@abloatai/humans 0.55.0 → 0.57.0

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

@@ -14,18 +14,17 @@
 import { EventEmitter } from 'events';
 import { v4 as uuid } from 'uuid';
 import { globalRuntime } from '../../context.js';
-import { AbloError, AbloConnectionError, AbloIdempotencyError, AbloNotFoundError, AbloValidationError, errorCodeSpec, } from '@abloatai/transaction/errors';
+import { AbloConnectionError, AbloIdempotencyError, } from '@abloatai/transaction/errors';
 import { LogPosition, } from '../../logPosition.js';
-import { mutationCommitResultSchema, } 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, } from './commitPayload.js';
+import {} from '@abloatai/transaction/wire/commit';
+import { computePriorityScore, normalizeModelKey, } from './commitPayload.js';
+import { generateTransactionId, mergeMutationData, createDataFor, changesToInput, updateDataFor, previousDataFor, } from './mutationInput.js';
 import { MutationStore } from './MutationStore.js';
-import { entityKey, mergeUpdateData, takeUnsentCreateForModel, findCreateBarrierForDelete, deferDeleteUntilCreateSettles, releaseDeferredDeletesForCreate, } from './coalesceRules.js';
+import { entityKey, takeUnsentCreateForModel, findCreateBarrierForDelete, deferDeleteUntilCreateSettles, releaseDeferredDeletesForCreate, } from './coalesceRules.js';
 import { DeltaConfirmationTracker } from './deltaConfirmation.js';
-import { deserializePersistedTransaction, isNonReplayablePersistedRow, pendingMutationRecordId, legacyPendingMutationRecordSchema, pendingMutationRecordSchema, persistedMutationSchema, } from './replayValidation.js';
+import { deserializePersistedTransaction, isNonReplayablePersistedRow, pendingMutationRecordId, } from './replayValidation.js';
 import { deserializeLegacyPendingMutation, loadPersistedTransactions, persistQueuedTransaction, removePersistedTransaction, settlePersistedFailure, } from './mutationPersistence.js';
-import { createCommitEnvelopeMember, createDurableCommitEnvelope, commitEnvelopeRecordId, durableCommitEnvelopeSchema, } from '@abloatai/transaction/transactions/confirmation/commitEnvelope';
+import { createCommitEnvelopeMember, } from '@abloatai/transaction/transactions/confirmation/commitEnvelope';
 import { stableStringify } from '@abloatai/transaction/utils/json';
 import { createLocalMutationPort, } from './localMutation.js';
 import { dispatchCommitBounded, parseMutationCommitResult, persistDurableCommitAcceptance, removeDurableCommit, sealDurableCommit, } from './commitTransport.js';
@@ -120,7 +119,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); },
         };
     }
     get commitLaneContext() {
@@ -138,7 +137,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,
                 ...(envelope.commitOptions.reads ? { reads: envelope.commitOptions.reads } : {}),
@@ -147,9 +146,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) => {
@@ -160,7 +159,7 @@ export class MutationQueue extends EventEmitter {
                     void this.processCommitLane();
                 }, delayMs);
             },
-            emitCommitLifecycle: (event, payload) => this.emitCommitLifecycle(event, payload),
+            emitCommitLifecycle: (event, payload) => { this.emitCommitLifecycle(event, payload); },
         };
     }
     get commitReceiptContext() {
@@ -175,22 +174,22 @@ export class MutationQueue extends EventEmitter {
     }
     get 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); },
         };
     }
     get modelMutationContext() {
         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),
@@ -199,11 +198,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),
@@ -211,11 +210,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),
         };
     }
@@ -224,9 +223,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); },
         };
     }
     get batchProcessingContext() {
@@ -238,7 +237,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; },
@@ -247,7 +246,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,
@@ -256,22 +255,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),
         };
@@ -283,7 +282,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),
@@ -295,7 +294,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); },
         };
     }
     get processingSchedulerContext() {
@@ -318,21 +317,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),
         };
@@ -356,7 +355,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),
         };
