@ultimat3/testing 30.2.0 → 30.4.0

package/src/seed-graph-patterns.ts

@@ -0,0 +1,51 @@
+// The `matches(/…/)` patterns an entity declares, per property. Read back from each invariant's
+// own CHECK text, which `expr.ts` builds as `<column> ~ <literal(source)>` (or `btrim(<column>)`,
+// `~*` for `/i`) — the same source `pattern.test` runs, so nothing here is a guess. A rule of any
+// other shape (`iff`, a predicate, two columns) is not a pattern and is skipped.
+
+import type { SeedEntity } from './seed-graph-shape';
+
+/** `col ~ E'src'` / `btrim(col) ~* 'src'`: the whole CHECK, one column, one quoted literal. */
+const PATTERN_CHECK = /^(?:btrim\(([a-z_][a-z0-9_$]*)\)|([a-z_][a-z0-9_$]*)) (~\*?) (E?)'(.*)'$/s;
+
+/**
+ * The `RegExp` one CHECK enforces on `column`, or `undefined`. The literal is undone exactly as
+ * `@ultimat3/db`'s `literal()` made it: `''` is one quote, and under `E'…'` `\\` is one backslash.
+ */
+export function patternOfCheck(sql: string, column: string): RegExp | undefined {
+  const match = PATTERN_CHECK.exec(sql);
+  if (match === null || (match[1] ?? match[2]) !== column) return undefined;
+  const body = match[5] ?? '';
+  // A lone quote inside the body is not something `literal()` writes: not this shape after all.
+  if (body.replaceAll("''", '').includes("'")) return undefined;
+  const unquoted = body.replaceAll("''", "'");
+  const source = match[4] === 'E' ? unquoted.replaceAll('\\\\', '\\') : unquoted;
+  try {
+    return new RegExp(source, match[3] === '~*' ? 'i' : '');
+  } catch {
+    // A source JavaScript cannot compile is no pattern to sample from; the solver still judges
+    // every candidate by the rule itself, so skipping it loses a hint and never a check.
+    return undefined;
+  }
+}
+
+/** Property -> the patterns its `check` invariants declare. Empty for an entity with none. */
+export function declaredPatterns(
+  entity: Pick<SeedEntity, '$invariants' | '$describe'>,
+): ReadonlyMap<string, readonly RegExp[]> {
+  const propertyOf = new Map(
+    entity.$describe().columns.map((column) => [column.column, column.property] as const),
+  );
+  const out = new Map<string, RegExp[]>();
+  for (const invariant of entity.$invariants) {
+    const [column] = invariant.columns;
+    if (invariant.kind !== 'check' || invariant.sql === null || invariant.columns.length !== 1) {
+      continue;
+    }
+    const property = column === undefined ? undefined : propertyOf.get(column);
+    const pattern = column === undefined ? undefined : patternOfCheck(invariant.sql, column);
+    if (property === undefined || pattern === undefined) continue;
+    out.set(property, [...(out.get(property) ?? []), pattern]);
+  }
+  return out;
+}

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

@@ -1,8 +1,12 @@
 // A value for one column, read off the column's own declaration — its kind, nullability, enumerated
-// values, length, money parts and default — never off its name. Every candidate is run through the
-// column's `$parse`, which refuses exactly what its CHECK refuses, so what survives is storable.
+// values, length, money parts, default, `matches()` patterns and `json(schema)` — never off its
+// name. Every candidate is run through the column's `$parse`, which refuses exactly what its CHECK
+// refuses, so what survives is storable.
 
+import { fnv1a } from '@ultimat3/core';
 import type { ColumnMeta } from '@ultimat3/entity';
+import type * as Sample from '@ultimat3/schema/sample';
+import { patternSamples } from './seed-pattern-sample';
 
 /** A column as `entity()` declares it, structurally: this barrel never loads `@ultimat3/entity`. */
 export interface SeedColumn {
@@ -18,6 +22,11 @@ export interface ValueContext {
   readonly canary: string;
   /** Declaration position of the column, so two instants on one row are ordered as declared. */
   readonly position: number;
+  /**
+   * The `matches(/…/)` patterns the entity's invariants hold this column to (`declaredPatterns`).
+   * Each one adds strings built from the pattern itself, so a rule no fixed shape meets is met.
+   */
+  readonly patterns?: readonly RegExp[] | undefined;
   uuid(): string;
 }
 
@@ -59,7 +68,46 @@ const textCandidates = (property: string, meta: ColumnMeta, ctx: ValueContext):
     `https://seed.test/${word}/${ctx.canary}`,
     ctx.canary,
   ];
