@ultimat3/testing 30.3.0 → 30.5.0

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/plan-oracle.ts

@@ -72,9 +72,12 @@ export function planRoot(answer: unknown): unknown {
 
 const IDENT = /(?:"?([A-Za-z_][\w$]*)"?\.)?"?([A-Za-z_][\w$]*)"?/g;
 const EQUALITY = /(?<![<>!])=(?!>)/;
+/** `IS NULL` pins one value as `=` does, and a btree serves it as an index condition. */
+const IS_NULL = /\bIS\s+NULL\b/i;
 
 /**
- * The columns of `scan` a condition names, split by how they are compared. A conjunct qualified by
+ * The columns of `scan` a condition names, split by how they are compared: `=` and `IS NULL` are
+ * equality, anything else a range. A conjunct qualified by
  * another alias is a join's other side; an unqualified name counts when the table has the column.
  */
 function columnsIn(
@@ -86,7 +89,7 @@ function columnsIn(
   const range: string[] = [];
   for (const condition of conditions) {
     for (const conjunct of condition.split(/\bAND\b/)) {
-      const into = EQUALITY.test(conjunct) ? equality : range;
+      const into = EQUALITY.test(conjunct) || IS_NULL.test(conjunct) ? equality : range;
       for (const [, qualifier, name] of conjunct.replace(/'[^']*'/g, '').matchAll(IDENT)) {
         if (name === undefined || !columns.has(name)) continue;
         if (qualifier !== undefined && qualifier !== scan.alias && qualifier !== scan.table)

package/src/plan-sweep-fix.ts

@@ -18,20 +18,66 @@ export interface PlanFinding {
 }
 
 /** Every column set the table holds unique: the primary key, unique columns, total unique rules. */
-function uniqueKeys(entity: SeedEntity): readonly (readonly string[])[] {
+function uniqueKeys(entity: SeedEntity, statement: string): readonly (readonly string[])[] {
   const description = entity.$describe();
+  const holds = (where: string | null): boolean => where === null || stated(where, statement);
   return [
     description.primaryKey,
     ...description.columns.filter((column) => column.unique).map((column) => [column.column]),
     ...description.indexes
-      .filter((index) => index.unique && index.where === null)
+      .filter((index) => index.unique && holds(index.where))
       .map((index) => index.columns),
     ...description.invariants
-      .filter((rule) => rule.kind === 'unique' && rule.where === null)
+      .filter((rule) => rule.kind === 'unique' && holds(rule.where))
       .map((rule) => rule.columns),
   ].filter((key) => key.length > 0);
 }
 
+/** Lower case outside literals, no identifier quotes, no parentheses, single spaces. */
+const normalized = (sql: string): string =>
+  sql
+    .split(/('[^']*')/)
+    .map((part, at) => (at % 2 === 1 ? part : part.toLowerCase().replace(/["()]/g, ' ')))
+    .join('')
+    .replace(/\s+/g, ' ')
+    .trim();
+
+/**
+ * A partial rule holds for a statement that states its predicate, conjunct for conjunct:
+ * `deleted_at is null` is in every soft-deleted entity's `one()`. Text, so a predicate the
+ * statement implies some other way is not credited — a finding, never a false pass.
+ */
+function stated(where: string, statement: string): boolean {
+  const text = ` ${normalized(statement)} `;
+  return normalized(where)
+    .split(/\band\b/)
+    .every((conjunct) => text.includes(` ${conjunct.trim()} `));
+}
+
+/** Every non-partial index the entity declares, in column order: primary key and unique ones too. */
+function declaredIndexes(entity: SeedEntity, statement: string): readonly (readonly string[])[] {
+  const description = entity.$describe();
+  return [
+    ...uniqueKeys(entity, statement),
+    ...description.indexes.filter((index) => index.where === null).map((index) => index.columns),
+  ];
+}
+
+/**
+ * A walk filtered by a range is served by an index that leads with the equality columns and then
+ * a range column: it bounds the rows and the planner sorts the few left. A generic plan with sorts
+ * off still prefers the ordered walk, so the oracle cannot see it. Credited, never re-proven.
+ */
+const servedByRange = (keys: readonly (readonly string[])[], verdict: PlanVerdict): boolean =>
+  keys.some((key) => {
+    const next = key[verdict.equality.length];
+    return (
+      next !== undefined &&
+      verdict.range.includes(next) &&
+      key.slice(0, verdict.equality.length).every((column) => verdict.equality.includes(column))
+    );
+  });
+
 const IDENTIFIER = /"([A-Za-z_][\w$]*)"|\b([A-Za-z_][\w$]*)\b/g;
 
 /**
@@ -95,16 +141,22 @@ export function planFindings(
     const entity = byTable.get(verdict.table);
     if (entity === undefined) return [];
     if (verdict.code === 'X_QUERY_UNINDEXED' && sorted.has(verdict.table)) return [];
-    const pinned = uniqueKeys(entity).some((key) =>
+    const pinned = uniqueKeys(entity, statement).some((key) =>
       key.every((column) => verdict.equality.includes(column)),
     );
     if (pinned) return [];
     const description = entity.$describe();
     const byColumn = new Map(description.columns.map((c) => [c.column, c.property]));
     const walked = verdict.code === 'X_QUERY_UNINDEXED' && verdict.node !== 'Seq Scan';
-    const order = walked
-      ? orderOf(statement, new Set(description.columns.map((c) => c.column)))
-      : verdict.order;
+    // A walk filtered by a range already has its order: what it lacks is the bound. A btree serves
+    // no order after a range column, so the index is the equality columns, then the range.
+    const ranged = walked && verdict.range.length > 0;
+    if (ranged && servedByRange(declaredIndexes(entity, statement), verdict)) return [];
+    const order = ranged
+      ? []
+      : walked
+        ? orderOf(statement, new Set(description.columns.map((c) => c.column)))
+        : verdict.order;
     if (servedByPartial(entity, verdict, order)) return [];
     const tenant = description.columns.find((c) => c.property === entity.$tenantColumn)?.column;
     const lead = tenant !== undefined && verdict.equality.includes(tenant) ? [tenant] : [];

package/src/plan-sweep-report.ts

@@ -24,7 +24,25 @@ const excerpt = (statement: string): string =>
 const indexLine = (finding: PlanFinding): string =>
   `indexes: [{ on: [${finding.index.map((p) => `'${p}'`).join(', ')}] }]`;
 
+/**
+ * A read that compares no column of the table — a whole-table count, an unfiltered export — is
+ * narrowed by no index: `on: []` is a line `x db gen` refuses. What ends it is saying why it may
+ * read every row, around the call or on the entity, or giving it a condition.
+ */
+function wholeRead(finding: PlanFinding, senders: readonly ExerciseRecord[]): SweepFinding {
+  const by = senders.map(primitive).join(', ');
+  const entity = renderFixLiteral(finding.entity, '<entity>');
+  const rerun = renderFixShellArg(senders[0]?.name ?? '', '<primitive>');
+  return {
+    code: finding.code,
+    cause: `${by} sent ${renderCauseValue(excerpt(finding.statement))}, which reads ${finding.table} whole (${finding.node}) and compares no column of it: no index narrows it, so it slows with every row the table gains`,
+    fix: `x exercise ${rerun} --json   # after expectedSeqScan('<why it reads every row>', fn) around the read, or scan: '<why it stays small>' in entity(${entity}), or a where clause that bounds it`,
+    at: senders[0] === undefined ? finding.entity : primitive(senders[0]),
+  };
+}
+
 function planFinding(finding: PlanFinding, senders: readonly ExerciseRecord[]): SweepFinding {
+  if (finding.index.length === 0) return wholeRead(finding, senders);
   const by = senders.map(primitive).join(', ');
   const entity = renderFixLiteral(finding.entity, '<entity>');
   const name = renderFixShellArg(`${finding.table}-${finding.index.join('-')}-index`, '<name>');
@@ -72,9 +90,10 @@ export function planSweepFindings(records: readonly ExerciseRecord[]): readonly
 /** One line per red: `action listPosts · X_QUERY_UNINDEXED posts on [orgId, authorId]`. */
 export function planSweepLines(records: readonly ExerciseRecord[]): readonly string[] {
   return records.flatMap((record) => [
-    ...(record.plans?.findings ?? []).map(
-      (finding) =>
-        `${primitive(record)} · ${finding.code} ${finding.table} on [${finding.index.join(', ')}]`,
+    ...(record.plans?.findings ?? []).map((finding) =>
+      finding.index.length === 0
+        ? `${primitive(record)} · ${finding.code} ${finding.table}, every row (no column to index)`
+        : `${primitive(record)} · ${finding.code} ${finding.table} on [${finding.index.join(', ')}]`,
     ),
     ...(record.scale?.verdict === 'grows' ? record.scale.shapes : []).map(
       (shape) =>

package/src/registry-leak-guard.ts

@@ -39,7 +39,7 @@ import {
  *   | locales / catalogs | `resetCatalogs` | `@ultimat3/i18n` | yes |
  *   | permissions / roles | `restorePermissions` / `restoreRoles` | `@ultimat3/policy` | yes |
  *   | routes | `clearRoutes` | `@ultimat3/render` | **no** |
- *   | jobs | `resetJobs` | `@ultimat3/jobs` | **no** |
+ *   | jobs | `resetJobs` / `restoreJobs` | `@ultimat3/jobs` | **no** — isolated per test |
  *   | tasks | `restoreTasks` | `@ultimat3/jobs` | yes (22.7) |
  *   | measurement actor | `resetMeasurementActor` | `@ultimat3/core` | yes |
  *   | actions | `resetActions` | `@ultimat3/action` | **no** |
@@ -50,7 +50,7 @@ import {
  *
  * Every "no" needs the SAME two halves the two "yes" rows have: a reader and a writer in the owning
  * package (`restorePermissions` was added to `@ultimat3/policy` for exactly this), and one line
- * here. `@ultimat3/jobs`, `@ultimat3/action`, `@ultimat3/query` and `@ultimat3/mail` publish a
+ * here. `@ultimat3/action`, `@ultimat3/query` and `@ultimat3/mail` publish a
  * lister and a reset but no restore, so the change is theirs first and this file's second — and it
  * has to land as ONE change, because the cost of the rest is a second edit of this same shape.
  */

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

@@ -1,7 +1,7 @@
 // Insert order for a seed graph: every parent before its children, over the foreign keys the
-// entities themselves resolve (`$references()`, the record `relationsOf` is built from). A cycle is
-// broken at a NULLABLE edge — inserted null, set by an update once its target exists; a cycle with
-// no nullable edge is refused, because no insert order can satisfy it.
+// entities themselves resolve (`$references()`). A cycle is broken at a NULLABLE edge — inserted
+// null, set by an update once its target exists — preferring a table that takes updates (never
+// `appendOnly`); a cycle with no nullable edge is refused: no insert order can satisfy it.
 
 import type { ReferenceDescription } from '@ultimat3/entity';
 import { seedGraphUnsatisfied } from './seed-graph-error';
@@ -9,6 +9,8 @@ import { seedGraphUnsatisfied } from './seed-graph-error';
 export interface OrderInput {
   readonly name: string;
   readonly references: readonly ReferenceDescription[];
+  /** False for a table whose rows are never updated (`appendOnly`). Default true. */
+  readonly updatable?: boolean;
 }
 
 export interface InsertOrder {
@@ -44,6 +46,7 @@ const reaches = (
 export function insertOrder(entities: readonly OrderInput[]): InsertOrder {
   const names = new Set(entities.map((entity) => entity.name));
   const edges = new Map(entities.map((entity) => [entity.name, entity.references]));
+  const frozen = new Set(entities.filter((e) => e.updatable === false).map((e) => e.name));
   const deferred = new Set<string>();
   // A self-reference never orders anything: the row's own table is already being written.
   const live = (from: string, reference: ReferenceDescription): boolean =>
@@ -76,9 +79,10 @@ export function insertOrder(entities: readonly OrderInput[]): InsertOrder {
             !placed.has(reference.targetEntity) &&
             reaches(edges, live, reference.targetEntity, name),
         )
-        .map((reference) => edgeKey(name, reference.property)),
+        .map((reference) => [name, edgeKey(name, reference.property)] as const),
     );
-    const edge = breakable[0];
+    // Name order still decides between equals, so the same set always breaks at the same edge.
+    const edge = (breakable.find(([name]) => !frozen.has(name)) ?? breakable[0])?.[1];
     if (edge === undefined) {
       const cyclic = stuck.filter((name) =>
         (edges.get(name) ?? []).some(