@ultimat3/testing 30.3.0 → 30.5.0

package/CLAUDE.md

@@ -16,7 +16,7 @@ import is `registry-isolation.ts`, own entry point, off the barrel. Full rule: `
 | No mocks of the DB | clone a template database; `template-db.ts` is the only DB path |
 | No wall clock | `withFrozenClock` / `advanceClock`; `Date.now()` is frozen by the preload |
 | Frozen ≠ different | `globalThis.Date` becomes a subclass; `FrozenDate[Symbol.hasInstance]` brands on the `[[DateValue]]` slot (`Date.prototype.getTime.call(value)` throws or not) |
-| No unmocked egress | `sealed-network.ts` seals `fetch`; `sealed-sockets.ts` `WebSocket`, `Bun.connect` (not loopback); a miss is `X_TEST_NETWORK_SEALED` |
+| No unmocked egress | `sealed-network.ts` seals `fetch`; `sealed-sockets.ts` `WebSocket`, `Bun.connect` (not loopback); `sealed-dns.ts` the three `lookup`s (a mocked host answers `MOCKED_HOST_ADDRESS`); a miss is `X_TEST_NETWORK_SEALED` |
 | One `mockFetch`, and it grows | a verb in the match, ordered answers, a pinned dial's name (`mock-route.ts`) and `requestLog` (`request-log.ts`). A stream bound for a real server logs `null` (teeing drains it). `original(input, init)` goes as handed: `tls`, `unix`, `proxy` are in no `Request`. `cassette()`: below |
 | Self is not egress | a port core's `markListening()` announced passes through — a socket test never unseals |
 | Offline is a state, not a mock | `network.offline()` / `.drop()` fail every dial, loopback too, as `X_TEST_NETWORK_OFFLINE` before any mock: the app's offline path runs |
@@ -49,15 +49,15 @@ import is `registry-isolation.ts`, own entry point, off the barrel. Full rule: `
 | The exercise pass runs what is registered | `exercise.ts` (`runExercisePass`): every action, query and job once, its own tenant pair off one `seedGraph`, an actor `exercise-actor.ts` picks, 39's `runExercise` as the verdict. Rows COMMITTED. Overrides only via `defineExercise` (blank `off` refused) |
 | An override `input` is awaited, as the call's actor | `exercise-override-input.ts`: run inside the call's own request, so `useContext().actor` is the seated actor; the one way to a signed input. `async` ones are left out of `x drill`'s load |
 | A passkey test signs for real | `softAuthenticator` is `@ultimat3/auth/soft-authenticator`'s, never re-exported here (one value, one path: `flight-copies`) and never a second one (auth's own suites need it, and auth cannot import testing) |
-| A reached job is crash-proven | `exercise-crash.ts`: `crashProof` with the control's input and actor, after the tenant proof; only `diverged` is red (`X_JOB_CRASH_DIVERGED`). Committed: job bodies escape transactions |
+| A reached job is crash-proven | `exercise-crash.ts`: `crashProof` with the control's input and actor, after the tenant proof; only `diverged` is red (`X_JOB_CRASH_DIVERGED`), its place `crashEffectPlace` (`inside` a step via jobs' `currentStep()`, or `after` one). Committed: job bodies escape transactions |
 | The tenant proof is taint only | `tenant-proof.ts`: B, A, B; B is A's role minus `tenancy:cross`. Leak = seeded canary or unhanded id (`tenant-canary.ts`); write = moved digest. Only `crossed` is red |
