@abloatai/ablo 0.25.0 → 0.27.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 { 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';
 import { getContext } from './context.js';
@@ -16,16 +17,18 @@ import { AbloAuthenticationError, AbloError, AbloValidationError } from './error
 import { EventEmitter } from 'events';
 import { NetworkMonitor } from './NetworkMonitor.js';
 import { TransactionQueue } from './transactions/TransactionQueue.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;
@@ -43,6 +46,22 @@ function rawRecordIsNewer(data, existing) {
         return true;
     return inMs > exMs;
 }
+/**
+ * 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)
+        return 0;
+    if (value instanceof Date)
+        return value.getTime();
+    if (typeof value === 'string' || typeof value === 'number') {
+        return new Date(value).getTime();
+    }
+    return 0;
+}
 export class SyncClient extends EventEmitter {
     objectPool;
     database;
@@ -56,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.
-     *
-     * 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).
+     * 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.
      *
-     * 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) {
@@ -92,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,
@@ -104,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();
@@ -122,8 +138,25 @@ export class SyncClient extends EventEmitter {
      * Setup network monitoring handlers
      */
     setupNetworkMonitoring() {
-        this.networkMonitor.on('online', () => this.handleReconnection());
-        this.networkMonitor.on('offline', () => this.handleDisconnection());
+        // Both handlers emit to external listeners (which can throw) before/around
+        // their own try/catch — route rejections into observability rather than
+        // losing a failed reconnect flush silently.
+        this.networkMonitor.on('online', () => {
+            void this.handleReconnection().catch((error) => {
+                getContext().observability.captureTransactionFailure({
+                    context: 'network-online-reconnection',
+                    error: error instanceof Error ? error : new Error(String(error)),
+                });
+            });
+        });
+        this.networkMonitor.on('offline', () => {
+            void this.handleDisconnection().catch((error) => {
+                getContext().observability.captureTransactionFailure({
+                    context: 'network-offline-handler',
+                    error: error instanceof Error ? error : new Error(String(error)),
+                });
+            });
+        });
     }
     /**
      * Handle transaction rollback. Two distinct shapes flow through this
@@ -254,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) => {
@@ -275,52 +308,20 @@ 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', async (event) => {
-            if (!this.database)
-                return;
-            try {
-                await this.database.saveTransaction({
-                    id: `awaiting_${event.txId}`,
-                    type: 'awaiting_delta',
-                    timestamp: Date.now(),
-                    awaitingDelta: {
-                        syncIdNeeded: event.syncIdNeeded ?? 0,
-                        modelName: event.model,
-                        modelId: event.modelId,
-                        operationType: event.operationType,
-                    },
-                });
-                getContext().observability.breadcrumb('Persisted unconfirmed transaction to IDB', 'sync.transaction', 'info', {
-                    txId: event.txId,
-                    model: event.model,
-                    modelId: event.modelId,
-                });
-            }
-            catch (error) {
-                getContext().observability.captureTransactionFailure({
-                    context: 'persist-awaiting-transaction',
-                    modelName: event.model,
-                    modelId: event.modelId,
-                    error: error instanceof Error ? error : new Error(String(error)),
-                });
-            }
+        this.transactionQueue.on('transaction:persist_awaiting', (event) => {
+            // void is safe: the handler's body is fully try/catch'd.
+            void this.persistAwaitingTransaction(event);
         });
         // Clean up persisted awaiting transactions when they're finally confirmed
-        this.transactionQueue.on('transaction:completed', async (tx) => {
-            if (!this.database)
-                return;
-            try {
-                await this.database.removeTransaction(`awaiting_${tx.id}`);
-            }
-            catch {
-                // Ignore — might not have been persisted
-            }
+        this.transactionQueue.on('transaction:completed', (tx) => {
+            // void is safe: the handler's body is fully try/catch'd.
+            void this.removeAwaitingTransaction(tx.id);
         });
         // Echo detection bridge. When the queue stages a transaction, the
         // client has already optimistically applied the change to the
@@ -338,6 +339,48 @@ export class SyncClient extends EventEmitter {
             this.echoTracker.drainOnRollback(event.transaction.id);
         });
     }
+    /** Persist an unconfirmed transaction to IndexedDB (never rejects — failures are captured). */
+    async persistAwaitingTransaction(event) {
+        if (!this.database)
+            return;
+        try {
+            await this.database.saveTransaction({
+                id: `awaiting_${event.txId}`,
+                type: 'awaiting_delta',
+                timestamp: Date.now(),
+                awaitingDelta: {
+                    syncIdNeeded: event.syncIdNeeded ?? 0,
+                    modelName: event.model,
+                    modelId: event.modelId,
+                    operationType: event.operationType,
+                },
+            });
+            getContext().observability.breadcrumb('Persisted unconfirmed transaction to IDB', 'sync.transaction', 'info', {
+                txId: event.txId,
+                model: event.model,
+                modelId: event.modelId,
+            });
+        }
+        catch (error) {
+            getContext().observability.captureTransactionFailure({
+                context: 'persist-awaiting-transaction',
+                modelName: event.model,
+                modelId: event.modelId,
+                error: error instanceof Error ? error : new Error(String(error)),
+            });
+        }
+    }
+    /** Drop the persisted awaiting-row once confirmed (never rejects). */
+    async removeAwaitingTransaction(txId) {
+        if (!this.database)
+            return;
+        try {
+            await this.database.removeTransaction(`awaiting_${txId}`);
+        }
+        catch {
+            // Ignore — might not have been persisted
+        }
+    }
     /**
      * Initialize sync client with authentication
      */
@@ -347,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');
         }
     }
