@scalebun-release/web 2.2.2

package/dist/pipeline/pipeline.js

@@ -0,0 +1,783 @@
+/**
+ * THE pipeline — the SDK's single egress. Every feature emits Items here; this batches them into
+ * SessionEnvelopes and flushes on a timer / on page-hide. At-least-once: a failed batch is
+ * re-queued and mirrored to IndexedDB so it survives a reload.
+ */
+import { PersistentBuffer } from '../storage/idb.js';
+import { now } from '../core/index.js';
+import { Backoff, isOnline } from '../core/retry.js';
+import { capBytes, freshOnly } from '../core/prune.js';
+// Inlined (not imported) so the zod-laden `@scalebun/protocol` barrel — and zod itself (~12 KB gz) —
+// stays OUT of the SDK bundle; SCHEMA_VERSION was the only runtime import that pulled it. The type
+// annotation pins this to the contract: a protocol SCHEMA_VERSION bump fails the SDK build. The
+// `import(...)` is type-only (erased), so it adds zero runtime weight.
+const SCHEMA_VERSION = 1;
+/** Replay-frame discriminators, shared by the queue-eviction and byte-cap policies so the two cannot
+ *  disagree about what a keyframe is. Structural checks — the frame types live in the lazy replay
+ *  chunk and must not be imported into the eager core. */
+const isFrame = (it) => it.kind === 'frame';
+const isKeyframe = (it) => it.frameType === 'keyframe';
+/** Re-arm attempts for a failed session-create. Small on purpose: this covers a transient 5xx or a
+ *  boot while offline, not a server that is refusing on principle. */
+const MAX_SESSION_RETRIES = 3;
+/**
+ * Serialized-byte budget for an unload (keepalive) batch.
+ *
+ * Fetch caps the SUM of in-flight keepalive bodies at 64 KiB per agent, so this leaves room for the
+ * envelope around the items (client/device/app/context) and for anything else the page may already
+ * have in flight. Under the cap the request is delivered; over it, it is refused outright.
+ */
+const KEEPALIVE_BUDGET_B = 48000;
+/** Batches one `drain()` will send before yielding to the next tick. `maxQueueSize` (1,000) over
+ *  `maxBatchSize` (50) is 20, so this empties a completely full queue and no more. */
+const MAX_DRAIN_BATCHES = 20;
+/** Serialized size of one item, for the keepalive budget. Falls back to a coarse, deliberately
+ *  PESSIMISTIC charge when an item will not stringify, so an unmeasurable item cannot silently
+ *  overrun the budget it is supposed to be constrained by. */
+function approxItemBytes(it) {
+    try {
+        return JSON.stringify(it).length;
+    }
+    catch {
+        return KEEPALIVE_BUDGET_B;
+    }
+}
+export class Pipeline {
+    constructor(config, session, transport) {
+        this.config = config;
+        this.session = session;
+        this.transport = transport;
+        this.queue = [];
+        this.timer = null;
+        this.droppedCount = 0;
+        /**
+         * P6 — the egress ledger. `pending` and `dropped` alone could not answer the question the
+         * reliability work kept running into: recovery demonstrably WORKS (frames arrive with a capture-to-
+         * storage gap of up to 12.8 hours, which only a durable queue draining on a later visit produces)
+         * and its contribution was completely uncountable, so it could never be separated from ordinary
+         * delivery or defended when someone asked whether it was worth its bytes.
+         *
+         * `expired` is split out of `dropped` deliberately. Age-pruning a queue the app sat on for days is
+         * correct behaviour; evicting a live item because the queue overflowed is data loss. Counting both
+         * as "dropped" made a healthy reload look like a leak, which is how a real signal gets ignored.
+         */
+        this.queuedCount = 0;
+        this.attemptedCount = 0;
+        this.retriedCount = 0;
+        this.recoveredCount = 0;
+        this.expiredCount = 0;
+        this.ackedCount = 0;
+        this.started = false;
+        // After discard() (consent denied) no-op ALL egress + persistence, so a racing fire-and-forget
+        // save() / pagehide can't re-persist denied data (drained on the next load). Reset on start().
+        this.dead = false;
+        // Lifecycle flush listeners — kept so stop()/discard() can remove them (no leak across re-init).
+        this.lifecycle = [];
+        this.buffer = new PersistentBuffer();
+        this.backoff = new Backoff();
+        /** True while a flush is awaiting the network. Prevents two flushes (timer + pagehide/keepalive)
+         *  from each splicing a different batch out of the queue. Parity with the in-app transport and the
+         *  RN EventTracker, which both guard; the session lane was the gap. */
+        this.flushing = false;
+        /** Resolves once the server has a session row for these items to attach to. Every flush awaits it
+         *  — see start(). Pre-resolved so a flush before start() (or after stop()) is not deadlocked. */
+        this.sessionStarted = Promise.resolve();
+        /** True once session-create has actually succeeded. See `armSession()`. */
+        this.sessionOk = false;
+        /** Re-arm attempts spent. Bounded so a permanently-refusing server costs a few extra requests
+         *  rather than one per flush for the life of the page. */
+        this.sessionRetries = 0;
+        /** A keyframe wanted the fast path while a batch was in flight — drain again on completion. */
+        this.keyframePending = false;
+        /** The batch currently being sent. It is NOT in `queue`, so persistence must still see it — if the
+         *  page dies mid-send, that fetch is cancelled and the re-queue never runs. */
+        this.inFlight = [];
+        this.consentGranted = !config.consent?.required || config.consent?.initial === 'granted';
+    }
+    /** Open/close the consent egress gate. Opening alone does not start the flush loop (see start()). */
+    setConsentGranted(granted) {
+        this.consentGranted = granted;
+    }
+    /** Whether egress is currently allowed (consent open + not discarded). Direct-send paths that
+     *  bypass emit() (e.g. reportBug) MUST honor this so they don't leak under consent denial. */
+    canEgress() {
+        return this.consentGranted && !this.dead;
+    }
+    async start() {
+        if (this.started)
+            return;
+        this.started = true;
+        this.dead = false; // re-grant after a prior discard() revives egress
+        /**
+         * Session-start is issued FIRST, and synchronously — before this method awaits anything.
+         *
+         * It used to sit after the IndexedDB drain below. That drain is an await, so a keyframe emitted
+         * during it fast-flushed against a `sessionStarted` still holding the pre-resolved default,
+         * and went out before the session existed: measured +7252ms batch, +7260ms session-create, and
+         * the server answers 200 while dropping every item of an unknown session. Assigning the gate
+         * here means there is no window in which a flush can outrun the row it needs.
+         *
+         * Ordering is also just correct on its own terms: nothing the drain recovers can be ingested
+         * until the session exists either.
+         */
+        this.armSession();
+        // Drain anything persisted from a previous page load (at-least-once across reloads), dropping
+        // items older than the max age so a reload doesn't replay data the app sat on for days.
+        try {
+            const raw = await this.buffer.load();
+            // `[sessionId, items]` since the orphan fix; a bare array is a queue persisted by an older
+            // build, which carries no session and can only be replayed under the current one.
+            const sid = typeof raw[0] === 'string' ? raw[0] : '';
+            const prev = (sid ? raw[1] : raw) ?? [];
+            const fresh = freshOnly(prev, (it) => it.timestamp, now());
+            this.expiredCount += prev.length - fresh.length; // age-pruned, not lost — see the ledger note
+            if (fresh.length) {
+                // Recovered = survived a page load. Counted here rather than on delivery so the number means
+                // "the durable queue did its job", independent of whether the network is up right now.
+                this.recoveredCount += fresh.length;
+                if (sid && sid !== this.session.sessionId)
+                    void this.drainOrphans(sid, fresh);
+                else
+                    this.queue.unshift(...fresh);
+            }
+        }
+        catch {
+            /* ignore */
+        }
+        this.timer = setInterval(() => this.autoFlush(), this.config.flushIntervalMs);
+        this.installLifecycleFlush();
+        // A keyframe captured before start() could not fast-flush (no gate yet), so do it here — the
+        // gate now exists and this is the first moment it is safe. Without this, the session that most
+        // needs the fast path (the recorder beat the pipeline) is the one that waits for the timer.
+        if (this.queue.some(isKeyframe))
+            void this.flush();
+    }
+    /**
+     * Issue session-create and hold the gate on it.
+     *
+     * Separate from `start()` because it must be RE-ISSUABLE. It ran exactly once, with its rejection
+     * swallowed by a bare `.catch(() => {})`, so a session-create that failed — offline at boot, a 5xx,
+     * a CORS misconfiguration — left a gate that resolved happily onto a session row the server did not
+     * have. Every subsequent batch was then rejected as `unknown_session`, which is retryable, so the
+     * pipeline retried the same items against a row that nothing was ever going to create. The one
+     * request that could have fixed it was the one request never sent again.
+     *
+     * `sessionOk` is what flush() reads to decide whether re-arming is worth a try; it is false both
+     * before the first attempt resolves and after a failed one.
+     */
+    armSession() {
+        this.sessionOk = false;
+        this.sessionStarted = this.transport
+            .startSession({
+            sessionId: this.session.sessionId,
+            client: this.session.client(),
+            device: this.session.device(),
+            app: this.session.app(),
+            context: this.session.context(),
+        })
+            .then(() => {
+            this.sessionOk = true;
+        })
+            .catch(() => { });
+    }
+    /**
+     * Open the session lane again under the SessionManager's CURRENT id, after a rotation.
+     *
+     * `start()` cannot serve here: it latches on `started` and also drains the persisted buffer, which
+     * belongs to a previous page load and not to a session that began a moment ago in this one. All a
+     * rotation needs is the row — and it genuinely needs it, because the batch endpoint answers 200
+     * while dropping every item of a session it has no row for. `unknown_session` is already the
+     * largest rejection reason in production; rotating without this would make every post-rotation
+     * item join it.
+     *
+     * The retry budget resets with the session: a create that failed for the previous id says nothing
+     * about this one.
+     */
+    async restart() {
+        this.sessionRetries = 0;
+        this.armSession();
+        await this.sessionStarted;
+    }
+    /**
+     * Make room by dropping the OLDEST REPLAY CHAIN whole, instead of one interior delta.
+     *
+     * THE BUG THIS FIXES. This used to evict the oldest DELTA frame, reasoning that a keyframe costs
+     * more to lose and that "the player interpolates across a gap". The player does not interpolate:
+     * `applyMutations` looks the node up, finds nothing, increments `NodeRegistry.misses` and skips the
+     * operation — so the element that mutation would have created never exists, and every later
+     * reference to it misses too. One evicted delta therefore corrupts the rest of the chain, which is
+     * why 1.16% frame loss measured on production put a `Partial reconstruction` badge on 13.5% of
+     * sessions. Loss was rare; it just was not survivable.
+     *
+     * So the unit of eviction is the CHAIN, exactly as `SegmentBuffer` already does for the pre-roll:
+     * drop every frame from the head up to (not including) the next keyframe, and nothing else. What
+     * remains is either intact or is about to be — see the `shed` checkpoint in the recorder, which
+     * opens a fresh chain the moment this fires. Non-frame items are stepped over, never dropped: an
+     * event or a network record has no chain to belong to and its loss buys no room worth having.
+     *
+     * Dropping many items at once is deliberate. A single-item eviction ran again on the very next
+     * emit, so a full queue shed continuously; freeing a whole chain (bounded by the recorder's
+     * 120-frame checkpoint) means this runs once per chain rather than once per frame.
+     */
+    evictChain() {
+        const q = this.queue;
+        let n = 0;
+        for (let i = 0; i < q.length;) {
+            const it = q[i]; // in range by the loop guard (noUncheckedIndexedAccess widens it anyway)
+            if (!isFrame(it)) {
+                i++;
+                continue;
+            }
+            if (n && isKeyframe(it))
+                break; // the next chain starts here — it is intact, keep it
+            q.splice(i, 1);
+            n++;
+        }
+        if (!n) {
+            q.shift(); // no frames at all (events/perf only) — the old drop-oldest still applies
+            n = 1;
+        }
+        this.droppedCount += n;
+    }
+    emit(item) {
+        // Consent gate (belt-and-suspenders for manual facade emits): drop, don't buffer, while gated.
+        if (!this.consentGranted) {
+            this.droppedCount++;
+            return;
+        }
+        if (this.queue.length >= this.config.maxQueueSize)
+            this.evictChain();
+        this.queuedCount++;
+        this.queue.push(item);
+        /**
+         * A KEYFRAME does not wait for the next tick.
+         *
+         * MEASURED on a live app: time from navigation to the first frame batch leaving the browser was
+         * 5920 / 5959 / 6007 ms across ten sessions — pinned to `flushIntervalMs` (5000), not to how
+         * long the snapshot took. The recorder had the keyframe within a few hundred ms; it then sat in
+         * this queue waiting for a timer. Any visitor who left inside that window lost the ENTIRE
+         * session's replay, because the keyframe is what makes every delta behind it playable.
+         *
+         * That is the shape of the production defect: of the sessions that arrived complete in every
+         * other lane with zero frames stored, 44% lasted 3-10s and 18% lasted 1-3s — i.e. they ended
+         * before the first flush tick. `pagehide` is the backstop, but it is not guaranteed to run (a
+         * backgrounded tab killed by mobile Safari never fires it), so relying on it is what left a
+         * measured 27% of sessions with no replay.
+         *
+         * Only keyframes. Deltas are small, frequent, and worthless without their base, so they keep
+         * batching normally — this costs one extra request per keyframe (~30s apart), not one per frame.
+         * `flush()` no-ops while a batch is already in flight, so a keyframe arriving mid-flush is
+         * picked up by the next drain rather than racing it.
+         *
+         * `this.started` is load-bearing, not defensive. Features install and emit before start() has
+         * run, and a fast-flush from there would race the very gate that protects it: measured, the
+         * keyframe batch left at +1768ms while session-create was issued at +1766ms and only answered at
+         * +1792ms — the flush had already begun against the pre-resolved default gate and the frames
+         * were dropped with a 200. start() sets `started` and assigns the gate in one synchronous block,
+         * so checking it here makes the ordering unconditional. A keyframe that arrives before start()
+         * is flushed by start() itself, once the gate exists.
+         */
+        if (this.started && isKeyframe(item)) {
+            // A flush already in flight would make flush() a no-op here, and the "next drain" is the 5s
+            // timer — which a bouncing visitor never reaches. Measured: the keyframe arrived while the
+            // first batch was mid-send, the fast path was skipped, and a 3s session stored nothing.
+            if (this.flushing)
+                this.keyframePending = true;
+            else
+                void this.flush();
+        }
+    }
+    /**
+     * Say that data was thrown away, on the one lane proven to work.
+     *
+     * A permanent rejection is real, unrecoverable data loss — an 8 MB keyframe or a closed entitlement
+     * will be refused identically forever, so the only correct action is to drop it. Dropping it
+     * SILENTLY is what made the `missing` replay bucket undiagnosable: replay produced nothing, and
+     * neither the client nor the server had anything to say about why. `dropped` alone cannot carry it
+     * either, since it already means "queue overflow".
+     *
+     * Same event name as the React Native SDK (`sdk_replay_capture_failed`), with platform-specific
+     * `reason` values, so one dashboard breakdown reads both platforms without a concept-map alias.
+     *
+     * Emitted through `emit()` on purpose: it inherits the durable queue, the consent gate and the
+     * batching that every other item gets. Latched to once per kind — see `reported`.
+     */
+    reportDrop(kind, reason) {
+        if (!kind)
+            return;
+        this.reported ?? (this.reported = new Set());
+        if (this.reported.has(kind))
+            return;
+        this.reported.add(kind);
+        this.emit({
+            kind: 'event',
+            name: 'sdk_replay_capture_failed',
+            timestamp: now(),
+            // `props`, NOT `properties`. The wire field is `props` — `mappers.ts` reads `data: it.props`,
+            // and `EventItemSchema` is `.passthrough()`, so an unknown key is carried to the mapper and
+            // then silently dropped with no error anywhere. Sending `properties` cost this event its
+            // entire payload: every `sdk_replay_capture_failed` landed with no stage, lane or reason —
+            // the one field the whole mechanism exists to deliver. `ack.test.ts` pins the key.
+            props: { stage: 'ingest-rejected', lane: kind, reason: reason ?? 'unknown' },
+        });
+    }
+    /** Persist the pending queue to IDB, trimmed to the byte budget (replay frames shed first so a
+     *  few large keyframes can't blow the IndexedDB quota). */
+    persistQueue() {
+        // Include the IN-FLIGHT batch. It has been spliced out of `queue` but isn't acknowledged yet, so a
+        // snapshot of `queue` alone silently drops it: on pagehide the in-flight (non-keepalive) fetch is
+        // cancelled with the page and the re-queue in flush() never runs — the batch existed nowhere.
+        const pending = this.inFlight.length ? [...this.inFlight, ...this.queue] : this.queue;
+        // Head slot = the session these items were CAPTURED in. buildEnvelope stamps the session at FLUSH
+        // time, so without this a queue recovered on a later visit is filed under whatever session is
+        // current then — measured: 32 frames captured in one session reappeared inside the next one,
+        // truncating the first replay and interleaving foreign seq numbers into the second.
+        void this.buffer.save([
+            this.session.sessionId,
+            capBytes(pending, isFrame, isKeyframe),
+        ]);
+    }
+    /** Auto (timer/reconnect-driven) flush: skip while offline or inside the backoff window so a
+     *  struggling/offline server isn't hit every tick. Explicit/keepalive flushes bypass this. */
+    autoFlush() {
+        if (this.dead || !isOnline() || !this.backoff.ready(now()))
+            return;
+        void this.drain();
+    }
+    /**
+     * Empty the queue, instead of taking one batch and waiting out the next tick.
+     *
+     * THE CEILING THIS REMOVES. `flush()` takes `maxBatchSize` items (50) and the timer fires every
+     * `flushIntervalMs` (5,000 ms), so sustained egress was pinned at TEN ITEMS PER SECOND. Capture
+     * runs above that on any active page — the DOM lane packages a frame every 100 ms, scroll and
+     * input flush every 100 ms, cursor moves every 300 ms, and clicks flush immediately. Production
+     * bears out the pressure: the current SDK records 40 frames per session at the median against the
+     * previous version's 13. A queue that fills faster than it drains reaches `maxQueueSize` and starts
+     * shedding, which is the upstream cause of most of the frame loss this lane exists to fix.
+     *
+     * Draining stops the moment the queue stops SHRINKING, so a failing or backing-off transport costs
+     * one attempt rather than a spin: `flush()` puts a failed batch back, the length does not fall, and
+     * the loop exits. `MAX_DRAIN_BATCHES` bounds the pathological case where items are emitted as fast
+     * as they are sent — the queue is capped at 1,000, so 20 batches empties a full one.
+     *
+     * NOT used for the unload path. Keepalive bodies share a single 64 KiB in-flight budget across the
+     * whole agent, so issuing several at once would fail them all; `persistAndFlush` still sends one.
+     */
+    async drain() {
+        for (let i = 0; i < MAX_DRAIN_BATCHES && this.queue.length; i++) {
+            const before = this.queue.length;
+            await this.flush();
+            if (this.queue.length >= before)
+                return; // no progress — the transport is refusing or backing off
+        }
+    }
+    /**
+     * Take as much of the queue as a KEEPALIVE request can actually carry.
+     *
+     * THE BUG THIS FIXES. The unload flush took `maxBatchSize` items like any other, and `httpClient`
+     * skips gzip on the keepalive path — on the stated grounds that "keepalive bodies are small". They
+     * are not: this is the same 50-item batch as a normal tick, replay keyframes included, sent as raw
+     * JSON. Fetch caps the total in-flight keepalive body at 64 KiB and returns a NETWORK ERROR past
+     * it, so an oversized unload flush did not truncate — it failed whole, and the tail of the session
+     * only ever arrived if the visitor came back in the same browser. That is the "the replay ends
+     * before the session does" report.
+     *
+     * Sizing by serialized bytes and stopping at the budget delivers what fits and leaves the rest in
+     * the queue, where `persistQueue()` — which pagehide already ran before calling us — has it safe
+     * for the next load. Partial delivery beats none.
+     *
+     * ALWAYS AT LEAST ONE ITEM, even one over budget on its own: a head item too large to fit would
+     * otherwise block the queue permanently, and sending it costs no more than the failure it replaces.
+     *
+     * Gzip is deliberately still not the answer here. `CompressionStream` is async, and awaiting it
+     * inside a pagehide handler races the document's teardown — the request would be built after the
+     * page is gone. A deterministic byte budget needs no such bet.
+     */
+    takeKeepalive() {
+        const out = [];
+        let bytes = 0;
+        while (this.queue.length && out.length < this.config.maxBatchSize) {
+            const size = approxItemBytes(this.queue[0]);
+            if (out.length && bytes + size > KEEPALIVE_BUDGET_B)
+                break;
+            bytes += size;
+            out.push(this.queue.shift());
+        }
+        return out;
+    }
+    /** Drain a batch. On failure, re-queue (front) + persist so nothing is lost, and widen the
+     *  backoff window; on success, collapse the window back to the base interval. */
+    async flush(opts) {
+        if (this.dead)
+            return; // discarded under consent denial — never send or persist
+        if (this.flushing)
+            return; // a batch is already in flight; its items are persisted, not lost
+        if (this.queue.length === 0)
+            return;
+        this.flushing = true;
+        const batch = opts?.keepalive ? this.takeKeepalive() : this.queue.splice(0, this.config.maxBatchSize);
+        this.inFlight = batch; // keep it reachable by persistQueue() until it's acknowledged
+        try {
+            // The server drops items for a session it has no row for, and answers 200 while doing it —
+            // so this await is what makes at-least-once actually hold for the first batch of a session.
+            await this.sessionStarted;
+            /**
+             * Re-arm a session that never got created, before spending the batch against a row the server
+             * does not have. Bounded — see `sessionRetries`.
+             *
+             * `this.started` is load-bearing. Before start() (and after stop()) `sessionStarted` is the
+             * pre-resolved default and `sessionOk` is false — which is not a failed session-create, it is
+             * "there is no session lane yet". Without this guard a flush from either state issues a
+             * session-create the caller never asked for, which is both wrong and exactly what the
+             * pre-resolved default exists to avoid.
+             */
+            if (this.started && !this.sessionOk && this.sessionRetries < MAX_SESSION_RETRIES) {
+                this.sessionRetries++;
+                this.armSession();
+                await this.sessionStarted;
+                /**
+                 * STILL no row: hold the batch back rather than spend it.
+                 *
+                 * The batch endpoint answers 200 for a session it has never heard of and drops every item in
+                 * the request. Those come back as `unknown_session`, which is retryable, so nothing is lost —
+                 * but the round trip is, and so is a slot in the drain loop. It is the largest rejection
+                 * reason in production by a wide margin: 13,385 items in one week, 1,711 of them frames.
+                 *
+                 * Bounded by the SAME retry budget that guards the re-arm above, so a server that will never
+                 * create the row cannot mute egress permanently — once the budget is spent, the batch goes
+                 * out on the old terms and takes its chances. Requeued at the HEAD because nothing else has
+                 * been sent ahead of it and order is still intact.
+                 */
+                if (!this.sessionOk) {
+                    this.queue.unshift(...batch);
+                    this.inFlight = [];
+                    this.backoff.fail(now());
+                    this.persistQueue(); // same durability as every other failure path
+                    return;
+                }
+            }
+            this.attemptedCount++;
+            /**
+             * DOM PAYLOADS GO STRAIGHT TO STORAGE, when the flag is on and this is not an unload.
+             *
+             * Measured on production: 154,235 of 163,644 frames stored in a 32h window are web DOM
+             * payloads that arrived inline HERE and were then PUT to object storage by the server, on
+             * the request path, at 25-70ms per round trip. Sending the bytes directly turns this
+             * envelope from a byte relay into a metadata post.
+             *
+             * ⚠ NEVER ON THE KEEPALIVE PATH. An unload flush races the document teardown, and this adds
+             * a presign round trip plus a PUT per frame before anything can be sent — the batch would
+             * lose the race and the tail of the session with it. `takeKeepalive` already exists because
+             * that boundary is unforgiving; frames leaving on pagehide go inline, as they always have.
+             *
+             * Lazily imported so the offload code stays out of the eager core, the same reason `gzip`
+             * is imported where it is used. Failure of any kind leaves every frame inline and sendable.
+             */
+            if (this.config.replayDirectUpload && !opts?.keepalive) {
+                try {
+                    const { offloadDomFrames } = await import('../features/replay/lifecycle/offloadDomFrames.js');
+                    await offloadDomFrames(batch, {
+                        sessionId: this.session.sessionId,
+                        presign: (sid, frames) => this.transport.presignFrames(sid, frames),
+                        put: (url, body, ct) => this.transport.putSigned(url, body, ct),
+                    });
+                }
+                catch {
+                    /* the offload is an optimisation; a batch must never fail because it could not run */
+                }
+            }
+            const ack = await this.transport.sendBatch(this.buildEnvelope(batch), opts);
+            if (ack) {
+                this.inFlight = [];
+                // ACKed = the server accepted these items. Set here and corrected below for the per-kind
+                // rejections, so `acked` counts what was STORED rather than what was merely 2xx'd — which is
+                // the distinction the whole per-kind receipt exists to draw.
+                this.ackedCount += batch.length;
+                /**
+                 * A 2xx is NOT proof the items were stored.
+                 *
+                 * The backend fans the envelope out by item kind and catches each kind's failures so one bad
+                 * kind cannot fail the whole batch — then answers 200 regardless. The per-kind verdict in
+                 * `results` is the real receipt, and until this read it, a rejected `frame` group was cleared
+                 * from the queue and from IndexedDB while the `event`/`performance` groups beside it landed:
+                 * the exact fingerprint of the `missing` replay bucket.
+                 *
+                 * `retry` distinguishes the two rejections that need opposite handling. An unknown session
+                 * becomes known as soon as `startSession` lands, so those items go back. An oversized payload
+                 * or a closed entitlement will be refused identically forever, so re-queueing it would loop
+                 * on the same bytes until the queue cap evicted something that WOULD have been accepted —
+                 * those are dropped and counted, so `dropped` stops meaning only "queue overflow".
+                 *
+                 * A kind absent from the map was stored. That is what makes this safe against a backend that
+                 * predates the field: no entries, nothing re-queued, behaviour identical to before.
+                 */
+                const back = [];
+                let dropped = 0;
+                for (const it of batch) {
+                    const kind = it.kind ?? '';
+                    const r = ack[kind];
+                    if (!r || r.ok)
+                        continue;
+                    this.ackedCount--; // provisionally counted above; this kind was NOT stored
+                    if (r.retry) {
+                        back.push(it);
+                        this.retriedCount++;
+                    }
+                    else {
+                        dropped++;
+                        this.droppedCount++;
+                        this.reportDrop(kind, r.reason);
+                    }
+                }
+                /**
+                 * HOW A RETRYABLE REJECTION IS RE-QUEUED — and why it is not simply `unshift`.
+                 *
+                 * `unshift` + an unconditional `backoff.reset()` was an infinite loop that starved every
+                 * other lane. A session whose row was never created rejects EVERY kind as retryable, so
+                 * `back` came back the full width of the batch, went to the HEAD, and `flush()` — which
+                 * takes `splice(0, maxBatchSize)` — selected exactly the same items on the next tick. The
+                 * backoff had just been reset because the response was a 2xx, so there was no widening
+                 * window either: the same 50 items re-POSTed every flush interval, forever, while items
+                 * emitted behind them sat at the tail and were eventually evicted by the queue cap.
+                 *
+                 * So the branch turns on whether ANYTHING landed:
+                 *  - Something landed → the server is working and this is an ordinary partial retry. Reset
+                 *    the window and put the items back at the head, where they keep their place in line.
+                 *  - Nothing landed → a 2xx that stored none of the batch is a FAILURE for our purposes,
+                 *    whatever the status code said. Widen the retry window like any other failure, and
+                 *    re-queue at the TAIL so a lane that cannot land stops holding the head hostage. The
+                 *    items are not lost — they are behind the other lanes instead of in front of them.
+                 *
+                 * Frame order survives the tail move: the backend orders frames by `sequenceNumber`, not by
+                 * arrival, and these items keep their relative order among themselves.
+                 */
+                if (back.length) {
+                    if (batch.length - back.length - dropped === 0) {
+                        this.backoff.fail(now());
+                        this.queue.push(...back);
+                    }
+                    else {
+                        this.backoff.reset();
+                        this.queue.unshift(...back);
+                    }
+                    this.persistQueue();
+                }
+                else {
+                    this.backoff.reset();
+                }
+            }
+            else {
+                // The request itself failed (offline, 5xx, abort). Nothing was stored, so nothing is ACKed;
+                // the whole batch goes back and counts as retried.
+                this.backoff.fail(now());
+                this.retriedCount += batch.length;
+                this.queue.unshift(...batch);
+                this.inFlight = []; // back in `queue` — persistQueue() sees it there now
+                this.persistQueue();
+            }
+        }
+        catch {
+            // A throwing transport must not swallow the batch (and must not throw into the host: every
+            // caller invokes flush() as `void flush()`, so a rejection would surface as an unhandled one).
+            this.backoff.fail(now());
+            this.retriedCount += batch.length;
+            this.queue.unshift(...batch);
+            this.inFlight = [];
+            this.persistQueue();
+        }
+        finally {
+            this.flushing = false;
+        }
+        // A keyframe that asked for the fast path mid-flush gets it now, rather than waiting out the
+        // flush interval. Cleared before recursing, so this drains once per keyframe, not in a loop.
+        if (this.keyframePending) {
+            this.keyframePending = false;
+            void this.flush(opts);
+        }
+    }
+    /**
+     * Ship a queue recovered from a PREVIOUS session under that session's own id.
+     *
+     * The transport derives the URL from `envelope.sessionId`, so overriding it is all that is needed
+     * to file the frames where they belong. Sent in its own envelope rather than merged into the
+     * current queue, because a batch may only describe one session.
+     *
+     * On failure the items are written back for one more attempt. That retry window lasts until this
+     * page's own `persistQueue()` overwrites the slot (its first page-hide or failed flush) — a single
+     * buffer entry cannot hold two sessions, and giving orphans their own key is not worth the eager
+     * bytes. Re-persisting under the ORIGINAL id, rather than folding them into the live queue, is the
+     * deliberate call: losing a few frames from a session the user already left beats interleaving
+     * foreign seq numbers into the replay of the session they are in right now.
+     */
+    /**
+     * File a single item against another session — the same orphan lane, for a signal rather than a
+     * recovered queue. Used by crash recovery to report a dead session's death ON that session
+     * instead of on the live one. Fire-and-forget: it must never block the current session's setup.
+     */
+    emitFor(sid, item) {
+        if (!this.consentGranted || !sid || sid === this.session.sessionId) {
+            // No session to redirect to (or consent withheld) — the caller's own fallback decides.
+            if (this.consentGranted && sid === this.session.sessionId)
+                this.emit(item);
+            return;
+        }
+        void this.drainOrphans(sid, [item]);
+    }
+    /**
+     * Ship a recovered queue under the session it belongs to — IN BATCHES, not as one envelope.
+     *
+     * THE BUG THIS FIXES. This sent `items` whole, and `items` here is a queue recovered from a
+     * previous page load: up to `maxQueueSize`, a thousand items. The frame endpoint accepts 100 per
+     * request and answers `batch_too_large` past that, which the backend deliberately classifies as
+     * RETRYABLE — "the right data in a request that was too big", to be split and resent. Nothing
+     * implemented the split, so the identical oversized envelope went back to the buffer and returned
+     * on the next load to fail the same way. Measured in production over one week: 232 frame items
+     * across 2 sessions, rejected exactly this way.
+     *
+     * Chunking at `maxBatchSize` makes the split unnecessary rather than merely handled — the request
+     * is never oversized in the first place. Sequential, because these are a dead session's tail and
+     * have no claim on the live session's bandwidth.
+     *
+     * Everything not taken accumulates and is saved ONCE at the end: the orphan buffer is a single
+     * slot, so a save per chunk would leave only the last chunk's leftovers in it.
+     */
+    async drainOrphans(sid, items) {
+        const keep = [];
+        for (let i = 0; i < items.length; i += this.config.maxBatchSize) {
+            const chunk = items.slice(i, i + this.config.maxBatchSize);
+            let ack = null;
+            try {
+                ack = await this.transport.sendBatch({ ...this.buildEnvelope(chunk), sessionId: sid });
+            }
+            catch {
+                /* treated as a failure */
+            }
+            /**
+             * Re-persist unless the server took it, applying the SAME per-kind rule as flush(): a permanent
+             * rejection is not worth another attempt, and re-saving it here would hold the single buffer
+             * slot against a payload that can never land. `null` (request failed) still re-saves the chunk.
+             */
+            if (!ack) {
+                // The request itself failed, so the chunks BEHIND this one were never attempted either —
+                // keeping only the current chunk would silently discard them. Take the whole remaining tail
+                // and stop; the next page load will try again.
+                keep.push(...items.slice(i));
+                break;
+            }
+            for (const it of chunk) {
+                const r = ack[it.kind ?? ''];
+                if (r && !r.ok && r.retry)
+                    keep.push(it);
+            }
+        }
+        if (keep.length)
+            void this.buffer.save([sid, keep]);
+    }
+    buildEnvelope(items) {
+        return {
+            schemaVersion: SCHEMA_VERSION,
+            sessionId: this.session.sessionId,
+            sentAt: now(),
+            client: this.session.client(),
+            device: this.session.device(),
+            app: this.session.app(),
+            context: this.session.context(),
+            items,
+        };
+    }
+    installLifecycleFlush() {
+        if (typeof document === 'undefined')
+            return;
+        const persistAndFlush = () => {
+            if (this.dead)
+                return; // denied → don't re-persist
+            this.persistQueue();
+            void this.flush({ keepalive: true });
+        };
+        const onHide = () => {
+            if (document.visibilityState === 'hidden')
+                persistAndFlush();
+        };
+        this.addLifecycle(document, 'visibilitychange', onHide);
+        if (typeof window !== 'undefined') {
+            // pagehide covers bfcache eviction / unload more reliably than 'unload'.
+            this.addLifecycle(window, 'pagehide', persistAndFlush);
+            // On reconnect: clear the backoff window and flush immediately (don't wait for the next tick).
+            this.addLifecycle(window, 'online', () => {
+                this.backoff.reset();
+                this.autoFlush();
+            });
+        }
+    }
+    addLifecycle(target, type, fn) {
+        target.addEventListener(type, fn);
+        this.lifecycle.push({ target, type, fn });
+    }
+    removeLifecycle() {
+        for (const l of this.lifecycle) {
+            try {
+                l.target.removeEventListener(l.type, l.fn);
+            }
+            catch {
+                /* ignore */
+            }
+        }
+        this.lifecycle = [];
+    }
+    async stop() {
+        if (this.timer)
+            clearInterval(this.timer);
+        this.timer = null;
+        this.removeLifecycle();
+        await this.flush({ keepalive: true });
+        await this.transport.finalize(this.session.sessionId);
+        await this.buffer.clear();
+        this.started = false;
+    }
+    /**
+     * Drop everything without sending — for consent denial. Stops the flush loop, discards the
+     * in-memory queue, and purges the persisted buffer (including any data from a prior load). Unlike
+     * stop(), it never flushes or finalizes (no network), so nothing leaves the browser.
+     */
+    async discard() {
+        this.dead = true; // set FIRST so any racing flush()/pagehide save() no-ops
+        this.consentGranted = false;
+        if (this.timer)
+            clearInterval(this.timer);
+        this.timer = null;
+        this.removeLifecycle();
+        this.queue = [];
+        this.started = false;
+        try {
+            await this.buffer.clear();
+        }
+        catch {
+            /* ignore */
+        }
+    }
+    get pendingCount() {
+        return this.queue.length;
+    }
+    get dropped() {
+        return this.droppedCount;
+    }
+    /**
+     * P6 — the full egress ledger, for `ScaleBun.egressStats()`.
+     *
+     * Exposed as one object rather than seven getters so a caller reads a CONSISTENT snapshot: the
+     * counters move on network callbacks, and seven separate reads could straddle a flush and produce a
+     * set that never actually existed.
+     */
+    get ledger() {
+        return {
+            queued: this.queuedCount,
+            attempted: this.attemptedCount,
+            retried: this.retriedCount,
+            recovered: this.recoveredCount,
+            dropped: this.droppedCount,
+            expired: this.expiredCount,
+            acked: this.ackedCount,
+        };
+    }
+}
+//# sourceMappingURL=pipeline.js.map