deepline 0.3.127 → 0.3.129

package/dist/bundling-sources/shared_libs/play-runtime/runtime-receipt-writer.ts

@@ -8,20 +8,36 @@ type PendingWrite<Input, Output> = {
   input: Input;
   bytes: number;
   signal: AbortSignal | null;
-  state: 'blocked' | 'queued' | 'active' | 'settled';
+  state: 'queued' | 'active' | 'settled';
   aborted: unknown;
   onAbort: (() => void) | null;
   resolve: (output: Output) => void;
   reject: (error: unknown) => void;
 };
 
+type CapacityWaiter = {
+  promise: Promise<void>;
+  resolve: () => void;
+  reject: (error: unknown) => void;
+};
+
 export type RuntimeReceiptWriterStats = {
+  /** True while at least one batch is in flight. */
   active: boolean;
+  /** Batches currently in flight (bounded by `maxInFlightBatches`). */
+  inFlightBatches: number;
   queued: number;
-  blocked: number;
+  /** Inputs retained by queued or active physical batches. */
+  bufferedItems: number;
   bufferedBytes: number;
 };
 
+/** Optional retained-input budget reserved for one transport lane. */
+export type RuntimeReceiptWriterLaneBufferLimit = {
+  items?: number;
+  bytes?: number;
+};
+
 export type RuntimeReceiptWriterRetryEvent<Input> = {
   phase: 'retry' | 'recovered';
   attempt: number;
@@ -32,7 +48,7 @@ export type RuntimeReceiptWriterRetryEvent<Input> = {
   elapsedMs: number;
   retryAfterMs: number;
   queued: number;
-  blocked: number;
+  bufferedItems: number;
   bufferedBytes: number;
   error?: unknown;
 };
@@ -50,6 +66,24 @@ export class RuntimeReceiptWriterBufferLimitError extends Error {
   }
 }
 
