@ultimat3/cli 22.15.0 → 24.0.0

package/src/transport-calls.ts

@@ -0,0 +1,105 @@
+// The four ways browser code opens its own connection, found in ONE file's text: a `fetch(` CALL,
+// `new WebSocket(`, `new XMLHttpRequest(`, `new EventSource(`. Pure, so every false positive the
+// rule has to leave alone is a fixture string. Which file may hold which shape is the caller's.
+
+import { maskLiterals } from '@ultimat3/core';
+import { lineIndex } from './ts-scan';
+
+export type TransportShape = 'fetch' | 'websocket' | 'xhr' | 'eventsource';
+
+export interface TransportCall {
+  readonly shape: TransportShape;
+  readonly line: number;
+  /** What the source spells — `fetch`, `globalThis.fetch`, `WebSocket` — so a finding quotes it. */
+  readonly spelled: string;
+}
+
+const CONSTRUCTED: ReadonlyMap<string, TransportShape> = new Map([
+  ['WebSocket', 'websocket'],
+  ['XMLHttpRequest', 'xhr'],
+  ['EventSource', 'eventsource'],
+]);
+
+/** The global object's three spellings. `server.fetch(` is a method, never the global. */
+const GLOBAL = String.raw`(?:(?:globalThis|window|self)\s*\.\s*)`;
+const NEW = new RegExp(
+  String.raw`\bnew\s+${GLOBAL}?(WebSocket|XMLHttpRequest|EventSource)\s*\(`,
+  'g',
+);
+const FETCH = new RegExp(String.raw`(?<![\w$.])(${GLOBAL}?)fetch\s*\(`, 'g');
+
+/**
+ * Whether the file binds `fetch` itself — a `const`/`let`/`var`/`function`, an import, a
+ * destructured declaration or a parameter — which makes a BARE `fetch(` its own function, not the
+ * page's. `packages/action/src/idempotency-postgres.ts` calls a local `fetch(key)`. Per file, not
+ * per scope: a floor, and the one direction it errs is silence on a file that shadows the global
+ * AND calls it bare. `globalThis.fetch(` is reported regardless.
+ */
+export function bindsFetch(code: string): boolean {
+  return (
+    /\b(?:const|let|var|function)\s+fetch\b/.test(code) ||
+    /\bimport\s+[^;]*\bfetch\b[^;]*\bfrom\b/.test(code) ||
+    /\b(?:const|let|var)\s*\{[^}]*\bfetch\b[^}]*\}\s*=/.test(code) ||
+    /\(\s*(?:[\w$]+\s*(?::[^,()]+)?,\s*)*fetch\s*[?:,)=][^()]*\)\s*(?::[^={;]+)?(?:=>|\{)/.test(
+      code,
+    )
+  );
+}
+
+/**
+ * The `)` closing the `(` at `open`, or `-1`. A bare depth count is exact HERE and only here: the
+ * text is `maskLiterals`' output, where every string, template, comment and regex body is already
+ * blank — so each parenthesis left is code.
+ */
+function closeOf(masked: string, open: number): number {
+  let depth = 0;
+  for (let index = open; index < masked.length; index += 1) {
+    if (masked[index] === '(') depth += 1;
+    else if (masked[index] === ')') {
+      depth -= 1;
+      if (depth === 0) return index;
+    }
+  }
+  return -1;
+}
+
+/** `fetch(req) {` and `fetch(req): Promise<Response> {` define a method; they call nothing. */
+function isDefinition(masked: string, open: number, start: number): boolean {
+  if (/\b(?:function|async|get|set)\s*$/.test(masked.slice(Math.max(0, start - 16), start))) {
+    return true;
+  }
+  const close = closeOf(masked, open);
+  if (close < 0) return false;
+  const after = masked.slice(close + 1).trimStart();
+  return after.startsWith('{') || (after.startsWith(':') && !after.startsWith('::'));
+}
+
+/** A file naming none of the four cannot call one — and masking it is the expensive half. */
+const NAMES_A_TRANSPORT = /fetch|WebSocket|XMLHttpRequest|EventSource/;
+
+export function transportCalls(source: string): readonly TransportCall[] {
+  if (!NAMES_A_TRANSPORT.test(source)) return [];
+  // Comments AND string contents blanked, offsets kept: `'fetch('` in a message is not a call, and
+  // neither is the one a template-literal scaffold emits for somebody else's file.
+  const masked = maskLiterals(source);
+  const lineAt = lineIndex(masked);
+  const calls: TransportCall[] = [];
+  for (const found of masked.matchAll(NEW)) {
+    const name = found[1] ?? '';
+    const shape = CONSTRUCTED.get(name);
+    if (shape !== undefined) calls.push({ shape, line: lineAt(found.index), spelled: name });
+  }
+  const local = bindsFetch(masked);
+  for (const found of masked.matchAll(FETCH)) {
+    const qualified = (found[1] ?? '').length > 0;
+    if (!qualified && local) continue;
+    const open = found.index + found[0].length - 1;
+    if (!qualified && isDefinition(masked, open, found.index)) continue;
+    calls.push({
+      shape: 'fetch',
+      line: lineAt(found.index),
+      spelled: qualified ? `${(found[1] ?? '').replace(/\s/g, '')}fetch` : 'fetch',
+    });
+  }
+  return calls.sort((a, b) => a.line - b.line);
+}