-| Every statement the pass sent is planned | `plan-sweep.ts` (`sweepPlans`): first relation an app table, `PREPARE` in a READ-ONLY transaction with seq/bitmap scans and sorts off, judged by `plan-oracle.ts`; red = `X_QUERY_UNINDEXED` / `X_QUERY_SORT_UNSERVED` with the `indexes:` entry (`plan-sweep-fix.ts`). `scan:` or `expectedSeqScan` is exempt, listed; no generic plan is `X_QUERY_PLAN_UNAVAILABLE`, never a pass |
+| Every statement the pass sent is planned | `plan-sweep.ts` (`sweepPlans`): first relation an app table, `PREPARE` in a READ-ONLY transaction with seq/bitmap scans and sorts off, judged by `plan-oracle.ts`; red = `X_QUERY_UNINDEXED` / `X_QUERY_SORT_UNSERVED` with the `indexes:` entry (`plan-sweep-fix.ts`). `scan:` or `expectedSeqScan` is exempt, listed; credited: a partial unique whose predicate the statement states (one row), a declared equality-then-range index under a limit; no generic plan is `X_QUERY_PLAN_UNAVAILABLE`, never a pass |
 | A shape that grows with the rows is red | `scale-sweep-run.ts`: two more tenants at `SCALE_SIZES` (2, 8 rows a table), every reached primitive once in each; `judgeScale` (pure) reds `X_QUERY_SCALES_WITH_ROWS`. Under `expectedQueryLoop` it is listed with its reason |
 | An erase is PROVED, not asserted | `subject-proof.ts` (`subjectProof`, run by cli's `exercise-subject.ts`): canaries in every table, one person erased, every stored row searched; a survivor outside `retain` is `X_SUBJECT_ERASE_INCOMPLETE`, naming table and column, never the value |
 | A captured failure replays as a test | `repro.ts`: `reproduce(bundle, { driver })` seeds the rows it read, freezes the clock at its instant, invokes as its actor; masked fields are stood in (`repro-stand-in.ts`). An unregistered name ANSWERS as the failure. `reproJob(runJobs, failure)` for a dead job. What `x repro --write` emits |
 | A vendor's answers are a cassette | `cassette.ts`: replay = one `mockFetch` route per recorded URL, seal kept (`X_CASSETTE_MISSING`, `X_CASSETTE_UNUSED`). Record = `ULTIMATE_CASSETTE=record` + `record.hosts`, refused under `CI` (`X_CASSETTE_RECORD_REFUSED`), headers allow-listed, credential keys masked, bytes scanned before disk (`X_CASSETTE_SECRET`). The request side is never written |
 | One seed writer | `entitySeedWriter({ entities, client \| driver })` (`seed-writer.ts`) writes through each entity's own repository; `snapshot` is required; `entity` loads on the first write, so the barrel stays entity-free |
-| Factory values are DECLARED | `factoriesFor` and `seedGraph` share `seed-graph-values.ts`: default, enum, kind, through `$parse`, never the name. `seed-graph*.ts` type-import `entity` only |
+| Factory values are DECLARED | `factoriesFor` and `seedGraph` share `seed-graph-values.ts`: default, enum, kind, a `matches()` pattern (`seed-pattern-sample.ts`, read off the CHECK by `seed-graph-patterns.ts`), `$meta.schema` (sampler `require`d on first use), through `$parse`, never the name. `seed-graph*.ts` type-import `entity` only |
 | e2e without a driver | `e2eTest` becomes `test.skip`; the gate reports the step SKIPPED (or `X_VERIFY_SUITE_VANISHED` when `x.verify.json` requires it), never passed |
 | The seam has an inverse | `resetE2eDriver()`: `useE2eDriver` writes MODULE scope, so a file that installs a browser undoes it |
 | Built vs declared | `clock` `mail` `network` `runJobs` `statements` `subscribe` are built in-process; `page` `budget` `signIn` `deploy` are declared and wait for a driver (`X_TEST_FIXTURE_UNAVAILABLE`). |

package/README.md

@@ -34,7 +34,8 @@ unitTest('the clock moves only when the test moves it', ({ clock }) => {
 | `seed-graph-error.ts` | `X_SEED_GRAPH_UNSATISFIED`, its fix naming the `defineFactory` to write; `X_SEED_GRAPH_ENTITY_UNKNOWN`, a plan and a writer built from two entity sets |
 | `seed-writer.ts` | `entitySeedWriter({ entities, client })` or `({ entities, driver? })` — the `SeedWriter` that writes a graph through each entity's own repository: Postgres or PGlite through a client, or a driver. `@ultimat3/entity` loads on the first write. `snapshot(rows)`, required on every `SeedWriter`, reads rows back as one digest each (`md5(t::text)` over a client), `null` for a row gone |
 | `exercise.ts` | `runExercisePass({ entities, writer, roles, seed?, overrides?, only? })` — every registered action, query and job once, each on its own committed tenant pair, one `ExerciseRecord` per primitive, the tenant proof's verdict on its `tenant`. What `x exercise` runs |
-| `define-exercise.ts` | `defineExercise({ <name>: { actor, input?, runs? } \| { off: '<why>' } }, { actor?: <entity>, factories?: { <entity name>: defineFactory(…) } })` — an app's overrides (the second argument names the entity whose rows are the actors, and the factories that build a table no generated row satisfies — a cross-column `satisfies` — keyed by entity name, unknown ones `X_DECLARATION_UNKNOWN`), `apps/web/exercise.ts`'s one export; a blank `off` is `X_CONTRACT_EXERCISE_UNDECLARED`, an unknown name `X_DECLARATION_UNKNOWN` when the pass runs |
+| `define-exercise.ts` | `defineExercise({ <name>: { actor, input?, runs? } \| { off: '<why>' } }, { actor?: <entity>, factories?: { <entity name>: defineFactory(…) }, setup?: () => mockFetch(…) \| cassette(…) })` — an app's overrides (the second argument names the entity whose rows are the actors, and the factories that build a table no generated row satisfies — a cross-column `satisfies` — keyed by entity name, unknown ones `X_DECLARATION_UNKNOWN`), `apps/web/exercise.ts`'s one export; a blank `off` is `X_CONTRACT_EXERCISE_UNDECLARED`, an unknown name `X_DECLARATION_UNKNOWN` when the pass runs |
+| `exercise-setup.ts` | `withExerciseSetup(room, setup)`: the app's `setup` run inside the sealed room before the first row, its handle disposed before the room restores the network; an `allowHost` in it is `X_EXERCISE_SETUP_UNSEALED`. Types `ExerciseSetup`, `ExerciseSetupHandle` |
 | `exercise-actor.ts` · `exercise-input.ts` · `exercise-report.ts` | the first `x policy explain` actor the policy allows, minted in the primitive's tenant · the input: override, then a seeded id by field stem, then the minimal draw (`@ultimat3/schema/sample`, loaded dynamically) · the room one run executes in (network sealed, mail captured, clock frozen) and its record, `overrideLine` the entry to paste |
 | `tenant-proof.ts` | internal (`CROSS_TENANT_SCOPE` is `@ultimat3/entity`'s): `proveTenant` — B with A's ids, A's own call, B again; each B leg between two snapshots of A's rows. `withoutCrossTenant` strips `tenancy:cross` (`CROSS_TENANT_SCOPE`) from B; `publicReason` decides `public` |
 | `tenant-canary.ts` | internal: `tenantTaint` — one tenant's rows, ids and marks (row canaries, key parts of `MIN_TAINT_ID_LENGTH` 8 or more no other tenant shares); `findTaint` — every path holding one |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ultimat3/testing",
-  "version": "30.3.0",
+  "version": "30.5.0",
   "description": "Test harness: cloned template DBs per worker, frozen clock, sealed network, 6 test types",
   "keywords": [
     "ultimate",
@@ -46,21 +46,21 @@
     "test": "bun test"
   },
   "dependencies": {
-    "@ultimat3/action": "30.3.0",
-    "@ultimat3/cache": "30.3.0",
-    "@ultimat3/core": "30.3.0",
-    "@ultimat3/db": "30.3.0",
-    "@ultimat3/entity": "30.3.0",
-    "@ultimat3/http": "30.3.0",
-    "@ultimat3/i18n": "30.3.0",
-    "@ultimat3/jobs": "30.3.0",
-    "@ultimat3/mail": "30.3.0",
-    "@ultimat3/policy": "30.3.0",
-    "@ultimat3/pwa": "30.3.0",
-    "@ultimat3/query": "30.3.0",
-    "@ultimat3/realtime": "30.3.0",
-    "@ultimat3/render": "30.3.0",
-    "@ultimat3/schema": "30.3.0",
-    "@ultimat3/time": "30.3.0"
+    "@ultimat3/action": "30.5.0",
+    "@ultimat3/cache": "30.5.0",
+    "@ultimat3/core": "30.5.0",
+    "@ultimat3/db": "30.5.0",
+    "@ultimat3/entity": "30.5.0",
+    "@ultimat3/http": "30.5.0",
+    "@ultimat3/i18n": "30.5.0",
+    "@ultimat3/jobs": "30.5.0",
+    "@ultimat3/mail": "30.5.0",
+    "@ultimat3/policy": "30.5.0",
+    "@ultimat3/pwa": "30.5.0",
+    "@ultimat3/query": "30.5.0",
+    "@ultimat3/realtime": "30.5.0",
+    "@ultimat3/render": "30.5.0",
+    "@ultimat3/schema": "30.5.0",
+    "@ultimat3/time": "30.5.0"
   }
 }

package/src/define-exercise.ts

@@ -5,6 +5,7 @@
 
 import type { ExerciseOptions } from '@ultimat3/action';
 import { renderCauseValue, renderFixLiteral, UltimateError } from '@ultimat3/core';
+import type { ExerciseSetup } from './exercise-setup';
 import type { SeedFactory } from './seed-graph-plan';
 
 /** 39's option type, exactly: `{ actor, input?, runs? }` or `{ off: '<reason>' }`. */
@@ -18,6 +19,8 @@ export interface ExerciseOverrides {
   readonly actorEntity?: string;
   /** By entity name: the pass's graph builds those rows with them (`seedGraph`'s `factories`). */
   readonly factories?: Readonly<Record<string, SeedFactory>>;
+  /** The app's hook, run once inside the pass's sealed room (`exercise-setup.ts`). */
+  readonly setup?: ExerciseSetup;
 }
 
 /** What the whole pass needs to know of the app, beside the per-primitive entries. */
@@ -34,6 +37,13 @@ export interface ExerciseAppOptions {
    * refused when the pass runs.
    */
   readonly factories?: Readonly<Record<string, SeedFactory>>;
+  /**
+   * Run in the exercise process once the network is sealed, before the first row: install the
+   * `mockFetch` routes or `cassette()` your vendor-calling handlers need, so they run for real.
+   * What it returns (a cassette, any `Disposable`) is disposed after the pass. `allowHost` here is
+   * `X_EXERCISE_SETUP_UNSEALED` — the pass never sends a call out.
+   */
+  readonly setup?: ExerciseSetup;
 }
 
 /** `X_CONTRACT_EXERCISE_UNDECLARED`, 39's code for the same silence: an `off` with no reason. */
@@ -59,6 +69,7 @@ export function defineExercise(
     entries,
     ...(app.actor === undefined ? {} : { actorEntity: app.actor.$name }),
     ...(app.factories === undefined ? {} : { factories: app.factories }),
+    ...(app.setup === undefined ? {} : { setup: app.setup }),
   });
 }
 

package/src/errors.ts

@@ -69,6 +69,7 @@ export const TESTING_ERROR_CODES = [
   'X_CASSETTE_SECRET',
   'X_CASSETTE_RECORD_REFUSED',
   'X_TEST_MODULE_MOCK_UNRESTORABLE',
+  'X_EXERCISE_SETUP_UNSEALED',
 ] as const;
 
 export type TestingErrorCode = (typeof TESTING_ERROR_CODES)[number];
@@ -133,6 +134,7 @@ export const TESTING_ERROR_TITLES: Readonly<Record<TestingErrorCode, string>> =
   X_CASSETTE_SECRET: 'a cassette about to be written holds a secret value',
   X_CASSETTE_RECORD_REFUSED: 'a cassette recording was refused',
   X_TEST_MODULE_MOCK_UNRESTORABLE: 'a mocked module could not be put back at the file boundary',
+  X_EXERCISE_SETUP_UNSEALED: 'an exercise setup let a host through the seal',
 };
 
 // Titles must be registered for `format()` to render the contract's first line. Every code above is
