@abloatai/humans 0.37.0

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

@@ -0,0 +1,95 @@
+import { AbloIdempotencyError, AbloValidationError } from '@abloatai/transaction/errors';
+import { durableCommitEnvelopeSchema } from '@abloatai/transaction/transactions/settlement/commitEnvelope';
+export async function restoreDurableCommits(ctx) {
+    if (!ctx.config.enablePersistence)
+        return new Set();
+    const sourceMutationIds = new Set();
+    try {
+        if (!ctx.commitOutbox)
+            return sourceMutationIds;
+        const rows = await ctx.commitOutbox.list();
+        const envelopes = [];
+        for (const row of rows) {
+            if (typeof row !== 'object' ||
+                row === null ||
+                row.type !== 'commit_envelope')
+                continue;
+            const parsed = durableCommitEnvelopeSchema.safeParse(row);
+            if (parsed.success) {
+                envelopes.push(parsed.data);
+            }
+            else {
+                ctx.runtime.logger.warn('A saved local write is unreadable and was held for review.');
+                ctx.runtime.observability.captureMutationFailure({
+                    context: 'restore-commit-envelope',
+                    error: parsed.error,
+                });
+                throw new AbloValidationError('A saved commit envelope is unreadable; replay stopped before newer writes were sent.', { code: 'write_options_invalid', cause: parsed.error });
+            }
+        }
+        envelopes.sort((a, b) => (a.sequence ?? a.sealedAt * 1_000) -
+            (b.sequence ?? b.sealedAt * 1_000) ||
+            a.id.localeCompare(b.id));
+        for (const envelope of envelopes) {
+            for (const mutationId of envelope.sourceMutationIds) {
+                sourceMutationIds.add(mutationId);
+            }
+            if (envelope.acceptedAt === undefined &&
+                Date.now() - envelope.sealedAt >=
+                    ctx.durableReplayWindowMs) {
+                ctx.runtime.logger.warn('A saved local write is too old to retry safely and was held for review.');
+                ctx.runtime.observability.captureMutationFailure({
+                    context: 'quarantine-expired-commit-envelope',
+                    error: `Envelope ${envelope.idempotencyKey} is too old to replay safely`,
+                });
+                throw new AbloIdempotencyError('A saved commit is older than the server idempotency window and cannot be replayed safely.', { code: 'idempotency_conflict' });
+            }
+            if (ctx.commitOutboxScope &&
+                (!envelope.scope || // eslint-disable-line @typescript-eslint/prefer-optional-chain -- missing scope must quarantine
+                    envelope.scope.organizationId !== ctx.commitOutboxScope.organizationId ||
+                    envelope.scope.participantId !== ctx.commitOutboxScope.participantId ||
+                    envelope.scope.namespace !== ctx.commitOutboxScope.namespace)) {
+                ctx.runtime.logger.warn('A saved local write belongs to a different account or server and was held for review.');
+                continue;
+            }
+            if (ctx.commitStore.has(envelope.idempotencyKey))
+                continue;
+            const transaction = {
+                id: envelope.idempotencyKey,
+                kind: 'commit',
+                operations: envelope.operations.map((operation) => ({ ...operation })),
+                ...(envelope.commitOptions.reads
+                    ? { reads: [...envelope.commitOptions.reads] }
+                    : {}),
+                ...(envelope.commitOptions.track
+                    ? { track: [...envelope.commitOptions.track] }
+                    : {}),
+                status: 'pending',
+                createdAt: envelope.createdAt,
+                sealedAt: envelope.sealedAt,
+                sequence: envelope.sequence ?? envelope.sealedAt * 1_000,
+                attempts: 0,
+                ...(envelope.correlationId
+                    ? { correlationId: envelope.correlationId }
+                    : {}),
+                sourceMutationIds: [...envelope.sourceMutationIds],
+                durableEnvelope: envelope,
+            };
+            ctx.commitStore.set(transaction.id, transaction);
+            ctx.commitLane.push(transaction);
+        }
+        if (ctx.commitLane.length > 0)
+            void ctx.processCommitLane();
+    }
+    catch (error) {
+        ctx.runtime.logger.debug('[MutationQueue] Failed to restore durable writes', {
+            error: error instanceof Error ? error.message : String(error),
+        });
+        ctx.runtime.observability.captureMutationFailure({
+            context: 'restore-commit-envelopes',
+            error: error instanceof Error ? error : String(error),
+        });
+        throw error;
+    }
+    return sourceMutationIds;
+}

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

