Files

T

vh 9703eb2b6b init: seed Ratatoskr from corviduo-project-template + ship v0 scaffold

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.

2026-05-20 20:38:22 -07:00

4.4 KiB

Raw 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	`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:

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.4 KiB Raw Blame History