@bayonai/offline 0.11.0 → 0.13.0

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.11.0",
+  "version": "0.13.0",
   "description": "Reusable offline read-cache, pending-write, and silent recovery primitives.",
   "license": "MIT",
   "author": "Bayon AI",