@ultimat3/testing 30.3.0 → 30.4.0

package/CLAUDE.md

@@ -51,13 +51,13 @@ import is `registry-isolation.ts`, own entry point, off the barrel. Full rule: `
 | A passkey test signs for real | `softAuthenticator` is `@ultimat3/auth/soft-authenticator`'s, never re-exported here (one value, one path: `flight-copies`) and never a second one (auth's own suites need it, and auth cannot import testing) |
 | A reached job is crash-proven | `exercise-crash.ts`: `crashProof` with the control's input and actor, after the tenant proof; only `diverged` is red (`X_JOB_CRASH_DIVERGED`). Committed: job bodies escape transactions |
 | The tenant proof is taint only | `tenant-proof.ts`: B, A, B; B is A's role minus `tenancy:cross`. Leak = seeded canary or unhanded id (`tenant-canary.ts`); write = moved digest. Only `crossed` is red |
-| Every statement the pass sent is planned | `plan-sweep.ts` (`sweepPlans`): first relation an app table, `PREPARE` in a READ-ONLY transaction with seq/bitmap scans and sorts off, judged by `plan-oracle.ts`; red = `X_QUERY_UNINDEXED` / `X_QUERY_SORT_UNSERVED` with the `indexes:` entry (`plan-sweep-fix.ts`). `scan:` or `expectedSeqScan` is exempt, listed; no generic plan is `X_QUERY_PLAN_UNAVAILABLE`, never a pass |
+| Every statement the pass sent is planned | `plan-sweep.ts` (`sweepPlans`): first relation an app table, `PREPARE` in a READ-ONLY transaction with seq/bitmap scans and sorts off, judged by `plan-oracle.ts`; red = `X_QUERY_UNINDEXED` / `X_QUERY_SORT_UNSERVED` with the `indexes:` entry (`plan-sweep-fix.ts`). `scan:` or `expectedSeqScan` is exempt, listed; credited: a partial unique whose predicate the statement states (one row), a declared equality-then-range index under a limit; no generic plan is `X_QUERY_PLAN_UNAVAILABLE`, never a pass |
 | A shape that grows with the rows is red | `scale-sweep-run.ts`: two more tenants at `SCALE_SIZES` (2, 8 rows a table), every reached primitive once in each; `judgeScale` (pure) reds `X_QUERY_SCALES_WITH_ROWS`. Under `expectedQueryLoop` it is listed with its reason |
 | An erase is PROVED, not asserted | `subject-proof.ts` (`subjectProof`, run by cli's `exercise-subject.ts`): canaries in every table, one person erased, every stored row searched; a survivor outside `retain` is `X_SUBJECT_ERASE_INCOMPLETE`, naming table and column, never the value |
 | A captured failure replays as a test | `repro.ts`: `reproduce(bundle, { driver })` seeds the rows it read, freezes the clock at its instant, invokes as its actor; masked fields are stood in (`repro-stand-in.ts`). An unregistered name ANSWERS as the failure. `reproJob(runJobs, failure)` for a dead job. What `x repro --write` emits |
 | A vendor's answers are a cassette | `cassette.ts`: replay = one `mockFetch` route per recorded URL, seal kept (`X_CASSETTE_MISSING`, `X_CASSETTE_UNUSED`). Record = `ULTIMATE_CASSETTE=record` + `record.hosts`, refused under `CI` (`X_CASSETTE_RECORD_REFUSED`), headers allow-listed, credential keys masked, bytes scanned before disk (`X_CASSETTE_SECRET`). The request side is never written |
 | One seed writer | `entitySeedWriter({ entities, client \| driver })` (`seed-writer.ts`) writes through each entity's own repository; `snapshot` is required; `entity` loads on the first write, so the barrel stays entity-free |
-| Factory values are DECLARED | `factoriesFor` and `seedGraph` share `seed-graph-values.ts`: default, enum, kind, through `$parse`, never the name. `seed-graph*.ts` type-import `entity` only |
+| Factory values are DECLARED | `factoriesFor` and `seedGraph` share `seed-graph-values.ts`: default, enum, kind, a `matches()` pattern (`seed-pattern-sample.ts`, read off the CHECK by `seed-graph-patterns.ts`), `$meta.schema` (sampler `require`d on first use), through `$parse`, never the name. `seed-graph*.ts` type-import `entity` only |
 | e2e without a driver | `e2eTest` becomes `test.skip`; the gate reports the step SKIPPED (or `X_VERIFY_SUITE_VANISHED` when `x.verify.json` requires it), never passed |
 | The seam has an inverse | `resetE2eDriver()`: `useE2eDriver` writes MODULE scope, so a file that installs a browser undoes it |
 | Built vs declared | `clock` `mail` `network` `runJobs` `statements` `subscribe` are built in-process; `page` `budget` `signIn` `deploy` are declared and wait for a driver (`X_TEST_FIXTURE_UNAVAILABLE`). |

package/README.md

@@ -34,7 +34,8 @@ unitTest('the clock moves only when the test moves it', ({ clock }) => {
 | `seed-graph-error.ts` | `X_SEED_GRAPH_UNSATISFIED`, its fix naming the `defineFactory` to write; `X_SEED_GRAPH_ENTITY_UNKNOWN`, a plan and a writer built from two entity sets |
 | `seed-writer.ts` | `entitySeedWriter({ entities, client })` or `({ entities, driver? })` — the `SeedWriter` that writes a graph through each entity's own repository: Postgres or PGlite through a client, or a driver. `@ultimat3/entity` loads on the first write. `snapshot(rows)`, required on every `SeedWriter`, reads rows back as one digest each (`md5(t::text)` over a client), `null` for a row gone |
 | `exercise.ts` | `runExercisePass({ entities, writer, roles, seed?, overrides?, only? })` — every registered action, query and job once, each on its own committed tenant pair, one `ExerciseRecord` per primitive, the tenant proof's verdict on its `tenant`. What `x exercise` runs |
-| `define-exercise.ts` | `defineExercise({ <name>: { actor, input?, runs? } \| { off: '<why>' } }, { actor?: <entity>, factories?: { <entity name>: defineFactory(…) } })` — an app's overrides (the second argument names the entity whose rows are the actors, and the factories that build a table no generated row satisfies — a cross-column `satisfies` — keyed by entity name, unknown ones `X_DECLARATION_UNKNOWN`), `apps/web/exercise.ts`'s one export; a blank `off` is `X_CONTRACT_EXERCISE_UNDECLARED`, an unknown name `X_DECLARATION_UNKNOWN` when the pass runs |
+| `define-exercise.ts` | `defineExercise({ <name>: { actor, input?, runs? } \| { off: '<why>' } }, { actor?: <entity>, factories?: { <entity name>: defineFactory(…) }, setup?: () => mockFetch(…) \| cassette(…) })` — an app's overrides (the second argument names the entity whose rows are the actors, and the factories that build a table no generated row satisfies — a cross-column `satisfies` — keyed by entity name, unknown ones `X_DECLARATION_UNKNOWN`), `apps/web/exercise.ts`'s one export; a blank `off` is `X_CONTRACT_EXERCISE_UNDECLARED`, an unknown name `X_DECLARATION_UNKNOWN` when the pass runs |
+| `exercise-setup.ts` | `withExerciseSetup(room, setup)`: the app's `setup` run inside the sealed room before the first row, its handle disposed before the room restores the network; an `allowHost` in it is `X_EXERCISE_SETUP_UNSEALED`. Types `ExerciseSetup`, `ExerciseSetupHandle` |
 | `exercise-actor.ts` · `exercise-input.ts` · `exercise-report.ts` | the first `x policy explain` actor the policy allows, minted in the primitive's tenant · the input: override, then a seeded id by field stem, then the minimal draw (`@ultimat3/schema/sample`, loaded dynamically) · the room one run executes in (network sealed, mail captured, clock frozen) and its record, `overrideLine` the entry to paste |
 | `tenant-proof.ts` | internal (`CROSS_TENANT_SCOPE` is `@ultimat3/entity`'s): `proveTenant` — B with A's ids, A's own call, B again; each B leg between two snapshots of A's rows. `withoutCrossTenant` strips `tenancy:cross` (`CROSS_TENANT_SCOPE`) from B; `publicReason` decides `public` |
 | `tenant-canary.ts` | internal: `tenantTaint` — one tenant's rows, ids and marks (row canaries, key parts of `MIN_TAINT_ID_LENGTH` 8 or more no other tenant shares); `findTaint` — every path holding one |

package/package.json

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

package/src/define-exercise.ts

@@ -5,6 +5,7 @@
 
 import type { ExerciseOptions } from '@ultimat3/action';
 import { renderCauseValue, renderFixLiteral, UltimateError } from '@ultimat3/core';
+import type { ExerciseSetup } from './exercise-setup';
 import type { SeedFactory } from './seed-graph-plan';
 
 /** 39's option type, exactly: `{ actor, input?, runs? }` or `{ off: '<reason>' }`. */
@@ -18,6 +19,8 @@ export interface ExerciseOverrides {
   readonly actorEntity?: string;
   /** By entity name: the pass's graph builds those rows with them (`seedGraph`'s `factories`). */
   readonly factories?: Readonly<Record<string, SeedFactory>>;
+  /** The app's hook, run once inside the pass's sealed room (`exercise-setup.ts`). */
+  readonly setup?: ExerciseSetup;
 }
 
 /** What the whole pass needs to know of the app, beside the per-primitive entries. */
@@ -34,6 +37,13 @@ export interface ExerciseAppOptions {
    * refused when the pass runs.
    */
   readonly factories?: Readonly<Record<string, SeedFactory>>;
+  /**
+   * Run in the exercise process once the network is sealed, before the first row: install the
+   * `mockFetch` routes or `cassette()` your vendor-calling handlers need, so they run for real.
+   * What it returns (a cassette, any `Disposable`) is disposed after the pass. `allowHost` here is
+   * `X_EXERCISE_SETUP_UNSEALED` — the pass never sends a call out.
+   */
+  readonly setup?: ExerciseSetup;
 }
 
 /** `X_CONTRACT_EXERCISE_UNDECLARED`, 39's code for the same silence: an `off` with no reason. */
@@ -59,6 +69,7 @@ export function defineExercise(
     entries,
     ...(app.actor === undefined ? {} : { actorEntity: app.actor.$name }),
     ...(app.factories === undefined ? {} : { factories: app.factories }),
+    ...(app.setup === undefined ? {} : { setup: app.setup }),
   });
 }
 

package/src/errors.ts

@@ -69,6 +69,7 @@ export const TESTING_ERROR_CODES = [
   'X_CASSETTE_SECRET',
   'X_CASSETTE_RECORD_REFUSED',
   'X_TEST_MODULE_MOCK_UNRESTORABLE',
+  'X_EXERCISE_SETUP_UNSEALED',
 ] as const;
 
 export type TestingErrorCode = (typeof TESTING_ERROR_CODES)[number];
@@ -133,6 +134,7 @@ export const TESTING_ERROR_TITLES: Readonly<Record<TestingErrorCode, string>> =
   X_CASSETTE_SECRET: 'a cassette about to be written holds a secret value',
   X_CASSETTE_RECORD_REFUSED: 'a cassette recording was refused',
   X_TEST_MODULE_MOCK_UNRESTORABLE: 'a mocked module could not be put back at the file boundary',
+  X_EXERCISE_SETUP_UNSEALED: 'an exercise setup let a host through the seal',
 };
 
 // Titles must be registered for `format()` to render the contract's first line. Every code above is

package/src/exercise-job-tenant.ts

@@ -31,8 +31,15 @@ const answer = (handle: TenantOf, input: unknown): string | undefined => {
   }
 };
 
+/** How deep an absent parent is filled in to read past it: `payload.input.orgId` is two. */
+const ABSENT_DEPTH = 4;
+
+/** The value at `path`, `undefined` when any step of it is absent. */
+const getAt = (input: unknown, path: Path): unknown =>
+  path.reduce<unknown>((value, key) => (isPlainObject(value) ? value[key] : undefined), input);
+
 /** Every property path `tenantFor` read, at any depth of plain objects — a missing one included. */
-function pathsRead(handle: TenantOf, input: unknown): readonly Path[] {
+function readOnce(handle: TenantOf, input: unknown): readonly Path[] {
   const read: Path[] = [];
   const watch = (value: unknown, at: Path): unknown =>
     !isPlainObject(value)
@@ -49,8 +56,28 @@ function pathsRead(handle: TenantOf, input: unknown): readonly Path[] {
   return read;
 }
 
+/**
+ * Every path read, past absent parents too: a read that found nothing is filled with `{}` and read
+ * again, so `payload.input.orgId` — a scoped backfill's tenant, its `input` left out of the
+ * minimal draw — is found, not lost to the throw reading `orgId` of `undefined`.
+ */
+function pathsRead(handle: TenantOf, input: unknown, depth = 0): readonly Path[] {
+  const reads = readOnce(handle, input);
+  if (depth >= ABSENT_DEPTH) return reads;
+  const deeper = reads
+    .filter((path) => getAt(input, path) === undefined)
+    .flatMap((path) => pathsRead(handle, setAt(input, path, {}), depth + 1));
+  const seen = new Set<string>();
+  return [...reads, ...deeper].filter((path) => {
+    const key = JSON.stringify(path);
+    if (seen.has(key)) return false;
+    seen.add(key);
+    return true;
+  });
+}
+
 /** `input` with `path` set to `value`, copied along the path only. */
-function setAt(input: unknown, path: Path, value: string): unknown {
+function setAt(input: unknown, path: Path, value: unknown): unknown {
   const [head, ...rest] = path;
   if (head === undefined) return value;
   const base = isPlainObject(input) ? input : {};

package/src/exercise-report.ts

@@ -13,6 +13,7 @@ import {
 import type { RowObserver } from '@ultimat3/entity';
 import { captureDeterminism, installDeterminism, restoreCapturedDeterminism } from './determinism';
 import { testMail } from './fixture-mail';
+import { routeMatches } from './mock-route';
 import type { PlanProof, SentStatement } from './plan-sweep';
 import type { ScaleProof, StatementTally } from './scale-sweep';
 import {
@@ -228,6 +229,10 @@ export async function openExerciseRoom(): Promise<ExerciseRoom> {
     },
     end: (): Observed => {
       const calls = requestLog().slice(logFrom);
+      // A call a route answered never left the process: the app's `setup` installed it.
+      const { mocks } = captureNetwork();
+      const refused = (call: (typeof calls)[number]): boolean =>
+        !local(call.url) && !mocks.some((route) => routeMatches(route, call));
       const effects: ExerciseEffect[] = [
         ...[...tally(rows)].map(([key, count]): ExerciseEffect => {
           const [entity = '', op = ''] = key.split('\u0000');
@@ -241,11 +246,11 @@ export async function openExerciseRoom(): Promise<ExerciseRoom> {
             kind: 'network',
             method: call.method,
             host: hostOf(call.url),
-            refused: !local(call.url),
+            refused: refused(call),
           }),
         ),
       ];
-      const refusedHosts = calls.filter((call) => !local(call.url)).map((c) => hostOf(c.url));
+      const refusedHosts = calls.filter(refused).map((c) => hostOf(c.url));
       const payloads: EffectPayload[] = [
         ...mail.outbox().map(({ message }, i) => ({
           path: `effect.mail[${i}]`,

package/src/exercise-setup.ts

@@ -0,0 +1,68 @@
+// `defineExercise(…, { setup })`, run: the app's hook inside the pass's sealed room, before the
+// first row is seeded, disposed before the room restores the network. What it installs — a
+// `mockFetch` route, a `cassette()` — answers a vendor call; `allowHost` would send one for real.
+
+import { renderCauseValue, UltimateError } from '@ultimat3/core';
+import type { ExerciseRoom } from './exercise-report';
+import { captureNetwork } from './sealed-network';
+
+/** What a setup may hand back to be undone after the pass: a `cassette()`, a `using` resource. */
+export type ExerciseSetupHandle = Disposable | AsyncDisposable;
+
+/**
+ * Runs once per pass, in the exercise process, after the seal and before any primitive. Returns
+ * nothing when there is nothing to undo — a `mockFetch` route goes with the room.
+ */
+export type ExerciseSetup = () =>
+  | void
+  | ExerciseSetupHandle
+  | Promise<void>
+  | Promise<ExerciseSetupHandle>
+  | Promise<ExerciseSetupHandle | undefined>;
+
+const setupUnsealed = (hosts: readonly string[]): UltimateError =>
+  new UltimateError({
+    code: 'X_EXERCISE_SETUP_UNSEALED',
+    cause: `defineExercise(…, { setup }) called allowHost(${hosts.map((host) => renderCauseValue(host)).join(', ')}): the pass would send a primitive's call out for real, where every vendor is answered by mockFetch or cassette()`,
+    fix: "mockFetch('https://<host>/*', handler)   # or cassette(import.meta.dir, '<name>') — in apps/web/exercise.ts's setup, in place of allowHost('<host>')",
+    meta: { hosts },
+  });
+
+async function release(handle: unknown): Promise<void> {
+  if (typeof handle !== 'object' || handle === null) return;
+  if (Symbol.asyncDispose in handle) await (handle as AsyncDisposable)[Symbol.asyncDispose]();
+  else if (Symbol.dispose in handle) (handle as Disposable)[Symbol.dispose]();
+}
+
+/**
+ * `room` with `setup` run inside it. Its dispose releases what setup returned FIRST — a cassette's
+ * own check reads the routes the pass used — then the room. A setup that throws, or lets a host
+ * through, disposes both before the pass refuses.
+ */
+export async function withExerciseSetup(
+  room: ExerciseRoom,
+  setup: ExerciseSetup | undefined,
+): Promise<ExerciseRoom> {
+  if (setup === undefined) return room;
+  const before = new Set(captureNetwork().allowed);
+  let handle: unknown;
+  try {
+    handle = await setup();
+  } catch (error) {
+    await room[Symbol.asyncDispose]();
+    throw error;
+  }
+  const dispose = async (): Promise<void> => {
+    try {
+      await release(handle);
+    } finally {
+      await room[Symbol.asyncDispose]();
+    }
+  };
+  const opened = captureNetwork().allowed.filter((host) => !before.has(host));
+  if (opened.length > 0) {
+    await dispose();
+    throw setupUnsealed(opened);
+  }
+  return { ...room, [Symbol.asyncDispose]: dispose };
+}

