@bayonai/offline 0.8.0 → 0.10.0

package/CHANGELOG.md

@@ -1,6 +1,44 @@
 # Changelog
 
-## 0.8.0 - Unreleased
+## 0.10.0 - 2026-11-03
+
+- Fixed all four audited recovery gaps: strict pending-store reads, retained async
+  refresh requests with capped rechecks, conservative transport classification,
+  and host-keyed snapshot-fenced retirement of acknowledged setter corrections.
+- Added buttonless pull-down refresh, cancellation fencing and transient database
+  reopen recovery while retaining cache read fallback and legacy aliases.
+
+- Moved the no-user-retry decision into the package-owned `RECOVERY.md` contract.
+- Added shared `getPendingChangesGuidance`, `offlineRecoveryCopy` and
+  `isTransientOfflineError` helpers for truthful background-sync guidance and
+  conservative recognition of known transient failures.
+- Added canonical fallback `reload()` semantics, normalized Reload labels and
+  a host durability veto for manual/reconnect/gesture navigation. Kept `retry()`
+  as an internal compatibility alias; failed navigation preserves the control.
+
+- Added the framework-free `assertReadBoundary` architecture-test utility for
+  host-supplied dependency graphs and exact trusted adapter boundaries.
+- Added actual IndexedDB close/reopen regression coverage for durable
+  create/update/delete commands, ordered connectivity replay, terminal rollback,
+  retained failure diagnostics, and account isolation.
+
+## 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.

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:
 
@@ -160,29 +200,55 @@ the current tab as before. A contested lease retries silently with bounded
 backoff. Remote write handlers must remain idempotent because leases do not
 cover other devices or every browser failure mode.
 
+## Recovery is application work
+
+Follow the package-owned [automatic recovery contract](RECOVERY.md). Never ask
+users to Retry/Try again or review and retry unchanged operations. Keep normal
+pending writes silent through the existing bounded background recovery owner.
+Use `getPendingChangesGuidance` with host-projected `hasReadyChanges`, `hasDrafts`,
+`hasErrors` and `isOffline` flags for shared status copy. Use
+`isTransientOfflineError` for known transport/service failures, retaining host
+validation, account scoping and idempotency policy. Unknown and explicit terminal
+errors must not become blind replay.
+
 ## Static Offline Fallback Recovery
 
-Standalone offline documents can reuse retry mechanics while keeping their
-own markup, branding, copy, and host-native connectivity event name:
+Pull-down and reconnect request a safe refresh; no refresh button is required.
 
 ```ts
 import { createBrowserOfflineFallbackRecovery } from "@bayonai/offline";
 
 const recovery = createBrowserOfflineFallbackRecovery({
-  control: document.querySelector<HTMLButtonElement>("#reload")!,
-  // Dispatch only after the host platform has validated connectivity.
+  // Read current storage health on every attempt. Never discard work to refresh.
+  canReload: async () => await hostCanProveLocalDurability(),
   retryEvent: "my-app:network-restored",
 });
-
 recovery.start();
+// On unmount:
+// recovery.stop();
 ```
 
