@bayonai/offline 0.5.0 → 0.7.0

package/CHANGELOG.md

@@ -1,5 +1,25 @@
 # Changelog
 
+## 0.7.0 - Unreleased
+
+- Added `createDurableCommandStore`, a framework-neutral store that projects
+  accepted commands immediately while persisting them before remote execution.
+- Added durable `notBefore` deadlines to pending writes, preserving ordered
+  deferred commands across navigation and restart.
+
+## 0.6.0 - 2026-09-14
+
+- Preserved the original, non-persisted failure value on failed pending-write
+  sync results so host applications can classify errors without losing stack
+  traces or structured conflict details.
+
+## 0.5.1 - 2026-09-12
+
+- Prevented timed-out conditional IndexedDB replacements and deletions from
+  committing after the operation has already reported failure.
+- Preserved strict chronological replay when an older record has an active
+  claim by leaving it and all later records for a future ordered run.
+
 ## 0.5.0 - 2026-09-12
 
 - Added `createBrowserOfflineFallbackRecovery`, a framework-free controller

package/README.md

@@ -98,6 +98,10 @@ await syncPendingWrite({
 });
 ```
 
+Failed sync results include a safe persisted `error` string and the original
+non-persisted `failure` value. Hosts may use `failure` for structured logging or
+domain error classification; it is never written into the pending-write store.
+
 For a browser application that wants durable, silent recovery, mount the
 headless controller once for the active account or workspace:
 
@@ -187,6 +191,36 @@ the later write queued until the predecessor is delivered. This protects remote
 write order; it does not replace idempotent server-side mutation handling for
 ambiguous request outcomes.
 
+## Durable Command Store
+
+Use `createDurableCommandStore` when a host needs one client-side owner for
+base data, optimistic projection, durable commands, and remote reconciliation.
+The host supplies its domain projection and authenticated transport; this
+package never imports an application model, database SDK, or framework.
+
+```ts
+const commands = createDurableCommandStore({
+  initialState: workspace,
+  load: (scope) => workspaceApi.load(scope),
+  execute: (command) => workspaceApi.execute(command),
+  project: (state, pending) => projectWorkspace(state, pending),
+  store,
+});
+
+const { accepted, operationId } = commands.dispatch(command);
+await accepted; // locally durable; remote confirmation continues in background
+
+// A delayed command stays ordered and can be cancelled before its deadline.
+const deferred = commands.dispatch(deleteCommand, { notBefore: deadline });
+await commands.cancel(deferred.operationId);
+```
+
+`getSnapshot` and `subscribe` expose projected state and command status to any
+UI framework. `refresh` ignores older read results, `recover` replays durable
+commands in order, and `close` releases the local subscription and delayed
+deadline timer. Local-storage failure rejects `accepted`; hosts must show that
+failure instead of claiming the command will recover.
+
 Use generic record summaries when an app needs to render its own status:
 
 ```ts
@@ -202,6 +236,11 @@ Interrupted sync claims expire after one minute so recovery can resume. Records
 created before snapshot identities were introduced remain readable; they receive
 a stable compatibility identity and are upgraded when next updated.
 
+Conditional IndexedDB mutations are cancelled when their storage deadline is
+exceeded, so an operation cannot report failure and then commit later. Ordered
+replay also stops at an active older claim; it never delivers a later record
+whose remote effect could subsequently be overwritten by that predecessor.
+
 Host apps that change their pending-write payload shape can normalize current
 records while keeping domain logic outside the package:
 

package/dist/durableCommandStore.d.ts

