@bayonai/offline 0.11.0 → 0.13.0

package/CHANGELOG.md

@@ -1,5 +1,18 @@
 # Changelog
 
+## 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.
+
+- Keep durable read failures visible throughout a retry, independently of capture failures; only current durable proof clears the failed read.
+
 ## 0.11.0
 
 - Add opt-in `projectPendingWriteFinalState` and store `consolidate` for final absolute setters. IndexedDB and memory retain winners and remove competing records atomically. Unknown effects, claims and cancellation deadlines remain ordering barriers. Legacy custom drivers retain records safely.

package/README.md

@@ -74,6 +74,15 @@ 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.
+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 +90,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`.
@@ -383,7 +405,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
@@ -464,3 +486,24 @@ cancel with superseded intent (for example, an award for a cancelled completion)
 Independent effects can opt out of being barriers with `isBarrier`; they stay in
 the queue. Claims and cancellation deadlines always fence both sides regardless
 of these callbacks. All callbacks are synchronous, pure host policy.
+
+### Observe pending changes without owning another queue
+
+`createPendingChangeTracker<T>()` observes host-supplied `load(accountKey)` and
+optional synchronous `capture(accountKey)` sources. Supply `subscribe(notify)`
+for existing command-store, draft and browser source notifications. It refreshes
+immediately, exposes stable `getSnapshot`/`subscribe` methods for external-store
+consumers, and releases its source subscription with `close()`.
+
+Hosts project real rows into `PendingChangeItem` (account, group, label, status
+and attention/storage/sending flags); generic host fields survive projection.
+`createPendingChangeSnapshot` also supports standalone synchronous consumers.
+Captured rows replace same-ID durable rows, groups preserve host order, and all
+counts and guidance derive from the resulting account-scoped rows. IDs must be
+unique across the host's sources unless replacement is intended.
+
+`setAccountKey` clears the previous account immediately and fences late reads.
+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.

package/RECOVERY.md

@@ -63,5 +63,17 @@ No queue record is discarded or reclassified merely because the app reopened.
 - Additional regression coverage: `src/recoveryRemediation.test.ts` exercises the
   four audited failure compositions with real IndexedDB reads and safe cleanup.
 
-
 Firestore server-only reads may report either exact “Failed to get documents from server.” or the exact SDK cache-retrieval guidance. These known messages classify as transient only when no structured code is present; terminal and unknown structured codes remain authoritative. Arbitrary messages containing connectivity words do not qualify.
+
+### Shared inspection source uncertainty
+
+`pendingChangeTracker` retains a failed durable read throughout a deferred retry,
+including when synchronous capture succeeds. Only current-generation durable
+proof clears that error. Capture failures remain independent and survive a
+successful durable read until capture itself succeeds. Last known account rows
+stay inspectable; account changes fence prior rows/errors and stale completions.
+Hosts must also project command-provider loading/hydration failures separately:
+an independent successful draft read does not establish an empty command queue.
+Inspection never acquires replay ownership. Coverage:
+`src/pendingChangeTracker.test.ts` and host
+`src/components/offline/PendingChangesIndicator.providers.test.tsx`.

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

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

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

package/dist/pendingChangeTracker.js

@@ -0,0 +1,199 @@
+import { getPendingChangesGuidance } from "./recoveryPolicy.js";
+/** Groups host-scoped rows without imposing account or domain semantics. */
+export function groupPendingChangeItems(items) {
+    const groups = new Map();
+    for (const item of items) {
+        let group = groups.get(item.groupKey);
+        if (!group) {
+            group = { key: item.groupKey, title: item.groupTitle, items: [] };
+            groups.set(item.groupKey, group);
+        }
+        group.items.push(item);
+    }
+    return [...groups.values()];
+}
+/** Same-ID captured edits replace durable rows; insertion order remains stable. */
+export function createPendingChangeSnapshot({ accountKey, items, isOffline = false, loading = false, readError = null, }) {
+    const unique = new Map();
+    for (const item of items) {
+        if (accountKey !== null && item.accountKey === accountKey)
+            unique.set(item.id, { ...item });
+    }
+    const rows = [...unique.values()];
+    const groups = groupPendingChangeItems(rows);
+    const draftCount = rows.filter((item) => item.status === "draft").length;
+    const readyCount = rows.filter((item) => item.status === "waiting" || item.status === "sending").length;
+    const attentionCount = rows.filter((item) => item.needsAttention || item.status === "attention").length;
+    const storageErrorCount = rows.filter((item) => item.storageError || item.status === "storage-error").length;
+    return {
+        accountKey,
+        items: rows,
+        groups,
+        count: rows.length,
+        draftCount,
+        readyCount,
+        attentionCount,
+        storageErrorCount,
+        sendingCount: rows.filter((item) => item.sending || item.status === "sending").length,
+        guidance: readError !== null
+            ? "Pending changes could not be read. Your last known changes are preserved."
+            : getPendingChangesGuidance({
+                hasReadyChanges: readyCount > 0,
+                hasDrafts: draftCount > 0,
+                hasErrors: attentionCount > 0 || storageErrorCount > 0 || readError !== null,
+                isOffline,
+            }),
+        loading,
+        readError,
+    };
+}
+/**
+ * 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 function createPendingChangeTracker(options) {
+    let accountKey = options.accountKey ?? null;
+    let isOffline = options.isOffline ?? false;
+    let durable = [];
+    let captured = [];
+    let durableReadError = null;
+    let captureReadError = null;
+    let loading = false;
+    let generation = 0;
+    let closed = false;
+    const listeners = new Set();
+    let snapshot = createPendingChangeSnapshot({
+        accountKey,
+        items: [],
+        isOffline,
+    });
+    const report = (error) => {
+        try {
+            if (options.onError)
+                options.onError(error);
+            else
+                console.error("Pending-change tracker could not read host changes; retaining the last known account snapshot.", error);
+        }
+        catch (callbackError) {
+            console.error("Pending-change tracker error reporter failed while reporting a host source failure.", callbackError, error);
+        }
+    };
+    const publish = () => {
+        const publishingGeneration = generation;
+        snapshot = createPendingChangeSnapshot({
+            accountKey,
+            items: [...durable, ...captured],
+            isOffline,
+            loading,
+            readError: durableReadError ?? captureReadError,
+        });
+        for (const listener of [...listeners]) {
+            if (closed || publishingGeneration !== generation)
+                return;
+            try {
+                listener();
+            }
+            catch (error) {
+                console.error("Pending-change tracker subscriber failed; other subscribers will still receive updates.", error);
+            }
+        }
+    };
+    const refresh = async () => {
+        if (closed)
+            return;
+        const request = ++generation;
+        const requestedAccount = accountKey;
+        const current = () => !closed && request === generation && requestedAccount === accountKey;
+        if (requestedAccount === null)
+            return;
+        // Capture callbacks may notify sources or switch accounts synchronously.
+        const capture = () => {
+            try {
+                const rows = options.capture?.(requestedAccount) ?? [];
+                if (!current())
+                    return;
+                captured = rows;
+                captureReadError = null;
+            }
+            catch (error) {
+                if (!current())
+                    return;
+                captureReadError = error;
+                report(error);
+            }
+        };
+        capture();
+        if (!current())
+            return;
+        loading = true;
+        publish();
+        if (!current())
+            return;
+        try {
+            const rows = await options.load(requestedAccount);
+            if (!current())
+                return;
+            // A successful capture cannot prove durable storage recovered.
+            durableReadError = null;
+            durable = rows;
+            // A durable read may retire host acceptance receipts without emitting an
+            // event. Recapture after proof so drained receipts cannot become ghosts.
+            capture();
+        }
+        catch (error) {
+            if (!current())
+                return;
+            durableReadError = error;
+            report(error);
+        }
+        if (!current())
+            return;
+        loading = false;
+        publish();
+    };
+    const unsubscribe = options.subscribe?.(() => {
+        void refresh();
+    });
+    const tracker = {
+        getSnapshot: () => snapshot,
+        subscribe: (listener) => {
+            if (closed)
+                return () => { };
+            listeners.add(listener);
+            return () => {
+                listeners.delete(listener);
+            };
+        },
+        refresh,
+        setAccountKey: (next) => {
+            if (closed || next === accountKey)
+                return;
+            ++generation;
+            accountKey = next;
+            durable = [];
+            captured = [];
+            durableReadError = null;
+            captureReadError = null;
+            loading = false;
+            publish();
+            void refresh();
+        },
+        setOffline: (next) => {
+            if (closed || next === isOffline)
+                return;
+            isOffline = next;
+            publish();
+        },
+        close: () => {
+            if (closed)
+                return;
+            closed = true;
+            ++generation;
+            unsubscribe?.();
+            listeners.clear();
+        },
+    };
+    void refresh();
+    return tracker;
+}

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/readCache.d.ts

@@ -13,12 +13,14 @@ 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 = {
     /**
@@ -29,12 +31,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 +47,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 +59,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 +105,31 @@ 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, forceFresh, includeProvenance, key, loadFresh, loadFreshResult, maxAgeMs, onOutcome, policy, onCacheWriteError, onUpdate, skipCache, requireSource, }: {
     cache: ReadCache;
     /** 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>;