@ultimat3/testing 1.0.0 → 1.2.0

package/README.md

@@ -11,7 +11,10 @@ frozen clock. Never let a test reach the network unmocked — it fails by design
 | `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 |
+| `factories.ts` | `defineFactory` — seeded rows, traits, associations, `build` vs `create` |
+| `factory-registry.ts` | `factoriesFor(registry)` — one factory per entity, defaults read off column names |
+| `factory-persist.ts` | `usePersister` — the one seam `create()` writes through |
+| `shared-examples.ts` | `sharedExamples` / `behavesLike` — one rule, many subjects |
 | `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 |
@@ -100,18 +103,76 @@ Each helper prefixes the test name with its type (`job · onboards an org`), whi
 `bun test --test-name-pattern "job · "` selects — the six lines of `x verify` come from the tests
 themselves, not from a directory convention.
 
+## Factories
+
+```ts
+const orgs = defineFactory(orgEntity, {
+  defaults: (n, ids): Org => ({ id: ids.uuid(), name: `org-${n}` }),
+});
+
+const posts = defineFactory(postEntity, {
+  defaults: (n, ids): Post => ({ id: ids.uuid(), title: `post-${n}`, orgId: '', published: false }),
+  traits: { published: { published: true }, popular: (n) => ({ views: n * 100 }) },
+  associations: { orgId: associate(orgs, (org) => org.id) },
+});
+
+posts.with('published').build();          // in memory, org built alongside it, no database
+await posts.with('published').create();   // org written first, then the post
+```
+
+| | |
+|---|---|
+| **trait** | a named partial. `with('a', 'b')` composes left to right; an explicit override still wins |
+| **association** | a column whose value comes from another factory, built with the **same strategy** — `build` leaves the parent in memory, `create` writes it |
+| **overrides suppress associations** | a column the caller (or a trait) supplied never creates a parent row nobody asked for |
+| **`build` vs `create`** | `build` never touches a database; `create` writes through `usePersister` and fails as `X_TEST_FACTORY_NOT_PERSISTED` when nothing installed one |
+| **seeded per table** | the default seed is derived from the table name, so a post and an org never draw the same uuid. Pass `seed` only to replay an older recording |
+| **`with()` validates** | an undeclared trait fails at the line that named it, listing the declared ones (`X_TEST_FACTORY_TRAIT_UNKNOWN`) |
+
+`factoriesFor(registry)` builds one factory per registered entity, with values inferred from column
+names (`…Id` → uuid, `…At` → date, `…Minor` → integer, `is…`/`has…` → false). Enough for the rows a
+test does not care about; `defineFactory` is for the rows it does.
+
+## Shared examples
+
+```ts
+const anAuthenticatedAction = sharedExamples<Action>('an authenticated action', (subject) => {
+  test('denies an anonymous actor', async () => {
+    await expect(subject().call(input, { actor: anonymous })).toDenyPolicy();
+  });
+});
+
+describe('publishPost', () => behavesLike(anAuthenticatedAction, () => publishPost));
+```
+
+The subject is a function, not a value, for the reason `describeApp`'s accessor is: the block is
+declared at module scope and the subject often does not exist until `beforeAll` has run. The
+failure line reads `publishPost > behaves like an authenticated action > denies an anonymous actor`
+— which subject, and which shared rule. `behavesLike` calls `describe`, so it goes at declaration
+scope, never inside a test body.
+
 ## 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.
 
