@ultimat3/testing 29.3.2 → 30.0.0

package/src/cassette.ts

@@ -0,0 +1,166 @@
+// `cassette()` — a vendor's recorded answers, replayed through `mockFetch` with the network still
+// sealed, and recorded (opt-in, never under CI) with the written bytes checked for secrets. Replay
+// adds no match path: each recorded URL is one `mockFetch` route, answered in call order.
+
+// why: `cassette()` is synchronous so `await using` can hold it, so the file is read synchronously;
+// Bun has no sync read or atomic rename of its own.
+import { existsSync, mkdirSync, readFileSync, renameSync, writeFileSync } from 'node:fs';
+// why: the cassette directory is joined from the caller's `import.meta.dir`; Bun has no path join.
+import { join } from 'node:path';
+import { assert } from '@ultimat3/core';
+import type { UnusedEntry } from './cassette-errors';
+import {
+  CassetteMissingError,
+  CassetteRecordRefusedError,
+  CassetteUnusedError,
+} from './cassette-errors';
+import type { CassetteEntry } from './cassette-format';
+import { decodeBody, parseCassette, urlMatch } from './cassette-format';
+import { startRecording } from './cassette-record';
+import { NetworkSealedError } from './errors';
+import { allowHost, captureNetwork, mockFetch, restoreCapturedNetwork } from './sealed-network';
+
+export interface CassetteOptions {
+  /** The vendor hosts a recording may reach (`api.stripe.com`). Recording needs at least one. */
+  readonly record?: { readonly hosts: readonly string[] };
+  /**
+   * The app's rule, after the built-in masking: applied to each URL and text body before the scan.
+   * Replace with `'[redacted]'` — in a URL that marker matches any one segment on replay.
+   */
+  readonly redact?: (text: string) => string;
+  /** Values that must never be written, beside every credential-named env var's. */
+  readonly secrets?: readonly string[];
+}
+
+/** `await using tape = cassette(...)`: the dispose is where a recording is written. */
+export interface Cassette extends AsyncDisposable {
+  readonly mode: 'replay' | 'record';
+  readonly file: string;
+}
+
+/** The switch: `ULTIMATE_CASSETTE=record` records; unset (or `replay`) replays. */
+export const CASSETTE_ENV = 'ULTIMATE_CASSETTE';
+
+export function cassette(dir: string, name: string, options: CassetteOptions = {}): Cassette {
+  const file = join(dir, '__cassettes__', `${name}.json`);
+  const before = captureNetwork();
+  const mode = modeOf(Bun.env[CASSETTE_ENV]);
+  if (mode === 'record') return recording(dir, name, file, options, before.allowed);
+  return replaying(dir, name, file);
+}
+
+function modeOf(value: string | undefined): Cassette['mode'] {
+  if (value === undefined || value === '' || value === 'replay') return 'replay';
+  assert(
+    value === 'record',
+    `${CASSETTE_ENV} is ${JSON.stringify(value)}; it is 'record', 'replay' or unset`,
+    `${CASSETTE_ENV}=record bun test <test file>   # or unset it to replay`,
+  );
+  return 'record';
+}
+
+function recording(
+  dir: string,
+  name: string,
+  file: string,
+  options: CassetteOptions,
+  allowedBefore: readonly string[],
+): Cassette {
+  // Before any dial: a gate must never reach a vendor, whatever a developer exported.
+  const ci = Bun.env['CI'];
+  if (ci !== undefined && ci !== '' && ci !== 'false' && ci !== '0') {
+    throw new CassetteRecordRefusedError({ reason: 'ci', name });
+  }
+  const hosts = options.record?.hosts ?? [];
+  if (hosts.length === 0) throw new CassetteRecordRefusedError({ reason: 'no-hosts', name });
+  for (const host of hosts) allowHost(host);
+  const tape = startRecording({
+    name,
+    dir,
+    file,
+    hosts: new Set(hosts),
+    redact: options.redact,
+    secrets: options.secrets ?? [],
+    env: Bun.env,
+    write: (text) => {
+      mkdirSync(join(dir, '__cassettes__'), { recursive: true });
+      const temp = `${file}.${process.pid}.tmp`;
+      writeFileSync(temp, text);
+      renameSync(temp, file);
+    },
+  });
+  return {
+    mode: 'record',
+    file,
+    async [Symbol.asyncDispose]() {
+      // The unsealing ends with the recording, whatever `finish` decides.
+      const now = captureNetwork();
+      const added = hosts.filter((host) => !allowedBefore.includes(host));
+      restoreCapturedNetwork({ ...now, allowed: now.allowed.filter((h) => !added.includes(h)) });
+      await tape.finish();
+    },
+  };
+}
+
+interface Queue {
+  readonly entries: CassetteEntry[];
+  readonly used: boolean[];
+  next: number;
+}
+
+function replaying(dir: string, name: string, file: string): Cassette {
+  if (!existsSync(file)) throw new CassetteMissingError({ file, dir, name });
+  const { entries } = parseCassette(readFileSync(file, 'utf8'), file);
+  // URL first, then verb: one route per URL, so a masked query's pattern is registered once.
+  const byUrl = new Map<string, Map<string, Queue>>();
+  for (const entry of entries) {
+    const verbs = byUrl.get(entry.url) ?? new Map<string, Queue>();
+    byUrl.set(entry.url, verbs);
+    const queue = verbs.get(entry.method) ?? { entries: [], used: [], next: 0 };
+    verbs.set(entry.method, queue);
+    queue.entries.push(entry);
+    queue.used.push(false);
+  }
+  const before = captureNetwork().mocks.length;
+  for (const [url, verbs] of byUrl) mockFetch(urlMatch(url), (request) => answer(verbs, request));
+  // `mockFetch` puts each new route FIRST: the cassette's are the head of the list.
+  const registered = captureNetwork().mocks;
+  const routes = registered.slice(0, registered.length - before);
+  return {
+    mode: 'replay',
+    file,
+    async [Symbol.asyncDispose]() {
+      const now = captureNetwork();
+      restoreCapturedNetwork({ ...now, mocks: now.mocks.filter((r) => !routes.includes(r)) });
+      const unused: UnusedEntry[] = [];
+      for (const [url, verbs] of byUrl) {
+        for (const [method, queue] of verbs) {
+          queue.used.forEach((used, index) => {
+            if (!used) unused.push({ method, url, index });
+          });
+        }
+      }
+      if (unused.length > 0) throw new CassetteUnusedError({ file, dir, unused });
+    },
+  };
+}
+
+/** The next recorded answer for this verb; past the end the last repeats, as `mockFetch`'s do. */
+function answer(verbs: ReadonlyMap<string, Queue>, request: Request): Response {
+  const queue = verbs.get(request.method.toUpperCase());
+  if (queue === undefined) {
+    throw new NetworkSealedError({ url: request.url, method: request.method, allowed: [] });
+  }
+  const index = Math.min(queue.next, queue.entries.length - 1);
+  queue.next += 1;
+  queue.used[index] = true;
+  const entry = queue.entries[index];
+  if (entry === undefined) {
+    throw new NetworkSealedError({ url: request.url, method: request.method, allowed: [] });
+  }
+  const empty = [101, 204, 205, 304].includes(entry.status);
+  return new Response(empty ? null : decodeBody(entry), {
+    status: entry.status,
+    headers: entry.headers,
+  });
+}

