@abloatai/humans 0.37.0

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

@@ -0,0 +1,144 @@
+export async function remove(ctx, model, context, writeOptions, sourceMutationId) {
+    ctx.assertDurableReplayOpen();
+    const modelName = model.getModelName();
+    if (modelName === 'Activity') {
+        ctx.logger.debug('MutationQueue.delete() skipping Activity deletion - permanent audit records', { modelId: model.id });
+        const transaction = {
+            id: ctx.generateId(), type: 'delete', modelName, modelId: model.id,
+            modelKey: ctx.normalizeModelKey(modelName), priorityScore: ctx.computePriorityScore('delete', modelName),
+            previousData: model.toJSON(), context, status: 'completed', createdAt: Date.now(), attempts: 0,
+            priority: 'high', writeOptions, localOnly: true, confirmation: Promise.resolve(),
+            ...(sourceMutationId ? { sourceMutationIds: [sourceMutationId] } : {}),
+        };
+        if (ctx.persistenceReady)
+            transaction.sourceMutationIds ??= [transaction.id];
+        if (ctx.enableOptimistic)
+            ctx.applyOptimisticDelete(model, transaction);
+        ctx.emit('transaction:created', transaction);
+        ctx.emit('transaction:completed', transaction);
+        return transaction;
+    }
+    const unsentCreate = ctx.takeUnsentCreateForModel(modelName, model.id);
+    if (unsentCreate) {
+        await ctx.cancelUnsentCreateForDelete(unsentCreate);
+        return ctx.completeLocalDelete(model, context, writeOptions, [
+            ...(unsentCreate.sourceMutationIds ?? []),
+            ...(sourceMutationId ? [sourceMutationId] : []),
+        ]);
+    }
+    const transaction = {
+        id: ctx.generateId(), type: 'delete', modelName, modelId: model.id,
+        modelKey: ctx.normalizeModelKey(modelName), priorityScore: ctx.computePriorityScore('delete', modelName),
+        previousData: model.toJSON(), context, status: 'pending', createdAt: Date.now(), attempts: 0,
+        priority: 'high', writeOptions,
+        ...(sourceMutationId ? { sourceMutationIds: [sourceMutationId] } : {}),
+    };
+    if (ctx.persistenceReady)
+        transaction.sourceMutationIds ??= [transaction.id];
+    ctx.attachConfirmation(transaction);
+    ctx.add(transaction);
+    const canceledUpdates = ctx.cancelTransactionsForModel(model.id, 'update');
+    const key = `${modelName}:${model.id}`;
+    const pendingMerge = ctx.pendingMergeByModel.get(key);
+    transaction.sourceMutationIds = [...new Set([
+            ...(transaction.sourceMutationIds ?? []),
+            ...canceledUpdates.flatMap((candidate) => candidate.commitEnvelope ? [] : (candidate.sourceMutationIds ?? [])),
+            ...(pendingMerge?.sourceMutationIds ?? []),
+        ])];
+    ctx.pendingMergeByModel.delete(key);
+    ctx.inFlightByModel.delete(key);
+    if (ctx.enableOptimistic)
+        ctx.applyOptimisticDelete(model, transaction);
+    await ctx.persistQueuedTransaction(transaction, model.toJSON());
+    const createBarrier = ctx.findCreateBarrierForDelete(modelName, model.id);
+    if (createBarrier)
+        ctx.deferDeleteUntilCreateSettles(createBarrier, transaction);
+    else
+        ctx.stageTransaction(transaction);
+    ctx.emit('transaction:created', transaction);
+    return transaction;
+}
+function stage(ctx, transaction, model) {
+    return ctx.persistenceReady
+        ? ctx.persistAndStage(transaction, model.toJSON())
+        : ctx.stageTransaction(transaction);
+}
+export function create(ctx, model, context, writeOptions, sourceMutationId) {
+    ctx.assertDurableReplayOpen();
+    const modelName = model.getModelName();
+    const transaction = {
+        id: ctx.generateId(), type: 'create', modelName, modelId: model.id,
+        modelKey: ctx.normalizeModelKey(modelName),
+        priorityScore: ctx.computePriorityScore('create', modelName),
+        data: ctx.extractCreateData(model), previousData: null, context,
+        status: 'pending', createdAt: Date.now(), attempts: 0, priority: 'normal', writeOptions,
+        ...(sourceMutationId ? { sourceMutationIds: [sourceMutationId] } : {}),
+    };
+    if (ctx.persistenceReady)
+        transaction.sourceMutationIds ??= [transaction.id];
+    ctx.attachConfirmation(transaction);
+    ctx.add(transaction);
+    if (ctx.enableOptimistic)
+        ctx.applyOptimisticCreate(model, transaction);
+    const staged = stage(ctx, transaction, model);
+    if (staged)
+        return staged.then(() => { ctx.emit('transaction:created', transaction); return transaction; });
+    ctx.emit('transaction:created', transaction);
+    return transaction;
+}
+export function update(ctx, model, context, precomputedChanges, writeOptions, sourceMutationId) {
+    ctx.assertDurableReplayOpen();
+    const modelName = model.getModelName();
+    const input = precomputedChanges
+        ? ctx.mapChangesToInput(modelName, precomputedChanges)
+        : ctx.extractUpdateData(model);
+    const previousData = ctx.extractPreviousData(model, input);
+    model.consumeModifiedFields(Object.keys(input));
+    const transaction = {
+        id: ctx.generateId(), type: 'update', modelName, modelId: model.id,
+        modelKey: ctx.normalizeModelKey(modelName),
+        priorityScore: ctx.computePriorityScore('update', modelName),
+        data: input, previousData, context, status: 'pending', createdAt: Date.now(), attempts: 0,
+        priority: ctx.isReorderPayload(input) ? 'high' : 'normal', writeOptions,
+        ...(sourceMutationId ? { sourceMutationIds: [sourceMutationId] } : {}),
+    };
+    if (ctx.persistenceReady)
+        transaction.sourceMutationIds ??= [transaction.id];
+    ctx.attachConfirmation(transaction);
+    ctx.add(transaction);
+    if (ctx.enableOptimistic)
+        ctx.applyOptimisticUpdate(model, transaction);
+    const staged = stage(ctx, transaction, model);
+    if (staged)
+        return staged.then(() => { ctx.emit('transaction:created', transaction); return transaction; });
+    ctx.emit('transaction:created', transaction);
+    return transaction;
+}
+export function archive(ctx, model, context, writeOptions, sourceMutationId) {
+    return simpleStatusMutation(ctx, 'archive', model, context, writeOptions, sourceMutationId);
+}
+export function unarchive(ctx, model, context) {
+    return simpleStatusMutation(ctx, 'unarchive', model, context);
+}
+function simpleStatusMutation(ctx, type, model, context, writeOptions, sourceMutationId) {
+    ctx.assertDurableReplayOpen();
+    const modelName = model.getModelName();
+    const transaction = {
+        id: ctx.generateId(), type, modelName, modelId: model.id,
+        modelKey: ctx.normalizeModelKey(modelName),
+        priorityScore: ctx.computePriorityScore(type, modelName),
+        previousData: model.toJSON(), context, status: 'pending', createdAt: Date.now(), attempts: 0,
+        priority: 'normal',
+        ...(writeOptions ? { writeOptions } : {}),
+        ...(sourceMutationId ? { sourceMutationIds: [sourceMutationId] } : {}),
+    };
+    if (ctx.persistenceReady)
+        transaction.sourceMutationIds ??= [transaction.id];
+    ctx.attachConfirmation(transaction);
+    ctx.add(transaction);
+    const staged = stage(ctx, transaction, model);
+    if (staged)
+        return staged.then(() => { ctx.emit('transaction:created', transaction); return transaction; });
+    ctx.emit('transaction:created', transaction);
+    return transaction;
+}

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

