@bayonai/offline 0.12.0 → 0.13.0

package/CHANGELOG.md

@@ -1,6 +1,13 @@
 # Changelog
 
-## 0.12.0 candidate - 2026-11-05
+## 0.13.0 - 2026-11-06
+
+- Add opt-in host-classified read failure handling, conditional terminal
+  retirement, source-required reads and layered provenance without renewing
+  retained cache age. Snapshot identifiers protect newer cross-instance writes;
+  existing version-one envelopes remain readable without a database upgrade.
+
+## 0.12.0 - 2026-11-06
 
 - Add framework-neutral pending-change projection and observable tracker, with host-supplied existing queues/drafts, account and stale-read fencing, stable external-store snapshots, grouping/counts/guidance, and retained last known records on read failures.
 

package/README.md

@@ -74,6 +74,15 @@ exceptions are logged and isolated from the read.
 
 When refresh fails, `refreshFailure: "use-retained"` returns retained data
 with `status: "stale"` and the error; `"throw"` propagates the loader error.
+An opt-in callback can classify the original failure as `"use-retained"`,
+`"throw"`, or `"retire"`. Retire propagates the original failure and
+conditionally removes the captured snapshot; a later confirmation is preserved.
+Built-in memory and IndexedDB drivers support atomic snapshot comparison.
+Custom adapters must implement `deleteIfVersion` with equivalent atomic
+ownership checks; without it, retirement is logged and cannot be guaranteed.
+New envelopes carry an opaque snapshot identifier. Existing version-one
+envelopes remain readable; legacy comparison is limited to serializable values
+and cannot distinguish identical writes by older, identifier-unaware clients.
 This also applies to forced refresh. Set `forceFresh: true` on
 `loadReadCacheResource` or `readThroughCache` to bypass freshness, retain
 eligible data as the failure fallback, and advance the cache generation so an
@@ -81,6 +90,19 @@ older in-flight load cannot overwrite the refresh. `readThroughCache` returns
 the `status` field alongside its existing `fromCache`, `stale`, and `error`
 fields.
 
+Set `includeProvenance: true` to receive `cache-hit`, `source-confirmed`, or
+`retained-fallback` provenance. Cache-derived results include their original
+`savedAt`; fallback also carries `originalError` without normalizing it. Layered
+adapters may use `loadFreshResult` to pass a provenance-bearing
+`readThroughCache` result. Cached and fallback values from an inner layer are
+not persisted as fresh outer confirmations. `requireSource: true` rejects
+cached or fallback results and preserves a fallback's original failure. The
+host still owns authorization, account scoping and retention durations.
+Source confirmations include `confirmedAt` when provenance is requested;
+the built-in cache preserves that time on outer writes. Custom adapters may
+implement `setIfVersionAt` to preserve it. Without that capability, layered
+confirmations are delivered but not persisted by the outer adapter.
+
 For compatibility, callers that omit `policy` retain the previous `maxAgeMs`
 freshness behavior and have no age-based fallback expiry. New callers should
 use `policy`; when supplied it takes precedence over the legacy `maxAgeMs`.
@@ -383,7 +405,7 @@ pnpm --filter @bayonai/offline pack:smoke
 2. Run the 100% coverage gate and production dependency audit.
 3. Run `pnpm --filter @bayonai/offline pack:smoke` and confirm the tarball
    includes only `package.json`, `dist`, `dist-cjs`, `README.md`,
-   `CHANGELOG.md`, and `LICENSE`.
+   `CHANGELOG.md`, `RECOVERY.md`, and `LICENSE`.
 4. Install the generated tarball into an isolated consumer and verify ESM,
    CommonJS, and TypeScript declaration imports.
 5. Confirm `package.json` metadata, version, repository, license, and

package/dist/pendingWriteConsolidation.js

