@bayonai/offline 0.11.0 → 0.13.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,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/index.d.ts

@@ -9,3 +9,4 @@ export * from "./readBoundary.js";
 export * from "./recoveryPolicy.js";
 export * from "./pendingWriteSupersession.js";
 export { projectPendingWriteFinalState, type PendingWriteSupersessionKey, type PendingWriteConsolidationOptions, } from "./pendingWriteConsolidation.js";
+export * from "./pendingChangeTracker.js";

package/dist-cjs/index.js

@@ -28,3 +28,4 @@ __exportStar(require("./recoveryPolicy"), exports);
 __exportStar(require("./pendingWriteSupersession"), exports);
 var pendingWriteConsolidation_1 = require("./pendingWriteConsolidation");
 Object.defineProperty(exports, "projectPendingWriteFinalState", { enumerable: true, get: function () { return pendingWriteConsolidation_1.projectPendingWriteFinalState; } });
+__exportStar(require("./pendingChangeTracker"), exports);

package/dist-cjs/pendingChangeTracker.d.ts

@@ -0,0 +1,71 @@
+export type PendingChangeStatus = "draft" | "waiting" | "sending" | "attention" | "storage-error";
+/** Hosts own domain labels and recovery actions; this is only a queue projection. */
+export type PendingChangeItem = {
+    id: string;
+    accountKey: string;
+    groupKey: string;
+    groupTitle: string;
+    label: string;
+    status: PendingChangeStatus;
+    attemptedText?: string;
+    needsAttention: boolean;
+    storageError: boolean;
+    sending: boolean;
+};
+export type PendingChangeGroup<T extends PendingChangeItem = PendingChangeItem> = {
+    key: string;
+    title: string;
+    items: readonly T[];
+};
+export type PendingChangeSnapshot<T extends PendingChangeItem = PendingChangeItem> = {
+    accountKey: string | null;
+    items: readonly T[];
+    groups: readonly PendingChangeGroup<T>[];
+    count: number;
+    draftCount: number;
+    readyCount: number;
+    attentionCount: number;
+    storageErrorCount: number;
+    sendingCount: number;
+    guidance: string;
+    loading: boolean;
+    readError: unknown | null;
+};
+/** Groups host-scoped rows without imposing account or domain semantics. */
+export declare function groupPendingChangeItems<T extends {
+    groupKey: string;
+    groupTitle: string;
+}>(items: readonly T[]): Array<{
+    key: string;
+    title: string;
+    items: T[];
+}>;
+/** Same-ID captured edits replace durable rows; insertion order remains stable. */
+export declare function createPendingChangeSnapshot<T extends PendingChangeItem>({ accountKey, items, isOffline, loading, readError, }: {
+    accountKey: string | null;
+    items: readonly T[];
+    isOffline?: boolean;
+    loading?: boolean;
+    readError?: unknown;
+}): PendingChangeSnapshot<T>;
+export type PendingChangeTracker<T extends PendingChangeItem = PendingChangeItem> = {
+    getSnapshot: () => PendingChangeSnapshot<T>;
+    subscribe: (listener: () => void) => () => void;
+    refresh: () => Promise<void>;
+    setAccountKey: (accountKey: string | null) => void;
+    setOffline: (isOffline: boolean) => void;
+    close: () => void;
+};
+/**
+ * Observes existing host queues, never persists or replays changes. Reads fail
+ * closed across accounts but retain the current account's last known rows.
+ * Hosts must notify for draft, command-store and connectivity source changes.
+ */
+export declare function createPendingChangeTracker<T extends PendingChangeItem>(options: {
+    accountKey?: string | null;
+    isOffline?: boolean;
+    load: (accountKey: string) => Promise<readonly T[]>;
+    capture?: (accountKey: string) => readonly T[];
+    subscribe?: (onChange: () => void) => () => void;
+    onError?: (error: unknown) => void;
+}): PendingChangeTracker<T>;