@@ -0,0 +1,25 @@
+import type { RuntimeContext } from '../../RuntimeContext.js';
+import type { MutationPersistencePort } from '../../mutationPersistence.js';
+import type { MutationQueueConfig } from './MutationQueue.js';
+import type { CommitOutboxScope } from '@abloatai/transaction/transactions/settlement/commitEnvelope';
+import type { QueuedMutation } from './commitPayload.js';
+import { MutationStore } from './MutationStore.js';
+import { deserializePersistedTransaction } from './replayValidation.js';
+export interface MutationPersistenceContext {
+    readonly runtime: RuntimeContext;
+    readonly persistence: MutationPersistencePort | null;
+    readonly commitOutboxScope: CommitOutboxScope | null;
+    readonly config: Pick<MutationQueueConfig, 'enablePersistence'>;
+    readonly store: MutationStore;
+    readonly enqueue: (transaction: QueuedMutation) => void;
+    readonly computePriorityScore: (type: QueuedMutation['type'], modelName: string) => number;
+    readonly deserializeTransaction: (data: Parameters<typeof deserializePersistedTransaction>[0]) => QueuedMutation | null;
+}
+export declare function persistQueuedTransaction(ctx: MutationPersistenceContext, transaction: QueuedMutation, modelData?: Record<string, unknown>): Promise<void>;
+export declare function removePersistedTransaction(ctx: MutationPersistenceContext, transactionId: string): void;
+export declare function settlePersistedFailure(ctx: MutationPersistenceContext, transaction: {
+    id?: string;
+    sourceMutationIds?: string[];
+}): void;
+export declare function deserializeLegacyPendingMutation(ctx: MutationPersistenceContext, row: object, fallbackMutationId?: string): QueuedMutation | null;
+export declare function loadPersistedTransactions(ctx: MutationPersistenceContext, persistence: MutationPersistencePort, sealedMutationIds?: ReadonlySet<string>): Promise<void>;

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

