@ultimat3/cli 29.4.0 → 30.0.0

package/src/db-seed-generate.ts

@@ -0,0 +1,188 @@
+// `x db seed --generate [--rows n] [--seed n]`: rows for every registered entity, off the entity
+// declarations alone (`@ultimat3/testing`'s `seedGraph`), written through each entity's own
+// repository. Generated rows are `dev` fixtures — the same graph `x exercise` runs on — so
+// production is refused whatever tier is asked for. One pass is one row of `x db seed`'s report.
+
+import type { Environment } from '@ultimat3/core';
+import { resolveEnvironment, UltimateError } from '@ultimat3/core';
+import { withTransaction } from '@ultimat3/db';
+import type { EntityCore, SeedTier } from '@ultimat3/entity';
+import { postgresDriver, registeredEntities, seedTiersFor } from '@ultimat3/entity';
+import type { SeedGraph, SeedWriter } from '@ultimat3/testing';
+import { entitySeedWriter, insertSeedGraph, seedGraph } from '@ultimat3/testing';
+import { loadApp } from './app-load';
+import type { CommandContext } from './command';
+import type { SeedPassRow } from './db-seed';
+import { parseSeedTierFlag, renderSeedTable, seedPassToJson } from './db-seed';
+import { readIntFlag } from './flag-number';
+import { withJobDriver } from './jobs-driver';
+import { msg } from './messages';
+import type { CommandResult } from './output';
+import { findingFrom } from './output';
+import type { ParsedArgs } from './parse';
+import { flagBool, flagString } from './parse';
+
+/** The name a generated pass reports under: a seed name no `defineSeed` can be confused with. */
+export const GENERATED_SEED = '(generated)';
+
+/** What `refuseGeneratedSeed` answers: the tier generated rows are, in every report. */
+const GENERATED_TIER: SeedTier = 'dev';
+
+/**
+ * Generated rows asked for where they must not land. `X_SEED_ENVIRONMENT`, the code `x db seed`
+ * already answers "this environment does not run that tier" with — but never its fix: a generated
+ * graph has no natural key to replay against, so no tier name makes production take it.
+ */
+export class GeneratedSeedRefusedError extends UltimateError {
+  constructor(environment: Environment, tiers: readonly SeedTier[]) {
+    super({
+      code: 'X_SEED_ENVIRONMENT',
+      cause: `x db seed --generate writes dev fixture rows, and ULTIMATE_ENV resolved ${environment}, where this run takes ${tiers.join(', ')} — generated rows never reach production, whatever tier is named`,
+      fix: 'ULTIMATE_ENV=development x db seed --generate --dry-run --json',
+    });
+  }
+}
+
+/** Throws unless this environment takes `dev` rows and is not production. */
+export function refuseGeneratedSeed(
+  environment: Environment,
+  requested: SeedTier | undefined,
+): void {
+  const tiers = seedTiersFor(environment, requested);
+  if (environment === 'production' || !tiers.includes(GENERATED_TIER)) {
+    throw new GeneratedSeedRefusedError(environment, tiers);
+  }
+}
+
+export interface GeneratedSeedFlags {
+  readonly rows?: number;
+  readonly seed?: number;
+}
+
+/** `--rows` (at least one) and `--seed`, through the one integer reader. */
+export function generatedSeedFlags(args: ParsedArgs): GeneratedSeedFlags {
+  const rows = readIntFlag(args, {
+    name: 'rows',
+    command: 'db seed',
+    min: 1,
+    max: 10_000,
+    example: 'x db seed --generate --rows 3 --json',
+  });
+  const seed = readIntFlag(args, {
+    name: 'seed',
+    command: 'db seed',
+    min: 0,
+    max: 2_147_483_647,
+    example: 'x db seed --generate --seed 1 --json',
+  });
+  return { ...(rows === undefined ? {} : { rows }), ...(seed === undefined ? {} : { seed }) };
+}
+
+/** The plan: `--rows` per table (per tenant when scoped), drawn from `--seed`. */
+export const generatedSeedPlan = (
+  entities: Readonly<Record<string, EntityCore>>,
+  flags: GeneratedSeedFlags,
+): SeedGraph =>
+  seedGraph(entities, {
+    ...(flags.rows === undefined ? {} : { perTable: flags.rows }),
+    ...(flags.seed === undefined ? {} : { seed: flags.seed }),
+  });
+
+export interface GeneratedSeedWrite {
+  readonly graph: SeedGraph;
+  readonly writer: SeedWriter;
+  readonly dryRun: boolean;
+  /** One transaction around the whole graph: half a graph is a child row with no parent. */
+  readonly transaction: <T>(work: () => Promise<T>) => Promise<T>;
+}
+
+/** Writes the plan, or counts it under `--dry-run`. Never throws — a failure is the row. */
+export async function writeGeneratedSeed(input: GeneratedSeedWrite): Promise<SeedPassRow> {
+  const started = Bun.nanoseconds();
+  const ms = (): number => Math.round((Bun.nanoseconds() - started) / 1_000_000);
+  const base = { file: GENERATED_SEED, name: GENERATED_SEED, tier: GENERATED_TIER, skipped: 0 };
+  try {
+    if (!input.dryRun) await input.transaction(() => insertSeedGraph(input.graph, input.writer));
+    return {
+      ...base,
+      status: 'ok',
+      ms: ms(),
+      inserted: input.graph.inserts.length,
+      updated: input.graph.updates.length,
+      finding: null,
+    };
+  } catch (error) {
+    return {
+      ...base,
+      status: 'failed',
+      ms: ms(),
+      inserted: 0,
+      updated: 0,
+      finding: findingFrom(error),
+    };
+  }
+}
+
+/**
+ * Every registered TABLE, by name — the set the plan and the writer are both handed. A view entity
+ * is left out: Postgres derives its rows, and a write to one is `X_ENTITY_VIEW_READ_ONLY`.
+ */
+export const registeredEntityCores = (): Readonly<Record<string, EntityCore>> =>
+  Object.fromEntries(
+    registeredEntities().flatMap((entry) =>
+      entry.core === undefined || entry.core.$viewQuery !== null
+        ? []
+        : [[entry.name, entry.core as EntityCore]],
+    ),
+  );
+
+/**
+ * The command half. The environment is refused BEFORE the app loads or a connection opens, the
+ * rule `runSeed` keeps for the same reason: the refusal must not have touched the database first.
+ */
+export async function runGeneratedSeed(ctx: CommandContext, root: string): Promise<CommandResult> {
+  const environment = resolveEnvironment({ env: ctx.env });
+  const requested = parseSeedTierFlag(
+    flagString(ctx.args, 'tier') ?? ctx.env['ULTIMATE_SEED_TIER'],
+  );
+  refuseGeneratedSeed(environment, requested);
+  const flags = generatedSeedFlags(ctx.args);
+  const dryRun = flagBool(ctx.args, 'dry-run');
+  const { findings } = await loadApp(root);
+  const entities = registeredEntityCores();
+  const graph = generatedSeedPlan(entities, flags);
+  const write = (): Promise<CommandResult> =>
+    writeGeneratedSeed({
+      graph,
+      writer: entitySeedWriter({ entities, driver: postgresDriver() }),
+      dryRun,
+      transaction: (work) => withTransaction(() => work()),
+    }).then((row) => generatedResult(row, dryRun, findings));
+  return dryRun ? write() : withJobDriver(root, ctx, write);
+}
+
+function generatedResult(
+  row: SeedPassRow,
+  dryRun: boolean,
+  findings: CommandResult['findings'],
+): CommandResult {
+  const loaded = findings ?? [];
+  return {
+    ok: row.finding === null && loaded.length === 0,
+    command: 'db',
+    summary:
+      row.finding !== null
+        ? msg('cli.db.seed.failed', { failed: 1, count: 1 })
+        : dryRun
+          ? msg('cli.db.seed.dryRun', { count: 1 })
+          : msg('cli.db.seed.done', {
+              count: 1,
+              inserted: row.inserted,
+              updated: row.updated,
+              skipped: row.skipped,
+            }),
+    findings: [...(row.finding === null ? [] : [row.finding]), ...loaded],
+    lines: renderSeedTable([row]).map((line) => `  ${line}`),
+    data: seedPassToJson([row]),
+  };
+}