@@ -375,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
@@ -431,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() {
@@ -483,8 +524,9 @@ export class SyncClient extends EventEmitter {
                 // Persist healed records back to IndexedDB (fire-and-forget, non-blocking)
                 if (recordsToHeal.length > 0 && this.database) {
                     getContext().logger.info(`[SyncClient.hydrate] Persisting ${recordsToHeal.length} healed ${modelType} records to IndexedDB`);
-                    // Use fire-and-forget to not block hydration
-                    Promise.resolve().then(async () => {
+                    // Use fire-and-forget to not block hydration.
+                    // void is safe: the handler's body is fully try/catch'd.
+                    void Promise.resolve().then(async () => {
                         try {
                             for (const { id, data } of recordsToHeal) {
                                 await this.database.putRecord(modelType, id, data);
@@ -501,13 +543,6 @@ export class SyncClient extends EventEmitter {
                     });
                 }
                 const typeEnd = typeof performance !== 'undefined' ? performance.now() : Date.now();
-                // Dev-only hydration summary
-                if (modelType === 'InboxItem' && process.env.NODE_ENV !== 'production') {
-                    getContext().logger.debug('[SyncClient] InboxItem hydration summary', {
-                        fetched: rawData.length,
-                        added: modelsForType.length,
-                    });
-                }
                 perTypePerfLogs.push({
                     type: modelType,
                     fetched: rawData.length,
@@ -552,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:
@@ -600,7 +635,8 @@ export class SyncClient extends EventEmitter {
                         if (this.database) {
                             const id = healResult.data.id;
                             const healedData = healResult.data;
-                            Promise.resolve().then(async () => {
+                            // void is safe: the handler's body is fully try/catch'd.
+                            void Promise.resolve().then(async () => {
                                 try {
                                     await this.database.putRecord(modelType, id, healedData);
                                 }
@@ -686,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.
+     * 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
@@ -709,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 });
@@ -755,11 +792,11 @@ export class SyncClient extends EventEmitter {
     }
     /** Add new model (CREATE) - works offline */
     add(model, options) {
-        this.mutate('create', model, () => this.objectPool.add(model, ModelScope.live), options);
+        this.mutate('create', model, () => { this.objectPool.add(model, ModelScope.live); }, options);
     }
     /** Update existing model (UPDATE) - works offline */
     update(model, options) {
-        this.mutate('update', model, () => this.objectPool.upsert(model, ModelScope.live), options);
+        this.mutate('update', model, () => { this.objectPool.upsert(model, ModelScope.live); }, options);
     }
     /**
      * Update existing model with pre-computed changes.
@@ -822,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) {
@@ -912,19 +950,20 @@ export class SyncClient extends EventEmitter {
     }
     /** Archive model (ARCHIVE) - works offline */
     archive(model) {
-        this.mutate('archive', model, () => this.objectPool.updateScope(model.id, ModelScope.archived));
+        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);
@@ -969,10 +1008,22 @@ export class SyncClient extends EventEmitter {
                 timestamp: Date.now(),
             });
         }
-        catch (error) { }
+        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),
+            });
+        }
     }
     /**
-     * Restore mutation queue from IndexedDB
+     * Restore the mutation queue from IndexedDB.
+     *
+     * 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)
@@ -982,19 +1033,39 @@ export class SyncClient extends EventEmitter {
             const queue = stored.find((t) => t.id === 'mutation-queue');
             if (queue?.mutations) {
                 for (const mutation of queue.mutations) {
-                    const model = this.objectPool.createFromData(mutation.modelData);
+                    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 model = this.objectPool.createFromData(parsed.data.modelData);
                     if (model) {
                         this.pendingMutations.push({
-                            type: mutation.type,
+                            type: parsed.data.type,
                             model,
-                            timestamp: new Date(mutation.timestamp),
-                            writeOptions: mutation.writeOptions,
+                            timestamp: new Date(parsed.data.timestamp),
+                            ...(parsed.data.writeOptions !== undefined
+                                ? { writeOptions: parsed.data.writeOptions }
+                                : {}),
                         });
                     }
                 }
             }
         }
-        catch (error) { }
+        catch (error) {
+            // A restore failure means queued offline writes did NOT rehydrate.
+            // Self-healing is impossible here (the record may be unreadable), but
+            // the failure must be visible for diagnosis instead of silent loss.
+            getContext().logger.debug('[SyncClient] Failed to restore offline mutation queue', {
+                error: error instanceof Error ? error.message : String(error),
+            });
+            getContext().observability.captureTransactionFailure({
+                context: 'restore-mutation-queue',
+                error: error instanceof Error ? error : String(error),
+            });
+        }
     }
     /**
      * Process pending mutations - can be called by SyncedStore when online
@@ -1035,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)) {
@@ -1055,20 +1126,33 @@ export class SyncClient extends EventEmitter {
         if (!this.userId || !this.organizationId)
             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
+        // apply, store add). That means the write never entered the queue, so
+        // capture it instead of dropping it silently.
+        const captureStagingFailure = (error) => {
+            getContext().observability.captureTransactionFailure({
+                context: `stage-mutation-${mutation.type}`,
+                modelName: mutation.model.getModelName(),
+                modelId: mutation.model.id,
+                error: error instanceof Error ? error : new Error(String(error)),
+            });
+        };
         if (mutation.type === 'update') {
-            this.transactionQueue.update(mutation.model, ctx, mutation.capturedChanges, mutation.writeOptions);
+            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);
+            handler(mutation.model, ctx, mutation.writeOptions).catch(captureStagingFailure);
         }
     }
     /**
-     * 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;
@@ -1078,7 +1162,7 @@ export class SyncClient extends EventEmitter {
                 ? localModel.updatedAt.getTime()
                 : new Date(localModel.updatedAt).getTime()
             : 0;
-        const serverUpdatedAt = serverData?.updatedAt ? new Date(serverData.updatedAt).getTime() : 0;
+        const serverUpdatedAt = toEpochMs(serverData.updatedAt);
         getContext().logger.debug('Conflict resolution', {
             modelId: localModel.id,
             modelType: localModel.getModelName(),
@@ -1114,7 +1198,7 @@ export class SyncClient extends EventEmitter {
             // Merge: server baseline + local dirty fields win
             const merged = { ...serverData, ...(localChanges || {}) };
             // Preserve the most recent updatedAt without clearing dirty flags
-            if (serverData?.updatedAt || localModel.updatedAt) {
+            if (serverData.updatedAt || localModel.updatedAt) {
                 const mergedUpdatedAt = new Date(Math.max(localUpdatedAt, serverUpdatedAt));
                 // updateFromData accepts Date or ISO string for dates
                 merged.updatedAt = mergedUpdatedAt;
@@ -1133,8 +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
+     * 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 = {};
@@ -1181,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({
@@ -1198,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');
     }
     /**
@@ -1295,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 {
@@ -1310,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);
@@ -1339,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 {
@@ -1374,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);
@@ -1488,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
@@ -1514,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;
@@ -1547,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;
             }
@@ -1622,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);
@@ -1651,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) {
@@ -1689,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)) {
@@ -1718,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 = [];