@@ -0,0 +1,14 @@
+/**
+ * The durable-write port moved to the settlement core (ADR 0016): it is a
+ * contract over commit envelopes and holds no local rows. Re-exported here so
+ * the existing `transactions/mutations/durableWriteStore` import path keeps
+ * resolving for the queue, the outbox, and the client options.
+ *
+ * The port and its config live in the core's `durableWrites` module (a behavior
+ * contract, not a persisted shape); the records that cross it are owned by
+ * `transactions/settlement/pendingWrite`.
+ */
+export { durableWriteStoreSchema, durableWritesConfigSchema, } from '@abloatai/transaction/durableWrites';
+export type { DurableWriteStore, DurableWritesConfig, } from '@abloatai/transaction/durableWrites';
+export { pendingWriteSchema } from '@abloatai/transaction/transactions/settlement/pendingWrite';
+export type { PendingWrite } from '@abloatai/transaction/transactions/settlement/pendingWrite';

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

@@ -0,0 +1,12 @@
+/**
+ * The durable-write port moved to the settlement core (ADR 0016): it is a
+ * contract over commit envelopes and holds no local rows. Re-exported here so
+ * the existing `transactions/mutations/durableWriteStore` import path keeps
+ * resolving for the queue, the outbox, and the client options.
+ *
+ * The port and its config live in the core's `durableWrites` module (a behavior
+ * contract, not a persisted shape); the records that cross it are owned by
+ * `transactions/settlement/pendingWrite`.
+ */
+export { durableWriteStoreSchema, durableWritesConfigSchema, } from '@abloatai/transaction/durableWrites';
+export { pendingWriteSchema } from '@abloatai/transaction/transactions/settlement/pendingWrite';

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

@@ -0,0 +1,6 @@
+import type { QueuedMutation } from './commitPayload.js';
+export declare function takeNextExecutionBatch(executionQueue: QueuedMutation[], maxBatchSize: number): {
+    batch: QueuedMutation[];
+    remaining: QueuedMutation[];
+};
+export declare function takePendingDrainBatch(pending: QueuedMutation[], maxBatchSize: number): QueuedMutation[];

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

@@ -0,0 +1,42 @@
+export function takeNextExecutionBatch(executionQueue, maxBatchSize) {
+    const retryGroups = new Map();
+    for (const tx of executionQueue) {
+        const envelope = tx.commitEnvelope;
+        if (!envelope)
+            continue;
+        const group = retryGroups.get(envelope.idempotencyKey) ?? new Map();
+        group.set(tx.id, tx);
+        retryGroups.set(envelope.idempotencyKey, group);
+    }
+    for (const [idempotencyKey, byId] of retryGroups) {
+        const members = [...byId.values()];
+        const expectedCount = members[0]?.commitEnvelope?.operationCount;
+        if (expectedCount === undefined || members.length !== expectedCount)
+            continue;
+        const remaining = executionQueue.filter((tx) => tx.commitEnvelope?.idempotencyKey !== idempotencyKey);
+        members.sort((a, b) => (a.commitEnvelope?.operationIndex ?? 0) - (b.commitEnvelope?.operationIndex ?? 0));
+        return { batch: members, remaining };
+    }
+    const fresh = executionQueue.filter((tx) => !tx.commitEnvelope);
+    const firstFresh = fresh[0];
+    if (!firstFresh)
+        return { batch: [], remaining: executionQueue };
+    const explicitIndex = fresh.findIndex((tx) => typeof tx.writeOptions?.idempotencyKey === 'string');
+    const selected = explicitIndex === 0
+        ? [firstFresh]
+        : fresh.slice(0, Math.min(maxBatchSize, explicitIndex > 0 ? explicitIndex : fresh.length));
+    const selectedIds = new Set(selected.map((tx) => tx.id));
+    return { batch: selected, remaining: executionQueue.filter((tx) => !selectedIds.has(tx.id)) };
+}
+export function takePendingDrainBatch(pending, maxBatchSize) {
+    const first = pending[0];
+    if (!first)
+        return [];
+    const envelope = first.commitEnvelope;
+    if (envelope)
+        return pending.filter((tx) => tx.commitEnvelope?.idempotencyKey === envelope.idempotencyKey);
+    if (typeof first.writeOptions?.idempotencyKey === 'string')
+        return [first];
+    const explicitIndex = pending.findIndex((tx) => typeof tx.writeOptions?.idempotencyKey === 'string');
+    return pending.slice(0, Math.min(maxBatchSize, explicitIndex > 0 ? explicitIndex : pending.length));
+}

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

