Files

T

vh 92aa05c688 feat(sse,tui): bump spec pin to v0.28.0 + AffectUpdate event (v0.11.0)

Spec pin moved 55101e9 (v0.19.0) → da93ca7 (v0.28.0); vendored
conversation-api-spec.md + conversation_api.contract.md re-snapshotted
from Worldtree at the new SHA. The only material delta consumed in
this bump is Worldtree #204's affect_update SSE event surface.

Wire layer (sse_client.py):
- New AffectUpdate dataclass: sse_id / status / turn_id / snapshot
  (snapshot is None for status="scheduled")
- Added to Event union + _envelope_for_type dispatch branch
- Without this, ratatoskr would crash on any persona-enabled turn
  from a v0.28.0 server (unknown SSE event type → ValueError)

TUI layer (tui.py):
- AffectUpdate routes through the v0.10.0 audit pipeline only — one
  debug-pane line per arrival with dominant_emotion + PAD for
  status="current", lightweight status+turn_id for status="scheduled"
- No transcript / tools / thinking pane writes — the persona UX shape
  (Persona TabPane vs sticky header line) is deferred to a separate
  bump pending operator direction

Tests: 2 new wire-layer tests for current+scheduled parsing + 2 new
presenter audit tests for routing and audit-line shape.

Not yet consumed: GET /agents/{id}/persona_state endpoint (step 2 of
the integration plan).

2026-05-25 18:48:44 -07:00

4.7 KiB

Raw Permalink Blame History

Worldtree spec pin

Ratatoskr is built against a specific Worldtree commit. This file documents the pin, the vendored artifacts, and the bump procedure.

Current pin

Field	Value
Worldtree git SHA	`da93ca7cf613f1dc229a7a44d07fc1d7efc78e25`
Worldtree HEAD message	`feat(#204): v0.28.0 — persona-state observability surface`
Pinned on	2026-05-25
Pinned by	ratatoskr-dev (bump for #204 affect_update SSE)
Worldtree version at pin	`v0.28.0`

Pin history

Date	SHA	Version	Notable deltas consumed
2026-05-25	`da93ca7`	v0.28.0	#204 — new SSE event `affect_update` (current/scheduled), new endpoint `GET /agents/{id}/persona_state` (not yet consumed), auth-model doc edits
2026-05-20	`55101e9`	v0.19.0	initial scaffold pin

Vendored artifacts

docs/conversation-api-spec.md — copy of Worldtree/docs/conversation-api-spec.md at the pinned SHA. This is the client-facing interface contract Ratatoskr is built against.
docs/conversation_api.contract.md — copy of Worldtree/docs/contracts/conversation_api.contract.md at the pinned SHA. The server-side contract including INV-001..INV-052 and amendments. Useful for understanding load-bearing server invariants (e.g., INV-014 turn-id-public, INV-046 admin-events-envelope-stable, INV-049 admin-events-pii-discipline) when designing client behavior against them.

Both files are vendored — they reflect Worldtree at the pinned SHA, not the live ~/development/Worldtree checkout. Update them only when bumping the pin (see procedure below).

Why pin?

Ratatoskr's dev team is decoupled from Worldtree's dev team. The spec that Ratatoskr is built against can drift from live Worldtree without either team noticing. Pinning makes the version-mismatch explicit:

The pin SHA is what we built against.
When live Worldtree advances, our pin is stale until we explicitly bump.
A bump is a conscious action that triggers the re-recording of snapshot tests and a manual review of spec deltas.

Bump procedure

When you bump the pin, do all five steps in one commit:

Pick the new target SHA. Usually live Worldtree HEAD. Run:
```
git -C ~/development/Worldtree rev-parse HEAD
git -C ~/development/Worldtree log --oneline <old-sha>..HEAD -- docs/conversation-api-spec.md docs/contracts/conversation_api.contract.md
```
The second command shows every change to the spec files since the old pin. If it returns nothing, the spec hasn't changed and the bump is trivial (just update the SHA in this file + pyproject.toml).

Re-vendor the spec files. From ~/development/ratatoskr/:

cp ~/development/Worldtree/docs/conversation-api-spec.md docs/conversation-api-spec.md
cp ~/development/Worldtree/docs/contracts/conversation_api.contract.md docs/conversation_api.contract.md

Diff-review the vendored files. Look for breaking changes — renamed endpoints, changed SSE event shapes, removed fields, new required parameters, new invariants that affect client behavior, etc. Anything that breaks Ratatoskr should result in a corresponding code change in this commit OR a deliberate "don't support new feature yet" decision recorded in persistent-memory.md.

Re-record SSE snapshot tests. From ~/development/ratatoskr/:

# Boot a local Worldtree at the new SHA
( cd ~/development/Worldtree && python -m core.conversation_api ) &
# Re-record (specific command depends on the snapshot harness — TBD by dev team)
uv run pytest --record-snapshots tests/snapshots/

Update pyproject.toml and this file. Bump worldtree-spec-rev in pyproject.toml; update the "Current pin" table above with the new SHA, the new HEAD message, today's date, and your handle.

Commit with a message of this shape:

pin: bump Worldtree spec to <short-sha>

<summary of material spec deltas, or "no client-facing changes" if trivial>

- <bullet for each notable change that affected Ratatoskr code>

Conformance smoke check

Independent of the pin, Ratatoskr's CI runs a conformance smoke test that boots Worldtree (via Docker compose) and runs a one-turn happy path. This catches integration-level drift that snapshot replay misses — e.g., a Worldtree config change that breaks the auth handshake or the SSE framing without changing the spec docs.

If the smoke test fails while the snapshot tests pass, the discovery should route to worldtree-dev via althing (the spec didn't change but Worldtree's behavior did — that's a worldtree-side concern).

History

Date	SHA	Note
2026-05-20	`55101e9`	Initial pin (scaffold). Worldtree v0.19.0 — #177 Vili v1 + persona async-decouple.

4.7 KiB Raw Permalink Blame History