generic-ml-cache-bootstrap 0.29.0__py3-none-any.whl

generic_ml_cache_bootstrap/discovery/client_discover.py

@@ -0,0 +1,274 @@
+# SPDX-FileCopyrightText: 2026 Daniel Slobozian
+# SPDX-License-Identifier: Apache-2.0
+"""Client discovery: report which configured clients are present and runnable.
+
+This is **read-only and advisory**. Discovery never chooses a client, never
+restricts which model may run, and never gates a call -- it only reports what it
+found on this machine. The run is always the validator.
+
+It is the detection half of "detection, not selection": the cache can tell a
+caller *what is here*; deciding *what to use* stays with the caller.
+"""
+
+from __future__ import annotations
+
+import subprocess
+import time
+
+from generic_ml_cache_core.application.domain.model.client_status import (
+    ClientStatus as ClientStatus,
+)
+from generic_ml_cache_core.application.domain.model.execution.execution_kind import ExecutionKind
+from generic_ml_cache_core.application.domain.model.model_listing import (
+    ModelListing as ModelListing,
+)
+from generic_ml_cache_core.application.port.outbound.diagnostics_port import DiagnosticsPort
+from generic_ml_cache_core.application.port.outbound.local_client_port import LocalClientPort
+from generic_ml_cache_core.common.errors import ClientNotFound, UnknownClient
+
+from generic_ml_cache_bootstrap.discovery.composition import (
+    catalog_and_resolver_for,
+    registered_local_names,
+)
+
+_LIST_MODELS_EXIT = "list-models EXIT"
+
+
+def _resolve_local_client(name: str, whitelist: frozenset[str] | None = None) -> LocalClientPort:
+    """Resolve a local-managed client adapter by client name, via the catalog +
+    resolver. Raises :class:`UnknownClient` if no local adapter serves ``name``."""
+    catalog, resolver = catalog_and_resolver_for(whitelist)
+    descriptors = list(catalog.find_by_client_name(name))
+    if not descriptors:
+        raise UnknownClient(f"unknown adapter {name!r}")
+    local = [d for d in descriptors if d.supports_mode(ExecutionKind.LOCAL_MANAGED)]
+    if not local:
+        raise UnknownClient(f"not a local managed adapter: {name!r}")
+    return resolver.resolve_local_client(local[0].adapter_id)
+
+
+def _probe_version(
+    argv: list[str], timeout: float, diag: DiagnosticsPort | None = None
+) -> tuple[str | None, str | None]:
+    _t = time.perf_counter()
+    if diag:
+        diag.debug("probe-version ENTER", argv0=argv[0] if argv else "")
+    try:
+        proc = subprocess.run(argv, capture_output=True, text=True, timeout=timeout)
+    except Exception as exc:  # noqa: BLE001 - any launch failure just means "unknown"
+        if diag:
+            diag.debug(
+                "probe-version FAILED — treating as unknown",
+                exc=exc,
+                duration_ms=round((time.perf_counter() - _t) * 1000, 1),
+            )
+        return None, f"version check failed: {exc}"
+    out = (proc.stdout or "").strip() or (proc.stderr or "").strip()
+    first = out.splitlines()[0].strip() if out else ""
+    version = first or None
+    detail = None if first else "no version output"
+    if diag:
+        diag.debug(
+            "probe-version EXIT",
+            version=version,
+            duration_ms=round((time.perf_counter() - _t) * 1000, 1),
+        )
+    return version, detail
+
+
+def probe(
+    name: str,
+    executable: str | None = None,
+    timeout: float = 10.0,
+    diag: DiagnosticsPort | None = None,
+) -> ClientStatus:
+    """Probe one registered client: is its executable present, and what version?
+
+    Never raises for an absent client -- absence is reported in the result.
+    """
+    _t = time.perf_counter()
+    if diag:
+        diag.debug("probe ENTER", name=name)
+    adapter = _resolve_local_client(name)
+    try:
+        exe = adapter.resolve_executable(executable)
+    except ClientNotFound as exc:
+        result = ClientStatus(name=name, present=False, detail=str(exc))
+        if diag:
+            diag.debug(
+                "probe EXIT",
+                name=name,
+                present=False,
+                duration_ms=round((time.perf_counter() - _t) * 1000, 1),
+            )
+        return result
+    version, detail = _probe_version(adapter.version_argv(exe), timeout, diag=diag)
+    result = ClientStatus(name=name, present=True, executable=exe, version=version, detail=detail)
+    if diag:
+        diag.debug(
+            "probe EXIT",
+            name=name,
+            present=True,
+            version=version,
+            duration_ms=round((time.perf_counter() - _t) * 1000, 1),
+        )
+    return result
+
+
+def probe_all(
+    timeout: float = 10.0,
+    executables: dict[str, str] | None = None,
+    whitelist: frozenset[str] | None = None,
+    diag: DiagnosticsPort | None = None,
+) -> list[ClientStatus]:
+    """Probe every registered client, in name order.
+
+    ``executables`` optionally maps a client name to the executable to probe
+    (e.g. from the ``[executables]`` config); a client absent from the mapping
+    falls back to its adapter's own ``PATH`` lookup.
+    ``whitelist`` opts third-party plugins into loading (by entry-point name); the bundled adapters always load.
+    """
+    _t = time.perf_counter()
+    if diag:
+        diag.debug("probe-all ENTER")
+    exe = executables or {}
+    results = [
+        probe(name, executable=exe.get(name), timeout=timeout, diag=diag)
+        for name in registered_local_names(whitelist)
+    ]
+    if diag:
+        diag.debug(
+            "probe-all EXIT",
+            count=len(results),
+            duration_ms=round((time.perf_counter() - _t) * 1000, 1),
+        )
+    return results
+
+
+def list_models(  # noqa: C901
+    name: str,
+    executable: str | None = None,
+    timeout: float = 30.0,
+    whitelist: frozenset[str] | None = None,
+    diag: DiagnosticsPort | None = None,
+) -> ModelListing:
+    """List one client's models by relaying its own listing command.
+
+    Never raises for an absent client or a client that cannot enumerate; both
+    are reported in the result. A relayed list reflects what the *authenticated*
+    client can reach, which is why it is preferred over any static catalog.
+    """
+    _t = time.perf_counter()
+    if diag:
+        diag.debug("list-models ENTER", name=name)
+    adapter = _resolve_local_client(name, whitelist)
+    try:
+        exe = adapter.resolve_executable(executable)
+    except ClientNotFound as exc:
+        result = ModelListing(name=name, present=False, supported=False, reason=str(exc))
+        if diag:
+            diag.debug(
+                _LIST_MODELS_EXIT,
+                name=name,
+                present=False,
+                duration_ms=round((time.perf_counter() - _t) * 1000, 1),
+            )
+        return result
+
+    argv = adapter.models_argv(exe)
+    if argv is None:
+        result = ModelListing(
+            name=name,
+            present=True,
+            supported=False,
+            reason="this client has no model-listing command",
+        )
+        if diag:
+            diag.debug(
+                _LIST_MODELS_EXIT,
+                name=name,
+                supported=False,
+                duration_ms=round((time.perf_counter() - _t) * 1000, 1),
+            )
+        return result
+
+    try:
+        proc = subprocess.run(argv, capture_output=True, text=True, timeout=timeout)
+    except Exception as exc:  # noqa: BLE001 - any launch failure is just "couldn't list"
+        if diag:
+            diag.debug(
+                "list-models launch failed",
+                name=name,
+                exc=exc,
+                duration_ms=round((time.perf_counter() - _t) * 1000, 1),
+            )
+        result = ModelListing(
+            name=name, present=True, supported=True, reason=f"model listing failed: {exc}"
+        )
+        if diag:
+            diag.debug(
+                _LIST_MODELS_EXIT,
+                name=name,
+                duration_ms=round((time.perf_counter() - _t) * 1000, 1),
+            )
+        return result
+
+    if proc.returncode != 0:
+        err = (proc.stderr or proc.stdout or "").strip().splitlines()
+        detail = err[0].strip() if err else f"exit {proc.returncode}"
+        result = ModelListing(
+            name=name,
+            present=True,
+            supported=True,
+            reason=f"client exited {proc.returncode}: {detail}",
+        )
+        if diag:
+            diag.debug(
+                _LIST_MODELS_EXIT,
+                name=name,
+                returncode=proc.returncode,
+                duration_ms=round((time.perf_counter() - _t) * 1000, 1),
+            )
+        return result
+
+    result = ModelListing(
+        name=name, present=True, supported=True, models=adapter.parse_model_list(proc.stdout)
+    )
+    if diag:
+        diag.debug(
+            "list-models EXIT",
+            name=name,
+            model_count=len(result.models) if result.models else 0,
+            duration_ms=round((time.perf_counter() - _t) * 1000, 1),
+        )
+    return result
+
+
+def list_models_all(
+    timeout: float = 30.0,
+    executables: dict[str, str] | None = None,
+    whitelist: frozenset[str] | None = None,
+    diag: DiagnosticsPort | None = None,
+) -> list[ModelListing]:
+    """List models for every registered client, in name order.
+
+    ``executables`` optionally maps a client name to the executable to use
+    (e.g. from the ``[executables]`` config); a client absent from the mapping
+    falls back to its adapter's own ``PATH`` lookup.
+    ``whitelist`` opts third-party plugins into loading (by entry-point name); the bundled adapters always load.
+    """
+    _t = time.perf_counter()
+    if diag:
+        diag.debug("list-models-all ENTER")
+    exe = executables or {}
+    results = [
+        list_models(name, executable=exe.get(name), timeout=timeout, whitelist=whitelist, diag=diag)
+        for name in registered_local_names(whitelist)
+    ]
+    if diag:
+        diag.debug(
+            "list-models-all EXIT",
+            count=len(results),
+            duration_ms=round((time.perf_counter() - _t) * 1000, 1),
+        )
+    return results

