@ultimat3/testing 30.4.0 → 30.6.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 |
@@ -46,10 +46,10 @@ import is `registry-isolation.ts`, own entry point, off the barrel. Full rule: `
 | Injection | `SqlRunner` and `connect` are parameters, so unit tests need no server |
 | Fixtures | the preload registers the framework bag — an app registers only what it alone knows (`seed`, `actorFor`) |
 | Every `e2eTest` is audited | `e2e-a11y.ts` (rules), `e2e-a11y-run.ts` (per-test run, `allow`, dedupe), `ax-node.ts` (the one AX reader); the full tree is read only in `cdp-e2e-page.ts` (`FULL_AX_TREE`, a convention). No switch; `allow` needs a non-blank `because`. And every raw tab: `e2e-a11y-tabs.ts`, checked after each `goto`/`reload` and at the test's end from the preload's `afterEach`; exceptions are `allowA11y([{ role, selector, because }])` |
-| 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) |
+| 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). A job runs ALONE (`exercise-job-run.ts`): a fresh queue, one `tick()`, what it queued left on the caller's queue unrun — never a `drain()` |
 | 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). Its world is `alone`: only the job's own row is claimed, a child is an `enqueue:` effect, never run. 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.6.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.6.0",
+    "@ultimat3/cache": "30.6.0",
+    "@ultimat3/core": "30.6.0",
+    "@ultimat3/db": "30.6.0",
+    "@ultimat3/entity": "30.6.0",
+    "@ultimat3/http": "30.6.0",
+    "@ultimat3/i18n": "30.6.0",
+    "@ultimat3/jobs": "30.6.0",
+    "@ultimat3/mail": "30.6.0",
+    "@ultimat3/policy": "30.6.0",
+    "@ultimat3/pwa": "30.6.0",
+    "@ultimat3/query": "30.6.0",
+    "@ultimat3/realtime": "30.6.0",
+    "@ultimat3/render": "30.6.0",
+    "@ultimat3/schema": "30.6.0",
+    "@ultimat3/time": "30.6.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-job-run.ts

@@ -0,0 +1,68 @@
+// A job primitive's one execution, as the exercise pass runs it: ALONE, on a queue that holds nothing
+// else, for one worker pass. What it enqueues is handed back to the caller's queue unrun, exactly as
+// an action's enqueues are — counted there as `enqueue` effects, searched by the tenant proof, and
+// never executed inside the subject's room, so a child's statements are never the subject's.
+
+import type { Actor } from '@ultimat3/core';
+import { assert } from '@ultimat3/core';
+import type { AnyJobHandle, JobExecution, JobRecord } from '@ultimat3/jobs';
+import { jobCursor, jobDriver, MAX_JOB_PAGE, registeredJobs } from '@ultimat3/jobs';
+import type { RunJobs } from './fixture-jobs';
+import { testJobs } from './fixture-jobs';
+
+const QUEUED: ReadonlySet<string> = new Set(['ready', 'delayed']);
+
+/** Every row the AMBIENT driver holds, page by page: what a fixture's queue has, finished or not. */
+export async function ambientJobRows(): Promise<readonly JobRecord[]> {
+  const introspect = jobDriver()?.introspect;
+  if (introspect === undefined) return [];
+  const records: JobRecord[] = [];
+  for (let after: string | undefined; ; ) {
+    const page = await introspect.list({
+      limit: MAX_JOB_PAGE,
+      ...(after === undefined ? {} : { after }),
+    });
+    records.push(...page);
+    const last = page[page.length - 1];
+    if (last === undefined || page.length < MAX_JOB_PAGE) break;
+    after = jobCursor(last);
+  }
+  return records;
+}
+
+/**
+ * `handle` run once with `input` in `tenant`, as `actor`'s worker: enqueued on a fresh queue and
+ * claimed by ONE pass, so the only run is its own — never a job `into` already held (an earlier
+ * call's, an earlier primitive's) and never one it queued. Those it queued land on `into`, unrun.
+ */
+export async function runJobAlone(
+  handle: AnyJobHandle,
+  input: unknown,
+  at: { readonly actor: Actor | null; readonly tenant: string },
+  into: RunJobs,
+): Promise<JobExecution | undefined> {
+  let own: JobExecution | undefined;
+  let queued: readonly JobRecord[];
+  {
+    await using alone = await testJobs();
+    const row = await alone.enqueue(handle, input, { tenantId: at.tenant });
+    const trace = await alone.tick(at.actor === null ? {} : { actor: at.actor });
+    own = trace.executions.find((run) => run.jobId === row.id);
+    queued = (await ambientJobRows()).filter(
+      (record) => record.id !== row.id && QUEUED.has(record.state),
+    );
+  }
+  const handles = new Map(registeredJobs().map((one) => [one.name, one]));
+  for (const record of queued) {
+    const child = handles.get(record.name);
+    assert(
+      child !== undefined,
+      `job "${handle.name}" queued job "${record.name}" but nothing registered it`,
+      `import the module that declares job("${record.name}") from the app's api module — the registry is populated by the import, not by the queue`,
+    );
+    await into.enqueue(child, record.input, {
+      ...(record.tenantId === undefined ? {} : { tenantId: record.tenantId }),
+    });
+  }
+  return own;
+}

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-subjects.ts

