@ultimat3/testing 30.0.0 → 30.1.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.1.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.1.0",
+    "@ultimat3/cache": "30.1.0",
+    "@ultimat3/core": "30.1.0",
+    "@ultimat3/db": "30.1.0",
+    "@ultimat3/entity": "30.1.0",
+    "@ultimat3/http": "30.1.0",
+    "@ultimat3/i18n": "30.1.0",
+    "@ultimat3/jobs": "30.1.0",
+    "@ultimat3/mail": "30.1.0",
+    "@ultimat3/policy": "30.1.0",
+    "@ultimat3/pwa": "30.1.0",
+    "@ultimat3/query": "30.1.0",
+    "@ultimat3/realtime": "30.1.0",
+    "@ultimat3/render": "30.1.0",
+    "@ultimat3/schema": "30.1.0",
+    "@ultimat3/time": "30.1.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) {

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;