generic_ml_cache_bootstrap/discovery/composite_adapter_catalog.py

@@ -0,0 +1,38 @@
+# SPDX-FileCopyrightText: 2026 Daniel Slobozian
+# SPDX-License-Identifier: Apache-2.0
+"""CompositeAdapterCatalog — merge several catalogs into one view.
+
+Used by composition to present entry-point adapters and in-process registered
+adapters (e.g. test fakes) as a single universe. On an ``adapter_id`` collision
+the first catalog wins.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Iterable, Sequence
+
+from generic_ml_cache_core.application.domain.model.catalog.adapter_descriptor import (
+    AdapterDescriptor,
+)
+from generic_ml_cache_core.application.domain.model.execution.execution_kind import ExecutionKind
+from generic_ml_cache_core.application.port.outbound.adapter_catalog_port import AdapterCatalogPort
+
+
+class CompositeAdapterCatalog(AdapterCatalogPort):
+    """An AdapterCatalogPort that unions several catalogs."""
+
+    def __init__(self, catalogs: Iterable[AdapterCatalogPort]) -> None:
+        self._catalogs: list[AdapterCatalogPort] = list(catalogs)
+
+    def list_adapters(self) -> Sequence[AdapterDescriptor]:
+        merged: dict[str, AdapterDescriptor] = {}
+        for catalog in self._catalogs:
+            for descriptor in catalog.list_adapters():
+                merged.setdefault(descriptor.adapter_id, descriptor)
+        return list(merged.values())
+
+    def find_by_client_name(self, client_name: str) -> Sequence[AdapterDescriptor]:
+        return [d for d in self.list_adapters() if d.client_name == client_name]
+
+    def supports(self, client_name: str, mode: ExecutionKind) -> bool:
+        return any(catalog.supports(client_name, mode) for catalog in self._catalogs)

generic_ml_cache_bootstrap/discovery/composite_adapter_resolver.py

@@ -0,0 +1,51 @@
+# SPDX-FileCopyrightText: 2026 Daniel Slobozian
+# SPDX-License-Identifier: Apache-2.0
+"""CompositeAdapterResolver — try several resolvers in order.
+
+The resolver counterpart to CompositeAdapterCatalog: composition merges the
+entry-point resolver with the in-process registry resolver so a registered fake
+and an installed adapter resolve through one object. The first resolver that
+knows the id wins.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Iterable
+
+from generic_ml_cache_core.application.port.outbound.adapter_resolver_port import (
+    AdapterResolverPort,
+)
+from generic_ml_cache_core.application.port.outbound.local_client_port import LocalClientPort
+from generic_ml_cache_core.application.port.outbound.ml_runner_port import MlRunnerPort
+from generic_ml_cache_core.common.errors import UnknownClient
+
+
+class CompositeAdapterResolver(AdapterResolverPort):
+    """An AdapterResolverPort that delegates to the first resolver that succeeds."""
+
+    def __init__(self, resolvers: Iterable[AdapterResolverPort]) -> None:
+        self._resolvers: list[AdapterResolverPort] = list(resolvers)
+
+    def resolve_local_client(
+        self,
+        adapter_id: str,
+        executable_override: str | None = None,
+        timeout: float | None = None,
+        stream_path: str | None = None,
+    ) -> LocalClientPort:
+        for resolver in self._resolvers:
+            try:
+                return resolver.resolve_local_client(
+                    adapter_id, executable_override, timeout, stream_path
+                )
+            except UnknownClient:
+                continue
+        raise UnknownClient(f"no resolver for id {adapter_id!r}")
+
+    def resolve_runner(self, adapter_id: str) -> MlRunnerPort:
+        for resolver in self._resolvers:
+            try:
+                return resolver.resolve_runner(adapter_id)
+            except UnknownClient:
+                continue
+        raise UnknownClient(f"no resolver for id {adapter_id!r}")