@@ -161,7 +163,7 @@ export class NetworkSealedError extends UltimateError {
     url: string;
     method: string;
     allowed: readonly string[];
-    transport?: 'fetch' | 'socket' | undefined;
+    transport?: 'fetch' | 'socket' | 'dns' | undefined;
   }) {
     const allowCall = `allowHost('${hostOf(input.url)}')`;
     const allow = `${allowCall} if it must be real`;
@@ -173,7 +175,9 @@ export class NetworkSealedError extends UltimateError {
       fix:
         input.transport === 'socket'
           ? `${allowCall}   # only if it must be real — otherwise inject the transport: pass the code under test its \`connect\`/\`client\` option, or dial a Bun.listen server on 127.0.0.1 (loopback is never sealed)`
-          : `mockFetch('${input.url}', () => new Response('{}')) — or ${allow}`,
+          : input.transport === 'dns'
+            ? `mockFetch('https://${hostOf(input.url)}/*', () => new Response('{}'))   # a mocked host resolves — or ${allow}`
+            : `mockFetch('${input.url}', () => new Response('{}')) — or ${allow}`,
     });
   }
 }

package/src/exercise-crash.ts

@@ -18,6 +18,7 @@ const findingOf = (divergence: CrashDivergence): CrashFinding => {
     clean: divergence.clean,
     killed: divergence.killed,
     ...(typeof after === 'string' ? { after } : {}),
+    ...(divergence.inside === undefined ? {} : { inside: divergence.inside }),
   };
 };
 

