cairnquire/.project/milestones/milestone-02-sync-protocol.md

Milestone 2: Sync Protocol

Duration: 2 weeks
Goal: Bidirectional file sync between server and filesystem/web client

Tasks

Week 3: Server-Side Sync

• Content-addressed filesystem implementation

  • SHA-256 hash computation
  • Directory layout: store/ab/cd/abcdef...
  • Write-once semantics
  • Deduplication verification

• File watcher (fsnotify)

  • Watch configured directory recursively
  • Debounce rapid changes
  • Ignore hidden paths and common editor temp files
  • Compute hash on change, update database

• WebSocket server

  • Connection management (connection pool)
  • Message framing and parsing
  • WebSocket authentication intentionally out of scope for Milestone 2
  • Heartbeat/ping-pong for connection health

• SimpleSync protocol server implementation

  • Sync request/response handler
  • Root hash computation
  • Missing content detection
  • Conflict detection logic

Week 4: Client-Side Sync & Offline Support

• WebSocket client (Go-served UI)

  • Connection management with auto-reconnect
  • Message queue for offline periods
  • Reconnection after offline periods

• IndexedDB cache layer

  • Store document/page content for offline reads
  • Store sync state and pending changes
  • Simple fixed cap for cached pages/content
  • Preserve pending edits during cache cleanup

• File sync UI

  • Sync status indicator
  • Offline mode banner
  • Pending changes list
  • Manual sync trigger button

• Conflict detection display

  • Visual indicator for conflicting files
  • Side-by-side diff for server copy vs queued edit
  • Conflict resolution UI with Monaco resolved document editor

Acceptance Criteria

Functional

• File changes on disk automatically sync to server within 5 seconds
• Web client receives real-time updates when files change on server
• Client can make changes offline and sync when reconnected
• Concurrent edits to different files succeed without conflict
• Concurrent edits to same file detected as conflict
• Content hash verified on every transfer (client and server)
• Sync works across browser refresh (IndexedDB persistence)

Non-Functional

• WebSocket authentication deferred to Milestone 3 application auth
• File watcher doesn't consume >1% CPU on idle
• IndexedDB logout clearing deferred to Milestone 3 application auth
• Sync protocol documented with state/flow diagrams

Performance

• Sync of 100 files completes in <10 seconds
• WebSocket message overhead <1KB per sync cycle
• File watcher detects changes within 500ms

Protocol Specification

Message Types

// Client → Server
interface SyncRequest {
  type: 'sync_request';
  clientId: string;
  rootHash: string;
  files: Record<string, string>; // path → hash
}

// Server → Client
interface SyncResponse {
  type: 'sync_response';
  serverRootHash: string;
  missingFromClient: string[]; // hashes to download
  missingFromServer: string[]; // hashes to upload
  conflicts: string[]; // file paths with conflicts
}

// Content request
interface ContentRequest {
  type: 'content_request';
  hash: string;
}

// Content response
interface ContentResponse {
  type: 'content_response';
  hash: string;
  content: string; // base64 encoded
}

State Machine

[Idle] --sync_request--> [Comparing] --has_differences--> [Transferring] --complete--> [Idle]
                                      --no_differences--> [Idle]
[Idle] --file_change--> [LocalChange] --sync--> [Comparing]

Deliverables

1. SimpleSync protocol specification document
2. State/flow diagrams for browser sync scenarios
3. WebSocket message documentation
4. Go-level offline/conflict sync test coverage

Risk Mitigation

Risk	Mitigation
WebSocket connection drops frequently	Auto-reconnect with exponential backoff, queue offline
Large files cause sync delays	Chunked transfer, progress indicators, size limits
Conflicts in frequently edited files	Optimistic UI, clear conflict resolution, email notification

Definition of Done

• All Milestone 2 functional acceptance criteria pass
• Sync protocol tested with 2+ concurrent clients
• Offline/online transition tested
• 100-file sync performance target validated
• Documentation complete