@bayonai/offline 0.7.0 → 0.9.0

package/CHANGELOG.md

@@ -1,6 +1,43 @@
 # Changelog
 
-## 0.7.0 - Unreleased
+## 0.9.0 - 2026-09-26
+
+- Added independent read-cache freshness and retention windows with explicit
+  `fresh`, `stale`, and `miss` outcomes and selectable refresh-failure behavior.
+- Added retained fallback and stale in-flight response protection to forced
+  `loadReadCacheResource` refreshes.
+- Added payload-free read-cache outcome callbacks for host-owned telemetry.
+- Preserved existing `maxAgeMs` behavior for callers that do not opt into the
+  new policy. Forced refreshes retain fallback data while invalidating older
+  in-flight cache writes.
+- Isolated pending-write listing and clearing by `keyPrefix` when logical
+  queues share one physical object store.
+- Fixed NodeNext declaration resolution and supplied matching declarations for
+  both ESM and CommonJS consumers.
+- Restored offline retry-control text when a reload attempt throws.
+
+## 0.8.0 - 2026-09-25
+
+- Added authoritative-result reconciliation to `createDurableCommandStore`,
+  including rebasing remaining optimistic commands without a transient revert.
+- Exposed stable durable operation IDs to remote executors for idempotent
+  command handling and prevented older refreshes from replacing confirmations.
+- Propagated injected clocks through ordered replay so deferred-command timing
+  stays deterministic in hosts and tests.
+- Added a host-owned retry policy so terminal failures remain inspectable
+  without replaying or blocking later commands, while connectivity failures
+  retain their optimistic projection and continue through ordered recovery.
+- Made IndexedDB mutation failures truthful: unavailable, rejected, and
+  cancelled timed-out writes now reject with `OfflineStorageError` instead of
+  reporting false durability.
+- Prevented delayed database opens from mutating after timeout, stale store
+  listings from replacing newer command state, and listener failures from
+  interrupting command dispatch.
+- Preserved retryable optimistic projections while later commands enter the
+  queue, added collision-resistant fallback IDs where Web Crypto UUIDs are
+  unavailable, and restored the package's 100% coverage release gate.
+
+## 0.7.0 - 2026-09-16
 
 - Added `createDurableCommandStore`, a framework-neutral store that projects
   accepted commands immediately while persisting them before remote execution.

package/README.md

@@ -25,8 +25,15 @@ import {
   createReadCacheKey,
   loadReadCacheResource,
   pruneReadCache,
+  type ReadCachePolicy,
 } from "@bayonai/offline";
 