@@ -0,0 +1,188 @@
+import { MutationStore } from './MutationStore.js';
+import { normalizeModelKey } from './commitPayload.js';
+import { deserializePersistedTransaction, legacyPendingMutationRecordSchema, pendingMutationRecordId, pendingMutationRecordSchema, persistedMutationSchema, } from './replayValidation.js';
+export async function persistQueuedTransaction(ctx, transaction, modelData) {
+    if (!ctx.persistence)
+        return;
+    const mutationId = transaction.sourceMutationIds?.[0] ?? transaction.id;
+    if (modelData && ctx.commitOutboxScope) {
+        await ctx.persistence.saveTransaction({
+            id: pendingMutationRecordId(mutationId),
+            type: 'pending_mutation',
+            storageVersion: 2,
+            mutation: {
+                mutationId,
+                type: transaction.type,
+                modelData,
+                modelName: transaction.modelName,
+                timestamp: new Date(transaction.createdAt).toISOString(),
+                ...(transaction.type === 'update' && transaction.data
+                    ? { capturedChanges: transaction.data }
+                    : {}),
+                ...(transaction.writeOptions !== undefined
+                    ? { writeOptions: transaction.writeOptions }
+                    : {}),
+            },
+            scope: ctx.commitOutboxScope,
+            timestamp: transaction.createdAt,
+        });
+        return;
+    }
+    await ctx.persistence.saveTransaction({
+        id: transaction.id,
+        type: transaction.type,
+        modelName: transaction.modelName,
+        modelId: transaction.modelId,
+        modelKey: transaction.modelKey,
+        ...(transaction.data !== undefined ? { data: transaction.data } : {}),
+        ...(transaction.previousData !== undefined ? { previousData: transaction.previousData } : {}),
+        context: transaction.context,
+        createdAt: transaction.createdAt,
+        ...(transaction.writeOptions !== undefined ? { writeOptions: transaction.writeOptions } : {}),
+        ...(transaction.sourceMutationIds !== undefined
+            ? { sourceMutationIds: transaction.sourceMutationIds }
+            : {}),
+    });
+}
+export function removePersistedTransaction(ctx, transactionId) {
+    const ids = [transactionId, pendingMutationRecordId(transactionId), ...(ctx.store.get(transactionId)?.sourceMutationIds ?? []).map(pendingMutationRecordId)];
+    for (const id of ids) {
+        void ctx.persistence?.removeTransaction(id).catch(() => undefined);
+    }
+}
+export function settlePersistedFailure(ctx, transaction) {
+    const sourceIds = new Set(transaction.sourceMutationIds ?? []);
+    const queued = transaction.id
+        ? ctx.store.get(transaction.id)
+        : undefined;
+    const match = queued ?? ctx.store.getAll().find((candidate) => candidate.id === transaction.id ||
+        sourceIds.has(candidate.id) ||
+        (candidate.sourceMutationIds ?? []).some((id) => sourceIds.has(id)));
+    if (match) {
+        ctx.store.updateStatus(match.id, 'failed');
+        removePersistedTransaction(ctx, match.id);
+    }
+    for (const sourceId of sourceIds)
+        removePersistedTransaction(ctx, sourceId);
+}
+export function deserializeLegacyPendingMutation(ctx, row, fallbackMutationId) {
+    const rowType = row.type;
+    const parsed = persistedMutationSchema.safeParse(rowType === 'pending_mutation'
+        ? (pendingMutationRecordSchema.safeParse(row).success
+            ? pendingMutationRecordSchema.parse(row).mutation
+            : legacyPendingMutationRecordSchema.safeParse(row).success
+                ? legacyPendingMutationRecordSchema.parse(row).mutation
+                : null)
+        : row);
+    if (!parsed.success)
+        return null;
+    const mutation = parsed.data;
+    const writtenAt = Date.parse(mutation.timestamp);
+    if (!Number.isFinite(writtenAt) || Date.now() - writtenAt >= 23 * 60 * 60 * 1000) {
+        return null;
+    }
+    const mutationId = mutation.mutationId ?? fallbackMutationId;
+    const modelId = mutation.modelData.id;
+    if (!mutationId || typeof modelId !== 'string')
+        return null;
+    const scope = ctx.commitOutboxScope;
+    if (!scope)
+        return null;
+    const type = mutation.type;
+    return {
+        id: mutationId,
+        type,
+        modelName: mutation.modelName,
+        modelId,
+        modelKey: normalizeModelKey(mutation.modelName),
+        ...(type === 'create'
+            ? { data: mutation.modelData }
+            : type === 'update'
+                ? { data: mutation.capturedChanges ?? mutation.modelData }
+                : {}),
+        ...(type === 'delete' || type === 'archive'
+            ? { previousData: mutation.modelData }
+            : { previousData: null }),
+        context: {
+            userId: scope.participantId,
+            organizationId: scope.organizationId,
+        },
+        status: 'pending',
+        createdAt: Date.parse(mutation.timestamp) || Date.now(),
+        attempts: 0,
+        priority: 'normal',
+        priorityScore: ctx.computePriorityScore(type, mutation.modelName),
+        ...(mutation.writeOptions !== undefined ? { writeOptions: mutation.writeOptions } : {}),
+        sourceMutationIds: [mutationId],
+    };
+}
+export async function loadPersistedTransactions(ctx, persistence, sealedMutationIds = new Set()) {
+    if (!ctx.config.enablePersistence)
+        return;
+    try {
+        const persisted = await persistence.getPersistedTransactions();
+        for (const data of persisted) {
+            if (data.type === 'pending_mutation') {
+                const legacy = deserializeLegacyPendingMutation(ctx, data);
+                if (legacy) {
+                    const v1 = legacyPendingMutationRecordSchema.safeParse(data);
+                    if (v1.success && ctx.commitOutboxScope) {
+                        await persistence.saveTransaction({
+                            ...data,
+                            storageVersion: 2,
+                            scope: ctx.commitOutboxScope,
+                        });
+                    }
+                    legacy.id = String(data.id);
+                    ctx.store.add(legacy);
+                    ctx.enqueue(legacy);
+                }
+                else {
+                    ctx.runtime.logger.debug('[SyncClient] Dropping malformed persisted mutation', {
+                        rowId: data.id,
+                    });
+                }
+                continue;
+            }
+            if (data.id === 'mutation-queue' && Array.isArray(data.mutations)) {
+                if (data.mutations.length === 0)
+                    continue;
+                let migrated = true;
+                for (const [index, mutation] of data.mutations.entries()) {
+                    if (typeof mutation !== 'object' || mutation === null) {
+                        migrated = false;
+                        continue;
+                    }
+                    const transaction = deserializeLegacyPendingMutation(ctx, mutation, `legacy_mutation_${index}`);
+                    if (!transaction) {
+                        migrated = false;
+                        ctx.runtime.logger.debug('[SyncClient] Dropping malformed persisted mutation', {
+                            rowId: `mutation-queue:${index}`,
+                        });
+                        continue;
+                    }
+                    await persistQueuedTransaction(ctx, transaction);
+                    ctx.store.add(transaction);
+                    ctx.enqueue(transaction);
+                }
+                if (migrated)
+                    await persistence.removeTransaction(data.id);
+                continue;
+            }
+            const transaction = ctx.deserializeTransaction(data);
+            if (!transaction)
+                continue;
+            if ((transaction.sourceMutationIds ?? []).some((id) => sealedMutationIds.has(id))) {
+                continue;
+            }
+            ctx.store.add(transaction);
+            ctx.enqueue(transaction);
+        }
+    }
+    catch (error) {
+        ctx.runtime.observability.captureMutationFailure({
+            context: 'load-persisted-transactions',
+            error: error instanceof Error ? error : String(error),
+        });
+    }
+}

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

