Merge branch 'bundles/docs' into bundles/review-fixes

# Conflicts:
#	BUNDLE_API.md

Author: erichare

BUNDLE_API.md

@@ -421,13 +421,24 @@ the deserialize half is covered by
   `installed > seed > lfx_bundles > dev > inline` -- **manifest always
   wins**, so a manifest-shipping `lfx-<provider>` shadows the same-named
   provider in a metapackage with the existing `bundle-shadowed` warning
-  (graduation requires no lockstep release).  New warning-only code
+  (graduation requires no lockstep release).  A metapackage provider whose
+  name is already claimed by an installed or seed source is **never
+  imported** -- all `@official` sources share the
+  `_lfx_ext.official.<bundle>.*` sys.modules namespace, so importing the
+  losing copy would overwrite the winner's live modules; the skipped copy
+  still surfaces the `bundle-shadowed` warning.  New warning-only code
   `bundle-discovery-malformed` added to `ERROR_CODES` (additive) for
   unresolvable declarations and invalid provider directory names; it never
   aborts startup.  Manifest-less bundles bypass the
   `version-constraint-unsatisfied` API-version gate by construction (no
   manifest to carry `lfx.compat`); install-time compatibility rides on the
-  metapackage's PEP 508 `lfx>=X,<Y` pin instead.
+  metapackage's PEP 508 `lfx>=X,<Y` pin instead.  Manifest-less records
+  register with `manifestless=True` (additive field on `LoadResult` /
+  `BundleRecord`) and are **not hot-reloadable**: the reload pipeline
+  refuses them with the new typed code `reload-manifestless-unsupported`
+  (additive in `ERROR_CODES`) instead of failing `manifest-not-found`;
+  pick up metapackage changes by upgrading the distribution and
+  restarting the process.
 - **`import_mod` promoted to a stable public home.**  The lazy-import helper
   that bundle packages call from their `__getattr__`-based `__init__.py`
   files moved from the internal `lfx.components._importing` to

src/lfx/src/lfx/extension/bundle_registry.py

@@ -98,6 +98,10 @@ class BundleRecord:
     components: tuple[LoadedComponent, ...] = ()
     distribution: str | None = None
     source_path: Path | None = None
+    # Provenance: True for manifest-less lfx.bundles metapackage providers.
+    # The reload pipeline refuses these with reload-manifestless-unsupported
+    # (no manifest exists for its load_extension stage to consume).
+    manifestless: bool = False
 
     @property
     def class_names(self) -> frozenset[str]:

src/lfx/src/lfx/extension/errors.py

@@ -97,6 +97,10 @@
         "reload-bundle-not-installed",
         "reload-bundle-name-mismatch",
         "reload-source-missing",
+        # Manifest-less lfx.bundles providers carry no manifest for the
+        # reload pipeline's load_extension stage; hot reload refuses them
+        # with this typed code instead of a misleading manifest-not-found.
+        "reload-manifestless-unsupported",
         # Post-swap hook failures: the registry swap committed but a
         # downstream side-effect (e.g. component cache rebuild) raised.
         # Surfaced on ReloadResult.warnings so the API caller knows the
@@ -307,6 +311,10 @@ def __bool__(self) -> bool:  # pragma: no cover - convenience
     "reload-source-missing": (
         "Reload source path {content!r} for bundle {location!r} does not exist or is not a directory."
     ),
