@memberjunction/realtime-runtime 6.2.0-edge.3 → 6.2.0-edge.5

package/dist/session/RecordingShardQueue.d.ts

@@ -0,0 +1,94 @@
+/**
+ * @fileoverview Retry queue for indexed recording shards.
+ *
+ * The recorder cuts the call's Opus stream into already-indexed `MJOPUS1` shards (see
+ * {@link RecordingShardWindow}) and each one is uploaded as it seals. Before this queue a failed
+ * upload was never retried, so a single transient error left a permanent gap in the recovered
+ * recording (#5197). The queue keeps failed shards and resends them, oldest first, on later
+ * flushes — bounded so a dead server cannot grow memory without limit. A shard the queue gives up on
+ * is not lost: it stays in the IndexedDB store, and the owner is told so it can re-send it from there
+ * once uploads succeed again (or a later load drains it).
+ *
+ * @module @memberjunction/realtime-runtime
+ */
+import type { RecordingShard } from './RecordingShardWindow.js';
+/** Resolves true when the server stored the shard; false or a throw are both failures. */
+export type ShardUpload = (shard: RecordingShard) => Promise<boolean>;
+/**
+ * Told about shards the queue stops retrying while the recording is live (attempts used up, or the
+ * retry list overflowed). They are still in the store; the owner re-sends them once uploads work.
+ */
+export type ShardsGivenUp = (shards: RecordingShard[]) => void;
+/** Total upload attempts per shard (the first try plus retries) before it is dropped. */
+export declare const MAX_SHARD_UPLOAD_ATTEMPTS = 3;
+/**
+ * Flushes allowed in flight at once. Flushes are ~5 s apart, so overlap only happens when an upload
+ * is slower than a tick; an unbounded pile-up on a dead network would start a new batch of uploads
+ * every tick. A flush that arrives at capacity does not upload, but it does not lose its shards
+ * either: they are retained and the next flush that has a free slot sends them, oldest first.
+ */
+export declare const MAX_CONCURRENT_FLUSHES = 2;
+/**
+ * Per-attempt upload deadline. A hung request would otherwise pin one of the
+ * {@link MAX_CONCURRENT_FLUSHES} slots forever and silently stop all later shards. A timeout counts
+ * as a failed attempt; if the request later succeeds anyway that is harmless, because the server
+ * key is per-index and a resend of the same bytes is an idempotent overwrite. The timeout is
+ * logical only: the transport may accept no AbortSignal, so a timed-out request may still be on the
+ * wire. Requests stay rate-bounded regardless (at most {@link MAX_CONCURRENT_FLUSHES} flushes, each
+ * sending at most one batch, per timeout window).
+ */
+export declare const SHARD_UPLOAD_TIMEOUT_MS = 60000;
+/**
+ * Cap on shards held for retry: 10 minutes of 5 s shards. A dead network with flushes at capacity
+ * would otherwise grow the retained list (and its bytes) without bound. Overflow drops the oldest;
+ * dropped shards remain in the IndexedDB store for the next-load drain.
+ */
+export declare const MAX_RETAINED_SHARDS = 120;
+/**
+ * Uploads indexed shards and retains failures for retry on later flushes. A retry keeps its shard's
+ * index and bytes. Safe to call {@link Flush} from an overlapping timer.
+ */
+export declare class RecordingShardQueue {
+    private readonly upload;
+    private readonly onGivenUp;
+    private retained;
+    /** Every shard handed to the queue and not yet acknowledged or given up on, by index. */
+    private readonly outstanding;
+    private inFlight;
+    /** True once a capacity stall has been logged; cleared when a flush actually runs. */
+    private capacityWarned;
+    /** Set by {@link Close} when the recording ends; nothing is sent or retained after it. */
+    private closed;
+    /**
+     * @param upload sends one shard
+     * @param onGivenUp told about every shard dropped while the recording is live (not on {@link Close})
+     */
+    constructor(upload: ShardUpload, onGivenUp?: ShardsGivenUp);
+    /** Shards awaiting a retry (for tests and diagnostics). */
+    get RetainedCount(): number;
+    /**
+     * Every shard the queue still holds without an acknowledgement — on the wire, waiting in a flush's
+     * batch, or retained for a retry — oldest first. A page that is about to unload re-sends these with
+     * `keepalive`, because its ordinary requests are aborted with it.
+     */
+    Unacknowledged(): RecordingShard[];
+    /**
+     * Uploads retained shards oldest-first, then `fresh`. A failure never stops the rest of the
+     * flush. At {@link MAX_CONCURRENT_FLUSHES} in flight nothing is uploaded and `fresh` is retained
+     * for the next flush instead. Never rejects.
+     */
+    Flush(fresh: RecordingShard[]): Promise<void>;
+    /**
+     * Ends the queue with its recording: discards retained shards and stops any flush in flight from
+     * sending more. An upload already on the wire cannot be aborted, so at most that one request can
+     * still land. Discarded shards remain in the IndexedDB store and are drained on a later load.
+     */
+    Close(): void;
+    /** Sorted re-insert: concurrent flushes can fail out of index order, and the oldest must go first. */
+    private retain;
+    /** Warns once per stall so a wedged uploader is visible without logging every tick. */
+    private warnCapacitySkip;
+    private uploadWithTimeout;
+    private send;
+}
+//# sourceMappingURL=RecordingShardQueue.d.ts.map

