@ultimat3/testing 30.2.0 → 30.3.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ultimat3/testing",
-  "version": "30.2.0",
+  "version": "30.3.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.2.0",
-    "@ultimat3/cache": "30.2.0",
-    "@ultimat3/core": "30.2.0",
-    "@ultimat3/db": "30.2.0",
-    "@ultimat3/entity": "30.2.0",
-    "@ultimat3/http": "30.2.0",
-    "@ultimat3/i18n": "30.2.0",
-    "@ultimat3/jobs": "30.2.0",
-    "@ultimat3/mail": "30.2.0",
-    "@ultimat3/policy": "30.2.0",
-    "@ultimat3/pwa": "30.2.0",
-    "@ultimat3/query": "30.2.0",
-    "@ultimat3/realtime": "30.2.0",
-    "@ultimat3/render": "30.2.0",
-    "@ultimat3/schema": "30.2.0",
-    "@ultimat3/time": "30.2.0"
+    "@ultimat3/action": "30.3.0",
+    "@ultimat3/cache": "30.3.0",
+    "@ultimat3/core": "30.3.0",
+    "@ultimat3/db": "30.3.0",
+    "@ultimat3/entity": "30.3.0",
+    "@ultimat3/http": "30.3.0",
+    "@ultimat3/i18n": "30.3.0",
+    "@ultimat3/jobs": "30.3.0",
+    "@ultimat3/mail": "30.3.0",
+    "@ultimat3/policy": "30.3.0",
+    "@ultimat3/pwa": "30.3.0",
+    "@ultimat3/query": "30.3.0",
+    "@ultimat3/realtime": "30.3.0",
+    "@ultimat3/render": "30.3.0",
+    "@ultimat3/schema": "30.3.0",
+    "@ultimat3/time": "30.3.0"
   }
 }

package/src/exercise-job-tenant.ts

@@ -0,0 +1,76 @@
+// A job's input, seated in the tenant the pass enqueues it under. A job DECLARES its org as a
+// function of its input (`tenant: (input) => input.orgId`), so a drawn input names a random org and
+// the enqueue refuses it (`X_JOB_TENANT_MISMATCH`). The fields that function reads are found by
+// reading them — a recording proxy, no field-name guess — and each is set to the seated tenant.
+
+/** The handle's half the binder needs: `AnyJobHandle.tenantFor`, structurally. */
+export interface TenantOf {
+  readonly name: string;
+  tenantFor(input: unknown): string | undefined;
+}
+
+/** `seated`: the input names the tenant. `fixed`: no field it reads moves the org it answers. */
+export type JobTenantBinding =
+  | { readonly kind: 'seated'; readonly input: unknown }
+  | { readonly kind: 'fixed'; readonly declared: string | undefined };
+
+type Path = readonly string[];
+
+const isPlainObject = (value: unknown): value is Record<string, unknown> => {
+  if (typeof value !== 'object' || value === null || Array.isArray(value)) return false;
+  const prototype: unknown = Object.getPrototypeOf(value);
+  return prototype === null || prototype === Object.prototype;
+};
+
+/** What `tenantFor` answered, or `undefined` for a throw: an unreadable input names no org. */
+const answer = (handle: TenantOf, input: unknown): string | undefined => {
+  try {
+    return handle.tenantFor(input);
+  } catch {
+    return undefined;
+  }
+};
+
+/** Every property path `tenantFor` read, at any depth of plain objects — a missing one included. */
+function pathsRead(handle: TenantOf, input: unknown): readonly Path[] {
+  const read: Path[] = [];
+  const watch = (value: unknown, at: Path): unknown =>
+    !isPlainObject(value)
+      ? value
+      : new Proxy(value, {
+          get(target, key, receiver) {
+            if (typeof key !== 'string') return Reflect.get(target, key, receiver);
+            const path = [...at, key];
+            read.push(path);
+            return watch(Reflect.get(target, key, receiver), path);
+          },
+        });
+  answer(handle, watch(input, []));
+  return read;
+}
+
+/** `input` with `path` set to `value`, copied along the path only. */
+function setAt(input: unknown, path: Path, value: string): unknown {
+  const [head, ...rest] = path;
+  if (head === undefined) return value;
+  const base = isPlainObject(input) ? input : {};
+  return { ...base, [head]: setAt(base[head], rest, value) };
+}
+
+/**
+ * `input` naming `tenant` wherever `handle.tenantFor` reads it. A `'none'` job, or one already
+ * naming it, comes back as given. A read path is kept only if setting it moves the answer to
+ * `tenant` — a field read and then ignored is left as drawn.
+ */
+export function bindJobTenant(handle: TenantOf, input: unknown, tenant: string): JobTenantBinding {
+  const declared = answer(handle, input);
+  if (declared === tenant) return { kind: 'seated', input };
+  const reads = pathsRead(handle, input);
+  // `tenant: 'none'` is never called: no org named, none read, so none to disagree with.
+  if (declared === undefined && reads.length === 0) return { kind: 'seated', input };
+  const moving = reads.filter((path) => answer(handle, setAt(input, path, tenant)) === tenant);
+  const bound = moving.reduce<unknown>((value, path) => setAt(value, path, tenant), input);
+  return moving.length > 0 && answer(handle, bound) === tenant
+    ? { kind: 'seated', input: bound }
+    : { kind: 'fixed', declared };
+}