generic_ml_cache_bootstrap/discovery/composition.py

@@ -0,0 +1,148 @@
+# SPDX-FileCopyrightText: 2026 Daniel Slobozian
+# SPDX-License-Identifier: Apache-2.0
+"""Default adapter-catalog composition, shared by the CLI and daemon drivers.
+
+The recommended default wiring: entry-point adapters merged with any in-process
+registered adapters, as a live catalog and resolver. Drivers opt into this (they
+could compose differently) and add deployment policy such as a whitelist on top.
+"""
+
+from __future__ import annotations
+
+from generic_ml_cache_core.application.domain.model.catalog.adapter_boundary import AdapterBoundary
+from generic_ml_cache_core.application.domain.model.execution.execution_kind import ExecutionKind
+from generic_ml_cache_core.application.port.outbound.adapter_catalog_port import AdapterCatalogPort
+from generic_ml_cache_core.application.port.outbound.adapter_resolver_port import (
+    AdapterResolverPort,
+)
+from generic_ml_cache_core.common.errors import UnknownClient
+
+from generic_ml_cache_bootstrap.discovery.composite_adapter_catalog import CompositeAdapterCatalog
+from generic_ml_cache_bootstrap.discovery.composite_adapter_resolver import CompositeAdapterResolver
+from generic_ml_cache_bootstrap.discovery.entrypoint_adapter_catalog import EntryPointAdapterCatalog
+from generic_ml_cache_bootstrap.discovery.entrypoint_adapter_resolver import (
+    EntryPointAdapterResolver,
+)
+from generic_ml_cache_bootstrap.discovery.in_memory_adapter_registry import default_registry
+
+_PRIMARY_MODE = {
+    AdapterBoundary.LOCAL_CLI: ExecutionKind.LOCAL_MANAGED,
+    AdapterBoundary.API: ExecutionKind.API,
+}
+
+_entrypoint_catalog: EntryPointAdapterCatalog | None = None
+_catalog: CompositeAdapterCatalog | None = None
+_resolver: CompositeAdapterResolver | None = None
+
+
+def _entrypoint() -> EntryPointAdapterCatalog:
+    global _entrypoint_catalog
+    if _entrypoint_catalog is None:
+        _entrypoint_catalog = EntryPointAdapterCatalog()
+    return _entrypoint_catalog
+
+
+def default_catalog() -> AdapterCatalogPort:
+    """Entry-point adapters merged with the in-process registry (a live view)."""
+    global _catalog
+    if _catalog is None:
+        _catalog = CompositeAdapterCatalog([_entrypoint(), default_registry()])
+    return _catalog
+
+
+def default_resolver() -> AdapterResolverPort:
+    """Resolve an adapter id from the DEFAULT (trusted-only) catalog's vetted classes
+    or the in-process registry. Bound to the same entry-point catalog as
+    :func:`default_catalog`, so it constructs only adapters that catalog gated in
+    (X15) — never by re-loading an ungated plugin."""
+    global _resolver
+    if _resolver is None:
+        _resolver = CompositeAdapterResolver(
+            [EntryPointAdapterResolver(_entrypoint()), default_registry()]
+        )
+    return _resolver
+
+
+def catalog_and_resolver_for(
+    whitelist: frozenset[str] | None = None,
+) -> tuple[AdapterCatalogPort, AdapterResolverPort]:
+    """A catalog and a resolver that SHARE one gated entry-point catalog, so the
+    resolver constructs exactly the adapters the catalog vetted — one trust gate, one
+    place (X15). Use this whenever a caller both lists and resolves under the same
+    ``whitelist``, so listing and resolution can never diverge."""
+    if whitelist is None:
+        return default_catalog(), default_resolver()
+    entrypoint = EntryPointAdapterCatalog(whitelist=whitelist)
+    registry = default_registry()
+    return (
+        CompositeAdapterCatalog([entrypoint, registry]),
+        CompositeAdapterResolver([EntryPointAdapterResolver(entrypoint), registry]),
+    )
+
+
+def catalog_for(whitelist: frozenset[str] | None = None) -> AdapterCatalogPort:
+    """The default catalog.
+
+    ``whitelist`` opts third-party plugins (by entry-point name) into loading;
+    the bundled adapters always load. With no whitelist, only the trusted bundled
+    adapters plus any in-process registrations are visible — the safe default
+    (a package installed for another reason never silently becomes a client).
+    """
+    if whitelist is None:
+        return default_catalog()
+    entrypoint = EntryPointAdapterCatalog(whitelist=whitelist)
+    return CompositeAdapterCatalog([entrypoint, default_registry()])
+
+
+def _unknown_adapter(name: str, catalog: AdapterCatalogPort) -> UnknownClient:
+    known = ", ".join(sorted({d.client_name for d in catalog.list_adapters()})) or "(none)"
+    return UnknownClient(f"unknown adapter {name!r}; available: {known}")
+
+
+def get_adapter(name: str, whitelist: frozenset[str] | None = None) -> object:
+    """Resolve a constructed adapter by client name (a local client or an API
+    runner). A convenience over the catalog + resolver; raises :class:`UnknownClient`
+    if the client is absent. Lives here, in infrastructure — never in core."""
+    catalog, resolver = catalog_and_resolver_for(whitelist)
+    descriptors = catalog.find_by_client_name(name)
+    if not descriptors:
+        raise _unknown_adapter(name, catalog)
+    descriptor = descriptors[0]
+    if descriptor.boundary is AdapterBoundary.API:
+        return resolver.resolve_runner(descriptor.adapter_id)
+    return resolver.resolve_local_client(descriptor.adapter_id)
+
+
+def execution_kind_for(client: str, whitelist: frozenset[str] | None = None) -> ExecutionKind:
+    """The primary execution kind for a client (LOCAL_MANAGED for a CLI, API for a
+    provider). Raises :class:`UnknownClient` if the client is absent."""
+    catalog = catalog_for(whitelist)
+    descriptors = catalog.find_by_client_name(client)
+    if not descriptors:
+        raise _unknown_adapter(client, catalog)
+    return _PRIMARY_MODE[descriptors[0].boundary]
+
+
+def registered_names(whitelist: frozenset[str] | None = None) -> list[str]:
+    return sorted({d.client_name for d in catalog_for(whitelist).list_adapters()})
+
+
+def registered_local_names(whitelist: frozenset[str] | None = None) -> list[str]:
+    return sorted(
+        {
+            d.client_name
+            for d in catalog_for(whitelist).list_adapters()
+            if d.supports_mode(ExecutionKind.LOCAL_MANAGED)
+        }
+    )
+
+
+def adapter_sources(whitelist: frozenset[str] | None = None) -> dict[str, str]:
+    """Map each entry-point client name to the distribution that provided it."""
+    sources = _entrypoint().sources()  # adapter_id -> "<package> <version>"
+    visible = {d.client_name for d in catalog_for(whitelist).list_adapters()}
+    out: dict[str, str] = {}
+    for descriptor in _entrypoint().list_adapters():
+        if descriptor.client_name in visible and descriptor.adapter_id in sources:
+            out[descriptor.client_name] = sources[descriptor.adapter_id]
+    return out

