@ahmed-g-gad/apothem 0.1.1

package/src/apothem/lib/frontmatter.py

@@ -0,0 +1,101 @@
+# SPDX-License-Identifier: MIT
+
+"""YAML frontmatter field probing and value extraction for ecosystem files.
+
+Provides three layers of inspection:
+
+* :func:`extract_frontmatter` — return the raw YAML block.
+* :func:`field_value` — return the value of a single declared field as a string,
+  or ``None`` when the field is absent.
+* :func:`has_field` / :func:`has_all_fields` — boolean presence checks.
+
+The probe is intentionally regex-based rather than a full YAML parser so that
+the validator surface has zero third-party dependencies and remains
+import-time cheap. It supports the small subset of YAML actually used in
+ecosystem frontmatter: scalar values (quoted or unquoted) on a single line.
+"""
+
+from __future__ import annotations
+
+import re
+from pathlib import Path
+from typing import Final
+
+_FRONTMATTER_BLOCK: Final[re.Pattern[str]] = re.compile(
+    r"\A---\s*\n(.*?)\n---", re.DOTALL
+)
+_LEADING_HTML_COMMENT: Final[re.Pattern[str]] = re.compile(
+    r"\A\s*<!--.*?-->\s*", re.DOTALL
+)
+
+
+def extract_frontmatter(path: Path) -> str | None:
+    """Return the raw YAML block at the top of ``path``, or ``None``.
+
+    A leading HTML-comment block (the canonical authorship banner injected
+    ecosystem-wide above the YAML frontmatter on every Markdown file) is
+    skipped before matching the frontmatter delimiter so the probe sees
+    the YAML block at the correct anchor.
+
+    Args:
+        path: File to read.
+
+    Returns:
+        The block content between the opening and closing ``---`` lines, or
+        ``None`` when the file is unreadable or has no frontmatter.
+    """
+    try:
+        text = path.read_text(encoding="utf-8", errors="replace")
+    except OSError:
+        return None
+    text = _LEADING_HTML_COMMENT.sub("", text, count=1)
+    match = _FRONTMATTER_BLOCK.match(text)
+    return match.group(1) if match else None
+
+
+def field_value(path: Path, field_name: str) -> str | None:
+    """Return the unquoted scalar value of ``field_name`` from ``path``.
+
+    Recognizes single-line ``key: "value"`` and ``key: value`` declarations.
+    Multi-line YAML constructs (block scalars, lists, mappings) return the
+    raw matched suffix and should be treated as opaque by callers.
+
+    Args:
+        path: File to read.
+        field_name: YAML key to look up.
+
+    Returns:
+        Stripped, dequoted value, or ``None`` when the field is absent.
+    """
+    block = extract_frontmatter(path)
+    if block is None:
+        return None
+    pattern = re.compile(
+        rf"^{re.escape(field_name)}\s*:\s*(.*?)\s*$",
+        re.MULTILINE,
+    )
+    match = pattern.search(block)
+    if match is None:
+        return None
+    raw = match.group(1).strip()
+    if (raw.startswith('"') and raw.endswith('"')) or (
+        raw.startswith("'") and raw.endswith("'")
+    ):
+        # Dequote by stripping the outer quotes only. Backslash escape
+        # sequences inside a double-quoted scalar (``"a \"b\""``) are NOT
+        # decoded — the inner text is returned verbatim. Apothem's own
+        # frontmatter values are plain prose with no escaped quotes, so this
+        # is sufficient in practice; a value needing escape decoding must be
+        # parsed with a full YAML loader by the caller.
+        return raw[1:-1]
+    return raw
+
+
+def has_field(path: Path, field_name: str) -> bool:
+    """Return True when frontmatter in ``path`` declares ``field_name:``."""
+    return field_value(path, field_name) is not None
+
+
+def has_all_fields(path: Path, field_names: list[str]) -> bool:
+    """Return True when every field in ``field_names`` is declared."""
+    return all(has_field(path, name) for name in field_names)

package/src/apothem/lib/harness_materializer.py