-  return meta.length === undefined ? shapes : [...shapes, ctx.canary.slice(0, meta.length)];
+  const sized = meta.length === undefined ? shapes : [...shapes, ctx.canary.slice(0, meta.length)];
+  return [...sized, ...fromPatterns(property, ctx)];
+};
+
+/** Strings drawn from each declared pattern, kept only where every other pattern agrees. */
+const fromPatterns = (property: string, ctx: ValueContext): string[] => {
+  const patterns = ctx.patterns ?? [];
+  return patterns
+    .flatMap((pattern) => patternSamples(pattern, `${property}:${ctx.canary}`))
+    .filter((sample) => patterns.every((pattern) => pattern.test(sample)));
+};
+
+let loadedSampler: typeof Sample | undefined;
+
+/**
+ * `@ultimat3/schema/sample`, loaded on the first `json(schema)` column and never at import: this
+ * module is on the barrel, and the walker is a dynamic-only dependency there (`CLAUDE.md`).
+ * `require` and not `import()` because every caller of `candidatesFor` is synchronous.
+ */
+const sampler = (): typeof Sample => {
+  loadedSampler ??= require('@ultimat3/schema/sample') as typeof Sample;
+  return loadedSampler;
+};
+
+/**
+ * Values the column's own schema accepts, seeded by the row so two rows differ and a rerun does
+ * not; then the bare `{}`/`[]`, which a schema-less `jsonb` column stores.
+ */
+const jsonCandidates = (property: string, meta: ColumnMeta, ctx: ValueContext): unknown[] => {
+  const schema = meta.schema;
+  if (schema === undefined) return [{}, []];
+  const { arbitrary, sampleInput, BOUNDARY_RUNS } = sampler();
+  const seed = fnv1a(`${property}:${ctx.canary}`);
+  return [
+    arbitrary(schema, { seed, run: BOUNDARY_RUNS }),
+    arbitrary(schema, { seed, run: 0 }),
+    sampleInput(schema),
+    {},
+    [],
+  ];
 };
 
 const byKind = (property: string, meta: ColumnMeta, ctx: ValueContext): unknown[] => {
@@ -84,7 +132,7 @@ const byKind = (property: string, meta: ColumnMeta, ctx: ValueContext): unknown[
     case 'date':
       return [`2026-01-${String((n % 28) + 1).padStart(2, '0')}`];
     case 'jsonb':
-      return [{}, []];
+      return jsonCandidates(property, meta, ctx);
     case 'bytea':
       return [new Uint8Array([n % 256])];
     case 'array':
@@ -123,9 +171,20 @@ export function candidatesFor(
       out.push(result.ok);
     }
   }
-  return out;
+  return keepsPatternsFirst(out, ctx.patterns ?? []);
 }
 
