# 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 | `562001af28d752c3a60d449c7ddd09f44fa9dc9a` |
| Worldtree HEAD message | `feat(#201): v0.29.0 — awaiting_llm_first_token SSE heartbeat` |
| Pinned on | 2026-05-26 |
| Pinned by | ratatoskr-dev (bump for #201 awaiting_llm_first_token SSE) |
| Worldtree version at pin | `v0.29.0` |

## Pin history

| Date | SHA | Version | Notable deltas consumed |
|---|---|---|---|
| 2026-05-26 | `562001a` | v0.29.0 | #201 — new SSE event `awaiting_llm_first_token` (heartbeat during BuildingPrompt → CallingLLM gap, default 5s interval) |
| 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:
   ```bash
   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/`:
   ```bash
   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/`:
   ```bash
   # 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. |