plm-skill-kernel 1.0.0__tar.gz

plm_skill_kernel-1.0.0/PKG-INFO

@@ -0,0 +1,135 @@
+Metadata-Version: 2.4
+Name: plm-skill-kernel
+Version: 1.0.0
+Summary: TracePulse PLM Skill Kernel — Wave 2 Conv A. Decorator-based Skill SDK + V1 in-process dispatcher + Kernel HTTP server stub matching CR.10 §7.bis (POST /v1/skills/{id}/invoke). Ships 3 starter skills (cleansing.normalise, cleansing.dedupe, bpmn.generate). Sibling of plm-engine-core; the two communicate over the V1.1 HTTP loopback (SKILL_KERNEL_LOOPBACK=on) — no Python-level coupling at the dispatch boundary.
+Author: TracePulse
+License: Proprietary
+Requires-Python: >=3.12
+Description-Content-Type: text/markdown
+Requires-Dist: plm-shared
+Requires-Dist: pydantic>=2.5.0
+Requires-Dist: fastapi>=0.110
+Requires-Dist: uvicorn>=0.27
+Requires-Dist: httpx>=0.27.0
+Requires-Dist: plm-engine-core
+Requires-Dist: plm-knowledge
+Provides-Extra: test
+Requires-Dist: pytest; extra == "test"
+Requires-Dist: pytest-asyncio; extra == "test"
+Requires-Dist: httpx<1,>=0.27; extra == "test"
+
+# plm-skill-kernel
+
+Wave 2 Conv A (FTR-604). The Skill Kernel package — sibling of
+`plm-engine-core` — that hosts the decorator-based Skill SDK, the V1
+in-process dispatcher, and the Kernel HTTP server stub matching CR.10
+§7.bis verbatim.
+
+## Layout
+
+```
+02_App/plm-skill-kernel/
+├── pyproject.toml             # editable install + import-linter contracts
+├── plm_skill_kernel/
+│   ├── __init__.py            # re-exports `skill`, `SkillContext`, etc.
+│   ├── __main__.py            # `python -m plm_skill_kernel` → server
+│   ├── server.py              # FastAPI app at POST /v1/skills/{id}/invoke
+│   ├── dispatcher.py          # V1 in-process invoker
+│   ├── registry.py            # boot wiring — discovers + registers skills
+│   ├── sdk/
+│   │   ├── decorator.py       # `@skill(id=, version=)`
+│   │   ├── context.py         # SkillContext Pydantic
+│   │   ├── types.py           # SkillInvokeRequest / SkillInvokeResult
+│   │   └── _registry.py       # in-process decorator registry
+│   └── skills/                # 3 starter skills (Q-W2A-1 nested layout)
+│       ├── cleansing/
+│       │   ├── normalise.py   # cleansing.normalise / 1.0.0 / L2
+│       │   └── dedupe.py      # cleansing.dedupe / 1.0.0 / L2
+│       └── bpmn/
+│           └── generate.py    # bpmn.generate / 1.0.0 / L1 (thin proxy)
+└── tests/                     # unit + ASGI in-process integration
+```
+
+## Editable install
+
+```bash
+cd 02_App/backend
+.\venv\Scripts\Activate.ps1                  # Windows
+pip install -e ../plm-skill-kernel
+```
+
+Mirrors the plm-engine-core editable-install pattern.
+
+## Dev launch (Q-W2A-3)
+
+```bash
+python -m plm_skill_kernel               # uvicorn on port 8100
+plm-skill-kernel --port 8100             # equivalent CLI
+```
+
+The backend at port 8000 is unaffected. The V1.1 loopback round-trip
+(D-CONV-M-4 closure) sends HTTP from the Engine Core dispatcher to
+this Kernel server when `SKILL_KERNEL_LOOPBACK=on`.
+
+## V1 wire contract
+
+`POST /v1/skills/{id}/invoke` — frozen at CR.10 §7.bis.
+
+```
+Headers:
+  X-Core-Caller: <UUID>            (required when caller is Core)
+  Idempotency-Key: <uuid>          (optional, V1)
+  traceparent: <W3C>               (optional)
+
+Request body (SkillInvokeRequest):
+  payload:        Dict[str, Any]
+  version:        str  ("1.0.0", etc.)
+  autonomy_hint:  Optional[str]    ("L1" / "L2" / "L3")
+
+Response body (SkillInvokeResult):
+  ok:             bool
+  result:         Optional[Dict[str, Any]]
+  error:          Optional[SkillErrorEnvelope]
+  deferred_to:    Optional[str]
+  cancelled:      Optional[bool]
+```
+
+## Skill authoring (Decision #59 — decorator)
+
+```python
+from plm_skill_kernel import skill, SkillContext
+
+@skill(id="cleansing.normalise", version="1.0.0")
+async def normalise(payload: dict, ctx: SkillContext) -> dict:
+    return {"normalised": _normalise_records(payload["records"])}
+```
+
+The decorator auto-registers into the in-process registry at module
+import time + carries `version` through to the federated manifest
+builder (CR.9).
+
+## Import-linter contracts
+
+Two Forbidden contracts live in `pyproject.toml`:
+
+1. `plm_skill_kernel` MUST NOT import `plm_engine_core` — federation
+   contract preservation. The two communicate over HTTP, not Python.
+2. `plm_skill_kernel` MUST NOT import `plm_accelerators` (Workbench)
+   — mirror of the plm-engine-core constraint.
+
+Run:
+
+```bash
+lint-imports --config 02_App/plm-skill-kernel/pyproject.toml
+```
+
+## Tests
+
+```bash
+cd 02_App/plm-skill-kernel
+python -m pytest -q
+```
+
+The V1.1 HTTP round-trip integration test mounts the FastAPI app via
+httpx.AsyncClient(ASGITransport) — no subprocess, no real port
+(Q-W2A-4).

