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:
+24
-24
@@ -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.
|
||||
|
||||
Reference in New Issue
Block a user