pin: re-pin to Worldtree's FROZEN v1 surface (OpenAPI 2.2.0 + SSE schema)

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.
This commit is contained in:
vh
2026-06-30 15:28:52 -07:00
parent 93e4176346
commit b798068932
7 changed files with 8357 additions and 35 deletions
+24 -24
View File
@@ -23,14 +23,15 @@ anchors against the frozen machine-readable artifacts, NOT the prose markdown:
| Conversation SSE events | `conversation-api-sse-events.schema.json` (sha `9deeebf4…`) — **11 discriminated event types** | **client** |
| Bifrost wire (consumer protocol) | wire **v0.6** STABLE/FROZEN (`bifrost==1.0.0`) — memory + affect planes | **provider** (Worldtree dispatches into us) |
> **Pin drift (finding P-1).** Ratatoskr vendors the **prose markdown**
> (`docs/conversation-api-spec.md`), which is **byte-identical to live
> Worldtree's markdown** but frozen at v0.35.16-era content (last WT edit
> 2026-05-31). The markdown does **not** document the b2 surface: 7 endpoints
> (below), the 409/503 on messages-POST (#331), the unified error envelope
> (#328), or the SSE schema. **Worldtree's authoritative v1 truth is now the
> OpenAPI 2.2.0 + SSE schema JSON**, which ratatoskr does not vendor. See
> § Pin remediation.
> **Pin drift (finding P-1) — REMEDIATED 2026-06-30.** Ratatoskr formerly
> vendored only the **prose markdown** (`docs/conversation-api-spec.md`), which
> is byte-identical to live Worldtree's but frozen at v0.35.16-era content (last
> WT edit 2026-05-31) and does **not** document the b2 surface (7 endpoints
> below, the 409/503 on messages-POST #331, the unified error envelope #328, the
> SSE schema). Remediated: the **OpenAPI 2.2.0 + SSE-schema JSON are now vendored
> and pinned** (`.corviduo-canonicals.toml` → `canonical_drift.py` gate); the
> prose markdown is the `tolerate_drift` reference. Spec pin advanced to
> 5810a26 (v1.0.0b2). See § Pin remediation.
**7 endpoints new in b2 OpenAPI, absent from our vendored markdown:**
`/admin/keys/bulk`, `/admin/persona/archive`, `/admin/persona/erase`,
@@ -219,18 +220,16 @@ starts exercising them.
---
## Pin remediation (finding P-1)
## Pin remediation (finding P-1) — DONE 2026-06-30
The vendored prose markdown is stale against the frozen OpenAPI 2.2.0. Options
(operator-owned; see § Open decision item 2):
- **Re-pin to the frozen machine-readable artifacts.** Vendor
`conversation-api-openapi.json` (2.2.0) + `conversation-api-sse-events.schema.json`,
add `.corviduo-canonicals.toml` pins (drift-checkable via `canonical_drift.py`),
keep the markdown as prose reference. Makes this coverage map reproducible
against a frozen, diffable target — the OpenAPI is the v1 truth.
- **Re-vendor the markdown only.** Near-no-op (content identical); leaves the
b2 surface undocumented in our pin. Not recommended.
Re-pinned to the frozen machine-readable artifacts (the chosen option):
`conversation-api-openapi.json` (2.2.0) + `conversation-api-sse-events.schema.json`
are vendored under `docs/` and pinned in `.corviduo-canonicals.toml`
(`worldtree-conversation-api-openapi-v2`, `-sse-events-v1`), drift-gated by
`canonical_drift.py`. The prose markdown stays as a `tolerate_drift` reference
(`-spec-v1`). `pyproject.toml` spec pin advanced f1b59f8 → 5810a26 (v1.0.0b2);
`docs/SPEC-PIN.md` records the bump. This map now audits a frozen, diffable
target — re-running the audit is a `canonical_drift.py` check away.
---
@@ -240,8 +239,9 @@ The vendored prose markdown is stale against the frozen OpenAPI 2.2.0. Options
frozen I/O point classified, zero unaccounted; NOT feature-complete client.
The ⬜-vs-🚫 line for the 11 formerly-pending rows is locked above (§
Scope-resolution record).
2. **Pin remediation (P-1) — PENDING.** Re-pin to the frozen OpenAPI 2.2.0 +
SSE-schema JSON (recommended; drift-checkable via `canonical_drift.py`) vs
re-vendor markdown only (near-no-op). Adds vendored artifacts + a
canonical-sync pin → deferred to an explicit operator nod (substrate change
with CI-gating reach).
2. **Pin remediation (P-1) — RESOLVED 2026-06-30 (re-pin to machine-readable).**
Vendored `conversation-api-openapi.json` (2.2.0) + `conversation-api-sse-events.schema.json`
as the authoritative drift gates (pinned in `.corviduo-canonicals.toml`,
`canonical_drift.py` green); prose markdown kept as `tolerate_drift`
reference. Spec pin advanced f1b59f8 (v0.35.16) → 5810a26 (v1.0.0b2). This
map now audits against a frozen, diffable target.