@ultimat3/testing 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 developerz.ai
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,130 @@
+# @ultimat3/testing
+
+The harness. Never mock the database — clone it. Never assert on wall-clock time — advance the
+frozen clock. Never let a test reach the network unmocked — it fails by design.
+
+## What it owns
+
+| Module | Owns |
+|---|---|
+| `harness.ts` | `describeApp()` / `testApp()` — boot an app in-process with its own database |
+| `template-db.ts` | N workers, N databases, one migrated template, `CREATE DATABASE ... TEMPLATE` |
+| `determinism.ts` | frozen clock, seeded RNG, seeded uuids, `assertDeterministic` |
+| `sealed-network.ts` | any unmocked egress fails, with the URL and the mock line |
+| `factories.ts` | typed factories from the entity registry, seeded |
+| `test-types.ts` | the six test types and their helpers |
+| `matchers.ts` | `toBeUltimateError` `toDenyPolicy` `toEmitSteps` `toMatchOpenApi` `toBeWithinBudget` `toRejectInput` |
+| `fixtures.ts` | the registry + `test('…', ({ clock }) => …)` injection |
+| `fixture-{clock,mail,jobs,network}.ts` | the four fixtures the framework builds in-process |
+| `fixture-drivers.ts` | the five it declares but a driver must build — `page` `budget` `signIn` `deploy` `subscribe` |
+| `framework-fixtures.ts` | registers both sets; the app registers only what it owns |
+| `preload.ts` | the bunfig preload that installs all of the above |
+
+## Install
+
+```toml
+# bunfig.toml
+[test]
+preload = ["@ultimat3/testing/preload"]
+```
+
+## Fixtures
+
+`test` from this package passes a fixture bag as the first argument, and builds only what the
+body destructures — a test that never names `runJobs` never starts a queue.
+
+```ts
+import { expect, test } from '@ultimat3/testing';
+
+test('the three-day sleep releases the worker', async ({ clock, runJobs }) => {
+  await runJobs(onboardOrg, { orgId });
+  expect(await runJobs.inFlight()).toBe(0);   // suspended, not waiting
+  clock.advance('3d');
+  expect(await runJobs.due()).toBe(1);
+});
+```
+
+| Fixture | Is | Built by |
+|---|---|---|
+| `clock` | `now()` · `advance('3d')` · `set(instant)` on the frozen clock | the preload |
+| `mail` | `outbox()` · `lastTo(address)` · `failOnce(mail)` over an in-memory transport | the preload |
+| `network` | `offline()` · `drop()` · `online()` · `state()` over the sealed network | the preload |
+| `runJobs` | a worker: call it to enqueue+drain, then `drain()` `due()` `inFlight()` `depth()` | the preload |
+| `page` | the browser: `goto` `gotoStreamed` `getByRole` `evaluate` `waitForServiceWorker` | a browser driver |
+| `budget` | `jsBytes(route)` measured off the built output | a browser driver |
+| `signIn` | put the browser session in a member's shoes | a browser driver |
+| `deploy` | `newBuild()` — same app, new build id, page still open | a browser driver |
+| `subscribe` | one subscriber's `rows()` `patches()` `settled()` `lsn()` | a replicator |
+| anything else | whatever the app registers | the app's `scripts/test-setup.ts` |
+
+The last five are **declared but not built**: the name resolves, and destructuring one in a process
+with no driver fails as `X_TEST_FIXTURE_UNAVAILABLE`, naming the driver rather than telling you to
+register a fixture that is not yours to define. A driver arrives through the same registry —
+`defineFixtures` merges, last registration wins — so there is no second seam to learn.
+
+The declaration is also the driver's type: `defineFixtures` holds every name `Fixtures` declares to
+the type it was declared with, so a half-built `page` is a compile error at the registration rather
+than a missing method three awaits into a later test.
+
+`mail`, `network` and `runJobs` install a process-global driver for the length of one test and hand the previous one back afterwards — the state they *found*, not a fixed default, so an outer fixture already offline stays offline when an inner one disposes. A fixture that takes over a global does the same: implement `Symbol.dispose` or `Symbol.asyncDispose` on what the factory returns, and `fixtureTest` calls it in reverse build order — including when the test body throws. Going offline is the `network` fixture's job and only its job; the gate's writer is not exported, because a test that set it directly would skip that disposal and take every later file down with it.
+
+An app adds its own with `defineFixtures` and widens the type by augmenting `Fixtures`:
+
+```ts
+defineFixtures({ seed: () => loadSeed, actorFor: () => actorFor });
+
+declare module '@ultimat3/testing' {
+  interface Fixtures {
+    readonly seed: (name: string) => SeedHandle;
+  }
+}
+```
+
+Destructuring a name nobody registered fails with `X_TEST_FIXTURE_UNKNOWN`, which names the set
+that *is* registered — never `undefined is not an object` from inside the body. A name that is
+registered but has no driver fails with `X_TEST_FIXTURE_UNAVAILABLE` instead; the two are different
+instructions, so they are different codes.
+
+## The six test types
+
+| Helper | Asserts | `x verify` step |
+|---|---|---|
+| `unitTest` | pure logic, no I/O | `unit` |
+| `contractTest` | OpenAPI diff vs the committed spec, MCP exposure | `contract` |
+| `liveTest` | exactly what each subscriber receives | `live` |
+| `jobTest` | step sequence, retries, idempotency | `job` |
+| `e2eTest` | Playwright incl. offline mode + SW update | `e2e` |
+| `evalTest` | LLM output scoring against a threshold | `eval` |
+
+Each helper prefixes the test name with its type (`job · onboards an org`), which is what
+`bun test --test-name-pattern "job · "` selects — the six lines of `x verify` come from the tests
+themselves, not from a directory convention.
+
+## Parallel databases
+
+```ts
+const db = await acquireWorkerDatabase({ adminUrl, migrate });
+// worker 0 -> ultimate_test_template_w0
+// worker 1 -> ultimate_test_template_w1
+```
+
+The first worker creates the template under a Postgres advisory lock and migrates it once; every
+worker then clones it copy-on-write. With no Postgres configured it falls back to PGlite, so
+`bun test` works on a laptop with nothing installed.
+
+## Sealed network
+
+```
+X_TEST_NETWORK_SEALED
+  cause: POST https://api.stripe.com/v1/charges was not mocked (allowed hosts: none)
+  fix:   mockFetch('https://api.stripe.com/v1/charges', () => new Response('{}')) — or allowHost('api.stripe.com') if it must be real
+```
+
+A server this process booted is exempt: `createServer().start()` announces its socket through
+core's `markListening()`, so a test may call its own `handle.url()` on a kernel-assigned port with
+the seal fully on. Unsealing (`ULTIMATE_TEST_ALLOW_NET=1`) stays reserved for a deliberate live
+integration — never for a socket test.
+
+## Errors
+
+`X_TEST_NETWORK_SEALED` `X_TEST_DB_UNAVAILABLE` `X_TEST_NONDETERMINISTIC` `X_TEST_FIXTURE_UNKNOWN`