+/**
+ * The writer rejected a new command before retaining its payload. The caller
+ * still owns the durable retry decision; a hidden waiter list must never turn
+ * this explicit backpressure into unbounded process memory.
+ */
+export class RuntimeReceiptWriterCapacityError extends Error {
+  constructor(
+    readonly limit: 'items' | 'bytes',
+    readonly current: number,
+    readonly maximum: number,
+  ) {
+    super(
+      `Runtime receipt writer ${limit} capacity is full (${current}/${maximum}); retry after a physical batch settles.`,
+    );
+    this.name = 'RuntimeReceiptWriterCapacityError';
+  }
+}
+
 export class RuntimeReceiptWriterResultCountError extends Error {
   constructor(
     readonly inputCount: number,
@@ -94,6 +128,12 @@ export class RuntimeReceiptWriterRetryDeadlineError extends Error {
  */
 export class RuntimeReceiptWriter<Input, Output> {
   readonly #batchKey: (input: Input) => unknown;
+  readonly #batchLane: (input: Input) => string;
+  /**
+   * Receipt identities whose commands cannot overlap in transport. Callers
+   * opt into this only when they use more than one in-flight batch.
+   */
+  readonly #orderingKeys: (input: Input) => readonly unknown[];
   readonly #send: (
     inputs: readonly Input[],
     options: { signal: AbortSignal },
@@ -105,23 +145,42 @@ export class RuntimeReceiptWriter<Input, Output> {
   readonly #maxBatchSize: number;
   readonly #maxBatchBytes: number;
   readonly #targetBatchBytes: number;
+  readonly #maxBufferedItems: number;
   readonly #maxBufferedBytes: number;
   readonly #maxFlushMs: number;
+  readonly #maxInFlightBatches: number;
+  readonly #maxInFlightBatchesByLane: ReadonlyMap<string, number>;
+  readonly #maxBufferedByLane: ReadonlyMap<
+    string,
+    Required<RuntimeReceiptWriterLaneBufferLimit>
+  >;
   readonly #maxRetryElapsedMs: number;
   readonly #onRetryEvent:
     | ((event: RuntimeReceiptWriterRetryEvent<Input>) => void)
     | null;
+  readonly #onBufferedBytesChanged: ((bufferedBytes: number) => void) | null;
+  /**
+   * A bounded state snapshot for diagnostics. Observers can see pressure but
+   * cannot influence admission or durable delivery.
+   */
+  readonly #onStatsChanged: ((stats: RuntimeReceiptWriterStats) => void) | null;
   readonly #queued: Array<PendingWrite<Input, Output>> = [];
-  readonly #blocked: Array<PendingWrite<Input, Output>> = [];
   readonly #closeController = new AbortController();
 
+  #bufferedItems = 0;
   #bufferedBytes = 0;
   #nextBatchId = 0;
-  #activeBatch: Array<PendingWrite<Input, Output>> | null = null;
-  #pump: Promise<void> | null = null;
+  #inFlight = new Set<Promise<void>>();
+  readonly #inFlightBatchesByLane = new Map<string, number>();
+  readonly #bufferedByLane = new Map<
+    string,
+    Required<RuntimeReceiptWriterLaneBufferLimit>
+  >();
+  readonly #activeOrderingKeys: unknown[] = [];
   #flushTimer: ReturnType<typeof setTimeout> | null = null;
   #closed = false;
   #closeReason: unknown = null;
+  #capacityWaiter: CapacityWaiter | null = null;
   #drainWaiters: Array<{
     resolve: () => void;
     reject: (error: unknown) => void;
@@ -129,6 +188,12 @@ export class RuntimeReceiptWriter<Input, Output> {
 
   constructor(options: {
     batchKey: (input: Input) => unknown;
+    /**
+     * Optional transport lane. Per-lane limits reserve bounded control
+     * capacity without exposing queues to receipt-domain callers.
+     */
+    batchLane?: (input: Input) => string;
+    orderingKeys?: (input: Input) => readonly unknown[];
     send: (
       inputs: readonly Input[],
       options: { signal: AbortSignal },
@@ -138,12 +203,37 @@ export class RuntimeReceiptWriter<Input, Output> {
     maxBatchSize?: number;
     maxBatchBytes?: number;
     targetBatchBytes?: number;
+    maxBufferedItems?: number;
     maxBufferedBytes?: number;
     maxFlushMs?: number;
+    /**
+     * Concurrent transport requests this writer may hold open. Ordering across
+     * batches is NOT preserved: every receipt command is keyed, so the store
+     * is the ordering authority. Default 1 keeps the historical strictly
+     * serialized pump.
+     */
+    maxInFlightBatches?: number;
+    /** Maximum simultaneous physical batches per named `batchLane`. */
+    maxInFlightBatchesByLane?: Readonly<Record<string, number>>;
+    /** Retained item/byte budgets reserved for named `batchLane`s. */
+    maxBufferedByLane?: Readonly<
+      Record<string, RuntimeReceiptWriterLaneBufferLimit>
+    >;
     maxRetryElapsedMs?: number;
     onRetryEvent?: (event: RuntimeReceiptWriterRetryEvent<Input>) => void;
+    /**
+     * Called with the writer's buffered byte total every time it changes. The
+     * writer is the only component that knows how many serialized completion
+     * bytes it is holding, so the runtime's byte ledger reads them from here
+     * rather than measuring the same payloads a second time.
+     */
+    onBufferedBytesChanged?: (bufferedBytes: number) => void;
+    /** Emits after this writer's retained/active state changes. */
+    onStatsChanged?: (stats: RuntimeReceiptWriterStats) => void;
   }) {
     this.#batchKey = options.batchKey;
+    this.#batchLane = options.batchLane ?? (() => 'default');
+    this.#orderingKeys = options.orderingKeys ?? (() => []);
     this.#send = options.send;
     this.#classifyRetryableError =
       options.classifyRetryableError ?? (() => null);
@@ -162,11 +252,84 @@ export class RuntimeReceiptWriter<Input, Output> {
       this.#maxBatchBytes,
     );
     this.#maxFlushMs = Math.max(0, Math.floor(options.maxFlushMs ?? 5));
+    this.#maxInFlightBatches = normalizePositiveInteger(
+      options.maxInFlightBatches,
+      1,
+    );
+    this.#maxInFlightBatchesByLane = new Map(
+      Object.entries(options.maxInFlightBatchesByLane ?? {}).map(
+        ([lane, maximum]) => [
+          normalizeLane(lane),
+          normalizePositiveInteger(maximum, 1),
+        ],
+      ),
+    );
+    this.#maxBufferedByLane = new Map(
+      Object.entries(options.maxBufferedByLane ?? {}).flatMap(
+        ([lane, limits]) => {
+          const items =
+            limits.items === undefined
+              ? undefined
+              : normalizePositiveInteger(limits.items, 1);
+          const bytes =
+            limits.bytes === undefined
+              ? undefined
+              : normalizePositiveInteger(limits.bytes, 1);
+          return items === undefined && bytes === undefined
+            ? []
+            : [
+                [
+                  normalizeLane(lane),
+                  {
+                    items: items ?? Number.MAX_SAFE_INTEGER,
+                    bytes: bytes ?? Number.MAX_SAFE_INTEGER,
+                  },
+                ] as const,
+              ];
+        },
+      ),
+    );
+    this.#maxBufferedItems = normalizePositiveInteger(
+      options.maxBufferedItems,
+      // A generic writer accepts one ordinary bulk receipt request by default;
+      // the Release Worker supplies its larger, release-specific bound.
+      Math.max(this.#maxBatchSize * this.#maxInFlightBatches * 2, 1_000),
+    );
     this.#maxRetryElapsedMs = normalizePositiveInteger(
       options.maxRetryElapsedMs,
       2 * 60_000,
     );
     this.#onRetryEvent = options.onRetryEvent ?? null;
+    this.#onBufferedBytesChanged = options.onBufferedBytesChanged ?? null;
+    this.#onStatsChanged = options.onStatsChanged ?? null;
+  }
+
+  #adjustBufferedBytes(deltaBytes: number): void {
+    if (deltaBytes === 0) return;
+    this.#bufferedBytes += deltaBytes;
+    this.#onBufferedBytesChanged?.(this.#bufferedBytes);
+  }
+
+  #adjustBufferedItems(deltaItems: number, lane: string): void {
+    if (deltaItems === 0) return;
+    this.#bufferedItems += deltaItems;
+    this.#adjustBufferedLane(lane, { items: deltaItems, bytes: 0 });
+  }
+
+  #adjustBufferedLane(
+    lane: string,
+    delta: Required<RuntimeReceiptWriterLaneBufferLimit>,
+  ): void {
+    const current = this.#bufferedByLane.get(lane) ?? { items: 0, bytes: 0 };
+    const next = {
+      items: current.items + delta.items,
+      bytes: current.bytes + delta.bytes,
+    };
+    if (next.items === 0 && next.bytes === 0) {
+      this.#bufferedByLane.delete(lane);
+      return;
+    }
+    this.#bufferedByLane.set(lane, next);
   }
 
   write(input: Input, options: { signal?: AbortSignal } = {}): Promise<Output> {
@@ -188,13 +351,60 @@ export class RuntimeReceiptWriter<Input, Output> {
     if (options.signal?.aborted) {
       return Promise.reject(abortReason(options.signal));
     }
+    const lane = this.#laneFor(input);
+    const laneLimit = this.#maxBufferedByLane.get(lane);
+    if (laneLimit && bytes > laneLimit.bytes) {
+      return Promise.reject(
+        new RuntimeReceiptWriterBufferLimitError(bytes, laneLimit.bytes),
+      );
+    }
+    if (this.#bufferedItems >= this.#maxBufferedItems) {
+      return Promise.reject(
+        new RuntimeReceiptWriterCapacityError(
+          'items',
+          this.#bufferedItems,
+          this.#maxBufferedItems,
+        ),
+      );
+    }
+    if (!this.#canBuffer(bytes)) {
+      return Promise.reject(
+        new RuntimeReceiptWriterCapacityError(
+          'bytes',
+          this.#bufferedBytes,
+          this.#maxBufferedBytes,
+        ),
+      );
+    }
+    const laneBuffered = this.#bufferedByLane.get(lane) ?? {
+      items: 0,
+      bytes: 0,
+    };
+    if (laneLimit && laneBuffered.items >= laneLimit.items) {
+      return Promise.reject(
+        new RuntimeReceiptWriterCapacityError(
+          'items',
+          laneBuffered.items,
+          laneLimit.items,
+        ),
+      );
+    }
+    if (laneLimit && laneBuffered.bytes + bytes > laneLimit.bytes) {
+      return Promise.reject(
+        new RuntimeReceiptWriterCapacityError(
+          'bytes',
+          laneBuffered.bytes,
+          laneLimit.bytes,
+        ),
+      );
+    }
 
     return new Promise<Output>((resolve, reject) => {
       const pending: PendingWrite<Input, Output> = {
         input,
         bytes,
         signal: options.signal ?? null,
-        state: 'blocked',
+        state: 'queued',
         aborted: null,
         onAbort: null,
         resolve,
@@ -205,14 +415,52 @@ export class RuntimeReceiptWriter<Input, Output> {
         once: true,
       });
 
-      if (this.#canBuffer(bytes)) {
-        this.#accept(pending);
-      } else {
-        this.#blocked.push(pending);
-      }
+      this.#accept(pending);
     });
   }
 
+  /**
+   * Wait until a rejected caller may retry its own input without making the
+   * writer retain that input. All callers share one progress promise; the
+   * caller continues to own its command and abort signal.
+   */
+  waitForCapacity(
+    input: Input,
+    options: { signal?: AbortSignal } = {},
+  ): Promise<void> {
+    if (this.#closed) {
+      return Promise.reject(
+        this.#closeReason ?? new RuntimeReceiptWriterClosedError(),
+      );
+    }
+    if (options.signal?.aborted) {
+      return Promise.reject(abortReason(options.signal));
+    }
+
+    const bytes = Math.max(0, Math.ceil(this.#estimateBytes(input)));
+    if (bytes > this.#maxBufferedBytes || bytes > this.#maxBatchBytes) {
+      return Promise.reject(
+        new RuntimeReceiptWriterBufferLimitError(
+          bytes,
+          Math.min(this.#maxBufferedBytes, this.#maxBatchBytes),
+        ),
+      );
+    }
+    const lane = this.#laneFor(input);
+    const laneLimit = this.#maxBufferedByLane.get(lane);
+    if (laneLimit && bytes > laneLimit.bytes) {
+      return Promise.reject(
+        new RuntimeReceiptWriterBufferLimitError(bytes, laneLimit.bytes),
+      );
+    }
+    this.#startPump();
+    if (this.#canAccept(bytes, lane)) return Promise.resolve();
+
+    const waiter = this.#capacityWaiter ?? this.#createCapacityWaiter();
+    if (!options.signal) return waiter.promise;
+    return this.#waitForCapacityOrAbort(waiter.promise, options.signal);
+  }
+
   async flush(): Promise<void> {
     this.#clearFlushTimer();
     this.#startPump();
@@ -229,6 +477,7 @@ export class RuntimeReceiptWriter<Input, Output> {
         reason === undefined ? new RuntimeReceiptWriterClosedError() : reason;
       if (reason !== undefined) {
         this.#closeController.abort(reason);
+        this.#rejectCapacityWaiter(reason);
         this.#rejectWaiting(reason);
       }
     }
@@ -236,29 +485,61 @@ export class RuntimeReceiptWriter<Input, Output> {
       await this.flush();
       return;
     }
-    if (this.#pump) await this.#pump;
+    // A forced close must not return while any batch still holds transport.
+    while (this.#inFlight.size > 0) {
+      await Promise.allSettled([...this.#inFlight]);
+    }
   }
 
   getStats(): RuntimeReceiptWriterStats {
     return {
-      active: this.#activeBatch !== null,
+      active: this.#inFlight.size > 0,
+      inFlightBatches: this.#inFlight.size,
       queued: this.#queued.length,
-      blocked: this.#blocked.length,
+      bufferedItems: this.#bufferedItems,
       bufferedBytes: this.#bufferedBytes,
     };
   }
 
+  #notifyStatsChanged(): void {
+    if (!this.#onStatsChanged) return;
+    try {
+      this.#onStatsChanged(this.getStats());
+    } catch {
+      // Receipt observability must never affect durable delivery.
+    }
+  }
+
   #canBuffer(bytes: number): boolean {
     return this.#bufferedBytes + bytes <= this.#maxBufferedBytes;
   }
 
+  #canAccept(bytes: number, lane: string): boolean {
+    if (this.#bufferedItems >= this.#maxBufferedItems) return false;
+    if (!this.#canBuffer(bytes)) return false;
+    const laneLimit = this.#maxBufferedByLane.get(lane);
+    const laneBuffered = this.#bufferedByLane.get(lane) ?? {
+      items: 0,
+      bytes: 0,
+    };
+    return (
+      !laneLimit ||
+      (laneBuffered.items < laneLimit.items &&
+        laneBuffered.bytes + bytes <= laneLimit.bytes)
+    );
+  }
+
   #accept(pending: PendingWrite<Input, Output>): void {
     pending.state = 'queued';
     this.#queued.push(pending);
-    this.#bufferedBytes += pending.bytes;
+    const lane = this.#laneFor(pending.input);
+    this.#adjustBufferedItems(1, lane);
+    this.#adjustBufferedBytes(pending.bytes);
+    this.#adjustBufferedLane(lane, { items: 0, bytes: pending.bytes });
+    this.#notifyStatsChanged();
     if (
       this.#queued.length >= this.#maxBatchSize ||
-      this.#queuedBytesAtHead() >= this.#targetBatchBytes
+      this.#nextBatchBytes() >= this.#targetBatchBytes
     ) {
       this.#clearFlushTimer();
       this.#startPump();
@@ -267,8 +548,17 @@ export class RuntimeReceiptWriter<Input, Output> {
     this.#scheduleFlush();
   }
 
+  /**
+   * Open a batching window so results settling within it share one request.
+   * The window is a fixed delay from the first queued arrival, not a resetting
+   * debounce: a continuous producer must never starve the queue. Size and byte
+   * triggers in `#accept` bypass the window entirely, and a batch that lands
+   * while the writer is saturated is picked up by the completing batch's own
+   * `#startPump`, so under load the window adds no latency.
+   */
   #scheduleFlush(): void {
-    if (this.#pump || this.#flushTimer || this.#queued.length === 0) return;
+    if (this.#flushTimer || this.#queued.length === 0) return;
+    if (!this.#hasFlightCapacity()) return;
     this.#flushTimer = setTimeout(() => {
       this.#flushTimer = null;
       this.#startPump();
@@ -276,83 +566,225 @@ export class RuntimeReceiptWriter<Input, Output> {
   }
 
   #startPump(): void {
-    if (this.#pump || this.#queued.length === 0) {
-      this.#notifyDrained();
-      return;
+    while (this.#queued.length > 0 && this.#hasFlightCapacity()) {
+      const batch = this.#takeBatchIfOrderAllows();
+      // An empty batch means every queued receipt conflicts with an active
+      // ordering key or belongs to a lane whose bounded capacity is full.
+      if (batch.length === 0) break;
+      this.#launchBatch(batch);
     }
-    this.#pump = this.#runPump().finally(() => {
-      this.#pump = null;
-      if (this.#queued.length > 0) this.#startPump();
-      else this.#notifyDrained();
-    });
+    if (this.#inFlight.size === 0) this.#notifyDrained();
   }
 
-  async #runPump(): Promise<void> {
-    while (this.#queued.length > 0) {
-      const batch = this.#takeBatch();
-      if (batch.length === 0) continue;
-      const batchId = ++this.#nextBatchId;
-      this.#activeBatch = batch;
-      try {
-        const outputs = await this.#sendWithRetry(batch, batchId);
-        if (outputs.length !== batch.length) {
-          throw new RuntimeReceiptWriterResultCountError(
-            batch.length,
-            outputs.length,
+  #launchBatch(batch: Array<PendingWrite<Input, Output>>): void {
+    const batchId = ++this.#nextBatchId;
+    const lane = this.#laneFor(batch[0]!.input);
+    const orderingKeys = this.#orderingKeysFor(batch);
+    this.#activeOrderingKeys.push(...orderingKeys);
+    this.#incrementInFlightLane(lane);
+    // Annotated: the callback below closes over `inFlight`, so inference
+    // would otherwise be circular.
+    const inFlight: Promise<void> = this.#runBatch(batch, batchId).finally(
+      () => {
+        this.#inFlight.delete(inFlight);
+        for (const key of orderingKeys) {
+          const index = this.#activeOrderingKeys.findIndex((active) =>
+            Object.is(active, key),
           );
+          if (index >= 0) this.#activeOrderingKeys.splice(index, 1);
         }
-        batch.forEach((pending, index) => {
-          if (pending.aborted !== null) {
-            this.#settleRejected(pending, pending.aborted);
-          } else {
-            this.#settleResolved(pending, outputs[index]!);
-          }
-        });
-      } catch (error) {
-        batch.forEach((pending) => {
-          this.#settleRejected(
-            pending,
-            pending.aborted !== null ? pending.aborted : error,
-          );
-        });
-      } finally {
-        this.#activeBatch = null;
         for (const pending of batch) {
-          this.#bufferedBytes -= pending.bytes;
+          this.#adjustBufferedItems(-1, this.#laneFor(pending.input));
+          this.#adjustBufferedBytes(-pending.bytes);
+          this.#adjustBufferedLane(this.#laneFor(pending.input), {
+            items: 0,
+            bytes: -pending.bytes,
+          });
         }
-        this.#admitBlocked();
+        this.#decrementInFlightLane(lane);
+        this.#notifyStatsChanged();
+        this.#resolveCapacityWaiter();
+        if (this.#queued.length > 0) this.#startPump();
+        else if (this.#inFlight.size === 0) this.#notifyDrained();
+      },
+    );
+    this.#inFlight.add(inFlight);
+    this.#notifyStatsChanged();
+  }
+
+  async #runBatch(
+    batch: Array<PendingWrite<Input, Output>>,
+    batchId: number,
+  ): Promise<void> {
+    try {
+      const outputs = await this.#sendWithRetry(batch, batchId);
+      if (outputs.length !== batch.length) {
+        throw new RuntimeReceiptWriterResultCountError(
+          batch.length,
+          outputs.length,
+        );
       }
+      batch.forEach((pending, index) => {
+        if (pending.aborted !== null) {
+          this.#settleRejected(pending, pending.aborted);
+        } else {
+          this.#settleResolved(pending, outputs[index]!);
+        }
+      });
+    } catch (error) {
+      batch.forEach((pending) => {
+        this.#settleRejected(
+          pending,
+          pending.aborted !== null ? pending.aborted : error,
+        );
+      });
     }
   }
 
-  #takeBatch(): Array<PendingWrite<Input, Output>> {
-    while (this.#queued[0]?.aborted !== null) {
-      const aborted = this.#queued.shift()!;
-      this.#bufferedBytes -= aborted.bytes;
-      this.#settleRejected(aborted, aborted.aborted);
-      this.#admitBlocked();
+  #takeBatchIfOrderAllows(): Array<PendingWrite<Input, Output>> {
+    this.#rejectAbortedQueued();
+    const indices = this.#selectRunnableBatchIndices();
+    if (indices.length === 0) return [];
+    const batch = indices.map((index) => this.#queued[index]!);
+    for (let index = indices.length - 1; index >= 0; index -= 1) {
+      this.#queued.splice(indices[index]!, 1);
     }
-    const first = this.#queued[0];
-    if (!first) return [];
+    for (const pending of batch) pending.state = 'active';
+    return batch;
+  }
 
-    const key = this.#batchKey(first.input);
-    const batch: Array<PendingWrite<Input, Output>> = [];
+  /**
+   * Select the first FIFO-ready batch. A command blocked only because its
+   * receipt is active may be bypassed so an independent receipt can use a
+   * free flight. A normally ready command is never bypassed: that keeps the
+   * historical FIFO ordering for callers that did not provide ordering keys.
+   */
+  #selectRunnableBatchIndices(): number[] {
+    const skippedOrderingKeys: unknown[] = [];
+    const selected: number[] = [];
+    let selectedBatchKey: unknown;
+    let selectedLane: string | null = null;
     let batchBytes = 0;
-    while (batch.length < this.#maxBatchSize) {
-      const next = this.#queued[0];
-      if (!next || !Object.is(this.#batchKey(next.input), key)) break;
+
+    for (let index = 0; index < this.#queued.length; index += 1) {
+      const pending = this.#queued[index]!;
+      if (pending.aborted !== null) continue;
+      const orderingKeys = this.#orderingKeys(pending.input);
+      const blockedByOrder = this.#orderingKeysConflict(
+        orderingKeys,
+        skippedOrderingKeys,
+      );
+      const blockedByActive = this.#orderingKeysConflict(
+        orderingKeys,
+        this.#activeOrderingKeys,
+      );
+      const lane = this.#laneFor(pending.input);
+      const laneAvailable = this.#hasFlightCapacity(lane);
+
+      if (selected.length === 0) {
+        if (blockedByOrder || blockedByActive || !laneAvailable) {
+          skippedOrderingKeys.push(...orderingKeys);
+          continue;
+        }
+        selected.push(index);
+        selectedBatchKey = this.#batchKey(pending.input);
+        selectedLane = lane;
+        batchBytes = pending.bytes;
+        continue;
+      }
+
+      // A ready, incompatible command is an ordinary FIFO boundary. It must
+      // run before any later command, even one that could share this batch.
+      if (blockedByOrder || blockedByActive || !laneAvailable) {
+        skippedOrderingKeys.push(...orderingKeys);
+        continue;
+      }
       if (
-        batch.length > 0 &&
-        batchBytes + next.bytes > this.#targetBatchBytes
+        selectedLane !== lane ||
+        !Object.is(this.#batchKey(pending.input), selectedBatchKey) ||
+        selected.length >= this.#maxBatchSize ||
+        batchBytes + pending.bytes > this.#targetBatchBytes
       ) {
         break;
       }
-      this.#queued.shift();
-      next.state = 'active';
-      batch.push(next);
-      batchBytes += next.bytes;
+      selected.push(index);
+      batchBytes += pending.bytes;
     }
-    return batch;
+    return selected;
+  }
+
+  #rejectAbortedQueued(): void {
+    let changed = false;
+    for (let index = this.#queued.length - 1; index >= 0; index -= 1) {
+      const pending = this.#queued[index]!;
+      if (pending.aborted === null) continue;
+      this.#queued.splice(index, 1);
+      this.#adjustBufferedItems(-1, this.#laneFor(pending.input));
+      this.#adjustBufferedBytes(-pending.bytes);
+      this.#adjustBufferedLane(this.#laneFor(pending.input), {
+        items: 0,
+        bytes: -pending.bytes,
+      });
+      this.#settleRejected(pending, pending.aborted);
+      changed = true;
+    }
+    if (changed) this.#notifyStatsChanged();
+  }
+
+  #nextBatchBytes(): number {
+    this.#rejectAbortedQueued();
+    return this.#selectRunnableBatchIndices().reduce(
+      (total, index) => total + this.#queued[index]!.bytes,
+      0,
+    );
+  }
+
+  #orderingKeysConflict(
+    candidate: readonly unknown[],
+    existing: readonly unknown[],
+  ): boolean {
+    return candidate.some((key) =>
+      existing.some((active) => Object.is(active, key)),
+    );
+  }
+
+  #laneFor(input: Input): string {
+    return normalizeLane(this.#batchLane(input));
+  }
+
+  #hasFlightCapacity(lane?: string): boolean {
+    if (this.#inFlight.size >= this.#maxInFlightBatches) return false;
+    if (lane === undefined) return true;
+    const maximum = this.#maxInFlightBatchesByLane.get(lane);
+    return (
+      maximum === undefined ||
+      (this.#inFlightBatchesByLane.get(lane) ?? 0) < maximum
+    );
+  }
+
+  #incrementInFlightLane(lane: string): void {
+    this.#inFlightBatchesByLane.set(
+      lane,
+      (this.#inFlightBatchesByLane.get(lane) ?? 0) + 1,
+    );
+  }
+
+  #decrementInFlightLane(lane: string): void {
+    const current = this.#inFlightBatchesByLane.get(lane) ?? 0;
+    if (current <= 1) this.#inFlightBatchesByLane.delete(lane);
+    else this.#inFlightBatchesByLane.set(lane, current - 1);
+  }
+
+  #orderingKeysFor(batch: readonly PendingWrite<Input, Output>[]): unknown[] {
+    const keys: unknown[] = [];
+    for (const pending of batch) {
+      for (const key of this.#orderingKeys(pending.input)) {
+        if (!keys.some((existing) => Object.is(existing, key))) {
+          keys.push(key);
+        }
+      }
+    }
+    return keys;
   }
 
   async #sendWithRetry(
@@ -445,7 +877,7 @@ export class RuntimeReceiptWriter<Input, Output> {
         elapsedMs: Date.now() - input.startedAt,
         retryAfterMs: input.retryAfterMs,
         queued: this.#queued.length,
-        blocked: this.#blocked.length,
+        bufferedItems: this.#bufferedItems,
         bufferedBytes: this.#bufferedBytes,
         ...(input.error === undefined ? {} : { error: input.error }),
       });
@@ -501,32 +933,23 @@ export class RuntimeReceiptWriter<Input, Output> {
     pending.aborted = abortReason(pending.signal);
     if (pending.state === 'active') return;
 
-    const collection =
-      pending.state === 'queued' ? this.#queued : this.#blocked;
+    const collection = pending.state === 'queued' ? this.#queued : [];
     const index = collection.indexOf(pending);
     if (index >= 0) collection.splice(index, 1);
     if (pending.state === 'queued') {
-      this.#bufferedBytes -= pending.bytes;
-      this.#admitBlocked();
+      this.#adjustBufferedItems(-1, this.#laneFor(pending.input));
+      this.#adjustBufferedBytes(-pending.bytes);
+      this.#adjustBufferedLane(this.#laneFor(pending.input), {
+        items: 0,
+        bytes: -pending.bytes,
+      });
+      this.#notifyStatsChanged();
     }
     this.#settleRejected(pending, pending.aborted);
+    this.#resolveCapacityWaiter();
     this.#notifyDrained();
   }
 
