@bayonai/offline 0.7.0 → 0.9.0

package/dist-cjs/durableCommandStore.js

@@ -7,24 +7,59 @@ const pendingWrites_1 = require("./pendingWrites");
  * durable command lifecycle. A command becomes visible immediately, but is
  * never sent remotely until IndexedDB has accepted it.
  */
-function createDurableCommandStore({ canCancel = () => true, classifyError = () => "unexpected", createId = createDurableCommandId, execute, initialState, load, now = () => new Date().toISOString(), project, store, }) {
+function createDurableCommandStore({ canCancel = () => true, classifyError = () => "unexpected", createId = createDurableCommandId, execute, initialState, load, now = () => new Date().toISOString(), project, reconcile, shouldRetry = () => true, store, }) {
     let baseState = initialState;
-    let refreshGeneration = 0;
+    let baseStateGeneration = 0;
     let savedAtMillis = 0;
+    let publishGeneration = 0;
+    let storedRecords = [];
     let deferredRecoveryTimer = null;
+    const provisionalRecords = new Map();
+    const localStorageFailures = new Map();
     let snapshot = {
         operations: [],
         state: initialState,
     };
     const listeners = new Set();
     const executor = (0, pendingWrites_1.createOrderedPendingWriteExecutor)({
+        now,
         scopeKey: "durable-command-store",
+        select: isActiveCommand,
         store,
-        sync: execute,
+        sync: async (command, { recordId }) => {
+            const result = await execute(command, { operationId: recordId });
+            // A completed remote write is newer than any read already in flight.
+            // Reconciliation is local-only: a projector bug must never retry a
+            // command whose remote effect may already have committed.
+            baseStateGeneration += 1;
+            if (reconcile) {
+                try {
+                    baseState = reconcile(baseState, command, result);
+                }
+                catch (error) {
+                    console.error("[Bayon offline] Unable to reconcile a confirmed durable command.", { error, operationId: recordId });
+                }
+            }
+        },
     });
     function notify() {
-        for (const listener of listeners)
-            listener();
+        for (const listener of listeners) {
+            try {
+                listener();
+            }
+            catch (error) {
+                console.error("[Bayon offline] Durable-command listener failed.", {
+                    error,
+                });
+            }
+        }
+    }
+    function classifyStoredError(error) {
+        return classifyError(new Error(error ?? "Unable to sync durable command."));
+    }
+    function isActiveCommand(record) {
+        return (record.syncStatus !== "failed" ||
+            shouldRetry(classifyStoredError(record.error), record.payload));
     }
     function scheduleDeferredRecovery(records) {
         if (deferredRecoveryTimer) {
@@ -40,32 +75,62 @@ function createDurableCommandStore({ canCancel = () => true, classifyError = ()
         }, null);
         if (nextDeadline === null)
             return;
-        deferredRecoveryTimer = setTimeout(() => void recover(), Math.max(0, nextDeadline - currentTime));
+        deferredRecoveryTimer = setTimeout(recoverInBackground, Math.max(0, nextDeadline - currentTime));
     }
-    async function publish() {
-        const records = await store.list();
+    function currentRecords() {
+        const records = new Map(storedRecords.map((record) => [record.id, record]));
+        for (const record of provisionalRecords.values()) {
+            records.set(record.id, record);
+        }
+        return [...records.values()].sort((left, right) => left.savedAt.localeCompare(right.savedAt) ||
+            left.id.localeCompare(right.id));
+    }
+    function applySnapshot(records) {
         snapshot = {
-            operations: records.map((record) => ({
-                command: record.payload,
-                ...(record.error
-                    ? { error: classifyError(new Error(record.error)) }
-                    : {}),
-                id: record.id,
-                status: record.syncStatus === "failed"
-                    ? "failed"
-                    : record.syncStatus === "syncing"
-                        ? "syncing"
-                        : "accepted",
-            })),
-            state: project(baseState, records.filter((record) => record.syncStatus !== "failed")),
+            operations: [
+                ...records.map((record) => ({
+                    command: record.payload,
+                    ...(record.syncStatus === "failed"
+                        ? { error: classifyStoredError(record.error) }
+                        : {}),
+                    id: record.id,
+                    status: record.syncStatus === "failed"
+                        ? "failed"
+                        : record.syncStatus === "syncing"
+                            ? "syncing"
+                            : "accepted",
+                })),
+                ...[...localStorageFailures].map(([id, command]) => ({
+                    command,
+                    error: "local-storage",
+                    id,
+                    status: "failed",
+                })),
+            ],
+            state: project(baseState, records.filter(isActiveCommand)),
         };
         scheduleDeferredRecovery(records);
+    }
+    async function publish() {
+        const generation = ++publishGeneration;
+        const records = await store.list();
+        if (generation !== publishGeneration)
+            return;
+        storedRecords = records;
+        applySnapshot(currentRecords());
         notify();
     }
     async function recover() {
         await executor.recover();
         await publish();
     }
+    function recoverInBackground() {
+        void recover().catch((error) => {
+            console.error("[Bayon offline] Unable to recover durable commands.", {
+                error,
+            });
+        });
+    }
     const unsubscribe = store.subscribe(() => {
         void publish().catch((error) => {
             console.error("[Bayon offline] Unable to publish durable commands.", {
@@ -75,6 +140,11 @@ function createDurableCommandStore({ canCancel = () => true, classifyError = ()
     });
     return {
         async cancel(operationId) {
+            if (localStorageFailures.delete(operationId)) {
+                applySnapshot(currentRecords());
+                notify();
+                return true;
+            }
             const record = await store.get(operationId);
             if (!record ||
                 record.syncStatus === "syncing" ||
@@ -89,6 +159,7 @@ function createDurableCommandStore({ canCancel = () => true, classifyError = ()
         close() {
             if (deferredRecoveryTimer)
                 clearTimeout(deferredRecoveryTimer);
+            publishGeneration += 1;
             unsubscribe();
         },
         dispatch(command, options = {}) {
@@ -103,36 +174,20 @@ function createDurableCommandStore({ canCancel = () => true, classifyError = ()
                 snapshotId: operationId,
                 syncStatus: "pending",
             };
-            // Project before storage settles so controls never wait on storage I/O.
-            snapshot = {
-                operations: [
-                    ...snapshot.operations,
-                    { command, id: operationId, status: "accepted" },
-                ],
-                state: project(baseState, [
-                    ...snapshot.operations
-                        .filter((operation) => operation.status !== "failed")
-                        .map((operation) => ({
-                        id: operation.id,
-                        payload: operation.command,
-                        savedAt: record.savedAt,
-                        snapshotId: operation.id,
-                        syncStatus: "pending",
-                    })),
-                    record,
-                ]),
-            };
+            // Product decision: provisional records remain part of the same ordered
+            // projection as persisted retryable failures while storage settles.
+            provisionalRecords.set(operationId, record);
+            localStorageFailures.delete(operationId);
+            applySnapshot(currentRecords());
             notify();
             const accepted = store.set(record).then(async () => {
+                provisionalRecords.delete(operationId);
                 await publish();
-                void recover();
+                recoverInBackground();
             }, async (error) => {
-                snapshot = {
-                    operations: snapshot.operations.map((operation) => operation.id === operationId
-                        ? { ...operation, error: "local-storage", status: "failed" }
-                        : operation),
-                    state: baseState,
-                };
+                provisionalRecords.delete(operationId);
+                localStorageFailures.set(operationId, command);
+                applySnapshot(currentRecords());
                 notify();
                 throw error;
             });
@@ -143,9 +198,9 @@ function createDurableCommandStore({ canCancel = () => true, classifyError = ()
             await recover();
         },
         async refresh(scope) {
-            const generation = ++refreshGeneration;
+            const generation = ++baseStateGeneration;
             const loaded = await load(scope);
-            if (generation !== refreshGeneration)
+            if (generation !== baseStateGeneration)
                 return;
             baseState = loaded;
             await publish();
@@ -157,5 +212,15 @@ function createDurableCommandStore({ canCancel = () => true, classifyError = ()
     };
 }
 function createDurableCommandId() {
-    return globalThis.crypto?.randomUUID?.() ?? `command-${Date.now()}`;
+    return globalThis.crypto?.randomUUID?.() ?? createFallbackDurableCommandId();
+}
+let fallbackDurableCommandSequence = 0;
+function createFallbackDurableCommandId() {
+    fallbackDurableCommandSequence += 1;
+    return [
+        "command",
+        Date.now().toString(36),
+        fallbackDurableCommandSequence.toString(36),
+        Math.random().toString(36).slice(2),
+    ].join("-");
 }

package/dist-cjs/idbDriver.d.ts

@@ -0,0 +1,26 @@
+export type BrowserKeyValueDriver = {
+    clear: () => Promise<void>;
+    close: () => Promise<void>;
+    delete: (key: string) => Promise<void>;
+    deleteIf: (key: string, predicate: KeyValuePredicate) => Promise<boolean>;
+    get: (key: string) => Promise<unknown | null>;
+    list: () => Promise<unknown[]>;
+    listEntries: () => Promise<Array<{
+        key: string;
+        value: unknown;
+    }>>;
+    set: (key: string, value: unknown) => Promise<void>;
+    setIf: (key: string, value: unknown, predicate: KeyValuePredicate) => Promise<boolean>;
+};
+export type KeyValuePredicate = (value: unknown | null) => boolean;
+export type BrowserKeyValueDriverOptions = {
+    databaseName: string;
+    databaseVersion?: number;
+    indexedDB?: IDBFactory;
+    operationTimeoutMs: number;
+    storeName: string;
+};
+export declare class OfflineStorageError extends Error {
+    name: string;
+}
+export declare function createIdbKeyValueDriver({ databaseName, databaseVersion, indexedDB, operationTimeoutMs, storeName, }: BrowserKeyValueDriverOptions): BrowserKeyValueDriver | null;

package/dist-cjs/idbDriver.js

@@ -1,7 +1,12 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.OfflineStorageError = void 0;
 exports.createIdbKeyValueDriver = createIdbKeyValueDriver;
 const idb_1 = require("idb");
+class OfflineStorageError extends Error {
+    name = "OfflineStorageError";
+}
+exports.OfflineStorageError = OfflineStorageError;
 function createIdbKeyValueDriver({ databaseName, databaseVersion = 1, indexedDB = globalThis.indexedDB, operationTimeoutMs, storeName, }) {
     if (!indexedDB) {
         return null;
@@ -12,25 +17,33 @@ function createIdbKeyValueDriver({ databaseName, databaseVersion = 1, indexedDB
         indexedDB,
         storeName,
     });
+    function runMutation(operationName, mutate) {
+        return runTransactionalStorageOperation({
+            failureMode: "throw",
+            fallback: undefined,
+            operationName,
+            storeName,
+            operation: async (setTransaction, isCancelled) => {
+                const database = await databasePromise;
+                if (isCancelled())
+                    return;
+                const transaction = database.transaction(storeName, "readwrite");
+                setTransaction(transaction);
+                await mutate(transaction.objectStore(storeName));
+                await transaction.done;
+            },
+            timeoutMs: operationTimeoutMs,
+        });
+    }
     return {
         async clear() {
-            await runTransactionalStorageOperation({
-                fallback: undefined,
-                operationName: "clear object store",
-                operation: async (setTransaction) => {
-                    const database = await databasePromise;
-                    const transaction = database.transaction(storeName, "readwrite");
-                    setTransaction(transaction);
-                    await transaction.objectStore(storeName).clear();
-                    await transaction.done;
-                },
-                timeoutMs: operationTimeoutMs,
-            });
+            await runMutation("clear object store", (objectStore) => objectStore.clear());
         },
         async close() {
             await runBrowserStorageOperation({
                 fallback: undefined,
                 operationName: "close database",
+                storeName,
                 operation: async () => {
                     const database = await databasePromise;
                     database.close();
@@ -39,18 +52,7 @@ function createIdbKeyValueDriver({ databaseName, databaseVersion = 1, indexedDB
             });
         },
         async delete(key) {
-            await runTransactionalStorageOperation({
-                fallback: undefined,
-                operationName: "delete key",
-                operation: async (setTransaction) => {
-                    const database = await databasePromise;
-                    const transaction = database.transaction(storeName, "readwrite");
-                    setTransaction(transaction);
-                    await transaction.objectStore(storeName).delete(key);
-                    await transaction.done;
-                },
-                timeoutMs: operationTimeoutMs,
-            });
+            await runMutation("delete key", (objectStore) => objectStore.delete(key));
         },
         async deleteIf(key, predicate) {
             return runConditionalStorageOperation({
@@ -71,6 +73,7 @@ function createIdbKeyValueDriver({ databaseName, databaseVersion = 1, indexedDB
             return runBrowserStorageOperation({
                 fallback: null,
                 operationName: "read key",
+                storeName,
                 operation: async () => {
                     const database = await databasePromise;
                     return (await database.get(storeName, key)) ?? null;
@@ -82,6 +85,7 @@ function createIdbKeyValueDriver({ databaseName, databaseVersion = 1, indexedDB
             return runBrowserStorageOperation({
                 fallback: [],
                 operationName: "list object store",
+                storeName,
                 operation: async () => {
                     const database = await databasePromise;
                     return database.getAll(storeName);
@@ -93,6 +97,7 @@ function createIdbKeyValueDriver({ databaseName, databaseVersion = 1, indexedDB
             return runBrowserStorageOperation({
                 fallback: [],
                 operationName: "list object-store entries",
+                storeName,
                 operation: async () => {
                     const database = await databasePromise;
                     // Keys and values must come from one transaction. Separate database
@@ -114,18 +119,7 @@ function createIdbKeyValueDriver({ databaseName, databaseVersion = 1, indexedDB
             });
         },
         async set(key, value) {
-            await runTransactionalStorageOperation({
-                fallback: undefined,
-                operationName: "write key",
-                operation: async (setTransaction) => {
-                    const database = await databasePromise;
-                    const transaction = database.transaction(storeName, "readwrite");
-                    setTransaction(transaction);
-                    await transaction.objectStore(storeName).put(value, key);
-                    await transaction.done;
-                },
-                timeoutMs: operationTimeoutMs,
-            });
+            await runMutation("write key", (objectStore) => objectStore.put(value, key));
         },
         async setIf(key, value, predicate) {
             return runConditionalStorageOperation({
@@ -158,18 +152,27 @@ async function openKeyValueDatabase({ databaseName, databaseVersion, indexedDB,
     }
     return database;
 }
-async function runBrowserStorageOperation({ cancelOnTimeout, fallback, operation, operationName, timeoutMs, }) {
+async function runBrowserStorageOperation({ cancelOnTimeout, failureMode = "fallback", fallback, operation, operationName, storeName, timeoutMs, }) {
     let timeoutId = null;
+    const startedAt = Date.now();
     try {
         return await Promise.race([
             operation(),
-            new Promise((resolve) => {
+            new Promise((resolve, reject) => {
                 timeoutId = setTimeout(() => {
-                    console.error(`IndexedDB timed out while trying to ${operationName}.`, {
+                    console.warn("[Bayon offline] IndexedDB operation timed out.", {
+                        elapsedMs: Date.now() - startedAt,
+                        operationName,
+                        storeName,
                         timeoutMs,
                     });
                     if (!cancelOnTimeout || cancelOnTimeout()) {
-                        resolve(fallback);
+                        if (failureMode === "throw") {
+                            reject(new OfflineStorageError(`IndexedDB timed out while attempting to ${operationName} in ${storeName}.`));
+                        }
+                        else {
+                            resolve(fallback);
+                        }
                     }
                 }, timeoutMs);
             }),
@@ -177,6 +180,11 @@ async function runBrowserStorageOperation({ cancelOnTimeout, fallback, operation
     }
     catch (error) {
         console.error(`IndexedDB failed to ${operationName}.`, { error });
+        if (failureMode === "throw") {
+            if (error instanceof OfflineStorageError)
+                throw error;
+            throw new OfflineStorageError(`IndexedDB failed to ${operationName} in ${storeName}.`, { cause: error });
+        }
         return fallback;
     }
     finally {
@@ -185,12 +193,14 @@ async function runBrowserStorageOperation({ cancelOnTimeout, fallback, operation
         }
     }
 }
-async function runTransactionalStorageOperation({ fallback, operation, operationName, timeoutMs, }) {
+async function runTransactionalStorageOperation({ failureMode, fallback, operation, operationName, storeName, timeoutMs, }) {
     let transaction;
     let cancelled = false;
     return runBrowserStorageOperation({
+        failureMode,
         fallback,
         operationName,
+        storeName,
         timeoutMs,
         cancelOnTimeout() {
             cancelled = true;
@@ -206,14 +216,12 @@ async function runTransactionalStorageOperation({ fallback, operation, operation
             }
         },
         operation: async () => {
-            if (cancelled)
-                return fallback;
             return operation((nextTransaction) => {
                 transaction = nextTransaction;
                 // Aborting can reject transaction.done. The operation also awaits it,
                 // but observing it here prevents a race from becoming unhandled.
                 void transaction.done.catch(() => undefined);
-            });
+            }, () => cancelled);
         },
     });
 }
@@ -221,8 +229,10 @@ async function runConditionalStorageOperation({ apply, databasePromise, operatio
     let transaction;
     let cancelled = false;
     return runBrowserStorageOperation({
+        failureMode: "throw",
         fallback: false,
         operationName,
+        storeName,
         timeoutMs,
         cancelOnTimeout() {
             cancelled = true;

package/dist-cjs/index.d.ts

@@ -0,0 +1,7 @@
+export * from "./readCache.js";
+export * from "./pendingWrites.js";
+export * from "./browserRecovery.js";
+export * from "./browserCoordination.js";
+export * from "./browserFallbackRecovery.js";
+export * from "./durableCommandStore.js";
+export { OfflineStorageError } from "./idbDriver.js";

package/dist-cjs/index.js

@@ -14,9 +14,12 @@ var __exportStar = (this && this.__exportStar) || function(m, exports) {
     for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
 };
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.OfflineStorageError = void 0;
 __exportStar(require("./readCache"), exports);
 __exportStar(require("./pendingWrites"), exports);
 __exportStar(require("./browserRecovery"), exports);
 __exportStar(require("./browserCoordination"), exports);
 __exportStar(require("./browserFallbackRecovery"), exports);
 __exportStar(require("./durableCommandStore"), exports);
+var idbDriver_1 = require("./idbDriver");
+Object.defineProperty(exports, "OfflineStorageError", { enumerable: true, get: function () { return idbDriver_1.OfflineStorageError; } });

package/dist-cjs/pendingWrites.d.ts

@@ -0,0 +1,179 @@
+import { type BrowserKeyValueDriverOptions } from "./idbDriver.js";
+export declare const pendingWriteSchemaVersion = 1;
+export declare const pendingWriteOperationTimeoutMs = 2000;
+export declare const pendingWriteSyncLeaseTimeoutMs = 60000;
+export type PendingWriteStatus = "pending" | "syncing" | "failed";
+export type PendingWriteRecord<Payload = unknown> = {
+    error?: string;
+    id: string;
+    /** Do not execute this accepted command before this ISO timestamp. */
+    notBefore?: string;
+    payload: Payload;
+    savedAt: string;
+    snapshotId: string;
+    /** Timestamp of the active remote-sync claim, absent when not owned. */
+    syncingAt?: string;
+    syncStatus: PendingWriteStatus;
+};
+export type PendingWriteRecordInput<Payload = unknown> = Omit<PendingWriteRecord<Payload>, "snapshotId"> & {
+    snapshotId?: string;
+};
+export type PendingWritePayloadNormalizer<Payload = unknown> = (payload: unknown) => Payload | null;
+export type PendingWriteDriver = {
+    clear: (key: string) => Promise<void>;
+    clearIf: (key: string, predicate: PendingWritePredicate) => Promise<boolean>;
+    clearAll?: () => Promise<void>;
+    close?: () => Promise<void>;
+    get: (key: string) => Promise<unknown | null>;
+    list: () => Promise<unknown[]>;
+    listEntries?: () => Promise<Array<{
+        key: string;
+        value: unknown;
+    }>>;
+    set: (key: string, value: unknown) => Promise<void>;
+    setIf: (key: string, value: unknown, predicate: PendingWritePredicate) => Promise<boolean>;
+};
+export type PendingWritePredicate = (value: unknown | null) => boolean;
+export type PendingWriteStoreChange<Payload = unknown> = {
+    record: PendingWriteRecord<Payload>;
+    type: "set";
+} | {
+    id: string;
+    type: "clear";
+} | {
+    type: "clearAll";
+} | {
+    record: PendingWriteRecord<Payload>;
+    type: "replace";
+};
+export type PendingWriteStoreChangeListener<Payload = unknown> = (change: PendingWriteStoreChange<Payload>) => void;
+export type PendingWriteStore<Payload = unknown> = {
+    claimIfSnapshotId: (id: string, snapshotId: string, record: PendingWriteRecord<Payload>, now: string) => Promise<boolean>;
+    clear: (id: string) => Promise<void>;
+    clearAll: () => Promise<void>;
+    clearIfSnapshotId: (id: string, snapshotId: string) => Promise<boolean>;
+    close: () => Promise<void>;
+    get: (id: string) => Promise<PendingWriteRecord<Payload> | null>;
+    list: () => Promise<Array<PendingWriteRecord<Payload>>>;
+    replaceIfSnapshotId: (id: string, snapshotId: string, record: PendingWriteRecord<Payload>) => Promise<boolean>;
+    set: (record: PendingWriteRecordInput<Payload>) => Promise<PendingWriteRecord<Payload>>;
+    /**
+     * Observes changes made through this in-memory store instance. It deliberately
+     * does not claim cross-tab/process delivery.
+     */
+    subscribe: (listener: PendingWriteStoreChangeListener<Payload>) => () => void;
+};
+export type PendingWriteStoreOptions<Payload = unknown> = {
+    keyPrefix: string;
+    normalizeLegacyRecord?: PendingWritePayloadNormalizer<PendingWriteRecordInput<Payload>>;
+    normalizePayload?: PendingWritePayloadNormalizer<Payload>;
+    schemaVersion?: number;
+};
+export type BrowserPendingWriteStoreOptions<Payload = unknown> = Partial<Pick<BrowserKeyValueDriverOptions, "databaseVersion" | "indexedDB">> & PendingWriteStoreOptions<Payload> & {
+    databaseName: string;
+    operationTimeoutMs?: number;
+    storeName: string;
+};
+export type PendingWriteKeyOptions = {
+    id: string;
+    prefix: string;
+};
+export type SyncPendingWriteResult = {
+    status: "idle";
+} | {
+    status: "synced";
+} | {
+    status: "superseded";
+} | {
+    error: string;
+    failure: unknown;
+    status: "failed";
+};
+export type SyncPendingWritesResult = {
+    attempted: number;
+    failed: number;
+    idle: number;
+    /** Records still selected after this attempt, including newer superseding writes. */
+    remaining: number;
+    superseded: number;
+    synced: number;
+};
+export type PendingWriteSyncContext = {
+    /** Stable durable-record identity; safe to use as a remote idempotency key. */
+    recordId: string;
+};
+export type PendingWriteSync<Payload, Result = unknown> = (payload: Payload, context: PendingWriteSyncContext) => Promise<Result>;
+export type RunPendingWriteResult<TResult, TQueued> = {
+    result: TResult;
+    status: "synced";
+} | {
+    queued: TQueued;
+    status: "queued";
+};
+export type PendingWriteRunOptions<TResult, TQueued> = {
+    enqueue: () => Promise<TQueued>;
+    isOnline: () => boolean;
+    shouldQueue: (error: unknown) => boolean;
+    write: () => Promise<TResult>;
+};
+/**
+ * Serializes recovery and new writes for one caller-defined scope.
+ *
+ * A queued write that cannot be replayed stays ahead of later writes. This
+ * preserves remote write order; callers retain ownership of scope selection
+ * and idempotent remote mutation semantics.
+ */
+export type OrderedPendingWriteExecutor<Payload> = {
+    recover: () => Promise<SyncPendingWritesResult>;
+    run: <TResult, TQueued>(options: PendingWriteRunOptions<TResult, TQueued>) => Promise<RunPendingWriteResult<TResult, TQueued>>;
+};
+export type PendingWriteSummary = {
+    failedCount: number;
+    pendingCount: number;
+    syncingCount: number;
+    totalCount: number;
+};
+export declare function createPendingWriteStore<Payload = unknown>(driver: PendingWriteDriver, { keyPrefix, normalizeLegacyRecord, normalizePayload, schemaVersion, }: PendingWriteStoreOptions<Payload>): PendingWriteStore<Payload>;
+export declare function createMemoryPendingWriteDriver(): PendingWriteDriver;
+export declare function createBrowserPendingWriteDriver({ databaseName, databaseVersion, indexedDB, operationTimeoutMs, storeName, }: Omit<BrowserPendingWriteStoreOptions, "keyPrefix" | "normalizePayload" | "schemaVersion">): PendingWriteDriver | null;
+export declare function createBrowserPendingWriteStore<Payload = unknown>({ databaseName, databaseVersion, indexedDB, keyPrefix, normalizeLegacyRecord, normalizePayload, operationTimeoutMs, schemaVersion, storeName, }: BrowserPendingWriteStoreOptions<Payload>): PendingWriteStore<Payload>;
+export declare function createPendingWriteKey({ id, prefix }: PendingWriteKeyOptions): string;
+export declare function createPendingWriteSnapshotId(): string;
+export declare function syncPendingWrite<Payload>({ id, now, store, sync, }: {
+    id: string;
+    now?: () => string;
+    store: PendingWriteStore<Payload>;
+    sync: PendingWriteSync<Payload>;
+}): Promise<SyncPendingWriteResult>;
+/**
+ * Replays selected writes oldest first and coalesces overlapping runs for the
+ * same store/scope. Callers own the selection predicate and idempotent remote
+ * mutation semantics.
+ */
+export declare function syncPendingWrites<Payload>({ now, scopeKey, select, stopOnFailure, store, sync, }: {
+    now?: () => string;
+    scopeKey?: string;
+    select?: (record: PendingWriteRecord<Payload>) => boolean;
+    /** Preserve caller ordering by leaving later records for a future retry. */
+    stopOnFailure?: boolean;
+    store: PendingWriteStore<Payload>;
+    sync: PendingWriteSync<Payload>;
+}): Promise<SyncPendingWritesResult>;
+/**
+ * Attempts a remote write now and persists a caller-created durable fallback
+ * only when offline or when the supplied retry classifier accepts the error.
+ */
+export declare function runPendingWrite<TResult, TQueued>({ enqueue, isOnline, shouldQueue, write, }: PendingWriteRunOptions<TResult, TQueued>): Promise<RunPendingWriteResult<TResult, TQueued>>;
+export declare function summarizePendingWrites<Payload>(records: Array<PendingWriteRecord<Payload>>): PendingWriteSummary;
+/**
+ * Creates a serial execution lane for a durable scope such as one user or
+ * workspace. Use its `recover` method for background replay and `run` for new
+ * writes so a newer remote mutation cannot overtake an older queued mutation.
+ */
+export declare function createOrderedPendingWriteExecutor<Payload>({ now, scopeKey, select, store, sync, }: {
+    now?: () => string;
+    scopeKey?: string;
+    select?: (record: PendingWriteRecord<Payload>) => boolean;
+    store: PendingWriteStore<Payload>;
+    sync: PendingWriteSync<Payload>;
+}): OrderedPendingWriteExecutor<Payload>;