package/package.json

@@ -0,0 +1,40 @@
+{
+  "name": "@ultimat3/testing",
+  "version": "1.0.0",
+  "description": "Test harness: cloned template DBs per worker, frozen clock, sealed network, 6 test types",
+  "license": "MIT",
+  "type": "module",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/developerz-ai/ultimate.git",
+    "directory": "packages/testing"
+  },
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  },
+  "exports": {
+    ".": "./src/index.ts",
+    "./preload": "./src/preload.ts"
+  },
+  "files": [
+    "src",
+    "!src/**/*.test.ts",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "bun": ">=1.3.0"
+  },
+  "scripts": {
+    "typecheck": "tsc --noEmit -p tsconfig.json",
+    "test": "bun test"
+  },
+  "dependencies": {
+    "@ultimat3/core": "1.0.0",
+    "@ultimat3/db": "1.0.0",
+    "@ultimat3/jobs": "1.0.0",
+    "@ultimat3/mail": "1.0.0",
+    "@ultimat3/time": "1.0.0"
+  }
+}

package/src/determinism.ts

@@ -0,0 +1,133 @@
+// Determinism, installed globally by the test preload. Anything nondeterministic in a test is a
+// bug: a frozen clock means "advance it", a seeded RNG means "same values every run", and both are
+// restorable so a test that genuinely needs real time can opt out explicitly.
+
+import { NondeterministicError } from './errors';
+
+export const DEFAULT_SEED = 20260101;
+export const DEFAULT_NOW = '2026-01-01T00:00:00.000Z';
+
+const RealDate = Date;
+const realRandom = Math.random;
+// Captured up front: the brand check below is only unforgeable while this is the engine's own
+// `getTime` and not whatever a later assignment to `Date.prototype.getTime` left there.
+const dateGetTime = RealDate.prototype.getTime;
+
+let frozenAt = new RealDate(DEFAULT_NOW).getTime();
+let installed = false;
+
+/** mulberry32: 32 bits of state, uniform enough for tests, identical across platforms and runs. */
+export function seededRandom(seed: number): () => number {
+  let state = seed >>> 0;
+  return () => {
+    state = (state + 0x6d2b79f5) >>> 0;
+    let t = state;
+    t = Math.imul(t ^ (t >>> 15), t | 1);
+    t ^= t + Math.imul(t ^ (t >>> 7), t | 61);
+    return ((t ^ (t >>> 14)) >>> 0) / 4294967296;
+  };
+}
+
+/** A seeded id generator, so factories produce stable uuids without a real RNG. */
+export function seededUuid(seed: number): () => string {
+  const next = seededRandom(seed);
+  const hex = (count: number): string =>
+    Array.from({ length: count }, () => Math.floor(next() * 16).toString(16)).join('');
+  return () => `${hex(8)}-${hex(4)}-4${hex(3)}-a${hex(3)}-${hex(12)}`;
+}
+
+class FrozenDate extends RealDate {
+  constructor(...args: readonly unknown[]) {
+    if (args.length === 0) {
+      super(frozenAt);
+      return;
+    }
+    // Delegating with a spread keeps every real Date constructor overload working unchanged.
+    super(...(args as ConstructorParameters<typeof RealDate>));
+  }
+
+  static override now(): number {
+    return frozenAt;
+  }
+
+  /**
+   * While the harness is installed `globalThis.Date` is this subclass, so `value instanceof Date`
+   * asks "is it a FrozenDate" — and a Date the runtime built for itself is not one: a timestamptz
+   * off a Postgres socket, a `structuredClone`, anything from another realm. Every
+   * `value instanceof Date` guard in the framework would then reject a real Date under test and
+   * nowhere else, which is the worst place a difference can be. Freezing the clock must not change
+   * what a Date *is*, so answer for the internal slot rather than for a prototype chain.
+   *
+   * `value instanceof RealDate` is not that answer: `instanceof` is per-realm, so a Date built in
+   * a `node:vm` context or a worker — the "another realm" case above — still comes back false. A
+   * `[object Date]` from `Object.prototype.toString` is not it either: any object carrying
+   * `Symbol.toStringTag: 'Date'` passes that. `getTime` throws for anything without a
+   * `[[DateValue]]` slot, and that slot is the one thing neither a fake nor a realm can hide.
+   */
+  static override [Symbol.hasInstance](value: unknown): boolean {
+    try {
+      dateGetTime.call(value);
+      return true;
+    } catch {
+      return false;
+    }
+  }
+}
+
+export interface DeterminismOptions {
+  readonly seed?: number;
+  readonly now?: string | number;
+}
+
+/** Install the frozen clock and the seeded RNG globally. Idempotent. */
+export function installDeterminism(options: DeterminismOptions = {}): void {
+  frozenAt = new RealDate(options.now ?? DEFAULT_NOW).getTime();
+  const next = seededRandom(options.seed ?? DEFAULT_SEED);
+  globalThis.Date = FrozenDate as unknown as DateConstructor;
+  Math.random = next;
+  installed = true;
+}
+
+export function restoreDeterminism(): void {
+  globalThis.Date = RealDate;
+  Math.random = realRandom;
+  installed = false;
+}
+
+export const isDeterminismInstalled = (): boolean => installed;
+
+/** Move the frozen clock forward. The only legal way for time to pass inside a test. */
+export function advanceClock(ms: number): Date {
+  frozenAt += ms;
+  return new RealDate(frozenAt);
+}
+
+export const frozenNow = (): Date => new RealDate(frozenAt);
+
+export function setFrozenClock(now: string | number): void {
+  frozenAt = new RealDate(now).getTime();
+}
+
+/** Run `body` with the clock frozen at `now`, then restore whatever was there before. */
+export async function frozenClock<T>(now: string, body: () => T | Promise<T>): Promise<T> {
+  const previous = frozenAt;
+  frozenAt = new RealDate(now).getTime();
+  try {
+    return await body();
+  } finally {
+    frozenAt = previous;
+  }
+}
+
+/**
+ * Run a body twice and fail if the results differ. Used by the harness to catch the tests that
+ * only pass because they ran first.
+ */
+export async function assertDeterministic<T>(what: string, body: () => T | Promise<T>): Promise<T> {
+  const first = await body();
+  const second = await body();
+  const a = JSON.stringify(first);
+  const b = JSON.stringify(second);
+  if (a !== b) throw new NondeterministicError({ what, first: a, second: b });
+  return first;
+}