package/src/deploy-verify-findings.ts

@@ -0,0 +1,98 @@
+// What `x deploy verify` reports: its `--json` shape and the finding for each way it fails. Causes
+// run every server-named build through `renderCauseValue`, and fixes every value through
+// `renderFixShellArg`, because a load balancer writes those strings.
+
+import { ERROR_DOCS_URL, renderCauseValue, renderFixShellArg } from '@ultimat3/core';
+import type { VerifyOptions } from './deploy-verify-flags';
+import type { QueueGrade, SampleFailure, SampleTally, UnservedQueue } from './deploy-verify-grade';
+import { tallyToJson } from './deploy-verify-grade';
+import type { Finding, JsonValue } from './output';
+
+/** What the wait ended on. `lastFailure`: the last transport error, when a sample had one. */
+export interface WaitOutcome {
+  readonly tally: SampleTally;
+  readonly closed: boolean;
+  readonly lastFailure: string | undefined;
+}
+
+export const unservedFinding = (unserved: UnservedQueue, origin: string): Finding => {
+  const running =
+    unserved.builds.length === 0
+      ? 'no worker claims it'
+      : `the workers claiming it run ${unserved.builds.map((build) => renderCauseValue(build)).join(', ')}, or are draining`;
+  const queue = renderFixShellArg(unserved.queue, '<queue>');
+  return {
+    code: 'X_DEPLOY_QUEUE_UNSERVED',
+    cause: `queue ${renderCauseValue(unserved.queue)} has no serving worker of this build, with ${unserved.depth} job(s) due or running: ${running}`,
+    fix: `x jobs list --json   # then WORKER_QUEUES=${queue} on a worker Deployment, or x deploy verify --url ${renderFixShellArg(origin, 'https://app.example.com')} --idle-ok ${queue} --json for a scale-to-zero pool`,
+    docs: ERROR_DOCS_URL,
+    meta: { queue: unserved.queue, builds: [...unserved.builds], depth: unserved.depth },
+  };
+};
+
+/** Every queue read failed until `--timeout`: the database was never read, so nothing passed. */
+export const queueReadFinding = (lastFailure: string | undefined): Finding => ({
+  code: 'X_DB_UNAVAILABLE',
+  cause: `no read of x_job_workers succeeded before --timeout passed${lastFailure === undefined ? '' : `: ${renderCauseValue(lastFailure)}`}`,
+  fix: 'x jobs list --json   # the same rows, over the same DATABASE_URL',
+  docs: ERROR_DOCS_URL,
+  ...(lastFailure === undefined ? {} : { meta: { lastFailure } }),
+});
+
+export function sampleFinding(
+  failure: SampleFailure,
+  wait: WaitOutcome,
+  build: string,
+  options: VerifyOptions,
+): Finding {
+  const samples = tallyToJson(wait.tally);
+  const url = renderFixShellArg(options.origin, 'https://app.example.com');
+  const rerun = `x deploy verify --url ${url} --build ${renderFixShellArg(build, '"$BUILD_ID"')} --json`;
+  const name = renderCauseValue(build);
+  const texts: Readonly<Record<SampleFailure, { readonly cause: string; readonly fix: string }>> = {
+    X_DEPLOY_BUILD_MISMATCH: {
+      cause: `no sample of ${samples.total} carried build ${name} before --timeout passed`,
+      fix: `x deploy verify --url ${url} --build "$BUILD_ID" --json   # the id CI stamped; meta.byBuild names what answered`,
+    },
+    X_DEPLOY_BUILD_UNSTAMPED: {
+      cause: `${wait.tally.unstamped} of ${samples.total} samples answered 2xx with no x-ultimate-build, so the image names no build`,
+      fix: 'x build --target docker --json   # stamps BUILD_ID into the image; or set BUILD_ID in the image environment',
+    },
+    X_DEPLOY_UNSTABLE: {
+      cause: `build ${name} answered, but ${options.windowMs} ms of consecutive good samples never closed: ${samples.good} of ${samples.total} were good`,
+      fix: `${rerun}   # samples.byStatus and samples.byBuild name what interrupted it`,
+    },
+  };
+  return {
+    code: failure,
+    ...texts[failure],
+    docs: ERROR_DOCS_URL,
+    meta: {
+      build,
+      byBuild: samples.byBuild,
+      byStatus: samples.byStatus,
+      ...(wait.lastFailure === undefined ? {} : { lastFailure: wait.lastFailure }),
+    },
+  };
+}
+
+export const resultData = (
+  build: string,
+  windowMs: number,
+  tally: SampleTally,
+  queues: QueueGrade,
+): { readonly [key: string]: JsonValue } => ({
+  build,
+  samples: tallyToJson(tally),
+  windowMs,
+  queues: {
+    graded: queues.graded,
+    served: [...queues.served],
+    unserved: queues.unserved.map(({ queue, builds, depth }) => ({
+      queue,
+      builds: [...builds],
+      depth,
+    })),
+    idle: [...queues.idle],
+  },
+});

