@ultimat3/testing 30.0.0 → 30.2.0

package/README.md

@@ -34,7 +34,7 @@ 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> })` — an app's overrides (the second argument names the entity whose rows are the actors), `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(…) } })` — 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-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.0.0",
+  "version": "30.2.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.0.0",
-    "@ultimat3/cache": "30.0.0",
-    "@ultimat3/core": "30.0.0",
-    "@ultimat3/db": "30.0.0",
-    "@ultimat3/entity": "30.0.0",
-    "@ultimat3/http": "30.0.0",
-    "@ultimat3/i18n": "30.0.0",
-    "@ultimat3/jobs": "30.0.0",
-    "@ultimat3/mail": "30.0.0",
-    "@ultimat3/policy": "30.0.0",
-    "@ultimat3/pwa": "30.0.0",
-    "@ultimat3/query": "30.0.0",
-    "@ultimat3/realtime": "30.0.0",
-    "@ultimat3/render": "30.0.0",
-    "@ultimat3/schema": "30.0.0",
-    "@ultimat3/time": "30.0.0"
+    "@ultimat3/action": "30.2.0",
+    "@ultimat3/cache": "30.2.0",
+    "@ultimat3/core": "30.2.0",
+    "@ultimat3/db": "30.2.0",
+    "@ultimat3/entity": "30.2.0",
+    "@ultimat3/http": "30.2.0",
+    "@ultimat3/i18n": "30.2.0",
+    "@ultimat3/jobs": "30.2.0",
+    "@ultimat3/mail": "30.2.0",
+    "@ultimat3/policy": "30.2.0",
+    "@ultimat3/pwa": "30.2.0",
+    "@ultimat3/query": "30.2.0",
+    "@ultimat3/realtime": "30.2.0",
+    "@ultimat3/render": "30.2.0",
+    "@ultimat3/schema": "30.2.0",
+    "@ultimat3/time": "30.2.0"
   }
 }

package/src/define-exercise.ts

@@ -5,6 +5,7 @@
 
 import type { ExerciseOptions } from '@ultimat3/action';
 import { renderCauseValue, renderFixLiteral, UltimateError } from '@ultimat3/core';
+import type { SeedFactory } from './seed-graph-plan';
 
 /** 39's option type, exactly: `{ actor, input?, runs? }` or `{ off: '<reason>' }`. */
 export type ExerciseOverride = ExerciseOptions;
@@ -15,6 +16,8 @@ export interface ExerciseOverrides {
   readonly entries: ReadonlyMap<string, ExerciseOverride>;
   /** The entity an actor is a row of, by name: its id is bound to a seeded row. */
   readonly actorEntity?: string;
+  /** By entity name: the pass's graph builds those rows with them (`seedGraph`'s `factories`). */
+  readonly factories?: Readonly<Record<string, SeedFactory>>;
 }
 
 /** What the whole pass needs to know of the app, beside the per-primitive entries. */
@@ -25,6 +28,12 @@ export interface ExerciseAppOptions {
    * writes a row that exists. Omitted, an actor's id is its role's name.
    */
   readonly actor?: { readonly $name: string };
+  /**
+   * By entity name, `seedGraph`'s own option: a table whose rows a generated value cannot satisfy
+   * (an `invariant` across columns) is built by the app's `defineFactory`. An unknown name is
+   * refused when the pass runs.
+   */
+  readonly factories?: Readonly<Record<string, SeedFactory>>;
 }
 
 /** `X_CONTRACT_EXERCISE_UNDECLARED`, 39's code for the same silence: an `off` with no reason. */
@@ -49,6 +58,7 @@ export function defineExercise(
     kind: 'exercise-overrides',
     entries,
     ...(app.actor === undefined ? {} : { actorEntity: app.actor.$name }),
+    ...(app.factories === undefined ? {} : { factories: app.factories }),
   });
 }
 

package/src/exercise.ts

@@ -418,6 +418,9 @@ export async function runExercisePass(
     graph = await seedPass(options.entities, options.writer, {
       primitives: live.length,
       seed: passSeed,
+      ...(options.overrides?.factories === undefined
+        ? {}
+        : { factories: options.overrides.factories }),
     });
     // In order, one at a time: the seams the room installs are the process's, not the primitive's.
     for (const subject of chosen) {
@@ -438,6 +441,7 @@ export async function runExercisePass(
     main: graph,
     seed: passSeed,
     room,
+    factories: options.overrides?.factories,
     setup: async (subject, sized, tenant, self) => {
       const full = chosen.find((one) => one.name === subject.name);
       return full === undefined

package/src/scale-sweep-graph.ts

@@ -3,7 +3,7 @@
 // every reference to one is pointed at the pass's own row in the same position. Pure.
 
 import { seedGraph } from './seed-graph';
-import type { SeedGraph } from './seed-graph-plan';
+import type { SeedFactory, SeedGraph } from './seed-graph-plan';
 import type { SeedEntity } from './seed-graph-shape';
 
 export interface ScaleGraph {
@@ -23,12 +23,18 @@ export interface ScaleGraph {
 export function scaleGraph(
   main: SeedGraph,
   entities: readonly SeedEntity[],
-  options: { readonly perTable: number; readonly seed: number },
+  options: {
+    readonly perTable: number;
+    readonly seed: number;
+    /** The app's `defineExercise` factories: a table only they satisfy is built by them here too. */
+    readonly factories?: Readonly<Record<string, SeedFactory>> | undefined;
+  },
 ): ScaleGraph {
   const sized = seedGraph(Object.fromEntries(entities.map((entity) => [entity.$name, entity])), {
     tenants: 1,
     perTable: options.perTable,
     seed: options.seed,
+    ...(options.factories === undefined ? {} : { factories: options.factories }),
   });
   const shared = (graph: SeedGraph) => graph.inserts.filter((insert) => insert.tenant === null);
   const theirs = shared(main);

package/src/scale-sweep-run.ts

@@ -10,7 +10,7 @@ import { testJobs } from './fixture-jobs';
 import type { ScaleProof, StatementTally } from './scale-sweep';
 import { judgeScale, SCALE_SIZES } from './scale-sweep';
 import { scaleGraph } from './scale-sweep-graph';
-import type { SeedGraph, SeedWriter } from './seed-graph-plan';
+import type { SeedFactory, SeedGraph, SeedWriter } from './seed-graph-plan';
 import { insertSeedGraph } from './seed-graph-plan';
 import type { SeedEntity } from './seed-graph-shape';
 
@@ -45,6 +45,8 @@ export interface ScaleSweepOptions {
   readonly seed: number;
   readonly room: ExerciseRoom;
   readonly setup: ScaleSetup;
+  /** `defineExercise`'s factories, handed to every sized graph as to the pass's own. */
+  readonly factories?: Readonly<Record<string, SeedFactory>> | undefined;
 }
 
 type Call = { readonly shapes: readonly StatementTally[] } | { readonly failed: string };
@@ -88,6 +90,7 @@ export async function scaleSweep(
     scaleGraph(options.main, options.entities, {
       perTable,
       seed: fnv1a(`scale:${options.seed}:${i}`) || 1,
+      factories: options.factories,
     }),
   );
   try {

package/src/seed-graph-error.ts

@@ -27,7 +27,7 @@ export class SeedGraphUnsatisfiedError extends UltimateError {
     super({
       code: 'X_SEED_GRAPH_UNSATISFIED',
       cause: `${input.entity}: ${input.what}`,
-      fix: `defineFactory(<the ${input.entity} entity>, { defaults: (index, ids) => ({ ${body} }) }), then seedGraph(entities, { factories: { ${name}: thatFactory } })`,
+      fix: `defineFactory(<the ${input.entity} entity>, { defaults: (index, ids) => ({ ${body} }) }), then seedGraph(entities, { factories: { ${name}: thatFactory } }) — for x exercise, defineExercise({}, { factories: { ${name}: thatFactory } }) in apps/web/exercise.ts`,
     });
   }
 }

package/src/seed-graph-pass.ts

@@ -3,10 +3,10 @@
 // owns a fresh tenant pair of its own. One graph also means one set of unique keys: per-primitive
 // graphs re-inserted the shared rows and collided on their primary keys.
 
-import { isUltimateError, renderThrowable } from '@ultimat3/core';
+import { isUltimateError, renderCauseValue, renderThrowable, UltimateError } from '@ultimat3/core';
 import { seedGraph } from './seed-graph';
 import { seedGraphUnsatisfied } from './seed-graph-error';
-import type { SeedGraph, SeedRow, SeedUpdate, SeedWriter } from './seed-graph-plan';
+import type { SeedFactory, SeedGraph, SeedRow, SeedUpdate, SeedWriter } from './seed-graph-plan';
 import { insertSeedGraph } from './seed-graph-plan';
 import type { SeedEntity } from './seed-graph-shape';
 
@@ -50,6 +50,15 @@ export const tenantPair = (graph: SeedGraph, index: number): readonly [string, s
   graph.tenants[index * TENANTS_PER_PRIMITIVE + 1] as string,
 ];
 
+/** A factory keyed by a name no seeded entity has would build nothing, and the red would stay. */
+const unknownFactory = (names: readonly string[], known: ReadonlySet<string>): UltimateError =>
+  new UltimateError({
+    code: 'X_DECLARATION_UNKNOWN',
+    cause: `defineExercise() factories name ${names.map((name) => renderCauseValue(name)).join(', ')}, which no seeded entity is called (seeded: ${renderCauseValue([...known].sort().join(', '))})`,
+    fix: "defineExercise({}, { factories: { '<the name entity(...) was declared with>': thatFactory } })   # in apps/web/exercise.ts; the seeded names are in the cause",
+    meta: { unknown: names, registered: [...known].sort() },
+  });
+
 /**
  * Plan and write the pass's graph: shared rows once, `TENANTS_PER_PRIMITIVE` tenants per
  * primitive. Same seed, same rows. Before any primitive runs, so a failure refuses the pass.
@@ -57,11 +66,19 @@ export const tenantPair = (graph: SeedGraph, index: number): readonly [string, s
 export async function seedPass(
   entities: readonly SeedEntity[],
   writer: SeedWriter,
-  options: { readonly primitives: number; readonly seed: number },
+  options: {
+    readonly primitives: number;
+    readonly seed: number;
+    readonly factories?: Readonly<Record<string, SeedFactory>>;
+  },
 ): Promise<SeedGraph> {
+  const known = new Set(entities.map((entity) => entity.$name));
+  const unknown = Object.keys(options.factories ?? {}).filter((name) => !known.has(name));
+  if (unknown.length > 0) throw unknownFactory(unknown, known);
   const graph = seedGraph(Object.fromEntries(entities.map((entity) => [entity.$name, entity])), {
     tenants: Math.max(1, options.primitives) * TENANTS_PER_PRIMITIVE,
     seed: options.seed,
+    ...(options.factories === undefined ? {} : { factories: options.factories }),
   });
   await insertSeedGraph(graph, coded(writer));
   return graph;

package/src/seed-graph-plan.ts

@@ -6,6 +6,13 @@
 export interface SeedFactory {
   build(): object;
   reset(): void;
+  /**
+   * Columns that follow from what the GRAPH chose — its keys and references, which no factory
+   * builds: `memorial_templates.scopeKey` from `ownerOrgId`. Called on each candidate row before
+   * its rules are judged; what it answers wins. A `defineFactory` with it:
+   * `{ build: () => f.build(), reset: () => f.reset(), derive: (row) => ({ … }) }`.
+   */
+  derive?(row: Readonly<Record<string, unknown>>): object;
 }
 
 export interface SeedGraphOptions {

package/src/seed-graph-row.ts

@@ -17,6 +17,8 @@ export interface RowProblem {
   readonly uniques: readonly (readonly string[])[];
   /** Per entry of `uniques`, the keys earlier rows already hold. */
   readonly taken: readonly ReadonlySet<string>[];
+  /** A factory's `derive`: columns that follow from the picked ones, applied before any rule. */
+  readonly derive?: ((row: Readonly<Record<string, unknown>>) => object) | undefined;
 }
 
 export type RowSolution =
@@ -77,7 +79,7 @@ const build = (problem: RowProblem, picks: readonly number[]): Record<string, un
   problem.columns.forEach(([property, candidates], index) => {
     row[property] = candidates[picks[index] ?? 0];
   });
-  return row;
+  return problem.derive === undefined ? row : { ...row, ...problem.derive(row) };
 };
 
 /** Odometer over the varied columns, last one fastest: deterministic and exhaustive up to the cap. */

package/src/seed-graph-shape.ts

@@ -26,6 +26,12 @@ export interface EntityShape {
   readonly references: ReadonlyMap<string, ReferenceDescription>;
   readonly checks: readonly RowCheck[];
   readonly uniques: readonly (readonly string[])[];
+  /**
+   * The uniques with a `where`: SQL the generator cannot evaluate, so held as total — stricter than
+   * the table — unless a factory builds every one of their columns, when the database judges them.
+   * `orgs: unique(kind) where kind = 'staff'` otherwise ran an enum out of values (`X_SEED_GRAPH_UNSATISFIED`).
+   */
+  readonly partialUniques: readonly (readonly string[])[];
   /**
    * The soft-delete property, or `null`. Seeded null unless a factory builds it: a row born deleted
    * is invisible to every read.
@@ -83,15 +89,25 @@ export function shapeOf(entity: SeedEntity): EntityShape {
         holds: (row) => invariant.holds(row),
       }),
     );
-  // A partial unique (`where`) is treated as total: stricter than the table, never looser.
   const uniques = dedupe([
     entity.$primaryKey,
     ...description.columns.filter((column) => column.unique).map((c) => toProperties([c.column])),
     ...entity.$invariants
-      .filter((invariant) => invariant.kind === 'unique')
+      .filter((invariant) => invariant.kind === 'unique' && invariant.where === undefined)
       .map((invariant) => toProperties(invariant.columns)),
-    ...description.indexes.filter((index) => index.unique).map((i) => toProperties(i.columns)),
+    ...description.indexes
+      .filter((index) => index.unique && index.where === null)
+      .map((i) => toProperties(i.columns)),
   ]);
+  const total = new Set(uniques.map((set) => set.join('\u0000')));
+  const partialUniques = dedupe([
+    ...entity.$invariants
+      .filter((invariant) => invariant.kind === 'unique' && invariant.where !== undefined)
+      .map((invariant) => toProperties(invariant.columns)),
+    ...description.indexes
+      .filter((index) => index.unique && index.where !== null)
+      .map((i) => toProperties(i.columns)),
+  ]).filter((set) => !total.has(set.join('\u0000')));
   return {
     entity,
     name: entity.$name,
@@ -99,6 +115,7 @@ export function shapeOf(entity: SeedEntity): EntityShape {
     references: new Map(entity.$references().map((reference) => [reference.property, reference])),
     checks,
     uniques,
+    partialUniques,
     softDelete: description.softDelete ? SEED_SOFT_DELETE_PROPERTY : null,
   };
 }

package/src/seed-graph.ts

@@ -135,7 +135,8 @@ export function seedGraph(
     const factory = options.factories?.[name];
     const rows: Placed[] = [];
     placed.set(name, rows);
-    const taken = shape.uniques.map(() => new Set<string>());
+    const allUniques = [...shape.uniques, ...shape.partialUniques];
+    const taken = allUniques.map(() => new Set<string>());
     const rootProperty = roots.get(name);
     const buckets: readonly (string | null)[] = scoped(name) ? tenants : [null];
     let ordinal = 0;
@@ -176,11 +177,19 @@ export function seedGraph(
             candidates.length === 0 ? refuseEmpty(shape, property, tenant) : candidates,
           ] as const;
         });
+        // A partial unique whose every column the factory built is the database's to judge.
+        const held = allUniques
+          .map((set, i) => [set, taken[i] as Set<string>] as const)
+          .filter(
+            ([set], i) =>
+              i < shape.uniques.length || !set.every((property) => Object.hasOwn(built, property)),
+          );
         const problem: RowProblem = {
           columns,
           checks: shape.checks,
-          uniques: shape.uniques,
-          taken,
+          uniques: held.map(([set]) => set),
+          taken: held.map(([, set]) => set),
+          derive: factory?.derive?.bind(factory),
         };
         const solved = solveRow(problem);
         if (!solved.ok) {
@@ -197,7 +206,7 @@ export function seedGraph(
           });
         }
         const row = { ...solved.row };
-        shape.uniques.forEach((set, i) => {
+        allUniques.forEach((set, i) => {
           const key = uniqueKey(row, set);
           if (key !== undefined) taken[i]?.add(key);
         });

package/src/subject-proof.ts

@@ -8,7 +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 type { SeedGraph, SeedWriter } from './seed-graph-plan';
+import type { SeedFactory, SeedGraph, SeedWriter } from './seed-graph-plan';
 import { insertSeedGraph } from './seed-graph-plan';
 import type { SeedEntity } from './seed-graph-shape';
 import { SubjectEraseIncompleteError } from './subject-proof-error';
@@ -22,6 +22,8 @@ export interface SubjectProofOptions {
   /** Every stored row of one table, as the database holds it, unscoped. */
   readonly read: (entity: SeedEntity) => Promise<readonly Stored[]>;
   readonly seed?: number;
+  /** `defineExercise`'s factories: a table only they satisfy is built by them for the proof too. */
+  readonly factories?: Readonly<Record<string, SeedFactory>> | undefined;
 }
 
 export interface SubjectProofResult {
@@ -107,6 +109,7 @@ export async function subjectProof<I>(
   const graph = seedGraph(Object.fromEntries(entities), {
     seed: finiteOption('subjectProof', 'seed', options.seed ?? 1),
     tenants: 2,
+    ...(options.factories === undefined ? {} : { factories: options.factories }),
   });
   await insertSeedGraph(graph, options.writer);
   const tenant = graph.tenants[0] ?? null;