@abloatai/humans 0.59.2 → 0.61.0

package/src/local/fileUploads.ts

@@ -0,0 +1,97 @@
+/** File-upload behavior owned beneath the SyncClient boundary. */
+
+import { AbloAuthenticationError } from '@abloatai/transaction/errors';
+import type { RuntimeContext } from './RuntimeContext.js';
+import { Model } from './Model.js';
+import { InstanceCache, ModelScope } from './InstanceCache.js';
+import type { MutationQueue } from './transactions/mutations/MutationQueue.js';
+
+export interface FileUploadOptions {
+  readonly id: string;
+  readonly attachableType: string;
+  readonly attachableId: string;
+  readonly metadata?: Record<string, unknown>;
+}
+
+export interface BatchFileUploadOptions {
+  readonly ids: string[];
+  readonly attachableType: string;
+  readonly attachableId: string;
+  readonly metadata?: Record<string, unknown>;
+}
+
+export interface FileUploadContext {
+  readonly userId: string | null;
+  readonly organizationId: string | null;
+  readonly mutationQueue: MutationQueue;
+  readonly objectPool: InstanceCache;
+  readonly observability: RuntimeContext['observability'];
+  readonly notifyCreated: (model: Model) => void;
+}
+
+function authenticatedContext(context: FileUploadContext): {
+  readonly userId: string;
+  readonly organizationId: string;
+} {
+  if (!context.userId || !context.organizationId) {
+    throw new AbloAuthenticationError('Authentication required for file uploads', {
+      code: 'file_upload_auth_required',
+    });
+  }
+  return { userId: context.userId, organizationId: context.organizationId };
+}
+
+function acceptUploadedModel(
+  context: FileUploadContext,
+  data: Record<string, unknown>,
+): Model | null {
+  const model = context.objectPool.createFromData(data);
+  if (!model) return null;
+  context.objectPool.add(model, ModelScope.live);
+  context.notifyCreated(model);
+  return model;
+}
+
+export async function uploadFile(
+  context: FileUploadContext,
+  file: File,
+  options: FileUploadOptions,
+): Promise<Model | null> {
+  const identity = authenticatedContext(context);
+  try {
+    const result = await context.mutationQueue.uploadAttachment(file, {
+      id: options.id,
+      attachableType: options.attachableType,
+      attachableId: options.attachableId,
+      metadata: options.metadata,
+    }, identity);
+    return result
+      ? acceptUploadedModel(context, { id: options.id, ...result })
+      : null;
+  } catch (error) {
+    context.observability.captureMutationFailure({
+      context: 'file-upload',
+      error: error instanceof Error ? error : new Error(String(error)),
+    });
+    throw error;
+  }
+}
+
+export async function batchUploadFiles(
+  context: FileUploadContext,
+  files: File[],
+  options: BatchFileUploadOptions,
+): Promise<Model[]> {
+  const identity = authenticatedContext(context);
+  const items = options.ids.map((id) => ({
+    id,
+    attachableType: options.attachableType,
+    attachableId: options.attachableId,
+    metadata: options.metadata,
+  }));
+  const results = await context.mutationQueue.batchUploadAttachments(files, items, identity);
+  return results.flatMap((result) => {
+    const model = acceptUploadedModel(context, { ...result });
+    return model ? [model] : [];
+  });
+}

package/src/local/storeContract.ts

@@ -14,7 +14,7 @@ import type { Model } from './Model.js';
 import type { ModelScope } from '@abloatai/transaction/types';
 import type { QueryView, QueryViewOptions } from './views/QueryView.js';
 import type { ViewRegistry } from './views/ViewRegistry.js';
-import type { ParticipantScope } from './sync/participants.js';
+import type { GroupScope } from './sync/scopeGroups.js';
 
 /**
  * A snapshot of the client's synchronization state, shaped for binding to UI.
@@ -132,10 +132,10 @@ export interface SyncStoreContract {
    * read subscriptions and write claims always agree on which group they refer
    * to. These are optional and do nothing until the connection is open.
    */
