@ultimat3/testing 29.4.0 → 30.0.0

package/src/scale-sweep-graph.ts

@@ -0,0 +1,82 @@
+// One tenant's rows at a chosen size, written beside the pass's graph in the same database. Its rows
+// of no tenant (`plans`) are NOT written again — a second copy collides on their unique keys — so
+// every reference to one is pointed at the pass's own row in the same position. Pure.
+
+import { seedGraph } from './seed-graph';
+import type { SeedGraph } from './seed-graph-plan';
+import type { SeedEntity } from './seed-graph-shape';
+
+export interface ScaleGraph {
+  /** The one tenant the sized rows belong to. */
+  readonly tenant: string;
+  /** What to write: the sized tenant's rows, references to rows of no tenant rewritten. */
+  readonly write: SeedGraph;
+  /** What an id lookup reads: the written rows and the pass's rows of no tenant they point at. */
+  readonly lookup: SeedGraph;
+}
+
+/**
+ * `seedGraph` at `perTable` rows for one tenant, rows of no tenant swapped for `main`'s. The i-th
+ * such row of an entity becomes `main`'s (i mod n)-th: a reference keeps pointing at a row that
+ * exists, and two rows that pointed at one row still do.
+ */
+export function scaleGraph(
+  main: SeedGraph,
+  entities: readonly SeedEntity[],
+  options: { readonly perTable: number; readonly seed: number },
+): ScaleGraph {
+  const sized = seedGraph(Object.fromEntries(entities.map((entity) => [entity.$name, entity])), {
+    tenants: 1,
+    perTable: options.perTable,
+    seed: options.seed,
+  });
+  const shared = (graph: SeedGraph) => graph.inserts.filter((insert) => insert.tenant === null);
+  const theirs = shared(main);
+  // (entity, property, value in the sized graph) → the pass's value at the same position.
+  const swap = new Map<string, unknown>();
+  const key = (entity: string, property: string, value: unknown) =>
+    `${entity}\u0000${property}\u0000${JSON.stringify(value)}`;
+  const seen = new Map<string, number>();
+  for (const insert of shared(sized)) {
+    const pool = theirs.filter((row) => row.entity === insert.entity);
+    const at = seen.get(insert.entity) ?? 0;
+    seen.set(insert.entity, at + 1);
+    const target = pool[at % Math.max(1, pool.length)];
+    if (target === undefined) continue;
+    for (const [property, value] of Object.entries(insert.row)) {
+      swap.set(key(insert.entity, property, value), target.row[property]);
+    }
+  }
+  const references = new Map(
+    entities.map((entity) => [
+      entity.$name,
+      entity
+        .$references()
+        .map((ref) => [ref.property, ref.targetEntity, ref.targetProperty] as const),
+    ]),
+  );
+  const rewrite = (entity: string, row: Readonly<Record<string, unknown>>) => {
+    const out: Record<string, unknown> = { ...row };
+    for (const [property, target, targetProperty] of references.get(entity) ?? []) {
+      const swapped = key(target, targetProperty, row[property]);
+      if (property in row && swap.has(swapped)) out[property] = swap.get(swapped);
+    }
+    return out;
+  };
+  const kept = sized.inserts.flatMap((insert, i) =>
+    insert.tenant === null ? [] : [[insert, sized.canaries[i]] as const],
+  );
+  const write: SeedGraph = {
+    ...sized,
+    inserts: kept.map(([insert]) => ({ ...insert, row: rewrite(insert.entity, insert.row) })),
+    canaries: kept.flatMap(([, canary]) => (canary === undefined ? [] : [canary])),
+    updates: sized.updates
+      .filter((update) => update.tenant !== null)
+      .map((update) => ({ ...update, patch: rewrite(update.entity, update.patch) })),
+  };
+  return {
+    tenant: sized.tenants[0] as string,
+    write,
+    lookup: { ...write, inserts: [...theirs, ...write.inserts] },
+  };
+}

