sod: symmetric replication for fold apps (local-first bogs, server/Node/browser-ready core)

[hhff]

What this is

sod — symmetric replication for fold apps. A sod is a replica: a local bog that always accepts writes and converges with its peers by exchanging what the other is missing (PouchDB's offline-first posture, with a protocol built for fold's data model). Client↔server and decentralized p2p are the same wire protocol — a star and a mesh of identical pairwise sessions.

Design spec: docs/superpowers/specs/2026-08-15-sod-design.md · Implementation plan: docs/superpowers/plans/2026-08-15-sod-implementation.md · Crate docs: sod/README.md · Runnable template: examples/sod-demo.

Why it converges

Fold's write primitive is a Z-set delta (datum + signed multiplicity). Deltas commute, so the multiset — and every deterministic view over it — is order-independent: replicas holding the same frames hold the same views, by algebra rather than coordination. Sync is anti-entropy: exchange version vectors, stream missing frames. Order-sensitive operations (uniqueness, claims) are an app-level pattern (route to a designated replica), never protocol machinery.

The model

• Per-origin hash-chained feeds (à la Secure Scuttlebutt): frames identified by BLAKE3, chained by prev-hash — tamper-evident, equivocation-poisoning (never of one's own feed), relayable through untrusted peers.
• Log is truth (append-only, torn-tail recovery, tamper-evident length prefixes); engines are rebuildable caches with a transactional applied-cursor, so a crash at any point heals on open.
• Ports everywhere: Engine ("the bog machinery" — MemEngine always compiled; FoldEngine behind the default fold-engine feature), LogStore, sans-io sync Session + transports (ws), entropy.
• Watermark time: max event-time applied is the only "now"; sod never reads a clock.

Fold is consumed, never modified

git diff main -- fold is empty. The applied-cursor is an ordinary Push node (AppliedCursor, sink name sod_cursor) that commits atomically with app deltas via fold's public API; where a stock sink doesn't fit replication, sod ships its own (sod::sinks::Bag). Two upstream findings for fold are documented rather than patched: Bag clamps negative running sums (order-dependent state under replication orderings), and Retain (processing-time window) cannot converge under any injected clock — the spec's Time section has the analysis; an event-time retain is the proposed fix.

Targets

• Server / native / Node.js: full stack today. Node packaging is a per-app napi-rs addon (examples/sod-demo/node) — verified cross-runtime: a Node replica and native CLI replicas converging over websocket, including third-party feeds learned by relay.
• Browser: the core (frames, vectors, log, replica, session, MemEngine) compiles for wasm32-unknown-unknown — enforced by tests/wasm_check.rs. OPFS/IndexedDB LogStore + browser transport are follow-on port implementations.
• React Native: the native stack behind a future UniFFI/JSI binding (phones have real filesystems; fjall works).

Testing

• 100-case randomized convergence suite: N replicas, interleaved writes, partial/interrupted syncs, relays — equal vectors ⇒ byte-identical views.
• Crash tests: torn-tail truncation at every byte offset, crash-window (log-ahead-of-engine) healing, interior-corruption refusal (including corrupted length prefixes).
• Adversarial tests: equivocation poisoning, forged own-feed frames, seq-0 frames, version-mismatch refusal, stray-TCP-probe on one-shot serve.
• Differential oracle: fold engine vs MemEngine over randomized delta sequences (this test caught the fold Bag clamp).
• Golden log-format fixture (byte-frozen) and the wasm32 portability gate.

Adversarial review loop

A multi-dimension review of the full branch produced 10 verified findings (8 CONFIRMED) — including a sync that could never converge past 256 frames (LIFO message drainage), log-first appends that could brick a replica on undecodable frames, silent log truncation via corrupted length prefixes, a one-message remote panic, and silently-swallowed feed poisoning. All 10 were fixed with regression tests, then adversarially re-reviewed: all confirmed closed, and the re-review's residual items (overflow-length classification, bounded refusal recording, an own-feed forgery spec clarification) were addressed in a follow-up commit.

Try it

cargo test -p sod
cargo run -p sod-demo -- ./a add hello
cargo run -p sod-demo -- ./b serve 127.0.0.1:7171   # terminal 1
cargo run -p sod-demo -- ./a sync ws://127.0.0.1:7171
cargo run -p sod-demo -- ./b list

🤖 Generated with Claude Code

Added: sod-web — the three-bog demo

A Next.js emoji reaction board where every instance embeds its own sod replica via a per-app napi addon (examples/sod-web/). The demo topology: a Fly.io hub + localhost:3000 + localhost:3001. Kill the wifi and the two locals keep syncing over loopback (a real partial partition); reconnect and the hub absorbs both sides — relay included — and all three boards converge byte-identically. The top nav shows it live: each instance is tinted by its replica id's hue, and connected peers appear as dots in their colors.

Sod additions this required (all additive, fold still untouched): SyncListener/IncomingSession and connect/OutgoingSession split accept and dial from session-run so embedding hosts borrow the replica only per-session — never while idle or dialing (blackhole-dial verified: <25 ms API latency while the loop dials a dead IP); Hello carries the sender's replica id and sessions yield a SyncReport, which is what powers the "N bogs connected" badge; bounded connect/IO timeouts with all-address dial fallback.

Verified: scripts/demo-local.mjs scripts the full three-act partition/heal rehearsal (passes); addon smoke test with a two-process sync leg (passes); Docker image built and exercised end-to-end including a host↔container sync. deployed to Fly (sanctuary-computer org) and verified: a laptop replica synced bidirectionally with https://sod-web-demo.fly.dev over the public internet (sync on raw-TCP port 10700, dedicated IPv4).

This work went through the same adversarial review loop: an interim round caught a demo-killing bug (dialing an unreachable peer while holding the replica lock — exactly the wifi-kill moment) plus five others; the final round contributed ten more findings (IPv6-first dial fallback, Fly HOSTNAME injection, a mutual-dial lock cycle, a Session::report panic path, and deploy-config issues among them). All fixed with regression coverage.