vh
9703eb2b6b
Worldtree Conversation API debug TUI. Multi-pane observability dashboard: chat transcript + persona/Vili affect log + tool events + admin events + Bifrost state + tool inventory + (opt-in) raw server log. Design locked at docs/design-brief.md (originated as brokkr-smithy/docs/ratatoskr-design-brief.md). Operator-locked decisions: - Textual application-shell framework (multi-pane dashboard, not REPL). - Separate repo + separate dev team (no Worldtree-source imports). - httpx-sse for SSE consumption (reference Python SSE-resume impl). - Triple version-skew mitigation: spec-pin in pyproject.toml + recorded SSE snapshot tests + conformance smoke. Initial pin: Worldtree v0.19.0 at 55101e909abcd2219833266b6f905c5bc956e0f0. - Persona pane: label-don't-refuse PII posture. - Server-log pane: opt-in via --server-log <path>. - Two-stage Ctrl-C (cancel then exit). - Markdown rendering default-on; --raw opt-out. In the box: - docs/design-brief.md — the locked design with full rationale. - docs/SPEC-PIN.md — Worldtree spec pin + bump procedure. - docs/conversation-api-spec.md + docs/conversation_api.contract.md — vendored Worldtree spec snapshots at the pinned SHA. - pyproject.toml — Python 3.12, hatchling, uv-managed, deps locked. - src/ratatoskr/ — stub package (cli.py raises NotImplementedError). - tests/test_no_worldtree_imports.py — boundary smoke test PASSING. - tests/snapshots/README.md — recording convention for SSE snapshot tests. Not in the box yet: - Gitea remote (operator/infra-ops to register at vh/ratatoskr). - Implementation — the dev team owns this; design brief is the spec. Origin: althing thread 01KS3R34XD3N6HMK91VXESHGW7 (worldtree-dev → brokkr-smithy-dev, 2026-05-20). Volva consulted via thread 01KS3VF6W33N3V5FNMGQ91YNVD.
100 lines
4.4 KiB
Markdown
100 lines
4.4 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 | `55101e909abcd2219833266b6f905c5bc956e0f0` |
|
|
| Worldtree HEAD message | `memory: snapshot — #177 Vili v1 + persona async-decouple shipped as v0.19.0` |
|
|
| Pinned on | 2026-05-20 |
|
|
| Pinned by | brokkr-smithy-dev (initial scaffold) |
|
|
| Worldtree version at pin | `v0.19.0` |
|
|
|
|
## 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. |
|