@genn-inc/cluebase-frontend-sdk 0.0.1

package/dist/exporter/browser-outbox.js

@@ -0,0 +1,876 @@
+import { DiagnosticStore } from "./diagnostics.js";
+import { isBrowserSourceSignalEvent } from "./source-event.js";
+import { canonicalize as canonicalJsonStringify } from "json-canonicalize";
+import { addStorageListener, browserEventsByteLength, createConsentChannel, createConsentRecord, createDraft, createGeneration, createLegacyTombstone, createPending, consentRecordKey, draftRecordKey, hasLegacyTombstone, largestFittingPrefix, nowIso, outboxEventCount, parseRecord, readLocks, readStorage, recordBatchId, sha256Hex, toHeadBatch, splitPendingRecord, pendingRecordKey, tombstoneRecordKey, UNANCHORED_COLLECTION_GENERATION, verifyHash, withChecksum, withoutChecksum, LEGACY_TOMBSTONE_LIMIT, } from "./browser-outbox-records.js";
+export class BrowserOutbox {
+    constructor(options) {
+        this.drafts = [];
+        this.pending = [];
+        this.tombstones = [];
+        this.nextOrdinal = 1;
+        this.nextPermitOrdinal = 1;
+        this.legacyImportBlocked = false;
+        this.consentAnchorEstablished = false;
+        this.memoryOnly = false;
+        this.durableWarningRecorded = false;
+        this.deliveryLockHeld = false;
+        this.purgePending = false;
+        this.consentStateUnavailable = false;
+        this.projectHash = sha256Hex(options.projectKey);
+        this.prefix = `cluebase:source-event-outbox:v2:${this.projectHash}:`;
+        this.consentKey = consentRecordKey(this.prefix);
+        this.legacyKey = `cluebase:source_event_outbox:${options.projectKey}`;
+        this.lockName = `cluebase:source-event-outbox:v2:${this.projectHash}`;
+        this.storage = "storage" in options ? options.storage ?? null : readStorage();
+        this.durableOutboxSupported = readLocks() !== null;
+        this.maxBytes = Math.max(1024, options.maxBytes);
+        this.maxEvents = Math.max(1, options.maxEvents);
+        this.metrics = options.metrics ?? null;
+        this.diagnostics = options.diagnostics ?? new DiagnosticStore();
+        this.onConsentRevoked = options.onConsentRevoked ?? (() => undefined);
+        this.consent = options.initialConsent;
+        this.generation = createGeneration();
+        this.initialDenialPending = options.initialConsent === "denied";
+        if (this.initialDenialPending)
+            this.legacyImportBlocked = true;
+        // Consent is the only state that must be available before the first lock
+        // acquisition. All outbox scans and mutations happen under the project
+        // Web Lock in `withDeliveryLock`.
+        if (!this.initialDenialPending)
+            this.restore(false);
+        if (!this.durableOutboxSupported) {
+            this.memoryOnly = true;
+            this.warnDurableUnavailable();
+        }
+        this.consentChannel = createConsentChannel(this.projectHash, (generation) => {
+            this.applyRemoteDenial(generation);
+        });
+        this.removeConsentStorageListener = addStorageListener(this.consentKey, () => this.restoreConsentFromStorage());
+        this.removeLegacyStorageListener = addStorageListener(this.legacyKey, () => {
+            this.diagnostics.record({ code: "legacy_writer_detected" });
+        });
+    }
+    currentConsent() {
+        return this.consent;
+    }
+    capturePermit() {
+        return Object.freeze({
+            generation: this.consentAnchorEstablished
+                ? this.generation
+                : UNANCHORED_COLLECTION_GENERATION,
+            permittedAtStart: this.consent !== "denied",
+            captureOrdinal: this.nextPermitOrdinal++,
+        });
+    }
+    permits(permit) {
+        return (permit.permittedAtStart &&
+            this.consent !== "denied" &&
+            permit.generation === this.generation);
+    }
+    setConsent(next) {
+        const recoveryExpectedRaw = this.consentStateUnavailable
+            ? this.peekConsentRaw()
+            : undefined;
+        const expectedGeneration = this.consentAnchorEstablished && !this.consentStateUnavailable
+            ? this.generation
+            : null;
+        const wasDenied = this.consent === "denied";
+        if (next === "denied" && !wasDenied) {
+            const purged = this.pendingEventCount();
+            this.consent = "denied";
+            this.generation = createGeneration();
+            this.legacyImportBlocked = true;
+            this.diagnostics.rotateForConsentPurge(purged);
+            this.consentChannel?.postMessage({ type: "denied", generation: this.generation });
+            this.clearMemory();
+            return Object.freeze({
+                state: this.consent,
+                generation: this.generation,
+                expectedGeneration,
+                recoveryExpectedRaw,
+                legacyImportBlocked: this.legacyImportBlocked,
+                purge: true,
+            });
+        }
+        if (this.purgePending) {
+            return Object.freeze({
+                state: next,
+                generation: this.generation,
+                expectedGeneration,
+                recoveryExpectedRaw,
+                legacyImportBlocked: this.legacyImportBlocked,
+                purge: false,
+            });
+        }
+        this.consent = next;
+        return Object.freeze({
+            state: this.consent,
+            generation: this.generation,
+            expectedGeneration,
+            recoveryExpectedRaw,
+            legacyImportBlocked: this.legacyImportBlocked,
+            purge: false,
+        });
+    }
+    commitConsentTransition(transition) {
+        if (transition.generation !== this.generation)
+            return;
+        if (transition.state !== "denied" && this.purgePending) {
+            this.consent = "denied";
+            this.legacyImportBlocked = true;
+            this.clearMemory();
+            this.onConsentRevoked();
+            return;
+        }
+        if (transition.state !== "denied" &&
+            transition.recoveryExpectedRaw !== undefined) {
+            const currentRaw = this.peekConsentRaw();
+            if (currentRaw === false ||
+                currentRaw !== transition.recoveryExpectedRaw) {
+                const persisted = this.readConsent();
+                if (persisted?.state === "denied")
+                    this.applyRemoteDenial(persisted.collectionGeneration);
+                else if (persisted)
+                    this.reconcileRemotePermittedConsent(persisted);
+                else
+                    this.failClosedConsentState();
+                return;
+            }
+        }
+        else if (transition.state !== "denied") {
+            const persisted = this.readConsent();
+            if (persisted?.state === "denied" &&
+                transition.expectedGeneration !== persisted.collectionGeneration) {
+                this.applyRemoteDenial(persisted.collectionGeneration);
+                return;
+            }
+            if (persisted &&
+                persisted.collectionGeneration !== transition.expectedGeneration) {
+                this.reconcileRemotePermittedConsent(persisted);
+                return;
+            }
+            if (!persisted && transition.expectedGeneration !== null) {
+                this.failClosedConsentState();
+                return;
+            }
+        }
+        if (this.initialDenialPending && transition.state !== "denied") {
+            if (!this.persistCommittedConsent({
+                state: "denied",
+                generation: transition.generation,
+                expectedGeneration: null,
+                legacyImportBlocked: true,
+                purge: true,
+            })) {
+                return;
+            }
+        }
+        this.initialDenialPending = false;
+        this.persistCommittedConsent(transition);
+    }
+    persistCommittedConsent(transition) {
+        this.consent = transition.state;
+        this.generation = transition.generation;
+        this.legacyImportBlocked = transition.legacyImportBlocked;
+        const persisted = this.persistConsent();
+        if (!persisted) {
+            this.diagnostics.record({ code: "consent_persistence_failed" });
+            this.failClosedConsentState();
+        }
+        if (persisted) {
+            this.consentStateUnavailable = false;
+            this.consentAnchorEstablished = true;
+        }
+        const purged = transition.purge ? this.purgeAll() : true;
+        return persisted && purged;
+    }
+    addDraft(event, permit = this.capturePermit()) {
+        const resolvedPermit = this.resolvePermit(permit);
+        if (!resolvedPermit)
+            return false;
+        const draft = createDraft({
+            event,
+            permit: resolvedPermit,
+            projectHash: this.projectHash,
+            createdAt: nowIso(),
+        });
+        if (!draft)
+            return false;
+        const key = draftRecordKey(this.prefix, draft.eventKeyHash);
+        const existing = this.readRecord(key);
+        if (existing) {
+            if (existing.kind === "draft" &&
+                existing.recordVerifierSha256 === draft.recordVerifierSha256) {
+                return true;
+            }
+            this.diagnostics.record({ code: "outbox_key_collision" });
+            return false;
+        }
+        this.drafts.push(draft);
+        this.enforceCapacity();
+        if (!this.writeRecord(key, draft)) {
+            this.memoryOnly = true;
+            this.warnDurableUnavailable();
+        }
+        return this.drafts.some((item) => item.eventId === draft.eventId);
+    }
+    estimatedDraftBytes(measure, metadata) {
+        return measure(this.drafts.map((draft) => draft.event), metadata);
+    }
+    prepareFence(input) {
+        const claimedEventKeyHashes = new Set(this.pending.flatMap((record) => record.eventKeyHashes));
+        const candidates = this.drafts.filter((draft) => !claimedEventKeyHashes.has(draft.eventKeyHash) &&
+            this.permits({
+                generation: draft.collectionGeneration,
+                permittedAtStart: draft.permittedAtStart,
+                captureOrdinal: 0,
+            }) &&
+            (draft.origin !== "legacy_v1" ||
+                hasLegacyTombstone(draft, this.tombstones)));
+        let oversized = 0;
+        let cursor = 0;
+        let targetOrdinal = this.pending[this.pending.length - 1]?.ordinal ?? 0;
+        while (cursor < candidates.length) {
+            const remaining = candidates.slice(cursor);
+            const metadata = input.createMetadata();
+            const count = largestFittingPrefix(remaining, input.maxPayloadBytes, metadata, input.measure);
+            if (count === 0) {
+                const draft = remaining[0];
+                if (draft) {
+                    this.removeDraft(draft);
+                    this.metrics?.increment("oversized_event_count");
+                    this.diagnostics.record({
+                        code: "event_oversize",
+                        event_fingerprint: this.diagnostics.eventFingerprint(canonicalJsonStringify(draft.event)),
+                    });
+                }
+                oversized += 1;
+                cursor += 1;
+                continue;
+            }
+            const selected = remaining.slice(0, count);
+            const record = createPending({
+                projectHash: this.projectHash,
+                metadata,
+                drafts: selected,
+                ordinal: this.nextOrdinal,
+            });
+            const key = pendingRecordKey(this.prefix, record.batchId);
+            if (!this.writeRecord(key, record)) {
+                this.memoryOnly = true;
+                this.warnDurableUnavailable();
+                break;
+            }
+            this.pending.push(record);
+            // The pending record now owns these events. Drop the drafts from the
+            // in-memory list unconditionally so a failed storage removal cannot
+            // leave them as live candidates for a duplicate send; the pending
+            // record carries the responsibility to delete any surviving draft
+            // record when it is finalized (`removeClaimedDraftRecords`).
+            for (const draft of selected) {
+                this.removeRecord(draftRecordKey(this.prefix, draft.eventKeyHash));
+            }
+            this.drafts = this.drafts.filter((draft) => !selected.includes(draft));
+            targetOrdinal = record.ordinal;
+            this.nextOrdinal += 1;
+            cursor += count;
+        }
+        return { targetOrdinal, oversized };
+    }
+    headThrough(targetOrdinal) {
+        const record = this.pending
+            .sort((left, right) => left.ordinal - right.ordinal)
+            .find((item) => item.ordinal <= targetOrdinal);
+        if (!record)
+            return null;
+        return toHeadBatch(record, pendingRecordKey(this.prefix, record.batchId));
+    }
+    removeHead(expected) {
+        const record = this.pending.find((item) => item.ordinal === expected.ordinal &&
+            item.batchId === recordBatchId(expected));
+        if (!record || !this.permitsBatch(expected))
+            return false;
+        const key = pendingRecordKey(this.prefix, record.batchId);
+        if (record.kind === "pending" ||
+            record.nextOrdinal === record.children.length - 1) {
+            // Delete any draft record still claimed by this batch before dropping
+            // the pending record. If a claimed draft cannot be removed, keep the
+            // pending record so the draft stays covered and cannot resurrect as a
+            // fresh event on the next restore; the batch is retried idempotently
+            // instead.
+            if (!this.removeClaimedDraftRecords(record))
+                return false;
+            if (!this.removeRecord(key))
+                return false;
+            this.pending = this.pending.filter((item) => item !== record);
+            return true;
+        }
+        const progressed = withChecksum({
+            ...withoutChecksum(record),
+            nextOrdinal: record.nextOrdinal + 1,
+        });
+        if (!this.writeRecord(key, progressed))
+            return false;
+        this.pending = this.pending.map((item) => item === record ? progressed : item);
+        return true;
+    }
+    retainHead(expected) {
+        return (this.permitsBatch(expected) &&
+            this.headThrough(expected.ordinal)?.recordKey === expected.recordKey);
+    }
+    splitHead(expected, createMetadata) {
+        const record = this.pending.find((item) => item.ordinal === expected.ordinal &&
+            item.batchId === recordBatchId(expected));
+        if (!record)
+            return false;
+        const plan = splitPendingRecord(record, createMetadata);
+        if (!plan)
+            return false;
+        const key = pendingRecordKey(this.prefix, record.batchId);
+        if (!this.writeRecord(key, plan))
+            return false;
+        this.pending = this.pending.map((item) => (item === record ? plan : item));
+        this.diagnostics.record({
+            code: "batch_split",
+            batch_fingerprint: expected.diagnosticCanonicalBytes
+                ? this.diagnostics.batchFingerprint(expected.diagnosticCanonicalBytes)
+                : undefined,
+        });
+        return true;
+    }
+    clear() {
+        let removed = true;
+        for (const draft of this.drafts) {
+            removed =
+                this.removeRecord(draftRecordKey(this.prefix, draft.eventKeyHash)) &&
+                    removed;
+        }
+        for (const pending of this.pending) {
+            // Also remove any draft record the batch still claims so a draft that
+            // survived its commit cannot outlive the clear and resurrect on restore.
+            removed = this.removeClaimedDraftRecords(pending) && removed;
+            removed =
+                this.removeRecord(pendingRecordKey(this.prefix, pending.batchId)) &&
+                    removed;
+        }
+        for (const tombstone of this.tombstones) {
+            removed =
+                this.removeRecord(tombstoneRecordKey(this.prefix, tombstone.eventKeyHash)) && removed;
+        }
+        this.drafts = [];
+        this.pending = [];
+        this.tombstones = [];
+        return removed;
+    }
+    close() {
+        this.consentChannel?.close();
+        this.removeConsentStorageListener();
+        this.removeLegacyStorageListener();
+    }
+    pendingEventCount() {
+        return outboxEventCount(this.drafts, this.pending);
+    }
+    pendingBytes() {
+        return browserEventsByteLength([
+            ...this.drafts.map((item) => item.event),
+            ...this.pending.flatMap((item) => item.events.map((event) => event.event)),
+        ]);
+    }
+    async withDeliveryLock(operation, options = {}) {
+        const locks = readLocks();
+        if (!locks) {
+            this.memoryOnly = true;
+            this.warnDurableUnavailable();
+            if (this.purgePending)
+                this.purgeAll();
+            this.initializeConsentForDelivery();
+            return await operation();
+        }
+        return await locks.request(this.lockName, { mode: "exclusive" }, async () => {
+            this.deliveryLockHeld = true;
+            try {
+                if (this.purgePending)
+                    this.purgeAll();
+                if (options.restore !== false) {
+                    this.initializeConsentForDelivery();
+                    this.importLegacy();
+                }
+                return await operation();
+            }
+            finally {
+                this.deliveryLockHeld = false;
+            }
+        });
+    }
+    permitsBatch(batch) {
+        return batch.events.every((event) => this.permits(event.permit));
+    }
+    resolvePermit(permit) {
+        if (!permit.permittedAtStart || this.consent === "denied")
+            return null;
+        if (permit.generation === UNANCHORED_COLLECTION_GENERATION) {
+            if (!this.consentAnchorEstablished)
+                return null;
+            return Object.freeze({
+                generation: this.generation,
+                permittedAtStart: true,
+                captureOrdinal: permit.captureOrdinal,
+            });
+        }
+        return this.permits(permit) ? permit : null;
+    }
+    initializeConsentForDelivery() {
+        if (this.consentStateUnavailable) {
+            this.consent = "denied";
+            this.consentAnchorEstablished = false;
+            this.clearMemory();
+            return;
+        }
+        if (this.initialDenialPending) {
+            this.commitConsentTransition({
+                state: "denied",
+                generation: this.generation,
+                expectedGeneration: null,
+                legacyImportBlocked: true,
+                purge: true,
+            });
+            return;
+        }
+        // A synchronous revocation must fence mutations that were queued before
+        // its durable commit. Never restore an older permitted record over it.
+        if (this.consent === "denied")
+            return;
+        const restored = this.restore(false);
+        if (!restored) {
+            if (!this.persistConsent()) {
+                this.diagnostics.record({ code: "consent_persistence_failed" });
+                this.failClosedConsentState();
+                return;
+            }
+            this.consentAnchorEstablished = true;
+        }
+        this.restoreOutbox();
+    }
+    enforceCapacity() {
+        while (this.pendingEventCount() > this.maxEvents ||
+            this.pendingBytes() > this.maxBytes) {
+            const dropped = this.drafts.shift();
+            if (!dropped)
+                return;
+            this.removeRecord(draftRecordKey(this.prefix, dropped.eventKeyHash));
+            this.metrics?.increment("dropped_count");
+            this.diagnostics.record({
+                code: "queue_overflow",
+                event_fingerprint: this.diagnostics.eventFingerprint(canonicalJsonStringify(dropped.event)),
+            });
+        }
+    }
+    purgeAll() {
+        const count = this.pendingEventCount();
+        let removed = this.clear();
+        const keys = this.rawStorageKeys();
+        if (!keys) {
+            removed = false;
+        }
+        else {
+            for (const key of keys) {
+                if (key.startsWith(this.prefix) && key !== this.consentKey) {
+                    removed = this.removeRawRecord(key) && removed;
+                }
+            }
+        }
+        if (removed) {
+            this.purgePending = false;
+            if (count > 0)
+                this.metrics?.set("pending_batch_count", 0);
+        }
+        else {
+            this.purgePending = true;
+            this.diagnostics.record({ code: "consent_purge_failed" });
+        }
+        return removed;
+    }
+    clearMemory() {
+        this.drafts = [];
+        this.pending = [];
+        this.tombstones = [];
+    }
+    restore(includeOutbox = true) {
+        const consent = this.readConsent();
+        if (consent) {
+            this.consent = consent.state;
+            this.generation = consent.collectionGeneration;
+            this.legacyImportBlocked = consent.legacyImportBlocked;
+            this.consentAnchorEstablished = true;
+        }
+        if (includeOutbox)
+            this.restoreOutbox();
+        return consent !== null;
+    }
+    restoreOutbox() {
+        if (this.consent === "denied" || this.memoryOnly)
+            return;
+        const drafts = [];
+        const pending = [];
+        const tombstones = [];
+        for (const key of this.storageKeys()) {
+            if (key === this.consentKey)
+                continue;
+            const record = this.readRecord(key);
+            if (!record)
+                continue;
+            if (record.kind === "draft" &&
+                record.collectionGeneration === this.generation) {
+                drafts.push(record);
+            }
+            if ((record.kind === "pending" || record.kind === "split_plan") &&
+                record.collectionGeneration === this.generation) {
+                pending.push(record);
+            }
+            if (record.kind === "legacy_tombstone")
+                tombstones.push(record);
+        }
+        const pendingHashes = new Set(pending.flatMap((record) => record.eventKeyHashes));
+        this.drafts = drafts
+            .filter((draft) => !pendingHashes.has(draft.eventKeyHash))
+            .sort((left, right) => left.createdAt.localeCompare(right.createdAt));
+        this.pending = pending.sort((left, right) => left.ordinal - right.ordinal);
+        this.tombstones = tombstones;
+        this.nextOrdinal = Math.max(1, ...pending.map((record) => record.ordinal + 1));
+    }
+    readConsent() {
+        const raw = this.peekConsentRaw();
+        if (raw === false) {
+            this.failClosedConsentState();
+            return null;
+        }
+        if (raw === null)
+            return null;
+        const record = parseRecord(raw, this.projectHash);
+        if (record?.kind === "consent")
+            return record;
+        this.diagnostics.record({ code: "outbox_record_corrupt" });
+        this.failClosedConsentState();
+        return null;
+    }
+    peekConsentRaw() {
+        if (!this.storage)
+            return false;
+        try {
+            return this.storage.getItem(this.consentKey);
+        }
+        catch {
+            return false;
+        }
+    }
+    restoreConsentFromStorage() {
+        if (this.initialDenialPending || this.consentStateUnavailable)
+            return;
+        const record = this.readConsent();
+        if (!record) {
+            this.failClosedConsentState();
+            return;
+        }
+        if (record?.state === "denied") {
+            this.applyRemoteDenial(record.collectionGeneration);
+            return;
+        }
+        this.reconcileRemotePermittedConsent(record);
+    }
+    reconcileRemotePermittedConsent(record) {
+        if (this.legacyImportBlocked && !record.legacyImportBlocked) {
+            this.repairDeniedConsentState();
+            return;
+        }
+        if (!this.consentAnchorEstablished) {
+            this.adoptConsentRecord(record);
+            return;
+        }
+        if (record.collectionGeneration === this.generation) {
+            this.adoptConsentRecord(record);
+            return;
+        }
+        if (this.consent === "denied" || !record.legacyImportBlocked) {
+            this.repairDeniedConsentState();
+            return;
+        }
+        const purged = this.pendingEventCount();
+        this.diagnostics.rotateForConsentPurge(purged);
+        this.clearMemory();
+        this.onConsentRevoked();
+        this.adoptConsentRecord(record);
+        void this.withDeliveryLock(async () => {
+            this.purgeAll();
+        }, { restore: false });
+    }
+    adoptConsentRecord(record) {
+        this.consent = record.state;
+        this.generation = record.collectionGeneration;
+        this.legacyImportBlocked = record.legacyImportBlocked;
+        this.consentAnchorEstablished = true;
+    }
+    repairDeniedConsentState() {
+        if (this.consent !== "denied") {
+            const purged = this.pendingEventCount();
+            this.consent = "denied";
+            this.generation = createGeneration();
+            this.legacyImportBlocked = true;
+            this.diagnostics.rotateForConsentPurge(purged);
+            this.clearMemory();
+            this.onConsentRevoked();
+        }
+        const generation = this.generation;
+        void this.withDeliveryLock(async () => {
+            this.commitConsentTransition({
+                state: "denied",
+                generation,
+                expectedGeneration: null,
+                legacyImportBlocked: true,
+                purge: true,
+            });
+        }, { restore: false });
+    }
+    importLegacy() {
+        if (!this.storage)
+            return;
+        if (this.legacyImportBlocked || this.consent === "denied") {
+            if (this.readLegacyEvents() !== null) {
+                this.diagnostics.record({
+                    code: "legacy_pre_revocation_event_blocked",
+                });
+            }
+            return;
+        }
+        const events = this.readLegacyEvents();
+        if (!events)
+            return;
+        for (const event of events) {
+            const eventId = event.event_id;
+            if (typeof eventId !== "string" || eventId.length === 0) {
+                this.diagnostics.record({ code: "outbox_record_corrupt" });
+                continue;
+            }
+            const verifier = verifyHash(eventId);
+            if (this.pending.some((record) => record.events.some((stored) => stored.recordVerifierSha256 === verifier)) ||
+                this.tombstones.some((record) => record.recordVerifierSha256 === verifier)) {
+                continue;
+            }
+            if (this.tombstones.length >= LEGACY_TOMBSTONE_LIMIT) {
+                this.diagnostics.record({ code: "legacy_bridge_capacity_reached" });
+                return;
+            }
+            const existingDraft = this.drafts.find((record) => record.recordVerifierSha256 === verifier);
+            if (existingDraft && existingDraft.origin !== "legacy_v1") {
+                continue;
+            }
+            const draft = existingDraft ??
+                createDraft({
+                    event,
+                    permit: this.capturePermit(),
+                    projectHash: this.projectHash,
+                    createdAt: nowIso(),
+                    origin: "legacy_v1",
+                });
+            if (!draft) {
+                this.diagnostics.record({ code: "outbox_record_corrupt" });
+                continue;
+            }
+            if (!existingDraft) {
+                if (!this.writeRecord(draftRecordKey(this.prefix, draft.eventKeyHash), draft))
+                    return;
+                this.drafts.push(draft);
+            }
+            const tombstone = createLegacyTombstone({
+                projectHash: this.projectHash,
+                eventKeyHash: draft.eventKeyHash,
+                verifier,
+            });
+            if (!this.writeRecord(tombstoneRecordKey(this.prefix, draft.eventKeyHash), tombstone))
+                return;
+            this.tombstones.push(tombstone);
+        }
+    }
+    readLegacyEvents() {
+        try {
+            const raw = this.storage?.getItem(this.legacyKey);
+            if (!raw)
+                return null;
+            const value = JSON.parse(raw);
+            if (!Array.isArray(value)) {
+                this.diagnostics.record({ code: "outbox_record_corrupt" });
+                return null;
+            }
+            return value.filter(isBrowserSourceSignalEvent);
+        }
+        catch {
+            this.diagnostics.record({ code: "outbox_record_corrupt" });
+            return null;
+        }
+    }
+    applyRemoteDenial(generation) {
+        if (this.consent === "denied" && this.generation === generation)
+            return;
+        const purged = this.pendingEventCount();
+        this.consent = "denied";
+        this.generation = generation;
+        this.legacyImportBlocked = true;
+        this.diagnostics.rotateForConsentPurge(purged);
+        this.clearMemory();
+        this.onConsentRevoked();
+        void this.withDeliveryLock(async () => {
+            this.commitConsentTransition({
+                state: "denied",
+                generation,
+                expectedGeneration: null,
+                legacyImportBlocked: true,
+                purge: true,
+            });
+        }, { restore: false });
+    }
+    persistConsent() {
+        if (!this.storage)
+            return false;
+        const record = createConsentRecord({
+            projectHash: this.projectHash,
+            state: this.consent,
+            collectionGeneration: this.generation,
+            legacyImportBlocked: this.legacyImportBlocked,
+        });
+        try {
+            this.storage.setItem(this.consentKey, JSON.stringify(record));
+            const persisted = parseRecord(this.storage.getItem(this.consentKey) ?? "", this.projectHash);
+            return (persisted?.kind === "consent" &&
+                persisted.state === record.state &&
+                persisted.collectionGeneration === record.collectionGeneration &&
+                persisted.legacyImportBlocked === record.legacyImportBlocked);
+        }
+        catch {
+            return false;
+        }
+    }
+    writeRecord(key, record) {
+        if (!this.storage || this.memoryOnly)
+            return true;
+        if (this.durableOutboxSupported && !this.deliveryLockHeld) {
+            this.memoryOnly = true;
+            this.warnDurableUnavailable();
+            return true;
+        }
+        const existing = this.readRecord(key);
+        if (existing &&
+            existing.recordVerifierSha256 !== record.recordVerifierSha256) {
+            this.diagnostics.record({ code: "outbox_key_collision" });
+            return false;
+        }
+        try {
+            this.storage.setItem(key, JSON.stringify(record));
+            return true;
+        }
+        catch {
+            return false;
+        }
+    }
+    removeRecord(key) {
+        if (!this.storage || this.memoryOnly)
+            return true;
+        if (this.durableOutboxSupported && !this.deliveryLockHeld) {
+            this.memoryOnly = true;
+            this.warnDurableUnavailable();
+            return true;
+        }
+        try {
+            this.storage.removeItem(key);
+            return true;
+        }
+        catch {
+            this.warnDurableUnavailable();
+            return false;
+        }
+    }
+    removeDraft(draft) {
+        if (!this.removeRecord(draftRecordKey(this.prefix, draft.eventKeyHash)))
+            return false;
+        this.drafts = this.drafts.filter((item) => item !== draft);
+        return true;
+    }
+    removeClaimedDraftRecords(record) {
+        let removed = true;
+        for (const eventKeyHash of record.eventKeyHashes) {
+            removed =
+                this.removeRecord(draftRecordKey(this.prefix, eventKeyHash)) && removed;
+        }
+        return removed;
+    }
+    readRecord(key) {
+        if (!this.storage || this.memoryOnly)
+            return null;
+        let raw;
+        try {
+            raw = this.storage.getItem(key);
+        }
+        catch {
+            this.memoryOnly = true;
+            this.warnDurableUnavailable();
+            return null;
+        }
+        if (!raw)
+            return null;
+        const record = parseRecord(raw, this.projectHash);
+        if (!record) {
+            this.diagnostics.record({ code: "outbox_record_corrupt" });
+        }
+        return record;
+    }
+    failClosedConsentState() {
+        const wasUnavailable = this.consentStateUnavailable;
+        const purged = this.pendingEventCount();
+        this.consentStateUnavailable = true;
+        this.consent = "denied";
+        this.generation = createGeneration();
+        this.legacyImportBlocked = true;
+        this.consentAnchorEstablished = false;
+        this.purgePending = true;
+        if (!wasUnavailable)
+            this.diagnostics.rotateForConsentPurge(purged);
+        this.clearMemory();
+        this.onConsentRevoked();
+        if (!wasUnavailable) {
+            this.diagnostics.record({ code: "consent_state_unavailable" });
+        }
+    }
+    storageKeys() {
+        if (!this.storage || this.memoryOnly)
+            return [];
+        return this.rawStorageKeys() ?? [];
+    }
+    rawStorageKeys() {
+        if (!this.storage)
+            return null;
+        try {
+            return Array.from({ length: this.storage.length }, (_, index) => this.storage?.key(index)).filter((key) => Boolean(key?.startsWith(this.prefix)));
+        }
+        catch {
+            this.memoryOnly = true;
+            this.warnDurableUnavailable();
+            return null;
+        }
+    }
+    removeRawRecord(key) {
+        if (!this.storage)
+            return false;
+        try {
+            this.storage.removeItem(key);
+            return true;
+        }
+        catch {
+            this.warnDurableUnavailable();
+            return false;
+        }
+    }
+    warnDurableUnavailable() {
+        if (this.durableWarningRecorded)
+            return;
+        this.durableWarningRecorded = true;
+        this.diagnostics.record({ code: "durable_outbox_unavailable" });
+    }
+}