@@ -0,0 +1,16 @@
+import type { RuntimeContext } from '../../RuntimeContext.js';
+import type { MutationQueueConfig } from './MutationQueue.js';
+import type { QueuedMutation } from './commitPayload.js';
+import type { MutationStore } from './MutationStore.js';
+export interface FailureHandlingContext {
+    readonly runtime: RuntimeContext;
+    readonly config: Pick<MutationQueueConfig, 'enableOptimistic' | 'maxRetries' | 'retryBackoff'>;
+    readonly store: MutationStore;
+    readonly isPermanentError: (error: Error) => boolean;
+    readonly rollbackOptimistic: (transaction: QueuedMutation, reason: string, error?: Error) => Promise<void>;
+    readonly enqueue: (transaction: QueuedMutation) => void;
+    readonly getLastPermanentErrorSignature: () => string | undefined;
+    readonly setLastPermanentErrorSignature: (signature: string) => void;
+    readonly emit: (event: string, payload: object) => boolean;
+}
+export declare function handleFailure(ctx: FailureHandlingContext, transaction: QueuedMutation, error: Error): Promise<void>;

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

@@ -0,0 +1,130 @@
+import { AbloError } from '@abloatai/transaction/errors';
+import { extractStatusCode } from './commitPayload.js';
+export async function handleFailure(ctx, transaction, error) {
+    transaction.attempts++;
+    // Check whether this is a permanent error that should not be retried.
+    if (ctx.isPermanentError(error)) {
+        // Logged at warn: a permanent error means the server rejected the write,
+        // so the developer should see the reason in the console. The typed
+        // AbloError fields (`type`, `code`, `httpStatus`) are included so the
+        // cause is visible — for example a foreign-key violation
+        // (AbloValidationError) versus expired authentication
+        // (AbloAuthenticationError).
+        try {
+            const abloErr = error instanceof AbloError ? error : undefined;
+            const details = {
+                txId: transaction.id.slice(0, 8),
+                type: transaction.type,
+                model: transaction.modelName,
+                modelId: transaction.modelId.slice(0, 12),
+                errorType: abloErr?.type ?? error?.name,
+                errorCode: abloErr?.code,
+                httpStatus: abloErr?.httpStatus,
+                requestId: abloErr?.requestId,
+                message: error?.message,
+                inputKeys: transaction.data ? Object.keys(transaction.data) : undefined,
+            };
+            // A `create` whose id already exists is the benign idempotency case:
+            // "this row is already there." It's the least alarming permanent
+            // error, so it doesn't warrant a `warn` — `info` keeps it visible
+            // without crying wolf. Everything else (FK violation, auth expiry,
+            // server 500) stays at `warn`.
+            const isBenignIdempotent = transaction.type === 'create' &&
+                (abloErr?.code === 'unique_violation' ||
+                    abloErr?.type === 'AbloIdempotencyError');
+            // Demote exact repeats (same write rejected for the same reason on
+            // each reconnect replay) to `debug` so the loop logs once.
+            const sig = `${details.type}:${details.model}:${details.modelId}:${details.errorCode ?? details.errorType}`;
+            const isRepeat = sig === ctx.getLastPermanentErrorSignature();
+            ctx.setLastPermanentErrorSignature(sig);
+            const logger = ctx.runtime.logger;
+            // Two registers from one call site, split by log level (the default
+            // logger is gated at `warn`, so `debug` stays hidden unless
+            // ABLO_LOG_LEVEL=debug is set to inspect the engine):
+            //   - the default-visible line speaks the application developer's
+            //     language: their verb (such as `update`), their model, the typed
+            //     error's own message, and the wire `code` for searching. It uses
+            //     no engine jargon and prints no JSON dump, which would alarm
+            //     without helping.
+            //   - the forensic `details` ride a companion `debug` line for anyone
+            //     debugging the engine internals.
+            const revertNote = ctx.config.enableOptimistic
+                ? ' The local change was reverted.'
+                : '';
+            const reason = abloErr?.message ? ` — ${abloErr.message}` : '';
+            const code = abloErr?.code ? ` (code: ${abloErr.code})` : '';
+            // An optimistic write resolves before the server answers, so a later
+            // rejection has no caller left to return to and this log is the only
+            // place it appears. That reads to an application developer as their own
+            // save silently failing — the write showed, then vanished — and sends
+            // them into their editor instead of here. Name the subscription that
+            // hands them the same typed error, so the application can say what
+            // happened rather than only the console.
+            const channelNote = ctx.config.enableOptimistic
+                ? ' To surface this in your app, subscribe with `ablo.onMutationFailure(…)`.'
+                : '';
+            const headline = `Your ${transaction.type} to "${transaction.modelName}" was not saved${reason}${code}.${revertNote}${channelNote}`;
+            if (isRepeat) {
+                // Same write rejected for the same reason on each reconnect replay —
+                // log the forensics once, stay quiet after.
+                logger.debug('write rejected again (same reason)', details);
+            }
+            else if (isBenignIdempotent) {
+                // Already-exists on a `create` is expected on replay, not a problem.
+                logger.info(`Your ${transaction.type} to "${transaction.modelName}" was skipped — this row already exists.`);
+                logger.debug('idempotent skip — details', details);
+            }
+            else {
+                logger.warn(headline);
+                logger.debug('write rejection — details', details);
+            }
+        }
+        catch { }
+        // Mark as failed immediately and rollback
+        ctx.store.updateStatus(transaction.id, 'failed');
+        if (ctx.config.enableOptimistic) {
+            await ctx.rollbackOptimistic(transaction, 'permanent_error', error);
+        }
+        ctx.emit('transaction:failed', { transaction, error, permanent: true });
+        // The id-suffixed event is what `waitForConfirmation` (the
+        // `wait:'confirmed'` path) listens on — without it a permanently
+        // rejected write left the caller's promise hanging forever.
+        ctx.emit(`transaction:failed:${transaction.id}`, { error });
+        return;
+    }
+    if (transaction.attempts < ctx.config.maxRetries) {
+        // Exponential backoff with full jitter on every transient retry:
+        // `sleep = random(0, min(cap, base * 2^attempt))`. Throttling responses
+        // (429/503) use a longer base than other transient errors. The re-enqueue
+        // is scheduled rather than awaited, so one backing-off transaction cannot
+        // stall unrelated commits.
+        const { baseMs, capMs } = ctx.config.retryBackoff;
+        let base = baseMs;
+        try {
+            const status = extractStatusCode(error);
+            if (status === 429 || status === 503)
+                base = Math.max(baseMs, 1_000);
+        }
+        catch { }
+        const ceiling = Math.min(capMs, base * Math.pow(2, transaction.attempts - 1));
+        const delay = Math.floor(Math.random() * ceiling);
+        ctx.store.updateStatus(transaction.id, 'pending');
+        setTimeout(() => {
+            // The queue may have shut down or the tx may have been settled
+            // (e.g. delta-confirmed) while we backed off.
+            if (ctx.store.get(transaction.id)?.status !== 'pending')
+                return;
+            ctx.enqueue(transaction);
+        }, delay);
+    }
+    else {
+        // Mark as failed and rollback
+        ctx.store.updateStatus(transaction.id, 'failed');
+        if (ctx.config.enableOptimistic) {
+            await ctx.rollbackOptimistic(transaction, 'max_retries_exhausted', error);
+        }
+        ctx.emit('transaction:failed', { transaction, error });
+        // Settle `waitForConfirmation` waiters (see the permanent branch above).
+        ctx.emit(`transaction:failed:${transaction.id}`, { error });
+    }
+}

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

