Realtime transport & failover semantics
How editorzero keeps every replica convergent when the websocket drops — and why the dispatcher, not the client, owns the moment of truth.
A self-hostable, AI-native workspace lives or dies on one promise: every editor — human or agent — sees the same document, eventually and provably. Transport is how we keep that promise across flaky networks.
01The convergence contract
Replicas exchange Yjs updates over a single websocket multiplexed per document. The CRDT guarantees that any permutation of those updates converges to identical state. Transport's only job is delivery — never resolution. When delivery fails, we degrade, we do not diverge.
The client is never the source of truth. The dispatcher is. A dropped socket is a delivery problem, not a correctness problem.
02Failover, step by step
- Detect. Heartbeat lapses past the grace window; the client marks the channel degraded and buffers locally.
- Buffer. Local edits keep applying against the in-memory doc; the update queue is ordered by Lamport clock.
- Reattach. On reconnect, the client sends its state vector; the server replies with the missing delta only.
- Reconcile. Buffered updates merge; the audit log records exactly one entry per applied mutation.
The reattach handshake is deliberately cheap — a state vector is a few hundred bytes regardless of document size, so a client that was offline for an hour pays the same reconnect cost as one offline for a second.
POST /sync/reattach { doc, stateVector }
→ 200 { delta, serverClock } # bytes ∝ divergence, not doc size
Every mutation produces exactly one audit entry, and the audit log alone reconstructs final state. Failover replays the queue through the same dispatcher path — so a recovered edit is indistinguishable from one that never dropped.
03Why agents change the math
Agents are first-class principals. An agent reconnecting after a network partition follows the identical reattach path as a human — same state vector, same delta, same audit attribution. There is no privileged agent channel and no second code path to drift out of sync.