+    "reload-manifestless-unsupported": (
+        "Bundle {content!r} comes from a manifest-less lfx.bundles metapackage and cannot be "
+        "hot-reloaded; upgrade the metapackage distribution and restart the process instead."
+    ),
     "reload-post-swap-hook-failed": (
         "Post-swap hook failed for bundle {content!r}; the bundle swap committed but a "
         "downstream side-effect (e.g. component cache rebuild) raised."

src/lfx/src/lfx/extension/loader/_bundles_root.py

@@ -52,7 +52,7 @@
 from lfx.extension.manifest import BUNDLE_NAME_RE
 
 if TYPE_CHECKING:
-    from collections.abc import Iterable
+    from collections.abc import Iterable, Mapping
     from importlib import metadata as importlib_metadata
 
 LFX_BUNDLES_ENTRY_POINT_GROUP = "lfx.bundles"
@@ -86,6 +86,7 @@ class _BundleRoot(NamedTuple):
 def load_lfx_bundles_extensions(
     *,
     entry_points: Iterable[importlib_metadata.EntryPoint] | None = None,
+    claimed_bundles: Mapping[str, tuple[str, str]] | None = None,
 ) -> list[LoadResult]:
     """Discover manifest-less ``lfx.bundles`` roots and load them at @official.
 
@@ -96,6 +97,18 @@ def load_lfx_bundles_extensions(
     subdirectories -- each valid subdirectory is one manifest-less bundle at
     the @official slot.
 
+    ``claimed_bundles`` maps bundle names already won by a higher-precedence
+    @official source (installed > seed) to ``(source_kind, source_path)``.
+    A provider directory whose name is claimed is **never imported** -- its
+    result carries a typed ``bundle-shadowed`` warning instead.  Skipping the
+    import (rather than letting :func:`_resolve_bundle_shadowing` drop the
+    components afterwards) matters because all @official sources share the
+    ``_lfx_ext.official.<bundle>.*`` sys.modules namespace: importing the
+    losing copy would overwrite the winner's live modules.  This is the
+    normal graduation state -- a manifest-shipping ``lfx-<provider>``
+    installed alongside an older metapackage that still contains the same
+    provider -- not an operator error.
+
     Returns one :class:`LoadResult` per discovered bundle, plus one sentinel
     :class:`LoadResult` carrying a ``bundle-discovery-malformed`` warning per
     declaration that could not be resolved.  Order is deterministic: entry
@@ -104,7 +117,7 @@ def load_lfx_bundles_extensions(
     even when no valid bundle followed.
     """
     roots, sentinels = _resolve_bundle_roots(entry_points)
-    return [*sentinels, *_load_bundle_roots(roots)]
+    return [*sentinels, *_load_bundle_roots(roots, claimed_bundles=claimed_bundles)]
 
 
 def _resolve_bundle_roots(
@@ -156,16 +169,23 @@ def _resolve_bundle_roots(
     return roots, sentinels
 
 
-def _load_bundle_roots(roots: Iterable[_BundleRoot]) -> list[LoadResult]:
+def _load_bundle_roots(
+    roots: Iterable[_BundleRoot],
+    *,
+    claimed_bundles: Mapping[str, tuple[str, str]] | None = None,
+) -> list[LoadResult]:
     """Folder-walk each resolved root, loading every valid subdirectory at @official.
 
     First-wins on duplicate bundle names across roots (the loser emits a typed
-    ``bundle-shadowed`` warning); subdirectories whose name is not a valid
-    bundle name emit ``bundle-discovery-malformed`` and are skipped.
-    Internal directories (dot-prefixed, underscore-prefixed, or in
-    :data:`SKIP_DIR_NAMES`) are skipped silently -- they are package
-    machinery, not providers.
+    ``bundle-shadowed`` warning); names in ``claimed_bundles`` (already won by
+    a higher-precedence installed/seed source) are skipped *without importing*
+    so the winner's ``_lfx_ext.official.<bundle>.*`` sys.modules entries are
+    never overwritten.  Subdirectories whose name is not a valid bundle name
+    emit ``bundle-discovery-malformed`` and are skipped.  Internal directories
+    (dot-prefixed, underscore-prefixed, or in :data:`SKIP_DIR_NAMES`) are
+    skipped silently -- they are package machinery, not providers.
     """
+    claimed = claimed_bundles or {}
     results: list[LoadResult] = []
     seen_names: dict[str, Path] = {}
     for root in roots:
@@ -206,7 +226,7 @@ def _load_bundle_roots(roots: Iterable[_BundleRoot]) -> list[LoadResult]:
                 results.append(result)
                 continue
 
-            result = LoadResult(slot=SLOT_OFFICIAL, source_path=child)
+            result = LoadResult(slot=SLOT_OFFICIAL, source_path=child, manifestless=True)
 
             if not BUNDLE_NAME_RE.match(name):
                 result.warnings.append(
@@ -220,6 +240,30 @@ def _load_bundle_roots(roots: Iterable[_BundleRoot]) -> list[LoadResult]:
                 results.append(result)
                 continue
 
+            if name in claimed:
+                winner_kind, winner_path = claimed[name]
+                result.bundle = name
+                result.warnings.append(
+                    ExtensionError(
+                        code="bundle-shadowed",
+                        message=(
+                            f"Manifest-less bundle {name!r} at {child} is shadowed by a "
+                            f"higher-precedence source at {winner_path} (source: {winner_kind}); "
+                            "the metapackage copy is not imported."
+                        ),
+                        location=str(child),
+                        content=name,
+                        hint=(
+                            "Discovery precedence is installed > seed > lfx_bundles > dev > inline. "
+                            "This is expected after a provider graduates to a standalone "
+                            "lfx-<provider> package; upgrade the metapackage to a version without "
+                            "this provider to silence the warning."
+                        ),
+                    )
+                )
+                results.append(result)
+                continue
+
             if name in seen_names:
                 result.bundle = name
                 result.warnings.append(

src/lfx/src/lfx/extension/loader/_types.py

@@ -137,6 +137,12 @@ class LoadResult:
     slot: Literal["official", "extra"] | None = None
     source_path: Path | None = None
     distribution: str | None = None
+    # True when the bundle came from a manifest-less ``lfx.bundles``
+    # metapackage root.  Provenance flag (not derivable from the other
+    # fields): the reload pipeline uses it to refuse hot reload with a
+    # typed ``reload-manifestless-unsupported`` instead of routing the
+    # record through load_extension and failing manifest-not-found.
+    manifestless: bool = False
 
     @property
     def ok(self) -> bool:

src/lfx/src/lfx/extension/reload.py

@@ -261,6 +261,34 @@ def reload_bundle(
     reload_id = uuid.uuid4().hex
     live = registry.get_bundle(bundle)
 
+    # Manifest-less lfx.bundles metapackage providers have no extension.json
+    # for the pipeline's load_extension stage; refuse with a typed code
+    # before resolving sources rather than failing later with a misleading
+    # manifest-not-found.  These records change only when the metapackage
+    # distribution is upgraded, which requires a process restart anyway.
+    if live is not None and live.manifestless:
+        return _failure(
+            bundle=bundle,
+            reload_id=reload_id,
+            errors=[
+                ExtensionError(
+                    code="reload-manifestless-unsupported",
+                    message=(
+                        f"Bundle {bundle!r} comes from a manifest-less lfx.bundles metapackage "
+                        "and cannot be hot-reloaded."
+                    ),
+                    location=str(live.source_path) if live.source_path else bundle,
+                    content=bundle,
+                    hint=(
+                        "Upgrade or reinstall the metapackage distribution and restart the "
+                        "server to pick up changes.  For a hot-reload development loop, use "
+                        "`lfx extension dev <path>` with a manifest-shipping bundle instead."
+                    ),
+                )
+            ],
+            previous=live,
+        )
+
     # Resolve effective source + slot from the live record when not given.
     effective_source = _resolve_source(source_path, live)
     effective_slot: Literal["official", "extra"] = slot or (live.slot if live else SLOT_OFFICIAL)

src/lfx/src/lfx/interface/components.py

@@ -812,6 +812,30 @@ def _emit_extension_diagnostics(results: list[LoadResult]) -> None:
 _DISCOVERY_PRECEDENCE: tuple[str, ...] = ("installed", "seed", "lfx_bundles", "dev", "inline")
 
 
+def _claimed_official_bundles(
+    extension_results: list[LoadResult],
+    seed_results: list[LoadResult],
+) -> dict[str, tuple[str, str]]:
+    """Map bundle names won by installed/seed sources to ``(kind, path)``.
+
+    Fed to :func:`load_lfx_bundles_extensions` so the manifest-less
+    metapackage tier skips *importing* providers that would lose shadow
+    resolution anyway -- the @official sources share one
+    ``_lfx_ext.official.<bundle>.*`` sys.modules namespace, and a
+    lower-precedence import would overwrite the winner's live modules.
+    Mirrors the winner-picking rule in :func:`_resolve_bundle_shadowing`:
+    only results that actually produced components claim a name, and the
+    first (highest-precedence) claimant wins.
+    """
+    claimed: dict[str, tuple[str, str]] = {}
+    for kind, results in (("installed", extension_results), ("seed", seed_results)):
+        for result in results:
+            if not result.bundle or not result.components or result.bundle in claimed:
+                continue
+            claimed[result.bundle] = (kind, str(result.source_path) if result.source_path else "<unknown>")
+    return claimed
+
+
 def _resolve_bundle_shadowing(
     *,
     extension_results: list[LoadResult],
@@ -972,7 +996,18 @@ async def import_extension_components(
     # subdirectories are bundles, registered at @official with no manifest.
     # Loaded here so they enter the same shadow-resolution + registry +
     # palette pathway; a no-op when no distribution declares the group.
-    lfx_bundles_results = load_lfx_bundles_extensions()
+    #
+    # ``claimed_bundles`` carries the names already won by the two
+    # higher-precedence sources so the metapackage loader never *imports* a
+    # losing copy: all @official sources share the
+    # ``_lfx_ext.official.<bundle>.*`` sys.modules namespace, so importing a
+    # shadowed provider would overwrite the winner's live modules even though
+    # _resolve_bundle_shadowing later drops its components.  This collision is
+    # the expected post-graduation state (standalone lfx-<provider> installed
+    # alongside an older metapackage), not a misconfiguration.
+    lfx_bundles_results = load_lfx_bundles_extensions(
+        claimed_bundles=_claimed_official_bundles(extension_results, seed_results)
+    )
     # Dev extensions registered via ``lfx extension dev`` ship the same v0
     # manifest contract as installed extensions; load them through the
     # @official-slot pathway so they enter the BundleRegistry, expose the
@@ -1049,6 +1084,7 @@ async def import_extension_components(
             components=tuple(result.components),
             distribution=result.distribution,
             source_path=result.source_path,
+            manifestless=result.manifestless,
         )
         registry.install_bundle(record)
 

src/lfx/tests/unit/extension/loader/test_load_lfx_bundles.py

@@ -17,6 +17,7 @@
 from __future__ import annotations
 
 import importlib
+import sys
 from pathlib import Path
 
 from lfx.extension import SLOT_OFFICIAL, LoadedComponent, LoadResult, load_lfx_bundles_extensions
@@ -26,7 +27,7 @@
     _load_bundle_roots,
     _resolve_bundle_roots,
 )
-from lfx.interface.components import _resolve_bundle_shadowing
+from lfx.interface.components import _claimed_official_bundles, _resolve_bundle_shadowing
 
 from .conftest import component_source
 
@@ -183,6 +184,71 @@ def test_duplicate_provider_across_roots_first_wins(tmp_path: Path) -> None:
     assert not shadowed[0].components
 
 
+def test_claimed_bundle_name_is_not_imported(tmp_path: Path) -> None:
+    """A name won by an installed/seed source is skipped *without importing*.
+
+    All @official sources share the ``_lfx_ext.official.<bundle>.*``
+    sys.modules namespace; importing the metapackage's losing copy would
+    overwrite the winner's live modules even though shadow resolution drops
+    the loser's components afterwards.  This is the expected post-graduation
+    state (standalone ``lfx-<provider>`` next to an older metapackage).
+    """
+    root = _make_bundles_root(tmp_path, "claimedprov", "freeprov")
+
+    results = _load_bundle_roots(
+        [_BundleRoot(root, "lfx-bundles", "1.0.0")],
+        claimed_bundles={"claimedprov": ("installed", "/site-packages/lfx_claimedprov")},
+    )
+    by_bundle = {r.bundle: r for r in results if r.bundle}
+
+    assert set(by_bundle) == {"claimedprov", "freeprov"}
+    claimed = by_bundle["claimedprov"]
+    assert not claimed.components
+    assert claimed.ok  # warning-only: never aborts startup
+    assert [w.code for w in claimed.warnings] == ["bundle-shadowed"]
+    assert "installed" in claimed.warnings[0].message
+    # The decisive property: nothing was imported for the claimed name, so
+    # the winner's live modules cannot have been overwritten.
+    assert not [k for k in sys.modules if k.startswith("_lfx_ext.official.claimedprov")]
+    # The unclaimed sibling in the same root still loads normally.
+    assert by_bundle["freeprov"].components
+
+
+def test_provider_results_are_marked_manifestless(tmp_path: Path) -> None:
+    """Provider results carry the provenance flag the reload pipeline keys on."""
+    root = _make_bundles_root(tmp_path, "flagged")
+
+    results = _load_bundle_roots([_BundleRoot(root, "lfx-bundles", "1.0.0")])
+
+    assert results
+    assert all(r.manifestless for r in results if r.bundle)
+
+
+def test_claimed_official_bundles_first_wins_and_requires_components(tmp_path: Path) -> None:
+    """The claim map mirrors the resolver's winner rule.
+
+    Only results that produced components claim a name, and the
+    highest-precedence claimant (installed before seed) wins.
+    """
+    installed_alpha = LoadResult(
+        slot=SLOT_OFFICIAL,
+        bundle="alpha",
+        source_path=tmp_path / "inst" / "alpha",
+        components=[_component("alpha")],
+    )
+    seed_alpha = LoadResult(
+        slot=SLOT_OFFICIAL,
+        bundle="alpha",
+        source_path=tmp_path / "seed" / "alpha",
+        components=[_component("alpha")],
+    )
+    seed_empty = LoadResult(slot=SLOT_OFFICIAL, bundle="empty", source_path=tmp_path / "seed" / "empty")
+
+    claimed = _claimed_official_bundles([installed_alpha], [seed_alpha, seed_empty])
+
+    assert claimed == {"alpha": ("installed", str(tmp_path / "inst" / "alpha"))}
+
+
 # ---------------------------------------------------------------------------
 # Entry-point resolution + malformed declarations
 # ---------------------------------------------------------------------------

src/lfx/tests/unit/extension/test_errors.py

@@ -103,6 +103,7 @@ def _err(code: str, **kw: object) -> ExtensionError:
     "reload-bundle-not-installed": "error[reload-bundle-not-installed]: Cannot reload bundle 'content': it is not registered. Install the extension first or pass an explicit source path.",  # noqa: E501
     "reload-bundle-name-mismatch": "error[reload-bundle-name-mismatch]: Reload source at loc declares bundle name 'content', which does not match the registered bundle being reloaded.",  # noqa: E501
     "reload-source-missing": "error[reload-source-missing]: Reload source path 'content' for bundle 'loc' does not exist or is not a directory.",  # noqa: E501
+    "reload-manifestless-unsupported": "error[reload-manifestless-unsupported]: Bundle 'content' comes from a manifest-less lfx.bundles metapackage and cannot be hot-reloaded; upgrade the metapackage distribution and restart the process instead.",  # noqa: E501
     "reload-post-swap-hook-failed": "error[reload-post-swap-hook-failed]: Post-swap hook failed for bundle 'content'; the bundle swap committed but a downstream side-effect (e.g. component cache rebuild) raised.",  # noqa: E501
     "reload-class-retag-failed": "error[reload-class-retag-failed]: Could not retag content.__module__ after reload at loc: msg",  # noqa: E501
     "reload-transport-error": "error[reload-transport-error]: Could not reach the reload endpoint at loc: msg",