@abloatai/ablo 0.26.0 → 0.27.0

package/dist/SyncClient.js

@@ -1,14 +1,14 @@
 /**
- * SyncClient - Mutation and offline queue manager
- *
- * Responsibilities:
- * - Handle model mutations (create, update, delete, archive)
- * - Manage offline mutation queue with persistence
- * - Send mutations to server via API client
- * - Handle conflict resolution for local changes
+ * Applies model mutations and manages the offline write queue. The
+ * SyncClient turns local create, update, delete, and archive calls into
+ * 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
+ * over the network.
  */
 import { runInAction } from 'mobx';
-import { ObjectPool, ModelScope } from './ObjectPool.js';
+import { InstanceCache, ModelScope } from './InstanceCache.js';
 import { Model } from './Model.js';
 // ModelRegistry instance accessed via this.objectPool.registry
 import { LoadStrategy } from './types/index.js';
@@ -17,17 +17,18 @@ import { AbloAuthenticationError, AbloError, AbloValidationError } from './error
 import { EventEmitter } from 'events';
 import { NetworkMonitor } from './NetworkMonitor.js';
 import { TransactionQueue } from './transactions/TransactionQueue.js';
-import { persistedMutationSchema } from './transactions/persistedReplay.js';
-import { OptimisticEchoTracker, } from './transactions/OptimisticEchoTracker.js';
+import { persistedMutationSchema } from './transactions/replayValidation.js';
+import { UnconfirmedWrites, } from './transactions/UnconfirmedWrites.js';
 import { SyncPosition } from './sync/syncPosition.js';
 /**
- * Is the raw snapshot record strictly newer than the pooled model? Compares
- * server-stamped `updatedAt` (the engine has no numeric row version; the delta
- * pipeline is arrival-ordered last-write-wins). An undefined incoming time is
- * treated as NOT newer (don't clobber a known row); an undefined existing time
- * means the pool row is unversioned, so the incoming record wins. Used by the
- * scoped hydrate-on-enter apply to drop snapshot rows a live delta already
- * advanced past the snapshot watermark.
+ * Reports whether an incoming snapshot record is strictly newer than the
+ * model already in the pool. The comparison uses the server-stamped
+ * `updatedAt` timestamp, since rows carry no numeric version and the delta
+ * pipeline resolves order by arrival (last write wins). An undefined incoming
+ * timestamp counts as not newer, so a known row is never clobbered; an
+ * undefined existing timestamp means the pooled row is unversioned, so the
+ * incoming record wins. The scoped hydrate-on-enter path uses this to drop
+ * snapshot rows that a live delta has already advanced past.
  */
 function rawRecordIsNewer(data, existing) {
     const raw = data.updatedAt;
@@ -46,10 +47,10 @@ function rawRecordIsNewer(data, existing) {
     return inMs > exMs;
 }
 /**
- * Narrow an untyped server `updatedAt` (ISO string / epoch / Date, off a
- * `Record<string, unknown>` row) to epoch ms for LWW comparison. Falsy /
- * non-date values → 0, matching the conflict resolver's historical
- * "no timestamp = epoch" behavior.
+ * Converts an untyped server `updatedAt` value — an ISO string, epoch number,
+ * or Date read off an untyped row — into epoch milliseconds for
+ * last-write-wins comparison. Falsy or non-date values become 0, matching the
+ * conflict resolver's rule that a missing timestamp sorts as the epoch.
  */
 function toEpochMs(value) {
     if (!value)
@@ -74,32 +75,28 @@ export class SyncClient extends EventEmitter {
     // Pending mutations queue
     pendingMutations = [];
     /**
-     * Tracks transaction ids the client has optimistically applied but
-     * the server has not yet confirmed. The receive path consults it
-     * to recognize delta echoes of own mutations and suppress the
-     * (otherwise-redundant) pool mutation — the IDB write still runs
-     * because the delta is the authoritative version of the row.
+     * Tracks the ids of transactions the client has applied optimistically but
+     * the server has not yet confirmed. When a delta arrives, the receive path
+     * consults this set to recognize the echo of the client's own mutation and
+     * skip the now-redundant pool update; the IndexedDB write still runs,
+     * because the delta is the authoritative version of the row. Without this
+     * discriminator, an optimistically applied delete followed by a
+     * server-confirmed create echo would resurrect the row for the window
+     * between the two confirmations.
      *
-     * The receive-layer discriminator named in
-     * `apps/sync-server/docs/OPTIMISTIC_RECONCILIATION.md`. Without
-     * it, an optimistically-applied DELETE followed by a
-     * server-confirming CREATE echo resurrects the row for the window
-     * between the two confirmations (the chart-delete flicker).
-     *
-     * Bounded with FIFO eviction; observability via `getEchoMetrics()`.
+     * The set is bounded with first-in-first-out eviction, and
+     * {@link SyncClient.getEchoMetrics} exposes its counters.
      */
-    echoTracker = new OptimisticEchoTracker();
+    echoTracker = new UnconfirmedWrites();
     // Connection state
     connectionState = 'disconnected';
-    offlineSince;
     // Configuration
-    maxRetries = 3;
     isDisposed = false;
     /**
-     * THE client's place in the global delta order — the one canonical
-     * instance (see `sync/syncPosition.ts`). The store advances
-     * `applied`/`persisted` as deltas land; the queue advances `acked` on
-     * commit responses; snapshots/claims read `readFloor`.
+     * The client's position in the global delta order, held as the single
+     * canonical {@link SyncPosition} 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();
     constructor(objectPool, database) {
@@ -110,8 +107,8 @@ export class SyncClient extends EventEmitter {
         // Initialize TransactionQueue with proper configuration
         this.transactionQueue = new TransactionQueue({
             position: this.position,
-            maxBatchSize: 50, // Increased from 10 to reduce batch count for large operations
-            // Lower delay for snappier dev UX; batching still happens via coalescing
+            maxBatchSize: 50, // Larger batches keep the batch count low for bulk operations
+            // A short delay keeps writes responsive; coalescing still groups them
             batchDelay: 150,
             maxRetries: 3,
             enableOptimistic: true,
@@ -122,16 +119,17 @@ export class SyncClient extends EventEmitter {
         });
         // Provide connection state to TransactionQueue - prevents rollbacks during disconnection
         this.transactionQueue.setConnectionChecker(() => this.connectionState === 'connected');
-        // LINEAR PATTERN: Subscribe to rollback events to restore ObjectPool state
-        // When a transaction fails (server rejects or timeout), we need to restore the model
-        // Since we no longer write to IndexedDB optimistically, IndexedDB already has correct state
+        // 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
+        // optimistically, that store already holds the correct state.
         this.setupTransactionRollbackHandling();
-        // REPLICACHE PATTERN: Forward reconciliation requests from TransactionQueue
-        // When delta confirmation times out, instead of rolling back we request the sync layer
-        // to cycle the WebSocket connection, triggering a delta catch-up from the server
+        // Forward reconciliation requests from the transaction queue. When delta
+        // confirmation times out, the client cycles the WebSocket connection to
+        // trigger a catch-up from the server rather than rolling the write back.
         this.setupReconciliationForwarding();
-        // LINEAR PATTERN: Persist unconfirmed transactions to IndexedDB
-        // When delta retries exhaust, cache in IDB so they survive tab close
+        // Persist unconfirmed transactions to IndexedDB. When delta retries are
+        // exhausted, the write is cached so it survives a tab close.
         this.setupAwaitingTransactionPersistence();
         // Setup network monitoring
         this.setupNetworkMonitoring();
@@ -289,10 +287,10 @@ export class SyncClient extends EventEmitter {
         });
     }
     /**
-     * Forward reconciliation requests from TransactionQueue to the sync layer.
-     * When delta confirmation times out, TransactionQueue emits 'reconciliation:needed'
-     * instead of rolling back — following the Replicache/PowerSync pattern of never
-     * destroying optimistic state that the server may have committed.
+     * Forward reconciliation requests from the {@link TransactionQueue} 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) => {
@@ -310,10 +308,10 @@ export class SyncClient extends EventEmitter {
         });
     }
     /**
-     * LINEAR PATTERN: Persist unconfirmed transactions to IndexedDB.
-     * When delta confirmation retries exhaust, the transaction data is cached in IDB
-     * so it survives tab close. On next session, WebSocket reconnect + delta catch-up
-     * will deliver the missing deltas and naturally confirm the transaction.
+     * Persist unconfirmed transactions to IndexedDB. When delta-confirmation
+     * retries are exhausted, the transaction is cached so it survives a tab
+     * close. On the next session, a WebSocket reconnect and delta catch-up
+     * deliver the missing deltas and confirm the transaction.
      */
     setupAwaitingTransactionPersistence() {
         this.transactionQueue.on('transaction:persist_awaiting', (event) => {
@@ -341,7 +339,7 @@ export class SyncClient extends EventEmitter {
             this.echoTracker.drainOnRollback(event.transaction.id);
         });
     }
-    /** Persist an unconfirmed transaction to IDB (never rejects — failures are captured). */
+    /** Persist an unconfirmed transaction to IndexedDB (never rejects — failures are captured). */
     async persistAwaitingTransaction(event) {
         if (!this.database)
             return;
@@ -392,19 +390,17 @@ export class SyncClient extends EventEmitter {
         getContext().observability.setContext(userId, organizationId);
         // Restore queued mutations from previous session
         await this.restoreMutationQueue();
-        // Check network status via the DI'd OnlineStatusProvider (see interfaces.ts:192).
-        // In the browser this is wired to the service worker's connectivity signal via
-        // abloOnlineStatus in ablo-sync-adapters.ts; in Node it returns true (assume
-        // online) via the browserOnlineStatus fallback. NetworkMonitor still drives
-        // event-based online/offline transitions below; this read is just the initial
-        // status snapshot at registerUser() time.
+        // Read the initial network status from the injected OnlineStatusProvider.
+        // In the browser this reflects the host's connectivity signal; in Node it
+        // reports online by default. NetworkMonitor drives the ongoing
+        // online/offline transitions below — this read is only the initial
+        // snapshot taken when identity is set.
         if (getContext().onlineStatus.isOnline()) {
             this.setConnectionState('connected');
         }
         else {
             // Offline - start in offline mode
             this.setConnectionState('disconnected');
-            this.offlineSince = new Date();
             this.emit('sync:offline');
         }
     }
@@ -420,7 +416,7 @@ export class SyncClient extends EventEmitter {
      * Self-healing helper for individual model records.
      *
      * Two registry-driven repair passes run on every row hydrated from
-     * IDB or merged from a delta:
+     * IndexedDB or merged from a delta:
      *
      * 1. **Auto-fill** — for each `autoFill` rule the consumer's schema
      *    declares on this model, copy the corresponding identity value
@@ -476,7 +472,7 @@ export class SyncClient extends EventEmitter {
         return { data: result, healed };
     }
     /**
-     * Hydrate ObjectPool with data from Database
+     * Hydrate InstanceCache with data from Database
      * Called after bootstrap is complete
      */
     async hydrateFromDatabase() {
@@ -591,7 +587,7 @@ export class SyncClient extends EventEmitter {
         catch { }
     }
     /**
-     * Re-hydrate ObjectPool from IndexedDB when the pool already has data.
+     * Re-hydrate InstanceCache from IndexedDB when the pool already has data.
      *
      * Unlike hydrateFromDatabase() (which uses addBatch and skips existing IDs),
      * this method properly:
@@ -726,13 +722,14 @@ export class SyncClient extends EventEmitter {
         return stats;
     }
     /**
-     * Mutate model optimistically and queue for server sync.
-     * IndexedDB is only updated when server confirms via delta packet.
-     *
-     * CRITICAL: Changes are captured BEFORE poolAction to prevent data loss.
-     * The captured changes are frozen and passed to queueMutation.
+     * Apply a mutation to a model optimistically and queue it for server sync.
+     * IndexedDB is updated only once the server confirms the change with a delta
+     * packet.
      *
-     * @see src/sync-engine/types/TrackableModel.ts for change capture pattern
+     * A model's changes are captured before the pool action runs, because a pool
+     * operation such as an upsert can clear the model's local change set;
+     * capturing first ensures those changes are never lost. The captured set is
+     * frozen and handed to {@link queueMutation}.
      */
     mutate(type, model, poolAction, writeOptions) {
         // No-op UPDATE guard (O(1)). An update with no dirty fields would travel
@@ -749,9 +746,9 @@ export class SyncClient extends EventEmitter {
         // real write. Only a genuine Model with an empty dirty-set is skipped.
         if (type === 'update' && model.hasChanges === false)
             return;
-        // CRITICAL FIX: Capture changes BEFORE pool action
-        // Pool operations (especially upsert) can clear _local changes
-        // By capturing first, we ensure changes are never lost
+        // 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.
         const capturedChanges = type === 'update' || type === 'create' ? this.captureModelChanges(model) : undefined;
         poolAction();
         this.queueMutation({ type, model, timestamp: new Date(), capturedChanges, writeOptions });
@@ -862,8 +859,9 @@ export class SyncClient extends EventEmitter {
         }
     }
     /**
-     * Upload file and create attachment (UPLOAD operation)
-     * Uses Linear-style pattern with immediate URL generation
+     * Upload a file and create its attachment record. The upload runs through
+     * the {@link TransactionQueue}, and a model is built from the server's
+     * response and added to the pool.
      */
     async uploadFile(file, options) {
         if (!this.userId || !this.organizationId) {
@@ -955,16 +953,17 @@ export class SyncClient extends EventEmitter {
         this.mutate('archive', model, () => { this.objectPool.updateScope(model.id, ModelScope.archived); });
     }
     /**
-     * Append a mutation and schedule its sync work.
+     * Append a mutation to the pending queue and schedule its sync work.
      *
-     * IDB persistence and the server push are deferred to a microtask so N
-     * pushes inside the same tick collapse into ONE IDB serialization + ONE
-     * process call. Without the deferral, queueing 100 mutations (paste,
-     * PPTX import, AI sandbox layer creation) reserializes the entire
-     * growing queue 100× — O(N²) `model.toJSON()`.
+     * 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
+     * reserialize the whole growing queue a hundred times, an O(N²) cost in
+     * `model.toJSON()`.
      *
-     * @param mutation.capturedChanges - Pre-captured changes (frozen), used
-     *   to avoid re-reading changes after pool ops that might clear them.
+     * @param mutation.capturedChanges - Pre-captured, frozen changes, used to
+     *   avoid re-reading a model after pool operations that might clear them.
      */
     queueMutation(mutation) {
         this.pendingMutations.push(mutation);
@@ -1018,12 +1017,13 @@ export class SyncClient extends EventEmitter {
         }
     }
     /**
-     * Restore mutation queue from IndexedDB.
+     * Restore the mutation queue from IndexedDB.
      *
-     * The persisted record was written by a PREVIOUS session (possibly an older
-     * SDK build), so each entry is validated at this replay boundary (T1.8):
-     * corrupt entries are dropped + logged at debug, and a failure never
-     * vanishes into an empty catch — offline write survival must be observable.
+     * The persisted record was written by an earlier session, possibly by an
+     * older build of the SDK, so each entry is validated as it is replayed:
+     * corrupt entries are dropped and logged at debug level, and a failure is
+     * never swallowed silently, because the survival of offline writes must be
+     * observable.
      */
     async restoreMutationQueue() {
         if (!this.database || !this.userId)
@@ -1106,8 +1106,8 @@ export class SyncClient extends EventEmitter {
         this.pendingMutations = [];
         // Clear persisted queue before processing
         await this.persistMutationQueue();
-        // LINEAR PATTERN: Stage all mutations synchronously in same event loop tick
-        // TransactionQueue's microtask will batch and send them together
+        // Stage every mutation synchronously within the same event-loop tick;
+        // the transaction queue's microtask batches and sends them together.
         for (const mutation of mutations) {
             // Skip mutations for deleted models (prevents "not found" errors)
             if (mutation.type !== 'delete' && !this.objectPool.get(mutation.model.id)) {
@@ -1149,11 +1149,10 @@ export class SyncClient extends EventEmitter {
         }
     }
     /**
-     * Resolve conflicts between local and server data
-     * Used when processing deltas from WebSocket
-     *
-     * CRITICAL: Always respects certain server states (deletes, deactivations)
-     * even when there are local changes, to maintain data consistency.
+     * Resolve a conflict between the local model and incoming server data,
+     * called while processing deltas from the WebSocket. Certain server states,
+     * such as deletions and deactivations, always take precedence even when the
+     * local model has unsynced changes, so the two sides stay consistent.
      */
     resolveConflicts(localModel, serverData) {
         const hasLocalChanges = localModel.hasChanges;
@@ -1218,9 +1217,9 @@ export class SyncClient extends EventEmitter {
         return localModel;
     }
     /**
-     * Extract critical state fields from server data
-     * These are states that must always be respected, even with local changes.
-     * The conflict brain reads exactly these known fields — nothing else.
+     * Extract the critical state fields from server data. These are the states
+     * that must be honored even when the local model has unsynced changes. The
+     * conflict resolver reads exactly these fields and no others.
      */
     extractCriticalState(serverData) {
         const critical = {};
@@ -1267,8 +1266,6 @@ export class SyncClient extends EventEmitter {
             await this.processPendingMutations();
             this.setConnectionState('connected');
             this.emit('sync:reconnected');
-            // Clear offline timestamp
-            this.offlineSince = undefined;
         }
         catch (error) {
             getContext().observability.captureTransactionFailure({
@@ -1284,7 +1281,6 @@ export class SyncClient extends EventEmitter {
     async handleDisconnection() {
         getContext().observability.breadcrumb('Network disconnected', 'sync.offline');
         this.setConnectionState('disconnected');
-        this.offlineSince = new Date();
         this.emit('sync:offline');
     }
     /**
@@ -1381,9 +1377,10 @@ export class SyncClient extends EventEmitter {
         this.removeAllListeners();
     }
     /**
-     * LINEAR PATTERN: Notify TransactionQueue of incoming delta for sync ID threshold confirmation.
-     * Transactions are confirmed when any delta with id >= their lastSyncId threshold arrives.
-     * @param syncId - The sync ID of the received delta
+     * Notify the {@link TransactionQueue} of an incoming delta so it can confirm
+     * transactions by sync-id threshold. A transaction is confirmed once any
+     * delta with an id at or beyond its `lastSyncId` threshold arrives.
+     * @param syncId - The sync id of the received delta.
      */
     onDeltaReceived(syncId) {
         try {
@@ -1396,22 +1393,21 @@ export class SyncClient extends EventEmitter {
         }
     }
     /**
-     * LINEAR PATTERN: Cancel transactions for orphaned child entities
-     *
-     * Called by SyncedStore when a DELETE delta arrives for a parent entity.
-     * Cancels pending transactions for children that reference the deleted parent.
+     * Cancel pending transactions for child entities orphaned by a parent's
+     * 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 (e.g., 'SlideLayer')
-     * @param foreignKey - The FK property name (e.g., 'slideId')
-     * @param parentId - The deleted parent's ID
-     * @returns Number of transactions cancelled
+     * @param childModelName - The child model type (for example, `SlideLayer`).
+     * @param foreignKey - The foreign-key property name (for example, `slideId`).
+     * @param parentId - The id of the deleted parent.
+     * @returns The number of transactions cancelled.
      */
     cancelTransactionsByForeignKey(childModelName, foreignKey, parentId) {
         return this.transactionQueue.cancelTransactionsByForeignKey(childModelName, foreignKey, parentId);
     }
     /**
-     * Wait for a transaction to be confirmed via delta echo (Linear pattern)
-     * Delegates to TransactionQueue which already handles timeouts
+     * Wait for a transaction to be confirmed by its delta echo. Delegates to the
+     * {@link TransactionQueue}, which handles the confirmation timeout.
      */
     waitForDeltaConfirmation(transactionId) {
         return this.transactionQueue.waitForConfirmation(transactionId);
@@ -1425,7 +1421,7 @@ export class SyncClient extends EventEmitter {
     /**
      * Get sync statistics. Return type is inferred from the literal so
      * the call site sees the actual shape — `connectionState` narrowed
-     * to its three states, `objectPoolStats` typed by `ObjectPool.getStats`.
+     * to its three states, `objectPoolStats` typed by `InstanceCache.getStats`.
      */
     getSyncStats() {
         return {
@@ -1460,25 +1456,26 @@ export class SyncClient extends EventEmitter {
      * can render typed UI (toast keyed by `AbloError.type`, route-level
      * "this entity reverted" boundaries, telemetry).
      *
-     * Distinct from `onTransactionEvent('failed', cb)`, which exists only
-     * for the legacy parameterless `pendingChanges` counter and intentionally
-     * drops the payload. The two coexist — keep the counter callback fast
-     * and the typed listener for user-visible surfaces.
+     * Distinct from `onTransactionEvent('failed', cb)`, which serves the
+     * parameterless `pendingChanges` counter and intentionally drops the
+     * payload. The two coexist: the counter callback stays lightweight, while
+     * this typed listener drives user-visible surfaces.
      */
     onMutationFailure(listener) {
         this.transactionQueue.on('transaction:failed', listener);
         return () => this.transactionQueue.off('transaction:failed', listener);
     }
     /**
-     * Subscribe to LOCAL transaction creation with the full {@link Transaction}
+     * Subscribe to local transaction creation with the full {@link Transaction}
      * payload (`type`, `modelName`, `modelId`, `data`, `previousData`). This is
-     * the feed `BaseSyncedStore.subscribeLocalMutations` taps for undo recording.
+     * the feed the store's local-mutation subscription taps for undo recording.
      *
-     * MUST subscribe to the TransactionQueue's emitter directly — that is the
-     * ONLY emitter that fires `transaction:created`. SyncClient's own emitter
-     * (reached via `subscribe()`) never re-broadcasts it, so routing undo through
-     * `subscribe('transaction:created')` silently records nothing. Mirrors
-     * `onMutationFailure`, which taps the queue for the same reason.
+     * It subscribes to the {@link TransactionQueue}'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
+     * record nothing. {@link onMutationFailure} taps the queue for the same
+     * reason.
      */
     onLocalTransaction(listener) {
         this.transactionQueue.on('transaction:created', listener);
@@ -1574,11 +1571,11 @@ export class SyncClient extends EventEmitter {
             assigneeId,
         });
     }
-    // ── Delta + Bootstrap application (owns ObjectPool writes) ──────────────
+    // ── Delta + Bootstrap application (owns InstanceCache writes) ──────────────
     /**
-     * Apply a batch of delta results from Database to the ObjectPool.
+     * Apply a batch of delta results from Database to the InstanceCache.
      * Owns: model creation, upsert, remove, archive, conflict resolution.
-     * Returns: nothing — ObjectPool is updated in place.
+     * Returns: nothing — InstanceCache is updated in place.
      */
     /**
      * Mark a local transaction as optimistically applied. The matching
@@ -1600,12 +1597,12 @@ export class SyncClient extends EventEmitter {
         return this.echoTracker.getMetrics();
     }
     /**
-     * Package-internal accessor for the TransactionQueue. Used by
-     * `Ablo.commits.create()` to route raw multi-op envelopes through the
-     * same retry-on-reconnect lane as the Model proxy path, and by tests
-     * to exercise the queue ↔ markTransactionPending wiring on the real
-     * instance the SyncClient subscribes to. NOT re-exported to SDK
-     * consumers — `Ablo` itself is the public surface.
+     * Package-internal accessor for the {@link TransactionQueue}. 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;
@@ -1633,16 +1630,14 @@ export class SyncClient extends EventEmitter {
         }
         for (const result of dbResults) {
             const { modelName, modelId, action, transactionId } = result;
-            // ECHO DETECTION. If this delta carries a transaction id that
-            // matches one we've optimistically applied locally, the pool
-            // already reflects this mutation — skip the pool op. The
-            // upstream IDB write (in `Database.processDeltaBatch`) still
-            // runs; only the in-memory pool mutation is suppressed. This is
-            // the architectural fix for the chart-delete flicker: a
-            // server-confirmed CREATE arriving AFTER the user has
-            // optimistically deleted the row would otherwise re-add the row
-            // for the ~2s window before the matching DELETE confirmation
-            // lands. See `OPTIMISTIC_RECONCILIATION.md` for the framing.
+            // Echo detection: if this delta carries a transaction id that matches
+            // one already applied optimistically, the pool already reflects the
+            // mutation, so the pool operation is skipped. The IndexedDB write in
+            // Database.processDeltaBatch still runs; only the in-memory pool update
+            // is suppressed. This prevents a resurrection flicker: a server-confirmed
+            // create arriving after the user has optimistically deleted the row would
+            // otherwise re-add it for the brief window before the matching delete
+            // confirmation lands.
             if (this.echoTracker.consumeEcho(transactionId)) {
                 continue;
             }
@@ -1708,17 +1703,15 @@ export class SyncClient extends EventEmitter {
                     break;
             }
         }
-        // Reveal the whole frame in ONE MobX action. `addBatch`/`upsertBatch`/
-        // `removeBatch`/`updateScope` are each individually `action`-wrapped,
-        // so calling them sequentially flushes reactions at every action
-        // boundary — a catch-up frame that adds + updates + removes would fire
-        // every dependent reaction (the decks gallery, each open editor) 3-4×
-        // in a row, re-rendering and re-sorting on each. Wrapping them in a
-        // single outer `runInAction` defers all reaction flushes to ONE
-        // boundary: dependents recompute exactly once regardless of how many
-        // models or how many op-kinds the frame touched. This is the MobX
-        // equivalent of Replicache's "atomically reveal the new state" — the
-        // app never observes a partially-applied frame.
+        // Reveal the whole frame in a single MobX action. `addBatch`,
+        // `upsertBatch`, `removeBatch`, and `updateScope` are each individually
+        // wrapped in an action, so calling them in sequence flushes reactions at
+        // every action boundary — a catch-up frame that adds, updates, and removes
+        // would fire every dependent reaction several times in a row, re-rendering
+        // and re-sorting on each. Wrapping them in one outer `runInAction` defers
+        // all reaction flushes to a single boundary, so dependents recompute
+        // exactly once regardless of how many models or operation kinds the frame
+        // touched. The app therefore never observes a partially applied frame.
         runInAction(() => {
             if (modelsToAdd.length > 0)
                 this.objectPool.addBatch(modelsToAdd, ModelScope.live);
@@ -1737,7 +1730,7 @@ export class SyncClient extends EventEmitter {
         });
     }
     /**
-     * Apply bootstrap data to the ObjectPool with ghost removal.
+     * Apply bootstrap data to the InstanceCache with ghost removal.
      * Owns: model creation, batch upsert, ghost detection + removal.
      */
     applyBootstrapDataToPool(bootstrapData, protectedIds, options) {
@@ -1775,12 +1768,12 @@ export class SyncClient extends EventEmitter {
                 const recordId = data.id;
                 if (recordId)
                     idsForType.add(recordId);
-                // Scoped backfill (P4 hydrate-on-enter): a subset snapshot is taken at
-                // a server watermark. If a concurrent live delta already advanced this
-                // row past the snapshot, skip it — `createFromData` mutates the pooled
-                // model IN PLACE (the "keep instances alive" Linear pattern), so this
-                // version guard MUST run BEFORE it; an upsert-layer guard would be too
-                // late, the row would already be clobbered.
+                // Scoped backfill for the hydrate-on-enter path: a subset snapshot is
+                // taken at a server watermark. If a concurrent live delta already
+                // advanced this row past the snapshot, skip it. `createFromData`
+                // mutates the pooled model in place to keep instances alive, so this
+                // version guard has to run before it; a guard at the upsert layer would
+                // be too late, because the row would already be clobbered.
                 if (options?.scoped && recordId) {
                     const existing = this.objectPool.get(recordId);
                     if (existing && !rawRecordIsNewer(data, existing)) {
@@ -1804,10 +1797,10 @@ export class SyncClient extends EventEmitter {
         this.objectPool.upsertBatch(allModels, ModelScope.live);
         const addedCount = this.objectPool.size - beforeSize;
         const updatedCount = allModels.length - addedCount;
-        // Ghost removal — remove pool entities not in the server snapshot. Only
-        // valid for a FULL bootstrap, where the snapshot is authoritative for each
-        // returned type. A SCOPED subset snapshot must NOT remove rows of the same
-        // type that belong to other (unhydrated) groups.
+        // Ghost removal: drop pool entities absent from the server snapshot. This
+        // is valid only for a full bootstrap, where the snapshot is authoritative
+        // for each returned type. A scoped subset snapshot must not remove rows of
+        // the same type that belong to other, unhydrated groups.
         let removedCount = 0;
         if (!options?.scoped) {
             const ghostIds = [];