ratatoskr/docs/SPEC-PIN.md

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	f1b59f8cd6fe41e497d0be9dad9d3110451f0d9a
Worldtree HEAD message	Merge #299: adopt bifrost v0.6 memory scope wire (scope_any/scope_all)
Pinned on	2026-06-17
Pinned by	ratatoskr-dev (bump for #297/#298 — cold recall closed end-to-end)
Worldtree version at pin	v0.35.16

Pin history

Date	SHA	Version	Notable deltas consumed
2026-06-17	f1b59f8	v0.35.16	#297 + #298/#299 — Worldtree adopts the bifrost v0.6 scope wire (emits scope_any/scope_all) + client-side per-scope-value union recall. With our v0.17.6 provider this closes cold cross-session recall end-to-end. Catch-up bump (v0.29.0→v0.35.16). Intervening client-facing deltas reviewed, none break our consumer: #211 agent rename (saga→echo, actor→mask — slugs only); #245 end_user_id persistence + memory-scope resolver; #187/#188/#219 Tier-3 define/PATCH policy (additive); bifrost binding field + ephemeral_does_not_accept_bifrost 422 now documented (the #17 surface). Error codes stable; no ratatoskr code change required.
2026-05-25	da93ca7	v0.28.0	#204 — new SSE event affect_update (current/scheduled), new endpoint GET /agents/{id}/persona_state, 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:

1. 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).

2. 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
   

3. 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.

4. 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/
   

5. 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.

6. 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.