@starci/jest-preset 1.1.0 → 2.0.0

package/CHANGELOG.md

@@ -0,0 +1,13 @@
+# Changelog
+
+## 2.0.0 - unreleased
+
+- Breaking: `starciJestConfig()` takes no options. The repository `jest.config.js` is a managed file, exactly `module.exports = require("@starci/jest-preset").starciJestConfig()`, rendered by `hfs sync` and compared by `hfs check` (HFS_MANAGED_FILE_DRIFT), so `moduleNameMapper`, `roots`, `tsconfig`, `rootDir`, `unit` and `e2e` overrides are gone. `StarciJestOptions` is removed.
+- Added: the three path aliases (`@features/*`, `@modules/*`, `@tests/*`) are part of the preset (`MODULE_NAME_MAPPER`), matching the aliases the managed `tsconfig.json` declares.
+- Added: `coverageProvider: "v8"`, so branch coverage counts real source, not the helpers TypeScript emits.
+- Breaking: four projects, one per test kind (owner test layout 2026-09-30): `unit` (colocated `*.spec.ts`, ignores `src/tests/{world,integration,e2e,contract}/`), `integration` (`src/tests/integration/**/*.integration-spec.ts`), `e2e` (`src/tests/e2e/**/*.e2e-spec.ts`) and `contract` (`src/tests/contract/**/*.contract-spec.ts`). The last three compile against `src/tests/tsconfig.json`, run one worker and share the test world's `globalSetup`/`globalTeardown` (`src/tests/world/global-setup.ts`, `global-teardown.ts`); there is no `setupFilesAfterEnv`. `src/tests/e2e/live/`, `E2E_LIVE` and `test:e2e:live` are gone: a provider sandbox is a contract spec. `typecheck:e2e` is replaced by `typecheck:tests`.
+- Unchanged: ts-jest with `diagnostics: false` (`isolatedModules` comes from `@starci/tsconfig`), `mock<T>()` and `FakeClock`.
+- Added (unit test standard, lane UT): the shared unit double kit on the package root, `mockEntityManager({ method: [Entity, result] })` (typed against the entity, `query: [sql, rows]`, a list of pairs for several answers, every method a `jest.fn`, any unstubbed method throws an error naming it, `create(Entity, plain)` works unstubbed), `fakeTransaction(em)` (`outcomes`, `commits`, `rollbacks`, `committedWrites`, `rolledBackWrites`), `fakeCache(clock)` (JSON round trip, TTL from the clock, `has`, `ttlOf`, `keys`, typed-key and cache-manager shapes), `fakeLock(clock)` (`acquire`, `release`, `isHeld`, `holderOf`, `fenceOf`), `recordingOutbox()` (`enqueue`, `messages`, `writes`, `entries` with `inTransaction`), `builder<T>(defaults)`, `fakeIds()` and the Outcome matchers `toBeRefused` and `toSucceedWith` (installed in the unit project through `setupFilesAfterEnv`). Sub-path exports `./cache`, `./lock`, `./outbox`, `./builders`, `./entity-manager`, `./ids` and `./matchers` were added next to `./mock` and `./clock`.
+- Breaking: coverage is collected from `src/**/*.service.ts` only (minus `src/tests/**`, `dist`, `coverage`), with a per-file threshold of 100 on lines, branches, functions and statements (`coverageThreshold` glob key `./src/**/*.service.ts`); the managed `test` script runs the unit project with `--coverage`. The previous denominator (`src/**/*.ts` and `apps/**/*.ts`) is gone. The unit project overlays `isolatedModules: false` and `importHelpers: true` on the repository tsconfig (exported as `UNIT_COMPILER_OPTIONS`) so a decorated service can reach 100 (no `design:paramtypes` guard branches, no inlined decorator helpers); repositories list `tslib` in devDependencies.
+- Breaking: `sonarCoverageExclusions()` is removed and coverage reporters are `text-summary` and `text` only (no `lcov`): Sonar does not depend on coverage and Codecov is not fed by the preset. `sonarExclusions()` remains and renders `sonar.exclusions`.
+- Breaking (convention): a unit spec exists only as `<name>.service.spec.ts` beside a `*.service.ts` and builds the service with `Test.createTestingModule({ providers })`; `mockEntityManager()` and `fakeTransaction()` from `src/tests/fixtures/database.ts` are replaced by the kit of this package.

package/README.md

@@ -1,31 +1,137 @@
 # @starci/jest-preset
 
-The jest config of a Nest repository, and the typed `mock<T>()` helper. Install it from the npm registry at the exact version in [`knowledge/hfs/canon-pins.yaml`](../../knowledge/hfs/canon-pins.yaml) (see [`packages/README.md`](../README.md)).
+The jest config of a Nest repository and the one shared unit-test double kit (`mock<T>()`, `mockEntityManager`, `fakeTransaction`, `fakeCache`, `fakeLock`, `recordingOutbox`, `builder`, `FakeClock`, `fakeIds` and the Outcome matchers). Install it from the npm registry at the exact version in [`knowledge/hfs/canon-pins.yaml`](../../knowledge/hfs/canon-pins.yaml) (see [`packages/README.md`](../README.md)).
 
 ```js
-// jest.config.js
-const { pathsToModuleNameMapper } = require("ts-jest")
-const { starciJestConfig } = require("@starci/jest-preset")
-const { compilerOptions } = require("./tsconfig.json")
-
-module.exports = starciJestConfig({
-    moduleNameMapper: pathsToModuleNameMapper(compilerOptions.paths, { prefix: `${__dirname}/` }),
-    e2e: { globalSetup: "<rootDir>/src/tests/e2e/setup/global-setup.js" },
-})
+// jest.config.js (a managed file: `hfs sync` renders it, `hfs check` compares it; do not edit)
+module.exports = require("@starci/jest-preset").starciJestConfig()
 ```
 
+`starciJestConfig()` takes no options: a repository has no jest setting to tune, so the file above is the whole config.
+
 ## What it sets
 