package/dist/session/RecordingShardQueue.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"RecordingShardQueue.d.ts","sourceRoot":"","sources":["../../src/session/RecordingShardQueue.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AACH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,wBAAwB,CAAC;AAE7D,0FAA0F;AAC1F,MAAM,MAAM,WAAW,GAAG,CAAC,KAAK,EAAE,cAAc,KAAK,OAAO,CAAC,OAAO,CAAC,CAAC;AAEtE;;;GAGG;AACH,MAAM,MAAM,aAAa,GAAG,CAAC,MAAM,EAAE,cAAc,EAAE,KAAK,IAAI,CAAC;AAE/D,yFAAyF;AACzF,eAAO,MAAM,yBAAyB,IAAI,CAAC;AAE3C;;;;;GAKG;AACH,eAAO,MAAM,sBAAsB,IAAI,CAAC;AAExC;;;;;;;;GAQG;AACH,eAAO,MAAM,uBAAuB,QAAS,CAAC;AAE9C;;;;GAIG;AACH,eAAO,MAAM,mBAAmB,MAAM,CAAC;AAYvC;;;GAGG;AACH,qBAAa,mBAAmB;IAclB,OAAO,CAAC,QAAQ,CAAC,MAAM;IAAe,OAAO,CAAC,QAAQ,CAAC,SAAS;IAb5E,OAAO,CAAC,QAAQ,CAAsB;IACtC,yFAAyF;IACzF,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAqC;IACjE,OAAO,CAAC,QAAQ,CAAK;IACrB,sFAAsF;IACtF,OAAO,CAAC,cAAc,CAAS;IAC/B,0FAA0F;IAC1F,OAAO,CAAC,MAAM,CAAS;IAEvB;;;OAGG;gBAC0B,MAAM,EAAE,WAAW,EAAmB,SAAS,GAAE,aAA+B;IAE7G,2DAA2D;IAC3D,IAAW,aAAa,IAAI,MAAM,CAEjC;IAED;;;;OAIG;IACI,cAAc,IAAI,cAAc,EAAE;IAIzC;;;;OAIG;IACU,KAAK,CAAC,KAAK,EAAE,cAAc,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC;IAqC1D;;;;OAIG;IACI,KAAK,IAAI,IAAI;IAMpB,sGAAsG;IACtG,OAAO,CAAC,MAAM;IAgBd,uFAAuF;IACvF,OAAO,CAAC,gBAAgB;YAUV,iBAAiB;YAYjB,IAAI;CAoCnB"}

package/dist/session/RecordingShardQueue.js