plm_skill_kernel-1.0.0/README.md

@@ -0,0 +1,115 @@
+# plm-skill-kernel
+
+Wave 2 Conv A (FTR-604). The Skill Kernel package — sibling of
+`plm-engine-core` — that hosts the decorator-based Skill SDK, the V1
+in-process dispatcher, and the Kernel HTTP server stub matching CR.10
+§7.bis verbatim.
+
+## Layout
+
+```
+02_App/plm-skill-kernel/
+├── pyproject.toml             # editable install + import-linter contracts
+├── plm_skill_kernel/
+│   ├── __init__.py            # re-exports `skill`, `SkillContext`, etc.
+│   ├── __main__.py            # `python -m plm_skill_kernel` → server
+│   ├── server.py              # FastAPI app at POST /v1/skills/{id}/invoke
+│   ├── dispatcher.py          # V1 in-process invoker
+│   ├── registry.py            # boot wiring — discovers + registers skills
+│   ├── sdk/
+│   │   ├── decorator.py       # `@skill(id=, version=)`
+│   │   ├── context.py         # SkillContext Pydantic
+│   │   ├── types.py           # SkillInvokeRequest / SkillInvokeResult
+│   │   └── _registry.py       # in-process decorator registry
+│   └── skills/                # 3 starter skills (Q-W2A-1 nested layout)
+│       ├── cleansing/
+│       │   ├── normalise.py   # cleansing.normalise / 1.0.0 / L2
+│       │   └── dedupe.py      # cleansing.dedupe / 1.0.0 / L2
+│       └── bpmn/
+│           └── generate.py    # bpmn.generate / 1.0.0 / L1 (thin proxy)
+└── tests/                     # unit + ASGI in-process integration
+```
+
+## Editable install
+
+```bash
+cd 02_App/backend
+.\venv\Scripts\Activate.ps1                  # Windows
+pip install -e ../plm-skill-kernel
+```
+
+Mirrors the plm-engine-core editable-install pattern.
+
+## Dev launch (Q-W2A-3)
+
+```bash
+python -m plm_skill_kernel               # uvicorn on port 8100
+plm-skill-kernel --port 8100             # equivalent CLI
+```
+
+The backend at port 8000 is unaffected. The V1.1 loopback round-trip
+(D-CONV-M-4 closure) sends HTTP from the Engine Core dispatcher to
+this Kernel server when `SKILL_KERNEL_LOOPBACK=on`.
+
+## V1 wire contract
+
+`POST /v1/skills/{id}/invoke` — frozen at CR.10 §7.bis.
+
+```
+Headers:
+  X-Core-Caller: <UUID>            (required when caller is Core)
+  Idempotency-Key: <uuid>          (optional, V1)
+  traceparent: <W3C>               (optional)
+
+Request body (SkillInvokeRequest):
+  payload:        Dict[str, Any]
+  version:        str  ("1.0.0", etc.)
+  autonomy_hint:  Optional[str]    ("L1" / "L2" / "L3")
+
+Response body (SkillInvokeResult):
+  ok:             bool
+  result:         Optional[Dict[str, Any]]
+  error:          Optional[SkillErrorEnvelope]
+  deferred_to:    Optional[str]
+  cancelled:      Optional[bool]
+```
+
+## Skill authoring (Decision #59 — decorator)
+
+```python
+from plm_skill_kernel import skill, SkillContext
+
+@skill(id="cleansing.normalise", version="1.0.0")
+async def normalise(payload: dict, ctx: SkillContext) -> dict:
+    return {"normalised": _normalise_records(payload["records"])}
+```
+
+The decorator auto-registers into the in-process registry at module
+import time + carries `version` through to the federated manifest
+builder (CR.9).
+
+## Import-linter contracts
+
+Two Forbidden contracts live in `pyproject.toml`:
+
+1. `plm_skill_kernel` MUST NOT import `plm_engine_core` — federation
+   contract preservation. The two communicate over HTTP, not Python.
+2. `plm_skill_kernel` MUST NOT import `plm_accelerators` (Workbench)
+   — mirror of the plm-engine-core constraint.
+
+Run:
+
+```bash
+lint-imports --config 02_App/plm-skill-kernel/pyproject.toml
+```
+
+## Tests
+
+```bash
+cd 02_App/plm-skill-kernel
+python -m pytest -q
+```
+
+The V1.1 HTTP round-trip integration test mounts the FastAPI app via
+httpx.AsyncClient(ASGITransport) — no subprocess, no real port
+(Q-W2A-4).