package/src/cdp-browser.ts

@@ -51,10 +51,12 @@ export const E2E_BROWSER_CLOSE_MS = LAUNCHED_CLOSE_MS;
 
 /**
  * Sequential deadlines one `tab.goto()` spends: the load event raced against `Page.navigate`'s
- * reply (one deadline, two waiters), then the two reads of the document (`cdp-e2e-page.ts`). Held
- * to the method by `cdp-browser.test.ts` over a fake connection, as the tab's count is.
+ * reply (one deadline, two waiters), the two reads of the document (`cdp-e2e-page.ts`), then the
+ * accessibility audit's two reads — the probe and the tree (`e2e-a11y-tabs.ts`). A finding's own
+ * description is three more calls, spent on a test that is already red. Held to the method by
+ * `cdp-browser.test.ts` over a fake connection, as the tab's count is.
  */
-export const GOTO_DEADLINES = 3;
+export const GOTO_DEADLINES = 5;
 
 /** The longest one `tab.goto()` is designed to take, at the default per-call deadline. */
 export const E2E_GOTO_MS = GOTO_DEADLINES * DEFAULT_CDP_TIMEOUT_MS;

package/src/cdp-e2e-page.ts

@@ -7,9 +7,11 @@
 // through it: `ScrapePage` is a full scraping surface whose intended implementation is
 // `puppeteer-core`, and an e2e driver needs none of it.
 
