@abloatai/humans 0.37.0

package/dist/local/transactions/mutations/MutationQueue.js

@@ -0,0 +1,1498 @@
+/**
+ * MutationQueue manages the lifecycle of local writes on their way to the
+ * server: it applies each change optimistically, batches the writes made in one
+ * event-loop tick into a single commit, retries transient failures, and rolls
+ * back on permanent rejection.
+ *
+ * Key behaviours:
+ * - Optimistic updates with rollback on failure.
+ * - Configurable conflict resolution.
+ * - Microtask batching: transactions created in the same event-loop tick share
+ *   a batch id and commit together in one round trip.
+ * - A dependency-injected executor, so several queues can coexist.
+ */
+import { EventEmitter } from 'events';
+import { v4 as uuid } from 'uuid';
+import { globalRuntime } from '../../context.js';
+import { AbloError, AbloConnectionError, AbloIdempotencyError, AbloNotFoundError, AbloValidationError, errorCodeSpec, } from '@abloatai/transaction/errors';
+import { LogPosition, } from '../../logPosition.js';
+import { mutationCommitResultSchema, } from '@abloatai/transaction/wire/commit';
+import { projectCommitPayload, computePriorityScore, normalizeModelKey, 
+// Includes stale guards as well as request identity/audit barriers.
+hasCommitCoalescingBarrier, applyWriteOptions, asTransportError, extractStatusCode, TX_TYPE_TO_MUTATION_OP, } from './commitPayload.js';
+import { MutationStore } from './MutationStore.js';
+import { entityKey, mergeUpdateData, takeUnsentCreateForModel, findCreateBarrierForDelete, deferDeleteUntilCreateSettles, releaseDeferredDeletesForCreate, } from './coalesceRules.js';
+import { DeltaConfirmationTracker } from './deltaConfirmation.js';
+import { deserializePersistedTransaction, isNonReplayablePersistedRow, pendingMutationRecordId, legacyPendingMutationRecordSchema, pendingMutationRecordSchema, persistedMutationSchema, } from './replayValidation.js';
+import { deserializeLegacyPendingMutation, loadPersistedTransactions, persistQueuedTransaction, removePersistedTransaction, settlePersistedFailure, } from './mutationPersistence.js';
+import { createCommitEnvelopeMember, createDurableCommitEnvelope, commitEnvelopeRecordId, durableCommitEnvelopeSchema, } from '@abloatai/transaction/transactions/settlement/commitEnvelope';
+import { stableStringify } from '@abloatai/transaction/utils/json';
+import { createLocalMutationPort, } from './localMutation.js';
+import { dispatchCommitBounded, parseMutationCommitResult, persistDurableCommitAcceptance, removeDurableCommit, sealDurableCommit, } from './commitTransport.js';
+import { processCommitLane, waitForCommitReceipt, } from './commitLane.js';
+import { enqueueCommit } from './commitApi.js';
+import { archive as archiveModel, create as createModel, remove as deleteModel, unarchive as unarchiveModel, update as updateModel, } from './modelOperations.js';
+import { enqueueTransaction } from './queueCoalescing.js';
+import { processBatch } from './batchProcessing.js';
+import { handleFailure } from './failureHandling.js';
+import { handleConflict as resolveConflict, isPermanentError as classifyPermanentError, isDefinitiveRejection as classifyDefinitiveRejection } from './failurePolicy.js';
+import { takeNextExecutionBatch as selectExecutionBatch, takePendingDrainBatch as selectPendingDrainBatch } from './executionSelection.js';
+import { scheduleProcessing as scheduleProcessingExternal } from './processingScheduler.js';
+import { drainPendingSettlements, } from './pendingDrain.js';
+import { restoreDurableCommits as restoreDurableCommitsExternal } from './durableCommitRestore.js';
+export class MutationQueue extends EventEmitter {
+    // Keep one hour of clock/network margin inside the server's 24-hour ledger.
+    static DURABLE_REPLAY_WINDOW_MS = 23 * 60 * 60 * 1000;
+    store = new MutationStore();
+    // Signature of the last permanent-error we logged at `warn`. A `create`
+    // whose id already exists (`unique_violation`) is a permanent rejection
+    // that a pending-work drain re-drives after reconnect/bootstrap — without
+    // this, the identical cause prints on a loop. We log the first occurrence
+    // and demote exact repeats to `debug`.
+    lastPermanentErrorSig;
+    // The executor bound to this queue instance, set by `setMutationExecutor(...)`
+    // just after construction. When unset it falls back to the ambient executor
+    // from `getContext()`.
+    //
+    // The binding matters because the ambient executor is a module-level
+    // singleton: constructing a second client instance overwrites the first
+    // instance's executor. Without a per-instance binding, commits on one
+    // instance would dispatch through another instance's executor closure; once
+    // that other instance disposed its store, the closure would resolve no live
+    // connection and every commit here would fail with `ws_not_ready`, which the
+    // queue treats as transient and retries endlessly.
+    _mutationExecutor = null;
+    get mutationExecutor() {
+        return this._mutationExecutor ?? this.runtime.mutationExecutor;
+    }
+    runtime;
+    /** Durable transaction journal owned by this queue, before commit sealing. */
+    persistence = null;
+    deferredMutations = [];
+    pendingPersistenceStages = [];
+    persistenceStageScheduled = false;
+    pendingDrainPromise = null;
+    executionQueue = [];
+    isProcessing = false;
+    processTimer;
+    processScheduled = false;
+    // Staging area for transactions created in the same event-loop tick. Each one
+    // lands here first, then a microtask commits them together.
+    createdTransactions = [];
+    commitScheduled = false;
+    // Per-model in-flight tracking and merge buffer
+    inFlightByModel = new Set();
+    pendingMergeByModel = new Map();
+    deferredDeletesByCreate = new Map();
+    // Commit lane: pre-built atomic multi-op envelopes from `ablo.commits.create()`.
+    // Drained serially (one envelope at a time) since each is atomic; no
+    // coalescing with model-proxy transactions.
+    commitLane = [];
+    commitStore = new Map();
+    /**
+     * Small race buffer for authoritative echoes that arrive before the queued
+     * mutation receipt. The forward and WAL stream are independent channels, so
+     * either can win without changing the settlement result.
+     */
+    recentDeltaCorrelations = new Map();
+    /**
+     * Client-facing confirmation deadlines for source-forwarded writes. These
+     * timers settle only the caller waiting for `confirmed`; the accepted write
+     * remains in `awaiting_delta`, with its durable envelope intact, until the
+     * authoritative WAL echo arrives.
+     */
+    replicationLagTimeouts = new Map();
+    replicationLagErrors = new Map();
+    commitProcessing = false;
+    lastCommitSequence = 0;
+    durableReplayBlock = null;
+    /** Browser-backed strict outbox; absent for standalone/in-memory consumers. */
+    commitOutbox = null;
+    commitOutboxScope = null;
+    get commitTransportContext() {
+        return {
+            runtime: this.runtime,
+            config: {
+                enablePersistence: this.config.enablePersistence,
+                commitDispatchTimeoutMs: this.config.commitDispatchTimeoutMs,
+            },
+            commitOutbox: this.commitOutbox,
+            commitOutboxScope: this.commitOutboxScope,
+            mutationExecutor: this.mutationExecutor,
+            emitCommitLifecycle: (event, payload) => this.emitCommitLifecycle(event, payload),
+        };
+    }
+    get commitLaneContext() {
+        return {
+            runtime: this.runtime,
+            config: { maxRetries: this.config.maxRetries },
+            commitLane: this.commitLane,
+            commitNotifications: this.commitNotifications,
+            commitMissingIds: this.commitMissingIds,
+            commitProcessing: this.commitProcessing,
+            setCommitProcessing: (value) => { this.commitProcessing = value; },
+            durableReplayBlock: this.durableReplayBlock,
+            sealDurableCommit: (input) => this.sealDurableCommit(input),
+            assertEnvelopeInsideReplayWindow: (envelope) => this.assertEnvelopeInsideReplayWindow(envelope),
+            dispatchCommit: async (envelope) => this.parseMutationCommitResult(await this.dispatchCommitBounded(envelope.operations, {
+                idempotencyKey: envelope.idempotencyKey,
+                ...(envelope.commitOptions.reads ? { reads: envelope.commitOptions.reads } : {}),
+                ...(envelope.commitOptions.track ? { track: envelope.commitOptions.track } : {}),
+            })),
+            persistDurableCommitAcceptance: (envelope, result) => this.persistDurableCommitAcceptance(envelope, result),
+            removeDurableCommit: (idempotencyKey) => this.removeDurableCommit(idempotencyKey),
+            queuedCommitEchoSyncId: (transaction) => this.queuedCommitEchoSyncId(transaction),
+            completeQueuedCommit: (transaction, syncId) => this.completeQueuedCommit(transaction, syncId),
+            scheduleReplicationLagTimeout: (transactionId, clientTxId, correlationId) => this.scheduleReplicationLagTimeout(transactionId, clientTxId, correlationId),
+            noteAck: (syncId) => this.noteAck(syncId),
+            isDefinitiveRejection: (error) => this.isDefinitiveRejection(error),
+            isPermanentError: (error) => this.isPermanentError(error),
+            emitCommitLifecycle: (event, payload) => this.emitCommitLifecycle(event, payload),
+        };
+    }
+    get commitReceiptContext() {
+        return {
+            commitStore: this.commitStore,
+            commitNotifications: this.commitNotifications,
+            commitMissingIds: this.commitMissingIds,
+            replicationLagErrors: this.replicationLagErrors,
+            on: (event, listener) => this.on(event, listener),
+            off: (event, listener) => this.off(event, listener),
+        };
+    }
+    get commitApiContext() {
+        return {
+            assertDurableReplayOpen: () => this.assertDurableReplayOpen(),
+            commitStore: this.commitStore,
+            commitLane: this.commitLane,
+            replicationLagErrors: this.replicationLagErrors,
+            clearReplicationLagState: (transactionId) => this.clearReplicationLagState(transactionId),
+            nextCommitSequence: () => this.nextCommitSequence(),
+            sealDurableCommit: (input) => this.sealDurableCommit(input),
+            processCommitLane: () => this.processCommitLane(),
+            emitCommitLifecycle: (event, payload) => this.emitCommitLifecycle(event, payload),
+        };
+    }
+    get modelMutationContext() {
+        return {
+            enableOptimistic: this.config.enableOptimistic,
+            persistenceReady: !!this.persistence && !!this.commitOutboxScope,
+            assertDurableReplayOpen: () => this.assertDurableReplayOpen(),
+            generateId: () => this.generateId(),
+            normalizeModelKey,
+            computePriorityScore: (type, modelName) => this.computePriorityScore(type, modelName),
+            extractCreateData: (model) => this.extractCreateData(model),
+            extractUpdateData: (model) => this.extractUpdateData(model),
+            extractPreviousData: (model, input) => this.extractPreviousData(model, input),
+            mapChangesToInput: (modelName, changes) => this.mapChangesToInput(modelName, changes),
+            isReorderPayload: (input) => this.isReorderPayload(input),
+            attachConfirmation: (transaction) => this.attachConfirmation(transaction),
+            add: (transaction) => this.store.add(transaction),
+            applyOptimisticCreate: (model, transaction) => this.applyOptimisticCreate(model, transaction),
+            applyOptimisticUpdate: (model, transaction) => this.applyOptimisticUpdate(model, transaction),
+            applyOptimisticDelete: (model, transaction) => this.applyOptimisticDelete(model, transaction),
+            takeUnsentCreateForModel: (modelName, modelId) => this.takeUnsentCreateForModel(modelName, modelId),
+            cancelUnsentCreateForDelete: (transaction) => this.cancelUnsentCreateForDelete(transaction),
+            completeLocalDelete: (model, context, writeOptions, sourceMutationIds) => this.completeLocalDelete(model, context, writeOptions, sourceMutationIds),
+            cancelTransactionsForModel: (modelId, type) => this.cancelTransactionsForModel(modelId, type),
+            pendingMergeByModel: this.pendingMergeByModel,
+            inFlightByModel: this.inFlightByModel,
+            findCreateBarrierForDelete: (modelName, modelId) => this.findCreateBarrierForDelete(modelName, modelId),
+            deferDeleteUntilCreateSettles: (create, transaction) => this.deferDeleteUntilCreateSettles(create, transaction),
+            logger: this.runtime.logger,
+            persistAndStage: (transaction, modelData) => this.persistAndStage(transaction, modelData),
+            persistQueuedTransaction: (transaction, modelData) => this.persistQueuedTransaction(transaction, modelData),
+            stageTransaction: (transaction) => this.stageTransaction(transaction),
+            emit: (event, payload) => this.emit(event, payload),
+        };
+    }
+    get queueCoalescingContext() {
+        return {
+            executionQueue: this.executionQueue,
+            inFlightByModel: this.inFlightByModel,
+            pendingMergeByModel: this.pendingMergeByModel,
+            ensureDerivedFields: (transaction) => this.ensureDerivedFields(transaction),
+            scheduleProcessing: (immediate) => this.scheduleProcessing(immediate),
+            storeRemove: (transactionId) => this.store.remove(transactionId),
+        };
+    }
+    get batchProcessingContext() {
+        return {
+            runtime: this.runtime,
+            config: this.config,
+            durableReplayBlock: this.durableReplayBlock,
+            executionQueue: this.executionQueue,
+            isProcessing: this.isProcessing,
+            setIsProcessing: (value) => { this.isProcessing = value; },
+            takeNextExecutionBatch: () => this.takeNextExecutionBatch(),
+            ensureDerivedFields: (transaction) => this.ensureDerivedFields(transaction),
+            ensureCommitEnvelope: (batch) => this.ensureCommitEnvelope([...batch]),
+            executingCount: this.executingCount,
+            setExecutingCount: (value) => { this.executingCount = value; },
+            inFlightByModel: this.inFlightByModel,
+            pendingMergeByModel: this.pendingMergeByModel,
+            generateId: () => this.generateId(),
+            computePriorityScore: (type, modelName) => this.computePriorityScore(type, modelName),
+            store: this.store,
+            enqueue: (transaction) => this.enqueue(transaction),
+            optimisticUpdates: this.localMutationPort.updates,
+            commitNotifications: this.commitNotifications,
+            commitMissingIds: this.commitMissingIds,
+            sourceMutationIdsFor: (batch) => this.sourceMutationIdsFor(batch),
+            dispatchCommitBounded: (...args) => this.dispatchCommitBounded(...args),
+            parseMutationCommitResult: (value) => this.parseMutationCommitResult(value),
+            persistDurableCommitAcceptance: (envelope, result) => this.persistDurableCommitAcceptance(envelope, result),
+            removeDurableCommit: (idempotencyKey) => this.removeDurableCommit(idempotencyKey),
+            assertEnvelopeInsideReplayWindow: (envelope) => this.assertEnvelopeInsideReplayWindow(envelope),
+            sealDurableCommit: (input) => this.sealDurableCommit(input),
+            noteAck: (syncId) => this.noteAck(syncId),
+            classifyReceiptNotifications: (operations, notifications) => this.classifyReceiptNotifications(operations, notifications),
+            receiptTargetKey: (modelName, modelId) => this.receiptTargetKey(modelName, modelId),
+            scheduleReplicationLagTimeout: (transactionId, clientTxId, correlationId) => this.scheduleReplicationLagTimeout(transactionId, clientTxId, correlationId),
+            scheduleDeltaConfirmationTimeout: (transaction, timeoutMs) => this.scheduleDeltaConfirmationTimeout(transaction, timeoutMs),
+            clearReplicationLagState: (transactionId) => this.clearReplicationLagState(transactionId),
+            completeQueuedCommit: (transaction, syncId) => this.completeQueuedCommit(transaction, syncId),
+            queuedCommitMatchesCorrelation: (transaction, correlationId) => this.queuedCommitMatchesCorrelation(transaction, correlationId),
+            recentDeltaCorrelations: this.recentDeltaCorrelations,
+            lastSeenSyncId: this.lastSeenSyncId,
+            scheduleProcessing: (immediate) => this.scheduleProcessing(immediate),
+            handleFailure: (transaction, error) => this.handleFailure(transaction, error),
+            isDefinitiveRejection: (error) => this.isDefinitiveRejection(error),
+            emitCommitLifecycle: (event, payload) => this.emitCommitLifecycle(event, payload),
+            emit: (event, payload) => this.emit(event, payload),
+            rollbackOptimistic: (transaction, reason, error) => this.rollbackOptimistic(transaction, reason, error),
+        };
+    }
+    get failureHandlingContext() {
+        return {
+            runtime: this.runtime,
+            config: this.config,
+            store: this.store,
+            isPermanentError: (error) => this.isPermanentError(error),
+            rollbackOptimistic: (transaction, reason, error) => this.rollbackOptimistic(transaction, reason, error),
+            enqueue: (transaction) => this.enqueue(transaction),
+            getLastPermanentErrorSignature: () => this.lastPermanentErrorSig,
+            setLastPermanentErrorSignature: (signature) => { this.lastPermanentErrorSig = signature; },
+            emit: (event, payload) => this.emit(event, payload),
+        };
+    }
+    get conflictPolicyContext() {
+        return {
+            config: this.config,
+            store: this.store,
+            rollbackOptimistic: (transaction, reason) => this.rollbackOptimistic(transaction, reason),
+            mergeData: (local, remote) => this.mergeData(local, remote),
+            enqueue: (transaction) => this.enqueue(transaction),
+        };
+    }
+    get processingSchedulerContext() {
+        return {
+            processScheduled: this.processScheduled,
+            setProcessScheduled: (value) => { this.processScheduled = value; },
+            processTimer: this.processTimer,
+            setProcessTimer: (timer) => { this.processTimer = timer; },
+            executingCount: this.executingCount,
+            maxExecutingTransactions: this.config.maxExecutingTransactions,
+            batchDelay: this.config.batchDelay,
+            processBatch: () => { void this.processBatch(); },
+            logger: this.runtime.logger,
+        };
+    }
+    get pendingDrainContext() {
+        return {
+            runtime: this.runtime,
+            config: { deltaConfirmationTimeout: this.config.deltaConfirmationTimeout },
+            store: this.store,
+            executionQueue: this.executionQueue,
+            optimisticUpdates: this.localMutationPort.updates,
+            assertDurableReplayOpen: () => this.assertDurableReplayOpen(),
+            processCommitLane: () => this.processCommitLane(),
+            takePendingDrainBatch: (pending) => this.takePendingDrainBatch(pending),
+            ensureCommitEnvelope: (batch) => this.ensureCommitEnvelope(batch),
+            ensureDerivedFields: (transaction) => this.ensureDerivedFields(transaction),
+            sourceMutationIdsFor: (batch) => this.sourceMutationIdsFor(batch),
+            sealDurableCommit: (input) => this.sealDurableCommit(input),
+            assertEnvelopeInsideReplayWindow: (envelope) => this.assertEnvelopeInsideReplayWindow(envelope),
+            parseMutationCommitResult: (value) => this.parseMutationCommitResult(value),
+            dispatchCommitBounded: (...args) => this.dispatchCommitBounded(...args),
+            persistDurableCommitAcceptance: (envelope, result) => this.persistDurableCommitAcceptance(envelope, result),
+            removeDurableCommit: (idempotencyKey) => this.removeDurableCommit(idempotencyKey),
+            scheduleReplicationLagTimeout: (transactionId, clientTxId, correlationId) => this.scheduleReplicationLagTimeout(transactionId, clientTxId, correlationId),
+            scheduleDeltaConfirmationTimeout: (transaction, timeoutMs) => this.scheduleDeltaConfirmationTimeout(transaction, timeoutMs),
+            enqueue: (transaction) => this.enqueue(transaction),
+            recentDeltaCorrelations: this.recentDeltaCorrelations,
+            emit: (event, payload) => this.emit(event, payload),
+        };
+    }
+    get durableCommitRestoreContext() {
+        return {
+            config: this.config,
+            commitOutbox: this.commitOutbox,
+            commitOutboxScope: this.commitOutboxScope,
+            commitStore: this.commitStore,
+            commitLane: this.commitLane,
+            runtime: this.runtime,
+            processCommitLane: () => this.processCommitLane(),
+            durableReplayWindowMs: MutationQueue.DURABLE_REPLAY_WINDOW_MS,
+        };
+    }
+    get persistenceContext() {
+        return {
+            runtime: this.runtime,
+            persistence: this.persistence,
+            commitOutboxScope: this.commitOutboxScope,
+            config: this.config,
+            store: this.store,
+            enqueue: (transaction) => this.enqueue(transaction),
+            computePriorityScore: (type, modelName) => this.computePriorityScore(type, modelName),
+            deserializeTransaction: (data) => this.deserializeTransaction(data),
+        };
+    }
+    nextCommitSequence() {
+        const wallSequence = Date.now() * 1_000;
+        this.lastCommitSequence = Math.max(wallSequence, this.lastCommitSequence + 1);
+        return this.lastCommitSequence;
+    }
+    emitCommitLifecycle(event, payload) {
+        try {
+            this.emit(event, payload);
+        }
+        catch (error) {
+            this.runtime.observability.captureMutationFailure({
+                context: `commit-lifecycle-listener:${event}`,
+                error: error instanceof Error ? error : String(error),
+            });
+        }
+    }
+    assertDurableReplayOpen() {
+        if (this.durableReplayBlock)
+            throw this.durableReplayBlock;
+    }
+    assertEnvelopeInsideReplayWindow(envelope) {
+        this.assertDurableReplayOpen();
+        if (envelope.acceptedAt === undefined &&
+            Date.now() - envelope.sealedAt >=
+                MutationQueue.DURABLE_REPLAY_WINDOW_MS) {
+            this.durableReplayBlock = new AbloIdempotencyError('A pending commit is older than the server idempotency window; newer writes are blocked until it is reviewed.', { code: 'idempotency_conflict' });
+            // This gate stops EVERY subsequent write on this client, and each of
+            // those rejections is captured to observability rather than surfaced to
+            // the caller — without this line the session degrades into "nothing
+            // saves and nothing errors". One loud line at the moment the block
+            // engages is the only visible trace.
+            this.runtime.logger.warn('sync paused: a saved write from an earlier session is older than the server replay window, so newer writes are held until it is reviewed', { sealedAt: envelope.sealedAt });
+            throw this.durableReplayBlock;
+        }
+    }
+    computePriorityScore(type, modelName) {
+        return computePriorityScore(type, modelName, this.runtime);
+    }
+    ensureDerivedFields(transaction) {
+        if (!transaction.modelKey) {
+            transaction.modelKey = normalizeModelKey(transaction.modelName);
+        }
+        if (transaction.priorityScore === undefined) {
+            transaction.priorityScore = this.computePriorityScore(transaction.type, transaction.modelName);
+        }
+    }
+    entityKey(modelName, modelId) {
+        return entityKey(modelName, modelId);
+    }
+    /** Collision-safe receipt target identity across models sharing a row id. */
+    receiptTargetKey(modelName, modelId) {
+        return stableStringify([normalizeModelKey(modelName), modelId]);
+    }
+    /**
+     * Relates stale notifications back to write targets without assuming the
+     * server's canonical model name uses the same spelling as the public schema
+     * key (`Task` versus `tasks`). Exact `(model,id)` wins; a globally unique id
+     * is the compatibility fallback. An ambiguous same-id cross-model mismatch
+     * is deliberately left unclassified, so it cannot falsely settle a queued
+     * write. A notification with no write-target id (or an explicit group) is a
+     * declared-read conflict and holds the whole batch.
+     */
+    classifyReceiptNotifications(operations, notifications) {
+        const targets = operations.map((operation) => ({
+            id: operation.id,
+            key: this.receiptTargetKey(operation.model, operation.id),
+        }));
+        const heldTargets = new Set();
+        const notificationsByTarget = new Map();
+        let holdsEntireBatch = false;
+        for (const notification of notifications) {
+            const candidates = targets.filter((target) => target.id === notification.id);
+            const notificationKey = this.receiptTargetKey(notification.model, notification.id);
+            const exactTargets = candidates.filter((target) => target.key === notificationKey);
+            const candidateKeys = new Set((exactTargets.length > 0 ? exactTargets : candidates).map((target) => target.key));
+            if (notification.group || candidates.length === 0) {
+                holdsEntireBatch = true;
+                continue;
+            }
+            if (candidateKeys.size !== 1) {
+                // Same id across multiple differently named models with no exact match:
+                // the id-only compatibility fallback is ambiguous. Await the echo.
+                continue;
+            }
+            const [targetKey] = candidateKeys;
+            if (!targetKey)
+                continue;
+            heldTargets.add(targetKey);
+            const targetNotifications = notificationsByTarget.get(targetKey) ?? [];
+            targetNotifications.push(notification);
+            notificationsByTarget.set(targetKey, targetNotifications);
+        }
+        return { holdsEntireBatch, heldTargets, notificationsByTarget };
+    }
+    resolveConfirmation(transaction) {
+        const resolver = this.confirmationResolvers.get(transaction.id);
+        if (!resolver)
+            return;
+        this.confirmationResolvers.delete(transaction.id);
+        resolver.resolve();
+    }
+    takeUnsentCreateForModel(modelName, modelId) {
+        return takeUnsentCreateForModel(this.createdTransactions, this.executionQueue, this.store, modelName, modelId);
+    }
+    async cancelUnsentCreateForDelete(transaction) {
+        this.store.updateStatus(transaction.id, 'rolled_back');
+        if (this.config.enableOptimistic) {
+            await this.rollbackOptimistic(transaction, 'model_cancelled');
+        }
+        this.resolveConfirmation(transaction);
+    }
+    findCreateBarrierForDelete(modelName, modelId) {
+        return findCreateBarrierForDelete(this.store, modelName, modelId);
+    }
+    completeLocalDelete(model, context, writeOptions, sourceMutationIds = []) {
+        const actualModelName = model.getModelName();
+        const modelKey = normalizeModelKey(actualModelName);
+        const transaction = {
+            id: this.generateId(),
+            type: 'delete',
+            modelName: actualModelName,
+            modelId: model.id,
+            modelKey,
+            priorityScore: this.computePriorityScore('delete', actualModelName),
+            previousData: model.toJSON ? model.toJSON() : { ...model },
+            context,
+            status: 'completed',
+            createdAt: Date.now(),
+            attempts: 0,
+            priority: 'high',
+            writeOptions,
+            ...(sourceMutationIds.length > 0
+                ? { sourceMutationIds: [...new Set(sourceMutationIds)] }
+                : {}),
+            localOnly: true,
+        };
+        this.attachConfirmation(transaction);
+        this.store.add(transaction);
+        if (this.config.enableOptimistic) {
+            this.applyOptimisticDelete(model, transaction);
+        }
+        this.emit('transaction:created', transaction);
+        this.emit('transaction:completed', transaction);
+        this.emit(`transaction:completed:${transaction.id}`, transaction);
+        this.localMutationPort.updates.delete(transaction.id);
+        return transaction;
+    }
+    deferDeleteUntilCreateSettles(createTransaction, deleteTransaction) {
+        deferDeleteUntilCreateSettles(this.deferredDeletesByCreate, createTransaction, deleteTransaction);
+    }
+    releaseDeferredDeletesForCreate(createTransaction) {
+        releaseDeferredDeletesForCreate(this.deferredDeletesByCreate, this.store, (tx) => { this.enqueue(tx); }, createTransaction);
+    }
+    // Default configuration, tuned so more operations coalesce into a single
+    // commit: a larger batch size and delay give rapid operations more time to
+    // merge before the batch is sent.
+    config = {
+        maxBatchSize: 50, // send up to this many operations per commit
+        batchDelay: 150, // milliseconds to wait for more operations before sending
+        maxRetries: 3,
+        conflictResolution: {
+            strategy: 'last-write-wins',
+        },
+        enablePersistence: true,
+        enableOptimistic: true,
+        maxExecutingTransactions: 100,
+        deltaConfirmationTimeout: 30000,
+        retryBackoff: { baseMs: 200, capMs: 1500 },
+        commitOfflineGraceMs: 30_000,
+        commitDispatchTimeoutMs: 30_000,
+    };
+    // Track executing transactions for backpressure
+    executingCount = 0;
+    localMutationPort;
+    // Stale-context notifications, keyed by transaction id. When the server
+    // accepts a commit but reports that an operation's premise had moved,
+    // the notification lands here from the commit acknowledgement and is drained
+    // by `waitForCommitReceipt`, so the receipt can carry it back to the caller.
+    commitNotifications = new Map();
+    /** Zero-row targets returned on a successful atomic commit receipt. */
+    commitMissingIds = new Map();
+    // Delta-confirmation tracking (ack watermark advance + the awaiting_delta
+    // timeout/retry maps) lives in `./deltaConfirmation.js`. Constructed in the
+    // constructor once `position` is bound.
+    deltaConfirmation;
+    // Connection-state check, supplied by the client, used to hold off rollbacks
+    // while disconnected.
+    isConnectedFn = () => true;
+    // Grace timer that, when fired, fails any commit-lane transaction
+    // still awaiting an ack. Started on `setConnectionState('disconnected')`,
+    // cleared on `'connected'`. The reconnect-retry behavior of the queue
+    // is preserved for brief blips; this only catches persistent disconnects.
+    commitOfflineGraceTimer = null;
+    /**
+     * This client's place in the global order of sync deltas. The instance is
+     * shared: the client injects one, and a standalone queue creates its own. The
+     * queue advances the `acked` cursor as commit responses arrive, the store
+     * advances `applied` and `persisted`, and snapshots and claims read
+     * `readFloor`. See `../logPosition.js` for the full contract.
+     */
+    position;
+    /** Applied-cursor alias, kept so the many internal read sites stay legible. */
+    get lastSeenSyncId() {
+        return this.position.applied;
+    }
+    noteAck(lastSyncId) {
+        this.deltaConfirmation.noteAck(lastSyncId);
+    }
+    // Batch management
+    batchIndex = 0;
+    /** Mints the request identity once; retry paths only read the stored value. */
+    generateCommitIdempotencyKey() {
+        return `commit_${uuid()}`;
+    }
+    /**
+     * Binds an ordered transaction batch to one wire-level idempotency key.
+     * Existing envelopes are validated and restored to their original order;
+     * they are never extended with newly queued work.
+     */
+    ensureCommitEnvelope(batch) {
+        const firstTransaction = batch[0];
+        if (!firstTransaction) {
+            throw new Error('Cannot create an idempotency envelope for an empty commit');
+        }
+        const existingKeys = new Set(batch
+            .map((tx) => tx.commitEnvelope?.idempotencyKey)
+            .filter((key) => key !== undefined));
+        if (existingKeys.size > 1) {
+            throw new Error('Cannot combine transactions from different commit envelopes');
+        }
+        const existingKey = existingKeys.values().next().value;
+        if (existingKey) {
+            const expectedCount = firstTransaction.commitEnvelope?.operationCount;
+            const indexes = new Set(batch.map((tx) => tx.commitEnvelope?.operationIndex));
+            const isCompleteEnvelope = expectedCount === batch.length &&
+                indexes.size === batch.length &&
+                batch.every((tx) => tx.commitEnvelope?.idempotencyKey === existingKey &&
+                    tx.commitEnvelope.operationCount === expectedCount &&
+                    tx.commitEnvelope.operationIndex < expectedCount);
+            if (!isCompleteEnvelope) {
+                throw new Error('Cannot replay a partial or malformed commit envelope');
+            }
+            const persistedSealTimes = new Set(batch
+                .map((transaction) => transaction.commitEnvelope?.sealedAt)
+                .filter((sealedAt) => sealedAt !== undefined));
+            if (persistedSealTimes.size > 1) {
+                throw new Error('Cannot replay a commit envelope with inconsistent seal times');
+            }
+            const sealedAt = persistedSealTimes.values().next().value ?? Date.now();
+            for (const transaction of batch) {
+                if (transaction.commitEnvelope)
+                    transaction.commitEnvelope.sealedAt = sealedAt;
+            }
+            batch.sort((a, b) => (a.commitEnvelope?.operationIndex ?? 0) -
+                (b.commitEnvelope?.operationIndex ?? 0));
+            return existingKey;
+        }
+        // An explicit public key owns its request. Transactions carrying one are
+        // selected as solo batches by takeNextExecutionBatch().
+        const explicitKey = batch.length === 1
+            ? firstTransaction.writeOptions?.idempotencyKey
+            : undefined;
+        const idempotencyKey = typeof explicitKey === 'string' && explicitKey.length > 0
+            ? explicitKey
+            : this.generateCommitIdempotencyKey();
+        const sealedAt = Date.now();
+        const sequence = this.nextCommitSequence();
+        batch.forEach((tx, operationIndex) => {
+            tx.commitEnvelope = createCommitEnvelopeMember({
+                idempotencyKey,
+                operationIndex,
+                operationCount: batch.length,
+                sealedAt,
+                sequence,
+            });
+        });
+        return idempotencyKey;
+    }
+    /** Bind the strict local outbox used before any mutation reaches the wire. */
+    setCommitOutbox(outbox) {
+        this.commitOutbox = outbox;
+    }
+    async setCommitOutboxScope(scope) {
+        this.commitOutboxScope = scope;
+        const deferred = this.deferredMutations;
+        this.deferredMutations = [];
+        await Promise.all(deferred.map((mutation) => this.enqueueModelMutation(mutation.type, mutation.model, { userId: scope.participantId, organizationId: scope.organizationId }, mutation.capturedChanges, mutation.writeOptions)));
+    }
+    deferMutation(type, model, capturedChanges, writeOptions) {
+        this.runtime.logger.debug('[MutationQueue] Deferring mutation until identity is resolved', { type, model: model.getModelName(), modelId: model.id });
+        this.deferredMutations.push({ type, model, capturedChanges, writeOptions });
+    }
+    async enqueueModelMutation(type, model, context, capturedChanges, writeOptions) {
+        switch (type) {
+            case 'create': return this.create(model, context, writeOptions);
+            case 'update': return this.update(model, context, capturedChanges, writeOptions);
+            case 'delete': return this.delete(model, context, writeOptions);
+            case 'archive': return this.archive(model, context, writeOptions);
+        }
+    }
+    /** Attach the durable journal supplied by the local/materializer layer. */
+    setPersistence(persistence) {
+        this.persistence = persistence;
+    }
+    async persistQueuedTransaction(transaction, modelData) {
+        await persistQueuedTransaction(this.persistenceContext, transaction, modelData);
+    }
+    persistAndStage(transaction, modelData) {
+        if (!this.persistence || !this.commitOutboxScope) {
+            this.stageTransaction(transaction);
+            return Promise.resolve();
+        }
+        return new Promise((resolve, reject) => {
+            this.pendingPersistenceStages.push({ transaction, modelData, resolve, reject });
+            if (this.persistenceStageScheduled)
+                return;
+            this.persistenceStageScheduled = true;
+            queueMicrotask(async () => {
+                this.persistenceStageScheduled = false;
+                const batch = this.pendingPersistenceStages;
+                this.pendingPersistenceStages = [];
+                const results = await Promise.allSettled(batch.map(({ transaction: queued, modelData: data }) => this.persistQueuedTransaction(queued, data)));
+                for (const [index, result] of results.entries()) {
+                    const item = batch[index];
+                    if (!item)
+                        continue;
+                    if (result.status === 'fulfilled') {
+                        this.stageTransaction(item.transaction);
+                        item.resolve();
+                    }
+                    else {
+                        item.reject(result.reason instanceof Error ? result.reason : new Error(String(result.reason)));
+                    }
+                }
+            });
+        });
+    }
+    removePersistedTransaction(transactionId) {
+        removePersistedTransaction(this.persistenceContext, transactionId);
+    }
+    settlePersistedFailure(transaction) {
+        settlePersistedFailure(this.persistenceContext, transaction);
+    }
+    sourceMutationIdsFor(batch) {
+        return [...new Set(batch.flatMap((transaction) => transaction.sourceMutationIds ?? []))];
+    }
+    /** Atomically seals a commit before it is allowed onto the dispatch lane. */
+    async sealDurableCommit(input) {
+        return sealDurableCommit(this.commitTransportContext, input, pendingMutationRecordId);
+    }
+    async removeDurableCommit(idempotencyKey) {
+        return removeDurableCommit(this.commitTransportContext, idempotencyKey);
+    }
+    async persistDurableCommitAcceptance(envelope, result) {
+        return persistDurableCommitAcceptance(this.commitTransportContext, envelope, result);
+    }
+    parseMutationCommitResult(value) {
+        return parseMutationCommitResult(value);
+    }
+    dispatchCommitBounded(...args) {
+        return dispatchCommitBounded(this.commitTransportContext, ...args);
+    }
+    clearReplicationLagState(transactionId) {
+        const timeout = this.replicationLagTimeouts.get(transactionId);
+        if (timeout)
+            clearTimeout(timeout);
+        this.replicationLagTimeouts.delete(transactionId);
+        this.replicationLagErrors.delete(transactionId);
+    }
+    /**
+     * Bounds the public `wait: 'confirmed'` promise without changing the
+     * accepted write's lifecycle. A lag timeout is not a rejection from the
+     * source database, so it must never emit `transaction:failed`, roll back
+     * optimistic state, or remove the durable replay envelope.
+     */
+    scheduleReplicationLagTimeout(transactionId, clientTxId = transactionId, correlationId) {
+        const previous = this.replicationLagTimeouts.get(transactionId);
+        if (previous)
+            clearTimeout(previous);
+        this.replicationLagErrors.delete(transactionId);
+        const timeoutMs = this.config.deltaConfirmationTimeout;
+        const timeout = setTimeout(() => {
+            this.replicationLagTimeouts.delete(transactionId);
+            const modelTx = this.store.get(transactionId);
+            const commitTx = this.commitStore.get(transactionId);
+            if (modelTx?.status !== 'awaiting_delta' &&
+                commitTx?.status !== 'awaiting_delta')
+                return;
+            const error = new AbloConnectionError(`The source accepted commit ${clientTxId}, but its replication echo did not arrive within ${timeoutMs}ms.`, {
+                code: 'replication_lag_timeout',
+                httpStatus: 504,
+                details: {
+                    clientTxId,
+                    ...(correlationId ? { correlationId } : {}),
+                    timeoutMs,
+                    accepted: true,
+                },
+            });
+            this.replicationLagErrors.set(transactionId, error);
+            // Model-proxy writes expose their waiter through the resolver table.
+            // Reject that promise without moving the transaction out of
+            // `awaiting_delta`; the eventual echo still completes it normally.
+            const resolver = this.confirmationResolvers.get(transactionId);
+            if (resolver) {
+                this.confirmationResolvers.delete(transactionId);
+                resolver.reject(error);
+            }
+            this.emitCommitLifecycle('transaction:confirmation_lagged', {
+                transactionId,
+                error,
+            });
+            this.emitCommitLifecycle(`transaction:confirmation_lagged:${transactionId}`, {
+                error,
+            });
+            if (commitTx) {
+                const firstOperation = commitTx.operations[0];
+                this.emitCommitLifecycle('reconciliation:needed', {
+                    reason: 'replication_lag_timeout',
+                    txId: transactionId,
+                    model: firstOperation?.model ?? 'commit',
+                    modelId: firstOperation?.id ?? transactionId,
+                    lastSeenSyncId: this.lastSeenSyncId,
+                    retryCount: 1,
+                });
+            }
+        }, timeoutMs);
+        this.replicationLagTimeouts.set(transactionId, timeout);
+    }
+    takeNextExecutionBatch() {
+        const selected = selectExecutionBatch(this.executionQueue, this.config.maxBatchSize);
+        this.executionQueue = selected.remaining;
+        return selected.batch;
+    }
+    takePendingDrainBatch(pending) {
+        return selectPendingDrainBatch(pending, this.config.maxBatchSize);
+    }
+    /**
+     * Resolvers for per-transaction `confirmation` promises. Populated in
+     * `attachConfirmation` at staging time, consumed by the constructor-time
+     * listeners on `transaction:completed` / `transaction:failed`. Kept off
+     * the QueuedMutation row so the store's iteration order stays plain-data
+     * and serialization-friendly.
+     */
+    confirmationResolvers = new Map();
+    constructor(config) {
+        super();
+        this.runtime = config?.runtime ?? globalRuntime;
+        this.position = config?.position ?? new LogPosition();
+        this.localMutationPort = config?.localMutationPort ?? createLocalMutationPort(this);
+        // Bind the confirmation tracker to this queue's store/ledger/events.
+        // `isConnected` closes over `isConnectedFn` so `setConnectionChecker`
+        // swaps stay visible to in-flight timeouts.
+        this.deltaConfirmation = new DeltaConfirmationTracker({
+            store: this.store,
+            optimisticUpdates: this.localMutationPort.updates,
+            emit: (event, payload) => {
+                this.emit(event, payload);
+            },
+            isConnected: () => this.isConnectedFn(),
+            position: this.position,
+            runtime: this.runtime,
+        });
+        if (config) {
+            this.config = { ...this.config, ...config };
+        }
+        // Centralized fan-in for `tx.confirmation`. Completion/failure are
+        // emitted from ~10 sites (delta confirm, immediate confirm, batch
+        // success, permanent error, max_retries_exhausted, …). Subscribing
+        // once here keeps every emit site intact and guarantees the call-site
+        // promise always settles, regardless of which path produced the
+        // terminal state.
+        this.on('transaction:completed', (tx) => {
+            // Any successful write clears the permanent-error dedup, so a genuine
+            // recurrence after recovery warns again instead of staying demoted.
+            this.lastPermanentErrorSig = undefined;
+            this.clearReplicationLagState(tx.id);
+            const r = this.confirmationResolvers.get(tx.id);
+            if (r) {
+                this.confirmationResolvers.delete(tx.id);
+                r.resolve();
+            }
+            if (tx.type === 'create') {
+                this.releaseDeferredDeletesForCreate(tx);
+            }
+            this.removePersistedTransaction(tx.id);
+        });
+        this.on('transaction:failed', ({ transaction, error }) => {
+            const r = this.confirmationResolvers.get(transaction.id);
+            if (r) {
+                this.confirmationResolvers.delete(transaction.id);
+                r.reject(error);
+            }
+            if (transaction.type === 'create') {
+                this.releaseDeferredDeletesForCreate(transaction);
+            }
+            this.settlePersistedFailure(transaction);
+        });
+    }
+    /**
+     * Returns the in-flight confirmation promise for a given model and id. When
+     * several transactions match, it returns the most recent one's promise; when
+     * none is open it resolves immediately, which covers both "already confirmed"
+     * and "never staged".
+     *
+     * It considers the three non-terminal statuses in which the write can still
+     * be rolled back — `pending`, `executing`, and `awaiting_delta` — and ignores
+     * `completed` (already settled) and `failed`/`rolled_back` (already
+     * rejected). This complements the `confirmation` promise carried on a known
+     * {@link QueuedMutation}: use this method at call sites that hold a model
+     * returned by `ablo.<model>.create()` but never see the underlying
+     * transaction.
+     */
+    confirmationFor(modelName, modelId) {
+        const candidates = [
+            ...this.store.getByStatus('pending'),
+            ...this.store.getByStatus('executing'),
+            ...this.store.getByStatus('awaiting_delta'),
+        ].filter((tx) => tx.modelName === modelName && tx.modelId === modelId);
+        if (candidates.length === 0)
+            return Promise.resolve();
+        const latest = candidates.sort((a, b) => b.createdAt - a.createdAt)[0];
+        if (!latest)
+            return Promise.resolve();
+        return latest.confirmation ?? Promise.resolve();
+    }
+    /**
+     * Attaches a `confirmation` promise to a newly created transaction. Call this
+     * before the transaction is staged so a caller can `await tx.confirmation`
+     * immediately after a create, update, or delete returns. It is idempotent and
+     * returns early if one is already attached.
+     *
+     * It also attaches a no-op rejection handler. Most callers never await the
+     * confirmation, and without this the runtime would report an unhandled
+     * rejection when a write fails. Callers that do want to observe failure simply
+     * attach their own `.then`/`.catch`.
+     */
+    attachConfirmation(tx) {
+        if (tx.confirmation)
+            return;
+        tx.confirmation = new Promise((resolve, reject) => {
+            this.confirmationResolvers.set(tx.id, { resolve, reject });
+        });
+        tx.confirmation.catch(() => {
+            // Swallow unhandled rejections; callers that care attach their own handler.
+        });
+    }
+    /**
+     * Registers a predicate the queue uses to check whether it is connected.
+     * While disconnected, confirmation timeouts re-schedule themselves instead of
+     * escalating, so a transaction is never rolled back merely because the client
+     * was briefly offline.
+     */
+    setConnectionChecker(fn) {
+        this.isConnectedFn = fn;
+    }
+    /**
+     * Drives the offline-grace timer for in-flight commit-lane transactions.
+     *
+     * On `'disconnected'` it starts a one-shot timer of
+     * `config.commitOfflineGraceMs`. If that timer fires — meaning the disconnect
+     * outlasted the grace window — every commit-lane transaction still `pending`
+     * or `executing` is failed with an {@link AbloConnectionError}, so
+     * {@link waitForCommitReceipt} rejects within seconds instead of hanging.
+     *
+     * On `'connected'` it clears any pending grace timer. Brief disconnects are
+     * absorbed transparently; {@link processCommitLane} and
+     * {@link drainPending} resumes the work when the owner decides to drain.
+     */
+    setConnectionState(state) {
+        if (state === 'connected') {
+            if (this.commitOfflineGraceTimer !== null) {
+                clearTimeout(this.commitOfflineGraceTimer);
+                this.commitOfflineGraceTimer = null;
+            }
+            return;
+        }
+        // state === 'disconnected'
+        if (this.commitOfflineGraceTimer !== null)
+            return; // already armed
+        const graceMs = this.config.commitOfflineGraceMs;
+        this.commitOfflineGraceTimer = setTimeout(() => {
+            this.commitOfflineGraceTimer = null;
+            this.failInFlightCommitsOnOffline(graceMs);
+        }, graceMs);
+    }
+    failInFlightCommitsOnOffline(graceMs) {
+        const inFlight = [];
+        for (const [id, tx] of this.commitStore.entries()) {
+            if (tx.status === 'pending' || tx.status === 'executing') {
+                inFlight.push(id);
+            }
+        }
+        if (inFlight.length === 0)
+            return;
+        // Each failed commit reaches the consumer through its own rejection path,
+        // so this aggregate line is forensic and logged at debug rather than warn.
+        this.runtime.logger.debug(`[MutationQueue] WS disconnected > ${graceMs}ms; failing ${inFlight.length} in-flight commit(s) with AbloConnectionError`, { inFlightIds: inFlight.map((id) => id.slice(0, 8)) });
+        for (const id of inFlight) {
+            const tx = this.commitStore.get(id);
+            if (!tx)
+                continue;
+            const err = new AbloConnectionError(`commit ack abandoned after ${graceMs}ms offline`, { code: 'commit_offline_grace_expired' });
+            tx.status = 'failed';
+            tx.error = err;
+            this.emit(`transaction:failed:${id}`, { error: err });
+        }
+    }
+    /**
+     * Binds the mutation executor for this queue instance. The owning client
+     * calls this right after construction, so commits made here always dispatch
+     * through this instance's connection even when several client instances exist
+     * in the same process.
+     */
+    setMutationExecutor(executor) {
+        this._mutationExecutor = executor;
+    }
+    // ============================================================================
+    // Microtask-based transaction staging
+    // ============================================================================
+    //
+    // Every transaction lands in the `createdTransactions` staging area first.
+    // A microtask then commits them together under one batch index, so a bulk
+    // operation such as importing a hundred rows is sent efficiently.
+    //
+    // Flow:
+    // 1. create()/update()/delete() calls stageTransaction().
+    // 2. stageTransaction() adds to createdTransactions and schedules a microtask.
+    // 3. The microtask runs commitCreatedTransactions() once the current
+    //    synchronous code finishes.
+    // 4. All staged transactions share one batch index and move to the execution
+    //    queue.
+    // ============================================================================
+    /**
+     * Stages a transaction for commit. Transactions staged within the same
+     * event-loop tick are committed together.
+     */
+    stageTransaction(transaction) {
+        this.createdTransactions.push(transaction);
+        this.scheduleCommit();
+    }
+    /**
+     * Schedules the staged transactions to commit on a microtask, so all
+     * transactions created synchronously within one tick are batched together.
+     */
+    scheduleCommit() {
+        if (this.commitScheduled)
+            return;
+        this.commitScheduled = true;
+        // Use queueMicrotask to run after current sync code completes
+        // All transactions created in same event loop will be committed together
+        const schedule = typeof queueMicrotask === 'function'
+            ? queueMicrotask
+            : (cb) => Promise.resolve().then(cb);
+        schedule(() => {
+            this.commitCreatedTransactions();
+        });
+    }
+    /**
+     * Moves all staged transactions onto the execution queue, assigning them a
+     * single shared batch index so they commit together.
+     */
+    commitCreatedTransactions() {
+        this.commitScheduled = false;
+        if (this.createdTransactions.length === 0)
+            return;
+        // Increment batch index - all transactions in this commit share it
+        this.batchIndex++;
+        const currentBatchIndex = this.batchIndex;
+        // Log batch commit for performance monitoring
+        this.runtime.logger.debug('[MutationQueue] commitCreatedTransactions', {
+            count: this.createdTransactions.length,
+            batchIndex: currentBatchIndex,
+            types: this.createdTransactions.map((t) => `${t.type}:${t.modelName}`),
+        });
+        // Move all staged transactions to execution queue
+        const staged = this.createdTransactions;
+        this.createdTransactions = [];
+        for (const transaction of staged) {
+            // Assign batch ID based on current batch index
+            transaction.batchId = `batch_${currentBatchIndex}`;
+            this.enqueue(transaction);
+        }
+    }
+    /**
+     * Flushes every pending transaction in one commit, the fast path taken on
+     * reconnect. If transport fails, the transactions retain this exact commit
+     * envelope when they fall back to normal queue processing.
+     */
+    async drainPending() {
+        if (this.pendingDrainPromise)
+            return this.pendingDrainPromise;
+        const drain = this.drainPendingInternal();
+        this.pendingDrainPromise = drain.finally(() => {
+            this.pendingDrainPromise = null;
+        });
+        return this.pendingDrainPromise;
+    }
+    async drainPendingInternal() {
+        await drainPendingSettlements(this.pendingDrainContext);
+    }
+    async create(model, context, writeOptions, sourceMutationId) {
+        return createModel(this.modelMutationContext, model, context, writeOptions, sourceMutationId);
+    }
+    async update(model, context, precomputedChanges, writeOptions, sourceMutationId) {
+        return updateModel(this.modelMutationContext, model, context, precomputedChanges, writeOptions, sourceMutationId);
+    }
+    async delete(model, context, writeOptions, sourceMutationId) {
+        return deleteModel(this.modelMutationContext, model, context, writeOptions, sourceMutationId);
+    }
+    async uploadAttachment(_file, options, _context // eslint-disable-line @typescript-eslint/no-unused-vars -- reserved executor context
+    ) {
+        return this.mutationExecutor.uploadAttachment?.(options.id, options) ?? null;
+    }
+    async batchUploadAttachments(_files, items, _context // eslint-disable-line @typescript-eslint/no-unused-vars -- reserved executor context
+    ) {
+        return this.mutationExecutor.batchUploadAttachments?.(items.map(i => ({ id: i.id, input: i }))) ?? [];
+    }
+    async archive(model, context, writeOptions, sourceMutationId) {
+        return archiveModel(this.modelMutationContext, model, context, writeOptions, sourceMutationId);
+    }
+    async unarchive(model, context) {
+        return unarchiveModel(this.modelMutationContext, model, context);
+    }
+    enqueue(transaction) {
+        enqueueTransaction(this.queueCoalescingContext, transaction);
+    }
+    scheduleProcessing(immediate = false) {
+        scheduleProcessingExternal(this.processingSchedulerContext, immediate);
+    }
+    async processBatch() {
+        await processBatch(this.batchProcessingContext);
+    }
+    rememberDeltaCorrelation(correlationId, syncId) {
+        // Refresh insertion order when a replay repeats the same correlation id.
+        this.recentDeltaCorrelations.delete(correlationId);
+        this.recentDeltaCorrelations.set(correlationId, syncId);
+        if (this.recentDeltaCorrelations.size <= 2_048)
+            return;
+        const oldest = this.recentDeltaCorrelations.keys().next().value;
+        if (typeof oldest === 'string')
+            this.recentDeltaCorrelations.delete(oldest);
+    }
+    queuedCommitEchoSyncId(tx) {
+        return tx.correlationId
+            ? this.recentDeltaCorrelations.get(tx.correlationId)
+            : undefined;
+    }
+    queuedCommitMatchesCorrelation(tx, correlationId) {
+        return tx.correlationId !== undefined && tx.correlationId === correlationId;
+    }
+    completeQueuedCommit(tx, syncId) {
+        if (tx.status !== 'awaiting_delta')
+            return;
+        this.clearReplicationLagState(tx.id);
+        tx.lastSyncId = syncId;
+        tx.status = 'completed';
+        // The queued receipt was only acceptance. The correlated source echo is
+        // the first definitive success and therefore the point where the durable
+        // replay envelope may be removed.
+        void this.removeDurableCommit(tx.id);
+        this.emitCommitLifecycle('transaction:completed', tx);
+        this.emitCommitLifecycle(`transaction:completed:${tx.id}`, tx);
+    }
+    /**
+     * Confirms awaiting writes. Hosted/anomaly receipts keep their sync-id
+     * threshold semantics; queued forwards require the exact server correlation.
+     */
+    onDeltaReceived(syncId, _transactionId, correlationId) {
+        if (correlationId)
+            this.rememberDeltaCorrelation(correlationId, syncId);
+        const correlatedModelTransactions = correlationId
+            ? this.store.getByStatus('awaiting_delta').filter((tx) => tx.requiresCorrelatedDelta === true &&
+                tx.correlationId !== undefined &&
+                tx.correlationId === correlationId)
+            : [];
+        this.deltaConfirmation.onDeltaReceived(syncId, correlationId);
+        if (correlatedModelTransactions.length > 0) {
+            const envelopeIds = new Set();
+            for (const tx of correlatedModelTransactions) {
+                this.clearReplicationLagState(tx.id);
+                if (tx.commitEnvelope)
+                    envelopeIds.add(tx.commitEnvelope.idempotencyKey);
+            }
+            for (const envelopeId of envelopeIds) {
+                const envelopeStillAwaiting = this.store
+                    .getByStatus('awaiting_delta')
+                    .some((tx) => tx.commitEnvelope?.idempotencyKey === envelopeId);
+                if (!envelopeStillAwaiting)
+                    void this.removeDurableCommit(envelopeId);
+            }
+        }
+        if (!correlationId)
+            return;
+        for (const tx of this.commitStore.values()) {
+            if (tx.status !== 'awaiting_delta')
+                continue;
+            if (this.queuedCommitMatchesCorrelation(tx, correlationId)) {
+                this.completeQueuedCommit(tx, syncId);
+            }
+        }
+    }
+    // Schedule the retry-and-reconciliation wait for a transaction's confirming
+    // delta; see {@link DeltaConfirmationTracker} in `./deltaConfirmation.js`.
+    scheduleDeltaConfirmationTimeout(tx, timeoutMs) {
+        this.deltaConfirmation.scheduleDeltaConfirmationTimeout(tx, timeoutMs);
+    }
+    /**
+     * Resolves once the given transaction is confirmed and rejects if it fails.
+     * The confirming delta's timeout is handled by
+     * {@link scheduleDeltaConfirmationTimeout}.
+     */
+    waitForConfirmation(transactionId) {
+        return new Promise((resolve, reject) => {
+            // Check if already completed
+            const tx = this.store.get(transactionId);
+            if (tx?.status === 'completed') {
+                resolve();
+                return;
+            }
+            const lagError = this.replicationLagErrors.get(transactionId);
+            if (lagError) {
+                reject(lagError);
+                return;
+            }
+            const onCompleted = () => {
+                cleanup();
+                resolve();
+            };
+            const onFailed = ({ error }) => {
+                cleanup();
+                reject(error);
+            };
+            const onLagged = ({ error }) => {
+                cleanup();
+                reject(error);
+            };
+            const cleanup = () => {
+                this.off(`transaction:completed:${transactionId}`, onCompleted);
+                this.off(`transaction:failed:${transactionId}`, onFailed);
+                this.off(`transaction:confirmation_lagged:${transactionId}`, onLagged);
+            };
+            // Listen to existing events (timeout already handled by scheduleDeltaConfirmationTimeout)
+            this.on(`transaction:completed:${transactionId}`, onCompleted);
+            this.on(`transaction:failed:${transactionId}`, onFailed);
+            this.on(`transaction:confirmation_lagged:${transactionId}`, onLagged);
+        });
+    }
+    // Reports whether a client mutation id is known to this queue, which helps
+    // identify a delta as this client's own echo.
+    hasClientMutationId(id) {
+        return !!this.store.get(id) || this.commitStore.has(id);
+    }
+    /** Enqueues a pre-built atomic commit through the commit API coordinator. */
+    async enqueueCommit(clientTxId, operations, options = {}) {
+        return enqueueCommit(this.commitApiContext, clientTxId, operations, options);
+    }
+    async processCommitLane() {
+        await processCommitLane(this.commitLaneContext);
+    }
+    waitForCommitReceipt(clientTxId) {
+        return waitForCommitReceipt(this.commitReceiptContext, clientTxId);
+    }
+    isReorderPayload(data) {
+        if (!data || typeof data !== 'object')
+            return false;
+        return 'order' in data || 'orderKey' in data || 'position' in data;
+    }
+    isPermanentError(error) {
+        return classifyPermanentError(error);
+    }
+    isDefinitiveRejection(error) {
+        return classifyDefinitiveRejection(error);
+    }
+    async handleFailure(transaction, error) {
+        await handleFailure(this.failureHandlingContext, transaction, error);
+    }
+    async handleConflict(transaction, serverData) {
+        await resolveConflict(this.conflictPolicyContext, transaction, serverData);
+    }
+    applyOptimisticCreate(model, transaction) {
+        this.localMutationPort.applyCreate(model, transaction);
+    }
+    applyOptimisticUpdate(model, transaction) {
+        this.localMutationPort.applyUpdate(model, transaction);
+    }
+    applyOptimisticDelete(model, transaction) {
+        this.localMutationPort.applyDelete(model, transaction);
+    }
+    async rollbackOptimistic(transaction, reason, error) {
+        await this.localMutationPort.rollback(transaction, reason, error);
+    }
+    deserializeLegacyPendingMutation(row, fallbackMutationId) {
+        return deserializeLegacyPendingMutation(this.persistenceContext, row, fallbackMutationId);
+    }
+    async loadPersistedTransactions(persistence, sealedMutationIds = new Set()) {
+        await loadPersistedTransactions(this.persistenceContext, persistence, sealedMutationIds);
+    }
+    async restoreDurableCommits() {
+        return restoreDurableCommitsExternal(this.durableCommitRestoreContext);
+    }
+    deserializeTransaction(data) {
+        if (isNonReplayablePersistedRow(data))
+            return null;
+        const transaction = deserializePersistedTransaction(data, this.runtime);
+        if (!transaction) {
+            const rowId = typeof data === 'object' && data !== null && typeof data.id === 'string'
+                ? data.id
+                : undefined;
+            this.runtime.logger.debug('[MutationQueue] Dropping malformed persisted transaction', {
+                rowId,
+            });
+            this.runtime.observability.captureMutationFailure({
+                context: 'deserialize-persisted-transaction',
+                error: `Persisted transaction failed schema validation${rowId ? ` (id: ${rowId})` : ''}`,
+            });
+            return null;
+        }
+        return transaction;
+    }
+    cancelTransactionsForModel(modelId, transactionType) {
+        const cancelledTransactions = [];
+        const allTransactions = [
+            ...this.store.getByStatus('pending'),
+            ...this.store.getByStatus('executing'),
+        ];
+        for (const transaction of allTransactions) {
+            if (transaction.modelId === modelId) {
+                if (!transactionType || transaction.type === transactionType) {
+                    cancelledTransactions.push(transaction);
+                    this.store.updateStatus(transaction.id, 'rolled_back');
+                    // Sync caller: a rejected rollback (throwing optimistic:rollback
+                    // listener) must surface, not vanish — the status flip above is
+                    // already committed either way.
+                    void this.rollbackOptimistic(transaction, 'model_cancelled').catch((error) => {
+                        this.runtime.observability.captureMutationFailure({
+                            context: 'rollback-model-cancelled',
+                            error: error instanceof Error ? error : String(error),
+                        });
+                    });
+                }
+            }
+        }
+        return cancelledTransactions;
+    }
+    /**
+     * Cancels pending transactions for child rows that reference a deleted parent,
+     * used to cascade a parent deletion. The caller supplies the foreign-key
+     * relationship; this method performs the cancellation.
+     *
+     * @param childModelName - The child model type (for example 'Block').
+     * @param foreignKey - The foreign-key property name (for example 'sectionId').
+     * @param parentId - The deleted parent's id.
+     * @returns The number of transactions cancelled.
+     */
+    cancelTransactionsByForeignKey(childModelName, foreignKey, parentId) {
+        let cancelled = 0;
+        const allTransactions = [
+            ...this.store.getByStatus('pending'),
+            ...this.store.getByStatus('executing'),
+            ...this.store.getByStatus('awaiting_delta'),
+        ];
+        for (const transaction of allTransactions) {
+            if (transaction.modelName === childModelName) {
+                // Check if this transaction's data contains the parent FK
+                const fkValue = transaction.data?.[foreignKey];
+                if (fkValue === parentId) {
+                    this.store.updateStatus(transaction.id, 'rolled_back');
+                    void this.rollbackOptimistic(transaction, 'cascade_parent_deleted').catch((error) => {
+                        this.runtime.observability.captureMutationFailure({
+                            context: 'rollback-cascade-parent-deleted',
+                            error: error instanceof Error ? error : String(error),
+                        });
+                    });
+                    cancelled++;
+                    this.runtime.logger.debug('[MutationQueue] Cascade cancelled orphaned transaction', {
+                        txId: transaction.id.slice(0, 12),
+                        model: childModelName,
+                        foreignKey,
+                        parentId: parentId.slice(0, 12),
+                    });
+                }
+            }
+        }
+        return cancelled;
+    }
+    /**
+     * Returns the number of transactions still pending or executing.
+     */
+    getOutstandingTransactionCount() {
+        return this.deferredMutations.length +
+            this.store.getByStatus('pending').length +
+            this.store.getByStatus('executing').length;
+    }
+    getOutstandingTransactions() {
+        return [
+            ...this.store.getByStatus('pending'),
+            ...this.store.getByStatus('executing'),
+        ];
+    }
+    /** Generates a unique local transaction id. */
+    generateId() {
+        return `tx_${Date.now()}_${Math.random().toString(36).substring(2, 11)}`;
+    }
+    mergeData(local, remote) {
+        return { ...(remote || {}), ...(local || {}) };
+    }
+    extractCreateData(model) {
+        return projectCommitPayload(model.getModelName(), model.toJSON(), { dropUndefined: false }, this.runtime);
+    }
+    mapChangesToInput(modelName, changes) {
+        return projectCommitPayload(modelName, changes, { dropUndefined: true }, this.runtime);
+    }
+    extractUpdateData(model) {
+        return projectCommitPayload(model.getModelName(), model.getChanges(), { dropUndefined: true }, this.runtime);
+    }
+    // Derive previous values for changed fields to support accurate rollback.
+    // Model-specific special cases do not belong here; a model that needs to
+    // surface previous state beyond `modifiedProperties` should expose a typed
+    // `getPreviousData()` accessor for this method to call.
+    extractPreviousData(model, updateInput) {
+        // When the update's written keys are known, capture a before-image for
+        // exactly those keys, so the recorded undo inverse reverts them and nothing
+        // else — a full-row inverse would clobber concurrent edits to unrelated
+        // fields. `fallbackToLive: false` makes `Model.capturePreviousValues` omit
+        // any key it cannot resolve, and `buildUndoOps` then drops an un-revertible
+        // inverse rather than inventing one. With no `updateInput` (a full extract)
+        // it falls back to every tracked field. `Model.capturePreviousValues` is the
+        // single before-image source, shared with
+        // `RecordingMutation.snapshotFields`.
+        const keys = updateInput
+            ? Object.keys(updateInput)
+            : [...(model.modifiedProperties instanceof Map ? model.modifiedProperties.keys() : [])];
+        return { id: model.id, ...model.capturePreviousValues(keys, { fallbackToLive: false }) };
+    }
+    /** Returns a snapshot of queue counts and the current configuration. */
+    getStats() {
+        return {
+            pending: this.store.getByStatus('pending').length,
+            executing: this.store.getByStatus('executing').length,
+            completed: this.store.getByStatus('completed').length,
+            failed: this.store.getByStatus('failed').length,
+            optimistic: this.localMutationPort.updates.size,
+            totalTransactions: this.store.getAll().length,
+            batchIndex: this.batchIndex,
+            config: { ...this.config },
+        };
+    }
+    /**
+     * Returns detailed internal state — pending, executing, and awaiting-delta
+     * transactions — to help diagnose delta-confirmation issues.
+     */
+    getDebugInfo() {
+        const awaitingDelta = this.store.getByStatus('awaiting_delta');
+        return {
+            lastSeenSyncId: this.lastSeenSyncId,
+            awaitingDeltaCount: awaitingDelta.length,
+            awaitingDeltaTransactions: awaitingDelta.map((tx) => ({
+                id: tx.id.slice(0, 8),
+                type: tx.type,
+                modelName: tx.modelName,
+                modelId: tx.modelId.slice(0, 8),
+                syncIdNeeded: tx.syncIdNeededForCompletion,
+                createdAt: tx.createdAt,
+                age: Date.now() - tx.createdAt,
+            })),
+            pendingTransactions: this.store.getByStatus('pending').map((tx) => ({
+                id: tx.id.slice(0, 8),
+                type: tx.type,
+                modelName: tx.modelName,
+                modelId: tx.modelId.slice(0, 8),
+            })),
+            executingTransactions: this.store.getByStatus('executing').map((tx) => ({
+                id: tx.id.slice(0, 8),
+                type: tx.type,
+                modelName: tx.modelName,
+                modelId: tx.modelId.slice(0, 8),
+            })),
+        };
+    }
+    /** Merges the given options into the queue's configuration. */
+    setConfig(config) {
+        this.config = { ...this.config, ...config };
+    }
+    /**
+     * Re-emits an incoming sync delta on the `sync:delta` event for the store to
+     * apply. Because rows use stable ids, no id reconciliation is needed here.
+     */
+    handleSyncDelta(delta) {
+        // Row ids are stable, so no reconciliation is needed; re-emit the delta for
+        // the store to apply directly.
+        this.emit('sync:delta', {
+            id: delta.id,
+            modelName: delta.modelName,
+            action: delta.action,
+            data: delta.data,
+        });
+        return true;
+    }
+    /**
+     * Releases the queue's resources: rolls back outstanding optimistic updates,
+     * clears all timers and stored transactions, and removes event listeners.
+     */
+    dispose() {
+        // Cancel all active optimistic updates
+        for (const [, optimistic] of this.localMutationPort.updates) {
+            this.emit('optimistic:rollback', {
+                model: optimistic.model,
+                previousState: optimistic.previousState,
+                transaction: optimistic.transaction,
+                reason: 'dispose',
+            });
+        }
+        // Clear processing
+        if (this.processTimer) {
+            clearTimeout(this.processTimer);
+        }
+        // Clear every armed delta-confirmation timer (one per in-flight tx,
+        // 30–120s each) — a disposed queue must not keep the process alive or
+        // fire confirmation callbacks against the cleared store below.
+        this.deltaConfirmation.dispose();
+        for (const timeout of this.replicationLagTimeouts.values()) {
+            clearTimeout(timeout);
+        }
+        this.replicationLagTimeouts.clear();
+        this.replicationLagErrors.clear();
+        // Clear the offline-grace timer armed by setConnectionState('disconnected').
+        if (this.commitOfflineGraceTimer !== null) {
+            clearTimeout(this.commitOfflineGraceTimer);
+            this.commitOfflineGraceTimer = null;
+        }
+        // Clear store
+        this.store.clear();
+        this.localMutationPort.updates.clear();
+        this.executionQueue = [];
+        this.createdTransactions = [];
+        this.deferredDeletesByCreate.clear();
+        this.recentDeltaCorrelations.clear();
+        this.commitLane = [];
+        this.commitStore.clear();
+        this.commitNotifications.clear();
+        this.commitMissingIds.clear();
+        // Clear event listeners
+        this.removeAllListeners();
+        // Reset state
+        this.isProcessing = false;
+        this.batchIndex = 0;
+    }
+}