-  #admitBlocked(): void {
-    while (this.#blocked.length > 0) {
-      const pending = this.#blocked[0]!;
-      if (pending.aborted !== null) {
-        this.#blocked.shift();
-        this.#settleRejected(pending, pending.aborted);
-        continue;
-      }
-      if (!this.#canBuffer(pending.bytes)) break;
-      this.#blocked.shift();
-      this.#accept(pending);
-    }
-  }
-
   #settleResolved(pending: PendingWrite<Input, Output>, output: Output): void {
     if (pending.state === 'settled') return;
     this.#detachAbort(pending);
@@ -549,41 +972,70 @@ export class RuntimeReceiptWriter<Input, Output> {
 
   #rejectWaiting(reason: unknown): void {
     this.#clearFlushTimer();
+    let changed = false;
     for (const pending of this.#queued.splice(0)) {
-      this.#bufferedBytes -= pending.bytes;
-      this.#settleRejected(pending, reason);
-    }
-    for (const pending of this.#blocked.splice(0)) {
+      this.#adjustBufferedItems(-1, this.#laneFor(pending.input));
+      this.#adjustBufferedBytes(-pending.bytes);
+      this.#adjustBufferedLane(this.#laneFor(pending.input), {
+        items: 0,
+        bytes: -pending.bytes,
+      });
       this.#settleRejected(pending, reason);