-  enterScope?(scope: ParticipantScope, opts?: { hydrate?: boolean }): Promise<void>;
-  leaveScope?(scope: ParticipantScope): Promise<void>;
-  pinScope?(scope: ParticipantScope): Promise<void>;
-  unpinScope?(scope: ParticipantScope): Promise<void>;
+  enterScope?(scope: GroupScope, opts?: { hydrate?: boolean }): Promise<void>;
+  leaveScope?(scope: GroupScope): Promise<void>;
+  pinScope?(scope: GroupScope): Promise<void>;
+  unpinScope?(scope: GroupScope): Promise<void>;
   /**
    * The full reactive {@link SyncStatus} record. The `useSyncStatus()` hook
    * reads its fields — `state`, `progress`, `pendingChanges`, `isSessionError`,

package/src/local/sync/contextOnChange.ts

@@ -54,7 +54,7 @@ export function contextOnChange(
   // already advanced this exact row in the pool.
   for (const read of rowReads) {
     const resident = pool.peek(read.id);
-    if (!resident || resident.getModelName().toLowerCase() !== read.model.toLowerCase()) {
+    if (resident?.getModelName().toLowerCase() !== read.model.toLowerCase()) {
       continue;
     }
     const observed = pool.watermarks.of(resident);

package/src/local/sync/createClaimStream.ts

@@ -468,7 +468,7 @@ export function createClaimStream(
         }
         ownClaims.clear();
         for (const claimId of [...pendingHeartbeats.keys()]) {
-          settleHeartbeat(claimId, ({ reject }) => reject(error));
+          settleHeartbeat(claimId, ({ reject }) => { reject(error); });
         }
       }),
     );

package/src/local/sync/credentialLifecycle.ts

@@ -1,8 +1,7 @@
 /**
- * Moved to the confirmation core with the duplex transport (ADR 0016): keeping
- * a long-lived socket's credential fresh is connection plumbing an agent needs
- * as much as a browser does. This path re-exports it so existing importers
- * stay unchanged.
+ * The shared session subsystem owns renewal for both browser and agent
+ * sessions. This local boundary keeps the reactive store pointed downward at
+ * that one lifecycle implementation.
  */
 
 export {
@@ -15,4 +14,4 @@ export {
   type CredentialRefreshResult,
   type CredentialRefresher,
   type CredentialLifecycleContext,
-} from '@abloatai/transaction/transport/connection';
+} from '@abloatai/transaction/sessions';

package/src/local/sync/deltaPipeline.ts