@@ -1390,39 +1389,25 @@ 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.
     generateId() {
-        return `tx_${Date.now()}_${Math.random().toString(36).substring(2, 11)}`;
+        return generateTransactionId();
     }
     mergeData(local, remote) {
-        return { ...(remote || {}), ...(local || {}) };
+        return mergeMutationData(local, remote);
     }
     extractCreateData(model) {
-        return projectCommitPayload(model.getModelName(), model.toJSON(), { dropUndefined: false }, this.runtime);
+        return createDataFor(model, this.runtime);
     }
     mapChangesToInput(modelName, changes) {
-        return projectCommitPayload(modelName, changes, { dropUndefined: true }, this.runtime);
+        return changesToInput(modelName, changes, this.runtime);
     }
     extractUpdateData(model) {
-        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.
     extractPreviousData(model, updateInput) {
-        // 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. */
     getStats() {

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

@@ -1,6 +1,6 @@
 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 } from '@abloatai/transaction/transactions/confirmation/commitEnvelope';
 import type { SealDurableCommitInput } from './commitTransport.js';
 export interface CommitTransaction {
@@ -23,6 +23,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;
@@ -73,5 +75,6 @@ export declare function waitForCommitReceipt(ctx: CommitReceiptContext, clientTx
     lastSyncId: number;
     notifications?: StaleNotification[];
     missingIds?: string[];
+    operationResults?: CommitOperationResult[];
 }>;
 export declare function processCommitLane(ctx: CommitLaneContext): Promise<void>;

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

@@ -14,18 +14,21 @@ export function waitForCommitReceipt(ctx, clientTxId) {
         ctx.commitMissingIds.delete(clientTxId);
         return ids.length > 0 ? ids : undefined;
     };
-    const receipt = (lastSyncId) => {
+    const receipt = (transaction, lastSyncId) => {
         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));
+            resolve(receipt(existing, existing.lastSyncId ?? 0));
             return;
         }
         if (existing?.status === 'failed' && existing.error) {
@@ -37,7 +40,11 @@ export function waitForCommitReceipt(ctx, clientTxId) {
             reject(lagError);
             return;
         }
-        const onCompleted = (tx) => { cleanup(); resolve(receipt(tx.lastSyncId ?? 0)); };
+        const onCompleted = (tx) => {
+            cleanup();
+            const completed = tx;
+            resolve(receipt(completed, completed.lastSyncId ?? 0));
+        };
         const onFailed = (payload) => { cleanup(); reject(payload.error); };
         const onLagged = (payload) => { cleanup(); reject(payload.error); };
         const cleanup = () => {
@@ -86,6 +93,8 @@ export async function processCommitLane(ctx) {
                 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)

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

@@ -0,0 +1,40 @@
+/**
+ * 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 { type MutationInput } from './commitPayload.js';
+/** A queued transaction's local identity, unique per process and monotonic enough to sort. */
+export declare function generateTransactionId(): string;
+/** Local values win: they are the edit the caller made, remote is the base. */
+export declare function mergeMutationData(local: MutationInput | undefined, remote: MutationInput | undefined): MutationInput;
+/** A create sends the whole row, `undefined` included, so absence is explicit. */
+export declare function createDataFor(model: LocalModel, runtime?: RuntimeContext): MutationInput;
+/** An arbitrary change set, projected the way an update is. */
+export declare function changesToInput(modelName: string, changes: Record<string, unknown>, runtime?: RuntimeContext): MutationInput;
+/** An update sends only what changed. */
+export declare function updateDataFor(model: LocalModel, runtime?: RuntimeContext): MutationInput;
+/**
+ * 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 declare function previousDataFor(model: LocalModel, updateInput?: MutationInput): MutationInput;

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

@@ -0,0 +1,53 @@
+/**
+ * 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 { projectCommitPayload } from './commitPayload.js';
+/** A queued transaction's local identity, unique per process and monotonic enough to sort. */
+export function generateTransactionId() {
+    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, remote) {
+    return { ...(remote ?? {}), ...(local ?? {}) };
+}
+/** A create sends the whole row, `undefined` included, so absence is explicit. */
+export function createDataFor(model, runtime) {
+    return projectCommitPayload(model.getModelName(), model.toJSON(), { dropUndefined: false }, runtime);
+}
+/** An arbitrary change set, projected the way an update is. */
+export function changesToInput(modelName, changes, runtime) {
+    return projectCommitPayload(modelName, changes, { dropUndefined: true }, runtime);
+}
+/** An update sends only what changed. */
+export function updateDataFor(model, runtime) {
+    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, updateInput) {
+    const keys = updateInput
+        ? Object.keys(updateInput)
+        : [...(model.modifiedProperties instanceof Map ? model.modifiedProperties.keys() : [])];
+    return { id: model.id, ...model.capturePreviousValues(keys, { fallbackToLive: false }) };
+}

package/dist/surface.d.ts

@@ -19,7 +19,7 @@
  * tuple, so it is the one list of model-verb names a generated summary can
  * describe.
  */
-export declare const PUBLIC_MODEL_VERBS: readonly ["get", "retrieve", "list", "local", "create", "update", "delete", "claim", "track", "join", "onChange"];
+export declare const PUBLIC_MODEL_VERBS: readonly ["get", "retrieve", "list", "listAll", "local", "create", "update", "delete", "claim", "track", "join", "onChange"];
 /**
  * The option keys accepted by `local.list` and `onChange`, matching the
  * keys of {@link LocalReadOptions}. Note that the lifecycle filter is named

package/dist/surface.js

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@abloatai/humans",
-  "version": "0.55.0",
+  "version": "0.57.0",
   "description": "The optional human-facing local-state package for Ablo: presence, live queries, and React bindings.",
   "license": "Apache-2.0",
   "type": "module",
@@ -84,7 +84,7 @@
     "directory": "packages/humans"
   },
   "dependencies": {
-    "@abloatai/transaction": "^0.55.0",
+    "@abloatai/transaction": "^0.57.0",
     "mobx": "^6.13.7",
     "uuid": "^11.1.0",
     "zod": "^4.4.3"

package/src/local/Database.ts

@@ -5,7 +5,6 @@
  * server. {@link BaseSyncedStore} drives it, and {@link InstanceCache} holds the
  * in-memory mirror of what this class persists.
  */
-
 import { DatabaseManager, type DatabaseInfo, type WorkspaceMetadata } from './stores/DatabaseManager.js';
 import type { PersistenceIdentity } from './stores/persistenceIdentity.js';
 import { StoreManager } from './stores/StoreManager.js';
@@ -21,7 +20,7 @@ import {
 } from './stores/persistenceCleanup.js';
 import type { BootstrapFetcher, BootstrapData } from './sync/BootstrapFetcher.js';
 import { InMemoryObjectStore } from './adapters/inMemoryStorage.js';
-import { logPositionSchema } from './logPosition.js';
+import { logPositionSnapshotSchema } from './logPosition.js';
 import type { SyncDeltaAction } from '@abloatai/transaction/wire/delta';
 import type { BootstrapType } from '@abloatai/transaction/types';
 import { highestPersistedPrefixSyncId } from './sync/persistedPrefix.js';
@@ -448,7 +447,7 @@ export class Database {
     // which only catches falsy, and get sent to the server as the resume
     // point). Invalid → 0 → full bootstrap, the safe degradation.
     const metadataLastSyncId =
-      logPositionSchema.shape.persisted.safeParse(metadata?.lastSyncId).data ?? 0;
+      logPositionSnapshotSchema.shape.persisted.safeParse(metadata?.lastSyncId).data ?? 0;
     const dataAge = metadata?.updatedAt ? Date.now() - metadata.updatedAt.getTime() : Infinity;
 
     // ── Cache-validity check ─────────────────────────────────────

package/src/local/Model.ts

@@ -1106,7 +1106,7 @@ export abstract class Model {
     }
 
     // Try to get model class by identifier
-    let ModelClass = getActiveRegistry().getModelByName(modelIdentifier);
+    const ModelClass = getActiveRegistry().getModelByName(modelIdentifier);
 
     if (!ModelClass) {
       throw new AbloValidationError(

package/src/local/SyncClient.ts

@@ -34,85 +34,25 @@ import {
   type UnconfirmedWritesMetrics,
 } from './transactions/mutations/UnconfirmedWrites.js';
 import type { DurableWriteStore } from './transactions/mutations/durableWriteStore.js';
-import type { CommitTransaction } from './transactions/mutations/commitLane.js';
 import type { Database } from './Database.js';
-import type { BootstrapData } from './sync/BootstrapFetcher.js';
 import type { MutationPersistencePort } from './mutationPersistence.js';
 import type { WriteOptions } from './interfaces/index.js';
 import { LogPosition } from './logPosition.js';
 import { createLocalMutationPort } from './transactions/localMutation.js';
 import { createReconnectDrain } from './transactions/reconnectDrain.js';
 import { DatabaseCommitOutboxStore } from './transactions/databaseCommitOutbox.js';
-
-interface SyncObserver {
-  onSync?: (event: SyncEvent) => void;
-}
-
-interface SyncEvent {
-  type: 'create' | 'update' | 'delete' | 'archive' | 'rollback';
-  modelType: string;
-  model?: Model;
-  modelId?: string;
-  transactionType?: string; // Original transaction type that was rolled back
-}
-
-interface SyncState {
-  connectionState: 'connected' | 'disconnected' | 'connecting';
-  pendingMutations: number;
-  lastSyncAt?: Date;
-  error?: Error;
-}
-
-export interface RehydrationStats {
-  added: number;
-  updated: number;
-  removed: number;
-  skipped: number;
-  healed: number;
-  elapsedMs: number;
-}
-
-type EventHandler = () => void;
-
-/**
- * The slice of a bootstrap answer the pool applies: its rows, the models whose
- * server query failed, and the log position the snapshot was taken at — the
- * position every row in it reflects. `lastSyncId` is optional only for callers
- * applying rows with no snapshot position to speak of; the fetcher always
- * names one.
- */
-export type BootstrapSnapshot = Pick<BootstrapData, 'models' | 'failedModels'> &
-  Partial<Pick<BootstrapData, 'lastSyncId'>>;
-
-/**
- * What `transaction:completed` carries: a model mutation (one row, confirmed
- * at `syncIdNeededForCompletion`) or an explicit commit (one row per operation,
- * confirmed at `lastSyncId`). Each arm projects its own queue record.
- */
-type CompletedTransaction =
-  | (Pick<QueuedMutation, 'id' | 'modelId' | 'syncIdNeededForCompletion'> & {
-      lastSyncId?: undefined;
-      operations?: undefined;
-    })
-  | (Pick<CommitTransaction, 'id' | 'lastSyncId' | 'operations'> & {
-      modelId?: undefined;
-      syncIdNeededForCompletion?: undefined;
-    });
-
-/**
- * Converts an untyped server `updatedAt` value — an ISO string, epoch number,
- * or Date read off an untyped row — into epoch milliseconds for
- * last-write-wins comparison. Falsy or non-date values become 0, matching the
- * conflict resolver's rule that a missing timestamp sorts as the epoch.
- */
-function toEpochMs(value: unknown): number {
-  if (!value) return 0;
-  if (value instanceof Date) return value.getTime();
-  if (typeof value === 'string' || typeof value === 'number') {
-    return new Date(value).getTime();
-  }
-  return 0;
-}
+import {
+  toEpochMs,
+  type CompletedTransaction,
+  type EventHandler,
+  type RehydrationStats,
+  type SyncEvent,
+  type SyncObserver,
+  type SyncState,
+} from './syncClientTypes.js';
+import type { BootstrapSnapshot } from './syncClientTypes.js';
+
+export type { BootstrapSnapshot, RehydrationStats } from './syncClientTypes.js';
 
 export class SyncClient extends EventEmitter {
   private objectPool: InstanceCache;