-- **Two projects**: `unit` (`**/*.spec.ts`, mocked, `clearMocks`) and `e2e` (`src/tests/e2e/**/*.e2e-spec.ts`, one worker, 120 s).
-  `src/tests/e2e/live/` is skipped unless `E2E_LIVE=1`; `test:e2e:live` is `E2E_LIVE=1 jest --selectProjects e2e src/tests/e2e/live`.
-- **ts-jest with `diagnostics: false`** in both. `isolatedModules: true` comes from `@starci/tsconfig` (ts-jest 29.4 reads it
-  there; its own option is deprecated). Types are checked once, by `typecheck` (unit specs included) and `typecheck:e2e`, and
-  `test:e2e` is `npm run typecheck:e2e && jest --selectProjects e2e`, so nobody runs e2e on code that does not type-check.
-- **Coverage that matches Sonar.** `collectCoverageFrom` is `src/**/*.ts` and `apps/**/*.ts` minus specs, e2e specs, `dist`,
-  `coverage`, `src/tests/**`, `*.d.ts` and `main.ts`: the same set Sonar counts. `sonarExclusions()` and
-  `sonarCoverageExclusions()` render the two `sonar-project.properties` values from the same lists, so the denominators
-  cannot drift. Reports are `coverage/lcov.info` (Codecov and Sonar read the one file) and a text summary. Thresholds are not
-  set here; Codecov's project and patch targets own the gate.
+- **Four projects, one per test kind**: `unit` (`**/*.spec.ts`, which by the unit standard means one `<name>.service.spec.ts` beside each `*.service.ts`; `clearMocks`; the Outcome matchers are installed through `setupFilesAfterEnv`; ignores
+  `src/tests/{world,integration,e2e,contract}/`), `integration` (`src/tests/integration/**/*.integration-spec.ts`), `e2e`
+  (`src/tests/e2e/**/*.e2e-spec.ts`) and `contract` (`src/tests/contract/**/*.contract-spec.ts`). The last three compile against
+  `src/tests/tsconfig.json`, run one worker, and start the one test world through `globalSetup`/`globalTeardown`
+  (`src/tests/world/global-setup.ts`, `global-teardown.ts`); only the unit project has a `setupFilesAfterEnv`. The managed scripts select one
+  project each: `test`, `test:integration`, `test:e2e`, `test:contract`; a contract spec skips itself without sandbox config.
+- **The three path aliases** `@features/*`, `@modules/*`, `@tests/*` (`MODULE_NAME_MAPPER`), the same ones the managed `tsconfig.json` declares.
+- **ts-jest with `diagnostics: false`** in every project. `isolatedModules: true` comes from `@starci/tsconfig` (ts-jest 29.4 reads it
+  there; its own option is deprecated). Types are checked once, by `typecheck` (unit specs included) and `typecheck:tests`
+  (`src/tests/tsconfig.json`), and `test:integration`/`test:e2e`/`test:contract` run `typecheck:tests` first, so no world spec
+  runs on code that does not type-check.
+- **Coverage of services only, per-file 100.** `collectCoverageFrom` is `src/**/*.service.ts` minus `src/tests/**`, `dist` and
+  `coverage`, and `coverageThreshold` is `{ "./src/**/*.service.ts": { lines: 100, branches: 100, functions: 100, statements: 100 } }`,
+  a glob key that applies to each file on its own, so every service must reach 100 on every metric (an average never passes). The
+  managed `test` script runs the unit project with `--coverage` and fails below it. Coverage is measured by v8, which counts the
+  real source. The unit project overlays `isolatedModules: false` and `importHelpers: true` on the repository tsconfig (ts-jest merges an
+  inline `tsconfig` object over the `tsconfig.json` it finds): with `isolatedModules` on, TypeScript emits an unreachable
+  `typeof Dep !== "undefined" ? Dep : Object` guard per class-typed constructor parameter, and inlined decorator helpers carry branches
+  of their own, so 100 would be unreachable. The repository lists `tslib` in its devDependencies (`UNIT_COMPILER_OPTIONS`). Reporters are `text-summary` and
+  `text`; there is no `lcov`.
+- **Sonar does not read coverage.** `sonarCoverageExclusions()` and the lcov report are removed. `sonarExclusions()` still renders
+  `sonar.exclusions` (`**/*.spec.ts,**/*.e2e-spec.ts,**/dist/**,**/coverage/**`); the quality gate fails on imported issues only.
+
+## The unit standard in one page
+
+Only services are unit-tested, through `Test.createTestingModule`, with the doubles of this package and nothing else:
+
+```ts
+import { Test } from "@nestjs/testing"
+import { FakeClock, mockEntityManager } from "@starci/jest-preset"
+
+const clock = new FakeClock("2026-01-01T00:00:00.000Z")
+const entityManager = mockEntityManager({ findOne: [Accrual, null] })
+const moduleRef = await Test.createTestingModule({
+  providers: [
+    CommissionService,
+    { provide: PRIMARY_ENTITY_MANAGER, useValue: entityManager },   // exactly the constructor dependencies
+    { provide: CLOCK, useValue: clock },
+  ],
+}).compile()
+const service = moduleRef.get(CommissionService)
+```
+
+No `new` of the service, no `imports`, no `overrideProvider`, no `jest.mock`, no casts, no `Date.now()` and no `process.env`. The
+full rules and the dependency-to-double-to-cases table are `knowledge/patterns/be/test.yaml` (BE-TEST-1 to BE-TEST-15). Every
+export below is on the package root (`@starci/jest-preset`); the sub-paths `./mock`, `./clock`, `./entity-manager`, `./ids`,
+`./matchers`, `./cache`, `./lock`, `./outbox` and `./builders` exist as well.
+
+## `mockEntityManager` and `fakeTransaction`
+
+A strict, typed `EntityManager` double. Describe what the subject should see; every method is a `jest.fn`, and any method the
+subject calls that the spec did not stub throws an error naming the method, so the absence of a stub proves the absence of that
+database call. A wrong entity or SQL text throws too. `create(Entity, plain)` works without a stub.
+
+```ts
+import { mockEntityManager, fakeTransaction } from "@starci/jest-preset"
+
+// [Entity, result], typed against the entity: `findOne: [Order, 5]` is a compile error
+const em = mockEntityManager({ findOne: [Order, order], save: [Order, saved] })
+expect(em.save).toHaveBeenCalledWith(expect.objectContaining({ status: "paid" }))
+
+// a raw query: [sql, rows]
+const reader = mockEntityManager({ query: ["select 1", [{ n: 1 }]] })
+
+// lists: a list of pairs answers several calls in order
+const two = mockEntityManager({ find: [[Order, [orderA]], [Order, [orderB]]] })
+
+// a transaction: work runs with a scoped view; commits, rollbacks and writes are recorded
+const tx = fakeTransaction(mockEntityManager({ save: [Order, saved] }))
+await service.place(params)                       // service calls em.transaction(async (manager) => ...)
+expect(tx.commits).toBe(1)
+expect(tx.committedWrites).toHaveLength(1)        // after a throwing body: tx.rollbacks, tx.rolledBackWrites, tx.outcomes
+```
+
+The stubbable methods are `findOne`, `findOneBy`, `findOneOrFail`, `findOneByOrFail`, `find`, `findBy`, `findAndCount`,
+`findAndCountBy`, `count`, `countBy`, `exists`, `existsBy`, `save`, `remove`, `softRemove`, `recover`, `insert`, `update`, `upsert`,
+`delete`, `softDelete`, `restore`, `increment`, `decrement` and `query`. `fakeTransaction(em)` returns `{ em, outcomes, commits,
+rollbacks, committedWrites, rolledBackWrites }`.
+
+## `fakeCache(clock)`, `fakeLock(clock)` and `recordingOutbox()`
+
+```ts
+const clock = new FakeClock("2026-01-01T00:00:00.000Z")
+
+const cache = fakeCache(clock)     // JSON round trip; TTL from the clock
+await cache.set({ key, args: ["u1"], value: profile })   // the typed-key port: get/set/del({ key, args, value })
+await cache.get({ key, args: ["u1"] })
+await cache.set("raw-key", value, 60_000)                // the cache-manager shape: get(text), set(text, value, ttlMs)
+cache.has({ key, args: ["u1"] })                          // a live entry exists
+cache.ttlOf({ key, args: ["u1"] })                        // seconds left (rounded up), null when absent or expired
+cache.keys()                                              // the texts of the live entries
+clock.advance(301_000)                                    // entries with a 300 s TTL are now expired
+
+const lock = fakeLock(clock)       // acquire, contention, release, expiry, growing fence
+const grant = await lock.acquire({ name: "writer", holder: "a", ttlMs: 30_000 })   // null when held by another
+lock.isHeld("writer"); lock.holderOf("writer"); lock.fenceOf("writer")
+await lock.release({ grant })
+
+const outbox = recordingOutbox()   // enqueue(manager, message)
+outbox.messages     // what the store would hold: the first write of each (queue, eventId)
+outbox.writes       // every message written, duplicates included
+outbox.entries      // every write with its manager and `inTransaction`
+outbox.allInTransaction; outbox.messagesOf("queue"); outbox.clear()
+```
+
+## `builder`, `fakeIds` and the Outcome matchers
+
+```ts
+import { builder, fakeIds } from "@starci/jest-preset"
+
+const options = builder<CommissionOptions>({ bps: 3000, enabled: true })   // a function returning the defaults with overrides applied
+const disabled = options({ enabled: false })
+const ids = fakeIds()             // ids.next() === "00000000-0000-4000-8000-000000000001", then ...0002; ids.issued, ids.reset()
+
+expect(outcome).toBeRefused("COMMISSION_SELF_REFERRAL")                     // { kind: "refused" } with this code
+expect(outcome).toBeRefused({ code: "PLAN_LIMIT", params: { max: 3 } })    // and these params
+expect(outcome).toSucceedWith(accrual)                                      // { kind: "ok" } whose value equals `accrual`
+```
+
+The matchers are installed in the unit project only (`setupFilesAfterEnv`); their types are declared globally by importing the
+package.
 
 ## `mock<T>()`
 

package/builders.cjs

