@abloatai/humans 0.37.0

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

@@ -0,0 +1,349 @@
+import { AbloError, AbloNotFoundError } from '@abloatai/transaction/errors';
+import { applyWriteOptions, normalizeModelKey, TX_TYPE_TO_MUTATION_OP } from './commitPayload.js';
+export async function processBatch(ctx) {
+    if (ctx.durableReplayBlock)
+        return;
+    const batchStart = typeof performance !== 'undefined' ? performance.now() : Date.now();
+    if (ctx.isProcessing || ctx.executionQueue.length === 0) {
+        return;
+    }
+    ctx.setIsProcessing(true);
+    // Declare batch outside try so it's accessible in finally for backpressure tracking
+    let batch = [];
+    await ctx.runtime.observability.startSpanAsync('sync.batch', 'sync.transaction.batch', async () => {
+        try {
+            // Sort the execution queue by foreign-key priority before selecting a
+            // batch, so a parent row is always committed before its children, even
+            // across batch boundaries.
+            ctx.executionQueue.sort((a, b) => {
+                // Ensure derived fields exist (covers restored/persisted transactions)
+                ctx.ensureDerivedFields(a);
+                ctx.ensureDerivedFields(b);
+                if (a.modelName === b.modelName && a.modelId === b.modelId && a.type !== b.type) {
+                    if (a.type === 'create')
+                        return -1;
+                    if (b.type === 'create')
+                        return 1;
+                }
+                return a.priorityScore - b.priorityScore;
+            });
+            // Take a fresh batch or one complete retry envelope. Retry envelopes
+            // retain both their original membership and operation order.
+            batch = ctx.takeNextExecutionBatch();
+            if (batch.length === 0)
+                return;
+            const commitIdempotencyKey = ctx.ensureCommitEnvelope(batch);
+            // Track executing count for backpressure
+            ctx.setExecutingCount(ctx.executingCount + batch.length);
+            // Mark all as executing
+            for (const tx of batch) {
+                const key = `${tx.modelName}:${tx.modelId}`;
+                if (tx.type === 'update')
+                    ctx.inFlightByModel.add(key);
+                ctx.store.updateStatus(tx.id, 'executing');
+            }
+            // Build every operation for one unified commit (a single round trip).
+            const batchOps = [];
+            for (const tx of batch) {
+                // The per-operation `transactionId` carries the local transaction id
+                // over the wire so the server can stamp it on the resulting sync
+                // delta. The receive path matches it through
+                // {@link UnconfirmedWrites.consumeEcho} to avoid applying the
+                // client's own optimistic change twice. This is separate from the
+                // batch-level idempotency key recorded in `mutation_log`.
+                const op = applyWriteOptions({
+                    type: TX_TYPE_TO_MUTATION_OP[tx.type],
+                    model: tx.modelKey,
+                    id: tx.modelId,
+                    input: tx.type === 'create' || tx.type === 'update' ? tx.data || {} : undefined,
+                    transactionId: tx.id,
+                }, tx);
+                batchOps.push({ tx, op });
+            }
+            // Execute the unified commit for every operation in one round trip.
+            if (batchOps.length > 0) {
+                let dispatchStarted = false;
+                try {
+                    const durableEnvelope = await ctx.sealDurableCommit({
+                        idempotencyKey: commitIdempotencyKey,
+                        origin: 'model_batch',
+                        operations: batchOps.map(({ op }) => op),
+                        sourceMutationIds: ctx.sourceMutationIdsFor(batch),
+                        createdAt: Math.min(...batch.map((transaction) => transaction.createdAt)),
+                        sealedAt: batch[0]?.commitEnvelope?.sealedAt ?? Date.now(),
+                        sequence: batch[0]?.commitEnvelope?.sequence,
+                    });
+                    const operations = durableEnvelope.operations;
+                    // Capture lastSyncId from the server response for threshold-based
+                    // confirmation.
+                    //
+                    // The queue owns request identity. A lost acknowledgement may be
+                    // retried after a backoff or reconnect, so every retry must send
+                    // the exact key assigned before the first transport attempt.
+                    ctx.assertEnvelopeInsideReplayWindow(durableEnvelope);
+                    dispatchStarted = true;
+                    const result = ctx.parseMutationCommitResult(await ctx.dispatchCommitBounded(operations, {
+                        idempotencyKey: commitIdempotencyKey,
+                    }));
+                    await ctx.persistDurableCommitAcceptance(durableEnvelope, result);
+                    const lastSyncId = result.lastSyncId;
+                    const notifications = result.notifications;
+                    const { holdsEntireBatch, heldTargets, notificationsByTarget, } = ctx.classifyReceiptNotifications(batchOps.map(({ op }) => ({ model: op.model, id: op.id })), notifications ?? []);
+                    for (const { tx } of batchOps) {
+                        const txTarget = ctx.receiptTargetKey(tx.modelKey, tx.modelId);
+                        const txNotifs = holdsEntireBatch
+                            ? notifications
+                            : notificationsByTarget.get(txTarget);
+                        if (txNotifs && txNotifs.length > 0) {
+                            ctx.commitNotifications.set(tx.id, txNotifs);
+                        }
+                    }
+                    const missingIds = new Set(result.missingIds ?? []);
+                    const settlingBatchOps = [];
+                    for (const entry of batchOps) {
+                        const { tx } = entry;
+                        if (missingIds.has(tx.modelId)) {
+                            await ctx.handleFailure(tx, new AbloNotFoundError(`${tx.modelName}/${tx.modelId} was not found or is outside this credential's scope.`, [tx.modelId]));
+                            continue;
+                        }
+                        if (holdsEntireBatch ||
+                            heldTargets.has(ctx.receiptTargetKey(tx.modelKey, tx.modelId))) {
+                            await ctx.rollbackOptimistic(tx, 'conflict_server_wins');
+                            ctx.store.updateStatus(tx.id, 'completed');
+                            ctx.emit('transaction:completed', tx);
+                            ctx.emit(`transaction:completed:${tx.id}`, tx);
+                            ctx.optimisticUpdates.delete(tx.id);
+                            continue;
+                        }
+                        settlingBatchOps.push(entry);
+                    }
+                    // A forwarded write has been accepted, but the source database
+                    // remains authoritative. It must not enter any of the confirmed
+                    // paths below: in particular, a queued DELETE with sync id 0 is
+                    // not the hosted-path idempotent-delete shortcut, and a later
+                    // unrelated delta cannot stand in for the source echo.
+                    if (result.status === 'queued') {
+                        // Keep the exact envelope crash-durable while any forwarded
+                        // member is awaiting its WAL echo. If coordination/missing-row
+                        // handling consumed the whole request, there is no echo left
+                        // to await and the durable intent is definitive.
+                        if (settlingBatchOps.length === 0) {
+                            await ctx.removeDurableCommit(commitIdempotencyKey);
+                        }
+                        for (const { tx } of settlingBatchOps) {
+                            tx.requiresCorrelatedDelta = true;
+                            tx.syncIdNeededForCompletion = undefined;
+                            tx.correlationId = result.correlationId;
+                            const echoSyncId = result.correlationId
+                                ? ctx.recentDeltaCorrelations.get(result.correlationId)
+                                : undefined;
+                            if (echoSyncId !== undefined) {
+                                ctx.store.updateStatus(tx.id, 'completed');
+                                ctx.emit('transaction:completed', tx);
+                                ctx.emit(`transaction:completed:${tx.id}`, tx);
+                                ctx.optimisticUpdates.delete(tx.id);
+                                continue;
+                            }
+                            ctx.store.updateStatus(tx.id, 'awaiting_delta');
+                            ctx.scheduleReplicationLagTimeout(tx.id, commitIdempotencyKey, result.correlationId);
+                            ctx.runtime.logger.debug('tx:awaiting_delta', {
+                                txId: tx.id.slice(0, 8),
+                                model: tx.modelName,
+                                reason: 'queued_forward_waiting_for_correlated_echo',
+                            });
+                            ctx.scheduleDeltaConfirmationTimeout(tx, ctx.config.deltaConfirmationTimeout);
+                        }
+                        if (settlingBatchOps.length > 0 &&
+                            settlingBatchOps.every(({ tx }) => tx.status === 'completed')) {
+                            await ctx.removeDurableCommit(commitIdempotencyKey);
+                        }
+                    }
+                    else {
+                        await ctx.removeDurableCommit(commitIdempotencyKey);
+                        ctx.noteAck(lastSyncId);
+                        // A lastSyncId of 0 means the mutation succeeded but the server
+                        // emitted no sync delta; record that anomaly for observability.
+                        if (lastSyncId === 0) {
+                            ctx.runtime.observability.captureCommitZeroSyncId({
+                                operationCount: operations.length,
+                                operations: operations.map((op) => `${op.type}:${op.model}:${op.id?.slice(0, 8) ?? '?'}`),
+                            });
+                        }
+                        // Mark each remaining transaction with the sync-id threshold
+                        // that will confirm it: any delta whose id is at least
+                        // lastSyncId.
+                        for (const { tx } of settlingBatchOps) {
+                            tx.syncIdNeededForCompletion = lastSyncId;
+                            // Safety net: a confirmed zero-sync DELETE is idempotent.
+                            // This shortcut is intentionally unreachable for queued
+                            // forwards, which must wait for their correlated echo.
+                            if (lastSyncId === 0 && tx.type === 'delete') {
+                                ctx.store.updateStatus(tx.id, 'completed');
+                                ctx.emit('transaction:completed', tx);
+                                ctx.emit(`transaction:completed:${tx.id}`, tx);
+                                ctx.optimisticUpdates.delete(tx.id);
+                                ctx.runtime.logger.debug('tx:confirm_delete_zero_syncid', {
+                                    txId: tx.id.slice(0, 8),
+                                    model: tx.modelName,
+                                    reason: 'delete_idempotent_no_delta',
+                                });
+                                continue;
+                            }
+                            // A real watermark is the established hosted-path
+                            // confirmation. A zero watermark on a non-delete stays on
+                            // the anomaly/reconciliation path.
+                            if (lastSyncId > 0) {
+                                ctx.store.updateStatus(tx.id, 'completed');
+                                ctx.emit('transaction:completed', tx);
+                                ctx.emit(`transaction:completed:${tx.id}`, tx);
+                                ctx.optimisticUpdates.delete(tx.id);
+                                ctx.runtime.logger.debug('tx:confirm_ack', {
+                                    txId: tx.id.slice(0, 8),
+                                    model: tx.modelName,
+                                    serverSyncId: lastSyncId,
+                                    lastSeenSyncId: ctx.lastSeenSyncId,
+                                });
+                            }
+                            else {
+                                ctx.store.updateStatus(tx.id, 'awaiting_delta');
+                                ctx.runtime.logger.debug('tx:awaiting_delta', {
+                                    txId: tx.id.slice(0, 8),
+                                    model: tx.modelName,
+                                    neededSyncId: lastSyncId,
+                                    lastSeenSyncId: ctx.lastSeenSyncId,
+                                    reason: 'zero_sync_id_anomaly',
+                                });
+                                ctx.scheduleDeltaConfirmationTimeout(tx, ctx.config.deltaConfirmationTimeout);
+                            }
+                        }
+                    }
+                }
+                catch (error) {
+                    const errorMessage = error.message || '';
+                    if (dispatchStarted && ctx.isDefinitiveRejection(error)) {
+                        await ctx.removeDurableCommit(commitIdempotencyKey);
+                    }
+                    // Surface the raw server rejection for the whole batch so a
+                    // cascaded failure — for example a foreign-key violation that
+                    // rolls back a multi-operation transaction — is attributable to a
+                    // specific cause rather than showing as a generic permanent error
+                    // on each operation.
+                    const abloErr = error instanceof AbloError ? error : undefined;
+                    // SyncWebSocket attaches a `diagnostics` snapshot to its
+                    // "not connected" / "closed while in flight" rejections.
+                    // Surface it here so the warn line attributes the drop to
+                    // a specific cause (handshake reject, heartbeat zombie,
+                    // session expiry, …) instead of just "AbloConnectionError".
+                    const readDiagnostics = (e) => {
+                        let cur = e;
+                        // Walk up to 3 wrap layers (current err → its cause → its
+                        // cause's cause) so diagnostics survive AbloConnectionError
+                        // wrapping in Ablo.commit() and any future wrappers.
+                        for (let i = 0; i < 3 && cur && typeof cur === 'object'; i++) {
+                            if ('diagnostics' in cur && cur.diagnostics) {
+                                return (cur).diagnostics;
+                            }
+                            cur = cur.cause;
+                        }
+                        return undefined;
+                    };
+                    const diagnostics = readDiagnostics(error);
+                    // Mechanic-level breadcrumb. Every batch rejection — transient
+                    // (reconnect retries it) or permanent (`handleFailure` logs the
+                    // authoritative `warn` with the same typed cause) — passes
+                    // through here. Logging it at `warn` made one rejected write
+                    // surface three identical dumps; keep it at `debug`.
+                    ctx.runtime.logger.debug('[MutationQueue] Batch commit rejected', {
+                        batchSize: batchOps.length,
+                        models: batchOps.map(({ op }) => `${op.type}:${op.model}`),
+                        errorType: abloErr?.type ?? error?.name,
+                        errorCode: abloErr?.code,
+                        httpStatus: abloErr?.httpStatus,
+                        requestId: abloErr?.requestId,
+                        message: errorMessage,
+                        diagnostics,
+                    });
+                    // Handle "no rows in result set" gracefully: the row was already
+                    // deleted, so for update and delete operations this is effectively
+                    // success — the intended end state already holds — and the
+                    // transaction is treated as completed.
+                    if (errorMessage.includes('no rows in result set')) {
+                        if (dispatchStarted) {
+                            await ctx.removeDurableCommit(commitIdempotencyKey);
+                        }
+                        ctx.runtime.logger.info('[MutationQueue] Graceful handling: entity already deleted', {
+                            batchSize: batchOps.length,
+                        });
+                        for (const { tx, op } of batchOps) {
+                            if (op.type === 'UPDATE' || op.type === 'DELETE') {
+                                // Row already gone: the intended state holds, mark completed.
+                                ctx.store.updateStatus(tx.id, 'completed');
+                                ctx.emit('transaction:completed', tx);
+                                ctx.runtime.logger.debug('[MutationQueue] Orphaned transaction treated as success', {
+                                    txId: tx.id.slice(0, 12),
+                                    model: tx.modelName,
+                                    type: op.type,
+                                });
+                            }
+                            else {
+                                // CREATE operations on non-existent parent are real failures
+                                await ctx.handleFailure(tx, error);
+                            }
+                        }
+                    }
+                    else {
+                        // Handle other batch failures - mark all as failed
+                        for (const { tx } of batchOps) {
+                            await ctx.handleFailure(tx, error);
+                        }
+                    }
+                }
+            }
+            // Handle post-execution merge for updates
+            for (const tx of batch) {
+                const key = `${tx.modelName}:${tx.modelId}`;
+                if (tx.type === 'update') {
+                    ctx.inFlightByModel.delete(key);
+                    const pending = ctx.pendingMergeByModel.get(key);
+                    if (pending && Object.keys(pending.data).length > 0) {
+                        // Create a single merged follow-up transaction
+                        const followUp = {
+                            id: ctx.generateId(),
+                            type: 'update',
+                            modelName: tx.modelName,
+                            modelId: tx.modelId,
+                            modelKey: tx.modelKey ?? normalizeModelKey(tx.modelName),
+                            data: pending.data,
+                            previousData: undefined,
+                            context: tx.context,
+                            status: 'pending',
+                            createdAt: Date.now(),
+                            attempts: 0,
+                            priority: 'normal',
+                            priorityScore: ctx.computePriorityScore('update', tx.modelName),
+                            sourceMutationIds: pending.sourceMutationIds,
+                        };
+                        ctx.pendingMergeByModel.delete(key);
+                        ctx.store.add(followUp);
+                        ctx.enqueue(followUp);
+                    }
+                }
+            }
+        }
+        finally {
+            ctx.setIsProcessing(false);
+            // Decrement executing count for backpressure tracking
+            ctx.setExecutingCount(ctx.executingCount - batch.length);
+            // Process next batch if needed
+            if (ctx.executionQueue.length > 0 && batch.length > 0) {
+                ctx.scheduleProcessing(true);
+            }
+            const batchEnd = typeof performance !== 'undefined' ? performance.now() : Date.now();
+            ctx.runtime.logger.debug('txn:batch', batchEnd - batchStart, {
+                maxBatchSize: ctx.config.maxBatchSize,
+                remaining: ctx.executionQueue.length,
+                executingCount: ctx.executingCount,
+            });
+        }
+    }, { batchSize: ctx.executionQueue.length + (batch?.length ?? 0) });
+}