package/src/exercise-defect.ts

@@ -0,0 +1,71 @@
+// What a 5xx tells the author beyond its code: the coded error's cause, the statement or the fields
+// it names, every value the call's input held under a credential key or a `.sensitive()` field
+// masked out of the text. Without it, every X_DB_STATEMENT_FAILED in the pass was rerun by hand.
+
+import { captureValue, isUltimateError, REDACTED, stringField } from '@ultimat3/core';
+import type { StandardSchemaV1 } from '@ultimat3/schema';
+
+/** What `ExerciseRecord.defect` holds. */
+export interface ExerciseDefect {
+  /** The error's own cause, credential values masked, cut at `MAX_DEFECT_CAUSE`. */
+  readonly cause: string;
+  /** The SQL a database refusal names (`… — statement: <sql>`), parameters as `$n`. */
+  readonly statement?: string;
+  /** The paths a validation failure names (`items.0.sku`). */
+  readonly fields?: readonly string[];
+}
+
+/** A cause long enough for a SQLSTATE, its message and a capped statement; past it, cut. */
+export const MAX_DEFECT_CAUSE = 600;
+
+const STATEMENT = / — statement: (.+)$/s;
+
+/** Every scalar the masked copy replaced: what must not appear in the cause either. */
+function maskedScalars(original: unknown, masked: unknown, into: string[]): void {
+  if (masked === REDACTED) {
+    if (typeof original === 'string' || typeof original === 'number') into.push(String(original));
+    return;
+  }
+  if (typeof original !== 'object' || original === null) return;
+  if (typeof masked !== 'object' || masked === null) return;
+  for (const [key, entry] of Object.entries(original)) {
+    maskedScalars(entry, Reflect.get(masked, key), into);
+  }
+}
+
+const fieldsOf = (meta: Readonly<Record<string, unknown>> | undefined): readonly string[] => {
+  const issues = meta?.['issues'];
+  if (!Array.isArray(issues)) return [];
+  return issues.flatMap((issue: unknown) => {
+    const path = stringField(issue, 'path');
+    return path === undefined || path === '' ? [] : [path];
+  });
+};
+
+/**
+ * The detail of a CODED failure, or `undefined` for an uncoded throw — whose reason already is the
+ * throw. `schema` is the primitive's input: its `.sensitive()` fields are masked as `redactKeys`
+ * ones are (core's `captureValue`), so the record holds no value the audit log would not.
+ */
+export async function defectDetail(
+  error: unknown,
+  input: unknown,
+  schema: StandardSchemaV1,
+): Promise<ExerciseDefect | undefined> {
+  if (!isUltimateError(error)) return undefined;
+  // On demand: `@ultimat3/schema` is a dynamic-only dependency of this barrel (`CLAUDE.md`).
+  const { maskSensitive } = await import('@ultimat3/schema');
+  const secrets: string[] = [];
+  maskedScalars(input, captureValue(maskSensitive(schema, input, REDACTED)).value, secrets);
+  let cause = error.cause;
+  for (const value of [...new Set(secrets)].sort((a, b) => b.length - a.length)) {
+    if (value !== '') cause = cause.split(value).join(REDACTED);
+  }
+  const statement = STATEMENT.exec(cause)?.[1]?.trim();
+  const fields = fieldsOf(error.meta);
+  return {
+    cause: cause.length > MAX_DEFECT_CAUSE ? `${cause.slice(0, MAX_DEFECT_CAUSE - 1)}…` : cause,
+    ...(statement === undefined || statement === '' ? {} : { statement }),
+    ...(fields.length === 0 ? {} : { fields }),
+  };
+}