@@ -0,0 +1,176 @@
+/** Total upload attempts per shard (the first try plus retries) before it is dropped. */
+export const MAX_SHARD_UPLOAD_ATTEMPTS = 3;
+/**
+ * Flushes allowed in flight at once. Flushes are ~5 s apart, so overlap only happens when an upload
+ * is slower than a tick; an unbounded pile-up on a dead network would start a new batch of uploads
+ * every tick. A flush that arrives at capacity does not upload, but it does not lose its shards
+ * either: they are retained and the next flush that has a free slot sends them, oldest first.
+ */
+export const MAX_CONCURRENT_FLUSHES = 2;
+/**
+ * Per-attempt upload deadline. A hung request would otherwise pin one of the
+ * {@link MAX_CONCURRENT_FLUSHES} slots forever and silently stop all later shards. A timeout counts
+ * as a failed attempt; if the request later succeeds anyway that is harmless, because the server
+ * key is per-index and a resend of the same bytes is an idempotent overwrite. The timeout is
+ * logical only: the transport may accept no AbortSignal, so a timed-out request may still be on the
+ * wire. Requests stay rate-bounded regardless (at most {@link MAX_CONCURRENT_FLUSHES} flushes, each
+ * sending at most one batch, per timeout window).
+ */
+export const SHARD_UPLOAD_TIMEOUT_MS = 60_000;
+/**
+ * Cap on shards held for retry: 10 minutes of 5 s shards. A dead network with flushes at capacity
+ * would otherwise grow the retained list (and its bytes) without bound. Overflow drops the oldest;
+ * dropped shards remain in the IndexedDB store for the next-load drain.
+ */
+export const MAX_RETAINED_SHARDS = 120;
+/** One-line reason for a warn message; the raw value is still passed along for its stack. */
+function describeFailure(failure) {
+    return failure instanceof Error ? failure.message : String(failure);
+}
+/**
+ * Uploads indexed shards and retains failures for retry on later flushes. A retry keeps its shard's
+ * index and bytes. Safe to call {@link Flush} from an overlapping timer.
+ */
+export class RecordingShardQueue {
+    /**
+     * @param upload sends one shard
+     * @param onGivenUp told about every shard dropped while the recording is live (not on {@link Close})
+     */
+    constructor(upload, onGivenUp = () => undefined) {
+        this.upload = upload;
+        this.onGivenUp = onGivenUp;
+        this.retained = [];
+        /** Every shard handed to the queue and not yet acknowledged or given up on, by index. */
+        this.outstanding = new Map();
+        this.inFlight = 0;
+        /** True once a capacity stall has been logged; cleared when a flush actually runs. */
+        this.capacityWarned = false;
+        /** Set by {@link Close} when the recording ends; nothing is sent or retained after it. */
+        this.closed = false;
+    }
+    /** Shards awaiting a retry (for tests and diagnostics). */
+    get RetainedCount() {
+        return this.retained.length;
+    }
+    /**
+     * Every shard the queue still holds without an acknowledgement — on the wire, waiting in a flush's
+     * batch, or retained for a retry — oldest first. A page that is about to unload re-sends these with
+     * `keepalive`, because its ordinary requests are aborted with it.
+     */
+    Unacknowledged() {
+        return [...this.outstanding.values()].sort((a, b) => a.Index - b.Index);
+    }
+    /**
+     * Uploads retained shards oldest-first, then `fresh`. A failure never stops the rest of the
+     * flush. At {@link MAX_CONCURRENT_FLUSHES} in flight nothing is uploaded and `fresh` is retained
+     * for the next flush instead. Never rejects.
+     */
+    async Flush(fresh) {
+        if (this.closed) {
+            if (fresh.length > 0) {
+                console.warn(`[RealtimeSession] Recording flush after the recording ended; shard(s) ${fresh.map((s) => s.Index).join(', ')} not sent — they stay in the local store and are drained later.`);
+            }
+            return;
+        }
+        const freshPending = fresh.map((shard) => ({ Shard: shard, Attempts: 0 }));
+        for (const shard of fresh) {
+            this.outstanding.set(shard.Index, shard);
+        }
+        if (this.inFlight >= MAX_CONCURRENT_FLUSHES) {
+            this.retain(freshPending);
+            this.warnCapacitySkip();
+            return;
+        }
+        this.capacityWarned = false;
+        this.inFlight++;
+        try {
+            // Swap the array out so a concurrent flush only sees shards nobody is currently sending.
+            const batch = [...this.retained, ...freshPending].sort((a, b) => a.Shard.Index - b.Shard.Index);
+            this.retained = [];
+            for (const pending of batch) {
+                // Re-checked before every send: a flush running when the recording ends must not keep
+                // uploading shards the terminal request is about to supersede.
+                if (this.closed) {
+                    return;
+                }
+                await this.send(pending);
+            }
+        }
+        finally {
+            this.inFlight--;
+        }
+    }
+    /**
+     * Ends the queue with its recording: discards retained shards and stops any flush in flight from
+     * sending more. An upload already on the wire cannot be aborted, so at most that one request can
+     * still land. Discarded shards remain in the IndexedDB store and are drained on a later load.
+     */
+    Close() {
+        this.closed = true;
+        this.retained = [];
+        this.outstanding.clear();
+    }
+    /** Sorted re-insert: concurrent flushes can fail out of index order, and the oldest must go first. */
+    retain(pending) {
+        this.retained.push(...pending);
+        this.retained.sort((a, b) => a.Shard.Index - b.Shard.Index);
+        const overflow = this.retained.length - MAX_RETAINED_SHARDS;
+        if (overflow > 0) {
+            const dropped = this.retained.splice(0, overflow);
+            for (const pending of dropped) {
+                this.outstanding.delete(pending.Shard.Index);
+            }
+            console.warn(`[RealtimeSession] Retry queue over ${MAX_RETAINED_SHARDS} shards; dropped oldest shard(s) ${dropped.map((p) => p.Shard.Index).join(', ')} from memory — they stay in the local IndexedDB store and are re-sent from it once uploads succeed again.`);
+            this.onGivenUp(dropped.map((p) => p.Shard));
+        }
+    }
+    /** Warns once per stall so a wedged uploader is visible without logging every tick. */
+    warnCapacitySkip() {
+        if (this.capacityWarned) {
+            return;
+        }
+        this.capacityWarned = true;
+        console.warn(`[RealtimeSession] Recording flush at capacity: ${this.inFlight}/${MAX_CONCURRENT_FLUSHES} flushes in flight, ${this.retained.length} shard(s) retained. Retained shards are sent by the next flush with a free slot.`);
+    }
+    async uploadWithTimeout(shard) {
+        let timer;
+        const deadline = new Promise((_, reject) => {
+            timer = setTimeout(() => reject(new Error(`upload timed out after ${SHARD_UPLOAD_TIMEOUT_MS}ms`)), SHARD_UPLOAD_TIMEOUT_MS);
+        });
+        try {
+            return await Promise.race([this.upload(shard), deadline]);
+        }
+        finally {
+            clearTimeout(timer);
+        }
+    }
+    async send(pending) {
+        const { Shard: shard } = pending;
+        pending.Attempts++;
+        let stored = false;
+        let failure = 'server refused the shard';
+        try {
+            stored = await this.uploadWithTimeout(shard);
+        }
+        catch (error) {
+            failure = error;
+        }
+        if (stored) {
+            this.outstanding.delete(shard.Index);
+            return;
+        }
+        if (this.closed) {
+            console.warn(`[RealtimeSession] Recording shard ${shard.Index} upload failed after the recording ended (${describeFailure(failure)}); not retried — it stays in the local store and is drained later:`, failure);
+            return;
+        }
+        if (pending.Attempts >= MAX_SHARD_UPLOAD_ATTEMPTS) {
+            console.warn(`[RealtimeSession] Dropping recording shard ${shard.Index} from the retry queue after ${pending.Attempts}/${MAX_SHARD_UPLOAD_ATTEMPTS} failed uploads (${describeFailure(failure)}); it stays in the local store and is re-sent from it once uploads succeed again:`, failure);
+            this.outstanding.delete(shard.Index);
+            this.onGivenUp([shard]);
+            return;
+        }
+        console.warn(`[RealtimeSession] Recording shard ${shard.Index} upload failed (attempt ${pending.Attempts}/${MAX_SHARD_UPLOAD_ATTEMPTS}: ${describeFailure(failure)}); will retry next flush:`, failure);
+        this.retain([pending]);
+    }
+}
+//# sourceMappingURL=RecordingShardQueue.js.map