+**Parallelism is opt-in, not the default.** `As of 2026-08`:
+
+| Command | Processes | Worker ids | Databases |
+|---|---|---|---|
+| `bun test` (what a scaffolded app's `test` script runs, and what every `x verify` test step runs) | 1 | `0` | one |
+| `bun test --parallel[=N]` | N (default: CPU count) | `1..N`, from Bun's own `BUN_TEST_WORKER_ID` | N |
+| `x test --workers N` | N | `0..N-1`, from `ULTIMATE_TEST_WORKER` | N |
+
+`ULTIMATE_TEST_WORKER` is read first so a runner-assigned shard always beats the index Bun assigns
+its own `--parallel` worker — measured on Bun 1.3.14, `--parallel` populates `BUN_TEST_WORKER_ID`
+and `JEST_WORKER_ID` itself, so that precedence is load-bearing rather than defensive.
+
 ## Sealed network
 
 ```
@@ -128,3 +189,4 @@ integration — never for a socket test.
 ## Errors
 
 `X_TEST_NETWORK_SEALED` `X_TEST_DB_UNAVAILABLE` `X_TEST_NONDETERMINISTIC` `X_TEST_FIXTURE_UNKNOWN`
+`X_TEST_FACTORY_TRAIT_UNKNOWN` `X_TEST_FACTORY_NOT_PERSISTED`

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ultimat3/testing",
-  "version": "1.0.0",
+  "version": "1.2.0",
   "description": "Test harness: cloned template DBs per worker, frozen clock, sealed network, 6 test types",
   "license": "MIT",
   "type": "module",
@@ -31,10 +31,10 @@
     "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"
+    "@ultimat3/core": "1.2.0",
+    "@ultimat3/db": "1.2.0",
+    "@ultimat3/jobs": "1.2.0",
+    "@ultimat3/mail": "1.2.0",
+    "@ultimat3/time": "1.2.0"
   }
 }

package/src/errors.ts

@@ -13,6 +13,8 @@ export const TESTING_ERROR_CODES = [
   'X_TEST_SCHEMA_EXPECTED',
   'X_TEST_JOB_EXPECTED',
   'X_TEST_NETWORK_RACE',
+  'X_TEST_FACTORY_TRAIT_UNKNOWN',
+  'X_TEST_FACTORY_NOT_PERSISTED',
 ] as const;
 
 export type TestingErrorCode = (typeof TESTING_ERROR_CODES)[number];
@@ -28,6 +30,8 @@ export const TESTING_ERROR_TITLES: Readonly<Record<TestingErrorCode, string>> =
   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',
+  X_TEST_FACTORY_TRAIT_UNKNOWN: 'a factory was asked for a trait it does not declare',
+  X_TEST_FACTORY_NOT_PERSISTED: 'a factory create() had nowhere to write the row',
 };
 
 // Titles must be registered for `format()` to render the contract's first line. Every code above is
@@ -185,6 +189,41 @@ export class TestJobExpectedError extends UltimateError {
   }
 }
 
+/**
+ * A factory was asked for a trait it does not declare. Listing the declared ones is the whole
+ * value: a typo (`:pubished`) and a trait that was never written are the same symptom and
+ * different fixes, and only the list tells them apart without opening the factory.
+ */
+export class FactoryTraitUnknownError extends UltimateError {
+  constructor(input: { table: string; trait: string; declared: readonly string[] }) {
+    super({
+      code: 'X_TEST_FACTORY_TRAIT_UNKNOWN',
+      cause:
+        input.declared.length === 0
+          ? `factory "${input.table}" was asked for trait "${input.trait}" but declares none`
+          : `factory "${input.table}" has no trait "${input.trait}"; declared: ${input.declared.join(', ')}`,
+      fix: `declare it: defineFactory(${input.table}, { traits: { ${input.trait}: { /* columns */ } } })`,
+      docs: docsFor('X_TEST_FACTORY_TRAIT_UNKNOWN'),
+    });
+  }
+}
+
+/**
+ * `create()` with no persister installed. Distinct from "the insert failed": nothing was attempted,
+ * so the instruction is to install the seam once in the preload — or to stop asking for a row that
+ * outlives the test, which `build()` already gives without a database at all.
+ */
+export class FactoryNotPersistedError extends UltimateError {
+  constructor(input: { table: string }) {
+    super({
+      code: 'X_TEST_FACTORY_NOT_PERSISTED',
+      cause: `factory "${input.table}".create() ran with no persister in this process`,
+      fix: 'usePersister({ insert: (table, row) => repoFor(table).insert(row) }) in the test preload — or build() for an in-memory row',
+      docs: docsFor('X_TEST_FACTORY_NOT_PERSISTED'),
+    });
+  }
+}
+
 /**
  * `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

package/src/factories.ts

@@ -1,8 +1,14 @@
 // 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.
+//
+// Traits and associations are FactoryBot's two, and only its two: a trait is a named partial the
+// caller composes, an association is a column whose value comes from another factory built with
+// the SAME strategy — `build()` leaves the parent in memory, `create()` writes it.
 
 import { seededRandom, seededUuid } from './determinism';
+import { FactoryTraitUnknownError } from './errors';
+import { persistRow } from './factory-persist';
 
 export interface EntityLike {
   readonly kind: 'entity';
@@ -10,90 +16,179 @@ export interface EntityLike {
   readonly columns: Readonly<Record<string, unknown>>;
 }
 
-export interface Factory<TRow> {
+/** The seeded generators a `defaults` or trait body draws from. Never `Math.random` directly. */
+export interface FactoryIds {
+  uuid(): string;
+  number(): number;
+}
+
+/** A named partial. A function form gets the row's index and the same seeded generators. */
+export type Trait<TRow> = Partial<TRow> | ((index: number, ids: FactoryIds) => Partial<TRow>);
+
+export type TraitMap<TRow> = Readonly<Record<string, Trait<TRow>>>;
+
+/**
+ * A column filled from another factory. Opaque on purpose: `associate()` captures the parent
+ * factory and the column to lift off it, so the map below stays exactly typed per column with no
+ * variance escape hatch.
+ */
+export interface Association<TValue> {
+  build(): TValue;
+  create(): Promise<TValue>;
+  /** Cascades from the child's `reset()`: a half-reset row is not the row the first block saw. */
+  reset(): void;
+}
+
+export type AssociationMap<TRow> = { readonly [K in keyof TRow]?: Association<TRow[K]> };
+
+/**
+ * `associate(orgs, (org) => org.id)` — the parent is built with the strategy the child is built
+ * with, which is the whole reason associations are not just another default: `create()` on a post
+ * has to leave an org row behind it, and `build()` must not touch a database at all.
+ */
+export function associate<TParent extends object, TValue>(
+  parent: Factory<TParent>,
+  pick: (row: TParent) => TValue,
+): Association<TValue> {
+  return {
+    build: () => pick(parent.build()),
+    create: async () => pick(await parent.create()),
+    reset: () => parent.reset(),
+  };
+}
+
+export interface FactoryOptions<TRow, TTraits extends TraitMap<TRow> = TraitMap<TRow>> {
+  /** Omitted means "derived from the table name" — see `seedFor`. */
+  readonly seed?: number;
+  /** Values for every column the entity requires; called once per built row. */
+  defaults(index: number, ids: FactoryIds): TRow;
+  readonly traits?: TTraits;
+  readonly associations?: AssociationMap<TRow>;
+}
+
+export interface Factory<TRow, TTrait extends string = string> {
   readonly table: string;
+  /** The declared trait names, sorted — what a failure lists and what a test can assert on. */
+  readonly traits: readonly TTrait[];
   build(over?: Partial<TRow>): TRow;
   buildMany(count: number, over?: Partial<TRow>): readonly TRow[];
+  /** Build, resolve associations by creating their parents, and write through the persister. */
+  create(over?: Partial<TRow>): Promise<TRow>;
+  createMany(count: number, over?: Partial<TRow>): Promise<readonly TRow[]>;
+  /** A view with those traits applied, sharing this factory's sequence so ids never repeat. */
+  with(...traits: readonly TTrait[]): Factory<TRow, TTrait>;
   /** 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;
+/**
+ * Two factories with the same seed emit the same uuids, so a default of `1` everywhere gave a user
+ * and a post the same id — rows that only look related. FNV-1a over the table name keeps every
+ * table on its own stream while staying a pure function of the schema, so the ids are still
+ * identical run to run and machine to machine.
+ */
+export function seedFor(table: string): number {
+  let hash = 0x811c9dc5;
+  for (let i = 0; i < table.length; i += 1) {
+    hash = Math.imul(hash ^ table.charCodeAt(i), 0x01000193) >>> 0;
+  }
+  return hash === 0 ? 1 : hash;
 }
 
-export function defineFactory<TRow extends object>(
+export function defineFactory<TRow extends object, TTraits extends TraitMap<TRow> = TraitMap<TRow>>(
   entity: EntityLike,
-  options: FactoryOptions<TRow>,
-): Factory<TRow> {
-  const seed = options.seed ?? 1;
+  options: FactoryOptions<TRow, TTraits>,
+): Factory<TRow, Extract<keyof TTraits, string>> {
+  type Name = Extract<keyof TTraits, string>;
+  const seed = options.seed ?? seedFor(entity.table);
+  const traits: TraitMap<TRow> = options.traits ?? {};
+  const declared = Object.keys(traits).sort() as Name[];
+  // Erased to one shape for iteration; the public `AssociationMap` already held each entry to its
+  // own column's type, so the value at key K is an `Association<TRow[K]>` by construction.
+  const links = Object.entries(
+    (options.associations ?? {}) as Readonly<Record<string, Association<unknown>>>,
+  );
+
   let uuid = seededUuid(seed);
   let random = seededRandom(seed);
   let index = 0;
-  const ids = {
+  const ids: FactoryIds = {
     uuid: () => uuid(),
     number: () => Math.floor(random() * 1_000_000),
   };
-  return {
+
+  const assertTrait = (name: string): string => {
+    if (traits[name] === undefined) {
+      throw new FactoryTraitUnknownError({ table: entity.table, trait: name, declared });
+    }
+    return name;
+  };
+
+  /**
+   * Traits then the call's own overrides, resolved before any association runs: a column the
+   * caller supplied must not also create a parent row nobody asked for.
+   */
+  const overridesOf = (
+    applied: readonly string[],
+    over: Partial<TRow>,
+    i: number,
+  ): Partial<TRow> => {
+    let patch: Partial<TRow> = {};
+    for (const name of applied) {
+      const trait = traits[name];
+      patch = { ...patch, ...(typeof trait === 'function' ? trait(i, ids) : trait) };
+    }
+    return { ...patch, ...over };
+  };
+
+  const buildRow = (applied: readonly string[], over: Partial<TRow>): TRow => {
+    index += 1;
+    const base = options.defaults(index, ids);
+    const overrides = overridesOf(applied, over, index);
+    const linked: Record<string, unknown> = {};
+    for (const [column, link] of links) if (!(column in overrides)) linked[column] = link.build();
+    return { ...base, ...(linked as Partial<TRow>), ...overrides };
+  };
+
+  const createRow = async (applied: readonly string[], over: Partial<TRow>): Promise<TRow> => {
+    index += 1;
+    const base = options.defaults(index, ids);
+    const overrides = overridesOf(applied, over, index);
+    const linked: Record<string, unknown> = {};
+    // Sequential, not `Promise.all`: two parents built concurrently would interleave their draws
+    // from the shared seeded generators and the run would stop being reproducible.
+    for (const [column, link] of links) {
+      if (!(column in overrides)) linked[column] = await link.create();
+    }
+    const row = { ...base, ...(linked as Partial<TRow>), ...overrides };
+    await persistRow(entity.table, row);
+    return row;
+  };
+
+  const view = (applied: readonly string[]): Factory<TRow, Name> => ({
     table: entity.table,
-    build: (over = {}) => {
-      index += 1;
-      return { ...options.defaults(index, ids), ...over };
+    traits: declared,
+    build: (over = {}) => buildRow(applied, over),
+    buildMany: (count, over = {}) => Array.from({ length: count }, () => buildRow(applied, over)),
+    create: (over = {}) => createRow(applied, over),
+    createMany: async (count, over = {}) => {
+      const rows: TRow[] = [];
+      for (let i = 0; i < count; i += 1) rows.push(await createRow(applied, over));
+      return rows;
     },
-    buildMany: (count, over = {}) =>
-      Array.from({ length: count }, () => {
-        index += 1;
-        return { ...options.defaults(index, ids), ...over };
-      }),
+    // Checked here rather than at build time: `with()` is the line that named the trait, and a
+    // failure three calls later would point at a row instead of at the typo.
+    with: (...names) => view([...applied, ...names.map(assertTrait)]),
     reset: () => {
       uuid = seededUuid(seed);
       random = seededRandom(seed);
       index = 0;
+      // Without this a reset factory rebuilt its own columns identically and drew a fresh org id
+      // for the association — one row that is half the row the first block saw, which is worse
+      // than not resetting at all because only one column moves.
+      for (const [, link] of links) link.reset();
     },
-  };
-}
-
-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}`;
+  return view([]);
 }

package/src/factory-persist.ts

@@ -0,0 +1,41 @@
+// The one seam a factory's `create()` writes through. Structural rather than an import of
+// `@ultimat3/entity`'s `Repo`: testing must not take a package dependency for one type — the same
+// reason `LiveTarget` is declared structurally in fixture-drivers.ts.
+
+import { FactoryNotPersistedError } from './errors';
+
+/**
+ * Writes a built row and answers nothing. Returning the stored row would make `create()` and
+ * `build()` able to disagree about what the row is, and a test could then only find out which one
+ * it holds by looking — the ambiguity axiom 1 forbids. The factory owns every column; the
+ * persister owns only whether the row exists.
+ */
+export interface Persister {
+  insert<TRow extends object>(table: string, row: TRow): Promise<void>;
+}
+
+let current: Persister | undefined;
+
+/**
+ * Install the writer, once, in the test preload. Process-global for the same reason the fixture
+ * registry is: a factory is imported by the file under test, not handed to it.
+ */
+export function usePersister(persister: Persister): void {
+  current = persister;
+}
+
+/** Hand the process back. An `afterAll` in any file that installed one of its own. */
+export function clearPersister(): void {
+  current = undefined;
+}
+
+export const persisterInstalled = (): boolean => current !== undefined;
+
+/**
+ * Throws where the row would have been written, so the failure names the table it was for rather
+ * than surfacing as a missing method on `undefined` inside the factory.
+ */
+export async function persistRow<TRow extends object>(table: string, row: TRow): Promise<void> {
+  if (current === undefined) throw new FactoryNotPersistedError({ table });
+  await current.insert(table, row);
+}

package/src/factory-registry.ts

@@ -0,0 +1,50 @@
+// One factory per registered entity, with defaults inferred from column names. Enough for the rows
+// a test does not care about; `defineFactory` is what a test reaches for when it cares.
+
+import type { EntityLike, Factory, FactoryIds } from './factories';
+import { defineFactory } from './factories';
+
+export type EntityRegistry = Readonly<Record<string, EntityLike>>;
+
+export type FactoryRegistry<TRegistry extends EntityRegistry> = {
+  readonly [K in keyof TRegistry]: Factory<Record<string, unknown>>;
+};
+
+/**
+ * `seed` is deliberately optional and deliberately not shared: with one seed for the whole
+ * registry every table drew the same uuid stream, so a user and a post came out with the same id.
+ * Omitted, each factory derives its own from its table name — still reproducible, no longer equal.
+ */
+export function factoriesFor<TRegistry extends EntityRegistry>(
+  registry: TRegistry,
+  seed?: number,
+): FactoryRegistry<TRegistry> {
+  const out: Record<string, Factory<Record<string, unknown>>> = {};
+  for (const [name, entity] of Object.entries(registry)) {
+    out[name] = defineFactory(entity, {
+      ...(seed === undefined ? {} : { seed }),
+      defaults: (index, ids): Record<string, unknown> => {
+        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>;
+}
+
+/**
+ * Column names carry the type in this framework's conventions — `…At` is a timestamp, `…Minor` is
+ * the integer half of a Money, `is…`/`has…` is a flag — so the name is the only input that can
+ * produce a value the schema will accept without the test saying anything.
+ */
+export function defaultFor(column: string, index: number, ids: FactoryIds): 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/index.ts

@@ -48,8 +48,21 @@ export {
   TESTING_ERROR_TITLES,
   TestDatabaseUnavailableError,
 } from './errors';
-export type { EntityLike, EntityRegistry, Factory, FactoryOptions } from './factories';
-export { defineFactory, factoriesFor } from './factories';
+export type {
+  Association,
+  AssociationMap,
+  EntityLike,
+  Factory,
+  FactoryIds,
+  FactoryOptions,
+  Trait,
+  TraitMap,
+} from './factories';
+export { associate, defineFactory, seedFor } from './factories';
+export type { Persister } from './factory-persist';
+export { clearPersister, persisterInstalled, usePersister } from './factory-persist';
+export type { EntityRegistry, FactoryRegistry } from './factory-registry';
+export { factoriesFor } from './factory-registry';
 export type { TestClock, TestDuration } from './fixture-clock';
 export { createTestClock } from './fixture-clock';
 export type {
@@ -96,6 +109,8 @@ export {
   sealNetwork,
   unsealNetwork,
 } from './sealed-network';
+export type { SharedExamples } from './shared-examples';
+export { behavesLike, sharedExamples } from './shared-examples';
 export type { SqlRunner, TemplateDbConfig, WorkerDatabase } from './template-db';
 export {
   acquireWorkerDatabase,

package/src/shared-examples.ts

@@ -0,0 +1,41 @@
+// One behaviour, asserted against many subjects — RSpec's `shared_examples` / `it_behaves_like`.
+// The framework's own rules are the reason it exists: "every action denies an anonymous actor" is
+// a sentence about forty actions, and forty copies of it is forty places for one of them to be
+// quietly missing.
+
+import { describe } from 'bun:test';
+
+/**
+ * A named block of tests waiting for a subject. Opaque — the only thing that may run it is
+ * `behavesLike`, so the `describe` nesting below is the one way these ever appear in output.
+ */
+export interface SharedExamples<TSubject> {
+  readonly name: string;
+  readonly body: (subject: () => TSubject) => void;
+}
+
+/**
+ * The subject arrives as a function, not a value, for the reason `describeApp`'s accessor does:
+ * the block is declared at module scope and the subject often does not exist until `beforeAll`
+ * has run. Called inside each test, it is always the current one.
+ */
+export function sharedExamples<TSubject>(
+  name: string,
+  body: (subject: () => TSubject) => void,
+): SharedExamples<TSubject> {
+  return { name, body };
+}
+
+/**
+ * Wrapped in its own `describe` so the failure line reads
+ * `publishPost > behaves like an authenticated action > denies an anonymous actor` — which subject
+ * failed, and which shared rule it failed. Two uses in one file therefore never collide.
+ */
+export function behavesLike<TSubject>(
+  examples: SharedExamples<TSubject>,
+  subject: () => TSubject,
+): void {
+  describe(`behaves like ${examples.name}`, () => {
+    examples.body(subject);
+  });
+}

package/src/template-db.ts

@@ -32,14 +32,19 @@ export interface WorkerDatabase {
 export const DEFAULT_TEMPLATE = 'ultimate_test_template';
 
 /**
- * Bun exposes the test worker index in the environment; a plain `bun test` run is worker 0. The
- * pid fallback keeps two hand-run processes from colliding on the same database.
+ * Which database this process owns. A plain `bun test` run is one process and worker 0; a
+ * `bun test --parallel=N` run is N processes and workers 1..N; an `x test --workers N` run is N
+ * processes and workers 0..N-1.
+ *
+ * The pid fallback keeps two hand-run processes from colliding on the same database.
  */
 export function workerId(env: Readonly<Record<string, string | undefined>>, pid = 0): number {
   // ULTIMATE_TEST_WORKER is checked FIRST because `x test` assigns it deliberately, one index per
-  // shard. A runner-set value must beat anything the runtime invents: if Bun ever populates
-  // BUN_TEST_WORKER_ID itself, two shards could resolve to the same index and then race on the
-  // same cloned database — a data-dependent failure that would look like a flaky test.
+  // shard, and a runner-set value must beat anything the runtime invents. That precedence is no
+  // longer hypothetical: measured on Bun 1.3.14, `bun test --parallel` populates BOTH
+  // BUN_TEST_WORKER_ID and JEST_WORKER_ID (identically, 1-based). So an `x test` shard that ever
+  // ran its child with --parallel would otherwise resolve to Bun's index instead of its own, two
+  // shards would land on one cloned database, and the failure would read as a flaky test.
   for (const key of ['ULTIMATE_TEST_WORKER', 'BUN_TEST_WORKER_ID', 'JEST_WORKER_ID']) {
     const raw = env[key];
     if (raw === undefined) continue;