Sync Protocol

WebSocket-based sync on port 9090 for NodeDB-Lite clients. CRDT deltas flow between edge devices and Origin for all eight storage engines and their overlays.

Supported Collections

All collection engines participate in sync:

• Document (schemaless + strict)
• Key-Value
• Columnar, Timeseries, Spatial
• Vector and Array
• Graph and Full-Text Search overlays on synced collections

Schema changes (new columns, new collections) are discovered automatically by connected Lite clients after the Origin catalog commit.

How It Works

1. Lite client connects via WebSocket to Origin
2. Client sends its current LSN watermark
3. Origin sends any missed deltas since that watermark
4. Client sends locally accumulated CRDT deltas
5. Origin validates constraints (UNIQUE, FK, CHECK) via Raft
6. Committed deltas are broadcast to all connected clients with matching shape subscriptions

Shape Subscriptions

Devices subscribe to a subset of data via shape subscriptions (wire-level sync feature, not SQL):

Shape subscription: users WHERE user_id = $me

The client only receives data matching this filter. Changes within a device's shape are pushed in real time. Changes outside the shape are not sent.

Compensation Hints

If a local write violates a constraint on Origin, a typed CompensationHint is sent back:

• UniqueViolation — duplicate key detected
• ForeignKeyMissing — FK target doesn't exist
• SchemaViolation — CHECK constraint or type rule failed
• IntegrityViolation — other integrity-rule violation
• PermissionDenied — insufficient privilege
• RateLimited — quota or rate limit exceeded
• Custom — application-specific handling

The application handles the conflict — no silent data loss.