@@ -0,0 +1,13 @@
+import type { MutationInput, QueuedMutation } from './commitPayload.js';
+import type { MutationQueueConfig } from './MutationQueue.js';
+import type { MutationStore } from './MutationStore.js';
+export declare function isPermanentError(error: Error): boolean;
+export declare function isDefinitiveRejection(error: Error): boolean;
+export interface ConflictPolicyContext {
+    readonly config: Pick<MutationQueueConfig, 'conflictResolution'>;
+    readonly store: MutationStore;
+    readonly rollbackOptimistic: (transaction: QueuedMutation, reason: string) => Promise<void>;
+    readonly mergeData: (local: MutationInput | undefined, remote: MutationInput) => MutationInput;
+    readonly enqueue: (transaction: QueuedMutation) => void;
+}
+export declare function handleConflict(ctx: ConflictPolicyContext, transaction: QueuedMutation, serverData: MutationInput): Promise<void>;

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

@@ -0,0 +1,48 @@
+import { asTransportError, extractStatusCode } from './commitPayload.js';
+import { mergeUpdateData } from './coalesceRules.js';
+import { AbloConnectionError, errorCodeSpec } from '@abloatai/transaction/errors';
+export function isPermanentError(error) {
+    if (error instanceof AbloConnectionError)
+        return false;
+    const code = error.code;
+    const spec = code ? errorCodeSpec(code) : undefined;
+    if (spec)
+        return !spec.retryable;
+    const message = error.message.toLowerCase();
+    if (['failed to fetch', 'network error', 'networkerror', 'connection refused', 'connection reset', 'timeout', 'econnrefused', 'econnreset', 'etimedout', 'socket hang up'].some((value) => message.includes(value)))
+        return false;
+    const status = extractStatusCode(error);
+    if (status !== undefined)
+        return status < 500 && status !== 429;
+    return !(asTransportError(error).response?.errors?.length);
+}
+export function isDefinitiveRejection(error) {
+    const code = error.code;
+    const spec = code ? errorCodeSpec(code) : undefined;
+    if (spec)
+        return !spec.retryable;
+    const status = extractStatusCode(error);
+    return status !== undefined && status >= 400 && status < 500 && status !== 429;
+}
+export async function handleConflict(ctx, transaction, serverData) {
+    const { strategy, resolver } = ctx.config.conflictResolution;
+    switch (strategy) {
+        case 'last-write-wins':
+            ctx.store.updateStatus(transaction.id, 'rolled_back');
+            await ctx.rollbackOptimistic(transaction, 'conflict_server_wins');
+            break;
+        case 'merge':
+            transaction.data = ctx.mergeData(transaction.data, serverData);
+            ctx.enqueue(transaction);
+            break;
+        case 'reject':
+            ctx.enqueue(transaction);
+            break;
+        case 'custom':
+            if (resolver) {
+                transaction.data = resolver(transaction.data, serverData);
+                ctx.enqueue(transaction);
+            }
+            break;
+    }
+}

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

