@abloatai/ablo 0.26.0 → 0.28.0

package/dist/transactions/TransactionQueue.js

@@ -1,25 +1,35 @@
 /**
- * TransactionQueue - Production-ready transaction management
+ * TransactionQueue manages the lifecycle of local writes on their way to the
+ * server: it applies each change optimistically, batches the writes made in one
+ * event-loop tick into a single commit, retries transient failures, and rolls
+ * back on permanent rejection.
  *
- * Key features:
- * - Optimistic updates with rollback
- * - Conflict resolution strategies
- * - LINEAR-style microtask batching (transactions in same event loop share batchId)
- * - Proper dependency injection (no singleton)
+ * Key behaviours:
+ * - Optimistic updates with rollback on failure.
+ * - Configurable conflict resolution.
+ * - Microtask batching: transactions created in the same event-loop tick share
+ *   a batch id and commit together in one round trip.
+ * - A dependency-injected executor, so several queues can coexist.
  */
 import { EventEmitter } from 'events';
+import { v4 as uuid } from 'uuid';
 import { Model } from '../Model.js';
 import { getContext } from '../context.js';
-import { handleMutationError } from './mutation-error-handler.js';
-import { AbloError, AbloConnectionError, errorCodeSpec } from '../errors.js';
+import { AbloError, AbloConnectionError, AbloIdempotencyError, AbloValidationError, errorCodeSpec, } from '../errors.js';
 import { SyncPosition } from '../sync/syncPosition.js';
-import { projectCommitPayload, computePriorityScore, normalizeModelKey, stripModelSuffix, hasStaleWriteOptions, applyWriteOptions, asTransportError, extractStatusCode, TX_TYPE_TO_MUTATION_OP, } from './commitPayload.js';
+import { projectCommitPayload, computePriorityScore, normalizeModelKey, 
+// Includes stale guards as well as request identity/audit barriers.
+hasCommitCoalescingBarrier, applyWriteOptions, asTransportError, extractStatusCode, TX_TYPE_TO_MUTATION_OP, } from './commitPayload.js';
 import { TransactionStore } from './TransactionStore.js';
 import { entityKey, mergeUpdateData, takeUnsentCreateForModel, findCreateBarrierForDelete, deferDeleteUntilCreateSettles, releaseDeferredDeletesForCreate, } from './coalesceRules.js';
 import { DeltaConfirmationTracker } from './deltaConfirmation.js';
