@bayonai/offline 0.13.0 → 0.15.0

package/dist/readResourceObserver.js

@@ -0,0 +1,108 @@
+/**
+ * Mounted presentation only: hosts retain cache, transport, identity and initial
+ * read policy. Accepting a snapshot preserves its source age; a successful
+ * refresh does not require persistence to have survived an unrelated write.
+ */
+export function createReadResourceObserver({ enabled = true, current, now, freshForMs, canRetain, isConnected = () => true, canonical, captureSnapshot, read, retireSnapshot, classifyFailure, subscribeWake, onUpdate, onData, onError, }) {
+    let disposed = false;
+    let retired = false;
+    let confirmedAt;
+    let retainable = true;
+    let pending;
+    let stop = () => { };
+    const detach = () => { const cleanup = stop; stop = () => { }; cleanup(); };
+    const active = () => !disposed && !retired && current();
+    const canRefresh = () => enabled && active() && retainable && confirmedAt !== undefined;
+    const accept = (update, age = now()) => {
+        if (!active())
+            return;
+        if ("data" in update) {
+            confirmedAt = age;
+            retainable = canRetain(update.data);
+            onData?.(update.data);
+        }
+        if (active())
+            onUpdate(update);
+    };
+    const adoptCanonical = () => {
+        const snapshot = canonical();
+        if (!snapshot || !active() || now() - snapshot.confirmedAt >= freshForMs)
+            return false;
+        accept({ status: "fresh", data: snapshot.data }, snapshot.confirmedAt);
+        return true;
+    };
+    const run = async (force) => {
+        if (!canRefresh())
+            return;
+        if (!force && now() - confirmedAt < freshForMs)
+            return;
+        if (!isConnected()) {
+            accept({ status: "retry", error: new Error("Resource unavailable while disconnected") });
+            return;
+        }
+        if (!force && adoptCanonical())
+            return;
+        accept({ status: "refreshing" });
+        if (!canRefresh())
+            return;
+        const snapshot = captureSnapshot();
+        let result;
+        try {
+            result = await read();
+        }
+        catch (error) {
+            if (!active())
+                return;
+            const failure = classifyFailure(error);
+            if (failure === "superseded") {
+                adoptCanonical();
+                return;
+            }
+            if (failure === "retired")
+                return;
+            if (onError)
+                onError(error);
+            else
+                console.error("[Bayon offline] Mounted resource refresh failed.", { error });
+            if (failure === "transient")
+                accept({ status: "retry", error });
+            else {
+                try {
+                    await retireSnapshot(snapshot);
+                }
+                catch (storageError) {
+                    // Storage cleanup cannot turn a known denial into retained presentation.
+                    console.error("[Bayon offline] Unable to retire a mounted read snapshot.", { error: storageError });
+                }
+                if (!active())
+                    return;
+                confirmedAt = undefined;
+                accept({ status: "failed", error });
+            }
+            return;
+        }
+        accept({ status: "fresh", data: result.data }, result.confirmedAt);
+    };
+    const refresh = ({ force = true } = {}) => {
+        if (!canRefresh())
+            return;
+        // Install ownership before callbacks can synchronously request another read.
+        if (!pending)
+            pending = Promise.resolve().then(() => run(force)).finally(() => { pending = undefined; });
+        return pending;
+    };
+    if (enabled && subscribeWake)
+        stop = subscribeWake(() => refresh({ force: false }) ?? Promise.resolve());
+    return {
+        accept, canRefresh, refresh,
+        retire() {
+            if (disposed || retired)
+                return;
+            retired = true;
+            detach();
+            // Clearing protected presentation is safe even after the host changed scope.
+            onUpdate({ status: "invalidated" });
+        },
+        dispose() { disposed = true; detach(); },
+    };
+}

package/dist-cjs/browserReadLifecycle.d.ts

@@ -0,0 +1,5 @@
+/** Native wake binding only; hosts own visibility, eligibility and request sharing. */
+export declare function bindBrowserReadLifecycle(targets: {
+    window: EventTarget;
+    document: EventTarget;
+}, notify: () => Promise<void>): () => void;

package/dist-cjs/browserReadLifecycle.js

@@ -0,0 +1,27 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.bindBrowserReadLifecycle = bindBrowserReadLifecycle;
+/** Native wake binding only; hosts own visibility, eligibility and request sharing. */
+function bindBrowserReadLifecycle(targets, notify) {
+    const report = (error) => console.error("[Bayon offline] Browser read refresh failed.", { error });
+    const wake = () => {
+        try {
+            void notify().catch(report);
+        }
+        catch (error) {
+            report(error);
+        }
+    };
+    targets.window.addEventListener("focus", wake);
+    targets.window.addEventListener("online", wake);
+    targets.document.addEventListener("visibilitychange", wake);
+    let stopped = false;
+    return () => {
+        if (stopped)
+            return;
+        stopped = true;
+        targets.window.removeEventListener("focus", wake);
+        targets.window.removeEventListener("online", wake);
+        targets.document.removeEventListener("visibilitychange", wake);
+    };
+}

