@bayonai/offline 0.11.0 → 0.12.0

package/CHANGELOG.md

@@ -1,5 +1,11 @@
 # Changelog
 
+## 0.12.0 candidate - 2026-11-05
+
+- 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

@@ -464,3 +464,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-cjs/index.d.ts

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

package/dist-cjs/index.js

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

package/dist-cjs/pendingChangeTracker.d.ts

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

package/dist-cjs/pendingChangeTracker.js

@@ -0,0 +1,204 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.groupPendingChangeItems = groupPendingChangeItems;
+exports.createPendingChangeSnapshot = createPendingChangeSnapshot;
+exports.createPendingChangeTracker = createPendingChangeTracker;
+const recoveryPolicy_1 = require("./recoveryPolicy");
+/** Groups host-scoped rows without imposing account or domain semantics. */
+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. */
+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."
+            : (0, recoveryPolicy_1.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.
+ */
+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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bayonai/offline",
-  "version": "0.11.0",
+  "version": "0.12.0",
   "description": "Reusable offline read-cache, pending-write, and silent recovery primitives.",
   "license": "MIT",
   "author": "Bayon AI",