@@ -0,0 +1,33 @@
+import type { RuntimeContext } from '../../RuntimeContext.js';
+import type { QueuedMutation } from './commitPayload.js';
+import type { MutationStore } from './MutationStore.js';
+import type { OptimisticUpdateEntry } from './localMutation.js';
+import type { MutationCommitResult } from '@abloatai/transaction/wire/commit';
+import type { DurableCommitEnvelope } from '@abloatai/transaction/transactions/settlement/commitEnvelope';
+export interface PendingDrainContext {
+    readonly runtime: RuntimeContext;
+    readonly config: {
+        deltaConfirmationTimeout: number;
+    };
+    readonly store: MutationStore;
+    executionQueue: QueuedMutation[];
+    readonly optimisticUpdates: Map<string, OptimisticUpdateEntry>;
+    readonly assertDurableReplayOpen: () => void;
+    readonly processCommitLane: () => Promise<void>;
+    readonly takePendingDrainBatch: (pending: QueuedMutation[]) => QueuedMutation[];
+    readonly ensureCommitEnvelope: (batch: QueuedMutation[]) => string;
+    readonly ensureDerivedFields: (transaction: QueuedMutation) => void;
+    readonly sourceMutationIdsFor: (batch: readonly QueuedMutation[]) => string[];
+    readonly sealDurableCommit: (input: Parameters<typeof import('./commitTransport.js').sealDurableCommit>[1]) => Promise<DurableCommitEnvelope>;
+    readonly assertEnvelopeInsideReplayWindow: (envelope: DurableCommitEnvelope) => void;
+    readonly parseMutationCommitResult: (value: Awaited<ReturnType<import('../../interfaces/index.js').MutationExecutor['commit']>>) => MutationCommitResult;
+    readonly dispatchCommitBounded: (...args: Parameters<import('../../interfaces/index.js').MutationExecutor['commit']>) => ReturnType<import('../../interfaces/index.js').MutationExecutor['commit']>;
+    readonly persistDurableCommitAcceptance: (envelope: DurableCommitEnvelope, result: MutationCommitResult) => Promise<DurableCommitEnvelope>;
+    readonly removeDurableCommit: (idempotencyKey: string) => Promise<void>;
+    readonly scheduleReplicationLagTimeout: (transactionId: string, clientTxId?: string, correlationId?: string) => void;
+    readonly scheduleDeltaConfirmationTimeout: (transaction: QueuedMutation, timeoutMs: number) => void;
+    readonly enqueue: (transaction: QueuedMutation) => void;
+    readonly recentDeltaCorrelations: Map<string, number>;
+    readonly emit: (event: string, payload: object) => boolean;
+}
+export declare function drainPendingSettlements(ctx: PendingDrainContext): Promise<void>;

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

