@abloatai/humans 0.37.0

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

@@ -0,0 +1,152 @@
+/**
+ * The vocabulary a local transaction uses on the wire. This module defines the
+ * {@link QueuedMutation} record and the helpers that turn a transaction into a
+ * wire-safe commit operation: schema-field projection
+ * ({@link projectCommitPayload}), write-option projection
+ * ({@link applyWriteOptions}), foreign-key-aware priority scoring
+ * ({@link computePriorityScore}), and the structural checks used to classify
+ * transport errors. Nothing here holds queue state or timers, so the batched
+ * queue path and the HTTP commit path share the same projection.
+ */
+import { globalRuntime } from '../../context.js';
+import { MutationOperationType } from '@abloatai/transaction/types';
+import { snapshotJsonValue } from '@abloatai/transaction/utils/json';
+/**
+ * Framework-internal keys added by `Model.toJSON()` that must never
+ * reach the wire. The server treats each top-level key as a target
+ * column, so shipping these would blow up the INSERT/UPDATE.
+ */
+const FRAMEWORK_KEYS = new Set(['__class', '__typename', 'clientId', 'syncStatus']);
+/**
+ * Projects a model's serialized data onto the fields declared in its schema and
+ * returns a wire-safe commit payload. It does two things:
+ *
+ *   1. Drops framework-internal keys (`__class`, `__typename`, `clientId`,
+ *      `syncStatus`) and anything not declared on the model's schema.
+ *   2. Takes a fresh plain JSON snapshot of the projected values. JSON-typed
+ *      fields stay objects rather than pre-serialized strings, while reactive
+ *      proxies cannot leak into persistence or the wire payload.
+ *
+ * For updates (`dropUndefined: true`), `undefined` values are also removed so
+ * they are not written as `SET column = NULL` on the server.
+ *
+ * Field metadata comes from the model registry, populated when the schema is
+ * registered at initialization. If a model has no registered field metadata —
+ * for example a manually registered model — projection snapshots all serialized
+ * data apart from the framework keys.
+ */
+export function projectCommitPayload(modelName, source, opts, runtime = globalRuntime) {
+    const metadata = runtime.getModelMetadata(modelName);
+    const fields = metadata?.fields;
+    const out = {};
+    if (!fields) {
+        // Unknown registration — strip framework keys and ship the rest.
+        for (const [k, v] of Object.entries(source)) {
+            if (FRAMEWORK_KEYS.has(k))
+                continue;
+            if (opts.dropUndefined && v === undefined)
+                continue;
+            out[k] = v;
+        }
+        return snapshotJsonValue(out, '$.input');
+    }
+    for (const key of Object.keys(fields)) {
+        if (!(key in source))
+            continue;
+        const value = source[key];
+        if (opts.dropUndefined && value === undefined)
+            continue;
+        // JSON-typed fields (stored as jsonb on the server) are sent as objects,
+        // not pre-serialized strings. Pre-stringifying here corrupts a round trip:
+        //
+        //   1. The client stringifies `position: {x, y}` to `'{"x":...}'`.
+        //   2. The server writes it to the jsonb column, parsing the string, fine.
+        //   3. The server's delta echoes the input, where `position` is still the
+        //      string from step 1.
+        //   4. The client merges the delta and sets `model.position` to that string.
+        //   5. The next edit spreads the string character by character, producing a
+        //      corrupted, index-keyed object.
+        //   6. That corrupt object lands in the next commit and is stored in jsonb.
+        //
+        // Sending objects avoids the mismatch: the value travels through the delta
+        // and the commit unchanged, and the Postgres driver serializes a JS object
+        // to jsonb correctly once the column is identified as jsonb.
+        out[key] = value;
+    }
+    return snapshotJsonValue(out, '$.input');
+}
+export const normalizeModelKey = (modelName) => modelName.replace('Model', '').toLowerCase();
+export const stripModelSuffix = (modelName) => modelName.replace('Model', '');
+/**
+ * Returns the priority score used to order create operations by foreign-key
+ * depth, so a parent row commits before its children.
+ *
+ * The score comes from a priority map on the runtime configuration, built once
+ * at initialization by walking the schema's `belongsTo` graph. No model names
+ * are hard-coded here, and an application can override specific priorities
+ * through `configOverrides.modelCreatePriority`.
+ *
+ * Non-create operations (update, delete, archive, unarchive) need no
+ * foreign-key ordering because the row already exists, so they all share the
+ * configured default non-create priority.
+ */
+export const computePriorityScore = (type, modelName, runtime = globalRuntime) => {
+    const { modelCreatePriority, defaultCreatePriority, defaultNonCreatePriority } = runtime.config;
+    if (type !== 'create')
+        return defaultNonCreatePriority;
+    return modelCreatePriority.get(modelName) ?? defaultCreatePriority;
+};
+export const TX_TYPE_TO_MUTATION_OP = {
+    create: MutationOperationType.CREATE,
+    update: MutationOperationType.UPDATE,
+    delete: MutationOperationType.DELETE,
+    archive: MutationOperationType.ARCHIVE,
+    unarchive: MutationOperationType.UNARCHIVE,
+};
+export function hasStaleWriteOptions(options) {
+    return (options?.readAt !== undefined ||
+        options?.onStale !== undefined);
+}
+/** Options whose identity/audit semantics forbid merging two caller writes. */
+export function hasCommitCoalescingBarrier(options) {
+    return (hasStaleWriteOptions(options) ||
+        typeof options?.idempotencyKey === 'string' ||
+        typeof options?.label === 'string');
+}
+/**
+ * Copies a transaction's `writeOptions` onto the wire operation. The
+ * stale-context guards (`readAt` and `onStale`) sit at the operation's root,
+ * while `idempotencyKey` and `label` go in its `options` slot — the
+ * `mutation_log` cache key and audit tag. This is the one place caller-supplied
+ * write options cross onto the wire.
+ */
+export function applyWriteOptions(op, transaction) {
+    const operation = op;
+    const writeOptions = transaction.writeOptions;
+    if (!writeOptions)
+        return operation;
+    if (writeOptions.readAt !== undefined) {
+        operation.readAt = writeOptions.readAt;
+    }
+    if (writeOptions.onStale !== undefined) {
+        operation.onStale = writeOptions.onStale;
+    }
+    if (writeOptions.fenceToken !== undefined) {
+        operation.fenceToken = writeOptions.fenceToken;
+    }
+    if (writeOptions.idempotencyKey != null || writeOptions.label !== undefined) {
+        operation.options = {
+            ...(writeOptions.idempotencyKey != null
+                ? { idempotencyKey: writeOptions.idempotencyKey }
+                : {}),
+            ...(writeOptions.label !== undefined ? { label: writeOptions.label } : {}),
+        };
+    }
+    return operation;
+}
+export function asTransportError(value) {
+    return (value && typeof value === 'object' ? value : {});
+}
+export function extractStatusCode(error) {
+    return asTransportError(error).response?.status;
+}

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

