@ultimat3/cli 1.1.0 → 2.0.0

package/src/ts-scan.ts

@@ -118,11 +118,25 @@ export const stripComments = (text: string): string => blankRegions(text, false)
 /** Comments and string contents gone, delimiters kept — what a scan for code structure reads. */
 export const maskLiterals = (text: string): string => blankRegions(text, true);
 
-const lineOf = (text: string, index: number): number => {
-  let line = 1;
-  for (let i = 0; i < index; i += 1) if (text[i] === '\n') line += 1;
-  return line;
-};
+/**
+ * Line numbers for one text, in one pass. Counting newlines per lookup is O(index), which a scan
+ * asking for a line per literal pays once per literal — measured at ~15s over the framework's own
+ * package tree, against ~1s for the same walk with this. One offset table, then a binary search.
+ */
+function lineIndex(text: string): (index: number) => number {
+  const newlines: number[] = [];
+  for (let i = 0; i < text.length; i += 1) if (text[i] === '\n') newlines.push(i);
+  return (index) => {
+    let low = 0;
+    let high = newlines.length;
+    while (low < high) {
+      const mid = (low + high) >> 1;
+      if ((newlines[mid] as number) < index) low = mid + 1;
+      else high = mid;
+    }
+    return low + 1;
+  };
+}
 
 /**
  * Every string literal in the value expression starting at `from`, at the expression's own bracket
@@ -130,7 +144,12 @@ const lineOf = (text: string, index: number): number => {
  * instead of silently skipped; the depth rule is what keeps `command.join(' ')`'s separator and
  * `table['key']`'s key out — an argument is not a fix.
  */