package/src/scale-sweep-run.ts

@@ -0,0 +1,134 @@
+// The scale sweep, run: two more tenants after the pass, one at 2 rows a table and one at 8, and
+// every reached primitive called once in each, in the same order — whatever an earlier call wrote,
+// it wrote at both sizes. A shape whose count grows with the rows is `judgeScale`'s red.
+
+import type { Actor } from '@ultimat3/core';
+import { fnv1a, renderThrowable } from '@ultimat3/core';
+import type { ExerciseRoom } from './exercise-report';
+import type { RunJobs } from './fixture-jobs';
+import { testJobs } from './fixture-jobs';
+import type { ScaleProof, StatementTally } from './scale-sweep';
+import { judgeScale, SCALE_SIZES } from './scale-sweep';
+import { scaleGraph } from './scale-sweep-graph';
+import type { SeedGraph, SeedWriter } from './seed-graph-plan';
+import { insertSeedGraph } from './seed-graph-plan';
+import type { SeedEntity } from './seed-graph-shape';
+
+/** What the sweep needs of a primitive: the pass's own call. */
+export interface ScaleSubject {
+  readonly name: string;
+  call(
+    input: unknown,
+    actor: Actor | null,
+    tenant: string,
+    jobs: RunJobs,
+  ): Promise<{ readonly failure?: unknown }>;
+}
+
+/**
+ * The pass's recipe for one call in `tenant` of `graph`: its actor and its input, or none. `self`
+ * binds a field naming the actor entity to the actor's own row, else to somebody else's — the two
+ * readings the control tries.
+ */
+export type ScaleSetup = (
+  subject: ScaleSubject,
+  graph: SeedGraph,
+  tenant: string,
+  self: boolean,
+) => Promise<{ readonly actor: Actor | null; readonly input: unknown } | undefined>;
+
+export interface ScaleSweepOptions {
+  readonly subjects: readonly ScaleSubject[];
+  readonly entities: readonly SeedEntity[];
+  readonly writer: SeedWriter;
+  readonly main: SeedGraph;
+  readonly seed: number;
+  readonly room: ExerciseRoom;
+  readonly setup: ScaleSetup;
+}
+
+type Call = { readonly shapes: readonly StatementTally[] } | { readonly failed: string };
+
+async function callAt(
+  subject: ScaleSubject,
+  graph: SeedGraph,
+  tenant: string,
+  options: ScaleSweepOptions,
+  self: boolean,
+): Promise<Call> {
+  let prepared: Awaited<ReturnType<ScaleSetup>>;
+  try {
+    prepared = await options.setup(subject, graph, tenant, self);
+  } catch (error) {
+    // An override's input is the app's code, run against this sized graph: its failure is this
+    // call's, never the sweep's.
+    return { failed: `its exercise.ts input threw: ${renderThrowable(error)}` };
+  }
+  if (prepared === undefined) return { failed: 'no actor its policy permits' };
+  await using jobs = await testJobs();
+  options.room.begin();
+  try {
+    const answer = await subject.call(prepared.input, prepared.actor, tenant, jobs);
+    const observed = options.room.end();
+    return 'failure' in answer ? { failed: renderThrowable(answer.failure) } : observed;
+  } catch (error) {
+    options.room.end();
+    return { failed: renderThrowable(error) };
+  }
+}
+
+/** Seed both sizes, call each subject at each, judge. Unseedable: every subject `unproven`. */
+export async function scaleSweep(
+  options: ScaleSweepOptions,
+): Promise<ReadonlyMap<string, ScaleProof>> {
+  const proofs = new Map<string, ScaleProof>();
+  if (options.subjects.length === 0) return proofs;
+  const sizes = [SCALE_SIZES.small, SCALE_SIZES.large].map((perTable, i) =>
+    // Hashed, never `seed + 1`: a later pass on the same database may be seeded with that number.
+    scaleGraph(options.main, options.entities, {
+      perTable,
+      seed: fnv1a(`scale:${options.seed}:${i}`) || 1,
+    }),
+  );
+  try {
+    for (const size of sizes) await insertSeedGraph(size.write, options.writer);
+  } catch (error) {
+    const reason = `the sized seed did not write: ${renderThrowable(error)}`;
+    for (const subject of options.subjects)
+      proofs.set(subject.name, { verdict: 'unproven', reason });
+    return proofs;
+  }
+  const runs: Call[][] = [];
+  // The reading that answered at the small size is the one the large size repeats.
+  const selves = options.subjects.map(() => true);
+  for (const [at, size] of sizes.entries()) {
+    const calls: Call[] = [];
+    for (const [i, subject] of options.subjects.entries()) {
+      let call = await callAt(subject, size.lookup, size.tenant, options, selves[i] ?? true);
+      if (at === 0 && 'failed' in call) {
+        const other = await callAt(subject, size.lookup, size.tenant, options, false);
+        if (!('failed' in other)) {
+          call = other;
+          selves[i] = false;
+        }
+      }
+      calls.push(call);
+    }
+    runs.push(calls);
+  }
+  options.subjects.forEach((subject, i) => {
+    const small = runs[0]?.[i];
+    const large = runs[1]?.[i];
+    if (small === undefined || large === undefined) return;
+    if ('failed' in small || 'failed' in large) {
+      const failed = 'failed' in small ? small.failed : 'failed' in large ? large.failed : '';
+      proofs.set(subject.name, {
+        verdict: 'unproven',
+        reason: `a sized call did not answer: ${failed}`,
+      });
+      return;
+    }
+    proofs.set(subject.name, judgeScale(small.shapes, large.shapes));
+  });
+  return proofs;
+}

