@bayonai/offline 0.9.0 → 0.10.0

package/dist/recoveryPolicy.js

@@ -0,0 +1,73 @@
+/** Shared product decision: recovery is application work, never a retry prompt. */
+export const offlineRecoveryCopy = {
+    reload: "Reload",
+    reloading: "Reconnecting…",
+    preservedChanges: "Some changes could not be saved. Your edits are preserved.",
+};
+/** Hosts project domain records to flags; payloads never enter shared guidance. */
+export function getPendingChangesGuidance({ hasReadyChanges, hasDrafts, hasErrors, isOffline, }) {
+    if (!hasReadyChanges)
+        return hasDrafts
+            ? "Finish editing these drafts to save them."
+            : offlineRecoveryCopy.preservedChanges;
+    if (!hasDrafts && !hasErrors)
+        return isOffline
+            ? "We’ll sync when you’re back online."
+            : "We’ll sync automatically.";
+    const sync = isOffline
+        ? "Changes ready to send will sync when you’re back online."
+        : "Changes ready to send will sync automatically.";
+    return hasDrafts ? `${sync} Finish editing drafts to save them.` : sync;
+}
+const terminalCodes = new Set([
+    "unauthenticated",
+    "permission-denied",
+    "resource-exhausted",
+    "invalid-argument",
+    "failed-precondition",
+    "not-found",
+    "already-exists",
+]);
+const transientCodes = new Set([
+    "unavailable",
+    "deadline-exceeded",
+    "cancelled",
+    "network-request-failed",
+    "internal",
+    "aborted",
+]);
+// Exact transport diagnostics are safe fallbacks only when no structured code
+// exists. Domain messages mentioning a network/offline setting are not signals.
+const connectivityMessages = new Set([
+    "failed to fetch",
+    "fetch failed",
+    "network request failed",
+    "load failed",
+    "offline",
+    "network unavailable",
+    "failed to get documents from server. these documents may exist in the local cache",
+    "failed to get document because the client is offline",
+]);
+/**
+ * Recognize known transient transport/service failures without a provider SDK.
+ * Hosts still own domain validation, idempotency, account scope and replay selection.
+ * Unknown failures are not permission to blindly repeat a mutation.
+ */
+export function isTransientOfflineError(error) {
+    const record = error && typeof error === "object" ? error : {};
+    const rawCode = "code" in record ? record.code : undefined;
+    const code = typeof rawCode === "string" ? rawCode.toLowerCase().split("/").at(-1) : "";
+    if (terminalCodes.has(code))
+        return false;
+    if (transientCodes.has(code))
+        return true;
+    if (code)
+        return false;
+    const rawMessage = typeof error === "string"
+        ? error
+        : "message" in record
+            ? record.message
+            : undefined;
+    const message = typeof rawMessage === "string" ? rawMessage.toLowerCase() : "";
+    return connectivityMessages.has(message.trim().replace(/[.!]$/, ""));
+}

package/dist-cjs/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-cjs/browserFallbackRecovery.js

@@ -2,72 +2,142 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.defaultOfflineFallbackPullThreshold = exports.defaultOfflineFallbackRetryEvent = void 0;
 exports.createBrowserOfflineFallbackRecovery = createBrowserOfflineFallbackRecovery;
+const recoveryPolicy_1 = require("./recoveryPolicy");
+const browserRecovery_1 = require("./browserRecovery");
 exports.defaultOfflineFallbackRetryEvent = "app:network-restored";
 exports.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.
