@caelo-cms/shared 0.11.5 → 0.11.7

package/src/phase-timer.test.ts

@@ -45,4 +45,41 @@ describe("PhaseTimer", () => {
     expect(t.phases()).toHaveLength(1);
     for (const p of t.phases()) expect(phaseTimingSchema.parse(p)).toEqual(p);
   });
+
+  it("lapParts closes a step as the phases measured inside it plus the rest (#1271)", async () => {
+    const t = new PhaseTimer(clock(0, 1, 4, 5, 9, 20));
+    const parts = new Map<string, { ms: number }>();
+    await t.measure(parts, "compose", () => undefined);
+    await t.measure(parts, "compose", async () => undefined);
+    t.lapParts(parts, "batches");
+    expect(t.phases()).toEqual([
+      { phase: "compose", ms: 7 },
+      { phase: "batches", ms: 13 },
+    ]);
+  });
+
+  it("a memory timer records each step's peak RSS and stops sampling when closed (#1271)", async () => {
+    const t = PhaseTimer.withMemory();
+    try {
+      const hold: Uint8Array[] = [];
+      const parts = new Map<string, { ms: number; peakRssMb?: number }>();
+      await t.measure(parts, "alloc", async () => {
+        for (let i = 0; i < 16; i += 1) hold.push(new Uint8Array(4 * 1024 * 1024).fill(i + 1));
+        await Bun.sleep(60);
+      });
+      expect(parts.get("alloc")?.peakRssMb ?? 0).toBeGreaterThan(0);
+      t.lap("x");
+      expect(t.phases()[0]?.peakRssMb ?? 0).toBeGreaterThan(0);
+      expect(hold.length).toBe(16);
+      for (const p of t.phases()) expect(phaseTimingSchema.parse(p)).toEqual(p);
+    } finally {
+      t.close();
+    }
+  });
+
+  it("include keeps a step's peak RSS", () => {
+    const t = new PhaseTimer(clock(0, 1));
+    t.include("generator", [{ phase: "compose", ms: 3, peakRssMb: 120 }]);
+    expect(t.phases()).toEqual([{ phase: "generator.compose", ms: 3, peakRssMb: 120 }]);
+  });
 });

package/src/phase-timer.ts

@@ -9,6 +9,15 @@
  * Laps instead of wrapped callbacks: `lap("x")` closes the step that ran
  * since the previous lap, so a long function gets one line per boundary
  * and keeps its control flow (early throws, shared locals) as it is.
+ *
+ * #1271 — with `{ memory: true }` every step also carries
+ *   - the peak resident memory of the process while it ran (`peakRssMb`):
+ *     sampled every {@link RSS_SAMPLE_MS} by one shared timer that runs only
+ *     while a memory timer is open ({@link PhaseTimer.close}), plus a reading
+ *     at every lap;
+ *   - the CPU time the process spent in it (`cpuMs`, user + system, every
+ *     thread of the process — zlib and the other runtime workers included).
+ *     `cpuMs / ms` is the number of cores the step kept busy.
  */
 
 import { z } from "zod";
@@ -17,29 +26,176 @@ import { z } from "zod";
 export const phaseTimingSchema = z.object({
   phase: z.string().min(1),
   ms: z.number().int().nonnegative(),
+  /** #1271 — the process's peak resident memory during the step, in MiB. */
+  peakRssMb: z.number().int().nonnegative().optional(),
+  /** #1271 — CPU time (user + system, all threads) the process spent in the step, in ms. */
+  cpuMs: z.number().int().nonnegative().optional(),
 });
 export type PhaseTiming = z.infer<typeof phaseTimingSchema>;
 