plm_skill_kernel-1.0.0/plm_skill_kernel/__init__.py

@@ -0,0 +1,33 @@
+"""TracePulse PLM Skill Kernel — Wave 2 Conv A (FTR-604).
+
+Sibling of ``plm-engine-core``. Owns:
+
+* The decorator-based Skill SDK (Decision #59 — Q-W2A-1 nested layout).
+* The V1 in-process dispatcher.
+* The Kernel HTTP server stub at ``POST /v1/skills/{id}/invoke``
+  matching CR.10 §7.bis verbatim.
+* 3 starter skills harvested per Decision #60 — ``cleansing.normalise``,
+  ``cleansing.dedupe``, ``bpmn.generate``.
+
+The Kernel and the Engine Core are deployed-separable. Their only
+sanctioned interaction is the V1.1 HTTP loopback (env-flagged on
+``SKILL_KERNEL_LOOPBACK``); any Python-level reach-in is forbidden by
+the import-linter contract in ``pyproject.toml``.
+"""
+__version__ = "0.1.0-alpha"
+
+# The decorator + sdk surface is the public authoring API. Re-exported
+# here so callers write ``from plm_skill_kernel import skill`` rather
+# than the deeper path. Skill author imports stay short + stable.
+from .sdk.decorator import skill
+from .sdk.context import SkillContext
+from .sdk.types import SkillInvokeRequest, SkillInvokeResult, SkillErrorEnvelope
+
+__all__ = [
+    "SkillContext",
+    "SkillErrorEnvelope",
+    "SkillInvokeRequest",
+    "SkillInvokeResult",
+    "__version__",
+    "skill",
+]

plm_skill_kernel-1.0.0/plm_skill_kernel/__main__.py

@@ -0,0 +1,13 @@
+"""``python -m plm_skill_kernel`` entry — delegates to :func:`server._cli_entry`.
+
+Q-W2A-3 picked the standalone launch shape. The ``__main__`` module is
+the canonical Python idiom; the ``plm-skill-kernel`` console script
+points at the same function via ``pyproject.toml [project.scripts]``.
+"""
+from __future__ import annotations
+
+from .server import _cli_entry
+
+
+if __name__ == "__main__":
+    _cli_entry()

plm_skill_kernel-1.0.0/plm_skill_kernel/dispatcher.py