@@ -0,0 +1,43 @@
+import { type PendingWriteRecord, type PendingWriteStore } from "./pendingWrites";
+export type DurableCommandErrorCategory = "auth" | "conflict" | "connectivity" | "local-storage" | "permission" | "unexpected" | "validation";
+export type DurableCommandOperation<Command> = {
+    command: Command;
+    error?: DurableCommandErrorCategory;
+    id: string;
+    status: "accepted" | "failed" | "syncing";
+};
+export type DurableCommandSnapshot<State, Command> = {
+    operations: DurableCommandOperation<Command>[];
+    state: State;
+};
+export type DurableCommandDispatch = {
+    accepted: Promise<void>;
+    operationId: string;
+};
+export type DurableCommandStore<State, Command, Scope> = {
+    cancel: (operationId: string) => Promise<boolean>;
+    close: () => void;
+    dispatch: (command: Command, options?: {
+        notBefore?: string;
+    }) => DurableCommandDispatch;
+    getSnapshot: () => DurableCommandSnapshot<State, Command>;
+    recover: () => Promise<void>;
+    refresh: (scope: Scope) => Promise<void>;
+    subscribe: (listener: () => void) => () => void;
+};
+/**
+ * Hosts provide domain projection and transport; this package only owns the
+ * durable command lifecycle. A command becomes visible immediately, but is
+ * never sent remotely until IndexedDB has accepted it.
+ */
+export declare function createDurableCommandStore<State, Command, Scope>({ canCancel, classifyError, createId, execute, initialState, load, now, project, store, }: {
+    canCancel?: (command: Command, now: string) => boolean;
+    classifyError?: (error: unknown) => DurableCommandErrorCategory;
+    createId?: () => string;
+    execute: (command: Command) => Promise<unknown>;
+    initialState: State;
+    load: (scope: Scope) => Promise<State>;
+    now?: () => string;
+    project: (state: State, commands: readonly PendingWriteRecord<Command>[]) => State;
+    store: PendingWriteStore<Command>;
+}): DurableCommandStore<State, Command, Scope>;

package/dist/durableCommandStore.js

@@ -0,0 +1,158 @@
+import { createOrderedPendingWriteExecutor, } from "./pendingWrites.js";
+/**
+ * Hosts provide domain projection and transport; this package only owns the
+ * durable command lifecycle. A command becomes visible immediately, but is
+ * never sent remotely until IndexedDB has accepted it.
+ */
+export function createDurableCommandStore({ canCancel = () => true, classifyError = () => "unexpected", createId = createDurableCommandId, execute, initialState, load, now = () => new Date().toISOString(), project, store, }) {
+    let baseState = initialState;
+    let refreshGeneration = 0;
+    let savedAtMillis = 0;
+    let deferredRecoveryTimer = null;
+    let snapshot = {
+        operations: [],
+        state: initialState,
+    };
+    const listeners = new Set();
+    const executor = createOrderedPendingWriteExecutor({
+        scopeKey: "durable-command-store",
+        store,
+        sync: execute,
+    });
+    function notify() {
+        for (const listener of listeners)
+            listener();
+    }
+    function scheduleDeferredRecovery(records) {
+        if (deferredRecoveryTimer) {
+            clearTimeout(deferredRecoveryTimer);
+            deferredRecoveryTimer = null;
+        }
+        const currentTime = Date.parse(now());
+        const nextDeadline = records.reduce((earliest, record) => {
+            const deadline = record.notBefore ? Date.parse(record.notBefore) : NaN;
+            if (!Number.isFinite(deadline) || deadline <= currentTime)
+                return earliest;
+            return earliest === null ? deadline : Math.min(earliest, deadline);
+        }, null);
+        if (nextDeadline === null)
+            return;
+        deferredRecoveryTimer = setTimeout(() => void recover(), Math.max(0, nextDeadline - currentTime));
+    }
+    async function publish() {
+        const records = await store.list();
+        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")),
+        };
+        scheduleDeferredRecovery(records);
+        notify();
+    }
+    async function recover() {
+        await executor.recover();
+        await publish();
+    }
+    const unsubscribe = store.subscribe(() => {
+        void publish().catch((error) => {
+            console.error("[Bayon offline] Unable to publish durable commands.", {
+                error,
+            });
+        });
+    });
+    return {
+        async cancel(operationId) {
+            const record = await store.get(operationId);
+            if (!record ||
+                record.syncStatus === "syncing" ||
+                !canCancel(record.payload, now())) {
+                return false;
+            }
+            const cancelled = await store.clearIfSnapshotId(record.id, record.snapshotId);
+            if (cancelled)
+                await publish();
+            return cancelled;
+        },
+        close() {
+            if (deferredRecoveryTimer)
+                clearTimeout(deferredRecoveryTimer);
+            unsubscribe();
+        },
+        dispatch(command, options = {}) {
+            const operationId = createId();
+            const timestamp = Math.max(Date.parse(now()), savedAtMillis + 1);
+            savedAtMillis = timestamp;
+            const record = {
+                id: operationId,
+                ...(options.notBefore ? { notBefore: options.notBefore } : {}),
+                payload: command,
+                savedAt: new Date(timestamp).toISOString(),
+                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,
+                ]),
+            };
+            notify();
+            const accepted = store.set(record).then(async () => {
+                await publish();
+                void recover();
+            }, async (error) => {
+                snapshot = {
+                    operations: snapshot.operations.map((operation) => operation.id === operationId
+                        ? { ...operation, error: "local-storage", status: "failed" }
+                        : operation),
+                    state: baseState,
+                };
+                notify();
+                throw error;
+            });
+            return { accepted, operationId };
+        },
+        getSnapshot: () => snapshot,
+        async recover() {
+            await recover();
+        },
+        async refresh(scope) {
+            const generation = ++refreshGeneration;
+            const loaded = await load(scope);
+            if (generation !== refreshGeneration)
+                return;
+            baseState = loaded;
+            await publish();
+        },
+        subscribe(listener) {
+            listeners.add(listener);
+            return () => listeners.delete(listener);
+        },
+    };
+}
+function createDurableCommandId() {
+    return globalThis.crypto?.randomUUID?.() ?? `command-${Date.now()}`;
+}

