@ultimat3/testing 30.2.0 → 30.4.0

package/src/exercise.ts

@@ -8,10 +8,8 @@
 
 import type { Actor, ExerciseAttempt, ExerciseVerdict } from '@ultimat3/core';
 import { isUltimateError, renderThrowable, runExercise } from '@ultimat3/core';
-import type { AnyJobHandle, JobExecution, JobRecord } from '@ultimat3/jobs';
+import type { JobExecution, JobRecord } from '@ultimat3/jobs';
 import { registeredJobs } from '@ultimat3/jobs';
-import type { Policy } from '@ultimat3/policy';
-import type { StandardSchemaV1 } from '@ultimat3/schema';
 import type { ExerciseOverride, ExerciseOverrides } from './define-exercise';
 import { assertOverridesKnown, unknownDeclaration } from './define-exercise';
 import type { RoleGrants } from './exercise-actor';
@@ -36,11 +34,13 @@ import type {
   Observed,
 } from './exercise-report';
 import { openExerciseRoom, overrideLine } from './exercise-report';
-import { withExerciseRequest } from './exercise-request';
+import { withExerciseSetup } from './exercise-setup';
+import type { Subject } from './exercise-subjects';
+import { fixedTenant, seatIn, subjectsOf } from './exercise-subjects';
 import { actorRowsOf, attachSweeps, seated, sizedCall } from './exercise-sweeps';
 import type { RunJobs } from './fixture-jobs';
 import { testJobs } from './fixture-jobs';
-import { seedPass, tenantPair } from './seed-graph-pass';
+import { deferredMayStayNull, pairGraph, seedPass, tenantPair } from './seed-graph-pass';
 import type { SeedGraph, SeedWriter } from './seed-graph-plan';
 import type { SeedEntity } from './seed-graph-shape';
 import { tenantTaint } from './tenant-canary';
@@ -62,86 +62,6 @@ export interface ExercisePassOptions {
   readonly roles: RoleGrants;
 }
 
