@bayonai/offline 0.12.0 → 0.15.0

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,7 +48,44 @@ export function createReadCache(driver) {
         operationQueue = next.then(() => undefined, () => undefined);
         return next;
     }
+    async function writeIfVersion(key, value, version, snapshot, savedAt, receipt) {
+        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;
+                // A driver may finish after the caller has retired this generation.
+                // Keep that retirement visible instead of issuing a new owned receipt.
+                if (receipt && getVersion(key) !== version)
+                    return false;
+            }
+            else {
+                await driver.set(key, next);
+            }
+            invalidate(key);
+            if (receipt)
+                receipt.version = getVersion(key);
+            return true;
+        });
+    }
     const cache = {
+        async commitIfVersion(key, value, version, snapshot, confirmedAt) {
+            if (!driver.setIf)
+                throw new Error("[Bayon offline] Canonical presentation requires atomic conditional cache writes.");
+            const receipt = { version };
+            const written = await writeIfVersion(key, value, version, snapshot, confirmedAt ?? new Date().toISOString(), receipt);
+            return { written, version: receipt.version };
+        },
         async clear() {
             pendingLoads.clear();
             globalVersion += 1;
@@ -39,40 +99,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 +173,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 +188,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 +209,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 +240,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 +266,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 +280,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 +320,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, deliveryPolicy = "immediate", 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 +376,68 @@ export async function loadReadCacheResource({ cache, forceFresh = false, key, lo
         }
     }
     const version = resourceCache.getVersion(key);
-    const cached = skipCache
-        ? null
-        : (forcedFallback ?? (await resourceCache.get(key)));
-    const retained = cached && isCacheRetained(cached.savedAt, resolvedPolicy);
-    if (retained) {
+    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)
+        && (deliveryPolicy === "immediate" || resourceCache.getVersion(key) === version);
+    function publishUpdate(update) {
+        if (deliveryPolicy === "immediate") {
+            onUpdate(update);
+            return;
+        }
+        try {
+            onUpdate(update);
+        }
+        catch (error) {
+            // Opted-in presentation is independent of the caller's source outcome.
+            console.error("[Bayon offline] Read-cache presentation callback failed.", {
+                error: normalizeError(error), key,
+            });
+        }
+    }
+    function reportPresentationStorageError(error) {
+        const normalizedError = normalizeError(error);
+        console.error("[Bayon offline] Unable to confirm current read-cache presentation.", {
+            error: normalizedError, key,
+        });
+        onCacheWriteError?.(normalizedError);
+    }
+    async function canonicalUpdate(expectedVersion) {
+        if (resourceCache.getVersion(key) !== expectedVersion)
+            return;
+        let canonical;
+        try {
+            canonical = await resourceCache.get(key);
+        }
+        catch (error) {
+            reportPresentationStorageError(error);
+            return;
+        }
+        if (!canonical || resourceCache.getVersion(key) !== expectedVersion
+            || !isCacheRetained(canonical.savedAt, resolvedPolicy))
+            return;
+        return {
+            data: canonical.value, fromCache: true,
+            status: isCacheFresh(canonical.savedAt, resolvedPolicy) ? "fresh" : "stale",
+            ...(includeProvenance ? {
+                provenance: "cache-hit", savedAt: canonical.savedAt,
+            } : {}),
+        };
+    }
+    if (retained && !requireSource) {
         const fresh = isCacheFresh(cached.savedAt, resolvedPolicy);
         reportReadCacheOutcome(onOutcome, fresh && !forceFresh ? "fresh-hit" : "stale-hit");
-        onUpdate({
+        publishUpdate({
             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 +445,77 @@ 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 (deliveryPolicy === "cache-current") {
+                const update = await canonicalUpdate(version);
+                if (update)
+                    publishUpdate(update);
+                return source.data;
+            }
+            if (resourceCache.getVersion(key) === version)
+                publishUpdate({
+                    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 (deliveryPolicy === "cache-current") {
+            let update;
+            try {
+                if (!resourceCache.commitIfVersion)
+                    throw new Error("[Bayon offline] Canonical presentation requires an atomic commit receipt.");
+                const receipt = await resourceCache.commitIfVersion(key, fresh, version, writeSnapshot, source.confirmedAt);
+                if (requireSource) {
+                    // Source-required consumers may never mistake a readback for proof.
+                    if (receipt.written && resourceCache.getVersion(key) === receipt.version)
+                        update = {
+                            data: fresh, fromCache: false, status: retained ? "fresh" : "miss",
+                            ...(includeProvenance ? {
+                                provenance: "source-confirmed", confirmedAt: source.confirmedAt,
+                            } : {}),
+                        };
+                }
+                else
+                    update = await canonicalUpdate(receipt.version);
+            }
+            catch (error) {
+                reportPresentationStorageError(error);
+            }
+            // Keep observer exceptions outside the storage diagnostic boundary.
+            if (update)
+                publishUpdate(update);
+            return fresh;
+        }
         if (resourceCache.getVersion(key) === version) {
-            onUpdate({
+            publishUpdate({
                 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,18 +527,134 @@ 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({
+        if (deliveryPolicy === "cache-current") {
+            const update = await canonicalUpdate(version);
+            if (update)
+                publishUpdate({
+                    ...update, status: "stale", error: normalizeError(error),
+                    ...(includeProvenance ? {
+                        provenance: "retained-fallback", originalError: error,
+                    } : {}),
+                });
+            return cached.value;
+        }
+        publishUpdate({
             data: cached.value,
             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 +695,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/readResourceBatch.d.ts

@@ -0,0 +1,13 @@
+import type { ReadResourceObservation, ReadResourceUpdate } from "./readResourceObserver.js";
+/** A mounted presentation barrier; child tasks retain sole network/cache ownership. */
+export declare function observeReadResourceBatch<T>({ count, observe, freshForMs, now, current, canRetain, retiredError, subscribe, onUpdate }: {
+    count: number;
+    observe: (index: number, update: (value: ReadResourceUpdate<T>) => void, age: (createdAt: number) => void) => ReadResourceObservation<T>;
+    freshForMs: number[];
+    now: () => number;
+    current: () => boolean;
+    canRetain: (value: T) => boolean;
+    retiredError: () => Error;
+    subscribe: (listener: () => Promise<void>) => () => void;
+    onUpdate: (update: ReadResourceUpdate<T[]>) => void;
+}): ReadResourceObservation<T[]>;