@abloatai/ablo 0.34.0 → 0.35.0

package/dist/SyncClient.js

@@ -4,24 +4,26 @@
  * optimistic changes, holds them while the client is offline, sends them to
  * the server when connectivity returns, and resolves conflicts when the
  * server's version of a row disagrees with the local one. It sits between the
- * reactive object pool and the {@link TransactionQueue} that delivers writes
+ * reactive object pool and the {@link MutationQueue} that delivers writes
  * over the network.
  */
 import { runInAction } from 'mobx';
 import { v4 as uuid } from 'uuid';
 import { InstanceCache, ModelScope } from './InstanceCache.js';
 import { Model } from './Model.js';
+import { snapshotJsonValue } from './transaction/utils/json.js';
 // ModelRegistry instance accessed via this.objectPool.registry
-import { LoadStrategy } from './types/index.js';
+import { LoadStrategy } from './transaction/types/index.js';
 import { getContext } from './context.js';
-import { AbloAuthenticationError, AbloError, AbloValidationError } from './errors.js';
+import { AbloAuthenticationError, AbloError, AbloValidationError } from './transaction/errors.js';
 import { EventEmitter } from 'events';
 import { NetworkMonitor } from './NetworkMonitor.js';
-import { TransactionQueue } from './transactions/TransactionQueue.js';
-import { legacyPendingMutationRecordSchema, PENDING_MUTATION_REPLAY_WINDOW_MS, pendingMutationRecordId, pendingMutationRecordSchema, persistedMutationSchema, } from './transactions/replayValidation.js';
-import { UnconfirmedWrites, } from './transactions/UnconfirmedWrites.js';
-import { SyncPosition } from './sync/syncPosition.js';
-import { DatabaseCommitOutboxStore, } from './transactions/commitOutboxStore.js';
+import { MutationQueue } from './transactions/mutations/MutationQueue.js';
+import { observeCommitLatency, } from './transactions/mutations/commitLatency.js';
+import { legacyPendingMutationRecordSchema, PENDING_MUTATION_REPLAY_WINDOW_MS, pendingMutationRecordId, pendingMutationRecordSchema, persistedMutationSchema, } from './transactions/mutations/replayValidation.js';
+import { UnconfirmedWrites, } from './transactions/mutations/UnconfirmedWrites.js';
+import { LogPosition } from './transaction/logPosition.js';
+import { DatabaseCommitOutboxStore, } from './transactions/mutations/commitOutboxStore.js';
 /**
  * Reports whether an incoming snapshot record is strictly newer than the
  * model already in the pool. The comparison uses the server-stamped
@@ -73,7 +75,7 @@ export class SyncClient extends EventEmitter {
      * @internal — test seam, stripped from the published declarations by
      * `stripInternal`. Unit suites deliver queue lifecycle events directly.
      */
-    transactionQueue;
+    mutationQueue;
     observers = new Set();
     // Authentication context
     userId = null;