package/src/exercise-job-tenant.ts

@@ -31,8 +31,15 @@ const answer = (handle: TenantOf, input: unknown): string | undefined => {
   }
 };
 
+/** How deep an absent parent is filled in to read past it: `payload.input.orgId` is two. */
+const ABSENT_DEPTH = 4;
+
+/** The value at `path`, `undefined` when any step of it is absent. */
+const getAt = (input: unknown, path: Path): unknown =>
+  path.reduce<unknown>((value, key) => (isPlainObject(value) ? value[key] : undefined), input);
+
 /** Every property path `tenantFor` read, at any depth of plain objects — a missing one included. */
-function pathsRead(handle: TenantOf, input: unknown): readonly Path[] {
+function readOnce(handle: TenantOf, input: unknown): readonly Path[] {
   const read: Path[] = [];
   const watch = (value: unknown, at: Path): unknown =>
     !isPlainObject(value)
@@ -49,8 +56,28 @@ function pathsRead(handle: TenantOf, input: unknown): readonly Path[] {
   return read;
 }
 
+/**
+ * Every path read, past absent parents too: a read that found nothing is filled with `{}` and read
+ * again, so `payload.input.orgId` — a scoped backfill's tenant, its `input` left out of the
+ * minimal draw — is found, not lost to the throw reading `orgId` of `undefined`.
+ */
+function pathsRead(handle: TenantOf, input: unknown, depth = 0): readonly Path[] {
+  const reads = readOnce(handle, input);
+  if (depth >= ABSENT_DEPTH) return reads;
+  const deeper = reads
+    .filter((path) => getAt(input, path) === undefined)
+    .flatMap((path) => pathsRead(handle, setAt(input, path, {}), depth + 1));
+  const seen = new Set<string>();
+  return [...reads, ...deeper].filter((path) => {
+    const key = JSON.stringify(path);
+    if (seen.has(key)) return false;
+    seen.add(key);
+    return true;
+  });
+}
+
 /** `input` with `path` set to `value`, copied along the path only. */
-function setAt(input: unknown, path: Path, value: string): unknown {
+function setAt(input: unknown, path: Path, value: unknown): unknown {
   const [head, ...rest] = path;
   if (head === undefined) return value;
   const base = isPlainObject(input) ? input : {};

package/src/exercise-report.ts

@@ -12,7 +12,9 @@ import {
 } from '@ultimat3/db';
 import type { RowObserver } from '@ultimat3/entity';
 import { captureDeterminism, installDeterminism, restoreCapturedDeterminism } from './determinism';
+import type { ExerciseDefect } from './exercise-defect';
 import { testMail } from './fixture-mail';
+import { routeMatches } from './mock-route';
 import type { PlanProof, SentStatement } from './plan-sweep';
 import type { ScaleProof, StatementTally } from './scale-sweep';
 import {
@@ -71,8 +73,10 @@ export interface CrashFinding {
   readonly effect: string;
   readonly clean: number;
   readonly killed: number;
-  /** The last step the clean run had written before the effect; absent, before the first. */
+  /** The last step the clean run had completed before the effect; absent, before the first. */
   readonly after?: string;
+  /** The step whose body made the effect, when it was made inside one: it runs again on a retry. */
+  readonly inside?: string;
 }
 
 /** The crash proof's verdict on a reached job: killed at every step boundary (`crashProof`). */
@@ -94,6 +98,8 @@ export interface ExerciseRecord {
   readonly outcome: ExerciseOutcome;
   readonly code?: string;
   readonly reason?: string;
+  /** On an `unreached` one that answered a 5xx: its cause, statement and fields, values masked. */
+  readonly defect?: ExerciseDefect;
   readonly statements: number;
   readonly effects: readonly ExerciseEffect[];
   readonly ms: number;
@@ -228,6 +234,10 @@ export async function openExerciseRoom(): Promise<ExerciseRoom> {
     },
     end: (): Observed => {
       const calls = requestLog().slice(logFrom);
+      // A call a route answered never left the process: the app's `setup` installed it.
+      const { mocks } = captureNetwork();
+      const refused = (call: (typeof calls)[number]): boolean =>
+        !local(call.url) && !mocks.some((route) => routeMatches(route, call));
       const effects: ExerciseEffect[] = [
         ...[...tally(rows)].map(([key, count]): ExerciseEffect => {
           const [entity = '', op = ''] = key.split('\u0000');
@@ -241,11 +251,11 @@ export async function openExerciseRoom(): Promise<ExerciseRoom> {
             kind: 'network',
             method: call.method,
             host: hostOf(call.url),
-            refused: !local(call.url),
+            refused: refused(call),
           }),
         ),
       ];
-      const refusedHosts = calls.filter((call) => !local(call.url)).map((c) => hostOf(c.url));
+      const refusedHosts = calls.filter(refused).map((c) => hostOf(c.url));
       const payloads: EffectPayload[] = [
         ...mail.outbox().map(({ message }, i) => ({
           path: `effect.mail[${i}]`,

package/src/exercise-setup.ts

@@ -0,0 +1,68 @@
+// `defineExercise(…, { setup })`, run: the app's hook inside the pass's sealed room, before the
+// first row is seeded, disposed before the room restores the network. What it installs — a
+// `mockFetch` route, a `cassette()` — answers a vendor call; `allowHost` would send one for real.
+
+import { renderCauseValue, UltimateError } from '@ultimat3/core';
+import type { ExerciseRoom } from './exercise-report';
+import { captureNetwork } from './sealed-network';
+
+/** What a setup may hand back to be undone after the pass: a `cassette()`, a `using` resource. */
+export type ExerciseSetupHandle = Disposable | AsyncDisposable;
+
+/**
+ * Runs once per pass, in the exercise process, after the seal and before any primitive. Returns
+ * nothing when there is nothing to undo — a `mockFetch` route goes with the room.
+ */
+export type ExerciseSetup = () =>
+  | void
+  | ExerciseSetupHandle
+  | Promise<void>
+  | Promise<ExerciseSetupHandle>
+  | Promise<ExerciseSetupHandle | undefined>;
+
+const setupUnsealed = (hosts: readonly string[]): UltimateError =>
+  new UltimateError({
+    code: 'X_EXERCISE_SETUP_UNSEALED',
+    cause: `defineExercise(…, { setup }) called allowHost(${hosts.map((host) => renderCauseValue(host)).join(', ')}): the pass would send a primitive's call out for real, where every vendor is answered by mockFetch or cassette()`,
+    fix: "mockFetch('https://<host>/*', handler)   # or cassette(import.meta.dir, '<name>') — in apps/web/exercise.ts's setup, in place of allowHost('<host>')",
+    meta: { hosts },
+  });
+
+async function release(handle: unknown): Promise<void> {
+  if (typeof handle !== 'object' || handle === null) return;
+  if (Symbol.asyncDispose in handle) await (handle as AsyncDisposable)[Symbol.asyncDispose]();
+  else if (Symbol.dispose in handle) (handle as Disposable)[Symbol.dispose]();
+}
+
+/**
+ * `room` with `setup` run inside it. Its dispose releases what setup returned FIRST — a cassette's
+ * own check reads the routes the pass used — then the room. A setup that throws, or lets a host
+ * through, disposes both before the pass refuses.
+ */
+export async function withExerciseSetup(
+  room: ExerciseRoom,
+  setup: ExerciseSetup | undefined,
+): Promise<ExerciseRoom> {
+  if (setup === undefined) return room;
+  const before = new Set(captureNetwork().allowed);
+  let handle: unknown;
+  try {
+    handle = await setup();
+  } catch (error) {
+    await room[Symbol.asyncDispose]();
+    throw error;
+  }
+  const dispose = async (): Promise<void> => {
+    try {
+      await release(handle);
+    } finally {
+      await room[Symbol.asyncDispose]();
+    }
+  };
+  const opened = captureNetwork().allowed.filter((host) => !before.has(host));
+  if (opened.length > 0) {
+    await dispose();
+    throw setupUnsealed(opened);
+  }
+  return { ...room, [Symbol.asyncDispose]: dispose };
+}

package/src/exercise-subjects.ts

@@ -3,7 +3,7 @@
 // (`exercise-job-tenant.ts`): a drawn org is a random one, and the enqueue refuses it.
 
 import type { Actor } from '@ultimat3/core';
-import { renderCauseValue, renderFixShellArg } from '@ultimat3/core';
+import { renderCauseValue, renderFixShellArg, UltimateError } from '@ultimat3/core';
 import type { AnyJobHandle, JobExecution } from '@ultimat3/jobs';
 import { registeredJobs } from '@ultimat3/jobs';
 import type { Policy } from '@ultimat3/policy';
@@ -58,8 +58,22 @@ export function fixedTenant(name: string, declared: string | undefined) {
 
 const ANSWERED: ReadonlySet<string> = new Set(['completed', 'suspended']);
 
-const statusOfJobFailure = (run: JobExecution | undefined): string =>
-  run === undefined ? 'the job never ran' : (run.error ?? `the run ended ${run.outcome}`);
+/**
+ * What a failed run hands the verdict. A run whose error carried a code is that code again, so
+ * core's `exerciseDefect` judges it by the one rule an action's refusal meets: a coded refusal
+ * under 500 is the job answering "no", a 5xx or an uncoded throw is a defect. The message alone
+ * read every coded refusal — an app's 409 included — as an uncoded throw: X_CONTRACT_DEFECT.
+ */
+const jobFailure = (run: JobExecution | undefined): unknown => {
+  if (run === undefined) return 'the job never ran';
+  const message = run.error ?? `the run ended ${run.outcome}`;
+  if (run.code === undefined) return message;
+  return new UltimateError({
+    code: run.code,
+    cause: message,
+    fix: `x errors explain ${renderFixShellArg(run.code, '<code>')} --json`,
+  });
+};
 
 const jobSubject = (handle: AnyJobHandle): Subject => ({
   kind: 'job',
@@ -73,11 +87,11 @@ const jobSubject = (handle: AnyJobHandle): Subject => ({
     const queued = await jobs.enqueue(handle, input, { tenantId: tenant });
     const trace = await jobs.drain(actor === null ? {} : { actor });
     const own = trace.executions.find((run) => run.jobId === queued.id);
-    // The worker's failure is a string on the row, never a throw: it is the attempt's error.
+    // The worker's failure is on the row, never a throw: the attempt's error and its code.
     // Suspended is a body that ran and parked (`step.sleep`, `waitForEvent`): reached.
     return own !== undefined && ANSWERED.has(own.outcome)
       ? { output: own.result }
-      : { failure: statusOfJobFailure(own) };
+      : { failure: jobFailure(own) };
   },
 });
 

package/src/exercise.ts

@@ -15,6 +15,7 @@ import { assertOverridesKnown, unknownDeclaration } from './define-exercise';
 import type { RoleGrants } from './exercise-actor';
 import { chooseActor } from './exercise-actor';
 import { proveCrash } from './exercise-crash';
+import { defectDetail } from './exercise-defect';
 import type { IdLookup, Sampler } from './exercise-input';
 import {
   bindIds,
@@ -34,12 +35,13 @@ import type {
   Observed,
 } from './exercise-report';
 import { openExerciseRoom, overrideLine } from './exercise-report';
+import { withExerciseSetup } from './exercise-setup';
 import type { Subject } from './exercise-subjects';
 import { fixedTenant, seatIn, subjectsOf } from './exercise-subjects';
 import { actorRowsOf, attachSweeps, seated, sizedCall } from './exercise-sweeps';
 import type { RunJobs } from './fixture-jobs';
 import { testJobs } from './fixture-jobs';
-import { pairGraph, seedPass, tenantPair } from './seed-graph-pass';
+import { deferredMayStayNull, pairGraph, seedPass, tenantPair } from './seed-graph-pass';
 import type { SeedGraph, SeedWriter } from './seed-graph-plan';
 import type { SeedEntity } from './seed-graph-shape';
 import { tenantTaint } from './tenant-canary';
@@ -211,7 +213,20 @@ async function control(
   const observed = room.end();
   const effects = [...observed.effects, ...(await enqueued(subject, jobs, executions))];
   const verdictOf = judged(subject, { verdict, answered, lastError, lastInput }, observed);
-  const record = { kind, name, statements: observed.statements, effects, ms, ...verdictOf };
+  // A 5xx's cause, statement and fields: the code alone sent the author to reproduce it by hand.
+  const defect =
+    verdict.kind === 'defect' && verdictOf.outcome === 'unreached'
+      ? await defectDetail(verdict.error, verdict.input, subject.input)
+      : undefined;
+  const record = {
+    kind,
+    name,
+    statements: observed.statements,
+    effects,
+    ms,
+    ...verdictOf,
+    ...(defect === undefined ? {} : { defect }),
+  };
   return { record, output, input: lastInput };
 }
 
@@ -343,7 +358,8 @@ export async function runExercisePass(
   const sampler = await loadSampler();
   // Not `Math.random`: the frozen RNG answers the same sequence in every process.
   const passSeed = options.seed ?? (crypto.getRandomValues(new Uint32Array(1))[0] as number);
-  const room = await openExerciseRoom();
+  // The app's setup runs inside the seal, before the first row: its routes answer every call.
+  const room = await withExerciseSetup(await openExerciseRoom(), options.overrides?.setup);
   const live = chosen.filter((subject) => !isOff(options.overrides, subject.name));
   const records: ExerciseRecord[] = [];
   let graph: SeedGraph;
@@ -372,7 +388,8 @@ export async function runExercisePass(
   return attachSweeps(records, {
     subjects: chosen.filter((subject) => reached.has(subject.name)),
     entities: options.entities,
-    writer: options.writer,
+    // The sized graphs close their cycles as the pass's did: a refused deferred key stays null.
+    writer: deferredMayStayNull(options.writer),
     main: graph,
     seed: passSeed,
     room,

package/src/factory-registry.ts

@@ -5,7 +5,8 @@
 import type { EntityLike, Factory, FactoryIds } from './factories';
 import { defineFactory } from './factories';
 import { seedGraphUnsatisfied } from './seed-graph-error';
-import { SEED_SOFT_DELETE_PROPERTY } from './seed-graph-shape';
+import { declaredPatterns } from './seed-graph-patterns';
+import { SEED_SOFT_DELETE_PROPERTY, type SeedEntity } from './seed-graph-shape';
 import { candidatesFor, isSeedColumn } from './seed-graph-values';
 
 export type EntityRegistry = Readonly<Record<string, EntityLike>>;
@@ -25,13 +26,14 @@ export function factoriesFor<TRegistry extends EntityRegistry>(
 ): FactoryRegistry<TRegistry> {
   const out: Record<string, Factory<Record<string, unknown>>> = {};
   for (const [name, entity] of Object.entries(registry)) {
+    const patterns = hasInvariants(entity) ? declaredPatterns(entity) : new Map();
     out[name] = defineFactory(entity, {
       ...(seed === undefined ? {} : { seed }),
       defaults: (index, ids): Record<string, unknown> => {
         const row: Record<string, unknown> = {};
         Object.entries(entity.$columns).forEach(([property, column], position) => {
           row[property] = defaultFor(
-            { table: entity.$table, property, column, position },
+            { table: entity.$table, property, column, position, patterns: patterns.get(property) },
             index,
             ids,
           );
@@ -43,12 +45,21 @@ export function factoriesFor<TRegistry extends EntityRegistry>(
   return out as FactoryRegistry<TRegistry>;
 }
 
+/** An `entity()` value, which declares rules; a hand-built `EntityLike` may declare none. */
+const hasInvariants = (entity: object): entity is Pick<SeedEntity, '$invariants' | '$describe'> =>
+  '$invariants' in entity &&
+  Array.isArray(entity.$invariants) &&
+  '$describe' in entity &&
+  typeof entity.$describe === 'function';
+
 /** One column of one entity: what `defaultFor` reads. The name labels a refusal, nothing more. */
 export interface DefaultColumn {
   readonly table: string;
   readonly property: string;
   readonly column: unknown;
   readonly position: number;
+  /** The `matches()` patterns the entity holds this column to (`declaredPatterns`). */
+  readonly patterns?: readonly RegExp[] | undefined;
 }
 
 /**
@@ -68,6 +79,7 @@ export function defaultFor(target: DefaultColumn, index: number, ids: FactoryIds
         ordinal: index,
         canary: String(index),
         position: target.position,
+        patterns: target.patterns,
         uuid: () => ids.uuid(),
       })
     : [];

package/src/index.ts

@@ -200,6 +200,7 @@ export {
 export type { ExercisePassOptions } from './exercise';
 export { runExercisePass } from './exercise';
 export type { ActorChoice, RoleGrants } from './exercise-actor';
+export type { ExerciseDefect } from './exercise-defect';
 export type {
   CrashFinding,
   CrashProof,
@@ -212,6 +213,7 @@ export type {
   TenantProof,
 } from './exercise-report';
 export { overrideLine } from './exercise-report';
+export type { ExerciseSetup, ExerciseSetupHandle } from './exercise-setup';
 export type {
   Association,
   AssociationMap,
@@ -375,6 +377,7 @@ export { crashProof } from './job-crash-proof';
 export { jobDriverConformance } from './job-driver-conformance';
 export type { SimEffect } from './job-sim-effects';
 export {
+  crashEffectPlace,
   JobCrashDivergedError,
   JobSimInvariantError,
   JobSimNondeterministicError,
@@ -443,6 +446,7 @@ export {
   allowHost,
   captureNetwork,
   isNetworkSealed,
+  MOCKED_HOST_ADDRESS,
   mockFetch,
   mockJson,
   networkState,