@ultimat3/cli 22.15.0 → 24.0.0

package/src/verify-merge.ts

@@ -6,55 +6,82 @@
 // - 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.
 //
+// - an app's coverage floor judged HERE for a sharded `unit` step: one shard's slice cannot hold a
+//   floor, so each hands its facts over in its document and the fold is judged once.
+//
 // 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';
+// why: Bun ships no synchronous existence check and no path-join primitive.
+import { existsSync } from 'node:fs';
+// why: Bun ships no path-join primitive.
+import { join } from 'node:path';
+import { ERROR_DOCS_URL, renderThrowable, UltimateError } from '@ultimat3/core';
+import { APP_CONFIG_FILE } from './app-root';
+import { judgeCoverage } from './coverage-floor';
+import type { CoverageMap } from './coverage-lcov';
+import { decodeCoverage, mergeCoverage } from './coverage-lcov';
 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 type { PartStep } from './verify-part-step';
+import { readPartStep } from './verify-part-step';
 import { verifySummary } from './verify-run';
-import { VERIFY_STEP_NAMES } from './verify-step';
+import { corpusHash } from './verify-shard';
+import { GATE_COMMAND, 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[];
-  };
+/**
+ * A part handed to `x verify merge` that is not an `x verify --json` document. `command` is the
+ * entry that raised it — `bun run verify` at the framework root, where `x verify` answers
+ * `X_NOT_IN_APP` — so the `fix:` runs where it was raised.
+ */
+export class VerifyMergeInputError extends UltimateError {
+  constructor(input: { file: string; reason: string; sourceError?: unknown; command?: string }) {
+    const command = input.command ?? GATE_COMMAND;
+    super({
+      code: 'X_VERIFY_MERGE_INPUT',
+      cause: `${command} merge: ${input.file} ${input.reason}`,
+      fix: `${command} --only unit --json > part.json   # one document per part, the last line of stdout`,
+      ...(input.sourceError === undefined ? {} : { sourceError: input.sourceError }),
+    });
+  }
 }
 
 export interface VerifyPart {
   readonly file: string;
   readonly durationMs: number;
   readonly steps: readonly PartStep[];
+  /** step → what this part's slice of it covered and did not judge (`data.coverage.<step>.facts`). */
+  readonly coverage?: Readonly<Record<string, CoverageMap>>;
+}
+
+/** Findings a step earns from the parts TOGETHER, which no one part could raise. */
+export type MergeRiders = Readonly<
+  Record<string, { readonly findings: readonly Finding[]; readonly output?: string }>
+>;
+
+export interface MergeOptions {
+  /** The gate as invoked here, for the `fix:` of a gap. */
+  readonly command?: string;
+  readonly riders?: MergeRiders;
 }
 
 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.
+ * The LAST non-empty line, and only it: `bin/check --json` prints the build's document and then
+ * the gate's. Never "the last line that parses" — a part whose tail is not the gate's document is
+ * a truncated or appended upload, and falling back to an earlier line would believe it.
  */
-export function parsePart(file: string, text: string): VerifyPart {
+export function parsePart(file: string, text: string, command: string = GATE_COMMAND): 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' });
+  if (lines.length === 0) throw new VerifyMergeInputError({ file, reason: 'is empty', command });
   let doc: unknown;
   try {
     doc = JSON.parse(lines[lines.length - 1] as string);
@@ -63,54 +90,138 @@ export function parsePart(file: string, text: string): VerifyPart {
       file,
       reason: `does not end in a JSON document (${renderThrowable(error)})`,
       sourceError: error,
+      command,
     });
   }
   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")',
+      command,
     });
   }
   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' });
