@abloatai/ablo 0.25.0 → 0.27.0

package/dist/transactions/TransactionQueue.js

@@ -1,202 +1,27 @@
 /**
- * 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 { Model } from '../Model.js';
 import { getContext } from '../context.js';
-import { getActiveRegistry } from '../ModelRegistry.js';
-import { MutationOperationType } from '../types/index.js';
-import { handleMutationError } from './mutation-error-handler.js';
 import { AbloError, AbloConnectionError, errorCodeSpec } from '../errors.js';
 import { SyncPosition } from '../sync/syncPosition.js';
-/**
- * Framework-internal keys added by `Model.toJSON()` that must never
- * reach the wire. The server treats each top-level key as a target
- * column, so shipping these would blow up the INSERT/UPDATE.
- */
-const FRAMEWORK_KEYS = new Set(['__class', '__typename', 'clientId', 'syncStatus']);
-/**
- * Project a Model's serialized data onto its schema-declared fields
- * and return a wire-safe commit payload. Two jobs:
- *
- *   1. Drop framework internals (`__class`, `__typename`, `clientId`,
- *      `syncStatus`) and anything not declared on the model's schema.
- *   2. JSON.stringify values typed as `field.json()` — TEXT columns
- *      storing JSON need explicit stringification; postgres.js won't
- *      auto-serialize for non-JSONB columns.
- *
- * For updates (`dropUndefined: true`), `undefined` values are also
- * stripped so they don't translate to `SET column = NULL` on the
- * server side.
- *
- * Fields are read from `ModelRegistry`, populated by
- * `registerModelsFromSchema` at SDK initialization. If the model
- * isn't registered with field metadata (edge case — e.g., tests or
- * manually registered models), projection falls back to identity and
- * the caller gets whatever the Model serialized.
- */
-function projectCommitPayload(modelName, source, opts) {
-    const metadata = getActiveRegistry().getMetadata(modelName);
-    const fields = metadata?.fields;
-    const out = {};
-    if (!fields) {
-        // Unknown registration — strip framework keys and ship the rest.
-        for (const [k, v] of Object.entries(source)) {
-            if (FRAMEWORK_KEYS.has(k))
-                continue;
-            if (opts.dropUndefined && v === undefined)
-                continue;
-            out[k] = v;
-        }
-        return out;
-    }
-    for (const [key, meta] of Object.entries(fields)) {
-        if (!(key in source))
-            continue;
-        const value = source[key];
-        if (opts.dropUndefined && value === undefined)
-            continue;
-        // JSON-typed fields (`jsonb` on the server): ship as OBJECTS over
-        // the wire, not pre-stringified strings. Previously we stringified
-        // here, which round-tripped incorrectly:
-        //
-        //   1. Client stringifies `position: {x, y}` → `'{"x":...}'`
-        //   2. Server writes to jsonb column (parses string → jsonb object, fine)
-        //   3. Server's delta echoes `data: JSON.stringify(op.input)` where
-        //      `op.input.position` is still the STRING from step 1
-        //   4. Client merges delta → `model.position = "{...}"` (STRING)
-        //   5. Next drag: `{ ...layer.position, x, y }` spreads the STRING
-        //      char-by-char, producing corrupted char-indexed objects like
-        //      `{"0":"{","1":"\"","2":"x",...,"x":null,"y":null,...}`
-        //   6. That corrupt object lands in the next commit, stored in jsonb.
-        //
-        // Sending objects avoids the round-trip mismatch: the wire carries
-        // the object through delta + commit unchanged, and `postgres-js`
-        // serializes JS objects to jsonb correctly via its own
-        // `json.serialize` (triggered by Postgres's ParameterDescription
-        // response identifying the column as type 3802 / jsonb).
-        out[key] = value;
-    }
-    return out;
-}
-const normalizeModelKey = (modelName) => modelName.replace('Model', '').toLowerCase();
-const stripModelSuffix = (modelName) => modelName.replace('Model', '');
-/**
- * FK-ordered create priority.
- *
- * Reads `config.modelCreatePriority` out of the runtime SyncEngineContext —
- * this map is populated once at `createSyncEngine(...)` time by walking the
- * schema's `belongsTo` graph (see `computeFKDepthPriority` in
- * `client/createSyncEngine.ts`). The queue stays schema-agnostic: no model
- * names appear here, and consumer applications can override specific
- * priorities via `configOverrides.modelCreatePriority` without touching the
- * SDK.
- *
- * Non-create ops (update/delete/archive/unarchive) don't need FK ordering
- * because the row already exists, so they all share
- * `config.defaultNonCreatePriority`.
- */
-const computePriorityScore = (type, modelName) => {
-    const { modelCreatePriority, defaultCreatePriority, defaultNonCreatePriority } = getContext().config;
-    if (type !== 'create')
-        return defaultNonCreatePriority;
-    return modelCreatePriority.get(modelName) ?? defaultCreatePriority;
-};
-const TX_TYPE_TO_MUTATION_OP = {
-    create: MutationOperationType.CREATE,
-    update: MutationOperationType.UPDATE,
-    delete: MutationOperationType.DELETE,
-    archive: MutationOperationType.ARCHIVE,
-    unarchive: MutationOperationType.UNARCHIVE,
-};
-function hasStaleWriteOptions(options) {
-    return (options?.readAt !== undefined ||
-        options?.onStale !== undefined);
-}
-/**
- * Project a transaction's `writeOptions` onto the wire operation. Stale
- * guards (`readAt`/`onStale`) ride at the op root; `idempotencyKey`/`label`
- * ride in the op's `options` slot (`MutationOperation.options` — the
- * mutation_log cache key + audit tag). This is the single place the
- * caller-supplied write vocabulary crosses onto the wire.
- */
-function applyWriteOptions(op, transaction) {
-    const operation = op;
-    const writeOptions = transaction.writeOptions;
-    if (!writeOptions)
-        return operation;
-    if (writeOptions.readAt !== undefined) {
-        operation.readAt = writeOptions.readAt;
-    }
-    if (writeOptions.onStale !== undefined) {
-        operation.onStale = writeOptions.onStale;
-    }
-    if (writeOptions.idempotencyKey != null || writeOptions.label !== undefined) {
-        operation.options = {
-            ...(writeOptions.idempotencyKey != null
-                ? { idempotencyKey: writeOptions.idempotencyKey }
-                : {}),
-            ...(writeOptions.label !== undefined ? { label: writeOptions.label } : {}),
-        };
-    }
-    return operation;
-}
-function asTransportError(value) {
-    return (value && typeof value === 'object' ? value : {});
-}
-function extractStatusCode(error) {
-    return asTransportError(error).response?.status;
-}
-class TransactionStore {
-    transactions = new Map();
-    byStatus = new Map();
-    add(transaction) {
-        this.transactions.set(transaction.id, transaction);
-        if (!this.byStatus.has(transaction.status)) {
-            this.byStatus.set(transaction.status, new Set());
-        }
-        this.byStatus.get(transaction.status).add(transaction.id);
-    }
-    get(id) {
-        return this.transactions.get(id);
-    }
-    updateStatus(id, newStatus) {
-        const tx = this.transactions.get(id);
-        if (!tx)
-            return;
-        this.byStatus.get(tx.status)?.delete(id);
-        tx.status = newStatus;
-        if (!this.byStatus.has(newStatus)) {
-            this.byStatus.set(newStatus, new Set());
-        }
-        this.byStatus.get(newStatus).add(id);
-    }
-    getByStatus(status) {
-        const ids = this.byStatus.get(status) || new Set();
-        return Array.from(ids)
-            .map((id) => this.transactions.get(id))
-            .filter(Boolean);
-    }
-    remove(id) {
-        const tx = this.transactions.get(id);
-        if (!tx)
-            return;
-        this.transactions.delete(id);
-        this.byStatus.get(tx.status)?.delete(id);
-    }
-    clear() {
-        this.transactions.clear();
-        this.byStatus.clear();
-    }
-    getAll() {
-        return Array.from(this.transactions.values());
-    }
-}
+import { projectCommitPayload, computePriorityScore, normalizeModelKey, hasStaleWriteOptions, 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 './replayValidation.js';
+import { applyOptimisticCreate, applyOptimisticUpdate, applyOptimisticDelete, rollbackOptimistic, } from './optimisticApply.js';
 export class TransactionQueue extends EventEmitter {
     store = new TransactionStore();
     // Signature of the last permanent-error we logged at `warn`. A `create`
@@ -205,17 +30,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;
@@ -224,8 +49,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
@@ -250,10 +75,7 @@ export class TransactionQueue extends EventEmitter {
         }
     }
     entityKey(modelName, modelId) {
-        return `${modelName}:${modelId}`;
-    }
-    isTransactionForModel(transaction, modelName, modelId) {
-        return transaction.modelName === modelName && transaction.modelId === modelId;
+        return entityKey(modelName, modelId);
     }
     resolveConfirmation(transaction) {
         const resolver = this.confirmationResolvers.get(transaction.id);
@@ -263,19 +85,7 @@ export class TransactionQueue extends EventEmitter {
         resolver.resolve();
     }
     takeUnsentCreateForModel(modelName, modelId) {
-        const isUnsentCreate = (tx) => tx.type === 'create' &&
-            tx.status === 'pending' &&
-            tx.attempts === 0 &&
-            this.isTransactionForModel(tx, modelName, modelId);
-        const stagedIndex = this.createdTransactions.findIndex(isUnsentCreate);
-        if (stagedIndex >= 0) {
-            return this.createdTransactions.splice(stagedIndex, 1)[0];
-        }
-        const queuedIndex = this.executionQueue.findIndex(isUnsentCreate);
-        if (queuedIndex >= 0) {
-            return this.executionQueue.splice(queuedIndex, 1)[0];
-        }
-        return this.store.getByStatus('pending').find(isUnsentCreate);
+        return takeUnsentCreateForModel(this.createdTransactions, this.executionQueue, this.store, modelName, modelId);
     }
     async cancelUnsentCreateForDelete(transaction) {
         this.store.updateStatus(transaction.id, 'rolled_back');
@@ -285,17 +95,7 @@ export class TransactionQueue extends EventEmitter {
         this.resolveConfirmation(transaction);
     }
     findCreateBarrierForDelete(modelName, modelId) {
-        const liveCreates = [
-            ...this.store.getByStatus('pending'),
-            ...this.store.getByStatus('executing'),
-            ...this.store.getByStatus('awaiting_delta'),
-        ].filter((tx) => tx.type === 'create' &&
-            this.isTransactionForModel(tx, modelName, modelId) &&
-            // A never-attempted pending create can be cancelled instead. Once the
-            // create has been sent, even a retry-pending state is a causal barrier:
-            // the server may already have applied it and only the response was lost.
-            (tx.status !== 'pending' || tx.attempts > 0));
-        return liveCreates.sort((a, b) => b.createdAt - a.createdAt)[0];
+        return findCreateBarrierForDelete(this.store, modelName, modelId);
     }
     completeLocalDelete(model, context, writeOptions) {
         const actualModelName = model.getModelName();
@@ -328,75 +128,17 @@ export class TransactionQueue extends EventEmitter {
         return transaction;
     }
     deferDeleteUntilCreateSettles(createTransaction, deleteTransaction) {
-        const key = this.entityKey(createTransaction.modelName, createTransaction.modelId);
-        const deferred = this.deferredDeletesByCreate.get(key) ?? [];
-        deferred.push(deleteTransaction);
-        this.deferredDeletesByCreate.set(key, deferred);
+        deferDeleteUntilCreateSettles(this.deferredDeletesByCreate, createTransaction, deleteTransaction);
     }
     releaseDeferredDeletesForCreate(createTransaction) {
-        const key = this.entityKey(createTransaction.modelName, createTransaction.modelId);
-        const deferred = this.deferredDeletesByCreate.get(key);
-        if (!deferred || deferred.length === 0)
-            return;
-        this.deferredDeletesByCreate.delete(key);
-        for (const deleteTransaction of deferred) {
-            if (this.store.get(deleteTransaction.id)?.status !== 'pending')
-                continue;
-            this.enqueue(deleteTransaction);
-        }
+        releaseDeferredDeletesForCreate(this.deferredDeletesByCreate, this.store, (tx) => { this.enqueue(tx); }, createTransaction);
     }
-    // Merge two GraphQL update payloads with special handling for metadata fields
-    mergeUpdateData(left, right, _modelName) {
-        const out = { ...(left || {}) };
-        const src = right || {};
-        for (const key of Object.keys(src)) {
-            // Special case: metadata payloads may be JSON strings; merge objects instead of clobbering
-            if (key === 'metadata') {
-                const l = out.metadata;
-                const r = src.metadata;
-                // If both sides undefined/null, continue
-                if (l == null && r == null) {
-                    continue;
-                }
-                // Normalize to objects
-                const toObj = (v) => {
-                    if (v == null)
-                        return {};
-                    if (typeof v === 'string') {
-                        try {
-                            return JSON.parse(v);
-                        }
-                        catch {
-                            return {};
-                        }
-                    }
-                    if (typeof v === 'object')
-                        return v;
-                    return {};
-                };
-                const lobj = toObj(l);
-                const robj = toObj(r);
-                const merged = { ...lobj, ...robj };
-                // Re-stringify to match schema input type
-                try {
-                    out.metadata = JSON.stringify(merged);
-                }
-                catch {
-                    // Fallback to right-hand side if stringify fails
-                    out.metadata = typeof r === 'string' ? r : JSON.stringify(robj || {});
-                }
-                continue;
-            }
-            // Default: shallow overwrite with right-hand value
-            out[key] = src[key];
-        }
-        return out;
-    }
-    // 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',
@@ -413,18 +155,21 @@ export class TransactionQueue extends EventEmitter {
     };
     // Track executing transactions for backpressure
     executingCount = 0;
-    // Optimistic update tracking
+    // 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();
-    // LINEAR PATTERN: Track delta confirmation timeouts for awaiting_delta transactions
-    // Following Replicache/PowerSync pattern: retry with backoff instead of rolling back
-    deltaConfirmationTimeouts = new Map();
-    // Track retry attempts per transaction for exponential backoff
-    deltaConfirmationRetries = new Map();
-    // Connection state check - set by SyncClient to prevent rollbacks during disconnection
+    // 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, 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')`,
@@ -432,11 +177,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. */
@@ -444,15 +189,8 @@ export class TransactionQueue extends EventEmitter {
         return this.position.applied;
     }
     noteAck(lastSyncId) {
-        this.position.noteAck(lastSyncId);
-    }
-    // Delta confirmation retry config (Replicache-style exponential backoff)
-    // Max retries before requesting full reconciliation
-    static DELTA_MAX_RETRIES = 5;
-    // Initial timeout (first attempt)
-    static DELTA_INITIAL_TIMEOUT_MS = 30_000;
-    // Max timeout cap (like Replicache's maxDelayMs of 60s)
-    static DELTA_MAX_TIMEOUT_MS = 120_000;
+        this.deltaConfirmation.noteAck(lastSyncId);
+    }
     // Batch management
     batchIndex = 0;
     /**
@@ -466,6 +204,18 @@ export class TransactionQueue extends EventEmitter {
     constructor(config) {
         super();
         this.position = config?.position ?? new SyncPosition();
+        // Bind the confirmation tracker to this queue's store/ledger/events.
+        // `isConnected` closes over `isConnectedFn` so `setConnectionChecker`
+        // swaps stay visible to in-flight timeouts.
+        this.deltaConfirmation = new DeltaConfirmationTracker({
+            store: this.store,
+            optimisticUpdates: this.optimisticUpdates,
+            emit: (event, payload) => {
+                this.emit(event, payload);
+            },
+            isConnected: () => this.isConnectedFn(),
+            position: this.position,
+        });
         if (config) {
             this.config = { ...this.config, ...config };
         }
@@ -500,22 +250,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 = [
@@ -526,18 +272,20 @@ export class TransactionQueue extends EventEmitter {
         if (candidates.length === 0)
             return Promise.resolve();
         const latest = candidates.sort((a, b) => b.createdAt - a.createdAt)[0];
+        if (!latest)
+            return Promise.resolve();
         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)
@@ -546,34 +294,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.
-     *
-     * 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.
+     * Drives the offline-grace timer for in-flight commit-lane transactions.
      *
-     * On `'connected'`: clear any pending grace timer. Brief blips are
-     * absorbed transparently; the existing reconnect-retry path in
-     * `processCommitLane` / `flushOfflineQueue` handles the resumption.
+     * 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.
      *
-     * 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') {
@@ -601,8 +345,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);
@@ -615,39 +359,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)
@@ -663,8 +409,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;
@@ -688,11 +434,15 @@ 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 the batch fails, each transaction falls back to normal,
+     * one-by-one 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.
+        // 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);
@@ -743,7 +493,9 @@ export class TransactionQueue extends EventEmitter {
         }
     }
     /**
-     * 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) {
         const actualModelName = model.getModelName();
@@ -755,8 +507,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',
@@ -770,16 +522,18 @@ export class TransactionQueue extends EventEmitter {
         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) {
         const actualModelName = model.getModelName();
@@ -788,12 +542,11 @@ export class TransactionQueue extends EventEmitter {
             ? 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));
@@ -821,18 +574,22 @@ 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)
+        // 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') {
@@ -905,30 +662,32 @@ 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) {
         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) {
         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)
+        // 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);
@@ -949,16 +708,18 @@ 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;
     }
     /**
-     * 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)
+        // 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);
@@ -978,36 +739,35 @@ 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).
+        // Retries (attempts > 0) must not take either merge path. A retry is
+        // re-enqueued from `handleFailure` while its own model key is still marked
+        // in `inFlightByModel`, so treating it as a concurrent edit would move its
+        // data into `pendingMergeByModel`, remove the transaction, and then mint a
+        // fresh follow-up with the attempt counter reset to zero. The counter would
+        // never accumulate, `maxRetries` would never trip, and the write would
+        // resend in an endless loop.
         if (transaction.type === 'update' && transaction.attempts === 0) {
             const preserveWatermark = hasStaleWriteOptions(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 = this.mergeUpdateData(prev, transaction.data || {}, transaction.modelName);
+                const merged = mergeUpdateData(prev, transaction.data || {}, transaction.modelName);
                 this.pendingMergeByModel.set(modelKey, merged);
                 this.store.remove(transaction.id);
                 return;
@@ -1019,7 +779,7 @@ export class TransactionQueue extends EventEmitter {
                 t.modelName === transaction.modelName &&
                 !hasStaleWriteOptions(t.writeOptions));
             if (!preserveWatermark && pendingInQueue) {
-                pendingInQueue.data = this.mergeUpdateData(pendingInQueue.data || {}, transaction.data || {}, transaction.modelName);
+                pendingInQueue.data = mergeUpdateData(pendingInQueue.data || {}, transaction.data || {}, transaction.modelName);
                 this.store.remove(transaction.id);
                 return;
             }
@@ -1036,8 +796,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,
@@ -1064,13 +825,11 @@ 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() {
         const batchStart = typeof performance !== 'undefined' ? performance.now() : Date.now();
@@ -1082,9 +841,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);
@@ -1108,15 +867,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,
@@ -1126,28 +885,27 @@ 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);
                     try {
-                        // LINEAR PATTERN: Capture lastSyncId from server response for threshold-based confirmation
+                        // 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.
+                        // Idempotency: the default HTTP executor derives a stable
+                        // idempotency key from the operations array itself (a sorted
+                        // SHA-256), so retrying the same batch reaches the server's
+                        // `mutation_log` replay path without threading a key through the
+                        // microtask boundary here.
                         const result = await this.mutationExecutor.commit(operations);
                         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) {
@@ -1156,15 +914,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
@@ -1196,17 +955,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);
@@ -1220,12 +979,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),
@@ -1240,11 +998,11 @@ 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.
+                        // 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.
@@ -1258,7 +1016,7 @@ export class TransactionQueue extends EventEmitter {
                             // wrapping in Ablo.commit() and any future wrappers.
                             for (let i = 0; i < 3 && cur && typeof cur === 'object'; i++) {
                                 if ('diagnostics' in cur && cur.diagnostics) {
-                                    return cur.diagnostics;
+                                    return (cur).diagnostics;
                                 }
                                 cur = cur.cause;
                             }
@@ -1280,16 +1038,17 @@ 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')) {
                             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', {
@@ -1360,179 +1119,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.
-     * @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) {
-        // Cursor advancing happens where the delta is APPLIED (the store calls
-        // position.advanceApplied / advancePersisted); this hook only resolves
-        // confirmation thresholds against the incoming id.
-        const awaitingTxs = this.store.getByStatus('awaiting_delta');
-        const executingTxs = this.store.getByStatus('executing');
-        // Debug: Show state when delta arrives
-        if (awaitingTxs.length > 0 || executingTxs.length > 0) {
-            getContext().logger.debug('tx:delta_received', {
-                syncId,
-                lastSeenSyncId: this.lastSeenSyncId,
-                awaitingCount: awaitingTxs.length,
-                executingCount: executingTxs.length,
-                awaitingThresholds: awaitingTxs.map((tx) => ({
-                    txId: tx.id.slice(0, 8),
-                    model: tx.modelName,
-                    needed: tx.syncIdNeededForCompletion,
-                    willConfirm: tx.syncIdNeededForCompletion !== undefined && syncId >= tx.syncIdNeededForCompletion,
-                })),
-            });
-        }
-        // Fast path: no awaiting transactions
-        if (awaitingTxs.length === 0)
-            return;
-        let confirmedCount = 0;
-        for (const tx of awaitingTxs) {
-            // Confirm if this delta's ID meets or exceeds the threshold
-            if (tx.syncIdNeededForCompletion !== undefined && syncId >= tx.syncIdNeededForCompletion) {
-                this.cancelDeltaConfirmationTimeout(tx.id);
-                this.store.updateStatus(tx.id, 'completed');
-                this.emit('transaction:completed', tx);
-                this.emit(`transaction:completed:${tx.id}`, tx);
-                this.optimisticUpdates.delete(tx.id);
-                confirmedCount++;
-                getContext().logger.debug('tx:confirm_via_delta', {
-                    txId: tx.id.slice(0, 8),
-                    model: tx.modelName,
-                    neededSyncId: tx.syncIdNeededForCompletion,
-                    receivedSyncId: syncId,
-                });
-            }
-        }
-        // Log batch summary only if we confirmed something
-        if (confirmedCount > 0) {
-            // Use warn for staging visibility when transactions confirm
-            getContext().observability.breadcrumb('Transactions confirmed via delta', 'sync.transaction', 'info', {
-                count: confirmedCount,
-                syncId,
-                remainingAwaiting: awaitingTxs.length - confirmedCount,
-            });
-        }
+        this.deltaConfirmation.onDeltaReceived(syncId);
     }
-    // REPLICACHE/POWERSYNC PATTERN: Schedule delta confirmation with retry + reconciliation
-    // Instead of rolling back on timeout (which destroys confirmed server state),
-    // retry with exponential backoff and request reconciliation to catch up on missed deltas.
-    // Only rollback on explicit server rejection, never on timeout.
+    // Schedule the retry-and-reconciliation wait for a transaction's confirming
+    // delta; see {@link DeltaConfirmationTracker} in `./deltaConfirmation.js`.
     scheduleDeltaConfirmationTimeout(tx, timeoutMs) {
-        // Cancel any existing timeout for this transaction
-        this.cancelDeltaConfirmationTimeout(tx.id);
-        const timeoutHandle = setTimeout(async () => {
-            const currentTx = this.store.get(tx.id);
-            if (!currentTx || currentTx.status !== 'awaiting_delta') {
-                this.deltaConfirmationRetries.delete(tx.id);
-                return; // Already confirmed or failed
-            }
-            // If disconnected, re-schedule with same timeout (no backoff while offline)
-            if (!this.isConnectedFn()) {
-                // Self-healing: re-schedule the confirmation wait while offline, no
-                // consumer action needed → debug.
-                getContext().logger.debug('[TransactionQueue] Timeout fired while disconnected - re-scheduling', {
-                    txId: tx.id.slice(0, 8),
-                    model: tx.modelName,
-                });
-                this.deltaConfirmationTimeouts.delete(tx.id);
-                this.scheduleDeltaConfirmationTimeout(tx, timeoutMs);
-                return;
-            }
-            const retryCount = this.deltaConfirmationRetries.get(tx.id) ?? 0;
-            const diagnosis = this.lastSeenSyncId === 0
-                ? 'No deltas received - delta pipeline may be broken'
-                : currentTx.syncIdNeededForCompletion &&
-                    this.lastSeenSyncId < currentTx.syncIdNeededForCompletion
-                    ? 'Delta not yet received - may be lost or delayed'
-                    : 'Delta should have confirmed - possible race condition';
-            getContext().observability.captureReconciliation({
-                reason: 'delta_timeout',
-                model: tx.modelName,
-                modelId: tx.modelId,
-                syncIdNeeded: currentTx.syncIdNeededForCompletion,
-                lastSeenSyncId: this.lastSeenSyncId,
-                retryCount,
-                connectionState: this.isConnectedFn() ? 'connected' : 'disconnected',
-            });
-            if (retryCount < TransactionQueue.DELTA_MAX_RETRIES) {
-                // RETRY: Request reconciliation and re-schedule with exponential backoff
-                // The server already committed this mutation — we just need the delta to arrive
-                this.deltaConfirmationRetries.set(tx.id, retryCount + 1);
-                this.deltaConfirmationTimeouts.delete(tx.id);
-                // Exponential backoff: 30s → 60s → 120s → 120s → 120s (capped)
-                const nextTimeout = Math.min(timeoutMs * 2, TransactionQueue.DELTA_MAX_TIMEOUT_MS);
-                // Emit reconciliation request so SyncedStore can cycle the WebSocket
-                // to trigger delta catch-up from the server
-                this.emit('reconciliation:needed', {
-                    reason: 'delta_confirmation_timeout',
-                    txId: tx.id,
-                    model: tx.modelName,
-                    modelId: tx.modelId,
-                    syncIdNeeded: currentTx.syncIdNeededForCompletion,
-                    lastSeenSyncId: this.lastSeenSyncId,
-                    retryCount: retryCount + 1,
-                });
-                // Self-healing retry with backoff — the server already committed; we're
-                // just waiting on the delta. No consumer action → debug.
-                getContext().logger.debug('[TransactionQueue] Re-scheduling with backoff', {
-                    txId: tx.id.slice(0, 8),
-                    model: tx.modelName,
-                    nextTimeoutMs: nextTimeout,
-                    retry: retryCount + 1,
-                });
-                this.scheduleDeltaConfirmationTimeout(tx, nextTimeout);
-            }
-            else {
-                // LINEAR PATTERN: Retries exhausted — persist to IndexedDB instead of rolling back.
-                // The transaction succeeded on the server (HTTP 200), so the data exists server-side.
-                // Persist the awaiting state so it survives tab close. On next session, the WebSocket
-                // reconnect + delta catch-up will naturally confirm it (like Linear's IndexedDB caching).
-                this.deltaConfirmationRetries.delete(tx.id);
-                this.deltaConfirmationTimeouts.delete(tx.id);
-                getContext().observability.captureDeltaRetryExhausted({
-                    txId: tx.id,
-                    model: tx.modelName,
-                    modelId: tx.modelId,
-                    retryCount: TransactionQueue.DELTA_MAX_RETRIES,
-                    syncIdNeeded: currentTx.syncIdNeededForCompletion,
-                });
-                // Emit persist event — SyncClient handles the IDB write
-                this.emit('transaction:persist_awaiting', {
-                    txId: tx.id,
-                    model: tx.modelName,
-                    modelId: tx.modelId,
-                    operationType: tx.type,
-                    syncIdNeeded: currentTx.syncIdNeededForCompletion,
-                });
-                // Also request one final reconciliation cycle
-                this.emit('reconciliation:needed', {
-                    reason: 'delta_retries_exhausted',
-                    txId: tx.id,
-                    model: tx.modelName,
-                    modelId: tx.modelId,
-                    syncIdNeeded: currentTx.syncIdNeededForCompletion,
-                    lastSeenSyncId: this.lastSeenSyncId,
-                    retryCount: TransactionQueue.DELTA_MAX_RETRIES,
-                });
-            }
-        }, timeoutMs);
-        this.deltaConfirmationTimeouts.set(tx.id, timeoutHandle);
-    }
-    // Cancel a pending delta confirmation timeout and clean up retry tracking
-    cancelDeltaConfirmationTimeout(id) {
-        const timeoutHandle = this.deltaConfirmationTimeouts.get(id);
-        if (timeoutHandle) {
-            clearTimeout(timeoutHandle);
-            this.deltaConfirmationTimeouts.delete(id);
-        }
-        this.deltaConfirmationRetries.delete(id);
+        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) => {
@@ -1559,17 +1162,18 @@ 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))
@@ -1586,19 +1190,19 @@ export class TransactionQueue extends EventEmitter {
         };
         this.commitStore.set(clientTxId, tx);
         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.
+        // 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.emit('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)
@@ -1607,6 +1211,8 @@ export class TransactionQueue extends EventEmitter {
         try {
             while (this.commitLane.length > 0) {
                 const tx = this.commitLane[0];
+                if (!tx)
+                    break;
                 if (tx.status !== 'pending') {
                     this.commitLane.shift();
                     continue;
@@ -1629,8 +1235,9 @@ export class TransactionQueue extends EventEmitter {
                 catch (err) {
                     const error = err instanceof Error ? err : new Error(String(err));
                     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),
@@ -1642,8 +1249,9 @@ 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,
@@ -1659,10 +1267,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.
@@ -1705,20 +1313,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).
+     * 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.
      *
-     * 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.
+     * Transient (retried):
+     * - Network failures, connection errors, and timeouts.
+     * - Server errors (HTTP 5xx).
+     * - Rate limiting (HTTP 429).
      *
-     * Transient errors (will retry):
-     * - Network failures, connection errors, timeouts
-     * - Server errors (5xx status codes)
-     * - Rate limiting (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
@@ -1776,18 +1384,20 @@ export class TransactionQueue extends EventEmitter {
         return true;
     }
     /**
-     * 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 = {
@@ -1816,17 +1426,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.'
                     : '';
@@ -1862,15 +1471,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 {
@@ -1902,7 +1507,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;
@@ -1932,65 +1539,25 @@ export class TransactionQueue extends EventEmitter {
         }
     }
     /**
-     * Optimistic updates
+     * 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) {
-        this.optimisticUpdates.set(transaction.id, {
-            model,
-            previousState: null,
-            transaction,
-        });
-        this.emit('optimistic:create', { model, transaction });
+        applyOptimisticCreate(this.optimisticUpdates, this, model, transaction);
     }
     applyOptimisticUpdate(model, transaction) {
-        this.optimisticUpdates.set(transaction.id, {
-            model,
-            previousState: transaction.previousData,
-            transaction,
-        });
-        this.emit('optimistic:update', { model, transaction });
+        applyOptimisticUpdate(this.optimisticUpdates, this, model, transaction);
     }
     applyOptimisticDelete(model, transaction) {
-        this.optimisticUpdates.set(transaction.id, {
-            model,
-            previousState: transaction.previousData,
-            transaction,
-        });
-        this.emit('optimistic:delete', { model, transaction });
+        applyOptimisticDelete(this.optimisticUpdates, this, model, transaction);
     }
     async rollbackOptimistic(transaction, reason, error) {
-        const optimistic = this.optimisticUpdates.get(transaction.id);
-        if (!optimistic)
-            return;
-        this.emit('optimistic:rollback', {
-            model: optimistic.model,
-            previousState: optimistic.previousState,
-            transaction,
-            reason: reason ?? 'unknown',
-            error,
-        });
-        this.optimisticUpdates.delete(transaction.id);
-    }
-    /**
-     * 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);
-        }
+        await rollbackOptimistic(this.optimisticUpdates, this, transaction, reason, error);
     }
     /**
-     * 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)
@@ -1999,6 +1566,8 @@ export class TransactionQueue extends EventEmitter {
             const persisted = await database.getPersistedTransactions();
             for (const data of persisted) {
                 const transaction = this.deserializeTransaction(data);
+                if (!transaction)
+                    continue;
                 this.store.add(transaction);
                 this.enqueue(transaction);
             }
@@ -2010,11 +1579,35 @@ export class TransactionQueue extends EventEmitter {
             });
         }
     }
+    /**
+     * 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) {
-        return { ...data, status: 'pending' };
+        if (isNonReplayablePersistedRow(data))
+            return null;
+        const transaction = deserializePersistedTransaction(data);
+        if (!transaction) {
+            const rowId = typeof data === 'object' && data !== null && typeof data.id === 'string'
+                ? data.id
+                : undefined;
+            getContext().logger.debug('[TransactionQueue] Dropping malformed persisted transaction', {
+                rowId,
+            });
+            getContext().observability.captureTransactionFailure({
+                context: 'deserialize-persisted-transaction',
+                error: `Persisted transaction failed schema validation${rowId ? ` (id: ${rowId})` : ''}`,
+            });
+            return null;
+        }
+        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 = [];
@@ -2027,23 +1620,29 @@ export class TransactionQueue extends EventEmitter {
                 if (!transactionType || transaction.type === transactionType) {
                     cancelledTransactions.push(transaction);
                     this.store.updateStatus(transaction.id, 'rolled_back');
-                    this.rollbackOptimistic(transaction, 'model_cancelled');
+                    // Sync caller: a rejected rollback (throwing optimistic:rollback
+                    // listener) must surface, not vanish — the status flip above is
+                    // already committed either way.
+                    void this.rollbackOptimistic(transaction, 'model_cancelled').catch((error) => {
+                        getContext().observability.captureTransactionFailure({
+                            context: 'rollback-model-cancelled',
+                            error: error instanceof Error ? error : String(error),
+                        });
+                    });
                 }
             }
         }
         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;
@@ -2058,7 +1657,12 @@ export class TransactionQueue extends EventEmitter {
                 const fkValue = transaction.data?.[foreignKey];
                 if (fkValue === parentId) {
                     this.store.updateStatus(transaction.id, 'rolled_back');
-                    this.rollbackOptimistic(transaction, 'cascade_parent_deleted');
+                    void this.rollbackOptimistic(transaction, 'cascade_parent_deleted').catch((error) => {
+                        getContext().observability.captureTransactionFailure({
+                            context: 'rollback-cascade-parent-deleted',
+                            error: error instanceof Error ? error : String(error),
+                        });
+                    });
                     cancelled++;
                     getContext().logger.debug('[TransactionQueue] Cascade cancelled orphaned transaction', {
                         txId: transaction.id.slice(0, 12),
@@ -2072,14 +1676,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)}`;
     }
@@ -2095,35 +1697,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,
@@ -2137,8 +1730,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');
@@ -2168,18 +1761,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,
@@ -2189,7 +1781,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
@@ -2205,6 +1798,15 @@ export class TransactionQueue extends EventEmitter {
         if (this.processTimer) {
             clearTimeout(this.processTimer);
         }
+        // Clear every armed delta-confirmation timer (one per in-flight tx,
+        // 30–120s each) — a disposed queue must not keep the process alive or
+        // fire confirmation callbacks against the cleared store below.
+        this.deltaConfirmation.dispose();
+        // Clear the offline-grace timer armed by setConnectionState('disconnected').
+        if (this.commitOfflineGraceTimer !== null) {
+            clearTimeout(this.commitOfflineGraceTimer);
+            this.commitOfflineGraceTimer = null;
+        }
         // Clear store
         this.store.clear();
         this.optimisticUpdates.clear();