docs(exploration): Yjs document history and evidence-grade attribution (0376, 0377)

[crs48]

Two linked explorations on document history and attribution. Docs only — no code, no changeset needed.

0376 — Two Histories, One Timeline

The History tab (time-machine, wildcard context tool) scrubs the node change log only. On a page it replays the title, tags and icon, and says nothing about the prose.

The plumbing is ~80% built and 0% surfaced:

• DocumentHistoryEngine captures Yjs snapshots on every debounced persist, persisted to a real yjs_snapshots table.
• mergeTimelines() already computes the unified timeline — no caller outside its own test.
• useTimeMachine fetches the snapshots only to .length them; TimeMachinePanel prints that count as a caption.

Findings:

• ⚠️ Restore silently half-restores. restoreToFrontier documents that document content is not restored, and tm.restore() inherits it — the confirm dialog promises a full restore. The frontier already carries yjsSnapshotRef, so the fix is small.
• No Yjs history is dropped — the gap is the time index, not the data. gc: false everywhere, PruningEngine never touches Yjs, no compaction exists. But CRDT items are keyed (client, clock) with no wall time, so a complete item log still can't answer "what did this say Tuesday at 3pm".
• Every snapshot stores a full document copy on top of that retained blob; eviction destroys index entries, not content.
• ⚠️ Do not "fix" the 5 MiB large-blob warning by enabling GC — retention is what makes scrubbing possible.

Recommends one timeline, two lanes, coarse by default — and rejects a naive merge, because it would mix signed and unsigned entries.

0377 — Evidence-Grade Attribution

The follow-on: how to get detailed attribution in the CRDT using the existing data model.

Almost none of it needs building. packages/sync/src/yjs-change.ts fully implements Yjs updates as entries in the same signed per-node hash chain — YJS_CHANGE_TYPE = 'yjs-update', createYjsChange, type guards, a ~350-line test suite, barrel exports. Zero production callers. Same for ClientIdAttestation, validateClientIdOwnership, createPersistedDocState, YjsBatcher. Change<T>'s own header names Yjs as a first-class payload type.

Meanwhile every Yjs update is already signed in transit with author + timestamp + clientID, and all of it is discarded at setDocumentContent.

Findings:

• ⚠️ clientID is spoofable and plan step 07's attestation is unwired — so any attribution UI shipped first would render a forgeable claim as fact. Step 07 is P0.
• ⚠️ plan03_4_1YjsSecurity/README.md has five [x] boxes that track module existence, not wiring. Worth correcting regardless of whether this work proceeds.
• yjs_state must stay authoritative. 0254 states the local log is a non-authoritative cache, and its compaction ships and runs every boot — inverting authority would let compaction delete document content. The correct shape is the parallel that already exists.
• Cost is rows and bytes, not CPU (38 µs native sign). YjsBatcher's 2 s default gives ~7-15:1 envelope amplification and ~1,800 rows per writing hour against a whole-user budget of 5,000 changes/day; ~10 s with paragraph flush lands ~2-3:1.
• BatchCommit is forbidden on the interactive lane (0357) — amortise by batching updates into fewer changes, not signatures.
• 0330's D3 gate is half-open: compaction shipped, the growth model never happened.

Notes

• Numbered 0376/0377 — 0373/0374/0375 were all taken (0373 was renumbered to 0375 and merged as feat(ui): rebuild inline comments as a workbench island (0375) #596).
• 0376 also flags that 0330's plan to wait for Yjs 14 AttributionManager is blocked on a beta frozen at 14.0.0-16 since 2025-12-07, while latest is 13.6.31.

🤖 Generated with Claude Code

[github-actions]

Preview: https://xnet.fyi/pr/597/app/
Demos: https://xnet.fyi/pr/597/play/