-import { deserializePersistedTransaction, isNonReplayablePersistedRow, } from './persistedReplay.js';
-import { applyOptimisticCreate, applyOptimisticUpdate, applyOptimisticDelete, rollbackOptimistic, } from './optimistic.js';
+import { deserializePersistedTransaction, isNonReplayablePersistedRow, pendingMutationRecordId, } from './replayValidation.js';
+import { createCommitEnvelopeMember, createDurableCommitEnvelope, commitEnvelopeRecordId, durableCommitEnvelopeSchema, } from './commitEnvelope.js';
+import { stableStringify } from '../utils/json.js';
+import { applyOptimisticCreate, applyOptimisticUpdate, applyOptimisticDelete, rollbackOptimistic, } from './optimisticApply.js';
 export class TransactionQueue extends EventEmitter {
+    // Keep one hour of clock/network margin inside the server's 24-hour ledger.
+    static DURABLE_REPLAY_WINDOW_MS = 23 * 60 * 60 * 1000;
     store = new TransactionStore();
     // Signature of the last permanent-error we logged at `warn`. A `create`
     // whose id already exists (`unique_violation`) is a permanent rejection
@@ -27,17 +37,17 @@ export class TransactionQueue extends EventEmitter {
     // this, the identical cause prints on a loop. We log the first occurrence
     // and demote exact repeats to `debug`.
     lastPermanentErrorSig;
-    // Per-instance executor binding. Set by `setMutationExecutor(...)` from the
-    // owning Ablo right after construction. Falls back to `getContext()` only
-    // when unset (preserves legacy tests / SDK consumers that haven't migrated).
+    // The executor bound to this queue instance, set by `setMutationExecutor(...)`
+    // just after construction. When unset it falls back to the ambient executor
+    // from `getContext()`.
     //
-    // Why this exists: `initSyncEngine()` writes a *module-level* singleton.
-    // Constructing a second Ablo (e.g. worker + per-job peer in agent-worker)
-    // overwrites the first instance's executor. Without an instance binding,
-    // queue commits on Ablo A would dispatch through Ablo B's executor closure,
-    // which captures B's `storeHolder.store` — and once B disposes its store,
-    // that closure returns `null` for `getWs()` and every commit on A throws
-    // `ws_not_ready` forever (queue classifies it as transient → retry loop).
+    // The binding matters because the ambient executor is a module-level
+    // singleton: constructing a second client instance overwrites the first
+    // instance's executor. Without a per-instance binding, commits on one
+    // instance would dispatch through another instance's executor closure; once
+    // that other instance disposed its store, the closure would resolve no live
+    // connection and every commit here would fail with `ws_not_ready`, which the
+    // queue treats as transient and retries endlessly.
     _mutationExecutor = null;
     get mutationExecutor() {
         return this._mutationExecutor ?? getContext().mutationExecutor;
@@ -46,8 +56,8 @@ export class TransactionQueue extends EventEmitter {
     isProcessing = false;
     processTimer;
     processScheduled = false;
-    // LINEAR PATTERN: Staging area for transactions created in same event loop tick
-    // All transactions go here first, then get committed together via microtask
+    // Staging area for transactions created in the same event-loop tick. Each one
+    // lands here first, then a microtask commits them together.
     createdTransactions = [];
     commitScheduled = false;
     // Per-model in-flight tracking and merge buffer
@@ -60,6 +70,39 @@ export class TransactionQueue extends EventEmitter {
     commitLane = [];
     commitStore = new Map();
     commitProcessing = false;
+    lastCommitSequence = 0;
+    durableReplayBlock = null;
+    /** Browser-backed strict outbox; absent for standalone/in-memory consumers. */
+    commitOutbox = null;
+    commitOutboxScope = null;
+    nextCommitSequence() {
+        const wallSequence = Date.now() * 1_000;
+        this.lastCommitSequence = Math.max(wallSequence, this.lastCommitSequence + 1);
+        return this.lastCommitSequence;
+    }
+    emitCommitLifecycle(event, payload) {
+        try {
+            this.emit(event, payload);
+        }
+        catch (error) {
+            getContext().observability.captureTransactionFailure({
+                context: `commit-lifecycle-listener:${event}`,
+                error: error instanceof Error ? error : String(error),
+            });
+        }
+    }
+    assertDurableReplayOpen() {
+        if (this.durableReplayBlock)
+            throw this.durableReplayBlock;
+    }
+    assertEnvelopeInsideReplayWindow(envelope) {
+        this.assertDurableReplayOpen();
+        if (Date.now() - envelope.sealedAt >=
+            TransactionQueue.DURABLE_REPLAY_WINDOW_MS) {
+            this.durableReplayBlock = new AbloIdempotencyError('A pending commit is older than the server idempotency window; newer writes are blocked until it is reviewed.', { code: 'idempotency_conflict' });
+            throw this.durableReplayBlock;
+        }
+    }
     computePriorityScore(type, modelName) {
         return computePriorityScore(type, modelName);
     }
@@ -94,7 +137,7 @@ export class TransactionQueue extends EventEmitter {
     findCreateBarrierForDelete(modelName, modelId) {
         return findCreateBarrierForDelete(this.store, modelName, modelId);
     }
-    completeLocalDelete(model, context, writeOptions) {
+    completeLocalDelete(model, context, writeOptions, sourceMutationIds = []) {
         const actualModelName = model.getModelName();
         const modelKey = normalizeModelKey(actualModelName);
         const transaction = {
@@ -111,6 +154,9 @@ export class TransactionQueue extends EventEmitter {
             attempts: 0,
             priority: 'high',
             writeOptions,
+            ...(sourceMutationIds.length > 0
+                ? { sourceMutationIds: [...new Set(sourceMutationIds)] }
+                : {}),
             localOnly: true,
         };
         this.attachConfirmation(transaction);
@@ -130,11 +176,12 @@ export class TransactionQueue extends EventEmitter {
     releaseDeferredDeletesForCreate(createTransaction) {
         releaseDeferredDeletesForCreate(this.deferredDeletesByCreate, this.store, (tx) => { this.enqueue(tx); }, createTransaction);
     }
-    // Configuration - tuned for LINEAR-style batching
-    // Higher batch size and delay allows more operations to coalesce into single HTTP call
+    // Default configuration, tuned so more operations coalesce into a single
+    // commit: a larger batch size and delay give rapid operations more time to
+    // merge before the batch is sent.
     config = {
-        maxBatchSize: 50, // Increased from 10 - matches Linear's batch size
-        batchDelay: 150, // Increased from 50ms - more time to coalesce rapid operations
+        maxBatchSize: 50, // send up to this many operations per commit
+        batchDelay: 150, // milliseconds to wait for more operations before sending
         maxRetries: 3,
         conflictResolution: {
             strategy: 'last-write-wins',
@@ -151,19 +198,21 @@ export class TransactionQueue extends EventEmitter {
     };
     // Track executing transactions for backpressure
     executingCount = 0;
-    // Optimistic update tracking. The entry shape + apply/rollback rules live
-    // in `./optimistic.js`; the ledger itself stays host state because the
+    // Optimistic update tracking. The entry shape and apply/rollback rules live
+    // in `./optimisticApply.js`; the map itself stays on the queue because the
     // completion paths, `getStats`, and `dispose` all read it.
     optimisticUpdates = new Map();
-    // Stale-context notifications (CoAgent/MTPO notify-instead-of-abort) keyed by
-    // transaction id, populated from the commit ack and drained by
-    // `waitForCommitReceipt` so the receipt carries the self-heal signal.
+    // Stale-context notifications, keyed by transaction id. When the server
+    // accepts a commit but reports that an operation's read premise had moved,
+    // the notification lands here from the commit acknowledgement and is drained
+    // by `waitForCommitReceipt`, so the receipt can carry it back to the caller.
     commitNotifications = new Map();
     // Delta-confirmation tracking (ack watermark advance + the awaiting_delta
     // timeout/retry maps) lives in `./deltaConfirmation.js`. Constructed in the
     // constructor once `position` is bound.
     deltaConfirmation;
-    // Connection state check - set by SyncClient to prevent rollbacks during disconnection
+    // Connection-state check, supplied by the client, used to hold off rollbacks
+    // while disconnected.
     isConnectedFn = () => true;
     // Grace timer that, when fired, fails any commit-lane transaction
     // still awaiting an ack. Started on `setConnectionState('disconnected')`,
@@ -171,11 +220,11 @@ export class TransactionQueue extends EventEmitter {
     // is preserved for brief blips; this only catches persistent disconnects.
     commitOfflineGraceTimer = null;
     /**
-     * THE client's place in the global delta order — the SHARED instance
-     * (injected by SyncClient; standalone construction gets its own). The
-     * queue advances `acked` on commit responses; the store advances
-     * `applied`/`persisted`; snapshots/claims read `readFloor`. Contract +
-     * rationale live in `sync/syncPosition.ts`.
+     * This client's place in the global order of sync deltas. The instance is
+     * shared: the client injects one, and a standalone queue creates its own. The
+     * queue advances the `acked` cursor as commit responses arrive, the store
+     * advances `applied` and `persisted`, and snapshots and claims read
+     * `readFloor`. See `../sync/syncPosition.js` for the full contract.
      */
     position;
     /** Applied-cursor alias, kept so the many internal read sites stay legible. */
@@ -187,6 +236,207 @@ export class TransactionQueue extends EventEmitter {
     }
     // Batch management
     batchIndex = 0;
+    /** Mints the request identity once; retry paths only read the stored value. */
+    generateCommitIdempotencyKey() {
+        return `commit_${uuid()}`;
+    }
+    /**
+     * Binds an ordered transaction batch to one wire-level idempotency key.
+     * Existing envelopes are validated and restored to their original order;
+     * they are never extended with newly queued work.
+     */
+    ensureCommitEnvelope(batch) {
+        const firstTransaction = batch[0];
+        if (!firstTransaction) {
+            throw new Error('Cannot create an idempotency envelope for an empty commit');
+        }
+        const existingKeys = new Set(batch
+            .map((tx) => tx.commitEnvelope?.idempotencyKey)
+            .filter((key) => key !== undefined));
+        if (existingKeys.size > 1) {
+            throw new Error('Cannot combine transactions from different commit envelopes');
+        }
+        const existingKey = existingKeys.values().next().value;
+        if (existingKey) {
+            const expectedCount = firstTransaction.commitEnvelope?.operationCount;
+            const indexes = new Set(batch.map((tx) => tx.commitEnvelope?.operationIndex));
+            const isCompleteEnvelope = expectedCount === batch.length &&
+                indexes.size === batch.length &&
+                batch.every((tx) => tx.commitEnvelope?.idempotencyKey === existingKey &&
+                    tx.commitEnvelope.operationCount === expectedCount &&
+                    tx.commitEnvelope.operationIndex < expectedCount);
+            if (!isCompleteEnvelope) {
+                throw new Error('Cannot replay a partial or malformed commit envelope');
+            }
+            const persistedSealTimes = new Set(batch
+                .map((transaction) => transaction.commitEnvelope?.sealedAt)
+                .filter((sealedAt) => sealedAt !== undefined));
+            if (persistedSealTimes.size > 1) {
+                throw new Error('Cannot replay a commit envelope with inconsistent seal times');
+            }
+            const sealedAt = persistedSealTimes.values().next().value ?? Date.now();
+            for (const transaction of batch) {
+                if (transaction.commitEnvelope)
+                    transaction.commitEnvelope.sealedAt = sealedAt;
+            }
+            batch.sort((a, b) => (a.commitEnvelope?.operationIndex ?? 0) -
+                (b.commitEnvelope?.operationIndex ?? 0));
+            return existingKey;
+        }
+        // An explicit public key owns its request. Transactions carrying one are
+        // selected as solo batches by takeNextExecutionBatch().
+        const explicitKey = batch.length === 1
+            ? firstTransaction.writeOptions?.idempotencyKey
+            : undefined;
+        const idempotencyKey = typeof explicitKey === 'string' && explicitKey.length > 0
+            ? explicitKey
+            : this.generateCommitIdempotencyKey();
+        const sealedAt = Date.now();
+        const sequence = this.nextCommitSequence();
+        batch.forEach((tx, operationIndex) => {
+            tx.commitEnvelope = createCommitEnvelopeMember({
+                idempotencyKey,
+                operationIndex,
+                operationCount: batch.length,
+                sealedAt,
+                sequence,
+            });
+        });
+        return idempotencyKey;
+    }
+    /** Bind the strict local outbox used before any mutation reaches the wire. */
+    setCommitOutbox(outbox) {
+        this.commitOutbox = outbox;
+    }
+    setCommitOutboxScope(scope) {
+        this.commitOutboxScope = scope;
+    }
+    sourceMutationIdsFor(batch) {
+        return [...new Set(batch.flatMap((transaction) => transaction.sourceMutationIds ?? []))];
+    }
+    /**
+     * Atomically replaces staged mutation journal rows with one exact request.
+     * The returned operations are the JSON-normalized values that must be sent;
+     * callers never send a separately reconstructed payload after sealing.
+     */
+    async sealDurableCommit(input) {
+        const sourceMutationIds = [...new Set(input.sourceMutationIds ?? [])];
+        const envelope = createDurableCommitEnvelope({
+            idempotencyKey: input.idempotencyKey,
+            origin: input.origin,
+            operations: [...input.operations],
+            sourceMutationIds,
+            commitOptions: {
+                ...(input.commitOptions?.causedByTaskId !== undefined
+                    ? { causedByTaskId: input.commitOptions.causedByTaskId }
+                    : {}),
+                ...(input.commitOptions?.reads !== undefined
+                    ? {
+                        reads: input.commitOptions.reads === null
+                            ? null
+                            : [...input.commitOptions.reads],
+                    }
+                    : {}),
+            },
+            ...(this.commitOutboxScope ? { scope: this.commitOutboxScope } : {}),
+            createdAt: input.createdAt,
+            sealedAt: input.sealedAt,
+            sequence: input.sequence ?? input.sealedAt * 1_000,
+        });
+        if (this.config.enablePersistence && this.commitOutbox) {
+            try {
+                await this.commitOutbox.seal(envelope, sourceMutationIds.map(pendingMutationRecordId));
+            }
+            catch (cause) {
+                if (cause instanceof AbloError)
+                    throw cause;
+                throw new AbloConnectionError('Could not seal the commit outbox before dispatch', {
+                    code: 'db_not_opened',
+                    cause,
+                });
+            }
+            this.emitCommitLifecycle('commit:envelope_persisted', {
+                idempotencyKey: envelope.idempotencyKey,
+                sourceMutationIds: envelope.sourceMutationIds,
+            });
+        }
+        return envelope;
+    }
+    /** Best-effort cleanup after a definitive result; replay is safe if it fails. */
+    async removeDurableCommit(idempotencyKey) {
+        if (!this.config.enablePersistence || !this.commitOutbox)
+            return;
+        try {
+            await this.commitOutbox.remove(commitEnvelopeRecordId(idempotencyKey));
+        }
+        catch (error) {
+            getContext().logger.debug('[TransactionQueue] Commit outbox cleanup deferred', {
+                idempotencyKey,
+                error: error instanceof Error ? error.message : String(error),
+            });
+        }
+    }
+    /**
+     * Takes either one complete retry envelope or a fresh batch. A retry waits
+     * until every original member has re-entered the queue, preventing an
+     * ambiguous A+B commit from being replayed later as A and B separately.
+     */
+    takeNextExecutionBatch() {
+        const retryGroups = new Map();
+        for (const tx of this.executionQueue) {
+            const envelope = tx.commitEnvelope;
+            if (!envelope)
+                continue;
+            const group = retryGroups.get(envelope.idempotencyKey) ??
+                new Map();
+            group.set(tx.id, tx);
+            retryGroups.set(envelope.idempotencyKey, group);
+        }
+        for (const [idempotencyKey, byId] of retryGroups) {
+            const members = [...byId.values()];
+            const expectedCount = members[0]?.commitEnvelope?.operationCount;
+            if (expectedCount === undefined || members.length !== expectedCount)
+                continue;
+            this.executionQueue = this.executionQueue.filter((tx) => tx.commitEnvelope?.idempotencyKey !== idempotencyKey);
+            members.sort((a, b) => (a.commitEnvelope?.operationIndex ?? 0) -
+                (b.commitEnvelope?.operationIndex ?? 0));
+            return members;
+        }
+        const fresh = this.executionQueue.filter((tx) => !tx.commitEnvelope);
+        const firstFresh = fresh[0];
+        if (!firstFresh)
+            return [];
+        // A caller-supplied key describes exactly one public mutation call. Keep
+        // that transaction out of an SDK-created aggregate batch so the key maps
+        // to the request its caller intended.
+        const explicitIndex = fresh.findIndex((tx) => typeof tx.writeOptions?.idempotencyKey === 'string');
+        const selected = explicitIndex === 0
+            ? [firstFresh]
+            : fresh.slice(0, Math.min(this.config.maxBatchSize, explicitIndex > 0 ? explicitIndex : fresh.length));
+        const selectedIds = new Set(selected.map((tx) => tx.id));
+        this.executionQueue = this.executionQueue.filter((tx) => !selectedIds.has(tx.id));
+        return selected;
+    }
+    /**
+     * Selects one reconnect batch without changing the request identity of work
+     * that was already attempted. Explicit caller keys remain one-call batches;
+     * an existing envelope is replayed only with all of its original members.
+     */
+    takeOfflineFlushBatch(pending) {
+        const first = pending[0];
+        if (!first)
+            return [];
+        const envelope = first.commitEnvelope;
+        if (envelope) {
+            return pending.filter((tx) => tx.commitEnvelope?.idempotencyKey === envelope.idempotencyKey);
+        }
+        if (typeof first.writeOptions?.idempotencyKey === 'string') {
+            return [first];
+        }
+        const boundary = pending.findIndex((tx) => tx.commitEnvelope !== undefined ||
+            typeof tx.writeOptions?.idempotencyKey === 'string');
+        return pending.slice(0, Math.min(this.config.maxBatchSize, boundary > 0 ? boundary : pending.length));
+    }
     /**
      * Resolvers for per-transaction `confirmation` promises. Populated in
      * `attachConfirmation` at staging time, consumed by the constructor-time
@@ -244,22 +494,18 @@ export class TransactionQueue extends EventEmitter {
         });
     }
     /**
-     * Look up the in-flight `confirmation` promise for a (model, id) pair.
-     * Returns the promise from the most-recent live transaction matching
-     * the given model+id, or `Promise.resolve()` if none is open (which
-     * means either "already confirmed" or "never staged" — both safe
-     * outcomes for the routing-helper grace-window use case).
-     *
-     * Looks across `pending`, `executing`, and `awaiting_delta` — these
-     * are the three non-terminal statuses where rollback is still
-     * possible. Skips `completed` (already settled) and `failed` /
-     * `rolled_back` (already rejected; the call site missed the
-     * `confirmation` window and should rely on `onMutationFailure` toast
-     * instead).
+     * Returns the in-flight confirmation promise for a given model and id. When
+     * several transactions match, it returns the most recent one's promise; when
+     * none is open it resolves immediately, which covers both "already confirmed"
+     * and "never staged".
      *
-     * Distinct from `tx.confirmation` on a known transaction — used by
-     * call sites that hold a Model reference (returned by
-     * `ablo.<model>.create()`) but never see the underlying transaction.
+     * It considers the three non-terminal statuses in which the write can still
+     * be rolled back — `pending`, `executing`, and `awaiting_delta` — and ignores
+     * `completed` (already settled) and `failed`/`rolled_back` (already
+     * rejected). This complements the `confirmation` promise carried on a known
+     * {@link Transaction}: use this method at call sites that hold a model
+     * returned by `ablo.<model>.create()` but never see the underlying
+     * transaction.
      */
     confirmationFor(modelName, modelId) {
         const candidates = [
@@ -275,15 +521,15 @@ export class TransactionQueue extends EventEmitter {
         return latest.confirmation ?? Promise.resolve();
     }
     /**
-     * Attach a hot `confirmation` promise to a freshly created transaction.
-     * Must be called BEFORE the transaction is staged so the call site can
-     * `await tx.confirmation` synchronously after the create/update/delete
-     * call returns. Idempotent: returns early if the tx already has one.
+     * Attaches a `confirmation` promise to a newly created transaction. Call this
+     * before the transaction is staged so a caller can `await tx.confirmation`
+     * immediately after a create, update, or delete returns. It is idempotent and
+     * returns early if one is already attached.
      *
-     * The unhandled-rejection trap is mandatory — most call sites won't
-     * `await confirmation`, and Node/browser would otherwise crash on the
-     * rejection. Consumers who *do* want failure visibility just attach a
-     * `.then`/`.catch` and the trap becomes a no-op.
+     * It also attaches a no-op rejection handler. Most callers never await the
+     * confirmation, and without this the runtime would report an unhandled
+     * rejection when a write fails. Callers that do want to observe failure simply
+     * attach their own `.then`/`.catch`.
      */
     attachConfirmation(tx) {
         if (tx.confirmation)
@@ -292,34 +538,30 @@ export class TransactionQueue extends EventEmitter {
             this.confirmationResolvers.set(tx.id, { resolve, reject });
         });
         tx.confirmation.catch(() => {
-            // Swallow unhandled rejections — explicit consumers attach their own
-            // handler; silent failure is the leak we're already fixing elsewhere.
+            // Swallow unhandled rejections; callers that care attach their own handler.
         });
     }
     /**
-     * Set connection state checker - prevents rollbacks during disconnection.
-     * When disconnected, timeouts re-schedule instead of rolling back.
+     * Registers a predicate the queue uses to check whether it is connected.
+     * While disconnected, confirmation timeouts re-schedule themselves instead of
+     * escalating, so a transaction is never rolled back merely because the client
+     * was briefly offline.
      */
     setConnectionChecker(fn) {
         this.isConnectedFn = fn;
     }
     /**
-     * Drive the offline-grace timer for in-flight commit-lane transactions.
+     * Drives the offline-grace timer for in-flight commit-lane transactions.
      *
-     * On `'disconnected'`: start a one-shot timer of
-     * `config.commitOfflineGraceMs`. If the timer fires (disconnect
-     * persisted past grace), iterate every commit-lane transaction with
-     * `status ∈ {'pending', 'executing'}` and emit
-     * `transaction:failed:${id}` with an `AbloConnectionError`. That
-     * lets `waitForCommitReceipt` reject in seconds instead of hanging
-     * forever — which is what wedged the 2026-05-15 subagent run.
+     * On `'disconnected'` it starts a one-shot timer of
+     * `config.commitOfflineGraceMs`. If that timer fires — meaning the disconnect
+     * outlasted the grace window — every commit-lane transaction still `pending`
+     * or `executing` is failed with an {@link AbloConnectionError}, so
+     * {@link waitForCommitReceipt} rejects within seconds instead of hanging.
      *
-     * On `'connected'`: clear any pending grace timer. Brief blips are
-     * absorbed transparently; the existing reconnect-retry path in
-     * `processCommitLane` / `flushOfflineQueue` handles the resumption.
-     *
-     * Called from SyncClient's `setConnectionState` after the
-     * `'connection:disconnected'` / `'connection:established'` events.
+     * On `'connected'` it clears any pending grace timer. Brief disconnects are
+     * absorbed transparently; {@link processCommitLane} and
+     * {@link flushOfflineQueue} resume the work on reconnect.
      */
     setConnectionState(state) {
         if (state === 'connected') {
@@ -347,8 +589,8 @@ export class TransactionQueue extends EventEmitter {
         }
         if (inFlight.length === 0)
             return;
-        // Internal mechanic: each failed commit surfaces to the consumer via its own
-        // rejection path, so this aggregate is forensic — debug, not warn.
+        // Each failed commit reaches the consumer through its own rejection path,
+        // so this aggregate line is forensic and logged at debug rather than warn.
         getContext().logger.debug(`[TransactionQueue] WS disconnected > ${graceMs}ms; failing ${inFlight.length} in-flight commit(s) with AbloConnectionError`, { inFlightIds: inFlight.map((id) => id.slice(0, 8)) });
         for (const id of inFlight) {
             const tx = this.commitStore.get(id);
@@ -361,39 +603,41 @@ export class TransactionQueue extends EventEmitter {
         }
     }
     /**
-     * Bind the executor for this queue instance. Called by the owning Ablo
-     * right after `BaseSyncedStore` is constructed so the executor's
-     * `storeHolder.store` closure resolves to *this* Ablo's WS — not whichever
-     * Ablo most recently called `initSyncEngine()`.
+     * Binds the mutation executor for this queue instance. The owning client
+     * calls this right after construction, so commits made here always dispatch
+     * through this instance's connection even when several client instances exist
+     * in the same process.
      */
     setMutationExecutor(executor) {
         this._mutationExecutor = executor;
     }
     // ============================================================================
-    // LINEAR PATTERN: Microtask-based Transaction Staging
+    // Microtask-based transaction staging
     // ============================================================================
     //
-    // All transactions first go to `createdTransactions` staging area.
-    // A microtask commits them all together with the same batchIndex.
-    // This ensures that bulk operations (like importing 100 layers) are batched efficiently.
+    // Every transaction lands in the `createdTransactions` staging area first.
+    // A microtask then commits them together under one batch index, so a bulk
+    // operation such as importing a hundred rows is sent efficiently.
     //
     // Flow:
-    // 1. create()/update()/delete() calls stageTransaction()
-    // 2. stageTransaction() adds to createdTransactions and schedules microtask
-    // 3. Microtask runs commitCreatedTransactions() after current sync code completes
-    // 4. All staged transactions get same batchIndex and move to executionQueue
+    // 1. create()/update()/delete() calls stageTransaction().
+    // 2. stageTransaction() adds to createdTransactions and schedules a microtask.
+    // 3. The microtask runs commitCreatedTransactions() once the current
+    //    synchronous code finishes.
+    // 4. All staged transactions share one batch index and move to the execution
+    //    queue.
     // ============================================================================
     /**
-     * Stage a transaction for commit (Linear pattern)
-     * Transactions staged in the same event loop tick will be committed together
+     * Stages a transaction for commit. Transactions staged within the same
+     * event-loop tick are committed together.
      */
     stageTransaction(transaction) {
         this.createdTransactions.push(transaction);
         this.scheduleCommit();
     }
     /**
-     * Schedule commit of staged transactions via microtask
-     * This ensures all synchronous transaction creates are batched together
+     * Schedules the staged transactions to commit on a microtask, so all
+     * transactions created synchronously within one tick are batched together.
      */
     scheduleCommit() {
         if (this.commitScheduled)
@@ -409,8 +653,8 @@ export class TransactionQueue extends EventEmitter {
         });
     }
     /**
-     * Commit all staged transactions to the execution queue (Linear pattern)
-     * All transactions get the same batchIndex for efficient batching
+     * Moves all staged transactions onto the execution queue, assigning them a
+     * single shared batch index so they commit together.
      */
     commitCreatedTransactions() {
         this.commitScheduled = false;
@@ -434,64 +678,99 @@ export class TransactionQueue extends EventEmitter {
             this.enqueue(transaction);
         }
     }
-    // Batch flush all pending transactions via commit (fast path on reconnect)
+    /**
+     * Flushes every pending transaction in one commit, the fast path taken on
+     * reconnect. If transport fails, the transactions retain this exact commit
+     * envelope when they fall back to normal queue processing.
+     */
     async flushOfflineQueue() {
-        // Kick the commit lane too — pending atomic envelopes from
-        // `commits.create()` were left at the head of the lane while the WS
-        // was down. Fire-and-forget; processCommitLane self-serializes.
+        this.assertDurableReplayOpen();
+        // Kick the commit lane too: atomic envelopes from `commits.create()` may
+        // have been left at the head of the lane while the connection was down.
+        // Fire-and-forget; processCommitLane serializes itself.
         void this.processCommitLane();
         // Collect pending transactions in created order
         const pending = this.store.getByStatus('pending').sort((a, b) => a.createdAt - b.createdAt);
         if (pending.length === 0)
             return;
-        // Build operations list
-        const operations = pending.map((tx) => {
-            this.ensureDerivedFields(tx);
-            return applyWriteOptions({
-                type: TX_TYPE_TO_MUTATION_OP[tx.type],
-                model: tx.modelKey,
-                id: tx.modelId,
-                input: tx.type === 'create' || tx.type === 'update' ? tx.data || {} : undefined,
-            }, tx);
-        });
-        try {
-            const res = await this.mutationExecutor.commit(operations);
-            // Mark all as completed
-            for (const tx of pending) {
-                this.store.updateStatus(tx.id, 'completed');
-                this.emit('transaction:completed', tx);
-                this.emit(`transaction:completed:${tx.id}`, tx);
-                this.optimisticUpdates.delete(tx.id);
-            }
-            // Simple perf note
-            getContext().logger.debug('txn:commit', 0, {
-                count: pending.length,
-                lastSyncId: res?.lastSyncId,
-            });
-        }
-        catch (err) {
-            // If batch fails, fall back to normal processing
-            // Only log if we're online (if we're offline, this is expected)
-            const isOffline = !getContext().onlineStatus.isOnline();
-            const isNetworkError = err instanceof Error &&
-                (err.message.includes('Failed to fetch') ||
-                    err.message.includes('Network request failed') ||
-                    err.message.includes('NetworkError'));
-            if (!isOffline || !isNetworkError) {
-                getContext().observability.breadcrumb('Batch flush fallback failed', 'sync.transaction', 'warning', {
-                    error: err instanceof Error ? err.message : String(err),
+        const pendingIds = new Set(pending.map((tx) => tx.id));
+        // These rows may already be waiting behind the normal batch timer. The
+        // reconnect fast path takes ownership of them for this attempt so the same
+        // transaction cannot dispatch concurrently through both paths.
+        this.executionQueue = this.executionQueue.filter((tx) => !pendingIds.has(tx.id));
+        const remaining = [...pending];
+        while (remaining.length > 0) {
+            const batch = this.takeOfflineFlushBatch(remaining);
+            if (batch.length === 0)
+                break;
+            const batchIds = new Set(batch.map((tx) => tx.id));
+            const nextRemaining = remaining.filter((tx) => !batchIds.has(tx.id));
+            try {
+                const idempotencyKey = this.ensureCommitEnvelope(batch);
+                const projectedOperations = batch.map((tx) => {
+                    this.ensureDerivedFields(tx);
+                    return applyWriteOptions({
+                        type: TX_TYPE_TO_MUTATION_OP[tx.type],
+                        model: tx.modelKey,
+                        id: tx.modelId,
+                        input: tx.type === 'create' || tx.type === 'update' ? tx.data || {} : undefined,
+                        transactionId: tx.id,
+                    }, tx);
+                });
+                const durableEnvelope = await this.sealDurableCommit({
+                    idempotencyKey,
+                    origin: 'model_batch',
+                    operations: projectedOperations,
+                    sourceMutationIds: this.sourceMutationIdsFor(batch),
+                    createdAt: Math.min(...batch.map((transaction) => transaction.createdAt)),
+                    sealedAt: batch[0]?.commitEnvelope?.sealedAt ?? Date.now(),
+                    sequence: batch[0]?.commitEnvelope?.sequence,
+                });
+                this.assertEnvelopeInsideReplayWindow(durableEnvelope);
+                const result = await this.mutationExecutor.commit(durableEnvelope.operations, {
+                    idempotencyKey,
+                });
+                await this.removeDurableCommit(idempotencyKey);
+                // Mark this request envelope as completed before moving to the next.
+                for (const tx of batch) {
+                    this.store.updateStatus(tx.id, 'completed');
+                    this.emit('transaction:completed', tx);
+                    this.emit(`transaction:completed:${tx.id}`, tx);
+                    this.optimisticUpdates.delete(tx.id);
+                }
+                getContext().logger.debug('txn:commit', 0, {
+                    count: batch.length,
+                    lastSyncId: result.lastSyncId,
                 });
+                remaining.splice(0, remaining.length, ...nextRemaining);
             }
-            // Enqueue pending ones to executionQueue
-            for (const tx of pending) {
-                this.enqueue(tx);
+            catch (err) {
+                // If one request fails, hand it and every later request back to the
+                // normal lane. Their envelopes stay attached for safe retry.
+                const isOffline = !getContext().onlineStatus.isOnline();
+                const isNetworkError = err instanceof Error &&
+                    (err.message.includes('Failed to fetch') ||
+                        err.message.includes('Network request failed') ||
+                        err.message.includes('NetworkError'));
+                if (!isOffline || !isNetworkError) {
+                    getContext().observability.breadcrumb('Batch flush fallback failed', 'sync.transaction', 'warning', {
+                        error: err instanceof Error ? err.message : String(err),
+                    });
+                }
+                for (const tx of [...batch, ...nextRemaining]) {
+                    this.enqueue(tx);
+                }
+                return;
             }
         }
     }
     /**
-     * Create operation with optimistic update
+     * Records a create and applies it optimistically, then stages it for the next
+     * batched commit. Returns the {@link Transaction}, whose `confirmation`
+     * promise settles once the server confirms the write.
      */
-    async create(model, context, writeOptions) {
+    async create(model, context, writeOptions, sourceMutationId) {
+        this.assertDurableReplayOpen();
         const actualModelName = model.getModelName();
         const transaction = {
             id: this.generateId(),
@@ -501,8 +780,8 @@ export class TransactionQueue extends EventEmitter {
             modelKey: normalizeModelKey(actualModelName),
             priorityScore: this.computePriorityScore('create', actualModelName),
             data: this.extractCreateData(model),
-            // CREATE rollback removes the row — there is no prior state to
-            // restore, so allocating a `toJSON()` snapshot here was waste.
+            // Rolling back a create removes the row, so there is no prior state to
+            // restore and no snapshot is captured here.
             previousData: null,
             context,
             status: 'pending',
@@ -510,36 +789,39 @@ export class TransactionQueue extends EventEmitter {
             attempts: 0,
             priority: 'normal',
             writeOptions,
+            ...(sourceMutationId ? { sourceMutationIds: [sourceMutationId] } : {}),
         };
         this.attachConfirmation(transaction);
         this.store.add(transaction);
         if (this.config.enableOptimistic) {
             this.applyOptimisticCreate(model, transaction);
         }
-        // Microtask coalescer (`scheduleCommit`) collapses all creates in
-        // this tick into one wire commit with one `batchIndex` — see
-        // `commitCreatedTransactions`. No batch API needed at the call site.
+        // The microtask coalescer (`scheduleCommit`) collapses all creates in this
+        // tick into one commit under a single `batchIndex` — see
+        // `commitCreatedTransactions`. No batch call is needed at the call site.
         this.stageTransaction(transaction);
         this.emit('transaction:created', transaction);
         return transaction;
     }
     /**
-     * Update operation with conflict detection
-     * @param precomputedChanges - Optional pre-captured changes (avoids re-reading from model)
+     * Records an update and applies it optimistically, then stages it for the next
+     * batched commit. Rapid updates to the same entity coalesce into a single wire
+     * operation.
+     * @param precomputedChanges - Optional pre-captured changes, used instead of re-reading them from the model.
      */
-    async update(model, context, precomputedChanges, writeOptions) {
+    async update(model, context, precomputedChanges, writeOptions, sourceMutationId) {
+        this.assertDurableReplayOpen();
         const actualModelName = model.getModelName();
         // Use pre-computed changes if provided, otherwise extract from model
         const updateInput = precomputedChanges
             ? this.mapChangesToInput(actualModelName, precomputedChanges)
             : this.extractUpdateData(model);
         const previousData = this.extractPreviousData(model, updateInput);
-        // Advance the per-field baseline for the keys we just froze into this
-        // transaction. `Model.propertyChanged` is first-old-wins and only cleared on
-        // sync-ack, so without this a SECOND update to the same field before the
-        // first acks would re-capture the original `.old` (the pre-session value)
-        // instead of THIS update's result — corrupting the stream-recorded undo
-        // inverse (the second move's "before" would point all the way back). The
+        // Advance the per-field baseline for the keys just frozen into this
+        // transaction. The model records the first old value per field and clears it
+        // only on sync acknowledgement, so a second update to the same field before
+        // the first is acknowledged would otherwise re-capture the original value
+        // instead of this update's result, corrupting the recorded undo inverse. The
         // wire payload is already frozen in `transaction.data`, so dropping the
         // consumed entries is safe.
         model.consumeModifiedFields(Object.keys(updateInput));
@@ -560,6 +842,7 @@ export class TransactionQueue extends EventEmitter {
             attempts: 0,
             priority: this.isReorderPayload(updateInput) ? 'high' : 'normal',
             writeOptions,
+            ...(sourceMutationId ? { sourceMutationIds: [sourceMutationId] } : {}),
         };
         this.attachConfirmation(transaction);
         this.store.add(transaction);
@@ -567,18 +850,23 @@ export class TransactionQueue extends EventEmitter {
         if (this.config.enableOptimistic) {
             this.applyOptimisticUpdate(model, transaction);
         }
-        // LINEAR PATTERN: Stage transaction for microtask commit
-        // Multiple updates in same event loop will be batched together
-        // enqueue() will still apply its coalescing logic for same-entity updates
+        // Stage the transaction for the microtask commit; updates made in the same
+        // tick are batched together, and enqueue() still coalesces same-entity
+        // updates.
         this.stageTransaction(transaction);
         this.emit('transaction:created', transaction);
         return transaction;
     }
     /**
-     * Delete operation with cascade handling
+     * Records a delete and applies it optimistically. If the row's own create has
+     * not yet been sent, both are cancelled locally rather than sending a create
+     * followed by a delete; if the create is already in flight, the delete waits
+     * until it settles so the server never sees a delete before the create.
      */
-    async delete(model, context, writeOptions) {
-        // 🔧 FIXED: Use getModelName() instead of constructor.name (production-safe)
+    async delete(model, context, writeOptions, sourceMutationId) {
+        this.assertDurableReplayOpen();
+        // Use getModelName() rather than constructor.name, which is unreliable once
+        // class names are minified.
         const actualModelName = model.getModelName();
         // Skip Activity delete transactions - activities are permanent audit records
         if (actualModelName === 'Activity') {
@@ -599,6 +887,7 @@ export class TransactionQueue extends EventEmitter {
                 attempts: 0,
                 priority: 'high',
                 writeOptions,
+                ...(sourceMutationId ? { sourceMutationIds: [sourceMutationId] } : {}),
                 localOnly: true,
                 // Activity deletes complete synchronously (audit-record skip path).
                 // Pre-resolved so consumers can still `await tx.confirmation` uniformly.
@@ -617,7 +906,10 @@ export class TransactionQueue extends EventEmitter {
         const unsentCreate = this.takeUnsentCreateForModel(actualModelName, model.id);
         if (unsentCreate) {
             await this.cancelUnsentCreateForDelete(unsentCreate);
-            return this.completeLocalDelete(model, context, writeOptions);
+            return this.completeLocalDelete(model, context, writeOptions, [
+                ...(unsentCreate.sourceMutationIds ?? []),
+                ...(sourceMutationId ? [sourceMutationId] : []),
+            ]);
         }
         const transaction = {
             id: this.generateId(),
@@ -633,13 +925,22 @@ export class TransactionQueue extends EventEmitter {
             attempts: 0,
             priority: 'high', // Deletes are high priority
             writeOptions,
+            ...(sourceMutationId ? { sourceMutationIds: [sourceMutationId] } : {}),
         };
         this.attachConfirmation(transaction);
         this.store.add(transaction);
         // Cancel any pending/in-flight updates for this model to prevent "no rows" errors
         // when the delete executes before the update (race condition fix)
-        this.cancelTransactionsForModel(model.id, 'update');
+        const canceledUpdates = this.cancelTransactionsForModel(model.id, 'update');
         const entityKey = this.entityKey(actualModelName, model.id);
+        const pendingMerge = this.pendingMergeByModel.get(entityKey);
+        transaction.sourceMutationIds = [
+            ...new Set([
+                ...(transaction.sourceMutationIds ?? []),
+                ...canceledUpdates.flatMap((candidate) => candidate.sourceMutationIds ?? []),
+                ...(pendingMerge?.sourceMutationIds ?? []),
+            ]),
+        ];
         this.pendingMergeByModel.delete(entityKey);
         this.inFlightByModel.delete(entityKey);
         // Apply optimistic delete
@@ -651,30 +952,35 @@ export class TransactionQueue extends EventEmitter {
             this.deferDeleteUntilCreateSettles(createBarrier, transaction);
         }
         else {
-            // LINEAR PATTERN: Stage transaction for microtask commit
-            // All deletes in same event loop will be batched together
+            // Stage the transaction for the microtask commit; deletes in the same
+            // tick are batched together.
             this.stageTransaction(transaction);
         }
         this.emit('transaction:created', transaction);
         return transaction;
     }
     /**
-     * Upload attachment — delegates to attachment-uploader.ts
+     * Uploads a single attachment, delegating to the mutation executor.
      */
-    async uploadAttachment(_file, options, _context) {
+    async uploadAttachment(_file, options, _context // eslint-disable-line @typescript-eslint/no-unused-vars -- reserved executor context
+    ) {
         return this.mutationExecutor.uploadAttachment?.(options.id, options) ?? null;
     }
     /**
-     * Batch upload attachments — delegates to MutationExecutor
+     * Uploads several attachments in one call, delegating to the mutation executor.
      */
-    async batchUploadAttachments(_files, items, _context) {
+    async batchUploadAttachments(_files, items, _context // eslint-disable-line @typescript-eslint/no-unused-vars -- reserved executor context
+    ) {
         return this.mutationExecutor.batchUploadAttachments?.(items.map(i => ({ id: i.id, input: i }))) ?? [];
     }
     /**
-     * Archive operation
+     * Records an archive and applies it optimistically, then stages it for the
+     * next batched commit.
      */
-    async archive(model, context, writeOptions) {
-        // 🔧 FIXED: Use getModelName() instead of constructor.name (production-safe)
+    async archive(model, context, writeOptions, sourceMutationId) {
+        this.assertDurableReplayOpen();
+        // Use getModelName() rather than constructor.name, which is unreliable once
+        // class names are minified.
         const actualModelName = model.getModelName();
         const modelKey = normalizeModelKey(actualModelName);
         const priorityScore = this.computePriorityScore('archive', actualModelName);
@@ -692,19 +998,23 @@ export class TransactionQueue extends EventEmitter {
             attempts: 0,
             priority: 'normal',
             writeOptions,
+            ...(sourceMutationId ? { sourceMutationIds: [sourceMutationId] } : {}),
         };
         this.attachConfirmation(transaction);
         this.store.add(transaction);
-        // LINEAR PATTERN: Stage transaction for microtask commit
+        // Stage the transaction for the microtask commit.
         this.stageTransaction(transaction);
         this.emit('transaction:created', transaction);
         return transaction;
     }
     /**
-     * Unarchive operation
+     * Records an unarchive and applies it optimistically, then stages it for the
+     * next batched commit.
      */
     async unarchive(model, context) {
-        // 🔧 FIXED: Use getModelName() instead of constructor.name (production-safe)
+        this.assertDurableReplayOpen();
+        // Use getModelName() rather than constructor.name, which is unreliable once
+        // class names are minified.
         const actualModelName = model.getModelName();
         const modelKey = normalizeModelKey(actualModelName);
         const priorityScore = this.computePriorityScore('unarchive', actualModelName);
@@ -724,37 +1034,44 @@ export class TransactionQueue extends EventEmitter {
         };
         this.attachConfirmation(transaction);
         this.store.add(transaction);
-        // LINEAR PATTERN: Stage transaction for microtask commit
+        // Stage the transaction for the microtask commit.
         this.stageTransaction(transaction);
         this.emit('transaction:created', transaction);
         return transaction;
     }
     /**
-     * Enqueue transaction for execution
+     * Places a transaction on the execution queue, coalescing it into an existing
+     * same-entity update where possible so redundant writes collapse.
      */
     enqueue(transaction) {
         this.ensureDerivedFields(transaction);
         const modelKey = `${transaction.modelName}:${transaction.modelId}`;
-        // LINEAR PATTERN: Simplified coalescing for updates
-        // Staging already batches all transactions in same event loop tick
-        // We only need to handle: (1) in-flight merging, (2) same-entity merging
+        // Coalescing for updates. Staging already batches everything created in one
+        // event-loop tick, so only two cases remain here: merging into an in-flight
+        // update, and merging into a pending same-entity update.
         //
-        // RETRIES (attempts > 0) must NEVER take either merge path. A retry is
-        // re-enqueued from `handleFailure` while its own modelKey is still in
-        // `inFlightByModel` (the post-batch cleanup runs after the catch), so the
-        // in-flight merge mistook the retry for a concurrent user edit: it moved
-        // the data into `pendingMergeByModel`, REMOVED the transaction, and the
-        // post-batch block minted a fresh follow-up with `attempts: 0`. The
-        // attempt counter never accumulated and `maxRetries` never tripped — an
-        // infinite ~`batchDelay` resend storm of self-laundering transaction
-        // clones (found by the claims journey, 2026-06-10).
-        if (transaction.type === 'update' && transaction.attempts === 0) {
-            const preserveWatermark = hasStaleWriteOptions(transaction.writeOptions);
+        // Retries (attempts > 0 or an already assigned commit envelope) must not
+        // take either merge path. A retry is re-enqueued while its own model key may
+        // still be marked in `inFlightByModel`; treating it as a concurrent edit
+        // would change the already-attempted request, discard its stable envelope,
+        // and either defeat maxRetries or duplicate an ambiguously committed write.
+        if (transaction.type === 'update' &&
+            transaction.attempts === 0 &&
+            !transaction.commitEnvelope) {
+            const preserveWatermark = hasCommitCoalescingBarrier(transaction.writeOptions);
             // If there is an in-flight update for this model, merge into post-flight buffer
             if (!preserveWatermark && this.inFlightByModel.has(modelKey)) {
-                const prev = this.pendingMergeByModel.get(modelKey) || {};
-                const merged = mergeUpdateData(prev, transaction.data || {}, transaction.modelName);
-                this.pendingMergeByModel.set(modelKey, merged);
+                const previous = this.pendingMergeByModel.get(modelKey);
+                const merged = mergeUpdateData(previous?.data ?? {}, transaction.data || {}, transaction.modelName);
+                this.pendingMergeByModel.set(modelKey, {
+                    data: merged,
+                    sourceMutationIds: [
+                        ...new Set([
+                            ...(previous?.sourceMutationIds ?? []),
+                            ...(transaction.sourceMutationIds ?? []),
+                        ]),
+                    ],
+                });
                 this.store.remove(transaction.id);
                 return;
             }
@@ -763,9 +1080,15 @@ export class TransactionQueue extends EventEmitter {
                 t.type === 'update' &&
                 t.modelId === transaction.modelId &&
                 t.modelName === transaction.modelName &&
-                !hasStaleWriteOptions(t.writeOptions));
+                !hasCommitCoalescingBarrier(t.writeOptions));
             if (!preserveWatermark && pendingInQueue) {
                 pendingInQueue.data = mergeUpdateData(pendingInQueue.data || {}, transaction.data || {}, transaction.modelName);
+                pendingInQueue.sourceMutationIds = [
+                    ...new Set([
+                        ...(pendingInQueue.sourceMutationIds ?? []),
+                        ...(transaction.sourceMutationIds ?? []),
+                    ]),
+                ];
                 this.store.remove(transaction.id);
                 return;
             }
@@ -782,8 +1105,9 @@ export class TransactionQueue extends EventEmitter {
     scheduleProcessing(immediate = false) {
         if (this.processScheduled)
             return;
-        // BACKPRESSURE: Don't schedule if too many transactions are already executing
-        // This prevents overwhelming the server with concurrent requests (Linear pattern)
+        // Backpressure: don't schedule another batch while too many transactions
+        // are already executing, so the server is not flooded with concurrent
+        // requests.
         if (this.executingCount >= this.config.maxExecutingTransactions) {
             getContext().logger.debug('[TransactionQueue] Backpressure: delaying batch, too many executing', {
                 executingCount: this.executingCount,
@@ -810,15 +1134,15 @@ export class TransactionQueue extends EventEmitter {
         }, delay);
     }
     /**
-     * Process batch of transactions using LINEAR-style unified batch execution.
-     *
-     * Key optimization: Instead of making separate calls per operation type/model,
-     * we collect ALL batchable operations and send them in a SINGLE commit call.
-     * The sync-server handles mixed types atomically inside one transaction.
-     *
-     * This reduces N round-trips to 1, dramatically improving batch latency.
+     * Processes one batch of transactions in a single commit. Rather than calling
+     * the server once per operation type or model, it collects every batchable
+     * operation and sends them together; the server applies the mixed operations
+     * atomically within one transaction. This turns many round trips into one and
+     * greatly reduces batch latency.
      */
     async processBatch() {
+        if (this.durableReplayBlock)
+            return;
         const batchStart = typeof performance !== 'undefined' ? performance.now() : Date.now();
         if (this.isProcessing || this.executionQueue.length === 0) {
             return;
@@ -828,9 +1152,9 @@ export class TransactionQueue extends EventEmitter {
         let batch = [];
         await getContext().observability.startSpanAsync('sync.batch', 'sync.transaction.batch', async () => {
             try {
-                // Sort executionQueue by FK priority before batch selection
-                // This ensures parent entities (Layout, SlideLayout) are always processed
-                // before their children (SlideLayoutLayer) across batch boundaries
+                // Sort the execution queue by foreign-key priority before selecting a
+                // batch, so a parent row is always committed before its children, even
+                // across batch boundaries.
                 this.executionQueue.sort((a, b) => {
                     // Ensure derived fields exist (covers restored/persisted transactions)
                     this.ensureDerivedFields(a);
@@ -843,8 +1167,12 @@ export class TransactionQueue extends EventEmitter {
                     }
                     return a.priorityScore - b.priorityScore;
                 });
-                // Get batch (now guaranteed to have parent entities before children)
-                batch = this.executionQueue.splice(0, this.config.maxBatchSize);
+                // Take a fresh batch or one complete retry envelope. Retry envelopes
+                // retain both their original membership and operation order.
+                batch = this.takeNextExecutionBatch();
+                if (batch.length === 0)
+                    return;
+                const commitIdempotencyKey = this.ensureCommitEnvelope(batch);
                 // Track executing count for backpressure
                 this.executingCount += batch.length;
                 // Mark all as executing
@@ -854,15 +1182,15 @@ export class TransactionQueue extends EventEmitter {
                         this.inFlightByModel.add(key);
                     this.store.updateStatus(tx.id, 'executing');
                 }
-                // Build ALL operations for unified commit (SINGLE WS round-trip)
+                // Build every operation for one unified commit (a single round trip).
                 const batchOps = [];
                 for (const tx of batch) {
-                    // Per-op `transactionId` carries the local tx UUID through
-                    // the wire so the server can stamp it on the resulting
-                    // sync delta. The receive path (`SyncClient.applyDeltaBatchToPool`)
-                    // matches it via `OptimisticEchoTracker.consumeEcho` to suppress
-                    // double-applying optimistic mutations. Distinct from the
-                    // batch-level idempotency key in mutation_log.
+                    // The per-operation `transactionId` carries the local transaction id
+                    // over the wire so the server can stamp it on the resulting sync
+                    // delta. The receive path matches it through
+                    // {@link UnconfirmedWrites.consumeEcho} to avoid applying the
+                    // client's own optimistic change twice. This is separate from the
+                    // batch-level idempotency key recorded in `mutation_log`.
                     const op = applyWriteOptions({
                         type: TX_TYPE_TO_MUTATION_OP[tx.type],
                         model: tx.modelKey,
@@ -872,28 +1200,40 @@ export class TransactionQueue extends EventEmitter {
                     }, tx);
                     batchOps.push({ tx, op });
                 }
-                // Execute unified commit for ALL operations (SINGLE WS round-trip)
+                // Execute the unified commit for every operation in one round trip.
                 if (batchOps.length > 0) {
-                    const operations = batchOps.map(({ op }) => op);
+                    let dispatchStarted = false;
                     try {
-                        // LINEAR PATTERN: Capture lastSyncId from server response for threshold-based confirmation
+                        const durableEnvelope = await this.sealDurableCommit({
+                            idempotencyKey: commitIdempotencyKey,
+                            origin: 'model_batch',
+                            operations: batchOps.map(({ op }) => op),
+                            sourceMutationIds: this.sourceMutationIdsFor(batch),
+                            createdAt: Math.min(...batch.map((transaction) => transaction.createdAt)),
+                            sealedAt: batch[0]?.commitEnvelope?.sealedAt ?? Date.now(),
+                            sequence: batch[0]?.commitEnvelope?.sequence,
+                        });
+                        const operations = durableEnvelope.operations;
+                        // Capture lastSyncId from the server response for threshold-based
+                        // confirmation.
                         //
-                        // Idempotency note: the default HTTP executor derives a
-                        // stable `Idempotency-Key` from the operations array
-                        // itself (sorted sha256), so retries of the SAME batch
-                        // hit the server's `mutation_log` replay path without
-                        // requiring us to thread a key through the microtask
-                        // boundary here. Keeping this path await-free preserves
-                        // the coalescing test's tight bound on batch count.
-                        const result = await this.mutationExecutor.commit(operations);
+                        // The queue owns request identity. A lost acknowledgement may be
+                        // retried after a backoff or reconnect, so every retry must send
+                        // the exact key assigned before the first transport attempt.
+                        this.assertEnvelopeInsideReplayWindow(durableEnvelope);
+                        dispatchStarted = true;
+                        const result = await this.mutationExecutor.commit(operations, {
+                            idempotencyKey: commitIdempotencyKey,
+                        });
+                        await this.removeDurableCommit(commitIdempotencyKey);
                         const lastSyncId = result?.lastSyncId ?? 0;
                         this.noteAck(lastSyncId);
-                        // Notify-instead-of-abort: the server returned stale-context
-                        // notifications for `onStale: 'notify'` ops whose premise moved.
-                        // Every notified op was HELD (not written) — its optimistic state
-                        // must be rolled back here; no delta will ever confirm it. We also
-                        // stamp the signal so `waitForCommitReceipt` carries it onto the
-                        // receipt.
+                        // The server returned stale-context notifications for operations
+                        // marked `onStale: 'notify'` whose read premise had moved. Each
+                        // notified operation was held rather than written, so its
+                        // optimistic state must be rolled back here — no delta will ever
+                        // confirm it — and the signal is stamped so
+                        // {@link waitForCommitReceipt} can carry it onto the receipt.
                         const notifications = result?.notifications;
                         const heldIds = new Set((notifications ?? []).map((n) => n.id));
                         for (const { tx } of batchOps) {
@@ -902,15 +1242,16 @@ export class TransactionQueue extends EventEmitter {
                                 this.commitNotifications.set(tx.id, txNotifs);
                             }
                         }
-                        // Detect server bug: lastSyncId 0 means mutation succeeded but no sync delta was emitted
+                        // A lastSyncId of 0 means the mutation succeeded but the server
+                        // emitted no sync delta; record that anomaly for observability.
                         if (lastSyncId === 0) {
                             getContext().observability.captureCommitZeroSyncId({
                                 operationCount: operations.length,
                                 operations: operations.map((op) => `${op.type}:${op.model}:${op.id?.slice(0, 8) ?? '?'}`),
                             });
                         }
-                        // LINEAR PATTERN: Mark as awaiting_delta with syncId threshold
-                        // Transactions will be confirmed when any delta with id >= lastSyncId arrives
+                        // Mark each transaction with the sync-id threshold that will
+                        // confirm it: any delta whose id is at least lastSyncId.
                         for (const { tx } of batchOps) {
                             // Held op ('notify'): the server withheld the write, so no delta
                             // will confirm it. Roll back the optimistic update (server
@@ -942,17 +1283,17 @@ export class TransactionQueue extends EventEmitter {
                                 });
                                 continue;
                             }
-                            // ACK-BASED CONFIRMATION. A successful commit response with a
-                            // real watermark means the server durably applied the write —
-                            // that IS the confirmation (the documented `wait: 'confirmed'`
-                            // contract, and how Replicache/Zero treat the push response's
-                            // lastMutationID). The delta echo is NOT an acknowledgement
-                            // channel: it's replication for OTHER clients, and this
-                            // client's own echo is suppressed by the OptimisticEchoTracker
-                            // anyway. Gating confirmation on the echo coupled "did my
-                            // write land" to subscription-stream health — a bare-Node
-                            // client with no live delta stream hung forever in
-                            // `awaiting_delta` on a write the server had already applied.
+                            // Acknowledgement-based confirmation. A successful commit
+                            // response carrying a real watermark means the server durably
+                            // applied the write, and that is the confirmation the
+                            // `wait: 'confirmed'` contract promises. The delta echo is not
+                            // an acknowledgement channel: it exists to replicate the change
+                            // to other clients, and this client's own echo is suppressed by
+                            // the {@link UnconfirmedWrites} regardless. Waiting on the
+                            // echo would tie "did my write land?" to the health of the
+                            // subscription stream, so a client with no live delta stream
+                            // would wait forever in `awaiting_delta` for a write the server
+                            // had already applied.
                             if (lastSyncId > 0) {
                                 this.store.updateStatus(tx.id, 'completed');
                                 this.emit('transaction:completed', tx);
@@ -966,12 +1307,11 @@ export class TransactionQueue extends EventEmitter {
                                 });
                             }
                             else {
-                                // lastSyncId === 0 on a non-DELETE: the server accepted the
-                                // commit but emitted no delta — a server-side anomaly
-                                // (already captured via captureCommitZeroSyncId above). Keep
-                                // the delta-wait + reconciliation timeout for THIS case
-                                // only, so the anomaly surfaces instead of silently
-                                // confirming a write with no watermark.
+                                // A lastSyncId of 0 on a non-delete: the server accepted the
+                                // commit but emitted no delta, which is an anomaly (already
+                                // captured above). Keep the delta wait and reconciliation
+                                // timeout only for this case, so the anomaly surfaces instead
+                                // of silently confirming a write that carries no watermark.
                                 this.store.updateStatus(tx.id, 'awaiting_delta');
                                 getContext().logger.debug('tx:awaiting_delta', {
                                     txId: tx.id.slice(0, 8),
@@ -986,11 +1326,14 @@ export class TransactionQueue extends EventEmitter {
                     }
                     catch (error) {
                         const errorMessage = error.message || '';
-                        // Surface the raw server rejection for the whole batch so
-                        // cascaded failures (e.g. Layout FK violation that rolls
-                        // back a 6-op transaction) are attributable to a specific
-                        // cause instead of each op showing as a generic permanent
-                        // error downstream.
+                        if (dispatchStarted && this.isDefinitiveRejection(error)) {
+                            await this.removeDurableCommit(commitIdempotencyKey);
+                        }
+                        // Surface the raw server rejection for the whole batch so a
+                        // cascaded failure — for example a foreign-key violation that
+                        // rolls back a multi-operation transaction — is attributable to a
+                        // specific cause rather than showing as a generic permanent error
+                        // on each operation.
                         const abloErr = error instanceof AbloError ? error : undefined;
                         // SyncWebSocket attaches a `diagnostics` snapshot to its
                         // "not connected" / "closed while in flight" rejections.
@@ -1026,16 +1369,20 @@ export class TransactionQueue extends EventEmitter {
                             message: errorMessage,
                             diagnostics,
                         });
-                        // LINEAR PATTERN: Handle "no rows in result set" gracefully
-                        // This error means the entity was already deleted - for UPDATE/DELETE ops, this is success
-                        // The claim was achieved (the data doesn't exist), so treat as completed
+                        // Handle "no rows in result set" gracefully: the row was already
+                        // deleted, so for update and delete operations this is effectively
+                        // success — the intended end state already holds — and the
+                        // transaction is treated as completed.
                         if (errorMessage.includes('no rows in result set')) {
+                            if (dispatchStarted) {
+                                await this.removeDurableCommit(commitIdempotencyKey);
+                            }
                             getContext().logger.info('[TransactionQueue] Graceful handling: entity already deleted', {
                                 batchSize: batchOps.length,
                             });
                             for (const { tx, op } of batchOps) {
                                 if (op.type === 'UPDATE' || op.type === 'DELETE') {
-                                    // Entity gone = claim achieved, mark as completed
+                                    // Row already gone: the intended state holds, mark completed.
                                     this.store.updateStatus(tx.id, 'completed');
                                     this.emit('transaction:completed', tx);
                                     getContext().logger.debug('[TransactionQueue] Orphaned transaction treated as success', {
@@ -1064,7 +1411,7 @@ export class TransactionQueue extends EventEmitter {
                     if (tx.type === 'update') {
                         this.inFlightByModel.delete(key);
                         const pending = this.pendingMergeByModel.get(key);
-                        if (pending && Object.keys(pending).length > 0) {
+                        if (pending && Object.keys(pending.data).length > 0) {
                             // Create a single merged follow-up transaction
                             const followUp = {
                                 id: this.generateId(),
@@ -1072,7 +1419,7 @@ export class TransactionQueue extends EventEmitter {
                                 modelName: tx.modelName,
                                 modelId: tx.modelId,
                                 modelKey: tx.modelKey ?? normalizeModelKey(tx.modelName),
-                                data: pending,
+                                data: pending.data,
                                 previousData: undefined,
                                 context: tx.context,
                                 status: 'pending',
@@ -1080,6 +1427,7 @@ export class TransactionQueue extends EventEmitter {
                                 attempts: 0,
                                 priority: 'normal',
                                 priorityScore: this.computePriorityScore('update', tx.modelName),
+                                sourceMutationIds: pending.sourceMutationIds,
                             };
                             this.pendingMergeByModel.delete(key);
                             this.store.add(followUp);
@@ -1093,7 +1441,7 @@ export class TransactionQueue extends EventEmitter {
                 // Decrement executing count for backpressure tracking
                 this.executingCount -= batch.length;
                 // Process next batch if needed
-                if (this.executionQueue.length > 0) {
+                if (this.executionQueue.length > 0 && batch.length > 0) {
                     this.scheduleProcessing(true);
                 }
                 const batchEnd = typeof performance !== 'undefined' ? performance.now() : Date.now();
@@ -1106,22 +1454,23 @@ export class TransactionQueue extends EventEmitter {
         }, { batchSize: this.executionQueue.length + (batch?.length ?? 0) });
     }
     /**
-     * LINEAR PATTERN: Confirm all awaiting transactions when delta with syncId >= threshold arrives.
-     * This replaces clientMutationId echoing - transactions are confirmed by sync ID threshold.
-     * Policy + timeout maps live in the `./deltaConfirmation.js` leaf.
-     * @param syncId - The sync ID of the received delta
+     * Confirms every awaiting transaction whose sync-id threshold this delta meets
+     * or exceeds. The confirmation policy and timeout tracking live in
+     * {@link DeltaConfirmationTracker} (`./deltaConfirmation.js`).
+     * @param syncId - The sync id of the received delta.
      */
     onDeltaReceived(syncId) {
         this.deltaConfirmation.onDeltaReceived(syncId);
     }
-    // REPLICACHE/POWERSYNC PATTERN: Schedule delta confirmation with retry +
-    // reconciliation — see DeltaConfirmationTracker in `./deltaConfirmation.js`.
+    // Schedule the retry-and-reconciliation wait for a transaction's confirming
+    // delta; see {@link DeltaConfirmationTracker} in `./deltaConfirmation.js`.
     scheduleDeltaConfirmationTimeout(tx, timeoutMs) {
         this.deltaConfirmation.scheduleDeltaConfirmationTimeout(tx, timeoutMs);
     }
     /**
-     * Wait for a transaction to be confirmed via delta echo (Linear pattern)
-     * Reuses existing timeout mechanism from scheduleDeltaConfirmationTimeout
+     * Resolves once the given transaction is confirmed and rejects if it fails.
+     * The confirming delta's timeout is handled by
+     * {@link scheduleDeltaConfirmationTimeout}.
      */
     waitForConfirmation(transactionId) {
         return new Promise((resolve, reject) => {
@@ -1148,21 +1497,45 @@ export class TransactionQueue extends EventEmitter {
             this.on(`transaction:failed:${transactionId}`, onFailed);
         });
     }
-    // Public: check if a clientMutationId exists in this queue (helps identify self-echo deltas)
+    // Reports whether a client mutation id is known to this queue, which helps
+    // identify a delta as this client's own echo.
     hasClientMutationId(id) {
         return !!this.store.get(id) || this.commitStore.has(id);
     }
     /**
-     * Enqueue a raw multi-op atomic commit envelope (the `ablo.commits.create`
-     * path). Operations are pre-built by the caller; the queue's job is
-     * retry-on-reconnect + idempotent dedup, NOT optimistic apply or FK
-     * ordering. Same idempotency key (clientTxId) is dropped on the floor
-     * if already in flight — server-side `mutation_log` handles cross-session
-     * dedup; this guard handles same-session double-enqueue.
+     * Enqueues a pre-built, multi-operation atomic commit — the
+     * `ablo.commits.create()` path. The caller supplies the operations; the queue
+     * only retries on reconnect and de-duplicates, and does not apply the change
+     * optimistically or reorder for foreign keys. A duplicate `clientTxId`
+     * already in flight is ignored: the server's `mutation_log` de-duplicates
+     * across sessions, and this guard covers a double-enqueue within one session.
      */
-    enqueueCommit(clientTxId, operations, options = {}) {
-        if (this.commitStore.has(clientTxId))
+    async enqueueCommit(clientTxId, operations, options = {}) {
+        this.assertDurableReplayOpen();
+        const existing = this.commitStore.get(clientTxId);
+        if (existing) {
+            await existing.sealPromise;
+            const existingIntent = stableStringify({
+                operations: existing.operations,
+                causedByTaskId: existing.causedByTaskId ?? null,
+                reads: existing.reads ?? null,
+            });
+            const incomingIntent = stableStringify({
+                operations,
+                causedByTaskId: options.causedByTaskId ?? null,
+                reads: options.reads ?? null,
+            });
+            if (existingIntent !== incomingIntent) {
+                throw new AbloIdempotencyError('Idempotency key reused with a different atomic commit request', { code: 'idempotency_conflict' });
+            }
+            if (existing.status === 'pending')
+                void this.processCommitLane();
             return;
+        }
+        this.emitCommitLifecycle('commit:staging', {
+            clientTxId,
+            operations,
+        });
         const tx = {
             id: clientTxId,
             kind: 'commit',
@@ -1172,25 +1545,56 @@ export class TransactionQueue extends EventEmitter {
             status: 'pending',
             createdAt: Date.now(),
             attempts: 0,
+            sealedAt: Date.now(),
+            sequence: this.nextCommitSequence(),
         };
         this.commitStore.set(clientTxId, tx);
+        tx.sealPromise = this.sealDurableCommit({
+            idempotencyKey: tx.id,
+            origin: 'atomic_commit',
+            operations: tx.operations,
+            commitOptions: {
+                causedByTaskId: tx.causedByTaskId ?? null,
+                ...(tx.reads ? { reads: tx.reads } : {}),
+            },
+            createdAt: tx.createdAt,
+            sealedAt: tx.sealedAt,
+            sequence: tx.sequence,
+        }).then((envelope) => {
+            tx.durableEnvelope = envelope;
+            tx.operations = envelope.operations.map((operation) => ({ ...operation }));
+        });
+        try {
+            await tx.sealPromise;
+        }
+        catch (error) {
+            this.commitStore.delete(clientTxId);
+            this.emitCommitLifecycle('commit:seal_failed', { clientTxId });
+            throw error;
+        }
+        finally {
+            tx.sealPromise = undefined;
+        }
         this.commitLane.push(tx);
-        // Surface the envelope on its OWN event so the undo stream can record
-        // commit-lane writes too (`SyncClient.onLocalTransaction` enriches each
-        // operation with pool-captured previous state). Deliberately NOT
-        // `transaction:created` — that event also feeds the optimistic-echo
-        // tracker, and commit-lane ops have no optimistic pool apply to echo.
-        this.emit('commit:created', { clientTxId, operations: tx.operations });
+        // Emit the envelope on its own event so the undo stream can record
+        // commit-lane writes as well. This deliberately avoids `transaction:created`,
+        // which also feeds the optimistic-echo tracker: commit-lane operations apply
+        // nothing optimistically and so have no echo to suppress.
+        this.emitCommitLifecycle('commit:created', {
+            clientTxId,
+            operations: tx.operations,
+        });
         void this.processCommitLane();
     }
     /**
-     * Drain pending commit-lane envelopes serially. Transient failures
-     * (network, ws_not_ready) leave the head-of-queue tx in `pending` and
-     * break — reconnect handler re-kicks via `flushOfflineQueue`.
-     * Permanent failures emit `transaction:failed:<id>` and drop the tx.
+     * Drains the pending commit-lane envelopes one at a time. A transient
+     * failure, such as a network error, leaves the envelope at the head of the
+     * lane in `pending` and stops; reconnect re-kicks it through
+     * {@link flushOfflineQueue}. A permanent failure emits
+     * `transaction:failed:<id>` and drops the envelope.
      */
     async processCommitLane() {
-        if (this.commitProcessing)
+        if (this.commitProcessing || this.durableReplayBlock)
             return;
         this.commitProcessing = true;
         try {
@@ -1204,24 +1608,52 @@ export class TransactionQueue extends EventEmitter {
                 }
                 tx.status = 'executing';
                 tx.attempts += 1;
+                let dispatchStarted = false;
                 try {
-                    const result = await this.mutationExecutor.commit(tx.operations, {
+                    const durableEnvelope = tx.durableEnvelope ??
+                        (await this.sealDurableCommit({
+                            idempotencyKey: tx.id,
+                            origin: 'atomic_commit',
+                            operations: tx.operations,
+                            sourceMutationIds: tx.sourceMutationIds,
+                            commitOptions: {
+                                causedByTaskId: tx.causedByTaskId ?? null,
+                                ...(tx.reads ? { reads: tx.reads } : {}),
+                            },
+                            createdAt: tx.createdAt,
+                            sealedAt: tx.sealedAt,
+                            sequence: tx.sequence,
+                        }));
+                    tx.durableEnvelope = durableEnvelope;
+                    this.assertEnvelopeInsideReplayWindow(durableEnvelope);
+                    dispatchStarted = true;
+                    const result = await this.mutationExecutor.commit(durableEnvelope.operations, {
                         idempotencyKey: tx.id,
-                        causedByTaskId: tx.causedByTaskId ?? undefined,
-                        ...(tx.reads ? { reads: tx.reads } : {}),
+                        causedByTaskId: durableEnvelope.commitOptions.causedByTaskId ?? undefined,
+                        ...(durableEnvelope.commitOptions.reads
+                            ? { reads: durableEnvelope.commitOptions.reads }
+                            : {}),
                     });
+                    await this.removeDurableCommit(tx.id);
                     tx.lastSyncId = result?.lastSyncId ?? 0;
                     this.noteAck(tx.lastSyncId);
                     tx.status = 'completed';
                     this.commitLane.shift();
-                    this.emit('transaction:completed', tx);
-                    this.emit(`transaction:completed:${tx.id}`, tx);
+                    // Guarded: a throwing observer here would land in the catch below,
+                    // whose permanent branch shifts the lane a second time and rejects a
+                    // commit the server has already durably applied.
+                    this.emitCommitLifecycle('transaction:completed', tx);
+                    this.emitCommitLifecycle(`transaction:completed:${tx.id}`, tx);
                 }
                 catch (err) {
                     const error = err instanceof Error ? err : new Error(String(err));
+                    if (dispatchStarted && this.isDefinitiveRejection(error)) {
+                        await this.removeDurableCommit(tx.id);
+                    }
                     if (!this.isPermanentError(error)) {
-                        // Transient — leave at head, retry on next kick (reconnect or
-                        // next enqueueCommit). Don't tight-loop while WS is down.
+                        // Transient: leave it at the head and retry on the next kick
+                        // (reconnect or the next enqueueCommit) rather than tight-looping
+                        // while the connection is down.
                         tx.status = 'pending';
                         getContext().logger.debug('[TransactionQueue] commit lane transient', {
                             txId: tx.id.slice(0, 12),
@@ -1233,15 +1665,16 @@ export class TransactionQueue extends EventEmitter {
                     tx.status = 'failed';
                     tx.error = error;
                     this.commitLane.shift();
-                    // Internal bookkeeping — the consumer-facing rejection is emitted via
-                    // 'transaction:failed' and surfaced by the permanent-error headline → debug.
+                    // Internal bookkeeping; the consumer-facing rejection is emitted on
+                    // 'transaction:failed' and surfaced by the permanent-error headline,
+                    // so this line stays at debug.
                     getContext().logger.debug('[TransactionQueue] commit lane permanent error', {
                         txId: tx.id.slice(0, 12),
                         attempts: tx.attempts,
                         message: error.message,
                     });
-                    this.emit('transaction:failed', { transaction: tx, error, permanent: true });
-                    this.emit(`transaction:failed:${tx.id}`, { error });
+                    this.emitCommitLifecycle('transaction:failed', { transaction: tx, error, permanent: true });
+                    this.emitCommitLifecycle(`transaction:failed:${tx.id}`, { error });
                 }
             }
         }
@@ -1250,10 +1683,10 @@ export class TransactionQueue extends EventEmitter {
         }
     }
     /**
-     * Promise-based confirmation for a commit-lane transaction. Resolves
-     * with the server-side `lastSyncId` once `mutation_result` lands;
-     * rejects on permanent failure. Backs the `wait: 'confirmed'` semantics
-     * of `ablo.commits.create()`.
+     * Resolves once a commit-lane transaction is confirmed, returning the server's
+     * `lastSyncId` and any stale-context notifications; rejects on permanent
+     * failure. This backs the `wait: 'confirmed'` semantics of
+     * `ablo.commits.create()`.
      */
     waitForCommitReceipt(clientTxId) {
         // Drain any stale-context notifications stamped for this tx on the ack.
@@ -1296,20 +1729,20 @@ export class TransactionQueue extends EventEmitter {
         return 'order' in data || 'orderKey' in data || 'position' in data;
     }
     /**
-     * Determine if an error is transient (retryable) vs permanent (non-retryable).
-     *
-     * IMPORTANT: Uses a BLOCKLIST approach for safety - only retry on known transient errors.
-     * Any unknown error type defaults to permanent (don't retry) to prevent infinite loops.
+     * Classifies an error as transient (worth retrying) or permanent. The
+     * approach is deliberately conservative: only known-transient errors are
+     * retried, and anything unrecognized is treated as permanent so a failing
+     * write cannot loop forever.
      *
-     * Transient errors (will retry):
-     * - Network failures, connection errors, timeouts
-     * - Server errors (5xx status codes)
-     * - Rate limiting (429)
+     * Transient (retried):
+     * - Network failures, connection errors, and timeouts.
+     * - Server errors (HTTP 5xx).
+     * - Rate limiting (HTTP 429).
      *
-     * Permanent errors (won't retry - includes but not limited to):
-     * - Validation errors, constraint violations
-     * - Not found, unauthorized, forbidden
-     * - Any other business logic error from the server
+     * Permanent (not retried), among others:
+     * - Validation errors and constraint violations.
+     * - Not found, unauthorized, and forbidden.
+     * - Any other business-logic error from the server.
      */
     isPermanentError(error) {
         // Typed connection error (e.g. ws_not_ready, transport timeout) is
@@ -1366,19 +1799,31 @@ export class TransactionQueue extends EventEmitter {
         // This is the safe default - better to fail fast than retry forever
         return true;
     }
+    /** True only when the server definitively rejected before applying. */
+    isDefinitiveRejection(error) {
+        if (error instanceof AbloError && error.code) {
+            const spec = errorCodeSpec(error.code);
+            if (spec)
+                return !spec.retryable;
+        }
+        const status = extractStatusCode(error);
+        return status !== undefined && status >= 400 && status < 500 && status !== 429;
+    }
     /**
-     * Handle transaction failure
+     * Handles a failed transaction: retries transient failures with backoff and
+     * rolls back permanent ones, settling the transaction's confirmation promise
+     * either way.
      */
     async handleFailure(transaction, error) {
         transaction.attempts++;
-        // Check if this is a permanent error that should NOT be retried
+        // Check whether this is a permanent error that should not be retried.
         if (this.isPermanentError(error)) {
-            // Elevated to warn — permanent errors mean user writes were rejected
-            // by the server, so the user should be able to see WHY in the
-            // console (not just via Sentry). Include the typed AbloError fields
-            // so the cause is visible: `type`/`code`/`httpStatus` are what
-            // distinguish e.g. FK-violation (AbloValidationError) from auth
-            // expiry (AbloAuthenticationError).
+            // Logged at warn: a permanent error means the server rejected the write,
+            // so the developer should see the reason in the console. The typed
+            // AbloError fields (`type`, `code`, `httpStatus`) are included so the
+            // cause is visible — for example a foreign-key violation
+            // (AbloValidationError) versus expired authentication
+            // (AbloAuthenticationError).
             try {
                 const abloErr = error instanceof AbloError ? error : undefined;
                 const details = {
@@ -1407,17 +1852,16 @@ export class TransactionQueue extends EventEmitter {
                 const isRepeat = sig === this.lastPermanentErrorSig;
                 this.lastPermanentErrorSig = sig;
                 const logger = getContext().logger;
-                // Two registers, one call site, split by log level (the default
-                // consumer logger is gated at `warn`, so `debug` is invisible unless
-                // someone sets ABLO_LOG_LEVEL=debug to debug the engine itself):
-                //   • the default-visible line speaks the APP DEVELOPER's language —
-                //     their verb (`update`), their model, the typed error's own human
-                //     message, and the wire `code` for grep — the way AI SDK / Next.js
-                //     surface errors. No engine nouns ("TransactionQueue", "permanent",
-                //     "rolling back") and no JSON dump on this line: those alarm and
-                //     don't help someone who just installed @abloatai/ablo.
-                //   • the forensic `details` ride a companion `debug` line for whoever
-                //     is debugging the engine internals.
+                // Two registers from one call site, split by log level (the default
+                // logger is gated at `warn`, so `debug` stays hidden unless
+                // ABLO_LOG_LEVEL=debug is set to inspect the engine):
+                //   - the default-visible line speaks the application developer's
+                //     language: their verb (such as `update`), their model, the typed
+                //     error's own message, and the wire `code` for searching. It uses
+                //     no engine jargon and prints no JSON dump, which would alarm
+                //     without helping.
+                //   - the forensic `details` ride a companion `debug` line for anyone
+                //     debugging the engine internals.
                 const revertNote = this.config.enableOptimistic
                     ? ' The local change was reverted.'
                     : '';
@@ -1453,15 +1897,11 @@ export class TransactionQueue extends EventEmitter {
             return;
         }
         if (transaction.attempts < this.config.maxRetries) {
-            // Exponential backoff with FULL jitter for EVERY transient retry
-            // (AWS-standard shape: `sleep = random(0, min(cap, base × 2^attempt))`
-            // — see the Exponential Backoff And Jitter analysis). Throttling
-            // signals (429/503) get a longer base, mirroring the AWS SDK's
-            // transient-vs-throttle split. Previously only 429/503 backed off
-            // AND the sleep blocked the whole batch loop — every other failure
-            // retried at raw `batchDelay` cadence. The re-enqueue is scheduled
-            // (never awaited) so one backing-off transaction can't stall
-            // unrelated commits.
+            // Exponential backoff with full jitter on every transient retry:
+            // `sleep = random(0, min(cap, base * 2^attempt))`. Throttling responses
+            // (429/503) use a longer base than other transient errors. The re-enqueue
+            // is scheduled rather than awaited, so one backing-off transaction cannot
+            // stall unrelated commits.
             const { baseMs, capMs } = this.config.retryBackoff;
             let base = baseMs;
             try {
@@ -1493,7 +1933,9 @@ export class TransactionQueue extends EventEmitter {
         }
     }
     /**
-     * Conflict resolution
+     * Resolves a conflict against server data using the configured strategy:
+     * last-write-wins rolls the local change back, merge and reject re-enqueue it,
+     * and custom applies the caller's resolver.
      */
     async handleConflict(transaction, serverData) {
         const { strategy, resolver } = this.config.conflictResolution;
@@ -1523,8 +1965,8 @@ export class TransactionQueue extends EventEmitter {
         }
     }
     /**
-     * Optimistic updates — apply/rollback rules live in `./optimistic.js`;
-     * these delegates bind the host-owned ledger + event emitter.
+     * Optimistic updates. The apply and rollback rules live in `./optimisticApply.js`;
+     * these methods bind them to the queue's own tracking map and event emitter.
      */
     applyOptimisticCreate(model, transaction) {
         applyOptimisticCreate(this.optimisticUpdates, this, model, transaction);
@@ -1539,25 +1981,9 @@ export class TransactionQueue extends EventEmitter {
         await rollbackOptimistic(this.optimisticUpdates, this, transaction, reason, error);
     }
     /**
-     * Execute individual transaction via the unified commit path
-     */
-    async executeTransaction(transaction) {
-        const { type, modelName, modelId, data } = transaction;
-        const schemaName = stripModelSuffix(modelName);
-        const mutationType = TX_TYPE_TO_MUTATION_OP[type];
-        const model = normalizeModelKey(modelName);
-        const input = (type === 'create' || type === 'update') ? data : undefined;
-        try {
-            await this.mutationExecutor.commit([
-                applyWriteOptions({ type: mutationType, model, id: modelId, input }, transaction),
-            ]);
-        }
-        catch (error) {
-            handleMutationError(error, `${type}-mutation`, schemaName, modelId);
-        }
-    }
-    /**
-     * Persistence
+     * Loads transactions persisted from a previous session and re-enqueues them,
+     * so writes made while offline survive a restart. Does nothing when
+     * persistence is disabled.
      */
     async loadPersistedTransactions(database) {
         if (!this.config.enablePersistence)
@@ -1580,11 +2006,102 @@ export class TransactionQueue extends EventEmitter {
         }
     }
     /**
-     * Validate + rehydrate one persisted row (the T1.8 IDB replay boundary).
-     * Rows written by other subsystems into the same store (`'queue'`,
-     * `'awaiting_delta'`) are skipped silently; rows that fail the
-     * persisted-transaction schema (older SDK versions, corruption) are
-     * DROPPED with an observability capture instead of replayed as commits.
+     * Restore exact sealed requests after the local database is open. Sealed
+     * envelopes replay through the atomic commit lane and are never re-projected
+     * through model/schema state from the new process.
+     */
+    async restoreDurableCommits() {
+        if (!this.config.enablePersistence)
+            return new Set();
+        const sourceMutationIds = new Set();
+        try {
+            if (!this.commitOutbox)
+                return sourceMutationIds;
+            const rows = await this.commitOutbox.list();
+            const envelopes = [];
+            for (const row of rows) {
+                if (typeof row !== 'object' ||
+                    row === null ||
+                    row.type !== 'commit_envelope')
+                    continue;
+                const parsed = durableCommitEnvelopeSchema.safeParse(row);
+                if (parsed.success) {
+                    envelopes.push(parsed.data);
+                }
+                else {
+                    getContext().logger.warn('A saved local write is unreadable and was held for review.');
+                    getContext().observability.captureTransactionFailure({
+                        context: 'restore-commit-envelope',
+                        error: parsed.error,
+                    });
+                    throw new AbloValidationError('A saved commit envelope is unreadable; replay stopped before newer writes were sent.', { code: 'write_options_invalid', cause: parsed.error });
+                }
+            }
+            envelopes.sort((a, b) => (a.sequence ?? a.sealedAt * 1_000) -
+                (b.sequence ?? b.sealedAt * 1_000) ||
+                a.id.localeCompare(b.id));
+            for (const envelope of envelopes) {
+                for (const mutationId of envelope.sourceMutationIds) {
+                    sourceMutationIds.add(mutationId);
+                }
+                if (Date.now() - envelope.sealedAt >=
+                    TransactionQueue.DURABLE_REPLAY_WINDOW_MS) {
+                    getContext().logger.warn('A saved local write is too old to retry safely and was held for review.');
+                    getContext().observability.captureTransactionFailure({
+                        context: 'quarantine-expired-commit-envelope',
+                        error: `Envelope ${envelope.idempotencyKey} is too old to replay safely`,
+                    });
+                    throw new AbloIdempotencyError('A saved commit is older than the server idempotency window and cannot be replayed safely.', { code: 'idempotency_conflict' });
+                }
+                if (this.commitOutboxScope &&
+                    (!envelope.scope || // eslint-disable-line @typescript-eslint/prefer-optional-chain -- missing scope must quarantine
+                        envelope.scope.organizationId !== this.commitOutboxScope.organizationId ||
+                        envelope.scope.participantId !== this.commitOutboxScope.participantId ||
+                        envelope.scope.namespace !== this.commitOutboxScope.namespace)) {
+                    getContext().logger.warn('A saved local write belongs to a different account or server and was held for review.');
+                    continue;
+                }
+                if (this.commitStore.has(envelope.idempotencyKey))
+                    continue;
+                const transaction = {
+                    id: envelope.idempotencyKey,
+                    kind: 'commit',
+                    operations: envelope.operations.map((operation) => ({ ...operation })),
+                    causedByTaskId: envelope.commitOptions.causedByTaskId ?? null,
+                    ...(envelope.commitOptions.reads
+                        ? { reads: [...envelope.commitOptions.reads] }
+                        : {}),
+                    status: 'pending',
+                    createdAt: envelope.createdAt,
+                    sealedAt: envelope.sealedAt,
+                    sequence: envelope.sequence ?? envelope.sealedAt * 1_000,
+                    attempts: 0,
+                    sourceMutationIds: [...envelope.sourceMutationIds],
+                    durableEnvelope: envelope,
+                };
+                this.commitStore.set(transaction.id, transaction);
+                this.commitLane.push(transaction);
+            }
+            if (this.commitLane.length > 0)
+                void this.processCommitLane();
+        }
+        catch (error) {
+            getContext().logger.debug('[TransactionQueue] Failed to restore commit outbox', {
+                error: error instanceof Error ? error.message : String(error),
+            });
+            getContext().observability.captureTransactionFailure({
+                context: 'restore-commit-envelopes',
+                error: error instanceof Error ? error : String(error),
+            });
+            throw error;
+        }
+        return sourceMutationIds;
+    }
+    /**
+     * Validates and rehydrates one persisted row. Rows written to the same store
+     * by other subsystems are skipped, and rows that fail the persisted
+     * transaction schema — from an older version or corruption — are dropped and
+     * reported rather than replayed as commits.
      */
     deserializeTransaction(data) {
         if (isNonReplayablePersistedRow(data))
@@ -1606,7 +2123,9 @@ export class TransactionQueue extends EventEmitter {
         return transaction;
     }
     /**
-     * Cancel transactions for a specific model
+     * Cancels every pending or executing transaction for a given model id,
+     * optionally limited to one operation type, rolling back their optimistic
+     * state. Returns the cancelled transactions.
      */
     cancelTransactionsForModel(modelId, transactionType) {
         const cancelledTransactions = [];
@@ -1634,16 +2153,14 @@ export class TransactionQueue extends EventEmitter {
         return cancelledTransactions;
     }
     /**
-     * LINEAR PATTERN: Cancel transactions for child entities by foreign key
+     * Cancels pending transactions for child rows that reference a deleted parent,
+     * used to cascade a parent deletion. The caller supplies the foreign-key
+     * relationship; this method performs the cancellation.
      *
-     * Used by SyncedStore for cascade cancellation when a parent is deleted.
-     * This keeps FK relationship knowledge in ModelRegistry/SyncedStore,
-     * while TransactionQueue just handles the cancellation mechanics.
-     *
-     * @param childModelName - The child model type (e.g., 'SlideLayer')
-     * @param foreignKey - The FK property name (e.g., 'slideId')
-     * @param parentId - The deleted parent's ID
-     * @returns Number of transactions cancelled
+     * @param childModelName - The child model type (for example 'SlideLayer').
+     * @param foreignKey - The foreign-key property name (for example 'slideId').
+     * @param parentId - The deleted parent's id.
+     * @returns The number of transactions cancelled.
      */
     cancelTransactionsByForeignKey(childModelName, foreignKey, parentId) {
         let cancelled = 0;
@@ -1677,14 +2194,12 @@ export class TransactionQueue extends EventEmitter {
         return cancelled;
     }
     /**
-     * Get count of outstanding transactions
+     * Returns the number of transactions still pending or executing.
      */
     getOutstandingTransactionCount() {
         return this.store.getByStatus('pending').length + this.store.getByStatus('executing').length;
     }
-    /**
-     * Utilities
-     */
+    /** Generates a unique local transaction id. */
     generateId() {
         return `tx_${Date.now()}_${Math.random().toString(36).substring(2, 11)}`;
     }
@@ -1700,35 +2215,26 @@ export class TransactionQueue extends EventEmitter {
     extractUpdateData(model) {
         return projectCommitPayload(model.getModelName(), model.getChanges(), { dropUndefined: true });
     }
-    buildUpdateInput(modelName, changes) {
-        return projectCommitPayload(modelName, changes, { dropUndefined: true });
-    }
     // Derive previous values for changed fields to support accurate rollback.
-    //
-    // The previous Slide-specific branch reaching into `_data` was removed:
-    // the field name in the comment (`_localChanges`) didn't match the
-    // code (`_data`), no `Slide` class still defines either field, and
-    // hardcoded model-name checks don't belong in a generic queue. If a
-    // model ever needs to surface previous-state outside `modifiedProperties`,
-    // expose a typed `getPreviousData()` accessor on Model and call that.
+    // Model-specific special cases do not belong here; a model that needs to
+    // surface previous state beyond `modifiedProperties` should expose a typed
+    // `getPreviousData()` accessor for this method to call.
     extractPreviousData(model, updateInput) {
         // When the update's written keys are known, capture a before-image for
-        // EXACTLY those keys so the recorded undo inverse can revert them and only
-        // them (a full-row inverse would clobber concurrent edits to unrelated
-        // fields). `fallbackToLive: false` makes `Model.capturePreviousValues` OMIT
-        // any key it can't resolve from `modifiedProperties.old` / the original
-        // snapshot — `buildUndoOps` then drops an un-revertible inverse rather than
-        // inventing one. With no `updateInput` (full extract) fall back to every
-        // tracked field. `Model.capturePreviousValues` is the single before-image
-        // source shared with `RecordingTransaction.snapshotFields`.
+        // exactly those keys, so the recorded undo inverse reverts them and nothing
+        // else — a full-row inverse would clobber concurrent edits to unrelated
+        // fields. `fallbackToLive: false` makes `Model.capturePreviousValues` omit
+        // any key it cannot resolve, and `buildUndoOps` then drops an un-revertible
+        // inverse rather than inventing one. With no `updateInput` (a full extract)
+        // it falls back to every tracked field. `Model.capturePreviousValues` is the
+        // single before-image source, shared with
+        // `RecordingTransaction.snapshotFields`.
         const keys = updateInput
             ? Object.keys(updateInput)
             : [...(model.modifiedProperties instanceof Map ? model.modifiedProperties.keys() : [])];
         return { id: model.id, ...model.capturePreviousValues(keys, { fallbackToLive: false }) };
     }
-    /**
-     * Public API
-     */
+    /** Returns a snapshot of queue counts and the current configuration. */
     getStats() {
         return {
             pending: this.store.getByStatus('pending').length,
@@ -1742,8 +2248,8 @@ export class TransactionQueue extends EventEmitter {
         };
     }
     /**
-     * Get detailed debug info for the sync debug page
-     * Exposes internal state that helps diagnose delta confirmation issues
+     * Returns detailed internal state — pending, executing, and awaiting-delta
+     * transactions — to help diagnose delta-confirmation issues.
      */
     getDebugInfo() {
         const awaitingDelta = this.store.getByStatus('awaiting_delta');
@@ -1773,18 +2279,17 @@ export class TransactionQueue extends EventEmitter {
             })),
         };
     }
-    /**
-     * Set configuration
-     */
+    /** Merges the given options into the queue's configuration. */
     setConfig(config) {
         this.config = { ...this.config, ...config };
     }
     /**
-     * Handle incoming sync delta - simplified for permanent IDs
+     * Re-emits an incoming sync delta on the `sync:delta` event for the store to
+     * apply. Because rows use stable ids, no id reconciliation is needed here.
      */
     handleSyncDelta(delta) {
-        // With permanent IDs, no reconciliation needed!
-        // Just emit the delta for ObjectPool to handle directly
+        // Row ids are stable, so no reconciliation is needed; re-emit the delta for
+        // the store to apply directly.
         this.emit('sync:delta', {
             id: delta.id,
             modelName: delta.modelName,
@@ -1794,7 +2299,8 @@ export class TransactionQueue extends EventEmitter {
         return true;
     }
     /**
-     * Cleanup and dispose resources
+     * Releases the queue's resources: rolls back outstanding optimistic updates,
+     * clears all timers and stored transactions, and removes event listeners.
      */
     dispose() {
         // Cancel all active optimistic updates