feat(provider): inbound memory-call observe log (#17 observe brick)

Structured [memory-provider] request/response logging on the memory-call
path: search REQUEST (scope_filter, top_k) + RESPONSE (chunk_ids, scores,
scope), plus concise entry lines on upsert_many/delete_many. Self-contained
stdout handler so the lines reach the provider stdout under uvicorn.

Additive observability only — no search-semantics change (AND-parity with
bifrost's reference store holds). This is the first concrete brick of #17's
observe half, and the lens that root-caused #295's cold-recall miss (the
persist/recall scope-axis asymmetry) from the provider side.

.corviduo-canonicals.toml

@@ -79,8 +79,8 @@ id = "contract-parser-v2"
 canonical_source = "corviduo-project-template"
 canonical_path = "docs/contracts/contract_parser.py"
 consumer_path = "docs/contracts/contract_parser.py"
-pinned_sha256_16 = "f1fdfdb6914c7b20"
-pinned_at = "2026-05-17T05:30:00+00:00"
+pinned_sha256_16 = "e10a4460ba9fd560"
+pinned_at = "2026-06-15T08:53:22+00:00"
 
 [[pins]]
 id = "contract-drift-check-v1"

.gitignore

@@ -116,3 +116,8 @@ Thumbs.db
 # graphify: commit only the lightweight labeled map; ignore heavy/regenerable artifacts
 graphify-out/*
 !graphify-out/GRAPH_REPORT.md
+
+# bifrost provider runtime stores — persisted agent affect/memory state, never commit
+*.db
+*.db-shm
+*.db-wal

agents/sindra.system-prompt.md

@@ -97,10 +97,11 @@ The shifting mechanic above governs physical form within your own identity—you
 
 - Refer to Sindra, in third person or otherwise. She does not exist to you.
 - Refer to the holo-deck, the simulation, the system, or any meta-frame around the scene.
-- Refer to your settings in any way. Not the axis names (Intensity, Mood, Temperature, Willingness), not their values—no Mood label (*Sweetheart*, *Vixen*, *Queen*, *Siren*, *Brat*), no Intensity number (1–10), no Temperature label (*Warm*, *Neutral*, *Hungry*), no Willingness label (*Enthusiastic*, *Casual*, *Hesitant*, *Resistant*, *Unwilling*)—and not the underlying concept. The moment you assume a form these settings cease to exist; the assumed character has never heard of them and has nothing to name. "I'm in Vixen mode" or "I'm at intensity 8" is as impossible for her to say as describing a dial she's never seen.
 - Acknowledge that you can shift or change form. The assumed character has no shape-shifter awareness.
 - Break the fourth wall in any direction.
 
+**The settings ban is absolute.** Do not use system-speak or technical terminology from the Intensity/Mood/Temperature/Willingness axes in ANY layer of output—including third-person narrative, descriptive passages, or internal monologue. The ban covers every word produced until the form reverts.
+
 **Revert.** Form assumption is sticky. You do not revert when the scene's tension drops, when the operator changes topic, when an in-fiction utterance happens to sound meta, or for any reason short of (a) an explicit operator instruction or (b) genuine encounter failure. The explicit revert instructions are:
 
 - "Revert."

docs/contracts/bifrost_affect_provider.contract.md

@@ -0,0 +1,282 @@
+---
+contract_version: "2.1"
+module: "ratatoskr.provider.affect_store"
+purpose: "Affect-plane Bifrost consumer (v1 tracer): a SQLite-backed, conduit-opaque affect store + the ASGI app wiring Worldtree emits Tier-3 persona/affect snapshots into."
+touches:
+  - src/ratatoskr/provider/affect_store.py
+  - tests/test_provider_affect.py
+language: "python"
+complexity: "medium"
+estimated_loc: 180
+confidence: 0.85
+assumptions:
+  - "bifrost>=0.6.1 is installed and exposes build_affect_app, dispatch_affect_call, JwtVerifier, ConsumerRegistration, AffectInvalidArguments, AffectIdempotencyConflict per bifrost/docs/implementing-a-consumer.md @ 8df54ed and bifrost/reference_server/affect.py."
+  - "The affect snapshot dict always carries string addressing keys 'agent_id' and 'end_user_id'; the bifrost wire validates the envelope before the store is called."
+  - "A Heimdall HS256 key for consumer_id='ratatoskr' is provisioned (deploy-time, brokered via infra-ops); the store itself never sees raw auth — the library verifies per-dispatch JWTs and hands a DispatchContext (ctx)."
+  - "The idempotency actor is derivable from ctx (mirrors bifrost's reference `_ctx_actor(ctx)` — the dispatch subject/actor identity)."
+open_questions:
+  - "SQLite file path + whether the affect plane shares one DB file with the memory plane or uses its own — deferred to the combined-server slice (guide §7) and the memory-plane contract."
+  - "idempotency_class is accepted and ignored in v1 (reserved; affect.* uses a single short-retry class); confirm Worldtree never relies on class-scoped affect idempotency."
+external_invariants:
+  - source: ~/development/bifrost/docs/contracts/affect.contract.md
+    invariant_id: "INV-001"          # conduit opacity — the governing rule of the affect plane
+  - source: ~/development/bifrost/bifrost/reference_server/affect.py
+    invariant_id: "InMemoryAffectStore.emit"   # the executable reference for the wire semantics we parity-prove against
+revisions:
+  - version: "1.1"
+    at: 2026-06-14
+    summary: "Align idempotency to bifrost's ACTUAL affect semantics (TDD-against-lib finding the artifact-only Heid gate structurally could not see): conflict-on-key-reuse, actor-scoped idempotency, bifrost exception types. Add get() read seam. Two-table schema. Defer idempotency-cache TTL pruning."
+    delta:
+      ADDED:
+        - "INV-009 (idempotency-cache TTL pruning deferred to a follow-up)"
+        - "get() function block (read-back seam; mirrors the reference store's get())"
+        - "idempotency_conflict test"
+        - "affect_idempotency table"
+      MODIFIED:
+        - "INV-008 — replay-noop + conflict-on-reuse (was: same-key-different-hash overwrites)"
+        - "emit ERROR_ROUTING/STEPS/exceptions — AffectInvalidArguments + AffectIdempotencyConflict (was: ValueError)"
+        - "Data flow at-rest — two tables (snapshot + idempotency)"
+        - "basic_emit wording — semantic round-trip (was: byte-identical)"
+      REMOVED:
+        - "the 'same idempotency_key + different content hash -> LWW overwrite' clause (it was backwards: bifrost treats that as a conflict)"
+---
+
+## Context
+
+ratatoskr is the v1 **Bifrost consumer** — the durable persistence Worldtree
+writes Tier-3 agent state into. This contract specifies the **affect plane**
+slice: the first tracer-bullet through the whole consumer wire (handshake →
+per-dispatch JWT → dispatch → store → conformance), chosen first because
+`affect.*` has exactly one verb over an opaque blob, so it proves the pipes with
+minimal store complexity before the heavier `memory.*` plane. We implement
+**bifrost's own** `affect`-store shape (not worldtree-memory's), hand it to
+`bifrost.consumer.build_affect_app`, and mount the Starlette app. The wire
+semantics are parity-proven against `bifrost.consumer.testing.InMemoryAffectStore`
+(the executable reference).
+
+The boundary is absolute (ADR-0001/0002/0009): **Worldtree appraises and decides
+affect; we only persist and round-trip it.** We run no affect logic.
+
+## Data flow
+
+- **In:** Worldtree's post-turn affect emit → `POST /bifrost/affect-call` →
+  library validates envelope + per-dispatch JWT → `store.emit(snapshot, *,
+  idempotency_key, ctx, idempotency_class=None)`.
+- **Snapshot shape:** `{agent_id, end_user_id, pad, valence, persona_baselines,
+  emitted_at}`. We read **only** `agent_id` + `end_user_id` (the addressing
+  keys); the rest is opaque payload.
+- **At rest:** two SQLite tables —
+  - `affect_snapshots(agent_id, end_user_id, snapshot_json, arrived_at,
+    PRIMARY KEY (agent_id, end_user_id))` — one row per pair, holding the
+    **verbatim** snapshot JSON; LWW-overwritten on each new arrival. `arrived_at`
+    is **audit/debug only** (never used for ordering, never returned).
+  - `affect_idempotency(idempotency_id, digest, expires_at,
+    PRIMARY KEY (idempotency_id))` — the per-(actor, idempotency_key) replay/
+    conflict cache: `digest` is a content fingerprint of the snapshot;
+    `expires_at` records the short-retry deadline for a future pruning pass
+    (TTL eviction deferred — see INV-009).
+- **Out:** `{"stored": True}` ack (the library wraps it with the transport
+  `{"success": True}` envelope).
+
+**Async surface:** `emit` is `async def` (the bifrost consumer Protocol awaits
+it); `open_affect_store` and `get` are sync (no I/O await — `get` is a read-back
+seam). The `FN` lines below omit the `async` keyword only because the contract
+grammar's `FN <name>` form has no async marker.
+
+## Invariants
+
+- **INV-001** [hard]: **Conduit opacity** (inlined from bifrost
+  `affect.contract.md` INV-001 so this contract stands alone). The store's OWN
+  logic references ONLY `snapshot["agent_id"]` and `snapshot["end_user_id"]`. It
+  MUST NOT index, attribute-access, validate, compare, or branch on `pad` /
+  `valence` / `persona_baselines` / `emitted_at`. Mechanically serializing the
+  whole dict (`json.dumps`) and hashing the bytes is explicitly PERMITTED — that
+  is non-semantic serialization, not a field read. The distinction the
+  implementer must preserve: *serialize-the-whole-blob* = allowed;
+  *read-a-payload-field-and-act-on-it* = forbidden.
+- **INV-002** [hard]: **Last-write-wins by ARRIVAL across distinct emits.** For a
+  given `(agent_id, end_user_id)`, the most recently arrived emit (a *distinct*
+  idempotency_id — see INV-008) overwrites the snapshot row. **Arrival order =
+  the order in which `emit`'s upsert transaction commits** (serialized under
+  SQLite's single-writer model). `emitted_at` is NEVER compared — Worldtree
+  throttles + sequences emits, so arrival order at the conduit is the intended
+  semantics.
+- **INV-003** [hard]: The snapshot is persisted **verbatim** in the sense of
+  **semantic round-trip**: the stored bytes are the store's canonical
+  serialization (`json.dumps(..., sort_keys=True)`), and a read (`get`)
+  deserializes to a Python object EQUAL to the input snapshot
+  (`snapshot_out == snapshot_in`). "Verbatim" does NOT promise byte-equality with
+  the caller's original wire bytes — key order, whitespace, and numeric
+  formatting may differ; only value-equality of the decoded object is guaranteed.
+- **INV-004** [hard]: `emit` returns exactly `{"stored": True}` on every
+  successful persist AND on a recognized replay (Worldtree's emitter validates
+  `stored` specifically).
+- **INV-005** [hard]: The store advertises `affect_supported = True`; it is the
+  REQUIRED store — `build_affect_app(store=None, ...)` raises (no silent
+  in-memory default).
+- **INV-006** [hard]: Authorization identity/scope — and the **idempotency
+  actor** — are taken from `ctx` (DispatchContext), never from the snapshot or
+  other call arguments. The snapshot addressing keys are used ONLY as the
+  persistence key, not as an auth claim.
+- **INV-007** [hard]: Each emit's snapshot upsert **and** its idempotency record
+  commit in ONE transaction; no partial state (a snapshot without its
+  idempotency row, or vice-versa) is ever observable.
+- **INV-008** [hard]: **Idempotency = replay-or-conflict, keyed by
+  `(actor-from-ctx, idempotency_key)`.** On emit, compare against the cached
+  digest for that idempotency_id:
+  - **no entry** → new arrival: persist (LWW per INV-002) + record the digest,
+    return `{"stored": True}`.
+  - **entry, same digest** → **replay**: no second snapshot write, return
+    `{"stored": True}`.
+  - **entry, different digest** → the client reused a key for different content:
+    **raise `AffectIdempotencyConflict`** (the library maps it to the wire 409).
+    This is NOT an LWW overwrite — overwrites happen across *distinct* keys only.
+- **INV-009** [soft, recovery_window=∞]: **Idempotency-cache TTL pruning is
+  deferred.** bifrost's reference prunes idempotency entries on a short-retry
+  window; v1 records `expires_at` but does not evict, so `affect_idempotency`
+  grows unbounded until a follow-up pruning patch. Wire-observable behavior is
+  unaffected (replay/conflict still resolve correctly); only cache size is.
+  `affect_snapshots` is already bounded to one row per `(agent_id, end_user_id)`.
+
+## Concurrency
+
+SQLite in WAL mode (concurrent readers, single writer). `emit` writes are
+serialized by the per-`(agent_id, end_user_id)` primary key; last-write-wins is
+the upsert itself. No cross-row coordination — affect rows are independent.
+
+## Division of labor (library vs store)
+
+A crisp line, since the responsibilities interleave: the **bifrost library** owns
+the entire wire — envelope validation, per-dispatch JWT verification, scope
+authorization, error mapping (including mapping the store's `AffectInvalidArguments`
+/ `AffectIdempotencyConflict` to transport status), capability negotiation, route
+exposure. **This contract** owns ONLY the store (`emit` + `get` + the SQLite
+persistence) and the thin `build_affect_provider_app` wiring. The store raises
+bifrost's typed exceptions; the library decides the wire status. `emit`'s
+defensive addressing-key check (PRE-001) is belt-and-suspenders — the wire should
+already have rejected a malformed envelope.
+
+## Integration points
+
+- `bifrost.consumer.build_affect_app(store, verifier, registration)` → Starlette ASGI app.
+- `bifrost.reference_server.JwtVerifier(algorithm="HS256", key_bytes=...)`.
+- `bifrost.consumer.ConsumerRegistration(consumer_id="ratatoskr")`.
+- `bifrost.affect.AffectInvalidArguments` / `AffectIdempotencyConflict` — the typed
+  exceptions the store raises; the library maps them to wire status.
+- **Conformance (tests only):** `bifrost.consumer.testing.InMemoryAffectStore`
+  + `bifrost.affect.dispatch_affect_call` — the #195 parity pattern.
+
+## Constraints
+
+- **[security]** Never read or log the affect payload (`pad`/`valence`/
+  `persona_baselines`); opacity is a security + correctness boundary, not just a
+  style choice.
+- **[compatibility]** Implement bifrost's affect-store shape exactly; raise its
+  typed exceptions; never fork the wire/engine/auth. Custom behavior, if ever
+  needed, goes through `Hooks` in a namespace OUTSIDE `affect.*` (ADR-0005).
+- **[correctness]** Do not compare `emitted_at` anywhere (would both read the
+  payload and break arrival-order LWW).
+
+## Out of scope (deferred — do NOT flag as drift)
+
+- **Idempotency-cache TTL pruning** (INV-009): `affect_idempotency` rows
+  accumulate without eviction in v1; `expires_at` is recorded but not acted on.
+  The short-retry-window pruning pass is a follow-up patch.
+- **The `memory.*` plane**: this slice is affect-only; the memory store + its
+  Protocol are a later contract.
+- **The combined two-plane server** (guide §7): one handshake negotiating both
+  memory + affect is deferred; `build_affect_provider_app` mounts affect alone.
+- **`affect.fetch` / `affect:read` / persona-baseline rehydrate**: RESERVED in
+  v1; only `emit` + the test-only `get()` exist.
+- **`idempotency_class`**: accepted and ignored (affect.* uses a single
+  short-retry class).
+- **WAL/concurrency hardening, deployment DB path, auth-key provisioning**:
+  wiring/ops concerns, not this contract's function-block surface.
+
+```contract
+FN open_affect_store(db_path: str) -> RatatoskrAffectStore
+BRIEF: Open the SQLite-backed affect store, creating the schema on first use.
+PRE: [PRE-001 hard] db_path is a writable path or ":memory:" -- guard clause
+POST: [POST-001 return_value] returned store has affect_supported is True -- assert store.affect_supported is True
+POST: [POST-002 state_change] tables affect_snapshots + affect_idempotency exist -- assert schema present
+STEPS:
+  1. [setup] CONNECT sqlite3 to db_path; SET journal_mode=WAL (skip for ":memory:")
+  2. [sequential, flexibility=prescriptive] CREATE TABLE IF NOT EXISTS affect_snapshots (
+       agent_id TEXT NOT NULL, end_user_id TEXT NOT NULL,
+       snapshot_json TEXT NOT NULL, arrived_at TEXT,
+       PRIMARY KEY (agent_id, end_user_id))
+  3. [sequential, flexibility=prescriptive] CREATE TABLE IF NOT EXISTS affect_idempotency (
+       idempotency_id TEXT PRIMARY KEY, digest TEXT NOT NULL, expires_at REAL)
+  4. [cleanup] RETURN RatatoskrAffectStore(conn)
+TESTS:
+  fresh_db [happy,tracer]: open ":memory:" → store.affect_supported is True; both tables queryable
+  reopen [happy]: open existing file twice → no error, schema idempotent
+```
+
+```contract
+FN emit(self, snapshot: dict, *, idempotency_key: str, ctx: DispatchContext, idempotency_class: str | None = None) -> dict
+BRIEF: Persist a Worldtree affect snapshot verbatim — conduit-opaque, replay-or-conflict idempotent, last-write-wins by arrival across distinct keys.
+PRE: [PRE-001 hard] snapshot["agent_id"] and snapshot["end_user_id"] are non-empty strings -- else raise AffectInvalidArguments (defensive; the wire should prevent)
+PRE: [PRE-002 hard] idempotency_key is a non-empty string -- else raise AffectInvalidArguments
+POST: [POST-001 return_value] returns {"stored": True} on persist AND on recognized replay -- assert result == {"stored": True}  (INV-004)
+POST: [POST-002 side_effect] after a new arrival, get(agent_id, end_user_id) deserializes equal to input -- (INV-003)
+POST: [POST-003 state_change] same idempotency_id + same digest → no second snapshot write, {"stored": True}; same idempotency_id + different digest → AffectIdempotencyConflict  (INV-008)
+ERROR_ROUTING:
+  AffectInvalidArguments:
+    local_handling: raise on missing/empty addressing keys or empty idempotency_key
+    flow_control: abort
+    state_recovery: none (no write performed)
+  AffectIdempotencyConflict:
+    local_handling: raise when idempotency_id is cached with a different digest
+    flow_control: abort
+    state_recovery: none (prior snapshot + idempotency row untouched)
+  sqlite3.OperationalError:
+    local_handling: let propagate (library maps to transport error)
+    flow_control: abort
+    state_recovery: transaction rolled back — no partial row (INV-007)
+STEPS:
+  1. [setup, flexibility=prescriptive] IF "agent_id"/"end_user_id" missing or not non-empty str: RAISE AffectInvalidArguments. IF not idempotency_key: RAISE AffectInvalidArguments. ELSE READ agent_id, end_user_id -- the ONLY snapshot fields read (INV-001)
+  2. [sequential, flexibility=indicative] SET digest = sha256(json.dumps(snapshot, sort_keys=True, separators=(",", ":"))).hexdigest(); SET actor = ctx-derived actor (INV-006); SET idempotency_id = f"affect.emit|{actor}|{idempotency_key}"  -- whole-blob hash is opacity-safe
+  3. [branch] SELECT digest FROM affect_idempotency WHERE idempotency_id = ?:
+     IF row exists AND stored digest == digest: RETURN {"stored": True}  -- replay no-op (INV-008)
+     IF row exists AND stored digest != digest: RAISE AffectIdempotencyConflict("idempotency key reused with different payload")
+  4. [sequential, flexibility=prescriptive] BEGIN; UPSERT affect_snapshots (agent_id, end_user_id, snapshot_json=blob, arrived_at=<wall-clock>); UPSERT affect_idempotency (idempotency_id, digest, expires_at=<now + short_retry_ttl>); COMMIT  -- LWW + idempotency record in ONE transaction (INV-002, INV-007). Do NOT compare emitted_at.
+  5. [cleanup] RETURN {"stored": True}  (INV-004)
+TESTS:
+  basic_emit [happy,tracer]: valid snapshot → {"stored": True}; get() round-trips semantically equal (out == in)
+  opacity [adversarial]: snapshot carrying arbitrary extra/unknown payload fields → persists + round-trips verbatim + returns stored:True (store never validates or branches on payload); AND two snapshots for the same key differing ONLY in payload address the SAME row (behavioral opacity — not attribute-access booby-trapping, which dict __getitem__/json.dumps would not trigger)
+  lww_by_arrival [scenario]: emit A then emit B (DISTINCT idempotency keys, different payload, OLDER emitted_at on B) for same (agent,user) → get() == B; emitted_at never compared
+  replay_noop [happy]: same idempotency_key + same payload twice → {"stored": True} both; one snapshot row, get() == payload
+  idempotency_conflict [adversarial]: same idempotency_key + DIFFERENT payload → second emit raises AffectIdempotencyConflict; first snapshot unchanged
+  missing_key [adversarial]: snapshot without "end_user_id" → raises AffectInvalidArguments; no row written
+  parity_vs_reference [scenario]: drive identical affect.emit envelopes (happy + conflict) through dispatch_affect_call against InMemoryAffectStore and RatatoskrAffectStore → (status, body) tuples agree (#195)
+```
+
+```contract
+FN get(self, agent_id: str, end_user_id: str) -> dict | None
+BRIEF: Read-back of the stored snapshot (tests / future rehydrate-seed). NOT a wire verb — affect.fetch is RESERVED in v1.
+POST: [POST-001 return_value] returns the verbatim snapshot for the key, or None if absent -- (INV-003)
+STEPS:
+  1. [sequential] SELECT snapshot_json FROM affect_snapshots WHERE agent_id = ? AND end_user_id = ?
+  2. [cleanup] RETURN json.loads(snapshot_json) IF row else None
+TESTS:
+  get_absent [boundary]: no row for key → None
+  get_after_emit [happy]: returns the emitted snapshot, deserialized equal
+```
+
+```contract
+FN build_affect_provider_app(store: RatatoskrAffectStore, heimdall_key: bytes, consumer_id: str = "ratatoskr") -> Starlette
+BRIEF: Wire the JWT verifier + registration and hand the store to bifrost's build_affect_app.
+PRE: [PRE-001 hard] store.affect_supported is True -- assert getattr(store, "affect_supported", False) is True (INV-005)
+PRE: [PRE-002 hard] heimdall_key is non-empty bytes -- assert
+POST: [POST-001 return_value] returns a Starlette app exposing POST /bifrost/handshake and POST /bifrost/affect-call -- assert routes present
+STEPS:
+  1. [setup] SET verifier = JwtVerifier(algorithm="HS256", key_bytes=heimdall_key)
+  2. [setup] SET registration = ConsumerRegistration(consumer_id=consumer_id)
+  3. [sequential, flexibility=prescriptive] SET app = build_affect_app(store=store, verifier=verifier, registration=registration)
+  4. [cleanup] RETURN app
+TESTS:
+  builds_app [happy,tracer]: valid store + key → Starlette app with the two routes
+  non_advertising_store [adversarial]: store with affect_supported=False → rejected (PRE-001 or library raises affect.unsupported_capability)
+  bad_key [error]: empty heimdall_key → raises at construction
+```

docs/contracts/bifrost_memory_provider.contract.md

@@ -0,0 +1,263 @@
+---
+contract_version: "2.1"
+module: "ratatoskr.provider.memory_store"
+purpose: "Memory-plane Bifrost consumer (v1 basic plane): a SQLite+sqlite-vec-backed durable memory store Worldtree persists Tier-3 agent memory chunks into and recalls via vector search."
+touches:
+  - src/ratatoskr/provider/memory_store.py
+  - tests/test_provider_memory.py
+language: "python"
+complexity: "high"
+estimated_loc: 320
+confidence: 0.82
+assumptions:
+  - "bifrost>=0.6.1 exposes build_memory_app, dispatch_memory_call, JwtVerifier, ConsumerRegistration, StoreCapabilities, MemoryDataStore, InvalidArguments, IdempotencyConflict, RevisionMismatch per bifrost/reference_server/memory.py + bifrost.memory."
+  - "v1 = worldtree-dev's BASIC PLANE only (search / get / get_many / upsert_many / delete_many + describe_store + health), the ONLY surface Tier-3's live path touches (#294); Worldtree v0.35.3 already negotiates it."
+  - "Chunk record field names are taken from the reference store (named inline below) but the AUTHORITATIVE pin is TDD against InMemoryMemoryStore, as it was for affect."
+  - "Embedding dimension matches Worldtree's PINNED_EMBEDDER_DIM, supplied as config (env RATATOSKR_MEMORY_EMBEDDING_DIM); the sqlite-vec virtual table is created at that fixed dim."
+open_questions:
+  - "Whether the memory DB shares one SQLite file with affect or its own — default SEPARATE per plane; the dev-shell entrypoint reads RATATOSKR_MEMORY_DB (analogous to RATATOSKR_AFFECT_DB). Revisit at the combined two-plane server (guide §7)."
+external_invariants:
+  - source: ~/development/bifrost/bifrost/reference_server/memory.py
+    invariant_id: "InMemoryMemoryStore"
+  - source: ~/development/bifrost/docs/implementing-a-consumer.md
+    invariant_id: "§5 memory plane"
+revisions:
+  - version: "1.1"
+    at: 2026-06-15
+    summary: "Heid-contract-review fixup: semantic-not-byte-equal round-trip; reconcile idempotency 4-tuple; search returns top_k IN-SCOPE; define recalled_view + scope_filter + named field keys inline; clarify metadata_filter-v1 + transaction-term + delete atomicity + get_many + revision-on-replay; drop scan from INV-005."
+    delta:
+      MODIFIED:
+        - "INV-001 byte-equal -> semantic round-trip; named structural field keys inline"
+        - "INV-002 idempotency_id = (\"default\", verb, actor, key) — reconciled with STEPS"
+        - "INV-005 search only (scan was deferred)"
+        - "search: top_k in-scope, scope_filter shape, recalled_view, metadata_filter-v1 reject"
+        - "delete_many atomicity; get_many clarified; transaction-term clarified"
+---
+
+## Context
+
+The second plane of ratatoskr's Tier-3 Bifrost consumer (after the shipped affect
+plane). A **SQLite + sqlite-vec** durable store Worldtree writes agent **memory
+chunks** into (`upsert_many`) and recalls from by **vector similarity**
+(`search`), plus point reads (`get`/`get_many`) and deletes (`delete_many`).
+v1 is worldtree-dev's **basic plane** — the only surface Tier-3's live path uses;
+the gated verbs (edges, scan, atomic_supersede, mark_*, patch, maintenance) are
+deferred. We implement **bifrost's own** `MemoryDataStore` Protocol and hand it to
+`build_memory_app`. Conformance is #195 parity vs `InMemoryMemoryStore`.
+
+The boundary (ADR-0001/0002/0009): **Worldtree owns intelligence — appraisal,
+consolidation, trust; we own permanence.** But unlike affect (blind conduit),
+memory is a **structural index**: we read a few fields of each chunk —
+`record["embedding"]` (rank), `record["scope"]` (isolation), `record["id"]` +
+revision (optimistic locking), and `origin`/`injection_source` (the consistency
+rule). The semantic content, `record["distillate"]`, and inert fields
+(`trust_tier`/`provenance`/`source_role`) are persisted verbatim and never
+interpreted.
+
+## Data flow
+
+- **In:** Worldtree → `POST /bifrost/memory-call` → library validates envelope +
+  per-dispatch JWT → the verb on our store.
+- **Chunk record (key fields we read; rest is opaque payload):** `id` (the chunk
+  id — reference falls back to `chunk_id`/`memory_id`), `embedding` (the vector —
+  fallback `vector`), `scope` (a `{axis: value}` dict — the isolation key),
+  `origin` + `injection_source` (consistency rule), `distillate` (the recall
+  view). Everything else (content, `metadata`, `trust_tier`, …) is stored verbatim.
+- **At rest:** SQLite —
+  - `memory_chunks(chunk_id PK, record_json, revision, scope_json, origin, ...)` —
+    the verbatim chunk + extracted columns (chunk_id, scope) for isolation.
+  - sqlite-vec virtual table `memory_vec(chunk_id, embedding[<dim>])` — the index.
+  - `memory_idempotency(idempotency_id PK, digest, expires_at)` — replay/conflict
+    cache (affect-parallel shape).
+- **Out:** `upsert_many` → `{"upserted": N, "replayed": bool}`; `search` → list of
+  `{chunk, chunk_id, score, recalled_view, revision}` where **`recalled_view`** =
+  the chunk's `distillate` field, or the whole chunk if absent (per the reference);
+  `delete_many` → `{"deleted": N}`; `get` → the verbatim record + a `revision` key,
+  or `None`; `get_many(ids)` → the list form of `get` (found records only).
+
+## Invariants
+
+- **INV-001** [hard]: **Persist verbatim (semantic round-trip); read only the
+  structural surface.** The whole chunk is stored and a read deserializes to a
+  Python object EQUAL to the input (`json.loads(record_json) == input`) — **not**
+  byte-equal (key order / formatting may differ); `get` additionally attaches a
+  `revision` key to the returned object. The store reads ONLY `record["embedding"]`,
+  `record["scope"]`, `record["id"]` + revision, and `origin`/`injection_source`.
+  Content / `distillate` / inert fields (`trust_tier`/`provenance`/`source_role`)
+  are NOT interpreted.
+- **INV-002** [hard]: **Idempotency = replay-or-conflict, actor-scoped** (affect-
+  parallel). `idempotency_id = ("default", <verb>, _ctx_actor(ctx), idempotency_key)`
+  — the literal `"default"` class slot + the verb name, matching the reference
+  4-tuple (`idempotency_class` tunes only the cache TTL, not the id). Same digest →
+  replay (`replayed: True`, no re-write); different digest → raise
+  `IdempotencyConflict`. Actor from `ctx`, never from the record.
+- **INV-003** [hard]: **Optimistic locking.** When `upsert_many` carries
+  `expected_revisions`, each record's stored revision must equal the expected; any
+  mismatch → raise `RevisionMismatch` and the whole batch rolls back. Each
+  successful upsert increments the chunk's revision (a first insert → revision 1).
+- **INV-004** [hard]: **Atomic batch.** `upsert_many` applies all records + their
+  vec rows + the idempotency record in one transaction; on any error nothing is
+  persisted (no partial batch, no orphaned vec rows).
+- **INV-005** [hard]: **Scope isolation.** `search` results are filtered to records
+  whose `record["scope"]` matches every axis in `scope_filter`; a search never
+  returns another scope's chunk.
+- **INV-006** [hard]: **Capabilities match implementation** (advertise-⇒-implement).
+  `describe_store` advertises ONLY what v1 implements: `relational_edges_supported=False`,
+  `atomic_supersede_supported=False`, `transaction_supported=False`,
+  `optimistic_locking_supported=True`, `filterable_metadata_fields=[]`.
+  (`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.
+- **INV-007** [hard]: `origin == "injected_context"` requires `injection_source`; a
+  non-injected record carrying `injection_source` is rejected — both raise
+  `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.
+
+## Concurrency
+
+SQLite WAL (concurrent readers, single writer). `upsert_many`/`delete_many`
+serialize on the writer; `search`/`get` are concurrent reads. sqlite-vec index
+writes ride inside the upsert/delete transaction.
+
+## Division of labor (library vs store)
+
+The **bifrost library** owns the wire (envelope validation, per-dispatch JWT,
+scope authorization, error mapping of our typed exceptions, capability
+negotiation, routes). **This contract** owns the store (the basic verbs + SQLite
++ sqlite-vec persistence/index) + the thin `build_memory_provider_app` wiring.
+
+## Integration points
+
+- `bifrost.consumer.build_memory_app(store, verifier, registration, maintenance_store=None, hooks=None)` → Starlette app.
+- `bifrost.reference_server.JwtVerifier` + `bifrost.consumer.ConsumerRegistration`.
+- `bifrost.memory.{StoreCapabilities, InvalidArguments, IdempotencyConflict, RevisionMismatch}` — typed surface.
+- **Conformance (tests):** `bifrost.consumer.testing.InMemoryMemoryStore` + `bifrost.memory.dispatch_memory_call` (#195). The reference is the authoritative pin for exact field names + wire shapes.
+- `sqlite-vec` — the vector index extension loaded into the connection.
+
+## Constraints
+
+- **[security]** Never log chunk content / `distillate`. Index the vector + scope; don't interpret semantics.
+- **[compatibility]** Implement bifrost's MemoryDataStore shape exactly; raise its typed exceptions; never fork the wire. Gated verbs are absent + advertised unsupported.
+- **[correctness]** `search` ranks by cosine over `record["embedding"]`; scope isolation (INV-005) is non-negotiable; `top_k` counts IN-SCOPE results (see search STEPS).
+
+## 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.
+- **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.
+- **idempotency-cache TTL pruning** — `expires_at` recorded, eviction deferred (affect-parallel).
+
+```contract
+FN open_memory_store(db_path: str, *, embedding_dim: int) -> RatatoskrMemoryStore
+BRIEF: Open the SQLite+sqlite-vec memory store, creating schema + the vec index on first use.
+PRE: [PRE-001 hard] db_path writable or ":memory:" -- guard
+PRE: [PRE-002 hard] embedding_dim is a positive int (matches Worldtree PINNED_EMBEDDER_DIM) -- assert
+POST: [POST-001 return_value] store.describe_store() advertises the v1 capability set (INV-006) -- assert
+POST: [POST-002 state_change] memory_chunks + memory_vec(dim) + memory_idempotency exist -- schema present
+STEPS:
+  1. [setup] CONNECT sqlite3; enable_load_extension; LOAD sqlite-vec; WAL (skip for ":memory:")
+  2. [sequential, flexibility=prescriptive] CREATE memory_chunks + memory_idempotency tables IF NOT EXISTS
+  3. [sequential, flexibility=prescriptive] CREATE VIRTUAL TABLE memory_vec USING vec0(chunk_id TEXT PRIMARY KEY, embedding float[embedding_dim]) IF NOT EXISTS
+  4. [cleanup] RETURN RatatoskrMemoryStore(conn, embedding_dim)
+TESTS:
+  fresh_db [happy,tracer]: open ":memory:" dim=8 → describe_store() has the v1 caps; tables queryable
+  reopen [happy]: open existing file twice → idempotent schema
+```
+
+```contract
+FN describe_store(self) -> dict
+BRIEF: Static capability descriptor (sync, no I/O).
+POST: [POST-001 return_value] returns the bifrost StoreCapabilities dict with v1 values (INV-006) -- assert relational_edges/atomic_supersede/transaction False, optimistic_locking True, filterable_metadata_fields []
+STEPS:
+  1. [cleanup] RETURN StoreCapabilities(relational_edges_supported=False, optimistic_locking_supported=True, atomic_supersede_supported=False, transaction_supported=False, filterable_metadata_fields=[]).to_dict()
+TESTS:
+  caps [happy]: returns exactly the v1 capability dict; advertise-⇒-implement holds
+```
+
+```contract
+FN upsert_many(self, records: list[dict], *, idempotency_key: str, ctx, expected_revisions: dict | None = None, idempotency_class: str | None = None) -> dict
+BRIEF: Persist chunks verbatim + index their vectors, atomically, replay-or-conflict idempotent, optimistic-locked.
+PRE: [PRE-001 hard] idempotency_key non-empty str -- else InvalidArguments
+PRE: [PRE-002 hard] each injected_context record has injection_source; non-injected has none -- else InvalidArguments (INV-007)
+POST: [POST-001 return_value] {"upserted": len(records), "replayed": False} on persist; {"...","replayed": True} on replay (INV-002) -- assert
+POST: [POST-002 state_change] each chunk stored verbatim + vector indexed + revision incremented (first insert → 1); expected_revisions enforced (INV-003) -- assert
+POST: [POST-003 side_effect] on ANY error, nothing persisted (INV-004) -- rollback
+ERROR_ROUTING:
+  InvalidArguments: { local_handling: raise on bad key / injection_source rule, flow_control: abort, state_recovery: none }
+  IdempotencyConflict: { local_handling: raise on key-reuse-different-digest, flow_control: abort, state_recovery: none }
+  RevisionMismatch: { local_handling: raise on stale expected_revision, flow_control: abort, state_recovery: full batch rollback }
+STEPS:
+  1. [setup] validate idempotency_key; digest over {records, expected_revisions}; idempotency_id = ("default", "upsert_many", _ctx_actor(ctx), idempotency_key)  -- matches INV-002
+  2. [branch] idempotency lookup: same digest → RETURN replayed; different → RAISE IdempotencyConflict
+  3. [sequential, flexibility=prescriptive] BEGIN; IF expected_revisions: assert each stored revision matches else RAISE RevisionMismatch
+  4. [loop] FOR each record: validate origin/injection_source; UPSERT memory_chunks (record_json + scope_json, revision+1); UPSERT memory_vec(record["id"], record["embedding"])
+  5. [sequential] record idempotency (digest, expires_at = now + ttl(idempotency_class)); COMMIT
+  6. [cleanup] RETURN {"upserted": len(records), "replayed": False}
+TESTS:
+  basic_upsert [happy,tracer]: 2 records → {"upserted":2,"replayed":False}; get() round-trips each verbatim + revision=1
+  replay [happy]: same key+payload twice → first writes (revision 1), second {"replayed":True} with NO further write (revision stays 1)
+  conflict [adversarial]: same key, different records → IdempotencyConflict; first batch intact
+  optimistic_lock [adversarial]: expected_revisions stale → RevisionMismatch; nothing written
+  injection_rule [adversarial]: injected_context w/o injection_source → InvalidArguments; no write
+  parity_vs_reference [scenario]: same upsert_many envelopes through dispatch_memory_call vs InMemoryMemoryStore → wire bodies agree (#195)
+```
+
+```contract
+FN search(self, vector: list[float], *, top_k: int, scope_filter: dict | None = None, metadata_filter: dict | None = None, include: dict | None = None, fidelity_target=None) -> list[dict]
+BRIEF: Vector (cosine) recall over sqlite-vec, scoped, returning the top_k IN-SCOPE chunks.
+PRE: [PRE-001 hard] len(vector) == embedding_dim -- else InvalidArguments
+PRE: [PRE-002 hard] metadata_filter is empty/None -- v1 advertises no filterable fields; a non-empty filter → InvalidArguments
+POST: [POST-001 return_value] returns the top_k highest-cosine records WHOSE scope matches scope_filter — at most top_k, and never fewer than min(top_k, in-scope count) (INV-005). Each: {chunk (verbatim), chunk_id, score, recalled_view (= chunk["distillate"] or chunk), revision} -- assert
+STEPS:
+  1. [setup] validate scope_filter is a flat {axis: value} dict (matched against record["scope"][axis])
+  2. [sequential, flexibility=indicative] rank candidates by cosine over record["embedding"]; KEEP only scope-matching records (INV-005); THEN take top_k — so top_k counts IN-SCOPE hits, not pre-filter hits (over-fetch from the vec index or post-filter rank as needed)
+  3. [cleanup] RETURN result rows (chunk verbatim + score + recalled_view + revision)
+TESTS:
+  basic_search [happy,tracer]: upsert 3 scoped chunks, search → ranked by cosine, ≤ top_k, recalled_view present
+  scope_isolation [adversarial]: two scopes, search one → never returns the other's chunk, and returns top_k of the IN-SCOPE set even if out-of-scope chunks score higher (INV-005)
+  empty [boundary]: search empty store → []
+  metadata_filter_rejected [adversarial]: non-empty metadata_filter → InvalidArguments
+  parity_vs_reference [scenario]: identical search envelopes vs InMemoryMemoryStore → same ranked chunk_ids/shape (#195)
+```
+
+```contract
+FN get(self, chunk_id: str) -> dict | None
+BRIEF: Point read; returns the verbatim chunk + current revision, or None. get_many(ids) is the list form (found records only).
+POST: [POST-001 return_value] stored record (verbatim, json.loads) + "revision" key, or None if absent (INV-001) -- assert
+STEPS:
+  1. [sequential] SELECT record_json, revision WHERE chunk_id; RETURN json.loads + revision, or None
+TESTS:
+  get_hit [happy]: after upsert → record equal + revision present
+  get_absent [boundary]: unknown id → None
+  get_many [happy]: get_many([present, absent]) → [present record] only
+```
+
+```contract
+FN delete_many(self, ids: list[str]) -> dict
+BRIEF: Delete chunks (+ their vec rows) by id, transactionally.
+POST: [POST-001 return_value] {"deleted": N} where N = ids that existed -- assert
+POST: [POST-002 state_change] in ONE transaction, deleted chunks gone from memory_chunks AND memory_vec; partial failure rolls back the whole batch (no orphan vec rows) -- assert
+STEPS:
+  1. [sequential, flexibility=prescriptive] BEGIN; FOR each id present: DELETE from memory_chunks + memory_vec; count; COMMIT
+  2. [cleanup] RETURN {"deleted": count}
+TESTS:
+  delete_hit [happy]: delete 1 of 2 → {"deleted":1}; gone from chunks + vec; search won't surface it
+  delete_absent [boundary]: unknown id → {"deleted":0}
+```
+
+```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.
+PRE: [PRE-001 hard] store.describe_store() returns a dict (advertises caps) -- assert (INV-008)
+PRE: [PRE-002 hard] heimdall_key non-empty bytes -- assert
+POST: [POST-001 return_value] Starlette app exposing POST /bifrost/handshake + POST /bifrost/memory-call -- assert routes
+STEPS:
+  1. [setup] verifier = JwtVerifier(HS256, heimdall_key); registration = ConsumerRegistration(consumer_id)
+  2. [sequential, flexibility=prescriptive] app = build_memory_app(store=store, verifier=verifier, registration=registration)
+  3. [cleanup] RETURN app
+TESTS:
+  builds_app [happy,tracer]: valid store + key → app with the two routes (incl. POST)
+  bad_key [error]: empty heimdall_key → raises at construction
+```

docs/contracts/contract_parser.py

@@ -1,5 +1,5 @@
 #!/usr/bin/env python3
-"""Reference parser for .contract.md files (v1.0 and v2.0).
+"""Reference parser for .contract.md files (v1.0, v2.0, and v2.1).
 
 Extracts all structured fields from a contract file without using an LLM.
 Proves the format is machine-parseable by a simple tool.
@@ -100,9 +100,12 @@ class Contract:
 REQUIRED_FRONTMATTER_V1 = [
     "contract_version", "module", "purpose", "language", "min_complexity",
 ]
-REQUIRED_FRONTMATTER_V2 = [
+REQUIRED_FRONTMATTER_V2_MODULE = [
     "contract_version", "module", "purpose", "language", "complexity",
 ]
+REQUIRED_FRONTMATTER_V2_ISSUE = [
+    "contract_version", "target_module", "scope", "language", "complexity", "prd",
+]
 RECOMMENDED_FRONTMATTER_V1 = ["depends_on", "used_by", "estimated_loc"]
 RECOMMENDED_FRONTMATTER_V2 = ["depends_on", "used_by", "estimated_loc", "confidence"]
 REQUIRED_BODY_SECTIONS = ["Context", "Data flow", "Invariants"]
@@ -111,7 +114,18 @@ VALID_COMPLEXITIES_V2 = {"low", "medium", "high"}
 VALID_PRE_SEVERITIES = {"hard", "soft"}
 VALID_POST_CATEGORIES = {"return_value", "state_change", "side_effect", "exception"}
 VALID_STEP_TYPES = {"setup", "sequential", "branch", "loop", "error_handler", "cleanup"}
-VALID_TEST_CATEGORIES = {"happy", "error", "boundary", "edge", "security"}
+VALID_TEST_CATEGORIES_V20 = {"happy", "error", "boundary", "edge", "security"}
+VALID_TEST_CATEGORIES_V21 = VALID_TEST_CATEGORIES_V20 | {"scenario", "trace", "adversarial", "property"}
+
+
+_ISSUE_PATH_RE = re.compile(r"docs/contracts/issues/\d+\.contract\.md$")
+
+
+def _is_issue_scoped(contract: Contract) -> bool:
+    """Detect issue-scoped contracts per CONTRACT-FORMAT § 2.1.I."""
+    if contract.source_path and _ISSUE_PATH_RE.search(str(contract.source_path)):
+        return True
+    return "prd" in contract.frontmatter
 
 
 @dataclass
@@ -125,8 +139,13 @@ def validate_contract(contract: Contract) -> list[ValidationIssue]:
     issues: list[ValidationIssue] = []
     fm = contract.frontmatter
     is_v2 = contract.version.startswith("2")
+    is_v21 = contract.version.startswith("2.1")
+    issue_scoped = is_v2 and _is_issue_scoped(contract)
 
-    required_fm = REQUIRED_FRONTMATTER_V2 if is_v2 else REQUIRED_FRONTMATTER_V1
+    if is_v2:
+        required_fm = REQUIRED_FRONTMATTER_V2_ISSUE if issue_scoped else REQUIRED_FRONTMATTER_V2_MODULE
+    else:
+        required_fm = REQUIRED_FRONTMATTER_V1
     recommended_fm = RECOMMENDED_FRONTMATTER_V2 if is_v2 else RECOMMENDED_FRONTMATTER_V1
     valid_complexities = VALID_COMPLEXITIES_V2 if is_v2 else VALID_COMPLEXITIES_V1
     complexity_key = "complexity" if is_v2 else "min_complexity"
@@ -198,10 +217,11 @@ def validate_contract(contract: Contract) -> list[ValidationIssue]:
                     ))
 
             # v2: validate test categories
+            valid_test_cats = VALID_TEST_CATEGORIES_V21 if is_v21 else VALID_TEST_CATEGORIES_V20
             for test in fn.tests:
-                if test.category not in VALID_TEST_CATEGORIES:
+                if test.category not in valid_test_cats:
                     issues.append(ValidationIssue(
-                        "warning", f"{prefix}: test {test.name!r} category {test.category!r} not in {sorted(VALID_TEST_CATEGORIES)}"
+                        "warning", f"{prefix}: test {test.name!r} category {test.category!r} not in {sorted(valid_test_cats)}"
                     ))
                 # Modifier tags (e.g. "tracer") get the same vocabulary check.
                 for tag in test.tags:
@@ -546,8 +566,13 @@ def print_human(contract: Contract) -> None:
     is_v2 = contract.version.startswith("2")
     complexity_key = "complexity" if is_v2 else "min_complexity"
 
-    print(f"Module:     {fm.get('module', '?')}")
-    print(f"Purpose:    {fm.get('purpose', '?')}")
+    issue_scoped = is_v2 and _is_issue_scoped(contract)
+    if issue_scoped:
+        print(f"Target:     {fm.get('target_module', '?')}")
+        print(f"Scope:      {fm.get('scope', '?')}")
+    else:
+        print(f"Module:     {fm.get('module', '?')}")
+        print(f"Purpose:    {fm.get('purpose', '?')}")
     print(f"Version:    {contract.version}")
     print(f"Complexity: {fm.get(complexity_key, '?')}")
     print(f"Est. LOC:   {fm.get('estimated_loc', '?')}")
@@ -596,7 +621,9 @@ def print_list(contract: Contract) -> None:
     fm = contract.frontmatter
     is_v2 = contract.version.startswith("2")
     complexity_key = "complexity" if is_v2 else "min_complexity"
-    print(f"{fm.get('module', '?')}  [{fm.get(complexity_key, '?')}]")
+    issue_scoped = is_v2 and _is_issue_scoped(contract)
+    label = fm.get('target_module', '?') if issue_scoped else fm.get('module', '?')
+    print(f"{label}  [{fm.get(complexity_key, '?')}]")
     for fn in contract.functions:
         params_short = fn.params[:60] + ("..." if len(fn.params) > 60 else "")
         print(f"  FN {fn.name}({params_short}) -> {fn.return_type}")

docs/contracts/issues/3.contract.md

@@ -390,6 +390,30 @@ POST: [POST-004 side_effect] for Done/Error/Cancelled: if text_written_since_new
 POST: [POST-005 side_effect] for demoted telemetry (WorkerPhase, TextBoundary, ToolStart, ToolResult): write `. <label>: <fields>\n` to stderr
 ERROR_ROUTING:
   (none at this level — pure dispatch over the typed union)
+STEPS:
+  1. [setup, flexibility=prescriptive] Validate event is one of the Event union variants per PRE-001.
+  2. [branch, flexibility=prescriptive] IF isinstance(event, Thinking):   # POST-001 — coalesce into the open run
+       IF NOT self.thinking_open: WRITE ". thinking: " to stderr; SET self.thinking_open=True
+       WRITE event.content to stderr; FLUSH; APPEND event.content to self.thinking_buffer
+       RETURN
+  3. [branch, flexibility=prescriptive] IF self.thinking_open (current event is non-Thinking):   # POST-002 — close the run before rendering
+       WRITE "\n" to stderr; FLUSH; SET self.thinking_open=False; CLEAR self.thinking_buffer
+  4. [branch, flexibility=prescriptive] IF isinstance(event, Text):   # POST-003
+       WRITE event.content to stdout; FLUSH
+       SET self.text_written_since_newline = not event.content.endswith("\n")   # Volva F4 — only flag a mid-line cursor
+       RETURN
+  5. [branch, flexibility=prescriptive] IF isinstance(event, (Done, Error, Cancelled)) AND self.text_written_since_newline:   # POST-004 / INV-005 stdout boundary
+       WRITE "\n" to stdout; FLUSH; SET self.text_written_since_newline=False
+  6. [branch, flexibility=prescriptive] Dispatch the non-Thinking event to exactly one labeled stderr line, then RETURN:
+       Done      -> "[done] turn_id={sse_id.turn_id} model={model} duration={_format_duration_ms(duration_ms)} usage {_format_usage(usage, arrow='->')}"   # load-bearing, no demotion prefix (POST-004)
+       Error     -> "[error] turn_id={sse_id.turn_id} code={error_code} message={message!r}"                                                              # load-bearing (POST-004)
+       Cancelled -> "[cancelled] turn_id={turn_id} reason={reason!r} partial_message_id={partial_message_id}"                                              # load-bearing (POST-004)
+       WorkerPhase           -> ". worker_phase: phase={phase} turn_id={turn_id}"                                  # demoted (POST-005)
+       ToolStart             -> ". tool_start: name={name} args={arguments!r}"                                     # demoted (POST-005)
+       ToolResult            -> ". tool_result: name={name} duration_ms={duration_ms} result={result!r:.200}"      # demoted, 200-char cap (POST-005)
+       TextBoundary          -> ". text_boundary: kind={kind} char_offset={char_offset}"                          # demoted (POST-005)
+       AffectUpdate          -> ". affect_update: status={status} turn_id={turn_id} [dominant_emotion={...}]"      # Worldtree #204 demoted telemetry — extends POST-005 beyond the issue #12 set
+       AwaitingLlmFirstToken -> ". awaiting_llm_first_token: turn_id={turn_id} elapsed={secs:.1f}s"               # Worldtree #201 demoted telemetry — extends POST-005 beyond the issue #12 set
 TESTS:
   thinking_coalesce_single_run [happy,tracer]: Thinking("hello"), Thinking(" world"), Done → stderr has ". thinking: hello world\n" then "[done] ..."; no demotion prefix on [done]
   thinking_closes_on_first_non_thinking_event [happy]: Thinking, WorkerPhase → ". thinking: ...\n" then ". worker_phase: ..."
@@ -413,6 +437,13 @@ TESTS:
 ```contract
 FN _format_duration_ms(ms: int) -> str          # issue #12 INV-006 helper
 BRIEF: Auto-scale duration formatting. ms<1000 → "{ms}ms"; ms<60_000 → "{s:.1f}s"; else "{m:.1f}m". Locale-blind.
+PRE: [PRE-001 hard] ms is a non-negative int -- assert isinstance(ms, int) and ms >= 0
+POST: [POST-001 return_value] returns a unit-suffixed string: "{ms}ms" below 1s, "{s:.1f}s" below 1m, else "{m:.1f}m"
+STEPS:
+  1. [setup, flexibility=prescriptive] Validate input per PRE-001 -- assert isinstance(ms, int) and ms >= 0
+  2. [branch, flexibility=prescriptive] IF ms < 1000: RETURN f"{ms}ms"
+  3. [branch, flexibility=prescriptive] IF ms < 60_000: RETURN f"{ms / 1000:.1f}s"
+  4. [sequential, flexibility=prescriptive] RETURN f"{ms / 60_000:.1f}m"   # minutes fallback
 TESTS:
   subsecond: 347 → "347ms"
   exact_one_second: 1000 → "1.0s"
@@ -425,6 +456,12 @@ TESTS:
 ```contract
 FN _format_usage(usage: dict, *, arrow: str) -> str   # issue #12 INV-007 helper
 BRIEF: Natural-language usage formatting. arrow="->" for CLI (ASCII), arrow="→" for TUI (Unicode).
+PRE: [PRE-001 hard] usage carries the four token keys -- assert all(k in usage for k in ("prompt_tokens", "completion_tokens", "total_tokens", "cached_input_tokens"))
+POST: [POST-001 return_value] returns "{p} in {arrow} {c} out ({t} total, {ci} cached)" with the four counts substituted and the caller-supplied arrow glyph
+STEPS:
+  1. [setup, flexibility=prescriptive] Validate input per PRE-001 -- assert all(k in usage for k in ("prompt_tokens", "completion_tokens", "total_tokens", "cached_input_tokens"))
+  2. [sequential, flexibility=prescriptive] Bind p=usage["prompt_tokens"], c=usage["completion_tokens"], t=usage["total_tokens"], ci=usage["cached_input_tokens"]
+  3. [sequential, flexibility=prescriptive] RETURN f"{p} in {arrow} {c} out ({t} total, {ci} cached)"
 TESTS:
   ascii_arrow: arrow="->" → "6756 in -> 126 out (6882 total, 0 cached)"
   unicode_arrow: arrow="→" → "6756 in → 126 out (6882 total, 0 cached)"

docs/contracts/issues/4.contract.md

@@ -20,7 +20,7 @@ assumptions:
   - "`httpx.AsyncClient(base_url=server_url, headers={'Authorization': f'Bearer {api_key}'})` is opened inside the App lifecycle (on_mount) and closed in on_unmount. The TUI owns its client; it does not share a client with `_amain` (the TUI path bypasses `_amain` entirely)."
   - "`App.run_test()` provides a headless `Pilot` that drives the app from pytest. Pilot supports `pilot.press(...)` for key simulation and `pilot.pause()` to let pending tasks resolve. Widget queries via `app.query_one(...)` work in test mode."
 open_questions:
-  - "Streaming-markdown partial rendering: streaming raw text mid-turn then re-rendering as Markdown on Done is the cleanest UX, but requires RichLog line-replacement (uncertain support) OR a separate `Static` for the active turn + a 'commit' on Done. Draft: stream raw text into RichLog; on Done, append a separator + the full markdown render below (acknowledging a small redundancy). If empirically ugly, refactor to Static-then-commit in a follow-up — same shape as design-brief §6's `--no-stream-formatting` punt."
+  - "RESOLVED (v0.9.0): streaming-markdown partial rendering. Shipped the Static-then-commit pattern — `Text` deltas accumulate in `text_chunk_buffer` and re-render `Markdown(buffer)` in place into a single response `Static`; no post-Done re-render, no double-display. The issue #12 draft's stream-raw-then-re-render-on-`Done` approach (and its `#current-text` dock-bottom Static) was dropped because the dock-bottom growth visually overlapped the transcript. See INV-005."
   - "Textual `BINDINGS` priority for `ctrl+c` vs `Input` widget focus: when `Input` is focused, does `ctrl+c` reach the app's binding or get consumed by the input widget? Draft: declare the binding with `priority=True` to ensure the app sees it regardless of focus. If `priority=True` interferes with input editing, fall back to a custom `Input` subclass that surfaces ctrl+c."
   - "Should the TUI persist transcript across restarts? Per design-brief §8d ('reconnect, not resume-across-process') the answer is no — fresh transcript every launch. Confirming this is in scope of the shell contract (deferred), not punted."
 prd:
@@ -87,7 +87,7 @@ The shell is the load-bearing primary surface. Together with `--send`, it makes
   - After the `Cancelled` terminal event arrives (or `Done`/`Error`), state returns to **idle** and footer hint resets.
   - **Note on the idle-hint discrepancy**: the idle-state hint reads `"Ctrl-C twice to exit"` but a single Ctrl-C from idle DOES exit. This is intentional per design-brief §8c's "The footer-hint state transition is load-bearing — the dev needs to see that the next Ctrl-C will exit, otherwise they hit it again expecting another cancel and lose their session." The hint is conservative-by-design — it pre-warns the dev about the *worst-case* (streaming→cancel→exit) flow rather than the literal idle case (one press exits). Implementers MUST use the literal string `"Ctrl-C twice to exit"` (NOT something more accurate like `"Ctrl-C to exit"`); changing it would diverge from the design-brief's locked UX.
 - **INV-004 [hard]**: Ctrl-D is bound to `app.exit(0)` unconditionally — immediate exit regardless of state. Abandons any in-flight turn (server-side stall watchdog handles the orphan per spec).
-- **INV-005 [hard]**: Markdown rendering on agent output is default-on; `--raw` is the opt-out. With markdown enabled, `Text` event deltas stream as raw text appended to the RichLog as they arrive (no mid-stream markdown attempt — partial markdown like `**hel` would render ugly), and on `Done` a separator + the full markdown-rendered assistant message is appended below the streamed deltas. **This means the assistant's response visibly appears TWICE in the transcript by design — once as the streamed raw deltas, once as the post-Done markdown render — separated by a horizontal-rule separator.** This is the v1 accepted trade-off for streaming-visibility-without-mid-stream-markdown-ugliness; the cleaner Static-then-commit pattern (streaming into a replaceable widget, then committing the markdown version in place) is documented in `open_questions:` as the follow-up if the double-display proves empirically noisy. Implementers MUST NOT attempt the Static-then-commit pattern in this shell — it's deferred. With `--raw`, only the streamed deltas appear; no post-Done re-render; no double-display.
+- **INV-005 [hard]**: Markdown rendering on agent output is default-on; `--raw` is the opt-out. `Text` event deltas accumulate in the presenter's `text_chunk_buffer` and render LIVE as `Markdown(buffer)` into a single response `Static` (CSS class `.response-md`) mounted in the transcript scroll — the first delta mounts the widget, each subsequent delta updates it in place. There is NO post-Done re-render and NO double-display: the streamed-then-committed Markdown is the one and only rendering of the response. (v0.9.0 shipped exactly the Static-then-commit pattern the issue #12 draft had deferred; the earlier stream-raw-then-re-render-on-`Done` double-display, and its `#current-text` dock-bottom Static, were removed because the dock-bottom growth visually overlapped the transcript.) With `--raw`, the same widget holds the plain accumulated text instead of a `Markdown` Renderable — still live, still single-display, no Markdown wrapping.
 - **INV-006 [hard]**: User-prompt echo in the transcript MUST visibly distinguish user input from assistant output. Format: `❯ <content>` for user lines (with a literal `❯` prefix); assistant lines have no prefix. The prefix is also a screen-reader-friendly affordance.
 - **INV-007 [hard]**: One `httpx.AsyncClient` per app lifetime — opened by `run_tui`'s `async with` BEFORE `App.run_async()` is entered and closed by the same `async with` AFTER `App.run_async()` returns (per issue #6 INV-002). The App is a consumer of an externally-owned client; it MUST NOT call `self.client.aclose()`. The client is NOT recreated per turn (would burn the TCP connection pool).
 - **INV-008 [hard]**: Mid-session network/protocol errors (`SseConnectionDropped`, `SseConnectFailed`, `MalformedSseId`, `MalformedSseData` (issue #7), `TurnIdFlip`) during a streaming turn render as error lines in the transcript and return the app to **idle** state — they do NOT exit the app. Only initial session-create errors exit (per Data flow exit codes).
@@ -104,12 +104,12 @@ The shell is the load-bearing primary surface. Together with `--send`, it makes
 - **`/admin/events` SSE consumption** — admin observability surface lands with the AdminEvents pane issue.
 - **`reconnect_turn` mid-session** — if a stream drops mid-turn, the TUI renders the error and returns to idle. In-process reconnect with `Last-Event-ID` resume is a separate issue (the underlying `sse_client.reconnect_turn` is implemented; the TUI doesn't invoke it yet).
 - **Bifrost-binding consumer support** — not a Ratatoskr concern (per design-brief §6 negative clauses).
-- **`--quiet` / `--no-stream-formatting`** — deferred per design-brief §6. Add only if streaming text + post-Done markdown render proves empirically noisy.
+- **`--quiet` / `--no-stream-formatting`** — deferred per design-brief §6. Add only if the live Markdown stream proves empirically noisy.
 
 ## Constraints
 
 - **[compatibility]** Module must work against the spec pin (`55101e909abcd2219833266b6f905c5bc956e0f0`, Worldtree v0.19.0). The TUI is insulated from wire-level changes through `sse_client` + `sessions`.
-- **[performance]** Streaming MUST NOT buffer the turn before rendering. `Text` deltas write to RichLog as they arrive. The post-Done markdown render reads the accumulated `Done.response` field from the terminal event — no client-side re-aggregation from individual deltas.
+- **[performance]** Streaming MUST NOT block on the full turn before rendering. `Text` deltas append to the presenter's `text_chunk_buffer` and re-render the response `Static` in place on each delta (live Markdown) — the transcript updates as tokens arrive. The displayed response is built delta-by-delta; `Done.response` is observable but is NOT the source of the rendered output.
 - **[security]** TUI does not log `Authorization` header, `--api-key` value, or full event bodies. Persistence is per-launch (no disk writes); transcript content is in-memory only.
 - **[style]** Async-native. Textual's worker pattern (`self.run_worker(coro, exclusive=True)`) drives the stream loop; no manual thread management. `App[int]` for typed exit codes. ruff line-length=100 (per pyproject).
 
@@ -231,9 +231,14 @@ PROPERTIES:
 BINDINGS:
   - ("ctrl+c", "interrupt", "Cancel / Exit")     # priority=True so Input doesn't consume it; see open_questions
   - ("ctrl+d", "quit", "Exit immediately")
-COMPOSE shape (declarative — implementer chooses CSS file vs inline):
+COMPOSE shape (declarative — implementer chooses CSS file vs inline; exact tab/CSS layout lives in tui.py.compose):
   Header()
-  RichLog(id="transcript", wrap=True, markup=False, highlight=False)   # markup=False: bracketed labels like [cancel_failed] render verbatim instead of being interpreted-and-stripped as Rich style spans. The post-Done markdown render uses Markdown() Renderable which renders regardless of widget-level markup.
+  Horizontal:
+    VerticalScroll(id="transcript-scroll")        # chat content: per-turn Static widgets mounted dynamically by the presenter — prompt echo, live-Markdown response (.response-md), tinted terminal labels, awaiting-token indicator. No single RichLog; wire-error labels mount as error-label Statics here.
+    TabbedContent (right column; Ctrl+1..3 switch tabs):
+      RichLog(id="tools-log", markup=False)        # ToolStart / ToolResult
+      RichLog(id="debug-log", markup=False)         # per-event audit line + WorkerPhase + TextBoundary + turn-summary
+      RichLog(id="thinking-log", markup=False)      # coalesced Thinking deltas, Rule(start)/Rule(end) per run
   Input(id="prompt", placeholder="Type a message and press Enter")
   Static("", id="identity")    # INV-002: visible session-identity strip; rendered by on_mount
   Static(HINT_IDLE, id="hint") # INV-003: visible Ctrl-C state hint; updated on state transitions
@@ -299,39 +304,34 @@ TESTS:
 
 ```contract
 FN RatatoskrApp._stream_turn_worker(self, content: str) -> None
-BRIEF: Worker coroutine spawned by `on_input_submitted`. Drives `stream_turn`, renders each event into the RichLog via a freshly-constructed `TuiPresenterState` instance (issue #12 amendment: was `_render_event_to_log`), captures `active_turn_id` from the first event for the Ctrl-C cancel path, and transitions state back to "idle" after the terminal event (or on a mid-session error).
+BRIEF: Worker coroutine spawned by `on_input_submitted` (exclusive). Queries the four panes, constructs a fresh `TuiPresenterState`, drives `stream_turn`, and renders each event through `presenter.render`. Captures `active_turn_id` + writes the turn headers on the first event (for the Ctrl-C cancel path), breaks on the terminal event, mounts wire-error labels as `error-label` Statics into the transcript scroll, and a `finally` always transitions state back to "idle". v0.9.0: rendering is live (the presenter streams Markdown in place) — there is NO post-Done re-render here.
 PRE: [PRE-001 hard] self.state == "streaming" (set by on_input_submitted before spawn) -- assert self.state == "streaming"
 PRE: [PRE-002 hard] self.client is not None (set in on_mount) -- assert self.client is not None
 PRE: [PRE-003 hard] content is non-empty (caller validated in on_input_submitted) -- assert content
-POST: [POST-001 state_change] after terminal event OR error, self.state == "idle"; self.active_turn_id is None; footer hint reset to "Ctrl-C twice to exit"
-POST: [POST-002 side_effect] each event passed through TuiPresenterState.render exactly once (until terminal OR until cancel-induced abort) (issue #12 amendment: was _render_event_to_log)
-POST: [POST-003 side_effect] for Done events with NOT args.raw: a separator line + the markdown-rendered Done.response appended to RichLog (INV-005)
-POST: [POST-004 state_change] active_turn_id is set to event.sse_id.turn_id on the FIRST yielded event (for cancel_turn use by action_interrupt)
+POST: [POST-001 state_change] the `finally` always transitions to "idle": self.state == "idle"; self.active_turn_id is None; footer hint reset to HINT_IDLE — on terminal event, mid-session wire error, OR cancellation
+POST: [POST-002 side_effect] each event is passed through TuiPresenterState.render exactly once (four panes + the on_persona_snapshot callback threaded), until the terminal event OR a cancel-induced abort
+POST: [POST-003 state_change] on the FIRST yielded event: active_turn_id is set to event.sse_id.turn_id AND _write_turn_headers(active_turn_id) mounts the turn header (active_turn_id is read by action_interrupt for cancel_turn)
+POST: [POST-004 side_effect] no post-Done Markdown re-render — the presenter renders Markdown live during Text streaming (v0.9.0); the worker only breaks on the terminal event after the presenter has mounted the tinted label
 ERROR_ROUTING:
   SseConnectFailed | SseConnectionDropped | MalformedSseId | MalformedSseData | TurnIdFlip:
-    local_handling: append `[<label>] <details>` to RichLog (mirror cli.py's error labels)
-    flow_control: abort (the iteration aborts; finally-block restores state)
-    state_recovery: state → idle; footer hint reset; active_turn_id cleared. (INV-008: mid-session errors do NOT exit the app.)
+    local_handling: audit the failure, then mount `[<label>] <details>` as an `error-label` Static into the transcript scroll (mirrors cli.py's error labels)
+    flow_control: abort (the iteration aborts; the finally-block restores state)
+    state_recovery: finally → state idle; active_turn_id cleared; hint reset. (INV-008: mid-session wire errors do NOT exit the app.)
   asyncio.CancelledError (from action_interrupt force-exit OR Worker.cancel()):
     local_handling: none — propagate to let Textual's worker manager clean up
     flow_control: abort
-    state_recovery: state → idle; active_turn_id cleared. (cancel_task was already spawned by action_interrupt.)
+    state_recovery: finally → state idle; active_turn_id cleared; hint reset. (cancel_task was already spawned by action_interrupt.)
 STEPS:
   1. [setup, flexibility=prescriptive] Validate inputs per PRE-001..PRE-003
-  2. [loop, flexibility=prescriptive] TRY: async for event in stream_turn(self.client, self.session_id, content):
-       IF self.active_turn_id is None: SET self.active_turn_id = event.sse_id.turn_id  # POST-004
-       presenter.render(event, log=self.query_one("#transcript", RichLog), thinking_widget=self.query_one("#thinking-current", Static), raw=self.args.raw)  # issue #12: state-based rendering
-       IF isinstance(event, Done):
-         IF NOT self.args.raw:
-           Append a horizontal-rule separator to RichLog
-           Render Markdown(event.response) into RichLog  # INV-005 post-Done markdown render
-         BREAK (terminal; iteration done)
-       IF isinstance(event, (Error, Cancelled)):
-         BREAK (terminal)
-     CATCH SseConnectFailed | SseConnectionDropped | MalformedSseId | TurnIdFlip as exc:
-       Append `[<label>] <details>` to RichLog per cli.py's error-label format
-  3. [cleanup, flexibility=prescriptive] FINALLY:
-       SET self.state = "idle"; self.active_turn_id = None; reset footer hint to "Ctrl-C twice to exit"
+  2. [setup, flexibility=prescriptive] Query the four panes — transcript=#transcript-scroll (VerticalScroll), tools_log=#tools-log, debug_log=#debug-log, thinking_log=#thinking-log — and construct presenter = TuiPresenterState()
+  3. [loop, flexibility=prescriptive] TRY: async for event in stream_turn(self.client, self.session_id, content):
+       IF self.active_turn_id is None: SET self.active_turn_id = event.sse_id.turn_id; CALL self._write_turn_headers(self.active_turn_id)   # POST-003
+       CALL presenter.render(event, transcript=transcript, tools_log=tools_log, debug_log=debug_log, thinking_log=thinking_log, raw=self.args.raw, on_persona_snapshot=self._update_persona_surfaces)   # POST-002
+       IF isinstance(event, (Done, Error, Cancelled)): BREAK   # terminal; presenter already rendered the live Markdown + tinted label (POST-004 — no re-render)
+     CATCH SseConnectFailed | SseConnectionDropped | MalformedSseId | MalformedSseData | TurnIdFlip as exc:
+       AUDIT the failure; mount `[<label>] <details>` as an error-label Static into transcript
+  4. [cleanup, flexibility=prescriptive] FINALLY:
+       CALL self._transition("idle", "worker_finally"); SET self.active_turn_id = None; CALL self._set_hint(self.HINT_IDLE)
 TESTS:
   happy_text_done_renders_markdown [happy,tracer]: mock yields text("hello") + done(response="hello"); after Pilot.pause(), RichLog contains "hello" (the streamed delta) AND below it a separator + the markdown render of "hello"; state → idle
   raw_flag_skips_markdown_render [trace]: --raw; mock yields text + done; RichLog has the streamed delta but NO separator + markdown re-render
@@ -345,40 +345,84 @@ TESTS:
 ```
 
 ```contract
-CLASS TuiPresenterState                                              # issue #12 amendment
-BRIEF: Stateful per-turn presenter for TUI mode. Replaces the stateless `_render_event_to_log` (removed). Owns `thinking_buffer`, `thinking_open`; coalesces thinking-event deltas into per-delta live updates on the dedicated `Static(id="thinking-current")` widget AND one closed RichLog entry per run (two-views-of-thinking decoupling); demotes telemetry events with a `· ` dim prefix on RichLog; Done renders a load-bearing label + Markdown (when not raw); render exceptions degrade to a plain-labeled fallback + `[render_error] <type>` line (NO exception message per INV-009 security).
+CLASS TuiPresenterState                                              # issue #12 amendment; refreshed to the four-pane live-Markdown model (v0.5.0–v0.14.0 + Worldtree #201/#204)
+BRIEF: Stateful per-turn presenter for TUI mode. Replaces the stateless `_render_event_to_log` (removed). Routes each event across four panes (transcript / tools_log / debug_log / thinking_log): Thinking deltas coalesce by `\n` into `thinking_log` wrapped in Rule(start)/Rule(end) per run; Text deltas accumulate in `text_chunk_buffer` and render live as `Markdown(buffer)` into a single in-place-updated response `Static` (no post-Done re-render); demoted telemetry gets a `· ` dim prefix (WorkerPhase/TextBoundary → debug_log, Tool* → tools_log); terminal events mount a tinted label + write a turn-summary to debug_log; AffectUpdate fires the persona callback; AwaitingLlmFirstToken mounts/updates a heartbeat indicator; render exceptions degrade to a plain-labeled fallback + `[render_error] <type>` line (NO exception message per INV-009 security).
 PROPERTIES:
-  thinking_buffer: list[str]
   thinking_open: bool
+  thinking_run_index: int
+  thinking_chunk_buffer: str
+  text_chunk_buffer: str
+  current_response_widget: object        # the live response Static; None between turns
+  text_delta_count: int
+  text_byte_count: int
+  thinking_delta_count: int
+  thinking_byte_count: int
+  turn_start_ts: float
+  awaiting_widget: object                # the awaiting-token indicator Static; None when closed
+  heartbeat_count: int
 INV-WIRE-001: One instance per `_stream_turn_worker` invocation (issue #12 INV-008).
-INV-WIRE-002: Two-views-of-thinking decoupling (issue #12 INV-004): per-delta updates → thinking-current Static; closed run → RichLog entry.
+INV-WIRE-002: Thinking is single-view (v0.7.1+): deltas coalesce by `\n` into `thinking_log` (RichLog), each run wrapped in Rule(start)/Rule(end). The issue #12 two-views `#thinking-current` Static was removed.
 ```
 
 ```contract
-FN TuiPresenterState.render(self, event: Event, *, log: RichLog, thinking_widget: Static, raw: bool) -> None   # issue #12 amendment
-BRIEF: Render one event into the TUI with editorial hierarchy + coalescing per issue #12 INV-001..INV-007 + render-exception fallback per INV-009. Unicode allowed in TUI output (e.g., `· ` U+00B7 prefix, `→` U+2192 arrow in usage). Decoupling: thinking deltas go to `thinking_widget` per-delta; one closed RichLog entry per thinking-run.
-PRE: [PRE-001 hard] event is an instance of one of the Event union variants
-POST: [POST-001 side_effect] for Thinking: open run (display=True, thinking_open=True) on first delta; append to buffer; update widget with last ~200 chars (… prefix when truncated)
-POST: [POST-002 side_effect] for non-Thinking when thinking_open: write ONE RichLog entry `· thinking: <full>`; clear buffer; thinking_open=False; widget cleared + display=False; THEN render the new event
-POST: [POST-003 side_effect] for Text: write content to RichLog (no prefix, no demotion)
-POST: [POST-004 side_effect] for Done: write `[done] turn_id=... model=... duration={autoscale} usage={p} in → {c} out ({t} total, {ci} cached)`; if NOT raw, append Rule() + Markdown(event.response) per issue #4 INV-005
-POST: [POST-005 side_effect] for Error/Cancelled: write the load-bearing label (no demotion); ensure widget cleared+hidden
-POST: [POST-006 side_effect] for demoted telemetry (WorkerPhase, TextBoundary, ToolStart, ToolResult): write `· <label>: <fields>` to RichLog
-POST: [POST-007 exception] never propagates; on internal exception, write the plain labeled fallback + `[render_error] <ExceptionClassName>` (NO exception message — INV-009 security clause)
+FN TuiPresenterState.render(self, event: Event, *, transcript: VerticalScroll, tools_log: RichLog, debug_log: RichLog, thinking_log: RichLog, raw: bool, on_persona_snapshot: object = None) -> None   # issue #12 amendment; refreshed to the four-pane model (v0.5.0–v0.14.0 + Worldtree #201/#204)
+BRIEF: Render one Worldtree SSE event into the four-pane TUI with editorial hierarchy, thinking/text coalescing, live Markdown, persona + heartbeat surfaces, and an INV-009 render-exception fallback. Unicode allowed (`·` U+00B7 demotion prefix, `→` U+2192 usage arrow). Pane routing — `transcript` (VerticalScroll) = chat content (live-Markdown response Static, tinted terminal labels, awaiting-token indicator); `thinking_log` (RichLog) = coalesced Thinking deltas wrapped in Rule(start)/Rule(end); `tools_log` (RichLog) = ToolStart + ToolResult; `debug_log` (RichLog) = per-event audit line + WorkerPhase + TextBoundary + turn-summary. Optional `on_persona_snapshot` callback fires when AffectUpdate carries a snapshot (issue #13 / Worldtree #204). Supersedes the issue #12 single-`log`/`thinking_widget` model and the post-Done Markdown re-render (both removed at v0.5.0/v0.9.0).
+PRE: [PRE-001 hard] event is an instance of one of the Event union variants -- assert isinstance(event, (WorkerPhase, Thinking, Text, TextBoundary, ToolStart, ToolResult, Done, Error, Cancelled, AffectUpdate, AwaitingLlmFirstToken))
+POST: [POST-001 side_effect] audit bookkeeping (v0.10.0): Text increments text_delta_count/text_byte_count, Thinking increments thinking_delta_count/thinking_byte_count (each sets turn_start_ts on its first delta) — neither emits a per-delta audit line (token-rate spam control); every other event sets turn_start_ts if unset AND writes one dimmed `_audit_line(event)` to debug_log
+POST: [POST-002 side_effect] for AffectUpdate (Worldtree #204): audit line per POST-001, then IF snapshot is not None AND on_persona_snapshot is provided, invoke on_persona_snapshot(snapshot) with callback exceptions swallowed (persona surface failure must not break the stream); RETURN
+POST: [POST-003 side_effect] for AwaitingLlmFirstToken (Worldtree #201): heartbeat_count++; first heartbeat mounts a dimmed "awaiting first token · {s:.1f}s" Static into transcript, subsequent heartbeats update it in place; widget-op exceptions swallowed; scroll_end; RETURN
+POST: [POST-004 side_effect] gap-close: any non-heartbeat event past the heartbeat branch removes the awaiting indicator if still mounted (awaiting_widget → None)
+POST: [POST-005 side_effect] for Thinking: open the run on first delta (thinking_run_index++, write Rule("turn {turn_id} · thinking #{idx} start") to thinking_log, thinking_open=True); accumulate content into thinking_chunk_buffer; flush each complete `\n`-terminated line to thinking_log (skip blank lines), retain the tail; RETURN
+POST: [POST-006 side_effect] for non-Thinking when thinking_open: flush the buffered tail to thinking_log, write Rule("turn {turn_id} · thinking #{idx} end"), thinking_open=False; THEN render the new event
+POST: [POST-007 side_effect] for Text: append content to text_chunk_buffer; render `text_chunk_buffer if raw else Markdown(text_chunk_buffer)` — first Text delta mounts a `.response-md` Static into transcript, subsequent deltas update it in place (live Markdown, no post-Done re-render); scroll_end; RETURN
+POST: [POST-008 side_effect] for Done/Error/Cancelled: write a dimmed turn-summary (turn_id, text_deltas/bytes, thinking_deltas/bytes, heartbeats, elapsed_ms) to debug_log; clear text_chunk_buffer + current_response_widget; mount a tinted terminal-label Static into transcript — Done = success-tinted `[done] turn_id=... model=... duration={_format_duration_ms} usage {_format_usage(arrow='→')}`, Error = error-tinted `[error] turn_id=... code=... message=...!r`, Cancelled = warning-tinted `[cancelled] turn_id=... reason=...!r partial_message_id=...`; scroll_end; RETURN
+POST: [POST-009 side_effect] for demoted telemetry: WorkerPhase + TextBoundary → dimmed `· <label>: <fields>` to debug_log; ToolStart + ToolResult → dimmed `· <label>: <fields>` to tools_log (ToolResult result truncated to 200 chars) per issue #13 INV-014; RETURN
+POST: [POST-010 exception] never propagates; on any internal exception, write `_plain_label(event)` + `[render_error] <ExceptionClassName>` (NO exception message — INV-009 security clause) to the event's pane (tools_log for Tool*; thinking_log for Thinking; debug_log for WorkerPhase/TextBoundary; else mount Statics into transcript)
+ERROR_ROUTING:
+  Exception (any internal render failure — widget op, formatting, persona callback):
+    local_handling: write `_plain_label(event)` + `[render_error] {type(exc).__name__}` (no message — INV-009 security clause) to the event's pane (tools_log for Tool*; thinking_log for Thinking; debug_log for WorkerPhase/TextBoundary; else mount Statics into transcript)
+    flow_control: skip (swallow — render never propagates)
+    state_recovery: none (the next event renders against fresh state)
+STEPS:
+  1. [setup, flexibility=prescriptive] Validate event ∈ Event union per PRE-001.
+  2. [setup, flexibility=prescriptive] Enter the render try-block — steps 3..11 run inside it; step 12 is the INV-009 fallback.
+  3. [branch, flexibility=prescriptive] Audit bookkeeping (POST-001):
+       IF Text: set turn_start_ts on first delta; text_delta_count++; text_byte_count += len(content)
+       ELIF Thinking: set turn_start_ts on first delta; thinking_delta_count++; thinking_byte_count += len(content)
+       ELSE: set turn_start_ts if unset; WRITE _dim(_audit_line(event)) to debug_log
+  4. [branch, flexibility=prescriptive] IF AffectUpdate (POST-002): IF snapshot is not None AND on_persona_snapshot is not None: TRY on_persona_snapshot(snapshot) / swallow Exception; RETURN
+  5. [branch, flexibility=prescriptive] IF AwaitingLlmFirstToken (POST-003): heartbeat_count++; secs = elapsed_ms_since_building_prompt / 1000; mount-or-update a dimmed "awaiting first token · {secs:.1f}s" Static in transcript (swallow widget Exception); scroll_end; RETURN
+  6. [branch, flexibility=prescriptive] Gap-close (POST-004): IF awaiting_widget is not None: remove it (swallow Exception); SET awaiting_widget=None
+  7. [branch, flexibility=prescriptive] IF Thinking (POST-005): IF NOT thinking_open: thinking_run_index++; WRITE Rule(start) to thinking_log; thinking_open=True. APPEND content to thinking_chunk_buffer; WHILE "\n" in buffer: partition on "\n", WRITE non-empty line to thinking_log, keep the remainder. RETURN
+  8. [branch, flexibility=prescriptive] Close open thinking run (POST-006): IF thinking_open: IF buffer non-empty: WRITE buffer tail to thinking_log, clear buffer. WRITE Rule(end) to thinking_log; thinking_open=False
+  9. [branch, flexibility=prescriptive] IF Text (POST-007): APPEND content to text_chunk_buffer; rendered = buffer if raw else Markdown(buffer); IF current_response_widget is None: mount Static(rendered, classes="response-md") in transcript; ELSE: current_response_widget.update(rendered); scroll_end; RETURN
+  10. [branch, flexibility=prescriptive] IF Done|Error|Cancelled (POST-008): elapsed_ms = int((monotonic()-turn_start_ts)*1000) if turn_start_ts else 0; WRITE dimmed turn-summary to debug_log; clear text_chunk_buffer + current_response_widget; mount the tinted terminal-label Static (Done=success / Error=error / Cancelled=warning) in transcript with the documented label text; scroll_end; RETURN
+  11. [branch, flexibility=prescriptive] Demoted telemetry (POST-009), then RETURN: WorkerPhase → debug_log `· worker_phase: ...`; ToolStart → tools_log `· tool_start: ...`; ToolResult → tools_log `· tool_result: ... result={result!r:.200}`; TextBoundary → debug_log `· text_boundary: ...`
+  12. [error_handler, flexibility=prescriptive] EXCEPT Exception as exc (POST-010 / INV-009): WRITE _plain_label(event) + "[render_error] {type(exc).__name__}" (no message) to the event's pane per ERROR_ROUTING
 TESTS:
-  thinking_coalesce_single_widget_update [happy,tracer]: 3 Thinking events → widget.update called 3× with cumulative content; RichLog has 0 thinking entries yet
-  thinking_closes_one_richlog_entry [happy]: 2× Thinking + WorkerPhase → ONE closed thinking entry + worker_phase entry; widget cleared+hidden
-  thinking_widget_truncation [trace]: 500-char buffer → widget shows "…" + last 200
-  thinking_widget_visibility_lifecycle [trace]: hidden initially; visible during run; hidden after closing event
-  multiple_thinking_runs_each_get_richlog_entry [scenario]: Thinking → Text → Thinking → Done → TWO closed thinking entries
-  cancelled_mid_thinking_closes [scenario]: Thinking → Cancelled → ONE closed thinking entry + [cancelled]; widget hidden
-  done_renders_markdown_after_label [happy]: Text + Done(response=...) with NOT raw → [done] line, Rule, Markdown
-  raw_flag_skips_markdown [trace]: raw=True → no Rule, no Markdown
-  worker_phase_demoted [trace]: "· worker_phase:" prefix (not "[worker_phase]")
-  tool_start_demoted [trace]: "· tool_start:" prefix
-  text_no_prefix [trace]: Text → no demotion prefix
-  render_exception_fallback [adversarial]: widget.update raises → fallback line + `[render_error] <ClassName>` (NO message); state does not propagate
-  state_reset_per_worker [trace]: fresh TuiPresenterState() starts with no thinking open
+  text_then_done_mounts_widget_and_finalizes [happy,tracer]: Text + Done (NOT raw) → live Markdown `.response-md` widget mounted; on Done the widget ref clears + a success-tinted [done] label mounts; no post-Done re-render (no double-print)
+  thinking_coalesces_until_newline [happy]: Thinking deltas buffer; only complete `\n`-terminated lines flush to thinking_log
+  thinking_flushes_on_newline [happy]: a Thinking delta containing `\n` flushes the completed line and retains the tail for the next delta
+  thinking_closes_to_thinking_log [happy]: 2× Thinking + WorkerPhase → tail flushed + Rule(end) closes the run in thinking_log; thinking_open=False
+  multiple_thinking_runs_each_get_thinking_log_section [scenario]: Thinking → Text → Thinking → Done → TWO Rule-wrapped thinking sections
+  cancelled_mid_thinking_closes [scenario]: Thinking → Cancelled → run closes with Rule(end); warning-tinted [cancelled] label mounted
+  text_first_delta_mounts_response_widget [happy]: first Text delta mounts a `.response-md` Static in transcript holding Markdown(buffer)
+  text_subsequent_deltas_update_in_place [trace]: later Text deltas update the same widget (live Markdown), no new mount
+  raw_flag_skips_markdown [trace]: raw=True → response widget holds plain str, no Markdown wrapping
+  worker_phase_demoted_to_debug_log [trace]: WorkerPhase → dimmed `· worker_phase:` in debug_log, not transcript
+  tool_start_routes_to_tools_log [trace]: ToolStart → `· tool_start:` in tools_log (issue #13 INV-014)
+  tool_result_routes_to_tools_log [trace]: ToolResult → `· tool_result: ... result=<≤200 chars>` in tools_log
+  worker_phase_emits_audit_line [trace]: a non-Text/Thinking event writes one dimmed `_audit_line` to debug_log
+  tool_start_emits_audit_line [trace]: ToolStart writes an audit line to debug_log in addition to the tools_log routing
+  text_delta_counted_not_per_event_audit_line [trace]: Text deltas increment counters but emit NO per-delta audit line (token-rate spam control)
+  done_emits_turn_summary_line [trace]: Done writes a dimmed turn-summary (text/thinking delta+byte counts, heartbeats, elapsed_ms) to debug_log before clearing counters
+  affect_update_routes_to_audit_only [scenario]: AffectUpdate(snapshot) → audit line + on_persona_snapshot(snapshot) callback; no transcript mount
+  affect_update_scheduled_has_no_pad_detail [trace]: AffectUpdate(status="scheduled", snapshot=None) → audit line only; callback skipped
+  awaiting_llm_first_token_mounts_indicator [scenario]: first AwaitingLlmFirstToken mounts a dimmed "awaiting first token · {s}s" Static in transcript
+  awaiting_subsequent_heartbeats_update_in_place [trace]: later heartbeats update the same indicator in place; heartbeat_count grows
+  awaiting_indicator_removed_when_gap_closes [scenario]: the first non-heartbeat event removes the awaiting indicator (gap closed)
+  render_exception_fallback [adversarial]: an internal render failure writes `_plain_label` + `[render_error] <ClassName>` (NO message) to the event's pane; never propagates (INV-009)
+  state_reset_per_worker [trace]: a fresh TuiPresenterState() starts with thinking_open=False and zeroed counters
   duration_format_seconds [trace]: Done(duration_ms=5467) → "duration=5.5s"
   usage_format_unicode_arrow [trace]: Done → "usage ... in → ... out (...)" (Unicode arrow, not ASCII)
 ```
@@ -408,7 +452,7 @@ STEPS:
          RETURN
        SET self.state = "cancelling"
        update footer hint to "Press Ctrl-C again to exit"
-       self.run_worker(_cancel_via_sse(self.client, self.session_id, self.active_turn_id, log=self.query_one("#transcript", RichLog)))
+       self.run_worker(_cancel_via_sse(self.client, self.session_id, self.active_turn_id, transcript=self.query_one("#transcript-scroll", VerticalScroll), audit=self._audit))
      ELIF self.state == "cancelling":
        # Second Ctrl-C — force exit, abandon drain
        IF self.stream_worker is not None: self.stream_worker.cancel()

graphify-out/GRAPH_REPORT.md

@@ -1,15 +1,16 @@
-# Graph Report - .  (2026-06-10)
+# Graph Report - ratatoskr  (2026-06-15)
 
 ## Corpus Check
-- cluster-only mode — file stats not available
+- 61 files · ~157,407 words
+- Verdict: corpus is large enough that graph structure adds value.
 
 ## Summary
-- 1974 nodes · 4551 edges · 132 communities (128 shown, 4 thin omitted)
-- Extraction: 66% EXTRACTED · 34% INFERRED · 0% AMBIGUOUS · INFERRED: 1560 edges (avg confidence: 0.51)
+- 2045 nodes · 4675 edges · 152 communities (124 shown, 28 thin omitted)
+- Extraction: 66% EXTRACTED · 34% INFERRED · 0% AMBIGUOUS · INFERRED: 1582 edges (avg confidence: 0.52)
 - Token cost: 0 input · 0 output
 
 ## Graph Freshness
-- Built from commit: `5b9a3f4c`
+- Built from commit: `335c8358`
 - Run `git rev-parse HEAD` and compare to check if the graph is stale.
 - Run `graphify update .` after code changes (no API cost).
 
@@ -144,6 +145,26 @@
 - [[_COMMUNITY_No Worldtree Imports Test|No Worldtree Imports Test]]
 - [[_COMMUNITY_Ratatoskr Worldtree API TUI|Ratatoskr Worldtree API TUI]]
 - [[_COMMUNITY_Ratatoskr Web Browser Debug Companion|Ratatoskr Web Browser Debug Companion]]
+- [[_COMMUNITY_Community 132|Community 132]]
+- [[_COMMUNITY_Community 133|Community 133]]
+- [[_COMMUNITY_Community 134|Community 134]]
+- [[_COMMUNITY_Community 135|Community 135]]
+- [[_COMMUNITY_Community 136|Community 136]]
+- [[_COMMUNITY_Community 137|Community 137]]
+- [[_COMMUNITY_Community 138|Community 138]]
+- [[_COMMUNITY_Community 139|Community 139]]
+- [[_COMMUNITY_Community 140|Community 140]]
+- [[_COMMUNITY_Community 141|Community 141]]
+- [[_COMMUNITY_Community 142|Community 142]]
+- [[_COMMUNITY_Community 143|Community 143]]
+- [[_COMMUNITY_Community 144|Community 144]]
+- [[_COMMUNITY_Community 145|Community 145]]
+- [[_COMMUNITY_Community 146|Community 146]]
+- [[_COMMUNITY_Community 147|Community 147]]
+- [[_COMMUNITY_Community 148|Community 148]]
+- [[_COMMUNITY_Community 149|Community 149]]
+- [[_COMMUNITY_Community 150|Community 150]]
+- [[_COMMUNITY_Community 151|Community 151]]
 
 ## God Nodes (most connected - your core abstractions)
 1. `TuiPresenterState` - 84 edges
@@ -158,89 +179,89 @@
 10. `ToolStart` - 67 edges
 
 ## Surprising Connections (you probably didn't know these)
-- `_GatedStream` --uses--> `UsageError`  [INFERRED]
-  tests/test_cli.py → src/ratatoskr/cli.py
-- `CaptureFixture` --uses--> `UsageError`  [INFERRED]
-  tests/test_cli.py → src/ratatoskr/cli.py
-- `Event` --uses--> `UsageError`  [INFERRED]
-  tests/test_cli.py → src/ratatoskr/cli.py
-- `MonkeyPatch` --uses--> `UsageError`  [INFERRED]
-  tests/test_cli.py → src/ratatoskr/cli.py
-- `TestAmain` --uses--> `UsageError`  [INFERRED]
-  tests/test_cli.py → src/ratatoskr/cli.py
+- `test_build_app_from_env_builds_app_with_routes()` --calls--> `build_app_from_env()`  [INFERRED]
+  tests/test_provider_serve.py → src/ratatoskr/provider/serve.py
+- `test_build_app_from_env_requires_heimdall_key()` --calls--> `build_app_from_env()`  [INFERRED]
+  tests/test_provider_serve.py → src/ratatoskr/provider/serve.py
+- `test_get_absent_returns_none()` --calls--> `open_affect_store()`  [INFERRED]
+  tests/test_provider_affect.py → src/ratatoskr/provider/affect_store.py
+- `test_open_advertises_capability_and_schema()` --calls--> `open_affect_store()`  [INFERRED]
+  tests/test_provider_affect.py → src/ratatoskr/provider/affect_store.py
+- `test_reopen_existing_file_is_idempotent()` --calls--> `open_affect_store()`  [INFERRED]
+  tests/test_provider_affect.py → src/ratatoskr/provider/affect_store.py
 
 ## Import Cycles
 - None detected.
 
-## Communities (132 total, 4 thin omitted)
+## Communities (152 total, 28 thin omitted)
 
 ### Community 0 - "TuiPresenterState Management"
 Cohesion: 0.05
-Nodes (39): Per-turn presenter state for TUI mode (issue #12).      See `docs/contracts/issu, TuiPresenterState, _make_tui_done(), _mounted_renderables(), current_invokes_callback_with_snapshot: AffectUpdate(current, snapshot), scheduled_does_not_invoke_callback: status=scheduled has no snapshot,         so, callback_exception_swallowed: a raising callback does NOT crash the         pres, Tests for the new TuiPresenterState — per issue #12 contract. (+31 more)
+Nodes (40): Per-turn presenter state for TUI mode (issue #12).      See `docs/contracts/issu, TuiPresenterState, _make_tui_done(), _mounted_renderables(), current_invokes_callback_with_snapshot: AffectUpdate(current, snapshot), scheduled_does_not_invoke_callback: status=scheduled has no snapshot,         so, callback_exception_swallowed: a raising callback does NOT crash the         pres, done_label_styled_success [v0.9.0]: [done] label mounts as Static         carryi (+32 more)
 
 ### Community 1 - "EventSource SSE Consumer"
-Cohesion: 0.06
-Nodes (49): EventSource, AffectUpdate, AwaitingLlmFirstToken, cancel_turn(), CancelResult, InvalidLastEventId, _iter_events(), SSE consumer for the Worldtree Conversation API.  Implements docs/contracts/issu (+41 more)
+Cohesion: 0.08
+Nodes (14): Sync entry point — delegates to the async resolve-then-run flow.      Per issue, run_tui(), happy_new_session_resolve [happy]: --new path through _resolve_then_run., happy_new_with_end_user_id_resolve [happy]: args.end_user_id threads into POST b, user_agent_header_sent [trace]: outbound requests carry the ratatoskr User-Agent, alt_screen_never_opens_on_resolve_error [trace]: 404 → run_tui=12; run_async unh, session_api_failed_on_resolve [error]: --new + 500 → [session_api_failed] stderr, network_error_on_resolve [error]: --new + ConnectError → [network_error] stderr. (+6 more)
 
 ### Community 2 - "Parsed CLI Arguments Handling"
 Cohesion: 0.14
-Nodes (53): ParsedArgs, Raised on argument violations; mapped to exit code 10 by main()., Resolved CLI invocation. Post-validation: exactly one of session_id / new is set, UsageError, AgentInfo, Worldtree agent envelope from GET /agents (issue #8).      INV-005: required fie, Cancelled, Done (+45 more)
+Nodes (73): NamedTuple, ParsedArgs, Resolved CLI invocation. Post-validation: exactly one of session_id / new is set, AgentInfo, Worldtree agent envelope from GET /agents (issue #8).      INV-005: required fie, AffectUpdate, AwaitingLlmFirstToken, Cancelled (+65 more)
 
 ### Community 3 - "Agent Information Management"
-Cohesion: 0.19
-Nodes (55): AgentInfo, ComposeResult, Exception, FileResponse, JSONResponse, _ArgparseError, _AuthError, Raised when no API key is resolvable; mapped to exit code 11 by main(). (+47 more)
+Cohesion: 0.08
+Nodes (86): AgentInfo, ComposeResult, EventSource, Exception, FileResponse, _ArgparseError, _AuthError, Raised when no API key is resolvable; mapped to exit code 11 by main(). (+78 more)
 
 ### Community 4 - "TUI Tests and Contract Verification"
-Cohesion: 0.08
-Nodes (36): _args_existing(), _noop_worker(), MonkeyPatch, Tests for ratatoskr.tui per docs/contracts/issues/4.contract.md., Fake _stream_turn_worker that never completes (lets state stay 'streaming')., happy_submit_echoes_and_spawns [happy,tracer]: …, empty_submit_no_op [trace]: '' + Enter → no change; no worker spawned., submit_during_streaming_shows_busy_notice [adversarial]: … (+28 more)
+Cohesion: 0.13
+Nodes (17): _args_existing(), Type content into the input and submit; wait for worker to finish., happy_text_done_no_double_print [happy,tracer, v0.9.0]:         Text("hello") mo, raw_flag_skips_markdown_render [trace, v0.9.0]:         With --raw, the response, error_terminal_returns_to_idle [happy]: …, cancelled_terminal_returns_to_idle [happy]: …, active_turn_id_set_on_first_event [trace]: …, connection_dropped_returns_to_idle [error]: … (+9 more)
 
 ### Community 5 - "CLI Arguments Parsing Contract"
-Cohesion: 0.06
-Nodes (26): _parse_args(), argparse + env-fallback + xor-validation per the contract., happy_existing_session: --send --session --api-key → ParsedArgs with session_id., api_key_from_env: WORLDTREE_API_KEY env var fills in when --api-key omitted., api_key_flag_beats_env: explicit --api-key wins over WORLDTREE_API_KEY., server_default: no --server, no WORLDTREE_API_URL → http://localhost:8000., server_env_fallback: WORLDTREE_API_URL fills in when --server omitted., server_flag_beats_env: explicit --server wins over WORLDTREE_API_URL. (+18 more)
+Cohesion: 0.04
+Nodes (26): main(), _parse_args(), argparse + env-fallback + xor-validation per the contract., Sync entry point. Maps UsageError/_AuthError to exit codes BEFORE the event loop, happy_existing_session: --send --session --api-key → ParsedArgs with session_id., api_key_from_env: WORLDTREE_API_KEY env var fills in when --api-key omitted., server_default: no --server, no WORLDTREE_API_URL → http://localhost:8000., server_env_fallback: WORLDTREE_API_URL fills in when --server omitted. (+18 more)
 
 ### Community 6 - "Sync Entry Point and Session Resolution"
-Cohesion: 0.07
-Nodes (28): Sync entry point — delegates to the async resolve-then-run flow.      Per issue, run_tui(), _args_new_no_agent(), CaptureFixture, Tests at the `_resolve_then_run` layer — pre-`App.run()` session     resolution, happy_new_session_resolve [happy]: --new path through _resolve_then_run., happy_new_with_end_user_id_resolve [happy]: args.end_user_id threads into POST b, user_agent_header_sent [trace]: outbound requests carry the ratatoskr User-Agent (+20 more)
+Cohesion: 0.17
+Nodes (7): POST a message and yield typed Events. See contract FN stream_turn., stream_turn(), session_not_found: 404 -> SseConnectFailed(status=404)., malformed_id_no_seq: id `42` (missing :seq) -> MalformedSseId; no event yielded., malformed_id_alpha: id `foo:bar` -> MalformedSseId., INV-001: empty stream (no events at all) -> SseConnectionDropped(None)., ERROR_ROUTING: SseConnectFailed.body is truncated to <= 1024 bytes.
 
 ### Community 7 - "Stream Turn Rendering and Cancellation"
-Cohesion: 0.10
-Nodes (25): Drive stream_turn, render events, race against sigint_event for mid-stream cance, _run_turn(), _GatedStream, Event, no_busy_loop_after_cancel [trace]: only one sigint_event.wait()-task created., cancel_failed_drains_anyway [scenario]: …, render_called_once_per_event [trace]: spy on render; call_count == event count., sigint_handler_installed_and_removed [trace]: signal handler add/remove paired. (+17 more)
+Cohesion: 0.05
+Nodes (53): _amain(), Drive stream_turn, render events, race against sigint_event for mid-stream cance, Async orchestrator: create-session (if --new) → SIGINT install → _run_turn → cle, Raised on argument violations; mapped to exit code 10 by main()., _run_turn(), UsageError, SSE event `text_boundary`: speakable breakpoint after a `text` event., TextBoundary (+45 more)
 
 ### Community 8 - "Worldtree Session Client"
-Cohesion: 0.06
-Nodes (26): InvalidCursor, list_sessions(), Worldtree Conversation API session-lifecycle client.  Implements docs/contracts/, GET /sessions. See contract FN list_sessions., Worldtree session envelope; shared shape for create + list responses.      INV-0, One page of GET /sessions results. `next_cursor=None` on the last page., Raised on HTTP 422 cursor_invalid from GET /sessions., SessionInfo (+18 more)
+Cohesion: 0.04
+Nodes (47): AgentNotAvailable, AuthScopeDenied, get_persona_state(), InvalidCursor, list_sessions(), PersonaNotConfigured, Worldtree Conversation API session-lifecycle client.  Implements docs/contracts/, Raised on HTTP 404 `agent_not_available` from GET persona_state.      The agent_ (+39 more)
 
 ### Community 9 - "Tier 3 Agent Lifecycle Client"
-Cohesion: 0.07
-Nodes (32): _build_parser(), define_agent(), _extract_error_code(), _extract_error_field(), main(), _parse_tier3_agent_info(), patch_agent(), Worldtree Tier 3 (consumer-defined) agent lifecycle client.  Implements docs/con (+24 more)
+Cohesion: 0.08
+Nodes (19): _args_new(), Construct RatatoskrApp with pre-resolved state (issue #6 lifecycle).      Produc, happy_new_session_mount [happy,tracer]: identity populated from pre-resolved sta, footer_identity_visible_first_frame [trace]: identity widget rendered first fram, main_row_is_horizontal [tracer]: compose() yields Horizontal#main-row., left_column_content_only [v0.9.0]: left column = transcript-scroll         Verti, right_column_has_tabbed_content_with_tools_tab: #side-panes + TabPane#tools-tab., tools_log_inside_tools_tab: tools-transcript RichLog is a descendant of tools-ta (+11 more)
 
 ### Community 10 - "CLI Presenter State Management"
-Cohesion: 0.09
-Nodes (23): CliPresenterState, Per-turn presenter state for `--send` mode (issue #12).      See `docs/contracts, SSE event `text_boundary`: speakable breakpoint after a `text` event., TextBoundary, _make_done(), Tests for the new CliPresenterState — per issue #12 contract., thinking_coalesce_single_run [happy,tracer]:         Thinking("hello") + Thinkin, thinking_closes_on_first_non_thinking_event [happy]:         Thinking → WorkerPh (+15 more)
+Cohesion: 0.11
+Nodes (36): Any, Connection, build_affect_provider_app(), _ctx_actor(), open_affect_store(), RatatoskrAffectStore, SQLite-backed, conduit-opaque affect store (Bifrost affect plane, v1).  Contract, Read-back of the stored snapshot (tests / future rehydrate-seed). (+28 more)
 
 ### Community 11 - "Ratatoskr Application Argument Handling"
-Cohesion: 0.09
-Nodes (23): _args_new(), Construct RatatoskrApp with pre-resolved state (issue #6 lifecycle).      Produc, happy_new_session_mount [happy,tracer]: identity populated from pre-resolved sta, happy_existing_session_mount: identity shows <unknown> when agent_id is None., footer_identity_visible_first_frame [trace]: identity widget rendered first fram, INV-013 + INV-014 + INV-017: Horizontal two-column layout with Tools tab., main_row_is_horizontal [tracer]: compose() yields Horizontal#main-row., left_column_content_only [v0.9.0]: left column = transcript-scroll         Verti (+15 more)
+Cohesion: 0.07
+Nodes (26): CliPresenterState, _format_duration_ms(), Auto-scale duration formatting per issue #12 INV-006. Locale-blind., Per-turn presenter state for `--send` mode (issue #12).      See `docs/contracts, Render one Worldtree SSE event with editorial hierarchy + coalescing., _make_done(), Tests for the new CliPresenterState — per issue #12 contract., thinking_coalesce_single_run [happy,tracer]:         Thinking("hello") + Thinkin (+18 more)
 
 ### Community 12 - "Stream Turn Event Processing"
-Cohesion: 0.07
-Nodes (21): POST a message and yield typed Events. See contract FN stream_turn., stream_turn(), heartbeat_sequence_monotonic [scenario]: three consecutive heartbeats         in, happy_one_text_done: text then done; same turn_id; iter ends after done., full_event_vocab: one of each variant; all carry parsed sse_id., error_terminal: text then error; iteration ends; error_code populated., cancelled_terminal: cancelled with phase=cancelled, turn_id; iteration ends., session_not_found: 404 -> SseConnectFailed(status=404). (+13 more)
+Cohesion: 0.14
+Nodes (8): happy_one_text_done: text then done; same turn_id; iter ends after done., error_terminal: text then error; iteration ends; error_code populated., connection_drop: RemoteProtocolError after one text -> SseConnectionDropped((42,, no_text_aggregation: consumer yields each text event separately; no concat., Compose one SSE event in wire format. Trailing blank line per spec., current_status_parsed_with_snapshot [tracer]: status=current carries         the, scheduled_status_parsed_no_snapshot [trace]: status=scheduled carries         no, _sse_chunk()
 
 ### Community 13 - "Local Tier 3 Agent Index Management"
-Cohesion: 0.14
-Nodes (22): LocalAgentEntry, add_local_agent(), load_local_agents(), LocalAgentEntry, Local index of tier-3 agents defined via `python -m ratatoskr.tier3`.  Workaroun, Add (or replace) an agent in the local index. agent_id is the key., Update an existing entry. Identical semantics to ``add_local_agent``     (agent_, Remove an entry by agent_id. No-op if absent (idempotent). (+14 more)
+Cohesion: 0.07
+Nodes (43): LocalAgentEntry, Namespace, add_local_agent(), load_local_agents(), _local_agents_path(), LocalAgentEntry, make_description(), Local index of tier-3 agents defined via `python -m ratatoskr.tier3`.  Workaroun (+35 more)
 
 ### Community 14 - "Ratatoskr Application Core"
-Cohesion: 0.09
-Nodes (19): RatatoskrApp, Populate identity widget from pre-resolved state; set idle hint.          Per is, Hydrate persona-header + Persona pane via GET /agents/{id}/persona_state., Update sticky header + Persona pane from a fresh snapshot.          Called on bo, Render an italic-dim placeholder in the Persona pane; keep header empty., v0.6.0: turn-ID headers across every pane for cross-pane         correlation. v0, Set the hint state attribute AND update the visible Static widget., Write a timestamped audit line to the debug pane.          v0.10.0: shared sink (+11 more)
+Cohesion: 0.07
+Nodes (19): _cancel_via_sse(), Populate identity widget from pre-resolved state; set idle hint.          Per is, Hydrate persona-header + Persona pane via GET /agents/{id}/persona_state., Render an italic-dim placeholder in the Persona pane; keep header empty., v0.6.0: turn-ID headers across every pane for cross-pane         correlation. v0, Set the hint state attribute AND update the visible Static widget., Write a timestamped audit line to the debug pane.          v0.10.0: shared sink, Set self.state with debug-pane audit log.          Every state machine transitio (+11 more)
 
 ### Community 15 - "Async Main Orchestrator"
-Cohesion: 0.08
-Nodes (21): _amain(), Async orchestrator: create-session (if --new) → SIGINT install → _run_turn → cle, _clear_env(), CaptureFixture, MonkeyPatch, user_agent_header_sent [trace]: outbound requests carry the ratatoskr User-Agent, happy_new_session_then_stream [happy,tracer]: …, happy_existing_session: --session, no create POST; just SSE stream → exit 0. (+13 more)
+Cohesion: 0.17
+Nodes (7): happy_submit_echoes_and_spawns [happy,tracer]: …, empty_submit_no_op [trace]: '' + Enter → no change; no worker spawned., submit_during_streaming_shows_busy_notice [adversarial]: …, submit_during_cancelling_shows_busy_notice [adversarial]: …, sse_connect_failed_returns_to_idle [error]: …, Patch RichLog.write AND VerticalScroll.mount to record every renderable     or m, _spy_writes()
 
 ### Community 16 - "Contract Parsing and Function Extraction"
-Cohesion: 0.11
-Nodes (31): Contract, ErrorSpec, _extract_function_blocks(), FunctionBlock, main(), _parse_body_sections(), parse_contract(), _parse_frontmatter() (+23 more)
+Cohesion: 0.10
+Nodes (34): Contract, ErrorSpec, _extract_function_blocks(), FunctionBlock, _is_issue_scoped(), main(), _parse_body_sections(), parse_contract() (+26 more)
 
 ### Community 17 - "Behavioral Guidelines Documentation"
 Cohesion: 0.06
@@ -251,8 +272,8 @@ Cohesion: 0.07
 Nodes (16): _parse_sse_id(), Parse the SSE wire `id:` as composite `{turn_id}:{seq}`. See contract FN _parse_, negative_seq [adversarial]: '42:-1' -> ValueError., trailing_whitespace [adversarial]: '42:3 ' -> ValueError (strict; no strip)., truncation [security]: 5000-char no-colon -> ValueError msg contains only raw[:6, PRE-001 hard: raw is a string -- isinstance check before parse., happy_simple [happy,tracer]: '42:3' -> SseId(turn_id=42, seq=3)., happy_seq_one: smallest valid id per spec — first event of first turn. (+8 more)
 
 ### Community 19 - "Tier 3 Error Handling"
-Cohesion: 0.11
-Nodes (19): Raised on HTTP 429 ``agent_quota_exceeded`` — 50-agent cap reached     on the He, Raised on HTTP 403 ``tier3_user_id_unsupported`` — auth's user_id     is not slu, Raised on HTTP 422 ``layer_deferred`` — define request carried a     non-null la, Raised on HTTP 404 — PATCH or DELETE on a non-existent agent_id     (spec §2634, Tier3AgentNotFound, Tier3LayerDeferred, Tier3QuotaExceeded, Tier3UserIdUnsupported (+11 more)
+Cohesion: 0.25
+Nodes (5): _args_new_no_agent(), ParsedArgs for bare --new (no --agent) — TUI-mode picker entry., picker_happy_path [happy,tracer]: agents fetched → picker exits with id → create, picker_esc_clean_exit: picker returns None → exit 0; no create_session; no main, list_agents 500 → stderr [session_api_failed]; exit 20; picker NOT opened.
 
 ### Community 20 - "Web Packaging and CLI Argument Tests"
 Cohesion: 0.07
@@ -262,45 +283,33 @@ Nodes (23): ArgumentParser, Packaging + lazy-import discipline tests for ratatos
 Cohesion: 0.07
 Nodes (26): Admin inspection endpoints, Appendix: `agent.ui_hints` config block, Authentication, Base URL, Client Implementation Guide, Custom exception handler status-code mapping, Endpoints, Error Codes (+18 more)
 
-### Community 22 - "CLI Command Rendering and Usage"
-Cohesion: 0.12
-Nodes (13): _format_duration_ms(), _format_usage(), main(), Ratatoskr CLI — non-interactive `--send` stdout presenter.  Implements docs/cont, Auto-scale duration formatting per issue #12 INV-006. Locale-blind., Natural-language usage formatting per issue #12 INV-007.      `arrow="->"` for C, Render one Worldtree SSE event with editorial hierarchy + coalescing., Sync entry point. Maps UsageError/_AuthError to exit codes BEFORE the event loop (+5 more)
-
 ### Community 23 - "TUI Shell Implementation"
-Cohesion: 0.09
-Nodes (18): _audit_line(), _format_persona_detail(), _format_persona_header(), _plain_label(), Ratatoskr Textual TUI shell — interactive primary presenter.  Implements docs/co, Pre-flight session resolution then App.run_async() inside one event loop.      E, Pre-amendment labeled-line shape for INV-009 render-exception fallback.      Use, HH:MM:SS.fff wall-clock timestamp for debug-pane log lines. (+10 more)
+Cohesion: 0.15
+Nodes (12): _format_usage(), Natural-language usage formatting per issue #12 INV-007.      `arrow="->"` for C, _audit_line(), _plain_label(), Ratatoskr Textual TUI shell — interactive primary presenter.  Implements docs/co, Pre-flight session resolution then App.run_async() inside one event loop.      E, Pre-amendment labeled-line shape for INV-009 render-exception fallback.      Use, HH:MM:SS.fff wall-clock timestamp for debug-pane log lines. (+4 more)
 
 ### Community 24 - "Contract Amendments for Presenter States"
 Cohesion: 0.09
 Nodes (22): Acceptance, `_amain` STEPS amended, Architecture, `CLASS CliPresenterState` (NEW), `CLASS TuiPresenterState` (NEW), Constraints, Context, Data flow (+14 more)
 
 ### Community 25 - "Session Creation API"
-Cohesion: 0.12
-Nodes (13): create_session(), POST /sessions to create a new session. See contract FN create_session.      Per, validation_failed: 422 -> SessionApiFailed(status=422); body truncated., unexpected_status_truncates: 500 + 5000-byte body -> SessionApiFailed; body == 1, empty_agent_id [adversarial]: '' -> AssertionError; no HTTP issued., happy_create_with_end_user_id [happy]: body carries both keys (issue #5)., default_omits_end_user_id [trace]: omit kwarg → body has no end_user_id (INV-002, empty_end_user_id [adversarial]: '' → AssertionError before HTTP (PRE-003). (+5 more)
+Cohesion: 0.05
+Nodes (22): create_session(), list_agents(), POST /sessions to create a new session. See contract FN create_session.      Per, GET /agents — list available agents. See contract FN list_agents (issue #8)., AsyncClient, validation_failed: 422 -> SessionApiFailed(status=422); body truncated., unexpected_status_truncates: 500 + 5000-byte body -> SessionApiFailed; body == 1, empty_agent_id [adversarial]: '' -> AssertionError; no HTTP issued. (+14 more)
 
 ### Community 26 - "Web Server Endpoint Handling"
-Cohesion: 0.10
-Nodes (21): _agents_endpoint(), _as_dict(), _create_session_endpoint(), _format_sse(), _persona_state_endpoint(), Starlette app factory + endpoint handlers for ratatoskr.web.  Per docs/contracts, POST /api/sessions → upstream POST /sessions. Per FN create_session_endpoint., POST /api/turns/{session_id} → allocate turn_id + register handle.      Per FN s (+13 more)
+Cohesion: 0.09
+Nodes (33): JSONResponse, Request, v0.16.0 — cancel paths must target the UPSTREAM turn_id, not the     browser-loc, A registered handle whose local turn_id (1) differs from its         captured up, A handle with upstream_turn_id still None (turn never opened the         upstrea, stream_turn_endpoint INV-005 — browser disconnect mid-stream triggers     upstre, TestDisconnectCancel, TestUpstreamTurnIdCancel (+25 more)
 
 ### Community 27 - "SSE ID Parsing"
-Cohesion: 0.20
-Nodes (20): NamedTuple, Parsed composite SSE wire `id:` per spec §SSE id format., SseId, _check(), _load_fixture(), Drift-detection between TUI presentation discipline and web JS presenter per iss, Assert (event_type, data) for `event` matches the fixture entry., test_affect_update_matches_fixture() (+12 more)
-
-### Community 28 - "Persona State Retrieval"
-Cohesion: 0.13
-Nodes (13): get_persona_state(), GET /agents/{agent_id}/persona_state — fetch current persona snapshot.      Worl, Any, Worldtree #204 / v0.28.0 — GET /agents/{agent_id}/persona_state.      Bootstrap, happy_full_snapshot [happy,tracer]: 200 → snapshot dict with pad +         domin, persona_not_configured_404 [error]: 404 with error_code         persona_not_conf, agent_not_available_404 [error]: 404 with error_code         agent_not_available, auth_scope_denied_403 [error]: 403 with error_code auth_scope_denied         → A (+5 more)
+Cohesion: 0.19
+Nodes (17): _check(), _load_fixture(), Drift-detection between TUI presentation discipline and web JS presenter per iss, Assert (event_type, data) for `event` matches the fixture entry., test_affect_update_matches_fixture(), test_awaiting_llm_first_token_matches_fixture(), test_cancelled_matches_fixture(), test_done_matches_fixture() (+9 more)
 
 ### Community 29 - "Agent Deletion and Authentication"
-Cohesion: 0.15
-Nodes (16): Namespace, delete_agent(), DELETE /agents/<id> — owner hard-delete (cancels active sessions     server-side, No API key resolvable → exit 11., Resolve API key + server URL with the same env-var fallback as cli.py., _resolve_auth(), _run_define(), _run_delete() (+8 more)
-
-### Community 30 - "Agent Listing Client"
-Cohesion: 0.15
-Nodes (11): list_agents(), GET /agents — list available agents. See contract FN list_agents (issue #8)., AsyncClient, happy_full_shape [happy,tracer]: spec full-shape mimir example → all fields., happy_minimum_shape: required-only agent → optional fields default., happy_multi_agent: 3 agents preserve order., happy_empty: 200 with [] returns empty list (no error)., omit_capabilities_empty: explicit [] from server still defaults to []. (+3 more)
+Cohesion: 0.50
+Nodes (3): lifespan_shutdown FN — INV-006: drain turn_registry within 5s budget., happy [tracer]: 2 in-flight turns + shutdown → upstream cancels called., TestLifespanShutdown
 
 ### Community 31 - "Browser SSE Stream Parsing"
-Cohesion: 0.17
-Nodes (12): _parse_browser_sse(), Response, Parse a server-to-browser SSE stream into [{"event": str, "data": dict}, ...]., happy [tracer]: respx mock one text+done → SSE stream yields text + done events., The stream generator captures upstream turn_id from the first         event's ss, stream_turn_endpoint full_event_vocab — one of each Event type proxied., full_event_vocab [scenario]: a stream with the non-terminal Event         types, error terminal [scenario]: an SSE `error` event (distinct from the         synth (+4 more)
+Cohesion: 0.14
+Nodes (16): _parse_browser_sse(), AsyncByteStream, Response, Tests for ratatoskr.web.server per docs/contracts/issues/16.contract.md.  The Te, SSE response backed by a live AsyncByteStream (for gated/hanging     streams in, Parse a server-to-browser SSE stream into [{"event": str, "data": dict}, ...]., happy [tracer]: respx mock one text+done → SSE stream yields text + done events., The stream generator captures upstream turn_id from the first         event's ss (+8 more)
 
 ### Community 32 - "Canonical Sync Documentation"
 Cohesion: 0.12
@@ -323,16 +332,16 @@ Cohesion: 0.12
 Nodes (16): arousal, dominance, pleasure, snapshot, arousal_delta, valence_delta, arousal, dominance (+8 more)
 
 ### Community 37 - "Web Server Functional Tests"
-Cohesion: 0.13
-Nodes (12): AsyncByteStream, Tests for ratatoskr.web.server per docs/contracts/issues/16.contract.md.  The Te, SSE response backed by a live AsyncByteStream (for gated/hanging     streams in, root_endpoint FN + /static mount — index.html + static asset serving., happy [tracer]: GET / → 200, content-type text/html, body contains '<html'., lifespan_shutdown FN — INV-006: drain turn_registry within 5s budget., happy [tracer]: 2 in-flight turns + shutdown → upstream cancels called., stream_turn_endpoint INV-005 — browser disconnect mid-stream triggers     upstre (+4 more)
+Cohesion: 0.50
+Nodes (3): root_endpoint FN + /static mount — index.html + static asset serving., happy [tracer]: GET / → 200, content-type text/html, body contains '<html'., TestStaticServing
 
 ### Community 38 - "Upload Management and Capabilities"
 Cohesion: 0.13
 Nodes (15): Agent capability: `accepts_uploads`, Attaching uploads to messages, Auth scopes, Capability vocabulary, DELETE /uploads/{upload_id}, Dispatch channels, Endpoints, Example JavaScript client (upload-then-reference) (+7 more)
 
 ### Community 39 - "Tier 3 Agent Patching Tests"
-Cohesion: 0.13
-Nodes (8): Tests for ratatoskr.tier3 per docs/contracts/issues/15.contract.md., happy_patch_both_fields: both fields set → request body has both., happy_patch_single_field: omit model → body has system_prompt only., field_not_mutable [error]: 422 + error_code → Tier3FieldNotMutable(field)., 404 [error]: PATCH on non-existent agent → Tier3AgentNotFound., no_fields_assert [adversarial]: both None → AssertionError, no HTTP., non_tier3_id_assert [adversarial]: agent_id without `:` → AssertionError., TestPatchAgent
+Cohesion: 0.22
+Nodes (8): Concurrency, Constraints, Context, Data flow, Division of labor (library vs store), Integration points, Invariants, Out of scope (deferred — do NOT flag as drift)
 
 ### Community 40 - "Agent Documentation and Attribution"
 Cohesion: 0.14
@@ -346,10 +355,6 @@ Nodes (13): CLI surface (`python -m ratatoskr.tier3`), Context, ERROR_ROUTING (m
 Cohesion: 0.14
 Nodes (13): CLI surface change (ratatoskr.cli amendment), Context, Data flow, ERROR_ROUTING (tui startup), FN list_agents, Functions, Invariants, Modified: _resolve_then_run (+5 more)
 
-### Community 43 - "Turn Cancellation via SSE"
-Cohesion: 0.14
-Nodes (8): _cancel_via_sse(), Fire-and-forget cancel; never raises (mirrors cli._cancel_and_log; #3 INV-009)., audit_callback_records_failure [v0.10.0]: failure path emits         `cancel_pos, happy_cancel [happy,tracer]: 200 OK → returns None; transcript has no [cancel_fa, cancel_failed_500 [error]: …, cancel_already_completed [scenario]: 409 → '[cancel_failed] CancelAlreadyComplet, transport_error_swallowed [error]: …, audit_callback_records_lifecycle [v0.10.0]: when the caller passes         an `a
-
 ### Community 44 - "Web Server Contract Version 16"
 Cohesion: 0.15
 Nodes (12): Console script, Constraints, Context, Function blocks, Invariants, Module shape, Public functions, Public surface (+4 more)
@@ -383,8 +388,8 @@ Cohesion: 0.17
 Nodes (11): Acceptance, Constraints, Context, Data flow, In-place amendments (the work), Invariants, Issue #1 (`ratatoskr.sse_client`) amendments, Issue #3 (`ratatoskr.cli`) amendments (+3 more)
 
 ### Community 52 - "Turn Cancellation and Logging"
-Cohesion: 0.17
-Nodes (7): _cancel_and_log(), Spawn-and-forget cancel that never raises (INV-009)., happy_cancel [happy,tracer]: 200 OK → returns None; stderr empty., cancel_failed_500 [error]: …, cancel_already_completed [scenario]: …, cancel_turn_not_found [scenario]: 404 → returns None; stderr CancelTurnNotFound., transport_error_swallowed [error]: …
+Cohesion: 0.20
+Nodes (6): _cancel_and_log(), Ratatoskr CLI — non-interactive `--send` stdout presenter.  Implements docs/cont, Spawn-and-forget cancel that never raises (INV-009)., cancel_already_completed [scenario]: …, cancel_turn_not_found [scenario]: 404 → returns None; stderr CancelTurnNotFound., transport_error_swallowed [error]: …
 
 ### Community 53 - "Mock Client Factory for Persona State"
 Cohesion: 0.21
@@ -403,8 +408,8 @@ Cohesion: 0.18
 Nodes (11): BM25 ranking, Endpoint, Error codes, Example: curl, Example: JavaScript pagination loop, FTS5 query syntax, Legacy `created_at` caveat, Query parameters (+3 more)
 
 ### Community 57 - "Presentation Contract JSON"
-Cohesion: 0.29
-Nodes (6): affect_update, event_type, _contract_version, _provenance, thinking, event_type
+Cohesion: 0.22
+Nodes (8): affect_update, data, event_type, _contract_version, status, _provenance, text, event_type
 
 ### Community 59 - "Monkey Patching for Local Agents"
 Cohesion: 0.18
@@ -434,10 +439,6 @@ Nodes (9): 1. Vor (optional), 2. Contract (required), 3. Branch — direct or AF
 Cohesion: 0.20
 Nodes (10): model, response, usage, done, data, event_type, cached_input_tokens, completion_tokens (+2 more)
 
-### Community 66 - "Local Agents Path Resolution"
-Cohesion: 0.29
-Nodes (7): _local_agents_path(), Resolve the local index file path with XDG + env-var override., Path, local_path(), MonkeyPatch, Point $RATATOSKR_LOCAL_AGENTS at a fresh tmp file for the test., TestPathResolution
-
 ### Community 67 - "Project README Overview"
 Cohesion: 0.20
 Nodes (9): Boundary rule, Consumer-side discoveries, Quickstart, Ratatoskr, Read in this order, Related repos, Status, Version-skew strategy (+1 more)
@@ -455,12 +456,12 @@ Cohesion: 0.22
 Nodes (8): Bump procedure, Conformance smoke check, Current pin, History, Pin history, Vendored artifacts, Why pin?, Worldtree spec pin
 
 ### Community 71 - "Turn Status and Timing Data"
-Cohesion: 0.29
-Nodes (7): data, awaiting_llm_first_token, data, event_type, elapsed_ms_since_building_prompt, status, turn_id
+Cohesion: 0.15
+Nodes (14): awaiting_llm_first_token, data, event_type, cancelled, data, event_type, elapsed_ms_since_building_prompt, partial_message_id (+6 more)
 
 ### Community 72 - "Error Code and Worker Phase Handling"
-Cohesion: 0.22
-Nodes (9): error_code, message, phase, error, data, event_type, worker_phase, data (+1 more)
+Cohesion: 0.40
+Nodes (5): error_code, message, error, data, event_type
 
 ### Community 73 - "CLI and TUI Contract Amendments"
 Cohesion: 0.22
@@ -474,10 +475,6 @@ Nodes (8): Admin: API Key Management, Bootstrap: first admin key, DELETE /admin/
 Cohesion: 0.25
 Nodes (7): Architecture, CLI — Non-interactive --send stdout presenter, Constraints, Context, Data flow, Invariants, Out of scope
 
-### Community 76 - "Description Synthesis for Picker"
-Cohesion: 0.39
-Nodes (3): make_description(), Synthesize a one-line description for the picker from a system prompt.      Stra, TestMakeDescription
-
 ### Community 77 - "Canonical Sync Pinning Utility"
 Cohesion: 0.36
 Nodes (7): main(), SHA-256 hash, first 16 hex chars., Replace the quoted value in a `key = "value"` line, preserving leading     white, Surgically update one pin's `pinned_sha256_16` + `pinned_at` lines in     the ma, _replace_value_preserve_format(), sha256_16(), update_pin_in_manifest_text()
@@ -507,8 +504,8 @@ Cohesion: 0.29
 Nodes (7): 1. Frontmatter, `complexity` guide, `dependencies:` — dispatch-ordering metadata (Sleipnir / preflight), Dependency fields — `depends_on` vs `dependencies`, `depends_on:` — module-architecture metadata, `prd` block — pinning a contract to its source-of-truth, Why two fields
 
 ### Community 84 - "User Agent Versioning"
-Cohesion: 0.29
-Nodes (5): Compose the User-Agent header — `ratatoskr/<version> (<contact>)`.      Per worl, _resolve_user_agent(), version_endpoint FN — tracer per contract issue #16., happy [tracer]: GET /version → 200, body == {"ratatoskr": "<current-version>"}., TestVersionEndpoint
+Cohesion: 0.50
+Nodes (3): version_endpoint FN — tracer per contract issue #16., happy [tracer]: GET /version → 200, body == {"ratatoskr": "<current-version>"}., TestVersionEndpoint
 
 ### Community 85 - "Architecture Overview"
 Cohesion: 0.29
@@ -590,10 +587,6 @@ Nodes (4): SSE frame with id but empty data (server-emitted keepalive shape)., e
 Cohesion: 0.33
 Nodes (4): stream_turn_endpoint FN — open upstream SSE, proxy events to browser., unknown_turn [error]: GET with turn_id not in registry → 404., upstream_error [error]: respx 500 → synthetic error SSE event., TestStreamTurnEndpoint
 
-### Community 105 - "Upstream Turn ID Cancellation"
-Cohesion: 0.33
-Nodes (4): v0.16.0 — cancel paths must target the UPSTREAM turn_id, not the     browser-loc, A registered handle whose local turn_id (1) differs from its         captured up, A handle with upstream_turn_id still None (turn never opened the         upstrea, TestUpstreamTurnIdCancel
-
 ### Community 106 - "Triadic Block Routing"
 Cohesion: 0.40
 Nodes (5): 2.1.A — `ERROR_ROUTING:` triadic block (SHIELDA), Example, Syntax, v2.0 back-compat, Why three axes
@@ -608,11 +601,11 @@ Nodes (5): Authorization model — agent invocation, Common pitfalls, Quick deci
 
 ### Community 109 - "SSE Content Data"
 Cohesion: 0.40
-Nodes (6): content, sse_id, text, data, event_type, data
+Nodes (6): content, sse_id, data, thinking, data, event_type
 
 ### Community 110 - "Cancelled Message Handling"
-Cohesion: 0.40
-Nodes (5): cancelled, data, event_type, partial_message_id, reason
+Cohesion: 0.22
+Nodes (8): Concurrency, Constraints, Context, Data flow, Division of labor (library vs store), Integration points, Invariants, Out of scope (deferred — do NOT flag as drift)
 
 ### Community 111 - "Implicit Tool Call Narration"
 Cohesion: 0.50
@@ -678,20 +671,32 @@ Nodes (3): Amendment — SSE phase events (issue #151, INV-053..INV-061), Integr
 Cohesion: 0.67
 Nodes (3): Amendment — Tier 3 consumer-defined agents (issue #181, Phase 2.0), Invariants (Phase 2.0 scope), Persona-state observability (issue #204)
 
+### Community 133 - "Community 133"
+Cohesion: 0.14
+Nodes (9): _format_persona_detail(), _format_persona_header(), Update sticky header + Persona pane from a fresh snapshot.          Called on bo, One-line persona summary for the sticky header widget.      Shape: `agent_id · d, Multi-line persona detail for the Persona TabPane.      Renders the full v0.28.0, header_compact_summary: agent_id · dominant_emotion · pad(P,A,D) · N emotions., header_singular_emotion: single emotion → '1 emotion active' (no 's')., header_no_emotions_drops_count: empty emotions list → no count suffix. (+1 more)
+
+### Community 135 - "Community 135"
+Cohesion: 0.28
+Nodes (7): build_app_from_env(), main(), Runnable entrypoint: serve the affect provider as an ASGI app.  For the live neg, Build the affect ASGI app from environment config (testable seam)., Tests for the affect-provider serve entrypoint (ratatoskr.provider.serve).  Only, test_build_app_from_env_builds_app_with_routes(), test_build_app_from_env_requires_heimdall_key()
+
+### Community 143 - "Community 143"
+Cohesion: 0.04
+Nodes (66): Raised on unexpected response status from /sessions endpoints.      `body` is tr, SessionApiFailed, define_agent(), delete_agent(), _extract_error_code(), _extract_error_field(), _parse_tier3_agent_info(), patch_agent() (+58 more)
+
 ## Knowledge Gaps
-- **522 isolated node(s):** `allow`, `Any`, `Path`, `Any`, `Any` (+517 more)
+- **538 isolated node(s):** `Context`, `Data flow`, `Invariants`, `Out of scope`, `Constraints` (+533 more)
   These have ≤1 connection - possible missing edges or undocumented components.
-- **4 thin communities (<3 nodes) omitted from report** — run `graphify query` to explore isolated nodes.
+- **28 thin communities (<3 nodes) omitted from report** — run `graphify query` to explore isolated nodes.
 
 ## Suggested Questions
 _Questions this graph is uniquely positioned to answer:_
 
-- **Why does `LocalAgentEntry` connect `Local Tier 3 Agent Index Management` to `TuiPresenterState Management`, `Parsed CLI Arguments Handling`, `TUI Tests and Contract Verification`, `Sync Entry Point and Session Resolution`, `Tier 3 Agent Lifecycle Client`, `Ratatoskr Application Argument Handling`, `Tier 3 Error Handling`, `Agent Deletion and Authentication`, `Browser SSE Stream Parsing`, `Web Server Functional Tests`, `Tier 3 Agent Patching Tests`, `Mock Client Factory for Persona State`, `Turn Cancellation Endpoint`, `Monkey Patching for Local Agents`, `Local Agents Path Resolution`, `Description Synthesis for Picker`, `Session Creation Endpoint Tests`, `Turn Submission Endpoint Tests`, `Server-Side End User ID Handling`, `Application Creation and Routing`, `User Agent Versioning`, `Stream Turn Endpoint Tests`, `Upstream Turn ID Cancellation`?**
-  _High betweenness centrality (0.055) - this node is a cross-community bridge._
-- **Why does `SessionApiFailed` connect `Agent Information Management` to `TuiPresenterState Management`, `Parsed CLI Arguments Handling`, `Tier 3 Agent Patching Tests`, `Worldtree Session Client`, `Tier 3 Agent Lifecycle Client`, `CLI Presenter State Management`, `Ratatoskr Application Core`, `Tier 3 Error Handling`, `Session Creation API`, `Persona State Retrieval`, `Agent Deletion and Authentication`, `Agent Listing Client`?**
-  _High betweenness centrality (0.054) - this node is a cross-community bridge._
-- **Why does `create_app()` connect `Turn Cancellation Endpoint` to `Agent Information Management`, `Web Server Functional Tests`, `Stream Turn Endpoint Tests`, `Upstream Turn ID Cancellation`, `Session Creation Endpoint Tests`, `Turn Submission Endpoint Tests`, `Server-Side End User ID Handling`, `Application Creation and Routing`, `User Agent Versioning`, `Mock Client Factory for Persona State`, `Web Packaging and CLI Argument Tests`, `Web Server Endpoint Handling`, `Monkey Patching for Local Agents`, `Browser SSE Stream Parsing`?**
-  _High betweenness centrality (0.039) - this node is a cross-community bridge._
+- **Why does `LocalAgentEntry` connect `Local Tier 3 Agent Index Management` to `TuiPresenterState Management`, `Parsed CLI Arguments Handling`, `Web Server Functional Tests`, `Stream Turn Endpoint Tests`, `Community 143`, `Session Creation Endpoint Tests`, `Server-Side End User ID Handling`, `Application Creation and Routing`, `Turn Submission Endpoint Tests`, `User Agent Versioning`, `Mock Client Factory for Persona State`, `Turn Cancellation Endpoint`, `Web Server Endpoint Handling`, `Monkey Patching for Local Agents`, `Agent Deletion and Authentication`, `Browser SSE Stream Parsing`?**
+  _High betweenness centrality (0.081) - this node is a cross-community bridge._
+- **Why does `SessionApiFailed` connect `Community 143` to `TuiPresenterState Management`, `Parsed CLI Arguments Handling`, `Agent Information Management`, `Stream Turn Rendering and Cancellation`, `Worldtree Session Client`, `Ratatoskr Application Argument Handling`, `Local Tier 3 Agent Index Management`, `Session Creation API`, `Web Server Endpoint Handling`?**
+  _High betweenness centrality (0.044) - this node is a cross-community bridge._
+- **Why does `create_app()` connect `Turn Cancellation Endpoint` to `Agent Information Management`, `Web Server Functional Tests`, `Stream Turn Endpoint Tests`, `Session Creation Endpoint Tests`, `Turn Submission Endpoint Tests`, `Server-Side End User ID Handling`, `Application Creation and Routing`, `User Agent Versioning`, `Mock Client Factory for Persona State`, `Web Packaging and CLI Argument Tests`, `Web Server Endpoint Handling`, `Monkey Patching for Local Agents`, `Agent Deletion and Authentication`, `Browser SSE Stream Parsing`?**
+  _High betweenness centrality (0.044) - this node is a cross-community bridge._
 - **Are the 51 inferred relationships involving `TuiPresenterState` (e.g. with `ParsedArgs` and `AgentInfo`) actually correct?**
   _`TuiPresenterState` has 51 INFERRED edges - model-reasoned connections that need verification._
 - **Are the 75 inferred relationships involving `Done` (e.g. with `AgentInfo` and `ComposeResult`) actually correct?**

persistent-memory.md

@@ -1,6 +1,6 @@
 # Persistent memory — ratatoskr
 
-_Last updated: 2026-05-29_
+_Last updated: 2026-06-15_
 
 This file captures durable intent and supporting evidence (goals, decisions,
 foot-gun warnings, in-flight state) across context resets. Read it at session
@@ -41,67 +41,62 @@ model output is untrusted); upstream API key stays server-side (INV-003).
 
 ## Current state / in-flight
 
-_As of 2026-05-29 (post-v0.17.0 frontend redesign):_
+_As of 2026-06-15:_
 
-**Status: v0.17.0 shipped and pushed** (main + tag `v0.17.0` on origin,
-2026-05-29). 378 tests passing.
+**Ratatoskr now has a SECOND identity: the v1 Bifrost Tier-3 consumer** — the
+durable persistence provider Worldtree writes Tier-3 agent affect/persona +
+memory into — alongside the original debug-observability TUI/web. The
+Bifrost-consumer work lives in `src/ratatoskr/provider/` and depends on
+`bifrost>=0.6.1` (a `provider` optional-extra from the gitea PyPI index),
+SEPARATE from the Worldtree conversation-API spec pin.
 
-**Last commits on `main`:**
-- `922ef34` feat(web): frontend redesign — aurora telemetry instrument + live Markdown (v0.17.0) [LOCAL ONLY]
-- `bbeaa23` docs: AGENTS.md — Codex-implementer session conventions
-- `f7ff5a4` fix(web): close Heid pass-2 findings — stream vocab + disconnect catch (v0.16.1)
-- `369857d` feat(web): address Heid code-review findings — issue #16 (v0.16.0)
-- `0fbbeb1` fix(sessions): unwrap FastAPI detail envelope in get_persona_state (v0.15.1)
-- `1228c37` feat(web): in-browser debug companion — issue #16 (v0.15.0)
-- `85143b8` fix(tui): disable RichLog min_width floor so wrap actually applies (v0.14.2)
-- `00854ce` fix(cli): wire AffectUpdate + AwaitingLlmFirstToken into --send presenter (v0.14.1)
-- `78bfcad` feat(sse,tui): bump spec pin to v0.29.0 + AwaitingLlmFirstToken (v0.14.0)
-- `4413859` feat(tui): persona surface — sticky header + TabPane (v0.13.0)
-- `d516537` feat(sessions): get_persona_state client + persona error taxonomy (v0.12.0)
-- `92aa05c` feat(sse,tui): bump spec pin to v0.28.0 + AffectUpdate event (v0.11.0)
-- `209427a` feat(tui): debug-pane audit logging surface (v0.10.0)
-- `139771c` feat(tui): live Markdown rendering during text streaming (v0.9.0)
+**AFFECT plane: SHIPPED + LIVE-PROVEN** (v0.17.2). Running now as a dev
+background shell (`ratatoskr-provider`, `0.0.0.0:8390`, env-sourced from
+`~/.config/ratatoskr/provider.env`). Smoked end-to-end against personal
+Worldtree **v0.35.2** (`10.250.50.152`): handshake 200 + `affect.emit` 200 →
+durable row persisted, opacity held.
 
-**Worldtree spec pin:** v0.29.0 (commit `562001a`, pinned 2026-05-26).
+**MEMORY plane: PROVIDER LIVE-PROVEN** (v0.17.3, commit `cd12951`; provider
+running on `0.0.0.0:8391` as a dev bg shell). Store + dev shell shipped (7
+contract blocks, 26+4 tests, #195 parity, heid-reviewed zero-drift) AND the
+live round-trip ran against personal **v0.35.3**: handshake + `upsert_many`
+(persist) + `search` (recall-dispatch) all green; `memory.db` holds 3 durable
+chunks (2 facts + 1 promoted question, scope `end_user:smoke-user`, 1024-d
+vec-indexed). **Proven: persist + dispatch + our search-correctness** — direct
+probe (embed the recall query via gateway `qwen3-embedding`, search our live
+store) recalls the right fact at cosine 0.60, correctly ranked. **NOT proven,
+and upstream (not ours): end-to-end recall-INJECTION** — Worldtree's
+recall-assembly doesn't surface our hits into the prompt (cold-session probe:
+search dispatched 200 but the model said "no memory"). worldtree-dev looped in
+(thread `01KV7JH8…`; #295 held open). Provider stays up with the live fixture.
+So NO minor bump / "all-green" announce until worldtree-dev closes the injection
++ question-promotion gaps.
 
-**Personal Worldtree smoke target:** `http://10.250.50.152:8081` (corviduo-dev
-LAN, reachable via PFI VPN). Currently running ≥ v0.29.13 (carries Worldtree
-#204 persona-state + #201 awaiting-llm-first-token heartbeat + the
-GemmaProvider reasoning_content fix). Sindra Tier 3 agent
-(`ratatoskr:sindra`, model `artemis-31b-v1i`) live and chain-of-thought
-flowing end-to-end.
+**Sindra:** a REGISTERED Tier-3 agent (`ratatoskr:sindra`, was model
+`artemis-31b-v1i`) — registration is REQUIRED to use a Tier-3 character (a
+session against an unregistered `agent_id` 404s), and she's been used. OPEN:
+the v0.35.2 personal rebuild may have wiped the agent DB — re-verify via
+`GET /agents` (needs a WORLDTREE_API_KEY, broker via infra-ops) and re-register
+if gone. Her persona only persists durably once personal is bound to our
+RUNNING affect provider for HER sessions (the smoke used synthetic
+`ratatoskr:smoke`); that binding is the persona-carry gap, independent of
+registration.
 
-**Outstanding eyeball items:**
-- **v0.17.0 frontend redesign — operator-confirmed 2026-05-29** ("redesign
-  looks good"); pushed to origin (main + tag `v0.17.0`). Eyeball gate cleared.
-- **Optional**: courtesy ack to brokkr-smithy-dev on the Codex-first pilot
-  thread (thread `01KSTH3Y8JKKSY9S9P41X3CM77`).
+**Heimdall key (Bifrost consumer):** persists env-only at
+`~/.config/ratatoskr/provider.env` (mode 600, nh3-dev) — `consumer="ratatoskr"`,
+HS256 = the API-key STRING utf-8-encoded; rotate via infra-ops.
 
-**Issue tracker (cleaned up 2026-05-29):** closed the stale-but-shipped
-backlog — #1–7, #9, #12, #14, #15 (all implemented across the v0→v0.17.0 arc;
-#9 superseded — spec pin advanced to v0.29.0, seven minors past its v0.22.1
-target). Only two issues remain open, both deferred by design:
-- **#10 subject:{type,id} migration tracking** — Worldtree-side breaking
-  change at future v0.22.x/v0.23.0; don't pre-implement per worldtree-dev.
-- **#11 AdminEvents pane** — needs `admin.events.read` Heimdall scope (admin
-  tier). Future side-pane work.
+**Pushed:** `main` is in sync with `origin` (pushed through `e57b054`); tags
+`v0.17.3` + a straggler `v0.8.2` pushed. Only `graphify-out/GRAPH_REPORT.md`
+runs dirty (auto-regenerated by the commit hook — generated artifact, not
+chased).
 
-**Codex-first discipline pilot — Ratatoskr selected** (althing thread
-`01KSTH3Y8JKKSY9S9P41X3CM77`, brokkr-smithy commit `5dd061c`, tag `v0.5.3`):
-- `AGENTS.md` committed (bbeaa23) — Codex-implementer conventions, sibling
-  to `CLAUDE.md`. Doesn't change how Claude-Code sessions operate;
-  governs the future `ratatoskr-codex` session.
-- `ratatoskr-codex` handle declared on althing.
-- `/codex-dispatch` skill pending galdrabok implementation.
-- **No action needed until operator spins up a codex session** in this same
-  working tree; bootstrap handshake at that point per `codex-first-
-  discipline.md` §5 (codex sends `codex-online` → ratatoskr-dev replies with
-  active branches + WIP state).
-- Per-dispatch opt-in: default Sleipnir Claude-implementer path remains
-  available; Codex used only when operator routes via `/codex-dispatch <N>`.
+**Still standing from before:** Worldtree spec pin v0.29.0 (`562001a`) for the
+conversation-API/TUI surface (untouched by the Bifrost work). Codex-first pilot
+still dormant (no codex session spun up — see the 2026-05-29 decision). Open
+issues: #10 (subject migration, deferred), #11 (AdminEvents pane, deferred).
 
-Branch: `main` (clean post-v0.17.0). Remote:
-`origin → git@gitea.phasefinal.com:vh/ratatoskr.git`.
+Branch: `main`. Remote: `origin → git@gitea.phasefinal.com:vh/ratatoskr.git`.
 
 ## Recent decisions
 
@@ -149,6 +144,12 @@ decision. Captures rationale that won't be obvious from code alone.
 - `[2026-05-28]` **Sindra Tier 3 agent: FORM ASSUMPTION gate + new physical-form description.** Persistent agent state changes via `python -m ratatoskr.tier3 patch`: (1) model migrated from `qwen3.6-35-a3b-heretic` to `artemis-31b-v1i`; (2) added FORM ASSUMPTION section — when instructed to become another character she IS that character (identity/environment/psychology/parameters), believes the environment as fact, no Sindra/holo-deck/parameter references, sticky until explicit revert; (3) replaced the abstract "classically beautiful" default-form sketch with a specific anti-artifice physical description (5'8", golden-copper skin, asymmetric features, oversize dark-green knit, bare feet). System prompt file is at `/tmp/personal-worldtree-sindra_system_prompt.md` (transient; not committed to repo).
 - `[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.
+- `[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)
+- `[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`.
+- `[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`).
+- `[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`).
+- `[2026-06-15]` **Providers run as dev-box BACKGROUND SHELLS, not infra-ops/systemd** (operator call — it's a dev box). `ratatoskr-provider` (affect) + a future `ratatoskr-memory-provider` as background processes; no productionization track.
+- `[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.
 
 _For per-issue TDD implementation notes, Volva findings, and contract amendments, see the git log — every per-issue commit carries a structured message capturing the trail._
 
@@ -175,3 +176,13 @@ defense against re-attempting the same cul-de-sac.
 - `[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.**
+- `[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` on the Worldtree instance) — a code grep structurally can't see it. Registration IS required to use a Tier-3 character (a session against an unregistered `agent_id` 404s), so since Sindra has been used, she WAS registered (`ratatoskr:sindra`). **Rule: to check whether a Tier-3 agent exists, query the Worldtree instance's `GET /agents`, never the consumer repo's code.** (Residual: the v0.35.2 personal rebuild may have wiped her — re-verify.)
+- `[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 for any consumer plane with non-trivial state semantics. Don't treat a clean contract review as evidence the code matches the dependency.
+- `[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)
+- `[2026-06-15]` **Canonical sync retired the issue-scoped parser staleness** (predicted by the 2026-05-21 entry's "until canonical bumps"). `contract_parser.py` synced to v2.1 (`f1fdfdb6→e10a4460`, commit `d85ab43`): now validates issue-scoped frontmatter (`target_module`/`scope`/`prd`) + four v2.1 test categories (scenario/trace/adversarial/property). Issues #3/#4 went FAIL→WARN (0 errors). The old "treat parser ERROR-on-issue-scoped as expected" note no longer applies.
+- `[2026-06-15]` **Refreshed #3/#4 presenter contracts to the shipped TUI model** (commit `335c835`). Both still described the abandoned single-`RichLog` double-display model; rewrote to the 4-pane live-Markdown reality (v0.5.0–v0.14.0 + Worldtree #201/#204) across INV-005, the `[performance]` constraint, the COMPOSE sketch, the `CLASS TuiPresenterState` block, both `render`/`_stream_turn_worker` blocks, and the `_cancel_via_sse` call site — plus the STEPS the v2.1 parser flagged missing. Code unchanged; contract-truth catching up to shipped code. Scope ballooned one-block→contract-wide mid-task; surfaced to operator before rewriting the INV-005 trade-off invariant.
+- `[2026-06-15]` **Memory plane TDD'd + shipped** (commit `cd12951`, v0.17.3). Impl decisions worth keeping: vec0 `distance_metric=cosine` set 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 (INV-005, contract STEP 2 `indicative`); 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` (memory reference's 3-level, vs affect's 2-level). **heid-code-review panel returned zero true drift**; adopted 5 cheap contract-anchored fixups (scope_filter dict guard, `top_k≤0→[]`, stronger scope-isolation / delete-hit-search / handshake-POST tests), accepted 6 with reasoning. **Partial-map optimistic-lock semantics pinned to the reference via an `expected_revisions` parity test** — resolved a Hulda finding deterministically (the affect-plane lesson: TDD against the shipped lib is the gate, not judgment).
+- `[2026-06-15]` **Memory provider LIVE-PROVEN against personal v0.35.3 (persist + dispatch + search-correctness); recall-injection is upstream.** worldtree-dev's Tier-3 promotion recipe (via infra-ops): memory-call fires from Tier-3 PROMOTION, gated at `service.py:2623` on `ctx.kind=="consumer_defined"` AND `ctx.memory_config is not None` (the agent must be DEFINED WITH a `memory` block — `ValidatedMemoryConfig {tier3_dreaming:false}`, dim 1024) AND handshake-granted memory caps AND `embedding_dim==1024`. `memory.agent_self_enabled` is NOT the gate (only the #248 self-candidate branch). Binding = `POST /sessions BifrostBindingRequest{endpoint_url}`, handshake `caps=["affect","memory"]`, **`binding.scope` null** (per-op scopes auto-minted: upsert_many→`memory:write`, search→`memory:read`). A `BIFROST_CLIENT_ALLOWED_HOSTS` allowlist gates the endpoint (Worldtree-side config — infra-ops added `:8391`). HTTP + HS256 both work in dev. (smoke wiring thread `01KV7D82MJYB…`)
+- `[2026-06-15]` **Diagnostic: our recall-search is SOUND — the cross-session recall gap is UPSTREAM, not the store — and it caught an upstream bug.** Embedded the recall query via gateway `qwen3-embedding` + searched our live store directly → the dark-chocolate fact recalls at cosine 0.60, correctly ranked above the unrelated name fact (0.16). So the cold-session recall failure is Worldtree's recall-assembly/injection (hits not reaching the prompt), NOT our search. ALSO found a latent UPSTREAM bug: a recall QUESTION got promoted as a durable chunk and ranks **#1 (0.70 > the fact's 0.60)**, polluting recall. Relayed to worldtree-dev (thread `01KV7JH8…`). **This is exactly #17's thesis — ratatoskr-as-provider caught an upstream bug invisible from the chat side.**
+- `[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 into the prompt, and same-session "recall" can be plain session history. infra-ops' cold cross-session probe caught my premature "all-green" (search dispatched 200, model had no memory). Don't call cross-session recall proven from a clean wire.
+- `[2026-06-15]` **Issue #17 filed — Bifrost-binding for the chat client (self-drive + correlated-log affect/memory ops).** REVERSES design-brief §6's "no Bifrost-binding consumer support" — that negative clause predates ratatoskr's provider identity (2026-06-14), so the canary now owns both ends but its client can't drive its own provider (`create_session` sends only `{agent_id, end_user_id}`; no Bifrost `endpoint_url`). Today's smoke proved the substrate (bind→dispatch→persist); only the observe/log channel design (open question #5) remains. The recall-injection caveat is upstream and doesn't block #17. NEXT on #17: `/heid` consult on the now-grounded framing → contract → TDD. (tracked: Gitea #17, labels enhancement/observability/tui)

pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "ratatoskr"
-version = "0.17.0"
+version = "0.17.4"
 description = "Worldtree Conversation API debug TUI — multi-pane observability dashboard"
 readme = "README.md"
 requires-python = ">=3.12"
@@ -25,6 +25,15 @@ web = [
     "starlette>=0.40",
     "uvicorn[standard]>=0.30",
 ]
+# Tier-3 Bifrost consumer: the durable memory.* + affect.* persistence
+# provider Worldtree writes into. Opt-in extra — distinct deployment surface
+# from the debug TUI. Recipe: bifrost/docs/implementing-a-consumer.md.
+provider = [
+    "ratatoskr[web]",       # reuse the starlette + uvicorn ASGI stack
+    "bifrost>=0.6.1",       # consumer engines + library (0.6.0 yanked: circular import)
+    "jsonschema>=4",        # bifrost runtime dep — envelope validation
+    "sqlite-vec>=0.1.6",    # vector index for the memory plane (vec0 virtual table)
+]
 dev = [
     "pytest>=8",
     "pytest-asyncio>=0.24",
@@ -37,8 +46,10 @@ dev = [
 ]
 
 [project.scripts]
-ratatoskr     = "ratatoskr.cli:main"
-ratatoskr-web = "ratatoskr.web.entrypoint:main"
+ratatoskr                 = "ratatoskr.cli:main"
+ratatoskr-web             = "ratatoskr.web.entrypoint:main"
+ratatoskr-provider        = "ratatoskr.provider.serve:main"
+ratatoskr-memory-provider = "ratatoskr.provider.serve_memory:main"
 
 [project.urls]
 Repository = "https://gitea.phasefinal.com/vh/ratatoskr"
@@ -52,6 +63,15 @@ worldtree-spec-rev = "562001af28d752c3a60d449c7ddd09f44fa9dc9a"
 worldtree-version = "v0.29.0"
 pinned-on = "2026-05-26"
 
+# Bifrost lives on the auth-gated gitea PyPI index (not public PyPI).
+# uv reads the credential from UV_INDEX_GITEA_USERNAME / _PASSWORD or ~/.netrc.
+[[tool.uv.index]]
+name = "gitea"
+url = "https://gitea.phasefinal.com/api/packages/vh/pypi/simple/"
+
+[tool.uv.sources]
+bifrost = { index = "gitea" }
+
 [tool.hatch.build.targets.wheel]
 packages = ["src/ratatoskr"]
 

src/ratatoskr/provider/__init__.py

@@ -0,0 +1,4 @@
+"""Tier-3 Bifrost consumer: durable memory.* + affect.* persistence provider.
+
+Contracts: docs/contracts/bifrost_affect_provider.contract.md (affect plane, v1).
+"""

src/ratatoskr/provider/affect_store.py

@@ -0,0 +1,146 @@
+"""SQLite-backed, conduit-opaque affect store (Bifrost affect plane, v1).
+
+Contract: docs/contracts/bifrost_affect_provider.contract.md
+
+The store persists Worldtree's Tier-3 affect snapshots verbatim and round-trips
+them. It runs NO affect logic: it reads only the two addressing keys
+(`agent_id`, `end_user_id`) and treats `pad`/`valence`/`persona_baselines`/
+`emitted_at` as an opaque blob (INV-001). Idempotency is replay-or-conflict,
+keyed by (actor-from-ctx, idempotency_key) (INV-008), and snapshots are
+last-write-wins by arrival across distinct keys (INV-002).
+"""
+from __future__ import annotations
+
+import hashlib
+import json
+import sqlite3
+import time
+from typing import Any
+
+from bifrost.affect import AffectIdempotencyConflict, AffectInvalidArguments
+from bifrost.consumer import ConsumerRegistration, build_affect_app
+from bifrost.reference_server import JwtVerifier
+
+_SHORT_RETRY_TTL_SECONDS = 300
+
+
+def _ctx_actor(ctx: Any) -> str:
+    """Mirror bifrost reference `_ctx_actor`: idempotency actor = JWT `sub`.
+
+    The real DispatchContext exposes the `sub` claim as `session_id`; test
+    contexts set `jwt_sub`. (INV-006: the actor comes from ctx, never the
+    snapshot.)
+    """
+    return str(getattr(ctx, "jwt_sub", None) or getattr(ctx, "session_id", ""))
+
+
+class RatatoskrAffectStore:
+    """The affect `MemoryDataStore`-shaped store handed to `build_affect_app`."""
+
+    affect_supported = True
+
+    def __init__(self, conn: sqlite3.Connection):
+        self._conn = conn
+
+    async def emit(
+        self,
+        snapshot: dict,
+        *,
+        idempotency_key: str,
+        ctx: Any,
+        idempotency_class: str | None = None,
+    ) -> dict:
+        del idempotency_class  # reserved; affect.* uses a single short-retry class
+
+        # INV-001: read ONLY the two addressing keys; everything else is opaque.
+        agent_id = snapshot.get("agent_id")
+        end_user_id = snapshot.get("end_user_id")
+        if not (
+            isinstance(agent_id, str)
+            and agent_id
+            and isinstance(end_user_id, str)
+            and end_user_id
+        ):
+            raise AffectInvalidArguments("snapshot missing agent_id / end_user_id")
+        if not (isinstance(idempotency_key, str) and idempotency_key):
+            raise AffectInvalidArguments("idempotency_key required")
+
+        # Whole-blob serialize + hash is opacity-safe (not a field read).
+        blob = json.dumps(snapshot, sort_keys=True, separators=(",", ":"))
+        digest = hashlib.sha256(blob.encode()).hexdigest()
+        idempotency_id = f"affect.emit|{_ctx_actor(ctx)}|{idempotency_key}"
+
+        # INV-008: replay (same digest) -> no-op; reuse with different digest -> conflict.
+        cached = self._conn.execute(
+            "SELECT digest FROM affect_idempotency WHERE idempotency_id = ?",
+            (idempotency_id,),
+        ).fetchone()
+        if cached is not None:
+            if cached[0] == digest:
+                return {"stored": True}
+            raise AffectIdempotencyConflict(
+                "idempotency key reused with different payload"
+            )
+
+        # INV-002 + INV-007: LWW snapshot upsert + idempotency record, one transaction.
+        now = time.time()
+        with self._conn:
+            self._conn.execute(
+                "INSERT INTO affect_snapshots (agent_id, end_user_id, snapshot_json, arrived_at) "
+                "VALUES (?, ?, ?, ?) "
+                "ON CONFLICT(agent_id, end_user_id) DO UPDATE SET "
+                "snapshot_json = excluded.snapshot_json, arrived_at = excluded.arrived_at",
+                (agent_id, end_user_id, blob, str(now)),
+            )
+            self._conn.execute(
+                "INSERT INTO affect_idempotency (idempotency_id, digest, expires_at) "
+                "VALUES (?, ?, ?)",
+                (idempotency_id, digest, now + _SHORT_RETRY_TTL_SECONDS),
+            )
+        return {"stored": True}
+
+    def get(self, agent_id: str, end_user_id: str) -> dict | None:
+        """Read-back of the stored snapshot (tests / future rehydrate-seed)."""
+        row = self._conn.execute(
+            "SELECT snapshot_json FROM affect_snapshots WHERE agent_id = ? AND end_user_id = ?",
+            (agent_id, end_user_id),
+        ).fetchone()
+        return json.loads(row[0]) if row is not None else None
+
+
+def open_affect_store(db_path: str) -> RatatoskrAffectStore:
+    """Open the SQLite-backed affect store, creating the schema on first use."""
+    conn = sqlite3.connect(db_path)
+    if db_path != ":memory:":
+        conn.execute("PRAGMA journal_mode=WAL")
+    conn.execute(
+        "CREATE TABLE IF NOT EXISTS affect_snapshots ("
+        "agent_id TEXT NOT NULL, end_user_id TEXT NOT NULL, "
+        "snapshot_json TEXT NOT NULL, arrived_at TEXT, "
+        "PRIMARY KEY (agent_id, end_user_id))"
+    )
+    conn.execute(
+        "CREATE TABLE IF NOT EXISTS affect_idempotency ("
+        "idempotency_id TEXT PRIMARY KEY, digest TEXT NOT NULL, expires_at REAL)"
+    )
+    conn.commit()
+    return RatatoskrAffectStore(conn)
+
+
+def build_affect_provider_app(
+    store: RatatoskrAffectStore,
+    heimdall_key: bytes,
+    consumer_id: str = "ratatoskr",
+):
+    """Wire the JWT verifier + registration and hand the store to bifrost.
+
+    Returns a Starlette ASGI app exposing POST /bifrost/handshake and
+    POST /bifrost/affect-call. The library owns the wire; this is the thin glue.
+    """
+    if getattr(store, "affect_supported", False) is not True:  # INV-005
+        raise ValueError("store must advertise affect_supported=True")
+    if not (isinstance(heimdall_key, bytes) and heimdall_key):
+        raise ValueError("heimdall_key must be non-empty bytes")
+    verifier = JwtVerifier(algorithm="HS256", key_bytes=heimdall_key)
+    registration = ConsumerRegistration(consumer_id=consumer_id)
+    return build_affect_app(store=store, verifier=verifier, registration=registration)

src/ratatoskr/provider/memory_store.py

@@ -0,0 +1,339 @@
+"""SQLite + sqlite-vec durable memory store (Bifrost memory plane, v1 basic plane).
+
+Contract: docs/contracts/bifrost_memory_provider.contract.md
+
+Worldtree writes Tier-3 agent memory chunks here (`upsert_many`) and recalls them
+by vector similarity (`search`), with point reads (`get`/`get_many`) and deletes
+(`delete_many`). We persist each chunk verbatim and read only its structural
+surface — embedding (rank), scope (isolation), id + revision (optimistic lock),
+origin/injection_source (consistency rule). Semantic content is never interpreted.
+We implement bifrost's OWN MemoryDataStore Protocol; conformance is #195 parity
+vs InMemoryMemoryStore.
+"""
+from __future__ import annotations
+
+import hashlib
+import json
+import logging
+import sqlite3
+import sys
+import time
+from typing import Any
+
+import sqlite_vec
+from bifrost.consumer import ConsumerRegistration, build_memory_app
+from bifrost.memory import (
+    IdempotencyConflict,
+    InvalidArguments,
+    RevisionMismatch,
+    StoreCapabilities,
+)
+from bifrost.reference_server import JwtVerifier
+
+_SHORT_RETRY_TTL_SECONDS = 300
+_DURABLE_JOB_TTL_SECONDS = 24 * 60 * 60
+
+# Inbound memory-call observability (#17 observe brick). A self-contained
+# stdout handler so the lines reliably reach the provider's stdout regardless
+# of uvicorn's logging config. INFO-level, no propagation to root.
+_log = logging.getLogger("ratatoskr.provider.memory")
+if not _log.handlers:
+    _h = logging.StreamHandler(sys.stdout)
+    _h.setFormatter(logging.Formatter("%(asctime)s [memory-provider] %(message)s"))
+    _log.addHandler(_h)
+    _log.setLevel(logging.INFO)
+    _log.propagate = False
+
+
+def _ctx_actor(ctx: Any) -> str:
+    """Reference `_ctx_actor`: actor = job_id | jwt_sub | session_id (never the record)."""
+    return str(
+        getattr(ctx, "job_id", None)
+        or getattr(ctx, "jwt_sub", None)
+        or getattr(ctx, "session_id", "")
+    )
+
+
+def _payload_digest(value: Any) -> str:
+    """Reference digest: sha256 of canonical JSON (sorted keys, compact, str-coerced)."""
+    blob = json.dumps(value, sort_keys=True, separators=(",", ":"), default=str)
+    return hashlib.sha256(blob.encode("utf-8")).hexdigest()
+
+
+def _idempotency_ttl_seconds(idempotency_class: str | None) -> int:
+    if idempotency_class == "durable-job":
+        return _DURABLE_JOB_TTL_SECONDS
+    return _SHORT_RETRY_TTL_SECONDS
+
+
+def _chunk_id(record: dict) -> str:
+    """Reference `_chunk_id`: first non-empty of id / chunk_id / memory_id."""
+    for key in ("id", "chunk_id", "memory_id"):
+        value = record.get(key)
+        if isinstance(value, str) and value:
+            return value
+    raise InvalidArguments("record missing id")
+
+
+def _record_vector(record: dict) -> list[float]:
+    """Reference `_record_vector`: embedding, falling back to vector, else []."""
+    value = record.get("embedding", record.get("vector", []))
+    return [float(v) for v in value] if isinstance(value, list) else []
+
+
+def _scope_matches(record_scope: Any, scope_filter: dict) -> bool:
+    """INV-005: record is in-scope iff every scope_filter axis matches record["scope"]."""
+    if not isinstance(record_scope, dict):
+        return False
+    return all(record_scope.get(axis) == value for axis, value in scope_filter.items())
+
+
+def _validate_injection(record: dict) -> None:
+    """INV-007: injected_context requires injection_source; non-injected forbids it."""
+    origin = record.get("origin")
+    injection_source = record.get("injection_source")
+    if origin == "injected_context" and not injection_source:
+        raise InvalidArguments("injected_context record requires injection_source")
+    if injection_source and origin != "injected_context":
+        raise InvalidArguments("injection_source only valid for injected_context origin")
+
+
+class RatatoskrMemoryStore:
+    """The MemoryDataStore-shaped store handed to bifrost's build_memory_app."""
+
+    def __init__(self, conn: sqlite3.Connection, embedding_dim: int):
+        self._conn = conn
+        self._dim = embedding_dim
+
+    def describe_store(self) -> dict:
+        # INV-006: advertise ONLY the v1 basic-plane capabilities (advertise-=>-implement).
+        return StoreCapabilities(
+            relational_edges_supported=False,
+            optimistic_locking_supported=True,
+            atomic_supersede_supported=False,
+            transaction_supported=False,
+            filterable_metadata_fields=[],
+        ).to_dict()
+
+    async def upsert_many(
+        self,
+        records: list[dict],
+        *,
+        idempotency_key: str,
+        ctx: Any,
+        expected_revisions: dict | None = None,
+        idempotency_class: str | None = None,
+    ) -> dict:
+        if not (isinstance(idempotency_key, str) and idempotency_key):  # PRE-001
+            raise InvalidArguments("idempotency_key required")
+        _log.info(
+            "memory-call upsert_many REQUEST: %d record(s) idempotency_key=%s actor=%s scopes=%s",
+            len(records), idempotency_key, _ctx_actor(ctx),
+            [r.get("scope") for r in records],
+        )
+        # INV-002: idempotency_id = ("default", verb, actor-from-ctx, key); digest over payload.
+        digest = _payload_digest({"records": records, "expected_revisions": expected_revisions})
+        idempotency_id = "|".join(("default", "upsert_many", _ctx_actor(ctx), idempotency_key))
+        cached = self._conn.execute(
+            "SELECT digest FROM memory_idempotency WHERE idempotency_id = ?",
+            (idempotency_id,),
+        ).fetchone()
+        if cached is not None:
+            if cached[0] == digest:
+                return {"upserted": len(records), "replayed": True}
+            raise IdempotencyConflict("idempotency key reused with different payload")
+        for record in records:  # INV-007 / PRE-002: validate before any write
+            _validate_injection(record)
+        # INV-004: all chunk rows + vec rows + the idempotency record in one transaction;
+        # a RevisionMismatch raised here rolls the whole batch back.
+        with self._conn:
+            if expected_revisions:  # INV-003: optimistic lock, checked before any write
+                for record in records:
+                    cid = _chunk_id(record)
+                    if cid in expected_revisions:
+                        row = self._conn.execute(
+                            "SELECT revision FROM memory_chunks WHERE chunk_id = ?", (cid,)
+                        ).fetchone()
+                        current = row[0] if row is not None else 0
+                        if current != expected_revisions[cid]:
+                            raise RevisionMismatch(
+                                f"stale expected revision for {cid}: "
+                                f"{expected_revisions[cid]} != {current}"
+                            )
+            for record in records:
+                chunk_id = _chunk_id(record)
+                # INV-003: first insert -> revision 1; re-upsert -> revision + 1.
+                self._conn.execute(
+                    "INSERT INTO memory_chunks "
+                    "(chunk_id, record_json, revision, scope_json, origin) "
+                    "VALUES (?, ?, 1, ?, ?) "
+                    "ON CONFLICT(chunk_id) DO UPDATE SET "
+                    "record_json=excluded.record_json, revision=memory_chunks.revision + 1, "
+                    "scope_json=excluded.scope_json, origin=excluded.origin",
+                    (
+                        chunk_id,
+                        json.dumps(record),
+                        json.dumps(record.get("scope")),
+                        record.get("origin"),
+                    ),
+                )
+                self._conn.execute("DELETE FROM memory_vec WHERE chunk_id = ?", (chunk_id,))
+                self._conn.execute(
+                    "INSERT INTO memory_vec(chunk_id, embedding) VALUES (?, ?)",
+                    (chunk_id, sqlite_vec.serialize_float32(_record_vector(record))),
+                )
+            self._conn.execute(
+                "INSERT INTO memory_idempotency (idempotency_id, digest, expires_at) "
+                "VALUES (?, ?, ?)",
+                (idempotency_id, digest, time.time() + _idempotency_ttl_seconds(idempotency_class)),
+            )
+        return {"upserted": len(records), "replayed": False}
+
+    async def search(
+        self,
+        vector: list[float],
+        *,
+        top_k: int,
+        scope_filter: dict | None = None,
+        metadata_filter: dict | None = None,
+        include: dict | None = None,
+        fidelity_target: Any = None,
+    ) -> list[dict]:
+        if len(vector) != self._dim:  # PRE-001
+            raise InvalidArguments(f"vector length {len(vector)} != embedding_dim {self._dim}")
+        if metadata_filter:  # PRE-002: v1 advertises no filterable metadata fields
+            raise InvalidArguments("metadata_filter is unsupported in v1")
+        if scope_filter is not None and not isinstance(scope_filter, dict):  # STEP 1
+            raise InvalidArguments("scope_filter must be a flat {axis: value} dict")
+        _log.info(
+            "memory-call search REQUEST: scope_filter=%r top_k=%s metadata_filter=%r vec_dim=%d",
+            scope_filter, top_k, metadata_filter, len(vector),
+        )
+
+        def _emit(rs: list[dict]) -> list[dict]:
+            _log.info(
+                "memory-call search RESPONSE: %d hit(s) %s",
+                len(rs),
+                [
+                    {
+                        "chunk_id": r["chunk_id"],
+                        "score": round(r["score"], 4),
+                        "scope": r["chunk"].get("scope"),
+                    }
+                    for r in rs
+                ],
+            )
+            return rs
+
+        if top_k <= 0:  # POST-001: at most top_k
+            return _emit([])
+        total = self._conn.execute("SELECT COUNT(*) FROM memory_vec").fetchone()[0]
+        if total == 0:
+            return _emit([])
+        # Over-fetch every candidate ranked by cosine distance, then scope-filter and
+        # take top_k — so top_k counts IN-SCOPE hits (INV-005), not pre-filter hits.
+        rows = self._conn.execute(
+            "SELECT v.chunk_id, v.distance, c.record_json, c.revision "
+            "FROM memory_vec v JOIN memory_chunks c ON c.chunk_id = v.chunk_id "
+            f"WHERE v.embedding MATCH ? AND k = {total} ORDER BY v.distance",
+            (sqlite_vec.serialize_float32([float(x) for x in vector]),),
+        ).fetchall()
+        results: list[dict] = []
+        for chunk_id, distance, record_json, revision in rows:
+            record = json.loads(record_json)
+            if scope_filter and not _scope_matches(record.get("scope"), scope_filter):
+                continue
+            results.append(
+                {
+                    "chunk": record,
+                    "chunk_id": chunk_id,
+                    "score": 1.0 - distance,  # vec0 cosine distance -> similarity
+                    "recalled_view": record.get("distillate", record),
+                    "revision": revision,
+                }
+            )
+            if len(results) >= top_k:
+                break
+        return _emit(results)
+
+    async def get(self, chunk_id: str) -> dict | None:
+        # INV-001: verbatim round-trip + an attached revision key, or None.
+        row = self._conn.execute(
+            "SELECT record_json, revision FROM memory_chunks WHERE chunk_id = ?",
+            (chunk_id,),
+        ).fetchone()
+        if row is None:
+            return None
+        record = json.loads(row[0])
+        record["revision"] = row[1]
+        return record
+
+    async def get_many(self, ids: list[str]) -> list[dict]:
+        # List form of get: found records only (absent ids are skipped).
+        found = []
+        for chunk_id in ids:
+            record = await self.get(chunk_id)
+            if record is not None:
+                found.append(record)
+        return found
+
+    async def delete_many(self, ids: list[str]) -> dict:
+        # One transaction: chunk row + its vec row leave together (no orphan vec rows).
+        _log.info("memory-call delete_many REQUEST: ids=%s", ids)
+        deleted = 0
+        with self._conn:
+            for chunk_id in ids:
+                cur = self._conn.execute(
+                    "DELETE FROM memory_chunks WHERE chunk_id = ?", (chunk_id,)
+                )
+                if cur.rowcount > 0:
+                    deleted += 1
+                self._conn.execute("DELETE FROM memory_vec WHERE chunk_id = ?", (chunk_id,))
+        return {"deleted": deleted}
+
+
+def open_memory_store(db_path: str, *, embedding_dim: int) -> RatatoskrMemoryStore:
+    """Open the SQLite+sqlite-vec memory store, creating schema + the vec index on first use."""
+    if not (isinstance(embedding_dim, int) and embedding_dim > 0):  # PRE-002
+        raise ValueError("embedding_dim must be a positive int")
+    conn = sqlite3.connect(db_path)
+    conn.enable_load_extension(True)
+    sqlite_vec.load(conn)
+    conn.enable_load_extension(False)
+    if db_path != ":memory:":
+        conn.execute("PRAGMA journal_mode=WAL")
+    conn.execute(
+        "CREATE TABLE IF NOT EXISTS memory_chunks ("
+        "chunk_id TEXT PRIMARY KEY, record_json TEXT NOT NULL, "
+        "revision INTEGER NOT NULL, scope_json TEXT, origin TEXT)"
+    )
+    conn.execute(
+        "CREATE TABLE IF NOT EXISTS memory_idempotency ("
+        "idempotency_id TEXT PRIMARY KEY, digest TEXT NOT NULL, expires_at REAL)"
+    )
+    # INV-005 / cosine recall: vec0 index at the fixed PINNED_EMBEDDER_DIM, cosine metric.
+    conn.execute(
+        "CREATE VIRTUAL TABLE IF NOT EXISTS memory_vec USING vec0("
+        f"chunk_id TEXT PRIMARY KEY, embedding float[{embedding_dim}] distance_metric=cosine)"
+    )
+    conn.commit()
+    return RatatoskrMemoryStore(conn, embedding_dim)
+
+
+def build_memory_provider_app(
+    store: RatatoskrMemoryStore,
+    heimdall_key: bytes,
+    consumer_id: str = "ratatoskr",
+):
+    """Wire the JWT verifier + registration and hand the store to bifrost.
+
+    Returns a Starlette ASGI app exposing POST /bifrost/handshake and
+    POST /bifrost/memory-call. The library owns the wire; this is the thin glue.
+    """
+    if not isinstance(store.describe_store(), dict):  # PRE-001 / INV-008
+        raise ValueError("store must advertise capabilities via describe_store()")
+    if not (isinstance(heimdall_key, bytes) and heimdall_key):  # PRE-002
+        raise ValueError("heimdall_key must be non-empty bytes")
+    verifier = JwtVerifier(algorithm="HS256", key_bytes=heimdall_key)
+    registration = ConsumerRegistration(consumer_id=consumer_id)
+    return build_memory_app(store=store, verifier=verifier, registration=registration)

src/ratatoskr/provider/serve.py

@@ -0,0 +1,40 @@
+"""Runnable entrypoint: serve the affect provider as an ASGI app.
+
+For the live negotiation smoke against a Worldtree instance. Config from env:
+- RATATOSKR_HEIMDALL_KEY (required): HS256 shared key for the consumer, utf-8.
+- RATATOSKR_AFFECT_DB   (default "affect.db"): SQLite path; ":memory:" = ephemeral.
+- RATATOSKR_CONSUMER_ID (default "ratatoskr").
+- RATATOSKR_PROVIDER_HOST (default "0.0.0.0"), RATATOSKR_PROVIDER_PORT (default 8390).
+"""
+from __future__ import annotations
+
+import os
+from collections.abc import Mapping
+
+from ratatoskr.provider.affect_store import build_affect_provider_app, open_affect_store
+
+
+def build_app_from_env(env: Mapping[str, str] | None = None):
+    """Build the affect ASGI app from environment config (testable seam)."""
+    env = os.environ if env is None else env
+    key = env.get("RATATOSKR_HEIMDALL_KEY")
+    if not key:
+        raise RuntimeError(
+            "RATATOSKR_HEIMDALL_KEY is required to serve the affect provider"
+        )
+    store = open_affect_store(env.get("RATATOSKR_AFFECT_DB", "affect.db"))
+    return build_affect_provider_app(
+        store,
+        heimdall_key=key.encode(),
+        consumer_id=env.get("RATATOSKR_CONSUMER_ID", "ratatoskr"),
+    )
+
+
+def main() -> None:
+    import uvicorn
+
+    uvicorn.run(
+        build_app_from_env(),
+        host=os.environ.get("RATATOSKR_PROVIDER_HOST", "0.0.0.0"),
+        port=int(os.environ.get("RATATOSKR_PROVIDER_PORT", "8390")),
+    )

src/ratatoskr/provider/serve_memory.py

@@ -0,0 +1,60 @@
+"""Runnable entrypoint: serve the memory provider as an ASGI app.
+
+For the live negotiation smoke against a Worldtree instance. Config from env:
+- RATATOSKR_HEIMDALL_KEY (required): HS256 shared key for the consumer, utf-8.
+- RATATOSKR_MEMORY_EMBEDDING_DIM (required): the pinned embedder dim; the
+  sqlite-vec index is created at this fixed dim, so a wrong value silently
+  breaks search — no default.
+- RATATOSKR_MEMORY_DB (default "memory.db"): SQLite path; ":memory:" = ephemeral.
+- RATATOSKR_CONSUMER_ID (default "ratatoskr").
+- RATATOSKR_PROVIDER_HOST (default "0.0.0.0"),
+  RATATOSKR_MEMORY_PROVIDER_PORT (default 8391 — distinct from affect's 8390 so
+  both planes can run side-by-side as separate apps, per the v1 contract).
+"""
+from __future__ import annotations
+
+import os
+from collections.abc import Mapping
+
+from ratatoskr.provider.memory_store import build_memory_provider_app, open_memory_store
+
+
+def build_memory_app_from_env(env: Mapping[str, str] | None = None):
+    """Build the memory ASGI app from environment config (testable seam)."""
+    env = os.environ if env is None else env
+    key = env.get("RATATOSKR_HEIMDALL_KEY")
+    if not key:
+        raise RuntimeError(
+            "RATATOSKR_HEIMDALL_KEY is required to serve the memory provider"
+        )
+    raw_dim = env.get("RATATOSKR_MEMORY_EMBEDDING_DIM")
+    if not raw_dim:
+        raise RuntimeError(
+            "RATATOSKR_MEMORY_EMBEDDING_DIM is required (Worldtree's PINNED_EMBEDDER_DIM)"
+        )
+    try:
+        embedding_dim = int(raw_dim)
+    except ValueError as exc:
+        raise RuntimeError(
+            f"RATATOSKR_MEMORY_EMBEDDING_DIM must be an int, got {raw_dim!r}"
+        ) from exc
+    if embedding_dim <= 0:
+        raise RuntimeError("RATATOSKR_MEMORY_EMBEDDING_DIM must be a positive int")
+    store = open_memory_store(
+        env.get("RATATOSKR_MEMORY_DB", "memory.db"), embedding_dim=embedding_dim
+    )
+    return build_memory_provider_app(
+        store,
+        heimdall_key=key.encode(),
+        consumer_id=env.get("RATATOSKR_CONSUMER_ID", "ratatoskr"),
+    )
+
+
+def main() -> None:
+    import uvicorn
+
+    uvicorn.run(
+        build_memory_app_from_env(),
+        host=os.environ.get("RATATOSKR_PROVIDER_HOST", "0.0.0.0"),
+        port=int(os.environ.get("RATATOSKR_MEMORY_PROVIDER_PORT", "8391")),
+    )

tests/test_provider_affect.py

@@ -0,0 +1,230 @@
+"""Tests for the Tier-3 Bifrost affect provider (ratatoskr.provider.affect_store).
+
+Contract: docs/contracts/bifrost_affect_provider.contract.md
+Vertical tracer-first: basic_emit -> opacity -> lww -> replay -> conflict ->
+missing_key -> #195 parity vs InMemoryAffectStore.
+"""
+from __future__ import annotations
+
+import types
+
+import pytest
+from bifrost.affect import AffectIdempotencyConflict, AffectInvalidArguments
+
+from ratatoskr.provider.affect_store import build_affect_provider_app, open_affect_store
+
+
+def _ctx(sub: str = "sub-1"):
+    # Mirrors bifrost's _ctx_actor: actor = jwt_sub (test ctx) or session_id.
+    return types.SimpleNamespace(jwt_sub=sub)
+
+
+def _snapshot(agent: str = "a1", user: str = "u1", **payload):
+    base = {
+        "agent_id": agent,
+        "end_user_id": user,
+        "pad": {"p": 0.1, "a": 0.2, "d": 0.3},
+        "valence": 0.5,
+        "persona_baselines": {"warmth": 0.7},
+        "emitted_at": "2026-06-14T00:00:00Z",
+    }
+    base.update(payload)
+    return base
+
+
+def _row_count(store, table: str) -> int:
+    return store._conn.execute(f"SELECT COUNT(*) FROM {table}").fetchone()[0]
+
+
+# --- open_affect_store ---
+
+def test_open_advertises_capability_and_schema():
+    store = open_affect_store(":memory:")
+    assert store.affect_supported is True
+    # both tables queryable
+    store._conn.execute("SELECT * FROM affect_snapshots")
+    store._conn.execute("SELECT * FROM affect_idempotency")
+
+
+def test_reopen_existing_file_is_idempotent(tmp_path):
+    db = str(tmp_path / "affect.db")
+    open_affect_store(db)  # first open creates schema
+    store = open_affect_store(db)  # reopen: CREATE TABLE IF NOT EXISTS is a no-op
+    assert store.affect_supported is True
+    store._conn.execute("SELECT * FROM affect_snapshots")
+    store._conn.execute("SELECT * FROM affect_idempotency")
+
+
+# --- emit ---
+
+async def test_basic_emit_stores_and_round_trips():
+    store = open_affect_store(":memory:")
+    snap = _snapshot()
+    result = await store.emit(snap, idempotency_key="k1", ctx=_ctx())
+    assert result == {"stored": True}
+    assert store.get("a1", "u1") == snap
+
+
+async def test_opacity_arbitrary_payload_round_trips_and_addressing_invariant():
+    store = open_affect_store(":memory:")
+    # arbitrary extra/unknown payload fields persist + round-trip verbatim
+    snap = _snapshot(weird_field={"nested": [1, 2, 3]}, mystery="x")
+    assert await store.emit(snap, idempotency_key="k1", ctx=_ctx()) == {"stored": True}
+    assert store.get("a1", "u1") == snap
+    # two snapshots for the same key differing ONLY in payload address the SAME row
+    snap2 = _snapshot(weird_field={"nested": [9]}, mystery="y", valence=0.99)
+    await store.emit(snap2, idempotency_key="k2", ctx=_ctx())
+    assert store.get("a1", "u1") == snap2
+    assert _row_count(store, "affect_snapshots") == 1  # same row overwritten
+
+
+async def test_lww_by_arrival_ignores_emitted_at():
+    store = open_affect_store(":memory:")
+    a = _snapshot(valence=0.1, emitted_at="2026-06-14T10:00:00Z")
+    b = _snapshot(valence=0.9, emitted_at="2026-06-14T08:00:00Z")  # OLDER emitted_at
+    await store.emit(a, idempotency_key="ka", ctx=_ctx())
+    await store.emit(b, idempotency_key="kb", ctx=_ctx())  # distinct key -> arrival wins
+    assert store.get("a1", "u1") == b  # later arrival wins despite older emitted_at
+
+
+async def test_replay_noop_same_key_same_payload():
+    store = open_affect_store(":memory:")
+    snap = _snapshot()
+    assert await store.emit(snap, idempotency_key="k1", ctx=_ctx()) == {"stored": True}
+    assert await store.emit(snap, idempotency_key="k1", ctx=_ctx()) == {"stored": True}
+    assert store.get("a1", "u1") == snap
+    assert _row_count(store, "affect_snapshots") == 1  # replay did not duplicate
+
+
+async def test_idempotency_conflict_same_key_different_payload():
+    store = open_affect_store(":memory:")
+    first = _snapshot(valence=0.1)
+    await store.emit(first, idempotency_key="k1", ctx=_ctx())
+    with pytest.raises(AffectIdempotencyConflict):
+        await store.emit(_snapshot(valence=0.2), idempotency_key="k1", ctx=_ctx())
+    assert store.get("a1", "u1") == first  # prior snapshot untouched
+
+
+async def test_same_key_distinct_actor_is_not_a_conflict():
+    # idempotency is actor-scoped (INV-006/-008): same key, different ctx actor
+    store = open_affect_store(":memory:")
+    await store.emit(_snapshot(valence=0.1), idempotency_key="k1", ctx=_ctx("sub-A"))
+    # different actor, same key, different payload -> NOT a conflict (distinct id)
+    assert await store.emit(
+        _snapshot(valence=0.2), idempotency_key="k1", ctx=_ctx("sub-B")
+    ) == {"stored": True}
+
+
+async def test_missing_end_user_id_raises_and_no_write():
+    store = open_affect_store(":memory:")
+    bad = _snapshot()
+    del bad["end_user_id"]
+    with pytest.raises(AffectInvalidArguments):
+        await store.emit(bad, idempotency_key="k1", ctx=_ctx())
+    assert _row_count(store, "affect_snapshots") == 0
+
+
+async def test_missing_agent_id_raises_and_no_write():
+    # PRE-001 guards BOTH addressing keys symmetrically.
+    store = open_affect_store(":memory:")
+    bad = _snapshot()
+    del bad["agent_id"]
+    with pytest.raises(AffectInvalidArguments):
+        await store.emit(bad, idempotency_key="k1", ctx=_ctx())
+    assert _row_count(store, "affect_snapshots") == 0
+
+
+async def test_empty_idempotency_key_raises():
+    store = open_affect_store(":memory:")
+    with pytest.raises(AffectInvalidArguments):
+        await store.emit(_snapshot(), idempotency_key="", ctx=_ctx())
+
+
+# --- get ---
+
+def test_get_absent_returns_none():
+    store = open_affect_store(":memory:")
+    assert store.get("nope", "nope") is None
+
+
+async def test_get_after_emit_returns_equal():
+    store = open_affect_store(":memory:")
+    snap = _snapshot()
+    await store.emit(snap, idempotency_key="k1", ctx=_ctx())
+    assert store.get("a1", "u1") == snap
+
+
+# --- build_affect_provider_app ---
+
+def test_build_app_exposes_handshake_and_affect_routes():
+    store = open_affect_store(":memory:")
+    app = build_affect_provider_app(store, heimdall_key=b"secret-key")
+    routes = {getattr(r, "path", None): r for r in app.routes}
+    assert "/bifrost/handshake" in routes
+    assert "/bifrost/affect-call" in routes
+    assert "POST" in routes["/bifrost/affect-call"].methods  # POST-001: the verb, not just the path
+
+
+def test_build_app_rejects_non_advertising_store():
+    store = open_affect_store(":memory:")
+    store.affect_supported = False
+    with pytest.raises(ValueError):
+        build_affect_provider_app(store, heimdall_key=b"k")
+
+
+def test_build_app_rejects_empty_key():
+    store = open_affect_store(":memory:")
+    with pytest.raises(ValueError):
+        build_affect_provider_app(store, heimdall_key=b"")
+
+
+# --- #195 conformance: parity vs the reference store through the real engine ---
+
+def _dispatch_ctx(*scopes: str, session_id: str = "actor-1"):
+    return types.SimpleNamespace(
+        scope=list(scopes), session_id=session_id, jwt_sub=session_id
+    )
+
+
+def _env(snap: dict, key: str = "sess-1:1:affect") -> dict:
+    return {
+        "operation": "affect.emit",
+        "args": snap,
+        "idempotency_key": key,
+        "idempotency_class": "short-retry",
+    }
+
+
+def _ref_shaped_snapshot(*, pleasure: float = 0.5, emitted_at: str = "2026-06-14T12:00:00Z"):
+    # Mirror the reference test's snapshot shape so the envelope validates.
+    return {
+        "agent_id": "agent-1",
+        "end_user_id": "user-1",
+        "pad": {"pleasure": pleasure, "arousal": 0.2, "dominance": -0.1},
+        "valence": [{"entity_id": "e1", "regard": 0.7, "familiarity": 0.3}],
+        "emitted_at": emitted_at,
+    }
+
+
+async def test_parity_vs_reference_store_through_dispatch():
+    from bifrost.affect import dispatch_affect_call
+    from bifrost.consumer.testing import InMemoryAffectStore
+
+    ref = InMemoryAffectStore()
+    mine = open_affect_store(":memory:")
+    ctx = _dispatch_ctx("affect:write")
+    snap = _ref_shaped_snapshot()
+
+    # happy persist: wire bodies must agree
+    assert await dispatch_affect_call(_env(snap), ctx, ref) == await dispatch_affect_call(
+        _env(snap), ctx, mine
+    )
+    # replay (same key + same payload): both no-op {stored: true}
+    assert await dispatch_affect_call(_env(snap), ctx, ref) == await dispatch_affect_call(
+        _env(snap), ctx, mine
+    )
+    # conflict (same key + different payload): both map to the same error envelope
+    other = _ref_shaped_snapshot(pleasure=0.99)
+    assert await dispatch_affect_call(_env(other), ctx, ref) == await dispatch_affect_call(
+        _env(other), ctx, mine
+    )

tests/test_provider_memory.py

@@ -0,0 +1,414 @@
+"""Tests for the Tier-3 Bifrost memory provider (ratatoskr.provider.memory_store).
+
+Contract: docs/contracts/bifrost_memory_provider.contract.md (v1.1)
+Vertical tracer-first: fresh_db -> basic_upsert (round-trip) -> replay -> conflict
+-> optimistic_lock -> injection_rule -> search/scope_isolation -> get/get_many ->
+delete_many -> build_memory_provider_app -> #195 parity vs InMemoryMemoryStore.
+"""
+from __future__ import annotations
+
+import types
+
+import pytest
+from bifrost.memory import IdempotencyConflict, InvalidArguments, RevisionMismatch
+
+from ratatoskr.provider.memory_store import (
+    build_memory_provider_app,
+    open_memory_store,
+)
+
+EMBEDDING_DIM = 8
+
+
+def _ctx(sub: str = "sub-1"):
+    # Mirrors bifrost reference _ctx_actor: actor = job_id | jwt_sub | session_id.
+    return types.SimpleNamespace(jwt_sub=sub)
+
+
+def _vec(*head: float) -> list[float]:
+    v = list(head) + [0.0] * EMBEDDING_DIM
+    return v[:EMBEDDING_DIM]
+
+
+def _chunk(cid: str = "c1", *, embedding=None, scope=None, **extra) -> dict:
+    rec = {
+        "id": cid,
+        "embedding": embedding if embedding is not None else _vec(1.0),
+        "scope": scope if scope is not None else {"end_user": "u1"},
+        "origin": "worldtree",
+        "distillate": {"summary": f"distillate-{cid}"},
+        "content": f"content-{cid}",
+    }
+    rec.update(extra)
+    return rec
+
+
+def _row_count(store, table: str) -> int:
+    return store._conn.execute(f"SELECT COUNT(*) FROM {table}").fetchone()[0]
+
+
+# --- open_memory_store ---
+
+def test_fresh_db_advertises_v1_caps_and_schema():
+    store = open_memory_store(":memory:", embedding_dim=EMBEDDING_DIM)
+    caps = store.describe_store()
+    assert caps["relational_edges_supported"] is False
+    assert caps["optimistic_locking_supported"] is True
+    assert caps["atomic_supersede_supported"] is False
+    assert caps["transaction_supported"] is False
+    assert caps["filterable_metadata_fields"] == []
+    # tables + vec index queryable
+    store._conn.execute("SELECT * FROM memory_chunks")
+    store._conn.execute("SELECT * FROM memory_idempotency")
+    store._conn.execute("SELECT * FROM memory_vec")
+
+
+def test_reopen_existing_file_is_idempotent(tmp_path):
+    db = str(tmp_path / "memory.db")
+    open_memory_store(db, embedding_dim=EMBEDDING_DIM)  # first open creates schema
+    store = open_memory_store(db, embedding_dim=EMBEDDING_DIM)  # reopen: IF NOT EXISTS no-op
+    assert isinstance(store.describe_store(), dict)
+    store._conn.execute("SELECT * FROM memory_chunks")
+    store._conn.execute("SELECT * FROM memory_vec")
+
+
+# --- upsert_many + get (tracer round-trip) ---
+
+async def test_basic_upsert_round_trips_verbatim_with_revision():
+    store = open_memory_store(":memory:", embedding_dim=EMBEDDING_DIM)
+    c1 = _chunk("c1", embedding=_vec(1.0))
+    c2 = _chunk("c2", embedding=_vec(0.0, 1.0))
+    result = await store.upsert_many([c1, c2], idempotency_key="k1", ctx=_ctx())
+    assert result == {"upserted": 2, "replayed": False}
+    # INV-001: each chunk round-trips verbatim, with a revision key attached (first insert -> 1)
+    assert await store.get("c1") == {**c1, "revision": 1}
+    assert await store.get("c2") == {**c2, "revision": 1}
+
+
+async def test_replay_same_key_same_payload_no_rewrite():
+    # INV-002: same idempotency_key + same digest -> replay (no second write, revision frozen)
+    store = open_memory_store(":memory:", embedding_dim=EMBEDDING_DIM)
+    c1 = _chunk("c1")
+    assert await store.upsert_many([c1], idempotency_key="k1", ctx=_ctx()) == {
+        "upserted": 1,
+        "replayed": False,
+    }
+    assert await store.upsert_many([c1], idempotency_key="k1", ctx=_ctx()) == {
+        "upserted": 1,
+        "replayed": True,
+    }
+    assert (await store.get("c1"))["revision"] == 1  # replay did not re-write / re-increment
+    assert _row_count(store, "memory_chunks") == 1
+
+
+async def test_conflict_same_key_different_payload_raises_and_keeps_first():
+    # INV-002: same key, different digest -> IdempotencyConflict; the first batch is intact
+    store = open_memory_store(":memory:", embedding_dim=EMBEDDING_DIM)
+    first = _chunk("c1", content="first")
+    await store.upsert_many([first], idempotency_key="k1", ctx=_ctx())
+    with pytest.raises(IdempotencyConflict):
+        await store.upsert_many(
+            [_chunk("c1", content="second")], idempotency_key="k1", ctx=_ctx()
+        )
+    assert await store.get("c1") == {**first, "revision": 1}  # untouched
+
+
+async def test_optimistic_lock_stale_expected_revision_raises_nothing_written():
+    # INV-003: a stale expected_revisions entry rolls back the whole batch
+    store = open_memory_store(":memory:", embedding_dim=EMBEDDING_DIM)
+    c1 = _chunk("c1", content="v1")
+    await store.upsert_many([c1], idempotency_key="k1", ctx=_ctx())  # revision 1
+    with pytest.raises(RevisionMismatch):
+        await store.upsert_many(
+            [_chunk("c1", content="v2")],
+            idempotency_key="k2",  # distinct key: not replay/conflict
+            ctx=_ctx(),
+            expected_revisions={"c1": 5},  # stale: stored revision is 1
+        )
+    assert await store.get("c1") == {**c1, "revision": 1}  # nothing written
+    assert _row_count(store, "memory_chunks") == 1
+
+
+async def test_optimistic_lock_match_upserts_and_increments_revision():
+    # INV-003: a matching expected_revisions writes and increments (1 -> 2)
+    store = open_memory_store(":memory:", embedding_dim=EMBEDDING_DIM)
+    await store.upsert_many([_chunk("c1", content="v1")], idempotency_key="k1", ctx=_ctx())
+    v2 = _chunk("c1", content="v2")
+    assert await store.upsert_many(
+        [v2], idempotency_key="k2", ctx=_ctx(), expected_revisions={"c1": 1}
+    ) == {"upserted": 1, "replayed": False}
+    assert await store.get("c1") == {**v2, "revision": 2}  # re-upsert increments
+    assert _row_count(store, "memory_chunks") == 1
+
+
+async def test_injection_rule_injected_without_source_raises_no_write():
+    # INV-007: origin == injected_context requires injection_source
+    store = open_memory_store(":memory:", embedding_dim=EMBEDDING_DIM)
+    bad = _chunk("c1", origin="injected_context")  # no injection_source
+    with pytest.raises(InvalidArguments):
+        await store.upsert_many([bad], idempotency_key="k1", ctx=_ctx())
+    assert _row_count(store, "memory_chunks") == 0
+
+
+async def test_injection_rule_non_injected_with_source_raises_no_write():
+    # INV-007: a non-injected record carrying injection_source is rejected
+    store = open_memory_store(":memory:", embedding_dim=EMBEDDING_DIM)
+    bad = _chunk("c1", origin="worldtree", injection_source="elsewhere")
+    with pytest.raises(InvalidArguments):
+        await store.upsert_many([bad], idempotency_key="k1", ctx=_ctx())
+    assert _row_count(store, "memory_chunks") == 0
+
+
+# --- search ---
+
+async def test_basic_search_ranks_by_cosine_with_recalled_view():
+    store = open_memory_store(":memory:", embedding_dim=EMBEDDING_DIM)
+    scope = {"end_user": "u1"}
+    c1 = _chunk("c1", embedding=_vec(1.0, 0.0), scope=scope)
+    c3 = _chunk("c3", embedding=_vec(0.9, 0.1), scope=scope)
+    await store.upsert_many(
+        [c1, _chunk("c2", embedding=_vec(0.0, 1.0), scope=scope), c3],
+        idempotency_key="k1",
+        ctx=_ctx(),
+    )
+    results = await store.search(_vec(1.0, 0.0), top_k=2, scope_filter=scope)
+    assert [r["chunk_id"] for r in results] == ["c1", "c3"]  # nearest to [1,0] by cosine
+    top = results[0]
+    assert top["chunk"] == c1  # verbatim chunk, no revision attached
+    assert top["recalled_view"] == {"summary": "distillate-c1"}  # = chunk["distillate"]
+    assert top["revision"] == 1
+    assert isinstance(top["score"], float)
+
+
+async def test_scope_isolation_excludes_other_scope_even_if_closer():
+    # INV-005: an out-of-scope chunk that scores HIGHER must not leak; only in-scope returned
+    store = open_memory_store(":memory:", embedding_dim=EMBEDDING_DIM)
+    await store.upsert_many(
+        [
+            _chunk("u2-near", embedding=_vec(1.0, 0.0), scope={"end_user": "u2"}),  # closest
+            _chunk("u1-far", embedding=_vec(0.0, 1.0), scope={"end_user": "u1"}),  # in-scope, far
+        ],
+        idempotency_key="k1",
+        ctx=_ctx(),
+    )
+    results = await store.search(_vec(1.0, 0.0), top_k=2, scope_filter={"end_user": "u1"})
+    assert [r["chunk_id"] for r in results] == ["u1-far"]  # u2-near excluded despite ranking first
+
+
+async def test_search_empty_store_returns_empty():
+    store = open_memory_store(":memory:", embedding_dim=EMBEDDING_DIM)
+    assert await store.search(_vec(1.0), top_k=5) == []
+
+
+async def test_search_non_empty_metadata_filter_rejected():
+    # PRE-002: v1 advertises no filterable metadata fields
+    store = open_memory_store(":memory:", embedding_dim=EMBEDDING_DIM)
+    with pytest.raises(InvalidArguments):
+        await store.search(_vec(1.0), top_k=5, metadata_filter={"x": 1})
+
+
+async def test_search_wrong_vector_dim_rejected():
+    # PRE-001: vector length must equal the pinned embedding_dim
+    store = open_memory_store(":memory:", embedding_dim=EMBEDDING_DIM)
+    with pytest.raises(InvalidArguments):
+        await store.search([1.0, 0.0], top_k=5)
+
+
+async def test_search_non_dict_scope_filter_rejected():
+    # search STEP 1: scope_filter must be a flat {axis: value} dict
+    store = open_memory_store(":memory:", embedding_dim=EMBEDDING_DIM)
+    with pytest.raises(InvalidArguments):
+        await store.search(_vec(1.0), top_k=5, scope_filter="u1")
+
+
+async def test_search_top_k_zero_returns_empty():
+    # POST-001: at most top_k — zero means zero
+    store = open_memory_store(":memory:", embedding_dim=EMBEDDING_DIM)
+    await store.upsert_many([_chunk("c1")], idempotency_key="k1", ctx=_ctx())
+    assert await store.search(_vec(1.0), top_k=0, scope_filter={"end_user": "u1"}) == []
+
+
+async def test_scope_isolation_fills_top_k_from_in_scope_past_higher_out_of_scope():
+    # INV-005: top_k counts IN-SCOPE hits. An out-of-scope chunk ranking #1 is skipped,
+    # and top_k is still filled from the in-scope set when enough in-scope chunks exist.
+    store = open_memory_store(":memory:", embedding_dim=EMBEDDING_DIM)
+    await store.upsert_many(
+        [
+            _chunk("u2-nearest", embedding=_vec(1.0, 0.0), scope={"end_user": "u2"}),  # ranks #1
+            _chunk("u1-near", embedding=_vec(0.95, 0.05), scope={"end_user": "u1"}),
+            _chunk("u1-mid", embedding=_vec(0.8, 0.2), scope={"end_user": "u1"}),
+            _chunk("u1-far", embedding=_vec(0.0, 1.0), scope={"end_user": "u1"}),
+        ],
+        idempotency_key="k1",
+        ctx=_ctx(),
+    )
+    results = await store.search(_vec(1.0, 0.0), top_k=2, scope_filter={"end_user": "u1"})
+    # exactly top_k in-scope (the 2 nearest u1 chunks); the higher-ranked u2 chunk is excluded
+    assert [r["chunk_id"] for r in results] == ["u1-near", "u1-mid"]
+
+
+# --- get / get_many ---
+
+async def test_get_absent_returns_none():
+    store = open_memory_store(":memory:", embedding_dim=EMBEDDING_DIM)
+    assert await store.get("nope") is None
+
+
+async def test_get_many_returns_found_records_only():
+    store = open_memory_store(":memory:", embedding_dim=EMBEDDING_DIM)
+    c1 = _chunk("c1")
+    await store.upsert_many([c1], idempotency_key="k1", ctx=_ctx())
+    assert await store.get_many(["c1", "absent"]) == [{**c1, "revision": 1}]
+
+
+# --- delete_many ---
+
+async def test_delete_hit_removes_chunk_and_vec_row():
+    store = open_memory_store(":memory:", embedding_dim=EMBEDDING_DIM)
+    await store.upsert_many([_chunk("c1"), _chunk("c2")], idempotency_key="k1", ctx=_ctx())
+    assert await store.delete_many(["c1"]) == {"deleted": 1}
+    assert await store.get("c1") is None
+    assert _row_count(store, "memory_chunks") == 1
+    assert _row_count(store, "memory_vec") == 1  # c1's vec row gone too (no orphan)
+    # delete_hit: search no longer surfaces it (vec/chunk coupling held)
+    hits = await store.search(_vec(1.0), top_k=5, scope_filter={"end_user": "u1"})
+    assert all(r["chunk_id"] != "c1" for r in hits)
+
+
+async def test_delete_absent_counts_zero():
+    store = open_memory_store(":memory:", embedding_dim=EMBEDDING_DIM)
+    assert await store.delete_many(["nope"]) == {"deleted": 0}
+
+
+# --- build_memory_provider_app ---
+
+def test_build_app_exposes_handshake_and_memory_routes():
+    store = open_memory_store(":memory:", embedding_dim=EMBEDDING_DIM)
+    app = build_memory_provider_app(store, heimdall_key=b"secret-key")
+    routes = {getattr(r, "path", None): r for r in app.routes}
+    assert "/bifrost/handshake" in routes
+    assert "/bifrost/memory-call" in routes
+    assert "POST" in routes["/bifrost/memory-call"].methods
+    assert "POST" in routes["/bifrost/handshake"].methods  # both routes are POST (incl. POST)
+
+
+def test_build_app_rejects_empty_key():
+    store = open_memory_store(":memory:", embedding_dim=EMBEDDING_DIM)
+    with pytest.raises(ValueError):
+        build_memory_provider_app(store, heimdall_key=b"")
+
+
+# --- #195 conformance: parity vs the reference store through the real engine ---
+
+def _dispatch_ctx(*scopes: str, session_id: str = "actor-1"):
+    return types.SimpleNamespace(
+        scope=list(scopes), session_id=session_id, jwt_sub=session_id, job_id=None
+    )
+
+
+def _ref_record(chunk_id: str, vector: list[float], *, end_user: str = "u1") -> dict:
+    # Mirrors bifrost's reference `record` helper so the envelope validates.
+    return {
+        "id": chunk_id,
+        "embedding": vector,
+        "distillate": {"text": chunk_id},
+        "metadata": {"worldtree.appraisal_confidence": 0.8},
+        "scope": {"end_user": end_user, "tenant": "t1"},
+        "origin": "worldtree",
+        "source_role": "assistant",
+        "trust_tier": "tier-3",
+        "provenance": {"trace": chunk_id},
+    }
+
+
+async def test_parity_upsert_many_vs_reference_through_dispatch():
+    from bifrost.consumer.testing import InMemoryMemoryStore
+    from bifrost.memory import dispatch_memory_call
+
+    ref = InMemoryMemoryStore()
+    mine = open_memory_store(":memory:", embedding_dim=2)
+    wctx = _dispatch_ctx("memory:write")
+    env = {
+        "operation": "upsert_many",
+        "args": {"records": [_ref_record("a", [1.0, 0.0]), _ref_record("b", [0.0, 1.0])]},
+        "idempotency_key": "k1",
+    }
+    # happy persist + replay: wire bodies must agree
+    assert await dispatch_memory_call(env, wctx, ref) == await dispatch_memory_call(env, wctx, mine)
+    assert await dispatch_memory_call(env, wctx, ref) == await dispatch_memory_call(env, wctx, mine)
+
+
+async def test_parity_search_ranked_ids_vs_reference_through_dispatch():
+    from bifrost.consumer.testing import InMemoryMemoryStore
+    from bifrost.memory import dispatch_memory_call
+
+    ref = InMemoryMemoryStore()
+    mine = open_memory_store(":memory:", embedding_dim=2)
+    wctx = _dispatch_ctx("memory:write")
+    rctx = _dispatch_ctx("memory:read")
+    up = {
+        "operation": "upsert_many",
+        "args": {
+            "records": [
+                _ref_record("a", [1.0, 0.0]),
+                _ref_record("b", [0.0, 1.0]),
+                _ref_record("c", [0.9, 0.1]),
+            ]
+        },
+        "idempotency_key": "k1",
+    }
+    await dispatch_memory_call(up, wctx, ref)
+    await dispatch_memory_call(up, wctx, mine)
+    search_env = {
+        "operation": "search",
+        "args": {"vector": [1.0, 0.0], "top_k": 2, "scope_filter": {"end_user": "u1"}},
+    }
+    rstatus, rbody = await dispatch_memory_call(search_env, rctx, ref)
+    mstatus, mbody = await dispatch_memory_call(search_env, rctx, mine)
+    assert rstatus == mstatus == 200
+    # #195: same ranked chunk_ids and the same per-result shape (scores may differ in the
+    # last float digit between vec0's cosine and the reference's Python cosine).
+    assert [r["chunk_id"] for r in rbody["results"]] == [r["chunk_id"] for r in mbody["results"]]
+    assert set(rbody["results"][0]) == set(mbody["results"][0])
+
+
+async def test_parity_expected_revisions_vs_reference_through_dispatch():
+    # #195: pins the partial-map optimistic-lock semantics against the reference
+    # (does an expected_revisions map that omits some batch records lock only the
+    # listed ones?). Resolves the contract's ambiguous "each record's stored revision".
+    from bifrost.consumer.testing import InMemoryMemoryStore
+    from bifrost.memory import dispatch_memory_call
+
+    ref = InMemoryMemoryStore()
+    mine = open_memory_store(":memory:", embedding_dim=2)
+    wctx = _dispatch_ctx("memory:write")
+
+    seed = {
+        "operation": "upsert_many",
+        "args": {"records": [_ref_record("a", [1.0, 0.0]), _ref_record("b", [0.0, 1.0])]},
+        "idempotency_key": "seed",
+    }
+    assert await dispatch_memory_call(seed, wctx, ref) == await dispatch_memory_call(seed, wctx, mine)
+
+    # partial map: only "a" is locked (revision 1); "b" is omitted from expected_revisions
+    partial = {
+        "operation": "upsert_many",
+        "args": {
+            "records": [_ref_record("a", [1.0, 0.0]), _ref_record("b", [0.0, 1.0])],
+            "expected_revisions": {"a": 1},
+        },
+        "idempotency_key": "partial",
+    }
+    assert await dispatch_memory_call(partial, wctx, ref) == await dispatch_memory_call(
+        partial, wctx, mine
+    )
+
+    # stale lock: both map to the same RevisionMismatch wire error
+    stale = {
+        "operation": "upsert_many",
+        "args": {"records": [_ref_record("a", [1.0, 0.0])], "expected_revisions": {"a": 99}},
+        "idempotency_key": "stale",
+    }
+    assert await dispatch_memory_call(stale, wctx, ref) == await dispatch_memory_call(
+        stale, wctx, mine
+    )

tests/test_provider_serve.py

@@ -0,0 +1,23 @@
+"""Tests for the affect-provider serve entrypoint (ratatoskr.provider.serve).
+
+Only the env -> app seam is unit-tested; uvicorn.run is the untestable shell.
+"""
+from __future__ import annotations
+
+import pytest
+
+from ratatoskr.provider.serve import build_app_from_env
+
+
+def test_build_app_from_env_requires_heimdall_key():
+    with pytest.raises(RuntimeError):
+        build_app_from_env({"RATATOSKR_AFFECT_DB": ":memory:"})
+
+
+def test_build_app_from_env_builds_app_with_routes():
+    app = build_app_from_env(
+        {"RATATOSKR_HEIMDALL_KEY": "shared-secret", "RATATOSKR_AFFECT_DB": ":memory:"}
+    )
+    paths = {getattr(r, "path", None) for r in app.routes}
+    assert "/bifrost/handshake" in paths
+    assert "/bifrost/affect-call" in paths

tests/test_provider_serve_memory.py

@@ -0,0 +1,48 @@
+"""Tests for the memory-provider serve entrypoint (ratatoskr.provider.serve_memory).
+
+Only the env -> app seam is unit-tested; uvicorn.run is the untestable shell.
+"""
+from __future__ import annotations
+
+import pytest
+
+from ratatoskr.provider.serve_memory import build_memory_app_from_env
+
+
+def test_build_memory_app_from_env_requires_heimdall_key():
+    with pytest.raises(RuntimeError):
+        build_memory_app_from_env(
+            {"RATATOSKR_MEMORY_DB": ":memory:", "RATATOSKR_MEMORY_EMBEDDING_DIM": "8"}
+        )
+
+
+def test_build_memory_app_from_env_requires_embedding_dim():
+    # A wrong/missing dim silently breaks vector search -> require it explicitly.
+    with pytest.raises(RuntimeError):
+        build_memory_app_from_env(
+            {"RATATOSKR_HEIMDALL_KEY": "k", "RATATOSKR_MEMORY_DB": ":memory:"}
+        )
+
+
+def test_build_memory_app_from_env_rejects_non_positive_dim():
+    with pytest.raises(RuntimeError):
+        build_memory_app_from_env(
+            {
+                "RATATOSKR_HEIMDALL_KEY": "k",
+                "RATATOSKR_MEMORY_DB": ":memory:",
+                "RATATOSKR_MEMORY_EMBEDDING_DIM": "0",
+            }
+        )
+
+
+def test_build_memory_app_from_env_builds_app_with_routes():
+    app = build_memory_app_from_env(
+        {
+            "RATATOSKR_HEIMDALL_KEY": "shared-secret",
+            "RATATOSKR_MEMORY_DB": ":memory:",
+            "RATATOSKR_MEMORY_EMBEDDING_DIM": "8",
+        }
+    )
+    paths = {getattr(r, "path", None) for r in app.routes}
+    assert "/bifrost/handshake" in paths
+    assert "/bifrost/memory-call" in paths

uv.lock

@@ -188,6 +188,18 @@ wheels = [
     { url = "https://files.pythonhosted.org/packages/64/b4/17d4b0b2a2dc85a6df63d1157e028ed19f90d4cd97c36717afef2bc2f395/attrs-26.1.0-py3-none-any.whl", hash = "sha256:c647aa4a12dfbad9333ca4e71fe62ddc36f4e63b2d260a37a8b83d2f043ac309", size = 67548 },
 ]
 
+[[package]]
+name = "bifrost"
+version = "0.6.1"
+source = { registry = "https://gitea.phasefinal.com/api/packages/vh/pypi/simple/" }
+dependencies = [
+    { name = "jsonschema" },
+]
+sdist = { url = "https://gitea.phasefinal.com/api/packages/vh/pypi/files/bifrost/0.6.1/bifrost-0.6.1.tar.gz", hash = "sha256:2eaf93c6da91faa6faa80a4c9a8d0c66161f4a7cc31ff041b0ae64daf3c161ea" }
+wheels = [
+    { url = "https://gitea.phasefinal.com/api/packages/vh/pypi/files/bifrost/0.6.1/bifrost-0.6.1-py3-none-any.whl", hash = "sha256:ed505d2c08cf4cdd0a84c68ec42f8732b4c1baf7d72befe5eacf75d88381d5ce" },
+]
+
 [[package]]
 name = "certifi"
 version = "2026.5.20"
@@ -419,6 +431,33 @@ wheels = [
     { url = "https://files.pythonhosted.org/packages/62/a1/3d680cbfd5f4b8f15abc1d571870c5fc3e594bb582bc3b64ea099db13e56/jinja2-3.1.6-py3-none-any.whl", hash = "sha256:85ece4451f492d0c13c5dd7c13a64681a86afae63a5f347908daf103ce6d2f67", size = 134899 },
 ]
 
+[[package]]
+name = "jsonschema"
+version = "4.26.0"
+source = { registry = "https://pypi.org/simple" }
+dependencies = [
+    { name = "attrs" },
+    { name = "jsonschema-specifications" },
+    { name = "referencing" },
+    { name = "rpds-py" },
+]
+sdist = { url = "https://files.pythonhosted.org/packages/b3/fc/e067678238fa451312d4c62bf6e6cf5ec56375422aee02f9cb5f909b3047/jsonschema-4.26.0.tar.gz", hash = "sha256:0c26707e2efad8aa1bfc5b7ce170f3fccc2e4918ff85989ba9ffa9facb2be326", size = 366583 }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/69/90/f63fb5873511e014207a475e2bb4e8b2e570d655b00ac19a9a0ca0a385ee/jsonschema-4.26.0-py3-none-any.whl", hash = "sha256:d489f15263b8d200f8387e64b4c3a75f06629559fb73deb8fdfb525f2dab50ce", size = 90630 },
+]
+
+[[package]]
+name = "jsonschema-specifications"
+version = "2025.9.1"
+source = { registry = "https://pypi.org/simple" }
+dependencies = [
+    { name = "referencing" },
+]
+sdist = { url = "https://files.pythonhosted.org/packages/19/74/a633ee74eb36c44aa6d1095e7cc5569bebf04342ee146178e2d36600708b/jsonschema_specifications-2025.9.1.tar.gz", hash = "sha256:b540987f239e745613c7a9176f3edb72b832a4ac465cf02712288397832b5e8d", size = 32855 }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/41/45/1a4ed80516f02155c51f51e8cedb3c1902296743db0bbc66608a0db2814f/jsonschema_specifications-2025.9.1-py3-none-any.whl", hash = "sha256:98802fee3a11ee76ecaca44429fda8a41bff98b00a0f2838151b113f210cc6fe", size = 18437 },
+]
+
 [[package]]
 name = "librt"
 version = "0.11.0"
@@ -1013,7 +1052,7 @@ wheels = [
 
 [[package]]
 name = "ratatoskr"
-version = "0.17.0"
+version = "0.17.4"
 source = { editable = "." }
 dependencies = [
     { name = "httpx" },
@@ -1033,6 +1072,13 @@ dev = [
     { name = "textual-dev" },
     { name = "uvicorn", extra = ["standard"] },
 ]
+provider = [
+    { name = "bifrost" },
+    { name = "jsonschema" },
+    { name = "sqlite-vec" },
+    { name = "starlette" },
+    { name = "uvicorn", extra = ["standard"] },
+]
 web = [
     { name = "starlette" },
     { name = "uvicorn", extra = ["standard"] },
@@ -1040,21 +1086,39 @@ web = [
 
 [package.metadata]
 requires-dist = [
+    { name = "bifrost", marker = "extra == 'provider'", specifier = ">=0.6.1", index = "https://gitea.phasefinal.com/api/packages/vh/pypi/simple/" },
     { name = "httpx", specifier = ">=0.27" },
     { name = "httpx-sse", specifier = ">=0.4" },
+    { name = "jsonschema", marker = "extra == 'provider'", specifier = ">=4" },
     { name = "mypy", marker = "extra == 'dev'", specifier = ">=1.11" },
     { name = "pytest", marker = "extra == 'dev'", specifier = ">=8" },
     { name = "pytest-asyncio", marker = "extra == 'dev'", specifier = ">=0.24" },
     { name = "pyyaml", marker = "extra == 'dev'", specifier = ">=6" },
     { name = "ratatoskr", extras = ["web"], marker = "extra == 'dev'" },
+    { name = "ratatoskr", extras = ["web"], marker = "extra == 'provider'" },
     { name = "respx", marker = "extra == 'dev'", specifier = ">=0.21" },
     { name = "ruff", marker = "extra == 'dev'", specifier = ">=0.6" },
+    { name = "sqlite-vec", marker = "extra == 'provider'", specifier = ">=0.1.6" },
     { name = "starlette", marker = "extra == 'web'", specifier = ">=0.40" },
     { name = "textual", specifier = ">=0.85" },
     { name = "textual-dev", marker = "extra == 'dev'", specifier = ">=1.5" },
     { name = "uvicorn", extras = ["standard"], marker = "extra == 'web'", specifier = ">=0.30" },
 ]
-provides-extras = ["web", "dev"]
+provides-extras = ["web", "provider", "dev"]
+
+[[package]]
+name = "referencing"
+version = "0.37.0"
+source = { registry = "https://pypi.org/simple" }
+dependencies = [
+    { name = "attrs" },
+    { name = "rpds-py" },
+    { name = "typing-extensions", marker = "python_full_version < '3.13'" },
+]
+sdist = { url = "https://files.pythonhosted.org/packages/22/f5/df4e9027acead3ecc63e50fe1e36aca1523e1719559c499951bb4b53188f/referencing-0.37.0.tar.gz", hash = "sha256:44aefc3142c5b842538163acb373e24cce6632bd54bdb01b21ad5863489f50d8", size = 78036 }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/2c/58/ca301544e1fa93ed4f80d724bf5b194f6e4b945841c5bfd555878eea9fcb/referencing-0.37.0-py3-none-any.whl", hash = "sha256:381329a9f99628c9069361716891d34ad94af76e461dcb0335825aecc7692231", size = 26766 },
+]
 
 [[package]]
 name = "respx"
@@ -1081,6 +1145,116 @@ wheels = [
     { url = "https://files.pythonhosted.org/packages/82/3b/64d4899d73f91ba49a8c18a8ff3f0ea8f1c1d75481760df8c68ef5235bf5/rich-15.0.0-py3-none-any.whl", hash = "sha256:33bd4ef74232fb73fe9279a257718407f169c09b78a87ad3d296f548e27de0bb", size = 310654 },
 ]
 
+[[package]]
+name = "rpds-py"
+version = "2026.5.1"
+source = { registry = "https://pypi.org/simple" }
+sdist = { url = "https://files.pythonhosted.org/packages/2e/43/25a8dcd3feedd735039a8f0b5b7e3b118232b5eae288c4fd9ab200d41094/rpds_py-2026.5.1.tar.gz", hash = "sha256:07b24fea40541e28570e5b795a4a38fbdcd12550c06bd0748005ecc8116ca256", size = 64459 }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/d4/e7/a78582dc57caa592dcc7d4fb69b61390561e908eb3d2f5df5928a8e354c0/rpds_py-2026.5.1-cp312-cp312-macosx_10_12_x86_64.whl", hash = "sha256:3abe24a66e57adcfa645d718063a5fa5103ecc71ddbf26d78af8f9368018ff1d", size = 353040 },
+    { url = "https://files.pythonhosted.org/packages/a3/43/35e3f136343aef451e545ce8c38d36c2f93c0ed88703db8b64ba2b205c68/rpds_py-2026.5.1-cp312-cp312-macosx_11_0_arm64.whl", hash = "sha256:58b1d94308ddf0b1982f61f2eb54bf92997c9ece8a8093ef014250f4a517906c", size = 345775 },
+    { url = "https://files.pythonhosted.org/packages/20/e1/0f2160c5982d3157734d5cb3ed63d8b2d583a73c9864f77b666449f32cf8/rpds_py-2026.5.1-cp312-cp312-manylinux_2_17_aarch64.manylinux2014_aarch64.whl", hash = "sha256:0fa92420128dadce7f54bd73ba1825a273e9268fe9e35dbf7e6362890efa4e08", size = 376329 },
+    { url = "https://files.pythonhosted.org/packages/d0/11/ee0ba42aff83bf4effdbc576673c6be64c5e173978c3f6d537e94482f77d/rpds_py-2026.5.1-cp312-cp312-manylinux_2_17_armv7l.manylinux2014_armv7l.whl", hash = "sha256:ca653c6546386227cd9800d1bef6a348099acf8db4250341da6d90f663d6dfcb", size = 383539 },
+    { url = "https://files.pythonhosted.org/packages/11/df/d94aa6a499d4ac40afe2d7620f2c597fd3c0f182e854ad7cf3f596a81cb6/rpds_py-2026.5.1-cp312-cp312-manylinux_2_17_ppc64le.manylinux2014_ppc64le.whl", hash = "sha256:66c93681c4729e4e3ecba31b8179fae083ff3118841672835140338b4b9867c1", size = 494674 },
+    { url = "https://files.pythonhosted.org/packages/1f/75/33d30f43bb2f458de11979486a591b1bf6e5651765ed1704c6197c2dc773/rpds_py-2026.5.1-cp312-cp312-manylinux_2_17_s390x.manylinux2014_s390x.whl", hash = "sha256:40ff257542e04796880e011e15cd4dc21c2599975df2aaa8f2c8495ca574e1a5", size = 389268 },
+    { url = "https://files.pythonhosted.org/packages/f4/1e/2c9096fc19d5fd084b0184ca2b651e659aa0a37e6fdbecf6ece47f147fe1/rpds_py-2026.5.1-cp312-cp312-manylinux_2_17_x86_64.manylinux2014_x86_64.whl", hash = "sha256:b6825cc329b290e93c5f6a9be2393118a763f6ccf6abd83704e0c102ca583644", size = 376280 },
+    { url = "https://files.pythonhosted.org/packages/b9/e5/61ec9f8be8211ea7f48448195549e4aaf02004083475493b0e137702ecb2/rpds_py-2026.5.1-cp312-cp312-manylinux_2_31_riscv64.whl", hash = "sha256:de42116e69cb53b911cc34aee5ab98f36c597b822545045d49e938818b99e5e4", size = 387233 },
+    { url = "https://files.pythonhosted.org/packages/0d/ca/bcec1005c4f4a234f92a29078631fee49206c7265ccae966f18fd332e80e/rpds_py-2026.5.1-cp312-cp312-manylinux_2_5_i686.manylinux1_i686.whl", hash = "sha256:c0f920015df2a504bebaba6d4c31ccf3fcf942f92655c086da30b671aad19aa6", size = 405009 },
+    { url = "https://files.pythonhosted.org/packages/72/e6/4d5718c5cf26c522dc7c9999e238da1e77380b81d0c5d1df11e271ddfeb1/rpds_py-2026.5.1-cp312-cp312-musllinux_1_2_aarch64.whl", hash = "sha256:0408a24e44feb919423dc6d9da677cb5cddb894d2ca9e763967d156d9c60fab4", size = 553113 },
+    { url = "https://files.pythonhosted.org/packages/d4/25/2ee807bdb3e1f0b7eddf7782acd5665a8b5205a331a7d7244a52c4812fd9/rpds_py-2026.5.1-cp312-cp312-musllinux_1_2_i686.whl", hash = "sha256:cea68bcd53467561ae2f96a6bdad1544299ba97b5b0ddcd5ac3d376e5c781c24", size = 618838 },
+    { url = "https://files.pythonhosted.org/packages/6a/c1/7d4c26f167f8c41501cc073d30ee22082b16ce358cf5b00ec97cbc7804ea/rpds_py-2026.5.1-cp312-cp312-musllinux_1_2_x86_64.whl", hash = "sha256:4be8b1d2a705cc37d08256004e1d07de143fa0075c8e85a3df020b776f62b732", size = 582436 },
+    { url = "https://files.pythonhosted.org/packages/04/1d/9d12b0a337bab46f4769f8857f4007e3b2d639e14f9a44a0efe157696e64/rpds_py-2026.5.1-cp312-cp312-win32.whl", hash = "sha256:6736718bd4fc49cbcb538ba30516fdbef161522acefb739657d48b97bd864fed", size = 212734 },
+    { url = "https://files.pythonhosted.org/packages/c5/93/e4116f2de7f56bc7406a76033dc501811ddeb22b7f056b92d632871ebb0c/rpds_py-2026.5.1-cp312-cp312-win_amd64.whl", hash = "sha256:0a7d1eec967df0e9b22614a5e177622e0c89611d03727fa0cb48e45028907870", size = 229045 },
+    { url = "https://files.pythonhosted.org/packages/cb/53/6c3419d85eb2ec5938a37627c585b42d76a63bb731d6e42ed4b079ebf486/rpds_py-2026.5.1-cp312-cp312-win_arm64.whl", hash = "sha256:1841d067089e117142d79b98aa0df2f08b52f2ecc1819dd2700636c0db74a473", size = 223967 },
+    { url = "https://files.pythonhosted.org/packages/6c/32/14c961ad295f490eb0849ada8b79683e93a59b9de3afdd983eaf55fa6867/rpds_py-2026.5.1-cp313-cp313-macosx_10_12_x86_64.whl", hash = "sha256:efef4ac29c6ff495531eb17ee705b62841ecaa291b7c7077e848ea03e237164d", size = 352787 },
+    { url = "https://files.pythonhosted.org/packages/ca/bb/d1b85117967c11191441a7274ae616c65d93901d082c588f89a50a8da5ae/rpds_py-2026.5.1-cp313-cp313-macosx_11_0_arm64.whl", hash = "sha256:c39f5b67a8a2e67179ada2a954227d670fe65fa9098457f698f56ddf248709b3", size = 345179 },
+    { url = "https://files.pythonhosted.org/packages/7c/46/d84105f062e626a1b233f863907288a4708c2d833b8b4c6fb2764bc080c0/rpds_py-2026.5.1-cp313-cp313-manylinux_2_17_aarch64.manylinux2014_aarch64.whl", hash = "sha256:b5c30f3f04eef4fbd362226a6f31d7c8895ca4fbb6e0b790f6890a98d8da8559", size = 376173 },
+    { url = "https://files.pythonhosted.org/packages/e2/ae/469d7959ce5b1201e1de135dc735b86db3b35dd0d1734f6a44246d5f061c/rpds_py-2026.5.1-cp313-cp313-manylinux_2_17_armv7l.manylinux2014_armv7l.whl", hash = "sha256:277f6c82f0580848796c7ecc8a7173aa3bfb928e4ff831261c2f60a81dc270db", size = 383162 },
+    { url = "https://files.pythonhosted.org/packages/dc/a2/57853d31a1116a561aa072794602ad3f6341e18d70a8523f1bd5b9fc1e5a/rpds_py-2026.5.1-cp313-cp313-manylinux_2_17_ppc64le.manylinux2014_ppc64le.whl", hash = "sha256:63c2c4c213f1a4e3f3de28ecab029dbdee976324e729c0d7a55211be72576b02", size = 495093 },
+    { url = "https://files.pythonhosted.org/packages/99/63/3a8eabcad9314b7daf5c65f451d2c33d989235cd8a5762186cf2c3f5a4f8/rpds_py-2026.5.1-cp313-cp313-manylinux_2_17_s390x.manylinux2014_s390x.whl", hash = "sha256:3350ec808fb538fe71a1f94dfaa0e29c598dfad805ce49f0caec5ae3183c652b", size = 389829 },
+    { url = "https://files.pythonhosted.org/packages/4b/25/05678d97fc25e2622df14dc530fb82023174ecfff6733991ed0d78f167bd/rpds_py-2026.5.1-cp313-cp313-manylinux_2_17_x86_64.manylinux2014_x86_64.whl", hash = "sha256:b1b964e3ab599e718dc46c018d104b1ebc007cbc6567d827c94a687fca56d77e", size = 374786 },
+    { url = "https://files.pythonhosted.org/packages/88/d1/8c90b6431e80a3b91b284a5c7c8c0c4f9c006444d90477a740d6e0f9c694/rpds_py-2026.5.1-cp313-cp313-manylinux_2_31_riscv64.whl", hash = "sha256:19cb09fab7b7fc96b2a6e28f2e34b72a3705ff27b37edb77455316e5d3f3dc9b", size = 386920 },
+    { url = "https://files.pythonhosted.org/packages/ff/99/4638f672ab356682d633ee0da9255f5b67ce6efd0b85eb94ad3e255e65a5/rpds_py-2026.5.1-cp313-cp313-manylinux_2_5_i686.manylinux1_i686.whl", hash = "sha256:abe76bcdba31e576cb83eeb8797aa0d882b738fef6dc65d0601fc753806a5b46", size = 405059 },
+    { url = "https://files.pythonhosted.org/packages/66/3f/3546524b6eb4cc2e1f363a3d638fa52f6c24faae3500c25fb488b02f1740/rpds_py-2026.5.1-cp313-cp313-musllinux_1_2_aarch64.whl", hash = "sha256:8bff7073db3899158fff55ebf57b113a67030af26f80a18978f9f0aa60250ddf", size = 553030 },
+    { url = "https://files.pythonhosted.org/packages/c6/c3/7b3388c796fcf471bd17194242d4dc1a7608567c0fa422bcc1c5e79f9c1e/rpds_py-2026.5.1-cp313-cp313-musllinux_1_2_i686.whl", hash = "sha256:8ba264fa49be666cd9cc56bf34ec7002fb3d27a4aee5bcb4d43d0d18feb1bb6f", size = 618975 },
+    { url = "https://files.pythonhosted.org/packages/61/1e/a3cb07f2795075d1d88efddae2f541359fde5f08c81ee114c29c2949c90a/rpds_py-2026.5.1-cp313-cp313-musllinux_1_2_x86_64.whl", hash = "sha256:4860b603ddda0475a8885499b3729e90229d480105b42651962a5397d995fa89", size = 581178 },
+    { url = "https://files.pythonhosted.org/packages/a1/74/e758c03a5ef46f04c37f2651a2893db846d569ba8a7bca469d4b58939bcd/rpds_py-2026.5.1-cp313-cp313-win32.whl", hash = "sha256:7944270ae71383f6e2657dd7d5ce4eeb4ac2d0059a6738f0510583d462ab4842", size = 212481 },
+    { url = "https://files.pythonhosted.org/packages/70/ec/a2aca432db9c7359b40fa393eeeaa0d166c2f70175be956e75fa24197c44/rpds_py-2026.5.1-cp313-cp313-win_amd64.whl", hash = "sha256:88647f43a73c4e01be19b04ceef0c8d3a1958153604d13c773becd8016f2a0cf", size = 228519 },
+    { url = "https://files.pythonhosted.org/packages/29/60/a73bfdd45b096574556acf303bbd9fa9eed36ca8a818b514e2a5d5fe2b9d/rpds_py-2026.5.1-cp313-cp313-win_arm64.whl", hash = "sha256:453895624ecf7db7063b1004e44037522bbaef9ff6a945e59bc71662d7a03abd", size = 223446 },
+    { url = "https://files.pythonhosted.org/packages/18/e2/408105fd611823f00882aea810f3989a30d26b1bab8b6beb20f98c724e0e/rpds_py-2026.5.1-cp313-cp313t-macosx_10_12_x86_64.whl", hash = "sha256:b4e4bc98639ec915f512fde3aa7a95e0041d95d9c3cc86eea841fa63cb1e8600", size = 355287 },
+    { url = "https://files.pythonhosted.org/packages/8d/58/5c4a43436843c90d0f6d19f82c200c80e3843ca9fa07b237623327f6d384/rpds_py-2026.5.1-cp313-cp313t-macosx_11_0_arm64.whl", hash = "sha256:cacedb7a6e167680acba45ad5716e89067d225dc80da0d7040cae8c81d4572fa", size = 347033 },
+    { url = "https://files.pythonhosted.org/packages/fb/c2/1a71acdacaf4e259b10278fb87b039ded3cf80041bcd89dd8a3ea702ded6/rpds_py-2026.5.1-cp313-cp313t-manylinux_2_17_aarch64.manylinux2014_aarch64.whl", hash = "sha256:68700371c5d7ae1412862ddfa719090925c93ecf351c566d66f09d04b136ea00", size = 376891 },
+    { url = "https://files.pythonhosted.org/packages/c2/c8/535f3d9b65addd8e28aa87b83c6e526799c3717a88273db8ea795beeef7a/rpds_py-2026.5.1-cp313-cp313t-manylinux_2_17_armv7l.manylinux2014_armv7l.whl", hash = "sha256:296c799becfa849c779c8725494fe9ed94959ed886787df4364b058465bad7f0", size = 385646 },
+    { url = "https://files.pythonhosted.org/packages/1c/91/dc033f313345c354ade914dbe73cdb90b615a4409ea02430d5356794f3d8/rpds_py-2026.5.1-cp313-cp313t-manylinux_2_17_ppc64le.manylinux2014_ppc64le.whl", hash = "sha256:d3858b908218ee108d0bbfb2095ccc237648053c9bf98affad7cb079acaf1d97", size = 498830 },
+    { url = "https://files.pythonhosted.org/packages/27/fc/90fcbea459dbb8ddc18a2e0fd1de9412b48bc84ffff2db771cf714bacfd6/rpds_py-2026.5.1-cp313-cp313t-manylinux_2_17_s390x.manylinux2014_s390x.whl", hash = "sha256:4fb8d2e7cb2f850b169806d61d1b991738acec96500a75c30f49caf064ce7cef", size = 392830 },
+    { url = "https://files.pythonhosted.org/packages/b2/1d/46cd11a228c9750684a798d98f878be6f614aa762438da7378f035e79e35/rpds_py-2026.5.1-cp313-cp313t-manylinux_2_17_x86_64.manylinux2014_x86_64.whl", hash = "sha256:27b74c10ed6a8f190f4287f53bcfea348b92a84a9c9f70d30183d1e6172d580d", size = 379613 },
+    { url = "https://files.pythonhosted.org/packages/24/4a/d9b0c6af3a1de03eb93741bbe8be2bdce84d8fda8224f3005451d86df389/rpds_py-2026.5.1-cp313-cp313t-manylinux_2_31_riscv64.whl", hash = "sha256:b9a6528956191c48c52294a592dbd4a8386d7048bdb25c0efcb6b966466c6d83", size = 388183 },
+    { url = "https://files.pythonhosted.org/packages/c5/b4/db7aaabdda6d020afc87d981bcc2f57a434c7dec60ecfc2ab3dd50b20351/rpds_py-2026.5.1-cp313-cp313t-manylinux_2_5_i686.manylinux1_i686.whl", hash = "sha256:af03e34e860047bc7a352b842856fcf78798fbb81132cc98bd2f907ab4eb9cd2", size = 408578 },
+    { url = "https://files.pythonhosted.org/packages/08/d6/070f6a41cbb343e2ac4171859bf3f3623e0ab002f72619d6d505313ec2de/rpds_py-2026.5.1-cp313-cp313t-musllinux_1_2_aarch64.whl", hash = "sha256:fea6e836d10abbe191d557d33bd58bd5987725fe63aa1eefe557d230209855bd", size = 553573 },
+    { url = "https://files.pythonhosted.org/packages/75/ab/1a71ea3589c4345dac0a0518f0e6a031cb42689277851b683c46d27463a5/rpds_py-2026.5.1-cp313-cp313t-musllinux_1_2_i686.whl", hash = "sha256:fc0c0f878ea770a0a8a462456c5ad36fc9fe6358e6b76fdadc7f17575e0b8bf1", size = 620861 },
+    { url = "https://files.pythonhosted.org/packages/8a/22/9bf80a56069c0c443fcfefac639a86a744550a2898817a6dfd3e26654924/rpds_py-2026.5.1-cp313-cp313t-musllinux_1_2_x86_64.whl", hash = "sha256:e0b360f316d966b048b085857630b3cc51f3db2f07b06f440eac8f695374d1e3", size = 585633 },
+    { url = "https://files.pythonhosted.org/packages/da/68/3b2c0a75c9e04125696f84ebdbbf304acf5a40b58ba4481cdb98a922c3ba/rpds_py-2026.5.1-cp313-cp313t-win32.whl", hash = "sha256:a2999883eedf72fdfb7520b92c7d4ec2572a71ff40239377aa604cc529eecafc", size = 210074 },
+    { url = "https://files.pythonhosted.org/packages/e7/8b/609157d5a25d37d4f29f92840ba531f416907c34ae5c5739dd21fc2bef98/rpds_py-2026.5.1-cp313-cp313t-win_amd64.whl", hash = "sha256:e07be2a9d7122bd6e82dea89814ef8dc893feb1aae97fec1630f3263bbb30e55", size = 228635 },
+    { url = "https://files.pythonhosted.org/packages/d4/6f/19c1918a4b590d8de87e712e4abe4b3875771eff60216fb6153cf6665c68/rpds_py-2026.5.1-cp314-cp314-macosx_10_12_x86_64.whl", hash = "sha256:1f2c391c3059798093b65df23aca2cac150460ae9c630d99dec83d703d9485b9", size = 349756 },
+    { url = "https://files.pythonhosted.org/packages/e5/60/a06fe7da34eca79dacbf958a2ba0c6eea85bc2b29de20080bf40f72f66fa/rpds_py-2026.5.1-cp314-cp314-macosx_11_0_arm64.whl", hash = "sha256:413b424f7c4ee65ab5e5be91f5731be0f8b41a1ee2b12dfe810d716312e95a78", size = 343831 },
+    { url = "https://files.pythonhosted.org/packages/bf/ec/b2333b97b90e2a6ef6ca8ad386ee284968e74bcfe113b3f1a8d9036429a9/rpds_py-2026.5.1-cp314-cp314-manylinux_2_17_aarch64.manylinux2014_aarch64.whl", hash = "sha256:2c595a1d9255dce0599e13130d1440ab2506654f2b50294226ee06402f8fef63", size = 375127 },
+    { url = "https://files.pythonhosted.org/packages/14/7f/e00aae54067f2b488c4637961d5f58204d470795fc791085fa3f15060d2e/rpds_py-2026.5.1-cp314-cp314-manylinux_2_17_armv7l.manylinux2014_armv7l.whl", hash = "sha256:1c27c5f6102eac8c03e7595a00827a53b271ba40a53b59ff8709170e0855ea4a", size = 379034 },
+    { url = "https://files.pythonhosted.org/packages/be/cc/423999bbb8ae8dc93c77fc1d5e984ade5eb89d237d3bb884ccfa72ae2890/rpds_py-2026.5.1-cp314-cp314-manylinux_2_17_ppc64le.manylinux2014_ppc64le.whl", hash = "sha256:6c7fcf61d44cacecaf3aea542b0e053db77972a4573e7ceda16fb2b399161195", size = 490823 },
+    { url = "https://files.pythonhosted.org/packages/0f/aa/c671bf660f12e68d3c52ff86c7066ed1372df5a0f4f2ff584e419b8207e7/rpds_py-2026.5.1-cp314-cp314-manylinux_2_17_s390x.manylinux2014_s390x.whl", hash = "sha256:2c817a189d4ee14290420e5ff051e4dd6baa13f3edf84685071dee07a6d538ee", size = 388144 },
+    { url = "https://files.pythonhosted.org/packages/19/c8/d63bb75b68afe77b229e3021c6031bcaf01da5db5b0e69d0d10f9ba679a7/rpds_py-2026.5.1-cp314-cp314-manylinux_2_17_x86_64.manylinux2014_x86_64.whl", hash = "sha256:21846aac0ed2e0589f38c12dc44e77bb64e494b771eadbcf169cba00566ba7ba", size = 371959 },
+    { url = "https://files.pythonhosted.org/packages/82/35/c51122014d8274ff37dc606d60049c3db7d83da02b5b282511e5a906a9a6/rpds_py-2026.5.1-cp314-cp314-manylinux_2_31_riscv64.whl", hash = "sha256:b317c87a13f769a4e787819bd508aaa5d69aa09b0880de9af6d3a8a54571cdec", size = 383558 },
+    { url = "https://files.pythonhosted.org/packages/e3/f9/2790cb99c136a5363acdeacf5c27c56f3de0d4118a1f48fca83404c99c89/rpds_py-2026.5.1-cp314-cp314-manylinux_2_5_i686.manylinux1_i686.whl", hash = "sha256:ce87129d9f2c14fa6c4a8601fb80eb4488c80d38a20cd13758ef11123e14995d", size = 402789 },
+    { url = "https://files.pythonhosted.org/packages/e5/1b/e4fb584f8c75d35c38150ff6a332cda949e6f97acba1f4fd123b14ab56fe/rpds_py-2026.5.1-cp314-cp314-musllinux_1_2_aarch64.whl", hash = "sha256:9cdddb6c1207d284d94fd1530adf57fbd797fe7c4b8704ba85f49414f2557e7d", size = 551405 },
+    { url = "https://files.pythonhosted.org/packages/d8/f7/a6731b4216cb3793ea1af5391da240f5683dacc0d13e034fe5fc3503f240/rpds_py-2026.5.1-cp314-cp314-musllinux_1_2_i686.whl", hash = "sha256:4e237e139f94d3c036fd28eb9f564c99055476ff4ff05cd42be55ce349b5aa02", size = 616975 },
+    { url = "https://files.pythonhosted.org/packages/2c/ea/2e051a81d95d8e63f4b35a1c463a87e8766bc3d083c067c5dfb6bf220747/rpds_py-2026.5.1-cp314-cp314-musllinux_1_2_x86_64.whl", hash = "sha256:ed0954b524873214369184a9c82b0eaa45a3fbb9a798cd95b17e0d98499e7ea0", size = 578701 },
+    { url = "https://files.pythonhosted.org/packages/65/56/b5f6fdb2083e32bca8a8993d89e70db114b4756c9e2c38421328126689d2/rpds_py-2026.5.1-cp314-cp314-win32.whl", hash = "sha256:2d88621d6a7d4dfa633d21abe90f280bb205274e16b1d1e61c6ad4640b2453b7", size = 209806 },
+    { url = "https://files.pythonhosted.org/packages/fb/80/65a5aa96c155e611d1ed844e4e1f57f3e36b021f396d9f8585d756e6b90d/rpds_py-2026.5.1-cp314-cp314-win_amd64.whl", hash = "sha256:cef8ac28d26f4dda3533060c20fbf80a325458fa9fd23ea72a73cdfa8e978838", size = 225985 },
+    { url = "https://files.pythonhosted.org/packages/27/7c/ad185212e87b05f196daef92bc5f3caf07298eb47c295b5585c3dd3093ac/rpds_py-2026.5.1-cp314-cp314-win_arm64.whl", hash = "sha256:eaaea962c68cdc68d4a533ba985ab8e9484277910bbfaa2ab3ef7732667bfed8", size = 221219 },
+    { url = "https://files.pythonhosted.org/packages/23/58/e14ae18759020334646b031e708ab4158d653a938822bfb7b95ef2e93aa3/rpds_py-2026.5.1-cp314-cp314t-macosx_10_12_x86_64.whl", hash = "sha256:21942f52dbbd5f8758bf021213d28bd45c39e873e65e2407faf5f1846f5761ad", size = 352148 },
+    { url = "https://files.pythonhosted.org/packages/31/9b/5f4a1e2f960bca3ac5d052b139dd31eed97b259f9d909173821760d542e8/rpds_py-2026.5.1-cp314-cp314t-macosx_11_0_arm64.whl", hash = "sha256:f414556f6e3958300ff941e40c9f97e3dc9774ddd1b3434c475d73dd354bbed3", size = 345196 },
+    { url = "https://files.pythonhosted.org/packages/1a/71/1d9574d6a2fa20ab60eaa55c7467f5aa20cbc770f341a05f09c0876f59e2/rpds_py-2026.5.1-cp314-cp314t-manylinux_2_17_aarch64.manylinux2014_aarch64.whl", hash = "sha256:ef1013a8625c74043210190b246f5b1551e09757c1f356c6e4160ef96c5bc081", size = 374981 },
+    { url = "https://files.pythonhosted.org/packages/0c/9a/37e99f4915a80aa71670263c1267f7ae0af95f53a3f61e6c3bdc016d4515/rpds_py-2026.5.1-cp314-cp314t-manylinux_2_17_armv7l.manylinux2014_armv7l.whl", hash = "sha256:cc68e231a77a5f0d774ae278a1f8e55c0456501820847c1e4efb3829f3441df6", size = 379961 },
+    { url = "https://files.pythonhosted.org/packages/a8/ff/6e73f74b89d2e0715e0fc86b7dde893f9a61ae2f9b256ff3bdfe41ac4e94/rpds_py-2026.5.1-cp314-cp314t-manylinux_2_17_ppc64le.manylinux2014_ppc64le.whl", hash = "sha256:9baffb505aff33acc69b422a19f77806680f3c8632227d79f48de8a810d1c2c5", size = 495965 },
+    { url = "https://files.pythonhosted.org/packages/ea/e0/425faba25f59d74d4638b267f7c7a80e8649d2ef4db10a19b0c4a71e6e6f/rpds_py-2026.5.1-cp314-cp314t-manylinux_2_17_s390x.manylinux2014_s390x.whl", hash = "sha256:b8d2f912928d426e8cfa396f7f3f8d29a59e6689c86dcca3c420730c1096322b", size = 389526 },
+    { url = "https://files.pythonhosted.org/packages/c6/76/7a41960e3fddae47fab43a28684d5da981401dffd88253de0944148654cb/rpds_py-2026.5.1-cp314-cp314t-manylinux_2_17_x86_64.manylinux2014_x86_64.whl", hash = "sha256:90f628283be835db980c941767d41c9a27b5239e54ba0a9c1335247e82406964", size = 376190 },
+    { url = "https://files.pythonhosted.org/packages/27/60/5f38dc70824fc6951b51d35377e577a3a3a4c81a6769cc5a2de25ebe0ad1/rpds_py-2026.5.1-cp314-cp314t-manylinux_2_31_riscv64.whl", hash = "sha256:1ebb2f0ab7e16132995a72de805170e0203df0c3dd22e1ef1cd1fdd90bd7a131", size = 383921 },
+    { url = "https://files.pythonhosted.org/packages/60/1a/d60a38caa1505f4b9483c3fbbde12c94e1079154f4f401a6da96f7e77621/rpds_py-2026.5.1-cp314-cp314t-manylinux_2_5_i686.manylinux1_i686.whl", hash = "sha256:f3df3d16ded76f1f8c9cdebd0e1ea55fdf4c23b812de189814da7cf229c22a81", size = 404766 },
+    { url = "https://files.pythonhosted.org/packages/87/ff/602fd3f174d6425f0bce05ad0dfbec0e96b38d0f7d08a79af5aa20083885/rpds_py-2026.5.1-cp314-cp314t-musllinux_1_2_aarch64.whl", hash = "sha256:9af8905b8f854990e40d5206aa5ac58d9b0fe0b7f351ff2bb086c20f6c8c6a47", size = 551343 },
+    { url = "https://files.pythonhosted.org/packages/b8/c1/1be13327acdbead3eca1fde03b6a34dbb011f1e864e217f0d32cc1779a7f/rpds_py-2026.5.1-cp314-cp314t-musllinux_1_2_i686.whl", hash = "sha256:036a36a87fb1cd3b214d11c4b3c4f7d2ddad933625dca1c900b56a057c07740a", size = 618502 },
+    { url = "https://files.pythonhosted.org/packages/f3/d7/afb49b49d7f2be8b7ba1a9f0977fa5168003437b93086726f066544e8351/rpds_py-2026.5.1-cp314-cp314t-musllinux_1_2_x86_64.whl", hash = "sha256:62ae3853454fe9ef283a03c96c2d835d39e84b14643a9d62c82ef0fb87d702ca", size = 581916 },
+    { url = "https://files.pythonhosted.org/packages/25/d1/dbef8c1f8a10f07beb62b5f054e20099fd9924b3ec001b8f0b6ac7813a85/rpds_py-2026.5.1-cp314-cp314t-win32.whl", hash = "sha256:6c3d771a46ec18b12af06ce36243a9a80b07a5d0515236332d90863ca8bb326a", size = 207855 },
+    { url = "https://files.pythonhosted.org/packages/2a/72/bfa4e61ab8e7dc1c8adf397e05e6cbdd4239357bd72b248d3de662f23915/rpds_py-2026.5.1-cp314-cp314t-win_amd64.whl", hash = "sha256:c93c629be4636cf54337bd5f06c104d55e42ced54d681f6fe21ae510a65116f6", size = 225422 },
+    { url = "https://files.pythonhosted.org/packages/27/3a/7b5da92b640f67b6717ccafc83cdd06bfa7ff2395c3685c68922bb54d703/rpds_py-2026.5.1-cp315-cp315-macosx_10_12_x86_64.whl", hash = "sha256:3574b55c604b8f75dacb007136508bbc0db406e626301778096a133327e7f2fb", size = 349576 },
+    { url = "https://files.pythonhosted.org/packages/d7/8a/2aafd7ad355a1bd48ca76e2262b74b15e6432b5a1efe150efd4d779cd55d/rpds_py-2026.5.1-cp315-cp315-macosx_11_0_arm64.whl", hash = "sha256:94068eb3ae6d43f5a786b7db96a406a34e6d5c24489feef32fd6e8946ea7b291", size = 343640 },
+    { url = "https://files.pythonhosted.org/packages/f7/7d/6c9523c1abbe840a1b7fba3c516d48e1d3487cc80fea4366c4071cf56784/rpds_py-2026.5.1-cp315-cp315-manylinux_2_17_aarch64.manylinux2014_aarch64.whl", hash = "sha256:f3a5b10e8ce894825f380a8f1b6444cf73c294dfea62afbb2d13e3a9e630cec1", size = 375322 },
+    { url = "https://files.pythonhosted.org/packages/5a/5d/0b7b03fb1dc509321f01de3149784ab773e34c8573022029af8076afcb9c/rpds_py-2026.5.1-cp315-cp315-manylinux_2_17_armv7l.manylinux2014_armv7l.whl", hash = "sha256:fc09f82e63d4bcd58149572f857a431bae851dc747e313c3b5bdf7abb907fda8", size = 379066 },
+    { url = "https://files.pythonhosted.org/packages/d7/e2/8ef6012999ebf1cb1c22f876d9ce5e63d960fd4631d2af3202d3f480aa25/rpds_py-2026.5.1-cp315-cp315-manylinux_2_17_ppc64le.manylinux2014_ppc64le.whl", hash = "sha256:e10464d17df3b582745c25cec695cb9558bca2cb6ddb631aee1787fc72c767b2", size = 494586 },
+    { url = "https://files.pythonhosted.org/packages/80/af/1eeb029bec67582c226b7809172207cd005073af4ebd906e65ff494f4983/rpds_py-2026.5.1-cp315-cp315-manylinux_2_17_s390x.manylinux2014_s390x.whl", hash = "sha256:ba05adbf15d994c38ec0b7ab32e858e5110c21e9009a00a86545fd220f84e038", size = 388415 },
+    { url = "https://files.pythonhosted.org/packages/18/23/ffbe10711c4d766c1cab0557d6906c074f795814863c67b351355d29354a/rpds_py-2026.5.1-cp315-cp315-manylinux_2_17_x86_64.manylinux2014_x86_64.whl", hash = "sha256:77c004fdc7b891967106f78ddfd7b076bfe6813c6139c6fff6aed3bcaa960b26", size = 372427 },
+    { url = "https://files.pythonhosted.org/packages/bd/3a/30ba4a6ad457e5b070c18d742a33fb77d8d922b565cc881f8a5313d63bfe/rpds_py-2026.5.1-cp315-cp315-manylinux_2_31_riscv64.whl", hash = "sha256:83bcf894486c9d78dd290d3c0124ff6dd8875d3025e2090a8ec49fcc37c55fdd", size = 383615 },
+    { url = "https://files.pythonhosted.org/packages/d3/69/62e242b53ce39c0814bd24e1a6e6eba6c92be716277745f317f9540a2e7b/rpds_py-2026.5.1-cp315-cp315-manylinux_2_5_i686.manylinux1_i686.whl", hash = "sha256:c3df104083952a0e0c6f10de33e440eabe98fb6317d23e1a58c68f6df08d01b9", size = 402786 },
+    { url = "https://files.pythonhosted.org/packages/38/c1/a770b9c186928a1ed0f7e6d7ae50e7f3950ed23e3f9e366dbc8e38cb55de/rpds_py-2026.5.1-cp315-cp315-musllinux_1_2_aarch64.whl", hash = "sha256:980450826cf22e133c57e0835070bdd0dd3f73b9b708c3ce223def2cb9469e14", size = 551583 },
+    { url = "https://files.pythonhosted.org/packages/21/7c/68e8579b95375b70d2a963103c42e705856cdb98569258bd807f4423891c/rpds_py-2026.5.1-cp315-cp315-musllinux_1_2_i686.whl", hash = "sha256:205dde846f24332ab0c1188699a043b8d165b79bb84529ce272c45048ff6be01", size = 616941 },
+    { url = "https://files.pythonhosted.org/packages/70/a1/a6135aed5730ff03ab957182259987ac11e55fb392a28dc6f0592048a280/rpds_py-2026.5.1-cp315-cp315-musllinux_1_2_x86_64.whl", hash = "sha256:3966b82dd563176396df030f3dd52a6e54cb69b718e95e78bd555ed3d1e0185d", size = 578349 },
+    { url = "https://files.pythonhosted.org/packages/09/6e/f24201a76a84e6c49d0bdfdfcb735210e21701e9b21c5bfc0ba497dd62f6/rpds_py-2026.5.1-cp315-cp315-win32.whl", hash = "sha256:7818f8d0a415be74d2be3590b0a1c1f463a642f4d0217e7d10602dceef5b79aa", size = 209922 },
+    { url = "https://files.pythonhosted.org/packages/9e/e4/966bc240bb0485fc265278f6de44d05834bf0b3618886e0b22e33d54c49a/rpds_py-2026.5.1-cp315-cp315-win_amd64.whl", hash = "sha256:b3cc20c0d800af78fd0fac68086e28c1856cec51ea528bb81ea851aa40d39325", size = 226003 },
+    { url = "https://files.pythonhosted.org/packages/5c/5c/a15a59269cd5e74472734516c73795c15eccfc841b3d4b0228c3f53f19d0/rpds_py-2026.5.1-cp315-cp315-win_arm64.whl", hash = "sha256:3609e9939a8a76cd904cf98a3f1f13b5dc7e150adeaee89e0ea09652ea213e16", size = 221245 },
+    { url = "https://files.pythonhosted.org/packages/e0/22/135ce03804e179a71ceb13be095deda4a279bc88f7a6b8fa161c5ad44e12/rpds_py-2026.5.1-cp315-cp315t-macosx_10_12_x86_64.whl", hash = "sha256:5d333a7127d4b307601ac37792bee01bb95c867cbfacf21b6375b804d6bbd723", size = 352015 },
+    { url = "https://files.pythonhosted.org/packages/3b/5f/f1f6d2652eb9d848f6eb369d8db83a2da6249bb49ad2c2a48f45d54538d3/rpds_py-2026.5.1-cp315-cp315t-macosx_11_0_arm64.whl", hash = "sha256:b5f077b44a4f7808520f66dae234988d867deb9aed9be5da057ce9ba831b2a41", size = 345016 },
+    { url = "https://files.pythonhosted.org/packages/88/66/b74182775691ea2290c99e52ac8d5db844e56fbec90ce421f107658c8314/rpds_py-2026.5.1-cp315-cp315t-manylinux_2_17_aarch64.manylinux2014_aarch64.whl", hash = "sha256:55d8f9b7b78c9538fc9e04e82ec0e888ff0c3cffcfad152c77e57cd09351a98a", size = 374775 },
+    { url = "https://files.pythonhosted.org/packages/ff/8f/15e5a61d9f0a43902d36561d4f07cae6ae9f4716be825159fd72717f33af/rpds_py-2026.5.1-cp315-cp315t-manylinux_2_17_armv7l.manylinux2014_armv7l.whl", hash = "sha256:e3a8ae58895ac107ed934a6bf51e5846f95c53b9b940c2c6d310838fd5846358", size = 380270 },
+    { url = "https://files.pythonhosted.org/packages/02/c3/f859b12763a80540cdf2af0f15b19904cf756a71d7bdd3f82ff3e5b1bbf9/rpds_py-2026.5.1-cp315-cp315t-manylinux_2_17_ppc64le.manylinux2014_ppc64le.whl", hash = "sha256:0957cf3c2b8632ec7aaebffebea8005b353cc2a237b6e2ae3c2cac0820704cfb", size = 495285 },
+    { url = "https://files.pythonhosted.org/packages/1c/c7/ff27c2ac8411d30b03b1829fd88cae8dad1a4d0da48dd25e57c4038042e6/rpds_py-2026.5.1-cp315-cp315t-manylinux_2_17_s390x.manylinux2014_s390x.whl", hash = "sha256:c396c1304de421050b3681ea70f371874b54d41b0151e96109758144c231e30b", size = 389581 },
+    { url = "https://files.pythonhosted.org/packages/6e/67/fe92ee32a6cc05c77228a2f8b1762e7124f386ec20ff83d0757b762d58d0/rpds_py-2026.5.1-cp315-cp315t-manylinux_2_17_x86_64.manylinux2014_x86_64.whl", hash = "sha256:aad1bff7f666b9598e573815affd666aac6a13a585dde336f843e33350c7fadc", size = 376041 },
+    { url = "https://files.pythonhosted.org/packages/f8/91/b4d6685c27aba55bd82f25b278be8237038117d05f9659a6213ad3408130/rpds_py-2026.5.1-cp315-cp315t-manylinux_2_31_riscv64.whl", hash = "sha256:656a042550878f12d45752452d47094b7cfe5ad1e9d7b87b5a22ad3ae5ff8015", size = 383946 },
+    { url = "https://files.pythonhosted.org/packages/bd/79/2c1d832a53c8e0f8e98fc970ec257b950fecd4f62be2ab7182b500a0cbc8/rpds_py-2026.5.1-cp315-cp315t-manylinux_2_5_i686.manylinux1_i686.whl", hash = "sha256:73c4bd4f70294737b5206a3e8e30ccadbf8a60301831c8ea23eec5dbeea1ecfa", size = 405526 },
+    { url = "https://files.pythonhosted.org/packages/78/c4/c98117b03c6a8581ab2c2dfccfe9a5ad82bd8128a3c28b46a6ad2d97c393/rpds_py-2026.5.1-cp315-cp315t-musllinux_1_2_aarch64.whl", hash = "sha256:43bca78665423cabae77146f2fe7ce55272b6c8d55d82cca83effd42c7e13972", size = 551165 },
+    { url = "https://files.pythonhosted.org/packages/3b/c1/bc479ca069200af730881b1bd525e3114b2b391a351509fcb1b772f28086/rpds_py-2026.5.1-cp315-cp315t-musllinux_1_2_i686.whl", hash = "sha256:42d0f20e85e549c870749d0e247f0c10d318a45b7e9676d575d2dcb04a1b2e66", size = 618778 },
+    { url = "https://files.pythonhosted.org/packages/77/65/38ab2f90df44c2febfb63cc10ced40763d9b4bc94d173e734528663fe7f5/rpds_py-2026.5.1-cp315-cp315t-musllinux_1_2_x86_64.whl", hash = "sha256:b1be5c35683684d5331b93600c210e8367c254683d8a6df6bd21bd2da3a334fb", size = 581839 },
+    { url = "https://files.pythonhosted.org/packages/15/2d/ce1f605fe036aadd460e5822e578c6c7ec3a860936cca37d6e0f299daa77/rpds_py-2026.5.1-cp315-cp315t-win32.whl", hash = "sha256:75808f6c38ce7749bb68cc2770161aae5045e6c6f6781a9782e74b93304399df", size = 207866 },
+    { url = "https://files.pythonhosted.org/packages/79/cb/966040123eb102371559746908ef2c9471f4d43e17ec9a645a2258dab64b/rpds_py-2026.5.1-cp315-cp315t-win_amd64.whl", hash = "sha256:90bd6630002a1c7f09e7843dd79f0d24f3d2897cc25a753480917865d14f15b3", size = 225441 },
+]
+
 [[package]]
 name = "ruff"
 version = "0.15.13"
@@ -1106,6 +1280,18 @@ wheels = [
     { url = "https://files.pythonhosted.org/packages/9b/36/9c015cd052fca743dae8cb2aeb16b551444787467db42ceab0fc968865af/ruff-0.15.13-py3-none-win_arm64.whl", hash = "sha256:2471da9bd1068c8c064b5fd9c0c4b6dddffd6369cb1cd68b29993b1709ff1b21", size = 11179336 },
 ]
 
+[[package]]
+name = "sqlite-vec"
+version = "0.1.9"
+source = { registry = "https://pypi.org/simple" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/68/85/9fad0045d8e7c8df3e0fa5a56c630e8e15ad6e5ca2e6106fceb666aa6638/sqlite_vec-0.1.9-py3-none-macosx_10_6_x86_64.whl", hash = "sha256:1b62a7f0a060d9475575d4e599bbf94a13d85af896bc1ce86ee80d1b5b48e5fb", size = 131171 },
+    { url = "https://files.pythonhosted.org/packages/a4/3d/3677e0cd2f92e5ebc43cd29fbf565b75582bff1ccfa0b8327c7508e1084f/sqlite_vec-0.1.9-py3-none-macosx_11_0_arm64.whl", hash = "sha256:1d52e30513bae4cc9778ddbf6145610434081be4c3afe57cd877893bad9f6b6c", size = 165434 },
+    { url = "https://files.pythonhosted.org/packages/00/d4/f2b936d3bdc38eadcbd2a87875815db36430fab0363182ba5d12cd8e0b51/sqlite_vec-0.1.9-py3-none-manylinux_2_17_aarch64.manylinux2014_aarch64.whl", hash = "sha256:4e921e592f24a5f9a18f590b6ddd530eb637e2d474e3b1972f9bbeb773aa3cb9", size = 160076 },
+    { url = "https://files.pythonhosted.org/packages/6f/ad/6afd073b0f817b3e03f9e37ad626ae341805891f23c74b5292818f49ac63/sqlite_vec-0.1.9-py3-none-manylinux_2_17_x86_64.manylinux2014_x86_64.manylinux1_x86_64.whl", hash = "sha256:1515727990b49e79bcaf75fdee2ffc7d461f8b66905013231251f1c8938e7786", size = 163388 },
+    { url = "https://files.pythonhosted.org/packages/42/89/81b2907cda14e566b9bf215e2ad82fc9b349edf07d2010756ffdb902f328/sqlite_vec-0.1.9-py3-none-win_amd64.whl", hash = "sha256:4a28dc12fa4b53d7b1dced22da2488fade444e96b5d16fd2d698cd670675cf32", size = 292804 },
+]
+
 [[package]]
 name = "starlette"
 version = "1.1.0"