@abloatai/humans 0.60.0 → 0.61.0

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

@@ -4,8 +4,12 @@ export function takeNextExecutionBatch(
   executionQueue: QueuedMutation[],
   maxBatchSize: number,
 ): { batch: QueuedMutation[]; remaining: QueuedMutation[] } {
+  // Cancellation, delta confirmation, and failure settlement can all make a
+  // queued reference terminal before its scheduler callback runs. Terminal or
+  // currently executing rows have no authority to cross the dispatch boundary.
+  const pendingQueue = executionQueue.filter((tx) => tx.status === 'pending');
   const retryGroups = new Map<string, Map<string, QueuedMutation>>();
-  for (const tx of executionQueue) {
+  for (const tx of pendingQueue) {
     const envelope = tx.commitEnvelope;
     if (!envelope) continue;
     const group = retryGroups.get(envelope.idempotencyKey) ?? new Map<string, QueuedMutation>();
@@ -16,27 +20,17 @@ export function takeNextExecutionBatch(
     const members = [...byId.values()];
     const expectedCount = members[0]?.commitEnvelope?.operationCount;
     if (expectedCount === undefined || members.length !== expectedCount) continue;
-    const remaining = executionQueue.filter((tx) => tx.commitEnvelope?.idempotencyKey !== idempotencyKey);
+    const remaining = pendingQueue.filter((tx) => tx.commitEnvelope?.idempotencyKey !== idempotencyKey);
     members.sort((a, b) => (a.commitEnvelope?.operationIndex ?? 0) - (b.commitEnvelope?.operationIndex ?? 0));
     return { batch: members, remaining };
   }
-  const fresh = executionQueue.filter((tx) => !tx.commitEnvelope);
+  const fresh = pendingQueue.filter((tx) => !tx.commitEnvelope);
   const firstFresh = fresh[0];
-  if (!firstFresh) return { batch: [], remaining: executionQueue };
+  if (!firstFresh) return { batch: [], remaining: pendingQueue };
   const explicitIndex = fresh.findIndex((tx) => typeof tx.writeOptions?.idempotencyKey === 'string');
   const selected = explicitIndex === 0
     ? [firstFresh]
     : fresh.slice(0, Math.min(maxBatchSize, explicitIndex > 0 ? explicitIndex : fresh.length));
   const selectedIds = new Set(selected.map((tx) => tx.id));
-  return { batch: selected, remaining: executionQueue.filter((tx) => !selectedIds.has(tx.id)) };
-}
-
-export function takePendingDrainBatch(pending: QueuedMutation[], maxBatchSize: number): QueuedMutation[] {
-  const first = pending[0];
-  if (!first) return [];
-  const envelope = first.commitEnvelope;
-  if (envelope) return pending.filter((tx) => tx.commitEnvelope?.idempotencyKey === envelope.idempotencyKey);
-  if (typeof first.writeOptions?.idempotencyKey === 'string') return [first];
-  const explicitIndex = pending.findIndex((tx) => typeof tx.writeOptions?.idempotencyKey === 'string');
-  return pending.slice(0, Math.min(maxBatchSize, explicitIndex > 0 ? explicitIndex : pending.length));
+  return { batch: selected, remaining: pendingQueue.filter((tx) => !selectedIds.has(tx.id)) };
 }

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

@@ -44,6 +44,16 @@ export async function handleFailure(
   transaction: QueuedMutation,
   error: Error,
 ): Promise<void> {
+  // The dispatch owner may lose its acknowledgement while an authoritative
+  // delta concurrently completes the same transaction. Completion is
+  // terminal: a late catch path must not turn that row back into `pending`
+  // and schedule a second seal after its durable sources were cleaned up.
+  if (
+    transaction.status === 'completed' ||
+    transaction.status === 'failed' ||
+    transaction.status === 'rolled_back' ||
+    transaction.status === 'awaiting_delta'
+  ) return;
   transaction.attempts++;
 
   // Check whether this is a permanent error that should not be retried.

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

@@ -43,9 +43,9 @@ export function createLocalMutationPort(emitter: OptimisticEmitter): LocalMutati
   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),
+    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),
   };
 }

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