@@ -0,0 +1,36 @@
+import type { RuntimeContext } from '../../RuntimeContext.js';
+import type { MutationExecutor } from '../../interfaces/index.js';
+import type { ReadDependency, TrackDependency } from '@abloatai/transaction/coordination/schema';
+import { type MutationCommitResult } from '@abloatai/transaction/wire/commit';
+import { type CommitOutboxScope, type DurableCommitEnvelope, type DurableCommitOperation } from '@abloatai/transaction/transactions/settlement/commitEnvelope';
+import type { DurableWriteStore } from './durableWriteStore.js';
+export interface CommitTransportContext {
+    readonly runtime: RuntimeContext;
+    readonly config: {
+        enablePersistence: boolean;
+        commitDispatchTimeoutMs: number;
+    };
+    readonly commitOutbox: DurableWriteStore | null;
+    readonly commitOutboxScope: CommitOutboxScope | null;
+    readonly mutationExecutor: MutationExecutor;
+    readonly emitCommitLifecycle: (event: string, payload: object) => void;
+}
+export interface SealDurableCommitInput {
+    idempotencyKey: string;
+    origin: 'model_batch' | 'atomic_commit';
+    operations: DurableCommitOperationInput[];
+    sourceMutationIds?: string[];
+    commitOptions?: {
+        reads?: readonly ReadDependency[] | null;
+        track?: readonly TrackDependency[] | null;
+    };
+    createdAt: number;
+    sealedAt: number;
+    sequence?: number;
+}
+export type DurableCommitOperationInput = DurableCommitOperation;
+export declare function sealDurableCommit(ctx: CommitTransportContext, input: SealDurableCommitInput, pendingMutationRecordId: (id: string) => string): Promise<DurableCommitEnvelope>;
+export declare function removeDurableCommit(ctx: CommitTransportContext, idempotencyKey: string): Promise<void>;
+export declare function persistDurableCommitAcceptance(ctx: CommitTransportContext, envelope: DurableCommitEnvelope, result: MutationCommitResult): Promise<DurableCommitEnvelope>;
+export declare function parseMutationCommitResult(value: Awaited<ReturnType<MutationExecutor['commit']>>): MutationCommitResult;
+export declare function dispatchCommitBounded(ctx: CommitTransportContext, ...args: Parameters<MutationExecutor['commit']>): ReturnType<MutationExecutor['commit']>;

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