- */
-function createBrowserOfflineFallbackRecovery({ control, environment = createDefaultBrowserOfflineFallbackRecoveryEnvironment(), pullThreshold = exports.defaultOfflineFallbackPullThreshold, retryEvent = exports.defaultOfflineFallbackRetryEvent, retryingText = "Reconnecting…", }) {
+/** Owns pull/reconnect recovery, including safe asynchronous durability proof. */
+function createBrowserOfflineFallbackRecovery({ control, canReload, environment = createDefaultBrowserOfflineFallbackRecoveryEnvironment(), pullThreshold = exports.defaultOfflineFallbackPullThreshold, retryEvent = exports.defaultOfflineFallbackRetryEvent, retryingText = recoveryPolicy_1.offlineRecoveryCopy.reloading, }) {
+    if (control)
+        control.textContent = recoveryPolicy_1.offlineRecoveryCopy.reload;
     let active = false;
-    let retrying = false;
+    let navigating = false;
+    let checking = false;
+    let requested = false;
+    let generation = 0;
+    let timer;
+    let delay = browserRecovery_1.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, browserRecovery_1.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 = recoveryPolicy_1.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 = browserRecovery_1.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-cjs/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-cjs/idbDriver.js

@@ -7,16 +7,28 @@ class OfflineStorageError extends Error {
     name = "OfflineStorageError";
 }
 exports.OfflineStorageError = OfflineStorageError;
-function createIdbKeyValueDriver({ databaseName, databaseVersion = 1, indexedDB = globalThis.indexedDB, operationTimeoutMs, storeName, }) {
+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",
@@ -24,7 +36,7 @@ function createIdbKeyValueDriver({ databaseName, databaseVersion = 1, indexedDB
             operationName,
             storeName,
             operation: async (setTransaction, isCancelled) => {
-                const database = await databasePromise;
+                const database = await getDatabase();
                 if (isCancelled())
                     return;
                 const transaction = database.transaction(storeName, "readwrite");
@@ -45,7 +57,7 @@ function createIdbKeyValueDriver({ databaseName, databaseVersion = 1, indexedDB
                 operationName: "close database",
                 storeName,
                 operation: async () => {
-                    const database = await databasePromise;
+                    const database = await getDatabase();
                     database.close();
                 },
                 timeoutMs: operationTimeoutMs,
@@ -56,7 +68,7 @@ function createIdbKeyValueDriver({ databaseName, databaseVersion = 1, indexedDB
         },
         async deleteIf(key, predicate) {
             return runConditionalStorageOperation({
-                databasePromise,
+                databasePromise: getDatabase(),
                 operationName: "conditionally delete key",
                 storeName,
                 timeoutMs: operationTimeoutMs,
@@ -71,11 +83,12 @@ function createIdbKeyValueDriver({ databaseName, databaseVersion = 1, indexedDB
         },
         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,
@@ -83,11 +96,12 @@ function createIdbKeyValueDriver({ databaseName, databaseVersion = 1, indexedDB
         },
         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,
@@ -95,11 +109,12 @@ function createIdbKeyValueDriver({ databaseName, databaseVersion = 1, indexedDB
         },
         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.
@@ -123,7 +138,7 @@ function createIdbKeyValueDriver({ databaseName, databaseVersion = 1, indexedDB
         },
         async setIf(key, value, predicate) {
             return runConditionalStorageOperation({
-                databasePromise,
+                databasePromise: getDatabase(),
                 operationName: "conditionally replace key",
                 storeName,
                 timeoutMs: operationTimeoutMs,

package/dist-cjs/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-cjs/index.js

@@ -23,3 +23,6 @@ __exportStar(require("./browserFallbackRecovery"), exports);
 __exportStar(require("./durableCommandStore"), exports);
 var idbDriver_1 = require("./idbDriver");
 Object.defineProperty(exports, "OfflineStorageError", { enumerable: true, get: function () { return idbDriver_1.OfflineStorageError; } });
+__exportStar(require("./readBoundary"), exports);
+__exportStar(require("./recoveryPolicy"), exports);
+__exportStar(require("./pendingWriteSupersession"), exports);

package/dist-cjs/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-cjs/pendingWriteSupersession.js

@@ -0,0 +1,28 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.clearSupersededPendingWriteFailures = clearSupersededPendingWriteFailures;
+/**
+ * After remote acknowledgment, retire only rejected snapshots superseded by an
+ * explicit host-owned account/entity/field key. Never infer keys from payloads.
+ */
+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-cjs/pendingWrites.js

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

package/dist-cjs/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-cjs/readBoundary.js

@@ -0,0 +1,26 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.assertReadBoundary = assertReadBoundary;
+/**
+ * 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.
+ */
+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, []);
+}

package/dist-cjs/recoveryPolicy.d.ts

@@ -0,0 +1,20 @@
+/** Shared product decision: recovery is application work, never a retry prompt. */
+export declare const offlineRecoveryCopy: {
+    readonly reload: "Reload";
+    readonly reloading: "Reconnecting…";
+    readonly preservedChanges: "Some changes could not be saved. Your edits are preserved.";
+};
+export type PendingChangesGuidanceState = {
+    hasReadyChanges: boolean;
+    hasDrafts: boolean;
+    hasErrors: boolean;
+    isOffline: boolean;
+};
+/** Hosts project domain records to flags; payloads never enter shared guidance. */
+export declare function getPendingChangesGuidance({ hasReadyChanges, hasDrafts, hasErrors, isOffline, }: PendingChangesGuidanceState): string;
+/**
+ * Recognize known transient transport/service failures without a provider SDK.
+ * Hosts still own domain validation, idempotency, account scope and replay selection.
+ * Unknown failures are not permission to blindly repeat a mutation.
+ */
+export declare function isTransientOfflineError(error: unknown): boolean;

package/dist-cjs/recoveryPolicy.js

@@ -0,0 +1,78 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.offlineRecoveryCopy = void 0;
+exports.getPendingChangesGuidance = getPendingChangesGuidance;
+exports.isTransientOfflineError = isTransientOfflineError;
+/** Shared product decision: recovery is application work, never a retry prompt. */
+exports.offlineRecoveryCopy = {
+    reload: "Reload",
+    reloading: "Reconnecting…",
+    preservedChanges: "Some changes could not be saved. Your edits are preserved.",
+};
+/** Hosts project domain records to flags; payloads never enter shared guidance. */
+function getPendingChangesGuidance({ hasReadyChanges, hasDrafts, hasErrors, isOffline, }) {
+    if (!hasReadyChanges)
+        return hasDrafts
+            ? "Finish editing these drafts to save them."
+            : exports.offlineRecoveryCopy.preservedChanges;
+    if (!hasDrafts && !hasErrors)
+        return isOffline
+            ? "We’ll sync when you’re back online."
+            : "We’ll sync automatically.";
+    const sync = isOffline
+        ? "Changes ready to send will sync when you’re back online."
+        : "Changes ready to send will sync automatically.";
+    return hasDrafts ? `${sync} Finish editing drafts to save them.` : sync;
+}
+const terminalCodes = new Set([
+    "unauthenticated",
+    "permission-denied",
+    "resource-exhausted",
+    "invalid-argument",
+    "failed-precondition",
+    "not-found",
+    "already-exists",
+]);
+const transientCodes = new Set([
+    "unavailable",
+    "deadline-exceeded",
+    "cancelled",
+    "network-request-failed",
+    "internal",
+    "aborted",
+]);
+// Exact transport diagnostics are safe fallbacks only when no structured code
+// exists. Domain messages mentioning a network/offline setting are not signals.
+const connectivityMessages = new Set([
+    "failed to fetch",
+    "fetch failed",
+    "network request failed",
+    "load failed",
+    "offline",
+    "network unavailable",
+    "failed to get documents from server. these documents may exist in the local cache",
+    "failed to get document because the client is offline",
+]);
+/**
+ * Recognize known transient transport/service failures without a provider SDK.
+ * Hosts still own domain validation, idempotency, account scope and replay selection.
+ * Unknown failures are not permission to blindly repeat a mutation.
+ */
+function isTransientOfflineError(error) {
+    const record = error && typeof error === "object" ? error : {};
+    const rawCode = "code" in record ? record.code : undefined;
+    const code = typeof rawCode === "string" ? rawCode.toLowerCase().split("/").at(-1) : "";
+    if (terminalCodes.has(code))
+        return false;
+    if (transientCodes.has(code))
+        return true;
+    if (code)
+        return false;
+    const rawMessage = typeof error === "string"
+        ? error
+        : "message" in record
+            ? record.message
+            : undefined;
+    const message = typeof rawMessage === "string" ? rawMessage.toLowerCase() : "";
+    return connectivityMessages.has(message.trim().replace(/[.!]$/, ""));
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bayonai/offline",
-  "version": "0.9.0",
+  "version": "0.10.0",
   "description": "Reusable offline read-cache, pending-write, and silent recovery primitives.",
   "license": "MIT",
   "author": "Bayon AI",
@@ -46,7 +46,8 @@
     "dist-cjs",
     "CHANGELOG.md",
     "LICENSE",
-    "README.md"
+    "README.md",
+    "RECOVERY.md"
   ],
   "publishConfig": {
     "access": "public"
@@ -63,7 +64,7 @@
     "idb": "^8.0.3"
   },
   "devDependencies": {
-    "fake-indexeddb": "^6.2.5",
+    "fake-indexeddb": "^6.2.6",
     "typescript": "^6.0.3",
     "vitest": "^5.0.1"
   }