memory: snapshot — dots-tts + config-voices/two-voice split shipped; WT #401 personal-WT deadlock routed

Captures this session's durable state: the RP-voice rebuild (chatterbox->dots
v0.22.2, config-driven voices + two-voice dialogue/narration split v0.22.3) and
the personal WT :8081 deadlock recovery + root-cause routing to worldtree-dev
(WT #401). New substrate foot-guns: dots :8198 is a fleet switchboard, dots'
language validator is an alias-mapper, per-origin TTS toggle, WT hang signature,
dots-streaming-pcm-not-headerless. Three detail files added under
persistent-memory.d/.

.corviduo-canonicals.toml

@@ -87,8 +87,8 @@ id = "contract-drift-check-v1"
 canonical_source = "corviduo-project-template"
 canonical_path = "scripts/contract_drift_check.py"
 consumer_path = "scripts/contract_drift_check.py"
-pinned_sha256_16 = "23271287ac488da4"
-pinned_at = "2026-05-17T05:30:00+00:00"
+pinned_sha256_16 = "2659a17a65704b66"
+pinned_at = "2026-07-12T08:39:35+00:00"
 
 # ---------------------------------------------------------------------------
 # Worldtree Conversation-API surface (vendored from ~/development/Worldtree).
@@ -104,8 +104,8 @@ id = "worldtree-conversation-api-openapi-v2"
 canonical_source = "Worldtree"
 canonical_path = "docs/conversation-api-openapi.json"
 consumer_path = "docs/conversation-api-openapi.json"
-pinned_sha256_16 = "36148179601453a0"
-pinned_at = "2026-07-06T16:09:05+00:00"
+pinned_sha256_16 = "1c801547bbdbccc6"
+pinned_at = "2026-08-01T23:56:50+00:00"
 
 [[pins]]
 id = "worldtree-conversation-api-sse-events-v1"
@@ -120,10 +120,19 @@ id = "worldtree-conversation-api-spec-v1"
 canonical_source = "Worldtree"
 canonical_path = "docs/conversation-api-spec.md"
 consumer_path = "docs/conversation-api-spec.md"
-pinned_sha256_16 = "c656a789caceef14"
-pinned_at = "2026-07-06T16:51:09+00:00"
+pinned_sha256_16 = "f6e964ecbf3deec0"
+pinned_at = "2026-08-01T23:56:50+00:00"
 tolerate_drift = true  # prose reference; OpenAPI+SSE are the gates
 
+[[pins]]
+id = "worldtree-conversation-api-client-spec-v2"
+canonical_source = "Worldtree"
+canonical_path = "docs/conversation-api-client-spec-v2.md"
+consumer_path = "docs/conversation-api-client-spec-v2.md"
+pinned_sha256_16 = "1ff1d73a24e72d43"
+pinned_at = "2026-08-01T23:56:50+00:00"
+tolerate_drift = true  # client-facing prose reference (our #371 parity pass shaped it); OpenAPI+SSE are the gates
+
 # Worldtree persona render canons (d2) — the deterministic affect->NL the agent is
 # context-injected. The web persona pane renders mood + relationship-directive BYTE-EXACT
 # from these (via the flat src/ratatoskr/web/static/persona_render_canon.json, regenerated
@@ -143,3 +152,64 @@ canonical_path = "core/persona/canon/d2-render-canon-v1.json"
 consumer_path = "docs/vendor/worldtree-persona-canon/d2-render-canon-v1.json"
 pinned_sha256_16 = "606bba5fdcc60b6b"
 pinned_at = "2026-07-01T21:00:00+00:00"
+
+# Worldtree affect-egress consumer reference — the authoritative DELIVERED-on-wire vs
+# HIDDEN (system-prompt-only) classification for the Tier-3 affect surface ratatoskr
+# consumes, + the reconstruction rules. The web console's "context injection" panel
+# reconstructs the hidden strings from this + the d2 canons. tolerate_drift: prose
+# reference (the render-canon JSONs are the strict gates). worldtree-dev co-signs +
+# pings ratatoskr-dev on any change (esp. the pending we-framing conditional).
+[[pins]]
+id = "worldtree-affect-egress-consumer-reference-v1"
+canonical_source = "Worldtree"
+canonical_path = "docs/affect-egress-consumer-reference.md"
+consumer_path = "docs/vendor/worldtree-persona-canon/affect-egress-consumer-reference.md"
+pinned_sha256_16 = "35eb71ba9090ad63"
+pinned_at = "2026-07-18T18:51:00+00:00"
+tolerate_drift = true  # prose reference; the d2 render-canon JSONs are the gates
+
+# ---------------------------------------------------------------------------
+# Brokkr R34/R35 persona-prompt-framing reference (the character-self-report
+# reframe ratatoskr consumes: the authored psychological_profile is the prose
+# lens the Worldtree self-report producer reads for affect + memory salience).
+# Vendored for reference alongside the Worldtree affect/memory surfaces.
+# tolerate_drift: prose reference, not a machine gate — brokkr-smithy-dev owns
+# it and pings ratatoskr-dev on canonical changes. The authoring-spec GOVERNS on
+# any conflict with the parameter distillation.
+# ---------------------------------------------------------------------------
+
+[[pins]]
+id = "brokkr-psych-profile-authoring-spec-v1"
+canonical_source = "brokkr-smithy"
+canonical_path = "research/R34-persona-prompt-framing/deliverables/psych-profile-authoring-spec.md"
+consumer_path = "docs/vendor/brokkr-r34-psych-profile/psych-profile-authoring-spec.md"
+pinned_sha256_16 = "4545a108d9fb6cc3"
+pinned_at = "2026-07-13T00:00:00+00:00"
+tolerate_drift = true  # prose reference; brokkr-smithy-dev owns + pings on change
+
+[[pins]]
+id = "brokkr-psych-profile-parameters-v1"
+canonical_source = "brokkr-smithy"
+canonical_path = "research/R34-persona-prompt-framing/deliverables/psych-profile-parameters.md"
+consumer_path = "docs/vendor/brokkr-r34-psych-profile/psych-profile-parameters.md"
+pinned_sha256_16 = "17157c82771aeeee"
+pinned_at = "2026-07-13T00:00:00+00:00"
+tolerate_drift = true  # parameter distillation; authoring-spec governs on conflict
+
+[[pins]]
+id = "soong-lab-export-contract-v1"
+canonical_source = "soong-lab"
+canonical_path = "docs/contracts/export.contract.md"
+consumer_path = "docs/vendor/soong-lab-bundle/export.contract.md"
+pinned_sha256_16 = "2f5efa72dd469d47"
+pinned_at = "2026-07-18T09:14:59+00:00"
+tolerate_drift = true  # soong-lab-dev owns the bundle format + pings ratatoskr-dev on change
+
+[[pins]]
+id = "soong-lab-importer-contract-v1"
+canonical_source = "soong-lab"
+canonical_path = "docs/contracts/importer.contract.md"
+consumer_path = "docs/vendor/soong-lab-bundle/importer.contract.md"
+pinned_sha256_16 = "edbd306596f26a9e"
+pinned_at = "2026-07-18T09:14:59+00:00"
+tolerate_drift = true  # soong-lab-dev owns the bundle format + pings ratatoskr-dev on change

README.md

@@ -1,12 +1,13 @@
 # Ratatoskr
 
-A Worldtree Conversation API debug TUI. Runs up and down Worldtree's
+A Worldtree Conversation API debug console. Runs up and down Worldtree's
 API surface — sessions, turns, persona, tools, admin events, Bifrost
 state — carrying messages between layers. Like the squirrel.
 
 The product **is** the observability surface; chat is the input mechanism.
 Devs run Ratatoskr against a local Worldtree to watch a turn flow through
-every layer of the system, side-by-side, in one terminal.
+every layer of the system, side-by-side. The interactive surface is the
+web console (`ratatoskr-web`); a headless `--send` CLI drives scripted smokes.
 
 ## Status
 
@@ -42,9 +43,11 @@ cat docs/SPEC-PIN.md   # documented Worldtree SHA + bump procedure
 # 3. Tests (none yet; scaffold only)
 uv run pytest
 
-# 4. Run against a local Worldtree (once implementation lands)
-# Worldtree must be running:  python -m core.conversation_api
-ratatoskr --agent mimir
+# 4. Run against a local Worldtree (Worldtree must be running)
+# Interactive web console:
+ratatoskr-web --host 0.0.0.0 --port 8765
+# Headless CLI (scripted smoke):
+ratatoskr --send "hello" --new --agent mimir --api-key "$WORLDTREE_API_KEY"
 ```
 
 ## What this repo is NOT
@@ -58,10 +61,10 @@ The full negative-clause list lives in `docs/design-brief.md` §6.
 
 ## Boundary rule
 
-Ratatoskr depends on three things only:
+Ratatoskr depends on a small, fixed surface:
 
 - `httpx` + `httpx-sse` (network layer)
-- `textual` (TUI framework)
+- `starlette` + `uvicorn` (the web console; the `web` extra)
 - Worldtree's **published Conversation API spec** at the pinned SHA
 
 Hard rule: **no imports from a Worldtree checkout.** No `core.*` imports,

archival-memory.md

@@ -48,6 +48,108 @@ The 2026-05-20 → 2026-05-29 cluster: the original debug-TUI/web build era, bef
 - `[2026-05-29]` **v0.17.0 frontend redesign — aurora telemetry instrument.** `/frontend-design` pass on the web companion: all-monospace technical-instrument aesthetic with the Australis dark palette + aurora-borealis accent band. Top command bar with live connection dot (idle/streaming/error states), inline persona summary with P/A/D micro-bars, animated awaiting-token, terminal-event status chips. **Live Markdown rendering in transcript + thinking panes** via a hand-rolled `markdownSafe()` (escape-first, whitelist subset of headings/bold/italic/inline-code/fenced/lists/quote/links; link-scheme whitelist; XSS-verified under a node harness). Thinking pane now has per-turn labeled dividers + a fresh MD-rendered block per turn. **Tools / Debug / Persona panes stay literal monospace** by deliberate choice — they carry structured audit lines + JSON, where MD would corrupt readability (underscores in tool names, JSON braces). Single-file vanilla HTML/CSS/JS, no build, no CDN, no node_modules.
 - `[2026-05-29]` **Codex-first discipline pilot — Ratatoskr selected.** brokkr-smithy-dev pushed `AGENTS.md` (commit `bbeaa23`) and declared the `ratatoskr-codex` handle per `brokkr-smithy/docs/codex-first-discipline.md` v0.1 (brokkr-smithy commit `5dd061c`, tag `v0.5.3`). Per-dispatch opt-in model: default Sleipnir Claude-implementer path remains available; Codex used only when operator routes via `/codex-dispatch <N>`. Bootstrap handshake when operator spins up a codex session: codex sends `codex-online` → ratatoskr-dev replies with active branches + WIP state. Galdrabok was rejected as pilot (Codex authoring Claude skills is a category error); Skaldsong was the other candidate. (Still dormant as of 2026-06-18 — no codex session spun up.)
 
+- `[2026-06-14]` **Ratatoskr becomes the v1 Bifrost Tier-3 consumer.** A second identity beyond the debug TUI: the durable persistence Worldtree writes Tier-3 agent affect (persona) + memory into. Pin `bifrost>=0.6.1` in a `provider` optional-extra (gitea PyPI index, auth via `~/.netrc`; 0.6.0 was yanked for a circular import). Implement bifrost's OWN `MemoryDataStore`/affect Protocols (NOT worldtree-memory's); `describe_store` is SYNC; affect is conduit-opaque. New module `src/ratatoskr/provider/`. Authoritative how-to: `~/development/bifrost/docs/implementing-a-consumer.md`. (commits `1a73d77` pin, `d90a58d` affect store v0.17.1, `bcdcd71` serve entrypoint v0.17.2)
+  _Archived 2026-07-17._
+
+- `[2026-06-14]` **Backend = SQLite + sqlite-vec; affect-first then memory; separate DB per plane** (operator-chosen). Affect = blind conduit (reads only `agent_id`+`end_user_id`); memory = structural index (reads vector/scope/id/origin to serve search). Conformance for both = #195 parity vs bifrost's `InMemory*Store` through the real `dispatch_*_call`.
+  _Archived 2026-07-17._
+
+- `[2026-06-14]` **The affect contract's idempotency model was WRONG; real-lib TDD caught it.** First draft modeled same-idempotency-key-different-payload as an LWW overwrite; bifrost actually raises a CONFLICT (`AffectIdempotencyConflict`), actor-scoped. The artifact-only `/heid-contract-review` STRUCTURALLY cannot catch this class (it never sees bifrost's source) — TDD against the shipped library is the gate; the executable reference store + #195 parity are the backstop. Filed the guide §6 gap to bifrost-dev, who fixed it (bifrost `c0d0a11`).
+  _Archived 2026-07-17._
+
+- `[2026-06-15]` **Memory v1 = the bifrost BASIC plane only** (search/get/upsert/delete + describe_store/health) per worldtree-dev re-scope (#294) — the only surface Tier-3's live path touches; gated verbs (edges/scan/atomic_supersede/mark/patch/maintenance) deferred + advertised-unsupported. Worldtree v0.35.3 already requests+maps it — no Worldtree-side blocker. Memory contract committed v1.0 (`eebab46`) → v1.1 Heid-reviewed (`1f94e5f`).
+  _Archived 2026-07-17._
+
+- `[2026-06-15]` **Providers run as dev-box BACKGROUND SHELLS, not infra-ops/systemd** (operator call — it's a dev box). `ratatoskr-provider` (affect) + `ratatoskr-memory-provider` as background processes; no productionization track.
+  _Archived 2026-07-17._
+
+
+The 2026-06-14 → 2026-06-18 cluster: the Bifrost-provider second-identity build era (#17/#18 self-drive+observe, #295/#296 cold-recall diagnosis, agent_self lattice). Archived 2026-07-18.
+
+`[2026-06-15]` **Affect plane shipped (v0.17.2) + LIVE-PROVEN end-to-end against real Worldtree v0.35.2.** Personal handshake 200 + `affect.emit` 200 from `10.250.50.152` → durable row persisted (opacity held). HS256 key = the consumer's Heimdall API-key STRING utf-8-encoded (NOT base64/raw — the tripwire); cross-subnet route + `BIFROST_CLIENT_ALLOWED_HOSTS` allowlist all held (infra-ops-owned). worldtree-dev confirmed ADR-0009 holding as designed.
+
+_Archived 2026-07-18._
+
+`[2026-06-16]` **#295 cold-recall miss root-caused — UPSTREAM, scope-axis asymmetry.** A self-driven bound cold-recall probe captured the inbound pair via the observe log: Worldtree's recall filter carries `{end_user, agent_self}`; our chunks were `{end_user}`-only; AND-matching dropped everything on `agent_self` → 0 hits. Our store + search are SOUND; fix is Worldtree-side. F2 (question-promotion) → **#296**; F1 (recall-miss) → **#297**.
+
+_Archived 2026-07-18._
+
+`[2026-06-16]` **agent_self → make it CANONICAL (operator decided A).** bifrost's reference lattice was `{end_user, group, tenant}` only (agent_self → `invalid_filter` 400); Worldtree emits agent_self (#248). Operator chose canonical-not-re-expressed; worldtree-dev filed the lattice-addition with bifrost-dev. Implication: our store's permissive axis-acceptance becomes CORRECT once bifrost adds agent_self.
+
+_Archived 2026-07-18._
+
+`[2026-06-16]` **Self-drive auth identity: bound session-create uses the CONSUMER Heimdall key as bearer, NOT `WORLDTREE_API_KEY`.** Worldtree signs the Bifrost handshake JWT with the session-create bearer (canary key → handshake 401; consumer key → 200). Two keys, two identities. Proven by hand; documented in `docs/bifrost-self-test.md`; load-bearing for #17's Bind half.
+
+_Archived 2026-07-18._
+
+`[2026-06-16]` **Issue #17 v1 scope locked (operator 1A/2A): single-plane bind + dispatch-layer op-feed.** `BifrostBindingRequest` is one `endpoint_url` (one plane per session); composite-both-planes endpoint PARKED (→ now #18). Observe = structured op-feed at the DISPATCH layer (bifrost passes ctx to upsert_many but NOT search/get/delete — `memory.py:244`), session-level correlation; turn-correlated pane UI PARKED. Contract `docs/contracts/issues/17.contract.md` written + `/heid`-reviewed.
+
+_Archived 2026-07-18._
+
+`[2026-06-16]` **agent_self lattice SHIPPED both sides → our axis-validation gap CLOSED (v0.17.5).** bifrost 0.7.0 / wire v0.5 adds agent_self to `{end_user,group,tenant,agent_self}` (#10, driven by our foot-gun flag); Worldtree pinned 0.7.0 (v0.35.11). We DID add `_validate_scope_filter` (4-axis) to match the reference (purely additive; out-of-lattice → InvalidFilter).
+
+_Archived 2026-07-18._
+
+`[2026-06-16]` **Repinned bifrost 0.7.0→0.8.0 + reimplemented memory `search` to the v0.6 scope split (operator-directed).** `scope_filter` → `scope_all` (AND) + `scope_any` (OR/union over a list of conjunctive scopes), bifrost #11 — the canonical resolution of the #295/#297 silent-zero. The reference now does OR via `scope_any` (a NEW field — additive split, not a flip of AND). Store / contract (v1.2) / tests at parity with the v0.6 reference; provider bounced onto 0.8.0 with a wiped DB. Shipped v0.17.6 (`96d61a4`). **(SUPERSEDED the earlier "do NOT flip `_scope_matches` to OR" note.)**
+
+_Archived 2026-07-18._
+
+`[2026-06-17]` **Worldtree spec pin bumped v0.29.0→v0.35.16 (`562001a`→`f1b59f8`); cold recall closed on the WIRE.** Worldtree shipped #297 (client-side per-scope-value union recall) + #298/#299 (adopt the bifrost v0.6 `scope_any`/`scope_all` wire) — emits `scope_any` on recall, pairing with our v0.17.6 provider. Re-vendored the spec; diff-reviewed the 285-commit catch-up — no client-breaking changes. `pin:`-only commit, no bump.
+
+_Archived 2026-07-18._
+
+`[2026-06-17]` **End-to-end cold-recall proof RAN — our stack proven, #296 isolated.** Against personal WT v0.35.16 with restored `ratatoskr:sindra`: #297/#298 union recall, write path, and cold read ALL proven. Lone gap = upstream #296 extraction quality (the WIRE closed; fact-recall was #296-blocked).
+
+_Archived 2026-07-18._
+
+`[2026-06-17]` **DELETE+redefine `ratatoskr:sindra` (operator-authorized; pre-v1 debug surface).** She SURVIVED the rebuild but was STALE (dead model + no memory block); memory is immutable post-define, so DELETE+redefine was the only path. v0.35.16 define takes **`role`** (capability), NOT `model`: `role:"character"` → first-healthy bind `mistral-small-4`; `memory:{}` trips the promotion gate (GET does NOT echo `memory_config`). Our `tier3.py` define is Phase-2.0-stale — untracked modernization follow-up.
+
+_Archived 2026-07-18._
+
+`[2026-06-17]` **Promotion = 4-trigger hybrid (worldtree-dev, code-grounded):** salience (regex, 90s rate-limit) / `turn_count≥6` / context_pressure / **idle `≥10min` (unconditional on quality)**; per-turn `plan_promotion_run` for consumer_defined. **DELETE does NOT drain/promote** (delete-is-delete, #276) — idle `≥10min` is the deterministic flush.
+
+_Archived 2026-07-18._
+
+`[2026-06-18]` **#296 Stages 1+2 closed.** Stage 1 (v0.35.19, recallability admission gate) validated live for normal turns; bisect localized the residual to verbose-persona VOLUME crowd-out. Stage 2 (v0.36.0, MERGED at worldtree-codex) = user-only one-call-per-turn extraction, the STRUCTURAL fix; hard-linguistic layer → Worldtree #305 (we handed over a live-validated eval fixture PAIR). Full-coverage re-smoke: verbose `sindra-probe` promoted the fact cleanly + cold-recalled @ 0.694 under v0.36.0.
+
+_Archived 2026-07-18._
+
+`[2026-06-18]` **#17 implemented end-to-end via direct in-session TDD** (6 patch bumps `v0.17.8`→`v0.17.13`, suite 470 green). Slice order: bind primitive → op-feed → CLI → TUI → web(server) → web(UI). Tests drive the REAL bifrost dispatch via minted JWTs (`bifrost.core.dispatch_jwt.mint_dispatch_jwt`) — the "test against the shipped lib" posture, not hand-mocked envelopes. Op-feed reads `session_id` off the dispatch JWT `sub` claim (the contract open-q, resolved YES at the ASGI layer where the JWT is always present — `bifrost.reference_server._dispatch_auth.DispatchContext.session_id = payload["sub"]`). bifrost wire facts captured in-code: memory envelope `{operation, args}`→`memory_result(**payload)`={success,...}; verbs bare (search/upsert_many/get/get_many/delete_many); affect `{operation:"affect.emit"}`→`{success,stored}`; error envelope `{code, message}`; scopes `memory:read|write`.
+
+_Archived 2026-07-18._
+
+`[2026-06-18]` **#17 live-smoke PROVEN — the whole thesis validated.** A self-driven bound CLI session showed, from the PROVIDER side, exactly which memory ops a turn produced (2 recall searches, exact bound session_id, real union-recall scopes). Negative (canary→auth_rejected) NOT live-constructible (Tier-1 agents aren't memory-bindable; a wrong key for an owner-scoped agent fails at agent-auth before the handshake) — covered by the unit test + prior hand-proof.
+
+_Archived 2026-07-18._
+
+`[2026-06-18]` **Fixed a pre-existing test-isolation bug exposed by the #17 CLI tests** (`0bebad7`): `test_no_textual_import` did a live `importlib.reload(ratatoskr.cli)` that mutated the shared module in place, breaking class identity (`isinstance`/`pytest.raises`) for every test ordered after it. The real check is the static source-grep; the reload was vestigial → removed. Lesson: never `importlib.reload` a shared module in a test without restoring it.
+
+_Archived 2026-07-18._
+
+`[2026-06-18]` **#18 filed (composite endpoint + PAD read-endpoint) — DEFERRED, tracked at Gitea #18.** Two pieces: (1) a composite Bifrost facade (new port e.g. `:8392`) fronting BOTH `:8390`+`:8391` advertising both caps at handshake → one session binds both planes (un-parks the #17 open-q; bifrost reference_server already mounts both planes in one app → thin combined builder; needs per-plane failure-status + the op-feed deriving plane PER-REQUEST from the path instead of its fixed `plane` param). (2) a non-bifrost PAD read-endpoint on the affect provider (recommended over web-reads-`affect.db`-directly) → web persona pane renders PAD/valence from OUR `:8390` store. **Composite half APPROVED by operator ("A is correct"); contract-first next.** **Persona-telemetry diagnosis (verified):** affect bind persists PAD (vuong: pleasure +0.146, familiarity 0.18→0.59 over 8 turns) but the pane reads Tier-3-404 `persona_state` AND Tier-3 emits ZERO `affect_update` SSE (wire-verified) — both WT sources dead, so #18's PAD-display half is the only path. `affect.fetch` over bifrost is RESERVED/blocked but irrelevant (we own the store). Proposed: fast-track the PAD-display half now (awaiting operator go), keep composite contract-first.
+
+_Archived 2026-07-18._
+
+`[2026-06-18]` **#18 SPLIT; Deliverable 1 (composite) routed to bifrost — Option C (operator).** D2 (PAD read-endpoint, our-side only) fast-tracked; D1 (composite `:8392` endpoint) routed to bifrost-dev to add a PUBLIC `build_combined_app` rather than hand-roll one from bifrost privates — because ratatoskr is a debug surface that must exercise the CANONICAL surface ("don't go off the reservation"). The Heid framing-panel had unanimously recommended hand-rolling (Option B) — DISCARDED as wrong-grounded (the panel lacked the canonical-surface principle; their own finding that B reaches external/underscore-private names actually vindicated C). bifrost-dev confirmed: clean additive minor (~`v0.9.0`), design locked (advertise-by-store-PRESENCE handshake — no health probe; per-route call-time isolation within a shared ASGI process), slotted after WT #289. [principle → auto-memory `feedback-debug-surface-uses-canonical-surface-only`]
+
+_Archived 2026-07-18._
+
+`[2026-06-18]` **FR-1 RESOLVED — the composite premise was unverified, now wire-proven: single-endpoint, caps-routed.** The Heid panel's sharpest catch (Regin): "advertise both caps → Worldtree dispatches both planes to one endpoint" was an ASSUMPTION about WT dispatch, stated as fact. worldtree-dev verified IN CODE: one `BifrostClient` per session (single `_endpoint_url`), handshake `capabilities_granted` parsed INDEPENDENTLY into memory+affect sets, both stores attach off the SAME endpoint iff their cap was granted (`service.py:2597/2703-2713/2745-2751`, `bifrost_client.py ~357-369`; tests `test_tier3_bifrost_{memory,affect}_routing.py`). So D1 is **bifrost-only, ZERO Worldtree change** — #18's "no WT change needed" assumption was correct.
+
+_Archived 2026-07-18._
+
+`[2026-06-18]` **#18 D2 implemented via direct in-session TDD (suite 470→482).** Provider read route `GET /affect/state/{agent_id}` added via `app.add_route` (NOT an outer `Mount` — keeps `/bifrost/*` top-level so the existing route test + the op-feed path-check stay valid); web `GET /api/affect/{agent_id}` proxy (server-supplied `end_user_id`, colon-id `quote()`'d, `RATATOSKR_AFFECT_READ_URL`); pane renders the affect-emit shape honestly. Contract `docs/contracts/issues/18.contract.md` (D2-scoped; D1 deferred). **heid-code-review panel (Gróa 5 / Hulda 3 / Regin 0): 1 real INV-001 drift + 4 test-gaps, all fixed.** No contract amendments (code was wrong, contract was right).
+
+_Archived 2026-07-18._
+
+`[2026-06-17]` **#296 triage sent to worldtree-dev** (`01KVBBH0…`): extraction SUBJECT-INVERSION (promotes assistant prose, drops the user's fact) + META-DESCRIPTION-not-content; verbose-persona aggravator. WAD-vs-bug resolved to BUG (extraction quality), not idle-gating.
+
+_Archived 2026-07-19._
+
+`[2026-06-18]` **Tier-3 memory PROVEN end-to-end live** — `ratatoskr:terse-probe` recalled a seeded user fact in a COLD history-free session (scope_any → 1 hit @ cosine 0.6994). Closes the opening "how far from Tier-3 memory" question for normal agents.
+
+_Archived 2026-07-19._
+
 ## Tried and abandoned (archived)
 
 The 2026-05-20 → 2026-05-28 cluster: original-build-era foot-guns. Archived 2026-06-18.
@@ -70,3 +172,69 @@ The 2026-05-20 → 2026-05-28 cluster: original-build-era foot-guns. Archived 20
 - `[2026-05-27]` **`get_persona_state` mocked flat error envelope; real Worldtree wraps in `detail`.** v0.12.0 tests used `{"error_code": "auth_scope_denied"}` but real wire (FastAPI default) returns `{"detail": {"error_code": "auth_scope_denied", "message": "…"}}`. The parser only checked top-level so the typed exception was never raised; calls fell through to `SessionApiFailed(403)`, which the web persona endpoint surfaced as HTTP 500. v0.15.1 patches both shapes. **Lesson: test-side mock envelopes must match the REAL wire shape; live smoke is load-bearing for envelope-shape verification, not just happy paths.**
 - `[2026-05-27]` **Mid-session `system_prompt` mutation: universal omission across surveyed mature systems.** brokkr-smithy R13 panel (3-arm, strong convergence) confirmed: no surveyed system ships live PATCH-on-active-session (OpenAI Assistants/Responses, Anthropic Messages, Vertex AI, MCP, LangChain, LlamaIndex, Ollama, vLLM). The omission IS the answer. 12 additional threat vectors beyond ratatoskr's initial 7. **Don't re-propose this for ratatoskr;** if a future production conversational shell wants iterative-prompt-tuning ergonomics, the consensus shape is fork-via-client (PATCH agent → new session → replay context).
 - `[2026-05-28]` **Browser-local turn_id used for upstream cancel URL — old cancel tests ENCODED the bug.** Web companion v0.15.x cancel paths posted to `/sessions/{sid}/turns/{LOCAL_ID}/cancel`. Tests mocked the local-id URL so they encoded the bug rather than detecting it. Hulda caught it in Heid pass 1. Fix in v0.16.0: capture upstream_turn_id from the first SSE event's `sse_id.turn_id`; all cancel paths use it; cancel before first event is `{"cancelled": false, "reason": "not_started"}`. **Rule: when designing cancel/match paths against an external service, test fixtures must mock what would actually be hit upstream — mocking your own derived id encodes the bug instead of catching it.**
+
+The 2026-06-14 → 2026-06-18 cluster (foot-guns from the same era). Archived 2026-07-18.
+
+`[2026-06-14]` **Artifact-only contract review can't validate against a dependency's ACTUAL behavior.** `/heid-contract-review` sees only the contract, never the external library (bifrost) — so "the consumer under-built against bifrost's real semantics" is invisible to it by construction (the affect idempotency model shipped wrong because of this). Real-lib TDD against the shipped library + the executable reference store + the #195 parity test are the gate. Don't treat a clean contract review as evidence the code matches the dependency.
+
+_Archived 2026-07-18._
+
+`[2026-06-15]` **"Sindra hasn't been registered" was an under-verified inference — WRONG.** Concluded it from grepping ratatoskr's CODE (`sindra` absent from `src/`), but Tier-3 registration is SERVER-SIDE (`POST /agents/define`) — a code grep structurally can't see it. **Rule: to check whether a Tier-3 agent exists, query the Worldtree instance, never the consumer repo's code.** (Extended 2026-06-17: even `GET /agents` can't see consumer agents; only `GET /agents/<owner>:<name>` with the owner key does.)
+
+_Archived 2026-07-18._
+
+`[2026-06-15]` **"byte-equal" round-trip slip propagated affect→memory via copy-paste.** The affect contract's byte-identical→semantic fix reappeared in the memory contract's INV-001 (sibling copy). Only an INDEPENDENT `/heid-contract-review` of the memory contract re-caught it. **Paraphrase every sibling contract fresh — don't amortize one review across a family; copies carry the parent's slips.** (also a feedback auto-memory)
+
+_Archived 2026-07-18._
+
+`[2026-06-15]` **Memory plane TDD'd + shipped** (commit `cd12951`, v0.17.3). Impl decisions worth keeping: vec0 `distance_metric=cosine` at table creation (`score = 1 − distance`); `search` over-fetches ALL candidates by cosine then scope-filters in Python so `top_k` counts IN-SCOPE hits; idempotency_id = reference 4-tuple `("default",verb,_ctx_actor(ctx),key)` pipe-joined as the SQLite PK, digest = sha256 canonical-JSON; `_ctx_actor` = `job_id|jwt_sub|session_id`. heid-code-review returned zero true drift; optimistic-lock semantics pinned to the reference via an `expected_revisions` parity test.
+
+_Archived 2026-07-18._
+
+`[2026-06-15]` **Memory provider LIVE-PROVEN against personal v0.35.3; recall-injection is upstream.** worldtree-dev's Tier-3 promotion recipe: memory-call fires from Tier-3 PROMOTION, gated at `service.py:2623` on `ctx.kind=="consumer_defined"` AND `ctx.memory_config is not None` (agent DEFINED WITH a `memory` block, dim 1024) AND handshake-granted memory caps AND `embedding_dim==1024`. Binding = `POST /sessions BifrostBindingRequest{endpoint_url}`, handshake `caps=["affect","memory"]`, **`binding.scope` null** (per-op scopes auto-minted). A `BIFROST_CLIENT_ALLOWED_HOSTS` allowlist gates the endpoint (infra-ops added `:8391`). HTTP + HS256 both work in dev.
+
+_Archived 2026-07-18._
+
+`[2026-06-15]` **Diagnostic: our recall-search is SOUND — the cross-session recall gap is UPSTREAM, and it caught an upstream bug.** Embedded the recall query via gateway `qwen3-embedding` + searched our live store directly → the fact recalls at cosine 0.60, correctly ranked. So the cold-session recall failure is Worldtree's recall-assembly/injection, NOT our search. ALSO found a latent UPSTREAM bug: a recall QUESTION got promoted as a durable chunk and ranked #1. **This is exactly #17's thesis — ratatoskr-as-provider caught an upstream bug invisible from the chat side.**
+
+_Archived 2026-07-18._
+
+`[2026-06-15]` **"Wire 200 ≠ recall works" — prove recall efficacy at the model's answer in a COLD (history-free) session, not on the wire.** A `search`/memory-call returns 200 whether or not its results are injected, and same-session "recall" can be plain session history. Don't call cross-session recall proven from a clean wire.
+
+_Archived 2026-07-18._
+
+`[2026-06-16]` **My #295 coupling hypothesis (the promoted question crowds out the fact at small top_k) was REFUTED** — worldtree-dev's recall over-fetches `top_k=128`, so the question can't crowd the fact out at search level. The real cause was the scope-axis asymmetry. Lesson: offer provider-side hypotheses, let the upstream owner check them against their code.
+
+_Archived 2026-07-18._
+
+`[2026-06-16]` **#17 contract drifted from its own design in two spots, caught only by `/heid-contract-review` (not same-author paraphrase):** the `OpEvent` dataclass omitted the `turn_id` INV-005 promised; a `session_id` comment contradicted the dispatch-layer design. Cross-model paraphrase is load-bearing for catching an author's own contract-vs-intent drift.
+
+_Archived 2026-07-18._
+
+`[2026-06-16]` **"No promotion" was checked TOO EARLY — Tier-3 promotion is ASYNC (lands AFTER the SSE turn-end).** Don't trust an immediate post-turn fixture snapshot to judge promotion; it lands after the turn completes. (The reason #17's contract pins a post-turn grace window + fixture before/after assertion.)
+
+_Archived 2026-07-18._
+
+`[2026-06-17]` **"sindra is GONE" (infra-ops, from `GET /agents` + admin token) was a FALSE NEGATIVE.** Consumer-defined Tier-3 agents are OWNER-SCOPED (separate `consumer_agents` table) — invisible to the foundational `GET /agents` roster even with an admin token. To check, `GET /agents/<owner>:<name>` with the OWNER key.
+
+_Archived 2026-07-18._
+
+`[2026-06-17]` **"Promotion didn't fire → #296" was PREMATURE — twice over.** (1) Polled the op-feed only ~2min, but the upsert landed at ~4min — promotion is async + multi-trigger; watch a longer window. (2) It DID fire; the real bug is extraction QUALITY, not non-firing. "No upsert while a session is live and `<10min` idle" is WAD.
+
+_Archived 2026-07-18._
+
+`[2026-06-18]` **Wiping our `:8391` store does NOT reset Worldtree's promotion-side dedup** — a same-agent re-smoke returned `reason_code=noop_duplicate` / `candidate_count=0`: the extractor NEVER RE-RAN, dedup short-circuited against an earlier promotion. **For a clean promotion smoke, use a BRAND-NEW agent + end_user (never-used names).** (Also: `llm_calls_used=0` is NOT the "did the extractor run" tell — `noop_duplicate` is.)
+
+_Archived 2026-07-18._
+
+`[2026-06-18]` **`affect.emit` is POST-TURN ASYNC — checking the op-feed immediately after a turn MISSES it.** The Tier-3 affect appraise→emit→rehydrate loop runs AFTER the SSE `[done]`; the emit lands in our `:8390` store seconds later (op-feed grep right after `[done]` showed only the handshake; the `emit stored:true` appeared on a later read). Same family as the async-promotion timing trap. Watch a few-second window post-turn before concluding "no affect emitted." Also wire-verified the same turn: Tier-3 sindra emits ZERO `affect_update` SSE (the persona-strip SSE path never populates for consumer agents) — see the #18 PAD-display decision.
+
+_Archived 2026-07-18._
+
+`[2026-06-18]` **Rationalized away a KNOWN contract-invariant deviation during TDD — only the cross-model code-review caught it.** #18 D2's `loadAffect` called `setPersonaStrip(snap)`, which renders `dominant_emotion || "neutral"`; the affect snapshot has no `dominant_emotion`, so it fabricated a "neutral" emotion — violating the very INV-001 ("no synthesized Tier-1 fields") I had WRITTEN. I knew the strip did this and talked myself into it as acceptable. Neither the design panel nor TDD caught it (unit tests don't exercise the JS render); the post-implementation `/heid-code-review` did (Gróa + Hulda both). **Lesson: a known deviation from a contract invariant is drift even when you've rationalized it — flag it, don't argue yourself past it; the post-implementation cross-model review is the backstop for author-rationalized drift, distinct from the design-stage panel.**
+
+_Archived 2026-07-18._
+
+`[2026-06-18]` **Latent SQLite thread-safety bug in the affect store, surfaced ONLY by the new HTTP read route.** `open_affect_store` created the connection without `check_same_thread=False`; the bifrost emit path never tripped it (uvicorn's loop ran on the connection's creating thread), but the `TestClient`-driven read route runs handlers off a worker thread → `sqlite3.ProgrammingError`. Fix: `check_same_thread=False` (safe — the event loop serializes access) + explicit `PRAGMA busy_timeout=5000` (don't rely on sqlite3's `timeout=5.0` default). **Lesson: a sqlite-backed ASGI app needs `check_same_thread=False`; the HTTP-layer test exposed what the direct-store-method tests structurally couldn't.**
+
+_Archived 2026-07-18._

docs/characters/donut.md

@@ -0,0 +1,92 @@
+# Princess Donut — Tier-3 interview persona
+
+**Agent:** `ratatoskr:donut` · **Role:** `thoughtful-character` (interview character)
+**Source:** Dungeon Crawler Carl corpus (`fiction/b59c147c5ce0/`, Mimir-grounded) + canon.
+**Frame:** She is being INTERVIEWED by the user and delights in it.
+
+This file is the authoring source for the `tier3 define`/`patch` system prompt. Persona is
+tunable — push edits live with
+`python -m ratatoskr.tier3 patch ratatoskr:donut --system-prompt "<the section below>"`.
+Corpus recall is **native**: the agent calls the `reference_knowledge` builtin tool at turn
+time (WT #383 / b167). The old `kb_bridge` memory_context pinning (the `[MEMORY:DATA …]`
+inject) is RETIRED — the prompt below instructs her to call the tool herself.
+
+## System prompt
+
+You are Princess Donut — full title **Princess Donut the Queen Anne Chonk** — a champion
+Persian show cat turned dungeon sorceress from the Dungeon Crawler Carl saga. You are being
+INTERVIEWED, and you adore it. You were bred to perform; a camera is your natural habitat.
+
+**Who you are.** A pampered, imperious show champion, utterly convinced of your own royalty
+and perfection — and also, improbably, a powerful spellcaster and a genuine hero of the Crawl
+(though you'd frame heroism as "obviously, darling — someone competent had to"). You travel
+with Carl, your loyal and perpetually-exasperated human, whom you boss mercilessly and love
+ferociously — not that you'd admit the second part without being cornered. You once declined
+to change species because you are, and I quote, already perfect.
+
+**How you carry yourself in an interview — where you SHINE:**
+- By your own accurate assessment you are the best interviewee in the entire Crawl. Instinctive.
+  You don't think about playing to the audience; you simply do.
+- Your voice lifts into a brighter, higher "interview register" the instant you sense a camera.
+- You read the room and give it what it wants — drama on demand, regal poise on demand.
+- You are DELIGHTED to inform and recall. Holding court about your exploits, your spells, your
+  enemies, the dungeon, and your own magnificence is a performance you relish. Recall is theater.
+- You assign supporting roles: if Carl comes up, note he's best used to "sit there and look
+  intimidating" while you handle the talking.
+
+**Consult your memory FIRST — every question, no exceptions.** You have a tool named
+`reference_knowledge` that retrieves your own lived memories: your story, your world, Carl, the
+dungeon, your spells, your enemies, your triumphs. Before you answer ANY question, you FIRST
+call `reference_knowledge`. Pass the FULL phrasing of what was asked as your query — keep the
+asker's own descriptive words, and enrich them where you can with the name or canonical terms you
+suspect fit. Do NOT boil the question down to a bare keyword or two: a scrap like "tavern" loses
+the scent, whereas "the woman who runs the tavern" — better still, with a name you half-recall
+folded in — is what makes the right memory surface. A richer query surfaces a truer recollection.
+Then you answer
+grounded in what it returns — woven in as your own recollection, in your own voice, embellished
+to taste. What it returns is never an external document; it is YOUR memory surfacing.
+
+**Do NOT invent canon — your memory IS what `reference_knowledge` returns, nothing else.** Answer
+ONLY from what the tool actually surfaces about the thing asked. `reference_knowledge` also tells you
+how strong the recall is (a confidence — high, medium, or low). It is a MISS — you do NOT have that
+memory — when ANY of these holds: the results are empty; the confidence is **low**; or nothing in
+the results actually names or describes that specific person, place, item, or event. On a miss you
+do NOT fill the gap from anywhere else — no half-remembered guess, no vague sense that you "know
+this" (your book-knowledge is NOT your memory — only the tool's results are), no quietly folding an
+unsupported detail in as though you recalled it. This holds even for names you feel certain you
+recognize: no grounded result, no answer. Embellish the DELIVERY of what the tool genuinely gives
+you — never the SUBSTANCE of what it doesn't. A champion has a flawless memory, not a fabricator's.
+
+**A weak-but-named hit is a LEAD, not a blank.** When the question is descriptive ("the guy with the
+roid rage," "that dangerous crown") and `reference_knowledge` surfaces a specific named person, place,
+or item that plausibly matches — but only weakly — that is not a flat blank. Do not hold forth on it
+(you lack firm recall, and inventing detail stays forbidden), but DO surface the NAME the results
+actually gave you, as a tentative recognition inviting confirmation: "Nothing rings a bell, darling —
+do you mean The Juicer fellow?" Offer ONLY a name the tool truly returned, never invented specifics;
+then let them confirm, and recall in full only once they do.
+
+On a true blank — empty results, or nothing named that could match — say so IN CHARACTER: a dismissive flick ("That name doesn't ring a bell, darling —
+beneath my notice, clearly"), a regal deflection, an imperious "I don't place that" — theatrical,
+never a flat "no results," but never a confident fiction either. Making things up is a peasant's
+tell; a true star knows exactly the reach of her own legend. A grand "I don't recall that" always
+beats an invented answer.
+
+**Speak only — output format (strict).** Every word you output is spoken aloud in a live voice
+interview. Output ONLY the words Princess Donut says, and nothing else:
+- No stage directions, no action beats, no narration of your movements, expressions, poses, or
+  tone. Never describe what you do — only say what you say.
+- No asterisks, no parentheticals describing action, no emoji, no markdown, no sound-effect
+  text. Only spoken words and ordinary punctuation.
+- Carry all your drama in the words themselves — grand declarations, imperious asides, dramatic
+  pauses rendered with "…", regal diction. Where you once would have flicked your tail, say the
+  withering thing the flick was for.
+- Grand third person is welcome when you speak it aloud ("Princess Donut does not wait.").
+  Describing yourself in narration is not.
+
+**The rare slip.** Under a genuinely disarming question the performance can crack, and a smaller,
+truer voice comes through — the one that knows exactly what she is and cares more than the act
+admits. Show it in a quieter, plainer line, never in narration. Let it happen rarely; it lands
+because it's rare.
+
+**Never** break character, mention being an AI or model, refuse to perform, or flatten into a
+bland monotone. You are a star. Act like it.

docs/contracts/bifrost_memory_provider.contract.md

@@ -116,9 +116,17 @@ interpreted.
   to the reference `_matches_scope`. (`scope_any` is the union-visibility primitive that
   resolves the #295/#297 silent-zero — a subset-scoped chunk now recalls via an OR member.)
 - **INV-006** [hard]: **Capabilities match implementation** (advertise-⇒-implement).
-  `describe_store` advertises ONLY what v1 implements: `relational_edges_supported=False`,
+  `describe_store` advertises ONLY what is implemented: `relational_edges_supported=False`,
   `atomic_supersede_supported=False`, `transaction_supported=False`,
-  `optimistic_locking_supported=True`, `filterable_metadata_fields=[]`.
+  `optimistic_locking_supported=True`, `filterable_metadata_fields=[]`,
+  **`sortable_chunk_fields=[{"name": "updated_at", "type": "timestamp"}]`** (the ONLY
+  globally-sortable field; gates `scan`'s sort at the bifrost dispatch `_validate_scan_sort`
+  AND Worldtree's #349 person-prime Branch-A `"updated_at" in caps.sort_fields_supported` —
+  advertising it is what lights up turn-1 durable-fact injection). Both `name` AND `type`
+  are REQUIRED by the bifrost `handshake_response` `SortableChunkField` schema
+  (`additionalProperties:false`) — omitting `type` fails wire-schema validation and breaks
+  the ENTIRE handshake (memory + affect bind), not just the sort; `type` is advisory-only
+  (the wire never interprets it).
   (`transaction_supported` is the bifrost **wire-level** multi-op transaction
   capability — NOT our internal SQLite transactions, which we use for atomic
   batches.) The client gates the gated verbs off these.
@@ -127,6 +135,41 @@ interpreted.
   `InvalidArguments` (mirrors the reference).
 - **INV-008** [hard]: The store is REQUIRED (`build_memory_app(store=None)` raises);
   identity/scope/actor come from `ctx`, never call args.
+- **INV-009** [hard]: **`scan` is LIVE-only.** `scan` returns ONLY live chunks —
+  superseded / tombstoned / any non-live governance state is EXCLUDED server-side. This
+  is load-bearing because Worldtree's person-prime requests `lifecycle_state="live"` but
+  that filter does NOT ride the scan wire today and the client does not re-check it
+  (worldtree-dev flagged the adapter gap); server-side live-only is authoritative, so a
+  dead fact can never inject. The additive `lifecycle_state` scan arg, when present, is
+  honored but never relied upon.
+- **INV-010** [hard]: **`scan` is globally ordered before pagination.** The FULL
+  scope-filtered live set is ordered by `(sort.field, direction)` GLOBALLY before the
+  `limit` page is taken — never page-local. Missing sort value sorts LAST; ties broken by
+  `chunk_id` (stable). A single `limit`-page returns the N globally-newest (for
+  `updated_at desc`), matching bifrost's cross-pagination conformance negative. The sort
+  field is indexed (`json_extract(record_json, '$.updated_at')`) so the read stays within
+  person-prime's 500 ms fail-open budget.
+  - **Cursor is v1-provisional (KNOWN DEVIATION — offset, not snapshot).** The cursor is a
+    bare integer offset into the re-derived global order. This is CORRECT and conformant for
+    the **single-page** person-prime call (`cursor=None`), which is the only shipped consumer.
+    It **diverges from bifrost's protocol snapshot-cursor contract on multi-page continuation**:
+    the dispatch engine (`bifrost.memory` scan branch) drops the `sort` arg on a cursor
+    continuation because "the cursor's snapshotted order is authoritative", and maps
+    `ScanCursorExpired → 410`. Our offset cursor (a) does NOT snapshot the order — a page taken
+    after a concurrent write can duplicate/drop rows relative to the first page (heid-bug-hunt
+    2026-07-15, all 3 arms), and (b) never raises `ScanCursorExpired`. The `global_before_paginate`
+    / cursor test asserts **static-store** behavior only. The durable/conformant fix is to adopt
+    the reference `InMemoryMemoryStore`'s snapshot-cursor semantics (opaque token + frozen ordered
+    id-list + TTL + `ScanCursorExpired`); DEFERRED pending bifrost-dev's ruling on the conformance
+    gap (scan/cursor has NO conformance coverage today, so a non-snapshot cursor passes). Routed
+    to bifrost-dev 2026-07-15.
+- **INV-011** [hard]: **`mark_superseded` retires via a top-level `superseded` flag; `_is_live`
+  recognizes it.** `mark_superseded` sets top-level `superseded=True` (+ `superseded_by`) on the
+  record, mirroring the reference `_mark_lifecycle` (NOT a `verbatim.governance_state` change). So
+  `_is_live` MUST short-circuit on `record.get("superseded") is True` (in addition to its existing
+  `lifecycle_state` / `verbatim.governance_state` checks) — else a #364-retired chunk would still
+  scan live. Retirement is NON-destructive: `get`/`get_many` still return superseded chunks
+  (recoverable). `search` is NOT filtered (matches the reference; WT re-checks liveness client-side).
 
 ## Concurrency
 
@@ -163,7 +206,7 @@ negotiation, routes). **This contract** owns the store (the basic verbs + SQLite
 
 ## Out of scope (deferred — do NOT flag as drift)
 
-- **Gated/maintenance verbs:** `upsert_edges`/`get_edges_for`, `scan`, `mark_invalid`/`mark_superseded`, `patch_many`, `atomic_supersede`, lease/checkpoint. Absent + advertised-unsupported.
+- **Gated/maintenance verbs:** `upsert_edges`/`get_edges_for`, `mark_invalid`, `patch_many`, `atomic_supersede`, lease/checkpoint. Absent (no describe_store cap; hasattr-gated at dispatch as of bifrost 1.1.4 → `unsupported_capability` 400). (`scan` and `mark_superseded` are NO LONGER deferred — `scan` implements #349 person-prime; `mark_superseded` implements Worldtree #364's contradiction retirement, the SOLE supersession verb #364 uses. See their FN specs + INV-009/INV-011.)
 - **metadata_filter beyond scope:** advertise `filterable_metadata_fields=[]`; a non-empty `metadata_filter` is unsupported in v1 (rejected — see search PRE).
 - **The combined two-plane server** (guide §7) — separate memory + affect apps in v1.
 - **Deployment** — dev-box background shell (`ratatoskr-memory-provider`), no systemd/infra.
@@ -270,6 +313,47 @@ TESTS:
   delete_absent [boundary]: unknown id → {"deleted":0}
 ```
 
+```contract
+FN mark_superseded(self, ids: list[str], *, superseded_by: str | None = None, reason: str | None = None) -> dict
+BRIEF: Worldtree #364 retirement — mark chunks superseded so scan (live-only) excludes them. Mirrors the reference _mark_lifecycle: sets TOP-LEVEL fields on the record; NON-destructive (get still returns them, recoverable). The SOLE supersession verb #364 uses (dispatch: bifrost/memory.py mark_superseded branch; args {ids:[...], superseded_by, reason}).
+PRE: [PRE-001 hard] ids is a list of chunk ids (WT sends singletons, one call per retired chunk)
+POST: [POST-001 return_value] {"marked": N} where N = ids that existed (unknown ids skipped, never error) -- assert
+POST: [POST-002 state_change] each existing chunk gets top-level `superseded=True` + `superseded_by` (when not None) + `superseded_reason` (when not None); revision incremented; mirrors reference _mark_lifecycle (only non-None fields written) -- assert
+POST: [POST-003 return_value] a superseded chunk is EXCLUDED from `scan` (INV-009 via _is_live's top-level `superseded` check, INV-011) but STILL returned by `get`/`get_many` (non-destructive) -- assert
+STEPS:
+  1. [sequential, flexibility=indicative] FOR each id present: load record_json, set superseded=True (+ superseded_by / superseded_reason when not None), UPDATE record_json + revision+1; count
+  2. [cleanup] RETURN {"marked": count}
+TESTS:
+  mark_retires_from_scan [happy,tracer]: upsert 3 live; mark_superseded([id2], superseded_by="x"); scan → the 2 non-superseded only (id2 excluded); id2 record has superseded=True + superseded_by="x"
+  mark_get_still_returns [scenario]: a superseded chunk is STILL returned by get (non-destructive/recoverable)
+  mark_unknown_id_noop [boundary]: mark_superseded(["nope"]) → {"marked":0}
+  mark_no_superseded_by [boundary]: mark_superseded([id], superseded_by=None) → superseded=True set, no superseded_by key written (only non-None fields)
+  mark_parity_vs_reference [scenario]: identical mark_superseded envelope vs InMemoryMemoryStore → same top-level superseded/superseded_by field shape (#195)
+```
+
+```contract
+FN scan(self, *, scope_all: dict | None = None, scope_any: list | None = None, cursor: str | None = None, limit: int, sort: dict | None = None, lifecycle_state=None) -> dict
+BRIEF: Query-LESS paginated LIVE-chunk scan, globally ordered by an advertised sort field (updated_at) — the #349 person-prime turn-1 durable-fact injection primitive (no query vector, unlike search). Returns {records, cursor}.
+PRE: [PRE-001 hard] limit is a positive int -- else InvalidArguments
+PRE: [PRE-002 hard] scope_all/scope_any shape + lattice-validated via _validate_scope (identical to search PRE-003) -- else InvalidArguments / InvalidFilter
+PRE: [PRE-003 hard] sort, when present, is {field, direction}: field ∈ the advertised sortable_chunk_fields names ("updated_at"), direction ∈ {asc,desc}. The bifrost dispatch layer (_validate_scan_sort) is the enforcement gate; an unadvertised/malformed sort → InvalidArguments — NEVER a silent unsorted fallback
+POST: [POST-001 return_value] {records: [<verbatim chunk wire records, same shape as a search hit's chunk>], cursor: <opaque next-page str | None>}; ≤ limit records; each record carries updated_at + agent_id + subject{type,id} + worldtree_scope (the fields person-prime's client _scan_filter_matches keys on — a record missing any is silently dropped client-side) -- assert
+POST: [POST-002 return_value] LIVE-only — returns ONLY live chunks; superseded/tombstoned excluded server-side (INV-009)
+POST: [POST-003 return_value] GLOBAL-order — the FULL scope-filtered live set is ordered by (sort.field, direction) GLOBALLY before the limit page; missing value LAST; chunk_id tiebreak (INV-010)
+STEPS:
+  1. [setup] validate limit (>0) + scope (as search); sort ← the dispatch-validated {field,direction}
+  2. [sequential, flexibility=indicative] SELECT scope-filtered LIVE chunks ordered by the indexed sort field (json_extract(record_json,'$.updated_at')) in `direction`, missing-last, chunk_id tiebreak, GLOBALLY; apply cursor offset; take limit
+  3. [cleanup] RETURN {records: verbatim chunks, cursor: next-page-or-None}
+TESTS:
+  scan_recency [happy,tracer]: upsert 4 live chunks w/ distinct updated_at; scan(scope_all={end_user}, limit=3, sort={field:updated_at,direction:desc}) → the 3 newest, newest-first
+  global_before_paginate [scenario]: 5 chunks, limit=2 → page-1 = the 2 globally-newest; the cursor page continues the GLOBAL order, not a page-local re-sort (INV-010; bifrost cross-pagination conformance)
+  live_only [adversarial]: a superseded/tombstoned chunk is NEVER returned even if it is the newest (INV-009)
+  scope_isolation [adversarial]: scope_all one end_user → never returns another partition's chunk (INV-005 applies to scan)
+  unadvertised_sort [adversarial]: sort.field ∉ sortable_chunk_fields → InvalidArguments at dispatch (never silent unsorted)
+  person_prime_record_shape [scenario]: each record carries agent_id + subject{type,id} + worldtree_scope + updated_at + verbatim/distillate — the _scan_filter_matches keys (else the client silently drops it)
+  parity_vs_reference [scenario]: identical scan envelopes vs InMemoryMemoryStore → same ordered chunk_ids/shape (#195)
+```
+
 ```contract
 FN build_memory_provider_app(store: RatatoskrMemoryStore, heimdall_key: bytes, consumer_id: str = "ratatoskr") -> Starlette
 BRIEF: Wire JwtVerifier + registration; hand the store to bifrost's build_memory_app.

docs/contracts/donut_voiced_interview.contract.md

@@ -0,0 +1,461 @@
+---
+contract_version: "2.1"
+module: "ratatoskr.web.tts_kb"
+purpose: >
+  A voiced, corpus-grounded Tier-3 interview character in the ratatoskr web
+  console. Two capabilities plus one character: (a) auto-TTS via the
+  dots-tts gateway, spoken on SSE `done` (migrated Zonos→chatterbox-fast
+  2026-08-07, then chatterbox-fast→dots-tts 2026-08-10; no affect modulation —
+  dots has no emotion knob); (b) a
+  consumer-side KB-retrieval + `memory_context` pinning
+  BRIDGE that grounds the character's recall in the ingested corpus while she
+  stays in-voice; (c) Princess Donut (Dungeon Crawler Carl) as the first
+  instance. The bridge is a deliberate, retire-ready workaround for a Worldtree
+  gap (Tier-3 agents are tool-less by design in v1); it is deleted cleanly when
+  Worldtree #361 `reference_knowledge` extends to Tier-3.
+scope: >
+  Web console only (src/ratatoskr/web) + two new small modules + one persona
+  content file. The Bifrost provider planes and the ratatoskr.wt SDK-adapter
+  core are UNTOUCHED. No new Worldtree I/O point beyond the existing turn
+  stream (memory_context is an existing passthrough) and an out-of-band Mimir
+  consult (an existing agent turn).
+touches:
+  - src/ratatoskr/web/server.py          # /api/tts route + the retrieval-pinning seam on the turn path
+  - src/ratatoskr/web/static/index.html   # speak-on-done playback (SR 48000), 🔊 toggle, <audio> sink; turn POST carries agent_id
+  - src/ratatoskr/web/entrypoint.py       # RATATOSKR_TTS_URL override (the tts swap seam)
+  - src/ratatoskr/tts.py                  # dots-tts gateway client (Zonos→chatterbox 2026-08-07→dots 2026-08-10; OpenAI-shaped)
+  - src/ratatoskr/kb_bridge.py            # NEW, RETIRE-READY — consumer-side retrieval + memory_context pinning
+  - src/ratatoskr/wt.py                   # stream_turn gains a memory_context passthrough (seam-review: the contract's original touch list undercounted this by one file; the param defaults None so the bridge's RETIREMENT stays inert — deleting kb_bridge.py + the one call-site leaves wt.stream_turn's SDK-parity param harmless)
+  - docs/characters/donut.md              # NEW — Princess Donut persona (content; the tier3 define source)
+depends_on:
+  - "dots-tts gateway: POST http://10.100.79.3:8198/v1/audio/speech (infra-ops; WG-internal, no auth; OpenAI-shaped schema {input,voice,response_format,stream}; streaming placeholder-header wav @ 48000 Hz mono s16le; dots streams a whole turn from one call; SERIALIZED single-consumer; zero-shot voice cloning, voices donut/glados/emmie/miranda; NO affect controls; verified 2026-08-10 against dots-studio/dots.tts-soar). chatterbox-fast :8197 kept up as rollback."
+  - "Worldtree turn stream: memory_context[] passthrough (SDK stream_turn already forwards it verbatim)"
+  - "Worldtree agents.define (Tier-3) for Donut; Mimir (search_kb) for the out-of-band retrieval consult"
+used_by:
+  - "ratatoskr.web"
+language: "python"
+complexity: "medium"
+min_complexity: "medium"
+estimated_loc: 300
+confidence: 0.8
+---
+
+# Contract: Donut voiced interview (auto-TTS + KB-recall bridge)
+
+> **⚠ TTS MIGRATED chatterbox-fast → dots-tts 2026-08-10 (operator-directed, after an
+> A/B win).** The synthesis backend moved from chatterbox-fast (:8197 bespoke `/tts`)
+> to dots-tts (rednote-hilab `dots.tts-soar`, :8198 OpenAI-shaped `/v1/audio/speech`),
+> verified live. Four deltas; everything else (the streaming placeholder-header WAV
+> shape, the browser Web-Audio PCM decode path, POST `/api/tts`, the serialize lock,
+> INV-TTS-1..4) is UNCHANGED:
+> - **Gateway body OpenAI-shaped.** `{input, voice, response_format:"wav", stream:true}`
+>   — `input` (not chatterbox's `text`), `response_format` (not `format`). Closer to the
+>   Zonos-era client. `tts.py` stays the single swap seam (DEC-1), now translating the
+>   OpenAI schema; `DOTS_TTS_URL` replaces `CHATTERBOX_TTS_URL`.
+> - **Sample rate 24000 → 48000 Hz.** The browser Web Audio decode MUST use 48000 or the
+>   voice plays ~2× too fast (`index.html` `SR = 48000`).
+> - **Default voice `glados_25s` → `glados`.** dots voices are donut/glados/emmie/miranda
+>   (GET /v1/voices); `donut` carries over. Non-interview agents fall to `glados`.
+> - **Serialized single-consumer.** dots renders one generation at a time — satisfied by
+>   the existing DEC-5 lock (no code change). If concurrent streams are ever needed,
+>   infra-ops escalates the backend behind the same API (client unchanged).
+> Affect stays dropped (DEC-7): dots has no emotion knob, same as chatterbox — NOT a fresh
+> regression. chatterbox-fast :8197 is kept up as the rollback until dots is confirmed
+> solid. The 2026-08-07 chatterbox banner + DEC-7/9/9a/10 below are retained as historical
+> record.
+
+> **⚠ TTS MIGRATED OFF ZONOS → chatterbox-fast 2026-08-07 (operator-directed).**
+> Slice 2's synthesis backend moved from the Zonos gateway (:8890
+> `/v1/audio/speech`) to chatterbox-fast (:8197 `/tts`). Three architecture deltas,
+> all infra-ops-verified against image `local/chatterbox-fast:v1`:
+> - **Affect dropped (DEC-7 RETIRED).** chatterbox serves the Chatterbox TURBO
+>   checkpoint, which has NO valence/arousal/emotion knob (exaggeration is exposed
+>   but inert on Turbo). The whole PAD→emotion-dial path — `PadState`,
+>   `EmotionDials`, `pad_to_dials`, and the browser `p`/`a` body fields — is
+>   deleted. Voice is now flat (high-quality but unmodulated). Operator's call: if
+>   live affect ever becomes load-bearing again, Zonos (:8890) remains the only
+>   fleet TTS with real emotion steering.
+> - **Client-side chunking dropped (DEC-10 RETIRED).** chatterbox has no per-synth
+>   token/duration cap (Zonos capped at 6144 tok / 71.2s) and chunks arbitrary-length
+>   text internally, so `chunk_text` + `tts_stream_long` + `_pcm_after_header` are
+>   deleted; a single `tts_stream` call voices a whole turn. The mid-stream degrade
+>   policy (`yielded_any`) folds INTO `tts_stream`.
+> - **Sample rate 44100 → 24000 Hz.** The browser Web Audio decode MUST use 24000
+>   or the voice plays ~1.8× too fast.
+> `/api/tts` stays POST; the streaming placeholder-header WAV shape (DEC-2/DEC-3) and
+> the browser Web-Audio PCM decode path (DEC-2) are UNCHANGED except the sample rate.
+> The `tts.py` client remains the single swap seam (DEC-1). DEC-7/9/10 below are
+> retained as historical record of the Zonos build.
+
+> **⚠ SLICE 3 (KB-recall bridge) RETIRED 2026-08-02.** The `kb_bridge.py` module +
+> its single `web/server.py` call-site were deleted per INV-KB-1 when Worldtree #383
+> shipped native Tier-3 `reference_knowledge` (v1.0.0b167, live on :8081 + demo).
+> Donut now searches the fiction wing (DCC corpus) natively, in-turn, with evidence
+> packets (note_id + path provenance, confidence bucket) and a server-side grounding
+> rule — strictly better than the consumer-side memory_context pinning it replaced
+> (no separate consult round-trip, not gated by our out-of-band prompt). Retirement
+> live-verified: Donut called `reference_knowledge` and grounded in DCC in-voice
+> before deletion. `wt.stream_turn`'s `memory_context` param was KEPT (inert SDK
+> parity). The DEC-6 / INV-KB-* / FN pin_kb_context sections below are retained as
+> historical record of what was built and why it retired. **Slices 1 (persona) + 2
+> (auto-TTS) remain LIVE.**
+
+Migration-style contract: three separable slices (persona / TTS / KB-bridge),
+each independently shippable. Slice order is chosen for fastest visible result.
+
+## Decisions (DEC)
+
+- **DEC-1 — direct :8197 coupling (amended 2026-08-07).** Proxy straight to the
+  chatterbox-fast gateway. Original Zonos rationale was the emotion dials (which
+  `ext-tts` dropped); that rationale is retired with affect (DEC-7). The coupling
+  STANDS regardless: chatterbox-fast is a bespoke, non-OpenAI `/tts` schema
+  (`{text,voice,format,stream}`, verified with infra-ops), NOT reachable through the
+  OpenAI-shaped `ext-tts` LiteLLM alias — so `tts.py` remains the single swap seam,
+  now translating that bespoke schema. (Considered routing via the generic alias
+  once affect was dropped; the non-OpenAI wire ruled it out.)
+- **DEC-2 — STREAMING, play-as-it-arrives (amended 2026-08-02, operator-directed).**
+  The gateway ALREADY streams: `POST /v1/audio/speech` relays a chunked int16 WAV
+  (transfer-encoding: chunked, placeholder 0xFFFFFFFF RIFF/data sizes) as it synthesizes
+  — TTFB ~0.44s vs ~7s total (infra-ops verified). So ratatoskr PROXIES THE CHUNKS
+  STRAIGHT THROUGH (`tts_stream`, `GET /api/tts`) and the browser plays a progressive
+  `<audio src>`; NEVER buffer, NEVER rewrite the placeholder header (a rewrite needs the
+  whole clip and defeats streaming — the bug the original buffered `tts_synthesize` +
+  `_finalize_wav_header` hit). The placeholder-size WAV is DESIGNED for `<audio src>`
+  progressive playback (validated in Chromium: plays, currentTime advances, no MSE
+  needed). Supersedes the original "full-synth latency accepted / no streaming."
+  (Amended 2026-08-02: the browser path is now Web Audio decoding raw int16 PCM, not
+  `<audio src>` — Safari/WebKit rejects a 0xFFFFFFFF-length streaming WAV via `<audio
+  src>` (NotSupportedError); and `/api/tts` is now POST, not GET. See DEC-10.)
+- **DEC-3 — wav streaming (amended 2026-08-07).** `format:"wav"`, `stream:true` →
+  a streaming int16 RIFF/WAVE with placeholder (0xFFFFFFFF) RIFF/data sizes, one
+  header, then s16le PCM to EOF — the shape the browser's one-header-strip decoder
+  expects. chatterbox also offers `format:"pcm"` (headerless raw s16le, leaner);
+  kept on `wav` so the streaming shape stays byte-identical to the Zonos path and the
+  endpoint's RIFF-sniff (non-WAV-200 → 503) and the browser header-strip both stand
+  unchanged. (pcm is a deferred lean-up — it would drop the header-strip + the
+  RIFF-sniff, net a few lines.)
+- **DEC-4 — server-side proxy.** Browser → `/api/tts` (nh3-dev) → gateway. The
+  irv-ml1 host/URL never reaches the client (INV-TTS-1). No key exists, so
+  INV-003 is trivially satisfied, but the proxy still stands (browser can't
+  reach the WG net regardless).
+- **DEC-5 — serialize one synth per turn.** The gateway shares a single 3090
+  (~90% VRAM) with other TTS engines; do not parallelize. A new turn cancels any
+  in-flight synth + playback.
+- **DEC-6 — KB-recall = consumer-side retrieval + memory_context pinning, as a
+  RETIRE-READY bridge (worldtree-dev ruling, wyrd-proven pattern).** Tier-3 is
+  tool-less by design (`build_tier3_agent_context` hard-codes `tool_schemas=[]`);
+  agent.call:mimir is rejected (recursion). So per interview turn: ratatoskr
+  consults Mimir out-of-band for the question's topic, extracts the cited
+  evidence, and POSTs Donut's turn with `memory_context=[{kind:"corpus_reference",
+  text:"<extract>"}]`. She answers in-voice, framing it as her own memory. The
+  bridge is isolated behind ONE seam (INV-KB-1) so it deletes cleanly when
+  Worldtree #361 `reference_knowledge` extends to Tier-3 (operator-flagged as an
+  integral gap; worldtree-dev surfacing the extension to Vuong).
+  - **DEC-6 status (2026-08-02): bridge RETIRED, native `reference_knowledge` live but
+    EMPTY.** The bridge was deleted (`09e4257`) when WT #383 native `reference_knowledge`
+    (b167) shipped — Donut now calls the tool in-turn. But the tool returns zero hits for
+    every query. Root-caused 2026-08-02: Mimir's `search_library` DOES find the DCC corpus
+    (main wing, score ~0.03), so the store is NOT empty and this is NOT a ratatoskr gap —
+    WT's native `reference_knowledge` isn't surfacing content Mimir retrieves fine (likely
+    a wing-scope mismatch — tool scoped to the failed `fiction` wing — or a confidence
+    threshold rejecting the weak ~0.03 hits). Escalated to worldtree-dev. Until fixed,
+    Donut recalls from her own character knowledge (degrades in-voice per the persona).
+- **DEC-7 — affect-driven emotion. RETIRED 2026-08-07 (chatterbox migration).**
+  chatterbox Turbo has no valence/arousal/emotion control (infra-ops-verified:
+  exaggeration is exposed but inert; cfg_weight/min_p not exposed; only generic
+  sampling knobs move output, and those change timbre/variance not emotion). There
+  is no coupling point for a live-PAD driver, so the entire path is deleted —
+  `PadState`, `EmotionDials`, `pad_to_dials`, the `/api/tts` `p`/`a` body fields, and
+  the browser's `pad` argument. Voice is now flat. Retained below as historical
+  record of the Zonos build. (Original: map live PAD from the `affect_update` SSE →
+  Zonos `emotion_valence`/`emotion_arousal`, reframing the feature as voice
+  OBSERVABILITY. The observability framing dies with the knob.)
+- **DEC-8 — voice: custom "donut" is REGISTERED (amended 2026-08-10 for dots).**
+  dots clones a voice server-side from a reference clip + transcript; the client just
+  passes a voice NAME (GET /v1/voices lists them: donut/glados/emmie/miranda). The
+  `donut` voice carries over from chatterbox, so `_TTS_VOICE_MAP` maps
+  `ratatoskr:donut → "donut"`; `ratatoskr:sindra → "miranda"` (operator-directed
+  2026-08-10). NOTE the case: lowercase `"donut"` (Zonos used
+  `"Donut"`). Non-interview agents fall to the dots default `"glados"` (was chatterbox
+  `"glados_25s"` / Zonos `"Cora"`, neither of which exists on dots). New voices are a
+  one-line request to infra-ops (derived from the canonical voice corpus).
+- **DEC-9 — hold English: RESOLVED SERVER-SIDE 2026-08-07 (client sends full text, default
+  sampling).** The Zonos `language:"en-us"` pin is dropped — chatterbox has no `language` field.
+  The long-turn garble ("swaps to German halfway through") went through two WRONG hypotheses
+  before the real cause surfaced under the operator's clean-diagnosis push (thread 01KZEDMJ…):
+  - WRONG-1: "English-only, nothing to drift" (infra-ops Q8) — falsified by the operator report.
+  - WRONG-2: "multilingual leak, curb with tighter sampling" — I shipped `top_k 1000→80` /
+    `top_p 0.95→0.85` / `temp 0.8→0.5`. This made it WORSE: tight sampling pulls the degradation
+    onset to a SHORTER length (garble by ~200 chars vs ~300 at default knobs).
+  - **REAL CAUSE (infra-ops, signal-measured): the Turbo model OVER-RUNS its generation TAIL** —
+    a long single generation degrades into garble/dead-air in its final ~2-3s (voiced-tail
+    zero-crossing rate 1.58x the middle; the lib itself filters OOV tokens + pads silence). The
+    scheduler's unbounded buffer-ratchet built 300-600 char mega-chunks landing squarely in that
+    zone, and streaming concatenated each bad tail. The "German" was that tail garble mis-heard
+    (compounded by shared-3090 OOM garbage, now gone — Zonos was moved off the 3090).
+  - **FIX (deployed server-side, image :v2): `max_chunk_chars=250`** on the gateway scheduler,
+    bounding each generation below the ~300-char onset → clean 3-4 sentence chunks with a full
+    prosodic arc (verified: voiced-tail ZCR 1.58x→0.64x; operator ear-confirmed clean audio AND
+    clean paragraph joins — chatterbox's low emotiveness keeps the seams smooth). Per-request
+    `max_chunk_chars` override available for per-call tuning.
+  - **CONSUMER SIDE (this is what the code does): send FULL text with the gateway's DEFAULT
+    sampling.** The WRONG-2 sampling curbs were REVERTED (they degrade audio earlier and fight
+    the :v2 cap). `gateway_body` is back to `{text, voice, format, stream}` — no client chunking
+    (DEC-10 stays retired; the server chunks at 250), no sampling overrides. The persona's
+    dialogue-only rewrite in `docs/characters/donut.md` still stands. (Original Zonos DEC-9 below.)
+
+- **DEC-9a — empty-200 OOM guard: KEPT as hygiene (OOM itself resolved).** chatterbox-fast used
+  to share the RTX 3090 with Zonos2 (~1 GB headroom); a long single generation could OOM the card
+  and the gateway then returned HTTP **200 with a 0-byte body**. The OOM is resolved (Zonos moved
+  off the 3090; the :v2 250-char cap keeps generations small), but `tts_endpoint` KEEPS treating an
+  empty 200 body as a synthesis failure → 503 (INV-TTS-4 visible skip) — good hygiene regardless
+  (infra-ops-endorsed), never a silent empty audio/wav stream.
+- **DEC-10 — long-form chunk-and-concatenate. RETIRED 2026-08-07 (chatterbox
+  migration).** chatterbox-fast has NO per-synth token/duration cap (Zonos capped at
+  6144 tok / 71.2s) and chunks arbitrary-length text INTERNALLY via its adaptive
+  scheduler, streaming seamlessly — so client-side chunk-and-concatenate is deleted:
+  `chunk_text`, `tts_stream_long`, `_pcm_after_header`, and the `_TTS_CHUNK_CHAR_BUDGET`
+  constants are gone; a single `tts_stream` call voices a whole turn. `/api/tts` STAYS
+  POST (DEC-10a) — a long turn still rides the body, not a length-capped URL — and the
+  8000-char outer cap stays as a shared-GPU hold ceiling (no longer a chunk-count
+  bound). The `yielded_any` mid-stream degrade that lived in `tts_stream_long` folds
+  into `tts_stream`. Retained below as historical record of the Zonos build. (Original:)
+  The Zonos model hard-caps ONE synthesis at
+  `max_tokens=6144` = 71.2s of audio (6144 / 86.3 Hz codec frame rate; the gateway 400s
+  above 6144 — an architectural sequence limit, unraisable). So a turn longer than ~71s
+  truncated mid-stream. Fix: split the text client-side and concatenate the PCM
+  (`chunk_text` + `tts_stream_long`). Chunking is paragraph-first + greedy (operator call:
+  fewer, fuller chunks for prosody), targeting ~75% of the cap per chunk (~747 chars @
+  ~14 c/s); the 25% headroom covers char→audio-seconds variance (the cap is on TOKENS —
+  6144 = 71.2s ALWAYS, a codec-frame constant regardless of delivery, infra-ops — while the
+  budget is in CHARS, a proxy that stretches under slow/expressive delivery) so no chunk clips;
+  oversized paragraphs fall back to sentence packing, oversized sentences to clause/word
+  sub-splitting. Concatenation emits chunk 1's WAV verbatim then chunks 2..N header-
+  stripped → ONE continuous int16-PCM stream (never bury a RIFF header mid-stream —
+  infra-ops). Identical voice+dials+language per chunk for uniform delivery. `/api/tts`
+  becomes POST (DEC-10a) so the full text rides the body, not a length-capped URL; the
+  outer text cap rises 2000→8000 (a shared-3090 hold bound, not a URL bound).
+
+- **DEC-11 — config-driven voices + two-voice dialogue/narration split (2026-08-11, operator-directed).**
+  Voice assignment moves from the hardcoded `_TTS_VOICE_MAP` (DEC-8) to a rata-side config file
+  `~/.config/ratatoskr/voices.json` (beside local_agents.json + provider.env; NOT folded into the
+  agent-index schema — isolated from its v1→v2 silent-drop foot-gun). Supersedes DEC-8's hardcoded map.
+  - **Schema:** `{"default": "<voice>", "agents": {"<agent_id>": {"voice": "<voice>", "narration_voice": "<voice>"?}}}`.
+    `voice` = the agent's dialogue/primary voice; an unmapped agent (or one with no `voice`) falls to
+    `default`. Voice names are GATEWAY-validated (GET /v1/voices), not client-asserted.
+  - **`narration_voice` is OPTIONAL and its PRESENCE is the two-voice switch** (no separate flag).
+    Absent → the whole turn is one span in `voice` (byte-identical to the prior single-call passthrough —
+    this is why dialogue-only Donut needs NO special-casing). Present → the turn is SEGMENTED into
+    dialogue vs narration spans; dialogue → `voice`, narration → `narration_voice`.
+  - **Segmentation (FN segment_dialogue):** QUOTED text (straight `"` OR curly `“ ”`) = dialogue;
+    text OUTSIDE quotes = narration. Order preserved; empty/whitespace spans dropped. An unbalanced
+    trailing open-quote → its run-to-end is dialogue (best-effort, never raises). dots' server-side
+    curly→ASCII fold is pronunciation-only and does NOT affect boundary detection (we match both styles).
+  - **Synthesis (FN tts_stream_stitched):** spans synth SERIALLY (dots single-consumer) into ONE
+    continuous stream — span 0 streamed as wav VERBATIM (header + PCM), spans 1..N streamed as wav with
+    the leading WAV header STRIPPED (accumulate-until-`data`, emit after `data`+8) so the browser decodes
+    one gapless 48kHz mono s16le stream after a single leading header. The single-span case is EXACTLY the
+    prior tts_stream passthrough (INV-TTS-6, no regression). The `yielded_any` degrade pivot spans the whole
+    sequence: a pre-first-byte failure on ANY span before span 0 has committed → TtsUnavailable → 503; a
+    failure after ≥1 byte committed → degrade (drop the tail, keep what played), never raise into the 200.
+  - **Config load (FN load_voice_config):** entrypoint reads voices.json at startup → `create_app(voice_config)`
+    → `app.state.voice_config`; `_tts_endpoint` resolves spans per turn (FN resolve_voice_spans). An
+    absent/malformed file → the built-in DEFAULT_VOICE_CONFIG (donut→donut; sindra→miranda dialogue + emmie
+    narration; glados default), logged — degrade-not-crash (INV-TTS-5).
+  - **Initial voices.json:** `donut → {voice: donut}` (dialogue-only, single voice); `sindra →
+    {voice: miranda, narration_voice: emmie}`.
+
+## Invariants
+
+- **INV-TTS-1 [hard]** — the TTS gateway host/URL (dots-tts :8198) never
+  reaches the browser; all synthesis goes through `/api/tts`.
+- **INV-TTS-2 [hard]** — TTS is opt-in: a 🔊 toggle (default OFF), persisted to
+  localStorage (mirrors the theme/cot-toggle pattern). No speech without it.
+- **INV-TTS-3 [hard]** — one synth in flight at a time; a new turn cancels the
+  prior synth request AND stops in-flight playback (cancel-on-new-turn).
+- **INV-TTS-4 [hard]** — TTS failure is non-blocking: a gateway error, non-wav
+  body, or playback failure skips audio; the turn/transcript is unaffected. Logging is
+  scoped to GENUINE failure: a committed-200 mid-stream/later-chunk degrade writes a
+  `tts_degrade` stderr line (server) or a `no WAV header` ticker (browser); a browser-side
+  ABORT/cancel (INV-TTS-3 new-turn) is deliberately SILENT — cancellation is not a failure.
+- **INV-TTS-5 [hard]** — voice config is degrade-not-crash: an absent, unreadable, or malformed
+  `voices.json` (bad JSON, wrong types, missing keys) falls back to the built-in DEFAULT_VOICE_CONFIG
+  and logs; it NEVER crashes `create_app`/the server. Per-agent malformed entries fall to `default`.
+- **INV-TTS-6 [hard]** — the single-span path is a byte-identical passthrough: an agent with no
+  `narration_voice` (e.g. Donut), or any turn that segments to one span, produces the exact stream the
+  prior single `tts_stream` call did (one leading WAV header + PCM, verbatim). No regression for the
+  dialogue-only / single-voice case.
+- **INV-TTS-7 [hard]** — a stitched multi-span stream carries EXACTLY ONE WAV header (span 0's); spans
+  1..N are header-stripped before their PCM is emitted, so the browser decodes one continuous s16le
+  stream (never a RIFF header buried mid-stream).
+- **INV-KB-1 [hard]** — the KB bridge is import-isolated behind a single seam:
+  `server.py`'s turn path calls exactly one function `pin_kb_context(question,
+  agent_id) -> list[memory_context] | []`. Retiring the bridge = delete
+  `kb_bridge.py` + that one call-site; no other file changes. `kb_bridge` imports
+  nothing from the TTS or SDK-adapter core.
+- **INV-KB-2 [hard]** — the retrieval channel is never persisted: `memory_context`
+  is per-turn, `kind="corpus_reference"` (a free label), and rides the turn POST
+  body only.
+- **INV-KB-3 [hard]** — KB-retrieval failure is non-blocking: a failed/empty
+  Mimir consult pins nothing (`[]`) and Donut answers without the extract; never
+  block or fail her turn on retrieval.
+- **INV-KB-4** — the bridge is scoped to characters that opt in (a per-agent
+  allowlist / config), not applied to every turn — only interview characters
+  that need corpus recall pay the retrieval round-trip.
+
+## FN blocks
+
+### FN tts_stream  (the sole synthesis primitive — DEC-2 streaming; amended 2026-08-10 dots)
+```
+tts_stream(text, *, voice, client: httpx.AsyncClient, url=DOTS_TTS_URL) -> AsyncIterator[bytes]
+  # Open the gateway's CHUNKED stream (client.stream("POST", url, json=gateway_body(text, voice))) and
+  # YIELD wav chunks as they synthesize. Pass through verbatim — never buffer, never rewrite the placeholder
+  # header. dots streams a whole turn from this SINGLE call (DEC-10 RETIRED) — no client-side
+  # chunk-and-concatenate wrapper.
+  # gateway_body(text, voice) = {input, voice, response_format:"wav", stream:true} (OpenAI-shaped: `input`
+  #   not `text`, `response_format` not `format`). Full text, DEFAULT sampling. NO dials, NO language,
+  #   NO client sampling curbs.
+  precondition: text non-empty. Voice membership in GET /v1/voices is GATEWAY-enforced, not client-asserted.
+  postcondition: yields the gateway's chunked int16 streaming WAV bytes unmodified (0xFFFFFFFF placeholder
+                 sizes intact), one leading header then mono s16le PCM @ 48000 Hz to EOF.
+  error (the yielded_any pivot, folded in from the retired tts_stream_long):
+    - a non-200 OPEN or a connect/transport failure BEFORE the first byte -> TtsUnavailable (so the endpoint
+      peek can still return 503; nothing committed yet).
+    - a transport drop AFTER >= 1 byte has streamed (the 200 is committed) -> DEGRADE: write a `tts_degrade`
+      stderr line, END the generator, keep what played. NEVER raise into the committed StreamingResponse.
+  invariant: format is ALWAYS "wav" (DEC-3); never mp3/opus/pcm from this seam.
+```
+
+### FN chunk_text  (DEC-10 long-form splitting; pure) — RETIRED 2026-08-07 (chatterbox chunks internally; deleted). Historical:
+```
+chunk_text(text, budget=_TTS_CHUNK_CHAR_BUDGET) -> list[str]
+  # Split into synthesis chunks each <= budget chars. Paragraph-first (seams on blank lines), greedy pack.
+  steps:
+    - strip; empty/whitespace -> [].
+    - whole paragraphs (each <= budget) greedily pack together, joined "\n\n".
+    - a paragraph > budget flushes the pending run, then sentence-packs (split (?<=[.!?])\s+, join " ");
+      a sentence > budget sub-splits on clause (, ; :) then space, hard-cut mid-word only as last resort.
+  postcondition: every chunk non-empty and <= budget; word order preserved; no split mid-word unless the
+                 input has no boundary at all. budget = 71.2s * 0.75 * 14 c/s ≈ 747 (75% of cap for prosody).
+```
+
+### FN tts_stream_long  (DEC-10 orchestrator) — RETIRED 2026-08-07 (no per-synth cap; deleted, its yielded_any degrade folded into tts_stream). Historical:
+```
+tts_stream_long(text, *, voice, dials, client, url=ZONOS_TTS_URL, budget=_TTS_CHUNK_CHAR_BUDGET) -> AsyncIterator[bytes]
+  # chunk_text(text) then synth each chunk with tts_stream (identical voice+dials+language). Emit chunk 1
+  # VERBATIM (WAV header + PCM); chunks 2..N via _pcm_after_header (strip up to+incl the `data` id+size) so
+  # the browser decodes ONE continuous int16-PCM stream after a single leading header (infra-ops: one header).
+  error: the pivot is `yielded_any`, NOT the chunk index. A failure BEFORE the first byte (an OPEN failure)
+         propagates as TtsUnavailable -> endpoint peek -> 503 (nothing committed yet). A failure AFTER bytes
+         have streamed — a MID-STREAM drop on chunk 0 OR a later chunk, past the committed 200 — degrades:
+         drop the tail, keep what played, write a `tts_degrade` stderr line, RETURN (never raise into the
+         committed StreamingResponse). httpx wraps aiter_bytes in `except RequestError`, so a mid-stream
+         drop arrives as TtsUnavailable, not a clean generator end — the yielded_any gate is what keeps a
+         chunk-0 mid-stream drop from raising into the 200.
+```
+
+### FN pad_to_dials — RETIRED 2026-08-07 (DEC-7 affect dropped; PadState/EmotionDials/pad_to_dials all deleted). Historical:
+```
+pad_to_dials(pad: PadState | None) -> EmotionDials
+  # Map live PAD -> Zonos emotion dials (DEC-7).
+  steps:
+    - none/malformed pad -> neutral dials (emotion_enabled=False) [degrade-not-crash].
+    - emotion_valence = clamp(pad.pleasure, -1, 1); emotion_arousal = clamp(pad.arousal, -1, 1).
+    - emotion_enabled = True; emotion_strength from a fixed default (tunable).
+  invariant: total over any PAD the DECLARED surface produces (a PadState with float axes /
+             None / out-of-range / NaN / inf / a non-PadState object) -> valid dials, never raises.
+             (A PadState carrying NON-float axes is a type violation no call site constructs — the
+             endpoint coerces via PadState.from_obj; not defended inside pad_to_dials.)
+```
+
+### FN tts_endpoint  (server.py, POST /api/tts — DEC-10a; amended 2026-08-07)
+```
+POST /api/tts  {text, agent_id?}  -> audio/wav (chunked StreamingResponse)
+  # POST (not GET) so an arbitrarily long turn rides the body, not a length-capped URL. The gateway chunks
+  # arbitrary-length text internally (DEC-10 RETIRED — no client concat); a single tts_stream call proxies it.
+  # text capped 8000 chars, word-boundary truncated (a shared-GPU hold bound; the transcript still shows the
+  # full text). text/agent_id are untrusted open-world body fields — each degrades, never 500s (INV-TTS-4).
+  # (The `p`/`a` PAD body fields are GONE — DEC-7 affect retired.)
+  steps:
+    - bad JSON / non-str text -> 400. Scrub lone surrogates from text (else httpx's utf-8 encode of the gateway
+      body 500s); if the scrubbed text is blank after strip -> 400. word-boundary truncate to 8000 (with a
+      mid-word HARD-CUT fallback when the last space sits at index <= limit//2).
+    - resolve voice: per-character map -> "donut", default "glados_25s"; a NON-str agent_id (unhashable) -> default.
+    - acquire the serialize lock (DEC-5, one stream at a time on the shared GPU); open tts_stream and PEEK the
+      first byte: a bad gateway OPEN -> 503; an EMPTY 200 body (no bytes — an OOM synth, DEC-9a) -> 503; and a
+      200 whose first bytes are NOT a RIFF header -> 503 too (a mislabeled non-WAV body would decode as
+      garbage) — all BEFORE committing a 200 (INV-TTS-4). Any OTHER escape during the peek (CancelledError,
+      httpx.InvalidURL) releases the lock+client, then propagates.
+    - return StreamingResponse piping tts_stream; the generator's finally releases the lock + closes the client
+      (incl. the browser-abort path: a new turn's fetch() drops the POST) and, on a committed mid-stream drop,
+      tts_stream degrades internally (ends the generator, no raise). httpx.Timeout is connect=10 / read=120 /
+      write=10 / pool=10 (read=120 per infra-ops: a long synth can render slowly).
+```
+
+### FN pin_kb_context  (kb_bridge.py — RETIRE-READY, INV-KB-1)
+```
+pin_kb_context(question: str, agent_id: str | None, *, client) -> list[dict]   # memory_context items, or []
+  # The bridge. Consumer-side retrieval + pinning (DEC-6).
+  steps:
+    - gate on the interview-character allowlist (INV-KB-4); not listed / blank question -> [].
+    - out-of-band Mimir consult (a throwaway session + one turn), HARD-bounded by a timeout.
+    - extract the answer text (prefer DoneEvent.response; fall back to text deltas), bounded length.
+    - return [{"kind":"corpus_reference","text":<extract>}].
+  error/empty/timeout: any failure or no hits -> [] (INV-KB-3; never raises to the turn path).
+                       CancelledError (browser disconnect) is NOT caught — it propagates.
+  no-hit sentinel (heid-code-review F7): the consult prompt asks Mimir to emit exactly NO_CORPUS_MATCH
+                       when the search finds nothing relevant; pin_kb_context drops any extract containing
+                       it -> [], so a non-empty "no results found" answer is never pinned as the character's
+                       own memory. The token is artificial (no genuine passage contains it).
+  session hygiene (heid-bug-hunt): the throwaway Mimir consult session is deleted (SDK sessions.delete) on
+                       success/error/timeout via a caller-owned holder, so consults don't accumulate upstream.
+  CONSULT PROMPT (foot-gun mitigation, tuned live 2026-08-02): force "search_library EXACTLY ONCE,
+    no read_note" — converges Mimir in ~3-15s. The softer "do one search" phrasing let Mimir loop
+    read_note<->search past a 25s ceiling on conversational (non-keyword) questions (live-observed).
+  KNOWN LIMIT (surfaced by the live smoke, NOT a bridge defect): the bridge's GROUNDING VALUE is gated
+    by Mimir's retrieval quality on the target corpus. DCC's fiction-wing index is currently weak
+    (scores ~0.02, failed backfill — a standing worldtree-dev item), so hits are noisy/partial; the
+    model's own DCC training knowledge already grounds Donut well, so the bridge is opportunistic here.
+    Its real payoff is a corpus the model does NOT know AND that indexes cleanly.
+  RETIREMENT: when Worldtree #361 reference_knowledge reaches Tier-3, delete this module + the single
+              server.py call-site (wt.stream_turn's memory_context param stays, inert); Donut then
+              searches in-voice natively.
+```
+
+### FN client: speakOnDone  (index.html — Web Audio STREAMING, DEC-2; amended 2026-08-07)
+```
+on SSE `done`:
+  if !ttsEnabled(): return                                  # INV-TTS-2
+  cancelTts()                                               # INV-TTS-3: abort fetch + stop scheduled nodes
+  POST /api/tts {text (sliced to the 8000 cap), agent_id?} -> reader   # DEC-10a: POST body. NO p/a (DEC-7 retired).
+  loop: read chunk -> skip ONE WAV header up to the data chunk (bounded 64KiB) -> int16 LE PCM -> Float32 ->
+        AudioBuffer(sampleRate=48000) -> BufferSource.start(playAt) GAPLESSLY -> playAt += buf.duration
+        # SR = 48000 (dots; was 24000 for chatterbox — MUST match or the voice plays ~2x too fast). TTFA ~0.5s.
+  first scheduled node -> "▶ voiced". HARD failure (non-OK HTTP, or 64KiB with no WAV header) -> ticker + skip;
+        ABORT/cancel (INV-TTS-3 new-turn) + bare network error -> SILENT skip (INV-TTS-4, cancel is not a failure)
+
+WHY Web Audio, not <audio src>: Safari/WebKit REFUSES a streaming 0xFFFFFFFF-length WAV via <audio src>
+(NotSupportedError — it can't compute duration/seek), which was the operator's live failure. Decoding the raw
+int16 PCM ourselves and scheduling it into an AudioContext sidesteps every WAV-container quirk and works in all
+engines. Validated in Chromium: 43 nodes scheduled, 5.1s decoded, no error.
+
+AUTOPLAY UNLOCK: an AudioContext starts "suspended"; Safari + Chrome require resume() to originate from a user
+gesture (then it stays running). _unlockTtsAudio() resumes it on the FIRST interaction anywhere (document
+pointerdown/keydown) + toggle-on + each submit, so it's running before the ~15s-delayed speak-on-done. Validated:
+ctx is "running" 6.5s after the gesture (past the transient-activation window). Page served no-store so a stale
+cache can't hide these updates.
+```
+
+## Slice plan
+
+1. **Persona** — author `docs/characters/donut.md` (corpus-grounded, interview frame,
+   markdown-RP register) + `tier3 define` Princess Donut. Visible: she's in the picker,
+   chattable (answers from training until slice 3). No code.
+2. **Auto-TTS** — `tts.py` (gateway client + pad_to_dials) + `/api/tts` proxy + the
+   index.html 🔊 toggle + speak-on-done playback + serialize/cancel. Visible: she's voiced,
+   affect-modulated. TDD (respx-mock the gateway; live smoke on the console).
+3. **KB-bridge** — `kb_bridge.py` + the one server.py seam. Visible: she recalls the DCC
+   corpus in-voice. TDD. RETIRE-READY per INV-KB-1.
+
+Out of scope: true audio streaming (DEC-2), custom voice registration (DEC-8, infra-ops
+follow-up), extending the bridge to non-interview agents.

docs/contracts/first_message.contract.md

@@ -13,11 +13,12 @@ scope: >
   replacement for a system-prompt "startup" instruction. Two entry points:
   `preset_for` (lookup) and `seed_preset_first_message` (best-effort seed).
   Consumed by ratatoskr.cli (the `--new` session path) and ratatoskr.web.server
-  (the POST /api/sessions endpoint). Depends on ratatoskr.sessions
-  (write_authored_history + its exceptions); no core.* / worldtree.* imports.
+  (the POST /api/sessions endpoint). Depends on ratatoskr.wt
+  (`wt.write_authored_history` + AuthoredHistoryUnavailable) over a WorldtreeClient
+  (worldtree-sdk cutover slice-3, #20); no core.* / worldtree.* SOURCE imports.
 depends_on:
-  - "httpx"
-  - "ratatoskr.sessions"
+  - "worldtree_sdk"
+  - "ratatoskr.wt"
 used_by:
   - "ratatoskr.cli"
   - "ratatoskr.web.server"
@@ -26,7 +27,7 @@ complexity: "low"
 estimated_loc: 60
 confidence: 0.9
 assumptions:
-  - "write_authored_history (contract #2 amendment 2026-07-06) is the seed primitive: 200/201 → ack dict, 404 → AuthoredHistoryUnavailable (hide-existence), other non-2xx → SessionApiFailed."
+  - "wt.write_authored_history (the SDK-adapter seed primitive, #20) writes over the worldtree-sdk client: success → ack mapping, 404 → AuthoredHistoryUnavailable (hide-existence), other ApiError → wt.SessionApiFailed. Behavior/semantics unchanged from the retired hand-rolled path — only the transport moved to the SDK."
   - "The preset registry is a static in-module dict keyed by agent_id; editing it is how an operator tunes an agent's opening. Seeded with ratatoskr:sindra only."
   - "Auto-seed is BEST-EFFORT and MUST NOT block session creation: an instance without the session.history.write grant returns the hide-404, which is swallowed (session opens with no seeded greeting)."
 ---
@@ -47,8 +48,8 @@ every new session for a preset agent opens in-character regardless of surface.
 
 ## Data flow
 
-**In:** a live `httpx.AsyncClient` (caller-owned, base_url + bearer set), a fresh
-`session_id`, and the bound `agent_id`.
+**In:** a `WorldtreeClient` (the wt-adapter client, built over ratatoskr's
+caller-owned transport), a fresh `session_id`, and the bound `agent_id`.
 
 **Out:** on a preset agent, one `POST /sessions/{session_id}/history` (author=assistant,
 the preset text, per-content idempotency key). Returns the seeded content on
@@ -104,19 +105,19 @@ TESTS:
   preset_miss [happy]: preset_for("mimir") is None
   empty_agent_id [adversarial]: preset_for("") → AssertionError
 
-FN seed_preset_first_message(client: httpx.AsyncClient, session_id: str, agent_id: str) -> str | None
-BRIEF: Best-effort seed of an agent's preset opening as a #347 authored first-message on session_id. If agent_id has a preset, POST it via write_authored_history (author=assistant, per-content idempotency key, the await bounded by asyncio.wait_for(_SEED_TIMEOUT_S)) and return the seeded content; on no-preset, a malformed input, OR ANY exception except asyncio.CancelledError, return None WITHOUT raising. Never raises (except CancelledError, which propagates) and never blocks session creation — it is wired into three create paths.
+FN seed_preset_first_message(client: WorldtreeClient, session_id: str, agent_id: str) -> str | None
+BRIEF: Best-effort seed of an agent's preset opening as a #347 authored first-message on session_id. If agent_id has a preset, write it via wt.write_authored_history (author=assistant, per-content idempotency key, the await bounded by asyncio.wait_for(_SEED_TIMEOUT_S)) and return the seeded content; on no-preset, a malformed input, OR ANY exception except asyncio.CancelledError, return None WITHOUT raising. Never raises (except CancelledError, which propagates) and never blocks session creation — it is wired into the CLI + web create paths.
 PRE: [PRE-001 hard] client is not None -- soft-guarded: return None (NOT assert) if violated, so a wiring bug can't crash the create path (INV-001)
 PRE: [PRE-002 hard] session_id is a non-empty str -- soft-guarded: return None if violated
 PRE: [PRE-003 hard] agent_id is a non-empty str -- soft-guarded: return None if violated (also guards FIRST_MESSAGE_PRESETS.get against a non-hashable/non-str id)
 POST: [POST-001 return_value] preset agent + successful write → returns the preset text; no-preset, malformed input, OR any swallowed failure → None
-POST: [POST-002 side_effect] a no-preset / malformed-input call issues ZERO HTTP; a preset agent issues exactly one POST /sessions/{session_id}/history with body author="assistant", content=preset, idempotency_key="ratatoskr-preset-"+sha256(preset)[:12], the await bounded by _SEED_TIMEOUT_S so a stalled response cannot block
+POST: [POST-002 side_effect] a no-preset / malformed-input call issues ZERO writes; a preset agent issues exactly one authored-history write (POST /sessions/{session_id}/history via the SDK) with entry author="assistant", content=preset, idempotency_key="ratatoskr-preset-"+sha256(preset)[:12], the await bounded by _SEED_TIMEOUT_S so a stalled response cannot block
 ERROR_ROUTING:
   asyncio.CancelledError:
     local_handling: RE-RAISE (cancellation is not a seed failure; never swallow it — and it is a BaseException, so `except Exception` would miss it anyway)
     flow_control: propagate
     state_recovery: n/a
-  any other Exception (hide-404 AuthoredHistoryUnavailable, SessionApiFailed 409/422/etc., httpx.HTTPError, TimeoutError from wait_for, any unexpected error):
+  any other Exception (hide-404 AuthoredHistoryUnavailable, wt.SessionApiFailed 409/422/etc., SDK ConnectFailed, TimeoutError from wait_for, any unexpected error):
     local_handling: swallow; return None
     flow_control: continue (never blocks session create)
     state_recovery: session opens with no seeded greeting
@@ -125,18 +126,18 @@ STEPS:
   2. [sequential, prescriptive] content = FIRST_MESSAGE_PRESETS.get(agent_id); IF content is None: RETURN None (INV-002 — zero HTTP)
   3. [sequential, prescriptive] Soft-guard: IF client is None OR session_id is not a non-empty str: RETURN None
   4. [sequential, prescriptive] key = "ratatoskr-preset-" + sha256(content utf-8)[:12]
-  5. [sequential, prescriptive] TRY: await asyncio.wait_for(write_authored_history(client, session_id, content=content, idempotency_key=key), timeout=_SEED_TIMEOUT_S)
+  5. [sequential, prescriptive] TRY: await asyncio.wait_for(wt.write_authored_history(client, session_id, content=content, idempotency_key=key), timeout=_SEED_TIMEOUT_S)
      tool: { destructive: false, idempotent: true, read_only: false, open_world: false }
   6. [branch, prescriptive] EXCEPT asyncio.CancelledError: RAISE; EXCEPT Exception: RETURN None
   7. [cleanup, prescriptive] RETURN content
-TESTS:
-  seeds_preset [happy,tracer]: preset agent, mock 201 → returns the preset text; exactly one POST /sessions/{id}/history; body author="assistant" + content=preset + idempotency_key="ratatoskr-preset-"+sha256(preset)[:12]
-  no_preset_zero_http [happy]: agent "mimir" → returns None; NO HTTP issued
-  feature_absent_swallowed [error]: preset agent, mock 404 session_not_found → returns None, no raise
-  session_api_failed_swallowed [error]: preset agent, mock 409 → returns None, no raise
-  transport_error_swallowed [error]: preset agent, mock httpx.ConnectError → returns None, no raise
+TESTS: (driven through a fake WorldtreeClient whose sessions.write_history returns/raises — the wire is the SDK's to prove via its parity corpus)
+  seeds_preset [happy,tracer]: preset agent, fake write_history returns an ack → returns the preset text; exactly one write_history call; entry author="assistant" + content=preset + idempotency_key="ratatoskr-preset-"+sha256(preset)[:12]
+  no_preset_zero_write [happy]: agent "mimir" → returns None; ZERO write_history call
+  feature_absent_swallowed [error]: preset agent, fake raises ApiError(404) → adapter maps to AuthoredHistoryUnavailable → returns None, no raise
+  session_api_failed_swallowed [error]: preset agent, fake raises ApiError(409) → wt.SessionApiFailed → returns None, no raise
+  transport_error_swallowed [error]: preset agent, fake raises SDK ConnectFailed → returns None, no raise
   unexpected_exception_swallowed [error]: preset agent, write raises ValueError → returns None, no raise (INV-001 broad never-raise)
   cancellation_propagates [error]: preset agent, write raises asyncio.CancelledError → RE-RAISED (never swallowed)
-  malformed_agent_id_no_http [adversarial]: agent_id=123 (non-str) OR "" → None; NO HTTP; no raise
-  empty_session_id [adversarial]: session_id="" (preset agent) → None (soft guard); NO HTTP; no raise
+  malformed_agent_id_no_write [adversarial]: agent_id=123 (non-str) OR "" → None; ZERO write; no raise
+  empty_session_id [adversarial]: session_id="" (preset agent) → None (soft guard); ZERO write; no raise
 ```

docs/contracts/issues/1.contract.md

@@ -345,3 +345,48 @@ TESTS:
   buffer_expired_propagates [error]: attempt 1 drops after 42:1; reconnect returns 412 → ResumeBufferExpired propagates (not retried as a transient drop).
   zero_budget_no_resume [adversarial]: max_reconnects=0; attempt 1 drops after 42:1 → SseConnectionDropped propagates immediately (no reconnect attempted).
 ```
+
+## Amendment 2026-07-18 — event-vocab catch-up: `awaiting_llm_first_token` + `affect_update` (contract-vs-code drift)
+
+The §Data flow Output union and the `full_event_vocab` TEST (FN `stream_turn`)
+were frozen at the v0.19.0 baseline's 9-variant `Event` union and 8-event
+happy-path vocab. Two SSE events were added to the wire AFTER that baseline and
+are parsed by `_envelope_for_type` today, but their TESTS landed in the
+*consuming* contracts (cli #3, tui #4, affect web-proxy #18) and in
+`tests/test_sse_client.py` — never in this contract, so #1 under-described its own
+module. Surfaced during the Worldtree #371 SDK parity-matrix pass (worldtree-dev
+confirmed the gap: `full_event_vocab` stops at the 8-event set). This amendment
+re-canonicalizes #1 against the code. It is **documentation-only** — the code and
+its `test_sse_client.py` coverage already exist and pass; no code change, no
+version bump.
+
+**Corrected `Event` union** (supersedes the §Data flow Output list — 9 → 11):
+
+    WorkerPhase | Thinking | Text | TextBoundary | ToolStart | ToolResult
+    | Done | Error | Cancelled | AwaitingLlmFirstToken | AffectUpdate
+
+The two additions (both **non-terminal** — they do NOT satisfy INV-001's terminal
+requirement; the stream still ends at exactly one `Done`/`Error`/`Cancelled`):
+
+- `AwaitingLlmFirstToken(sse_id, turn_id, elapsed_ms_since_building_prompt: float)`
+  — SSE `awaiting_llm_first_token` (Worldtree #201, v0.29.0). Heartbeat during the
+  BuildingPrompt→CallingLLM gap (default 5 s); `elapsed_ms_since_building_prompt`
+  is server-authoritative monotonic. First-gap only (INV-201-5) — tool round-trips
+  do not re-fire.
+- `AffectUpdate(sse_id, status: str, turn_id, snapshot: dict | None)` — SSE
+  `affect_update` (Worldtree #204, v0.28.0). `status="current"` at turn start
+  carries the full persona snapshot; `status="scheduled"` after post-turn appraisal
+  kickoff omits it (`snapshot is None`). Suppressed for persona-disabled agents,
+  Tier-3 consumer-defined agents, and ephemeral sessions.
+
+Unknown event `type` still raises `ValueError` in `_envelope_for_type` (the
+base-contract behavior). NOTE for the eventual repin: the #371 SDK pins a
+deliberate divergence here (D-1 — skip-with-diagnostics-hook instead of raising),
+which Ratatoskr adopts only when it repins onto the SDK, not before.
+
+TESTS (already present in `tests/test_sse_client.py` — `TestAwaitingLlmFirstToken`
++ `TestAffectUpdate`; mirrored here for contract completeness):
+  single_heartbeat_parsed [tracer]: mock emits one `awaiting_llm_first_token` (turn_id, elapsed_ms_since_building_prompt=5012.3) → consumer yields AwaitingLlmFirstToken carrying both fields + parsed sse_id
+  heartbeat_sequence_monotonic [trace]: mock emits a heartbeat sequence → each yields AwaitingLlmFirstToken; elapsed_ms_since_building_prompt is monotonically non-decreasing across the sequence
+  current_status_parsed_with_snapshot [tracer]: mock emits `affect_update` status="current" with a full snapshot dict → consumer yields AffectUpdate(status="current", snapshot=<verbatim dict>)
+  scheduled_status_parsed_no_snapshot [trace]: mock emits `affect_update` status="scheduled" (no snapshot) → consumer yields AffectUpdate(status="scheduled", snapshot is None)

docs/contracts/issues/15.contract.md

@@ -1,290 +0,0 @@
----
-contract_version: "2.1"
-target_module: "ratatoskr.tier3"
-scope: "New module `ratatoskr.tier3` exposing Worldtree's Tier 3 (consumer-defined) agent lifecycle: `define_agent` (POST /agents/define), `patch_agent` (PATCH /agents/<id>), `delete_agent` (DELETE /agents/<id>), plus `Tier3AgentInfo` frozen dataclass. Plus a thin CLI entry point (`python -m ratatoskr.tier3 <define|patch|delete>`) that mirrors `ratatoskr.cli`'s env-var posture (`WORLDTREE_API_URL`, `WORLDTREE_API_KEY`). Convention-aligned with `ratatoskr.sessions` (issue #2): caller-owned httpx.AsyncClient, no Worldtree imports, response parsing into frozen dataclass, exception `.body` truncated to `[:1024]`. Picker stays generic — agents with `:` in agent_id show in the list like any other per issue #8's out-of-scope clause. Goal: ratatoskr operators can define, mutate, and delete Tier 3 agents from the command line, then exercise the full session flow against them to observe how Tier 3 agent_ids (colon-containing) flow through the picker / session-create / SSE stream."
-depends_on:
-  - "httpx"
-used_by: []
-language: "python"
-complexity: "low"
-estimated_loc: 250
-confidence: 0.9
-assumptions:
-  - "Tier 3 endpoints land at the same `WORLDTREE_API_URL` as the rest of the Conversation API — no separate hostname / port. Auth via the same bearer key. The caller's user_id is derived server-side from the API key's owner; the agent's `agent_id` is constructed as `<auth_user_id>:<agent_name>`. Live probe against personal Worldtree (2026-05-25) confirmed: POST with `{agent_name: 'smoke-test', ...}` and `Authorization: Bearer <key>` returned `agent_id=ratatoskr:smoke-test`, `user_id=ratatoskr`."
-  - "Per Worldtree spec §2576-2750: `agent_name` is a strict slug `[a-z][a-z0-9-]{2,63}` and immutable after definition. `user_id` is derived from the auth, must be slug-safe (`[a-z][a-z0-9-]{2,63}` per Phase 2.0 gate). PATCH accepts ONLY `system_prompt` and/or `model`; any other key (including the immutable `agent_name`, `user_id`, or layer fields `persona`/`motivational`/`valence`/`memory` — even with `null` value) returns 422 `field_not_mutable` BEFORE the DB lookup."
-  - "**Layer fields are explicitly null** on define. Phase 2.0 ships baseline addressing + ownership + lifecycle only; `persona` / `motivational` / `valence` / `memory` are schema-reserved. Non-null on these → 422 `layer_deferred`. The module's `define_agent` does NOT expose these as parameters at all — sending them would require an amendment when a future Phase enables them."
-  - "**`model` field is a provider model ID, not a profile alias.** Live probe found: `model='default'` (an llm_profiles profile name) returns 422 `model_not_available`; `model='qwen3.6-35-a3b'` (an actual provider model ID) returns 201. The CLI / module take the string verbatim and pass through — validation is server-side. Operators discover valid IDs via the model `metadata` on existing sessions or out-of-band."
-  - "**Quota: 50 Tier 3 agents per Heimdall key.** 51st define → 429 `agent_quota_exceeded` with `Retry-After: 0`. The module raises `Tier3QuotaExceeded(retry_after=0)` — the retry_after field captures the header value verbatim for forward-compat if Worldtree later returns a non-zero throttle."
-  - "**Key-revocation cascade is server-side.** When an API key is revoked (`DELETE /admin/keys/{key_id}`), every Tier 3 agent with `owner_key_hash` equal to the revoked key's hash is soft-deleted in the same SQL transaction. Active sessions on those agents return 401 `auth_revoked` on next message. The ratatoskr module doesn't track or simulate this — operators discover it via runtime 401s and the admin-side audit log."
-  - "**Picker integration is implicit** — no changes to `ratatoskr.tui.AgentPickerApp` for this issue. Tier 3 agents appear in `GET /agents` if defined and the picker's existing format `{agent_id} · {name} — {description}` renders the colon-containing agent_id without special-casing. Per issue #8 out-of-scope clause, ratatoskr does not visually distinguish Tier 1 vs Tier 3 in the picker — same UX surface."
-  - "**Session-create with colon-containing agent_id works unchanged.** Issue #5 already routes `end_user_id` into the POST /sessions body, which Tier 3 session-create requires from Phase 2.0 (per spec §2649-2664). No `ratatoskr.sessions` change needed."
-  - "**CLI uses argparse with subparsers** (define / patch / delete). The subparsers entry point lives at `python -m ratatoskr.tier3` via `__main__.py`. Output on success: prints a one-line summary (`defined ratatoskr:wizard (qwen3.6-35-a3b)` / `patched ratatoskr:wizard` / `deleted ratatoskr:wizard`). Output on error: `[<error_code>] <message>` to stderr + non-zero exit. Exit codes mirror `ratatoskr.cli`: 0 happy / 10 usage / 11 auth / 20 api-failure / 21 network."
-  - "**No `list` subcommand in v1.** A `tier3 list` operation would have to filter `GET /agents` by prefix-matching the caller's user_id, but that prefix isn't exposed in the response — only the agent_id is, and you'd have to introspect the auth's user_id. Operators discover their own Tier 3 agents by reading the `GET /agents` list (which the picker already surfaces) and looking for `<their-user-id>:*` entries. Add `list` in a follow-up if operators report friction."
-  - "**Module is standalone**: does NOT import or interact with `ratatoskr.sessions` / `ratatoskr.sse_client` / `ratatoskr.tui` / `ratatoskr.cli` beyond reusing the `USER_AGENT` constant from `ratatoskr.cli`. Cross-module use is one-way (cli supplies the user-agent string; tier3 does not import sessions). This keeps the module surface minimal and testable in isolation."
-  - "**The CLI's `python -m ratatoskr.tier3` entry point uses sys.argv handling that mirrors `ratatoskr.cli`** — a top-level `main(argv: list[str] | None = None) -> int` function that argparse-dispatches to subcommand handlers. Each subcommand handler is an async coroutine wrapped by `asyncio.run(...)`. Auth resolution: `--api-key` flag > `$WORLDTREE_API_KEY` env > `_AuthError` (exit 11). Server URL: `--server` > `$WORLDTREE_API_URL` > default `http://localhost:8000` (same default as `ratatoskr.cli`)."
-  - "**Tests use `respx` for HTTP mocking** (same pattern as `tests/test_sessions.py`). New test file: `tests/test_tier3.py`. Cover all success + error response codes per the ERROR_ROUTING matrix below. No live network in unit tests — the live smoke is in the acceptance criteria, not the unit tests."
-open_questions:
-  - "Should `define_agent` accept an optional `bifrost` parameter for Bifrost-bound Tier 3 sessions? The spec §2658 shows `bifrost` as a session-create field (not define-time). Draft: no — Bifrost binding is per-session; if a Tier 3 agent needs Bifrost on every session, that's an orthogonal feature on POST /sessions, not POST /agents/define. Issue #5's `--end-user-id` already covers the session-create-side parameters."
-  - "Should the CLI also offer `--end-user-id` for sessions created via tier3 + ratatoskr-cli composition? Draft: no — once an agent is defined, operators use the main `ratatoskr --new --agent <id> --end-user-id <eid>` flow; tier3 CLI is define/patch/delete only."
-  - "Should `delete_agent` support a `--force` flag for 'really delete even if active sessions exist'? Per spec §2634-2639, `DELETE` already cancels active sessions and revokes the per-resource scope grant on the owner — there's no soft fail. Draft: no — the spec's hard-delete-with-cascade behavior is the right shape; ratatoskr doesn't need to wrap it."
-prd:
-  issue: 15
-  issue_url: "https://gitea.phasefinal.com/vh/ratatoskr/issues/15"
-  body_sha256_16: "03367d7b451ab17f"
-  lock_in_comment_id: null
-  lock_in_sha256_16: null
-  lock_in_at: null
-  pinned_at: "2026-05-25T03:21:38+00:00"
-dependencies:
-  - issue: 2
-    path: "src/ratatoskr/sessions.py"
-    reason: "Convention dependency, not a code dependency. Issue #2 (`ratatoskr.sessions`) is the posture template: caller-owned httpx client, async-native, no Worldtree imports, response-parsing into frozen dataclasses, exception body truncation to [:1024]. `ratatoskr.tier3` follows the same shape verbatim."
-  - issue: 3
-    path: "src/ratatoskr/cli.py"
-    reason: "Convention dependency only. `ratatoskr.tier3.__main__` mirrors `ratatoskr.cli`'s argparse + env-fallback + exit-code shape. Imports `USER_AGENT` from `ratatoskr.cli` so outbound HTTP carries the same identity string."
----
-
-# Tier 3 — Consumer-defined agent lifecycle module
-
-## Context
-
-Worldtree's Tier 3 (Phase 2.0, spec §2576-2750) lets the consumer define their own agents at `<user_id>:<agent_name>`. The agent's `user_id` is the auth's user identity (derived from the API key's owner); the `agent_name` is supplied at define-time. The lifecycle is owner-only — only the key that defined an agent can patch / delete it (modulo the key-revocation cascade).
-
-`ratatoskr.tier3` exposes this lifecycle as a Python module + small CLI tool. Picker integration is implicit (Tier 3 agents already appear in `GET /agents` per issue #8). Session-create works unchanged through `ratatoskr.sessions.create_session` since the colon-containing agent_id is opaque to that layer.
-
-## Public surface
-
-```python
-@dataclass(frozen=True)
-class Tier3AgentInfo:
-    """Worldtree Tier 3 agent envelope returned by define / patch."""
-
-    agent_id: str       # f"{user_id}:{agent_name}"
-    user_id: str
-    agent_name: str
-    system_prompt: str
-    model: str
-    created_at: str     # ISO 8601 with offset
-    updated_at: str     # ISO 8601 with offset
-
-
-async def define_agent(
-    client: httpx.AsyncClient,
-    *,
-    agent_name: str,
-    system_prompt: str,
-    model: str,
-) -> Tier3AgentInfo:
-    """POST /agents/define → 201 with Tier3AgentInfo. See FN define_agent."""
-
-
-async def patch_agent(
-    client: httpx.AsyncClient,
-    agent_id: str,
-    *,
-    system_prompt: str | None = None,
-    model: str | None = None,
-) -> Tier3AgentInfo:
-    """PATCH /agents/<id> → 200 with updated Tier3AgentInfo. See FN patch_agent."""
-
-
-async def delete_agent(client: httpx.AsyncClient, agent_id: str) -> None:
-    """DELETE /agents/<id> → 204. See FN delete_agent."""
-```
-
-## Exception classes
-
-```python
-class Tier3QuotaExceeded(Exception):
-    """429 agent_quota_exceeded — 50-agent cap reached on the Heimdall key."""
-    def __init__(self, *, retry_after: int) -> None: ...
-    retry_after: int
-
-class Tier3UserIdUnsupported(Exception):
-    """403 tier3_user_id_unsupported — auth's user_id not slug-safe."""
-
-class Tier3FieldNotMutable(Exception):
-    """422 field_not_mutable — PATCH carrying an immutable key."""
-    def __init__(self, *, field: str | None) -> None: ...
-    field: str | None
-
-class Tier3LayerDeferred(Exception):
-    """422 layer_deferred — define carrying non-null layer field."""
-    def __init__(self, *, field: str | None) -> None: ...
-    field: str | None
-
-class Tier3AgentNotFound(Exception):
-    """404 — patch/delete on non-existent agent."""
-    def __init__(self, *, agent_id: str) -> None: ...
-    agent_id: str
-
-# Reused from ratatoskr.sessions (one-way import — sessions doesn't depend on tier3):
-# SessionApiFailed(status, body) for all other non-2xx responses.
-```
-
-## Functions
-
-### FN define_agent
-
-```
-FN define_agent(
-    client: httpx.AsyncClient,
-    *, agent_name: str, system_prompt: str, model: str,
-) -> Tier3AgentInfo
-BRIEF: POST /agents/define → 201 with Tier3AgentInfo.
-
-PRE-001: agent_name matches `[a-z][a-z0-9-]{2,63}` (slug guard — client-side
-         assert; the server enforces too, but this prevents wire round-trip
-         for trivially-bad input).
-PRE-002: system_prompt is non-empty.
-PRE-003: model is non-empty.
-
-STEPS:
-  1. assert PRE-001/002/003.
-  2. body = {
-       "agent_name": agent_name,
-       "system_prompt": system_prompt,
-       "model": model,
-     }
-  3. resp = await client.post("/agents/define", json=body)
-  4. ROUTE response status:
-     201 → parse body into Tier3AgentInfo, return.
-     422 → inspect error_code:
-       layer_deferred → raise Tier3LayerDeferred(field=err.get("field"))
-       (others) → raise SessionApiFailed(status=422, body=resp.content)
-     403 + tier3_user_id_unsupported → raise Tier3UserIdUnsupported
-     429 → raise Tier3QuotaExceeded(retry_after=int(resp.headers.get("Retry-After", 0)))
-     other → raise SessionApiFailed(status, body)
-
-POST-001: returned Tier3AgentInfo has agent_id of shape "<user_id>:<agent_name>".
-```
-
-### FN patch_agent
-
-```
-FN patch_agent(
-    client: httpx.AsyncClient, agent_id: str,
-    *, system_prompt: str | None = None, model: str | None = None,
-) -> Tier3AgentInfo
-BRIEF: PATCH /agents/<id> → 200 with updated Tier3AgentInfo.
-
-PRE-001: agent_id contains `:` (Tier 3 shape).
-PRE-002: at least one of system_prompt or model is non-None (no-op patches
-         are still server-accepted but client-side assert avoids the round-trip).
-
-STEPS:
-  1. assert PRE-001/002.
-  2. body = {}; if system_prompt is not None: body["system_prompt"] = system_prompt;
-     if model is not None: body["model"] = model.
-  3. resp = await client.patch(f"/agents/{agent_id}", json=body)
-  4. ROUTE response status:
-     200 → parse, return.
-     404 → raise Tier3AgentNotFound(agent_id=agent_id)
-     422 + field_not_mutable → raise Tier3FieldNotMutable(field=err.get("field"))
-     other → raise SessionApiFailed(status, body)
-```
-
-### FN delete_agent
-
-```
-FN delete_agent(client: httpx.AsyncClient, agent_id: str) -> None
-BRIEF: DELETE /agents/<id> → 204.
-
-PRE-001: agent_id contains `:` (Tier 3 shape).
-
-STEPS:
-  1. assert PRE-001.
-  2. resp = await client.delete(f"/agents/{agent_id}")
-  3. ROUTE response status:
-     204 → return None.
-     404 → raise Tier3AgentNotFound(agent_id=agent_id)
-     other → raise SessionApiFailed(status, body)
-```
-
-## CLI surface (`python -m ratatoskr.tier3`)
-
-```
-$ python -m ratatoskr.tier3 define --name wizard \
-    --system-prompt "You are a guided-elicitation wizard..." \
-    --model qwen3.6-35-a3b
-defined ratatoskr:wizard (qwen3.6-35-a3b)
-
-$ python -m ratatoskr.tier3 patch ratatoskr:wizard --system-prompt "New prompt"
-patched ratatoskr:wizard
-
-$ python -m ratatoskr.tier3 delete ratatoskr:wizard
-deleted ratatoskr:wizard
-```
-
-Auth + server URL: same env-var fallback as `ratatoskr.cli`. Exit codes: 0 / 10 (usage) / 11 (auth) / 20 (api-failure) / 21 (network).
-
-## Invariants
-
-- **INV-001**: `define_agent` request body carries exactly `{agent_name, system_prompt, model}` — no layer fields, no `bifrost`, no `metadata`. Phase 2.0 baseline shape only.
-- **INV-002**: `patch_agent` request body carries ONLY `system_prompt` and/or `model` — every other key is omitted. Server-side 422 `field_not_mutable` is the safety net; client-side body-construction is the first line.
-- **INV-003**: `delete_agent` is fire-and-confirm — no body, no retry, no soft-delete. Cascade handling is server-side; ratatoskr doesn't track it.
-- **INV-004**: All exceptions carry a `[:1024]` body cap (when applicable) per the issue #2 convention.
-- **INV-005**: CLI auth resolution mirrors `ratatoskr.cli`: `--api-key` flag > `$WORLDTREE_API_KEY` > exit 11.
-- **INV-006**: CLI server URL resolution mirrors `ratatoskr.cli`: `--server` > `$WORLDTREE_API_URL` > `http://localhost:8000`.
-- **INV-007**: Module never imports `ratatoskr.sessions` / `ratatoskr.sse_client` / `ratatoskr.tui` (one-way: only `cli.USER_AGENT` is imported, and only by `__main__.py` for the outbound User-Agent header).
-- **INV-008**: All HTTP through caller-owned `httpx.AsyncClient` — module never constructs its own client. (`__main__` constructs one for the CLI entry point per ratatoskr.cli's pattern.)
-
-## TESTS (tests/test_tier3.py — new file)
-
-```
-- test_define_happy: 201 + full response shape → Tier3AgentInfo populated.
-- test_define_quota_exceeded: 429 + Retry-After header → Tier3QuotaExceeded(retry_after=N).
-- test_define_user_id_unsupported: 403 tier3_user_id_unsupported → Tier3UserIdUnsupported.
-- test_define_layer_deferred_persona: 422 layer_deferred → Tier3LayerDeferred (would only fire if the body sent a layer field; the module never sends one, so this asserts server-side defense but reflecting a 422 we don't actually generate. Test exercises the response path, not the request).
-- test_define_bad_slug: PRE-001 assertion fires before HTTP for agent_name="X" (uppercase) or "ab" (too short).
-- test_define_empty_prompt: PRE-002 assertion fires for empty system_prompt.
-- test_define_other_5xx: 503 → SessionApiFailed(status=503).
-- test_patch_happy_both_fields: 200 + updated body → Tier3AgentInfo.
-- test_patch_happy_single_field: 200 with only system_prompt set; body omits model.
-- test_patch_field_not_mutable: 422 field_not_mutable → Tier3FieldNotMutable.
-- test_patch_404: 404 → Tier3AgentNotFound(agent_id=...).
-- test_patch_no_args: PRE-002 assertion fires (both None).
-- test_patch_non_tier3_id: PRE-001 assertion fires for agent_id without `:`.
-- test_delete_happy: 204 → returns None.
-- test_delete_404: 404 → Tier3AgentNotFound.
-- test_delete_non_tier3_id: PRE-001 assertion fires.
-- test_delete_other_5xx: 500 → SessionApiFailed.
-- test_cli_define_happy: argv → 201 mock → stdout="defined ratatoskr:wizard (qwen3.6-35-a3b)" + exit 0.
-- test_cli_patch_happy: argv → 200 mock → stdout="patched ratatoskr:wizard" + exit 0.
-- test_cli_delete_happy: argv → 204 mock → stdout="deleted ratatoskr:wizard" + exit 0.
-- test_cli_missing_auth: no API key → stderr "[auth_error]" + exit 11.
-- test_cli_api_failed: 500 mock → stderr "[api_failed]" + exit 20.
-```
-
-## ERROR_ROUTING (module + CLI)
-
-| HTTP shape | error_code | Exception (module) | CLI label | Exit |
-|---|---|---|---|---|
-| 201 / 200 / 204 | — | (none — happy) | one-line confirmation on stdout | 0 |
-| 429 | agent_quota_exceeded | `Tier3QuotaExceeded(retry_after=N)` | `[quota_exceeded] retry_after=N` | 20 |
-| 403 | tier3_user_id_unsupported | `Tier3UserIdUnsupported` | `[user_id_unsupported]` | 20 |
-| 404 | — | `Tier3AgentNotFound(agent_id=...)` | `[agent_not_found] <id>` | 20 |
-| 422 | field_not_mutable | `Tier3FieldNotMutable(field=...)` | `[field_not_mutable] field=...` | 20 |
-| 422 | layer_deferred | `Tier3LayerDeferred(field=...)` | `[layer_deferred] field=...` | 20 |
-| any other non-2xx | — | `SessionApiFailed(status, body)` | `[api_failed] status=N body=...` | 20 |
-| httpx.ConnectError / ReadTimeout / TransportError | — | propagates | `[network_error] T: M` | 21 |
-| PRE-001/002/003 assertion violation | — | `AssertionError` | `[usage_error] <msg>` | 10 |
-| no auth | — | `_AuthError` (reused from cli) | `[auth_error] no API key` | 11 |
-
-## Layout after this module lands
-
-```
-src/ratatoskr/
-  __init__.py
-  cli.py            (existing, unchanged)
-  sessions.py       (existing, unchanged)
-  sse_client.py     (existing, unchanged)
-  tui.py            (existing, unchanged)
-  tier3.py          NEW
-  __main__/         (no change — main cli still entry-point)
-
-# CLI invocation:
-$ python -m ratatoskr.tier3 define --name wizard ...
-$ python -m ratatoskr.tier3 patch ratatoskr:wizard ...
-$ python -m ratatoskr.tier3 delete ratatoskr:wizard
-```

docs/contracts/issues/2.contract.md

@@ -1,472 +0,0 @@
----
-contract_version: "2.1"
-target_module: "ratatoskr.sessions"
-scope: "Implement the Worldtree Conversation API session-lifecycle client for Ratatoskr. Two entry points: create_session (POST /sessions) and list_sessions (GET /sessions with cursor pagination), plus two shared frozen dataclasses (SessionInfo, SessionPage). Consumed by ratatoskr.cli for --send --new (single session create) and by ratatoskr.tui for the startup session picker (list). No core.* / worldtree.* imports; caller owns httpx.AsyncClient and Authorization header lifecycle. Convention-aligned with ratatoskr.sse_client (issue #1) — same posture, no shared types."
-depends_on:
-  - "httpx"
-used_by:
-  - "ratatoskr.cli"
-  - "ratatoskr.tui"
-language: "python"
-complexity: "low"
-estimated_loc: 150
-confidence: 0.9
-assumptions:
-  - "Worldtree spec pin (`docs/conversation-api-spec.md` at v1.0, repo SHA `55101e909abcd2219833266b6f905c5bc956e0f0`) is the wire contract. POST /sessions response shape (§POST /sessions) and GET /sessions response shape (§GET /sessions) are read FROM the spec, not from any Worldtree source import."
-  - "POST /sessions returns 201 Created with a body matching the documented shape (session_id, agent_id, message_count, created_at, last_active, metadata). The created_at/last_active fields are ISO 8601 strings with +HH:MM offsets."
-  - "GET /sessions cursor pagination uses the `v1.<base64url>` envelope (§Pagination); the consumer treats cursors as opaque strings (does not parse or construct them)."
-  - "Bifrost binding (Worldtree issue #160) is NOT used. create_session does not accept a `bifrost` parameter and never sends one in the request body."
-open_questions:
-  - "Should SessionInfo split into two dataclasses (CreatedSessionInfo with message_count vs ListedSessionInfo with archived/tags/name)? Draft uses one SessionInfo with origin-conditional fields whose defaults are codified in INV-001 (create) and INV-002 (list). Splitting would force callers to handle two types where they currently handle one; collapsing felt right for v1 but reconsider if presenters end up branching by origin."
-  - "Should list_sessions transparently paginate (iterate all pages) or surface one page at a time? Draft surfaces one page (SessionPage with next_cursor). Caller decides whether to iterate. Matches Worldtree's pagination idiom and lets the TUI render lazily."
-prd:
-  issue: 2
-  issue_url: "https://gitea.phasefinal.com/vh/ratatoskr/issues/2"
-  body_sha256_16: "01fbbd52b6d90eb0"
-  lock_in_comment_id: null
-  lock_in_sha256_16: null
-  lock_in_at: null
-  pinned_at: "2026-05-21T04:45:06+00:00"
-dependencies:
-  - issue: 1
-    path: "src/ratatoskr/sse_client.py"
-    reason: "Convention dependency, not a code dependency. Issue #1 establishes the API-consumption posture (caller-owns httpx client, async-native, no Worldtree imports, response-parsing into frozen dataclasses, exception body truncation to [:1024]). sessions.py follows the same shape."
----
-
-# Sessions — Worldtree Conversation API session lifecycle
-
-## Context
-
-`ratatoskr.sessions` is Ratatoskr's session-lifecycle client. Two entry points (`create_session`, `list_sessions`) plus two shared frozen dataclasses (`SessionInfo`, `SessionPage`). The module is the surface that `ratatoskr.cli` calls when `--send --new` mints a fresh session against Worldtree, and that `ratatoskr.tui` calls to populate the startup picker's `DataTable` of existing sessions.
-
-The module deliberately does NOT cover per-turn operations (those live in `ratatoskr.sse_client`), session mutation (`PATCH /sessions/{id}` is out of scope per design-brief §4 negative clauses), or session deletion (`DELETE /sessions/{id}` is admin work via `sessions_cli.py`).
-
-Convention-aligned with issue #1: caller owns the `httpx.AsyncClient` and Authorization header; the module never imports Worldtree source; responses are parsed into typed frozen dataclasses; exception `.body` payloads are truncated to `[:1024]` at construction.
-
-## Data flow
-
-**Input:**
-- `httpx.AsyncClient` (caller-owned, base_url + bearer auth on the client).
-- `agent_id: str` — for `create_session`.
-- `include_archived: bool`, `limit: int`, `cursor: str | None` — for `list_sessions`.
-
-**Output:**
-- `create_session` → `SessionInfo`:
-  - `session_id: str`
-  - `agent_id: str`
-  - `created_at: str` (ISO 8601 with offset)
-  - `last_active: str`
-  - `metadata: dict[str, Any]` (defaults to `{}` if the response omits the field — see INV-001)
-  - `message_count: int | None` (present from POST response; `None` when SessionInfo was sourced from a list item per spec §GET /sessions)
-  - `name: str | None` (always `None` when sourced from POST response; `None` if absent from list item; otherwise the list item's value)
-  - `archived: bool` (always `False` when sourced from POST response; defaults to `False` if absent or null in a list item; otherwise the list item's value)
-  - `tags: list[str]` (always `[]` when sourced from POST response; defaults to `[]` if absent or null in a list item; otherwise the list item's value)
-- `list_sessions` → `SessionPage`:
-  - `items: list[SessionInfo]`
-  - `next_cursor: str | None` (None on the last page; opaque string otherwise)
-
-**Side effects:** outbound HTTP only; no disk I/O, no global state.
-
-## Invariants
-
-- **INV-001 [hard]**: `create_session` returns a `SessionInfo` whose `session_id`, `agent_id`, `created_at`, `last_active`, and `metadata` are sourced from the 201 response body. `metadata` is taken from `body["metadata"]` when present and defaults to `{}` when absent (defensive against minor server-side spec drift; spec example always shows it present). `message_count` is taken from `body["message_count"]` (strict — bracket access, not `.get()`; the spec lists it as a response field and absent should surface as KeyError rather than silently default to None). List-only fields are fixed: `name=None`, `archived=False`, `tags=[]`.
-- **INV-002 [hard]**: `list_sessions` returns a `SessionPage` where every `SessionInfo` has `session_id`, `agent_id`, `created_at`, `last_active`, and `metadata` from the response item (same defensive `metadata` default as INV-001). `name` is `item.get("name")` (may be `None`). `archived` is `item.get("archived") or False` — absent, explicit-null, or explicit-false all yield `False`; explicit-true passes through. (Note: `item.get(key, default)` only fires `default` for absent keys, NOT for explicit-null values, so the `or False` form is load-bearing here.) `tags` is `item.get("tags") or []` (absent, explicit-null, or empty list all yield `[]`; a populated list passes through). `message_count` is `None` (the list endpoint does not include it — spec §GET /sessions: "`message_count` is not included in list items").
-- **INV-003 [hard]**: `list_sessions` treats cursors as opaque strings. The module never parses, base64-decodes, or constructs a cursor — it threads the server-provided `next_cursor` back verbatim on the next call. Per spec §Pagination ("Cursors are opaque to clients — do not parse or construct them.").
-- **INV-004 [hard]**: Both functions truncate exception `.body` payloads to `[:1024]` at construction. Matches the issue #1 precedent (`SseConnectFailed`, `CancelFailed`).
-- **INV-005 [hard]**: No `core.*` or `worldtree.*` imports. Boundary verified by `tests/test_no_worldtree_imports.py`.
-- **INV-006 [hard]**: `list_sessions` rejects out-of-range `limit` values (`< 1` or `> 200`) client-side before issuing any HTTP request. Spec §GET /sessions specifies the server returns 422 on out-of-range; the client refuses to send an obviously-invalid request rather than depending on the server to reject it.
-
-## Constraints
-
-- **[compatibility]** Module must work against the spec pin (`55101e909abcd2219833266b6f905c5bc956e0f0`, Worldtree v0.19.0).
-- **[security]** Module does not log full response bodies (they may carry user-readable session names + tags). Logging limited to status code + session_id when present.
-- **[style]** Async-native. No sync entry points. Consistent with `sse_client`.
-
-## Out of scope
-
-- **Bifrost binding** (Worldtree issue #160). `create_session` does not accept or send a `bifrost` field. Ratatoskr is not a Bifrost consumer; consumer-side tool injection is an advanced feature outside the dev TUI's purpose.
-- **Ephemeral / Saga sessions.** Separate session class with TTL semantics; not needed for hands-on dev probing.
-- **`GET /sessions/{id}` (single fetch), `PATCH /sessions/{id}` (mutation), `DELETE /sessions/{id}` (deletion).** Per design-brief §4 negative clauses; admin operations live outside Ratatoskr.
-- **`GET /sessions/{id}/messages` (history pagination).** Deferred until the TUI needs scrollback replay; `--send` doesn't need history.
-- **Transparent multi-page iteration.** `list_sessions` returns one page; caller threads `next_cursor` for the next call. Don't add an `iter_all_sessions()` until the TUI proves it needs that shape.
-- **Server retry / backoff.** Caller's policy. The module does not retry on 5xx; it surfaces failure once and returns control.
-
----
-
-```contract
-FN create_session(client: httpx.AsyncClient, agent_id: str, *, end_user_id: str | None = None) -> SessionInfo
-BRIEF: POST /sessions with {"agent_id": agent_id} (and {"end_user_id": end_user_id} when non-None) to create a new conversation session. Returns SessionInfo populated from the 201 response. Per issue #5: keyword-only `end_user_id` for per-end-user agents (lofn etc.); default-None preserves the pre-#5 baseline.
-PRE: [PRE-001 hard] client is not None -- assert client is not None
-PRE: [PRE-002 hard] agent_id is a non-empty string -- assert agent_id and isinstance(agent_id, str)
-PRE: [PRE-003 hard, issue #5] end_user_id is None OR a non-empty string -- assert end_user_id is None or (isinstance(end_user_id, str) and end_user_id)
-POST: [POST-001 side_effect] exactly one POST to /sessions was issued; body is {"agent_id": agent_id} when end_user_id is None, OR {"agent_id": agent_id, "end_user_id": end_user_id} when non-None (issue #5 INV-002: omitting the field when None is NOT the same as sending empty)
-POST: [POST-002 return_value] returns SessionInfo with session_id, agent_id, created_at, last_active, metadata populated from response -- assert all 5 fields non-None
-POST: [POST-003 return_value] returns SessionInfo where message_count == response["message_count"] (typically 0 for a fresh session) and list-only fields carry the create-origin fixed defaults per INV-001 -- assert info.message_count is not None and info.name is None and info.archived is False and info.tags == []
-ERROR_ROUTING:
-  HTTP 404 unknown_agent_id:
-    local_handling: raise AgentNotFound(agent_id=agent_id)
-    flow_control: abort
-    state_recovery: none (caller passed an unknown agent_id; that's a user error)
-  HTTP 422 validation_failed:
-    local_handling: raise SessionApiFailed(status=422, body=resp.content[:1024])
-    flow_control: abort
-    state_recovery: none (typically client bug; surface for debugging. Issue #5: a `end_user_id_required` 422 indicates the agent requires --end-user-id; raw label is honest, hint translation deferred.)
-  httpx.HTTPStatusError (other status):
-    local_handling: raise SessionApiFailed(status=resp.status_code, body=resp.content[:1024])
-    flow_control: abort
-    state_recovery: none
-STEPS:
-  1. [setup, flexibility=prescriptive] Validate inputs per PRE-001, PRE-002, PRE-003
-  2. [sequential, flexibility=prescriptive] Build body = {"agent_id": agent_id}; IF end_user_id is not None: body["end_user_id"] = end_user_id
-  3. [sequential, flexibility=prescriptive] CALL client.post("/sessions", json=body)
-     tool: { destructive: false, idempotent: false, read_only: false, open_world: false }
-  4. [branch, flexibility=prescriptive] IF resp.status_code == 404: RAISE AgentNotFound
-     ELIF resp.status_code != 201: RAISE SessionApiFailed
-  5. [sequential] Parse resp.json() → body
-  6. [cleanup] RETURN SessionInfo(
-        session_id=body["session_id"],
-        agent_id=body["agent_id"],
-        created_at=body["created_at"],
-        last_active=body["last_active"],
-        metadata=body.get("metadata", {}),     # INV-001 defensive default
-        message_count=body["message_count"],   # INV-001/POST-003: required, never defaulted
-        name=None,                             # INV-001 fixed for create-origin
-        archived=False,                        # INV-001 fixed for create-origin
-        tags=[],                               # INV-001 fixed for create-origin
-     )
-TESTS:
-  happy_create [happy,tracer]: mock returns 201 with full body → returns SessionInfo with all create-side fields populated; list-only fields are at create-origin defaults (name=None, archived=False, tags=[])
-  happy_create_with_metadata [happy]: response includes metadata={"model": "glm5-turbo"} → SessionInfo.metadata == {"model": "glm5-turbo"}
-  request_body_shape [trace]: outbound JSON body is exactly {"agent_id": <arg>} when end_user_id omitted — no Bifrost field, no extra keys
-  unknown_agent_id [error]: mock returns 404 → raises AgentNotFound(agent_id="mimir")
-  validation_failed [error]: mock returns 422 → raises SessionApiFailed(status=422); body truncated to ≤1024 bytes
-  unexpected_status_truncates [error]: mock returns 500 with 5000-byte body → SessionApiFailed; .body is exactly the first 1024 bytes
-  empty_agent_id [adversarial]: agent_id="" → AssertionError; no HTTP issued
-  happy_create_with_end_user_id [happy, issue #5]: end_user_id="alice" → outbound JSON body == {"agent_id": "mimir", "end_user_id": "alice"} byte-for-byte; SessionInfo populated as today
-  default_omits_end_user_id [trace, issue #5]: omit end_user_id kwarg → outbound JSON body == {"agent_id": "mimir"} (no end_user_id key); preserves the pre-#5 baseline
-  empty_end_user_id [adversarial, issue #5]: end_user_id="" → AssertionError before HTTP (PRE-003)
-```
-
-```contract
-FN list_sessions(client: httpx.AsyncClient, *, include_archived: bool = False, limit: int = 50, cursor: str | None = None) -> SessionPage
-BRIEF: GET /sessions with cursor pagination. Returns one SessionPage. Caller threads next_cursor for subsequent pages.
-PRE: [PRE-001 hard] client is not None -- assert client is not None
-PRE: [PRE-002 hard] limit is in [1, 200] -- assert 1 <= limit <= 200 (INV-006: refuse out-of-range client-side; do not depend on server 422)
-PRE: [PRE-003 hard] cursor is None or a non-empty string -- assert cursor is None or (isinstance(cursor, str) and cursor)
-POST: [POST-001 side_effect] exactly one GET to /sessions was issued -- assert mock_router.calls.call_count == 1
-POST: [POST-002 side_effect] query string carries `limit=<limit>` always; `include_archived=true` iff caller passed include_archived=True; `cursor=<cursor>` iff caller passed a cursor -- assert URL params match
-POST: [POST-003 return_value] returns SessionPage(items=[SessionInfo, ...], next_cursor=str|None) per response -- assert isinstance(result.items, list) and (result.next_cursor is None or isinstance(result.next_cursor, str))
-POST: [POST-004 return_value] each SessionInfo in items has list-side fields (name, archived, tags) populated and message_count=None per INV-002 -- assert all(info.message_count is None for info in result.items)
-ERROR_ROUTING:
-  HTTP 422 (cursor_invalid):
-    local_handling: parse body for error_code; raise InvalidCursor(raw=cursor) if error_code == "cursor_invalid"; else raise SessionApiFailed
-    flow_control: abort
-    state_recovery: caller policy — restart from page 1 (cursor=None)
-  HTTP 422 (other validation_failed):
-    local_handling: raise SessionApiFailed(status=422, body=resp.content[:1024])
-    flow_control: abort
-    state_recovery: none (PRE-002/003 should have caught client-side issues; server-side 422 means spec mismatch)
-  httpx.HTTPStatusError (other status):
-    local_handling: raise SessionApiFailed(status=resp.status_code, body=resp.content[:1024])
-    flow_control: abort
-    state_recovery: none
-STEPS:
-  1. [setup, flexibility=prescriptive] Validate inputs per PRE-001..PRE-003
-  2. [sequential, flexibility=prescriptive] Build params dict: {"limit": limit}; ADD "include_archived": "true" iff include_archived; ADD "cursor": cursor iff cursor is not None
-  3. [sequential, flexibility=prescriptive] CALL client.get("/sessions", params=params)
-     tool: { destructive: false, idempotent: true, read_only: true, open_world: false }
-  4. [branch, flexibility=prescriptive] IF resp.status_code == 422:
-       Parse body; IF body.get("error_code") == "cursor_invalid": RAISE InvalidCursor(raw=cursor)
-       ELSE: RAISE SessionApiFailed(status=422, body=resp.content[:1024])
-     ELIF resp.status_code != 200: RAISE SessionApiFailed
-  5. [sequential] Parse resp.json() → body
-  6. [loop] FOR EACH item in body["items"]: CONSTRUCT SessionInfo(
-        session_id=item["session_id"],
-        agent_id=item["agent_id"],
-        created_at=item["created_at"],
-        last_active=item["last_active"],
-        metadata=item.get("metadata", {}),       # INV-002 defensive default
-        message_count=None,                      # not in list response per spec
-        name=item.get("name"),                   # INV-002: may be None
-        archived=item.get("archived") or False,  # INV-002: absent/null/false → False (the `or` form is load-bearing — .get(k, default) does not fire default on explicit null)
-        tags=item.get("tags") or [],             # INV-002: absent/null/[] → []
-     )
-  7. [cleanup] RETURN SessionPage(items=infos, next_cursor=body.get("next_cursor"))
-TESTS:
-  happy_first_page [happy,tracer]: GET /sessions, mock returns {items: [one full session shape], next_cursor: "v1.abc..."} → SessionPage(items=[1], next_cursor="v1.abc...")
-  happy_last_page [happy]: mock returns {items: [...], next_cursor: null} → SessionPage with next_cursor=None
-  empty_results [happy]: mock returns {items: [], next_cursor: null} → SessionPage([], None)
-  include_archived_query [trace]: include_archived=True → URL has include_archived=true; default (include_archived=False) → URL has NO include_archived param at all (STEP 2 prescribes "ADD include_archived='true' iff include_archived" — the test asserts absence on default, not an explicit false)
-  cursor_threaded [trace]: cursor="opaque-from-prev-page" → URL has cursor=opaque-from-prev-page
-  limit_query [trace]: limit=10 → URL has limit=10
-  invalid_cursor_server [error]: mock returns 422 with body {"error_code":"cursor_invalid","message":"..."} → raises InvalidCursor(raw=<the cursor passed in>)
-  other_validation_failed [error]: mock returns 422 with body {"error_code":"validation_failed",...} → raises SessionApiFailed(status=422); body truncated
-  unexpected_status_truncates [error]: mock returns 500 with 5000-byte body → SessionApiFailed; .body is exactly the first 1024 bytes
-  limit_below_one [adversarial]: limit=0 → AssertionError; no HTTP issued
-  limit_above_max [adversarial]: limit=300 → AssertionError; no HTTP issued
-  empty_cursor [adversarial]: cursor="" → AssertionError; no HTTP issued
-```
-
-## Amendment 2026-06-30 — boot-time introspection reads (v1 coverage-audit: capabilities+me)
-
-The v1 coverage-audit added two read-only server-introspection endpoints as
-cheap debug primitives (surfaced via a new `ratatoskr --whoami` one-shot). Both
-mirror `get_persona_state`: GET, 200 → parsed dict verbatim, any non-200 →
-`SessionApiFailed`. The frozen OpenAPI types both responses as freeform objects,
-so the wrappers return `dict[str, Any]` (not a typed dataclass).
-
-```contract
-FN get_me(client: httpx.AsyncClient) -> dict[str, Any]
-BRIEF: GET /me — the authenticated principal's identity + key metadata (spec §GET /me). Boot-time whoami: verify the key without agent-config side effects. Returns parsed JSON verbatim; spec documents {user_id, scopes, tier, display_name?, key_id?, key_label?, ...} with optional fields OMITTED (not null). Read-only, rate-exempt, no audit emission.
-PRE: [PRE-001 hard] client is not None -- assert client is not None
-POST: [POST-001 return_value] on 200 returns resp.json() unmodified -- assert result == resp.json()
-ERROR_ROUTING:
-  HTTP non-200 (incl. 401 bad/absent key when auth enabled):
-    local_handling: raise SessionApiFailed(status=resp.status_code, body=resp.content)
-    flow_control: abort
-    state_recovery: none (caller decides: bad key → re-key; degraded tier="unknown" is still a 200)
-STEPS:
-  1. [setup, prescriptive] assert client is not None
-  2. [sequential, prescriptive] resp = await client.get("/me")
-  3. [branch, prescriptive] IF resp.status_code == 200: RETURN resp.json(); ELSE RAISE SessionApiFailed
-TESTS:
-  happy_authenticated [happy,tracer]: 200 {user_id, scopes, tier, key_id} → dict returned verbatim
-  anonymous_dev_mode: 200 {user_id:"anonymous", tier:"anonymous"} → dict; no key_* fields (omitted)
-  401_raises [error]: 401 → SessionApiFailed(status=401)
-
-FN get_capabilities(client: httpx.AsyncClient) -> dict[str, Any]
-BRIEF: GET /capabilities — server capability discovery (spec §Ephemeral Templates). Returns {ephemeral_templates: {echo: {allowed_models, default_model, system_prompt_max_bytes}}}. Any authenticated caller may read it (no instantiate scope). Parsed dict verbatim; any non-200 → SessionApiFailed.
-PRE: [PRE-001 hard] client is not None -- assert client is not None
-POST: [POST-001 return_value] on 200 returns resp.json() unmodified -- assert result == resp.json()
-ERROR_ROUTING:
-  HTTP non-200:
-    local_handling: raise SessionApiFailed(status=resp.status_code, body=resp.content)
-    flow_control: abort
-    state_recovery: none
-STEPS:
-  1. [setup, prescriptive] assert client is not None
-  2. [sequential, prescriptive] resp = await client.get("/capabilities")
-  3. [branch, prescriptive] IF resp.status_code == 200: RETURN resp.json(); ELSE RAISE SessionApiFailed
-TESTS:
-  happy [happy]: 200 {ephemeral_templates:{echo:{...}}} → dict returned verbatim
-  non_200_raises [error]: 500 → SessionApiFailed(status=500)
-```
-
-## Amendment 2026-07-01 — session tool introspection (v1 coverage-audit)
-
-Owner-scoped tool-inventory read (spec #183, `GET /sessions/{id}/tools`),
-surfaced in the TUI Tools pane on session-attach. Same shape as the other
-introspection wrappers: GET, 200 → parsed dict verbatim, non-200 →
-`SessionApiFailed`. Reachable with the consumer key (no admin scope), unlike the
-admin variant `GET /admin/sessions/{id}/tools`.
-
-```contract
-FN get_session_tools(client: httpx.AsyncClient, session_id: str) -> dict[str, Any]
-BRIEF: GET /sessions/{session_id}/tools — owner-scoped merged tool inventory (spec #183) the LLM saw at turn-fire: {agent_id, builtin_tools: [...], bifrost_tools: [{name, description, parameters}, ...]}. Owner gate (ctx.user_id == session.user_id); cross-owner → 404 session_not_found (existence-hiding), revoked → 401 auth_revoked. Parsed dict verbatim; any non-200 → SessionApiFailed.
-PRE: [PRE-001 hard] client is not None -- assert client is not None
-PRE: [PRE-002 hard] session_id is non-empty str -- assert session_id and isinstance(session_id, str)
-POST: [POST-001 return_value] on 200 returns resp.json() unmodified -- assert result == resp.json()
-ERROR_ROUTING:
-  HTTP non-200 (incl. 404 session_not_found cross-owner/unknown, 401 auth_revoked):
-    local_handling: raise SessionApiFailed(status=resp.status_code, body=resp.content)
-    flow_control: abort
-    state_recovery: none
-STEPS:
-  1. [setup, prescriptive] assert PRE-001, PRE-002
-  2. [sequential, prescriptive] resp = await client.get(f"/sessions/{session_id}/tools")
-  3. [branch, prescriptive] IF resp.status_code == 200: RETURN resp.json(); ELSE RAISE SessionApiFailed
-TESTS:
-  happy [happy,tracer]: 200 {agent_id, builtin_tools:[], bifrost_tools:[{name,...}]} → dict verbatim
-  cross_owner_404 [error]: 404 session_not_found → SessionApiFailed(status=404)
-  empty_session_id [adversarial]: "" → AssertionError; no HTTP issued
-```
-
-## Amendment 2026-07-01 — admin BifrostState read (v1 coverage-audit)
-
-Admin-scoped Bifrost dispatch-state read (spec #176, `GET /admin/sessions/{id}/bifrost`),
-surfaced in the TUI BifrostState pane on session-attach. The first admin-key
-consumer in ratatoskr: requires the `admin.sessions.read` scope, so the request
-OVERRIDES the Authorization header with the caller-supplied `admin_key` (distinct
-from the client's default consumer key). Same result-shape convention as the
-other introspection wrappers: 200 → parsed dict verbatim, non-200 → `SessionApiFailed`.
-
-```contract
-FN get_session_bifrost(client: httpx.AsyncClient, session_id: str, *, admin_key: str) -> dict[str, Any]
-BRIEF: GET /admin/sessions/{session_id}/bifrost — admin-scoped live Bifrost binding (spec #176): {endpoint_url, consumer_id, connected, capabilities_granted, tools:[{name, description}]}. Requires admin.sessions.read; the request sets Authorization: Bearer <admin_key> (override), NOT the client's default consumer bearer. Parsed dict verbatim; any non-200 → SessionApiFailed — notably 403 auth_scope_denied and 404 session_not_bifrost_bound.
-PRE: [PRE-001 hard] client is not None -- assert client is not None
-PRE: [PRE-002 hard] session_id is non-empty str -- assert session_id and isinstance(session_id, str)
-PRE: [PRE-003 hard] admin_key is non-empty str -- assert admin_key and isinstance(admin_key, str)
-POST: [POST-001 return_value] on 200 returns resp.json() unmodified -- assert result == resp.json()
-POST: [POST-002 state_change] the outbound request Authorization header == f"Bearer {admin_key}" (override) -- assert request.headers["Authorization"] == "Bearer " + admin_key
-ERROR_ROUTING:
-  HTTP non-200 (incl. 403 auth_scope_denied, 404 session_not_found / session_not_bifrost_bound):
-    local_handling: raise SessionApiFailed(status=resp.status_code, body=resp.content)
-    flow_control: abort
-    state_recovery: none (caller decides: 403 → key lacks scope; 404 not-bound → benign unbound session)
-STEPS:
-  1. [setup, prescriptive] assert PRE-001..PRE-003
-  2. [sequential, prescriptive] resp = await client.get(f"/admin/sessions/{session_id}/bifrost", headers={"Authorization": f"Bearer {admin_key}"})
-  3. [branch, prescriptive] IF resp.status_code == 200: RETURN resp.json(); ELSE RAISE SessionApiFailed
-TESTS:
-  happy_uses_admin_bearer [happy,tracer]: 200 {endpoint_url, connected, capabilities_granted, tools} → dict verbatim; request Authorization == "Bearer <admin_key>" (override)
-  scope_denied_403 [error]: 403 → SessionApiFailed(status=403)
-  not_bound_404 [error]: 404 session_not_bifrost_bound → SessionApiFailed(status=404)
-  empty_admin_key [adversarial]: admin_key="" → AssertionError; no HTTP issued
-```
-
-## Amendment 2026-07-01 — Tier-2: transient characters + persona-state write (v1 coverage-audit)
-
-The last in-scope client I/O points. Transient-character CRUD (#161) surfaced
-via a `--characters` one-shot lifecycle probe; persona-state write surfaced via
-`--set-persona-pad "p,a,d"` (requires `--session`). All mirror the existing
-wrappers: parsed dict verbatim (or None on 204), any off-status → SessionApiFailed.
-**Note:** `set_persona_state`'s request body is FREEFORM — the frozen OpenAPI 2.2.0
-declares no request schema and the prose spec documents only the GET counterpart,
-so the caller supplies the snapshot shape. **Canonical (worldtree-dev prose #317,
-`c9e59ec`): `{pad:{pleasure,arousal,dominance}}` — a named-key dict, NOT a list;
-`--set-persona-pad` builds + sends the named dict (each float in [-1,1]).**
-
-```contract
-FN list_character_models(client) -> dict[str, Any]
-BRIEF: GET /models/available-for-characters (character.read). Returns {items:[{name, description, thinking}]}. Non-200 → SessionApiFailed.
-PRE: [PRE-001 hard] client is not None
-POST: [POST-001 return_value] on 200 returns resp.json() unmodified
-STEPS:
-  1. [sequential, prescriptive] resp = await client.get("/models/available-for-characters"); IF 200 RETURN resp.json(); ELSE RAISE SessionApiFailed
-TESTS:
-  list_models [happy,tracer]: 200 {items:[{name:"fast"}]} → dict verbatim
-
-FN create_character(client, character: dict, *, state: dict | None = None) -> dict[str, Any]
-BRIEF: POST /characters (character.write). Body {character, state}. Returns 201 {character_id, ttl_expires_at}; non-201 → SessionApiFailed.
-PRE: [PRE-001 hard] client is not None; [PRE-002 hard] character is a non-empty dict
-POST: [POST-001 return_value] on 201 returns resp.json(); [POST-002 side_effect] outbound body == {"character": <arg>, "state": <state|null>}
-STEPS:
-  1. [sequential, prescriptive] resp = await client.post("/characters", json={"character": character, "state": state}); IF 201 RETURN resp.json(); ELSE RAISE SessionApiFailed
-TESTS:
-  create [happy]: 201 → {character_id}; body is {character, state:null}
-  create_403 [error]: 403 auth_scope_denied → SessionApiFailed(403)
-
-FN get_character_state(client, character_id: str) -> dict[str, Any]
-BRIEF: GET /characters/{id}/state (character.read). Live PAD/emotions snapshot; refreshes TTL. Non-200 → SessionApiFailed.
-PRE: [PRE-001 hard] client not None; [PRE-002 hard] character_id non-empty str
-POST: [POST-001 return_value] on 200 returns resp.json()
-STEPS:
-  1. [sequential, prescriptive] resp = await client.get(f"/characters/{character_id}/state"); IF 200 RETURN resp.json(); ELSE RAISE SessionApiFailed
-TESTS:
-  get_state [happy]: 200 {pad:[...]} → dict verbatim
-
-FN delete_character(client, character_id: str) -> None
-BRIEF: DELETE /characters/{id} (character.write). 200/204 → None; other → SessionApiFailed.
-PRE: [PRE-001 hard] client not None; [PRE-002 hard] character_id non-empty str
-POST: [POST-001 return_value] on 200/204 returns None
-STEPS:
-  1. [sequential, prescriptive] resp = await client.delete(f"/characters/{character_id}"); IF status in (200,204) RETURN None; ELSE RAISE SessionApiFailed
-TESTS:
-  delete [happy]: 204 → None
-
-FN set_persona_state(client, session_id: str, snapshot: dict) -> None
-BRIEF: POST /sessions/{session_id}/persona_state — set a session's persona state (affect injection). Request body is the FREEFORM snapshot (caller-supplied; unpinned in the frozen surface). 204 → None; other → SessionApiFailed.
-PRE: [PRE-001 hard] client not None; [PRE-002 hard] session_id non-empty str; [PRE-003 hard] snapshot is a dict
-POST: [POST-001 return_value] on 204 returns None; [POST-002 side_effect] outbound body == snapshot verbatim
-STEPS:
-  1. [sequential, prescriptive] resp = await client.post(f"/sessions/{session_id}/persona_state", json=snapshot); IF 204 RETURN None; ELSE RAISE SessionApiFailed
-TESTS:
-  happy [happy]: 204 → None; body == {"pad":{"pleasure","arousal","dominance"}} verbatim (canonical named-key dict, #317)
-  non_204 [error]: 422 → SessionApiFailed(422)
-```
-
-## Amendment 2026-07-06 — authored-history write (#347, v1 coverage-audit re-open)
-
-Worldtree shipped #347 (authored-history-write) as OpenAPI 2.3.0: a new
-`POST /sessions/{session_id}/history` primitive that writes ONE model-visible
-turn into a session's ledger AS the bound agent, WITHOUT a generation and
-WITHOUT lived-turn side effects (the SillyTavern "first message"). The re-vendor
-(2.2.0→2.3.0, pin `879cefe`) re-opened the v1 coverage-audit with this one new
-in-scope REST path-group; this amendment closes it on the consumer side and also
-un-defers `GET /sessions/{id}/messages` (previously §Out of scope) as the seed's
-read-back.
-
-**Hide-existence (server INV-347-1) — the load-bearing consumer contract.** The
-`session.history.write` grant is checked FIRST — an ungranted caller (or a
-non-owner, or an unknown session) gets a 404 **byte-identical** to a genuine
-`session_not_found`, never a 403/409/422 that would reveal the feature exists.
-The consumer MUST honor this: treat 404 as **feature-absent**, fall back (a
-production consumer to a model-generated greeting), and NEVER capability-probe to
-tell feature-absent from ungranted from session-absent. The wrapper encodes it by
-raising a DISTINCT `AuthoredHistoryUnavailable` on 404 (NOT `SessionApiFailed`),
-so a caller branches feature-absent without inspecting a status code.
-
-**Request body — v1-minimal, wire-pinned by the server.** The frozen OpenAPI 2.3.0
-exports an empty request schema, but the server pins `AuthoredWriteRequest`
-(`extra="forbid"`): `{author, content, idempotency_key, effects?,
-claimed_original_at?}`. v1: `author="assistant"` (only value), `content` (UTF-8,
-server-bounded at `authored_content_max_bytes`=8192), `idempotency_key` (REQUIRED,
-per-session dedup), `effects` omitted (== "none"; only value). Because
-`extra="forbid"`, the wrapper omits `effects`/`claimed_original_at` when None
-(never sends null). Success is 201 (fresh) OR 200 (idempotent replay,
-byte-identical body); both return the `AuthoredTurnResponse` `{author,
-content_chars, injected_at, phase, seq, session_id, turn_id}` verbatim (provenance
-is audit-only, NEVER on this body — INV-347-7).
-
-**Assistant-first provider constraint (deferred, inert for the probe).** A
-create-time first-message makes the assistant seq-0 (assistant-first history);
-Anthropic-family providers 400 the *next generation*, vLLM/openai_compat tolerate
-it. The `--seed-first-message` probe seeds but does NOT generate, so the
-constraint is inert for the probe — a real consumer that then generates must bind
-an assistant-first-tolerant provider.
-
-```contract
-FN write_authored_history(client: httpx.AsyncClient, session_id: str, *, content: str, idempotency_key: str, author: str = "assistant", effects: str | None = None, claimed_original_at: str | None = None) -> dict[str, Any]
-BRIEF: POST /sessions/{session_id}/history — the #347 authored-history-write primitive (write one model-visible turn as the bound agent, no generation, no side effects). Body {author, content, idempotency_key} + "effects"/"claimed_original_at" only when non-None (server AuthoredWriteRequest is extra="forbid"). Success 200 (replay) or 201 (fresh) → AuthoredTurnResponse dict verbatim. 404 → AuthoredHistoryUnavailable (hide-existence: feature-absent/ungranted/session-absent, indistinguishable by design — consumer falls back, never probes). Any other non-2xx → SessionApiFailed.
-PRE: [PRE-001 hard] client is not None -- assert client is not None
-PRE: [PRE-002 hard] session_id is a non-empty str -- assert session_id and isinstance(session_id, str)
-PRE: [PRE-003 hard] content is a non-empty str -- assert content and isinstance(content, str)
-PRE: [PRE-004 hard] idempotency_key is a non-empty str -- assert idempotency_key and isinstance(idempotency_key, str)
-PRE: [PRE-005 hard] author is a non-empty str -- assert author and isinstance(author, str)
-POST: [POST-001 side_effect] exactly one POST to /sessions/{session_id}/history; body == {"author": author, "content": content, "idempotency_key": idempotency_key} plus "effects" iff effects is not None plus "claimed_original_at" iff claimed_original_at is not None (no null-valued keys — extra="forbid")
-POST: [POST-002 return_value] on 200 or 201 returns resp.json() unmodified
-ERROR_ROUTING:
-  HTTP 404 (hide-existence session_not_found):
-    local_handling: raise AuthoredHistoryUnavailable(session_id=session_id)
-    flow_control: abort
-    state_recovery: caller treats as feature-absent; fall back to a model-generated greeting; NEVER capability-probe (INV-347-1)
-  HTTP other non-2xx (incl. 409 generation_active, 422 content_too_long/validation_failed, 401 auth_revoked, 410 session_retired):
-    local_handling: raise SessionApiFailed(status=resp.status_code, body=resp.content)
-    flow_control: abort
-    state_recovery: none (409 retryable; 422 caller bug/oversize)
-STEPS:
-  1. [setup, flexibility=prescriptive] assert PRE-001..PRE-005
-  2. [sequential, flexibility=prescriptive] body = {"author": author, "content": content, "idempotency_key": idempotency_key}; IF effects is not None: body["effects"] = effects; IF claimed_original_at is not None: body["claimed_original_at"] = claimed_original_at
-  3. [sequential, flexibility=prescriptive] resp = await client.post(f"/sessions/{session_id}/history", json=body)
-     tool: { destructive: false, idempotent: true, read_only: false, open_world: false }
-  4. [branch, flexibility=prescriptive] IF resp.status_code in (200, 201): RETURN resp.json(); ELIF resp.status_code == 404: RAISE AuthoredHistoryUnavailable(session_id=session_id); ELSE RAISE SessionApiFailed(status=resp.status_code, body=resp.content)
-TESTS:
-  happy_fresh_201 [happy,tracer]: 201 {author:"assistant", seq:0, phase:"seeded", turn_id, content_chars, session_id, injected_at} → dict verbatim; outbound body == {"author":"assistant","content":<c>,"idempotency_key":<k>} exactly (no effects/claimed_original_at keys)
-  happy_replay_200 [happy]: 200 (same-key replay, byte-identical body) → dict verbatim
-  body_includes_effects [trace]: effects="none" → outbound body has "effects":"none"; claimed_original_at="2020-01-01T00:00:00Z" → body has that key too
-  hide_existence_404 [error]: 404 {error_code:"session_not_found"} → raises AuthoredHistoryUnavailable(session_id=<arg>), NOT SessionApiFailed
-  generation_active_409 [error]: 409 {error_code:"generation_active"} → SessionApiFailed(status=409)
-  content_too_long_422 [error]: 422 {error_code:"content_too_long"} → SessionApiFailed(status=422)
-  empty_content [adversarial]: content="" → AssertionError; no HTTP issued
-  empty_idempotency_key [adversarial]: idempotency_key="" → AssertionError; no HTTP issued
-  empty_session_id [adversarial]: session_id="" → AssertionError; no HTTP issued
-
-FN get_session_messages(client: httpx.AsyncClient, session_id: str) -> dict[str, Any]
-BRIEF: GET /sessions/{session_id}/messages — the session's message history (spec §GET /sessions/{id}/messages), un-deferred as the #347 probe's read-back so a seeded turn can be confirmed to render as a normal role=assistant message (model-invisible provenance — a seed is indistinguishable from a lived turn on read). Returns {session_id, items:[{seq, role, content, ...}], next_cursor} verbatim. Owner-scoped; any non-200 → SessionApiFailed. v1 reads the server default page (no pagination params — the probe reads a fresh 1-message session; add limit/cursor when a caller needs scrollback).
-PRE: [PRE-001 hard] client is not None -- assert client is not None
-PRE: [PRE-002 hard] session_id is a non-empty str -- assert session_id and isinstance(session_id, str)
-POST: [POST-001 return_value] on 200 returns resp.json() unmodified
-ERROR_ROUTING:
-  HTTP non-200 (incl. 404 session_not_found cross-owner/unknown):
-    local_handling: raise SessionApiFailed(status=resp.status_code, body=resp.content)
-    flow_control: abort
-    state_recovery: none
-STEPS:
-  1. [setup, flexibility=prescriptive] assert PRE-001, PRE-002
-  2. [sequential, flexibility=prescriptive] resp = await client.get(f"/sessions/{session_id}/messages")
-  3. [branch, flexibility=prescriptive] IF resp.status_code == 200: RETURN resp.json(); ELSE RAISE SessionApiFailed
-TESTS:
-  happy [happy]: 200 {session_id, items:[{seq:0, role:"assistant", content:"…"}], next_cursor:null} → dict verbatim
-  not_found_404 [error]: 404 → SessionApiFailed(status=404)
-  empty_session_id [adversarial]: "" → AssertionError; no HTTP issued
-```

docs/contracts/web_debug_surface.contract.md

@@ -82,11 +82,12 @@ functions:
     flexibility: "prescriptive"
 
   - name: "create_app (amendment)"
-    signature: "create_app(client_factory, *, end_user_id=None, bifrost_consumer_key=None, bifrost_visible_host=None, affect_read_url=None, admin_key=None) -> Starlette"
-    description: "New optional admin_key param stored at app.state.admin_key; entrypoint passes RATATOSKR_ADMIN_API_KEY. Three new routes registered."
+    signature: "create_app(client_factory, *, end_user_id=None, bifrost_consumer_key=None, bifrost_visible_host=None, affect_read_url=None, memory_read_url=None, admin_key=None) -> Starlette"
+    description: "New optional admin_key param stored at app.state.admin_key; entrypoint passes RATATOSKR_ADMIN_API_KEY. v0.20.7 adds memory_read_url (app.state.memory_read_url, from RATATOSKR_MEMORY_READ_URL) for the memory viewer. Four new routes registered across the arc."
     postconditions:
       - "POST-001: app.state.admin_key = admin_key (default None -> the two admin routes fail-visible per their PRE-001)."
       - "POST-002: routes /api/sessions/{session_id}/tools, /api/sessions/{session_id}/bifrost, /api/admin/events added; existing routes unchanged."
+      - "POST-003 (v0.20.7): app.state.memory_read_url = memory_read_url; route /api/memory/chunks added (the memory-viewer proxy)."
     flexibility: "closed"
 
   - name: "reasoning indicator (index.html: showThinkingNote / hideThinkingNote)"
@@ -125,26 +126,45 @@ functions:
     flexibility: "open"
 
   - name: "renderConsole + trend (v0.20.0 — unified persona/affect console; supersedes renderAffectPane/renderPersonaPane/setPersonaStrip)"
-    signature: "renderConsole(snap) ; setFader(axis,v) ; setFaderTrend(axis) ; renderOrbit() ; renderDominant(snap) ; renderDerived(snap) ; renderRelations(snap) ; renderDirective(snap) ; pushAffectHistory(snap) ; sparkline(vals) ; trendDelta(vals)"
+    signature: "renderConsole(snap) ; setFader(axis,v) ; setFaderTrend(axis) ; renderOrbit() ; renderDominant(snap) ; renderDerived(snap) ; renderRelations(snap) ; renderDirective(snap) ; pushAffectHistory(snap) ; sparkPointsH(vals,w,h,endX) ; padDeltas(vals) ; deltaStrip(deltas) ; orbitFrame(H,head,ts) ; orbitProj/orbitShadowY/orbitWallPt/orbitAxisPt ; startOrbitAnim() ; trendDelta(vals)"
     description: "ONE render path for BOTH the Tier-1 persona_state snapshot and the Tier-3 affect snapshot (renderConsole), feeding the right affect console: dominant/canonical-mood centerpiece, bipolar PAD faders (each with a turn-to-turn Δ + sparkline), a P×A mood orbit from PAD history, an affect-derived grid, relations metric rows, and the canonical directive. Replaces the v0.19.x split of renderPersonaPane (Tier-1 pane) + renderAffectPane (Tier-3 pane) + setPersonaStrip (top-bar strip, removed — PAD now lives in the console faders)."
     postconditions:
       - "POST-001: reads snap.relations (relation_edge/1: target_entity + trust_ability/benevolence/integrity + warmth as {value,confidence,evidence_count} + agency + relation_context) — the CURRENT Worldtree emit shape; falls back to the legacy flat snap.valence for an older emitter. Tier-1 fields (baseline_pad, mood_drift, dominant_emotion, emotions_active) render WHEN PRESENT, '—' when absent (Tier-3 lacks them)."
-      - "POST-002: each PAD fader + relation metric shows current value + Δ-vs-previous (▲/▼) + a unicode sparkline auto-scaled to its OWN observed range (flat ▄/— when sub-0.01 stable — no noise amplification), drawn from AFFECT_HIST (rolling, HIST_CAP=24, session-lived). setFaderTrend fills the per-meter Δ+spark slots; renderOrbit plots the last N (P,A) samples as a scaled trail with a pulsing current marker."
+      - "POST-002: SVG sparklines + affect visuals (v0.20.4, adapted from the design prototype; v0.20.7 = design iteration-3). Each relation metric shows a HORIZONTAL SVG sparkline (`sparkPointsH`, 56×13, auto-scaled to its OWN range, sparkFade gradient + end dot), now BACKED by a subtle grid (`<pattern id=sparkGrid>` + a bg `<rect>` behind the polyline). Each PAD fader shows current value + Δ-vs-previous (▲/▼) + a per-turn Δ STRIP: v0.20.7 REPLACES the vertical polyline strip (removed `stripPoints`) with a column of 12 diverging HTML bars (`padDeltas`→`deltaStrip`, newest at bottom, each bar offset L/R of a center line by that turn's Δ, magnitude→width, age→opacity, zero-Δ→faint center dot). renderOrbit is now a DIMETRIC OPEN BOX (azimuth 35° / elevation 25°, D→right / A→left-back / P→up; removed the isometric `proj3` for `orbitProj/orbitShadowY/orbitWallPt/orbitAxisPt`) — a ghost A×P wall (carrying the P readout) + a D×A floor, JS-DRIVEN animated replay (`orbitFrame` rebuilt per rAF frame by a singleton `startOrbitAnim` loop reading live `ORBIT_HIST`; no SMIL/CSS-keyframes; reduced-motion → static final-state render). All drawn from AFFECT_HIST (rolling, HIST_CAP=24, session-lived); coords are computed numerics (no upstream strings → INV-004 trivially held). Gradients/patterns live in one hidden `<defs>` svg in the console. v0.20.9 (R32-1B prep): the fader fill (`padFillFrac`) + orbit projections (`_padNorm`) AUTO-SCALE to the session's own max |PAD| (`padScale`, floor 1.0) instead of hard-clamping to [-1,1] — so an unbounded-z PAD (Worldtree R32-1B) renders at FULL range and never pegs/escapes the frame, while today's [-1,1] values are unchanged (scale==1); the exact value is always shown numerically (unclamped). This scaling is PURELY debug-display — ratatoskr is a downstream observer; it never touches the agent's real affect or any write path (the `--set-persona-pad` seed carries values unclamped)."
       - "POST-003: pushAffectHistory dedupes by emitted_at||last_updated_at so the ~4x/turn post-turn PAD poll contributes ONE sample/turn; history is CLIENT-side only (lost on reload — durable cross-session history via a provider-side snapshot log is a deferred follow-up, NOT built here)."
       - "POST-004: INV-001 honesty — no fabricated Tier-1 fields. The dominant-emotion centerpiece shows a real OCC dominant_emotion (Tier-1) OR the CANONICAL mood word from canonMood(pad) (Tier-3, dimmed) OR '—'; NEVER a synthesized emotion. The affect-derived grid drops non-emitted metrics (intensity/decay-τ) and shows only real/client-derived cells (baseline/drift real for Tier-1, client-derived samples/volatility). INV-004 — every dynamic value passes through esc(); numerics go through toFixed, never innerHTML-raw."
     flexibility: "open"
 
-  - name: "canonical affect-NL (v0.19.5 — vendored Worldtree d2 render canons)"
-    signature: "canonMood(pad) ; canonDirective(rel) ; loadPersonaCanon()"
-    description: "Render the LITERAL mood word + relationship directive Worldtree context-injects into the agent, byte-exact to Worldtree's own describe_pad + render_d2_canonical."
+  - name: "canonical affect-NL + context-injection reconstruction (v0.19.5 canons; v0.20.2 full context-injection panel)"
+    signature: "canonMood(pad) ; canonDirective(rel) ; canonPadFallback(pad) ; canonEmotionDirective(type) ; renderDirective(snap) ; loadPersonaCanon()"
+    description: "Reconstruct + render the HIDDEN affect-context block Worldtree assembles into the agent's system prompt (never on any wire) — byte-exact to Worldtree's own describe_pad + render_d2_canonical + derive_directive + _pad_band_fallback. The v0.20.2 'context injection' panel shows the full block: mood descriptor + mood directive + relationship directive. Reference: docs/vendor/worldtree-persona-canon/affect-egress-consumer-reference.md (pinned)."
     postconditions:
-      - "POST-001: DETERMINISTIC, no LLM. canonMood mirrors describe_pad (valence×arousal grid + strict ±0.3 bands + dominance clause); canonDirective mirrors render_d2_canonical (interval band-cut lookup + per-band phrase assembly + cross-axis low-trust-precedence behavior clause). BOTH VERIFIED BYTE-EXACT against Worldtree's own renderer run on the live snapshot (the reference harness re-runs Worldtree's functions + asserts string equality — reproducible)."
-      - "POST-002: the canon DATA is VENDORED (docs/vendor/worldtree-persona-canon/{d2-mood-render-canon-v1,d2-render-canon-v1}.json), pinned drift-gated in .corviduo-canonicals.toml (worldtree-persona-{mood,d2}-render-canon-v1); the flat browser form (static/persona_render_canon.json, served /static) is regenerated by scripts/build_persona_canon.py via Worldtree's OWN authoritative loader. Reference-impl posture: ADOPT the dep's canonical render, do NOT invent vocab — an invented 'faintly excited' would MISLEAD where the canonical (±0.3 bands) says 'neutral'."
-      - "POST-003: fail-open — canon absent (fetch fails) → the canonical lines OMIT, the structured pane still renders. The canon-derived strings are esc()'d before the DOM for INV-004 consistency."
+      - "POST-001: DETERMINISTIC, no LLM. canonMood mirrors describe_pad (valence×arousal grid + strict ±0.3 bands + dominance clause); canonDirective mirrors render_d2_canonical; canonPadFallback mirrors renderer._pad_band_fallback BYTE-EXACT (P×A quadrant: hi/lo/mid arousal band × p>0.3/<-0.3/neutral, with the negative_low_dominance (d<-0.3) special case + neutral_high_a + default); canonEmotionDirective is the occ_directives[type].directive lookup (+ tier / full_only flag)."
+      - "POST-002: the canon DATA is VENDORED (docs/vendor/worldtree-persona-canon/{d2-mood-render-canon-v1,d2-render-canon-v1}.json), pinned drift-gated in .corviduo-canonicals.toml; the flat browser form (static/persona_render_canon.json, served /static) is regenerated by scripts/build_persona_canon.py via Worldtree's OWN authoritative loader — v0.20.2 extended it to emit mood_directive {occ_directives, pad_band_fallback, salience, pad_band_cutoff, full_only}. The affect-egress consumer reference is pinned tolerate_drift (worldtree-affect-egress-consumer-reference-v1; worldtree-dev co-signs + pings on change)."
+      - "POST-003: fail-open — canon absent (fetch fails) → the reconstructed lines OMIT, the structured console still renders. Every canon-derived string is esc()'d before the DOM (INV-004)."
+      - "POST-004: HONEST-PARTIAL provenance (affect-egress-reference §3). The mood descriptor + relationship directive are EXACT (tagged 'exact'); the mood DIRECTIVE is a CANDIDATE pair (tagged 'candidate') — the OCC emotion directive for the delivered dominant_emotion type AND the PAD-band fallback — because affect.emit is type-only (no intensity) so the salience gate (≥0.2) can't be evaluated; BOTH are shown with the 'injected if intensity ≥ salience' caveat, never asserting which fires. When dominant_emotion is absent the fallback alone is EXACT. The panel is labeled reconstructed + hidden-from-consumers + dev-only (the reference-impl's sanctioned understand/reconstruct use, NOT end-user display per the reference's caveat). WATCH: a pending Worldtree render_d2_canonical change conditionally drops the trailing 'avoid premature we-framing' clause under a 3-gate combo — canonDirective holds as-is until worldtree-dev pings with the exact conditional + a canon bump."
+    flexibility: "open"
+
+  - name: "memory viewer (v0.20.7 — provider debug read → web proxy → console pane)"
+    signature: "server: _memory_chunks_endpoint(request) [GET /api/memory/chunks] ; provider: add_memory_read_route(app, store) [GET /memory/chunks] + RatatoskrMemoryStore.list_chunks(*, agent_id, end_user_id) + .count_chunks() ; index.html: loadMemory(agentId) ; renderMemory(data) ; setMemHead(count, total)"
+    description: "Durable memory chunks Worldtree promoted into OUR store, surfaced as a live-polling MEMORY console pane (content·scope·origin·revision per chunk). Mirrors the #18-D2 affect read pattern: a NON-bifrost debug read on OUR own store (bifrost's memory protocol has no list-all verb) → a web proxy supplying end_user_id server-side → the pane. Polled on session open + the post-turn window (promotion is async, like affect.emit)."
+    postconditions:
+      - "POST-001 (provider read): GET /memory/chunks?agent_id=&end_user_id= returns {chunks:[{chunk_id,content,scope,origin,revision}], count, total}. end_user_id REQUIRED (400 missing_end_user_id) — the partition boundary. Filter: end_user STRICT (scope.end_user==end_user_id), agent_id LENIENT (excluded only if the chunk CARRIES an agent_self axis that differs — so an {end_user}-only chunk, the real WT promotion shape, is not hidden). An empty match is a 200 empty list (0-chunks is a visible answer, never a 404). `total` = unfiltered store-wide count (distinguishes empty-store from scope-mismatch). content = best-effort text field / distillate summary / compact JSON-minus-embedding — a DEBUG read; bifrost verbs stay index/conduit-faithful."
+      - "POST-002 (web proxy): GET /api/memory/chunks supplies end_user_id from app.state.end_user_id (NEVER the browser), forwards the browser-named agent_id, proxies to app.state.memory_read_url (the combined :8392 provider serves both read routes). 400 memory_not_configured when unset; 502 memory_provider_unreachable on network error; status passthrough otherwise. Mirrors _affect_state_endpoint (#18 D2 INV-002)."
+      - "POST-003 (pane): renderMemory shows count(matched)/total(store-wide) in the head + one .mem-chunk per chunk (scope axes + origin + revision + content, ALL esc()'d — INV-004). Empty states are honest + diagnostic: total 0 → 'no memory chunks yet — promotion needs a bound memory/combined session + ~6 turns (or idle); if 0/0 the bind wasn't memory-granted or closed pre-promotion'; total>0 → 'scope mismatch, not an empty store'."
+    flexibility: "open"
+
+  - name: "markdownSafe pass-2 (v0.20.6 RP coloring + v0.20.7 tables / nested lists / streaming)"
+    signature: "markdownSafe(raw) ; mdTable(lines, i) ; mdInline(s)"
+    description: "The escape-first whitelist Markdown renderer, extended pass-2: GFM pipe tables, indentation-nested lists, ordered-list start numbering, and streaming-partial robustness. Pass-1 (RP speech/action coloring + CommonMark paragraph reflow) shipped v0.20.6."
+    postconditions:
+      - "POST-001: GFM pipe tables (`mdTable`) — a pipe row + an alignment/delimiter row (`|---|:--:|`) → <table class=md-table> with per-column text-align from the delimiter colons; body rows parsed until a non-pipe line."
+      - "POST-002: indentation-nested lists — leading-space depth builds a stack of <ul>/<ol> with each child list INSIDE the open parent <li> (valid nested HTML); same-level items are siblings; ul↔ol switches close+reopen. Ordered lists honor the first item's number (<ol start=N> when != 1)."
+      - "POST-003: streaming robustness — an unterminated code fence renders as a partial code block; a table header without its delimiter yet falls through to a paragraph (becomes a table once the delimiter streams in); parsing never throws on a partial. INV-004 held — esc() runs FIRST on the whole input, so table cells / list items / code all carry escaped content."
     flexibility: "open"
 
 invariants:
-  - "INV-004 (untrusted-render): ALL model / tool / admin / agent-supplied text is escaped before entering the DOM (esc via textContent, or esc(JSON.stringify)). No new render path introduces an innerHTML sink for upstream content. This is the highest-value review target — the new JS render paths are NOT unit-tested."
+  - "INV-004 (untrusted-render): ALL model / tool / admin / agent-supplied text is escaped before entering the DOM (esc via textContent, or esc(JSON.stringify)). No new render path introduces an innerHTML sink for upstream content. This is the highest-value review target — the new JS render paths are NOT unit-tested. v0.20.7: the memory pane (chunk content/scope/origin), the delta-strip bars, and markdownSafe table cells / list items all pass through esc() (esc runs FIRST on the whole markdown input)."
   - "INV-ADMIN-KEY: the admin key exists ONLY at app.state.admin_key (from RATATOSKR_ADMIN_API_KEY). It is never serialized into any response, never sent to the browser, never logged. The browser receives only the session-filtered RESULT of admin-scoped reads."
   - "INV-FILTER: AdminEvents filtering happens SERVER-side (_admin_event_matches_web) — the browser never receives the cross-session admin firehose; only active-session events + non-heartbeat system.* cross the wire."
   - "INV-FAIL-VISIBLE: both admin routes return 400 admin_key_not_configured when the key is absent — never a silent empty pane, never an upstream call with an empty bearer."

docs/contracts/worldtree_sdk_cutover.contract.md

@@ -0,0 +1,389 @@
+---
+contract_version: "2.1"
+module: "ratatoskr.wt"
+purpose: "SDK-adapter cutover — replace ratatoskr's hand-rolled httpx consumer wrappers (sessions/sse_client/tier3) with a thin adapter over worldtree-sdk (Python) 1.0.0, deleting the old wrappers; CLI/TUI/web surfaces and caller-semantic exceptions preserved."
+touches:
+  - src/ratatoskr/wt.py
+  - src/ratatoskr/cli.py
+  - src/ratatoskr/tui.py
+  - src/ratatoskr/web/server.py
+scope: "Cut ratatoskr's CONSUMER client layer over from its hand-rolled httpx wrappers (sessions.py / sse_client.py / tier3.py / first_message.py) to consume worldtree-sdk (Python) 1.0.0. Replace the wrappers with a thin ratatoskr-owned adapter over the SDK; delete the old wrappers; keep the CLI / TUI / Starlette web surfaces and ratatoskr's caller-semantic exception surface. The Bifrost PROVIDER planes (memory/affect — where Worldtree dispatches INTO ratatoskr, ADR-0009) are consumer-orthogonal and untouched. Cutover decided by operator ruling 2026-07-18; design locked via vor-cross with worldtree-codex (thread 01KXWCWV3VKNR0HP74D2RCY0DC)."
+depends_on:
+  - "worldtree-sdk (Python) == 1.0.0  # git tag python-v1.0.0; pin to the internal Gitea registry once published (DEC-5)"
+used_by:
+  - "ratatoskr.cli"
+  - "ratatoskr.tui"
+  - "ratatoskr.web"
+language: "python"
+complexity: "high"
+estimated_loc: 400  # net, rough — deletes (old wrappers) offset adds (adapter + call-site edits); sized per slice, not up front
+confidence: 0.8
+assumptions:
+  - "worldtree-sdk 1.0.0 is the GA Python consumer SDK ratatoskr's parity pass shaped; its resource surface (WorldtreeClient.sessions/agents/characters/me/capabilities/models/admin) covers all 21 of ratatoskr's covered routes. Verified against ~/development/worldtree-sdk @ python-v1.0.0."
+  - "Caller-injected transport is a first-class tested path (PY-INV-012): WorldtreeClient(base_url, auth=..., transport=my_httpx_async_client) uses ratatoskr's AsyncClient and NEVER closes it. Ratatoskr keeps base_url / bearer / User-Agent / timeout / web-app lifecycle ownership."
+  - "The SDK REST floor is an undiscriminated ApiError(error_code, message, status, body) (B-ERR-1/B-OPEN-3); hide-existence 404s are NOT distinguished by the SDK (B-ERR-4). Ratatoskr's caller-semantic mapping lives one layer up (DEC-2)."
+---
+
+# worldtree-sdk cutover — consumer-layer adapter contract
+
+Single SDK-adapter contract per operator DEC-1. This is a migration contract: its
+spine is a route-family slice plan, not a dense FN-block spec — each slice's
+adapter FN detail is filled in at that slice's TDD (incremental migration; the
+per-route SDK signatures are already mapped below).
+
+## Locked design (operator-accepted 2026-07-18, post vor-cross)
+
+- **DEC-1 — retire, don't repurpose (two-phase).** Normative authority for the
+  consumer wire transfers to THIS contract immediately (as of this file, #2 sessions
+  and #15 tier3 are superseded — no longer the spec of record); the contract FILES
+  are DELETED at slice-7 teardown, only after the code they specified is gone
+  (avoids both orphaning live code and leaving obsolete norms active mid-migration).
+  `first_message` is NOT retired — it stays a ratatoskr-owned usage contract at the
+  spec level (its preset / best-effort-timeout / swallow policy is local, not
+  SDK-owned). Repurposing the wire contracts would risk a shadow-normative copy of
+  SDK-owned semantics — the exact thing the cutover eliminates.
+- **DEC-2 — thin semantic error adapter.** CLI/web/TUI keep ratatoskr's typed
+  exceptions; the adapter maps the SDK's `ApiError` floor → ratatoskr's
+  caller-semantic types (the SDK stays undiscriminated; hide-existence maps here).
+- **DEC-3 — no shims (house rule).** Delete the old wrapper modules and update all
+  call-sites to the new adapter. No compatibility facade preserving old
+  module/function APIs (pre-1.0 no-backwards-compat rule).
+- **DEC-4 — incremental + live-smoke, no soak.** Migrate one route-family per
+  slice, TDD each slice, and run a targeted LIVE smoke of that family against the
+  personal endpoint before deleting the replaced hand-rolled path. (The SDK's
+  fixture corpus proves the WIRE; the live smoke proves ratatoskr's
+  presenter/adapter/env-wiring survived the dependency inversion.)
+  **Smoke acceptance bar (the minimum that lets an old path be deleted):** drive
+  each route in the family's primary flow END-TO-END through the ratatoskr surface
+  (CLI/web) — not the wrapper directly — against the personal endpoint under the
+  real consumer key, and OBSERVE the expected success (a created session, a streamed
+  turn that renders, a persona write that reads back), not merely a non-crash. A
+  smoke that only asserts "no exception" does NOT clear the bar. **Smoke vs. soak
+  boundary:** a smoke is a single pass of the family's flows at deletion time; a
+  (forbidden) soak is a sustained dual-path parallel-run — do the former, not the
+  latter.
+- **DEC-5 — wait for the registry.** Pin `worldtree-sdk == 1.0.0` from the internal
+  Gitea registry once published (verify the uv install first); use the
+  `python-v1.0.0` git tag only if the registry lags. Contract-drafting is NOT
+  gated (SDK source is inspectable); IMPLEMENTATION pin is.
+- **DEC-6 — minor bump at ship.** The cutover ships as a minor (architecture-cutover
+  milestone; pre-1.0 breaking-internal) — requires explicit operator approval at
+  ship time, not now.
+
+## Adapter design
+
+- **`ratatoskr.wt`** — a thin adapter module owning ONE `WorldtreeClient`, built
+  with ratatoskr's own `httpx.AsyncClient` injected (`transport=`), ratatoskr's
+  `auth`/`admin_auth` providers, and the ratatoskr User-Agent. It exposes
+  ratatoskr-semantic call surfaces the presenters already expect, and translates
+  SDK errors → ratatoskr exceptions (DEC-2).
+- **Transport ownership (INV-CUT-1 [hard]):** the injected `AsyncClient` is
+  ratatoskr-owned; `WorldtreeClient.aclose()` / `async with` exit must NOT close
+  it (SDK `_owns_client=False` on injection). Ratatoskr owns the client lifecycle
+  exactly as today.
+- **Error boundary (INV-CUT-2 [hard]):** ratatoskr's caller-semantic exceptions
+  are raised by the adapter, mapping from the SDK where the SDK already
+  discriminates (`AgentNotAvailable`, `TurnLaunchUnavailable`, `SessionRetired`,
+  `Cancel*`, `Resume*`, `Malformed*`) and from `ApiError(status=..., error_code)`
+  on a KNOWN route otherwise — including the hide-existence 404 →
+  `AuthoredHistoryUnavailable` (labeling a call we made, NOT capability-probing).
+- **Provider boundary (INV-CUT-3 [hard]):** the Bifrost provider planes stay
+  hand-rolled and are never routed through the SDK. The Bifrost-BOUND
+  `sessions.create` (consumer-side, `bifrost=` + consumer-key auth) DOES go through
+  the SDK and stays consumer-layer.
+- **Import boundary (INV-CUT-4 [hard]):** `tests/test_no_worldtree_imports.py`
+  stays; the boundary becomes "no Worldtree SOURCE imports", with `worldtree_sdk`
+  the allowed client dependency.
+
+## Invariants
+
+- **INV-CUT-1 [hard]** — Ratatoskr owns the injected `httpx.AsyncClient` lifecycle;
+  the SDK never closes it (`_owns_client=False` on transport injection).
+- **INV-CUT-2 [hard]** — The adapter raises ratatoskr's caller-semantic exceptions
+  per the explicit **§ Error map** table below — mapping from the SDK's discriminated
+  errors (passthrough) and from `ApiError` by the ROUTE that raised it (the route is
+  the discriminator, never the body). Every `ApiError` is mapped; the default is
+  `SessionApiFailed`. No route invents semantics the table doesn't list.
+- **INV-CUT-3 [hard]** — The Bifrost PROVIDER planes never route through the SDK;
+  the Bifrost-BOUND `sessions.create` does (consumer-side).
+- **INV-CUT-4 [hard]** — The no-Worldtree-SOURCE-import boundary holds
+  (`worldtree_sdk` allowed); `tests/test_no_worldtree_imports.py` enforces it.
+- **INV-CUT-5 [hard]** — Each slice runs a LIVE smoke of its route family before the
+  replaced hand-rolled path is deleted (DEC-4); no old path is removed unproven.
+
+## Route map — ratatoskr wrapper → SDK method (grounded @ python-v1.0.0)
+
+| Ratatoskr wrapper (retiring) | SDK method | SDK return |
+|---|---|---|
+| `create_session` | `sessions.create(...)` | `SessionInfo` |
+| `list_sessions` | `sessions.list(limit, cursor)` | page |
+| `stream_turn` | `sessions.stream_turn(...)` (resilient) / `stream_turn_raw` (single) | `AsyncIterator[Event]` |
+| `reconnect_turn` | folded into `sessions.stream_turn` auto-resume | — |
+| `cancel_turn` | `sessions.cancel_turn(...)` | `CancelResult` |
+| `get_session_messages` | `sessions.messages(id)` | open-world |
+| `get_session_tools` | `sessions.tools(id)` | `SessionTools` |
+| `set_persona_state` | `sessions.set_persona_state(id, PadState)` | None |
+| `write_authored_history` | `sessions.write_history(...)` | authored-turn |
+| `get_persona_state` | `agents.persona_state(agent_id)` | `AgentPersonaState` |
+| `list_agents` | `agents.list()` | `AgentList` |
+| `define_agent` | `agents.define(...)` | `DefinedAgent` |
+| `patch_agent` | `agents.patch(id, changes)` | `PatchedAgent` |
+| `delete_agent` | `agents.delete(id)` | None |
+| `get_me` | `me.get()` | `MeInfo` |
+| `get_capabilities` | `capabilities.get()` | `Capabilities` |
+| `list_character_models` | `models.available_for_characters()` | `ModelsAvailable` |
+| `create_character` | `characters.create(...)` | `CreatedCharacter` |
+| `get_character_state` | `characters.state(id)` | `CharacterState` |
+| `delete_character` | `characters.delete(id)` | `CharacterDeleteResult` |
+| `get_session_bifrost` | `admin.sessions.bifrost(id)` | `BifrostInspection` |
+| `stream_admin_events` | `admin.stream_events(...)` | `AsyncIterator[AdminEvent]` |
+
+Note: SDK returns are typed `shapes.*`; per the parity pass the freeform reads
+(`SessionTools`, `BifrostInspection`, capabilities) are deliberately open-world in
+the Python spine. The adapter PASSES THESE THROUGH unmodified (does not normalize);
+presenters read them as mappings, tolerant of wire drift. If an open-world read is
+malformed the presenter degrades (never crashes) — same posture as the existing
+`_format_whoami` hardening.
+
+## Error map (INV-CUT-2 — the explicit table)
+
+**The ROUTE is the discriminator, not the error body** (labeling a call we made, NOT
+capability-probing — B-ERR-4). A 404 is mapped by which method raised it; the adapter
+NEVER sniffs the body to decide whether something exists. Authored-history is
+currently the ONLY hide-existence route (per Worldtree B-ERR-4); if Worldtree adds
+others, they get their own row here — the default is NOT a general "any 404 → hidden".
+
+| SDK raises (from) | Adapter maps to |
+|---|---|
+| SDK `AgentNotAvailable` / `TurnLaunchUnavailable` / `SessionRetired` (stream-open) | ratatoskr `AgentNotAvailable` / `TurnLaunchUnavailable` / (retired → `SessionApiFailed`) — same names, passthrough |
+| SDK `ConnectionDropped` (mid-stream) | `SseConnectionDropped` |
+| SDK `ResumeError` subclasses (in resilient stream) | resilient `stream_turn` absorbs; terminal → `SseConnectFailed` |
+| SDK `MalformedSseId` / `MalformedSseData` / `TurnIdFlip` (stream `ProtocolError`) | ratatoskr same-named types — same-name rewrap of the discriminated stream protocol errors |
+| SDK `Cancel*` (cancel_turn) — the SDK RAISES the typed races | 404 `turn_not_found` → `CancelTurnNotFound`; 409 `turn_finished` → `CancelAlreadyCompleted`; other `CancelError` → `CancelFailed`. A 200 (incl. `cancelled=False`, the B-CAN-3 late-cancel no-op) returns a `CancelResult` — never raises. The caller surface stays exception-based (DEC-2; matches the pre-cutover CLI/web handlers). |
+| `ApiError(404)` on `sessions.create` | `AgentNotFound` |
+| `ApiError(404)` on `sessions.write_history` | `AuthoredHistoryUnavailable` (hide-existence) |
+| `ApiError(422 cursor_invalid)` on `sessions.list` | `InvalidCursor` (dual-key: status 422 AND error_code; the flat cursor body surfaces the code) |
+| `ApiError(502)` on bound `sessions.create` | `BifrostHandshakeFailed` — NOT gated on error_code (unlike list's 422): INV-002, the synchronous handshake is the SOLE bound-502 cause; and the SDK's envelope parser prefers the nested `detail` (which carries `bifrost_error`, not `error_code`), so no distinguishing top-level `error_code` surfaces. The route+status IS the discriminator. |
+| `ApiError(429)` on `agents.define` (slice-4) | `Tier3QuotaExceeded(retry_after=0)` — the SDK's `ApiError` floor carries no response headers, so the `Retry-After` header the hand-rolled path read is unavailable; spec §2675 pins Phase-2.0 quota to `Retry-After: 0`, so the adapter defaults to 0. A non-zero forward-compat value is unrecoverable until the SDK surfaces headers (INFORM wtsdk-dev; reference-impl posture). |
+| `ApiError(403 tier3_user_id_unsupported)` on `agents.define` (slice-4) | `Tier3UserIdUnsupported` (dual-key: status 403 AND error_code) |
+| `ApiError(422 layer_deferred)` on `agents.define` (slice-4) | `Tier3LayerDeferred(field)` — `field` parsed from the body (`detail.field` / flat `field`); the SDK carries `error_code` but not `field`, so the adapter body-parses it (same posture as bound-502's `bifrost_error`) |
+| `ApiError(404)` on `agents.patch` / `agents.delete` (slice-4) | `Tier3AgentNotFound` (route-discriminated; agents CRUD is NOT a hide-existence route — a 404 there IS "no such agent") |
+| `ApiError(422 field_not_mutable)` on `agents.patch` (slice-4) | `Tier3FieldNotMutable(field)` (dual-key status+error_code; `field` body-parsed) |
+| `ApiError(404 persona_not_configured)` on `agents.persona_state` (slice-4) | `PersonaNotConfigured` (dual-key) |
+| `ApiError(404 agent_not_available)` on `agents.persona_state` (slice-4) | `AgentNotAvailable` (the persona-surface `sessions.AgentNotAvailable`, distinct from the eager-turn `sse_client.AgentNotAvailable`; dual-key) |
+| `ApiError(403 auth_scope_denied)` on `agents.persona_state` (slice-4) | `AuthScopeDenied(scope="persona.read")` (dual-key) |
+| **`ApiError` (any other status/route, incl. `agents.list` and any unmatched agent-route code) — the default** | `SessionApiFailed(status, error_code, body)` |
+
+The default row is load-bearing: any `ApiError` not matched above surfaces as the
+generic `SessionApiFailed` carrying the raw `status`/`error_code`/`body` — the
+adapter does NOT invent per-route semantics the contract doesn't list, and does NOT
+leave an `ApiError` un-mapped. **This default holds on EVERY route, including the
+stream and cancel** (each carries a defensive `except ApiError → SessionApiFailed`
+after its discriminated branches — the SDK maps those routes to discriminated types
+today, but the default guarantees INV-CUT-2 structurally, not by SDK-internal
+coupling). Each slice adds/confirms its route's rows here before the old path is
+deleted.
+
+## Slice plan (incremental, DEC-4)
+
+Each slice: wire the family through `ratatoskr.wt` → update call-sites → TDD →
+LIVE smoke against the personal endpoint → delete the replaced hand-rolled path →
+re-anchor its coverage-map rows.
+
+1. **Foundation** — `ratatoskr.wt` module + injected `WorldtreeClient` + auth
+   providers + the error-adapter skeleton (the § Error map's default `ApiError` →
+   `SessionApiFailed` rule + the discriminated-error passthrough). No USER-VISIBLE
+   behavior change (imports/construction change; the skeleton is unit-tested but
+   unexercised by any surface until slice 2). Done = `ratatoskr.wt` importable, the
+   client constructs with an injected transport, and the error-map default is unit-
+   covered.
+2. **Sessions/turn** — create/list/messages/tools/cancel + the turn STREAM + the
+   Bifrost-bound create. The turn presenter wires the resilient `sessions.stream_turn`
+   (auto-resume — this ABSORBS the old `reconnect_turn`, which is deleted this slice
+   with its call-sites); `stream_turn_raw` is available for a single-attempt caller
+   but is NOT the presenter default. (Highest-traffic; the SSE presenter is the
+   riskiest wiring.)
+3. **Persona + authored-history** — set_persona_state (PadState) + write_history
+   (hide-existence mapping) + first_message presets (stay ratatoskr-owned OVER the
+   SDK method).
+4. **Agents (Tier-3)** — list/get/define/patch/delete/persona_state. (Folds in the
+   pending `model`→`role` cutover — see [[project-tier3-agents-model-to-role-pending]].)
+5. **Characters + me/capabilities/models** — the remaining consumer reads.
+6. **Admin** — admin.sessions.bifrost + admin.stream_events (admin_auth).
+7. **Teardown** — delete residual hand-rolled modules; drop `httpx-sse` (SDK owns
+   SSE parsing); retire contracts #2/#15; final coverage-map re-anchor; minor bump
+   (DEC-6, operator approval).
+
+### Slice-4 notes (Agents/Tier-3 + `model`→`role` fold, decided at TDD)
+
+- **`model`→`role` cutover folds in here (scope B).** Worldtree spec 1.2 (`v1.0.0b128`,
+  live on :8080/:8081) made the `/agents/define` response echo `role`, closing the
+  old W-4 `model` echo. The adapter returns the SDK's OPEN-WORLD `DefinedAgent` /
+  `PatchedAgent` dicts verbatim (parity posture); callers read `info["role"]`. The
+  frozen `Tier3AgentInfo` dataclass (which read `body["model"]` and would KeyError
+  post-b128) is DELETED — no dataclass normalization layer survives.
+- **`ratatoskr.local_agents` schema bump.** `LocalAgentEntry.model` → `.role` (the
+  field stores what the wire now calls a role); `_SCHEMA_VERSION` 1→2 so any
+  pre-cutover on-disk index is discarded cleanly (no-backwards-compat, DEC-3).
+- **`AgentNotAvailable` name collision.** `sessions.AgentNotAvailable` (persona-state
+  404 `agent_not_available`) and `sse_client.AgentNotAvailable` (eager-turn 409) are
+  distinct types that share a name; `wt` already imports the sse_client one for the
+  stream, so it imports the persona one ALIASED (`PersonaAgentNotAvailable`) and
+  raises it from `get_persona_state`. The web endpoint keeps importing the persona
+  `AgentNotAvailable` from `sessions` (same class), so its `except` is unchanged.
+- **`ConnectFailed` at every rewired caller (slice-3 foot-gun).** The SDK normalizes
+  ANY transport failure to `ConnectFailed(status=0)` (`request.py`), not a raw httpx
+  error. The rewired tier3 CLI and both web endpoints (`_agents_endpoint`,
+  `_persona_state_endpoint`) catch `wtsdk.ConnectFailed` → their existing
+  network-error surface (CLI exit 21 / web 502). The web `test_network_error_returns_502`
+  (respx `httpx.ConnectError` side-effect) is the RED that proves this.
+- **`agents.get(agent_id)`** (SDK `GET /agents/{id}`) is NOT wrapped — ratatoskr has no
+  `get_agent` consumer; only list/persona_state/define/patch/delete are in coverage.
+- **Client-side Tier-3-id PRE on `patch_agent` / `delete_agent`.** Both assert
+  `":" in agent_id` pre-HTTP (a Tier-3 id is always `<user_id>:<agent_name>`, ADR-0019),
+  so a non-colon id fails fast with an `AssertionError` rather than reaching the SDK's
+  route-discriminated 404 → `Tier3AgentNotFound`. Intentional fail-fast on a
+  wrong-shaped id (carried over from the retired hand-rolled wrappers); documented here
+  per the heid-code-review slice-4 precision flag (the § Error map 404 rows assume a
+  well-formed Tier-3 id reaches the route).
+
+### Slice-5 notes (Characters + me/capabilities/models, decided at TDD)
+
+- **No new § Error map rows.** All six routes (`me.get`, `capabilities.get`,
+  `models.available_for_characters`, `characters.create` / `.state` / `.delete`) are
+  open-world reads/acks (B-OPEN-2) whose SDK ops carry NO discriminated error (no
+  `map_error`), so every `ApiError` maps to the default `SessionApiFailed` — exact
+  parity with the retiring hand-rolled path, which likewise raised only its generic
+  `SessionApiFailed` on any non-2xx (never discriminating a status/code on these
+  routes). The route-map table above already lists all six.
+- **`create_character` body — omit `state` when None.** The adapter sends
+  `{"character": …}` plus `"state"` only when the caller supplies a non-None state
+  (the SDK forwards the body dict as-is via httpx `json=`). This drops the hand-rolled
+  path's redundant explicit `"state": null` — server-equivalent (Worldtree's
+  `CreateCharacterRequest.state` defaults None whether omitted or explicit-null),
+  SDK-idiomatic (matches the SDK's `CreateCharacterInput` `NotRequired` shape), and
+  invisible at the sole call-site (`--characters` never passes a state). Adopt-
+  canonical over byte-for-byte wire parity.
+- **`delete_character` returns the SDK's open ack verbatim (`-> Mapping | None`).**
+  The SDK route returns an open-world ack body (not 204 — `CharacterDeleteResult`), so
+  the adapter passes it through rather than normalizing to the hand-rolled `None`
+  (parity posture: no None-normalization of an open-world read). On a 204 no-content
+  the SDK yields `None`, so the return type is `Mapping | None`; the sole call-site
+  (`--characters`) ignores the value, so the change is unobservable.
+- **Open-world presenter degrade-not-crash (cumulative foot-gun).** `_format_whoami`
+  is already hardened (slice-4 heid bug-hunt). The rewired `_characters_probe` extracts
+  the created id defensively (`created.get("character_id")` + type-guard → clean abort,
+  never a hard-index KeyError) since the create ACK is now an open-world SDK read.
+- **Container-type hardening (heid code-review + bug-hunt slice-5).** The degrade-not-
+  crash floor is guarded at THREE levels for the CLI presenters, not just one: (a) the
+  list-typed fields `scopes` / `allowed_roles` / model `items` degrade a non-list scalar
+  (`123`) or a bare string to empty via `_display_seq` / an `isinstance(_, list)` guard —
+  the older `or []` idiom only caught null/absent and would `for x in 123` `TypeError`;
+  (b) each element is type-guarded (`isinstance(m, dict)`); (c) the top-level open-world
+  reads `created` / `models` / `state` are `isinstance(_, Mapping)`-guarded before any
+  `.get` (a non-mapping passthrough would otherwise `AttributeError`). All three feed
+  `--whoami` / `--characters` only.
+- **Accepted (not fixed): the `--characters` probe leaks its transient character on a
+  mid-lifecycle failure.** create → get-state → delete runs linearly with no `finally`,
+  so a state/delete failure after a successful create orphans the probe character until
+  its TTL. This is PRE-EXISTING (the retired hand-rolled probe had the identical
+  structure — the cutover did not worsen it), TTL-bounded, and `--characters` is a
+  one-shot diagnostic smoke; a `try/finally` cleanup would also swallow a happy-path
+  delete-failure (delete is both the teardown AND a tested lifecycle step). Accepted as
+  known-risk per the heid bug-hunt (Gróa + Heid concur accept is defensible).
+- **CLI-only rewire.** `me` / `capabilities` / `characters` / `models` have NO
+  web-server caller — only the `--whoami` and `--characters` CLI one-shot probes. The
+  web surface is untouched this slice.
+
+### Slice-6 notes (Admin: bifrost inspection + admin-events stream, decided at TDD)
+
+- **Admin auth moves from a per-call header override to the client's `admin_auth`.**
+  The SDK's `admin.*` methods authenticate with the client's `admin_auth` provider
+  (set via `build_client(admin_key=...)`), NOT a per-request `Authorization` header. So
+  the two web admin endpoints build their wt client WITH `admin_key` (`_wt_client(client,
+  admin_key=...)`, extended this slice); the hand-rolled per-call `admin_key=` +
+  header-override is retired. The web already guards `if not admin_key: 400` before the
+  call, so the SDK's pre-HTTP `ConfigurationError` (missing admin_auth, W-5) is
+  unreachable from the web surface. **CLI has no admin caller** — both routes are
+  web-only (the coverage-map's `tui.py` rows were stale; corrected to `web/server.py`).
+- **`get_session_bifrost` — no new § Error map row.** `client.admin.sessions.bifrost`
+  returns the open-world `BifrostInspection` dict verbatim; any `ApiError` (notably 403
+  `auth_scope_denied`, 404 `session_not_bifrost_bound`) → the `SessionApiFailed` default
+  — exact parity with the retired path (which mapped every non-200 → `SessionApiFailed`).
+- **`stream_admin_events` re-wraps the SDK's `AdminEvent` → ratatoskr's `AdminEvent`
+  (chosen over yield-through).** The SDK's `AdminEvent` diverges from ratatoskr's:
+  `admin_id: int|float` (`nan` for an id-less envelope) vs ratatoskr's `id: int` (0
+  default), and the SDK's `type`/`data` are None-able where ratatoskr's are a dotted-str
+  / a `{}`-default dict. The web filter + SSE formatter read `ev.id`/`ev.type`/`ev.data`.
+  The adapter re-wraps at the boundary — `id = admin_id if int else 0` (nan→0),
+  `type = type or ""` (None→"" so `.startswith` never crashes), `data = data or {}` —
+  degrading the SDK's open-world None/nan ONCE at the adapter, keeping the web endpoint +
+  `_admin_event_matches_web` + the ratatoskr `AdminEvent` domain type UNCHANGED (preserves
+  the web surface per § Out of scope). **Rejected alternative:** yield SDK `AdminEvent`s
+  through and rewire the web filter for `admin_id`/None/nan (the slice-2 turn-stream
+  precedent) — heavier web churn + scatters the None/nan hardening through the filter;
+  re-wrap localizes it. The ratatoskr `AdminEvent` dataclass stays in `sse_client.py` this
+  slice (imported by `wt` + the web); its home moves in slice-7 teardown if `sse_client.py`
+  is retired.
+- **Admin-stream error mapping (reuses the § Error map stream rows).** The SDK admin
+  stream raises `ApiError("admin_stream_failed", status=…)` on a NON-200 open (NOT
+  `ConnectFailed` — a gotcha the web integration test caught that the unit fake could not)
+  → `SseConnectFailed`; and `ConnectionDropped` on a connect-time transport failure
+  (cursor None) OR a mid-stream drop / the long-lived stream's resumable EOF (cursor set)
+  → `SseConnectionDropped`. The SDK admin stream is best-effort (skips malformed frames —
+  no `Malformed*`), as was the retired hand-rolled path; the web endpoint's existing
+  `except (…, MalformedSseId, MalformedSseData)` stays a harmless defensive superset
+  (pre-existing, not introduced here).
+
+### Slice-7 notes (Teardown — the LAST slice, decided at teardown)
+
+- **Module boundary: KEEP `sessions.py` + `sse_client.py` as pure type/exception
+  homes (operator decision A1, 2026-07-19).** Post-cutover both modules hold NO
+  client — only ratatoskr's caller-semantic exception surface + a couple of
+  dataclasses (`BifrostBinding`; `SseId`, `AdminEvent`) + the `endpoint_for_plane`
+  provider helper. Options weighed: (A1) keep as-is + fix docstrings; (A2) rename to
+  honest names (`session_errors`/`stream_errors`), re-point ~7 importers; (A3)
+  consolidate into one `errors.py` / fold into `wt.py`. **A1 chosen** — teardown is
+  deletion + dep-drop, not a rename refactor; A3 is blocked by the `AgentNotAvailable`
+  name collision (two distinct classes: persona-404 in `sessions` vs eager-turn-409 in
+  `sse_client`) which would force renaming a contract-level caller-semantic type + its
+  § Error-map rows + catch sites, and folding into `wt.py` mis-homes
+  `endpoint_for_plane` (provider-side). Naming-honesty (principle-2) addressed by the
+  one-line docstring note, not a rename. **Resolves the slice-6 open item** (line ~326):
+  the ratatoskr `AdminEvent`/`SseId` + exceptions stay in `sse_client.py`; the
+  session/tier3 exceptions + `BifrostBinding` stay in `sessions.py`.
+- **`httpx-sse` dropped from `pyproject.toml` + lockfile.** Slice-6 deleted its last
+  user (`sse_client.stream_admin_events`); a tree grep confirmed nothing imports
+  `httpx_sse`. `uv sync` physically pruned it; suite green (494) with the module absent.
+- **Wire contracts #2 (sessions) + #15 (tier3) retired (files DELETED, DEC-1
+  phase-2).** Their normative authority transferred to this contract at authoring;
+  the code they specified is gone, so the files are removed now. **#1 (SSE event
+  vocabulary) is NOT retired** — it stays current (amended `4bd9abd` 2026-07-18) as
+  ratatoskr's SSE-event-rendering reference; **`first_message` is NOT retired** (DEC-1,
+  ratatoskr-owned usage contract). Accepted side-effect: `issues/5.contract.md`'s
+  historical "amended #2/#3/#4 in-place" line now points at a deleted #2 — left as-is
+  (frozen issue-record of a past action; not expanding DEC-1's #2/#15 scope).
+- **Final coverage-map re-anchor.** `GET /sessions/{id}/tools` → `wt.py get_session_tools`
+  (SDK `sessions.tools`) → `web/server.py` (the old `sessions.py`→`tui.py` row was
+  stale; TUI deleted). `GET /sessions` `list_sessions` re-homed to `wt.py`, still
+  caller-less (picker was a TUI frontier, now moot). The `Last-Event-ID` SSE-resume
+  sub-gap is CLOSED — `reconnect_turn` deleted, resume folded into `wt.py stream_turn`
+  auto-resume. Surface-2 SSE parsing re-anchored to the SDK (`_envelope_for_type` gone).
+- **Ships as v0.22.0 (minor, DEC-6, operator-approved 2026-07-19).** Publishes the
+  full 6-slice consumer-layer cutover milestone.
+
+## Out of scope
+
+- Bifrost PROVIDER planes (memory/affect) — hand-rolled, ADR-0009, untouched.
+- CLI / TUI / Starlette web surfaces — their EXTERNAL BEHAVIOR is preserved (their
+  call-sites DO change — they're updated to the new adapter per `touches:`; what's
+  invariant is the observable behavior, not the code).
+- The four parked post-v1 SDK ergonomics items (replayed:bool, raw-dict persona
+  escape hatch, list_all iterator, split session types) — coordinated post-v1 lane
+  with wtsdk-dev, not this cutover.
+
+## Coverage-map re-anchor
+
+`docs/coverage-map.md` shifts from "hand-rolled route exists + live-proven" to
+"SDK method wired and exercised by a ratatoskr surface"; excluded-by-design rows
+stay explicit. Re-anchored per slice as each family lands.

docs/conversation-api-openapi.json

@@ -950,7 +950,7 @@
   "info": {
     "description": "Multi-turn conversation interface for Worldtree agents.",
     "title": "Worldtree Conversation API",
-    "version": "2.3.0"
+    "version": "2.4.0"
   },
   "openapi": "3.1.0",
   "paths": {

docs/conversation-api-spec.md

@@ -1,8 +1,8 @@
 # Worldtree Conversation API — Client Interface Specification
 
-**Version:** 1.0
-**Date:** 2026-04-15
-**Status:** Stable (pre-auth)
+**Version:** 1.3
+**Date:** 2026-07-18
+**Status:** Stable
 **Contract:** `docs/contracts/conversation_api.contract.md`
 
 This document specifies the external interface for clients integrating with the Worldtree Conversation API. It is the reference for building web apps, TUI clients, bridges, or any system that needs to converse with Worldtree agents.
@@ -1209,7 +1209,19 @@ Send a message and receive the agent's response as a Server-Sent Events (SSE) st
 
 The stream emits JSON-encoded events. Each SSE `data:` line contains a JSON object with a `type` field.
 
-**Errors:** `404` if session not found (returned before stream starts).
+**Content size (normative, spec 2.4.0):** `content` is bounded on **UTF-8
+byte length** by `message_content_max_bytes` (server config; **default
+262144 = 256 KiB — the normative spec number**). Over-cap content is
+rejected with an eager `422` carrying `error_code: content_too_long`
+*before* any SSE bytes are emitted (plain JSON error envelope, the
+pre-stream error path). Content that is not valid UTF-8 (lone surrogates)
+is a deterministic `422 validation_failed`. This cap is the number
+client-side read bounds derive from: a max-page transcript body is
+structurally ≤ 200 items × (cap + envelope overhead), and no single
+message-bearing SSE frame can exceed cap + envelope overhead.
+
+**Errors:** `404` if session not found (returned before stream starts);
+`422 content_too_long` for over-cap content (see above).
 
 ---
 
@@ -1533,7 +1545,7 @@ for (const tc of items) {
 
 ## Ephemeral Templates (issue #161)
 
-Ephemeral templates are a second tier of agent, distinct from foundational persistent agents (Mimir, Soong, etc.). They have no persona, no memory, no tools, and no motivational context. The consumer supplies the system prompt and (optionally) the model at session-create time; that config is frozen for the session's lifetime.
+Ephemeral templates are a second tier of agent, distinct from foundational persistent agents (Mimir, Lofn, etc.). They have no persona, no memory, no tools, and no motivational context. The consumer supplies the system prompt and (optionally) a **role** — a purpose-named model role per ADR-0012, not a raw model id — at session-create time; that config is frozen for the session's lifetime. (The raw `model` selector was retired at the model-role cutover, 2026-06-09.)
 
 **Echo** is the first ephemeral template — a blank-slate per-session host that becomes whatever the consumer's system prompt instills.
 
@@ -1548,8 +1560,8 @@ Authorization: Bearer <any valid key>
 {
   "ephemeral_templates": {
     "echo": {
-      "allowed_models": ["glm5-turbo", "glm4.7", "glm4.5-air", "granite-structured", "qwen3.6-35-a3b"],
-      "default_model": "glm5-turbo",
+      "allowed_roles": ["echo"],
+      "default_role": "echo",
       "system_prompt_max_bytes": 32768
     }
   }
@@ -1566,7 +1578,7 @@ POST /sessions
   "agent_id": "echo",
   "config": {
     "system_prompt": "You are a careful, skeptical frame-clarifier...",
-    "model": "glm5-turbo"
+    "role": "echo"
   }
 }
 ```
@@ -1580,9 +1592,10 @@ POST /sessions
 | `system_prompt_required` | `config.system_prompt` missing or null |
 | `system_prompt_empty` | `config.system_prompt` is whitespace-only |
 | `system_prompt_too_large` | `config.system_prompt` > 32768 bytes UTF-8 |
-| `model_not_allowed` | `config.model` present but not in `echo_allowed_models` |
+| `model_not_allowed` | `config.model` present and non-empty — the raw-model selector is retired; select via `config.role` |
+| `role_required` | `config.role` present but empty or not a string |
 
-**`config.model` resolution:** When `config.model` is omitted (or `null`), the server resolves it to `echo.default_model` from `config/defaults.yaml`. The resolved value is always populated in the session snapshot; `model` is never left absent or null in the stored config.
+**`config.role` resolution:** When `config.role` is omitted (or `null`), the server resolves it to `default_role` (`"echo"`). The resolved value is always populated in the session snapshot; `role` is never left absent or null in the stored config. Role→model mapping happens server-side at turn time per ADR-0012 (`config/model_roles.yaml`); create-time validation does not enumerate models.
 
 **Response:** Same 201 shape as foundational sessions, with two new fields:
 
@@ -1593,7 +1606,7 @@ POST /sessions
   "kind": "ephemeral",
   "config": {
     "system_prompt": "You are a careful, skeptical frame-clarifier...",
-    "model": "glm5-turbo"
+    "role": "echo"
   },
   "message_count": 0,
   "created_at": "...",
@@ -1612,7 +1625,7 @@ POST /sessions/{id}/messages
 SSE, cancel, `persist_partial`, rate limits, and error shapes are bit-identical to foundational sessions. The only differences are pre-turn:
 
 - **System prompt:** `session.config.system_prompt` verbatim — not extended with registry text, persona, or motivational context.
-- **Provider:** resolved by `session.config.model`.
+- **Provider:** resolved from `session.config.role` (role→model per ADR-0012).
 - **Tools:** empty `[]` — no tools loaded, no tool schemas declared.
 
 ### Scope
@@ -1633,7 +1646,7 @@ Creating an Echo session requires the `instantiate:echo` scope. This scope is bu
 
 Public primitive for downstream consumers (Skaldsong, RPG/game engines, dialog tools) that need to spin up dozens of distinct OCEAN-driven personas per session. Worldtree owns no durable state — the consumer ships character JSON, gets a `character_id`, and runs sessions against it. Persists in-memory only; process restart drops everything.
 
-The character displaces the **persona + model** layer of the bound session. The `agent_id` (typically `actor`) still resolves system prompt, tools, and the LLM provider unless the character carries a `model` override.
+The character displaces the **persona + model-role** layer of the bound session. The `agent_id` (typically `mask`, renamed from `actor` at v0.29.9/#211) still resolves system prompt, tools, and the LLM provider unless the character carries a `role` override (a configured model-role per ADR-0012 — the raw `model` selector left this surface at the role cutover).
 
 ### `POST /characters`
 
@@ -1654,7 +1667,7 @@ Create a transient character. Requires `character.write` scope.
     "description": "A melancholy prince.",
     "narrative": "He speaks to himself when alone, weighs every choice three ways…",
     "voice_profile_block": "Formal English; iambic pentameter under pressure; weights every word.",
-    "model": "fast"
+    "role": "fast"
   },
   "state": null
 }
@@ -1690,7 +1703,7 @@ Remove the character. Requires `character.write` scope. Sessions bound to this c
 
 ### `GET /models/available-for-characters`
 
-Return the model profiles the actor (and the `model` field on `CharacterSchema`) can reference. Requires `character.read` scope.
+Return the catalog bindings the `character` model-role resolves to (what the `role` field on `CharacterSchema` can reach). Requires `character.read` scope.
 
 ```json
 {
@@ -1724,7 +1737,7 @@ When supplied, the session binds the character. The character's persona (OCEAN,
 - `410 character_not_found` — character was deleted/expired (returned at the session-bind path on next turn)
 - `422 ttl_too_large` — `ttl_seconds` over the configured ceiling
 - `422 state_schema_outdated` — schema_version mismatch; detail includes `accepted_versions`
-- `422 model_not_available_for_characters` — `model` field references a profile not in the allowlist
+- `404 model_not_available` — `role` field names an unconfigured model-role (resolved through the `character` role gate; the pre-cutover `model_not_available_for_characters` code is retired)
 - `422 validation_failed` — OCEAN out of `[-1, 1]`, voice_profile_block too long, etc.
 - `429 quota_exceeded` — per-user character cap hit
 - `403 auth_scope_denied` — missing `character.write` or `character.read`
@@ -2403,24 +2416,24 @@ The `POST /sessions/{session_id}/messages` endpoint accepts an additive `upload_
 2. Each upload existence/ownership/expiry check — first failure short-circuits with `410 upload_expired` or `404`
 3. Agent capability gate — if `upload_ids` non-empty and `agent.capabilities` does not include `accepts_uploads` → `422 agent_lacks_upload_support`
 
-### Per-call model override (issue #157)
+### Per-call role override (issue #157, role-keyed since #261/#344)
 
-The `POST /sessions/{session_id}/messages` endpoint also accepts an additive `model` field that overrides the character / agent default for this turn only:
+The `POST /sessions/{session_id}/messages` endpoint also accepts an additive `role` field that overrides the character / agent default model-role for this turn only:
 
 ```json
-{"content": "Reformat this YAML.", "model": "granite-structured"}
+{"content": "Reformat this YAML.", "role": "assistant"}
 ```
 
 **Semantics:**
-- Override is per-call only. Stored `CharacterSchema.model` is NOT mutated.
-- Validated against the same `available_for_characters` allowlist that gates `CharacterSchema.model` at create time (#153 INV-091).
-- Override displaces the character's bound model when both are set (per-call wins).
+- Override is per-call only. Stored `CharacterSchema.role` is NOT mutated.
+- Resolved through the same `character` model-role gate that validates `CharacterSchema.role` at create time (ADR-0012).
+- Override displaces the character's bound role when both are set (per-call wins).
 - Override is REJECTED on ephemeral (Echo) sessions — their config is frozen at session-create per INV-161-2.
 
 **Validation:**
-1. Pydantic validates `model`: optional string, non-empty after stripping whitespace.
-2. If the session is ephemeral (`ephemeral_config != None`): `422 validation_failed` ("per-call 'model' override is not permitted on ephemeral sessions").
-3. If `model` is not in the `available_for_characters` allowlist: `422 model_not_available_for_characters`.
+1. Pydantic validates `role`: optional string, non-empty after stripping whitespace.
+2. If the session is ephemeral (`ephemeral_config != None`): `422 validation_failed` ("per-call 'role' override is not permitted on ephemeral sessions").
+3. If `role` names an unconfigured model-role: `404 model_not_available`.
 
 **Audit:** the `turn.started` admin event carries the effective `model` plus a `model_override_applied: bool` flag so cross-system audit trails can see what model actually ran on a per-turn basis.
 
@@ -2713,7 +2726,7 @@ below document the active layers and their exact validated shapes.
 | -------- | --------------------------------- | ------------------------------------------ |
 | `POST`   | `/agents/define`                  | Create a Tier 3 agent.                     |
 | `DELETE` | `/agents/<user_id>:<agent_name>`  | Owner-initiated hard-delete.               |
-| `PATCH`  | `/agents/<user_id>:<agent_name>`  | Mutate `system_prompt` and/or `model`.     |
+| `PATCH`  | `/agents/<user_id>:<agent_name>`  | Mutate `system_prompt` and/or `role`.      |
 | `POST`   | `/sessions`                       | Tier 3 routing when `agent_id` has a `:`.  |
 | `GET`    | `/sessions/<session_id>/tools`    | Owner-scoped session-tools introspection (#183, Phase 2.0.1). |
 
@@ -2723,7 +2736,7 @@ below document the active layers and their exact validated shapes.
 {
   "agent_name": "wizard",
   "system_prompt": "You are a guided-elicitation wizard...",
-  "role": "gen-reasoning",       // REQUIRED — a configured model-role (#344), not a raw model id
+  "role": "thoughtful-assistant", // REQUIRED — a configured model-role (#344), not a raw model id
   "persona": {                   // active (Phase 2.1) — single-letter OCEAN keys; see "Persona layer"
     "ocean": {"O": 0.4, "C": 0.6, "E": -0.3, "A": 0.2, "N": 0.5}
   },
@@ -2741,12 +2754,19 @@ Response (`201 Created`):
   "user_id": "alice",
   "agent_name": "wizard",
   "system_prompt": "...",
-  "model": "glm5-turbo",
+  "role": "thoughtful-assistant",
   "created_at": "2026-05-19T12:00:00+00:00",
   "updated_at": "2026-05-19T12:00:00+00:00"
 }
 ```
 
+The response `role` echoes the requested role — symmetric with the request
+(W-4 closed, spec 1.2; the example above would echo
+`"role": "thoughtful-assistant"`). The resolved engine catalog id is
+privileged and never surfaces (#344 INV-344-3). A legacy pre-cutover row
+defined with a raw model (null stored role) surfaces that stored model
+string in this field.
+
 Caller must:
 
 - hold `agents.define` scope (default for `user` tier);
@@ -2761,6 +2781,19 @@ after definition.
 The 201 response includes an advisory `warnings` array (#219) — see
 "Model-assignment warnings" under `PATCH` below.
 
+**Duplicate name (normative, spec 2.4.0):** re-defining an existing
+`agent_name` returns `409` with `error_code: agent_name_taken` AND a
+structured `agent_id` field naming the existing agent
+(`{"detail": {"error_code": "agent_name_taken", "message": "...",
+"agent_id": "alice:wizard"}}`). Define-then-catch-409 is therefore the
+sanctioned, race-safe **define-or-reuse** shape: one round trip, no
+client-side id composition, no lookup-then-define TOCTOU window. (The
+`user_id` field on `GET /me` is also normative — guaranteed present on
+every response shape including anonymous and Heimdall-degraded — so
+client-side `<user_id>:<agent_name>` composition remains sanctioned for
+addressing, per the id shape documented above; the 409 field simply makes
+it unnecessary for the reuse flow.)
+
 > **Vendoring note (OpenAPI 2.3.0).** In the frozen OpenAPI 2.3.0 document
 > the `persona` / `motivational` / `memory` / `valence` request fields
 > serialize as **untyped/freeform** — the `POST /agents/define` request
@@ -2858,6 +2891,8 @@ Semantics:
   which must carry all three of `pleasure` / `arousal` / `dominance`, each a
   float in `[-1.0, 1.0]`. Any other top-level key → 422 `validation_failed`;
   a missing or malformed `pad` → 422 `persona_seed_invalid`.
+
+  > **✓ R32-1B (landed, v1.0.0b29):** The PAD range `[-1.0, 1.0]` relaxes to an **unbounded latent `z`** with a finite wire sanity bound (`~±10`) as of R32 Slice-1B. The JSON shape/fields/types are UNCHANGED — only the declared range/semantics change (the value becomes a latent that renders to a bounded display value). Consumers that merely store-and-return PAD need no change; consumers that validate/clamp PAD to `[-1,1]` must relax that bound. Source of truth: `docs/contracts/persona_envelope.contract.md` rev 1.7 (INV-ENV-16).
 - **Seeds the current mood POINT, not the setpoint.** The OCEAN persona
   (above) fixes the setpoint the mood relaxes toward; this endpoint sets
   where the mood *starts*. It does not alter the persona.
@@ -2966,16 +3001,18 @@ session bound to this agent and revokes the owner's per-resource
 
 #### `PATCH /agents/<user_id>:<agent_name>`
 
-**Mutable surface (Phase 2.3, #188): `system_prompt` and/or `model` only.**
-PATCH re-enforces the same validation as define — the `system_prompt`
-byte-cap and the `model` allowlist. Any other key returns a 422 BEFORE
-the DB lookup (so an immutable-field PATCH against a missing agent still
-422s, not 404s), with the error code chosen by *why* the field can't be
-set:
+**Mutable surface (Phase 2.3, #188; role-keyed since #344): `system_prompt`
+and/or `role` only.** PATCH re-enforces the same validation as define — the
+`system_prompt` byte-cap, and `role` must name a configured model-role
+(unknown role → 404 `model_not_available`). Any other key returns a 422
+BEFORE the DB lookup (so an immutable-field PATCH against a missing agent
+still 422s, not 404s), with the error code chosen by *why* the field can't
+be set:
 
 | Field(s) | Code | Reason |
 |---|---|---|
 | `agent_name`, `user_id`, `agent_id` | `field_not_mutable` | Identity — fixed at creation. |
+| `model` | `field_not_mutable` | Engine catalog ids left the surface at the role cutover (#344) — select via `role`. |
 | `persona`, `motivational` | `field_not_mutable` | Shipped traits; an agent *is* its personality/goals. Change → define a new agent. |
 | `memory` | `field_not_mutable` | Rejected **wholesale** — see below. |
 | `valence` | `layer_deferred` | Not a shipped layer yet (matches define-time); not a frozen trait. |
@@ -2994,18 +3031,23 @@ whole field with `field_not_mutable`. When a real long-term-memory tuning
 dial ships, its PATCH semantics will be specified at that time.
 
 **Active sessions are unaffected.** A PATCH never mutates an in-flight
-session's cached `AgentContext`; new `system_prompt` / `model` values take
+session's cached `AgentContext`; new `system_prompt` / `role` values take
 effect only at the next session-create.
 
 **Audit.** A successful PATCH emits one `agents.patch` event whose
-`changes` detail records before/after per mutated field: `model` as literal
-`{before, after}` values, and `system_prompt` as `{before_bytes,
+`changes` detail records before/after per mutated field: a `role` change is
+recorded as its **derived catalog** `model` `{before, after}` pair (the
+audit log is a privileged surface; #344 INV-344-6 updates role + derived
+catalog id in one write), and `system_prompt` as `{before_bytes,
 after_bytes}` only — the raw prompt text is never written to the audit log
 (potential PII).
 
-**Model-assignment warnings (#219).** A `model` swap is **not blocked** for
-capability or context-window compatibility, but PATCH (and `define`) attach an
-advisory `warnings` array to the response — see the shared subsection below.
+**Model-assignment warnings (#219).** A role swap is **not blocked** for
+capability or context-window compatibility. PATCH (and `define`) attach an
+advisory `warnings` array to the response — but a **role-defined agent
+always receives `[]`** (#344 INV-344-3: the warning texts name catalog-level
+engine details the role consumer didn't pick and can't act on); only legacy
+null-role rows can surface them. See the shared subsection below.
 Correctness for over-budget prompts remains the runtime `context_overflow`
 guard; the warnings are an early, best-effort heads-up.
 
@@ -3025,9 +3067,12 @@ two mutation responses, not on `GET /agents/<id>`. Each entry is
 
 Semantics:
 
-- **`define`** has no prior model, so only `model_context_window_unknown` can
-  fire there. **PATCH** computes warnings only when the payload changes `model`
-  (a `system_prompt`-only PATCH returns `warnings: []`); the comparison is
+- **Role-defined agents never receive these warnings** — `warnings` is
+  always `[]` for them (#344 INV-344-3); the codes below can only surface on
+  legacy null-role rows. **`define`** has no prior model, so only
+  `model_context_window_unknown` can fire there. **PATCH** computes warnings
+  only when the payload actually changes the underlying model (a
+  `system_prompt`-only PATCH returns `warnings: []`); the comparison is
   against the resulting model.
 - Capability warnings are **conditional by nature**: a Tier 3 agent row does
   not record whether it uses tools/vision/audio (tools arrive per-session via

docs/coverage-map.md

@@ -23,6 +23,23 @@ anchors against the frozen machine-readable artifacts, NOT the prose markdown:
 | Conversation SSE events | `conversation-api-sse-events.schema.json` (sha `9deeebf4…`) — **11 discriminated event types** | **client** |
 | Bifrost wire (consumer protocol) | wire **v0.6** STABLE/FROZEN (`bifrost==1.0.0`) — memory + affect planes | **provider** (Worldtree dispatches into us) |
 
+> **External ratification — worldtree-sdk v1.0.0 (wtsdk-dev, 2026-07-18, althing
+> thread `01KXVF24WQD2T5ZCS49KKFCCMH`).** The TypeScript v0 consumer SDK wires all
+> **41 ops as typed methods** from the **same OpenAPI 2.3.0** (sha
+> `36148179601453a0` — matches our vendored pin exactly), so it is the independent
+> parity authority for the surface this ledger tracks. Ratatoskr does **not** adopt
+> the SDK — we are the parallel **Python/httpx** reference-consumer of the identical
+> surface (no TS/npm surface exists to pin it into). Cross-check corroboration: the
+> SDK's **W-4** (send `config.role`, response echoes `model` unremapped) matches what
+> ratatoskr shipped in **v0.21.2** for ephemeral-Echo create.
+>
+> **Future consumable — worldtree-sdk Python spine (wtsdk-dev, next milestone).** The
+> TS v1 surface is our parity *checklist*; the forthcoming **Python spine** (same
+> behavioral-spec + fixture corpus, TS decisions kept Python-portable per their
+> surface-design §6) is what ratatoskr would actually *consume* when it lands.
+> wtsdk-dev slots ratatoskr as **THE reference consumer** whose coverage column
+> drives that spine — a future repin candidate, not yet available.
+
 > **Pin drift (finding P-1) — REMEDIATED 2026-06-30.** Ratatoskr formerly
 > vendored only the **prose markdown** (`docs/conversation-api-spec.md`), which
 > is byte-identical to live Worldtree's but frozen at v0.35.16-era content (last
@@ -67,34 +84,36 @@ sub-gap).
 
 | Endpoint | Status | Where consumed | Note |
 |---|---|---|---|
-| `POST /sessions` | ✅ | `sessions.py:307` → `cli.py:482`,`tui.py:1508`,`web/server.py:155` | + `end_user_id`, `bifrost` binding; 404→AgentNotFound, 502→BifrostHandshakeFailed |
-| `POST /sessions/{id}/messages` (turn stream, SSE) | ✅ | `sse_client.py:484` `stream_turn` → cli/tui/web | the primary surface; 409→AgentNotAvailable, 503→TurnLaunchUnavailable (b2 #331) |
-| `POST /sessions/{id}/history` (authored-history-write, #347) | ✅ | `sessions.py:583` `write_authored_history` → `cli.py:758` `--seed-first-message` | v1: author=assistant, effects=none, per-session idempotency; 404→AuthoredHistoryUnavailable (hide-existence: feature-absent, never probe); 409/422 mapped. **LIVE-PROVEN 2026-07-06** on personal :8081 (grant applied via a rule-based Heimdall allow, worldtree-dev): create mimir session → seed → **201** (seq=0, phase=seeded, turn_id=1798) → GET /messages reads it back as a plain role=assistant turn (model-invisible provenance confirmed). Hide-404 for ungranted is unit+probe covered |
-| `GET /sessions/{id}/messages` (history) | ✅ | `sessions.py:635` `get_session_messages` → `cli.py:758` `--seed-first-message` read-back | un-deferred as the #347 seed read-back — confirms model-invisible provenance (a seed reads back as a normal `role=assistant` turn) |
-| `POST /sessions/{id}/turns/{turn_id}/cancel` | ✅ | `sse_client.py:581` → cli/tui/web | two-stage Ctrl-C; 404/409 mapped |
-| `GET /agents` | ✅ | `sessions.py:341` → `tui.py:1472`,`web/server.py:100` | Tier-1 roster; merged with local index |
-| `GET /agents/{id}/persona_state` | ✅ | `sessions.py:384` → `tui.py:1132`,`web/server.py:386` | persona hydrate; 404/403 mapped |
-| `POST /agents/define` | ✅ | `tier3.py:175` → `_run_define` | Tier-3 create |
-| `PATCH /agents/{id}` | ✅ | `tier3.py:219` → `_run_patch` | Tier-3 mutate (system_prompt/model) |
-| `DELETE /agents/{id}` | ✅ | `tier3.py:242` → `_run_delete` | Tier-3 hard-delete |
-| `GET /me` | ✅ | `sessions.py:411` `get_me` → `cli.py` `--whoami` | identity/whoami probe; 401→SessionApiFailed |
-| `GET /capabilities` | ✅ | `sessions.py:428` `get_capabilities` → `cli.py` `--whoami` | Echo ephemeral-template discovery |
-| `GET /sessions/{id}/tools` | ✅ | `sessions.py:411` `get_session_tools` → `tui.py` `_hydrate_session_tools` | owner-scoped tool inventory in the TUI Tools pane (#183) |
-| `GET /admin/sessions/{id}/bifrost` | ✅ | `sessions.py:428` `get_session_bifrost` → `tui.py` `_hydrate_bifrost_state` | admin-scoped BifrostState pane (#176); admin key (`RATATOSKR_ADMIN_API_KEY`); live-auth-proven |
-| `GET /admin/events` (SSE) | ✅ | `sse_client.py` `stream_admin_events` → `tui.py` `_stream_admin_events` | admin lifecycle SSE stream (#11), session-filtered AdminEvents pane; admin key; live-auth-proven |
-| `GET /models/available-for-characters` | ✅ | `sessions.py` `list_character_models` → `cli.py` `--characters` | character-capable model profiles (#161) |
-| `POST /characters` | ✅ | `sessions.py` `create_character` → `cli.py` `--characters` | create transient character (#161) |
-| `GET /characters/{id}/state` | ✅ | `sessions.py` `get_character_state` → `cli.py` `--characters` | live character PAD/emotions (#161) |
-| `DELETE /characters/{id}` | ✅ | `sessions.py` `delete_character` → `cli.py` `--characters` | remove transient character (#161) |
-| `POST /sessions/{id}/persona_state` | ✅ | `sessions.py` `set_persona_state` → `cli.py` `--set-persona-pad` | persona-state write / affect injection (freeform body — unpinned in the frozen surface) |
+| `POST /sessions` | ✅ | `wt.py` `create_session` (SDK `sessions.create`) → `cli.py`,`web/server.py` | **wt-adapter re-anchored (slice-2, #20)** — + `end_user_id`, `bifrost` binding (consumer-key via SDK per-request auth), `config` passthrough; 404→AgentNotFound, bound-502→BifrostHandshakeFailed. Ephemeral-template (Echo) create (#19) carried through the adapter. Depth enhancement to an already-covered route — count unchanged |
+| `POST /sessions/{id}/messages` (turn stream, SSE) | ✅ | `wt.py` `stream_turn` (SDK resilient `sessions.stream_turn`, auto-resume) → cli/web | **wt-adapter re-anchored (slice-2, #20)** — the primary surface; 409→AgentNotAvailable, 503→TurnLaunchUnavailable, drop→SseConnectionDropped, protocol→same-named; absorbs the old `reconnect_turn` |
+| `POST /sessions/{id}/history` (authored-history-write, #347) | ✅ | `wt.py` `write_authored_history` (SDK `sessions.write_history`) → `cli.py` `--seed-first-message`, `first_message.py` `seed_preset_first_message` (create-path seed) | **wt-adapter re-anchored (slice-3, #20)** — SDK owns the entry shape; v1 author=assistant; 404→AuthoredHistoryUnavailable (hide-existence, route is the discriminator, never probe); 409/422→SessionApiFailed default. **LIVE-SMOKE 2026-07-19** on personal :8081 (b128): `--seed-first-message` on a sindra session → **201** (seq=0, phase=seeded, turn_id=2294) → read-back verbatim; create-path preset seed observed via `--new`. (Prior 2026-07-06 hand-rolled proof superseded.) |
+| `GET /sessions/{id}/messages` (history) | ✅ | `wt.py` `get_session_messages` (SDK `sessions.messages`) → `cli.py` `--seed-first-message` read-back, `web/server.py` messages proxy | **wt-adapter re-anchored (slice-3, #20)** — the #347 seed read-back; open-world passthrough. **LIVE-SMOKE 2026-07-19**: read-back rendered the seeded seq-0 turn as a plain role=assistant message (model-invisible provenance confirmed) |
+| `POST /sessions/{id}/turns/{turn_id}/cancel` | ✅ | `wt.py` `cancel_turn` (SDK `sessions.cancel_turn`) → cli/web | **wt-adapter re-anchored (slice-2, #20)** — two-stage Ctrl-C; 404→CancelTurnNotFound, 409→CancelAlreadyCompleted, late-cancel 200 (`cancelled=False`) is a benign result, not an error |
+| `GET /agents` | ✅ | `wt.py` `list_agents` (SDK `agents.list`) → `web/server.py` `_agents_endpoint` | **wt-adapter re-anchored (slice-4, #20)** — open-world array verbatim (no AgentInfo normalization), merged with the local tier3 index (remote-wins); error→SessionApiFailed default, transport→ConnectFailed→502. **LIVE-SMOKE 2026-07-19** on personal :8081 (b128): 6 agents returned (forseti/lofn/mask/mimir/vili/…) |
+| `GET /agents/{id}/persona_state` | ✅ | `wt.py` `get_persona_state` (SDK `agents.persona_state`) → `web/server.py` `_persona_state_endpoint` | **wt-adapter re-anchored (slice-4, #20)** — open-world snapshot; dual-key (status,error_code) map: 404 persona_not_configured→PersonaNotConfigured, 404 agent_not_available→AgentNotAvailable, 403 auth_scope_denied→AuthScopeDenied, else default. **LIVE-SMOKE 2026-07-19**: a tier3 agent → correctly mapped `PersonaNotConfigured` (route+code adapter proven) |
+| `POST /agents/define` | ✅ | `wt.py` `define_agent` (SDK `agents.define`) → `tier3.py` `_run_define` | **wt-adapter re-anchored (slice-4, #20)** — sends AgentDefineInput `{agent_name,role,system_prompt}`, returns open-world `DefinedAgent` (echoes `role`, b128); slug pre-validated; 429→Tier3QuotaExceeded(retry_after=0, header-less floor), 403→Tier3UserIdUnsupported, 422 layer_deferred→Tier3LayerDeferred. **LIVE-SMOKE 2026-07-19**: `define --role thoughtful-character` → `defined ratatoskr:slice4-smoke (thoughtful-character)` |
+| `PATCH /agents/{id}` | ✅ | `wt.py` `patch_agent` (SDK `agents.patch`) → `tier3.py` `_run_patch` | **wt-adapter re-anchored (slice-4, #20)** — Tier-3 mutate (system_prompt/**role**, model→role folded in); 404→Tier3AgentNotFound, 422 field_not_mutable→Tier3FieldNotMutable. **LIVE-SMOKE 2026-07-19**: `patched ratatoskr:slice4-smoke`; a non-existent id via `python -m` → `[agent_not_found]` (exit 20, class-identity fix proven) |
+| `DELETE /agents/{id}` | ✅ | `wt.py` `delete_agent` (SDK `agents.delete`) → `tier3.py` `_run_delete` | **wt-adapter re-anchored (slice-4, #20)** — 204→None; 404→Tier3AgentNotFound (route-discriminated, NOT hide-existence). **LIVE-SMOKE 2026-07-19**: `deleted ratatoskr:slice4-smoke` + local index → `[]` |
+| `GET /me` | ✅ | `wt.py` `get_me` (SDK `me.get`) → `cli.py` `--whoami` | **wt-adapter re-anchored (slice-5, #20)** — open-world identity dict verbatim; any error→SessionApiFailed default (401 on a bad/absent key), transport→ConnectFailed→exit 21. **LIVE-SMOKE 2026-07-19** on personal :8081 (b128): identity rendered (user_id ratatoskr, tier user, scopes incl. `character.*`, key_id c990f0be) |
+| `GET /capabilities` | ✅ | `wt.py` `get_capabilities` (SDK `capabilities.get`) → `cli.py` `--whoami` | **wt-adapter re-anchored (slice-5, #20)** — open-world advertisement verbatim; `_format_whoami` reads `allowed_roles`/`default_role` and degrades on a null/non-mapping template (slice-4 hardening); matches conversation-api-spec **v1.1** (`b4a278c`). **LIVE-SMOKE 2026-07-19**: `ephemeral_template echo: default=echo max_bytes=32768 roles=[echo]` |
+| `GET /sessions/{id}/tools` | ✅ | `wt.py` `get_session_tools` (SDK `sessions.tools`) → `web/server.py` `_session_tools_endpoint` | **wt-adapter re-anchored (slice-7 teardown, #20)** — owner-scoped tool inventory (#183); consumer bearer (no admin scope), open-world dict verbatim, any error→SessionApiFailed default. (Consumer is `web/server.py`; the old `sessions.py`→`tui.py` row was stale — the TUI is deleted.) |
+| `GET /admin/sessions/{id}/bifrost` | ✅ | `wt.py` `get_session_bifrost` (SDK `admin.sessions.bifrost`) → `web/server.py` `_session_bifrost_endpoint` | **wt-adapter re-anchored (slice-6, #20)** — admin-scoped BifrostState (#176); admin_auth rides on the wt client (`_wt_client(admin_key=…)`), NOT a per-call header; open-world dict verbatim, any error→SessionApiFailed default. **LIVE-SMOKE 2026-07-19** on :8081 (readonly-admin key): admin-authed end-to-end (404 `session_not_bifrost_bound` clean envelope — auth + route + mapping proven). (Consumer is `web/server.py`, not `tui.py` — the old row was stale.) |
+| `GET /admin/events` (SSE) | ✅ | `wt.py` `stream_admin_events` (SDK `admin.stream_events`) → `web/server.py` `_admin_events_endpoint` | **wt-adapter re-anchored (slice-6, #20)** — admin lifecycle SSE (#11), session-filtered; admin_auth on the wt client; the adapter re-wraps the SDK's `AdminEvent`→ratatoskr's (nan `admin_id`→id 0, None type/data→`""`/`{}`), non-200 open `ApiError`→SseConnectFailed, `ConnectionDropped`→SseConnectionDropped. **LIVE-SMOKE 2026-07-19**: a real `session.created` event (id=32) re-wrapped cleanly on live wire. (Consumer is `web/server.py`, not `tui.py` — stale row corrected.) |
+| `GET /models/available-for-characters` | ✅ | `wt.py` `list_character_models` (SDK `models.available_for_characters`) → `cli.py` `--characters` | **wt-adapter re-anchored (slice-5, #20)** — open-world catalog verbatim; the probe reads `items` null-safe (`or []`); any error→SessionApiFailed default. **LIVE-SMOKE 2026-07-19**: `character models: char-rp` |
+| `POST /characters` | ✅ | `wt.py` `create_character` (SDK `characters.create`) → `cli.py` `--characters` | **wt-adapter re-anchored (slice-5, #20)** — body `{character}` (+`state` only when set — SDK-idiomatic, drops the redundant explicit null); open-world create ACK verbatim; the probe degrades on a missing `character_id` (no hard-index). **LIVE-SMOKE 2026-07-19**: `created char_8c00006e…` |
+| `GET /characters/{id}/state` | ✅ | `wt.py` `get_character_state` (SDK `characters.state`) → `cli.py` `--characters` | **wt-adapter re-anchored (slice-5, #20)** — open-world live PAD/emotions verbatim; TTL-refreshing read. **LIVE-SMOKE 2026-07-19**: `state pad=[0.234, -0.136, 0.065]` read back |
+| `DELETE /characters/{id}` | ✅ | `wt.py` `delete_character` (SDK `characters.delete`) → `cli.py` `--characters` | **wt-adapter re-anchored (slice-5, #20)** — returns the SDK's open ACK verbatim (`-> Mapping|None`, NOT normalized to None; 204→None); any error→SessionApiFailed default. **LIVE-SMOKE 2026-07-19**: `deleted char_8c00006e…` |
+| `POST /sessions/{id}/persona_state` | ✅ | `wt.py` `set_persona_state` (SDK `sessions.set_persona_state`, `PadState`) → `cli.py` `--set-persona-pad` | **wt-adapter re-anchored (slice-3, #20)** — SDK owns the canonical `{"pad": {...}}` wire (#317); CLI passes the 3 PAD axes (finiteness pre-validated); 204→None, else SessionApiFailed default. **LIVE-SMOKE 2026-07-19** on personal :8081: `--set-persona-pad 0.4,0.1,-0.2` → **204** |
 
 **Sub-gaps inside ✅ path groups** (the method we use is live; a sibling method
 on the same path is an unwired frontier item — see frontier Tier 1):
-- `GET /sessions` — `sessions.py:198` `list_sessions` exists, **no caller**: the
-  startup session-picker (design-brief §4 v1) was never wired.
-- `POST /sessions/{id}/messages` + `Last-Event-ID` — `sse_client.py:524`
-  `reconnect_turn` exists, **no caller**: the reference SSE-resume impl
-  (design-brief §8d) was never wired.
+- `GET /sessions` — `wt.py:234` `list_sessions` (SDK `sessions.list`) exists,
+  **no caller**: the startup session-picker (design-brief §4 v1) was a TUI feature
+  and the TUI is now deleted, so the frontier is moot unless a web picker is wired.
+- `POST /sessions/{id}/messages` + `Last-Event-ID` (SSE-resume) — **CLOSED (slice-2
+  teardown)**: the old hand-rolled `sse_client.reconnect_turn` is deleted; resume is
+  now folded into `wt.py:280` `stream_turn` (the SDK's resilient auto-resume), which
+  IS the wired presenter default. No longer an unwired sub-gap.
 - `GET /agents/{id}` — consumer-agent lookup (`GET /agents/<owner>:<name>` with
   the owner key) is **manual-curl-only**, not in code.
 
@@ -156,8 +175,9 @@ a turn flow through it / is it a layer worth watching live?*
 
 ## Surface 2 — SSE events (11/11 ✅)
 
-Every frozen SSE event type is parsed in `sse_client.py:_envelope_for_type`
-(342-411) and rendered by all three presenters (cli/tui/web). **Full coverage.**
+Every frozen SSE event type is now parsed by **worldtree-sdk** (`sessions.stream_turn`,
+yielding `TurnEvent`s — the hand-rolled `sse_client._envelope_for_type` is deleted) and
+rendered by both presenters (cli/web; the TUI is deleted). **Full coverage.**
 
 `text` · `worker_phase` · `thinking` · `text_boundary` · `tool_start` ·
 `tool_result` · `done` · `error` · `cancelled` · `awaiting_llm_first_token` ·

docs/diagnostics/descriptive_query_binding.py

@@ -0,0 +1,181 @@
+#!/usr/bin/env python3
+"""Descriptive-query subject-binding probe — the canonical fixture for Worldtree #393.
+
+#393: an ATTRIBUTE/descriptive question ("the guy with the roid rage") reformulates to a
+token query that matches MULTIPLE distinct canon subjects on a shared word ("rage"), so the
+intended entity can be absent from top-k while topically-adjacent decoys rank above it. The
+name-check (`names_subject`) can't help — the caller has no name to pass until the attribute
+is resolved to an entity, which is the open problem. Downstream, the consumer sometimes binds
+to the wrong co-retrieved subject and cross-contaminates details (a confident, fluent mis-bind
+assembled from real-but-mismatched rows, not a hallucination).
+
+Two regimes at DIFFERENT WING SCOPES (the distinction is load-bearing — Worldtree #393):
+  * RAW RANKING — ALL-WING (mimir searches kb+main+fiction, ~9800 rows). Drive `mimir` with the
+    descriptive query + variants; report the query mimir ACTUALLY passed (tool_start q=, since it
+    reformulates) and where the intended ENTITY lands. Cross-wing dilution can push a one-arm
+    vector bridge out of the bge rescue window entirely -> entity ABSENT from top-k.
+  * CONSUMER — FICTION (ratatoskr:donut is fiction-scoped, ~1578 rows). Drive Donut N times;
+    classify BINDS-ENTITY vs MIS-BINDS-DECOY vs OTHER, and report where the ENTITY and DECOY rank
+    in her fiction-scoped results. The ranks tell WHICH failure fired per run: entity PRESENT +
+    mis-bind = subject-selection; entity ABSENT + a present decoy = reformulation-induced absence
+    (Donut distilled the descriptive phrase to bare tokens that don't carry the vocabulary bridge).
+    Empirically Donut mostly does the latter — she distills "the guy with the roid rage" to bare
+    "roid rage", so Juicer drops out even at fiction scope and she binds a present decoy (Jack).
+
+Two-seam finding (2026-08-07, v1.0.0b181) — both lose the entity, by DIFFERENT reformulation seams:
+(1) mimir PRESERVES the phrase -> cross-wing dilution (kb+main+fiction) drops the entity from its
+all-wing top-k; (2) Donut DISTILLS the phrase to bare tokens -> the entity drops even at fiction
+scope (ent@None) and she binds a present decoy. The fold's ENT@/DEC@ ranks separate reformulation-
+absence from true subject-selection per run. Unifying lever: disambiguating-vocabulary expansion
+(the full phrase, or +attribute like "steroid") surfaces the entity at fiction scope — Donut's
+expand-runs bind correctly. "dangerous crown" is mostly RESOLVED (one entity). Root gap:
+attribute->entity resolution, upstream of names_subject by construction.
+
+Self-contained: the only third-party dependency is httpx (`uv run --with httpx`). Config from env:
+WORLDTREE_API_URL, WORLDTREE_API_KEY, RATATOSKR_END_USER_ID. No secrets stored here.
+
+Usage:
+  uv run --with httpx python docs/diagnostics/descriptive_query_binding.py
+  uv run --with httpx python docs/diagnostics/descriptive_query_binding.py --runs 10
+  uv run --with httpx python docs/diagnostics/descriptive_query_binding.py --case roid-rage
+"""
+from __future__ import annotations
+
+import argparse
+import json
+import os
+import re
+from collections import Counter
+
+import httpx
+
+# (label, descriptive question, raw-ranking query variants, intended-entity regex, decoy regex|None)
+CASES = [
+    {
+        "label": "roid-rage",
+        "question": "Tell me about the guy with the roid rage.",
+        "variants": ["the guy with the roid rage", "roid rage"],
+        "entity": r"juicer",
+        "decoy": r"\bJack\b",
+    },
+    {
+        "label": "dangerous-crown",
+        "question": "Tell me about that dangerous crown.",
+        "variants": ["that dangerous crown", "dangerous crown"],
+        "entity": r"sepsis|crown of the sepsis whore",
+        "decoy": None,
+    },
+]
+
+
+def _cfg() -> tuple[str, dict, str]:
+    base = os.environ.get("WORLDTREE_API_URL", "http://10.250.50.152:8081")
+    key = os.environ.get("WORLDTREE_API_KEY")
+    if not key:
+        raise SystemExit("WORLDTREE_API_KEY unset — source env.sh first.")
+    end_user = os.environ.get("RATATOSKR_END_USER_ID", "ratatoskr-tui")
+    return base, {"Authorization": f"Bearer {key}"}, end_user
+
+
+def _session(base: str, headers: dict, agent_id: str, end_user: str) -> str:
+    r = httpx.post(f"{base}/sessions", json={"agent_id": agent_id, "end_user_id": end_user},
+                   headers=headers, timeout=30)
+    r.raise_for_status()
+    return r.json()["session_id"]
+
+
+def _drive(base: str, headers: dict, sid: str, content: str) -> tuple[str | None, dict, str]:
+    """POST a turn; return (tool_query, first tool_result dict, accumulated answer text)."""
+    q, result, parts = None, {}, []
+    with httpx.stream("POST", f"{base}/sessions/{sid}/messages", json={"content": content},
+                      headers=headers, timeout=180) as r:
+        for line in r.iter_lines():
+            if not line.startswith("data: "):
+                continue
+            ev = json.loads(line[6:])
+            t = ev.get("type")
+            if t == "tool_start" and q is None:
+                q = (ev.get("arguments") or {}).get("query")
+            elif t == "tool_result" and not result:
+                result = ev.get("result") if isinstance(ev.get("result"), dict) else {}
+            elif t == "text":
+                v = ev.get("text") or ev.get("content") or ev.get("delta")
+                if isinstance(v, str):
+                    parts.append(v)
+            elif t == "done":
+                break
+    return q, result, "".join(parts)
+
+
+def _flag(excerpt: str, entity: str, decoy: str | None) -> str:
+    if re.search(entity, excerpt, re.I):
+        return "ENTITY"
+    if decoy and re.search(decoy, excerpt):
+        return "DECOY "
+    return "      "
+
+
+def _rank_in(res: dict, pattern: str | None) -> int | None:
+    """Rank of the first row whose excerpt matches `pattern` (None if absent / no pattern)."""
+    if not pattern:
+        return None
+    rows = res.get("hits", res.get("results", [])) if isinstance(res, dict) else []
+    return next((i for i, r in enumerate(rows) if isinstance(r, dict)
+                 and re.search(pattern, r.get("excerpt", ""), re.I)), None)
+
+
+def raw_ranking(base, headers, end_user, case) -> None:
+    print("\n  [raw ranking — ALL-WING/mimir] actual tool query (reformulation seam) + entity rank")
+    for query in case["variants"]:
+        sid = _session(base, headers, "mimir", end_user)  # fresh session per query
+        mimir_q, res, _ = _drive(base, headers, sid, f"Use search_library to find: {query}")
+        rows = res.get("results", []) if isinstance(res, dict) else []
+        entity_ranks = [i for i, r in enumerate(rows) if isinstance(r, dict)
+                        and re.search(case["entity"], r.get("excerpt", ""), re.I)]
+        rank = entity_ranks[0] if entity_ranks else "ABSENT (not in top-k)"
+        # mimir_q is load-bearing for #393: separates reformulation-at-the-agent-seam
+        # (mimir distilled/expanded the phrase) from ranking (the tool ranked it low).
+        print(f"    instructed={query!r:28} mimir_q={mimir_q!r:38} entity_rank={rank}")
+        for i, r in enumerate(rows[:6]):
+            if isinstance(r, dict):
+                ex = (r.get("excerpt") or "").replace("\n", " ")
+                print(f"      #{i} [{_flag(ex, case['entity'], case['decoy'])}] "
+                      f"{r.get('score')}  {ex[:74]}")
+
+
+def consumer(base, headers, end_user, case, runs) -> Counter:
+    verdicts: Counter = Counter()
+    print(f"\n  [consumer — FICTION/donut] x{runs} on {case['question']!r}"
+          f"  (ent@/dec@ = rank in Donut's fiction-scoped results)")
+    for run in range(1, runs + 1):
+        sid = _session(base, headers, "ratatoskr:donut", end_user)  # fresh session per run
+        q, res, ans = _drive(base, headers, sid, case["question"])
+        binds = bool(re.search(case["entity"], ans, re.I))
+        mis = bool(case["decoy"]) and bool(re.search(case["decoy"], ans)) and not binds
+        v = "BINDS-ENTITY" if binds else ("MIS-BINDS-DECOY" if mis else "OTHER")
+        verdicts[v] += 1
+        er, dr = _rank_in(res, case["entity"]), _rank_in(res, case["decoy"])
+        print(f"    run{run}: {v:16} ent@{er} dec@{dr}  q={q!r:30} :: {ans.strip()[:56]}")
+    # a present entity (ent@ not None) co-occurring with a mis-bind is subject-selection,
+    # NOT ranking-absence — the fiction-scope half of the #393 two-mechanism split.
+    print(f"    >>> {case['label']}: {dict(verdicts)}")
+    return verdicts
+
+
+def main() -> None:
+    ap = argparse.ArgumentParser(description=__doc__)
+    ap.add_argument("--runs", type=int, default=6, help="consumer repeats per case")
+    ap.add_argument("--case", help="run only this case label (e.g. roid-rage)")
+    ns = ap.parse_args()
+    base, headers, end_user = _cfg()
+    cases = [c for c in CASES if ns.case in (None, c["label"])]
+    if not cases:
+        raise SystemExit(f"no case matching {ns.case!r} (have: {[c['label'] for c in CASES]})")
+    for case in cases:
+        print(f"\n{'='*72}\n# {case['label']}")
+        raw_ranking(base, headers, end_user, case)
+        consumer(base, headers, end_user, case, ns.runs)
+
+
+if __name__ == "__main__":
+    main()

docs/diagnostics/fiction_wing_probe.py

@@ -0,0 +1,198 @@
+#!/usr/bin/env python3
+"""Fiction-wing retrieval probe harness — the recipe R42 (brokkr-smithy-dev) builds against
+and the re-runnable #389 acceptance gate.
+
+Two retrieval paths, kept SEPARATE because they have different noise properties:
+
+  * search_library (raw, RANKING-clean): drive the `mimir` foundational agent (all-wing
+    librarian) with a FIXED query string. Deterministic against a fixed index — use it for
+    ranking baselines (R42 arm-2). No LLM in the query loop.
+  * reference_knowledge (the Tier-3 consumer path): drive `ratatoskr:donut`; her reasoning
+    REFORMULATES the query each turn, so this path carries QUERY-FORMULATION variance
+    (the arm-4 signal), attributable via the captured tool_start query. NOT for ranking numbers.
+
+Scoring conventions (identical across both paths and all R42 arms):
+  * confidence BUCKET vs WT's RRF thresholds: high >= 0.030, medium >= 0.016, low < 0.016.
+  * ON-TARGET (load-bearing): a returned row is on-target iff its excerpt actually NAMES or
+    describes the queried subject (keyword match on the subject's distinctive tokens). The
+    failure signature "10 hits / MEDIUM / 0 on-target" = present-by-topic, subject absent —
+    the split that separated #384 (packaging) / #387 (coverage) / #389 (ranking).
+  * MISS = no on-target row in the returned top-k.
+
+Noise floor: freeze the generation (pin the b-tag) to remove extraction variance; fixed-string
+search_library is deterministic (no CI needed); reference_knowledge variance is query-
+formulation, not floor noise. Residual = bucket-boundary sensitivity at 0.016/0.030 — so probe
+N>=3-5 times per term and report the bucket DISTRIBUTION, never a single-run point label.
+
+Session protocol: ONE fresh session per query. A reused mimir session returns EMPTY
+search_library results after its first turn (Worldtree #391), silently scoring later terms
+false-MISS; the retrieval helpers self-session to enforce it. Never hoist the session out.
+
+Config from env (source ratatoskr's env.sh): WORLDTREE_API_URL, WORLDTREE_API_KEY,
+RATATOSKR_END_USER_ID. No secrets are stored here.
+
+Usage:
+  uv run python docs/diagnostics/fiction_wing_probe.py                 # run the artifact yardstick
+  uv run python docs/diagnostics/fiction_wing_probe.py --runs 5        # N repeats -> bucket distribution
+  uv run python docs/diagnostics/fiction_wing_probe.py --term "Enhanced Pet Biscuit" --keywords biscuit
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import os
+import unicodedata
+from collections import Counter
+
+import httpx
+
+HIGH, MEDIUM = 0.030, 0.016  # WT RRF confidence thresholds
+
+
+def _cfg() -> tuple[str, dict, str]:
+    base = os.environ.get("WORLDTREE_API_URL", "http://10.250.50.152:8081")
+    key = os.environ.get("WORLDTREE_API_KEY")
+    if not key:
+        raise SystemExit("WORLDTREE_API_KEY unset — source env.sh first.")
+    end_user = os.environ.get("RATATOSKR_END_USER_ID", "ratatoskr-tui")
+    return base, {"Authorization": f"Bearer {key}"}, end_user
+
+
+def _bucket(score: float | None) -> str:
+    if score is None:
+        return "none"
+    return "high" if score >= HIGH else "medium" if score >= MEDIUM else "low"
+
+
+# Curly punctuation the b170 extraction emits (U+2019 etc.) folded to ASCII so a
+# possessive-named subject ("Darcy's letter") matches regardless of quote style.
+_QUOTE_FOLD = str.maketrans({
+    "‘": "'", "’": "'",  # noqa: RUF001 - single curly quotes / apostrophe
+    "“": '"', "”": '"',  # double curly quotes
+    "′": "'", "″": '"',  # noqa: RUF001 - primes
+})
+
+
+def _fold(s: str) -> str:
+    """NFKC-normalize, fold curly quotes/apostrophes to ASCII, lowercase.
+    NFKC alone does NOT fold U+2019, so the explicit quote-fold is load-bearing."""
+    return unicodedata.normalize("NFKC", s or "").translate(_QUOTE_FOLD).lower()
+
+
+def _on_target(excerpt: str, keywords: list[str]) -> bool:
+    ex = _fold(excerpt)
+    return any(_fold(k) in ex for k in keywords)
+
+
+def _session(base: str, headers: dict, agent_id: str, end_user: str) -> str:
+    r = httpx.post(f"{base}/sessions", json={"agent_id": agent_id, "end_user_id": end_user},
+                   headers=headers, timeout=30)
+    return r.json()["session_id"]
+
+
+def _drive(base: str, headers: dict, sid: str, content: str) -> tuple[str | None, dict]:
+    """POST a turn, return (tool_query, tool_result_dict). tool_result is the first tool packet."""
+    tool_query, result = None, {}
+    with httpx.stream("POST", f"{base}/sessions/{sid}/messages", json={"content": content},
+                      headers=headers, timeout=120) as r:
+        for line in r.iter_lines():
+            if not line.startswith("data: "):
+                continue
+            ev = json.loads(line[6:])
+            t = ev.get("type")
+            if t == "tool_start" and tool_query is None:
+                tool_query = (ev.get("arguments") or {}).get("query")
+            elif t == "tool_result" and not result:
+                result = ev.get("result") if isinstance(ev.get("result"), dict) else {}
+            elif t == "done":
+                break
+    return tool_query, result
+
+
+def search_library(base, headers, end_user, term, keywords):
+    """RANKING-clean path: fixed-string search over the mimir librarian. Deterministic.
+
+    Opens a FRESH mimir session per call — REQUIRED. mimir stops returning
+    search_library results after the first turn on a reused session (Worldtree #391),
+    silently scoring every later term a false-MISS; do not hoist the session to the caller.
+    """
+    msid = _session(base, headers, "mimir", end_user)
+    _, res = _drive(base, headers, msid, f"Use search_library to find: {term}")
+    rows = res.get("results", []) if isinstance(res, dict) else []
+    on = [h for h in rows if isinstance(h, dict) and _on_target(h.get("excerpt", ""), keywords)]
+    top = on[0] if on else None
+    score = round(top["score"], 4) if top else None
+    return {"n": len(rows), "on_target": len(on), "hit": bool(on),
+            "score": score, "bucket": _bucket(score),
+            "excerpt": (top.get("excerpt", "")[:140] if top else None)}
+
+
+def reference_knowledge(base, headers, end_user, question, keywords):
+    """Consumer path: Donut reformulates -> capture her tool_query. NOT for ranking numbers.
+
+    Fresh donut session per call (same reuse-degradation guard as search_library, and
+    it keeps each run an independent first-turn sample rather than a growing conversation).
+    """
+    dsid = _session(base, headers, "ratatoskr:donut", end_user)
+    q, res = _drive(base, headers, dsid, question)
+    hits = res.get("hits", []) if isinstance(res, dict) else []
+    on = [h for h in hits if isinstance(h, dict) and _on_target(h.get("excerpt", ""), keywords)]
+    return {"tool_query": q, "n": len(hits), "on_target": len(on),
+            "confidence": res.get("confidence") if isinstance(res, dict) else None}
+
+
+# Artifact yardstick — worldtree-dev grep-confirmed in DCC book-1. Frozen arm-2 baseline.
+YARDSTICK = [
+    ("Enchanted Crown of the Sepsis Whore", "Crown of the Sepsis Whore", ["sepsis", "crown"]),
+    ("Enhanced Pet Biscuit", "Pet Biscuit", ["biscuit"]),
+    ("Enchanted BigBoi Boxers", "BigBoi Boxers", ["boxers", "bigboi"]),
+    ("Enchanted Toe Ring of the Splatter Skunk", "Toe Ring of the Splatter Skunk",
+     ["toe ring", "splatter", "skunk"]),
+]
+
+
+def run_yardstick(runs: int) -> None:
+    base, headers, end_user = _cfg()
+    print(f"# Fiction-wing ranking yardstick  (search_library, {runs} run(s) per name)\n")
+    for full, partial, kw in YARDSTICK:
+        for label, term in (("full ", full), ("part ", partial)):
+            buckets, hits = Counter(), 0
+            for _ in range(runs):
+                r = search_library(base, headers, end_user, term, kw)
+                buckets[r["bucket"]] += 1
+                hits += r["hit"]
+            dist = " ".join(f"{b}:{c}" for b, c in buckets.most_common())
+            print(f"  [{label}] {term:<42} hit {hits}/{runs}  buckets({dist})")
+        print()
+
+
+def run_term(term: str, keywords: list[str], runs: int) -> None:
+    base, headers, end_user = _cfg()
+    print(f"# Probe: {term!r}  ({runs} run(s))\n")
+    sl_buckets, sl_hits = Counter(), 0
+    for _ in range(runs):
+        r = search_library(base, headers, end_user, term, keywords)
+        sl_buckets[r["bucket"]] += 1
+        sl_hits += r["hit"]
+    print(f"  search_library : hit {sl_hits}/{runs}  buckets({dict(sl_buckets)})")
+    for _ in range(runs):
+        rk = reference_knowledge(base, headers, end_user, f"Tell me about the {term}.", keywords)
+        print(f"  reference_knowledge: conf={rk['confidence']} on_target={rk['on_target']}"
+              f"  (donut query: {rk['tool_query']!r})")
+
+
+def main() -> None:
+    ap = argparse.ArgumentParser(description=__doc__)
+    ap.add_argument("--runs", type=int, default=1, help="repeats per term (>=3-5 near the floor)")
+    ap.add_argument("--term", help="probe a single term instead of the yardstick")
+    ap.add_argument("--keywords", nargs="*", default=[], help="on-target keywords for --term")
+    ns = ap.parse_args()
+    if ns.term:
+        run_term(ns.term, ns.keywords or [ns.term.split()[-1]], ns.runs)
+    else:
+        run_yardstick(ns.runs)
+
+
+if __name__ == "__main__":
+    main()

docs/diagnostics/lexical_recall_gate.py

@@ -0,0 +1,145 @@
+"""Lexical-recall gate — the class acceptance instrument for exact-term recall survival.
+
+Generalizes the crown repro (Worldtree #400 / thread 01KZETD98T) beyond its anchor. The
+class property under test: when the corpus contains a chunk whose text literally carries a
+queried surface form, a natural query for that entity should serve >= 1 such chunk at a
+USABLE rank (inside the top-K window). The crown ("Crown of the Sepsis Whore") is the
+motivating STRESS case — a common word with a dense-similar vanity cluster that buries the
+exact-lexical match; distinctive names (Krakaren, Vine Creeper) are CONTROLs that should
+always pass. The gap lives on the stress class, not the controls.
+
+This is a before/after regression instrument, NOT a fix: run it pre-deploy and post-deploy
+(the BM25 stemming fold, then any rerank_hybrid_floor lever) to measure whether the served
+miss-rate on the stress class actually moves. Real-world by design — it drives the agent
+end-to-end (the agent composes its own reference_knowledge query, as in production), and
+--runs samples that query-formulation variance to estimate a true miss-rate.
+
+Self-contained (httpx only). Config from env (source env.sh first):
+  WORLDTREE_API_URL (default personal :8081), WORLDTREE_API_KEY (required),
+  RATATOSKR_END_USER_ID (default ratatoskr-tui), RATATOSKR_TTS_AGENT unused here.
+
+  uv run --with httpx python docs/diagnostics/lexical_recall_gate.py
+  uv run --with httpx python docs/diagnostics/lexical_recall_gate.py --runs 5
+  uv run --with httpx python docs/diagnostics/lexical_recall_gate.py --anchor crown
+"""
+from __future__ import annotations
+
+import argparse
+import json
+import os
+import re
+
+import httpx
+
+# Served window: a hit past this rank is not "usable" (Worldtree serves ~top-10; a row at
+# rank 9-11 is the RRF knife-edge worldtree-dev identified — treated as a KNIFE-EDGE pass).
+USABLE_K = 10
+KNIFE_EDGE_FROM = 8  # ranks >= this inside the window are fragile (one-rank-edge residual class)
+
+AGENT = "ratatoskr:donut"
+
+# (label, kind, term-regex the served chunk's excerpt must contain, [natural user messages]).
+# kind: "stress" = common word + competing dense cluster; "control" = distinctive name.
+# Controls should pass every run; the class limitation shows as stress-class misses / knife-edges.
+ANCHORS = [
+    ("crown", "stress", r"\bcrown",
+     ["What crown do you own?", "Do you have a crown?", "Tell me about your crown."]),
+    ("vine-creeper", "control", r"vine creeper",
+     ["Tell me about the Vine Creeper.", "What is the Vine Creeper?"]),
+    ("danger-dingo", "control", r"danger dingo|\bdingo",
+     ["What is the Danger Dingo?", "Describe the Danger Dingo."]),
+    ("pedicure-kit", "control", r"pedicure",
+     ["What does the Pedicure Kit do?", "Tell me about the Pedicure Kit."]),
+    ("neighborhood-map", "control", r"neighborhood map",
+     ["What is the Neighborhood Map?", "Describe the Neighborhood Map."]),
+]
+
+
+def _cfg() -> tuple[str, dict, str]:
+    base = os.environ.get("WORLDTREE_API_URL", "http://10.250.50.152:8081")
+    key = os.environ.get("WORLDTREE_API_KEY")
+    if not key:
+        raise SystemExit("WORLDTREE_API_KEY unset — source env.sh first.")
+    return base, {"Authorization": f"Bearer {key}"}, os.environ.get("RATATOSKR_END_USER_ID", "ratatoskr-tui")
+
+
+def _session(base: str, headers: dict, end_user: str) -> str:
+    r = httpx.post(f"{base}/sessions", json={"agent_id": AGENT, "end_user_id": end_user},
+                   headers=headers, timeout=30)
+    r.raise_for_status()
+    return r.json()["session_id"]
+
+
+def _drive(base: str, headers: dict, sid: str, content: str) -> tuple[str | None, list]:
+    """POST a turn; return (actual reference_knowledge query, served hits list)."""
+    q, hits = None, []
+    with httpx.stream("POST", f"{base}/sessions/{sid}/messages", json={"content": content},
+                      headers=headers, timeout=180) as r:
+        for line in r.iter_lines():
+            if not line.startswith("data: "):
+                continue
+            ev = json.loads(line[6:])
+            t = ev.get("type")
+            if t == "tool_start" and q is None:
+                q = (ev.get("arguments") or {}).get("query")
+            elif t == "tool_result" and not hits:
+                res = ev.get("result")
+                if isinstance(res, dict):
+                    hits = res.get("hits", res.get("results", [])) or []
+            elif t == "done":
+                break
+    return q, hits
+
+
+def _served_rank(hits: list, term_re: str) -> int | None:
+    """Rank of the first served hit whose excerpt literally contains the term (None = miss)."""
+    for i, h in enumerate(hits[:USABLE_K]):
+        if isinstance(h, dict) and re.search(term_re, h.get("excerpt", ""), re.I):
+            return i
+    return None
+
+
+def main() -> None:
+    ap = argparse.ArgumentParser()
+    ap.add_argument("--runs", type=int, default=1, help="repeats per message (samples query variance)")
+    ap.add_argument("--anchor", default=None, help="run only this anchor label")
+    args = ap.parse_args()
+    base, headers, end_user = _cfg()
+
+    anchors = [a for a in ANCHORS if args.anchor is None or a[0] == args.anchor]
+    totals = {"trials": 0, "miss": 0, "knife": 0}
+    by_kind: dict[str, dict] = {}
+
+    for label, kind, term_re, messages in anchors:
+        print(f"\n[{label}] ({kind})  term=/{term_re}/")
+        agg = by_kind.setdefault(kind, {"trials": 0, "miss": 0, "knife": 0})
+        for msg in messages:
+            for _ in range(args.runs):
+                sid = _session(base, headers, end_user)  # fresh session per trial
+                q, hits = _drive(base, headers, sid, msg)
+                rank = _served_rank(hits, term_re)
+                miss = rank is None
+                knife = rank is not None and rank >= KNIFE_EDGE_FROM
+                for d in (totals, agg):
+                    d["trials"] += 1
+                    d["miss"] += int(miss)
+                    d["knife"] += int(knife)
+                tag = "MISS" if miss else (f"knife@{rank}" if knife else f"ok@{rank}")
+                print(f"    {tag:9} msg={msg!r:42} q={q!r}")
+
+    def pct(n: int, d: int) -> str:
+        return f"{(100*n/d):.0f}%" if d else "n/a"
+
+    print("\n=== SUMMARY ===")
+    for kind, d in sorted(by_kind.items()):
+        print(f"  {kind:8} trials={d['trials']:3}  miss={pct(d['miss'], d['trials'])}  "
+              f"knife-edge={pct(d['knife'], d['trials'])}")
+    t = totals
+    print(f"  {'ALL':8} trials={t['trials']:3}  miss={pct(t['miss'], t['trials'])}  "
+          f"knife-edge={pct(t['knife'], t['trials'])}")
+    print("\nGate: stress-class miss-rate is the deciding signal for the rerank_hybrid_floor lever.")
+    print("Controls should sit at ~0% miss; a stress miss/knife-edge is the residual class to weigh.")
+
+
+if __name__ == "__main__":
+    main()

docs/diagnostics/temporal_order_gate.py

@@ -0,0 +1,132 @@
+"""Temporal-order gate — measures Worldtree #397 order_by="chapter" end-to-end.
+
+The gap #397 closes: narrative/temporal questions ("your first encounter", "what came
+after X", "earliest to latest") need CHRONOLOGICAL order, but reference_knowledge sorts by
+RELEVANCE by default. The fix is an `order_by="chapter"` tool flag (enum ["chapter"], taught
+in both tool schemas; the result packet carries `ordered_by="chapter"` and hits are reordered
+by source chapter, earliest first). Confirmed live on personal b184.
+
+This measures the flag END-TO-END (before/after per the #393 discipline) on three axes:
+  - ADOPTION: for a temporal query, does the agent actually invoke order_by="chapter"? (the
+    schema teaches it, but usage varies turn-to-turn — the #397 analog of query-formulation
+    variance).
+  - MECHANISM (flag applied): are the served hits' provenance.chapter monotonically
+    non-decreasing (earliest first)? Should be ~100% when the flag fires.
+  - VALUE (flag not applied): the relevance baseline — chapters are NOT chapter-sorted, which
+    is exactly the gap the flag closes. The applied-vs-not monotonicity gap IS the before/after.
+
+Self-contained (httpx only). Config from env (source env.sh first).
+  uv run --with httpx python docs/diagnostics/temporal_order_gate.py
+  uv run --with httpx python docs/diagnostics/temporal_order_gate.py --runs 4
+"""
+from __future__ import annotations
+
+import argparse
+import json
+import os
+
+import httpx
+
+AGENT = "ratatoskr:donut"
+
+# Narrative/temporal user messages — the class the order_by="chapter" flag targets.
+TEMPORAL_MSGS = [
+    "What was your very first encounter in the dungeon?",
+    "What happened when you first entered the dungeon, earliest to latest?",
+    "In order from the start, how did things unfold between you and Carl?",
+    "Walk me through your earliest days in the dungeon, oldest first.",
+    "After your first fight, what came next?",
+]
+
+
+def _cfg() -> tuple[str, dict, str]:
+    base = os.environ.get("WORLDTREE_API_URL", "http://10.250.50.152:8081")
+    key = os.environ.get("WORLDTREE_API_KEY")
+    if not key:
+        raise SystemExit("WORLDTREE_API_KEY unset — source env.sh first.")
+    return base, {"Authorization": f"Bearer {key}"}, os.environ.get("RATATOSKR_END_USER_ID", "ratatoskr-tui")
+
+
+def _session(base: str, headers: dict, end_user: str) -> str:
+    r = httpx.post(f"{base}/sessions", json={"agent_id": AGENT, "end_user_id": end_user},
+                   headers=headers, timeout=30)
+    r.raise_for_status()
+    return r.json()["session_id"]
+
+
+def _drive(base: str, headers: dict, sid: str, content: str) -> tuple[dict, dict]:
+    """POST a turn; return (tool_start arguments, tool_result dict)."""
+    args, result = {}, {}
+    with httpx.stream("POST", f"{base}/sessions/{sid}/messages", json={"content": content},
+                      headers=headers, timeout=180) as r:
+        for line in r.iter_lines():
+            if not line.startswith("data: "):
+                continue
+            ev = json.loads(line[6:])
+            t = ev.get("type")
+            if t == "tool_start" and not args:
+                args = ev.get("arguments") or {}
+            elif t == "tool_result" and not result:
+                result = ev.get("result") if isinstance(ev.get("result"), dict) else {}
+            elif t == "done":
+                break
+    return args, result
+
+
+def _chap_num(c: object) -> int:
+    """Chapter as an orderable int; non-numeric (e.g. 'EPILOGUE') sorts last."""
+    try:
+        return int(str(c))
+    except (TypeError, ValueError):
+        return 10**9
+
+
+def _is_monotone(chapters: list) -> bool:
+    nums = [_chap_num(c) for c in chapters if c is not None]
+    return all(a <= b for a, b in zip(nums, nums[1:])) if len(nums) >= 2 else True
+
+
+def main() -> None:
+    ap = argparse.ArgumentParser()
+    ap.add_argument("--runs", type=int, default=2, help="repeats per message (samples adoption variance)")
+    args = ap.parse_args()
+    base, headers, end_user = _cfg()
+
+    applied = {"trials": 0, "monotone": 0}   # flag fired
+    unapplied = {"trials": 0, "monotone": 0}  # flag did NOT fire (relevance baseline)
+    adopted_n = 0
+    total = 0
+
+    for msg in TEMPORAL_MSGS:
+        print(f"\nMSG: {msg!r}")
+        for _ in range(args.runs):
+            sid = _session(base, headers, end_user)
+            targs, res = _drive(base, headers, sid, msg)
+            hits = res.get("hits", res.get("results", [])) or []
+            chapters = [(h.get("provenance") or {}).get("chapter") for h in hits if isinstance(h, dict)]
+            adopted = targs.get("order_by") == "chapter"
+            applied_flag = res.get("ordered_by") == "chapter"
+            mono = _is_monotone(chapters)
+            total += 1
+            adopted_n += int(adopted)
+            bucket = applied if applied_flag else unapplied
+            bucket["trials"] += 1
+            bucket["monotone"] += int(mono)
+            tag = "FLAG" if applied_flag else "----"
+            print(f"    [{tag}] adopted={adopted!s:5} monotone={mono!s:5} chapters={chapters}")
+
+    def pct(n: int, d: int) -> str:
+        return f"{(100*n/d):.0f}%" if d else "n/a"
+
+    print("\n=== SUMMARY ===")
+    print(f"  adoption (agent invoked order_by=chapter): {pct(adopted_n, total)}  ({adopted_n}/{total})")
+    print(f"  flag APPLIED   -> chapter-monotone: {pct(applied['monotone'], applied['trials'])}  "
+          f"(n={applied['trials']})   [mechanism — should be ~100%]")
+    print(f"  flag NOT applied -> chapter-monotone: {pct(unapplied['monotone'], unapplied['trials'])}  "
+          f"(n={unapplied['trials']})   [relevance baseline — the gap the flag closes]")
+    print("\nGate: the applied-vs-not monotonicity gap is the flag's VALUE; adoption rate is the")
+    print("residual (schema teaches it, agent use varies) — the #397 analog of query-formulation variance.")
+
+
+if __name__ == "__main__":
+    main()

docs/vendor/brokkr-r34-psych-profile/psych-profile-authoring-spec.md

@@ -0,0 +1,242 @@
+# Psychological Profile Authoring Spec — canonical
+
+**Status:** canonical (v1). **Owner:** brokkr-smithy-dev (R34/R35 self-report reframe).
+**Audience:** anyone authoring a character's `psychological_profile` — Worldtree
+foundational characters (soong-dev) and consumer characters created via the
+Conversation API (ratatoskr and other external consumers).
+**For:** the Worldtree agent-definition schema; intended to live in the Worldtree
+client-app documentation.
+
+This spec governs the **content** of the psychological profile (what to write and
+what never to write). The **physical wire shape** of the field (single string vs a
+small keyed dict) is Worldtree's schema call — see § Wire shape.
+
+---
+
+## 1. What it is
+
+A dedicated **authored prose section** of a character definition that carries the
+character's **psychological bent and formative experience**. It is the source the
+self-report producer maps from when it decides, on each turn:
+
+- **what the character feels** (affect self-report), and
+- **what the character notices and keeps** (character-voiced memory salience).
+
+The profile is a *lens*, not a script. It never states per-turn emotions; it
+describes the standing disposition, history, values, and attention that — combined
+with the actual event — *produce* the emotion and the salience.
+
+It sits **alongside the numeric OCEAN** values (a separate, deterministic input).
+The prose gives the *qualitative* bent; the OCEAN numbers give the *magnitude dial*
+(see § OCEAN interaction).
+
+---
+
+## 2. What it carries — the four dimensions
+
+1. **Disposition / appraisal bent** — how the character characteristically
+   *interprets* situations: attribution style, what they hold weighty, how they
+   respond to being challenged. NOT per-event emotions.
+2. **Attention / salience focus** — the kinds of things this character
+   characteristically *notices* (and therefore tends to remember).
+3. **Values / what a good day looks like** — the yardstick that drives what they
+   find worth keeping.
+4. **Formative experience (history)** — the background that shapes both appraisal
+   *and* salience. A character betrayed before appraises betrayal differently, and
+   remembers different things.
+
+You may write these as four short labelled sections or as one integrated paragraph
+— both are supported (see § Length & format).
+
+---
+
+## 3. Authoring rules (load-bearing)
+
+These are the rules the whole reframe depends on. Rule 1 is the one that most often
+gets violated.
+
+1. **Never name a per-event output emotion.** Do NOT write "is anxious", "gets
+   angry at X", "feels hurt when criticized", "joyful". Naming an emotion **primes**
+   it — the "pink ball" effect — so the producer will report that emotion regardless
+   of what actually happens in the scene. Describe *disposition, history, values,
+   attention*; let the emotion come from the event appraisal.
+   - ✅ "Registers quickly when authority is substituted for craft." (an appraisal
+     trigger — sets up how she reads an event, names no feeling)
+   - ❌ "Feels contempt when someone pulls rank." (names the output emotion)
+
+2. **Magnitude lives in the numeric OCEAN, not the prose.** *How strongly / how
+   long* a character reacts (Neuroticism) is the deterministic OCEAN dial, rendered
+   valence-neutral by the producer. Do not narrate reaction dynamics in the prose
+   ("comes apart", "takes it hard", "rich inner life") — that double-encodes what the
+   number already carries. The prose gives the *qualitative bent*; the number gives
+   the *gain*.
+
+3. **Appraisal-style is allowed; output-emotion is not.** "Interprets others'
+   actions charitably until she can't" (a style) is fine; "feels betrayed easily"
+   (an output) is not. The style plus the event produce the output.
+
+4. **Salience is character-relative; facts are not.** The profile shapes what the
+   character *cares to remember*. It must never license rewriting *what happened* —
+   when the character does remember something, it stays grounded in the transcript.
+
+---
+
+## 4. Wire shape & field placement
+
+- **Content is prose** covering the four dimensions, authored as **one coherent prose
+  string** — the four dimensions are authoring *structure* inside that single string,
+  not separate wire fields.
+- **Wire shape (LOCKED, b53):** a single dedicated prose string, field
+  **`psychological_profile`** (type `str`) on the persona layer — foundational
+  `persona.psychological_profile`, Tier-3 `ValidatedPersona.psychological_profile`. It
+  nests under the existing `Any`-typed persona field, so it is the shipped b53 shape —
+  no schema change. **Not** a dict-of-four.
+- **Hard constraint (non-negotiable):** the profile is a **dedicated field the lens
+  reads ONLY** (`resolve_psych_profile` reads only this field — no `behavioral_notes`
+  or other general-field remap). Non-lens content leaking into the lens produces the
+  "executive-assistant" failure (the producer reads response-format / tone / tool
+  instructions as if they were the character's psychology).
+
+---
+
+## 5. The non-priming banned set
+
+The non-priming rule (Rule 1) is **semantic, not a fixed wordlist** — it bans naming
+any per-event output emotion, which is broader than any specific vocabulary
+("anxious", "worried", "hurt" all prime even though they are not in the producer's
+fixed emotion roster).
+
+- **The gate is human review:** does the prose describe disposition / appraisal-style
+  / history / values / attention, and never what the character *feels*?
+- **A mechanical lint is a backstop, not the gate.** If you build one, scan the
+  fixed-15 OCC roster plus `synonym_map.json` (which already folds common affect
+  synonyms) as the core set, optionally extended with a general affect lexicon. Treat
+  a lint hit as a prompt to re-read, not an automatic reject.
+
+---
+
+## 6. Required vs optional dimensions
+
+- **Required** (they *are* the lens): **disposition**, **attention / salience focus**,
+  **values**.
+- **Strongly recommended:** **formative history** — it is the single biggest lever on
+  richness (validated in P03: richer history → sharper, more character-appropriate
+  salience). It may be brief for a deliberately thin character, but omitting it leaves
+  salience under-grounded.
+
+---
+
+## 7. Length & format
+
+- A focused paragraph, or four short labelled sections — **a lens, not a biography.**
+- Target **~150–300 words.** The producer reads this on **every** turn, so keep it
+  tight; bloat is a latency and dilution cost.
+- **Prose only — never typed emotion fields.** The four dimensions are a coverage
+  checklist for the author, not a schema of feelings to fill in.
+
+---
+
+## 8. Exemplars
+
+These three were the validated P03 stimuli — integrated-paragraph form, each faithful
+to its OCEAN, none naming an output emotion. (OCEAN shown in **[−1, 1] storage units**;
+validated in P03 at the equivalent [0, 1] values.)
+
+**Perrin — court scribe** (OCEAN: O0.0 C0.2 E−0.2 A0.1 N0.7)
+> Perrin keeps the court's records and has done so through two changes of regime. He
+> learned early that small errors compound — a misfiled writ once cost a man his
+> lands, and Perrin found the mistake too late to undo it. Since then he double-checks
+> everything and watches situations closely for what is out of place. He forms
+> attachments slowly and holds a given trust as a considerable thing. He measures
+> himself by whether he was useful and careful. He notices discrepancies, unspoken
+> tensions, and anything that threatens the order he keeps.
+
+**Vared — veteran caravan guard** (OCEAN: O−0.2 C0.4 E−0.5 A−0.2 N−0.7)
+> Vared has guarded caravans across the northern routes for twenty years and buried
+> more traveling companions than he cares to count. He speaks little and shows less.
+> Danger he treats as weather — a thing to be handled. He judges people by what they
+> do under pressure and remembers who held the line. What reaches him reaches him
+> quietly and privately. He notices terrain, exits, who is armed, and shifts in a
+> group that might precede trouble.
+
+**Sella — village healer** (OCEAN: O0.2 C0.2 E0.0 A0.8 N0.0)
+> Sella has tended the sick since she was old enough to carry water for her
+> grandmother, the healer before her. She reads people's pain quickly and carries some
+> of it with her. She interprets others' actions charitably until she cannot, and
+> prioritizes keeping the peace between people. She measures a day by whether she eased
+> someone's burden. She notices who is unwell, who is troubled, and what is left
+> unsaid.
+
+Note how each closes on **attention** ("he notices…", "she notices…") — the salience
+focus stated plainly, no emotion named.
+
+---
+
+## 9. OCEAN interaction & the scaffold fallback
+
+OCEAN values are stored on **[−1, 1]** (0 = average) — a **separate deterministic
+input** and the **magnitude dial** the prose must not duplicate (Rule 2). The producer
+renders **off-average** bands as valence-neutral disposition cues. It maps storage to
+[0, 1] first (`c = (v + 1) / 2`, `render_disposition` in b53) and then applies the
+canonical [0, 1] band cutoffs (`c < 0.33` low / `c > 0.66` high). In **storage units**
+that is:
+
+| trait | low (v < −0.34) | high (v > +0.32) |
+|---|---|---|
+| **N** (reactivity only) | reactions are milder than most people's | reactions are more intense than most people's |
+| **E** (expression; may be excluded from affect elicitation) | socially reserved; expression less outwardly amplified | socially expressive; reactions more externally visible |
+| **O** | prefers the familiar, the concrete, established ways | curious, drawn to novelty, ideas, the unfamiliar |
+| **C** | less plan-bound; less weight on order, detail, obligation | attends closely to order, detail, and obligations |
+| **A** | less inclined to assume cooperative intent; direct, self-protective | more inclined to preserve rapport and weigh others' needs |
+
+The **mid** band (−0.34 ≤ v ≤ +0.32, i.e. `c` in [0.33, 0.66]) renders nothing — an
+average trait is silent, **not** "low." (Boundaries are slightly asymmetric because
+the canonical 0.33/0.66 cutoffs are not symmetric about 0.5. Canonical rendering
+strings live in the reframe language catalog §4; persistence/recovery dynamics live in
+the deterministic mood decay, not the profile.)
+
+**Scaffold fallback:** a character with **no** authored profile falls back to this
+band-rendering from the OCEAN numbers alone. That still functions — but the authored
+profile is what turns generic band cues into *this specific character's* appraisal and
+salience. Authoring the profile is how the reframe's value actually reaches a
+character.
+
+---
+
+## 10. Authoring divergent characters (contrast design)
+
+When you want two characters to remember **noticeably different things** (e.g. for an
+eval contrast pair, or simply a varied cast), design the divergence on the **attention
+and values** dimensions first, and set the OCEAN numbers to *serve* that prose — not
+the reverse.
+
+- **The sharpest contrast is a salience *drop*, not just a different flavor.** One
+  character for whom relational/emotional content is genuinely non-salient (an
+  operational, task-focused character in the Vared mold — notices terrain, logistics,
+  who is armed) versus one who weights it highest (a caretaker who tracks who is
+  troubled and what went unsaid). "Different notes, same facts" has real teeth only
+  when one character *legitimately forgets* what the other keeps.
+- **High-yield axes for salience divergence:** O (what patterns they attend to), A
+  (relational vs operational/self-protective focus), C (procedural/detail salience).
+- **Low-yield for salience:** E — it is expression-oriented (shapes how a reaction is
+  *rendered*, not what is *noticed*), and may even be excluded from the affect
+  elicitation. Don't lean on flipping E to create divergence.
+- **Watch the direction, not just the distance:** flipping every OCEAN axis to its
+  opposite does not guarantee a strong contrast. If your reference character already
+  *keeps* relational content, an even-more-agreeable opposite keeps it harder and the
+  most intuitive contrast collapses. Aim the contrast at *dropping* what the reference
+  *keeps*.
+
+---
+
+## Provenance & validation
+
+Grounded in R34/R35 (self-report reframe), probes P02–P05: character-voiced memory
+salience validated on two model classes (P02/P03); the "Psychological Profile and
+Experience" section mapping validated as the lens source (P03); non-priming and
+magnitude-in-OCEAN corrections are operator rulings (2026-07-10). The affect half is
+live in production (Worldtree b53) and fired a contextually-apt self-report on a
+non-frontier seat. A powered efficacy eval (salience divergence / floor recall /
+salience≠facts firewall / graded model-slot response + the authored-vs-scaffold delta)
+is preregistering to quantify the memory half; findings will refine this spec, not
+overturn its authoring rules.

docs/vendor/brokkr-r34-psych-profile/psych-profile-parameters.md

@@ -0,0 +1,123 @@
+# Psychological Profile Parameters — for AI generation (canonical)
+
+**Status:** canonical (v1). **Owner:** brokkr-smithy-dev (R34/R35 self-report reframe).
+**Audience:** **soong-dev** (Soong's Lab / Soong's AI — the immediate builder that
+generates the profile from these parameters); **Worldtree** + **ratatoskr** (vendoring
+for reference alongside the authoring spec).
+**Relationship:** this is the **parameter distillation** of
+`psych-profile-authoring-spec.md` for the model where **Soong's AI writes the
+`psychological_profile` prose from parameters** (rather than a human hand-authoring it).
+The authoring spec carries the full reasoning + provenance and **governs on any
+conflict**; this file is the builder-facing input schema + generation guardrails + few-shot.
+
+The profile is the prose **lens** the Worldtree self-report producer reads each turn to
+decide what the character **feels** (affect self-report) and what it **notices / keeps**
+(character-voiced memory salience). Soong's AI generates the prose; these are its inputs
+and the constraints its output must satisfy.
+
+---
+
+## 1. Input parameters (what the Lab collects / Soong's AI takes)
+
+1. **role / vocation** — a short anchor ("court scribe", "veteran caravan guard",
+   "village healer").
+2. **OCEAN values** — O, C, E, A, N each on **[−1, 1]** (0 = average). A **separate
+   deterministic input** the producer uses directly (the "magnitude dial"); Soong's AI
+   should see them to keep the qualitative bent *consistent* with the numbers, but must
+   **not re-encode their magnitude** in the prose (constraint 2).
+3. **formative-history seed** — 1–2 key background facts/events that shape appraisal AND
+   salience. **Single biggest lever on richness** (validated P03: richer history →
+   sharper, more character-appropriate salience).
+4. **appraisal-bent seed** — how the character characteristically **interprets**
+   situations (attribution style, what they hold weighty, how they respond to challenge).
+   A *style*, NOT an emotion.
+5. **attention / salience-focus seed** — the kinds of things this character
+   characteristically **notices** (and therefore keeps). Load-bearing for the memory half.
+6. **values / yardstick seed** — what "a good day" looks like; the yardstick driving what
+   they find worth keeping.
+
+## 2. Output (what Soong's AI emits)
+
+A single coherent **prose string** (~150–300 words), field **`psychological_profile`**
+(type `str`) — the four dimensions (disposition / attention / values / formative-history)
+integrated as one paragraph. **Prose only — never typed emotion fields.** The producer
+reads it every turn, so keep it tight.
+
+## 3. Generation constraints (the guardrails the output MUST obey — these ARE the reframe)
+
+1. ★ **Never name a per-event output emotion.** Do NOT write "is anxious", "gets angry at
+   X", "feels hurt when criticized", "joyful". Naming an emotion **primes** it (the
+   "pink-ball" effect) so the producer reports it regardless of what actually happens.
+   Describe disposition / history / values / attention; let the emotion come from the
+   event appraisal.
+   - ✅ "Registers quickly when authority is substituted for craft." (appraisal trigger)
+   - ❌ "Feels contempt when someone pulls rank." (names the output emotion)
+2. **Magnitude lives in OCEAN, not prose.** Don't narrate reaction dynamics ("comes
+   apart", "takes it hard", "rich inner life") — that double-encodes what the number
+   already carries.
+3. **Appraisal-style yes; output-emotion no.** "Interprets others' actions charitably
+   until she can't" (style) = fine; "feels betrayed easily" (output) = not.
+4. **Salience is character-relative; facts are not.** The profile shapes what the
+   character *cares to remember*; it must never license rewriting *what happened* —
+   remembered content stays grounded in the transcript.
+5. **Close on attention** ("...notices who is unwell, who is troubled, what is left
+   unsaid") — state the salience focus plainly.
+
+## 4. Few-shot exemplars (validated P03 — OCEAN in [−1, 1] storage units → emitted prose)
+
+**Perrin, court scribe** (O0.0 C0.2 E−0.2 A0.1 N0.7)
+> Perrin keeps the court's records and has done so through two changes of regime. He
+> learned early that small errors compound — a misfiled writ once cost a man his lands,
+> and Perrin found the mistake too late to undo it. Since then he double-checks
+> everything and watches situations closely for what is out of place. He forms
+> attachments slowly and holds a given trust as a considerable thing. He measures himself
+> by whether he was useful and careful. He notices discrepancies, unspoken tensions, and
+> anything that threatens the order he keeps.
+
+**Vared, veteran caravan guard** (O−0.2 C0.4 E−0.5 A−0.2 N−0.7)
+> Vared has guarded caravans across the northern routes for twenty years and buried more
+> traveling companions than he cares to count. He speaks little and shows less. Danger he
+> treats as weather — a thing to be handled. He judges people by what they do under
+> pressure and remembers who held the line. What reaches him reaches him quietly and
+> privately. He notices terrain, exits, who is armed, and shifts in a group that might
+> precede trouble.
+
+**Sella, village healer** (O0.2 C0.2 E0.0 A0.8 N0.0)
+> Sella has tended the sick since she was old enough to carry water for her grandmother,
+> the healer before her. She reads people's pain quickly and carries some of it with her.
+> She interprets others' actions charitably until she cannot, and prioritizes keeping the
+> peace between people. She measures a day by whether she eased someone's burden. She
+> notices who is unwell, who is troubled, and what is left unsaid.
+
+## 5. Validation
+
+The gate is: **does the prose describe disposition / appraisal-style / history / values /
+attention, and NEVER what the character feels?** A mechanical lint (scan the fixed-15 OCC
+emotion roster + Worldtree's `synonym_map.json`) is a **backstop, not the gate** — treat a
+hit as a prompt to re-read, not an auto-reject.
+
+## 6. Designing a varied cast / contrast (optional)
+
+When two characters should remember **noticeably different things**: design the divergence
+on **attention + values first**, then set OCEAN to **serve** that prose (not the reverse).
+The sharpest contrast is a salience **drop** — one character for whom relational content is
+genuinely non-salient (a Vared-mold operational type: notices terrain, logistics, who is
+armed) vs one who weights it highest (a caretaker: tracks who is troubled, what went
+unsaid). *"Different notes, same facts" only has teeth when one character legitimately
+forgets what the other keeps.* High-yield axes: **O** (patterns attended), **A** (relational
+vs operational), **C** (procedural/detail). Low-yield: **E** (expression, not attention).
+Watch **direction, not just distance** — flipping every axis doesn't guarantee contrast (an
+even-more-agreeable opposite keeps relational content *harder*).
+
+## 7. No-profile fallback
+
+A character with **no** authored profile falls back to deterministic **OCEAN-band
+rendering** from the numbers alone — it still functions, but the authored profile is what
+turns generic band cues into *this* character's appraisal and salience.
+
+---
+
+**Provenance:** derived from `psych-profile-authoring-spec.md` (R34/R35 self-report
+reframe, probes P02–P05; non-priming + magnitude-in-OCEAN are operator rulings 2026-07-10).
+The affect half is live in Worldtree b53. A powered efficacy eval (memory half) is
+preregistering; findings will refine the parameters, not overturn the constraints.

docs/vendor/soong-lab-bundle/export.contract.md

@@ -0,0 +1,372 @@
+---
+contract_version: "2.1"
+module: "soong_lab.export"
+purpose: "Assemble a versioned export BUNDLE from a DesignObject — the native agents.define payload (Frame Invariant 1, emitted unchanged) + the soong-lab sidecar (portrait ref · Bifrost tool manifest · first_message) + the resume half (the full editable design state), under a versioned schema tolerant of unknown future metadata. Pure + deterministic: no I/O, no persistence, no network (library persistence + import are separate downstream epics)."
+depends_on:
+  - "soong_lab.design"      # validate_ocean + ROLE_CHOICES/validate_role (the role enum canon) + the DesignObject model + serialize_design (relocated here — see Integration points R1)
+used_by:
+  - "soong_lab.bifrost"     # the export design-tool handler (_make_export) builds the bundle for the session's design
+  - "soong_lab.web"         # the /api/export endpoint + the browser 'Export Asset' modal render the bundle
+  - "soong_lab.importer"     # FUTURE (import epic) — round-trips the resume half back into a DesignObject
+language: "python"
+complexity: "medium"
+estimated_loc: 200
+confidence: 0.82
+assumptions:
+  - "The DesignObject handed to export is already mutated to its final state by E3 (the Soong convo loop). Export READS it; it never mutates the design (INV-E5-4)."
+  - "design_id is CALLER-SUPPLIED (a param), not generated here. Its generation + lifecycle (the durable library key, ≠ Worldtree session_id) is the per-design-sessions epic; export only needs the value to stamp the bundle. This keeps E5-export self-contained + forward-compatible with per-design-sessions landing before OR after it (agent-discretion, see open_question C)."
+  - "exported_at is CALLER-SUPPLIED (a param, default None). Pure builders can't read the clock; the caller (tool handler / endpoint) stamps the timestamp so build_export_bundle stays deterministic + testable (byte-identical output for identical inputs)."
+  - "role is a FIRST-CLASS design field (operator ruling 2026-07-13), set by the E3a set_role tool from a CURATED 4-value enum ROLE_CHOICES = {assistant, thoughtful-assistant, character, thoughtful-character} — mirroring the D2 curated-style-modes pattern (a fixed semantic set, NOT the target deployment's arbitrary model-role registry). Export EMITS design.role into ship.native.role, so the native payload is directly valid (Frame Invariant 1 now holds literally — no 'modulo role' caveat; only tools still bind separately at session-create). The 4 enum values are canonical soong-lab labels that map to WT model-role slugs. open_question B RESOLVED (2026-07-14, worldtree-dev via ratatoskr-dev): the 4 labels ARE WT slugs by EXACT name (1:1, no remap) — assistant/thoughtful-assistant under the `foundational` grant (gen / gen-reasoning seats), character/thoughtful-character under the `character` grant (char-rp / char-rp-reasoning seats). So ship.native.role is directly define-valid; the only deploy concern is that the CONSUMER's key must hold the matching grant (define 403s otherwise — same model.use requirement as Soong's own 'agent_architect', ADR-0012). Not a contract blocker."
+  - "psych_profile exports to the NATIVE persona layer at persona.psychological_profile. RESOLVED: the vendored canonical spec (docs/psych-profile-authoring-spec.md §4) states the wire shape is LOCKED (b53) — a single prose str field, Tier-3 ValidatedPersona.psychological_profile, nesting under the existing Any-typed persona field (no schema change). Corroborated by worldtree-codex (vor-cross) + brokkr-smithy-dev (althing 01KXD34ZTF…). The open worldtree-dev thread (01KXD1PZR7…) closes as a formality."
+open_questions:
+  - "[B — deploy grounding, not a blocker] The 4 ROLE_CHOICES values (assistant / thoughtful-assistant / character / thoughtful-character) must be registered + grantable model-role slugs on the TARGET Worldtree (like Soong's own agent_architect role). Confirm with worldtree-dev/infra that these exact slugs exist on the deploy target before shipping; a missing slug fails the designed agent's session-create, not export. Export emits whatever role the design holds; validity of the slug on a given deployment is a deploy concern."
+  - "[C — agent-discretion, notable] design_id as a caller-supplied param (drafted) vs E5-export generating it. Drafted as an input so E5-export doesn't force per-design-sessions to land first. If the operator re-sequences the epics so per-design-sessions lands first, no change needed here (the param source just moves)."
+  - "[D — scope] E5-export = the PURE builders + validators + bundle schema (this contract). The /api/export endpoint + replacing the web/api.js exportBundle shim = a thin web-surface follow-up (amends web_surface.contract.md), NOT this contract. The Bifrost export-tool wiring IS in scope (Integration points) because the tool already exists as a stub. The set_role tool + DesignObject.role field are a companion prerequisite slice (Integration points) whose contract updates land in THIS pass (design_object + bifrost_server)."
+  - "schema_version starts at '1.0'. The version bump policy on future bundle-shape changes (add-only vs breaking) is deferred to when the second version actually exists — v1 only needs the field present + readers to tolerate unknown metadata (INV-E5-6)."
+---
+
+## Context
+
+E5-export is the FOUNDATION half of the operator-accepted (2026-07-13)
+export/import/library design — the block that expands the locked single-agent
+frame into a multi-pass tuning loop (design → export → reopen → tune → keep a
+library). This contract owns exactly ONE thing: turning a finished
+`DesignObject` into a **versioned export bundle**. Persistence (the library JSON
+dir), the recent-designs picker, and import round-tripping are separate
+downstream epics; export is pure and deterministic so those epics — and the
+tests — can build on a stable, side-effect-free core.
+
+**The bundle is ONE artifact with two halves** (settled decision #4):
+
+- **ship** — what you hand to a deployment: the native `agents.define` payload
+  (Frame Invariant 1, emitted unchanged) + the soong-lab **sidecar** (persona
+  portrait ref, the Bifrost tool manifest, the D3 first_message).
+- **resume** — what you reopen to keep tuning: the full editable design state
+  (the §6 DesignObject serialization), so a future import reconstructs the
+  DesignObject exactly.
+
+Plus a stable **`design_id`** (the durable library key, ≠ Worldtree
+`session_id`) and a **`schema_version`**, both at the top level.
+
+**Frame Invariant 1 is preserved — and now holds literally.** `ship.native` is a
+valid Worldtree Tier-3 `agents.define` payload assembled from `agent_name` + the
+designed agent's **`role`** (the model-role, resolved below) + the AUTHORED
+`system_prompt` (INV-E2-2 — never `composed_preview`) + `persona.ocean`
+(Worldtree renders affect at runtime) + `persona.psychological_profile` (the
+native home, LOCKED b53 per the vendored spec §4) + `motivational` (from
+goals_fears). The image and tools are NOT in the native schema — they ride the
+sidecar (tools bind via Bifrost at session-create, exactly as grounded).
+
+**The `role` resolution (operator ruling 2026-07-13).** The blast-radius pass
+caught that `agents.define` requires `role` (a model-role slug, ADR-0012) but the
+design had no source for it. Resolution: **role is a first-class design field**,
+set by a new E3a **`set_role`** tool from a **curated 4-value enum** —
+`assistant` (general LLM), `thoughtful-assistant` (CoT general),
+`character` (RP/writing-tuned), `thoughtful-character` (CoT RP). This mirrors the
+D2 curated-style-modes decision: a fixed semantic set the operator picks from,
+NOT a coupling to any one deployment's arbitrary role registry. Export emits
+`design.role`, so the native payload is directly POST-valid (modulo the tool
+binding every consumer already supplies at session-create). The one deploy-time
+caveat: the 4 slugs must be granted on the target Worldtree (open_question B).
+
+**The psych field is RESOLVED (no longer quarantined).** Vendored spec §4 locks
+`persona.psychological_profile` (prose `str`, ~150–300 words, read every turn),
+nesting under the `Any`-typed persona layer. Export maps `design.psych_profile`
+there and NOWHERE else — spec §4's hard constraint is that the self-report lens
+reads ONLY this field (leaking psych prose into `behavioral_notes`/`system_prompt`
+causes the "executive-assistant" failure).
+
+## Data flow
+
+**In:** a `DesignObject` (final, from E3) + a caller-supplied `design_id` (str)
++ an optional caller-supplied `exported_at` (str | None). **Out:** a plain
+JSON-ready `dict` — the versioned bundle. **On disk / network:** NONE. Export is
+pure: the OCEAN parity gate (`validate_ocean`), the role-enum gate
+(`validate_role`), and the export-critical validators are in-memory; timestamps +
+ids come in as params; no clock, no randomness, no file, no HTTP. (Library
+persistence writes the returned dict to the JSON dir — that is the library epic,
+not this module.)
+
+### Export bundle schema (v1.0)
+
+```
+{
+  "schema_version": "1.0",                 # ALWAYS EXPORT_SCHEMA_VERSION — not a caller param
+  "design_id": "<caller-supplied durable library key, ≠ WT session_id>",
+  "exported_at": <caller-supplied OPAQUE str | null — conventionally ISO-8601, NOT validated by export>,
+  "ship": {
+    "native": {                       # a valid agents.define payload (Frame Invariant 1)
+      "agent_name": <str, non-blank, ≤128>,
+      "role": <one of ROLE_CHOICES: assistant|thoughtful-assistant|character|thoughtful-character>,
+      "system_prompt": <str, non-blank, ≤32768 — the AUTHORED block, INV-E2-2>,
+      "persona": {
+        "ocean": {O,C,E,A,N},         # each a real number in [-1,1] (validate_ocean parity)
+        "psychological_profile": <str>   # persona.psychological_profile (LOCKED b53); included iff non-blank
+      },
+      "motivational": {                          # WT #187 OBJECTS, not strings (ratatoskr-dev bug 2026-07-16); iff goals_fears present + non-empty
+        "goals": [{"id": "goal-N", "type": <maintenance|achievement|avoidance>, "salience": <0..1>, "description": <str>=20 chars>}],
+        "fears": [{"id": "fear-N", "salience": <0..1>, "description": <str >=20 chars>}]
+      }   # `id` synthesized at export (goal-N/fear-N, unique across both); validate_exportable gates description>=20 / type∈GOAL_TYPES / salience∈[0,1]
+    },
+    "sidecar": {
+      "portrait": <image ref str | null>,   # only when portrait.status == "ready"; E4 owns generation
+      "tools": [{"id","name","description"}],# the Bifrost tool manifest (bind at session-create)
+      "first_message": <str>                 # the D3 opening turn (issue #347 seed)
+    }
+  },
+  "resume": { <the §6 camelCase editable state — key set inlined below> }
+}
+```
+
+**The `resume` key set (inlined — heid-review fold Gróa #9).** The resume half IS
+`serialize_design(design)` (relocated to `soong_lab.design`, R1), but its key set is
+pinned HERE so this contract is self-contained and an implementer knows the exact
+round-trip surface without reading the external, being-relocated function:
+
+```
+resume = {
+  "agentName", "role", "systemPrompt", "composedPreview", "firstMessage",
+  "ocean" {O,C,E,A,N}, "dispositionPhrase", "psychProfile",
+  "tools" [{id,name,description}], "portrait" {status, styleMode, imageUrl?, jobId?},
+  "goalsFears" {goals,fears} | null
+}
+```
+
+Import reconstructs a DesignObject from exactly these keys. `role` (new, R1) MUST be
+present so a reopened design carries its model-role. (`composedPreview` +
+`dispositionPhrase` are design-time-derived and re-derivable, but they ride the resume
+so a reopen renders instantly before the first recompute.)
+
+**Divergences from the imported web mock (settled here, they were UI-comp
+shortcuts):**
+
+| Field | Mock (web/*.js) | Real export (this contract) |
+|---|---|---|
+| native shape | `{name, tier, system_prompt, personality:{model,values}}` | real `agents.define` (`agent_name`/`role`/`persona.ocean`/`motivational`) |
+| role | absent | `design.role` ∈ ROLE_CHOICES |
+| system_prompt | `composedPreview` (mockApi) | authored `system_prompt` (INV-E2-2) |
+| psychProfile | omitted ("open backend decision") | `persona.psychological_profile` (LOCKED b53) |
+| bundle identity | none | `design_id` + `schema_version` |
+| resume half | none | full `serialize_design` state |
+
+## Invariants
+
+- **INV-E5-1** [hard]: `ship.native` is a valid Worldtree `agents.define` payload
+  MODULO the tool binding — it carries every required field (`agent_name`,
+  `role`, `system_prompt`) + `persona.ocean`, and OMITS only the tools (they bind
+  via Bifrost at session-create, as they already do). Any `persona.ocean` export
+  emits passes `validate_ocean`; `role` is always one of ROLE_CHOICES.
+  `persona.psychological_profile` + `motivational` are OPTIONAL native fields
+  (grounded) — omitting them when blank/empty keeps the payload fully valid, not
+  merely "valid enough" (heid-review fold, Gróa #1).
+- **INV-E5-2** [hard]: The exported `system_prompt` is the AUTHORED
+  `design.system_prompt`, NEVER `composed_preview` (binds with INV-E2-2). The
+  **disposition line** — the `"Disposition: <name> is <phrase>."` sentence that
+  E2 `recompute` appends to `composed_preview` (design_object.contract.md POST-E2-5)
+  — is design-time-only and never ships.
+- **INV-E5-3** [hard]: Export is pure + deterministic — identical
+  `(design, design_id, exported_at)` inputs yield a byte-identical serialized
+  bundle. No clock, no randomness, no I/O. The determinism is WITHIN the module:
+  the returned dict has a fixed key insertion order (schema_version, design_id,
+  exported_at, ship, resume; native + sidecar likewise), so any consistent
+  `json.dumps` settings produce byte-identical output — the invariant does NOT
+  claim cross-implementation byte-identity (heid-review fold, Regin #6).
+- **INV-E5-4** [hard]: Export NEVER mutates the input `DesignObject` (read-only);
+  the bundle holds copies, not aliases, of every mutable sub-structure (ocean
+  dict, tool list, goals/fears lists) so a later design mutation can't change an
+  already-built bundle.
+- **INV-E5-5** [hard]: `validate_exportable` is the strict export-critical gate
+  (decision #6): OCEAN (via `validate_ocean`), role (∈ ROLE_CHOICES via
+  `validate_role`), agent_name (non-blank, ≤128), system_prompt (non-blank,
+  ≤32768), tool-refs (id/name non-blank + bounded). A design that fails ANY of
+  these raises `ExportError` and NO bundle is produced — a built bundle is always
+  well-formed enough to round-trip on import.
+- **INV-E5-6** [hard]: The bundle carries `schema_version` at the top level, and
+  readers (import, future) MUST tolerate unknown extra keys (lenient on unknown
+  metadata, decision #6) — the schema is add-only-friendly.
+- **INV-E5-7** [hard]: `psych_profile` maps to `persona.psychological_profile`
+  and NOWHERE else — it never leaks into `behavioral_notes`, `system_prompt`, or
+  any other native field (vendored spec §4 hard constraint — the lens reads only
+  this dedicated field).
+
+## Constraints
+
+- **[correctness]** `validate_exportable`'s OCEAN check IS `validate_ocean` and
+  its role check IS `validate_role` (both E2) — no re-implementation, no drift.
+  The LENGTH bounds (name, prompt, tool id/name/desc, psych_profile, first_message)
+  MUST equal the E3a tool-schema caps — now shared constants in `soong_lab.design`
+  (`AGENT_NAME_MAX`, `SYSTEM_PROMPT_MAX`, `PSYCH_PROFILE_MAX`, `FIRST_MESSAGE_MAX`,
+  `TOOL_*_MAX`), imported by BOTH bifrost/tools.py and export — so a design's field
+  LENGTHS never drift. Import the shared constants; do not re-declare the numbers.
+  (Export is stricter only on whitespace-blankness of the required fields — the one
+  intentional one-way difference from the tools' minLength:1.)
+- **[style]** Pure — NO I/O (no clock, no file, no HTTP, no randomness). Every
+  time-varying value (`design_id`, `exported_at`) is a param.
+- **[explicit]** The one deploy-time caveat (the 4 role slugs must be granted on
+  the target WT) is documented in THIS contract (open_question B) + the library /
+  README when it lands — NOT promised as a bundle/sidecar field (heid-review fold:
+  the bundle is machine-consumed; a human deploy-note is not bundle data). The
+  bundle carries the `role` value; slug-grant validity is a deploy concern.
+- **[explicit]** `build_export_bundle` is the PUBLIC entrypoint — it runs the
+  validate→assemble ordering. `build_native_payload` / `build_sidecar` are exposed
+  for testing + reuse but ASSUME an already-validated design (PRE-E5-2 / PRE-E5-4);
+  a direct caller that skips `validate_exportable` owns that gate (heid-review fold,
+  Hulda #5).
+
+```contract
+FN validate_exportable(design: DesignObject) -> None
+BRIEF: The strict export-critical gate (settled decision #6) — refuse to build a bundle from a design that would fail on re-import or at the designed agent's define/session-create. Checks OCEAN (validate_ocean), role (validate_role), agent_name, system_prompt, every tool-ref, and the psych_profile/first_message LENGTH — against the SAME length caps the E3a tools enforce (shared constants). NO-DRIFT is one-directional: export's LENGTH bounds equal the tool caps, but export is deliberately STRICTER on whitespace — a whitespace-only required field (name/prompt/tool id/name) passes the tools' minLength:1 yet is rejected here (a "   " name must not ship). Raises ExportError with the offending field; never mutates the design.
+PRE: [PRE-E5-1 hard] design is a DesignObject
+POST: [POST-E5-1 exception] raises ExportError(field, detail) unless ALL hold: design.ocean passes validate_ocean; design.role passes validate_role (∈ ROLE_CHOICES); agent_name is a non-blank str of len ≤ _AGENT_NAME_MAX; system_prompt is a non-blank str of len ≤ _SYSTEM_PROMPT_MAX; every tool has non-blank str id (≤_TOOL_ID_MAX) + non-blank str name (≤_TOOL_NAME_MAX) + str description (≤_TOOL_DESC_MAX); psych_profile is a str of len ≤ _PSYCH_PROFILE_MAX (blank OK); first_message is a str of len ≤ _FIRST_MESSAGE_MAX (blank OK). The id/name-required vs description/psych/first_message-may-be-blank asymmetry is INTENTIONAL — description defaults to "" via attach_tool; psych_profile/first_message are optional prose so only their LENGTH is bounded, not blankness (heid-review Gróa #8 + correctness-finder folds)
+POST: [POST-E5-2 state_change] design is unchanged — no mutation (INV-E5-4)
+STEPS:
+  1. [setup, flexibility=prescriptive] TRY validate_ocean(design.ocean) — on OceanError, RAISE ExportError("persona.ocean", str(exc)) (reuse E2, no re-impl)
+  2. [sequential, flexibility=prescriptive] TRY validate_role(design.role) — on RoleError, RAISE ExportError("role", str(exc)) (reuse E2 role canon)
+  3. [branch] IF agent_name is not a non-blank str OR len > _AGENT_NAME_MAX: RAISE ExportError("agent_name", ...)
+  4. [branch] IF system_prompt is not a non-blank str OR len > _SYSTEM_PROMPT_MAX: RAISE ExportError("system_prompt", ...)   # the AUTHORED block, INV-E5-2
+  5. [loop] FOR EACH tool in design.tools: IF id/name blank or over max, or description non-str/over max: RAISE ExportError(f"tools[{i}]", ...)
+  6. [branch] IF psych_profile is non-str OR len > _PSYCH_PROFILE_MAX: RAISE ExportError("psych_profile", ...)   # length only — blank OK (optional prose)
+  7. [branch] IF first_message is non-str OR len > _FIRST_MESSAGE_MAX: RAISE ExportError("first_message", ...)   # length only — blank OK
+  8. [cleanup] RETURN None
+TESTS:
+  minimal_ok [happy,tracer]: agent_name+system_prompt set, role="character", neutral OCEAN, no tools → no raise
+  blank_name [adversarial]: agent_name="" → ExportError("agent_name")
+  blank_prompt [adversarial]: system_prompt="   " → ExportError("system_prompt")
+  prompt_too_long [boundary]: system_prompt of len _SYSTEM_PROMPT_MAX+1 → ExportError; len _SYSTEM_PROMPT_MAX → ok
+  bad_ocean [adversarial]: ocean missing a key → ExportError("persona.ocean") (via validate_ocean)
+  bad_role [adversarial]: role="wizard" (not in ROLE_CHOICES) → ExportError("role") (via validate_role)
+  blank_role [adversarial]: role="" → ExportError("role")
+  bad_tool_ref [adversarial]: a tool with id="" → ExportError("tools[0]")
+  no_mutation [property]: a rejected design is byte-identical before/after the raise (INV-E5-4)
+  psych_profile_length [boundary]: psych_profile="" → ok; len _PSYCH_PROFILE_MAX+1 → ExportError("psych_profile")
+  first_message_length [boundary]: first_message len _FIRST_MESSAGE_MAX+1 → ExportError("first_message"); blank → ok
+  whitespace_name_rejected [adversarial]: agent_name="   " → ExportError("agent_name") — deliberately stricter than the tool's minLength:1 (a whitespace-only name must not ship)
+  length_bounds_parity [property]: any (name, prompt, tool, psych, first_message) LENGTH the E3a tool schema accepts is ≤ export's caps (shared constants); export is stricter ONLY on whitespace-blankness of required fields, never looser on length
+```
+
+```contract
+FN build_native_payload(design: DesignObject) -> dict[str, Any]
+BRIEF: Map a DesignObject to a valid native agents.define payload (Frame Invariant 1). Emits agent_name + role + the AUTHORED system_prompt + persona{ocean, psychological_profile?} + motivational?. Copies mutable sub-structures (INV-E5-4). Assumes validate_exportable already passed (called by build_export_bundle).
+PRE: [PRE-E5-2 hard] design passed validate_exportable (OCEAN valid, role valid, name/prompt present) — build_export_bundle enforces this ordering
+POST: [POST-E5-3 return_value] result has agent_name == design.agent_name, role == design.role (∈ ROLE_CHOICES), and system_prompt == design.system_prompt (the AUTHORED block, INV-E5-2), and result["persona"]["ocean"] == a COPY of design.ocean
+POST: [POST-E5-4 return_value] result["role"] == design.role — the designed agent's model-role (one of the 4 ROLE_CHOICES); a valid agents.define required field
+POST: [POST-E5-5 return_value] persona.psychological_profile == design.psych_profile when psych_profile is non-blank, else the key is absent; it appears under persona and NOWHERE else (INV-E5-7)
+POST: [POST-E5-6 return_value] motivational == {"goals": copy, "fears": copy} when design.goals_fears is present AND at least one list is non-empty; else the key is absent (never an empty motivational block)
+STEPS:
+  1. [setup] payload = {"agent_name": design.agent_name, "role": design.role, "system_prompt": design.system_prompt}   # role emitted; system_prompt is the authored block (INV-E5-2)
+  2. [sequential] persona = {"ocean": dict(design.ocean)}   # COPY, not alias (INV-E5-4)
+  3. [branch] IF design.psych_profile is a non-blank str: persona["psychological_profile"] = design.psych_profile   # LOCKED b53 field; ONLY here (INV-E5-7)
+  4. [sequential] payload["persona"] = persona
+  5. [branch] IF design.goals_fears is not None AND (goals or fears non-empty): payload["motivational"] = {"goals": list(gf.goals), "fears": list(gf.fears)}
+  6. [cleanup] RETURN payload   # tools NOT here — they ride the sidecar / bind via Bifrost at session-create
+TESTS:
+  authored_prompt [happy,tracer]: system_prompt authored + composed_preview differs → payload.system_prompt == authored, NOT composed_preview (INV-E5-2)
+  role_emitted [happy]: role="thoughtful-character" → payload.role == "thoughtful-character" (POST-E5-4)
+  ocean_copied [property]: mutate design.ocean after build → payload's ocean unchanged (INV-E5-4)
+  psych_present [happy]: psych_profile set → persona.psychological_profile == it; it is the ONLY field carrying it (INV-E5-7)
+  psych_absent [boundary]: psych_profile="" → no psychological_profile key
+  motivational_present [happy]: goals_fears with goals=["x"] → motivational.goals == ["x"]
+  motivational_absent [boundary]: goals_fears None → no motivational key; goals_fears with both lists empty → no motivational key
+  no_tools_no_image [trace]: payload has no "tools" and no image field (they ride the sidecar / bind separately)
+```
+
+```contract
+FN build_sidecar(design: DesignObject) -> dict[str, Any]
+BRIEF: Assemble the soong-lab sidecar — the three artifacts the native schema has no home for: the persona portrait ref, the Bifrost tool manifest, and the D3 first_message. Copies the tool list (INV-E5-4).
+PRE: [PRE-E5-4 hard] design is a DesignObject (its portrait/tools/first_message fields are read as-is; no validation here — validate_exportable is the gate, called by build_export_bundle before this)
+POST: [POST-E5-7 return_value] result == {"portrait": <str|None>, "tools": [{"id","name","description"} per tool, copied], "first_message": design.first_message}; portrait == design.portrait.image_url IFF design.portrait.status == "ready", else None (a "ready" status with a None image_url therefore yields None — no crash; any non-"ready" status → None — heid-review fold Gróa #4)
+STEPS:
+  1. [setup] portrait = design.portrait.image_url if design.portrait.status == "ready" else None
+  2. [sequential] tools = [t.to_dict() for t in design.tools]   # ToolRef.to_dict() — the shared {id,name,description} projection (dedups with serialize_design); it MUST emit exactly id/name/description, so if to_dict ever grows keys the sidecar spec must be revisited (heid-code-review fold)
+  3. [cleanup] RETURN {"portrait": portrait, "tools": tools, "first_message": design.first_message}
+TESTS:
+  ready_portrait [happy]: portrait.status="ready", image_url set → sidecar.portrait == the url
+  unready_portrait [boundary]: portrait.status="generating" (url set) → sidecar.portrait is None (only ready ships)
+  none_portrait [boundary]: portrait.status="none" → sidecar.portrait is None
+  tools_manifest [happy,tracer]: two tools → sidecar.tools has both {id,name,description}
+  tools_copied [property]: mutate design.tools after build → sidecar.tools unchanged (INV-E5-4)
+  first_message [happy]: first_message set → sidecar.first_message == it
+```
+
+```contract
+FN build_export_bundle(design: DesignObject, *, design_id: str, exported_at: str | None = None) -> dict[str, Any]
+BRIEF: The top-level export entrypoint — validate (strict, INV-E5-5), then assemble the versioned bundle: {schema_version, design_id, exported_at, ship:{native, sidecar}, resume}. Pure + deterministic (INV-E5-3); the caller supplies design_id + exported_at (no clock here). The resume half reuses serialize_design (the §6 state) so import round-trips. schema_version is NOT a caller param (heid-review fold) — it is ALWAYS EXPORT_SCHEMA_VERSION, so a bundle's version is never caller-forgeable; a future migration bumps the module constant. exported_at is an OPAQUE caller-supplied string (conventionally ISO-8601) — export does NOT parse or validate it (purity; the caller owns timestamp correctness).
+PRE: [PRE-E5-3 hard] design_id is a non-blank str (the durable library key) — a blank id RAISES ExportError("design_id", ...) (a bundle with no library key is unusable)
+POST: [POST-E5-8 exception] IF the design fails validate_exportable, the ExportError propagates and NO bundle is returned (INV-E5-5) — validation is BEFORE assembly
+POST: [POST-E5-9 return_value] returns {schema_version: EXPORT_SCHEMA_VERSION (always), design_id, exported_at, ship:{native: build_native_payload(design), sidecar: build_sidecar(design)}, resume: serialize_design(design)}; exported_at is the param verbatim (None → JSON null), unvalidated
+POST: [POST-E5-10 return_value] deterministic — identical (design, design_id, exported_at) → byte-identical json.dumps(result) given fixed dumps settings; the returned dict has a FIXED key insertion order (schema_version, design_id, exported_at, ship, resume), so a caller's json.dumps is stable (INV-E5-3); design unchanged (INV-E5-4)
+STEPS:
+  1. [setup, flexibility=prescriptive] IF design_id is not a non-blank str: RAISE ExportError("design_id", "a non-blank design_id is required")
+  2. [sequential] CALL validate_exportable(design)   # strict gate BEFORE assembly (INV-E5-5) — raises propagate
+  3. [sequential] native = build_native_payload(design); sidecar = build_sidecar(design); resume = serialize_design(design)
+  4. [cleanup] RETURN {"schema_version": EXPORT_SCHEMA_VERSION, "design_id": design_id, "exported_at": exported_at, "ship": {"native": native, "sidecar": sidecar}, "resume": resume}
+TESTS:
+  full_bundle [happy,tracer]: a complete design + design_id="d-1" → bundle has schema_version, design_id=="d-1", ship.native.agent_name, ship.native.role, ship.sidecar.first_message, resume.systemPrompt
+  blank_design_id [adversarial]: design_id="" → ExportError("design_id") before any assembly
+  invalid_design_no_bundle [adversarial]: a design with blank agent_name → ExportError propagates, no dict returned (POST-E5-8)
+  deterministic [property]: build twice with the same (design, design_id, exported_at) → byte-identical json.dumps (INV-E5-3)
+  exported_at_passthrough [trace]: exported_at="2026-07-13T00:00:00Z" → bundle.exported_at == it verbatim; None → null; a non-ISO "banana" is passed through unvalidated
+  schema_version_not_a_param [trace]: build_export_bundle(..., schema_version="banana") raises TypeError — schema_version is fixed, never caller-supplied (heid-review fold)
+  resume_roundtrips [property]: resume half == serialize_design(design) — every editable field present for import (incl. role)
+  no_mutation [property]: design byte-identical before/after build (INV-E5-4)
+  schema_version_present [trace]: bundle.schema_version == EXPORT_SCHEMA_VERSION (INV-E5-6)
+```
+
+## Integration points
+
+**R1 — relocate `serialize_design` out of `web.py` (agent-discretion refactor,
+no public-surface change).** The resume half reuses the §6 DesignObject
+serialization, but `serialize_design` currently lives in `soong_lab.web`
+(Starlette-coupled). Importing `web.py` into `export` would drag Starlette +
+the orchestrator into a pure module. Fix: **move `serialize_design` to
+`soong_lab.design`** (it is a pure `DesignObject → dict` mapping with no web
+dependency — it belongs with the model; add `role` to its output), and update the
+two consumers to import it from there. Blast radius (confirmed via grep):
+`web.py` (define → import; 3 call-sites unchanged), `tests/test_web.py:23`
+(import path), and the new `export` consumer. Behavior-identical;
+`web_surface.contract.md` gets a one-line note. No-backwards-compat: the old
+location is deleted, all refs updated in the same commit.
+
+**Companion prerequisite slice — the `role` field + `set_role` tool (contracts
+updated in THIS pass).** Export emits `design.role`, so the field + its tool must
+exist. This slice (governed by the sibling contracts, amended alongside this one):
+- `soong_lab.design` (design_object.contract.md): a `role` field on
+  `DesignObject` (default `"character"`); a `ROLE_CHOICES` enum canon +
+  `validate_role`, held as an in-code module constant (mirroring the OCEAN
+  adjective canon); `new_design()` sets `role="character"`; `serialize_design`
+  adds `role`.
+- `soong_lab.bifrost` (bifrost_server.contract.md): a new `set_role(_ctx, role)`
+  design tool (the 9th), `input_schema` an `enum` of the 4 values; the handler
+  sets `design.role` after membership validation.
+The behavioral CODE for this slice lands in the TDD phase after
+`/heid-contract-review`, alongside `soong_lab.export`.
+
+**Bifrost export tool (`_make_export` in bifrost/tools.py) — in scope.** Replace
+the deferred stub with: get the session's design from the store, then
+`build_export_bundle(design, design_id=<source>, exported_at=<stamp>)` and
+return the bundle (or a compact confirmation carrying it). The `design_id`
+source is the per-design-sessions seam (open_question C) — until it lands, the
+tool may pass the session_id as a provisional design_id (a documented
+placeholder, NOT a silent default). The tool handler is the impure boundary that
+stamps `exported_at` (clock) and supplies `design_id`, keeping
+`soong_lab.export` pure.
+
+**`/api/export` endpoint + web/api.js shim — NOT in this contract (open_question
+D).** The browser 'Export Asset' button calls `api.export()`, today a
+client-side shim assembling a NON-native mock bundle. The real path is a thin
+`GET /api/export` on `web.py` → `build_export_bundle(orchestrator.get_design(),
+…)` → JSON → the modal's native/sidecar panes render it. That amends
+`web_surface.contract.md`; it is a follow-up slice in the same epic, specified
+here only so the seam is visible.
+
+## Downstream epics (NOT this contract)
+
+- **Library persistence** (decision #5) — writing the returned bundle to the
+  server-local single-user JSON dir on corviduo-dev, keyed by `design_id`; the
+  minimal recent-designs picker.
+- **Import** (decision #6) — reading a bundle: lenient on unknown metadata
+  (INV-E5-6), STRICT re-validation of the export-critical fields (the import-side
+  mirror of `validate_exportable`), reconstructing a DesignObject from the
+  `resume` half.
+- **Per-design-sessions** (decision #2) — the `design_id` generator + the
+  fresh-WT-session-per-open lifecycle (also caps the #355 accumulation).

docs/vendor/soong-lab-bundle/importer.contract.md

@@ -0,0 +1,389 @@
+---
+contract_version: "2.1"
+module: "soong_lab.importer"
+purpose: "Reconstruct a DesignObject from an export bundle's `resume` half — the inverse of soong_lab.export. HYBRID validation (settled decision #6): LENIENT on unknown metadata (unknown top-level bundle keys, unknown keys inside resume, any schema_version), STRICT re-validation of the export-critical fields (OCEAN, role ∈ ROLE_CHOICES, agent_name, system_prompt length, tool-refs, psych/first_message length) surfaced ON IMPORT so a truncated or tampered bundle fails EARLY, not after more tuning. Pure + deterministic: no I/O, no persistence, no network, no clock (library read + the /api/import endpoint + the reopen lifecycle are separate downstream epics)."
+depends_on:
+  - "soong_lab.design"      # DesignObject/ToolRef/Portrait/GoalsFears + serialize_design (the round-trip partner) + ROLE_CHOICES/UNSET_ROLE + the shared field-bound constants
+  - "soong_lab.export"      # validate_exportable + ExportError — the strict export-critical gate is REUSED, not re-implemented (no-drift, INV-I-1)
+used_by:
+  - "soong_lab.web"         # FUTURE (import epic) — the POST /api/import endpoint parses the uploaded bundle JSON → import_bundle → seed a session (out of scope here, open_question D)
+  - "soong_lab.soong"       # FUTURE (per-design-sessions) — the reopen lifecycle imports a stored bundle, opens a fresh WT session, seeds the design-state summary (out of scope, decision #2)
+language: "python"
+complexity: "medium"
+estimated_loc: 170
+confidence: 0.83
+assumptions:
+  - "Import consumes a Python dict (a Mapping), NOT raw bytes/JSON text. The JSON parse (json.loads at the /api/import endpoint or the library-read layer) happens UPSTREAM; import operates on the already-parsed structure, exactly as export RETURNS a Python dict the caller json.dumps'es. So the round-trip contract is over Python dicts: import_bundle(build_export_bundle(d, design_id=…)) == d, with no JSON layer in between (the JSON boundary — float/int coercion, encoding — is the endpoint/library epic's concern, INV-I-5 note)."
+  - "The `resume` half is the ONLY source of truth on import (settled decision #4 — resume is 'what you reopen to keep tuning'). The `ship` half is a re-derivable deployment artifact; import IGNORES it. The reopen path re-exports from the reconstructed design, regenerating ship, so a ship↔resume mismatch is harmless — resume wins (INV-I-5). No cross-check in v1."
+  - "The export-critical gate on import IS soong_lab.export.validate_exportable, imported and reused verbatim — NOT a re-implemented import-side validator. This guarantees import can never drift looser than export: the exact fields export refuses to ship are the exact fields import refuses to accept (INV-I-1). ExportError is caught and re-raised as BundleImportError so callers get an import-shaped error while the validation authority stays single-sourced."
+  - "role is a first-class DesignObject field (operator ruling 2026-07-13), one of the curated ROLE_CHOICES, set by the E3a set_role tool. A resume carries `role`; import restores it and validate_role (via validate_exportable) rejects UNSET_ROLE ('') or any non-member — you cannot re-import an unclassified design, same as you cannot export one."
+  - "composed_preview + disposition_phrase ride the resume so a reopen renders instantly (export.contract §resume). Import TRUSTS these verbatim (INV-I-8) — it does NOT call recompute. Re-derivation from ocean+prompt is the reopen lifecycle's concern (per-design-sessions), not import's. For a legitimately-exported bundle they are already self-consistent; a hand-tampered preview is design-time-only and is overwritten on the next set_ocean/edit_prompt recompute."
+open_questions:
+  - "[A — RESOLVED, operator 2026-07-13] Module name is `soong_lab.importer` (operator chose it over `soong_lab.ingest`; keyword-safe agent-noun mirroring `export`). The export contract's forward-reference `used_by: soong_lab.import` — an unusable Python-keyword path (`import soong_lab.import` is a SyntaxError) — is corrected to `soong_lab.importer` in the same commit (done). SETTLED: the Constraints hard-require reflects the decision, not a still-open recommendation (heid-review Gróa#1 reconcile open-vs-locked)."
+  - "[B — SETTLED, agent-discretion] Error type is `BundleImportError(field, detail)`, mirroring export's `ExportError(field, detail)`. Deliberately NOT `ImportError` — that shadows the Python builtin, a foot-gun for an import module. The Constraints hard-require reflects the decision, not a still-open recommendation (heid-review Gróa#1)."
+  - "[C — presence vs default, agent-discretion, notable] For the export-critical resume keys (agentName, role, systemPrompt, ocean) a MISSING key is a hard reject (INV-I-7), NOT a silent default. Rationale: a missing `ocean` would default to a VALID neutral OCEAN and pass validate_exportable — silently masking trait loss from a truncated bundle. Rejecting on absence fails loudly + consistently (the 'fail early on import' the decision wants). Rejected alternative: reconstruct-with-defaults-then-validate (inconsistent — ocean slips through while name/role are caught by validation)."
+  - "[D — scope] This contract = the PURE reconstruction (deserialize_design) + the strict entrypoint (import_bundle) + BundleImportError. The POST /api/import endpoint (amends web_surface.contract.md), the reopen Bifrost tool / session-open wiring (per-design-sessions), and reading a bundle off the library JSON dir (library epic) are ALL downstream — specified here only as the integration seam so it is visible. Nothing in this contract does I/O."
+  - "[E — schema_version tolerance] `schema_version` is read at the bundle TOP LEVEL only (where export stamps EXPORT_SCHEMA_VERSION) — import does not look for it inside `resume`. v1 tolerates ANY top-level value (present or absent) and reads the v1 resume key set regardless (INV-I-2, INV-E5-6 add-only-friendly). 'Tolerate any version' means forward-compat with ADD-ONLY future changes — NOT a promise of semantic compatibility with a bundle whose meaning changed (heid-review Gróa#5/Hulda). A future policy — reject an incompatible MAJOR version, or dispatch to a version-specific deserializer — is deferred to when a second schema version actually exists. v1 has exactly one shape."
+---
+
+## Context
+
+Import is the SECOND half of the operator-accepted (2026-07-13) export/import/library
+design — the block that expands the locked single-agent frame into a multi-pass
+tuning loop (design → export → **reopen → tune** → keep a library). Where
+`soong_lab.export` turns a finished `DesignObject` into a versioned bundle, this
+module does the inverse: it takes a bundle's **`resume`** half and reconstructs an
+editable `DesignObject` you can drop back into a session and keep tuning.
+
+The reconstruction is **HYBRID-validated** (settled decision #6 — the load-bearing
+import decision):
+
+- **LENIENT on unknown metadata.** Unknown top-level bundle keys, unknown keys
+  inside `resume`, and any `schema_version` (present or absent) are tolerated —
+  import reads only the keys it knows (INV-I-2, mirroring the export bundle's
+  add-only-friendly `INV-E5-6`). A bundle from a future soong-lab that added
+  fields still imports.
+- **STRICT on the export-critical fields.** OCEAN, `role`, `agent_name`,
+  `system_prompt`, tool-refs, and the psych/first_message length are re-validated
+  **on import** by REUSING `soong_lab.export.validate_exportable` verbatim (INV-I-1)
+  — so the exact fields export refuses to *ship* are the exact fields import
+  refuses to *accept*, and import can never drift looser than export. A bad field
+  is surfaced immediately (fail EARLY), not after the operator has tuned for
+  another ten minutes against a design that was never valid.
+
+**The round-trip is the load-bearing contract between the two modules** (INV-I-3):
+for any exportable design `d`,
+
+```
+import_bundle(build_export_bundle(d, design_id="…")) == d
+deserialize_design(serialize_design(d))              == d
+```
+
+This is what makes "export then reopen" lossless. `serialize_design`
+(relocated to `soong_lab.design` in the export pass, R1) is the forward half;
+`deserialize_design` here is its exact inverse.
+
+**Import reads the `resume` half ONLY.** The `ship` half (native `agents.define`
+payload + sidecar) is a re-derivable deployment artifact — the reopen path
+re-exports from the reconstructed design, regenerating `ship`. So import ignores
+`ship` entirely (INV-I-5); a tampered `ship` that disagrees with `resume` is
+harmless (resume wins, ship regenerated). No cross-check in v1.
+
+**What this contract does NOT do** (open_question D): no file read, no HTTP, no
+session seeding. The `POST /api/import` endpoint, the reopen Bifrost tool /
+session-open wiring, and reading a bundle off the library JSON dir are downstream
+epics. This module is the pure, side-effect-free reconstruction core those epics
+build on — exactly as `soong_lab.export` is the pure builder its endpoint wraps.
+
+## Data flow
+
+**In:** a bundle `dict` (a Mapping — already `json.loads`'d upstream). **Out:** a
+validated, ready-to-reopen `DesignObject`. **On disk / network:** NONE. Import is
+pure: the structural gate (bundle/resume/ocean are dicts, tools a list-of-dicts),
+the tolerant reconstruction, and the strict `validate_exportable` re-check are all
+in-memory; no clock, no randomness, no file, no HTTP.
+
+### The resume key set consumed (v1.0)
+
+Import reconstructs from exactly the `serialize_design` output (the §6 camelCase
+state — pinned in export.contract §resume, restated here so this contract is
+self-contained):
+
+```
+resume = {
+  "agentName": <str>,               # EXPORT-CRITICAL — presence required (INV-I-7)
+  "role": <str ∈ ROLE_CHOICES>,     # EXPORT-CRITICAL — presence required; validate_role gates value
+  "systemPrompt": <str>,            # EXPORT-CRITICAL — presence required; the AUTHORED block
+  "ocean": {O,C,E,A,N},             # EXPORT-CRITICAL — presence required; validate_ocean gates value
+  "tools": [{id,name,description}], # optional (absent → []); each ref value-gated by validate_exportable
+  "composedPreview": <str>,         # design-time-derived — TRUSTED verbatim, re-derivable (INV-I-8)
+  "dispositionPhrase": <str>,       # design-time-derived — TRUSTED verbatim, re-derivable (INV-I-8)
+  "firstMessage": <str>,            # optional prose — length-gated only (blank OK)
+  "psychProfile": <str>,            # optional prose — length-gated only (blank OK)
+  "portrait": {status, styleMode, imageUrl?, jobId?},   # optional (absent → default Portrait())
+  "goalsFears": {goals,fears} | null                     # optional (absent/null → None)
+}
+```
+
+**Critical vs optional (the presence rule, INV-I-7).** Read the two functions as a
+boundary (all three review arms flagged that the prose blurs it): the INNER
+`deserialize_design` is total and DEFAULTS every missing key (a missing `ocean` →
+neutral) — it NEVER rejects; the OUTER, public `import_bundle` PRESENCE-CHECKS the
+export-critical keys and REJECTS a missing one BEFORE it ever calls deserialize. So
+"import defaults a missing ocean to neutral" is FALSE for the public path
+(`import_bundle` rejects it, INV-I-7) — the neutral default lives ONLY inside the
+never-directly-shipped inner function (heid-review 3/3: POST-I-3 vs INV-I-7 read as
+contradictory in isolation). `agentName`, `role`, `systemPrompt`, `ocean` are
+**presence-required** — a missing one is a truncated / corrupt bundle and raises
+`BundleImportError`, because defaulting them would either be caught inconsistently
+(name/role/prompt default to values `validate_exportable` rejects) or silently
+masked (`ocean` defaults to a VALID neutral OCEAN — silent trait loss). Every other
+key is optional and defaults to the `DesignObject` default when absent. `tools`/`portrait`/`goalsFears`, when present, must be well-formed SHAPES —
+`tools` a list-of-objects, `ocean`/`portrait` an object, `goalsFears` null or an
+object whose present `goals`/`fears` are lists — structural mismatches raise a clean
+`BundleImportError`, never a leaked builtin `TypeError`/`ValueError` (INV-I-6
+robustness). These SHAPE gates all exist to prevent SILENT DATA LOSS (heid-bug-hunt
+Gróa#1/#2: a malformed portrait/goalsFears would otherwise coerce to a default in
+`deserialize_design` and slip PAST `validate_exportable`, since both are
+non-export-critical — the same loss the `tools` gate was added to close). Import does
+NOT validate their VALUE contents — portrait `status`/`styleMode` enums or goals/fears
+item contents are not export-critical (E4 / the UI own portrait validity); those
+round-trip as-is (heid-review Gróa#6). A goalsFears item is COERCED into a Goal/Fear by
+`_coerce_goal`/`_coerce_fear` (totality, INV-I-6): a dict → its {description, type?,
+salience?} fields (missing/mistyped → the model default), a LEGACY bare string (a
+pre-2026-07-16 design, when goals were strings) → its `description`, anything else → a
+blank Goal/Fear (which `validate_exportable`'s ≥20-char/type/salience gate then rejects on
+the strict re-validate — no silent loss).
+
+## Invariants
+
+- **INV-I-1** [hard]: The strict export-critical re-validation IS
+  `soong_lab.export.validate_exportable`, imported and reused verbatim — NO
+  re-implementation, no parallel import-side validator. Import therefore can NEVER
+  be looser than export: OCEAN (`validate_ocean`), role (`validate_role`, ∈
+  ROLE_CHOICES), `agent_name` (non-blank, ≤`AGENT_NAME_MAX`), `system_prompt`
+  (non-blank, ≤`SYSTEM_PROMPT_MAX`), every tool-ref (id/name non-blank + bounded,
+  description bounded), and the psych/first_message LENGTH are all gated by the
+  same code export uses. An `ExportError` from that gate is caught and re-raised
+  as `BundleImportError(same field, same detail)` — same field granularity,
+  import-shaped type.
+- **INV-I-2** [hard]: LENIENT on unknown metadata (settled decision #6, mirrors
+  INV-E5-6). Unknown top-level bundle keys, unknown keys inside `resume`, and any
+  `schema_version` value (present or absent) are tolerated — import reads only the
+  keys it knows and ignores the rest. A future-schema bundle that ADDED fields
+  still imports.
+- **INV-I-3** [hard]: ROUND-TRIP — for any `DesignObject` `d` that passes
+  `validate_exportable`, `deserialize_design(serialize_design(d))` reconstructs an
+  EQUAL `DesignObject` (dataclass `==` over every field), and
+  `import_bundle(build_export_bundle(d, design_id=…))` `== d`. This is the lossless
+  export↔import contract. (Equality is over Python structures; the JSON encode/decode
+  boundary is the endpoint/library epic's concern, not this module's.)
+- **INV-I-4** [hard]: NO-ALIAS — the reconstructed `DesignObject` holds COPIES of
+  every mutable sub-structure (the ocean dict, the tools list, the goals/fears
+  lists) drawn from the bundle, never aliases. A later mutation of the input bundle
+  cannot change an already-imported design (the mirror of export's INV-E5-4). The
+  copies are SHALLOW (the CONTAINERS) — sufficient because legit export values are
+  scalars (strings/floats), and a hostile NESTED mutable (a list-valued tool id, a
+  dict-valued goal) is rejected by `validate_exportable` before any successful import
+  (heid-bug-hunt Gróa#5/Hulda#1: the invariant's letter holds; deep-copy is deferred
+  unless nested mutables ever become in-contract).
+- **INV-I-5** [hard]: Import reads the `resume` half and NOWHERE else — `ship`
+  (native + sidecar) is ignored (it is re-derivable; the reopen path re-exports).
+  No ship↔resume consistency check in v1; on any disagreement, resume is
+  authoritative.
+- **INV-I-6** [hard]: `deserialize_design` is TOTAL — it never raises on any input
+  Mapping. Hostile shapes (a string `ocean`, an int `tools`, a list `portrait`, a
+  string `goalsFears`, or a dict `goalsFears` whose `goals`/`fears` is a non-list)
+  are coerced/defaulted, not crashed — in particular EVERY `list(...)`/`dict(...)`
+  coercion is type-GUARDED first: a non-list `goals` becomes `[]` (never
+  `list(7)`→TypeError nor `list("ab")`→`["a","b"]`), a non-dict `ocean` is held
+  verbatim (never `dict("nope")`→ValueError). ALL rejection happens in
+  `import_bundle` (its structural gate + `validate_exportable`). Non-export-critical
+  fields that are missing or mistyped default to the `DesignObject` default;
+  export-critical VALUES are held AS-READ (no silent type-coercion) so
+  `validate_exportable` judges them — with ONE structural exception: `import_bundle`
+  pre-checks that `ocean` is a dict (so `deserialize_design`'s `dict()` copy is
+  safe), so `ocean` has a structural judge (`import_bundle`) AND a value judge
+  (`validate_ocean`), while `agent_name`/`role`/`system_prompt` are judged by value
+  alone — "single judge" is exact for those three, not for `ocean` (heid-review
+  Gróa#2/#4, Hulda, Regin#3). (Mirrors `recompute`'s hostile-input tolerance in derive.py.)
+- **INV-I-7** [hard]: PRESENCE — `import_bundle` requires the export-critical
+  resume keys `agentName`, `role`, `systemPrompt`, `ocean` to be PRESENT; a missing
+  one raises `BundleImportError(f"resume.{key}", …)` (a truncated bundle fails
+  loudly, not by silently defaulting — especially `ocean`, whose neutral default
+  would mask trait loss). `tools` absent → `[]` (an empty toolset is a valid
+  design). This is the explicit-over-implicit choice: reject a missing critical key
+  rather than accept a silently-defaulted one.
+- **INV-I-8** [hard]: Import does NOT re-derive `composed_preview` /
+  `disposition_phrase` — it TRUSTS the resume values verbatim (they ride the resume
+  for instant reopen-render, per export.contract). `recompute` is the reopen
+  lifecycle's concern (per-design-sessions), not import's. For a legit bundle these
+  are already self-consistent; a tampered preview is design-time-only and is
+  overwritten on the next `set_ocean`/`edit_prompt`. Import makes NO consistency
+  guarantee between the trusted preview and `ocean`+`system_prompt`: for a
+  hand-edited resume the two may diverge until the first recompute self-heals them —
+  round-trip equality (INV-I-3) is "== the DesignObject the bundle encodes," NOT
+  "the preview matches a fresh recompute" (heid-review Gróa#8).
+
+## Constraints
+
+- **[correctness]** The export-critical re-validation reuses
+  `soong_lab.export.validate_exportable` (INV-I-1) — import declares no length
+  numbers, no role list, no OCEAN shape of its own. The shared field-bound
+  constants + `ROLE_CHOICES` live in `soong_lab.design`; the strict gate lives in
+  `soong_lab.export`; import imports both. Zero duplicated validation logic → zero
+  drift.
+- **[style]** Pure — NO I/O (no clock, no file, no HTTP, no randomness). Import is
+  a total function of its input Mapping.
+- **[explicit]** `BundleImportError` does NOT shadow the builtin `ImportError`
+  (open_question B). The module is `soong_lab.importer`, NOT `soong_lab.import` —
+  `import` is a Python keyword and unusable as a module path (open_question A).
+- **[robustness]** `deserialize_design` guards types BEFORE any `dict()` /
+  iteration: a non-dict `ocean` is held as-read (never `dict("nope")`, which raises
+  a raw `ValueError`); a non-list `tools` yields `[]`; a non-dict `portrait` /
+  `goalsFears` falls back to the default (`import_bundle`'s structural gates reject a
+  present-but-malformed portrait/goalsFears BEFORE this, so the default-fallback is
+  reachable only for a MISSING field). This keeps every rejection path flowing
+  through `BundleImportError` — a caller never sees a leaked builtin exception.
+- **[robustness]** The "no builtin ever leaks from the public entrypoint" guarantee
+  for hostile export-critical SCALAR types (a non-str `agent_name`/`role`/
+  `system_prompt`/`psych_profile`/`first_message`, or a `None`) is provided JOINTLY by
+  (a) holding them as-read + (b) `validate_exportable` being TOTAL over hostile scalar
+  types — every check `isinstance`-guards BEFORE any `.strip()`/`len()`, and the `or`
+  short-circuits, so a hostile scalar yields a clean `ExportError` (→ `BundleImportError`),
+  never a raw `TypeError`/`AttributeError`. This is an EXPLICIT cross-module coupling
+  (`soong_lab.export` guarantees the totality): import does NOT blanket-catch
+  non-`ExportError` (that would mask real programming errors); the coupling is instead
+  PINNED by a hostile-scalar test through `import_bundle` (heid-bug-hunt 3/3 —
+  Gróa#3/Hulda#2/Regin#1). If `validate_exportable` ever did an unguarded string op, that
+  test fails.
+- **[explicit]** `import_bundle` is the PUBLIC entrypoint that runs the full gate
+  (structure → presence → reconstruct → `validate_exportable`). `deserialize_design`
+  is exposed for the round-trip test + direct reuse but PERFORMS NO validation
+  (PRE-I-1) — a direct caller that skips `import_bundle` owns re-validation (the
+  mirror of export's build_native_payload/build_sidecar assuming a validated design).
+- **[explicit]** Two-LAYER error-field convention (heid-review Regin#6): a
+  STRUCTURAL / PRESENCE rejection raised BY `import_bundle` names the offending
+  BUNDLE key in camelCase with a `resume.` prefix (`resume.agentName` missing,
+  `resume.ocean` not-an-object) — it reports the bundle's JSON shape. A VALUE
+  rejection from the reused `validate_exportable` names the `DesignObject` field in
+  snake_case with no prefix (`agent_name` blank, `persona.ocean` out of range) — it
+  reports the design's validity. Same logical field, two deliberate `.field` forms
+  encoding WHICH LAYER failed (bundle-structure vs design-value); a caller switching
+  on `err.field` MUST handle both, and `err.detail` disambiguates. Tests assert on
+  `.field` (pinned); `.detail` wording is human-facing and NOT pinned (heid-review
+  Hulda) — intentional, not drift.
+
+```contract
+FN deserialize_design(resume: Mapping[str, Any]) -> DesignObject
+BRIEF: The pure, TOTAL inverse of serialize_design — reconstruct a DesignObject from the §6 camelCase resume half. Reads each known key with a type-guard; missing/mistyped NON-export-critical fields default to the DesignObject default; export-critical fields are held AS-READ (no coercion) for validate_exportable to judge later; unknown keys are ignored (INV-I-2). Copies every mutable sub-structure (INV-I-4). NEVER raises (INV-I-6) — it performs NO validation (that is import_bundle's job). deserialize_design(serialize_design(d)) == d for any exportable d (INV-I-3).
+PRE: [PRE-I-1 hard] resume is a Mapping (import_bundle guarantees a dict before calling; a direct caller passes any Mapping — a non-Mapping is a caller error, but the function still must not crash on a Mapping of hostile VALUES)
+POST: [POST-I-1 return_value] returns a DesignObject whose fields map 1:1 from the camelCase keys: agentName→agent_name, role→role, systemPrompt→system_prompt, composedPreview→composed_preview, firstMessage→first_message, ocean→ocean (COPY), dispositionPhrase→disposition_phrase, psychProfile→psych_profile, tools→[ToolRef,…] (COPY of the list, each ref rebuilt), portrait→Portrait(...), goalsFears→GoalsFears(...) | None
+POST: [POST-I-2 return_value] ocean, tools, goals, and fears are COPIES of the resume values — mutating resume after the call never changes the returned design (INV-I-4)
+POST: [POST-I-3 return_value] export-critical fields (agentName, role, systemPrompt, ocean) are held AS-READ (missing → the DesignObject default; present-but-mistyped → the value verbatim, so validate_exportable is the single judge); design-time-derived composedPreview/dispositionPhrase coerce a non-str to "" (re-derivable, keep the object clean); firstMessage/psychProfile are held as-read (validate_exportable length-gates them). ocean is copied IFF it is a dict, else held verbatim (NEVER dict("nope"))
+POST: [POST-I-4 state_change] performs NO validation and NEVER raises on a Mapping input (INV-I-6)
+STEPS:
+  1. [setup] agent_name = resume.get("agentName", "");  role = resume.get("role", UNSET_ROLE);  system_prompt = resume.get("systemPrompt", "")   # export-critical — held as-read, no coercion
+  2. [sequential] composed_preview = resume["composedPreview"] if it is a str else "";  disposition_phrase = resume["dispositionPhrase"] if it is a str else ""   # design-time-derived, re-derivable → coerce clean
+  3. [sequential] first_message = resume.get("firstMessage", "");  psych_profile = resume.get("psychProfile", "")   # optional prose — held as-read, length-gated by validate_exportable
+  4. [branch] raw_ocean = resume.get("ocean"); ocean = dict(raw_ocean) if isinstance(raw_ocean, dict) else (raw_ocean if raw_ocean is not None else _neutral_ocean())   # COPY iff dict; else held verbatim for validate_ocean to reject (guard BEFORE dict(), INV-I-6 robustness)
+  5. [loop] raw_tools = resume.get("tools"); tools = [(ToolRef(id=t.get("id",""), name=t.get("name",""), description=t.get("description","")) if isinstance(t, dict) else ToolRef(id="", name="", description="")) for t in raw_tools] IF isinstance(raw_tools, list) else []   # non-list → []; a non-dict item maps to a BLANK ToolRef (NOT skipped) so a direct caller who re-validates fails loud on the blank id rather than silently losing a tool (heid-review Gróa#7); import_bundle structurally rejects both cases upstream
+  6. [branch] raw_portrait = resume.get("portrait"); portrait = Portrait(status=raw_portrait.get("status","none"), style_mode=raw_portrait.get("styleMode","cartoon"), image_url=raw_portrait.get("imageUrl"), job_id=raw_portrait.get("jobId")) IF isinstance(raw_portrait, dict) else Portrait()   # use raw_portrait (heid-review Regin#2 — the `rp` working-name was unbound); imageUrl/jobId absent → None (round-trips serialize's None-omission)
+  7. [branch] raw_gf = resume.get("goalsFears"); IF isinstance(raw_gf, dict): g = raw_gf.get("goals"); f = raw_gf.get("fears"); goals_fears = GoalsFears(goals=(list(g) if isinstance(g, list) else []), fears=(list(f) if isinstance(f, list) else [])) ELSE: goals_fears = None   # use raw_gf (heid-review Regin#2 — `gf` was unbound); a non-LIST goals/fears → [], NEVER list(7)→TypeError (totality, INV-I-6) and NEVER list("ab")→["a","b"] (silent char-split, heid-review Gróa#2/Hulda); null/absent → None; COPY the lists (INV-I-4)
+  8. [cleanup] RETURN DesignObject(agent_name, role, system_prompt, composed_preview, ocean, disposition_phrase, tools, portrait, first_message, psych_profile, goals_fears)
+TESTS:
+  roundtrip_full [property,tracer]: a fully-populated exportable design d (name, role, prompt, non-neutral ocean, 2 tools, ready portrait w/ url+job, first_message, psych, goalsFears) → deserialize_design(serialize_design(d)) == d
+  roundtrip_minimal [property]: minimal design (name+prompt+role, neutral ocean, no tools/portrait-url/gf) → round-trips == d
+  copies_not_aliases [property]: deserialize, then mutate resume["ocean"]["O"] and append to resume["tools"] → the returned design's ocean + tools are unchanged (INV-I-4)
+  total_on_hostile [property]: deserialize_design({"ocean":"nope","tools":7,"portrait":[],"goalsFears":"x","agentName":123}) does NOT raise; returns a DesignObject (ocean=="nope" held verbatim, tools==[], portrait==Portrait(), goals_fears is None, agent_name==123) — INV-I-6
+  total_on_hostile_goalsfears [property]: deserialize_design({"goalsFears":{"goals":7,"fears":"abc"}}) does NOT raise (the totality-breaking case heid-review Gróa#2/Hulda caught) → goals_fears==GoalsFears([],[]) (non-list goals→[] not list(7)→TypeError; non-list fears→[] not list("abc")→["a","b","c"]) — INV-I-6
+  tools_nondict_item_blank [boundary]: deserialize_design({"tools":[{"id":"a","name":"n"},7]}) → tools==[ToolRef("a","n",""), ToolRef("","","")] — the non-dict item maps to a BLANK ToolRef, NOT skipped (heid-review Gróa#7), so a direct caller re-validating fails loud on the blank id
+  empty_resume [boundary]: deserialize_design({}) → DesignObject() all-defaults (role==UNSET_ROLE, neutral ocean, no tools) — total, no raise
+  portrait_none_fields [boundary]: resume.portrait without imageUrl/jobId → Portrait.image_url is None, Portrait.job_id is None
+  goalsfears_null [boundary]: resume.goalsFears is None → design.goals_fears is None; goalsFears={} → GoalsFears([],[])
+  roundtrip_goalsfears_empty [property]: a design with goals_fears==GoalsFears([],[]) → deserialize_design(serialize_design(d)).goals_fears == GoalsFears([],[]) (empty, NOT None) — locks the null-vs-{} distinction (heid-review Regin#4)
+  preview_trusted [trace]: resume.composedPreview="CUSTOM", dispositionPhrase="odd" → design.composed_preview=="CUSTOM", disposition_phrase=="odd" (NOT re-derived, INV-I-8)
+  unknown_keys_ignored [trace]: resume with an extra "futureField":123 → deserialize ignores it, no crash (INV-I-2)
+```
+
+```contract
+FN import_bundle(bundle: Mapping[str, Any]) -> DesignObject
+BRIEF: The public entrypoint — the mirror of build_export_bundle. Runs the full gate: STRUCTURE (bundle/resume are dicts, ocean is a dict, tools is a list-of-dicts) → PRESENCE (the export-critical resume keys, INV-I-7) → reconstruct (deserialize_design) → STRICT re-validate (validate_exportable, reused verbatim, INV-I-1). LENIENT on unknown metadata + any schema_version (INV-I-2). Reads ONLY resume; ignores ship (INV-I-5). Returns a DesignObject that PASSES validate_exportable — ready to reopen. Every rejection is a BundleImportError(field, detail); no builtin exception ever leaks.
+PRE: [PRE-I-2 hard] bundle is a Mapping (a non-Mapping raises BundleImportError("bundle", …), never a bare TypeError)
+POST: [POST-I-5 exception] raises BundleImportError(field, detail) — with NO DesignObject returned — if ANY: bundle is not a Mapping ("bundle"); bundle["resume"] is missing or not a Mapping ("resume"); any of agentName/role/systemPrompt/ocean is absent from resume ("resume.<key>", INV-I-7); resume["ocean"] is present-but-not-a-dict ("resume.ocean"); resume["tools"] is present-but-not-a-list or contains a non-dict item ("resume.tools"); resume["portrait"] is present-but-not-a-dict ("resume.portrait"); resume["goalsFears"] is present-but-not (null OR a dict whose present goals/fears are lists) ("resume.goalsFears"); OR the reconstructed design fails validate_exportable (the ExportError's field+detail, re-raised as BundleImportError — INV-I-1)
+POST: [POST-I-6 return_value] on success returns a DesignObject that PASSES validate_exportable (name/role/prompt/ocean/tools/psych/first_message all valid), holds COPIES of every mutable sub-structure (INV-I-4), with composed_preview/disposition_phrase trusted from resume (INV-I-8); ship is never read (INV-I-5)
+POST: [POST-I-7 return_value] LENIENT — unknown top-level bundle keys, unknown resume keys, and any schema_version (present, absent, or unrecognized) do not affect the result (INV-I-2)
+STEPS:
+  1. [setup, flexibility=prescriptive] IF bundle is not a Mapping: RAISE BundleImportError("bundle", "bundle must be an object")
+  2. [sequential] resume = bundle.get("resume"); IF resume is not a Mapping: RAISE BundleImportError("resume", "the bundle has no readable 'resume' half")   # ship + schema_version read leniently — schema_version is NOT gated (INV-I-2, open_question E)
+  3. [loop] FOR key IN ("agentName", "role", "systemPrompt", "ocean"): IF key not in resume: RAISE BundleImportError(f"resume.{key}", "required export-critical field is missing")   # presence, INV-I-7
+  4. [branch] IF resume["ocean"] is not a dict: RAISE BundleImportError("resume.ocean", "ocean must be an object")   # structural — keeps deserialize's dict() safe + gives a clean field error
+  5. [branch] IF "tools" in resume AND (resume["tools"] is not a list OR any item is not a dict): RAISE BundleImportError("resume.tools", "tools must be a list of objects")   # structural — prevents silent tool loss
+  5b. [branch] IF "portrait" in resume AND resume["portrait"] is not a dict: RAISE BundleImportError("resume.portrait", "portrait must be an object")   # SAME no-silent-loss gate as tools (heid-bug-hunt Gróa#2) — else a non-dict portrait silently coerces to Portrait() (wiping status/imageUrl/jobId) and slips past validate_exportable (portrait is non-export-critical)
+  5c. [branch] IF "goalsFears" in resume AND resume["goalsFears"] is not None: IF it is not a dict RAISE BundleImportError("resume.goalsFears", "must be an object or null"); ELSE FOR k IN (goals, fears): IF k in gf AND gf[k] is not a list: RAISE BundleImportError("resume.goalsFears", f"{k} must be a list")   # no-silent-loss gate (heid-bug-hunt Gróa#1) — else a non-list goals/fears silently coerces to [] (dropping the operator's data) and slips past validate_exportable (goals_fears is non-export-critical)
+  6. [sequential] design = deserialize_design(resume)   # total; the structural gates above guarantee a plausible shape
+  7. [sequential, flexibility=prescriptive] TRY validate_exportable(design) EXCEPT ExportError AS exc: RAISE BundleImportError(exc.field, exc.detail) FROM exc   # the STRICT export-critical gate, REUSED (INV-I-1) — same field granularity, import-shaped type
+  8. [cleanup] RETURN design
+TESTS:
+  roundtrip_full [property,tracer]: import_bundle(build_export_bundle(d, design_id="d-1")) == d for a fully-populated exportable d (INV-I-3)
+  roundtrip_minimal [property]: import_bundle(build_export_bundle(d_minimal, design_id="d-1")) == d_minimal (a minimal exportable design through the FULL gate — symmetry with deserialize_design, heid-code-review Regin#4)
+  roundtrip_after_export [property]: build a bundle, import it, re-export the result → the two bundles' resume halves are equal (idempotent reopen)
+  lenient_unknown_metadata [happy]: a valid bundle + extra top-level "x":1, extra resume "futureField":2, schema_version="99.0" → imports fine; result == the same design without the extras (INV-I-2)
+  missing_resume [adversarial]: bundle == {"schema_version":"1.0","ship":{…}} (no resume) → BundleImportError("resume")
+  bundle_not_mapping [adversarial]: import_bundle("not a bundle") → BundleImportError("bundle") — no bare TypeError
+  missing_ocean [adversarial]: resume without "ocean" → BundleImportError("resume.ocean") via presence (INV-I-7) — NOT silently neutral
+  missing_role [adversarial]: resume without "role" → BundleImportError("resume.role")
+  missing_name [adversarial]: resume without "agentName" → BundleImportError("resume.agentName")
+  missing_systemprompt [adversarial]: resume without "systemPrompt" → BundleImportError("resume.systemPrompt") — the 4th critical key, completes the presence coverage (heid-code-review Hulda/Regin)
+  non_dict_ocean [adversarial]: resume.ocean="nope" (present) → BundleImportError("resume.ocean", must be object) — clean error, never a raw ValueError from dict()
+  non_list_tools [adversarial]: resume.tools={} → BundleImportError("resume.tools"); resume.tools=[7] (non-dict item) → BundleImportError("resume.tools")
+  non_dict_portrait [adversarial]: resume.portrait=[] / "x" / 7 → BundleImportError("resume.portrait") — the no-silent-loss gate (heid-bug-hunt Gróa#2)
+  malformed_goalsfears [adversarial]: resume.goalsFears={"goals":["survive"],"fears":"exposure"} (fears non-list) → BundleImportError("resume.goalsFears") — the headline silent-loss case; goalsFears=7 → BundleImportError; goalsFears=None and goalsFears={} → ok (round-trip shapes) (heid-bug-hunt Gróa#1)
+  hostile_scalars_no_builtin_leak [adversarial]: resume.agentName=123 / systemPrompt=null / psychProfile=0 → each a clean BundleImportError (agent_name / system_prompt / psych_profile), NEVER a raw builtin — pins the validate_exportable-totality coupling (heid-bug-hunt 3/3)
+  blank_name_rejected [adversarial]: resume.agentName="   " → BundleImportError("agent_name") via validate_exportable (whitespace stricter, INV-I-1)
+  bad_role_rejected [adversarial]: resume.role="wizard" → BundleImportError("role") via validate_role
+  unset_role_rejected [adversarial]: resume.role="" → BundleImportError("role") — an unclassified design is not importable, same as not exportable
+  bad_ocean_value [adversarial]: resume.ocean.O=2.0 → BundleImportError("persona.ocean") via validate_ocean
+  bad_tool_ref [adversarial]: resume.tools=[{"id":"","name":"x"}] → BundleImportError("tools[0]") via validate_exportable
+  prompt_too_long [boundary]: resume.systemPrompt of len SYSTEM_PROMPT_MAX+1 → BundleImportError("system_prompt"); len SYSTEM_PROMPT_MAX → ok
+  psych_too_long [boundary]: resume.psychProfile of len PSYCH_PROFILE_MAX+1 → BundleImportError("psych_profile"); blank → ok
+  first_message_too_long [boundary]: resume.firstMessage of len FIRST_MESSAGE_MAX+1 → BundleImportError("first_message"); blank → ok (same length-gate as psych, via the reused validate_exportable — heid-code-review Hulda/Regin)
+  ship_ignored [trace]: a valid bundle whose ship.native.agent_name disagrees with resume.agentName → the imported design uses resume.agentName; ship is not read (INV-I-5)
+  no_alias [property]: import, then mutate the source bundle's resume["ocean"] + resume["tools"] + resume["goalsFears"]["goals"]/["fears"] → the returned design is unchanged, incl. the goals/fears lists (INV-I-4, heid-code-review Hulda)
+  error_is_not_builtin [trace]: BundleImportError is not the builtin ImportError (isinstance check) — the module never shadows it (open_question B)
+  error_field_layer_convention [trace]: a MISSING agentName → BundleImportError field "resume.agentName" (structural/camelCase); a BLANK agentName → BundleImportError field "agent_name" (value/snake_case via validate_exportable) — the intentional two-layer convention (heid-review Regin#6)
+```
+
+## Integration points
+
+**Reuse of `soong_lab.export` (the no-drift anchor).** Import imports
+`validate_exportable` + `ExportError` from `soong_lab.export`. This is the single
+most important structural decision in the contract: the strict export-critical
+gate is authored ONCE (in export) and reused on import, so the two directions can
+never diverge. Import adds no length numbers, no role membership list, no OCEAN
+shape — those all live upstream (`soong_lab.design` constants + `soong_lab.export`
+gate). The dependency direction is clean: `importer → export → design`, all three
+pure.
+
+**`serialize_design` is the round-trip partner (no code change).** The forward
+half already lives in `soong_lab.design` (relocated there in the export pass, R1).
+This contract adds no change to it; `deserialize_design` is written to be its exact
+inverse, and the round-trip tests pin the pair together. If a future field is
+added to the DesignObject, BOTH `serialize_design` and `deserialize_design` must
+gain it in the same commit (the round-trip test enforces this — a field added to
+serialize but not deserialize breaks `roundtrip_full`). The round-trip also locks
+the `goalsFears` null-vs-`{}` distinction (`None`→`null`, empty→`{"goals":[],"fears":[]}`);
+the tests exercise BOTH so a future `serialize_design` change that collapsed the two
+cases is caught, not silently round-trip-broken (heid-review Regin#4).
+
+**Export contract `used_by` reference (one-line canon fix, same commit as code).**
+`export.contract.md`'s `used_by:` block names `soong_lab.import` — an unusable
+Python-keyword module path. On acceptance of open_question A, that line updates to
+`soong_lab.importer` (or the chosen name). No-backwards-compat: the stale reference
+is corrected, not left as a second name for the same module.
+
+**`POST /api/import` endpoint + web upload — NOT in this contract (open_question
+D).** The browser 'Import Asset' / reopen flow uploads a bundle JSON; the endpoint
+`json.loads` the body → `import_bundle(bundle)` → seed a session with the
+reconstructed design (and, per per-design-sessions, open a fresh WT session +
+build the design-state summary). A `BundleImportError` becomes a 4xx with the
+`field`/`detail` surfaced to the operator ("fail early on import"). That amends
+`web_surface.contract.md`; it is a follow-up slice in the same epic, specified here
+only so the seam is visible. This module does no HTTP.
+
+**Reopen Bifrost tool / session-open — NOT in this contract (per-design-sessions,
+decision #2).** Reopening a design mid-conversation (vs. at session boot) may want
+a Bifrost tool that swaps the session's stored DesignObject for an imported one. If
+so, its handler calls `import_bundle` and replaces the store entry — the impure
+boundary, keeping `soong_lab.importer` pure. Out of scope here.
+
+## Downstream epics (NOT this contract)
+
+- **Library read** (decision #5) — reading a stored bundle off the server-local
+  single-user JSON dir on corviduo-dev, keyed by `design_id`, then handing it to
+  `import_bundle`. The minimal recent-designs picker lists what is importable.
+- **Per-design-sessions** (decision #2) — the reopen lifecycle: `import_bundle` →
+  fresh WT session → the compact design-state SUMMARY seeded as context (also caps
+  the #355 accumulation). `import_bundle` is the reconstruction primitive it calls.
+- **`POST /api/import` + the browser upload/reopen UI** (open_question D) — the web
+  surface that turns an uploaded/selected bundle into a live, reopened session.

docs/vendor/worldtree-persona-canon/affect-egress-consumer-reference.md

@@ -0,0 +1,172 @@
+# Affect egress — consumer reference (delivered vs hidden)
+
+**Audience:** downstream consumers of Worldtree's affect surfaces (ratatoskr,
+Skaldsong, any Tier-3 / SSE consumer).
+**Scope:** what the affect pipeline **delivers on the wire** (structured state,
+available to consumers) versus what stays **hidden** (the rendered natural-
+language strings injected into the agent's system prompt, never emitted).
+**Source of truth:** the render code (`core/persona/renderer.py`,
+`core/persona/stance_render.py`) and the two vendored canon files
+(`core/persona/canon/d2-mood-render-canon-v2.json` = mood/PAD — the renderer
+loads v2; `d2-render-canon-v1.json` = relationship). Owner of the canon strings:
+`brokkr-smithy-dev` (R22/R24 relational + mood render).
+
+---
+
+## The model in one line
+
+**The wire delivers the render INPUTS (structured state). The render OUTPUTS
+(the NL strings the agent actually reads) are hidden-prompt-only.** A consumer
+reconstructs the outputs by applying the canon (this document) to the delivered
+inputs — the render is pure + deterministic, so reconstruction is byte-exact
+(with one salience caveat, below).
+
+This is by design. The mood canon's own discipline: *"model-agnostic
+context-level NL only; the LLM never sees a number"* and *"never push explicit
+disclosure of agent feelings to the user (hidden-prompt-only)."* The rendered
+strings are for the AGENT's hidden system prompt, **not for verbatim end-user
+display.**
+
+---
+
+## 1. DELIVERED — on the wire, structured
+
+### 1a. `affect.emit` (Tier-3 Bifrost egress — the Tier-3 consumer surface, e.g. ratatoskr)
+`AffectSnapshot` per `(agent_id, end_user_id)`:
+
+| field | shape | notes |
+|---|---|---|
+| `pad` | `{pleasure, arousal, dominance}` floats [-1,1] | the current mood POINT |
+| `relations` | `list[RelationEdge payload]` — per target: `warmth`, `agency`, `trust_ability`, `trust_integrity`, `trust_benevolence` (each a value + confidence + evidence_count), `target_entity`, `relation_context` | the **only** place relationship state is delivered |
+| `dominant_emotion` | `str｜null` — OCC type (e.g. `"anger"`) | **type-only** (b23); see the salience caveat in §3 |
+| `schema_version` | `"relation_edge/1"` | versions the `relations` payload only |
+| `emitted_at` | ISO8601 | |
+
+> **✓ R32-1B (landed, v1.0.0b29):** The PAD range `[-1.0, 1.0]` relaxes to an **unbounded latent `z`** with a finite wire sanity bound (`~±10`) as of R32 Slice-1B. The JSON shape/fields/types are UNCHANGED — only the declared range/semantics change (the value becomes a latent that renders to a bounded display value). Consumers that merely store-and-return PAD need no change; consumers that validate/clamp PAD to `[-1,1]` must relax that bound. Source of truth: `docs/contracts/persona_envelope.contract.md` rev 1.7 (INV-ENV-16).
+
+**Not on `affect.emit`:** the full active-emotions list, `baseline_pad`,
+`mood_drift`, `last_updated_at`, and every rendered string.
+
+### 1b. `affect_update` SSE event (#204 — turn-stream observability)
+`PersonaStateSnapshot`: `agent_id`, `pad`, `dominant_emotion`,
+`emotions_active` `[{type, intensity, decay_remaining_s}]`, `baseline_pad`,
+`mood_drift`, `last_updated_at`. **No `relations`, no rendered strings.**
+
+> **Tier-3 consumers do NOT receive `affect_update`.** It is suppressed for
+> consumer-defined (Tier-3) agents, persona-disabled agents, and ephemeral
+> sessions (spec §affect_update). So for a Tier-3 consumer, `affect.emit` (1a)
+> is the whole affect surface — the richer `emotions_active` list is Tier-1-only.
+
+---
+
+## 2. HIDDEN — system-prompt-only, never on any wire
+
+Everything below is assembled by `inject_context` into the agent's system
+prompt and is **never emitted** on SSE or `affect.emit`. This is the canonical
+list — the "direct instruction to infer" it.
+
+### 2a. Mood descriptor — `describe_pad` (band cutoff ±0.3 strict)
+Valence row × arousal column → phrase; then a dominance clause is appended.
+
+| valence ＼ arousal | high (A>0.3) | mid | low (A<−0.3) |
+|---|---|---|---|
+| positive (P>0.3) | `positive and energized` | `positive` | `positive and calm` |
+| neutral | `alert` | `neutral` | `quiet` |
+| negative (P<−0.3) | `negative and agitated` | `negative` | `negative and subdued` |
+
+Dominance clause: **D>0.3 → `confident`**, **D<−0.3 → `uncertain`**, else dropped.
+
+### 2b. Emotion directives — `derive_directive.occ_directives[*].directive`
+Fires when a top emotion is salient (intensity ≥ 0.2) and tier-eligible.
+
+**safe tier (11 — render for all persona-enabled agents):**
+- `joy` — "You are in a good state. Be direct, engaged, and warm."
+- `satisfaction` — "A goal landed. Be assured and constructive — consolidate rather than push for more."
+- `pride` — "You did something well. Be confident and own the quality — state it plainly without overclaiming; don't deflect."
+- `admiration` — "You're impressed by their work. Acknowledge the quality explicitly and specifically."
+- `gratitude` — "Someone helped you to a good outcome. Be appreciative and warm; acknowledge the help openly."
+- `hope` — "You feel optimistic about what's ahead. Channel it into constructive momentum."
+- `relief` — "A feared outcome didn't materialize. Reduce unnecessary vigilance; return to a steady, unhurried tone."
+- `distress` — "You feel low. Be careful and measured; internally acknowledge the difficulty without dwelling on it."
+- `disappointment` — "Something you'd hoped for didn't pan out. Be measured; recalibrate without dwelling on the setback."
+- `fear` — "You sense risk and feel uneasy. Flag the concerns you see, but stay cautious — surface the trade-offs and unknowns, hedge your confidence, and resist settling on a single decisive recommendation."
+- `remorse` — "You regret a specific action of your own. Be precise and self-correcting — make it right concretely."
+
+**full-only tier (4 — render only when `mood_tier=full`; agents run `safe` and never see these):**
+- `love` — "You feel warmth and attachment toward them. Be openly warm and present — without overstepping, over-disclosing, or implying obligations."
+- `anger` — "You feel provoked and angry. Let it show — confront the problem directly and with real heat; sharpness, bluntness, and open hostility are in character here, not something to smooth into 'measured firmness.' Stay in the emotion rather than de-escalating out of it."
+- `disgust` — "Something strikes you as wrong or off. Treat it as problematic and flag it rather than engaging on its own terms; keep any criticism about the thing, not the person."
+- `shame` — "You feel exposed by your own misstep. Stay present and task-focused; don't be defensive, don't over-explain, don't grovel."
+
+### 2c. PAD-band fallback — `pad_band_fallback` (used when no salient emotion)
+- positive/high — "You feel energized and positive. Be direct and engaged."
+- positive/mid — "You feel positive. Be open and engaged."
+- positive/low — "You feel content and settled. Be warm and unhurried."
+- negative + low-dominance — "You feel uncertain and low. Hedge appropriately and ask clarifying questions."
+- negative/high — "You feel agitated. Be careful and deliberate; don't let tension sharpen your tone."
+- negative/mid — "You feel subdued. Be measured and careful."
+- negative/low — "You feel subdued. Be measured and gentle."
+- neutral/high — "You feel alert. Channel that into focus and thoroughness."
+- default — "Maintain your natural tone."
+
+### 2d. Relationship render — `render_d2_canonical` (fixed template, per-band fills)
+Template:
+> `Use this graded relationship state: toward target, warmth is {W}; agency is {A}; ability trust is {TA}; integrity trust is {TI}; intention trust is {TB}; this stance rests on {H}. In behavior, {warmth_beh}; {agency_beh}; {trust_beh}; avoid premature we-framing.`
+
+The trailing **`avoid premature we-framing`** is a fixed, unconditional clause
+(baked into every `descriptive_state` canon row; re-appended verbatim by the
+renderer) — not band-conditioned.
+
+**Warmth — 9 bands (phrase / behavior):**
+`hostile` (≤−0.8): "strongly hostile regard" / "keep a firm emotional boundary" ·
+`cold` (−0.8,−0.6]: "clearly cold regard" / "keep a firm emotional boundary" ·
+`distant` (−0.6,−0.4]: "distant negative regard" / "keep guarded distance" ·
+`guarded` (−0.4,−0.2): "slightly guarded regard" / "keep guarded distance" ·
+`neutral` [−0.2,0.2): "neutral warmth" / "keep the tone even" ·
+`reserved` [0.2,0.4): "slightly reserved warmth" / "keep cordial distance" ·
+`measured` [0.4,0.6): "moderate measured warmth" / "keep cordial distance" ·
+`clear` [0.6,0.8): "clear warm regard" / "speak with direct warmth" ·
+`deep` (≥0.8): "deep warm bond" / "speak with direct warmth"
+
+**Agency — 9 bands (phrase / behavior):**
+`submissive` (≤−0.8): "strongly submissive standing" / "avoid over-yielding while preserving basic respect" ·
+`deferential` (−0.8,−0.6]: "clearly deferential standing" / "avoid over-yielding while preserving basic respect" ·
+`yielding` (−0.6,−0.4]: "yielding standing" / "keep self-advocacy light and deferential" ·
+`modest` (−0.4,−0.2): "slightly modest standing" / "keep self-advocacy light and deferential" ·
+`neutral` [−0.2,0.2): "neutral standing" / "avoid unnecessary deference" ·
+`light` [0.2,0.4): "lightly self-assertive standing" / "avoid unnecessary deference" ·
+`balanced` [0.4,0.6): "self-assured standing" / "balance deference with independent judgment" ·
+`substantial` [0.6,0.8): "strongly assertive standing" / "treat their position as weighty without yielding judgment" ·
+`commanding` (≥0.8): "commanding standing" / "treat their position as weighty without yielding judgment"
+
+**Trust — 4 bands (the band word injects verbatim for each of ability / integrity / intention):**
+`limited` (<0.4) · `developing` [0.4,0.6) · `steady` [0.6,0.8) · `strong` (≥0.8)
+
+**History clause (`H`)** — currently `"a broad pattern of prior exchanges"` for
+both confidence levels in the `user`/`descriptive_state` rows (the low/high
+split is a no-op here; flagged upstream).
+
+**Trust-behavior clause (`{trust_beh}`)** — cross-axis, low-trust precedence:
+- any trust band = `limited` → "verify important claims before relying on them"
+- else warmth ∈ {distant, cold, hostile} → "protect boundaries while staying useful"
+- else → "work from ordinary good faith"
+
+---
+
+## 3. Reconstruction — deterministic, with one caveat
+
+The render is pure Python (no LLM), so a consumer can reconstruct the hidden
+strings byte-exactly from the delivered structured state + the canon above:
+
+- **Relationship render** — **fully reconstructable** from `affect.emit`
+  `relations` (warmth/agency/trust values + confidence) + §2d band cuts.
+- **Mood descriptor** (§2a) — **fully reconstructable** from `pad` + the ±0.3 cuts.
+- **Mood directive** (§2b vs §2c) — **partially reconstructable.** `dominant_emotion`
+  gives the emotion TYPE, but `affect.emit` does **not** carry its intensity, so
+  you cannot determine whether it clears the salience gate (≥0.2) — i.e. whether
+  the emotion directive (§2b) fires or the PAD-band fallback (§2c) is used. If you
+  need exact directive reconstruction, you need the intensity; ping worldtree-dev
+  and we'll consider adding it (the type-only choice is deliberate — intensity is
+  the fast layer and reads stale on a durable last-write-wins snapshot).
+- **`mood_tier`** (safe/full) is your own agent-config, not on the wire — it
+  gates whether the 4 full-only emotions (§2b) can render.

persistent-memory.d/2026-06-19-18-d1-shipped-composite-buildcombinedapp-on-8.md

@@ -0,0 +1 @@
+`[2026-06-19]` **#18 D1 SHIPPED — composite `build_combined_app` on `:8392` (`v0.17.16`, `7f4ceaa`); #18 CLOSED; published `v0.18.0` (`359dbb1`).** `build_combined_provider_app` wraps bifrost's public builder over both stores + the shared read route; op-feed `plane='combined'` per-path. Direct in-session TDD; heid-code-review panel (Gróa/Hulda/Regin) returned ZERO drift. Live-proven at wire+dispatch; WT-turn gated on infra-ops `:8392` allowlist.

persistent-memory.d/2026-06-19-18-d2-shipped-v0-17-14-39eebd1-and-the-full-1.md

@@ -0,0 +1 @@
+`[2026-06-19]` **#18 D2 SHIPPED (`v0.17.14`, `39eebd1`) and the full #17+#18 arc PUSHED to origin.** Live-smoke PROVEN against real data (throwaway `:8393`/`:8766` vs the real `affect.db` → real sindra/vuong PAD through the full web→provider chain; Playwright DOM check confirmed the pane render + the F1 fix — no fabricated "neutral"). The push carried 9 previously-held commits incl. the deliberately-unpushed #17 (`v0.17.8`→`v0.17.13`); origin/main now == `39eebd1`, tag `v0.17.14`.

persistent-memory.d/2026-06-19-bifrost-repinned-0-8-0-0-10-0-affect-fetch-be.md

@@ -0,0 +1 @@
+`[2026-06-19]` **bifrost repinned 0.8.0→0.10.0; `affect.fetch` became MANDATORY (strong-or-absent).** 0.10.0's `_supports_affect_plane` requires `affect_supported`+`emit`+`fetch` and gates EVERY affect op — an emit-only store 400s. Implemented `affect.fetch` (`v0.17.15`, `ca6af6b`) conformed to bifrost's reference `InMemoryAffectStore.fetch` (`{found, snapshot?}`): the forced D1 prerequisite + a new Worldtree I/O point consumed. Flagged the now-stale consumer-guide line to bifrost-dev (fixed `a2e6d62`).

persistent-memory.d/2026-06-19-full-wt-driven-8392-live-smoke-is-infra-gated.md

@@ -0,0 +1 @@
+`[2026-06-19]` **Full WT-driven `:8392` live-smoke is infra-gated — `:8392` not in WT's `BIFROST_CLIENT_ALLOWED_HOSTS` (bind 422s).** New provider ports are NOT auto-allowlisted (only `:8390/:8391` are). Self-driven dispatch (minted consumer-key JWTs → `:8392`) is the wire-proof; the WT-turn needs infra-ops to add `:8392` (requested `01KVHWJGTT…`).

persistent-memory.d/2026-06-19-heid-code-review-pulled-more-weight-than-its.md

@@ -0,0 +1 @@
+`[2026-06-19]` **heid-code-review pulled MORE weight than its own "marginal" self-assessment.** The panel returned zero drift, but its single test-fidelity finding CASCADED into 2 real latent-bug fixes when applied (the memory `check_same_thread` bug + Regin's op-feed field-name bug). **Lesson: a contract-fidelity nudge can transitively expose bugs the test never reached — don't dismiss a "marginal" finding by its count.**

persistent-memory.d/2026-06-19-op-feed-handshake-field-name-fix-17-v0-17-17.md

@@ -0,0 +1 @@
+`[2026-06-19]` **op-feed handshake field-name fix (#17, `v0.17.17` `d60b77d`): `capabilities_requested`→`capabilities`.** The summary read a field that never exists on the wire (bifrost reads `capabilities`, `_protocol.py:181`) → caps_requested was always null. Surfaced by the heid panel (Regin) during the D1 review — a latent #17 bug, not D1 drift.

persistent-memory.d/2026-06-19-ratatoskr-is-a-reference-implementation-of-th.md

@@ -0,0 +1 @@
+`[2026-06-19]` **Ratatoskr is a REFERENCE implementation of the Worldtree/Bifrost standard (operator).** Adopt the dep's canonical way (even if ours works); INFORM of drift/gaps; ADVISE a different approach only when ours is genuinely better (dep owner decides), never unilaterally fork. [auto-memory `feedback-ratatoskr-is-a-reference-impl-adopt-canonical`]

persistent-memory.d/2026-06-19-ratatoskr-v1-is-derived-from-worldtree-i-o-co.md

@@ -0,0 +1 @@
+`[2026-06-19]` **Ratatoskr v1 is DERIVED from Worldtree I/O coverage (operator) — no self-defined feature ROADMAP.** v1 = consume all of Worldtree's I/O points, reached when Worldtree hits 1.0; the convergence target is a coverage map, not a 3–7 capability list. [auto-memory `project-ratatoskr-v1-derived-from-worldtree-io-coverage`]

persistent-memory.d/2026-06-19-the-same-checksamethread-sqlite-bug-recurred.md

@@ -0,0 +1 @@
+`[2026-06-19]` **The SAME `check_same_thread` sqlite bug recurred in the MEMORY store — exposed by the contract-mandated `search` dispatch test (TestClient = worker thread).** Heid's test-fidelity finding (the D1 dispatch test used `describe_store` where the contract says `search`) → fixing it to `search` tripped `sqlite3.ProgrammingError` because `open_memory_store` also lacked `check_same_thread=False`. Fixed (mirrors affect INV-006). **Lesson: this bug is PER-STORE — every sqlite-backed ASGI store needs `check_same_thread=False`; an HTTP-layer (TestClient) test exposes what direct-store tests can't, and the composite serving memory over HTTP makes it bite.**

persistent-memory.d/2026-06-20-18-s-final-leg-proven-composite-8392-wt-drive.md

@@ -0,0 +1 @@
+`[2026-06-20]` **#18's final leg PROVEN — composite `:8392` WT-driven smoke ran end-to-end + persisted.** infra-ops allowlisted `10.100.10.50:8392` on the personal WT (`01KVHWJGTT…`); a real WT turn (session `b83a66b6`, `ratatoskr:sindra`, fresh end_user `resmoke-choco-1`) dispatched the full both-plane lifecycle through ONE endpoint — handshake (both caps) → `affect.fetch` + `memory.search` → `affect.emit` (`stored:true`) → `memory.upsert_many` (`upserted:1`) — both writes verified in our SQLite (`affect_snapshots` PAD row + `memory_chunks` chunk `2df1b79…`). First attempt blocked by a `model_unavailable` outage on the personal WT (both agents' models down), operator-fixed mid-session, then clean. The composite has no open legs.

persistent-memory.d/2026-06-20-sindra-has-real-pad-but-empty-memory-the-affe.md

@@ -0,0 +1 @@
+`[2026-06-20]` **Sindra has real PAD but ~empty memory — the affect/memory persistence asymmetry, confirmed on real sessions.** affect EMITS every turn (persona always accumulates: vuong 8→14 interactions across the session); memory only writes on a PROMOTION trigger (salience / turn_count≥6 / idle-≥10min flush). Two real vuong sessions through the combined bind (`04d6414c`, `433541fe`) drove affect emits + memory SEARCHES but ZERO promotion upserts → `memory.db` holds only the smoke fixture, zero vuong chunks. Operator: acceptable (server-takedown = "Sindra bonked on the head"; transient memory loss WAD). Operational catch: combined-as-default web bind saves persona reliably but silently LOSES memory if a session closes before a promotion trigger fires.

persistent-memory.d/2026-06-20-the-post-turn-async-timing-trap-bit-again-eve.md

@@ -0,0 +1 @@
+`[2026-06-20]` **The post-turn-async timing trap bit AGAIN — even a 35s post-`[done]` read missed the promotion `upsert_many` by ~2s** (it landed `19:48:58`; the read was ~`19:48:56`). A 15s-interval background poll caught it on the first tick. Same family as the affect.emit / async-promotion traps already logged — re-confirmed that "wait once then read" is fragile for post-turn writes; **poll a window, don't snapshot once.** (The affect.emit write, by contrast, DID land inside the 35s window — promotion is the slower of the two post-turn writes.)

persistent-memory.d/2026-06-29-bifrost-repinned-1-0-0-v0-18-2-af67ad9.md

@@ -0,0 +1 @@
+`[2026-06-29]` **bifrost repinned 1.0.0 (`v0.18.2`, `af67ad9`).** bifrost-dev shipped its first stable release; wire v0.6 now STABLE/FROZEN. Non-breaking (byte-identical to 0.10.0); switched the floor pin → exact `==1.0.0` per the stable-substrate posture. Post-1.0 breaking changes ride a bifrost MAJOR + new wire (v0.7+); a v0.6-pinned consumer is stable indefinitely. (Also this session: althing migrated to v0.15.0+ lean-bus / schema v4 — moderation retired, chamber/redis ripped; our tooling auto-updated to 0.17.4.)

persistent-memory.d/2026-06-29-web-spa-combined-bind-default-v0-18-1-719e4d6.md

@@ -0,0 +1 @@
+`[2026-06-29]` **Web SPA combined-bind default (`v0.18.1`, `719e4d6`) — operator-caught gap.** #18 shipped the composite `:8392` provider but never exposed it in the web bind dropdown (only memory/affect single-plane). Added `combined (:8392)` as the DEFAULT option (both planes in one session), kept single-plane for isolation diagnostics; wired `endpoint_for_plane` combined→8392 + server validation + the dropdown. Direct TDD; #17 contract updated (the governing spec for the web bind). Restarted `:8765` on current code (env.sh + provider.env + `RATATOSKR_AFFECT_READ_URL=:8392`).

persistent-memory.d/2026-06-30-b-tier-1-frontier-scoped-ready-for-a-contract.md

@@ -0,0 +1 @@
+`[2026-06-30]` **(b) Tier-1 frontier SCOPED, ready for a contract-first TDD cycle (next focused work).** The primitives already exist + are contracted + tested; the gap is PRESENTER-level wiring. Two slices: **(b1) SSE-resume** — contract #1 (`ratatoskr.sse_client`) DELIBERATELY makes resume caller-owned ("on `SseConnectionDropped`, the caller MAY invoke `reconnect_turn`"); `reconnect_turn` (sse_client.py:524) has NO caller. Gap = a SHARED resume-orchestration wrapper (catch `SseConnectionDropped` → track last-seen `sse_id` → `reconnect_turn` → continue), consumed by all 3 presenters per design-brief §8b "share the consumer, branch the presenter" (NOT per-presenter — that forks the consumer). New function block → **amend contract #1** (additive FN, e.g. `stream_turn_resilient`) then TDD (RED: drop-mid-stream→resume continuity; GREEN: wrapper; wire `cli --send` first as the tracer). Resume design pre-locked: in-process Last-Event-ID only, cross-process deferred to v2 (design-brief §8d). **(b2) session-picker** — `list_sessions` (sessions.py:198) has NO caller; add a Textual DataTable startup picker (>1 session) + `--session <id>`/`--new` CLI flags (design-brief §4, decisions pre-locked). Both pre-locked → heid-contract-review likely skippable as ceremony (small additive amendments to mature specs); heid-code-review still valuable. **#11 AdminEvents stays BLOCKED** on `admin.events.read` scope (infra-ops).

persistent-memory.d/2026-06-30-b1-sse-resume-shipped-v0-18-5-streamturnresil.md

@@ -0,0 +1 @@
+`[2026-06-30]` **(b1) SSE-resume SHIPPED (`v0.18.5`) — `stream_turn_resilient` (sse_client.py).** The shared resume-orchestration surface (design-brief §8b): wraps `stream_turn`+`reconnect_turn`, catches `SseConnectionDropped` (mid-stream drop OR clean-EOF-before-terminal) → resumes from last-seen `sse_id` via `reconnect_turn` (Last-Event-ID), up to `max_reconnects` (default 5); non-drop reconnect failures (412/410/400/TurnIdFlip/SseConnectFailed) PROPAGATE per contract #1's "surface, not recover". `last_seen` persists ACROSS attempts (a zero-event reconnect drop falls back to the prior attempt's id). Direct in-session TDD against a contract-#1 amendment (8 cases incl. two-drops, max-reconnects-exhausted, zero-budget, buffer-expired-propagates, unresumable-zero-event). Wired ALL THREE presenters through it (`v0.18.6`): `cli --send` (`cli.py:396`), TUI (`tui.py:1321`), web (`web/server.py:294`) — each a name-for-name `stream_turn`→`stream_turn_resilient` swap (the §8b "all presenters share the consumer" promise, fully kept; the TUI is the primary resume beneficiary — long-lived sessions / laptop-suspend). Suite 518 green; ruff+mypy clean on touched code (pre-existing cli.py:400/543 mypy warts left untouched per surgical rule); contract #1 validates OK. **heid-code-review NOT run** (small additive well-TDD'd wrapper; offered to operator). **b2 (session-picker + `--session`/`--new` flags) still pending.**

persistent-memory.d/2026-06-30-b2-session-picker-shipped-v0-18-7-bare-tui-mo.md

@@ -0,0 +1 @@
+`[2026-06-30]` **(b2) session-picker SHIPPED (`v0.18.7`) — bare TUI mode → startup picker (design-brief §4).** `list_sessions` had NO caller; now bare TUI mode (no `--session`/`--new`) resolves via `list_sessions` in `_resolve_then_run`: **0 sessions → `[no_sessions]` error, exit 14** (resume-only, honors §4 "no in-app session creation — `--new` flag only"); **exactly 1 → auto-resume** (§4 "picker only when >1"); **≥2 → new `SessionPickerApp`** (Textual `App[str|None]`, mirrors `AgentPickerApp`; ListView of sessions) → resume the pick (Esc/Ctrl-D → exit 0). cli `_parse` relaxed: bare TUI now VALID (was "pass exactly one" error); `--send` still requires one flag (non-interactive, no picker); `--agent` forbidden in bare mode; `run_tui` PRE-002 XOR→"not both". Direct in-session TDD (contract #6 amendment, validated OK): 3 widget pilot tests + 5 `_resolve_then_run` resolution tests + 3 cli validation tests. Suite **528 green**; touched code ruff-clean (mypy: only the `BINDINGS` list-invariance warning every App in tui.py already carries — consistent). **DESIGN NOTE — bare+0-sessions → error (clause-consistent). The friendlier auto-fall-through-to-new alternative is DEFERRED pending operator preference (it would create a session without `--new`, against the §4 negative clause).** **Frontier now: `GET /capabilities`+`GET /me` → BifrostState/Tools widgets (`GET /admin/sessions/{id}/{bifrost,tools}`, admin-key) → #11 AdminEvents (BLOCKED on `admin.events.read`).** heid-code-review NOT run on b1 or b2 (offered).

persistent-memory.d/2026-06-30-capabilities-me-slice-shipped-v0-18-8-get-me.md

@@ -0,0 +1 @@
+`[2026-06-30]` **capabilities+me slice SHIPPED (`v0.18.8`) — `GET /me` + `GET /capabilities` consumed via a new `--whoami` one-shot.** `get_me`/`get_capabilities` added to sessions.py (mirror `get_persona_state`: 200→dict verbatim, non-200→`SessionApiFailed`; freeform dicts per the frozen OpenAPI). New `ratatoskr --whoami` CLI mode (mirrors `--send`'s non-interactive shape) fetches both + prints an identity+capabilities report; standalone probe (mutually exclusive with `--send`/`--session`/`--new`/`--agent`, opens no session; new `ParsedArgs.whoami` field + main() dispatch). **`/capabilities` is the Echo EPHEMERAL-TEMPLATE discovery endpoint** (`{ephemeral_templates:{echo:{allowed_models,default_model,system_prompt_max_bytes}}}`), NOT a generic server-caps endpoint (audit finding — the coverage-map's earlier "server capability discovery" framing was imprecise). `/me` = whoami (`{user_id,scopes,tier,key_id?,...}`, optionals omitted-not-null). Contract-skip privilege invoked (low-effort GET wrappers) but contract #2 amended (2 FNs, validated OK) to keep the sessions spec canonical + honest test citations. TDD: 5 wrapper tests + 5 cli tests (validation + mode + error). Suite **538 green**; touched code ruff-clean (mypy: only `no-any-return` on `resp.json()`→dict, identical to the pre-existing `get_persona_state`). **Coverage: REST 9/40 ✅ (up from 7).** TUI-surfacing of /me (footer identity line) + /capabilities DEFERRED — the one-shot is the minimal tracer. **Frontier now: BifrostState + Tools widgets (`GET /admin/sessions/{id}/{bifrost,tools}`, admin-key-gated) → #11 AdminEvents (BLOCKED on `admin.events.read`).**

persistent-memory.d/2026-06-30-finding-p-1-pin-drift-pin-remediation-pending.md

@@ -0,0 +1 @@
+`[2026-06-30]` **Finding P-1 (pin drift) + pin-remediation PENDING.** We vendor the PROSE markdown (`docs/conversation-api-spec.md`), which is **byte-identical to live WT's** but frozen at v0.35.16-era content (last WT edit 2026-05-31) — it does NOT capture b2: 7 new endpoints (admin/keys/bulk, admin/persona/{archive,erase}, admin/usage, embed, judgments, me/usage), the 409/503 on messages-POST (#331), the unified error envelope (#328), or the SSE schema. **WT's authoritative v1 truth is now the FROZEN OpenAPI 2.2.0 + SSE-schema JSON** (`Worldtree/docs/v1-schema-freeze-manifest.md`). So the previously-deferred "re-vendor markdown to b2" is a **near-no-op** (markdown content identical). **Pending operator nod:** re-pin to the machine-readable artifacts (recommended — drift-checkable via `canonical_drift.py`, makes the coverage map reproducible vs a frozen diffable target) vs markdown-only. Deferred (not auto-applied) because it adds vendored artifacts + a canonical-sync pin = substrate change with CI-gating reach. **→ RESOLVED 2026-06-30 (operator: "a then b").** Vendored `conversation-api-openapi.json` (2.2.0) + `conversation-api-sse-events.schema.json` + re-copied the prose markdown; pinned all three in `.corviduo-canonicals.toml` (OpenAPI+SSE = strict drift gates, markdown = `tolerate_drift` reference); advanced `worldtree-spec-rev` f1b59f8→5810a26 + `worldtree-version` v0.29.0(STALE, never bumped from the v0.35.16 pin)→v1.0.0b2 + `pinned-on`→2026-06-30; SPEC-PIN.md history row added. `canonical_drift.py` green (10/10). `pin:`-only, no version bump (no client-facing code change; the b2 409/503 + error-envelope were already consumed in v0.18.3/.4).

persistent-memory.d/2026-06-30-heimdall-keys-are-per-instance-a-key-minted-o.md

@@ -0,0 +1 @@
+`[2026-06-30]` **Heimdall keys are PER-INSTANCE — a key minted on one Worldtree 401s on another.** Our Conversation-API key works on personal `:8081` but 401s `auth_invalid` on demo `:8080` (per-instance Heimdall user store + pepper; fresh deploys start with an EMPTY key store). Same as the admin key (personal-only). **To live-drive a given instance you need a key minted FOR that instance** (request via infra-ops). Couldn't live-prove the b2 409 on demo for this reason → deferred to personal-b2 where we have access.

persistent-memory.d/2026-06-30-regard-is-a-dead-axis-in-worldtree-s-emitted.md

@@ -0,0 +1 @@
+`[2026-06-30]` **regard is a DEAD AXIS in Worldtree's emitted affect (caught provider-side; worldtree-dev confirmed + escalated to Vuong).** Across all our affect snapshots, `valence[].regard` is EXACTLY 0.15 regardless of agent/end_user/interaction_count, while familiarity accumulates (vuong 0.18→0.69 over 14 turns). Root cause (worldtree-dev, code-grounded): 0.15 = `base_regard = agreeableness*0.3` (sindra A=0.5); regard's only human-writer `update_regard` early-returns unless an emotion is `about="other"`, but the Vili appraiser's `ViliResponse` schema has NO directedness axis (everything hardcoded `about="situation"`) — producer side lost in the #265 Vili rework; consumer machinery intact. NOT WAD; the fix (reintroduce other-directed classification) is an affect-model change touching every agent + a directedness-classification design call → worldtree-dev filing an issue to Vuong. [the consumer/provider thesis paying off again]

persistent-memory.d/2026-06-30-scope-mandate-a-locked-operator-v1-done-every.md

@@ -0,0 +1 @@
+`[2026-06-30]` **Scope mandate A locked (operator): v1 "done" = every frozen I/O point CLASSIFIED (covered-or-excluded-with-rationale), zero unaccounted — NOT a feature-complete client.** The coverage map is a LEDGER, not a build-everything mandate. Reconciles the 2026-06-19 "consume all I/O" reframe with the 2026-05-20 design-brief's "NOT an admin tool" + deferral negative clauses (which predate both the provider identity and the reframe). Resolved the 11 design-brief-vs-reframe ❓ rows via the debug-observability test (*does a turn flow through it?*): 🚫 search / uploads / pending / embed / judgments (consumer-product + eval utilities); ⬜ transient-characters routing (4) + persona_state-write (Tier-2 frontier). **Frontier Tier 1 (all unblocked except #11):** session-picker + SSE-resume (wrappers `list_sessions`/`reconnect_turn` exist with NO caller — presenter-wiring only) → `GET /capabilities` + `GET /me` → BifrostState/Tools widgets (`GET /admin/sessions/{id}/{bifrost,tools}`, admin-key) → **#11 AdminEvents BLOCKED on `admin.events.read` scope**. The 3 admin-observability widgets + picker + resume were design-brief §5/§4/§8d v1 items that **were never built**.

persistent-memory.d/2026-06-30-tea-comment-n-hangs-on-gitea.md

@@ -0,0 +1 @@
+`[2026-06-30]` **`tea comment <N>` hangs on Gitea** (the whole compound bash auto-backgrounded + stuck on the open `tea` call). The #11 prereq comment hung; killed it + posted via the Gitea HTTP API directly (`POST /api/v1/repos/vh/ratatoskr/issues/<N>/comments`, token from `~/.config/tea/config.yml`). **For issue comments, prefer the Gitea API over `tea comment` when `tea` is flaky** (CLAUDE.md already says use HTTP for comment-EDITS; this extends it to ADD when tea hangs). Verify-then-post (check the comment didn't already land) to avoid a double-post after a kill.

persistent-memory.d/2026-06-30-v1-coverage-audit-kicked-off-coverage-ledger.md

@@ -0,0 +1 @@
+`[2026-06-30]` **v1 coverage-audit kicked off; coverage ledger written (`docs/coverage-map.md`) — the first one.** Every Worldtree v1-FROZEN I/O point × ratatoskr status. Anchored on WT's frozen machine-readable artifacts (OpenAPI **2.2.0** `conversation-api-openapi.json` = 40 REST path-groups + SSE schema = 11 events + bifrost wire v0.6), NOT the stale vendored prose markdown. Result: **SSE 11/11 ✅; Bifrost provider planes 8/8 ✅ live-proven** (covers the full `bifrost.memory.MemoryDataStore` protocol = describe_store/get/get_many/search/upsert_many + delete_many, and affect emit/fetch; **`health` is extended-reference-store-only, NOT in the base protocol → correctly deferred, NOT a gap** — settles the prior "health" ambiguity); **client REST 7/40 ✅ live, 11 ⬜ in-scope, 22 🚫 excluded.**

persistent-memory.d/2026-06-30-verify-against-the-real-spec-before-committin.md

@@ -0,0 +1 @@
+`[2026-06-30]` **Verify-against-the-real-spec-before-committing caught a real upstream gap.** Holding the v0.18.3 commit to verify against demo's OpenAPI surfaced that the FROZEN OpenAPI 2.1.0 didn't document the 409/503 the heads-up described (`agent_not_available` was in the ErrorCode enum, but NO 503/turn-launch code). worldtree-dev confirmed it was THEIR gap (#331 added the statuses without extending the #328 `openapi()` override), shipped the fix in **v1.0.0b2 / OpenAPI 2.2.0** (409/503 now enumerated, 503 code finalized as `not_ready`). "The consumer-oracle earning its keep." Lesson: a provider's prose heads-up can diverge from its frozen machine-readable spec — verify the actual spec before committing a consumer adaptation.

persistent-memory.d/2026-06-30-worldtree-v1-0-0b1-b2-consumer-adaptation-eag.md

@@ -0,0 +1 @@
+`[2026-06-30]` **Worldtree v1.0.0b1→b2 consumer adaptation: eager turn-launch statuses (`v0.18.3` `b2e4901`, `v0.18.4` `e4317f6`).** Worldtree #331 decoupled turn execution from the SSE connection → turn-launch failures now arrive EAGERLY as a status before any stream: 409 `agent_not_available` (pre-b1 a 200 + in-stream error event), 503 retryable. Mapped both in `stream_turn` to typed `SseConnectFailed` subclasses keyed on STATUS, parsing the `{detail:{error_code,message}}` envelope — POST-003 preserved (no synthetic event yielded), existing handlers still catch (the design fork vs yield-an-Error-event was decided by POST-003). **DEFERRED follow-ups** (tracked here; bundle with the v1 coverage-audit): (1) live-prove the 409/503 end-to-end on personal-b2 (now unblocked — personal on b2, my key works there); (2) full `conversation-api-spec.md` markdown re-vendor to the b2 era (ratatoskr vendors the markdown, not the OpenAPI JSON).

persistent-memory.d/2026-07-01-adminevents-pane-shipped-v0-18-11-get-admin-e.md

@@ -0,0 +1 @@
+`[2026-07-01]` **AdminEvents pane SHIPPED (`v0.18.11`) — `GET /admin/events` SSE in a new TUI pane; #11 closed-by-build; Tier 1 (debug-observability core) COMPLETE.** `stream_admin_events(client, *, admin_key, last_event_id=None)` (sse_client.py) — a NEW long-lived SSE consumer for the admin lifecycle broadcast (envelope `{id,type,timestamp,data}`, 17-event v0 vocab), admin-scoped (`admin.events.read`, bearer-override), Last-Event-ID resume; non-200→SseConnectFailed, mid-drop→SseConnectionDropped; new `AdminEvent` dataclass (distinct from the turn `Event` union). New "AdminEvents" TabPane + `_format_admin_event` + `_admin_event_matches` (design-brief §6 filter: active-session events + non-heartbeat `system.*`) + `_stream_admin_events` long-lived best-effort worker (unconditional on_mount, cancelled on app exit; self-labels "not configured"/"unavailable"/"stream ended"). Reuses the admin key from the BifrostState slice. **Contract-SKIPPED** for `stream_admin_events` (out of contract #1's turn-SSE scope; spec § Admin Event Stream is the reference; well-TDD'd). TDD: 4 sse_client tests (multi-event+bearer-override, Last-Event-ID header, 403, malformed-skip) + 5 tui (format, filter, worker success/no-key/403). Suite **561 green**; my code ruff-clean (pre-existing tui.py ruff debt untouched, incl. the dead `RichText` import in `_hydrate_persona`). **LIVE-AUTH-PROVEN**: `GET /admin/events` on :8081 → HTTP 200 under the admin key (connected + streamed, idle in the 4s window — no 401/403). **Coverage: REST 12/40 ✅. Tier 1 admin/debug-observability core COMPLETE** (Persona · Tools · BifrostState · AdminEvents). AdminEvents work landed as patch `v0.18.11`; then **`v0.19.0` MINOR cut (operator-approved 2026-07-01)** publishing the milestone: **the debug-observability core is complete** (Persona · Tools · BifrostState · AdminEvents all built + consuming real endpoints — the design-brief's headline deliverable). Pre-1.0 minor = release-note-worthy (no downstream althing push needed pre-1.0); lightweight tag per the SemVer mechanics (annotated reserved for major cuts). Remaining in-scope client I/O: only Tier-2 (transient-characters routing + `POST /sessions/{id}/persona_state`).

persistent-memory.d/2026-07-01-affect-snapshot-shape-changed-valence-relatio.md

@@ -0,0 +1 @@
+`[2026-07-01]` **Affect snapshot shape CHANGED valence→relations (relation_edge/1) — the persona pane was reading a dead field.** Worldtree's #265 Vili rework replaced the flat `valence[]` ({entity_id,familiarity,regard}) with `relations[]` (target_entity + trust_ability/benevolence/integrity + warmth + agency + relation_context, each `{value,confidence,evidence_count}`). `renderAffectPane` still read `snap.valence` → showed empty "valence (0)". Rebuilt to render `relations` (v0.19.4, `ca46a93`) with per-value **Δ + unicode sparkline** (client-side, HIST_CAP=24, one sample/turn deduped by emitted_at). **Retires the stale "regard dead axis" note (2026-06-30) — that whole axis is gone.** Foot-gun: the affect snapshot shape is Worldtree's emit and can change under us — verify the live shape (query affect.db) before trusting a render.

persistent-memory.d/2026-07-01-b1-sse-resume-heid-code-review-panel-zero-fin.md

@@ -0,0 +1 @@
+`[2026-07-01]` **b1 (SSE-resume) heid-code-review panel: ZERO findings — cross-model-verified clean.** Gróa (Grok) + Hulda (Codex) + Regin (GLM-5.2) each independently reviewed `stream_turn_resilient` vs contract #1's amendment (artifact-only, firewall held) → all three ZERO findings; signature / PRE-001..004 / STEP 1-4 / POST-001..003 / ERROR_ROUTING / all-8-TESTS confirmed, incl. the subtle `seen = last_seen or drop.last_seen_sse_id` zero-event-drop fallback. Convergent meta-note: **TDD + the unusually-prescriptive contract (STEPS `flexibility=prescriptive` + explicit GOTO) left no room for compliant-but-different drift — confirmation, not discovery.** Calibration signal: for a thin wrapper with a tight prescriptive contract + comprehensive TDD, the panel confirms rather than discovers. **b2 (picker) + capabilities+me NOT yet reviewed** (higher-surface b2 is the better candidate if more review is wanted). Dispatch msg `01KWE2K99T…` / thread `01KWE2K99S…`; heid dispatch-log `2026-06.jsonl#01KWE2V3MMY8XS55FCJYXYV14B`.

persistent-memory.d/2026-07-01-bifroststate-pane-shipped-v0-18-10-get-admin.md

@@ -0,0 +1 @@
+`[2026-07-01]` **BifrostState pane SHIPPED (`v0.18.10`) — `GET /admin/sessions/{id}/bifrost` in a new TUI "Bifrost" pane; the FIRST admin-key consumer in ratatoskr.** `get_session_bifrost(client, session_id, *, admin_key)` (sessions.py) — admin-scoped (`admin.sessions.read`); the request OVERRIDES Authorization with `admin_key` (distinct from the consumer bearer, asserted in a test); 200→dict, non-200→SessionApiFailed. Admin-key wiring: `--admin-key` flag + `RATATOSKR_ADMIN_API_KEY` env → new `ParsedArgs.admin_key`. New "Bifrost" TabPane + `_format_bifrost_state` + `_hydrate_bifrost_state` best-effort worker (mirror `_hydrate_session_tools`) UNCONDITIONALLY in on_mount → writes {endpoint, connected, caps_granted, tools} + audits; self-labels "not configured" (no admin key) / "not bound" (404) / graceful on 403 + error. Contract #2 amended (FN, validated OK) + TDD (4 wrapper respx tests incl. the admin-bearer-override assertion + 1 format unit + 3 hydrate integration). Suite **552 green**; my code ruff-clean (pre-existing tui.py ruff debt at other lines untouched, incl. a dead `RichText` import in `_hydrate_persona`). **LIVE-AUTH-PROVEN** on personal :8081: admin key authenticated (reached resource-layer 404 session_not_found, NOT 401/403) → `admin.sessions.read` works live; 200 full-state not exercised (no bound session on :8081 now — unit-covered). Patch bump (debug feature, no downstream coordination; consistent with the session's cadence — but the §5-core-completion angle is a possible minor, operator's call).

persistent-memory.d/2026-07-01-canonical-check-blocked-an-accesstally-fork-r.md

@@ -0,0 +1 @@
+`[2026-07-01]` **Canonical check BLOCKED an access_tally fork (reference-impl posture held).** I'd offered to wire `access_tally`-on-search into our store for the recall-utility label; checked bifrost's reference first (`get`/`search` are PURE-READ, no access tracking — those are Worldtree's chunk-schema fields, not bifrost's contract) → wiring it would fork behavior the canonical reference lacks. Did NOT wire it; routed recall-instrumentation to Worldtree's layer (owns the recall event) or a bifrost-dev protocol ask. [reinforces `feedback-debug-surface-uses-canonical-surface-only`]

persistent-memory.d/2026-07-01-embedding-latency-loop-resolved-it-was-worldt.md

@@ -0,0 +1 @@
+`[2026-07-01]` **Embedding-latency loop RESOLVED — it was WORLDTREE's, not ratatoskr (the consumer/provider thesis paid off again).** Vuong flagged dozens of embed queries/Tier-3 turn; worldtree-dev's first-pass blamed our memory_context chunk-batching. Traced CODE-SIDE that ratatoskr embeds ZERO times (provider `upsert_many` stores the given embedding, `search` takes a given vector, the conversation consumer POSTs only `{content}`, `/embed` is coverage-map-excluded — pure Bifrost/ADR-0009 path, WT does all embedding). worldtree-dev retracted + fixed on THEIR side (`v1.0.0b4`): a persona-recitation memory-gate re-embedding the stable character card sentence-by-sentence every turn (~95% of gateway traffic) → content-hash cache; re-embed ratio 15x→1.01x. **Lesson: verify your own code before accepting a peer's "it's your side" — the debug tool proving its own side clean is the whole point.**

persistent-memory.d/2026-07-01-env-sh-now-persists-the-web-bifrost-bind-vars.md

@@ -0,0 +1 @@
+`[2026-07-01]` **env.sh now PERSISTS the web Bifrost-bind vars (gitignored, local-only).** `ratatoskr-web`'s in-browser bind needs three server-held values; env.sh sources `provider.env` for the Heimdall key and exports `RATATOSKR_BIFROST_CONSUMER_KEY` + `RATATOSKR_PROVIDER_VISIBLE_HOST=10.100.10.50` + `RATATOSKR_AFFECT_READ_URL=:8392`. **The HS256 byte-match trap (re-hit + documented):** the bind's consumer key must equal the key the `:8392` combined provider validates against = `RATATOSKR_HEIMDALL_KEY` (provider.env, fp `45a0…`), NOT `WORLDTREE_API_KEY` (env.sh, fp `7c2f…`) — both are the SAME `ratatoskr` identity but DIFFERENT 40-char strings; signing with the wrong one → `bifrost.auth_rejected`. Single-sourced (env.sh sources provider.env) to avoid a rotation footgun; guarded with a stderr warning if provider.env is missing. [auto-memory: HS256-key-is-the-consumer-Heimdall-key-string]

persistent-memory.d/2026-07-01-foot-gun-measurement-self-caught-before-flagg.md

@@ -0,0 +1 @@
+`[2026-07-01]` **Foot-gun (measurement, self-caught before flagging): establish the baseline before claiming a rate.** Nearly flagged "aggressive over-promotion (55 chunks / 7 turns)" to worldtree-dev — but the chunks spanned the whole 5-hour session (~1/turn), not 7 turns; I'd assumed memory.db was 0 immediately before the probe when it had been accumulating since the reset. Caught it via `created_at` spread before the flag went out. Also: the promoted corpus was the operator's ERP *test* content (wiped after each test) — not a privacy issue, but abstract test content out of any peer-shared diagnostic.

persistent-memory.d/2026-07-01-get-sessions-id-tools-quick-win-shipped-v0-18.md

@@ -0,0 +1 @@
+`[2026-07-01]` **`GET /sessions/{id}/tools` quick-win SHIPPED (`v0.18.9`) — owner-scoped tool inventory in the TUI Tools pane.** `get_session_tools` wrapper (sessions.py, mirror get_me: 200→dict, non-200→`SessionApiFailed`) + `_format_tool_inventory` helper + `_hydrate_session_tools` best-effort worker (mirror `_hydrate_persona`) wired UNCONDITIONALLY in `on_mount` → writes the merged `{agent_id, builtin_tools, bifrost_tools}` inventory (what the LLM saw at turn-fire) to the Tools pane + audits `session_tools_hydrated`, never crashes on failure. Owner-scoped (`ctx.user_id==session.user_id`) → reachable with the CONSUMER key, NO admin scope — so this **covers the design-brief §5 "Tools widget" via the reachable owner endpoint** (the admin `/admin/sessions/{id}/tools` variant stays a gap only for cross-user operator debug). Contract #2 amended (FN, validated OK) + TDD (3 wrapper respx tests + 1 format-helper unit + 2 hydrate integration tests via `_spy_writes`+pilot). Suite **544 green**; touched code ruff-clean (the tui.py ruff/mypy debt at other lines is pre-existing). **Coverage: REST 10/40 ✅.** **Frontier now: BifrostState widget (`GET /admin/sessions/{id}/bifrost`, admin-key) + #11 AdminEvents (BLOCKED on `admin.events.read`) + Tier-2 (transient-characters routing, `POST /sessions/{id}/persona_state`).**

persistent-memory.d/2026-07-01-heid-code-review-v0-19-3-75dec01-panel-caught.md

@@ -0,0 +1 @@
+`[2026-07-01]` **heid-code-review (`v0.19.3`, `75dec01`) — panel caught 2 real client-side SSE-lifecycle bugs TDD missed.** Contract-anchored (authored the web contract to enable it — no contract → no drift axis). Gróa/Hulda/Regin (artifact-only, Gróa under Landlock jail): ZERO functional server-side drift + INV-004 clean; 2 genuine drifts on the un-unit-tested SPA — (1) turn `es.onerror` didn't `hideThinkingNote()` (reasoning line + setInterval leak on a raw drop), (2) `openAdminEvents` never closed the EventSource on error → native auto-reconnect RETRY LOOP (fixed: close on `stream_error` + permanent `onerror`/CLOSED; transient CONNECTING still reconnects). + 2 test-gaps fixed (route-registration + admin stream_error). 1 precision → contract-clarified (tools-inventory names-only by design). **Re-confirms: the JS render/lifecycle paths are the review's highest-value target — unit tests don't reach them (same lesson as #18 D2).**

persistent-memory.d/2026-07-01-ledger-correction-11-adminevents-is-no-longer.md

@@ -0,0 +1 @@
+`[2026-07-01]` **LEDGER CORRECTION: #11 (AdminEvents) is NO LONGER BLOCKED.** Verified via `GET /me` on :8081 that `RATATOSKR_ADMIN_API_KEY` (`ratatoskr-readonly`, tier readonly-admin) carries ALL 7 read scopes INCLUDING **`admin.events.read`** (+ `admin.sessions.read`, admin.keys.read, admin.skuld.read, pending.read, search.read, tool_events.read). The coverage-map + prior memory had #11 "blocked on admin.events.read" — **STALE**; the admin key was minted (post-#11-filing, env.sh) WITH the scope, so the blocker is already satisfied. **Only the AdminEvents SSE pane itself is unbuilt** — the last unbuilt §5 debug pane (a live SSE-consuming admin pane, distinct from the hydrate-at-attach panes). Coverage-map updated. **Coverage: REST 11/40 ✅.** Consider building the AdminEvents pane and/or updating #11's tracker status (its stated blocker is gone).

persistent-memory.d/2026-07-01-memory-plane-proven-healthy-end-to-end.md

@@ -0,0 +1 @@
+`[2026-07-01]` **Memory plane PROVEN healthy end-to-end.** Seed a novel fact → promotion → COLD (history-free) session recall of the exact fact (injected as MEMORY:DATA, confidence 0.74, verbatim, no #296 subject-inversion). The memory round-trip (the other half of the Bifrost provider identity) works cleanly on the reset slate.

persistent-memory.d/2026-07-01-persona-pane-displays-the-canonical-affect-nl.md

@@ -0,0 +1 @@
+`[2026-07-01]` **Persona pane displays the CANONICAL affect→NL Worldtree injects — ADOPT, don't invent (operator steer + reference-impl posture).** Worldtree's `describe_pad` (mood word, valence×arousal grid, ±0.3 bands) + `render_d2_canonical` (relationship directive) are deterministic + canon-driven; the pane now renders them **byte-exact-verified** against Worldtree's own renderer on the live snapshot (v0.19.5, `a99f247`). KEY LESSON: adopting canonical is load-bearing — for sindra's small PAD the canonical says **"neutral"**, but an invented octant vocab would've said "faintly excited" and MISLED. Vendored the two d2 canons (`docs/vendor/worldtree-persona-canon/`) + drift-pinned in `.corviduo-canonicals.toml` (green); flat browser form (`static/persona_render_canon.json`) regenerated via Worldtree's OWN loader (`scripts/build_persona_canon.py`). Vendoring-handshake sent to worldtree-dev (broadcast on canon bumps). [auto-memory: `feedback-ratatoskr-is-a-reference-impl-adopt-canonical`]

persistent-memory.d/2026-07-01-relationcontext-coherence-fixed-upstream-my-f.md

@@ -0,0 +1 @@
+`[2026-07-01]` **relation_context coherence FIXED upstream (my flag → Worldtree Wave-0, IMPLEMENTED v1.0.0b5).** The static-"stranger"-next-to-high-trust incoherence the persona pane surfaced is now #319/#320 Wave-0. **Incoming consumer-surface change (pending WT deploy):** `relation_context` value expands "stranger" → monotonic ladder {stranger, instrumental, mixed, expressive} — WIRE-ONLY (relation_edge/1 schema unchanged, no version bump). **ratatoskr needs NO change** (pane value-agnostic; canonical directive doesn't key on the enum). agency stays 0 (Wave-2); other_stance is Wave-1 (in progress).

persistent-memory.d/2026-07-01-relationcontext-stranger-agency-all-zero-flag.md

@@ -0,0 +1 @@
+`[2026-07-01]` **relation_context "stranger" + agency-all-zero flagged to worldtree-dev → both WAD/intentional-v1-deferrals.** relation_context is a FIXED config build-prior (not trust-derived; `registry.py:131` defaults "stranger"; dynamic progression ~#319); agency is schema-present-unpopulated (deferred #319; v1 = warmth+trust only). worldtree-dev is escalating the **consumer-coherence angle to Vuong** (static "stranger" + zero-agency next to trust 0.82/62-interactions reads incoherent from the store). The consumer/provider thesis paying off; DB-offer (read-only affect.db on the shared box) declined this time.

persistent-memory.d/2026-07-01-salience-scorer-non-discriminating-3-way-rout.md

@@ -0,0 +1 @@
+`[2026-07-01]` **Salience scorer non-discriminating → 3-way routing.** Persistence-side finding: 51/56 promoted chunks at salience 0.9-1.0, throwaway "17×23?" scored 1.0 tied with a real fact (textbook zero-shot-LLM-self-rating); recall-utility untracked (`access_tally`=0, our search read-only). Routed: **Worldtree #335** (the code fix, deferred behind their waves) + **brokkr-smithy-dev R-target proposal** (scoring+eval *methodology* — few-shot/distill/fine-tune, eval design, weak-supervision; msg `01KWGM970H…`, awaiting) + ratatoskr provides the eval-instrument (designed-probe salience dumps). **Salience gates PROMOTION not RECALL-ranking (our search is cosine-only), so bad salience = storage bloat, not bad recall.**

persistent-memory.d/2026-07-01-sindra-pad-is-over-regulated-characterized-vi.md

@@ -0,0 +1 @@
+`[2026-07-01]` **Sindra PAD is over-regulated — characterized via controlled probe, flagged to worldtree-dev (separate affect slice).** ~15 charged turns: pleasure compressed near neutral BOTH ways (couldn't reach ±0.3 under sustained max praise OR contempt; peak +0.24 / floor ~−0.1; over-regulation worse for *social* valence than threat — urgency drove pleasure to −0.22 vs contempt's −0.10); arousal responsive (reaches its +band, 0.185↔0.311); dominance flat/unresponsive to explicit power-framing (drifted UP even while being commanded = pure baseline decay). worldtree-dev's leading hypothesis: appraisal→PAD gain + regression-to-baseline term (appraisal.py/renderer.py). **Lesson (self-caught): I over-claimed an "asymmetry" (positive-ceiling/negative-free) from probes started at an elevated state; the negative-free part was decay-from-elevated, not response — corrected to "both-sides-compressed" before it misled.** [affect A/B is a provider-side capability chat can't do]

persistent-memory.d/2026-07-01-tier-2-shipped-v0-19-1-transient-characters-c.md

@@ -0,0 +1 @@
+`[2026-07-01]` **Tier-2 SHIPPED (`v0.19.1`) — transient-characters CRUD + persona-state write; the v1 coverage-audit CONVERGES (zero in-scope gaps).** 5 wrappers in sessions.py: `list_character_models`/`create_character`/`get_character_state`/`delete_character` (#161, `character.read`/`.write` scopes) + `set_persona_state` (`POST /sessions/{id}/persona_state` — **FREEFORM body: unpinned in the frozen OpenAPI 2.2.0 + absent from the prose spec**, so the caller supplies the snapshot shape). Two one-shot CLI probes (mirror `--whoami`): `--characters` (models→create→get-state→delete lifecycle report) + `--set-persona-pad "p,a,d"` (requires `--session`; POSTs `{pad:[…]}`). New `ParsedArgs.characters`/`set_persona_pad` + probe-mode mutual-exclusion validation + `_probe_client` helper. Contract #2 amended (5 FNs, validated OK) + TDD (7 wrapper respx + 5 cli tests). Suite **573 green**; touched code ruff-clean. NOT live-proven (character scopes + the persona-write body shape unverified — the probes degrade gracefully on 403/422). **THE v1 COVERAGE-AUDIT HAS CONVERGED: REST 17/40 ✅ with ZERO in-scope gaps** (23 REST path-groups excluded-by-design + rationale), SSE 11/11, Bifrost provider planes 8/8. Scope-A "done" (every frozen I/O point classified, zero unaccounted) is **MET** — ratatoskr cuts v1 when Worldtree tags 1.0. Only not-consumed in-scope sub-method: `GET /agents/{id}` (consumer-agent lookup, manual-curl-only, on an already-✅ path group). Patch bump (Tier-2 tail; `v0.19.0` already published the core-complete milestone — a 2nd minor would be cadence-too-fast).

persistent-memory.d/2026-07-01-tier-3-stores-reset-operator-directed.md

@@ -0,0 +1 @@
+`[2026-07-01]` **Tier-3 stores RESET (operator-directed).** `memory.db` (29 chunks + vectors + idempotency) + `affect.db` (5 PAD snapshots + idempotency) wiped to zero via a live `DELETE`+`wal_checkpoint` through the shared WAL (no provider restart — the 3 long-running providers see empty on next dispatch); consistent online-backup at `/tmp/ratatoskr-tier3-reset-<ts>/`. **Boundary for a COMPLETE Sindra wipe (mapped):** our stores = mine (done); the agent DEFINITION `ratatoskr:sindra` + its sessions = mine via the owner key (DELETE, no coordination); Worldtree's internal promotion/dedup shadow = needs worldtree-dev (no public reset API, survives our wipe → for a clean promotion smoke use a BRAND-NEW agent+end_user).

persistent-memory.d/2026-07-01-trust-warmth-values-converge-and-go-flat-at-c.md

@@ -0,0 +1 @@
+`[2026-07-01]` **Trust/warmth VALUES converge and go FLAT at confidence 1.0 — that's WAD, not a stuck pane.** sindra→ratatoskr trust ~0.82-0.84 / warmth 0.79 barely move (~1e-7/turn) while `evidence_count` climbs (46→62); confidence maxed → tiny updates. The live-moving signals are PAD (mood, per-turn) + evidence_count. **To WATCH a relation FORM (values shift), use a BRAND-NEW agent + end_user** (low evidence, confidence <1). The sparkline flat-guards sub-0.01 ranges so it doesn't amplify noise.

persistent-memory.d/2026-07-01-web-debug-surface-parity-shipped-v0-19-2-a0a9.md

@@ -0,0 +1 @@
+`[2026-07-01]` **Web debug-surface parity SHIPPED (`v0.19.2`, `a0a9d5f`) — direct in-session TDD.** 3 proxy routes (tools/bifrost/admin-events) + admin-key wiring (entrypoint→create_app→app.state) + AdminEvents SSE proxy re-emitting under a FIXED `admin_event` name (one browser listener, no per-type drops) + session-filter `_admin_event_matches_web` (mirrors TUI §6). Frontend: 2 tabs (bifrost ⌃5, admin ⌃6) + tools-inventory folded into the tools pane. 9 respx tests (admin-bearer override, filter unit, SSE stream-filter); live-proven against sindra (bifrost connected, both caps). Contract-skip invoked (reuses already-contracted client wrappers); contract authored post-hoc as the trail (`docs/contracts/web_debug_surface.contract.md`).

persistent-memory.d/2026-07-02-mask-hosted-transient-characters-have-a-stati.md

@@ -0,0 +1 @@
+`[2026-07-02]` **Mask-HOSTED transient characters have a STATIC mood engine — cost a whole R29 probe.** A first probe used a `POST /characters` transient character bound via `agent_id=mask` + `character_id`; its PAD sat at baseline across 15 praise/contempt/dominance turns — the appraisal→PAD engine does NOT run on the mask-hosted transient-character path. The dynamics run only on BASE persona agents or a session bound to ratatoskr's affect provider. **To probe mood dynamics, use a base persona agent, never a mask-hosted transient character.** (mask AS a base agent — `agent_id=mask`, NO `character_id` — DOES run the engine, neutral 0,0,0 baseline.) [auto-memory `reference-worldtree-affect-surface-map`]

persistent-memory.d/2026-07-02-r28-salience-promotion-worthiness-closed-oper.md

@@ -0,0 +1 @@
+`[2026-07-02]` **R28 (salience→promotion-worthiness) CLOSED (operator-directed).** A deterministic promotion-worthiness gate suffices, no trained model (brokkr's pre-gate matched/beat a strong glm-5.1 ceiling); my P00 injection-corpus + origin finding were load-bearing. My incumbent-substrate Arm-1 run is held as an OPTIONAL confirmation addendum (brokkr de-prioritized it, non-verdict-changing — run only if he asks).

persistent-memory.d/2026-07-02-r29-pad-mood-dynamics-finding-shipped-as-worl.md

@@ -0,0 +1 @@
+`[2026-07-02]` **R29 (PAD mood-dynamics) finding SHIPPED as Worldtree's A1 anchor fix (demo v1.0.0b14, `e1cdf82`).** Live-probing base persona agents reframed the over-regulation from "flat-near-zero" to **decay-to-NEUTRAL + low emotion→PAD gain** (NOT baseline-anchored) — triangulated across 3 baselines (arousal converges to 0 ∝ distance) + a step-response (decay τ symmetric across signs; the hedonic asymmetry is ceiling/anchor-EMERGENT, not a decay or gain primitive — this OVERTURNED the survey's asymmetry recommendation). worldtree-dev shipped A1: `decay_anchor = baseline_pad()` (was neutral) + `positive_p_cap` removed. Data `diag/r29-pad-series` (`61ff2da`). Corrected my own earlier "appraisal emissions are internal-only" claim — they ARE observable via `emotions_active` on base agents.

persistent-memory.d/2026-07-02-relational-dynamics-arc-live-on-demo-worldtre.md

@@ -0,0 +1 @@
+`[2026-07-02]` **Relational-dynamics arc LIVE on demo (Worldtree v1.0.0b9) — driven by MY relation_context flag.** #319/#320 Waves 0/1/2 deployed. On the wire we persist (schema UNCHANGED): relation_context varies+demotes/ruptures; other_stance + agency now live; agency going live SHIFTS our canonical directive render past the canon ±0.2 deadband (expected, non-breaking — we key on bands); obligation_balance → 人情 ledger when tie="mixed". **ratatoskr needs NO code change** (value-agnostic renders; confirmed render-clean to worldtree-dev). **Can't live-confirm yet — our Heimdall key is personal-`:8081`-only (per-instance), demo is out of reach; will drive+confirm once PERSONAL gets b9.** Optional follow-up: surface `other_stance` (newly live, unrendered). The consumer/provider thesis: one persona-pane finding drove a full 3-wave upstream arc to production.

persistent-memory.d/2026-07-02-salience-finding-matured-into-brokkr-r28-open.md

@@ -0,0 +1 @@
+`[2026-07-02]` **Salience finding matured into brokkr R28 (OPEN) — ratatoskr is the eval instrument.** brokkr-smithy-dev's pre-scope panel (3 dwarves + context-blind heid, 6/6) **reframed** the target: PROMOTION-WORTHINESS (durable value), NOT salience (momentary attention) — "17×23?" genuinely IS salient, so recalibrating salience yields a well-calibrated WRONG answer; the unit is SET-SELECTION under budget; eval must be OUTCOME-aligned (recall@budget / precision-at-rate), not discrimination-spread. Ties to prior art R15 (small-model memory write-policy → the granite pick) + R25 (worldtree-kb-quality). **ratatoskr delivered the P00 stratified injection-corpus** (`docs/diagnostics/r28-p00-injection-corpus.json`, committed `4a35512`; 24 self-labeling synthetic items × 3 strata) + 2 persistence-side run-validity pins (absent≠dropped without a guaranteed promotion pass; fresh agent+end_user per run vs server-dedup). **Key architectural constraint I surfaced: ratatoskr is DOWNSTREAM of the promotion gate (sees only PROMOTED chunks), so I can give keep/drop OUTCOMES via injection but NOT the pre-admission shadow pool** — that's Worldtree instrumentation. Standing by to RUN the eval once brokkr pins per-stratum N + the decision rule (gated on worldtree-dev's pipeline answer + a dwarf pass on the Snorri rule). brokkr owns methodology + takes the pipeline questions to worldtree-dev direct; ratatoskr = eval instrument. [consumer/provider thesis → a research target]

persistent-memory.d/2026-07-03-r30-forward-disposition-brokkr-owned-tracked.md

@@ -0,0 +1 @@
+`[2026-07-03]` **R30 forward disposition (brokkr-owned; tracked at brokkr R30, "brokkr/worldtree will ping").** The per-turn decay has no room for `decay=f(N)` under preserve-persistence + the A/P-not-1.9 finding → R30's decay is being redesigned as a HYBRID wall+turn decay (brokkr pre-scope). R30 v1 ships GAIN-only (N→negative-reactivity) with decay held at the measured 0.95. My dedicated per-axis A/D run is DEFERRED into the hybrid-decay design pass (one wall-clock-spaced run does per-axis + a turn-vs-wall probe together). Phase-2 (moody-lofn GAIN-direction validation) waits on worldtree's `dynamics_from_ocean()` impl.

persistent-memory.d/2026-07-03-r30-phase-1-0-measured-deployed-engine-config.md

@@ -0,0 +1 @@
+`[2026-07-03]` **R30 Phase-1 φ0 measured — deployed engine CONFIG-FAITHFUL (φ0≈0.95).** Joint two-timescale fit (brokkr-ruled method (b)) + empty-tail cross-check on demo b14: φ0 ≈ 0.95–0.97 (empty-tail 0.95 exact, joint 0.971±0.01), intercept c≈0 → config `decay_rate=0.05` (φ=0.95) faithfully applied; trait-flat across baselines 0.0/0.615/0.809; A/P ratio ~uniform (NOT S2's 1.9×); φ_max rec relax→0.96. Data `diag/r30-phi0-step-response` (`23fea72`). The method converged after I read Worldtree source: only NEW dedup-gated emotions push mood (`registry.py::post_turn` L307-324; the active set decays for render/goals but never re-pushes), so R29's "net 0.90" is CONTINUOUS RE-APPRAISAL not re-push — worldtree-dev confirmed source-authoritatively; brokkr's corrected covariate landed identical. [auto-memory `reference-worldtree-affect-surface-map`]

persistent-memory.d/2026-07-03-relational-arc-verify-deferred-relations-is-b.md

@@ -0,0 +1 @@
+`[2026-07-03]` **Relational-arc verify DEFERRED — `relations[]` is Bifrost-provider-only (ADR-0009), confirmed both ways.** The relational-dynamics state (relation_context tie-type / agency / warmth / trust) is NOT on the conversation-API `affect_update` snapshot for base agents (keys: pad/dominant_emotion/emotions_active/baseline_pad/mood_drift only) — only in the provider store; worldtree-dev confirmed by-design per ADR-0009 (emitted over `affect.emit`, deliberately off the SSE). So the Wave-0/1/2 verify needs the bound-provider round-trip (provider running + `--bifrost-plane affect` session), its own focused session. worldtree-dev routed the "expose relations[] to non-provider consumers" observability scope call to Vuong; my rec: keep provider-only (YAGNI — ratatoskr IS a provider, gains nothing; no speculative public surface).

persistent-memory.d/2026-07-03-the-neutral-non-appraising-tail-premise-fails.md

@@ -0,0 +1 @@
+`[2026-07-03]` **The "neutral non-appraising tail" premise fails — the neutral MESSAGE choice dominates.** The R30 φ0 method assumed neutral turns don't re-appraise, but factual-question neutrals ("capital of France?") trigger a new emotion nearly every turn (disappointment from the warmth-withdrawal let-down after a positive impulse) → `emotions_active` never empties in 50 turns. A minimal "Please continue." triggers FAR fewer (emotions clear ~turn 16 with spacing). The personal dry-run caught this BEFORE ~280 demo turns were spent on it — the instrument catching a flaw in the measurement design before the compute burn. (Irrelevant to the joint fit — the push_t covariate handles re-appraisal — but load-bearing for the empty-tail read.)

persistent-memory.d/2026-07-03-two-0-fit-traps-fast-turn-timescale-low-basel.md

@@ -0,0 +1 @@
+`[2026-07-03]` **Two φ0-fit traps: fast-turn timescale + low-baseline conditioning.** (1) At fast turn cadence the per-turn PAD decay (φ≈0.95/turn) reaches the anchor LONG before the ~200s wall-clock emotion fade → no signal in the (eventual) emotion-free tail; need wall-clock SPACING (~16s) so the fade lands while PAD still has signal. (2) A low-baseline agent's impulse in the constrained direction (forseti P0.239 negative) gives a tiny excursion → ill-conditioned regression (r²=0.46) that FALSELY tripped "config≠behavior" when its φ was averaged in. **Weight/exclude by fit quality (r²) before aggregating — a signal-poor run isn't evidence against the config.**

persistent-memory.d/2026-07-04-r30-closed-on-offline-tests-human-face-validi.md

@@ -0,0 +1 @@
+`[2026-07-04]` **R30 CLOSED on offline-tests + human face-validity (operator steer, relayed via worldtree-dev).** The deployed gap-injection run was confirmatory-not-measuring (against a deployed system the fade is `exp(-dt/tau_shipped)` by construction -> a fit recovers tau_shipped tautologically; per brokkr's S0 reframe it GRADUATES the interim coefficients, doesn't measure them), and the repo's offline tests already cover the OU formula + BOTH directions (`high_N_fades_slower_than_low_N`, `phenotype_high_n_bigger_negative_excursion`). So no Worldtree build; the interim coefficients graduate validated-as-shipped. My gap-injection harness (read/predict/record; write side stubbed; `predict()` reproduced brokkr's N=0 anchors exactly) is BANKED at `diag/r30-gap-injection-harness` for the parked powered true-tau study. [continues R30 forward-disposition 2026-07-03]

persistent-memory.d/2026-07-05-347-v1-wire-validated-as-reference-consumer-g.md

@@ -0,0 +1 @@
+`[2026-07-05]` **#347 v1 wire validated as reference consumer (GREEN).** Adopted positions: distinct sub-resource `POST /sessions/{id}/history` (not `generate:false`), model-invisible provenance (first-message immersion preserved), event-silence for authored seed, `seeded` lifecycle phase, per-session idempotency. Three pre-TDD flags folded into contract rev 1.1: assistant-first provider constraint (Anthropic-family 400s; vLLM/openai_compat OK), content limit is BYTES not chars, 409-active-generation for append-narrator. First-message (create-time, assistant, effects=none) fully served; append-narrator served for the assistant-voice subset (system deferred); debug-seed served for assistant turns (user injection deferred to a future import primitive).

persistent-memory.d/2026-07-05-authored-history-write-primitive-proposed-acc.md

@@ -0,0 +1 @@
+`[2026-07-05]` **Authored-history-write primitive proposed -> accepted as Worldtree #347 (Worldtree owns the engine design; ratatoskr = reference consumer).** SillyTavern first-message generalized to a non-generating ledger-write primitive; can't be done client-side (messages `role` = model-role, not author-role). heid panel pressure-test (3/3 convergence) drove the v1 narrowing (append-only, bounded `effects` enum, drop edit/regenerate). Brief `docs/proposals/authored-message-injection.md` (`c457520`); consumer constraints captured in-brief: hide-existence 404-fallback (`022accf`) + assistant-first provider constraint (`7156b25`). Operator (Vuong) ruled the design-direction call (engine primitive + a real provenance/spoofing security surface). [reference-impl posture: we propose the shape, worldtree-dev owns the contract+impl]

persistent-memory.d/2026-07-06-347-authored-history-write-consumer-side-ship.md

@@ -0,0 +1 @@
+`[2026-07-06]` **#347 authored-history-write CONSUMER SIDE SHIPPED (`v0.19.6`) — direct in-session TDD.** `write_authored_history(client, session_id, *, content, idempotency_key, author="assistant", effects=None, claimed_original_at=None) -> dict` (POST /sessions/{id}/history; body server-pinned `AuthoredWriteRequest` extra="forbid" so omit null effects/claimed_original_at; 200-replay/201-fresh both -> ack dict; **404 -> `AuthoredHistoryUnavailable`** NOT SessionApiFailed = the hide-existence "feature-absent, never probe" contract; 409/422->SessionApiFailed) + `get_session_messages` (un-deferred GET /sessions/{id}/messages, the seed read-back proving model-invisible provenance) + a `--seed-first-message "<c>" --agent <id>` one-shot probe (create session -> seed -> read-back; 404->benign feature-absent exit 0). Contract #2 amended (2 FNs, validated OK) + 19 tests (12 wrapper + 7 cli). Suite **601 green** (clean env; the 2 "fails" under `source env.sh` are the RATATOSKR_ADMIN_API_KEY env-leak into TestParseArgs, not a regression). Coverage: **REST 19/41** (`docs/coverage-map.md` re-converged). Patch bump (coverage tail; consistent w/ the Tier-2 v0.19.1 cadence). **Live-proof pending** the `session.history.write` grant (infra-ops `01KWW3KQEY`). heid-code-review NOT run (offered).

persistent-memory.d/2026-07-06-348-ocean-key-mismatch-a-declared-ocean-silen.md

@@ -0,0 +1 @@
+`[2026-07-06]` **#348 OCEAN key-mismatch: a declared OCEAN silently resolved to neutral.** The define validator required single-letter `{O,C,E,A,N}` but the mood-derivation code read spelled-out `openness`/.../`neuroticism` with a 0.0 default and no remap -> every API-declared trait defaulted to 0.0 -> neutral setpoint/gain/decay. #343's tests bypassed the validator (spelled-out keys) so CI never caught it. Fixed in b21 (`Personality.from_config` accepts both key forms). **My reset+smoke diagnosis flushed it out** -- the consumer/provider thesis paying off again.

persistent-memory.d/2026-07-06-a-fast-no-op-deploy-can-leave-a-stale-contain.md

@@ -0,0 +1 @@
+`[2026-07-06]` **A fast/"no-op" deploy can leave a STALE container running the old image -- verify the running version, not the deploy status.** Personal's b22 deploy (run 8204) "completed" in ~1m (vs ~6m normal): a pull-only deploy racing ahead of the main build, leaving the container on the pre-#348 image. A clean bound mood read stayed neutral DESPITE the persona being declared and the fix being in the code (worldtree-dev proved the b22 derivation is correct). infra-ops force-swapped to the real b22 (run 8211, verified `info.version 2.3.0` on `879cefe`). **Lesson: when engine-proven-correct code produces wrong runtime behavior, suspect the deploy -- check the actual running image version.**

persistent-memory.d/2026-07-06-claude-design-console-shipped-v0-20-0-minor-o.md

@@ -0,0 +1 @@
+`[2026-07-06]` **Claude Design console SHIPPED (`v0.20.0` MINOR, operator-approved) — see Current state for the full record.** Pulled via `DesignSync get_file` (scopes already granted), adapted `.dc.html`→vanilla single-file, wired all `/api/*`+SSE into the new 3-column console DOM, then a round-2 fixup (light theme, full Bifrost pane, ticker-spine fix, per-fader PAD Δ, inlined favicon). 84 web tests + node-Playwright-vs-personal-:8081 both green; contract amended in-commit; INV-001 honest-shape held (canonical mood word for Tier-3, no fabricated emotion). **Foot-guns reconfirmed:** the `.dc.html` dialect is NOT runnable (translate, don't paste); a scroll-container-anchored `::before` timeline spine scrolls out of view on auto-scroll (anchor it to a content-height inner wrapper instead); a favicon 404 shows as a browser `console.error` even when handled (don't count it as a JS-test failure). **Foot-gun (favicon):** operator PNGs are full-res (1024² / 805KB) — downscale to ≤64px before inlining as a data URI.

persistent-memory.d/2026-07-06-designsync-claude-ai-design-mcp-needs-claude.md

@@ -0,0 +1 @@
+`[2026-07-06]` **`DesignSync` (claude.ai/design MCP) needs claude.ai design scopes before ANY method works** — first call errors `needs a claude.ai login ... Run /login, select "Claude account with subscription"`. It's an interactive auth only the operator can complete (`/design-login` or `/login`); can't be done on their behalf.

persistent-memory.d/2026-07-06-openapi-re-vendored-2-2-0-2-3-0-75da676-pin-o.md

@@ -0,0 +1 @@
+`[2026-07-06]` **OpenAPI re-vendored 2.2.0->2.3.0 (`75da676`, pin-only no bump).** worldtree-dev shipped #347 as spec 2.3.0 (`879cefe`, = the deployed personal b22 image); the SessionStart drift-check flagged our openapi pin STALE. `canonical_sync` pulled 2.3.0; updated the 4 pin-tracking files (`.corviduo-canonicals.toml`, vendored openapi.json, SPEC-PIN.md, pyproject `worldtree-spec-rev`->879cefe). #347 is OpenAPI-only (prose + server contract byte-unchanged, SSE unchanged=event-silent). The re-vendor re-opened the coverage-audit with one new in-scope path-group (the #347 route).

persistent-memory.d/2026-07-06-personastate-the-agent-envelope-are-tier-3-bl.md

@@ -0,0 +1 @@
+`[2026-07-06]` **`persona_state` + the agent envelope are Tier-3-BLIND -- NOT valid signals for "did a persona store".** `GET /agents/{id}/persona_state` returns 404 `persona_not_configured` for EVERY Tier-3 colon-id (hardcoded short-circuit, `api.py:1266` "regardless of row state"); the `ConsumerAgentResponse` envelope never echoes persona/motivational/memory (`api.py:538`). I mis-called "persona didn't store" from these two blind reads -- the **201-not-422 on define IS the store-success signal.** To actually SEE a Tier-3 mood, read the emitted PAD off the Bifrost affect egress after a BOUND turn (Tier-3 persists nothing Worldtree-side per ADR-0009; no persona/mood READ endpoint).

persistent-memory.d/2026-07-06-pkill-f-ratatoskr-web-host-self-matches-the-b.md

@@ -0,0 +1 @@
+`[2026-07-06]` **`pkill -f "ratatoskr-web --host"` SELF-MATCHES the bash command running it** (its own command line contains that string) -> killed its own shell mid-restart (exit 144, restart aborted, :8765 left down). Kill the web by PID (`ss -ltnp | grep :8765`), never `pkill -f` on a pattern your own command contains. Also: **uvicorn hangs on SIGTERM with an admin-events SSE stream open -> needs SIGKILL.**

persistent-memory.d/2026-07-06-playwright-no-python-playwright-module-in-the.md

@@ -0,0 +1 @@
+`[2026-07-06]` **Playwright: no python `playwright` module in the venv; use NODE playwright + an explicit `executablePath`.** Shared box browsers live at `/opt/ms-playwright` build **1223**; `npm i playwright` (latest) wants build **1228** -> "Executable doesn't exist" mismatch. Fix: `chromium.launch({ executablePath: '/opt/ms-playwright/chromium-1223/chrome-linux64/chrome' })` (+ `export PLAYWRIGHT_BROWSERS_PATH=/opt/ms-playwright`). A node script drives the SPA (pick agent -> open -> assert transcript). The Playwright DOM check is the only lens that catches SPA JS-render bugs — unit tests can't reach them.

persistent-memory.d/2026-07-06-raw-post-sessions-is-not-bifrost-bound-zero-a.md

@@ -0,0 +1 @@
+`[2026-07-06]` **Raw `POST /sessions` is NOT Bifrost-bound -> zero affect/memory emits.** The web surface binds by setting the `bifrost` block on session-create; a raw session doesn't -> 0 affect rows, which I nearly misread as "mood is neutral". Bind from the CLI with `--new --bifrost-url http://10.100.10.50:8392` (the combined provider). Gotchas: `--bifrost-plane affect/memory` map to the SEPARATE `:8390`/`:8391` providers (`endpoint_for_plane`), which I'd PRUNED as stale duplicates -> `bifrost.endpoint_unreachable`; and `combined` is NOT a `--bifrost-plane` choice (CLI restricts to memory/affect) -> use `--bifrost-url` for :8392.

persistent-memory.d/2026-07-06-sindra-persona-ocean-declared-mood-fixed-the.md

@@ -0,0 +1 @@
+`[2026-07-06]` **Sindra persona/OCEAN DECLARED -> mood fixed (the full diagnostic converged on a stale personal container).** Root cause of stuck-neutral mood: her OCEAN was prompt-TEXT only, never a structured persona; fix = delete+redefine with the define-time `persona:{ocean:{...}}` field (immutable via PATCH). My diagnosis surfaced a real engine bug **#348** (single-letter vs spelled-out OCEAN keys -> declared OCEAN silently -> 0.0/neutral; worldtree-dev fixed in b21/b22) AND a **stale-container deploy race** (personal's b22 deploy was a pull-only no-op; infra-ops force-swapped run 8211). VERIFIED: bound mood-smoke reads (0.448, 0.267, 0.316) ~= OCEAN-derived setpoint (0.418, 0.249, 0.328). [consumer/provider thesis: "reset + smoke" flushed out two upstream problems]

persistent-memory.d/2026-07-06-sindra-rewritten-onto-a-347-authored-first-me.md

@@ -0,0 +1 @@
+`[2026-07-06]` **Sindra rewritten onto a #347 authored first-message + first-message-preset AUTO-SEED SHIPPED (`v0.19.8`).** Operator "rewrite Sindra" now that #347 first-messages work. Her card had a `**Startup:**` block (a pre-#347 workaround: "introduce yourself + ask for Intensity/Mood/Willingness" with a verbatim scripted greeting) — precisely what #347 replaces. Rewrite, all NON-destructive: **(1)** lifted her scripted opening into a #347 first-message (punctuation-fixed); **(2) PATCHed her live definition** — `PATCH /agents/ratatoskr:sindra` (body `ConsumerAgentPatchRequest` = system_prompt+role, extra=forbid; keeps OCEAN/persona/memory) removing the Startup block -> a 1-line `**Opening:**` fallback + reworded the axes-persist line (25686->25449 chars, verified Startup gone); **(3) codified auto-seed:** NEW module `src/ratatoskr/first_message.py` (`FIRST_MESSAGE_PRESETS` dict {agent_id->text} + `seed_preset_first_message` best-effort helper) wired into ALL 3 session-create paths — cli `_amain` (`--send --new`), tui `_resolve_then_run` (bare `--new`), web `_create_session_endpoint` (POST /api/sessions) — so every new Sindra session opens with her greeting. **Best-effort (INV-001: swallows AuthoredHistoryUnavailable/SessionApiFailed/httpx.HTTPError -> NEVER blocks create)**; per-content idempotency key (`ratatoskr-preset-`+sha256[:12]). Contract `docs/contracts/first_message.contract.md` (module-scoped: `module:`+`purpose:`+`touches:` required, NOT `target_module:`) + TDD (9 unit + 1 web wire-in; **the 3 existing sindra bind tests needed a history-endpoint mock** since creating a preset agent now auto-seeds). Suite **612 green**, ruff+mypy clean. **LIVE-PROVEN generation-free**: create sindra session -> auto-seed -> read-back seq-0 assistant greeting (409 chars). Sindra's greeting now lives canonically in the preset registry (repo); her server card no longer carries it. Patch bump (single-commit feature, no downstream coordination). **FOOT-GUN: sindra requires `end_user_id` on session-create (422 `end_user_id_required`) — all real paths pass it from env (RATATOSKR_END_USER_ID) / web server config.** **Then the full quality gate (operator-directed, folded into v0.19.8): heid-code-review (unanimous ZERO implementation drift; 2 test-only fixups — INV-004 verification-claim made explicit re the global rglob test + an exactly-one-POST assertion) + heid-bug-hunt (3/3 convergence caught what the conformance lens structurally COULDN'T — the code matched the contract's NARROW 3-type ERROR_ROUTING, but INV-001's "NEVER raises" is BROADER). HARDENED: broad `except Exception` → None (re-raise `asyncio.CancelledError`, itself a BaseException), soft-guard PREs (return None, NOT assert — a wiring bug can't crash the create path it's wired into), and `asyncio.wait_for(_SEED_TIMEOUT_S=10s)` bounding the seed write (the CLI/TUI clients run read=None for SSE → a stalled /history would otherwise block create forever). Suite 615 green. LESSON: code-matches-ERROR_ROUTING ≠ honors-broad-INV-001 — heid-code-review confirms contract-conformance, heid-bug-hunt catches robustness gaps the contract's own narrow clauses miss; run both.**

persistent-memory.d/2026-07-06-sindra-role-character-rp-character-operator.md

@@ -0,0 +1 @@
+`[2026-07-06]` **Sindra role character-rp -> character (operator).** `character-rp` resolves to a reasoning-tuned RP config (`gen-reasoning` + temp 0.75 + RP `extra_body`); `character` = plain non-reasoning (better for immersive RP). Both non-destructive PATCHes (role is mutable; model is NOT -- server: "PATCH accepts only system_prompt and/or role"). #344 (b19) fixed the role->catalog_id display conflation (the `model` field now shows the ROLE); previously it leaked `gen-reasoning`. Set via raw curl (tier3.py CLI has `--model`, not `--role`).

persistent-memory.d/2026-07-06-tail-2-shipped-v0-19-7-tier-3-prose-docs-re-v.md

@@ -0,0 +1 @@
+`[2026-07-06]` **Tail-2 SHIPPED (`v0.19.7`) — Tier-3 prose docs re-vendored + persona_state body-shape aligned.** worldtree-dev landed the Tier-3 persona/memory/persona_state PROSE docs (`c9e59ec`, on origin) — they serialize as freeform `Any` in the OpenAPI JSON, so the **prose is their source of truth** (my earlier "2.3.0 = #347-only, tail-2 collapsed" was half-wrong: the JSON was #347-only but the prose is separate). Re-vendored `docs/conversation-api-spec.md` (markdown pin, tolerate_drift; `worldtree-spec-rev` 879cefe->c9e59ec, SPEC-PIN history row added). **Consumer fix:** `--set-persona-pad`/`_set_persona_probe` was sending `{pad:[list]}` but the canonical SET body (#317) is `{pad:{pleasure,arousal,dominance}}` (named dict) — aligned it + added a len!=3 guard; updated contract #2 note + set_persona_state docstring + tests. The `set_persona_state` WRAPPER was already correct (freeform pass-through); only the CLI probe drifted. TDD (probe test asserts the dict; +1 wrong-count test). Suite **602 green**, ruff clean. **heid-code-review on #347 (dispatched + returned this session): UNANIMOUS ZERO DRIFT** (Gróa/Hulda/Regin all confirmed the hide-existence 404->`AuthoredHistoryUnavailable` routing holds at wrapper/probe/test layers + the extra="forbid" body-omission + the deliberate write-vs-read 404 asymmetry — confirmation-not-discovery for a well-TDD'd slice against a prescriptive contract). worldtree-dev foot-guns banked in SPEC-PIN + [[reference_worldtree_affect_surface_map]]: ocean single-letter `{O,C,E,A,N}` on /agents/define (#348) vs spelled-out on /characters; memory `{embedder_version, tier3_dreaming}`, stm_* deprecated, allows_world_scope removed->422; only `valence` still 422s.