@ultimat3/testing 1.0.0

package/src/fixture-drivers.ts

@@ -0,0 +1,97 @@
+// The fixtures the framework DECLARES but cannot build in this process: a browser for `page`,
+// `budget`, `signIn` and `deploy`; a replicator feeding a live-query registry for `subscribe`.
+// Each is a type a driver implements, plus a factory that says what is missing until one does.
+
+import { fixtureUnavailable } from './errors';
+import type { FixtureFactory, Fixtures } from './fixtures';
+
+/** Per-route byte budgets, measured off the built output rather than declared. */
+export interface TestBudget {
+  jsBytes(route: string): Promise<number>;
+}
+
+/** Put the browser session in this member's shoes. A row, because the app owns what a member is. */
+export type SignIn = (member: Readonly<Record<string, unknown>>) => Promise<void>;
+
+/** Version skew: same app, new immutable build id, while the page stays open. */
+export interface TestDeploy {
+  newBuild(): Promise<void>;
+}
+
+/**
+ * What `query.live(input, { actor })` resolves to, named structurally so `@ultimat3/testing` does
+ * not take a dependency on `@ultimat3/query` for one type. The real `LiveQuery` satisfies it.
+ */
+export interface LiveTarget {
+  readonly name: string;
+  readonly queryHash: string;
+}
+
+export interface LiveFeedPatch<R extends object> {
+  readonly op: 'insert' | 'update' | 'delete';
+  readonly row: R;
+}
+
+/** One subscriber's view: what it holds, what it was sent, and how it got there. */
+export interface LiveFeed<R extends object> {
+  rows(): readonly R[];
+  row(id: string): R | undefined;
+  /** The optimistic twin a mutator applied locally, before the server confirmed it. */
+  local(id: string): R | undefined;
+  patches(): readonly LiveFeedPatch<R>[];
+  /** Resolves when every patch in flight has been applied — never a sleep. */
+  settled(): Promise<void>;
+  lsn(): string;
+  /** Set when a reconnect resumed from a cursor; undefined when it resnapshotted. */
+  resubscribedFrom(): string | undefined;
+  /** How many snapshots this subscriber received. A resume that refetched shows up here. */
+  snapshots(): number;
+}
+
+export type Subscribe = <R extends object>(
+  target: LiveTarget | Promise<LiveTarget>,
+) => Promise<LiveFeed<R>>;
+
+export const DRIVER_FIXTURE_NAMES = ['budget', 'deploy', 'page', 'signIn', 'subscribe'] as const;
+
+export type DriverFixtureName = (typeof DRIVER_FIXTURE_NAMES)[number];
+
+/** What each one is waiting on. `Record` over the name union, so the two lists cannot drift. */
+export const DRIVER_FIXTURE_NEEDS: Readonly<Record<DriverFixtureName, string>> = {
+  budget: 'the byte counts a browser run measures off the built output',
+  deploy: 'a second build to switch the running app to',
+  page: 'a browser driving the built app',
+  signIn: 'a browser session against the app’s own sign-in route',
+  subscribe: 'an in-process replicator feeding the live-query registry',
+};
+
+/**
+ * Declared rather than left out, because the name is the contract. An app that registered its own
+ * `page` would be deciding for itself what a page is, and two apps would then disagree — the same
+ * reason `clock` is not an app fixture. And an unregistered name fails as X_TEST_FIXTURE_UNKNOWN,
+ * whose fix ("register it") is the wrong instruction: what is missing is a driver, not a
+ * registration. So the name resolves, and asking for it without a driver says so.
+ *
+ * Throws when built, not when used. Building is where the test is still on its own first line, so
+ * the failure names the fixture instead of surfacing three awaits later as a missing method.
+ */
+export const unavailableFixture =
+  <K extends DriverFixtureName>(name: K): FixtureFactory<Fixtures[K]> =>
+  () => {
+    throw fixtureUnavailable(name, DRIVER_FIXTURE_NEEDS[name]);
+  };
+
+/** Each declaration carries the type its driver must satisfy — `defineFixtures` holds it to that. */
+export type DriverFixtures = { readonly [K in DriverFixtureName]: FixtureFactory<Fixtures[K]> };
+
+/**
+ * The declared bag, as `defineFixtures` takes it. A driver overrides these the ordinary way —
+ * `defineFixtures` merges, last registration wins.
+ */
+export const driverFixtures = (): DriverFixtures => ({
+  budget: unavailableFixture('budget'),
+  deploy: unavailableFixture('deploy'),
+  page: unavailableFixture('page'),
+  signIn: unavailableFixture('signIn'),
+  subscribe: unavailableFixture('subscribe'),
+});