@@ -0,0 +1,104 @@
+import { AbloConnectionError, AbloError, AbloIdempotencyError, } from '@abloatai/transaction/errors';
+import { mutationCommitResultSchema, } from '@abloatai/transaction/wire/commit';
+import { createDurableCommitEnvelope, commitEnvelopeRecordId, durableCommitEnvelopeSchema, } from '@abloatai/transaction/transactions/settlement/commitEnvelope';
+export async function sealDurableCommit(ctx, input, pendingMutationRecordId) {
+    const sourceMutationIds = [...new Set(input.sourceMutationIds ?? [])];
+    const envelope = createDurableCommitEnvelope({
+        idempotencyKey: input.idempotencyKey,
+        origin: input.origin,
+        operations: [...input.operations],
+        sourceMutationIds,
+        commitOptions: {
+            ...(input.commitOptions?.reads !== undefined
+                ? { reads: input.commitOptions.reads === null ? null : [...input.commitOptions.reads] }
+                : {}),
+            ...(input.commitOptions?.track !== undefined
+                ? { track: input.commitOptions.track === null ? null : [...input.commitOptions.track] }
+                : {}),
+        },
+        ...(ctx.commitOutboxScope ? { scope: ctx.commitOutboxScope } : {}),
+        createdAt: input.createdAt,
+        sealedAt: input.sealedAt,
+        sequence: input.sequence ?? input.sealedAt * 1_000,
+    });
+    if (ctx.config.enablePersistence && ctx.commitOutbox) {
+        try {
+            await ctx.commitOutbox.seal(envelope, sourceMutationIds.map(pendingMutationRecordId));
+        }
+        catch (cause) {
+            if (cause instanceof AbloError)
+                throw cause;
+            throw new AbloConnectionError('Could not persist the durable write before dispatch', {
+                code: 'db_not_opened',
+                cause,
+            });
+        }
+        ctx.emitCommitLifecycle('commit:envelope_persisted', {
+            idempotencyKey: envelope.idempotencyKey,
+            sourceMutationIds: envelope.sourceMutationIds,
+        });
+    }
+    return envelope;
+}
+export async function removeDurableCommit(ctx, idempotencyKey) {
+    if (!ctx.config.enablePersistence || !ctx.commitOutbox)
+        return;
+    try {
+        await ctx.commitOutbox.remove(commitEnvelopeRecordId(idempotencyKey));
+    }
+    catch (error) {
+        ctx.runtime.logger.debug('[MutationQueue] Durable-write cleanup deferred', {
+            idempotencyKey,
+            error: error instanceof Error ? error.message : String(error),
+        });
+    }
+}
+export async function persistDurableCommitAcceptance(ctx, envelope, result) {
+    if (result.status !== 'queued')
+        return envelope;
+    const correlationId = result.correlationId;
+    if (!correlationId) {
+        throw new AbloConnectionError('The source accepted the commit without durable correlation evidence.', {
+            code: 'commit_no_result',
+        });
+    }
+    if (envelope.correlationId !== undefined && envelope.correlationId !== correlationId) {
+        throw new AbloIdempotencyError('The same commit replay returned a different source correlation.', {
+            code: 'idempotency_conflict',
+        });
+    }
+    if (envelope.acceptedAt !== undefined)
+        return envelope;
+    const accepted = durableCommitEnvelopeSchema.parse({
+        ...envelope,
+        acceptedAt: Math.max(Date.now(), envelope.sealedAt),
+        correlationId,
+    });
+    if (ctx.config.enablePersistence && ctx.commitOutbox) {
+        try {
+            await ctx.commitOutbox.seal(accepted, []);
+        }
+        catch (cause) {
+            if (cause instanceof AbloError)
+                throw cause;
+            throw new AbloConnectionError('The source accepted the commit, but that acceptance could not be persisted locally.', { code: 'db_not_opened', cause });
+        }
+    }
+    return accepted;
+}
+export function parseMutationCommitResult(value) {
+    const parsed = mutationCommitResultSchema.safeParse(value);
+    if (parsed.success)
+        return parsed.data;
+    throw new AbloConnectionError('The mutation transport returned an invalid commit receipt; its outcome remains pending and is safe to retry.', { code: 'commit_no_result', cause: parsed.error });
+}
+export function dispatchCommitBounded(ctx, ...args) {
+    const dispatched = ctx.mutationExecutor.commit(...args);
+    const timeoutMs = ctx.config.commitDispatchTimeoutMs;
+    if (!Number.isFinite(timeoutMs) || timeoutMs <= 0)
+        return dispatched;
+    return new Promise((resolve, reject) => {
+        const timer = setTimeout(() => reject(new AbloConnectionError('The mutation transport did not acknowledge the commit in time; its outcome remains pending and is safe to retry.', { code: 'commit_no_result' })), timeoutMs);
+        dispatched.then((value) => { clearTimeout(timer); resolve(value); }, (error) => { clearTimeout(timer); reject(error instanceof Error ? error : new Error(String(error))); });
+    });
+}

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

