@bayonai/offline 0.1.0 → 0.1.1

package/CHANGELOG.md

@@ -1,7 +1,10 @@
 # Changelog
 
-## Unreleased
+## 0.1.1 - 2026-08-10
 
+- Added unique pending-write snapshot identities and atomic conditional
+  replacement/deletion, preventing overlapping sync and autosave operations
+  from deleting newer local data. Existing records remain compatible.
 - Added the initial workspace package with generic read-cache and pending-write
   primitives backed by `idb`.
 - Replaced app-specific test fixtures with neutral package examples.

package/README.md

@@ -81,6 +81,13 @@ await syncPendingWrite({
 });
 ```
 
+Each call to `set` assigns a unique `snapshotId`. Sync status updates and
+successful cleanup compare that identity inside a single storage transaction,
+so a newer local write cannot be overwritten or deleted by an older sync.
+Records created before snapshot identities were introduced remain readable;
+they receive a stable compatibility identity and are upgraded when next
+updated.
+
 Host apps that change their pending-write payload shape can normalize current
 records while keeping domain logic outside the package:
 

package/dist/idbDriver.d.ts

@@ -2,10 +2,13 @@ export type BrowserKeyValueDriver = {
     clear: () => Promise<void>;
     close: () => Promise<void>;
     delete: (key: string) => Promise<void>;
+    deleteIf: (key: string, predicate: KeyValuePredicate) => Promise<boolean>;
     get: (key: string) => Promise<unknown | null>;
     list: () => Promise<unknown[]>;
     set: (key: string, value: unknown) => Promise<void>;
+    setIf: (key: string, value: unknown, predicate: KeyValuePredicate) => Promise<boolean>;
 };
+export type KeyValuePredicate = (value: unknown | null) => boolean;
 export type BrowserKeyValueDriverOptions = {
     databaseName: string;
     databaseVersion?: number;

package/dist/idbDriver.js

@@ -13,6 +13,7 @@ export function createIdbKeyValueDriver({ databaseName, databaseVersion = 1, ind
         async clear() {
             await runBrowserStorageOperation({
                 fallback: undefined,
+                operationName: "clear object store",
                 operation: async () => {
                     const database = await databasePromise;
                     await database.clear(storeName);
@@ -23,6 +24,7 @@ export function createIdbKeyValueDriver({ databaseName, databaseVersion = 1, ind
         async close() {
             await runBrowserStorageOperation({
                 fallback: undefined,
+                operationName: "close database",
                 operation: async () => {
                     const database = await databasePromise;
                     database.close();
@@ -33,6 +35,7 @@ export function createIdbKeyValueDriver({ databaseName, databaseVersion = 1, ind
         async delete(key) {
             await runBrowserStorageOperation({
                 fallback: undefined,
+                operationName: "delete key",
                 operation: async () => {
                     const database = await databasePromise;
                     await database.delete(storeName, key);
@@ -40,9 +43,32 @@ export function createIdbKeyValueDriver({ databaseName, databaseVersion = 1, ind
                 timeoutMs: operationTimeoutMs,
             });
         },
+        async deleteIf(key, predicate) {
+            return runBrowserStorageOperation({
+                fallback: false,
+                operationName: "conditionally delete key",
+                operation: async () => {
+                    const database = await databasePromise;
+                    // The ownership check and deletion must share a transaction; splitting
+                    // them can delete a newer offline snapshot written by another trigger.
+                    const transaction = database.transaction(storeName, "readwrite");
+                    const objectStore = transaction.objectStore(storeName);
+                    const current = (await objectStore.get(key)) ?? null;
+                    if (!predicate(current)) {
+                        await transaction.done;
+                        return false;
+                    }
+                    await objectStore.delete(key);
+                    await transaction.done;
+                    return true;
+                },
+                timeoutMs: operationTimeoutMs,
+            });
+        },
         async get(key) {
             return runBrowserStorageOperation({
                 fallback: null,
+                operationName: "read key",
                 operation: async () => {
                     const database = await databasePromise;
                     return (await database.get(storeName, key)) ?? null;
@@ -53,6 +79,7 @@ export function createIdbKeyValueDriver({ databaseName, databaseVersion = 1, ind
         async list() {
             return runBrowserStorageOperation({
                 fallback: [],
+                operationName: "list object store",
                 operation: async () => {
                     const database = await databasePromise;
                     return database.getAll(storeName);
@@ -63,6 +90,7 @@ export function createIdbKeyValueDriver({ databaseName, databaseVersion = 1, ind
         async set(key, value) {
             await runBrowserStorageOperation({
                 fallback: undefined,
+                operationName: "write key",
                 operation: async () => {
                     const database = await databasePromise;
                     await database.put(storeName, value, key);
@@ -70,6 +98,26 @@ export function createIdbKeyValueDriver({ databaseName, databaseVersion = 1, ind
                 timeoutMs: operationTimeoutMs,
             });
         },
+        async setIf(key, value, predicate) {
+            return runBrowserStorageOperation({
+                fallback: false,
+                operationName: "conditionally replace key",
+                operation: async () => {
+                    const database = await databasePromise;
+                    const transaction = database.transaction(storeName, "readwrite");
+                    const objectStore = transaction.objectStore(storeName);
+                    const current = (await objectStore.get(key)) ?? null;
+                    if (!predicate(current)) {
+                        await transaction.done;
+                        return false;
+                    }
+                    await objectStore.put(value, key);
+                    await transaction.done;
+                    return true;
+                },
+                timeoutMs: operationTimeoutMs,
+            });
+        },
     };
 }
 async function openKeyValueDatabase({ databaseName, databaseVersion, indexedDB, storeName, }) {
@@ -86,17 +134,23 @@ async function openKeyValueDatabase({ databaseName, databaseVersion, indexedDB,
     }
     return database;
 }
-async function runBrowserStorageOperation({ fallback, operation, timeoutMs, }) {
+async function runBrowserStorageOperation({ fallback, operation, operationName, timeoutMs, }) {
     let timeoutId = null;
     try {
         return await Promise.race([
             operation(),
             new Promise((resolve) => {
-                timeoutId = setTimeout(() => resolve(fallback), timeoutMs);
+                timeoutId = setTimeout(() => {
+                    console.error(`IndexedDB timed out while trying to ${operationName}.`, {
+                        timeoutMs,
+                    });
+                    resolve(fallback);
+                }, timeoutMs);
             }),
         ]);
     }
-    catch {
+    catch (error) {
+        console.error(`IndexedDB failed to ${operationName}.`, { error });
         return fallback;
     }
     finally {

package/dist/pendingWrites.d.ts

@@ -7,28 +7,37 @@ export type PendingWriteRecord<Payload = unknown> = {
     id: string;
     payload: Payload;
     savedAt: string;
+    snapshotId: string;
     syncStatus: PendingWriteStatus;
 };
+export type PendingWriteRecordInput<Payload = unknown> = Omit<PendingWriteRecord<Payload>, "snapshotId"> & {
+    snapshotId?: string;
+};
 export type PendingWritePayloadNormalizer<Payload = unknown> = (payload: unknown) => Payload | null;
 export type PendingWriteDriver = {
     clear: (key: string) => Promise<void>;
+    clearIf: (key: string, predicate: PendingWritePredicate) => Promise<boolean>;
     clearAll: () => Promise<void>;
     close?: () => Promise<void>;
     get: (key: string) => Promise<unknown | null>;
     list: () => Promise<unknown[]>;
     set: (key: string, value: unknown) => Promise<void>;
+    setIf: (key: string, value: unknown, predicate: PendingWritePredicate) => Promise<boolean>;
 };
+export type PendingWritePredicate = (value: unknown | null) => boolean;
 export type PendingWriteStore<Payload = unknown> = {
     clear: (id: string) => Promise<void>;
     clearAll: () => Promise<void>;
-    clearIfSavedAt: (id: string, savedAt: string) => Promise<boolean>;
+    clearIfSnapshotId: (id: string, snapshotId: string) => Promise<boolean>;
     close: () => Promise<void>;
     get: (id: string) => Promise<PendingWriteRecord<Payload> | null>;
     list: () => Promise<Array<PendingWriteRecord<Payload>>>;
-    set: (record: PendingWriteRecord<Payload>) => Promise<void>;
+    replaceIfSnapshotId: (id: string, snapshotId: string, record: PendingWriteRecord<Payload>) => Promise<boolean>;
+    set: (record: PendingWriteRecordInput<Payload>) => Promise<PendingWriteRecord<Payload>>;
 };
 export type PendingWriteStoreOptions<Payload = unknown> = {
     keyPrefix: string;
+    normalizeLegacyRecord?: PendingWritePayloadNormalizer<PendingWriteRecordInput<Payload>>;
     normalizePayload?: PendingWritePayloadNormalizer<Payload>;
     schemaVersion?: number;
 };
@@ -51,11 +60,12 @@ export type SyncPendingWriteResult = {
     error: string;
     status: "failed";
 };
-export declare function createPendingWriteStore<Payload = unknown>(driver: PendingWriteDriver, { keyPrefix, normalizePayload, schemaVersion, }: PendingWriteStoreOptions<Payload>): PendingWriteStore<Payload>;
+export declare function createPendingWriteStore<Payload = unknown>(driver: PendingWriteDriver, { keyPrefix, normalizeLegacyRecord, normalizePayload, schemaVersion, }: PendingWriteStoreOptions<Payload>): PendingWriteStore<Payload>;
 export declare function createMemoryPendingWriteDriver(): PendingWriteDriver;
 export declare function createBrowserPendingWriteDriver({ databaseName, databaseVersion, indexedDB, operationTimeoutMs, storeName, }: Omit<BrowserPendingWriteStoreOptions, "keyPrefix" | "normalizePayload" | "schemaVersion">): PendingWriteDriver | null;
-export declare function createBrowserPendingWriteStore<Payload = unknown>({ databaseName, databaseVersion, indexedDB, keyPrefix, normalizePayload, operationTimeoutMs, schemaVersion, storeName, }: BrowserPendingWriteStoreOptions<Payload>): PendingWriteStore<Payload>;
+export declare function createBrowserPendingWriteStore<Payload = unknown>({ databaseName, databaseVersion, indexedDB, keyPrefix, normalizeLegacyRecord, normalizePayload, operationTimeoutMs, schemaVersion, storeName, }: BrowserPendingWriteStoreOptions<Payload>): PendingWriteStore<Payload>;
 export declare function createPendingWriteKey({ id, prefix }: PendingWriteKeyOptions): string;
+export declare function createPendingWriteSnapshotId(): `${string}-${string}-${string}-${string}-${string}`;
 export declare function syncPendingWrite<Payload>({ id, store, sync, }: {
     id: string;
     store: PendingWriteStore<Payload>;

package/dist/pendingWrites.js

@@ -1,7 +1,7 @@
 import { createIdbKeyValueDriver, } from "./idbDriver.js";
 export const pendingWriteSchemaVersion = 1;
 export const pendingWriteOperationTimeoutMs = 2_000;
-export function createPendingWriteStore(driver, { keyPrefix, normalizePayload, schemaVersion = pendingWriteSchemaVersion, }) {
+export function createPendingWriteStore(driver, { keyPrefix, normalizeLegacyRecord, normalizePayload, schemaVersion = pendingWriteSchemaVersion, }) {
     return {
         async clear(id) {
             await driver.clear(createPendingWriteKey({ id, prefix: keyPrefix }));
@@ -9,33 +9,43 @@ export function createPendingWriteStore(driver, { keyPrefix, normalizePayload, s
         async clearAll() {
             await driver.clearAll();
         },
-        async clearIfSavedAt(id, savedAt) {
-            const current = await this.get(id);
-            if (!current || current.savedAt !== savedAt) {
-                return false;
-            }
-            await this.clear(id);
-            return true;
+        async clearIfSnapshotId(id, snapshotId) {
+            return driver.clearIf(createPendingWriteKey({ id, prefix: keyPrefix }), (value) => toPendingWriteEnvelope(value, schemaVersion, {
+                normalizeLegacyRecord,
+                normalizePayload,
+            })?.record.snapshotId === snapshotId);
         },
         async close() {
             await driver.close?.();
         },
         async get(id) {
-            return (toPendingWriteEnvelope(await driver.get(createPendingWriteKey({ id, prefix: keyPrefix })), schemaVersion, { normalizePayload })?.record ?? null);
+            return (toPendingWriteEnvelope(await driver.get(createPendingWriteKey({ id, prefix: keyPrefix })), schemaVersion, { normalizeLegacyRecord, normalizePayload })?.record ?? null);
         },
         async list() {
             return (await driver.list())
                 .map((value) => toPendingWriteEnvelope(value, schemaVersion, {
+                normalizeLegacyRecord,
                 normalizePayload,
             })?.record)
                 .filter((record) => Boolean(record))
                 .sort((left, right) => left.savedAt.localeCompare(right.savedAt));
         },
+        async replaceIfSnapshotId(id, snapshotId, record) {
+            return driver.setIf(createPendingWriteKey({ id, prefix: keyPrefix }), { record, schemaVersion }, (value) => toPendingWriteEnvelope(value, schemaVersion, {
+                normalizeLegacyRecord,
+                normalizePayload,
+            })?.record.snapshotId === snapshotId);
+        },
         async set(record) {
+            const storedRecord = {
+                ...record,
+                snapshotId: record.snapshotId ?? createPendingWriteSnapshotId(),
+            };
             await driver.set(createPendingWriteKey({ id: record.id, prefix: keyPrefix }), {
-                record,
+                record: storedRecord,
                 schemaVersion,
             });
+            return storedRecord;
         },
     };
 }
@@ -45,6 +55,14 @@ export function createMemoryPendingWriteDriver() {
         async clear(key) {
             records.delete(key);
         },
+        async clearIf(key, predicate) {
+            const current = records.get(key) ?? null;
+            if (!predicate(current)) {
+                return false;
+            }
+            records.delete(key);
+            return true;
+        },
         async clearAll() {
             records.clear();
         },
@@ -58,6 +76,13 @@ export function createMemoryPendingWriteDriver() {
         async set(key, value) {
             records.set(key, value);
         },
+        async setIf(key, value, predicate) {
+            if (!predicate(records.get(key) ?? null)) {
+                return false;
+            }
+            records.set(key, value);
+            return true;
+        },
     };
 }
 export function createBrowserPendingWriteDriver({ databaseName, databaseVersion, indexedDB = globalThis.indexedDB, operationTimeoutMs = pendingWriteOperationTimeoutMs, storeName, }) {
@@ -70,7 +95,7 @@ export function createBrowserPendingWriteDriver({ databaseName, databaseVersion,
     });
     return driver ? toPendingWriteDriver(driver) : null;
 }
-export function createBrowserPendingWriteStore({ databaseName, databaseVersion, indexedDB = globalThis.indexedDB, keyPrefix, normalizePayload, operationTimeoutMs = pendingWriteOperationTimeoutMs, schemaVersion = pendingWriteSchemaVersion, storeName, }) {
+export function createBrowserPendingWriteStore({ databaseName, databaseVersion, indexedDB = globalThis.indexedDB, keyPrefix, normalizeLegacyRecord, normalizePayload, operationTimeoutMs = pendingWriteOperationTimeoutMs, schemaVersion = pendingWriteSchemaVersion, storeName, }) {
     const driver = createBrowserPendingWriteDriver({
         databaseName,
         databaseVersion,
@@ -78,11 +103,14 @@ export function createBrowserPendingWriteStore({ databaseName, databaseVersion,
         operationTimeoutMs,
         storeName,
     });
-    return createPendingWriteStore(driver ?? createNoopPendingWriteDriver(), { keyPrefix, normalizePayload, schemaVersion });
+    return createPendingWriteStore(driver ?? createNoopPendingWriteDriver(), { keyPrefix, normalizeLegacyRecord, normalizePayload, schemaVersion });
 }
 export function createPendingWriteKey({ id, prefix }) {
     return `${prefix}:${encodeURIComponent(id)}`;
 }
+export function createPendingWriteSnapshotId() {
+    return globalThis.crypto.randomUUID();
+}
 export async function syncPendingWrite({ id, store, sync, }) {
     const pending = await store.get(id);
     if (!pending) {
@@ -91,7 +119,7 @@ export async function syncPendingWrite({ id, store, sync, }) {
     await markPendingSnapshot({
         id,
         nextRecord: { ...pending, error: undefined, syncStatus: "syncing" },
-        savedAt: pending.savedAt,
+        snapshotId: pending.snapshotId,
         store,
     });
     try {
@@ -102,18 +130,21 @@ export async function syncPendingWrite({ id, store, sync, }) {
         await markPendingSnapshot({
             id,
             nextRecord: { ...pending, error: message, syncStatus: "failed" },
-            savedAt: pending.savedAt,
+            snapshotId: pending.snapshotId,
             store,
         });
         return { error: message, status: "failed" };
     }
-    return (await store.clearIfSavedAt(id, pending.savedAt))
+    return (await store.clearIfSnapshotId(id, pending.snapshotId))
         ? { status: "synced" }
         : { status: "superseded" };
 }
 function createNoopPendingWriteDriver() {
     return {
         async clear() { },
+        async clearIf() {
+            return false;
+        },
         async clearAll() { },
         async close() { },
         async get() {
@@ -123,43 +154,41 @@ function createNoopPendingWriteDriver() {
             return [];
         },
         async set() { },
+        async setIf() {
+            return false;
+        },
     };
 }
 function toPendingWriteDriver(driver) {
     return {
         clear: driver.delete,
+        clearIf: driver.deleteIf,
         clearAll: driver.clear,
         close: driver.close,
         get: driver.get,
         list: driver.list,
         set: driver.set,
+        setIf: driver.setIf,
     };
 }
-async function markPendingSnapshot({ id, nextRecord, savedAt, store, }) {
-    const current = await store.get(id);
-    if (current?.savedAt !== savedAt) {
-        return false;
-    }
-    await store.set(nextRecord);
-    return true;
+async function markPendingSnapshot({ id, nextRecord, snapshotId, store, }) {
+    return store.replaceIfSnapshotId(id, snapshotId, nextRecord);
 }
-function toPendingWriteEnvelope(value, schemaVersion, { normalizePayload }) {
-    if (!value ||
-        typeof value !== "object" ||
-        !("schemaVersion" in value) ||
-        value.schemaVersion !== schemaVersion ||
-        !("record" in value) ||
-        !isPendingWriteRecord(value.record)) {
-        return null;
-    }
-    const record = normalizePendingWriteRecord(value.record, normalizePayload);
+function toPendingWriteEnvelope(value, schemaVersion, { normalizeLegacyRecord, normalizePayload }) {
+    const envelopeRecord = readPendingWriteEnvelopeRecord(value, schemaVersion);
+    const legacyRecord = envelopeRecord
+        ? null
+        : (normalizeLegacyRecord?.(value) ?? null);
+    const record = normalizePendingWriteRecord(envelopeRecord ?? legacyRecord, normalizePayload);
     return record ? { record, schemaVersion } : null;
 }
 function normalizePendingWriteRecord(record, normalizePayload) {
-    if (!normalizePayload) {
-        return record;
+    if (!record) {
+        return null;
     }
-    const payload = normalizePayload(record.payload);
+    const payload = normalizePayload
+        ? normalizePayload(record.payload)
+        : record.payload;
     if (payload === null) {
         return null;
     }
@@ -168,9 +197,24 @@ function normalizePendingWriteRecord(record, normalizePayload) {
         id: record.id,
         payload,
         savedAt: record.savedAt,
+        snapshotId: record.snapshotId ?? createLegacyPendingWriteSnapshotId(record),
         syncStatus: record.syncStatus,
     };
 }
+function readPendingWriteEnvelopeRecord(value, schemaVersion) {
+    if (!value ||
+        typeof value !== "object" ||
+        !("schemaVersion" in value) ||
+        value.schemaVersion !== schemaVersion ||
+        !("record" in value) ||
+        !isPendingWriteRecord(value.record)) {
+        return null;
+    }
+    return value.record;
+}
+function createLegacyPendingWriteSnapshotId(record) {
+    return `legacy:${encodeURIComponent(record.id)}:${encodeURIComponent(record.savedAt)}`;
+}
 function isPendingWriteRecord(value) {
     return (value !== null &&
         typeof value === "object" &&
@@ -178,6 +222,7 @@ function isPendingWriteRecord(value) {
         typeof value.id === "string" &&
         "savedAt" in value &&
         typeof value.savedAt === "string" &&
+        (!("snapshotId" in value) || typeof value.snapshotId === "string") &&
         "syncStatus" in value &&
         (value.syncStatus === "pending" ||
             value.syncStatus === "syncing" ||

package/dist/readCache.d.ts

@@ -1,6 +1,8 @@
 import { type BrowserKeyValueDriverOptions } from "./idbDriver";
 export declare const readCacheSchemaVersion = 1;
 export declare const readCacheFreshnessMaxAgeMs = 30000;
+export declare const durableReadCacheFreshnessMaxAgeMs: number;
+export declare const identityReadCacheFreshnessMaxAgeMs: number;
 export declare const browserReadCacheOperationTimeoutMs = 2000;
 export type ReadCacheHit<T> = {
     fromCache: true;
@@ -10,14 +12,23 @@ export type ReadCacheHit<T> = {
 export type ReadCacheDriver = {
     clear: () => Promise<void>;
     close?: () => Promise<void>;
+    delete: (key: string) => Promise<void>;
     get: (key: string) => Promise<unknown | null>;
     set: (key: string, value: unknown) => Promise<void>;
 };
 export type ReadCache = {
+    /**
+     * Resolves a stable cache for the duration of a resource load. Dynamic
+     * adapters use this to pin the active account before asynchronous work.
+     */
+    capture?: () => ReadCache;
     clear: () => Promise<void>;
     close: () => Promise<void>;
+    delete: (key: string) => Promise<void>;
     get: <T>(key: string) => Promise<ReadCacheHit<T> | null>;
+    getVersion: (key: string) => string;
     set: <T>(key: string, value: T) => Promise<void>;
+    setIfVersion: <T>(key: string, value: T, version: string) => Promise<boolean>;
 };
 export type ReadThroughCacheResult<T> = {
     data: T;
@@ -45,15 +56,18 @@ export declare function createReadCache(driver: ReadCacheDriver): ReadCache;
 export declare function createMemoryReadCacheDriver(): ReadCacheDriver;
 export declare function createBrowserReadCache({ databaseName, databaseVersion, indexedDB, operationTimeoutMs, storeName, }: BrowserReadCacheOptions): ReadCache;
 export declare function createReadCacheKey({ namespace, params, prefix, scope, }: ReadCacheKeyOptions): string;
-export declare function readThroughCache<T>({ cache, key, loadFresh, }: {
+export declare function readThroughCache<T>({ cache, key, loadFresh, maxAgeMs, }: {
     cache: ReadCache;
     key: string;
     loadFresh: () => Promise<T>;
+    maxAgeMs?: number;
 }): Promise<ReadThroughCacheResult<T>>;
-export declare function loadReadCacheResource<T>({ cache, key, loadFresh, maxAgeMs, onUpdate, }: {
+export declare function loadReadCacheResource<T>({ cache, key, loadFresh, maxAgeMs, onCacheWriteError, onUpdate, skipCache, }: {
     cache: ReadCache;
     key: string;
     loadFresh: () => Promise<T>;
     maxAgeMs?: number;
+    onCacheWriteError?: (error: Error) => void;
     onUpdate: (update: ReadCacheResourceUpdate<T>) => void;
+    skipCache?: boolean;
 }): Promise<T>;

package/dist/readCache.js

@@ -1,16 +1,37 @@
 import { createIdbKeyValueDriver, } from "./idbDriver.js";
 export const readCacheSchemaVersion = 1;
 export const readCacheFreshnessMaxAgeMs = 30_000;
+export const durableReadCacheFreshnessMaxAgeMs = 60 * 60_000;
+export const identityReadCacheFreshnessMaxAgeMs = 24 * 60 * 60_000;
 export const browserReadCacheOperationTimeoutMs = 2_000;
-const pendingFreshLoads = new Map();
+const pendingFreshLoads = new WeakMap();
 export function createReadCache(driver) {
-    return {
+    let globalVersion = 0;
+    const keyVersions = new Map();
+    let operationQueue = Promise.resolve();
+    const pendingLoads = new Map();
+    function getVersion(key) {
+        return `${globalVersion}:${keyVersions.get(key) ?? 0}`;
+    }
+    function enqueue(operation) {
+        const next = operationQueue.then(operation, operation);
+        operationQueue = next.then(() => undefined, () => undefined);
+        return next;
+    }
+    const cache = {
         async clear() {
-            pendingFreshLoads.clear();
-            await driver.clear();
+            pendingLoads.clear();
+            globalVersion += 1;
+            keyVersions.clear();
+            await enqueue(() => driver.clear());
         },
         async close() {
-            await driver.close?.();
+            await enqueue(async () => driver.close?.());
+        },
+        async delete(key) {
+            pendingLoads.delete(key);
+            keyVersions.set(key, (keyVersions.get(key) ?? 0) + 1);
+            await enqueue(() => driver.delete(key));
         },
         async get(key) {
             const envelope = toReadCacheEnvelope(await driver.get(key));
@@ -22,14 +43,33 @@ export function createReadCache(driver) {
                 }
                 : null;
         },
+        getVersion,
         async set(key, value) {
-            await driver.set(key, {
+            await enqueue(() => driver.set(key, {
                 savedAt: new Date().toISOString(),
                 schemaVersion: readCacheSchemaVersion,
                 value,
+            }));
+        },
+        async setIfVersion(key, value, version) {
+            if (getVersion(key) !== version) {
+                return false;
+            }
+            return enqueue(async () => {
+                if (getVersion(key) !== version) {
+                    return false;
+                }
+                await driver.set(key, {
+                    savedAt: new Date().toISOString(),
+                    schemaVersion: readCacheSchemaVersion,
+                    value,
+                });
+                return true;
             });
         },
     };
+    pendingFreshLoads.set(cache, pendingLoads);
+    return cache;
 }
 export function createMemoryReadCacheDriver() {
     const records = new Map();
@@ -38,6 +78,9 @@ export function createMemoryReadCacheDriver() {
             records.clear();
         },
         async close() { },
+        async delete(key) {
+            records.delete(key);
+        },
         async get(key) {
             return records.get(key) ?? null;
         },
@@ -71,11 +114,21 @@ export function createReadCacheKey({ namespace, params = {}, prefix, scope, }) {
         .filter(Boolean)
         .join(":");
 }
-export async function readThroughCache({ cache, key, loadFresh, }) {
-    const cached = await cache.get(key);
+export async function readThroughCache({ cache, key, loadFresh, maxAgeMs, }) {
+    const resourceCache = cache.capture?.() ?? cache;
+    const version = resourceCache.getVersion(key);
+    const cached = await resourceCache.get(key);
+    if (cached && isCacheFresh(cached.savedAt, maxAgeMs)) {
+        return {
+            data: cached.value,
+            error: null,
+            fromCache: true,
+            stale: false,
+        };
+    }
     try {
         const fresh = await loadFresh();
-        await cache.set(key, fresh);
+        await resourceCache.setIfVersion(key, fresh, version);
         return {
             data: fresh,
             error: null,
@@ -95,8 +148,10 @@ export async function readThroughCache({ cache, key, loadFresh, }) {
         throw error;
     }
 }
-export async function loadReadCacheResource({ cache, key, loadFresh, maxAgeMs, onUpdate, }) {
-    const cached = await cache.get(key);
+export async function loadReadCacheResource({ cache, key, loadFresh, maxAgeMs, onCacheWriteError, onUpdate, skipCache = false, }) {
+    const resourceCache = cache.capture?.() ?? cache;
+    const version = resourceCache.getVersion(key);
+    const cached = skipCache ? null : await resourceCache.get(key);
     if (cached) {
         onUpdate({ data: cached.value, fromCache: true });
         if (isCacheFresh(cached.savedAt, maxAgeMs)) {
@@ -104,9 +159,16 @@ export async function loadReadCacheResource({ cache, key, loadFresh, maxAgeMs, o
         }
     }
     try {
-        const fresh = await loadSharedFreshResource(key, loadFresh);
+        const fresh = await loadSharedFreshResource(resourceCache, key, loadFresh);
         onUpdate({ data: fresh, fromCache: false });
-        void cache.set(key, fresh).catch(() => undefined);
+        void resourceCache.setIfVersion(key, fresh, version).catch((error) => {
+            const normalizedError = normalizeError(error);
+            console.error("[Bayon offline] Unable to refresh the read cache.", {
+                error: normalizedError,
+                key,
+            });
+            onCacheWriteError?.(normalizedError);
+        });
         return fresh;
     }
     catch (error) {
@@ -125,6 +187,7 @@ function createNoopReadCacheDriver() {
     return {
         async clear() { },
         async close() { },
+        async delete() { },
         async get() {
             return null;
         },
@@ -138,22 +201,32 @@ function isCacheFresh(savedAt, maxAgeMs) {
     const savedTime = Date.parse(savedAt);
     return Number.isFinite(savedTime) && Date.now() - savedTime <= maxAgeMs;
 }
-async function loadSharedFreshResource(key, loadFresh) {
-    const pendingLoad = pendingFreshLoads.get(key);
+async function loadSharedFreshResource(cache, key, loadFresh) {
+    const pendingLoads = getPendingFreshLoads(cache);
+    const pendingLoad = pendingLoads.get(key);
     if (pendingLoad) {
         return (await pendingLoad);
     }
     const nextLoad = loadFresh();
-    pendingFreshLoads.set(key, nextLoad);
+    pendingLoads.set(key, nextLoad);
     try {
         return await nextLoad;
     }
     finally {
-        if (pendingFreshLoads.get(key) === nextLoad) {
-            pendingFreshLoads.delete(key);
+        if (pendingLoads.get(key) === nextLoad) {
+            pendingLoads.delete(key);
         }
     }
 }
+function getPendingFreshLoads(cache) {
+    const existing = pendingFreshLoads.get(cache);
+    if (existing) {
+        return existing;
+    }
+    const next = new Map();
+    pendingFreshLoads.set(cache, next);
+    return next;
+}
 function toReadCacheEnvelope(value) {
     if (!value || typeof value !== "object") {
         return null;

package/dist-cjs/idbDriver.js

@@ -16,6 +16,7 @@ function createIdbKeyValueDriver({ databaseName, databaseVersion = 1, indexedDB
         async clear() {
             await runBrowserStorageOperation({
                 fallback: undefined,
+                operationName: "clear object store",
                 operation: async () => {
                     const database = await databasePromise;
                     await database.clear(storeName);
@@ -26,6 +27,7 @@ function createIdbKeyValueDriver({ databaseName, databaseVersion = 1, indexedDB
         async close() {
             await runBrowserStorageOperation({
                 fallback: undefined,
+                operationName: "close database",
                 operation: async () => {
                     const database = await databasePromise;
                     database.close();
@@ -36,6 +38,7 @@ function createIdbKeyValueDriver({ databaseName, databaseVersion = 1, indexedDB
         async delete(key) {
             await runBrowserStorageOperation({
                 fallback: undefined,
+                operationName: "delete key",
                 operation: async () => {
                     const database = await databasePromise;
                     await database.delete(storeName, key);
@@ -43,9 +46,32 @@ function createIdbKeyValueDriver({ databaseName, databaseVersion = 1, indexedDB
                 timeoutMs: operationTimeoutMs,
             });
         },
+        async deleteIf(key, predicate) {
+            return runBrowserStorageOperation({
+                fallback: false,
+                operationName: "conditionally delete key",
+                operation: async () => {
+                    const database = await databasePromise;
+                    // The ownership check and deletion must share a transaction; splitting
+                    // them can delete a newer offline snapshot written by another trigger.
+                    const transaction = database.transaction(storeName, "readwrite");
+                    const objectStore = transaction.objectStore(storeName);
+                    const current = (await objectStore.get(key)) ?? null;
+                    if (!predicate(current)) {
+                        await transaction.done;
+                        return false;
+                    }
+                    await objectStore.delete(key);
+                    await transaction.done;
+                    return true;
+                },
+                timeoutMs: operationTimeoutMs,
+            });
+        },
         async get(key) {
             return runBrowserStorageOperation({
                 fallback: null,
+                operationName: "read key",
                 operation: async () => {
                     const database = await databasePromise;
                     return (await database.get(storeName, key)) ?? null;
@@ -56,6 +82,7 @@ function createIdbKeyValueDriver({ databaseName, databaseVersion = 1, indexedDB
         async list() {
             return runBrowserStorageOperation({
                 fallback: [],
+                operationName: "list object store",
                 operation: async () => {
                     const database = await databasePromise;
                     return database.getAll(storeName);
@@ -66,6 +93,7 @@ function createIdbKeyValueDriver({ databaseName, databaseVersion = 1, indexedDB
         async set(key, value) {
             await runBrowserStorageOperation({
                 fallback: undefined,
+                operationName: "write key",
                 operation: async () => {
                     const database = await databasePromise;
                     await database.put(storeName, value, key);
@@ -73,6 +101,26 @@ function createIdbKeyValueDriver({ databaseName, databaseVersion = 1, indexedDB
                 timeoutMs: operationTimeoutMs,
             });
         },
+        async setIf(key, value, predicate) {
+            return runBrowserStorageOperation({
+                fallback: false,
+                operationName: "conditionally replace key",
+                operation: async () => {
+                    const database = await databasePromise;
+                    const transaction = database.transaction(storeName, "readwrite");
+                    const objectStore = transaction.objectStore(storeName);
+                    const current = (await objectStore.get(key)) ?? null;
+                    if (!predicate(current)) {
+                        await transaction.done;
+                        return false;
+                    }
+                    await objectStore.put(value, key);
+                    await transaction.done;
+                    return true;
+                },
+                timeoutMs: operationTimeoutMs,
+            });
+        },
     };
 }
 async function openKeyValueDatabase({ databaseName, databaseVersion, indexedDB, storeName, }) {
@@ -89,17 +137,23 @@ async function openKeyValueDatabase({ databaseName, databaseVersion, indexedDB,
     }
     return database;
 }
-async function runBrowserStorageOperation({ fallback, operation, timeoutMs, }) {
+async function runBrowserStorageOperation({ fallback, operation, operationName, timeoutMs, }) {
     let timeoutId = null;
     try {
         return await Promise.race([
             operation(),
             new Promise((resolve) => {
-                timeoutId = setTimeout(() => resolve(fallback), timeoutMs);
+                timeoutId = setTimeout(() => {
+                    console.error(`IndexedDB timed out while trying to ${operationName}.`, {
+                        timeoutMs,
+                    });
+                    resolve(fallback);
+                }, timeoutMs);
             }),
         ]);
     }
-    catch {
+    catch (error) {
+        console.error(`IndexedDB failed to ${operationName}.`, { error });
         return fallback;
     }
     finally {

package/dist-cjs/pendingWrites.js

@@ -6,11 +6,12 @@ exports.createMemoryPendingWriteDriver = createMemoryPendingWriteDriver;
 exports.createBrowserPendingWriteDriver = createBrowserPendingWriteDriver;
 exports.createBrowserPendingWriteStore = createBrowserPendingWriteStore;
 exports.createPendingWriteKey = createPendingWriteKey;
+exports.createPendingWriteSnapshotId = createPendingWriteSnapshotId;
 exports.syncPendingWrite = syncPendingWrite;
 const idbDriver_1 = require("./idbDriver");
 exports.pendingWriteSchemaVersion = 1;
 exports.pendingWriteOperationTimeoutMs = 2_000;
-function createPendingWriteStore(driver, { keyPrefix, normalizePayload, schemaVersion = exports.pendingWriteSchemaVersion, }) {
+function createPendingWriteStore(driver, { keyPrefix, normalizeLegacyRecord, normalizePayload, schemaVersion = exports.pendingWriteSchemaVersion, }) {
     return {
         async clear(id) {
             await driver.clear(createPendingWriteKey({ id, prefix: keyPrefix }));
@@ -18,33 +19,43 @@ function createPendingWriteStore(driver, { keyPrefix, normalizePayload, schemaVe
         async clearAll() {
             await driver.clearAll();
         },
-        async clearIfSavedAt(id, savedAt) {
-            const current = await this.get(id);
-            if (!current || current.savedAt !== savedAt) {
-                return false;
-            }
-            await this.clear(id);
-            return true;
+        async clearIfSnapshotId(id, snapshotId) {
+            return driver.clearIf(createPendingWriteKey({ id, prefix: keyPrefix }), (value) => toPendingWriteEnvelope(value, schemaVersion, {
+                normalizeLegacyRecord,
+                normalizePayload,
+            })?.record.snapshotId === snapshotId);
         },
         async close() {
             await driver.close?.();
         },
         async get(id) {
-            return (toPendingWriteEnvelope(await driver.get(createPendingWriteKey({ id, prefix: keyPrefix })), schemaVersion, { normalizePayload })?.record ?? null);
+            return (toPendingWriteEnvelope(await driver.get(createPendingWriteKey({ id, prefix: keyPrefix })), schemaVersion, { normalizeLegacyRecord, normalizePayload })?.record ?? null);
         },
         async list() {
             return (await driver.list())
                 .map((value) => toPendingWriteEnvelope(value, schemaVersion, {
+                normalizeLegacyRecord,
                 normalizePayload,
             })?.record)
                 .filter((record) => Boolean(record))
                 .sort((left, right) => left.savedAt.localeCompare(right.savedAt));
         },
+        async replaceIfSnapshotId(id, snapshotId, record) {
+            return driver.setIf(createPendingWriteKey({ id, prefix: keyPrefix }), { record, schemaVersion }, (value) => toPendingWriteEnvelope(value, schemaVersion, {
+                normalizeLegacyRecord,
+                normalizePayload,
+            })?.record.snapshotId === snapshotId);
+        },
         async set(record) {
+            const storedRecord = {
+                ...record,
+                snapshotId: record.snapshotId ?? createPendingWriteSnapshotId(),
+            };
             await driver.set(createPendingWriteKey({ id: record.id, prefix: keyPrefix }), {
-                record,
+                record: storedRecord,
                 schemaVersion,
             });
+            return storedRecord;
         },
     };
 }
@@ -54,6 +65,14 @@ function createMemoryPendingWriteDriver() {
         async clear(key) {
             records.delete(key);
         },
+        async clearIf(key, predicate) {
+            const current = records.get(key) ?? null;
+            if (!predicate(current)) {
+                return false;
+            }
+            records.delete(key);
+            return true;
+        },
         async clearAll() {
             records.clear();
         },
@@ -67,6 +86,13 @@ function createMemoryPendingWriteDriver() {
         async set(key, value) {
             records.set(key, value);
         },
+        async setIf(key, value, predicate) {
+            if (!predicate(records.get(key) ?? null)) {
+                return false;
+            }
+            records.set(key, value);
+            return true;
+        },
     };
 }
 function createBrowserPendingWriteDriver({ databaseName, databaseVersion, indexedDB = globalThis.indexedDB, operationTimeoutMs = exports.pendingWriteOperationTimeoutMs, storeName, }) {
@@ -79,7 +105,7 @@ function createBrowserPendingWriteDriver({ databaseName, databaseVersion, indexe
     });
     return driver ? toPendingWriteDriver(driver) : null;
 }
-function createBrowserPendingWriteStore({ databaseName, databaseVersion, indexedDB = globalThis.indexedDB, keyPrefix, normalizePayload, operationTimeoutMs = exports.pendingWriteOperationTimeoutMs, schemaVersion = exports.pendingWriteSchemaVersion, storeName, }) {
+function createBrowserPendingWriteStore({ databaseName, databaseVersion, indexedDB = globalThis.indexedDB, keyPrefix, normalizeLegacyRecord, normalizePayload, operationTimeoutMs = exports.pendingWriteOperationTimeoutMs, schemaVersion = exports.pendingWriteSchemaVersion, storeName, }) {
     const driver = createBrowserPendingWriteDriver({
         databaseName,
         databaseVersion,
@@ -87,11 +113,14 @@ function createBrowserPendingWriteStore({ databaseName, databaseVersion, indexed
         operationTimeoutMs,
         storeName,
     });
-    return createPendingWriteStore(driver ?? createNoopPendingWriteDriver(), { keyPrefix, normalizePayload, schemaVersion });
+    return createPendingWriteStore(driver ?? createNoopPendingWriteDriver(), { keyPrefix, normalizeLegacyRecord, normalizePayload, schemaVersion });
 }
 function createPendingWriteKey({ id, prefix }) {
     return `${prefix}:${encodeURIComponent(id)}`;
 }
+function createPendingWriteSnapshotId() {
+    return globalThis.crypto.randomUUID();
+}
 async function syncPendingWrite({ id, store, sync, }) {
     const pending = await store.get(id);
     if (!pending) {
@@ -100,7 +129,7 @@ async function syncPendingWrite({ id, store, sync, }) {
     await markPendingSnapshot({
         id,
         nextRecord: { ...pending, error: undefined, syncStatus: "syncing" },
-        savedAt: pending.savedAt,
+        snapshotId: pending.snapshotId,
         store,
     });
     try {
@@ -111,18 +140,21 @@ async function syncPendingWrite({ id, store, sync, }) {
         await markPendingSnapshot({
             id,
             nextRecord: { ...pending, error: message, syncStatus: "failed" },
-            savedAt: pending.savedAt,
+            snapshotId: pending.snapshotId,
             store,
         });
         return { error: message, status: "failed" };
     }
-    return (await store.clearIfSavedAt(id, pending.savedAt))
+    return (await store.clearIfSnapshotId(id, pending.snapshotId))
         ? { status: "synced" }
         : { status: "superseded" };
 }
 function createNoopPendingWriteDriver() {
     return {
         async clear() { },
+        async clearIf() {
+            return false;
+        },
         async clearAll() { },
         async close() { },
         async get() {
@@ -132,43 +164,41 @@ function createNoopPendingWriteDriver() {
             return [];
         },
         async set() { },
+        async setIf() {
+            return false;
+        },
     };
 }
 function toPendingWriteDriver(driver) {
     return {
         clear: driver.delete,
+        clearIf: driver.deleteIf,
         clearAll: driver.clear,
         close: driver.close,
         get: driver.get,
         list: driver.list,
         set: driver.set,
+        setIf: driver.setIf,
     };
 }
-async function markPendingSnapshot({ id, nextRecord, savedAt, store, }) {
-    const current = await store.get(id);
-    if (current?.savedAt !== savedAt) {
-        return false;
-    }
-    await store.set(nextRecord);
-    return true;
+async function markPendingSnapshot({ id, nextRecord, snapshotId, store, }) {
+    return store.replaceIfSnapshotId(id, snapshotId, nextRecord);
 }
-function toPendingWriteEnvelope(value, schemaVersion, { normalizePayload }) {
-    if (!value ||
-        typeof value !== "object" ||
-        !("schemaVersion" in value) ||
-        value.schemaVersion !== schemaVersion ||
-        !("record" in value) ||
-        !isPendingWriteRecord(value.record)) {
-        return null;
-    }
-    const record = normalizePendingWriteRecord(value.record, normalizePayload);
+function toPendingWriteEnvelope(value, schemaVersion, { normalizeLegacyRecord, normalizePayload }) {
+    const envelopeRecord = readPendingWriteEnvelopeRecord(value, schemaVersion);
+    const legacyRecord = envelopeRecord
+        ? null
+        : (normalizeLegacyRecord?.(value) ?? null);
+    const record = normalizePendingWriteRecord(envelopeRecord ?? legacyRecord, normalizePayload);
     return record ? { record, schemaVersion } : null;
 }
 function normalizePendingWriteRecord(record, normalizePayload) {
-    if (!normalizePayload) {
-        return record;
+    if (!record) {
+        return null;
     }
-    const payload = normalizePayload(record.payload);
+    const payload = normalizePayload
+        ? normalizePayload(record.payload)
+        : record.payload;
     if (payload === null) {
         return null;
     }
@@ -177,9 +207,24 @@ function normalizePendingWriteRecord(record, normalizePayload) {
         id: record.id,
         payload,
         savedAt: record.savedAt,
+        snapshotId: record.snapshotId ?? createLegacyPendingWriteSnapshotId(record),
         syncStatus: record.syncStatus,
     };
 }
+function readPendingWriteEnvelopeRecord(value, schemaVersion) {
+    if (!value ||
+        typeof value !== "object" ||
+        !("schemaVersion" in value) ||
+        value.schemaVersion !== schemaVersion ||
+        !("record" in value) ||
+        !isPendingWriteRecord(value.record)) {
+        return null;
+    }
+    return value.record;
+}
+function createLegacyPendingWriteSnapshotId(record) {
+    return `legacy:${encodeURIComponent(record.id)}:${encodeURIComponent(record.savedAt)}`;
+}
 function isPendingWriteRecord(value) {
     return (value !== null &&
         typeof value === "object" &&
@@ -187,6 +232,7 @@ function isPendingWriteRecord(value) {
         typeof value.id === "string" &&
         "savedAt" in value &&
         typeof value.savedAt === "string" &&
+        (!("snapshotId" in value) || typeof value.snapshotId === "string") &&
         "syncStatus" in value &&
         (value.syncStatus === "pending" ||
             value.syncStatus === "syncing" ||

package/dist-cjs/readCache.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.browserReadCacheOperationTimeoutMs = exports.readCacheFreshnessMaxAgeMs = exports.readCacheSchemaVersion = void 0;
+exports.browserReadCacheOperationTimeoutMs = exports.identityReadCacheFreshnessMaxAgeMs = exports.durableReadCacheFreshnessMaxAgeMs = exports.readCacheFreshnessMaxAgeMs = exports.readCacheSchemaVersion = void 0;
 exports.createReadCache = createReadCache;
 exports.createMemoryReadCacheDriver = createMemoryReadCacheDriver;
 exports.createBrowserReadCache = createBrowserReadCache;
@@ -10,16 +10,37 @@ exports.loadReadCacheResource = loadReadCacheResource;
 const idbDriver_1 = require("./idbDriver");
 exports.readCacheSchemaVersion = 1;
 exports.readCacheFreshnessMaxAgeMs = 30_000;
+exports.durableReadCacheFreshnessMaxAgeMs = 60 * 60_000;
+exports.identityReadCacheFreshnessMaxAgeMs = 24 * 60 * 60_000;
 exports.browserReadCacheOperationTimeoutMs = 2_000;
-const pendingFreshLoads = new Map();
+const pendingFreshLoads = new WeakMap();
 function createReadCache(driver) {
-    return {
+    let globalVersion = 0;
+    const keyVersions = new Map();
+    let operationQueue = Promise.resolve();
+    const pendingLoads = new Map();
+    function getVersion(key) {
+        return `${globalVersion}:${keyVersions.get(key) ?? 0}`;
+    }
+    function enqueue(operation) {
+        const next = operationQueue.then(operation, operation);
+        operationQueue = next.then(() => undefined, () => undefined);
+        return next;
+    }
+    const cache = {
         async clear() {
-            pendingFreshLoads.clear();
-            await driver.clear();
+            pendingLoads.clear();
+            globalVersion += 1;
+            keyVersions.clear();
+            await enqueue(() => driver.clear());
         },
         async close() {
-            await driver.close?.();
+            await enqueue(async () => driver.close?.());
+        },
+        async delete(key) {
+            pendingLoads.delete(key);
+            keyVersions.set(key, (keyVersions.get(key) ?? 0) + 1);
+            await enqueue(() => driver.delete(key));
         },
         async get(key) {
             const envelope = toReadCacheEnvelope(await driver.get(key));
@@ -31,14 +52,33 @@ function createReadCache(driver) {
                 }
                 : null;
         },
+        getVersion,
         async set(key, value) {
-            await driver.set(key, {
+            await enqueue(() => driver.set(key, {
                 savedAt: new Date().toISOString(),
                 schemaVersion: exports.readCacheSchemaVersion,
                 value,
+            }));
+        },
+        async setIfVersion(key, value, version) {
+            if (getVersion(key) !== version) {
+                return false;
+            }
+            return enqueue(async () => {
+                if (getVersion(key) !== version) {
+                    return false;
+                }
+                await driver.set(key, {
+                    savedAt: new Date().toISOString(),
+                    schemaVersion: exports.readCacheSchemaVersion,
+                    value,
+                });
+                return true;
             });
         },
     };
+    pendingFreshLoads.set(cache, pendingLoads);
+    return cache;
 }
 function createMemoryReadCacheDriver() {
     const records = new Map();
@@ -47,6 +87,9 @@ function createMemoryReadCacheDriver() {
             records.clear();
         },
         async close() { },
+        async delete(key) {
+            records.delete(key);
+        },
         async get(key) {
             return records.get(key) ?? null;
         },
@@ -80,11 +123,21 @@ function createReadCacheKey({ namespace, params = {}, prefix, scope, }) {
         .filter(Boolean)
         .join(":");
 }
-async function readThroughCache({ cache, key, loadFresh, }) {
-    const cached = await cache.get(key);
+async function readThroughCache({ cache, key, loadFresh, maxAgeMs, }) {
+    const resourceCache = cache.capture?.() ?? cache;
+    const version = resourceCache.getVersion(key);
+    const cached = await resourceCache.get(key);
+    if (cached && isCacheFresh(cached.savedAt, maxAgeMs)) {
+        return {
+            data: cached.value,
+            error: null,
+            fromCache: true,
+            stale: false,
+        };
+    }
     try {
         const fresh = await loadFresh();
-        await cache.set(key, fresh);
+        await resourceCache.setIfVersion(key, fresh, version);
         return {
             data: fresh,
             error: null,
@@ -104,8 +157,10 @@ async function readThroughCache({ cache, key, loadFresh, }) {
         throw error;
     }
 }
-async function loadReadCacheResource({ cache, key, loadFresh, maxAgeMs, onUpdate, }) {
-    const cached = await cache.get(key);
+async function loadReadCacheResource({ cache, key, loadFresh, maxAgeMs, onCacheWriteError, onUpdate, skipCache = false, }) {
+    const resourceCache = cache.capture?.() ?? cache;
+    const version = resourceCache.getVersion(key);
+    const cached = skipCache ? null : await resourceCache.get(key);
     if (cached) {
         onUpdate({ data: cached.value, fromCache: true });
         if (isCacheFresh(cached.savedAt, maxAgeMs)) {
@@ -113,9 +168,16 @@ async function loadReadCacheResource({ cache, key, loadFresh, maxAgeMs, onUpdate
         }
     }
     try {
-        const fresh = await loadSharedFreshResource(key, loadFresh);
+        const fresh = await loadSharedFreshResource(resourceCache, key, loadFresh);
         onUpdate({ data: fresh, fromCache: false });
-        void cache.set(key, fresh).catch(() => undefined);
+        void resourceCache.setIfVersion(key, fresh, version).catch((error) => {
+            const normalizedError = normalizeError(error);
+            console.error("[Bayon offline] Unable to refresh the read cache.", {
+                error: normalizedError,
+                key,
+            });
+            onCacheWriteError?.(normalizedError);
+        });
         return fresh;
     }
     catch (error) {
@@ -134,6 +196,7 @@ function createNoopReadCacheDriver() {
     return {
         async clear() { },
         async close() { },
+        async delete() { },
         async get() {
             return null;
         },
@@ -147,22 +210,32 @@ function isCacheFresh(savedAt, maxAgeMs) {
     const savedTime = Date.parse(savedAt);
     return Number.isFinite(savedTime) && Date.now() - savedTime <= maxAgeMs;
 }
-async function loadSharedFreshResource(key, loadFresh) {
-    const pendingLoad = pendingFreshLoads.get(key);
+async function loadSharedFreshResource(cache, key, loadFresh) {
+    const pendingLoads = getPendingFreshLoads(cache);
+    const pendingLoad = pendingLoads.get(key);
     if (pendingLoad) {
         return (await pendingLoad);
     }
     const nextLoad = loadFresh();
-    pendingFreshLoads.set(key, nextLoad);
+    pendingLoads.set(key, nextLoad);
     try {
         return await nextLoad;
     }
     finally {
-        if (pendingFreshLoads.get(key) === nextLoad) {
-            pendingFreshLoads.delete(key);
+        if (pendingLoads.get(key) === nextLoad) {
+            pendingLoads.delete(key);
         }
     }
 }
+function getPendingFreshLoads(cache) {
+    const existing = pendingFreshLoads.get(cache);
+    if (existing) {
+        return existing;
+    }
+    const next = new Map();
+    pendingFreshLoads.set(cache, next);
+    return next;
+}
 function toReadCacheEnvelope(value) {
     if (!value || typeof value !== "object") {
         return null;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bayonai/offline",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "description": "Reusable offline read-cache and pending-write primitives.",
   "license": "MIT",
   "author": "Bayon AI",
@@ -46,8 +46,10 @@
   "scripts": {
     "build": "tsc -p tsconfig.json && node scripts/write-esm-extensions.mjs && tsc -p tsconfig.cjs.json && node scripts/write-cjs.mjs",
     "lint": "tsc --noEmit -p tsconfig.json",
-    "prepack": "pnpm run build",
-    "test": "vitest run"
+    "pack:smoke": "corepack pnpm run build && npm pack --dry-run --access public",
+    "prepack": "corepack pnpm run build",
+    "test": "vitest run",
+    "test:coverage": "vitest run --coverage"
   },
   "dependencies": {
     "idb": "^8.0.3"