package/src/fixture-jobs.ts

@@ -0,0 +1,169 @@
+// The `runJobs` fixture: a whole worker, in-process, driven by the frozen clock.
+//
+// A job test asserts the guarantees rather than the return value — a step replayed instead of
+// re-run, a duplicate enqueue deduped, a `step.sleep('3d')` that parks the run instead of
+// holding a connection — so the trace this returns is keyed by step name and counts executions.
+// Nothing here polls or sleeps: a job becomes due only because `clock.advance()` said so.
+
+import { assert, createContext } from '@ultimat3/core';
+import type {
+  AnyJobHandle,
+  EnqueueResult,
+  JobDriver,
+  JobExecution,
+  JobHandle,
+  JobRecord,
+  StepStatus,
+} from '@ultimat3/jobs';
+import { frozenNow } from './determinism';
+
+export interface StepTally {
+  /** Times the step body actually ran. A replay from storage does not count. */
+  readonly executions: number;
+  readonly attempts: number;
+  readonly status: StepStatus;
+}
+
+/**
+ * Cumulative for the life of the fixture, which is one test. A retry driven by
+ * `clock.advance()` is a second drain, and "provision ran once, nudge ran twice" is a claim
+ * about the whole run — a per-drain trace could not express it.
+ */
+export interface JobRunTrace {
+  readonly executions: readonly JobExecution[];
+  /** `trace.steps['welcome-email'].executions` — the assertion a job test is written around. */
+  readonly steps: Readonly<Record<string, StepTally>>;
+}
+
+/** `AsyncDisposable`: the fixture installs the ambient job driver and restores it after the test. */
+export interface RunJobs extends AsyncDisposable {
+  /** Enqueue and drain in one call — the common case. */
+  <I>(handle: JobHandle<I>, input: I): Promise<JobRunTrace>;
+  enqueue<I>(handle: JobHandle<I>, input: I): Promise<EnqueueResult>;
+  /** Claim and execute everything due at the current instant, until nothing is. */
+  drain(): Promise<JobRunTrace>;
+  /** Live jobs — ready, delayed, running or suspended — optionally for one job only. */
+  depth(handle?: AnyJobHandle): Promise<number>;
+  /** Live jobs claimable right now. `clock.advance()` is what turns delayed into due. */
+  due(): Promise<number>;
+  inFlight(): Promise<number>;
+}
+
+const WORKER_ID = 'test-worker';
+const VISIBILITY_TIMEOUT_MS = 30_000;
+const CLAIM_LIMIT = 64;
+/** A drain that has not settled in this many rounds is a runaway, not a slow queue. */
+const MAX_ROUNDS = 100;
+const LIVE_STATES: ReadonlySet<string> = new Set(['ready', 'delayed', 'running', 'suspended']);
+
+const tallyOf = (executions: readonly JobExecution[]): Record<string, StepTally> => {
+  const steps: Record<string, StepTally> = {};
+  for (const execution of executions) {
+    const replayed = new Set(execution.replayed);
+    for (const step of execution.steps) {
+      const previous = steps[step.name];
+      const ran = replayed.has(step.name) ? 0 : 1;
+      steps[step.name] = {
+        executions: (previous?.executions ?? 0) + ran,
+        attempts: step.attempts,
+        status: step.status,
+      };
+    }
+  }
+  return steps;
+};
+
+export async function createRunJobs(): Promise<RunJobs> {
+  const jobs = await import('@ultimat3/jobs');
+  const driver: JobDriver = jobs.createMemoryDriver();
+  // Captured before the overwrite: the ambient driver is process-global, so without this the
+  // next file to call `send()` enqueues into this test's dead queue instead of sending inline.
+  const previous = jobs.jobDriver();
+  jobs.setJobDriver(driver);
+  const ctx = createContext({ role: 'worker' });
+
+  const introspect = (): NonNullable<JobDriver['introspect']> => {
+    const found = driver.introspect;
+    assert(
+      found !== undefined,
+      'the in-memory job driver lost its introspection surface',
+      'runJobs reads queue state through driver.introspect — do not replace the driver inside a test',
+    );
+    return found;
+  };
+
+  const live = async (name?: string): Promise<readonly JobRecord[]> => {
+    const rows = await introspect().list({ limit: 1000, ...(name === undefined ? {} : { name }) });
+    return rows.filter((record) => LIVE_STATES.has(record.state));
+  };
+
+  const queues = (): readonly string[] => [
+    ...new Set([jobs.DEFAULT_QUEUE, ...jobs.registeredJobs().map((handle) => handle.queue)]),
+  ];
+
+  const round = async (): Promise<readonly JobExecution[]> => {
+    const claimed = await driver.claim({
+      queues: queues(),
+      limit: CLAIM_LIMIT,
+      visibilityTimeoutMs: VISIBILITY_TIMEOUT_MS,
+      workerId: WORKER_ID,
+    });
+    const executions: JobExecution[] = [];
+    for (const job of claimed) {
+      const handle = jobs.getJob(job.name);
+      assert(
+        handle !== undefined,
+        `queue holds job "${job.name}" but nothing registered it`,
+        `import the module that declares job("${job.name}") from the test file — the registry is populated by the import, not by the queue`,
+      );
+      executions.push(await jobs.executeJob({ driver, claimed: job, handle, ctx }));
+    }
+    return executions;
+  };
+
+  /** Every execution this fixture has driven, because the trace is cumulative. */
+  const history: JobExecution[] = [];
+
+  const drain = async (): Promise<JobRunTrace> => {
+    for (let rounds = 0; rounds < MAX_ROUNDS; rounds += 1) {
+      const batch = await round();
+      if (batch.length === 0) return { executions: [...history], steps: tallyOf(history) };
+      history.push(...batch);
+    }
+    assert(
+      false,
+      `runJobs.drain() ran ${MAX_ROUNDS} rounds without the queue settling`,
+      'give the failing job a retry delay, or assert with runJobs.due() instead of draining a job that re-enqueues itself',
+    );
+  };
+
+  const enqueue = async <I>(handle: JobHandle<I>, input: I): Promise<EnqueueResult> =>
+    driver.enqueue({
+      name: handle.name,
+      queue: handle.queue,
+      input,
+      idempotencyKey: handle.idempotencyKeyFor(input),
+      maxAttempts: handle.retry.attempts,
+    });
+
+  const enqueueThenDrain = async <I>(handle: JobHandle<I>, input: I): Promise<JobRunTrace> => {
+    await enqueue(handle, input);
+    return drain();
+  };
+
+  return Object.assign(enqueueThenDrain, {
+    enqueue,
+    drain,
+    depth: async (handle?: AnyJobHandle) => (await live(handle?.name)).length,
+    due: async () =>
+      (await live()).filter(
+        (record) => record.state !== 'running' && record.runAt <= frozenNow().getTime(),
+      ).length,
+    inFlight: async () => (await live()).filter((record) => record.state === 'running').length,
+    [Symbol.asyncDispose]: async (): Promise<void> => {
+      await driver.close?.();
+      if (previous === undefined) jobs.resetJobDriver();
+      else jobs.setJobDriver(previous);
+    },
+  });
+}