package/src/exercise-report.ts

@@ -99,6 +99,11 @@ export interface ExerciseRecord {
   readonly ms: number;
   /** For an `unreached` one: the line to paste into `defineExercise({ … })`. */
   readonly override?: string;
+  /**
+   * For an `unreached` one no override reaches: the edit that does, in place of the paste — a job
+   * whose `tenant(input)` names one fixed org (`exercise-subjects.ts`'s `fixedTenant`).
+   */
+  readonly fix?: string;
   /** On every record that ran — absent only on `off` and `refused`. The fields above are A's. */
   readonly tenant?: TenantProof;
   /** On a reached job only: its control's input, killed at every step boundary. */

package/src/exercise-subjects.ts

@@ -0,0 +1,119 @@
+// 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.
+
+import type { Actor } from '@ultimat3/core';
+import { renderCauseValue, renderFixShellArg } from '@ultimat3/core';
+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 type { JobTenantBinding } from './exercise-job-tenant';
+import { bindJobTenant } from './exercise-job-tenant';
+import { withExerciseRequest } from './exercise-request';
+import type { RunJobs } from './fixture-jobs';
+
+/** `failure` set: the worker recorded one (a job's). Absent: answered, with `output`. */
+export interface Answer {
+  readonly failure?: unknown;
+  readonly output?: unknown;
+}
+
+/** One primitive, as the pass drives it: the schema to draw from and the one call to make. */
+export interface Subject {
+  readonly kind: 'action' | 'query' | 'job';
+  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;
+  /** A job's: `input` naming `tenant` wherever its declared `tenant(input)` reads the org. */
+  seat?(input: unknown, tenant: string): JobTenantBinding;
+  /** 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>;
+}
+
+/** `input` seated in `tenant` when the subject declares a seat and one exists; else as given. */
+export const seatIn = (subject: Pick<Subject, 'seat'>, input: unknown, tenant: string): unknown => {
+  const seat = subject.seat?.(input, tenant);
+  return seat?.kind === 'seated' ? seat.input : input;
+};
+
+/**
+ * Why a job whose org no input field moves is not run: the pass seats every primitive in a FRESH
+ * tenant of its own, and a constant org is none of them. Seeding that one org instead would hand
+ * every such job the same tenant — no fresh pair, no tenant proof — so it is reported, never run
+ * in a tenant whose rows the pass did not seed. The repair is the declaration's.
+ */
+export function fixedTenant(name: string, declared: string | undefined) {
+  const org = declared === undefined ? 'no org' : `org ${renderCauseValue(declared)}`;
+  return {
+    code: 'X_JOB_TENANT_MISMATCH',
+    reason: `its tenant(input) answers ${org} whatever its input carries, so it cannot run in the fresh tenant the pass seeded for it`,
+    fix: `tenant: (input) => input.orgId   # in job({ name: ${JSON.stringify(name)} })'s declaration: the org as input, so every enqueuer — this pass too — names it; then: x exercise ${renderFixShellArg(name, '<name>')} --json`,
+  };
+}
+
+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}`);
+
+const jobSubject = (handle: AnyJobHandle): Subject => ({
+  kind: 'job',
+  name: handle.name,
+  input: handle.input,
+  policy: undefined,
+  permissions: [],
+  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);
+    // 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) };
+  },
+});
+
+export 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');
+  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(jobSubject),
+  ];
+}

package/src/exercise-sweeps.ts

@@ -3,8 +3,6 @@
 // database). Both verdicts land on the record of the primitive that sent the statements.
 
 import type { Actor } from '@ultimat3/core';
-import type { Policy } from '@ultimat3/policy';
-import type { StandardSchemaV1 } from '@ultimat3/schema';
 import type { ExerciseOverrides } from './define-exercise';
 import type { ActorRows, RoleGrants } from './exercise-actor';
 import { asSeededRow, chooseActor } from './exercise-actor';
@@ -12,6 +10,8 @@ import type { Sampler } from './exercise-input';
 import { bindIds, drawInput, seededIds } from './exercise-input';
 import { overrideInput } from './exercise-override-input';
 import type { ExerciseRecord } from './exercise-report';
+import type { Subject } from './exercise-subjects';
+import { seatIn } from './exercise-subjects';
 import { sweepPlans } from './plan-sweep';
 import type { ScaleSweepOptions } from './scale-sweep-run';
 import { scaleSweep } from './scale-sweep-run';
@@ -37,13 +37,8 @@ export const actorRowsOf = (options: CallOptions, graph: SeedGraph): ActorRows |
 export const seated = (actor: Actor | null, tenant: string, rows: ActorRows | undefined) =>
   rows === undefined ? actor : asSeededRow(actor, tenant, rows);
 
-/** A primitive as a sized call needs it: its schema and its policy. */
-interface Callable {
-  readonly name: string;
-  readonly input: StandardSchemaV1;
-  readonly policy: Policy | undefined;
-  readonly permissions: readonly string[];
-}
+/** A primitive as a sized call needs it: its schema, its policy, and a job's seat. */
+type Callable = Pick<Subject, 'name' | 'input' | 'policy' | 'permissions' | 'seat'>;
 
 /** One call of `subject` in `tenant` of a sized graph: the control's actor and first input. */
 export async function sizedCall(
@@ -67,7 +62,8 @@ export async function sizedCall(
   const lookup = seededIds(graph, options.entities, { ...scope, self });
   const drawn = bindIds(drawInput(sampler, subject.input, 0, 0), lookup);
   const bindInput = overrideInput(subject.name, override);
-  return { actor, input: bindInput === undefined ? drawn : await bindInput(drawn, actor) };
+  const given = bindInput === undefined ? drawn : await bindInput(drawn, actor);
+  return { actor, input: seatIn(subject, given, tenant) };
 }
 
 /**

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,12 @@ import type {
   Observed,
 } from './exercise-report';
 import { openExerciseRoom, overrideLine } from './exercise-report';
-import { withExerciseRequest } from './exercise-request';
+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 { 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 +61,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 +183,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 +226,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 +297,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),
@@ -425,8 +359,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]();

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-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';
 
@@ -38,6 +45,14 @@ const refused = (write: SeedRow | SeedUpdate, error: unknown): unknown => {
 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 +65,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({

package/src/seed-graph-plan.ts

@@ -72,6 +72,12 @@ export interface SeedGraph {
 /** Where `insertSeedGraph` writes. One insert per row, in order, then one update per deferred key. */
 export interface SeedWriter {
   insert(row: SeedRow): Promise<void>;
+  /**
+   * Rows of ONE entity, in plan order, as one write — `insertAll`. Optional: a writer without it
+   * takes `insert` per row. With it, a graph costs one statement per table, not one per row: a
+   * pass seeding a fresh tenant pair per primitive writes primitives × tables rows.
+   */
+  insertMany?(rows: readonly SeedRow[]): Promise<void>;
   update(update: SeedUpdate): Promise<void>;
   /**
    * Each row read back by its primary key, as one digest per row in the order given — `null` for
@@ -81,8 +87,24 @@ export interface SeedWriter {
   snapshot(rows: readonly SeedRow[]): Promise<readonly (string | null)[]>;
 }
 
+/**
+ * Each run of consecutive rows of one entity. The plan writes table by table, so a run is a table's
+ * rows — and a parent table's run always lands before its children's.
+ */
+export function entityRuns(rows: readonly SeedRow[]): readonly (readonly SeedRow[])[] {
+  const runs: SeedRow[][] = [];
+  for (const row of rows) {
+    const last = runs[runs.length - 1];
+    if (last !== undefined && last[0]?.entity === row.entity) last.push(row);
+    else runs.push([row]);
+  }
+  return runs;
+}
+
 /** Writes the plan in order: every insert, then every deferred key. Sequential, so it replays. */
 export async function insertSeedGraph(graph: SeedGraph, writer: SeedWriter): Promise<void> {
-  for (const row of graph.inserts) await writer.insert(row);
+  const { insertMany } = writer;
+  if (insertMany === undefined) for (const row of graph.inserts) await writer.insert(row);
+  else for (const run of entityRuns(graph.inserts)) await insertMany.call(writer, run);
   for (const update of graph.updates) await writer.update(update);
 }

package/src/seed-graph.ts

@@ -72,9 +72,19 @@ export function seedGraph(
   // A view entity is a relation Postgres derives: no row is ever written to it, so it is no part of
   // the graph (`X_ENTITY_VIEW_READ_ONLY` otherwise) — the tables it reads from carry the rows. A
   // history table is the same from this side: its trigger writes every row, from the parent's.
+  // A `readOnly` table is the app's own statement that it writes no row there (a trigger refuses
+  // every INSERT): seeded like a view, never — a reference into one is null or refused below.
+  const closed = new Map(
+    Object.values(entities).flatMap((entity) => {
+      const reason = entity.$describe().readOnly;
+      return reason === undefined ? [] : [[entity.$name, reason] as const];
+    }),
+  );
   const tables = Object.values(entities).filter((entity) => {
     const described = entity.$describe();
-    return described.view === undefined && described.historyOf === undefined;
+    return (
+      described.view === undefined && described.historyOf === undefined && !closed.has(entity.$name)
+    );
   });
   const shapes = new Map(tables.map((entity) => [entity.$name, shapeOf(entity)]));
   const { order, deferred } = insertOrder(
@@ -99,21 +109,34 @@ export function seedGraph(
   for (const factory of Object.values(options.factories ?? {})) factory.reset();
 
   const placed = new Map<string, Placed[]>();
+  // The same rows by tenant: a pool read per row was a filter of the whole parent table, so a pass
+  // seeding a tenant pair per primitive planned in primitives² time.
+  const placedIn = new Map<string, Map<string | null, Placed[]>>();
   const parentValues = (
     reference: ReferenceDescription,
     tenant: string | null,
     index: number,
   ): unknown[] => {
     if (!shapes.has(reference.targetEntity)) return reference.nullable ? [null] : [];
-    const pool = (placed.get(reference.targetEntity) ?? []).filter(
-      (parent) => tenant === null || !scoped(reference.targetEntity) || parent.tenant === tenant,
-    );
+    const pool =
+      tenant === null || !scoped(reference.targetEntity)
+        ? (placed.get(reference.targetEntity) ?? [])
+        : (placedIn.get(reference.targetEntity)?.get(tenant) ?? []);
     const values =
       pool.length === 0 ? [] : rotate(pool, index).map((p) => p.row[reference.targetProperty]);
     return reference.nullable ? [...values, null] : values;
   };
   const refuseEmpty = (shape: EntityShape, property: string, tenant: string | null): never => {
     const reference = shape.references.get(property);
+    const reason = reference === undefined ? undefined : closed.get(reference.targetEntity);
+    if (reference !== undefined && reason !== undefined) {
+      throw seedGraphUnsatisfied({
+        entity: shape.name,
+        what: `${property} references ${reference.targetEntity}, which is readOnly (${reason}): no row of it is seeded and ${property} is not nullable, so no ${shape.name} row can be written`,
+        columns: [property],
+        fix: `entity('${shape.name}', { readOnly: '<why the app never writes it>' })   # when the app never writes ${shape.name} either — else ${property}: <its column>.nullable(), then x db gen "${shape.entity.$table} ${property} nullable"`,
+      });
+    }
     throw seedGraphUnsatisfied({
       entity: shape.name,
       what:
@@ -135,6 +158,8 @@ export function seedGraph(
     const factory = options.factories?.[name];
     const rows: Placed[] = [];
     placed.set(name, rows);
+    const byTenant = new Map<string | null, Placed[]>();
+    placedIn.set(name, byTenant);
     const allUniques = [...shape.uniques, ...shape.partialUniques];
     const taken = allUniques.map(() => new Set<string>());
     const rootProperty = roots.get(name);
@@ -210,7 +235,11 @@ export function seedGraph(
           const key = uniqueKey(row, set);
           if (key !== undefined) taken[i]?.add(key);
         });
-        rows.push({ tenant, row, index });
+        const one = { tenant, row, index };
+        rows.push(one);
+        const bucketRows = byTenant.get(tenant);
+        if (bucketRows === undefined) byTenant.set(tenant, [one]);
+        else bucketRows.push(one);
         inserts.push({ entity: name, table: entity.$table, tenant, row: { ...row } });
         canaries.push({
           entity: name,

package/src/seed-writer.ts

@@ -42,45 +42,52 @@ const keyColumns = (entity: EntityCore): readonly string[] => {
   );
 };
 
+/** Joins a composite key's parts, in Postgres and here alike: no seeded key holds a unit separator. */
+const KEY_SEPARATOR = '\u001f';
+
 /**
  * `md5(t::text)` per row, by primary key, through the client — the whole stored row, columns no
- * entity declares included. One statement per table for a one-column key, one per row for a
- * composite one. Unscoped on purpose: the question is whether the row changed, not who may read it.
+ * entity declares included. ONE statement, a `union all` branch per table, a composite key matched
+ * through parallel arrays: the tenant proof snapshots four times a primitive, and a statement per
+ * table was primitives × tables round trips. Unscoped on purpose: the question is whether the row
+ * changed, not who may read it.
  */
 async function snapshotOnClient(
   client: DbClient,
   rows: readonly SeedRow[],
   entities: readonly EntityCore[],
 ): Promise<readonly (string | null)[]> {
-  const out: (string | null)[] = rows.map(() => null);
   const byEntity = new Map<EntityCore, number[]>();
   entities.forEach((entity, i) => {
-    byEntity.set(entity, [...(byEntity.get(entity) ?? []), i]);
+    const indexes = byEntity.get(entity);
+    if (indexes === undefined) byEntity.set(entity, [i]);
+    else indexes.push(i);
   });
-  for (const [entity, indexes] of byEntity) {
-    const table = identifier(entity.$table);
-    const columns = keyColumns(entity);
-    const keyAt = (i: number, at: number) => String(rows[i]?.row[entity.$primaryKey[at] as string]);
-    const [single] = columns;
-    if (columns.length === 1 && single !== undefined) {
-      const key = identifier(single);
-      const found = await client.query<{ k: string; h: string }>(
-        sql`select ${key}::text as k, md5(t::text) as h from ${table} t where ${key}::text = any(${indexes.map((i) => keyAt(i, 0))}::text[])`,
-      );
-      const digests = new Map(found.map((one) => [one.k, one.h]));
-      for (const i of indexes) out[i] = digests.get(keyAt(i, 0)) ?? null;
-      continue;
-    }
+  const keyOf = (entity: EntityCore, i: number): string =>
+    entity.$primaryKey.map((property) => String(rows[i]?.row[property])).join(KEY_SEPARATOR);
+  const branches = [...byEntity].map(([entity, indexes], at): SqlFragment => {
+    const columns = keyColumns(entity).map((column) => identifier(column));
+    // Each key column against its values, the parameter UNTYPED so Postgres types it as the
+    // column: `id::text = any(…)` read every row of a table that grows with the primitives. A
+    // composite key matches a superset here; the full key is matched below.
+    const matched = entity.$primaryKey.map(
+      (property, part) =>
+        sql`${columns[part] as SqlFragment} = any(${[...new Set(indexes.map((i) => String(rows[i]?.row[property])))]})`,
+    );
+    const texts = columns.map((column) => sql`${column}::text`);
+    return sql`select ${at}::int as e, concat_ws(${KEY_SEPARATOR}, ${join(texts)}) as k, md5(t::text) as h from ${identifier(entity.$table)} t where ${join(matched, ' and ')}`;
+  });
+  if (branches.length === 0) return [];
+  const found = await client.query<{ e: number; k: string; h: string }>(
+    join(branches, ' union all '),
+  );
+  const digests = new Map(found.map((one) => [`${one.e}${KEY_SEPARATOR}${one.k}`, one.h]));
+  const out: (string | null)[] = rows.map(() => null);
+  [...byEntity].forEach(([entity, indexes], at) => {
     for (const i of indexes) {
-      const terms: SqlFragment[] = columns.map(
-        (column, at) => sql`${identifier(column)}::text = ${keyAt(i, at)}`,
-      );
-      const one = await client.one<{ h: string }>(
-        sql`select md5(t::text) as h from ${table} t where ${join(terms, ' and ')}`,
-      );
-      out[i] = one?.h ?? null;
+      out[i] = digests.get(`${at}${KEY_SEPARATOR}${keyOf(entity, i)}`) ?? null;
     }
-  }
+  });
   return out;
 }
 
@@ -146,6 +153,20 @@ export function entitySeedWriter(options: EntitySeedWriterOptions): SeedWriter {
       const { entity, repo } = await repoFor(row.entity);
       await repo.insert({ ...row.row }, scope(entity, row));
     },
+    async insertMany(rows) {
+      const [first] = rows;
+      if (first === undefined) return;
+      const { entity, repo } = await repoFor(first.entity);
+      // One scope when every row shares it. An insert's statement reads none — both drivers check
+      // a row's tenant column against the ACTOR, and a seed has none — so a table holding many
+      // tenants' rows is still one `insertAll`.
+      const scopes = new Set(rows.map((row) => scope(entity, row).orgId));
+      const [only] = scopes;
+      await repo.insertAll(
+        rows.map((row) => ({ ...row.row })),
+        scopes.size === 1 && only !== undefined ? { orgId: only } : {},
+      );
+    },
     async update(update) {
       const { entity, repo } = await repoFor(update.entity);
       await repo.updateWhere({ ...update.key }, { ...update.patch }, scope(entity, update));