@@ -0,0 +1,15 @@
+"use strict"
+
+/**
+ * `builder(defaults)` -- the one way a spec makes a plain value with a few fields changed: a module options object
+ * (`<CAP>_OPTIONS`), a principal, a request context. Options tokens are provided as REAL values, never as doubles; a
+ * builder holds the valid defaults once so each spec states only the field it varies.
+ *
+ *   const options = builder<OrderOptions>({ maxLines: 50, allowGuestCheckout: false })
+ *   options({ allowGuestCheckout: true })   // a whole OrderOptions with one flag flipped
+ */
+function builder(defaults) {
+  return (overrides) => ({ ...defaults, ...overrides })
+}
+
+module.exports = { builder }

package/builders.d.ts

@@ -0,0 +1,2 @@
+/** Makes a builder of `T`: a function returning the defaults with `overrides` applied. */
+export declare function builder<T extends object>(defaults: T): (overrides?: Partial<T>) => T

package/cache.cjs

@@ -0,0 +1,67 @@
+"use strict"
+
+/**
+ * `fakeCache(clock)` -- a behavioural in-memory double of a cache port.
+ *
+ * It keeps entries as JSON text (like a Redis-backed cache, so a Date comes back as a string and a `key.parse` narrows
+ * what was stored), expires them from the `FakeClock` (`clock.advance(ms)` is a TTL expiry, no sleep), and offers the
+ * inspection a spec needs: `has(key)`, `ttlOf(key)`, `keys()`.
+ *
+ * Two call shapes are served by the same object, so it stands in for either kind of cache dependency:
+ *   - the typed-key port: `get({ key, args })`, `set({ key, args, value })`, `del({ key, args })`, where `key` is
+ *     `{ name, ttl: { seconds }, parse? }` and the entry text is `<name>:<arg>:...`;
+ *   - the cache-manager shape: `get(text)`, `set(text, value, ttlMs?)`, `del(text)`.
+ * `has`, `ttlOf` and `del` accept a request or the entry text.
+ */
+
+const textOf = (request) => (typeof request === "string" ? request : [request.key.name, ...(request.args ?? [])].join(":"))
+
+/** @param {{ now(): Date }} clock */
+function fakeCache(clock) {
+  if (!clock || typeof clock.now !== "function") throw new Error("fakeCache: pass the FakeClock the spec drives, fakeCache(clock)")
+  const entries = new Map()
+
+  const live = (text) => {
+    const entry = entries.get(text)
+    if (entry === undefined) return undefined
+    if (entry.expiresAt !== null && clock.now().getTime() >= entry.expiresAt) {
+      entries.delete(text)
+      return undefined
+    }
+    return entry
+  }
+
+  return {
+    async get(request) {
+      const entry = live(textOf(request))
+      if (entry === undefined) return null
+      const stored = JSON.parse(entry.json)
+      return typeof request === "string" || typeof request.key.parse !== "function" ? stored : request.key.parse(stored)
+    },
+    async set(request, value, ttlMs) {
+      const text = textOf(request)
+      const typed = typeof request !== "string"
+      const stored = typed ? request.value : value
+      const lifetimeMs = typed ? request.key.ttl.seconds * 1000 : ttlMs
+      if (lifetimeMs !== undefined && !(lifetimeMs > 0)) throw new Error(`fakeCache: the ttl of ${text} must be positive`)
+      entries.set(text, { json: JSON.stringify(stored), expiresAt: lifetimeMs === undefined ? null : clock.now().getTime() + lifetimeMs })
+    },
+    async del(request) {
+      entries.delete(textOf(request))
+    },
+    /** Whether a live (not expired) entry exists. */
+    has: (request) => live(textOf(request)) !== undefined,
+    /** Seconds left before the entry expires (rounded up), null when there is no live entry or it never expires. */
+    ttlOf(request) {
+      const entry = live(textOf(request))
+      if (entry === undefined || entry.expiresAt === null) return null
+      return Math.ceil((entry.expiresAt - clock.now().getTime()) / 1000)
+    },
+    /** The texts of the live entries. */
+    keys: () => [...entries.keys()].filter((text) => live(text) !== undefined),
+    /** Drops every entry. */
+    clear: () => entries.clear(),
+  }
+}
+
+module.exports = { fakeCache }

package/cache.d.ts

@@ -0,0 +1,31 @@
+/** The declared key of a typed cache entry: `{ name, ttl, parse? }`. */
+export interface FakeCacheKey<TValue = unknown> {
+  readonly name: string
+  readonly ttl: { readonly seconds: number }
+  readonly parse?: (stored: unknown) => TValue | null
+}
+/** The typed-key request: the key plus the arguments that make the entry unique. */
+export interface FakeCacheRequest<TValue = unknown> {
+  readonly key: FakeCacheKey<TValue>
+  readonly args?: ReadonlyArray<string>
+}
+export type FakeCacheEntry<TValue = unknown> = FakeCacheRequest<TValue> & { readonly value: TValue }
+
+/** A behavioural in-memory cache: JSON round trip, expiry driven by the clock, inspection helpers. */
+export interface FakeCache {
+  get<TValue>(request: FakeCacheRequest<TValue>): Promise<TValue | null>
+  get(text: string): Promise<unknown>
+  set<TValue>(entry: FakeCacheEntry<TValue>): Promise<void>
+  set(text: string, value: unknown, ttlMs?: number): Promise<void>
+  del(request: FakeCacheRequest | string): Promise<void>
+  /** Whether a live (not expired) entry exists. */
+  has(request: FakeCacheRequest | string): boolean
+  /** Seconds left before the entry expires (rounded up); null when absent, expired or without a ttl. */
+  ttlOf(request: FakeCacheRequest | string): number | null
+  /** The texts of the live entries. */
+  keys(): string[]
+  clear(): void
+}
+
+/** The cache double; `clock` is the `FakeClock` of the spec, so `clock.advance(ms)` expires entries. */
+export declare function fakeCache(clock: { now(): Date }): FakeCache

package/entity-manager.cjs