+/**
+ * Stable: what keeps every declared pattern moves ahead, so `factoriesFor`, which takes the FIRST
+ * candidate and runs no solver, builds a row its own rules accept.
+ */
+const keepsPatternsFirst = (values: unknown[], patterns: readonly RegExp[]): unknown[] => {
+  if (patterns.length === 0) return values;
+  const keeps = (value: unknown): boolean =>
+    typeof value === 'string' && patterns.every((pattern) => pattern.test(value));
+  return [...values.filter(keeps), ...values.filter((value) => !keeps(value))];
+};
+
 /** Candidates offered verbatim (a factory's value), kept only where the column stores them. */
 export function storable(column: SeedColumn, values: readonly unknown[]): readonly unknown[] {
   return values.flatMap((value) => {

package/src/seed-graph.ts

@@ -7,6 +7,7 @@ import type { ReferenceDescription } from '@ultimat3/entity';
 import { DEFAULT_SEED, seededUuid } from './determinism';
 import { seedGraphUnsatisfied } from './seed-graph-error';
 import { edgeKey, insertOrder } from './seed-graph-order';
+import { declaredPatterns } from './seed-graph-patterns';
 import type {
   SeedCanary,
   SeedGraph,
@@ -72,15 +73,26 @@ 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(
     [...shapes.values()].map((shape) => ({
       name: shape.name,
       references: [...shape.references.values()],
+      updatable: shape.entity.$describe().appendOnly !== true,
     })),
   );
   const tenantStream = seededUuid(streamSeed(seed, '$tenants'));
@@ -99,21 +111,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,9 +160,13 @@ 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);
+    // Read once per table: each `matches(/…/)` an invariant holds a column to, sampled from.
+    const patterns = declaredPatterns(entity);
     const buckets: readonly (string | null)[] = scoped(name) ? tenants : [null];
     let ordinal = 0;
     for (const [bucket, tenant] of buckets.entries()) {
@@ -170,6 +199,7 @@ export function seedGraph(
                           ordinal,
                           canary,
                           position,
+                          patterns: patterns.get(property),
                           uuid: stream,
                         });
           return [
@@ -210,7 +240,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,
@@ -228,6 +262,8 @@ export function seedGraph(
   const updates: SeedUpdate[] = [];
   for (const name of order) {
     const shape = shapes.get(name) as EntityShape;
+    // An appendOnly row is never updated (its trigger refuses): a key deferred there stays null.
+    if (shape.entity.$describe().appendOnly === true) continue;
     const later = shape.columns.filter(([property]) => deferred.has(edgeKey(name, property)));
     if (later.length === 0) continue;
     for (const { tenant, row, index } of placed.get(name) ?? []) {

package/src/seed-pattern-sample.ts

@@ -0,0 +1,216 @@
+// Strings a declared `matches(/…/)` pattern accepts, built by walking the pattern rather than
+// guessing shapes. The common subset only — literals, classes, `.`, groups, alternation,
+// quantifiers, anchors — and an honest `[]` for anything past it (lookaround, backreference, `\b`,
+// `\p{…}`): a pattern this cannot read leaves the column's other candidates to the solver.
+
+import { fnv1a } from '@ultimat3/core';
+import { seededRandom } from './determinism';
+
+type Node =
+  | { readonly kind: 'chars'; readonly chars: readonly string[] }
+  | { readonly kind: 'alt'; readonly branches: readonly (readonly Piece[])[] }
+  | { readonly kind: 'empty' };
+
+interface Piece {
+  readonly node: Node;
+  readonly min: number;
+  readonly max: number;
+}
+
+/** How far past its floor an unbounded quantifier draws: enough to vary, short enough to store. */
+const UNBOUNDED_SPAN = 6;
+
+/** The universe a class or `.` picks from: printable ASCII, so every sample is plain text. */
+const PRINTABLE = Array.from({ length: 95 }, (_, i) => String.fromCharCode(32 + i));
+const DIGITS = PRINTABLE.filter((c) => c >= '0' && c <= '9');
+const WORD = PRINTABLE.filter((c) => /\w/.test(c));
+const SPACE = [' ', '\t'];
+
+const SHORTHAND: Readonly<Record<string, readonly string[]>> = {
+  d: DIGITS,
+  D: PRINTABLE.filter((c) => !DIGITS.includes(c)),
+  w: WORD,
+  W: PRINTABLE.filter((c) => !WORD.includes(c)),
+  s: SPACE,
+  S: PRINTABLE.filter((c) => c !== ' '),
+};
+
+const CONTROL: Readonly<Record<string, string>> = { t: '\t', n: '\n', r: '\r', f: '\f', v: '\v' };
+
+class Parser {
+  private at = 0;
+  /** The first construct past the subset; set once, and it ends the walk. */
+  private refused: string | undefined;
+  constructor(private readonly source: string) {}
+
+  /** The tree, or `undefined` when any part of the pattern is past the subset. */
+  parse(): Node | undefined {
+    const node = this.alternation();
+    if (this.refused === undefined && this.at < this.source.length) this.refuse('a stray ")"');
+    return this.refused === undefined ? node : undefined;
+  }
+
+  /** Records the refusal and moves to the end, so every loop above stops on its next look. */
+  private refuse(construct: string): readonly string[] {
+    this.refused ??= construct;
+    this.at = this.source.length;
+    return [];
+  }
+
+  private peek(): string | undefined {
+    return this.source[this.at];
+  }
+
+  private alternation(): Node {
+    const branches: Piece[][] = [this.sequence()];
+    while (this.peek() === '|') {
+      this.at += 1;
+      branches.push(this.sequence());
+    }
+    return { kind: 'alt', branches };
+  }
+
+  private sequence(): Piece[] {
+    const pieces: Piece[] = [];
+    for (let c = this.peek(); c !== undefined && c !== '|' && c !== ')'; c = this.peek()) {
+      const node = this.atom();
+      const [min, max] = this.quantifier();
+      pieces.push({ node, min, max });
+    }
+    return pieces;
+  }
+
+  private quantifier(): readonly [number, number] {
+    const c = this.peek();
+    const bounds = /^\{(\d+)(,(\d*))?\}/.exec(this.source.slice(this.at));
+    let range: readonly [number, number] | undefined;
+    if (c === '*') range = [0, UNBOUNDED_SPAN];
+    else if (c === '+') range = [1, 1 + UNBOUNDED_SPAN];
+    else if (c === '?') range = [0, 1];
+    else if (bounds !== null) {
+      const low = Number(bounds[1]);
+      const high =
+        bounds[2] === undefined ? low : bounds[3] === '' ? low + UNBOUNDED_SPAN : Number(bounds[3]);
+      range = [low, high];
+    }
+    if (range === undefined) return [1, 1];
+    this.at += bounds !== null && c === '{' ? bounds[0].length : 1;
+    // A lazy quantifier matches the same strings; only the engine's preference differs.
+    if (this.peek() === '?') this.at += 1;
+    return range;
+  }
+
+  private atom(): Node {
+    const c = this.peek() as string;
+    this.at += 1;
+    if (c === '^' || c === '$') return { kind: 'empty' };
+    if (c === '.') return { kind: 'chars', chars: PRINTABLE };
+    if (c === '[') return { kind: 'chars', chars: this.charClass() };
+    if (c === '(') return this.group();
+    if (c === '\\') return { kind: 'chars', chars: this.escape(false) };
+    if (c === '*' || c === '+' || c === '?' || c === '{')
+      return { kind: 'chars', chars: this.refuse(`a bare "${c}"`) };
+    return { kind: 'chars', chars: [c] };
+  }
+
+  private group(): Node {
+    if (this.peek() === '?') {
+      const head = this.source.slice(this.at, this.at + 3);
+      if (head.startsWith('?:')) this.at += 2;
+      else if (/^\?<[A-Za-z_$]/.test(head) && this.source.includes('>', this.at)) {
+        this.at = this.source.indexOf('>', this.at) + 1;
+      } else return { kind: 'chars', chars: this.refuse(`the lookaround "(${head}"`) };
+    }
+    const inner = this.alternation();
+    if (this.peek() !== ')') return { kind: 'chars', chars: this.refuse('an unclosed group') };
+    this.at += 1;
+    return inner;
+  }
+
+  private escape(inClass: boolean): readonly string[] {
+    const c = this.peek();
+    if (c === undefined) return this.refuse('a trailing backslash');
+    this.at += 1;
+    const shorthand = Object.hasOwn(SHORTHAND, c) ? SHORTHAND[c] : undefined;
+    if (shorthand !== undefined) return shorthand;
+    const control = Object.hasOwn(CONTROL, c) ? CONTROL[c] : undefined;
+    if (control !== undefined) return [control];
+    const hex = c === 'x' ? 2 : c === 'u' ? 4 : 0;
+    if (hex > 0) {
+      const digits = this.source.slice(this.at, this.at + hex);
+      if (!/^[0-9a-fA-F]+$/.test(digits) || digits.length !== hex) return this.refuse(`\\${c}`);
+      this.at += hex;
+      return [String.fromCharCode(Number.parseInt(digits, 16))];
+    }
+    // `\b`, `\B`, a backreference, `\p{…}`, `\k<…>`, `\0`: a position or a reference, not a char.
+    if (/[A-Za-z0-9]/.test(c)) return this.refuse(`\\${c}${inClass ? ' in a class' : ''}`);
+    return [c];
+  }
+
+  /** The members of `[…]`, drawn from printable ASCII; a negated class is its complement there. */
+  private charClass(): readonly string[] {
+    const negated = this.peek() === '^';
+    if (negated) this.at += 1;
+    const members = new Set<string>();
+    let first = true;
+    for (let c = this.peek(); c !== ']' || first; c = this.peek()) {
+      if (c === undefined) return this.refuse('an unclosed class');
+      first = false;
+      const low = this.classMember();
+      if (low.length === 1 && this.peek() === '-' && this.source[this.at + 1] !== ']') {
+        this.at += 1;
+        const high = this.classMember();
+        if (high.length !== 1) return this.refuse('a range ending in a shorthand');
+        const [from, to] = [(low[0] as string).charCodeAt(0), (high[0] as string).charCodeAt(0)];
+        // Past printable ASCII the range's own first member stands in, so `[À-ÿ]` still yields one.
+        const inside = PRINTABLE.filter((ch) => ch.charCodeAt(0) >= from && ch.charCodeAt(0) <= to);
+        for (const ch of inside.length > 0 ? inside : [String.fromCharCode(from)]) members.add(ch);
+      } else {
+        for (const ch of low) members.add(ch);
+      }
+    }
+    this.at += 1;
+    return negated ? PRINTABLE.filter((ch) => !members.has(ch)) : [...members];
+  }
+
+  private classMember(): readonly string[] {
+    const c = this.peek() as string;
+    this.at += 1;
+    return c === '\\' ? this.escape(true) : [c];
+  }
+}
+
+const draw = (node: Node, random: () => number): string => {
+  const pick = <T>(items: readonly T[]): T | undefined =>
+    items[Math.floor(random() * items.length)];
+  if (node.kind === 'empty') return '';
+  if (node.kind === 'chars') return pick(node.chars) ?? '';
+  const branch = pick(node.branches) ?? [];
+  return branch
+    .map((piece) => {
+      const count = piece.min + Math.floor(random() * (piece.max - piece.min + 1));
+      return Array.from({ length: count }, () => draw(piece.node, random)).join('');
+    })
+    .join('');
+};
+
+/** Tries per sample: a draw that crosses an anchor (`a^b`) or a flag is retried, never returned. */
+const ATTEMPTS = 8;
+
+/**
+ * Up to `count` distinct strings `pattern.test` accepts, the same ones for the same `seed` on any
+ * machine. Empty when the pattern is past the subset, or when no draw lands inside it.
+ */
+export function patternSamples(pattern: RegExp, seed: string, count = 4): readonly string[] {
+  const tree = new Parser(pattern.source).parse();
+  if (tree === undefined) return [];
+  const random = seededRandom(fnv1a(`${pattern.source}/${pattern.flags}:${seed}`) || 1);
+  // `lastIndex` would make `test` stateful under `g`/`y`; a copy without them judges each draw.
+  const judge = new RegExp(pattern.source, pattern.flags.replace(/[gy]/g, ''));
+  const out: string[] = [];
+  for (let attempt = 0; attempt < count * ATTEMPTS && out.length < count; attempt += 1) {
+    const sample = draw(tree, random);
+    if (judge.test(sample) && !out.includes(sample)) out.push(sample);
+  }
+  return out;
+}

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));

package/src/subject-proof.ts

@@ -8,6 +8,7 @@ import { ctxOf, finiteOption, runWithContext, serviceActor } from '@ultimat3/cor
 import type { Subject, SubjectPlan } from '@ultimat3/jobs';
 import { memoryStepStore, planSubject, stepRunner, subjectEraseTables } from '@ultimat3/jobs';
 import { seedGraph } from './seed-graph';
+import { deferredMayStayNull } from './seed-graph-pass';
 import type { SeedFactory, SeedGraph, SeedWriter } from './seed-graph-plan';
 import { insertSeedGraph } from './seed-graph-plan';
 import type { SeedEntity } from './seed-graph-shape';
@@ -111,7 +112,8 @@ export async function subjectProof<I>(
     tenants: 2,
     ...(options.factories === undefined ? {} : { factories: options.factories }),
   });
-  await insertSeedGraph(graph, options.writer);
+  // The pass's rule: a nullable cycle key the database refuses to set stays null.
+  await insertSeedGraph(graph, deferredMayStayNull(options.writer));
   const tenant = graph.tenants[0] ?? null;
   const person = graph.inserts.find(
     (i) => i.entity === subject.entity && (i.tenant === tenant || i.tenant === null),