@ultimat3/db 29.3.2 → 30.0.0

package/src/migration-errors.ts

@@ -1,6 +1,6 @@
 // Single responsibility: the refusals a MIGRATION earns — the lock it could not take, a ledger that
 // disagrees with this build, a plan that cannot be reversed, a plan that destroys rows without
-// saying so, a snapshot that was never written, and a view standing in a retype's way. Split out of
+// saying so, a snapshot never written, a view in a retype's way, a concurrent build. Split out of
 // `errors.ts` only because that file reached the 500-line ceiling, exactly as `invariant-errors.ts`
 // was: every code below is still declared, titled and registered there, and `DbError` is still the
 // one class. One direction only — nothing here is imported back.
@@ -8,6 +8,7 @@
 import { renderFixShellArg } from '@ultimat3/core';
 import { DESTRUCTIVE_CAUSE, DESTRUCTIVE_MARKER, type DestructiveStatement } from './destructive';
 import { DbError } from './errors';
+import { statementExcerpt } from './statement-excerpt';
 
 /**
  * The migration advisory lock was still held when the wait ran out. `pg_advisory_lock` blocks with
@@ -155,3 +156,49 @@ export const migrationDestructive = (
     fix: `add the line "${DESTRUCTIVE_MARKER}" to ${file}, or regenerate it: x db gen "<name>" --allow-destructive`,
     meta: { file, kind: first.kind, statements: more + 1 },
   });
+
+/**
+ * A concurrent index statement in a migration the runner would wrap in a transaction, refused
+ * BEFORE `BEGIN` — Postgres answers `25001` only after the transaction is open, in words that name
+ * neither the migration nor the marker that fixes it. `-- transaction: false` is the marker
+ * (`concurrent-index.ts`); the path is the one directory `x db gen` writes, `packages/db/migrations`.
+ * The id is FILENAME text, so it reaches the command through `renderFixShellArg`.
+ */
+export const migrationConcurrentInTransaction = (id: string, statement: string): DbError =>
+  new DbError({
+    code: 'X_MIGRATION_CONCURRENT_IN_TRANSACTION',
+    cause:
+      `migration "${id}" runs inside a transaction and holds a statement Postgres refuses there ` +
+      `(25001): ${statementExcerpt(statement)}`,
+    // The marker is spelled out rather than spliced: it is `NO_TRANSACTION_MARKER`, and
+    // `concurrent-index.ts` imports nothing from here, but a constant in the command position is
+    // one the shell-argument screen cannot tell from caller input.
+    fix: `sed -i '1i -- transaction: false' packages/db/migrations/${renderFixShellArg(id, '<id>')}.sql   # before it is applied — or move the statement into a migration of its own`,
+    meta: { id },
+  });
+
+/**
+ * A concurrent index build on a PARTITIONED parent, which Postgres refuses (`0A000`) — reached as
+ * a bare `X_DB_STATEMENT_FAILED` that named the refusal and not the sequence that replaces it.
+ * `sourceError` keeps the server's own error, SQLSTATE included. The sequence is pg_dump's: each
+ * partition built concurrently, the parent's index `on only` (instant, no rows), then attached.
+ */
+export const migrationConcurrentPartitioned = (
+  id: string,
+  statement: string,
+  sourceError: unknown,
+): DbError =>
+  new DbError({
+    code: 'X_MIGRATION_CONCURRENT_PARTITIONED',
+    cause:
+      `migration "${id}" builds an index concurrently on a partitioned table, which Postgres ` +
+      `refuses (0A000): ${statementExcerpt(statement)}`,
+    // Three pieces, each opening with the statement it is: the parent's index is attached to,
+    // never built over, so `on only` is instant and valid once every partition's is attached.
+    fix:
+      'CREATE INDEX CONCURRENTLY <index>_<partition> ON <partition> (<columns>);   # per partition, then ' +
+      'CREATE INDEX <index> ON ONLY <parent> (<columns>);   # then, per partition, ' +
+      'ALTER INDEX <index> ATTACH PARTITION <index>_<partition>;   # in a -- transaction: false migration',
+    meta: { id, sqlState: '0A000' },
+    sourceError,
+  });

