@ultimat3/testing 29.4.0 → 30.1.0

package/src/plan-sweep-report.ts

@@ -0,0 +1,84 @@
+// The plan and scale sweeps, as `x exercise` reports them: one coded finding per statement no index
+// serves (every primitive that sent it named) and per shape that grows with the rows, each with the
+// edit that ends it — the `indexes:` entry read off the entity, or the `preload` — and one line each.
+
+import { renderCauseValue, renderFixLiteral, renderFixShellArg } from '@ultimat3/core';
+import type { ExerciseRecord } from './exercise-report';
+import type { PlanFinding } from './plan-sweep-fix';
+
+export interface SweepFinding {
+  readonly code: 'X_QUERY_UNINDEXED' | 'X_QUERY_SORT_UNSERVED' | 'X_QUERY_SCALES_WITH_ROWS';
+  readonly cause: string;
+  readonly fix: string;
+  /** The primitive, by kind and name: the registry records no declaring file. */
+  readonly at: string;
+}
+
+const primitive = (record: ExerciseRecord): string => `${record.kind} ${record.name}`;
+
+const STATEMENT_CHARS = 160;
+const excerpt = (statement: string): string =>
+  statement.length <= STATEMENT_CHARS ? statement : `${statement.slice(0, STATEMENT_CHARS)}…`;
+
+/** `indexes: [{ on: ['orgId', 'authorId'] }]` — the line to paste into the entity. */
+const indexLine = (finding: PlanFinding): string =>
+  `indexes: [{ on: [${finding.index.map((p) => `'${p}'`).join(', ')}] }]`;
+
+function planFinding(finding: PlanFinding, senders: readonly ExerciseRecord[]): SweepFinding {
+  const by = senders.map(primitive).join(', ');
+  const entity = renderFixLiteral(finding.entity, '<entity>');
+  const name = renderFixShellArg(`${finding.table}-${finding.index.join('-')}-index`, '<name>');
+  const what =
+    finding.code === 'X_QUERY_SORT_UNSERVED'
+      ? `sorts its rows to answer a limited read (${finding.node} under Limit)`
+      : `reads ${finding.table} whole (${finding.node})`;
+  const scan =
+    finding.code === 'X_QUERY_UNINDEXED'
+      ? `; or scan: '<why it stays small>' in that entity()`
+      : '';
+  return {
+    code: finding.code,
+    cause: `${by} sent ${renderCauseValue(excerpt(finding.statement))}, which ${what}: no index on ${finding.table} serves it, so it slows with every row the table gains`,
+    fix: `x db gen ${name}   # after ${indexLine(finding)} in entity(${entity})${scan}`,
+    at: senders[0] === undefined ? finding.entity : primitive(senders[0]),
+  };
+}
+
+/** One finding per statement and red node, naming every primitive that sent it. */
+export function planSweepFindings(records: readonly ExerciseRecord[]): readonly SweepFinding[] {
+  const groups = new Map<string, { finding: PlanFinding; senders: ExerciseRecord[] }>();
+  for (const record of records) {
+    for (const finding of record.plans?.findings ?? []) {
+      const key = `${finding.code}\u0000${finding.table}\u0000${finding.statement}`;
+      const group = groups.get(key) ?? { finding, senders: [] };
+      group.senders.push(record);
+      groups.set(key, group);
+    }
+  }
+  const plans = [...groups.values()].map(({ finding, senders }) => planFinding(finding, senders));
+  const scale = records.flatMap((record): SweepFinding[] => {
+    if (record.scale?.verdict !== 'grows') return [];
+    const name = renderFixShellArg(record.name, '<primitive>');
+    return record.scale.shapes.map((shape) => ({
+      code: 'X_QUERY_SCALES_WITH_ROWS',
+      cause: `${primitive(record)} sent ${renderCauseValue(shape.fingerprint)} ${shape.small}× at 2 rows a table and ${shape.large}× at 8: one statement per row, a loop no test named`,
+      fix: `x exercise ${name} --json   # after preload() of the relation the loop reads, or expectedQueryLoop('<why>', fn) around a deliberate loop`,
+      at: primitive(record),
+    }));
+  });
+  return [...plans, ...scale];
+}
+
+/** One line per red: `action listPosts · X_QUERY_UNINDEXED posts on [orgId, authorId]`. */
+export function planSweepLines(records: readonly ExerciseRecord[]): readonly string[] {
+  return records.flatMap((record) => [
+    ...(record.plans?.findings ?? []).map(
+      (finding) =>
+        `${primitive(record)} · ${finding.code} ${finding.table} on [${finding.index.join(', ')}]`,
+    ),
+    ...(record.scale?.verdict === 'grows' ? record.scale.shapes : []).map(
+      (shape) =>
+        `${primitive(record)} · X_QUERY_SCALES_WITH_ROWS ${shape.fingerprint} ${shape.small}→${shape.large}`,
+    ),
+  ]);
+}

