“Both people edited the same task offline. The system converged without pretending their disagreement disappeared.”
RELAY is an in-browser local-first collaboration lab built on Automerge v3.5 CRDTs that exposes how unseen concurrent changes make operational handoffs stale.
In standard collaborative boards (Trello, Jira, Notion), concurrent offline edits are resolved via naive wall-clock Last-Writer-Wins (LWW):
- The Disagreement: Coordinator A and Coordinator B lose internet connectivity during a festival. Both see the sound system setup task as unassigned, and both assign it to themselves.
- The Data Loss: When they reconnect, whoever's packet happens to arrive a millisecond later silently overwrites the other person's assignment.
- The Operational Failure: Two people believe they are responsible for the same critical equipment task, with zero warning given to either coordinator.
-
Multi-Value Conflict Preservation: Automerge preserves both competing values in its internal register (
getConflicts). RELAY surfaces both alternatives in context with their author IDs. -
Causal Acknowledgment Validity: If Coordinator A acknowledged a handoff in state
$S$ , and Coordinator B's offline change arrives, the acknowledgment is automatically revoked as Stale. - Causal Ancestry Strictness: Even if an offline user changes a field and changes it back to the exact same value, RELAY detects the intervening unreviewed causal branch and flags the acknowledgment as stale.
interface Task {
taskId: string;
title: string;
ownerId: string;
status: 'todo' | 'in-progress' | 'blocked' | 'done';
archived: boolean;
notesById: Record<string, Note>;
}When concurrent edits modify ownerId while disconnected:
const conflicts = Automerge.getConflicts(task, 'ownerId');
// Retains: { '44@1111...': 'Meera', '44@2222...': 'Arjun' }An acknowledgment
-
$T.\text{ownerId} \equiv \text{Ack}.\text{owner}$ and$T.\text{status} \equiv \text{Ack}.\text{status}$ . - Relevant field conflicts are empty (
$\text{conflicts} \le 1$ ). - The current document heads descend strictly from
$\text{Ack}.\text{relevantKnownChangeHeads}$ without unacknowledged intervening modifications to relevant task fields.
- Sync protocol exchanges incremental binary envelopes carrying
Automerge.generateSyncMessage(). - Supports single-step packet delivery, duplicate delivery (testing sync idempotence), and adversarial change dropping.
- Quiescence is defined as the state where both outgoing queues are empty and
generateSyncMessageproducesnull.
Running in Node.js / V8 across 25 deterministic schedule seeds:
- Convergence Rate: 100% (25/25 seeds converged to identical document heads).
- Mean Sync Rounds to Quiescence: 3.8 rounds.
- Mean Messages Exchanged: 4.2 messages.
- Mean Wire Bytes Exchanged: ~840 bytes per multi-edit session.
- Adversarial Negative Control: Passed (dropping changes correctly asserts cryptographic divergence).
Detailed benchmark breakdown: see BENCHMARK.md.
relay/
├── docs/
│ ├── BENCHMARK.md # 25-seed deterministic schedule benchmark report
│ ├── DEMO_SCRIPT.md # 60-second executive walkthrough script
│ ├── INTERVIEW_WALKTHROUGH.md # Staff/Senior Distributed Systems Q&A
│ ├── LINKEDIN_POST.md # Technical LinkedIn engineering post draft
│ ├── PERFORMANCE.md # Latency, wire footprint, and bundle audit
│ ├── PRIOR_ART.md # Attribution to Kleppmann, Ink & Switch, Yjs
│ ├── SYNC_CONTRACT.md # Formal CRDT & Acknowledgment specifications
│ ├── VALIDATION.md # Verification logs and contract certification
│ └── screenshots/ # 8 real browser screenshots
├── src/
│ ├── app/App.tsx # Main dual-replica state container & event router
│ ├── components/HeaderRail.tsx # Brand header, convergence status, wire stats
│ ├── domain/
│ │ ├── crdt.ts # Automerge 3.5 wrappers & conflict detection
│ │ └── types.ts # Strict TypeScript interfaces
│ ├── features/
│ │ ├── board/ # ReplicaPanel & TransportBridge
│ │ ├── conflicts/ # ConflictInboxView (Explicit resolution)
│ │ ├── export/ # ExportAndMethodView (JSON/Binary export)
│ │ ├── history/ # HistoryInspectorView (Causal timeline)
│ │ └── scenarios/ # GuidedScenariosView (4 Presets)
│ ├── storage/
│ │ └── indexeddb.ts # Namespaced local persistence
│ ├── transport/
│ │ └── simulator.ts # Controllable packet bridge simulator
│ ├── index.css
│ └── main.tsx
├── tests/
│ └── sync_contract.test.js # 5/5 Contract test suite
├── scripts/
│ ├── automerge_spike.mjs # Section 4 Technical spike script
│ ├── run_benchmark.mjs # 25-seed schedule benchmark CLI
│ └── capture_screenshots.cjs # Automated Playwright Chrome capture script
├── package.json
└── vite.config.ts
- Node.js
$\ge 18$
npm testOutput: 5 passing tests in ~260ms.
npm run benchmarkOutput: 25 schedule seeds evaluated with 100% convergence in ~560ms.
npm run buildCompiles Rust/WASM Automerge core and React bundle to static dist/ with relative base (./).
npm run dev- Kleppmann, M., & Beresford, A. R. (2017): A Conflict-Free Replicated JSON Datatype. IEEE TPDS.
- Kleppmann, M., et al. (2019): Local-first software: You own your data, in spite of the cloud. ACM Onward!
- Automerge 3.0 / Automerge-wasm: Ink & Switch high-performance Rust/WASM CRDT implementation.







