vh
b798068932
v1 coverage-audit remediation P-1: vendor the authoritative machine- readable artifacts and pin them for drift-checking, advancing the spec pin from v0.35.16 (f1b59f8) to v1.0.0b2 (5810a26). - Vendor docs/conversation-api-openapi.json (OpenAPI 2.2.0, 40 path- groups) + docs/conversation-api-sse-events.schema.json (11 events). - Pin all three Conversation-API artifacts in .corviduo-canonicals.toml: OpenAPI + SSE schema as strict drift gates (canonical_drift.py), the prose markdown as tolerate_drift reference. Drift check green (10/10). - pyproject: worldtree-spec-rev -> 5810a26, worldtree-version -> v1.0.0b2 (was stale at v0.29.0), pinned-on -> 2026-06-30. - SPEC-PIN.md: current-pin table + history row + vendored-artifacts list. - coverage-map.md: P-1 marked remediated; the map now audits a frozen, diffable target. The prose markdown is byte-identical to v0.35.16 (last WT edit 2026-05-31); the b2 surface lives only in the OpenAPI. No client- facing code change (the b2 409/503 + unified error envelope were already consumed in v0.18.3/.4) -> pin-only, no version bump.
116 lines
7.3 KiB
Markdown
116 lines
7.3 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 | `5810a26b38a5ea6630892f9a39756f57c5b7b41e` |
|
|
| Worldtree HEAD message | `memory: snapshot — v1.0.0b2 shipped complete (demo + personal green); consumer loop closed` |
|
|
| Pinned on | 2026-06-30 |
|
|
| Pinned by | ratatoskr-dev (v1 coverage-audit — re-pin to the FROZEN OpenAPI 2.2.0 + SSE schema) |
|
|
| Worldtree version at pin | `v1.0.0b2` |
|
|
|
|
## Pin history
|
|
|
|
| Date | SHA | Version | Notable deltas consumed |
|
|
|---|---|---|---|
|
|
| 2026-06-30 | `5810a26` | v1.0.0b2 | **Re-pin to Worldtree's FROZEN v1 surface (#326), as part of the v1 coverage-audit.** Vendored the machine-readable artifacts — `conversation-api-openapi.json` (OpenAPI **2.2.0**, 40 path-groups) + `conversation-api-sse-events.schema.json` (11 events) — now the **authoritative drift gates** (pinned in `.corviduo-canonicals.toml`, CI-checked by `canonical_drift.py`). The prose `conversation-api-spec.md` is **byte-identical** to the v0.35.16 pin (last WT markdown edit 2026-05-31), kept as the human reference (`tolerate_drift`). b2 deltas already consumed in code: 409/503 eager turn-launch statuses (#331, v0.18.3/.4) + the unified error envelope (#328). 7 endpoints documented only in the OpenAPI, not the prose, all classified in `docs/coverage-map.md`: `admin/keys/bulk`, `admin/persona/{archive,erase}`, `admin/usage`, `embed`, `judgments`, `me/usage`. No client-breaking change — `pin:`-only, no version bump. |
|
|
| 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
|
|
|
|
**Authoritative (FROZEN, machine-readable — the drift gates):**
|
|
|
|
- `docs/conversation-api-openapi.json` — copy of `Worldtree/docs/conversation-api-openapi.json` (OpenAPI `info.version` **2.2.0**). The frozen v1 REST wire (40 path-groups). Pinned `worldtree-conversation-api-openapi-v2` in `.corviduo-canonicals.toml`; drift gated by `canonical_drift.py`.
|
|
- `docs/conversation-api-sse-events.schema.json` — copy of `Worldtree/docs/conversation-api-sse-events.schema.json`. The frozen SSE event schema (11 discriminated event types). Pinned `worldtree-conversation-api-sse-events-v1`.
|
|
|
|
**Reference (prose; allowed to lag — `tolerate_drift`):**
|
|
|
|
- `docs/conversation-api-spec.md` — copy of `Worldtree/docs/conversation-api-spec.md` at the pinned SHA. The **client-facing prose narrative**. Byte-frozen at v0.35.16-era content (last WT edit 2026-05-31); the OpenAPI/SSE JSON above are the source of truth where they diverge. Pinned `worldtree-conversation-api-spec-v1` (tolerate_drift).
|
|
- `docs/conversation_api.contract.md` — copy of `Worldtree/docs/contracts/conversation_api.contract.md` at the pinned SHA (byte-identical at b2 — server contract unchanged since the v0.35.16 pin). 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. Not in the canonical manifest (reference-only).
|
|
|
|
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. |
|