@@ -173,7 +173,9 @@ export function deduplicateDeltas(deltas: SyncDelta[]): SyncDelta[] {
 
   let strictlyOrdered = true;
   for (let index = 1; index < deltas.length; index += 1) {
-    if (deltas[index - 1]!.id >= deltas[index]!.id) {
+    const previous = deltas[index - 1];
+    const current = deltas[index];
+    if (!previous || !current || previous.id >= current.id) {
       strictlyOrdered = false;
       break;
     }
@@ -400,10 +402,12 @@ export function sliceApplyChanges<T extends { readonly transactionId?: string }>
   while (index < changes.length) {
     // The indivisible unit starting here: one transaction's run, or a single
     // untransacted change.
-    const transactionId = changes[index]!.transactionId;
+    const change = changes[index];
+    if (!change) break;
+    const transactionId = change.transactionId;
     let end = index + 1;
     if (transactionId !== undefined) {
-      while (end < changes.length && changes[end]!.transactionId === transactionId) end += 1;
+      while (changes[end]?.transactionId === transactionId) end += 1;
     }
     const groupSize = end - index;
     if (current.length > 0 && current.length + groupSize > maxDeltas) {
@@ -459,9 +463,10 @@ async function flushDeltaBatchInner(
   if (customDeltas.length > 0) {
     runInAction(() => {
       for (const delta of customDeltas) {
+        if (delta.data === null) continue;
         const data = typeof delta.data === 'string'
           ? (JSON.parse(delta.data) as Record<string, unknown>)
-          : (delta.data!);
+          : delta.data;
 
         // 'C' (Covering) is treated identically to 'I' here — the client
         // gained permission to see the entity, so we insert it into the
@@ -529,7 +534,7 @@ async function flushDeltaBatchInner(
     // slice. Slices stay the atomicity unit; the budget only decides where
     // the loop breathes.
     let sliceStartedAt = performance.now();
-    for (let index = 0; index < slices.length; index++) {
+    for (const [index, slice] of slices.entries()) {
       if (index > 0 && performance.now() - sliceStartedAt > APPLY_YIELD_BUDGET_MS) {
         pipelineDebug.phase = `apply-yield-${index}`;
         pipelineDebug.applyYields += 1;
@@ -538,7 +543,6 @@ async function flushDeltaBatchInner(
       }
       pipelineDebug.phase = `apply-slice-${index}`;
       pipelineDebug.applySlices += 1;
-      const slice = slices[index]!;
       if (hasApplyPlugins) {
         runStage(stagePlugins, 'apply', { changes: slice });
       } else {

package/src/local/sync/scopeGroups.ts

@@ -0,0 +1,91 @@
+import type { ClaimTarget } from '@abloatai/transaction/types/streams';
+import type { Schema } from '@abloatai/transaction/schema/schema';
+import { scopeKindOf, type ModelDef } from '@abloatai/transaction/schema/model';
+
+/** A schema-shaped selector used to narrow connection groups and presence reads. */
+export type GroupScope =
+  | ClaimTarget
+  | readonly ClaimTarget[]
+  | string
+  | readonly string[]
+  | { readonly syncGroup: string }
+  | { readonly syncGroups: readonly string[] }
+  | Record<string, string | readonly string[] | undefined>;
+
+/** Resolve an application-shaped scope into the wire groups owned by the schema. */
+export function resolveScopeGroups(
+  scope: GroupScope | undefined,
+  schema?: Schema,
+): string[] {
+  if (!scope) return [];
+  if (typeof scope === 'string') return [scope];
+  if (Array.isArray(scope)) {
+    const groups: string[] = [];
+    for (const entry of scope as readonly unknown[]) {
+      if (typeof entry === 'string') groups.push(entry);
+      else if (isEntityScope(entry)) groups.push(groupFromEntityRef(entry, schema));
+    }
+    return groups;
+  }
+  const direct = scope as { syncGroup?: unknown; syncGroups?: unknown };
+  if (isEntityScope(scope)) return [groupFromEntityRef(scope, schema)];
+  if (typeof direct.syncGroup === 'string') return [direct.syncGroup];
+  if (Array.isArray(direct.syncGroups)) {
+    return direct.syncGroups.filter((group): group is string => typeof group === 'string');
+  }
+  const groups: string[] = [];
+  for (const [key, value] of Object.entries(scope) as [string, unknown][]) {
+    if (value === undefined) continue;
+    if (Array.isArray(value)) {
+      for (const id of value as unknown[]) {
+        if (typeof id === 'string') groups.push(groupFromSchemaKey(key, id, schema));
+      }
+    } else if (typeof value === 'string') {
+      groups.push(groupFromSchemaKey(key, value, schema));
+    }
+  }
+  return groups;
+}
+
+export function groupFromEntityRef(ref: ClaimTarget, schema?: Schema): string {
+  const match = findModelForEntityRef(ref, schema);
+  const kind = match
+    ? groupKindForModel(match.def, match.key)
+    : ref.type.toLowerCase();
+  return `${kind}:${ref.id}`;
+}
+
+function groupFromSchemaKey(schemaKey: string, id: string, schema?: Schema): string {
+  const def = schema?.models[schemaKey];
+  const kind = def ? groupKindForModel(def, schemaKey) : schemaKey.toLowerCase();
+  return `${kind}:${id}`;
+}
+
+function groupKindForModel(def: ModelDef, key: string): string {
+  return scopeKindOf(def, key) ?? (def.typename ?? key).toLowerCase();
+}
+
+function findModelForEntityRef(
+  ref: ClaimTarget,
+  schema?: Schema,
+): { key: string; def: ModelDef } | null {
+  if (!schema?.models) return null;
+  const wanted = ref.type.toLowerCase();
+  for (const [key, def] of Object.entries(schema.models) as [string, ModelDef][]) {
+    const typename = def.typename ?? key;
+    if (typename.toLowerCase() === wanted || key.toLowerCase() === wanted) {
+      return { key, def };
+    }
+  }
+  return null;
+}
+
+function isEntityScope(scope: unknown): scope is ClaimTarget {
+  return (
+    typeof scope === 'object' &&
+    scope !== null &&
+    !Array.isArray(scope) &&
+    typeof (scope as { type?: unknown }).type === 'string' &&
+    typeof (scope as { id?: unknown }).id === 'string'
+  );
+}

package/src/local/sync/wsFrameHandlers.ts

@@ -12,7 +12,6 @@ export {
   wsFrameHandlers,
   dispatchWsFrame,
   type PendingCommit,
-  type PendingClaim,
   type PendingSubscription,
   type WsInboundFrame,
   type WsSession,

package/src/local/transactions/localMutation.ts

@@ -35,11 +35,11 @@ export function createLocalMutationPort(
   return {
     updates,
     applyCreate: (model, transaction) =>
-      track('optimistic:create', model, transaction),
+      { track('optimistic:create', model, transaction); },
     applyUpdate: (model, transaction) =>
-      track('optimistic:update', model, transaction),
+      { track('optimistic:update', model, transaction); },
     applyDelete: (model, transaction) =>
-      track('optimistic:delete', model, transaction),
+      { track('optimistic:delete', model, transaction); },
     rollback: (transaction, reason, error) => {
       const optimistic = updates.get(transaction.id);
       if (!optimistic) return Promise.resolve();

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

@@ -108,12 +108,8 @@ import { enqueueTransaction, type QueueCoalescingContext } from './queueCoalesci
 import { processBatch, type BatchProcessingContext } from './batchProcessing.js';
 import { handleFailure, type FailureHandlingContext } from './failureHandling.js';
 import { handleConflict as resolveConflict, isPermanentError as classifyPermanentError, isDefinitiveRejection as classifyDefinitiveRejection, type ConflictResolutionContext } from './failurePolicy.js';
-import { takeNextExecutionBatch as selectExecutionBatch, takePendingDrainBatch as selectPendingDrainBatch } from './executionSelection.js';
+import { takeNextExecutionBatch as selectExecutionBatch } from './executionSelection.js';
 import { scheduleProcessing as scheduleProcessingExternal, type ProcessingSchedulerContext } from './processingScheduler.js';
-import {
-  drainPendingConfirmations,
-  type PendingDrainContext,
-} from './pendingDrain.js';
 import { restoreDurableCommits as restoreDurableCommitsExternal, type DurableCommitRestoreContext } from './durableCommitRestore.js';
 
 // The queue is split across sibling modules (`commitPayload`,
@@ -244,6 +240,7 @@ export class MutationQueue extends EventEmitter {
   }[] = [];
   private persistenceStageScheduled = false;
   private pendingDrainPromise: Promise<void> | null = null;
+  private modelProcessingPromise: Promise<void> | null = null;
 
   private executionQueue: QueuedMutation[] = [];
   private isProcessing = false;
@@ -496,33 +493,6 @@ export class MutationQueue extends EventEmitter {
     };
   }
 
-  private get pendingDrainContext(): PendingDrainContext {
-    return {
-      runtime: this.runtime,
-      config: { deltaConfirmationTimeout: this.config.deltaConfirmationTimeout },
-      store: this.store,
-      executionQueue: this.executionQueue,
-      optimisticUpdates: this.localMutationPort.updates,
-      assertDurableReplayOpen: () => { this.assertDurableReplayOpen(); },
-      processCommitLane: () => this.processCommitLane(),
-      takePendingDrainBatch: (pending) => this.takePendingDrainBatch(pending),
-      ensureCommitEnvelope: (batch) => this.ensureCommitEnvelope(batch),
-      ensureDerivedFields: (transaction) => { this.ensureDerivedFields(transaction); },
-      sourceMutationIdsFor: (batch) => this.sourceMutationIdsFor(batch),
-      sealDurableCommit: (input) => this.sealDurableCommit(input),
-      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); },
-      recentDeltaCorrelations: this.recentDeltaCorrelations,
-      emit: (event, payload) => this.emit(event, payload),
-    };
-  }
-
   private get durableCommitRestoreContext(): DurableCommitRestoreContext {
     return {
       config: this.config,
@@ -1064,10 +1034,6 @@ export class MutationQueue extends EventEmitter {
     return selected.batch;
   }
 
-  private takePendingDrainBatch(pending: QueuedMutation[]): QueuedMutation[] {
-    return selectPendingDrainBatch(pending, this.config.maxBatchSize);
-  }
-
   /**
    * Resolvers for per-transaction `confirmation` promises. Populated in
    * `attachConfirmation` at staging time, consumed by the constructor-time
@@ -1361,22 +1327,15 @@ export class MutationQueue extends EventEmitter {
   }
 
   private async drainPendingInternal(): Promise<void> {
-    // The normal batch scheduler and the explicit/reconnect drain are two
-    // ways to drive the same durable queue. They must never seal the same
-    // staged source records concurrently: the first seal consumes those
-    // records, so the second would correctly reject them as already claimed.
-    //
-    // `isProcessing` is acquired synchronously before either path awaits,
-    // making it the queue-wide execution lock. If the normal lane already
-    // owns it, that lane will finish the pending work; callers waiting on a
-    // specific confirmation remain attached to the exact transaction.
-    if (this.isProcessing) return;
-    this.isProcessing = true;
-    try {
-      await drainPendingConfirmations(this.pendingDrainContext);
-    } finally {
-      this.isProcessing = false;
-      if (this.executionQueue.length > 0) this.scheduleProcessing(true);
+    // Explicit flushes and reconnects are merely another trigger for the one
+    // model-mutation execution lane. A second sealing implementation can race
+    // the scheduled lane, consume its journal sources, and later dispatch the
+    // same transaction again. Move every staged row to the owned queue, then
+    // drive the normal lane until the queue has handed off all current work.
+    this.commitCreatedTransactions();
+    await this.processCommitLane();
+    while (this.executionQueue.length > 0 || this.modelProcessingPromise) {
+      await this.processBatch();
     }
   }
   async create(
@@ -1445,7 +1404,19 @@ export class MutationQueue extends EventEmitter {
   }
 
   private async processBatch(): Promise<void> {
-    await processBatch(this.batchProcessingContext);
+    if (this.modelProcessingPromise) {
+      await this.modelProcessingPromise;
+      if (this.executionQueue.length > 0) await this.processBatch();
+      return;
+    }
+    const processing = processBatch(this.batchProcessingContext);
+    const tracked = processing.finally(() => {
+      if (this.modelProcessingPromise === tracked) {
+        this.modelProcessingPromise = null;
+      }
+    });
+    this.modelProcessingPromise = tracked;
+    await tracked;
   }
 
   private rememberDeltaCorrelation(correlationId: string, syncId: number): void {

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

@@ -133,16 +133,31 @@ export async function processBatch(ctx: BatchProcessingContext): Promise<void> {
           if (batchOps.length > 0) {
             let dispatchStarted = false;
             try {
-              const durableEnvelope = await ctx.sealDurableCommit({
-                idempotencyKey: commitIdempotencyKey,
-                origin: 'model_batch',
-                operations: batchOps.map(({ op }) => op),
-                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,
-              });
+              let durableEnvelope = batch[0]?.durableEnvelope;
+              if (durableEnvelope) {
+                const mismatched = batch.some(
+                  (transaction) =>
+                    transaction.durableEnvelope?.idempotencyKey !==
+                    durableEnvelope?.idempotencyKey,
+                );
+                if (mismatched || durableEnvelope.idempotencyKey !== commitIdempotencyKey) {
+                  throw new Error('Cannot replay a model batch with inconsistent durable envelopes');
+                }
+              } else {
+                durableEnvelope = await ctx.sealDurableCommit({
+                  idempotencyKey: commitIdempotencyKey,
+                  origin: 'model_batch',
+                  operations: batchOps.map(({ op }) => op),
+                  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,
+                });
+                for (const transaction of batch) {
+                  transaction.durableEnvelope = durableEnvelope;
+                }
+              }
               const operations = durableEnvelope.operations;
 
               // Capture lastSyncId from the server response for threshold-based

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

@@ -14,7 +14,10 @@ import type { RuntimeContext } from '../../RuntimeContext.js';
 import { MutationOperationType } from '@abloatai/transaction/types';
 import { snapshotJsonValue } from '@abloatai/transaction/utils/json';
 import type { MutationOptions, WriteOptions } from '../../interfaces/index.js';
-import type { CommitEnvelopeMember } from '@abloatai/transaction/commit';
+import type {
+  CommitEnvelopeMember,
+  DurableCommitEnvelope,
+} from '@abloatai/transaction/commit';
 
 export interface UserContext {
   userId: string;
@@ -123,6 +126,13 @@ export interface QueuedMutation {
    * re-batching its operations under a fresh key.
    */
   commitEnvelope?: CommitEnvelopeMember;
+  /**
+   * The exact durable request produced by the first successful local seal.
+   * Runtime retries dispatch this object directly. Asking the outbox to seal
+   * again is both unnecessary and unsafe after a concurrent authoritative
+   * completion has begun cleaning up the stored envelope.
+   */
+  durableEnvelope?: DurableCommitEnvelope;
   /** Pending-mutation journal entries atomically consumed by this envelope. */
   sourceMutationIds?: string[];
   /** Completed locally without a server operation; no sync echo will arrive. */

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

@@ -158,10 +158,10 @@ export function dispatchCommitBounded(
   const timeoutMs = ctx.config.commitDispatchTimeoutMs;
   if (!Number.isFinite(timeoutMs) || timeoutMs <= 0) return dispatched;
   return new Promise((resolve, reject) => {
-    const timer = setTimeout(() => reject(new AbloConnectionError(
+    const timer = setTimeout(() => { reject(new AbloConnectionError(
       'The mutation transport did not acknowledge the commit in time; its outcome remains pending and is safe to retry.',
       { code: 'commit_no_result' },
-    )), timeoutMs);
+    )); }, timeoutMs);
     dispatched.then(
       (value) => { clearTimeout(timer); resolve(value); },
       (error) => { clearTimeout(timer); reject(error instanceof Error ? error : new Error(String(error))); },

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) {