@abloatai/ablo 0.34.1 → 0.36.0

package/dist/transactions/{TransactionQueue.js → mutations/MutationQueue.js}

@@ -1,5 +1,5 @@
 /**
- * TransactionQueue manages the lifecycle of local writes on their way to the
+ * MutationQueue 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.
@@ -13,25 +13,25 @@
  */
 import { EventEmitter } from 'events';
 import { v4 as uuid } from 'uuid';
-import { Model } from '../Model.js';
-import { getContext } from '../context.js';
-import { AbloError, AbloConnectionError, AbloIdempotencyError, AbloNotFoundError, AbloValidationError, errorCodeSpec, } from '../errors.js';
-import { SyncPosition } from '../sync/syncPosition.js';
-import { mutationCommitResultSchema, } from '../wire/commit.js';
+import { Model } from '../../Model.js';
+import { globalRuntime } from '../../context.js';
+import { AbloError, AbloConnectionError, AbloIdempotencyError, AbloNotFoundError, AbloValidationError, errorCodeSpec, } from '../../transaction/errors.js';
+import { LogPosition } from '../../transaction/logPosition.js';
+import { mutationCommitResultSchema, } from '../../transaction/wire/commit.js';
 import { projectCommitPayload, computePriorityScore, normalizeModelKey, 
 // Includes stale guards as well as request identity/audit barriers.
 hasCommitCoalescingBarrier, applyWriteOptions, asTransportError, extractStatusCode, TX_TYPE_TO_MUTATION_OP, } from './commitPayload.js';
-import { TransactionStore } from './TransactionStore.js';
+import { MutationStore } from './MutationStore.js';
 import { entityKey, mergeUpdateData, takeUnsentCreateForModel, findCreateBarrierForDelete, deferDeleteUntilCreateSettles, releaseDeferredDeletesForCreate, } from './coalesceRules.js';
 import { DeltaConfirmationTracker } from './deltaConfirmation.js';
 import { deserializePersistedTransaction, isNonReplayablePersistedRow, pendingMutationRecordId, } from './replayValidation.js';
-import { createCommitEnvelopeMember, createDurableCommitEnvelope, commitEnvelopeRecordId, durableCommitEnvelopeSchema, } from './commitEnvelope.js';
-import { stableStringify } from '../utils/json.js';
+import { createCommitEnvelopeMember, createDurableCommitEnvelope, commitEnvelopeRecordId, durableCommitEnvelopeSchema, } from '../../transaction/transactions/settlement/commitEnvelope.js';
+import { stableStringify } from '../../transaction/utils/json.js';
 import { applyOptimisticCreate, applyOptimisticUpdate, applyOptimisticDelete, rollbackOptimistic, } from './optimisticApply.js';