package/dist/session/RecordingShardQueue.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"RecordingShardQueue.js","sourceRoot":"","sources":["../../src/session/RecordingShardQueue.ts"],"names":[],"mappings":"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"}

package/dist/session/RecordingShardStore.d.ts

@@ -0,0 +1,57 @@
+/**
+ * @fileoverview Durable queue for realtime-call recording shards, backed by IndexedDB.
+ *
+ * A shard is written here BEFORE its upload starts and deleted only once the server acknowledges
+ * it, so a crash, a closed tab or a dead network never loses audio that was already captured: the
+ * next page load drains whatever is left. Persistence is best-effort by design — every failure is
+ * logged with the session and shard index and then swallowed into a resolved promise, because a
+ * broken disk must never interrupt a live call.
+ *
+ * @module @memberjunction/realtime-runtime
+ */
+/** A shard waiting in the store for the server to acknowledge it. */
+export interface PendingRecordingShard {
+    SessionID: string;
+    /**
+     * The MJ user whose call this is, or null when the page had no signed-in user. A page only lists
+     * (and so re-sends) its own user's shards, and logout deletes them: on a shared browser one user's
+     * audio is never sent with, or left behind for, another user's session.
+     */
+    UserID: string | null;
+    Index: number;
+    Bytes: Uint8Array;
+    /** Epoch ms at which the shard was stored; drives oldest-first draining and retention. */
+    SavedAt: number;
+}
+/**
+ * Durable shard queue. No method throws: a storage failure is logged and the call resolves (empty
+ * for {@link IRecordingShardStore.ListOldest}).
+ */
+export interface IRecordingShardStore {
+    /** Persists a shard (idempotent per session+index). */
+    Put(shard: PendingRecordingShard): Promise<void>;
+    /** Removes a shard once the server has acknowledged it. */
+    Delete(sessionID: string, index: number): Promise<void>;
+    /** Purges entries past retention (every user's), then returns up to `limit` of `userID`'s shards, oldest first. */
+    ListOldest(limit: number, userID: string | null): Promise<PendingRecordingShard[]>;
+    /** Removes every shard of `userID` (logout). */
+    DeleteForUser(userID: string | null): Promise<void>;
+}
+/** How long an unacknowledged shard is kept; the server stops accepting late shards well before this. */
+export declare const RECORDING_SHARD_RETENTION_MS: number;
+/** Store used when the host has no IndexedDB (server-side render, some React Native runtimes). */
+export declare class NullRecordingShardStore implements IRecordingShardStore {
+    Put(_shard: PendingRecordingShard): Promise<void>;
+    Delete(_sessionID: string, _index: number): Promise<void>;
+    ListOldest(_limit: number, _userID: string | null): Promise<PendingRecordingShard[]>;
+    DeleteForUser(_userID: string | null): Promise<void>;
+}
+/**
+ * Creates the shard store for a host. A host without IndexedDB passes `null`/`undefined` and gets a
+ * no-op store, so callers never branch on availability.
+ *
+ * @param factory The host's `indexedDB`, or null/undefined when it has none.
+ * @param now Injectable clock for the retention purge; defaults to `Date.now`.
+ */
+export declare function CreateRecordingShardStore(factory: IDBFactory | null | undefined, now?: () => number): IRecordingShardStore;
+//# sourceMappingURL=RecordingShardStore.d.ts.map

