vh/ratatoskr
1
0
Fork 0
Code Issues 4 Pull Requests Actions Packages Projects Releases Wiki Activity

feat(#18): affect.fetch — adopt bifrost 0.10.0 mandatory fetch (D1 prerequisite)

Browse Source 
bifrost 0.10.0's _supports_affect_plane (bifrost/affect.py:75-80) now requires a
callable fetch for the affect capability to advertise/dispatch at all (INV-012
strong-or-absent), so an emit-only store 400s on EVERY affect op — repinning past
the affect.fetch release (#12/#13) breaks our shipped affect plane until fetch
exists. Implement affect.fetch as a thin async wrapper over the existing get()
read seam, conformed verbatim to the reference InMemoryAffectStore.fetch:
{"found": False} or {"found": True, "snapshot": <verbatim>}, AffectInvalidArguments
on empty ids, opaque (INV-001 — never reads pad/valence).

This is the forced prerequisite for the #18 D1 composite (build_combined_app),
and a new Worldtree I/O point consumed (affect read-back over bifrost).

- Repin bifrost>=0.8.0 -> >=0.10.0 (uv lock: 0.8.0 -> 0.10.0)
- affect_store.py: add async fetch() over get()
- contract bifrost_affect_provider v1.2: fetch FN block + INV-010 (cap = supported+emit+fetch)
- tests: 3 fetch unit + parity_vs_reference_fetch through dispatch_affect_call
- suite 482 -> 486 green
This commit is contained in:
vh
2026-06-19 22:59:59 -07:00
parent a0c6c73ab9
commit ca6af6bdaa
5 changed files with 158 additions and 19 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/contracts/bifrost_affect_provider.contract.md
+68 -11
View File
@@ -10,7 +10,7 @@ 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."
- "bifrost>=0.10.0 is installed and exposes build_affect_app, build_combined_app, dispatch_affect_call, JwtVerifier, ConsumerRegistration, AffectInvalidArguments, AffectIdempotencyConflict, and REQUIRES a callable affect-store fetch for the affect capability (_supports_affect_plane, bifrost/affect.py:75-80, strong-or-absent) per 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)."
@@ -21,7 +21,9 @@ 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
invariant_id: "InMemoryAffectStore.emit" # the executable reference for the emit wire semantics we parity-prove against
- source: ~/development/bifrost/bifrost/reference_server/affect.py
invariant_id: "InMemoryAffectStore.fetch" # the executable reference for the affect.fetch read shape ({found, snapshot})
revisions:
- version: "1.1"
at: 2026-06-14
@@ -39,6 +41,22 @@ revisions:
- "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)"
- version: "1.2"
at: 2026-06-19
summary: "Adopt bifrost 0.10.0's mandatory affect.fetch (strong-or-absent, INV-012): _supports_affect_plane now requires a callable fetch for the affect cap to advertise/dispatch at all, so an emit-only store 400s on EVERY affect op. Promote the sync get() read seam to an async wire fetch() returning bifrost's {found, snapshot} shape; conform to the reference InMemoryAffectStore.fetch. affect.fetch leaves 'reserved'. Forced prerequisite of the #18 D1 composite (build_combined_app)."
delta:
ADDED:
- "fetch() function block (async wire verb; mirrors reference InMemoryAffectStore.fetch)"
- "INV-010 (affect cap = affect_supported + emit + fetch, strong-or-absent)"
- "parity_vs_reference_fetch test"
- "InMemoryAffectStore.fetch external invariant"
MODIFIED:
- "INV-005 — cross-refs INV-010 (the affect cap now requires fetch present too)"
- "assumptions — bifrost pin >=0.10.0 (build_combined_app + mandatory affect.fetch)"
- "get() BRIEF — the sync read seam fetch() wraps (no longer 'affect.fetch RESERVED')"
- "Data flow — add the fetch read-back path"
REMOVED:
- "the 'affect.fetch / affect:read RESERVED in v1' out-of-scope line"
---
## Context
@@ -75,13 +93,19 @@ affect; we only persist and round-trip it.** We run no affect logic.
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
- **Out (emit):** `{"stored": True}` ack (the library wraps it with the transport
`{"success": True}` envelope).
- **Fetch (read-back):** Worldtree's `affect.fetch` → `POST /bifrost/affect-call`
→ `store.fetch(agent_id=..., end_user_id=...)` → `{"found": False}` or
`{"found": True, "snapshot": <verbatim snapshot>}` (the library wraps it via
`affect_result(**fetched)`). The snapshot is returned opaque/verbatim — `fetch`
never reads `pad` / `valence` / `persona_baselines` / `emitted_at` (INV-001).
**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.
**Async surface:** `emit` and `fetch` are `async def` (the bifrost consumer
Protocol awaits them); `open_affect_store` and `get` are sync (no I/O await —
`get` is the read-back seam `fetch` wraps). The `FN` lines below omit the
`async` keyword only because the contract grammar's `FN <name>` form has no
async marker.
## Invariants
@@ -113,7 +137,7 @@ grammar's `FN <name>` form has no async marker.
`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).
in-memory default). See INV-010 for the full affect-capability surface.
- **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
@@ -137,6 +161,13 @@ grammar's `FN <name>` form has no async marker.
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)`.
- **INV-010** [hard]: **The affect capability is `affect_supported` + `emit` +
`fetch`, strong-or-absent** (bifrost ≥0.10.0 `_supports_affect_plane`,
`bifrost/affect.py:75-80`; the INV-012 no-degraded-path rule). bifrost gates
EVERY affect op (emit included) on all three being present, so a store missing
a callable `fetch` is rejected with `affect.unsupported_capability` and the
handshake never advertises `affect`. We therefore implement `fetch` fully (not
a stub) — the canonical surface admits no emit-only affect store.
## Concurrency
@@ -186,8 +217,10 @@ already have rejected a malformed envelope.
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.
- **`affect:read` scope enforcement / persona-baseline rehydrate shaping**: the
library owns scope auth (`affect:read` for fetch); `fetch` returns the stored
blob verbatim — any richer rehydrate shaping beyond a snapshot round-trip is
Worldtree's concern, not the store's.
- **`idempotency_class`**: accepted and ignored (affect.* uses a single
short-retry class).
- **WAL/concurrency hardening, deployment DB path, auth-key provisioning**:
@@ -254,7 +287,7 @@ TESTS:
```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.
BRIEF: Sync read-back seam returning the verbatim stored snapshot (or None). The async wire verb fetch() wraps this; tests / the D2 read route / rehydrate-seed also use it directly.
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 = ?
@@ -264,6 +297,30 @@ TESTS:
get_after_emit [happy]: returns the emitted snapshot, deserialized equal
```
```contract
FN fetch(self, agent_id: str, end_user_id: str) -> dict
BRIEF: Wire affect.fetch read handler — return the stored snapshot in bifrost's {found, snapshot} shape, conduit-opaque. Mirrors the reference InMemoryAffectStore.fetch verbatim (INV-010 strong-or-absent: this method MUST exist for the affect cap to advertise/dispatch).
PRE: [PRE-001 hard] agent_id and end_user_id are non-empty strings -- else raise AffectInvalidArguments (mirrors reference; the wire validates the envelope first, this is belt-and-suspenders)
POST: [POST-001 return_value] returns {"found": False} when no snapshot for the key -- (the library wraps via affect_result(**fetched))
POST: [POST-002 return_value] returns {"found": True, "snapshot": <verbatim snapshot>} when present; snapshot deserializes equal to the emitted snapshot -- (INV-003)
POST: [POST-003 return_value] never reads pad/valence/persona_baselines/emitted_at — returns the whole blob opaque -- (INV-001)
ERROR_ROUTING:
AffectInvalidArguments:
local_handling: raise on missing/empty agent_id or end_user_id
flow_control: abort
state_recovery: none (read-only; no state touched)
STEPS:
1. [setup, flexibility=prescriptive] IF agent_id/end_user_id missing or not non-empty str: RAISE AffectInvalidArguments
2. [sequential] SET snap = self.get(agent_id, end_user_id) -- the existing sync read seam; whole-blob json.loads, no field reads (INV-001)
3. [branch] IF snap is None: RETURN {"found": False}
4. [cleanup] RETURN {"found": True, "snapshot": snap}
TESTS:
fetch_absent [boundary]: no row for key → {"found": False}
fetch_after_emit [happy,tracer]: emit then fetch → {"found": True, "snapshot": equals the emitted snapshot}
fetch_missing_key [adversarial]: empty/missing agent_id or end_user_id → raises AffectInvalidArguments
parity_vs_reference_fetch [scenario]: drive identical affect.fetch envelopes (found + not-found) through dispatch_affect_call against InMemoryAffectStore and RatatoskrAffectStore → (status, body) tuples agree (#195)
```
```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.