@@ -0,0 +1,145 @@
+"use strict"
+
+/**
+ * `mockEntityManager()` and `fakeTransaction()` -- the one typed double of a typeorm `EntityManager`.
+ *
+ * `mockEntityManager(stubs)` takes the answers a spec describes as `{ method: [Entity, result] }` (`query` takes
+ * `[sql, rows]`; several answers of one method are a list of pairs). Every method is a `jest.fn()`, so
+ * `expect(em.save).toHaveBeenCalledWith(...)` works, and a method the subject calls that the spec did NOT stub throws
+ * `mockEntityManager: em.<method>() was called but this spec did not stub it`. The absence of a stub is therefore the
+ * proof that the subject made no such call. A method stubbed for another entity (or another sql text) throws too and names
+ * both. Answers of one method and one entity are handed out in order and the last one repeats. There is no typeorm import
+ * here: the types come from `entity-manager.d.ts` (type-only), the runtime is a Proxy.
+ *
+ * `create(Entity, plain)` is pure construction and works without a stub. `transaction` needs `fakeTransaction`.
+ *
+ * `fakeTransaction(em)` makes `em.transaction(work)` (and `em.transaction(isolation, work)`) run `work` with a scoped view
+ * of the same double and record how it ended (`commit` when `work` resolves, `rollback` when it throws and the error is
+ * rethrown) and which writes it made, so a spec can assert that a rolled-back transaction committed nothing.
+ */
+const { createMock, jestFn } = require("./mock.cjs")
+
+/** The manager views handed to a transaction body; `recordingOutbox` asks whether a manager is one of them. */
+const TRANSACTION_MANAGERS = new WeakSet()
+
+/** Methods that change data; a write made inside a transaction is recorded on it. */
+const WRITE_METHODS = new Set([
+  "save", "insert", "update", "delete", "remove", "softRemove", "softDelete", "recover", "restore", "upsert",
+  "increment", "decrement", "clear",
+])
+const WRITE_SQL = /^\s*(insert|update|delete|upsert|merge|truncate)\b/i
+
+const describeTarget = (target) => (typeof target === "function" ? target.name || "<anonymous class>" : JSON.stringify(String(target)).slice(0, 80))
+
+const isPair = (value) => Array.isArray(value) && value.length === 2 && (typeof value[0] === "function" || typeof value[0] === "string")
+
+/** `{ method: [target, result] | [[target, result], ...] }` as `Map<method, Array<{ target, result, used }>>`. */
+function tableOf(stubs) {
+  const table = new Map()
+  for (const [method, value] of Object.entries(stubs)) {
+    const pairs = isPair(value) ? [value] : value
+    if (!Array.isArray(pairs) || !pairs.every(isPair)) {
+      throw new Error(`mockEntityManager: the stub of em.${method}() must be [Entity, result] (em.query: [sql, rows]) or a list of such pairs`)
+    }
+    table.set(method, pairs.map(([target, result]) => ({ target, result, used: false })))
+  }
+  return table
+}
+
+/**
+ * The kit over a function factory (`makeFn(implementation)`); `mockEntityManager` and `fakeTransaction` below bind it to
+ * `jest.fn`. The seam lets the package spec run the kit without a jest runtime.
+ */
+function createEntityManagerKit(makeFn) {
+  function answerOf(method, entries) {
+    if (entries === undefined) {
+      return () => {
+        throw new Error(
+          `mockEntityManager: em.${method}() was called but this spec did not stub it. Stub it with mockEntityManager({ ${method}: [Entity, result] }); an unstubbed call means the subject reached the database where the spec says it must not.`,
+        )
+      }
+    }
+    return async (...args) => {
+      const matches = entries.filter((entry) => entry.target === args[0])
+      if (matches.length === 0) {
+        throw new Error(
+          `mockEntityManager: em.${method}(${describeTarget(args[0])}) was called but this spec stubbed em.${method} only for ${entries.map((entry) => describeTarget(entry.target)).join(", ")}`,
+        )
+      }
+      const entry = matches.find((candidate) => !candidate.used) ?? matches[matches.length - 1]
+      entry.used = true
+      return entry.result
+    }
+  }
+
+  /** @param {Record<string, unknown>} [stubs] */
+  function mockEntityManager(stubs = {}) {
+    const table = tableOf(stubs)
+    const create = makeFn((target, plain) => Object.assign(new target(), plain))
+    return createMock((method) => makeFn(answerOf(method, table.get(method))))({ create })
+  }
+
+  /** @param {object} [em] - The double to attach the transaction to; a fresh `mockEntityManager()` by default. */
+  function fakeTransaction(em = mockEntityManager()) {
+    const runs = []
+    const scopedFor = (run) => {
+      const view = new Proxy(em, {
+        get(target, property, receiver) {
+          const value = Reflect.get(target, property, receiver)
+          if (property === "transaction") return (...args) => args[args.length - 1](view)
+          if (typeof property !== "string" || typeof value !== "function") return value
+          if (!WRITE_METHODS.has(property) && property !== "query") return value
+          return (...args) => {
+            if (property !== "query" || WRITE_SQL.test(String(args[0]))) run.writes.push({ method: property, args })
+            return value(...args)
+          }
+        },
+      })
+      TRANSACTION_MANAGERS.add(view)
+      return view
+    }
+    em.transaction = makeFn(async (...args) => {
+      const work = args[args.length - 1]
+      if (typeof work !== "function") throw new Error("fakeTransaction: em.transaction() needs a callback as its last argument")
+      const run = { outcome: "pending", writes: [] }
+      runs.push(run)
+      try {
+        const result = await work(scopedFor(run))
+        run.outcome = "commit"
+        return result
+      } catch (error) {
+        run.outcome = "rollback"
+        throw error
+      }
+    })
+    const writesOf = (outcome) => runs.filter((run) => run.outcome === outcome).flatMap((run) => run.writes)
+    return {
+      em,
+      /** How each transaction ended, in call order: "commit" or "rollback". */
+      get outcomes() {
+        return runs.map((run) => run.outcome)
+      },
+      get commits() {
+        return runs.filter((run) => run.outcome === "commit").length
+      },
+      get rollbacks() {
+        return runs.filter((run) => run.outcome === "rollback").length
+      },
+      /** The writes (`{ method, args }`) that ended in a commit, in call order. */
+      get committedWrites() {
+        return writesOf("commit")
+      },
+      /** The writes that a rollback discarded: made by a body that then threw. */
+      get rolledBackWrites() {
+        return writesOf("rollback")
+      },
+    }
+  }
+
+  return { mockEntityManager, fakeTransaction }
+}
+
+/** Whether `manager` is the scoped view a `fakeTransaction` body received. */
+const isTransactionManager = (manager) => typeof manager === "object" && manager !== null && TRANSACTION_MANAGERS.has(manager)
+
+module.exports = { ...createEntityManagerKit(jestFn), createEntityManagerKit, isTransactionManager }

package/entity-manager.d.ts

@@ -0,0 +1,103 @@
+/// <reference types="jest" />
+import type { DeleteResult, EntityManager, InsertResult, UpdateResult } from "typeorm"
+import type { MockOf } from "./mock"
+
+/** A typed double of `EntityManager`: assignable wherever an `EntityManager` is required, every method a jest mock. */
+export type MockEntityManager = MockOf<EntityManager>
+
+/** An entity class. */
+export type EntityClass<E extends object = object> = new (...args: never[]) => E
+
+type Row<C extends EntityClass> = InstanceType<C>
+type Write<T> = Partial<Omit<T, "raw">> & { readonly raw?: unknown }
+
+/** The result type of each entity-taking `EntityManager` method, for the entity class `C`. */
+export interface EntityAnswers<C extends EntityClass> {
+  findOne: Row<C> | null
+  findOneBy: Row<C> | null
+  findOneOrFail: Row<C>
+  findOneByOrFail: Row<C>
+  find: ReadonlyArray<Row<C>>
+  findBy: ReadonlyArray<Row<C>>
+  findAndCount: readonly [ReadonlyArray<Row<C>>, number]
+  findAndCountBy: readonly [ReadonlyArray<Row<C>>, number]
+  count: number
+  countBy: number
+  exists: boolean
+  existsBy: boolean
+  save: Row<C> | ReadonlyArray<Row<C>>
+  remove: Row<C> | ReadonlyArray<Row<C>>
+  softRemove: Row<C> | ReadonlyArray<Row<C>>
+  recover: Row<C> | ReadonlyArray<Row<C>>
+  insert: Write<InsertResult>
+  update: Write<UpdateResult>
+  upsert: Write<InsertResult>
+  delete: Write<DeleteResult>
+  softDelete: Write<UpdateResult>
+  restore: Write<UpdateResult>
+  increment: Write<UpdateResult>
+  decrement: Write<UpdateResult>
+}
+
+/** The methods a spec may stub as `[Entity, result]`. */
+export type EntityMethod = keyof EntityAnswers<EntityClass>
+
+type Pair<M extends EntityMethod, C extends EntityClass> = readonly [entity: C, result: EntityAnswers<C>[M]]
+type Untyped = readonly [unknown, unknown]
+
+/** One stub: `[Entity, result]` (`query`: `[sql, rows]`), or a list of such pairs answered in order. */
+export type StubOf<M extends string, V> = M extends "query"
+  ? readonly [sql: string, rows: unknown] | ReadonlyArray<readonly [sql: string, rows: unknown]>
+  : M extends EntityMethod
+    ? V extends readonly [infer C extends EntityClass, unknown]
+      ? Pair<M, C>
+      : V extends ReadonlyArray<readonly [infer C extends EntityClass, unknown]>
+        ? ReadonlyArray<Pair<M, C>>
+        : never
+    : never
+
+/** The stubs of a spec, checked entry by entry against the entity each one names. */
+export type StubsOf<S> = { readonly [M in keyof S & string]: StubOf<M, S[M]> }
+
+/**
+ * A strict `EntityManager` double. Describe what the subject should see, `{ findOne: [OrderEntity, order] }`; any method
+ * the subject calls that the spec did not stub throws an error naming the method, and a wrong entity or sql text throws
+ * too. Results are typed against the entity: `findOne: [OrderEntity, 5]` is a compile error.
+ */
+export declare function mockEntityManager<
+  const S extends { readonly [M in string]?: Untyped | ReadonlyArray<Untyped> } = Record<never, never>,
+>(stubs?: S & StubsOf<S>): MockEntityManager
+
+/** A write made inside a transaction. */
+export interface TransactionWrite {
+  readonly method: string
+  readonly args: ReadonlyArray<unknown>
+}
+
+/** The transaction attached to a double by `fakeTransaction`. */
+export interface FakeTransaction<M extends MockEntityManager = MockEntityManager> {
+  /** The double whose `transaction(work)` runs `work`. */
+  readonly em: M
+  /** How each transaction ended, in call order. */
+  readonly outcomes: ReadonlyArray<"commit" | "rollback" | "pending">
+  /** Number of transactions that committed. */
+  readonly commits: number
+  /** Number of transactions that rolled back (the callback threw; the error was rethrown). */
+  readonly rollbacks: number
+  /** The writes of the transactions that committed. */
+  readonly committedWrites: ReadonlyArray<TransactionWrite>
+  /** The writes of the transactions that rolled back: what a real rollback would have discarded. */
+  readonly rolledBackWrites: ReadonlyArray<TransactionWrite>
+}
+
+/** Makes `em.transaction(work)` run `work` with a scoped view of the double and record commit, rollback and writes. */
+export declare function fakeTransaction<M extends MockEntityManager = MockEntityManager>(em?: M): FakeTransaction<M>
+
+/** Whether `manager` is the view a `fakeTransaction` body received (used by `recordingOutbox`). */
+export declare function isTransactionManager(manager: unknown): boolean
+
+/** The kit over a function factory, for callers that bring their own (used by the package spec). */
+export declare function createEntityManagerKit(makeFn: (implementation?: (...args: never[]) => unknown) => unknown): {
+  mockEntityManager: typeof mockEntityManager
+  fakeTransaction: typeof fakeTransaction
+}