package/src/migration-ledger.ts

@@ -3,15 +3,18 @@
 // Split from `migrate.ts`, which keeps the lock, the apply loop and the rollback; `migrate.ts`
 // re-exports every name here, so its public surface is unchanged.
 
+import { isFixShellSafe } from '@ultimat3/core';
 import type { DbClient } from './client';
 import type { SchemaDescription } from './introspect';
 import { migrationConflict } from './migration-errors';
-import { migrationNameArg } from './primary-key';
 import { raw, sql } from './sql';
 import { SQLSTATE, sqlState } from './sqlstate';
 
 export const LEDGER_TABLE = 'x_migrations';
 
+/** Where `x new` puts an app's migrations: this package reads rows, the CLI reads the directory. */
+const APP_MIGRATIONS_DIR = 'packages/db/migrations';
+
 export interface Migration {
   /** Sort key and primary key. `20260726120000_add_publish_at`. */
   readonly id: string;
@@ -31,6 +34,13 @@ export interface LedgerRow {
   readonly applied_at: string;
   readonly app_version: string;
   readonly duration_ms: number;
+  /**
+   * Whether this migration's `up` destroys data, recorded at apply (`destructiveBit`). `null` on a
+   * row applied before the ledger kept the bit: the framework cannot know, and says so
+   * (`migrate-rollback.ts` warns rather than refuses over it). Optional so a row a caller builds
+   * by hand still types; `readLedger` always answers it.
+   */
+  readonly destructive?: boolean | null | undefined;
 }
 
 /**
@@ -58,6 +68,11 @@ export async function ensureLedger(client: DbClient): Promise<void> {
       duration_ms integer not null
     )
   `);
+  // Added, never part of the create: a ledger every earlier release made has no such column, and
+  // its rows keep `null` — "applied before the bit was recorded", never a guessed `false`.
+  await client.execute(sql`
+    alter table ${raw(LEDGER_TABLE)} add column if not exists destructive boolean
+  `);
 }
 
 /**
@@ -76,10 +91,16 @@ export function isLedgerMissing(error: unknown): boolean {
   return sqlState(error) === SQLSTATE.undefinedTable;
 }
 
+/**
+ * The bit is read through the row's JSON, not by name: `x db status`, the drift step and the MCP
+ * dry run read a ledger `ensureLedger` has not touched, and naming a column an older release's
+ * ledger lacks would turn every one of those reads into `42703`. Absent reads `null`.
+ */
 export async function readLedger(client: DbClient): Promise<readonly LedgerRow[]> {
   return client.query<LedgerRow>(sql`
-    select id, name, checksum, applied_at, app_version, duration_ms
-    from ${raw(LEDGER_TABLE)}
+    select id, name, checksum, applied_at, app_version, duration_ms,
+           (to_jsonb(ledger) ->> 'destructive')::boolean as destructive
+    from ${raw(LEDGER_TABLE)} as ledger
     order by id
   `);
 }
@@ -122,11 +143,24 @@ export function auditLedger(
     if (checksum === row.checksum) continue;
     throw migrationConflict(
       `migration "${row.id}" was applied with checksum ${row.checksum} but now hashes ${checksum}`,
-      `x db gen ${migrationNameArg(`fix ${migration.name}`)}   # never edit an applied migration, add a new one`,
+      editedMigrationFix(row.id, row.checksum),
     );
   }
 }
 