@@ -0,0 +1,112 @@
+import { applyWriteOptions, TX_TYPE_TO_MUTATION_OP } from './commitPayload.js';
+export async function drainPendingSettlements(ctx) {
+    ctx.assertDurableReplayOpen();
+    // Kick the commit lane too: atomic envelopes from `commits.create()` may
+    // have been left at the head of the lane while the connection was down.
+    // Fire-and-forget; processCommitLane serializes itself.
+    void ctx.processCommitLane();
+    // Collect pending transactions in created order
+    const pending = ctx.store.getByStatus('pending').sort((a, b) => a.createdAt - b.createdAt);
+    if (pending.length === 0)
+        return;
+    const pendingIds = new Set(pending.map((tx) => tx.id));
+    // These rows may already be waiting behind the normal batch timer. The
+    // reconnect fast path takes ownership of them for this attempt so the same
+    // transaction cannot dispatch concurrently through both paths.
+    ctx.executionQueue = ctx.executionQueue.filter((tx) => !pendingIds.has(tx.id));
+    const remaining = [...pending];
+    while (remaining.length > 0) {
+        const batch = ctx.takePendingDrainBatch(remaining);
+        if (batch.length === 0)
+            break;
+        const batchIds = new Set(batch.map((tx) => tx.id));
+        const nextRemaining = remaining.filter((tx) => !batchIds.has(tx.id));
+        try {
+            const idempotencyKey = ctx.ensureCommitEnvelope(batch);
+            const projectedOperations = batch.map((tx) => {
+                ctx.ensureDerivedFields(tx);
+                return 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);
+            });
+            const durableEnvelope = await ctx.sealDurableCommit({
+                idempotencyKey,
+                origin: 'model_batch',
+                operations: projectedOperations,
+                sourceMutationIds: ctx.sourceMutationIdsFor(batch),
+                createdAt: Math.min(...batch.map((transaction) => transaction.createdAt)),
+                sealedAt: batch[0]?.commitEnvelope?.sealedAt ?? Date.now(),
+                sequence: batch[0]?.commitEnvelope?.sequence,
+            });
+            ctx.assertEnvelopeInsideReplayWindow(durableEnvelope);
+            const result = ctx.parseMutationCommitResult(await ctx.dispatchCommitBounded(durableEnvelope.operations, {
+                idempotencyKey,
+            }));
+            await ctx.persistDurableCommitAcceptance(durableEnvelope, result);
+            if (result.status === 'queued') {
+                // Reconnect flushes use the same accepted-vs-confirmed contract as
+                // the normal lane. A queued source receipt retains the envelope and
+                // waits for exact correlation; it is never promoted by the reconnect
+                // shortcut itself.
+                for (const tx of batch) {
+                    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, idempotencyKey, result.correlationId);
+                    ctx.scheduleDeltaConfirmationTimeout(tx, ctx.config.deltaConfirmationTimeout);
+                }
+                if (batch.every((tx) => tx.status === 'completed')) {
+                    await ctx.removeDurableCommit(idempotencyKey);
+                }
+            }
+            else {
+                await ctx.removeDurableCommit(idempotencyKey);
+                // Mark this request envelope as completed before moving to the next.
+                for (const tx of batch) {
+                    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('txn:commit', 0, {
+                count: batch.length,
+                lastSyncId: result.lastSyncId,
+            });
+            remaining.splice(0, remaining.length, ...nextRemaining);
+        }
+        catch (err) {
+            // If one request fails, hand it and every later request back to the
+            // normal lane. Their envelopes stay attached for safe retry.
+            const networkUnavailable = !ctx.runtime.onlineStatus.isOnline();
+            const isNetworkError = err instanceof Error &&
+                (err.message.includes('Failed to fetch') ||
+                    err.message.includes('Network request failed') ||
+                    err.message.includes('NetworkError'));
+            if (!networkUnavailable || !isNetworkError) {
+                ctx.runtime.observability.breadcrumb('Batch flush fallback failed', 'sync.transaction', 'warning', {
+                    error: err instanceof Error ? err.message : String(err),
+                });
+            }
+            for (const tx of [...batch, ...nextRemaining]) {
+                ctx.enqueue(tx);
+            }
+            return;
+        }
+    }
+}

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

