vh
78bfcadb9e
Spec pin moved da93ca7 (v0.28.0) → 562001a (v0.29.0); vendored conversation-api-spec.md + conversation_api.contract.md re-snapshotted. The only material delta is Worldtree #201's awaiting_llm_first_token SSE heartbeat — a top-level event (NOT a worker_phase extension, per INV-053's three-field stability) that fires at a configurable interval (default 5s) during the BuildingPrompt → CallingLLM gap. Wire layer (sse_client.py): - New `AwaitingLlmFirstToken` dataclass: sse_id / turn_id / elapsed_ms_since_building_prompt (server-authoritative monotonic) - Added to Event union + _envelope_for_type dispatch branch - Without this, ratatoskr would crash on any slow-first-token turn from a v0.29.0 server (unknown SSE event type → ValueError) TUI layer (tui.py): - Audit pipeline: per-event debug-pane line with elapsed in seconds - Live transcript indicator: first heartbeat mounts a Static ("awaiting first token · 5.0s"); subsequent heartbeats update it in place; any non-heartbeat event removes it (the gap closed) - Turn-summary line now carries heartbeat count - Indicator demoted via .awaiting-label CSS so it reads as ambient progress, not content Tests: 2 wire-layer (single + monotonic sequence) + 3 presenter (audit line shape, single-mount semantic, indicator removal on gap close). Suite: 318 passing.
108 lines
4.9 KiB
Markdown
108 lines
4.9 KiB
Markdown
# 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. |
|