@@ -0,0 +1,141 @@
+"""V1 in-process Kernel dispatcher.
+
+Resolves ``(skill_id, version)`` against the SDK registry, validates the
+payload + context, and invokes the registered callable. Exceptions are
+caught + converted to a typed :class:`SkillInvokeResult` carrying a
+:class:`SkillErrorEnvelope` — bare exceptions never escape the dispatch
+boundary so the HTTP server can rely on always getting back a
+serialisable result.
+
+Decision #51 (Conv M / Q-M2 = (c) "Both"): the dispatcher lives in
+plm-skill-kernel; the plm-engine-core dispatcher (under
+``plm_engine_core.agent_runtime.dispatcher``) becomes a thin transport
+proxy when ``SKILL_KERNEL_LOOPBACK=on`` (Wave 2 Conv A item 8 — the
+V1.1 transport closure for D-CONV-M-4).
+"""
+from __future__ import annotations
+
+import logging
+from typing import Any, Dict, Optional
+
+from .sdk._registry import RegisteredSkill, _Registry, get_registry
+from .sdk.context import SkillContext
+from .sdk.types import (
+    SkillErrorEnvelope,
+    SkillInvokeRequest,
+    SkillInvokeResult,
+)
+
+
+logger = logging.getLogger(__name__)
+
+
+# ── Error codes (D-AUDIT-7 entries owned by the Skill Kernel) ────────────
+#
+# These mirror string-values declared on
+# ``plm_engine_core.control_plane.capability_registry.errors`` +
+# ``services/llm_errors.py``. Wave 2 Conv A re-uses the existing
+# ``SKILL_NOT_FOUND`` / ``SKILL_VERSION_NOT_FOUND`` /
+# ``KERNEL_DISPATCH_DISABLED`` strings (no new codes — the close
+# audit at Conv N tallied 57 codes; this conv keeps that total).
+SKILL_NOT_FOUND = "SKILL_NOT_FOUND"
+SKILL_VERSION_NOT_FOUND = "SKILL_VERSION_NOT_FOUND"
+KERNEL_DISPATCH_FAILED = "KERNEL_DISPATCH_FAILED"
+
+
+class InProcessDispatcher:
+    """V1 in-process invoker.
+
+    Constructor accepts an explicit registry so tests can isolate
+    registration state. Production callers receive the module-level
+    singleton via :func:`get_registry`.
+    """
+
+    def __init__(self, registry: Optional[_Registry] = None) -> None:
+        self._registry = registry if registry is not None else get_registry()
+
+    async def dispatch(
+        self,
+        skill_id: str,
+        request: SkillInvokeRequest,
+        *,
+        context: SkillContext,
+    ) -> SkillInvokeResult:
+        """Resolve + invoke a skill.
+
+        Returns a :class:`SkillInvokeResult` always — exceptions raised
+        by the skill body are caught and surfaced via the
+        ``KERNEL_DISPATCH_FAILED`` envelope.
+        """
+        entry = self._registry.resolve(skill_id, request.version)
+        if entry is None:
+            return self._not_found(skill_id, request.version)
+
+        try:
+            result = await entry.fn(dict(request.payload), context)
+        except Exception as exc:  # noqa: BLE001 — boundary; we re-package
+            logger.exception(
+                "skill dispatch failed skill_id=%s version=%s",
+                skill_id,
+                request.version,
+            )
+            return SkillInvokeResult(
+                ok=False,
+                error=SkillErrorEnvelope(
+                    error_code=KERNEL_DISPATCH_FAILED,
+                    message=f"skill {skill_id!r} raised {type(exc).__name__}",
+                    detail={"exception_message": str(exc)},
+                ),
+            )
+
+        # V1 contract: skills return a JSON-serialisable dict.
+        if not isinstance(result, dict):
+            return SkillInvokeResult(
+                ok=False,
+                error=SkillErrorEnvelope(
+                    error_code=KERNEL_DISPATCH_FAILED,
+                    message=(
+                        f"skill {skill_id!r} returned a non-dict result; "
+                        "V1 contract requires `dict[str, Any]`"
+                    ),
+                    detail={"actual_type": type(result).__name__},
+                ),
+            )
+
+        return SkillInvokeResult(ok=True, result=result)
+
+    def _not_found(self, skill_id: str, version: str) -> SkillInvokeResult:
+        # Differentiate "skill_id has no entries" from
+        # "skill_id exists but the requested version is missing" by
+        # walking the registry once.
+        any_version_for_id = any(
+            e.skill_id == skill_id for e in self._registry.list_all()
+        )
+        if any_version_for_id:
+            return SkillInvokeResult(
+                ok=False,
+                error=SkillErrorEnvelope(
+                    error_code=SKILL_VERSION_NOT_FOUND,
+                    message=(
+                        f"skill {skill_id!r} version {version!r} is not "
+                        "registered"
+                    ),
+                    detail={"skill_id": skill_id, "version": version},
+                ),
+            )
+        return SkillInvokeResult(
+            ok=False,
+            error=SkillErrorEnvelope(
+                error_code=SKILL_NOT_FOUND,
+                message=f"no skill registered for id={skill_id!r}",
+                detail={"skill_id": skill_id, "version": version},
+            ),
+        )
+
+
+__all__ = [
+    "InProcessDispatcher",
+    "KERNEL_DISPATCH_FAILED",
+    "SKILL_NOT_FOUND",
+    "SKILL_VERSION_NOT_FOUND",
+]

