@scalebun/react-native 1.0.2 → 1.0.3

package/lib/module/features/session/BackendSessionAdapter.js

@@ -1,26 +1,26 @@
-/**
- * ScaleBun SDK — Backend Session Adapter
- *
- * Implements the SessionTransport interface (System A) and bridges
- * session/frame/event data to the backend API via HTTP.
- *
- * This is the ADAPTER that connects the existing SessionManager
- * (which only has DesktopSessionTransport) to the backend.
- *
- * Design:
- * - Uses the same endpoint contract as BackendReplayTransport
- *   (POST /v1/replay/sessions, /frames, /events, /finalize)
- * - Batches frames and events with auto-flush
- * - Never throws — all errors are caught and logged
- * - Behind config flag: only constructed when backendUpload is enabled
- *
- * This does NOT duplicate the existing BackendReplayTransport.
- * It exists because SessionManager uses a different interface
- * (SessionTransport from sessionTypes.ts) than ReplayTransport
- * (from features/replay/transport/ReplayTransport.ts).
- * The payload shapes differ, so this adapter maps between them.
- *
- * MVP/dev-only: base64 frames are sent inline in JSON body.
+/**
+ * ScaleBun SDK — Backend Session Adapter
+ *
+ * Implements the SessionTransport interface (System A) and bridges
+ * session/frame/event data to the backend API via HTTP.
+ *
+ * This is the ADAPTER that connects the existing SessionManager
+ * (which only has DesktopSessionTransport) to the backend.
+ *
+ * Design:
+ * - Uses the same endpoint contract as BackendReplayTransport
+ *   (POST /v1/replay/sessions, /frames, /events, /finalize)
+ * - Batches frames and events with auto-flush
+ * - Never throws — all errors are caught and logged
+ * - Behind config flag: only constructed when backendUpload is enabled
+ *
+ * This does NOT duplicate the existing BackendReplayTransport.
+ * It exists because SessionManager uses a different interface
+ * (SessionTransport from sessionTypes.ts) than ReplayTransport
+ * (from features/replay/transport/ReplayTransport.ts).
+ * The payload shapes differ, so this adapter maps between them.
+ *
+ * MVP/dev-only: base64 frames are sent inline in JSON body.
  */
 
 import { logger } from '../../core/logger/internalLogger';
@@ -29,14 +29,18 @@ import { ENDPOINTS } from '../../transport/http/endpoints';
 import { SDK_VERSION } from '../../core/constants/version';
 import { bridgeAdapter } from '../replay/bridge/adapters/bridgeAdapter';
 import { getReplaySdkNative } from '../replay/bridge/nativeModule';
+// Reused rather than reimplemented: `chunkEvents` is generic, order-preserving, and already carries
+// a contract test proving it drops and duplicates nothing (analytics/__tests__/batchChunking.test.ts).
+// Its internal ceiling (MAX_BATCH_EVENTS = 500) is well above the 100-frame cap passed here.
+import { chunkEvents } from '../../analytics/batching';
 
 // ─── Config ─────────────────────────────────────────────────────────────────
 
-/**
- * One platform-agnostic log line for the logs lane. The queue forwards whatever it is
- * given — `source`/`platform` are neutral string hints set by the PRODUCER (console
- * tags 'console'/'js'; a future native producer tags its own values onto this SAME
- * shape). `level` is free-text. Nothing here is JS-specific.
+/**
+ * One platform-agnostic log line for the logs lane. The queue forwards whatever it is
+ * given — `source`/`platform` are neutral string hints set by the PRODUCER (console
+ * tags 'console'/'js'; a future native producer tags its own values onto this SAME
+ * shape). `level` is free-text. Nothing here is JS-specific.
  */
 
 // ─── Adapter ────────────────────────────────────────────────────────────────
