@bayonai/offline 0.13.0 → 0.15.0

package/CHANGELOG.md

@@ -1,5 +1,25 @@
 # Changelog
 
+## 0.15.0 - 2026-11-07
+
+- Add framework-neutral mounted read observation, atomic batch presentation and
+  native browser wake binding, with host-owned authorization, transport, cache
+  policy and exact-snapshot retirement. Preserve original source age, independent
+  source promises, scoped disposal and initial-only refresh intent.
+- Add opt-in canonical cache delivery with atomic commit receipts. Newer
+  cross-instance confirmations and local invalidation fence obsolete presentation;
+  default immediate callbacks and nonblocking writes remain unchanged.
+- Preserve canonical updates separately from raw child results and retire denied
+  groups immediately, including before initial settlement. Handle reentrant wakes,
+  undefined positions/errors and listener cleanup without duplicate reads.
+
+## 0.14.0 - 2026-11-07
+
+- Serialize overlapping replay calls with different selection or execution
+  policies per store and scope. Identical calls still coalesce; each distinct
+  caller receives its own results. Callers that depended on scope-only
+  coalescing should use stable callback references or handle separate summaries.
+
 ## 0.13.0 - 2026-11-06
 
 - Add opt-in host-classified read failure handling, conditional terminal

package/README.md

@@ -78,6 +78,21 @@ An opt-in callback can classify the original failure as `"use-retained"`,
 `"throw"`, or `"retire"`. Retire propagates the original failure and
 conditionally removes the captured snapshot; a later confirmation is preserved.
 Built-in memory and IndexedDB drivers support atomic snapshot comparison.
+`loadReadCacheResource({ deliveryPolicy: "cache-current", ... })` opts into
+awaiting an atomic commit receipt before presenting the canonical retained
+cache snapshot. Canonical updates carry `cache-hit` provenance and their stored
+age, including when this call wrote that snapshot. The returned promise still
+settles with this call's source result. A lost ownership comparison may adopt
+another instance's eligible confirmation; local invalidation suppresses delivery.
+This fences confirmations committed before the comparison, not future writes or
+cross-tab notifications. The default `immediate` policy keeps nonblocking writes.
+With `requireSource`, only the successfully committed source result can be
+presented as source-confirmed; a lost ownership comparison suppresses delivery.
+Opted-in presentation callback errors are logged independently of source success.
+Custom caches must implement `commitIfVersion`, returning `{ written, version }`
+with the generation captured inside the atomic commit after its own invalidation.
+Built-in caches require the driver's atomic `setIf` for this mode. Missing atomic
+support or storage failure logs an error and suppresses uncertain presentation.
 Custom adapters must implement `deleteIfVersion` with equivalent atomic
 ownership checks; without it, retirement is logged and cannot be guaranteed.
 New envelopes carry an opaque snapshot identifier. Existing version-one
@@ -279,6 +294,17 @@ the later write queued until the predecessor is delivered. This protects remote
 write order; it does not replace idempotent server-side mutation handling for
 ambiguous request outcomes.
 
+Overlapping `syncPendingWrites` calls for the same store and scope share a
+single replay only when their selection and sync callbacks, clock, and
+stop-on-failure setting are identical. Different requests run in arrival order
+and each receives results for its own selection. Use stable callback references
+when callers intentionally share a run. Separate scopes remain independent.
+A failed storage operation rejects its own call and does not prevent a later
+queued recovery from attempting a fresh read. Migration: callers that previously
+relied on scope-only coalescing with newly created inline callbacks should either
+keep stable callback references or expect each serialized call to report its own
+attempts and remaining count.
+
 ## Durable Command Store
 
 Use `createDurableCommandStore` when a host needs one client-side owner for
@@ -507,3 +533,52 @@ Read failures retain the current account's last known rows and expose `readError
 provide `onError` for host diagnostics (otherwise the tracker logs to console).
 Call `setOffline` when connectivity changes. The tracker never persists, executes,
 consolidates or retires operations, and adds no schema, jobs or provider imports.