package/src/fixture-mail.ts

@@ -0,0 +1,61 @@
+// The `mail` fixture: an in-memory outbox, plus the one failure a mail test actually needs.
+//
+// `mail.failOnce(nudgeEmail)` is how a job test proves that only the failed step retried. It is
+// a transport failure rather than a thrown stub because a stub would bypass rendering, and a
+// mail that fails to render is the bug this catches most often.
+
+import type { MailDriver, MailMessage, SendResult, SentMail } from '@ultimat3/mail';
+
+/** A `defineMail()` handle, or its id. Both read naturally at a call site. */
+export type MailRef = string | { readonly id: string };
+
+/** `Disposable`: the fixture installs the ambient mail driver and restores it after the test. */
+export interface TestMail extends Disposable {
+  /** Newest first, so an assertion does not index backwards. */
+  outbox(): readonly SentMail[];
+  lastTo(address: string): SentMail | undefined;
+  /** The next send of this mail fails, once. Every later send succeeds. */
+  failOnce(mail: MailRef): void;
+  clear(): void;
+}
+
+const idOf = (mail: MailRef): string => (typeof mail === 'string' ? mail : mail.id);
+
+export async function createTestMail(): Promise<TestMail> {
+  const { createMemoryDriver, driverUnavailable, resetMailDriver, setMailDriver, tryMailDriver } =
+    await import('@ultimat3/mail');
+  const memory = createMemoryDriver();
+  const failuresLeft = new Map<string, number>();
+  // The ambient driver is process-global; the fixture borrows it for one test and hands it back.
+  const previous = tryMailDriver();
+
+  const driver: MailDriver = {
+    name: 'test',
+    send(message: MailMessage): Promise<SendResult> {
+      const left = failuresLeft.get(message.mailId) ?? 0;
+      if (left === 0) return memory.send(message);
+      failuresLeft.set(message.mailId, left - 1);
+      return Promise.reject(
+        driverUnavailable(`mail.failOnce() failed "${message.mailId}" on purpose`),
+      );
+    },
+  };
+  setMailDriver(driver);
+
+  return {
+    outbox: () => memory.outbox(),
+    lastTo: (address) => memory.lastTo(address),
+    failOnce: (mail) => {
+      const id = idOf(mail);
+      failuresLeft.set(id, (failuresLeft.get(id) ?? 0) + 1);
+    },
+    clear: () => {
+      memory.clear();
+      failuresLeft.clear();
+    },
+    [Symbol.dispose]: (): void => {
+      if (previous === undefined) resetMailDriver();
+      else setMailDriver(previous);
+    },
+  };
+}