@@ -35,7 +35,8 @@ export function projectPendingWriteFinalState(records, getKey, { isBarrier = ()
         const previous = latest.get(key);
         if (previous) {
             superseded.add(previous);
-            for (const effect of dependents.get(key) ?? [])
+            // Every latest entry creates its matching dependency list below.
+            for (const effect of dependents.get(key))
                 superseded.add(effect);
         }
         latest.set(key, record);

package/dist/readCache.d.ts

@@ -13,12 +13,14 @@ export type ReadCacheDriver = {
     clear: () => Promise<void>;
     close?: () => Promise<void>;
     delete: (key: string) => Promise<void>;
+    deleteIf?: (key: string, predicate: (value: unknown | null) => boolean) => Promise<boolean>;
     get: (key: string) => Promise<unknown | null>;
     listEntries?: () => Promise<Array<{
         key: string;
         value: unknown;
     }>>;
     set: (key: string, value: unknown) => Promise<void>;
+    setIf?: (key: string, value: unknown, predicate: (value: unknown | null) => boolean) => Promise<boolean>;
 };
 export type ReadCache = {
     /**
@@ -29,12 +31,15 @@ export type ReadCache = {
     clear: () => Promise<void>;
     close: () => Promise<void>;
     delete: (key: string) => Promise<void>;
+    /** Retire only a snapshot still owned by the captured generation. */
+    deleteIfVersion?: (key: string, version: string, snapshot: ReadCacheHit<unknown>) => Promise<boolean>;
     /** 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>;
+    setIfVersion: <T>(key: string, value: T, version: string, snapshot?: ReadCacheHit<unknown> | null, confirmedAt?: string) => Promise<boolean>;
+    setIfVersionAt?: <T>(key: string, value: T, version: string, snapshot: ReadCacheHit<unknown> | null, confirmedAt: string) => Promise<boolean>;
 };
 export type ReadCachePolicy = {
     /** Time that a cached value can suppress a remote read. */
@@ -42,9 +47,10 @@ export type ReadCachePolicy = {
     /** 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";
+    refreshFailure: "use-retained" | "throw" | ((error: unknown) => "use-retained" | "throw" | "retire");
 };
 export type ReadCacheStatus = "fresh" | "stale" | "miss";
+export type ReadCacheProvenance = "cache-hit" | "source-confirmed" | "retained-fallback";
 /** 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> = {
@@ -53,12 +59,27 @@ export type ReadThroughCacheResult<T> = {
     fromCache: boolean;
     stale: boolean;
     status: ReadCacheStatus;
+    provenance?: ReadCacheProvenance;
+    confirmedAt?: string;
+    savedAt?: string;
+    originalError?: unknown;
 };
 export type ReadCacheResourceUpdate<T> = {
     data: T;
     error?: Error;
     fromCache: boolean;
     status: ReadCacheStatus;
+    provenance?: ReadCacheProvenance;
+    confirmedAt?: string;
+    savedAt?: string;
+    originalError?: unknown;
+};
+export type ReadCacheLoader<T> = {
+    loadFresh: () => Promise<T>;
+    loadFreshResult?: never;
+} | {
+    loadFresh?: never;
+    loadFreshResult: () => Promise<ReadThroughCacheResult<T>>;
 };
 export type BrowserReadCacheOptions = Partial<Pick<BrowserKeyValueDriverOptions, "databaseVersion" | "indexedDB">> & {
     databaseName: string;
@@ -84,29 +105,31 @@ 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, onOutcome, policy, }: {
+export declare function readThroughCache<T>({ cache, forceFresh, includeProvenance, key, loadFresh, loadFreshResult, maxAgeMs, onOutcome, policy, requireSource, }: {
     cache: ReadCache;
     /**
      * Revalidates after advancing the key generation, retaining the prior value
      * as a possible fallback if refresh fails.
      */
     forceFresh?: boolean;
+    includeProvenance?: 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, }: {
+    requireSource?: boolean;
+} & ReadCacheLoader<T>): Promise<ReadThroughCacheResult<T>>;
+export declare function loadReadCacheResource<T>({ cache, forceFresh, includeProvenance, key, loadFresh, loadFreshResult, maxAgeMs, onOutcome, policy, onCacheWriteError, onUpdate, skipCache, requireSource, }: {
     cache: ReadCache;
     /** Revalidate while retaining eligible data as fallback on loader failure. */
     forceFresh?: boolean;
+    includeProvenance?: 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>;
+    requireSource?: boolean;
+} & ReadCacheLoader<T>): Promise<T>;

package/dist/readCache.js

@@ -1,4 +1,5 @@
 import { createIdbKeyValueDriver, } from "./idbDriver.js";
+import { createPendingWriteSnapshotId } from "./pendingWrites.js";
 export const readCacheSchemaVersion = 1;
 export const readCacheFreshnessMaxAgeMs = 30_000;
 export const durableReadCacheFreshnessMaxAgeMs = 60 * 60_000;
@@ -13,6 +14,28 @@ export function createReadCache(driver) {
     const keyVersions = new Map();
     let operationQueue = Promise.resolve();
     const pendingLoads = new Map();
+    const capturedSnapshots = new WeakMap();
+    function ownsSnapshot(current, snapshot) {
+        if (!snapshot)
+            return current === null || toReadCacheEnvelope(current) === null;
+        const captured = capturedSnapshots.get(snapshot);
+        const envelope = toReadCacheEnvelope(current);
+        if (!captured || !envelope)
+            return false;
+        if (captured.snapshotId)
+            return envelope.snapshotId === captured.snapshotId;
+        if (envelope.snapshotId || envelope.savedAt !== captured.savedAt)
+            return false;
+        try {
+            if (!isComparableLegacyValue(envelope.value) ||
+                !isComparableLegacyValue(captured.value))
+                return false;
+            return JSON.stringify(envelope.value) === JSON.stringify(captured.value);
+        }
+        catch {
+            return false;
+        }
+    }
     function getVersion(key) {
         return `${globalVersion}:${keyVersions.get(key) ?? 0}`;
     }
@@ -25,6 +48,30 @@ export function createReadCache(driver) {
         operationQueue = next.then(() => undefined, () => undefined);
         return next;
     }
+    async function writeIfVersion(key, value, version, snapshot, savedAt) {
+        if (getVersion(key) !== version)
+            return false;
+        return enqueue(async () => {
+            if (getVersion(key) !== version)
+                return false;
+            const next = {
+                savedAt,
+                schemaVersion: readCacheSchemaVersion,
+                snapshotId: createPendingWriteSnapshotId(),
+                value,
+            };
+            if (snapshot !== undefined && driver.setIf) {
+                const written = await driver.setIf(key, next, (current) => getVersion(key) === version && ownsSnapshot(current, snapshot));
+                if (!written)
+                    return false;
+            }
+            else {
+                await driver.set(key, next);
+            }
+            invalidate(key);
+            return true;
+        });
+    }
     const cache = {
         async clear() {
             pendingLoads.clear();
@@ -39,40 +86,50 @@ export function createReadCache(driver) {
             invalidate(key);
             await enqueue(() => driver.delete(key));
         },
+        async deleteIfVersion(key, version, snapshot) {
+            return enqueue(async () => {
+                if (getVersion(key) !== version)
+                    return false;
+                if (!capturedSnapshots.has(snapshot) || !driver.deleteIf) {
+                    console.error("[Bayon offline] Cannot safely retire a read-cache snapshot: atomic deletion is unavailable.", { key });
+                    return false;
+                }
+                const deleted = await driver.deleteIf(key, (current) => {
+                    return getVersion(key) === version && ownsSnapshot(current, snapshot);
+                });
+                if (deleted)
+                    invalidate(key);
+                return deleted;
+            });
+        },
         invalidate,
         async get(key) {
             const envelope = toReadCacheEnvelope(await driver.get(key));
-            return envelope
-                ? {
-                    fromCache: true,
-                    savedAt: envelope.savedAt,
-                    value: envelope.value,
-                }
-                : null;
+            if (!envelope)
+                return null;
+            const hit = {
+                fromCache: true,
+                savedAt: envelope.savedAt,
+                value: envelope.value,
+            };
+            capturedSnapshots.set(hit, envelope);
+            return hit;
         },
         getVersion,
         async set(key, value) {
+            invalidate(key);
             await enqueue(() => driver.set(key, {
                 savedAt: new Date().toISOString(),
                 schemaVersion: readCacheSchemaVersion,
+                snapshotId: createPendingWriteSnapshotId(),
                 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;
-            });
+        async setIfVersion(key, value, version, snapshot, confirmedAt) {
+            return writeIfVersion(key, value, version, snapshot, confirmedAt ?? new Date().toISOString());
+        },
+        async setIfVersionAt(key, value, version, snapshot, confirmedAt) {
+            return writeIfVersion(key, value, version, snapshot, confirmedAt);
         },
     };
     pendingFreshLoads.set(cache, pendingLoads);
@@ -103,6 +160,12 @@ export function createMemoryReadCacheDriver() {
         async delete(key) {
             records.delete(key);
         },
+        async deleteIf(key, predicate) {
+            if (!predicate(records.get(key) ?? null))
+                return false;
+            records.delete(key);
+            return true;
+        },
         async get(key) {
             return records.get(key) ?? null;
         },
@@ -112,6 +175,12 @@ export function createMemoryReadCacheDriver() {
         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 createBrowserReadCache({ databaseName, databaseVersion, indexedDB = globalThis.indexedDB, operationTimeoutMs = browserReadCacheOperationTimeoutMs, storeName, }) {
@@ -127,9 +196,11 @@ export function createBrowserReadCache({ databaseName, databaseVersion, indexedD
             clear: driver.clear,
             close: driver.close,
             delete: driver.delete,
+            deleteIf: driver.deleteIf,
             get: driver.get,
             listEntries: driver.listEntries,
             set: driver.set,
+            setIf: driver.setIf,
         }
         : createNoopReadCacheDriver());
 }
@@ -156,10 +227,12 @@ export function createReadCacheKey({ namespace, params = {}, prefix, scope, }) {
         .filter(Boolean)
         .join(":");
 }
-export async function readThroughCache({ cache, forceFresh = false, key, loadFresh, maxAgeMs, onOutcome, policy, }) {
+export async function readThroughCache({ cache, forceFresh = false, includeProvenance = false, key, loadFresh, loadFreshResult, maxAgeMs, onOutcome, policy, requireSource = false, }) {
     const resourceCache = cache.capture?.() ?? cache;
     const resolvedPolicy = resolvePolicy(policy, maxAgeMs);
+    const capturedVersion = resourceCache.getVersion(key);
     const forcedFallback = forceFresh ? await resourceCache.get(key) : null;
+    const changedDuringCapture = forceFresh && resourceCache.getVersion(key) !== capturedVersion;
     if (forceFresh) {
         reportReadCacheOutcome(onOutcome, "forced-refresh");
         // Built-in caches advance generation without deleting fallback data.
@@ -180,9 +253,13 @@ export async function readThroughCache({ cache, forceFresh = false, key, loadFre
         }
     }
     const version = resourceCache.getVersion(key);
+    const retirementVersion = changedDuringCapture ? capturedVersion : version;
     const cached = forcedFallback ?? (await resourceCache.get(key));
     const retained = cached && isCacheRetained(cached.savedAt, resolvedPolicy);
-    if (!forceFresh && retained && isCacheFresh(cached.savedAt, resolvedPolicy)) {
+    if (!forceFresh &&
+        !requireSource &&
+        retained &&
+        isCacheFresh(cached.savedAt, resolvedPolicy)) {
         reportReadCacheOutcome(onOutcome, "fresh-hit");
         return {
             data: cached.value,
@@ -190,14 +267,33 @@ export async function readThroughCache({ cache, forceFresh = false, key, loadFre
             fromCache: true,
             stale: false,
             status: "fresh",
+            ...(includeProvenance
+                ? { provenance: "cache-hit", savedAt: cached.savedAt }
+                : {}),
         };
     }
     reportReadCacheOutcome(onOutcome, retained ? "stale-hit" : "cache-miss");
     try {
-        const fresh = await loadSharedFreshResource(resourceCache, key, loadFresh);
+        const source = await loadSharedFreshResource(resourceCache, key, () => resolveFreshLoad(loadFresh, loadFreshResult));
+        if (source.provenance !== "source-confirmed") {
+            if (requireSource)
+                throw (source.originalError ??
+                    source.error ??
+                    new Error("[Bayon offline] Source confirmation was required."));
+            return includeProvenance
+                ? source
+                : {
+                    data: source.data,
+                    error: source.error,
+                    fromCache: source.fromCache,
+                    stale: source.stale,
+                    status: source.status,
+                };
+        }
+        const fresh = source.data;
         reportReadCacheOutcome(onOutcome, "loader-success");
         try {
-            await resourceCache.setIfVersion(key, fresh, version);
+            await writeConfirmedResource(resourceCache, key, fresh, version, cached, source.confirmedAt, Boolean(loadFreshResult));
         }
         catch (error) {
             console.error("[Bayon offline] Unable to refresh the read cache.", {
@@ -211,26 +307,44 @@ export async function readThroughCache({ cache, forceFresh = false, key, loadFre
             fromCache: false,
             stale: false,
             status: retained ? "fresh" : "miss",
+            ...(includeProvenance
+                ? {
+                    provenance: "source-confirmed",
+                    confirmedAt: source.confirmedAt,
+                }
+                : {}),
         };
     }
     catch (error) {
         reportReadCacheOutcome(onOutcome, "loader-failure");
-        if (retained && resolvedPolicy.refreshFailure === "use-retained") {
+        if (error instanceof ReadCacheLoaderContractError)
+            throw error;
+        const failure = await handleReadFailure(resourceCache, key, retirementVersion, cached, resolvedPolicy, error);
+        if (!requireSource && retained && failure === "use-retained") {
             return {
                 data: cached.value,
                 error: normalizeError(error),
                 fromCache: true,
                 stale: true,
                 status: "stale",
+                ...(includeProvenance
+                    ? {
+                        provenance: "retained-fallback",
+                        savedAt: cached.savedAt,
+                        originalError: error,
+                    }
+                    : {}),
             };
         }
         throw error;
     }
 }
-export async function loadReadCacheResource({ cache, forceFresh = false, key, loadFresh, maxAgeMs, onOutcome, policy, onCacheWriteError, onUpdate, skipCache = false, }) {
+export async function loadReadCacheResource({ cache, forceFresh = false, includeProvenance = false, key, loadFresh, loadFreshResult, maxAgeMs, onOutcome, policy, onCacheWriteError, onUpdate, skipCache = false, requireSource = false, }) {
     const resourceCache = cache.capture?.() ?? cache;
     const resolvedPolicy = resolvePolicy(policy, maxAgeMs);
+    const capturedVersion = resourceCache.getVersion(key);
     const forcedFallback = forceFresh ? await resourceCache.get(key) : null;
+    const changedDuringCapture = forceFresh && resourceCache.getVersion(key) !== capturedVersion;
     if (forceFresh) {
         reportReadCacheOutcome(onOutcome, "forced-refresh");
         try {
@@ -249,19 +363,23 @@ export async function loadReadCacheResource({ cache, forceFresh = false, key, lo
         }
     }
     const version = resourceCache.getVersion(key);
-    const cached = skipCache
-        ? null
-        : (forcedFallback ?? (await resourceCache.get(key)));
+    const retirementVersion = changedDuringCapture ? capturedVersion : version;
+    // Capture ownership even when presentation skips the cached value.
+    const writeSnapshot = forcedFallback ?? (await resourceCache.get(key));
+    const cached = skipCache ? null : writeSnapshot;
     const retained = cached && isCacheRetained(cached.savedAt, resolvedPolicy);
-    if (retained) {
+    if (retained && !requireSource) {
         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",
+            ...(includeProvenance
+                ? { provenance: "cache-hit", savedAt: cached.savedAt }
+                : {}),
         });
-        if (fresh && !forceFresh) {
+        if (fresh && !forceFresh && !requireSource) {
             return cached.value;
         }
     }
@@ -269,16 +387,44 @@ export async function loadReadCacheResource({ cache, forceFresh = false, key, lo
         reportReadCacheOutcome(onOutcome, "cache-miss");
     }
     try {
-        const fresh = await loadSharedFreshResource(resourceCache, key, loadFresh);
+        const source = await loadSharedFreshResource(resourceCache, key, () => resolveFreshLoad(loadFresh, loadFreshResult));
+        if (source.provenance !== "source-confirmed") {
+            if (requireSource)
+                throw (source.originalError ??
+                    source.error ??
+                    new Error("[Bayon offline] Source confirmation was required."));
+            if (resourceCache.getVersion(key) === version)
+                onUpdate({
+                    data: source.data,
+                    fromCache: source.fromCache,
+                    status: source.status,
+                    ...(source.error ? { error: source.error } : {}),
+                    ...(includeProvenance
+                        ? {
+                            provenance: source.provenance,
+                            savedAt: source.savedAt,
+                            originalError: source.originalError,
+                        }
+                        : {}),
+                });
+            return source.data;
+        }
+        const fresh = source.data;
         reportReadCacheOutcome(onOutcome, "loader-success");
         if (resourceCache.getVersion(key) === version) {
             onUpdate({
                 data: fresh,
                 fromCache: false,
                 status: retained ? "fresh" : "miss",
+                ...(includeProvenance
+                    ? {
+                        provenance: "source-confirmed",
+                        confirmedAt: source.confirmedAt,
+                    }
+                    : {}),
             });
         }
-        void resourceCache.setIfVersion(key, fresh, version).catch((error) => {
+        void writeConfirmedResource(resourceCache, key, fresh, version, writeSnapshot, source.confirmedAt, Boolean(loadFreshResult)).catch((error) => {
             const normalizedError = normalizeError(error);
             console.error("[Bayon offline] Unable to refresh the read cache.", {
                 error: normalizedError,
@@ -290,7 +436,10 @@ export async function loadReadCacheResource({ cache, forceFresh = false, key, lo
     }
     catch (error) {
         reportReadCacheOutcome(onOutcome, "loader-failure");
-        if (!retained || resolvedPolicy.refreshFailure === "throw") {
+        if (error instanceof ReadCacheLoaderContractError)
+            throw error;
+        const failure = await handleReadFailure(resourceCache, key, retirementVersion, cached, resolvedPolicy, error);
+        if (requireSource || !retained || failure !== "use-retained") {
             throw error;
         }
         onUpdate({
@@ -298,10 +447,112 @@ export async function loadReadCacheResource({ cache, forceFresh = false, key, lo
             error: normalizeError(error),
             fromCache: true,
             status: "stale",
+            ...(includeProvenance
+                ? {
+                    provenance: "retained-fallback",
+                    savedAt: cached.savedAt,
+                    originalError: error,
+                }
+                : {}),
         });
         return cached.value;
     }
 }
+class ReadCacheLoaderContractError extends TypeError {
+}
+// Older envelopes have no identity token. Avoid comparisons that JSON would
+// collapse, such as distinct Maps, non-finite numbers, or cyclic values.
+function isComparableLegacyValue(value, seen = new Set()) {
+    if (value === null || typeof value === "string" || typeof value === "boolean")
+        return true;
+    if (typeof value === "number")
+        return Number.isFinite(value);
+    if (typeof value !== "object" || seen.has(value))
+        return false;
+    if (value instanceof Date)
+        return Number.isFinite(value.getTime());
+    if (Array.isArray(value) &&
+        (Object.keys(value).length !== value.length ||
+            Array.from({ length: value.length }, (_, index) => Object.hasOwn(value, index)).some((present) => !present)))
+        return false;
+    if (!Array.isArray(value) &&
+        Object.getPrototypeOf(value) !== Object.prototype)
+        return false;
+    seen.add(value);
+    const comparable = Object.values(value).every((item) => isComparableLegacyValue(item, seen));
+    seen.delete(value);
+    return comparable;
+}
+async function resolveFreshLoad(loadFresh, loadFreshResult) {
+    if (!!loadFresh === !!loadFreshResult)
+        throw new ReadCacheLoaderContractError("[Bayon offline] Provide exactly one read loader.");
+    if (loadFreshResult) {
+        const result = await loadFreshResult();
+        if (!result ||
+            !["source-confirmed", "cache-hit", "retained-fallback"].includes(result.provenance ?? ""))
+            throw new ReadCacheLoaderContractError("[Bayon offline] Layered read must report valid provenance.");
+        const cached = result.provenance !== "source-confirmed";
+        if (result.confirmedAt !== undefined &&
+            (typeof result.confirmedAt !== "string" ||
+                !Number.isFinite(Date.parse(result.confirmedAt)))) {
+            throw new ReadCacheLoaderContractError("[Bayon offline] Layered read has an invalid confirmedAt timestamp.");
+        }
+        if (result.fromCache !== cached ||
+            (cached &&
+                (typeof result.savedAt !== "string" ||
+                    !Number.isFinite(Date.parse(result.savedAt)))) ||
+            (result.provenance === "retained-fallback"
+                ? !result.error || !result.stale
+                : result.error !== null)) {
+            throw new ReadCacheLoaderContractError("[Bayon offline] Layered read has inconsistent provenance metadata.");
+        }
+        return result;
+    }
+    const data = await loadFresh();
+    return {
+        data,
+        error: null,
+        fromCache: false,
+        stale: false,
+        status: "miss",
+        provenance: "source-confirmed",
+        confirmedAt: new Date().toISOString(),
+    };
+}
+function writeConfirmedResource(cache, key, value, version, snapshot, confirmedAt, layered) {
+    // Preserve the established write hook for ordinary, value-only loaders.
+    if (!layered)
+        return cache.setIfVersion(key, value, version, snapshot, confirmedAt);
+    if (confirmedAt && cache.setIfVersionAt)
+        return cache.setIfVersionAt(key, value, version, snapshot, confirmedAt);
+    // A legacy adapter cannot preserve the age of a layered confirmation.
+    return Promise.resolve(false);
+}
+async function handleReadFailure(cache, key, version, snapshot, policy, error) {
+    let failure;
+    try {
+        failure =
+            typeof policy.refreshFailure === "function"
+                ? policy.refreshFailure(error)
+                : policy.refreshFailure;
+    }
+    catch (classificationError) {
+        console.error("[Bayon offline] Unable to classify the read failure; preserving the source error.", { error: normalizeError(classificationError), key });
+        return "throw";
+    }
+    if (failure === "retire" && snapshot) {
+        try {
+            if (cache.deleteIfVersion)
+                await cache.deleteIfVersion(key, version, snapshot);
+            else
+                console.error("[Bayon offline] Cannot safely retire a read-cache entry: adapter lacks deleteIfVersion.", { key });
+        }
+        catch (retirementError) {
+            console.error("[Bayon offline] Unable to retire the denied read-cache entry.", { key, error: normalizeError(retirementError) });
+        }
+    }
+    return failure;
+}
 function reportReadCacheOutcome(onOutcome, outcome) {
     if (!onOutcome)
         return;
@@ -342,7 +593,9 @@ function resolvePolicy(policy, maxAgeMs) {
             policy.freshForMs < 0 ||
             !Number.isFinite(policy.retainForMs) ||
             policy.retainForMs < policy.freshForMs ||
-            !["use-retained", "throw"].includes(policy.refreshFailure)) {
+            !(typeof policy.refreshFailure === "function" ||
+                policy.refreshFailure === "use-retained" ||
+                policy.refreshFailure === "throw")) {
             throw new RangeError("[Bayon offline] Invalid read-cache policy: require finite non-negative durations, retainForMs >= freshForMs, and a supported refreshFailure mode.");
         }
         return policy;

package/dist-cjs/pendingWriteConsolidation.js

@@ -38,7 +38,8 @@ function projectPendingWriteFinalState(records, getKey, { isBarrier = () => true
         const previous = latest.get(key);
         if (previous) {
             superseded.add(previous);
-            for (const effect of dependents.get(key) ?? [])
+            // Every latest entry creates its matching dependency list below.
+            for (const effect of dependents.get(key))
                 superseded.add(effect);
         }
         latest.set(key, record);

package/dist-cjs/readCache.d.ts

@@ -13,12 +13,14 @@ export type ReadCacheDriver = {
     clear: () => Promise<void>;
     close?: () => Promise<void>;
     delete: (key: string) => Promise<void>;
+    deleteIf?: (key: string, predicate: (value: unknown | null) => boolean) => Promise<boolean>;
     get: (key: string) => Promise<unknown | null>;
     listEntries?: () => Promise<Array<{
         key: string;
         value: unknown;
     }>>;
     set: (key: string, value: unknown) => Promise<void>;
+    setIf?: (key: string, value: unknown, predicate: (value: unknown | null) => boolean) => Promise<boolean>;
 };
 export type ReadCache = {
     /**
@@ -29,12 +31,15 @@ export type ReadCache = {
     clear: () => Promise<void>;
     close: () => Promise<void>;
     delete: (key: string) => Promise<void>;
+    /** Retire only a snapshot still owned by the captured generation. */
+    deleteIfVersion?: (key: string, version: string, snapshot: ReadCacheHit<unknown>) => Promise<boolean>;
     /** 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>;
+    setIfVersion: <T>(key: string, value: T, version: string, snapshot?: ReadCacheHit<unknown> | null, confirmedAt?: string) => Promise<boolean>;
+    setIfVersionAt?: <T>(key: string, value: T, version: string, snapshot: ReadCacheHit<unknown> | null, confirmedAt: string) => Promise<boolean>;
 };
 export type ReadCachePolicy = {
     /** Time that a cached value can suppress a remote read. */
@@ -42,9 +47,10 @@ export type ReadCachePolicy = {
     /** 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";
+    refreshFailure: "use-retained" | "throw" | ((error: unknown) => "use-retained" | "throw" | "retire");
 };
 export type ReadCacheStatus = "fresh" | "stale" | "miss";
+export type ReadCacheProvenance = "cache-hit" | "source-confirmed" | "retained-fallback";
 /** 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> = {
@@ -53,12 +59,27 @@ export type ReadThroughCacheResult<T> = {
     fromCache: boolean;
     stale: boolean;
     status: ReadCacheStatus;
+    provenance?: ReadCacheProvenance;
+    confirmedAt?: string;
+    savedAt?: string;
+    originalError?: unknown;
 };
 export type ReadCacheResourceUpdate<T> = {
     data: T;
     error?: Error;
     fromCache: boolean;
     status: ReadCacheStatus;
+    provenance?: ReadCacheProvenance;
+    confirmedAt?: string;
+    savedAt?: string;
+    originalError?: unknown;
+};
+export type ReadCacheLoader<T> = {
+    loadFresh: () => Promise<T>;
+    loadFreshResult?: never;
+} | {
+    loadFresh?: never;
+    loadFreshResult: () => Promise<ReadThroughCacheResult<T>>;
 };
 export type BrowserReadCacheOptions = Partial<Pick<BrowserKeyValueDriverOptions, "databaseVersion" | "indexedDB">> & {
     databaseName: string;
@@ -84,29 +105,31 @@ 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, onOutcome, policy, }: {
+export declare function readThroughCache<T>({ cache, forceFresh, includeProvenance, key, loadFresh, loadFreshResult, maxAgeMs, onOutcome, policy, requireSource, }: {
     cache: ReadCache;
     /**
      * Revalidates after advancing the key generation, retaining the prior value
      * as a possible fallback if refresh fails.
      */
     forceFresh?: boolean;
+    includeProvenance?: 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, }: {
+    requireSource?: boolean;
+} & ReadCacheLoader<T>): Promise<ReadThroughCacheResult<T>>;
+export declare function loadReadCacheResource<T>({ cache, forceFresh, includeProvenance, key, loadFresh, loadFreshResult, maxAgeMs, onOutcome, policy, onCacheWriteError, onUpdate, skipCache, requireSource, }: {
     cache: ReadCache;
     /** Revalidate while retaining eligible data as fallback on loader failure. */
     forceFresh?: boolean;
+    includeProvenance?: 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>;
+    requireSource?: boolean;
+} & ReadCacheLoader<T>): Promise<T>;

package/dist-cjs/readCache.js

@@ -9,6 +9,7 @@ exports.createReadCacheKey = createReadCacheKey;
 exports.readThroughCache = readThroughCache;
 exports.loadReadCacheResource = loadReadCacheResource;
 const idbDriver_1 = require("./idbDriver");
+const pendingWrites_1 = require("./pendingWrites");
 exports.readCacheSchemaVersion = 1;
 exports.readCacheFreshnessMaxAgeMs = 30_000;
 exports.durableReadCacheFreshnessMaxAgeMs = 60 * 60_000;
@@ -23,6 +24,28 @@ function createReadCache(driver) {
     const keyVersions = new Map();
     let operationQueue = Promise.resolve();
     const pendingLoads = new Map();
+    const capturedSnapshots = new WeakMap();
+    function ownsSnapshot(current, snapshot) {
+        if (!snapshot)
+            return current === null || toReadCacheEnvelope(current) === null;
+        const captured = capturedSnapshots.get(snapshot);
+        const envelope = toReadCacheEnvelope(current);
+        if (!captured || !envelope)
+            return false;
+        if (captured.snapshotId)
+            return envelope.snapshotId === captured.snapshotId;
+        if (envelope.snapshotId || envelope.savedAt !== captured.savedAt)
+            return false;
+        try {
+            if (!isComparableLegacyValue(envelope.value) ||
+                !isComparableLegacyValue(captured.value))
+                return false;
+            return JSON.stringify(envelope.value) === JSON.stringify(captured.value);
+        }
+        catch {
+            return false;
+        }
+    }
     function getVersion(key) {
         return `${globalVersion}:${keyVersions.get(key) ?? 0}`;
     }
@@ -35,6 +58,30 @@ function createReadCache(driver) {
         operationQueue = next.then(() => undefined, () => undefined);
         return next;
     }
+    async function writeIfVersion(key, value, version, snapshot, savedAt) {
+        if (getVersion(key) !== version)
+            return false;
+        return enqueue(async () => {
+            if (getVersion(key) !== version)
+                return false;
+            const next = {
+                savedAt,
+                schemaVersion: exports.readCacheSchemaVersion,
+                snapshotId: (0, pendingWrites_1.createPendingWriteSnapshotId)(),
+                value,
+            };
+            if (snapshot !== undefined && driver.setIf) {
+                const written = await driver.setIf(key, next, (current) => getVersion(key) === version && ownsSnapshot(current, snapshot));
+                if (!written)
+                    return false;
+            }
+            else {
+                await driver.set(key, next);
+            }
+            invalidate(key);
+            return true;
+        });
+    }
     const cache = {
         async clear() {
             pendingLoads.clear();
@@ -49,40 +96,50 @@ function createReadCache(driver) {
             invalidate(key);
             await enqueue(() => driver.delete(key));
         },
+        async deleteIfVersion(key, version, snapshot) {
+            return enqueue(async () => {
+                if (getVersion(key) !== version)
+                    return false;
+                if (!capturedSnapshots.has(snapshot) || !driver.deleteIf) {
+                    console.error("[Bayon offline] Cannot safely retire a read-cache snapshot: atomic deletion is unavailable.", { key });
+                    return false;
+                }
+                const deleted = await driver.deleteIf(key, (current) => {
+                    return getVersion(key) === version && ownsSnapshot(current, snapshot);
+                });
+                if (deleted)
+                    invalidate(key);
+                return deleted;
+            });
+        },
         invalidate,
         async get(key) {
             const envelope = toReadCacheEnvelope(await driver.get(key));
-            return envelope
-                ? {
-                    fromCache: true,
-                    savedAt: envelope.savedAt,
-                    value: envelope.value,
-                }
-                : null;
+            if (!envelope)
+                return null;
+            const hit = {
+                fromCache: true,
+                savedAt: envelope.savedAt,
+                value: envelope.value,
+            };
+            capturedSnapshots.set(hit, envelope);
+            return hit;
         },
         getVersion,
         async set(key, value) {
+            invalidate(key);
             await enqueue(() => driver.set(key, {
                 savedAt: new Date().toISOString(),
                 schemaVersion: exports.readCacheSchemaVersion,
+                snapshotId: (0, pendingWrites_1.createPendingWriteSnapshotId)(),
                 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;
-            });
+        async setIfVersion(key, value, version, snapshot, confirmedAt) {
+            return writeIfVersion(key, value, version, snapshot, confirmedAt ?? new Date().toISOString());
+        },
+        async setIfVersionAt(key, value, version, snapshot, confirmedAt) {
+            return writeIfVersion(key, value, version, snapshot, confirmedAt);
         },
     };
     pendingFreshLoads.set(cache, pendingLoads);
@@ -113,6 +170,12 @@ function createMemoryReadCacheDriver() {
         async delete(key) {
             records.delete(key);
         },
+        async deleteIf(key, predicate) {
+            if (!predicate(records.get(key) ?? null))
+                return false;
+            records.delete(key);
+            return true;
+        },
         async get(key) {
             return records.get(key) ?? null;
         },
@@ -122,6 +185,12 @@ function createMemoryReadCacheDriver() {
         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 createBrowserReadCache({ databaseName, databaseVersion, indexedDB = globalThis.indexedDB, operationTimeoutMs = exports.browserReadCacheOperationTimeoutMs, storeName, }) {
@@ -137,9 +206,11 @@ function createBrowserReadCache({ databaseName, databaseVersion, indexedDB = glo
             clear: driver.clear,
             close: driver.close,
             delete: driver.delete,
+            deleteIf: driver.deleteIf,
             get: driver.get,
             listEntries: driver.listEntries,
             set: driver.set,
+            setIf: driver.setIf,
         }
         : createNoopReadCacheDriver());
 }
@@ -166,10 +237,12 @@ function createReadCacheKey({ namespace, params = {}, prefix, scope, }) {
         .filter(Boolean)
         .join(":");
 }
-async function readThroughCache({ cache, forceFresh = false, key, loadFresh, maxAgeMs, onOutcome, policy, }) {
+async function readThroughCache({ cache, forceFresh = false, includeProvenance = false, key, loadFresh, loadFreshResult, maxAgeMs, onOutcome, policy, requireSource = false, }) {
     const resourceCache = cache.capture?.() ?? cache;
     const resolvedPolicy = resolvePolicy(policy, maxAgeMs);
+    const capturedVersion = resourceCache.getVersion(key);
     const forcedFallback = forceFresh ? await resourceCache.get(key) : null;
+    const changedDuringCapture = forceFresh && resourceCache.getVersion(key) !== capturedVersion;
     if (forceFresh) {
         reportReadCacheOutcome(onOutcome, "forced-refresh");
         // Built-in caches advance generation without deleting fallback data.
@@ -190,9 +263,13 @@ async function readThroughCache({ cache, forceFresh = false, key, loadFresh, max
         }
     }
     const version = resourceCache.getVersion(key);
+    const retirementVersion = changedDuringCapture ? capturedVersion : version;
     const cached = forcedFallback ?? (await resourceCache.get(key));
     const retained = cached && isCacheRetained(cached.savedAt, resolvedPolicy);
-    if (!forceFresh && retained && isCacheFresh(cached.savedAt, resolvedPolicy)) {
+    if (!forceFresh &&
+        !requireSource &&
+        retained &&
+        isCacheFresh(cached.savedAt, resolvedPolicy)) {
         reportReadCacheOutcome(onOutcome, "fresh-hit");
         return {
             data: cached.value,
@@ -200,14 +277,33 @@ async function readThroughCache({ cache, forceFresh = false, key, loadFresh, max
             fromCache: true,
             stale: false,
             status: "fresh",
+            ...(includeProvenance
+                ? { provenance: "cache-hit", savedAt: cached.savedAt }
+                : {}),
         };
     }
     reportReadCacheOutcome(onOutcome, retained ? "stale-hit" : "cache-miss");
     try {
-        const fresh = await loadSharedFreshResource(resourceCache, key, loadFresh);
+        const source = await loadSharedFreshResource(resourceCache, key, () => resolveFreshLoad(loadFresh, loadFreshResult));
+        if (source.provenance !== "source-confirmed") {
+            if (requireSource)
+                throw (source.originalError ??
+                    source.error ??
+                    new Error("[Bayon offline] Source confirmation was required."));
+            return includeProvenance
+                ? source
+                : {
+                    data: source.data,
+                    error: source.error,
+                    fromCache: source.fromCache,
+                    stale: source.stale,
+                    status: source.status,
+                };
+        }
+        const fresh = source.data;
         reportReadCacheOutcome(onOutcome, "loader-success");
         try {
-            await resourceCache.setIfVersion(key, fresh, version);
+            await writeConfirmedResource(resourceCache, key, fresh, version, cached, source.confirmedAt, Boolean(loadFreshResult));
         }
         catch (error) {
             console.error("[Bayon offline] Unable to refresh the read cache.", {
@@ -221,26 +317,44 @@ async function readThroughCache({ cache, forceFresh = false, key, loadFresh, max
             fromCache: false,
             stale: false,
             status: retained ? "fresh" : "miss",
+            ...(includeProvenance
+                ? {
+                    provenance: "source-confirmed",
+                    confirmedAt: source.confirmedAt,
+                }
+                : {}),
         };
     }
     catch (error) {
         reportReadCacheOutcome(onOutcome, "loader-failure");
-        if (retained && resolvedPolicy.refreshFailure === "use-retained") {
+        if (error instanceof ReadCacheLoaderContractError)
+            throw error;
+        const failure = await handleReadFailure(resourceCache, key, retirementVersion, cached, resolvedPolicy, error);
+        if (!requireSource && retained && failure === "use-retained") {
             return {
                 data: cached.value,
                 error: normalizeError(error),
                 fromCache: true,
                 stale: true,
                 status: "stale",
+                ...(includeProvenance
+                    ? {
+                        provenance: "retained-fallback",
+                        savedAt: cached.savedAt,
+                        originalError: error,
+                    }
+                    : {}),
             };
         }
         throw error;
     }
 }
-async function loadReadCacheResource({ cache, forceFresh = false, key, loadFresh, maxAgeMs, onOutcome, policy, onCacheWriteError, onUpdate, skipCache = false, }) {
+async function loadReadCacheResource({ cache, forceFresh = false, includeProvenance = false, key, loadFresh, loadFreshResult, maxAgeMs, onOutcome, policy, onCacheWriteError, onUpdate, skipCache = false, requireSource = false, }) {
     const resourceCache = cache.capture?.() ?? cache;
     const resolvedPolicy = resolvePolicy(policy, maxAgeMs);
+    const capturedVersion = resourceCache.getVersion(key);
     const forcedFallback = forceFresh ? await resourceCache.get(key) : null;
+    const changedDuringCapture = forceFresh && resourceCache.getVersion(key) !== capturedVersion;
     if (forceFresh) {
         reportReadCacheOutcome(onOutcome, "forced-refresh");
         try {
@@ -259,19 +373,23 @@ async function loadReadCacheResource({ cache, forceFresh = false, key, loadFresh
         }
     }
     const version = resourceCache.getVersion(key);
-    const cached = skipCache
-        ? null
-        : (forcedFallback ?? (await resourceCache.get(key)));
+    const retirementVersion = changedDuringCapture ? capturedVersion : version;
+    // Capture ownership even when presentation skips the cached value.
+    const writeSnapshot = forcedFallback ?? (await resourceCache.get(key));
+    const cached = skipCache ? null : writeSnapshot;
     const retained = cached && isCacheRetained(cached.savedAt, resolvedPolicy);
-    if (retained) {
+    if (retained && !requireSource) {
         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",
+            ...(includeProvenance
+                ? { provenance: "cache-hit", savedAt: cached.savedAt }
+                : {}),
         });
-        if (fresh && !forceFresh) {
+        if (fresh && !forceFresh && !requireSource) {
             return cached.value;
         }
     }
@@ -279,16 +397,44 @@ async function loadReadCacheResource({ cache, forceFresh = false, key, loadFresh
         reportReadCacheOutcome(onOutcome, "cache-miss");
     }
     try {
-        const fresh = await loadSharedFreshResource(resourceCache, key, loadFresh);
+        const source = await loadSharedFreshResource(resourceCache, key, () => resolveFreshLoad(loadFresh, loadFreshResult));
+        if (source.provenance !== "source-confirmed") {
+            if (requireSource)
+                throw (source.originalError ??
+                    source.error ??
+                    new Error("[Bayon offline] Source confirmation was required."));
+            if (resourceCache.getVersion(key) === version)
+                onUpdate({
+                    data: source.data,
+                    fromCache: source.fromCache,
+                    status: source.status,
+                    ...(source.error ? { error: source.error } : {}),
+                    ...(includeProvenance
+                        ? {
+                            provenance: source.provenance,
+                            savedAt: source.savedAt,
+                            originalError: source.originalError,
+                        }
+                        : {}),
+                });
+            return source.data;
+        }
+        const fresh = source.data;
         reportReadCacheOutcome(onOutcome, "loader-success");
         if (resourceCache.getVersion(key) === version) {
             onUpdate({
                 data: fresh,
                 fromCache: false,
                 status: retained ? "fresh" : "miss",
+                ...(includeProvenance
+                    ? {
+                        provenance: "source-confirmed",
+                        confirmedAt: source.confirmedAt,
+                    }
+                    : {}),
             });
         }
-        void resourceCache.setIfVersion(key, fresh, version).catch((error) => {
+        void writeConfirmedResource(resourceCache, key, fresh, version, writeSnapshot, source.confirmedAt, Boolean(loadFreshResult)).catch((error) => {
             const normalizedError = normalizeError(error);
             console.error("[Bayon offline] Unable to refresh the read cache.", {
                 error: normalizedError,
@@ -300,7 +446,10 @@ async function loadReadCacheResource({ cache, forceFresh = false, key, loadFresh
     }
     catch (error) {
         reportReadCacheOutcome(onOutcome, "loader-failure");
-        if (!retained || resolvedPolicy.refreshFailure === "throw") {
+        if (error instanceof ReadCacheLoaderContractError)
+            throw error;
+        const failure = await handleReadFailure(resourceCache, key, retirementVersion, cached, resolvedPolicy, error);
+        if (requireSource || !retained || failure !== "use-retained") {
             throw error;
         }
         onUpdate({
@@ -308,10 +457,112 @@ async function loadReadCacheResource({ cache, forceFresh = false, key, loadFresh
             error: normalizeError(error),
             fromCache: true,
             status: "stale",
+            ...(includeProvenance
+                ? {
+                    provenance: "retained-fallback",
+                    savedAt: cached.savedAt,
+                    originalError: error,
+                }
+                : {}),
         });
         return cached.value;
     }
 }
+class ReadCacheLoaderContractError extends TypeError {
+}
+// Older envelopes have no identity token. Avoid comparisons that JSON would
+// collapse, such as distinct Maps, non-finite numbers, or cyclic values.
+function isComparableLegacyValue(value, seen = new Set()) {
+    if (value === null || typeof value === "string" || typeof value === "boolean")
+        return true;
+    if (typeof value === "number")
+        return Number.isFinite(value);
+    if (typeof value !== "object" || seen.has(value))
+        return false;
+    if (value instanceof Date)
+        return Number.isFinite(value.getTime());
+    if (Array.isArray(value) &&
+        (Object.keys(value).length !== value.length ||
+            Array.from({ length: value.length }, (_, index) => Object.hasOwn(value, index)).some((present) => !present)))
+        return false;
+    if (!Array.isArray(value) &&
+        Object.getPrototypeOf(value) !== Object.prototype)
+        return false;
+    seen.add(value);
+    const comparable = Object.values(value).every((item) => isComparableLegacyValue(item, seen));
+    seen.delete(value);
+    return comparable;
+}
+async function resolveFreshLoad(loadFresh, loadFreshResult) {
+    if (!!loadFresh === !!loadFreshResult)
+        throw new ReadCacheLoaderContractError("[Bayon offline] Provide exactly one read loader.");
+    if (loadFreshResult) {
+        const result = await loadFreshResult();
+        if (!result ||
+            !["source-confirmed", "cache-hit", "retained-fallback"].includes(result.provenance ?? ""))
+            throw new ReadCacheLoaderContractError("[Bayon offline] Layered read must report valid provenance.");
+        const cached = result.provenance !== "source-confirmed";
+        if (result.confirmedAt !== undefined &&
+            (typeof result.confirmedAt !== "string" ||
+                !Number.isFinite(Date.parse(result.confirmedAt)))) {
+            throw new ReadCacheLoaderContractError("[Bayon offline] Layered read has an invalid confirmedAt timestamp.");
+        }
+        if (result.fromCache !== cached ||
+            (cached &&
+                (typeof result.savedAt !== "string" ||
+                    !Number.isFinite(Date.parse(result.savedAt)))) ||
+            (result.provenance === "retained-fallback"
+                ? !result.error || !result.stale
+                : result.error !== null)) {
+            throw new ReadCacheLoaderContractError("[Bayon offline] Layered read has inconsistent provenance metadata.");
+        }
+        return result;
+    }
+    const data = await loadFresh();
+    return {
+        data,
+        error: null,
+        fromCache: false,
+        stale: false,
+        status: "miss",
+        provenance: "source-confirmed",
+        confirmedAt: new Date().toISOString(),
+    };
+}
+function writeConfirmedResource(cache, key, value, version, snapshot, confirmedAt, layered) {
+    // Preserve the established write hook for ordinary, value-only loaders.
+    if (!layered)
+        return cache.setIfVersion(key, value, version, snapshot, confirmedAt);
+    if (confirmedAt && cache.setIfVersionAt)
+        return cache.setIfVersionAt(key, value, version, snapshot, confirmedAt);
+    // A legacy adapter cannot preserve the age of a layered confirmation.
+    return Promise.resolve(false);
+}
+async function handleReadFailure(cache, key, version, snapshot, policy, error) {
+    let failure;
+    try {
+        failure =
+            typeof policy.refreshFailure === "function"
+                ? policy.refreshFailure(error)
+                : policy.refreshFailure;
+    }
+    catch (classificationError) {
+        console.error("[Bayon offline] Unable to classify the read failure; preserving the source error.", { error: normalizeError(classificationError), key });
+        return "throw";
+    }
+    if (failure === "retire" && snapshot) {
+        try {
+            if (cache.deleteIfVersion)
+                await cache.deleteIfVersion(key, version, snapshot);
+            else
+                console.error("[Bayon offline] Cannot safely retire a read-cache entry: adapter lacks deleteIfVersion.", { key });
+        }
+        catch (retirementError) {
+            console.error("[Bayon offline] Unable to retire the denied read-cache entry.", { key, error: normalizeError(retirementError) });
+        }
+    }
+    return failure;
+}
 function reportReadCacheOutcome(onOutcome, outcome) {
     if (!onOutcome)
         return;
@@ -352,7 +603,9 @@ function resolvePolicy(policy, maxAgeMs) {
             policy.freshForMs < 0 ||
             !Number.isFinite(policy.retainForMs) ||
             policy.retainForMs < policy.freshForMs ||
-            !["use-retained", "throw"].includes(policy.refreshFailure)) {
+            !(typeof policy.refreshFailure === "function" ||
+                policy.refreshFailure === "use-retained" ||
+                policy.refreshFailure === "throw")) {
             throw new RangeError("[Bayon offline] Invalid read-cache policy: require finite non-negative durations, retainForMs >= freshForMs, and a supported refreshFailure mode.");
         }
         return policy;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bayonai/offline",
-  "version": "0.12.0",
+  "version": "0.13.0",
   "description": "Reusable offline read-cache, pending-write, and silent recovery primitives.",
   "license": "MIT",
   "author": "Bayon AI",