+/**
+ * Restore first. `x db gen` was this line, and it exits 0 and writes the edited SQL into the schema
+ * dump, with `drift` green over it. `git checkout -- <file>` was the next, and a COMMITTED edit
+ * restores the same wrong blob, so the line lists the file's revisions and the ledger's checksum
+ * names the one applied. The id is a file name and the checksum a ledger value: either one the
+ * shell would read is left out (the directory, then the cause) rather than spliced.
+ */
+const editedMigrationFix = (id: string, checksum: string): string => {
+  const path = isFixShellSafe(id) ? `${APP_MIGRATIONS_DIR}/${id}.sql` : APP_MIGRATIONS_DIR;
+  const applied = isFixShellSafe(checksum) ? `checksum ${checksum}` : 'the checksum in the cause';
+  return `git log --format='%h %ad %s' --date=short -- ${path}   # restore the revision applied with ${applied}: git checkout <rev> -- ${path} and never edit an applied migration; then x db gen "<change>"`;
+};
+
 /**
  * The migration id is the DATABASE's own text — whoever can write a ledger row picks what lands in
  * a line an operator pastes — and it goes inside SHELL DOUBLE QUOTES, where `$(…)` and a backtick

package/src/migration-step.ts

@@ -0,0 +1,192 @@
+// Single responsibility: apply ONE migration script and its ledger write — inside a transaction,
+// or, for a migration marked `-- transaction: false`, statement by statement outside one. Split
+// from `migrate.ts`, which keeps the lock, the ledger audit and the loops over pending migrations;
+// `migrate()` and `rollback()` both come through here, so both directions take the same path.
+
+import { logger } from '@ultimat3/core';
+import type { DbClient } from './client';
+import {
+  concurrentIndexTarget,
+  firstConcurrentStatement,
+  isConcurrentIndexStatement,
+  isNonTransactional,
+  isPartitionedBuildRefusal,
+} from './concurrent-index';
+import { refuseDependentViews } from './dependent-view';
+import { type LockRetryPolicy, withLockRetry } from './migrate-lock-retry';
+import {
+  migrationConcurrentInTransaction,
+  migrationConcurrentPartitioned,
+} from './migration-errors';
+import { raw, sql } from './sql';
+import { statementsOf } from './statement-split';
+import { withTransaction } from './transaction';
+
+export interface MigrationStep {
+  readonly id: string;
+  /** The migration's `up` — where the marker lives, whichever direction runs. */
+  readonly up: string;
+  /** What runs: `up` forwards, `down` on a rollback. */
+  readonly script: string;
+  /** `SET LOCAL lock_timeout` — every transaction, and no concurrent statement. `0` sets none. */
+  readonly lockTimeoutMs: number;
+  /** What a `lock_timeout` firing is worth (`migrate-lock-retry.ts`). Absent is no second attempt. */
+  readonly lockRetry?: Omit<LockRetryPolicy, 'lockTimeoutMs'> | undefined;
+  /** The ledger write, on the client the statements ran on — after the last of them succeeded. */
+  readonly record: (client: DbClient) => Promise<void>;
+}
+
+/**
+ * A migration's `up` and `down` are **scripts**, and one send is one statement — because the two
+ * drivers disagree about anything else. PGlite's `query()` is the extended protocol always and
+ * answers `cannot insert multiple commands into a prepared statement`; `Bun.SQL.unsafe` degrades
+ * to the simple protocol when no value is bound and applies the same script, which is a fact about
+ * bun 1.3.14 and not a contract. An empty script sends nothing at all, which is how a no-op
+ * migration reaches its ledger row.
+ */
+async function applyScript(tx: DbClient, script: string): Promise<void> {
+  for (const statement of statementsOf(script)) await tx.execute(raw(statement));
+}
+
+/**
+ * Bound how long this migration will queue behind a lock it cannot take.
+ *
+ * `alter table … add column` needs `ACCESS EXCLUSIVE`. A long `SELECT` holding `ACCESS SHARE`
+ * makes it wait — and because Postgres' lock queue is FIFO, **every subsequent query on that table
+ * queues behind the ALTER**. The `migrate` profile runs `statement_timeout = 0` deliberately, so
+ * without this the migrator waits forever and the app is down on one table for as long as the
+ * reporting query runs. `lock_timeout` bounds the *wait* alone and never the work.
+ *
+ * `SET LOCAL`, inside the migration's own transaction: it reverts at COMMIT, so a value chosen for
+ * DDL never leaks onto the session the next migration runs on. The failure it produces is `55P03`,
+ * typed as `X_DB_LOCK_TIMEOUT` by `driverError`, whose fix is `x db diagnostics --json`.
+ */
+async function setLockTimeout(tx: DbClient, lockTimeoutMs: number): Promise<void> {
+  if (lockTimeoutMs <= 0) return;
+  // `SET LOCAL` takes no parameter placeholder, and the value is a validated integer of ours.
+  await tx.execute(raw(`SET LOCAL lock_timeout = ${Math.round(lockTimeoutMs)}`));
+}
+
+/**
+ * An interrupted `create index concurrently` leaves the index behind marked INVALID: never used by
+ * the planner, still maintained on every write, and — the part that bites — still holding the
+ * name, so `if not exists` would skip the rebuild and record the step as done. So before each
+ * named concurrent build: an INVALID index under that name is dropped (concurrently) first.
+ *
+ * `to_regclass` resolves the name exactly as the statement will — quoting and `search_path`
+ * included — and answers `null` for a missing one. The name is the statement's own text, which
+ * this runner is about to send anyway, so the drop adds no surface the build did not have.
+ */
+async function dropInvalidLeftover(session: DbClient, statement: string): Promise<void> {
+  const name = concurrentIndexTarget(statement);
+  if (name === null) return;
+  const row = await session.one<{ valid: boolean }>(
+    sql`select i.indisvalid as valid from pg_index i where i.indexrelid = to_regclass(${name})`,
+  );
+  if (row === null || row.valid) return;
+  logger.warn('ultimate migrate dropping an invalid index left by an interrupted build', {
+    index: name,
+    cause: `index ${name} is INVALID — a concurrent build of it failed or was interrupted`,
+    fix: 'x db migrate --json   # already running: the leftover is dropped and built again',
+  });
+  await session.execute(raw(`drop index concurrently if exists ${name}`));
+}
+
+/**
+ * Outside a transaction, one statement at a time. A concurrent index statement runs bare, with no
+ * `lock_timeout`: the concurrent forms take SHARE UPDATE EXCLUSIVE, which queues no read and no
+ * write, and the long waits they do make — for every transaction older than the build — are lock
+ * waits too, so the 3 s bound would turn a slow-but-harmless build into an INVALID index.
+ *
+ * Every other statement — the `alter table … drop constraint` a UNIQUE removal needs, a hand-written
+ * `drop table` — can queue the table, so it gets a transaction of its own under the same
+ * `SET LOCAL lock_timeout` a transactional migration runs with. Only what Postgres refuses inside a
+ * transaction (`vacuum`, `create database`, …: `AUTOCOMMIT_ONLY`) runs autocommitted.
+ *
+ * The step must be idempotent, since a failure leaves what already ran in place and no ledger
+ * row: `x db gen` writes only `if not exists` / `if exists` forms here.
+ */
+/**
+ * The statements Postgres refuses inside a transaction block (25001): they run autocommitted. Every
+ * other statement under the marker — an `alter table`, a `drop table`, any DDL that can queue the
+ * table behind a long reader — runs in a short transaction under the migration's `lock_timeout`.
+ */
+const AUTOCOMMIT_ONLY =
+  /^\s*(?:vacuum|create\s+database|drop\s+database|alter\s+system|create\s+tablespace|drop\s+tablespace|reindex\s+(?:\(.*\)\s*)?(?:system|database)\b|create\s+subscription|drop\s+subscription|alter\s+subscription)\b/i;
+/** `cluster` with no table re-clusters every table: refused in a transaction. One table's is not. */
+const BARE_CLUSTER = /^\s*cluster(?:\s+verbose)?\s*;?\s*$/i;
+
+/** A statement's text past its leading `--` lines (the step's own marker rides the first one). */
+const withoutLeadingComments = (statement: string): string =>
+  statement.replace(/^(?:\s*--[^\n]*(?:\n|$))+/, '');
+
+/** The one retry wrap, whichever unit the step's kind makes safe to send again. */
+const retrying = (step: MigrationStep, attempt: () => Promise<void>): Promise<void> =>
+  withLockRetry(
+    step.id,
+    { ...(step.lockRetry ?? { retries: 0 }), lockTimeoutMs: step.lockTimeoutMs },
+    attempt,
+  );
+
+async function applyOutsideTransaction(session: DbClient, step: MigrationStep): Promise<void> {
+  await refuseDependentViews(session, step.script);
+  for (const statement of statementsOf(step.script)) {
+    if (isConcurrentIndexStatement(statement)) {
+      await dropInvalidLeftover(session, statement);
+      await session.execute(raw(statement)).catch((error: unknown) => {
+        // `0A000` on a partitioned parent: the instruction is the sequence that replaces it.
+        if (isPartitionedBuildRefusal(statement, error)) {
+          throw migrationConcurrentPartitioned(step.id, statement, error);
+        }
+        throw error;
+      });
+      continue;
+    }
+    // Postgres refuses these inside a transaction (25001): autocommitted, as the marker promises.
+    const bare = withoutLeadingComments(statement);
+    if (AUTOCOMMIT_ONLY.test(bare) || BARE_CLUSTER.test(bare)) {
+      await session.execute(raw(statement));
+      continue;
+    }
+    // This statement and no earlier one: what already ran stays run. From the top would re-swap
+    // every validated key to `not valid` and scan it again, and repeat a hand-written first line.
+    await retrying(step, () =>
+      withTransaction(
+        async (tx) => {
+          await setLockTimeout(tx, step.lockTimeoutMs);
+          await tx.execute(raw(statement));
+        },
+        { client: session },
+      ),
+    );
+  }
+  await step.record(session);
+}
+
+/** Apply one migration script and record it, on the migrator's own pinned session. */
+export async function applyMigrationStep(session: DbClient, step: MigrationStep): Promise<void> {
+  if (isNonTransactional(step.up)) return applyOutsideTransaction(session, step);
+  // Before `BEGIN`, never after the failure: inside the transaction Postgres' 25001 names neither
+  // the migration nor the marker that fixes it.
+  const refused = firstConcurrentStatement(step.script);
+  if (refused !== undefined) {
+    throw migrationConcurrentInTransaction(step.id, refused);
+  }
+  // Whole: the failed attempt rolled back, so nothing it did is left to repeat.
+  await retrying(step, () =>
+    withTransaction(
+      async (tx) => {
+        await setLockTimeout(tx, step.lockTimeoutMs);
+        // Before the first statement, never after the failure: a view compiled against a column
+        // this script retypes is `0A000` from the server with the view named only in a DETAIL field
+        // nothing prints (`dependent-view.ts`).
+        await refuseDependentViews(tx, step.script);
+        await applyScript(tx, step.script);
+        await step.record(tx);
+      },
+      // The lock's own session: a migration applied on another connection is not covered by the
+      // lock at all, and on `ROLE=migrate` there is no other connection to apply it on.
+      { client: session },
+    ),
+  );
+}