package/src/deploy-verify-flags.ts

@@ -0,0 +1,109 @@
+// `x deploy verify`'s flags, read and refused before anything is sampled: every value the wait could
+// not use is an `X_CLI_BAD_FLAG` here, never a red run minutes later.
+
+// why: Bun exposes no path-join primitive; the manifest sits at the app root.
+import { join } from 'node:path';
+import { renderCauseValue, stringField } from '@ultimat3/core';
+import { MANIFEST_FILENAME } from '@ultimat3/manifest';
+import { parseDuration } from '@ultimat3/time';
+import type { CommandContext } from './command';
+import { BadFlagError } from './errors';
+import { flagList, flagString } from './parse';
+
+export const VERIFY_COMMAND = 'deploy verify';
+const EXAMPLE = 'x deploy verify --url https://app.example.com --json';
+const DEFAULT_WINDOW = '60s';
+const DEFAULT_INTERVAL = '5s';
+const DEFAULT_TIMEOUT = '10m';
+
+/**
+ * `@ultimat3/time`'s `parseDuration`, the grammar a job's `timeout: '1d'` is read with, so a flag
+ * never refuses a value a declaration accepts. Bare `0` where the flag can mean none; a negative or
+ * a zero where it cannot is refused here, because a wait of nothing is not a wait.
+ */
+export function readDuration(
+  raw: string,
+  flag: { readonly flag: string; readonly zero: boolean },
+): number {
+  const ms = raw.trim() === '0' ? 0 : parsedOrNaN(raw);
+  if (ms >= 0 && (flag.zero || ms > 0)) return ms;
+  throw new BadFlagError({
+    flag: flag.flag,
+    command: VERIFY_COMMAND,
+    reason: `${renderCauseValue(raw)} is not a ${flag.zero ? '' : 'positive '}duration such as 60s, 10m, 1d or PT1H`,
+    fix: EXAMPLE,
+  });
+}
+
+/** `NaN` for anything `parseDuration` refuses: the flag's own refusal above names the flag. */
+function parsedOrNaN(raw: string): number {
+  try {
+    return parseDuration(raw);
+  } catch {
+    return Number.NaN;
+  }
+}
+
+/**
+ * The origin, and only that: `/readyz` lives at the root, so a path would be silently dropped, and
+ * credentials would ride into every log line that names the URL. The cause never echoes the value.
+ */
+function readOrigin(raw: string | undefined): string {
+  const refuse = (reason: string): BadFlagError =>
+    new BadFlagError({ flag: 'url', command: VERIFY_COMMAND, reason, fix: EXAMPLE });
+  if (raw === undefined) throw refuse('it is required: the origin the load balancer answers on');
+  const parsed = URL.canParse(raw) ? new URL(raw) : undefined;
+  if (parsed === undefined || !['http:', 'https:'].includes(parsed.protocol)) {
+    throw refuse('it must be an http or https origin');
+  }
+  if (parsed.href !== `${parsed.origin}/`) {
+    throw refuse('it must be a bare origin: no path, query, fragment or credentials');
+  }
+  return parsed.origin;
+}
+
+/** `--build`, else the manifest's: what `x build --target docker` stamped when CI stamped nothing. */
+export async function readBuild(ctx: CommandContext, root: string): Promise<string> {
+  const given = flagString(ctx.args, 'build');
+  if (given !== undefined && given.trim() !== '') return given;
+  const file = Bun.file(join(root, MANIFEST_FILENAME));
+  // A manifest that is not JSON is one that names no build: refused below, never a raw SyntaxError.
+  const manifest: unknown = (await file.exists())
+    ? await file.json().catch(() => undefined)
+    : undefined;
+  const buildId = stringField(manifest, 'buildId');
+  if (typeof buildId === 'string' && buildId !== '') return buildId;
+  throw new BadFlagError({
+    flag: 'build',
+    command: VERIFY_COMMAND,
+    reason: `not given, and ${MANIFEST_FILENAME} names no buildId`,
+    fix: 'x deploy verify --url https://app.example.com --build "$BUILD_ID" --json',
+  });
+}
+
+export interface VerifyOptions {
+  readonly origin: string;
+  readonly windowMs: number;
+  readonly intervalMs: number;
+  readonly timeoutMs: number;
+  readonly idleOk: readonly string[];
+}
+
+export function readOptions(ctx: CommandContext): VerifyOptions {
+  const duration = (flag: string, fallback: string, zero = false): number =>
+    readDuration(flagString(ctx.args, flag) ?? fallback, { flag, zero });
+  const origin = readOrigin(flagString(ctx.args, 'url'));
+  const windowMs = duration('window', DEFAULT_WINDOW, true);
+  const intervalMs = duration('interval', DEFAULT_INTERVAL);
+  const timeoutMs = duration('timeout', DEFAULT_TIMEOUT);
+  // A window the wait can never hold is a red run whatever production does.
+  if (windowMs > timeoutMs) {
+    throw new BadFlagError({
+      flag: 'window',
+      command: VERIFY_COMMAND,
+      reason: `${windowMs} ms cannot close inside --timeout of ${timeoutMs} ms`,
+      fix: EXAMPLE,
+    });
+  }
+  return { origin, windowMs, intervalMs, timeoutMs, idleOk: flagList(ctx.args, 'idle-ok') };
+}