+    const step = readPartStep(raw);
+    if (typeof step === 'string') throw new VerifyMergeInputError({ file, reason: step, command });
+    steps.push(step);
+  }
+  const coverage = new Map<string, CoverageMap>();
+  for (const [step, entry] of Object.entries(isRecord(data['coverage']) ? data['coverage'] : {})) {
+    // A part that judged its own floor carries numbers, not facts: nothing here to fold.
+    if (!isRecord(entry) || !('facts' in entry)) continue;
+    const map = decodeCoverage(entry['facts']);
+    if (map === undefined) {
+      throw new VerifyMergeInputError({
+        file,
+        reason: `carries coverage for "${step}" that is not a coverage map`,
+        command,
+      });
     }
-    steps.push(raw as unknown as PartStep);
+    coverage.set(step, map);
   }
   return {
     file,
     durationMs: typeof data['durationMs'] === 'number' ? data['durationMs'] : 0,
     steps,
+    ...(coverage.size === 0 ? {} : { coverage: Object.fromEntries(coverage) }),
   };
 }
 
-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 }),
-});
+/** A gap finding, with a fix spelled for the entry that raised it. */
+type Gap = (cause: string, at?: string) => Finding;
+
+const gapFor =
+  (command: string): Gap =>
+  (cause, at) => ({
+    code: 'X_VERIFY_MERGE_INCOMPLETE',
+    cause,
+    fix: `${command} merge parts/*.json --json   # after every CI job uploaded its part`,
+    docs: ERROR_DOCS_URL,
+    ...(at === undefined ? {} : { at }),
+  });
+
+/** The step every part's coverage facts belong to. */
+const COVERED_STEP = 'unit';
+
+/**
+ * An app's coverage floor over a SHARDED `unit` step, judged once on the fold of every shard —
+ * the finding no shard could raise alone. Nothing when the step was not split (the whole run
+ * judged itself), when a shard is red (a failed slice wrote no lcov, and its own finding is the
+ * one to read), or outside an app. Shards that carry no facts at all fold to an empty map, which
+ * is 0% and a red gate: a split can never skip the floor by saying nothing.
+ */
+export async function coverageRiders(
+  parts: readonly VerifyPart[],
+  root: string,
+  floor: VerifyFloor | undefined,
+): Promise<MergeRiders> {
+  if (!existsSync(join(root, APP_CONFIG_FILE))) return {};
+  const shards = parts.flatMap((part) =>
+    part.steps
+      .filter((step) => step.name === COVERED_STEP && step.shard !== undefined)
+      .map((step) => ({ step, coverage: part.coverage?.[COVERED_STEP] })),
+  );
+  if (shards.length === 0 || shards.some((shard) => !shard.step.ok)) return {};
+  const folded = mergeCoverage(
+    shards.flatMap((shard) => (shard.coverage === undefined ? [] : [shard.coverage])),
+  );
+  const verdict = await judgeCoverage(root, folded, floor?.coverage);
+  return { [COVERED_STEP]: { findings: verdict.findings, output: verdict.output } };
+}
 
 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 },
-  );
+  const errors = counted.reduce((sum, step) => sum + (step.tests?.errors ?? 0), 0);
+  return {
+    ran: counted.reduce((sum, step) => sum + (step.tests?.ran ?? 0), 0),
+    skipped: counted.reduce((sum, step) => sum + (step.tests?.skipped ?? 0), 0),
+    ...(errors === 0 ? {} : { errors }),
+  };
 };
 