package/dist/session/RecordingShardStore.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"RecordingShardStore.d.ts","sourceRoot":"","sources":["../../src/session/RecordingShardStore.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,qEAAqE;AACrE,MAAM,WAAW,qBAAqB;IAClC,SAAS,EAAE,MAAM,CAAC;IAClB;;;;OAIG;IACH,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;IACtB,KAAK,EAAE,MAAM,CAAC;IACd,KAAK,EAAE,UAAU,CAAC;IAClB,0FAA0F;IAC1F,OAAO,EAAE,MAAM,CAAC;CACnB;AAED;;;GAGG;AACH,MAAM,WAAW,oBAAoB;IACjC,uDAAuD;IACvD,GAAG,CAAC,KAAK,EAAE,qBAAqB,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACjD,2DAA2D;IAC3D,MAAM,CAAC,SAAS,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACxD,mHAAmH;IACnH,UAAU,CAAC,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,IAAI,GAAG,OAAO,CAAC,qBAAqB,EAAE,CAAC,CAAC;IACnF,gDAAgD;IAChD,aAAa,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CACvD;AAED,yGAAyG;AACzG,eAAO,MAAM,4BAA4B,QAAoB,CAAC;AAmB9D,kGAAkG;AAClG,qBAAa,uBAAwB,YAAW,oBAAoB;IACnD,GAAG,CAAC,MAAM,EAAE,qBAAqB,GAAG,OAAO,CAAC,IAAI,CAAC;IAGjD,MAAM,CAAC,UAAU,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAGzD,UAAU,CAAC,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,IAAI,GAAG,OAAO,CAAC,qBAAqB,EAAE,CAAC;IAGpF,aAAa,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC;CAGpE;AAsJD;;;;;;GAMG;AACH,wBAAgB,yBAAyB,CACrC,OAAO,EAAE,UAAU,GAAG,IAAI,GAAG,SAAS,EACtC,GAAG,GAAE,MAAM,MAAiB,GAC7B,oBAAoB,CAEtB"}