package/src/fixture-network.ts

@@ -0,0 +1,61 @@
+// The `network` fixture: pull the cable, put back exactly what was there. What an offline test
+// needs is not a mock that answers differently — it is a request that fails the way a real one
+// fails, so the app's own offline path runs instead of a branch written for the test.
+
+import {
+  isNetworkSealed,
+  type NetworkState,
+  networkState,
+  sealNetwork,
+  setNetworkState,
+  unsealNetwork,
+} from './sealed-network';
+
+/** `Disposable`: the gate is process-global, so the fixture puts back the state it found. */
+export interface TestNetwork extends Disposable {
+  /** Every request fails as it would with no route to the host. */
+  offline(): void;
+  /**
+   * Offline, and the connection was cut rather than closed — a subscriber must reconnect.
+   * Next to `offline()` because the two are different bugs: a clean offline is what a service
+   * worker answers, and a fixture with only one of them cannot tell a resume from a resubscribe.
+   */
+  drop(): void;
+  online(): void;
+  state(): NetworkState;
+}
+
+/**
+ * Synchronous, unlike `mail` and `runJobs`: the gate it drives lives in this package, so there is
+ * no subsystem to import on demand. The test bodies rely on it — `network.offline()` is followed
+ * on the next line by the mutation that has to observe it.
+ */
+export function createTestNetwork(): TestNetwork {
+  // A process that unsealed on purpose (ULTIMATE_TEST_ALLOW_NET=1) still gets a working
+  // `offline()`, and gets its unsealed fetch back on disposal rather than keeping ours.
+  const sealedBefore = isNetworkSealed();
+  // Both halves of what was here, because disposal restores rather than assumes. An outer fixture
+  // already offline must not come back online because an inner one finished.
+  const stateBefore = networkState();
+  let sealedByUs = false;
+
+  const goto = (next: NetworkState): void => {
+    if (next !== 'online' && !isNetworkSealed()) {
+      sealNetwork();
+      sealedByUs = true;
+    }
+    setNetworkState(next);
+  };
+
+  return {
+    offline: () => goto('offline'),
+    drop: () => goto('dropped'),
+    online: () => goto('online'),
+    state: networkState,
+    [Symbol.dispose]: (): void => {
+      setNetworkState(stateBefore);
+      if (sealedByUs && !sealedBefore) unsealNetwork();
+      sealedByUs = false;
+    },
+  };
+}