@@ -12,6 +12,12 @@ export interface QueueCoalescingContext {
 }
 
 export function enqueueTransaction(ctx: QueueCoalescingContext, transaction: QueuedMutation): void {
+  // Only the pending state may cross into the execution owner. A late timer,
+  // reconnect callback, or stale staging callback must not resurrect a row
+  // that is already executing or terminal, and repeated triggers must not put
+  // the same source mutation into the queue twice.
+  if (transaction.status !== 'pending') return;
+  if (ctx.executionQueue.some((candidate) => candidate.id === transaction.id)) return;
   ctx.ensureDerivedFields(transaction);
   const modelKey = `${transaction.modelName}:${transaction.modelId}`;
   if (transaction.type === 'update' && transaction.attempts === 0 && !transaction.commitEnvelope) {

package/src/react/useErrorListener.ts

@@ -16,7 +16,7 @@ export function useErrorListener(listener: (error: Error) => void): void {
   const listenerRef = useRef(listener);
   listenerRef.current = listener;
   useEffect(
-    () => context.subscribeError((error) => listenerRef.current(error)),
+    () => context.subscribeError((error) => { listenerRef.current(error); }),
     [context],
   );
 }

package/src/react/useMutationFailureListener.ts

@@ -29,6 +29,6 @@ export function useMutationFailureListener(
   useEffect(() => {
     const engine = context.engine;
     if (!engine) return;
-    return engine.onMutationFailure((payload) => listenerRef.current(payload));
+    return engine.onMutationFailure((payload) => { listenerRef.current(payload); });
   }, [context, context.engine]);
 }

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

@@ -1,33 +0,0 @@
-import type { RuntimeContext } from '../../RuntimeContext.js';
-import type { QueuedMutation } from './commitPayload.js';
-import type { MutationStore } from './MutationStore.js';
-import type { OptimisticUpdateEntry } from './localMutation.js';
-import type { MutationCommitResult } from '@abloatai/transaction/commit';
-import type { DurableCommitEnvelope } from '@abloatai/transaction/commit';
-export interface PendingDrainContext {
-    readonly runtime: RuntimeContext;
-    readonly config: {
-        deltaConfirmationTimeout: number;
-    };
-    readonly store: MutationStore;
-    readonly executionQueue: QueuedMutation[];
-    readonly optimisticUpdates: Map<string, OptimisticUpdateEntry>;
-    readonly assertDurableReplayOpen: () => void;
-    readonly processCommitLane: () => Promise<void>;
-    readonly takePendingDrainBatch: (pending: QueuedMutation[]) => QueuedMutation[];
-    readonly ensureCommitEnvelope: (batch: QueuedMutation[]) => string;
-    readonly ensureDerivedFields: (transaction: QueuedMutation) => void;
-    readonly sourceMutationIdsFor: (batch: readonly QueuedMutation[]) => string[];
-    readonly sealDurableCommit: (input: Parameters<typeof import('./commitTransport.js').sealDurableCommit>[1]) => Promise<DurableCommitEnvelope>;
-    readonly assertEnvelopeInsideReplayWindow: (envelope: DurableCommitEnvelope) => void;
-    readonly parseMutationCommitResult: (value: Awaited<ReturnType<import('../../interfaces/index.js').MutationExecutor['commit']>>) => MutationCommitResult;
-    readonly dispatchCommitBounded: (...args: Parameters<import('../../interfaces/index.js').MutationExecutor['commit']>) => ReturnType<import('../../interfaces/index.js').MutationExecutor['commit']>;
-    readonly persistDurableCommitAcceptance: (envelope: DurableCommitEnvelope, result: MutationCommitResult) => Promise<DurableCommitEnvelope>;
-    readonly removeDurableCommit: (idempotencyKey: string) => Promise<void>;
-    readonly scheduleReplicationLagTimeout: (transactionId: string, clientTxId?: string, correlationId?: string) => void;
-    readonly scheduleDeltaConfirmationTimeout: (transaction: QueuedMutation, timeoutMs: number) => void;
-    readonly enqueue: (transaction: QueuedMutation) => void;
-    readonly recentDeltaCorrelations: Map<string, number>;
-    readonly emit: (event: string, payload: object) => boolean;
-}
-export declare function drainPendingConfirmations(ctx: PendingDrainContext): Promise<void>;

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

@@ -1,117 +0,0 @@
-import { applyWriteOptions, collectQueuedReads, TX_TYPE_TO_MUTATION_OP } from './commitPayload.js';
-export async function drainPendingConfirmations(ctx) {
-    ctx.assertDurableReplayOpen();
-    // Kick the commit lane too: atomic envelopes from `commits.create()` may
-    // have been left at the head of the lane while the connection was down.
-    // Fire-and-forget; processCommitLane serializes itself.
-    void ctx.processCommitLane();
-    // Collect pending transactions in created order
-    const pending = ctx.store.getByStatus('pending').sort((a, b) => a.createdAt - b.createdAt);
-    if (pending.length === 0)
-        return;
-    const pendingIds = new Set(pending.map((tx) => tx.id));
-    // These rows may already be waiting behind the normal batch timer. The
-    // reconnect fast path takes ownership of them for this attempt so the same
-    // transaction cannot dispatch concurrently through both paths.
-    const retainedQueue = ctx.executionQueue.filter((tx) => !pendingIds.has(tx.id));
-    ctx.executionQueue.splice(0, ctx.executionQueue.length, ...retainedQueue);
-    const remaining = [...pending];
-    while (remaining.length > 0) {
-        const batch = ctx.takePendingDrainBatch(remaining);
-        if (batch.length === 0)
-            break;
-        const batchIds = new Set(batch.map((tx) => tx.id));
-        const nextRemaining = remaining.filter((tx) => !batchIds.has(tx.id));
-        try {
-            const idempotencyKey = ctx.ensureCommitEnvelope(batch);
-            const projectedOperations = batch.map((tx) => {
-                ctx.ensureDerivedFields(tx);
-                return applyWriteOptions({
-                    type: TX_TYPE_TO_MUTATION_OP[tx.type],
-                    model: tx.modelKey,
-                    id: tx.modelId,
-                    input: tx.type === 'create' || tx.type === 'update' ? tx.data || {} : undefined,
-                    transactionId: tx.id,
-                }, tx);
-            });
-            const durableEnvelope = await ctx.sealDurableCommit({
-                idempotencyKey,
-                origin: 'model_batch',
-                operations: projectedOperations,
-                sourceMutationIds: ctx.sourceMutationIdsFor(batch),
-                commitOptions: { reads: collectQueuedReads(batch) },
-                createdAt: Math.min(...batch.map((transaction) => transaction.createdAt)),
-                sealedAt: batch[0]?.commitEnvelope?.sealedAt ?? Date.now(),
-                sequence: batch[0]?.commitEnvelope?.sequence,
-            });
-            ctx.assertEnvelopeInsideReplayWindow(durableEnvelope);
-            const result = ctx.parseMutationCommitResult(await ctx.dispatchCommitBounded(durableEnvelope.operations, {
-                idempotencyKey,
-                ...(durableEnvelope.commitOptions.reads !== undefined
-                    ? { reads: durableEnvelope.commitOptions.reads }
-                    : {}),
-            }));
-            await ctx.persistDurableCommitAcceptance(durableEnvelope, result);
-            if (result.status === 'queued') {
-                // Reconnect flushes use the same accepted-vs-confirmed contract as
-                // the normal lane. A queued source receipt retains the envelope and
-                // waits for exact correlation; it is never promoted by the reconnect
-                // shortcut itself.
-                for (const tx of batch) {
-                    tx.requiresCorrelatedDelta = true;
-                    tx.syncIdNeededForCompletion = undefined;
-                    tx.correlationId = result.correlationId;
-                    const echoSyncId = result.correlationId
-                        ? ctx.recentDeltaCorrelations.get(result.correlationId)
-                        : undefined;
-                    if (echoSyncId !== undefined) {
-                        ctx.store.updateStatus(tx.id, 'completed');
-                        ctx.emit('transaction:completed', tx);
-                        ctx.emit(`transaction:completed:${tx.id}`, tx);
-                        ctx.optimisticUpdates.delete(tx.id);
-                        continue;
-                    }
-                    ctx.store.updateStatus(tx.id, 'awaiting_delta');
-                    ctx.scheduleReplicationLagTimeout(tx.id, idempotencyKey, result.correlationId);
-                    ctx.scheduleDeltaConfirmationTimeout(tx, ctx.config.deltaConfirmationTimeout);
-                }
-                if (batch.every((tx) => tx.status === 'completed')) {
-                    await ctx.removeDurableCommit(idempotencyKey);
-                }
-            }
-            else {
-                await ctx.removeDurableCommit(idempotencyKey);
-                // Mark this request envelope as completed before moving to the next.
-                for (const tx of batch) {
-                    ctx.store.updateStatus(tx.id, 'completed');
-                    ctx.emit('transaction:completed', tx);
-                    ctx.emit(`transaction:completed:${tx.id}`, tx);
-                    ctx.optimisticUpdates.delete(tx.id);
-                }
-            }
-            ctx.runtime.logger.debug('txn:commit', 0, {
-                count: batch.length,
-                lastSyncId: result.lastSyncId,
-            });
-            remaining.splice(0, remaining.length, ...nextRemaining);
-        }
-        catch (err) {
-            // If one request fails, hand it and every later request back to the
-            // normal lane. Their envelopes stay attached for safe retry.
-            const networkUnavailable = !ctx.runtime.onlineStatus.isOnline();
-            const isNetworkError = err instanceof Error &&
-                (err.message.includes('Failed to fetch') ||
-                    err.message.includes('Network request failed') ||
-                    err.message.includes('NetworkError'));
-            if (!networkUnavailable || !isNetworkError) {
-                ctx.runtime.observability.breadcrumb('Batch flush fallback failed', 'sync.transaction', 'warning', {
-                    error: err instanceof Error ? err.message : String(err),
-                });
-            }
-            for (const tx of [...batch, ...nextRemaining]) {
-                ctx.enqueue(tx);
-            }
-            return;
-        }
-    }
-}

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

@@ -1,169 +0,0 @@
-import type { RuntimeContext } from '../../RuntimeContext.js';
-import type { QueuedMutation } from './commitPayload.js';
-import type { MutationStore } from './MutationStore.js';
-import type { OptimisticUpdateEntry } from './localMutation.js';
-import type { MutationCommitResult } from '@abloatai/transaction/commit';
-import type { DurableCommitEnvelope } from '@abloatai/transaction/commit';
-import { applyWriteOptions, collectQueuedReads, TX_TYPE_TO_MUTATION_OP } from './commitPayload.js';
-
-export interface PendingDrainContext {
-  readonly runtime: RuntimeContext;
-  readonly config: { deltaConfirmationTimeout: number };
-  readonly store: MutationStore;
-  readonly executionQueue: QueuedMutation[];
-  readonly optimisticUpdates: Map<string, OptimisticUpdateEntry>;
-  readonly assertDurableReplayOpen: () => void;
-  readonly processCommitLane: () => Promise<void>;
-  readonly takePendingDrainBatch: (pending: QueuedMutation[]) => QueuedMutation[];
-  readonly ensureCommitEnvelope: (batch: QueuedMutation[]) => string;
-  readonly ensureDerivedFields: (transaction: QueuedMutation) => void;
-  readonly sourceMutationIdsFor: (batch: readonly QueuedMutation[]) => string[];
-  readonly sealDurableCommit: (input: Parameters<typeof import('./commitTransport.js').sealDurableCommit>[1]) => Promise<DurableCommitEnvelope>;
-  readonly assertEnvelopeInsideReplayWindow: (envelope: DurableCommitEnvelope) => void;
-  readonly parseMutationCommitResult: (value: Awaited<ReturnType<import('../../interfaces/index.js').MutationExecutor['commit']>>) => MutationCommitResult;
-  readonly dispatchCommitBounded: (...args: Parameters<import('../../interfaces/index.js').MutationExecutor['commit']>) => ReturnType<import('../../interfaces/index.js').MutationExecutor['commit']>;
-  readonly persistDurableCommitAcceptance: (envelope: DurableCommitEnvelope, result: MutationCommitResult) => Promise<DurableCommitEnvelope>;
-  readonly removeDurableCommit: (idempotencyKey: string) => Promise<void>;
-  readonly scheduleReplicationLagTimeout: (transactionId: string, clientTxId?: string, correlationId?: string) => void;
-  readonly scheduleDeltaConfirmationTimeout: (transaction: QueuedMutation, timeoutMs: number) => void;
-  readonly enqueue: (transaction: QueuedMutation) => void;
-  readonly recentDeltaCorrelations: Map<string, number>;
-  readonly emit: (event: string, payload: object) => boolean;
-}
-
-export async function drainPendingConfirmations(ctx: PendingDrainContext): Promise<void> {
-    ctx.assertDurableReplayOpen();
-    // Kick the commit lane too: atomic envelopes from `commits.create()` may
-    // have been left at the head of the lane while the connection was down.
-    // Fire-and-forget; processCommitLane serializes itself.
-    void ctx.processCommitLane();
-
-    // Collect pending transactions in created order
-    const pending = ctx.store.getByStatus('pending').sort((a, b) => a.createdAt - b.createdAt);
-    if (pending.length === 0) return;
-    const pendingIds = new Set(pending.map((tx) => tx.id));
-    // These rows may already be waiting behind the normal batch timer. The
-    // reconnect fast path takes ownership of them for this attempt so the same
-    // transaction cannot dispatch concurrently through both paths.
-    const retainedQueue = ctx.executionQueue.filter(
-      (tx) => !pendingIds.has(tx.id),
-    );
-    ctx.executionQueue.splice(
-      0,
-      ctx.executionQueue.length,
-      ...retainedQueue,
-    );
-
-    const remaining = [...pending];
-    while (remaining.length > 0) {
-      const batch = ctx.takePendingDrainBatch(remaining);
-      if (batch.length === 0) break;
-      const batchIds = new Set(batch.map((tx) => tx.id));
-      const nextRemaining = remaining.filter((tx) => !batchIds.has(tx.id));
-
-      try {
-        const idempotencyKey = ctx.ensureCommitEnvelope(batch);
-        const projectedOperations = batch.map((tx) => {
-          ctx.ensureDerivedFields(tx);
-          return applyWriteOptions(
-            {
-              type: TX_TYPE_TO_MUTATION_OP[tx.type],
-              model: tx.modelKey,
-              id: tx.modelId,
-              input: tx.type === 'create' || tx.type === 'update' ? tx.data || {} : undefined,
-              transactionId: tx.id,
-            },
-            tx,
-          );
-        });
-        const durableEnvelope = await ctx.sealDurableCommit({
-          idempotencyKey,
-          origin: 'model_batch',
-          operations: projectedOperations,
-          sourceMutationIds: ctx.sourceMutationIdsFor(batch),
-          commitOptions: { reads: collectQueuedReads(batch) },
-          createdAt: Math.min(...batch.map((transaction) => transaction.createdAt)),
-          sealedAt: batch[0]?.commitEnvelope?.sealedAt ?? Date.now(),
-          sequence: batch[0]?.commitEnvelope?.sequence,
-        });
-        ctx.assertEnvelopeInsideReplayWindow(durableEnvelope);
-        const result = ctx.parseMutationCommitResult(
-          await ctx.dispatchCommitBounded(durableEnvelope.operations, {
-            idempotencyKey,
-            ...(durableEnvelope.commitOptions.reads !== undefined
-              ? { reads: durableEnvelope.commitOptions.reads }
-              : {}),
-          }),
-        );
-        await ctx.persistDurableCommitAcceptance(durableEnvelope, result);
-        if (result.status === 'queued') {
-          // Reconnect flushes use the same accepted-vs-confirmed contract as
-          // the normal lane. A queued source receipt retains the envelope and
-          // waits for exact correlation; it is never promoted by the reconnect
-          // shortcut itself.
-          for (const tx of batch) {
-            tx.requiresCorrelatedDelta = true;
-            tx.syncIdNeededForCompletion = undefined;
-            tx.correlationId = result.correlationId;
-            const echoSyncId = result.correlationId
-              ? ctx.recentDeltaCorrelations.get(result.correlationId)
-              : undefined;
-            if (echoSyncId !== undefined) {
-              ctx.store.updateStatus(tx.id, 'completed');
-              ctx.emit('transaction:completed', tx);
-              ctx.emit(`transaction:completed:${tx.id}`, tx);
-              ctx.optimisticUpdates.delete(tx.id);
-              continue;
-            }
-            ctx.store.updateStatus(tx.id, 'awaiting_delta');
-            ctx.scheduleReplicationLagTimeout(
-              tx.id,
-              idempotencyKey,
-              result.correlationId,
-            );
-            ctx.scheduleDeltaConfirmationTimeout(
-              tx,
-              ctx.config.deltaConfirmationTimeout,
-            );
-          }
-          if (batch.every((tx) => tx.status === 'completed')) {
-            await ctx.removeDurableCommit(idempotencyKey);
-          }
-        } else {
-          await ctx.removeDurableCommit(idempotencyKey);
-          // Mark this request envelope as completed before moving to the next.
-          for (const tx of batch) {
-            ctx.store.updateStatus(tx.id, 'completed');
-            ctx.emit('transaction:completed', tx);
-            ctx.emit(`transaction:completed:${tx.id}`, tx);
-            ctx.optimisticUpdates.delete(tx.id);
-          }
-        }
-        ctx.runtime.logger.debug('txn:commit', 0, {
-          count: batch.length,
-          lastSyncId: result.lastSyncId,
-        });
-        remaining.splice(0, remaining.length, ...nextRemaining);
-      } catch (err) {
-        // If one request fails, hand it and every later request back to the
-        // normal lane. Their envelopes stay attached for safe retry.
-        const networkUnavailable = !ctx.runtime.onlineStatus.isOnline();
-        const isNetworkError =
-          err instanceof Error &&
-          (err.message.includes('Failed to fetch') ||
-            err.message.includes('Network request failed') ||
-            err.message.includes('NetworkError'));
-
-        if (!networkUnavailable || !isNetworkError) {
-          ctx.runtime.observability.breadcrumb('Batch flush fallback failed', 'sync.transaction', 'warning', {
-            error: err instanceof Error ? err.message : String(err),
-          });
-        }
-
-        for (const tx of [...batch, ...nextRemaining]) {
-          ctx.enqueue(tx);
-        }
-        return;
-      }
-    }
-}