package/ids.cjs

@@ -0,0 +1,41 @@
+"use strict"
+
+/**
+ * `fakeIds()` -- the test double for the platform ids port (`{ next(): string }`; the production adapter is
+ * `randomUUID()` behind the port). Ids are deterministic and UUID-shaped, so a spec can assert on the exact persisted id:
+ * the first is `00000000-0000-4000-8000-000000000001`, the second `...0002`, and so on. A `prefix` (1 to 8 hex digits)
+ * changes the leading group so two generators in one spec never collide.
+ */
+class FakeIds {
+  /** @param {string} [prefix] - 1 to 8 hex digits for the first group; default "00000000". */
+  constructor(prefix = "00000000") {
+    if (!/^[0-9a-f]{1,8}$/i.test(prefix)) throw new Error("fakeIds: the prefix is 1 to 8 hex digits")
+    this._prefix = prefix.padStart(8, "0").toLowerCase()
+    this._issued = []
+  }
+
+  /** The next id. */
+  next() {
+    const n = String(this._issued.length + 1).padStart(12, "0")
+    const id = `${this._prefix}-0000-4000-8000-${n}`
+    this._issued.push(id)
+    return id
+  }
+
+  /** Every id handed out so far, in order. */
+  get issued() {
+    return [...this._issued]
+  }
+
+  /** Starts the sequence over. */
+  reset() {
+    this._issued = []
+  }
+}
+
+/** @param {string} [prefix] */
+function fakeIds(prefix) {
+  return new FakeIds(prefix)
+}
+
+module.exports = { fakeIds, FakeIds }

package/ids.d.ts

@@ -0,0 +1,13 @@
+/** The platform ids port a spec injects `fakeIds()` for: `{ next(): string }`. */
+export declare class FakeIds {
+  constructor(prefix?: string)
+  /** The next deterministic UUID-shaped id. */
+  next(): string
+  /** Every id handed out so far, in order. */
+  readonly issued: ReadonlyArray<string>
+  /** Starts the sequence over. */
+  reset(): void
+}
+
+/** A deterministic id generator: `00000000-0000-4000-8000-000000000001`, `...0002`, ... */
+export declare function fakeIds(prefix?: string): FakeIds

package/index.cjs

@@ -1,29 +1,31 @@
 "use strict"
 
 const { mock, createMock } = require("./mock.cjs")
+const { mockEntityManager, fakeTransaction } = require("./entity-manager.cjs")
+const { FakeClock } = require("./clock.cjs")
+const { fakeCache } = require("./cache.cjs")
+const { fakeLock } = require("./lock.cjs")
+const { recordingOutbox } = require("./outbox.cjs")
+const { builder } = require("./builders.cjs")
+const { fakeIds, FakeIds } = require("./ids.cjs")
 
 /**
- * What Sonar counts as production code, expressed once. `sonarCoverageExclusions` renders the same list for
- * `sonar.coverage.exclusions`, so the jest denominator and the Sonar denominator cannot drift.
- *
- * Sonar side (canon sonar-project.properties): sources = src,apps; exclusions = specs, e2e specs, dist, coverage;
- * coverage.exclusions = src/tests/**, e2e specs, entrypoints and declaration files.
+ * Coverage is measured on services only: the one place business logic lives (owner-locked unit standard). Handlers,
+ * resolvers, controllers and consumers are thin, and helpers called by a service are covered through the service's own
+ * spec, so every `*.service.ts` under `src` is the whole denominator and every file in it must reach 100 on every metric.
+ * Sonar does not read coverage at all (the gate fails on imported issues only), so there is no second list to keep in step.
  */
-const COVERAGE_SOURCES = ["src/**/*.ts", "apps/**/*.ts"]
-/** Sonar `sonar.exclusions`: not analysed at all, so neither counted nor covered. */
-const SONAR_EXCLUSIONS = ["**/*.spec.ts", "**/*.e2e-spec.ts", "**/dist/**", "**/coverage/**"]
-/** Sonar `sonar.coverage.exclusions`: analysed, but outside the coverage denominator. */
-const COVERAGE_ONLY_EXCLUSIONS = ["src/tests/**", "**/*.d.ts", "**/main.ts"]
-const COVERAGE_EXCLUDES = [...SONAR_EXCLUSIONS, ...COVERAGE_ONLY_EXCLUSIONS]
+const COVERAGE_SOURCES = ["src/**/*.service.ts"]
+const COVERAGE_EXCLUDES = ["src/tests/**", "**/dist/**", "**/coverage/**"]
+/** The four metrics, each held at 100 per file. */
+const COVERAGE_THRESHOLD = Object.freeze({ lines: 100, branches: 100, functions: 100, statements: 100 })
 
 function collectCoverageFrom() {
   return [...COVERAGE_SOURCES, ...COVERAGE_EXCLUDES.map((glob) => `!${glob}`)]
 }
 
