@bayonai/offline 0.12.0 → 0.15.0

package/CHANGELOG.md

@@ -1,6 +1,33 @@
 # Changelog
 
-## 0.12.0 candidate - 2026-11-05
+## 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
+  retirement, source-required reads and layered provenance without renewing
+  retained cache age. Snapshot identifiers protect newer cross-instance writes;
+  existing version-one envelopes remain readable without a database upgrade.
+
+## 0.12.0 - 2026-11-06
 
 - Add framework-neutral pending-change projection and observable tracker, with host-supplied existing queues/drafts, account and stale-read fencing, stable external-store snapshots, grouping/counts/guidance, and retained last known records on read failures.
 

package/README.md

@@ -74,6 +74,30 @@ exceptions are logged and isolated from the read.
 
 When refresh fails, `refreshFailure: "use-retained"` returns retained data
 with `status: "stale"` and the error; `"throw"` propagates the loader error.
+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
+envelopes remain readable; legacy comparison is limited to serializable values
+and cannot distinguish identical writes by older, identifier-unaware clients.
 This also applies to forced refresh. Set `forceFresh: true` on
 `loadReadCacheResource` or `readThroughCache` to bypass freshness, retain
 eligible data as the failure fallback, and advance the cache generation so an
@@ -81,6 +105,19 @@ older in-flight load cannot overwrite the refresh. `readThroughCache` returns
 the `status` field alongside its existing `fromCache`, `stale`, and `error`
 fields.
 
+Set `includeProvenance: true` to receive `cache-hit`, `source-confirmed`, or
+`retained-fallback` provenance. Cache-derived results include their original
+`savedAt`; fallback also carries `originalError` without normalizing it. Layered
+adapters may use `loadFreshResult` to pass a provenance-bearing
+`readThroughCache` result. Cached and fallback values from an inner layer are
+not persisted as fresh outer confirmations. `requireSource: true` rejects
+cached or fallback results and preserves a fallback's original failure. The
+host still owns authorization, account scoping and retention durations.
+Source confirmations include `confirmedAt` when provenance is requested;
+the built-in cache preserves that time on outer writes. Custom adapters may
+implement `setIfVersionAt` to preserve it. Without that capability, layered
+confirmations are delivered but not persisted by the outer adapter.
+
 For compatibility, callers that omit `policy` retain the previous `maxAgeMs`
 freshness behavior and have no age-based fallback expiry. New callers should
 use `policy`; when supplied it takes precedence over the legacy `maxAgeMs`.
@@ -257,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
@@ -383,7 +431,7 @@ pnpm --filter @bayonai/offline pack:smoke
 2. Run the 100% coverage gate and production dependency audit.
 3. Run `pnpm --filter @bayonai/offline pack:smoke` and confirm the tarball
    includes only `package.json`, `dist`, `dist-cjs`, `README.md`,
-   `CHANGELOG.md`, and `LICENSE`.
+   `CHANGELOG.md`, `RECOVERY.md`, and `LICENSE`.
 4. Install the generated tarball into an isolated consumer and verify ESM,
    CommonJS, and TypeScript declaration imports.
 5. Confirm `package.json` metadata, version, repository, license, and
@@ -485,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/pendingWriteConsolidation.js