package/src/errors.ts

@@ -0,0 +1,202 @@
+// The X_* codes owned by @ultimat3/testing. A test failure has to be as actionable as a runtime
+// failure — the fix line here is the mock to add, the service to start, or the seed to freeze.
+import { registerErrorCodes, UltimateError } from '@ultimat3/core';
+
+export const TESTING_ERROR_CODES = [
+  'X_TEST_NETWORK_SEALED',
+  'X_TEST_NETWORK_OFFLINE',
+  'X_TEST_DB_UNAVAILABLE',
+  'X_TEST_NONDETERMINISTIC',
+  'X_TEST_FIXTURE_UNKNOWN',
+  'X_TEST_FIXTURE_UNAVAILABLE',
+  'X_TEST_EVAL_THRESHOLD',
+  'X_TEST_SCHEMA_EXPECTED',
+  'X_TEST_JOB_EXPECTED',
+  'X_TEST_NETWORK_RACE',
+] as const;
+
+export type TestingErrorCode = (typeof TESTING_ERROR_CODES)[number];
+
+export const TESTING_ERROR_TITLES: Readonly<Record<TestingErrorCode, string>> = {
+  X_TEST_NETWORK_SEALED: 'a test tried to reach the network',
+  X_TEST_NETWORK_OFFLINE: 'the test network is offline',
+  X_TEST_DB_UNAVAILABLE: 'no Postgres for the test template',
+  X_TEST_NONDETERMINISTIC: 'a test read wall-clock time or unseeded randomness',
+  X_TEST_FIXTURE_UNKNOWN: 'a test requested a fixture nobody registered',
+  X_TEST_FIXTURE_UNAVAILABLE: 'a declared fixture has no driver in this process',
+  X_TEST_EVAL_THRESHOLD: 'an evalTest() score fell below its threshold',
+  X_TEST_SCHEMA_EXPECTED: 'a matcher expected a Standard Schema and got something else',
+  X_TEST_JOB_EXPECTED: 'a matcher expected a job declaration and got something else',
+  X_TEST_NETWORK_RACE: 'a request raced unsealNetwork() and lost the patched fetch',
+};
+
+// Titles must be registered for `format()` to render the contract's first line. Every code above is
+// owned here and none is borrowed, so the call is unconditional: a second package claiming one has
+// to fail as X_ERROR_CODE_DUPLICATE, not quietly keep whichever title was registered first.
+registerErrorCodes(
+  Object.fromEntries(
+    Object.entries(TESTING_ERROR_TITLES).map(([code, title]) => [code, { title }]),
+  ),
+);
+
+const docsFor = (code: TestingErrorCode): string => `https://ultimate.dev/errors/${code}`;
+
+/** A test reached the network without a mock or an allowlist entry. Always a bug, never a flake. */
+export class NetworkSealedError extends UltimateError {
+  constructor(input: { url: string; method: string; allowed: readonly string[] }) {
+    super({
+      code: 'X_TEST_NETWORK_SEALED',
+      cause: `${input.method} ${input.url} was not mocked (allowed hosts: ${
+        input.allowed.length > 0 ? input.allowed.join(', ') : 'none'
+      })`,
+      fix: `mockFetch('${input.url}', () => new Response('{}')) — or allowHost('${hostOf(input.url)}') if it must be real`,
+      docs: docsFor('X_TEST_NETWORK_SEALED'),
+    });
+  }
+}
+
+/** No Postgres and no PGlite: the harness cannot give the test a database to clone. */
+export class TestDatabaseUnavailableError extends UltimateError {
+  constructor(input: { cause: string }) {
+    super({
+      code: 'X_TEST_DB_UNAVAILABLE',
+      cause: input.cause,
+      fix: 'x dev (embedded Postgres), or set TEST_DATABASE_URL to a running Postgres',
+      docs: docsFor('X_TEST_DB_UNAVAILABLE'),
+    });
+  }
+}
+
+/** Two runs of the same test produced different values. The seed or the clock is not frozen. */
+export class NondeterministicError extends UltimateError {
+  constructor(input: { what: string; first: string; second: string }) {
+    super({
+      code: 'X_TEST_NONDETERMINISTIC',
+      cause: `${input.what} produced "${input.first}" then "${input.second}"`,
+      fix: 'wrap the test in frozenClock() / seededRandom(), or remove the wall-clock read',
+      docs: docsFor('X_TEST_NONDETERMINISTIC'),
+    });
+  }
+}
+
+export function hostOf(url: string): string {
+  try {
+    return new URL(url).host;
+  } catch {
+    return url;
+  }
+}
+
+/**
+ * A test destructured a fixture nobody registered. Naming the registered set matters: the
+ * failure would otherwise surface as `undefined is not an object` deep inside the body,
+ * pointing at the use rather than the missing registration.
+ */
+export class FixtureUnknownError extends UltimateError {
+  constructor(input: { name: string; registered: readonly string[] }) {
+    super({
+      code: 'X_TEST_FIXTURE_UNKNOWN',
+      cause:
+        input.registered.length === 0
+          ? `test requested fixture "${input.name}" but none are registered`
+          : `test requested fixture "${input.name}"; registered: ${input.registered.join(', ')}`,
+      fix: `register it at test setup: defineFixtures({ ${input.name}: () => buildIt() })`,
+      docs: docsFor('X_TEST_FIXTURE_UNKNOWN'),
+    });
+  }
+}
+
+export const fixtureUnknown = (name: string, registered: readonly string[]): UltimateError =>
+  new FixtureUnknownError({ name, registered });
+
+/**
+ * Different failure from `X_TEST_FIXTURE_UNKNOWN`, and the distinction is the whole point: the
+ * name IS registered, so "register it" is the wrong instruction. What is missing is the driver
+ * underneath — a browser, a replicator — which the framework declares but deliberately does not
+ * bundle. Naming what it needs turns "undefined is not an object" into a decision the reader can
+ * make: install the driver, or stop asking for the fixture.
+ */
+export class FixtureUnavailableError extends UltimateError {
+  constructor(input: { name: string; needs: string }) {
+    super({
+      code: 'X_TEST_FIXTURE_UNAVAILABLE',
+      cause: `fixture "${input.name}" is declared but nothing in this process drives it — it needs ${input.needs}`,
+      fix: `install one in the test preload: defineFixtures({ ${input.name}: () => yourDriver() })`,
+      docs: docsFor('X_TEST_FIXTURE_UNAVAILABLE'),
+    });
+  }
+}
+
+export const fixtureUnavailable = (name: string, needs: string): UltimateError =>
+  new FixtureUnavailableError({ name, needs });
+
+/**
+ * A request made while `network.offline()` (or `network.drop()`) is in force. Coded rather than a
+ * bare `TypeError` because a test that lands here uncaught needs to know which of the two it was:
+ * the app's offline path not running, or a fixture left offline by the test before it.
+ */
+export class NetworkOfflineError extends UltimateError {
+  constructor(input: { url: string; method: string; mode: 'offline' | 'dropped' }) {
+    super({
+      code: 'X_TEST_NETWORK_OFFLINE',
+      cause: `${input.method} ${input.url} while the test network is ${input.mode}`,
+      fix: 'network.online() before the call — or assert the offline path instead of the request',
+      docs: docsFor('X_TEST_NETWORK_OFFLINE'),
+    });
+  }
+}
+
+/** `evalTest()`'s score fell below its declared threshold. A test failure, not a warning. */
+export class TestEvalThresholdError extends UltimateError {
+  constructor(input: { name: string; threshold: number; detail: string }) {
+    super({
+      code: 'X_TEST_EVAL_THRESHOLD',
+      cause: `eval "${input.name}" scored below ${input.threshold}: ${input.detail}`,
+      fix: 'improve the prompt under test, or lower the threshold passed to evalTest()',
+      docs: docsFor('X_TEST_EVAL_THRESHOLD'),
+    });
+  }
+}
+
+/** `toRejectInput`/`toAcceptInput` were handed something other than a Standard Schema. */
+export class TestSchemaExpectedError extends UltimateError {
+  constructor() {
+    super({
+      code: 'X_TEST_SCHEMA_EXPECTED',
+      cause: 'toRejectInput/toAcceptInput expect a Standard Schema (`t`), not the action',
+      // Names the call, not the intent: "assert against action.input" left the reader to work out
+      // which call to edit, and a fix is only executable if it can be pasted over the failing line.
+      fix: 'call toRejectInput(action.input) — the schema, not toRejectInput(action) or the query',
+      docs: docsFor('X_TEST_SCHEMA_EXPECTED'),
+    });
+  }
+}
+
+/** `toEmitSteps`/`recordSteps` were handed something other than a job declaration. */
+export class TestJobExpectedError extends UltimateError {
+  constructor() {
+    super({
+      code: 'X_TEST_JOB_EXPECTED',
+      cause: 'toEmitSteps expects a job declaration built with job(...)',
+      // Same rule as X_TEST_SCHEMA_EXPECTED's: the paste-able call, not a description of it.
+      fix: 'call toEmitSteps(myJob) with the job export, not toEmitSteps(myJob.run)',
+      docs: docsFor('X_TEST_JOB_EXPECTED'),
+    });
+  }
+}
+
+/**
+ * `sealNetwork()` always sets the original `fetch` before installing its patch, so this can only
+ * fire if `unsealNetwork()` ran concurrently with a request from the same seal — a race, not a
+ * reachable steady state.
+ */
+export class NetworkRaceError extends UltimateError {
+  constructor() {
+    super({
+      code: 'X_TEST_NETWORK_RACE',
+      cause: 'sealed network lost its original fetch mid-request',
+      fix: 'do not call unsealNetwork() while a request from the same test is still in flight',
+      docs: docsFor('X_TEST_NETWORK_RACE'),
+    });
+  }
+}