+
+## Mounted read presentation
+
+`createReadResourceObserver<T, Snapshot>` owns mounted refresh presentation over
+the host's existing cache and shared source reader. The host calls
+`accept(update, confirmedAt)` for its initial delivery; the timestamp must be
+the original cache/source confirmation time. The controller stores age and
+eligibility, not another copy of the value. `canRetain(data)` excludes mutation
+affordances or other values requiring a strict contract.
+
+`refresh()` explicitly forces a confirmation; wake subscriptions invoke ordinary
+freshness checks. A fresh canonical host snapshot may satisfy ordinary recovery
+without a source request. A host-classified superseded read adopts that snapshot
+immediately. Transient failures preserve the mounted value and original age;
+terminal failures call `retireSnapshot` with the exact token captured before the
+read, clear confirmation, and emit `failed`. The host must condition retirement
+on token ownership and current authority. Failed cleanup is logged separately
+and does not hide the terminal failure.
+
+The host owns initial force versus persistent strict mode, identity, authorization,
+connectivity/visibility, read eligibility, TTLs and transport sharing. Set
+`enabled: false` for strict/noncacheable/command observations; their initial data
+can still be accepted but they never subscribe or refresh. The controller uses
+no timer or retry engine. `subscribeWake` returns an unsubscribe function;
+`dispose()` silently fences callbacks and detaches it. `retire()` emits one safe
+invalidation even after scope changes. Neither cancels an already-running shared
+source promise.
+
+`observeReadResourceBatch<T>` composes host child observations into one mounted
+presentation barrier. It retains child order, duplicate positions and explicit
+`undefined` results. Children retain all source/cache ownership; the barrier
+records only their current presentation values and source ages. During refresh,
+a temporary failure keeps the last complete array visible. A terminal child
+failure retires the whole presentation immediately, including while another
+child stalls, and later sibling completions cannot revive it.
+
+The initial presentation follows accepted child callbacks, filling positions
+without a callback from settled child promises. The batch promise preserves the
+original child promise results, which may differ from newer canonical callback
+values. Use child callbacks for presentation and promise results for source-call
+settlement. Forced refresh, ordinary freshness checks, strict-value exclusion,
+scope checks and disposal follow the scalar contract. No second cache, automatic
+write replay, schema change or scheduling service is introduced.
+
+`bindBrowserReadLifecycle({ window, document }, notify)` forwards native focus,
+online and visibility-change events and returns idempotent cleanup. Hosts keep
+visibility/connectivity checks and transport coordination inside `notify`.
+Synchronous throws and rejected wake promises are logged without escaping the
+native event callback. This binding does not acquire pending-write replay ownership.

package/RECOVERY.md

@@ -10,6 +10,9 @@ This is the package-owned product contract for all offline consumers, establishe
 - `createBrowserPendingWriteRecovery` owns silent startup, focus, reconnect and
   capped exponential-backoff recovery. Reuse its coordination and ordered executor;
   never add a second replay owner, a billable job or a recurring server service.
+- Concurrent replay for one store and scope serializes different selection and
+  execution policies; only identical requests share results. Each caller must
+  see its own selection and failure policy, including after a rejected read.
 - `getPendingChangesGuidance` supplies common guidance without domain payloads.
   Ready work syncs automatically; unfinished drafts need editing before submission.
   Rejected work stays preserved. No retry button is part of pending inspection.

package/dist/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/browserReadLifecycle.js

@@ -0,0 +1,24 @@
+/** Native wake binding only; hosts own visibility, eligibility and request sharing. */
+export 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/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/index.js

@@ -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/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/pendingWrites.js

@@ -285,30 +285,34 @@ export async function syncPendingWrite({ id, now = () => new Date().toISOString(
         : { 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.
  */
-export function syncPendingWrites({ now, scopeKey = "all", select = () => true, stopOnFailure = false, store, sync, }) {
+export 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;
@@ -346,6 +350,7 @@ export 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/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/readCache.js

@@ -48,7 +48,7 @@ export 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 () => {
@@ -64,15 +64,28 @@ export 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;
@@ -339,7 +352,7 @@ export async function readThroughCache({ cache, forceFresh = false, includeProve
         throw error;
     }
 }
-export async function loadReadCacheResource({ cache, forceFresh = false, includeProvenance = false, key, loadFresh, loadFreshResult, maxAgeMs, onOutcome, policy, onCacheWriteError, onUpdate, skipCache = false, requireSource = 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);
@@ -367,11 +380,56 @@ export async function loadReadCacheResource({ cache, forceFresh = false, include
     // 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",
@@ -393,8 +451,14 @@ export async function loadReadCacheResource({ cache, forceFresh = false, include
                 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,
@@ -411,8 +475,35 @@ export async function loadReadCacheResource({ cache, forceFresh = false, include
         }
         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",
@@ -442,7 +533,18 @@ export async function loadReadCacheResource({ cache, forceFresh = false, include
         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/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/readResourceBatch.js

@@ -0,0 +1,116 @@
+/** A mounted presentation barrier; child tasks retain sole network/cache ownership. */
+export 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/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;
+};