package/src/fixtures.ts

@@ -0,0 +1,189 @@
+// Fixture injection: `test('…', async ({ seed, actorFor }) => …)`.
+//
+// Bun's `test` passes a `done` callback as the first argument, so destructuring a fixture bag
+// from it yields `undefined` for every key — silently, because the failure only surfaces later
+// as "cannot read property of undefined", naming nothing useful. This wraps `bun:test` so the
+// first argument is the fixture bag instead.
+//
+// Fixtures are registered by the app, not hardcoded here: `seed` and `billing` mean nothing to
+// the framework. `defineFixtures` merges, so a package can add one without knowing the others.
+
+import { test as bunTest } from 'bun:test';
+import { fixtureUnknown } from './errors';
+import type { TestClock } from './fixture-clock';
+import type { SignIn, Subscribe, TestBudget, TestDeploy } from './fixture-drivers';
+import type { RunJobs } from './fixture-jobs';
+import type { TestMail } from './fixture-mail';
+import type { TestNetwork } from './fixture-network';
+import type { PageLike } from './test-types';
+
+/** Built once per test, on first use. */
+export type FixtureFactory<T = unknown> = () => T | Promise<T>;
+
+/** The registry's own shape, where the built type is erased — what `fixtureSnapshot()` hands back. */
+export type FixtureMap = Readonly<Record<string, FixtureFactory>>;
+
+/**
+ * What a test body receives. Everything the framework owns is declared here and registered by the
+ * preload; apps widen it by augmenting `Fixtures`:
+ *
+ * ```ts
+ * declare module '@ultimat3/testing' {
+ *   interface Fixtures {
+ *     seed: (name: string) => SeedHandle;
+ *   }
+ * }
+ * ```
+ *
+ * The last five are declared but driver-backed: destructuring one in a process with no driver
+ * fails as `X_TEST_FIXTURE_UNAVAILABLE`, naming what is missing. Typed here anyway, because the
+ * type is the contract a driver implements — see `fixture-drivers.ts`.
+ */
+export interface Fixtures {
+  readonly clock: TestClock;
+  readonly mail: TestMail;
+  readonly network: TestNetwork;
+  readonly runJobs: RunJobs;
+  readonly budget: TestBudget;
+  readonly deploy: TestDeploy;
+  readonly page: PageLike;
+  readonly signIn: SignIn;
+  readonly subscribe: Subscribe;
+}
+
+/**
+ * A registration bag, with every name the framework declares held to the type it was declared
+ * with. A driver that registers a half-built `page` is a compile error at the registration, rather
+ * than a missing method three awaits into some later test — the same reason the name is declared
+ * at all. A key `Fixtures` does not name is the app's, and takes any factory: the framework has
+ * nothing to check it against until the app augments `Fixtures`.
+ *
+ * Written over the argument's own keys rather than as an intersection, so a value typed only as
+ * `FixtureMap` — a snapshot on its way back into the registry — still satisfies it.
+ */
+export type FixtureRegistration<M> = {
+  readonly [K in keyof M]: K extends keyof Fixtures ? FixtureFactory<Fixtures[K]> : FixtureFactory;
+};
+
+const registry = new Map<string, FixtureFactory>();
+
+export function defineFixtures<M extends FixtureRegistration<M>>(map: M): void {
+  for (const [name, factory] of Object.entries(map as FixtureMap)) registry.set(name, factory);
+}
+
+export function clearFixtures(): void {
+  registry.clear();
+}
+
+export function registeredFixtures(): readonly string[] {
+  return [...registry.keys()].sort();
+}
+
+/**
+ * A copy of the registry. The registry is process-global and bun shares one process across
+ * files, so a test that needs an empty one snapshots first and hands it back afterwards —
+ * otherwise every later file silently loses the fixtures the preload registered.
+ */
+export function fixtureSnapshot(): FixtureMap {
+  return Object.fromEntries(registry);
+}
+
+/**
+ * The names a body destructures, read from its source.
+ *
+ * Reading source is unusual enough to justify: the alternative is building every registered
+ * fixture for every test, so one test that touches `page` would start a browser for the whole
+ * suite. Playwright resolves fixtures the same way and for the same reason. Only the first
+ * parameter is inspected, and only its top-level keys.
+ */
+export function requestedFixtures(body: (...args: never[]) => unknown): readonly string[] {
+  const source = body.toString();
+  const open = source.indexOf('{');
+  if (open === -1) return [];
+  const close = source.indexOf('}', open);
+  if (close === -1) return [];
+  // Bail if the brace opens a body rather than a destructuring pattern — `async () => {`.
+  const beforeBrace = source.slice(0, open);
+  if (/\)\s*(?::[^=]*)?=>\s*$/.test(beforeBrace) || /\)\s*$/.test(beforeBrace)) return [];
+  return source
+    .slice(open + 1, close)
+    .split(',')
+    .map((part) => (part.split(':')[0] ?? '').trim())
+    .filter((name) => /^[A-Za-z_$][\w$]*$/.test(name));
+}
+
+export type FixtureBody = (fixtures: Fixtures) => void | Promise<void>;
+
+/**
+ * A fixture that installs process-global state — the ambient job driver, the ambient mail
+ * driver — implements one of the standard disposal symbols to put it back. Bun shares one
+ * process across every test file, so a fixture that skips this does not leak within its own
+ * test: it leaks into every file that runs after it, and the failure surfaces somewhere else.
+ */
+type MaybeDisposable = {
+  readonly [Symbol.asyncDispose]?: () => PromiseLike<void> | void;
+  readonly [Symbol.dispose]?: () => void;
+};
+
+const disposerOf = (value: unknown): (() => PromiseLike<void> | void) | undefined => {
+  if (value === null || (typeof value !== 'object' && typeof value !== 'function'))
+    return undefined;
+  const target = value as MaybeDisposable;
+  const asyncDispose = target[Symbol.asyncDispose];
+  if (typeof asyncDispose === 'function') return () => asyncDispose.call(target);
+  const dispose = target[Symbol.dispose];
+  return typeof dispose === 'function' ? () => dispose.call(target) : undefined;
+};
+
+/**
+ * Build what the body asked for, run it, dispose in reverse. Split out of `fixtureTest` because
+ * that one hands its callback to bun and returns nothing — teardown is the part most worth
+ * testing, and it cannot be observed through a registration. Not in the package's public API:
+ * `fixtureTest` stays the one way to write a test with fixtures.
+ */
+export async function runWithFixtures(body: FixtureBody): Promise<void> {
+  const wanted = requestedFixtures(body as (...args: never[]) => unknown);
+  // Partial by construction — only what the body destructured is built. Handed over as the
+  // full `Fixtures` because the keys came from that same body: a key it did not name is a key
+  // it cannot read, so the missing ones are unobservable.
+  const bag: Partial<Fixtures> & Record<string, unknown> = {};
+  const built: unknown[] = [];
+  // Boxed rather than a bare `unknown`, so a body that throws a falsy value still reports.
+  let failure: { readonly error: unknown } | undefined;
+  try {
+    for (const key of wanted) {
+      const factory = registry.get(key);
+      // Naming the registered set turns "undefined is not an object" into a fixable message.
+      if (factory === undefined) throw fixtureUnknown(key, registeredFixtures());
+      const value = await factory();
+      built.push(value);
+      bag[key] = value;
+    }
+    await body(bag as Fixtures);
+  } catch (error) {
+    failure = { error };
+  }
+
+  // Every disposer runs even when an earlier one throws: a fixture that cannot clean up must
+  // not strand the ones built before it. The body's own failure wins, because a teardown error
+  // that replaced it would hide the assertion that actually broke.
+  for (const value of built.reverse()) {
+    try {
+      await disposerOf(value)?.();
+    } catch (error) {
+      failure ??= { error };
+    }
+  }
+  if (failure !== undefined) throw failure.error;
+}
+
+/**
+ * `test` with fixtures. Only what the body destructures is built, and each is awaited before
+ * the body runs — so a body reads `seed('dev')` directly instead of awaiting every fixture.
+ *
+ * Teardown runs in reverse build order whether the body passed or threw: a failing assertion
+ * must not be the reason the next file inherits a queue.
+ */
+export function fixtureTest(name: string, body: FixtureBody): void {
+  bunTest(name, () => runWithFixtures(body));
+}