@@ -46,8 +50,31 @@ export class BackendSessionAdapter {
 
   /** Storage key for the snapshotted unflushed frame buffer (see persistPendingFrames). */
   static PENDING_FRAMES_KEY = 'scalebun_replay_pending_frames';
-  /** Cap on frames persisted per snapshot — bounds KV footprint (keeps the most recent). */
-  static MAX_PERSIST_FRAMES = 10;
+  /**
+   * Byte budget for the cross-kill frame snapshot (see `_selectFramesToPersist`).
+   *
+   * Replaces a flat 10-frame cap. A count could not bound the KV write at all — these frames carry
+   * base64 screenshots, so ten of them is anywhere from ~200 KB to several MB depending on device
+   * resolution, and an oversized value is exactly what fails on the background transition where
+   * this write happens.
+   *
+   * 2 MB is deliberately modest: this is a last-resort snapshot for frames that never reached the
+   * network, not a mirror of the session. Enough for a keyframe plus a run of deltas on any device;
+   * small enough that writing it cannot itself be the reason backgrounding stalls.
+   */
+  static MAX_PERSIST_BYTES = 2 * 1024 * 1024;
+  /**
+   * Frames the backend accepts in ONE request — `'Max 100 frames per batch'`
+   * (`IngestionService.uploadFrames`). Exceeding it is a 4xx, which this SDK classifies as
+   * permanent.
+   *
+   * This has to exist alongside the byte budget, not instead of it. The budget alone cannot bound
+   * the COUNT, and the count is what the server checks: measured on real traffic, mobile keyframes
+   * average ~16 KB, so a 2 MB snapshot is around 128 frames — over the cap by construction. The old
+   * flat 10-frame rule was under it by construction, which is why this failure could not happen
+   * before and can now.
+   */
+  static MAX_FRAMES_PER_BATCH = 100;
   // Per-session toggle: cleared to false if the backend reports storage disabled.
 
   // True when telemetry should divert to the durable native outbox (both flags on).
@@ -75,6 +102,14 @@ export class BackendSessionAdapter {
   pendingLogs = [];
   flushTimer = null;
   destroyed = false;
+  /**
+   * Latch for `sdk_replay_capture_failed` — reported once per adapter, not once per rejected batch.
+   *
+   * A session whose row was never created rejects EVERY frame batch, so an unlatched report would
+   * emit one analytics event per flush for as long as the app stays open, on the same lane it is
+   * trying to report through.
+   */
+  _captureFailureReported = false;
 
   // ── Analytics lane (always-on, foreground-scoped; isolated from recording) ──
   // Fully separate from currentSessionId/pendingEvents/_flushEvents, which serve
@@ -120,10 +155,10 @@ export class BackendSessionAdapter {
 
   // ─── SessionTransport Interface ─────────────────────────────────────
 
-  /**
-   * §11 gate: true only when the current recording session's INGESTION_START row is
-   * confirmed on the backend. Child telemetry lanes consult this before flushing so they
-   * never race ahead of session creation (which would 404). Null id → not ready.
+  /**
+   * §11 gate: true only when the current recording session's INGESTION_START row is
+   * confirmed on the backend. Child telemetry lanes consult this before flushing so they
+   * never race ahead of session creation (which would 404). Null id → not ready.
    */
   _sessionRowReady() {
     return !!this.currentSessionId && this._startedSessionIds.has(this.currentSessionId);
@@ -240,15 +275,20 @@ export class BackendSessionAdapter {
     return this._analyticsSessionId;
   }
 
-  /**
-   * Open the always-on analytics ingestion session. Sets the analytics id,
-   * starts the analytics flush timer, replays any pre-ready buffered events,
-   * and POSTs INGESTION_START. Mirrors sendSessionStart's body builder but
-   * never touches currentSessionId (recording lane).
+  /**
+   * Open the always-on analytics ingestion session. Sets the analytics id,
+   * starts the analytics flush timer, replays any pre-ready buffered events,
+   * and POSTs INGESTION_START. Mirrors sendSessionStart's body builder but
+   * never touches currentSessionId (recording lane).
    */
   async startAnalyticsSession(session) {
     if (this.destroyed) return;
     this._analyticsSessionId = session.sessionId;
+    // A new session gets its own capture-failure report. The latch bounds reports WITHIN a
+    // session; left standing across sessions it silenced every session after the first in the
+    // app process, which is the one place this differs from the web SDK — that pipeline is
+    // constructed per page and its session id is readonly, so its latch cannot outlive a session.
+    this._captureFailureReported = false;
     this._startAnalyticsFlushTimer();
 
     // Replay pre-ready buffered events now that the id exists. sessionId is
@@ -291,9 +331,9 @@ export class BackendSessionAdapter {
     }
   }
 
-  /**
-   * Enqueue a user track() event. Buffers (bounded, drop-oldest) when the
-   * analytics session is not yet open; flushes at >=20 once it is.
+  /**
+   * Enqueue a user track() event. Buffers (bounded, drop-oldest) when the
+   * analytics session is not yet open; flushes at >=20 once it is.
    */
   trackEvent(event) {
     if (this.destroyed) return;
@@ -307,13 +347,13 @@ export class BackendSessionAdapter {
     }
   }
 
-  /**
-   * Emit an app-lifecycle boundary marker (APP_BACKGROUND / APP_FOREGROUND) onto
-   * the analytics lane so the dashboard can shade the backgrounded span on the
-   * replay timeline and exclude it from the active duration. Timestamp is captured
-   * at the transition (accurate even if delivery is deferred until the next
-   * foreground on iOS). No-op when no analytics session is open. The sessionId is
-   * (re)stamped at flush time, so passing the current id here is only a placeholder.
+  /**
+   * Emit an app-lifecycle boundary marker (APP_BACKGROUND / APP_FOREGROUND) onto
+   * the analytics lane so the dashboard can shade the backgrounded span on the
+   * replay timeline and exclude it from the active duration. Timestamp is captured
+   * at the transition (accurate even if delivery is deferred until the next
+   * foreground on iOS). No-op when no analytics session is open. The sessionId is
+   * (re)stamped at flush time, so passing the current id here is only a placeholder.
    */
   emitLifecycleMarker(type, payload) {
     if (this.destroyed || !this._analyticsSessionId) return;
@@ -329,21 +369,21 @@ export class BackendSessionAdapter {
     });
   }
 
-  /**
-   * Public: force-flush queued analytics events immediately. Called on
-   * APP_BACKGROUND so the lifecycle marker (and any buffered track events) reach
-   * the backend before the OS suspends the flush timer. Best-effort on iOS, where
-   * the POST may not resolve until the next foreground — the events stay buffered
-   * with accurate timestamps and flush then.
+  /**
+   * Public: force-flush queued analytics events immediately. Called on
+   * APP_BACKGROUND so the lifecycle marker (and any buffered track events) reach
+   * the backend before the OS suspends the flush timer. Best-effort on iOS, where
+   * the POST may not resolve until the next foreground — the events stay buffered
+   * with accurate timestamps and flush then.
    */
   flushAnalytics() {
     return this._flushAnalyticsEvents();
   }
 
-  /**
-   * Flush queued analytics events. Mirrors _flushEvents (recording) byte for
-   * byte on the wire map, but gates on _analyticsSessionId and STAMPS that id
-   * into every event so endpoint id == body sessionId by construction.
+  /**
+   * Flush queued analytics events. Mirrors _flushEvents (recording) byte for
+   * byte on the wire map, but gates on _analyticsSessionId and STAMPS that id
+   * into every event so endpoint id == body sessionId by construction.
    */
   async _flushAnalyticsEvents(forSessionId) {
     // finalize clears _analyticsSessionId synchronously, then passes the
@@ -407,14 +447,14 @@ export class BackendSessionAdapter {
     }
   }
 
-  /**
-   * Close any analytics session left open by a suspended background finalize.
-   * Called on the NEXT foreground (SDKBootstrapper app-state 'active') BEFORE a new
-   * analytics session is opened. JS is live on foreground, so this POST completes.
-   * No-op when there is no pending id. Idempotent with the background finalize: the
-   * marker is cleared on a confirmed background ACK, so this only fires when the
-   * background POST was NOT confirmed; if that suspended POST later also lands, the
-   * server must treat a repeat INGESTION_FINALIZE for the same id as a no-op.
+  /**
+   * Close any analytics session left open by a suspended background finalize.
+   * Called on the NEXT foreground (SDKBootstrapper app-state 'active') BEFORE a new
+   * analytics session is opened. JS is live on foreground, so this POST completes.
+   * No-op when there is no pending id. Idempotent with the background finalize: the
+   * marker is cleared on a confirmed background ACK, so this only fires when the
+   * background POST was NOT confirmed; if that suspended POST later also lands, the
+   * server must treat a repeat INGESTION_FINALIZE for the same id as a no-op.
    */
   async reconcilePendingFinalize() {
     const sessionId = this._pendingFinalizeId;
@@ -507,10 +547,10 @@ export class BackendSessionAdapter {
     return this._flushErrors();
   }
 
-  /**
-   * Public: flush ALL recording-lane queues immediately. Called on APP_BACKGROUND
-   * so the server-side reaper computes endedAt from the freshest data even when
-   * the OS suspends the flush timer right after backgrounding.
+  /**
+   * Public: flush ALL recording-lane queues immediately. Called on APP_BACKGROUND
+   * so the server-side reaper computes endedAt from the freshest data even when
+   * the OS suspends the flush timer right after backgrounding.
    */
   async flushAll() {
     await Promise.all([this._flushFrames(), this._flushEvents(), this._flushNetwork(), this._flushErrors(), this._flushPerformance(), this._flushLogs()]);
@@ -530,11 +570,11 @@ export class BackendSessionAdapter {
     }
   }
 
-  /**
-   * Queue one log line onto the platform-agnostic logs lane. Mirrors
-   * queueNetworkRequest: drop when not in SaaS mode (no clientKey) or destroyed,
-   * batch-flush at LOGS_BATCH_SIZE. The producer supplies source/platform/level —
-   * this method makes NO assumptions about them, so a native producer reuses it as-is.
+  /**
+   * Queue one log line onto the platform-agnostic logs lane. Mirrors
+   * queueNetworkRequest: drop when not in SaaS mode (no clientKey) or destroyed,
+   * batch-flush at LOGS_BATCH_SIZE. The producer supplies source/platform/level —
+   * this method makes NO assumptions about them, so a native producer reuses it as-is.
    */
   queueLog(data) {
     if (this.destroyed || !this.config.clientKey) return;
@@ -560,11 +600,11 @@ export class BackendSessionAdapter {
 
   // ─── Native outbox routing ──────────────────────────────────────────
 
-  /**
-   * Hand a telemetry batch to the durable native outbox. Returns true if native
-   * accepted it (native uploader now owns delivery — caller must NOT also POST).
-   * Returns false on any miss (flag off, no session, old binary, native error) so
-   * the caller falls back to the JS HTTP path with the batch intact.
+  /**
+   * Hand a telemetry batch to the durable native outbox. Returns true if native
+   * accepted it (native uploader now owns delivery — caller must NOT also POST).
+   * Returns false on any miss (flag off, no session, old binary, native error) so
+   * the caller falls back to the JS HTTP path with the batch intact.
    */
   async _enqueueNative(lane, records) {
     if (!this.nativeOutboxEnabled || !this.currentSessionId) return false;
@@ -578,12 +618,12 @@ export class BackendSessionAdapter {
     }
   }
 
-  /**
-   * Bootstrap the native outbox once. In SaaS mode the native module's full
-   * `initialize()` (which builds a SessionManager) is never called, so the
-   * NativeOutbox/uploader would not exist. `initOutbox` constructs only the
-   * durable outbox from clientKey/apiBaseUrl/flags. Idempotent + cached so it
-   * runs at most once; resolves false on old binaries (caller falls back to JS).
+  /**
+   * Bootstrap the native outbox once. In SaaS mode the native module's full
+   * `initialize()` (which builds a SessionManager) is never called, so the
+   * NativeOutbox/uploader would not exist. `initOutbox` constructs only the
+   * durable outbox from clientKey/apiBaseUrl/flags. Idempotent + cached so it
+   * runs at most once; resolves false on old binaries (caller falls back to JS).
    */
   _ensureNativeOutbox(native) {
     if (this._nativeOutboxReady) return this._nativeOutboxReady;
@@ -599,11 +639,11 @@ export class BackendSessionAdapter {
     return this._nativeOutboxReady;
   }
 
-  /**
-   * Public readiness gate for the native frame outbox path (used by the frame
-   * capture adapter). Resolves true only when both outbox flags are on, a session
-   * exists, the native binary exposes the bridge, and `initOutbox` succeeded.
-   * Resolves false otherwise so the frame pipeline falls back to `captureScreenshot`.
+  /**
+   * Public readiness gate for the native frame outbox path (used by the frame
+   * capture adapter). Resolves true only when both outbox flags are on, a session
+   * exists, the native binary exposes the bridge, and `initOutbox` succeeded.
+   * Resolves false otherwise so the frame pipeline falls back to `captureScreenshot`.
    */
   ensureNativeOutboxReady() {
     if (!this.nativeOutboxEnabled || !this.currentSessionId) return Promise.resolve(false);
@@ -669,14 +709,14 @@ export class BackendSessionAdapter {
     };
   }
 
-  /**
-   * P2-4: build the lean (v2) wire payload for one event. Drops redundant/empty
-   * fields at the source while NEVER dropping fields the dashboard/analytics depend
-   * on (eventId, type, timestamp, sessionId). `label` is omitted when it equals
-   * `type` (the server defaults it back). `screenName` omitted when empty. `data`
-   * is pruned of null/''/undefined leaves (one level). The `v:2` marker lets the
-   * backend/dashboard pick the lean decoder; legacy (v1/no-marker) events still
-   * decode unchanged. See P2_CONTRACT.md §4.
+  /**
+   * P2-4: build the lean (v2) wire payload for one event. Drops redundant/empty
+   * fields at the source while NEVER dropping fields the dashboard/analytics depend
+   * on (eventId, type, timestamp, sessionId). `label` is omitted when it equals
+   * `type` (the server defaults it back). `screenName` omitted when empty. `data`
+   * is pruned of null/''/undefined leaves (one level). The `v:2` marker lets the
+   * backend/dashboard pick the lean decoder; legacy (v1/no-marker) events still
+   * decode unchanged. See P2_CONTRACT.md §4.
    */
   _leanEvent(e, sessionId) {
     const out = {
@@ -714,29 +754,114 @@ export class BackendSessionAdapter {
     if (!this._sessionRowReady()) return;
     const sessionId = this.currentSessionId;
     const batch = this.pendingFrames.splice(0, this.config.batchSize);
-    try {
-      await this._postFrameBatch(sessionId, batch);
-      logger.debug(`[BackendSessionAdapter] Flushed ${batch.length} frame(s)`);
-      // Delivered — the durable snapshot (if any) is now redundant. Clear it once
-      // the in-memory buffer is fully drained so a later kill can't replay
-      // already-uploaded frames.
-      if (this.pendingFrames.length === 0) this._clearPersistedFrames();
-    } catch (err) {
-      if (BackendSessionAdapter._isPermanentHttpError(err)) return;
+    /**
+     * Chunked, because `config.batchSize` is HOST-CONFIGURABLE and the server's 100-frame cap is
+     * not. A host raising it past 100 previously turned every frame flush into a permanent 4xx —
+     * silent, total replay loss for that app, from a config value that looks like a tuning knob.
+     *
+     * A permanent rejection is reported and abandoned inside `_postFramesChunked`; what comes
+     * back is only what is still worth another attempt.
+     */
+    const remaining = await this._postFramesChunked(sessionId, batch);
+    if (remaining.length) {
       logger.warn(`[replay.sdk.error] backend frame upload failure`, {
-        count: batch.length
+        count: remaining.length
       });
-      // Re-queue on failure
-      this.pendingFrames.unshift(...batch);
+      this.pendingFrames.unshift(...remaining);
+      return;
     }
+    logger.debug(`[BackendSessionAdapter] Flushed ${batch.length} frame(s)`);
+    // Delivered — the durable snapshot (if any) is now redundant. Clear it once
+    // the in-memory buffer is fully drained so a later kill can't replay
+    // already-uploaded frames.
+    if (this.pendingFrames.length === 0) this._clearPersistedFrames();
   }
 
-  /**
-   * POST one frame batch under an EXPLICIT sessionId (object-storage path when
-   * active, else legacy inline base64). Used by both the live flush and cross-kill
-   * recovery — recovery passes the PRIOR session's id so orphaned frames relink to
-   * it. Throws on transient error so the caller can re-queue; frame writes are
-   * idempotent server-side (upsert by frameId), so a double-send is harmless.
+  /**
+   * Report frames the SDK gave up on, on the analytics lane.
+   *
+   * SAME EVENT NAME AS THE WEB SDK (`sdk_replay_capture_failed`) with platform-specific `reason`
+   * values, so one dashboard breakdown reads both platforms without a concept-map alias — the two
+   * SDKs share no event vocabulary otherwise (`$pageview` vs `screen_viewed`), and adding a second
+   * name here would need an entry in `event-concepts.ts` for no benefit.
+   *
+   * Latched to once per session: a session whose row was never created rejects every batch, and an
+   * unlatched report would emit one event per flush for as long as the app is open.
+   *
+   * Best-effort and never throws — a diagnostic must not be able to break the capture path it
+   * describes.
+   */
+  _reportCaptureFailure(stage, err, frameCount) {
+    if (this._captureFailureReported) return;
+    this._captureFailureReported = true;
+    try {
+      if (!this._analyticsSessionId) return; // no lane open — nothing to attach it to
+      const status = err?.status;
+      this.trackEvent({
+        eventId: this._clientId(),
+        sessionId: this._analyticsSessionId,
+        ts: Date.now(),
+        type: 'sdk_replay_capture_failed',
+        source: 'sdk',
+        payload: {
+          stage,
+          // Platform-specific vocabulary. The HTTP status is the honest reason on this path:
+          // RN posts to the per-lane endpoints, which surface a real status — unlike the web
+          // batch fan-out, whose 200 says nothing about what it stored.
+          reason: status ? `http_${status}` : 'upload_failed',
+          frames: frameCount,
+          platform: 'react-native'
+        }
+      });
+    } catch {
+      // Diagnostics must never break the capture path.
+    }
+  }
+
+  /**
+   * Post frames in BACKEND-SAFE CHUNKS, and return the ones that were not durably accepted.
+   *
+   * WHY THIS EXISTS. `_postFrameBatch` issues exactly one request for whatever array it is handed,
+   * and both callers could hand it more than the server's 100-frame cap — the live flush via
+   * `config.batchSize`, and cross-kill recovery via the 2 MB persistence budget (~128 frames at the
+   * measured 16 KB average). The result was a 4xx, classified permanent, and on the recovery path
+   * that meant `_clearPersistedFrames()` — the ENTIRE cross-kill snapshot deleted because it was
+   * one frame too big to send in a single request it never needed to be sent in.
+   *
+   * THE RETURN VALUE IS THE POINT. The caller must be able to delete exactly what landed and keep
+   * exactly what did not, so this reports the survivors rather than throwing:
+   *   - chunk accepted            → dropped from the result (it is durably stored)
+   *   - chunk PERMANENTLY refused → dropped, and reported once. Re-sending identical bytes cannot
+   *                                 succeed, and holding it would wedge every future launch on the
+   *                                 same poison chunk. Only that chunk is abandoned; the rest still
+   *                                 gets its chance, which is the whole difference from before.
+   *   - chunk TRANSIENTLY failed  → that chunk AND every chunk after it are kept, in order. We stop
+   *                                 on the first transient failure rather than pressing on, because
+   *                                 the usual cause is the network being gone and the rest would
+   *                                 fail identically.
+   */
+  async _postFramesChunked(sessionId, items) {
+    const chunks = chunkEvents(items, BackendSessionAdapter.MAX_FRAMES_PER_BATCH);
+    for (let i = 0; i < chunks.length; i++) {
+      try {
+        await this._postFrameBatch(sessionId, chunks[i]);
+      } catch (err) {
+        if (BackendSessionAdapter._isPermanentHttpError(err)) {
+          this._reportCaptureFailure('upload-rejected', err, chunks[i].length);
+          continue;
+        }
+        return chunks.slice(i).flat();
+      }
+    }
+    return [];
+  }
+
+  /**
+   * POST one frame batch under an EXPLICIT sessionId (object-storage path when
+   * active, else legacy inline base64). Used by both the live flush and cross-kill
+   * recovery — recovery passes the PRIOR session's id so orphaned frames relink to
+   * it. Throws on transient error so the caller can re-queue; frame writes are
+   * idempotent server-side (upsert by frameId), so a double-send is harmless.
    */
   async _postFrameBatch(sessionId, batch) {
     if (batch.length === 0) return;
@@ -775,17 +900,18 @@ export class BackendSessionAdapter {
   // KV store on background (survives kill), then re-upload it on the NEXT launch
   // linked to the PRIOR session id. Best-effort and never throws.
 
-  /**
-   * Snapshot the current unflushed frame buffer to durable storage so it survives
-   * a process kill. Called on APP_BACKGROUND before the (possibly-suspended)
-   * network flush. Synchronous mirror write — reaches disk on the native store's
-   * next coalesced flush. No-op if recovery storage is absent or nothing pending.
+  /**
+   * Snapshot the current unflushed frame buffer to durable storage so it survives
+   * a process kill. Called on APP_BACKGROUND before the (possibly-suspended)
+   * network flush. Synchronous mirror write — reaches disk on the native store's
+   * next coalesced flush. No-op if recovery storage is absent or nothing pending.
    */
   persistPendingFrames() {
     if (!this._frameStore || this.destroyed || !this.currentSessionId) return;
     if (this.pendingFrames.length === 0) return;
     try {
-      const items = this.pendingFrames.slice(-BackendSessionAdapter.MAX_PERSIST_FRAMES);
+      const items = BackendSessionAdapter._selectFramesToPersist(this.pendingFrames);
+      if (items.length === 0) return;
       this._frameStore.set(BackendSessionAdapter.PENDING_FRAMES_KEY, JSON.stringify({
         sessionId: this.currentSessionId,
         items
@@ -795,6 +921,67 @@ export class BackendSessionAdapter {
     }
   }
 
+  /**
+   * Choose which unflushed frames survive a process kill.
+   *
+   * WHY THIS IS NOT `slice(-10)`.
+   *
+   * The old rule kept the ten most RECENT frames, which is the wrong end of the buffer for replay.
+   * A delta reconstructs against its base keyframe, so ten trailing deltas whose keyframe was
+   * dropped are unplayable on their own — they arrive as `orphaned`, the state the dashboard flags
+   * as a capture defect. Keeping the keyframe and fewer deltas yields a SHORTER replay; keeping the
+   * deltas and no keyframe yields NO replay. That asymmetry is the whole decision.
+   *
+   * So: every keyframe is kept, then the most recent deltas fill whatever byte budget is left. This
+   * mirrors the web SDK's `capBytes` policy (which sheds deltas first and never the keyframe), so
+   * the two platforms lose the same thing under pressure instead of two different things.
+   *
+   * BYTES, not a frame count. A count is a poor proxy here: these carry base64 screenshots, so ten
+   * frames may be 200 KB or 4 MB depending on device resolution — and this write goes to a KV store
+   * on the background transition, where an oversized value is the thing most likely to fail and
+   * lose the snapshot entirely. `imageData.length` is the base64 length, which is within ~1% of the
+   * serialized cost and needs no extra pass.
+   */
+  static _selectFramesToPersist(pending) {
+    const isKeyframe = b => b.frame.frameType !== 'delta';
+    const size = b => b.imageData?.length ?? 0;
+    const keep = [];
+    let budget = BackendSessionAdapter.MAX_PERSIST_BYTES;
+    /**
+     * A COUNT cap as well as a byte budget.
+     *
+     * The byte budget is the right bound for the KV write; it is the wrong bound for the upload,
+     * because the server checks a count. Recovery now chunks, so exceeding this is no longer
+     * destructive — but persisting more than can ever be sent in one pass just guarantees leftover
+     * work on every launch, and the frames past this point are the least valuable ones anyway.
+     */
+    const maxCount = BackendSessionAdapter.MAX_FRAMES_PER_BATCH;
+
+    // Keyframes first, newest back to oldest — a later keyframe supersedes an earlier one, so if
+    // only one fits it should be the one closest to what the user last saw.
+    for (let i = pending.length - 1; i >= 0; i--) {
+      const b = pending[i];
+      if (!isKeyframe(b)) continue;
+      const cost = size(b);
+      if (cost > budget || keep.length >= maxCount) continue;
+      budget -= cost;
+      keep.push(b);
+    }
+    // Then the most recent deltas with what remains.
+    for (let i = pending.length - 1; i >= 0; i--) {
+      const b = pending[i];
+      if (isKeyframe(b)) continue;
+      const cost = size(b);
+      if (cost > budget || keep.length >= maxCount) continue;
+      budget -= cost;
+      keep.push(b);
+    }
+
+    // Restore capture order: the backend orders frames by `sequenceNumber`, and the recovery POST
+    // re-sends this array as-is.
+    return keep.sort((a, b) => (a.frame.sequenceNumber ?? 0) - (b.frame.sequenceNumber ?? 0));
+  }
+
   /** Drop the persisted frame snapshot (after successful delivery). Never throws. */
   _clearPersistedFrames() {
     if (!this._frameStore) return;
@@ -805,12 +992,12 @@ export class BackendSessionAdapter {
     }
   }
 
-  /**
-   * On cold launch: if a prior run left an unflushed frame snapshot, re-upload it
-   * linked to that PRIOR session, then clear it. Runs independently of the new
-   * session (uses the stored id + a direct POST, bypassing the row-ready gate —
-   * the prior session row already exists server-side). Best-effort; on transient
-   * failure the snapshot is kept for the next launch.
+  /**
+   * On cold launch: if a prior run left an unflushed frame snapshot, re-upload it
+   * linked to that PRIOR session, then clear it. Runs independently of the new
+   * session (uses the stored id + a direct POST, bypassing the row-ready gate —
+   * the prior session row already exists server-side). Best-effort; on transient
+   * failure the snapshot is kept for the next launch.
    */
   async recoverPersistedFrames() {
     if (!this._frameStore) return;
@@ -835,25 +1022,42 @@ export class BackendSessionAdapter {
       this._clearPersistedFrames();
       return;
     }
-    try {
-      logger.info(`[replay.sdk.frame] recovering ${items.length} frame(s) for prior session ${sessionId}`);
-      await this._postFrameBatch(sessionId, items);
+    logger.info(`[replay.sdk.frame] recovering ${items.length} frame(s) for prior session ${sessionId}`);
+    /**
+     * DELETE ONLY WHAT WAS ACCEPTED.
+     *
+     * This posted every recovered frame in ONE request and, on any permanent rejection, deleted
+     * the whole snapshot. Since the persistence budget is 2 MB of ~16 KB frames, that request was
+     * routinely over the server's 100-frame cap — so the common outcome was a 4xx followed by the
+     * deletion of a cross-kill recovery snapshot in which every frame was individually fine. The
+     * one thing a recovery buffer must never do.
+     *
+     * Now the send is chunked and only the unaccepted remainder survives. A chunk the server will
+     * never take is abandoned inside `_postFramesChunked` (and reported), so a single poison chunk
+     * cannot wedge every future launch — but a transient failure keeps its frames for next time.
+     */
+    const remaining = await this._postFramesChunked(sessionId, items);
+    if (remaining.length === 0) {
       this._clearPersistedFrames();
-    } catch (err) {
-      if (BackendSessionAdapter._isPermanentHttpError(err)) {
-        // Server rejected permanently (e.g. session gone) — don't retry forever.
-        this._clearPersistedFrames();
-        return;
-      }
-      // Transient — keep the snapshot for the next launch.
-      logger.warn(`[replay.sdk.frame] prior-session frame recovery deferred (transient)`);
+      return;
+    }
+    logger.warn(`[replay.sdk.frame] prior-session frame recovery deferred`, {
+      kept: remaining.length
+    });
+    try {
+      this._frameStore.set(BackendSessionAdapter.PENDING_FRAMES_KEY, JSON.stringify({
+        sessionId,
+        items: remaining
+      }));
+    } catch {
+      // Re-writing the trimmed snapshot is best-effort; the original is still on disk.
     }
   }
 
-  /**
-   * Upload a batch via object storage. Returns 'sent' on success, 'disabled' if
-   * the backend reports storage is not configured (caller falls back to inline).
-   * Throws on transient error so the caller re-queues the batch.
+  /**
+   * Upload a batch via object storage. Returns 'sent' on success, 'disabled' if
+   * the backend reports storage is not configured (caller falls back to inline).
+   * Throws on transient error so the caller re-queues the batch.
    */
   async _uploadFramesViaStorage(sessionId, batch) {
     const presignReq = batch.map(b => {
@@ -1059,10 +1263,10 @@ export class BackendSessionAdapter {
     }
   }
 
-  /**
-   * POST that parses and returns the JSON response body. Mirrors _post's headers
-   * and timeout handling; used by the object-storage presign request, which needs
-   * the returned upload URLs (the void _post discards the body).
+  /**
+   * POST that parses and returns the JSON response body. Mirrors _post's headers
+   * and timeout handling; used by the object-storage presign request, which needs
+   * the returned upload URLs (the void _post discards the body).
    */
   async _postReturning(path, body) {
     const url = `${this.config.endpoint}${path}`;
@@ -1093,10 +1297,10 @@ export class BackendSessionAdapter {
     }
   }
 
-  /**
-   * PUT raw image bytes directly to a presigned storage URL. Decodes the base64
-   * frame payload to a binary Blob so the wire body is bytes, not a base64 string.
-   * No client key header — the presigned URL carries its own auth.
+  /**
+   * PUT raw image bytes directly to a presigned storage URL. Decodes the base64
+   * frame payload to a binary Blob so the wire body is bytes, not a base64 string.
+   * No client key header — the presigned URL carries its own auth.
    */
   async _putBytes(uploadUrl, base64, contentType) {
     // RN-safe base64→binary: decode to a Uint8Array and send that as the body.