package/src/plan-sweep.ts

@@ -0,0 +1,148 @@
+// The plan sweep: every distinct statement the exercise pass sent whose first relation is an app
+// table, planned on the migrated database with sequential scans, bitmap scans and sorts disabled,
+// judged by `plan-oracle.ts`, each red node named as the `indexes:` entry that answers it.
+// Read-only: `PREPARE` in a read-only transaction whose settings die with it, then `DEALLOCATE`.
+
+import { renderThrowable, UltimateError } from '@ultimat3/core';
+import type { DbClient } from '@ultimat3/db';
+import { isReservable, raw, sql, withReadTransaction } from '@ultimat3/db';
+import './errors';
+import type { PlanTableColumns } from './plan-oracle';
+import { judgePlan } from './plan-oracle';
+import type { PlanFinding } from './plan-sweep-fix';
+import { planFindings } from './plan-sweep-fix';
+import type { SeedEntity } from './seed-graph-shape';
+
+/** What the pass's room kept of one statement text: who sent it, under which scan reason. */
+export interface SentStatement {
+  readonly primitives: ReadonlySet<string>;
+  /** The `expectedSeqScan` reason in force when it was sent. */
+  readonly scan?: string;
+}
+
+export interface PlanExempt {
+  readonly statement: string;
+  readonly reason: string;
+}
+
+/** One primitive's statements, planned. Only `findings` is red. */
+export interface PlanProof {
+  readonly planned: number;
+  readonly findings: readonly PlanFinding[];
+  /** A table that declared `scan`, or a statement under `expectedSeqScan`: why it may scan. */
+  readonly exempt: readonly PlanExempt[];
+  /** Generic planning refused it (an untyped parameter): listed and counted, never red. */
+  readonly unplannable: readonly PlanExempt[];
+}
+
+/** The server cannot hand back a generic plan: no statement was judged, which is never a pass. */
+export class QueryPlanUnavailableError extends UltimateError {
+  constructor(version: string) {
+    super({
+      code: 'X_QUERY_PLAN_UNAVAILABLE',
+      cause: `the gate's database answered server_version_num ${version}: below Postgres 12 there is no plan_cache_mode, so the plan sweep cannot read a generic plan and no statement was judged`,
+      fix: 'DATABASE_URL= x verify --only exercise   # the embedded database answers every plan',
+      meta: { version },
+    });
+  }
+}
+
+/** The planner's choices the sweep removes: what remains is what the schema can serve. */
+const SETTINGS = {
+  enable_seqscan: 'off',
+  enable_bitmapscan: 'off',
+  enable_sort: 'off',
+  plan_cache_mode: 'force_generic_plan',
+} as const;
+const PREPARED = 'x_plan_sweep';
+const FIRST_RELATION = /\b(?:from|into|update|join)\s+(?:"?\w+"?\.)?"?([A-Za-z_][\w$]*)"?/i;
+
+/** `$1` … `$n`: the highest one is how many nulls `execute` passes. */
+const parameterCount = (statement: string): number =>
+  Math.max(0, ...[...statement.matchAll(/\$(\d+)/g)].map((match) => Number(match[1])));
+
+interface Planned {
+  readonly plan?: unknown;
+  readonly refused?: string;
+}
+
+async function explain(client: DbClient, statement: string): Promise<Planned> {
+  const connection = isReservable(client) ? await client.reserve() : undefined;
+  const on = connection ?? client;
+  let prepared = false;
+  try {
+    const n = parameterCount(statement);
+    const args = n === 0 ? '' : `(${Array.from({ length: n }, () => 'null').join(', ')})`;
+    const rows = await withReadTransaction(
+      async (tx) => {
+        await tx.execute(raw(`prepare ${PREPARED} as ${statement}`));
+        prepared = true;
+        return tx.query<Record<string, unknown>>(
+          raw(`explain (format json) execute ${PREPARED}${args}`),
+        );
+      },
+      { settings: SETTINGS, client: on },
+    );
+    return { plan: rows[0]?.['QUERY PLAN'] };
+  } catch (error) {
+    return { refused: renderThrowable(error) };
+  } finally {
+    // A prepared statement outlives the transaction: left, the connection's next sweep collides.
+    if (prepared) await on.execute(raw(`deallocate ${PREPARED}`));
+    connection?.release();
+  }
+}
+
+interface ProofBuilder {
+  planned: number;
+  readonly findings: PlanFinding[];
+  readonly exempt: PlanExempt[];
+  readonly unplannable: PlanExempt[];
+}
+
+/** Plan every statement `sent` holds, once each, and hand each primitive the verdicts of its own. */
+export async function sweepPlans(
+  client: DbClient,
+  sent: ReadonlyMap<string, SentStatement>,
+  entities: readonly SeedEntity[],
+): Promise<ReadonlyMap<string, PlanProof>> {
+  const tables = entities.filter((entity) => entity.$describe().view === undefined);
+  const byTable = new Map(tables.map((entity) => [entity.$table, entity]));
+  const judged: PlanTableColumns = new Map(
+    tables
+      .filter((entity) => entity.$describe().scan === undefined)
+      .map((entity) => [entity.$table, new Set(entity.$describe().columns.map((c) => c.column))]),
+  );
+  const version = await client.one<{ readonly v: string }>(
+    sql`select current_setting('server_version_num') as v`,
+  );
+  if (Number(version?.v ?? 0) < 120_000) throw new QueryPlanUnavailableError(version?.v ?? '?');
+
+  const proofs = new Map<string, ProofBuilder>();
+  const proofOf = (name: string): ProofBuilder => {
+    const found = proofs.get(name);
+    if (found !== undefined) return found;
+    const made: ProofBuilder = { planned: 0, findings: [], exempt: [], unplannable: [] };
+    proofs.set(name, made);
+    return made;
+  };
+  for (const [statement, { primitives, scan }] of sent) {
+    const table = FIRST_RELATION.exec(statement)?.[1];
+    const entity = table === undefined ? undefined : byTable.get(table);
+    if (entity === undefined) continue;
+    const declared = entity.$describe().scan;
+    const exemptBy = scan ?? declared;
+    const planned = exemptBy === undefined ? await explain(client, statement) : {};
+    for (const name of primitives) {
+      const proof = proofOf(name);
+      proof.planned += 1;
+      if (exemptBy !== undefined) proof.exempt.push({ statement, reason: exemptBy });
+      else if (planned.refused !== undefined) {
+        proof.unplannable.push({ statement, reason: planned.refused });
+      } else {
+        proof.findings.push(...planFindings(statement, judgePlan(planned.plan, judged), byTable));
+      }
+    }
+  }
+  return proofs;
+}