@@ -0,0 +1,63 @@
+/**
+ * Tracks whether the confirming delta for a write has arrived. It holds the
+ * acknowledgement watermark (through the shared {@link LogPosition}), the
+ * per-transaction confirmation timeouts, and the retry-with-backoff and
+ * reconciliation policy for transactions in the `awaiting_delta` status. It
+ * reaches back to {@link MutationQueue} only through the small
+ * {@link DeltaConfirmationContext} interface, not the queue class itself, so it
+ * has no cyclic dependency and can be tested on its own.
+ */
+import type { RuntimeContext } from '../../RuntimeContext.js';
+import type { LogPositionPort } from '../../logPosition.js';
+import type { QueuedMutation } from './commitPayload.js';
+/**
+ * The subset of {@link MutationQueue} that the confirmation tracker needs:
+ * store lookups and status changes, removing optimistic entries once a write
+ * confirms, the queue's event emitter (`transaction:completed`,
+ * `reconciliation:needed`, and so on), a connection check (so timeouts
+ * re-schedule instead of escalating while offline), and the shared client
+ * position (`noteAck` advances the acknowledgement cursor; diagnostics read the
+ * applied cursor).
+ */
+export interface DeltaConfirmationContext {
+    store: {
+        get(id: string): QueuedMutation | undefined;
+        getByStatus(status: QueuedMutation['status']): QueuedMutation[];
+        updateStatus(id: string, status: QueuedMutation['status']): void;
+    };
+    optimisticUpdates: {
+        delete(id: string): boolean;
+    };
+    emit(event: string, payload?: unknown): void;
+    isConnected(): boolean;
+    position: LogPositionPort;
+    /** The owning client's runtime. Defaults to the module-global bridge. */
+    runtime?: RuntimeContext;
+}
+export declare class DeltaConfirmationTracker {
+    private readonly ctx;
+    private static readonly DELTA_MAX_RETRIES;
+    private static readonly DELTA_MAX_TIMEOUT_MS;
+    private deltaConfirmationTimeouts;
+    private deltaConfirmationRetries;
+    private readonly runtime;
+    constructor(ctx: DeltaConfirmationContext);
+    /** Applied-cursor alias, kept so the read sites below stay legible. */
+    private get lastSeenSyncId();
+    private matchesSourceEcho;
+    noteAck(lastSyncId: number | undefined): void;
+    /**
+     * Confirms every awaiting transaction whose sync-id threshold this delta
+     * meets or exceeds.
+     * @param syncId - The sync id of the received delta.
+     */
+    onDeltaReceived(syncId: number, correlationId?: string): void;
+    scheduleDeltaConfirmationTimeout(tx: QueuedMutation, timeoutMs: number): void;
+    private cancelDeltaConfirmationTimeout;
+    /**
+     * Clears every armed confirmation timer, one per in-flight transaction.
+     * {@link MutationQueue.dispose} calls this; without it a disposed queue
+     * would keep the process alive and fire callbacks against a cleared store.
+     */
+    dispose(): void;
+}

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

