@bayonai/offline 0.9.0 → 0.10.1

package/CHANGELOG.md

@@ -1,5 +1,31 @@
 # Changelog
 
+## 0.10.1 - 2026-11-04
+
+- Recognize two exact Firestore server-only cache diagnostics as transient while retaining terminal-code precedence.
+
+## 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

package/README.md

@@ -200,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.
@@ -364,3 +390,27 @@ pnpm --filter @bayonai/offline pack:smoke
    `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,67 @@
+# 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.
+
+
+Firestore server-only reads may report either exact “Failed to get documents from server.” or the exact SDK cache-retrieval guidance. These known messages classify as transient only when no structured code is present; terminal and unknown structured codes remain authoritative. Arbitrary messages containing connectivity words do not qualify.

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,69 +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;
-        const previousText = control.textContent;
-        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;
-            control.textContent = previousText;
+            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/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,

package/dist/index.d.ts

@@ -5,3 +5,6 @@ export * from "./browserCoordination.js";
 export * from "./browserFallbackRecovery.js";
 export * from "./durableCommandStore.js";
 export { OfflineStorageError } from "./idbDriver.js";
+export * from "./readBoundary.js";
+export * from "./recoveryPolicy.js";
+export * from "./pendingWriteSupersession.js";

package/dist/index.js

@@ -5,3 +5,6 @@ export * from "./browserCoordination.js";
 export * from "./browserFallbackRecovery.js";
 export * from "./durableCommandStore.js";
 export { OfflineStorageError } from "./idbDriver.js";
+export * from "./readBoundary.js";
+export * from "./recoveryPolicy.js";
+export * from "./pendingWriteSupersession.js";

package/dist/pendingWriteSupersession.d.ts

@@ -0,0 +1,11 @@
+import type { PendingWriteRecord, PendingWriteStore } from "./pendingWrites.js";
+/**
+ * After remote acknowledgment, retire only rejected snapshots superseded by an
+ * explicit host-owned account/entity/field key. Never infer keys from payloads.
+ */
+export declare function clearSupersededPendingWriteFailures<Payload>({ acknowledged, getSupersessionKey, isRejected, store, }: {
+    acknowledged: PendingWriteRecord<Payload>;
+    getSupersessionKey: (record: PendingWriteRecord<Payload>) => string | null;
+    isRejected: (record: PendingWriteRecord<Payload>) => boolean;
+    store: PendingWriteStore<Payload>;
+}): Promise<number>;

package/dist/pendingWriteSupersession.js

@@ -0,0 +1,25 @@
+/**
+ * After remote acknowledgment, retire only rejected snapshots superseded by an
+ * explicit host-owned account/entity/field key. Never infer keys from payloads.
+ */
+export async function clearSupersededPendingWriteFailures({ acknowledged, getSupersessionKey, isRejected, store, }) {
+    const key = getSupersessionKey(acknowledged);
+    if (key === null)
+        return 0;
+    let cleared = 0;
+    for (const previous of await store.list()) {
+        const older = previous.savedAt.localeCompare(acknowledged.savedAt) ||
+            previous.id.localeCompare(acknowledged.id);
+        if (previous.id === acknowledged.id ||
+            older >= 0 ||
+            previous.syncStatus !== "failed" ||
+            previous.syncingAt ||
+            !isRejected(previous) ||
+            getSupersessionKey(previous) !== key)
+            continue;
+        // Snapshot fencing protects a correction or claim accepted during the scan.
+        if (await store.clearIfSnapshotId(previous.id, previous.snapshotId))
+            cleared++;
+    }
+    return cleared;
+}

package/dist/pendingWrites.js

@@ -170,6 +170,7 @@ export function createBrowserPendingWriteDriver({ databaseName, databaseVersion,
         indexedDB,
         operationTimeoutMs,
         storeName,
+        readFailureMode: "throw",
     });
     return driver ? toPendingWriteDriver(driver) : null;
 }
@@ -409,10 +410,10 @@ function createUnavailablePendingWriteDriver() {
         },
         async close() { },
         async get() {
-            return null;
+            throw unavailable();
         },
         async list() {
-            return [];
+            throw unavailable();
         },
         async set() {
             throw unavailable();

package/dist/readBoundary.d.ts

@@ -0,0 +1,13 @@
+export type ReadBoundaryOptions = {
+    modules: Readonly<Record<string, readonly string[]>>;
+    roots: readonly string[];
+    allowedAdapters: readonly string[];
+    isForbidden: (moduleId: string) => boolean;
+};
+/**
+ * Host contract: supply every reachable local runtime dependency, including
+ * re-exports and dynamic imports. Absent nodes are external leaves. Exact
+ * trusted adapter IDs stop traversal; hosts verify their cache policy separately.
+ * This test utility deliberately owns no parser, framework, or provider policy.
+ */
+export declare function assertReadBoundary({ modules, roots, allowedAdapters, isForbidden, }: ReadBoundaryOptions): void;

package/dist/readBoundary.js

@@ -0,0 +1,23 @@
+/**
+ * Host contract: supply every reachable local runtime dependency, including
+ * re-exports and dynamic imports. Absent nodes are external leaves. Exact
+ * trusted adapter IDs stop traversal; hosts verify their cache policy separately.
+ * This test utility deliberately owns no parser, framework, or provider policy.
+ */
+export function assertReadBoundary({ modules, roots, allowedAdapters, isForbidden, }) {
+    const adapters = new Set(allowedAdapters);
+    const visited = new Set();
+    function visit(id, path) {
+        if (adapters.has(id) || visited.has(id))
+            return;
+        const nextPath = [...path, id];
+        if (isForbidden(id)) {
+            throw new Error(`Read boundary violation: ${nextPath.join(" -> ")}`);
+        }
+        visited.add(id);
+        for (const dependency of modules[id] ?? [])
+            visit(dependency, nextPath);
+    }
+    for (const root of roots)
+        visit(root, []);
+}