deepline 0.1.259 → 0.1.260

package/dist/bundling-sources/sdk/src/config.ts

@@ -41,7 +41,7 @@ import {
   writeFileSync,
 } from 'node:fs';
 import { homedir } from 'node:os';
-import { dirname, join, resolve } from 'node:path';
+import { dirname, isAbsolute, join, resolve } from 'node:path';
 import type { DeeplineClientOptions, ResolvedConfig } from './types.js';
 import { ConfigError } from './errors.js';
 
@@ -429,6 +429,26 @@ export function resolveApiKeyForBaseUrl(
   );
 }
 
+export function resolveProjectApiKeyForBaseUrl(
+  baseUrl: string,
+  startDir: string = process.cwd(),
+): string {
+  const normalizedBaseUrl = normalizeBaseUrl(baseUrl);
+  return firstNonEmpty(
+    ...loadProjectEnvCandidates(startDir).map(({ env }) => {
+      const projectBaseUrl = normalizeBaseUrl(env[HOST_URL_ENV] ?? '');
+      return projectBaseUrl === normalizedBaseUrl ? env[API_KEY_ENV] : '';
+    }),
+  );
+}
+
+export function resolveGlobalApiKeyForBaseUrl(baseUrl: string): string {
+  return firstNonEmpty(
+    process.env[API_KEY_ENV],
+    loadCliEnv(normalizeBaseUrl(baseUrl) || baseUrl)[API_KEY_ENV],
+  );
+}
+
 function getResolvedProjectAuthSource(
   baseUrl: string,
   apiKey: string,
@@ -491,18 +511,100 @@ function mergeProjectEnvFile(filePath: string, values: EnvValues): void {
 }
 
 function ensureProjectEnvIsIgnored(dir: string): void {
+  ensureProjectPrivatePathsIgnored(dir, [
+    PROJECT_DEEPLINE_ENV_FILE,
+    '.deepline/',
+  ]);
+}
+
+export function ensureProjectPrivatePathsIgnored(
+  dir: string,
+  entries: readonly string[],
+): void {
+  const gitDir = findNearestGitCommonDir(dir);
+  if (gitDir) {
+    const excludePath = join(gitDir, 'info', 'exclude');
+    const existing = existsSync(excludePath)
+      ? readFileSync(excludePath, 'utf-8')
+      : '';
+    const existingEntries = new Set(
+      existing
+        .split(/\r?\n/)
+        .map((line) => line.trim())
+        .filter(Boolean),
+    );
+    const missing = entries.filter(
+      (entry) =>
+        !existingEntries.has(entry) && !existingEntries.has(`/${entry}`),
+    );
+    if (missing.length === 0) return;
+    mkdirSync(dirname(excludePath), { recursive: true });
+    const prefix = existing && !existing.endsWith('\n') ? '\n' : '';
+    writeFileSync(
+      excludePath,
+      `${existing}${prefix}${missing.join('\n')}\n`,
+      'utf-8',
+    );
+    return;
+  }
+
   const gitignorePath = join(dir, '.gitignore');
-  const entry = PROJECT_DEEPLINE_ENV_FILE;
   const existing = existsSync(gitignorePath)
     ? readFileSync(gitignorePath, 'utf-8')
     : '';
-  const alreadyIgnored = existing
-    .split(/\r?\n/)
-    .map((line) => line.trim())
-    .some((line) => line === entry || line === `/${entry}`);
-  if (alreadyIgnored) return;
+  const existingEntries = new Set(
+    existing
+      .split(/\r?\n/)
+      .map((line) => line.trim())
+      .filter(Boolean),
+  );
+  const missing = entries.filter(
+    (entry) => !existingEntries.has(entry) && !existingEntries.has(`/${entry}`),
+  );
+  if (missing.length === 0) return;
   const prefix = existing && !existing.endsWith('\n') ? '\n' : '';
-  writeFileSync(gitignorePath, `${existing}${prefix}${entry}\n`, 'utf-8');
+  writeFileSync(
+    gitignorePath,
+    `${existing}${prefix}${missing.join('\n')}\n`,
+    'utf-8',
+  );
+}
+
+function findNearestGitCommonDir(startDir: string): string | null {
+  let current = resolve(startDir);
+  while (true) {
+    const candidate = join(current, '.git');
+    if (existsSync(candidate)) {
+      try {
+        const stat = statSync(candidate);
+        if (stat.isDirectory()) return candidate;
+        if (stat.isFile()) {
+          const match = readFileSync(candidate, 'utf8').match(
+            /^gitdir:\s*(.+)$/m,
+          );
+          const rawGitDir = match?.[1]?.trim();
+          if (rawGitDir) {
+            const gitDir = isAbsolute(rawGitDir)
+              ? rawGitDir
+              : resolve(dirname(candidate), rawGitDir);
+            const commonDirPath = join(gitDir, 'commondir');
+            if (!existsSync(commonDirPath)) return gitDir;
+            const rawCommonDir = readFileSync(commonDirPath, 'utf8').trim();
+            return rawCommonDir
+              ? isAbsolute(rawCommonDir)
+                ? rawCommonDir
+                : resolve(gitDir, rawCommonDir)
+              : gitDir;
+          }
+        }
+      } catch {
+        return null;
+      }
+    }
+    const parent = dirname(current);
+    if (parent === current) return null;
+    current = parent;
+  }
 }
 
 export function saveProjectDeeplineEnvValues(

package/dist/bundling-sources/sdk/src/release.ts

@@ -123,7 +123,7 @@ export const SDK_RELEASE = {
   // Deepline-native radars. Older clients must update before discovering,
   // checking, or deploying an unlaunched monitor integration.
   // 0.1.253 makes play-page browser opening opt-in and retires --no-open.
-  version: '0.1.259',
+  version: '0.1.260',
   apiContract: '2026-07-native-monitor-launch-hard-cutover',
   supportPolicy: {
     minimumSupported: '0.1.53',

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

@@ -108,6 +108,7 @@ import {
 import { COMPLETED_RECEIPT_CACHE_INSERT_LEASE_ID } from './durable-receipt-execution';
 import { vercelProtectionBypassHeader } from './vercel-protection';
 import {
+  isRuntimePostgresAdmissionError,
   RuntimePostgresAdmission,
   type RuntimePostgresAdmissionSnapshot,
   type RuntimePostgresLane,
@@ -127,6 +128,7 @@ type RuntimeApiContext = {
   runtimeTestFaultHeader?: string | null;
   disablePostgresPoolCache?: boolean | null;
   postgresSessionUnwrapKey?: string | null;
+  abortSignal?: AbortSignal | null;
 };
 
 const RUNTIME_RUN_DATASET_CATALOG_TABLE = '_deepline_run_datasets';
@@ -319,6 +321,10 @@ const RUNTIME_API_RESOLVE_PLAY_RETRY_DELAYS_MS = [
 ] as const;
 const RUNTIME_API_DEFAULT_RETRY_AFTER_MS = 2_000;
 const RUNTIME_API_REQUEST_TIMEOUT_MS = 30_000;
+// A sheet admission can legitimately wait behind two large transactional
+// writes. Keep the caller alive long enough for the FIFO admission queue to
+// make progress instead of aborting a healthy queued start after 30 seconds.
+const RUNTIME_SHEET_ADMISSION_REQUEST_TIMEOUT_MS = 10 * 60_000;
 const RUNTIME_POSTGRES_PREWARM_MAX_ATTEMPTS = 4;
 const RUNTIME_POSTGRES_PREWARM_RETRY_DELAYS_MS = [250, 750, 1_500] as const;
 const RUNTIME_POSTGRES_CONNECT_MAX_ATTEMPTS = 4;
@@ -338,8 +344,12 @@ const RUNTIME_POSTGRES_CONNECT_TIMEOUT_MS = 10_000;
 // Neon Pool and node-postgres may queue internally, but runtime callers never
 // enter those unobservable queues without first holding a lane permit.
 const RUNTIME_POSTGRES_POOL_CONNECTIONS_PER_LANE = 2;
-const RUNTIME_POSTGRES_ADMISSION_MAX_QUEUED_PER_LANE = 2_000;
-const RUNTIME_POSTGRES_ADMISSION_TIMEOUT_MS = 10_000;
+const RUNTIME_POSTGRES_RECEIPT_ADMISSION_MAX_QUEUED = 2_000;
+// Sheet starts retain their parsed request body while waiting. Bound that
+// memory independently from lightweight receipt requests; overflow is a
+// retryable 503 and waits outside this long-lived gateway process.
+const RUNTIME_POSTGRES_SHEET_ADMISSION_MAX_QUEUED = 4;
+const RUNTIME_POSTGRES_RECEIPT_ADMISSION_TIMEOUT_MS = 10_000;
 const RECEIPT_STATUS_QUEUED = RECEIPT_STATUS_CODE.queued;
 const RECEIPT_STATUS_PENDING = RECEIPT_STATUS_CODE.pending;
 const RECEIPT_STATUS_RUNNING = RECEIPT_STATUS_CODE.running;
@@ -563,7 +573,7 @@ async function postRuntimeApi<TResponse>(
     const abortController = new AbortController();
     const timeout = setTimeout(
       () => abortController.abort(),
-      RUNTIME_API_REQUEST_TIMEOUT_MS,
+      runtimeApiRequestTimeoutMs(body.action),
     );
     try {
       response = await fetch(url, {
@@ -662,6 +672,14 @@ function runtimeApiRetryDelayMs(
     : Math.max(retryAfterMs, configuredDelay);
 }
 
+function runtimeApiRequestTimeoutMs(
+  action: RuntimeApiActionRequest['action'],
+): number {
+  return action === 'runtime_sheet_start'
+    ? RUNTIME_SHEET_ADMISSION_REQUEST_TIMEOUT_MS
+    : RUNTIME_API_REQUEST_TIMEOUT_MS;
+}
+
 async function sleepRuntimeApiRetry(
   action: RuntimeApiActionRequest['action'],
   attempt: number,
@@ -1525,8 +1543,29 @@ async function connectRuntimePostgresPool(
   pool: RuntimePool,
   admission: RuntimePostgresAdmission,
   lane: RuntimePostgresLane,
+  postgresUrl: string,
+  signal?: AbortSignal | null,
 ): Promise<RuntimePoolClient> {
-  const releaseAdmission = await admission.acquire(lane);
+  const admissionStartedAt = Date.now();
+  const releaseAdmission = await admission.acquire(lane, {
+    signal: signal ?? undefined,
+  });
+  const admissionWaitMs = Math.max(0, Date.now() - admissionStartedAt);
+  if (admissionWaitMs > 0) {
+    const telemetry = admission.snapshot()[lane];
+    console.info('[runtime-postgres-admission]', {
+      event: 'acquired_after_wait',
+      lane,
+      waitMs: admissionWaitMs,
+      active: telemetry.active,
+      queued: telemetry.queued,
+      poolKeyHash: createHash('sha256')
+        .update(postgresUrl)
+        .digest('hex')
+        .slice(0, 12),
+      phase: 'pool_connect',
+    });
+  }
   let timedOut = false;
   let timeout: ReturnType<typeof setTimeout> | null = null;
   const connectPromise = pool.connect();
@@ -1534,7 +1573,6 @@ async function connectRuntimePostgresPool(
     .then((client) => {
       if (timedOut) {
         client.release();
-        releaseAdmission();
       }
     })
     .catch(() => {});
@@ -1544,6 +1582,9 @@ async function connectRuntimePostgresPool(
       new Promise<never>((_, reject) => {
         timeout = setTimeout(() => {
           timedOut = true;
+          // Do not make a timed-out driver connect pin an admission permit.
+          // A late connect still releases its client in the handler above.
+          releaseAdmission();
           reject(
             new Error(
               `Runtime Postgres connection timed out after ${RUNTIME_POSTGRES_CONNECT_TIMEOUT_MS}ms.`,
@@ -1596,8 +1637,20 @@ function getRuntimePostgresAdmission(
   if (existing) return existing;
   const admission = new RuntimePostgresAdmission({
     maxActivePerLane: RUNTIME_POSTGRES_POOL_CONNECTIONS_PER_LANE,
-    maxQueuedPerLane: RUNTIME_POSTGRES_ADMISSION_MAX_QUEUED_PER_LANE,
-    acquireTimeoutMs: RUNTIME_POSTGRES_ADMISSION_TIMEOUT_MS,
+    maxQueuedPerLane: {
+      receipts: RUNTIME_POSTGRES_RECEIPT_ADMISSION_MAX_QUEUED,
+      sheets: RUNTIME_POSTGRES_SHEET_ADMISSION_MAX_QUEUED,
+    },
+    // Sheet capacity is backpressure, not a sheet-persistence failure. The
+    // surrounding runtime request has its own bounded deadline and the queue
+    // stays FIFO; no healthy request is discarded merely because two writes
+    // are active for ten seconds. Receipt admission retains its short timeout:
+    // a receipt can follow the ordinary retry/recovery path without holding a
+    // row's data-plane transaction open.
+    acquireTimeoutMs: {
+      receipts: RUNTIME_POSTGRES_RECEIPT_ADMISSION_TIMEOUT_MS,
+      sheets: null,
+    },
   });
   runtimePostgresAdmissions.set(postgresUrl, admission);
   return admission;
@@ -1654,7 +1707,11 @@ async function resetRuntimePostgresPool(postgresUrl: string): Promise<void> {
 async function withRuntimePostgres<T>(
   session: RuntimePostgresSession,
   fn: (client: RuntimePoolClient) => Promise<T>,
-  options: { cachePool?: boolean; maxConnectAttempts?: number } = {},
+  options: {
+    cachePool?: boolean;
+    maxConnectAttempts?: number;
+    signal?: AbortSignal | null;
+  } = {},
 ): Promise<T> {
   let client: RuntimePoolClient | null = null;
   let requestLocalPool: RuntimePool | null = null;
@@ -1672,7 +1729,13 @@ async function withRuntimePostgres<T>(
       if (!cachePool) {
         requestLocalPool = pool;
       }
-      client = await connectRuntimePostgresPool(pool, admission, lane);
+      client = await connectRuntimePostgresPool(
+        pool,
+        admission,
+        lane,
+        session.postgresUrl,
+        options.signal,
+      );
       if (session.executionRole) {
         await client.query(
           `SET ROLE ${quoteIdentifier(session.executionRole)}`,
@@ -1684,7 +1747,13 @@ async function withRuntimePostgres<T>(
         client.release();
         client = null;
       }
-      if (cachePool) {
+      // Queue overflow and caller cancellation happen before pool.connect().
+      // They describe admission state, not a broken shared pool. Ending that
+      // pool would invalidate the active clients and FIFO waiters that caused
+      // the backpressure in the first place.
+      const preserveSharedPool =
+        cachePool && isRuntimePostgresAdmissionError(error);
+      if (cachePool && !preserveSharedPool) {
         const poolKey = runtimePostgresPoolKey(session.postgresUrl, lane);
         const pool = postgresPools.get(poolKey);
         postgresPools.delete(poolKey);
@@ -1923,7 +1992,10 @@ async function withRuntimeSheetQueryClient<T>(
             throw error;
           }
         },
-        { cachePool: !context.disablePostgresPoolCache },
+        {
+          cachePool: !context.disablePostgresPoolCache,
+          signal: context.abortSignal,
+        },
       );
     },
   );
@@ -1968,13 +2040,16 @@ function runDatasetCatalogTable(session: RuntimePostgresSession): string {
 async function registerRuntimeDataset(
   session: RuntimePostgresSession,
   input: { playName: string; tableNamespace: string; runId: string },
+  signal?: AbortSignal | null,
 ): Promise<void> {
   const tableNamespace = normalizeTableNamespace(input.tableNamespace);
   const playName = normalizePlayNameForSheet(input.playName);
   const datasetId = createRuntimeDatasetId(playName, tableNamespace);
-  await withRuntimePostgres(session, async (client) => {
-    await client.query(
-      `INSERT INTO ${runDatasetCatalogTable(session)} (
+  await withRuntimePostgres(
+    session,
+    async (client) => {
+      await client.query(
+        `INSERT INTO ${runDatasetCatalogTable(session)} (
          run_id, dataset_id, play_name, table_namespace, public_path
        ) VALUES ($1, $2, $3, $4, $5)
        ON CONFLICT (run_id, dataset_id) DO UPDATE SET
@@ -1982,15 +2057,17 @@ async function registerRuntimeDataset(
          table_namespace = EXCLUDED.table_namespace,
          public_path = EXCLUDED.public_path,
          updated_at = now()`,
-      [
-        input.runId,
-        datasetId,
-        playName,
-        tableNamespace,
-        `datasets.${tableNamespace}`,
-      ],
-    );
-  });
+        [
+          input.runId,
+          datasetId,
+          playName,
+          tableNamespace,
+          `datasets.${tableNamespace}`,
+        ],
+      );
+    },
+    { signal },
+  );
 }
 
 function workReceiptTable(session: RuntimePostgresSession): string {
@@ -2312,7 +2389,10 @@ async function withRuntimeWorkReceiptClient<T>(
         : await withRuntimePostgres(
             session,
             (client) => runWithSelfHeal(client),
-            { cachePool: !context.disablePostgresPoolCache },
+            {
+              cachePool: !context.disablePostgresPoolCache,
+              signal: context.abortSignal,
+            },
           );
     } catch (error) {
       if (
@@ -5770,11 +5850,15 @@ export async function startRuntimeSheetDataset(
   // Register the exact run-scoped Dataset Handle before any row can become
   // durable. A crash after a later sheet write can therefore never leave
   // customer data discoverable only through static pipeline inference.
-  await registerRuntimeDataset(session, {
-    playName,
-    tableNamespace: input.tableNamespace,
-    runId: input.runId,
-  });
+  await registerRuntimeDataset(
+    session,
+    {
+      playName,
+      tableNamespace: input.tableNamespace,
+      runId: input.runId,
+    },
+    context.abortSignal,
+  );
   const normalizeStartedAt = Date.now();
   const uniqueRows = new Map<
     string,
@@ -5840,9 +5924,18 @@ export async function startRuntimeSheetDataset(
           .map((column) => `payload -> ${quoteLiteral(column)}`)
           .join(', ')}`
       : '';
+  const outputPhysicalColumns = outputPhysicalSheetColumnProjections(
+    input.sheetContract,
+  );
+  const outputPhysicalColumnNames = new Set(
+    outputPhysicalColumns.map((column) => column.sqlName),
+  );
+  const physicalRefreshColumns = physicalColumns.filter(
+    (column) => !outputPhysicalColumnNames.has(column),
+  );
   const physicalRefreshSetSql =
-    physicalColumns.length > 0
-      ? `, ${physicalColumns
+    physicalRefreshColumns.length > 0
+      ? `, ${physicalRefreshColumns
           .map(
             (column) =>
               `${quoteIdentifier(column)} = input_rows.payload -> ${quoteLiteral(column)}`,
@@ -5858,9 +5951,6 @@ export async function startRuntimeSheetDataset(
           )
           .join(', ')}`
       : '';
-  const outputPhysicalColumns = outputPhysicalSheetColumnProjections(
-    input.sheetContract,
-  );
   const normalizedPlayName = normalizePlayNameForSheet(playName);
   const normalizedTableNamespace = normalizeTableNamespace(
     input.tableNamespace,

package/dist/bundling-sources/shared_libs/play-runtime/runtime-postgres-admission.ts

@@ -7,6 +7,7 @@ export type RuntimePostgresLaneTelemetry = {
   waited: number;
   timedOut: number;
   rejected: number;
+  cancelled: number;
   totalWaitMs: number;
   maxWaitMs: number;
 };
@@ -21,9 +22,13 @@ export class RuntimePostgresAdmissionTimeoutError extends Error {
     readonly lane: RuntimePostgresLane,
     readonly queueDepth: number,
     readonly timeoutMs: number,
+    readonly active: number,
+    readonly queuedBeforeTimeout: number,
+    readonly waitedMs: number,
   ) {
     super(
-      `Runtime Postgres ${lane} admission timed out after ${timeoutMs}ms (${queueDepth} queued).`,
+      `Runtime Postgres ${lane} admission timed out after ${timeoutMs}ms ` +
+        `(${active} active, ${queuedBeforeTimeout} queued before timeout; ${queueDepth} queued after removal).`,
     );
     this.name = 'RuntimePostgresAdmissionTimeoutError';
   }
@@ -41,11 +46,44 @@ export class RuntimePostgresAdmissionQueueFullError extends Error {
   }
 }
 
+export class RuntimePostgresAdmissionCancelledError extends Error {
+  constructor(readonly lane: RuntimePostgresLane) {
+    super(`Runtime Postgres ${lane} admission was cancelled.`);
+    this.name = 'RuntimePostgresAdmissionCancelledError';
+  }
+}
+
+export function isRuntimePostgresAdmissionCapacityError(
+  error: unknown,
+): error is
+  | RuntimePostgresAdmissionTimeoutError
+  | RuntimePostgresAdmissionQueueFullError {
+  return (
+    error instanceof RuntimePostgresAdmissionTimeoutError ||
+    error instanceof RuntimePostgresAdmissionQueueFullError
+  );
+}
+
+export function isRuntimePostgresAdmissionError(
+  error: unknown,
+): error is
+  | RuntimePostgresAdmissionTimeoutError
+  | RuntimePostgresAdmissionQueueFullError
+  | RuntimePostgresAdmissionCancelledError {
+  return (
+    isRuntimePostgresAdmissionCapacityError(error) ||
+    error instanceof RuntimePostgresAdmissionCancelledError
+  );
+}
+
 type Waiter = {
   enqueuedAt: number;
-  timeout: ReturnType<typeof setTimeout>;
+  timeout: ReturnType<typeof setTimeout> | null;
   resolve: (release: () => void) => void;
   reject: (error: Error) => void;
+  signal: AbortSignal | null;
+  onAbort: (() => void) | null;
+  settled: boolean;
 };
 
 type LaneState = RuntimePostgresLaneTelemetry & { waiters: Waiter[] };
@@ -58,6 +96,7 @@ function createLaneState(): LaneState {
     waited: 0,
     timedOut: 0,
     rejected: 0,
+    cancelled: 0,
     totalWaitMs: 0,
     maxWaitMs: 0,
     waiters: [],
@@ -66,8 +105,8 @@ function createLaneState(): LaneState {
 
 export class RuntimePostgresAdmission {
   readonly #maxActivePerLane: number;
-  readonly #maxQueuedPerLane: number;
-  readonly #acquireTimeoutMs: number;
+  readonly #maxQueuedPerLane: Record<RuntimePostgresLane, number>;
+  readonly #acquireTimeoutMs: Record<RuntimePostgresLane, number | null>;
   readonly #lanes: Record<RuntimePostgresLane, LaneState> = {
     receipts: createLaneState(),
     sheets: createLaneState(),
@@ -75,22 +114,59 @@ export class RuntimePostgresAdmission {
 
   constructor(input: {
     maxActivePerLane: number;
-    maxQueuedPerLane: number;
-    acquireTimeoutMs: number;
+    maxQueuedPerLane: number | Record<RuntimePostgresLane, number>;
+    acquireTimeoutMs:
+      | number
+      | null
+      | Record<RuntimePostgresLane, number | null>;
   }) {
     this.#maxActivePerLane = Math.max(1, Math.floor(input.maxActivePerLane));
-    this.#maxQueuedPerLane = Math.max(0, Math.floor(input.maxQueuedPerLane));
-    this.#acquireTimeoutMs = Math.max(1, Math.floor(input.acquireTimeoutMs));
+    const normalizeQueueLimit = (value: number): number =>
+      Math.max(0, Math.floor(value));
+    this.#maxQueuedPerLane =
+      typeof input.maxQueuedPerLane === 'object'
+        ? {
+            receipts: normalizeQueueLimit(input.maxQueuedPerLane.receipts),
+            sheets: normalizeQueueLimit(input.maxQueuedPerLane.sheets),
+          }
+        : {
+            receipts: normalizeQueueLimit(input.maxQueuedPerLane),
+            sheets: normalizeQueueLimit(input.maxQueuedPerLane),
+          };
+    const normalizeTimeout = (value: number | null): number | null =>
+      value === null ? null : Math.max(1, Math.floor(value));
+    const acquireTimeoutMs = input.acquireTimeoutMs;
+    this.#acquireTimeoutMs =
+      acquireTimeoutMs !== null && typeof acquireTimeoutMs === 'object'
+        ? {
+            receipts: normalizeTimeout(acquireTimeoutMs.receipts),
+            sheets: normalizeTimeout(acquireTimeoutMs.sheets),
+          }
+        : {
+            receipts: normalizeTimeout(
+              typeof acquireTimeoutMs === 'number' ? acquireTimeoutMs : null,
+            ),
+            sheets: normalizeTimeout(
+              typeof acquireTimeoutMs === 'number' ? acquireTimeoutMs : null,
+            ),
+          };
   }
 
-  async acquire(lane: RuntimePostgresLane): Promise<() => void> {
+  async acquire(
+    lane: RuntimePostgresLane,
+    options: { signal?: AbortSignal } = {},
+  ): Promise<() => void> {
     const state = this.#lanes[lane];
+    if (options.signal?.aborted) {
+      state.cancelled += 1;
+      throw new RuntimePostgresAdmissionCancelledError(lane);
+    }
     if (state.active < this.#maxActivePerLane && state.waiters.length === 0) {
       state.active += 1;
       state.acquired += 1;
       return this.#releaseFor(lane);
     }
-    if (state.waiters.length >= this.#maxQueuedPerLane) {
+    if (state.waiters.length >= this.#maxQueuedPerLane[lane]) {
       state.rejected += 1;
       throw new RuntimePostgresAdmissionQueueFullError(
         lane,
@@ -98,28 +174,56 @@ export class RuntimePostgresAdmission {
       );
     }
     state.waited += 1;
+    const acquireTimeoutMs = this.#acquireTimeoutMs[lane];
     return await new Promise<() => void>((resolve, reject) => {
       const waiter: Waiter = {
         enqueuedAt: Date.now(),
-        timeout: setTimeout(() => {
-          const index = state.waiters.indexOf(waiter);
-          if (index < 0) return;
-          state.waiters.splice(index, 1);
-          state.queued = state.waiters.length;
+        timeout: null,
+        resolve,
+        reject,
+        signal: options.signal ?? null,
+        onAbort: null,
+        settled: false,
+      };
+      const removeWaiter = (): boolean => {
+        if (waiter.settled) return false;
+        const index = state.waiters.indexOf(waiter);
+        if (index < 0) return false;
+        waiter.settled = true;
+        state.waiters.splice(index, 1);
+        state.queued = state.waiters.length;
+        if (waiter.timeout) clearTimeout(waiter.timeout);
+        if (waiter.signal && waiter.onAbort) {
+          waiter.signal.removeEventListener('abort', waiter.onAbort);
+        }
+        return true;
+      };
+      waiter.onAbort = () => {
+        if (!removeWaiter()) return;
+        state.cancelled += 1;
+        reject(new RuntimePostgresAdmissionCancelledError(lane));
+      };
+      waiter.signal?.addEventListener('abort', waiter.onAbort, { once: true });
+      if (acquireTimeoutMs !== null) {
+        waiter.timeout = setTimeout(() => {
+          const queuedBeforeTimeout = state.waiters.length;
+          if (!removeWaiter()) return;
           state.timedOut += 1;
           reject(
             new RuntimePostgresAdmissionTimeoutError(
               lane,
               state.waiters.length,
-              this.#acquireTimeoutMs,
+              acquireTimeoutMs,
+              state.active,
+              queuedBeforeTimeout,
+              Math.max(0, Date.now() - waiter.enqueuedAt),
             ),
           );
-        }, this.#acquireTimeoutMs),
-        resolve,
-        reject,
-      };
+        }, acquireTimeoutMs);
+      }
       state.waiters.push(waiter);
       state.queued = state.waiters.length;
+      if (waiter.signal?.aborted) waiter.onAbort();
     });
   }
 
@@ -131,6 +235,7 @@ export class RuntimePostgresAdmission {
       waited: state.waited,
       timedOut: state.timedOut,
       rejected: state.rejected,
+      cancelled: state.cancelled,
       totalWaitMs: state.totalWaitMs,
       maxWaitMs: state.maxWaitMs,
     });
@@ -150,7 +255,11 @@ export class RuntimePostgresAdmission {
       const waiter = state.waiters.shift();
       state.queued = state.waiters.length;
       if (!waiter) return;
-      clearTimeout(waiter.timeout);
+      waiter.settled = true;
+      if (waiter.timeout) clearTimeout(waiter.timeout);
+      if (waiter.signal && waiter.onAbort) {
+        waiter.signal.removeEventListener('abort', waiter.onAbort);
+      }
       const waitMs = Math.max(0, Date.now() - waiter.enqueuedAt);
       state.totalWaitMs += waitMs;
       state.maxWaitMs = Math.max(state.maxWaitMs, waitMs);