cortexdbai 0.13.0__tar.gz → 0.14.0__tar.gz

{cortexdbai-0.13.0 → cortexdbai-0.14.0}/COVERAGE.md

@@ -15,6 +15,17 @@ server adds goes in this table in the same change.
   `forget_routes*.rs`, `code_routes.rs`, `commitment_routes.rs`, `source_erasure_routes.rs` and the rest).
 - **Base:** `origin/sharedcontext` at `4618df85`, the final 0.14.0 server, 206 paths and 237 operations (a path with
   two methods is two rows). The field families are in the second table.
+- **Since then (CortexDB 0.15.0, `cortexdbai` 0.14.0):** N10 step 0's `derivation_provenance_v1` adds one route,
+  `GET /v1/derivation/decisions`; `derivation_policy_v1` (M4) adds `GET /v1/derivation/policy`, `/templates`,
+  `/taxonomy`, `PUT`, `GET` and `DELETE /v1/derivation/settings`, `GET /v1/derivation/texts` and
+  `POST /v1/derivation/texts/erase`, and (M5) `POST /v1/derivation/policy/test`; `derivation_feed_v1` (M8) adds
+  `GET /v1/derivation/feed`; `corrections_v1` (M3) adds `POST` and `GET /v1/corrections`, `GET` and
+  `DELETE /v1/corrections/{id}` and `GET /v1/memory/about`; `derivation_review_v1` (M6) adds `GET /v1/review` and
+  `POST /v1/review/decisions`; `derivation_rederive_v1` (M7) adds `POST /v1/derivation/rederive`,
+  `GET /v1/derivation/rederive/{job_id}`, `POST .../cancel` and `GET /v1/derivation/report`; M8's records add
+  `GET /v1/derivation/feed/consumers` (`derivation_feed_v1`) and `POST /v1/episodes` and `DELETE /v1/episodes/{id}`
+  (`declared_episodes_v1`); and they, `derived_by_v1` (M0.6) and the importers' modes (M13) add the field families
+  at the end of the second table: 226 paths and 262 operations.
 - **The method column** is read from the SDK itself: each method's docstring names its route first.
 - **Status:** `covered` (both clients), or `not covered` with the reason.
 
