@genn-inc/cluebase-frontend-sdk 0.0.1

package/dist/exporter/batch.js

@@ -0,0 +1,485 @@
+import { CONSENT_DENIED_ABORT_REASON } from "../provider/constants.js";
+import { BrowserOutbox, } from "./browser-outbox.js";
+import { ownEvent } from "./browser-outbox-records.js";
+import { DiagnosticStore } from "./diagnostics.js";
+export class BatchTransport {
+    constructor(options) {
+        this.activeSendController = null;
+        this.closeDeadlineController = null;
+        this.closeDeadlineTimer = null;
+        this.closeDeadlineAt = null;
+        this.closePermitOrdinal = null;
+        this.flushDeadlineController = null;
+        this.flushDeadlineTimer = null;
+        this.flushDeadlineAt = null;
+        this.lifecycle = "open";
+        this.closeHadTerminalDisposition = false;
+        // Promise tracking the currently executing flush cycle. Awaiters that
+        // arrive while a flush is in flight await this promise so the SDK's public
+        // `flush()` resolves after token issuance and canonical ingest have
+        // completed.
+        this.activeFlushPromise = null;
+        // A public enqueue cannot await Web Locks, so it appends its durable draft
+        // mutation here. A flush snapshots and awaits this chain before acquiring
+        // the same project lock, which prevents a flush from racing an enqueue.
+        this.enqueueTail = Promise.resolve();
+        // Capture modules and OTel span export both feed source signals into this
+        // transport. The bounded ring prevents duplicate event_id rows from being
+        // sent to ingest.
+        this.seenEventIds = new Set();
+        this.enabled = options.enabled;
+        this.flushIntervalMs = Math.max(100, options.flushIntervalMs);
+        this.maxPayloadBytes = Math.max(1024, options.maxPayloadBytes);
+        this.flushThresholdBytes = Math.min(this.maxPayloadBytes, Math.max(1024, options.flushThresholdBytes ?? Math.floor(this.maxPayloadBytes * 0.8)));
+        this.client = options.client;
+        this.metrics = options.metrics ?? null;
+        this.diagnostics = options.diagnostics ?? new DiagnosticStore();
+        this.onGovernorFeedback = options.onGovernorFeedback ?? null;
+        this.outbox = new BrowserOutbox({
+            projectKey: options.projectKey ?? "unconfigured",
+            initialConsent: options.initialConsent ?? "unknown",
+            metrics: this.metrics ?? undefined,
+            diagnostics: this.diagnostics,
+            maxEvents: options.queueMaxItems ?? 5000,
+            maxBytes: options.queueMaxBytes ?? 300 * 1024,
+            onConsentRevoked: () => this.abortActiveSendForConsent(),
+            ...(options.projectKey ? {} : { storage: null }),
+        });
+        this.idleHandle = null;
+        this.flushing = false;
+        this.flushAgainAfterCurrent = false;
+        this.recordPendingBatchCount();
+    }
+    getDiagnostics() {
+        return this.diagnostics.snapshot();
+    }
+    start() {
+        if (!this.enabled) {
+            return;
+        }
+    }
+    stop() {
+        if (this.idleHandle) {
+            clearTimeout(this.idleHandle);
+            this.idleHandle = null;
+        }
+    }
+    dispose() {
+        this.stop();
+        this.outbox.close();
+    }
+    currentConsent() {
+        return this.outbox.currentConsent();
+    }
+    capturePermit() {
+        return this.outbox.capturePermit();
+    }
+    setConsent(consent) {
+        if (consent === "denied") {
+            this.abortActiveSendForConsent();
+        }
+        const transition = this.outbox.setConsent(consent);
+        void this.queueOutboxMutation(async () => {
+            await this.outbox.withDeliveryLock(async () => this.outbox.commitConsentTransition(transition), { restore: false });
+            this.recordPendingBatchCount();
+        });
+    }
+    enqueue(event, permit) {
+        if (this.lifecycle !== "open" &&
+            !(this.lifecycle === "closing" &&
+                permit !== undefined &&
+                this.closePermitOrdinal !== null &&
+                permit.captureOrdinal < this.closePermitOrdinal)) {
+            this.metrics?.increment("dropped_count");
+            return;
+        }
+        // Take ownership of the event before enqueue returns: `ownEvent` deep
+        // clones and validates it, so a caller mutating the object afterwards
+        // cannot taint what is retained and sent. Events without a usable
+        // event_id cannot be deduped or retained, so drop them here.
+        const collectionPermit = permit ?? this.outbox.capturePermit();
+        const owned = ownEvent(event, collectionPermit);
+        const eventId = event.event_id;
+        if (!owned || typeof eventId !== "string" || eventId.length === 0) {
+            this.metrics?.increment("dropped_count");
+            return;
+        }
+        void this.queueOutboxMutation(async () => {
+            // Dedup by event_id with a bounded LRU so converged capture and OTel
+            // emission cannot produce duplicate ingest rows. Registration is
+            // committed on the serialized mutation queue only after retention
+            // succeeds, so a rejected retention (capacity or stale generation)
+            // leaves the id retriable instead of silently swallowing the retry.
+            if (this.seenEventIds.has(eventId)) {
+                return;
+            }
+            const retained = await this.outbox.withDeliveryLock(async () => this.outbox.addDraft(owned.value(), owned.permit));
+            if (!retained) {
+                this.metrics?.increment("dropped_count");
+                return;
+            }
+            this.seenEventIds.add(eventId);
+            if (this.seenEventIds.size > BatchTransport.DEDUP_CAPACITY) {
+                // Drop the oldest entry to keep the set bounded. Set iteration
+                // order is insertion order in JS, so the first key is the oldest.
+                const oldest = this.seenEventIds.values().next().value;
+                if (oldest !== undefined)
+                    this.seenEventIds.delete(oldest);
+            }
+            this.recordPendingBatchCount();
+            this.scheduleFlushDeadline();
+            if (!this.enabled) {
+                void this.flush();
+                return;
+            }
+            if (this.outbox.estimatedDraftBytes((events, metadata) => this.client.measurePayloadBytes([...events], metadata), this.client.createBatchEnvelopeMetadata()) >= this.flushThresholdBytes) {
+                void this.flush();
+            }
+        });
+    }
+    scheduleFlushDeadline() {
+        if (!this.enabled) {
+            return;
+        }
+        if (this.idleHandle) {
+            return;
+        }
+        this.idleHandle = setTimeout(() => {
+            this.idleHandle = null;
+            void this.flush();
+        }, this.flushIntervalMs);
+    }
+    beginFlushDeadline() {
+        const active = this.currentDeadline();
+        if (active)
+            return active;
+        const controller = new AbortController();
+        const deadlineAt = monotonicNow() + 5000;
+        this.flushDeadlineController = controller;
+        this.flushDeadlineAt = deadlineAt;
+        this.flushDeadlineTimer = setTimeout(() => {
+            controller.abort("shutdown_deadline");
+            this.activeSendController?.abort("shutdown_deadline");
+        }, 5000);
+        return { signal: controller.signal, deadlineAt };
+    }
+    endFlushDeadline(deadline) {
+        if (!deadline || this.flushDeadlineController?.signal !== deadline.signal)
+            return;
+        if (this.flushDeadlineTimer)
+            clearTimeout(this.flushDeadlineTimer);
+        this.flushDeadlineTimer = null;
+        this.flushDeadlineController = null;
+        this.flushDeadlineAt = null;
+    }
+    async flush(deadline = this.currentDeadline()) {
+        if (this.lifecycle === "closed")
+            return;
+        // Link onto the in-flight flush so awaiters resolve after the token and
+        // ingest pipeline has actually drained.
+        if (this.flushing) {
+            this.flushAgainAfterCurrent = true;
+            if (this.activeFlushPromise) {
+                await this.activeFlushPromise;
+            }
+            return;
+        }
+        const enqueuesAtStart = this.enqueueTail;
+        await enqueuesAtStart;
+        if (this.flushing) {
+            this.flushAgainAfterCurrent = true;
+            if (this.activeFlushPromise)
+                await this.activeFlushPromise;
+            return;
+        }
+        if (this.idleHandle) {
+            clearTimeout(this.idleHandle);
+            this.idleHandle = null;
+        }
+        this.flushing = true;
+        this.activeFlushPromise = this.runFlushUntilIdle(deadline);
+        try {
+            await this.activeFlushPromise;
+        }
+        finally {
+            this.activeFlushPromise = null;
+            this.flushing = false;
+        }
+        this.diagnostics.setFlushOutcome(this.outbox.pendingEventCount() === 0 ? "clean" : "failed");
+        return;
+    }
+    async runFlushUntilIdle(deadline) {
+        while (true) {
+            // Enqueue mutations acquire the same project Web Lock as the flush
+            // cycle. Wait for mutations outside that lock; awaiting `enqueueTail`
+            // from inside `withDeliveryLock` deadlocks when a capture event arrives
+            // while the first batch is being sent.
+            const enqueuesAtCycleStart = this.enqueueTail;
+            await enqueuesAtCycleStart;
+            await this.outbox.withDeliveryLock(() => this.runFlushCycle(deadline));
+            const enqueuesAfterCycle = this.enqueueTail;
+            if (this.lifecycle !== "open" ||
+                (!this.flushAgainAfterCurrent &&
+                    enqueuesAfterCycle === enqueuesAtCycleStart)) {
+                return;
+            }
+            this.flushAgainAfterCurrent = false;
+        }
+    }
+    beginClose() {
+        if (this.lifecycle === "closed")
+            return null;
+        if (this.lifecycle === "closing" && this.closeDeadlineController) {
+            return this.closeDeadlineController.signal;
+        }
+        this.lifecycle = "closing";
+        this.closeHadTerminalDisposition = false;
+        this.diagnostics.setLifecycle("closing");
+        this.stop();
+        const controller = new AbortController();
+        this.closeDeadlineController = controller;
+        this.closeDeadlineAt = monotonicNow() + 5000;
+        this.closePermitOrdinal = this.outbox.capturePermit().captureOrdinal;
+        this.closeDeadlineTimer = setTimeout(() => {
+            controller.abort("shutdown_deadline");
+            this.activeSendController?.abort("shutdown_deadline");
+        }, 5000);
+        return controller.signal;
+    }
+    async close() {
+        if (this.lifecycle === "closed")
+            return;
+        const signal = this.beginClose();
+        if (!signal)
+            return;
+        try {
+            await this.flush();
+        }
+        finally {
+            this.clearCloseDeadline(signal);
+        }
+        if (this.outbox.pendingEventCount() > 0) {
+            this.lifecycle = "closing_failed";
+            this.diagnostics.setLifecycle("closing_failed");
+            this.diagnostics.setCloseOutcome("retryable_failure");
+            this.diagnostics.record({ code: "shutdown_failure" });
+            return;
+        }
+        this.lifecycle = "closed";
+        this.diagnostics.setLifecycle("closed");
+        this.diagnostics.setCloseOutcome(this.closeHadTerminalDisposition ? "terminal_failure" : "clean");
+    }
+    async runFlushCycle(deadline) {
+        const fence = this.outbox.prepareFence({
+            maxPayloadBytes: this.maxPayloadBytes,
+            createMetadata: () => this.client.createBatchEnvelopeMetadata(),
+            measure: (events, metadata) => this.client.measurePayloadBytes([...events], metadata),
+        });
+        if (fence.oversized > 0)
+            this.recordPendingBatchCount();
+        while (true) {
+            const batch = this.outbox.headThrough(fence.targetOrdinal);
+            if (!batch) {
+                break;
+            }
+            if (batch.events.length === 0 ||
+                batch.events.some((event) => !this.outbox.permits(event.permit))) {
+                this.outbox.removeHead(batch);
+                this.recordPendingBatchCount();
+                continue;
+            }
+            this.metrics?.increment("batch_flush_count");
+            const result = await this.sendBatchWhilePermitted(batch, deadline);
+            if (!result || this.applyDeliveryResult(batch, result) === "break")
+                break;
+        }
+    }
+    async sendBatchWhilePermitted(batch, deadline) {
+        const sendController = new AbortController();
+        const abortForClose = () => sendController.abort("shutdown_deadline");
+        if (deadline?.signal.aborted)
+            abortForClose();
+        deadline?.signal.addEventListener("abort", abortForClose, { once: true });
+        this.activeSendController = sendController;
+        let result;
+        try {
+            result = await this.client.send(batch.events.map((event) => event.value()), {
+                maxPayloadBytes: this.maxPayloadBytes,
+                metadata: batch.metadata,
+                signal: sendController.signal,
+                deadlineAt: deadline?.deadlineAt,
+            });
+        }
+        finally {
+            deadline?.signal.removeEventListener("abort", abortForClose);
+            if (this.activeSendController === sendController) {
+                this.activeSendController = null;
+            }
+        }
+        if (batch.events.some((event) => !this.outbox.permits(event.permit))) {
+            this.recordPendingBatchCount();
+            return null;
+        }
+        return result;
+    }
+    applyDeliveryResult(batch, result) {
+        if (result.governor)
+            this.onGovernorFeedback?.(result.governor);
+        return result.ok
+            ? this.applySuccessfulDelivery(batch, result)
+            : this.applyFailedDelivery(batch, result);
+    }
+    applyFailedDelivery(batch, result) {
+        if (result.retryStrategy === "split_batch") {
+            if (this.outbox.splitHead(batch, () => this.client.createBatchEnvelopeMetadata())) {
+                this.recordPendingBatchCount();
+                this.scheduleFlushDeadline();
+                return "continue";
+            }
+            this.metrics?.increment("dropped_count", batch.events.length);
+            this.metrics?.increment("oversized_event_dropped_count");
+            this.outbox.removeHead(batch);
+            this.recordPendingBatchCount();
+            return "continue";
+        }
+        if (this.shouldRetainFailedBatch(result.retryStrategy)) {
+            this.diagnostics.record({
+                code: "retry_exhausted",
+                strategy: "retry_same_batch",
+                attempt: result.attempts,
+                batch_fingerprint: this.diagnostics.batchFingerprint(batch.diagnosticCanonicalBytes),
+            });
+            this.outbox.retainHead(batch);
+            this.metrics?.increment("transport_requeue_count");
+            this.recordPendingBatchCount();
+            if (this.lifecycle === "open")
+                this.scheduleFlushDeadline();
+            return "break";
+        }
+        this.diagnostics.record({
+            code: result.retryStrategy === "drop_event"
+                ? "intentional_drop"
+                : "terminal_rejection",
+            strategy: result.retryStrategy ?? undefined,
+            count: batch.events.length,
+            batch_fingerprint: this.diagnostics.batchFingerprint(batch.diagnosticCanonicalBytes),
+        });
+        if (this.lifecycle === "closing")
+            this.closeHadTerminalDisposition = true;
+        this.metrics?.increment("dropped_count", batch.events.length);
+        this.metrics?.increment("transport_failed_count");
+        if (!this.outbox.removeHead(batch)) {
+            this.metrics?.increment("transport_requeue_count");
+            this.recordPendingBatchCount();
+            return "break";
+        }
+        this.recordPendingBatchCount();
+        return "continue";
+    }
+    applySuccessfulDelivery(batch, result) {
+        if (!this.outbox.removeHead(batch)) {
+            this.metrics?.increment("transport_requeue_count");
+            this.recordPendingBatchCount();
+            return "break";
+        }
+        if (result.partial) {
+            if (this.lifecycle === "closing")
+                this.closeHadTerminalDisposition = true;
+            this.diagnostics.record({
+                code: "intentional_drop",
+                count: result.droppedEventCount ?? 0,
+                batch_fingerprint: this.diagnostics.batchFingerprint(batch.diagnosticCanonicalBytes),
+            });
+        }
+        this.recordPendingBatchCount();
+        return "continue";
+    }
+    flushOnUnload() {
+        if (!this.client.hasUsableBrowserToken()) {
+            return;
+        }
+        this.stop();
+        void this.queueOutboxMutation(async () => {
+            await this.outbox.withDeliveryLock(async () => {
+                const fence = this.outbox.prepareFence({
+                    maxPayloadBytes: this.maxPayloadBytes,
+                    createMetadata: () => this.client.createBatchEnvelopeMetadata(),
+                    measure: (events, metadata) => this.client.measurePayloadBytes([...events], metadata),
+                });
+                this.recordPendingBatchCount();
+                const batch = this.outbox.headThrough(fence.targetOrdinal);
+                if (!batch)
+                    return;
+                const sendController = new AbortController();
+                this.activeSendController = sendController;
+                try {
+                    await this.client.send(batch.events.map((event) => event.value()), {
+                        keepalive: true,
+                        useBeacon: false,
+                        requireCachedBrowserToken: true,
+                        maxPayloadBytes: this.maxPayloadBytes,
+                        metadata: batch.metadata,
+                        signal: sendController.signal,
+                    });
+                }
+                finally {
+                    if (this.activeSendController === sendController) {
+                        this.activeSendController = null;
+                    }
+                }
+            });
+        });
+    }
+    clear() {
+        this.activeSendController?.abort();
+        this.activeSendController = null;
+        this.outbox.clearMemory();
+        void this.queueOutboxMutation(async () => {
+            await this.outbox.withDeliveryLock(async () => this.outbox.clear());
+        });
+        this.recordPendingBatchCount();
+    }
+    abortActiveSendForConsent() {
+        this.activeSendController?.abort(CONSENT_DENIED_ABORT_REASON);
+        this.activeSendController = null;
+    }
+    recordPendingBatchCount() {
+        this.metrics?.set("pending_batch_count", this.outbox.pendingEventCount());
+    }
+    clearCloseDeadline(signal) {
+        if (this.closeDeadlineController?.signal !== signal)
+            return;
+        if (this.closeDeadlineTimer) {
+            clearTimeout(this.closeDeadlineTimer);
+            this.closeDeadlineTimer = null;
+        }
+        this.closeDeadlineController = null;
+        this.closeDeadlineAt = null;
+        this.closePermitOrdinal = null;
+    }
+    currentDeadline() {
+        if (this.closeDeadlineController && this.closeDeadlineAt !== null) {
+            return {
+                signal: this.closeDeadlineController.signal,
+                deadlineAt: this.closeDeadlineAt,
+            };
+        }
+        if (this.flushDeadlineController && this.flushDeadlineAt !== null) {
+            return {
+                signal: this.flushDeadlineController.signal,
+                deadlineAt: this.flushDeadlineAt,
+            };
+        }
+        return null;
+    }
+    queueOutboxMutation(operation) {
+        const next = this.enqueueTail.then(operation, operation);
+        this.enqueueTail = next.catch(() => undefined);
+        return next;
+    }
+    shouldRetainFailedBatch(retryStrategy) {
+        return retryStrategy === null || retryStrategy === "retry_same_batch";
+    }
+}
+BatchTransport.DEDUP_CAPACITY = 1024;
+const monotonicNow = () => typeof performance !== "undefined" ? performance.now() : Date.now();