+import type { AxTreeNode } from './ax-node';
+import { axRecord, toAxTreeNodes } from './ax-node';
 import type { CdpConnection } from './cdp-connection';
 import { CdpCallFailedError, CdpTimeoutError } from './cdp-errors';
-import type { E2eBrowserPage } from './e2e-page';
+import type { AxTreeRequest, E2eBrowserPage } from './e2e-page';
 
 /** What the page threw, when `Runtime.evaluate` answered with an exception rather than a value. */
 const thrownIn = (result: Record<string, unknown> | undefined): string | undefined => {
@@ -39,9 +41,12 @@ const NAVIGATED_AWAY = [
   'Inspected target navigated or closed',
   'Execution context was destroyed',
   'Cannot find context with specified id',
+  // A tree node's DOM id from the document that was just replaced (`DOM.resolveNode`).
+  'No node with given id found',
 ] as const;
 
-const navigatedAway = (error: unknown): error is CdpCallFailedError =>
+/** A call refused because the document it addressed is gone: "not this document", not a failure. */
+export const navigatedAway = (error: unknown): error is CdpCallFailedError =>
   error instanceof CdpCallFailedError && NAVIGATED_AWAY.some((text) => error.cause.includes(text));
 
 /** One tab: the port the driver drives, plus what a multi-tab acceptance suite asks of one. */
@@ -65,6 +70,8 @@ export interface E2eTab extends E2eBrowserPage {
    * dispatches straight at the element and can never see that.
    */
   pointerClick(selector: string): Promise<void>;
+  /** Required on a tab: the audit of every `e2eTest` reads it (`e2e-a11y-run.ts`). */
+  accessibilityTree(request: AxTreeRequest): Promise<readonly AxTreeNode[]>;
   /** Reload and wait for the load, at the url the tab already had. */
   reload(): Promise<void>;
   /** Poll `expression` in the page until it is truthy, or refuse naming `what`. */
@@ -87,13 +94,41 @@ export interface CdpE2eTabOptions {
   readonly loadTimeoutMs: number;
   /** The session's browser-wide switch, which `offline()` forwards to. */
   readonly offline: (enabled: boolean) => Promise<void>;
+  /**
+   * The raw-tab accessibility audit (`e2e-a11y-tabs.ts`), which the session wires: `navigated`
+   * after every settled `goto`/`reload`, `used` on every call the tab sends, `closed` once
+   * `close()` is answered. Absent, a tab is a
+   * bare driver — what this file's own unit tests build.
+   */
+  readonly audit?: { navigated(): Promise<void>; used(): void; closed(): void } | undefined;
 }
 
 const POLL_MS = 100;
 
+/** The one place the framework reads a whole document's accessibility tree. */
+export const FULL_AX_TREE = 'Accessibility.getFullAXTree';
+
+/**
+ * Run ON the resolved node: a document answers for its `<html>`, opening tag only — its whole
+ * markup starts with the head, which names nothing. Bounded as `e2e-a11y.ts` says.
+ */
+const DESCRIBE_NODE = `function (selectors) {
+  const el = this.nodeType === 9 ? this.documentElement : this;
+  if (!el || typeof el.outerHTML !== 'string') return JSON.stringify({ html: '', matches: [] });
+  const html = el === document.documentElement ? el.outerHTML.slice(0, el.outerHTML.indexOf('>') + 1) : el.outerHTML;
+  return JSON.stringify({
+    html: html.slice(0, 120),
+    matches: selectors.filter((s) => { try { return el.matches(s); } catch { return false; } }),
+  });
+}`;
+
 /** A tab over a session the caller has already attached and enabled (`cdp-e2e-session.ts`). */
 export function cdpE2eTab(options: CdpE2eTabOptions): E2eTab {
-  const send = options.connection.send.bind(options.connection);
+  const sendRaw = options.connection.send.bind(options.connection);
+  const send: CdpConnection['send'] = (...args) => {
+    options.audit?.used();
+    return sendRaw(...args);
+  };
   const { sessionId } = options;
 
   // `url()` is SYNCHRONOUS on the port, and CDP has no synchronous read — so the last committed
@@ -145,6 +180,44 @@ export function cdpE2eTab(options: CdpE2eTabOptions): E2eTab {
     throw new CdpTimeoutError({ method: `waitFor(${what})${last}`, timeoutMs });
   };
 
+  // One node described: resolved to a page object, asked in the page, released with its group.
+  const describeNode = async (
+    backendNodeId: number,
+    selectors: readonly string[],
+  ): Promise<Pick<AxTreeNode, 'html' | 'matches'>> => {
+    const objectGroup = 'x-e2e-a11y';
+    const resolved = await send('DOM.resolveNode', { backendNodeId, objectGroup }, sessionId);
+    const objectId = axRecord(resolved.result?.['object'])?.['objectId'];
+    if (typeof objectId !== 'string') return {};
+    try {
+      const raw = evaluated(
+        (
+          await send(
+            'Runtime.callFunctionOn',
+            {
+              objectId,
+              functionDeclaration: DESCRIBE_NODE,
+              arguments: [{ value: selectors }],
+              returnByValue: true,
+            },
+            sessionId,
+          )
+        ).result,
+      );
+      const answer = axRecord(typeof raw === 'string' ? JSON.parse(raw) : raw);
+      const html = answer?.['html'];
+      const matches = answer?.['matches'];
+      return {
+        ...(typeof html === 'string' ? { html } : {}),
+        matches: Array.isArray(matches)
+          ? matches.filter((m): m is string => typeof m === 'string')
+          : [],
+      };
+    } finally {
+      await send('Runtime.releaseObjectGroup', { objectGroup }, sessionId).catch(() => undefined);
+    }
+  };
+
   const tab: E2eTab = {
     targetId: options.targetId,
     url: () => current,
@@ -192,6 +265,8 @@ export function cdpE2eTab(options: CdpE2eTabOptions): E2eTab {
       // The app may have redirected, so the committed url is re-read rather than assumed.
       const settled = await evaluate('location.href');
       if (typeof settled === 'string' && settled !== '') current = settled;
+      // The document as it settled, before anything replaces it: what a person would land on.
+      await options.audit?.navigated();
       return undefined;
     },
     evaluate,
@@ -230,6 +305,18 @@ export function cdpE2eTab(options: CdpE2eTabOptions): E2eTab {
       }
     },
     offline: (enabled: boolean) => options.offline(enabled),
+    async accessibilityTree(request: AxTreeRequest): Promise<readonly AxTreeNode[]> {
+      const nodes = toAxTreeNodes((await send(FULL_AX_TREE, {}, sessionId)).result);
+      const out: AxTreeNode[] = [];
+      for (const node of nodes) {
+        const described =
+          node.backendNodeId !== undefined && request.describe(node)
+            ? await describeNode(node.backendNodeId, request.selectors)
+            : {};
+        out.push({ ...node, ...described });
+      }
+      return out;
+    },
     async scripting(enabled: boolean): Promise<void> {
       await send('Emulation.setScriptExecutionDisabled', { value: !enabled }, sessionId);
     },
@@ -249,6 +336,7 @@ export function cdpE2eTab(options: CdpE2eTabOptions): E2eTab {
     },
     async close(): Promise<void> {
       await send('Target.closeTarget', { targetId: options.targetId });
+      options.audit?.closed();
     },
   };
   return tab;

package/src/cdp-e2e-session.ts

@@ -9,6 +9,8 @@ import { cdpE2eTab } from './cdp-e2e-page';
 import { CdpCallFailedError, CdpTimeoutError } from './cdp-errors';
 import { isNetworkProbe, networkAgrees } from './cdp-network-probe';
 import { offlineScripts } from './cdp-offline-script';
+import type { AuditedTab } from './e2e-a11y-tabs';
+import { auditTab } from './e2e-a11y-tabs';
 
 export interface E2eSession {
   /** A new tab in the same profile — same cookies, same origin storage, same SharedWorker. */
@@ -311,13 +313,28 @@ export async function cdpE2eSession(options: CdpE2eSessionOptions): Promise<E2eS
         });
       }
       const sessionId = await attached(targetId);