+/**
+ * The shards' `files` must PARTITION the corpus they all hashed: each file in exactly one shard,
+ * and the union hashing to `corpusHash`. Agreeing on the hash is not agreeing on the split — shard
+ * 1/2 round-robin beside 2/2 with `--timings` ran one file twice and another nowhere, green.
+ */
+function partitionGaps(
+  name: string,
+  sharded: readonly { readonly step: PartStep }[],
+  gap: Gap,
+): readonly Finding[] {
+  const counts = new Map<string, number>();
+  for (const entry of sharded) {
+    for (const file of entry.step.shard?.files ?? []) counts.set(file, (counts.get(file) ?? 0) + 1);
+  }
+  const twice = [...counts].filter(([, count]) => count > 1).map(([file]) => file);
+  const found: Finding[] = [];
+  if (twice.length > 0) {
+    found.push(gap(`step "${name}" ran ${twice.join(', ')} in more than one shard`, name));
+  }
+  // A list's fingerprint, not a credential: what the shards ran against what they all counted.
+  const ranCorpus = corpusHash([...counts.keys()]);
+  const countedCorpus = sharded[0]?.step.shard?.corpusHash;
+  if (ranCorpus !== countedCorpus) {
+    found.push(
+      gap(
+        `step "${name}"'s shards ran ${String(counts.size)} distinct file(s), which is not the corpus they hashed — some file ran in no shard; every shard must split one list the same way (all with --timings, or none)`,
+        name,
+      ),
+    );
+  }
+  return found;
+}
+
 /** 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,
+  gap: Gap,
+  rider: MergeRiders[string] | undefined,
 ): StepResult {
   if (entries.length === 0) {
     return {
@@ -166,6 +277,8 @@ function mergeStep(
     if (doubled.length > 0) {
       gaps.push(gap(`step "${name}" has shard(s) ${doubled.join(', ')} more than once`, name));
     }
+    // Only over a complete, single-corpus set — any gap above already explains a partial union.
+    if (gaps.length === 0) gaps.push(...partitionGaps(name, sharded, gap));
   }
   const steps = entries.map((entry) => entry.step);
   const tests = sumCounts(steps);
@@ -174,16 +287,23 @@ function mergeStep(
   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 riding = rider?.findings ?? [];
+  const findings = [...steps.flatMap((step) => step.findings), ...gaps, ...floorGap, ...riding];
+  const output = [
+    ...steps
+      .filter((step) => !step.ok && step.output !== undefined && step.output.length > 0)
+      .map((step) => step.output as string),
+    ...(rider?.output === undefined ? [] : [rider.output]),
+  ].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,
+    ok:
+      steps.every((step) => step.ok) &&
+      gaps.length === 0 &&
+      floorGap.length === 0 &&
+      riding.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 } : {}),
@@ -198,7 +318,9 @@ export function mergeParts(
   parts: readonly VerifyPart[],
   floor: VerifyFloor | undefined,
   declared: readonly string[] = VERIFY_STEP_NAMES,
+  options: MergeOptions = {},
 ): CommandResult {
+  const gap = gapFor(options.command ?? GATE_COMMAND);
   const unknown = parts.flatMap((part) =>
     part.steps
       .filter((step) => !declared.includes(step.name))
@@ -211,6 +333,10 @@ export function mergeParts(
         part.steps.filter((step) => step.name === name).map((step) => ({ part: part.file, step })),
       ),
       floor,
+      gap,
+      options.riders !== undefined && Object.hasOwn(options.riders, name)
+        ? options.riders[name]
+        : undefined,
     ),
   );
   const failed = steps.filter((step) => !step.ok).map((step) => step.name);

package/src/verify-part-step.ts

@@ -0,0 +1,90 @@
+// One step of an `x verify --json` part, read against the shape `mergeStep` relies on. It was a
+// cast past `name` and `ok`: `findings: [null]` merged green, and a step with no `durationMs`
+// reached `Math.max` as `undefined` — a part a CI job hand-edited, or truncated, was believed.
+
+import type { Finding } from './output';
+import type { TestCounts } from './test-counts';
+
+export 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[];
+  };
+}
+
+const isRecord = (value: unknown): value is Record<string, unknown> =>
+  typeof value === 'object' && value !== null && !Array.isArray(value);
+
+const isCount = (value: unknown): value is number =>
+  typeof value === 'number' && Number.isInteger(value) && value >= 0;
+
+/** What every finding is: code, cause and fix as strings. Optional fields ride along as written. */
+const isFinding = (value: unknown): value is Finding =>
+  isRecord(value) &&
+  typeof value['code'] === 'string' &&
+  typeof value['cause'] === 'string' &&
+  typeof value['fix'] === 'string';
+
+const isTests = (value: unknown): value is TestCounts =>
+  isRecord(value) &&
+  isCount(value['ran']) &&
+  isCount(value['skipped']) &&
+  (value['errors'] === undefined || isCount(value['errors']));
+
+const isShard = (value: unknown): value is NonNullable<PartStep['shard']> =>
+  isRecord(value) &&
+  isCount(value['index']) &&
+  isCount(value['total']) &&
+  typeof value['corpusHash'] === 'string' &&
+  Array.isArray(value['files']) &&
+  value['files'].every((file) => typeof file === 'string');
+
+/** The step, or the reason it is not one — phrased to follow "holds a step …". */
+export function readPartStep(raw: unknown): PartStep | string {
+  if (!isRecord(raw) || typeof raw['name'] !== 'string' || typeof raw['ok'] !== 'boolean') {
+    return 'holds a step without a name and ok';
+  }
+  const name = raw['name'];
+  const durationMs = raw['durationMs'];
+  if (typeof durationMs !== 'number' || !Number.isFinite(durationMs) || durationMs < 0) {
+    return `holds step "${name}" without a durationMs in milliseconds`;
+  }
+  const findings = raw['findings'];
+  if (!Array.isArray(findings) || !findings.every(isFinding)) {
+    return `holds step "${name}" whose findings are not each a code, a cause and a fix`;
+  }
+  const { tests, shard, output, workers, skipped } = raw;
+  if (tests !== undefined && !isTests(tests)) {
+    return `holds step "${name}" whose tests are not counts`;
+  }
+  if (shard !== undefined && !isShard(shard)) {
+    return `holds step "${name}" whose shard is not an index, a total, a corpusHash and its files`;
+  }
+  if (output !== undefined && typeof output !== 'string') {
+    return `holds step "${name}" whose output is not text`;
+  }
+  if (workers !== undefined && !isCount(workers)) {
+    return `holds step "${name}" whose workers is not a count`;
+  }
+  return {
+    name,
+    ok: raw['ok'],
+    durationMs,
+    skipped: skipped === true,
+    findings,
+    ...(workers === undefined ? {} : { workers }),
+    ...(tests === undefined ? {} : { tests }),
+    ...(output === undefined ? {} : { output }),
+    ...(shard === undefined ? {} : { shard }),
+  };
+}

