feat(sync): Real-time cloud synchronization for listening history and playback progress

[ashwkun]

Overview & Motivation

Listeners frequently switch between multiple devices (e.g., phone during a commute, tablet or desktop at home). While boxlore maintains accurate local listening history in Room, multi-device continuity requires reliable, low-latency cloud synchronization for playback progress and episode completion states.

Architectural Context

• Backend: The Netcup stack runs boxlore-sync-db (PostgreSQL 16 with Row-Level Security) and boxlore-sync-api (Fastify microservice).
• Client: Interacts via BoxLoreCloudSyncService and persists state locally in PlaybackHistoryEntity / Room database.

Proposed Scope

1. Progress Delta Synchronization:
   • Push playback progress updates to sync-api using an intelligent, battery-efficient debounce strategy:
     • Every 30–60 seconds during active playback.
     • Immediately upon Pause, Seek, Episode Completion, or App Backgrounding.
   • Sync payload schema: episode_id, podcast_id, position_ms, duration_ms, is_completed, updated_at.
2. Conflict Resolution (Last-Write-Wins with Monotonic Progress):
   • When synchronizing across devices, resolve conflicting positions using updated_at timestamps.
   • If an episode is marked as completed on any device, preserve the completed state unless the user explicitly taps "Mark as Unplayed".
3. Offline-First Resilience:
   • All playback events commit locally to Room first.
   • Pending sync actions queue in a local sync outbox and flush automatically via WorkManager once network connectivity is restored.
4. Bandwidth & Battery Protection:
   • Throttle progress pings when on metered cellular networks; batch non-urgent history items.

Acceptance Criteria

• Pausing an episode on Device A updates the remote database within seconds.
• Device B receives and displays the updated playback progress when opened.
• Full offline playback continues uninterrupted; outbox flushes cleanly when online.
• Conflict resolution tests verify that the latest timestamp reliably wins without corrupting local Room state.
• JVM unit tests in :core:catalog / sync module verify delta generation and conflict resolution logic.