package/dist-cjs/index.d.ts

@@ -1,4 +1,7 @@
 export * from "./readCache.js";
+export * from "./readResourceObserver.js";
+export * from "./readResourceBatch.js";
+export * from "./browserReadLifecycle.js";
 export * from "./pendingWrites.js";
 export * from "./browserRecovery.js";
 export * from "./browserCoordination.js";

package/dist-cjs/index.js

@@ -16,6 +16,9 @@ var __exportStar = (this && this.__exportStar) || function(m, exports) {
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.projectPendingWriteFinalState = exports.OfflineStorageError = void 0;
 __exportStar(require("./readCache"), exports);
+__exportStar(require("./readResourceObserver"), exports);
+__exportStar(require("./readResourceBatch"), exports);
+__exportStar(require("./browserReadLifecycle"), exports);
 __exportStar(require("./pendingWrites"), exports);
 __exportStar(require("./browserRecovery"), exports);
 __exportStar(require("./browserCoordination"), exports);

package/dist-cjs/pendingWrites.d.ts

@@ -151,9 +151,9 @@ export declare function syncPendingWrite<Payload>({ id, now, store, sync, }: {
     sync: PendingWriteSync<Payload>;
 }): Promise<SyncPendingWriteResult>;
 /**
- * Replays selected writes oldest first and coalesces overlapping runs for the
- * same store/scope. Callers own the selection predicate and idempotent remote
- * mutation semantics.
+ * Replays selected writes oldest first. Identical overlapping calls coalesce;
+ * calls with different options run serially for the same store and scope.
+ * Callers own the selection predicate and idempotent remote mutation semantics.
  */
 export declare function syncPendingWrites<Payload>({ now, scopeKey, select, stopOnFailure, store, sync, }: {
     now?: () => string;

package/dist-cjs/pendingWrites.js

@@ -299,30 +299,34 @@ async function syncPendingWrite({ id, now = () => new Date().toISOString(), stor
         : { status: "superseded" };
 }
 /**
- * Replays selected writes oldest first and coalesces overlapping runs for the
- * same store/scope. Callers own the selection predicate and idempotent remote
- * mutation semantics.
+ * Replays selected writes oldest first. Identical overlapping calls coalesce;
+ * calls with different options run serially for the same store and scope.
+ * Callers own the selection predicate and idempotent remote mutation semantics.
  */
-function syncPendingWrites({ now, scopeKey = "all", select = () => true, stopOnFailure = false, store, sync, }) {
+function syncPendingWrites({ now, scopeKey = "all", select = selectAllPendingWrites, stopOnFailure = false, store, sync, }) {
     let inFlightByScope = pendingWriteSyncs.get(store);
     if (!inFlightByScope) {
         inFlightByScope = new Map();
         pendingWriteSyncs.set(store, inFlightByScope);
     }
     const existing = inFlightByScope.get(scopeKey);
-    if (existing) {
-        return existing;
+    if (existing &&
+        existing.select === select &&
+        existing.sync === sync &&
+        existing.now === now &&
+        existing.stopOnFailure === stopOnFailure) {
+        return existing.promise;
     }
-    const syncRun = performPendingWriteSync({
-        now,
-        select,
-        stopOnFailure,
-        store,
-        sync,
-    });
-    inFlightByScope.set(scopeKey, syncRun);
+    const run = () => performPendingWriteSync({ now, select, stopOnFailure, store, sync });
+    // Product decision: distinct filters must never share counts or run in
+    // parallel; each waits for the preceding scope run and uses its own policy.
+    const syncRun = existing ? existing.promise.then(run, run) : run();
+    const entry = { now, select, stopOnFailure, sync, promise: syncRun };
+    inFlightByScope.set(scopeKey, entry);
     const clearInFlight = () => {
-        inFlightByScope.delete(scopeKey);
+        if (inFlightByScope.get(scopeKey) === entry) {
+            inFlightByScope.delete(scopeKey);
+        }
     };
     void syncRun.then(clearInFlight, clearInFlight);
     return syncRun;
@@ -360,6 +364,7 @@ function summarizePendingWrites(records) {
         return summary;
     }, { failedCount: 0, pendingCount: 0, syncingCount: 0, totalCount: 0 });
 }
+const selectAllPendingWrites = () => true;
 const pendingWriteSyncs = new WeakMap();
 async function performPendingWriteSync({ now, select, stopOnFailure, store, sync, }) {
     const summary = {

package/dist-cjs/readCache.d.ts

@@ -23,6 +23,11 @@ export type ReadCacheDriver = {
     setIf?: (key: string, value: unknown, predicate: (value: unknown | null) => boolean) => Promise<boolean>;
 };
 export type ReadCache = {
+    /** Atomic ownership proof for opt-in canonical presentation; version is captured at commit. */
+    commitIfVersion?: <T>(key: string, value: T, version: string, snapshot: ReadCacheHit<unknown> | null, confirmedAt?: string) => Promise<{
+        written: boolean;
+        version: string;
+    }>;
     /**
      * Resolves a stable cache for the duration of a resource load. Dynamic
      * adapters use this to pin the active account before asynchronous work.
@@ -119,8 +124,10 @@ export declare function readThroughCache<T>({ cache, forceFresh, includeProvenan
     policy?: ReadCachePolicy;
     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, }: {
+export declare function loadReadCacheResource<T>({ cache, deliveryPolicy, forceFresh, includeProvenance, key, loadFresh, loadFreshResult, maxAgeMs, onOutcome, policy, onCacheWriteError, onUpdate, skipCache, requireSource, }: {
     cache: ReadCache;
+    /** Opt in to presenting the eligible canonical cache after conditional persistence. */
+    deliveryPolicy?: "immediate" | "cache-current";
     /** Revalidate while retaining eligible data as fallback on loader failure. */
     forceFresh?: boolean;
     includeProvenance?: boolean;

package/dist-cjs/readCache.js

@@ -58,7 +58,7 @@ function createReadCache(driver) {
         operationQueue = next.then(() => undefined, () => undefined);
         return next;
     }
-    async function writeIfVersion(key, value, version, snapshot, savedAt) {
+    async function writeIfVersion(key, value, version, snapshot, savedAt, receipt) {
         if (getVersion(key) !== version)
             return false;
         return enqueue(async () => {
@@ -74,15 +74,28 @@ function createReadCache(driver) {
                 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;
@@ -349,7 +362,7 @@ async function readThroughCache({ cache, forceFresh = false, includeProvenance =
         throw error;
     }
 }
-async function loadReadCacheResource({ cache, forceFresh = false, includeProvenance = false, key, loadFresh, loadFreshResult, maxAgeMs, onOutcome, policy, onCacheWriteError, onUpdate, skipCache = false, requireSource = false, }) {
+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);
@@ -377,11 +390,56 @@ async function loadReadCacheResource({ cache, forceFresh = false, includeProvena
     // 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);
+    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",
@@ -403,8 +461,14 @@ async function loadReadCacheResource({ cache, forceFresh = false, includeProvena
                 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)
-                onUpdate({
+                publishUpdate({
                     data: source.data,
                     fromCache: source.fromCache,
                     status: source.status,
@@ -421,8 +485,35 @@ async function loadReadCacheResource({ cache, forceFresh = false, includeProvena
         }
         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",
@@ -452,7 +543,18 @@ async function loadReadCacheResource({ cache, forceFresh = false, includeProvena
         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,

package/dist-cjs/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[]>;

package/dist-cjs/readResourceBatch.js

@@ -0,0 +1,119 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.observeReadResourceBatch = observeReadResourceBatch;
+/** A mounted presentation barrier; child tasks retain sole network/cache ownership. */
+function observeReadResourceBatch({ count, observe, freshForMs, now, current, canRetain, retiredError, subscribe, onUpdate }) {
+    let disposed = false;
+    let retired = false;
+    let presented = false;
+    let strict = false;
+    let initialRetry;
+    let pending;
+    let failure;
+    let stop = () => { };
+    const children = [];
+    const disposedChildren = new Set();
+    const detach = () => { const cleanup = stop; stop = () => { }; cleanup(); };
+    const disposeChildren = () => children.forEach(child => {
+        if (!disposedChildren.has(child)) {
+            disposedChildren.add(child);
+            child.dispose();
+        }
+    });
+    const values = new Array(count);
+    const received = new Set();
+    const ages = new Array(count).fill(-Infinity);
+    const active = () => !disposed && !retired && current();
+    const retire = () => { retired = true; detach(); disposeChildren(); };
+    for (let index = 0; index < count; index++) {
+        const child = observe(index, update => {
+            if (disposed || retired)
+                return;
+            if (update.status === "invalidated" || update.status === "expired") {
+                onUpdate({ status: "invalidated" });
+                retire();
+                return;
+            }
+            if (!current())
+                return;
+            if ("data" in update) {
+                received.add(index);
+                values[index] = update.data;
+                if (!canRetain(update.data))
+                    strict = true;
+            }
+            // Denial retires the group even before every initial source has settled.
+            if (update.status === "failed") {
+                onUpdate(update);
+                presented = false;
+                retire();
+                return;
+            }
+            if (update.status === "retry") {
+                if (presented)
+                    failure = update;
+                else
+                    initialRetry = { error: update.error };
+            }
+        }, createdAt => { ages[index] = createdAt; });
+        children.push(child);
+        if (retired) {
+            disposeChildren();
+            break;
+        }
+    }
+    const refresh = (force = false) => {
+        if (!active() || !presented || strict)
+            return Promise.resolve();
+        if (pending)
+            return pending;
+        if (!force && ages.every((age, index) => now() - age < freshForMs[index]))
+            return Promise.resolve();
+        // Claim the barrier before a presentation callback can request it again.
+        pending = Promise.resolve().then(async () => {
+            if (!active() || strict)
+                return;
+            failure = undefined;
+            onUpdate({ status: "refreshing" });
+            if (!active() || strict)
+                return;
+            await Promise.all(children.map(child => child.refresh?.({ force })));
+            if (!active())
+                return;
+            if (failure)
+                onUpdate(failure);
+            else {
+                // Never expose a successful sibling beside an older failed member.
+                onUpdate({ status: "fresh", data: [...values] });
+                if (strict)
+                    detach();
+            }
+        }).finally(() => { pending = undefined; });
+        return pending;
+    };
+    if (!retired)
+        stop = subscribe(() => refresh());
+    const promise = Promise.allSettled(children.map(child => child.promise)).then(results => {
+        if (!active())
+            throw retiredError();
+        const rejected = results.find(result => result.status === "rejected");
+        if (rejected?.status === "rejected")
+            throw rejected.reason;
+        const data = results.map(result => result.value);
+        data.forEach((value, index) => { if (!received.has(index))
+            values[index] = value; });
+        presented = true;
+        // Presentation follows accepted canonical updates, while the promise keeps
+        // each shared source caller's original result (including duplicate positions).
+        onUpdate({ status: initialRetry === undefined ? "fresh" : "retained", data: [...values] });
+        if (initialRetry !== undefined && active())
+            onUpdate({ status: "retry", error: initialRetry.error });
+        if (strict)
+            detach();
+        return data;
+    });
+    return { promise,
+        refresh: ({ force = true } = {}) => active() && presented && !strict ? refresh(force) : undefined,
+        dispose() { disposed = true; detach(); disposeChildren(); },
+    };
+}

package/dist-cjs/readResourceObserver.d.ts

@@ -0,0 +1,57 @@
+export type ReadResourceUpdate<T> = {
+    status: "retained" | "fresh";
+    data: T;
+} | {
+    status: "refreshing";
+} | {
+    status: "retry";
+    error: unknown;
+} | {
+    status: "failed";
+    error: unknown;
+} | {
+    status: "expired";
+} | {
+    status: "invalidated";
+};
+export type ReadResourceSnapshot<T> = {
+    data: T;
+    confirmedAt: number;
+};
+export type ReadResourceObservation<T> = {
+    promise: Promise<T>;
+    refresh?: (options?: {
+        force?: boolean;
+    }) => Promise<void> | undefined;
+    dispose: () => void;
+};
+/**
+ * Mounted presentation only: hosts retain cache, transport, identity and initial
+ * read policy. Accepting a snapshot preserves its source age; a successful
+ * refresh does not require persistence to have survived an unrelated write.
+ */
+export declare function createReadResourceObserver<T, Snapshot>({ enabled, current, now, freshForMs, canRetain, isConnected, canonical, captureSnapshot, read, retireSnapshot, classifyFailure, subscribeWake, onUpdate, onData, onError, }: {
+    enabled?: boolean;
+    current: () => boolean;
+    now: () => number;
+    freshForMs: number;
+    canRetain: (data: T) => boolean;
+    isConnected?: () => boolean;
+    canonical: () => ReadResourceSnapshot<T> | undefined;
+    captureSnapshot: () => Snapshot;
+    read: () => Promise<ReadResourceSnapshot<T>>;
+    retireSnapshot: (snapshot: Snapshot) => Promise<void>;
+    classifyFailure: (error: unknown) => "transient" | "terminal" | "superseded" | "retired";
+    subscribeWake?: (listener: () => Promise<void>) => () => void;
+    onUpdate: (update: ReadResourceUpdate<T>) => void;
+    onData?: (data: T) => void;
+    onError?: (error: unknown) => void;
+}): {
+    accept: (update: ReadResourceUpdate<T>, age?: number) => void;
+    canRefresh: () => boolean;
+    refresh: ({ force }?: {
+        force?: boolean | undefined;
+    }) => Promise<void> | undefined;
+    retire(): void;
+    dispose(): void;
+};