+const policy: ReadCachePolicy = {
+  freshForMs: 30_000,
+  retainForMs: 7 * 24 * 60 * 60_000,
+  refreshFailure: "use-retained",
+};
+
 const cache = createBrowserReadCache({
   databaseName: "my-app:v1",
   storeName: "read-cache",
@@ -43,13 +50,41 @@ const projects = await loadReadCacheResource({
   cache,
   key,
   loadFresh: () => fetchProjects(),
-  maxAgeMs: 30_000,
-  onUpdate: ({ data, fromCache }) => {
-    renderProjects(data, { fromCache });
+  onOutcome: (outcome) => telemetry.record("offline-read", { outcome }),
+  policy,
+  onUpdate: ({ data, status, fromCache }) => {
+    renderProjects(data, { fromCache, status });
   },
 });
 ```
 
+`freshForMs` controls how long a cached value can avoid a remote read.
+`retainForMs` independently controls how long it can be shown as an offline
+fallback. A stale-but-retained value is emitted immediately and revalidated;
+an expired value is not emitted and cannot mask a loader failure. The
+`status` is `fresh`, `stale`, or `miss`: a stale update is retained data while
+refreshing or after a failed refresh, and a miss is a successful loader result
+with no retained cache. Successful remote results are `fresh` when replacing
+stale data and `miss` when there was no usable retained data.
+
+`onOutcome` emits only a fixed event name (`fresh-hit`, `stale-hit`,
+`cache-miss`, `forced-refresh`, `loader-success`, or `loader-failure`). It never
+includes cache keys, user identifiers, payloads, or error messages. Callback
+exceptions are logged and isolated from the read.
+
+When refresh fails, `refreshFailure: "use-retained"` returns retained data
+with `status: "stale"` and the error; `"throw"` propagates the loader error.
+This also applies to forced refresh. Set `forceFresh: true` on
+`loadReadCacheResource` or `readThroughCache` to bypass freshness, retain
+eligible data as the failure fallback, and advance the cache generation so an
+older in-flight load cannot overwrite the refresh. `readThroughCache` returns
+the `status` field alongside its existing `fromCache`, `stale`, and `error`
+fields.
+
+For compatibility, callers that omit `policy` retain the previous `maxAgeMs`
+freshness behavior and have no age-based fallback expiry. New callers should
+use `policy`; when supplied it takes precedence over the legacy `maxAgeMs`.
+
 After a successful write, use `readThroughCache({ forceFresh: true })` when
 the next read must be server-confirmed rather than a pre-write cached or
 in-flight response. Concurrent ordinary reads for the same cache/key share one
@@ -102,6 +137,11 @@ 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.
 
+`keyPrefix` is an isolation boundary inside a shared object store. Listing,
+recovery, and `clearAll()` affect only that prefix, so independent logical
+queues may safely share the same IndexedDB database and store when their
+prefixes are distinct.
+
 For a browser application that wants durable, silent recovery, mount the
 headless controller once for the active account or workspace:
 
@@ -202,8 +242,12 @@ package never imports an application model, database SDK, or framework.
 const commands = createDurableCommandStore({
   initialState: workspace,
   load: (scope) => workspaceApi.load(scope),
-  execute: (command) => workspaceApi.execute(command),
+  execute: (command, { operationId }) =>
+    workspaceApi.execute(command, { operationId }),
   project: (state, pending) => projectWorkspace(state, pending),
+  reconcile: (state, command, result) =>
+    reconcileWorkspace(state, command, result),
+  shouldRetry: (category) => category === "connectivity",
   store,
 });
 
@@ -221,6 +265,31 @@ 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.
 
+Browser pending-write mutations reject with `OfflineStorageError` when
+IndexedDB is unavailable, rejects an operation, or cancels a timed-out
+transaction. This is intentional: successful queue acceptance always means
+the command was durably stored. Read-cache access remains best-effort, and a
+fresh remote result is still returned when optional cache invalidation or
+persistence fails.
+
+The executor receives the durable `operationId` on every attempt so the remote
+handler can use it as an idempotency key. When execution succeeds, `reconcile`
+folds the authoritative result into base state before the command is removed;
+any later optimistic commands are projected over that confirmed state. A read
+that started before this confirmation cannot replace it when it finishes.
+Reconciliation is deliberately a host-owned, synchronous state transformation.
+If it throws, the package logs the local bug and removes the already-confirmed
+command rather than risking a duplicate remote effect.
+
+`classifyError` and `shouldRetry` let a host distinguish recoverable failures
+from terminal validation, authentication, permission, or conflict outcomes.
+Retryable failures retain their optimistic projection while awaiting recovery.
+Terminal failures roll back, stay available in `operations` for host feedback
+or dismissal, and are excluded from later recovery lanes, so they neither retry
+nor block a newer command. Because recovery survives restart, classification
+must work from the package's persisted safe error message rather than relying
+only on a non-serializable error object.
+
 Use generic record summaries when an app needs to render its own status:
 
 ```ts
@@ -277,17 +346,21 @@ opened at the same version.
 
 ```bash
 pnpm --filter @bayonai/offline test
+pnpm --filter @bayonai/offline test:coverage
 pnpm --filter @bayonai/offline run build
-pnpm --filter @bayonai/offline pack --dry-run
+pnpm --filter @bayonai/offline pack:smoke
 ```
 
 ## Publish Checklist
 
 1. Run the package tests and build.
-2. Run `pnpm --filter @bayonai/offline pack --dry-run` and confirm the tarball
+2. Run the 100% coverage gate and production dependency audit.
+3. Run `pnpm --filter @bayonai/offline pack:smoke` and confirm the tarball
    includes only `package.json`, `dist`, `dist-cjs`, `README.md`,
    `CHANGELOG.md`, and `LICENSE`.
-3. Confirm `package.json` metadata, version, repository, license, and
+4. Install the generated tarball into an isolated consumer and verify ESM,
+   CommonJS, and TypeScript declaration imports.
+5. Confirm `package.json` metadata, version, repository, license, and
    `publishConfig.access` are correct.
-4. Publish from the package directory or with the package filter after the
+6. Publish from the package directory or with the package filter after the
    workspace lockfile is current.

package/dist/browserFallbackRecovery.js

@@ -8,9 +8,11 @@ export function createBrowserOfflineFallbackRecovery({ control, environment = cr
     let active = false;
     let retrying = false;
     let pullStartY = null;
+    const touchThreshold = pullThreshold === null ? Number.POSITIVE_INFINITY : pullThreshold;
     function retry() {
         if (retrying)
             return;
+        const previousText = control.textContent;
         retrying = true;
         control.disabled = true;
         control.textContent = retryingText;
@@ -19,9 +21,12 @@ export function createBrowserOfflineFallbackRecovery({ control, environment = cr
         }
         catch (error) {
             // A failed navigation must leave the recovery action visible and usable.
-            console.error("[Bayon offline] Offline fallback reload failed.", { error });
+            console.error("[Bayon offline] Offline fallback reload failed.", {
+                error,
+            });
             retrying = false;
             control.disabled = false;
+            control.textContent = previousText;
         }
     }
     function handleTouchStart(event) {
@@ -32,7 +37,7 @@ export function createBrowserOfflineFallbackRecovery({ control, environment = cr
         const touchY = getSingleTouchY(event, "changedTouches");
         if (pullStartY !== null &&
             touchY !== null &&
-            touchY - pullStartY >= (pullThreshold ?? Number.POSITIVE_INFINITY)) {
+            touchY - pullStartY >= touchThreshold) {
             retry();
         }
         pullStartY = null;

package/dist/browserRecovery.d.ts

@@ -1,5 +1,5 @@
-import { type PendingWriteRecord, type PendingWriteStore, type PendingWriteSync, type SyncPendingWritesResult } from "./pendingWrites";
-import type { BrowserPendingWriteRecoveryCoordination } from "./browserCoordination";
+import { type PendingWriteRecord, type PendingWriteStore, type PendingWriteSync, type SyncPendingWritesResult } from "./pendingWrites.js";
+import type { BrowserPendingWriteRecoveryCoordination } from "./browserCoordination.js";
 export declare const initialPendingWriteRetryDelayMs = 2000;
 export declare const maxPendingWriteRetryDelayMs = 60000;
 export type BrowserPendingWriteRecoveryEnvironment = {

package/dist/durableCommandStore.d.ts

@@ -1,4 +1,4 @@
-import { type PendingWriteRecord, type PendingWriteStore } from "./pendingWrites";
+import { type PendingWriteRecord, type PendingWriteStore } from "./pendingWrites.js";
 export type DurableCommandErrorCategory = "auth" | "conflict" | "connectivity" | "local-storage" | "permission" | "unexpected" | "validation";
 export type DurableCommandOperation<Command> = {
     command: Command;
@@ -14,6 +14,10 @@ export type DurableCommandDispatch = {
     accepted: Promise<void>;
     operationId: string;
 };
+export type DurableCommandExecutionContext = {
+    /** Stable across retries so the remote command can be idempotent. */
+    operationId: string;
+};
 export type DurableCommandStore<State, Command, Scope> = {
     cancel: (operationId: string) => Promise<boolean>;
     close: () => void;
@@ -30,14 +34,16 @@ export type DurableCommandStore<State, Command, Scope> = {
  * 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, }: {
+export declare function createDurableCommandStore<State, Command, Scope, Result = unknown>({ canCancel, classifyError, createId, execute, initialState, load, now, project, reconcile, shouldRetry, store, }: {
     canCancel?: (command: Command, now: string) => boolean;
     classifyError?: (error: unknown) => DurableCommandErrorCategory;
     createId?: () => string;
-    execute: (command: Command) => Promise<unknown>;
+    execute: (command: Command, context: DurableCommandExecutionContext) => Promise<Result>;
     initialState: State;
     load: (scope: Scope) => Promise<State>;
     now?: () => string;
     project: (state: State, commands: readonly PendingWriteRecord<Command>[]) => State;
+    reconcile?: (state: State, command: Command, result: Result) => State;
+    shouldRetry?: (category: DurableCommandErrorCategory, command: Command) => boolean;
     store: PendingWriteStore<Command>;
 }): DurableCommandStore<State, Command, Scope>;

package/dist/durableCommandStore.js

@@ -4,24 +4,59 @@ import { createOrderedPendingWriteExecutor, } from "./pendingWrites.js";
  * 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, }) {
+export 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 = 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) {
@@ -37,32 +72,62 @@ export function createDurableCommandStore({ canCancel = () => true, classifyErro
         }, 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.", {
@@ -72,6 +137,11 @@ export function createDurableCommandStore({ canCancel = () => true, classifyErro
     });
     return {
         async cancel(operationId) {
+            if (localStorageFailures.delete(operationId)) {
+                applySnapshot(currentRecords());
+                notify();
+                return true;
+            }
             const record = await store.get(operationId);
             if (!record ||
                 record.syncStatus === "syncing" ||
@@ -86,6 +156,7 @@ export function createDurableCommandStore({ canCancel = () => true, classifyErro
         close() {
             if (deferredRecoveryTimer)
                 clearTimeout(deferredRecoveryTimer);
+            publishGeneration += 1;
             unsubscribe();
         },
         dispatch(command, options = {}) {
@@ -100,36 +171,20 @@ export function createDurableCommandStore({ canCancel = () => true, classifyErro
                 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;
             });
@@ -140,9 +195,9 @@ export function createDurableCommandStore({ canCancel = () => true, classifyErro
             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();
@@ -154,5 +209,15 @@ export function createDurableCommandStore({ canCancel = () => true, classifyErro
     };
 }
 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/idbDriver.d.ts

@@ -20,4 +20,7 @@ export type BrowserKeyValueDriverOptions = {
     operationTimeoutMs: number;
     storeName: string;
 };
+export declare class OfflineStorageError extends Error {
+    name: string;
+}
 export declare function createIdbKeyValueDriver({ databaseName, databaseVersion, indexedDB, operationTimeoutMs, storeName, }: BrowserKeyValueDriverOptions): BrowserKeyValueDriver | null;