vscode-cowriting-plugin-content/specs/coauthoring-sidecar-contract.md

---
status: living
---
# Coauthoring Sidecar — the Cross-Rung Contract (v1.0)

| | |
| --- | --- |
| **Author(s)** | Ben Stull (with Claude) |
| **Status** | `living` — this is a standing contract, not a one-shot Solution Design |
| **Contract version** | v1.0 · `schemaVersion: 1` |
| **Machine-checkable half** | `vscode-cowriting-plugin/schemas/coauthoring-sidecar.schema.json` (+ `scripts/validate-sidecar.mjs`) |
| **Reference implementation** | `vscode-cowriting-plugin/src/model.ts` (serializer), `src/mergeArtifacts.ts` (merge), `scripts/crossrung-reply.mjs` (conforming foreign writer) |
| **Source artifacts** | Solution Design `coauthoring-cross-rung-format.md` (F5, Feature `benstull/vscode-cowriting-plugin#14`) · supersedes the format sections (§6.3) of `coauthoring-inner-loop.md`, `coauthoring-attribution.md`, `coauthoring-propose-accept.md` as the format reference |

**This document is canonical (INV-14).** Format changes land here first, then in
the JSON Schema, then in code — documentation-leads-automation applied to the
format. The Schema and every implementation conform to this prose; on
disagreement, this document wins and the others are fixed.

## Changelog

| Date | Contract | schemaVersion | Change |
| --- | --- | --- | --- |
| 2026-06-10 | v1.0 | 1 | Initial publication. Ratifies the shipped F2–F4 format (anchors/threads/attributions/proposals) and adds the additive cross-rung identity fields (`Provenance.email`, `agent.onBehalfOf`) plus the compatibility (INV-15/16) and merge (INV-17) rules. |

---

## 1. Scope