-function valueLiterals(masked: string, source: string, from: number): readonly FixSite[] {
+function valueLiterals(
+  masked: string,
+  source: string,
+  from: number,
+  lineAt: (index: number) => number,
+): readonly FixSite[] {
   const found: { value: string; index: number }[] = [];
   let depth = 0;
   for (let i = from; i < masked.length; i += 1) {
@@ -147,7 +166,7 @@ function valueLiterals(masked: string, source: string, from: number): readonly F
   }
   return found.map((literal) => ({
     at: '',
-    line: lineOf(masked, literal.index),
+    line: lineAt(literal.index),
     fix: literal.value,
   }));
 }
@@ -155,25 +174,180 @@ function valueLiterals(masked: string, source: string, from: number): readonly F
 /** The lookbehind rejects member access: `cond ? e.fix : ''` is a ternary, not a declaration. */
 const FIX_KEY = /(?<![.\w$])fix\s*:\s*/g;
 
+/** Text between the bracket at `open` and its match, or `undefined` when it never closes. */
+function bracketSpan(masked: string, open: number): string | undefined {
+  let depth = 0;
+  for (let i = open; i < masked.length; i += 1) {
+    const ch = masked[i] as string;
+    // Only `()[]{}`. An angle bracket is a generic in a parameter list and the tail of `=>` in the
+    // very same list, so counting it makes `(fn: () => void)` end the span in the wrong place.
+    if (OPENERS.has(ch)) depth += 1;
+    else if (CLOSERS.has(ch)) {
+      depth -= 1;
+      if (depth === 0) return masked.slice(open + 1, i);
+    }
+  }
+  return undefined;
+}
+
+/** Split at depth-0 commas. Safe on masked text, where a comma inside a literal is already gone. */
+function topLevelParts(text: string): readonly string[] {
+  const parts: string[] = [];
+  let depth = 0;
+  let start = 0;
+  for (let i = 0; i < text.length; i += 1) {
+    const ch = text[i] as string;
+    if (OPENERS.has(ch)) depth += 1;
+    else if (CLOSERS.has(ch)) depth -= 1;
+    else if (ch === ',' && depth === 0) {
+      parts.push(text.slice(start, i));
+      start = i + 1;
+    }
+  }
+  parts.push(text.slice(start));
+  return parts;
+}
+
+/** A local function that builds an error and takes its fix positionally, and where in its list. */
+interface FixHelper {
+  readonly name: string;
+  readonly index: number;
+}
+
+const HELPER_DECL =
+  /(?<![.\w$])(?:function\s+([A-Za-z_$][\w$]*)\s*\(|(?:const|let)\s+([A-Za-z_$][\w$]*)\s*(?::[^=;]*)?=\s*(?:async\s+)?\()/g;
+
+const FIX_PARAM = /^\s*fix\s*:\s*string\s*$/;
+
+/**
+ * What separates a helper that BUILDS a fix from one that CONSUMES one. `citedCommandProblem(fix:
+ * string, …)` in `fix-command.ts` takes a fix in order to judge it, and reading its call sites as
+ * declarations would report findings about strings that are already findings. A builder names a
+ * `code` or constructs an `…Error`; a consumer does neither.
+ */
+const BUILDS_ERROR = /(?<![.\w$])code\s*[:=]|new\s+[A-Za-z_$][\w$]*Error\s*\(/;
+
+/**
+ * The body of the declaration whose parameter list ends at `after`, and never a `{` belonging to
+ * something below it. An unbounded `indexOf('{')` reads the next object literal in the FILE when
+ * the body is a concise expression, so `const label = (fix: string) => fix.trim();` followed
+ * anywhere by a `{ code: … }` was read as an error builder and every `label(…)` call handed the
+ * gate a string to judge as a fix — a false gate failure over innocent source.
+ *
+ * The scan therefore ends at the `;` that ends the declaration, or at a bracket closing a scope
+ * this declaration is inside. Both directions of that bound answer `''`, which classifies the
+ * helper as a non-builder: a missed fix line costs one unchecked citation, a wrongly claimed one
+ * costs a build. A `{` inside a return-type annotation (`(): { ok: boolean } => …`) is read as the
+ * body and answers `''` for the same reason.
+ */
+function bodyOf(masked: string, after: number): string {
+  for (let i = after; i < masked.length; i += 1) {
+    const ch = masked[i] as string;
+    if (ch === '{') return bracketSpan(masked, i) ?? '';
+    if (ch === ';' || CLOSERS.has(ch)) break;
+  }
+  return '';
+}
+
+function fixHelpers(masked: string): readonly FixHelper[] {
+  const helpers: FixHelper[] = [];
+  for (const declaration of masked.matchAll(HELPER_DECL)) {
+    const name = declaration[1] ?? declaration[2];
+    const open = declaration.index + declaration[0].length - 1;
+    if (name === undefined || masked[open] !== '(') continue;
+    const params = bracketSpan(masked, open);
+    // A rest parameter makes the position of everything after it unknowable, and a destructured
+    // one has no position at all — its `fix:` key at the CALL site is already read by `FIX_KEY`.
+    if (params === undefined || params.includes('...')) continue;
+    const parts = topLevelParts(params);
+    if (parts.some((part) => /^\s*[[{]/.test(part))) continue;
+    const index = parts.findIndex((part) => FIX_PARAM.test(part));
+    if (index === -1) continue;
+    if (!BUILDS_ERROR.test(bodyOf(masked, open + params.length + 2))) continue;
+    helpers.push({ name, index });
+  }
+  return helpers;
+}
+
+/**
+ * The argument in that position at every call to that helper IN THIS FILE.
+ *
+ * Same file, deliberately: resolving `dbNotImplemented` imported from `@ultimat3/db` would mean a
+ * cross-file symbol table, and a scanner that guessed at which import a name came from would read
+ * an unrelated function's argument as a fix. The gap that leaves is named in `CLAUDE.md`.
+ */
+function helperFixSites(
+  masked: string,
+  source: string,
+  at: string,
+  helper: FixHelper,
+  lineAt: (index: number) => number,
+): readonly FixSite[] {
+  const sites: FixSite[] = [];
+  // The lookbehind is `FIX_KEY`'s: `reporter.rejected(…)` is some other object's method.
+  const call = new RegExp(`(?<![.\\w$])${helper.name}\\s*\\(`, 'g');
+  for (const match of masked.matchAll(call)) {
+    const open = match.index + match[0].length - 1;
+    const args = bracketSpan(masked, open);
+    if (args === undefined) continue;
+    const parts = topLevelParts(args);
+    const argument = parts[helper.index];
+    if (argument === undefined) continue;
+    // Stricter than the `fix:` path, and deliberately: the whole argument must BE one literal.
+    // `valueLiterals` alone reads `prefix + 'x doctor'` as one literal, because the identifier
+    // half contributes none — and publishing half a fix as the whole one is the failure
+    // `soleLiteral` already names. A key at least declares that what follows is the value.
+    const quote = argument.trim()[0];
+    if (quote === undefined || !QUOTES.has(quote)) continue;
+    const literal = argument.indexOf(quote);
+    if (argument.slice(endOfLiteral(argument, literal)).trim() !== '') continue;
+    const from = parts.slice(0, helper.index).reduce((n, part) => n + part.length + 1, open + 1);
+    const literals = valueLiterals(masked, source, from, lineAt);
+    if (literals.length === 1) sites.push({ ...(literals[0] as FixSite), at });
+  }
+  return sites;
+}
+
 /**
  * Every string a `fix:` can evaluate to. Searched over the masked source, so a `fix:` written
  * inside a doc comment or interpolated into a message is not mistaken for a declaration. A `fix`
  * computed at runtime — a bare identifier, a parameter, a table lookup with no literal fallback —
  * has nothing to read and is beyond a static scan; the gate says so rather than guessing.
+ *
+ * Two shapes, because a fix does not always arrive under a key. `@ultimat3/mcp`'s `readonly-sql.ts`
+ * hands every one of its fixes positionally to a local `rejected(cause, fix)` helper, so the key
+ * rule alone returned `[]` for the whole file — 20 non-test files in that package and the scanner
+ * saw fixes in three — and two stale `x db branch <name>` lines shipped through the hole.
  */
 export function scanFixes(source: string, at: string): readonly FixSite[] {
   const masked = maskLiterals(source);
+  const lineAt = lineIndex(masked);
   const sites: FixSite[] = [];
   for (const key of masked.matchAll(FIX_KEY)) {
     const start = key.index + key[0].length;
-    for (const literal of valueLiterals(masked, source, start)) sites.push({ ...literal, at });
+    for (const literal of valueLiterals(masked, source, start, lineAt)) {
+      sites.push({ ...literal, at });
+    }
+  }
+  for (const helper of fixHelpers(masked)) {
+    sites.push(...helperFixSites(masked, source, at, helper, lineAt));
   }
   return sites;
 }
 
-/** `packages/<pkg>/src/errors.ts` and core's `error-codes.ts`: one file per package, by rule. */
-export const isCodeRegistry = (path: string): boolean =>
-  /(?:^|\/)(?:errors|error-codes)\.ts$/.test(path);
+const CODE_TABLE = /\bexport const [A-Z][A-Z0-9_]*_ERROR_(?:CODES|TITLES)\b/;
+
+/**
+ * Whether a file IS a package's code registry — asked of its contents, not of its name.
+ *
+ * A filename test (`errors.ts` or `error-codes.ts`) held only while one file per package did both
+ * jobs. The moment `@ultimat3/cli`'s split under the 500-line ceiling — table into `error-codes.ts`,
+ * classes into `errors.ts` — the classes file was still *named* like a registry, so every code it
+ * throws outranked the package that actually owns it and `X_NOT_IMPLEMENTED` moved from `core` to
+ * `cli` in the manifest. The table is the thing; `export const <PKG>_ERROR_{CODES,TITLES}` is the
+ * one shape every package declares it in, and `x verify`'s `errors` step is what keeps that true.
+ */
+export const isCodeRegistry = (source: string): boolean => CODE_TABLE.test(source);
 
 const CODE_AT_KEY = /\bcode\s*[:=]\s*(['"`])(X_[A-Z0-9_]+)\1/g;
 const CODE_LITERAL = /(['"`])(X_[A-Z0-9_]+)\1/g;
@@ -187,18 +361,102 @@ const CODE_KEY = /^[\t ]*(X_[A-Z0-9_]+)\s*:/gm;
  */
 export function scanCodes(source: string, at: string): readonly CodeSite[] {
   const text = stripComments(source);
+  const lineAt = lineIndex(text);
   const sites = new Map<string, CodeSite>();
   const add = (code: string, index: number): void => {
-    if (!sites.has(code)) sites.set(code, { at, line: lineOf(text, index), code });
+    if (!sites.has(code)) sites.set(code, { at, line: lineAt(index), code });
   };
   for (const match of text.matchAll(CODE_AT_KEY)) add(match[2] as string, match.index);
-  if (isCodeRegistry(at)) {
+  if (isCodeRegistry(text)) {
     for (const match of text.matchAll(CODE_LITERAL)) add(match[2] as string, match.index);
     for (const match of text.matchAll(CODE_KEY)) add(match[1] as string, match.index);
   }
   return [...sites.values()];
 }
 
+export interface CodeFixSite extends CodeSite {
+  /**
+   * The fix literal exactly as written, `${…}` included. Absent when the throw site builds its
+   * fix out of something this cannot read — a helper call, a parameter, a ternary with two
+   * branches — because a fix the scan has to guess at is one it must not report.
+   */
+  readonly fix?: string;
+}
+
+/** `code:` / `code =`, or `fix:`. `fix =` is deliberately not a declaration — `scanFixes` agrees. */
+const CODE_OR_FIX_KEY = /(?<![.\w$])(?:(code)\s*[:=]|(fix)\s*:)\s*/g;
+
+/**
+ * The single literal a key's value evaluates to, or `undefined` when it evaluates to none or to
+ * more than one. Two is as unreadable as zero here: `cond ? 'a' : 'b'` and `'a' + 'b'` need a
+ * parser to tell apart, and picking a branch would publish half a fix as the whole one.
+ */
+function soleLiteral(
+  masked: string,
+  source: string,
+  from: number,
+  lineAt: (index: number) => number,
+): FixSite | undefined {
+  const found = valueLiterals(masked, source, from, lineAt);
+  return found.length === 1 ? found[0] : undefined;
+}
+
+/**
+ * Every `X_*` code paired with the `fix:` written beside it — in the SAME object literal, which is
+ * the whole rule. `new UltimateError({ code, cause, fix })` is the one shape this framework raises
+ * an error in, so adjacency decides the pair without a parser and without asking which of a file's
+ * fixes belongs to which of its codes. `X_ERROR_FIX_INVALID` already proves every one of these is
+ * runnable, so a reader that projects them inherits that proof instead of restating it (axiom 2).
+ *
+ * A site is reported with no `fix` rather than dropped: "this code is raised here and the fix is
+ * computed" is a different, and more useful, answer than "this code does not exist".
+ */
+export function scanCodeFixSites(source: string, at: string): readonly CodeFixSite[] {
+  const masked = maskLiterals(source);
+  const lineAt = lineIndex(masked);
+  const keys = new Map<number, { readonly kind: 'code' | 'fix'; readonly from: number }>();
+  for (const key of masked.matchAll(CODE_OR_FIX_KEY)) {
+    keys.set(key.index, {
+      kind: key[1] === undefined ? 'fix' : 'code',
+      from: key.index + key[0].length,
+    });
+  }
+  const codes = new Map<number, CodeSite>();
+  const fixes = new Map<number, string>();
+  const stack: number[] = [];
+  for (let i = 0; i < masked.length; i += 1) {
+    const ch = masked[i] as string;
+    if (QUOTES.has(ch)) {
+      i = endOfLiteral(masked, i) - 1;
+      continue;
+    }
+    if (OPENERS.has(ch)) {
+      stack.push(i);
+      continue;
+    }
+    if (CLOSERS.has(ch)) {
+      stack.pop();
+      continue;
+    }
+    const key = keys.get(i);
+    // Scope `-1` is the file body: a top-level `const code = 'X_A'` and an unrelated `fix:` far
+    // below it are not one declaration, and pairing them would invent an error nobody throws.
+    const scope = stack.at(-1);
+    if (key === undefined || scope === undefined) continue;
+    const literal = soleLiteral(masked, source, key.from, lineAt);
+    if (literal === undefined) continue;
+    if (key.kind === 'fix') {
+      if (!fixes.has(scope)) fixes.set(scope, literal.fix);
+    } else if (/^X_[A-Z0-9_]+$/.test(literal.fix) && !codes.has(scope)) {
+      codes.set(scope, { at, line: literal.line, code: literal.fix });
+    }
+  }
+  return [...codes].map(([scope, site]) => {
+    const fix = fixes.get(scope);
+    return fix === undefined ? site : { ...site, fix };
+  });
+}
+
 const BORROWED_LIST = /BORROWED_ERROR_CODES[^=]*=[^[]*\[([^\]]*)\]/g;
 
 /**

package/src/tsconfig-references.ts

@@ -0,0 +1,78 @@
+// One rule: every published workspace is in the root build graph. `bun run typecheck` is `tsc -b`,
+// which compiles referenced projects and nothing else — so a package no reference names is a
+// package the gate's `typecheck` step reports green over without having read a line of it.
+
+// Bun ships no equivalent: `join` builds the host-separator path from the scan root to the config.
+// Nothing else here is `node:` — the read is `Bun.file`, and its rejection is also the answer for a
+// root that has no `tsconfig.json` at all, so an `existsSync` ahead of it was a second question
+// with one answer.
+import { join } from 'node:path';
+import { docsFor } from './error-codes';
+import type { Finding } from './output';
+
+const ROOT_TSCONFIG = 'tsconfig.json';
+
+/**
+ * `./packages/cli`, `packages/cli/` and `packages/cli` are one project; the JSON allows all three.
+ * Exported because "is this project already referenced?" is asked in three places — here,
+ * `scripts/new-package.ts` when it adds an entry, and `scripts/reference-app-gate.ts` when it
+ * checks an app — and a spelling one of them treats as a match and another does not is how the
+ * scaffolder appends a duplicate entry the check already considered present.
+ */
+export const normalizeReferencePath = (path: string): string =>
+  path.replace(/^\.\//, '').replace(/\/+$/, '');
+
+/**
+ * `undefined` means "this root does not use project references" — a different repo shape, not an
+ * empty graph. A scaffolded app is that shape (`extends` + `include`, no references at all), and
+ * telling its author to add an entry to a list that does not exist is a fix that makes the build
+ * worse. A tsconfig that will not parse is `typecheck`'s to report, with tsc's own message.
+ */
+async function referencedPaths(root: string): Promise<ReadonlySet<string> | undefined> {
+  const payload: unknown = await Bun.file(join(root, ROOT_TSCONFIG))
+    .json()
+    .catch(() => undefined);
+  const references =
+    typeof payload === 'object' && payload !== null
+      ? (payload as { references?: unknown }).references
+      : undefined;
+  if (!Array.isArray(references)) return undefined;
+  return new Set(
+    references.flatMap((entry: unknown) => {
+      const value =
+        typeof entry === 'object' && entry !== null
+          ? (entry as { path?: unknown }).path
+          : undefined;
+      return typeof value === 'string' ? [normalizeReferencePath(value)] : [];
+    }),
+  );
+}
+
+/**
+ * The edit, spelled out: the array to add to, the entry to add, and the command that proves it
+ * took. `tsc -b` is the same one the gate's `typecheck` step runs, so a reader who runs the fix
+ * runs the check.
+ */
+export const unreferencedFinding = (dir: string): Finding => ({
+  code: 'X_PACKAGE_UNREFERENCED',
+  cause: `packages/${dir} is a published workspace and ${ROOT_TSCONFIG} has no reference to it, so tsc -b never builds it`,
+  fix: `add { "path": "./packages/${dir}" } to "references" in ${ROOT_TSCONFIG}, then run bunx tsc -b --pretty false`,
+  docs: docsFor('X_PACKAGE_UNREFERENCED'),
+  at: ROOT_TSCONFIG,
+});
+
+/**
+ * Published workspaces only. A private package is not a shipped contract and a generated app's
+ * `packages/*` are all private, so this asks nothing of an app that never publishes — the same
+ * line `checkPublishShape` already draws.
+ */
+export async function checkRootReferences(
+  root: string,
+  dirs: readonly string[],
+): Promise<readonly Finding[]> {
+  const referenced = await referencedPaths(root);
+  if (referenced === undefined) return [];
+  return dirs
+    .filter((dir) => !referenced.has(`packages/${dir}`))
+    .map((dir) => unreferencedFinding(dir));
+}

package/src/verify-floor.ts

@@ -0,0 +1,133 @@
+// The suite ratchet: the steps this repo has already proved it can run, committed as a floor.
+// `applies` answers "is there anything to check here?", and a deleted suite answers "no" — which
+// reads as a skip and keeps the gate green. The floor turns that skip back into a failure. Read
+// here and written by nothing: a gate that edits its own floor ratchets both ways, which is none.
+
+// Bun ships no equivalent for either: `existsSync` answers whether this root committed a floor at
+// all, and `join` builds the host-separator path to it.
+import { existsSync } from 'node:fs';
+import { join } from 'node:path';
+import { docsFor } from './error-codes';
+import type { Finding } from './output';
+import { VERIFY_STEP_NAMES } from './verify-step';
+
+/** Hand-written and committed, beside the generated `x.manifest.json` the same gate reads. */
+export const VERIFY_FLOOR_FILE = 'x.verify.json';
+
+export interface VerifyFloor {
+  /** Declared step names this run may not report as skipped. */
+  readonly steps: readonly string[];
+  /** Why part of the file is not a floor. The `manifest` step reports these; nothing swallows them. */
+  readonly problems: readonly string[];
+}
+
+const asRecord = (value: unknown): Record<string, unknown> | undefined =>
+  typeof value === 'object' && value !== null && !Array.isArray(value)
+    ? (value as Record<string, unknown>)
+    : undefined;
+
+/**
+ * The file's names, split into the ones the ratchet can enforce and the reasons the rest cannot be.
+ * A name no step declares is dropped rather than enforced — it can never apply, so enforcing it
+ * would pin the gate red forever — and it is returned as a problem, because a floor with a typo in
+ * it silently covers nothing, which is the same false green the floor exists to close.
+ *
+ * `declared` is a parameter rather than the imported constant at the call site, so a test can pin a
+ * closed world instead of asserting against every step this build happens to ship.
+ */
+export function parseVerifyFloor(
+  text: string,
+  declared: readonly string[] = VERIFY_STEP_NAMES,
+): VerifyFloor {
+  let payload: unknown;
+  try {
+    payload = JSON.parse(text);
+  } catch (error) {
+    const reason = error instanceof Error ? error.message : String(error);
+    return { steps: [], problems: [`it does not parse as JSON (${reason})`] };
+  }
+  const steps = asRecord(payload)?.['steps'];
+  if (!Array.isArray(steps)) {
+    return { steps: [], problems: ['it has no "steps" array of step names'] };
+  }
+  const named = steps.filter((step): step is string => typeof step === 'string');
+  const unknown = named.filter((step) => !declared.includes(step));
+  return {
+    steps: named.filter((step) => declared.includes(step)),
+    problems: [
+      ...(named.length === steps.length ? [] : ['"steps" holds an entry that is not a string']),
+      ...(unknown.length === 0
+        ? []
+        : [`"steps" names ${unknown.join(', ')}, which x verify does not run`]),
+    ],
+  };
+}
+
+/** No file is no floor: a repo that never committed one is not ratcheted, and reports nothing. */
+export async function readVerifyFloor(root: string): Promise<VerifyFloor | undefined> {
+  const path = join(root, VERIFY_FLOOR_FILE);
+  if (!existsSync(path)) return undefined;
+  const text = await Bun.file(path)
+    .text()
+    .catch(() => undefined);
+  if (text === undefined) return { steps: [], problems: ['it could not be read as a file'] };
+  return parseVerifyFloor(text);
+}
+
+/** Whether the floor already claims this step has something to check in this repo. */
+export const floorRequires = (floor: VerifyFloor | undefined, step: string): boolean =>
+  floor?.steps.includes(step) === true;
+
+/**
+ * A step the floor requires that found nothing to run. Named for what happened rather than for the
+ * file — the suite is what vanished — and the fix carries both edits that resolve it, because
+ * either can be right: the suite comes back, or the floor drops a line in a commit that says why.
+ *
+ * Command first, alternatives behind a `#`, so the line runs verbatim and the shell drops the rest
+ * (the shape `mcp-errors.ts` gives this same code). Neither edit is scripted here on purpose: a
+ * command that rewrites the floor is the gate editing its own ratchet, which is the false green the
+ * floor exists to close — so the run that proves the step is back is what this offers to repeat.
+ */
+export const vanishedSuiteFinding = (step: string): Finding => ({
+  code: 'X_VERIFY_SUITE_VANISHED',
+  cause: `${VERIFY_FLOOR_FILE} requires the ${step} step and this run found nothing for it to check`,
+  fix: `x verify --json   # restore the ${step} suite, or drop "${step}" from ${VERIFY_FLOOR_FILE} in the commit that says why`,
+  docs: docsFor('X_VERIFY_SUITE_VANISHED'),
+  at: VERIFY_FLOOR_FILE,
+});
+
+/**
+ * The second way a suite vanishes, and the reason this is the same code rather than a new one: a
+ * step whose files are all still there and whose every test skipped itself found exactly as much
+ * for the floor to stand on as a step with no files — nothing. `applies` cannot see it, because
+ * `describe.skipIf` is decided inside the run, so this is read back out of what bun reported.
+ *
+ * The fix names the suite's own command first: what an author has to change is the environment the
+ * tests skip without (`TEST_DATABASE_URL` for `live`), and running the type alone is how they find
+ * out which one. Dropping the step from the floor stays the alternative, behind the `#`, because
+ * either can be the right answer and neither may be performed by the gate on its own ratchet.
+ */
+export const skippedSuiteFinding = (step: string, skipped: number): Finding => ({
+  code: 'X_VERIFY_SUITE_VANISHED',
+  cause: `${VERIFY_FLOOR_FILE} requires the ${step} step and all ${skipped} test(s) it found skipped themselves, so nothing ran`,
+  fix: `x test ${step} --json   # then set what the suite skips without, or drop "${step}" from ${VERIFY_FLOOR_FILE} in the commit that says why`,
+  docs: docsFor('X_VERIFY_SUITE_VANISHED'),
+  at: VERIFY_FLOOR_FILE,
+});
+
+/**
+ * The floor file's own integrity, as findings. `X_CONFIG_INVALID` rather than a second code of this
+ * package's own: a committed file the framework reads and cannot use is exactly what core already
+ * named, and a floor that enforces nothing is not a vanished suite.
+ *
+ * The command runs first because it is what the edit needs: the step table it prints is the closed
+ * set of names the floor may hold, so an author fixing a typo reads the answer instead of guessing.
+ */
+export const floorProblemFindings = (floor: VerifyFloor | undefined): readonly Finding[] =>
+  (floor?.problems ?? []).map((problem) => ({
+    code: 'X_CONFIG_INVALID',
+    cause: `${VERIFY_FLOOR_FILE} is not a suite floor: ${problem}`,
+    fix: `x verify --json   # then write ${VERIFY_FLOOR_FILE} as {"steps":["unit","contract"]}, naming only steps it ran`,
+    docs: docsFor('X_CONFIG_INVALID'),
+    at: VERIFY_FLOOR_FILE,
+  }));

package/src/verify-step.ts

@@ -5,6 +5,7 @@
 import type { ExecResult, Runner } from './exec';
 import { execOutput } from './exec';
 import type { Finding } from './output';
+import type { TestCounts } from './test-counts';
 
 /**
  * Every step of the gate, in cost order — cheapest and most informative first, and never a check
@@ -44,12 +45,30 @@ export interface VerifyContext {
   readonly root: string;
   readonly runner: Runner;
   readonly hostChecks?: Partial<Record<VerifyStepName, HostCheck>>;
+  /**
+   * How wide the parallel test steps go. Absent means `defaultWorkers()` — a knob, never a
+   * narrowing: no value of it changes which steps run or what "green" means, which is why this is
+   * the only flag `x verify` accepts beyond the global ones.
+   */
+  readonly workers?: number;
 }
 
 export interface StepOutcome {
   readonly ok: boolean;
   readonly findings: readonly Finding[];
   readonly output?: string;
+  /**
+   * Processes this step actually used. `1` is a step that ran serially, and a reader has to be
+   * able to tell "serial because nothing could isolate it" from "parallel and fast" without
+   * reading the step list's source.
+   */
+  readonly workers?: number;
+  /**
+   * What the suite executed, for the steps that run one. Absent means this step spawned no test
+   * process at all — a check step, or the `eval` step answering with declarations alone — and is
+   * NOT the same as a suite that ran nothing, which is a number the ratchet acts on.
+   */
+  readonly tests?: TestCounts;
 }
 
 export interface VerifyStep {

package/src/verify-test-run.ts

@@ -0,0 +1,72 @@
+// Running one test type across N worker processes and reporting it as one gate step. Split from
+// verify-tests.ts because that file owns which files belong to a type and this one owns what
+// happens to them once selected — a wrong file list is never a race, and a race is never a
+// selection bug.
+
+import { docsFor } from './error-codes';
+import type { Runner } from './exec';
+import { execOutput } from './exec';
+import type { Finding } from './output';
+import { countsOf } from './test-counts';
+import type { TestFile } from './test-select';
+import { planShards, reproduceFor, shardArgs } from './test-shards';
+import type { StepOutcome } from './verify-step';
+// Type-only, so nothing here evaluates verify-tests.ts and the two files cannot form a cycle.
+import type { TestType } from './verify-tests';
+
+export interface ParallelRunOptions {
+  readonly root: string;
+  readonly runner: Runner;
+  readonly files: readonly TestFile[];
+  /** The ask. `planShards` clamps it to the file count, and the report carries what it became. */
+  readonly workers: number;
+  /** Carried into the `fix:` so a failed shard reproduces as `x test <type> --workers N …`. */
+  readonly type: TestType;
+}
+
+/**
+ * The whole point is wall-clock, so every shard starts at once. Two things make that safe and
+ * neither is optional: `shardArgs` gives each FILE its own module registry (`--isolate`), and
+ * `ULTIMATE_TEST_WORKER` gives each PROCESS its own database — `@ultimat3/testing`'s
+ * `acquireWorkerDatabase` reads exactly that variable first and clones the migrated template into
+ * `…_w<index>`. Rails' numbered test databases, with Postgres doing the copy.
+ */
+export async function runParallel(options: ParallelRunOptions): Promise<StepOutcome> {
+  const shards = planShards(options.files, options.workers);
+  const runs = await Promise.all(
+    shards.map(async (shard) => ({
+      shard,
+      result: await options.runner(shardArgs(shard), {
+        cwd: options.root,
+        env: { ULTIMATE_TEST_WORKER: String(shard.index) },
+      }),
+    })),
+  );
+  const findings: Finding[] = [];
+  for (const { shard, result } of runs) {
+    if (result.ok) continue;
+    findings.push({
+      code: 'X_TEST_SHARD_FAILED',
+      cause: `${options.type} shard ${shard.index} of ${shards.length} exited ${result.code} (${shard.files.length} file(s))`,
+      // The reproduction has to name every input to the split, or it reruns a different file set:
+      // `reproduceFor` is the one place that rule lives, shared with `x test`.
+      fix: reproduceFor(shard, { workers: shards.length, type: options.type }),
+      docs: docsFor('X_TEST_SHARD_FAILED'),
+    });
+  }
+  // Only the failing shards' output: a green 8-way split would otherwise print eight summaries,
+  // and the reader of a red gate needs the assertion diff, not the seven runs that passed.
+  const output = runs
+    .filter((run) => !run.result.ok)
+    .map((run) => `— shard ${run.shard.index}\n${execOutput(run.result)}`)
+    .join('\n');
+  return {
+    ok: findings.length === 0,
+    findings,
+    workers: shards.length,
+    // Every shard's summary, including the green ones whose output is dropped above: the counts
+    // are how the ratchet tells a suite that passed from a suite that skipped itself to nothing.
+    tests: countsOf(runs.map((run) => run.result)),
+    ...(output === '' ? {} : { output }),
+  };
+}