package/src/factories.ts

@@ -0,0 +1,99 @@
+// Typed factories derived from the entity registry. Rows come from the entity's own columns, so a
+// new NOT NULL column breaks the factory at compile time instead of at the first insert — and the
+// values are seeded, so two runs of the same suite produce byte-identical rows.
+
+import { seededRandom, seededUuid } from './determinism';
+
+export interface EntityLike {
+  readonly kind: 'entity';
+  readonly table: string;
+  readonly columns: Readonly<Record<string, unknown>>;
+}
+
+export interface Factory<TRow> {
+  readonly table: string;
+  build(over?: Partial<TRow>): TRow;
+  buildMany(count: number, over?: Partial<TRow>): readonly TRow[];
+  /** Restart the sequence so a second describe block sees the same ids as the first. */
+  reset(): void;
+}
+
+export interface FactoryOptions<TRow> {
+  readonly seed?: number;
+  /** Values for every column the entity requires; called once per built row. */
+  defaults(index: number, ids: { uuid(): string; number(): number }): TRow;
+}
+
+export function defineFactory<TRow extends object>(
+  entity: EntityLike,
+  options: FactoryOptions<TRow>,
+): Factory<TRow> {
+  const seed = options.seed ?? 1;
+  let uuid = seededUuid(seed);
+  let random = seededRandom(seed);
+  let index = 0;
+  const ids = {
+    uuid: () => uuid(),
+    number: () => Math.floor(random() * 1_000_000),
+  };
+  return {
+    table: entity.table,
+    build: (over = {}) => {
+      index += 1;
+      return { ...options.defaults(index, ids), ...over };
+    },
+    buildMany: (count, over = {}) =>
+      Array.from({ length: count }, () => {
+        index += 1;
+        return { ...options.defaults(index, ids), ...over };
+      }),
+    reset: () => {
+      uuid = seededUuid(seed);
+      random = seededRandom(seed);
+      index = 0;
+    },
+  };
+}
+
+export type EntityRegistry = Readonly<Record<string, EntityLike>>;
+
+export type FactoryRegistry<TRegistry extends EntityRegistry> = {
+  readonly [K in keyof TRegistry]: Factory<Record<string, unknown>>;
+};
+
+/**
+ * Build one factory per registered entity, with column-name-driven defaults. Enough for the rows a
+ * test does not care about; pass `defineFactory` explicitly for the rows it does.
+ */
+export function factoriesFor<TRegistry extends EntityRegistry>(
+  registry: TRegistry,
+  seed = 1,
+): FactoryRegistry<TRegistry> {
+  const out: Record<string, Factory<Record<string, unknown>>> = {};
+  for (const [name, entity] of Object.entries(registry)) {
+    out[name] = defineFactory<Record<string, unknown>>(entity, {
+      seed,
+      defaults: (index, ids) => {
+        const row: Record<string, unknown> = {};
+        for (const column of Object.keys(entity.columns)) {
+          row[column] = defaultFor(column, index, ids);
+        }
+        return row;
+      },
+    });
+  }
+  return out as FactoryRegistry<TRegistry>;
+}
+
+function defaultFor(
+  column: string,
+  index: number,
+  ids: { uuid(): string; number(): number },
+): unknown {
+  if (column === 'id' || column.endsWith('Id')) return ids.uuid();
+  if (column.endsWith('At')) return new Date(0);
+  if (column.endsWith('Minor')) return ids.number();
+  if (column.endsWith('Currency')) return 'USD';
+  if (column.startsWith('is') || column.startsWith('has')) return false;
+  return `${column}-${index}`;
+}

package/src/fixture-clock.ts

@@ -0,0 +1,28 @@
+// The `clock` fixture: the only legal way for time to pass inside a test.
+//
+// `clock.advance('3d')` is synchronous — a job test asserts on what is due on the very next
+// line — so the duration parser is resolved while the fixture is built, not when it is used.
+
+import { advanceClock, frozenNow, setFrozenClock } from './determinism';
+
+/** `'3d'` | `'30s'` | `1500`. Same vocabulary as a job's `timeout` and a step's `sleep`. */
+export type TestDuration = string | number;
+
+export interface TestClock {
+  /** The frozen instant. Never the wall clock. */
+  now(): Date;
+  advance(duration: TestDuration): Date;
+  set(instant: string | number): Date;
+}
+
+export async function createTestClock(): Promise<TestClock> {
+  const { toMs } = await import('@ultimat3/time');
+  return {
+    now: frozenNow,
+    advance: (duration) => advanceClock(toMs(duration)),
+    set: (instant) => {
+      setFrozenClock(instant);
+      return frozenNow();
+    },
+  };
+}