@bayonai/offline 0.8.0 → 0.10.0

package/dist-cjs/pendingWrites.d.ts

@@ -0,0 +1,179 @@
+import { type BrowserKeyValueDriverOptions } from "./idbDriver.js";
+export declare const pendingWriteSchemaVersion = 1;
+export declare const pendingWriteOperationTimeoutMs = 2000;
+export declare const pendingWriteSyncLeaseTimeoutMs = 60000;
+export type PendingWriteStatus = "pending" | "syncing" | "failed";
+export type PendingWriteRecord<Payload = unknown> = {
+    error?: string;
+    id: string;
+    /** Do not execute this accepted command before this ISO timestamp. */
+    notBefore?: string;
+    payload: Payload;
+    savedAt: string;
+    snapshotId: string;
+    /** Timestamp of the active remote-sync claim, absent when not owned. */
+    syncingAt?: 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[]>;
+    listEntries?: () => Promise<Array<{
+        key: string;
+        value: 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 PendingWriteStoreChange<Payload = unknown> = {
+    record: PendingWriteRecord<Payload>;
+    type: "set";
+} | {
+    id: string;
+    type: "clear";
+} | {
+    type: "clearAll";
+} | {
+    record: PendingWriteRecord<Payload>;
+    type: "replace";
+};
+export type PendingWriteStoreChangeListener<Payload = unknown> = (change: PendingWriteStoreChange<Payload>) => void;
+export type PendingWriteStore<Payload = unknown> = {
+    claimIfSnapshotId: (id: string, snapshotId: string, record: PendingWriteRecord<Payload>, now: string) => Promise<boolean>;
+    clear: (id: string) => Promise<void>;
+    clearAll: () => Promise<void>;
+    clearIfSnapshotId: (id: string, snapshotId: string) => Promise<boolean>;
+    close: () => Promise<void>;
+    get: (id: string) => Promise<PendingWriteRecord<Payload> | null>;
+    list: () => Promise<Array<PendingWriteRecord<Payload>>>;
+    replaceIfSnapshotId: (id: string, snapshotId: string, record: PendingWriteRecord<Payload>) => Promise<boolean>;
+    set: (record: PendingWriteRecordInput<Payload>) => Promise<PendingWriteRecord<Payload>>;
+    /**
+     * Observes changes made through this in-memory store instance. It deliberately
+     * does not claim cross-tab/process delivery.
+     */
+    subscribe: (listener: PendingWriteStoreChangeListener<Payload>) => () => void;
+};
+export type PendingWriteStoreOptions<Payload = unknown> = {
+    keyPrefix: string;
+    normalizeLegacyRecord?: PendingWritePayloadNormalizer<PendingWriteRecordInput<Payload>>;
+    normalizePayload?: PendingWritePayloadNormalizer<Payload>;
+    schemaVersion?: number;
+};
+export type BrowserPendingWriteStoreOptions<Payload = unknown> = Partial<Pick<BrowserKeyValueDriverOptions, "databaseVersion" | "indexedDB">> & PendingWriteStoreOptions<Payload> & {
+    databaseName: string;
+    operationTimeoutMs?: number;
+    storeName: string;
+};
+export type PendingWriteKeyOptions = {
+    id: string;
+    prefix: string;
+};
+export type SyncPendingWriteResult = {
+    status: "idle";
+} | {
+    status: "synced";
+} | {
+    status: "superseded";
+} | {
+    error: string;
+    failure: unknown;
+    status: "failed";
+};
+export type SyncPendingWritesResult = {
+    attempted: number;
+    failed: number;
+    idle: number;
+    /** Records still selected after this attempt, including newer superseding writes. */
+    remaining: number;
+    superseded: number;
+    synced: number;
+};
+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";
+} | {
+    queued: TQueued;
+    status: "queued";
+};
+export type PendingWriteRunOptions<TResult, TQueued> = {
+    enqueue: () => Promise<TQueued>;
+    isOnline: () => boolean;
+    shouldQueue: (error: unknown) => boolean;
+    write: () => Promise<TResult>;
+};
+/**
+ * Serializes recovery and new writes for one caller-defined scope.
+ *
+ * A queued write that cannot be replayed stays ahead of later writes. This
+ * preserves remote write order; callers retain ownership of scope selection
+ * and idempotent remote mutation semantics.
+ */
+export type OrderedPendingWriteExecutor<Payload> = {
+    recover: () => Promise<SyncPendingWritesResult>;
+    run: <TResult, TQueued>(options: PendingWriteRunOptions<TResult, TQueued>) => Promise<RunPendingWriteResult<TResult, TQueued>>;
+};
+export type PendingWriteSummary = {
+    failedCount: number;
+    pendingCount: number;
+    syncingCount: number;
+    totalCount: number;
+};
+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, normalizeLegacyRecord, normalizePayload, operationTimeoutMs, schemaVersion, storeName, }: BrowserPendingWriteStoreOptions<Payload>): PendingWriteStore<Payload>;
+export declare function createPendingWriteKey({ id, prefix }: PendingWriteKeyOptions): string;
+export declare function createPendingWriteSnapshotId(): string;
+export declare function syncPendingWrite<Payload>({ id, now, store, sync, }: {
+    id: string;
+    now?: () => string;
+    store: PendingWriteStore<Payload>;
+    sync: PendingWriteSync<Payload>;
+}): Promise<SyncPendingWriteResult>;
+/**
+ * Replays selected writes oldest first and coalesces overlapping runs for the
+ * same store/scope. Callers own the selection predicate and idempotent remote
+ * mutation semantics.
+ */
+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. */
+    stopOnFailure?: boolean;
+    store: PendingWriteStore<Payload>;
+    sync: PendingWriteSync<Payload>;
+}): Promise<SyncPendingWritesResult>;
+/**
+ * Attempts a remote write now and persists a caller-created durable fallback
+ * only when offline or when the supplied retry classifier accepts the error.
+ */
+export declare function runPendingWrite<TResult, TQueued>({ enqueue, isOnline, shouldQueue, write, }: PendingWriteRunOptions<TResult, TQueued>): Promise<RunPendingWriteResult<TResult, TQueued>>;
+export declare function summarizePendingWrites<Payload>(records: Array<PendingWriteRecord<Payload>>): PendingWriteSummary;
+/**
+ * Creates a serial execution lane for a durable scope such as one user or
+ * 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>({ now, scopeKey, select, store, sync, }: {
+    now?: () => string;
+    scopeKey?: string;
+    select?: (record: PendingWriteRecord<Payload>) => boolean;
+    store: PendingWriteStore<Payload>;
+    sync: PendingWriteSync<Payload>;
+}): OrderedPendingWriteExecutor<Payload>;

package/dist-cjs/pendingWrites.js

@@ -31,6 +31,29 @@ function createPendingWriteStore(driver, { keyPrefix, normalizeLegacyRecord, nor
             }
         }
     };
+    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) => {
@@ -51,7 +74,20 @@ function createPendingWriteStore(driver, { keyPrefix, normalizeLegacyRecord, nor
             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) {
@@ -71,13 +107,7 @@ function createPendingWriteStore(driver, { keyPrefix, normalizeLegacyRecord, nor
             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) {
@@ -132,6 +162,9 @@ function createMemoryPendingWriteDriver() {
         async list() {
             return [...records.values()];
         },
+        async listEntries() {
+            return [...records].map(([key, value]) => ({ key, value }));
+        },
         async set(key, value) {
             records.set(key, value);
         },
@@ -151,6 +184,7 @@ function createBrowserPendingWriteDriver({ databaseName, databaseVersion, indexe
         indexedDB,
         operationTimeoutMs,
         storeName,
+        readFailureMode: "throw",
     });
     return driver ? toPendingWriteDriver(driver) : null;
 }
@@ -388,13 +422,12 @@ function createUnavailablePendingWriteDriver() {
         async clearIf() {
             return false;
         },
-        async clearAll() { },
         async close() { },
         async get() {
-            return null;
+            throw unavailable();
         },
         async list() {
-            return [];
+            throw unavailable();
         },
         async set() {
             throw unavailable();
@@ -412,6 +445,7 @@ function toPendingWriteDriver(driver) {
         close: driver.close,
         get: driver.get,
         list: driver.list,
+        listEntries: driver.listEntries,
         set: driver.set,
         setIf: driver.setIf,
     };

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/readCache.d.ts

@@ -0,0 +1,112 @@
+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 = 1000;
+export type ReadCacheHit<T> = {
+    fromCache: true;
+    savedAt: string;
+    value: T;
+};
+export type ReadCacheDriver = {
+    clear: () => Promise<void>;
+    close?: () => Promise<void>;
+    delete: (key: string) => Promise<void>;
+    get: (key: string) => Promise<unknown | null>;
+    listEntries?: () => Promise<Array<{
+        key: string;
+        value: unknown;
+    }>>;
+    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>;
+    /** 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;
+    operationTimeoutMs?: number;
+    storeName: string;
+};
+export type ReadCacheKeyOptions = {
+    namespace: string;
+    params?: Record<string, string | number | boolean | null | undefined>;
+    prefix: string;
+    scope: string;
+};
+export declare function createReadCache(driver: ReadCacheDriver): ReadCache;
+export declare function createMemoryReadCacheDriver(): ReadCacheDriver;
+export declare function createBrowserReadCache({ databaseName, databaseVersion, indexedDB, operationTimeoutMs, storeName, }: BrowserReadCacheOptions): ReadCache;
+/**
+ * Deletes only valid read-cache envelopes older than the supplied age. It is
+ * opt-in and returns zero for custom cache adapters that cannot enumerate keys.
+ */
+export declare function pruneReadCache({ cache, maxAgeMs, now, }: {
+    cache: ReadCache;
+    maxAgeMs: number;
+    now?: () => number;
+}): Promise<number>;
+export declare function createReadCacheKey({ namespace, params, prefix, scope, }: ReadCacheKeyOptions): string;
+export declare function readThroughCache<T>({ cache, forceFresh, key, loadFresh, maxAgeMs, onOutcome, policy, }: {
+    cache: ReadCache;
+    /**
+     * 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, 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;
+}): Promise<T>;

package/dist-cjs/readCache.js

@@ -26,6 +26,10 @@ function createReadCache(driver) {
     function getVersion(key) {
         return `${globalVersion}:${keyVersions.get(key) ?? 0}`;
     }
+    function invalidate(key) {
+        pendingLoads.delete(key);
+        keyVersions.set(key, (keyVersions.get(key) ?? 0) + 1);
+    }
     function enqueue(operation) {
         const next = operationQueue.then(operation, operation);
         operationQueue = next.then(() => undefined, () => undefined);
@@ -42,10 +46,10 @@ function createReadCache(driver) {
             await enqueue(async () => driver.close?.());
         },
         async delete(key) {
-            pendingLoads.delete(key);
-            keyVersions.set(key, (keyVersions.get(key) ?? 0) + 1);
+            invalidate(key);
             await enqueue(() => driver.delete(key));
         },
+        invalidate,
         async get(key) {
             const envelope = toReadCacheEnvelope(await driver.get(key));
             return envelope
@@ -162,13 +166,21 @@ function createReadCacheKey({ namespace, params = {}, prefix, scope, }) {
         .filter(Boolean)
         .join(":");
 }
-async function readThroughCache({ cache, forceFresh = false, key, loadFresh, maxAgeMs, }) {
+async function readThroughCache({ cache, forceFresh = false, key, loadFresh, maxAgeMs, onOutcome, policy, }) {
     const resourceCache = cache.capture?.() ?? cache;
+    const resolvedPolicy = resolvePolicy(policy, maxAgeMs);
+    const forcedFallback = forceFresh ? await resourceCache.get(key) : null;
     if (forceFresh) {
-        // Deletion advances the cache version, so a request started before this
-        // post-write refresh cannot restore stale data after it finishes.
+        reportReadCacheOutcome(onOutcome, "forced-refresh");
+        // Built-in caches advance generation without deleting fallback data.
+        // Legacy custom adapters retain their old delete behavior.
         try {
-            await resourceCache.delete(key);
+            if (resourceCache.invalidate) {
+                resourceCache.invalidate(key);
+            }
+            else {
+                await resourceCache.delete(key);
+            }
         }
         catch (error) {
             console.error("[Bayon offline] Unable to invalidate the read cache.", {
@@ -178,17 +190,22 @@ async function readThroughCache({ cache, forceFresh = false, key, loadFresh, max
         }
     }
     const version = resourceCache.getVersion(key);
-    const cached = await resourceCache.get(key);
-    if (cached && isCacheFresh(cached.savedAt, maxAgeMs)) {
+    const cached = forcedFallback ?? (await resourceCache.get(key));
+    const retained = cached && isCacheRetained(cached.savedAt, resolvedPolicy);
+    if (!forceFresh && retained && isCacheFresh(cached.savedAt, resolvedPolicy)) {
+        reportReadCacheOutcome(onOutcome, "fresh-hit");
         return {
             data: cached.value,
             error: null,
             fromCache: true,
             stale: false,
+            status: "fresh",
         };
     }
+    reportReadCacheOutcome(onOutcome, retained ? "stale-hit" : "cache-miss");
     try {
         const fresh = await loadSharedFreshResource(resourceCache, key, loadFresh);
+        reportReadCacheOutcome(onOutcome, "loader-success");
         try {
             await resourceCache.setIfVersion(key, fresh, version);
         }
@@ -203,33 +220,74 @@ async function readThroughCache({ cache, forceFresh = false, key, loadFresh, max
             error: null,
             fromCache: false,
             stale: false,
+            status: retained ? "fresh" : "miss",
         };
     }
     catch (error) {
-        if (cached) {
+        reportReadCacheOutcome(onOutcome, "loader-failure");
+        if (retained && resolvedPolicy.refreshFailure === "use-retained") {
             return {
                 data: cached.value,
                 error: normalizeError(error),
                 fromCache: true,
                 stale: true,
+                status: "stale",
             };
         }
         throw error;
     }
 }
-async function loadReadCacheResource({ cache, key, loadFresh, maxAgeMs, onCacheWriteError, onUpdate, skipCache = false, }) {
+async function loadReadCacheResource({ cache, forceFresh = false, key, loadFresh, maxAgeMs, onOutcome, policy, onCacheWriteError, onUpdate, skipCache = false, }) {
     const resourceCache = cache.capture?.() ?? cache;
+    const resolvedPolicy = resolvePolicy(policy, maxAgeMs);
+    const forcedFallback = forceFresh ? await resourceCache.get(key) : null;
+    if (forceFresh) {
+        reportReadCacheOutcome(onOutcome, "forced-refresh");
+        try {
+            if (resourceCache.invalidate) {
+                resourceCache.invalidate(key);
+            }
+            else {
+                await resourceCache.delete(key);
+            }
+        }
+        catch (error) {
+            console.error("[Bayon offline] Unable to invalidate the read cache.", {
+                error: normalizeError(error),
+                key,
+            });
+        }
+    }
     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)) {
+    const cached = skipCache
+        ? null
+        : (forcedFallback ?? (await resourceCache.get(key)));
+    const retained = cached && isCacheRetained(cached.savedAt, resolvedPolicy);
+    if (retained) {
+        const fresh = isCacheFresh(cached.savedAt, resolvedPolicy);
+        reportReadCacheOutcome(onOutcome, fresh && !forceFresh ? "fresh-hit" : "stale-hit");
+        onUpdate({
+            data: cached.value,
+            fromCache: true,
+            status: fresh && !forceFresh ? "fresh" : "stale",
+        });
+        if (fresh && !forceFresh) {
             return cached.value;
         }
     }
+    else {
+        reportReadCacheOutcome(onOutcome, "cache-miss");
+    }
     try {
         const fresh = await loadSharedFreshResource(resourceCache, key, loadFresh);
-        onUpdate({ data: fresh, fromCache: false });
+        reportReadCacheOutcome(onOutcome, "loader-success");
+        if (resourceCache.getVersion(key) === version) {
+            onUpdate({
+                data: fresh,
+                fromCache: false,
+                status: retained ? "fresh" : "miss",
+            });
+        }
         void resourceCache.setIfVersion(key, fresh, version).catch((error) => {
             const normalizedError = normalizeError(error);
             console.error("[Bayon offline] Unable to refresh the read cache.", {
@@ -241,17 +299,32 @@ async function loadReadCacheResource({ cache, key, loadFresh, maxAgeMs, onCacheW
         return fresh;
     }
     catch (error) {
-        if (!cached) {
+        reportReadCacheOutcome(onOutcome, "loader-failure");
+        if (!retained || resolvedPolicy.refreshFailure === "throw") {
             throw error;
         }
         onUpdate({
             data: cached.value,
             error: normalizeError(error),
             fromCache: true,
+            status: "stale",
         });
         return cached.value;
     }
 }
+function reportReadCacheOutcome(onOutcome, outcome) {
+    if (!onOutcome)
+        return;
+    try {
+        onOutcome(outcome);
+    }
+    catch (error) {
+        console.error("[Bayon offline] Read-cache outcome callback failed.", {
+            error: normalizeError(error),
+            outcome,
+        });
+    }
+}
 function createNoopReadCacheDriver() {
     return {
         async clear() { },
@@ -266,12 +339,33 @@ function createNoopReadCacheDriver() {
         async set() { },
     };
 }
-function isCacheFresh(savedAt, maxAgeMs) {
-    if (!maxAgeMs || maxAgeMs <= 0) {
+function isCacheFresh(savedAt, policy) {
+    if (policy.freshForMs <= 0) {
         return false;
     }
     const savedTime = Date.parse(savedAt);
-    return Number.isFinite(savedTime) && Date.now() - savedTime <= maxAgeMs;
+    return (Number.isFinite(savedTime) && Date.now() - savedTime <= policy.freshForMs);
+}
+function resolvePolicy(policy, maxAgeMs) {
+    if (policy) {
+        if (!Number.isFinite(policy.freshForMs) ||
+            policy.freshForMs < 0 ||
+            !Number.isFinite(policy.retainForMs) ||
+            policy.retainForMs < policy.freshForMs ||
+            !["use-retained", "throw"].includes(policy.refreshFailure)) {
+            throw new RangeError("[Bayon offline] Invalid read-cache policy: require finite non-negative durations, retainForMs >= freshForMs, and a supported refreshFailure mode.");
+        }
+        return policy;
+    }
+    return {
+        freshForMs: maxAgeMs ?? 0,
+        retainForMs: Number.POSITIVE_INFINITY,
+        refreshFailure: "use-retained",
+    };
+}
+function isCacheRetained(savedAt, policy) {
+    const savedTime = Date.parse(savedAt);
+    return (Number.isFinite(savedTime) && Date.now() - savedTime <= policy.retainForMs);
 }
 async function loadSharedFreshResource(cache, key, loadFresh) {
     const pendingLoads = getPendingFreshLoads(cache);