@ultimat3/testing 29.4.0 → 30.1.0

package/src/drill-writes.ts

@@ -0,0 +1,123 @@
+// A drill's write lane: the app's actions an anonymous caller may POST, each request carrying a
+// fresh input drawn as the exercise pass draws one (the seeded draw, then the app's `exercise.ts`
+// override). It is how a drill's load reaches the queue — a job enqueued over HTTP is what
+// `worker-sigkill` and `worker-sigterm` need on the table to have anything to reclaim.
+
+import { bindDrawn } from '@ultimat3/core';
+import type { StandardSchemaV1 } from '@ultimat3/schema';
+import type { ExerciseOverrides } from './define-exercise';
+import type { DrillTarget } from './drill-load';
+import type { Sampler } from './exercise-input';
+import { loadSampler } from './exercise-input';
+import { isAsyncInput } from './exercise-override-input';
+
+/** The seed every drill draws under: one run's inputs are the same on every machine. */
+export const DRILL_DRAW_SEED = 40;
+
+/** An action as the served route table states it. */
+export interface DrillWriteCandidate {
+  readonly name: string;
+  readonly method: string;
+  readonly path: string;
+  /** The policy admits a caller with no session (`auth: 'public'` on its route). */
+  readonly anonymous: boolean;
+  readonly input: StandardSchemaV1;
+}
+
+export interface DrillWritesOptions {
+  readonly actions: readonly DrillWriteCandidate[];
+  readonly overrides?: ExerciseOverrides | undefined;
+  /** The exercise pass's own sampler, loaded on demand when not handed in. */
+  readonly sampler?: Pick<Sampler, 'arbitrary'> | undefined;
+}
+
+export interface DrillWrites {
+  readonly targets: readonly DrillTarget[];
+  /** Every action left out, and why: printed, so an empty lane is never a silent one. */
+  readonly skipped: readonly { readonly name: string; readonly reason: string }[];
+}
+
+const ASYNC_INPUT =
+  'exercise.ts computes its input from the pass (an async input); a load has none';
+
+type Verdict =
+  | { readonly reason: string }
+  | { readonly bind: ((drawn: unknown) => unknown) | undefined };
+
+/** Why `candidate` cannot ride an anonymous load, or the override that binds its input. */
+function verdictOf(
+  candidate: DrillWriteCandidate,
+  overrides: ExerciseOverrides | undefined,
+): Verdict {
+  if (candidate.method !== 'POST') return { reason: `answers ${candidate.method}; the load posts` };
+  if (/[:*]/.test(candidate.path))
+    return { reason: 'its path takes a parameter the load cannot bind' };
+  if (!candidate.anonymous) return { reason: 'its policy refuses an anonymous caller' };
+  const override = overrides?.entries.get(candidate.name);
+  if (override === undefined) return { bind: undefined };
+  if ('off' in override) return { reason: `exercise.ts turns it off: ${override.off.trim()}` };
+  if (override.actor !== null) return { reason: 'exercise.ts runs it as a signed-in actor' };
+  if (isAsyncInput(override)) {
+    return {
+      reason: 'exercise.ts computes its input from the pass (an async input); a load has none',
+    };
+  }
+  return { bind: bindDrawn(override.input) };
+}
+
+const isThenable = (value: unknown): value is PromiseLike<unknown> =>
+  (typeof value === 'object' || typeof value === 'function') &&
+  value !== null &&
+  typeof (value as { then?: unknown }).then === 'function';
+
+/**
+ * The first request's input, drawn ahead of the load. A thenable's rejection is handled: its
+ * outcome is discarded — the action is skipped either way — and unhandled it would end the drill.
+ * A throw answers `undefined`: the load's own draw throws it again on every request, as before.
+ */
+function probe(
+  bind: (drawn: unknown) => unknown,
+  sampler: Pick<Sampler, 'arbitrary'>,
+  candidate: DrillWriteCandidate,
+): unknown {
+  try {
+    const first = bind(sampler.arbitrary(candidate.input, { seed: DRILL_DRAW_SEED, run: 1 }));
+    if (isThenable(first)) Promise.resolve(first).catch(() => undefined);
+    return first;
+  } catch {
+    return undefined;
+  }
+}
+
+/** The write targets of an anonymous load, and every action it leaves out. */
+export async function drillWriteTargets(options: DrillWritesOptions): Promise<DrillWrites> {
+  const sampler = options.sampler ?? (await loadSampler());
+  const targets: DrillTarget[] = [];
+  const skipped: { name: string; reason: string }[] = [];
+  for (const candidate of options.actions) {
+    const verdict = verdictOf(candidate, options.overrides);
+    if ('reason' in verdict) {
+      skipped.push({ name: candidate.name, reason: verdict.reason });
+      continue;
+    }
+    const { bind } = verdict;
+    // `isAsyncInput` reads the function's tag, and a plain function returning a promise has none:
+    // drawn, its body was `JSON.stringify(promise)` — `{}`. So the first request's input is drawn
+    // here, and one that is a thenable is the same skip.
+    if (bind !== undefined && isThenable(probe(bind, sampler, candidate))) {
+      skipped.push({ name: candidate.name, reason: ASYNC_INPUT });
+      continue;
+    }
+    targets.push({
+      method: 'POST',
+      path: candidate.path,
+      // Run n of the seeded draw: a distinct input per request, so a job keyed by its input is a
+      // distinct job — the same body every time is one job deduped, and nothing to reclaim.
+      draw: (run) => {
+        const drawn = sampler.arbitrary(candidate.input, { seed: DRILL_DRAW_SEED, run });
+        return bind === undefined ? drawn : bind(drawn);
+      },
+    });
+  }
+  return { targets, skipped };
+}

