@bayonai/offline 0.3.0 → 0.4.0

package/CHANGELOG.md

@@ -1,5 +1,17 @@
 # Changelog
 
+## 0.4.0 - 2026-09-01
+
+- Fixed cross-context replay claiming: a remote sync now runs only after an
+  atomic claim, while interrupted claims become recoverable after a bounded
+  lease timeout.
+- Fixed silent recovery after a non-blocking Web Lock is unavailable. Active
+  online controllers now retry contested leases with bounded backoff.
+- Added `createOrderedPendingWriteExecutor`, a framework-neutral per-scope lane
+  that serializes background replay and live writes so later writes cannot
+  overtake unresolved queued predecessors.
+- Documented the remaining at-least-once delivery contract for remote sinks.
+
 ## 0.3.0 - 2026-08-31
 
 - Added optional `BroadcastChannel` wake-ups and `navigator.locks` replay

package/README.md

@@ -105,7 +105,7 @@ headless controller once for the active account or workspace:
 import {
   createBrowserPendingWriteRecovery,
   createBrowserPendingWriteRecoveryCoordination,
-  runPendingWrite,
+  createOrderedPendingWriteExecutor,
   summarizePendingWrites,
 } from "@bayonai/offline";
 
@@ -115,18 +115,23 @@ const coordination = createBrowserPendingWriteRecoveryCoordination({
   leaseName: `my-app:pending-recovery:${currentUser.id}`,
 });
 
