@bayonai/offline 0.10.1 → 0.12.0

package/CHANGELOG.md

@@ -1,5 +1,15 @@
 # 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.
+
 ## 0.10.1 - 2026-11-04
 
 - Recognize two exact Firestore server-only cache diagnostics as transient while retaining terminal-code precedence.

package/README.md

@@ -414,3 +414,74 @@ no TypeScript parser, Firebase SDK, or host-domain module. Bounded's real catalo
 read-family recipe lives in `src/lib/lists/catalogReadBoundary.test.ts` and works
 with its existing cache behavior tests. This locally added export requires an
 intentional future package release before registry consumers can adopt it.
+
+## Consolidate unsent absolute state
+
+`store.consolidate(getSupersessionKey)` atomically retires earlier unclaimed
+absolute setters with the same explicit account/entity/field key. Call after
+acceptance and before recovery to compact historical queue records too. Keep the
+latest setter even when the remote baseline is unknown. This capability is
+optional on custom stores; built-in stores always expose it. Legacy custom
+drivers without atomic `deleteSelected` retain records and return zero.
+
+```ts
+await store.set(nextIntent);
+await store.consolidate?.((record) =>
+  record.payload.kind === "setCompleted"
+    ? JSON.stringify([
+        record.payload.accountId,
+        record.payload.taskId,
+        "completed",
+      ])
+    : null,
+);
+```
+
+Return null for effects, partial patches, overlapping fields, moves/access changes,
+assignments with notifications and commands that observe earlier state. Null keys,
+syncing records (including expired claims), explicit `syncingAt` and any
+`notBefore` deadline fence both sides of the ordered lane. Distinct recurrence
+occurrences must not share a setter key. Hosts own the keys and their proof of
+independence. All ordinary setters between barriers must commute with the omitted
+older setters; do not key commands merely because they target the same entity.
+
+`projectPendingWriteFinalState(records, getSupersessionKey)` provides the same
+pure ordered view for display/capture overlays. It does not establish durability
+and must not justify dropping live optimistic receipts before storage succeeds.
+Consolidation emits clear events only after the deletion transaction commits.
+No envelope schema or database upgrade is required. Driver implementations of
+`deleteSelected` must select and delete in one atomic transaction and propagate
+failures without partial mutation. Policy callbacks are synchronous and pure.
+
+Related effects may explicitly depend on an unsent setter: supply
+`getDependencyKey(effect)` returning that setter's key and optionally
+`isDependencySatisfied(effect, state)`. When a later setter supersedes the
+prerequisite, its pending dependent effects retire with it. A false dependency
+check retires an effect attached to a cancelling latest setter. Without an
+unclaimed prerequisite in the same barrier-bounded lane, effects remain ordered.
+Use this only for dependent consequences that the host explicitly wants to
+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/idbDriver.d.ts

