CRDT Sync Overview

NodeDB bridges AP (available, partition-tolerant) on edge devices with CP (consistent, partition-tolerant) in the cloud.

How It Works

1. Device writes locally — Available immediately, no network required
2. CRDT delta produced — Each write generates a Loro CRDT delta
3. Connectivity returns — Deltas sync to Origin via WebSocket (port 9090)
4. Origin validates — SQL constraints (UNIQUE, FK, CHECK) checked at Raft commit
5. Committed — Delta replicated via Raft, broadcast to connected clients
6. Conflict — Failed constraints produce a typed CompensationHint back to device

Shape Subscriptions

Devices subscribe to a subset of data — not the entire database. This is a wire-level sync feature (ShapeSubscribe message), not a SQL statement:

Shape subscription for: users WHERE user_id = $me
Shape subscription for: tax_rates WHERE jurisdiction IN ('US-CA', 'US-NY')

Changes within a device's shape are pushed in real time via the sync protocol.

Multiple Devices

Multiple devices converge to the same state regardless of operation order. Loro's operation-based CRDTs guarantee eventual consistency without coordination.

Supported Engines for Sync

All eight engines now participate in CRDT sync:

• Data-bearing engines — Document (schemaless + strict), KV, Columnar, Timeseries, Spatial, Vector, Array
• Overlay engines — Graph traversal and Full-Text Search built on synced collections
• Schema changes — DDL (new columns, collections) broadcast to connected Lite clients after Origin catalog commit; embedded clients auto-discover schema

All engines work locally on NodeDB-Lite with sub-millisecond reads and no network dependency.