package/dist/local/transactions/mutations/coalesceRules.d.ts

@@ -0,0 +1,58 @@
+/**
+ * The queue's rules for coalescing operations that touch the same row, so their
+ * causal order is preserved. {@link MutationQueue} calls into these through a
+ * small store-shaped interface:
+ *
+ *   - Create-then-delete cancellation ({@link takeUnsentCreateForModel}):
+ *     deleting a row whose create never left the client cancels both locally.
+ *   - The create barrier ({@link findCreateBarrierForDelete}) and deferred-delete
+ *     parking ({@link deferDeleteUntilCreateSettles} /
+ *     {@link releaseDeferredDeletesForCreate}): once a create has been sent, a
+ *     delete must wait for it to settle, or the server could receive the delete
+ *     before the create.
+ *   - Update-payload merging ({@link mergeUpdateData}): collapses rapid updates
+ *     to the same row into one wire operation.
+ *
+ * The queue keeps the `enqueue` and `delete` methods that orchestrate optimistic
+ * state and events; these functions hold only the coalescing rules.
+ */
+import type { MutationInput, QueuedMutation } from './commitPayload.js';
+/** The subset of {@link MutationStore} that the coalescing rules read. */
+export interface MutationStoreLike {
+    get(id: string): QueuedMutation | undefined;
+    getByStatus(status: QueuedMutation['status']): QueuedMutation[];
+}
+export declare const entityKey: (modelName: string, modelId: string) => string;
+/**
+ * Finds and removes a create for the given model and id that has never been
+ * sent, searching the staging area, the execution queue, and the store's
+ * pending bucket in that order. It splices the match out of whichever queue
+ * held it, so the caller can cancel it rather than send a create followed by a
+ * delete.
+ */
+export declare function takeUnsentCreateForModel(staged: QueuedMutation[], queued: QueuedMutation[], store: Pick<MutationStoreLike, 'getByStatus'>, modelName: string, modelId: string): QueuedMutation | undefined;
+/**
+ * Returns the most recent in-flight create for the given model and id that a
+ * delete must wait behind, or undefined if there is none. A pending create that
+ * has never been attempted is not a barrier, because it can be cancelled
+ * instead; once a create has been sent, even a retry-pending one is a barrier.
+ */
+export declare function findCreateBarrierForDelete(store: Pick<MutationStoreLike, 'getByStatus'>, modelName: string, modelId: string): QueuedMutation | undefined;
+/**
+ * Parks a delete until the create for the same row settles, keyed by the
+ * create's model and id. {@link releaseDeferredDeletesForCreate} re-enqueues
+ * the parked deletes once that create completes.
+ */
+export declare function deferDeleteUntilCreateSettles(deferredDeletesByCreate: Map<string, QueuedMutation[]>, createTransaction: QueuedMutation, deleteTransaction: QueuedMutation): void;
+/**
+ * Re-enqueues the deletes parked behind a create once that create settles,
+ * skipping any whose status is no longer pending.
+ */
+export declare function releaseDeferredDeletesForCreate(deferredDeletesByCreate: Map<string, QueuedMutation[]>, store: Pick<MutationStoreLike, 'get'>, enqueue: (transaction: QueuedMutation) => void, createTransaction: QueuedMutation): void;
+/**
+ * Merges two update payloads for the same row into one. Later values win, with
+ * one exception: a `metadata` field is deep-merged as an object — parsing it
+ * first when it arrives as a JSON string — rather than replaced, so partial
+ * metadata updates accumulate instead of overwriting each other.
+ */
+export declare function mergeUpdateData(left: MutationInput | undefined, right: MutationInput | undefined, _modelName?: string): MutationInput;

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

