F5: cross-rung format contract + round-trip (#14) #15

2026-06-11T06:07:30Z

benstull commented

2026-06-11 06:07:30 +00:00

Summary

Implements Feature #14 (F5) per the graduated spec vscode-cowriting-plugin-content/specs/coauthoring-cross-rung-format.md — the .threads/ sidecar graduates from the editor's private shape into the published cross-rung contract.

SLICE-1 — contract published: normative prose (specs/coauthoring-sidecar-contract.md v1.0, content repo, INV-14) + JSON Schema (schemas/coauthoring-sidecar.schema.json) + rung-neutral validator (scripts/validate-sidecar.mjs, ajv dev-only); schema wired into the unit suite (drift fails CI).
SLICE-2 — writer conformance: Provenance.email + agent.onBehalfOf (git's identity model, fork c); serializer unknown-field preservation at every level (INV-15); isNewerMajor + store write-refusal backstop; VersionGuard — newer-major sidecars render best-effort, warn once, write nothing (INV-16, PUC-4); currentAuthor() populates email from workspace git config, fail-open.
SLICE-3 — mergeArtifacts: pure 2-way union-by-id, deterministic symmetric tie-breaks, every resolved divergence surfaced in conflicts (INV-17); throws on differing majors.
SLICE-4 — scripts/crossrung-reply.mjs Gitea-rung stand-in (independent contract implementation; byte-fidelity unit test is the drift tripwire) + host E2E: editor thread → stand-in reply → external change → reply renders at the re-resolved anchor (PUC-2); newer-major warning + untouched bytes (PUC-4).
SLICE-5 — README cross-rung section.

All additive — schemaVersion stays 1; existing sidecars unchanged.

Test plan

npm run typecheck clean
npx vitest run — 98 passed (schema validation, identity, INV-15 preservation, INV-16 refusal, merge cases, stand-in byte-fidelity)
npm run test:e2e — 18 + 3 passing (incl. F5 round-trip + fail-safe)

Closes #14

🤖 Generated with Claude Code

## Summary Implements Feature #14 (F5) per the graduated spec `vscode-cowriting-plugin-content/specs/coauthoring-cross-rung-format.md` — the `.threads/` sidecar graduates from the editor's private shape into the published cross-rung contract. - **SLICE-1** — contract published: normative prose (`specs/coauthoring-sidecar-contract.md` v1.0, content repo, INV-14) + JSON Schema (`schemas/coauthoring-sidecar.schema.json`) + rung-neutral validator (`scripts/validate-sidecar.mjs`, ajv dev-only); schema wired into the unit suite (drift fails CI). - **SLICE-2** — writer conformance: `Provenance.email` + `agent.onBehalfOf` (git's identity model, fork c); serializer unknown-field preservation at every level (INV-15); `isNewerMajor` + store write-refusal backstop; `VersionGuard` — newer-major sidecars render best-effort, warn once, write nothing (INV-16, PUC-4); `currentAuthor()` populates email from workspace git config, fail-open. - **SLICE-3** — `mergeArtifacts`: pure 2-way union-by-id, deterministic symmetric tie-breaks, every resolved divergence surfaced in `conflicts` (INV-17); throws on differing majors. - **SLICE-4** — `scripts/crossrung-reply.mjs` Gitea-rung stand-in (independent contract implementation; byte-fidelity unit test is the drift tripwire) + host E2E: editor thread → stand-in reply → external change → reply renders at the re-resolved anchor (PUC-2); newer-major warning + untouched bytes (PUC-4). - **SLICE-5** — README cross-rung section. All additive — `schemaVersion` stays 1; existing sidecars unchanged. ## Test plan - [x] `npm run typecheck` clean - [x] `npx vitest run` — 98 passed (schema validation, identity, INV-15 preservation, INV-16 refusal, merge cases, stand-in byte-fidelity) - [x] `npm run test:e2e` — 18 + 3 passing (incl. F5 round-trip + fail-safe) Closes #14 🤖 Generated with [Claude Code](https://claude.com/claude-code)

benstull added 11 commits 2026-06-11 06:07:31 +00:00

chore: add ajv devDependency + F5 implementation plan (F5 SLICE-1, #14 ) 0ddeaba5a6

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

feat: publish coauthoring-sidecar JSON Schema + rung-neutral validator (F5 SLICE-1, PUC-5, #14 ) 7c4d3ed79f

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

feat: Provenance gains email + agent.onBehalfOf — cross-rung identity (F5 SLICE-2, #14 ) da172a3117

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

feat: serializer preserves unknown fields at every level (F5 SLICE-2, INV-15, #14 ) a6b16f0d9c

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

feat: isNewerMajor + store write-refusal backstop (F5 SLICE-2, INV-16, #14 ) 746071a585

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

feat: currentAuthor() carries git user.email — fail-open identity (F5 SLICE-2, #14 ) ef4ec8dbe9

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

feat: VersionGuard — newer-major sidecars are read-only with one warning (F5 SLICE-2, INV-16/PUC-4, #14 ) ef7d9403c0

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

feat: mergeArtifacts — deterministic union-by-id with surfaced conflicts (F5 SLICE-3, INV-17, #14 ) 452f5d193f

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

feat: crossrung-reply stand-in writer — validate, append, stable-serialize (F5 SLICE-4, #14 ) e0c127c4d9

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

test: host E2E — crossrung round-trip + newer-major fail-safe (F5 SLICE-4, PUC-2/PUC-4, #14 ) 5de59fde11

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

docs: cross-rung contract pointers in README (F5 SLICE-5, #14 ) abb9c882a4

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

benstull merged commit 4651410136 into main

2026-06-11 06:07:39 +00:00

Sign in to join this conversation.

1 Participants

Notifications

Due Date

No due date set.

Dependencies

No dependencies set.

Reference: benstull/vscode-cowriting-plugin#15