+      changed = true;
     }
+    if (changed) this.#notifyStatsChanged();
+    this.#resolveCapacityWaiter();
     this.#notifyDrained(reason);
   }
 
-  #queuedBytesAtHead(): number {
-    const first = this.#queued[0];
-    if (!first) return 0;
-    const key = this.#batchKey(first.input);
-    let bytes = 0;
-    let count = 0;
-    for (const pending of this.#queued) {
-      if (
-        count >= this.#maxBatchSize ||
-        !Object.is(this.#batchKey(pending.input), key)
-      ) {
-        break;
-      }
-      bytes += pending.bytes;
-      count += 1;
-    }
-    return bytes;
+  #createCapacityWaiter(): CapacityWaiter {
+    let resolve!: () => void;
+    let reject!: (error: unknown) => void;
+    const promise = new Promise<void>((resolvePromise, rejectPromise) => {
+      resolve = resolvePromise;
+      reject = rejectPromise;
+    });
+    const waiter = { promise, resolve, reject };
+    this.#capacityWaiter = waiter;
+    return waiter;
+  }
+
+  #resolveCapacityWaiter(): void {
+    const waiter = this.#capacityWaiter;
+    if (!waiter) return;
+    this.#capacityWaiter = null;
+    waiter.resolve();
+  }
+
+  #rejectCapacityWaiter(reason: unknown): void {
+    const waiter = this.#capacityWaiter;
+    if (!waiter) return;
+    this.#capacityWaiter = null;
+    waiter.reject(reason);
+  }
+
+  async #waitForCapacityOrAbort(
+    capacity: Promise<void>,
+    signal: AbortSignal,
+  ): Promise<void> {
+    await new Promise<void>((resolve, reject) => {
+      const finish = (error?: unknown): void => {
+        signal.removeEventListener('abort', onAbort);
+        if (error === undefined) resolve();
+        else reject(error);
+      };
+      const onAbort = () => finish(abortReason(signal));
+      capacity.then(
+        () => finish(),
+        (error) => finish(error),
+      );
+      signal.addEventListener('abort', onAbort, { once: true });
+      if (signal.aborted) onAbort();
+    });
   }
 
   #isDrained(): boolean {