@@ -0,0 +1,213 @@
+# SPDX-License-Identifier: MIT
+
+"""Shared building blocks for per-harness materializers.
+
+These helpers cover profile-to-Markdown field extraction and the legacy
+managed-YAML body shape retained for compatibility tests. Current harness
+materializers that target strict vendor schemas should emit only documented
+keys instead of using the generic managed body.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Mapping
+from dataclasses import dataclass, field
+from typing import Any, Final
+
+import yaml
+
+from apothem.lib.profile import DEFAULT_LANGUAGE, DEFAULT_STYLE, coerce_profile
+
+# Canonical sentinel pair delimiting the Apothem-managed block inside an
+# operator-owned Markdown instruction anchor (AGENTS.md, GEMINI.md, QWEN.md,
+# copilot-instructions.md, and the project-scope rule files). The pair is the
+# stable, documented merge boundary each harness dossier references: Apothem
+# owns only the bytes between the sentinels; operator prose outside is
+# preserved verbatim. Changing these strings would orphan every previously
+# installed managed block, so they are a frozen contract.
+APOTHEM_BLOCK_BEGIN: Final[str] = "<!-- BEGIN APOTHEM MANAGED BLOCK -->"
+APOTHEM_BLOCK_END: Final[str] = "<!-- END APOTHEM MANAGED BLOCK -->"
+
+
+def wrap_managed_block(body: str) -> str:
+    """Return *body* wrapped in the canonical Apothem managed-block sentinels.
+
+    The wrapped form is the unit Apothem writes into an operator-owned
+    Markdown anchor. The body is stripped of surrounding blank lines so the
+    block is byte-stable across re-installs (idempotency depends on the
+    wrapped form being identical for identical bodies).
+    """
+    return f"{APOTHEM_BLOCK_BEGIN}\n{body.strip()}\n{APOTHEM_BLOCK_END}\n"
+
+
+def extract_managed_block(text: str) -> str | None:
+    """Return the managed-block region found in *text*, or ``None``.
+
+    A well-formed block (begin sentinel followed by an end sentinel) returns
+    both sentinels and the body between them, exactly as in *text*. An *orphan*
+    begin sentinel with no following end sentinel (a truncated or
+    operator-mangled block) returns the degenerate region from the begin
+    sentinel to end-of-text, so :func:`merge_managed_block` REPLACES it in place
+    rather than appending a second block. Appending on an orphan would leave a
+    two-begin file whose next merge swallows the operator text trapped between
+    the orphan begin and the appended block — so the orphan is reclaimed on the
+    first merge instead (operator prose *before* the orphan begin is always
+    preserved; the caller writes a backup of the prior file). ``None`` only when
+    no begin sentinel is present at all.
+    """
+    begin = text.find(APOTHEM_BLOCK_BEGIN)
+    if begin == -1:
+        return None
+    end = text.find(APOTHEM_BLOCK_END, begin + len(APOTHEM_BLOCK_BEGIN))
+    if end == -1:
+        return text[begin:]
+    return text[begin : end + len(APOTHEM_BLOCK_END)]
+
+
+def merge_managed_block(existing: str, body: str) -> str:
+    """Merge an Apothem managed block carrying *body* into *existing* text.
+
+    Three cases, all preserving operator prose:
+
+    - *existing* is empty — return the wrapped block alone.
+    - *existing* already carries a managed block — replace that block in
+      place, leaving operator prose before and after it untouched.
+    - *existing* carries no managed block — append the wrapped block after
+      the operator's content, separated by one blank line.
+
+    The merge is idempotent: re-merging the same *body* into text that
+    already carries the resulting block returns byte-identical output.
+    """
+    wrapped = wrap_managed_block(body)
+    if not existing.strip():
+        return wrapped
+    current_block = extract_managed_block(existing)
+    if current_block is not None:
+        return existing.replace(current_block, wrapped.rstrip("\n"), 1)
+    separator = "" if existing.endswith("\n") else "\n"
+    return f"{existing}{separator}\n{wrapped}"
+
+
+def remove_managed_block(existing: str) -> str:
+    """Return *existing* with the Apothem managed block surgically removed.
+
+    The inverse of :func:`merge_managed_block`: strips the managed block (and the
+    blank-line separator the merge inserted around it) while preserving operator
+    prose before and after it. When the remainder is whitespace-only — i.e. the
+    anchor was Apothem-only — returns the empty string so the caller can delete
+    the now-empty file rather than leaving a stub. Returns *existing* unchanged
+    when it carries no managed block (including a degenerate orphan-begin block,
+    which :func:`extract_managed_block` reclaims).
+
+    Round-trips byte-for-byte for the canonical case: an operator prose block
+    ending in a single newline, merged-then-removed, returns the original.
+    """
+    block = extract_managed_block(existing)
+    if block is None:
+        return existing
+    index = existing.find(block)
+    before = existing[:index].rstrip("\n")
+    after = existing[index + len(block) :].lstrip("\n")
+    if before and after:
+        remainder = f"{before}\n\n{after}"
+    elif before:
+        remainder = f"{before}\n"
+    else:
+        remainder = after
+    return "" if not remainder.strip() else remainder
+
+
+@dataclass(frozen=True)
+class MarkdownProfileFields:
+    """The profile fields the Markdown-output adapters render into their body.
+
+    Carries the full identity (name/role/email/website/github), both
+    preference scalars (language/style), the seriousness band, the rules
+    list (+ its pre-rendered block), and the opted-in enforcement flags. The
+    optional fields default to absent so an empty profile renders cleanly; the
+    projection seam omits any field with no value.
+    """
+
+    name: str
+    role: str
+    language: str
+    rules: list[str]
+    seriousness: str
+    extra_rules_block: str
+    style: str = DEFAULT_STYLE
+    email: str | None = None
+    website: str | None = None
+    github: str | None = None
+    enforcement: Mapping[str, bool] = field(default_factory=dict)
+
+
+def extract_markdown_fields(profile: dict[str, Any]) -> MarkdownProfileFields:
+    """Extract the canonical Markdown-output field set from *profile*.
+
+    The defaults are delegated to the canonical profile model so Markdown
+    helpers and schema-backed profile loading cannot drift. Accepts either a
+    raw profile dict or a ``CanonicalProfile.for_harness`` projection.
+    """
+    canonical = coerce_profile(profile)
+    normalized = canonical.to_dict()
+    identity = normalized["identity"]
+    preferences = normalized["preferences"]
+    rules: list[str] = normalized["rules"]
+    return MarkdownProfileFields(
+        name=identity["name"],
+        role=identity["role"],
+        language=preferences["language"],
+        rules=rules,
+        seriousness=normalized["seriousness"],
+        extra_rules_block=_render_extra_rules_block(rules),
+        style=preferences["style"],
+        email=identity.get("email"),
+        website=identity.get("website"),
+        github=identity.get("github"),
+        enforcement=dict(normalized["enforcement"]),
+    )
+
+
+def _render_extra_rules_block(rules: list[str]) -> str:
+    """Format the optional ``## Custom Rules`` Markdown block.
+
+    Empty when *rules* is empty; otherwise a two-newline-separated
+    section header followed by a bullet list of rules.
+    """
+    if not rules:
+        return ""
+    body = "\n".join(f"- {r}" for r in rules)
+    return f"\n\n## Custom Rules\n\n{body}"
+
+
+def build_yaml_managed_config(profile: dict[str, Any], header: str) -> str:
+    """Render the canonical ``apothem_managed`` YAML config body.
+
+    Retained for compatibility with earlier generic materializers. The body
+    carries the apothem-managed sentinel, the full identity + preferences
+    sub-dicts (with their per-key defaults), the seriousness band, and an
+    optional rules list.
+    """
+    normalized = coerce_profile(profile).to_dict()
+    identity = normalized["identity"]
+    preferences = normalized["preferences"]
+    rules: list[str] = normalized["rules"]
+
+    config: dict[str, Any] = {
+        "apothem_managed": True,
+        "identity": {
+            "name": identity.get("name", ""),
+            "role": identity.get("role", ""),
+            "email": identity.get("email", ""),
+        },
+        "preferences": {
+            "language": preferences.get("language", DEFAULT_LANGUAGE),
+            "style": preferences.get("style", DEFAULT_STYLE),
+        },
+        "apothem_support": "apothem",
+        "seriousness": normalized["seriousness"],
+    }
+    if rules:
+        config["rules"] = rules
+
+    return header + yaml.safe_dump(config, default_flow_style=False, allow_unicode=True)

package/src/apothem/lib/harness_protocol.py

@@ -0,0 +1,59 @@
+# SPDX-License-Identifier: MIT
+
+"""Apothem harness adapter protocol — the foundation contract.
+
+Defines :class:`HarnessAdapter`, the structural contract every concrete
+adapter must satisfy. It lives in the foundation ``lib`` layer so the harness
+registry can reference the contract without the foundation importing its
+consumers; :mod:`apothem.harnesses` re-exports it as the public surface
+(importable as ``apothem.harnesses.HarnessAdapter``), and the adapters that
+satisfy it are declared in :mod:`apothem.lib.harness_registry`.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Any, Protocol, runtime_checkable
+
+
+@runtime_checkable
+class HarnessAdapter(Protocol):
+    """Protocol every apothem harness adapter must satisfy.
+
+    Adapters translate a shared :class:`dict` profile into a
+    harness-native configuration on disk.  The lifecycle contract is small:
+    an adapter owns one primary ``output_path`` anchor, implements the
+    install/update/uninstall/verify methods, and keeps the richer identity,
+    target, docs, capability, and package-data obligations in the central
+    registry.
+    """
+
+    @property
+    def name(self) -> str:
+        """Canonical kebab-case harness identifier (e.g. ``'claude-code'``)."""
+        ...
+
+    @property
+    def output_path(self) -> Path:
+        """Absolute path to the target configuration file."""
+        ...
+
+    def install(self, profile: dict[str, Any]) -> object:
+        """Materialize the harness configuration from the shared profile dict."""
+        ...
+
+    def update(self, profile: dict[str, Any]) -> object:
+        """Re-materialize the harness configuration from the updated profile."""
+        ...
+
+    def uninstall(self) -> None:
+        """Remove the harness configuration file if present."""
+        ...
+
+    def is_installed(self) -> bool:
+        """Return ``True`` if the harness configuration file exists on disk."""
+        ...
+
+    def verify(self) -> bool:
+        """Return ``True`` if the installed harness configuration is valid."""
+        ...

