From ffcc61920a80ffeb02b0415d4ee750ddafaa6a5d Mon Sep 17 00:00:00 2001 From: Shay Date: Mon, 15 Jun 2026 02:44:45 -0700 Subject: [PATCH] docs(workbench): mark Vault P0/P1/P2 complete; document recall endpoint (#768) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Reconcile the living docs with the shipped Vault evidence surface: - README "Shipped surfaces": record the Vault P0 (honest empty/unavailable framing, #760), P1 (inspector depth + status/facet/text filters + evidence-rail progression, #762/#763/#764), and P2 (read-only exact-CGA recall, #766) arc as complete; enrich the Vault entry row. Read-only throughout — no runtime controls. - wave-R: extend the Vault surface bullet with the recall endpoint and the P0/P1/P2 completion note + the +inf-self-match-sentinel honesty point. - api-contract-v1: add GET /vault/entries/{index}/recall (purpose, errors, trust boundary, cross-link to the data shape). - data-shapes-v1: add VaultRecallHit / VaultRecall types. - UI-UX-GUIDE: enrich the Vault row (inspector depth, filters, rail, opt-in exact-CGA recall; read-only). Docs-only; no code or contract behavior change. --- docs/workbench/README.md | 10 ++++++++- docs/workbench/UI-UX-GUIDE.md | 2 +- docs/workbench/api-contract-v1.md | 26 ++++++++++++++++++++++ docs/workbench/data-shapes-v1.md | 29 +++++++++++++++++++++++++ docs/workbench/wave-R-mastery-revamp.md | 13 ++++++++--- 5 files changed, 75 insertions(+), 5 deletions(-) diff --git a/docs/workbench/README.md b/docs/workbench/README.md index 4189e992..bd331268 100644 --- a/docs/workbench/README.md +++ b/docs/workbench/README.md @@ -237,6 +237,14 @@ alignment / safety). Phase E (robustness; continuous) and the parallel tracks (the CORE-Logos *Studio* mutation/patch-forge path, the universal proposal envelope) remain. +The **Vault** evidence surface is likewise complete end to end: **P0** honest +empty/unavailable framing (every state framed as the Vault; absence vs +persisted-empty split; #760), **P1** entry-inspector depth + status/facet/text +filters + an honest evidence-rail progression (#762/#763/#764), and **P2** +read-only exact-CGA recall evidence (`GET /vault/entries/{index}/recall`; #766). +It stays a read-only evidence surface — no runtime controls, no persistence +toggle, no approximate recall. + Doctrine is unchanged: read-only first, allowlisted execution only (`/evals/run`, ratify, `/demos/{id}/run`), every surface a real backend reader (no theater), determinism over persuasion. @@ -250,7 +258,7 @@ Doctrine is unchanged: read-only first, allowlisted execution only | Converse | **Chat** | | Cognition | **Trace** (Pipeline / Field / Bundle / Surfaces / Grounding / Verdicts / Metadata / Raw tabs), **Contemplation** (staged learning loop) | | Determinism | **Tour** (guided determinism narrative), **Replay** (hash-to-hash), **Demos** (Demo Theater) | -| Evidence | **Proposals** (+ HITL ratification), **Runs** (+ identity continuity), **Lived Life** (always-on heartbeat), **Vault**, **Audit** | +| Evidence | **Proposals** (+ HITL ratification), **Runs** (+ identity continuity), **Lived Life** (always-on heartbeat), **Vault** (honest empty/unavailable framing · inspector depth + status/facet/text filters · evidence-rail progression · exact-CGA recall), **Audit** | | Discipline | **Evals** (wrong=0 ledger), **Calibration** (gold-tether arena, Wilson floor vs θ) | | Substrate | **Packs**, **CORE-Logos** (read-only pack reader) | | Settings | **Settings** (landing / density / inspector prefs) | diff --git a/docs/workbench/UI-UX-GUIDE.md b/docs/workbench/UI-UX-GUIDE.md index 9ac10a36..563d46c5 100644 --- a/docs/workbench/UI-UX-GUIDE.md +++ b/docs/workbench/UI-UX-GUIDE.md @@ -73,7 +73,7 @@ Current route count: 16. | Evidence | Proposals | `/proposals` | `⌘4` | Review cognition and math proposal evidence. | | Evidence | Runs | `/runs` | `⌘6` | Browse recorded run/session evidence. | | Evidence | Lived Life | `/lived-life` | Palette | Watch the always-on heartbeat hold one continuous life (closure read-not-repaired over uptime + learned-while-idle). | -| Evidence | Vault | `/vault` | `⌘8` | Inspect persisted vault metadata when persistence exists. | +| Evidence | Vault | `/vault` | `⌘8` | Inspect persisted vault entries when persistence exists — entry-inspector depth, status/facet/text filters, evidence rail, and opt-in exact-CGA recall evidence. Read-only (no runtime controls). | | Evidence | Audit | `/audit` | `⌘9` | Read deterministic audit events. | | Discipline | Evals | `/evals` | `⌘5` | Run/read allowlisted eval lanes and wrong=0 ledgers. | | Discipline | Calibration | `/calibration` | Palette | Inspect practice-class reliability and license verdicts. | diff --git a/docs/workbench/api-contract-v1.md b/docs/workbench/api-contract-v1.md index 2c5a06dc..6dd1ea55 100644 --- a/docs/workbench/api-contract-v1.md +++ b/docs/workbench/api-contract-v1.md @@ -614,6 +614,32 @@ Query: - `limit`: non-negative integer, default `100` - `offset`: non-negative integer, default `0` +## GET /vault/entries/{index}/recall + +Purpose: + +Read-only proof that a persisted vault entry is recallable by CORE's *actual* +exact CGA machinery. Rehydrates the persisted `VaultStore` +(`VaultStore.from_dict` — bit-exact versors, no reprojection) and runs the real +`VaultStore.recall` using the selected entry's own stored versor as the query. +The exact `cga_inner` scan — never ANN / cosine / approximate. + +`recall`'s exact-self-match `+inf` sentinel never crosses the boundary: each hit +reports the genuine finite `cga_inner` plus an `exact_self_match` flag. The raw +versor never leaves the engine — only content-addressed digests. The persisted +file is never written and the live runtime is never touched. + +Path parameter: + +- `index`: the entry's `entry_index` (live deque position). + +Errors: + +- Non-integer / out-of-range `index` → `404 not_found`. +- Absent persisted snapshot → `501 evidence_unavailable`. + +See `VaultRecall` in [data-shapes-v1.md](./data-shapes-v1.md). + --- # Evals diff --git a/docs/workbench/data-shapes-v1.md b/docs/workbench/data-shapes-v1.md index 6f0e79d3..f28f6ef3 100644 --- a/docs/workbench/data-shapes-v1.md +++ b/docs/workbench/data-shapes-v1.md @@ -606,6 +606,35 @@ export type VaultEntry = { metadata: Record; versor_digest: string | null; }; + +// One result of CORE's exact CGA recall scan over the persisted vault. +// `cga_inner` is the genuine, finite exact inner product (never a similarity +// proxy). `exact_self_match` flags a byte-identical entry, promoted ahead of +// metric ranking (stored versors are CGA null vectors → ~0 self inner-product). +export type VaultRecallHit = { + entry_index: number; + rank: number; + cga_inner: number; + exact_self_match: boolean; + epistemic_status: string; + epistemic_state: string; + versor_digest: string | null; +}; + +// Read-only proof that a persisted vault entry is recallable by CORE's actual +// exact CGA machinery. `exact_cga` is always true / `approximate` always false: +// this is the exact `cga_inner` scan, never ANN / cosine / approximate ranking. +export type VaultRecall = { + entry_index: number; + query_versor_digest: string | null; + top_k: number; + hits: VaultRecallHit[]; + self_hit_rank: number | null; + self_hit_found: boolean; + exact_cga: boolean; + approximate: boolean; + source_path: string; +}; ``` Vault shapes are available only from persisted `engine_state/session_state.json` diff --git a/docs/workbench/wave-R-mastery-revamp.md b/docs/workbench/wave-R-mastery-revamp.md index 71ddf7ba..816c0403 100644 --- a/docs/workbench/wave-R-mastery-revamp.md +++ b/docs/workbench/wave-R-mastery-revamp.md @@ -222,9 +222,16 @@ versor-condition strip (see journal note below), and the conformance test. primitive); mutation-boundary events visually weighted above routine events. - **Packs** — `GET /packs`, `GET /packs/{pack_id}`; new `TreeView` primitive; manifest checksum displayed with `DigestBadge` (verify affordance). -- **Vault** — `GET /vault/summary`, `GET /vault/entries`; epistemic-state - badges; exact-recall provenance (`cga_inner` evidence shown, never an - approximate score — runtime recall is exact by doctrine). +- **Vault** — `GET /vault/summary`, `GET /vault/entries`, + `GET /vault/entries/{index}/recall`; epistemic-state badges; exact-recall + provenance (`cga_inner` evidence shown, never an approximate score — runtime + recall is exact by doctrine). **Vault P0/P1/P2 complete** (post-wave-R + follow-on): P0 honest empty/unavailable framing (#760); P1 entry-inspector + depth, status/facet/text filters, evidence-rail progression (#762/#763/#764); + P2 read-only exact-CGA recall evidence (#766) — rehydrates the persisted vault + and runs the real `VaultStore.recall`, reporting the genuine finite + `cga_inner` + an `exact_self_match` flag (the `+inf` self-match sentinel never + crosses the boundary). Read-only throughout; no runtime controls. - **Settings** — localStorage prefs + read-only runtime config display; no engine mutation (CLI-only, stated in the UI).