package/src/partition-order.ts

@@ -0,0 +1,56 @@
+// Single responsibility: the two facts a partitioned table changes about the schema dump — the
+// order its tables load in (parent before partition, every one in the ROOT's file) and the index
+// definition its parent's index can be rebuilt from. Pure; `schema-dump.ts` places the statements.
+
+import type { CatalogTable } from './catalog';
+
+/** A table and the file it is written to: its own, or its partition root's. */
+export interface PlacedTable {
+  readonly table: CatalogTable;
+  readonly file: string;
+}
+
+/**
+ * Every table once, each partition after the table it is a partition of, and filed under its root
+ * — so `04_tables/events.sql` creates `events` and then each month, whatever the months are
+ * called. Name order would create `a_2026_11` before `events`. A partition whose parent is not in
+ * the list (another schema's) is filed under itself, after every family.
+ */
+export function inLoadOrder(tables: readonly CatalogTable[]): readonly PlacedTable[] {
+  const byName = new Map(tables.map((table) => [table.name, table]));
+  const children = new Map<string, CatalogTable[]>();
+  for (const table of tables) {
+    const parent = table.partitionOf?.table;
+    if (parent === undefined || !byName.has(parent)) continue;
+    const siblings = children.get(parent) ?? [];
+    siblings.push(table);
+    children.set(parent, siblings);
+  }
+  const placed: PlacedTable[] = [];
+  const seen = new Set<string>();
+  const family = (root: CatalogTable): void => {
+    // Breadth first: a sub-partition comes after every partition of the level above it.
+    const queue = [root];
+    for (let at = 0; at < queue.length; at += 1) {
+      const table = queue[at];
+      if (table === undefined || seen.has(table.name)) continue;
+      seen.add(table.name);
+      placed.push({ table, file: root.name });
+      queue.push(...(children.get(table.name) ?? []));
+    }
+  };
+  for (const table of tables) {
+    const parent = table.partitionOf?.table;
+    if (parent === undefined || !byName.has(parent)) family(table);
+  }
+  return placed;
+}
+
+/**
+ * `pg_get_indexdef` spells a partitioned table's index `ON ONLY` — the form that builds the
+ * parent's index alone, INVALID until every partition's is attached. The dump renders no
+ * partition's attached index, so it loads the parent's without `ONLY`, which builds them all.
+ */
+const ON_ONLY = /^(CREATE (?:UNIQUE )?INDEX (?:"(?:[^"]|"")*"|\S+) ON )ONLY /;
+
+export const indexDefinitionOf = (definition: string): string => definition.replace(ON_ONLY, '$1');