package/src/apothem/lib/harness_registry.py

@@ -0,0 +1,282 @@
+# SPDX-License-Identifier: MIT
+
+"""Central registry for supported Apothem harness adapters.
+
+The declarative ``HARNESS_REGISTRY`` data table lives in the sibling
+``harness_registry_data`` module; this module imports it and carries the
+resolution / discovery logic plus the derived lookup indexes. It re-exports the
+full public surface (data + types + functions) so
+``from apothem.lib.harness_registry import X`` is unchanged for every consumer.
+This module is authoritative at runtime.
+"""
+
+from __future__ import annotations
+
+import importlib
+import importlib.util
+import sys
+from collections.abc import Mapping
+from pathlib import Path
+from types import ModuleType
+
+from apothem.lib.harness_protocol import HarnessAdapter
+from apothem.lib.harness_registry_data import (
+    HARNESS_REGISTRY as HARNESS_REGISTRY,
+)
+from apothem.lib.harness_registry_data import (
+    REQUIRED_CAPABILITIES as REQUIRED_CAPABILITIES,
+)
+from apothem.lib.harness_registry_data import (
+    SUPPORTED_HARNESS_COUNT as SUPPORTED_HARNESS_COUNT,
+)
+from apothem.lib.harness_registry_data import (
+    CapabilityStatus as CapabilityStatus,
+)
+from apothem.lib.harness_registry_data import (
+    HarnessRegistryEntry as HarnessRegistryEntry,
+)
+from apothem.lib.harness_registry_data import (
+    HarnessScope as HarnessScope,
+)
+
+SUPPORTED_HARNESS_IDS: tuple[str, ...] = tuple(
+    entry.public_id for entry in HARNESS_REGISTRY
+)
+SUPPORTED_PACKAGE_KEYS: tuple[str, ...] = tuple(
+    entry.package_key for entry in HARNESS_REGISTRY
+)
+
+_BY_PUBLIC_ID: Mapping[str, HarnessRegistryEntry] = {
+    entry.public_id: entry for entry in HARNESS_REGISTRY
+}
+_BY_PACKAGE_KEY: Mapping[str, HarnessRegistryEntry] = {
+    entry.package_key: entry for entry in HARNESS_REGISTRY
+}
+
+if len(HARNESS_REGISTRY) != SUPPORTED_HARNESS_COUNT:  # pragma: no cover
+    raise RuntimeError(
+        "the supported harness registry must contain exactly "
+        f"{SUPPORTED_HARNESS_COUNT} entries"
+    )
+if len(set(SUPPORTED_HARNESS_IDS)) != SUPPORTED_HARNESS_COUNT:  # pragma: no cover
+    raise RuntimeError("duplicate public harness ids in registry")
+if len(set(SUPPORTED_PACKAGE_KEYS)) != SUPPORTED_HARNESS_COUNT:  # pragma: no cover
+    raise RuntimeError("duplicate harness package keys in registry")
+
+
+def normalize_harness_reference(value: object) -> str:
+    """Normalize a public id or package key reference for registry lookup."""
+    return str(value).strip().lower()
+
+
+def iter_harness_entries() -> tuple[HarnessRegistryEntry, ...]:
+    """Return registry entries in deterministic public-id order."""
+    return HARNESS_REGISTRY
+
+
+def get_harness_entry(value: object) -> HarnessRegistryEntry:
+    """Return the registry entry addressed by public id or package key."""
+    key = normalize_harness_reference(value)
+    if key in _BY_PUBLIC_ID:
+        return _BY_PUBLIC_ID[key]
+    if key in _BY_PACKAGE_KEY:
+        return _BY_PACKAGE_KEY[key]
+    raise KeyError(key)
+
+
+def public_id_for_package_key(package_key: object) -> str:
+    """Return the public harness id for a Python package key."""
+    return get_harness_entry(package_key).public_id
+
+
+def package_key_for_public_id(public_id: object) -> str:
+    """Return the Python package key for a public harness id."""
+    return get_harness_entry(public_id).package_key
+
+
+def load_adapter_class(entry: HarnessRegistryEntry) -> type[object]:
+    """Import and return the adapter class declared by a registry entry."""
+    module = importlib.import_module(entry.adapter_module)
+    adapter_class = getattr(module, entry.adapter_class_name)
+    if not isinstance(adapter_class, type):
+        raise TypeError(f"{entry.entry_point} did not resolve to a class")
+    return adapter_class
+
+
+class AdapterDiscoveryError(RuntimeError):
+    """Raised when a harness sub-package fails convention-based adapter resolution.
+
+    The error message names the offending directory so a silently-dropped
+    adapter never becomes an invisible coverage regression.
+    """
+
+
+# Directory names under ``harnesses/`` that hold shared helpers rather than a
+# concrete adapter sub-package. They are skipped during discovery alongside
+# private (underscore / dot prefixed) and cache directories.
+_DISCOVERY_HELPER_DIRS: frozenset[str] = frozenset({"_shared", "templates"})
+
+
+def _adapter_canonical_name(package_key: str) -> str:
+    """Return the canonical kebab-case name for a harness package directory.
+
+    Reuses the static registry's ``package_key`` -> ``public_id`` mapping for
+    fidelity (e.g. ``claude_code`` -> ``claude-code``). Falls back to a direct
+    underscore-to-hyphen transform when the directory is not yet registered,
+    so a newly-added adapter is still discoverable before the static registry
+    is updated.
+    """
+    entry = _BY_PACKAGE_KEY.get(package_key)
+    if entry is not None:
+        return entry.public_id
+    return package_key.replace("_", "-")
+
+
+def _resolve_adapter_class(package_key: str, module: object) -> type[object]:
+    """Find the single ``*Adapter`` class exposed by an imported harness module.
+
+    The class name is resolved by convention rather than computed from the
+    directory name: the snake-to-Pascal transform is not reliable (for
+    instance ``github_copilot`` exposes ``GitHubCopilotAdapter`` with an
+    internal capital ``H``). Instead every attribute whose name ends with
+    ``Adapter`` and is a class is collected; exactly one must be present.
+    """
+    candidates: list[type[object]] = []
+    for attr_name in dir(module):
+        if not attr_name.endswith("Adapter"):
+            continue
+        attr = getattr(module, attr_name)
+        if isinstance(attr, type) and attr is not HarnessAdapter:
+            candidates.append(attr)
+
+    # De-duplicate while preserving identity (an adapter may be re-exported
+    # under more than one attribute name pointing at the same class object).
+    unique = list(dict.fromkeys(candidates))
+    if not unique:
+        raise AdapterDiscoveryError(
+            f"harnesses/{package_key}: no '*Adapter' class found in the package module"
+        )
+    if len(unique) > 1:
+        names = ", ".join(sorted(cls.__name__ for cls in unique))
+        raise AdapterDiscoveryError(
+            f"harnesses/{package_key}: expected exactly one '*Adapter' class, "
+            f"found {len(unique)} ({names})"
+        )
+    return unique[0]
+
+
+def _is_installed_package_root(root: Path) -> bool:
+    """Return ``True`` when ``root`` is the installed ``apothem`` package dir."""
+    import apothem
+
+    apothem_file = getattr(apothem, "__file__", None)
+    if apothem_file is None:  # pragma: no cover - namespace package edge
+        return False
+    return Path(apothem_file).resolve().parent == root.resolve()
+
+
+def _import_harness_module(root: Path, name: str, package_dir: Path) -> ModuleType:
+    """Import the harness sub-package ``name`` found under ``root / harnesses``.
+
+    When ``root`` is the installed ``apothem`` package directory the robust
+    namespace import (``apothem.harnesses.<name>``) is used — this honors
+    editable installs and namespace-package layouts. Otherwise the module is
+    loaded directly from its ``__init__.py`` on disk, so an arbitrary ``root``
+    (for instance a test fixture tree) is enumerated against the actual files
+    it contains rather than the installed package.
+    """
+    if _is_installed_package_root(root):
+        return importlib.import_module(f"apothem.harnesses.{name}")
+
+    fq_name = f"_apothem_discovered_harness_{name}"
+    spec = importlib.util.spec_from_file_location(fq_name, package_dir / "__init__.py")
+    if spec is None or spec.loader is None:  # pragma: no cover - defensive
+        raise AdapterDiscoveryError(
+            f"harnesses/{name}: package could not be loaded from {package_dir}"
+        )
+    module = importlib.util.module_from_spec(spec)
+    sys.modules[fq_name] = module
+    spec.loader.exec_module(module)
+    return module
+
+
+def discover_adapters(root: Path) -> dict[str, type[object]]:
+    """Discover harness adapters by filesystem convention under ``root``.
+
+    Conformance utility, NOT the runtime resolver. The authoritative
+    adapter source at runtime is the static :data:`HARNESS_REGISTRY`; this
+    discovery exists so a parity test can assert the on-disk adapter set
+    equals the registry, catching a convention-correct but unregistered
+    adapter as a coverage regression. No CLI / runtime path calls this.
+
+    Scans the immediate subdirectories of ``root / "harnesses"``, importing
+    each package and resolving its ``*Adapter`` class by convention. The
+    returned mapping is keyed by the adapter's canonical kebab-case name and
+    ordered deterministically (sorted by key).
+
+    Args:
+        root: The ``apothem`` package directory whose ``harnesses/``
+            subdirectory holds the per-harness adapter sub-packages.
+
+    Returns:
+        A ``dict`` mapping canonical harness name (e.g. ``'claude-code'``)
+        to the resolved adapter class, in sorted key order.
+
+    Raises:
+        AdapterDiscoveryError: When a candidate sub-package exposes zero or
+            more than one ``*Adapter`` class. The message names the directory.
+    """
+    harnesses_dir = root / "harnesses"
+    discovered: dict[str, type[object]] = {}
+    for child in sorted(harnesses_dir.iterdir()):
+        if not child.is_dir():
+            continue
+        name = child.name
+        if name.startswith(("_", ".")) or name in _DISCOVERY_HELPER_DIRS:
+            continue
+        if not (child / "__init__.py").is_file():
+            continue
+        module = _import_harness_module(root, name, child)
+        adapter_class = _resolve_adapter_class(name, module)
+        discovered[_adapter_canonical_name(name)] = adapter_class
+    return dict(sorted(discovered.items()))
+
+
+def discovered_adapter_map() -> dict[str, type[object]]:
+    """Discover adapters under the installed ``apothem`` package directory.
+
+    Convenience wrapper over :func:`discover_adapters` that defaults ``root``
+    to the directory of the installed ``apothem`` package, so callers need
+    not compute it themselves. Like :func:`discover_adapters`, this is a
+    conformance/parity utility (registry-vs-filesystem agreement), not the
+    runtime adapter resolver — the static :data:`HARNESS_REGISTRY` is
+    authoritative at runtime.
+
+    Returns:
+        A ``dict`` mapping canonical harness name to adapter class, sorted.
+    """
+    import apothem
+
+    package_root = Path(apothem.__file__).resolve().parent
+    return discover_adapters(package_root)
+
+
+__all__ = [
+    "HARNESS_REGISTRY",
+    "REQUIRED_CAPABILITIES",
+    "SUPPORTED_HARNESS_COUNT",
+    "SUPPORTED_HARNESS_IDS",
+    "SUPPORTED_PACKAGE_KEYS",
+    "AdapterDiscoveryError",
+    "CapabilityStatus",
+    "HarnessRegistryEntry",
+    "HarnessScope",
+    "discover_adapters",
+    "discovered_adapter_map",
+    "get_harness_entry",
+    "iter_harness_entries",
+    "load_adapter_class",
+    "normalize_harness_reference",
+    "package_key_for_public_id",
+    "public_id_for_package_key",
+]