@@ -0,0 +1,58 @@
+/**
+ * Local-first apply and rollback bookkeeping for pending mutations.
+ *
+ * When a change is written before the server confirms it, these functions
+ * record it in a ledger and emit an `optimistic:*` event; separate listeners
+ * apply the change to the in-memory data and, on rollback, restore the value
+ * it replaced. Each function takes the ledger and a small event emitter rather
+ * than any larger object, so the rules have no dependencies of their own and
+ * can be tested in isolation.
+ */
+import type { LocalModel as Model } from '../../localModelContract.js';
+import type { MutationInput, QueuedMutation } from './commitPayload.js';
+/**
+ * One tracked optimistic mutation: the live model plus the value it held
+ * before the change, kept so a rollback can restore it.
+ */
+export interface OptimisticUpdateEntry {
+    model: Model;
+    previousState: MutationInput | null | undefined;
+    transaction: QueuedMutation;
+}
+/**
+ * The event emitter these functions use to announce each optimistic change and
+ * its rollback. You supply the implementation.
+ */
+export interface OptimisticEmitter {
+    emit(event: string, payload: unknown): void;
+}
+/** Materializer capability consumed by settlement; implementation belongs to the local layer. */
+export interface LocalMutationPort {
+    readonly updates: Map<string, OptimisticUpdateEntry>;
+    applyCreate(model: Model, transaction: QueuedMutation): void;
+    applyUpdate(model: Model, transaction: QueuedMutation): void;
+    applyDelete(model: Model, transaction: QueuedMutation): void;
+    rollback(transaction: QueuedMutation, reason?: string, error?: Error): Promise<void>;
+}
+export declare function createLocalMutationPort(emitter: OptimisticEmitter): LocalMutationPort;
+/**
+ * Record an optimistic create and announce it. There is no prior value to
+ * restore, so the rollback pre-image is `null`.
+ */
+export declare function applyOptimisticCreate(optimisticUpdates: Map<string, OptimisticUpdateEntry>, emitter: OptimisticEmitter, model: Model, transaction: QueuedMutation): void;
+/**
+ * Record an optimistic update and announce it, keeping the row's prior value so
+ * a rollback can put it back.
+ */
+export declare function applyOptimisticUpdate(optimisticUpdates: Map<string, OptimisticUpdateEntry>, emitter: OptimisticEmitter, model: Model, transaction: QueuedMutation): void;
+/**
+ * Record an optimistic delete and announce it, keeping the deleted row so a
+ * rollback can restore it.
+ */
+export declare function applyOptimisticDelete(optimisticUpdates: Map<string, OptimisticUpdateEntry>, emitter: OptimisticEmitter, model: Model, transaction: QueuedMutation): void;
+/**
+ * Undo an optimistic mutation by its transaction id: emit `optimistic:rollback`
+ * with the saved pre-image so listeners can restore the prior value, then drop
+ * the ledger entry. Does nothing if the transaction was never tracked.
+ */
+export declare function rollbackOptimistic(optimisticUpdates: Map<string, OptimisticUpdateEntry>, emitter: OptimisticEmitter, transaction: QueuedMutation, reason?: string, error?: Error): Promise<void>;

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