package/src/partitioned-tables.ts

@@ -0,0 +1,24 @@
+// Single responsibility: name the PARTITIONED parents in a schema (`relkind = 'p'`), so a table
+// description can say it is one. The partitions themselves are not app schema and never reach
+// here: `nonAppRelations()` excludes every `relispartition` row, a sub-partition's parent included.
+
+import type { DbClient } from './client';
+import { sql } from './sql';
+
+interface PartitionedRow {
+  readonly name: string;
+}
+
+/** The partitioned tables of `schema` that are not themselves a partition — the ones migrations declare. */
+export async function partitionedTables(
+  client: DbClient,
+  schema: string,
+): Promise<readonly string[]> {
+  const rows = await client.query<PartitionedRow>(sql`
+    select c.relname as name
+    from pg_class c
+    join pg_namespace n on n.oid = c.relnamespace
+    where n.nspname = ${schema} and c.relkind = 'p' and not c.relispartition
+  `);
+  return rows.map((row) => row.name);
+}

package/src/pool-gate.ts

@@ -0,0 +1,120 @@
+// Single responsibility: how many units of work may be out on the pool at once, and how long the
+// next one waits. `Bun.SQL` queues past `max` with no bound and publishes no occupancy, so this counts
+// in front of it: a statement and a pin each hold one slot, and a full pool refuses on one deadline.
+
+import type { Scheduler } from '@ultimat3/core';
+import { type DbError, poolAcquireTimeout } from './errors';
+import type { PoolDemand } from './pool-gauge';
+import { unrefSchedule } from './pool-timer';
+
+export interface PoolGate {
+  /**
+   * Take a slot. `undefined` when one was free, so the path that never waits pays no promise and
+   * sends in the caller's own turn. Otherwise resolves `true` when the slot arrives, `false` when
+   * this pool retired first, and rejects past `acquireTimeoutMs` (`X_DB_POOL_EXHAUSTED`). `0` waits
+   * forever.
+   */
+  enter(acquireTimeoutMs: number): Promise<boolean> | undefined;
+  /** Give a slot back. The oldest waiter inherits it, so a newcomer never overtakes the queue. */
+  leave(): void;
+  /** This pool is gone but the database may not be: everyone queued asks the next pool. */
+  handOverWaiting(): void;
+  /** Reject everyone still queued. Slots already held are untouched. */
+  refuseWaiting(reason: DbError): void;
+}
+
+/** What `takeSlot` needs of a pool: the gate that admits to it and the counter that reports it. */
+export interface GatedPool {
+  readonly gate: PoolGate;
+  readonly demand: PoolDemand;
+}
+
+/**
+ * A slot on the current pool, counted from the ask: a statement queued behind a full pool is exactly
+ * what `db_pool_waiting` reports. Answers the pool itself when a slot was free, so a caller checking
+ * `instanceof Promise` sends in its own turn. A retirement during the wait re-asks the pool that
+ * replaced it, with a fresh deadline: the work was never sent, so it can only be late, never doubled.
+ */
+export function takeSlot<P extends GatedPool>(
+  connect: () => P,
+  acquireTimeoutMs: number,
+): P | Promise<P> {
+  const asked = connect();
+  asked.demand.enter();
+  const wait = asked.gate.enter(acquireTimeoutMs);
+  if (wait === undefined) return asked;
+  return (async () => {
+    let admitted: boolean;
+    try {
+      admitted = await wait;
+    } catch (error) {
+      asked.demand.leave();
+      throw error;
+    }
+    if (admitted) return asked;
+    asked.demand.leave();
+    return takeSlot(connect, acquireTimeoutMs);
+  })();
+}
+
+/** The other half of `takeSlot`. */
+export function freeSlot(pool: GatedPool): void {
+  pool.gate.leave();
+  pool.demand.leave();
+}
+
+interface Waiter {
+  readonly settle: (admitted: boolean) => void;
+  readonly refuse: (reason: DbError) => void;
+  disarm: () => void;
+}
+
+export function poolGate(max: number, schedule: Scheduler = unrefSchedule): PoolGate {
+  let out = 0;
+  // A Set: FIFO by insertion, and a waiter past its deadline leaves from the middle in O(1).
+  const waiting = new Set<Waiter>();
+
+  return {
+    enter(acquireTimeoutMs) {
+      // `leave` hands a slot over rather than freeing it, so a free slot means nobody is queued.
+      if (out < max) {
+        out += 1;
+        return undefined;
+      }
+      return new Promise<boolean>((settle, refuse) => {
+        const waiter: Waiter = { settle, refuse, disarm: () => undefined };
+        waiting.add(waiter);
+        if (acquireTimeoutMs <= 0) return;
+        waiter.disarm = schedule(() => {
+          waiting.delete(waiter);
+          refuse(poolAcquireTimeout(acquireTimeoutMs, max));
+        }, acquireTimeoutMs);
+      });
+    },
+    leave() {
+      const next = waiting.values().next();
+      if (next.done === true) {
+        out = Math.max(0, out - 1);
+        return;
+      }
+      // Handed over: `out` does not move, the slot changes hands.
+      waiting.delete(next.value);
+      next.value.disarm();
+      next.value.settle(true);
+    },
+    handOverWaiting() {
+      for (const waiter of waiting) {
+        waiter.disarm();
+        waiter.settle(false);
+      }
+      waiting.clear();
+    },
+    refuseWaiting(reason) {
+      for (const waiter of waiting) {
+        waiter.disarm();
+        waiter.refuse(reason);
+      }
+      waiting.clear();
+    },
+  };
+}