@abloatai/ablo 0.26.0 → 0.28.0

package/dist/SyncClient.js

@@ -1,14 +1,15 @@
 /**
- * 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 { v4 as uuid } from 'uuid';
+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 +18,19 @@ 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 { 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';
 /**
- * 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 +49,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)
@@ -66,6 +69,10 @@ export class SyncClient extends EventEmitter {
     database;
     get mutationExecutor() { return getContext().mutationExecutor; }
     networkMonitor;
+    /**
+     * @internal — test seam, stripped from the published declarations by
+     * `stripInternal`. Unit suites deliver queue lifecycle events directly.
+     */
     transactionQueue;
     observers = new Set();
     // Authentication context
@@ -73,45 +80,46 @@ export class SyncClient extends EventEmitter {
     organizationId = null;
     // Pending mutations queue
     pendingMutations = [];
+    stagedMutationIds = new Set();
+    pendingJournalBatch = [];
+    journalFlushScheduled = false;
+    commitOutboxNamespace;
     /**
-     * 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) {
+    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({
             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,
@@ -120,18 +128,66 @@ export class SyncClient extends EventEmitter {
                 strategy: 'last-write-wins',
             },
         });
+        this.transactionQueue.setCommitOutbox(commitOutbox);
+        this.transactionQueue.on('commit:envelope_persisted', (event) => {
+            if (event.sourceMutationIds.length === 0)
+                return;
+            const consumed = new Set(event.sourceMutationIds);
+            this.pendingMutations = this.pendingMutations.filter((mutation) => !consumed.has(mutation.mutationId));
+            for (const mutationId of consumed)
+                this.stagedMutationIds.delete(mutationId);
+            if (this.stagedMutationIds.size === 0 && this.pendingMutations.length > 0) {
+                this.scheduleSync();
+            }
+        });
+        this.transactionQueue.on('transaction:completed', (transaction) => {
+            const completed = new Set(transaction.sourceMutationIds ?? []);
+            if (completed.size > 0) {
+                this.pendingMutations = this.pendingMutations.filter((mutation) => !completed.has(mutation.mutationId));
+            }
+            for (const mutationId of transaction.sourceMutationIds ?? []) {
+                this.stagedMutationIds.delete(mutationId);
+                void this.database
+                    .removeTransaction(pendingMutationRecordId(mutationId))
+                    .catch(() => undefined);
+            }
+            if (this.stagedMutationIds.size === 0 && this.pendingMutations.length > 0) {
+                this.scheduleSync();
+            }
+        });
+        this.transactionQueue.on('transaction:failed', ({ transaction }) => {
+            const failed = transaction.sourceMutationIds ?? [];
+            if (failed.length === 0)
+                return;
+            const failedSet = new Set(failed);
+            this.pendingMutations = this.pendingMutations.filter((mutation) => !failedSet.has(mutation.mutationId));
+            for (const mutationId of failed) {
+                this.stagedMutationIds.delete(mutationId);
+                // The queue has already rolled the model back, so replaying the
+                // journal row on the next boot would resurrect a rejected write.
+                void this.database
+                    .removeTransaction(pendingMutationRecordId(mutationId))
+                    .catch(() => undefined);
+            }
+            // Without this drain, terminally failed ids stayed claimed forever and
+            // the size guard in processPendingMutations stalled every later write.
+            if (this.stagedMutationIds.size === 0 && this.pendingMutations.length > 0) {
+                this.scheduleSync();
+            }
+        });
         // 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 +345,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 +366,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 +397,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;
@@ -390,23 +446,38 @@ export class SyncClient extends EventEmitter {
         this.userId = userId;
         this.organizationId = organizationId;
         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.
+        this.transactionQueue.setCommitOutboxScope({
+            organizationId,
+            participantId: userId,
+            namespace: this.commitOutboxNamespace,
+        });
+        // Calls made during startup are allowed to queue before identity arrives,
+        // but they cannot be serialized with a trustworthy scope until now. Flush
+        // those already-created journal promises before any write can be staged.
+        if (this.pendingJournalBatch.length > 0) {
+            this.scheduleJournalFlush();
+            await Promise.all(this.pendingMutations.map((mutation) => mutation.journaled));
+        }
+        // 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();
+        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
+        // 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');
         }
+        if (this.pendingMutations.length > 0)
+            this.scheduleSync();
     }
     /**
      * The organization this client writes under (set by `initialize`).
@@ -420,7 +491,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 +547,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 +662,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 +797,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.
+     * 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.
      *
-     * CRITICAL: Changes are captured BEFORE poolAction to prevent data loss.
-     * The captured changes are frozen and passed to queueMutation.
-     *
-     * @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 +821,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 });
@@ -849,6 +921,7 @@ export class SyncClient extends EventEmitter {
      */
     clearPendingMutationsForModel(modelId) {
         const beforeCount = this.pendingMutations.length;
+        const removed = this.pendingMutations.filter((mutation) => mutation.model.id === modelId);
         this.pendingMutations = this.pendingMutations.filter((m) => m.model.id !== modelId);
         const afterCount = this.pendingMutations.length;
         if (beforeCount !== afterCount) {
@@ -857,13 +930,24 @@ export class SyncClient extends EventEmitter {
                 clearedCount: beforeCount - afterCount,
                 remainingCount: afterCount,
             });
-            // Persist updated queue immediately
-            void this.persistMutationQueue();
+            for (const mutation of removed) {
+                // Once staged, TransactionQueue 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.
+                if (this.stagedMutationIds.has(mutation.mutationId))
+                    continue;
+                this.stagedMutationIds.delete(mutation.mutationId);
+                void mutation.journaled
+                    .then(() => this.database.removeTransaction(pendingMutationRecordId(mutation.mutationId)))
+                    .catch(() => undefined);
+            }
         }
     }
     /**
-     * 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,21 +1039,102 @@ 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);
+        const mutationId = `mutation_${uuid()}`;
+        const modelData = mutation.model.toJSON
+            ? mutation.model.toJSON()
+            : { ...mutation.model };
+        let resolveJournal;
+        let rejectJournal;
+        const journaled = new Promise((resolve, reject) => {
+            resolveJournal = resolve;
+            rejectJournal = reject;
+        });
+        let resolveStaged;
+        let rejectStaged;
+        const staged = new Promise((resolve, reject) => {
+            resolveStaged = resolve;
+            rejectStaged = reject;
+        });
+        const pending = {
+            ...mutation,
+            mutationId,
+            modelData,
+            journaled,
+            resolveJournal,
+            rejectJournal,
+            staged,
+            resolveStaged,
+            rejectStaged,
+        };
+        this.pendingJournalBatch.push(pending);
+        this.scheduleJournalFlush();
+        // Offline drains may not await this until much later. Observe rejection
+        // immediately to avoid an unhandled-promise report while retaining the
+        // original rejecting promise for fail-closed dispatch.
+        void pending.journaled.catch(() => undefined);
+        void pending.staged.catch(() => undefined);
+        this.pendingMutations.push(pending);
         this.scheduleSync();
     }
+    scheduleJournalFlush() {
+        if (this.journalFlushScheduled)
+            return;
+        this.journalFlushScheduled = true;
+        const schedule = typeof queueMicrotask === 'function'
+            ? queueMicrotask
+            : (callback) => { void Promise.resolve().then(callback); };
+        schedule(() => {
+            this.journalFlushScheduled = false;
+            const batch = this.pendingJournalBatch;
+            this.pendingJournalBatch = [];
+            void this.flushPendingMutationJournal(batch);
+        });
+    }
+    async flushPendingMutationJournal(batch) {
+        if (batch.length === 0)
+            return;
+        if (!this.userId || !this.organizationId) {
+            // Startup writes remain behind their unresolved journal promise. Identity
+            // initialization re-kicks this batch once its durable scope is known.
+            this.pendingJournalBatch = [...batch, ...this.pendingJournalBatch];
+            return;
+        }
+        try {
+            const records = batch.map((mutation) => this.pendingMutationRecord(mutation));
+            const database = this.database;
+            if (database.saveTransactions) {
+                await database.saveTransactions(records);
+            }
+            else {
+                await Promise.all(records.map((record) => database.saveTransaction(record)));
+            }
+            for (const mutation of batch)
+                mutation.resolveJournal?.();
+        }
+        catch (error) {
+            for (const mutation of batch)
+                mutation.rejectJournal?.(error);
+        }
+        finally {
+            for (const mutation of batch) {
+                mutation.resolveJournal = undefined;
+                mutation.rejectJournal = undefined;
+            }
+        }
+    }
     syncScheduled = false;
     scheduleSync() {
         if (this.syncScheduled)
@@ -980,7 +1145,6 @@ export class SyncClient extends EventEmitter {
             : (cb) => Promise.resolve().then(cb);
         schedule(() => {
             this.syncScheduled = false;
-            void this.persistMutationQueue();
             if (getContext().onlineStatus.isOnline()) {
                 this.processPendingMutations().catch((err) => {
                     getContext().observability.breadcrumb('Background sync failed', 'sync.transaction', 'warning', { error: err instanceof Error ? err.message : String(err) });
@@ -988,69 +1152,136 @@ export class SyncClient extends EventEmitter {
             }
         });
     }
-    /**
-     * Persist mutation queue to IndexedDB
-     */
-    async persistMutationQueue() {
-        if (!this.database || !this.userId)
-            return;
-        try {
-            const serializedMutations = this.pendingMutations.map((m) => ({
-                type: m.type,
-                modelData: m.model.toJSON ? m.model.toJSON() : { ...m.model },
-                modelName: m.model.getModelName(),
-                timestamp: m.timestamp.toISOString(),
-                writeOptions: m.writeOptions,
-            }));
-            await this.database.saveTransaction({
-                id: 'mutation-queue',
-                type: 'queue',
-                mutations: serializedMutations,
-                timestamp: Date.now(),
-            });
-        }
-        catch (error) {
-            // Best-effort persistence — the in-memory queue still processes; only
-            // a tab close before reconnect loses these. Forensic → debug.
-            getContext().logger.debug('[SyncClient] Failed to persist offline mutation queue', {
-                error: error instanceof Error ? error.message : String(error),
-            });
+    pendingMutationRecord(mutation) {
+        if (!this.userId || !this.organizationId) {
+            throw new AbloValidationError('Cannot persist a mutation before participant scope is initialized', { code: 'write_options_invalid' });
         }
+        return pendingMutationRecordSchema.parse({
+            id: pendingMutationRecordId(mutation.mutationId),
+            type: 'pending_mutation',
+            storageVersion: 2,
+            mutation: {
+                mutationId: mutation.mutationId,
+                type: mutation.type,
+                modelData: mutation.modelData,
+                modelName: mutation.model.getModelName(),
+                timestamp: mutation.timestamp.toISOString(),
+                ...(mutation.capturedChanges !== undefined
+                    ? { capturedChanges: mutation.capturedChanges }
+                    : {}),
+                ...(mutation.writeOptions !== undefined
+                    ? { writeOptions: mutation.writeOptions }
+                    : {}),
+            },
+            scope: {
+                organizationId: this.organizationId,
+                participantId: this.userId,
+                namespace: this.commitOutboxNamespace,
+            },
+            timestamp: mutation.timestamp.getTime(),
+        });
+    }
+    async persistPendingMutation(mutation) {
+        await this.database.saveTransaction(this.pendingMutationRecord(mutation));
     }
     /**
-     * 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() {
+    async restoreMutationQueue(sealedMutationIds = new Set()) {
         if (!this.database || !this.userId)
             return;
         try {
             const stored = await this.database.getPersistedTransactions();
-            const queue = stored.find((t) => t.id === 'mutation-queue');
-            if (queue?.mutations) {
-                for (const mutation of queue.mutations) {
-                    const parsed = persistedMutationSchema.safeParse(mutation);
-                    if (!parsed.success) {
-                        getContext().logger.debug('[SyncClient] Dropping malformed persisted mutation', {
-                            issues: parsed.error.issues.map((i) => i.path.join('.')).join(', '),
-                        });
-                        continue;
+            const restoredMutationIds = new Set();
+            let heldForReview = 0;
+            const restore = async (mutation, migrateLegacy, legacyMutationId) => {
+                const parsed = persistedMutationSchema.safeParse(mutation);
+                if (!parsed.success) {
+                    getContext().logger.debug('[SyncClient] Dropping malformed persisted mutation', {
+                        issues: parsed.error.issues.map((i) => i.path.join('.')).join(', '),
+                    });
+                    return;
+                }
+                // The window is anchored to when the write was made, because a
+                // record re-sealed on restore would otherwise reset its own expiry
+                // clock. An unparseable timestamp is held rather than replayed.
+                const writtenAt = Date.parse(parsed.data.timestamp);
+                const age = Date.now() - writtenAt;
+                if (!(age < PENDING_MUTATION_REPLAY_WINDOW_MS)) {
+                    heldForReview += 1;
+                    getContext().logger.warn('A saved local write is older than the server idempotency window and was held for review.');
+                    return;
+                }
+                const mutationId = parsed.data.mutationId ?? legacyMutationId ?? `mutation_${uuid()}`;
+                if (sealedMutationIds.has(mutationId) ||
+                    restoredMutationIds.has(mutationId))
+                    return;
+                const model = this.objectPool.createFromData(parsed.data.modelData);
+                if (model) {
+                    const pending = {
+                        mutationId,
+                        type: parsed.data.type,
+                        model,
+                        modelData: parsed.data.modelData,
+                        timestamp: new Date(parsed.data.timestamp),
+                        ...(parsed.data.capturedChanges !== undefined
+                            ? { capturedChanges: parsed.data.capturedChanges }
+                            : {}),
+                        ...(parsed.data.writeOptions !== undefined
+                            ? { writeOptions: parsed.data.writeOptions }
+                            : {}),
+                        journaled: Promise.resolve(),
+                        // Restored mutations have no live `wait: 'confirmed'` caller, so
+                        // their staging needs no waiter handshake.
+                        staged: Promise.resolve(),
+                    };
+                    if (migrateLegacy) {
+                        pending.journaled = this.persistPendingMutation(pending);
+                        await pending.journaled;
                     }
-                    const model = this.objectPool.createFromData(parsed.data.modelData);
-                    if (model) {
-                        this.pendingMutations.push({
-                            type: parsed.data.type,
-                            model,
-                            timestamp: new Date(parsed.data.timestamp),
-                            ...(parsed.data.writeOptions !== undefined
-                                ? { writeOptions: parsed.data.writeOptions }
-                                : {}),
-                        });
+                    this.pendingMutations.push(pending);
+                    restoredMutationIds.add(mutationId);
+                }
+            };
+            for (const row of stored) {
+                if (row.type !== 'pending_mutation')
+                    continue;
+                const parsed = pendingMutationRecordSchema.safeParse(row);
+                if (!parsed.success) {
+                    const legacy = legacyPendingMutationRecordSchema.safeParse(row);
+                    if (legacy.success) {
+                        await restore(legacy.data.mutation, true);
+                        continue;
                     }
+                    getContext().logger.debug('[SyncClient] Dropping malformed pending mutation record', {
+                        rowId: row.id,
+                    });
+                    continue;
+                }
+                if (parsed.data.scope.organizationId !== this.organizationId ||
+                    parsed.data.scope.participantId !== this.userId ||
+                    parsed.data.scope.namespace !== this.commitOutboxNamespace) {
+                    getContext().logger.warn('A saved local write belongs to a different account or server and was held for review.');
+                    continue;
+                }
+                await restore(parsed.data.mutation, false);
+            }
+            const legacyQueue = stored.find((row) => row.id === 'mutation-queue');
+            if (legacyQueue?.mutations) {
+                const heldBefore = heldForReview;
+                for (const [index, mutation] of legacyQueue.mutations.entries()) {
+                    await restore(mutation, true, `legacy_mutation_${index}`);
+                }
+                // Deleting the legacy row would discard any entry held for review, so
+                // it is only removed once every entry has migrated.
+                if (heldForReview === heldBefore) {
+                    await this.database.removeTransaction('mutation-queue');
                 }
             }
         }
@@ -1102,17 +1333,45 @@ export class SyncClient extends EventEmitter {
             return; // Skip if offline
         if (this.isDisposed)
             return; // Skip if disposed
-        const mutations = this.pendingMutations;
-        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
+        if (this.stagedMutationIds.size > 0)
+            return;
+        const mutations = this.pendingMutations.filter((mutation) => !this.stagedMutationIds.has(mutation.mutationId)).slice(0, 500);
+        if (mutations.length === 0)
+            return;
+        // Claim the batch BEFORE awaiting the journal. This method runs
+        // concurrently — the scheduleSync microtask and a direct syncNow() caller
+        // land in the same tick — and both would otherwise capture this same
+        // batch, suspend on the identical `journaled` promises, and stage every
+        // mutation twice (two transactions on the wire for one write). Claiming
+        // synchronously makes the second caller hit the guard above and return.
         for (const mutation of mutations) {
-            // Skip mutations for deleted models (prevents "not found" errors)
-            if (mutation.type !== 'delete' && !this.objectPool.get(mutation.model.id)) {
-                continue;
+            this.stagedMutationIds.add(mutation.mutationId);
+        }
+        // A journal rejection is permanent for that mutation (fail-closed: it can
+        // never dispatch without its durable record), so drop it rather than
+        // leaving it queued to poison every later pass. Healthy batch members
+        // still stage.
+        const journalResults = await Promise.allSettled(mutations.map((mutation) => mutation.journaled));
+        const journaledMutations = [];
+        journalResults.forEach((result, index) => {
+            const mutation = mutations[index];
+            if (result.status === 'fulfilled') {
+                journaledMutations.push(mutation);
+                return;
             }
+            this.stagedMutationIds.delete(mutation.mutationId);
+            this.pendingMutations = this.pendingMutations.filter((pending) => pending.mutationId !== mutation.mutationId);
+            mutation.rejectStaged?.(result.reason);
+            getContext().observability.captureTransactionFailure({
+                context: 'persist-pending-mutation',
+                error: result.reason instanceof Error
+                    ? result.reason
+                    : new Error(String(result.reason)),
+            });
+        });
+        // 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
             this.stageMutation(mutation);
         }
@@ -1123,8 +1382,12 @@ export class SyncClient extends EventEmitter {
      * @param mutation.capturedChanges - Pre-captured changes to use instead of re-reading from model
      */
     stageMutation(mutation) {
-        if (!this.userId || !this.organizationId)
+        if (!this.userId || !this.organizationId) {
+            // Nothing will stage this call; settle the waiter with the legacy
+            // "silently dropped" semantics rather than hanging a `wait: 'confirmed'`.
+            mutation.resolveStaged?.();
             return;
+        }
         const ctx = { userId: this.userId, organizationId: this.organizationId };
         // Settlement is delivered via transaction.confirmation, not this promise —
         // it only rejects when staging itself throws (change extraction, optimistic
@@ -1137,23 +1400,23 @@ export class SyncClient extends EventEmitter {
                 modelId: mutation.model.id,
                 error: error instanceof Error ? error : new Error(String(error)),
             });
+            this.stagedMutationIds.delete(mutation.mutationId);
         };
-        if (mutation.type === 'update') {
-            this.transactionQueue
-                .update(mutation.model, ctx, mutation.capturedChanges, mutation.writeOptions)
-                .catch(captureStagingFailure);
-        }
-        else {
-            const handler = this.transactionQueue[mutation.type].bind(this.transactionQueue);
-            handler(mutation.model, ctx, mutation.writeOptions).catch(captureStagingFailure);
-        }
+        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);
+        staging
+            .then(() => mutation.resolveStaged?.())
+            .catch((error) => {
+            captureStagingFailure(error);
+            mutation.rejectStaged?.(error);
+        });
     }
     /**
-     * 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 +1481,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 +1530,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 +1545,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');
     }
     /**
@@ -1368,6 +1628,16 @@ export class SyncClient extends EventEmitter {
      */
     markConnected() {
         this.setConnectionState('connected');
+        // 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({
+                context: 'restore-commit-outbox',
+                error: error instanceof Error ? error : new Error(String(error)),
+            });
+        });
+        void this.processPendingMutations();
     }
     /**
      * Dispose and cleanup
@@ -1381,9 +1651,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 +1667,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);
@@ -1420,12 +1690,19 @@ export class SyncClient extends EventEmitter {
      * Force sync now - process pending mutations
      */
     async syncNow() {
+        // Snapshot before draining: a concurrent drain may already have claimed
+        // this caller's write, in which case processPendingMutations returns
+        // without staging anything. `wait: 'confirmed'` resolves on finding no
+        // in-flight work, so it must not run until every write queued before this
+        // call has a real transaction in the queue or was definitively dropped.
+        const queuedBeforeCall = this.pendingMutations.map((mutation) => mutation.staged);
         await this.processPendingMutations();
+        await Promise.allSettled(queuedBeforeCall);
     }
     /**
      * 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,28 +1737,41 @@ 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);
+        const snapshotsByCommit = new Map();
+        const onCommitStaging = (payload) => {
+            snapshotsByCommit.set(payload.clientTxId, payload.operations.map((operation) => {
+                if (operation.type === 'CREATE')
+                    return undefined;
+                const resident = this.objectPool.get(operation.id);
+                return resident?.toJSON();
+            }));
+        };
+        const onCommitSealFailed = (payload) => {
+            snapshotsByCommit.delete(payload.clientTxId);
+        };
         // Commit-lane writes (`ablo.commits.create` — the agent/atomic door) ride
         // their own `commit:created` event: they have no optimistic pool apply,
         // so they must not feed the echo tracker's `transaction:created` path.
@@ -1489,6 +1779,8 @@ export class SyncClient extends EventEmitter {
         // (the queue is pool-free) and hand the synthesized transaction to the
         // same listener, so undo observes every write door — one stream.
         const onCommitCreated = (payload) => {
+            const stagedSnapshots = snapshotsByCommit.get(payload.clientTxId);
+            snapshotsByCommit.delete(payload.clientTxId);
             const TYPE_BY_WIRE = {
                 CREATE: 'create',
                 UPDATE: 'update',
@@ -1500,8 +1792,11 @@ export class SyncClient extends EventEmitter {
                 const type = TYPE_BY_WIRE[op.type];
                 if (!type || !op.id)
                     return;
-                const resident = this.objectPool.get(op.id);
-                const snapshot = type === 'create' ? undefined : resident?.toJSON();
+                const snapshot = type === 'create'
+                    ? undefined
+                    : stagedSnapshots
+                        ? stagedSnapshots[index]
+                        : this.objectPool.get(op.id)?.toJSON();
                 // A DELETE of a row the local graph never saw is not invertible —
                 // recording it would make undo "restore" an empty husk. Skip it.
                 if (type === 'delete' && !snapshot)
@@ -1532,10 +1827,15 @@ export class SyncClient extends EventEmitter {
                 });
             });
         };
+        this.transactionQueue.on('commit:staging', onCommitStaging);
+        this.transactionQueue.on('commit:seal_failed', onCommitSealFailed);
         this.transactionQueue.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);
+            snapshotsByCommit.clear();
         };
     }
     /**
@@ -1574,11 +1874,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 +1900,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 +1933,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 +2006,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 +2033,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 +2071,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 +2100,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 = [];