@scalebun/react-native 1.0.0 → 1.0.2

package/src/features/session/BackendSessionAdapter.ts

@@ -1,1233 +1,1233 @@
-/**
- * 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 { 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';
-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';
-    /** Cap on frames persisted per snapshot — bounds KV footprint (keeps the most recent). */
-    private static readonly MAX_PERSIST_FRAMES = 10;
-    // 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>();
-    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;
-
-    // ── 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;
-
-    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;
-        logger.info(`[ScaleBun Replay] backendUpload enabled`);
-        logger.info(`[ScaleBun Replay] backendBaseUrl: ${this.config.endpoint}`);
-        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);
-    }
-
-    sendSessionStart(session: Session): void {
-        this.currentSessionId = session.sessionId;
-        this._startFlushTimer();
-
-        logger.info(`[ScaleBun Replay] session start requested`);
-        logger.info(`[ScaleBun Replay] sessionId: ${session.sessionId}`);
-        logger.info(`[ScaleBun Replay] deviceId: ${session.deviceId}`);
-        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) {
-            logger.info(`[ScaleBun Replay] recording attached to analytics session ${session.sessionId} (no new row)`);
-            return;
-        }
-
-        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;
-                const payload = {
-                    sessionId: session.sessionId,
-                    deviceId: session.deviceId,
-                    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,
-                    },
-                };
-                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);
-                logger.info(`[ScaleBun Replay] backend session upload success`);
-            })
-            .catch(() => logger.info(`[ScaleBun Replay] backend session upload failure`));
-    }
-
-    sendSessionEnd(session: Session): void {
-        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) {
-                logger.info(`[ScaleBun Replay] recording ended; analytics session ${session.sessionId} stays open`);
-                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(() => {
-            logger.info(`[ScaleBun Replay] finalize success`);
-        }).catch(() => { 
-            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();
-            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;
-        this._analyticsSessionId = session.sessionId;
-        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;
-            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,
-                },
-            };
-            await this._post(startEndpoint, payload);
-            // §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);
-            // 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(() => { });
-            logger.info(`[ScaleBun Analytics] session start upload success: ${session.sessionId}`);
-        } catch {
-            logger.info(`[ScaleBun Analytics] session start upload failure`);
-        }
-    }
-
-    /**
-     * 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;
-        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;
-
-        // 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 });
-            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;
-            logger.debug(`[BackendSessionAdapter] Analytics session finalized: ${sessionId}`);
-        } catch {
-            // Leave the marker set — foreground reconciliation will retry the close.
-            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;
-
-        try {
-            const finalizeEndpoint = this.config.clientKey
-                ? ENDPOINTS.INGESTION_FINALIZE(sessionId)
-                : `/replay/sessions/${sessionId}/finalize`;
-            await this._post(finalizeEndpoint, { endedAt: Date.now() });
-            logger.info(`[ScaleBun Analytics] reconciled finalize on foreground: ${sessionId}`);
-        } catch {
-            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._flushAnalyticsEvents().catch(() => { });
-        }, this.config.flushIntervalMs);
-    }
-
-    private _stopAnalyticsFlushTimer(): void {
-        if (this.analyticsFlushTimer) {
-            clearInterval(this.analyticsFlushTimer);
-            this.analyticsFlushTimer = null;
-        }
-    }
-
-    sendEvent(event: JourneyEvent): void {
-        if (this.destroyed) return;
-
-        logger.info(`[ScaleBun Replay] event recorded`);
-        logger.info(`  eventId: ${event.eventId}`);
-        logger.info(`  type: ${event.type}`);
-        logger.info(`  timestamp: ${event.ts}`);
-        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;
-
-        logger.info(`[ScaleBun Replay] frame captured`);
-        logger.info(`  frameId: ${frame.frameId}`);
-        logger.info(`  timestamp: ${frame.ts}`);
-        logger.info(`  sessionId: ${frame.sessionId}`);
-        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>;
-    }): void {
-        if (this.destroyed || !this.config.clientKey) 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(() => {});
-        }
-    }
-
-    queueError(data: {
-        type: string; message: string; stack?: string; screenName?: string;
-    }): void {
-        if (this.destroyed || !this.config.clientKey) return;
-        this.pendingErrors.push({ ...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). */
-    flushErrors(): Promise<void> {
-        return this._flushErrors();
-    }
-
-    /**
-     * Public: flush ALL recording-lane queues immediately. Called on APP_BACKGROUND
-     * so the server-side reaper computes endedAt from the freshest data even when
-     * the OS suspends the flush timer right after backgrounding.
-     */
-    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) return;
-        this.pendingPerformanceMetrics.push({ ...data, clientId: this._clientId(), timestamp: new Date().toISOString() });
-        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;
-        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>>,
-    ): Promise<boolean> {
-        if (!this.nativeOutboxEnabled || !this.currentSessionId) return false;
-        const native = getReplaySdkNative();
-        if (!native?.enqueueOutboxRecords) return false;
-        if (!(await this._ensureNativeOutbox(native))) return false;
-        try {
-            return await native.enqueueOutboxRecords(lane, this.currentSessionId, records);
-        } 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);
-        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._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();
-    }
-
-    // ─── 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',
-        };
-    }
-
-    /**
-     * 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;
-        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;
-        // §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);
-        try {
-            await this._postFrameBatch(sessionId, batch);
-            logger.debug(`[BackendSessionAdapter] Flushed ${batch.length} frame(s)`);
-            // Delivered — the durable snapshot (if any) is now redundant. Clear it once
-            // the in-memory buffer is fully drained so a later kill can't replay
-            // already-uploaded frames.
-            if (this.pendingFrames.length === 0) this._clearPersistedFrames();
-        } catch (err) {
-            if (BackendSessionAdapter._isPermanentHttpError(err)) return;
-            logger.warn(`[replay.sdk.error] backend frame upload failure`, { count: batch.length });
-            // Re-queue on failure
-            this.pendingFrames.unshift(...batch);
-        }
-    }
-
-    /**
-     * 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;
-        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') {
-                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 });
-        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;
-        try {
-            const items = this.pendingFrames.slice(-BackendSessionAdapter.MAX_PERSIST_FRAMES);
-            this._frameStore.set(
-                BackendSessionAdapter.PENDING_FRAMES_KEY,
-                JSON.stringify({ sessionId: this.currentSessionId, items }),
-            );
-        } catch {
-            // Serialization/storage failure must never break backgrounding.
-        }
-    }
-
-    /** 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;
-        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;
-        }
-
-        try {
-            logger.info(`[replay.sdk.frame] recovering ${items.length} frame(s) for prior session ${sessionId}`);
-            await this._postFrameBatch(sessionId, items);
-            this._clearPersistedFrames();
-        } catch (err) {
-            if (BackendSessionAdapter._isPermanentHttpError(err)) {
-                // Server rejected permanently (e.g. session gone) — don't retry forever.
-                this._clearPersistedFrames();
-                return;
-            }
-            // Transient — keep the snapshot for the next launch.
-            logger.warn(`[replay.sdk.frame] prior-session frame recovery deferred (transient)`);
-        }
-    }
-
-    /**
-     * 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'> {
-        const presignReq = batch.map(b => {
-            const m = this._frameMeta(b);
-            return { frameId: m.frameId, contentType: m.contentType, format: m.format };
-        });
-        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]));
-
-        // Upload bytes directly to storage (backend never sees image bytes here).
-        await Promise.all(batch.map(async b => {
-            const p = byFrameId.get(b.frame.frameId);
-            if (!p) throw new Error(`No presign URL for frame ${b.frame.frameId}`);
-            await this._putBytes(p.uploadUrl, b.imageData, p.contentType);
-        }));
-
-        // Persist key-only metadata (no base64 in the body).
-        const frames = batch.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;
-
-        const batch = this.pendingEvents.splice(0, 20);
-        const events = batch.map(e => this._leanEvent(e, e.sessionId));
-
-        try {
-            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 },
-            );
-            logger.info(`[replay.sdk.event] backend event upload success`);
-            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;
-        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);
-        }
-    }
-
-    private async _flushErrors(): Promise<void> {
-        if (this.pendingErrors.length === 0 || !this.currentSessionId || !this.config.clientKey) return;
-        const batch = this.pendingErrors.splice(0, 20);
-        try {
-            if (await this._enqueueNative('errors', batch)) return;
-            if (!this._sessionRowReady()) { this.pendingErrors.unshift(...batch); return; }
-            await this._post(ENDPOINTS.INGESTION_ERRORS(this.currentSessionId), { errors: batch });
-        } catch (err) {
-            if (!BackendSessionAdapter._isPermanentHttpError(err)) this.pendingErrors.unshift(...batch);
-        }
-    }
-
-    private async _flushPerformance(): Promise<void> {
-        if (this.pendingPerformanceMetrics.length === 0 || !this.currentSessionId || !this.config.clientKey) return;
-        const batch = this.pendingPerformanceMetrics.splice(0, 50);
-        try {
-            if (await this._enqueueNative('performance', batch)) return;
-            if (!this._sessionRowReady()) { this.pendingPerformanceMetrics.unshift(...batch); return; }
-            await this._post(ENDPOINTS.INGESTION_PERFORMANCE(this.currentSessionId), { metrics: batch });
-        } catch (err) {
-            if (!BackendSessionAdapter._isPermanentHttpError(err)) this.pendingPerformanceMetrics.unshift(...batch);
-        }
-    }
-
-    private async _flushLogs(): Promise<void> {
-        if (this.pendingLogs.length === 0 || !this.currentSessionId || !this.config.clientKey) 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._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 };
-                    httpErr.status = response.status;
-                    throw httpErr;
-                }
-            } 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;
-        }
-    }
-
-    /**
-     * 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 };
-                httpErr.status = response.status;
-                throw httpErr;
-            }
-            return (await response.json()) as T;
-        } finally {
-            clearTimeout(timeout);
-        }
-    }
-
-    /**
-     * PUT raw image bytes directly to a presigned storage URL. Decodes the base64
-     * frame payload to a binary Blob so the wire body is bytes, not a base64 string.
-     * No client key header — the presigned URL carries its own auth.
-     */
-    private async _putBytes(uploadUrl: string, base64: string, contentType: string): Promise<void> {
-        // RN-safe base64→binary: decode to a Uint8Array and send that as the body.
-        // The `fetch('data:…').blob()` round-trip fails under the new architecture
-        // ("Network request failed"); RN's XHR sends a typed array as real binary.
-        const bytes = base64ToBytes(this._stripDataUri(base64));
-
-        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;
-    }
-}
+/**
+ * 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 { 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';
+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';
+    /** Cap on frames persisted per snapshot — bounds KV footprint (keeps the most recent). */
+    private static readonly MAX_PERSIST_FRAMES = 10;
+    // 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>();
+    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;
+
+    // ── 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;
+
+    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;
+        logger.info(`[ScaleBun Replay] backendUpload enabled`);
+        logger.info(`[ScaleBun Replay] backendBaseUrl: ${this.config.endpoint}`);
+        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);
+    }
+
+    sendSessionStart(session: Session): void {
+        this.currentSessionId = session.sessionId;
+        this._startFlushTimer();
+
+        logger.info(`[ScaleBun Replay] session start requested`);
+        logger.info(`[ScaleBun Replay] sessionId: ${session.sessionId}`);
+        logger.info(`[ScaleBun Replay] deviceId: ${session.deviceId}`);
+        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) {
+            logger.info(`[ScaleBun Replay] recording attached to analytics session ${session.sessionId} (no new row)`);
+            return;
+        }
+
+        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;
+                const payload = {
+                    sessionId: session.sessionId,
+                    deviceId: session.deviceId,
+                    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,
+                    },
+                };
+                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);
+                logger.info(`[ScaleBun Replay] backend session upload success`);
+            })
+            .catch(() => logger.info(`[ScaleBun Replay] backend session upload failure`));
+    }
+
+    sendSessionEnd(session: Session): void {
+        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) {
+                logger.info(`[ScaleBun Replay] recording ended; analytics session ${session.sessionId} stays open`);
+                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(() => {
+            logger.info(`[ScaleBun Replay] finalize success`);
+        }).catch(() => { 
+            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();
+            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;
+        this._analyticsSessionId = session.sessionId;
+        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;
+            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,
+                },
+            };
+            await this._post(startEndpoint, payload);
+            // §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);
+            // 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(() => { });
+            logger.info(`[ScaleBun Analytics] session start upload success: ${session.sessionId}`);
+        } catch {
+            logger.info(`[ScaleBun Analytics] session start upload failure`);
+        }
+    }
+
+    /**
+     * 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;
+        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;
+
+        // 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 });
+            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;
+            logger.debug(`[BackendSessionAdapter] Analytics session finalized: ${sessionId}`);
+        } catch {
+            // Leave the marker set — foreground reconciliation will retry the close.
+            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;
+
+        try {
+            const finalizeEndpoint = this.config.clientKey
+                ? ENDPOINTS.INGESTION_FINALIZE(sessionId)
+                : `/replay/sessions/${sessionId}/finalize`;
+            await this._post(finalizeEndpoint, { endedAt: Date.now() });
+            logger.info(`[ScaleBun Analytics] reconciled finalize on foreground: ${sessionId}`);
+        } catch {
+            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._flushAnalyticsEvents().catch(() => { });
+        }, this.config.flushIntervalMs);
+    }
+
+    private _stopAnalyticsFlushTimer(): void {
+        if (this.analyticsFlushTimer) {
+            clearInterval(this.analyticsFlushTimer);
+            this.analyticsFlushTimer = null;
+        }
+    }
+
+    sendEvent(event: JourneyEvent): void {
+        if (this.destroyed) return;
+
+        logger.info(`[ScaleBun Replay] event recorded`);
+        logger.info(`  eventId: ${event.eventId}`);
+        logger.info(`  type: ${event.type}`);
+        logger.info(`  timestamp: ${event.ts}`);
+        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;
+
+        logger.info(`[ScaleBun Replay] frame captured`);
+        logger.info(`  frameId: ${frame.frameId}`);
+        logger.info(`  timestamp: ${frame.ts}`);
+        logger.info(`  sessionId: ${frame.sessionId}`);
+        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>;
+    }): void {
+        if (this.destroyed || !this.config.clientKey) 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(() => {});
+        }
+    }
+
+    queueError(data: {
+        type: string; message: string; stack?: string; screenName?: string;
+    }): void {
+        if (this.destroyed || !this.config.clientKey) return;
+        this.pendingErrors.push({ ...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). */
+    flushErrors(): Promise<void> {
+        return this._flushErrors();
+    }
+
+    /**
+     * Public: flush ALL recording-lane queues immediately. Called on APP_BACKGROUND
+     * so the server-side reaper computes endedAt from the freshest data even when
+     * the OS suspends the flush timer right after backgrounding.
+     */
+    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) return;
+        this.pendingPerformanceMetrics.push({ ...data, clientId: this._clientId(), timestamp: new Date().toISOString() });
+        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;
+        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>>,
+    ): Promise<boolean> {
+        if (!this.nativeOutboxEnabled || !this.currentSessionId) return false;
+        const native = getReplaySdkNative();
+        if (!native?.enqueueOutboxRecords) return false;
+        if (!(await this._ensureNativeOutbox(native))) return false;
+        try {
+            return await native.enqueueOutboxRecords(lane, this.currentSessionId, records);
+        } 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);
+        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._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();
+    }
+
+    // ─── 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',
+        };
+    }
+
+    /**
+     * 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;
+        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;
+        // §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);
+        try {
+            await this._postFrameBatch(sessionId, batch);
+            logger.debug(`[BackendSessionAdapter] Flushed ${batch.length} frame(s)`);
+            // Delivered — the durable snapshot (if any) is now redundant. Clear it once
+            // the in-memory buffer is fully drained so a later kill can't replay
+            // already-uploaded frames.
+            if (this.pendingFrames.length === 0) this._clearPersistedFrames();
+        } catch (err) {
+            if (BackendSessionAdapter._isPermanentHttpError(err)) return;
+            logger.warn(`[replay.sdk.error] backend frame upload failure`, { count: batch.length });
+            // Re-queue on failure
+            this.pendingFrames.unshift(...batch);
+        }
+    }
+
+    /**
+     * 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;
+        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') {
+                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 });
+        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;
+        try {
+            const items = this.pendingFrames.slice(-BackendSessionAdapter.MAX_PERSIST_FRAMES);
+            this._frameStore.set(
+                BackendSessionAdapter.PENDING_FRAMES_KEY,
+                JSON.stringify({ sessionId: this.currentSessionId, items }),
+            );
+        } catch {
+            // Serialization/storage failure must never break backgrounding.
+        }
+    }
+
+    /** 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;
+        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;
+        }
+
+        try {
+            logger.info(`[replay.sdk.frame] recovering ${items.length} frame(s) for prior session ${sessionId}`);
+            await this._postFrameBatch(sessionId, items);
+            this._clearPersistedFrames();
+        } catch (err) {
+            if (BackendSessionAdapter._isPermanentHttpError(err)) {
+                // Server rejected permanently (e.g. session gone) — don't retry forever.
+                this._clearPersistedFrames();
+                return;
+            }
+            // Transient — keep the snapshot for the next launch.
+            logger.warn(`[replay.sdk.frame] prior-session frame recovery deferred (transient)`);
+        }
+    }
+
+    /**
+     * 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'> {
+        const presignReq = batch.map(b => {
+            const m = this._frameMeta(b);
+            return { frameId: m.frameId, contentType: m.contentType, format: m.format };
+        });
+        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]));
+
+        // Upload bytes directly to storage (backend never sees image bytes here).
+        await Promise.all(batch.map(async b => {
+            const p = byFrameId.get(b.frame.frameId);
+            if (!p) throw new Error(`No presign URL for frame ${b.frame.frameId}`);
+            await this._putBytes(p.uploadUrl, b.imageData, p.contentType);
+        }));
+
+        // Persist key-only metadata (no base64 in the body).
+        const frames = batch.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;
+
+        const batch = this.pendingEvents.splice(0, 20);
+        const events = batch.map(e => this._leanEvent(e, e.sessionId));
+
+        try {
+            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 },
+            );
+            logger.info(`[replay.sdk.event] backend event upload success`);
+            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;
+        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);
+        }
+    }
+
+    private async _flushErrors(): Promise<void> {
+        if (this.pendingErrors.length === 0 || !this.currentSessionId || !this.config.clientKey) return;
+        const batch = this.pendingErrors.splice(0, 20);
+        try {
+            if (await this._enqueueNative('errors', batch)) return;
+            if (!this._sessionRowReady()) { this.pendingErrors.unshift(...batch); return; }
+            await this._post(ENDPOINTS.INGESTION_ERRORS(this.currentSessionId), { errors: batch });
+        } catch (err) {
+            if (!BackendSessionAdapter._isPermanentHttpError(err)) this.pendingErrors.unshift(...batch);
+        }
+    }
+
+    private async _flushPerformance(): Promise<void> {
+        if (this.pendingPerformanceMetrics.length === 0 || !this.currentSessionId || !this.config.clientKey) return;
+        const batch = this.pendingPerformanceMetrics.splice(0, 50);
+        try {
+            if (await this._enqueueNative('performance', batch)) return;
+            if (!this._sessionRowReady()) { this.pendingPerformanceMetrics.unshift(...batch); return; }
+            await this._post(ENDPOINTS.INGESTION_PERFORMANCE(this.currentSessionId), { metrics: batch });
+        } catch (err) {
+            if (!BackendSessionAdapter._isPermanentHttpError(err)) this.pendingPerformanceMetrics.unshift(...batch);
+        }
+    }
+
+    private async _flushLogs(): Promise<void> {
+        if (this.pendingLogs.length === 0 || !this.currentSessionId || !this.config.clientKey) 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._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 };
+                    httpErr.status = response.status;
+                    throw httpErr;
+                }
+            } 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;
+        }
+    }
+
+    /**
+     * 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 };
+                httpErr.status = response.status;
+                throw httpErr;
+            }
+            return (await response.json()) as T;
+        } finally {
+            clearTimeout(timeout);
+        }
+    }
+
+    /**
+     * PUT raw image bytes directly to a presigned storage URL. Decodes the base64
+     * frame payload to a binary Blob so the wire body is bytes, not a base64 string.
+     * No client key header — the presigned URL carries its own auth.
+     */
+    private async _putBytes(uploadUrl: string, base64: string, contentType: string): Promise<void> {
+        // RN-safe base64→binary: decode to a Uint8Array and send that as the body.
+        // The `fetch('data:…').blob()` round-trip fails under the new architecture
+        // ("Network request failed"); RN's XHR sends a typed array as real binary.
+        const bytes = base64ToBytes(this._stripDataUri(base64));
+
+        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;
+    }
+}