-const recovery = createBrowserPendingWriteRecovery({
-  coordination,
+const writes = createOrderedPendingWriteExecutor({
   scopeKey: currentUser.id,
   select: (record) => record.payload.userId === currentUser.id,
   store,
   sync: (mutation) => replayMutation(mutation),
+});
+
+const recovery = createBrowserPendingWriteRecovery({
+  coordination,
+  recover: writes.recover,
+  store,
   onError: (error) => console.error("Pending replay failed", { error }),
 });
 
 recovery.start(); // silent initial, focus, online, and local-set recovery
 
-const result = await runPendingWrite({
+const result = await writes.run({
   isOnline: () => navigator.onLine,
   write: () => saveRemotely(),
   shouldQueue: isRetryableNetworkError,
@@ -147,8 +152,16 @@ mechanism.
 When coordination is supplied, a queued write wakes peer tabs through
 `BroadcastChannel`, and each recovery attempt acquires a non-blocking
 `navigator.locks` lease when supported. Browsers without either API recover in
-the current tab as before. Remote write handlers must remain idempotent because
-leases do not cover other devices or every browser failure mode.
+the current tab as before. A contested lease retries silently with bounded
+backoff. Remote write handlers must remain idempotent because leases do not
+cover other devices or every browser failure mode.
+
+Use `createOrderedPendingWriteExecutor` when a new write must never overtake a
+previously queued write in the same user, workspace, or other durable scope.
+Its `recover` and `run` methods share one lane: an unresolved predecessor keeps
+the later write queued until the predecessor is delivered. This protects remote
+write order; it does not replace idempotent server-side mutation handling for
+ambiguous request outcomes.
 
 Use generic record summaries when an app needs to render its own status:
 
@@ -157,12 +170,13 @@ const summary = summarizePendingWrites(await store.list());
 // { pendingCount, syncingCount, failedCount, totalCount }
 ```
 
-Each call to `set` assigns a unique `snapshotId`. Sync status updates and
-successful cleanup compare that identity inside a single storage transaction,
-so a newer local write cannot be overwritten or deleted by an older sync.
-Records created before snapshot identities were introduced remain readable;
-they receive a stable compatibility identity and are upgraded when next
-updated.
+Each call to `set` assigns a unique `snapshotId`. A replay first atomically
+claims a fresh snapshot identity before calling the remote sink, then compares
+that identity during status updates and cleanup. This prevents concurrent
+workers or an older sync from overwriting or deleting a newer local write.
+Interrupted sync claims expire after one minute so recovery can resume. Records
+created before snapshot identities were introduced remain readable; they receive
+a stable compatibility identity and are upgraded when next updated.
 
 Host apps that change their pending-write payload shape can normalize current
 records while keeping domain logic outside the package:

package/dist/browserRecovery.d.ts

@@ -17,7 +17,7 @@ export type BrowserPendingWriteRecovery<Payload> = {
     start: () => void;
     stop: () => void;
 };
-export declare function createBrowserPendingWriteRecovery<Payload>({ environment, coordination, initialRetryDelayMs, maxRetryDelayMs, onError, onResult, scopeKey, select, store, sync, }: {
+type BrowserPendingWriteRecoveryOptions<Payload> = {
     /** Optional BroadcastChannel/Web Locks coordination supplied by the package factory. */
     coordination?: BrowserPendingWriteRecoveryCoordination;
     environment?: BrowserPendingWriteRecoveryEnvironment;
@@ -30,5 +30,13 @@ export declare function createBrowserPendingWriteRecovery<Payload>({ environment
     scopeKey?: string;
     select?: (record: PendingWriteRecord<Payload>) => boolean;
     store: PendingWriteStore<Payload>;
+} & ({
+    /** Runs one complete host-owned recovery pass, such as through an ordered executor. */
+    recover: () => Promise<SyncPendingWritesResult>;
+    sync?: never;
+} | {
+    recover?: never;
     sync: PendingWriteSync<Payload>;
-}): BrowserPendingWriteRecovery<Payload>;
+});
+export declare function createBrowserPendingWriteRecovery<Payload>(options: BrowserPendingWriteRecoveryOptions<Payload>): BrowserPendingWriteRecovery<Payload>;
+export {};

package/dist/browserRecovery.js

@@ -1,7 +1,8 @@
 import { syncPendingWrites, } from "./pendingWrites.js";
 export const initialPendingWriteRetryDelayMs = 2_000;
 export const maxPendingWriteRetryDelayMs = 60_000;
-export function createBrowserPendingWriteRecovery({ environment = createDefaultBrowserRecoveryEnvironment(), coordination, initialRetryDelayMs = initialPendingWriteRetryDelayMs, maxRetryDelayMs = maxPendingWriteRetryDelayMs, onError, onResult, scopeKey = "all", select = () => true, store, sync, }) {
+export function createBrowserPendingWriteRecovery(options) {
+    const { environment = createDefaultBrowserRecoveryEnvironment(), coordination, initialRetryDelayMs = initialPendingWriteRetryDelayMs, maxRetryDelayMs = maxPendingWriteRetryDelayMs, onError, onResult, scopeKey = "all", select = () => true, store, } = options;
     let active = false;
     let retryDelayMs = Math.max(0, initialRetryDelayMs);
     let retryTimer;
@@ -60,16 +61,21 @@ export function createBrowserPendingWriteRecovery({ environment = createDefaultB
         }
         const attempt = (async () => {
             try {
-                const run = () => syncPendingWrites({
-                    scopeKey,
-                    select,
-                    store,
-                    sync,
-                });
+                const run = () => options.recover
+                    ? options.recover()
+                    : syncPendingWrites({
+                        scopeKey,
+                        select,
+                        store,
+                        sync: options.sync,
+                    });
                 const result = coordination
                     ? await coordination.runExclusive(run)
                     : await run();
                 if (!result) {
+                    // Another tab currently owns the lease. It may disappear before
+                    // completion, so active recovery must retry rather than go dormant.
+                    scheduleRetry();
                     return null;
                 }
                 emitResult(result);

package/dist/pendingWrites.d.ts

@@ -1,6 +1,7 @@
 import { type BrowserKeyValueDriverOptions } from "./idbDriver";
 export declare const pendingWriteSchemaVersion = 1;
 export declare const pendingWriteOperationTimeoutMs = 2000;
+export declare const pendingWriteSyncLeaseTimeoutMs = 60000;
 export type PendingWriteStatus = "pending" | "syncing" | "failed";
 export type PendingWriteRecord<Payload = unknown> = {
     error?: string;
@@ -8,6 +9,8 @@ export type PendingWriteRecord<Payload = unknown> = {
     payload: Payload;
     savedAt: string;
     snapshotId: string;
+    /** Timestamp of the active remote-sync claim, absent when not owned. */
+    syncingAt?: string;
     syncStatus: PendingWriteStatus;
 };
 export type PendingWriteRecordInput<Payload = unknown> = Omit<PendingWriteRecord<Payload>, "snapshotId"> & {
@@ -39,6 +42,7 @@ export type PendingWriteStoreChange<Payload = unknown> = {
 };
 export type PendingWriteStoreChangeListener<Payload = unknown> = (change: PendingWriteStoreChange<Payload>) => void;
 export type PendingWriteStore<Payload = unknown> = {
+    claimIfSnapshotId: (id: string, snapshotId: string, record: PendingWriteRecord<Payload>, now: string) => Promise<boolean>;
     clear: (id: string) => Promise<void>;
     clearAll: () => Promise<void>;
     clearIfSnapshotId: (id: string, snapshotId: string) => Promise<boolean>;
@@ -95,6 +99,23 @@ export type RunPendingWriteResult<TResult, TQueued> = {
     queued: TQueued;
     status: "queued";
 };
+export type PendingWriteRunOptions<TResult, TQueued> = {
+    enqueue: () => Promise<TQueued>;
+    isOnline: () => boolean;
+    shouldQueue: (error: unknown) => boolean;
+    write: () => Promise<TResult>;
+};
+/**
+ * Serializes recovery and new writes for one caller-defined scope.
+ *
+ * A queued write that cannot be replayed stays ahead of later writes. This
+ * preserves remote write order; callers retain ownership of scope selection
+ * and idempotent remote mutation semantics.
+ */
+export type OrderedPendingWriteExecutor<Payload> = {
+    recover: () => Promise<SyncPendingWritesResult>;
+    run: <TResult, TQueued>(options: PendingWriteRunOptions<TResult, TQueued>) => Promise<RunPendingWriteResult<TResult, TQueued>>;
+};
 export type PendingWriteSummary = {
     failedCount: number;
     pendingCount: number;
@@ -107,8 +128,9 @@ export declare function createBrowserPendingWriteDriver({ databaseName, database
 export declare function createBrowserPendingWriteStore<Payload = unknown>({ databaseName, databaseVersion, indexedDB, keyPrefix, normalizeLegacyRecord, normalizePayload, operationTimeoutMs, schemaVersion, storeName, }: BrowserPendingWriteStoreOptions<Payload>): PendingWriteStore<Payload>;
 export declare function createPendingWriteKey({ id, prefix }: PendingWriteKeyOptions): string;
 export declare function createPendingWriteSnapshotId(): `${string}-${string}-${string}-${string}-${string}`;
-export declare function syncPendingWrite<Payload>({ id, store, sync, }: {
+export declare function syncPendingWrite<Payload>({ id, now, store, sync, }: {
     id: string;
+    now?: () => string;
     store: PendingWriteStore<Payload>;
     sync: PendingWriteSync<Payload>;
 }): Promise<SyncPendingWriteResult>;
@@ -117,9 +139,11 @@ export declare function syncPendingWrite<Payload>({ id, store, sync, }: {
  * same store/scope. Callers own the selection predicate and idempotent remote
  * mutation semantics.
  */
-export declare function syncPendingWrites<Payload>({ scopeKey, select, store, sync, }: {
+export declare function syncPendingWrites<Payload>({ scopeKey, select, stopOnFailure, store, sync, }: {
     scopeKey?: string;
     select?: (record: PendingWriteRecord<Payload>) => boolean;
+    /** Preserve caller ordering by leaving later records for a future retry. */
+    stopOnFailure?: boolean;
     store: PendingWriteStore<Payload>;
     sync: PendingWriteSync<Payload>;
 }): Promise<SyncPendingWritesResult>;
@@ -127,10 +151,16 @@ export declare function syncPendingWrites<Payload>({ scopeKey, select, store, sy
  * Attempts a remote write now and persists a caller-created durable fallback
  * only when offline or when the supplied retry classifier accepts the error.
  */
-export declare function runPendingWrite<TResult, TQueued>({ enqueue, isOnline, shouldQueue, write, }: {
-    enqueue: () => Promise<TQueued>;
-    isOnline: () => boolean;
-    shouldQueue: (error: unknown) => boolean;
-    write: () => Promise<TResult>;
-}): Promise<RunPendingWriteResult<TResult, TQueued>>;
+export declare function runPendingWrite<TResult, TQueued>({ enqueue, isOnline, shouldQueue, write, }: PendingWriteRunOptions<TResult, TQueued>): Promise<RunPendingWriteResult<TResult, TQueued>>;
 export declare function summarizePendingWrites<Payload>(records: Array<PendingWriteRecord<Payload>>): PendingWriteSummary;
+/**
+ * Creates a serial execution lane for a durable scope such as one user or
+ * workspace. Use its `recover` method for background replay and `run` for new
+ * writes so a newer remote mutation cannot overtake an older queued mutation.
+ */
+export declare function createOrderedPendingWriteExecutor<Payload>({ scopeKey, select, store, sync, }: {
+    scopeKey?: string;
+    select?: (record: PendingWriteRecord<Payload>) => boolean;
+    store: PendingWriteStore<Payload>;
+    sync: PendingWriteSync<Payload>;
+}): OrderedPendingWriteExecutor<Payload>;

package/dist/pendingWrites.js

@@ -1,6 +1,7 @@
 import { createIdbKeyValueDriver, } from "./idbDriver.js";
 export const pendingWriteSchemaVersion = 1;
 export const pendingWriteOperationTimeoutMs = 2_000;
+export const pendingWriteSyncLeaseTimeoutMs = 60_000;
 export function createPendingWriteStore(driver, { keyPrefix, normalizeLegacyRecord, normalizePayload, schemaVersion = pendingWriteSchemaVersion, }) {
     const listeners = new Set();
     const notify = (change) => {
@@ -17,6 +18,20 @@ export function createPendingWriteStore(driver, { keyPrefix, normalizeLegacyReco
         }
     };
     return {
+        async claimIfSnapshotId(id, snapshotId, record, now) {
+            const claimed = await driver.setIf(createPendingWriteKey({ id, prefix: keyPrefix }), { record, schemaVersion }, (value) => {
+                const current = toPendingWriteEnvelope(value, schemaVersion, {
+                    normalizeLegacyRecord,
+                    normalizePayload,
+                })?.record;
+                return (current?.snapshotId === snapshotId &&
+                    isPendingWriteSyncClaimAvailable(current, now));
+            });
+            if (claimed) {
+                notify({ record, type: "replace" });
+            }
+            return claimed;
+        },
         async clear(id) {
             await driver.clear(createPendingWriteKey({ id, prefix: keyPrefix }));
             notify({ id, type: "clear" });
@@ -141,31 +156,44 @@ export function createPendingWriteKey({ id, prefix }) {
 export function createPendingWriteSnapshotId() {
     return globalThis.crypto.randomUUID();
 }
-export async function syncPendingWrite({ id, store, sync, }) {
+export async function syncPendingWrite({ id, now = () => new Date().toISOString(), store, sync, }) {
     const pending = await store.get(id);
     if (!pending) {
         return { status: "idle" };
     }
-    await markPendingSnapshot({
-        id,
-        nextRecord: { ...pending, error: undefined, syncStatus: "syncing" },
-        snapshotId: pending.snapshotId,
-        store,
-    });
+    const claimedSnapshotId = createPendingWriteSnapshotId();
+    const claimed = await store.claimIfSnapshotId(id, pending.snapshotId, {
+        ...pending,
+        error: undefined,
+        snapshotId: claimedSnapshotId,
+        syncingAt: now(),
+        syncStatus: "syncing",
+    }, now());
+    if (!claimed) {
+        return { status: "superseded" };
+    }
     try {
         await sync(pending.payload);
     }
     catch (error) {
         const message = error instanceof Error ? error.message : "Unable to sync pending write.";
-        await markPendingSnapshot({
+        const { syncingAt: _syncingAt, ...pendingWithoutSyncClaim } = pending;
+        const markedFailed = await markPendingSnapshot({
             id,
-            nextRecord: { ...pending, error: message, syncStatus: "failed" },
-            snapshotId: pending.snapshotId,
+            nextRecord: {
+                ...pendingWithoutSyncClaim,
+                error: message,
+                snapshotId: claimedSnapshotId,
+                syncStatus: "failed",
+            },
+            snapshotId: claimedSnapshotId,
             store,
         });
-        return { error: message, status: "failed" };
+        return markedFailed
+            ? { error: message, status: "failed" }
+            : { status: "superseded" };
     }
-    return (await store.clearIfSnapshotId(id, pending.snapshotId))
+    return (await store.clearIfSnapshotId(id, claimedSnapshotId))
         ? { status: "synced" }
         : { status: "superseded" };
 }
@@ -174,7 +202,7 @@ export async function syncPendingWrite({ id, store, sync, }) {
  * same store/scope. Callers own the selection predicate and idempotent remote
  * mutation semantics.
  */
-export function syncPendingWrites({ scopeKey = "all", select = () => true, store, sync, }) {
+export function syncPendingWrites({ scopeKey = "all", select = () => true, stopOnFailure = false, store, sync, }) {
     let inFlightByScope = pendingWriteSyncs.get(store);
     if (!inFlightByScope) {
         inFlightByScope = new Map();
@@ -184,7 +212,12 @@ export function syncPendingWrites({ scopeKey = "all", select = () => true, store
     if (existing) {
         return existing;
     }
-    const syncRun = performPendingWriteSync({ select, store, sync });
+    const syncRun = performPendingWriteSync({
+        select,
+        stopOnFailure,
+        store,
+        sync,
+    });
     inFlightByScope.set(scopeKey, syncRun);
     const clearInFlight = () => {
         inFlightByScope.delete(scopeKey);
@@ -226,7 +259,7 @@ export function summarizePendingWrites(records) {
     }, { failedCount: 0, pendingCount: 0, syncingCount: 0, totalCount: 0 });
 }
 const pendingWriteSyncs = new WeakMap();
-async function performPendingWriteSync({ select, store, sync, }) {
+async function performPendingWriteSync({ select, stopOnFailure, store, sync, }) {
     const summary = {
         attempted: 0,
         failed: 0,
@@ -244,10 +277,72 @@ async function performPendingWriteSync({ select, store, sync, }) {
         });
         summary.attempted += 1;
         summary[result.status] += 1;
+        if (stopOnFailure && result.status === "failed") {
+            break;
+        }
     }
     summary.remaining = (await store.list()).filter(select).length;
     return summary;
 }
+function isPendingWriteSyncClaimAvailable(record, now) {
+    if (record.syncStatus !== "syncing") {
+        return true;
+    }
+    if (!record.syncingAt) {
+        return true;
+    }
+    const startedAt = Date.parse(record.syncingAt);
+    const currentTime = Date.parse(now);
+    return (!Number.isFinite(startedAt) ||
+        !Number.isFinite(currentTime) ||
+        currentTime - startedAt >= pendingWriteSyncLeaseTimeoutMs);
+}
+/**
+ * Creates a serial execution lane for a durable scope such as one user or
+ * workspace. Use its `recover` method for background replay and `run` for new
+ * writes so a newer remote mutation cannot overtake an older queued mutation.
+ */
+export function createOrderedPendingWriteExecutor({ scopeKey = "all", select = () => true, store, sync, }) {
+    let execution = Promise.resolve();
+    function inOrder(operation) {
+        const result = execution.then(operation, operation);
+        execution = result.then(() => undefined, () => undefined);
+        return result;
+    }
+    function recover() {
+        return inOrder(() => syncPendingWrites({
+            scopeKey,
+            select,
+            stopOnFailure: true,
+            store,
+            sync,
+        }));
+    }
+    return {
+        recover,
+        run(options) {
+            return inOrder(async () => {
+                if (!options.isOnline()) {
+                    return runPendingWrite(options);
+                }
+                const replay = await syncPendingWrites({
+                    scopeKey,
+                    select,
+                    stopOnFailure: true,
+                    store,
+                    sync,
+                });
+                // Product decision: unresolved older records retain their position in
+                // this scope. Queue the later write rather than letting it overtake a
+                // replay whose remote effect may be ambiguous.
+                if (replay.remaining > 0) {
+                    return { queued: await options.enqueue(), status: "queued" };
+                }
+                return runPendingWrite(options);
+            });
+        },
+    };
+}
 function createNoopPendingWriteDriver() {
     return {
         async clear() { },
@@ -307,6 +402,9 @@ function normalizePendingWriteRecord(record, normalizePayload) {
         payload,
         savedAt: record.savedAt,
         snapshotId: record.snapshotId ?? createLegacyPendingWriteSnapshotId(record),
+        ...(typeof record.syncingAt === "string"
+            ? { syncingAt: record.syncingAt }
+            : {}),
         syncStatus: record.syncStatus,
     };
 }
@@ -332,6 +430,7 @@ function isPendingWriteRecord(value) {
         "savedAt" in value &&
         typeof value.savedAt === "string" &&
         (!("snapshotId" in value) || typeof value.snapshotId === "string") &&
+        (!("syncingAt" in value) || typeof value.syncingAt === "string") &&
         "syncStatus" in value &&
         (value.syncStatus === "pending" ||
             value.syncStatus === "syncing" ||

package/dist-cjs/browserRecovery.js

@@ -5,7 +5,8 @@ exports.createBrowserPendingWriteRecovery = createBrowserPendingWriteRecovery;
 const pendingWrites_1 = require("./pendingWrites");
 exports.initialPendingWriteRetryDelayMs = 2_000;
 exports.maxPendingWriteRetryDelayMs = 60_000;
-function createBrowserPendingWriteRecovery({ environment = createDefaultBrowserRecoveryEnvironment(), coordination, initialRetryDelayMs = exports.initialPendingWriteRetryDelayMs, maxRetryDelayMs = exports.maxPendingWriteRetryDelayMs, onError, onResult, scopeKey = "all", select = () => true, store, sync, }) {
+function createBrowserPendingWriteRecovery(options) {
+    const { environment = createDefaultBrowserRecoveryEnvironment(), coordination, initialRetryDelayMs = exports.initialPendingWriteRetryDelayMs, maxRetryDelayMs = exports.maxPendingWriteRetryDelayMs, onError, onResult, scopeKey = "all", select = () => true, store, } = options;
     let active = false;
     let retryDelayMs = Math.max(0, initialRetryDelayMs);
     let retryTimer;
@@ -64,16 +65,21 @@ function createBrowserPendingWriteRecovery({ environment = createDefaultBrowserR
         }
         const attempt = (async () => {
             try {
-                const run = () => (0, pendingWrites_1.syncPendingWrites)({
-                    scopeKey,
-                    select,
-                    store,
-                    sync,
-                });
+                const run = () => options.recover
+                    ? options.recover()
+                    : (0, pendingWrites_1.syncPendingWrites)({
+                        scopeKey,
+                        select,
+                        store,
+                        sync: options.sync,
+                    });
                 const result = coordination
                     ? await coordination.runExclusive(run)
                     : await run();
                 if (!result) {
+                    // Another tab currently owns the lease. It may disappear before
+                    // completion, so active recovery must retry rather than go dormant.
+                    scheduleRetry();
                     return null;
                 }
                 emitResult(result);

package/dist-cjs/pendingWrites.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.pendingWriteOperationTimeoutMs = exports.pendingWriteSchemaVersion = void 0;
+exports.pendingWriteSyncLeaseTimeoutMs = exports.pendingWriteOperationTimeoutMs = exports.pendingWriteSchemaVersion = void 0;
 exports.createPendingWriteStore = createPendingWriteStore;
 exports.createMemoryPendingWriteDriver = createMemoryPendingWriteDriver;
 exports.createBrowserPendingWriteDriver = createBrowserPendingWriteDriver;
@@ -11,9 +11,11 @@ exports.syncPendingWrite = syncPendingWrite;
 exports.syncPendingWrites = syncPendingWrites;
 exports.runPendingWrite = runPendingWrite;
 exports.summarizePendingWrites = summarizePendingWrites;
+exports.createOrderedPendingWriteExecutor = createOrderedPendingWriteExecutor;
 const idbDriver_1 = require("./idbDriver");
 exports.pendingWriteSchemaVersion = 1;
 exports.pendingWriteOperationTimeoutMs = 2_000;
+exports.pendingWriteSyncLeaseTimeoutMs = 60_000;
 function createPendingWriteStore(driver, { keyPrefix, normalizeLegacyRecord, normalizePayload, schemaVersion = exports.pendingWriteSchemaVersion, }) {
     const listeners = new Set();
     const notify = (change) => {
@@ -30,6 +32,20 @@ function createPendingWriteStore(driver, { keyPrefix, normalizeLegacyRecord, nor
         }
     };
     return {
+        async claimIfSnapshotId(id, snapshotId, record, now) {
+            const claimed = await driver.setIf(createPendingWriteKey({ id, prefix: keyPrefix }), { record, schemaVersion }, (value) => {
+                const current = toPendingWriteEnvelope(value, schemaVersion, {
+                    normalizeLegacyRecord,
+                    normalizePayload,
+                })?.record;
+                return (current?.snapshotId === snapshotId &&
+                    isPendingWriteSyncClaimAvailable(current, now));
+            });
+            if (claimed) {
+                notify({ record, type: "replace" });
+            }
+            return claimed;
+        },
         async clear(id) {
             await driver.clear(createPendingWriteKey({ id, prefix: keyPrefix }));
             notify({ id, type: "clear" });
@@ -154,31 +170,44 @@ function createPendingWriteKey({ id, prefix }) {
 function createPendingWriteSnapshotId() {
     return globalThis.crypto.randomUUID();
 }
-async function syncPendingWrite({ id, store, sync, }) {
+async function syncPendingWrite({ id, now = () => new Date().toISOString(), store, sync, }) {
     const pending = await store.get(id);
     if (!pending) {
         return { status: "idle" };
     }
-    await markPendingSnapshot({
-        id,
-        nextRecord: { ...pending, error: undefined, syncStatus: "syncing" },
-        snapshotId: pending.snapshotId,
-        store,
-    });
+    const claimedSnapshotId = createPendingWriteSnapshotId();
+    const claimed = await store.claimIfSnapshotId(id, pending.snapshotId, {
+        ...pending,
+        error: undefined,
+        snapshotId: claimedSnapshotId,
+        syncingAt: now(),
+        syncStatus: "syncing",
+    }, now());
+    if (!claimed) {
+        return { status: "superseded" };
+    }
     try {
         await sync(pending.payload);
     }
     catch (error) {
         const message = error instanceof Error ? error.message : "Unable to sync pending write.";
-        await markPendingSnapshot({
+        const { syncingAt: _syncingAt, ...pendingWithoutSyncClaim } = pending;
+        const markedFailed = await markPendingSnapshot({
             id,
-            nextRecord: { ...pending, error: message, syncStatus: "failed" },
-            snapshotId: pending.snapshotId,
+            nextRecord: {
+                ...pendingWithoutSyncClaim,
+                error: message,
+                snapshotId: claimedSnapshotId,
+                syncStatus: "failed",
+            },
+            snapshotId: claimedSnapshotId,
             store,
         });
-        return { error: message, status: "failed" };
+        return markedFailed
+            ? { error: message, status: "failed" }
+            : { status: "superseded" };
     }
-    return (await store.clearIfSnapshotId(id, pending.snapshotId))
+    return (await store.clearIfSnapshotId(id, claimedSnapshotId))
         ? { status: "synced" }
         : { status: "superseded" };
 }
@@ -187,7 +216,7 @@ async function syncPendingWrite({ id, store, sync, }) {
  * same store/scope. Callers own the selection predicate and idempotent remote
  * mutation semantics.
  */
-function syncPendingWrites({ scopeKey = "all", select = () => true, store, sync, }) {
+function syncPendingWrites({ scopeKey = "all", select = () => true, stopOnFailure = false, store, sync, }) {
     let inFlightByScope = pendingWriteSyncs.get(store);
     if (!inFlightByScope) {
         inFlightByScope = new Map();
@@ -197,7 +226,12 @@ function syncPendingWrites({ scopeKey = "all", select = () => true, store, sync,
     if (existing) {
         return existing;
     }
-    const syncRun = performPendingWriteSync({ select, store, sync });
+    const syncRun = performPendingWriteSync({
+        select,
+        stopOnFailure,
+        store,
+        sync,
+    });
     inFlightByScope.set(scopeKey, syncRun);
     const clearInFlight = () => {
         inFlightByScope.delete(scopeKey);
@@ -239,7 +273,7 @@ function summarizePendingWrites(records) {
     }, { failedCount: 0, pendingCount: 0, syncingCount: 0, totalCount: 0 });
 }
 const pendingWriteSyncs = new WeakMap();
-async function performPendingWriteSync({ select, store, sync, }) {
+async function performPendingWriteSync({ select, stopOnFailure, store, sync, }) {
     const summary = {
         attempted: 0,
         failed: 0,
@@ -257,10 +291,72 @@ async function performPendingWriteSync({ select, store, sync, }) {
         });
         summary.attempted += 1;
         summary[result.status] += 1;
+        if (stopOnFailure && result.status === "failed") {
+            break;
+        }
     }
     summary.remaining = (await store.list()).filter(select).length;
     return summary;
 }
+function isPendingWriteSyncClaimAvailable(record, now) {
+    if (record.syncStatus !== "syncing") {
+        return true;
+    }
+    if (!record.syncingAt) {
+        return true;
+    }
+    const startedAt = Date.parse(record.syncingAt);
+    const currentTime = Date.parse(now);
+    return (!Number.isFinite(startedAt) ||
+        !Number.isFinite(currentTime) ||
+        currentTime - startedAt >= exports.pendingWriteSyncLeaseTimeoutMs);
+}
+/**
+ * Creates a serial execution lane for a durable scope such as one user or
+ * workspace. Use its `recover` method for background replay and `run` for new
+ * writes so a newer remote mutation cannot overtake an older queued mutation.
+ */
+function createOrderedPendingWriteExecutor({ scopeKey = "all", select = () => true, store, sync, }) {
+    let execution = Promise.resolve();
+    function inOrder(operation) {
+        const result = execution.then(operation, operation);
+        execution = result.then(() => undefined, () => undefined);
+        return result;
+    }
+    function recover() {
+        return inOrder(() => syncPendingWrites({
+            scopeKey,
+            select,
+            stopOnFailure: true,
+            store,
+            sync,
+        }));
+    }
+    return {
+        recover,
+        run(options) {
+            return inOrder(async () => {
+                if (!options.isOnline()) {
+                    return runPendingWrite(options);
+                }
+                const replay = await syncPendingWrites({
+                    scopeKey,
+                    select,
+                    stopOnFailure: true,
+                    store,
+                    sync,
+                });
+                // Product decision: unresolved older records retain their position in
+                // this scope. Queue the later write rather than letting it overtake a
+                // replay whose remote effect may be ambiguous.
+                if (replay.remaining > 0) {
+                    return { queued: await options.enqueue(), status: "queued" };
+                }
+                return runPendingWrite(options);
+            });
+        },
+    };
+}
 function createNoopPendingWriteDriver() {
     return {
         async clear() { },
@@ -320,6 +416,9 @@ function normalizePendingWriteRecord(record, normalizePayload) {
         payload,
         savedAt: record.savedAt,
         snapshotId: record.snapshotId ?? createLegacyPendingWriteSnapshotId(record),
+        ...(typeof record.syncingAt === "string"
+            ? { syncingAt: record.syncingAt }
+            : {}),
         syncStatus: record.syncStatus,
     };
 }
@@ -345,6 +444,7 @@ function isPendingWriteRecord(value) {
         "savedAt" in value &&
         typeof value.savedAt === "string" &&
         (!("snapshotId" in value) || typeof value.snapshotId === "string") &&
+        (!("syncingAt" in value) || typeof value.syncingAt === "string") &&
         "syncStatus" in value &&
         (value.syncStatus === "pending" ||
             value.syncStatus === "syncing" ||

package/package.json

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