package/src/trusted-hops-error.ts

@@ -0,0 +1,17 @@
+// The refusal of a malformed `TRUSTED_PROXY_HOPS` — its own code, never `X_PORT_INVALID`: a proxy
+// count is not a port, and an operator told "is not a TCP port number" looked for the wrong setting.
+
+import { UltimateError } from '@ultimat3/core';
+import { MAX_PROXY_HOPS } from '@ultimat3/http';
+import { quoteArg } from './shell-quote';
+
+export class TrustedProxyHopsInvalidError extends UltimateError {
+  constructor(input: { readonly value: string }) {
+    super({
+      code: 'X_TRUSTED_PROXY_HOPS_INVALID',
+      cause: `TRUSTED_PROXY_HOPS=${quoteArg(input.value)} is not a whole number of proxies from 1 to ${MAX_PROXY_HOPS} — the count that append to x-forwarded-for in front of this process; unset means none`,
+      fix: 'TRUSTED_PROXY_HOPS=1 ROLE=web bun apps/web/server.ts',
+      meta: { value: input.value, max: MAX_PROXY_HOPS },
+    });
+  }
+}

package/src/unscanned-admin.ts

@@ -0,0 +1,54 @@
+// A `defineAdmin()` the app scan never imports. The admin's one home is `apps/admin/app/admin/`
+// (`ADMIN_FILE`, what `x new` and `x g admin:page` write); `apps/<app>/src/` is outside every
+// glob `app-load.ts` imports, so a declaration there never runs and `/admin` is never mounted —
+// silently, which is how the reference app shipped an admin nobody could open.
+
+import { renderFixShellArg, stripComments } from '@ultimat3/core';
+import { describeRoutes } from '@ultimat3/render';
+import { ADMIN_FILE } from './admin-registration';
+import type { Finding } from './output';
+import { hasPathSegment } from './path-segments';
+import { isTest } from './source-files';
+
+/** The one place an admin used to be written that the scan cannot see. */
+const UNSCANNED = 'apps/*/src/**/*.{ts,tsx}';
+
+const DECLARES = /\bdefineAdmin\(/;
+
+/** Any admin this process mounted — then every declaration was reached, wherever it sits. */
+export const adminMounted = (): boolean =>
+  describeRoutes().some((route) => route.mount?.by === 'defineAdmin');
+
+/** Where the file belongs: its own name under the admin's home, `index.ts` as the declaration. */
+const homeOf = (file: string): string => {
+  const name = file.slice(file.lastIndexOf('/') + 1);
+  const home = ADMIN_FILE.slice(0, ADMIN_FILE.lastIndexOf('/'));
+  return /^index\.tsx?$/.test(name) ? ADMIN_FILE : `${home}/${name}`;
+};
+
+const unscannedFinding = (file: string): Finding => ({
+  code: 'X_ADMIN_UNSCANNED',
+  cause: `${file} calls defineAdmin(), and the app scan imports apps/*/{site,app,api,shared}/** only — no boot evaluates it, so the admin is never mounted and /admin answers 404`,
+  // A file name is the app's: screened, so a name carrying shell syntax reads as a placeholder.
+  fix: `git mv ${renderFixShellArg(file, '<the file above>')} ${renderFixShellArg(homeOf(file), '<apps/admin/app/admin/its-name.ts>')}   # then repoint its relative imports and x verify --only manifest --json`,
+  at: file,
+});
+
+/**
+ * One finding per unscanned file that declares an admin. Read only when nothing mounted one: an app
+ * whose admin is mounted pays for no glob, and comments are masked so prose naming the call is not
+ * a declaration.
+ */
+export async function unscannedAdminFindings(
+  root: string,
+  mounted: () => boolean = adminMounted,
+): Promise<readonly Finding[]> {
+  if (mounted()) return [];
+  const files: string[] = [];
+  for await (const file of new Bun.Glob(UNSCANNED).scan({ cwd: root })) {
+    const path = file.replaceAll('\\', '/');
+    if (hasPathSegment(path, 'node_modules') || isTest(path)) continue;
+    if (DECLARES.test(stripComments(await Bun.file(`${root}/${path}`).text()))) files.push(path);
+  }
+  return files.sort().map(unscannedFinding);
+}

package/src/unthrown-codes.ts

@@ -0,0 +1,26 @@
+// The registered codes this repo no longer throws, as a list `error-unthrown.ts` reads — its own
+// file, so the literals naming the waived codes are not mistaken for a throw site.
+
+/** Where the list lives, so a finding can name the file to edit. */
+export const UNTHROWN_CODES_FILE = 'packages/cli/src/unthrown-codes.ts';
+
+/**
+ * The codes this repo registers and no longer throws — each a decision, and each row on the
+ * reference page says so in words. A LIST, never a prose match: the waiver was any row containing
+ * "not thrown" or "thrown by nothing", so a sentence that happened to use either phrase silenced the
+ * rule for its code. A listing whose code is thrown again, or is not registered, is
+ * `X_ERROR_CODE_UNTHROWN_STALE`.
+ */
+export const UNTHROWN_CODES: ReadonlySet<string> = new Set([
+  // `x db studio` is planned and unreleased; it exits X_NOT_IMPLEMENTED.
+  'X_DB_STUDIO_FAILED',
+  // 21.0.0: there is no LiveClient to register (X_REALTIME_UNINSTALLED replaced it).
+  'X_LIVE_CLIENT_MISSING',
+  // 21.0.0: liveHookFor was deleted; useQuery reads any query.
+  'X_QUERY_NOT_SUBSCRIBABLE',
+  // 21.0.0: the worker no longer POSTs a flush endpoint nothing mounted.
+  'X_PWA_SYNC_FLUSH_FAILED',
+  'X_PWA_SYNC_INCOMPLETE',
+  // 24.0.0: `x test --worker` was deleted; `x verify --only unit --shard i/n` is the one split.
+  'X_TEST_SHARD_FAILED',
+]);

package/src/verify-checks.ts

@@ -6,18 +6,13 @@ import { existsSync } from 'node:fs';
 import { join } from 'node:path';
 import { ERROR_DOCS_URL } from '@ultimat3/core';
 import type { Manifest } from '@ultimat3/manifest';
-import {
-  AGENTS_MD_FILENAME,
-  assertNoDrift,
-  MANIFEST_FILENAME,
-  verifyContract,
-} from '@ultimat3/manifest';
+import { AGENTS_MD_FILENAME, MANIFEST_FILENAME, verifyContract } from '@ultimat3/manifest';
 import type { MetaIssue } from '@ultimat3/seo';
 import { validateMeta } from '@ultimat3/seo';
 import { checkAgentsMd } from './app-agents-md';
+import { readAppSources } from './app-boundaries';
 import { envExampleFindings } from './app-env';
 import { appManifest, readAppManifest } from './app-manifest';
-import { OPENAPI_FILE, openApiStaleness } from './app-openapi';
 import { policyFindings } from './app-permissions';
 import { APP_CONFIG_FILE } from './app-root';
 import { asyncPageFindings } from './async-pages';
@@ -32,14 +27,21 @@ import { catalogFindings } from './i18n-registration';
 import { unregisteredJobFindings } from './job-registration';
 import { liveRouteFindings } from './live-routes';
 import { withLoadFindings, withoutLoadFindings } from './load-findings';
+import {
+  hasCommittedContract,
+  manifestMissingFindings,
+  manifestStaleness,
+} from './manifest-staleness';
 import { msg } from './messages';
 import type { Finding } from './output';
 import { findingFrom } from './output';
 import { checkMigrationDrift } from './schema-drift';
+import { checkSchemaDump } from './schema-dump-drift';
 import { scanSiteMeta } from './seo-meta';
 import { quoteArg } from './shell-quote';
 import { readStaticReport } from './static-report';
 import { floorProblemFindings, readVerifyFloor } from './verify-floor';
+import { roleLoadFindings } from './verify-role-load';
 import type { VerifyStep } from './verify-step';
 import { fromExec, fromFindings, hostFindings } from './verify-step';
 import { TEST_STEPS } from './verify-tests';
@@ -90,7 +92,8 @@ export const VERIFY_STEPS: readonly VerifyStep[] = [
   },
   {
     name: 'boundaries',
-    summary: "surface, layer and package-tier imports, and the app's own guards",
+    summary:
+      "surface, layer and package-tier imports, one browser transport, and the app's own guards",
     // An app's `guards/` rides here rather than becoming a step of its own, for the reason the
     // seam already states: a host adds findings to a step, it can never add, remove, reorder or
     // skip one — so "green" keeps meaning exactly what it meant. This is the step whose host slot
@@ -101,12 +104,18 @@ export const VERIFY_STEPS: readonly VerifyStep[] = [
     // Discovered, not registered: `guardFindings` reads the directory. A guard that had to
     // announce itself is a guard an app can forget to announce, which is the coupling axiom 8's
     // extension model rejects.
-    run: async (ctx) =>
-      fromFindings([
-        ...(await appBoundaryFindings(ctx.root)),
-        ...(await guardFindings(ctx.root)),
+    //
+    // ONE read of the app's surface files for the whole step: the import rules, the transport
+    // rule and every guard are handed the same text. The guards used to walk and read the tree a
+    // second time (`guard-sources.ts`).
+    async run(ctx) {
+      const sources = await readAppSources(ctx.root);
+      return fromFindings([
+        ...(await appBoundaryFindings(ctx.root, sources)),
+        ...(await guardFindings(ctx.root, sources)),
         ...(await hostFindings(ctx, 'boundaries')),
-      ]),
+      ]);
+    },
   },
   {
     name: 'filesize',
@@ -161,7 +170,7 @@ export const VERIFY_STEPS: readonly VerifyStep[] = [
   {
     name: 'drift',
     summary:
-      'entity declarations vs migrations, every destructive statement declared, and every statement no declaration carries',
+      'entity declarations vs migrations, every destructive statement declared, every statement no declaration carries, and the committed schema dump',
     // Only an app owns migrations; a package monorepo's `packages/db` is the driver, not a schema.
     // Source, not database: the gate runs in CI with nothing listening, and the database half is
     // the post-migrate verification `runMigrations` performs where a connection is already open.
@@ -179,15 +188,20 @@ export const VERIFY_STEPS: readonly VerifyStep[] = [
         // a squash silently drops. Same directory, same reader, no database — this step's own
         // question, which is why it is not a step of its own.
         ...(await checkUngeneratableMigrations(ctx.root)),
+        // The fourth, and the only one that opens a database — a scratch embedded one it boots
+        // itself, so CI still needs nothing listening: the committed `packages/db/schema/` against
+        // what replaying the migrations produces, and that dump loaded back (`X_SCHEMA_DUMP_DRIFT`).
+        ...(await checkSchemaDump(ctx.root, ctx.env ?? Bun.env)),
       ]),
   },
   {
     name: 'contract-diff',
     summary: 'the published contract vs the committed manifest',
-    // Either file is a published contract on its own: `openapi.json` generates the typed client,
-    // so gating on the manifest alone let a stale spec ship a wrong client unchecked.
-    applies: async (ctx) =>
-      existsSync(join(ctx.root, MANIFEST_FILENAME)) || existsSync(join(ctx.root, OPENAPI_FILE)),
+    // A BREAKING change against the committed manifest, and nothing else. Whether the committed
+    // files are stale — `openapi.json` included — is the `manifest` step's, through the one check
+    // `x manifest --check` runs (`manifest-staleness.ts`): reported here as well it was two
+    // steps and one command answering one question, and the step named `manifest` saying green.
+    applies: async (ctx) => existsSync(join(ctx.root, MANIFEST_FILENAME)),
     async run(ctx) {
       const committed = await readAppManifest(ctx.root);
       const { manifest, findings } = await appManifest(ctx.root);
@@ -195,14 +209,13 @@ export const VERIFY_STEPS: readonly VerifyStep[] = [
       return withoutLoadFindings(ctx.root, [
         ...findings,
         ...(committed === undefined ? [] : contractFindings(committed, manifest)),
-        ...(await openApiStaleness(ctx.root, manifest)),
       ]);
     },
   },
   {
     name: 'budgets',
     summary:
-      'per-route JS bytes and LCP, the global style layer every document carries, and the routes that boot nothing to receive their live rows',
+      'per-route JS bytes, the global style layer every document carries, and the routes that boot nothing to receive their live rows',
     // The global-style assertion rides here rather than becoming a step of its own, because this
     // step already asks the one question it asks: what does the document this build emits actually
     // contain? It is also the same app load — `appManifest` fills render's stylesheet registry on
@@ -328,14 +341,18 @@ export const VERIFY_STEPS: readonly VerifyStep[] = [
       const agents = await checkAgentsMd(ctx.root, floor?.agentsMdMaxBytes);
       // The app's load failures, once, here — every other step that loaded it points at this one.
       const app = existsSync(join(ctx.root, APP_CONFIG_FILE));
+      // Started first and awaited last: it is a child process, and it runs beside the rest.
+      const roleLoad = app ? roleLoadFindings(ctx.root, ctx.runner) : Promise.resolve([]);
       const drift = await driftFindings(ctx.root);
       const findings = [
-        ...manifestMissingFindings(ctx.root),
         ...(app ? await withLoadFindings(ctx.root, drift) : drift),
         // An app only: the framework monorepo declares no `defineApi`, so it has no list to be in.
         ...(existsSync(join(ctx.root, APP_CONFIG_FILE))
           ? await unregisteredJobFindings(ctx.root)
           : []),
+        // What a worker never registers: a declaration beside a component the API index does not
+        // import (`verify-role-load.ts`). The boot checks jobs and tasks only, and only at boot.
+        ...(await roleLoad),
         ...(await envExampleFindings(ctx.root)),
         ...floorProblemFindings(floor),
         ...agents.findings,
@@ -365,41 +382,14 @@ export const VERIFY_STEPS: readonly VerifyStep[] = [
 ];
 
 /**
- * The half that had never been asked: is the file there at all? `driftFindings` returns nothing
- * when it is absent — correctly, it has nothing to compare — and `AGENTS.md` line 3 tells an agent
- * that facts live in `x.manifest.json`, `x dev` prints its path, and `x manifest` is the only
- * thing that writes it. Nothing ran it: after `x new`, `bin/setup` and all thirteen generators,
- * `find . -name '*.manifest.json'` returned nothing while this step reported green (#F7).
- *
- * An app root, never this repo: the framework monorepo emits `framework.manifest.json` and has no
- * `x.manifest.json` to be missing, so the `app.config.ts` is what decides — the same discriminator
- * `drift`, `budgets`, `seo`, `i18n` and `policy` each use.
+ * The committed generated files against the code — `x manifest --check`'s check, through its
+ * function. With no committed contract there is nothing to load an app for: an app root is told
+ * its manifest is missing, and the framework monorepo (which has neither file) is told nothing.
  */
-function manifestMissingFindings(root: string): readonly Finding[] {
-  if (!existsSync(join(root, APP_CONFIG_FILE))) return [];
-  if (existsSync(join(root, MANIFEST_FILENAME))) return [];
-  return [
-    {
-      code: 'X_MANIFEST_MISSING',
-      cause: `${MANIFEST_FILENAME} does not exist, so every fact an agent reads about this app — route table, action schemas, policies, error codes — is unavailable`,
-      fix: 'x manifest',
-      docs: ERROR_DOCS_URL,
-      at: MANIFEST_FILENAME,
-    },
-  ];
-}
-
-/** `assertNoDrift` throws `X_MANIFEST_DRIFT`; a step reports, so the error becomes a finding. */
 async function driftFindings(root: string): Promise<readonly Finding[]> {
-  const path = join(root, MANIFEST_FILENAME);
-  if (!existsSync(path)) return [];
+  if (!hasCommittedContract(root)) return manifestMissingFindings(root);
   const { manifest, findings } = await appManifest(root);
-  try {
-    await assertNoDrift({ manifest, path });
-    return findings;
-  } catch (error) {
-    return [...findings, { ...findingFrom(error), at: MANIFEST_FILENAME }];
-  }
+  return [...findings, ...(await manifestStaleness(root, manifest))];
 }
 
 /** A breaking change is allowed — with a major bump. `verifyContract` is the one that decides. */

package/src/verify-coverage-run.ts

@@ -0,0 +1,190 @@
+// An app's `unit` step, run so its coverage can be read: the suite as a pool of plain `bun test`
+// processes over fixed slices, each writing its own lcov, folded by `coverage-lcov.ts`'s rule.
+//
+// NOT `bun test --parallel` with `--coverage` added, which is the obvious form and was measured
+// first (2026-10-01, Bun 1.4.0, `examples/dummy`, 53 unit files): Bun's own cross-worker merge is
+// a union, so the SAME tree read 59.9% of lines at four workers, 65.0% at two and 65.5% in one
+// process. A floor that moves with the core count is not a floor. Per-process lcov folded here
+// read 65.90% at 2, 4 and 8 processes.
+//
+// It costs nothing measurable: four slice processes took 9.7 s against 12.4 s for `--parallel=4`
+// over the same files, on a loaded 12-core box.
+
+// why: Bun ships no recursive delete and no path-join primitive; the lcov parts live under `.x/`.
+import { rm } from 'node:fs/promises';
+// why: Bun ships no path-join primitive.
+import { dirname, join } from 'node:path';
+import type { CoverageMap } from './coverage-lcov';
+import { fileCoverageOf, mergeCoverage, parseLcov } from './coverage-lcov';
+import type { ExecResult, Runner } from './exec';
+import { execOutput } from './exec';
+import { msg } from './messages';
+import { countsOf } from './test-counts';
+import { testEnvOverrides } from './test-dotenv';
+import { failureOf, ISOLATED_TEST_ENV } from './test-shards';
+import { SLOT_HELD_ENV } from './test-slots';
+import type { StepOutcome } from './verify-step';
+
+/**
+ * Test files per process. Small enough that a process is thrown away before its heap grows with
+ * the corpus (`test-batches.ts`), large enough that the ~0.3 s a process costs to start is noise.
+ */
+export const COVERAGE_SLICE_FILES = 16;
+
+/** Where a run's lcov parts are written, under the app root — removed when the run has read them. */
+export const COVERAGE_DIR = '.x/coverage';
+
+/**
+ * The slices one run is spent as: a pure function of the sorted file list, never of the machine,
+ * so the measured number is the same on a laptop and on a runner. A directory's tests stay in one
+ * slice — function coverage is the best one process reached (`mergeFileCoverage`), and the tests
+ * that cover a file sit beside it — and only a directory larger than the cap is cut.
+ */
+export function coverageSlices(
+  files: readonly string[],
+  cap: number = COVERAGE_SLICE_FILES,
+): readonly (readonly string[])[] {
+  const byDir = new Map<string, string[]>();
+  for (const file of [...new Set(files)].sort()) {
+    const dir = dirname(file);
+    const list = byDir.get(dir) ?? [];
+    list.push(file);
+    byDir.set(dir, list);
+  }
+  const slices: string[][] = [];
+  let open: string[] = [];
+  const close = (): void => {
+    if (open.length > 0) slices.push(open);
+    open = [];
+  };
+  for (const group of byDir.values()) {
+    if (group.length > cap) {
+      close();
+      for (let at = 0; at < group.length; at += cap) slices.push(group.slice(at, at + cap));
+    } else {
+      if (open.length + group.length > cap) close();
+      open.push(...group);
+    }
+  }
+  close();
+  return slices;
+}
+
+export interface CoveredRunOptions {
+  readonly root: string;
+  readonly runner: Runner;
+  /** Paths relative to `root`. */
+  readonly files: readonly string[];
+  readonly workers: number;
+  readonly isolate?: boolean;
+  readonly env?: Readonly<Record<string, string | undefined>>;
+  readonly widthReason?: string;
+  readonly lease?: (want: number) => Promise<{ readonly count: number; release(): void }>;
+  /** Test files per process. Absent is `COVERAGE_SLICE_FILES`; a test cuts smaller. */
+  readonly sliceFiles?: number;
+}
+
+export interface CoveredRun extends StepOutcome {
+  /** Every file any slice loaded, by the path Bun wrote — relative to `root`. */
+  readonly coverage: CoverageMap;
+}
+
+/** One slice's argv. An explicit file list, never a re-glob, for `testArgs`' reason. */
+export const coveredArgs = (
+  files: readonly string[],
+  dir: string,
+  isolate: boolean,
+): readonly string[] => [
+  'bun',
+  'test',
+  ...(isolate ? ['--isolate'] : []),
+  '--coverage',
+  '--coverage-reporter=lcov',
+  `--coverage-dir=${dir}`,
+  ...files,
+];
+
+export async function runCovered(options: CoveredRunOptions): Promise<CoveredRun> {
+  const slices = coverageSlices(options.files, options.sliceFiles);
+  const want = Math.max(1, Math.min(Math.trunc(options.workers), slices.length));
+  const lease = want > 1 ? await options.lease?.(want) : undefined;
+  const width = Math.min(want, lease?.count ?? want);
+  const base = join(options.root, COVERAGE_DIR, `unit-${String(process.pid)}`);
+  const isolate = options.isolate === true;
+  const overrides = {
+    ...testEnvOverrides(options.root, options.env ?? Bun.env),
+    ...(isolate ? { [ISOLATED_TEST_ENV]: '1' } : {}),
+    ...(lease === undefined ? {} : { [SLOT_HELD_ENV]: '1' }),
+  };
+  const results = new Array<ExecResult>(slices.length);
+  let next = 0;
+  // Each pool worker names its own numbered test database, as `--parallel`'s workers do.
+  const worker = async (slot: number): Promise<void> => {
+    while (next < slices.length) {
+      const index = next;
+      next += 1;
+      results[index] = await options.runner(
+        coveredArgs(slices[index] as readonly string[], join(base, String(index)), isolate),
+        { cwd: options.root, env: { ...overrides, ULTIMATE_TEST_WORKER: String(slot) } },
+      );
+    }
+  };
+  let maps: CoverageMap[];
+  try {
+    await Promise.all(Array.from({ length: width }, (_, slot) => worker(slot)));
+    maps = await Promise.all(slices.map((_, index) => readPart(join(base, String(index)))));
+  } finally {
+    lease?.release();
+    await rm(base, { recursive: true, force: true });
+  }
+  const failed = results.filter((result) => !result.ok);
+  const first = failed[0];
+  const output = results
+    .map((result, index) =>
+      result.ok
+        ? undefined
+        : [
+            msg('cli.test.batch', {
+              batch: index + 1,
+              batches: results.length,
+              files: slices[index]?.length ?? 0,
+            }),
+            execOutput(result),
+          ].join('\n'),
+    )
+    .filter((text) => text !== undefined)
+    .join('\n');
+  return {
+    ok: first === undefined,
+    findings:
+      first === undefined
+        ? []
+        : [
+            failureOf(first.code, options.files.length, {
+              workers: width,
+              type: 'unit',
+              ...(isolate ? { isolate: true } : {}),
+            }),
+          ],
+    workers: width,
+    ...(options.widthReason === undefined ? {} : { widthReason: options.widthReason }),
+    tests: countsOf(results),
+    ...(first === undefined ? {} : { output }),
+    coverage: mergeCoverage(maps),
+  };
+}
+
+/**
+ * One slice's lcov as a map, kept to the app's own tree: a slice loads a thousand framework files
+ * for every hundred of the app's, and none of those is what the floor measures. No file is no
+ * coverage — the slice died before writing it, and its exit code already says so.
+ */
+async function readPart(dir: string): Promise<CoverageMap> {
+  const file = Bun.file(join(dir, 'lcov.info'));
+  if (!(await file.exists())) return {};
+  return Object.fromEntries(
+    parseLcov(await file.text())
+      .filter((record) => /^(?:apps|packages)\//.test(record.file))
+      .map((record) => [record.file, fileCoverageOf(record)]),
+  );
+}