@@ -0,0 +1,14 @@
+export interface ProcessingSchedulerContext {
+    readonly processScheduled: boolean;
+    readonly setProcessScheduled: (value: boolean) => void;
+    readonly processTimer: ReturnType<typeof setTimeout> | undefined;
+    readonly setProcessTimer: (timer: ReturnType<typeof setTimeout> | undefined) => void;
+    readonly executingCount: number;
+    readonly maxExecutingTransactions: number;
+    readonly batchDelay: number;
+    readonly processBatch: () => void;
+    readonly logger: {
+        debug: (message: string, fields?: Record<string, number>) => void;
+    };
+}
+export declare function scheduleProcessing(ctx: ProcessingSchedulerContext, immediate?: boolean): void;

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

@@ -0,0 +1,24 @@
+export function scheduleProcessing(ctx, immediate = false) {
+    if (ctx.processScheduled)
+        return;
+    if (ctx.executingCount >= ctx.maxExecutingTransactions) {
+        ctx.logger.debug('[MutationQueue] Backpressure: delaying batch, too many executing', {
+            executingCount: ctx.executingCount, max: ctx.maxExecutingTransactions,
+        });
+        return;
+    }
+    ctx.setProcessScheduled(true);
+    const run = () => {
+        ctx.setProcessScheduled(false);
+        ctx.processBatch();
+    };
+    if (immediate || ctx.batchDelay <= 0) {
+        (typeof queueMicrotask === 'function' ? queueMicrotask : (callback) => Promise.resolve().then(callback))(run);
+        return;
+    }
+    const timer = setTimeout(() => {
+        ctx.setProcessTimer(undefined);
+        run();
+    }, Math.max(0, ctx.batchDelay));
+    ctx.setProcessTimer(timer);
+}

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