-The controller disables the control after the first retry and changes its text
-to `Reconnecting…`; it then reloads once. It listens to browser `online`, the
-configured host event, and (by default) a 72px downward touch gesture beginning
-at the top of the page. Set `pullThreshold: null` when the host owns touch
-recovery. Static fallback documents must still bundle or inline this package
-code; a browser cannot resolve a bare npm package specifier from `public/`.
+An unsafe/rejected proof retains the same request and rechecks with capped
+backoff, so a person never needs to repeat the gesture. Only one proof and one
+timer may run at once. Stop cancels rechecks and fences late proof results.
+The default top-of-page pull threshold is 72px; `pullThreshold: null` lets a host
+own gesture recognition and call `recovery.refresh()` instead. Supply the actual
+scroll region through the environment when the fallback has a scrolling modal.
+Static documents must bundle this package code rather than use bare npm imports.
+The optional legacy `control`, `reload()` and `retry()` APIs remain compatible.
+
+### Strict pending reads and acknowledged corrections
+
+Browser pending stores throw `OfflineStorageError` on read failure or timeout;
+never interpret uncertainty as an empty queue. Cache reads remain best-effort.
+Custom pending-write drivers must throw on failed reads too. Retain last-known
+pending state while the existing browser recovery controller rechecks storage.
+
+Use `clearSupersededPendingWriteFailures({ acknowledged, store,
+getSupersessionKey, isRejected })` only after confirmed remote acknowledgment.
+Hosts map an explicit account/entity/field key for supersedable setters and null
+for effectful operations. The helper clears only older failed unclaimed matching
+snapshots through compare-and-clear; it never blindly removes all rejected work.
 
 Use `createOrderedPendingWriteExecutor` when a new write must never overtake a
 previously queued write in the same user, workspace, or other durable scope.