@@ -35,7 +35,8 @@ export function projectPendingWriteFinalState(records, getKey, { isBarrier = ()
         const previous = latest.get(key);
         if (previous) {
             superseded.add(previous);
-            for (const effect of dependents.get(key) ?? [])
+            // Every latest entry creates its matching dependency list below.
+            for (const effect of dependents.get(key))
                 superseded.add(effect);
         }
         latest.set(key, record);

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

@@ -13,14 +13,21 @@ export type ReadCacheDriver = {
     clear: () => Promise<void>;
     close?: () => Promise<void>;
     delete: (key: string) => Promise<void>;
+    deleteIf?: (key: string, predicate: (value: unknown | null) => boolean) => Promise<boolean>;
     get: (key: string) => Promise<unknown | null>;
     listEntries?: () => Promise<Array<{
         key: string;
         value: unknown;
     }>>;
     set: (key: string, value: unknown) => Promise<void>;
+    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.
@@ -29,12 +36,15 @@ export type ReadCache = {
     clear: () => Promise<void>;
     close: () => Promise<void>;
     delete: (key: string) => Promise<void>;
+    /** Retire only a snapshot still owned by the captured generation. */
+    deleteIfVersion?: (key: string, version: string, snapshot: ReadCacheHit<unknown>) => Promise<boolean>;
     /** Advances a key's generation without deleting its retained value. */
     invalidate?: (key: string) => void;
     get: <T>(key: string) => Promise<ReadCacheHit<T> | null>;
     getVersion: (key: string) => string;
     set: <T>(key: string, value: T) => Promise<void>;
-    setIfVersion: <T>(key: string, value: T, version: string) => Promise<boolean>;
+    setIfVersion: <T>(key: string, value: T, version: string, snapshot?: ReadCacheHit<unknown> | null, confirmedAt?: string) => Promise<boolean>;
+    setIfVersionAt?: <T>(key: string, value: T, version: string, snapshot: ReadCacheHit<unknown> | null, confirmedAt: string) => Promise<boolean>;
 };
 export type ReadCachePolicy = {
     /** Time that a cached value can suppress a remote read. */
@@ -42,9 +52,10 @@ export type ReadCachePolicy = {
     /** Maximum age at which cached data remains eligible as an offline fallback. */
     retainForMs: number;
     /** Behavior when revalidation fails while retained data is available. */
-    refreshFailure: "use-retained" | "throw";
+    refreshFailure: "use-retained" | "throw" | ((error: unknown) => "use-retained" | "throw" | "retire");
 };
 export type ReadCacheStatus = "fresh" | "stale" | "miss";
+export type ReadCacheProvenance = "cache-hit" | "source-confirmed" | "retained-fallback";
 /** Payload-free cache lifecycle events suitable for host-owned telemetry. */
 export type ReadCacheOutcome = "fresh-hit" | "stale-hit" | "cache-miss" | "forced-refresh" | "loader-success" | "loader-failure";
 export type ReadThroughCacheResult<T> = {
@@ -53,12 +64,27 @@ export type ReadThroughCacheResult<T> = {
     fromCache: boolean;
     stale: boolean;
     status: ReadCacheStatus;
+    provenance?: ReadCacheProvenance;
+    confirmedAt?: string;
+    savedAt?: string;
+    originalError?: unknown;
 };
 export type ReadCacheResourceUpdate<T> = {
     data: T;
     error?: Error;
     fromCache: boolean;
     status: ReadCacheStatus;
+    provenance?: ReadCacheProvenance;
+    confirmedAt?: string;
+    savedAt?: string;
+    originalError?: unknown;
+};
+export type ReadCacheLoader<T> = {
+    loadFresh: () => Promise<T>;
+    loadFreshResult?: never;
+} | {
+    loadFresh?: never;
+    loadFreshResult: () => Promise<ReadThroughCacheResult<T>>;
 };
 export type BrowserReadCacheOptions = Partial<Pick<BrowserKeyValueDriverOptions, "databaseVersion" | "indexedDB">> & {
     databaseName: string;
@@ -84,29 +110,33 @@ export declare function pruneReadCache({ cache, maxAgeMs, now, }: {
     now?: () => number;
 }): Promise<number>;
 export declare function createReadCacheKey({ namespace, params, prefix, scope, }: ReadCacheKeyOptions): string;
-export declare function readThroughCache<T>({ cache, forceFresh, key, loadFresh, maxAgeMs, onOutcome, policy, }: {
+export declare function readThroughCache<T>({ cache, forceFresh, includeProvenance, key, loadFresh, loadFreshResult, maxAgeMs, onOutcome, policy, requireSource, }: {
     cache: ReadCache;
     /**
      * Revalidates after advancing the key generation, retaining the prior value
      * as a possible fallback if refresh fails.
      */
     forceFresh?: boolean;
+    includeProvenance?: boolean;
     key: string;
-    loadFresh: () => Promise<T>;
     maxAgeMs?: number;
     onOutcome?: (outcome: ReadCacheOutcome) => void;
     policy?: ReadCachePolicy;
-}): Promise<ReadThroughCacheResult<T>>;
-export declare function loadReadCacheResource<T>({ cache, forceFresh, key, loadFresh, maxAgeMs, onOutcome, policy, onCacheWriteError, onUpdate, skipCache, }: {
+    requireSource?: boolean;
+} & ReadCacheLoader<T>): Promise<ReadThroughCacheResult<T>>;
+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;
     key: string;
-    loadFresh: () => Promise<T>;
     maxAgeMs?: number;
     onOutcome?: (outcome: ReadCacheOutcome) => void;
     policy?: ReadCachePolicy;
     onCacheWriteError?: (error: Error) => void;
     onUpdate: (update: ReadCacheResourceUpdate<T>) => void;
     skipCache?: boolean;
-}): Promise<T>;
+    requireSource?: boolean;
+} & ReadCacheLoader<T>): Promise<T>;