@@ -1,4 +1,11 @@
+export type KeyValueEntry = {
+    key: string;
+    value: unknown;
+};
+export type KeyValueDeletionSelector = (entries: KeyValueEntry[]) => readonly string[];
 export type BrowserKeyValueDriver = {
+    /** Select and delete within one transaction, including the winning-record read. */
+    deleteSelected?: (select: KeyValueDeletionSelector) => Promise<string[]>;
     clear: () => Promise<void>;
     close: () => Promise<void>;
     delete: (key: string) => Promise<void>;

package/dist/idbDriver.js

@@ -43,6 +43,48 @@ export function createIdbKeyValueDriver({ databaseName, databaseVersion = 1, ind
         });
     }
     return {
+        async deleteSelected(select) {
+            return runTransactionalStorageOperation({
+                failureMode: "throw",
+                fallback: [],
+                operationName: "consolidate pending keys",
+                storeName,
+                timeoutMs: operationTimeoutMs,
+                operation: async (setTransaction, isCancelled) => {
+                    const database = await getDatabase();
+                    if (isCancelled())
+                        return [];
+                    const transaction = database.transaction(storeName, "readwrite");
+                    setTransaction(transaction);
+                    try {
+                        const objectStore = transaction.objectStore(storeName);
+                        const [keys, values] = await Promise.all([
+                            objectStore.getAllKeys(),
+                            objectStore.getAll(),
+                        ]);
+                        const entries = keys.map((key, index) => ({
+                            key: String(key),
+                            value: values[index],
+                        }));
+                        const existingKeys = new Set(entries.map((entry) => entry.key));
+                        const selected = [...new Set(select(entries))].filter((key) => existingKeys.has(key));
+                        await Promise.all(selected.map((key) => objectStore.delete(key)));
+                        await transaction.done;
+                        return selected;
+                    }
+                    catch (error) {
+                        // A policy failure must roll back, never commit a partial selection.
+                        try {
+                            transaction.abort();
+                        }
+                        catch {
+                            /* Already aborted or settled. */
+                        }
+                        throw error;
+                    }
+                },
+            });
+        },
         async clear() {
             await runMutation("clear object store", (objectStore) => objectStore.clear());
         },

package/dist/index.d.ts

@@ -8,3 +8,5 @@ export { OfflineStorageError } from "./idbDriver.js";
 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

@@ -8,3 +8,5 @@ export { OfflineStorageError } from "./idbDriver.js";
 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.d.ts

@@ -0,0 +1,17 @@
+import type { PendingWriteRecord } from "./pendingWrites.js";
+/** Host keys must identify account, entity and one independent absolute field. */
+export type PendingWriteSupersessionKey<Payload> = (record: PendingWriteRecord<Payload>) => string | null;
+export type PendingWriteConsolidationOptions<Payload> = {
+    /** Optional effects that belong to the latest unsent keyed setter. */
+    getDependencyKey?: PendingWriteSupersessionKey<Payload>;
+    /** False retires a dependent effect whose latest unsent prerequisite cancels it. */
+    isDependencySatisfied?: (effect: PendingWriteRecord<Payload>, state: PendingWriteRecord<Payload>) => boolean;
+    /** A host may prove an unkeyed effect independent; it remains in the queue. */
+    isBarrier?: (record: PendingWriteRecord<Payload>) => boolean;
+};
+/**
+ * Keep final absolute state, never infer cancellation of effects. Unknown commands,
+ * claims (even expired ones) and Undo deadlines fence both sides of the lane.
+ * This pure view does not establish durability; stores compact atomically.
+ */
+export declare function projectPendingWriteFinalState<Payload>(records: readonly PendingWriteRecord<Payload>[], getKey: PendingWriteSupersessionKey<Payload>, { isBarrier, getDependencyKey, isDependencySatisfied, }?: PendingWriteConsolidationOptions<Payload>): PendingWriteRecord<Payload>[];

package/dist/pendingWriteConsolidation.js

@@ -0,0 +1,45 @@
+/**
+ * Keep final absolute state, never infer cancellation of effects. Unknown commands,
+ * claims (even expired ones) and Undo deadlines fence both sides of the lane.
+ * This pure view does not establish durability; stores compact atomically.
+ */
+export function projectPendingWriteFinalState(records, getKey, { isBarrier = () => true, getDependencyKey, isDependencySatisfied, } = {}) {
+    const ordered = [...records].sort((a, b) => a.savedAt.localeCompare(b.savedAt) || a.id.localeCompare(b.id));
+    const latest = new Map();
+    const dependents = new Map();
+    const superseded = new Set();
+    for (const record of ordered) {
+        const key = getKey(record);
+        if (record.syncStatus === "syncing" ||
+            record.syncingAt ||
+            record.notBefore) {
+            latest.clear();
+            dependents.clear();
+            continue;
+        }
+        if (key === null) {
+            const dependencyKey = getDependencyKey?.(record);
+            const prerequisite = dependencyKey == null ? undefined : latest.get(dependencyKey);
+            if (prerequisite && dependencyKey != null) {
+                if (isDependencySatisfied?.(record, prerequisite) === false)
+                    superseded.add(record);
+                else
+                    dependents.get(dependencyKey).push(record);
+            }
+            else if (isBarrier(record)) {
+                latest.clear();
+                dependents.clear();
+            }
+            continue;
+        }
+        const previous = latest.get(key);
+        if (previous) {
+            superseded.add(previous);
+            for (const effect of dependents.get(key) ?? [])
+                superseded.add(effect);
+        }
+        latest.set(key, record);
+        dependents.set(key, []);
+    }
+    return ordered.filter((record) => !superseded.has(record));
+}

package/dist/pendingWrites.d.ts

@@ -1,4 +1,5 @@
-import { type BrowserKeyValueDriverOptions } from "./idbDriver.js";
+import { type PendingWriteSupersessionKey, type PendingWriteConsolidationOptions } from "./pendingWriteConsolidation.js";
+import { type BrowserKeyValueDriverOptions, type KeyValueDeletionSelector } from "./idbDriver.js";
 export declare const pendingWriteSchemaVersion = 1;
 export declare const pendingWriteOperationTimeoutMs = 2000;
 export declare const pendingWriteSyncLeaseTimeoutMs = 60000;
@@ -20,6 +21,8 @@ export type PendingWriteRecordInput<Payload = unknown> = Omit<PendingWriteRecord
 };
 export type PendingWritePayloadNormalizer<Payload = unknown> = (payload: unknown) => Payload | null;
 export type PendingWriteDriver = {
+    /** Optional for legacy drivers; must read and delete atomically. */
+    deleteSelected?: (select: KeyValueDeletionSelector) => Promise<string[]>;
     clear: (key: string) => Promise<void>;
     clearIf: (key: string, predicate: PendingWritePredicate) => Promise<boolean>;
     clearAll?: () => Promise<void>;
@@ -48,6 +51,8 @@ export type PendingWriteStoreChange<Payload = unknown> = {
 };
 export type PendingWriteStoreChangeListener<Payload = unknown> = (change: PendingWriteStoreChange<Payload>) => void;
 export type PendingWriteStore<Payload = unknown> = {
+    /** Retire competing absolute setters atomically; custom stores may omit it. */
+    consolidate?: (getKey: PendingWriteSupersessionKey<Payload>, options?: PendingWriteConsolidationOptions<Payload>) => Promise<number>;
     claimIfSnapshotId: (id: string, snapshotId: string, record: PendingWriteRecord<Payload>, now: string) => Promise<boolean>;
     clear: (id: string) => Promise<void>;
     clearAll: () => Promise<void>;

package/dist/pendingWrites.js

@@ -1,3 +1,4 @@
+import { projectPendingWriteFinalState, } from "./pendingWriteConsolidation.js";
 import { createIdbKeyValueDriver, OfflineStorageError, } from "./idbDriver.js";
 export const pendingWriteSchemaVersion = 1;
 export const pendingWriteOperationTimeoutMs = 2_000;
@@ -41,6 +42,36 @@ export function createPendingWriteStore(driver, { keyPrefix, normalizeLegacyReco
         return records.filter((record) => Boolean(record));
     }
     return {
+        async consolidate(getKey, options) {
+            if (!driver.deleteSelected)
+                return 0;
+            const removedIds = new Map();
+            const deleted = await driver.deleteSelected((entries) => {
+                const scoped = entries.filter(({ key }) => key.startsWith(`${keyPrefix}:`));
+                const records = scoped.map(({ value }) => toPendingWriteEnvelope(value, schemaVersion, {
+                    normalizeLegacyRecord,
+                    normalizePayload,
+                })?.record);
+                // An unreadable envelope may be an ordering barrier from a newer host.
+                // Never infer that skipping it makes its neighbours commute.
+                if (records.some((record) => !record))
+                    return [];
+                const valid = records;
+                const retained = new Set(projectPendingWriteFinalState(valid, getKey, options));
+                return scoped
+                    .filter((entry, index) => {
+                    const record = valid[index];
+                    if (retained.has(record))
+                        return false;
+                    removedIds.set(entry.key, record.id);
+                    return true;
+                })
+                    .map((entry) => entry.key);
+            });
+            for (const key of deleted)
+                notify({ id: removedIds.get(key), type: "clear" });
+            return deleted.length;
+        },
         async claimIfSnapshotId(id, snapshotId, record, now) {
             const claimed = await driver.setIf(createPendingWriteKey({ id, prefix: keyPrefix }), { record, schemaVersion }, (value) => {
                 const current = toPendingWriteEnvelope(value, schemaVersion, {
@@ -127,6 +158,13 @@ export function createPendingWriteStore(driver, { keyPrefix, normalizeLegacyReco
 export function createMemoryPendingWriteDriver() {
     const records = new Map();
     return {
+        async deleteSelected(select) {
+            // No await between observing winners and deleting obsolete records.
+            const selected = [
+                ...new Set(select([...records].map(([key, value]) => ({ key, value })))),
+            ];
+            return selected.filter((key) => records.delete(key));
+        },
         async clear(key) {
             records.delete(key);
         },
@@ -425,6 +463,7 @@ function createUnavailablePendingWriteDriver() {
 }
 function toPendingWriteDriver(driver) {
     return {
+        deleteSelected: driver.deleteSelected,
         clear: driver.delete,
         clearIf: driver.deleteIf,
         clearAll: driver.clear,

package/dist-cjs/idbDriver.d.ts

@@ -1,4 +1,11 @@
+export type KeyValueEntry = {
+    key: string;
+    value: unknown;
+};
+export type KeyValueDeletionSelector = (entries: KeyValueEntry[]) => readonly string[];
 export type BrowserKeyValueDriver = {
+    /** Select and delete within one transaction, including the winning-record read. */
+    deleteSelected?: (select: KeyValueDeletionSelector) => Promise<string[]>;
     clear: () => Promise<void>;
     close: () => Promise<void>;
     delete: (key: string) => Promise<void>;

package/dist-cjs/idbDriver.js

@@ -48,6 +48,48 @@ function createIdbKeyValueDriver({ databaseName, databaseVersion = 1, indexedDB
         });
     }
     return {
+        async deleteSelected(select) {
+            return runTransactionalStorageOperation({
+                failureMode: "throw",
+                fallback: [],
+                operationName: "consolidate pending keys",
+                storeName,
+                timeoutMs: operationTimeoutMs,
+                operation: async (setTransaction, isCancelled) => {
+                    const database = await getDatabase();
+                    if (isCancelled())
+                        return [];
+                    const transaction = database.transaction(storeName, "readwrite");
+                    setTransaction(transaction);
+                    try {
+                        const objectStore = transaction.objectStore(storeName);
+                        const [keys, values] = await Promise.all([
+                            objectStore.getAllKeys(),
+                            objectStore.getAll(),
+                        ]);
+                        const entries = keys.map((key, index) => ({
+                            key: String(key),
+                            value: values[index],
+                        }));
+                        const existingKeys = new Set(entries.map((entry) => entry.key));
+                        const selected = [...new Set(select(entries))].filter((key) => existingKeys.has(key));
+                        await Promise.all(selected.map((key) => objectStore.delete(key)));
+                        await transaction.done;
+                        return selected;
+                    }
+                    catch (error) {
+                        // A policy failure must roll back, never commit a partial selection.
+                        try {
+                            transaction.abort();
+                        }
+                        catch {
+                            /* Already aborted or settled. */
+                        }
+                        throw error;
+                    }
+                },
+            });
+        },
         async clear() {
             await runMutation("clear object store", (objectStore) => objectStore.clear());
         },

package/dist-cjs/index.d.ts

@@ -8,3 +8,5 @@ export { OfflineStorageError } from "./idbDriver.js";
 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

@@ -14,7 +14,7 @@ var __exportStar = (this && this.__exportStar) || function(m, exports) {
     for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.OfflineStorageError = void 0;
+exports.projectPendingWriteFinalState = exports.OfflineStorageError = void 0;
 __exportStar(require("./readCache"), exports);
 __exportStar(require("./pendingWrites"), exports);
 __exportStar(require("./browserRecovery"), exports);
@@ -26,3 +26,6 @@ Object.defineProperty(exports, "OfflineStorageError", { enumerable: true, get: f
 __exportStar(require("./readBoundary"), exports);
 __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/dist-cjs/pendingWriteConsolidation.d.ts

@@ -0,0 +1,17 @@
+import type { PendingWriteRecord } from "./pendingWrites.js";
+/** Host keys must identify account, entity and one independent absolute field. */
+export type PendingWriteSupersessionKey<Payload> = (record: PendingWriteRecord<Payload>) => string | null;
+export type PendingWriteConsolidationOptions<Payload> = {
+    /** Optional effects that belong to the latest unsent keyed setter. */
+    getDependencyKey?: PendingWriteSupersessionKey<Payload>;
+    /** False retires a dependent effect whose latest unsent prerequisite cancels it. */
+    isDependencySatisfied?: (effect: PendingWriteRecord<Payload>, state: PendingWriteRecord<Payload>) => boolean;
+    /** A host may prove an unkeyed effect independent; it remains in the queue. */
+    isBarrier?: (record: PendingWriteRecord<Payload>) => boolean;
+};
+/**
+ * Keep final absolute state, never infer cancellation of effects. Unknown commands,
+ * claims (even expired ones) and Undo deadlines fence both sides of the lane.
+ * This pure view does not establish durability; stores compact atomically.
+ */
+export declare function projectPendingWriteFinalState<Payload>(records: readonly PendingWriteRecord<Payload>[], getKey: PendingWriteSupersessionKey<Payload>, { isBarrier, getDependencyKey, isDependencySatisfied, }?: PendingWriteConsolidationOptions<Payload>): PendingWriteRecord<Payload>[];

package/dist-cjs/pendingWriteConsolidation.js

@@ -0,0 +1,48 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.projectPendingWriteFinalState = projectPendingWriteFinalState;
+/**
+ * Keep final absolute state, never infer cancellation of effects. Unknown commands,
+ * claims (even expired ones) and Undo deadlines fence both sides of the lane.
+ * This pure view does not establish durability; stores compact atomically.
+ */
+function projectPendingWriteFinalState(records, getKey, { isBarrier = () => true, getDependencyKey, isDependencySatisfied, } = {}) {
+    const ordered = [...records].sort((a, b) => a.savedAt.localeCompare(b.savedAt) || a.id.localeCompare(b.id));
+    const latest = new Map();
+    const dependents = new Map();
+    const superseded = new Set();
+    for (const record of ordered) {
+        const key = getKey(record);
+        if (record.syncStatus === "syncing" ||
+            record.syncingAt ||
+            record.notBefore) {
+            latest.clear();
+            dependents.clear();
+            continue;
+        }
+        if (key === null) {
+            const dependencyKey = getDependencyKey?.(record);
+            const prerequisite = dependencyKey == null ? undefined : latest.get(dependencyKey);
+            if (prerequisite && dependencyKey != null) {
+                if (isDependencySatisfied?.(record, prerequisite) === false)
+                    superseded.add(record);
+                else
+                    dependents.get(dependencyKey).push(record);
+            }
+            else if (isBarrier(record)) {
+                latest.clear();
+                dependents.clear();
+            }
+            continue;
+        }
+        const previous = latest.get(key);
+        if (previous) {
+            superseded.add(previous);
+            for (const effect of dependents.get(key) ?? [])
+                superseded.add(effect);
+        }
+        latest.set(key, record);
+        dependents.set(key, []);
+    }
+    return ordered.filter((record) => !superseded.has(record));
+}

package/dist-cjs/pendingWrites.d.ts

@@ -1,4 +1,5 @@
-import { type BrowserKeyValueDriverOptions } from "./idbDriver.js";
+import { type PendingWriteSupersessionKey, type PendingWriteConsolidationOptions } from "./pendingWriteConsolidation.js";
+import { type BrowserKeyValueDriverOptions, type KeyValueDeletionSelector } from "./idbDriver.js";
 export declare const pendingWriteSchemaVersion = 1;
 export declare const pendingWriteOperationTimeoutMs = 2000;
 export declare const pendingWriteSyncLeaseTimeoutMs = 60000;
@@ -20,6 +21,8 @@ export type PendingWriteRecordInput<Payload = unknown> = Omit<PendingWriteRecord
 };
 export type PendingWritePayloadNormalizer<Payload = unknown> = (payload: unknown) => Payload | null;
 export type PendingWriteDriver = {
+    /** Optional for legacy drivers; must read and delete atomically. */
+    deleteSelected?: (select: KeyValueDeletionSelector) => Promise<string[]>;
     clear: (key: string) => Promise<void>;
     clearIf: (key: string, predicate: PendingWritePredicate) => Promise<boolean>;
     clearAll?: () => Promise<void>;
@@ -48,6 +51,8 @@ export type PendingWriteStoreChange<Payload = unknown> = {
 };
 export type PendingWriteStoreChangeListener<Payload = unknown> = (change: PendingWriteStoreChange<Payload>) => void;
 export type PendingWriteStore<Payload = unknown> = {
+    /** Retire competing absolute setters atomically; custom stores may omit it. */
+    consolidate?: (getKey: PendingWriteSupersessionKey<Payload>, options?: PendingWriteConsolidationOptions<Payload>) => Promise<number>;
     claimIfSnapshotId: (id: string, snapshotId: string, record: PendingWriteRecord<Payload>, now: string) => Promise<boolean>;
     clear: (id: string) => Promise<void>;
     clearAll: () => Promise<void>;

package/dist-cjs/pendingWrites.js

@@ -12,6 +12,7 @@ exports.syncPendingWrites = syncPendingWrites;
 exports.runPendingWrite = runPendingWrite;
 exports.summarizePendingWrites = summarizePendingWrites;
 exports.createOrderedPendingWriteExecutor = createOrderedPendingWriteExecutor;
+const pendingWriteConsolidation_1 = require("./pendingWriteConsolidation");
 const idbDriver_1 = require("./idbDriver");
 exports.pendingWriteSchemaVersion = 1;
 exports.pendingWriteOperationTimeoutMs = 2_000;
@@ -55,6 +56,36 @@ function createPendingWriteStore(driver, { keyPrefix, normalizeLegacyRecord, nor
         return records.filter((record) => Boolean(record));
     }
     return {
+        async consolidate(getKey, options) {
+            if (!driver.deleteSelected)
+                return 0;
+            const removedIds = new Map();
+            const deleted = await driver.deleteSelected((entries) => {
+                const scoped = entries.filter(({ key }) => key.startsWith(`${keyPrefix}:`));
+                const records = scoped.map(({ value }) => toPendingWriteEnvelope(value, schemaVersion, {
+                    normalizeLegacyRecord,
+                    normalizePayload,
+                })?.record);
+                // An unreadable envelope may be an ordering barrier from a newer host.
+                // Never infer that skipping it makes its neighbours commute.
+                if (records.some((record) => !record))
+                    return [];
+                const valid = records;
+                const retained = new Set((0, pendingWriteConsolidation_1.projectPendingWriteFinalState)(valid, getKey, options));
+                return scoped
+                    .filter((entry, index) => {
+                    const record = valid[index];
+                    if (retained.has(record))
+                        return false;
+                    removedIds.set(entry.key, record.id);
+                    return true;
+                })
+                    .map((entry) => entry.key);
+            });
+            for (const key of deleted)
+                notify({ id: removedIds.get(key), type: "clear" });
+            return deleted.length;
+        },
         async claimIfSnapshotId(id, snapshotId, record, now) {
             const claimed = await driver.setIf(createPendingWriteKey({ id, prefix: keyPrefix }), { record, schemaVersion }, (value) => {
                 const current = toPendingWriteEnvelope(value, schemaVersion, {
@@ -141,6 +172,13 @@ function createPendingWriteStore(driver, { keyPrefix, normalizeLegacyRecord, nor
 function createMemoryPendingWriteDriver() {
     const records = new Map();
     return {
+        async deleteSelected(select) {
+            // No await between observing winners and deleting obsolete records.
+            const selected = [
+                ...new Set(select([...records].map(([key, value]) => ({ key, value })))),
+            ];
+            return selected.filter((key) => records.delete(key));
+        },
         async clear(key) {
             records.delete(key);
         },
@@ -439,6 +477,7 @@ function createUnavailablePendingWriteDriver() {
 }
 function toPendingWriteDriver(driver) {
     return {
+        deleteSelected: driver.deleteSelected,
         clear: driver.delete,
         clearIf: driver.deleteIf,
         clearAll: driver.clear,

package/package.json

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