-    return (
-      this.#activeBatch === null &&
-      this.#queued.length === 0 &&
-      this.#blocked.length === 0
-    );
+    return this.#inFlight.size === 0 && this.#queued.length === 0;
   }
 
   #notifyDrained(error?: unknown): void {
@@ -602,6 +1054,32 @@ export class RuntimeReceiptWriter<Input, Output> {
   }
 }
 
+/**
+ * Submit one idempotent receipt command without turning local admission
+ * pressure into either an unbounded writer queue or a persistence failure.
+ *
+ * The caller retains `input` while it waits on the writer's shared progress
+ * signal. This is deliberately shared by the receipt-store Adapter and
+ * Context's direct completion writer so all runtime receipt paths apply the
+ * same bounded backpressure rule.
+ */
+export async function writeRuntimeReceiptWithBackpressure<Input, Output>(
+  writer: RuntimeReceiptWriter<Input, Output>,
+  input: Input,
+  options: { signal?: AbortSignal } = {},
+): Promise<Output> {
+  while (true) {
+    try {
+      return await writer.write(input, options);
+    } catch (error) {
+      if (!(error instanceof RuntimeReceiptWriterCapacityError)) {
+        throw error;
+      }
+      await writer.waitForCapacity(input, options);
+    }
+  }
+}
+
 const textEncoder = new TextEncoder();
 
 function estimateJsonBytes(input: unknown): number {
@@ -616,6 +1094,14 @@ function normalizePositiveInteger(
   return Math.max(1, Math.floor(value ?? fallback));
 }
 
+function normalizeLane(value: string): string {
+  const lane = value.trim();
+  if (!lane) {
+    throw new Error('Runtime receipt writer batch lanes must be non-empty.');
+  }
+  return lane;
+}
+
 function jitteredRetryDelayMs(delayMs: number): number {
   const normalized = Math.max(0, Math.floor(delayMs));
   if (normalized === 0) return 0;