package/src/preload.ts

@@ -7,11 +7,13 @@
 
 // A green run prints the reporter and nothing else: the process logger's lines go to a sink.
 import './quiet-logs';
-import { installDeterminism } from './determinism';
+import { captureDeterminism, installDeterminism, restoreCapturedDeterminism } from './determinism';
 import { registerFrameworkFixtures } from './framework-fixtures';
 import './matchers';
+import { installTabA11yAudit } from './e2e-a11y-tabs';
 import { onFileBoundary } from './file-boundary';
 import { ISOLATED_ENV, releasePluginsAfterIsolatedFile } from './isolated-plugins';
+import { installModuleMockBoundary } from './module-mock-boundary';
 import { installPerTestReset } from './per-test-reset';
 import { installRegistryLeakGuard } from './registry-leak-guard';
 import { sealNetwork } from './sealed-network';
@@ -32,6 +34,11 @@ installDeterminism({
 
 registerFrameworkFixtures();
 
+// And the CLOCK, per FILE: the frozen instant is one process', so a file that advanced it and never
+// put it back handed every later file on the worker a moved clock (`clock-file-boundary.test.ts`).
+const installedClock = captureDeterminism();
+onFileBoundary(() => restoreCapturedDeterminism(installedClock));
+
 // Inside a test process the machine's test slots are already accounted for — by the `x test` /
 // `x verify` that spawned it, or by nobody when `bun test` ran bare. An `x test` a test runs in
 // process (the framework's own suites do) must never lease from the real pool: it would wait on
@@ -46,6 +53,14 @@ installRegistryLeakGuard();
 // resumed the next test's waiting run (`per-test-reset.ts`).
 installPerTestReset();
 
+// And every `mock.module`: Bun keeps one past `mock.restore()` and past the file, so the next file
+// on a shared worker read the fake. Put back at the boundary (`module-mock-boundary.ts`).
+installModuleMockBoundary();
+
+// And every browser tab a suite drives itself is audited like an `e2eTest`'s page: its findings
+// fail the test from this one `afterEach`, so no suite has a line to forget (`e2e-a11y-tabs.ts`).
+installTabA11yAudit();
+
 // A shared worker only (an isolated file is a fresh registry anyway): the app's
 // `defineApi({ pathStyle })` evaluates once per worker, in whichever file first imports it, and
 // must not be refused because an EARLIER file derived action paths under the default style.
@@ -55,13 +70,18 @@ installPerTestReset();
 // was red whenever another file calling that action ran first. Each file starts with full buckets,
 // the store back to one process' memory, as a file run alone would have it.
 //
+// And the METER store, for the same reason one period longer: a file that drew a seeded org's
+// daily allowance left it drawn, so the next file's "the 101st draft is refused" test was red or
+// green by file order (`meter-file-boundary.test.ts`).
+//
 // And the LIFECYCLE, which is one process' too: a drain is terminal, so a file that drained the
 // process — or that emitted a real SIGINT at it, as a signal test does — left every later file on
 // the worker answering 503 X_DRAINING for a reason nothing in that file explains. Each file starts
 // from a live lifecycle, as a file run alone would have it.
 if (Bun.env[ISOLATED_ENV] !== '1') {
-  const { forgetHandedOutActionPaths } = await import('@ultimat3/action');
+  const { forgetHandedOutActionPaths, resetMeterStore } = await import('@ultimat3/action');
   onFileBoundary(forgetHandedOutActionPaths);
+  onFileBoundary(resetMeterStore);
   const { resetRateLimitStore } = await import('@ultimat3/http');
   onFileBoundary(resetRateLimitStore);
   const { resetLifecycle } = await import('@ultimat3/core');
@@ -81,10 +101,10 @@ releasePluginsAfterIsolatedFile();
 // Every `.tsx` compiles with the framework's JSX factory from the first file on, in every test
 // process — an app root or any workspace below it. Bun's own compile of a `.tsx` is wrong on every
 // Bun (`@ultimat3/render`'s `module-loader.ts`): through 1.4.2 a cached `React.createElement`
-// (`React is not defined`, 18 notificado.co tests), from 1.4.3 a link-time `SyntaxError: Export
+// (`React is not defined`, 18 of one adopter's tests), from 1.4.3 a link-time `SyntaxError: Export
 // named 'jsxDEV' not found` in any file that merely imports a component (issue #883). It was
 // installed only where `app.config.ts` sat beside the run, so a workspace package's own tests
-// needed a hand-written preload (castlefight.online, ai-maxxing).
+// needed a hand-written preload (one adopter, and another).
 const { installRenderLoader } = await import('@ultimat3/render/server');
 installRenderLoader();
 

package/src/registry-snapshot.ts

@@ -139,7 +139,7 @@ function restoreCatalogs(snapshot: readonly (readonly [Locale, Catalog])[]): voi
  * declared, plus what this file inherited. Since 22.7 a worker runs many files in one module
  * registry, so a module a file imports evaluates ONCE — a later file that resets the permission
  * set at module scope would otherwise hand every file after it a registry missing declarations no
- * cached module will ever make again (measured on notificado.co: "admin:read is not in the
+ * cached module will ever make again (measured on one adopter's app: "admin:read is not in the
  * permission set (8 known)"). Newer wins on a conflict, so a file's own redefinition still stands
  * for that file.
  */

package/src/repro-stand-in.ts

@@ -0,0 +1,67 @@
+// Single responsibility: a value for every field a failure bundle masked. The bundle never holds a
+// secret, so a replay needs one that the schema accepts: the masked paths are filled from a seeded
+// `arbitrary()` value of the same schema (input), or from the column's own candidates (a row).
+
+import { REDACTED, uuidV7 } from '@ultimat3/core';
+import type { EntityCore } from '@ultimat3/entity';
+import { arbitrary } from '@ultimat3/schema/sample';
+import { candidatesFor, type SeedColumn } from './seed-graph-values';
+
+/** The seed every stand-in draws from: the same bundle, the same replay. */
+const STAND_IN_SEED = 0x5eed;
+
+const isRecord = (value: unknown): value is Record<string, unknown> =>
+  typeof value === 'object' && value !== null && !Array.isArray(value);
+
+/** Every `REDACTED` leaf of `value` replaced by the leaf at the same place in `sample`. */
+function fill(value: unknown, sample: unknown): unknown {
+  if (value === REDACTED) return sample;
+  if (Array.isArray(value)) {
+    const items = Array.isArray(sample) ? sample : [];
+    return value.map((entry, index) => fill(entry, items[index] ?? items[0]));
+  }
+  if (!isRecord(value)) return value;
+  const out: Record<string, unknown> = {};
+  for (const [key, entry] of Object.entries(value)) {
+    Object.defineProperty(out, key, {
+      value: fill(entry, isRecord(sample) ? sample[key] : undefined),
+      enumerable: true,
+      writable: true,
+      configurable: true,
+    });
+  }
+  return out;
+}
+
+/** The input with every masked field replaced by a value `schema` accepts. */
+export function inputStandIn(schema: unknown, input: unknown, masked: readonly string[]): unknown {
+  if (masked.length === 0) return input;
+  // `arbitrary` reads the schema's IR; a schema without one yields `{}`, and the replay says so.
+  const sample = arbitrary(schema as Parameters<typeof arbitrary>[0], {
+    seed: STAND_IN_SEED,
+    run: 0,
+  });
+  return fill(input, sample);
+}
+
+/** The row with every masked column replaced by the first value that column stores. */
+export function rowStandIn(
+  entity: EntityCore<unknown>,
+  row: Readonly<Record<string, unknown>>,
+  masked: readonly string[],
+): Record<string, unknown> {
+  const out: Record<string, unknown> = { ...row };
+  const columns = entity.$columns as Readonly<Record<string, SeedColumn>>;
+  for (const [position, property] of masked.entries()) {
+    const column = columns[property];
+    if (column === undefined) continue;
+    const [first] = candidatesFor(property, column, {
+      ordinal: 1,
+      canary: '5eed',
+      position,
+      uuid: () => uuidV7(),
+    });
+    out[property] = first;
+  }
+  return out;
+}

package/src/repro.ts

@@ -0,0 +1,158 @@
+// `reproduce(bundle)` and `reproJob(runJobs, failure)` — what a test `x repro --write` generated
+// calls. Request: seed the rows the failing call read, freeze the clock at its instant, invoke as
+// its actor with its input (masked fields stood in for). Job: the stored input, the completed steps
+// replayed from their output, one drain. Each ANSWERS the outcome; the test asserts on it.
+
+import type { Actor, FailureBundle, FailureRead } from '@ultimat3/core';
+import {
+  agentActor,
+  anonymousActor,
+  ctxOf,
+  frozenClock,
+  isUltimateError,
+  renderThrowable,
+  serviceActor,
+  userActor,
+} from '@ultimat3/core';
+import type { Driver, EntityCore, RowWrite } from '@ultimat3/entity';
+import type { JobHandle } from '@ultimat3/jobs';
+import type { RunJobs } from './fixture-jobs';
+
+/** What a replay ended in. `failure` is `CODE: cause` (or the thrown value rendered), else `null`. */
+export interface ReproOutcome {
+  readonly code: string | null;
+  readonly failure: string | null;
+  /** A job's: the step whose record ended `failed`, `null` for a request or a body-level throw. */
+  readonly step: string | null;
+}
+
+/** A dead job, as `x repro <jobId>` read it: everything a replay needs and nothing it does not. */
+export interface JobFailure {
+  readonly jobId: string;
+  readonly name: string;
+  readonly input: unknown;
+  readonly masked: readonly string[];
+  /** Completed steps, in order, with the output each returned: replayed, never re-executed. */
+  readonly steps: readonly { readonly name: string; readonly output: unknown }[];
+  readonly code: string | null;
+  readonly step: string | null;
+}
+
+export interface ReproduceOptions {
+  /** The app's own driver (`@<app>/db`'s `driver`): captured rows go where the code reads. */
+  readonly driver?: Driver | undefined;
+}
+
+const outcomeOf = (error: unknown): ReproOutcome => ({
+  code: isUltimateError(error) ? error.code : 'X_INTERNAL',
+  failure: isUltimateError(error) ? `${error.code}: ${error.cause}` : renderThrowable(error),
+  step: null,
+});
+
+const PASSED: ReproOutcome = { code: null, failure: null, step: null };
+
+function actorFrom(captured: FailureBundle['actor']): Actor {
+  if (captured === null || captured.kind === 'anonymous') return anonymousActor();
+  const init = {
+    id: captured.id,
+    orgId: captured.orgId ?? undefined,
+    roles: captured.roles,
+    scopes: captured.scopes,
+    permissions: captured.permissions,
+  };
+  if (captured.kind === 'service') return serviceActor(init);
+  if (captured.kind === 'agent') return agentActor(init);
+  return userActor(init);
+}
+
+/** Each captured row written through its entity's repository, replay-safe (`onMatch: 'nothing'`). */
+async function seedReads(
+  reads: readonly FailureRead[],
+  driver: Driver,
+): Promise<readonly string[]> {
+  const { getEntity } = await import('@ultimat3/entity');
+  const { rowStandIn } = await import('./repro-stand-in');
+  const unknown: string[] = [];
+  for (const read of reads) {
+    const entity = getEntity(read.entity)?.core as EntityCore<unknown> | undefined;
+    if (entity === undefined) {
+      unknown.push(read.entity);
+      continue;
+    }
+    // `$parse` answers the entity's own row; the registry erased its type, the write restores it.
+    const row = entity.$parse(rowStandIn(entity, read.row, read.masked)) as RowWrite<unknown>;
+    await driver.repo(entity).upsertAll([row], {
+      onConflict: [...entity.$primaryKey] as never,
+      onMatch: 'nothing',
+    });
+  }
+  return unknown;
+}
+
+/**
+ * Replay one captured request. A bundle naming an action or query this process has not registered
+ * answers that as its failure rather than throwing: the written test is red with the reason.
+ */
+export async function reproduce(
+  bundle: FailureBundle,
+  options: ReproduceOptions = {},
+): Promise<ReproOutcome> {
+  if (options.driver !== undefined) {
+    options.driver.reset?.();
+    await seedReads(bundle.reads, options.driver);
+  }
+  const ctx = ctxOf({ actor: actorFrom(bundle.actor), clock: frozenClock(bundle.at) });
+  const { inputStandIn } = await import('./repro-stand-in');
+  try {
+    if (bundle.primitive === 'action') {
+      const { invoke, listActions } = await import('@ultimat3/action');
+      const target = listActions().find((candidate) => candidate.name === bundle.name);
+      if (target === undefined) return unregistered('action', bundle.name);
+      await invoke(target, inputStandIn(target.input, bundle.input, bundle.masked), { ctx });
+    } else {
+      const { listQueries, runQuery } = await import('@ultimat3/query');
+      const target = listQueries().find((candidate) => candidate.name === bundle.name);
+      if (target === undefined) return unregistered('query', bundle.name);
+      await runQuery(target, inputStandIn(target.input, bundle.input, bundle.masked), { ctx });
+    }
+    return PASSED;
+  } catch (error) {
+    return outcomeOf(error);
+  }
+}
+
+const unregistered = (kind: string, name: string): ReproOutcome => ({
+  code: null,
+  step: null,
+  failure: `no ${kind} named "${name}" is registered in this test process — import the module that declares it from the written test`,
+});
+
+/** Replay one dead job through the `runJobs` fixture: its input, its completed steps, one drain. */
+export async function reproJob(runJobs: RunJobs, failure: JobFailure): Promise<ReproOutcome> {
+  const jobs = await import('@ultimat3/jobs');
+  const handle = jobs.registeredJobs().find((candidate) => candidate.name === failure.name);
+  if (handle === undefined) return unregistered('job', failure.name);
+  const { inputStandIn } = await import('./repro-stand-in');
+  const input = inputStandIn(handle.input, failure.input, failure.masked);
+  const { runId } = await runJobs.enqueue(handle as JobHandle<unknown>, input);
+  const store = jobs.jobDriver()?.steps;
+  for (const step of failure.steps) {
+    await store?.put({
+      runId,
+      name: step.name,
+      status: 'completed',
+      output: step.output,
+      startedAt: 0,
+      completedAt: 0,
+      attempts: 1,
+    });
+  }
+  const trace = await runJobs.drain();
+  const run = trace.executions.find((execution) => execution.error !== undefined);
+  if (run?.error === undefined) return PASSED;
+  return {
+    code: /X_[A-Z0-9_]+/.exec(run.error)?.[0] ?? 'X_INTERNAL',
+    failure: run.error,
+    step: run.steps.find((step) => step.status === 'failed')?.name ?? null,
+  };
+}

package/src/request-log.ts

@@ -0,0 +1,64 @@
+// One `fetch` call as `requestLog()` records it. A probe of the request is read, never the request:
+// the handler and the real dial each still get a body of their own.
+
+/** One dial, as attempted. A socket dial has no headers and no body. Unredacted, process-local. */
+export interface LoggedRequest {
+  readonly method: string;
+  readonly url: string;
+  /** Lowercase names. */
+  readonly headers: Readonly<Record<string, string>>;
+  /** Decoded as UTF-8. `null`: no body, an unreadable one, or a stream a real server is reading. */
+  readonly body: string | null;
+}
+
+/** A stream read here would be drained ahead of its consumer, which is its backpressure gone. */
+export const hasStreamBody = (init: RequestInit | undefined): boolean => {
+  const body = init?.body ?? null;
+  return !(
+    body === null ||
+    typeof body === 'string' ||
+    body instanceof ArrayBuffer ||
+    ArrayBuffer.isView(body) ||
+    body instanceof Blob ||
+    body instanceof FormData ||
+    body instanceof URLSearchParams
+  );
+};
+
+/**
+ * A body with no end the log can wait for: a stream, or a Request's own, which may be one. Its
+ * capture runs beside the call, so a mock that answers 413 at once is not held to the stream's end.
+ */
+export const isOpenEnded = (input: RequestInfo | URL, init: RequestInit | undefined): boolean =>
+  hasStreamBody(init) || (init?.body == null && input instanceof Request && input.body !== null);
+
+/**
+ * The call's own request, for reading only: a stream body stays out of it, unlocked. `undefined`
+ * when no Request can hold the call, so the refusal the test is owed stays the seal's or the real
+ * dial's rather than this module's `TypeError`.
+ */
+export const requestProbe = (
+  input: RequestInfo | URL,
+  init: RequestInit | undefined,
+): Request | undefined => {
+  try {
+    if (input instanceof Request && init === undefined) return input.clone();
+    const source = input instanceof Request ? input.clone() : input;
+    return new Request(source, hasStreamBody(init) ? { ...init, body: null } : init);
+  } catch {
+    return undefined;
+  }
+};
+
+export const headersOf = (probe: Request | undefined): Readonly<Record<string, string>> =>
+  probe === undefined ? {} : Object.fromEntries(probe.headers);
+
+/** Never rejects: a body that cannot be read is the real call's failure to report, not the log's. */
+export const readBody = async (request: Request | undefined): Promise<string | null> => {
+  if (request === undefined) return null;
+  try {
+    return request.body === null ? null : await request.text();
+  } catch {
+    return null;
+  }
+};

package/src/reusable-database.ts

@@ -3,7 +3,7 @@
 // Booting an embedded Postgres (PGlite) from a migrated template costs 2.4-7 s of CPU on a
 // 12-core box (measured, 64 MB template: 2.7-7.2 s cold, 2.4-2.9 s with the WASM module and fs
 // bundle already compiled — the untar and the postgres start are the cost, not the compile). A
-// suite that boots one per file pays that in every file: notificado.co's unit tier has 236 such
+// suite that boots one per file pays that in every file: one adopter's unit tier has 236 such
 // files, ~700 s of CPU, which is most of its wall time at any width.
 //
 // Since 22.7 a worker runs many files in one process (no `--isolate`), so the database can outlive