deepline 0.3.128 → 0.3.130

package/dist/bundling-sources/shared_libs/play-runtime/runtime-flow.ts

@@ -0,0 +1,448 @@
+/**
+ * Private runtime admission composition.
+ *
+ * A flow is deliberately smaller than a queue: it owns no payloads, retries,
+ * workers, or durable state. It acquires the capacity already owned by its
+ * stages, and releases every acquired stage in reverse order. That gives a
+ * map row, provider dispatch, or result handoff one idiomatic permit without
+ * inventing a second runtime scheduler.
+ */
+
+export type RuntimeFlowLease = {
+  release(): void;
+};
+
+export type RuntimeFlowStage<Input> = {
+  /** Stable diagnostic name. It never changes execution behavior. */
+  name: string;
+  acquire(input: Input): Promise<RuntimeFlowLease>;
+};
+
+export type RuntimeFlow<Input> = {
+  /**
+   * Admit and run one logical unit through every capacity boundary in order.
+   *
+   * A later boundary rejecting returns earlier permits immediately. The permits
+   * stay private to the callback and return in reverse order on every exit.
+   */
+  run<Output>(
+    input: Input,
+    work: () => Output | Promise<Output>,
+  ): Promise<Output>;
+};
+
+export function createRuntimeFlow<Input>(input: {
+  stages: readonly RuntimeFlowStage<Input>[];
+}): RuntimeFlow<Input> {
+  const stages = [...input.stages];
+  if (stages.length === 0) {
+    throw new Error('Runtime flow requires at least one admission stage.');
+  }
+  const names = new Set<string>();
+  for (const stage of stages) {
+    const name = stage.name.trim();
+    if (!name) throw new Error('Runtime flow stages require a name.');
+    if (names.has(name)) {
+      throw new Error(`Runtime flow stage "${name}" was registered twice.`);
+    }
+    names.add(name);
+  }
+
+  const admit = async (value: Input): Promise<RuntimeFlowLease[]> => {
+    const leases: RuntimeFlowLease[] = [];
+    try {
+      for (const stage of stages) {
+        leases.push(await stage.acquire(value));
+      }
+    } catch (error) {
+      releaseRuntimeFlowLeases(leases);
+      throw error;
+    }
+
+    return leases;
+  };
+
+  return {
+    async run<Output>(
+      value: Input,
+      work: () => Output | Promise<Output>,
+    ): Promise<Output> {
+      const leases = await admit(value);
+      try {
+        return await work();
+      } finally {
+        releaseRuntimeFlowLeases(leases);
+      }
+    },
+  };
+}
+
+/**
+ * A provider permit has a distinct pre-dispatch cancellation path. `park`,
+ * when present, returns a due permit that lost the local execution-slot race
+ * to its source for immediate local re-draw instead of refunding it.
+ */
+export type RuntimeDispatchProviderPermit = RuntimeFlowLease & {
+  cancel(): Promise<void>;
+  park?(): Promise<void>;
+};
+
+export type RuntimeDispatchFlowInput = {
+  providerResourceKey?: string | null;
+  signal?: AbortSignal;
+  /** Fixtures consume provider capacity but acquire app transport after delay. */
+  requiresTransportPermit: boolean;
+  /** Emits the request-side transport wait observed by the caller's metrics. */
+  onTransportAdmitted?: (waitMs: number) => void;
+};
+
+type RuntimeDispatchPermit<
+  ProviderPermit extends RuntimeDispatchProviderPermit,
+> = {
+  providerPermit: ProviderPermit;
+  executionSlot: RuntimeFlowLease;
+  integrationRequestLease: RuntimeFlowLease | null;
+};
+
+/**
+ * The only capability exposed while a provider-dispatch flow is admitted.
+ *
+ * `request` brackets the physical HTTP exchange, including consuming its
+ * body. It never exposes the provider, execution, or transport leases, so a
+ * caller cannot accidentally retain capacity after that exchange or return a
+ * provider permit before it knows whether the request began.
+ */
+export type RuntimeDispatchScope = {
+  /**
+   * Run the one physical request. `beforeRelease` executes after the response
+   * is known but while the provider lease is still valid, so a caller can
+   * durably record response-bound feedback that the lease authorizes.
+   */
+  request<Output>(
+    work: () => Output | Promise<Output>,
+    beforeRelease?: () => void | Promise<void>,
+  ): Promise<Output>;
+};
+
+export type RuntimeDispatchFlow<
+  ProviderPermit extends RuntimeDispatchProviderPermit,
+> = {
+  /**
+   * Admit and run exactly one physical provider request.
+   *
+   * Work that exits before `request` returns the provider permit through its
+   * cancellation path. Once `request` starts, the permit is released after
+   * the request body is consumed, even if that body cannot be verified. This
+   * preserves the ambiguity boundary while making resource lifetime private.
+   */
+  run<Output>(
+    input: RuntimeDispatchFlowInput,
+    work: (scope: RuntimeDispatchScope) => Output | Promise<Output>,
+  ): Promise<Output>;
+};
+
+/**
+ * Compose provider, sandbox-execution, and app-transport capacity at the
+ * dispatch edge. A provider permit is only useful when the local execution
+ * slot (and, for a live call, app transport) is immediately available. If a
+ * later stage is full, this flow returns every acquired permit and observes
+ * that stage's next availability. An execution slot won that way is kept
+ * only if a provider permit is already due locally (`tryAcquireProviderPermit`);
+ * otherwise the flow releases it and admits from the provider boundary
+ * again. No execution slot is ever held across a blocking provider acquire.
+ *
+ * It is not a queue and retains no tool input or result. The caller receives
+ * only a scoped request callback; Flow releases or cancels every lease based
+ * on whether that callback actually began.
+ */
+export function createRuntimeDispatchFlow<
+  ProviderPermit extends RuntimeDispatchProviderPermit,
+>(input: {
+  acquireProviderPermit: (input: {
+    signal?: AbortSignal;
+  }) => Promise<ProviderPermit>;
+  /** Synchronous local-only admission; must never block or go remote. */
+  tryAcquireProviderPermit?: () => ProviderPermit | null;
+  tryAcquireExecutionSlot: (input: {
+    providerResourceKey?: string | null;
+  }) => RuntimeFlowLease | null;
+  waitForExecutionSlot: (input: {
+    providerResourceKey?: string | null;
+    signal?: AbortSignal;
+  }) => Promise<RuntimeFlowLease>;
+  tryAcquireTransportSlot: () => RuntimeFlowLease | null;
+  waitForTransportSlot: (input: {
+    signal?: AbortSignal;
+  }) => Promise<RuntimeFlowLease>;
+}): RuntimeDispatchFlow<ProviderPermit> {
+  const admit = async (
+    admission: RuntimeDispatchFlowInput,
+  ): Promise<RuntimeDispatchPermit<ProviderPermit>> => {
+    while (true) {
+      let providerPermit: ProviderPermit | null = null;
+      let executionSlot: RuntimeFlowLease | null = null;
+      const releaseExecutionSlot = (): void => {
+        const slot = executionSlot;
+        executionSlot = null;
+        slot?.release();
+      };
+      const cancelProviderPermit = async (): Promise<void> => {
+        const permit = providerPermit;
+        providerPermit = null;
+        await permit?.cancel();
+      };
+      // The execution-slot wait is brief and the permit is already due, so
+      // keep it local for the retry instead of refunding it to the store.
+      const parkProviderPermit = async (): Promise<void> => {
+        const permit = providerPermit;
+        providerPermit = null;
+        if (!permit) return;
+        if (permit.park) await permit.park();
+        else await permit.cancel();
+      };
+      try {
+        providerPermit = await input.acquireProviderPermit({
+          signal: admission.signal,
+        });
+        executionSlot = input.tryAcquireExecutionSlot({
+          providerResourceKey: admission.providerResourceKey,
+        });
+        if (!executionSlot) {
+          await parkProviderPermit();
+          executionSlot = await input.waitForExecutionSlot({
+            providerResourceKey: admission.providerResourceKey,
+            signal: admission.signal,
+          });
+          // Releasing this slot would hand it to the next FIFO waiter, so
+          // keep it if the parked (or any due) permit can be re-drawn without
+          // blocking. Otherwise the blocking provider acquire must not run
+          // while a slot is held.
+          providerPermit = input.tryAcquireProviderPermit
+            ? input.tryAcquireProviderPermit()
+            : null;
+          if (!providerPermit) {
+            releaseExecutionSlot();
+            continue;
+          }
+        }
+
+        if (!admission.requiresTransportPermit) {
+          return {
+            providerPermit,
+            executionSlot,
+            integrationRequestLease: null,
+          };
+        }
+
+        const integrationRequestLease = input.tryAcquireTransportSlot();
+        if (integrationRequestLease) {
+          return {
+            providerPermit,
+            executionSlot,
+            integrationRequestLease,
+          };
+        }
+
+        releaseExecutionSlot();
+        await cancelProviderPermit();
+        const availability = await input.waitForTransportSlot({
+          signal: admission.signal,
+        });
+        availability.release();
+      } catch (error) {
+        await cleanupRuntimeDispatchAdmissionFailure({
+          cause: error,
+          executionSlot,
+          providerPermit,
+        });
+      }
+    }
+  };
+
+  return {
+    async run<Output>(
+      admission: RuntimeDispatchFlowInput,
+      work: (scope: RuntimeDispatchScope) => Output | Promise<Output>,
+    ): Promise<Output> {
+      const permit = await admit(admission);
+      let transportLease = permit.integrationRequestLease;
+      let requestStarted = false;
+      let requestUsed = false;
+      let scopeOpen = true;
+      let requestPromise: Promise<unknown> | null = null;
+      let permitReleased = false;
+      const releasePermit = async (): Promise<void> => {
+        if (permitReleased) return;
+        permitReleased = true;
+        await releaseRuntimeDispatchPermit({
+          transportLease,
+          executionSlot: permit.executionSlot,
+          providerPermit: permit.providerPermit,
+          requestStarted,
+        });
+      };
+      try {
+        const output = await work({
+          request: <RequestOutput>(
+            request: () => RequestOutput | Promise<RequestOutput>,
+            beforeRelease?: () => void | Promise<void>,
+          ): Promise<RequestOutput> => {
+            if (!scopeOpen) {
+              return Promise.reject(
+                new Error('Runtime dispatch flow scope has already closed.'),
+              );
+            }
+            if (requestUsed) {
+              return Promise.reject(
+                new Error(
+                  'Runtime dispatch flow permits exactly one physical request.',
+                ),
+              );
+            }
+            requestUsed = true;
+            requestPromise = (async () => {
+              try {
+                if (transportLease) {
+                  admission.onTransportAdmitted?.(0);
+                } else {
+                  const transportStartedAt = Date.now();
+                  transportLease = await input.waitForTransportSlot({
+                    signal: admission.signal,
+                  });
+                  admission.onTransportAdmitted?.(
+                    Date.now() - transportStartedAt,
+                  );
+                }
+                requestStarted = true;
+                return await request();
+              } finally {
+                // Feedback is response-bound, but it is not allowed to strand
+                // the capacity that made the response possible. Preserve the
+                // ordering (feedback while the provider lease is valid) and
+                // always release all leases even when feedback persistence
+                // fails.
+                try {
+                  if (requestStarted) await beforeRelease?.();
+                } finally {
+                  await releasePermit();
+                }
+              }
+            })();
+            return requestPromise as Promise<RequestOutput>;
+          },
+        });
+        // A caller normally returns `await request(...)`. Waiting here also
+        // makes an accidental fire-and-forget request drain before its scope
+        // can close and prevents an early release of its capacity.
+        await requestPromise;
+        return output;
+      } finally {
+        scopeOpen = false;
+        // `work` may throw after it deliberately started a fire-and-forget
+        // request. That request has already claimed this permit's ownership,
+        // even when it is still waiting to acquire transport. Drain it before
+        // the outer cleanup: releasing first would make the request's own
+        // finally a no-op and leak a transport lease it acquires afterwards.
+        // Its rejection cannot replace the original work failure, but its
+        // cleanup must finish before any permit is returned.
+        if (requestPromise) {
+          try {
+            await requestPromise;
+          } catch {
+            // The normal path above already surfaces request failures. This
+            // path only preserves an earlier failure from `work`.
+          }
+        }
+        await releasePermit();
+      }
+    },
+  };
+}
+
+async function cleanupRuntimeDispatchAdmissionFailure<
+  ProviderPermit extends RuntimeDispatchProviderPermit,
+>(input: {
+  cause: unknown;
+  executionSlot: RuntimeFlowLease | null;
+  providerPermit: ProviderPermit | null;
+}): Promise<never> {
+  const failures = [input.cause];
+  try {
+    input.executionSlot?.release();
+  } catch (error) {
+    failures.push(error);
+  }
+  try {
+    await input.providerPermit?.cancel();
+  } catch (error) {
+    failures.push(error);
+  }
+  if (failures.length === 1) {
+    throw input.cause;
+  }
+  throw new AggregateError(
+    failures,
+    'Runtime dispatch admission and cleanup both failed.',
+  );
+}
+
+function releaseRuntimeFlowLeases(leases: readonly RuntimeFlowLease[]): void {
+  let failure: unknown = null;
+  let hasFailure = false;
+  for (let index = leases.length - 1; index >= 0; index -= 1) {
+    try {
+      leases[index]?.release();
+    } catch (error) {
+      if (!hasFailure) {
+        failure = error;
+        hasFailure = true;
+      }
+    }
+  }
+  if (hasFailure) {
+    throw failure;
+  }
+}
+
+async function releaseRuntimeDispatchPermit<
+  ProviderPermit extends RuntimeDispatchProviderPermit,
+>(input: {
+  transportLease: RuntimeFlowLease | null;
+  executionSlot: RuntimeFlowLease;
+  providerPermit: ProviderPermit;
+  requestStarted: boolean;
+}): Promise<void> {
+  let failure: unknown = null;
+  let hasFailure = false;
+  const release = (work: () => void): void => {
+    try {
+      work();
+    } catch (error) {
+      if (!hasFailure) {
+        failure = error;
+        hasFailure = true;
+      }
+    }
+  };
+  const releaseAsync = async (work: () => Promise<void>): Promise<void> => {
+    try {
+      await work();
+    } catch (error) {
+      if (!hasFailure) {
+        failure = error;
+        hasFailure = true;
+      }
+    }
+  };
+
+  release(() => input.transportLease?.release());
+  release(() => input.executionSlot.release());
+  if (input.requestStarted) {
+    release(() => input.providerPermit.release());
+  } else {
+    await releaseAsync(async () => await input.providerPermit.cancel());
+  }
+  if (hasFailure) {
+    throw failure;
+  }
+}