@@ -0,0 +1,140 @@
+/**
+ * The queue's rules for coalescing operations that touch the same row, so their
+ * causal order is preserved. {@link MutationQueue} calls into these through a
+ * small store-shaped interface:
+ *
+ *   - Create-then-delete cancellation ({@link takeUnsentCreateForModel}):
+ *     deleting a row whose create never left the client cancels both locally.
+ *   - The create barrier ({@link findCreateBarrierForDelete}) and deferred-delete
+ *     parking ({@link deferDeleteUntilCreateSettles} /
+ *     {@link releaseDeferredDeletesForCreate}): once a create has been sent, a
+ *     delete must wait for it to settle, or the server could receive the delete
+ *     before the create.
+ *   - Update-payload merging ({@link mergeUpdateData}): collapses rapid updates
+ *     to the same row into one wire operation.
+ *
+ * The queue keeps the `enqueue` and `delete` methods that orchestrate optimistic
+ * state and events; these functions hold only the coalescing rules.
+ */
+export const entityKey = (modelName, modelId) => `${modelName}:${modelId}`;
+const isTransactionForModel = (transaction, modelName, modelId) => transaction.modelName === modelName && transaction.modelId === modelId;
+/**
+ * Finds and removes a create for the given model and id that has never been
+ * sent, searching the staging area, the execution queue, and the store's
+ * pending bucket in that order. It splices the match out of whichever queue
+ * held it, so the caller can cancel it rather than send a create followed by a
+ * delete.
+ */
+export function takeUnsentCreateForModel(staged, queued, store, modelName, modelId) {
+    const isUnsentCreate = (tx) => tx.type === 'create' &&
+        tx.status === 'pending' &&
+        tx.attempts === 0 &&
+        isTransactionForModel(tx, modelName, modelId);
+    const stagedIndex = staged.findIndex(isUnsentCreate);
+    if (stagedIndex >= 0) {
+        return staged.splice(stagedIndex, 1)[0];
+    }
+    const queuedIndex = queued.findIndex(isUnsentCreate);
+    if (queuedIndex >= 0) {
+        return queued.splice(queuedIndex, 1)[0];
+    }
+    return store.getByStatus('pending').find(isUnsentCreate);
+}
+/**
+ * Returns the most recent in-flight create for the given model and id that a
+ * delete must wait behind, or undefined if there is none. A pending create that
+ * has never been attempted is not a barrier, because it can be cancelled
+ * instead; once a create has been sent, even a retry-pending one is a barrier.
+ */
+export function findCreateBarrierForDelete(store, modelName, modelId) {
+    const liveCreates = [
+        ...store.getByStatus('pending'),
+        ...store.getByStatus('executing'),
+        ...store.getByStatus('awaiting_delta'),
+    ].filter((tx) => tx.type === 'create' &&
+        isTransactionForModel(tx, modelName, modelId) &&
+        // A never-attempted pending create can be cancelled instead. Once the
+        // create has been sent, even a retry-pending state is a causal barrier:
+        // the server may already have applied it and only the response was lost.
+        (tx.status !== 'pending' || tx.attempts > 0));
+    return liveCreates.sort((a, b) => b.createdAt - a.createdAt)[0];
+}
+/**
+ * Parks a delete until the create for the same row settles, keyed by the
+ * create's model and id. {@link releaseDeferredDeletesForCreate} re-enqueues
+ * the parked deletes once that create completes.
+ */
+export function deferDeleteUntilCreateSettles(deferredDeletesByCreate, createTransaction, deleteTransaction) {
+    const key = entityKey(createTransaction.modelName, createTransaction.modelId);
+    const deferred = deferredDeletesByCreate.get(key) ?? [];
+    deferred.push(deleteTransaction);
+    deferredDeletesByCreate.set(key, deferred);
+}
+/**
+ * Re-enqueues the deletes parked behind a create once that create settles,
+ * skipping any whose status is no longer pending.
+ */
+export function releaseDeferredDeletesForCreate(deferredDeletesByCreate, store, enqueue, createTransaction) {
+    const key = entityKey(createTransaction.modelName, createTransaction.modelId);
+    const deferred = deferredDeletesByCreate.get(key);
+    if (!deferred || deferred.length === 0)
+        return;
+    deferredDeletesByCreate.delete(key);
+    for (const deleteTransaction of deferred) {
+        if (store.get(deleteTransaction.id)?.status !== 'pending')
+            continue;
+        enqueue(deleteTransaction);
+    }
+}
+/**
+ * Merges two update payloads for the same row into one. Later values win, with
+ * one exception: a `metadata` field is deep-merged as an object — parsing it
+ * first when it arrives as a JSON string — rather than replaced, so partial
+ * metadata updates accumulate instead of overwriting each other.
+ */
+export function mergeUpdateData(left, right, _modelName) {
+    const out = { ...(left || {}) };
+    const src = right || {};
+    for (const key of Object.keys(src)) {
+        // Special case: metadata payloads may be JSON strings; merge objects instead of clobbering
+        if (key === 'metadata') {
+            const l = out.metadata;
+            const r = src.metadata;
+            // If both sides undefined/null, continue
+            if (l == null && r == null) {
+                continue;
+            }
+            // Normalize to objects
+            const toObj = (v) => {
+                if (v == null)
+                    return {};
+                if (typeof v === 'string') {
+                    try {
+                        return JSON.parse(v);
+                    }
+                    catch {
+                        return {};
+                    }
+                }
+                if (typeof v === 'object')
+                    return v;
+                return {};
+            };
+            const lobj = toObj(l);
+            const robj = toObj(r);
+            const merged = { ...lobj, ...robj };
+            // Re-stringify to match schema input type
+            try {
+                out.metadata = JSON.stringify(merged);
+            }
+            catch {
+                // Fallback to right-hand side if stringify fails
+                out.metadata = typeof r === 'string' ? r : JSON.stringify(robj || {});
+            }
+            continue;
+        }
+        // Default: shallow overwrite with right-hand value
+        out[key] = src[key];
+    }
+    return out;
+}

