vscode-cowriting-plugin-content/specs/coauthoring-attribution.md

---
status: graduated
---
# Solution Design: Live Human/Claude Attribution in the Buffer (F3)

| | |
| --- | --- |
| **Author(s)** | Ben Stull (with Claude) |
| **Reviewers / approvers** | Ben Stull |
| **Status** | `draft` |
| **Version** | v0.1.0 |
| **Source artifacts** | Epic `benstull/vscode-cowriting-plugin#1` · Feature `#6` (F3) · Parent spec: `vscode-cowriting-plugin-content/specs/coauthoring-inner-loop.md` (graduated; §6.3 `attributions[]`/`provenance`, §9 OPEN→F3/F4) · F2 shipped: `#4` (PR #5, session 0004) · Lineage: `ben.stull/rfc-app#48` |

**Change log**

| Date | Version | Change | By |
| --- | --- | --- | --- |
| 2026-06-10 | v0.1.0 | Initial draft — brainstorming session 0006 | Ben Stull + Claude |

---

## 1. Business Context

### 1.1 Executive Summary

F3 makes the buffer an **honest record of authorship**: as a document is
coauthored, the editor shows — live — which spans were written by the **human**
and which by **Claude**, and persists that record git-natively in the same
sidecar F2 shipped, filling the reserved `attributions[]` extension point on the
shared `anchors`/`Provenance` primitives. It also lands the project's **first
live `@cline/sdk` turn** — the minimal machine-edit ingress that gives
attribution something real to attribute — behind a programmatic apply-edit
**seam** that F4's propose/accept will later drive.

### 1.2 Background

F2 (#4) gave regions durable *discussion*; nothing yet records who *wrote* what.
Epic #1's second acceptance pillar is "see, live in the buffer, which spans are
human vs. Claude." The parent spec deliberately reserved `attributions: []`
(INV-4) and deferred "where Claude runs + provider/auth" to "the first live
`@cline/sdk` turn, F3/F4" — i.e., to exactly this design. Issue #6 routed the
open fork (what counts as a machine edit before F4 exists; the `attributions[]`
shape; mixed-edit granularity) to this brainstorming session.

### 1.3 Business Actors / Roles

- **Coauthor (human)** — the writer/engineer authoring prose/specs in VS Code.
- **Coauthor (machine)** — Claude via `@cline/sdk`; **active for the first time**
  (F2 reserved the `agent` provenance author; F3 uses it).

### 1.4 Problem Statement

Once a machine edit lands in the buffer it is indistinguishable from human
typing. There is no basis for trust ("did I write this claim or did it?"), no
provenance to carry up the ladder, and no substrate for F4's propose/accept to
render against.

### 1.5 Pain Points

- No visible, live distinction between human-authored and Claude-authored spans.
- No durable authorship record: attribution (if any) dies on reload.
- No machine-edit pathway at all yet — F2 is human-only by design.

### 1.6 Targeted Business Outcomes

Human and Claude spans visibly distinguished as edits happen; the attribution
survives further editing (re-anchor) and reload (sidecar persistence); a real
Claude edit can be invoked from the editor; F4 inherits both the attribution
substrate and a clean apply-edit seam.

### 1.7 Scope (business)

**In scope:** live in-buffer rendering of human/Claude span attribution;
capturing human keystrokes and applied machine edits as attributed anchored
spans; the `attributions[]` shape; character-precise split/merge of mixed edits;
attribution survival across edits (re-anchor / orphan); git-native persistence +
reload; the programmatic apply-edit seam; a minimal live `@cline/sdk` turn
(edit-selection command) on the `claude-code` provider.

**Out of scope (deferred, not forgotten):** F4 propose/accept (keep/reject UX,
inline diff — it will drive this seam); F5 cross-rung format + Gitea round-trip
(#46); attribution of edits made outside the session (external editors, git
merges) beyond the orphan rule; per-character blame depth (the span is the
unit); multi-file orchestration; Anthropic API-key auth (config option later);
chat-panel UX; any server.

### 1.8 Assumptions · Constraints · Dependencies

- **Parent:** Epic #1. **Blocked by:** F2 #4 (shipped). **Feeds:** F4
  (propose/accept renders into this substrate and drives the seam); relates to
  F5.
- Builds on the graduated parent spec's primitives: shared `anchors`
  (INV-4), `Provenance` (`kind: human | agent`), the Anchorer's
  resolve/orphan ladder (INV-1/INV-3), the per-document sidecar (INV-2).
- **F2's no-credentials invariant (parent INV-5) ends here by design** — but
  with zero key handling: the live turn uses the SDK's built-in **`claude-code`
  provider** ("Use Claude Code SDK with Claude Pro/Max subscription"), riding
  the operator's existing local Claude Code login. The extension stores no
  secret of any kind.
- Requires Claude Code installed + signed in for the live turn; everything else
  (tracking, rendering, persistence, tests) works without it.
- Native primitives: `vscode.window.createTextEditorDecorationType` (rendering),
  `onDidChangeTextDocument` (edit deltas — the Anchorer already consumes it),
  `WorkspaceEdit` (the seam's application path).

### 1.9 Business Use Cases

- **BUC-1** A coauthor watches authorship accumulate honestly as they and Claude
  write: each author's spans are visibly theirs, live, and the record survives
  editing and reopening the workspace.
- **BUC-2** A coauthor selects a region, asks Claude to edit it, and the
  resulting machine edit lands visibly Claude-attributed.

---

## 2. Solution Proposal

Fill the sidecar's reserved `attributions[]` with **anchored, author-attributed
spans** maintained live by a pure span-algebra tracker: human keystrokes produce
human spans; edits applied through a new programmatic **apply-edit seam**
produce agent spans. Mixed edits split character-precisely; adjacent same-author
spans coalesce. Spans persist via the existing Store/Anchorer (fingerprint on
save; resolve-or-orphan on load — never guess). A minimal live turn — an
edit-selection command on the SDK's `claude-code` provider — drives the seam so
there is a real machine author from day one. Rendering is the native Decorations
API: Claude spans tinted, human spans gutter-marked, unattributed text plain.

---

## 3. Product Personas

- **PP-1 Inner-loop coauthor** — the human writer/engineer (as in F2).
- **PP-2 Machine coauthor (Claude)** — now active: authors edits via the live
  turn; its spans carry `agent` provenance.

## 4. Product Use Cases

- **PUC-1** Type in a tracked document → the new/changed span renders
  human-attributed, live.
- **PUC-2** Select a region, run "Ask Claude to edit selection," give an
  instruction → the replacement lands Claude-attributed, live.
- **PUC-3** Edit inside a Claude-attributed span → the span splits
  character-precisely; the human's characters are human-attributed; the
  remainder stays Claude's.
- **PUC-4** Reopen the workspace → attributed spans reload from the sidecar at
  their re-resolved anchors; un-resolvable spans surface as orphaned, never
  silently moved.
- **PUC-5** Toggle attribution decorations on/off.

## 5. UX Layout

No new UI surface. Attribution renders as **decorations**: a subtle background
tint on Claude-attributed spans, a thin gutter bar on human-attributed spans,
nothing on unattributed text (text predating tracking — absence of a span is
the honest record). Two contributed commands: **"Cowriting: Ask Claude to edit
selection"** (selection + instruction input box → machine edit) and
**"Cowriting: Toggle attribution"**. Orphaned attributions are dropped from
decoration and surfaced as a **status-bar count** (details in the output
channel) — visible, flagged, recoverable, per F2's orphan precedent.

---

## 6. Technical Design

### 6.1 Invariants

Parent-spec invariants INV-1..INV-4 carry over unchanged. F3 adds:

- **INV-6** An attribution span is **never silently moved or re-authored**: its
  location is re-resolved by fingerprint (or orphaned), and its author only
  changes by the explicit split/clip rules of the span algebra.
- **INV-7** Attribution is **char-honest**: the span algebra attributes exactly
  the characters each author produced (split character-precisely; coalesce only
  adjacent same-author spans). No threshold heuristics, no whole-span flips.
- **INV-8** The extension **stores no credentials**. The live turn delegates
  auth entirely to the local Claude Code installation (`claude-code` provider);
  if it is absent or signed out, the live turn fails gracefully with guidance —
  tracking, rendering, and persistence are unaffected.
- **INV-9** Machine edits enter the buffer **only through the seam**
  (`applyAgentEdit`), so attribution can never mistake an agent edit for typing;
  F4 inherits the same guarantee.

### 6.2 High-level architecture

Two new vscode-free units (unit-testable, like the POC's `cline.ts` and F2's
model/anchorer) plus thin editor-facing wiring:

- **`attributions` model** — the typed `attributions[]` shape on the artifact
  (replaces the `unknown[]` placeholder; `schemaVersion` stays 1 — additive).
- **AttributionTracker** — pure span algebra over offset ranges:
  `applyChange(spans, edit, author) → spans` (shift/split/clip/coalesce).
- **Apply-edit seam** — `applyAgentEdit(doc, range, newText, provenance)`:
  applies a `WorkspaceEdit` and registers it (keyed by document version) so the
  tracker attributes the resulting change event to the agent. Exposed as an
  internal API + a command, so tests drive it with no LLM.
- **LiveTurn** — the edit-selection command: instruction → `@cline/sdk`
  (`claude-code` provider, building on the POC's vscode-free `cline.ts`
  driver) → replacement text → the seam.
- **AttributionRenderer** — two `TextEditorDecorationType`s + the toggle;
  re-renders on tracker change.
- **CoauthorStore / Anchorer — reused unchanged.**

```
keystroke ─────────────▶ AttributionTracker (author = human)
applyAgentEdit (seam) ─▶ WorkspaceEdit + pending-edit registry ─▶ AttributionTracker (author = agent)
live turn ─▶ selection + instruction ─▶ @cline/sdk (claude-code) ─▶ seam
document change ───────▶ shift/split/clip/coalesce ─▶ AttributionRenderer (decorations)
save ──────────────────▶ buildFingerprint per span ─▶ sidecar attributions[] (CoauthorStore)
load / external change ▶ resolve per span ─▶ render | orphaned (Anchorer ladder, INV-1)
```

### 6.3 Data model & ownership

Same sidecar, same `anchors` map, same `Provenance` — `attributions[]` is filled,
not reshaped (parent INV-4; no `schemaVersion` bump):

```jsonc
"attributions": [
  {
    "id": "at1",
    "anchorId": "a7",              // shared anchors map — same Fingerprint primitive
    "author": { "kind": "agent", "id": "claude",
                "agent": { "sdk": "@cline/sdk", "model": "…", "sessionId": "…" } },
    "createdAt": "ISO-8601",
    "updatedAt": "ISO-8601",       // bumped when the span's extent/fingerprint changes
    "turnId": "turn-…"             // optional; groups all spans applied by one live turn
  }
]
```

- **Orphanhood is not persisted** — exactly like F2 threads, it is a
  resolve-time outcome: fingerprint fails → orphaned (visible, flagged), never
  guessed.
- **Unattributed text is the absence of a span** — text predating tracking has
  no attribution record, honestly.
- Ownership/format rules unchanged: extension is the sole writer; stable key
  ordering; ids via `newId()`.

### 6.4 Interfaces & contracts

- **AttributionTracker** (pure): `applyChange(spans, edit, author): spans` ·
  `coalesce(spans): spans` · span = `{ range: OffsetRange, author: Provenance,
  id, turnId? }`. Reuses `anchorer.shift` semantics for untouched spans.
- **Seam**: `applyAgentEdit(doc, range, newText, provenance): Promise<boolean>`
  — applies + registers; also contributed as an internal command (E2E entry
  point).
- **LiveTurn**: `editSelection(doc, selection, instruction): Promise<void>` —
  resolves the `claude-code` provider, runs one SDK turn producing replacement
  text for the selection, calls the seam with `agent` provenance (model +
  sessionId from the turn).
- **AttributionRenderer**: `render(editor, spans)` · `setVisible(boolean)`.
- **Store/Anchorer**: existing contracts, now also carrying attributions.

### 6.5 Per–Product-Use-Case design

- **PUC-1 (type):** `onDidChangeTextDocument` → for each content change, the
  tracker shifts spans past the edit, clips/deletes spans overlapping a
  deletion, splits a different-author span around an insertion, attributes the
  inserted range to **human** (no pending seam registration for this document
  version), then coalesces. Render.
- **PUC-2 (live turn):** command guards (selection non-empty, document tracked,
  Claude Code available) → input box → SDK turn (replacement text only —
  single-range, the selection) → `applyAgentEdit` → the change event arrives
  with a matching registration → attributed to **agent** with `turnId`. Render.
- **PUC-3 (mixed edit):** the insertion-inside-a-span case of PUC-1's algebra:
  split at the insertion point, new human span between the two agent halves
  (INV-7). Same rule symmetric for agent edits inside human spans.
- **PUC-4 (reload / external change):** on open or sidecar/document external
  change: `load` → per attribution `resolve(fingerprint)` → live span or
  orphaned (counted, not rendered). On save: refresh fingerprints from live
  spans (`updatedAt` bumped only for changed spans), persist.
- **PUC-5 (toggle):** flips renderer visibility; tracking continues regardless.

### 6.6 Non-functional requirements & cross-cutting concerns

Tracking is O(spans) per change event — fine at human scale; coalescing bounds
span growth. Persistence happens on save (not per keystroke), as F2 does.
Resolution cost on load matches F2 (O(document) per anchor). No secrets at all
(INV-8). Skip non-text/oversized files (F2 rule). Single editor writer.
Live-turn latency is user-visible: show progress notification; the buffer is not
locked (edits during a turn are handled by the version-keyed registration — a
stale turn result fails to apply and reports, rather than corrupting).

### 6.7 Key decisions & alternatives considered

| Decision | Chosen | Alternatives rejected |
| --- | --- | --- |
| Machine-edit ingress | Programmatic seam **+** minimal live SDK turn driving it | seam-only (no real machine author; demo is simulated); live-turn-only (couples tracking to the SDK; F4 has no clean ingress to drive) |
| Provider/auth | `claude-code` provider (local Claude Code Pro/Max login; zero key handling) | Anthropic API key in SecretStorage (ignores the plan already paid for; adds key-handling surface — deferred as a config option); Cline-account OAuth (couples UX to Cline's auth service); env var (no user story) |
| Mixed-edit granularity | Character-precise split + same-author coalescing (INV-7) | whole-span re-attribution (dishonest at the edges); threshold-based (arbitrary, not strictly honest) |
| Attribution record | Span-list on shared `anchors` (state, not history) | event log + replay (truthful history but heavy sidecar churn; re-anchoring a log is hard); hybrid (YAGNI) |
| Rendering | Claude tint + human gutter bar + plain unattributed; toggle | Claude-only (human record invisible); both tinted (visually heavy prose) |
| Live-turn UX | Edit-selection command (selection + instruction → replacement) | whole-document multi-range edits (big bite for "minimal ingress"); chat panel (new surface F4 will reshape) |
| Orphan persistence | Resolve-time (not persisted), per F2 threads | persisted status field (duplicates what resolution derives; risks stale state) |

### 6.8 Testing strategy

- **Unit (vitest, vscode-free):** AttributionTracker span algebra exhaustively —
  insert/delete at/around/inside spans, split, clip, coalesce, multi-edit
  sequences, both author directions; model round-trip (serialize → reload,
  stable formatting); resolve→orphan for attribution fingerprints.
- **Host E2E (`@vscode/test-electron`, F2 pattern):** type → human span → seam
  command edit → agent span → save → reload → spans restored → edit above →
  re-anchored → mangle anchored text → orphaned. **No LLM in CI** — E2E drives
  the seam.
- **Live-turn smoke (manual, documented):** select → instruct → Claude edit
  lands attributed; run on a signed-in Claude Code machine. Failure-path check:
  signed-out / missing Claude Code → graceful error (INV-8).

### 6.9 Failure modes, rollback & flags

Orphaned attributions (INV-1/INV-6) — handled, recoverable (re-resolve if the
text reappears). Live-turn failures (no Claude Code, signed out, model error,
stale document version) — surfaced as notifications; never partial-applied.
Sidecar merge conflicts — plain JSON, human-resolvable (unchanged). No feature
flag: additive; decorations have a toggle; absence of `attributions[]` entries
is the off state.

---

## 7. Delivery Plan

### 7.1 Approach / strategy

One planning-and-executing session (F3 = #6), plan written just-in-time from
this spec, per the F2 precedent.

### 7.2 Slicing plan

- **SLICE-1** Typed `attributions[]` model (+ round-trip tests).
- **SLICE-2** AttributionTracker span algebra (+ exhaustive unit tests).
- **SLICE-3** Seam (`applyAgentEdit` + registry) and human-edit wiring +
  decoration rendering (tint/gutter/toggle).
- **SLICE-4** Persistence on save; reload / external-change resolve; orphan
  surfacing.
- **SLICE-5** Live `claude-code` turn (edit-selection command) + documented
  manual smoke + graceful-failure paths.
- **SLICE-6** Host E2E (type → attribute → seam edit → attribute → reload →
  re-anchor → orphan).

E2E are first-class plan tasks (handbook §4 / parent §6.8), not a follow-up.

### 7.3 Rollout / launch plan

Still non-shippable (no marketplace publish). "Done" = issue #6 acceptance met:
unit + host E2E green, live smoke performed once on this machine.

### 7.4 Risks & mitigations

| Risk | Mitigation |
| --- | --- |
| Span churn from heavy typing (many tiny spans) | coalescing (INV-7's merge half); persistence only on save |
| Misattributing a seam edit to the human (or vice versa) | version-keyed pending-edit registry; seam is the only machine ingress (INV-9); algebra unit-tested both directions |
| `claude-code` provider/SDK surface shifts under us (SDK 0.0.x) | provider use isolated in vscode-free LiveTurn module; seam keeps everything else LLM-free |
| Buffer edited mid-turn | stale-version application fails gracefully, reports, never partial-applies |
| Fingerprint mis-resolution on duplicated text | unchanged F2 ladder: context + lineHint, orphan over guess |

---

## 8. Traceability matrix

| Requirement (issue #6 acceptance) | Use case | Design | Slice |
| --- | --- | --- | --- |
| Human spans recorded/rendered live | PUC-1 | §6.2, §6.5, INV-7 | SLICE-2/3 |
| Machine edits recorded/rendered as Claude's | PUC-2 | seam + LiveTurn, INV-9 | SLICE-3/5 |
| Attribution survives edits (re-anchor / orphan) | PUC-4 | Anchorer ladder, INV-1/6 | SLICE-4 |
| Git-native persistence + reload | PUC-4 | §6.3, parent INV-2/4 | SLICE-1/4 |
| Mixed-edit split/merge | PUC-3 | INV-7, §6.5 | SLICE-2 |
| Unit + host E2E coverage | — | §6.8 | SLICE-2/6 |

## 9. Open Questions & Decisions log

- **RESOLVED (this session):** ingress = seam + minimal live turn; auth =
  `claude-code` provider only (no extension-held credentials; Anthropic-key
  fallback deferred — not needed for testing since tests drive the seam);
  granularity = character-precise split + coalesce; record = span-list on shared
  anchors, orphanhood resolve-time; rendering = Claude tint + human gutter +
  toggle; live-turn UX = edit-selection command.
- **OPEN → F4:** propose/accept drives the same seam; accepted diffs render into
  this attribution substrate. The seam's contract (single-range apply) may grow
  multi-range then.
- **OPEN → F5:** cross-rung persistence format may re-home `attributions[]`
  alongside the rest of the sidecar.
- **OPEN → later:** attribution of out-of-session edits (git merges, external
  editors) beyond the orphan rule; span-level → finer blame; Anthropic API-key
  config option for machines without Claude Code.

## 10. Glossary & References

- **Attribution span** — an anchored, author-attributed range of a document; the
  unit of provenance. **Seam** — `applyAgentEdit`, the single programmatic
  ingress for machine edits (INV-9). **Unattributed** — text with no span (it
  predates tracking). **Live turn** — one `@cline/sdk` invocation producing a
  machine edit. **`claude-code` provider** — the SDK's built-in provider that
  rides the local Claude Code Pro/Max login.
- Epic #1 · Feature #6 (F3) · F2 #4 (PR #5) · parent spec
  `coauthoring-inner-loop.md` · POC #2 · rfc-app#48/#46 (lineage).