package/src/scale-sweep.ts

@@ -0,0 +1,74 @@
+// The scale verdict: one primitive's statement shapes at a small seed and at a large one. A shape
+// sent more often when the tables hold more rows is a loop over rows — an N+1 no test named — and
+// red, unless `expectedQueryLoop` scoped it, which is reported with its reason. Pure: tallies in.
+
+/** One statement shape in one call: every statement, and the ones no `expectedQueryLoop` covered. */
+export interface StatementTally {
+  /** `statementFingerprint`: `posts.findById` when attributed, else the collapsed text. */
+  readonly fingerprint: string;
+  readonly count: number;
+  readonly unexpected: number;
+  /** The `expectedQueryLoop` reason in force when one of them was sent. */
+  readonly expected?: string;
+}
+
+/** A shape whose count moved between the two sizes. */
+export interface ScaleShape {
+  readonly fingerprint: string;
+  readonly small: number;
+  readonly large: number;
+  /** Present on a loop `expectedQueryLoop` declared: why it is deliberate. */
+  readonly reason?: string;
+}
+
+export type ScaleProof =
+  /** No shape grew; `expected` lists the declared loops that did, with their reasons. */
+  | { readonly verdict: 'flat'; readonly expected: readonly ScaleShape[] }
+  | {
+      readonly verdict: 'grows';
+      readonly shapes: readonly ScaleShape[];
+      readonly expected: readonly ScaleShape[];
+    }
+  /** A call at one size did not answer as at the other: the counts are not comparable. Never red. */
+  | { readonly verdict: 'unproven'; readonly reason: string };
+
+/** Rows a table per tenant at each size: a loop over them sends 2 statements, then 8. */
+export const SCALE_SIZES = { small: 2, large: 8 } as const;
+
+/**
+ * Per shape, the large run against the small one. Only unexpected statements are judged; a shape
+ * that grew only under an `expectedQueryLoop` is listed beside the verdict with its reason. A shape
+ * absent at the small size and present at the large one grew from zero.
+ */
+export function judgeScale(
+  small: readonly StatementTally[],
+  large: readonly StatementTally[],
+): ScaleProof {
+  const before = new Map(small.map((tally) => [tally.fingerprint, tally]));
+  const shapes: ScaleShape[] = [];
+  const expected: ScaleShape[] = [];
+  for (const after of large) {
+    const was = before.get(after.fingerprint);
+    if (after.unexpected > (was?.unexpected ?? 0)) {
+      shapes.push({
+        fingerprint: after.fingerprint,
+        small: was?.unexpected ?? 0,
+        large: after.unexpected,
+      });
+    } else if (after.count > (was?.count ?? 0) && after.expected !== undefined) {
+      expected.push({
+        fingerprint: after.fingerprint,
+        small: was?.count ?? 0,
+        large: after.count,
+        reason: after.expected,
+      });
+    }
+  }
+  const byName = (a: ScaleShape, b: ScaleShape): number =>
+    a.fingerprint.localeCompare(b.fingerprint);
+  shapes.sort(byName);
+  expected.sort(byName);
+  return shapes.length === 0
+    ? { verdict: 'flat', expected }
+    : { verdict: 'grows', shapes, expected };
+}

