@scalebun/react-native 1.0.2 → 1.0.4

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);
@@ -152,6 +187,7 @@ export class BackendSessionAdapter {
     // Falls back to metadata-only if bridge unavailable (old native binary).
     bridgeAdapter.getDeviceInfo().then(nativeInfo => {
       const m = session.metadata;
+      this._cachedAppVersion = nativeInfo?.appVersion ?? m?.appVersion ?? null;
       const payload = {
         sessionId: session.sessionId,
         deviceId: session.deviceId,
@@ -240,15 +276,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
@@ -258,6 +299,7 @@ export class BackendSessionAdapter {
     try {
       const nativeInfo = await bridgeAdapter.getDeviceInfo();
       const m = session.metadata;
+      this._cachedAppVersion = nativeInfo?.appVersion ?? m?.appVersion ?? null;
       const payload = {
         sessionId: session.sessionId,
         deviceId: session.deviceId,
@@ -291,9 +333,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 +349,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 +371,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 +449,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;
@@ -490,11 +532,31 @@ export class BackendSessionAdapter {
       this._flushNetwork().catch(() => {});
     }
   }
+
+  // D8/D9/D12: this signature was {type, message, stack, screenName} — four
+  // fields — while the backend row and every dashboard surface were already
+  // built for the rest. The consequences of the four-field bottleneck:
+  // regression detection permanently false (no appVersion on any mobile
+  // error), Issue.primaryPlatform NULL for every RN crash (no platform), and
+  // native crash signal/thread/exception-type discarded one call before the
+  // wire (no metadata). The receiver needed nothing; only this signature did.
+  /** App version resolved at session start; errors stamp it so regression
+   *  detection has a version to work with (D8). Null until a session starts. */
+  _cachedAppVersion = null;
+  _appVersion() {
+    return this._cachedAppVersion ?? undefined;
+  }
   queueError(data) {
     if (this.destroyed || !this.config.clientKey) return;
     this.pendingErrors.push({
       ...data,
-      clientId: this._clientId(),
+      // The session already knows the app version — never make a crash
+      // reporter's callers supply what the transport can fill itself.
+      appVersion: data.appVersion ?? this._appVersion(),
+      // A recovered crash brings its OWN clientId — the stable id written when the crash was
+      // first persisted. Generating a fresh one here would mint a new identity on every retry
+      // and defeat the unique constraint the backend dedupes with.
+      clientId: data.clientId ?? this._clientId(),
       timestamp: new Date().toISOString()
     });
     if (this.pendingErrors.length >= 10) {
@@ -502,15 +564,20 @@ export class BackendSessionAdapter {
     }
   }
 
-  /** Public: force-flush queued errors immediately (handled-error delivery). */
+  /**
+   * Public: force-flush queued errors immediately (handled-error delivery).
+   *
+   * @returns whether the batch was DURABLY accepted. Crash recovery deletes its on-disk record on
+   *          this answer, so it must reflect the backend and not merely that the call returned.
+   */
   flushErrors() {
     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 +597,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,30 +627,40 @@ 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,
+  /**
+   * Session to enqueue UNDER. Defaults to the current one, which is right for every live lane.
+   *
+   * A recovered native crash must override it. Without this parameter the outbox stamped
+   * `currentSessionId` on everything, so with the outbox enabled a recovered crash was filed
+   * against the session created after the restart — the exact defect the routing above exists
+   * to prevent, reappearing through a path that routing never touched.
    */
-  async _enqueueNative(lane, records) {
-    if (!this.nativeOutboxEnabled || !this.currentSessionId) return false;
+  targetSessionId) {
+    const sessionId = targetSessionId || this.currentSessionId;
+    if (!this.nativeOutboxEnabled || !sessionId) return false;
     const native = getReplaySdkNative();
     if (!native?.enqueueOutboxRecords) return false;
     if (!(await this._ensureNativeOutbox(native))) return false;
     try {
-      return await native.enqueueOutboxRecords(lane, this.currentSessionId, records);
+      return await native.enqueueOutboxRecords(lane, sessionId, records);
     } catch {
       return false;
     }
   }
 
-  /**
-   * 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 +676,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 +746,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 = {
@@ -690,6 +767,17 @@ export class BackendSessionAdapter {
     if (screen) out.screenName = screen;
     const label = e.subtype ?? e.type;
     if (label && label !== e.type) out.label = label;
+    /**
+     * THIS MAPPER ENUMERATES. Every field the wire carries has to be named here, so a field
+     * added to JourneyEvent and not added here is dropped silently — no error, no warning, and
+     * nothing downstream can tell the difference between "the SDK did not send it" and "the
+     * user never produced it". `frameId` was exactly that case: the column, the DTO field and
+     * the ingest write all existed already, and the value died on this line.
+     *
+     * Omitted when absent rather than sent as null, matching how screenName and label behave
+     * above — the v2 lean shape drops empty fields and the server reconstructs them.
+     */
+    if (e.frameId) out.frameId = e.frameId;
     const data = this._pruneEmpty(e.payload);
     if (data && Object.keys(data).length > 0) out.data = data;
     return out;
@@ -714,29 +802,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
+      });
+      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();
+  }
+
+  /**
+   * 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'
+        }
       });
-      // Re-queue on failure
-      this.pendingFrames.unshift(...batch);
+    } catch {
+      // Diagnostics must never break the capture path.
     }
   }
 
-  /**
-   * 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.
+  /**
+   * 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 +948,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 +969,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 +1040,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 +1070,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 => {
@@ -942,20 +1194,89 @@ export class BackendSessionAdapter {
       if (!BackendSessionAdapter._isPermanentHttpError(err)) this.pendingNetworkRequests.unshift(...batch);
     }
   }
+
+  /**
+   * D11: deliver a bug report to the SAME ingest the web SDK uses
+   * (`POST /ingestion/sessions/:id/bug-reports`). Fire-and-forget with one
+   * retry deferral: RN previously had NO path to this endpoint at all —
+   * `reportBug()` emitted an analytics event no handler consumed, so the
+   * bug-reports page was empty forever for every RN app.
+   */
+  submitBugReport(report) {
+    if (this.destroyed || !this.config.clientKey || !this.currentSessionId) return;
+    void this._post(`/ingestion/sessions/${this.currentSessionId}/bug-reports`, {
+      ...report,
+      timestamp: Date.now()
+    }).catch(() => {
+      /* best-effort; the $bug_report analytics breadcrumb still records intent */
+    });
+  }
+
+  /**
+   * @returns TRUE only when every group in this batch was DURABLY accepted — an HTTP 2xx, or a
+   *          handoff to the native outbox, which is itself a persistent retrying queue.
+   *
+   * The return value is not cosmetic: `drainNativeCrash` deletes the on-disk crash record on the
+   * strength of it. This method used to return `void` and swallow its own errors in the catch
+   * below, so "the promise resolved" meant nothing at all — a failed POST looked exactly like a
+   * successful one, and the caller would have deleted the only durable copy of a crash that never
+   * arrived. Anything less than a real acknowledgement here reintroduces the loss this whole
+   * change exists to prevent.
+   */
   async _flushErrors() {
-    if (this.pendingErrors.length === 0 || !this.currentSessionId || !this.config.clientKey) return;
+    if (this.pendingErrors.length === 0 || !this.currentSessionId || !this.config.clientKey) return false;
     const batch = this.pendingErrors.splice(0, 20);
     try {
-      if (await this._enqueueNative('errors', batch)) return;
       if (!this._sessionRowReady()) {
         this.pendingErrors.unshift(...batch);
-        return;
+        return false;
       }
-      await this._post(ENDPOINTS.INGESTION_ERRORS(this.currentSessionId), {
-        errors: batch
-      });
+      /**
+       * ROUTED BY THE ERROR'S OWN SESSION, not by whichever session is current.
+       *
+       * A recovered native crash carries the id of the session it actually happened in — that
+       * process is gone, so the current session is the wrong owner. Sending it under
+       * `currentSessionId` is what marked a healthy session crashed and left the crashed one
+       * looking clean.
+       *
+       * The URL still carries a session because that is the established ingest shape; the
+       * error's own `sessionId` simply chooses WHICH one. Errors are grouped by their target
+       * so a batch mixing a recovered crash with live errors cannot drag the live ones onto
+       * the dead session.
+       */
+      const byTarget = new Map();
+      for (const e of batch) {
+        const target = e.sessionId || this.currentSessionId;
+        byTarget.set(target, [...(byTarget.get(target) ?? []), e]);
+      }
+      let allAccepted = true;
+      for (const [target, errors] of byTarget) {
+        // `sessionId` is a routing instruction, not payload — strip it so the stored row is
+        // byte-identical to one sent the ordinary way.
+        const cleaned = errors.map(({
+          sessionId: _s,
+          ...rest
+        }) => rest);
+
+        // The outbox is enqueued PER TARGET, so a recovered crash keeps its own session.
+        if (await this._enqueueNative('errors', cleaned, target)) continue;
+        try {
+          await this._post(ENDPOINTS.INGESTION_ERRORS(target), {
+            errors: cleaned
+          });
+        } catch (err) {
+          allAccepted = false;
+          // A permanent error (4xx) will never succeed, so re-queuing it would spin
+          // forever; anything else is worth another attempt.
+          if (!BackendSessionAdapter._isPermanentHttpError(err)) {
+            this.pendingErrors.unshift(...errors);
+          }
+        }
+      }
+      return allAccepted;
     } catch (err) {
       if (!BackendSessionAdapter._isPermanentHttpError(err)) this.pendingErrors.unshift(...batch);
+      return false;
     }
   }
   async _flushPerformance() {
@@ -1059,10 +1380,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 +1414,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.