@scalebun/react-native 1.0.2 → 1.0.3

package/src/pipeline/queue/persistentQueue.ts

@@ -1,414 +1,414 @@
-/**
- * ScaleBun SDK — Disk-Backed Persistent Queue
- *
- * Persists event envelopes to a StorageBackend so they survive
- * app restarts, crashes, and force-kills.
- *
- * STORAGE LAYOUT (chunked keys):
- *   scalebun_q:meta        → { head, tail, count, totalBytes }
- *   scalebun_q:e:{seq}     → JSON-serialized envelope
- *
- * Each envelope gets its own key. This makes add() O(1) and
- * popBatch() O(batch_size) instead of the old O(queue_size)
- * approach of serializing the entire array on every write.
- *
- * FEATURES:
- * - Configurable bounds: maxBytes (default 5 MB), maxEntries (default 5000)
- * - Redaction before write: strips PII from payloads before disk persistence
- * - Leftover drain: on init, returns envelopes from previous run before
- *   accepting new ones — ensures crash-time events are not lost
- * - FIFO ordering: popBatch() returns envelopes in insertion order
- *
- * STORAGE: persists through the SDK's first-party `StorageBackend` (durable
- * native file store by default; in-memory only as an emergency fallback). No
- * third-party storage dependency is required.
- */
-
-import type { Envelope } from '../envelope/envelope';
-import type { StorageBackend } from '../../storage/StorageBackend';
-import { logger } from '../../core/logger/internalLogger';
-import { redactBody } from '../../debug/redaction';
-
-// ─── Constants ──────────────────────────────────────────────────────────────
-
-const META_KEY = 'scalebun_q:meta';
-const ENTRY_PREFIX = 'scalebun_q:e:';
-
-// ─── Config ─────────────────────────────────────────────────────────────────
-
-export interface PersistenceConfig {
-    /** Whether disk persistence is enabled. Default: true */
-    enabled: boolean;
-    /** Max total bytes stored. Default: 5 MB (5_242_880) */
-    maxBytes: number;
-    /** Max total entries stored. Default: 5000 */
-    maxEntries: number;
-    /** Whether to redact PII before writing to disk. Default: true */
-    redactBeforeWrite: boolean;
-}
-
-export const DEFAULT_PERSISTENCE_CONFIG: PersistenceConfig = {
-    enabled: true,
-    maxBytes: 5_242_880,   // 5 MB
-    maxEntries: 5_000,
-    redactBeforeWrite: true,
-};
-
-// ─── Queue Metadata ─────────────────────────────────────────────────────────
-
-interface QueueMeta {
-    /** Sequence number of the oldest entry */
-    head: number;
-    /** Sequence number to use for the NEXT entry */
-    tail: number;
-    /** Current entry count */
-    count: number;
-    /** Approximate total bytes stored (envelope JSON sizes) */
-    totalBytes: number;
-}
-
-const EMPTY_META: QueueMeta = { head: 0, tail: 0, count: 0, totalBytes: 0 };
-
-// ─── PersistentQueue ────────────────────────────────────────────────────────
-
-export class PersistentQueue {
-    private backend: StorageBackend;
-    private config: PersistenceConfig;
-    private meta: QueueMeta;
-
-    /**
-     * Create a PersistentQueue backed by the given storage.
-     *
-     * @param backend - Storage backend (MemoryBackend for tests, native durable backend for prod)
-     * @param config  - Persistence configuration (bounds, redaction)
-     */
-    constructor(backend: StorageBackend, config: Partial<PersistenceConfig> = {}) {
-        this.backend = backend;
-        this.config = { ...DEFAULT_PERSISTENCE_CONFIG, ...config };
-        this.meta = this._loadMeta();
-
-        logger.debug(
-            `[PersistentQueue] Initialized: count=${this.meta.count}, ` +
-            `bytes=${this.meta.totalBytes}, head=${this.meta.head}, tail=${this.meta.tail}`,
-        );
-    }
-
-    // ─── Public API ─────────────────────────────────────────────────────
-
-    /**
-     * Add an envelope to the queue.
-     *
-     * If redactBeforeWrite is enabled, the envelope payload is redacted
-     * before serialization. If bounds are exceeded, the oldest entries
-     * are evicted.
-     */
-    add(envelope: Envelope): void {
-        try {
-            const toStore = this.config.redactBeforeWrite
-                ? this._redactEnvelope(envelope)
-                : envelope;
-
-            const serialized = JSON.stringify(toStore);
-            const byteSize = serialized.length; // Approximate: 1 char ≈ 1 byte for ASCII/JSON
-
-            // Evict oldest entries if we'd exceed caps
-            this._evictIfNeeded(byteSize);
-
-            const key = ENTRY_PREFIX + this.meta.tail;
-            this.backend.set(key, serialized);
-
-            this.meta.tail++;
-            this.meta.count++;
-            this.meta.totalBytes += byteSize;
-            this._saveMeta();
-        } catch (e) {
-            logger.error('[PersistentQueue] Failed to add envelope:', e);
-        }
-    }
-
-    /**
-     * Pop a batch of envelopes in FIFO order.
-     *
-     * @param limit - Max number of envelopes to return (default 50)
-     * @returns Array of deserialized envelopes
-     */
-    popBatch(limit = 50): Envelope[] {
-        const batch: Envelope[] = [];
-        try {
-            const count = Math.min(limit, this.meta.count);
-            for (let i = 0; i < count; i++) {
-                const seq = this.meta.head + i;
-                const key = ENTRY_PREFIX + seq;
-                const raw = this.backend.get(key);
-                if (raw) {
-                    try {
-                        batch.push(JSON.parse(raw));
-                    } catch {
-                        logger.warn(`[PersistentQueue] Corrupt entry at seq=${seq}, skipping`);
-                    }
-                    this.backend.delete(key);
-                    this.meta.totalBytes -= raw.length;
-                } else {
-                    // Gap — entry was already evicted or corrupted
-                    logger.debug(`[PersistentQueue] Missing entry at seq=${seq}`);
-                }
-            }
-
-            this.meta.head += count;
-            this.meta.count -= count;
-            if (this.meta.totalBytes < 0) this.meta.totalBytes = 0;
-
-            // Reset counters when empty to prevent unbounded seq growth
-            if (this.meta.count === 0) {
-                this.meta.head = 0;
-                this.meta.tail = 0;
-                this.meta.totalBytes = 0;
-            }
-
-            this._saveMeta();
-        } catch (e) {
-            logger.error('[PersistentQueue] Failed to pop batch:', e);
-        }
-        return batch;
-    }
-
-    /**
-     * Return a previously-popped batch to the FRONT of the queue, preserving
-     * the batch's original FIFO order relative to the rest of the queue.
-     *
-     * Used when a flush fails with a recoverable error: the events must go back
-     * exactly where they were (oldest-first) rather than being appended to the
-     * tail behind newer events. These envelopes were already redacted on their
-     * first `add()`, so redaction is intentionally NOT re-applied here (avoids
-     * double-masking and wasted work).
-     */
-    requeueBatch(batch: Envelope[]): void {
-        if (batch.length === 0) return;
-        try {
-            // Insert in reverse so batch[0] ends up at the smallest head index.
-            for (let i = batch.length - 1; i >= 0; i--) {
-                const serialized = JSON.stringify(batch[i]);
-                this.meta.head--;
-                const key = ENTRY_PREFIX + this.meta.head;
-                this.backend.set(key, serialized);
-                this.meta.count++;
-                this.meta.totalBytes += serialized.length;
-            }
-            this._saveMeta();
-        } catch (e) {
-            logger.warn('[PersistentQueue] Failed to requeue batch:', e);
-        }
-    }
-
-    /**
-     * Current queue length (number of envelopes).
-     */
-    length(): number {
-        return this.meta.count;
-    }
-
-    /**
-     * Current approximate total bytes stored.
-     */
-    totalBytes(): number {
-        return this.meta.totalBytes;
-    }
-
-    /**
-     * Drain all leftover envelopes from a previous app run.
-     *
-     * Call this during SDK init, BEFORE accepting new events.
-     * Returns all stored envelopes and clears the queue.
-     * If no leftovers exist, returns an empty array.
-     */
-    drainLeftovers(): Envelope[] {
-        if (this.meta.count === 0) return [];
-
-        logger.info(
-            `[PersistentQueue] Draining ${this.meta.count} leftover envelopes ` +
-            `from previous run (${this.meta.totalBytes} bytes)`,
-        );
-
-        // Pop everything
-        return this.popBatch(this.meta.count);
-    }
-
-    /**
-     * Clear all entries and reset metadata.
-     */
-    clear(): void {
-        try {
-            // Delete all entry keys
-            for (let seq = this.meta.head; seq < this.meta.tail; seq++) {
-                this.backend.delete(ENTRY_PREFIX + seq);
-            }
-            this.meta = { ...EMPTY_META };
-            this._saveMeta();
-        } catch (e) {
-            logger.error('[PersistentQueue] Failed to clear:', e);
-        }
-    }
-
-    // ─── Internal ───────────────────────────────────────────────────────
-
-    /**
-     * Load queue metadata from storage.
-     * If no metadata exists, scans for orphan entry keys (recovery mode).
-     */
-    private _loadMeta(): QueueMeta {
-        try {
-            const raw = this.backend.get(META_KEY);
-            if (raw) {
-                const parsed = JSON.parse(raw) as QueueMeta;
-                // Validate loaded meta
-                if (
-                    typeof parsed.head === 'number' &&
-                    typeof parsed.tail === 'number' &&
-                    typeof parsed.count === 'number' &&
-                    typeof parsed.totalBytes === 'number' &&
-                    parsed.head >= 0 &&
-                    parsed.tail >= parsed.head &&
-                    parsed.count >= 0
-                ) {
-                    return parsed;
-                }
-                logger.warn('[PersistentQueue] Invalid metadata, recovering...');
-            }
-
-            // Recovery: scan for orphan keys
-            return this._recoverMeta();
-        } catch (e) {
-            logger.error('[PersistentQueue] Failed to load metadata:', e);
-            return { ...EMPTY_META };
-        }
-    }
-
-    /**
-     * Recovery mode: scan getAllKeys() for `scalebun_q:e:*` entries
-     * and reconstruct metadata from what's actually stored.
-     */
-    private _recoverMeta(): QueueMeta {
-        try {
-            const allKeys = this.backend.getAllKeys();
-            const entryKeys = allKeys
-                .filter(k => k.startsWith(ENTRY_PREFIX))
-                .map(k => parseInt(k.substring(ENTRY_PREFIX.length), 10))
-                .filter(n => !isNaN(n))
-                .sort((a, b) => a - b);
-
-            if (entryKeys.length === 0) return { ...EMPTY_META };
-
-            let totalBytes = 0;
-            for (const seq of entryKeys) {
-                const raw = this.backend.get(ENTRY_PREFIX + seq);
-                if (raw) totalBytes += raw.length;
-            }
-
-            const meta: QueueMeta = {
-                head: entryKeys[0],
-                tail: entryKeys[entryKeys.length - 1] + 1,
-                count: entryKeys.length,
-                totalBytes,
-            };
-
-            logger.info(
-                `[PersistentQueue] Recovered metadata: ${meta.count} entries, ` +
-                `head=${meta.head}, tail=${meta.tail}, bytes=${meta.totalBytes}`,
-            );
-
-            this.backend.set(META_KEY, JSON.stringify(meta));
-            return meta;
-        } catch {
-            return { ...EMPTY_META };
-        }
-    }
-
-    /** Save queue metadata to storage. */
-    private _saveMeta(): void {
-        try {
-            this.backend.set(META_KEY, JSON.stringify(this.meta));
-        } catch (e) {
-            logger.error('[PersistentQueue] Failed to save metadata:', e);
-        }
-    }
-
-    /**
-     * Evict oldest entries if adding `newBytes` would exceed caps.
-     */
-    private _evictIfNeeded(newBytes: number): void {
-        // Evict for entry count cap
-        while (this.meta.count >= this.config.maxEntries && this.meta.head < this.meta.tail) {
-            this._evictOldest();
-        }
-
-        // Evict for byte cap
-        while (
-            this.meta.totalBytes + newBytes > this.config.maxBytes &&
-            this.meta.count > 0 &&
-            this.meta.head < this.meta.tail
-        ) {
-            this._evictOldest();
-        }
-    }
-
-    /** Evict the oldest entry. */
-    private _evictOldest(): void {
-        const key = ENTRY_PREFIX + this.meta.head;
-        const raw = this.backend.get(key);
-        if (raw) {
-            this.meta.totalBytes -= raw.length;
-        }
-        this.backend.delete(key);
-        this.meta.head++;
-        this.meta.count--;
-        if (this.meta.totalBytes < 0) this.meta.totalBytes = 0;
-    }
-
-    /**
-     * Apply redaction to an envelope before disk write.
-     * Returns a new envelope — never mutates the original.
-     */
-    private _redactEnvelope(envelope: Envelope): Envelope {
-        try {
-            return {
-                ...envelope,
-                payload: redactBody(envelope.payload) as any,
-            };
-        } catch {
-            // If redaction fails, store as-is rather than dropping
-            return envelope;
-        }
-    }
-}
-
-// ─── Factory ────────────────────────────────────────────────────────────────
-
-/**
- * Create a PersistentQueue with the best available backend.
- *
- * If persistence is disabled in config, uses MemoryBackend.
- * Otherwise uses the shared first-party durable backend from createStorageBackend().
- *
- * @param config - Persistence config from SDK init
- * @param backend - Override backend (for tests). If provided, skips auto-detection.
- */
-export function createPersistentQueue(
-    config: Partial<PersistenceConfig> = {},
-    backend?: StorageBackend,
-): PersistentQueue {
-    if (backend) {
-        return new PersistentQueue(backend, config);
-    }
-
-    const mergedConfig = { ...DEFAULT_PERSISTENCE_CONFIG, ...config };
-
-    if (!mergedConfig.enabled) {
-        logger.info('[PersistentQueue] Persistence disabled — using in-memory queue');
-        const { MemoryBackend } = require('../../storage/StorageBackend');
-        return new PersistentQueue(new MemoryBackend(), mergedConfig);
-    }
-
-    const { createStorageBackend } = require('../../storage/StorageBackend');
-    const autoBackend = createStorageBackend();
-    return new PersistentQueue(autoBackend, mergedConfig);
-}
+/**
+ * ScaleBun SDK — Disk-Backed Persistent Queue
+ *
+ * Persists event envelopes to a StorageBackend so they survive
+ * app restarts, crashes, and force-kills.
+ *
+ * STORAGE LAYOUT (chunked keys):
+ *   scalebun_q:meta        → { head, tail, count, totalBytes }
+ *   scalebun_q:e:{seq}     → JSON-serialized envelope
+ *
+ * Each envelope gets its own key. This makes add() O(1) and
+ * popBatch() O(batch_size) instead of the old O(queue_size)
+ * approach of serializing the entire array on every write.
+ *
+ * FEATURES:
+ * - Configurable bounds: maxBytes (default 5 MB), maxEntries (default 5000)
+ * - Redaction before write: strips PII from payloads before disk persistence
+ * - Leftover drain: on init, returns envelopes from previous run before
+ *   accepting new ones — ensures crash-time events are not lost
+ * - FIFO ordering: popBatch() returns envelopes in insertion order
+ *
+ * STORAGE: persists through the SDK's first-party `StorageBackend` (durable
+ * native file store by default; in-memory only as an emergency fallback). No
+ * third-party storage dependency is required.
+ */
+
+import type { Envelope } from '../envelope/envelope';
+import type { StorageBackend } from '../../storage/StorageBackend';
+import { logger } from '../../core/logger/internalLogger';
+import { redactBody } from '../../debug/redaction';
+
+// ─── Constants ──────────────────────────────────────────────────────────────
+
+const META_KEY = 'scalebun_q:meta';
+const ENTRY_PREFIX = 'scalebun_q:e:';
+
+// ─── Config ─────────────────────────────────────────────────────────────────
+
+export interface PersistenceConfig {
+    /** Whether disk persistence is enabled. Default: true */
+    enabled: boolean;
+    /** Max total bytes stored. Default: 5 MB (5_242_880) */
+    maxBytes: number;
+    /** Max total entries stored. Default: 5000 */
+    maxEntries: number;
+    /** Whether to redact PII before writing to disk. Default: true */
+    redactBeforeWrite: boolean;
+}
+
+export const DEFAULT_PERSISTENCE_CONFIG: PersistenceConfig = {
+    enabled: true,
+    maxBytes: 5_242_880,   // 5 MB
+    maxEntries: 5_000,
+    redactBeforeWrite: true,
+};
+
+// ─── Queue Metadata ─────────────────────────────────────────────────────────
+
+interface QueueMeta {
+    /** Sequence number of the oldest entry */
+    head: number;
+    /** Sequence number to use for the NEXT entry */
+    tail: number;
+    /** Current entry count */
+    count: number;
+    /** Approximate total bytes stored (envelope JSON sizes) */
+    totalBytes: number;
+}
+
+const EMPTY_META: QueueMeta = { head: 0, tail: 0, count: 0, totalBytes: 0 };
+
+// ─── PersistentQueue ────────────────────────────────────────────────────────
+
+export class PersistentQueue {
+    private backend: StorageBackend;
+    private config: PersistenceConfig;
+    private meta: QueueMeta;
+
+    /**
+     * Create a PersistentQueue backed by the given storage.
+     *
+     * @param backend - Storage backend (MemoryBackend for tests, native durable backend for prod)
+     * @param config  - Persistence configuration (bounds, redaction)
+     */
+    constructor(backend: StorageBackend, config: Partial<PersistenceConfig> = {}) {
+        this.backend = backend;
+        this.config = { ...DEFAULT_PERSISTENCE_CONFIG, ...config };
+        this.meta = this._loadMeta();
+
+        logger.debug(
+            `[PersistentQueue] Initialized: count=${this.meta.count}, ` +
+            `bytes=${this.meta.totalBytes}, head=${this.meta.head}, tail=${this.meta.tail}`,
+        );
+    }
+
+    // ─── Public API ─────────────────────────────────────────────────────
+
+    /**
+     * Add an envelope to the queue.
+     *
+     * If redactBeforeWrite is enabled, the envelope payload is redacted
+     * before serialization. If bounds are exceeded, the oldest entries
+     * are evicted.
+     */
+    add(envelope: Envelope): void {
+        try {
+            const toStore = this.config.redactBeforeWrite
+                ? this._redactEnvelope(envelope)
+                : envelope;
+
+            const serialized = JSON.stringify(toStore);
+            const byteSize = serialized.length; // Approximate: 1 char ≈ 1 byte for ASCII/JSON
+
+            // Evict oldest entries if we'd exceed caps
+            this._evictIfNeeded(byteSize);
+
+            const key = ENTRY_PREFIX + this.meta.tail;
+            this.backend.set(key, serialized);
+
+            this.meta.tail++;
+            this.meta.count++;
+            this.meta.totalBytes += byteSize;
+            this._saveMeta();
+        } catch (e) {
+            logger.error('[PersistentQueue] Failed to add envelope:', e);
+        }
+    }
+
+    /**
+     * Pop a batch of envelopes in FIFO order.
+     *
+     * @param limit - Max number of envelopes to return (default 50)
+     * @returns Array of deserialized envelopes
+     */
+    popBatch(limit = 50): Envelope[] {
+        const batch: Envelope[] = [];
+        try {
+            const count = Math.min(limit, this.meta.count);
+            for (let i = 0; i < count; i++) {
+                const seq = this.meta.head + i;
+                const key = ENTRY_PREFIX + seq;
+                const raw = this.backend.get(key);
+                if (raw) {
+                    try {
+                        batch.push(JSON.parse(raw));
+                    } catch {
+                        logger.warn(`[PersistentQueue] Corrupt entry at seq=${seq}, skipping`);
+                    }
+                    this.backend.delete(key);
+                    this.meta.totalBytes -= raw.length;
+                } else {
+                    // Gap — entry was already evicted or corrupted
+                    logger.debug(`[PersistentQueue] Missing entry at seq=${seq}`);
+                }
+            }
+
+            this.meta.head += count;
+            this.meta.count -= count;
+            if (this.meta.totalBytes < 0) this.meta.totalBytes = 0;
+
+            // Reset counters when empty to prevent unbounded seq growth
+            if (this.meta.count === 0) {
+                this.meta.head = 0;
+                this.meta.tail = 0;
+                this.meta.totalBytes = 0;
+            }
+
+            this._saveMeta();
+        } catch (e) {
+            logger.error('[PersistentQueue] Failed to pop batch:', e);
+        }
+        return batch;
+    }
+
+    /**
+     * Return a previously-popped batch to the FRONT of the queue, preserving
+     * the batch's original FIFO order relative to the rest of the queue.
+     *
+     * Used when a flush fails with a recoverable error: the events must go back
+     * exactly where they were (oldest-first) rather than being appended to the
+     * tail behind newer events. These envelopes were already redacted on their
+     * first `add()`, so redaction is intentionally NOT re-applied here (avoids
+     * double-masking and wasted work).
+     */
+    requeueBatch(batch: Envelope[]): void {
+        if (batch.length === 0) return;
+        try {
+            // Insert in reverse so batch[0] ends up at the smallest head index.
+            for (let i = batch.length - 1; i >= 0; i--) {
+                const serialized = JSON.stringify(batch[i]);
+                this.meta.head--;
+                const key = ENTRY_PREFIX + this.meta.head;
+                this.backend.set(key, serialized);
+                this.meta.count++;
+                this.meta.totalBytes += serialized.length;
+            }
+            this._saveMeta();
+        } catch (e) {
+            logger.warn('[PersistentQueue] Failed to requeue batch:', e);
+        }
+    }
+
+    /**
+     * Current queue length (number of envelopes).
+     */
+    length(): number {
+        return this.meta.count;
+    }
+
+    /**
+     * Current approximate total bytes stored.
+     */
+    totalBytes(): number {
+        return this.meta.totalBytes;
+    }
+
+    /**
+     * Drain all leftover envelopes from a previous app run.
+     *
+     * Call this during SDK init, BEFORE accepting new events.
+     * Returns all stored envelopes and clears the queue.
+     * If no leftovers exist, returns an empty array.
+     */
+    drainLeftovers(): Envelope[] {
+        if (this.meta.count === 0) return [];
+
+        logger.info(
+            `[PersistentQueue] Draining ${this.meta.count} leftover envelopes ` +
+            `from previous run (${this.meta.totalBytes} bytes)`,
+        );
+
+        // Pop everything
+        return this.popBatch(this.meta.count);
+    }
+
+    /**
+     * Clear all entries and reset metadata.
+     */
+    clear(): void {
+        try {
+            // Delete all entry keys
+            for (let seq = this.meta.head; seq < this.meta.tail; seq++) {
+                this.backend.delete(ENTRY_PREFIX + seq);
+            }
+            this.meta = { ...EMPTY_META };
+            this._saveMeta();
+        } catch (e) {
+            logger.error('[PersistentQueue] Failed to clear:', e);
+        }
+    }
+
+    // ─── Internal ───────────────────────────────────────────────────────
+
+    /**
+     * Load queue metadata from storage.
+     * If no metadata exists, scans for orphan entry keys (recovery mode).
+     */
+    private _loadMeta(): QueueMeta {
+        try {
+            const raw = this.backend.get(META_KEY);
+            if (raw) {
+                const parsed = JSON.parse(raw) as QueueMeta;
+                // Validate loaded meta
+                if (
+                    typeof parsed.head === 'number' &&
+                    typeof parsed.tail === 'number' &&
+                    typeof parsed.count === 'number' &&
+                    typeof parsed.totalBytes === 'number' &&
+                    parsed.head >= 0 &&
+                    parsed.tail >= parsed.head &&
+                    parsed.count >= 0
+                ) {
+                    return parsed;
+                }
+                logger.warn('[PersistentQueue] Invalid metadata, recovering...');
+            }
+
+            // Recovery: scan for orphan keys
+            return this._recoverMeta();
+        } catch (e) {
+            logger.error('[PersistentQueue] Failed to load metadata:', e);
+            return { ...EMPTY_META };
+        }
+    }
+
+    /**
+     * Recovery mode: scan getAllKeys() for `scalebun_q:e:*` entries
+     * and reconstruct metadata from what's actually stored.
+     */
+    private _recoverMeta(): QueueMeta {
+        try {
+            const allKeys = this.backend.getAllKeys();
+            const entryKeys = allKeys
+                .filter(k => k.startsWith(ENTRY_PREFIX))
+                .map(k => parseInt(k.substring(ENTRY_PREFIX.length), 10))
+                .filter(n => !isNaN(n))
+                .sort((a, b) => a - b);
+
+            if (entryKeys.length === 0) return { ...EMPTY_META };
+
+            let totalBytes = 0;
+            for (const seq of entryKeys) {
+                const raw = this.backend.get(ENTRY_PREFIX + seq);
+                if (raw) totalBytes += raw.length;
+            }
+
+            const meta: QueueMeta = {
+                head: entryKeys[0],
+                tail: entryKeys[entryKeys.length - 1] + 1,
+                count: entryKeys.length,
+                totalBytes,
+            };
+
+            logger.info(
+                `[PersistentQueue] Recovered metadata: ${meta.count} entries, ` +
+                `head=${meta.head}, tail=${meta.tail}, bytes=${meta.totalBytes}`,
+            );
+
+            this.backend.set(META_KEY, JSON.stringify(meta));
+            return meta;
+        } catch {
+            return { ...EMPTY_META };
+        }
+    }
+
+    /** Save queue metadata to storage. */
+    private _saveMeta(): void {
+        try {
+            this.backend.set(META_KEY, JSON.stringify(this.meta));
+        } catch (e) {
+            logger.error('[PersistentQueue] Failed to save metadata:', e);
+        }
+    }
+
+    /**
+     * Evict oldest entries if adding `newBytes` would exceed caps.
+     */
+    private _evictIfNeeded(newBytes: number): void {
+        // Evict for entry count cap
+        while (this.meta.count >= this.config.maxEntries && this.meta.head < this.meta.tail) {
+            this._evictOldest();
+        }
+
+        // Evict for byte cap
+        while (
+            this.meta.totalBytes + newBytes > this.config.maxBytes &&
+            this.meta.count > 0 &&
+            this.meta.head < this.meta.tail
+        ) {
+            this._evictOldest();
+        }
+    }
+
+    /** Evict the oldest entry. */
+    private _evictOldest(): void {
+        const key = ENTRY_PREFIX + this.meta.head;
+        const raw = this.backend.get(key);
+        if (raw) {
+            this.meta.totalBytes -= raw.length;
+        }
+        this.backend.delete(key);
+        this.meta.head++;
+        this.meta.count--;
+        if (this.meta.totalBytes < 0) this.meta.totalBytes = 0;
+    }
+
+    /**
+     * Apply redaction to an envelope before disk write.
+     * Returns a new envelope — never mutates the original.
+     */
+    private _redactEnvelope(envelope: Envelope): Envelope {
+        try {
+            return {
+                ...envelope,
+                payload: redactBody(envelope.payload) as any,
+            };
+        } catch {
+            // If redaction fails, store as-is rather than dropping
+            return envelope;
+        }
+    }
+}
+
+// ─── Factory ────────────────────────────────────────────────────────────────
+
+/**
+ * Create a PersistentQueue with the best available backend.
+ *
+ * If persistence is disabled in config, uses MemoryBackend.
+ * Otherwise uses the shared first-party durable backend from createStorageBackend().
+ *
+ * @param config - Persistence config from SDK init
+ * @param backend - Override backend (for tests). If provided, skips auto-detection.
+ */
+export function createPersistentQueue(
+    config: Partial<PersistenceConfig> = {},
+    backend?: StorageBackend,
+): PersistentQueue {
+    if (backend) {
+        return new PersistentQueue(backend, config);
+    }
+
+    const mergedConfig = { ...DEFAULT_PERSISTENCE_CONFIG, ...config };
+
+    if (!mergedConfig.enabled) {
+        logger.info('[PersistentQueue] Persistence disabled — using in-memory queue');
+        const { MemoryBackend } = require('../../storage/StorageBackend');
+        return new PersistentQueue(new MemoryBackend(), mergedConfig);
+    }
+
+    const { createStorageBackend } = require('../../storage/StorageBackend');
+    const autoBackend = createStorageBackend();
+    return new PersistentQueue(autoBackend, mergedConfig);
+}