diff --git a/README.md b/README.md index 99c5805..038c59e 100644 --- a/README.md +++ b/README.md @@ -98,6 +98,39 @@ CI. Design: `vscode-cowriting-plugin-content/specs/coauthoring-propose-accept.md`. Live smoke: [`docs/MANUAL-SMOKE-F4.md`](docs/MANUAL-SMOKE-F4.md). +## F5 — Cross-rung format + round-trip (Feature #14) + +The `.threads/` sidecar is the **published cross-rung contract**: any rung of +the ladder (this editor → Gitea substrate → rfc-app) reads and writes the same +record per the contract; git push/pull is the transport, no re-homing ever. + +- **Normative contract (INV-14):** + `vscode-cowriting-plugin-content/specs/coauthoring-sidecar-contract.md` — + format changes land there first, then schema, then code. +- **Machine-checkable half:** + [`schemas/coauthoring-sidecar.schema.json`](schemas/coauthoring-sidecar.schema.json); + validate any sidecar from any rung with + `node scripts/validate-sidecar.mjs `. The unit suite validates every + serialized artifact — contract drift fails CI. +- **Identity crosses rungs:** `Provenance.email` (git's own join key — + populated from the workspace git config when available) and + `agent.onBehalfOf` (who the machine acted for). +- **Writers preserve unknown fields (INV-15):** rewriting a sidecar never + destroys another rung's data — unknown keys survive, after known keys, + sorted. +- **Newer-major sidecars are read-only (INV-16):** the editor renders what it + understands, warns once, and writes nothing (the store refuses as a + backstop). +- **Deterministic merge (INV-17):** `src/mergeArtifacts.ts` — union-by-id, + documented tie-breaks, every resolved divergence surfaced in `conflicts`. +- **The round-trip is proven, not asserted:** + [`scripts/crossrung-reply.mjs`](scripts/crossrung-reply.mjs) is a + self-contained conforming foreign writer (the Gitea-rung stand-in); host E2E + drives editor-thread → stand-in reply → external-change → the reply renders + in the thread. + +Design: `vscode-cowriting-plugin-content/specs/coauthoring-cross-rung-format.md`. + ## Develop - `npm run watch` — rebuild on change.