package/src/drills.ts

@@ -0,0 +1,109 @@
+// The drill table: each drill's fault and the framework contracts that must hold through it. Data
+// only — `drill-run.ts` plays a fault, `drill-verdict.ts` judges what was measured. Never an app's
+// business rule: every property is one the framework declares for every app the same.
+
+import type { DrillBudgets, DrillProperty } from './drill-verdict';
+import type { FaultMode } from './fault-proxy';
+
+/** A service a drill puts a fault proxy in front of. */
+export type DrillService = 'postgres' | 'redis' | 'nats';
+
+/**
+ * A role the fleet runs as its own process (`ROLE`, `apps/web/server.ts`); `sync` only for a drill
+ * whose sync client needs a node to dial.
+ */
+export type DrillRole = 'web' | 'worker' | 'sync';
+
+export type DrillName =
+  | 'pg-blackhole'
+  | 'pg-slow'
+  | 'pg-restart'
+  | 'redis-down'
+  | 'nats-down'
+  | 'worker-sigkill'
+  | 'worker-sigterm'
+  | 'web-sigterm';
+
+/** The fault itself: a proxy mode per phase, or a signal to one role's process. */
+export type DrillFault =
+  | {
+      readonly kind: 'service';
+      readonly service: DrillService;
+      /** Played in order, each for one phase; `pass` follows, and recovery is timed from it. */
+      readonly phases: (budgets: DrillBudgets) => readonly FaultMode[];
+    }
+  | { readonly kind: 'signal'; readonly role: DrillRole; readonly signal: 'SIGKILL' | 'SIGTERM' };
+
+export interface Drill {
+  readonly name: DrillName;
+  readonly fault: DrillFault;
+  readonly holds: readonly DrillProperty[];
+}
+
+/** Past the statement ceiling and short of the request deadline: slow, never dead. */
+const slowStatementMs = (budgets: DrillBudgets): number => Math.floor(budgets.deadlineMs / 2);
+
+export const DRILLS: readonly Drill[] = [
+  {
+    name: 'pg-blackhole',
+    fault: { kind: 'service', service: 'postgres', phases: () => [{ kind: 'blackhole' }] },
+    holds: ['requests-coded', 'requests-bounded', 'recovers', 'jobs-once'],
+  },
+  {
+    name: 'pg-slow',
+    fault: {
+      kind: 'service',
+      service: 'postgres',
+      phases: (budgets) => [{ kind: 'delay', ms: slowStatementMs(budgets) }],
+    },
+    holds: ['requests-coded', 'requests-bounded', 'recovers'],
+  },
+  {
+    name: 'pg-restart',
+    fault: {
+      kind: 'service',
+      service: 'postgres',
+      phases: () => [{ kind: 'reset' }, { kind: 'refuse' }],
+    },
+    holds: ['requests-coded', 'readyz-flips', 'recovers', 'jobs-once'],
+  },
+  {
+    name: 'redis-down',
+    fault: { kind: 'service', service: 'redis', phases: () => [{ kind: 'blackhole' }] },
+    holds: ['requests-coded', 'requests-prompt', 'requests-ok', 'recovers'],
+  },
+  {
+    name: 'nats-down',
+    fault: { kind: 'service', service: 'nats', phases: () => [{ kind: 'refuse' }] },
+    holds: ['requests-coded', 'recovers', 'sync-resumes'],
+  },
+  {
+    name: 'worker-sigkill',
+    fault: { kind: 'signal', role: 'worker', signal: 'SIGKILL' },
+    holds: ['jobs-terminal', 'jobs-once', 'requests-coded'],
+  },
+  {
+    name: 'worker-sigterm',
+    fault: { kind: 'signal', role: 'worker', signal: 'SIGTERM' },
+    holds: ['role-exits', 'jobs-terminal', 'jobs-once'],
+  },
+  {
+    name: 'web-sigterm',
+    fault: { kind: 'signal', role: 'web', signal: 'SIGTERM' },
+    holds: ['requests-ok', 'role-exits'],
+  },
+];
+
+export const DRILL_NAMES: readonly DrillName[] = DRILLS.map((drill) => drill.name);
+
+/** The drill named `name`, or `undefined`: the caller refuses with the list. */
+export const drillNamed = (name: string): Drill | undefined =>
+  DRILLS.find((drill) => drill.name === name);
+
+/** The roles a drill's fleet runs: a sync client needs the sync node it dials. */
+export const drillRoles = (drill: Drill): readonly DrillRole[] =>
+  drill.holds.includes('sync-resumes') ? ['web', 'worker', 'sync'] : ['web', 'worker'];
+
+/** The service a drill needs running, when it needs one beyond Postgres. */
+export const drillService = (drill: Drill): DrillService | undefined =>
+  drill.fault.kind === 'service' ? drill.fault.service : undefined;