@@ -104,19 +106,19 @@ export class SyncClient extends EventEmitter {
     isDisposed = false;
     /**
      * The client's position in the global delta order, held as the single
-     * canonical {@link SyncPosition} instance. The store advances `applied` and
+     * canonical {@link LogPosition} instance. The store advances `applied` and
      * `persisted` as deltas land, the queue advances `acked` on commit
      * responses, and snapshots and claims read `readFloor`.
      */
-    position = new SyncPosition();
+    position = new LogPosition();
     constructor(objectPool, database, commitOutbox = new DatabaseCommitOutboxStore(database), commitOutboxNamespace = 'default') {
         super();
         this.objectPool = objectPool;
         this.database = database;
         this.commitOutboxNamespace = commitOutboxNamespace;
         this.networkMonitor = new NetworkMonitor();
-        // Initialize TransactionQueue with proper configuration
-        this.transactionQueue = new TransactionQueue({
+        // Initialize MutationQueue with proper configuration
+        this.mutationQueue = new MutationQueue({
             position: this.position,
             maxBatchSize: 50, // Larger batches keep the batch count low for bulk operations
             // A short delay keeps writes responsive; coalescing still groups them
@@ -128,8 +130,8 @@ export class SyncClient extends EventEmitter {
                 strategy: 'last-write-wins',
             },
         });
-        this.transactionQueue.setCommitOutbox(commitOutbox);
-        this.transactionQueue.on('commit:envelope_persisted', (event) => {
+        this.mutationQueue.setCommitOutbox(commitOutbox);
+        this.mutationQueue.on('commit:envelope_persisted', (event) => {
             if (event.sourceMutationIds.length === 0)
                 return;
             const consumed = new Set(event.sourceMutationIds);
@@ -140,7 +142,7 @@ export class SyncClient extends EventEmitter {
                 this.scheduleSync();
             }
         });
-        this.transactionQueue.on('transaction:completed', (transaction) => {
+        this.mutationQueue.on('transaction:completed', (transaction) => {
             const completed = new Set(transaction.sourceMutationIds ?? []);
             if (completed.size > 0) {
                 this.pendingMutations = this.pendingMutations.filter((mutation) => !completed.has(mutation.mutationId));
@@ -155,7 +157,7 @@ export class SyncClient extends EventEmitter {
                 this.scheduleSync();
             }
         });
-        this.transactionQueue.on('transaction:failed', ({ transaction }) => {
+        this.mutationQueue.on('transaction:failed', ({ transaction }) => {
             const failed = transaction.sourceMutationIds ?? [];
             if (failed.length === 0)
                 return;
@@ -175,8 +177,8 @@ export class SyncClient extends EventEmitter {
                 this.scheduleSync();
             }
         });
-        // Provide connection state to TransactionQueue - prevents rollbacks during disconnection
-        this.transactionQueue.setConnectionChecker(() => this.connectionState === 'connected');
+        // Provide connection state to MutationQueue - prevents rollbacks during disconnection
+        this.mutationQueue.setConnectionChecker(() => this.connectionState === 'connected');
         // Restore object-pool state when a transaction is rolled back. If the
         // server rejects a write or it times out, the model's previous state is
         // put back. Because writes are no longer applied to IndexedDB
@@ -201,7 +203,7 @@ export class SyncClient extends EventEmitter {
         // losing a failed reconnect flush silently.
         this.networkMonitor.on('online', () => {
             void this.handleReconnection().catch((error) => {
-                getContext().observability.captureTransactionFailure({
+                getContext().observability.captureMutationFailure({
                     context: 'network-online-reconnection',
                     error: error instanceof Error ? error : new Error(String(error)),
                 });
@@ -209,7 +211,7 @@ export class SyncClient extends EventEmitter {
         });
         this.networkMonitor.on('offline', () => {
             void this.handleDisconnection().catch((error) => {
-                getContext().observability.captureTransactionFailure({
+                getContext().observability.captureMutationFailure({
                     context: 'network-offline-handler',
                     error: error instanceof Error ? error : new Error(String(error)),
                 });
@@ -233,12 +235,12 @@ export class SyncClient extends EventEmitter {
      *      discard the optimistic state silently.
      *
      * Treating both paths the same caused the deletion-flicker bug: every
-     * cancelled update on a multi-layer chart fired a per-model observer
+     * cancelled update on a multi-child record fired a per-model observer
      * event and a `[SyncClient.rollback]` warn, producing N renders and N
      * spam log lines for one user-initiated delete.
      */
     setupTransactionRollbackHandling() {
-        this.transactionQueue.on('optimistic:rollback', (event) => {
+        this.mutationQueue.on('optimistic:rollback', (event) => {
             const { model, previousState, transaction, reason, error } = event;
             // Local cleanup path — discard quietly. The optimistic state was
             // applied to a model that's already disposed by the cascading
@@ -253,7 +255,7 @@ export class SyncClient extends EventEmitter {
             // `AbloServerError` with `httpStatus: 500`). Falling back to
             // generic message lets us still see unstructured errors.
             // Mechanic-level breadcrumb only. The authoritative, user-facing
-            // reason is logged once at `warn` by `TransactionQueue.handleFailure`
+            // reason is logged once at `warn` by `MutationQueue.handleFailure`
             // (`Permanent error - rolling back`). Logging the same typed cause
             // again here at `warn` is what produced three identical dumps per
             // rejected write — keep it at `debug` so the rollback mechanics are
@@ -303,7 +305,7 @@ export class SyncClient extends EventEmitter {
                     if (model.disposed) {
                         // Follow-on of an already-logged permanent error, not its own
                         // problem: the tx that failed has already surfaced the cause in
-                        // TransactionQueue. Restoring a disposed model is a no-op by
+                        // MutationQueue. Restoring a disposed model is a no-op by
                         // design (can't revive the private isDisposed flag), so keep this
                         // at `debug` instead of emitting a second `warn` that reads as a
                         // distinct failure in the console.
@@ -334,7 +336,7 @@ export class SyncClient extends EventEmitter {
                 });
             }
             catch (error) {
-                getContext().observability.captureTransactionFailure({
+                getContext().observability.captureMutationFailure({
                     context: 'rollback-failed',
                     transactionId: transaction.id,
                     modelName: transaction.modelName,
@@ -345,13 +347,13 @@ export class SyncClient extends EventEmitter {
         });
     }
     /**
-     * Forward reconciliation requests from the {@link TransactionQueue} to the
+     * Forward reconciliation requests from the {@link MutationQueue} to the
      * sync layer. When delta confirmation times out, the queue emits
      * `reconciliation:needed` instead of rolling back, so optimistic state the
      * server may already have committed is never destroyed.
      */
     setupReconciliationForwarding() {
-        this.transactionQueue.on('reconciliation:needed', (event) => {
+        this.mutationQueue.on('reconciliation:needed', (event) => {
             getContext().observability.captureReconciliation({
                 reason: event.reason,
                 model: event.model,
@@ -372,12 +374,12 @@ export class SyncClient extends EventEmitter {
      * deliver the missing deltas and confirm the transaction.
      */
     setupAwaitingTransactionPersistence() {
-        this.transactionQueue.on('transaction:persist_awaiting', (event) => {
+        this.mutationQueue.on('transaction:persist_awaiting', (event) => {
             // void is safe: the handler's body is fully try/catch'd.
             void this.persistAwaitingTransaction(event);
         });
         // Clean up persisted awaiting transactions when they're finally confirmed
-        this.transactionQueue.on('transaction:completed', (tx) => {
+        this.mutationQueue.on('transaction:completed', (tx) => {
             // void is safe: the handler's body is fully try/catch'd.
             void this.removeAwaitingTransaction(tx.id);
         });
@@ -389,11 +391,11 @@ export class SyncClient extends EventEmitter {
         // server processes it, we drain on rollback too so a stale id
         // doesn't permanently silence a foreign delta sharing the same id
         // (vanishingly unlikely for UUIDs, but cheap insurance).
-        this.transactionQueue.on('transaction:created', (tx) => {
+        this.mutationQueue.on('transaction:created', (tx) => {
             if (!tx.localOnly)
                 this.echoTracker.markPending(tx.id);
         });
-        this.transactionQueue.on('optimistic:rollback', (event) => {
+        this.mutationQueue.on('optimistic:rollback', (event) => {
             this.echoTracker.drainOnRollback(event.transaction.id);
         });
     }
@@ -420,7 +422,7 @@ export class SyncClient extends EventEmitter {
             });
         }
         catch (error) {
-            getContext().observability.captureTransactionFailure({
+            getContext().observability.captureMutationFailure({
                 context: 'persist-awaiting-transaction',
                 modelName: event.model,
                 modelId: event.modelId,
@@ -446,7 +448,7 @@ export class SyncClient extends EventEmitter {
         this.userId = userId;
         this.organizationId = organizationId;
         getContext().observability.setContext(userId, organizationId);
-        this.transactionQueue.setCommitOutboxScope({
+        this.mutationQueue.setCommitOutboxScope({
             organizationId,
             participantId: userId,
             namespace: this.commitOutboxNamespace,
@@ -461,7 +463,7 @@ export class SyncClient extends EventEmitter {
         // Restore exact, already-sealed requests first. The returned source ids
         // suppress any legacy queue entry left behind by an older non-atomic
         // handoff.
-        const sealedMutationIds = await this.transactionQueue.restoreDurableCommits();
+        const sealedMutationIds = await this.mutationQueue.restoreDurableCommits();
         await this.restoreMutationQueue(sealedMutationIds);
         // Read the initial network status from the injected OnlineStatusProvider.
         // In the browser this reflects the host's connectivity signal; in Node it
@@ -501,7 +503,7 @@ export class SyncClient extends EventEmitter {
      * 2. **Required-field gate** — if the row is missing any field listed
      *    in the model's `requiredFields`, return `null` so the caller
      *    skips this record. Used for FK columns whose absence renders the
-     *    row unrecoverable (e.g. a SlideLayer with no slideId).
+     *    row unrecoverable (e.g. a Block with no sectionId).
      *
      * The engine itself is product-neutral: model identity (which fields
      * to back-fill, which absences are fatal) lives entirely in the
@@ -559,7 +561,7 @@ export class SyncClient extends EventEmitter {
         // Get model types that should be hydrated on startup (skip lazy per LSE)
         const modelTypes = this.objectPool.registry.getRegisteredModelNames().filter((name) => {
             const meta = this.objectPool.registry.getMetadata(name);
-            return (meta?.loadStrategy === LoadStrategy.instant || meta?.loadStrategy === LoadStrategy.partial);
+            return meta?.loadStrategy === LoadStrategy.instant;
         });
         const totalStart = typeof performance !== 'undefined' ? performance.now() : Date.now();
         // Phase 1: Fetch all data from IndexedDB and create model instances (async I/O).
@@ -609,7 +611,7 @@ export class SyncClient extends EventEmitter {
                             getContext().logger.info(`[SyncClient.hydrate] Successfully healed ${recordsToHeal.length} ${modelType} records`);
                         }
                         catch (err) {
-                            getContext().observability.captureTransactionFailure({
+                            getContext().observability.captureMutationFailure({
                                 context: 'persist-healed-records',
                                 modelName: modelType,
                                 error: err instanceof Error ? err : new Error(String(err)),
@@ -681,7 +683,7 @@ export class SyncClient extends EventEmitter {
         // Model types to rehydrate (same filter as hydrateFromDatabase)
         const modelTypes = this.objectPool.registry.getRegisteredModelNames().filter((name) => {
             const meta = this.objectPool.registry.getMetadata(name);
-            return (meta?.loadStrategy === LoadStrategy.instant || meta?.loadStrategy === LoadStrategy.partial);
+            return meta?.loadStrategy === LoadStrategy.instant;
         });
         // ── Phase 1: Read from IndexedDB & create model instances (async I/O) ──
         const allModels = [];
@@ -819,8 +821,9 @@ export class SyncClient extends EventEmitter {
         // object can reach here with `hasChanges === undefined`. `undefined === false`
         // is false → we fall through to the normal path rather than risk dropping a
         // real write. Only a genuine Model with an empty dirty-set is skipped.
-        if (type === 'update' && model.hasChanges === false)
+        if (type === 'update' && model.hasChanges === false) {
             return;
+        }
         // Capture changes before the pool action runs. Pool operations —
         // upsert in particular — can clear the model's local changes, so
         // capturing first ensures they are never lost.
@@ -834,7 +837,7 @@ export class SyncClient extends EventEmitter {
             modelId: model.id,
         });
         // QueryProcessor uses `models:changed` to invalidate caches. Coalesce
-        // to one event per microtask: a paste of 100 layers should re-run
+        // to one event per microtask: a paste of 100 rows should re-run
         // affected queries ONCE, not 100×.
         this.markModelChanged(model.getModelName());
     }
@@ -876,7 +879,7 @@ export class SyncClient extends EventEmitter {
     /**
      * Update existing model with pre-computed changes.
      * Used by saveManyOptimized when incoming models have empty change-tracking
-     * (e.g. freshly constructed SpreadsheetCellModels from decomposeSpreadsheetDocument).
+     * (e.g. freshly constructed cell models from a bulk document decomposition).
      */
     updateWithChanges(model, changes) {
         getContext().logger.debug(`SyncClient.updateWithChanges`, {
@@ -903,7 +906,7 @@ export class SyncClient extends EventEmitter {
             modelId: model.id,
         });
     }
-    /** Expose the GraphQL client for atomic mutations (e.g., createSlideWithLayers).
+    /** Expose the GraphQL client for atomic mutations (e.g., createSectionWithBlocks).
      *  Used by SyncedStore for operations that bypass the transaction queue
      *  but still need optimistic pool updates at the sync layer. */
     get gql() {
@@ -917,7 +920,7 @@ export class SyncClient extends EventEmitter {
     }
     /**
      * Clear all pending mutations for a specific model
-     * Called before deletion to prevent "layer not found" errors on the server
+     * Called before deletion to prevent "record not found" errors on the server
      */
     clearPendingMutationsForModel(modelId) {
         const beforeCount = this.pendingMutations.length;
@@ -931,7 +934,7 @@ export class SyncClient extends EventEmitter {
                 remainingCount: afterCount,
             });
             for (const mutation of removed) {
-                // Once staged, TransactionQueue owns cancellation and transfers this
+                // Once staged, MutationQueue owns cancellation and transfers this
                 // source id into the superseding delete envelope. Deleting the journal
                 // row here would make that valid atomic promotion look like a
                 // multi-tab loser. Truly unstaged work can be canceled locally.
@@ -946,7 +949,7 @@ export class SyncClient extends EventEmitter {
     }
     /**
      * Upload a file and create its attachment record. The upload runs through
-     * the {@link TransactionQueue}, and a model is built from the server's
+     * the {@link MutationQueue}, and a model is built from the server's
      * response and added to the pool.
      */
     async uploadFile(file, options) {
@@ -956,8 +959,8 @@ export class SyncClient extends EventEmitter {
             });
         }
         try {
-            // Use TransactionQueue to handle the upload mutation
-            const result = await this.transactionQueue.uploadAttachment(file, {
+            // Use MutationQueue to handle the upload mutation
+            const result = await this.mutationQueue.uploadAttachment(file, {
                 id: options.id,
                 attachableType: options.attachableType,
                 attachableId: options.attachableId,
@@ -985,7 +988,7 @@ export class SyncClient extends EventEmitter {
             return null;
         }
         catch (error) {
-            getContext().observability.captureTransactionFailure({
+            getContext().observability.captureMutationFailure({
                 context: 'file-upload',
                 error: error instanceof Error ? error : new Error(String(error)),
             });
@@ -1015,7 +1018,7 @@ export class SyncClient extends EventEmitter {
             attachableId: options.attachableId,
             metadata: options.metadata,
         }));
-        const results = await this.transactionQueue.batchUploadAttachments(files, items, {
+        const results = await this.mutationQueue.batchUploadAttachments(files, items, {
             userId: this.userId,
             organizationId: this.organizationId,
         });
@@ -1044,7 +1047,7 @@ export class SyncClient extends EventEmitter {
      * IndexedDB persistence and the server push are deferred to a microtask, so
      * many pushes within the same tick collapse into a single serialization and
      * a single process call. Without the deferral, queueing a hundred mutations
-     * at once — a large paste, a document import, bulk layer creation — would
+     * at once — a large paste, a document import, bulk row creation — would
      * reserialize the whole growing queue a hundred times, an O(N²) cost in
      * `model.toJSON()`.
      *
@@ -1113,20 +1116,59 @@ export class SyncClient extends EventEmitter {
             return;
         }
         try {
-            const records = batch.map((mutation) => this.pendingMutationRecord(mutation));
+            // Build each durable row independently. A malformed mutation must not
+            // prevent unrelated writes from the same event-loop burst from being
+            // journaled and dispatched.
+            const entries = [];
+            for (const mutation of batch) {
+                try {
+                    entries.push({
+                        mutation,
+                        record: this.pendingMutationRecord(mutation),
+                    });
+                }
+                catch (error) {
+                    mutation.rejectJournal?.(error);
+                }
+            }
+            if (entries.length === 0)
+                return;
             const database = this.database;
+            const saveOne = async (record) => {
+                // Some adapters (including IndexedDB's put path) can throw before
+                // returning a Promise. The async wrapper turns that into an individual
+                // rejected outcome instead of aborting construction of the whole list.
+                await database.saveTransaction(record);
+            };
+            let outcomes;
             if (database.saveTransactions) {
-                await database.saveTransactions(records);
+                try {
+                    await database.saveTransactions(entries.map(({ record }) => record));
+                    outcomes = entries.map(() => ({
+                        status: 'fulfilled',
+                        value: undefined,
+                    }));
+                }
+                catch {
+                    // IndexedDB aborts a multi-row transaction when any value cannot be
+                    // cloned. Retry one row per transaction to identify the offender and
+                    // preserve every valid sibling. Re-putting a row is idempotent by id.
+                    outcomes = await Promise.allSettled(entries.map(({ record }) => saveOne(record)));
+                }
             }
             else {
-                await Promise.all(records.map((record) => database.saveTransaction(record)));
+                outcomes = await Promise.allSettled(entries.map(({ record }) => saveOne(record)));
+            }
+            for (const [index, entry] of entries.entries()) {
+                const outcome = outcomes[index];
+                if (outcome?.status === 'fulfilled') {
+                    entry.mutation.resolveJournal?.();
+                }
+                else {
+                    entry.mutation.rejectJournal?.(outcome?.reason ??
+                        new Error('Mutation journal persistence failed'));
+                }
             }
-            for (const mutation of batch)
-                mutation.resolveJournal?.();
-        }
-        catch (error) {
-            for (const mutation of batch)
-                mutation.rejectJournal?.(error);
         }
         finally {
             for (const mutation of batch) {
@@ -1156,7 +1198,7 @@ export class SyncClient extends EventEmitter {
         if (!this.userId || !this.organizationId) {
             throw new AbloValidationError('Cannot persist a mutation before participant scope is initialized', { code: 'write_options_invalid' });
         }
-        return pendingMutationRecordSchema.parse({
+        const candidate = {
             id: pendingMutationRecordId(mutation.mutationId),
             type: 'pending_mutation',
             storageVersion: 2,
@@ -1179,7 +1221,10 @@ export class SyncClient extends EventEmitter {
                 namespace: this.commitOutboxNamespace,
             },
             timestamp: mutation.timestamp.getTime(),
-        });
+        };
+        // One framework-neutral boundary contract owns both Proxy unwrapping and
+        // rejection of values JSON would silently corrupt before IndexedDB sees it.
+        return pendingMutationRecordSchema.parse(snapshotJsonValue(candidate, '$.pendingMutation'));
     }
     async persistPendingMutation(mutation) {
         await this.database.saveTransaction(this.pendingMutationRecord(mutation));
@@ -1292,7 +1337,7 @@ export class SyncClient extends EventEmitter {
             getContext().logger.debug('[SyncClient] Failed to restore offline mutation queue', {
                 error: error instanceof Error ? error.message : String(error),
             });
-            getContext().observability.captureTransactionFailure({
+            getContext().observability.captureMutationFailure({
                 context: 'restore-mutation-queue',
                 error: error instanceof Error ? error : String(error),
             });
@@ -1303,7 +1348,7 @@ export class SyncClient extends EventEmitter {
      *
      * Best Practice: Only sync models that still exist locally (local-first principle)
      * - If a model was deleted locally → skip any pending updates/creates for it
-     * - This prevents "layer not found" errors from fast copy-paste-delete workflows
+     * - This prevents "record not found" errors from fast copy-paste-delete workflows
      */
     async processPendingMutations() {
         if (this.pendingMutations.length === 0)
@@ -1374,7 +1419,7 @@ export class SyncClient extends EventEmitter {
             this.stagedMutationIds.delete(mutation.mutationId);
             this.pendingMutations = this.pendingMutations.filter((pending) => pending.mutationId !== mutation.mutationId);
             mutation.rejectStaged?.(outcome.reason);
-            getContext().observability.captureTransactionFailure({
+            getContext().observability.captureMutationFailure({
                 context: 'persist-pending-mutation',
                 error: outcome.reason instanceof Error
                     ? outcome.reason
@@ -1384,12 +1429,12 @@ export class SyncClient extends EventEmitter {
         // Stage every mutation synchronously within the same event-loop tick;
         // the transaction queue's microtask batches and sends them together.
         for (const mutation of journaledMutations) {
-            // Stage synchronously - TransactionQueue handles batching, retry, and errors
+            // Stage synchronously - MutationQueue handles batching, retry, and errors
             this.stageMutation(mutation);
         }
     }
     /**
-     * Stage mutation to TransactionQueue - mutations in same tick are batched via microtask
+     * Stage mutation to MutationQueue - mutations in same tick are batched via microtask
      *
      * @param mutation.capturedChanges - Pre-captured changes to use instead of re-reading from model
      */
@@ -1406,7 +1451,7 @@ export class SyncClient extends EventEmitter {
         // apply, store add). That means the write never entered the queue, so
         // capture it instead of dropping it silently.
         const captureStagingFailure = (error) => {
-            getContext().observability.captureTransactionFailure({
+            getContext().observability.captureMutationFailure({
                 context: `stage-mutation-${mutation.type}`,
                 modelName: mutation.model.getModelName(),
                 modelId: mutation.model.id,
@@ -1415,8 +1460,8 @@ export class SyncClient extends EventEmitter {
             this.stagedMutationIds.delete(mutation.mutationId);
         };
         const staging = mutation.type === 'update'
-            ? this.transactionQueue.update(mutation.model, ctx, mutation.capturedChanges, mutation.writeOptions, mutation.mutationId)
-            : this.transactionQueue[mutation.type].bind(this.transactionQueue)(mutation.model, ctx, mutation.writeOptions, mutation.mutationId);
+            ? this.mutationQueue.update(mutation.model, ctx, mutation.capturedChanges, mutation.writeOptions, mutation.mutationId)
+            : this.mutationQueue[mutation.type].bind(this.mutationQueue)(mutation.model, ctx, mutation.writeOptions, mutation.mutationId);
         staging
             .then(() => mutation.resolveStaged?.())
             .catch((error) => {
@@ -1535,7 +1580,7 @@ export class SyncClient extends EventEmitter {
         try {
             // Prefer a single batch flush for pending mutations (fast path)
             try {
-                await this.transactionQueue.flushOfflineQueue();
+                await this.mutationQueue.flushOfflineQueue();
             }
             catch { }
             // Process all queued mutations
@@ -1544,7 +1589,7 @@ export class SyncClient extends EventEmitter {
             this.emit('sync:reconnected');
         }
         catch (error) {
-            getContext().observability.captureTransactionFailure({
+            getContext().observability.captureMutationFailure({
                 context: 'reconnection-sync',
                 error: error instanceof Error ? error : new Error(String(error)),
             });
@@ -1581,11 +1626,11 @@ export class SyncClient extends EventEmitter {
             getContext().observability.breadcrumb(`Connection: ${oldState} → ${state}`, 'sync.websocket');
             if (state === 'connected') {
                 this.emit('connection:established');
-                this.transactionQueue.setConnectionState('connected');
+                this.mutationQueue.setConnectionState('connected');
             }
             else if (state === 'disconnected') {
                 this.emit('connection:disconnected');
-                this.transactionQueue.setConnectionState('disconnected');
+                this.mutationQueue.setConnectionState('disconnected');
             }
         }
     }
@@ -1643,8 +1688,8 @@ export class SyncClient extends EventEmitter {
         // Browser online state may have marked the client connected before the
         // WebSocket itself was ready. Always kick both durable lanes on the real
         // socket event, even when the high-level state did not change.
-        void this.transactionQueue.flushOfflineQueue().catch((error) => {
-            getContext().observability.captureTransactionFailure({
+        void this.mutationQueue.flushOfflineQueue().catch((error) => {
+            getContext().observability.captureMutationFailure({
                 context: 'restore-commit-outbox',
                 error: error instanceof Error ? error : new Error(String(error)),
             });
@@ -1663,7 +1708,7 @@ export class SyncClient extends EventEmitter {
         this.removeAllListeners();
     }
     /**
-     * Notify the {@link TransactionQueue} of an incoming delta so it can confirm
+     * Notify the {@link MutationQueue} of an incoming delta so it can confirm
      * hosted writes by sync-id threshold and queued forwards by their echoed
      * source-batch correlation id.
      * @param syncId - The sync id of the received delta.
@@ -1672,7 +1717,7 @@ export class SyncClient extends EventEmitter {
      */
     onDeltaReceived(syncId, transactionId, correlationId) {
         try {
-            this.transactionQueue.onDeltaReceived(syncId, transactionId, correlationId);
+            this.mutationQueue.onDeltaReceived(syncId, transactionId, correlationId);
         }
         catch (e) {
             getContext().observability.breadcrumb('Failed to notify delta received', 'sync.transaction', 'warning', {
@@ -1687,20 +1732,20 @@ export class SyncClient extends EventEmitter {
      * deletion. The store calls this when a delete delta arrives for a parent,
      * cancelling any queued writes on children that reference it.
      *
-     * @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 id of the deleted parent.
      * @returns The number of transactions cancelled.
      */
     cancelTransactionsByForeignKey(childModelName, foreignKey, parentId) {
-        return this.transactionQueue.cancelTransactionsByForeignKey(childModelName, foreignKey, parentId);
+        return this.mutationQueue.cancelTransactionsByForeignKey(childModelName, foreignKey, parentId);
     }
     /**
      * Wait for a transaction to be confirmed by its delta echo. Delegates to the
-     * {@link TransactionQueue}, which handles the confirmation timeout.
+     * {@link MutationQueue}, which handles the confirmation timeout.
      */
     waitForDeltaConfirmation(transactionId) {
-        return this.transactionQueue.waitForConfirmation(transactionId);
+        return this.mutationQueue.waitForConfirmation(transactionId);
     }
     /**
      * Force sync now - process pending mutations
@@ -1728,11 +1773,11 @@ export class SyncClient extends EventEmitter {
         };
     }
     /**
-     * Get pending transaction count from TransactionQueue
+     * Get pending transaction count from MutationQueue
      * Used by SyncedStore to compute hasUnsyncedChanges
      */
     getPendingTransactionCount() {
-        const stats = this.transactionQueue.getStats();
+        const stats = this.mutationQueue.getStats();
         // Include pending and executing as "unsynced"
         // awaiting_delta transactions are included in 'executing' until confirmed
         // Completed and failed are "synced" (either done or gave up)
@@ -1744,12 +1789,12 @@ export class SyncClient extends EventEmitter {
      */
     onTransactionEvent(event, callback) {
         const eventName = `transaction:${event}`;
-        this.transactionQueue.on(eventName, callback);
-        return () => this.transactionQueue.off(eventName, callback);
+        this.mutationQueue.on(eventName, callback);
+        return () => this.mutationQueue.off(eventName, callback);
     }
     /**
      * Subscribe to mutation failures with the full payload. Mirrors the
-     * underlying TransactionQueue 'transaction:failed' shape so consumers
+     * underlying MutationQueue 'transaction:failed' shape so consumers
      * can render typed UI (toast keyed by `AbloError.type`, route-level
      * "this entity reverted" boundaries, telemetry).
      *
@@ -1759,15 +1804,26 @@ export class SyncClient extends EventEmitter {
      * this typed listener drives user-visible surfaces.
      */
     onMutationFailure(listener) {
-        this.transactionQueue.on('transaction:failed', listener);
-        return () => this.transactionQueue.off('transaction:failed', listener);
+        this.mutationQueue.on('transaction:failed', listener);
+        return () => this.mutationQueue.off('transaction:failed', listener);
+    }
+    /**
+     * Subscribe to commit round-trip latency, split into the local seal and the
+     * remote acknowledgement. Fires once per completed commit.
+     *
+     * Taps the {@link MutationQueue} emitter for the same reason
+     * {@link onMutationFailure} does: the commit lifecycle events originate
+     * there and the SyncClient's own emitter never rebroadcasts them.
+     */
+    onCommitLatency(listener) {
+        return observeCommitLatency(this.mutationQueue, listener);
     }
     /**
-     * Subscribe to local transaction creation with the full {@link Transaction}
+     * Subscribe to local transaction creation with the full {@link QueuedMutation}
      * payload (`type`, `modelName`, `modelId`, `data`, `previousData`). This is
      * the feed the store's local-mutation subscription taps for undo recording.
      *
-     * It subscribes to the {@link TransactionQueue}'s emitter directly, since
+     * It subscribes to the {@link MutationQueue}'s emitter directly, since
      * that is the only emitter that fires `transaction:created`. The SyncClient's
      * own emitter (reached through {@link subscribe}) never rebroadcasts that
      * event, so routing undo through `subscribe('transaction:created')` would
@@ -1775,7 +1831,7 @@ export class SyncClient extends EventEmitter {
      * reason.
      */
     onLocalTransaction(listener) {
-        this.transactionQueue.on('transaction:created', listener);
+        this.mutationQueue.on('transaction:created', listener);
         const snapshotsByCommit = new Map();
         const onCommitStaging = (payload) => {
             snapshotsByCommit.set(payload.clientTxId, payload.operations.map((operation) => {
@@ -1843,14 +1899,14 @@ export class SyncClient extends EventEmitter {
                 });
             });
         };
-        this.transactionQueue.on('commit:staging', onCommitStaging);
-        this.transactionQueue.on('commit:seal_failed', onCommitSealFailed);
-        this.transactionQueue.on('commit:created', onCommitCreated);
+        this.mutationQueue.on('commit:staging', onCommitStaging);
+        this.mutationQueue.on('commit:seal_failed', onCommitSealFailed);
+        this.mutationQueue.on('commit:created', onCommitCreated);
         return () => {
-            this.transactionQueue.off('transaction:created', listener);
-            this.transactionQueue.off('commit:staging', onCommitStaging);
-            this.transactionQueue.off('commit:seal_failed', onCommitSealFailed);
-            this.transactionQueue.off('commit:created', onCommitCreated);
+            this.mutationQueue.off('transaction:created', listener);
+            this.mutationQueue.off('commit:staging', onCommitStaging);
+            this.mutationQueue.off('commit:seal_failed', onCommitSealFailed);
+            this.mutationQueue.off('commit:created', onCommitCreated);
             snapshotsByCommit.clear();
         };
     }
@@ -1858,14 +1914,14 @@ export class SyncClient extends EventEmitter {
      * Wait for the latest in-flight transaction for (modelName, modelId)
      * to be confirmed by the server, or reject if it's rolled back.
      * Resolves immediately when no transaction is in flight — see
-     * `TransactionQueue.confirmationFor` for the lookup contract.
+     * `MutationQueue.confirmationFor` for the lookup contract.
      *
      * Distinct from `waitForDeltaConfirmation(transactionId)` which keys
      * off a known tx id; this variant is for call sites that hold a
      * Model reference but never see the underlying transaction.
      */
     waitForConfirmation(modelName, modelId) {
-        return this.transactionQueue.confirmationFor(modelName, modelId);
+        return this.mutationQueue.confirmationFor(modelName, modelId);
     }
     /**
      * Get detailed debug info for the sync debug page
@@ -1874,7 +1930,7 @@ export class SyncClient extends EventEmitter {
         return {
             connectionState: this.connectionState,
             pendingMutationsCount: this.pendingMutations.length,
-            transactionQueue: this.transactionQueue.getDebugInfo(),
+            mutationQueue: this.mutationQueue.getDebugInfo(),
         };
     }
     // --- Best-practice assignment ops ---
@@ -1900,7 +1956,7 @@ export class SyncClient extends EventEmitter {
      * Mark a local transaction as optimistically applied. The matching
      * server delta (when it arrives with the same `transactionId`) will
      * be recognized as an echo and skip the pool mutation. Called
-     * automatically by `TransactionQueue` when a transaction is staged;
+     * automatically by `MutationQueue` when a transaction is staged;
      * exposed publicly so tests can drive the API directly.
      */
     markTransactionPending(transactionId) {
@@ -1916,15 +1972,15 @@ export class SyncClient extends EventEmitter {
         return this.echoTracker.getMetrics();
     }
     /**
-     * Package-internal accessor for the {@link TransactionQueue}. Used by
+     * Package-internal accessor for the {@link MutationQueue}. Used by
      * `Ablo.commits.create()` to route raw multi-operation envelopes through the
      * same retry-on-reconnect lane as the model proxy path, and by tests to
      * exercise the queue's interaction with {@link markTransactionPending} on the
      * real instance the SyncClient subscribes to. It is not re-exported to SDK
      * consumers; `Ablo` is the public surface.
      */
-    getTransactionQueue() {
-        return this.transactionQueue;
+    getMutationQueue() {
+        return this.mutationQueue;
     }
     applyDeltaBatchToPool(dbResults, enrichRelations) {
         const modelsToAdd = [];
@@ -1932,8 +1988,8 @@ export class SyncClient extends EventEmitter {
         const idsToRemove = [];
         const idsToArchive = [];
         // Pre-pass: collect every id slated for `remove` in this batch. The
-        // chart-delete flicker came from this exact pattern: a peer (or the
-        // user themself) deletes a chart with N layers; the commit produces
+        // parent-delete flicker came from this exact pattern: a peer (or the
+        // user themself) deletes a parent with N children; the commit produces
         // BOTH residual `update` deltas (from the optimistic edits that
         // happened just before the delete) AND `remove` deltas. The
         // `update` branch below would `createFromData` the row back into
@@ -1962,7 +2018,7 @@ export class SyncClient extends EventEmitter {
             }
             // If a later op in this batch will remove this id, skip earlier
             // add/update ops on it. Server FK ordering can produce
-            // U(layer)+D(layer) when an optimistic edit and a delete both
+            // U(child)+D(child) when an optimistic edit and a delete both
             // commit in the same window; only the final state matters.
             if ((action === 'add' || action === 'update') && idsBeingRemoved.has(modelId)) {
                 continue;