feat(realtime): resilient realtime transport — unified reconnection, heartbeat and backpressure

[Nimatstar]

Summary

This PR resolves #1143 — a cross-cutting refactor of the realtime layer.

The realtime layer was fragmented across three independent implementations (src/lib/websocketManager.ts, src/lib/notifications/socket.ts, src/lib/graphql/subscriptions.ts), each with its own connect/reconnect loop, inconsistent backoff, no shared heartbeat and no backpressure. Messages emitted while disconnected were silently dropped, and store convergence could permanently miss events from the reconnect gap.

Changes

• src/lib/realtime/connectionSupervisor.ts (new): transport-agnostic ConnectionSupervisor providing a unified lifecycle — connect, exponential backoff with full jitter, heartbeat with ping-timeout detection, a single unified ConnectionStatus shape, a bounded outbound queue with documented drop-oldest/block backpressure, inbound sequence tracking with catch-up, a resubscribe registry, and reconnection metrics (reconnect_attempt, reconnect_success, heartbeat_timeout, queue_dropped, realtime_offline) with an alert threshold. Once max attempts are exceeded it degrades to offline mode, signalled through the service worker.
• src/lib/websocketManager.ts: delegates connect/reconnect/heartbeat/queue to the supervisor; adds send() (queued, ordered) and joinRoom() (auto re-join after reconnect) while keeping the existing public API.
• src/lib/notifications/socket.ts: delegates lifecycle to the supervisor; same public API and status shape.
• src/lib/graphql/subscriptions.ts: drives the graphql-ws socket through the supervisor with lazy connect and automatic re-subscribe of registered subscriptions after reconnect; exposes subscribeRealtime().
• src/hooks/useRealtimeConnection.ts (new): single unified connection status hook, adopted by useWebSocket, useCollaboration and useRealTimeAnalytics.
• src/store/synchronizationEngine.ts: consumes the supervisor's onReconnect catch-up hook to re-broadcast state after a reconnect gap.
• src/lib/monitoring/metrics.ts / alerts.ts: realtime metric helper and alert on repeated reconnect failure / heartbeat timeout.
• src/serviceWorker.ts + public/sw.js: handle the REALTIME_OFFLINE signal and broadcast it to clients.
• src/constants/app.constants.ts: realtime constants (backoff, heartbeat, queue, offline event).
• Tests: src/lib/realtime/__tests__/connectionSupervisor.test.ts covering backoff-with-jitter scheduling, heartbeat-timeout-triggered reconnect, queue flush ordering, drop-oldest/block policies, sequence-gap catch-up, resubscribe after a drop, and offline degradation. Also fixed a pre-existing mock constructibility bug in src/lib/graphql/subscriptions.test.ts that failed under Node 24.

Acceptance criteria

• ✅ All three transports reconnect through the single supervisor (jittered backoff + shared heartbeat)
• ✅ Messages sent while disconnected are queued (bounded) and flushed in order on reconnect; overflow follows the documented policy
• ✅ GraphQL subscriptions and socket rooms are automatically restored after reconnect; catch-up path recovers missed events
• ✅ Single unified connection status available to all consumer hooks; reconnection metrics + alert emitted
• ✅ Tests cover the backoff schedule, heartbeat-triggered reconnect, queue flush ordering and resubscribe

Closes #1143

[RUKAYAT-CODER]

Thank you for contributing to the project.