package/src/deploy-verify-grade.ts

@@ -0,0 +1,185 @@
+// The verdict behind `x deploy verify`, pure: samples folded into a tally and a window, worker rows
+// graded per queue. No socket, no database, no clock — `cmd-deploy-verify.ts` owns the waiting.
+
+import type { WorkerRecord } from '@ultimat3/jobs';
+
+/** One `GET /readyz`. A `null` status is a sample nothing answered: refused, reset, timed out. */
+export interface Sample {
+  /** Monotonic ms, when the answer arrived. */
+  readonly at: number;
+  readonly status: number | null;
+  /** `x-ultimate-build` as answered, on any status. `null`: no header, or an empty one. */
+  readonly build: string | null;
+  /** Answered from a cache (`Age` > 0): a CDN's copy says nothing about the fleet behind it. */
+  readonly cached: boolean;
+}
+
+/** Samples since the first good one: what the bad rate is measured over. */
+export interface SinceGood {
+  readonly total: number;
+  readonly bad: number;
+}
+
+export interface SampleTally {
+  readonly total: number;
+  readonly good: number;
+  /** Built with computed keys and read through `Object.hasOwn`: a server names these. */
+  readonly byBuild: Readonly<Record<string, number>>;
+  readonly byStatus: Readonly<Record<string, number>>;
+  /** 2xx answers that named no build: what `X_DEPLOY_BUILD_UNSTAMPED` is told apart by. */
+  readonly unstamped: number;
+  /** When the current run of good samples began. `null`: the last sample broke it. */
+  readonly goodSince: number | null;
+  readonly lastAt: number | null;
+  readonly cached: number;
+  /** `null` until a sample was good: old answers before it are the roll, not instability. */
+  readonly sinceGood: SinceGood | null;
+}
+
+/** The `byStatus` key of a sample nothing answered. */
+export const UNREACHABLE = 'unreachable';
+
+/** The label `builds` gives a row with no build: a worker from before the column. */
+export const UNKNOWN_BUILD = 'unknown';
+
+export const emptyTally = (): SampleTally => ({
+  total: 0,
+  good: 0,
+  byBuild: {},
+  byStatus: {},
+  unstamped: 0,
+  goodSince: null,
+  lastAt: null,
+  cached: 0,
+  sinceGood: null,
+});
+
+const countOf = (counts: Readonly<Record<string, number>>, key: string): number =>
+  Object.hasOwn(counts, key) ? (counts[key] ?? 0) : 0;
+
+const bump = (
+  counts: Readonly<Record<string, number>>,
+  key: string,
+): Readonly<Record<string, number>> => ({ ...counts, [key]: countOf(counts, key) + 1 });
+
+const is2xx = (status: number | null): boolean => status !== null && status >= 200 && status < 300;
+
+export function foldSample(tally: SampleTally, sample: Sample, build: string): SampleTally {
+  const good = is2xx(sample.status) && sample.build === build && !sample.cached;
+  const since = tally.sinceGood;
+  return {
+    total: tally.total + 1,
+    good: tally.good + (good ? 1 : 0),
+    byBuild: sample.build === null ? tally.byBuild : bump(tally.byBuild, sample.build),
+    byStatus: bump(tally.byStatus, sample.status === null ? UNREACHABLE : String(sample.status)),
+    unstamped: tally.unstamped + (is2xx(sample.status) && sample.build === null ? 1 : 0),
+    // Any bad sample restarts it: an old build mid-window is a roll still in flight.
+    goodSince: good ? (tally.goodSince ?? sample.at) : null,
+    lastAt: sample.at,
+    cached: tally.cached + (sample.cached ? 1 : 0),
+    sinceGood:
+      since === null
+        ? good
+          ? { total: 1, bad: 0 }
+          : null
+        : { total: since.total + 1, bad: since.bad + (good ? 0 : 1) },
+  };
+}
+
+/**
+ * Closed when the good run spans `windowMs` AND, since the first good sample, fewer than one sample
+ * in `perWindow` (`ceil(window / interval)`) was bad. The run alone passed a fleet stuck with 10% old
+ * pods 99.6% of the time: thirteen good in a row happen by chance. `--window 0` closes on the first
+ * good sample: the build answered once.
+ */
+export const windowClosed = (tally: SampleTally, windowMs: number, perWindow: number): boolean =>
+  tally.goodSince !== null &&
+  tally.lastAt !== null &&
+  tally.lastAt - tally.goodSince >= windowMs &&
+  tally.sinceGood !== null &&
+  tally.sinceGood.bad * perWindow < tally.sinceGood.total;
+
+export type SampleFailure =
+  | 'X_DEPLOY_BUILD_MISMATCH'
+  | 'X_DEPLOY_BUILD_UNSTAMPED'
+  | 'X_DEPLOY_UNSTABLE';
+
+/**
+ * Why a wait ended without the window closing. "The build answered" reads the header on any status:
+ * a new pod answering 503 is the build, unstable, and telling that operator it never shipped would
+ * send them to the wrong problem. Unstamped only when no sample named any build, because one old
+ * build beside it means the header works and the build is what is missing.
+ */
+export function failureOf(tally: SampleTally, build: string): SampleFailure {
+  if (countOf(tally.byBuild, build) > 0) return 'X_DEPLOY_UNSTABLE';
+  const namedNone = Object.keys(tally.byBuild).length === 0;
+  return namedNone && tally.unstamped > 0 ? 'X_DEPLOY_BUILD_UNSTAMPED' : 'X_DEPLOY_BUILD_MISMATCH';
+}
+
+/** The tally as `--json` reports it. The window's bookkeeping stays out. */
+export const tallyToJson = (tally: SampleTally) => ({
+  total: tally.total,
+  good: tally.good,
+  byBuild: { ...tally.byBuild },
+  byStatus: { ...tally.byStatus },
+  /** Each build's share of every sample, to three places: a stuck roll reads as its old share. */
+  share: Object.fromEntries(
+    Object.entries(tally.byBuild).map(([name, count]) => [
+      name,
+      Math.round((count / Math.max(1, tally.total)) * 1000) / 1000,
+    ]),
+  ),
+  cached: tally.cached,
+});
+
+export interface UnservedQueue {
+  readonly queue: string;
+  /** Every build a live row claiming this queue runs, sorted: a stalled roll reads as one. */
+  readonly builds: readonly string[];
+  readonly depth: number;
+}
+
+export interface QueueGrade {
+  readonly graded: boolean;
+  readonly served: readonly string[];
+  readonly unserved: readonly UnservedQueue[];
+  /** On `--idle-ok`, no serving worker, depth 0. */
+  readonly idle: readonly string[];
+}
+
+/** No `DATABASE_URL`, or a window that never closed: nothing was read, so nothing passed. */
+export const UNGRADED: QueueGrade = Object.freeze({
+  graded: false,
+  served: [],
+  unserved: [],
+  idle: [],
+});
+
+export interface QueueGradeInput {
+  readonly build: string;
+  readonly expected: readonly string[];
+  readonly workers: readonly WorkerRecord[];
+  /** Work a worker would have to run now, per queue. A queue with no entry holds none. */
+  readonly depth: ReadonlyMap<string, number>;
+  readonly idleOk: readonly string[];
+}
+
+export function gradeQueues(input: QueueGradeInput): QueueGrade {
+  const served: string[] = [];
+  const unserved: UnservedQueue[] = [];
+  const idle: string[] = [];
+  for (const queue of input.expected) {
+    const claiming = input.workers.filter((worker) => worker.queues.includes(queue));
+    const serving = claiming.some(
+      (worker) => worker.drainingAt === undefined && worker.build === input.build,
+    );
+    const depth = input.depth.get(queue) ?? 0;
+    if (serving) served.push(queue);
+    else if (depth === 0 && input.idleOk.includes(queue)) idle.push(queue);
+    else {
+      const builds = new Set(claiming.map((worker) => worker.build ?? UNKNOWN_BUILD));
+      unserved.push({ queue, builds: [...builds].sort(), depth });
+    }
+  }
+  return { graded: true, served, unserved, idle };
+}