plm_skill_kernel-1.0.0/plm_skill_kernel/registry.py

@@ -0,0 +1,80 @@
+"""Boot-time skill discovery + registration.
+
+Importing :func:`load_starter_skills` triggers the import of each
+starter-skill module. Each module's top-level ``@skill(...)``
+decorator runs as a side-effect of import, so by the time
+:func:`load_starter_skills` returns the SDK registry contains every
+starter skill.
+
+This module is the V1 wiring point — production ``server.py`` calls
+:func:`load_starter_skills` at startup. Tests that need a clean
+registry call ``get_registry().clear()`` first.
+
+Wave 3 Conv A (per Decision #60) added ``documents.parse`` +
+``agents.suggest`` to the fan-out — bringing the starter set to 5
+skills (3 Wave 2 + 2 Wave 3).
+
+Wave 5 Conv C (FTR-603 / Decision #122 + #124) adds the 5 active V1
+``knowledge.*`` primitives — bringing the boot-loaded set to 10
+skills (3 Wave 2 + 2 Wave 3 + 5 Wave 5). The 2 deferred primitives
+(``explain`` / ``context_pack``) stay YAML ``draft`` capabilities
+only and do NOT register a kernel skill in V1; their dispatch is
+short-circuited by the engine-core envelope returning
+``KS_PRIMITIVE_DEFERRED_V1_1``.
+"""
+from __future__ import annotations
+
+import logging
+from typing import List, Tuple
+
+from .sdk._registry import RegisteredSkill, get_registry
+
+
+logger = logging.getLogger(__name__)
+
+
+def load_starter_skills() -> List[RegisteredSkill]:
+    """Import the 5 starter skills + return the resulting list.
+
+    The imports themselves run the decorator side-effects; this
+    function returns the registry's view post-load so callers can
+    log or assert on the exact skills available.
+
+    Idempotent — re-importing a module is a no-op (Python caches),
+    and the SDK registry tolerates same-callable re-registration.
+    """
+    # Local imports — module-load side effect is the registration. The
+    # imports MUST be inside the function so test fixtures that clear
+    # the registry can re-trigger registration by re-calling.
+    # NOTE: `noqa: F401` because the bound names are unused; the
+    # imports' side effect (decorator registration) is the point.
+    from .skills.cleansing import dedupe as _dedupe  # noqa: F401
+    from .skills.cleansing import normalise as _normalise  # noqa: F401
+    from .skills.bpmn import generate as _generate  # noqa: F401
+    from .skills.documents import parse as _parse  # noqa: F401
+    from .skills.agents import suggest as _suggest  # noqa: F401
+    # Wave 5 Conv C — FTR-603 Knowledge Services V1 active primitives.
+    from .skills.knowledge import search as _ks_search  # noqa: F401
+    from .skills.knowledge import get_record as _ks_get_record  # noqa: F401
+    from .skills.knowledge import retrieve as _ks_retrieve  # noqa: F401
+    from .skills.knowledge import resolve as _ks_resolve  # noqa: F401
+    from .skills.knowledge import validate as _ks_validate  # noqa: F401
+
+    entries = get_registry().list_all()
+    logger.info(
+        "skill_kernel boot_loaded count=%s ids=%s",
+        len(entries),
+        ",".join(sorted(f"{e.skill_id}@{e.version}" for e in entries)),
+    )
+    return entries
+
+
+def list_registered_skill_ids() -> List[Tuple[str, str]]:
+    """Return ``(skill_id, version)`` pairs for every registered entry.
+
+    Used by the federation manifest builder + introspection endpoints.
+    """
+    return [(e.skill_id, e.version) for e in get_registry().list_all()]
+
+
+__all__ = ["list_registered_skill_ids", "load_starter_skills"]

plm_skill_kernel-1.0.0/plm_skill_kernel/sdk/__init__.py