package/dist/bundling-sources/shared_libs/play-runtime/runtime-map-row-feed.ts

@@ -0,0 +1,215 @@
+/**
+ * Hands source pages to one running map worker pool so the pool never drains
+ * between pages. Workers that outrun the appended rows wait here; the page
+ * pump appends the next page as soon as the previous one is fully dispatched,
+ * so at most one undispatched page and one prepared page are resident.
+ */
+export type RuntimeMapRowFeedSnapshot = {
+  appendedRows: number;
+  dispatchedRows: number;
+  pagesAppended: number;
+  closed: boolean;
+  failed: boolean;
+  workersWaiting: number;
+  pumpWaitingForDrain: boolean;
+};
+
+export const RUNTIME_MAP_ROW_FEED_MAX_WAIT_MS = 30 * 60 * 1000;
+
+export class RuntimeMapRowFeedStalledError extends Error {
+  readonly snapshot: RuntimeMapRowFeedSnapshot;
+
+  constructor(input: {
+    waiter: 'worker' | 'pump';
+    waitMs: number;
+    snapshot: RuntimeMapRowFeedSnapshot;
+  }) {
+    super(
+      `Runtime map row feed stalled: ${input.waiter} waited ${input.waitMs} ms ` +
+        `(${JSON.stringify(input.snapshot)}).`,
+    );
+    this.name = 'RuntimeMapRowFeedStalledError';
+    this.snapshot = input.snapshot;
+  }
+}
+
+type Waiter<T> = {
+  resolve: (value: T) => void;
+  reject: (error: unknown) => void;
+  timer: ReturnType<typeof setTimeout>;
+};
+
+export class RuntimeMapRowFeed {
+  #appended = 0;
+  #dispatched = 0;
+  #pages = 0;
+  #closed = false;
+  #failure: unknown = null;
+  #failed = false;
+  readonly #rowWaiters = new Map<Waiter<boolean>, number>();
+  #drainWaiter: Waiter<void> | null = null;
+  #onAppended: ((fromIndex: number, toIndex: number) => void) | null = null;
+  readonly #maxWaitMs: number;
+
+  constructor(input?: { maxWaitMs?: number }) {
+    this.#maxWaitMs =
+      input?.maxWaitMs !== undefined &&
+      Number.isFinite(input.maxWaitMs) &&
+      input.maxWaitMs > 0
+        ? input.maxWaitMs
+        : RUNTIME_MAP_ROW_FEED_MAX_WAIT_MS;
+  }
+
+  onAppended(listener: (fromIndex: number, toIndex: number) => void): void {
+    this.#onAppended = listener;
+  }
+
+  append(rowCount: number): void {
+    if (this.#failed) throw this.#failure;
+    if (this.#closed) {
+      throw new Error('Runtime map row feed is closed; cannot append rows.');
+    }
+    if (!Number.isInteger(rowCount) || rowCount < 0) {
+      throw new Error(`Runtime map row feed append count must be a non-negative integer, got ${String(rowCount)}.`);
+    }
+    const fromIndex = this.#appended;
+    this.#appended += rowCount;
+    this.#pages += 1;
+    this.#onAppended?.(fromIndex, this.#appended);
+    this.#wakeRowWaiters();
+  }
+
+  close(): void {
+    if (this.#closed || this.#failed) return;
+    this.#closed = true;
+    this.#wakeRowWaiters();
+    this.#settleDrainWaiter();
+  }
+
+  fail(error: unknown): void {
+    if (this.#failed) return;
+    this.#failed = true;
+    this.#failure = error;
+    for (const [waiter] of this.#rowWaiters) {
+      clearTimeout(waiter.timer);
+      waiter.reject(error);
+    }
+    this.#rowWaiters.clear();
+    if (this.#drainWaiter) {
+      clearTimeout(this.#drainWaiter.timer);
+      this.#drainWaiter.reject(error);
+      this.#drainWaiter = null;
+    }
+  }
+
+  get failed(): boolean {
+    return this.#failed;
+  }
+
+  get closed(): boolean {
+    return this.#closed;
+  }
+
+  markDispatched(count = 1): void {
+    this.#dispatched += count;
+    if (this.#dispatched > this.#appended) {
+      throw new Error(
+        `Runtime map row feed dispatched ${this.#dispatched} rows but only ${this.#appended} were appended.`,
+      );
+    }
+    this.#settleDrainWaiter();
+  }
+
+  /**
+   * Resolves true once row `index` has been appended, false once the feed is
+   * closed with no such row. Rejects with the feed's failure.
+   */
+  waitForRows(index: number): Promise<boolean> {
+    if (this.#failed) return Promise.reject(this.#failure);
+    if (index < this.#appended) return Promise.resolve(true);
+    if (this.#closed) return Promise.resolve(false);
+    return new Promise<boolean>((resolve, reject) => {
+      const startedAt = Date.now();
+      const waiter: Waiter<boolean> = {
+        resolve,
+        reject,
+        timer: setTimeout(() => {
+          this.#rowWaiters.delete(waiter);
+          reject(
+            new RuntimeMapRowFeedStalledError({
+              waiter: 'worker',
+              waitMs: Date.now() - startedAt,
+              snapshot: this.snapshot(),
+            }),
+          );
+        }, this.#maxWaitMs),
+      };
+      waiter.timer.unref?.();
+      this.#rowWaiters.set(waiter, index);
+    });
+  }
+
+  /** Resolves once every appended row has been dispatched to a worker. */
+  waitUntilDrained(): Promise<void> {
+    if (this.#failed) return Promise.reject(this.#failure);
+    if (this.#dispatched >= this.#appended) return Promise.resolve();
+    if (this.#drainWaiter) {
+      return Promise.reject(
+        new Error('Runtime map row feed already has a pump waiting to drain.'),
+      );
+    }
+    return new Promise<void>((resolve, reject) => {
+      const startedAt = Date.now();
+      this.#drainWaiter = {
+        resolve,
+        reject,
+        timer: setTimeout(() => {
+          this.#drainWaiter = null;
+          reject(
+            new RuntimeMapRowFeedStalledError({
+              waiter: 'pump',
+              waitMs: Date.now() - startedAt,
+              snapshot: this.snapshot(),
+            }),
+          );
+        }, this.#maxWaitMs),
+      };
+      this.#drainWaiter.timer.unref?.();
+    });
+  }
+
+  snapshot(): RuntimeMapRowFeedSnapshot {
+    return {
+      appendedRows: this.#appended,
+      dispatchedRows: this.#dispatched,
+      pagesAppended: this.#pages,
+      closed: this.#closed,
+      failed: this.#failed,
+      workersWaiting: this.#rowWaiters.size,
+      pumpWaitingForDrain: this.#drainWaiter !== null,
+    };
+  }
+
+  #wakeRowWaiters(): void {
+    for (const [waiter, index] of this.#rowWaiters) {
+      if (index < this.#appended) {
+        this.#rowWaiters.delete(waiter);
+        clearTimeout(waiter.timer);
+        waiter.resolve(true);
+      } else if (this.#closed) {
+        this.#rowWaiters.delete(waiter);
+        clearTimeout(waiter.timer);
+        waiter.resolve(false);
+      }
+    }
+  }
+
+  #settleDrainWaiter(): void {
+    if (!this.#drainWaiter) return;
+    if (this.#dispatched < this.#appended && !this.#closed) return;
+    const waiter = this.#drainWaiter;
+    this.#drainWaiter = null;
+    clearTimeout(waiter.timer);
+    waiter.resolve();
+  }
+}

package/dist/bundling-sources/shared_libs/play-runtime/runtime-operation-contract.ts

@@ -24,6 +24,7 @@ export const RUNTIME_OPERATION_CAPABILITIES = {
   mark_runtime_step_receipts_queued: 'receipt.write',
   complete_runtime_step_receipt: 'receipt.write',
   complete_runtime_step_receipts: 'receipt.write',
+  complete_runtime_step_receipts_by_reference: 'receipt.write',
   release_runtime_step_receipt: 'receipt.write',
   fail_runtime_step_receipt: 'receipt.write',
   fail_runtime_step_receipts: 'receipt.write',
@@ -54,6 +55,16 @@ export const RUNTIME_OPERATION_CONTRACT: DeployedOperationContract =
   deployed.operation({
     id: 'runtime-api-actions',
     actions: RUNTIME_OPERATION_CAPABILITIES,
+    olderReceiver: {
+      // The runner retains the complete result before attempting this
+      // compact completion. An older app receiver reports the action as
+      // unsupported, and the adapter retries the established full-payload
+      // completion without re-executing the provider call.
+      complete_runtime_step_receipts_by_reference: {
+        kind: 'equivalent-fallback',
+        action: 'complete_runtime_step_receipts',
+      },
+    },
   });
 
 export function runtimeOperationCapability(