@scalebun-release/react-native 2.5.0

package/src/features/session/BackendSessionAdapter.ts

@@ -0,0 +1,1977 @@
+/**
+ * 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';
+import type { ReplaySdkNativeModule } from '../replay/bridge/nativeModule';
+import type { StorageBackend } from '../../storage/StorageBackend';
+// 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, type QuotaFeature } from '../../config/quotaState';
+import { syncNativeQuotaLanes, subscribeNativeQuotaEvents, setNativeSessionRefusedHandler } from '../replay/bridge/nativeQuota';
+import type {
+    SessionTransport,
+    Session,
+    SessionMetadata,
+    JourneyEvent,
+    ReplayFrame,
+} from './sessionTypes';
+
+// ─── Config ─────────────────────────────────────────────────────────────────
+
+export interface BackendSessionConfig {
+    /** Backend API base URL (e.g. http://localhost:3001/api) */
+    endpoint: string;
+    /** Batch size for frames before auto-flush. Default: 5 */
+    batchSize?: number;
+    /** Auto-flush interval in ms. Default: 3000 */
+    flushIntervalMs?: number;
+    /** Request timeout in ms. Default: 15000 */
+    timeoutMs?: number;
+    /** SaaS multi-tenant client key — enables ingestion endpoints and x-scalebun-client-key header */
+    clientKey?: string;
+    /**
+     * Upload frame bytes directly to object storage via presigned PUT instead of
+     * inline base64 in the JSON body. Default false → legacy inline path. Flip on
+     * after the backend presign endpoint is deployed. Falls back to inline
+     * automatically if the backend reports storage is not configured.
+     */
+    useObjectStorage?: boolean;
+    /**
+     * Route telemetry lanes (events/network/errors/performance/logs) through the
+     * durable NATIVE file outbox instead of JS-side HTTP. Only takes effect when BOTH
+     * this and `nativeOutboxUploadEnabled` are true AND the native module exposes the
+     * outbox methods — otherwise the existing JS upload path is used unchanged. When
+     * active, the native uploader owns delivery (no duplicate JS POST). Default false.
+     */
+    enableNativeFileOutbox?: boolean;
+    /** Native outbox actually uploads (vs. capture/store-only). Gates telemetry routing. */
+    nativeOutboxUploadEnabled?: boolean;
+    /**
+     * Additive native-outbox tuning flags (retry interval, attempt caps, Retry-After,
+     * byte/age GC bounds, etc.) forwarded verbatim to the native `initOutbox` dict.
+     * Native parses both `nativeOutbox*` and bare `outbox*` keys and applies its own
+     * defaults for anything omitted — so an empty object changes nothing.
+     */
+    nativeOutboxTuning?: Record<string, unknown>;
+    /** Idle-gap threshold (ms) the SDK recorded with; persisted on the session row. */
+    idleThresholdMs?: number;
+    /**
+     * Durable key-value store used to persist the unflushed frame buffer across a
+     * process kill. On background the in-flight frames are snapshotted here; on the
+     * next launch they are re-uploaded and linked to the PRIOR session. Omitted →
+     * frame-kill recovery is disabled (in-memory only, prior behavior).
+     */
+    storage?: StorageBackend;
+}
+
+/**
+ * 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.
+ */
+export interface LogQueueItem {
+    level: string;
+    message: string;
+    source: string;
+    platform: string;
+    timestamp: string;
+    metadata?: Record<string, unknown>;
+}
+
+// ─── Adapter ────────────────────────────────────────────────────────────────
+
+export class BackendSessionAdapter implements SessionTransport {
+    private config: Required<Omit<BackendSessionConfig, 'clientKey' | 'storage'>> & { clientKey?: string; storage?: StorageBackend };
+    /** Durable store for cross-kill frame recovery (null → recovery disabled). */
+    private readonly _frameStore: StorageBackend | null;
+    /** Storage key for the snapshotted unflushed frame buffer (see persistPendingFrames). */
+    private static readonly 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.
+     */
+    private static readonly 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.
+     */
+    private static readonly MAX_FRAMES_PER_BATCH = 100;
+    // Per-session toggle: cleared to false if the backend reports storage disabled.
+    private objectStorageActive: boolean;
+    // 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.
+    private readonly nativeOutboxEnabled: boolean;
+    // Cached one-shot native-outbox bootstrap promise (see _ensureNativeOutbox).
+    private _nativeOutboxReady: Promise<boolean> | null = null;
+    private currentSessionId: string | null = 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.
+    private readonly _startedSessionIds = new Set<string>();
+    // §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).
+    private readonly _pendingStartPayloads = new Map<string, Record<string, unknown>>();
+    private _startRetryInFlight = false;
+    private pendingFrames: Array<{ frame: ReplayFrame; imageData: string }> = [];
+    private pendingEvents: JourneyEvent[] = [];
+    private pendingNetworkRequests: Array<Record<string, unknown>> = [];
+    private pendingErrors: Array<Record<string, unknown>> = [];
+    private pendingPerformanceMetrics: Array<Record<string, unknown>> = [];
+    // Platform-agnostic logs lane. Neutral by construction — holds whatever LogQueueItems
+    // it's handed (console today; native later) and forwards them untouched.
+    private pendingLogs: LogQueueItem[] = [];
+    private flushTimer: ReturnType<typeof setInterval> | null = null;
+    private 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.
+     */
+    private _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.
+    private static readonly ANALYTICS_BUFFER_CAP = 100;
+    /** Logs lane: queue length that triggers an eager flush (mirrors the network lane). */
+    private static readonly LOGS_BATCH_SIZE = 20;
+    /** Logs lane: max rows posted per flush (server caps at 200/batch). */
+    private static readonly LOGS_FLUSH_MAX = 50;
+    private _analyticsSessionId: string | null = null;
+    private pendingAnalyticsEvents: JourneyEvent[] = [];
+    private analyticsFlushTimer: ReturnType<typeof setInterval> | null = 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).
+    private _pendingFinalizeId: string | null = null;
+
+    // ── Per-feature quota (shared contract v1) ──
+    /** Unsubscribe from quotaState (set in the constructor, released in destroy). */
+    private _quotaUnsub: (() => void) | null = 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.
+     */
+    private readonly _refusedSessionIds = new Set<string>();
+    /** Unregister this adapter as the native sessions-refusal handler. */
+    private _nativeRefusedUnsub: (() => void) | null = null;
+    /** Host hook (SessionManager) to end a recording whose session start was refused. */
+    private _onSessionRefused: ((sessionId: string) => void) | null = null;
+
+    constructor(config: BackendSessionConfig) {
+        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.
+     */
+    private _sessionRowReady(): boolean {
+        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.
+     */
+    private _errorsSessionId(): string | null {
+        return this.currentSessionId ?? this._analyticsSessionId;
+    }
+
+    /** Lazy: nativeCrashBridge → CrashReporter → SessionManager → this file would be a cycle. */
+    private _publishNativeSession(sessionId: string): void {
+        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). */
+    private _currentSessionRefused(): boolean {
+        return !!this.currentSessionId && this._refusedSessionIds.has(this.currentSessionId);
+    }
+
+    /** Register the host's reaction to a refused session start (SessionManager ends the recording). */
+    setSessionRefusedHandler(fn: ((sessionId: string) => void) | null): void {
+        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).
+     */
+    private _onQuotaChange(feature: QuotaFeature, blocked: boolean): void {
+        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.
+     */
+    private _refuseSession(sessionId: string): void {
+        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. */
+    private static _isQuotaRefusal(err: unknown, feature?: QuotaFeature): boolean {
+        const f = (err as { quotaFeature?: QuotaFeature | null })?.quotaFeature;
+        return !!f && (feature === undefined || f === feature);
+    }
+
+    sendSessionStart(session: Session): void {
+        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: Session): void {
+        __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(): string | null {
+        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: {
+        sessionId: string;
+        deviceId: string;
+        startedAt: number;
+        metadata?: SessionMetadata;
+        /** Idle-gap threshold (ms) the SDK declares for this session; echoed by the
+         *  backend so the dashboard uses the same value to draw idle bands. */
+        idleThresholdMs?: number;
+    }): Promise<void> {
+        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.
+     */
+    private _retryPendingStarts(): void {
+        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 as
+            | [string, Record<string, unknown>]
+            | undefined;
+        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: JourneyEvent): void {
+        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: 'APP_BACKGROUND' | 'APP_FOREGROUND',
+        payload?: Record<string, unknown>,
+    ): void {
+        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(): Promise<void> {
+        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.
+     */
+    private async _flushAnalyticsEvents(forSessionId?: string): Promise<void> {
+        // 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(): Promise<void> {
+        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(): Promise<void> {
+        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;
+        }
+    }
+
+    private _startAnalyticsFlushTimer(): void {
+        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);
+    }
+
+    private _stopAnalyticsFlushTimer(): void {
+        if (this.analyticsFlushTimer) {
+            clearInterval(this.analyticsFlushTimer);
+            this.analyticsFlushTimer = null;
+        }
+    }
+
+    sendEvent(event: JourneyEvent): void {
+        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: ReplayFrame, imageData: string): void {
+        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: {
+        method: string; url: string; statusCode?: number; duration?: number;
+        screenName?: string; error?: string; requestSize?: number; responseSize?: number;
+        requestHeaders?: Record<string, string>; responseHeaders?: Record<string, string>;
+        requestBody?: string; responseBody?: string;
+    }): void {
+        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. */
+    private _cachedAppVersion: string | null = null;
+
+    private _appVersion(): string | undefined {
+        return this._cachedAppVersion ?? undefined;
+    }
+
+    queueError(data: {
+        type: string; message: string; stack?: string; screenName?: string;
+        platform?: string;
+        appVersion?: string;
+        isFatal?: boolean;
+        metadata?: Record<string, unknown>;
+        /** Target session. Set ONLY by a recovered native crash; absent means the current session. */
+        sessionId?: string;
+        /** Stable idempotency key. Set ONLY by a recovered crash; the backend dedupes on it. */
+        clientId?: string;
+    }): void {
+        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(): Promise<boolean> {
+        /*
+         * 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. */
+    private _errorsFlushTail: Promise<boolean> = 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(): Promise<void> {
+        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: {
+        type: string; screenName?: string; duration?: number; value?: number;
+        metadata?: Record<string, unknown>;
+    }): void {
+        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: {
+        level: string; message: string; source: string; platform: string;
+        timestamp?: string; metadata?: Record<string, unknown>;
+    }): void {
+        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). */
+    private _clientId(): string {
+        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.
+     */
+    private async _enqueueNative(
+        lane: 'events' | 'network' | 'errors' | 'performance' | 'logs',
+        records: Array<Record<string, unknown>>,
+        /**
+         * 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?: string,
+    ): Promise<boolean> {
+        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).
+     */
+    private _ensureNativeOutbox(native: ReplaySdkNativeModule): Promise<boolean> {
+        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(): Promise<boolean> {
+        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. */
+    private _triggerNativeFlush(): void {
+        if (!this.nativeOutboxEnabled) return;
+        try {
+            getReplaySdkNative()?.flushNativeOutbox?.().catch(() => { });
+        } catch {
+            /* old binary / unavailable — ignore */
+        }
+    }
+
+    // ─── Lifecycle ──────────────────────────────────────────────────────
+
+    destroy(): void {
+        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). */
+    private _frameMeta(b: { frame: ReplayFrame; imageData: string }) {
+        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.
+     */
+    private _leanEvent(e: JourneyEvent, sessionId: string): Record<string, unknown> {
+        const out: Record<string, unknown> = {
+            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. */
+    private _pruneEmpty(payload: unknown): Record<string, unknown> | undefined {
+        if (!payload || typeof payload !== 'object') return undefined;
+        const src = payload as Record<string, unknown>;
+        const out: Record<string, unknown> = {};
+        for (const k of Object.keys(src)) {
+            const v = src[k];
+            if (v === null || v === undefined || v === '') continue;
+            out[k] = v;
+        }
+        return out;
+    }
+
+    private async _flushFrames(): Promise<void> {
+        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.
+     */
+    private _reportCaptureFailure(stage: string, err: unknown, frameCount: number): void {
+        if (this._captureFailureReported) return;
+        this._captureFailureReported = true;
+        try {
+            if (!this._analyticsSessionId) return; // no lane open — nothing to attach it to
+            const status = (err as { status?: number })?.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',
+                },
+            } as unknown as JourneyEvent);
+        } 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.
+     */
+    private async _postFramesChunked(
+        sessionId: string,
+        items: Array<{ frame: ReplayFrame; imageData: string }>,
+    ): Promise<Array<{ frame: ReplayFrame; imageData: string }>> {
+        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.
+     */
+    private async _postFrameBatch(
+        sessionId: string,
+        batch: Array<{ frame: ReplayFrame; imageData: string }>,
+    ): Promise<void> {
+        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(): void {
+        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.
+     */
+    private static _selectFramesToPersist(
+        pending: Array<{ frame: ReplayFrame; imageData: string }>,
+    ): Array<{ frame: ReplayFrame; imageData: string }> {
+        const isKeyframe = (b: { frame: ReplayFrame }) => b.frame.frameType !== 'delta';
+        const size = (b: { imageData: string }) => b.imageData?.length ?? 0;
+
+        const keep: Array<{ frame: ReplayFrame; imageData: string }> = [];
+        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. */
+    private _clearPersistedFrames(): void {
+        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(): Promise<void> {
+        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: string | undefined;
+        try {
+            raw = this._frameStore.get(BackendSessionAdapter.PENDING_FRAMES_KEY);
+        } catch {
+            return;
+        }
+        if (!raw) return;
+
+        let parsed: { sessionId?: string; items?: Array<{ frame: ReplayFrame; imageData: string }> };
+        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.
+     */
+    private async _uploadFramesViaStorage(
+        sessionId: string,
+        batch: Array<{ frame: ReplayFrame; imageData: string }>,
+    ): Promise<'sent' | 'disabled'> {
+        // 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<{ enabled: boolean; frames?: Array<{ frameId: string; uploadUrl: string; storageKey: string; bucket: string; contentType: string }> }>(
+            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';
+    }
+
+    private async _flushEvents(): Promise<void> {
+        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);
+        }
+    }
+
+    private async _flushNetwork(): Promise<void> {
+        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: { message: string; title?: string; email?: string }): void {
+        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.
+     */
+    private async _flushErrors(): Promise<boolean> {
+        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<string, typeof batch>();
+            for (const e of batch) {
+                const target = (e as { sessionId?: string }).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 }: any) => 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 as { status?: number })?.status === 404 && target !== live) {
+                        const moved = cleaned.map((e: any) => ({
+                            ...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;
+        }
+    }
+
+    private async _flushPerformance(): Promise<void> {
+        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);
+        }
+    }
+
+    private async _flushLogs(): Promise<void> {
+        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 as unknown as Array<Record<string, unknown>>)) 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 ────────────────────────────────────────────────
+
+    private _startFlushTimer(): void {
+        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);
+    }
+
+    private _stopFlushTimer(): void {
+        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.
+    private static _isPermanentHttpError(err: unknown): boolean {
+        const status = (err as { status?: number })?.status;
+        return typeof status === 'number' && status >= 400 && status < 500 && status !== 408 && status !== 429;
+    }
+
+    private async _post(path: string, body: unknown): Promise<void> {
+        const url = `${this.config.endpoint}${path}`;
+
+        try {
+            const controller = new AbortController();
+            const timeout = setTimeout(() => controller.abort(), this.config.timeoutMs);
+
+            try {
+                const headers: Record<string, string> = { '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}`) as Error & { status?: number; quotaFeature?: QuotaFeature | null };
+                    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: any) {
+            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.
+     */
+    private static async _noteQuota(response: Response): Promise<QuotaFeature | null> {
+        const status = response?.status;
+        if (status !== 402 && !(status >= 200 && status < 300)) return null;
+        if (typeof (response as { json?: unknown })?.json !== 'function') return null;
+        try {
+            const body = await response.json();
+            return noteQuotaResponse(status, body, (response as { headers?: any }).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).
+     */
+    private async _postReturning<T>(path: string, body: unknown): Promise<T> {
+        const url = `${this.config.endpoint}${path}`;
+
+        const controller = new AbortController();
+        const timeout = setTimeout(() => controller.abort(), this.config.timeoutMs);
+        try {
+            const headers: Record<string, string> = { '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}`) as Error & { status?: number; quotaFeature?: QuotaFeature | null };
+                httpErr.status = response.status;
+                httpErr.quotaFeature = await BackendSessionAdapter._noteQuota(response);
+                throw httpErr;
+            }
+            const parsed = (await response.json()) as T;
+            // A 2xx can carry a partial grant (`quota.refused > 0`) — record it (frames presign).
+            try { noteQuotaResponse(response.status, parsed, (response as { headers?: any }).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.
+     */
+    private async _putBytes(uploadUrl: string, bytes: Uint8Array, contentType: string): Promise<void> {
+
+        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. */
+    private _stripDataUri(s: string): string {
+        const comma = s.indexOf(',');
+        return s.startsWith('data:') && comma !== -1 ? s.slice(comma + 1) : s;
+    }
+}