Write-Path Atomicity
Every content mutation and its audit entry commit as one transaction — or neither does. The audit log alone can reconstruct final state.
A content mutation flows through ctx.transact(doc_id, fn). Inside that boundary the dispatcher persists the encoded doc_updates, appends exactly one audit row, and — for visibility changes — enqueues an outbox event. The invariant is binary: all five rows commit, or none do.
01The boundary
The resident Y.Doc is the source of truth in memory; SQLite (or Postgres) is the durable floor. When a transaction aborts, BoundSyncService.rollback evicts the resident doc so the next reader rehydrates from the last committed bytes — never from a phantom edit.
“The audit log is not a side-effect. It is the document’s second body — lose the bytes, replay the log.”
02Why agents make this load-bearing
When an agent and a human edit the same block within the same tick, the CRDT converges the bytes — but attribution must stay exact. Each principal’s contribution is a distinct, signed audit entry, so “who wrote this clause” is always answerable, human or machine.
03Guarantees
- One mutation → exactly one audit entry.
- Rollback evicts the resident
Y.Doc; no phantom state survives. - Metadata-only mutations are dispatcher-tx-only.
- Replay from the audit log alone reconstructs the final document.
This is the floor every surface — API, CLI, MCP, Web UI — sits on. None of them re-implement it. 0