package/src/verify-progress.ts

@@ -0,0 +1,25 @@
+// One finished gate step as one line of JSON, for stderr. `x verify --json` prints its document
+// when the run ENDS, so a job cancelled mid-run used to leave a log with nothing in it (#589):
+// the last of these lines is the last step that finished, and the hung one is whichever is next.
+
+import type { StepResult } from './output';
+
+/** `{"step":"lint","ok":true,"ms":21987}` — plus `"skipped":true` for a step that did not apply. */
+export const stepLine = (step: StepResult): string =>
+  JSON.stringify({
+    step: step.name,
+    ok: step.ok,
+    ms: step.durationMs,
+    ...(step.skipped === true ? { skipped: true } : {}),
+  });
+
+/**
+ * The `onStep` a `--json` run streams through, or nothing: the human render needs no second
+ * channel. One function for both entries (`x verify`, and `bun run verify` at the framework
+ * root), so the two cannot print different lines.
+ */
+export const stepStream = (
+  json: boolean,
+  write: (line: string) => void,
+): { readonly onStep?: (step: StepResult) => void } =>
+  json ? { onStep: (step) => write(stepLine(step)) } : {};

package/src/verify-role-load-probe.ts

@@ -0,0 +1,54 @@
+// The child `verify-role-load.ts` spawns: `bun verify-role-load-probe.ts <app root>`. Imports what
+// a worker imports, then every module that load left out — one at a time — and prints what each of
+// those registered that the worker's process did not hold. Run by hand, it is the same answer.
+
+import { scanAppModules } from './app-load';
+import { scanBackground } from './role-load';
+import type { MissingRegistration } from './verify-role-load';
+import { PROBE_MARKER, registeredSince, registrations } from './verify-role-load';
+import { writeLine } from './write-line';
+
+/**
+ * What importing each module the worker load left out registered, by module — `[]` when the whole
+ * scan reported a module that would not import. Exported so a test calls it in its own process;
+ * the gate runs it as a child, where the registries hold nothing the gate's own load put there.
+ */
+export async function probeRoleLoad(root: string): Promise<readonly MissingRegistration[]> {
+  const background = await scanBackground(root);
+  const imported = new Set(background.files);
+  let held = registrations();
+  const missing: MissingRegistration[] = [];
+  let current: string | undefined;
+
+  /** Whatever appeared since the last look was registered by importing `current`. */
+  const attribute = (): void => {
+    const now = registrations();
+    if (current !== undefined) {
+      for (const one of registeredSince(held, now)) missing.push({ ...one, module: current });
+    }
+    held = now;
+  };
+
+  // The whole app, in the scan's own order. `include` is asked before each import, so the look it
+  // takes is at what the PREVIOUS module added; a module the worker already imported adds nothing.
+  const prefix = root.endsWith('/') ? root : `${root}/`;
+  const whole = await scanAppModules(root, {
+    track: false,
+    include: (absolute) => {
+      attribute();
+      const file = absolute.startsWith(prefix) ? absolute.slice(prefix.length) : absolute;
+      current = imported.has(file) ? undefined : file;
+      return true;
+    },
+  });
+  attribute();
+  // A module that would not import registered nothing in EITHER load, and the gate's own load
+  // already reports it: an answer drawn from a short scan would blame the wrong thing.
+  return whole.findings.length > 0 ? [] : missing;
+}
+
+if (import.meta.main) {
+  const answer = await probeRoleLoad(process.argv[2] ?? process.cwd());
+  writeLine(`${PROBE_MARKER}${JSON.stringify(answer)}`);
+  process.exit(0);
+}