package/src/sealed-network.ts

@@ -3,8 +3,12 @@
 // 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.
 
-import { classifyAddress, isSelfOrigin } from '@ultimat3/core';
+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 type { LoggedRequest } from './request-log';
+import { hasStreamBody, headersOf, isOpenEnded, readBody, requestProbe } from './request-log';
 import { installSocketSeal } from './sealed-sockets';
 
 export type FetchLike = typeof globalThis.fetch;
@@ -15,16 +19,10 @@ export type FetchLike = typeof globalThis.fetch;
  */
 export type NetworkState = 'online' | 'offline' | 'dropped';
 
-export interface MockRoute {
-  /** Exact URL, or a prefix ending in `*`, or a RegExp. */
-  readonly match: string | RegExp;
-  readonly handler: (request: Request) => Response | Promise<Response>;
-}
-
 interface SealState {
   readonly allowed: Set<string>;
   readonly mocks: MockRoute[];
-  readonly seen: string[];
+  readonly log: LoggedRequest[];
   original: FetchLike | undefined;
   /** `installSocketSeal`'s undo, held beside `original` so one unseal restores all three dials. */
   restoreSockets: (() => void) | undefined;
@@ -34,22 +32,12 @@ interface SealState {
 const state: SealState = {
   allowed: new Set(),
   mocks: [],
-  seen: [],
+  log: [],
   original: undefined,
   restoreSockets: undefined,
   network: 'online',
 };
 
-const matches = (route: MockRoute, url: string): boolean => {
-  if (route.match instanceof RegExp) {
-    // A `g`/`y` pattern's `test` resumes at `lastIndex`: without the reset, every other call missed.
-    route.match.lastIndex = 0;
-    return route.match.test(url);
-  }
-  if (route.match.endsWith('*')) return url.startsWith(route.match.slice(0, -1));
-  return route.match === url;
-};
-
 const urlOf = (input: RequestInfo | URL): string => {
   if (typeof input === 'string') return input;
   if (input instanceof URL) return input.toString();
@@ -70,14 +58,14 @@ const methodOf = (input: RequestInfo | URL, init: RequestInit | undefined): stri
  */
 const isThisMachine = (hostname: string): boolean => {
   if (hostname.toLowerCase() === 'localhost') return true;
-  const kind = classifyAddress(hostname);
+  const kind = peerAddressClass(hostname);
   return kind === 'loopback' || kind === 'unspecified';
 };
 
 /** The socket dials' gate: the same allow-list, offline state and record as `fetch`. No mocks — a
  *  socket test injects its transport (`connect`, `client`), it does not intercept the dial. */
 const socketRefusal = (url: string, method: string): Error | undefined => {
-  state.seen.push(url);
+  state.log.push({ method, url, headers: {}, body: null });
   let target: URL;
   try {
     target = new URL(url);
@@ -102,34 +90,58 @@ export function sealNetwork(): void {
   state.restoreSockets = installSocketSeal(socketRefusal);
   globalThis.fetch = (async (input: RequestInfo | URL, init?: RequestInit): Promise<Response> => {
     const url = urlOf(input);
-    state.seen.push(url);
+    const method = methodOf(input, init);
+    const probe = requestProbe(input, init);
+    // In the log before the first await, so concurrent calls keep their order; every verdict below
+    // is reached before the body is awaited too, so a call is judged by the state it was made in.
+    const call = { method, url, headers: headersOf(probe), body: null as string | null };
+    state.log.push(call);
+    const openEnded = isOpenEnded(input, init);
+    /** A finite body is in the entry when `fetch` settles; an open-ended one, once it ends. */
+    const logBody = async (source: Request | undefined): Promise<void> => {
+      const read = readBody(source).then((body) => {
+        call.body = body;
+      });
+      if (!openEnded) await read;
+    };
     // Ahead of the mocks on purpose: a test that mocked Stripe and then went offline is asserting
     // the offline path, and a mock that still answered would be the one thing that path never sees.
     if (state.network !== 'online') {
-      throw new NetworkOfflineError({
-        url,
-        method: methodOf(input, init),
-        mode: state.network,
-      });
+      const mode = state.network;
+      await logBody(probe);
+      throw new NetworkOfflineError({ url, method, mode });
     }
-    const mock = state.mocks.find((route) => matches(route, url));
+    const mock = state.mocks.find((route) => routeMatches(route, call));
     if (mock !== undefined) {
-      return mock.handler(input instanceof Request ? input : new Request(url, init));
+      const request =
+        input instanceof Request && init === undefined ? input : new Request(input, init);
+      // The probe left a stream out, and a mock is the one consumer that cannot lose backpressure.
+      const logged = hasStreamBody(init) ? request.clone() : probe;
+      // Asked before the body is awaited: an answer list goes in CALL order, so a slow POST made
+      // first cannot let a later GET take its 503. A thrown answer rejects; it is awaited below.
+      const answered = (async () => mock.handler(request))();
+      answered.catch(() => undefined);
+      await logBody(logged);
+      return answered;
     }
     // A server this process booted is not egress — the port is one the kernel just handed us, so
     // there is nothing to allowlist ahead of time. Without this, a socket test's only option is to
     // unseal the network wholesale, which then hides the real egress it was meant to catch.
     const host = safeHost(url);
-    if (isSelfOrigin(url) || (host !== undefined && state.allowed.has(host))) {
-      const original = state.original;
+    const passes = isSelfOrigin(url) || (host !== undefined && state.allowed.has(host));
+    const allowed = [...state.allowed];
+    const original = state.original;
+    if (passes) {
       if (original === undefined) throw new NetworkRaceError();
-      return original(input, init);
+      // `(input, init)` as handed: `tls`, `unix` and `proxy` are Bun's own and no Request holds them.
+      // Dialled before the body is read, so a stream's consumer is the real server, not the log.
+      const dialled = original(input, init);
+      dialled.catch(() => undefined);
+      await logBody(probe);
+      return dialled;
     }
-    throw new NetworkSealedError({
-      url,
-      method: methodOf(input, init),
-      allowed: [...state.allowed],
-    });
+    await logBody(probe);
+    throw new NetworkSealedError({ url, method, allowed });
   }) as FetchLike;
 }
 
@@ -165,11 +177,16 @@ export function allowHost(host: string): void {
   state.allowed.add(host);
 }
 
+/**
+ * `match` is a URL, a prefix ending in `*` or a RegExp, every verb; a string may name one verb first
+ * (`'POST https://…'`). `answer` is a handler, or a list answered in order with the last repeated,
+ * where an `Error` is thrown: a 503-then-200 retry test is one registration and no counter.
+ */
 export function mockFetch(
   match: string | RegExp,
-  handler: (request: Request) => Response | Promise<Response>,
+  answer: MockHandler | readonly (Response | Error)[],
 ): void {
-  state.mocks.unshift({ match, handler });
+  state.mocks.unshift(mockRoute(match, answer));
 }
 
 /** Convenience for the common case: a JSON body and a status. */
@@ -184,13 +201,13 @@ export function mockJson(match: string | RegExp, body: unknown, status = 200): v
   );
 }
 
-/** Every URL a test attempted, in order — the fastest way to see what a failure actually called. */
-export const requestedUrls = (): readonly string[] => [...state.seen];
+/** Every dial a test attempted, in order, refused ones included — what it sent, and to whom. */
+export const requestLog = (): readonly LoggedRequest[] => [...state.log];
 
 export function resetNetwork(): void {
   state.allowed.clear();
   state.mocks.length = 0;
-  state.seen.length = 0;
+  state.log.length = 0;
   state.network = 'online';
 }
 
@@ -198,7 +215,7 @@ export function resetNetwork(): void {
 export interface NetworkSnapshot {
   readonly allowed: readonly string[];
   readonly mocks: readonly MockRoute[];
-  readonly seen: readonly string[];
+  readonly log: readonly LoggedRequest[];
   readonly network: NetworkState;
 }
 
@@ -212,7 +229,7 @@ export interface NetworkSnapshot {
 export const captureNetwork = (): NetworkSnapshot => ({
   allowed: [...state.allowed],
   mocks: [...state.mocks],
-  seen: [...state.seen],
+  log: [...state.log],
   network: state.network,
 });
 
@@ -221,7 +238,7 @@ export function restoreCapturedNetwork(snapshot: NetworkSnapshot): void {
   for (const host of snapshot.allowed) state.allowed.add(host);
   state.mocks.length = 0;
   state.mocks.push(...snapshot.mocks);
-  state.seen.length = 0;
-  state.seen.push(...snapshot.seen);
+  state.log.length = 0;
+  state.log.push(...snapshot.log);
   state.network = snapshot.network;
 }

package/src/seed-graph-error.ts

@@ -0,0 +1,50 @@
+// The seed graph's refusals: no generated row satisfies a table, or a writer handed a plan for an
+// entity it was not given. Apart from ./errors, which owns the codes, their titles and the one
+// registration, because that catalogue is at its ceiling. A row refusal's fix names the
+// `defineFactory` to write, since a factory is the only input that beats the graph.
+
+import { renderCauseValue, renderFixLiteral, UltimateError } from '@ultimat3/core';
+import './errors';
+
+/** What could not be generated: a column, a rule a row breaks, or a cycle with no nullable edge. */
+export interface SeedGraphUnsatisfiedInput {
+  readonly entity: string;
+  readonly what: string;
+  /** The columns the factory has to supply. Empty when no column is to blame (a cycle). */
+  readonly columns: readonly string[];
+}
+
+const ENTITY_PLACEHOLDER = '<the entity the cause names>';
+
+/** `defaultFor` and `seedGraph` refuse the same way: the row is the app's to describe. */
+export class SeedGraphUnsatisfiedError extends UltimateError {
+  constructor(input: SeedGraphUnsatisfiedInput) {
+    const name = renderFixLiteral(input.entity, ENTITY_PLACEHOLDER);
+    const body =
+      input.columns.length === 0
+        ? '/* every column */'
+        : input.columns.map((column) => `${column}: …`).join(', ');
+    super({
+      code: 'X_SEED_GRAPH_UNSATISFIED',
+      cause: `${input.entity}: ${input.what}`,
+      fix: `defineFactory(<the ${input.entity} entity>, { defaults: (index, ids) => ({ ${body} }) }), then seedGraph(entities, { factories: { ${name}: thatFactory } })`,
+    });
+  }
+}
+
+export const seedGraphUnsatisfied = (input: SeedGraphUnsatisfiedInput): SeedGraphUnsatisfiedError =>
+  new SeedGraphUnsatisfiedError(input);
+
+/**
+ * `entitySeedWriter` met a row whose entity is not in the set it writes through: the plan and the
+ * writer were built from two different entity sets. The fix is one set, handed to both.
+ */
+export class SeedGraphEntityUnknownError extends UltimateError {
+  constructor(input: { readonly entity: string; readonly known: readonly string[] }) {
+    super({
+      code: 'X_SEED_GRAPH_ENTITY_UNKNOWN',
+      cause: `the seed plan writes ${renderCauseValue(input.entity)}, and the writer holds only ${renderCauseValue(input.known)}`,
+      fix: 'const graph = seedGraph(entities, …); await insertSeedGraph(graph, entitySeedWriter({ entities, … }))   # one entity set for both',
+    });
+  }
+}

package/src/seed-graph-order.ts

@@ -0,0 +1,98 @@
+// 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.
+
+import type { ReferenceDescription } from '@ultimat3/entity';
+import { seedGraphUnsatisfied } from './seed-graph-error';
+
+export interface OrderInput {
+  readonly name: string;
+  readonly references: readonly ReferenceDescription[];
+}
+
+export interface InsertOrder {
+  readonly order: readonly string[];
+  /** `<entity>.<property>` for every key inserted null and set afterwards. */
+  readonly deferred: ReadonlySet<string>;
+}
+
+export const edgeKey = (entity: string, property: string): string => `${entity}.${property}`;
+
+/** Whether `to` reaches `from` over the live edges, i.e. whether `from -> to` closes a cycle. */
+const reaches = (
+  edges: ReadonlyMap<string, readonly ReferenceDescription[]>,
+  live: (from: string, reference: ReferenceDescription) => boolean,
+  start: string,
+  goal: string,
+): boolean => {
+  const seen = new Set<string>();
+  const stack = [start];
+  while (stack.length > 0) {
+    const node = stack.pop() as string;
+    if (node === goal) return true;
+    if (seen.has(node)) continue;
+    seen.add(node);
+    for (const reference of edges.get(node) ?? []) {
+      if (live(node, reference)) stack.push(reference.targetEntity);
+    }
+  }
+  return false;
+};
+
+/** Kahn's algorithm in name order, so the same entity set always inserts in the same order. */
+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 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 =>
+    names.has(reference.targetEntity) &&
+    reference.targetEntity !== from &&
+    !deferred.has(edgeKey(from, reference.property));
+  const order: string[] = [];
+  const placed = new Set<string>();
+  const sorted = [...names].sort();
+  while (order.length < sorted.length) {
+    const ready = sorted.find(
+      (name) =>
+        !placed.has(name) &&
+        (edges.get(name) ?? []).every(
+          (reference) => !live(name, reference) || placed.has(reference.targetEntity),
+        ),
+    );
+    if (ready !== undefined) {
+      order.push(ready);
+      placed.add(ready);
+      continue;
+    }
+    const stuck = sorted.filter((name) => !placed.has(name));
+    const breakable = stuck.flatMap((name) =>
+      (edges.get(name) ?? [])
+        .filter(
+          (reference) =>
+            reference.nullable &&
+            live(name, reference) &&
+            !placed.has(reference.targetEntity) &&
+            reaches(edges, live, reference.targetEntity, name),
+        )
+        .map((reference) => edgeKey(name, reference.property)),
+    );
+    const edge = breakable[0];
+    if (edge === undefined) {
+      const cyclic = stuck.filter((name) =>
+        (edges.get(name) ?? []).some(
+          (reference) =>
+            live(name, reference) && reaches(edges, live, reference.targetEntity, name),
+        ),
+      );
+      throw seedGraphUnsatisfied({
+        entity: cyclic[0] ?? stuck[0] ?? '',
+        what: `a cycle of non-nullable foreign keys joins ${cyclic.join(', ')} — no insert order satisfies it; make one key .nullable(), or seed these tables yourself`,
+        columns: [],
+      });
+    }
+    deferred.add(edge);
+  }
+  return { order, deferred };
+}