@ultimat3/cli 22.6.1 → 22.7.0

package/src/test-workers.ts

@@ -3,10 +3,12 @@
 // suite two different ways, and the `--worker N` reproduction a shard failure prints would then
 // name a shard the gate never ran.
 
-// Bun ships no CPU-count or free-memory primitive: `cpus()` is the fallback when navigator cannot
-// answer, and `freemem()` is the only reader of available memory.
-import { cpus, freemem } from 'node:os';
+// Bun ships no CPU-count or memory primitive: `cpus()` is the fallback when navigator cannot
+// answer, and `totalmem()` is the only reader of the machine's RAM.
+// why: Bun ships no CPU-count or total-memory primitive.
+import { cpus, totalmem } from 'node:os';
 import type { TestType } from '@ultimat3/testing';
+import { TestBudgetInvalidError } from './verify-errors';
 
 /** navigator first: it is the runtime's own answer, and it respects a container's CPU limit. */
 export function availableCpus(): number {
@@ -15,56 +17,75 @@ export function availableCpus(): number {
 }
 
 /**
- * Deliberately MORE workers than cores, bounded by memory rather than by a fixed count.
+ * The width of a default run is a MEMORY question first and a CPU question second, and the memory
+ * it plans on is a BUDGET, not "whatever looks free".
  *
- * `cpus - 1` is the intuitive default and it was measured to be worthless exactly where it has to
- * pay off. On a 4-core `ubuntu-latest` — the runner this repo commits to — the `unit` step:
+ * Until 22.7 the default was `ceil(cpus x 1.5)` held to 60% of `os.freemem()`. Both halves failed
+ * on the machines Ultimate is for (8-16 GB, 2-8 cores, often two agents' gates at once):
  *
- *   | workers | wall  |
- *   |---------|-------|
- *   | serial  | 43.2s |
- *   | 3 (cpus - 1) | 44.8s |   <- the old default: slower than not sharding at all
- *   | 4       | 41.6s |
- *   | 6       | 34.8s |
+ * - `freemem()` is MemAvailable, which counts reclaimable page cache, so a box that had just built
+ *   read as mostly free. Two gates planned independently, each took 14-18 workers, and on
+ *   2026-09-27 a 45 GB box with no swap was OOM-killed with 36 `bun` processes holding ~40 GB.
+ * - 1.5x the cores only paid when every worker was stalled on `--isolate` rebuilding a module
+ *   registry per file. Without isolation (the default since 22.7, below) a worker is CPU-bound,
+ *   and oversubscribing only multiplies memory.
  *
- * Three workers on four cores loses to serial because sharding is not free — each worker reloads
- * the framework's module graph — and three of them cannot cover that cost. The reason more-than-
- * cores wins is that a test worker is not CPU-bound end to end: it spends real time on module
- * resolution, on `--isolate` rebuilding a registry per file, and on waiting for its database.
- * Oversubscribing fills those stalls.
- *
- * The bound is memory, not cores. A worker is a whole Bun process with the framework's module
- * graph loaded and — in the typed suites — its own cloned Postgres or an in-process PGlite. Until
- * 22.3 that was a FIXED ceiling of 8, which held a 12-core box to 8 workers with 30 GB free: the
- * notificado.co `unit` step (381 files) sat at 51s on 8 workers against a 90s gate budget. The
- * ceiling is now what the machine can actually hold — `os.freemem()` (MemAvailable on Linux, so
- * reclaimable page cache counts as free) divided by `WORKER_BYTES` — which still binds on a small
- * CI runner and on a loaded laptop, the two places an unbounded count would swap.
- *
- * The floor of 2 keeps a 1-core box sharding rather than silently reverting to serial.
+ * So: `min(GATE_BUDGET_CAP, max(GATE_BUDGET_FLOOR, GATE_BUDGET_SHARE x TOTAL memory))` — total, never free, so the plan
+ * is the same on every run of the same machine — divided by `WORKER_BYTES`, clamped to 1..cpus.
+ * `ULTIMATE_TEST_MEMORY_BUDGET` (e.g. `3g`) replaces the budget, `ULTIMATE_TEST_MAX_WORKERS` caps
+ * the width, and an explicit `--workers` wins over both.
  */
-export const WORKER_OVERSUBSCRIBE = 1.5;
+export const GATE_BUDGET_CAP = 4 * 1024 * 1024 * 1024;
 
-/** The floor the paragraph above names: a 1-core box shards rather than reverting to serial. */
-export const WORKER_FLOOR = 2;
+/** A quarter of the machine: an editor, a language server and another agent's gate need the rest. */
+export const GATE_BUDGET_SHARE = 0.25;
+
+/**
+ * The budget never plans below this: enough for TWO workers at `WORKER_BYTES`. A quarter of an
+ * 8 GB laptop (2 GiB) planned one worker, ~4.7 min for notificado.co's unit tier; two stay inside
+ * the owner's 1-4 GB gate target (~2.6 GB measured).
+ */
+export const GATE_BUDGET_FLOOR = 2.75 * 1024 * 1024 * 1024;
 
 /**
- * What one test worker is budgeted at, for the memory bound above. MEASURED — peak RSS of the whole
- * `x test unit` process tree on the notificado.co corpus (381 files, PGlite per worker), 12-core
- * box, `As of 2026-09-25`:
+ * What one test worker is planned at. MEASURED, whole-tree RSS sampled every 200 ms, Bun 1.4.0,
+ * 12-core box, `As of 2026-09-27`, NO isolation:
  *
- *   | workers | peak tree RSS |
- *   |---------|---------------|
- *   | 8       | 20.7 GB       |
- *   | 12      | 22.5 GB       |
- *   | 16      | 24.3 GB       |
+ *   | corpus                                  | workers | batch | peak tree | tree / worker |
+ *   |-----------------------------------------|---------|-------|-----------|---------------|
+ *   | framework unit (1620 files)             | 4       | 24    | 3.61-3.78 GB | 0.90-0.95 GB |
+ *   | notificado.co unit (768 files)          | 4       | 24    | 4.26-4.58 GB | 1.07-1.15 GB |
+ *   | notificado.co unit (768 files)          | 4       | 48    | 4.35 GB   | 1.09 GB       |
+ *   | notificado.co unit (768 files)          | 3       | 24    | 3.28-3.61 GB | 1.09-1.20 GB |
  *
- * The MARGINAL worker costs ~0.45 GB (the slope); the ~17 GB intercept is the corpus itself —
- * every file's module graph and database, retained per worker — and does not shrink with fewer
- * workers, so it is not this bound's to budget. The constant is the slope doubled and rounded to a
- * power of two, because free memory is read once, before a single worker has started.
+ * The planning figure is what the TREE costs per worker at its peak — the `x` parent and Bun's
+ * coordinator included — rounded up from the heaviest corpus, not the largest single worker:
+ * workers do not all peak at the same instant. The floor of a worker is not the runner: a Bun
+ * process that has booted ONE PGlite sits at 0.9-1.1 GB RSS even after `close()` and a full GC
+ * (measured standalone), so a suite on the embedded database cannot plan below ~1 GB a worker.
+ */
+export const WORKER_BYTES = 1.25 * 1024 * 1024 * 1024;
+
+/** The fewest workers `--workers` accepts and the fewest a default plans: one is a legal width. */
+export const WORKER_FLOOR = 1;
+
+/**
+ * Files each ISOLATED worker is handed before its `bun test` process is thrown away and a fresh one
+ * takes the next batch (`test-batches.ts`, which carries the measurement): under `--isolate` every
+ * file re-evaluates the module graph and the heap grows per file, so the recycle point is what
+ * makes the peak a function of the width rather than of the corpus.
+ */
+export const BATCH_FILES_PER_WORKER = 24;
+
+/**
+ * The recycle point WITHOUT isolation (the default since 22.7). A shared worker's peak is set by
+ * its live PGlite, not by how many files it has run, and a batch boundary is pure cost: every
+ * worker restarts, re-imports the app and re-boots its database, and the batch waits on its
+ * slowest file. Measured on notificado.co's unit tier (768 files, 281 s of file time, 3 workers,
+ * no isolation): 6 batches of 48/worker 150-172 s, ONE batch 92-94 s at 3.9 GB peak — the work
+ * floor (281 s / 3). 256 a worker keeps a recycle point for a corpus far past that size.
  */
-export const WORKER_BYTES = 1024 * 1024 * 1024;
+export const SHARED_BATCH_FILES_PER_WORKER = 256;
 
 /**
  * The most `--workers` accepts, on either command. Not a default and not a memory rule — a sanity
@@ -73,35 +94,126 @@ export const WORKER_BYTES = 1024 * 1024 * 1024;
  */
 export const WORKER_CEILING = 64;
 
-/** Bun ships no memory primitive; `freemem()` is libuv's MemAvailable on Linux. */
-export const availableMemory = (): number => freemem();
+/** Replaces the budget: `3g`, `512m`, `4GiB`, or a byte count. */
+export const MEMORY_BUDGET_ENV = 'ULTIMATE_TEST_MEMORY_BUDGET';
+
+/** Caps the default width: a positive integer. */
+export const MAX_WORKERS_ENV = 'ULTIMATE_TEST_MAX_WORKERS';
+
+/** Bun ships no memory primitive; `totalmem()` is the machine's (or the cgroup-blind host's) RAM. */
+export const totalMemory = (): number => totalmem();
+
+type Env = Readonly<Record<string, string | undefined>>;
+
+const UNITS: Readonly<Record<string, number>> = {
+  '': 1,
+  b: 1,
+  k: 1024,
+  kb: 1024,
+  kib: 1024,
+  m: 1024 ** 2,
+  mb: 1024 ** 2,
+  mib: 1024 ** 2,
+  g: 1024 ** 3,
+  gb: 1024 ** 3,
+  gib: 1024 ** 3,
+};
 
 /**
- * `ceil(cpus x 1.5)`, held to what free memory can carry and never below the floor. The file-count
- * clamp is `test-passes.ts`'s (every pass is clamped to its own file list), because only the
- * caller knows the selection.
+ * `3g` → 3 GiB. Binary units whatever the spelling, because the reader is sizing against RSS and
+ * RSS is pages. `undefined` for anything else — the caller refuses it with the value in the cause,
+ * rather than a typo silently meaning "the default".
  */
-export const defaultWorkers = (
-  available: number = availableCpus(),
-  freeBytes: number = availableMemory(),
-): number => {
-  const byCpu = Math.ceil(available * WORKER_OVERSUBSCRIBE);
-  const byMemory = Math.floor(freeBytes / WORKER_BYTES);
-  return Math.max(WORKER_FLOOR, Math.min(byCpu, byMemory, WORKER_CEILING));
+export const parseBytes = (raw: string): number | undefined => {
+  const match = /^\s*(\d+(?:\.\d+)?)\s*([a-z]*)\s*$/i.exec(raw);
+  if (match === null) return undefined;
+  const unit = (match[2] ?? '').toLowerCase();
+  if (!Object.hasOwn(UNITS, unit)) return undefined;
+  const bytes = Math.floor(Number(match[1]) * (UNITS[unit] as number));
+  return Number.isFinite(bytes) && bytes > 0 ? bytes : undefined;
 };
 
+/** Why the width is what it is, in words a step line can print. */
+export interface WorkerPlan {
+  readonly workers: number;
+  readonly budgetBytes: number;
+  /** Which bound decided the width. */
+  readonly boundBy: 'budget' | 'cpus' | 'max-workers';
+  /** `4 workers (budget 4.0 GB)` — the step line's suffix. */
+  readonly reason: string;
+}
+
+const gb = (bytes: number): string => (bytes / 1024 ** 3).toFixed(1);
+
+/** The budget a default run plans on: the env override, or `min(4 GiB, max(2.75 GiB, 25% of RAM))`. */
+export function memoryBudget(total: number = totalMemory(), env: Env = Bun.env): number {
+  const raw = env[MEMORY_BUDGET_ENV];
+  if (raw !== undefined && raw.trim() !== '') {
+    const bytes = parseBytes(raw);
+    if (bytes === undefined) throw new TestBudgetInvalidError(MEMORY_BUDGET_ENV, raw);
+    return bytes;
+  }
+  return Math.min(
+    GATE_BUDGET_CAP,
+    Math.max(GATE_BUDGET_FLOOR, Math.floor(Math.max(0, total) * GATE_BUDGET_SHARE)),
+  );
+}
+
+const maxWorkersOf = (env: Env): number | undefined => {
+  const raw = env[MAX_WORKERS_ENV];
+  if (raw === undefined || raw.trim() === '') return undefined;
+  const value = Number(raw.trim());
+  if (!Number.isInteger(value) || value < 1) throw new TestBudgetInvalidError(MAX_WORKERS_ENV, raw);
+  return value;
+};
+
+/**
+ * `clamp(1..cpus, floor(budget / WORKER_BYTES))`, then `ULTIMATE_TEST_MAX_WORKERS`. Never more
+ * workers than cores, never fewer than one. The file-count clamp is `test-passes.ts`'s, because
+ * only the caller knows the selection.
+ */
+export function workerPlan(
+  cpus: number = availableCpus(),
+  total: number = totalMemory(),
+  env: Env = Bun.env,
+): WorkerPlan {
+  const budgetBytes = memoryBudget(total, env);
+  const cores = Math.max(1, Math.trunc(cpus));
+  const byBudget = Math.max(WORKER_FLOOR, Math.floor(budgetBytes / WORKER_BYTES));
+  const cap = maxWorkersOf(env);
+  let workers = Math.min(cores, byBudget, WORKER_CEILING);
+  let boundBy: WorkerPlan['boundBy'] = byBudget <= cores ? 'budget' : 'cpus';
+  if (cap !== undefined && cap < workers) {
+    workers = cap;
+    boundBy = 'max-workers';
+  }
+  const noun = workers === 1 ? 'worker' : 'workers';
+  const why =
+    boundBy === 'max-workers'
+      ? `${MAX_WORKERS_ENV}=${String(cap)}`
+      : boundBy === 'cpus'
+        ? `${String(cores)} cores, budget ${gb(budgetBytes)} GB`
+        : `budget ${gb(budgetBytes)} GB`;
+  return { workers, budgetBytes, boundBy, reason: `${String(workers)} ${noun} (${why})` };
+}
+
+/** The width alone — `workerPlan(...).workers`. */
+export const defaultWorkers = (
+  cpus: number = availableCpus(),
+  total: number = totalMemory(),
+  env: Env = Bun.env,
+): number => workerPlan(cpus, total, env).workers;
+
 /**
  * The width for a parallel suite that SHARES the machine — `x verify` runs the static steps beside
- * `live`, `job`, `e2e` and `eval` (`verify-run.ts`), and each of those scans is a CPU-bound process
- * of its own. `defaultWorkers()`' oversubscription fills a worker's own stalls when nothing else
- * wants the cores; beside six other processes it only multiplies the contention. Measured on
- * notificado.co, 8 vCPU (#537): at 1.5x, `errors` went 1.8s alone → 7.9s in the gate and
- * `boundaries` 2.3s → 9.7s. So: one worker per core, still held to what memory can carry.
+ * `live`, `job`, `e2e` and `eval` (`verify-run.ts`). The default is already one worker per core at
+ * most, so this is the same plan; it stays a name of its own so the overlap window has one reader.
  */
 export const sharedWorkers = (
-  available: number = availableCpus(),
-  freeBytes: number = availableMemory(),
-): number => Math.min(defaultWorkers(available, freeBytes), Math.max(WORKER_FLOOR, available));
+  cpus: number = availableCpus(),
+  total: number = totalMemory(),
+  env: Env = Bun.env,
+): number => defaultWorkers(cpus, total, env);
 
 /**
  * Which types run across worker processes, and why the other two cannot.

package/src/verify-errors.ts

@@ -0,0 +1,49 @@
+// The gate's sizing and CI-split refusals: a bad budget env var, an unsplittable `--shard`, and a
+// `x verify merge` part that is not a verify document. Split from errors.ts at its size ceiling.
+
+import { UltimateError } from '@ultimat3/core';
+
+/**
+ * `ULTIMATE_TEST_MEMORY_BUDGET` or `ULTIMATE_TEST_MAX_WORKERS` set to something that does not
+ * parse. Refused rather than ignored: a typo read as "the default" is a run sized for a machine
+ * the caller said this is not.
+ */
+export class TestBudgetInvalidError extends UltimateError {
+  constructor(name: string, value: string) {
+    super({
+      code: 'X_TEST_BUDGET_INVALID',
+      cause: `${name}=${JSON.stringify(value)} does not parse — ${
+        name === 'ULTIMATE_TEST_MAX_WORKERS'
+          ? 'expected a positive integer'
+          : 'expected a size such as 3g, 512m or 4GiB'
+      }`,
+      fix:
+        name === 'ULTIMATE_TEST_MAX_WORKERS'
+          ? 'ULTIMATE_TEST_MAX_WORKERS=4 x verify'
+          : 'ULTIMATE_TEST_MEMORY_BUDGET=3g x verify',
+    });
+  }
+}
+
+/** `x verify --shard` asked for a split the gate cannot make. */
+export class VerifyShardInvalidError extends UltimateError {
+  constructor(input: { reason: string; fix?: string }) {
+    super({
+      code: 'X_VERIFY_SHARD_INVALID',
+      cause: `x verify --shard: ${input.reason}`,
+      fix: input.fix ?? 'x verify --only unit --shard 1/4 --json',
+    });
+  }
+}
+
+/** A part handed to `x verify merge` that is not an `x verify --json` document. */
+export class VerifyMergeInputError extends UltimateError {
+  constructor(input: { file: string; reason: string; sourceError?: unknown }) {
+    super({
+      code: 'X_VERIFY_MERGE_INPUT',
+      cause: `x verify merge: ${input.file} ${input.reason}`,
+      fix: 'x verify --only <step> --json > part.json   # one document per part, the last line of stdout',
+      ...(input.sourceError === undefined ? {} : { sourceError: input.sourceError }),
+    });
+  }
+}

package/src/verify-floor.ts

@@ -41,6 +41,13 @@ export interface VerifyFloor {
    * found` from its own shell, not a framework opinion about which compiler is correct.
    */
   readonly typecheckBin?: string;
+  /**
+   * Run every parallel test file in a fresh global (`bun test --isolate`). Absent or `false` is
+   * the default since 22.7: one global per worker process, reused across the files it runs — 2-5x
+   * faster, measured (`test-workers.ts`). A repository whose tests lean on per-file module state
+   * says `true` here once, in the file that configures the gate, and `x test`/`x verify` honour it.
+   */
+  readonly isolate?: boolean;
   /** Why part of the file is not a floor. The `manifest` step reports these; nothing swallows them. */
   readonly problems: readonly string[];
 }
@@ -51,6 +58,22 @@ export const BUDGET_FIELD = 'agentsMdMaxBytes';
 /** The floor's typecheck-binary key. Named once: the problem quotes it and the fix repairs it. */
 export const TYPECHECK_BIN_FIELD = 'typecheckBin';
 
+/** The floor's isolation key. */
+export const ISOLATE_FIELD = 'isolate';
+
+function readIsolate(payload: Record<string, unknown> | undefined): {
+  isolate?: boolean;
+  problems: readonly string[];
+} {
+  const raw = payload?.[ISOLATE_FIELD];
+  if (raw === undefined) return { problems: [] };
+  if (typeof raw !== 'boolean')
+    return {
+      problems: [`"${ISOLATE_FIELD}" is ${JSON.stringify(raw)}, which is not true or false`],
+    };
+  return { isolate: raw, problems: [] };
+}
+
 /**
  * `agentsMdMaxBytes`, or a reason it is not one. A budget that is not a positive whole number is
  * the caller's bug and must not silently fall back to the default: a floor file that says
@@ -123,16 +146,19 @@ export function parseVerifyFloor(
   const record = asRecord(payload);
   const budget = readBudget(record);
   const typecheckBin = readTypecheckBin(record);
+  const isolate = readIsolate(record);
   const steps = record?.['steps'];
   if (!Array.isArray(steps)) {
     return {
       steps: [],
       ...(budget.budget === undefined ? {} : { agentsMdMaxBytes: budget.budget }),
       ...(typecheckBin.bin === undefined ? {} : { typecheckBin: typecheckBin.bin }),
+      ...(isolate.isolate === undefined ? {} : { isolate: isolate.isolate }),
       problems: [
         'it has no "steps" array of step names',
         ...budget.problems,
         ...typecheckBin.problems,
+        ...isolate.problems,
       ],
     };
   }
@@ -142,7 +168,9 @@ export function parseVerifyFloor(
     steps: named.filter((step) => declared.includes(step)),
     ...(budget.budget === undefined ? {} : { agentsMdMaxBytes: budget.budget }),
     ...(typecheckBin.bin === undefined ? {} : { typecheckBin: typecheckBin.bin }),
+    ...(isolate.isolate === undefined ? {} : { isolate: isolate.isolate }),
     problems: [
+      ...isolate.problems,
       ...(named.length === steps.length ? [] : ['"steps" holds an entry that is not a string']),
       ...typecheckBin.problems,
       ...(unknown.length === 0

package/src/verify-merge.ts

@@ -0,0 +1,235 @@
+// `x verify merge <part.json…>`: n CI jobs' `x verify --only … [--shard i/n] --json` documents
+// back into ONE gate verdict. Green only when the parts are provably the whole gate:
+//
+// - every step of `VERIFY_STEP_NAMES` reported by exactly one part — or, for a sharded step, by
+//   shards 1..n exactly once each, all counting the same corpus (`corpusHash`);
+// - the zero-tests floor applied to the SUMMED counts of a sharded step, which each shard deferred;
+// - any gap is a named `X_VERIFY_MERGE_INCOMPLETE` finding, never a silent pass.
+//
+// The merged document is a gate run (no `notAGateRun`), because the question it answers — did
+// every step run, over the whole tree, and pass — is the gate's question.
+
+import { ERROR_DOCS_URL, renderThrowable } from '@ultimat3/core';
+import { msg } from './messages';
+import type { CommandResult, Finding, StepResult } from './output';
+import type { TestCounts } from './test-counts';
+import { VerifyMergeInputError } from './verify-errors';
+import type { VerifyFloor } from './verify-floor';
+import { floorRequires, skippedSuiteFinding } from './verify-floor';
+import { verifySummary } from './verify-run';
+import { VERIFY_STEP_NAMES } from './verify-step';
+
+interface PartStep {
+  readonly name: string;
+  readonly ok: boolean;
+  readonly durationMs: number;
+  readonly skipped: boolean;
+  readonly findings: readonly Finding[];
+  readonly workers?: number;
+  readonly tests?: TestCounts;
+  readonly output?: string;
+  readonly shard?: {
+    readonly index: number;
+    readonly total: number;
+    readonly corpusHash: string;
+    readonly files: readonly string[];
+  };
+}
+
+export interface VerifyPart {
+  readonly file: string;
+  readonly durationMs: number;
+  readonly steps: readonly PartStep[];
+}
+
+const isRecord = (value: unknown): value is Record<string, unknown> =>
+  typeof value === 'object' && value !== null && !Array.isArray(value);
+
+/**
+ * The LAST non-empty line that parses: `bin/check --json` prints the build's document and then
+ * the gate's, and a reader takes the last one.
+ */
+export function parsePart(file: string, text: string): VerifyPart {
+  const lines = text
+    .split('\n')
+    .map((line) => line.trim())
+    .filter((line) => line.length > 0);
+  if (lines.length === 0) throw new VerifyMergeInputError({ file, reason: 'is empty' });
+  let doc: unknown;
+  try {
+    doc = JSON.parse(lines[lines.length - 1] as string);
+  } catch (error) {
+    throw new VerifyMergeInputError({
+      file,
+      reason: `does not end in a JSON document (${renderThrowable(error)})`,
+      sourceError: error,
+    });
+  }
+  if (!isRecord(doc) || doc['command'] !== 'verify' || !Array.isArray(doc['steps'])) {
+    throw new VerifyMergeInputError({
+      file,
+      reason: 'is not an x verify --json document (no "command": "verify" with "steps")',
+    });
+  }
+  const data = isRecord(doc['data']) ? doc['data'] : {};
+  const steps: PartStep[] = [];
+  for (const raw of doc['steps'] as unknown[]) {
+    if (!isRecord(raw) || typeof raw['name'] !== 'string' || typeof raw['ok'] !== 'boolean') {
+      throw new VerifyMergeInputError({ file, reason: 'holds a step without a name and ok' });
+    }
+    steps.push(raw as unknown as PartStep);
+  }
+  return {
+    file,
+    durationMs: typeof data['durationMs'] === 'number' ? data['durationMs'] : 0,
+    steps,
+  };
+}
+
+const gap = (cause: string, at?: string): Finding => ({
+  code: 'X_VERIFY_MERGE_INCOMPLETE',
+  cause,
+  fix: 'x verify merge parts/*.json --json   # after every CI job uploaded its part',
+  docs: ERROR_DOCS_URL,
+  ...(at === undefined ? {} : { at }),
+});
+
+const sumCounts = (steps: readonly PartStep[]): TestCounts | undefined => {
+  const counted = steps.filter((step) => step.tests !== undefined);
+  if (counted.length === 0) return undefined;
+  return counted.reduce<TestCounts>(
+    (sum, step) => ({
+      ran: sum.ran + (step.tests?.ran ?? 0),
+      skipped: sum.skipped + (step.tests?.skipped ?? 0),
+    }),
+    { ran: 0, skipped: 0 },
+  );
+};
+
+/** One step's entries from every part, folded into one step result and its gaps. */
+function mergeStep(
+  name: string,
+  entries: readonly { readonly part: string; readonly step: PartStep }[],
+  floor: VerifyFloor | undefined,
+): StepResult {
+  if (entries.length === 0) {
+    return {
+      name,
+      ok: false,
+      durationMs: 0,
+      findings: [gap(`step "${name}" is in no part — no CI job ran it`, name)],
+    };
+  }
+  const sharded = entries.filter((entry) => entry.step.shard !== undefined);
+  const whole = entries.filter((entry) => entry.step.shard === undefined);
+  const gaps: Finding[] = [];
+  if (whole.length > 1 || (whole.length > 0 && sharded.length > 0)) {
+    gaps.push(
+      gap(
+        `step "${name}" is reported by ${String(entries.length)} parts (${entries
+          .map((entry) => entry.part)
+          .join(', ')}) — each step belongs to one job, or to one full set of shards`,
+        name,
+      ),
+    );
+  }
+  if (sharded.length > 0) {
+    const totals = new Set(sharded.map((entry) => entry.step.shard?.total));
+    const hashes = new Set(sharded.map((entry) => entry.step.shard?.corpusHash));
+    if (totals.size > 1) {
+      gaps.push(gap(`step "${name}" mixes splits of ${[...totals].join(' and ')} shards`, name));
+    }
+    if (hashes.size > 1) {
+      gaps.push(
+        gap(
+          `step "${name}"'s shards counted ${String(hashes.size)} different corpora — every job must check out the same commit`,
+          name,
+        ),
+      );
+    }
+    const total = Math.max(...sharded.map((entry) => entry.step.shard?.total ?? 0));
+    const seen = new Map<number, number>();
+    for (const entry of sharded) {
+      const index = entry.step.shard?.index ?? 0;
+      seen.set(index, (seen.get(index) ?? 0) + 1);
+    }
+    const missing = Array.from({ length: total }, (_, i) => i + 1).filter((i) => !seen.has(i));
+    const doubled = [...seen].filter(([, count]) => count > 1).map(([index]) => index);
+    if (missing.length > 0) {
+      gaps.push(
+        gap(
+          `step "${name}" is missing shard(s) ${missing.map((i) => `${String(i)}/${String(total)}`).join(', ')}`,
+          name,
+        ),
+      );
+    }
+    if (doubled.length > 0) {
+      gaps.push(gap(`step "${name}" has shard(s) ${doubled.join(', ')} more than once`, name));
+    }
+  }
+  const steps = entries.map((entry) => entry.step);
+  const tests = sumCounts(steps);
+  // The floor each shard deferred, on the summed counts: a split step whose shards together ran
+  // nothing is the same vanished suite a whole run that ran nothing is.
+  const nothingRan = sharded.length > 0 && tests !== undefined && tests.ran === 0;
+  const required = floorRequires(floor, name);
+  const floorGap = nothingRan && required ? [skippedSuiteFinding(name, tests.skipped)] : [];
+  const findings = [...steps.flatMap((step) => step.findings), ...gaps, ...floorGap];
+  const output = steps
+    .filter((step) => !step.ok && step.output !== undefined && step.output.length > 0)
+    .map((step) => step.output as string)
+    .join('\n');
+  const skipped =
+    sharded.length > 0 ? nothingRan && !required : steps.every((step) => step.skipped);
+  return {
+    name,
+    ok: steps.every((step) => step.ok) && gaps.length === 0 && floorGap.length === 0,
+    // The slowest job: the parts ran side by side, and wall time is what a CI run waits on.
+    durationMs: Math.max(...steps.map((step) => step.durationMs)),
+    ...(skipped ? { skipped: true } : {}),
+    findings,
+    ...(output.length === 0 ? {} : { output }),
+    ...(tests === undefined ? {} : { tests }),
+  };
+}
+
+/** The gate verdict n parts add up to. */
+export function mergeParts(
+  parts: readonly VerifyPart[],
+  floor: VerifyFloor | undefined,
+  declared: readonly string[] = VERIFY_STEP_NAMES,
+): CommandResult {
+  const unknown = parts.flatMap((part) =>
+    part.steps
+      .filter((step) => !declared.includes(step.name))
+      .map((step) => gap(`${part.file} reports "${step.name}", which x verify does not run`)),
+  );
+  const steps = declared.map((name) =>
+    mergeStep(
+      name,
+      parts.flatMap((part) =>
+        part.steps.filter((step) => step.name === name).map((step) => ({ part: part.file, step })),
+      ),
+      floor,
+    ),
+  );
+  const failed = steps.filter((step) => !step.ok).map((step) => step.name);
+  const skipped = steps.filter((step) => step.skipped === true).map((step) => step.name);
+  const durationMs = Math.max(0, ...parts.map((part) => part.durationMs));
+  const ok = failed.length === 0 && unknown.length === 0;
+  const summary = verifySummary({ results: steps, failed, skipped, totalMs: durationMs });
+  return {
+    ok,
+    command: 'verify',
+    summary: msg('cli.verify.merged', { parts: parts.length, summary }),
+    steps,
+    ...(unknown.length === 0 ? {} : { findings: unknown }),
+    data: {
+      failed,
+      skipped,
+      durationMs,
+      merged: { parts: parts.map((part) => part.file) },
+    },
+    exitCode: ok ? 0 : 1,
+  };
+}