Design Library Sync Protocol (Leaderless)

Description

Design the detailed protocol for Library Sync using a leaderless hybrid model.

Architecture Update (Oct 2025): Moved from leader-based to peer-to-peer model based on data ownership analysis.

Design Documents

• core/src/infra/sync/NEW_SYNC.md - Current leaderless design
• docs/core/sync.md - Outdated leader-based model
• docs/core/sync-setup.md - Library sync setup flow (still valid)
• docs/core/events.md - Unified event system
• docs/core/devices.md - Device system

Architecture Decisions (Revised)

• Leaderless peer-to-peer: No leader election, all devices equal
• Hybrid sync strategy:
  • State-based for device-owned data (locations, entries)
  • Log-based with HLC for shared resources (tags, albums)
• Bulk optimization: Batched state transfers for efficiency
• Conflict resolution: HLC ordering + union merge
• No central coordinator: Each device broadcasts to peers

Key Changes from Original Design

Aspect	Old Design	New Design
Architecture	Leader/follower	Peer-to-peer
Ordering	Central sequences	HLC timestamps
Sync log	One central log	Per-device for shared changes only
Device-owned data	Goes through leader	Direct state broadcast
Complexity	High (election, heartbeats)	Low (simpler)

Acceptance Criteria

• Detailed protocol design document created
• Hybrid strategy (state + log) defined
• HLC ordering mechanism specified
• Peer broadcast protocol designed
• Implementation tasks updated

References

• core/src/infra/sync/NEW_SYNC.md - Complete new specification
• HLC implementation: LSYNC-009
• Peer sync service: LSYNC-010