package/src/verify-role-load.ts

@@ -0,0 +1,148 @@
+// The gate's half of per-role loading (`manifest` step): a worker and a scheduler import the API
+// index and every module that reaches no component or stylesheet (`role-load.ts`). A registration
+// made in a module that DOES reach one, and that the index does not import, exists in the web role
+// and in every tool — and not in a worker. At boot only jobs and tasks are checked, against the
+// manifest; this is the build error for everything else a job reads by name.
+
+// why: Bun ships no path API; the fix names the import relative to the API index.
+import { dirname, join, relative } from 'node:path';
+import { ERROR_DOCS_URL, registeredServiceNames, singleLine } from '@ultimat3/core';
+import { entityNames } from '@ultimat3/entity';
+import { catalogDeclarationCount } from '@ultimat3/i18n';
+import { registeredBackfills, registeredJobs, registeredTasks } from '@ultimat3/jobs';
+import { registeredLayouts, registeredMailIds } from '@ultimat3/mail';
+import { registeredChannels } from '@ultimat3/realtime';
+import { definedStorage } from '@ultimat3/storage';
+import { API_INDEX } from './app-root';
+import type { Runner } from './exec';
+import type { Finding } from './output';
+import { quoteArg } from './shell-quote';
+
+/** One thing a process registered, as a job would ask for it: by kind and by name. */
+export interface Registration {
+  readonly kind: string;
+  readonly name: string;
+}
+
+/** A registration the whole app makes and the background load does not, and the module it took. */
+export interface MissingRegistration extends Registration {
+  /** App-root-relative: the scanned module whose import registered it. */
+  readonly module: string;
+}
+
+/**
+ * Every name-keyed registry a job body can read without importing the declaration: what
+ * `ctx.<service>`, `disk('x')`, `t('key')`, a mail layout or a channel resolves through. A
+ * registry read only through a static import of its declaration is not here — the import loads it.
+ */
+export function registrations(): readonly Registration[] {
+  const of = (kind: string, names: readonly string[]): readonly Registration[] =>
+    names.map((name) => ({ kind, name }));
+  return [
+    ...of('service', registeredServiceNames()),
+    ...of('storage disk', definedStorage()?.diskNames ?? []),
+    // A catalog declaration carries no name of its own: the count is what a module adds to.
+    ...of(
+      'catalog declaration',
+      Array.from({ length: catalogDeclarationCount() }, (_, at) => `#${String(at + 1)}`),
+    ),
+    ...of('entity', entityNames()),
+    ...of(
+      'job',
+      registeredJobs().map((job) => job.name),
+    ),
+    ...of(
+      'task',
+      registeredTasks().map((task) => task.name),
+    ),
+    ...of(
+      'backfill',
+      registeredBackfills().map((backfill) => backfill.name),
+    ),
+    ...of('mail', registeredMailIds()),
+    ...of('mail layout', registeredLayouts()),
+    ...of(
+      'channel',
+      registeredChannels().map((channel) => channel.name),
+    ),
+  ];
+}
+
+const keyOf = (one: Registration): string => `${one.kind}\u0000${one.name}`;
+
+/** What `after` holds that `before` did not. */
+export function registeredSince(
+  before: readonly Registration[],
+  after: readonly Registration[],
+): readonly Registration[] {
+  const had = new Set(before.map(keyOf));
+  return after.filter((one) => !had.has(keyOf(one)));
+}
+
+/** The import the API index is missing, as it would be written there. */
+function specifierFor(module: string): string {
+  const from = relative(dirname(API_INDEX), module).replace(/\.[jt]sx?$/, '');
+  return from.startsWith('.') ? from : `./${from}`;
+}
+
+export function roleLoadFinding(missing: MissingRegistration): Finding {
+  return {
+    code: 'X_ROLE_LOAD_INCOMPLETE',
+    cause: `${missing.kind} ${JSON.stringify(missing.name)} is registered by importing ${missing.module}, which reaches a component or a stylesheet and which ${API_INDEX} does not import — so a worker and a scheduler, which import no document, run without it`,
+    fix: `edit ${API_INDEX}: add import '${specifierFor(missing.module)}'; — or move the ${missing.kind} out of ${missing.module} into a module that imports no .tsx and no stylesheet`,
+    docs: ERROR_DOCS_URL,
+    at: missing.module,
+  };
+}
+
+/** The line the probe prints its answer on; everything else it writes is a module's own output. */
+export const PROBE_MARKER = 'x-role-load-probe:';
+
+const PROBE = join(import.meta.dir, 'verify-role-load-probe.ts');
+
+const isMissing = (value: unknown): value is MissingRegistration => {
+  if (typeof value !== 'object' || value === null) return false;
+  const one = value as Record<string, unknown>;
+  return (
+    typeof one['kind'] === 'string' &&
+    typeof one['name'] === 'string' &&
+    typeof one['module'] === 'string'
+  );
+};
+
+/** The probe's answer off its stdout — `undefined` when it printed none. */
+export function parseProbe(stdout: string): readonly MissingRegistration[] | undefined {
+  const line = stdout
+    .split('\n')
+    .reverse()
+    .find((one) => one.startsWith(PROBE_MARKER));
+  if (line === undefined) return undefined;
+  try {
+    const parsed: unknown = JSON.parse(line.slice(PROBE_MARKER.length));
+    return Array.isArray(parsed) && parsed.every(isMissing) ? parsed : undefined;
+  } catch {
+    return undefined;
+  }
+}
+
+/**
+ * One child, because the comparison needs a process whose registries hold ONLY what the background
+ * load put there — this one has already imported the whole app. The child imports what a worker
+ * imports, then the rest module by module, and answers what each of those added.
+ */
+export async function roleLoadFindings(root: string, runner: Runner): Promise<readonly Finding[]> {
+  const result = await runner(['bun', PROBE, root], { cwd: root });
+  const missing = parseProbe(result.stdout);
+  if (missing !== undefined) return missing.map(roleLoadFinding);
+  // No answer is not a pass: the load a worker performs did not complete in a clean process.
+  const said = singleLine(result.stderr.trim().split('\n').at(-1) ?? '');
+  return [
+    {
+      code: 'X_ROLE_LOAD_INCOMPLETE',
+      cause: `the worker's load of this app did not complete in a process of its own (exit ${String(result.code)}${said === '' ? '' : `: ${said}`}), so what a worker registers could not be compared with the whole app`,
+      fix: `bun ${quoteArg(PROBE)} ${quoteArg(root)}`,
+      docs: ERROR_DOCS_URL,
+      at: API_INDEX,
+    },
+  ];
+}