deepline 0.3.113 → 0.3.114

package/dist/bundling-sources/shared_libs/play-runtime/scheduler-backends/absurd-runtime-worker.ts

@@ -164,6 +164,8 @@ import {
   readPostgresSchedulerRunnerLiveness,
   readPostgresSchedulerRuntimeResourcesForRun,
   requestComputeBillingDispatchToken,
+  blockPostgresSchedulerCronSchedule,
+  PostgresSchedulerCronScheduleConfigurationError,
   releasePostgresSchedulerReceiptsForAttempt,
   runtimeTerminalReasonFromError,
   settlePostgresSchedulerRuntimeResources,
@@ -196,6 +198,8 @@ import { runtimeSandboxProviderCapabilities } from './absurd-worker-required-env
 import {
   acquirePgNotifyHub,
   isRuntimeSchedulerCapacityError,
+  isRuntimeSchedulerRetryableTransactionError,
+  isConnectionCategoryError,
   parseRuntimeSchedulerCapacityError,
   RuntimeSchedulerCapacityError,
   runtimeSchedulerCapacityRetryAfterMs,
@@ -211,6 +215,7 @@ import {
 import {
   ABSURD_PLAY_RUN_MAX_ATTEMPTS,
   ABSURD_PLAY_RUN_RETRY_STRATEGY,
+  ABSURD_CRON_FIRE_TASK,
   ABSURD_DAYTONA_SANDBOX_CLEANUP_TASK,
   ABSURD_PLAY_RUN_TASK,
   ABSURD_RUNS_QUEUE,
@@ -234,6 +239,7 @@ import {
   normalizeAbsurdSchedulerOptions,
   resolveAbsurdPoolOptions,
   type AbsurdPlayRunTaskParams,
+  type AbsurdCronFireTaskParams,
   type AbsurdDaytonaSandboxCleanupTaskParams,
   type AbsurdRuntimeResult,
   type AbsurdSchedulerOptions,
@@ -659,6 +665,26 @@ export type AbsurdRuntimeWorkerDeps = {
    * suspenders lane-mismatch guard without mutating process env. Defaults to
    * `currentAbsurdReleaseId()`. */
   currentReleaseId: () => string;
+  /** Raw release registry identity stamped onto new child Run envelopes. */
+  currentLaunchReleaseId: () => string;
+  /**
+   * Cron has a different preparation boundary than ordinary worker execution:
+   * the sleeping task asks the current Vercel deployment to build a fresh
+   * authority, then that deployment commits the Run, task, outbox fact, and
+   * successor cursor in one Runtime Postgres transaction. The task itself
+   * never reuses the seed-time launch envelope.
+   */
+  admitCronFire: (input: {
+    scheduleId: string;
+    generation: number;
+    fireGeneration: number;
+    dueAtMs: number;
+    schedulerSchema?: string | null;
+  }) => Promise<
+    | { status: 'admitted'; runId: string; successorDueAtMs: number }
+    | { status: 'superseded' }
+    | { status: 'blocked' }
+  >;
   /** Best-effort deletion of an orphaned runtime sandbox by id (push-execution
    * B4 GC on reclaim/terminal-failure). Injectable so tests assert the GC call
    * without touching the Daytona SDK. Defaults to `deleteDaytonaSandboxById`. */
@@ -757,6 +783,8 @@ function buildDefaultDeps(absurd: Absurd): AbsurdRuntimeWorkerDeps {
         expectedOrganizationId: routingDomain,
       }),
     currentReleaseId: () => currentAbsurdReleaseId(),
+    currentLaunchReleaseId: () => currentAbsurdLaunchReleaseId(),
+    admitCronFire: requestCronFireAdmissionViaApp,
   };
 }
 
@@ -930,6 +958,149 @@ export async function requestAttemptExecutorToken(input: {
   return body.executorToken;
 }
 
+type CronFireAdmissionResult =
+  | { status: 'admitted'; runId: string; successorDueAtMs: number }
+  | { status: 'superseded' }
+  | { status: 'blocked' };
+
+/** A Vercel-side admission failure that tells the durable timer whether to defer. */
+class CronFireAdmissionGatewayError extends Error {
+  constructor(
+    message: string,
+    readonly retryable: boolean,
+    readonly retryAfterMs: number | null = null,
+  ) {
+    super(message);
+    this.name = 'CronFireAdmissionGatewayError';
+  }
+}
+
+function cronFireAdmissionGatewayUrl(): string {
+  const raw = process.env.DEEPLINE_RUNTIME_ADMISSION_GATEWAY_URL?.trim();
+  if (!raw) {
+    throw new CronFireAdmissionGatewayError(
+      'DEEPLINE_RUNTIME_ADMISSION_GATEWAY_URL is required for cron-fire fresh admission.',
+      true,
+    );
+  }
+  try {
+    const url = new URL(raw);
+    if (url.protocol !== 'https:' && url.protocol !== 'http:') {
+      throw new Error('non-HTTP protocol');
+    }
+    return url.origin;
+  } catch {
+    throw new CronFireAdmissionGatewayError(
+      'DEEPLINE_RUNTIME_ADMISSION_GATEWAY_URL must be an absolute HTTP(S) URL.',
+      true,
+    );
+  }
+}
+
+function cronFireRetryAfterMs(headers: Headers): number | null {
+  const value = headers.get('retry-after')?.trim();
+  if (!value) return null;
+  const seconds = Number(value);
+  return Number.isFinite(seconds) && seconds >= 0
+    ? Math.round(seconds * 1_000)
+    : null;
+}
+
+/**
+ * Make the timer's only external call after wake. The target is a stable
+ * Vercel alias, not the seed-time runtimeApiBaseUrl, so it always mints fresh
+ * run authority under the currently serving application release.
+ */
+export async function requestCronFireAdmissionViaApp(input: {
+  scheduleId: string;
+  generation: number;
+  fireGeneration: number;
+  dueAtMs: number;
+  schedulerSchema?: string | null;
+}): Promise<CronFireAdmissionResult> {
+  const internalToken = process.env.DEEPLINE_INTERNAL_TOKEN?.trim();
+  if (!internalToken) {
+    throw new CronFireAdmissionGatewayError(
+      'DEEPLINE_INTERNAL_TOKEN is required for cron-fire fresh admission.',
+      true,
+    );
+  }
+  const admissionGatewayUrl = cronFireAdmissionGatewayUrl();
+  const protectionHeaders = await vercelProtectionBypassHeaders({
+    baseUrl: admissionGatewayUrl,
+    token: process.env.VERCEL_PROTECTION_BYPASS_TOKEN ?? null,
+  });
+  let response: Response;
+  try {
+    response = await fetch(
+      `${admissionGatewayUrl}/api/v2/internal/runtime/cron-fire`,
+      {
+        method: 'POST',
+        signal: AbortSignal.timeout(30_000),
+        headers: {
+          'content-type': 'application/json',
+          'x-deepline-internal-token': internalToken,
+          'x-deepline-runtime-trace-id': `cron-fire:${input.scheduleId}:${input.generation}:${input.fireGeneration}:${input.dueAtMs}`,
+          ...protectionHeaders,
+        },
+        body: JSON.stringify(input),
+      },
+    );
+  } catch (error) {
+    throw new CronFireAdmissionGatewayError(
+      `Cron-fire admission gateway transport failed: ${error instanceof Error ? error.message : String(error)}`,
+      true,
+    );
+  }
+  const raw = await response.text();
+  const body = (() => {
+    try {
+      return JSON.parse(raw) as {
+        status?: unknown;
+        runId?: unknown;
+        successorDueAtMs?: unknown;
+        error?: unknown;
+        retryable?: unknown;
+      };
+    } catch {
+      return null;
+    }
+  })();
+  if (
+    response.ok &&
+    body?.status === 'admitted' &&
+    typeof body.runId === 'string' &&
+    typeof body.successorDueAtMs === 'number'
+  ) {
+    return {
+      status: 'admitted',
+      runId: body.runId,
+      successorDueAtMs: body.successorDueAtMs,
+    };
+  }
+  if (
+    response.ok &&
+    (body?.status === 'superseded' || body?.status === 'blocked')
+  ) {
+    return { status: body.status };
+  }
+  const retryable =
+    typeof body?.retryable === 'boolean'
+      ? body.retryable
+      : response.status === 401 ||
+        response.status === 403 ||
+        response.status === 408 ||
+        response.status === 429 ||
+        response.status >= 500;
+  throw new CronFireAdmissionGatewayError(
+    typeof body?.error === 'string'
+      ? body.error
+      : `Cron-fire admission gateway returned HTTP ${response.status}.`,
+    retryable,
+    cronFireRetryAfterMs(response.headers),
+  );
+}
+
 function signalData(
   record: PostgresSchedulerSignalRecord | null,
 ): Record<string, unknown> | null {
@@ -1268,6 +1439,142 @@ export async function executeAbsurdRuntimeLaunch(
   }
 }
 
+/**
+ * Advance one Runtime-owned cron cursor. The durable sleep is intentionally in
+ * the task rather than in Vercel: it releases the worker claim until due and a
+ * database outage after wake defers this same task without acknowledging the
+ * occurrence or consuming customer-code attempts.
+ */
+export async function executeAbsurdCronFire(
+  params: AbsurdCronFireTaskParams,
+  ctx: TaskContext,
+  deps: Pick<AbsurdRuntimeWorkerDeps, 'runWithClient' | 'admitCronFire'>,
+): Promise<
+  | { status: 'admitted'; runId: string; successorDueAtMs: number }
+  | { status: 'superseded' }
+  | { status: 'blocked' }
+> {
+  // Reader-first ABI compatibility: a timer written by the immediately
+  // preceding reader did not carry the repair generation. Its only safe
+  // interpretation is the original generation one.
+  const fireGeneration = params.fireGeneration ?? 1;
+  if (
+    !params.scheduleId?.trim() ||
+    !Number.isSafeInteger(params.generation) ||
+    params.generation <= 0 ||
+    !Number.isSafeInteger(fireGeneration) ||
+    fireGeneration <= 0 ||
+    !Number.isSafeInteger(params.dueAtMs) ||
+    params.dueAtMs <= 0
+  ) {
+    throw new Error(
+      'cron-fire requires a schedule id, generation, and due time.',
+    );
+  }
+  try {
+    // `sleepUntil` persists a checkpoint and a wake through the scheduler
+    // store before it throws SuspendTask. A transient failure there is no less
+    // retryable than the later atomic fire CTE, so keep this boundary inside
+    // the same durable deferral policy.
+    await ctx.sleepUntil('due', new Date(params.dueAtMs));
+    const result = await deps.admitCronFire({
+      scheduleId: params.scheduleId,
+      generation: params.generation,
+      fireGeneration,
+      dueAtMs: params.dueAtMs,
+      schedulerSchema: params.schedulerSchema ?? null,
+    });
+    console.info('[play.cron_fire]', {
+      scheduleId: params.scheduleId,
+      generation: params.generation,
+      dueAtMs: params.dueAtMs,
+      status: result.status,
+      ...(result.status === 'admitted'
+        ? { runId: result.runId, successorDueAtMs: result.successorDueAtMs }
+        : {}),
+    });
+    return result;
+  } catch (error) {
+    if (
+      error instanceof SuspendTask ||
+      error instanceof CancelledTask ||
+      error instanceof FailedTask
+    ) {
+      throw error;
+    }
+    if (error instanceof PostgresSchedulerCronScheduleConfigurationError) {
+      const reason = error.message;
+      let blocked: boolean;
+      try {
+        blocked = await deps.runWithClient((client) =>
+          blockPostgresSchedulerCronSchedule(
+            client,
+            {
+              scheduleId: params.scheduleId,
+              generation: params.generation,
+              fireGeneration,
+              dueAtMs: params.dueAtMs,
+              reason,
+            },
+            { schema: params.schedulerSchema ?? undefined },
+          ),
+        );
+      } catch (blockError) {
+        if (isRetryableCronFireStoreError(blockError)) {
+          throw deferCronFireStoreError(blockError);
+        }
+        throw blockError;
+      }
+      console.error('[play.cron_fire.blocked]', {
+        scheduleId: params.scheduleId,
+        generation: params.generation,
+        dueAtMs: params.dueAtMs,
+        blocked,
+        reason,
+      });
+      return { status: 'blocked' };
+    }
+    // A failed transaction has created neither Run nor successor. Parking the
+    // same durable fire preserves the cron retry owner (Absurd) through a
+    // PgBouncer or control-plane outage; DeferTask does not spend an engine
+    // attempt or create a second task.
+    if (isRetryableCronFireStoreError(error)) {
+      throw deferCronFireStoreError(error);
+    }
+    throw error;
+  }
+}
+
+function isRetryableCronFireStoreError(error: unknown): boolean {
+  if (error instanceof CronFireAdmissionGatewayError) return error.retryable;
+  if (
+    isRuntimeSchedulerCapacityError(error) ||
+    isConnectionCategoryError(error) ||
+    isRuntimeSchedulerRetryableTransactionError(error)
+  ) {
+    return true;
+  }
+  const code =
+    error && typeof error === 'object'
+      ? (error as { code?: unknown }).code
+      : null;
+  if (code === '57014') return true; // query cancelled / statement timeout
+  return (
+    error instanceof Error &&
+    /no longer accepts new launches/i.test(error.message)
+  );
+}
+
+function deferCronFireStoreError(error: unknown): DeferTask {
+  const reason = error instanceof Error ? error.message : String(error);
+  const retryAfterMs =
+    error instanceof CronFireAdmissionGatewayError ? error.retryAfterMs : null;
+  return new DeferTask(
+    `cron-fire atomic admission deferred: ${reason}`,
+    retryAfterMs === null ? 30 : Math.max(1, Math.ceil(retryAfterMs / 1_000)),
+  );
+}
+
 /**
  * ADR 0016 rule 3: load the run's durable terminal truth and fold it into the
  * progress reporter BEFORE its terminal finalize flush.
@@ -4248,6 +4555,12 @@ export function createAbsurdRuntimeTasks(
       resolved,
     ),
   );
+  // Register on both the current lane and every adopted continuation lane.
+  // The task may sleep for days, but its handler schedules children on the
+  // current release through `resolved.currentReleaseId` after waking.
+  absurd.registerTask({ name: ABSURD_CRON_FIRE_TASK, queue }, (params, ctx) =>
+    executeAbsurdCronFire(params as AbsurdCronFireTaskParams, ctx, resolved),
+  );
   absurd.registerTask(
     { name: ABSURD_DAYTONA_SANDBOX_CLEANUP_TASK, queue },
     async (params) => {

package/dist/bundling-sources/shared_libs/play-runtime/scheduler-backends/absurd-shared.ts

@@ -10,6 +10,7 @@
  * absurd-specific wiring (queue, event names, checkpoint boundary shaping).
  */
 import { createHash } from 'node:crypto';
+import { AsyncLocalStorage } from 'node:async_hooks';
 import type {
   PlayCheckpoint,
   PlayExecutionEvent,
@@ -20,6 +21,11 @@ import type { PlayRunLedgerEvent } from '../run-ledger';
 import type { PlaySchedulerSubmitInput } from '../scheduler-backend';
 import type { WorkerRuntimeApiContext } from '../app-runtime-api';
 import { RUNTIME_CAPACITY_POLICY } from '../runtime-capacity-policy';
+import {
+  PLAY_ADMISSION_MAX_ACQUIRE_QUEUE_WAIT_MS,
+  PLAY_ADMISSION_MAX_ACTIVE_LIFECYCLES,
+  PLAY_ADMISSION_MAX_PARALLELISM,
+} from '../admission-transport-policy';
 import { assertKnownResolvedBoundary } from '../checkpoint-boundaries';
 import type { Absurd, Log, RetryStrategy } from '@deepline/absurd/sdk';
 import { isIsolatedRuntimeSchedulerSchema } from '../runtime-scheduler-topology';
@@ -503,6 +509,15 @@ export {
   ABSURD_PLAY_RUN_TASK,
   type AbsurdPlayRunTaskParams,
 } from './absurd-play-run-task';
+export {
+  ABSURD_CRON_FIRE_MAX_ATTEMPTS,
+  ABSURD_CRON_FIRE_RETRY_STRATEGY,
+  ABSURD_CRON_FIRE_TASK,
+  buildAbsurdCronFireTask,
+  buildCronFireRunIdentity,
+  cronFireIdempotencyKey,
+  type AbsurdCronFireTaskParams,
+} from './absurd-cron-fire-task';
 /** Worker-owned cleanup for a Daytona sandbox in this release lane. */
 export const ABSURD_DAYTONA_SANDBOX_CLEANUP_TASK = 'daytona-sandbox-cleanup';
 
@@ -548,6 +563,87 @@ export const ABSURD_RUNTIME_POOL_MAX_CLIENTS =
  */
 export const ABSURD_SERVERLESS_POOL_MAX_CLIENTS = 1;
 
+/**
+ * A Vercel isolate may survive long after its one webhook has returned. Keep
+ * its single scheduler client only long enough to reuse it for an immediate
+ * follow-up, then return that scarce PgBouncer client before the source's
+ * delayed Workpool recovery is due. The worker fleet deliberately keeps the
+ * ordinary 30-second idle lifetime.
+ */
+export const ABSURD_SERVERLESS_POOL_IDLE_TIMEOUT_MS = 1_000;
+
+// A normal Vercel request submits exactly one Run and must retain the one-client
+// ceiling. The private batch adapter is different: Workpool elects one global
+// up-to-1,024-source collection before entering this context, so one batch
+// request may use the bounded scheduler capacity without multiplying it per
+// source request.
+// Other one-client Workpool adapters can still overlap during rollout.
+type ServerlessAdmissionPoolContext = {
+  maxClients: number;
+  maxAcquireQueueDepth: number;
+  maxAcquireQueueWaitMs: number;
+};
+
+const serverlessAdmissionPoolContext =
+  new AsyncLocalStorage<ServerlessAdmissionPoolContext>();
+
+export async function withServerlessAdmissionPoolMaxClients<T>(input: {
+  maxClients: number;
+  maxAcquireQueueDepth?: number;
+  maxAcquireQueueWaitMs?: number;
+  fn: () => Promise<T>;
+}): Promise<T> {
+  if (
+    !Number.isInteger(input.maxClients) ||
+    input.maxClients < 1 ||
+    input.maxClients > PLAY_ADMISSION_MAX_PARALLELISM
+  ) {
+    throw new Error(
+      'Serverless admission pool capacity is outside the supported range.',
+    );
+  }
+  const maxAcquireQueueDepth =
+    input.maxAcquireQueueDepth ?? PLAY_ADMISSION_MAX_ACTIVE_LIFECYCLES;
+  const maxAcquireQueueWaitMs =
+    input.maxAcquireQueueWaitMs ?? PLAY_ADMISSION_MAX_ACQUIRE_QUEUE_WAIT_MS;
+  if (
+    !Number.isSafeInteger(maxAcquireQueueDepth) ||
+    maxAcquireQueueDepth < 1 ||
+    maxAcquireQueueDepth > PLAY_ADMISSION_MAX_ACTIVE_LIFECYCLES
+  ) {
+    throw new Error(
+      'Serverless admission acquire queue capacity is outside the supported range.',
+    );
+  }
+  if (
+    !Number.isSafeInteger(maxAcquireQueueWaitMs) ||
+    maxAcquireQueueWaitMs < 5_000 ||
+    maxAcquireQueueWaitMs > PLAY_ADMISSION_MAX_ACQUIRE_QUEUE_WAIT_MS
+  ) {
+    throw new Error(
+      'Serverless admission acquire queue wait is outside the supported range.',
+    );
+  }
+  return await serverlessAdmissionPoolContext.run(
+    {
+      maxClients: input.maxClients,
+      maxAcquireQueueDepth,
+      maxAcquireQueueWaitMs,
+    },
+    input.fn,
+  );
+}
+
+/**
+ * The private batch adapter owns this request-local scheduler pool. Reserve
+ * one client for executor-token and other critical control-plane traffic; the
+ * rest may submit the independently idempotent batch sources in parallel.
+ */
+export function serverlessAdmissionSubmitMaxActive(): number | null {
+  const context = serverlessAdmissionPoolContext.getStore();
+  return context === undefined ? null : Math.max(1, context.maxClients - 1);
+}
+
 /**
  * Resolve the runtime scheduler Postgres pool options for the absurd control
  * plane. Loud failure over silent fallback: the absurd worker and scheduler
@@ -563,12 +659,24 @@ export function resolveAbsurdPoolOptions(
         'scheduler Postgres URL). Refusing to fall back to local execution.',
     );
   }
+  const serverless = process.env.VERCEL?.trim();
+  const context = serverlessAdmissionPoolContext.getStore();
   return {
     url,
     applicationName: 'deepline-absurd-runtime',
-    maxClients: process.env.VERCEL?.trim()
-      ? ABSURD_SERVERLESS_POOL_MAX_CLIENTS
-      : ABSURD_RUNTIME_POOL_MAX_CLIENTS,
+    maxClients:
+      serverless || context !== undefined
+        ? (context?.maxClients ?? ABSURD_SERVERLESS_POOL_MAX_CLIENTS)
+        : ABSURD_RUNTIME_POOL_MAX_CLIENTS,
+    ...(serverless || context !== undefined
+      ? { idleTimeoutMs: ABSURD_SERVERLESS_POOL_IDLE_TIMEOUT_MS }
+      : {}),
+    ...(context
+      ? {
+          maxAcquireQueueDepth: context.maxAcquireQueueDepth,
+          maxAcquireQueueWaitMs: context.maxAcquireQueueWaitMs,
+        }
+      : {}),
   };
 }
 

package/dist/bundling-sources/shared_libs/play-runtime/scheduler-backends/absurd.ts

@@ -20,6 +20,7 @@
  */
 import { recordPerfTrace } from '../perf-trace';
 import { CTX_RUN_PLAY_INLINE_ONLY } from '../child-execution-strategy';
+import { PLAY_ADMISSION_MAX_ACTIVE_LIFECYCLES } from '../admission-transport-policy';
 import {
   defaultRuntimeSandboxReconciliation,
   runtimeSandboxDeleteSucceeded,
@@ -58,6 +59,7 @@ import {
   ensureAbsurdRuntimeReady,
   normalizeAbsurdSchedulerOptions,
   resolveAbsurdPoolOptions,
+  serverlessAdmissionSubmitMaxActive,
   type AbsurdDaytonaSandboxCleanupTaskParams,
   type AbsurdSchedulerOptions,
 } from './absurd-shared';
@@ -325,9 +327,23 @@ export function createAbsurdSchedulerBackend(
       // Returning from submit therefore means the durable work is runnable;
       // there is no outbox, dispatcher, or second admission boundary.
       let submissionQueue = queue;
+      const serverlessSubmitMaxActive = serverlessAdmissionSubmitMaxActive();
       const admissionParams = {
         schedulerUrl: poolOptions.url,
         schedulerSchema: normalizedSchedulerOptions.schema,
+        ...(serverlessSubmitMaxActive === null
+          ? {}
+          : {
+              maxActive: serverlessSubmitMaxActive,
+              // The private batch may prepare 256 sources while 31 atomic
+              // Runtime submissions are active. Its process-local wait room
+              // must cover that already-bounded difference; otherwise the
+              // generic 128-launch buffer rejects healthy burst members
+              // before PgBouncer has a chance to drain them.
+              maxQueued:
+                PLAY_ADMISSION_MAX_ACTIVE_LIFECYCLES -
+                serverlessSubmitMaxActive,
+            }),
       };
       let spawn = await withRuntimeSchedulerSubmitAdmission(
         admissionParams,

package/dist/bundling-sources/shared_libs/play-runtime/scheduler-backends/postgres-pool.ts

@@ -28,6 +28,10 @@ import {
   RuntimeSchedulerSubmissionAdmissionError,
   RuntimeSchedulerSaturatedError,
 } from './scheduler-capacity';
+import {
+  PLAY_ADMISSION_LARGE_BATCH_SIZE,
+  PLAY_ADMISSION_MAX_ACQUIRE_QUEUE_WAIT_MS,
+} from '../admission-transport-policy';
 import { RUNTIME_RELIABILITY_POLICY } from '../runtime-reliability-policy';
 export {
   isRuntimeSchedulerCapacityError,
@@ -163,6 +167,23 @@ export type RuntimeSchedulerPoolOptions = {
   url: string;
   applicationName?: string;
   maxClients?: number;
+  /**
+   * Serverless launchers must not pin a scarce PgBouncer client between
+   * requests. Long-lived workers retain the default; Vercel callers opt into
+   * a short idle lifetime through the shared Absurd pool resolver.
+   */
+  idleTimeoutMs?: number;
+  /**
+   * Optional request-local acquire queue capacity. The dense webhook batch
+   * owns a finite 256-source wave, so it may reserve enough scheduler waiters
+   * for that wave without widening ordinary worker/request callers.
+   */
+  maxAcquireQueueDepth?: number;
+  /**
+   * Optional request-local waiter lifetime. A bounded batch may spend longer
+   * than the ordinary single-launch acquire timeout draining its finite wave.
+   */
+  maxAcquireQueueWaitMs?: number;
 };
 
 export type RuntimeSchedulerQueryClient = {
@@ -328,6 +349,7 @@ export class RuntimeSchedulerPoolAdmission {
 type PoolEntry = {
   pool: Pool;
   maxClients: number;
+  maxAcquireQueueDepth: number;
   admission: RuntimeSchedulerPoolAdmission;
   breaker: BreakerState;
   stats: {
@@ -489,6 +511,14 @@ function getPoolEntry(options: RuntimeSchedulerPoolOptions): PoolEntry {
   assertRuntimeSchedulerHotPathUrl(options.url);
   const maxClients =
     options.maxClients ?? RUNTIME_SCHEDULER_POOL_DEFAULTS.maxClients;
+  const idleTimeoutMs =
+    options.idleTimeoutMs ?? RUNTIME_SCHEDULER_POOL_DEFAULTS.idleTimeoutMs;
+  const maxAcquireQueueDepth =
+    options.maxAcquireQueueDepth ??
+    RUNTIME_SCHEDULER_POOL_DEFAULTS.maxAcquireQueueDepth;
+  const maxAcquireQueueWaitMs =
+    options.maxAcquireQueueWaitMs ??
+    RUNTIME_SCHEDULER_POOL_DEFAULTS.acquireTimeoutMs;
   if (maxClients > RUNTIME_SCHEDULER_POOL_DEFAULTS.maxClientsHardCap) {
     throw new Error(
       `Runtime scheduler pool maxClients=${maxClients} exceeds the hard cap of ` +
@@ -496,16 +526,46 @@ function getPoolEntry(options: RuntimeSchedulerPoolOptions): PoolEntry {
         'instead of widening a single process pool.',
     );
   }
+  if (!Number.isSafeInteger(idleTimeoutMs) || idleTimeoutMs < 0) {
+    throw new Error(
+      `Runtime scheduler pool idleTimeoutMs=${idleTimeoutMs} must be a non-negative integer.`,
+    );
+  }
+  if (
+    !Number.isSafeInteger(maxAcquireQueueDepth) ||
+    maxAcquireQueueDepth < 1 ||
+    maxAcquireQueueDepth > PLAY_ADMISSION_LARGE_BATCH_SIZE
+  ) {
+    throw new Error(
+      `Runtime scheduler pool maxAcquireQueueDepth=${maxAcquireQueueDepth} ` +
+        `must be an integer between 1 and ${PLAY_ADMISSION_LARGE_BATCH_SIZE}.`,
+    );
+  }
+  if (
+    !Number.isSafeInteger(maxAcquireQueueWaitMs) ||
+    maxAcquireQueueWaitMs < RUNTIME_SCHEDULER_POOL_DEFAULTS.acquireTimeoutMs ||
+    maxAcquireQueueWaitMs > PLAY_ADMISSION_MAX_ACQUIRE_QUEUE_WAIT_MS
+  ) {
+    throw new Error(
+      `Runtime scheduler pool maxAcquireQueueWaitMs=${maxAcquireQueueWaitMs} ` +
+        `must be between ${RUNTIME_SCHEDULER_POOL_DEFAULTS.acquireTimeoutMs} and ` +
+        `${PLAY_ADMISSION_MAX_ACQUIRE_QUEUE_WAIT_MS}.`,
+    );
+  }
   const registry = getPoolRegistry();
   const connectionString = normalizePostgresConnectionStringForPg(options.url);
-  const key = `${connectionString}::${maxClients}`;
+  // The connection lifetime is part of a Pool's semantics. Do not let a
+  // serverless short-idle caller accidentally reuse a long-lived worker pool
+  // merely because both target the same runtime database.
+  const key = `${connectionString}::${maxClients}::${idleTimeoutMs}::${maxAcquireQueueDepth}::${maxAcquireQueueWaitMs}`;
   const existing = registry.get(key);
   if (existing) {
     // Next dev can retain the process-global pool across a module hot reload.
     // Upgrade that live entry in place when this admission layer first lands.
     existing.admission ??= new RuntimeSchedulerPoolAdmission(
       maxClients,
-      RUNTIME_SCHEDULER_POOL_DEFAULTS.maxAcquireQueueDepth,
+      maxAcquireQueueDepth,
+      maxAcquireQueueWaitMs,
     );
     return existing;
   }
@@ -515,7 +575,7 @@ function getPoolEntry(options: RuntimeSchedulerPoolOptions): PoolEntry {
     application_name:
       options.applicationName ?? 'deepline-runtime-scheduler-pool',
     max: maxClients,
-    idleTimeoutMillis: RUNTIME_SCHEDULER_POOL_DEFAULTS.idleTimeoutMs,
+    idleTimeoutMillis: idleTimeoutMs,
     connectionTimeoutMillis: RUNTIME_SCHEDULER_POOL_DEFAULTS.acquireTimeoutMs,
     query_timeout: RUNTIME_SCHEDULER_POOL_DEFAULTS.queryTimeoutMs,
     keepAlive: true,
@@ -523,9 +583,11 @@ function getPoolEntry(options: RuntimeSchedulerPoolOptions): PoolEntry {
   const entry: PoolEntry = {
     pool,
     maxClients,
+    maxAcquireQueueDepth,
     admission: new RuntimeSchedulerPoolAdmission(
       maxClients,
-      RUNTIME_SCHEDULER_POOL_DEFAULTS.maxAcquireQueueDepth,
+      maxAcquireQueueDepth,
+      maxAcquireQueueWaitMs,
     ),
     breaker: {
       consecutiveFailures: 0,
@@ -653,10 +715,7 @@ export async function withRuntimeSchedulerClient<T>(
     ) {
       throwIfSchedulerAborted(signal);
       breakerGate(entry);
-      if (
-        entry.pool.waitingCount >=
-        RUNTIME_SCHEDULER_POOL_DEFAULTS.maxAcquireQueueDepth
-      ) {
+      if (entry.pool.waitingCount >= entry.maxAcquireQueueDepth) {
         entry.stats.saturationRejections += 1;
         throw new RuntimeSchedulerSaturatedError(entry.pool.waitingCount);
       }