feat: offline disk overflow and network-aware persistence [rn]

[choudlet]

Summary

PR 2 of 2 of Network Awareness (builds on #24). Adds offline disk overflow, cold-start drain, debounced reachability, and a cleaned-up public capacity API.

Ticket: SC-36910 · Pt. 2: SC-37597

What changed

Offline disk overflow

• Dispatcher overflow callback — when the memory queue hits capacity, evicted events are redirected to PersistentEventQueue via onOverflow instead of being dropped.
• Batched overflow buffer — events accumulate in-memory and flush at a 100-event threshold, avoiding per-event disk I/O.
• Direct disk-to-network drain — on offline→online transition (and at cold start when hasDiskData), overflow events drain directly from disk to network in batches of 100 via sendBatchDirect, bypassing the memory queue. Prevents memory spikes when 10K events need to ship through a 2K queue.
• Dual flush paths on reconnect — memory queue flushes via the existing path; disk overflow drains independently.
• TTL enforcement — events older than 7 days are filtered during drain. Events with unparseable timestamps are preserved (conservative, matches iOS/Android).
• Fatal-config parity — 401/403/404 during drain now fires onFatalConfig and stops the client, matching the main flush path (previously silent delete).

Consolidated disk storage

Collapsed the dual-file (snapshot + overflow-snapshot) JS abstraction into one file backed by queue.v1.json. The overflow-specific native methods were never implemented on iOS/Android — in production the old "offline overflow" path silently dropped events. Consolidation fixes that latent bug by routing all persistence through the single native API that already exists.

• NativeQueueStorage: dropped read/write/deleteOverflowSnapshot; single read/write/deleteSnapshot interface.
• flushToDisk now drains memory and appends to disk (read-merge-cap-write), so memory + disk never double-hold the same events.
• Dispatcher.onFlushToOfflineStorage → onFlushToDisk (no longer offline-specific). New Dispatcher.drainQueue() helper.

Cold-start: no rehydration

Replaced rehydrate-into-memory with a cheap exists() probe so a large on-disk backlog no longer forces an allocation spike on cold start. Memory queue stays empty through init(); disk is drained directly to network when online.

• Native (iOS/Android): new exists() returning a boolean without reading file contents.
• PersistentEventQueue.rehydrate() removed; replaced by checkForPersistedEvents() which sets a hasDiskData flag kept in sync on write/delete/drain.
• getDebugInfo exposes hasDiskData: boolean (replaces rehydratedEvents: number).

Debounced network monitor (2s asymmetric)

New DebouncedNetworkMonitor wraps the raw monitor so consumers see:

• Offline transitions immediately (pause HTTP ASAP — no wasted retries on a down network).
• Online transitions only after 2s of stable connectivity (absorbs WiFi/cellular flaps that would otherwise trigger flush attempts that immediately fail).

A pending online debounce is cancelled if offline arrives during the wait; the window resets on repeated raw online signals. Injected monitors (tests, custom providers) are used as-is.

Public capacity API

Aligns the RN surface with iOS/Android:

Before	After
maxQueueBytes (public)	internal 5MB constant
maxOfflineDiskEvents	maxDiskEvents (public, default 10000)
—	maxQueueEvents (public, default 2000)

• Constructor throws on negative maxDiskEvents (use 0 to disable persistence); silently clamps maxQueueEvents to ≥ 1; warns when a non-zero maxDiskEvents < maxQueueEvents.
• Dispatcher enforces both count and byte caps on enqueue / enqueueFront.
• New isPersistenceEnabled callback: when maxDiskEvents === 0, capacity overflow becomes a ring buffer (drop-oldest one-by-one) instead of splicing the whole queue to a no-op disk handler.
• flush() offline branch skips the splice-to-disk callback when persistence is disabled — events stay in memory for the next foreground retry.
• flushToDisk / flushEventsToDisk are no-ops when maxDiskEvents === 0.

Log phrasing alignment

Matches iOS/Android canonical wording from the port guide so support can grep the same strings across platforms:

• Network status changed: <old> -> <new>
• Dispatcher paused — device is offline
• Dispatcher resumed — device is online, triggering flush

Test plan

• 237/237 tests pass across 16 suites (npx jest)
• TypeScript compiles cleanly
• Overflow: handleOverflow buffers + respects disk cap; flushes at 100-event threshold
• Overflow: flushOverflowBufferToDisk merges with existing disk overflow and enforces cap
• Drain: drainDiskToNetwork sends directly to network without entering memory queue
• Drain: deletes file after completion; stops on network failure; filters expired events
• Drain: FATAL_CONFIG fires onFatalConfig (parity with main flush path)
• Dispatcher: onOverflow fires when queue drops events (replaces warn-and-drop)
• Dispatcher: count-cap overflow parity with byte-cap overflow
• Dispatcher: ring-buffer drop-oldest when persistence disabled (maxDiskEvents=0)
• Cold start: hasDiskData flag stays in sync on write/delete/drain; no unconditional rehydrate
• Debounce: offline immediate, online after 2s, pending online cancelled by offline, repeated online resets window
• Offline→online: dual flush paths (memory + disk) run independently
• Config: throws on negative maxDiskEvents; warns on maxDiskEvents < maxQueueEvents
• Manual: verify iOS NWPathMonitor + disk drain end-to-end in RN app
• Manual: verify Android ConnectivityManager + disk drain end-to-end in RN app