The **coauthoring sidecar** is the git-native record of a document's
human+machine coauthoring state: anchored discussion threads, authorship
attribution, and pending machine proposals. It is the **canonical cross-rung
carrier** — any rung of the ladder (the VS Code editor extension, a Gitea-rung
surface, rfc-app) reads and writes the same file per this contract; git
push/pull is the transport. There is no server, no sync daemon, and no
migration between rungs ("git is truth; the surfaces are clients" —
rfc-app#46).

- **Location:** `.threads/<repo-relative-document-path>.json`, in the same
  repository as the document it describes (e.g. `docs/spec.md` →
  `.threads/docs/spec.md.json`). The document path is the sidecar key; file
  rename/move tracking is out of scope for v1.
- **One sidecar per document.** Each sidecar is a single JSON object, the
  **Artifact** (§3.1).
- **Multiple writers are expected.** The editor extension is *a* writer, not
  *the* writer. Any process conforming to §5 may append to or modify the
  record.

## 2. Serialization rules (INV-2)

A conforming writer emits the artifact **deterministically**, so diffs stay
minimal and any two conforming writers produce byte-identical output for the
same logical content:

1. **Pretty JSON**, 2-space indent, UTF-8, **exactly one trailing newline**,
   no BOM.
2. **Root key order:** `schemaVersion`, `document`, `anchors`, `threads`,
   `attributions`, `proposals` — then unknown root keys (rule 5).
3. **`anchors` keys sorted** lexicographically.
4. **Known keys of every object in the canonical order** given by the field
   tables in §3 (the order shown is normative). Optional known fields that are
   absent are **omitted entirely** (never `null`).
5. **Unknown keys serialize after known keys, sorted lexicographically**
   (INV-15's deterministic placement — see §4).

## 3. Data model

### 3.1 Artifact (root)

| Key | Type | Req | Semantics |
| --- | --- | --- | --- |
| `schemaVersion` | integer ≥ 1 | ✓ | The format **major**. v1.0 of this contract = `1`. See §4. |
| `document` | object | ✓ | `{ "path": string }` — repo-relative path of the described document; the sidecar key. |
| `anchors` | object | ✓ | Map of anchor id → `Anchor` (§3.2). The **shared** anchoring primitive: threads, attributions, and proposals all reference entries here by id. Anchors referenced by no record are pruned by writers that own the rewrite. |
| `threads` | array | ✓ | `Thread[]` (§3.4). |
| `attributions` | array | ✓ | `AttributionRecord[]` (§3.5). **State, not history** — the current authorship map, not an edit log. |
| `proposals` | array | ✓ | `Proposal[]` (§3.6). **Pending-only** — accepted/rejected proposals are removed, never archived here. |

All four sections are required even when empty (`{}` / `[]`).

### 3.2 Anchor & Fingerprint

An **Anchor** is `{ "fingerprint": Fingerprint }`.

A **Fingerprint** locates a text region by content, not position:

| Key | Type | Req | Semantics |
| --- | --- | --- | --- |
| `text` | string | ✓ | The anchored text itself. **The text is the truth**: a region resolves only where this text is found (with its context). For proposals, `text` is also the exact replace target. |
| `before` | string | ✓ | ≤ ~3 lines / 120 chars of leading context. |
| `after` | string | ✓ | ≤ ~3 lines / 120 chars of trailing context. |
| `lineHint` | integer ≥ 0 | ✓ | 0-based line of the anchor start at write time. A **tie-breaker among multiple text matches, never truth**: a reader must not resolve an anchor by line number alone. |

Resolution semantics: resolve by exact `text` match disambiguated by
`before`/`after`, tie-broken by proximity to `lineHint`; if the text cannot be
found, the record is **orphaned** — surfaced to the user, never silently moved
or guessed (the editor's INV-1).

### 3.3 Provenance

The reusable author field, carried by messages, attributions, and proposals.
Identity is **git's own model**: `email` is the cross-rung join key (forges
already map email → account); `id` is the display/short name. There are no
signatures in v1 — this is provenance, not authentication; the git history is
the integrity layer.

| Key | Type | Req | Semantics |
| --- | --- | --- | --- |
| `kind` | `"human"` \| `"agent"` | ✓ | Who kind of actor authored this. |
| `id` | string | ✓ | Short/display name (e.g. a username, `"claude"`). Not forge-resolvable on its own. |
| `email` | string | — | The actor's email — the cross-rung identity join key. Omitted when unknown (e.g. no git config). |
| `agent` | object | ✓ when `kind:"agent"` | Machine details, below. Absent on humans. |

`agent` payload:

| Key | Type | Req | Semantics |
| --- | --- | --- | --- |
| `sdk` | string | ✓ | The driving SDK (e.g. `"@cline/sdk"`). |
| `model` | string | ✓ | Model name/alias used for the turn. |
| `sessionId` | string | ✓ | The SDK session/run id (may be `""` when unavailable). |
| `onBehalfOf` | object | — | `{ "id": string, "email"?: string }` — the **human operator the machine acted for** (rfc-app#46 §6.5's `On-behalf-of:` made data). Omitted when not established. |

**PII note:** emails in a repo-committed file are exactly what git commits
already record; adopters should know the sidecar carries the same class of
data as `git log`.

### 3.4 Thread & Message

**Thread** — an anchored discussion:

| Key | Type | Req | Semantics |
| --- | --- | --- | --- |
| `id` | string | ✓ | Unique id (reference writers use `t_<uuid>`). |
| `anchorId` | string | ✓ | Key into `anchors`. |
| `status` | `"open"` \| `"resolved"` | ✓ | Discussion state. |
| `messages` | array | ✓ | `Message[]`, chronological. |

**Message:**

| Key | Type | Req | Semantics |
| --- | --- | --- | --- |
| `id` | string | ✓ | Unique id (`m_<uuid>`). |
| `author` | Provenance | ✓ | §3.3. |
| `body` | string | ✓ | Markdown message body. |
| `createdAt` | string | ✓ | ISO-8601 UTC timestamp (`YYYY-MM-DDTHH:mm:ss.sssZ`). |

### 3.5 AttributionRecord

The current authorship map: an anchored, author-attributed span. **State, not
history** — records are coalesced/split as the document evolves.

| Key | Type | Req | Semantics |
| --- | --- | --- | --- |
| `id` | string | ✓ | Unique id (`at_<uuid>`). |
| `anchorId` | string | ✓ | Key into `anchors`. |
| `author` | Provenance | ✓ | Who authored the span's text. |
| `createdAt` | string | ✓ | ISO-8601 UTC. |
| `updatedAt` | string | ✓ | ISO-8601 UTC; bumped when the span's extent/fingerprint changes. Drives merge resolution (§6). |
| `turnId` | string | — | Groups all spans applied by one machine turn. |

### 3.6 Proposal

A **pending** machine edit awaiting a human decision. Decisions are
human-only; a proposal never mutates the document until accepted.

| Key | Type | Req | Semantics |
| --- | --- | --- | --- |
| `id` | string | ✓ | Unique id (`p_<uuid>`). |
| `anchorId` | string | ✓ | Key into `anchors`; the anchor's `fingerprint.text` **is** the exact target text and is immutable for the proposal's life. |
| `replacement` | string | ✓ | The full proposed text for the anchored range. |
| `author` | Provenance | ✓ | The proposing machine (with `onBehalfOf` where known). |
| `createdAt` | string | ✓ | ISO-8601 UTC. |
| `turnId` | string | — | Groups N proposals born of one turn. |
| `instruction` | string | — | What the human asked for (review context). |

## 4. Compatibility & versioning (INV-15, INV-16)

`schemaVersion` is the **major**. The rules:

1. **Within a major, changes are additive-only**: new *optional* fields or new
   root sections. Existing documents remain valid unmodified; the major does
   not bump.
2. **Readers ignore unknown optional fields** they don't implement (but see
   rule 3).
3. **Writers preserve unknown fields — INV-15 (round-trip preservation).** A
   conforming writer rewriting a sidecar MUST carry every field it does not
   recognize, at **every object level** (root, anchor, fingerprint, thread,
   message, provenance, attribution, proposal, …), serialized after known
   keys, sorted (§2 rule 5). **No rung's writer may destroy another rung's
   data.**
4. **A newer major is read-only — fail-safe.** A reader encountering
   `schemaVersion` greater than the major it implements MUST NOT write the
   sidecar: render what it understands, surface a warning naming the version,
   and skip every write path. Recoverable by upgrading the older rung.
5. **Breaking changes bump the major** and are recorded in this changelog.

The JSON Schema deliberately allows unknown fields everywhere; it validates
known-field structure only. Validation of a v-next document against the v1
schema therefore still passes for the v1 subset — by design.

## 5. Conforming-writer checklist

Any process writing a sidecar (a forge surface, a CLI, an editor) MUST:

1. **Validate before writing** (schema + the §3 semantics it touches); refuse
   to operate on an invalid record rather than "fixing" it silently.
2. **Refuse newer majors** (§4 rule 4).
3. **Preserve unknown fields** (§4 rule 3).
4. **Mint fresh uuid-based ids** for new records (`m_`/`t_`/`at_`/`p_` +
   UUID); never reuse or guess ids.
5. **Stamp ISO-8601 UTC timestamps** (`new Date().toISOString()` shape).
6. **Carry identity**: set `author.email` when the writer knows it; agents set
   `onBehalfOf` when the operator is established.
7. **Serialize per §2** (byte-determinism) and **validate again after** the
   rewrite.

Executable example: `vscode-cowriting-plugin/scripts/crossrung-reply.mjs` — a
self-contained foreign writer that appends a thread reply per this checklist.

## 6. Merge rules (INV-17)

Two writers on two clones can diverge; git will surface the sidecar as a
textual conflict. The **semantic** resolution is a deterministic 2-way merge,
`merge(ours, theirs)`:

- **Refuse differing majors** (error; a rung never merges what it can't fully
  read).
- **`anchors`**: union by key. Same key, divergent value → deterministic
  tie-break (below), **key reported**.
- **`threads` / `attributions` / `proposals`**: union by `id`. Records present
  on one side only pass through; identical records dedupe. Same-id divergence
  resolves:
  - **Thread**: the **shell** (all fields except `messages`) and the messages
    merge independently. Divergent shells → deterministic tie-break, thread id
    reported. (A consequence: divergent `status` resolves to `"resolved"`
    over `"open"`, since the tie-break is lexicographic.) `messages` union by
    `id`, **ordered by (`createdAt`, `id`)**; divergent same-id messages →
    tie-break, message id reported. The common forge case — one side appends a
    reply while the other edits elsewhere — merges **cleanly by construction**
    (fresh uuids, disjoint sections).
  - **Attribution**: **newer `updatedAt` wins**; equal `updatedAt` →
    tie-break. Id reported either way.
  - **Proposal / Message / Anchor** (no `updatedAt`): tie-break. Id reported.
- **Unknown root keys**: union; same key divergent → tie-break, key reported.
- **`document`**: must agree; divergence → tie-break + `"document"` reported
  (should not happen — sidecars are per-path).

**The deterministic tie-break:** the **lexicographically larger
stable-stringify** wins, where stable-stringify is JSON with all object keys
sorted and no whitespace. Symmetric: `merge(a,b)` and `merge(b,a)` pick the
same winner.

**Merge honesty (INV-17):** every rule-resolved divergence is **surfaced to
the caller** (the list of resolved ids/keys) — never silently guessed. Humans
remain the final arbiter: the file is plain pretty JSON and stays
human-resolvable; these rules give tools and humans the same answer.

Reference implementation:
`vscode-cowriting-plugin/src/mergeArtifacts.ts` (`mergeArtifacts(ours,
theirs): { merged, conflicts }`). Wiring it as a `.gitattributes` merge driver
is a deployment convenience, not part of this contract.

## 7. Out of scope (v1)

File rename/move tracking · signed provenance / authentication ·
`ratifiedBy` / multi-party provenance · rejected-proposal history trails ·
any transport beyond git itself.