package/src/exercise-subjects.ts

@@ -3,7 +3,7 @@
 // (`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 { renderCauseValue, renderFixShellArg, UltimateError } from '@ultimat3/core';
 import type { AnyJobHandle, JobExecution } from '@ultimat3/jobs';
 import { registeredJobs } from '@ultimat3/jobs';
 import type { Policy } from '@ultimat3/policy';
@@ -58,8 +58,22 @@ export function fixedTenant(name: string, declared: string | undefined) {
 
 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}`);
+/**
+ * What a failed run hands the verdict. A run whose error carried a code is that code again, so
+ * core's `exerciseDefect` judges it by the one rule an action's refusal meets: a coded refusal
+ * under 500 is the job answering "no", a 5xx or an uncoded throw is a defect. The message alone
+ * read every coded refusal — an app's 409 included — as an uncoded throw: X_CONTRACT_DEFECT.
+ */
+const jobFailure = (run: JobExecution | undefined): unknown => {
+  if (run === undefined) return 'the job never ran';
+  const message = run.error ?? `the run ended ${run.outcome}`;
+  if (run.code === undefined) return message;
+  return new UltimateError({
+    code: run.code,
+    cause: message,
+    fix: `x errors explain ${renderFixShellArg(run.code, '<code>')} --json`,
+  });
+};
 
 const jobSubject = (handle: AnyJobHandle): Subject => ({
   kind: 'job',
@@ -73,11 +87,11 @@ const jobSubject = (handle: AnyJobHandle): Subject => ({
     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.
+    // The worker's failure is on the row, never a throw: the attempt's error and its code.
     // 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) };
+      : { failure: jobFailure(own) };
   },
 });
 

package/src/exercise.ts

@@ -34,12 +34,13 @@ import type {
   Observed,
 } from './exercise-report';
 import { openExerciseRoom, overrideLine } from './exercise-report';
+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 { pairGraph, 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';
@@ -343,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;
@@ -372,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-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

@@ -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':
@@ -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,
@@ -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),