@@ -23,7 +34,7 @@ server adds goes in this table in the same change.
 - **Unit** (`tests/`, run by CI's `pytest -q` in `sdks/python`): every method on both clients sends the same
   request (`test_client_parity.py`), and each route family's tests pin its requests and its answers' handling.
 - **Live** (`tests/live/`, against a release binary of the merged tree, `CORTEXDB_BINARY=… pytest tests/live`): one
-  org's life in 25 legs, run once on each client. The last leg calls every route the others do not, and checks that
+  org's life in 30 legs, run once on each client. The last leg calls every route the others do not, and checks that
   each answers by its contract on a default server: 2xx, or the documented refusal of a switch the server leaves off
   (`CODE_PLANE_DISABLED`, `COHORT_DISABLED`, `ICE_OFF`, plans' 404, the native memory host's routes, which a
   plain server does not mount). With `CORTEXDB_LIVE_ROUTES=<file>` the run records every request it sent: on 0.14.0
@@ -46,7 +57,7 @@ These are served by the binary but are not the v1 API a client calls:
 
 ## Summary
 
-237 operations: 235 covered by both clients, 2 not covered (each row says why).
+258 operations: 256 covered by both clients, 2 not covered (each row says why).
 
 Before the 0.14.0 work (`cortexdbai` 0.12.0), 67 operations were reached, 49 of them only partly (38 had no
 `AsyncV1Client` method), and none of the shared-memory routes.
@@ -145,7 +156,7 @@ Before the 0.14.0 work (`cortexdbai` 0.12.0), 67 operations were reached, 49 of
 | `POST /v1/answer` | Read | `answer`, `answer_stream` | covered |
 | `GET /v1/apps/{id}` | Applications | `app_get` | covered |
 | `PUT /v1/apps/{id}` | Applications | `app_put` | covered |
-| `GET /v1/audit` | Audit | `audit_list` | covered |
+| `GET /v1/audit` | Audit | `audit_list` (`action=`, CortexDB 0.15.0) | covered |
 | `GET /v1/audit/chain` | Audit | `audit_chain` | covered |
 | `POST /v1/audit/chain/verify` | Audit | `audit_chain_verify` | covered |
 | `POST /v1/audit/verify` | Audit | `audit_verify` | covered |
@@ -202,13 +213,35 @@ Before the 0.14.0 work (`cortexdbai` 0.12.0), 67 operations were reached, 49 of
 | `GET /v1/concepts/{id}/related` | Layers | `concept_related` | covered |
 | `GET /v1/conflicts` | Layers | `list_conflicts` | covered |
 | `GET /v1/conflicts/{id}` | Layers | `get_conflict` | covered |
-| `POST /v1/conflicts/{id}/resolve` | Layers | `resolve_conflict` | covered |
-| `GET /v1/derivation/status` | Layers | `derivation_status` | covered |
+| `POST /v1/conflicts/{id}/resolve` | Layers | `resolve_conflict` (`loser=` and the answer's `correction_ids`, `corrections_v1`) | covered |
+| `GET /v1/corrections` | Corrections (`corrections_v1`, CortexDB 0.15.0) | `corrections` (pages with `pages()`) | covered |
+| `POST /v1/corrections` | Corrections (`corrections_v1`) | `correct`; its shorthands `reject`, `replace`, `pin`, `confirm` | covered |
+| `DELETE /v1/corrections/{id}` | Corrections (`corrections_v1`) | `undo_correction` | covered |
+| `GET /v1/corrections/{id}` | Corrections (`corrections_v1`) | `correction` | covered |
+| `GET /v1/derivation/decisions` | Layers (`derivation_provenance_v1`, CortexDB 0.15.0) | `derivation_decisions` | covered |
+| `GET /v1/derivation/feed` | Derivation (`derivation_feed_v1`, CortexDB 0.15.0) | `derivation_feed`; `feed_iter` follows its cursor; `cortexdb.workers.DerivationWorker` reads it | covered |
+| `GET /v1/derivation/feed/consumers` | Derivation (`derivation_feed_v1`, CortexDB 0.15.0) | `feed_consumers` (pages with `pages()`) | covered |
+| `GET /v1/derivation/policy` | Derivation (`derivation_policy_v1`, CortexDB 0.15.0) | `derivation_policy` (`include_texts=True`) | covered |
+| `POST /v1/derivation/policy/test` | Derivation (`derivation_policy_v1`) | `derivation_policy_test` (a draft `policy` or a staged `changeset`; `sample` the newest N, 50 by default, or named event ids; `max_cost_usd`, 1 by default; `compare_with_active`, on here; its HTTP timeout raised to cover the sample, and never sent twice) | covered |
+| `POST /v1/derivation/rederive` | Derivation (`derivation_rederive_v1`, CortexDB 0.15.0) | `rederive` (`regate` or `reextract`, a dry run by default; `event_ids` or the unsynced rows; an apply's `estimate_id`, `cap_usd` and `job_id` key; a dry run's HTTP timeout raised to cover its sample) | covered |
+| `GET /v1/derivation/rederive/{job_id}` | Derivation (`derivation_rederive_v1`) | `rederive_job`; `rederive_wait` polls it until the job closes | covered |
+| `POST /v1/derivation/rederive/{job_id}/cancel` | Derivation (`derivation_rederive_v1`) | `rederive_cancel` | covered |
+| `GET /v1/derivation/report` | Derivation (`derivation_rederive_v1`) | `derivation_report` (`since`, `until`; `csv=True` answers the CSV text) | covered |
+| `DELETE /v1/derivation/settings` | Derivation (`derivation_policy_v1`) | `delete_derivation_settings` | covered |
+| `GET /v1/derivation/settings` | Derivation (`derivation_policy_v1`) | `derivation_settings` | covered |
+| `PUT /v1/derivation/settings` | Derivation (`derivation_policy_v1`) | `put_derivation_settings` (a whole-record replace; `settings_fields` reads a record back into its fields) | covered |
+| `GET /v1/derivation/status` | Layers | `derivation_status` (the `extraction` block, `at_least`, and `derived_by`) | covered |
+| `GET /v1/derivation/taxonomy` | Derivation (`derivation_policy_v1`) | `derivation_taxonomy` | covered |
+| `GET /v1/derivation/templates` | Derivation (`derivation_policy_v1`) | `derivation_templates` | covered |
+| `GET /v1/derivation/texts` | Derivation (`derivation_policy_v1`) | `derivation_texts` (pages with `pages()`) | covered |
+| `POST /v1/derivation/texts/erase` | Derivation (`derivation_policy_v1`) | `erase_derivation_texts` | covered |
 | `GET /v1/directory` | Directory | `directory_search` | covered |
 | `DELETE /v1/directory/{id}` | Directory | `directory_delete` | covered |
 | `GET /v1/directory/{id}` | Directory | `directory_get` | covered |
 | `PUT /v1/directory/{id}` | Directory | `directory_put` | covered |
 | `GET /v1/episodes` | Layers | `episodes` | covered |
+| `POST /v1/episodes` | Layers (`declared_episodes_v1`, CortexDB 0.15.0) | `declare_episode` | covered |
+| `DELETE /v1/episodes/{id}` | Layers (`declared_episodes_v1`) | `delete_episode` | covered |
 | `POST /v1/episodes/build` | Layers | `build_episodes` | covered |
 | `POST /v1/erasures` | Erasures | `erase` | covered |
 | `POST /v1/erasures/person` | Erasures | `erase_person` | covered |
@@ -235,16 +268,17 @@ Before the 0.14.0 work (`cortexdbai` 0.12.0), 67 operations were reached, 49 of
 | `GET /v1/health` | Service and policy | `health` | covered |
 | `POST /v1/import` | Import and export | `import_data` | covered |
 | `POST /v1/import/jsonl` | Import and export | `import_jsonl` | covered |
-| `POST /v1/import/letta` | Import and export | `import_letta` | covered |
-| `POST /v1/import/mem0` | Import and export | `import_mem0` | covered |
-| `POST /v1/import/openai` | Import and export | `import_openai` | covered |
-| `POST /v1/import/zep` | Import and export | `import_zep` | covered |
+| `POST /v1/import/letta` | Import and export | `import_letta` (`mode=`, CortexDB 0.15.0) | covered |
+| `POST /v1/import/mem0` | Import and export | `import_mem0` (`mode=`) | covered |
+| `POST /v1/import/openai` | Import and export | `import_openai` (`mode=`) | covered |
+| `POST /v1/import/zep` | Import and export | `import_zep` (`mode=`, `keep_triples` too) | covered |
 | `GET /v1/import/{id}` | Import and export | `import_status` | covered |
 | `GET /v1/lifecycle` | Lifecycle | `lifecycle_events` | covered |
 | `GET /v1/lifecycle/event/{lce_id}` | Lifecycle | `lifecycle_event` | covered |
 | `GET /v1/lifecycle/memory-event/{evt_id}` | Lifecycle | `lifecycle_memory_event` | covered |
 | `POST /v1/lifecycle/memory-event/{evt_id}/cancel` | Lifecycle | `cancel_event` | covered |
 | `GET /v1/lifecycle/stream` | Lifecycle | `lifecycle_stream` | covered |
+| `GET /v1/memory/about` | Corrections (`corrections_v1`, CortexDB 0.15.0) | `memory_about` (`include=("corrections", "held")` by default, `MEMORY_ABOUT_DEFAULT_INCLUDE`; pages with `pages()`) | covered |
 | `POST /v1/memory/commitments/commands` | Native memory host | `native.commitment_command` | covered |
 | `POST /v1/memory/commitments/current` | Native memory host | `native.commitment_current` | covered |
 | `POST /v1/memory/commitments/evidence` | Native memory host | `native.commitment_evidence` | covered |
@@ -262,6 +296,8 @@ Before the 0.14.0 work (`cortexdbai` 0.12.0), 67 operations were reached, 49 of
 | `POST /v1/publish` | Publish | `publish` | covered |
 | `GET /v1/ready` | Service and policy | `ready` | covered |
 | `POST /v1/recall` | Read | `recall` | covered |
+| `GET /v1/review` | Review (`derivation_review_v1`, CortexDB 0.15.0) | `review` (`topic=`, `rule=`, `descend=`, `state=`; pages with `pages()`) | covered |
+| `POST /v1/review/decisions` | Review (`derivation_review_v1`) | `review_decide`; its shorthands `approve`, `reject_held` (one decision each) | covered |
 | `POST /v1/recall/stream` | Read | `recall_stream` | covered |
 | `GET /v1/rollups` | Rollups | `rollups` | covered |
 | `GET /v1/rollups/totals` | Rollups | `rollup_totals` | covered |
@@ -293,7 +329,7 @@ Before the 0.14.0 work (`cortexdbai` 0.12.0), 67 operations were reached, 49 of
 | `PATCH /v1/vocabularies/{name}` | Vocabularies and phrases | `update_vocabulary` | covered |
 | `PUT /v1/vocabularies/{name}` | Vocabularies and phrases | `replace_vocabulary` | covered |
 
-## Fields, headers and errors of 0.14.0
+## Fields, headers and errors of 0.14.0 and 0.15.0
 
 | Family | Where | SDK | Status |
 |---|---|---|---|
@@ -313,6 +349,7 @@ Before the 0.14.0 work (`cortexdbai` 0.12.0), 67 operations were reached, 49 of
 | `X-Cortex-Subject-Token` (`subject_token_shadow_v1`) | the trusted operator's requests | `with_options(subject_token=...)` | covered |
 | Chain fields of a mint (`act`, `app`, `client`, `run`, `run_start`, `taint`; `mint_chain_v1`) and `tenant` | `POST /v1/auth/tokens` | `mint_token(...)`, `mint_agent_token`, `mint_app_token`; `check_mint` refuses locally what the server always refuses; `with_token` | covered |
 | `purpose` (`read_purpose_v1`) | `/v1/recall`, `/v1/recall/stream`, `/v1/answer`, `/v1/compose`, `POST /v1/access/{check,explain}` | `purpose="..."` (`[a-z0-9_-]{1,64}`, a `ValueError` otherwise); a read refused for want of its purpose raises `PolicyDeniedError` with `reason == "purpose_required"` and `purpose` | covered |
+| `session` (`derivation_use_rules_v1`, CortexDB 0.15.0) | `/v1/recall`, `/v1/recall/stream`, `/v1/answer`, `/v1/compose` | `session="..."` on `recall`, `recall_stream`, `answer`, `answer_stream` and `compose` of both clients (1 to 256 bytes with no control character, a `ValueError` otherwise): where a read-time use rule is in force, memory from other sessions or older than its window is withheld and `warnings` says `use_rule_withheld: <n> events from earlier sessions`; a read without it sends the request it sent before | covered |
 | `?scope=` on the by-id reads (a scope that does not hold the row is 404) | `/v1/facts/{id}`, `/v1/beliefs/{why,history}`, `/v1/concepts/{id}[/history,/related]`, `/v1/understanding/{id}[/history,/related]`, `/v1/conflicts/{id}[/resolve]`, `/v1/lifecycle/event/{id}`, `/v1/admin/events/{id}/chunks`, `/v1/erasures/{id}[/receipt,/verify]` | `scope=` | covered |
 | `include_vectors=true` | the layer listings and the fact and concept reads by id | `include_vectors=True` | covered |
 | Paging: `cursor` / `next_cursor` / `has_more` (the events' `le1.` cursor newest first, the scope list, the layers) | `GET /v1/events`, `/v1/scopes/list`, `/v1/facts`, `/v1/beliefs`, `/v1/episodes`, `/v1/understanding`, `/v1/concepts` and the access listings | `cursor=`, `pages(method, ...)` | covered |
@@ -320,8 +357,28 @@ Before the 0.14.0 work (`cortexdbai` 0.12.0), 67 operations were reached, 49 of
 | `idempotency_key` on a declared belief; `owner` on `POST /v1/scopes`; `scope` on a temporal phrase; `batch_id` on the lifecycle stream | those routes | `idempotency_key=`, `owner=`, `scope=`, `batch_id=` | covered |
 | `events_under_legal_hold`, `derived_under_legal_hold`, and `matched` counting what a hold kept | `POST /v1/forget`, `/v1/forget/preview` | in the answer (documented on both methods) | covered |
 | `in_band`, `in_band_parts` of a change set's preview; the operator key's in-band activation under `deny` (`BREAK_GLASS_REQUIRED` class `in_band`, `NOTICE_UNAVAILABLE`, `REGISTRY_STALE`) | `POST /v1/access/changes/{id}/preview`, `/activate` | `ChangeSetPreview` in `cortexdb.v1.models`; `client.break_glass(...).changeset_activate(...)` | covered |
+| A change set's 202 while its evaluation runs (0.14.1; `Retry-After`, a preview's `{state: "previewing"}`) | `POST /v1/access/changes`, `/{id}/parts`, `/{id}/preview`, `/{id}/activate` | sent again after `Retry-After` for at most `wait` seconds (`CHANGESET_WAIT_SECONDS`), then `V1EvaluationPendingError`; `wait=0` returns `EvaluationPending` | covered |
+| `operator_plane` of a tenant binding, its dry run's included (0.14.1) | `POST /v1/admin/access/tenant-binding` | `TenantBindingResponse` in `cortexdb.v1.models`; `admin_tenant_binding` | covered |
 | `deployment_mode` (`tenant_access_settings_v1`) | `GET`, `PUT /v1/admin/access/tenant-settings`; the access report's `tenant_settings` | `TenantAccessSettings` in `cortexdb.v1.models` | covered |
 | `resend` of a write status (`"no"` for a failed write, never re-sent; `"new_key"` gone) | `GET /v1/experience/status` | `write_status(...)`; `IndexingFailedError` says never to re-send | covered |
 | An omitted `X-Cortex-Actor` (issuers-file `prefix`, `hash` and `directory` tokens; SCIM clients) | every route | `actor=None`, `with_options(actor=None)`; derived from a token's `sub` when no `actor` is given (none for a mapped subject) | covered |
 | `view` left to the server (granular at an org tree's shared scope) | `/v1/recall`, `/v1/answer`, `/v1/compose` | `view=None` (the default) | covered |
-| Typed errors with `retriable` and `details` | every route | one class per code (`cortexdb.v1.errors`, 362 codes from `scripts/error_codes.json`, built from the error catalog, `docs/API_REFERENCE_V1.md` §16) under status-family classes; documented `details` keys as properties; `retry_after` | covered |
+| `include=derivation` (`derivation_provenance_v1`, CortexDB 0.15.0): each row's `derivation` (verdict, models, prompt and gate versions, policy, `derived_by`, `pinned`, `confirmed`, `unsynced`) | `GET /v1/facts`, `/v1/facts/{id}`, `/v1/facts/timeline`, `/v1/beliefs`, `/v1/beliefs/why` | `include=["derivation"]` (sent once, comma-joined); `DerivationDetails` in `cortexdb.v1.models`; `derivation_of(row)` (`None` from a server that ignores the parameter) | covered |
+| The status route's `extraction` block (`derivation_provenance_v1`) | `GET /v1/derivation/status` | `ExtractionStatus` in `cortexdb.v1.models`; `derivation_status(scope, at_least=)` | covered |
+| `directive_not_enforced:<name>` in a write's `warnings` (0.15.0: `consolidate_into`, `confidence_floor`, `ttl_for_belief_layer`, `embed`, `async`) | `POST /v1/experience`, each `/v1/experience/bulk` `results` item, an import's 202 and `GET /v1/import/{id}` | `unenforced_directives(answer)`, `DIRECTIVES_NOT_ENFORCED` (`cortexdb.v1.derivation`) | covered |
+| `enrich_kept` warnings of a change set (0.15.0: a companion put that keeps the stored `enrich`) | a staging's 200 (`POST /v1/access/changes`, `/{id}/parts`), every preview page | `enrich_kept(answer)`, `EnrichKeptWarning` (`cortexdb.v1.derivation`); `ChangeSetStatusWarningsItem`, `ChangeSetPreviewWarningsItem` in `cortexdb.v1.models` | covered |
+| Derive records (`derivation_policy_v1`, CortexDB 0.15.0): a record of kind `derive` at `<scope>/attrs:derive`, its texts inline, in a change set of derive records alone; the preview's `derivation` section (`records`, `effective`, `narrowing`, `texts`, `warnings`) | `POST /v1/access/changes`, `/{id}/parts`, `/{id}/preview`, `/{id}/activate` | `derive_record(scope, body)` (`cortexdb.v1`, also `client.derive_record`) for `changeset_part`; `DerivationPreview` in `cortexdb.v1.models` | covered |
+| `derived_by` (`derived_by_v1`, CortexDB 0.15.0): a write-back's `{name, version}`, on a typed triple only, part of write identity | `POST /v1/experience`, each `/v1/experience/bulk` and `/v1/experiences` item, `POST /v1/beliefs` | `derived_by=` on `experience` and `create_belief` (a mapping or `"name@version"`, checked before sending), a bulk item's `"derived_by"`; `EnvelopeDerivedBy`, `DeclareBeliefRequestDerivedBy` in `cortexdb.v1.models` | covered |
+| `?derived_by=` and the answer's `derived_by` reports (`derived_by_v1`) | `GET /v1/derivation/status` | `derivation_status(scope, derived_by=[...])` (at most 8 names, comma-joined); `DerivedByReport` in `cortexdb.v1.models` | covered |
+| The feed's erasure items, which name events only by `event_id_hashes` (BLAKE3 of `cortexdb/feed/erased-id/v1` and the id's 16 bytes) | `GET /v1/derivation/feed` | `feed_erased_id_hash(event_id)`, `erased_matches(item, held_ids)` (`cortexdb.v1.derivation`; the `blake3` extra, else pure Python); `DerivationFeedItem` in `cortexdb.v1.models` | covered |
+| A feed page's `consumer_recorded` (format 11: the consumer's mark recorded) | `GET /v1/derivation/feed` | the page's key; `consumer_recorded` on `FeedIterator` and `AsyncFeedIterator` (the last page's) | covered |
+| An erasure's `feed_consumers` (format 11: the consumers whose marks passed an erased event, with the events' hashes) and `corrections` (the corrections it erased); the proof's `governed_records` check | `GET /v1/erasures/{id}/receipt`, `GET /v1/erasures/{id}/verify` | `feed_consumers_of(answer)`, `verify_check(proof, GOVERNED_RECORDS_CHECK)` (`cortexdb.v1.derivation`); `ErasureReceiptResponseReceiptFeedConsumersItem`, `ErasureVerifyResponseFeedConsumersItem` in `cortexdb.v1.models` | covered |
+| The reference worker (design §13.6): reads the feed as its consumer, writes results back in bulk with `provenance`, `derived_by` and deterministic keys, purges on erasure items by hash, saves its cursor after its writes commit, backs off on 503 | `GET /v1/derivation/feed`, `POST /v1/experience/bulk`, `GET /v1/events/{id}` | `cortexdb.workers`: `DerivationWorker`, `FileCursor`, `MemoryCursor`, `Triple` | covered |
+| A Claude memory-tool handler (design §13.7): Anthropic's memory tool (`memory_20250818`) on a scope, one event per file version labelled `memory_file:<path>` | `POST /v1/experience`, `GET /v1/events`, `POST /v1/forget`, `POST /v1/erasures` | `cortexdb.memory_tool`: `CortexMemoryTool` (the Anthropic SDK's `BetaAbstractMemoryTool`; the `anthropic` extra), `CortexMemoryFiles` (without it) | covered |
+| An importer's `mode` (`raw`, `keep`; Zep's `keep_triples`) and a row's `id` (N10 M13, CortexDB 0.15.0); `derived_by_dropped:<name>` in an import job's `warnings` | `POST /v1/import/mem0`, `/zep`, `/letta`, `/openai`; an import's 202 and `GET /v1/import/{id}` | `mode=` on the four importers (checked before sending; a row's `id` passes through); `dropped_derived_by(job)`, `IMPORT_MODES`, `ZEP_IMPORT_MODES` (`cortexdb.v1.derivation`) | covered |
+| `?action=` of the audit listing, and a handler row's `action` (`derivation_consent`, `derivation_text_erase`, `correction`, `correction_undo`) | `GET /v1/audit` | `audit_list(action=...)`; `AuditRow.action` in `cortexdb.v1.models` | covered |
+| A correction's target (a `fact_id` or a `claim` `{subject, predicate, object, negated}`), `bind`, `value`, `valid`, `reason`, `subject_principal` and `idempotency_key` (a replay answers 200 with `replayed: true`) | `POST /v1/corrections` | `correct(scope, action, target, ...)` and its shorthands (a target is a fact id string or a claim mapping; what the route always refuses is a `ValueError` before sending); `CorrectionRequest`, `CorrectionCreated`, `Correction`, `CorrectionPage`, `CorrectionUndone`, `MemoryAbout` in `cortexdb.v1.models` | covered |
+| `loser` (`closed`, `wrong`) beside a `pick`, and the answer's `correction_ids` (`corrections_v1`, format 11) | `POST /v1/conflicts/{id}/resolve` | `resolve_conflict(..., loser=)`; the answer passes through | covered |
+| A review decision (`derivation_review_v1`, CortexDB 0.15.0): `held_id`, `decision` (`approve`, `reject`), a rejection's `bind` (`claim`, `subject_predicate`) and `reason`, at most 100 a request; each result's `fact_id`, `pending`, `correction_id`, or `error_code` (`NOT_FOUND`, `REVIEW_ITEM_DECIDED`, `PROVENANCE_ERASED`, a retriable storage code) | `POST /v1/review/decisions` | `review_decide(scope, decisions)`, `approve(scope, held_id)`, `reject_held(scope, held_id, bind="claim")` (what the route always refuses is a `ValueError` before sending; a refused decision is a result, not an exception); `ReviewDecisionsRequest`, `ReviewDecisionsResponse`, `ReviewPage` in `cortexdb.v1.models`; `DERIVATION_REVIEW_V1`, `REVIEW_DECISIONS`, `REVIEW_BINDS`, `MAX_REVIEW_DECISIONS` (`cortexdb.v1.derivation`) | covered |
+| `include=held` and a held item (`kind: "held"`, `held_id`, `rule`, `lapse_at`; `counts.held`) | `GET /v1/memory/about` | `memory_about(scope, include=("corrections", "held"))`; `MEMORY_ABOUT_INCLUDES` (`cortexdb.v1.derivation`) | covered |
+| Typed errors with `retriable` and `details` | every route | one class per code (`cortexdb.v1.errors`, 371 codes from `scripts/error_codes.json`, built from the error catalog, `docs/API_REFERENCE_V1.md` §16) under status-family classes; documented `details` keys as properties; `retry_after` | covered |