@@ -1,6 +1,7 @@
 // The primitives an exercise pass drives, each as one call: every registered action, query and job,
 // loaded on demand. A job is enqueued in the tenant it is called for, its input SEATED there first
-// (`exercise-job-tenant.ts`): a drawn org is a random one, and the enqueue refuses it.
+// (`exercise-job-tenant.ts`): a drawn org is a random one, and the enqueue refuses it. It runs
+// alone (`exercise-job-run.ts`): what it queues is left queued, as an action's is.
 
 import type { Actor } from '@ultimat3/core';
 import { renderCauseValue, renderFixShellArg, UltimateError } from '@ultimat3/core';
@@ -8,6 +9,7 @@ import type { AnyJobHandle, JobExecution } from '@ultimat3/jobs';
 import { registeredJobs } from '@ultimat3/jobs';
 import type { Policy } from '@ultimat3/policy';
 import type { StandardSchemaV1 } from '@ultimat3/schema';
+import { runJobAlone } from './exercise-job-run';
 import type { JobTenantBinding } from './exercise-job-tenant';
 import { bindJobTenant } from './exercise-job-tenant';
 import { withExerciseRequest } from './exercise-request';
@@ -84,9 +86,9 @@ const jobSubject = (handle: AnyJobHandle): Subject => ({
   handle,
   seat: (input, tenant) => bindJobTenant(handle, input, tenant),
   call: async (input, actor, tenant, jobs) => {
-    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);
+    // Its own execution and nothing else: a drain of `jobs` ran what it queued (one child per row,
+    // which the scale sweep read as the job's loop) and whatever an earlier call had left there.
+    const own = await runJobAlone(handle, input, { actor, tenant }, jobs);
     // 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)

package/src/exercise.ts

@@ -8,13 +8,13 @@
 
 import type { Actor, ExerciseAttempt, ExerciseVerdict } from '@ultimat3/core';
 import { isUltimateError, renderThrowable, runExercise } from '@ultimat3/core';
-import type { JobExecution, JobRecord } from '@ultimat3/jobs';
 import { registeredJobs } from '@ultimat3/jobs';
 import type { ExerciseOverride, ExerciseOverrides } from './define-exercise';
 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,
@@ -24,6 +24,7 @@ import {
   namesActorEntity,
   seededIds,
 } from './exercise-input';
+import { ambientJobRows } from './exercise-job-run';
 import type { OverrideInput } from './exercise-override-input';
 import { overrideInput } from './exercise-override-input';
 import type {
@@ -75,13 +76,15 @@ const codeOf = (error: unknown): string | undefined => {
 const reasonOf = (error: unknown): string =>
   isUltimateError(error) ? error.cause : typeof error === 'string' ? error : renderThrowable(error);
 
-/** Jobs queued or run by the primitive, the primitive's own job excepted. */
-async function enqueued(subject: Subject, jobs: RunJobs, runs: readonly JobExecution[]) {
+/**
+ * Jobs the primitive queued, its own job excepted. Never run: a job's children are left queued as
+ * an action's are (`exercise-job-run.ts`), so their statements are theirs, never this record's.
+ */
+async function enqueued(subject: Subject, jobs: RunJobs) {
   const effects: ExerciseEffect[] = [];
   for (const handle of registeredJobs()) {
     if (subject.kind === 'job' && handle.name === subject.name) continue;
-    const ran = new Set(runs.filter((run) => run.job === handle.name).map((r) => r.jobId)).size;
-    const count = ran + (await jobs.depth(handle));
+    const count = await jobs.depth(handle);
     if (count > 0) effects.push({ kind: 'enqueue', job: handle.name, count });
   }
   return effects;
@@ -92,21 +95,7 @@ async function enqueued(subject: Subject, jobs: RunJobs, runs: readonly JobExecu
  * input is what B was handed. Read off the leg's own queue, page by page.
  */
 async function queuedPayloads(subject: Subject): Promise<readonly EffectPayload[]> {
-  const jobs = await import('@ultimat3/jobs');
-  const introspect = jobs.jobDriver()?.introspect;
-  if (introspect === undefined) return [];
-  const records: JobRecord[] = [];
-  for (let after: string | undefined; ; ) {
-    const page = await introspect.list({
-      limit: jobs.MAX_JOB_PAGE,
-      ...(after === undefined ? {} : { after }),
-    });
-    records.push(...page);
-    const last = page[page.length - 1];
-    if (last === undefined || page.length < jobs.MAX_JOB_PAGE) break;
-    after = jobs.jobCursor(last);
-  }
-  return records
+  return (await ambientJobRows())
     .filter((record) => !(subject.kind === 'job' && record.name === subject.name))
     .map((record, i) => ({
       path: `effect.enqueue[${i}]`,
@@ -173,7 +162,6 @@ async function control(
   let lastError: unknown;
   let lastInput: unknown;
   let output: unknown;
-  let executions: readonly JobExecution[] = [];
   room.begin(name);
   const started = performance.now();
   const verdict = await runExercise({
@@ -208,11 +196,23 @@ async function control(
     statusOf: (await import('@ultimat3/http')).statusFor,
   });
   const ms = Math.round(performance.now() - started);
-  if (kind === 'job') executions = (await jobs.drain()).executions;
   const observed = room.end();
-  const effects = [...observed.effects, ...(await enqueued(subject, jobs, executions))];
+  const effects = [...observed.effects, ...(await enqueued(subject, jobs))];
   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/fixture-jobs.ts

@@ -69,6 +69,11 @@ export interface RunJobs extends AsyncDisposable {
   enqueue<I>(handle: JobHandle<I>, input: I, options?: JobEnqueueAs): Promise<EnqueueResult>;
   /** Claim and execute everything due at the current instant, until nothing is. */
   drain(options?: JobDrainAs): Promise<JobRunTrace>;
+  /**
+   * ONE worker pass: what is due now runs, and what those runs enqueue waits for the next pass —
+   * "it queued one child per row" asserted without running a child.
+   */
+  tick(options?: JobDrainAs): Promise<JobRunTrace>;
   /** Live jobs — ready, delayed, running or suspended — optionally for one job only. */
   depth(handle?: AnyJobHandle): Promise<number>;
   /** Live jobs claimable right now. `clock.advance()` is what turns delayed into due. */
@@ -194,14 +199,20 @@ export async function testJobs(): Promise<RunJobs> {
   /** Every execution this fixture has driven, because the trace is cumulative. */
   const history: JobExecution[] = [];
 
+  const ctxFor = (options: JobDrainAs): Ctx =>
+    options.actor === undefined ? anonymousWorker : ctxOf({ role: 'worker', actor: options.actor });
+  const traced = (): JobRunTrace => ({ executions: [...history], steps: tallyOf(history) });
+
+  const tick = async (options: JobDrainAs = {}): Promise<JobRunTrace> => {
+    history.push(...(await round(ctxFor(options))));
+    return traced();
+  };
+
   const drain = async (options: JobDrainAs = {}): Promise<JobRunTrace> => {
-    const ctx =
-      options.actor === undefined
-        ? anonymousWorker
-        : ctxOf({ role: 'worker', actor: options.actor });
+    const ctx = ctxFor(options);
     for (let rounds = 0; rounds < MAX_ROUNDS; rounds += 1) {
       const batch = await round(ctx);
-      if (batch.length === 0) return { executions: [...history], steps: tallyOf(history) };
+      if (batch.length === 0) return traced();
       history.push(...batch);
     }
     assert(
@@ -239,6 +250,7 @@ export async function testJobs(): Promise<RunJobs> {
   return Object.assign(enqueueThenDrain, {
     enqueue,
     drain,
+    tick,
     depth: async (handle?: AnyJobHandle) => (await live(handle?.name)).length,
     due: async () =>
       (await live()).filter(

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;
 }
 
@@ -132,7 +134,10 @@ async function runOnce<I>(
     if (op.step.startsWith(COMPENSATE_PREFIX)) compensated.push(op.step);
     else if (op.step !== UNWINDING_STEP) forward.add(op.step);
   };
+  // Alone: a child the job queues is its enqueue effect, never run — the clean run that ran it
+  // first wrote its rows, and every killed run after found them there (0× against 6×).
   await using world = await openSimWorld({
+    alone: true,
     seed: finiteCount('crashProof', 'seed', options.seed ?? 1),
     decide,
     landed,
@@ -155,8 +160,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 +188,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 +243,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

@@ -31,6 +31,8 @@ export const SIM_VISIBILITY_MS = 30_000;
 const RENEW_MS = 1;
 const CLAIM_LIMIT = 64;
 const LIVE: ReadonlySet<string> = new Set(['ready', 'delayed', 'running', 'suspended']);
+/** Where an `alone` world files the harness's row: no body enqueues here, so no worker claims theirs. */
+const HARNESS_QUEUE = 'x-sim-harness';
 
 export interface SimWorldOptions {
   /** Seeds `Math.random` for the run: a body's jitter and draws are the seed's. */
@@ -40,6 +42,11 @@ export interface SimWorldOptions {
   decide(op: SimOp): SimDecision | Promise<SimDecision>;
   /** Told every landed call, after the world has read it. */
   landed?(op: SimOp, answer: unknown): void;
+  /**
+   * Only the row the harness filed is ever claimed: what a body enqueues lands, dedupes and is an
+   * `enqueue:` effect, and never runs — its effects are its own job's, not this run's.
+   */
+  readonly alone?: boolean;
 }
 
 export interface SimWorld extends AsyncDisposable {
@@ -86,7 +93,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) => {
@@ -112,9 +122,11 @@ export async function openSimWorld(options: SimWorldOptions): Promise<SimWorld>
   const anonymous = ctxOf({ role: 'worker' });
   const context = options.context ?? (() => anonymous);
 
-  const queues = (): readonly string[] => [
-    ...new Set([jobs.DEFAULT_QUEUE, ...jobs.registeredJobs().map((handle) => handle.queue)]),
-  ];
+  const queues = (): readonly string[] =>
+    options.alone === true
+      ? [HARNESS_QUEUE]
+      : [...new Set([jobs.DEFAULT_QUEUE, ...jobs.registeredJobs().map((handle) => handle.queue)])];
+  const claimable = new Set(queues());
 
   const rows = async (): Promise<readonly JobRecord[]> => {
     const all: JobRecord[] = [];
@@ -143,7 +155,7 @@ export async function openSimWorld(options: SimWorldOptions): Promise<SimWorld>
     enqueue: async (handle, input) => {
       const result = await base.enqueue({
         name: handle.name,
-        queue: handle.queue,
+        queue: options.alone === true ? HARNESS_QUEUE : handle.queue,
         input,
         idempotencyKey: handle.idempotencyKeyFor(input),
         maxAttempts: jobs.enqueuedAttempts(handle.retry, handle.compensates),
@@ -176,7 +188,9 @@ export async function openSimWorld(options: SimWorldOptions): Promise<SimWorld>
     rows,
     nextDue: async () => {
       const due = (await rows())
-        .filter((row) => LIVE.has(row.state))
+        .filter(
+          (row) => LIVE.has(row.state) && (options.alone !== true || claimable.has(row.queue)),
+        )
         .map((row) => (row.state === 'running' ? (row.visibleAt ?? row.runAt) : row.runAt));
       return due.length === 0 ? undefined : Math.min(...due);
     },

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 ?? []);
 }