package/dist/session/RecordingShardStore.js

@@ -0,0 +1,184 @@
+/**
+ * @fileoverview Durable queue for realtime-call recording shards, backed by IndexedDB.
+ *
+ * A shard is written here BEFORE its upload starts and deleted only once the server acknowledges
+ * it, so a crash, a closed tab or a dead network never loses audio that was already captured: the
+ * next page load drains whatever is left. Persistence is best-effort by design — every failure is
+ * logged with the session and shard index and then swallowed into a resolved promise, because a
+ * broken disk must never interrupt a live call.
+ *
+ * @module @memberjunction/realtime-runtime
+ */
+/** How long an unacknowledged shard is kept; the server stops accepting late shards well before this. */
+export const RECORDING_SHARD_RETENTION_MS = 7 * 24 * 3600_000;
+const DB_NAME = 'mj-realtime-recording';
+const DB_VERSION = 1;
+const STORE_NAME = 'pending-shards';
+const SAVED_AT_INDEX = 'by-saved-at';
+/** Initial open plus one retry; a persistently failing open then degrades to no-ops. */
+const MAX_OPEN_ATTEMPTS = 2;
+/** Store used when the host has no IndexedDB (server-side render, some React Native runtimes). */
+export class NullRecordingShardStore {
+    async Put(_shard) {
+        // Intentionally empty: without IndexedDB the in-memory retry queue is the only buffer.
+    }
+    async Delete(_sessionID, _index) {
+        // Intentionally empty.
+    }
+    async ListOldest(_limit, _userID) {
+        return [];
+    }
+    async DeleteForUser(_userID) {
+        // Intentionally empty.
+    }
+}
+function describeFailure(failure) {
+    return failure instanceof Error ? failure.message : String(failure);
+}
+function toTransactionPromise(tx) {
+    return new Promise((resolve, reject) => {
+        tx.oncomplete = () => resolve();
+        tx.onerror = () => reject(tx.error ?? new Error('IndexedDB transaction failed'));
+        tx.onabort = () => reject(tx.error ?? new Error('IndexedDB transaction aborted'));
+    });
+}
+class IndexedDBRecordingShardStore {
+    constructor(factory, now) {
+        this.factory = factory;
+        this.now = now;
+        this.db = null;
+        this.opening = null;
+        this.openAttempts = 0;
+        this.disabled = false;
+    }
+    async Put(shard) {
+        const context = `shard ${shard.SessionID}/${shard.Index}`;
+        const row = {
+            SessionID: shard.SessionID,
+            UserID: shard.UserID,
+            Index: shard.Index,
+            Buffer: shard.Bytes.slice().buffer,
+            SavedAt: shard.SavedAt,
+        };
+        await this.run(context, 'readwrite', (store) => {
+            store.put(row);
+        });
+    }
+    async Delete(sessionID, index) {
+        await this.run(`shard ${sessionID}/${index}`, 'readwrite', (store) => {
+            store.delete([sessionID, index]);
+        });
+    }
+    async ListOldest(limit, userID) {
+        const rows = [];
+        const cutoff = this.now() - RECORDING_SHARD_RETENTION_MS;
+        await this.run('listing pending shards', 'readwrite', (store) => {
+            // One ascending walk does both jobs: rows are ordered by age, so every expired row
+            // precedes every live one. Purge and read share a transaction so a shard cannot expire
+            // between the two steps. (Avoids IDBKeyRange, which is not a global in every host.)
+            store.index(SAVED_AT_INDEX).openCursor().onsuccess = (event) => {
+                const cursor = event.target.result;
+                if (!cursor)
+                    return;
+                const row = cursor.value;
+                if (row.SavedAt < cutoff) {
+                    cursor.delete();
+                }
+                else if ((row.UserID ?? null) !== userID) {
+                    // another user's shard: neither listed nor counted against this page's limit
+                }
+                else if (rows.length < limit) {
+                    rows.push(row);
+                }
+                else {
+                    return;
+                }
+                cursor.continue();
+            };
+        });
+        return rows.map((r) => ({
+            SessionID: r.SessionID,
+            UserID: r.UserID ?? null,
+            Index: r.Index,
+            Bytes: new Uint8Array(r.Buffer),
+            SavedAt: r.SavedAt,
+        }));
+    }
+    async DeleteForUser(userID) {
+        await this.run(`deleting the stored shards of user ${userID ?? '(none)'}`, 'readwrite', (store) => {
+            store.openCursor().onsuccess = (event) => {
+                const cursor = event.target.result;
+                if (!cursor)
+                    return;
+                if ((cursor.value.UserID ?? null) === userID) {
+                    cursor.delete();
+                }
+                cursor.continue();
+            };
+        });
+    }
+    /** Runs one transaction; any failure is logged with `context` and swallowed. */
+    async run(context, mode, work) {
+        const db = await this.getDatabase(context);
+        if (!db)
+            return;
+        try {
+            const tx = db.transaction(STORE_NAME, mode);
+            const done = toTransactionPromise(tx);
+            work(tx.objectStore(STORE_NAME));
+            await done;
+        }
+        catch (failure) {
+            console.warn(`[RealtimeSession] Recording shard store failed (${context}): ${describeFailure(failure)}`, failure);
+        }
+    }
+    async getDatabase(context) {
+        if (this.db)
+            return this.db;
+        if (this.disabled)
+            return null;
+        // Concurrent callers share the in-flight open instead of each counting as an attempt.
+        this.opening ??= this.open(context).finally(() => {
+            this.opening = null;
+        });
+        return this.opening;
+    }
+    async open(context) {
+        this.openAttempts++;
+        try {
+            this.db = await this.openDatabase();
+            return this.db;
+        }
+        catch (failure) {
+            console.warn(`[RealtimeSession] Recording shard store could not open IndexedDB (${context}, attempt ${this.openAttempts}/${MAX_OPEN_ATTEMPTS}): ${describeFailure(failure)}`, failure);
+            if (this.openAttempts >= MAX_OPEN_ATTEMPTS) {
+                this.disabled = true;
+                console.warn('[RealtimeSession] Recording shard persistence disabled for this page; shards stay in memory only.');
+            }
+            return null;
+        }
+    }
+    openDatabase() {
+        return new Promise((resolve, reject) => {
+            const request = this.factory.open(DB_NAME, DB_VERSION);
+            request.onupgradeneeded = () => {
+                const store = request.result.createObjectStore(STORE_NAME, { keyPath: ['SessionID', 'Index'] });
+                store.createIndex(SAVED_AT_INDEX, 'SavedAt');
+            };
+            request.onsuccess = () => resolve(request.result);
+            request.onerror = () => reject(request.error ?? new Error('IndexedDB open failed'));
+            request.onblocked = () => reject(new Error('IndexedDB open blocked'));
+        });
+    }
+}
+/**
+ * Creates the shard store for a host. A host without IndexedDB passes `null`/`undefined` and gets a
+ * no-op store, so callers never branch on availability.
+ *
+ * @param factory The host's `indexedDB`, or null/undefined when it has none.
+ * @param now Injectable clock for the retention purge; defaults to `Date.now`.
+ */
+export function CreateRecordingShardStore(factory, now = Date.now) {
+    return factory ? new IndexedDBRecordingShardStore(factory, now) : new NullRecordingShardStore();
+}
+//# sourceMappingURL=RecordingShardStore.js.map

