@scalebun-release/react-native 2.5.0

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

@@ -0,0 +1,1908 @@
+/**
+ * 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';
+import { base64ToBytes } from '../../core/encoding/base64';
+import { ENDPOINTS } from '../../transport/http/endpoints';
+import { resolveInstallationId } from '../../core/id/installationId';
+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';
+import { quotaState, noteQuotaResponse } from '../../config/quotaState';
+import { syncNativeQuotaLanes, subscribeNativeQuotaEvents, setNativeSessionRefusedHandler } from '../replay/bridge/nativeQuota';
+
+// ─── 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.
+ */
+
+// ─── Adapter ────────────────────────────────────────────────────────────────
+
+export class BackendSessionAdapter {
+  /** Durable store for cross-kill frame recovery (null → recovery disabled). */
+
+  /** Storage key for the snapshotted unflushed frame buffer (see persistPendingFrames). */
+  static PENDING_FRAMES_KEY = 'scalebun_replay_pending_frames';
+  /**
+   * 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).
+  // Native module availability is re-checked per call so a missing/old binary falls
+  // back to the JS path transparently.
+
+  // Cached one-shot native-outbox bootstrap promise (see _ensureNativeOutbox).
+  _nativeOutboxReady = null;
+  currentSessionId = null;
+  // §11 session_start ordering: a recording sessionId is added here ONLY after its
+  // INGESTION_START row is confirmed created on the backend (either via sendSessionStart's
+  // own POST, or via startAnalyticsSession when recording adopts the analytics id).
+  // Child telemetry lanes (frames/events/network/errors/perf/logs) refuse to flush until
+  // the row exists — otherwise the backend 404s the child write. Data stays buffered and
+  // the flush timer retries, so nothing is lost to a start/child race. The durable native
+  // outbox path has its own ordering; this guards only the JS in-memory fallback.
+  _startedSessionIds = new Set();
+  // §11 offline-start recovery: INGESTION_START payloads whose POST failed (e.g. the app
+  // launched with no connectivity). Without this, a failed START was logged and forgotten —
+  // the row-ready gate never opened, every child lane re-buffered forever, and the session
+  // stayed stuck until an app restart even after the network returned. Each flush tick
+  // re-attempts these until acked (network errors keep retrying; permanent 4xx gives up).
+  _pendingStartPayloads = new Map();
+  _startRetryInFlight = false;
+  pendingFrames = [];
+  pendingEvents = [];
+  pendingNetworkRequests = [];
+  pendingErrors = [];
+  pendingPerformanceMetrics = [];
+  // Platform-agnostic logs lane. Neutral by construction — holds whatever LogQueueItems
+  // it's handed (console today; native later) and forwards them untouched.
+  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
+  // recording. This lane carries user track() events and never touches recording
+  // state. One queue doubles as the pre-ready buffer (bounded, drop-oldest) and
+  // the outgoing queue; sessionId is stamped at flush so endpoint id == body id.
+  static ANALYTICS_BUFFER_CAP = 100;
+  /** Logs lane: queue length that triggers an eager flush (mirrors the network lane). */
+  static LOGS_BATCH_SIZE = 20;
+  /** Logs lane: max rows posted per flush (server caps at 200/batch). */
+  static LOGS_FLUSH_MAX = 50;
+  _analyticsSessionId = null;
+  pendingAnalyticsEvents = [];
+  analyticsFlushTimer = null;
+  // iOS finalize reconciliation: the id of a backgrounded analytics session whose
+  // INGESTION_FINALIZE has NOT been confirmed delivered. Set synchronously in
+  // finalizeAnalyticsSession before any await (so it survives an iOS suspension of
+  // the awaited fetch), cleared only on a confirmed finalize ACK. On the next
+  // foreground the listener calls reconcilePendingFinalize() to close it for real.
+  // In-memory is sufficient: the JS context survives background→foreground; only a
+  // true process kill drops it (covered by the server-side idle-close backstop).
+  _pendingFinalizeId = null;
+
+  // ── Per-feature quota (shared contract v1) ──
+  /** Unsubscribe from quotaState (set in the constructor, released in destroy). */
+  _quotaUnsub = null;
+  /**
+   * Sessions whose INGESTION_START was refused with `quota_exceeded` (feature `sessions`). No row
+   * will ever exist for them, so every child lane for that id is dropped rather than buffered
+   * behind a row-ready gate that can never open.
+   */
+  _refusedSessionIds = new Set();
+  /** Unregister this adapter as the native sessions-refusal handler. */
+  _nativeRefusedUnsub = null;
+  /** Host hook (SessionManager) to end a recording whose session start was refused. */
+  _onSessionRefused = null;
+  constructor(config) {
+    this.config = {
+      batchSize: 5,
+      flushIntervalMs: 3000,
+      timeoutMs: 15_000,
+      useObjectStorage: false,
+      enableNativeFileOutbox: false,
+      nativeOutboxUploadEnabled: false,
+      nativeOutboxTuning: {},
+      idleThresholdMs: 60_000,
+      ...config,
+      clientKey: config.clientKey
+    };
+    this._frameStore = config.storage ?? null;
+    this.objectStorageActive = this.config.useObjectStorage;
+    this.nativeOutboxEnabled = this.config.enableNativeFileOutbox && this.config.nativeOutboxUploadEnabled;
+    // Quota: purge/park a lane the moment its block starts, un-park it when it ends. Applies to
+    // blocks from /config AND from refusals seen on any lane (including another lane's 402).
+    this._quotaUnsub = quotaState.subscribe((feature, blocked) => this._onQuotaChange(feature, blocked));
+    // The native lane mirror (re-asserted on EVERY quota sync) is registered once per process by
+    // subscribeNativeQuotaEvents(), before whichever native init builds an uploader. A session the
+    // native uploader saw refused is dropped here too.
+    this._nativeRefusedUnsub = setNativeSessionRefusedHandler(id => {
+      if (!this.destroyed) this._refuseSession(id);
+    });
+    __DEV__ && logger.info(`[ScaleBun Replay] backendUpload enabled`);
+    __DEV__ && logger.info(`[ScaleBun Replay] backendBaseUrl: ${this.config.endpoint}`);
+    __DEV__ && logger.info(`[ScaleBun Replay] transport fan-out active: desktop yes, backend yes`);
+  }
+
+  // ─── 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.
+   */
+  _sessionRowReady() {
+    return !!this.currentSessionId && this._startedSessionIds.has(this.currentSessionId);
+  }
+
+  /**
+   * The session live errors go to: the recording session when one runs, else the always-on
+   * analytics session.
+   *
+   * Errors used to require `currentSessionId` — the RECORDING lane — so on any device where replay
+   * was not recording (sampled out, `record: false`, between recordings) not one error left the
+   * phone, and a recovered crash drained at launch waited for a recording that might never start.
+   * The analytics session has a backend row from the moment it opens, which is all an error needs.
+   */
+  _errorsSessionId() {
+    return this.currentSessionId ?? this._analyticsSessionId;
+  }
+
+  /** Lazy: nativeCrashBridge → CrashReporter → SessionManager → this file would be a cycle. */
+  _publishNativeSession(sessionId) {
+    try {
+      // eslint-disable-next-line @typescript-eslint/no-var-requires
+      const {
+        setNativeActiveSession
+      } = require('../crash/nativeCrashBridge');
+      void setNativeActiveSession(sessionId);
+    } catch {
+      // Losing this degrades a recovered crash to "current session" — never fail a start.
+    }
+  }
+
+  // ─── Quota (shared contract v1) ─────────────────────────────────────
+
+  /** True when the current recording session's START was refused for quota (no row, ever). */
+  _currentSessionRefused() {
+    return !!this.currentSessionId && this._refusedSessionIds.has(this.currentSessionId);
+  }
+
+  /** Register the host's reaction to a refused session start (SessionManager ends the recording). */
+  setSessionRefusedHandler(fn) {
+    this._onSessionRefused = fn;
+  }
+
+  /**
+   * A limited feature's block started or ended.
+   *
+   * Started: everything queued for it is PURGED (in memory, the cross-kill frame snapshot, and the
+   * native outbox lane), because the server will refuse it and a retry is exactly what the contract
+   * forbids. Capture itself is stopped by the owners of capture (SessionManager for frames,
+   * NetworkFeature/EventTracker gate at their entry points); this adapter also refuses new items at
+   * its own entry points, so a producer that was not told still cannot leak through.
+   *
+   * Ended: nothing is replayed — what was purged is gone. The native lanes follow via the sync
+   * listener registered in the constructor (it fires after every transition too).
+   */
+  _onQuotaChange(feature, blocked) {
+    if (this.destroyed) return;
+    if (blocked) {
+      if (feature === 'frames') {
+        this.pendingFrames = [];
+        this._clearPersistedFrames();
+      } else if (feature === 'networkRequests') {
+        this.pendingNetworkRequests = [];
+      } else if (feature === 'events') {
+        this.pendingEvents = [];
+        this.pendingAnalyticsEvents = [];
+      }
+    }
+  }
+
+  /**
+   * A session START came back 402 `quota_exceeded` (feature `sessions`). Drop the session: no row
+   * will be created, so nothing may queue behind it and the start is never retried.
+   */
+  _refuseSession(sessionId) {
+    this._refusedSessionIds.add(sessionId);
+    this._pendingStartPayloads.delete(sessionId);
+    if (sessionId === this._analyticsSessionId) {
+      this._analyticsSessionId = null;
+      this._stopAnalyticsFlushTimer();
+      this.pendingAnalyticsEvents = [];
+    }
+    if (sessionId === this.currentSessionId) {
+      this.pendingFrames = [];
+      this.pendingEvents = [];
+      this.pendingNetworkRequests = [];
+      this.pendingPerformanceMetrics = [];
+      this.pendingLogs = [];
+      try {
+        this._onSessionRefused?.(sessionId);
+      } catch {/* no-throw */}
+    }
+    logger.warn(`[ScaleBun Replay] session start refused (quota_exceeded: sessions) — session dropped`);
+  }
+
+  /** True when an HTTP error carried a recorded quota refusal. */
+  static _isQuotaRefusal(err, feature) {
+    const f = err?.quotaFeature;
+    return !!f && (feature === undefined || f === feature);
+  }
+  sendSessionStart(session) {
+    this.currentSessionId = session.sessionId;
+    this._startFlushTimer();
+    __DEV__ && logger.info(`[ScaleBun Replay] session start requested`);
+    __DEV__ && logger.info(`[ScaleBun Replay] sessionId: ${session.sessionId}`);
+    __DEV__ && logger.info(`[ScaleBun Replay] deviceId: ${session.deviceId}`);
+    __DEV__ && logger.info(`[ScaleBun Replay] recordingSessionId: ${session.sessionId}`);
+
+    // One-row merge: when recording adopted the always-on analytics id
+    // (SessionManager.startSession), the INGESTION_START row already exists.
+    // Do NOT post a second one — just keep the flush timer running so frames/
+    // journey/network/errors/perf flush to INGESTION_*(analyticsId). Legacy
+    // mode (no clientKey, distinct minted id) still posts /replay/sessions.
+    if (this.config.clientKey && session.sessionId === this._analyticsSessionId) {
+      __DEV__ && logger.info(`[ScaleBun Replay] recording attached to analytics session ${session.sessionId} (no new row)`);
+      return;
+    }
+
+    // Quota: a `sessions` block stops NEW sessions. SessionManager already refuses to start one
+    // (it only adopts an analytics session that exists), so this is the transport's own backstop:
+    // mark the id refused — every child lane for it then drops instead of buffering forever.
+    if (this.config.clientKey && quotaState.isBlocked('sessions')) {
+      this._refusedSessionIds.add(session.sessionId);
+      logger.warn(`[ScaleBun Replay] session start skipped — sessions quota exceeded`);
+      // Deferred: we are still inside SessionManager.startSession, which must finish before the
+      // recording it started can be ended.
+      const refusedId = session.sessionId;
+      Promise.resolve().then(() => {
+        try {
+          this._onSessionRefused?.(refusedId);
+        } catch {/* no-throw */}
+      });
+      return;
+    }
+    __DEV__ && logger.info(`[ScaleBun Replay] backend session upload started`);
+    const startEndpoint = this.config.clientKey ? ENDPOINTS.INGESTION_START : '/replay/sessions';
+
+    // Fetch native device info to enrich the session payload.
+    // 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,
+        // The canonical per-install id — the SAME value OTA events are
+        // reported under, and a DIFFERENT value from deviceId. The
+        // backend stores it on the Device so release health can join a
+        // bundle's installs to that device's sessions. Without it, crash
+        // impact for a release resolves to "no data" for every device
+        // that never registered for push.
+        installationId: resolveInstallationId(),
+        startedAt: session.startedAt,
+        // Link the recording row to the always-on analytics row so the
+        // dashboard can join them. track() events land on the analytics
+        // id; frames/journey land on this recording id. Without this
+        // link the two appear as separate sessions (one looks "empty").
+        // BACKEND DEPENDENCY: the dashboard must read/join on this field
+        // (or treat the analytics row as canonical) to fully merge them.
+        analyticsSessionId: this._analyticsSessionId,
+        // Carry the idle threshold on the recording lane too: it may
+        // create the row before the analytics lane does. Backend
+        // upsert leaves it untouched if already set.
+        idleThresholdMs: this.config.idleThresholdMs,
+        device: {
+          platform: nativeInfo?.platform ?? m?.platform,
+          osVersion: nativeInfo?.osVersion ?? m?.osVersion,
+          deviceModel: nativeInfo?.deviceModel ?? m?.deviceModel,
+          screenWidth: m?.screenWidth,
+          screenHeight: m?.screenHeight,
+          appName: nativeInfo?.appName ?? m?.appName,
+          appVersion: nativeInfo?.appVersion ?? m?.appVersion,
+          bundleId: nativeInfo?.bundleId ?? m?.bundleId,
+          sdkVersion: SDK_VERSION,
+          releaseStage: m?.buildType,
+          // Backend ingestion source not in this repo; field name
+          // unconfirmed. Send both so whichever it reads is populated.
+          environment: m?.buildType
+        }
+      };
+      __DEV__ && logger.debug(`[BackendSessionAdapter] POST session start: ${session.sessionId}`);
+      return this._post(startEndpoint, payload).then(() => {
+        // §11: row now exists — release the child-lane flush gate for this id.
+        this._startedSessionIds.add(session.sessionId);
+        this._pendingStartPayloads.delete(session.sessionId);
+        __DEV__ && logger.info(`[ScaleBun Replay] backend session upload success`);
+      }, err => {
+        // Quota: 402 quota_exceeded(sessions) — no row, never retried.
+        if (BackendSessionAdapter._isQuotaRefusal(err, 'sessions')) {
+          this._refuseSession(session.sessionId);
+          return;
+        }
+        // Offline-start recovery: keep the payload; the flush timer re-attempts it
+        // until the row is acked. A permanent 4xx (rejected key) is not retried —
+        // the same payload can never succeed.
+        if (!BackendSessionAdapter._isPermanentHttpError(err)) {
+          this._pendingStartPayloads.set(session.sessionId, payload);
+        }
+        logger.info(`[ScaleBun Replay] backend session upload failure`);
+      });
+    }).catch(() => logger.info(`[ScaleBun Replay] backend session upload failure`));
+  }
+  sendSessionEnd(session) {
+    __DEV__ && logger.info(`[ScaleBun Replay] finalize started`);
+    // Flush all pending data first, then finalize
+    Promise.all([this._flushFrames(), this._flushEvents(), this._flushNetwork(), this.flushErrors(), this._flushPerformance()]).then(() => {
+      // One-row merge: if this recording adopted the always-on analytics id,
+      // the analytics lane owns the session's lifecycle and finalizes it on
+      // background (finalizeAnalyticsSession). Finalizing here would close the
+      // shared row mid-foreground and orphan later track() events — so flush
+      // (above) but skip finalize. Legacy/distinct-id sessions finalize normally.
+      if (this.config.clientKey && session.sessionId === this._analyticsSessionId) {
+        __DEV__ && logger.info(`[ScaleBun Replay] recording ended; analytics session ${session.sessionId} stays open`);
+        return;
+      }
+      // Quota: a session whose start was refused has no row — nothing to finalize.
+      if (this._refusedSessionIds.has(session.sessionId)) return;
+      const finalizeEndpoint = this.config.clientKey ? ENDPOINTS.INGESTION_FINALIZE(session.sessionId) : `/replay/sessions/${session.sessionId}/finalize`;
+      return this._post(finalizeEndpoint, {
+        endedAt: session.endedAt ?? Date.now(),
+        durationMs: session.endedAt ? session.endedAt - session.startedAt : Date.now() - session.startedAt,
+        totalFrames: session.artifactIndex?.frameRefs?.length ?? 0,
+        totalEvents: session.artifactIndex?.eventRefs?.length ?? 0,
+        finalState: session.status === 'timeout' ? 'timeout' : 'completed'
+      });
+    }).then(() => {
+      __DEV__ && logger.info(`[ScaleBun Replay] finalize success`);
+    }).catch(() => {
+      __DEV__ && logger.info(`[ScaleBun Replay] finalize failure`);
+    }).finally(() => {
+      this._stopFlushTimer();
+      // Keep the row-ready gate OPEN for a merged analytics session. The analytics
+      // lane still owns it (not finalized on background — the session spans the
+      // app-switch), so a foreground restart re-adopts the SAME id and must keep
+      // flushing frames/events. Dropping the gate here would 404-buffer everything
+      // after the first background cycle. Only clear it for a distinct/legacy
+      // recording id that was actually finalized above.
+      if (!(this.config.clientKey && session.sessionId === this._analyticsSessionId)) {
+        this._startedSessionIds.delete(session.sessionId);
+      }
+      // Session end: drain any durably-stored telemetry from the native outbox.
+      this._triggerNativeFlush();
+      __DEV__ && logger.debug(`[BackendSessionAdapter] Session finalized: ${session.sessionId}`);
+    });
+  }
+
+  // ─── Analytics Lane (isolated from recording) ───────────────────────
+
+  /** Public: the always-on analytics session id, or null before it opens. */
+  get analyticsSessionId() {
+    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).
+   */
+  async startAnalyticsSession(session) {
+    if (this.destroyed) return;
+    // Quota: a `sessions` block stops NEW sessions. No id is opened, so track() events buffer
+    // (bounded, drop-oldest) and recording does not start; a session that is ALREADY open is
+    // untouched and keeps its other lanes. SDKBootstrapper opens one when the block lifts.
+    if (quotaState.isBlocked('sessions')) {
+      logger.warn(`[ScaleBun Analytics] session not started — sessions quota exceeded`);
+      return;
+    }
+    this._analyticsSessionId = session.sessionId;
+    // Native crash records must name a session the backend has a row for. This is that
+    // session; publishing anything else (the event tracker's local `sess-` id did) makes
+    // every recovered crash 404 and get dropped.
+    this._publishNativeSession(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
+    // stamped at flush time, so buffered events need no rewrite.
+    this._flushAnalyticsEvents().catch(() => {});
+    const startEndpoint = this.config.clientKey ? ENDPOINTS.INGESTION_START : '/replay/sessions';
+    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,
+        startedAt: session.startedAt,
+        idleThresholdMs: session.idleThresholdMs,
+        device: {
+          platform: nativeInfo?.platform ?? m?.platform,
+          osVersion: nativeInfo?.osVersion ?? m?.osVersion,
+          deviceModel: nativeInfo?.deviceModel ?? m?.deviceModel,
+          screenWidth: m?.screenWidth,
+          screenHeight: m?.screenHeight,
+          appName: nativeInfo?.appName ?? m?.appName,
+          appVersion: nativeInfo?.appVersion ?? m?.appVersion,
+          bundleId: nativeInfo?.bundleId ?? m?.bundleId,
+          sdkVersion: SDK_VERSION,
+          releaseStage: m?.buildType,
+          environment: m?.buildType
+        }
+      };
+      try {
+        await this._post(startEndpoint, payload);
+      } catch (err) {
+        // Quota: 402 quota_exceeded(sessions) — drop the session, never retry the start.
+        if (BackendSessionAdapter._isQuotaRefusal(err, 'sessions')) {
+          this._refuseSession(session.sessionId);
+          throw err;
+        }
+        // Offline-start recovery: keep the payload for the flush-tick retry loop.
+        // Without this a session that started with no connectivity NEVER opened its
+        // row-ready gate — frames/events re-buffered for the life of the process and
+        // only an app restart recovered it, even after the network came back.
+        if (!BackendSessionAdapter._isPermanentHttpError(err)) {
+          this._pendingStartPayloads.set(session.sessionId, payload);
+        }
+        throw err;
+      }
+      // §11: row exists. When recording adopts this analytics id (one-row merge),
+      // this also releases the recording child-lane gate (_sessionRowReady).
+      this._startedSessionIds.add(session.sessionId);
+      this._pendingStartPayloads.delete(session.sessionId);
+      // Row is confirmed — replay any events buffered while START was in flight.
+      // The pre-ack flush at the top of this method is gated off until now, so
+      // this is what actually drains the pre-ready buffer (no premature 404).
+      this._flushAnalyticsEvents().catch(() => {});
+      __DEV__ && logger.info(`[ScaleBun Analytics] session start upload success: ${session.sessionId}`);
+    } catch {
+      __DEV__ && logger.info(`[ScaleBun Analytics] session start upload failure`);
+    }
+  }
+
+  /**
+   * Re-attempt any INGESTION_START whose POST failed (offline app launch). Runs on every
+   * flush tick of BOTH lanes — cheap no-op when the map is empty, single-flight guarded.
+   * On ack: opens the row-ready gate and drains whichever lane the id belongs to, which is
+   * exactly what un-sticks a replay that started offline once connectivity returns.
+   */
+  _retryPendingStarts() {
+    if (this.destroyed || this._startRetryInFlight || this._pendingStartPayloads.size === 0) return;
+    // A start re-attempted while `sessions` is blocked would only be refused; keep it for later.
+    if (quotaState.isBlocked('sessions')) return;
+    const entry = this._pendingStartPayloads.entries().next().value;
+    if (!entry) return;
+    const [sessionId, payload] = entry;
+    // A stale pending start for a session that already ended AND is not the open analytics
+    // session would create a row nothing will ever finalize — drop it instead.
+    const stillRelevant = sessionId === this.currentSessionId || sessionId === this._analyticsSessionId;
+    if (!stillRelevant) {
+      this._pendingStartPayloads.delete(sessionId);
+      return;
+    }
+    this._startRetryInFlight = true;
+    const startEndpoint = this.config.clientKey ? ENDPOINTS.INGESTION_START : '/replay/sessions';
+    this._post(startEndpoint, payload).then(() => {
+      this._startedSessionIds.add(sessionId);
+      this._pendingStartPayloads.delete(sessionId);
+      __DEV__ && logger.info(`[ScaleBun Replay] deferred session start delivered: ${sessionId}`);
+      if (sessionId === this._analyticsSessionId) {
+        this._flushAnalyticsEvents().catch(() => {});
+      }
+    }).catch(err => {
+      if (BackendSessionAdapter._isQuotaRefusal(err, 'sessions')) {
+        this._refuseSession(sessionId);
+      } else if (BackendSessionAdapter._isPermanentHttpError(err)) {
+        this._pendingStartPayloads.delete(sessionId); // will never succeed — stop retrying
+      }
+    }).finally(() => {
+      this._startRetryInFlight = false;
+    });
+  }
+
+  /**
+   * 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;
+    // Quota: an `events` block stops capture at the source — the server would refuse it.
+    if (quotaState.isBlocked('events')) return;
+    this.pendingAnalyticsEvents.push(event);
+    const overflow = this.pendingAnalyticsEvents.length - BackendSessionAdapter.ANALYTICS_BUFFER_CAP;
+    if (overflow > 0) {
+      this.pendingAnalyticsEvents.splice(0, overflow); // drop oldest
+    }
+    if (this._analyticsSessionId && this.pendingAnalyticsEvents.length >= 20) {
+      this._flushAnalyticsEvents().catch(() => {});
+    }
+  }
+
+  /**
+   * 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;
+    this.trackEvent({
+      eventId: this._clientId(),
+      sessionId: this._analyticsSessionId,
+      ts: Date.now(),
+      type,
+      source: 'sdk',
+      ...(payload ? {
+        payload
+      } : {})
+    });
+  }
+
+  /**
+   * 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.
+   */
+  async _flushAnalyticsEvents(forSessionId) {
+    // finalize clears _analyticsSessionId synchronously, then passes the
+    // captured id here so the final drain still targets the right session.
+    const sessionId = forSessionId ?? this._analyticsSessionId;
+    if (this.pendingAnalyticsEvents.length === 0 || !sessionId) return;
+
+    // Quota, send-time: anything queued before the block (or for a refused session) is purged,
+    // never sent — a refused batch must not be retried.
+    if (quotaState.isBlocked('events') || this._refusedSessionIds.has(sessionId)) {
+      this.pendingAnalyticsEvents = [];
+      return;
+    }
+
+    // Row-confirmed gate (mirrors the recording lanes' _sessionRowReady). The
+    // INGESTION_START create is async and can fail/lag; flushing events before
+    // the row exists 404s the child write and re-buffers forever. Keep events
+    // queued (bounded, drop-oldest via trackEvent) until START is acked.
+    if (!this._startedSessionIds.has(sessionId)) return;
+    const batch = this.pendingAnalyticsEvents.splice(0, 20);
+    const events = batch.map(e => this._leanEvent(e, sessionId));
+    try {
+      const eventsEndpoint = this.config.clientKey ? ENDPOINTS.INGESTION_EVENTS(sessionId) : `/replay/sessions/${sessionId}/events`;
+      await this._post(eventsEndpoint, {
+        events
+      });
+      __DEV__ && logger.debug(`[BackendSessionAdapter] Flushed ${batch.length} analytics event(s)`);
+    } catch (err) {
+      if (!BackendSessionAdapter._isPermanentHttpError(err)) this.pendingAnalyticsEvents.unshift(...batch);
+    }
+  }
+
+  /** Flush remaining analytics events, finalize the session, stop its timer. */
+  async finalizeAnalyticsSession() {
+    const sessionId = this._analyticsSessionId;
+    if (!sessionId) return;
+
+    // Clear the id and stop the timer SYNCHRONOUSLY, before any await. On iOS
+    // the app is suspended on background and the finalize fetch below never
+    // resolves until the next foreground, so the old `finally` that nulled the
+    // id never ran before the resume guard (SDKBootstrapper: `state==='active'
+    // && !adapter.analyticsSessionId`) evaluated → guard stayed false → no new
+    // session opened. Clearing up front makes the guard always see null after
+    // background, so resume re-opens a fresh analytics session every cycle.
+    this._analyticsSessionId = null;
+    this._stopAnalyticsFlushTimer();
+
+    // Mark as pending-finalize BEFORE any await. On iOS the app suspends right
+    // after backgrounding, so the awaited _post below may never resolve. Setting
+    // the marker synchronously guarantees the next foreground can reconcile-close
+    // this id even though the background POST was suspended. Cleared only on a
+    // confirmed ACK (below), so a suspended POST leaves the marker in place.
+    this._pendingFinalizeId = sessionId;
+    try {
+      // Pass the captured id explicitly — the field is already cleared.
+      await this._flushAnalyticsEvents(sessionId);
+      const finalizeEndpoint = this.config.clientKey ? ENDPOINTS.INGESTION_FINALIZE(sessionId) : `/replay/sessions/${sessionId}/finalize`;
+      await this._post(finalizeEndpoint, {
+        endedAt: Date.now()
+      });
+      // Confirmed delivered → drop the marker so the foreground reconciler does
+      // NOT re-finalize this id (first half of the no-double-finalize guard).
+      if (this._pendingFinalizeId === sessionId) this._pendingFinalizeId = null;
+      __DEV__ && logger.debug(`[BackendSessionAdapter] Analytics session finalized: ${sessionId}`);
+    } catch {
+      // Leave the marker set — foreground reconciliation will retry the close.
+      __DEV__ && logger.info(`[ScaleBun Analytics] finalize failure (will reconcile on foreground): ${sessionId}`);
+    }
+  }
+
+  /**
+   * 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;
+    if (!sessionId) return;
+    if (this._refusedSessionIds.has(sessionId)) {
+      this._pendingFinalizeId = null;
+      return;
+    }
+    try {
+      const finalizeEndpoint = this.config.clientKey ? ENDPOINTS.INGESTION_FINALIZE(sessionId) : `/replay/sessions/${sessionId}/finalize`;
+      await this._post(finalizeEndpoint, {
+        endedAt: Date.now()
+      });
+      __DEV__ && logger.info(`[ScaleBun Analytics] reconciled finalize on foreground: ${sessionId}`);
+    } catch {
+      __DEV__ && logger.info(`[ScaleBun Analytics] foreground reconcile finalize failed: ${sessionId}`);
+    } finally {
+      // Clear after a foreground attempt regardless of outcome: JS is live here
+      // so a transient network error is rare, and the server-side idle-close
+      // backstop covers any still-orphaned row. Bounds total finalizes per id to
+      // at most 2 (suspended-bg + foreground) — never a per-foreground loop.
+      if (this._pendingFinalizeId === sessionId) this._pendingFinalizeId = null;
+    }
+  }
+  _startAnalyticsFlushTimer() {
+    this._stopAnalyticsFlushTimer();
+    this.analyticsFlushTimer = setInterval(() => {
+      this._retryPendingStarts();
+      this._flushAnalyticsEvents().catch(() => {});
+      // Errors ride the analytics session when nothing is recording; without this tick they
+      // waited on the recording timer, which does not run when replay is off.
+      if (!this.currentSessionId) this.flushErrors().catch(() => {});
+    }, this.config.flushIntervalMs);
+  }
+  _stopAnalyticsFlushTimer() {
+    if (this.analyticsFlushTimer) {
+      clearInterval(this.analyticsFlushTimer);
+      this.analyticsFlushTimer = null;
+    }
+  }
+  sendEvent(event) {
+    if (this.destroyed) return;
+    // Quota: journey events are `events` (same /events endpoint as track()).
+    if (quotaState.isBlocked('events') || this._currentSessionRefused()) return;
+    __DEV__ && logger.info(`[ScaleBun Replay] event recorded`);
+    __DEV__ && logger.info(`  eventId: ${event.eventId}`);
+    __DEV__ && logger.info(`  type: ${event.type}`);
+    __DEV__ && logger.info(`  timestamp: ${event.ts}`);
+    __DEV__ && logger.info(`  sessionId: ${event.sessionId}`);
+    this.pendingEvents.push(event);
+    if (this.pendingEvents.length >= 20) {
+      this._flushEvents().catch(() => {});
+    }
+  }
+  sendFrame(frame, imageData) {
+    if (this.destroyed) return;
+    // Quota: SessionManager stops capture on a `frames` block; this refuses any frame that was
+    // already in flight when the block arrived.
+    if (quotaState.isBlocked('frames') || this._currentSessionRefused()) return;
+    __DEV__ && logger.info(`[ScaleBun Replay] frame captured`);
+    __DEV__ && logger.info(`  frameId: ${frame.frameId}`);
+    __DEV__ && logger.info(`  timestamp: ${frame.ts}`);
+    __DEV__ && logger.info(`  sessionId: ${frame.sessionId}`);
+    __DEV__ && logger.info(`  width/height: ${frame.width}x${frame.height}`);
+    this.pendingFrames.push({
+      frame,
+      imageData
+    });
+    if (this.pendingFrames.length >= this.config.batchSize) {
+      this._flushFrames().catch(() => {});
+    }
+  }
+
+  // ─── SaaS Ingestion Queues ──────────────────────────────────────────
+
+  queueNetworkRequest(data) {
+    if (this.destroyed || !this.config.clientKey) return;
+    // Quota: `networkRequests` block (NetworkFeature also gates before calling this).
+    if (quotaState.isBlocked('networkRequests') || this._currentSessionRefused()) return;
+    // clientId: stable per-row idempotency key so a mobile retry of the same
+    // batch upserts instead of inserting duplicates server-side.
+    this.pendingNetworkRequests.push({
+      ...data,
+      clientId: this._clientId(),
+      timestamp: new Date().toISOString()
+    });
+    if (this.pendingNetworkRequests.length >= 20) {
+      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,
+      // 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) {
+      this.flushErrors().catch(() => {});
+    }
+  }
+
+  /**
+   * 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() {
+    /*
+     * SERIALISED, and an empty queue answers with the flush that emptied it.
+     *
+     * BackendErrorsSink.deliver() queues a crash and immediately calls flushErrors(); the crash
+     * drain then calls flushErrors() again to ask whether the crash was delivered. The first
+     * call had already taken the batch (the splice is synchronous), so the second found an
+     * empty queue and answered `false` — every recovered crash stayed on disk, the drain stopped
+     * after one record, and the crash was re-sent every launch forever. Chaining the calls means
+     * the question waits for the flush actually carrying the crash and gets ITS answer.
+     *
+     * Nothing can be delivered without a clientKey (queueError drops it), so that is never
+     * "delivered", however empty the queue.
+     */
+    const run = this._errorsFlushTail.then(previousOk => {
+      if (this.destroyed || !this.config.clientKey) return false;
+      if (this.pendingErrors.length === 0) return previousOk;
+      return this._flushErrors();
+    });
+    this._errorsFlushTail = run.catch(() => false);
+    return run;
+  }
+
+  /** The last errors flush — the answer an empty queue gives. Starts true: nothing owed. */
+  _errorsFlushTail = Promise.resolve(true);
+
+  /**
+   * 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()]);
+    // Background trigger: close native segments + drain the native uploader so a
+    // suspended JS context doesn't strand durably-stored telemetry.
+    this._triggerNativeFlush();
+  }
+  queuePerformanceMetric(data) {
+    if (this.destroyed || !this.config.clientKey) {
+      logger.warn('[perf.queue] dropped — no clientKey or adapter destroyed', {
+        type: data.type,
+        destroyed: this.destroyed,
+        hasClientKey: !!this.config.clientKey
+      });
+      return;
+    }
+    if (this._currentSessionRefused()) return; // no row will ever exist for this session
+    this.pendingPerformanceMetrics.push({
+      ...data,
+      clientId: this._clientId(),
+      timestamp: new Date().toISOString()
+    });
+    logger.debug('[perf.trace] queue enqueued performance metric', {
+      type: data.type,
+      pending: this.pendingPerformanceMetrics.length
+    });
+    if (this.pendingPerformanceMetrics.length >= 20) {
+      this._flushPerformance().catch(() => {});
+    }
+  }
+
+  /**
+   * 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;
+    if (this._currentSessionRefused()) return; // no row will ever exist for this session
+    this.pendingLogs.push({
+      level: data.level,
+      message: data.message,
+      source: data.source,
+      platform: data.platform,
+      timestamp: data.timestamp ?? new Date().toISOString(),
+      ...(data.metadata ? {
+        metadata: data.metadata
+      } : {})
+    });
+    if (this.pendingLogs.length >= BackendSessionAdapter.LOGS_BATCH_SIZE) {
+      this._flushLogs().catch(() => {});
+    }
+  }
+
+  /** Stable client-generated idempotency id (matches journeyManager id scheme). */
+  _clientId() {
+    return `${Date.now().toString(36)}-${Math.random().toString(36).substring(2, 10)}`;
+  }
+
+  // ─── 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.
+   */
+  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.
+   */
+  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, 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).
+   */
+  _ensureNativeOutbox(native) {
+    if (this._nativeOutboxReady) return this._nativeOutboxReady;
+    if (!native.initOutbox) return Promise.resolve(false);
+    // Quota, BEFORE initOutbox: initOutbox builds the uploader and drains immediately. The module
+    // remembers lane blocks set before the uploader exists and applies them when it is built, and
+    // bridge calls to one module are processed in order — so persisted blocks are in place before
+    // the first drain. The 402 listener is attached first for the same reason.
+    subscribeNativeQuotaEvents();
+    syncNativeQuotaLanes();
+    this._nativeOutboxReady = native.initOutbox({
+      ...this.config.nativeOutboxTuning,
+      clientKey: this.config.clientKey,
+      apiBaseUrl: this.config.endpoint,
+      enableNativeFileOutbox: true,
+      nativeOutboxUploadEnabled: true,
+      useObjectStorageForFrames: this.config.useObjectStorage === true
+    }).catch(() => false);
+    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`.
+   */
+  ensureNativeOutboxReady() {
+    if (!this.nativeOutboxEnabled || !this.currentSessionId) return Promise.resolve(false);
+    const native = getReplaySdkNative();
+    if (!native?.captureScreenshotToFile) return Promise.resolve(false);
+    return this._ensureNativeOutbox(native);
+  }
+
+  /** Best-effort: close native segments and drain the native uploader. Never throws. */
+  _triggerNativeFlush() {
+    if (!this.nativeOutboxEnabled) return;
+    try {
+      getReplaySdkNative()?.flushNativeOutbox?.().catch(() => {});
+    } catch {
+      /* old binary / unavailable — ignore */
+    }
+  }
+
+  // ─── Lifecycle ──────────────────────────────────────────────────────
+
+  destroy() {
+    this.destroyed = true;
+    this._quotaUnsub?.();
+    this._quotaUnsub = null;
+    this._nativeRefusedUnsub?.();
+    this._nativeRefusedUnsub = null;
+    this._refusedSessionIds.clear();
+    this._onSessionRefused = null;
+    this._stopFlushTimer();
+    this._stopAnalyticsFlushTimer();
+    this.pendingFrames = [];
+    this.pendingEvents = [];
+    this.pendingAnalyticsEvents = [];
+    this.pendingNetworkRequests = [];
+    this.pendingErrors = [];
+    this.pendingPerformanceMetrics = [];
+    this.currentSessionId = null;
+    this._analyticsSessionId = null;
+    this._pendingFinalizeId = null;
+    this._startedSessionIds.clear();
+    this._pendingStartPayloads.clear();
+  }
+
+  // ─── Internal: Flush ────────────────────────────────────────────────
+
+  /** Wire metadata for a frame — real format/sizeBytes from native (no hardcoded literals). */
+  _frameMeta(b) {
+    const f = b.frame;
+    const format = f.format ?? 'jpeg';
+    // P2-5: a JSON frame-delta carries an application content type, not an image MIME.
+    const isJsonDelta = f.frameType === 'delta' && format === 'scalebun-framedelta';
+    const contentType = isJsonDelta ? 'application/x-scalebun-framedelta+json' : `image/${format}`;
+    return {
+      frameId: f.frameId,
+      sessionId: f.sessionId,
+      timestamp: f.ts,
+      // P2-0: real monotonic per-session sequence (was hardcoded 0 server-side).
+      sequenceNumber: f.sequenceNumber,
+      // P2-5: keyframe|delta + base reference for dashboard reconstruction.
+      frameType: f.frameType,
+      baseFrameId: f.baseFrameId,
+      screenName: f.screen ?? '',
+      trigger: f.captureReason ?? '',
+      format,
+      contentType,
+      width: f.width,
+      height: f.height,
+      sizeBytes: f.byteSize ?? 0,
+      masked: f.redactionState === 'full',
+      // Visible scroll containers at capture time, sanitized at the native boundary. Omitted
+      // (not sent as []) when not measured, so the server stores null rather than "none".
+      ...(f.scrollState ? {
+        scrollState: f.scrollState
+      } : {})
+    };
+  }
+
+  /**
+   * 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 = {
+      v: 2,
+      eventId: e.eventId,
+      sessionId,
+      type: e.type,
+      timestamp: e.ts
+    };
+    const screen = e.screen ?? '';
+    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;
+  }
+
+  /** Shallow-prune null/undefined/'' leaves from a payload object. */
+  _pruneEmpty(payload) {
+    if (!payload || typeof payload !== 'object') return undefined;
+    const src = payload;
+    const out = {};
+    for (const k of Object.keys(src)) {
+      const v = src[k];
+      if (v === null || v === undefined || v === '') continue;
+      out[k] = v;
+    }
+    return out;
+  }
+  async _flushFrames() {
+    if (this.pendingFrames.length === 0 || !this.currentSessionId) return;
+    // Quota, send-time: frames queued before a `frames` block are DISCARDED — including the
+    // final flush on session end — and the cross-kill snapshot with them.
+    if (quotaState.isBlocked('frames')) {
+      this.pendingFrames = [];
+      this._clearPersistedFrames();
+      return;
+    }
+    if (this._currentSessionRefused()) {
+      this.pendingFrames = [];
+      return;
+    }
+    // §11: hold frames until the session_start row is confirmed (else 404). Data stays
+    // buffered; the flush timer retries once the row lands.
+    if (!this._sessionRowReady()) return;
+    const sessionId = this.currentSessionId;
+    const batch = this.pendingFrames.splice(0, this.config.batchSize);
+    /**
+     * 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: remaining.length
+      });
+      this.pendingFrames.unshift(...remaining);
+      return;
+    }
+    __DEV__ && 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'
+        }
+      });
+    } 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++) {
+      // Re-checked per chunk: a block can arrive (from any lane or /config) mid-loop.
+      if (quotaState.isBlocked('frames')) return [];
+      try {
+        await this._postFrameBatch(sessionId, chunks[i]);
+      } catch (err) {
+        // Quota: a refusal (402 on presign or frames) is not a capture defect and nothing
+        // after it will be accepted either — abandon the whole remainder, report nothing.
+        // quotaState is already set, and its listener has purged the lane.
+        if (BackendSessionAdapter._isQuotaRefusal(err)) return [];
+        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;
+    __DEV__ && logger.info(`[replay.sdk.frame] backend frame upload started`, {
+      count: batch.length
+    });
+
+    // Object-storage path: presign → PUT bytes → post key-only metadata.
+    if (this.objectStorageActive && this.config.clientKey) {
+      const result = await this._uploadFramesViaStorage(sessionId, batch);
+      if (result === 'sent') {
+        __DEV__ && logger.info(`[replay.sdk.frame] backend frame upload success (object storage)`);
+        return;
+      }
+      // 'disabled' → storage not configured server-side; fall through to inline.
+    }
+
+    // Legacy inline path: base64 in JSON body.
+    const frames = batch.map(b => ({
+      ...this._frameMeta(b),
+      imageData: b.imageData
+    }));
+    const framesEndpoint = this.config.clientKey ? ENDPOINTS.INGESTION_FRAMES(sessionId) : `/replay/sessions/${sessionId}/frames`;
+    await this._post(framesEndpoint, {
+      frames
+    });
+    __DEV__ && logger.info(`[replay.sdk.frame] backend frame upload success`);
+  }
+
+  // ─── Cross-kill frame recovery ──────────────────────────────────────
+  //
+  // Frames buffer in-memory (pendingFrames) and only reach the backend on flush.
+  // A process kill (swipe-away, OOM) between captures loses the last frames the
+  // user saw — the iOS/Android background flush may be suspended before its POST
+  // resolves. To close that gap we snapshot the unflushed buffer to the durable
+  // 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.
+   */
+  persistPendingFrames() {
+    if (!this._frameStore || this.destroyed || !this.currentSessionId) return;
+    if (this.pendingFrames.length === 0) return;
+    // Quota: never snapshot frames that can never be uploaded.
+    if (quotaState.isBlocked('frames') || this._currentSessionRefused()) return;
+    try {
+      const items = BackendSessionAdapter._selectFramesToPersist(this.pendingFrames);
+      if (items.length === 0) return;
+      this._frameStore.set(BackendSessionAdapter.PENDING_FRAMES_KEY, JSON.stringify({
+        sessionId: this.currentSessionId,
+        items
+      }));
+    } catch {
+      // Serialization/storage failure must never break backgrounding.
+    }
+  }
+
+  /**
+   * 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;
+    try {
+      this._frameStore.delete(BackendSessionAdapter.PENDING_FRAMES_KEY);
+    } catch {
+      /* non-fatal */
+    }
+  }
+
+  /**
+   * 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;
+    // Quota: this path bypasses the live flush, so it must check the block itself. A snapshot
+    // restored while `frames` is blocked is deleted, not kept for a later launch — it was
+    // captured under a period whose allowance is spent.
+    if (quotaState.isBlocked('frames')) {
+      this._clearPersistedFrames();
+      return;
+    }
+    let raw;
+    try {
+      raw = this._frameStore.get(BackendSessionAdapter.PENDING_FRAMES_KEY);
+    } catch {
+      return;
+    }
+    if (!raw) return;
+    let parsed;
+    try {
+      parsed = JSON.parse(raw);
+    } catch {
+      // Corrupt snapshot — discard so it can't wedge every launch.
+      this._clearPersistedFrames();
+      return;
+    }
+    const sessionId = parsed.sessionId;
+    const items = parsed.items;
+    if (!sessionId || !Array.isArray(items) || items.length === 0) {
+      this._clearPersistedFrames();
+      return;
+    }
+    __DEV__ && 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();
+      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.
+   */
+  async _uploadFramesViaStorage(sessionId, batch) {
+    // Decode ONCE: the exact byte count we will PUT is declared as `sizeBytes`, and the backend
+    // signs that Content-Length into the URL — the PUT body must be these very bytes.
+    const decoded = batch.map(b => ({
+      b,
+      bytes: base64ToBytes(this._stripDataUri(b.imageData))
+    }));
+    const presignReq = decoded.map(({
+      b,
+      bytes
+    }) => {
+      const m = this._frameMeta(b);
+      return {
+        frameId: m.frameId,
+        contentType: m.contentType,
+        format: m.format,
+        sizeBytes: bytes.length
+      };
+    });
+    const resp = await this._postReturning(ENDPOINTS.INGESTION_FRAMES_PRESIGN(sessionId), {
+      frames: presignReq
+    });
+    if (!resp || resp.enabled === false) {
+      // Latch off for the rest of the session so we don't presign every batch.
+      this.objectStorageActive = false;
+      return 'disabled';
+    }
+    const byFrameId = new Map((resp.frames ?? []).map(p => [p.frameId, p]));
+
+    // PARTIAL GRANT: the backend issues URLs only up to the remaining frames allowance (the
+    // response's `quota` block — already recorded by _postReturning — blocks `frames` from here
+    // on). A frame WITHOUT a URL was refused: it is dropped, never thrown for and never retried.
+    const granted = decoded.filter(({
+      b
+    }) => byFrameId.has(b.frame.frameId));
+    if (granted.length < decoded.length) {
+      logger.warn(`[replay.sdk.frame] presign granted ${granted.length}/${decoded.length} frame(s); the rest are dropped (quota)`);
+    }
+    if (granted.length === 0) return 'sent';
+
+    // Upload bytes directly to storage (backend never sees image bytes here). URLs live 120 s.
+    await Promise.all(granted.map(async ({
+      b,
+      bytes
+    }) => {
+      const p = byFrameId.get(b.frame.frameId);
+      await this._putBytes(p.uploadUrl, bytes, p.contentType);
+    }));
+
+    // Persist key-only metadata (no base64 in the body) — granted frames only.
+    const frames = granted.map(({
+      b
+    }) => {
+      const p = byFrameId.get(b.frame.frameId);
+      return {
+        ...this._frameMeta(b),
+        storageKey: p.storageKey,
+        contentType: p.contentType
+      };
+    });
+    await this._post(ENDPOINTS.INGESTION_FRAMES(sessionId), {
+      frames
+    });
+    return 'sent';
+  }
+  async _flushEvents() {
+    if (this.pendingEvents.length === 0 || !this.currentSessionId) return;
+    if (quotaState.isBlocked('events') || this._currentSessionRefused()) {
+      this.pendingEvents = [];
+      return;
+    }
+    const batch = this.pendingEvents.splice(0, 20);
+    const events = batch.map(e => this._leanEvent(e, e.sessionId));
+    try {
+      __DEV__ && logger.info(`[replay.sdk.event] backend event upload started`, {
+        count: batch.length
+      });
+      // Durable native outbox owns delivery when active (no duplicate JS POST).
+      // The native enqueue is NOT gated on row-readiness: it writes to disk and its
+      // uploader handles ordering/retry, so it must accept data even while offline.
+      if (await this._enqueueNative('events', events)) return;
+      // §11: JS-direct POST only after the session_start row exists; else re-buffer.
+      if (!this._sessionRowReady()) {
+        this.pendingEvents.unshift(...batch);
+        return;
+      }
+      const eventsEndpoint = this.config.clientKey ? ENDPOINTS.INGESTION_EVENTS(this.currentSessionId) : `/replay/sessions/${this.currentSessionId}/events`;
+      await this._post(eventsEndpoint, {
+        events
+      });
+      __DEV__ && logger.info(`[replay.sdk.event] backend event upload success`);
+      __DEV__ && logger.debug(`[BackendSessionAdapter] Flushed ${batch.length} event(s)`);
+    } catch (err) {
+      if (BackendSessionAdapter._isPermanentHttpError(err)) return;
+      logger.warn(`[replay.sdk.error] backend event upload failure`, {
+        count: batch.length
+      });
+      this.pendingEvents.unshift(...batch);
+    }
+  }
+  async _flushNetwork() {
+    if (this.pendingNetworkRequests.length === 0 || !this.currentSessionId || !this.config.clientKey) return;
+    if (quotaState.isBlocked('networkRequests') || this._currentSessionRefused()) {
+      this.pendingNetworkRequests = [];
+      return;
+    }
+    const batch = this.pendingNetworkRequests.splice(0, 50);
+    try {
+      if (await this._enqueueNative('network', batch)) return;
+      if (!this._sessionRowReady()) {
+        this.pendingNetworkRequests.unshift(...batch);
+        return;
+      }
+      await this._post(ENDPOINTS.INGESTION_NETWORK(this.currentSessionId), {
+        requests: batch
+      });
+    } catch (err) {
+      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() {
+    const live = this._errorsSessionId();
+    if (this.pendingErrors.length === 0 || !live || !this.config.clientKey) return false;
+    const batch = this.pendingErrors.splice(0, 20);
+    try {
+      if (!this._startedSessionIds.has(live)) {
+        this.pendingErrors.unshift(...batch);
+        return false;
+      }
+      /**
+       * 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 || live;
+        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) {
+          /*
+           * 404 on a session that is not the live one: the backend has no row for the
+           * session this crash names. Records written before the native session id was
+           * fixed name the event tracker's local `sess-` id, which never had a row, and
+           * a session can also be purged by retention before its crash is drained.
+           * Dropping it as "permanent" is what lost every such crash. File it under the
+           * live session instead, and SAY so — a crash attributed by fallback must never
+           * read as one observed in that session.
+           */
+          if (err?.status === 404 && target !== live) {
+            const moved = cleaned.map(e => ({
+              ...e,
+              metadata: {
+                ...(e.metadata ?? {}),
+                attribution: 'fallback',
+                originalSessionId: target
+              }
+            }));
+            try {
+              await this._post(ENDPOINTS.INGESTION_ERRORS(live), {
+                errors: moved
+              });
+              continue;
+            } catch (retryErr) {
+              err = retryErr;
+            }
+          }
+          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() {
+    if (this.pendingPerformanceMetrics.length === 0) return;
+    if (!this.currentSessionId || !this.config.clientKey) {
+      logger.debug('[perf.trace] flush waiting — not deliverable yet', {
+        pending: this.pendingPerformanceMetrics.length,
+        hasSession: !!this.currentSessionId,
+        hasClientKey: !!this.config.clientKey
+      });
+      return;
+    }
+    if (this._currentSessionRefused()) {
+      this.pendingPerformanceMetrics = [];
+      return;
+    }
+    const batch = this.pendingPerformanceMetrics.splice(0, 50);
+    try {
+      if (await this._enqueueNative('performance', batch)) {
+        logger.debug('[perf.trace] flush handed to native outbox', {
+          count: batch.length
+        });
+        return;
+      }
+      if (!this._sessionRowReady()) {
+        logger.debug('[perf.trace] flush session row not ready — re-buffering', {
+          count: batch.length
+        });
+        this.pendingPerformanceMetrics.unshift(...batch);
+        return;
+      }
+      await this._post(ENDPOINTS.INGESTION_PERFORMANCE(this.currentSessionId), {
+        metrics: batch
+      });
+      logger.debug('[perf.trace] flush POST performance metrics ok', {
+        count: batch.length
+      });
+    } catch (err) {
+      const permanent = BackendSessionAdapter._isPermanentHttpError(err);
+      logger.warn('[perf.flush] POST performance metrics failed', {
+        count: batch.length,
+        permanent
+      });
+      if (!permanent) this.pendingPerformanceMetrics.unshift(...batch);
+    }
+  }
+  async _flushLogs() {
+    if (this.pendingLogs.length === 0 || !this.currentSessionId || !this.config.clientKey) return;
+    if (this._currentSessionRefused()) {
+      this.pendingLogs = [];
+      return;
+    }
+    const batch = this.pendingLogs.splice(0, BackendSessionAdapter.LOGS_FLUSH_MAX);
+    try {
+      if (await this._enqueueNative('logs', batch)) return;
+      if (!this._sessionRowReady()) {
+        this.pendingLogs.unshift(...batch);
+        return;
+      }
+      await this._post(ENDPOINTS.INGESTION_LOGS(this.currentSessionId), {
+        logs: batch
+      });
+    } catch (err) {
+      if (!BackendSessionAdapter._isPermanentHttpError(err)) this.pendingLogs.unshift(...batch);
+    }
+  }
+
+  // ─── Internal: Timer ────────────────────────────────────────────────
+
+  _startFlushTimer() {
+    this._stopFlushTimer();
+    this.flushTimer = setInterval(() => {
+      this._retryPendingStarts();
+      this._flushFrames().catch(() => {});
+      this._flushEvents().catch(() => {});
+      this._flushNetwork().catch(() => {});
+      this.flushErrors().catch(() => {});
+      this._flushPerformance().catch(() => {});
+      this._flushLogs().catch(() => {});
+      this._triggerNativeFlush();
+    }, this.config.flushIntervalMs);
+  }
+  _stopFlushTimer() {
+    if (this.flushTimer) {
+      clearInterval(this.flushTimer);
+      this.flushTimer = null;
+    }
+  }
+
+  // ─── Internal: HTTP ─────────────────────────────────────────────────
+
+  // A 4xx (except 408 Request Timeout / 429 Too Many Requests) is permanent:
+  // the same payload will never succeed, so requeuing it retries forever and
+  // floods the logs (e.g. a rejected clientKey → HTTP 403 on every flush tick).
+  // Drop the batch on these; keep retrying 5xx / timeouts / network errors.
+  static _isPermanentHttpError(err) {
+    const status = err?.status;
+    return typeof status === 'number' && status >= 400 && status < 500 && status !== 408 && status !== 429;
+  }
+  async _post(path, body) {
+    const url = `${this.config.endpoint}${path}`;
+    try {
+      const controller = new AbortController();
+      const timeout = setTimeout(() => controller.abort(), this.config.timeoutMs);
+      try {
+        const headers = {
+          'Content-Type': 'application/json'
+        };
+        if (this.config.clientKey) {
+          headers['x-scalebun-client-key'] = this.config.clientKey;
+        }
+        const response = await fetch(url, {
+          method: 'POST',
+          headers,
+          body: JSON.stringify(body),
+          signal: controller.signal
+        });
+        if (!response.ok) {
+          logger.warn(`[BackendSessionAdapter] HTTP ${response.status} from ${path}`);
+          const httpErr = new Error(`HTTP ${response.status}`);
+          httpErr.status = response.status;
+          httpErr.quotaFeature = await BackendSessionAdapter._noteQuota(response);
+          throw httpErr;
+        }
+        // A 2xx may carry a partial grant (`quota.refused > 0`): the allowance is now spent.
+        await BackendSessionAdapter._noteQuota(response);
+      } finally {
+        clearTimeout(timeout);
+      }
+    } catch (err) {
+      if (err?.name === 'AbortError') {
+        logger.warn(`[BackendSessionAdapter] Timeout on ${path}`);
+      } else {
+        logger.warn(`[BackendSessionAdapter] Failed ${path}: ${err?.message}`);
+      }
+      throw err;
+    }
+  }
+
+  /**
+   * Read an ingestion response for a quota refusal (contract v1 §2a) and record it in quotaState.
+   * Only a 402 or a 2xx can carry one; anything else is not read. Never throws.
+   */
+  static async _noteQuota(response) {
+    const status = response?.status;
+    if (status !== 402 && !(status >= 200 && status < 300)) return null;
+    if (typeof response?.json !== 'function') return null;
+    try {
+      const body = await response.json();
+      return noteQuotaResponse(status, body, response.headers);
+    } catch {
+      return null; // empty / non-JSON 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}`;
+    const controller = new AbortController();
+    const timeout = setTimeout(() => controller.abort(), this.config.timeoutMs);
+    try {
+      const headers = {
+        'Content-Type': 'application/json'
+      };
+      if (this.config.clientKey) {
+        headers['x-scalebun-client-key'] = this.config.clientKey;
+      }
+      const response = await fetch(url, {
+        method: 'POST',
+        headers,
+        body: JSON.stringify(body),
+        signal: controller.signal
+      });
+      if (!response.ok) {
+        logger.warn(`[BackendSessionAdapter] HTTP ${response.status} from ${path}`);
+        const httpErr = new Error(`HTTP ${response.status}`);
+        httpErr.status = response.status;
+        httpErr.quotaFeature = await BackendSessionAdapter._noteQuota(response);
+        throw httpErr;
+      }
+      const parsed = await response.json();
+      // A 2xx can carry a partial grant (`quota.refused > 0`) — record it (frames presign).
+      try {
+        noteQuotaResponse(response.status, parsed, response.headers);
+      } catch {/* no-throw */}
+      return parsed;
+    } finally {
+      clearTimeout(timeout);
+    }
+  }
+
+  /**
+   * PUT raw image bytes directly to a presigned storage URL. The caller decodes the base64 frame
+   * payload once (RN-safe: a Uint8Array body — the `fetch('data:…').blob()` round-trip fails under
+   * the new architecture) so the bytes PUT are exactly the `sizeBytes` declared at presign, whose
+   * Content-Length the URL is signed for. No client key header — the URL carries its own auth.
+   */
+  async _putBytes(uploadUrl, bytes, contentType) {
+    const controller = new AbortController();
+    const timeout = setTimeout(() => controller.abort(), this.config.timeoutMs);
+    try {
+      const response = await fetch(uploadUrl, {
+        method: 'PUT',
+        headers: {
+          'Content-Type': contentType
+        },
+        body: bytes,
+        signal: controller.signal
+      });
+      if (!response.ok) {
+        throw new Error(`HTTP ${response.status}`);
+      }
+    } finally {
+      clearTimeout(timeout);
+    }
+  }
+
+  /** Strip a leading `data:<mime>;base64,` prefix if the native layer included one. */
+  _stripDataUri(s) {
+    const comma = s.indexOf(',');
+    return s.startsWith('data:') && comma !== -1 ? s.slice(comma + 1) : s;
+  }
+}
+//# sourceMappingURL=BackendSessionAdapter.js.map