@abloatai/humans 0.60.0 → 0.61.0

package/src/local/SyncClient.ts

@@ -18,7 +18,7 @@ import { deepEqual, snapshotJsonValue } from '@abloatai/transaction/utils/json';
 import { LoadStrategy } from '@abloatai/transaction/types';
 import { globalRuntime } from './context.js';
 import type { RuntimeContext } from './RuntimeContext.js';
-import { AbloAuthenticationError, AbloError, AbloValidationError } from '@abloatai/transaction/errors';
+import { AbloError, AbloValidationError } from '@abloatai/transaction/errors';
 import { EventEmitter } from 'events';
 import { NetworkMonitor } from './NetworkMonitor.js';
 import {
@@ -51,9 +51,16 @@ import {
   type SyncState,
 } from './syncClientTypes.js';
 import type { BootstrapSnapshot } from './syncClientTypes.js';
+import {
+  batchUploadFiles,
+  uploadFile,
+  type BatchFileUploadOptions,
+  type FileUploadContext,
+  type FileUploadOptions,
+} from './fileUploads.js';
 
 export type { BootstrapSnapshot, RehydrationStats } from './syncClientTypes.js';
-
+const ignoreSeparatelyObservedMutationFailure = (): undefined => undefined;
 export class SyncClient extends EventEmitter {
   private objectPool: InstanceCache;
   private database: Database;
@@ -1057,7 +1064,7 @@ export class SyncClient extends EventEmitter {
     if (capturedChanges === undefined) return;
 
     this.objectPool.upsert(model, ModelScope.live);
-    this.stageMutation('update', model, capturedChanges);
+    void this.stageMutation('update', model, capturedChanges);
     this.notifyObservers({
       type: 'update',
       modelType: model.getModelName(),
@@ -1080,128 +1087,30 @@ export class SyncClient extends EventEmitter {
     return this.mutate('delete', model, () => this.objectPool.remove(model.id), options);
   }
 
-  /**
-   * Upload a file and create its attachment record. The upload runs through
-   * the {@link MutationQueue}, and a model is built from the server's
-   * response and added to the pool.
-   */
-  async uploadFile(
-    file: File,
-    options: {
-      id: string;
-      attachableType: string;
-      attachableId: string;
-      metadata?: Record<string, unknown>;
-    }
-  ): Promise<Model | null> {
-    if (!this.userId || !this.organizationId) {
-      throw new AbloAuthenticationError('Authentication required for file uploads', {
-        code: 'file_upload_auth_required',
-      });
-    }
-
-    try {
-      // Use MutationQueue to handle the upload mutation
-      const result = await this.mutationQueue.uploadAttachment(
-        file,
-        {
-          id: options.id,
-          attachableType: options.attachableType,
-          attachableId: options.attachableId,
-          metadata: options.metadata,
-        },
-        {
-          userId: this.userId,
-          organizationId: this.organizationId,
-        }
-      );
-
-      if (result) {
-        // Create model from response using ModelRegistry (generic — no concrete class import)
-        const model = this.objectPool.createFromData({
-          id: options.id,
-          ...result,
-        });
-
-        if (model) {
-          this.objectPool.add(model, ModelScope.live);
-          this.notifyObservers({
-            type: 'create',
-            modelType: model.getModelName(),
-            model,
-          });
-          return model;
-        }
-      }
-
-      return null;
-    } catch (error) {
-      this.runtime.observability.captureMutationFailure({
-        context: 'file-upload',
-        error: error instanceof Error ? error : new Error(String(error)),
-      });
-      throw error;
-    }
-  }
-
-  /**
-   * Batch upload files — single GraphQL call + parallel S3 PUTs.
-   *
-   * Returns the raw `Model[]` built by the object pool (typename is
-   * determined by the payload the server returns — currently always
-   * `Attachment`). The SDK has no knowledge of app-specific model classes,
-   * so it cannot honestly claim a narrower return type; consumers that
-   * need an `Attachment[]` project through their own typed accessor
-   * (e.g. `store.query.attachments.findMany({ where: { id: IN ids } })`)
-   * after the upload resolves.
-   */
-  async batchUploadFiles(
-    files: File[],
-    options: {
-      ids: string[];
-      attachableType: string;
-      attachableId: string;
-      metadata?: Record<string, unknown>;
-    }
-  ): Promise<Model[]> {
-    if (!this.userId || !this.organizationId) {
-      throw new AbloAuthenticationError('Authentication required for file uploads', {
-        code: 'file_upload_auth_required',
-      });
-    }
-
-    const items = options.ids.map((id) => ({
-      id,
-      attachableType: options.attachableType,
-      attachableId: options.attachableId,
-      metadata: options.metadata,
-    }));
-
-    const results = await this.mutationQueue.batchUploadAttachments(files, items, {
+  private fileUploadContext(): FileUploadContext {
+    return {
       userId: this.userId,
       organizationId: this.organizationId,
-    });
+      mutationQueue: this.mutationQueue,
+      objectPool: this.objectPool,
+      observability: this.runtime.observability,
+      notifyCreated: (model) => {
+        this.notifyObservers({ type: 'create', modelType: model.getModelName(), model });
+      },
+    };
+  }
 
-    const models: Model[] = [];
-    for (const result of results) {
-      const model = this.objectPool.createFromData({ ...result });
-      if (model) {
-        this.objectPool.add(model, ModelScope.live);
-        this.notifyObservers({
-          type: 'create',
-          modelType: model.getModelName(),
-          model,
-        });
-        models.push(model);
-      }
-    }
+  uploadFile(file: File, options: FileUploadOptions): Promise<Model | null> {
+    return uploadFile(this.fileUploadContext(), file, options);
+  }
 
-    return models;
+  batchUploadFiles(files: File[], options: BatchFileUploadOptions): Promise<Model[]> {
+    return batchUploadFiles(this.fileUploadContext(), files, options);
   }
 
   /** Archive model (ARCHIVE) - works offline */
-  archive(model: Model): void {
-    this.mutate('archive', model, () => { this.objectPool.updateScope(model.id, ModelScope.archived); });
+  archive(model: Model): Promise<void> | undefined {
+    return this.mutate('archive', model, () => { this.objectPool.updateScope(model.id, ModelScope.archived); });
   }
 
   /**
@@ -1243,7 +1152,7 @@ export class SyncClient extends EventEmitter {
     // Most internal callers intentionally use fire-and-forget writes. Observe
     // their rejection without replacing the exact promise returned to model
     // operations that need authoritative per-transaction confirmation.
-    void confirmation.catch(() => undefined);
+    void confirmation.catch(ignoreSeparatelyObservedMutationFailure);
     const pending = staging.then(() => undefined).catch((error: Error) => {
       this.runtime.observability.captureMutationFailure({
         context: `stage-mutation-${type}`,
@@ -1495,14 +1404,11 @@ export class SyncClient extends EventEmitter {
   markConnected(): void {
     this.setConnectionState('connected');
     // Browser online state may have marked the client connected before the
-    // WebSocket itself was ready. Always kick both durable lanes on the real
-    // socket event, even when the high-level state did not change.
-    void this.drainPendingConfirmations().catch((error: unknown) => {
-      this.runtime.observability.captureMutationFailure({
-        context: 'restore-commit-outbox',
-        error: error instanceof Error ? error : new Error(String(error)),
-      });
-    });
+    // WebSocket itself was ready. Kick the durable lanes through the staging
+    // barrier: a model mutation enters the in-memory store before its journal
+    // row finishes saving, so a direct reconnect drain can otherwise try to
+    // seal a source record that does not exist yet. The pending drain also
+    // starts the atomic commit lane, so one ordered entry point covers both.
     void this.processPendingMutations();
   }
 

package/src/local/client/createModelOperations.ts

@@ -149,6 +149,9 @@ import {
   type ReadSetContext,
 } from '@abloatai/transaction/internal/read-set';
 
+const ignoreSeparatelyObservedMutationFailure = (): undefined => undefined;
+const ignoreBestEffortClaimReleaseFailure = (): undefined => undefined;
+
 export interface ModelClientMeta {
   readonly key: string;
   readonly typename: string;
@@ -490,7 +493,7 @@ export function createModelOperations<T, C>(
       // await does not create an unhandled-rejection process error. Returning
       // the original promise preserves normal rejection for callers that do
       // await or attach their own catch handler.
-      void confirmation.catch(() => undefined);
+      void confirmation.catch(ignoreSeparatelyObservedMutationFailure);
       return confirmation;
     };
   };
@@ -660,9 +663,9 @@ export function createModelOperations<T, C>(
     // This runs after authoritative confirmation. A best-effort abandon frame
     // cannot turn a committed write into an apparent failure; the server has
     // already fulfilled the participant's claims as part of that commit.
-    await releaseClaimsForEntity(entityId).catch(() => undefined);
+    await releaseClaimsForEntity(entityId).catch(ignoreBestEffortClaimReleaseFailure);
     if (explicit && !explicitWasLocal) {
-      await explicit.release?.().catch(() => undefined);
+      await explicit.release?.().catch(ignoreBestEffortClaimReleaseFailure);
     }
   };
 
@@ -1376,7 +1379,7 @@ export function createModelOperations<T, C>(
         await waitForMutation(model, confirmation);
         return modelAsRow<T>(model);
       } finally {
-        await autoLease?.release?.().catch(() => {});
+        await autoLease?.release?.().catch(ignoreBestEffortClaimReleaseFailure);
       }
   });
 
@@ -1501,7 +1504,7 @@ export function createModelOperations<T, C>(
               const confirmation = syncClient.update(
                 model,
                 effective,
-                patch as Record<string, unknown>,
+                patch,
               );
               await waitForMutation(model, confirmation);
               return modelAsRow<T>(model);
@@ -1562,7 +1565,7 @@ export function createModelOperations<T, C>(
         const confirmation = syncClient.update(
           model,
           effective,
-          params.data as Record<string, unknown>,
+          params.data,
         );
         await waitForMutation(model, confirmation);
         const updated = modelAsRow<T>(model);

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/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/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/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))); },