-      return cdpE2eTab({
+      // Every tab is audited: built here, so no suite can hold one the audit does not see. The
+      // tab is alive while the browser still knows its target — a closed one has no page to read.
+      let audit: AuditedTab | undefined;
+      const tab = cdpE2eTab({
         connection,
         sessionId,
         targetId,
         loadTimeoutMs: options.loadTimeoutMs,
         offline,
+        audit: {
+          navigated: () => audit?.navigated() ?? Promise.resolve(),
+          used: () => audit?.used(),
+          closed: () => audit?.closed(),
+        },
       });
+      audit = auditTab(tab, () =>
+        send('Target.getTargetInfo', { targetId }).then(
+          () => true,
+          () => false,
+        ),
+      );
+      return tab;
     },
     async addInitScript(source: string): Promise<void> {
       scripts.push(source);

package/src/define-exercise.ts

@@ -0,0 +1,82 @@
+// `defineExercise({ publishPost: { input, actor }, sendInvoice: { off: 'why' } })`: an app's
+// overrides for the exercise pass, one entry per primitive. Each value IS 39's `.contract({
+// exercise })` option, re-exported rather than restated, so one shape answers both questions.
+// A blank `off` is refused here, at declaration; an unknown name when the pass runs.
+
+import type { ExerciseOptions } from '@ultimat3/action';
+import { renderCauseValue, renderFixLiteral, UltimateError } from '@ultimat3/core';
+
+/** 39's option type, exactly: `{ actor, input?, runs? }` or `{ off: '<reason>' }`. */
+export type ExerciseOverride = ExerciseOptions;
+
+/** What `defineExercise` returns: the overrides, by primitive name. Read by `runExercisePass`. */
+export interface ExerciseOverrides {
+  readonly kind: 'exercise-overrides';
+  readonly entries: ReadonlyMap<string, ExerciseOverride>;
+  /** The entity an actor is a row of, by name: its id is bound to a seeded row. */
+  readonly actorEntity?: string;
+}
+
+/** What the whole pass needs to know of the app, beside the per-primitive entries. */
+export interface ExerciseAppOptions {
+  /**
+   * The entity whose rows ARE the app's actors (`members`, `users`): each actor's id becomes a
+   * seeded row's key in its own tenant, so a handler writing `ctx.actor.id` into a foreign key
+   * writes a row that exists. Omitted, an actor's id is its role's name.
+   */
+  readonly actor?: { readonly $name: string };
+}
+
+/** `X_CONTRACT_EXERCISE_UNDECLARED`, 39's code for the same silence: an `off` with no reason. */
+const blankReason = (name: string): UltimateError =>
+  new UltimateError({
+    code: 'X_CONTRACT_EXERCISE_UNDECLARED',
+    cause: `defineExercise() turns ${renderCauseValue(name)} off with a blank reason, so the skip is silent`,
+    fix: `defineExercise({ ${renderFixLiteral(name, '<name>')}: { off: '<why this primitive cannot run in the exercise pass>' } })   # in apps/web/exercise.ts`,
+  });
+
+export function defineExercise(
+  overrides: Readonly<Record<string, ExerciseOverride>>,
+  app: ExerciseAppOptions = {},
+): ExerciseOverrides {
+  const entries = new Map<string, ExerciseOverride>();
+  // `Object.entries`, never `for in`: an inherited key is not a declaration.
+  for (const [name, override] of Object.entries(overrides)) {
+    if ('off' in override && override.off.trim().length === 0) throw blankReason(name);
+    entries.set(name, override);
+  }
+  return Object.freeze({
+    kind: 'exercise-overrides',
+    entries,
+    ...(app.actor === undefined ? {} : { actorEntity: app.actor.$name }),
+  });
+}
+
+/**
+ * Every override names a registered action, query or job — checked when the pass runs, because
+ * that is when the registries are full. `X_DECLARATION_UNKNOWN`, the code an unknown name answers
+ * everywhere else; the cause lists what IS registered so the typo is visible.
+ */
+export function assertOverridesKnown(
+  overrides: ExerciseOverrides | undefined,
+  known: ReadonlySet<string>,
+): void {
+  const unknown = [...(overrides?.entries.keys() ?? [])].filter((name) => !known.has(name)).sort();
+  if (unknown.length === 0) return;
+  throw unknownDeclaration(unknown, known, 'defineExercise() overrides');
+}
+
+/** One unknown-name refusal for an override and for `only`, so both read the same. */
+export function unknownDeclaration(
+  names: readonly string[],
+  known: ReadonlySet<string>,
+  where: string,
+): UltimateError {
+  const listed = [...known].sort();
+  return new UltimateError({
+    code: 'X_DECLARATION_UNKNOWN',
+    cause: `${where} name ${names.map((name) => renderCauseValue(name)).join(', ')}, which no registered action, query or job is called (registered: ${listed.length === 0 ? 'none' : renderCauseValue(listed.join(', '))})`,
+    fix: 'x actions list --json   # or x queries list --json / x jobs list --json; rename or remove the entry in apps/web/exercise.ts',
+    meta: { unknown: names, registered: listed },
+  });
+}

package/src/drill-budgets.ts

@@ -0,0 +1,54 @@
+// A drill's thresholds, derived from what the app declares — its request deadline, its drain and
+// its readiness mode — never typed per drill. `--budget-ms` replaces the deadline alone, and the
+// verdict prints that it did.
+
+import { finiteCount, MAX_TIMER_MS } from '@ultimat3/core';
+import type { DrillBudgets } from './drill-verdict';
+
+/** The facts of an app's config a drill reads. */
+export interface DrillConfig {
+  /** `configureHttp({ requestTimeoutMs })`; `0` is "no deadline", which a drill cannot judge. */
+  readonly requestTimeoutMs: number;
+  readonly drainDeadlineMs: number;
+  readonly readinessGraceMs: number;
+  readonly readiness: 'dependencies' | 'process';
+}
+
+/** `@ultimat3/http`'s own default request deadline, the one a drill measures against with none set. */
+export const DRILL_DEFAULT_DEADLINE_MS = 30_000;
+
+/**
+ * One bounded delay: what a degraded dependency may cost one request. The redis tier's per-command
+ * deadline is 150 ms and a paused probe answered under 1 s (`29-data-redis-outage`).
+ */
+export const DRILL_PROMPT_MS = 1_000;
+
+export interface DrillTiming extends DrillBudgets {
+  /** How long each fault phase is held: past one deadline, so a blocked request meets it. */
+  readonly phaseMs: number;
+}
+
+export function drillBudgets(config: DrillConfig, overrideMs?: number): DrillTiming {
+  const declared = finiteCount('drillBudgets', 'requestTimeoutMs', config.requestTimeoutMs);
+  const deadlineMs =
+    overrideMs === undefined
+      ? declared === 0
+        ? DRILL_DEFAULT_DEADLINE_MS
+        : declared
+      : finiteCount('x drill', '--budget-ms', overrideMs, 1);
+  const drainMs =
+    finiteCount('drillBudgets', 'readinessGraceMs', config.readinessGraceMs) +
+    finiteCount('drillBudgets', 'drainDeadlineMs', config.drainDeadlineMs);
+  return {
+    deadlineMs: Math.min(deadlineMs, MAX_TIMER_MS),
+    promptMs: DRILL_PROMPT_MS,
+    // Recovery and readiness are each given one deadline: a pool that replaces its sockets does
+    // so on the next statement, and a statement is bounded by the request it serves.
+    recoveryMs: deadlineMs,
+    readinessMs: deadlineMs,
+    drainMs,
+    readiness: config.readiness,
+    override: overrideMs,
+    phaseMs: deadlineMs + DRILL_PROMPT_MS,
+  };
+}

package/src/drill-errors.ts

@@ -0,0 +1,45 @@
+// The two ways a fault drill ends red. Declared in `errors.ts` with this package's codes, thrown
+// from here: a drill whose service is missing is REFUSED, never skipped — a green drill that ran
+// nothing is the vacuous pass — and a drill whose property failed names the property and evidence.
+
+import { renderCauseValue, renderFixShellArg, UltimateError } from '@ultimat3/core';
+import type { DrillFailure } from './drill-verdict';
+
+const DRILL_PLACEHOLDER = '<the drill the cause names>';
+
+export type DrillServiceGap =
+  /** The service is not running where the drill can reach it: its `TEST_*` URL is unset. */
+  | { readonly kind: 'unset'; readonly variable: string }
+  /** The app declares no use of the service, so faulting it would prove nothing. */
+  | { readonly kind: 'undeclared'; readonly declaration: string };
+
+export class DrillServiceMissingError extends UltimateError {
+  constructor(input: { readonly drill: string; readonly gap: DrillServiceGap }) {
+    const { gap } = input;
+    super({
+      code: 'X_DRILL_SERVICE_MISSING',
+      cause:
+        gap.kind === 'unset'
+          ? `x drill ${renderCauseValue(input.drill)} needs ${gap.variable}, and it is unset: a drill with no service to fault is refused, never passed`
+          : `x drill ${renderCauseValue(input.drill)} faults a service this app does not use (${gap.declaration}), so it would prove nothing`,
+      fix:
+        gap.kind === 'unset'
+          ? 'docker compose -f docker/docker-compose.test.yml up -d --wait   # then: set -a; . docker/test-services.env; set +a'
+          : `x drill --list --json   # pick a drill this app declares the service for, or declare it in app.config.ts: ${gap.declaration}`,
+      meta: { drill: input.drill, gap: gap.kind },
+    });
+  }
+}
+
+/** One failed property, as a thrown error or as the cause and fix of a CLI finding. */
+export class DrillFailedError extends UltimateError {
+  constructor(input: { readonly drill: string; readonly failure: DrillFailure }) {
+    const { failure } = input;
+    super({
+      code: 'X_DRILL_FAILED',
+      cause: `x drill ${renderCauseValue(input.drill)}: ${failure.property} did not hold — expected ${failure.expected}; observed ${renderCauseValue(failure.observed)}`,
+      fix: `x drill ${renderFixShellArg(input.drill, DRILL_PLACEHOLDER)} --json   # read ${failure.property} and its evidence, then explain the code that evidence names: x errors explain <CODE>`,
+      meta: { drill: input.drill, property: failure.property },
+    });
+  }
+}