@@ -0,0 +1,13 @@
+import type { QueuedMutation } from './commitPayload.js';
+export interface QueueCoalescingContext {
+    readonly executionQueue: QueuedMutation[];
+    readonly inFlightByModel: Set<string>;
+    readonly pendingMergeByModel: Map<string, {
+        data: QueuedMutation['data'];
+        sourceMutationIds: string[];
+    }>;
+    readonly ensureDerivedFields: (transaction: QueuedMutation) => void;
+    readonly scheduleProcessing: (immediate: boolean) => void;
+    readonly storeRemove: (transactionId: string) => void;
+}
+export declare function enqueueTransaction(ctx: QueueCoalescingContext, transaction: QueuedMutation): void;

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

@@ -0,0 +1,35 @@
+import { mergeUpdateData } from './coalesceRules.js';
+import { hasCommitCoalescingBarrier } from './commitPayload.js';
+export function enqueueTransaction(ctx, transaction) {
+    ctx.ensureDerivedFields(transaction);
+    const modelKey = `${transaction.modelName}:${transaction.modelId}`;
+    if (transaction.type === 'update' && transaction.attempts === 0 && !transaction.commitEnvelope) {
+        const preserveWatermark = hasCommitCoalescingBarrier(transaction.writeOptions);
+        if (!preserveWatermark && ctx.inFlightByModel.has(modelKey)) {
+            const previous = ctx.pendingMergeByModel.get(modelKey);
+            const merged = mergeUpdateData(previous?.data ?? {}, transaction.data || {}, transaction.modelName);
+            ctx.pendingMergeByModel.set(modelKey, {
+                data: merged,
+                sourceMutationIds: [...new Set([...(previous?.sourceMutationIds ?? []), ...(transaction.sourceMutationIds ?? [])])],
+            });
+            ctx.storeRemove(transaction.id);
+            return;
+        }
+        const pendingInQueue = ctx.executionQueue.find((candidate) => candidate.id !== transaction.id && candidate.type === 'update' &&
+            candidate.modelId === transaction.modelId && candidate.modelName === transaction.modelName &&
+            !hasCommitCoalescingBarrier(candidate.writeOptions));
+        if (!preserveWatermark && pendingInQueue) {
+            pendingInQueue.data = mergeUpdateData(pendingInQueue.data || {}, transaction.data || {}, transaction.modelName);
+            pendingInQueue.sourceMutationIds = [...new Set([
+                    ...(pendingInQueue.sourceMutationIds ?? []), ...(transaction.sourceMutationIds ?? []),
+                ])];
+            ctx.storeRemove(transaction.id);
+            return;
+        }
+    }
+    if (transaction.priority === 'high')
+        ctx.executionQueue.unshift(transaction);
+    else
+        ctx.executionQueue.push(transaction);
+    ctx.scheduleProcessing(transaction.priority === 'high');
+}