@ultimat3/testing 30.3.0 → 30.5.0

package/src/seed-graph-pass.ts

@@ -41,6 +41,31 @@ 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) =>
@@ -146,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)) };
 }

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-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':
@@ -104,6 +152,12 @@ const parsed = (column: SeedColumn, value: unknown): { readonly ok: unknown } |
   }
 };
 
+/**
+ * What every driver binds as SQL NULL — a JSON `null` included (`pg-row.ts` `bindable`): `t.json()`
+ * accepts it and the sampler draws it, so a NOT NULL `jsonb` column must never be offered one.
+ */
+const storesAsSqlNull = (value: unknown): boolean => value === null || value === undefined;
+
 /**
  * Every storable value for this column, most plausible first: the declared default, then what the
  * kind offers, then `null` when the column allows it. Empty means nothing generated is storable.
@@ -119,13 +173,23 @@ export function candidatesFor(
   const out: unknown[] = [];
   for (const value of raw) {
     const result = parsed(column, value);
-    if (result !== undefined && !out.some((seen) => Bun.deepEquals(seen, result.ok))) {
-      out.push(result.ok);
-    }
+    if (result === undefined || (meta.notNull && storesAsSqlNull(result.ok))) continue;
+    if (!out.some((seen) => Bun.deepEquals(seen, result.ok))) 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,
@@ -91,6 +92,7 @@ export function seedGraph(
     [...shapes.values()].map((shape) => ({
       name: shape.name,
       references: [...shape.references.values()],
+      updatable: shape.entity.$describe().appendOnly !== true,
     })),
   );
   const tenantStream = seededUuid(streamSeed(seed, '$tenants'));
@@ -163,6 +165,8 @@ export function seedGraph(
     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()) {
@@ -195,6 +199,7 @@ export function seedGraph(
                           ordinal,
                           canary,
                           position,
+                          patterns: patterns.get(property),
                           uuid: stream,
                         });
           return [
@@ -257,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/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),