generic_ml_cache_bootstrap/discovery/entrypoint_adapter_catalog.py

@@ -0,0 +1,159 @@
+# SPDX-FileCopyrightText: 2026 Daniel Slobozian
+# SPDX-License-Identifier: Apache-2.0
+"""EntryPointAdapterCatalog — discover adapters from installed entry points.
+
+The default catalog: it scans the ``gmlcache.adapters`` entry-point group, loads
+each adapter class, and reads its ``descriptor()`` — without instantiating the
+adapter. A broken or incompatible entry point is warned and skipped; bad
+third-party code never crashes discovery. This is where the packaging-system
+dependency lives, out of core.
+"""
+
+from __future__ import annotations
+
+import importlib.metadata
+import warnings
+from collections.abc import Sequence
+from typing import cast
+
+from generic_ml_cache_core.application.domain.model.catalog.adapter_descriptor import (
+    AdapterDescriptor,
+)
+from generic_ml_cache_core.application.domain.model.execution.execution_kind import ExecutionKind
+from generic_ml_cache_core.application.port.outbound.adapter_catalog_port import AdapterCatalogPort
+
+from generic_ml_cache_bootstrap.discovery._entrypoints import (
+    ADAPTER_CONTRACT_VERSION,
+    ADAPTER_ENTRYPOINT_GROUP,
+    describe_source,
+    distribution_name,
+    iter_entry_points,
+)
+
+# Distributions whose plugins are trusted to load by default. The bundled
+# adapters ship here; any other distribution declaring a gmlcache.adapters
+# entry point is third-party and must be whitelisted by name to load (its module
+# code runs at ep.load(), so the gate is BEFORE the load — ambient authority).
+DEFAULT_TRUSTED_DISTRIBUTIONS = frozenset({"generic-ml-cache-adapters"})
+
+
+class EntryPointAdapterCatalog(AdapterCatalogPort):
+    """Catalog backed by the installed ``gmlcache.adapters`` entry points.
+
+    Trusted-distribution plugins always load. A third-party plugin loads only if
+    its entry-point name is in ``whitelist`` — otherwise it is never imported, so
+    a package installed for another reason cannot silently become a cache client.
+    """
+
+    def __init__(
+        self,
+        group: str = ADAPTER_ENTRYPOINT_GROUP,
+        *,
+        whitelist: frozenset[str] | None = None,
+        trusted_distributions: frozenset[str] = DEFAULT_TRUSTED_DISTRIBUTIONS,
+    ) -> None:
+        self._group = group
+        self._whitelist = whitelist
+        self._trusted = trusted_distributions
+        self._descriptors: list[AdapterDescriptor] | None = None
+        self._sources: dict[str, str] = {}
+        # The vetted adapter classes, keyed by adapter_id — populated during the same
+        # gated scan that builds the descriptors, so the resolver can construct ONLY
+        # what this catalog already trusted, never re-loading an ungated plugin (X15).
+        self._classes: dict[str, type] = {}
+
+    def _is_allowed_to_load(self, entry_point: importlib.metadata.EntryPoint) -> bool:
+        """Trust gate, evaluated BEFORE entry_point.load(): a trusted distribution
+        always loads; anything else only if its entry-point name is whitelisted."""
+        if distribution_name(entry_point) in self._trusted:
+            return True
+        return self._whitelist is not None and entry_point.name in self._whitelist
+
+    def _scan(self) -> list[AdapterDescriptor]:
+        descriptors: list[AdapterDescriptor] = []
+        for entry_point in iter_entry_points(self._group):
+            entry_point_name = entry_point.name
+            if not self._is_allowed_to_load(entry_point):
+                # Untrusted third-party, not whitelisted: never import it.
+                continue
+            try:
+                cls = entry_point.load()
+            except Exception as exc:  # noqa: BLE001 — broken plugin must not crash discovery
+                warnings.warn(
+                    f"gmlcache: could not load entry-point adapter {entry_point_name!r}: {exc}",
+                    stacklevel=2,
+                )
+                continue
+
+            declared = getattr(cls, "adapter_contract_version", None)
+            if declared is not None and declared != ADAPTER_CONTRACT_VERSION:
+                warnings.warn(
+                    f"gmlcache: entry-point adapter {entry_point_name!r} targets contract {declared!r} "
+                    f"but this core requires {ADAPTER_CONTRACT_VERSION!r}; skipping",
+                    stacklevel=2,
+                )
+                continue
+
+            describe = getattr(cls, "descriptor", None)
+            if not callable(describe):
+                warnings.warn(
+                    f"gmlcache: entry-point adapter {entry_point_name!r} has no descriptor(); skipping",
+                    stacklevel=2,
+                )
+                continue
+            try:
+                descriptor = cast(AdapterDescriptor, describe())
+            except Exception as exc:  # noqa: BLE001
+                warnings.warn(
+                    f"gmlcache: descriptor() failed for entry-point adapter {entry_point_name!r}: {exc}",
+                    stacklevel=2,
+                )
+                continue
+
+            if descriptor.adapter_id in self._classes:
+                # Two plugins claim the same adapter_id: ambiguous provenance. Reject
+                # deterministically rather than let iteration order pick a winner (X15)
+                # — a silent last-writer could let an untrusted plugin shadow a trusted
+                # one. Fail loud so the operator resolves the conflict.
+                raise ValueError(
+                    f"gmlcache: duplicate adapter_id {descriptor.adapter_id!r} — provided by both "
+                    f"{self._sources[descriptor.adapter_id]!r} and {describe_source(entry_point)!r}; "
+                    "uninstall one of the conflicting plugins"
+                )
+            descriptors.append(descriptor)
+            self._sources[descriptor.adapter_id] = describe_source(entry_point)
+            self._classes[descriptor.adapter_id] = cls
+        return descriptors
+
+    def resolve_class(self, adapter_id: str) -> type | None:
+        """The vetted class for ``adapter_id``, or None if this catalog does not trust
+        it. The resolver constructs from THIS — never by re-loading entry points — so
+        a plugin the catalog gated out is never imported at resolution time (X15)."""
+        self._ensure_loaded()
+        return self._classes.get(adapter_id)
+
+    def _ensure_loaded(self) -> list[AdapterDescriptor]:
+        if self._descriptors is None:
+            self._descriptors = self._scan()
+        return self._descriptors
+
+    def list_adapters(self) -> Sequence[AdapterDescriptor]:
+        return list(self._ensure_loaded())
+
+    def find_by_client_name(self, client_name: str) -> Sequence[AdapterDescriptor]:
+        return [
+            descriptor
+            for descriptor in self._ensure_loaded()
+            if descriptor.client_name == client_name
+        ]
+
+    def supports(self, client_name: str, mode: ExecutionKind) -> bool:
+        return any(
+            descriptor.client_name == client_name and descriptor.supports_mode(mode)
+            for descriptor in self._ensure_loaded()
+        )
+
+    def sources(self) -> dict[str, str]:
+        """Map each ``adapter_id`` to the distribution that provided it (for doctor)."""
+        self._ensure_loaded()
+        return dict(self._sources)