@@ -0,0 +1,235 @@
+/**
+ * Tracks whether the confirming delta for a write has arrived. It holds the
+ * acknowledgement watermark (through the shared {@link LogPosition}), the
+ * per-transaction confirmation timeouts, and the retry-with-backoff and
+ * reconciliation policy for transactions in the `awaiting_delta` status. It
+ * reaches back to {@link MutationQueue} only through the small
+ * {@link DeltaConfirmationContext} interface, not the queue class itself, so it
+ * has no cyclic dependency and can be tested on its own.
+ */
+import { globalRuntime } from '../../context.js';
+export class DeltaConfirmationTracker {
+    ctx;
+    // Retry configuration for delta confirmation, using exponential backoff.
+    // Maximum retries before requesting a full reconciliation.
+    static DELTA_MAX_RETRIES = 5;
+    // Upper bound on the backoff timeout.
+    static DELTA_MAX_TIMEOUT_MS = 120_000;
+    // Pending confirmation timeouts for transactions awaiting their delta. On
+    // timeout the tracker retries with backoff rather than rolling back.
+    deltaConfirmationTimeouts = new Map();
+    // Track retry attempts per transaction for exponential backoff
+    deltaConfirmationRetries = new Map();
+    runtime;
+    constructor(ctx) {
+        this.ctx = ctx;
+        this.runtime = ctx.runtime ?? globalRuntime;
+    }
+    /** Applied-cursor alias, kept so the read sites below stay legible. */
+    get lastSeenSyncId() {
+        return this.ctx.position.applied;
+    }
+    matchesSourceEcho(tx, correlationId) {
+        return (correlationId !== undefined &&
+            tx.correlationId !== undefined &&
+            correlationId === tx.correlationId);
+    }
+    noteAck(lastSyncId) {
+        this.ctx.position.noteAck(lastSyncId);
+    }
+    /**
+     * Confirms every awaiting transaction whose sync-id threshold this delta
+     * meets or exceeds.
+     * @param syncId - The sync id of the received delta.
+     */
+    onDeltaReceived(syncId, correlationId) {
+        // The cursor advances where the delta is applied (the store calls
+        // position.advanceApplied / advancePersisted); this hook only resolves
+        // confirmation thresholds against the incoming id.
+        const awaitingTxs = this.ctx.store.getByStatus('awaiting_delta');
+        const executingTxs = this.ctx.store.getByStatus('executing');
+        // Debug: Show state when delta arrives
+        if (awaitingTxs.length > 0 || executingTxs.length > 0) {
+            this.runtime.logger.debug('tx:delta_received', {
+                syncId,
+                lastSeenSyncId: this.lastSeenSyncId,
+                awaitingCount: awaitingTxs.length,
+                executingCount: executingTxs.length,
+                awaitingThresholds: awaitingTxs.map((tx) => ({
+                    txId: tx.id.slice(0, 8),
+                    model: tx.modelName,
+                    needed: tx.syncIdNeededForCompletion,
+                    requiresCorrelatedDelta: tx.requiresCorrelatedDelta === true,
+                    willConfirm: tx.requiresCorrelatedDelta === true
+                        ? this.matchesSourceEcho(tx, correlationId)
+                        : tx.syncIdNeededForCompletion !== undefined &&
+                            syncId >= tx.syncIdNeededForCompletion,
+                })),
+            });
+        }
+        // Fast path: no awaiting transactions
+        if (awaitingTxs.length === 0)
+            return;
+        let confirmedCount = 0;
+        for (const tx of awaitingTxs) {
+            // Queued forward receipts deliberately have no watermark. They confirm
+            // only when the authoritative source echoes the receipt's opaque,
+            // authenticated-scope batch identity; the legacy anomaly path continues
+            // to use its sync-id threshold.
+            const confirmedByCorrelation = tx.requiresCorrelatedDelta === true &&
+                this.matchesSourceEcho(tx, correlationId);
+            const confirmedByThreshold = tx.requiresCorrelatedDelta !== true &&
+                tx.syncIdNeededForCompletion !== undefined &&
+                syncId >= tx.syncIdNeededForCompletion;
+            if (confirmedByCorrelation || confirmedByThreshold) {
+                this.cancelDeltaConfirmationTimeout(tx.id);
+                this.ctx.store.updateStatus(tx.id, 'completed');
+                this.ctx.emit('transaction:completed', tx);
+                this.ctx.emit(`transaction:completed:${tx.id}`, tx);
+                this.ctx.optimisticUpdates.delete(tx.id);
+                confirmedCount++;
+                this.runtime.logger.debug('tx:confirm_via_delta', {
+                    txId: tx.id.slice(0, 8),
+                    model: tx.modelName,
+                    neededSyncId: tx.syncIdNeededForCompletion,
+                    receivedSyncId: syncId,
+                    confirmation: confirmedByCorrelation ? 'source_correlation' : 'sync_id',
+                });
+            }
+        }
+        // Log batch summary only if we confirmed something
+        if (confirmedCount > 0) {
+            // Leave a breadcrumb when transactions confirm.
+            this.runtime.observability.breadcrumb('Transactions confirmed via delta', 'sync.transaction', 'info', {
+                count: confirmedCount,
+                syncId,
+                remainingAwaiting: awaitingTxs.length - confirmedCount,
+            });
+        }
+    }
+    // Schedule the confirmation wait for a transaction. On timeout the tracker
+    // retries with exponential backoff and requests reconciliation to catch up on
+    // missed deltas, rather than rolling back, which would discard state the
+    // server has already confirmed. A rollback happens only on an explicit server
+    // rejection, never on a timeout.
+    scheduleDeltaConfirmationTimeout(tx, timeoutMs) {
+        // Cancel any existing timeout for this transaction
+        this.cancelDeltaConfirmationTimeout(tx.id);
+        // Deliberately not an async callback: the body is fully synchronous, and
+        // `setTimeout(async …)` would turn any throw into an unhandled promise
+        // rejection instead of a catchable synchronous error.
+        const timeoutHandle = setTimeout(() => {
+            const currentTx = this.ctx.store.get(tx.id);
+            if (currentTx?.status !== 'awaiting_delta') {
+                this.deltaConfirmationRetries.delete(tx.id);
+                return; // Already confirmed or failed
+            }
+            // If disconnected, re-schedule with same timeout (no backoff while offline)
+            if (!this.ctx.isConnected()) {
+                // Self-healing: re-schedule the confirmation wait while offline, no
+                // consumer action needed → debug.
+                this.runtime.logger.debug('[MutationQueue] Timeout fired while disconnected - re-scheduling', {
+                    txId: tx.id.slice(0, 8),
+                    model: tx.modelName,
+                });
+                this.deltaConfirmationTimeouts.delete(tx.id);
+                this.scheduleDeltaConfirmationTimeout(tx, timeoutMs);
+                return;
+            }
+            const retryCount = this.deltaConfirmationRetries.get(tx.id) ?? 0;
+            this.runtime.observability.captureReconciliation({
+                reason: 'delta_timeout',
+                model: tx.modelName,
+                modelId: tx.modelId,
+                syncIdNeeded: currentTx.syncIdNeededForCompletion,
+                lastSeenSyncId: this.lastSeenSyncId,
+                retryCount,
+                connectionState: this.ctx.isConnected() ? 'connected' : 'disconnected',
+            });
+            if (retryCount < DeltaConfirmationTracker.DELTA_MAX_RETRIES) {
+                // Retry: request reconciliation and re-schedule with exponential
+                // backoff. The server has already committed the mutation; only the
+                // delta is outstanding.
+                this.deltaConfirmationRetries.set(tx.id, retryCount + 1);
+                this.deltaConfirmationTimeouts.delete(tx.id);
+                // Exponential backoff: 30s → 60s → 120s → 120s → 120s (capped)
+                const nextTimeout = Math.min(timeoutMs * 2, DeltaConfirmationTracker.DELTA_MAX_TIMEOUT_MS);
+                // Request reconciliation so the client can cycle the connection and
+                // catch up on missed deltas from the server.
+                this.ctx.emit('reconciliation:needed', {
+                    reason: 'delta_confirmation_timeout',
+                    txId: tx.id,
+                    model: tx.modelName,
+                    modelId: tx.modelId,
+                    syncIdNeeded: currentTx.syncIdNeededForCompletion,
+                    lastSeenSyncId: this.lastSeenSyncId,
+                    retryCount: retryCount + 1,
+                });
+                // Self-healing retry with backoff — the server already committed; we're
+                // just waiting on the delta. No consumer action → debug.
+                this.runtime.logger.debug('[MutationQueue] Re-scheduling with backoff', {
+                    txId: tx.id.slice(0, 8),
+                    model: tx.modelName,
+                    nextTimeoutMs: nextTimeout,
+                    retry: retryCount + 1,
+                });
+                this.scheduleDeltaConfirmationTimeout(tx, nextTimeout);
+            }
+            else {
+                // Retries exhausted: persist the awaiting state instead of rolling back.
+                // The commit succeeded on the server, so the data exists there. Saving
+                // the awaiting state lets it survive the page closing; on the next
+                // session, reconnecting and catching up on deltas will confirm it.
+                this.deltaConfirmationRetries.delete(tx.id);
+                this.deltaConfirmationTimeouts.delete(tx.id);
+                this.runtime.observability.captureDeltaRetryExhausted({
+                    txId: tx.id,
+                    model: tx.modelName,
+                    modelId: tx.modelId,
+                    retryCount: DeltaConfirmationTracker.DELTA_MAX_RETRIES,
+                    syncIdNeeded: currentTx.syncIdNeededForCompletion,
+                });
+                // Emit the persist event; the client performs the write to local storage.
+                this.ctx.emit('transaction:persist_awaiting', {
+                    txId: tx.id,
+                    model: tx.modelName,
+                    modelId: tx.modelId,
+                    operationType: tx.type,
+                    syncIdNeeded: currentTx.syncIdNeededForCompletion,
+                });
+                // Also request one final reconciliation cycle
+                this.ctx.emit('reconciliation:needed', {
+                    reason: 'delta_retries_exhausted',
+                    txId: tx.id,
+                    model: tx.modelName,
+                    modelId: tx.modelId,
+                    syncIdNeeded: currentTx.syncIdNeededForCompletion,
+                    lastSeenSyncId: this.lastSeenSyncId,
+                    retryCount: DeltaConfirmationTracker.DELTA_MAX_RETRIES,
+                });
+            }
+        }, timeoutMs);
+        this.deltaConfirmationTimeouts.set(tx.id, timeoutHandle);
+    }
+    // Cancel a pending delta confirmation timeout and clean up retry tracking
+    cancelDeltaConfirmationTimeout(id) {
+        const timeoutHandle = this.deltaConfirmationTimeouts.get(id);
+        if (timeoutHandle) {
+            clearTimeout(timeoutHandle);
+            this.deltaConfirmationTimeouts.delete(id);
+        }
+        this.deltaConfirmationRetries.delete(id);
+    }
+    /**
+     * Clears every armed confirmation timer, one per in-flight transaction.
+     * {@link MutationQueue.dispose} calls this; without it a disposed queue
+     * would keep the process alive and fire callbacks against a cleared store.
+     */
+    dispose() {
+        for (const timeoutHandle of this.deltaConfirmationTimeouts.values()) {
+            clearTimeout(timeoutHandle);
+        }
+        this.deltaConfirmationTimeouts.clear();
+        this.deltaConfirmationRetries.clear();
+    }
+}

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

@@ -0,0 +1,17 @@
+import type { RuntimeContext } from '../../RuntimeContext.js';
+import type { CommitTransaction } from './commitLane.js';
+import type { CommitOutboxScope } from '@abloatai/transaction/transactions/settlement/commitEnvelope';
+import type { DurableWriteStore } from './durableWriteStore.js';
+export interface DurableCommitRestoreContext {
+    readonly config: {
+        enablePersistence: boolean;
+    };
+    readonly commitOutbox: DurableWriteStore | null;
+    readonly commitOutboxScope: CommitOutboxScope | null;
+    readonly commitStore: Map<string, CommitTransaction>;
+    readonly commitLane: CommitTransaction[];
+    readonly runtime: RuntimeContext;
+    readonly processCommitLane: () => Promise<void>;
+    readonly durableReplayWindowMs: number;
+}
+export declare function restoreDurableCommits(ctx: DurableCommitRestoreContext): Promise<Set<string>>;