-export class TransactionQueue extends EventEmitter {
+export class MutationQueue extends EventEmitter {
     // Keep one hour of clock/network margin inside the server's 24-hour ledger.
     static DURABLE_REPLAY_WINDOW_MS = 23 * 60 * 60 * 1000;
-    store = new TransactionStore();
+    store = new MutationStore();
     // Signature of the last permanent-error we logged at `warn`. A `create`
     // whose id already exists (`unique_violation`) is a permanent rejection
     // that the offline queue re-drives on every reconnect/bootstrap — without
@@ -51,8 +51,9 @@ export class TransactionQueue extends EventEmitter {
     // queue treats as transient and retries endlessly.
     _mutationExecutor = null;
     get mutationExecutor() {
-        return this._mutationExecutor ?? getContext().mutationExecutor;
+        return this._mutationExecutor ?? this.runtime.mutationExecutor;
     }
+    runtime;
     executionQueue = [];
     isProcessing = false;
     processTimer;
@@ -100,7 +101,7 @@ export class TransactionQueue extends EventEmitter {
             this.emit(event, payload);
         }
         catch (error) {
-            getContext().observability.captureTransactionFailure({
+            this.runtime.observability.captureMutationFailure({
                 context: `commit-lifecycle-listener:${event}`,
                 error: error instanceof Error ? error : String(error),
             });
@@ -114,13 +115,19 @@ export class TransactionQueue extends EventEmitter {
         this.assertDurableReplayOpen();
         if (envelope.acceptedAt === undefined &&
             Date.now() - envelope.sealedAt >=
-                TransactionQueue.DURABLE_REPLAY_WINDOW_MS) {
+                MutationQueue.DURABLE_REPLAY_WINDOW_MS) {
             this.durableReplayBlock = new AbloIdempotencyError('A pending commit is older than the server idempotency window; newer writes are blocked until it is reviewed.', { code: 'idempotency_conflict' });
+            // This gate stops EVERY subsequent write on this client, and each of
+            // those rejections is captured to observability rather than surfaced to
+            // the caller — without this line the session degrades into "nothing
+            // saves and nothing errors". One loud line at the moment the block
+            // engages is the only visible trace.
+            this.runtime.logger.warn('sync paused: a saved write from an earlier session is older than the server replay window, so newer writes are held until it is reviewed', { sealedAt: envelope.sealedAt });
             throw this.durableReplayBlock;
         }
     }
     computePriorityScore(type, modelName) {
-        return computePriorityScore(type, modelName);
+        return computePriorityScore(type, modelName, this.runtime);
     }
     ensureDerivedFields(transaction) {
         if (!transaction.modelKey) {
@@ -256,6 +263,7 @@ export class TransactionQueue extends EventEmitter {
         deltaConfirmationTimeout: 30000,
         retryBackoff: { baseMs: 200, capMs: 1500 },
         commitOfflineGraceMs: 30_000,
+        commitDispatchTimeoutMs: 30_000,
     };
     // Track executing transactions for backpressure
     executingCount = 0;
@@ -264,7 +272,7 @@ export class TransactionQueue extends EventEmitter {
     // completion paths, `getStats`, and `dispose` all read it.
     optimisticUpdates = new Map();
     // Stale-context notifications, keyed by transaction id. When the server
-    // accepts a commit but reports that an operation's read premise had moved,
+    // accepts a commit but reports that an operation's 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();
@@ -287,7 +295,7 @@ export class TransactionQueue extends EventEmitter {
      * 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.
+     * `readFloor`. See `../logPosition.js` for the full contract.
      */
     position;
     /** Applied-cursor alias, kept so the many internal read sites stay legible. */
@@ -390,9 +398,6 @@ export class TransactionQueue extends EventEmitter {
             operations: [...input.operations],
             sourceMutationIds,
             commitOptions: {
-                ...(input.commitOptions?.causedByTaskId !== undefined
-                    ? { causedByTaskId: input.commitOptions.causedByTaskId }
-                    : {}),
                 ...(input.commitOptions?.reads !== undefined
                     ? {
                         reads: input.commitOptions.reads === null
@@ -440,7 +445,7 @@ export class TransactionQueue extends EventEmitter {
             await this.commitOutbox.remove(commitEnvelopeRecordId(idempotencyKey));
         }
         catch (error) {
-            getContext().logger.debug('[TransactionQueue] Durable-write cleanup deferred', {
+            this.runtime.logger.debug('[MutationQueue] Durable-write cleanup deferred', {
                 idempotencyKey,
                 error: error instanceof Error ? error.message : String(error),
             });
@@ -489,6 +494,35 @@ export class TransactionQueue extends EventEmitter {
             return parsed.data;
         throw new AbloConnectionError('The mutation transport returned an invalid commit receipt; its outcome remains pending and is safe to retry.', { code: 'commit_no_result', cause: parsed.error });
     }
+    /**
+     * Dispatch a sealed envelope to the transport, bounded by
+     * `commitDispatchTimeoutMs`. Every executor call site routes through here:
+     * a transport that never answers must become a retryable no-receipt failure
+     * (the same class as a malformed receipt) instead of an eternally in-flight
+     * commit, because an unanswered commit holds the staged-batch lock and
+     * silently stalls every later write in the session. The abandoned commit's
+     * eventual result, if it ever arrives, is discarded; the retry re-sends the
+     * identical idempotency key, so the server deduplicates an already-applied
+     * write.
+     */
+    dispatchCommitBounded(...args) {
+        const timeoutMs = this.config.commitDispatchTimeoutMs;
+        const dispatched = this.mutationExecutor.commit(...args);
+        if (!Number.isFinite(timeoutMs) || timeoutMs <= 0)
+            return dispatched;
+        return new Promise((resolve, reject) => {
+            const timer = setTimeout(() => {
+                reject(new AbloConnectionError('The mutation transport did not acknowledge the commit in time; its outcome remains pending and is safe to retry.', { code: 'commit_no_result' }));
+            }, timeoutMs);
+            dispatched.then((value) => {
+                clearTimeout(timer);
+                resolve(value);
+            }, (error) => {
+                clearTimeout(timer);
+                reject(error instanceof Error ? error : new Error(String(error)));
+            });
+        });
+    }
     clearReplicationLagState(transactionId) {
         const timeout = this.replicationLagTimeouts.get(transactionId);
         if (timeout)
@@ -620,13 +654,14 @@ export class TransactionQueue extends EventEmitter {
      * Resolvers for per-transaction `confirmation` promises. Populated in
      * `attachConfirmation` at staging time, consumed by the constructor-time
      * listeners on `transaction:completed` / `transaction:failed`. Kept off
-     * the Transaction row so the store's iteration order stays plain-data
+     * the QueuedMutation row so the store's iteration order stays plain-data
      * and serialization-friendly.
      */
     confirmationResolvers = new Map();
     constructor(config) {
         super();
-        this.position = config?.position ?? new SyncPosition();
+        this.runtime = config?.runtime ?? globalRuntime;
+        this.position = config?.position ?? new LogPosition();
         // Bind the confirmation tracker to this queue's store/ledger/events.
         // `isConnected` closes over `isConnectedFn` so `setConnectionChecker`
         // swaps stay visible to in-flight timeouts.
@@ -638,6 +673,7 @@ export class TransactionQueue extends EventEmitter {
             },
             isConnected: () => this.isConnectedFn(),
             position: this.position,
+            runtime: this.runtime,
         });
         if (config) {
             this.config = { ...this.config, ...config };
@@ -683,7 +719,7 @@ export class TransactionQueue extends EventEmitter {
      * 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
+     * {@link QueuedMutation}: use this method at call sites that hold a model
      * returned by `ablo.<model>.create()` but never see the underlying
      * transaction.
      */
@@ -771,7 +807,7 @@ export class TransactionQueue extends EventEmitter {
             return;
         // 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)) });
+        this.runtime.logger.debug(`[MutationQueue] 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);
             if (!tx)
@@ -844,7 +880,7 @@ export class TransactionQueue extends EventEmitter {
         this.batchIndex++;
         const currentBatchIndex = this.batchIndex;
         // Log batch commit for performance monitoring
-        getContext().logger.debug('[TransactionQueue] commitCreatedTransactions', {
+        this.runtime.logger.debug('[MutationQueue] commitCreatedTransactions', {
             count: this.createdTransactions.length,
             batchIndex: currentBatchIndex,
             types: this.createdTransactions.map((t) => `${t.type}:${t.modelName}`),
@@ -907,7 +943,7 @@ export class TransactionQueue extends EventEmitter {
                     sequence: batch[0]?.commitEnvelope?.sequence,
                 });
                 this.assertEnvelopeInsideReplayWindow(durableEnvelope);
-                const result = this.parseMutationCommitResult(await this.mutationExecutor.commit(durableEnvelope.operations, {
+                const result = this.parseMutationCommitResult(await this.dispatchCommitBounded(durableEnvelope.operations, {
                     idempotencyKey,
                 }));
                 await this.persistDurableCommitAcceptance(durableEnvelope, result);
@@ -948,7 +984,7 @@ export class TransactionQueue extends EventEmitter {
                         this.optimisticUpdates.delete(tx.id);
                     }
                 }
-                getContext().logger.debug('txn:commit', 0, {
+                this.runtime.logger.debug('txn:commit', 0, {
                     count: batch.length,
                     lastSyncId: result.lastSyncId,
                 });
@@ -957,13 +993,13 @@ export class TransactionQueue extends EventEmitter {
             catch (err) {
                 // If one request fails, hand it and every later request back to the
                 // normal lane. Their envelopes stay attached for safe retry.
-                const isOffline = !getContext().onlineStatus.isOnline();
+                const isOffline = !this.runtime.onlineStatus.isOnline();
                 const isNetworkError = err instanceof Error &&
                     (err.message.includes('Failed to fetch') ||
                         err.message.includes('Network request failed') ||
                         err.message.includes('NetworkError'));
                 if (!isOffline || !isNetworkError) {
-                    getContext().observability.breadcrumb('Batch flush fallback failed', 'sync.transaction', 'warning', {
+                    this.runtime.observability.breadcrumb('Batch flush fallback failed', 'sync.transaction', 'warning', {
                         error: err instanceof Error ? err.message : String(err),
                     });
                 }
@@ -976,7 +1012,7 @@ export class TransactionQueue extends EventEmitter {
     }
     /**
      * Records a create and applies it optimistically, then stages it for the next
-     * batched commit. Returns the {@link Transaction}, whose `confirmation`
+     * batched commit. Returns the {@link QueuedMutation}, whose `confirmation`
      * promise settles once the server confirms the write.
      */
     async create(model, context, writeOptions, sourceMutationId) {
@@ -1080,7 +1116,7 @@ export class TransactionQueue extends EventEmitter {
         const actualModelName = model.getModelName();
         // Skip Activity delete transactions - activities are permanent audit records
         if (actualModelName === 'Activity') {
-            getContext().logger.debug('TransactionQueue.delete() skipping Activity deletion - permanent audit records', { modelId: model.id });
+            this.runtime.logger.debug('MutationQueue.delete() skipping Activity deletion - permanent audit records', { modelId: model.id });
             const modelKey = normalizeModelKey(actualModelName);
             const priorityScore = this.computePriorityScore('delete', actualModelName);
             const mockTransaction = {
@@ -1147,7 +1183,14 @@ export class TransactionQueue extends EventEmitter {
         transaction.sourceMutationIds = [
             ...new Set([
                 ...(transaction.sourceMutationIds ?? []),
-                ...canceledUpdates.flatMap((candidate) => candidate.sourceMutationIds ?? []),
+                // Absorb journal sources only from updates that never sealed an
+                // envelope. A sealed update's seal already CONSUMED its journal rows
+                // — they belong to that envelope forever — so listing them here
+                // poisons this delete's own seal: the new-envelope guard finds its
+                // sources missing, rejects with `idempotency_conflict`, and the
+                // optimistic delete reverts. That was a user-visible lost delete
+                // (edit a layer, then delete it while the edit was on the wire).
+                ...canceledUpdates.flatMap((candidate) => candidate.commitEnvelope ? [] : (candidate.sourceMutationIds ?? [])),
                 ...(pendingMerge?.sourceMutationIds ?? []),
             ]),
         ];
@@ -1319,7 +1362,7 @@ export class TransactionQueue extends EventEmitter {
         // 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', {
+            this.runtime.logger.debug('[MutationQueue] Backpressure: delaying batch, too many executing', {
                 executingCount: this.executingCount,
                 max: this.config.maxExecutingTransactions,
             });
@@ -1360,7 +1403,7 @@ export class TransactionQueue extends EventEmitter {
         this.isProcessing = true;
         // Declare batch outside try so it's accessible in finally for backpressure tracking
         let batch = [];
-        await getContext().observability.startSpanAsync('sync.batch', 'sync.transaction.batch', async () => {
+        await this.runtime.observability.startSpanAsync('sync.batch', 'sync.transaction.batch', async () => {
             try {
                 // Sort the execution queue by foreign-key priority before selecting a
                 // batch, so a parent row is always committed before its children, even
@@ -1432,7 +1475,7 @@ export class TransactionQueue extends EventEmitter {
                         // the exact key assigned before the first transport attempt.
                         this.assertEnvelopeInsideReplayWindow(durableEnvelope);
                         dispatchStarted = true;
-                        const result = this.parseMutationCommitResult(await this.mutationExecutor.commit(operations, {
+                        const result = this.parseMutationCommitResult(await this.dispatchCommitBounded(operations, {
                             idempotencyKey: commitIdempotencyKey,
                         }));
                         await this.persistDurableCommitAcceptance(durableEnvelope, result);
@@ -1496,7 +1539,7 @@ export class TransactionQueue extends EventEmitter {
                                 }
                                 this.store.updateStatus(tx.id, 'awaiting_delta');
                                 this.scheduleReplicationLagTimeout(tx.id, commitIdempotencyKey, result.correlationId);
-                                getContext().logger.debug('tx:awaiting_delta', {
+                                this.runtime.logger.debug('tx:awaiting_delta', {
                                     txId: tx.id.slice(0, 8),
                                     model: tx.modelName,
                                     reason: 'queued_forward_waiting_for_correlated_echo',
@@ -1514,7 +1557,7 @@ export class TransactionQueue extends EventEmitter {
                             // 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({
+                                this.runtime.observability.captureCommitZeroSyncId({
                                     operationCount: operations.length,
                                     operations: operations.map((op) => `${op.type}:${op.model}:${op.id?.slice(0, 8) ?? '?'}`),
                                 });
@@ -1532,7 +1575,7 @@ export class TransactionQueue extends EventEmitter {
                                     this.emit('transaction:completed', tx);
                                     this.emit(`transaction:completed:${tx.id}`, tx);
                                     this.optimisticUpdates.delete(tx.id);
-                                    getContext().logger.debug('tx:confirm_delete_zero_syncid', {
+                                    this.runtime.logger.debug('tx:confirm_delete_zero_syncid', {
                                         txId: tx.id.slice(0, 8),
                                         model: tx.modelName,
                                         reason: 'delete_idempotent_no_delta',
@@ -1547,7 +1590,7 @@ export class TransactionQueue extends EventEmitter {
                                     this.emit('transaction:completed', tx);
                                     this.emit(`transaction:completed:${tx.id}`, tx);
                                     this.optimisticUpdates.delete(tx.id);
-                                    getContext().logger.debug('tx:confirm_ack', {
+                                    this.runtime.logger.debug('tx:confirm_ack', {
                                         txId: tx.id.slice(0, 8),
                                         model: tx.modelName,
                                         serverSyncId: lastSyncId,
@@ -1556,7 +1599,7 @@ export class TransactionQueue extends EventEmitter {
                                 }
                                 else {
                                     this.store.updateStatus(tx.id, 'awaiting_delta');
-                                    getContext().logger.debug('tx:awaiting_delta', {
+                                    this.runtime.logger.debug('tx:awaiting_delta', {
                                         txId: tx.id.slice(0, 8),
                                         model: tx.modelName,
                                         neededSyncId: lastSyncId,
@@ -1603,7 +1646,7 @@ export class TransactionQueue extends EventEmitter {
                         // authoritative `warn` with the same typed cause) — passes
                         // through here. Logging it at `warn` made one rejected write
                         // surface three identical dumps; keep it at `debug`.
-                        getContext().logger.debug('[TransactionQueue] Batch commit rejected', {
+                        this.runtime.logger.debug('[MutationQueue] Batch commit rejected', {
                             batchSize: batchOps.length,
                             models: batchOps.map(({ op }) => `${op.type}:${op.model}`),
                             errorType: abloErr?.type ?? error?.name,
@@ -1621,7 +1664,7 @@ export class TransactionQueue extends EventEmitter {
                             if (dispatchStarted) {
                                 await this.removeDurableCommit(commitIdempotencyKey);
                             }
-                            getContext().logger.info('[TransactionQueue] Graceful handling: entity already deleted', {
+                            this.runtime.logger.info('[MutationQueue] Graceful handling: entity already deleted', {
                                 batchSize: batchOps.length,
                             });
                             for (const { tx, op } of batchOps) {
@@ -1629,7 +1672,7 @@ export class TransactionQueue extends EventEmitter {
                                     // 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', {
+                                    this.runtime.logger.debug('[MutationQueue] Orphaned transaction treated as success', {
                                         txId: tx.id.slice(0, 12),
                                         model: tx.modelName,
                                         type: op.type,
@@ -1689,7 +1732,7 @@ export class TransactionQueue extends EventEmitter {
                     this.scheduleProcessing(true);
                 }
                 const batchEnd = typeof performance !== 'undefined' ? performance.now() : Date.now();
-                getContext().logger.debug('txn:batch', batchEnd - batchStart, {
+                this.runtime.logger.debug('txn:batch', batchEnd - batchStart, {
                     maxBatchSize: this.config.maxBatchSize,
                     remaining: this.executionQueue.length,
                     executingCount: this.executingCount,
@@ -1834,13 +1877,11 @@ export class TransactionQueue extends EventEmitter {
             await existing.sealPromise;
             const existingIntent = stableStringify({
                 operations: existing.operations,
-                causedByTaskId: existing.causedByTaskId ?? null,
                 reads: existing.reads ?? null,
                 track: existing.track ?? null,
             });
             const incomingIntent = stableStringify({
                 operations,
-                causedByTaskId: options.causedByTaskId ?? null,
                 reads: options.reads ?? null,
                 track: options.track ?? null,
             });
@@ -1871,7 +1912,6 @@ export class TransactionQueue extends EventEmitter {
             id: clientTxId,
             kind: 'commit',
             operations: [...operations],
-            causedByTaskId: options.causedByTaskId ?? null,
             ...(options.reads ? { reads: options.reads } : {}),
             ...(options.track ? { track: options.track } : {}),
             status: 'pending',
@@ -1886,7 +1926,6 @@ export class TransactionQueue extends EventEmitter {
             origin: 'atomic_commit',
             operations: tx.operations,
             commitOptions: {
-                causedByTaskId: tx.causedByTaskId ?? null,
                 ...(tx.reads ? { reads: tx.reads } : {}),
                 ...(tx.track ? { track: tx.track } : {}),
             },
@@ -1950,7 +1989,6 @@ export class TransactionQueue extends EventEmitter {
                             operations: tx.operations,
                             sourceMutationIds: tx.sourceMutationIds,
                             commitOptions: {
-                                causedByTaskId: tx.causedByTaskId ?? null,
                                 ...(tx.reads ? { reads: tx.reads } : {}),
                                 ...(tx.track ? { track: tx.track } : {}),
                             },
@@ -1961,9 +1999,8 @@ export class TransactionQueue extends EventEmitter {
                     tx.durableEnvelope = durableEnvelope;
                     this.assertEnvelopeInsideReplayWindow(durableEnvelope);
                     dispatchStarted = true;
-                    const result = this.parseMutationCommitResult(await this.mutationExecutor.commit(durableEnvelope.operations, {
+                    const result = this.parseMutationCommitResult(await this.dispatchCommitBounded(durableEnvelope.operations, {
                         idempotencyKey: tx.id,
-                        causedByTaskId: durableEnvelope.commitOptions.causedByTaskId ?? undefined,
                         ...(durableEnvelope.commitOptions.reads
                             ? { reads: durableEnvelope.commitOptions.reads }
                             : {}),
@@ -1991,7 +2028,7 @@ export class TransactionQueue extends EventEmitter {
                         }
                         else {
                             this.scheduleReplicationLagTimeout(tx.id, tx.id, result.correlationId);
-                            getContext().logger.debug('[TransactionQueue] commit lane awaiting source echo', {
+                            this.runtime.logger.debug('[MutationQueue] commit lane awaiting source echo', {
                                 txId: tx.id.slice(0, 12),
                             });
                         }
@@ -2012,14 +2049,29 @@ export class TransactionQueue extends EventEmitter {
                     if (dispatchStarted && this.isDefinitiveRejection(error)) {
                         await this.removeDurableCommit(tx.id);
                     }
-                    if (!this.isPermanentError(error)) {
+                    // A transport that is DOWN is not a failing write: the envelope is
+                    // meant to wait for reconnect, which is what makes a commit survive a
+                    // dropped connection. A transient error the SERVER keeps returning is
+                    // a different thing, and this lane has no attempt bound of its own —
+                    // so a 5xx carrying no wire code reads as transient on every kick,
+                    // sits at the head of the lane, and `waitForCommitReceipt` never
+                    // settles. The caller sees a write that neither lands nor fails.
+                    //
+                    // Counting only the non-connection failures keeps offline waiting
+                    // unbounded while giving a repeating server rejection an end.
+                    if (!(error instanceof AbloConnectionError)) {
+                        tx.transientAttempts = (tx.transientAttempts ?? 0) + 1;
+                    }
+                    const exhausted = (tx.transientAttempts ?? 0) > this.config.maxRetries;
+                    if (!this.isPermanentError(error) && !exhausted) {
                         // 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', {
+                        this.runtime.logger.debug('[MutationQueue] commit lane transient', {
                             txId: tx.id.slice(0, 12),
                             attempts: tx.attempts,
+                            transientAttempts: tx.transientAttempts ?? 0,
                             message: error.message,
                         });
                         break;
@@ -2030,7 +2082,7 @@ export class TransactionQueue extends EventEmitter {
                     // 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', {
+                    this.runtime.logger.debug('[MutationQueue] commit lane permanent error', {
                         txId: tx.id.slice(0, 12),
                         attempts: tx.attempts,
                         message: error.message,
@@ -2240,7 +2292,7 @@ export class TransactionQueue extends EventEmitter {
                 const sig = `${details.type}:${details.model}:${details.modelId}:${details.errorCode ?? details.errorType}`;
                 const isRepeat = sig === this.lastPermanentErrorSig;
                 this.lastPermanentErrorSig = sig;
-                const logger = getContext().logger;
+                const logger = this.runtime.logger;
                 // 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):
@@ -2256,7 +2308,17 @@ export class TransactionQueue extends EventEmitter {
                     : '';
                 const reason = abloErr?.message ? ` — ${abloErr.message}` : '';
                 const code = abloErr?.code ? ` (code: ${abloErr.code})` : '';
-                const headline = `Your ${transaction.type} to "${transaction.modelName}" was not saved${reason}${code}.${revertNote}`;
+                // An optimistic write resolves before the server answers, so a later
+                // rejection has no caller left to return to and this log is the only
+                // place it appears. That reads to an application developer as their own
+                // save silently failing — the write showed, then vanished — and sends
+                // them into their editor instead of here. Name the subscription that
+                // hands them the same typed error, so the application can say what
+                // happened rather than only the console.
+                const channelNote = this.config.enableOptimistic
+                    ? ' To surface this in your app, subscribe with `ablo.onMutationFailure(…)`.'
+                    : '';
+                const headline = `Your ${transaction.type} to "${transaction.modelName}" was not saved${reason}${code}.${revertNote}${channelNote}`;
                 if (isRepeat) {
                     // Same write rejected for the same reason on each reconnect replay —
                     // log the forensics once, stay quiet after.
@@ -2388,7 +2450,7 @@ export class TransactionQueue extends EventEmitter {
             }
         }
         catch (error) {
-            getContext().observability.captureTransactionFailure({
+            this.runtime.observability.captureMutationFailure({
                 context: 'load-persisted-transactions',
                 error: error instanceof Error ? error : String(error),
             });
@@ -2418,8 +2480,8 @@ export class TransactionQueue extends EventEmitter {
                     envelopes.push(parsed.data);
                 }
                 else {
-                    getContext().logger.warn('A saved local write is unreadable and was held for review.');
-                    getContext().observability.captureTransactionFailure({
+                    this.runtime.logger.warn('A saved local write is unreadable and was held for review.');
+                    this.runtime.observability.captureMutationFailure({
                         context: 'restore-commit-envelope',
                         error: parsed.error,
                     });
@@ -2435,9 +2497,9 @@ export class TransactionQueue extends EventEmitter {
                 }
                 if (envelope.acceptedAt === undefined &&
                     Date.now() - envelope.sealedAt >=
-                        TransactionQueue.DURABLE_REPLAY_WINDOW_MS) {
-                    getContext().logger.warn('A saved local write is too old to retry safely and was held for review.');
-                    getContext().observability.captureTransactionFailure({
+                        MutationQueue.DURABLE_REPLAY_WINDOW_MS) {
+                    this.runtime.logger.warn('A saved local write is too old to retry safely and was held for review.');
+                    this.runtime.observability.captureMutationFailure({
                         context: 'quarantine-expired-commit-envelope',
                         error: `Envelope ${envelope.idempotencyKey} is too old to replay safely`,
                     });
@@ -2448,7 +2510,7 @@ export class TransactionQueue extends EventEmitter {
                         envelope.scope.organizationId !== this.commitOutboxScope.organizationId ||
                         envelope.scope.participantId !== this.commitOutboxScope.participantId ||
                         envelope.scope.namespace !== this.commitOutboxScope.namespace)) {
-                    getContext().logger.warn('A saved local write belongs to a different account or server and was held for review.');
+                    this.runtime.logger.warn('A saved local write belongs to a different account or server and was held for review.');
                     continue;
                 }
                 if (this.commitStore.has(envelope.idempotencyKey))
@@ -2457,7 +2519,6 @@ export class TransactionQueue extends EventEmitter {
                     id: envelope.idempotencyKey,
                     kind: 'commit',
                     operations: envelope.operations.map((operation) => ({ ...operation })),
-                    causedByTaskId: envelope.commitOptions.causedByTaskId ?? null,
                     ...(envelope.commitOptions.reads
                         ? { reads: [...envelope.commitOptions.reads] }
                         : {}),
@@ -2482,10 +2543,10 @@ export class TransactionQueue extends EventEmitter {
                 void this.processCommitLane();
         }
         catch (error) {
-            getContext().logger.debug('[TransactionQueue] Failed to restore durable writes', {
+            this.runtime.logger.debug('[MutationQueue] Failed to restore durable writes', {
                 error: error instanceof Error ? error.message : String(error),
             });
-            getContext().observability.captureTransactionFailure({
+            this.runtime.observability.captureMutationFailure({
                 context: 'restore-commit-envelopes',
                 error: error instanceof Error ? error : String(error),
             });
@@ -2502,15 +2563,15 @@ export class TransactionQueue extends EventEmitter {
     deserializeTransaction(data) {
         if (isNonReplayablePersistedRow(data))
             return null;
-        const transaction = deserializePersistedTransaction(data);
+        const transaction = deserializePersistedTransaction(data, this.runtime);
         if (!transaction) {
             const rowId = typeof data === 'object' && data !== null && typeof data.id === 'string'
                 ? data.id
                 : undefined;
-            getContext().logger.debug('[TransactionQueue] Dropping malformed persisted transaction', {
+            this.runtime.logger.debug('[MutationQueue] Dropping malformed persisted transaction', {
                 rowId,
             });
-            getContext().observability.captureTransactionFailure({
+            this.runtime.observability.captureMutationFailure({
                 context: 'deserialize-persisted-transaction',
                 error: `Persisted transaction failed schema validation${rowId ? ` (id: ${rowId})` : ''}`,
             });
@@ -2538,7 +2599,7 @@ export class TransactionQueue extends EventEmitter {
                     // 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({
+                        this.runtime.observability.captureMutationFailure({
                             context: 'rollback-model-cancelled',
                             error: error instanceof Error ? error : String(error),
                         });
@@ -2553,8 +2614,8 @@ export class TransactionQueue extends EventEmitter {
      * used to cascade a parent deletion. The caller supplies the foreign-key
      * relationship; this method performs the cancellation.
      *
-     * @param childModelName - The child model type (for example 'SlideLayer').
-     * @param foreignKey - The foreign-key property name (for example 'slideId').
+     * @param childModelName - The child model type (for example 'Block').
+     * @param foreignKey - The foreign-key property name (for example 'sectionId').
      * @param parentId - The deleted parent's id.
      * @returns The number of transactions cancelled.
      */
@@ -2572,13 +2633,13 @@ export class TransactionQueue extends EventEmitter {
                 if (fkValue === parentId) {
                     this.store.updateStatus(transaction.id, 'rolled_back');
                     void this.rollbackOptimistic(transaction, 'cascade_parent_deleted').catch((error) => {
-                        getContext().observability.captureTransactionFailure({
+                        this.runtime.observability.captureMutationFailure({
                             context: 'rollback-cascade-parent-deleted',
                             error: error instanceof Error ? error : String(error),
                         });
                     });
                     cancelled++;
-                    getContext().logger.debug('[TransactionQueue] Cascade cancelled orphaned transaction', {
+                    this.runtime.logger.debug('[MutationQueue] Cascade cancelled orphaned transaction', {
                         txId: transaction.id.slice(0, 12),
                         model: childModelName,
                         foreignKey,
@@ -2603,13 +2664,13 @@ export class TransactionQueue extends EventEmitter {
         return { ...(remote || {}), ...(local || {}) };
     }
     extractCreateData(model) {
-        return projectCommitPayload(model.getModelName(), model.toJSON(), { dropUndefined: false });
+        return projectCommitPayload(model.getModelName(), model.toJSON(), { dropUndefined: false }, this.runtime);
     }
     mapChangesToInput(modelName, changes) {
-        return projectCommitPayload(modelName, changes, { dropUndefined: true });
+        return projectCommitPayload(modelName, changes, { dropUndefined: true }, this.runtime);
     }
     extractUpdateData(model) {
-        return projectCommitPayload(model.getModelName(), model.getChanges(), { dropUndefined: true });
+        return projectCommitPayload(model.getModelName(), model.getChanges(), { dropUndefined: true }, this.runtime);
     }
     // Derive previous values for changed fields to support accurate rollback.
     // Model-specific special cases do not belong here; a model that needs to
@@ -2624,7 +2685,7 @@ export class TransactionQueue extends EventEmitter {
         // 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`.
+        // `RecordingMutation.snapshotFields`.
         const keys = updateInput
             ? Object.keys(updateInput)
             : [...(model.modifiedProperties instanceof Map ? model.modifiedProperties.keys() : [])];