dna-client 0.21.1__tar.gz

dna_client-0.21.1/.gitignore

@@ -0,0 +1,23 @@
+__pycache__/
+*.py[cod]
+.venv/
+.pytest_cache/
+.ruff_cache/
+node_modules/
+*.tsbuildinfo
+dist/
+coverage/
+.DS_Store
+.env
+.env.*
+!.env.example
+# resolver cache — created when a demo/example resolves github: deps
+.dna-cache/
+# MkDocs build output — the docs site is built in CI / on Pages, never committed
+site/
+# per-workstation pointer written by `dna sdlc story start` (read by the
+# prepare-commit-msg hook) — never source-of-truth, never committed
+.dna/active-story.txt
+
+# Local hybrid-search index store (dna recall/search) — s-record-search-sqlite
+.dna-search/

dna_client-0.21.1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 DNA contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

dna_client-0.21.1/PKG-INFO

@@ -0,0 +1,93 @@
+Metadata-Version: 2.4
+Name: dna-client
+Version: 0.21.1
+Summary: DNA — Official Python client for the DNA REST read-API (spec-parity twin of the TypeScript dna-client)
+Project-URL: Homepage, https://ruinosus.github.io/dna/
+Project-URL: Repository, https://github.com/ruinosus/dna
+Project-URL: Documentation, https://ruinosus.github.io/dna/guides/using-the-client/
+Project-URL: Changelog, https://github.com/ruinosus/dna/blob/main/CHANGELOG.md
+Project-URL: Issues, https://github.com/ruinosus/dna/issues
+License-Expression: MIT
+License-File: LICENSE
+Keywords: agents,client,dna,openapi,rest,sdlc,typed
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Typing :: Typed
+Requires-Python: <3.14,>=3.12
+Requires-Dist: httpx>=0.27
+Provides-Extra: dev
+Requires-Dist: dna-cli[api]; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# dna-client (Python)
+
+The **official Python client for the DNA REST API** (`dna api serve`).
+Spec-parity twin of the TypeScript [`dna-client`](https://www.npmjs.com/package/dna-client):
+both cover the same surface, derived from the same OpenAPI document
+(`docs/openapi.json`, dumped from the FastAPI app) — so consumers stop
+hand-rolling HTTP.
+
+- **Typed inputs**, `httpx`-based, sync, context-manageable.
+- **Complete** — a named method for EVERY operation in the spec, reads and
+  writes alike. `client.request(...)` remains as a low-level escape hatch, but
+  no route depends on it.
+- **Guarded** — a drift test re-dumps the live schema and fails CI if the
+  committed spec is stale, *and* fails if any operation (of any HTTP method)
+  has no named method. Adding a write route cannot pass silently.
+
+## Install
+
+```bash
+pip install dna-client        # or: uv add dna-client
+```
+
+Only runtime dep is `httpx`. Python >= 3.12.
+
+## Usage
+
+```python
+from dna_client import DnaClient
+
+with DnaClient(
+    "http://127.0.0.1:8080",
+    token="…",                 # optional — for --auth token/config
+    scope="dna-development",    # optional default applied to every call
+) as dna:
+    agents = dna.list_agents()
+    prompt = dna.agent_prompt("jarvis")
+    hits = dna.search_memories("tenancy invariant", k=3)
+    board = dna.get_board("dna-development", recent=6)
+
+    # Writes are named methods too — no escape hatch needed.
+    dna.remember_memory("a lesson worth keeping", area="ops")
+    dna.delete_memory("s-foo")
+    dna.set_insight_state("i-42", "actioned")
+
+    # Workspace routes are identity-scoped: the boundary comes from the caller's
+    # verified claims, so they never take the client's default scope/tenant.
+    ws = dna.create_workspace("Acme")           # id is minted server-side
+    dna.create_invite(ws["workspace_id"], "teammate@acme.com", role="member")
+```
+
+Routes with security semantics say so in their docstring — e.g.
+`create_project()` is **403** without an active workspace membership, and
+`revoke_workspace_member()` is **409** on the last remaining owner.
+
+A non-2xx response raises `DnaApiError` (carrying `.status` and the API's
+`{"detail": ...}` payload).
+
+## Note on return types
+
+Every DNA REST handler returns an untyped JSON object (`dict[str, Any]`), so the
+OpenAPI **response** schemas are opaque. Request inputs (query/path params) are
+typed; response bodies are `dict[str, Any]`. Tighten the API's response models to
+tighten these.
+
+## Parity
+
+This client and the TypeScript twin are generated from the SAME
+`docs/openapi.json` — spec-parity, not byte-parity. See
+[Using the DNA client](https://ruinosus.github.io/dna/guides/using-the-client/).

dna_client-0.21.1/README.md

@@ -0,0 +1,69 @@
+# dna-client (Python)
+
+The **official Python client for the DNA REST API** (`dna api serve`).
+Spec-parity twin of the TypeScript [`dna-client`](https://www.npmjs.com/package/dna-client):
+both cover the same surface, derived from the same OpenAPI document
+(`docs/openapi.json`, dumped from the FastAPI app) — so consumers stop
+hand-rolling HTTP.
+
+- **Typed inputs**, `httpx`-based, sync, context-manageable.
+- **Complete** — a named method for EVERY operation in the spec, reads and
+  writes alike. `client.request(...)` remains as a low-level escape hatch, but
+  no route depends on it.
+- **Guarded** — a drift test re-dumps the live schema and fails CI if the
+  committed spec is stale, *and* fails if any operation (of any HTTP method)
+  has no named method. Adding a write route cannot pass silently.
+
+## Install
+
+```bash
+pip install dna-client        # or: uv add dna-client
+```
+
+Only runtime dep is `httpx`. Python >= 3.12.
+
+## Usage
+
+```python
+from dna_client import DnaClient
+
+with DnaClient(
+    "http://127.0.0.1:8080",
+    token="…",                 # optional — for --auth token/config
+    scope="dna-development",    # optional default applied to every call
+) as dna:
+    agents = dna.list_agents()
+    prompt = dna.agent_prompt("jarvis")
+    hits = dna.search_memories("tenancy invariant", k=3)
+    board = dna.get_board("dna-development", recent=6)
+
+    # Writes are named methods too — no escape hatch needed.
+    dna.remember_memory("a lesson worth keeping", area="ops")
+    dna.delete_memory("s-foo")
+    dna.set_insight_state("i-42", "actioned")
+
+    # Workspace routes are identity-scoped: the boundary comes from the caller's
+    # verified claims, so they never take the client's default scope/tenant.
+    ws = dna.create_workspace("Acme")           # id is minted server-side
+    dna.create_invite(ws["workspace_id"], "teammate@acme.com", role="member")
+```
+
+Routes with security semantics say so in their docstring — e.g.
+`create_project()` is **403** without an active workspace membership, and
+`revoke_workspace_member()` is **409** on the last remaining owner.
+
+A non-2xx response raises `DnaApiError` (carrying `.status` and the API's
+`{"detail": ...}` payload).
+
+## Note on return types
+
+Every DNA REST handler returns an untyped JSON object (`dict[str, Any]`), so the
+OpenAPI **response** schemas are opaque. Request inputs (query/path params) are
+typed; response bodies are `dict[str, Any]`. Tighten the API's response models to
+tighten these.
+
+## Parity
+
+This client and the TypeScript twin are generated from the SAME
+`docs/openapi.json` — spec-parity, not byte-parity. See
+[Using the DNA client](https://ruinosus.github.io/dna/guides/using-the-client/).

dna_client-0.21.1/dna_client/__init__.py

@@ -0,0 +1,26 @@
+"""``dna_client`` — the official Python client for the **DNA REST read-API**
+(``dna api serve``).
+
+The spec-parity twin of the TypeScript ``dna-client``: both cover the SAME read
+surface, derived from the SAME OpenAPI document (``docs/openapi.json``, dumped
+from the FastAPI app by ``scripts/dump_openapi.py``). The TS client generates its
+types from that spec with ``openapi-typescript``; this Python client is a
+hand-thin ``httpx`` wrapper whose method surface + query params are derived from
+the same spec (a drift test keeps the spec honest against the live routes). The
+two clients stay semantically in sync — spec-parity, not byte-parity.
+
+Read-first: the named methods cover the ``/v1/*`` GET read surface (the shape
+dna-cloud's hand-rolled ``lib/rest-client.ts`` consumes today). The full surface
+— including the few writes — is reachable via :meth:`DnaClient.request`.
+
+NOTE ON RETURN TYPES: every DNA REST handler returns an untyped JSON object
+(``dict[str, Any]``), so the OpenAPI *response* schemas are opaque. Request
+inputs (query/path params) ARE typed here; response bodies are ``dict[str, Any]``
+(documented per method). Tighten the API's response models to tighten these.
+"""
+from __future__ import annotations
+
+from .client import DnaApiError, DnaClient
+
+__all__ = ["DnaClient", "DnaApiError"]
+__version__ = "0.17.0"

dna_client-0.21.1/dna_client/client.py

@@ -0,0 +1,509 @@
+"""The DNA REST API client (sync, ``httpx``-based).
+
+Named methods for the FULL ``/v1/*`` surface — every operation in
+``docs/openapi.json``, reads AND writes. :meth:`DnaClient.request` remains the
+low-level escape hatch, but it is no longer the only way to reach a write.
+Every method returns the API's JSON object (``dict[str, Any]``) and raises
+:class:`DnaApiError` on a non-2xx status.
+
+Coverage is enforced: ``tests/test_openapi_drift.py`` fails if the spec grows an
+operation — of ANY HTTP method — with no named method here.
+"""
+from __future__ import annotations
+
+from typing import Any
+
+import httpx
+
+__all__ = ["DnaClient", "DnaApiError"]
+
+JsonObject = dict[str, Any]
+
+
+class DnaApiError(Exception):
+    """Raised when the DNA REST API responds with a non-2xx status. Carries the
+    HTTP ``status`` and the API's ``{"detail": ...}`` payload (or the raw body)."""
+
+    def __init__(self, status: int, detail: Any) -> None:
+        self.status = status
+        self.detail = detail
+        message = (
+            detail["detail"]
+            if isinstance(detail, dict) and "detail" in detail
+            else f"DNA REST API error (HTTP {status})"
+        )
+        super().__init__(str(message))
+
+
+#: Routes that accept NO ``scope``/``tenant`` query param, so the client-level
+#: defaults must NOT be merged into them, keyed by ``(METHOD, path)``. FastAPI
+#: would silently ignore the stray params, but sending them misrepresents the
+#: route: the workspace boundary is resolved from the caller's VERIFIED identity
+#: (or the body), never from a tenant hint on the query string.
+_NO_SCOPE_TENANT: frozenset[tuple[str, str]] = frozenset(
+    {
+        ("GET", "/health"),
+        # The workspace boundary routes — identity-scoped, not tenant-scoped.
+        ("GET", "/v1/workspaces"),
+        ("POST", "/v1/workspaces"),
+        ("POST", "/v1/workspaces/accept"),
+        ("PUT", "/v1/workspace-plan"),
+        # POST /v1/projects names its workspace in the BODY (decision A1); the
+        # GET on the same path IS scope/tenant-aware, hence the method-keyed set.
+        ("POST", "/v1/projects"),
+    }
+)
+
+
+class DnaClient:
+    """A typed client for the DNA REST API — the full read AND write surface.
+
+    ``base_url`` is a running API, e.g. ``http://127.0.0.1:8080``. ``token`` (for
+    ``--auth token``/``--auth config``) is sent as ``Authorization: Bearer``.
+    ``tenant``/``scope`` are optional defaults merged into every call's query
+    (a per-call value wins). Usable as a context manager (closes the transport).
+
+    >>> with DnaClient("http://127.0.0.1:8080", scope="dna-development") as dna:
+    ...     agents = dna.list_agents()
+    ...     hits = dna.search_memories("tenancy invariant", k=3)
+    """
+
+    def __init__(
+        self,
+        base_url: str,
+        *,
+        token: str | None = None,
+        tenant: str | None = None,
+        scope: str | None = None,
+        timeout: float = 30.0,
+        transport: httpx.BaseTransport | None = None,
+    ) -> None:
+        headers = {"Authorization": f"Bearer {token}"} if token else {}
+        self._default_tenant = tenant
+        self._default_scope = scope
+        self._http = httpx.Client(
+            base_url=base_url.rstrip("/"),
+            headers=headers,
+            timeout=timeout,
+            transport=transport,
+        )
+
+    # -- lifecycle -----------------------------------------------------------
+
+    def close(self) -> None:
+        self._http.close()
+
+    def __enter__(self) -> DnaClient:
+        return self
+
+    def __exit__(self, *exc: object) -> None:
+        self.close()
+
+    # -- low-level (the full surface, incl. writes) --------------------------
+
+    def request(
+        self, method: str, path: str, *, params: dict[str, Any] | None = None,
+        json: Any = None,
+    ) -> JsonObject:
+        """Issue a raw request (the full API surface — reads AND writes). Drops
+        ``None`` query params, merges the client-level default ``scope``/``tenant``
+        when the path accepts them, and raises :class:`DnaApiError` on non-2xx."""
+        query = self._merge_query(method, path, params)
+        resp = self._http.request(method, path, params=query, json=json)
+        if resp.is_success:
+            return resp.json()
+        try:
+            detail: Any = resp.json()
+        except Exception:  # noqa: BLE001 — a non-JSON error body is still an error.
+            detail = resp.text
+        raise DnaApiError(resp.status_code, detail)
+
+    def _get(self, path: str, **params: Any) -> JsonObject:
+        return self.request("GET", path, params=params)
+
+    def _write(
+        self, method: str, path: str, body: JsonObject, **params: Any
+    ) -> JsonObject:
+        """Issue a write, dropping ``None`` body keys so the server's own default
+        (not the client's idea of one) applies to an omitted optional field."""
+        payload = {k: v for k, v in body.items() if v is not None}
+        return self.request(method, path, params=params, json=payload)
+
+    def _merge_query(
+        self, method: str, path: str, params: dict[str, Any] | None
+    ) -> dict[str, Any]:
+        params = dict(params or {})
+        # A `/v1/workspaces/{id}/...` sub-route is identity-scoped like its parent.
+        takes_scope_tenant = (
+            (method.upper(), path) not in _NO_SCOPE_TENANT
+            and not path.startswith("/v1/workspaces/")
+        )
+        if takes_scope_tenant:
+            if self._default_scope is not None and params.get("scope") is None:
+                params["scope"] = self._default_scope
+            # `/v1/tenants/{tid}/...` takes `scope` but NOT `tenant` — the tenant
+            # IS the `tid` path segment, so a default tenant must not shadow it.
+            if (
+                self._default_tenant is not None
+                and params.get("tenant") is None
+                and not path.startswith("/v1/tenants/")
+            ):
+                params["tenant"] = self._default_tenant
+        return {k: v for k, v in params.items() if v is not None}
+
+    # -- health --------------------------------------------------------------
+
+    def health(self) -> JsonObject:
+        """Liveness probe (unauthenticated). Returns ``{"ok": True}``."""
+        return self._get("/health")
+
+    # -- definitions ---------------------------------------------------------
+
+    def list_agents(
+        self, *, scope: str | None = None, tenant: str | None = None
+    ) -> JsonObject:
+        """List a scope's prompt-target agents, tenant-aware."""
+        return self._get("/v1/agents", scope=scope, tenant=tenant)
+
+    def agent_prompt(
+        self, name: str, *, scope: str | None = None, tenant: str | None = None
+    ) -> JsonObject:
+        """Compose one agent's system prompt LIVE (Soul + Guardrails + instruction)."""
+        return self._get(f"/v1/agents/{name}/prompt", scope=scope, tenant=tenant)
+
+    def list_tools(
+        self, *, scope: str | None = None, tenant: str | None = None
+    ) -> JsonObject:
+        """List a scope's Tool Kind surfaces (name + description), tenant-aware."""
+        return self._get("/v1/tools", scope=scope, tenant=tenant)
+
+    # -- memory (reads) ------------------------------------------------------
+
+    def list_memories(
+        self, *, scope: str | None = None, tenant: str | None = None
+    ) -> JsonObject:
+        """List the tenant's memory — base + the tenant's OWN overlay."""
+        return self._get("/v1/memories", scope=scope, tenant=tenant)
+
+    def search_memories(
+        self, q: str, *, k: int = 5, scope: str | None = None,
+        tenant: str | None = None,
+    ) -> JsonObject:
+        """Recall the tenant's memory for ``q`` (hybrid/bi-temporal or lexical)."""
+        return self._get("/v1/memories/search", q=q, k=k, scope=scope, tenant=tenant)
+
+    # -- memory (writes) -----------------------------------------------------
+
+    def remember_memory(
+        self, summary: str, *, area: str = "general", tags: list[str] | None = None,
+        affect: str = "triumph", owner: str = "portal", scope: str | None = None,
+        tenant: str | None = None,
+    ) -> JsonObject:
+        """Persist ONE memory (an ``Engram``) into the tenant's OWN overlay.
+
+        Writes only to the caller's overlay — never the base scope, never another
+        tenant. 400 on a blank ``summary``. The deterministic name it returns is
+        the id :meth:`delete_memory` targets to undo the write."""
+        return self._write(
+            "POST", "/v1/memories",
+            {"summary": summary, "area": area, "tags": tags,
+             "affect": affect, "owner": owner},
+            scope=scope, tenant=tenant,
+        )
+
+    def delete_memory(
+        self, name: str, *, scope: str | None = None, tenant: str | None = None
+    ) -> JsonObject:
+        """Delete ONE memory from the tenant's OWN overlay.
+
+        Refuses anything outside that overlay: a base-scope memory, or another
+        tenant's, is a 404 — the delete cannot reach across the isolation."""
+        return self.request(
+            "DELETE", f"/v1/memories/{name}", params={"scope": scope, "tenant": tenant},
+        )
+
+    # -- intel (reads) -------------------------------------------------------
+
+    def list_sources(
+        self, *, scope: str | None = None, tenant: str | None = None
+    ) -> JsonObject:
+        """List the tenant's watched IntelSource docs (the Direction stage)."""
+        return self._get("/v1/sources", scope=scope, tenant=tenant)
+
+    def list_insights(
+        self, *, scope: str | None = None, tenant: str | None = None,
+        state: str | None = None, source: str | None = None,
+        source_ref: str | None = None,
+    ) -> JsonObject:
+        """List the tenant's IntelInsight docs (ranked), filterable by state/source."""
+        return self._get(
+            "/v1/insights", scope=scope, tenant=tenant, state=state,
+            source=source, source_ref=source_ref,
+        )
+
+    def insight_metrics(
+        self, *, scope: str | None = None, tenant: str | None = None,
+        source_ref: str | None = None,
+    ) -> JsonObject:
+        """The feedback KPIs (precision + noise rate) over the insight stream."""
+        return self._get(
+            "/v1/insights/metrics", scope=scope, tenant=tenant, source_ref=source_ref
+        )
+
+    # -- intel (write) -------------------------------------------------------
+
+    def set_insight_state(
+        self, name: str, state: str, *, scope: str | None = None,
+        tenant: str | None = None,
+    ) -> JsonObject:
+        """Set an insight's feedback state — the reader's disposition.
+
+        ``state`` is one of ``new|actioned|dismissed|snoozed``; anything else is a
+        400. An insight unknown to this (scope, tenant) is a 404."""
+        return self._write(
+            "PATCH", f"/v1/insights/{name}/state", {"state": state},
+            scope=scope, tenant=tenant,
+        )
+
+    # -- portfolio (reads) ---------------------------------------------------
+
+    def list_orgs(
+        self, *, scope: str | None = None, tenant: str | None = None
+    ) -> JsonObject:
+        """List the tenant's Organization docs."""
+        return self._get("/v1/orgs", scope=scope, tenant=tenant)
+
+    def list_projects(
+        self, *, scope: str | None = None, tenant: str | None = None
+    ) -> JsonObject:
+        """List the tenant's Project docs."""
+        return self._get("/v1/projects", scope=scope, tenant=tenant)
+
+    def get_project(
+        self, slug: str, *, scope: str | None = None, tenant: str | None = None
+    ) -> JsonObject:
+        """One project's detail + its RESOLVED repos. 404 → :class:`DnaApiError`."""
+        return self._get(f"/v1/projects/{slug}", scope=scope, tenant=tenant)
+
+    def list_project_members(
+        self, slug: str, *, scope: str | None = None, tenant: str | None = None,
+        viewer: str | None = None,
+    ) -> JsonObject:
+        """List a project's members with their RESOLVED role, tenant-scoped."""
+        return self._get(
+            f"/v1/projects/{slug}/members", scope=scope, tenant=tenant, viewer=viewer
+        )
+
+    def list_repos(
+        self, *, scope: str | None = None, tenant: str | None = None
+    ) -> JsonObject:
+        """List the tenant's Repo docs (code repositories the portfolio references)."""
+        return self._get("/v1/repos", scope=scope, tenant=tenant)
+
+    # -- portfolio (writes) --------------------------------------------------
+
+    def create_project(
+        self, workspace_id: str, name: str, *, slug: str | None = None,
+        claims: dict[str, Any] | None = None,
+    ) -> JsonObject:
+        """Create a Project inside ``workspace_id``.
+
+        SECURITY: the caller must hold an ACTIVE ``WorkspaceMembership`` in that
+        workspace — a caller without one is **403**, and a pending invite does not
+        count. The write scope and the project's ``board_scope`` are DERIVED from
+        the workspace + slug; the route refuses to accept either from the caller.
+        400 on a blank ``workspace_id``/``name``.
+
+        ``claims`` is the caller's identity for a trusted server-side call under
+        ``--auth none``/``--auth token``. Under ``--auth config`` the VERIFIED
+        token claims always win and this argument is ignored."""
+        return self._write(
+            "POST", "/v1/projects",
+            {"workspace_id": workspace_id, "name": name, "slug": slug,
+             "claims": claims},
+        )
+
+    def set_project_member(
+        self, slug: str, user: str, role: str, *, actor: str | None = None,
+        scope: str | None = None, tenant: str | None = None,
+    ) -> JsonObject:
+        """Invite / set a user's PROJECT-scope role (upserts one Membership doc).
+
+        SECURITY: ``actor`` must be Owner/Admin of the project or its org, and only
+        an Owner may grant ``owner`` — **403** otherwise. 404 for an unknown
+        project; 422 for an unknown role."""
+        return self._write(
+            "POST", f"/v1/projects/{slug}/members",
+            {"user": user, "role": role, "actor": actor},
+            scope=scope, tenant=tenant,
+        )
+
+    def remove_project_member(
+        self, slug: str, user: str, *, actor: str | None = None,
+        scope: str | None = None, tenant: str | None = None,
+    ) -> JsonObject:
+        """Remove a user's PROJECT-scope grant.
+
+        SECURITY: ``actor`` must be Owner/Admin, and removing an Owner requires
+        Owner — **403** otherwise. Deletes ONLY the project-scope grant; an
+        inherited org-scope grant is untouched (the user may still resolve to a
+        role afterwards). 404 when the user holds no project grant here."""
+        return self.request(
+            "DELETE", f"/v1/projects/{slug}/members/{user}",
+            params={"actor": actor, "scope": scope, "tenant": tenant},
+        )
+
+    def provision_tenant_owner(
+        self, tid: str, user: str, *, scope: str | None = None
+    ) -> JsonObject:
+        """First-owner bootstrap: make ``user`` Owner of tenant ``tid`` when it has
+        no Owner yet (org- + project-scope grants).
+
+        SECURITY: FIRST-owner only and idempotent — once ANY Owner exists this is a
+        no-op, so a later user cannot auto-escalate into an established tenant.
+        This is a trusted server-side call (the portal's shared bearer), not a
+        user-facing one. 400 on a missing tenant/user."""
+        return self._write(
+            "POST", f"/v1/tenants/{tid}/provision-owner", {"user": user}, scope=scope,
+        )
+
+    # -- board (reads) -------------------------------------------------------
+
+    def get_board(
+        self, scope: str, *, tenant: str | None = None, recent: int = 6
+    ) -> JsonObject:
+        """A compact SDLC summary for a project's ``board_scope``."""
+        return self._get("/v1/board", scope=scope, tenant=tenant, recent=recent)
+
+    def get_board_item(
+        self, scope: str, name: str, *, tenant: str | None = None,
+        kind: str | None = None,
+    ) -> JsonObject:
+        """One board work-item's FULL doc (the console's item-detail drawer)."""
+        return self._get(
+            "/v1/board/item", scope=scope, name=name, tenant=tenant, kind=kind
+        )
+
+    # -- workspaces (read) ---------------------------------------------------
+
+    def list_workspaces(
+        self, *, actor_oid: str | None = None, actor_email: str | None = None,
+    ) -> JsonObject:
+        """The workspaces the caller holds an ACTIVE membership in.
+
+        Enumerates by membership, never by tenant provenance: a pending invite
+        does not appear, and an unknown identity gets an empty list rather than
+        somebody else's. This is the data source a workspace switcher builds on."""
+        return self._get(
+            "/v1/workspaces", actor_oid=actor_oid, actor_email=actor_email,
+        )
+
+    def list_workspace_members(
+        self, workspace_id: str, *, actor_oid: str | None = None,
+        actor_email: str | None = None,
+    ) -> JsonObject:
+        """List a workspace's members (grants). RBAC: the actor must be Owner/Admin."""
+        return self._get(
+            f"/v1/workspaces/{workspace_id}/members",
+            actor_oid=actor_oid, actor_email=actor_email,
+        )
+
+    # -- workspaces (writes) -------------------------------------------------
+    # Every route below is identity-scoped: the boundary is resolved from the
+    # caller's VERIFIED claims, never from a `tenant` query hint. Under
+    # `--auth config` the token's claims WIN over any `claims`/`actor` argument
+    # here; those arguments exist for a TRUSTED server-side caller running the API
+    # under `--auth none`/`--auth token` (the portal, holding the shared bearer).
+
+    def create_workspace(
+        self, name: str, *, slug: str | None = None,
+        claims: dict[str, Any] | None = None,
+    ) -> JsonObject:
+        """Create a workspace and its first OWNER, in one call.
+
+        SECURITY: the ``workspace_id`` is MINTED SERVER-SIDE and cannot be supplied
+        — there is deliberately no field for it, so a caller cannot name a
+        workspace into existence and race its real owner for it. The caller's
+        verified identity becomes the active owner. ``slug`` defaults to a
+        slugified ``name`` and is made unique. 400 on a blank name or a missing
+        oid/email claim."""
+        return self._write(
+            "POST", "/v1/workspaces",
+            {"name": name, "slug": slug, "claims": claims},
+        )
+
+    def create_invite(
+        self, workspace_id: str, email: str, *, role: str = "member",
+        actor: dict[str, Any] | None = None,
+    ) -> JsonObject:
+        """Invite an identity (by email) into a workspace — a ``pending``
+        ``WorkspaceMembership`` that only :meth:`accept_invites` can activate.
+
+        SECURITY: the actor must be Owner/Admin of the workspace, and only an
+        Owner may invite an Owner — **403** otherwise. 422 on an unknown role."""
+        return self._write(
+            "POST", f"/v1/workspaces/{workspace_id}/invites",
+            {"email": email, "role": role, "actor": actor},
+        )
+
+    def accept_invites(self, *, claims: dict[str, Any] | None = None) -> JsonObject:
+        """Accept EVERY pending invite matching the caller's verified sign-in
+        claims — binds the durable ``oid`` and flips ``pending`` → ``active``.
+
+        SECURITY: matches on a VERIFIED email claim only, and refuses to hijack a
+        grant already bound to a different ``oid``. Takes no workspace argument by
+        design: a caller cannot accept an invite that was not addressed to them."""
+        return self._write("POST", "/v1/workspaces/accept", {"claims": claims})
+
+    def provision_workspace_owner(
+        self, workspace_id: str, *, claims: dict[str, Any] | None = None
+    ) -> JsonObject:
+        """Reconcile the verified identity's membership in ``workspace_id`` — the
+        portal's every-sign-in idempotent no-op.
+
+        SECURITY: since decision **D5** this CREATES NOTHING. It REQUIRES an
+        existing ACTIVE ``WorkspaceMembership`` and merely returns it (back-filling
+        a missing Workspace identity doc for an owner). A caller holding no active
+        membership here — a stranger included — is **403**. To create a workspace
+        use :meth:`create_workspace`, which mints its own id. 400 on a missing
+        oid/email claim."""
+        return self._write(
+            "POST", f"/v1/workspaces/{workspace_id}/provision-owner",
+            {"claims": claims},
+        )
+
+    def revoke_workspace_member(
+        self, workspace_id: str, *, target_email: str | None = None,
+        target_oid: str | None = None, actor: dict[str, Any] | None = None,
+    ) -> JsonObject:
+        """Revoke (remove) a member's ``WorkspaceMembership``.
+
+        SECURITY: the actor must be Owner/Admin — **403** otherwise. The LAST
+        remaining owner can NEVER be revoked (**409**, fail-closed), so a workspace
+        cannot be orphaned. A target holding no grant here is 404. Name the target
+        by ``target_email`` or ``target_oid`` (oid wins when both are given)."""
+        return self._write(
+            "POST", f"/v1/workspaces/{workspace_id}/members/revoke",
+            {"target_email": target_email, "target_oid": target_oid, "actor": actor},
+        )
+
+    # -- billing (write) -----------------------------------------------------
+
+    def set_workspace_plan(
+        self, workspace_id: str, tier_id: str, *, source: str = "stripe",
+        stripe_customer_id: str | None = None,
+        stripe_subscription_id: str | None = None, status: str | None = None,
+    ) -> JsonObject:
+        """Upsert the ``WorkspacePlan`` assigning ``workspace_id`` → ``tier_id`` —
+        the billing→enforcement bridge.
+
+        SECURITY: this route ASSIGNS a plan and performs no membership check of its
+        own; it is a trusted server-side call (the portal's Stripe webhook handler,
+        holding the shared bearer) and must never be exposed to an end user.
+        Idempotent under Stripe retries. 400 on a missing workspace_id/tier_id."""
+        return self._write(
+            "PUT", "/v1/workspace-plan",
+            {"workspace_id": workspace_id, "tier_id": tier_id, "source": source,
+             "stripe_customer_id": stripe_customer_id,
+             "stripe_subscription_id": stripe_subscription_id, "status": status},
+        )

dna_client-0.21.1/pyproject.toml

@@ -0,0 +1,54 @@
+[project]
+name = "dna-client"
+version = "0.21.1"
+description = "DNA — Official Python client for the DNA REST read-API (spec-parity twin of the TypeScript dna-client)"
+readme = "README.md"
+license = "MIT"
+keywords = ["dna", "client", "rest", "openapi", "typed", "agents", "sdlc"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Typing :: Typed",
+]
+# 3.12 floor — tracks dna-sdk / dna-cli (see packages/sdk-py/pyproject.toml).
+requires-python = ">=3.12,<3.14"
+dependencies = [
+    "httpx>=0.27",
+]
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=8.0",
+    # The OpenAPI drift test (tests/test_openapi_drift.py) re-dumps the live
+    # FastAPI schema via scripts/dump_openapi.py and diffs it against the
+    # committed docs/openapi.json — so it needs the REST API face importable.
+    # Resolved from the sibling packages via [tool.uv.sources] below (editable).
+    "dna-cli[api]",
+]
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["dna_client"]
+
+# Dev-workspace override: inside this repo, uv resolves dna-cli + dna-sdk from
+# the sibling packages (editable) for the drift test — NOT from PyPI. The
+# published wheel carries ONLY the httpx runtime dep (the drift test is a repo
+# dev tool, never shipped).
+[tool.uv.sources]
+dna-cli = { path = "../cli", editable = true }
+dna-sdk = { path = "../sdk-py", editable = true }
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+
+[project.urls]
+Homepage = "https://ruinosus.github.io/dna/"
+Repository = "https://github.com/ruinosus/dna"
+Documentation = "https://ruinosus.github.io/dna/guides/using-the-client/"
+Changelog = "https://github.com/ruinosus/dna/blob/main/CHANGELOG.md"
+Issues = "https://github.com/ruinosus/dna/issues"

dna_client-0.21.1/tests/test_client.py

@@ -0,0 +1,198 @@
+"""Usage test for the DNA REST Python client — drives the named read methods
+against an ``httpx.MockTransport`` (no live server), asserting method, URL, path
+substitution, query params (incl. client-level defaults), the bearer header, and
+that it unwraps success + raises :class:`DnaApiError` on a non-2xx.
+"""
+from __future__ import annotations
+
+import json
+
+import httpx
+import pytest
+
+from dna_client import DnaApiError, DnaClient
+
+
+def _recorder(body: object, status: int = 200):
+    """A MockTransport that records each request and returns a canned JSON body."""
+    calls: list[httpx.Request] = []
+
+    def handler(request: httpx.Request) -> httpx.Response:
+        calls.append(request)
+        return httpx.Response(status, json=body)
+
+    return httpx.MockTransport(handler), calls
+
+
+BASE = "http://dna.test"
+
+
+def test_health_unwraps_body():
+    transport, calls = _recorder({"ok": True})
+    with DnaClient(BASE, transport=transport) as dna:
+        assert dna.health() == {"ok": True}
+    assert calls[0].url.path == "/health"
+
+
+def test_bearer_token_sent():
+    transport, calls = _recorder({"agents": []})
+    with DnaClient(BASE, token="sekret", transport=transport) as dna:
+        dna.list_agents(scope="s")
+    assert calls[0].headers["authorization"] == "Bearer sekret"
+
+
+def test_scope_tenant_query_params():
+    transport, calls = _recorder({"agents": []})
+    with DnaClient(BASE, transport=transport) as dna:
+        dna.list_agents(scope="dna-development", tenant="acme")
+    url = calls[0].url
+    assert url.path == "/v1/agents"
+    assert url.params["scope"] == "dna-development"
+    assert url.params["tenant"] == "acme"
+
+
+def test_client_defaults_apply_and_per_call_overrides_win():
+    transport, calls = _recorder({"memories": []})
+    with DnaClient(BASE, tenant="acme", scope="base", transport=transport) as dna:
+        dna.list_memories()               # uses defaults
+        dna.list_memories(tenant="other")  # overrides tenant
+    assert calls[0].url.params["tenant"] == "acme"
+    assert calls[0].url.params["scope"] == "base"
+    assert calls[1].url.params["tenant"] == "other"
+    assert calls[1].url.params["scope"] == "base"
+
+
+def test_none_params_are_dropped():
+    transport, calls = _recorder({"agents": []})
+    with DnaClient(BASE, transport=transport) as dna:
+        dna.list_agents()  # no scope/tenant/defaults → empty query
+    assert str(calls[0].url) == f"{BASE}/v1/agents"
+
+
+def test_path_substitution_and_typed_query():
+    transport, calls = _recorder({"ok": 1})
+    with DnaClient(BASE, transport=transport) as dna:
+        dna.agent_prompt("jarvis", scope="s")
+        dna.get_project("my-proj")
+        dna.search_memories("hello", k=3)
+        dna.get_board("dna-development", recent=5)
+        dna.get_board_item("dna-development", "s-foo")
+    assert calls[0].url.path == "/v1/agents/jarvis/prompt"
+    assert calls[1].url.path == "/v1/projects/my-proj"
+    assert calls[2].url.path == "/v1/memories/search"
+    assert calls[2].url.params["q"] == "hello"
+    assert calls[2].url.params["k"] == "3"
+    assert calls[3].url.params["recent"] == "5"
+    assert calls[4].url.params["name"] == "s-foo"
+
+
+def test_workspace_members_no_scope_tenant_default():
+    # /v1/workspaces/* boundary routes do NOT take scope/tenant — the client
+    # must not inject its defaults there.
+    transport, calls = _recorder({"members": []})
+    with DnaClient(BASE, tenant="acme", scope="base", transport=transport) as dna:
+        dna.list_workspace_members("ws-1", actor_email="a@b.com")
+    url = calls[0].url
+    assert url.path == "/v1/workspaces/ws-1/members"
+    assert "tenant" not in url.params
+    assert "scope" not in url.params
+    assert url.params["actor_email"] == "a@b.com"
+
+
+def test_non_2xx_raises_dna_api_error():
+    transport, _ = _recorder({"detail": "unknown project 'nope'"}, status=404)
+    with DnaClient(BASE, transport=transport) as dna:
+        with pytest.raises(DnaApiError) as exc:
+            dna.get_project("nope")
+    assert exc.value.status == 404
+    assert "unknown project" in str(exc.value)
+
+
+def test_request_reaches_full_surface_incl_writes():
+    transport, calls = _recorder({"deleted": "s-foo"})
+    with DnaClient(BASE, transport=transport) as dna:
+        out = dna.request("DELETE", "/v1/memories/s-foo", params={"tenant": "acme"})
+    assert out == {"deleted": "s-foo"}
+    assert calls[0].method == "DELETE"
+    assert calls[0].url.path == "/v1/memories/s-foo"
+    assert calls[0].url.params["tenant"] == "acme"
+
+
+# -- the named write surface -------------------------------------------------
+
+
+def test_named_writes_use_the_right_verb_and_path():
+    transport, calls = _recorder({"ok": 1})
+    with DnaClient(BASE, transport=transport) as dna:
+        dna.remember_memory("a lesson", scope="s")
+        dna.delete_memory("s-foo", scope="s")
+        dna.set_insight_state("i-1", "dismissed")
+        dna.set_workspace_plan("w1", "pro")
+        dna.revoke_workspace_member("w1", target_email="a@b.c")
+        dna.remove_project_member("proj", "user@x.y", actor="boss@x.y")
+    seen = [(c.method, c.url.path) for c in calls]
+    assert seen == [
+        ("POST", "/v1/memories"),
+        ("DELETE", "/v1/memories/s-foo"),
+        ("PATCH", "/v1/insights/i-1/state"),
+        ("PUT", "/v1/workspace-plan"),
+        ("POST", "/v1/workspaces/w1/members/revoke"),
+        ("DELETE", "/v1/projects/proj/members/user@x.y"),
+    ]
+
+
+def test_write_body_drops_none_so_server_defaults_apply():
+    transport, calls = _recorder({"ok": 1})
+    with DnaClient(BASE, transport=transport) as dna:
+        dna.create_workspace("Acme")  # slug + claims omitted
+    body = json.loads(calls[0].content)
+    assert body == {"name": "Acme"}, "None-valued optional keys must not be sent"
+
+
+def test_write_body_carries_explicit_values():
+    transport, calls = _recorder({"ok": 1})
+    with DnaClient(BASE, transport=transport) as dna:
+        dna.remember_memory("a lesson", area="ops", tags=["x"], affect="scar")
+    body = json.loads(calls[0].content)
+    assert body == {
+        "summary": "a lesson", "area": "ops", "tags": ["x"],
+        "affect": "scar", "owner": "portal",
+    }
+
+
+def test_workspace_boundary_writes_get_no_scope_tenant_default():
+    # The workspace boundary is resolved from the caller's VERIFIED identity, so a
+    # client-level tenant default must never leak onto these routes and imply the
+    # caller may choose their own boundary.
+    transport, calls = _recorder({"ok": 1})
+    with DnaClient(BASE, tenant="acme", scope="base", transport=transport) as dna:
+        dna.list_workspaces()
+        dna.create_workspace("Acme")
+        dna.accept_invites()
+        dna.create_project("w1", "P")
+        dna.create_invite("w1", "a@b.c")
+        dna.provision_workspace_owner("w1")
+        dna.set_workspace_plan("w1", "pro")
+    for call in calls:
+        assert "tenant" not in call.url.params, f"tenant leaked onto {call.url.path}"
+        assert "scope" not in call.url.params, f"scope leaked onto {call.url.path}"
+
+
+def test_scope_tenant_defaults_still_reach_the_scoped_writes():
+    transport, calls = _recorder({"ok": 1})
+    with DnaClient(BASE, tenant="acme", scope="base", transport=transport) as dna:
+        dna.remember_memory("x")
+        dna.set_project_member("proj", "u@x.y", "admin")
+    for call in calls:
+        assert call.url.params["tenant"] == "acme"
+        assert call.url.params["scope"] == "base"
+
+
+def test_provision_tenant_owner_takes_scope_but_never_tenant():
+    # The tenant IS the {tid} path segment — a default tenant must not shadow it.
+    transport, calls = _recorder({"ok": 1})
+    with DnaClient(BASE, tenant="acme", scope="base", transport=transport) as dna:
+        dna.provision_tenant_owner("tid-1", "u@x.y")
+    assert calls[0].url.path == "/v1/tenants/tid-1/provision-owner"
+    assert calls[0].url.params["scope"] == "base"
+    assert "tenant" not in calls[0].url.params

dna_client-0.21.1/tests/test_openapi_drift.py

@@ -0,0 +1,172 @@
+"""OpenAPI drift guard — keeps the committed generation source in sync with the
+live DNA REST API.
+
+The clients (``packages/client-ts`` + ``packages/client-py``) are generated from
+``docs/openapi.json``, which is dumped from the FastAPI app by
+``scripts/dump_openapi.py``. If a route/param changes and nobody re-dumps the
+spec, the clients silently drift from the API. This test re-dumps the schema from
+the live app and asserts it equals the committed file — so a stale spec fails CI
+with a clear "run `python scripts/dump_openapi.py`" message.
+
+The second half of this module is the COVERAGE guard: every operation in the
+spec — of any HTTP method — must have a named method on the client. See the
+``_COVERED`` comment for why it is keyed by ``(method, path)`` rather than by
+path, and why the read-only version of this guard was a blind spot.
+
+It needs the REST API face importable (``dna-cli[api]`` + ``dna-sdk``); when
+those are absent (a minimal ``pip install dna-client`` with no dev extras) it
+SKIPS rather than fails, so the published package's own install never depends on
+the repo. CI installs the dev extra, so the guard runs for real there.
+"""
+from __future__ import annotations
+
+import sys
+from pathlib import Path
+
+import pytest
+
+# Repo root = packages/client-py/tests/ → up 3. scripts/ + docs/openapi.json live there.
+_REPO_ROOT = Path(__file__).resolve().parents[3]
+_SCRIPTS = _REPO_ROOT / "scripts"
+_SPEC = _REPO_ROOT / "docs" / "openapi.json"
+
+if str(_SCRIPTS) not in sys.path:
+    sys.path.insert(0, str(_SCRIPTS))
+
+
+def _load_dumper():
+    """Import scripts/dump_openapi.py, skipping if the REST API face is absent."""
+    pytest.importorskip(
+        "fastapi",
+        reason="the drift test needs the REST API face — install dna-client[dev] "
+        "(pulls dna-cli[api] + dna-sdk).",
+    )
+    pytest.importorskip("dna_cli._rest_api", reason="dna-cli not importable")
+    import dump_openapi  # noqa: WPS433 — repo dev script on sys.path
+
+    return dump_openapi
+
+
+def test_committed_openapi_matches_live_api():
+    dump_openapi = _load_dumper()
+    assert _SPEC.exists(), f"missing committed spec: {_SPEC}"
+    committed = _SPEC.read_text(encoding="utf-8")
+    live = dump_openapi.dump()
+    assert committed == live, (
+        "docs/openapi.json is stale — the DNA REST API changed without "
+        "regenerating the client spec. Run `python scripts/dump_openapi.py` "
+        "(and `cd packages/client-ts && bun run gen`), then commit."
+    )
+
+
+# ---------------------------------------------------------------------------
+# Operation coverage — EVERY operation, not just the reads.
+#
+# This map is keyed by ``(HTTP METHOD, path)``, not by path, and is checked
+# against every operation in the spec. That is deliberate: the previous version
+# of this guard enumerated GET paths only and declared writes out of scope
+# ("writes stay behind .request"), so a new write route entered the spec, the
+# API and CI in total silence — which is exactly how POST /v1/workspaces and
+# POST /v1/projects shipped with no client coverage at all. A guard that only
+# watches the surface you already covered is not a guard.
+#
+# Adding an operation to the API now REQUIRES either a named client method here
+# or an explicit, justified entry in _UNCOVERED below.
+_COVERED: dict[tuple[str, str], str] = {
+    # -- reads ---------------------------------------------------------------
+    ("GET", "/health"): "health",
+    ("GET", "/v1/agents"): "list_agents",
+    ("GET", "/v1/agents/{name}/prompt"): "agent_prompt",
+    ("GET", "/v1/tools"): "list_tools",
+    ("GET", "/v1/memories"): "list_memories",
+    ("GET", "/v1/memories/search"): "search_memories",
+    ("GET", "/v1/sources"): "list_sources",
+    ("GET", "/v1/insights"): "list_insights",
+    ("GET", "/v1/insights/metrics"): "insight_metrics",
+    ("GET", "/v1/orgs"): "list_orgs",
+    ("GET", "/v1/projects"): "list_projects",
+    ("GET", "/v1/projects/{slug}"): "get_project",
+    ("GET", "/v1/projects/{slug}/members"): "list_project_members",
+    ("GET", "/v1/repos"): "list_repos",
+    ("GET", "/v1/board"): "get_board",
+    ("GET", "/v1/board/item"): "get_board_item",
+    ("GET", "/v1/workspaces"): "list_workspaces",
+    ("GET", "/v1/workspaces/{workspace_id}/members"): "list_workspace_members",
+    # -- writes --------------------------------------------------------------
+    ("POST", "/v1/memories"): "remember_memory",
+    ("DELETE", "/v1/memories/{name}"): "delete_memory",
+    ("PATCH", "/v1/insights/{name}/state"): "set_insight_state",
+    ("POST", "/v1/projects"): "create_project",
+    ("POST", "/v1/projects/{slug}/members"): "set_project_member",
+    ("DELETE", "/v1/projects/{slug}/members/{user}"): "remove_project_member",
+    ("POST", "/v1/tenants/{tid}/provision-owner"): "provision_tenant_owner",
+    ("PUT", "/v1/workspace-plan"): "set_workspace_plan",
+    ("POST", "/v1/workspaces"): "create_workspace",
+    ("POST", "/v1/workspaces/accept"): "accept_invites",
+    ("POST", "/v1/workspaces/{workspace_id}/invites"): "create_invite",
+    ("POST", "/v1/workspaces/{workspace_id}/members/revoke"): "revoke_workspace_member",
+    ("POST", "/v1/workspaces/{workspace_id}/provision-owner"): "provision_workspace_owner",
+}
+
+# Operations DELIBERATELY left without a named client method. Each entry needs a
+# comment saying WHY — "it's a write" is not a reason. Empty today: every one of
+# the spec's 31 operations is a single, self-contained call that a named method
+# can honestly express. An operation belongs here only if a named method would
+# LIE about how usable it is (e.g. it needs a multi-step handshake, or a
+# credential the client has no way to hold).
+_UNCOVERED: dict[tuple[str, str], str] = {}
+
+# HTTP methods that carry an operation (OpenAPI path items also hold non-operation
+# keys such as "parameters" / "summary", which must not be mistaken for one).
+_HTTP_METHODS = frozenset(
+    {"get", "put", "post", "delete", "options", "head", "patch", "trace"}
+)
+
+
+def _spec_operations(schema: dict) -> set[tuple[str, str]]:
+    """Every ``(METHOD, path)`` operation in the OpenAPI document."""
+    return {
+        (method.upper(), path)
+        for path, item in schema["paths"].items()
+        for method in item
+        if method.lower() in _HTTP_METHODS
+    }
+
+
+def test_client_covers_every_operation():
+    """EVERY operation in the spec — read or write — must have a named method on
+    the client, or an explicit justified entry in ``_UNCOVERED``."""
+    dump_openapi = _load_dumper()
+    from dna_client import DnaClient
+
+    operations = _spec_operations(dump_openapi.build_schema())
+
+    uncovered = operations - _COVERED.keys() - _UNCOVERED.keys()
+    assert not uncovered, (
+        "operation(s) in the API with no named client method: "
+        f"{sorted(uncovered)} — add a named method to dna_client/client.py and "
+        "map it in _COVERED, or, if it genuinely should not have one, add it to "
+        "_UNCOVERED with the reason. Do NOT leave it to `.request`."
+    )
+
+    for (verb, path), name in _COVERED.items():
+        assert hasattr(DnaClient, name), f"client missing {name}() for {verb} {path}"
+
+
+def test_coverage_map_has_no_stale_entries():
+    """The maps must not outlive the spec — a removed route has to be removed here
+    too, else the guard silently protects an operation that no longer exists."""
+    dump_openapi = _load_dumper()
+    operations = _spec_operations(dump_openapi.build_schema())
+
+    stale = (_COVERED.keys() | _UNCOVERED.keys()) - operations
+    assert not stale, (
+        f"coverage map lists operation(s) absent from the spec: {sorted(stale)} "
+        "— the route was removed/renamed; drop the entry (and its client method)."
+    )
+
+
+def test_every_uncovered_entry_states_a_reason():
+    """An allowlist without reasons decays into a dumping ground."""
+    for key, reason in _UNCOVERED.items():
+        assert reason and reason.strip(), f"_UNCOVERED[{key}] needs a stated reason"