package/src/e2e-a11y-run.ts

@@ -0,0 +1,189 @@
+// One test's accessibility audit, for `e2eTest` and a raw tab (`e2e-a11y-tabs.ts`) alike: every
+// settled navigation and the test's end read the tree and the probe, findings no reasoned `allow`
+// covers are kept, and the test fails once with every element named. Rules: `e2e-a11y.ts`.
+// `X_E2E_A11Y_VIOLATION` is registered in `errors.ts`; its constructors live here.
+
+import { renderCauseValue, renderFixLiteral, UltimateError } from '@ultimat3/core';
+import { navigatedAway } from './cdp-e2e-page';
+import type { A11yFinding } from './e2e-a11y';
+import { findingKey, probeExpression, probeFindings, ruleFor, treeFinding } from './e2e-a11y';
+import type { E2eBrowserPage } from './e2e-page';
+// Bare: the title `X_E2E_A11Y_VIOLATION` renders with is registered there.
+import './errors';
+
+/** One deliberate exception, and why. `selector` is CSS, matched by the page against the element. */
+export interface A11yAllow {
+  readonly role: string;
+  readonly selector: string;
+  readonly because: string;
+}
+
+/** What an `e2eTest` may say about its audit. There is no switch: only reasoned exceptions. */
+export interface A11yOptions {
+  readonly allow?: readonly A11yAllow[] | undefined;
+}
+
+const ALLOW_FIX =
+  "e2eTest(name, body, { a11y: { allow: [{ role: 'button', selector: '#close', because: 'why this element is exempt' }] } })";
+
+/** Who audited the page — so the fix names the place THAT test can say `allow`. */
+export type A11yAuditor = 'e2eTest' | 'tab';
+
+/** A page in this test failed the audit. The cause lists every element, deduplicated. */
+export class E2eA11yViolationError extends UltimateError {
+  constructor(findings: readonly A11yFinding[], auditor: A11yAuditor = 'e2eTest') {
+    const listed = findings
+      .map((f) => `${f.rule} ${f.role} ${renderCauseValue(f.html)} at ${renderCauseValue(f.url)}`)
+      .join('; ');
+    const role = renderFixLiteral(findings[0]?.role, "'<role>'");
+    const entry = `[{ role: ${role}, selector: '<css>', because: '<why>' }]`;
+    super({
+      code: 'X_E2E_A11Y_VIOLATION',
+      cause: `${String(findings.length)} element(s) a screen reader cannot use — name each one (visible text, aria-label, <label for>, alt; alt="" for a decorative image; a <title>, <html lang>, nothing focusable under aria-hidden), or allow it with a reason: ${listed}`,
+      fix:
+        auditor === 'tab'
+          ? `allowA11y(${entry}) — in the test, before the navigation that lands on it`
+          : `e2eTest(name, body, { a11y: { allow: ${entry} } })`,
+      meta: { findings: findings.map(({ matches: _, ...told }) => told) },
+    });
+  }
+}
+
+/** An `allow` entry with no reason: an exception nobody can review is the global switch again. */
+export class E2eA11yAllowUnreasonedError extends UltimateError {
+  constructor(entry: unknown) {
+    super({
+      code: 'X_E2E_A11Y_VIOLATION',
+      cause: `an a11y.allow entry has no role, selector or non-blank because: ${renderCauseValue(entry)}`,
+      fix: ALLOW_FIX,
+    });
+  }
+}
+
+/** The page port cannot read the tree. Never a silent skip: that would pass every page. */
+export class E2eA11yUnavailableError extends UltimateError {
+  constructor() {
+    super({
+      code: 'X_TEST_FIXTURE_UNAVAILABLE',
+      cause:
+        'the page handed to installE2eDriver({ page }) has no accessibilityTree(), so no e2eTest can be audited — implement it on that E2eBrowserPage, or forward it from the wrapper; cdpE2eTab (packages/testing/src/cdp-e2e-page.ts) has one',
+      fix: 'accessibilityTree: (request) => tab.accessibilityTree(request)',
+    });
+  }
+}
+
+const filled = (text: unknown): boolean => typeof text === 'string' && text.trim() !== '';
+
+/** Every entry reasoned, or the test is refused before its body runs. */
+export const checkAllow = (options: A11yOptions | undefined): readonly A11yAllow[] => {
+  const allow = options?.allow ?? [];
+  for (const entry of allow) {
+    if (!filled(entry.role) || !filled(entry.selector) || !filled(entry.because)) {
+      throw new E2eA11yAllowUnreasonedError(entry);
+    }
+  }
+  return allow;
+};
+
+const allowed = (finding: A11yFinding, allow: readonly A11yAllow[]): boolean =>
+  allow.some((entry) => entry.role === finding.role && finding.matches.includes(entry.selector));
+
+/** The tree and the probe of the page as it is now: one round trip each, plus one per finding. */
+const readPage = async (
+  page: E2eBrowserPage,
+  selectors: readonly string[],
+): Promise<readonly A11yFinding[]> => {
+  if (page.accessibilityTree === undefined) throw new E2eA11yUnavailableError();
+  const url = page.url();
+  // A tab nothing navigated (`about:blank`) is no app's page: it has no title and no lang to give.
+  if (!/^https?:/.test(url)) return [];
+  const probed = probeFindings(await page.evaluate(probeExpression(selectors)), url);
+  if (probed === undefined) return [];
+  const nodes = await page.accessibilityTree({
+    describe: (node) => ruleFor(node) !== undefined,
+    selectors,
+  });
+  const fromTree = nodes.filter((node) => ruleFor(node) !== undefined);
+  return [...fromTree.map((node) => treeFinding(node, url)), ...probed];
+};
+
+export interface A11yRun {
+  /** Audit the page now; findings are kept, never thrown here. */
+  check(): Promise<void>;
+  /** Throw `X_E2E_A11Y_VIOLATION` if anything was kept. */
+  verdict(): void;
+}
+
+/** One test's findings over any number of pages: each `check(page)` reads one, `verdict` tells all. */
+export interface A11yPagesRun {
+  check(page: E2eBrowserPage): Promise<void>;
+  /** More reasoned exceptions for THIS run: they cover the reads after this call. */
+  allow(entries: readonly A11yAllow[]): void;
+  verdict(): void;
+}
+
+/**
+ * The pages an `e2eTest` runner audits itself, with its test's `allow`, until the test ends. The
+ * raw-tab audit (`e2e-a11y-tabs.ts`) stands down for these, so one navigation is never judged twice
+ * — once with the test's reasoned exceptions and once without them.
+ */
+const claimed = new Set<E2eBrowserPage>();
+
+export const claimedThisTest = (page: E2eBrowserPage): boolean => claimed.has(page);
+
+/** At a test's end: every page is the raw-tab audit's again. */
+export const releaseClaims = (): void => claimed.clear();
+
+/**
+ * Findings across pages, for one test. `reported` is the SUITE's set: a finding another test
+ * already failed on is not told twice, so a shared header with no name fails one test rather than
+ * every one.
+ */
+export function a11yPagesRun(
+  given: readonly A11yAllow[],
+  reported: Set<string>,
+  auditor: A11yAuditor = 'e2eTest',
+): A11yPagesRun {
+  const allow = [...given];
+  let selectors = [...new Set(allow.map((entry) => entry.selector))];
+  const kept = new Map<string, A11yFinding>();
+  return {
+    async check(page) {
+      let findings: readonly A11yFinding[];
+      try {
+        findings = await readPage(page, selectors);
+      } catch (error) {
+        // A document that committed under the read is "not this document": read the new one once.
+        if (!navigatedAway(error)) throw error;
+        findings = await readPage(page, selectors);
+      }
+      for (const finding of findings) {
+        const key = findingKey(finding);
+        if (allowed(finding, allow) || reported.has(key)) continue;
+        kept.set(key, finding);
+      }
+    },
+    allow(entries) {
+      allow.push(...entries);
+      selectors = [...new Set(allow.map((entry) => entry.selector))];
+    },
+    verdict() {
+      if (kept.size === 0) return;
+      for (const key of kept.keys()) reported.add(key);
+      const told = [...kept.values()];
+      kept.clear();
+      throw new E2eA11yViolationError(told, auditor);
+    },
+  };
+}
+
+/** One `e2eTest`'s audit of the one page it drives — claimed from the raw-tab audit until it ends. */
+export function startA11yRun(
+  page: E2eBrowserPage,
+  allow: readonly A11yAllow[],
+  reported: Set<string>,
+): A11yRun {
+  claimed.add(page);
+  const run = a11yPagesRun(allow, reported);
+  return { check: () => run.check(page), verdict: () => run.verdict() };
+}

