chronogrid/docs/ARCHITECTURE/03-crdt-sync-protocol.md

CRDT Synchronization Protocol Specification

1. Core Synchronization Engine

• Framework: Automerge (Rust Crate)
• Clock Specification: Hybrid Logical Clocks (HLC) combining physical system time with explicit logical sequence counters to prevent clock-skew anomalies across cross-platform endpoints.

2. Register Models & Conflict Resolution

• Task & Note Primitive Fields:
  • Properties (Title, Status, Priority Rating, Markdown Body) utilize Last-Write-Wins Element-Set (LWW-Element-Set) registers.
  • Conflicts resolve deterministically based on HLC timestamps (hlc_timestamp).
• Project Tree & Order Hierarchy:
  • Sequence Ordering uses Fractional Indexing combined with Tree-CRDT rules to eliminate circular references when moving projects offline.

3. Delta Exchange & Wire Protocol

• Transport Layer: libp2p over QUIC with direct UDP transport.
• Delta Sync Workflow:
  1. Connection established via Noise XK handshake.
  2. Peers exchange vector clocks containing the local head state hash.
  3. Missing CRDT delta changesets are compressed, encrypted, and streamed over binary channels.
  4. Both nodes merge changesets locally into SQLCipher within a single atomic database transaction.