@abloatai/ablo 0.34.1 → 0.35.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 { getContext } 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
@@ -100,7 +100,7 @@ export class TransactionQueue extends EventEmitter {
             this.emit(event, payload);
         }
         catch (error) {
-            getContext().observability.captureTransactionFailure({
+            getContext().observability.captureMutationFailure({
                 context: `commit-lifecycle-listener:${event}`,
                 error: error instanceof Error ? error : String(error),
             });
@@ -114,8 +114,14 @@ 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.
+            getContext().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;
         }
     }
@@ -256,6 +262,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 +271,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 +294,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 +397,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 +444,7 @@ export class TransactionQueue extends EventEmitter {
             await this.commitOutbox.remove(commitEnvelopeRecordId(idempotencyKey));
         }
         catch (error) {
-            getContext().logger.debug('[TransactionQueue] Durable-write cleanup deferred', {
+            getContext().logger.debug('[MutationQueue] Durable-write cleanup deferred', {
                 idempotencyKey,
                 error: error instanceof Error ? error.message : String(error),
             });
@@ -489,6 +493,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 +653,13 @@ 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.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.
@@ -683,7 +716,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 +804,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)) });
+        getContext().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 +877,7 @@ export class TransactionQueue extends EventEmitter {
         this.batchIndex++;
         const currentBatchIndex = this.batchIndex;
         // Log batch commit for performance monitoring
-        getContext().logger.debug('[TransactionQueue] commitCreatedTransactions', {
+        getContext().logger.debug('[MutationQueue] commitCreatedTransactions', {
             count: this.createdTransactions.length,
             batchIndex: currentBatchIndex,
             types: this.createdTransactions.map((t) => `${t.type}:${t.modelName}`),
@@ -907,7 +940,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);
@@ -976,7 +1009,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 +1113,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 });
+            getContext().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 = {
@@ -1319,7 +1352,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', {
+            getContext().logger.debug('[MutationQueue] Backpressure: delaying batch, too many executing', {
                 executingCount: this.executingCount,
                 max: this.config.maxExecutingTransactions,
             });
@@ -1432,7 +1465,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);
@@ -1603,7 +1636,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', {
+                        getContext().logger.debug('[MutationQueue] Batch commit rejected', {
                             batchSize: batchOps.length,
                             models: batchOps.map(({ op }) => `${op.type}:${op.model}`),
                             errorType: abloErr?.type ?? error?.name,
@@ -1621,7 +1654,7 @@ export class TransactionQueue extends EventEmitter {
                             if (dispatchStarted) {
                                 await this.removeDurableCommit(commitIdempotencyKey);
                             }
-                            getContext().logger.info('[TransactionQueue] Graceful handling: entity already deleted', {
+                            getContext().logger.info('[MutationQueue] Graceful handling: entity already deleted', {
                                 batchSize: batchOps.length,
                             });
                             for (const { tx, op } of batchOps) {
@@ -1629,7 +1662,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', {
+                                    getContext().logger.debug('[MutationQueue] Orphaned transaction treated as success', {
                                         txId: tx.id.slice(0, 12),
                                         model: tx.modelName,
                                         type: op.type,
@@ -1834,13 +1867,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 +1902,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 +1916,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 +1979,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 +1989,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 +2018,7 @@ export class TransactionQueue extends EventEmitter {
                         }
                         else {
                             this.scheduleReplicationLagTimeout(tx.id, tx.id, result.correlationId);
-                            getContext().logger.debug('[TransactionQueue] commit lane awaiting source echo', {
+                            getContext().logger.debug('[MutationQueue] commit lane awaiting source echo', {
                                 txId: tx.id.slice(0, 12),
                             });
                         }
@@ -2012,14 +2039,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', {
+                        getContext().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 +2072,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', {
+                    getContext().logger.debug('[MutationQueue] commit lane permanent error', {
                         txId: tx.id.slice(0, 12),
                         attempts: tx.attempts,
                         message: error.message,
@@ -2256,7 +2298,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 +2440,7 @@ export class TransactionQueue extends EventEmitter {
             }
         }
         catch (error) {
-            getContext().observability.captureTransactionFailure({
+            getContext().observability.captureMutationFailure({
                 context: 'load-persisted-transactions',
                 error: error instanceof Error ? error : String(error),
             });
@@ -2419,7 +2471,7 @@ export class TransactionQueue extends EventEmitter {
                 }
                 else {
                     getContext().logger.warn('A saved local write is unreadable and was held for review.');
-                    getContext().observability.captureTransactionFailure({
+                    getContext().observability.captureMutationFailure({
                         context: 'restore-commit-envelope',
                         error: parsed.error,
                     });
@@ -2435,9 +2487,9 @@ export class TransactionQueue extends EventEmitter {
                 }
                 if (envelope.acceptedAt === undefined &&
                     Date.now() - envelope.sealedAt >=
-                        TransactionQueue.DURABLE_REPLAY_WINDOW_MS) {
+                        MutationQueue.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({
+                    getContext().observability.captureMutationFailure({
                         context: 'quarantine-expired-commit-envelope',
                         error: `Envelope ${envelope.idempotencyKey} is too old to replay safely`,
                     });
@@ -2457,7 +2509,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 +2533,10 @@ export class TransactionQueue extends EventEmitter {
                 void this.processCommitLane();
         }
         catch (error) {
-            getContext().logger.debug('[TransactionQueue] Failed to restore durable writes', {
+            getContext().logger.debug('[MutationQueue] Failed to restore durable writes', {
                 error: error instanceof Error ? error.message : String(error),
             });
-            getContext().observability.captureTransactionFailure({
+            getContext().observability.captureMutationFailure({
                 context: 'restore-commit-envelopes',
                 error: error instanceof Error ? error : String(error),
             });
@@ -2507,10 +2558,10 @@ export class TransactionQueue extends EventEmitter {
             const rowId = typeof data === 'object' && data !== null && typeof data.id === 'string'
                 ? data.id
                 : undefined;
-            getContext().logger.debug('[TransactionQueue] Dropping malformed persisted transaction', {
+            getContext().logger.debug('[MutationQueue] Dropping malformed persisted transaction', {
                 rowId,
             });
-            getContext().observability.captureTransactionFailure({
+            getContext().observability.captureMutationFailure({
                 context: 'deserialize-persisted-transaction',
                 error: `Persisted transaction failed schema validation${rowId ? ` (id: ${rowId})` : ''}`,
             });
@@ -2538,7 +2589,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({
+                        getContext().observability.captureMutationFailure({
                             context: 'rollback-model-cancelled',
                             error: error instanceof Error ? error : String(error),
                         });
@@ -2553,8 +2604,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 +2623,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({
+                        getContext().observability.captureMutationFailure({
                             context: 'rollback-cascade-parent-deleted',
                             error: error instanceof Error ? error : String(error),
                         });
                     });
                     cancelled++;
-                    getContext().logger.debug('[TransactionQueue] Cascade cancelled orphaned transaction', {
+                    getContext().logger.debug('[MutationQueue] Cascade cancelled orphaned transaction', {
                         txId: transaction.id.slice(0, 12),
                         model: childModelName,
                         foreignKey,
@@ -2624,7 +2675,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() : [])];

package/dist/transactions/{TransactionStore.d.ts → mutations/MutationStore.d.ts}

@@ -3,18 +3,18 @@
  * The status index keeps the queue's hot paths — such as `getByStatus('pending')`
  * on every batch and coalesce decision — proportional to the number of
  * transactions in that status rather than the total across all statuses.
- * {@link TransactionQueue} owns an instance and routes every status change
+ * {@link MutationQueue} owns an instance and routes every status change
  * through {@link updateStatus}, which keeps the two indexes consistent.
  */
-import type { Transaction } from './commitPayload.js';
-export declare class TransactionStore {
+import type { QueuedMutation } from './commitPayload.js';
+export declare class MutationStore {
     private transactions;
     private byStatus;
-    add(transaction: Transaction): void;
-    get(id: string): Transaction | undefined;
-    updateStatus(id: string, newStatus: Transaction['status']): void;
-    getByStatus(status: Transaction['status']): Transaction[];
+    add(transaction: QueuedMutation): void;
+    get(id: string): QueuedMutation | undefined;
+    updateStatus(id: string, newStatus: QueuedMutation['status']): void;
+    getByStatus(status: QueuedMutation['status']): QueuedMutation[];
     remove(id: string): void;
     clear(): void;
-    getAll(): Transaction[];
+    getAll(): QueuedMutation[];
 }

package/dist/transactions/{TransactionStore.js → mutations/MutationStore.js}

@@ -3,10 +3,10 @@
  * The status index keeps the queue's hot paths — such as `getByStatus('pending')`
  * on every batch and coalesce decision — proportional to the number of
  * transactions in that status rather than the total across all statuses.
- * {@link TransactionQueue} owns an instance and routes every status change
+ * {@link MutationQueue} owns an instance and routes every status change
  * through {@link updateStatus}, which keeps the two indexes consistent.
  */
-export class TransactionStore {
+export class MutationStore {
     transactions = new Map();
     byStatus = new Map();
     add(transaction) {

package/dist/transactions/{coalesceRules.d.ts → mutations/coalesceRules.d.ts}

@@ -1,6 +1,6 @@
 /**
  * The queue's rules for coalescing operations that touch the same row, so their
- * causal order is preserved. {@link TransactionQueue} calls into these through a
+ * causal order is preserved. {@link MutationQueue} calls into these through a
  * small store-shaped interface:
  *
  *   - Create-then-delete cancellation ({@link takeUnsentCreateForModel}):
@@ -16,11 +16,11 @@
  * The queue keeps the `enqueue` and `delete` methods that orchestrate optimistic
  * state and events; these functions hold only the coalescing rules.
  */
-import type { MutationInput, Transaction } from './commitPayload.js';
-/** The subset of {@link TransactionStore} that the coalescing rules read. */
-export interface TransactionStoreLike {
-    get(id: string): Transaction | undefined;
-    getByStatus(status: Transaction['status']): Transaction[];
+import type { MutationInput, QueuedMutation } from './commitPayload.js';
+/** The subset of {@link MutationStore} that the coalescing rules read. */
+export interface MutationStoreLike {
+    get(id: string): QueuedMutation | undefined;
+    getByStatus(status: QueuedMutation['status']): QueuedMutation[];
 }
 export declare const entityKey: (modelName: string, modelId: string) => string;
 /**
@@ -30,25 +30,25 @@ export declare const entityKey: (modelName: string, modelId: string) => string;
  * held it, so the caller can cancel it rather than send a create followed by a
  * delete.
  */
-export declare function takeUnsentCreateForModel(staged: Transaction[], queued: Transaction[], store: Pick<TransactionStoreLike, 'getByStatus'>, modelName: string, modelId: string): Transaction | undefined;
+export declare function takeUnsentCreateForModel(staged: QueuedMutation[], queued: QueuedMutation[], store: Pick<MutationStoreLike, 'getByStatus'>, modelName: string, modelId: string): QueuedMutation | undefined;
 /**
  * Returns the most recent in-flight create for the given model and id that a
  * delete must wait behind, or undefined if there is none. A pending create that
  * has never been attempted is not a barrier, because it can be cancelled
  * instead; once a create has been sent, even a retry-pending one is a barrier.
  */
-export declare function findCreateBarrierForDelete(store: Pick<TransactionStoreLike, 'getByStatus'>, modelName: string, modelId: string): Transaction | undefined;
+export declare function findCreateBarrierForDelete(store: Pick<MutationStoreLike, 'getByStatus'>, modelName: string, modelId: string): QueuedMutation | undefined;
 /**
  * Parks a delete until the create for the same row settles, keyed by the
  * create's model and id. {@link releaseDeferredDeletesForCreate} re-enqueues
  * the parked deletes once that create completes.
  */
-export declare function deferDeleteUntilCreateSettles(deferredDeletesByCreate: Map<string, Transaction[]>, createTransaction: Transaction, deleteTransaction: Transaction): void;
+export declare function deferDeleteUntilCreateSettles(deferredDeletesByCreate: Map<string, QueuedMutation[]>, createTransaction: QueuedMutation, deleteTransaction: QueuedMutation): void;
 /**
  * Re-enqueues the deletes parked behind a create once that create settles,
  * skipping any whose status is no longer pending.
  */
-export declare function releaseDeferredDeletesForCreate(deferredDeletesByCreate: Map<string, Transaction[]>, store: Pick<TransactionStoreLike, 'get'>, enqueue: (transaction: Transaction) => void, createTransaction: Transaction): void;
+export declare function releaseDeferredDeletesForCreate(deferredDeletesByCreate: Map<string, QueuedMutation[]>, store: Pick<MutationStoreLike, 'get'>, enqueue: (transaction: QueuedMutation) => void, createTransaction: QueuedMutation): void;
 /**
  * Merges two update payloads for the same row into one. Later values win, with
  * one exception: a `metadata` field is deep-merged as an object — parsing it

package/dist/transactions/{coalesceRules.js → mutations/coalesceRules.js}

@@ -1,6 +1,6 @@
 /**
  * The queue's rules for coalescing operations that touch the same row, so their
- * causal order is preserved. {@link TransactionQueue} calls into these through a
+ * causal order is preserved. {@link MutationQueue} calls into these through a
  * small store-shaped interface:
  *
  *   - Create-then-delete cancellation ({@link takeUnsentCreateForModel}):

package/dist/transactions/mutations/commitLatency.d.ts

@@ -0,0 +1,52 @@
+/**
+ * Commit latency — how long a user's edit actually takes to land.
+ *
+ * The engine has never measured this. HUDs and dashboards reach for
+ * `window.fetch` timings, which the sync engine's WebSocket never touches, so
+ * the latency a user sees reported while editing has had nothing to do with
+ * the writes they are making. This module closes that gap without adding a
+ * single timestamp to the hot path: `MutationQueue` already emits the commit
+ * lifecycle, and the events already carry the correlation key.
+ *
+ * Three events, two intervals:
+ *
+ *   commit:staging ──sealMs──▶ commit:created ──ackMs──▶ transaction:completed
+ *
+ *  - `sealMs` is **local** — writing the durable envelope before the commit is
+ *    allowed onto the wire. Slow here means storage (IndexedDB), not network.
+ *  - `ackMs` is **remote** — dispatch, round-trip, and server work. For a
+ *    commit routed at a connected source this also spans the wait for the
+ *    correlated echo that promotes `queued` to `confirmed`, so it answers
+ *    "when did my edit become real" rather than raw socket round-trip. Read a
+ *    large `ackMs` against a small `sealMs` as a network or replication cost.
+ *
+ * Correlation is by `clientTxId`: `MutationQueue` uses it as the transaction
+ * id verbatim, so the staging event and the completion event share one key.
+ */
+/**
+ * The slice of an event emitter this module needs. Declared structurally so a
+ * plain object can stand in under test — `MutationQueue` satisfies it by
+ * extending `EventEmitter`.
+ */
+export interface CommitEventSource {
+    on(event: string, listener: (payload: unknown) => void): unknown;
+    off(event: string, listener: (payload: unknown) => void): unknown;
+}
+/** One completed commit, broken into its local and remote halves. */
+export interface CommitLatencySample {
+    /** The commit's `clientTxId`, identical to its transaction id. */
+    clientTxId: string;
+    /** Milliseconds sealing the durable envelope locally. */
+    sealMs: number;
+    /** Milliseconds from sealed envelope to acknowledgement. */
+    ackMs: number;
+    /** Milliseconds from staging to acknowledgement — `sealMs + ackMs`. */
+    totalMs: number;
+}
+/**
+ * Pair commit lifecycle events into latency samples. Returns an unsubscribe
+ * function that also drops any still-pending timings.
+ *
+ * `onSample` fires once per commit that completes, in completion order.
+ */
+export declare function observeCommitLatency(source: CommitEventSource, onSample: (sample: CommitLatencySample) => void): () => void;