package/src/e2e-a11y-tabs.ts

@@ -0,0 +1,113 @@
+// The audit of every RAW tab — a `session.newTab()` a suite drives itself, outside `e2eTest`.
+// Every settled `goto`/`reload` reads the page, every tab the test drove is read once more at its
+// end, and the findings fail that test from the preload's one `afterEach`. No suite opts in: the
+// tab reports here because `cdp-e2e-session.ts` built it. The rules and the read are `e2e-a11y-run`'s.
+
+import { afterEach } from 'bun:test';
+import type { A11yAllow, A11yPagesRun } from './e2e-a11y-run';
+import { a11yPagesRun, checkAllow, claimedThisTest, releaseClaims } from './e2e-a11y-run';
+import type { E2eBrowserPage } from './e2e-page';
+
+/** What the session tells this file about one tab it built. */
+export interface AuditedTab {
+  /** A settled navigation: read the document now, before the next one replaces it. */
+  navigated(): Promise<void>;
+  /** The test called the tab — it is read again at the test's end, so a dialog it opened counts. */
+  used(): void;
+  /** Closed by the test: nothing left to read at its end, and Chrome may still list the target. */
+  closed(): void;
+}
+
+interface Watched {
+  readonly tab: E2eBrowserPage;
+  closed: boolean;
+  /** False once the tab or its whole browser is gone: there is no page left to read. */
+  readonly alive: () => Promise<boolean>;
+}
+
+/** The tabs the running test (or the `beforeAll` before it) called. Cleared at each test's end. */
+const used = new Set<Watched>();
+/** The process' set: a finding one test failed on is not told again by the next. */
+const reported = new Set<string>();
+let current: A11yPagesRun | undefined;
+let installed = false;
+
+const run = (): A11yPagesRun => {
+  current ??= a11yPagesRun([], reported, 'tab');
+  return current;
+};
+
+/** Register a tab the session just built. Its `goto` calls `navigated`, its every call `used`. */
+export function auditTab(tab: E2eBrowserPage, alive: () => Promise<boolean>): AuditedTab {
+  const entry: Watched = { tab, alive, closed: false };
+  return {
+    async navigated() {
+      if (claimedThisTest(tab)) return;
+      await run().check(tab);
+      // No preload to fail the test at its end: fail it HERE, at the navigation, rather than
+      // keeping findings nothing will ever tell — a silent skip would pass every page.
+      if (!installed) endRun();
+    },
+    used() {
+      used.add(entry);
+    },
+    closed() {
+      entry.closed = true;
+    },
+  };
+}
+
+/**
+ * The raw-tab test's reasoned exceptions — `e2eTest`'s `{ a11y: { allow } }`, for a test with no
+ * options slot. Each entry needs a non-blank `because`, it covers the reads after the call, and it
+ * ends with the test. Call it first in the test body, before the navigation that lands on it.
+ */
+export function allowA11y(entries: readonly A11yAllow[]): void {
+  run().allow(checkAllow({ allow: entries }));
+}
+
+const endRun = (): void => {
+  const ending = current;
+  current = undefined;
+  ending?.verdict();
+};
+
+/**
+ * The end of one test: every tab it called is read as the test left it, and everything kept since
+ * the last test fails THIS one. A tab whose browser closed has no page left to read; what its
+ * navigations found is still told.
+ */
+export async function endTabA11y(): Promise<void> {
+  const touched = [...used];
+  try {
+    for (const entry of touched) {
+      if (claimedThisTest(entry.tab)) continue;
+      if (entry.closed || !(await entry.alive())) continue;
+      await run().check(entry.tab);
+    }
+    endRun();
+  } finally {
+    // After the reads, which call the tab too: the next test starts with nothing it touched.
+    used.clear();
+    current = undefined;
+    releaseClaims();
+  }
+}
+
+/**
+ * The longest one test's end may take: three reads per tab, a handful of tabs. A literal, not
+ * `DEFAULT_CDP_TIMEOUT_MS` times a count — `cdp-browser.ts` reaches this file through the session,
+ * and the import back would be a cycle. Measured ends are tens of milliseconds.
+ */
+export const TAB_A11Y_END_MS = 120_000;
+
+/**
+ * Called by the preloads, once per process. In a preload, `afterEach` runs after every test of
+ * every file — the only place a hook reaches a suite that wrote none (measured on Bun 1.4.4: one
+ * registered from a library call inside `beforeAll` ran once, not per test).
+ */
+export function installTabA11yAudit(): void {
+  if (installed) return;
+  installed = true;
+  afterEach(endTabA11y, TAB_A11Y_END_MS);
+}