package/src/deploy-verify-queues.ts

@@ -0,0 +1,53 @@
+// The real sources behind `x deploy verify`'s queue grade: the set an app's workers must claim, and
+// the rows that say who claims them. Apart from the command so the verdict on the build alone never
+// imports the app's module graph or a database driver.
+
+import { dbExecutor, postgresClient } from '@ultimat3/db';
+import type { JobDriver } from '@ultimat3/jobs';
+import { postgresJobDriver, registeredJobs } from '@ultimat3/jobs';
+import { loadAppConfig } from './app-config-load';
+import { loadApp } from './app-load';
+import type { ExpectedQueues, QueueReader } from './cmd-deploy-verify';
+import { workerQueuesFor } from './runtime-jobs';
+
+/**
+ * What an unset `WORKER_QUEUES` serves: `jobs.queues` plus every registered job's queue. A closed
+ * set: a `WORKER_QUEUES` pattern is refused at boot (`X_WORKER_QUEUE_UNKNOWN`), and a queue only
+ * `enqueue({ queue })` reaches has to be in `jobs.queues`.
+ */
+export async function expectedQueues(root: string): Promise<ExpectedQueues> {
+  const { findings } = await loadApp(root);
+  const config = await loadAppConfig(root);
+  const registered = registeredJobs().map((handle) => handle.queue);
+  return { queues: workerQueuesFor(config?.jobs.queues ?? [], registered) ?? [], findings };
+}
+
+/** One connection, against the url given and never the ambient client: this process owns no db. */
+export function openQueue(
+  url: string,
+  env: Readonly<Record<string, string | undefined>>,
+  statementTimeoutMs: number,
+): Promise<QueueReader> {
+  const client = postgresClient({
+    url,
+    // The server cancels a read past what is left of `--timeout`: the command stops waiting on its
+    // own clock, and this is what stops the database working on a query nobody reads.
+    profile: { max: 1, statementTimeoutMs },
+    env,
+    applicationName: 'x deploy verify',
+  });
+  const driver = postgresJobDriver({ executor: dbExecutor(() => client) });
+  return Promise.resolve(queueReaderOf(driver, () => client.close()));
+}
+
+/**
+ * Any driver as the grade's reader. A driver with no registry lists no worker: the grade then reads
+ * every queue unserved, never served by default.
+ */
+export function queueReaderOf(driver: JobDriver, close: () => Promise<void>): QueueReader {
+  return {
+    workers: async () => (await driver.introspect?.workers()) ?? [],
+    demand: () => driver.demand(),
+    close,
+  };
+}