package/dist/exporter/browser-outbox-records.d.ts

@@ -0,0 +1,159 @@
+import type { BatchEnvelopeMetadata } from "./client.js";
+import type { CluebaseConsentState } from "../provider/types.js";
+import { type BrowserSourceEvent } from "./source-event.js";
+export type StorageLike = Pick<Storage, "getItem" | "setItem" | "removeItem" | "key"> & {
+    readonly length: number;
+};
+export type CollectionPermit = {
+    readonly generation: string;
+    readonly permittedAtStart: boolean;
+    readonly captureOrdinal: number;
+};
+export type OwnedBrowserEvent = {
+    readonly byteLength: number;
+    readonly permit: CollectionPermit;
+    readonly diagnosticCanonicalBytes: string;
+    value(): BrowserSourceEvent;
+};
+export type PendingBrowserBatch = {
+    readonly events: readonly OwnedBrowserEvent[];
+    readonly metadata: BatchEnvelopeMetadata;
+    readonly generation: string;
+    readonly ordinal: number;
+    readonly diagnosticCanonicalBytes: string;
+    readonly recordKey: string;
+    readonly ownerBatchId: string;
+    readonly planOrdinal: number | null;
+};
+type RecordBase = {
+    readonly storageVersion: 2;
+    readonly projectHash: string;
+    readonly createdAt: string;
+    readonly recordVerifierSha256: string | null;
+};
+export type OwnedStoredEvent = {
+    readonly eventId: string;
+    readonly eventKeyHash: string;
+    readonly recordVerifierSha256: string;
+    readonly event: BrowserSourceEvent;
+    readonly permittedAtStart: boolean;
+};
+export type DraftRecord = RecordBase & {
+    readonly kind: "draft";
+    readonly origin: "v2" | "legacy_v1";
+    readonly eventId: string;
+    readonly eventKeyHash: string;
+    readonly event: BrowserSourceEvent;
+    readonly collectionGeneration: string;
+    readonly permittedAtStart: boolean;
+    readonly checksumSha256: string;
+};
+export type PendingRecord = RecordBase & {
+    readonly kind: "pending";
+    readonly batchId: string;
+    readonly idempotencyKey: string;
+    readonly sentAt: string;
+    readonly collectionGeneration: string;
+    readonly events: readonly OwnedStoredEvent[];
+    readonly eventKeyHashes: readonly string[];
+    readonly lifetimeAttemptTotal: number;
+    readonly ordinal: number;
+    readonly checksumSha256: string;
+};
+export type SplitPlanRecord = RecordBase & {
+    readonly kind: "split_plan";
+    readonly batchId: string;
+    readonly idempotencyKey: string;
+    readonly sentAt: string;
+    readonly collectionGeneration: string;
+    readonly events: readonly OwnedStoredEvent[];
+    readonly eventKeyHashes: readonly string[];
+    readonly lifetimeAttemptTotal: number;
+    readonly ordinal: number;
+    readonly children: readonly SplitPlanChild[];
+    readonly nextOrdinal: number;
+    readonly checksumSha256: string;
+};
+export type SplitPlanChild = {
+    readonly start: number;
+    readonly end: number;
+    readonly metadata: BatchEnvelopeMetadata;
+};
+export type TombstoneRecord = RecordBase & {
+    readonly kind: "legacy_tombstone";
+    readonly eventKeyHash: string;
+    readonly importedAt: string;
+    readonly checksumSha256: string;
+};
+export type ConsentRecord = RecordBase & {
+    readonly kind: "consent";
+    readonly state: CluebaseConsentState;
+    readonly collectionGeneration: string;
+    readonly legacyImportBlocked: boolean;
+    readonly updatedAt: string;
+    readonly checksumSha256: string;
+};
+export type OutboxRecord = DraftRecord | PendingRecord | SplitPlanRecord | TombstoneRecord | ConsentRecord;
+export type PendingRecordLike = PendingRecord | SplitPlanRecord;
+type StoredWithoutChecksum = Omit<OutboxRecord, "checksumSha256">;
+export declare const UNANCHORED_COLLECTION_GENERATION = "__cluebase_unanchored_generation__";
+export declare const LEGACY_TOMBSTONE_LIMIT = 10000;
+export declare const createDraft: (input: {
+    readonly event: BrowserSourceEvent;
+    readonly permit: CollectionPermit;
+    readonly projectHash: string;
+    readonly createdAt: string;
+    readonly origin?: "v2" | "legacy_v1";
+}) => DraftRecord | null;
+export declare const createLegacyTombstone: (input: {
+    readonly projectHash: string;
+    readonly eventKeyHash: string;
+    readonly verifier: string;
+}) => TombstoneRecord;
+export declare const createConsentRecord: (input: {
+    readonly projectHash: string;
+    readonly state: CluebaseConsentState;
+    readonly collectionGeneration: string;
+    readonly legacyImportBlocked: boolean;
+}) => ConsentRecord;
+export declare const createPending: (input: {
+    readonly projectHash: string;
+    readonly metadata: BatchEnvelopeMetadata;
+    readonly drafts: readonly DraftRecord[];
+    readonly ordinal: number;
+}) => PendingRecord;
+export declare const toPendingBatch: (record: PendingRecordLike, recordKey: string, events: readonly OwnedStoredEvent[], metadata: BatchEnvelopeMetadata, planOrdinal: number | null) => PendingBrowserBatch;
+export declare const toHeadBatch: (record: PendingRecordLike, recordKey: string) => PendingBrowserBatch | null;
+export declare const splitPendingRecord: (record: PendingRecordLike, createMetadata: () => BatchEnvelopeMetadata) => SplitPlanRecord | null;
+export declare const largestFittingPrefix: (drafts: readonly DraftRecord[], maxBytes: number, metadata: BatchEnvelopeMetadata, measure: (events: readonly BrowserSourceEvent[], metadata: BatchEnvelopeMetadata) => number) => number;
+export declare const ownEvent: (event: BrowserSourceEvent, permit: CollectionPermit) => OwnedBrowserEvent | null;
+export declare const isOwnedEvent: (value: OwnedBrowserEvent | null) => value is OwnedBrowserEvent;
+export declare const recordBatchId: (batch: PendingBrowserBatch) => string;
+export declare const withChecksum: <T extends StoredWithoutChecksum>(record: T) => T & {
+    readonly checksumSha256: string;
+};
+export declare const withoutChecksum: <T extends OutboxRecord>(record: T) => Omit<T, "checksumSha256">;
+export declare const parseRecord: (raw: string, projectHash: string) => OutboxRecord | null;
+export declare const isRecord: (value: unknown) => value is Record<string, unknown>;
+export declare const sha256Hex: (value: string) => string;
+export declare const keyHash: (id: string) => string;
+export declare const verifyHash: (id: string) => string;
+export declare const nowIso: () => string;
+export declare const consentRecordKey: (prefix: string) => string;
+export declare const draftRecordKey: (prefix: string, eventKeyHash: string) => string;
+export declare const pendingRecordKey: (prefix: string, batchId: string) => string;
+export declare const tombstoneRecordKey: (prefix: string, eventKeyHash: string) => string;
+export declare const browserEventsByteLength: (events: readonly BrowserSourceEvent[]) => number;
+export declare const outboxEventCount: (drafts: readonly DraftRecord[], pending: readonly PendingRecordLike[]) => number;
+export declare const hasLegacyTombstone: (draft: DraftRecord, tombstones: readonly TombstoneRecord[]) => boolean;
+export declare const createGeneration: () => string;
+export declare const readStorage: () => StorageLike | null;
+export type LockManagerLike = {
+    request<T>(name: string, options: {
+        readonly mode: "exclusive";
+    }, callback: () => Promise<T>): Promise<T>;
+};
+export declare const readLocks: () => LockManagerLike | null;
+export declare const createConsentChannel: (projectHash: string, onDenied: (generation: string) => void) => BroadcastChannel | null;
+export declare const addStorageListener: (key: string, onChanged: () => void) => (() => void);
+export {};