package/src/e2e-a11y.ts

@@ -0,0 +1,153 @@
+// The accessibility audit's RULES: which of the browser's own tree nodes a screen reader cannot
+// name, the one in-page probe for what the tree prunes (`<html lang>`, focus under `aria-hidden`),
+// and how a finding is told. No engine and no heuristics: every rule is a fact the browser already
+// computed. When it runs and how it fails a test is `e2e-a11y-run.ts`.
+
+import type { AxTreeNode } from './ax-node';
+
+/**
+ * Roles whose node needs a non-blank name, keyed on the browser's spelling AND its `role.type`
+ * (probed on Chrome, 2026-11-02): an ARIA `role` and Chrome's `internalRole` never share a key,
+ * so an author's `role="Iframe"` is not the browser's `Iframe`. An image is `image`, never `img`.
+ */
+export const NAMED_ROLES: Readonly<Record<'role' | 'internalRole', readonly string[]>> = {
+  role: [
+    'button',
+    'link',
+    'textbox',
+    'searchbox',
+    'combobox',
+    'checkbox',
+    'radio',
+    'switch',
+    'slider',
+    'spinbutton',
+    'tab',
+    'menuitem',
+    'image',
+    'heading',
+  ],
+  internalRole: ['Iframe', 'DisclosureTriangle'],
+};
+
+/** The document itself: an empty name is a page with no `<title>`. */
+export const DOCUMENT_ROLE = 'RootWebArea';
+
+/** What a probe finding under `aria-hidden` is called: the tree pruned it, so it has no role. */
+export const FOCUSABLE_ROLE = 'focusable';
+
+export type A11yRule = 'name' | 'title' | 'lang' | 'aria-hidden-focus';
+
+/** One element that fails, as the error tells it and as an `allow` entry matches it. */
+export interface A11yFinding {
+  readonly rule: A11yRule;
+  readonly role: string;
+  /** `outerHTML`, at most `HTML_BOUND` characters. */
+  readonly html: string;
+  readonly url: string;
+  /** The `allow` selectors this element matches — read in the page, never re-derived here. */
+  readonly matches: readonly string[];
+}
+
+/** A finding is read by a person in a terminal: the opening tag is what names the element. */
+export const HTML_BOUND = 120;
+
+const blank = (text: string): boolean => text.trim() === '';
+
+/** The rule a tree node breaks, or undefined. Only an UNIGNORED node is in the reader's tree. */
+export const ruleFor = (node: AxTreeNode): A11yRule | undefined => {
+  if (node.ignored || !blank(node.name)) return undefined;
+  if (node.roleType === 'internalRole' && node.role === DOCUMENT_ROLE) return 'title';
+  const named =
+    node.roleType === 'role'
+      ? NAMED_ROLES.role
+      : node.roleType === 'internalRole'
+        ? NAMED_ROLES.internalRole
+        : [];
+  return named.includes(node.role) ? 'name' : undefined;
+};
+
+/** Every node of a tree that breaks a rule, in the browser's order. */
+export const auditTree = (nodes: readonly AxTreeNode[]): readonly AxTreeNode[] =>
+  nodes.filter((node) => ruleFor(node) !== undefined);
+
+/**
+ * What the tree cannot say, asked in ONE evaluate. Answers JSON text. Focusable means reachable by
+ * Tab: rendered, not disabled, not `inert`, not `tabindex="-1"`.
+ */
+export const probeExpression = (selectors: readonly string[]): string => `(() => {
+  const selectors = ${JSON.stringify(selectors)};
+  const describe = (el) => ({
+    html: (el === document.documentElement
+      ? el.outerHTML.slice(0, el.outerHTML.indexOf('>') + 1)
+      : el.outerHTML).slice(0, ${String(HTML_BOUND)}),
+    matches: selectors.filter((s) => { try { return el.matches(s); } catch { return false; } }),
+  });
+  const root = document.documentElement;
+  const focusable = 'a[href], button, input:not([type="hidden"]), select, textarea, iframe, summary, [tabindex], [contenteditable=""], [contenteditable="true"], audio[controls], video[controls]';
+  const hidden = [...document.querySelectorAll('[aria-hidden="true"]')]
+    .flatMap((host) => [host, ...host.querySelectorAll(focusable)])
+    .filter((el, at, all) => all.indexOf(el) === at && el.matches(focusable))
+    .filter((el) => !el.matches(':disabled') && el.getAttribute('tabindex') !== '-1')
+    .filter((el) => el.closest('[inert]') === null && el.getClientRects().length > 0)
+    .map(describe);
+  return JSON.stringify({
+    html: document.contentType === 'text/html' || document.contentType === 'application/xhtml+xml',
+    lang: (root?.getAttribute('lang') ?? '').trim() !== '',
+    root: root === null ? { html: '', matches: [] } : describe(root),
+    hidden,
+  });
+})()`;
+
+interface Described {
+  readonly html: string;
+  readonly matches: readonly string[];
+}
+
+const described = (raw: unknown): Described => {
+  const value = typeof raw === 'object' && raw !== null ? (raw as Record<string, unknown>) : {};
+  const html = value['html'];
+  const matches = value['matches'];
+  return {
+    html: typeof html === 'string' ? html.slice(0, HTML_BOUND) : '',
+    matches: Array.isArray(matches)
+      ? matches.filter((m): m is string => typeof m === 'string')
+      : [],
+  };
+};
+
+/**
+ * The probe's answer as findings. `undefined` is a document that is not markup — JSON, an image,
+ * a PDF the browser wrapped in its own viewer — which no rule here is about. An answer that is not
+ * the probe's shape finds nothing.
+ */
+export const probeFindings = (raw: unknown, url: string): readonly A11yFinding[] | undefined => {
+  const decoded: unknown = typeof raw === 'string' ? JSON.parse(raw) : raw;
+  if (typeof decoded !== 'object' || decoded === null) return [];
+  const answer = decoded as Record<string, unknown>;
+  if (answer['html'] === false) return undefined;
+  const hidden = Array.isArray(answer['hidden']) ? answer['hidden'] : [];
+  const out: A11yFinding[] = hidden.map((el) => ({
+    rule: 'aria-hidden-focus',
+    role: FOCUSABLE_ROLE,
+    url,
+    ...described(el),
+  }));
+  if (answer['lang'] === false) {
+    out.unshift({ rule: 'lang', role: DOCUMENT_ROLE, url, ...described(answer['root']) });
+  }
+  return out;
+};
+
+/** A tree node that broke a rule, as a finding. */
+export const treeFinding = (node: AxTreeNode, url: string): A11yFinding => ({
+  rule: ruleFor(node) ?? 'name',
+  role: node.role,
+  html: (node.html ?? '').slice(0, HTML_BOUND),
+  url,
+  matches: node.matches ?? [],
+});
+
+/** The four facts a finding is deduplicated on: a shared header reports once per URL. */
+export const findingKey = (finding: A11yFinding): string =>
+  JSON.stringify([finding.rule, finding.role, finding.html, finding.url]);