package/dist/session/RecordingShardStore.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"RecordingShardStore.js","sourceRoot":"","sources":["../../src/session/RecordingShardStore.ts"],"names":[],"mappings":"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"}

package/dist/session/RecordingShardWindow.d.ts

@@ -0,0 +1,42 @@
+/** One sealed, encoded shard ready to store and upload. */
+export interface RecordingShard {
+    /** Zero-based, contiguous position in the call's shard sequence. */
+    Index: number;
+    /** 48 kHz sample offset of the shard's first frame. */
+    StartSample: number;
+    /** Audio samples the shard covers. */
+    SampleCount: number;
+    /** The encoded `MJOPUS1` bytes. */
+    Bytes: Uint8Array;
+}
+/**
+ * Accumulates Opus packets and seals them into shards. Pure: no timers, no I/O.
+ *
+ * A window seals when it reaches {@link RECORDING_SHARD_MAX_PACKETS} packets (two 5 s windows), or
+ * just BEFORE a packet that would push the encoded shard past {@link RECORDING_TERMINAL_MAX_BYTES}.
+ * The runtime's 5 s tick seals whatever is pending, so a live call still cuts one ~5 s shard per tick;
+ * the packet cap only splits a backlog (a throttled tab's batch). The byte cap guarantees that
+ * whatever tail is pending always fits the terminal request body, even after a VBR spike.
+ */
+export declare class RecordingShardWindow {
+    private pending;
+    private pendingBytes;
+    private nextIndex;
+    private sealedSamples;
+    /** Index of the last sealed shard; -1 before any seal. */
+    get LastSealedIndex(): number;
+    /** End sample of the last sealed shard. */
+    get SealedSamples(): number;
+    /** End sample of everything appended so far, sealed or pending. */
+    get PendingSamples(): number;
+    /** Adds packets in capture order and returns every shard that sealed as a result. */
+    Append(packets: Uint8Array[]): RecordingShard[];
+    /**
+     * Seals the partial window now. `sampleCount` (default packets*960) is clamped to
+     * [0, packets*960]; the caller passes less when the encoder's last frame was padded. Returns null
+     * when no packets are pending, so a second call is a no-op.
+     */
+    SealTail(sampleCount?: number): RecordingShard | null;
+    private seal;
+}
+//# sourceMappingURL=RecordingShardWindow.d.ts.map