@@ -306,15 +372,16 @@ 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 the 100% coverage gate and production dependency audit.
-3. Run `pnpm --filter @bayonai/offline pack --dry-run` and confirm the tarball
+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`.
 4. Install the generated tarball into an isolated consumer and verify ESM,
@@ -323,3 +390,27 @@ pnpm --filter @bayonai/offline pack --dry-run
    `publishConfig.access` are correct.
 6. Publish from the package directory or with the package filter after the
    workspace lockfile is current.
+
+### Enforcing consumer read boundaries
+
+`assertReadBoundary` is a framework-free architecture-test utility. The host
+parses its actual source into a module graph and supplies provider policy:
+
+```ts
+assertReadBoundary({
+  modules: parsedRuntimeDependencies,
+  roots: featureEntryModuleIds,
+  allowedAdapters: trustedCacheAdapterModuleIds,
+  isForbidden: (id) => forbiddenReadProviders.has(id),
+});
+```
+
+Supply all reachable local runtime imports, re-exports and dynamic imports;
+reject unresolved or non-static local dependencies in the host parser. Absent
+nodes are external leaves. Exact allowed adapter IDs stop traversal; verify
+those adapters' cache-first behavior separately. Cycles terminate safely, and
+a bypass throws an error containing its dependency path. The package imports
+no TypeScript parser, Firebase SDK, or host-domain module. Bounded's real catalog
+read-family recipe lives in `src/lib/lists/catalogReadBoundary.test.ts` and works
+with its existing cache behavior tests. This locally added export requires an
+intentional future package release before registry consumers can adopt it.

package/RECOVERY.md

@@ -0,0 +1,64 @@
+# Automatic recovery is application work
+
+This is the package-owned product contract for all offline consumers, established
+2026-11-03 from the owner's Thunderlist requirement.
+
+## Observable behavior
+
+- Never ask a person to Retry, Try again, or review and retry an unchanged operation.
+  A generic error is not a reason to make the user repeat work.
+- `createBrowserPendingWriteRecovery` owns silent startup, focus, reconnect and
+  capped exponential-backoff recovery. Reuse its coordination and ordered executor;
+  never add a second replay owner, a billable job or a recurring server service.
+- `getPendingChangesGuidance` supplies common guidance without domain payloads.
+  Ready work syncs automatically; unfinished drafts need editing before submission.
+  Rejected work stays preserved. No retry button is part of pending inspection.
+- `isTransientOfflineError` recognizes known connectivity, internal-service and
+  aborted-transaction failures without importing provider SDKs. Explicit terminal
+  auth/access/validation/quota/not-found/already-exists codes override messages.
+  Unrecognized structured codes are not retried; only exact recognized transport
+  diagnostics may classify an uncoded error. Unknown failures do not authorize automatic replay. Hosts remain
+  responsible for domain classification, idempotency and authorized replay selection.
+- The static fallback controller exposes `refresh()` and owns pull-down/reconnect
+  navigation. New hosts do not render refresh buttons; `control` is an optional
+  compatibility surface. `reload()`/`retry()` remain internal aliases.
+- A host `canReload` proof may return a boolean or Promise<boolean>. Each attempt
+  must read fresh, account-scoped storage health. A veto or failed proof retains
+  the requested refresh and rechecks through one capped-backoff timer, starting
+  at two seconds and capped at 60 seconds. Stop cancels timers and fences late
+  asynchronous results. Concurrent gestures/reconnects coalesce.
+- Browser pending-store reads reject with OfflineStorageError on failed reads,
+  unavailable storage and timeouts. Empty means a successful read. Read caches
+  retain their best-effort default. Custom pending drivers must also throw on
+  uncertainty. A failed database open can be retried by a later operation.
+- `clearSupersededPendingWriteFailures` retires older rejected snapshots only
+  after acknowledgment and an exact host-supplied account/entity/field key match.
+  It skips live claims, newer records and effectful operations with null keys;
+  atomic snapshot ownership protects changes accepted during its scan.
+- Never automatically reload a live app in response to each failed mutation.
+  Reload belongs to explicit application/fallback recovery, not normal queue replay.
+- Ask for user action only to resolve a specific condition the application cannot
+  resolve itself: correct invalid input, restore access/authentication, adjust device
+  settings, or observe a documented rate-limit wait. Describe that resolution.
+
+## Compatibility and ownership
+
+`retry()` remains an internal compatibility alias for `reload()`. Technical retry
+identifiers and diagnostics are permitted; they must not become user instructions.
+Hosts still own framework components, branding, layout, operation labels, task/list
+identity and grouping, names/scopes/migrations, authentication and conflict handling.
+The package does not depend on Thunderlist, Bounded domain types, React or Firebase.
+No queue record is discarded or reclassified merely because the app reopened.
+
+## Regression coverage
+
+- `src/recoveryPolicy.test.ts`: user guidance and known transient/terminal taxonomy.
+- `src/browserFallbackRecovery.test.ts`: Reload semantics, navigation deduplication,
+  durability vetoes, failed navigation and reconnect/gesture lifecycle.
+- `src/browserRecovery.test.ts`: silent capped-backoff, reconnect, offline pause,
+  coordination and lifecycle behavior.
+- `src/pendingWrites.test.ts`, `src/durableCommandStore.persistence.test.ts`:
+  persistent intent, ownership, ordering and restart safety.
+
+- Additional regression coverage: `src/recoveryRemediation.test.ts` exercises the
+  four audited failure compositions with real IndexedDB reads and safe cleanup.

package/dist/browserFallbackRecovery.d.ts

@@ -11,22 +11,23 @@ export type OfflineFallbackRetryControl = {
     textContent: string | null;
 };
 export type BrowserOfflineFallbackRecovery = {
-    /** Attempts recovery once. Repeated calls are ignored while navigation starts. */
+    /** Requests one safe refresh; unsafe or failed proof is rechecked automatically. */
+    refresh: () => void;
+    /** Compatibility for hosts that label navigation as Reload. */
+    reload: () => void;
+    /** @deprecated Internal compatibility alias; never a user retry instruction. */
     retry: () => void;
     start: () => void;
     stop: () => void;
 };
 export type BrowserOfflineFallbackRecoveryOptions = {
-    control: OfflineFallbackRetryControl;
+    /** Optional legacy UI; new hosts use pull-down without a refresh button. */
+    control?: OfflineFallbackRetryControl;
+    canReload?: () => boolean | Promise<boolean>;
     environment?: BrowserOfflineFallbackRecoveryEnvironment;
-    /** A host-native validation callback may dispatch this event after connectivity returns. */
     retryEvent?: string;
     retryingText?: string;
-    /** Set to `null` to omit touch pull-to-retry. */
     pullThreshold?: number | null;
 };
-/**
- * Owns generic recovery mechanics for a static offline fallback. Hosts retain
- * all markup, copy, styling, and the choice of a native reconnect event.
- */
-export declare function createBrowserOfflineFallbackRecovery({ control, environment, pullThreshold, retryEvent, retryingText, }: BrowserOfflineFallbackRecoveryOptions): BrowserOfflineFallbackRecovery;
+/** Owns pull/reconnect recovery, including safe asynchronous durability proof. */
+export declare function createBrowserOfflineFallbackRecovery({ control, canReload, environment, pullThreshold, retryEvent, retryingText, }: BrowserOfflineFallbackRecoveryOptions): BrowserOfflineFallbackRecovery;

package/dist/browserFallbackRecovery.js

@@ -1,67 +1,139 @@
+import { offlineRecoveryCopy } from "./recoveryPolicy.js";
+import { initialPendingWriteRetryDelayMs, maxPendingWriteRetryDelayMs, } from "./browserRecovery.js";
 export const defaultOfflineFallbackRetryEvent = "app:network-restored";
 export const defaultOfflineFallbackPullThreshold = 72;
-/**
- * Owns generic recovery mechanics for a static offline fallback. Hosts retain
- * all markup, copy, styling, and the choice of a native reconnect event.
- */
-export function createBrowserOfflineFallbackRecovery({ control, environment = createDefaultBrowserOfflineFallbackRecoveryEnvironment(), pullThreshold = defaultOfflineFallbackPullThreshold, retryEvent = defaultOfflineFallbackRetryEvent, retryingText = "Reconnecting…", }) {
+/** Owns pull/reconnect recovery, including safe asynchronous durability proof. */
+export function createBrowserOfflineFallbackRecovery({ control, canReload, environment = createDefaultBrowserOfflineFallbackRecoveryEnvironment(), pullThreshold = defaultOfflineFallbackPullThreshold, retryEvent = defaultOfflineFallbackRetryEvent, retryingText = offlineRecoveryCopy.reloading, }) {
+    if (control)
+        control.textContent = offlineRecoveryCopy.reload;
     let active = false;
-    let retrying = false;
+    let navigating = false;
+    let checking = false;
+    let requested = false;
+    let generation = 0;
+    let timer;
+    let delay = initialPendingWriteRetryDelayMs;
     let pullStartY = null;
-    const touchThreshold = pullThreshold === null ? Number.POSITIVE_INFINITY : pullThreshold;
-    function retry() {
-        if (retrying)
+    const touchThreshold = pullThreshold === null ? Infinity : pullThreshold;
+    function clearTimer() {
+        if (timer !== undefined)
+            clearTimeout(timer);
+        timer = undefined;
+    }
+    function schedule() {
+        if (!active || !requested || timer !== undefined)
+            return;
+        timer = setTimeout(() => {
+            timer = undefined;
+            attempt();
+        }, delay);
+        delay = Math.min(delay * 2, maxPendingWriteRetryDelayMs);
+    }
+    function failed(error) {
+        console.error("[Bayon offline] Offline fallback refresh could not complete; local work retained.", { error });
+        navigating = false;
+        if (control) {
+            control.disabled = false;
+            control.textContent = offlineRecoveryCopy.reload;
+        }
+        schedule();
+    }
+    function complete(safe, currentGeneration) {
+        if (currentGeneration !== generation)
+            return;
+        checking = false;
+        if (!safe) {
+            schedule();
             return;
-        retrying = true;
-        control.disabled = true;
-        control.textContent = retryingText;
+        }
+        clearTimer();
+        navigating = true;
+        if (control) {
+            control.disabled = true;
+            control.textContent = retryingText;
+        }
         try {
             environment.reload();
+            requested = false;
         }
         catch (error) {
-            // A failed navigation must leave the recovery action visible and usable.
-            console.error("[Bayon offline] Offline fallback reload failed.", {
-                error,
-            });
-            retrying = false;
-            control.disabled = false;
+            failed(error);
         }
     }
+    function attempt() {
+        if (!requested || checking || navigating)
+            return;
+        checking = true;
+        const currentGeneration = generation;
+        try {
+            const proof = canReload ? canReload() : true;
+            if (typeof proof === "boolean")
+                complete(proof, currentGeneration);
+            else
+                void proof.then((safe) => complete(safe, currentGeneration), (error) => {
+                    if (currentGeneration !== generation)
+                        return;
+                    checking = false;
+                    failed(error);
+                });
+        }
+        catch (error) {
+            checking = false;
+            failed(error);
+        }
+    }
+    function refresh() {
+        requested = true;
+        clearTimer();
+        delay = initialPendingWriteRetryDelayMs;
+        attempt();
+    }
     function handleTouchStart(event) {
-        const touchY = getSingleTouchY(event, "touches");
-        pullStartY = environment.getScrollY() === 0 ? touchY : null;
+        pullStartY =
+            environment.getScrollY() === 0 ? getSingleTouchY(event, "touches") : null;
     }
     function handleTouchEnd(event) {
         const touchY = getSingleTouchY(event, "changedTouches");
         if (pullStartY !== null &&
             touchY !== null &&
-            touchY - pullStartY >= touchThreshold) {
-            retry();
-        }
+            touchY - pullStartY >= touchThreshold)
+            refresh();
+        pullStartY = null;
+    }
+    function handleTouchCancel() {
         pullStartY = null;
     }
     return {
-        retry,
+        refresh,
+        reload: refresh,
+        retry: refresh,
         start() {
             if (active)
                 return;
             active = true;
-            environment.addEventListener("online", retry);
-            environment.addEventListener(retryEvent, retry);
+            environment.addEventListener("online", refresh);
+            environment.addEventListener(retryEvent, refresh);
             if (pullThreshold !== null) {
                 environment.addEventListener("touchstart", handleTouchStart);
                 environment.addEventListener("touchend", handleTouchEnd);
+                environment.addEventListener("touchcancel", handleTouchCancel);
             }
         },
         stop() {
+            // Fence a proof completing after unmount, including manual pre-start calls.
+            generation++;
+            requested = false;
+            checking = false;
+            clearTimer();
             if (!active)
                 return;
             active = false;
-            environment.removeEventListener("online", retry);
-            environment.removeEventListener(retryEvent, retry);
+            environment.removeEventListener("online", refresh);
+            environment.removeEventListener(retryEvent, refresh);
             if (pullThreshold !== null) {
                 environment.removeEventListener("touchstart", handleTouchStart);
                 environment.removeEventListener("touchend", handleTouchEnd);
+                environment.removeEventListener("touchcancel", handleTouchCancel);
             }
             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;

package/dist/idbDriver.d.ts

@@ -18,9 +18,11 @@ export type BrowserKeyValueDriverOptions = {
     databaseVersion?: number;
     indexedDB?: IDBFactory;
     operationTimeoutMs: number;
+    /** Queue reads must throw; read caches may retain best-effort fallback. */
+    readFailureMode?: "fallback" | "throw";
     storeName: string;
 };
 export declare class OfflineStorageError extends Error {
     name: string;
 }
-export declare function createIdbKeyValueDriver({ databaseName, databaseVersion, indexedDB, operationTimeoutMs, storeName, }: BrowserKeyValueDriverOptions): BrowserKeyValueDriver | null;
+export declare function createIdbKeyValueDriver({ databaseName, databaseVersion, indexedDB, operationTimeoutMs, readFailureMode, storeName, }: BrowserKeyValueDriverOptions): BrowserKeyValueDriver | null;

package/dist/idbDriver.js

@@ -2,16 +2,28 @@ import { wrap, } from "idb";
 export class OfflineStorageError extends Error {
     name = "OfflineStorageError";
 }
-export function createIdbKeyValueDriver({ databaseName, databaseVersion = 1, indexedDB = globalThis.indexedDB, operationTimeoutMs, storeName, }) {
+export function createIdbKeyValueDriver({ databaseName, databaseVersion = 1, indexedDB = globalThis.indexedDB, operationTimeoutMs, readFailureMode = "fallback", storeName, }) {
     if (!indexedDB) {
         return null;
     }
-    const databasePromise = openKeyValueDatabase({
-        databaseName,
-        databaseVersion,
-        indexedDB,
-        storeName,
-    });
+    let databasePromise = null;
+    function getDatabase() {
+        if (!databasePromise) {
+            const attempt = openKeyValueDatabase({
+                databaseName,
+                databaseVersion,
+                indexedDB: indexedDB,
+                storeName,
+            });
+            databasePromise = attempt;
+            // A transient failed open must not poison every later recovery read.
+            void attempt.catch(() => {
+                databasePromise = null;
+            });
+        }
+        return databasePromise;
+    }
+    getDatabase();
     function runMutation(operationName, mutate) {
         return runTransactionalStorageOperation({
             failureMode: "throw",
@@ -19,7 +31,7 @@ export function createIdbKeyValueDriver({ databaseName, databaseVersion = 1, ind
             operationName,
             storeName,
             operation: async (setTransaction, isCancelled) => {
-                const database = await databasePromise;
+                const database = await getDatabase();
                 if (isCancelled())
                     return;
                 const transaction = database.transaction(storeName, "readwrite");
@@ -40,7 +52,7 @@ export function createIdbKeyValueDriver({ databaseName, databaseVersion = 1, ind
                 operationName: "close database",
                 storeName,
                 operation: async () => {
-                    const database = await databasePromise;
+                    const database = await getDatabase();
                     database.close();
                 },
                 timeoutMs: operationTimeoutMs,
@@ -51,7 +63,7 @@ export function createIdbKeyValueDriver({ databaseName, databaseVersion = 1, ind
         },
         async deleteIf(key, predicate) {
             return runConditionalStorageOperation({
-                databasePromise,
+                databasePromise: getDatabase(),
                 operationName: "conditionally delete key",
                 storeName,
                 timeoutMs: operationTimeoutMs,
@@ -66,11 +78,12 @@ export function createIdbKeyValueDriver({ databaseName, databaseVersion = 1, ind
         },
         async get(key) {
             return runBrowserStorageOperation({
+                failureMode: readFailureMode,
                 fallback: null,
                 operationName: "read key",
                 storeName,
                 operation: async () => {
-                    const database = await databasePromise;
+                    const database = await getDatabase();
                     return (await database.get(storeName, key)) ?? null;
                 },
                 timeoutMs: operationTimeoutMs,
@@ -78,11 +91,12 @@ export function createIdbKeyValueDriver({ databaseName, databaseVersion = 1, ind
         },
         async list() {
             return runBrowserStorageOperation({
+                failureMode: readFailureMode,
                 fallback: [],
                 operationName: "list object store",
                 storeName,
                 operation: async () => {
-                    const database = await databasePromise;
+                    const database = await getDatabase();
                     return database.getAll(storeName);
                 },
                 timeoutMs: operationTimeoutMs,
@@ -90,11 +104,12 @@ export function createIdbKeyValueDriver({ databaseName, databaseVersion = 1, ind
         },
         async listEntries() {
             return runBrowserStorageOperation({
+                failureMode: readFailureMode,
                 fallback: [],
                 operationName: "list object-store entries",
                 storeName,
                 operation: async () => {
-                    const database = await databasePromise;
+                    const database = await getDatabase();
                     // Keys and values must come from one transaction. Separate database
                     // reads could pair a key from one cross-tab storage state with a
                     // value from another, causing retention code to delete the wrong key.
@@ -118,7 +133,7 @@ export function createIdbKeyValueDriver({ databaseName, databaseVersion = 1, ind
         },
         async setIf(key, value, predicate) {
             return runConditionalStorageOperation({
-                databasePromise,
+                databasePromise: getDatabase(),
                 operationName: "conditionally replace key",
                 storeName,
                 timeoutMs: operationTimeoutMs,