@@ -0,0 +1,29 @@
+"""Public Skill SDK surface (Wave 2 Conv A / Decision #59).
+
+Skill authors import from here:
+
+    from plm_skill_kernel import skill, SkillContext
+    # or, equivalently:
+    from plm_skill_kernel.sdk import skill, SkillContext
+
+The decorator + context + wire types are the V1-stable authoring
+surface; internal helpers (the registry implementation, validation
+helpers) live under ``plm_skill_kernel.sdk._registry`` and are NOT
+re-exported.
+"""
+from .context import SkillContext
+from .decorator import SkillDecoratorError, skill
+from .types import (
+    SkillErrorEnvelope,
+    SkillInvokeRequest,
+    SkillInvokeResult,
+)
+
+__all__ = [
+    "SkillContext",
+    "SkillDecoratorError",
+    "SkillErrorEnvelope",
+    "SkillInvokeRequest",
+    "SkillInvokeResult",
+    "skill",
+]

plm_skill_kernel-1.0.0/plm_skill_kernel/sdk/_registry.py

@@ -0,0 +1,111 @@
+"""Internal in-process decorator registry.
+
+The :func:`plm_skill_kernel.sdk.skill` decorator stamps each
+``async def`` it wraps into this module-level registry at import
+time. The Kernel dispatcher then resolves ``(skill_id, version)``
+back to the callable at dispatch time.
+
+Hot-reload (V1.1) replaces a single entry atomically; V1 callers that
+re-import a skill module will get a duplicate-registration error so
+test suites can detect accidental re-registration.
+
+Decision #25 / #41 / #52 / #53 V1 in-memory + Protocol pattern:
+the registry is a module-level dict + an ``RLock``. Wave 4+ may swap
+the backing store for a process-shared cache without changing the
+public surface (which is just ``register`` + ``resolve`` + ``list_all``).
+"""
+from __future__ import annotations
+
+import threading
+from dataclasses import dataclass
+from typing import Awaitable, Callable, Dict, List, Optional, Tuple
+
+from .context import SkillContext
+
+
+# Type alias for a registered skill body — every skill is
+# ``async def fn(payload: dict, ctx: SkillContext) -> dict``.
+SkillCallable = Callable[
+    [Dict, SkillContext], Awaitable[Dict]
+]
+
+
+@dataclass(frozen=True)
+class RegisteredSkill:
+    """One entry in the decorator registry.
+
+    The ``min_autonomy`` + ``streaming`` + ``hitl_required`` fields
+    are advisory metadata the SDK can pass through to the federation
+    manifest builder (CR.9) at boot. They are NOT enforced at dispatch
+    time — Core's selector + gating already ran upstream.
+    """
+
+    skill_id: str
+    version: str
+    fn: SkillCallable
+    description: Optional[str]
+    min_autonomy: str  # "L1" / "L2" / "L3"
+    streaming: bool
+    hitl_required: bool
+
+
+class _Registry:
+    """Thread-safe registry of decorated skills.
+
+    Keyed by ``(skill_id, version)``. Adding a duplicate raises a
+    :class:`RuntimeError` so test fixtures catch double-registration
+    rather than silently shadowing.
+    """
+
+    def __init__(self) -> None:
+        self._lock = threading.RLock()
+        self._entries: Dict[Tuple[str, str], RegisteredSkill] = {}
+
+    def register(self, entry: RegisteredSkill) -> None:
+        key = (entry.skill_id, entry.version)
+        with self._lock:
+            existing = self._entries.get(key)
+            if existing is not None and existing.fn is not entry.fn:
+                raise RuntimeError(
+                    f"skill {entry.skill_id!r} version {entry.version!r} "
+                    "is already registered with a different callable; "
+                    "duplicate registration is forbidden in V1"
+                )
+            self._entries[key] = entry
+
+    def resolve(
+        self, skill_id: str, version: str
+    ) -> Optional[RegisteredSkill]:
+        with self._lock:
+            return self._entries.get((skill_id, version))
+
+    def list_all(self) -> List[RegisteredSkill]:
+        with self._lock:
+            return list(self._entries.values())
+
+    def clear(self) -> None:
+        """Test-only — unregister everything. Production callers MUST NOT."""
+        with self._lock:
+            self._entries.clear()
+
+
+# Module-level singleton. Imported by the decorator + the dispatcher.
+_REGISTRY = _Registry()
+
+
+def get_registry() -> _Registry:
+    """Return the module-level registry singleton.
+
+    Tests that need isolation can call ``get_registry().clear()`` in a
+    fixture's setup; production callers never construct a fresh registry
+    (skills register at import time into the singleton).
+    """
+    return _REGISTRY
+
+
+__all__ = [
+    "RegisteredSkill",
+    "SkillCallable",
+    "_Registry",
+    "get_registry",
+]