package/dist/local/transactions/mutations/commitApi.d.ts

@@ -0,0 +1,19 @@
+import type { ReadDependency, TrackDependency } from '@abloatai/transaction/coordination/schema';
+import type { DurableCommitEnvelope } from '@abloatai/transaction/transactions/settlement/commitEnvelope';
+import type { CommitTransaction } from './commitLane.js';
+import type { SealDurableCommitInput } from './commitTransport.js';
+export interface CommitApiContext {
+    readonly assertDurableReplayOpen: () => void;
+    readonly commitStore: Map<string, CommitTransaction>;
+    readonly commitLane: CommitTransaction[];
+    readonly replicationLagErrors: Map<string, Error>;
+    readonly clearReplicationLagState: (transactionId: string) => void;
+    readonly nextCommitSequence: () => number;
+    readonly sealDurableCommit: (input: SealDurableCommitInput) => Promise<DurableCommitEnvelope>;
+    readonly processCommitLane: () => Promise<void>;
+    readonly emitCommitLifecycle: (event: string, payload: object) => void;
+}
+export declare function enqueueCommit(ctx: CommitApiContext, clientTxId: string, operations: CommitTransaction['operations'], options?: {
+    reads?: ReadDependency[] | null;
+    track?: TrackDependency[] | null;
+}): Promise<void>;

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

