cortexdb-mcp 0.8.0__tar.gz → 0.9.0__tar.gz

cortexdb_mcp-0.9.0/COVERAGE.md

@@ -0,0 +1,149 @@
+# cortexdb-mcp coverage of CortexDB 0.14.0
+
+This file records how `cortexdb-mcp` (the stdio MCP server in this directory) covers the CortexDB 0.14.0 API: the
+audit of every tool that existed before 0.14.0, and what each finding changed. The spec, in order of authority:
+the server code (the `sharedcontext` branch with lanes p5g, p5h and p5j merged), `docs/schemas/openapi.json`,
+`docs/shared_memory/IDENTITY_AND_API_CONTRACT.md` with `docs/API_REFERENCE_V1.md`, and the release-notes drafts
+`docs/shared_memory/PHASE{0..5}_RELEASE_NOTES_DRAFT.md`.
+
+The server's own HTTP MCP endpoint (`POST /mcp`, `crates/cortex-api/src/v1/mcp.rs`, `CORTEX_MCP=on`) is a separate
+surface with its own five tools. The stdio server keeps today's tools, output shapes and default profile (design
+§13.8, §14.3); the tools it adds follow `/mcp`'s rule, read by default and writes opt-in.
+
+## What 0.14.0 breaks, and what it did to the tools
+
+| 0.14.0 change | Tools it reached | What happened before 0.9.0 | Now |
+|---|---|---|---|
+| **Strict forget and erasure selectors**: a selector field a route does not apply is 422 `unknown_selector_field`, a misspelt layer `unknown_layer`, and the erasure routes refuse the key selectors | `memory_forget`, `memory_delete`, `memory_bulk_delete`, `forget_preview` | Their bodies were valid (only `about_subject`, `memory_ids`, `cascade`, `reason`, `confirm_all`, `from_preview_id`). The same class of mistake was open one level up: FastMCP drops an argument a tool does not take, so `memory_forget(reason, memory_ids=[…])` dropped the ids and forgot the whole scope's derived records | Every body is checked against the strict rules in the tests (`test_audit.py::test_the_bodies_pass_the_strict_selector`). Every tool refuses an argument it does not take, naming it and listing the ones it does (`additionalProperties: false` in each schema), as the server refuses a field it does not apply and `/mcp` refuses one on its destructive tools |
+| **`/v1/forget` cascades**: a forget that names no cascade runs `derived_only`, which deletes derived records only; a whole-scope forget under it deletes no memory and says so in `warnings` | `memory_forget`, `memory_bulk_delete` | `memory_forget` said a call without `query` "deletes everything under the scope"; `memory_bulk_delete` said it deletes "multiple memories" and reported `0 event(s) removed`. The server's `warnings` were dropped | The descriptions say what is deleted (derived records) and what is KEPT (the events), and point to `memory_delete` and `forget_by_key` for memories. Every forget answer lists its derived counts, `requested` and `matched`, its audit id and the server's warnings |
+| **Total confinement**: a token that carries `scopes` holds only the families its entries name (403 `POLICY_DENIED`, `details.link: "confinement"`, `details.capability`) | every tool | A refusal surfaced as `CortexDB returned HTTP 403: {raw json}` | Every refusal is a typed `CortexDBError`: code, retriable, request id, and for a confinement refusal the capability and the `scopes` entry to mint (`<capability>:<scope>`, `<scope>/*`, `<capability>:*`), with the view hint for `scope.read.holistic` and `scope.read.descend`. A signup token names its 18 families, so every tool still works inside the signup user's own subtrees |
+| **Break-glass**: on `cloud_shared_saas` the operator key's data reads (and its in-band writes) are 403 `BREAK_GLASS_REQUIRED` without `X-Cortex-Break-Glass` | every read tool, `memory_forget`/`memory_bulk_delete`/`forget_preview` by query, the insights engine | Nothing could send the header; the insights engine answered "no insights" to the refusal | `CORTEXDB_BREAK_GLASS_REASON`, `_TICKET` and `_NOTE` send it, validated as the server validates it; `BREAK_GLASS_REQUIRED` says to use a person's token or set the two settings. A forget or preview by ids or keys needs none (it reads nothing first) |
+| **`tree.display_name` refused** in version-1 registry writes (422 `INVALID_SCOPE_TREE`) | none: no tool registers scopes | `cortexdb_check_call` did not know `POST /v1/scopes` or `PUT /v1/scopes/tree` | `cortexdb_check_call` flags `tree.display_name` there and points to `PUT /v1/directory/{id}` |
+| **Org trees' views**: at a shared org-tree scope (org, team, group, compartment) a walking view is 422 `VIEW_NOT_ALLOWED_AT_SCOPE`, and a recall naming no view reads granular | `memory_search`, `get_context`, `advanced_search` | They always sent `view` (the default holistic by name), so every search at a team scope was refused | `view` is sent only when `CORTEXDB_VIEW` is set; otherwise the server picks (holistic elsewhere, as before, granular at a shared scope) |
+| **Agent writes redirected** (DB-28): a non-human chain's write whose read record is unknown, tainted or carries a private atom lands in its writer's private space, `redirected_to` | `memory_store`, `entity_link`, `belief_declare` | The receipt's `redirected_to` was dropped: the agent was told it stored at the scope it asked for | The answer names where it landed |
+| **Per-person and chain tokens**: a minted token needs `X-Cortex-Actor` equal to its `sub`; an issuers-file token in `prefix`, `hash` or `directory` mode goes alone | every tool | A minted token without `CORTEXDB_ACTOR` was 401 `ACTOR_MISMATCH` on every call | `X-Cortex-Actor` is read from a PASETO or JWT bearer whose `sub` is an actor id, left out for an IdP subject, and `CORTEXDB_ACTOR=-` sends none |
+
+## The audit, tool by tool
+
+"Request" is the body or query the tool sends, checked against the route's handler; "output" the fields it reads;
+"errors" what the agent sees on a refusal. Every tool's errors are the typed errors above, so the column names only
+what is particular to the tool.
+
+| Tool | Route | Request | Output | Errors | Changed in 0.9.0 |
+|---|---|---|---|---|---|
+| `cortexdb_check_call` | none (a static contract) | — | — | — | Knows the strict forget body and selector (`unknown_selector_field`, `unknown_layer`, unknown top-level fields), the key selectors and their bounds, the erasure routes' refusals (`key_selector_not_supported`, `UNSUPPORTED_SELECTOR`, `confirm` without `subject`), `tree.display_name`, and the new routes (access check and explain, rollups, publish, notices, the directory) |
+| `memory_store` | `POST /v1/experience` | ok | dropped `redirected_to`, `replayed_from_idempotency`, `warnings` | `RUN_REQUIRED`, `ATOMS_REDIRECT_REFUSED`, confinement | names a redirect, a replay and the server's warnings |
+| `memory_status` | `GET /v1/experience/status` | ok | ignored the server's `resend` and `note`: claimed "re-storing is safe" for every not-found answer, where by event id the server answers `check_first` (erased, forgotten or not visible: do not re-send); said "indexing in progress" for a cancelled write | — | renders `resend` and `note`; takes `tenant_id` (`?scope=`, the alignment pass below) |
+| `memory_search`, `get_context`, `advanced_search` | `POST /v1/recall` | `view` always sent (see above) | ok | `VIEW_NOT_ALLOWED_AT_SCOPE`, confinement of `scope.read.holistic` | `view` only when set |
+| `memory_forget` | `POST /v1/forget` | ok | dropped `warnings`; the description was wrong (see above) | `BREAK_GLASS_REQUIRED` for a query under `deny` | accurate description, warnings, counts |
+| `forget_preview` | `POST /v1/forget/preview` | ok | told the agent to execute a `memory_ids` preview with `memory_forget`, which takes no ids | — | names the tool that sends exactly the previewed selector (`memory_delete` for one id, which now takes `from_preview_id`) and shows `requested`/`matched` |
+| `memory_list` | `GET /v1/events` | sent `offset` as a numeric `cursor`, which the final server refuses (422 `INVALID_CURSOR`: its cursor is `le1.`, newest first, bound to the query) | dropped `next_cursor` | `INVALID_CURSOR` | pages by `cursor` (`offset` is gone) and ends a page with `More: cursor=`; a type is filtered by the server (`labels`), the default type here |
+| `memory_get` | `GET /v1/events/{id}` | ignored `tenant_id`, the exact scope `?scope=` confines the read to, which a cluster routes a by-id read by (a break-glass by-id read without it was 503 `NOTICE_UNAVAILABLE` `scope_unnamed` until the final 0.14.0 server, which decides it by the row's own scope) | ok | `NOTICE_UNAVAILABLE` | sends `tenant_id` as `?scope=` (the event's exact scope) when given |
+| `memory_delete` | `POST /v1/forget` (`memory_ids`) | ok | dropped `matched` and `warnings` (an id stored elsewhere answers `matched: 0`) | — | counts, `matched`, warnings; takes `from_preview_id` |
+| `memory_bulk_delete` | `POST /v1/forget` (`about_subject`), `/v1/forget/preview` | ok | reported events only, always 0 | — | derived counts and warnings; accurate description |
+| `entity_list`, `entity_get`, `entity_edges` | `GET /v1/facts` | ok | ok | — | none |
+| `entity_link` | `POST /v1/experience` | ok | dropped `redirected_to` | as `memory_store` | names a redirect |
+| `belief_declare` | `POST /v1/beliefs` | ok (strictness unchanged; `provenance` is optional) | dropped `redirected_to` | `RUN_REQUIRED`, `FORMAT_UPGRADE_PENDING` (atoms below format 10) | names a redirect |
+| `list_conflicts`, `resolve_conflict`, `claim_history` | `GET /v1/conflicts`, `POST /v1/conflicts/{id}/resolve`, `GET /v1/claims/history` | ok | ok | — | `resolve_conflict` takes `tenant_id` (`?scope=`, the alignment pass below) |
+| `health_check` | `GET /v1/auth/whoami` | ok | dropped `chain` (0.14.0: an agent's chain token names its links) | — | shows `chain` |
+| `get_usage` | `GET /v1/auth/whoami` | ok | dropped `chain` | raised a raw `httpx` error | typed errors; shows the chain |
+| `get_insights`, `cortexdb://insights` | `GET /v1/events`, `/v1/facts`, `/v1/beliefs` | sent only the bearer and the actor | ok | every failure was swallowed: a refused read (`BREAK_GLASS_REQUIRED`, confinement) answered "no notable insights" | reads with the tools' headers; names a layer it could not read, and fails when it read none |
+| `code_explore`, `code_impact`, `code_inventory`, `code_graph` | `/v1/code/*` | ok | ok | `CODE_PLANE_DISABLED`; code reads are D-rows routes, so the operator key needs break-glass under `deny` | none |
+| resources `cortexdb://health`, `cortexdb://episodes` | `GET /v1/auth/whoami`, `GET /v1/events` | ok | ok | — | none |
+| the insights API (`cortexdb_mcp.api`) | as `get_insights` | sent no `X-Cortex-Actor`, so a minted token was 401 | ok | — | the tools' headers |
+
+## The tools 0.9.0 adds
+
+Profiles (`--tool-profile`, or `CORTEXDB_TOOL_PROFILE`): `all`, the default, is every tool but the opt-in writes,
+so an existing install keeps its tools and gains the read tools below; `write` adds `publish` and `forget_by_key`;
+`read` lists only the tools that write no memory (`/mcp`'s default); `code` the four code tools. Every tool carries
+MCP annotations (`readOnlyHint`, `destructiveHint`, `idempotentHint`), as `/mcp`'s do.
+
+| Tool | Profile | Route | What it answers |
+|---|---|---|---|
+| `access_check` | all, read, write | `POST /v1/access/check` | Can a principal (the token's own chain by default, or another: `principal`, `agent`, `app`, `chain_scopes`) read, write or own a scope, or read a memory: ALLOWED or DENIED with the deciding link and each link's path, the delivered role, the label cap, conditions and directory names |
+| `access_explain` | all, read, write | `POST /v1/access/explain` | Why: the home's decision link by link, one decision per atom (a redacted one says so), a derived memory's visible supports, the label against the cap |
+| `rollups` | all, read, write | `GET /v1/rollups`, `/v1/rollups/{id}`, `/v1/rollups/totals` | A unit's rollups at its `aud:roll` home (a unit's path is completed), by kind or topic, one by id with its citations, or the merged typed totals over a month range |
+| `notices` | all, read, write | `GET /v1/access/notices?mine=true` | The caller's own unacknowledged notices at its root: who read what, when and why (a grant, a break-glass read, a sign-in account change), with directory names |
+| `acknowledge_notices` | all, read, write | `POST /v1/access/notices/ack` | Acknowledges notices by `seqs` or a `through` position (changes no memory; a stale position acknowledges nothing and says so) |
+| `directory_lookup` | all, read, write | `GET /v1/directory`, `GET /v1/directory/{id}` | A name or email prefix search, or one entry, with only the fields the caller may read |
+| `publish` | write | `POST /v1/publish` | A person (directly, or through an admitted application whose token says `client: person`) copies an event or a rollup into a home they write; the answer names the copy and its original, and with `consistency` a token to read it back |
+| `forget_by_key` | write | `POST /v1/forget`, `/v1/forget/preview` (`selector.idempotency_keys`, `selector.capture_keys`) | The read-free forget, with its preview and `from_preview_id` |
+
+New fields on existing tools, each sent only when used, so a call without them sends the 0.8.0 request (but for `belief_declare`, which sends a fresh `idempotency_key` when none is given, as `memory_store` does):
+
+| Tool | Fields |
+|---|---|
+| `memory_search` | `extra_scopes` (at most 40), `coverage`, `at_least` (a consistency token) |
+| `get_context` | the same, and `merged_beliefs` (`beliefs: "merged"`) and `app_mounts` (`mounts: "default"`) |
+| `advanced_search` | `coverage`, `at_least` |
+| `memory_list`, `memory_get` | `at_least` (`?at_least=`) |
+| `memory_store` | `idempotency_key`, `provenance`, `consistency` (`?consistency=1`, the answer's token) |
+| `belief_declare` | `provenance`, `idempotency_key` |
+
+## CortexDB 0.14.0's route and field families
+
+What this server covers of each family the 0.14.0 clients cover, and why the rest is not here. The stdio server is an
+agent's tool surface, not an SDK: an operator's or an identity provider's route has no tool.
+
+| Family | Covered | By, or why not |
+|---|---|---|
+| Access API: `check`, `explain` | yes | `access_check`, `access_explain` |
+| Access API: `limits`, `lookup/scopes`, `lookup/principals`, `enrich` | no | sizing and planning inputs for an application or an Owner; `access_check` answers an agent's question about a given scope |
+| AuthZEN (`/access/v1/*`, `/.well-known/authzen-configuration`) | no | a policy decision point's interface for policy engines |
+| Change sets (`/v1/access/changes*`) | no | registry administration (CortexOS's compiler, an Owner) |
+| Watch | no | the root's Owner's and the operator's feed |
+| Notices and their acknowledgement | yes | `notices`, `acknowledge_notices` |
+| Restores (`/v1/access/{records,restore/ack}`, `/v1/admin/access/restore`) | no | an access source's or the operator's acknowledgement; a pending root's refusal (`ACCESS_RESTORE_PENDING`) is mapped |
+| Source containers (`rehome`, `watermarks`, `accounts/resolve`) | no | a connector's work; a source's watermark reaches `coverage` |
+| Applications (`/v1/apps/{id}`) | no | administration; `app_mounts` reads an application's mounts |
+| Directory (`/v1/directory[/{id}]`) | reads | `directory_lookup`; writes are an Owner's or the operator's |
+| SCIM (`/scim/v2/*`) | no | an identity provider's interface; a SCIM error body is parsed if one reaches a tool |
+| Rollups (`/v1/rollups`, `/totals`, `/{id}`) | yes | `rollups`; `/v1/admin/rollups/status` is the operator's |
+| Publish (`POST /v1/publish`) | yes | `publish` (write profile) |
+| Erasures (`/v1/erasures/{person,tenant}`, `subject: {email}`) | no | the operator's GDPR jobs; `cortexdb_check_call` knows their selector rules |
+| The read-free forget (`/v1/forget` key selectors) | yes | `forget_by_key` (write profile) |
+| Admin (`/v1/admin/access/*`, `/v1/admin/auth/reload`) | no | operator routes |
+| Read fields: `extra_scopes` (40), `coverage`, `beliefs: "merged"`, `mounts: "default"`, `consistency`, `purpose` | yes | the recall tools (above); `purpose` on the access tools too |
+| Write fields: `provenance`, `?consistency=1` | yes | `memory_store`, `belief_declare` |
+| Consistency tokens: `consistency_token` in answers, `?at_least=` on GETs | yes | shown when returned; `memory_list`, `memory_get` |
+| Tokens: confinement, lifetime ceilings, `act`, issuers-file tokens | yes | any bearer in `CORTEXDB_API_KEY`, `X-Cortex-Actor` from the token, typed refusals |
+| The operator key's break-glass | yes | `CORTEXDB_BREAK_GLASS_*`; `BREAK_GLASS_REQUIRED` and a malformed header's `INVALID_HEADER` mapped |
+| The subject-token shadow | yes | `CORTEXDB_SUBJECT_TOKEN` |
+| New error codes, retriable ones marked | yes | `CortexDBError`: the envelope's code, `retriable` and `Retry-After`, with what to do for each code a caller can act on |
+| Format 10 arming (`FORMAT_UPGRADE_PENDING` on an unarmed node) | yes | mapped by `details.reason` |
+
+## The alignment pass: the final 0.14.0 server
+
+What changed on the server after 0.9.0 was first built (`sharedcontext` 8b8bfb6d), and what the tools do about it.
+
+| Server change | Tools | Now |
+|---|---|---|
+| `GET /v1/events` pages with a newest-first cursor (`le1.`) bound to its query; any other cursor is 422 `INVALID_CURSOR` | `memory_list` | `cursor` replaces `offset`; each page ends with `More: cursor=<next>`; `episode_type` is the server's `labels` filter, so the cursor pages the filtered listing |
+| Codes: 400 `INVALID_HEADER` for any header that does not parse, the break-glass header's included (`details {part, field, reason}`); 410 `ROLLUP_SUPERSEDED` (`details.current`); 422 `act_not_delegable` (and the token's 401 `INVALID_TOKEN_CLAIM`); 422 `field_not_applied`; 504 `DB_TIMEOUT`; 500 `INTERNAL_ERROR` (was `INTERNAL`); 500 `SCOPE_STORAGE_MISCONFIGURED`; 503 `WAL_OUTCOME_UNKNOWN` (was `SCOPE_MUTATION_UNKNOWN`); 405 `METHOD_NOT_ALLOWED`; every envelope's `request_id` | every tool | each says what to do: the setting behind the header, the current rollup to read or publish, the employee's own chain, the fields to drop, to narrow a timed-out call; `memory_store`'s retriable refusal names the idempotency key to retry with, so a write whose outcome is unknown is replayed, not stored twice. `IDEMPOTENCY_CONFLICT` and `CLUSTER_ROUTE_UNSUPPORTED` are mapped too. `cortexdb_check_call` flags a `field_not_applied` forget. The client keeps no table of statuses or retriable flags: it reads each envelope's |
+| `read_purpose_v1`: a read declares `purpose` (`[a-z0-9_-]{1,64}`) on `/v1/recall`, `/recall/stream`, `/answer`, `/compose` and `POST /v1/access/check`/`explain`; a roster path whose `when` names it holds only then, and every decision line records it | `memory_search`, `get_context`, `advanced_search`, `access_check`, `access_explain` | `purpose` on each, default `CORTEXDB_PURPOSE`; checked against the grammar before anything is sent (the setting's error names it); a call naming none sends the request it sent before. The layer GETs (`memory_list`, `memory_get`, the entity tools) take no purpose on the server, so none is sent there. `cortexdb_check_call` checks the grammar |
+| Forget and its preview gain `events_under_legal_hold` and `derived_under_legal_hold` (facts, beliefs, episodes, understanding): what a legal hold keeps, counted in no deleted field | `memory_forget`, `memory_delete`, `memory_bulk_delete` (and its dry run), `forget_preview`, `forget_by_key` (and its preview) | each answer says what the hold kept ("Kept under a legal hold", a preview's "Would keep"): the events, erased when the hold is released, and the derived records by layer; nothing when it kept nothing |
+| The by-id reads take `?scope=` (a row elsewhere answers 404), and a cluster routes every by-id route by it, refusing one without (501 `CLUSTER_ROUTE_UNSUPPORTED`); `include_vectors=true` returns the embeddings | `memory_get`, `memory_status`, `resolve_conflict` | `memory_get` sent it already; `memory_status` (the exact scope the write went to) and `resolve_conflict` (the scope the conflict was listed at) take `tenant_id` and send it as `?scope=`, only when given, so a single node's call is unchanged. `rollups` by id and `directory_lookup` by id send their home and root already. No tool has a by-id fact, belief, concept or lifecycle read. `include_vectors` is not sent: an embedding is no text an agent reads, and it would fill the tool's answer |
+| `POST /v1/beliefs` takes `idempotency_key` (at most 256 bytes): the same key at the same scope answers the first declaration's belief, another declaration under it is 409 `IDEMPOTENCY_CONFLICT` | `belief_declare` | takes `idempotency_key`, and sends a fresh one when none is given (as `memory_store` does), so a retriable refusal names the key to retry with and a declaration whose outcome is unknown is never made twice; a server before 0.14.0 ignores the field |
+| Publish: a person may publish through an application the tenant admitted (`client: person`); refused are an agent's `act`, a run, a service subject and an `app` token with no `client`. `?consistency=1` returns `consistency_token`; a superseded rollup is 410 `ROLLUP_SUPERSEDED` | `publish` | the description and the `PUBLISH_PERSON_REQUIRED` hint no longer list "an application" among the refused, and say which chains are; `consistency` sends `?consistency=1` and shows the token; the 410 names the build to publish instead |
+| `GET /v1/rollups/totals` takes a bound of exactly four digits, a hyphen and a month 01 to 12 (p5o item 9: `2026-+1` used to pass), else 422 `INVALID_QUERY` | `rollups` (`totals`) | the client's check is the server's: ASCII digits only, the whole value (a trailing newline or another script's digits no longer pass it) |
+| The final catalog (API reference §16): `NON_HUMAN_WRITE_UNSUPPORTED` retired, `RATE_LIMITED` answered by no route (`SUBTREE_RATE_LIMITED`, `RECALL_OVERLOADED`), `NOTICE_UNAVAILABLE`'s reasons `moving`, `limit`, `arming_disabled`, `members_behind`, `refused` (`scope_unnamed` gone: a by-id read's notice is its row's region's), and a failed write's `resend: no` | every tool; `memory_get`, `memory_status` | the retired codes' hints are gone and `RECALL_OVERLOADED` has one; `NOTICE_UNAVAILABLE` reads the new reasons; `memory_get` no longer says a break-glass read needs `tenant_id`; `memory_status` says a failed write is never re-sent (it said `memory_store` re-stores it under a new key) |
+| p5w: under `deny` the operator key's change-set activation is in-band: 403 `BREAK_GLASS_REQUIRED` (`details.class: "in_band"`) without the header, 503 `NOTICE_UNAVAILABLE`, 503 `REGISTRY_STALE`; the preview gains `in_band` and `in_band_parts` | none previews or activates a change set; the operator key's tools meet `in_band` on a write into a private region or a shared scope | the `BREAK_GLASS_REQUIRED` hint says what the class refused (in-band work, or data reads); `REGISTRY_STALE` is retriable and read as the envelope says |
+| Codes no tool can meet | none | `ERASURE_NOT_CANCELLABLE`, `COHORT_UNSUPPORTED`, `SCIM_UNSUPPORTED`, `TENANT_SETTINGS_UNAVAILABLE`, the mint's `scopes_exceed_minter`, `caps_exceed_minter` and `deployment_mint_requires_operator`, `BLOB_STORE_ERROR`, and p5o's admin codes (`PERSIST_FAILED`, `ICE_FORK_UNSUPPORTED`, the repairs' `UNSUPPORTED_MEDIA_TYPE`, `CROSS_SHARD_REQUEST`): no tool cancels an erasure, asks a cohort, speaks SCIM, mints or calls an admin route; any of them still renders as a typed error |
+
+## Server behaviour noted, not changed here
+
+- Fixed on the final server: `GET /v1/experience/status` answered `resend: "new_key"` for a `failed` write, which
+  the contract (`INDEXING_FAILED`, §8 O6) says never to re-send; it answers `no` now, and since p5v 17 its note says
+  never to re-send it, at any age, under any key (the key replays the failure; the operator re-includes the stored
+  event in place, and a copy under a new key would store the memory twice). `memory_status` and the
+  `INDEXING_FAILED` hint say the same. The reference's §11.2 no longer says the forget selector ignores a field it
+  does not know.
+- Fixed in p5v, after the live run of this pass found them: a forget whose every named event a legal hold kept
+  answered `matched: 0` and the "matched no records ... check the ids" warning (p5v 1: `matched` counts what a hold
+  kept, at most `requested`, and the warning fires only when nothing matched); a read refused for want of its
+  purpose answered as if the caller held no role (p5v 2: 403 `POLICY_DENIED`, `details.reason: "purpose_required"`
+  and `details.purpose`, which the hint names); the reference said a redirected write is found by key only without
+  `scope` (p5v 3: by either, as the code does). A format hold's `NOTICE_UNAVAILABLE` keeps its own reason (p5v 12):
+  `reserved_path_in_use` is not retriable, and the hint says the operator clears it.
+- Tenant settings carry `deployment_mode` (p5v 13); no tool reads them.