@abloatai/humans 0.56.0 → 0.57.0

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

@@ -18,14 +18,9 @@ import type { LocalModel } from '../../localModelContract.js';
 import type { MutationPersistencePort } from '../../mutationPersistence.js';
 import { globalRuntime } from '../../context.js';
 import type { RuntimeContext } from '../../RuntimeContext.js';
-import type { MutationOperationType } from '@abloatai/transaction/types';
 import {
-  AbloError,
   AbloConnectionError,
   AbloIdempotencyError,
-  AbloNotFoundError,
-  AbloValidationError,
-  errorCodeSpec,
 } from '@abloatai/transaction/errors';
 import {
   LogPosition,
@@ -34,28 +29,28 @@ import {
 import type { WriteOptions } from '../../interfaces/index.js';
 import type { OnStaleMode, StaleNotification, ReadDependency, TrackDependency } from '@abloatai/transaction/coordination/schema';
 import {
-  mutationCommitResultSchema,
+  type CommitOperationResult,
   type MutationCommitResult,
 } from '@abloatai/transaction/wire/commit';
 import {
-  projectCommitPayload,
   computePriorityScore,
   normalizeModelKey,
   // Includes stale guards as well as request identity/audit barriers.
-  hasCommitCoalescingBarrier,
-  applyWriteOptions,
-  asTransportError,
-  extractStatusCode,
-  TX_TYPE_TO_MUTATION_OP,
   type MutationInput,
   type QueuedMutation,
   type UserContext,
-  type WriteOperationFields,
 } from './commitPayload.js';
+import {
+  generateTransactionId,
+  mergeMutationData,
+  createDataFor,
+  changesToInput,
+  updateDataFor,
+  previousDataFor,
+} from './mutationInput.js';
 import { MutationStore } from './MutationStore.js';
 import {
   entityKey,
-  mergeUpdateData,
   takeUnsentCreateForModel,
   findCreateBarrierForDelete,
   deferDeleteUntilCreateSettles,
@@ -66,9 +61,6 @@ import {
   deserializePersistedTransaction,
   isNonReplayablePersistedRow,
   pendingMutationRecordId,
-  legacyPendingMutationRecordSchema,
-  pendingMutationRecordSchema,
-  persistedMutationSchema,
 } from './replayValidation.js';
 import {
   deserializeLegacyPendingMutation,
@@ -80,12 +72,7 @@ import {
 } from './mutationPersistence.js';
 import {
   createCommitEnvelopeMember,
-  createDurableCommitEnvelope,
-  commitEnvelopeRecordId,
-  durableCommitEnvelopeSchema,
   type DurableCommitEnvelope,
-  type DurableCommitOperation,
-  type DurableCommitOperationInput,
   type CommitOutboxScope,
 } from '@abloatai/transaction/transactions/confirmation/commitEnvelope';
 import type { DurableWriteStore } from './durableWriteStore.js';
@@ -101,7 +88,6 @@ import {
   removeDurableCommit,
   sealDurableCommit,
   type CommitTransportContext,
-  type SealDurableCommitInput,
 } from './commitTransport.js';
 import {
   processCommitLane,
@@ -245,18 +231,18 @@ export class MutationQueue extends EventEmitter {
   private readonly runtime: RuntimeContext;
   /** Durable transaction journal owned by this queue, before commit sealing. */
   private persistence: MutationPersistencePort | null = null;
-  private deferredMutations: Array<{
+  private deferredMutations: {
     type: 'create' | 'update' | 'delete' | 'archive';
     model: LocalModel;
     capturedChanges?: Record<string, unknown>;
     writeOptions?: WriteOptions;
-  }> = [];
-  private pendingPersistenceStages: Array<{
+  }[] = [];
+  private pendingPersistenceStages: {
     transaction: QueuedMutation;
     modelData: Record<string, unknown>;
     resolve: () => void;
     reject: (error: Error) => void;
-  }> = [];
+  }[] = [];
   private persistenceStageScheduled = false;
   private pendingDrainPromise: Promise<void> | null = null;
 
@@ -315,7 +301,7 @@ export class MutationQueue extends EventEmitter {
       commitOutbox: this.commitOutbox,
       commitOutboxScope: this.commitOutboxScope,
       mutationExecutor: this.mutationExecutor,
-      emitCommitLifecycle: (event, payload) => this.emitCommitLifecycle(event, payload),
+      emitCommitLifecycle: (event, payload) => { this.emitCommitLifecycle(event, payload); },
     };
   }
 
@@ -334,7 +320,7 @@ export class MutationQueue extends EventEmitter {
       setCommitProcessing: (value) => { this.commitProcessing = value; },
       durableReplayBlock: this.durableReplayBlock,
       sealDurableCommit: (input) => this.sealDurableCommit(input),
-      assertEnvelopeInsideReplayWindow: (envelope) => this.assertEnvelopeInsideReplayWindow(envelope),
+      assertEnvelopeInsideReplayWindow: (envelope) => { this.assertEnvelopeInsideReplayWindow(envelope); },
       dispatchCommit: async (envelope) => this.parseMutationCommitResult(
         await this.dispatchCommitBounded(envelope.operations, {
           idempotencyKey: envelope.idempotencyKey,
@@ -345,9 +331,9 @@ export class MutationQueue extends EventEmitter {
       persistDurableCommitAcceptance: (envelope, result) => this.persistDurableCommitAcceptance(envelope, result),
       removeDurableCommit: (idempotencyKey) => this.removeDurableCommit(idempotencyKey),
       queuedCommitEchoSyncId: (transaction) => this.queuedCommitEchoSyncId(transaction),
-      completeQueuedCommit: (transaction, syncId) => this.completeQueuedCommit(transaction, syncId),
-      scheduleReplicationLagTimeout: (transactionId, clientTxId, correlationId) => this.scheduleReplicationLagTimeout(transactionId, clientTxId, correlationId),
-      noteAck: (syncId) => this.noteAck(syncId),
+      completeQueuedCommit: (transaction, syncId) => { this.completeQueuedCommit(transaction, syncId); },
+      scheduleReplicationLagTimeout: (transactionId, clientTxId, correlationId) => { this.scheduleReplicationLagTimeout(transactionId, clientTxId, correlationId); },
+      noteAck: (syncId) => { this.noteAck(syncId); },
       isDefinitiveRejection: (error) => this.isDefinitiveRejection(error),
       isPermanentError: (error) => this.isPermanentError(error),
       scheduleRetry: (delayMs) => {
@@ -357,7 +343,7 @@ export class MutationQueue extends EventEmitter {
           void this.processCommitLane();
         }, delayMs);
       },
-      emitCommitLifecycle: (event, payload) => this.emitCommitLifecycle(event, payload),
+      emitCommitLifecycle: (event, payload) => { this.emitCommitLifecycle(event, payload); },
     };
   }
 
@@ -374,15 +360,15 @@ export class MutationQueue extends EventEmitter {
 
   private get commitApiContext(): CommitApiContext {
     return {
-      assertDurableReplayOpen: () => this.assertDurableReplayOpen(),
+      assertDurableReplayOpen: () => { this.assertDurableReplayOpen(); },
       commitStore: this.commitStore,
       commitLane: this.commitLane,
       replicationLagErrors: this.replicationLagErrors,
-      clearReplicationLagState: (transactionId) => this.clearReplicationLagState(transactionId),
+      clearReplicationLagState: (transactionId) => { this.clearReplicationLagState(transactionId); },
       nextCommitSequence: () => this.nextCommitSequence(),
       sealDurableCommit: (input) => this.sealDurableCommit(input),
       processCommitLane: () => this.processCommitLane(),
-      emitCommitLifecycle: (event, payload) => this.emitCommitLifecycle(event, payload),
+      emitCommitLifecycle: (event, payload) => { this.emitCommitLifecycle(event, payload); },
     };
   }
 
@@ -390,7 +376,7 @@ export class MutationQueue extends EventEmitter {
     return {
       enableOptimistic: this.config.enableOptimistic,
       persistenceReady: !!this.persistence && !!this.commitOutboxScope,
-      assertDurableReplayOpen: () => this.assertDurableReplayOpen(),
+      assertDurableReplayOpen: () => { this.assertDurableReplayOpen(); },
       generateId: () => this.generateId(),
       normalizeModelKey,
       computePriorityScore: (type, modelName) => this.computePriorityScore(type, modelName),
@@ -399,11 +385,11 @@ export class MutationQueue extends EventEmitter {
       extractPreviousData: (model, input) => this.extractPreviousData(model, input),
       mapChangesToInput: (modelName, changes) => this.mapChangesToInput(modelName, changes),
       isReorderPayload: (input) => this.isReorderPayload(input),
-      attachConfirmation: (transaction) => this.attachConfirmation(transaction),
-      add: (transaction) => this.store.add(transaction),
-      applyOptimisticCreate: (model, transaction) => this.applyOptimisticCreate(model, transaction),
-      applyOptimisticUpdate: (model, transaction) => this.applyOptimisticUpdate(model, transaction),
-      applyOptimisticDelete: (model, transaction) => this.applyOptimisticDelete(model, transaction),
+      attachConfirmation: (transaction) => { this.attachConfirmation(transaction); },
+      add: (transaction) => { this.store.add(transaction); },
+      applyOptimisticCreate: (model, transaction) => { this.applyOptimisticCreate(model, transaction); },
+      applyOptimisticUpdate: (model, transaction) => { this.applyOptimisticUpdate(model, transaction); },
+      applyOptimisticDelete: (model, transaction) => { this.applyOptimisticDelete(model, transaction); },
       takeUnsentCreateForModel: (modelName, modelId) => this.takeUnsentCreateForModel(modelName, modelId),
       cancelUnsentCreateForDelete: (transaction) => this.cancelUnsentCreateForDelete(transaction),
       completeLocalDelete: (model, context, writeOptions, sourceMutationIds) => this.completeLocalDelete(model, context, writeOptions, sourceMutationIds),
@@ -411,11 +397,11 @@ export class MutationQueue extends EventEmitter {
       pendingMergeByModel: this.pendingMergeByModel,
       inFlightByModel: this.inFlightByModel,
       findCreateBarrierForDelete: (modelName, modelId) => this.findCreateBarrierForDelete(modelName, modelId),
-      deferDeleteUntilCreateSettles: (create, transaction) => this.deferDeleteUntilCreateSettles(create, transaction),
+      deferDeleteUntilCreateSettles: (create, transaction) => { this.deferDeleteUntilCreateSettles(create, transaction); },
       logger: this.runtime.logger,
       persistAndStage: (transaction, modelData) => this.persistAndStage(transaction, modelData),
       persistQueuedTransaction: (transaction, modelData) => this.persistQueuedTransaction(transaction, modelData),
-      stageTransaction: (transaction) => this.stageTransaction(transaction),
+      stageTransaction: (transaction) => { this.stageTransaction(transaction); },
       emit: (event, payload) => this.emit(event, payload),
     };
   }
@@ -425,9 +411,9 @@ export class MutationQueue extends EventEmitter {
       executionQueue: this.executionQueue,
       inFlightByModel: this.inFlightByModel,
       pendingMergeByModel: this.pendingMergeByModel,
-      ensureDerivedFields: (transaction) => this.ensureDerivedFields(transaction),
-      scheduleProcessing: (immediate) => this.scheduleProcessing(immediate),
-      storeRemove: (transactionId) => this.store.remove(transactionId),
+      ensureDerivedFields: (transaction) => { this.ensureDerivedFields(transaction); },
+      scheduleProcessing: (immediate) => { this.scheduleProcessing(immediate); },
+      storeRemove: (transactionId) => { this.store.remove(transactionId); },
     };
   }
 
@@ -440,7 +426,7 @@ export class MutationQueue extends EventEmitter {
       isProcessing: this.isProcessing,
       setIsProcessing: (value) => { this.isProcessing = value; },
       takeNextExecutionBatch: () => this.takeNextExecutionBatch(),
-      ensureDerivedFields: (transaction) => this.ensureDerivedFields(transaction),
+      ensureDerivedFields: (transaction) => { this.ensureDerivedFields(transaction); },
       ensureCommitEnvelope: (batch) => this.ensureCommitEnvelope([...batch]),
       executingCount: this.executingCount,
       setExecutingCount: (value) => { this.executingCount = value; },
@@ -449,7 +435,7 @@ export class MutationQueue extends EventEmitter {
       generateId: () => this.generateId(),
       computePriorityScore: (type, modelName) => this.computePriorityScore(type, modelName),
       store: this.store,
-      enqueue: (transaction) => this.enqueue(transaction),
+      enqueue: (transaction) => { this.enqueue(transaction); },
       optimisticUpdates: this.localMutationPort.updates,
       commitNotifications: this.commitNotifications,
       commitMissingIds: this.commitMissingIds,
@@ -458,22 +444,22 @@ export class MutationQueue extends EventEmitter {
       parseMutationCommitResult: (value) => this.parseMutationCommitResult(value),
       persistDurableCommitAcceptance: (envelope, result) => this.persistDurableCommitAcceptance(envelope, result),
       removeDurableCommit: (idempotencyKey) => this.removeDurableCommit(idempotencyKey),
-      assertEnvelopeInsideReplayWindow: (envelope) => this.assertEnvelopeInsideReplayWindow(envelope),
+      assertEnvelopeInsideReplayWindow: (envelope) => { this.assertEnvelopeInsideReplayWindow(envelope); },
       sealDurableCommit: (input) => this.sealDurableCommit(input),
-      noteAck: (syncId) => this.noteAck(syncId),
+      noteAck: (syncId) => { this.noteAck(syncId); },
       classifyReceiptNotifications: (operations, notifications) => this.classifyReceiptNotifications(operations, notifications),
       receiptTargetKey: (modelName, modelId) => this.receiptTargetKey(modelName, modelId),
-      scheduleReplicationLagTimeout: (transactionId, clientTxId, correlationId) => this.scheduleReplicationLagTimeout(transactionId, clientTxId, correlationId),
-      scheduleDeltaConfirmationTimeout: (transaction, timeoutMs) => this.scheduleDeltaConfirmationTimeout(transaction, timeoutMs),
-      clearReplicationLagState: (transactionId) => this.clearReplicationLagState(transactionId),
-      completeQueuedCommit: (transaction, syncId) => this.completeQueuedCommit(transaction, syncId),
+      scheduleReplicationLagTimeout: (transactionId, clientTxId, correlationId) => { this.scheduleReplicationLagTimeout(transactionId, clientTxId, correlationId); },
+      scheduleDeltaConfirmationTimeout: (transaction, timeoutMs) => { this.scheduleDeltaConfirmationTimeout(transaction, timeoutMs); },
+      clearReplicationLagState: (transactionId) => { this.clearReplicationLagState(transactionId); },
+      completeQueuedCommit: (transaction, syncId) => { this.completeQueuedCommit(transaction, syncId); },
       queuedCommitMatchesCorrelation: (transaction, correlationId) => this.queuedCommitMatchesCorrelation(transaction, correlationId),
       recentDeltaCorrelations: this.recentDeltaCorrelations,
       lastSeenSyncId: this.lastSeenSyncId,
-      scheduleProcessing: (immediate) => this.scheduleProcessing(immediate),
+      scheduleProcessing: (immediate) => { this.scheduleProcessing(immediate); },
       handleFailure: (transaction, error) => this.handleFailure(transaction, error),
       isDefinitiveRejection: (error) => this.isDefinitiveRejection(error),
-      emitCommitLifecycle: (event, payload) => this.emitCommitLifecycle(event, payload),
+      emitCommitLifecycle: (event, payload) => { this.emitCommitLifecycle(event, payload); },
       emit: (event, payload) => this.emit(event, payload),
       rollbackOptimistic: (transaction, reason, error) => this.rollbackOptimistic(transaction, reason, error),
     };
@@ -486,7 +472,7 @@ export class MutationQueue extends EventEmitter {
       store: this.store,
       isPermanentError: (error) => this.isPermanentError(error),
       rollbackOptimistic: (transaction, reason, error) => this.rollbackOptimistic(transaction, reason, error),
-      enqueue: (transaction) => this.enqueue(transaction),
+      enqueue: (transaction) => { this.enqueue(transaction); },
       getLastPermanentErrorSignature: () => this.lastPermanentErrorSig,
       setLastPermanentErrorSignature: (signature) => { this.lastPermanentErrorSig = signature; },
       emit: (event, payload) => this.emit(event, payload),
@@ -499,7 +485,7 @@ export class MutationQueue extends EventEmitter {
       store: this.store,
       rollbackOptimistic: (transaction, reason) => this.rollbackOptimistic(transaction, reason),
       mergeData: (local, remote) => this.mergeData(local, remote),
-      enqueue: (transaction) => this.enqueue(transaction),
+      enqueue: (transaction) => { this.enqueue(transaction); },
     };
   }
 
@@ -524,21 +510,21 @@ export class MutationQueue extends EventEmitter {
       store: this.store,
       executionQueue: this.executionQueue,
       optimisticUpdates: this.localMutationPort.updates,
-      assertDurableReplayOpen: () => this.assertDurableReplayOpen(),
+      assertDurableReplayOpen: () => { this.assertDurableReplayOpen(); },
       processCommitLane: () => this.processCommitLane(),
       takePendingDrainBatch: (pending) => this.takePendingDrainBatch(pending),
       ensureCommitEnvelope: (batch) => this.ensureCommitEnvelope(batch),
-      ensureDerivedFields: (transaction) => this.ensureDerivedFields(transaction),
+      ensureDerivedFields: (transaction) => { this.ensureDerivedFields(transaction); },
       sourceMutationIdsFor: (batch) => this.sourceMutationIdsFor(batch),
       sealDurableCommit: (input) => this.sealDurableCommit(input),
-      assertEnvelopeInsideReplayWindow: (envelope) => this.assertEnvelopeInsideReplayWindow(envelope),
+      assertEnvelopeInsideReplayWindow: (envelope) => { this.assertEnvelopeInsideReplayWindow(envelope); },
       parseMutationCommitResult: (value) => this.parseMutationCommitResult(value),
       dispatchCommitBounded: (...args) => this.dispatchCommitBounded(...args),
       persistDurableCommitAcceptance: (envelope, result) => this.persistDurableCommitAcceptance(envelope, result),
       removeDurableCommit: (idempotencyKey) => this.removeDurableCommit(idempotencyKey),
-      scheduleReplicationLagTimeout: (transactionId, clientTxId, correlationId) => this.scheduleReplicationLagTimeout(transactionId, clientTxId, correlationId),
-      scheduleDeltaConfirmationTimeout: (transaction, timeoutMs) => this.scheduleDeltaConfirmationTimeout(transaction, timeoutMs),
-      enqueue: (transaction) => this.enqueue(transaction),
+      scheduleReplicationLagTimeout: (transactionId, clientTxId, correlationId) => { this.scheduleReplicationLagTimeout(transactionId, clientTxId, correlationId); },
+      scheduleDeltaConfirmationTimeout: (transaction, timeoutMs) => { this.scheduleDeltaConfirmationTimeout(transaction, timeoutMs); },
+      enqueue: (transaction) => { this.enqueue(transaction); },
       recentDeltaCorrelations: this.recentDeltaCorrelations,
       emit: (event, payload) => this.emit(event, payload),
     };
@@ -564,7 +550,7 @@ export class MutationQueue extends EventEmitter {
       commitOutboxScope: this.commitOutboxScope,
       config: this.config,
       store: this.store,
-      enqueue: (transaction) => this.enqueue(transaction),
+      enqueue: (transaction) => { this.enqueue(transaction); },
       computePriorityScore: (type, modelName) => this.computePriorityScore(type, modelName),
       deserializeTransaction: (data) => this.deserializeTransaction(data),
     };
@@ -1703,6 +1689,7 @@ export class MutationQueue extends EventEmitter {
     lastSyncId: number;
     notifications?: StaleNotification[];
     missingIds?: string[];
+    operationResults?: CommitOperationResult[];
   }> {
     return waitForCommitReceipt(this.commitReceiptContext, clientTxId);
   }
@@ -1879,47 +1866,33 @@ export class MutationQueue extends EventEmitter {
   }
 
   /** Generates a unique local transaction id. */
+  // The payload rules live in `mutationInput`; these keep the call sites here
+  // reading as the queue's own vocabulary.
   private generateId(): string {
-    return `tx_${Date.now()}_${Math.random().toString(36).substring(2, 11)}`;
+    return generateTransactionId();
   }
 
   private mergeData(
     local: MutationInput | undefined,
     remote: MutationInput | undefined
   ): MutationInput {
-    return { ...(remote || {}), ...(local || {}) };
+    return mergeMutationData(local, remote);
   }
 
   private extractCreateData(model: LocalModel): MutationInput {
-    return projectCommitPayload(model.getModelName(), model.toJSON(), { dropUndefined: false }, this.runtime);
+    return createDataFor(model, this.runtime);
   }
 
   private mapChangesToInput(modelName: string, changes: Record<string, unknown>): MutationInput {
-    return projectCommitPayload(modelName, changes, { dropUndefined: true }, this.runtime);
+    return changesToInput(modelName, changes, this.runtime);
   }
 
   private extractUpdateData(model: LocalModel): MutationInput {
-    return projectCommitPayload(model.getModelName(), model.getChanges(), { dropUndefined: true }, this.runtime);
+    return updateDataFor(model, this.runtime);
   }
 
-  // Derive previous values for changed fields to support accurate rollback.
-  // Model-specific special cases do not belong here; a model that needs to
-  // surface previous state beyond `modifiedProperties` should expose a typed
-  // `getPreviousData()` accessor for this method to call.
   private extractPreviousData(model: LocalModel, updateInput?: MutationInput): MutationInput {
-    // When the update's written keys are known, capture a before-image for
-    // exactly those keys, so the recorded undo inverse reverts them and nothing
-    // else — a full-row inverse would clobber concurrent edits to unrelated
-    // fields. `fallbackToLive: false` makes `Model.capturePreviousValues` omit
-    // any key it cannot resolve, and `buildUndoOps` then drops an un-revertible
-    // inverse rather than inventing one. With no `updateInput` (a full extract)
-    // it falls back to every tracked field. `Model.capturePreviousValues` is the
-    // single before-image source, shared with
-    // `RecordingMutation.snapshotFields`.
-    const keys = updateInput
-      ? Object.keys(updateInput)
-      : [...(model.modifiedProperties instanceof Map ? model.modifiedProperties.keys() : [])];
-    return { id: model.id, ...model.capturePreviousValues(keys, { fallbackToLive: false }) };
+    return previousDataFor(model, updateInput);
   }
 
   /** Returns a snapshot of queue counts and the current configuration. */

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

@@ -1,6 +1,9 @@
 import type { RuntimeContext } from '../../RuntimeContext.js';
 import type { ReadDependency, TrackDependency, OnStaleMode, StaleNotification } from '@abloatai/transaction/coordination/schema';
-import type { MutationCommitResult } from '@abloatai/transaction/wire/commit';
+import type {
+  CommitOperationResult,
+  MutationCommitResult,
+} from '@abloatai/transaction/wire/commit';
 import type {
   DurableCommitEnvelope,
   DurableCommitOperation,
@@ -28,6 +31,8 @@ export interface CommitTransaction {
   transientAttempts?: number;
   firstTransientFailureAt?: number;
   lastSyncId?: number;
+  /** Fresh transport rows. Deliberately transient: durable server replays redact row data. */
+  operationResults?: CommitOperationResult[];
   correlationId?: string;
   error?: Error;
   sealedAt: number;
@@ -77,7 +82,12 @@ export interface CommitReceiptContext {
 export function waitForCommitReceipt(
   ctx: CommitReceiptContext,
   clientTxId: string,
-): Promise<{ lastSyncId: number; notifications?: StaleNotification[]; missingIds?: string[] }> {
+): Promise<{
+  lastSyncId: number;
+  notifications?: StaleNotification[];
+  missingIds?: string[];
+  operationResults?: CommitOperationResult[];
+}> {
   const drainNotifications = (): StaleNotification[] | undefined => {
     const notifications = ctx.commitNotifications.get(clientTxId);
     if (!notifications) return undefined;
@@ -90,21 +100,28 @@ export function waitForCommitReceipt(
     ctx.commitMissingIds.delete(clientTxId);
     return ids.length > 0 ? ids : undefined;
   };
-  const receipt = (lastSyncId: number) => {
+  const receipt = (transaction: CommitTransaction, lastSyncId: number) => {
     const missingIds = drainMissingIds();
     return {
       lastSyncId,
       notifications: drainNotifications(),
+      ...(transaction.operationResults
+        ? { operationResults: transaction.operationResults }
+        : {}),
       ...(missingIds ? { missingIds } : {}),
     };
   };
   return new Promise((resolve, reject) => {
     const existing = ctx.commitStore.get(clientTxId);
-    if (existing?.status === 'completed') { resolve(receipt(existing.lastSyncId ?? 0)); return; }
+    if (existing?.status === 'completed') { resolve(receipt(existing, existing.lastSyncId ?? 0)); return; }
     if (existing?.status === 'failed' && existing.error) { reject(existing.error); return; }
     const lagError = ctx.replicationLagErrors.get(clientTxId);
     if (lagError) { reject(lagError); return; }
-    const onCompleted = (tx: object) => { cleanup(); resolve(receipt((tx as CommitTransaction).lastSyncId ?? 0)); };
+    const onCompleted = (tx: object) => {
+      cleanup();
+      const completed = tx as CommitTransaction;
+      resolve(receipt(completed, completed.lastSyncId ?? 0));
+    };
     const onFailed = (payload: object) => { cleanup(); reject((payload as { error: Error }).error); };
     const onLagged = (payload: object) => { cleanup(); reject((payload as { error: Error }).error); };
     const cleanup = () => {
@@ -152,6 +169,7 @@ export async function processCommitLane(ctx: CommitLaneContext): Promise<void> {
         const result = await ctx.dispatchCommit(durableEnvelope);
         tx.durableEnvelope = await ctx.persistDurableCommitAcceptance(durableEnvelope, result);
         tx.lastSyncId = result.lastSyncId;
+        if (result.operationResults?.length) tx.operationResults = [...result.operationResults];
         if (result.notifications?.length) ctx.commitNotifications.set(tx.id, result.notifications);
         if (result.missingIds?.length) ctx.commitMissingIds.set(tx.id, result.missingIds);
         ctx.commitLane.shift();

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

@@ -0,0 +1,69 @@
+/**
+ * The input a queued mutation carries, derived from a local model.
+ *
+ * Six small rules that answer one question: given a model and what changed on
+ * it, what does the commit actually send? They sat as private methods on
+ * `MutationQueue` because that is where they were called, which is how a queue
+ * ends up also owning the payload vocabulary.
+ *
+ * The before-image rule is the one worth reading twice, and it is stated in
+ * `previousDataFor` rather than here.
+ */
+
+import type { LocalModel } from '../../localModelContract.js';
+import type { RuntimeContext } from '../../RuntimeContext.js';
+import { projectCommitPayload, type MutationInput } from './commitPayload.js';
+
+/** A queued transaction's local identity, unique per process and monotonic enough to sort. */
+export function generateTransactionId(): string {
+  return `tx_${Date.now()}_${Math.random().toString(36).substring(2, 11)}`;
+}
+
+/** Local values win: they are the edit the caller made, remote is the base. */
+export function mergeMutationData(
+  local: MutationInput | undefined,
+  remote: MutationInput | undefined,
+): MutationInput {
+  return { ...(remote ?? {}), ...(local ?? {}) };
+}
+
+/** A create sends the whole row, `undefined` included, so absence is explicit. */
+export function createDataFor(model: LocalModel, runtime?: RuntimeContext): MutationInput {
+  return projectCommitPayload(model.getModelName(), model.toJSON(), { dropUndefined: false }, runtime);
+}
+
+/** An arbitrary change set, projected the way an update is. */
+export function changesToInput(
+  modelName: string,
+  changes: Record<string, unknown>,
+  runtime?: RuntimeContext,
+): MutationInput {
+  return projectCommitPayload(modelName, changes, { dropUndefined: true }, runtime);
+}
+
+/** An update sends only what changed. */
+export function updateDataFor(model: LocalModel, runtime?: RuntimeContext): MutationInput {
+  return projectCommitPayload(model.getModelName(), model.getChanges(), { dropUndefined: true }, runtime);
+}
+
+/**
+ * The before-image an undo reverts to.
+ *
+ * When the update's written keys are known, capture a before-image for exactly
+ * those keys, so the recorded undo inverse reverts them and nothing else — a
+ * full-row inverse would clobber concurrent edits to unrelated fields.
+ * `fallbackToLive: false` makes `Model.capturePreviousValues` omit any key it
+ * cannot resolve, and `buildUndoOps` then drops an un-revertible inverse rather
+ * than inventing one. With no `updateInput` (a full extract) it falls back to
+ * every tracked field.
+ *
+ * Model-specific special cases do not belong here: a model that needs to
+ * surface previous state beyond `modifiedProperties` should expose a typed
+ * `getPreviousData()` accessor for this to call.
+ */
+export function previousDataFor(model: LocalModel, updateInput?: MutationInput): MutationInput {
+  const keys = updateInput
+    ? Object.keys(updateInput)
+    : [...(model.modifiedProperties instanceof Map ? model.modifiedProperties.keys() : [])];
+  return { id: model.id, ...model.capturePreviousValues(keys, { fallbackToLive: false }) };
+}

package/src/surface.ts

@@ -35,6 +35,7 @@ export const PUBLIC_MODEL_VERBS = [
   'get',
   'retrieve',
   'list',
+  'listAll',
   'local',
   'create',
   'update',