@@ -0,0 +1,74 @@
+import { AbloIdempotencyError } from '@abloatai/transaction/errors';
+import { stableStringify } from '@abloatai/transaction/utils/json';
+export async function enqueueCommit(ctx, clientTxId, operations, options = {}) {
+    ctx.assertDurableReplayOpen();
+    const existing = ctx.commitStore.get(clientTxId);
+    if (existing) {
+        await existing.sealPromise;
+        const existingIntent = stableStringify({
+            operations: existing.operations,
+            reads: existing.reads ?? null,
+            track: existing.track ?? null,
+        });
+        const incomingIntent = stableStringify({
+            operations,
+            reads: options.reads ?? null,
+            track: options.track ?? null,
+        });
+        if (existingIntent !== incomingIntent) {
+            throw new AbloIdempotencyError('Idempotency key reused with a different atomic commit request', { code: 'idempotency_conflict' });
+        }
+        if (existing.status === 'awaiting_delta' && ctx.replicationLagErrors.has(existing.id)) {
+            ctx.clearReplicationLagState(existing.id);
+            existing.status = 'pending';
+            ctx.commitLane.push(existing);
+        }
+        if (existing.status === 'pending')
+            void ctx.processCommitLane();
+        return;
+    }
+    ctx.emitCommitLifecycle('commit:staging', { clientTxId, operations });
+    const now = Date.now();
+    const tx = {
+        id: clientTxId,
+        kind: 'commit',
+        operations: [...operations],
+        ...(options.reads ? { reads: options.reads } : {}),
+        ...(options.track ? { track: options.track } : {}),
+        status: 'pending',
+        createdAt: now,
+        attempts: 0,
+        sealedAt: now,
+        sequence: ctx.nextCommitSequence(),
+    };
+    ctx.commitStore.set(clientTxId, tx);
+    tx.sealPromise = ctx.sealDurableCommit({
+        idempotencyKey: tx.id,
+        origin: 'atomic_commit',
+        operations: tx.operations,
+        commitOptions: {
+            ...(tx.reads ? { reads: tx.reads } : {}),
+            ...(tx.track ? { track: tx.track } : {}),
+        },
+        createdAt: tx.createdAt,
+        sealedAt: tx.sealedAt,
+        sequence: tx.sequence,
+    }).then((envelope) => {
+        tx.durableEnvelope = envelope;
+        tx.operations = envelope.operations.map((operation) => ({ ...operation }));
+    });
+    try {
+        await tx.sealPromise;
+    }
+    catch (error) {
+        ctx.commitStore.delete(clientTxId);
+        ctx.emitCommitLifecycle('commit:seal_failed', { clientTxId });
+        throw error;
+    }
+    finally {
+        tx.sealPromise = undefined;
+    }
+    ctx.commitLane.push(tx);
+    ctx.emitCommitLifecycle('commit:created', { clientTxId, operations: tx.operations });
+    void ctx.processCommitLane();
+}