# Milestone 2: Sync Protocol

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

## Tasks

### Week 3: Server-Side Sync

- [x] Content-addressed filesystem implementation
  - [x] SHA-256 hash computation
  - [x] Directory layout: `store/ab/cd/abcdef...`
  - [x] Write-once semantics
  - [x] Deduplication verification
  
- [x] File watcher (fsnotify)
  - [x] Watch configured directory recursively
  - [x] Debounce rapid changes
  - [x] Ignore hidden paths and common editor temp files
  - [x] Compute hash on change, update database
  
- [x] WebSocket server
  - [x] Connection management (connection pool)
  - [x] Message framing and parsing
  - WebSocket authentication intentionally out of scope for Milestone 2
  - [x] Heartbeat/ping-pong for connection health
  
- [x] SimpleSync protocol server implementation
  - [x] Sync request/response handler
  - [x] Root hash computation
  - [x] Missing content detection
  - [x] Conflict detection logic

### Week 4: Client-Side Sync & Offline Support

- [x] WebSocket client (Go-served UI)
  - [x] Connection management with auto-reconnect
  - [x] Message queue for offline periods
  - [x] Reconnection after offline periods
  
- [x] IndexedDB cache layer
  - [x] Store document/page content for offline reads
  - [x] Store sync state and pending changes
  - [x] Simple fixed cap for cached pages/content
  - [x] Preserve pending edits during cache cleanup
  
- [x] File sync UI
  - [x] Sync status indicator
  - [x] Offline mode banner
  - [x] Pending changes list
  - [x] Manual sync trigger button
  
- [x] Conflict detection display
  - [x] Visual indicator for conflicting files
  - [x] Side-by-side diff for server copy vs queued edit
  - [x] Conflict resolution UI with Monaco resolved document editor

## Acceptance Criteria

### Functional
- [x] File changes on disk automatically sync to server within 5 seconds
- [x] Web client receives real-time updates when files change on server
- [x] Client can make changes offline and sync when reconnected
- [x] Concurrent edits to different files succeed without conflict
- [x] Concurrent edits to same file detected as conflict
- [x] Content hash verified on every transfer (client and server)
- [x] 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
- [x] Sync protocol documented with state/flow diagrams

### Performance
- [x] 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

```typescript
// 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. [x] SimpleSync protocol specification document
2. [x] State/flow diagrams for browser sync scenarios
3. [x] WebSocket message documentation
4. [x] 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

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