-/** The `sonar.coverage.exclusions` value that matches `collectCoverageFrom`; `sonar.exclusions` is `sonarExclusions()`. */
-function sonarCoverageExclusions() {
-  return COVERAGE_ONLY_EXCLUSIONS.join(",")
-}
+/** Sonar `sonar.exclusions`: specs, e2e specs, dist and coverage output are not analysed at all. */
+const SONAR_EXCLUSIONS = ["**/*.spec.ts", "**/*.e2e-spec.ts", "**/dist/**", "**/coverage/**"]
 
 function sonarExclusions() {
   return SONAR_EXCLUSIONS.join(",")
@@ -33,8 +35,8 @@ const TS_TRANSFORM = String.raw`^.+\.ts$`
 
 /**
  * ts-jest without a type check (`diagnostics: false`; `isolatedModules: true` comes from @starci/tsconfig, which is where
- * ts-jest 29.4 reads it — the ts-jest option of the same name is deprecated): types are checked once, by `typecheck` / `typecheck:e2e`, never per test file.
- * `npm run test:e2e` must be `npm run typecheck:e2e && jest --selectProjects e2e` so nobody runs e2e on code that
+ * ts-jest 29.4 reads it — the ts-jest option of the same name is deprecated): types are checked once, by `typecheck` / `typecheck:tests`, never per test file.
+ * `npm run test:e2e` (and `test:integration`, `test:contract`) runs `npm run typecheck:tests` first so nobody runs a world spec on code that
  * does not type-check.
  */
 function transform(tsconfig) {
@@ -42,59 +44,114 @@ function transform(tsconfig) {
 }
 
 /**
- * The whole jest config of a Nest repository: one `unit` project and one `e2e` project.
+ * The compiler options the UNIT project overlays on the repository tsconfig (ts-jest merges an inline `tsconfig` object over the
+ * `tsconfig.json` it finds under `rootDir`). They exist so that per-file 100 coverage is reachable for a decorated service:
+ *  - `isolatedModules: false`: with it on, TypeScript cannot tell whether an imported name is a class, and emits a
+ *    `typeof (_a = typeof Dep !== "undefined" && Dep) === "function" ? _a : Object` guard per class-typed constructor parameter for
+ *    `design:paramtypes`; the `Object` arm can never run, so the branch stays uncovered. With the full language service the
+ *    metadata is emitted as plain `Dep`.
+ *  - `importHelpers: true`: the decorator helpers (`__decorate`, `__param`, `__metadata`) come from `tslib`, not inlined per file
+ *    with branches of their own. The repository lists `tslib` in its devDependencies.
+ * Integration, e2e and contract keep the repository setting: they measure nothing.
+ */
+const UNIT_COMPILER_OPTIONS = Object.freeze({ isolatedModules: false, importHelpers: true })
+
+function unitTransform() {
+  return transform({ ...UNIT_COMPILER_OPTIONS })
+}
+
+/**
+ * The path aliases of a StarCi back end: the same three `paths` the managed `tsconfig.json` declares, so jest resolves what
+ * `tsc` resolves. They are part of the preset, not an option: a repository has no other alias.
+ */
+const MODULE_NAME_MAPPER = Object.freeze({
+  "^@features/(.*)$": "<rootDir>/src/features/$1",
+  "^@modules/(.*)$": "<rootDir>/src/modules/$1",
+  "^@tests/(.*)$": "<rootDir>/src/tests/$1",
+})
+
+/** The test folders under `src/tests/` that a project other than `unit` owns (owner test layout 2026-09-30). */
+const TEST_KIND_FOLDERS = Object.freeze(["world", "integration", "e2e", "contract"])
+const underTests = (folder) => String.raw`[\\/]src[\\/]tests[\\/]` + folder + String.raw`[\\/]`
+
+/**
+ * The whole jest config of a Nest repository: projects `unit` (colocated `<name>.spec.ts`), `integration`
+ * (`src/tests/integration/<capability>/<name>.integration-spec.ts`), `e2e` (`src/tests/e2e/<area>/<name>.e2e-spec.ts`) and
+ * `contract` (`src/tests/contract/<provider>/<name>.contract-spec.ts`). It takes no options: the repository's `jest.config.js` is a managed file
+ * (R05), rendered by `hfs sync` as `module.exports = require("@starci/jest-preset").starciJestConfig()`.
  *
- * @param {object} options
- * @param {string} [options.tsconfig]            ts-jest tsconfig, default `tsconfig.json`
- * @param {Record<string,string|string[]>} [options.moduleNameMapper]  path aliases for both projects
- * @param {string[]} [options.roots]             default `<rootDir>/src`, `<rootDir>/apps`
- * @param {object} [options.unit]                extra jest project options for unit (setupFiles, ...)
- * @param {object} [options.e2e]                 extra jest project options for e2e (globalSetup, ...)
+ * The managed scripts select one project each (`test` = unit, `test:integration`, `test:e2e`, `test:contract`); the
+ * contract project is never part of `test` or `test:e2e`, and a contract spec skips itself without sandbox config. The
+ * test tree compiles against `src/tests/tsconfig.json`, the nearest config of every file under `src/tests/`. The
+ * integration, e2e and contract projects share the world's `global-setup.ts`/`global-teardown.ts` (`src/tests/world/`) and
+ * run one worker; the unit project alone has a `setupFilesAfterEnv` (the Outcome matchers).
+ * Coverage is collected from every `*.service.ts` only, with a per-file threshold of 100 on lines, branches, functions and
+ * statements: the `test` script runs the unit project with `--coverage` and fails below it. It uses v8: istanbul instruments the helpers TypeScript emits (`__decorate`, `__param`, `__awaiter`, interop wrappers)
+ * as thousands of branches no spec can cover, while v8 measures the real source.
  */
-function starciJestConfig(options = {}) {
-  const tsconfig = options.tsconfig ?? "tsconfig.json"
+function starciJestConfig() {
   const shared = {
     preset: "ts-jest",
     testEnvironment: "node",
-    rootDir: options.rootDir ?? ".",
-    roots: options.roots ?? ["<rootDir>/src", "<rootDir>/apps"],
-    moduleNameMapper: options.moduleNameMapper ?? {},
-    transform: transform(tsconfig),
+    rootDir: ".",
+    roots: ["<rootDir>/src", "<rootDir>/apps"],
+    moduleNameMapper: { ...MODULE_NAME_MAPPER },
   }
-  const live = process.env.E2E_LIVE === "1"
+  const suite = (displayName, suffix) => ({
+    ...shared,
+    transform: transform("src/tests/tsconfig.json"),
+    displayName,
+    maxWorkers: 1,
+    testMatch: [`<rootDir>/src/tests/${displayName}/**/*.${suffix}.ts`],
+    // The one test world: started once per run of a project that has a test to run, torn down after it.
+    globalSetup: "<rootDir>/src/tests/world/global-setup.ts",
+    globalTeardown: "<rootDir>/src/tests/world/global-teardown.ts",
+  })
   return {
     testTimeout: 120_000,
+    coverageProvider: "v8",
     collectCoverageFrom: collectCoverageFrom(),
+    // A glob key is applied to every matching file on its own: each service file must reach 100, not the average.
+    coverageThreshold: { "./src/**/*.service.ts": { ...COVERAGE_THRESHOLD } },
     coverageDirectory: "coverage",
-    coverageReporters: ["lcov", "text-summary"],
+    coverageReporters: ["text-summary", "text"],
     projects: [
       {
         ...shared,
+        transform: unitTransform(),
         displayName: "unit",
         clearMocks: true,
+        // The Outcome matchers (`toBeRefused`, `toSucceedWith`) exist in the unit project only.
+        setupFilesAfterEnv: [require.resolve("./matchers.cjs")],
         testMatch: ["**/*.spec.ts"],
-        testPathIgnorePatterns: ["/node_modules/", "\.e2e-spec\.ts$", "[\\/]src[\\/]tests[\\/]e2e[\\/]"],
-        ...options.unit,
-      },
-      {
-        ...shared,
-        displayName: "e2e",
-        maxWorkers: 1,
-        testMatch: ["<rootDir>/src/tests/e2e/**/*.e2e-spec.ts"],
-        testPathIgnorePatterns: live ? ["/node_modules/"] : ["/node_modules/", "[\\/]src[\\/]tests[\\/]e2e[\\/]live[\\/]"],
-        ...options.e2e,
+        testPathIgnorePatterns: ["/node_modules/", ...TEST_KIND_FOLDERS.map(underTests)],
       },
+      suite("integration", "integration-spec"),
+      suite("e2e", "e2e-spec"),
+      suite("contract", "contract-spec"),
     ],
   }
 }
 
 module.exports = {
   starciJestConfig,
+  TEST_KIND_FOLDERS,
+  MODULE_NAME_MAPPER,
   mock,
   createMock,
+  mockEntityManager,
+  fakeTransaction,
+  FakeClock,
+  fakeCache,
+  fakeLock,
+  recordingOutbox,
+  builder,
+  fakeIds,
+  FakeIds,
   collectCoverageFrom,
-  sonarCoverageExclusions,
   sonarExclusions,
   COVERAGE_SOURCES,
   COVERAGE_EXCLUDES,
+  COVERAGE_THRESHOLD,
+  UNIT_COMPILER_OPTIONS,
 }

package/index.d.ts

@@ -1,19 +1,22 @@
 import type { Config } from "jest"
 
 export { mock, createMock, MockOf } from "./mock"
+export { mockEntityManager, fakeTransaction, MockEntityManager, FakeTransaction, EntityClass } from "./entity-manager"
+export { fakeCache, FakeCache } from "./cache"
+export { fakeLock, FakeLock } from "./lock"
+export { recordingOutbox, RecordingOutbox } from "./outbox"
+export { builder } from "./builders"
+export { FakeClock } from "./clock"
+export { fakeIds, FakeIds } from "./ids"
+export { RefusalReason } from "./matchers"
 
-export interface StarciJestOptions {
-  rootDir?: string
-  tsconfig?: string
-  moduleNameMapper?: Record<string, string | string[]>
-  roots?: string[]
-  unit?: Record<string, unknown>
-  e2e?: Record<string, unknown>
-}
-
-export declare function starciJestConfig(options?: StarciJestOptions): Config
+/** The whole jest config: projects `unit`, `integration`, `e2e` and `contract`. It takes no options; the repository config is a managed file. */
+export declare function starciJestConfig(): Config
+export declare const MODULE_NAME_MAPPER: Readonly<Record<string, string>>
 export declare function collectCoverageFrom(): string[]
-export declare function sonarCoverageExclusions(): string
 export declare function sonarExclusions(): string
 export declare const COVERAGE_SOURCES: string[]
 export declare const COVERAGE_EXCLUDES: string[]
+/** The compiler options the unit project overlays on the repository tsconfig so per-file 100 coverage of a decorated service is reachable. */
+export declare const UNIT_COMPILER_OPTIONS: Readonly<{ isolatedModules: false; importHelpers: true }>
+export declare const COVERAGE_THRESHOLD: Readonly<{ lines: 100; branches: 100; functions: 100; statements: 100 }>

package/lock.cjs

@@ -0,0 +1,56 @@
+"use strict"
+
+/**
+ * `fakeLock(clock)` -- a behavioural in-memory double of a lease (cross-replica lock with fencing).
+ *
+ * `acquire({ name, holder, ttlMs, at? })` grants `{ name, holder, fence }` when nobody holds the name (or the previous
+ * ttl ran out on the clock) and answers `null` on contention; the fence grows with every grant of one name.
+ * `release({ grant })` lets go only when the grant is still current. A holder acquiring its own live lease renews it.
+ * Inspection: `isHeld(name)`, `holderOf(name)`, `fenceOf(name)`. Expiry is driven by the `FakeClock`; a request may carry
+ * its own `at`, which wins.
+ */
+
+/** @param {{ now(): Date }} [clock] */
+function fakeLock(clock) {
+  const state = new Map()
+  const fences = new Map()
+  const nowOf = (params) => {
+    const at = params.at ?? clock?.now()
+    if (at === undefined) throw new Error("fakeLock: pass the FakeClock, fakeLock(clock), or an `at` on each acquire")
+    return at.getTime()
+  }
+  const liveHold = (name) => {
+    const hold = state.get(name)
+    if (hold === undefined) return undefined
+    if (clock !== undefined && clock.now().getTime() >= hold.expiresAt) {
+      state.delete(name)
+      return undefined
+    }
+    return hold
+  }
+
+  return {
+    async acquire(params) {
+      const at = nowOf(params)
+      const held = state.get(params.name)
+      const alive = held !== undefined && at < held.expiresAt
+      if (alive && held.holder !== params.holder) return null
+      const fence = alive ? held.fence : (fences.get(params.name) ?? 0) + 1
+      fences.set(params.name, fence)
+      state.set(params.name, { holder: params.holder, fence, expiresAt: at + params.ttlMs })
+      return { name: params.name, holder: params.holder, fence }
+    },
+    async release({ grant }) {
+      const held = state.get(grant.name)
+      if (held !== undefined && held.fence === grant.fence && held.holder === grant.holder) state.delete(grant.name)
+    },
+    /** Whether a live lease exists for `name`. */
+    isHeld: (name) => liveHold(name) !== undefined,
+    /** The holder of the live lease, or null. */
+    holderOf: (name) => liveHold(name)?.holder ?? null,
+    /** The fence of the latest grant of `name`, or null when it was never granted. */
+    fenceOf: (name) => fences.get(name) ?? null,
+  }
+}
+
+module.exports = { fakeLock }

package/lock.d.ts

@@ -0,0 +1,26 @@
+/** What a caller asks for when it wants a named lease. */
+export interface FakeLockAcquire {
+  readonly name: string
+  readonly holder: string
+  readonly ttlMs: number
+  /** The instant of the request; defaults to the clock of the double. */
+  readonly at?: Date
+}
+/** A granted lease. */
+export interface FakeLockGrant {
+  readonly name: string
+  readonly holder: string
+  readonly fence: number
+}
+
+/** A behavioural in-memory lease: acquire, contention, release, ttl expiry on the clock, growing fence. */
+export interface FakeLock {
+  acquire(params: FakeLockAcquire): Promise<FakeLockGrant | null>
+  release(params: { readonly grant: FakeLockGrant }): Promise<void>
+  isHeld(name: string): boolean
+  holderOf(name: string): string | null
+  fenceOf(name: string): number | null
+}
+
+/** The lock double; expiry follows `clock`, so `clock.advance(ms)` frees a lease whose ttl ran out. */
+export declare function fakeLock(clock?: { now(): Date }): FakeLock

package/matchers.cjs

@@ -0,0 +1,45 @@
+"use strict"
+
+/**
+ * Outcome matchers, registered by the `unit` project's `setupFilesAfterEnv` (nowhere else).
+ *
+ * They match the platform `Outcome<V, C>` structurally: `{ kind: "ok", value }` or `{ kind: "refused", code, params? }`.
+ * `expect(outcome).toBeRefused("STOCK_EXHAUSTED")` (or `{ code, params }`) and `expect(outcome).toSucceedWith(value)`.
+ */
+
+const isOutcome = (received) => typeof received === "object" && received !== null && (received.kind === "ok" || received.kind === "refused")
+
+const notOutcome = (utils, received) => `expected an Outcome ({ kind: "ok" | "refused" }), received ${utils.printReceived(received)}`
+
+const matchers = {
+  toBeRefused(received, reason) {
+    if (!isOutcome(received)) return { pass: false, message: () => notOutcome(this.utils, received) }
+    const expected = typeof reason === "string" ? { code: reason } : reason
+    const pass =
+      received.kind === "refused" &&
+      received.code === expected.code &&
+      (!("params" in expected) || this.equals(received.params, expected.params))
+    return {
+      pass,
+      message: () =>
+        pass
+          ? `expected the outcome not to be refused with ${this.utils.printExpected(expected)}`
+          : `expected the outcome to be refused with ${this.utils.printExpected(expected)}, received ${this.utils.printReceived(received)}`,
+    }
+  },
+  toSucceedWith(received, value) {
+    if (!isOutcome(received)) return { pass: false, message: () => notOutcome(this.utils, received) }
+    const pass = received.kind === "ok" && this.equals(received.value, value)
+    return {
+      pass,
+      message: () =>
+        pass
+          ? `expected the outcome not to succeed with ${this.utils.printExpected(value)}`
+          : `expected the outcome to succeed with ${this.utils.printExpected(value)}, received ${this.utils.printReceived(received)}`,
+    }
+  },
+}
+
+if (typeof expect !== "undefined" && typeof expect.extend === "function") expect.extend(matchers)
+
+module.exports = { matchers }

package/matchers.d.ts

@@ -0,0 +1,17 @@
+/// <reference types="jest" />
+
+/** The refusal a matcher expects: a capability code, or a code with the parameters of its display text. */
+export type RefusalReason = string | { readonly code: string; readonly params?: Record<string, unknown> }
+
+declare global {
+  namespace jest {
+    interface Matchers<R> {
+      /** The received `Outcome` is `{ kind: "refused" }` with this code (and these params, when given). */
+      toBeRefused(reason: RefusalReason): R
+      /** The received `Outcome` is `{ kind: "ok" }` whose value equals `value` (recursive equality). */
+      toSucceedWith(value: unknown): R
+    }
+  }
+}
+
+export declare const matchers: Record<"toBeRefused" | "toSucceedWith", (this: jest.MatcherContext, received: unknown, expected: unknown) => jest.CustomMatcherResult>

package/mock.cjs

@@ -8,8 +8,8 @@
  * type-checks against `Repo["find"]`. Values passed in `overrides` win over the generated functions and may be
  * partial: the return type is still `T`.
  *
- * `createMock` takes the function factory as an argument so the helper has no hard dependency on a global
- * `jest`; `mock` binds it to `jest.fn`.
+ * `createMock` takes the function factory as an argument (called with the property name) so the helper has no hard
+ * dependency on a global `jest`; `mock` binds it to `jest.fn`.
  */
 
 // Probed by promise resolution, jest matchers and serializers: they must read as absent, not as a mock function.
@@ -24,7 +24,7 @@ function createMock(makeFn) {
         if (Object.hasOwn(target, property)) return Reflect.get(target, property, receiver)
         if (typeof property === "symbol" || property in Object.prototype) return Reflect.get(target, property, receiver)
         if (ABSENT.has(property)) return undefined
-        if (!own.has(property)) own.set(property, makeFn())
+        if (!own.has(property)) own.set(property, makeFn(property))
         return own.get(property)
       },
       set(target, property, value) {
@@ -41,13 +41,13 @@ function createMock(makeFn) {
 
 // jest-runtime hands every module it loads, this one included, a module-scoped `jest` object; it is not a property
 // of globalThis, so it is read as a free identifier. @jest/globals is the fallback for a runner that does not.
-function jestFn() {
-  if (typeof jest !== "undefined" && typeof jest.fn === "function") return jest.fn()
+function jestFn(implementation) {
+  if (typeof jest !== "undefined" && typeof jest.fn === "function") return jest.fn(implementation)
   try {
-    return require("@jest/globals").jest.fn()
+    return require("@jest/globals").jest.fn(implementation)
   } catch {
     throw new Error("@starci/jest-preset mock<T>() needs the jest runtime; call it from a jest test")
   }
 }
 
-module.exports = { mock: createMock(jestFn), createMock }
+module.exports = { mock: createMock(() => jestFn()), createMock, jestFn }

package/outbox.cjs

@@ -0,0 +1,53 @@
+"use strict"
+
+/**
+ * `recordingOutbox()` -- an outbox double that records what a service writes, so a spec asserts on `outbox.messages`.
+ *
+ * `enqueue(manager, message)` records the message with the manager it was written through. `messages` is what the store
+ * would hold: one message per (queue, eventId), like the real unique key, so a duplicate write keeps one. `writes` is every
+ * call, duplicates included, and `entries` adds `inTransaction`: whether the manager was the view a `fakeTransaction` body
+ * received, so a spec proves a message is written in the transaction of the change that caused it.
+ */
+const { isTransactionManager } = require("./entity-manager.cjs")
+
+function recordingOutbox() {
+  const written = []
+  return {
+    async enqueue(manager, message) {
+      written.push({ message, manager, inTransaction: isTransactionManager(manager) })
+    },
+    /** The messages the store would hold: the first write of each (queue, eventId). */
+    get messages() {
+      const seen = new Set()
+      return written
+        .filter(({ message }) => {
+          const key = `${message.queue}\u0000${message.eventId}`
+          if (seen.has(key)) return false
+          seen.add(key)
+          return true
+        })
+        .map(({ message }) => message)
+    },
+    /** Every write, in order: `{ message, manager, inTransaction }`. */
+    get entries() {
+      return [...written]
+    },
+    /** Every message written, duplicates included. */
+    get writes() {
+      return written.map(({ message }) => message)
+    },
+    /** True when something was written and every write went through a transaction manager. */
+    get allInTransaction() {
+      return written.length > 0 && written.every((entry) => entry.inTransaction)
+    },
+    /** The stored messages of one queue. */
+    messagesOf(queue) {
+      return this.messages.filter((message) => message.queue === queue)
+    },
+    clear() {
+      written.length = 0
+    },
+  }
+}
+
+module.exports = { recordingOutbox }

package/outbox.d.ts

@@ -0,0 +1,32 @@
+/** A message as the outbox port takes it. */
+export interface RecordedMessage {
+  readonly queue: string
+  readonly eventId: string
+  readonly payload: object
+  readonly availableAt?: Date
+}
+/** One recorded write. */
+export interface OutboxWrite<M extends RecordedMessage = RecordedMessage> {
+  readonly message: M
+  readonly manager: unknown
+  /** Whether the manager was the view a `fakeTransaction` body received. */
+  readonly inTransaction: boolean
+}
+
+/** An outbox double that records writes. */
+export interface RecordingOutbox<M extends RecordedMessage = RecordedMessage> {
+  enqueue(manager: unknown, message: M): Promise<void>
+  /** What the store would hold: the first write of each (queue, eventId). */
+  readonly messages: ReadonlyArray<M>
+  /** Every write with its manager, duplicates included. */
+  readonly entries: ReadonlyArray<OutboxWrite<M>>
+  /** Every message written, duplicates included. */
+  readonly writes: ReadonlyArray<M>
+  /** True when something was written and every write went through a `fakeTransaction` manager. */
+  readonly allInTransaction: boolean
+  messagesOf(queue: string): ReadonlyArray<M>
+  clear(): void
+}
+
+/** The outbox double. */
+export declare function recordingOutbox<M extends RecordedMessage = RecordedMessage>(): RecordingOutbox<M>

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@starci/jest-preset",
-  "version": "1.1.0",
-  "description": "The StarCi jest config for Nest repositories (unit and e2e projects, ts-jest with diagnostics off, coverage matching the Sonar denominators), the typed mock<T>() helper and the FakeClock test double for the platform/clock Clock port.",
+  "version": "2.0.0",
+  "description": "The StarCi jest config for Nest repositories (unit, integration, e2e and contract projects, ts-jest with diagnostics off, per-file 100 coverage of *.service.ts only) and the one shared unit-test double kit: typed mock<T>(), mockEntityManager(), fakeTransaction(), fakeCache(), fakeLock(), recordingOutbox(), FakeClock, fakeIds(), builder() and the Outcome matchers toBeRefused/toSucceedWith.",
   "license": "UNLICENSED",
   "private": false,
   "main": "index.cjs",
@@ -18,13 +18,42 @@
     "./clock": {
       "types": "./clock.d.ts",
       "default": "./clock.cjs"
+    },
+    "./entity-manager": {
+      "types": "./entity-manager.d.ts",
+      "default": "./entity-manager.cjs"
+    },
+    "./ids": {
+      "types": "./ids.d.ts",
+      "default": "./ids.cjs"
+    },
+    "./matchers": {
+      "types": "./matchers.d.ts",
+      "default": "./matchers.cjs"
+    },
+    "./cache": {
+      "types": "./cache.d.ts",
+      "default": "./cache.cjs"
+    },
+    "./lock": {
+      "types": "./lock.d.ts",
+      "default": "./lock.cjs"
+    },
+    "./outbox": {
+      "types": "./outbox.d.ts",
+      "default": "./outbox.cjs"
+    },
+    "./builders": {
+      "types": "./builders.d.ts",
+      "default": "./builders.cjs"
     }
   },
   "files": [
     "*.cjs",
     "*.d.ts",
     "!*.test.*",
-    "README.md"
+    "README.md",
+    "CHANGELOG.md"
   ],
   "publishConfig": {
     "access": "public"
@@ -32,9 +61,15 @@
   "peerDependencies": {
     "@types/jest": ">=29",
     "jest": ">=29",
-    "ts-jest": ">=29"
+    "ts-jest": ">=29",
+    "typeorm": ">=0.3"
   },
   "scripts": {
     "test": "node --test \"*.test.mjs\""
+  },
+  "peerDependenciesMeta": {
+    "typeorm": {
+      "optional": true
+    }
   }
 }