@abloatai/humans 0.37.0

package/src/local/transactions/mutations/failurePolicy.ts

@@ -0,0 +1,61 @@
+import type { MutationInput, QueuedMutation } from './commitPayload.js';
+import { asTransportError, extractStatusCode } from './commitPayload.js';
+import { mergeUpdateData } from './coalesceRules.js';
+import { AbloConnectionError, errorCodeSpec } from '@abloatai/transaction/errors';
+import type { MutationQueueConfig } from './MutationQueue.js';
+import type { MutationStore } from './MutationStore.js';
+
+export function isPermanentError(error: Error): boolean {
+  if (error instanceof AbloConnectionError) return false;
+  const code = (error as { code?: string }).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: Error): boolean {
+  const code = (error as { code?: string }).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 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 async function handleConflict(
+  ctx: ConflictPolicyContext,
+  transaction: QueuedMutation,
+  serverData: MutationInput,
+): Promise<void> {
+  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/src/local/transactions/mutations/localMutation.ts

@@ -0,0 +1,135 @@
+/**
+ * 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 function createLocalMutationPort(emitter: OptimisticEmitter): LocalMutationPort {
+  const updates = new Map<string, OptimisticUpdateEntry>();
+  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: Map<string, OptimisticUpdateEntry>,
+  emitter: OptimisticEmitter,
+  model: Model,
+  transaction: QueuedMutation,
+): void {
+  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: Map<string, OptimisticUpdateEntry>,
+  emitter: OptimisticEmitter,
+  model: Model,
+  transaction: QueuedMutation,
+): void {
+  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: Map<string, OptimisticUpdateEntry>,
+  emitter: OptimisticEmitter,
+  model: Model,
+  transaction: QueuedMutation,
+): void {
+  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: Map<string, OptimisticUpdateEntry>,
+  emitter: OptimisticEmitter,
+  transaction: QueuedMutation,
+  reason?: string,
+  error?: Error,
+): Promise<void> {
+  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/src/local/transactions/mutations/modelOperations.ts

@@ -0,0 +1,210 @@
+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 async function remove(
+  ctx: ModelMutationContext,
+  model: Model,
+  context: UserContext,
+  writeOptions?: WriteOptions,
+  sourceMutationId?: string,
+): Promise<QueuedMutation> {
+  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: QueuedMutation = {
+      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: QueuedMutation = {
+    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: ModelMutationContext, transaction: QueuedMutation, model: Model): Promise<void> | void {
+  return ctx.persistenceReady
+    ? ctx.persistAndStage(transaction, model.toJSON())
+    : ctx.stageTransaction(transaction);
+}
+
+export function create(
+  ctx: ModelMutationContext,
+  model: Model,
+  context: UserContext,
+  writeOptions?: WriteOptions,
+  sourceMutationId?: string,
+): Promise<QueuedMutation> | QueuedMutation {
+  ctx.assertDurableReplayOpen();
+  const modelName = model.getModelName();
+  const transaction: QueuedMutation = {
+    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: ModelMutationContext,
+  model: Model,
+  context: UserContext,
+  precomputedChanges?: Record<string, unknown>,
+  writeOptions?: WriteOptions,
+  sourceMutationId?: string,
+): Promise<QueuedMutation> | QueuedMutation {
+  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: QueuedMutation = {
+    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: ModelMutationContext,
+  model: Model,
+  context: UserContext,
+  writeOptions?: WriteOptions,
+  sourceMutationId?: string,
+): Promise<QueuedMutation> | QueuedMutation {
+  return simpleStatusMutation(ctx, 'archive', model, context, writeOptions, sourceMutationId);
+}
+
+export function unarchive(
+  ctx: ModelMutationContext,
+  model: Model,
+  context: UserContext,
+): Promise<QueuedMutation> | QueuedMutation {
+  return simpleStatusMutation(ctx, 'unarchive', model, context);
+}
+
+function simpleStatusMutation(
+  ctx: ModelMutationContext,
+  type: 'archive' | 'unarchive',
+  model: Model,
+  context: UserContext,
+  writeOptions?: WriteOptions,
+  sourceMutationId?: string,
+): Promise<QueuedMutation> | QueuedMutation {
+  ctx.assertDurableReplayOpen();
+  const modelName = model.getModelName();
+  const transaction: QueuedMutation = {
+    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/src/local/transactions/mutations/mutationPersistence.ts

@@ -0,0 +1,231 @@
+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 { normalizeModelKey } from './commitPayload.js';
+import {
+  deserializePersistedTransaction,
+  legacyPendingMutationRecordSchema,
+  pendingMutationRecordId,
+  pendingMutationRecordSchema,
+  persistedMutationSchema,
+} 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 async function persistQueuedTransaction(
+    ctx: MutationPersistenceContext,
+    transaction: QueuedMutation,
+    modelData?: Record<string, unknown>,
+  ): Promise<void> {
+    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: MutationPersistenceContext, transactionId: string): void {
+    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: MutationPersistenceContext, transaction: { id?: string; sourceMutationIds?: string[] }): void {
+    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: MutationPersistenceContext,
+    row: object,
+    fallbackMutationId?: string,
+  ): QueuedMutation | null {
+    const rowType = (row as { type?: string }).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: MutationPersistenceContext,
+    persistence: MutationPersistencePort,
+    sealedMutationIds: ReadonlySet<string> = new Set(),
+  ): Promise<void> {
+    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),
+      });
+    }
+  }