@@ -0,0 +1,75 @@
+/**
+ * Local-first apply and rollback bookkeeping for pending mutations.
+ *
+ * When a change is written before the server confirms it, these functions
+ * record it in a ledger and emit an `optimistic:*` event; separate listeners
+ * apply the change to the in-memory data and, on rollback, restore the value
+ * it replaced. Each function takes the ledger and a small event emitter rather
+ * than any larger object, so the rules have no dependencies of their own and
+ * can be tested in isolation.
+ */
+export function createLocalMutationPort(emitter) {
+    const updates = new Map();
+    return {
+        updates,
+        applyCreate: (model, transaction) => applyOptimisticCreate(updates, emitter, model, transaction),
+        applyUpdate: (model, transaction) => applyOptimisticUpdate(updates, emitter, model, transaction),
+        applyDelete: (model, transaction) => applyOptimisticDelete(updates, emitter, model, transaction),
+        rollback: (transaction, reason, error) => rollbackOptimistic(updates, emitter, transaction, reason, error),
+    };
+}
+/**
+ * Record an optimistic create and announce it. There is no prior value to
+ * restore, so the rollback pre-image is `null`.
+ */
+export function applyOptimisticCreate(optimisticUpdates, emitter, model, transaction) {
+    optimisticUpdates.set(transaction.id, {
+        model,
+        previousState: null,
+        transaction,
+    });
+    emitter.emit('optimistic:create', { model, transaction });
+}
+/**
+ * Record an optimistic update and announce it, keeping the row's prior value so
+ * a rollback can put it back.
+ */
+export function applyOptimisticUpdate(optimisticUpdates, emitter, model, transaction) {
+    optimisticUpdates.set(transaction.id, {
+        model,
+        previousState: transaction.previousData,
+        transaction,
+    });
+    emitter.emit('optimistic:update', { model, transaction });
+}
+/**
+ * Record an optimistic delete and announce it, keeping the deleted row so a
+ * rollback can restore it.
+ */
+export function applyOptimisticDelete(optimisticUpdates, emitter, model, transaction) {
+    optimisticUpdates.set(transaction.id, {
+        model,
+        previousState: transaction.previousData,
+        transaction,
+    });
+    emitter.emit('optimistic:delete', { model, transaction });
+}
+/**
+ * Undo an optimistic mutation by its transaction id: emit `optimistic:rollback`
+ * with the saved pre-image so listeners can restore the prior value, then drop
+ * the ledger entry. Does nothing if the transaction was never tracked.
+ */
+export function rollbackOptimistic(optimisticUpdates, emitter, transaction, reason, error) {
+    const optimistic = optimisticUpdates.get(transaction.id);
+    if (!optimistic)
+        return Promise.resolve();
+    emitter.emit('optimistic:rollback', {
+        model: optimistic.model,
+        previousState: optimistic.previousState,
+        transaction,
+        reason: reason ?? 'unknown',
+        error,
+    });
+    optimisticUpdates.delete(transaction.id);
+    return Promise.resolve();
+}

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