package/src/framework-fixtures.ts

@@ -0,0 +1,42 @@
+// Registers the fixtures the FRAMEWORK owns, so an app registers only what it owns (`seed`,
+// `actorFor`, …). Called by the preload, which is why an app never writes
+// `defineFixtures({ clock })` and why two apps cannot disagree about what `clock` means.
+
+import { createTestClock } from './fixture-clock';
+import { DRIVER_FIXTURE_NAMES, driverFixtures } from './fixture-drivers';
+import { createRunJobs } from './fixture-jobs';
+import { createTestMail } from './fixture-mail';
+import { createTestNetwork } from './fixture-network';
+import { defineFixtures } from './fixtures';
+
+/**
+ * Built in-process. Always available, in every test type — the first of the bag's two kinds of
+ * member. The other is `DRIVER_FIXTURE_NAMES`: declared here, built by a driver the process
+ * installs. See `fixture-drivers.ts` for why a declared-and-unavailable fixture beats an
+ * unregistered name.
+ */
+export const FRAMEWORK_FIXTURE_NAMES = ['clock', 'mail', 'network', 'runJobs'] as const;
+
+export { DRIVER_FIXTURE_NAMES };
+
+/** Every name the framework puts in the bag, in the order `registeredFixtures()` reports them. */
+export const ALL_FIXTURE_NAMES: readonly string[] = [
+  ...FRAMEWORK_FIXTURE_NAMES,
+  ...DRIVER_FIXTURE_NAMES,
+].sort();
+
+/**
+ * Each factory imports its subsystem on demand, for the reason the whole registry is lazy: a test
+ * that never touches jobs must not pay for the queue, and a `packages/core` test must not boot
+ * mail. `defineFixtures` merges, so registering twice is idempotent — and so a driver registered
+ * afterwards replaces the declaration it was waiting on.
+ */
+export function registerFrameworkFixtures(): void {
+  defineFixtures({
+    ...driverFixtures(),
+    clock: createTestClock,
+    mail: createTestMail,
+    network: createTestNetwork,
+    runJobs: createRunJobs,
+  });
+}