@ultimat3/testing 30.4.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,7 +49,7 @@ 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; 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 |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ultimat3/testing",
-  "version": "30.4.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.4.0",
-    "@ultimat3/cache": "30.4.0",
-    "@ultimat3/core": "30.4.0",
-    "@ultimat3/db": "30.4.0",
-    "@ultimat3/entity": "30.4.0",
-    "@ultimat3/http": "30.4.0",
-    "@ultimat3/i18n": "30.4.0",
-    "@ultimat3/jobs": "30.4.0",
-    "@ultimat3/mail": "30.4.0",
-    "@ultimat3/policy": "30.4.0",
-    "@ultimat3/pwa": "30.4.0",
-    "@ultimat3/query": "30.4.0",
-    "@ultimat3/realtime": "30.4.0",
-    "@ultimat3/render": "30.4.0",
-    "@ultimat3/schema": "30.4.0",
-    "@ultimat3/time": "30.4.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/errors.ts

@@ -163,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`;
@@ -175,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-report.ts

@@ -12,6 +12,7 @@ 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';
@@ -72,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`). */
@@ -95,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;

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,
@@ -212,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 };
 }
 

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,
@@ -376,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,
@@ -444,6 +446,7 @@ export {
   allowHost,
   captureNetwork,
   isNetworkSealed,
+  MOCKED_HOST_ADDRESS,
   mockFetch,
   mockJson,
   networkState,

package/src/job-crash-proof.ts

@@ -33,6 +33,8 @@ export interface CrashDivergence {
   readonly effect: string;
   readonly clean: number;
   readonly killed: number;
+  /** The step whose body made the effect, when every occurrence was made inside that one step. */
+  readonly inside?: string;
   readonly error: JobCrashDivergedError;
 }
 
@@ -155,8 +157,22 @@ async function runOnce<I>(
 }
 
 /**
- * Effects the killed run made more often than the reference — or less often, when both ended alike
- * and neither unwound. An unwound run is also held to the reference's compensators: each once, last
+ * The one step whose body made every occurrence of `key` in both runs, or `undefined` when any
+ * occurrence was made between steps (or in two different steps).
+ */
+function insideOf(key: string, runs: readonly Ran[]): string | undefined {
+  const steps = new Set(
+    runs.flatMap((run) => run.effects.filter((one) => one.key === key).map((one) => one.inside)),
+  );
+  const [only] = steps;
+  return steps.size === 1 ? only : undefined;
+}
+
+/**
+ * Effects the killed run made more often than the reference — or less often, when both ended alike,
+ * neither unwound and the effect is made between steps. Inside a step body that did not complete,
+ * fewer is a kill that spent one of the step's attempts (the queue's lease accounting), not a call
+ * the crash skipped. An unwound run is also held to the reference's compensators: each once, last
  * in first out, for exactly the forward steps that completed in it.
  */
 function compare(reference: Ran, killed: Ran): readonly [string, number, number][] {
@@ -169,7 +185,9 @@ function compare(reference: Ran, killed: Ran): readonly [string, number, number]
   for (const key of keys) {
     const c = before.get(key) ?? 0;
     const k = after.get(key) ?? 0;
-    if (k > c || (k < c && alike)) out.push([key, c, k]);
+    if (k > c || (k < c && alike && insideOf(key, [reference, killed]) === undefined)) {
+      out.push([key, c, k]);
+    }
   }
   if (unwound) {
     const expected = reference.compensated.filter((name) =>
@@ -222,19 +240,25 @@ export async function crashProof<I>(
           : clean;
       for (const [effect, c, k] of compare(reference, killed)) {
         const after = afterOf(effect);
+        const inside = insideOf(effect, [reference, killed]);
+        const where = {
+          ...(after === undefined ? {} : { after }),
+          ...(inside === undefined ? {} : { inside }),
+        };
         divergences.push({
           boundary: label,
           mode,
           effect,
           clean: c,
           killed: k,
+          ...(inside === undefined ? {} : { inside }),
           error: new JobCrashDivergedError({
             job: handle.name,
             boundary: label,
             effect,
             clean: c,
             killed: k,
-            ...(after === undefined ? {} : { after }),
+            ...where,
           }),
         });
       }

package/src/job-sim-effects.ts

@@ -18,15 +18,17 @@ export interface SimEffect {
   readonly key: string;
   /** The worker whose body made it; absent for the harness. */
   readonly worker?: string;
-  /** The last step that worker's run had written when the effect happened. */
+  /** The last step that worker's run had COMPLETED when the effect happened. */
   readonly after?: string;
+  /** The step whose body made it (`@ultimat3/jobs`' `currentStep()`); absent between steps. */
+  readonly inside?: string;
 }
 
 export interface EffectLog extends AsyncDisposable {
   /** The worker a call in flight belongs to: what `run` scoped it to. */
   readonly scope: AsyncContext<string>;
   record(key: string): void;
-  /** A worker's run wrote this step — what the next effect it makes is placed after. */
+  /** A worker's run completed this step — what the next effect it makes is placed after. */
   stepWritten(worker: string, step: string): void;
   effects(): readonly SimEffect[];
   clear(): void;
@@ -52,6 +54,7 @@ const methodOf = (input: RequestInfo | URL, init: RequestInit | undefined): stri
 
 export async function openEffectLog(options: EffectLogOptions): Promise<EffectLog> {
   const { setRowObserver } = await import('@ultimat3/entity');
+  const { currentStep } = await import('@ultimat3/jobs');
   const mail = await import('@ultimat3/mail');
   const scope = asyncContext<string>('the job simulation');
   const log: SimEffect[] = [];
@@ -61,10 +64,12 @@ export async function openEffectLog(options: EffectLogOptions): Promise<EffectLo
     const worker = scope.get();
     if (worker !== undefined && options.isDead(worker)) return;
     const after = worker === undefined ? undefined : lastStep.get(worker);
+    const inside = currentStep();
     log.push({
       key,
       ...(worker === undefined ? {} : { worker }),
       ...(after === undefined ? {} : { after }),
+      ...(inside === undefined ? {} : { inside }),
     });
   };
 

package/src/job-sim-errors.ts

@@ -17,18 +17,49 @@ export interface CrashDivergedInput {
   readonly effect: string;
   readonly clean: number;
   readonly killed: number;
-  /** The last step written before the effect, in the clean run. */
+  /** The last step completed before the effect, in the clean run. */
   readonly after?: string;
+  /** The step whose body made the effect, when it was made inside one. */
+  readonly inside?: string;
 }
 
+/**
+ * Where an effect was made, as the crash proof's two reporters phrase it — this error and the CLI's
+ * finding (`@ultimat3/cli`'s `exercise-findings.ts`) — so the two cannot name different places.
+ * `remedy` is prose for a `fix:`'s comment, after the call it pastes.
+ */
+export function crashEffectPlace(where: {
+  readonly after?: string | undefined;
+  readonly inside?: string | undefined;
+}): { readonly place: string; readonly remedy: string } {
+  if (where.inside !== undefined) {
+    const step = renderCauseValue(where.inside);
+    return {
+      place: `it runs inside step ${step}, whose body runs again until the step completes`,
+      remedy: `make the body of step ${step} idempotent: key its external call on \`\${jobId}:${where.inside}\`, or move the effect into a step of its own`,
+    };
+  }
+  const at =
+    where.after === undefined
+      ? 'before the first step'
+      : `after step ${renderCauseValue(where.after)}`;
+  return {
+    place: `it runs outside every step, ${at}`,
+    remedy: `wrap the effect made ${at} in step.run('<name>', async () => …); key an external call on \`\${jobId}:<step>\``,
+  };
+}
+
+const howOften = (killed: number, clean: number): string =>
+  killed > clean ? 'so the retry makes it again' : 'so the crash skipped it';
+
 export class JobCrashDivergedError extends UltimateError {
   constructor(input: CrashDivergedInput) {
-    const where =
-      input.after === undefined ? 'before the first step' : `after step "${input.after}"`;
+    const { place, remedy } = crashEffectPlace(input);
+    const name = input.inside ?? `${input.boundary}-effect`;
     super({
       code: 'X_JOB_CRASH_DIVERGED',
-      cause: `job ${renderCauseValue(input.job)} killed at ${renderCauseValue(input.boundary)} made ${renderCauseValue(input.effect)} ${input.killed}× against ${input.clean}× in a clean run: it runs outside every step, ${where}, so the retry makes it again`,
-      fix: `step.run(${renderFixLiteral(`${input.boundary}-effect`, '<name>')}, async () => …)   # in job(${renderFixLiteral(input.job, '<job>')}): wrap the ${renderFixLiteral(input.effect, '<effect>')} made ${where}; key an external call on \`\${jobId}:<step>\`; then: x test job --filter <the test file>`,
+      cause: `job ${renderCauseValue(input.job)} killed at ${renderCauseValue(input.boundary)} made ${renderCauseValue(input.effect)} ${input.killed}× against ${input.clean}× in a clean run: ${place}, ${howOften(input.killed, input.clean)}`,
+      fix: `step.run(${renderFixLiteral(name, '<name>')}, async () => …)   # in job(${renderFixLiteral(input.job, '<job>')}), for ${renderFixLiteral(input.effect, '<effect>')}: ${remedy}; then: x test job --filter <the test file>`,
       meta: { ...input },
     });
   }

package/src/job-sim-world.ts

@@ -86,7 +86,10 @@ export async function openSimWorld(options: SimWorldOptions): Promise<SimWorld>
     decide: (op) => options.decide(op),
     landed: (op, answer) => {
       remember(answer);
-      if (op.call === 'put' && op.step !== undefined) log?.stepWritten(op.worker, op.step);
+      // Completed only: a `failed` or `started` record is not a step the body has moved past.
+      if (op.call === 'put' && op.step !== undefined && op.status === 'completed') {
+        log?.stepWritten(op.worker, op.step);
+      }
       if ((op.call === 'enqueue' || op.call === 'enqueueMany') && log !== undefined) {
         const results = (Array.isArray(answer) ? answer : [answer]) as readonly EnqueueResult[];
         results.forEach((result, i) => {

package/src/mock-route.ts

@@ -79,3 +79,24 @@ export const routeMatches = (
   const named = namedUrl(call.url, call.headers);
   return named !== undefined && urlMatches(route.match, named);
 };
+
+/** A RegExp's literal text: a `.` in a host is `\.` in its source. */
+const escaped = (text: string): string => text.replace(/[.*+?^${}()|[\]\\/]/g, '\\$&');
+
+/**
+ * Whether `route` answers some URL on `hostname` — what makes the sealed resolver answer the name.
+ * A string names its host outright; a RegExp when it matches the host's origin or spells the host
+ * in its source (`/api\.vendor\.example\/v1/`), since no reader can enumerate what a pattern matches.
+ */
+export const routeNamesHost = (route: MockRoute, hostname: string): boolean => {
+  const host = hostname.toLowerCase();
+  if (route.match instanceof RegExp) {
+    const pattern = route.match;
+    const origins = [`https://${host}/`, `http://${host}/`];
+    if (origins.some((origin) => urlMatches(pattern, origin))) return true;
+    const source = pattern.source.toLowerCase();
+    return source.includes(escaped(host)) || source.includes(host);
+  }
+  const literal = route.match.endsWith('*') ? route.match.slice(0, -1) : route.match;
+  return URL.canParse(literal) && new URL(literal).hostname.toLowerCase() === host;
+};

package/src/sealed-dns.ts

@@ -0,0 +1,86 @@
+// The resolver half of the sealed network: `Bun.dns.lookup`, `dns.lookup` and `dns.promises.lookup`.
+// Only the patching lives here; WHAT a name resolves to is `sealed-network.ts`'s one gate, handed in,
+// so a host `fetch` would answer by mock resolves and a host it would refuse does not. A named ESM
+// import (`import { lookup } from 'node:dns'`) binds before the seal and is NOT covered (measured).
+
+// why: `dns.lookup` and `dns.promises.lookup` are what an app's own resolver calls; Bun ships both.
+import nodeDns from 'node:dns';
+
+/** One lookup's verdict: the addresses to answer, a refusal to raise, or `real` for the resolver. */
+export type DnsVerdict =
+  | { readonly answer: readonly string[] }
+  | { readonly refused: Error }
+  | { readonly real: true };
+
+export type DnsGate = (hostname: string) => DnsVerdict;
+
+interface LookupEntry {
+  readonly address: string;
+  readonly family: number;
+}
+
+const familyOf = (address: string): number => (address.includes(':') ? 6 : 4);
+
+const entriesOf = (addresses: readonly string[]): LookupEntry[] =>
+  addresses.map((address) => ({ address, family: familyOf(address) }));
+
+type NodeCallback = (error: unknown, address?: unknown, family?: number) => void;
+
+/** Node's `(hostname, options?, callback)`; `options.all` answers the list, a number is a family. */
+const wantsAll = (options: unknown): boolean =>
+  typeof options === 'object' && options !== null && 'all' in options && options.all === true;
+
+/**
+ * Patch the three resolvers and return the uninstaller, which puts back exactly what was there.
+ * Assigned through `Reflect.set`: each is a writable data property the types declare a function.
+ */
+export function installDnsSeal(gate: DnsGate): () => void {
+  const originalBun = Reflect.get(Bun.dns, 'lookup') as typeof Bun.dns.lookup;
+  const originalNode = Reflect.get(nodeDns, 'lookup') as (...args: unknown[]) => void;
+  const originalPromises = Reflect.get(nodeDns.promises, 'lookup') as (
+    ...args: unknown[]
+  ) => Promise<unknown>;
+
+  const sealedBun = async (hostname: string, options?: unknown): Promise<unknown> => {
+    const verdict = gate(hostname);
+    if ('refused' in verdict) throw verdict.refused;
+    if ('answer' in verdict) return entriesOf(verdict.answer).map((one) => ({ ...one, ttl: 0 }));
+    return Reflect.apply(originalBun, Bun.dns, [hostname, options]);
+  };
+
+  const sealedNode = (hostname: string, ...rest: unknown[]): void => {
+    const verdict = gate(hostname);
+    if ('real' in verdict) {
+      Reflect.apply(originalNode, nodeDns, [hostname, ...rest]);
+      return;
+    }
+    const callback = rest.findLast((one) => typeof one === 'function') as NodeCallback | undefined;
+    const options = rest.length > 1 ? rest[0] : undefined;
+    // A real lookup answers on a later tick, and a caller may rely on it: never synchronously.
+    queueMicrotask(() => {
+      if ('refused' in verdict) return callback?.(verdict.refused);
+      const entries = entriesOf(verdict.answer);
+      if (wantsAll(options)) return callback?.(null, entries);
+      return callback?.(null, entries[0]?.address, entries[0]?.family);
+    });
+  };
+
+  const sealedPromises = async (hostname: string, options?: unknown): Promise<unknown> => {
+    const verdict = gate(hostname);
+    if ('refused' in verdict) throw verdict.refused;
+    if ('real' in verdict) {
+      return Reflect.apply(originalPromises, nodeDns.promises, [hostname, options]);
+    }
+    const entries = entriesOf(verdict.answer);
+    return wantsAll(options) ? entries : entries[0];
+  };
+
+  Reflect.set(Bun.dns, 'lookup', sealedBun);
+  Reflect.set(nodeDns, 'lookup', sealedNode);
+  Reflect.set(nodeDns.promises, 'lookup', sealedPromises);
+  return () => {
+    Reflect.set(Bun.dns, 'lookup', originalBun);
+    Reflect.set(nodeDns, 'lookup', originalNode);
+    Reflect.set(nodeDns.promises, 'lookup', originalPromises);
+  };
+}

package/src/sealed-network.ts

@@ -1,14 +1,15 @@
-// Sealed network. Any egress a test did not explicitly mock or allow fails the test with the URL
-// and the line that fixes it. A test that quietly reaches the internet is a test that fails in CI
-// for reasons nobody can reproduce — so the default is "nothing gets out". Three dials are sealed:
-// `fetch` here, `WebSocket` and `Bun.connect` through `sealed-sockets.ts`, all behind one gate.
+// Sealed network: egress a test did not mock or allow fails with the URL and the line that fixes
+// it, so nothing reaches the internet unreproducibly. `fetch` here, `WebSocket`/`Bun.connect` via
+// `sealed-sockets.ts`, name resolution via `sealed-dns.ts` — one gate, one set of mocks and allows.
 
 import { isSelfOrigin, peerAddressClass } from '@ultimat3/core';
 import { NetworkOfflineError, NetworkRaceError, NetworkSealedError } from './errors';
 import type { MockHandler, MockRoute } from './mock-route';
-import { mockRoute, routeMatches } from './mock-route';
+import { mockRoute, routeMatches, routeNamesHost } from './mock-route';
 import type { LoggedRequest } from './request-log';
 import { hasStreamBody, headersOf, isOpenEnded, readBody, requestProbe } from './request-log';
+import type { DnsVerdict } from './sealed-dns';
+import { installDnsSeal } from './sealed-dns';
 import { installSocketSeal } from './sealed-sockets';
 
 export type FetchLike = typeof globalThis.fetch;
@@ -26,6 +27,8 @@ interface SealState {
   original: FetchLike | undefined;
   /** `installSocketSeal`'s undo, held beside `original` so one unseal restores all three dials. */
   restoreSockets: (() => void) | undefined;
+  /** `installDnsSeal`'s undo, likewise. */
+  restoreDns: (() => void) | undefined;
   network: NetworkState;
 }
 
@@ -35,9 +38,17 @@ const state: SealState = {
   log: [],
   original: undefined,
   restoreSockets: undefined,
+  restoreDns: undefined,
   network: 'online',
 };
 
+/**
+ * What a mocked host resolves to: one `public` address (`classifyAddress`), so an SSRF screen
+ * passes it, and never a host network — a screen refuses those. Never dialled: a dial pinned to it
+ * carries the name in `Host`, which is how the mock answers it (`mock-route.ts`'s `namedUrl`).
+ */
+export const MOCKED_HOST_ADDRESS = '11.11.11.11';
+
 const urlOf = (input: RequestInfo | URL): string => {
   if (typeof input === 'string') return input;
   if (input instanceof URL) return input.toString();
@@ -82,12 +93,40 @@ const socketRefusal = (url: string, method: string): Error | undefined => {
   return new NetworkSealedError({ url, method, allowed: [...state.allowed], transport: 'socket' });
 };
 
-/** Replace global fetch, `WebSocket` and `Bun.connect`. Idempotent: sealing twice keeps the one
- *  set of originals around. */
+/** A host the allow-list names, whatever port it was allowed on: a lookup carries no port. */
+const isAllowedName = (hostname: string): boolean =>
+  [...state.allowed].some((host) => safeHost(`https://${host}`)?.split(':')[0] === hostname);
+
+/**
+ * The resolver's gate, in `fetch`'s order: offline refuses every name, this machine and an allowed
+ * host resolve for real, a host a mock answers resolves to `MOCKED_HOST_ADDRESS`, the rest is
+ * `X_TEST_NETWORK_SEALED` — the code `fetch` would have raised a moment later.
+ */
+const dnsVerdict = (hostname: string): DnsVerdict => {
+  const name = hostname.toLowerCase().replace(/^\[|\]$/g, '');
+  const url = `dns://${name}`;
+  if (state.network !== 'online') {
+    return { refused: new NetworkOfflineError({ url, method: 'LOOKUP', mode: state.network }) };
+  }
+  if (isThisMachine(name) || peerAddressClass(name) !== undefined || isAllowedName(name)) {
+    return { real: true };
+  }
+  if (state.mocks.some((route) => routeNamesHost(route, name))) {
+    return { answer: [MOCKED_HOST_ADDRESS] };
+  }
+  const allowed = [...state.allowed];
+  return {
+    refused: new NetworkSealedError({ url, method: 'LOOKUP', allowed, transport: 'dns' }),
+  };
+};
+
+/** Replace global fetch, `WebSocket`, `Bun.connect` and the resolvers. Idempotent: sealing twice
+ *  keeps the one set of originals around. */
 export function sealNetwork(): void {
   if (state.original !== undefined) return;
   state.original = globalThis.fetch;
   state.restoreSockets = installSocketSeal(socketRefusal);
+  state.restoreDns = installDnsSeal(dnsVerdict);
   globalThis.fetch = (async (input: RequestInfo | URL, init?: RequestInit): Promise<Response> => {
     const url = urlOf(input);
     const method = methodOf(input, init);
@@ -151,6 +190,8 @@ export function unsealNetwork(): void {
   state.original = undefined;
   state.restoreSockets?.();
   state.restoreSockets = undefined;
+  state.restoreDns?.();
+  state.restoreDns = undefined;
 }
 
 /** Whether the patch is installed. The `network` fixture seals before going offline, so that

package/src/seed-graph-values.ts

@@ -152,6 +152,12 @@ const parsed = (column: SeedColumn, value: unknown): { readonly ok: unknown } |
   }
 };
 
+/**
+ * What every driver binds as SQL NULL — a JSON `null` included (`pg-row.ts` `bindable`): `t.json()`
+ * accepts it and the sampler draws it, so a NOT NULL `jsonb` column must never be offered one.
+ */
+const storesAsSqlNull = (value: unknown): boolean => value === null || value === undefined;
+
 /**
  * Every storable value for this column, most plausible first: the declared default, then what the
  * kind offers, then `null` when the column allows it. Empty means nothing generated is storable.
@@ -167,9 +173,8 @@ export function candidatesFor(
   const out: unknown[] = [];
   for (const value of raw) {
     const result = parsed(column, value);
-    if (result !== undefined && !out.some((seen) => Bun.deepEquals(seen, result.ok))) {
-      out.push(result.ok);
-    }
+    if (result === undefined || (meta.notNull && storesAsSqlNull(result.ok))) continue;
+    if (!out.some((seen) => Bun.deepEquals(seen, result.ok))) out.push(result.ok);
   }
   return keepsPatternsFirst(out, ctx.patterns ?? []);
 }