+/** How often the open memory timers sample the resident set. */
+export const RSS_SAMPLE_MS = 25;
+
+const MIB = 1024 * 1024;
+
+/** Process CPU time so far (user + system), in ms; 0 where there is no process. */
+function cpuNow(): number {
+  if (typeof process === "undefined" || typeof process.cpuUsage !== "function") return 0;
+  const u = process.cpuUsage();
+  return (u.user + u.system) / 1000;
+}
+
+function rssNow(): number {
+  return typeof process !== "undefined" && typeof process.memoryUsage === "function"
+    ? process.memoryUsage().rss
+    : 0;
+}
+
+/**
+ * The one sampler of this process: its timer runs while at least one memory
+ * timer is open, and every open timer sees each sample.
+ */
+const sampler = (() => {
+  const listeners = new Set<(rss: number) => void>();
+  let timer: ReturnType<typeof setInterval> | null = null;
+  return {
+    add(fn: (rss: number) => void): void {
+      listeners.add(fn);
+      if (timer === null) {
+        timer = setInterval(() => {
+          const rss = rssNow();
+          for (const l of listeners) l(rss);
+        }, RSS_SAMPLE_MS);
+        // Never what keeps the process alive.
+        (timer as { unref?: () => void }).unref?.();
+      }
+    },
+    remove(fn: (rss: number) => void): void {
+      listeners.delete(fn);
+      if (listeners.size === 0 && timer !== null) {
+        clearInterval(timer);
+        timer = null;
+      }
+    },
+  };
+})();
+
+/** What {@link PhaseTimer.measure} adds up for one repeated step. */
+export interface PartTiming {
+  ms: number;
+  peakRssMb?: number;
+  cpuMs?: number;
+}
+
 export class PhaseTimer {
   readonly #now: () => number;
   readonly #phases: PhaseTiming[] = [];
   readonly #start: number;
+  readonly #listener: ((rss: number) => void) | null;
   #last: number;
+  #peak = 0;
+  #lastCpu = 0;
 
-  /** @param now clock in milliseconds; injectable for tests. */
-  constructor(now: () => number = () => performance.now()) {
+  /**
+   * @param now clock in milliseconds; injectable for tests.
+   * @param opts.memory record each step's peak RSS (see the file header);
+   *   the timer must then be {@link close}d.
+   */
+  constructor(now: () => number = () => performance.now(), opts: { memory?: boolean } = {}) {
     this.#now = now;
     this.#start = now();
     this.#last = this.#start;
+    if (opts.memory) {
+      this.#peak = rssNow();
+      this.#lastCpu = cpuNow();
+      this.#listener = (rss) => {
+        if (rss > this.#peak) this.#peak = rss;
+      };
+      sampler.add(this.#listener);
+    } else {
+      this.#listener = null;
+    }
+  }
+
+  /** A timer that records peak RSS per step (`new PhaseTimer(undefined, { memory: true })`). */
+  static withMemory(): PhaseTimer {
+    return new PhaseTimer(undefined, { memory: true });
   }
 
   /** Close the step that ran since the previous lap (or construction) as `phase`. */
   lap(phase: string): void {
     const t = this.#now();
-    this.#phases.push({ phase, ms: Math.round(t - this.#last) });
+    this.#phases.push({
+      phase,
+      ms: Math.round(t - this.#last),
+      ...this.#takePeak(),
+      ...this.#takeCpu(0),
+    });
     this.#last = t;
   }
 
+  /**
+   * Close the step since the previous lap as several phases measured
+   * inside it (`parts`, ms and peak each — e.g. the passes of every page
+   * batch summed), plus `rest` for whatever of the step they do not cover.
+   */
+  lapParts(parts: ReadonlyMap<string, PartTiming>, rest: string): void {
+    const t = this.#now();
+    const elapsed = t - this.#last;
+    let covered = 0;
+    let coveredCpu = 0;
+    for (const [phase, p] of parts) {
+      covered += p.ms;
+      coveredCpu += p.cpuMs ?? 0;
+      this.#phases.push({
+        phase,
+        ms: Math.round(p.ms),
+        ...(p.peakRssMb !== undefined ? { peakRssMb: p.peakRssMb } : {}),
+        ...(p.cpuMs !== undefined ? { cpuMs: Math.round(p.cpuMs) } : {}),
+      });
+    }
+    this.#phases.push({
+      phase: rest,
+      ms: Math.max(0, Math.round(elapsed - covered)),
+      ...this.#takePeak(),
+      ...this.#takeCpu(coveredCpu),
+    });
+    this.#last = t;
+  }
+
+  /**
+   * Run `fn` and add its duration (and, for a memory timer, its peak RSS)
+   * to `into[phase]` — for steps that repeat per batch, summed by
+   * {@link lapParts}.
+   */
+  async measure<T>(
+    into: Map<string, PartTiming>,
+    phase: string,
+    fn: () => Promise<T> | T,
+  ): Promise<T> {
+    const peakBefore = this.#peak;
+    if (this.#listener) this.#peak = rssNow();
+    const t0 = this.#now();
+    const cpu0 = this.#listener ? cpuNow() : 0;
+    try {
+      return await fn();
+    } finally {
+      const prev = into.get(phase) ?? { ms: 0 };
+      const ms = prev.ms + (this.#now() - t0);
+      if (this.#listener) {
+        const peak = Math.max(this.#peak, rssNow());
+        into.set(phase, {
+          ms,
+          peakRssMb: Math.max(prev.peakRssMb ?? 0, Math.round(peak / MIB)),
+          cpuMs: (prev.cpuMs ?? 0) + (cpuNow() - cpu0),
+        });
+        this.#peak = Math.max(peakBefore, peak);
+      } else {
+        into.set(phase, { ms });
+      }
+    }
+  }
+
   /**
    * Append steps timed elsewhere (the generator subprocess, a publisher)
    * as `<prefix>.<phase>`. They ran inside the current lap, so the lap that
@@ -47,7 +203,7 @@ export class PhaseTimer {
    * around them, e.g. spawning the subprocess).
    */
   include(prefix: string, phases: readonly PhaseTiming[]): void {
-    for (const p of phases) this.#phases.push({ phase: `${prefix}.${p.phase}`, ms: p.ms });
+    for (const p of phases) this.#phases.push({ ...p, phase: `${prefix}.${p.phase}` });
   }
 
   /** Milliseconds since construction. */
@@ -59,4 +215,26 @@ export class PhaseTimer {
   phases(): PhaseTiming[] {
     return [...this.#phases];
   }
+
+  /** Stop sampling memory (a memory timer must be closed; idempotent). */
+  close(): void {
+    if (this.#listener) sampler.remove(this.#listener);
+  }
+
+  /** CPU time since the previous lap, less what parts already account for. */
+  #takeCpu(covered: number): { cpuMs?: number } {
+    if (!this.#listener) return {};
+    const now = cpuNow();
+    const spent = now - this.#lastCpu - covered;
+    this.#lastCpu = now;
+    return { cpuMs: Math.max(0, Math.round(spent)) };
+  }
+
+  /** The peak since the previous lap, then restart it from now. */
+  #takePeak(): { peakRssMb?: number } {
+    if (!this.#listener) return {};
+    const peak = Math.max(this.#peak, rssNow());
+    this.#peak = rssNow();
+    return { peakRssMb: Math.round(peak / MIB) };
+  }
 }

package/src/pool-budget.test.ts

@@ -0,0 +1,111 @@
+// SPDX-License-Identifier: MPL-2.0
+
+/** Issue #1254 — the connection budget formula (pool-budget.ts). */
+
+import { describe, expect, it } from "bun:test";
+import {
+  ADMIN_POOL_FLOOR,
+  ADMIN_PUBLIC_POOL_MAX,
+  computePoolBudget,
+  DB_POOL_MAX_ENV,
+  DB_PUBLIC_POOL_MAX_ENV,
+  GATEWAY_POOL_MAX,
+  GENERATOR_POOL_MAX,
+  LISTEN_CONNECTIONS_PER_ADMIN_INSTANCE,
+  type PoolBudgetInput,
+  poolBudgetEnv,
+} from "./pool-budget.js";
+
+const GCP_DEFAULT: PoolBudgetInput = {
+  maxConnections: 100,
+  adminMaxInstances: 5,
+  gatewayMaxInstances: 10,
+  concurrentBuilds: 2,
+  maintenanceReserve: 5,
+  migrationsReserve: 2,
+  jobsReserve: 4,
+};
+
+describe("computePoolBudget", () => {
+  it("splits what the reserves leave across the admin instances", () => {
+    const b = computePoolBudget(GCP_DEFAULT);
+    // 100 - (5 + 2 + 4 + 8 + 20 + 5 + 10 + 20) = 26 → floor(26 / 5) = 5, 1 left.
+    expect(b.adminPoolMax).toBe(5);
+    expect(b.unassigned).toBe(1);
+    expect(b.adminPublicPoolMax).toBe(ADMIN_PUBLIC_POOL_MAX);
+    expect(b.gatewayPoolMax).toBe(GATEWAY_POOL_MAX);
+    expect(b.generatorPoolMax).toBe(GENERATOR_POOL_MAX);
+  });
+
+  it("never hands out more than max_connections at full scale-out", () => {
+    for (const maxConnections of [60, 100, 250, 429]) {
+      for (const adminMaxInstances of [1, 3, 5]) {
+        const input = { ...GCP_DEFAULT, maxConnections, adminMaxInstances };
+        let b: ReturnType<typeof computePoolBudget>;
+        try {
+          b = computePoolBudget(input);
+        } catch {
+          continue;
+        }
+        const reserved = b.reserves.reduce((s, r) => s + r.connections, 0);
+        expect(reserved + b.adminPoolMax * adminMaxInstances + b.unassigned).toBe(maxConnections);
+      }
+    }
+  });
+
+  it("names a LISTEN reserve of one connection per admin instance (#1267)", () => {
+    const listen = computePoolBudget(GCP_DEFAULT).reserves.find((r) => r.name === "listen");
+    expect(LISTEN_CONNECTIONS_PER_ADMIN_INSTANCE).toBe(1);
+    expect(listen?.connections).toBe(GCP_DEFAULT.adminMaxInstances);
+  });
+
+  it("budgets the gateway and the generator from their instance counts", () => {
+    const r = new Map(computePoolBudget(GCP_DEFAULT).reserves.map((x) => [x.name, x.connections]));
+    expect(r.get("gateway")).toBe(10 * GATEWAY_POOL_MAX);
+    expect(r.get("generator")).toBe(2 * 2 * GENERATOR_POOL_MAX);
+    expect(r.get("admin-public")).toBe(5 * ADMIN_PUBLIC_POOL_MAX);
+  });
+
+  it("refuses a budget below the admin floor, naming the connections needed", () => {
+    // The pre-#1254 GCP shape: 100 gateway instances can never fit 100 slots.
+    expect(() => computePoolBudget({ ...GCP_DEFAULT, gatewayMaxInstances: 100 })).toThrow(
+      /Raise maxConnections to at least 364/,
+    );
+    expect(() => computePoolBudget({ ...GCP_DEFAULT, maxConnections: 50 })).toThrow(
+      new RegExp(`minimum of ${ADMIN_POOL_FLOOR}`),
+    );
+  });
+
+  it("accepts exactly the floor", () => {
+    // reserves 74 + 5 × 4 = 94.
+    expect(computePoolBudget({ ...GCP_DEFAULT, maxConnections: 94 }).adminPoolMax).toBe(4);
+    expect(() => computePoolBudget({ ...GCP_DEFAULT, maxConnections: 93 })).toThrow();
+  });
+
+  it("rejects malformed input instead of guessing", () => {
+    expect(() => computePoolBudget({ ...GCP_DEFAULT, adminMaxInstances: 0 })).toThrow(
+      /adminMaxInstances/,
+    );
+    expect(() => computePoolBudget({ ...GCP_DEFAULT, maxConnections: Number.NaN })).toThrow(
+      /maxConnections/,
+    );
+    expect(() => computePoolBudget({ ...GCP_DEFAULT, jobsReserve: -1 })).toThrow(/jobsReserve/);
+  });
+});
+
+describe("poolBudgetEnv", () => {
+  const b = computePoolBudget(GCP_DEFAULT);
+
+  it("sizes both admin pools", () => {
+    expect(poolBudgetEnv(b, "admin")).toEqual([
+      { name: DB_POOL_MAX_ENV, value: "5" },
+      { name: DB_PUBLIC_POOL_MAX_ENV, value: String(ADMIN_PUBLIC_POOL_MAX) },
+    ]);
+  });
+
+  it("sizes the gateway's only (cms_public) pool", () => {
+    expect(poolBudgetEnv(b, "gateway")).toEqual([
+      { name: DB_PUBLIC_POOL_MAX_ENV, value: String(GATEWAY_POOL_MAX) },
+    ]);
+  });
+});

package/src/pool-budget.ts

@@ -0,0 +1,234 @@
+// SPDX-License-Identifier: MPL-2.0
+
+/**
+ * Issue #1254 — the database connection budget of an install.
+ *
+ * Every Caelo process that talks to Postgres holds connection pools, and
+ * they all draw from ONE server-wide `max_connections` (cms_admin and
+ * cms_public live on the same server). Before #1254 every pool took Bun's
+ * default of 10, so the admin alone asked for `adminMaxInstances × 2 × 10`
+ * — exactly the 100 slots of a default install, with nothing left for the
+ * gateway, the static generator, migrations or the provider's own agents.
+ * Under load the last admin instance to scale up could not connect at all.
+ *
+ * The budget turns that around: provisioning states how many connections
+ * the server has and how many instances may run, every fixed consumer is
+ * named as a {@link PoolBudgetReserve}, and what is left is split across
+ * the admin instances' cms_admin pools — the pool the write path uses.
+ * The admin's cms_public pool is small and fixed: the admin only reads
+ * plugin data there and publishes the gateway projection.
+ *
+ * Why not simply raise the pool: a larger pool only moves the wait from
+ * the pool to the server. A pool sized past the budget fails with "too
+ * many clients" at the worst moment (scale-out under load) instead of
+ * waiting a bounded time for a free connection of its own pool
+ * (query-api pool-guard.ts). docs/dev/connection-budget.md has the long
+ * version.
+ *
+ * Pure module — no I/O. Used by the provisioning stacks (which set the
+ * resulting env on each service) and re-exported by `@caelo-cms/query-api`.
+ */
+
+/** Env var sizing every pool of a `DatabaseAdapter` (both pools, unless the next one is set). */
+export const DB_POOL_MAX_ENV = "CAELO_DB_POOL_MAX";
+
+/**
+ * Env var sizing the cms_public pool of a `DatabaseAdapter` on its own. It
+ * wins over {@link DB_POOL_MAX_ENV} for that pool, so the admin can run a
+ * large cms_admin pool next to a small cms_public one.
+ */
+export const DB_PUBLIC_POOL_MAX_ENV = "CAELO_DB_PUBLIC_POOL_MAX";
+
+/** Smallest pool a `DatabaseAdapter` accepts: one connection self-deadlocks it. */
+export const MIN_POOL_MAX = 2;
+
+/**
+ * Smallest cms_admin pool the budget hands an admin instance. Below it a
+ * handful of concurrent editors and agents queue on every write; an install
+ * whose server cannot afford it must get a larger tier or fewer instances,
+ * so {@link computePoolBudget} refuses instead of shipping a starved pool.
+ */
+export const ADMIN_POOL_FLOOR = 4;
+
+/** The admin's cms_public pool: plugin-data reads and the gateway projection. */
+export const ADMIN_PUBLIC_POOL_MAX = 4;
+
+/** The gateway's only pool (public_role on cms_public), per instance. */
+export const GATEWAY_POOL_MAX = 2;
+
+/**
+ * Each pool of one static-generator subprocess. A build runs in ONE
+ * transaction (pool-guard.ts LONG_TRANSACTION_ALLOWLIST) and takes no
+ * second checkout, so the minimum pool ({@link MIN_POOL_MAX}) is enough.
+ */
+export const GENERATOR_POOL_MAX = 2;
+
+/**
+ * #1267 — the dedicated connection each admin instance keeps open for
+ * `LISTEN` on the change journal's wake-up channel. A LISTEN connection is
+ * held for the instance's lifetime and can never serve a query of the pool,
+ * so it is budgeted outside the pools, one per admin instance.
+ */
+export const LISTEN_CONNECTIONS_PER_ADMIN_INSTANCE = 1;
+
+/**
+ * The connection each gateway instance keeps open for `LISTEN
+ * caelo_gateway_settings` on cms_public (api-gateway server.ts): outside the
+ * gateway's pool, held for the instance's lifetime.
+ */
+export const LISTEN_CONNECTIONS_PER_GATEWAY_INSTANCE = 1;
+
+/** What the budget is computed from: the server and the scale-out limits. */
+export interface PoolBudgetInput {
+  /** The server's `max_connections`, as provisioning sets it. */
+  readonly maxConnections: number;
+  /** Most admin instances that may run at once (Cloud Run `maxInstanceCount`, …). */
+  readonly adminMaxInstances: number;
+  /** Most gateway instances that may run at once. */
+  readonly gatewayMaxInstances: number;
+  /**
+   * Static-generator subprocesses that may run at once across the install
+   * (a Stage, a Publish live and a plugin-data build can overlap).
+   */
+  readonly concurrentBuilds: number;
+  /**
+   * Connections the server keeps for itself and the provider's agents:
+   * `superuser_reserved_connections`, Cloud SQL's `cloudsqladmin`, RDS's
+   * `rdsadmin`, Azure's replication and monitoring slots.
+   */
+  readonly maintenanceReserve: number;
+  /** Connections a migration run opens (one per database). */
+  readonly migrationsReserve: number;
+  /**
+   * Connections of the install's other jobs (operator-access sync,
+   * upgrader, converge). They run one query at a time.
+   */
+  readonly jobsReserve: number;
+}
+
+/** The named consumers the budget sets aside before it sizes the admin's cms_admin pool. */
+export type PoolBudgetReserveName =
+  | "maintenance"
+  | "migrations"
+  | "jobs"
+  | "generator"
+  | "gateway"
+  /** #1267 — one LISTEN connection per admin instance ({@link LISTEN_CONNECTIONS_PER_ADMIN_INSTANCE}). */
+  | "listen"
+  /** The gateway's settings LISTEN, one per gateway instance ({@link LISTEN_CONNECTIONS_PER_GATEWAY_INSTANCE}). */
+  | "gateway-listen"
+  | "admin-public";
+
+/** One consumer of the server's connections the budget sets aside. */
+export interface PoolBudgetReserve {
+  readonly name: PoolBudgetReserveName;
+  readonly connections: number;
+}
+
+/** The computed budget: pool sizes per process, and where every connection goes. */
+export interface PoolBudget {
+  /** cms_admin pool of each admin instance ({@link DB_POOL_MAX_ENV} on the admin). */
+  readonly adminPoolMax: number;
+  /** cms_public pool of each admin instance ({@link DB_PUBLIC_POOL_MAX_ENV} on the admin). */
+  readonly adminPublicPoolMax: number;
+  /** The gateway's cms_public pool ({@link DB_PUBLIC_POOL_MAX_ENV} on the gateway). */
+  readonly gatewayPoolMax: number;
+  /** Each pool of a generator subprocess (the admin sets it on the child). */
+  readonly generatorPoolMax: number;
+  readonly reserves: readonly PoolBudgetReserve[];
+  /** Connections no pool may use (the remainder of the per-instance split). */
+  readonly unassigned: number;
+}
+
+function positiveInteger(value: number, name: string, min: number): void {
+  if (!Number.isInteger(value) || value < min) {
+    throw new Error(`pool budget: ${name} must be an integer >= ${min} (got ${value})`);
+  }
+}
+
+/**
+ * Split `maxConnections` across every process of the install.
+ *
+ * `adminPoolMax = floor((maxConnections − Σ reserves) / adminMaxInstances)`,
+ * where the reserves are the fixed consumers of {@link PoolBudgetInput} plus
+ * `gateway = gatewayMaxInstances × GATEWAY_POOL_MAX`,
+ * `generator = concurrentBuilds × 2 × GENERATOR_POOL_MAX`,
+ * `listen = adminMaxInstances × LISTEN_CONNECTIONS_PER_ADMIN_INSTANCE`,
+ * `gateway-listen = gatewayMaxInstances × LISTEN_CONNECTIONS_PER_GATEWAY_INSTANCE` and
+ * `admin-public = adminMaxInstances × ADMIN_PUBLIC_POOL_MAX`.
+ *
+ * @throws Error naming what to change when the server cannot give every
+ *   admin instance at least {@link ADMIN_POOL_FLOOR} cms_admin connections.
+ *
+ * @example
+ *   computePoolBudget({ maxConnections: 100, adminMaxInstances: 5,
+ *     gatewayMaxInstances: 10, concurrentBuilds: 2, maintenanceReserve: 5,
+ *     migrationsReserve: 2, jobsReserve: 4 }).adminPoolMax // → 7
+ */
+export function computePoolBudget(input: PoolBudgetInput): PoolBudget {
+  positiveInteger(input.maxConnections, "maxConnections", 1);
+  positiveInteger(input.adminMaxInstances, "adminMaxInstances", 1);
+  positiveInteger(input.gatewayMaxInstances, "gatewayMaxInstances", 0);
+  positiveInteger(input.concurrentBuilds, "concurrentBuilds", 0);
+  positiveInteger(input.maintenanceReserve, "maintenanceReserve", 0);
+  positiveInteger(input.migrationsReserve, "migrationsReserve", 0);
+  positiveInteger(input.jobsReserve, "jobsReserve", 0);
+
+  const reserves: PoolBudgetReserve[] = [
+    { name: "maintenance", connections: input.maintenanceReserve },
+    { name: "migrations", connections: input.migrationsReserve },
+    { name: "jobs", connections: input.jobsReserve },
+    { name: "generator", connections: input.concurrentBuilds * 2 * GENERATOR_POOL_MAX },
+    { name: "gateway", connections: input.gatewayMaxInstances * GATEWAY_POOL_MAX },
+    {
+      name: "listen",
+      connections: input.adminMaxInstances * LISTEN_CONNECTIONS_PER_ADMIN_INSTANCE,
+    },
+    {
+      name: "gateway-listen",
+      connections: input.gatewayMaxInstances * LISTEN_CONNECTIONS_PER_GATEWAY_INSTANCE,
+    },
+    { name: "admin-public", connections: input.adminMaxInstances * ADMIN_PUBLIC_POOL_MAX },
+  ];
+  const reserved = reserves.reduce((sum, r) => sum + r.connections, 0);
+  const forAdmin = input.maxConnections - reserved;
+  const adminPoolMax = Math.floor(forAdmin / input.adminMaxInstances);
+  if (adminPoolMax < ADMIN_POOL_FLOOR) {
+    const needed = reserved + ADMIN_POOL_FLOOR * input.adminMaxInstances;
+    const breakdown = reserves.map((r) => `${r.name} ${r.connections}`).join(", ");
+    throw new Error(
+      `pool budget: max_connections ${input.maxConnections} cannot give each of ${input.adminMaxInstances} admin instances the minimum of ${ADMIN_POOL_FLOOR} cms_admin connections ` +
+        `(reserved: ${breakdown}; ${needed} needed). Raise maxConnections to at least ${needed} (a larger database tier may be required), ` +
+        "or lower adminMaxInstances / gatewayMaxInstances.",
+    );
+  }
+  return {
+    adminPoolMax,
+    adminPublicPoolMax: ADMIN_PUBLIC_POOL_MAX,
+    gatewayPoolMax: GATEWAY_POOL_MAX,
+    generatorPoolMax: GENERATOR_POOL_MAX,
+    reserves,
+    unassigned: forAdmin - adminPoolMax * input.adminMaxInstances,
+  };
+}
+
+/** Which service's pool env {@link poolBudgetEnv} returns. */
+export type PoolBudgetService = "admin" | "gateway";
+
+/**
+ * The env that sizes `service`'s pools from `budget`, for the stacks to set.
+ * The admin gets both pools; the gateway, whose only pool is cms_public,
+ * gets just that one.
+ */
+export function poolBudgetEnv(
+  budget: PoolBudget,
+  service: PoolBudgetService,
+): { readonly name: string; readonly value: string }[] {
+  if (service === "gateway") {
+    return [{ name: DB_PUBLIC_POOL_MAX_ENV, value: String(budget.gatewayPoolMax) }];
+  }
+  return [
+    { name: DB_POOL_MAX_ENV, value: String(budget.adminPoolMax) },
+    { name: DB_PUBLIC_POOL_MAX_ENV, value: String(budget.adminPublicPoolMax) },
+  ];
+}

package/src/stage-status.test.ts

@@ -0,0 +1,75 @@
+// SPDX-License-Identifier: MPL-2.0
+
+import { describe, expect, it } from "bun:test";
+import { describeStageRun, formatStageDuration, type StageStatusRun } from "./stage-status.js";
+
+const base: StageStatusRun = {
+  runId: "00000000-0000-0000-0000-000000001288",
+  targetName: "staging",
+  status: "running",
+  phase: "building",
+  pagesDone: 812,
+  pagesTotal: 1904,
+  startedAt: "2026-11-01T07:00:00.000Z",
+  finishedAt: null,
+  elapsedMs: 60_000,
+  error: null,
+  failedPhase: null,
+  eta: { remainingMs: 100_000, basis: "this_run_rate", includesPublish: true },
+  etaUnavailable: null,
+};
+
+describe("formatStageDuration", () => {
+  it("reads like a person would say it", () => {
+    expect(formatStageDuration(45_000)).toBe("45 s");
+    expect(formatStageDuration(100_000)).toBe("1 min 40 s");
+    expect(formatStageDuration(120_000)).toBe("2 min");
+    expect(formatStageDuration(725_000)).toBe("12 min");
+  });
+});
+
+describe("describeStageRun", () => {
+  it("states progress and the estimate with its basis", () => {
+    expect(describeStageRun(base)).toBe(
+      "Building pages 812 of 1,904 — about 1 min 40 s left (from this run's pace)",
+    );
+  });
+
+  it("says when the estimate covers the pages only", () => {
+    expect(
+      describeStageRun({
+        ...base,
+        eta: { remainingMs: 30_000, basis: "this_run_rate", includesPublish: false },
+      }),
+    ).toContain("pages only — publishing time unknown");
+  });
+
+  it("names why there is no estimate instead of a number", () => {
+    expect(
+      describeStageRun({
+        ...base,
+        phase: "preparing",
+        pagesDone: null,
+        pagesTotal: null,
+        eta: null,
+        etaUnavailable: "no successful Stage has recorded its step times yet",
+      }),
+    ).toBe(
+      "Preparing the build (1 min so far) — no estimate: no successful Stage has recorded its step times yet",
+    );
+  });
+
+  it("gives a failed run's step and reason", () => {
+    expect(
+      describeStageRun({
+        ...base,
+        status: "failed",
+        phase: "failed",
+        elapsedMs: 94_736,
+        error: "122 render failure(s)",
+        failedPhase: "generator",
+        eta: null,
+      }),
+    ).toBe("Failed in generator after 1 min 35 s: 122 render failure(s)");
+  });
+});