@bayonai/offline 0.7.0 → 0.9.0

package/dist/idbDriver.js

@@ -1,4 +1,7 @@
 import { wrap, } from "idb";
+export class OfflineStorageError extends Error {
+    name = "OfflineStorageError";
+}
 export function createIdbKeyValueDriver({ databaseName, databaseVersion = 1, indexedDB = globalThis.indexedDB, operationTimeoutMs, storeName, }) {
     if (!indexedDB) {
         return null;
@@ -9,25 +12,33 @@ export function createIdbKeyValueDriver({ databaseName, databaseVersion = 1, ind
         indexedDB,
         storeName,
     });
+    function runMutation(operationName, mutate) {
+        return runTransactionalStorageOperation({
+            failureMode: "throw",
+            fallback: undefined,
+            operationName,
+            storeName,
+            operation: async (setTransaction, isCancelled) => {
+                const database = await databasePromise;
+                if (isCancelled())
+                    return;
+                const transaction = database.transaction(storeName, "readwrite");
+                setTransaction(transaction);
+                await mutate(transaction.objectStore(storeName));
+                await transaction.done;
+            },
+            timeoutMs: operationTimeoutMs,
+        });
+    }
     return {
         async clear() {
-            await runTransactionalStorageOperation({
-                fallback: undefined,
-                operationName: "clear object store",
-                operation: async (setTransaction) => {
-                    const database = await databasePromise;
-                    const transaction = database.transaction(storeName, "readwrite");
-                    setTransaction(transaction);
-                    await transaction.objectStore(storeName).clear();
-                    await transaction.done;
-                },
-                timeoutMs: operationTimeoutMs,
-            });
+            await runMutation("clear object store", (objectStore) => objectStore.clear());
         },
         async close() {
             await runBrowserStorageOperation({
                 fallback: undefined,
                 operationName: "close database",
+                storeName,
                 operation: async () => {
                     const database = await databasePromise;
                     database.close();
@@ -36,18 +47,7 @@ export function createIdbKeyValueDriver({ databaseName, databaseVersion = 1, ind
             });
         },
         async delete(key) {
-            await runTransactionalStorageOperation({
-                fallback: undefined,
-                operationName: "delete key",
-                operation: async (setTransaction) => {
-                    const database = await databasePromise;
-                    const transaction = database.transaction(storeName, "readwrite");
-                    setTransaction(transaction);
-                    await transaction.objectStore(storeName).delete(key);
-                    await transaction.done;
-                },
-                timeoutMs: operationTimeoutMs,
-            });
+            await runMutation("delete key", (objectStore) => objectStore.delete(key));
         },
         async deleteIf(key, predicate) {
             return runConditionalStorageOperation({
@@ -68,6 +68,7 @@ export function createIdbKeyValueDriver({ databaseName, databaseVersion = 1, ind
             return runBrowserStorageOperation({
                 fallback: null,
                 operationName: "read key",
+                storeName,
                 operation: async () => {
                     const database = await databasePromise;
                     return (await database.get(storeName, key)) ?? null;
@@ -79,6 +80,7 @@ export function createIdbKeyValueDriver({ databaseName, databaseVersion = 1, ind
             return runBrowserStorageOperation({
                 fallback: [],
                 operationName: "list object store",
+                storeName,
                 operation: async () => {
                     const database = await databasePromise;
                     return database.getAll(storeName);
@@ -90,6 +92,7 @@ export function createIdbKeyValueDriver({ databaseName, databaseVersion = 1, ind
             return runBrowserStorageOperation({
                 fallback: [],
                 operationName: "list object-store entries",
+                storeName,
                 operation: async () => {
                     const database = await databasePromise;
                     // Keys and values must come from one transaction. Separate database
@@ -111,18 +114,7 @@ export function createIdbKeyValueDriver({ databaseName, databaseVersion = 1, ind
             });
         },
         async set(key, value) {
-            await runTransactionalStorageOperation({
-                fallback: undefined,
-                operationName: "write key",
-                operation: async (setTransaction) => {
-                    const database = await databasePromise;
-                    const transaction = database.transaction(storeName, "readwrite");
-                    setTransaction(transaction);
-                    await transaction.objectStore(storeName).put(value, key);
-                    await transaction.done;
-                },
-                timeoutMs: operationTimeoutMs,
-            });
+            await runMutation("write key", (objectStore) => objectStore.put(value, key));
         },
         async setIf(key, value, predicate) {
             return runConditionalStorageOperation({
@@ -155,18 +147,27 @@ async function openKeyValueDatabase({ databaseName, databaseVersion, indexedDB,
     }
     return database;
 }
-async function runBrowserStorageOperation({ cancelOnTimeout, fallback, operation, operationName, timeoutMs, }) {
+async function runBrowserStorageOperation({ cancelOnTimeout, failureMode = "fallback", fallback, operation, operationName, storeName, timeoutMs, }) {
     let timeoutId = null;
+    const startedAt = Date.now();
     try {
         return await Promise.race([
             operation(),
-            new Promise((resolve) => {
+            new Promise((resolve, reject) => {
                 timeoutId = setTimeout(() => {
-                    console.error(`IndexedDB timed out while trying to ${operationName}.`, {
+                    console.warn("[Bayon offline] IndexedDB operation timed out.", {
+                        elapsedMs: Date.now() - startedAt,
+                        operationName,
+                        storeName,
                         timeoutMs,
                     });
                     if (!cancelOnTimeout || cancelOnTimeout()) {
-                        resolve(fallback);
+                        if (failureMode === "throw") {
+                            reject(new OfflineStorageError(`IndexedDB timed out while attempting to ${operationName} in ${storeName}.`));
+                        }
+                        else {
+                            resolve(fallback);
+                        }
                     }
                 }, timeoutMs);
             }),
@@ -174,6 +175,11 @@ async function runBrowserStorageOperation({ cancelOnTimeout, fallback, operation
     }
     catch (error) {
         console.error(`IndexedDB failed to ${operationName}.`, { error });
+        if (failureMode === "throw") {
+            if (error instanceof OfflineStorageError)
+                throw error;
+            throw new OfflineStorageError(`IndexedDB failed to ${operationName} in ${storeName}.`, { cause: error });
+        }
         return fallback;
     }
     finally {
@@ -182,12 +188,14 @@ async function runBrowserStorageOperation({ cancelOnTimeout, fallback, operation
         }
     }
 }
-async function runTransactionalStorageOperation({ fallback, operation, operationName, timeoutMs, }) {
+async function runTransactionalStorageOperation({ failureMode, fallback, operation, operationName, storeName, timeoutMs, }) {
     let transaction;
     let cancelled = false;
     return runBrowserStorageOperation({
+        failureMode,
         fallback,
         operationName,
+        storeName,
         timeoutMs,
         cancelOnTimeout() {
             cancelled = true;
@@ -203,14 +211,12 @@ async function runTransactionalStorageOperation({ fallback, operation, operation
             }
         },
         operation: async () => {
-            if (cancelled)
-                return fallback;
             return operation((nextTransaction) => {
                 transaction = nextTransaction;
                 // Aborting can reject transaction.done. The operation also awaits it,
                 // but observing it here prevents a race from becoming unhandled.
                 void transaction.done.catch(() => undefined);
-            });
+            }, () => cancelled);
         },
     });
 }
@@ -218,8 +224,10 @@ async function runConditionalStorageOperation({ apply, databasePromise, operatio
     let transaction;
     let cancelled = false;
     return runBrowserStorageOperation({
+        failureMode: "throw",
         fallback: false,
         operationName,
+        storeName,
         timeoutMs,
         cancelOnTimeout() {
             cancelled = true;

package/dist/index.d.ts

@@ -1,6 +1,7 @@
-export * from "./readCache";
-export * from "./pendingWrites";
-export * from "./browserRecovery";
-export * from "./browserCoordination";
-export * from "./browserFallbackRecovery";
-export * from "./durableCommandStore";
+export * from "./readCache.js";
+export * from "./pendingWrites.js";
+export * from "./browserRecovery.js";
+export * from "./browserCoordination.js";
+export * from "./browserFallbackRecovery.js";
+export * from "./durableCommandStore.js";
+export { OfflineStorageError } from "./idbDriver.js";

package/dist/index.js

@@ -4,3 +4,4 @@ export * from "./browserRecovery.js";
 export * from "./browserCoordination.js";
 export * from "./browserFallbackRecovery.js";
 export * from "./durableCommandStore.js";
+export { OfflineStorageError } from "./idbDriver.js";

package/dist/pendingWrites.d.ts

@@ -1,4 +1,4 @@
-import { type BrowserKeyValueDriverOptions } from "./idbDriver";
+import { type BrowserKeyValueDriverOptions } from "./idbDriver.js";
 export declare const pendingWriteSchemaVersion = 1;
 export declare const pendingWriteOperationTimeoutMs = 2000;
 export declare const pendingWriteSyncLeaseTimeoutMs = 60000;
@@ -22,10 +22,14 @@ export type PendingWritePayloadNormalizer<Payload = unknown> = (payload: unknown
 export type PendingWriteDriver = {
     clear: (key: string) => Promise<void>;
     clearIf: (key: string, predicate: PendingWritePredicate) => Promise<boolean>;
-    clearAll: () => Promise<void>;
+    clearAll?: () => Promise<void>;
     close?: () => Promise<void>;
     get: (key: string) => Promise<unknown | null>;
     list: () => Promise<unknown[]>;
+    listEntries?: () => Promise<Array<{
+        key: string;
+        value: unknown;
+    }>>;
     set: (key: string, value: unknown) => Promise<void>;
     setIf: (key: string, value: unknown, predicate: PendingWritePredicate) => Promise<boolean>;
 };
@@ -94,7 +98,11 @@ export type SyncPendingWritesResult = {
     superseded: number;
     synced: number;
 };
-export type PendingWriteSync<Payload> = (payload: Payload) => Promise<unknown>;
+export type PendingWriteSyncContext = {
+    /** Stable durable-record identity; safe to use as a remote idempotency key. */
+    recordId: string;
+};
+export type PendingWriteSync<Payload, Result = unknown> = (payload: Payload, context: PendingWriteSyncContext) => Promise<Result>;
 export type RunPendingWriteResult<TResult, TQueued> = {
     result: TResult;
     status: "synced";
@@ -130,7 +138,7 @@ 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, 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 createPendingWriteSnapshotId(): string;
 export declare function syncPendingWrite<Payload>({ id, now, store, sync, }: {
     id: string;
     now?: () => string;
@@ -142,7 +150,8 @@ export declare function syncPendingWrite<Payload>({ id, now, store, sync, }: {
  * same store/scope. Callers own the selection predicate and idempotent remote
  * mutation semantics.
  */
-export declare function syncPendingWrites<Payload>({ scopeKey, select, stopOnFailure, store, sync, }: {
+export declare function syncPendingWrites<Payload>({ now, scopeKey, select, stopOnFailure, store, sync, }: {
+    now?: () => string;
     scopeKey?: string;
     select?: (record: PendingWriteRecord<Payload>) => boolean;
     /** Preserve caller ordering by leaving later records for a future retry. */
@@ -161,7 +170,8 @@ export declare function summarizePendingWrites<Payload>(records: Array<PendingWr
  * workspace. Use its `recover` method for background replay and `run` for new
  * writes so a newer remote mutation cannot overtake an older queued mutation.
  */
-export declare function createOrderedPendingWriteExecutor<Payload>({ scopeKey, select, store, sync, }: {
+export declare function createOrderedPendingWriteExecutor<Payload>({ now, scopeKey, select, store, sync, }: {
+    now?: () => string;
     scopeKey?: string;
     select?: (record: PendingWriteRecord<Payload>) => boolean;
     store: PendingWriteStore<Payload>;

package/dist/pendingWrites.js

@@ -1,4 +1,4 @@
-import { createIdbKeyValueDriver, } from "./idbDriver.js";
+import { createIdbKeyValueDriver, OfflineStorageError, } from "./idbDriver.js";
 export const pendingWriteSchemaVersion = 1;
 export const pendingWriteOperationTimeoutMs = 2_000;
 export const pendingWriteSyncLeaseTimeoutMs = 60_000;
@@ -17,6 +17,29 @@ export function createPendingWriteStore(driver, { keyPrefix, normalizeLegacyReco
             }
         }
     };
+    async function listScopedRecords() {
+        const readOptions = { normalizeLegacyRecord, normalizePayload };
+        const entries = await driver.listEntries?.();
+        if (entries) {
+            const keyPrefixBoundary = `${keyPrefix}:`;
+            return entries
+                .filter(({ key }) => key.startsWith(keyPrefixBoundary))
+                .map(({ value }) => toPendingWriteEnvelope(value, schemaVersion, readOptions)
+                ?.record)
+                .filter((record) => Boolean(record));
+        }
+        // Compatibility path for custom drivers created before listEntries was
+        // available. Point reads prove that each candidate belongs to this prefix.
+        const candidateIds = new Set((await driver.list())
+            .map((value) => toPendingWriteEnvelope(value, schemaVersion, readOptions)
+            ?.record.id)
+            .filter((id) => Boolean(id)));
+        const records = await Promise.all([...candidateIds].map(async (id) => {
+            const value = await driver.get(createPendingWriteKey({ id, prefix: keyPrefix }));
+            return toPendingWriteEnvelope(value, schemaVersion, readOptions)?.record;
+        }));
+        return records.filter((record) => Boolean(record));
+    }
     return {
         async claimIfSnapshotId(id, snapshotId, record, now) {
             const claimed = await driver.setIf(createPendingWriteKey({ id, prefix: keyPrefix }), { record, schemaVersion }, (value) => {
@@ -37,7 +60,20 @@ export function createPendingWriteStore(driver, { keyPrefix, normalizeLegacyReco
             notify({ id, type: "clear" });
         },
         async clearAll() {
-            await driver.clearAll();
+            const entries = await driver.listEntries?.();
+            if (entries) {
+                const keyPrefixBoundary = `${keyPrefix}:`;
+                await Promise.all(entries
+                    .filter(({ key }) => key.startsWith(keyPrefixBoundary))
+                    .map(({ key }) => driver.clear(key)));
+            }
+            else {
+                const records = await listScopedRecords();
+                await Promise.all(records.map((record) => driver.clearIf(createPendingWriteKey({ id: record.id, prefix: keyPrefix }), (value) => toPendingWriteEnvelope(value, schemaVersion, {
+                    normalizeLegacyRecord,
+                    normalizePayload,
+                })?.record.snapshotId === record.snapshotId)));
+            }
             notify({ type: "clearAll" });
         },
         async clearIfSnapshotId(id, snapshotId) {
@@ -57,13 +93,7 @@ export function createPendingWriteStore(driver, { keyPrefix, normalizeLegacyReco
             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) ||
+            return (await listScopedRecords()).sort((left, right) => left.savedAt.localeCompare(right.savedAt) ||
                 left.id.localeCompare(right.id));
         },
         async replaceIfSnapshotId(id, snapshotId, record) {
@@ -118,6 +148,9 @@ export function createMemoryPendingWriteDriver() {
         async list() {
             return [...records.values()];
         },
+        async listEntries() {
+            return [...records].map(([key, value]) => ({ key, value }));
+        },
         async set(key, value) {
             records.set(key, value);
         },
@@ -148,14 +181,24 @@ export function createBrowserPendingWriteStore({ databaseName, databaseVersion,
         operationTimeoutMs,
         storeName,
     });
-    return createPendingWriteStore(driver ?? createNoopPendingWriteDriver(), { keyPrefix, normalizeLegacyRecord, normalizePayload, schemaVersion });
+    return createPendingWriteStore(driver ?? createUnavailablePendingWriteDriver(), { keyPrefix, normalizeLegacyRecord, normalizePayload, schemaVersion });
 }
 export function createPendingWriteKey({ id, prefix }) {
     return `${prefix}:${encodeURIComponent(id)}`;
 }
 export function createPendingWriteSnapshotId() {
-    return globalThis.crypto.randomUUID();
+    const randomId = globalThis.crypto?.randomUUID?.();
+    if (randomId)
+        return randomId;
+    pendingWriteSnapshotSequence += 1;
+    return [
+        "snapshot",
+        Date.now().toString(36),
+        pendingWriteSnapshotSequence.toString(36),
+        Math.random().toString(36).slice(2),
+    ].join("-");
 }
+let pendingWriteSnapshotSequence = 0;
 export async function syncPendingWrite({ id, now = () => new Date().toISOString(), store, sync, }) {
     const pending = await store.get(id);
     if (!pending) {
@@ -163,8 +206,7 @@ export async function syncPendingWrite({ id, now = () => new Date().toISOString(
     }
     // A delayed command remains in its ordered lane until its grace period has
     // elapsed. This makes cancellation survive UI unmounts and app restarts.
-    if (pending.notBefore &&
-        Date.parse(pending.notBefore) > Date.parse(now())) {
+    if (pending.notBefore && Date.parse(pending.notBefore) > Date.parse(now())) {
         return { status: "idle" };
     }
     const claimedSnapshotId = createPendingWriteSnapshotId();
@@ -179,7 +221,7 @@ export async function syncPendingWrite({ id, now = () => new Date().toISOString(
         return { status: "superseded" };
     }
     try {
-        await sync(pending.payload);
+        await sync(pending.payload, { recordId: pending.id });
     }
     catch (error) {
         const message = error instanceof Error ? error.message : "Unable to sync pending write.";
@@ -208,7 +250,7 @@ export async function syncPendingWrite({ id, now = () => new Date().toISOString(
  * same store/scope. Callers own the selection predicate and idempotent remote
  * mutation semantics.
  */
-export function syncPendingWrites({ scopeKey = "all", select = () => true, stopOnFailure = false, store, sync, }) {
+export function syncPendingWrites({ now, scopeKey = "all", select = () => true, stopOnFailure = false, store, sync, }) {
     let inFlightByScope = pendingWriteSyncs.get(store);
     if (!inFlightByScope) {
         inFlightByScope = new Map();
@@ -219,6 +261,7 @@ export function syncPendingWrites({ scopeKey = "all", select = () => true, stopO
         return existing;
     }
     const syncRun = performPendingWriteSync({
+        now,
         select,
         stopOnFailure,
         store,
@@ -265,7 +308,7 @@ export function summarizePendingWrites(records) {
     }, { failedCount: 0, pendingCount: 0, syncingCount: 0, totalCount: 0 });
 }
 const pendingWriteSyncs = new WeakMap();
-async function performPendingWriteSync({ select, stopOnFailure, store, sync, }) {
+async function performPendingWriteSync({ now, select, stopOnFailure, store, sync, }) {
     const summary = {
         attempted: 0,
         failed: 0,
@@ -278,6 +321,7 @@ async function performPendingWriteSync({ select, stopOnFailure, store, sync, })
     for (const record of records) {
         const result = await syncPendingWrite({
             id: record.id,
+            now,
             store,
             sync,
         });
@@ -313,7 +357,7 @@ function isPendingWriteSyncClaimAvailable(record, now) {
  * workspace. Use its `recover` method for background replay and `run` for new
  * writes so a newer remote mutation cannot overtake an older queued mutation.
  */
-export function createOrderedPendingWriteExecutor({ scopeKey = "all", select = () => true, store, sync, }) {
+export function createOrderedPendingWriteExecutor({ now, scopeKey = "all", select = () => true, store, sync, }) {
     let execution = Promise.resolve();
     function inOrder(operation) {
         const result = execution.then(operation, operation);
@@ -322,6 +366,7 @@ export function createOrderedPendingWriteExecutor({ scopeKey = "all", select = (
     }
     function recover() {
         return inOrder(() => syncPendingWrites({
+            now,
             scopeKey,
             select,
             stopOnFailure: true,
@@ -337,6 +382,7 @@ export function createOrderedPendingWriteExecutor({ scopeKey = "all", select = (
                     return runPendingWrite(options);
                 }
                 const replay = await syncPendingWrites({
+                    now,
                     scopeKey,
                     select,
                     stopOnFailure: true,
@@ -354,13 +400,13 @@ export function createOrderedPendingWriteExecutor({ scopeKey = "all", select = (
         },
     };
 }
-function createNoopPendingWriteDriver() {
+function createUnavailablePendingWriteDriver() {
+    const unavailable = () => new OfflineStorageError("IndexedDB is unavailable; the pending write was not stored.");
     return {
         async clear() { },
         async clearIf() {
             return false;
         },
-        async clearAll() { },
         async close() { },
         async get() {
             return null;
@@ -368,9 +414,11 @@ function createNoopPendingWriteDriver() {
         async list() {
             return [];
         },
-        async set() { },
+        async set() {
+            throw unavailable();
+        },
         async setIf() {
-            return false;
+            throw unavailable();
         },
     };
 }
@@ -382,6 +430,7 @@ function toPendingWriteDriver(driver) {
         close: driver.close,
         get: driver.get,
         list: driver.list,
+        listEntries: driver.listEntries,
         set: driver.set,
         setIf: driver.setIf,
     };

package/dist/readCache.d.ts

@@ -1,9 +1,9 @@
-import { type BrowserKeyValueDriverOptions } from "./idbDriver";
+import { type BrowserKeyValueDriverOptions } from "./idbDriver.js";
 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 declare const browserReadCacheOperationTimeoutMs = 1000;
 export type ReadCacheHit<T> = {
     fromCache: true;
     savedAt: string;
@@ -29,21 +29,36 @@ export type ReadCache = {
     clear: () => Promise<void>;
     close: () => Promise<void>;
     delete: (key: string) => Promise<void>;
+    /** Advances a key's generation without deleting its retained value. */
+    invalidate?: (key: string) => 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 ReadCachePolicy = {
+    /** Time that a cached value can suppress a remote read. */
+    freshForMs: number;
+    /** Maximum age at which cached data remains eligible as an offline fallback. */
+    retainForMs: number;
+    /** Behavior when revalidation fails while retained data is available. */
+    refreshFailure: "use-retained" | "throw";
+};
+export type ReadCacheStatus = "fresh" | "stale" | "miss";
+/** Payload-free cache lifecycle events suitable for host-owned telemetry. */
+export type ReadCacheOutcome = "fresh-hit" | "stale-hit" | "cache-miss" | "forced-refresh" | "loader-success" | "loader-failure";
 export type ReadThroughCacheResult<T> = {
     data: T;
     error: Error | null;
     fromCache: boolean;
     stale: boolean;
+    status: ReadCacheStatus;
 };
 export type ReadCacheResourceUpdate<T> = {
     data: T;
     error?: Error;
     fromCache: boolean;
+    status: ReadCacheStatus;
 };
 export type BrowserReadCacheOptions = Partial<Pick<BrowserKeyValueDriverOptions, "databaseVersion" | "indexedDB">> & {
     databaseName: string;
@@ -69,22 +84,28 @@ export declare function pruneReadCache({ cache, maxAgeMs, now, }: {
     now?: () => number;
 }): Promise<number>;
 export declare function createReadCacheKey({ namespace, params, prefix, scope, }: ReadCacheKeyOptions): string;
-export declare function readThroughCache<T>({ cache, forceFresh, key, loadFresh, maxAgeMs, }: {
+export declare function readThroughCache<T>({ cache, forceFresh, key, loadFresh, maxAgeMs, onOutcome, policy, }: {
     cache: ReadCache;
     /**
-     * Invalidates the current value before loading. Use after a successful write
-     * when a cached or earlier in-flight response must not become authoritative.
+     * Revalidates after advancing the key generation, retaining the prior value
+     * as a possible fallback if refresh fails.
      */
     forceFresh?: boolean;
     key: string;
     loadFresh: () => Promise<T>;
     maxAgeMs?: number;
+    onOutcome?: (outcome: ReadCacheOutcome) => void;
+    policy?: ReadCachePolicy;
 }): Promise<ReadThroughCacheResult<T>>;
-export declare function loadReadCacheResource<T>({ cache, key, loadFresh, maxAgeMs, onCacheWriteError, onUpdate, skipCache, }: {
+export declare function loadReadCacheResource<T>({ cache, forceFresh, key, loadFresh, maxAgeMs, onOutcome, policy, onCacheWriteError, onUpdate, skipCache, }: {
     cache: ReadCache;
+    /** Revalidate while retaining eligible data as fallback on loader failure. */
+    forceFresh?: boolean;
     key: string;
     loadFresh: () => Promise<T>;
     maxAgeMs?: number;
+    onOutcome?: (outcome: ReadCacheOutcome) => void;
+    policy?: ReadCachePolicy;
     onCacheWriteError?: (error: Error) => void;
     onUpdate: (update: ReadCacheResourceUpdate<T>) => void;
     skipCache?: boolean;