-/** One primitive, as the pass drives it: the schema to draw from and the one call to make. */
-interface Subject {
-  readonly kind: ExerciseRecord['kind'];
-  readonly name: string;
-  readonly input: StandardSchemaV1;
-  readonly policy: Policy | undefined;
-  /** Every permission the policy references — what `x policy explain` matches grants against. */
-  readonly permissions: readonly string[];
-  /** A job's handle: what the crash proof kills at every step boundary once the control reached it. */
-  readonly handle?: AnyJobHandle;
-  /** Resolves to the failure a worker recorded on the row (a job's), or what the call answered. */
-  call(input: unknown, actor: Actor | null, tenant: string, jobs: RunJobs): Promise<Answer>;
-}
-
-/** `failure` set: the worker recorded one (a job's). Absent: answered, with `output`. */
-interface Answer {
-  readonly failure?: unknown;
-  readonly output?: unknown;
-}
-
-const ANSWERED: ReadonlySet<string> = new Set(['completed', 'suspended']);
-
-const statusOfJobFailure = (run: JobExecution | undefined): string =>
-  run === undefined ? 'the job never ran' : (run.error ?? `the run ended ${run.outcome}`);
-
-async function subjectsOf(): Promise<readonly Subject[]> {
-  // On demand, as every fixture here loads them: the barrel stays off `action` and `query`.
-  const { invoke, listActions } = await import('@ultimat3/action');
-  const { listQueries, runQuery } = await import('@ultimat3/query');
-  const job = (handle: AnyJobHandle): Subject => ({
-    kind: 'job',
-    name: handle.name,
-    input: handle.input,
-    policy: undefined,
-    permissions: [],
-    handle,
-    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);
-      // The worker's failure is a string on the row, never a throw: it is the attempt's error.
-      // Suspended is a body that ran and parked (`step.sleep`, `waitForEvent`): reached.
-      return own !== undefined && ANSWERED.has(own.outcome)
-        ? { output: own.result }
-        : { failure: statusOfJobFailure(own) };
-    },
-  });
-  return [
-    ...listActions().map(
-      (target): Subject => ({
-        kind: 'action',
-        name: target.name,
-        input: target.input,
-        policy: target.policy,
-        permissions: target.describe().permissions,
-        call: async (input, actor) => ({
-          output: await withExerciseRequest(target.name, actor, () =>
-            invoke(target, input, { surface: 'http' }),
-          ),
-        }),
-      }),
-    ),
-    ...listQueries().map(
-      (target): Subject => ({
-        kind: 'query',
-        name: target.name,
-        input: target.input,
-        policy: target.policy,
-        permissions: target.describe().permissions,
-        call: async (input, actor) => ({
-          output: await withExerciseRequest(target.name, actor, () =>
-            runQuery(target, input, { surface: 'http' }),
-          ),
-        }),
-      }),
-    ),
-    ...registeredJobs().map(job),
-  ];
-}
-
 const isOff = (overrides: ExerciseOverrides | undefined, name: string): boolean => {
   const override = overrides?.entries.get(name);
   return override !== undefined && 'off' in override;
@@ -264,7 +184,8 @@ async function control(
     draw: (at, n) => drawInput(sampler, subject.input, at, declaredRuns === undefined ? 0 : n),
     bind: async (drawn) => {
       const bound = bindIds(drawn, lookups[binds++ === 0 ? 0 : 1]);
-      lastInput = bindInput === undefined ? bound : await bindInput(bound, actor);
+      const given = bindInput === undefined ? bound : await bindInput(bound, actor);
+      lastInput = seatIn(subject, given, tenant);
       return lastInput;
     },
     accepts: async (input) =>
@@ -306,13 +227,16 @@ async function attack(
   await using jobs = await testJobs();
   room.begin(subject.name);
   let output: unknown;
+  // A job's org is re-seated in B's: B cannot enqueue a payload naming A (refused at the enqueue,
+  // which proves nothing), so the attack that matters is a job of B's carrying A's ids.
+  const sent = seatIn(subject, input, tenant);
   // Every `crossTenant()` B's call opened: a job's declared sweep is told from a leak by it alone.
   // Loaded here, never at the top: the barrel stays entity-free (`seed-writer.ts`'s rule).
   const { setCrossTenantObserver } = await import('@ultimat3/entity');
   const crossings: string[] = [];
   setCrossTenantObserver((reason) => crossings.push(reason));
   try {
-    const answer = await subject.call(input, actor, tenant, jobs);
+    const answer = await subject.call(sent, actor, tenant, jobs);
     output = answer.output;
   } catch {
     // B's refusal is the answer a scoped primitive gives: only what B got back, and what B's call
@@ -374,7 +298,18 @@ async function exerciseOne(
   };
   // A's own first input, A's ids in it: B sends exactly what A legitimately would.
   const drawn = bindIds(drawInput(sampler, subject.input, 0, 0), lookups[0]);
-  const input = bindInput === undefined ? drawn : await bindInput(drawn, actor);
+  const given = bindInput === undefined ? drawn : await bindInput(drawn, actor);
+  const seat = subject.seat?.(given, tenant);
+  if (seat?.kind === 'fixed') {
+    const fixed = fixedTenant(name, seat.declared);
+    return {
+      ...none,
+      outcome: 'unreached',
+      ...fixed,
+      tenant: { verdict: 'unproven', reason: fixed.reason },
+    };
+  }
+  const input = seat === undefined ? given : seat.input;
   let reachedWith: unknown;
   const record = await proveTenant({
     taint: tenantTaint(graph, tenant),
@@ -409,7 +344,8 @@ export async function runExercisePass(
   const sampler = await loadSampler();
   // Not `Math.random`: the frozen RNG answers the same sequence in every process.
   const passSeed = options.seed ?? (crypto.getRandomValues(new Uint32Array(1))[0] as number);
-  const room = await openExerciseRoom();
+  // The app's setup runs inside the seal, before the first row: its routes answer every call.
+  const room = await withExerciseSetup(await openExerciseRoom(), options.overrides?.setup);
   const live = chosen.filter((subject) => !isOff(options.overrides, subject.name));
   const records: ExerciseRecord[] = [];
   let graph: SeedGraph;
@@ -425,8 +361,9 @@ export async function runExercisePass(
     // In order, one at a time: the seams the room installs are the process's, not the primitive's.
     for (const subject of chosen) {
       const index = live.indexOf(subject);
-      const pair = tenantPair(graph, Math.max(0, index));
-      records.push(await exerciseOne(subject, options, pair, graph, room, sampler));
+      const at = Math.max(0, index);
+      const view = pairGraph(graph, at);
+      records.push(await exerciseOne(subject, options, tenantPair(graph, at), view, room, sampler));
     }
   } catch (error) {
     await room[Symbol.asyncDispose]();
@@ -437,7 +374,8 @@ export async function runExercisePass(
   return attachSweeps(records, {
     subjects: chosen.filter((subject) => reached.has(subject.name)),
     entities: options.entities,
-    writer: options.writer,
+    // The sized graphs close their cycles as the pass's did: a refused deferred key stays null.
+    writer: deferredMayStayNull(options.writer),
     main: graph,
     seed: passSeed,
     room,

package/src/factory-registry.ts

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

package/src/index.ts

@@ -212,6 +212,7 @@ export type {
   TenantProof,
 } from './exercise-report';
 export { overrideLine } from './exercise-report';
+export type { ExerciseSetup, ExerciseSetupHandle } from './exercise-setup';
 export type {
   Association,
   AssociationMap,

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/seed-graph-error.ts

@@ -12,6 +12,8 @@ export interface SeedGraphUnsatisfiedInput {
   readonly what: string;
   /** The columns the factory has to supply. Empty when no column is to blame (a cycle). */
   readonly columns: readonly string[];
+  /** When no factory is the repair — a key into a `readOnly` table no row is seeded in. */
+  readonly fix?: string;
 }
 
 const ENTITY_PLACEHOLDER = '<the entity the cause names>';
@@ -27,7 +29,9 @@ export class SeedGraphUnsatisfiedError extends UltimateError {
     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 } }) — for x exercise, defineExercise({}, { factories: { ${name}: thatFactory } }) in apps/web/exercise.ts`,
+      fix:
+        input.fix ??
+        `defineFactory(<the ${input.entity} entity>, { defaults: (index, ids) => ({ ${body} }) }), then seedGraph(entities, { factories: { ${name}: thatFactory } }) — for x exercise, defineExercise({}, { factories: { ${name}: thatFactory } }) in apps/web/exercise.ts`,
     });
   }
 }

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(

package/src/seed-graph-pass.ts

@@ -6,7 +6,14 @@
 import { isUltimateError, renderCauseValue, renderThrowable, UltimateError } from '@ultimat3/core';
 import { seedGraph } from './seed-graph';
 import { seedGraphUnsatisfied } from './seed-graph-error';
-import type { SeedFactory, SeedGraph, SeedRow, SeedUpdate, SeedWriter } from './seed-graph-plan';
+import type {
+  SeedCanary,
+  SeedFactory,
+  SeedGraph,
+  SeedRow,
+  SeedUpdate,
+  SeedWriter,
+} from './seed-graph-plan';
 import { insertSeedGraph } from './seed-graph-plan';
 import type { SeedEntity } from './seed-graph-shape';
 
@@ -34,10 +41,43 @@ const refused = (write: SeedRow | SeedUpdate, error: unknown): unknown => {
   });
 };
 
+const refusedRow = (error: unknown): boolean =>
+  !isUltimateError(error) || ROW_REFUSALS.has(error.code) || error.code === 'X_ENTITY_APPEND_ONLY';
+
+/**
+ * A deferred key the database refuses to set is left null: only a nullable key is ever deferred
+ * (`seed-graph-order.ts`), so the row as inserted is already a valid one. The refusal is a rule no
+ * declaration carries — a trigger that refuses every UPDATE of the table. An environment failure
+ * still rejects with its own code. `onRefused` hears each update left out.
+ */
+export const deferredMayStayNull = (
+  writer: SeedWriter,
+  onRefused: (update: SeedUpdate) => void = () => undefined,
+): SeedWriter => ({
+  insert: (row) => writer.insert(row),
+  ...(writer.insertMany === undefined
+    ? {}
+    : { insertMany: (rows: readonly SeedRow[]) => writer.insertMany?.(rows) ?? Promise.resolve() }),
+  update: (update) =>
+    writer.update(update).catch((error: unknown) => {
+      if (!refusedRow(error)) return Promise.reject(error);
+      onRefused(update);
+    }),
+  snapshot: (rows) => writer.snapshot(rows),
+});
+
 /** Every write coded: a row refusal names its factory, an environment failure keeps its own fix. */
 const coded = (writer: SeedWriter): SeedWriter => ({
   insert: (row) =>
     writer.insert(row).catch((error: unknown) => Promise.reject(refused(row, error))),
+  ...(writer.insertMany === undefined
+    ? {}
+    : {
+        insertMany: (rows: readonly SeedRow[]) =>
+          (writer.insertMany?.(rows) ?? Promise.resolve()).catch((error: unknown) =>
+            Promise.reject(refused(rows[0] as SeedRow, error)),
+          ),
+      }),
   update: (update) =>
     writer.update(update).catch((error: unknown) => Promise.reject(refused(update, error))),
   // A read, not a write: nothing a database refuses here is the generated row's fault.
@@ -50,6 +90,57 @@ export const tenantPair = (graph: SeedGraph, index: number): readonly [string, s
   graph.tenants[index * TENANTS_PER_PRIMITIVE + 1] as string,
 ];
 
+interface TenantIndex {
+  readonly inserts: ReadonlyMap<string | null, readonly number[]>;
+  readonly updates: ReadonlyMap<string | null, readonly SeedUpdate[]>;
+}
+
+const indexes = new WeakMap<SeedGraph, TenantIndex>();
+
+const grouped = <T>(items: readonly T[], tenantOf: (item: T) => string | null) => {
+  const out = new Map<string | null, T[]>();
+  for (const item of items) {
+    const key = tenantOf(item);
+    const bucket = out.get(key);
+    if (bucket === undefined) out.set(key, [item]);
+    else bucket.push(item);
+  }
+  return out;
+};
+
+const indexOf = (graph: SeedGraph): TenantIndex => {
+  let index = indexes.get(graph);
+  if (index === undefined) {
+    const positions = graph.inserts.map((_, i) => i);
+    index = {
+      inserts: grouped(positions, (i) => (graph.inserts[i] as SeedRow).tenant),
+      updates: grouped(graph.updates, (update) => update.tenant),
+    };
+    indexes.set(graph, index);
+  }
+  return index;
+};
+
+/**
+ * What primitive `index` can see of the pass's graph: the rows of no tenant and its own pair's —
+ * the same rows, in the same order, `canaries` still aligned. Everything a primitive reads off the
+ * graph (ids to bind, its taint, its actor rows) reads this, so its cost is its pair's, never the
+ * whole pass's: a filter of every row per primitive was primitives² over the pass.
+ */
+export function pairGraph(graph: SeedGraph, index: number): SeedGraph {
+  const pair = tenantPair(graph, index);
+  const { inserts, updates } = indexOf(graph);
+  const at = [null, ...pair].flatMap((tenant) => inserts.get(tenant) ?? []).sort((a, b) => a - b);
+  return {
+    seed: graph.seed,
+    tenants: pair,
+    order: graph.order,
+    inserts: at.map((i) => graph.inserts[i] as SeedRow),
+    canaries: at.map((i) => graph.canaries[i] as SeedCanary),
+    updates: [null, ...pair].flatMap((tenant) => updates.get(tenant) ?? []),
+  };
+}
+
 /** A factory keyed by a name no seeded entity has would build nothing, and the red would stay. */
 const unknownFactory = (names: readonly string[], known: ReadonlySet<string>): UltimateError =>
   new UltimateError({
@@ -80,6 +171,10 @@ export async function seedPass(
     seed: options.seed,
     ...(options.factories === undefined ? {} : { factories: options.factories }),
   });
-  await insertSeedGraph(graph, coded(writer));
-  return graph;
+  const refused = new Set<SeedUpdate>();
+  await insertSeedGraph(graph, coded(deferredMayStayNull(writer, (update) => refused.add(update))));
+  // What was written: an update the database refused is no part of the seeded state.
+  return refused.size === 0
+    ? graph
+    : { ...graph, updates: graph.updates.filter((update) => !refused.has(update)) };
 }