@abloatai/humans 0.37.0

package/dist/local/SyncClient.js

@@ -0,0 +1,1754 @@
+/**
+ * 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 MutationQueue} that delivers writes
+ * over the network.
+ */
+import { runInAction } from 'mobx';
+import { InstanceCache, ModelScope } from './InstanceCache.js';
+import { Model } from './Model.js';
+import { snapshotJsonValue } from '@abloatai/transaction/utils/json';
+// ModelRegistry instance accessed via this.objectPool.registry
+import { LoadStrategy } from '@abloatai/transaction/types';
+import { globalRuntime } from './context.js';
+import { AbloAuthenticationError, AbloError, AbloValidationError } from '@abloatai/transaction/errors';
+import { EventEmitter } from 'events';
+import { NetworkMonitor } from './NetworkMonitor.js';
+import { MutationQueue, } from './transactions/mutations/MutationQueue.js';
+import { observeCommitLatency, } from './transactions/mutations/commitLatency.js';
+import { UnconfirmedWrites, } from './transactions/mutations/UnconfirmedWrites.js';
+import { LogPosition } from './logPosition.js';
+import { createLocalMutationPort } from './transactions/localMutation.js';
+import { createReconnectDrain } from './transactions/reconnectDrain.js';
+import { DatabaseCommitOutboxStore } from './transactions/databaseCommitOutbox.js';
+/**
+ * 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;
+    const inMs = raw instanceof Date
+        ? raw.getTime()
+        : typeof raw === 'string'
+            ? (Number.isNaN(Date.parse(raw)) ? undefined : Date.parse(raw))
+            : typeof raw === 'number'
+                ? raw
+                : undefined;
+    const exMs = existing.updatedAt instanceof Date ? existing.updatedAt.getTime() : undefined;
+    if (inMs === undefined)
+        return false;
+    if (exMs === undefined)
+        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 {
+    runtime;
+    objectPool;
+    database;
+    mutationPersistence;
+    reconnectDrain = createReconnectDrain();
+    get mutationExecutor() { return this.runtime.mutationExecutor; }
+    networkMonitor;
+    /**
+     * @internal — test seam, stripped from the published declarations by
+     * `stripInternal`. Unit suites deliver queue lifecycle events directly.
+     */
+    mutationQueue;
+    observers = new Set();
+    // Authentication context
+    userId = null;
+    organizationId = null;
+    // The MutationQueue is the sole owner of queued transaction state.
+    pendingStages = new Set();
+    commitOutboxNamespace;
+    /** Compatibility view for diagnostics; transaction state lives in the queue. */
+    get pendingMutations() {
+        const transactions = [...this.mutationQueue.getOutstandingTransactions()];
+        const deferredCount = this.mutationQueue.getOutstandingTransactionCount() - transactions.length;
+        return deferredCount > 0
+            ? [...transactions, ...Array.from({ length: deferredCount })]
+            : transactions;
+    }
+    /**
+     * 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 set is bounded with first-in-first-out eviction, and
+     * {@link SyncClient.getEchoMetrics} exposes its counters.
+     */
+    echoTracker = new UnconfirmedWrites();
+    // Connection state
+    connectionState = 'disconnected';
+    // Configuration
+    isDisposed = false;
+    /**
+     * The client's position in the global delta order, held as the single
+     * canonical {@link LogPosition} instance. The store advances `applied` and
+     * `persisted` as deltas land, the queue advances `acked` on commit
+     * responses, and snapshots and claims read `readFloor`.
+     */
+    position = new LogPosition();
+    constructor(objectPool, database, commitOutbox = new DatabaseCommitOutboxStore(database), commitOutboxNamespace = 'default', runtime = globalRuntime) {
+        super();
+        this.runtime = runtime;
+        this.objectPool = objectPool;
+        this.database = database;
+        this.mutationPersistence = {
+            saveTransaction: (transaction) => database.saveTransaction(snapshotJsonValue(transaction, '$.pendingMutation')),
+            removeTransaction: (id) => database.removeTransaction(id),
+            getPersistedTransactions: () => database.getPersistedTransactions(),
+        };
+        this.commitOutboxNamespace = commitOutboxNamespace;
+        this.networkMonitor = new NetworkMonitor(this.runtime);
+        // Initialize MutationQueue with proper configuration
+        const localMutationPort = createLocalMutationPort((event, payload) => {
+            this.mutationQueue.emit(event, payload);
+        });
+        this.mutationQueue = new MutationQueue({
+            position: this.position,
+            runtime: this.runtime,
+            localMutationPort,
+            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,
+            enablePersistence: true,
+            conflictResolution: {
+                strategy: 'last-write-wins',
+            },
+        });
+        this.mutationQueue.setPersistence(this.mutationPersistence);
+        this.mutationQueue.setCommitOutbox(commitOutbox);
+        // Provide connection state to MutationQueue - prevents rollbacks during disconnection
+        this.mutationQueue.setConnectionChecker(() => this.connectionState === 'connected');
+        // Restore object-pool state when a transaction is rolled back. If the
+        // server rejects a write or it times out, the model's previous state is
+        // put back. Because writes are no longer applied to IndexedDB
+        // optimistically, that store already holds the correct state.
+        this.setupTransactionRollbackHandling();
+        // 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();
+        // 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();
+    }
+    /**
+     * Setup network monitoring handlers
+     */
+    setupNetworkMonitoring() {
+        // 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) => {
+                this.runtime.observability.captureMutationFailure({
+                    context: 'network-online-reconnection',
+                    error: error instanceof Error ? error : new Error(String(error)),
+                });
+            });
+        });
+        this.networkMonitor.on('offline', () => {
+            void this.handleDisconnection().catch((error) => {
+                this.runtime.observability.captureMutationFailure({
+                    context: 'network-offline-handler',
+                    error: error instanceof Error ? error : new Error(String(error)),
+                });
+            });
+        });
+    }
+    /**
+     * Handle transaction rollback. Two distinct shapes flow through this
+     * event:
+     *
+     *   1. **Server-rejected rollback** (`reason === 'permanent_error'`,
+     *      `'max_retries_exhausted'`, `'conflict_server_wins'`) — the
+     *      optimistic state is wrong, the row exists, restore previous
+     *      state and notify the UI.
+     *
+     *   2. **Local-cancellation cleanup** (`reason === 'model_cancelled'`,
+     *      `'cascade_parent_deleted'`) — the user deleted this model (or
+     *      its parent), so a pending UPDATE on it gets cancelled. There's
+     *      nothing to restore (the model is doomed) and no UI notification
+     *      needed (the delete itself already triggered re-renders). Just
+     *      discard the optimistic state silently.
+     *
+     * Treating both paths the same caused the deletion-flicker bug: every
+     * cancelled update on a multi-child record fired a per-model observer
+     * event and a `[SyncClient.rollback]` warn, producing N renders and N
+     * spam log lines for one user-initiated delete.
+     */
+    setupTransactionRollbackHandling() {
+        this.mutationQueue.on('optimistic:rollback', (event) => {
+            const { model, previousState, transaction, reason, error } = event;
+            // Local cleanup path — discard quietly. The optimistic state was
+            // applied to a model that's already disposed by the cascading
+            // delete, and emitting per-model observer events here would
+            // re-render N times for one user-initiated cascade.
+            if (reason === 'model_cancelled' || reason === 'cascade_parent_deleted') {
+                return;
+            }
+            // Surface the typed AbloError fields directly — `type`/`code`/
+            // `httpStatus`/`requestId` are what tell us the rollback cause
+            // (e.g. `AbloValidationError` with `code: 'schema_...'`,
+            // `AbloServerError` with `httpStatus: 500`). Falling back to
+            // generic message lets us still see unstructured errors.
+            // Mechanic-level breadcrumb only. The authoritative, user-facing
+            // reason is logged once at `warn` by `MutationQueue.handleFailure`
+            // (`Permanent error - rolling back`). Logging the same typed cause
+            // again here at `warn` is what produced three identical dumps per
+            // rejected write — keep it at `debug` so the rollback mechanics are
+            // available when debugging but don't double the console noise.
+            const abloErr = error instanceof AbloError ? error : undefined;
+            this.runtime.logger.debug('[SyncClient.rollback]', {
+                txType: transaction.type,
+                modelName: transaction.modelName,
+                modelId: transaction.modelId.slice(0, 12),
+                reason: reason ?? 'unknown',
+                errorType: abloErr?.type ?? error?.name,
+                errorCode: abloErr?.code,
+                httpStatus: abloErr?.httpStatus,
+                requestId: abloErr?.requestId,
+                message: error?.message,
+            });
+            this.runtime.observability.captureRollback({
+                transactionType: transaction.type,
+                modelName: transaction.modelName,
+                modelId: transaction.modelId,
+                reason: reason ?? 'unknown',
+                error: error?.message,
+                connectionState: this.connectionState,
+            });
+            try {
+                if (transaction.type === 'create') {
+                    // CREATE rollback: remove the optimistically created entity
+                    this.objectPool.remove(transaction.modelId);
+                }
+                else if (transaction.type === 'delete' &&
+                    reason === 'permanent_error' &&
+                    error?.message?.includes('not found')) {
+                    // DELETE "not found" rollback: the entity doesn't exist on the server.
+                    // Instead of restoring a ghost entity, remove it locally too.
+                    // Both sides agree: this entity should not exist.
+                    this.runtime.observability.breadcrumb('DELETE rolled back with "not found" - removing ghost entity', 'sync.conflict', 'info', {
+                        modelId: transaction.modelId,
+                        modelName: transaction.modelName,
+                    });
+                    this.objectPool.remove(transaction.modelId);
+                }
+                else if (model) {
+                    // For update/delete/archive: restore model (with previousState if available)
+                    // Guard: if the model was disposed (e.g. by a concurrent DELETE rollback or
+                    // cascade), don't re-add it — Object.assign cannot restore the private
+                    // isDisposed flag, so the model would be added in a broken state.
+                    if (model.disposed) {
+                        // Follow-on of an already-logged permanent error, not its own
+                        // problem: the tx that failed has already surfaced the cause in
+                        // MutationQueue. Restoring a disposed model is a no-op by
+                        // design (can't revive the private isDisposed flag), so keep this
+                        // at `debug` instead of emitting a second `warn` that reads as a
+                        // distinct failure in the console.
+                        this.runtime.logger.debug('[SyncClient] Rollback skipped restore (model already disposed)', {
+                            modelId: transaction.modelId,
+                            modelName: transaction.modelName,
+                            reason,
+                        });
+                    }
+                    else {
+                        if (previousState)
+                            Object.assign(model, previousState);
+                        this.objectPool.add(model, ModelScope.live);
+                    }
+                }
+                this.notifyObservers({
+                    type: 'rollback',
+                    modelType: transaction.modelName,
+                    modelId: transaction.modelId,
+                    transactionType: transaction.type,
+                });
+                // Emit event so SyncedStore can clear pendingDeletes on delete rollback
+                this.emit('sync:rollback', {
+                    modelId: transaction.modelId,
+                    modelName: transaction.modelName,
+                    transactionType: transaction.type,
+                    reason,
+                });
+            }
+            catch (error) {
+                this.runtime.observability.captureMutationFailure({
+                    context: 'rollback-failed',
+                    transactionId: transaction.id,
+                    modelName: transaction.modelName,
+                    modelId: transaction.modelId,
+                    error: error instanceof Error ? error : new Error(String(error)),
+                });
+            }
+        });
+    }
+    /**
+     * Forward reconciliation requests from the {@link MutationQueue} to the
+     * sync layer. When delta confirmation times out, the queue emits
+     * `reconciliation:needed` instead of rolling back, so optimistic state the
+     * server may already have committed is never destroyed.
+     */
+    setupReconciliationForwarding() {
+        this.mutationQueue.on('reconciliation:needed', (event) => {
+            this.runtime.observability.captureReconciliation({
+                reason: event.reason,
+                model: event.model,
+                modelId: event.modelId,
+                syncIdNeeded: event.syncIdNeeded,
+                lastSeenSyncId: event.lastSeenSyncId,
+                retryCount: event.retryCount,
+                connectionState: this.connectionState,
+            });
+            // Forward to SyncedStore via event — it has access to the WebSocket
+            this.emit('reconciliation:needed', event);
+        });
+    }
+    /**
+     * 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.mutationQueue.on('transaction:persist_awaiting', (event) => {
+            // void is safe: the handler's body is fully try/catch'd.
+            void this.persistAwaitingTransaction(event);
+        });
+        // Clean up persisted awaiting transactions when they're finally confirmed
+        this.mutationQueue.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
+        // pool — record the tx id so the matching server delta echo gets
+        // recognized in `applyDeltaBatchToPool`. The set is drained when
+        // the echo lands; if a transaction is rolled back before the
+        // server processes it, we drain on rollback too so a stale id
+        // doesn't permanently silence a foreign delta sharing the same id
+        // (vanishingly unlikely for UUIDs, but cheap insurance).
+        this.mutationQueue.on('transaction:created', (tx) => {
+            if (!tx.localOnly)
+                this.echoTracker.markPending(tx.id);
+        });
+        this.mutationQueue.on('optimistic:rollback', (event) => {
+            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,
+                },
+            });
+            this.runtime.observability.breadcrumb('Persisted unconfirmed transaction to IDB', 'sync.transaction', 'info', {
+                txId: event.txId,
+                model: event.model,
+                modelId: event.modelId,
+            });
+        }
+        catch (error) {
+            this.runtime.observability.captureMutationFailure({
+                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
+     */
+    async initialize(userId, organizationId) {
+        this.userId = userId;
+        this.organizationId = organizationId;
+        this.runtime.observability.setContext(userId, organizationId);
+        await this.mutationQueue.setCommitOutboxScope({
+            organizationId,
+            participantId: userId,
+            namespace: this.commitOutboxNamespace,
+        });
+        // 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.mutationQueue.restoreDurableCommits();
+        await this.mutationQueue.loadPersistedTransactions(this.mutationPersistence, 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 (this.runtime.onlineStatus.isOnline()) {
+            this.setConnectionState('connected');
+        }
+        else {
+            // Offline - start in offline mode
+            this.setConnectionState('disconnected');
+            this.emit('sync:offline');
+        }
+        if (this.mutationQueue.getOutstandingTransactionCount() > 0) {
+            this.scheduleSync();
+        }
+    }
+    /**
+     * The organization this client writes under (set by `initialize`).
+     * Read by the model proxy so `create()` defaults `organizationId` the
+     * same way the mutator path does — `null` until identity is wired.
+     */
+    getOrganizationId() {
+        return this.organizationId;
+    }
+    /**
+     * Self-healing helper for individual model records.
+     *
+     * Two registry-driven repair passes run on every row hydrated from
+     * 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
+     *    (`organizationId` / `userId`) onto the row when it's missing.
+     *    Repairs rows from a past version that didn't write the field.
+     *
+     * 2. **Required-field gate** — if the row is missing any field listed
+     *    in the model's `requiredFields`, return `null` so the caller
+     *    skips this record. Used for FK columns whose absence renders the
+     *    row unrecoverable (e.g. a Block with no sectionId).
+     *
+     * The engine itself is product-neutral: model identity (which fields
+     * to back-fill, which absences are fatal) lives entirely in the
+     * consumer schema.
+     */
+    healModelRecord(modelType, data) {
+        const meta = this.objectPool.registry.getMetadata(modelType);
+        if (!meta)
+            return { data, healed: false };
+        const idPrefix = data.id?.slice(0, 8) ?? 'unknown';
+        let result = data;
+        let healed = false;
+        if (meta.autoFill) {
+            for (const rule of meta.autoFill) {
+                if (result[rule.field])
+                    continue;
+                const replacement = rule.from === 'organizationId' ? this.organizationId : this.userId;
+                if (!replacement)
+                    continue;
+                this.runtime.observability.captureSelfHealing({
+                    modelName: modelType,
+                    modelId: idPrefix,
+                    field: rule.field,
+                    action: `added missing ${rule.field}`,
+                });
+                result = { ...result, [rule.field]: replacement };
+                healed = true;
+            }
+        }
+        if (meta.requiredFields) {
+            for (const field of meta.requiredFields) {
+                if (result[field])
+                    continue;
+                this.runtime.observability.captureSelfHealing({
+                    modelName: modelType,
+                    modelId: idPrefix,
+                    field,
+                    action: `skipped corrupted ${modelType} - missing ${field}`,
+                });
+                return null;
+            }
+        }
+        return { data: result, healed };
+    }
+    /**
+     * Hydrate InstanceCache with data from Database
+     * Called after bootstrap is complete
+     */
+    async hydrateFromDatabase() {
+        if (!this.database) {
+            throw new AbloValidationError('Database not available for hydration', {
+                code: 'sync_client_db_missing',
+            });
+        }
+        // Get model types that should be hydrated on startup (skip lazy per LSE)
+        const modelTypes = this.objectPool.registry.getRegisteredModelNames().filter((name) => {
+            const meta = this.objectPool.registry.getMetadata(name);
+            return meta?.loadStrategy === LoadStrategy.instant;
+        });
+        const totalStart = typeof performance !== 'undefined' ? performance.now() : Date.now();
+        // Phase 1: Fetch all data from IndexedDB and create model instances (async I/O).
+        // We collect all models across ALL types before touching MobX, so that Phase 2
+        // can add them in a single addBatch() call → ONE MobX action → ONE re-render.
+        const allModelsToAdd = [];
+        const perTypePerfLogs = [];
+        for (const modelType of modelTypes) {
+            const typeStart = typeof performance !== 'undefined' ? performance.now() : Date.now();
+            try {
+                // Get raw data from Database (via StoreManager)
+                const rawData = await this.database.hydrateModels(modelType);
+                const afterFetch = typeof performance !== 'undefined' ? performance.now() : Date.now();
+                // Create models in batch first, collect for deferred addBatch
+                const modelsForType = [];
+                const recordsToHeal = [];
+                for (const data of rawData) {
+                    let withType = data && typeof data === 'object' && !data.__typename
+                        ? { __typename: modelType, ...data }
+                        : data;
+                    // Self-healing: Fix corrupted IndexedDB records missing essential fields
+                    const healResult = this.healModelRecord(modelType, withType);
+                    if (healResult === null) {
+                        continue; // Record is corrupted beyond repair — skip
+                    }
+                    withType = healResult.data;
+                    if (healResult.healed) {
+                        recordsToHeal.push({ id: healResult.data.id, data: healResult.data });
+                    }
+                    const model = this.objectPool.createFromData(withType);
+                    if (model) {
+                        modelsForType.push(model);
+                    }
+                }
+                // Collect models for the single batched addBatch call in Phase 2
+                allModelsToAdd.push(...modelsForType);
+                // Persist healed records back to IndexedDB (fire-and-forget, non-blocking)
+                if (recordsToHeal.length > 0 && this.database) {
+                    this.runtime.logger.info(`[SyncClient.hydrate] Persisting ${recordsToHeal.length} healed ${modelType} records to IndexedDB`);
+                    // 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);
+                            }
+                            this.runtime.logger.info(`[SyncClient.hydrate] Successfully healed ${recordsToHeal.length} ${modelType} records`);
+                        }
+                        catch (err) {
+                            this.runtime.observability.captureMutationFailure({
+                                context: 'persist-healed-records',
+                                modelName: modelType,
+                                error: err instanceof Error ? err : new Error(String(err)),
+                            });
+                        }
+                    });
+                }
+                const typeEnd = typeof performance !== 'undefined' ? performance.now() : Date.now();
+                perTypePerfLogs.push({
+                    type: modelType,
+                    fetched: rawData.length,
+                    added: modelsForType.length,
+                    fetchMs: (afterFetch - typeStart).toFixed(2),
+                    createMs: (typeEnd - afterFetch).toFixed(2),
+                });
+            }
+            catch (error) {
+                this.runtime.observability.captureBootstrapFailure(error, { type: `hydrate-${modelType}` });
+            }
+        }
+        // Phase 2: Single MobX action — add ALL models across all types at once.
+        const addStart = typeof performance !== 'undefined' ? performance.now() : Date.now();
+        const totalAdded = this.objectPool.addBatch(allModelsToAdd, ModelScope.live);
+        const addEnd = typeof performance !== 'undefined' ? performance.now() : Date.now();
+        // Log per-type perf after the batched add (so logs still show per-type breakdown)
+        for (const entry of perTypePerfLogs) {
+            this.runtime.logger.debug('hydrate:type', parseFloat(entry.fetchMs) + parseFloat(entry.createMs), {
+                type: entry.type,
+                fetched: entry.fetched,
+                added: entry.added,
+                fetchMs: entry.fetchMs,
+                createMs: entry.createMs,
+            });
+        }
+        const totalEnd = typeof performance !== 'undefined' ? performance.now() : Date.now();
+        this.runtime.logger.debug('hydrate:total', totalEnd - totalStart, {
+            totalModels: totalAdded,
+            addBatchMs: (addEnd - addStart).toFixed(2),
+        });
+        // One-line startup summary: types pre-seeded and items per type
+        try {
+            const preseededTypes = this.objectPool.registry.getRegisteredModelNames();
+            const stats = this.objectPool.getStats();
+            this.runtime.logger.info('startup_summary', {
+                typesPreseeded: preseededTypes.length,
+                poolSize: stats.size,
+                typeCounts: stats.typeCounts,
+            });
+        }
+        catch { }
+    }
+    /**
+     * Re-hydrate InstanceCache from IndexedDB when the pool already has data.
+     *
+     * Unlike hydrateFromDatabase() (which uses addBatch and skips existing IDs),
+     * this method properly:
+     *   1. Upserts models — updates existing models in-place, adds new ones
+     *   2. Removes ghosts — deletes models from the pool that no longer exist in IndexedDB
+     *
+     * Used by background bootstrap, network recovery, and server-triggered re-bootstrap.
+     */
+    async rehydrateFromDatabase() {
+        if (!this.database) {
+            throw new AbloValidationError('Database not available for rehydration', {
+                code: 'sync_client_db_missing',
+            });
+        }
+        const totalStart = typeof performance !== 'undefined' ? performance.now() : Date.now();
+        // Model types to rehydrate (same filter as hydrateFromDatabase)
+        const modelTypes = this.objectPool.registry.getRegisteredModelNames().filter((name) => {
+            const meta = this.objectPool.registry.getMetadata(name);
+            return meta?.loadStrategy === LoadStrategy.instant;
+        });
+        // ── Phase 1: Read from IndexedDB & create model instances (async I/O) ──
+        const allModels = [];
+        const idbIdsByType = new Map();
+        let healedCount = 0;
+        let skippedCount = 0;
+        for (const modelType of modelTypes) {
+            try {
+                const rawData = await this.database.hydrateModels(modelType);
+                const idsForType = new Set();
+                idbIdsByType.set(modelType, idsForType);
+                for (const data of rawData) {
+                    let withType = data && typeof data === 'object' && !data.__typename
+                        ? { __typename: modelType, ...data }
+                        : data;
+                    // Self-healing
+                    const healResult = this.healModelRecord(modelType, withType);
+                    if (healResult === null) {
+                        skippedCount++;
+                        continue;
+                    }
+                    withType = healResult.data;
+                    if (healResult.healed) {
+                        healedCount++;
+                        // Persist heal back to IndexedDB (fire-and-forget)
+                        if (this.database) {
+                            const id = healResult.data.id;
+                            const healedData = healResult.data;
+                            // 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);
+                                }
+                                catch {
+                                    // Non-critical — will heal again next time
+                                }
+                            });
+                        }
+                    }
+                    // Register ID before createFromData — prevents ghost removal
+                    // if createFromData fails for a record that exists in IDB
+                    const recordId = withType.id;
+                    if (recordId) {
+                        idsForType.add(recordId);
+                    }
+                    try {
+                        const model = this.objectPool.createFromData(withType);
+                        if (model) {
+                            allModels.push(model);
+                        }
+                    }
+                    catch (error) {
+                        this.runtime.observability.breadcrumb('Model creation failed during rehydration', 'sync.bootstrap', 'warning', {
+                            modelType,
+                            modelId: recordId?.slice(0, 8) ?? 'unknown',
+                            error: error instanceof Error ? error.message : String(error),
+                        });
+                        skippedCount++;
+                    }
+                }
+            }
+            catch (error) {
+                this.runtime.observability.captureBootstrapFailure(error, { type: `rehydrate-${modelType}` });
+            }
+        }
+        // ── Phase 2: Upsert batch (single MobX action) ──
+        // createFromData already calls updateFromData() on existing models,
+        // so existing models are up-to-date. Upsert adds the new ones and
+        // updates scope for any that changed.
+        const beforeSize = this.objectPool.size;
+        this.objectPool.upsertBatch(allModels, ModelScope.live);
+        const addedCount = this.objectPool.size - beforeSize;
+        const updatedCount = allModels.length - addedCount;
+        // ── Phase 3: Reconcile ghost deletions (single MobX action) ──
+        // Only reconcile types that were rehydrated — never touch lazy-loaded types.
+        const ghostIds = [];
+        for (const modelType of modelTypes) {
+            const idbIds = idbIdsByType.get(modelType);
+            if (!idbIds)
+                continue; // Type had an error during fetch — don't reconcile
+            const poolIds = this.objectPool.getIdsByModelType(modelType);
+            if (!poolIds)
+                continue;
+            for (const poolId of poolIds) {
+                if (!idbIds.has(poolId)) {
+                    ghostIds.push(poolId);
+                }
+            }
+        }
+        const removedCount = this.objectPool.removeBatch(ghostIds);
+        // ── Phase 4: Stats & logging ──
+        const totalEnd = typeof performance !== 'undefined' ? performance.now() : Date.now();
+        const elapsedMs = Math.round(totalEnd - totalStart);
+        const stats = {
+            added: addedCount,
+            updated: updatedCount,
+            removed: removedCount,
+            skipped: skippedCount,
+            healed: healedCount,
+            elapsedMs,
+        };
+        this.runtime.logger.info('[SyncClient.rehydrate] Complete', {
+            ...stats,
+            poolSize: this.objectPool.size,
+            ghostIds: ghostIds.length > 0 ? ghostIds.slice(0, 5).map((id) => id.slice(0, 8)) : [],
+        });
+        this.runtime.observability.breadcrumb('Rehydration complete', 'sync.bootstrap', 'info', {
+            added: stats.added,
+            updated: stats.updated,
+            removed: stats.removed,
+            elapsedMs: stats.elapsedMs,
+        });
+        return stats;
+    }
+    /**
+     * 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.
+     *
+     * 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
+        // to the server, get dropped by `coalesceOperations` Rule 4 (empty input),
+        // and — if it was the only op — come back as `lastSyncId: 0`. That trips
+        // `captureCommitZeroSyncId` (false-positive Sentry anomaly) AND parks the
+        // tx in `awaiting_delta` for a 30s reconciliation timeout on a write that
+        // changed nothing. `Model.hasChanges` reads `modifiedProperties.size`, so
+        // this costs O(1) with no allocation (vs. O(N) materializing getChanges()).
+        //
+        // Strict `=== false` is deliberate: `rowAsModel` only casts, so a non-Model
+        // object can reach here with `hasChanges === undefined`. `undefined === false`
+        // is false → we fall through to the normal path rather than risk dropping a
+        // real write. Only a genuine Model with an empty dirty-set is skipped.
+        const hasChanges = model.hasChanges;
+        if (type === 'update' && hasChanges === false) {
+            return;
+        }
+        // Capture changes before the pool action runs. Pool operations —
+        // upsert in particular — can clear the model's local changes, so
+        // capturing first ensures they are never lost.
+        const capturedChanges = type === 'update' || type === 'create' ? this.captureModelChanges(model) : undefined;
+        poolAction();
+        this.stageMutation(type, model, capturedChanges, writeOptions);
+        this.notifyObservers({
+            type,
+            modelType: model.getModelName(),
+            model: type !== 'delete' ? model : undefined,
+            modelId: model.id,
+        });
+        // QueryProcessor uses `models:changed` to invalidate caches. Coalesce
+        // to one event per microtask: a paste of 100 rows should re-run
+        // affected queries ONCE, not 100×.
+        this.markModelChanged(model.getModelName());
+    }
+    pendingChangedTypes = null;
+    markModelChanged(modelType) {
+        if (!this.pendingChangedTypes) {
+            this.pendingChangedTypes = new Set();
+            const schedule = typeof queueMicrotask === 'function'
+                ? queueMicrotask
+                : (cb) => Promise.resolve().then(cb);
+            schedule(() => {
+                const types = this.pendingChangedTypes;
+                this.pendingChangedTypes = null;
+                if (types && types.size > 0)
+                    this.emit('models:changed', types);
+            });
+        }
+        this.pendingChangedTypes.add(modelType);
+    }
+    /**
+     * Capture model changes immutably BEFORE any pool operations
+     * This prevents the fragile pattern of reading changes after state modification
+     */
+    captureModelChanges(model) {
+        if (typeof model.getChanges !== 'function')
+            return undefined;
+        const changes = model.getChanges();
+        // Return a frozen copy to prevent accidental modification
+        return Object.keys(changes).length > 0 ? Object.freeze({ ...changes }) : undefined;
+    }
+    /** Add new model (CREATE) - works offline */
+    add(model, 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);
+    }
+    /**
+     * Update existing model with pre-computed changes.
+     * Used by saveManyOptimized when incoming models have empty change-tracking
+     * (e.g. freshly constructed cell models from a bulk document decomposition).
+     */
+    updateWithChanges(model, changes) {
+        this.runtime.logger.debug(`SyncClient.updateWithChanges`, {
+            modelId: model.id,
+            modelType: model.getModelName(),
+        });
+        // Use pre-computed changes if provided, otherwise fall back to model.getChanges()
+        const capturedChanges = changes && Object.keys(changes).length > 0
+            ? Object.freeze({ ...changes })
+            : this.captureModelChanges(model);
+        // No-op UPDATE guard: neither an explicit change set nor model dirty-fields.
+        // `captureModelChanges` already returns undefined for an empty dirty-set, so
+        // an undefined here means there is genuinely nothing to send — skip rather
+        // than emit an empty-input update that the server coalesces to lastSyncId 0
+        // (see the same guard in `mutate`).
+        if (capturedChanges === undefined)
+            return;
+        this.objectPool.upsert(model, ModelScope.live);
+        this.stageMutation('update', model, capturedChanges);
+        this.notifyObservers({
+            type: 'update',
+            modelType: model.getModelName(),
+            model,
+            modelId: model.id,
+        });
+    }
+    /** Expose the GraphQL client for atomic mutations (e.g., createSectionWithBlocks).
+     *  Used by SyncedStore for operations that bypass the transaction queue
+     *  but still need optimistic pool updates at the sync layer. */
+    get gql() {
+        return this.mutationExecutor;
+    }
+    /** Delete model (DELETE) - works offline */
+    delete(model, options) {
+        // Clear pending mutations first to prevent "not found" errors on fast delete
+        this.mutationQueue.cancelTransactionsForModel(model.id);
+        this.mutate('delete', model, () => this.objectPool.remove(model.id), options);
+    }
+    /**
+     * Upload a file and create its attachment record. The upload runs through
+     * the {@link MutationQueue}, and a model is built from the server's
+     * response and added to the pool.
+     */
+    async uploadFile(file, options) {
+        if (!this.userId || !this.organizationId) {
+            throw new AbloAuthenticationError('Authentication required for file uploads', {
+                code: 'file_upload_auth_required',
+            });
+        }
+        try {
+            // Use MutationQueue to handle the upload mutation
+            const result = await this.mutationQueue.uploadAttachment(file, {
+                id: options.id,
+                attachableType: options.attachableType,
+                attachableId: options.attachableId,
+                metadata: options.metadata,
+            }, {
+                userId: this.userId,
+                organizationId: this.organizationId,
+            });
+            if (result) {
+                // Create model from response using ModelRegistry (generic — no concrete class import)
+                const model = this.objectPool.createFromData({
+                    id: options.id,
+                    ...result,
+                });
+                if (model) {
+                    this.objectPool.add(model, ModelScope.live);
+                    this.notifyObservers({
+                        type: 'create',
+                        modelType: model.getModelName(),
+                        model,
+                    });
+                    return model;
+                }
+            }
+            return null;
+        }
+        catch (error) {
+            this.runtime.observability.captureMutationFailure({
+                context: 'file-upload',
+                error: error instanceof Error ? error : new Error(String(error)),
+            });
+            throw error;
+        }
+    }
+    /**
+     * Batch upload files — single GraphQL call + parallel S3 PUTs.
+     *
+     * Returns the raw `Model[]` built by the object pool (typename is
+     * determined by the payload the server returns — currently always
+     * `Attachment`). The SDK has no knowledge of app-specific model classes,
+     * so it cannot honestly claim a narrower return type; consumers that
+     * need an `Attachment[]` project through their own typed accessor
+     * (e.g. `store.query.attachments.findMany({ where: { id: IN ids } })`)
+     * after the upload resolves.
+     */
+    async batchUploadFiles(files, options) {
+        if (!this.userId || !this.organizationId) {
+            throw new AbloAuthenticationError('Authentication required for file uploads', {
+                code: 'file_upload_auth_required',
+            });
+        }
+        const items = options.ids.map((id) => ({
+            id,
+            attachableType: options.attachableType,
+            attachableId: options.attachableId,
+            metadata: options.metadata,
+        }));
+        const results = await this.mutationQueue.batchUploadAttachments(files, items, {
+            userId: this.userId,
+            organizationId: this.organizationId,
+        });
+        const models = [];
+        for (const result of results) {
+            const model = this.objectPool.createFromData({ ...result });
+            if (model) {
+                this.objectPool.add(model, ModelScope.live);
+                this.notifyObservers({
+                    type: 'create',
+                    modelType: model.getModelName(),
+                    model,
+                });
+                models.push(model);
+            }
+        }
+        return models;
+    }
+    /** Archive model (ARCHIVE) - works offline */
+    archive(model) {
+        this.mutate('archive', model, () => { this.objectPool.updateScope(model.id, ModelScope.archived); });
+    }
+    /**
+     * Append a mutation to the pending queue and schedule its sync work.
+     *
+     * 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 row creation — would
+     * reserialize the whole growing queue a hundred times, an O(N²) cost in
+     * `model.toJSON()`.
+     *
+     * @param mutation.capturedChanges - Pre-captured, frozen changes, used to
+     *   avoid re-reading a model after pool operations that might clear them.
+     */
+    /** Stage one mutation through the queue, which owns durability and execution. */
+    stageMutation(type, model, capturedChanges, writeOptions) {
+        if (this.isDisposed)
+            return;
+        if (!this.userId || !this.organizationId) {
+            this.mutationQueue.deferMutation(type, model, capturedChanges, writeOptions);
+            return;
+        }
+        const context = { userId: this.userId, organizationId: this.organizationId };
+        const staging = this.mutationQueue.enqueueModelMutation(type, model, context, capturedChanges, writeOptions);
+        const pending = staging.then(() => undefined).catch((error) => {
+            this.runtime.observability.captureMutationFailure({
+                context: `stage-mutation-${type}`,
+                modelName: model.getModelName(),
+                modelId: model.id,
+                error,
+            });
+        });
+        this.pendingStages.add(pending);
+        void pending.finally(() => this.pendingStages.delete(pending));
+    }
+    scheduleSync() {
+        if (!this.runtime.onlineStatus.isOnline() || this.isDisposed)
+            return;
+        void this.processPendingMutations().catch((error) => {
+            this.runtime.observability.captureMutationFailure({
+                context: 'background-sync',
+                error,
+            });
+        });
+    }
+    async processPendingMutations() {
+        if (this.pendingStages.size > 0) {
+            await Promise.all([...this.pendingStages]);
+        }
+        await this.drainPendingSettlements();
+    }
+    /**
+     * 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;
+        // Safely get timestamp, handling both Date objects and strings
+        const localUpdatedAt = localModel.updatedAt
+            ? localModel.updatedAt instanceof Date
+                ? localModel.updatedAt.getTime()
+                : new Date(localModel.updatedAt).getTime()
+            : 0;
+        const serverUpdatedAt = toEpochMs(serverData.updatedAt);
+        this.runtime.logger.debug('Conflict resolution', {
+            modelId: localModel.id,
+            modelType: localModel.getModelName(),
+            hasLocalChanges,
+            localUpdatedAt: localModel.updatedAt?.toString(),
+            serverUpdatedAt: serverData.updatedAt,
+            localChanges: localModel.getChanges(),
+            serverState: this.extractCriticalState(serverData),
+        });
+        // PRIORITY 1: Check for critical server states that must be respected
+        // These states override any local changes to maintain data consistency
+        const criticalServerStates = this.extractCriticalState(serverData);
+        const shouldForceAcceptServer = this.hasCriticalStateChange(criticalServerStates);
+        if (shouldForceAcceptServer) {
+            this.runtime.logger.debug('Accepting server update - critical state change detected', {
+                modelId: localModel.id,
+                criticalStates: criticalServerStates,
+            });
+            // Force accept server state for critical changes
+            localModel.updateFromData(serverData);
+            localModel.clearChanges();
+            localModel.markAsSynced();
+            return localModel;
+        }
+        // Local-first: if we have local dirty fields, merge by field.
+        // Keep locally changed fields; apply server for the rest.
+        if (hasLocalChanges) {
+            const localChanges = localModel.getChanges();
+            this.runtime.logger.debug('Merging server update with local dirty fields', {
+                modelId: localModel.id,
+                keptFields: Object.keys(localChanges || {}),
+            });
+            // 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) {
+                const mergedUpdatedAt = new Date(Math.max(localUpdatedAt, serverUpdatedAt));
+                // updateFromData accepts Date or ISO string for dates
+                merged.updatedAt = mergedUpdatedAt;
+            }
+            localModel.updateFromData(merged);
+            // Intentionally DO NOT clearChanges here; pending tx will confirm and clear
+            return localModel;
+        }
+        // No local changes: fall back to LWW to converge
+        // Accept server regardless of timestamp equality to stay in sync
+        const acceptReason = serverUpdatedAt > localUpdatedAt ? 'server is newer' : 'no local changes';
+        this.runtime.logger.debug(`Accepting server update - ${acceptReason}`);
+        localModel.updateFromData(serverData);
+        localModel.clearChanges();
+        localModel.markAsSynced();
+        return localModel;
+    }
+    /**
+     * 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 = {};
+        if (!serverData || typeof serverData !== 'object') {
+            return critical;
+        }
+        // Deletion/archival states - always critical
+        if (serverData.deletedAt !== undefined) {
+            critical.deletedAt = serverData.deletedAt;
+        }
+        if (serverData.archivedAt !== undefined) {
+            critical.archivedAt = serverData.archivedAt;
+        }
+        // Deactivation states - critical for assignments and similar entities
+        if (serverData.isActive !== undefined && serverData.isActive === false) {
+            critical.isActive = false;
+        }
+        if (serverData.unassignedAt !== undefined) {
+            critical.unassignedAt = serverData.unassignedAt;
+        }
+        return critical;
+    }
+    /**
+     * Check if critical state changes exist that require forcing server state
+     */
+    hasCriticalStateChange(criticalStates) {
+        // Any critical state present means we should force accept server
+        return (Object.keys(criticalStates).length > 0 &&
+            Object.values(criticalStates).some((v) => v !== null && v !== undefined));
+    }
+    /**
+     * Handle network reconnection
+     */
+    async handleReconnection() {
+        this.runtime.observability.breadcrumb('Network reconnected', 'sync.offline');
+        this.emit('sync:reconnecting');
+        try {
+            // MutationQueue owns the durable flush and commit lanes.
+            await this.processPendingMutations();
+            this.setConnectionState('connected');
+            this.emit('sync:reconnected');
+        }
+        catch (error) {
+            this.runtime.observability.captureMutationFailure({
+                context: 'reconnection-sync',
+                error: error instanceof Error ? error : new Error(String(error)),
+            });
+            this.emit('sync:error', error);
+        }
+    }
+    /**
+     * Handle network disconnection
+     */
+    async handleDisconnection() {
+        this.runtime.observability.breadcrumb('Network disconnected', 'sync.offline');
+        this.setConnectionState('disconnected');
+        this.emit('sync:offline');
+    }
+    /**
+     * Get current sync state
+     */
+    getState() {
+        return {
+            connectionState: this.connectionState,
+            pendingMutations: this.mutationQueue.getOutstandingTransactionCount(),
+            lastSyncAt: new Date(),
+            error: undefined,
+        };
+    }
+    /**
+     * Set connection state
+     */
+    setConnectionState(state) {
+        const oldState = this.connectionState;
+        this.connectionState = state;
+        if (oldState !== state) {
+            this.runtime.observability.setConnectionState(state);
+            this.runtime.observability.breadcrumb(`Connection: ${oldState} → ${state}`, 'sync.websocket');
+            if (state === 'connected') {
+                this.emit('connection:established');
+                this.mutationQueue.setConnectionState('connected');
+            }
+            else if (state === 'disconnected') {
+                this.emit('connection:disconnected');
+                this.mutationQueue.setConnectionState('disconnected');
+            }
+        }
+    }
+    /**
+     * Subscribe to events with disposer pattern
+     */
+    subscribe(event, handler) {
+        super.on(event, handler);
+        // Return disposer function
+        return () => {
+            this.off(event, handler);
+        };
+    }
+    /**
+     * Add observer for sync events
+     */
+    addObserver(observer) {
+        this.observers.add(observer);
+    }
+    /**
+     * Remove observer
+     */
+    removeObserver(observer) {
+        this.observers.delete(observer);
+    }
+    /**
+     * Notify all observers
+     */
+    notifyObservers(event) {
+        for (const observer of this.observers) {
+            if (observer.onSync) {
+                try {
+                    observer.onSync(event);
+                }
+                catch (error) {
+                    this.runtime.observability.breadcrumb('Observer error', 'sync.transaction', 'error', {
+                        error: error instanceof Error ? error.message : String(error),
+                    });
+                }
+            }
+        }
+    }
+    /**
+     * Disconnect from sync
+     */
+    disconnect() {
+        this.setConnectionState('disconnected');
+    }
+    /**
+     * Mark the sync client as connected
+     * Called when WebSocket successfully connects (can happen independently of browser online/offline)
+     */
+    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.drainPendingSettlements().catch((error) => {
+            this.runtime.observability.captureMutationFailure({
+                context: 'restore-commit-outbox',
+                error: error instanceof Error ? error : new Error(String(error)),
+            });
+        });
+        void this.processPendingMutations();
+    }
+    drainPendingSettlements() {
+        return this.reconnectDrain.drain(() => this.mutationQueue.drainPending());
+    }
+    /**
+     * Dispose and cleanup
+     */
+    dispose() {
+        this.isDisposed = true;
+        this.disconnect();
+        this.networkMonitor.dispose();
+        this.observers.clear();
+        this.pendingStages.clear();
+        this.removeAllListeners();
+    }
+    /**
+     * Notify the {@link MutationQueue} of an incoming delta so it can confirm
+     * hosted writes by sync-id threshold and queued forwards by their echoed
+     * source-batch correlation id.
+     * @param syncId - The sync id of the received delta.
+     * @param transactionId - Optional server echo of the originating local write.
+     * @param correlationId - Opaque batch identity decoded from a source WAL echo.
+     */
+    onDeltaReceived(syncId, transactionId, correlationId) {
+        try {
+            this.mutationQueue.onDeltaReceived(syncId, transactionId, correlationId);
+        }
+        catch (e) {
+            this.runtime.observability.breadcrumb('Failed to notify delta received', 'sync.transaction', 'warning', {
+                syncId,
+                transactionId,
+                correlationId,
+            });
+        }
+    }
+    /**
+     * 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 (for example, `Block`).
+     * @param foreignKey - The foreign-key property name (for example, `sectionId`).
+     * @param parentId - The id of the deleted parent.
+     * @returns The number of transactions cancelled.
+     */
+    cancelTransactionsByForeignKey(childModelName, foreignKey, parentId) {
+        return this.mutationQueue.cancelTransactionsByForeignKey(childModelName, foreignKey, parentId);
+    }
+    /**
+     * Wait for a transaction to be confirmed by its delta echo. Delegates to the
+     * {@link MutationQueue}, which handles the confirmation timeout.
+     */
+    waitForDeltaConfirmation(transactionId) {
+        return this.mutationQueue.waitForConfirmation(transactionId);
+    }
+    /**
+     * Force sync now - process pending mutations
+     */
+    async syncNow() {
+        await this.processPendingMutations();
+    }
+    /**
+     * 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 `InstanceCache.getStats`.
+     */
+    getSyncStats() {
+        return {
+            connectionState: this.connectionState,
+            pendingMutations: this.mutationQueue.getOutstandingTransactionCount(),
+            objectPoolStats: this.objectPool.getStats(),
+        };
+    }
+    /**
+     * Get pending transaction count from MutationQueue
+     * Used by SyncedStore to compute hasUnsyncedChanges
+     */
+    getPendingTransactionCount() {
+        const stats = this.mutationQueue.getStats();
+        // Include pending and executing as "unsynced"
+        // awaiting_delta transactions are included in 'executing' until confirmed
+        // Completed and failed are "synced" (either done or gave up)
+        return stats.pending + stats.executing;
+    }
+    /**
+     * Subscribe to transaction events for sync status tracking
+     * Returns unsubscribe function
+     */
+    onTransactionEvent(event, callback) {
+        const eventName = `transaction:${event}`;
+        this.mutationQueue.on(eventName, callback);
+        return () => this.mutationQueue.off(eventName, callback);
+    }
+    /**
+     * Subscribe to mutation failures with the full payload. Mirrors the
+     * underlying MutationQueue 'transaction:failed' shape so consumers
+     * can render typed UI (toast keyed by `AbloError.type`, route-level
+     * "this entity reverted" boundaries, telemetry).
+     *
+     * 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.mutationQueue.on('transaction:failed', listener);
+        return () => this.mutationQueue.off('transaction:failed', listener);
+    }
+    /**
+     * Subscribe to commit round-trip latency, split into the local seal and the
+     * remote acknowledgement. Fires once per completed commit.
+     *
+     * Taps the {@link MutationQueue} emitter for the same reason
+     * {@link onMutationFailure} does: the commit lifecycle events originate
+     * there and the SyncClient's own emitter never rebroadcasts them.
+     */
+    onCommitLatency(listener) {
+        return observeCommitLatency(this.mutationQueue, listener);
+    }
+    /**
+     * Subscribe to local transaction creation with the full {@link QueuedMutation}
+     * payload (`type`, `modelName`, `modelId`, `data`, `previousData`). This is
+     * the feed the store's local-mutation subscription taps for undo recording.
+     *
+     * It subscribes to the {@link MutationQueue}'s emitter directly, since
+     * that is the only emitter that fires `transaction:created`. The SyncClient's
+     * own emitter (reached through {@link subscribe}) never rebroadcasts that
+     * event, so routing undo through `subscribe('transaction:created')` would
+     * record nothing. {@link onMutationFailure} taps the queue for the same
+     * reason.
+     */
+    onLocalTransaction(listener) {
+        this.mutationQueue.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.
+        // Enrich each operation with previous state captured from the pool HERE
+        // (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',
+                DELETE: 'delete',
+                ARCHIVE: 'archive',
+                UNARCHIVE: 'unarchive',
+            };
+            payload.operations.forEach((op, index) => {
+                const type = TYPE_BY_WIRE[op.type];
+                if (!type || !op.id)
+                    return;
+                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)
+                    return;
+                // UPDATE inverse must only revert the fields this op actually wrote;
+                // handing undo the FULL row would clobber concurrent edits to
+                // unrelated fields on revert.
+                const previousData = type === 'update' && snapshot && op.input
+                    ? Object.fromEntries(Object.keys(op.input).map((key) => [key, snapshot[key]]))
+                    : snapshot ?? null;
+                listener({
+                    id: `${payload.clientTxId}_op${index}`,
+                    type,
+                    modelName: op.model,
+                    modelId: op.id,
+                    modelKey: op.model,
+                    data: op.input ?? undefined,
+                    previousData,
+                    context: {
+                        userId: this.userId ?? '',
+                        organizationId: this.organizationId ?? '',
+                    },
+                    status: 'pending',
+                    createdAt: Date.now(),
+                    attempts: 0,
+                    priority: 'normal',
+                    priorityScore: 0,
+                });
+            });
+        };
+        this.mutationQueue.on('commit:staging', onCommitStaging);
+        this.mutationQueue.on('commit:seal_failed', onCommitSealFailed);
+        this.mutationQueue.on('commit:created', onCommitCreated);
+        return () => {
+            this.mutationQueue.off('transaction:created', listener);
+            this.mutationQueue.off('commit:staging', onCommitStaging);
+            this.mutationQueue.off('commit:seal_failed', onCommitSealFailed);
+            this.mutationQueue.off('commit:created', onCommitCreated);
+            snapshotsByCommit.clear();
+        };
+    }
+    /**
+     * Wait for the latest in-flight transaction for (modelName, modelId)
+     * to be confirmed by the server, or reject if it's rolled back.
+     * Resolves immediately when no transaction is in flight — see
+     * `MutationQueue.confirmationFor` for the lookup contract.
+     *
+     * Distinct from `waitForDeltaConfirmation(transactionId)` which keys
+     * off a known tx id; this variant is for call sites that hold a
+     * Model reference but never see the underlying transaction.
+     */
+    waitForConfirmation(modelName, modelId) {
+        return this.mutationQueue.confirmationFor(modelName, modelId);
+    }
+    /**
+     * Get detailed debug info for the sync debug page
+     */
+    getDebugInfo() {
+        return {
+            connectionState: this.connectionState,
+            pendingMutationsCount: this.mutationQueue.getOutstandingTransactionCount(),
+            mutationQueue: this.mutationQueue.getDebugInfo(),
+        };
+    }
+    // --- Best-practice assignment ops ---
+    async unassignEntity(entityType, entityId) {
+        // Call server-side unassign to avoid per-id races
+        await this.mutationExecutor.executeDelete('Assignment', entityId);
+    }
+    async reassignEntity(entityType, entityId, assigneeType, assigneeId, id) {
+        await this.mutationExecutor.executeCreate('Assignment', id || '', {
+            entityType,
+            entityId,
+            assigneeType,
+            assigneeId,
+        });
+    }
+    // ── Delta + Bootstrap application (owns InstanceCache writes) ──────────────
+    /**
+     * Apply a batch of delta results from Database to the InstanceCache.
+     * Owns: model creation, upsert, remove, archive, conflict resolution.
+     * Returns: nothing — InstanceCache is updated in place.
+     */
+    /**
+     * Mark a local transaction as optimistically applied. The matching
+     * server delta (when it arrives with the same `transactionId`) will
+     * be recognized as an echo and skip the pool mutation. Called
+     * automatically by `MutationQueue` when a transaction is staged;
+     * exposed publicly so tests can drive the API directly.
+     */
+    markTransactionPending(transactionId) {
+        this.echoTracker.markPending(transactionId);
+    }
+    /**
+     * Read echo-detection counters: hits, rollbacks, evictions, and the
+     * current pending-set size. Surfaced for production observability
+     * — a sustained `evictions > 0` rate or `rollbacks` spike is a
+     * health signal worth alerting on.
+     */
+    getEchoMetrics() {
+        return this.echoTracker.getMetrics();
+    }
+    /**
+     * Package-internal accessor for the {@link MutationQueue}. Used by
+     * `Ablo.commits.create()` to route raw multi-operation envelopes through the
+     * same retry-on-reconnect lane as the model proxy path, and by tests to
+     * exercise the queue's interaction with {@link markTransactionPending} on the
+     * real instance the SyncClient subscribes to. It is not re-exported to SDK
+     * consumers; `Ablo` is the public surface.
+     */
+    getMutationQueue() {
+        return this.mutationQueue;
+    }
+    applyDeltaBatchToPool(dbResults, enrichRelations) {
+        const modelsToAdd = [];
+        const modelsToUpsert = [];
+        const idsToRemove = [];
+        const idsToArchive = [];
+        // Pre-pass: collect every id slated for `remove` in this batch. The
+        // parent-delete flicker came from this exact pattern: a peer (or the
+        // user themself) deletes a parent with N children; the commit produces
+        // BOTH residual `update` deltas (from the optimistic edits that
+        // happened just before the delete) AND `remove` deltas. The
+        // `update` branch below would `createFromData` the row back into
+        // the pool when `existing` was already gone (optimistic remove
+        // happened), and the next loop iteration's `remove` would strip
+        // it again — net effect: pool transitions live → gone → live →
+        // gone in one tick, which the renderer catches mid-frame as a
+        // flicker. Filter ops on doomed ids before they touch the pool.
+        const idsBeingRemoved = new Set();
+        for (const r of dbResults) {
+            if (r.action === 'remove')
+                idsBeingRemoved.add(r.modelId);
+        }
+        for (const result of dbResults) {
+            const { modelName, modelId, action, transactionId } = result;
+            // 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;
+            }
+            // If a later op in this batch will remove this id, skip earlier
+            // add/update ops on it. Server FK ordering can produce
+            // U(child)+D(child) when an optimistic edit and a delete both
+            // commit in the same window; only the final state matters.
+            if ((action === 'add' || action === 'update') && idsBeingRemoved.has(modelId)) {
+                continue;
+            }
+            switch (action) {
+                case 'add': {
+                    const existing = this.objectPool.get(modelId);
+                    if (existing) {
+                        existing.markAsSynced();
+                    }
+                    else if (result.data) {
+                        const data = enrichRelations(modelName, { ...result.data, __typename: modelName });
+                        const model = this.objectPool.createFromData(data, undefined, {
+                            deferObservability: true,
+                        });
+                        if (model)
+                            modelsToAdd.push(model);
+                    }
+                    break;
+                }
+                case 'update': {
+                    const existing = this.objectPool.get(modelId);
+                    if (existing && !existing.disposed && result.data) {
+                        enrichRelations(modelName, result.data);
+                        const resolved = this.resolveConflicts(existing, result.data);
+                        modelsToUpsert.push(resolved);
+                    }
+                    // Resurrection drop: if `existing` is gone (optimistic delete
+                    // discarded it; the matching D delta is in-flight) we used
+                    // to call `createFromData` here, which reintroduced the row
+                    // for a frame before the D delta stripped it again — the
+                    // chart-delete flicker. Trust the local state. If the server
+                    // still considers the row alive, a subsequent bootstrap or
+                    // resync will reconcile.
+                    break;
+                }
+                case 'remove':
+                    idsToRemove.push(modelId);
+                    break;
+                case 'archive':
+                    idsToArchive.push(modelId);
+                    break;
+                case 'verify':
+                    // `verify` is `Database.processDeltaBatch`'s signal for a delta
+                    // whose IDB store transaction FAILED. Pool isn't updated for
+                    // this delta — by design, since the persisted view doesn't
+                    // reflect it either — and the persistence-gated cursor in
+                    // `BaseSyncedStore.flushPendingDeltas` will NOT ack past it,
+                    // so the next 30s catch-up poll (or reconnect handshake) will
+                    // re-fetch and re-apply. Logged here so silent IDB failures
+                    // are observable instead of disappearing into a default switch
+                    // fall-through.
+                    // Self-healing: the next catch-up poll / reconnect re-fetches and
+                    // re-applies this delta, so it's forensic, not consumer-actionable → debug.
+                    this.runtime.logger.debug('[SyncClient.applyDeltaBatchToPool] skipping pool op for unpersisted delta', {
+                        modelName,
+                        modelId: modelId.slice(0, 12),
+                    });
+                    break;
+            }
+        }
+        // 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);
+            if (modelsToUpsert.length > 0)
+                this.objectPool.upsertBatch(modelsToUpsert, ModelScope.live);
+            if (idsToRemove.length > 0)
+                this.objectPool.removeBatch(idsToRemove);
+            for (const id of idsToArchive)
+                this.objectPool.updateScope(id, ModelScope.archived);
+            // Emit changed model types so QueryProcessor can auto-invalidate.
+            // Kept inside the action so any observable query-cache state it
+            // flips is part of the same atomic reveal.
+            const changedTypes = new Set(dbResults.map(r => r.modelName));
+            if (changedTypes.size > 0)
+                this.emit('models:changed', changedTypes);
+        });
+    }
+    /**
+     * Apply bootstrap data to the InstanceCache with ghost removal.
+     * Owns: model creation, batch upsert, ghost detection + removal.
+     */
+    applyBootstrapDataToPool(bootstrapData, protectedIds, options) {
+        if (!bootstrapData.models) {
+            return { added: 0, updated: 0, removed: 0, skipped: 0, healed: 0 };
+        }
+        const allModels = [];
+        const serverIdsByType = new Map();
+        let healedCount = 0;
+        let skippedCount = 0;
+        const failedTypes = new Set(bootstrapData.failedModels ?? []);
+        for (const [modelType, records] of Object.entries(bootstrapData.models)) {
+            if (failedTypes.has(modelType))
+                continue;
+            const idsForType = new Set();
+            serverIdsByType.set(modelType, idsForType);
+            if (!Array.isArray(records) || records.length === 0)
+                continue;
+            for (const rawRecord of records) {
+                if (!rawRecord || typeof rawRecord !== 'object') {
+                    skippedCount++;
+                    continue;
+                }
+                let data = rawRecord;
+                if (!data.__typename)
+                    data = { __typename: modelType, ...data };
+                const healResult = this.healModelRecord(modelType, data);
+                if (healResult === null) {
+                    skippedCount++;
+                    continue;
+                }
+                data = healResult.data;
+                if (healResult.healed)
+                    healedCount++;
+                const recordId = data.id;
+                if (recordId)
+                    idsForType.add(recordId);
+                // 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)) {
+                        skippedCount++;
+                        continue;
+                    }
+                }
+                try {
+                    const model = this.objectPool.createFromData(data);
+                    if (model)
+                        allModels.push(model);
+                }
+                catch {
+                    skippedCount++;
+                }
+            }
+        }
+        // Upsert. The scoped stale-skip above already guarded the version, so a
+        // plain upsert is correct here for both paths.
+        const beforeSize = this.objectPool.size;
+        this.objectPool.upsertBatch(allModels, ModelScope.live);
+        const addedCount = this.objectPool.size - beforeSize;
+        const updatedCount = allModels.length - addedCount;
+        // 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 = [];
+            for (const [modelType, serverIds] of serverIdsByType) {
+                const poolIds = this.objectPool.getIdsByModelType(modelType);
+                if (!poolIds)
+                    continue;
+                for (const poolId of poolIds) {
+                    if (!serverIds.has(poolId) && !protectedIds?.has(poolId))
+                        ghostIds.push(poolId);
+                }
+            }
+            removedCount = this.objectPool.removeBatch(ghostIds);
+        }
+        // Emit changed model types so QueryProcessor can auto-invalidate
+        const changedTypes = new Set(Object.keys(bootstrapData.models));
+        if (changedTypes.size > 0)
+            this.emit('models:changed', changedTypes);
+        return { added: addedCount, updated: updatedCount, removed: removedCount, skipped: skippedCount, healed: healedCount };
+    }
+}