Architecture · Write path
Write-Path Atomicity Guarantees
Every content mutation flows through a single transaction boundary so that the audit log alone can reconstruct final state — for human operators and AI agents alike, with no privileged side channel.
01 The single-entry rule
Content mutations are funnelled through ctx.transact(doc_id, fn). Metadata mutations are dispatcher-transaction-only; the authoritative list lives in METADATA_ONLY_CAPABILITIES. No surface — API, CLI, MCP, or Web UI — re-implements this path; each delegates to the same dispatcher.
- Exactly one audit entry is produced per mutation, regardless of originating surface.
- Agent edits traverse the identical boundary as human edits — attribution differs, mechanism does not.
- Replays are deterministic: the log is the source of truth, the CRDT is its convergent projection.
write-path · dispatcher typescript
// one boundary — humans and agents converge here await ctx.transact(docId, (tx) => { tx.apply(op, { actor }) // human | agent tx.audit("block.update") // invariant 3 })
02 Convergence under concurrency
Concurrent human and agent edits converge across replicas via the CRDT. The transaction boundary serialises intent; the CRDT merges state. Neither principal class can observe a torn write.
NOTE
Restore is forward motion. "Restore version N" computes a delta against current state and applies it as a new corrective update — old states stay in history, never rewound.