package/dist/idbDriver.js

@@ -1,4 +1,4 @@
-import { wrap } from "idb";
+import { wrap, } from "idb";
 export function createIdbKeyValueDriver({ databaseName, databaseVersion = 1, indexedDB = globalThis.indexedDB, operationTimeoutMs, storeName, }) {
     if (!indexedDB) {
         return null;
@@ -11,12 +11,15 @@ export function createIdbKeyValueDriver({ databaseName, databaseVersion = 1, ind
     });
     return {
         async clear() {
-            await runBrowserStorageOperation({
+            await runTransactionalStorageOperation({
                 fallback: undefined,
                 operationName: "clear object store",
-                operation: async () => {
+                operation: async (setTransaction) => {
                     const database = await databasePromise;
-                    await database.clear(storeName);
+                    const transaction = database.transaction(storeName, "readwrite");
+                    setTransaction(transaction);
+                    await transaction.objectStore(storeName).clear();
+                    await transaction.done;
                 },
                 timeoutMs: operationTimeoutMs,
             });
@@ -33,36 +36,32 @@ export function createIdbKeyValueDriver({ databaseName, databaseVersion = 1, ind
             });
         },
         async delete(key) {
-            await runBrowserStorageOperation({
+            await runTransactionalStorageOperation({
                 fallback: undefined,
                 operationName: "delete key",
-                operation: async () => {
+                operation: async (setTransaction) => {
                     const database = await databasePromise;
-                    await database.delete(storeName, key);
+                    const transaction = database.transaction(storeName, "readwrite");
+                    setTransaction(transaction);
+                    await transaction.objectStore(storeName).delete(key);
+                    await transaction.done;
                 },
                 timeoutMs: operationTimeoutMs,
             });
         },
         async deleteIf(key, predicate) {
-            return runBrowserStorageOperation({
-                fallback: false,
+            return runConditionalStorageOperation({
+                databasePromise,
                 operationName: "conditionally delete key",
-                operation: async () => {
-                    const database = await databasePromise;
-                    // The ownership check and deletion must share a transaction; splitting
-                    // them can delete a newer offline snapshot written by another trigger.
-                    const transaction = database.transaction(storeName, "readwrite");
-                    const objectStore = transaction.objectStore(storeName);
+                storeName,
+                timeoutMs: operationTimeoutMs,
+                apply: async (objectStore) => {
                     const current = (await objectStore.get(key)) ?? null;
-                    if (!predicate(current)) {
-                        await transaction.done;
+                    if (!predicate(current))
                         return false;
-                    }
                     await objectStore.delete(key);
-                    await transaction.done;
                     return true;
                 },
-                timeoutMs: operationTimeoutMs,
             });
         },
         async get(key) {
@@ -112,34 +111,32 @@ export function createIdbKeyValueDriver({ databaseName, databaseVersion = 1, ind
             });
         },
         async set(key, value) {
-            await runBrowserStorageOperation({
+            await runTransactionalStorageOperation({
                 fallback: undefined,
                 operationName: "write key",
-                operation: async () => {
+                operation: async (setTransaction) => {
                     const database = await databasePromise;
-                    await database.put(storeName, value, key);
+                    const transaction = database.transaction(storeName, "readwrite");
+                    setTransaction(transaction);
+                    await transaction.objectStore(storeName).put(value, key);
+                    await transaction.done;
                 },
                 timeoutMs: operationTimeoutMs,
             });
         },
         async setIf(key, value, predicate) {
-            return runBrowserStorageOperation({
-                fallback: false,
+            return runConditionalStorageOperation({
+                databasePromise,
                 operationName: "conditionally replace key",
-                operation: async () => {
-                    const database = await databasePromise;
-                    const transaction = database.transaction(storeName, "readwrite");
-                    const objectStore = transaction.objectStore(storeName);
+                storeName,
+                timeoutMs: operationTimeoutMs,
+                apply: async (objectStore) => {
                     const current = (await objectStore.get(key)) ?? null;
-                    if (!predicate(current)) {
-                        await transaction.done;
+                    if (!predicate(current))
                         return false;
-                    }
                     await objectStore.put(value, key);
-                    await transaction.done;
                     return true;
                 },
-                timeoutMs: operationTimeoutMs,
             });
         },
     };
@@ -158,7 +155,7 @@ async function openKeyValueDatabase({ databaseName, databaseVersion, indexedDB,
     }
     return database;
 }
-async function runBrowserStorageOperation({ fallback, operation, operationName, timeoutMs, }) {
+async function runBrowserStorageOperation({ cancelOnTimeout, fallback, operation, operationName, timeoutMs, }) {
     let timeoutId = null;
     try {
         return await Promise.race([
@@ -168,7 +165,9 @@ async function runBrowserStorageOperation({ fallback, operation, operationName,
                     console.error(`IndexedDB timed out while trying to ${operationName}.`, {
                         timeoutMs,
                     });
-                    resolve(fallback);
+                    if (!cancelOnTimeout || cancelOnTimeout()) {
+                        resolve(fallback);
+                    }
                 }, timeoutMs);
             }),
         ]);
@@ -183,3 +182,71 @@ async function runBrowserStorageOperation({ fallback, operation, operationName,
         }
     }
 }
+async function runTransactionalStorageOperation({ fallback, operation, operationName, timeoutMs, }) {
+    let transaction;
+    let cancelled = false;
+    return runBrowserStorageOperation({
+        fallback,
+        operationName,
+        timeoutMs,
+        cancelOnTimeout() {
+            cancelled = true;
+            if (!transaction)
+                return true;
+            try {
+                transaction.abort();
+                return true;
+            }
+            catch (error) {
+                console.warn("[Bayon offline] IndexedDB transaction already settling at timeout.", { error, operationName });
+                return false;
+            }
+        },
+        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);
+            });
+        },
+    });
+}
+async function runConditionalStorageOperation({ apply, databasePromise, operationName, storeName, timeoutMs, }) {
+    let transaction;
+    let cancelled = false;
+    return runBrowserStorageOperation({
+        fallback: false,
+        operationName,
+        timeoutMs,
+        cancelOnTimeout() {
+            cancelled = true;
+            if (!transaction)
+                return true;
+            try {
+                transaction.abort();
+                return true;
+            }
+            catch (error) {
+                // Product decision: when commit has already started, report its actual
+                // result instead of returning a false failure that can later mutate data.
+                console.warn("[Bayon offline] Conditional transaction already settling at timeout.", { error, operationName });
+                return false;
+            }
+        },
+        operation: async () => {
+            const database = await databasePromise;
+            if (cancelled)
+                return false;
+            transaction = database.transaction(storeName, "readwrite");
+            // Aborting can reject both a request and transaction.done. Observe the
+            // latter immediately so cancellation never creates an unhandled rejection.
+            void transaction.done.catch(() => undefined);
+            const result = await apply(transaction.objectStore(storeName));
+            await transaction.done;
+            return result;
+        },
+    });
+}

package/dist/index.d.ts

@@ -3,3 +3,4 @@ export * from "./pendingWrites";
 export * from "./browserRecovery";
 export * from "./browserCoordination";
 export * from "./browserFallbackRecovery";
+export * from "./durableCommandStore";

package/dist/index.js

@@ -3,3 +3,4 @@ export * from "./pendingWrites.js";
 export * from "./browserRecovery.js";
 export * from "./browserCoordination.js";
 export * from "./browserFallbackRecovery.js";
+export * from "./durableCommandStore.js";

package/dist/pendingWrites.d.ts

@@ -6,6 +6,8 @@ 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;
@@ -80,6 +82,7 @@ export type SyncPendingWriteResult = {
     status: "superseded";
 } | {
     error: string;
+    failure: unknown;
     status: "failed";
 };
 export type SyncPendingWritesResult = {

package/dist/pendingWrites.js

@@ -161,6 +161,12 @@ export async function syncPendingWrite({ id, now = () => new Date().toISOString(
     if (!pending) {
         return { status: "idle" };
     }
+    // A delayed command remains in its ordered lane until its grace period has
+    // elapsed. This makes cancellation survive UI unmounts and app restarts.
+    if (pending.notBefore &&
+        Date.parse(pending.notBefore) > Date.parse(now())) {
+        return { status: "idle" };
+    }
     const claimedSnapshotId = createPendingWriteSnapshotId();
     const claimed = await store.claimIfSnapshotId(id, pending.snapshotId, {
         ...pending,
@@ -190,7 +196,7 @@ export async function syncPendingWrite({ id, now = () => new Date().toISOString(
             store,
         });
         return markedFailed
-            ? { error: message, status: "failed" }
+            ? { error: message, failure: error, status: "failed" }
             : { status: "superseded" };
     }
     return (await store.clearIfSnapshotId(id, claimedSnapshotId))
@@ -277,7 +283,12 @@ async function performPendingWriteSync({ select, stopOnFailure, store, sync, })
         });
         summary.attempted += 1;
         summary[result.status] += 1;
-        if (stopOnFailure && result.status === "failed") {
+        // Product decision: a superseded result can represent an older live claim.
+        // Preserve strict ordering by leaving every later record for a future run.
+        if (stopOnFailure &&
+            (result.status === "failed" ||
+                result.status === "idle" ||
+                result.status === "superseded")) {
             break;
         }
     }
@@ -399,6 +410,9 @@ function normalizePendingWriteRecord(record, normalizePayload) {
     return {
         ...(typeof record.error === "string" ? { error: record.error } : {}),
         id: record.id,
+        ...(typeof record.notBefore === "string"
+            ? { notBefore: record.notBefore }
+            : {}),
         payload,
         savedAt: record.savedAt,
         snapshotId: record.snapshotId ?? createLegacyPendingWriteSnapshotId(record),
@@ -427,6 +441,7 @@ function isPendingWriteRecord(value) {
         typeof value === "object" &&
         "id" in value &&
         typeof value.id === "string" &&
+        (!("notBefore" in value) || typeof value.notBefore === "string") &&
         "savedAt" in value &&
         typeof value.savedAt === "string" &&
         (!("snapshotId" in value) || typeof value.snapshotId === "string") &&

package/dist-cjs/durableCommandStore.js

@@ -0,0 +1,161 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createDurableCommandStore = createDurableCommandStore;
+const pendingWrites_1 = require("./pendingWrites");
+/**
+ * Hosts provide domain projection and transport; this package only owns the
+ * 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, }) {
+    let baseState = initialState;
+    let refreshGeneration = 0;
+    let savedAtMillis = 0;
+    let deferredRecoveryTimer = null;
+    let snapshot = {
+        operations: [],
+        state: initialState,
+    };
+    const listeners = new Set();
+    const executor = (0, pendingWrites_1.createOrderedPendingWriteExecutor)({
+        scopeKey: "durable-command-store",
+        store,
+        sync: execute,
+    });
+    function notify() {
+        for (const listener of listeners)
+            listener();
+    }
+    function scheduleDeferredRecovery(records) {
+        if (deferredRecoveryTimer) {
+            clearTimeout(deferredRecoveryTimer);
+            deferredRecoveryTimer = null;
+        }
+        const currentTime = Date.parse(now());
+        const nextDeadline = records.reduce((earliest, record) => {
+            const deadline = record.notBefore ? Date.parse(record.notBefore) : NaN;
+            if (!Number.isFinite(deadline) || deadline <= currentTime)
+                return earliest;
+            return earliest === null ? deadline : Math.min(earliest, deadline);
+        }, null);
+        if (nextDeadline === null)
+            return;
+        deferredRecoveryTimer = setTimeout(() => void recover(), Math.max(0, nextDeadline - currentTime));
+    }
+    async function publish() {
+        const records = await store.list();
+        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")),
+        };
+        scheduleDeferredRecovery(records);
+        notify();
+    }
+    async function recover() {
+        await executor.recover();
+        await publish();
+    }
+    const unsubscribe = store.subscribe(() => {
+        void publish().catch((error) => {
+            console.error("[Bayon offline] Unable to publish durable commands.", {
+                error,
+            });
+        });
+    });
+    return {
+        async cancel(operationId) {
+            const record = await store.get(operationId);
+            if (!record ||
+                record.syncStatus === "syncing" ||
+                !canCancel(record.payload, now())) {
+                return false;
+            }
+            const cancelled = await store.clearIfSnapshotId(record.id, record.snapshotId);
+            if (cancelled)
+                await publish();
+            return cancelled;
+        },
+        close() {
+            if (deferredRecoveryTimer)
+                clearTimeout(deferredRecoveryTimer);
+            unsubscribe();
+        },
+        dispatch(command, options = {}) {
+            const operationId = createId();
+            const timestamp = Math.max(Date.parse(now()), savedAtMillis + 1);
+            savedAtMillis = timestamp;
+            const record = {
+                id: operationId,
+                ...(options.notBefore ? { notBefore: options.notBefore } : {}),
+                payload: command,
+                savedAt: new Date(timestamp).toISOString(),
+                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,
+                ]),
+            };
+            notify();
+            const accepted = store.set(record).then(async () => {
+                await publish();
+                void recover();
+            }, async (error) => {
+                snapshot = {
+                    operations: snapshot.operations.map((operation) => operation.id === operationId
+                        ? { ...operation, error: "local-storage", status: "failed" }
+                        : operation),
+                    state: baseState,
+                };
+                notify();
+                throw error;
+            });
+            return { accepted, operationId };
+        },
+        getSnapshot: () => snapshot,
+        async recover() {
+            await recover();
+        },
+        async refresh(scope) {
+            const generation = ++refreshGeneration;
+            const loaded = await load(scope);
+            if (generation !== refreshGeneration)
+                return;
+            baseState = loaded;
+            await publish();
+        },
+        subscribe(listener) {
+            listeners.add(listener);
+            return () => listeners.delete(listener);
+        },
+    };
+}
+function createDurableCommandId() {
+    return globalThis.crypto?.randomUUID?.() ?? `command-${Date.now()}`;
+}

package/dist-cjs/idbDriver.js

@@ -14,12 +14,15 @@ function createIdbKeyValueDriver({ databaseName, databaseVersion = 1, indexedDB
     });
     return {
         async clear() {
-            await runBrowserStorageOperation({
+            await runTransactionalStorageOperation({
                 fallback: undefined,
                 operationName: "clear object store",
-                operation: async () => {
+                operation: async (setTransaction) => {
                     const database = await databasePromise;
-                    await database.clear(storeName);
+                    const transaction = database.transaction(storeName, "readwrite");
+                    setTransaction(transaction);
+                    await transaction.objectStore(storeName).clear();
+                    await transaction.done;
                 },
                 timeoutMs: operationTimeoutMs,
             });
@@ -36,36 +39,32 @@ function createIdbKeyValueDriver({ databaseName, databaseVersion = 1, indexedDB
             });
         },
         async delete(key) {
-            await runBrowserStorageOperation({
+            await runTransactionalStorageOperation({
                 fallback: undefined,
                 operationName: "delete key",
-                operation: async () => {
+                operation: async (setTransaction) => {
                     const database = await databasePromise;
-                    await database.delete(storeName, key);
+                    const transaction = database.transaction(storeName, "readwrite");
+                    setTransaction(transaction);
+                    await transaction.objectStore(storeName).delete(key);
+                    await transaction.done;
                 },
                 timeoutMs: operationTimeoutMs,
             });
         },
         async deleteIf(key, predicate) {
-            return runBrowserStorageOperation({
-                fallback: false,
+            return runConditionalStorageOperation({
+                databasePromise,
                 operationName: "conditionally delete key",
-                operation: async () => {
-                    const database = await databasePromise;
-                    // The ownership check and deletion must share a transaction; splitting
-                    // them can delete a newer offline snapshot written by another trigger.
-                    const transaction = database.transaction(storeName, "readwrite");
-                    const objectStore = transaction.objectStore(storeName);
+                storeName,
+                timeoutMs: operationTimeoutMs,
+                apply: async (objectStore) => {
                     const current = (await objectStore.get(key)) ?? null;
-                    if (!predicate(current)) {
-                        await transaction.done;
+                    if (!predicate(current))
                         return false;
-                    }
                     await objectStore.delete(key);
-                    await transaction.done;
                     return true;
                 },
-                timeoutMs: operationTimeoutMs,
             });
         },
         async get(key) {
@@ -115,34 +114,32 @@ function createIdbKeyValueDriver({ databaseName, databaseVersion = 1, indexedDB
             });
         },
         async set(key, value) {
-            await runBrowserStorageOperation({
+            await runTransactionalStorageOperation({
                 fallback: undefined,
                 operationName: "write key",
-                operation: async () => {
+                operation: async (setTransaction) => {
                     const database = await databasePromise;
-                    await database.put(storeName, value, key);
+                    const transaction = database.transaction(storeName, "readwrite");
+                    setTransaction(transaction);
+                    await transaction.objectStore(storeName).put(value, key);
+                    await transaction.done;
                 },
                 timeoutMs: operationTimeoutMs,
             });
         },
         async setIf(key, value, predicate) {
-            return runBrowserStorageOperation({
-                fallback: false,
+            return runConditionalStorageOperation({
+                databasePromise,
                 operationName: "conditionally replace key",
-                operation: async () => {
-                    const database = await databasePromise;
-                    const transaction = database.transaction(storeName, "readwrite");
-                    const objectStore = transaction.objectStore(storeName);
+                storeName,
+                timeoutMs: operationTimeoutMs,
+                apply: async (objectStore) => {
                     const current = (await objectStore.get(key)) ?? null;
-                    if (!predicate(current)) {
-                        await transaction.done;
+                    if (!predicate(current))
                         return false;
-                    }
                     await objectStore.put(value, key);
-                    await transaction.done;
                     return true;
                 },
-                timeoutMs: operationTimeoutMs,
             });
         },
     };
@@ -161,7 +158,7 @@ async function openKeyValueDatabase({ databaseName, databaseVersion, indexedDB,
     }
     return database;
 }
-async function runBrowserStorageOperation({ fallback, operation, operationName, timeoutMs, }) {
+async function runBrowserStorageOperation({ cancelOnTimeout, fallback, operation, operationName, timeoutMs, }) {
     let timeoutId = null;
     try {
         return await Promise.race([
@@ -171,7 +168,9 @@ async function runBrowserStorageOperation({ fallback, operation, operationName,
                     console.error(`IndexedDB timed out while trying to ${operationName}.`, {
                         timeoutMs,
                     });
-                    resolve(fallback);
+                    if (!cancelOnTimeout || cancelOnTimeout()) {
+                        resolve(fallback);
+                    }
                 }, timeoutMs);
             }),
         ]);
@@ -186,3 +185,71 @@ async function runBrowserStorageOperation({ fallback, operation, operationName,
         }
     }
 }
+async function runTransactionalStorageOperation({ fallback, operation, operationName, timeoutMs, }) {
+    let transaction;
+    let cancelled = false;
+    return runBrowserStorageOperation({
+        fallback,
+        operationName,
+        timeoutMs,
+        cancelOnTimeout() {
+            cancelled = true;
+            if (!transaction)
+                return true;
+            try {
+                transaction.abort();
+                return true;
+            }
+            catch (error) {
+                console.warn("[Bayon offline] IndexedDB transaction already settling at timeout.", { error, operationName });
+                return false;
+            }
+        },
+        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);
+            });
+        },
+    });
+}
+async function runConditionalStorageOperation({ apply, databasePromise, operationName, storeName, timeoutMs, }) {
+    let transaction;
+    let cancelled = false;
+    return runBrowserStorageOperation({
+        fallback: false,
+        operationName,
+        timeoutMs,
+        cancelOnTimeout() {
+            cancelled = true;
+            if (!transaction)
+                return true;
+            try {
+                transaction.abort();
+                return true;
+            }
+            catch (error) {
+                // Product decision: when commit has already started, report its actual
+                // result instead of returning a false failure that can later mutate data.
+                console.warn("[Bayon offline] Conditional transaction already settling at timeout.", { error, operationName });
+                return false;
+            }
+        },
+        operation: async () => {
+            const database = await databasePromise;
+            if (cancelled)
+                return false;
+            transaction = database.transaction(storeName, "readwrite");
+            // Aborting can reject both a request and transaction.done. Observe the
+            // latter immediately so cancellation never creates an unhandled rejection.
+            void transaction.done.catch(() => undefined);
+            const result = await apply(transaction.objectStore(storeName));
+            await transaction.done;
+            return result;
+        },
+    });
+}

package/dist-cjs/index.js

@@ -19,3 +19,4 @@ __exportStar(require("./pendingWrites"), exports);
 __exportStar(require("./browserRecovery"), exports);
 __exportStar(require("./browserCoordination"), exports);
 __exportStar(require("./browserFallbackRecovery"), exports);
+__exportStar(require("./durableCommandStore"), exports);

package/dist-cjs/pendingWrites.js

@@ -175,6 +175,12 @@ async function syncPendingWrite({ id, now = () => new Date().toISOString(), stor
     if (!pending) {
         return { status: "idle" };
     }
+    // A delayed command remains in its ordered lane until its grace period has
+    // elapsed. This makes cancellation survive UI unmounts and app restarts.
+    if (pending.notBefore &&
+        Date.parse(pending.notBefore) > Date.parse(now())) {
+        return { status: "idle" };
+    }
     const claimedSnapshotId = createPendingWriteSnapshotId();
     const claimed = await store.claimIfSnapshotId(id, pending.snapshotId, {
         ...pending,
@@ -204,7 +210,7 @@ async function syncPendingWrite({ id, now = () => new Date().toISOString(), stor
             store,
         });
         return markedFailed
-            ? { error: message, status: "failed" }
+            ? { error: message, failure: error, status: "failed" }
             : { status: "superseded" };
     }
     return (await store.clearIfSnapshotId(id, claimedSnapshotId))
@@ -291,7 +297,12 @@ async function performPendingWriteSync({ select, stopOnFailure, store, sync, })
         });
         summary.attempted += 1;
         summary[result.status] += 1;
-        if (stopOnFailure && result.status === "failed") {
+        // Product decision: a superseded result can represent an older live claim.
+        // Preserve strict ordering by leaving every later record for a future run.
+        if (stopOnFailure &&
+            (result.status === "failed" ||
+                result.status === "idle" ||
+                result.status === "superseded")) {
             break;
         }
     }
@@ -413,6 +424,9 @@ function normalizePendingWriteRecord(record, normalizePayload) {
     return {
         ...(typeof record.error === "string" ? { error: record.error } : {}),
         id: record.id,
+        ...(typeof record.notBefore === "string"
+            ? { notBefore: record.notBefore }
+            : {}),
         payload,
         savedAt: record.savedAt,
         snapshotId: record.snapshotId ?? createLegacyPendingWriteSnapshotId(record),
@@ -441,6 +455,7 @@ function isPendingWriteRecord(value) {
         typeof value === "object" &&
         "id" in value &&
         typeof value.id === "string" &&
+        (!("notBefore" in value) || typeof value.notBefore === "string") &&
         "savedAt" in value &&
         typeof value.savedAt === "string" &&
         (!("snapshotId" in value) || typeof value.snapshotId === "string") &&

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bayonai/offline",
-  "version": "0.5.0",
+  "version": "0.7.0",
   "description": "Reusable offline read-cache, pending-write, and silent recovery primitives.",
   "license": "MIT",
   "author": "Bayon AI",
@@ -55,6 +55,7 @@
     "idb": "^8.0.3"
   },
   "devDependencies": {
+    "fake-indexeddb": "^6.2.5",
     "typescript": "^5",
     "vitest": "^4.1.6"
   }