@@ -0,0 +1,44 @@
+import type { WriteOptions } from '../../interfaces/index.js';
+import type { LocalModel as Model } from '../../localModelContract.js';
+import type { QueuedMutation, UserContext, MutationInput } from './commitPayload.js';
+export interface ModelMutationContext {
+    readonly enableOptimistic: boolean;
+    readonly persistenceReady: boolean;
+    readonly assertDurableReplayOpen: () => void;
+    readonly generateId: () => string;
+    readonly normalizeModelKey: (modelName: string) => string;
+    readonly computePriorityScore: (type: QueuedMutation['type'], modelName: string) => number;
+    readonly extractCreateData: (model: Model) => Record<string, unknown>;
+    readonly extractUpdateData: (model: Model) => MutationInput;
+    readonly extractPreviousData: (model: Model, input: MutationInput) => Record<string, unknown> | null;
+    readonly mapChangesToInput: (modelName: string, changes: Record<string, unknown>) => MutationInput;
+    readonly isReorderPayload: (input: MutationInput) => boolean;
+    readonly attachConfirmation: (transaction: QueuedMutation) => void;
+    readonly add: (transaction: QueuedMutation) => void;
+    readonly applyOptimisticCreate: (model: Model, transaction: QueuedMutation) => void;
+    readonly applyOptimisticUpdate: (model: Model, transaction: QueuedMutation) => void;
+    readonly applyOptimisticDelete: (model: Model, transaction: QueuedMutation) => void;
+    readonly takeUnsentCreateForModel: (modelName: string, modelId: string) => QueuedMutation | undefined;
+    readonly cancelUnsentCreateForDelete: (transaction: QueuedMutation) => Promise<void>;
+    readonly completeLocalDelete: (model: Model, context: UserContext, writeOptions?: WriteOptions, sourceMutationIds?: string[]) => QueuedMutation | Promise<QueuedMutation>;
+    readonly cancelTransactionsForModel: (modelId: string, type: 'update') => QueuedMutation[];
+    readonly pendingMergeByModel: Map<string, {
+        data: MutationInput;
+        sourceMutationIds: string[];
+    }>;
+    readonly inFlightByModel: Set<string>;
+    readonly findCreateBarrierForDelete: (modelName: string, modelId: string) => QueuedMutation | undefined;
+    readonly deferDeleteUntilCreateSettles: (create: QueuedMutation, transaction: QueuedMutation) => void;
+    readonly logger: {
+        debug: (message: string, fields?: Record<string, string>) => void;
+    };
+    readonly persistAndStage: (transaction: QueuedMutation, modelData: Record<string, unknown>) => Promise<void>;
+    readonly persistQueuedTransaction: (transaction: QueuedMutation, modelData: Record<string, unknown>) => Promise<void>;
+    readonly stageTransaction: (transaction: QueuedMutation) => void;
+    readonly emit: (event: string, payload: object) => void;
+}
+export declare function remove(ctx: ModelMutationContext, model: Model, context: UserContext, writeOptions?: WriteOptions, sourceMutationId?: string): Promise<QueuedMutation>;
+export declare function create(ctx: ModelMutationContext, model: Model, context: UserContext, writeOptions?: WriteOptions, sourceMutationId?: string): Promise<QueuedMutation> | QueuedMutation;
+export declare function update(ctx: ModelMutationContext, model: Model, context: UserContext, precomputedChanges?: Record<string, unknown>, writeOptions?: WriteOptions, sourceMutationId?: string): Promise<QueuedMutation> | QueuedMutation;
+export declare function archive(ctx: ModelMutationContext, model: Model, context: UserContext, writeOptions?: WriteOptions, sourceMutationId?: string): Promise<QueuedMutation> | QueuedMutation;
+export declare function unarchive(ctx: ModelMutationContext, model: Model, context: UserContext): Promise<QueuedMutation> | QueuedMutation;