package/dist/session/RecordingShardWindow.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"RecordingShardWindow.d.ts","sourceRoot":"","sources":["../../src/session/RecordingShardWindow.ts"],"names":[],"mappings":"AAkBA,2DAA2D;AAC3D,MAAM,WAAW,cAAc;IAC7B,oEAAoE;IACpE,KAAK,EAAE,MAAM,CAAC;IACd,uDAAuD;IACvD,WAAW,EAAE,MAAM,CAAC;IACpB,sCAAsC;IACtC,WAAW,EAAE,MAAM,CAAC;IACpB,mCAAmC;IACnC,KAAK,EAAE,UAAU,CAAC;CACnB;AAED;;;;;;;;GAQG;AACH,qBAAa,oBAAoB;IAC/B,OAAO,CAAC,OAAO,CAAoB;IACnC,OAAO,CAAC,YAAY,CAAgC;IACpD,OAAO,CAAC,SAAS,CAAK;IACtB,OAAO,CAAC,aAAa,CAAK;IAE1B,0DAA0D;IAC1D,IAAW,eAAe,IAAI,MAAM,CAEnC;IAED,2CAA2C;IAC3C,IAAW,aAAa,IAAI,MAAM,CAEjC;IAED,mEAAmE;IACnE,IAAW,cAAc,IAAI,MAAM,CAElC;IAED,qFAAqF;IAC9E,MAAM,CAAC,OAAO,EAAE,UAAU,EAAE,GAAG,cAAc,EAAE;IAgBtD;;;;OAIG;IACI,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,GAAG,cAAc,GAAG,IAAI;IAS5D,OAAO,CAAC,IAAI;CAmBb"}