@starci/jest-preset 2.2.3 → 2.2.5

package/CHANGELOG.md

@@ -1,5 +1,23 @@
 # Changelog
 
+## Unreleased
+
+- Breaking (contract change `coverage-modules-logic`): `starciJestConfig({ coverage: { roots, roles, excludes } })` takes the coverage scope the managed `be/jest.config.js` renders (`hfs sync`, from the `coverage` field of the slot manifest and `ruleParams.be.logicRoles`, through `scripts/hfs/coverage-scope.mjs`), and refuses to run without it. `COVERAGE_SOURCES` is deleted: per-file 100 now holds on every logic role (service, policy, projection, guard, mapper, client, filter, interceptor, processor, step, saga, saga-step, compensation, consumer, webhook) inside the measured roots (the logic of `be/src/modules`), never on `be/src/features` (thin by R203). New exports `rootGlob` and `StarciCoverageScope`; `collectCoverageFrom(coverage)` and `hasCoverageSubjects(root, glob)` take a scope and a glob with `**` and `{a,b}`.
+- New: `fakeInbox()` (also `@starci/jest-preset/inbox`), the twin of `recordingOutbox()` for the delivery side: `claim` answers true for the first call of a (source, eventId) pair and false afterwards, `release` gives the claim back, `seen` marks a redelivery, and `claims`, `claimed`, `released`, `failNext` and `clear` let a spec assert what a consumer or a signed webhook did. A spec no longer stubs `mock<Inbox>()` by hand.
+
+## 2.2.4 - 2026-10-02
+
+- Changed: the world runner runs up to `min(--maxWorkers, slots)` files of the integration, e2e and contract projects at once,
+  each still in a fresh process of its own (never in band), each bound to one data slot of `@starci/test-world` 1.1.0: the
+  file's process is forked with `STARCI_TEST_WORLD_SLOT=<k>`, and no two files ever hold one slot at the same time. The slot
+  count is the one the world's globalSetup published in its state file. This lifts the 2.2.0 limitation "one file at a time".
+- Changed: the runner reads test-world state protocol 2 only. A missing state file or another protocol fails the run with
+  `JEST_PRESET_WORLD_PAIR_MISMATCH`, naming this preset, the test-world that wrote the file and the fix (pin both together per
+  knowledge/hfs/canon-pins.yaml); there is no fallback mode.
+## Unreleased
+
+- Removed (breaking): `recordingOutbox()` and the `./outbox` entry, superseded by the event bus and the queue outbox. Added `recordingEventBus()` (the `EventBus` port: `publish(event, tx)`, scripted pending retries, dead letters and one-shot failures) and `recordingQueueOutbox()` (the `QueueOutbox` port: `write(tx, queue, payload)`), each recording whether `tx` was a `fakeTransaction` manager, and the `./event-bus` and `./queue` entries. Contract change `patterns-event-bus`.
+
 ## 2.2.2 - 2026-10-01
 
 - Changed: the coverage reporters are `text-summary`, `text` and `lcov`. The unit run writes `coverage/lcov.info`, which Sonar (`sonar.javascript.lcov.reportPaths`) and Codecov import with the scope `hfs sync` renders from `COVERAGE_SOURCES` (services only). Coverage is still collected from `src/**/*.service.ts` only, with the per-file threshold of 100. Contract change `sonar-services-coverage`.

package/LICENSE

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

package/README.md

@@ -1,47 +1,54 @@
 # @starci/jest-preset
 
-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)).
+The jest config of a Nest repository and the one shared unit-test double kit (`mock<T>()`, `mockEntityManager`, `fakeTransaction`, `fakeCache`, `fakeLock`, `recordingEventBus`, `recordingQueueOutbox`, `fakeInbox`, `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 (a managed file: `hfs sync` renders it, `hfs check` compares it; do not edit)
-module.exports = require("@starci/jest-preset").starciJestConfig()
+// jest.config.js (a managed file: `starci app sync` renders it, `starci app check` compares it; do not edit)
+module.exports = require("@starci/jest-preset").starciJestConfig({
+  coverage: { roots, roles, excludes },
+})
 ```
 
-`starciJestConfig()` takes no options: a repository has no jest setting to tune, so the file above is the whole config.
+The only option is `coverage`: the measured scope `starci app sync` derives once from the slot manifest
+(`scripts/hfs/coverage-scope.mjs`, R204 `HFS_COVERAGE_SCOPE_DRIFT`) — the measured roots, the roles a measured file carries
+and the exclusions. A repository has no other jest setting to tune.
 
 ## What it sets
 
-- **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
+- **Four projects, one per test kind**: `unit` (`**/*.spec.ts`, which by the unit standard means one `<name>.<role>.spec.ts` beside each spec-required subject — a `*.service.ts`, a `*.cli.ts` of `src/features/cli` — and beside any other measured logic file that chooses one; `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`, start the one test world through `globalSetup`/`globalTeardown`
   (`src/tests/world/global-setup.ts`, `global-teardown.ts`) and run on the world runner (`world-runner.cjs`, `WORLD_RUNNER`): every
   spec file in a worker process of its own and never in band, so nothing the globalSetup or another file left on a process global
-  (a framework registry such as `@nestjs/graphql`'s type metadata) reaches the file; and ONE FILE AT A TIME whatever
-  `--maxWorkers` says, because every file shares the run's data (the test world resets it when a file boots). Only the unit project has a `setupFilesAfterEnv`. The managed scripts select one
+  (a framework registry such as `@nestjs/graphql`'s type metadata) reaches the file; and up to `min(--maxWorkers, slots)` files at
+  once, each bound to its own data slot of `@starci/test-world` 1.1.0 (`STARCI_TEST_WORLD_SLOT`), never two files on one slot,
+  because the test world resets a slot's data when a file boots. The runner reads test-world state protocol 2 only: pin
+  the two packages together (canon-pins); another protocol fails with `JEST_PRESET_WORLD_PAIR_MISMATCH`. 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
+- **Coverage of the measured logic, per-file 100.** `collectCoverageFrom` is one glob per `coverage.roots` entry covering `<root>/**/*.{<roles>}.ts`
+  (the `ruleParams.be.logicRoles` of the rendered scope), minus its `excludes`, `dist` and `coverage`, and `coverageThreshold` holds
+  `{ lines: 100, branches: 100, functions: 100, statements: 100 }` on each of those globs — a glob key applies to each file on its own, so every file of a
+  `ruleParams.be.logicRoles` role inside a measured slot 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`,
   `text` and `lcov`: the run writes `coverage/lcov.info` under the repository (be/) root.
-- **Sonar and Codecov import that lcov, scoped to the services.** `hfs sync` renders `sonar.coverage.exclusions` (the complement of the services: SonarQube has no coverage inclusions) and the `codecov.yml`
-  status paths from `COVERAGE_SOURCES` on the be side (`be/src/**/*.service.ts`), so jest, Sonar and Codecov measure the same files;
+- **Sonar and Codecov import that lcov, scoped to the same measured files.** `starci app sync` renders `sonar.coverage.exclusions` (the complement of the measured files: SonarQube has no coverage inclusions) and the `codecov.yml`
+  status paths and components from the one derivation (`scripts/hfs/coverage-scope.mjs`), so jest, Sonar and Codecov measure the same files;
   the Sonar gate holds coverage at 100 overall, on new code and per file. `sonarExclusions()` still renders `sonar.exclusions`
   (`**/*.spec.ts,**/*.e2e-spec.ts,**/dist/**,**/coverage/**`). There is no coverage exclusion list.
 
 ## The unit standard in one page
 
-Only services are unit-tested, through `Test.createTestingModule`, with the doubles of this package and nothing else:
+Every spec-required file is unit-tested beside its subject — a `*.service.ts`, a cli command of `src/features/cli` — through `Test.createTestingModule`, with the doubles of this package and nothing else, and any other measured logic file may carry the same spec beside it:
 
 ```ts
 import { Test } from "@nestjs/testing"
@@ -62,7 +69,7 @@ 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.
+`./matchers`, `./cache`, `./lock`, `./event-bus`, `./queue`, `./inbox` and `./builders` exist as well.
 
 ## `mockEntityManager` and `fakeTransaction`
 
@@ -95,7 +102,7 @@ The stubbable methods are `findOne`, `findOneBy`, `findOneOrFail`, `findOneByOrF
 `delete`, `softDelete`, `restore`, `increment`, `decrement` and `query`. `fakeTransaction(em)` returns `{ em, outcomes, commits,
 rollbacks, committedWrites, rolledBackWrites }`.
 
-## `fakeCache(clock)`, `fakeLock(clock)` and `recordingOutbox()`
+## `fakeCache(clock)`, `fakeLock(clock)`, `recordingEventBus()` and `recordingQueueOutbox()`
 
 ```ts
 const clock = new FakeClock("2026-01-01T00:00:00.000Z")
@@ -114,18 +121,23 @@ const grant = await lock.acquire({ name: "writer", holder: "a", ttlMs: 30_000 })
 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()
-
-// the claim side: script what a worker's claim returns
-outbox.queueRecords(record)                 // the backlog claimDue hands out, in order, filtered by queue and cut at limit
-outbox.queueRecords(record, record)         // a duplicate delivery
-await outbox.claimDue(params)               // [] when the backlog is empty
-outbox.failNext("complete", new Error("db down"))   // the next call of that operation rejects once
-outbox.claims; outbox.completed; outbox.retried; outbox.buried; outbox.backlog
+const bus = recordingEventBus()   // publish(event, tx): the EventBus port
+bus.events          // what the outbox would hold: the first publication of each (event name, event id)
+bus.writes          // every event published, duplicates included
+bus.entries         // every publication with its tx and `inTransaction`
+bus.allInTransaction; bus.eventsOf(OrderPlacedEvent); bus.clear()
+bus.setPendingRetries(2)                    // what pendingRetries(eventClass) answers
+bus.queueDeadLetters(letter)                // what deadLetters(eventClass) hands out; bus.requeued keeps requeue(id) calls
+bus.failNext("publish", new Error("down"))  // the next call of that operation rejects once
+
+const queueOutbox = recordingQueueOutbox()  // write(tx, queue, payload): the QueueOutbox port
+queueOutbox.jobs; queueOutbox.jobsOf("mail"); queueOutbox.entries; queueOutbox.allInTransaction
+
+const inbox = fakeInbox()                // the delivery side, the twin of the recording outboxes
+await inbox.claim("sepay", "e-1")        // true the first time, false for the same pair until it is released
+await inbox.release("sepay", "e-1")      // gives the claim back: the next claim answers true
+inbox.seen("sepay", "e-2")               // a redelivery: the next claim of the pair answers false
+inbox.claims; inbox.claimed; inbox.released; inbox.failNext("claim", new Error("db down")); inbox.clear()
 ```
 
 ## `builder`, `fakeIds` and the Outcome matchers

package/entity-manager.cjs

@@ -19,7 +19,7 @@
  */
 const { createMock, jestFn } = require("./mock.cjs")
 
-/** The manager views handed to a transaction body; `recordingOutbox` asks whether a manager is one of them. */
+/** The manager views handed to a transaction body; `recordingEventBus` and `recordingQueueOutbox` ask 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. */

package/entity-manager.d.ts

@@ -93,7 +93,7 @@ export interface FakeTransaction<M extends MockEntityManager = MockEntityManager
 /** 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`). */
+/** Whether `manager` is the view a `fakeTransaction` body received (used by `recordingEventBus` and `recordingQueueOutbox`). */
 export declare function isTransactionManager(manager: unknown): boolean
 
 /** The kit over a function factory, for callers that bring their own (used by the package spec). */

package/event-bus.cjs

@@ -0,0 +1,100 @@
+"use strict"
+
+/**
+ * `recordingEventBus()` -- an `EventBus` double that records what a domain service publishes, so a spec asserts on `bus.events`.
+ *
+ * `publish(event, tx)` records the event with the manager it was written through. `events` is what the outbox would hold: one
+ * event per (event name, event id), like the real unique key, so a duplicate publication keeps one. `writes` is every call, duplicates
+ * included, and `entries` adds `inTransaction`: whether `tx` was the view a `fakeTransaction` body received, so a spec proves an event
+ * is published in the transaction of the change that caused it. The name of an event is the static `eventName` of its class.
+ *
+ * The read side is scripted: `setPendingRetries(count)` sets what `pendingRetries(eventClass)` answers, `deadLetters(eventClass)`
+ * returns what `queueDeadLetters(...letters)` filled, `requeue(id)` records the id, and `failNext(operation, error)` makes the next
+ * call of that operation reject once, so a spec drives the failure path.
+ */
+const { isTransactionManager } = require("./entity-manager.cjs")
+
+const nameOf = (event) => event.constructor.eventName
+
+function recordingEventBus() {
+  const written = []
+  const letters = []
+  const requeued = []
+  const failures = new Map()
+  let pending = 0
+  const failIfScripted = (operation) => {
+    if (!failures.has(operation)) return
+    const error = failures.get(operation)
+    failures.delete(operation)
+    throw error
+  }
+  return {
+    async publish(event, tx) {
+      failIfScripted("publish")
+      written.push({ event, tx, inTransaction: isTransactionManager(tx) })
+    },
+    async pendingRetries() {
+      failIfScripted("pendingRetries")
+      return pending
+    },
+    async deadLetters(eventClass) {
+      failIfScripted("deadLetters")
+      return letters.filter((letter) => letter.eventName === eventClass.eventName)
+    },
+    async requeue(id) {
+      failIfScripted("requeue")
+      requeued.push(id)
+    },
+    /** The events the outbox would hold: the first publication of each (event name, event id). */
+    get events() {
+      const seen = new Set()
+      return written
+        .filter(({ event }) => {
+          const key = `${nameOf(event)}\u0000${event.eventId}`
+          if (seen.has(key)) return false
+          seen.add(key)
+          return true
+        })
+        .map(({ event }) => event)
+    },
+    /** Every publication, in order: `{ event, tx, inTransaction }`. */
+    get entries() {
+      return [...written]
+    },
+    /** Every event published, duplicates included. */
+    get writes() {
+      return written.map(({ event }) => event)
+    },
+    /** True when something was published and every publication went through a transaction manager. */
+    get allInTransaction() {
+      return written.length > 0 && written.every((entry) => entry.inTransaction)
+    },
+    /** The stored events of one class. */
+    eventsOf(eventClass) {
+      return this.events.filter((event) => nameOf(event) === eventClass.eventName)
+    },
+    /** Sets the answer of `pendingRetries`. */
+    setPendingRetries(count) {
+      pending = count
+    },
+    /** Adds dead letters `deadLetters` hands out. */
+    queueDeadLetters(...items) {
+      letters.push(...items)
+    },
+    /** The ids passed to `requeue`, in order. */
+    get requeued() {
+      return [...requeued]
+    },
+    /** Makes the next call of `operation` reject with `error`, once. */
+    failNext(operation, error) {
+      failures.set(operation, error)
+    },
+    clear() {
+      for (const list of [written, letters, requeued]) list.length = 0
+      pending = 0
+      failures.clear()
+    },
+  }
+}
+
+module.exports = { recordingEventBus }

package/event-bus.d.ts

@@ -0,0 +1,54 @@
+/** An event as the bus port takes it: a class instance with a stable id; its name is the static `eventName` of its class. */
+export interface RecordedEvent {
+  readonly eventId: string
+}
+/** The static side of an event class. */
+export interface RecordedEventClass {
+  readonly eventName: string
+}
+/** One recorded publication. */
+export interface EventWrite<E extends RecordedEvent = RecordedEvent> {
+  readonly event: E
+  readonly tx: unknown
+  /** Whether `tx` was the view a `fakeTransaction` body received. */
+  readonly inTransaction: boolean
+}
+/** A dead letter as the bus port returns it. */
+export interface RecordedDeadLetter {
+  readonly id: string
+  readonly eventName: string
+  readonly eventId: string
+  readonly reason: string
+  readonly attempts: number
+}
+/** The bus operations `failNext` can make reject. */
+export type EventBusOperation = "publish" | "pendingRetries" | "deadLetters" | "requeue"
+
+/** An `EventBus` double that records publications and scripts the read side. */
+export interface RecordingEventBus<E extends RecordedEvent = RecordedEvent> {
+  publish(event: E, tx: unknown): Promise<void>
+  pendingRetries(eventClass: RecordedEventClass): Promise<number>
+  deadLetters(eventClass: RecordedEventClass): Promise<ReadonlyArray<RecordedDeadLetter>>
+  requeue(id: string): Promise<void>
+  /** What the outbox would hold: the first publication of each (event name, event id). */
+  readonly events: ReadonlyArray<E>
+  /** Every publication with its manager, duplicates included. */
+  readonly entries: ReadonlyArray<EventWrite<E>>
+  /** Every event published, duplicates included. */
+  readonly writes: ReadonlyArray<E>
+  /** True when something was published and every publication went through a `fakeTransaction` manager. */
+  readonly allInTransaction: boolean
+  eventsOf(eventClass: RecordedEventClass): ReadonlyArray<E>
+  /** Sets the answer of `pendingRetries`. */
+  setPendingRetries(count: number): void
+  /** Adds dead letters `deadLetters` hands out. */
+  queueDeadLetters(...items: ReadonlyArray<RecordedDeadLetter>): void
+  /** The ids passed to `requeue`. */
+  readonly requeued: ReadonlyArray<string>
+  /** Makes the next call of `operation` reject with `error`, once. */
+  failNext(operation: EventBusOperation, error: Error): void
+  clear(): void
+}
+
+/** The event bus double. */
+export declare function recordingEventBus<E extends RecordedEvent = RecordedEvent>(): RecordingEventBus<E>

package/inbox.cjs

@@ -0,0 +1,71 @@
+"use strict"
+
+/**
+ * `fakeInbox()` -- the twin of `recordingOutbox()` for the delivery side: an `Inbox` double with the behaviour of the real
+ * claim, so a spec asserts what a consumer or a signed webhook did with a delivery instead of stubbing `claim` by hand.
+ *
+ * `claim(source, eventId)` answers `true` for the first call of a (source, eventId) pair and `false` for every later one, like the
+ * real unique key; `release(source, eventId)` gives the claim back, so the next claim of the pair answers `true` again.
+ * `claims` is every claim in order, `claimed` the pairs that are held now, `released` every release, `seen(source, eventId)` marks a
+ * pair as already delivered (a redelivery), and `failNext(operation, error)` makes the next call of that operation reject once, so
+ * a spec drives the failure path.
+ */
+function fakeInbox() {
+  const held = new Set()
+  const claims = []
+  const released = []
+  const failures = new Map()
+  const keyOf = (source, eventId) => `${source}\u0000${eventId}`
+  const failIfScripted = (operation) => {
+    if (!failures.has(operation)) return
+    const error = failures.get(operation)
+    failures.delete(operation)
+    throw error
+  }
+  return {
+    async claim(source, eventId) {
+      failIfScripted("claim")
+      claims.push({ source, eventId })
+      const key = keyOf(source, eventId)
+      if (held.has(key)) return false
+      held.add(key)
+      return true
+    },
+    async release(source, eventId) {
+      failIfScripted("release")
+      released.push({ source, eventId })
+      held.delete(keyOf(source, eventId))
+    },
+    /** Marks a pair as already claimed, so the next `claim` of it answers `false` (a redelivery). */
+    seen(source, eventId) {
+      held.add(keyOf(source, eventId))
+    },
+    /** Makes the next call of `operation` reject with `error`, once. */
+    failNext(operation, error) {
+      failures.set(operation, error)
+    },
+    /** Every `claim`, in order, duplicates included. */
+    get claims() {
+      return [...claims]
+    },
+    /** The pairs held now: claimed and not released. */
+    get claimed() {
+      return [...held].map((key) => {
+        const [source, eventId] = key.split("\u0000")
+        return { source, eventId }
+      })
+    },
+    /** Every `release`, in order. */
+    get released() {
+      return [...released]
+    },
+    clear() {
+      held.clear()
+      claims.length = 0
+      released.length = 0
+      failures.clear()
+    },
+  }
+}
+
+module.exports = { fakeInbox }

package/inbox.d.ts

@@ -0,0 +1,29 @@
+/** One claim or release of a delivery. */
+export interface InboxEntry {
+  readonly source: string
+  readonly eventId: string
+}
+/** The inbox operations `failNext` can make reject. */
+export type InboxOperation = "claim" | "release"
+
+/** An `Inbox` double with the behaviour of the real claim. */
+export interface FakeInbox {
+  /** True for the first claim of a (source, eventId) pair, false for every later one until it is released. */
+  claim(source: string, eventId: string): Promise<boolean>
+  /** Gives the claim back, so the next claim of the pair answers true. */
+  release(source: string, eventId: string): Promise<void>
+  /** Marks a pair as already claimed (a redelivery). */
+  seen(source: string, eventId: string): void
+  /** Makes the next call of `operation` reject with `error`, once. */
+  failNext(operation: InboxOperation, error: Error): void
+  /** Every claim, in order, duplicates included. */
+  readonly claims: ReadonlyArray<InboxEntry>
+  /** The pairs held now: claimed and not released. */
+  readonly claimed: ReadonlyArray<InboxEntry>
+  /** Every release, in order. */
+  readonly released: ReadonlyArray<InboxEntry>
+  clear(): void
+}
+
+/** The inbox double. */
+export declare function fakeInbox(): FakeInbox

package/index.cjs

@@ -5,24 +5,36 @@ 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 { recordingEventBus } = require("./event-bus.cjs")
+const { recordingQueueOutbox } = require("./queue.cjs")
+const { fakeInbox } = require("./inbox.cjs")
 const { builder } = require("./builders.cjs")
 const { fakeIds, FakeIds } = require("./ids.cjs")
 
 /**
- * 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.
- * The unit run also writes `coverage/lcov.info`: Sonar imports it (`sonar.javascript.lcov.reportPaths`) with the same scope
- * (`sonar.coverage.exclusions` holds every other file, rendered by hfs sync) and its quality gate holds coverage at 100 on those files.
+ * Coverage is measured where logic runs: every file `<name>.<role>.ts` of a LOGIC role (service, policy, projection, guard, mapper, client, ...)
+ * inside the roots the slot manifest marks `coverage: required` (the modules of the back end: domain, integrations, platform, projections).
+ * The features (handlers, resolvers, controllers, consumers, processors, steps, sagas, cli commands) are thin by rule (BE_FEATURE_THIN) and are
+ * never measured. The scope is NOT written here: `starci app sync` renders it from the manifest (scripts/hfs/coverage-scope.mjs) into the repository's
+ * jest.config.js as `starciJestConfig({ coverage: { roots, roles, excludes } })`, and the same derivation renders Sonar's
+ * `sonar.coverage.exclusions` and the Codecov paths and components, so the three can never disagree. Every measured file must reach 100 on every metric.
+ * The unit run also writes `coverage/lcov.info`: Sonar and Codecov import it.
  */
-const COVERAGE_SOURCES = ["src/**/*.service.ts"]
-const COVERAGE_EXCLUDES = ["src/tests/**", "**/dist/**", "**/coverage/**"]
+const COVERAGE_EXCLUDES = ["**/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 glob one measured root stands for: every file of a logic role below it. */
+function rootGlob(root, roles) {
+  return `${root}**/*.${roles.length === 1 ? roles[0] : `{${roles.join(",")}}`}.ts`
+}
+
+/**
+ * jest's `collectCoverageFrom` of a coverage scope `{ roots, roles, excludes }`: the glob of every root, then the none directories inside a
+ * root (`excludes`, each a glob that ends in `**`) and the generated folders as negations.
+ */
+function collectCoverageFrom(coverage) {
+  return [...coverage.roots.map((root) => rootGlob(root, coverage.roles)), ...[...coverage.excludes, ...COVERAGE_EXCLUDES].map((glob) => `!${glob}`)]
 }
 
 /** Sonar `sonar.exclusions`: specs, e2e specs, dist and coverage output are not analysed at all. */
@@ -78,16 +90,16 @@ const underTests = (folder) => String.raw`[\\/]src[\\/]tests[\\/]` + folder + St
 /**
  * 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()`.
+ * `contract` (`src/tests/contract/<provider>/<name>.contract-spec.ts`). It takes ONE option, the coverage scope: the repository's `jest.config.js` is a managed file
+ * (R05), rendered by `starci app sync` as `module.exports = require("@starci/jest-preset").starciJestConfig({ coverage: { roots, roles, excludes } })`, the scope derived from the slot manifest.
  *
  * 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 their spec files one at a time, each in a worker process of its own (`world-runner.cjs`; every file shares the
- * run's data, so the runner never runs two at once); 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
+ * run their spec files up to `min(--maxWorkers, slots)` at once, each in a worker process of its own bound to one data slot
+ * of the test world (`world-runner.cjs`; a slot's data is reset when a file boots, so no two files ever share a slot); the unit project alone has a `setupFilesAfterEnv` (the Outcome matchers).
+ * Coverage is collected from the logic roles of the measured roots only (`coverage` option), with a per-file threshold of 100 on lines, branches, functions and
  * statements: the `test` script runs the unit project with `--coverage`, fails below it and writes `coverage/lcov.info` for Sonar. 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.
  */
@@ -99,7 +111,68 @@ function hasTestWorld(root) {
   return require("node:fs").existsSync(require("node:path").join(root, "src", "tests", "world", "global-setup.ts"))
 }
 
-function starciJestConfig() {
+/** Every alternative a `{a,b}` pattern spells, braces expanded left to right. */
+function braceVariants(value) {
+  const match = /{([^{}]+)}/.exec(value)
+  return match ? match[1].split(",").flatMap((part) => braceVariants(`${value.slice(0, match.index)}${part}${value.slice(match.index + match[0].length)}`)) : [value]
+}
+
+/** The anchored RegExp of one brace-free glob over a posix path: `**` spans directories, `*` and `?` stay inside a segment. */
+function globRegExp(glob) {
+  let source = ""
+  for (let i = 0; i < glob.length; i += 1) {
+    const c = glob[i]
+    if (c === "*" && glob[i + 1] === "*") {
+      i += 1
+      if (glob[i + 1] === "/") {
+        i += 1
+        source += "(?:.*/)?"
+      } else source += ".*"
+    } else if (c === "*") source += "[^/]*"
+    else if (c === "?") source += "[^/]"
+    else source += /[.+^${}()|[\]\\]/.test(c) ? `\\${c}` : c
+  }
+  return new RegExp(`^${source}$`)
+}
+
+/**
+ * True when the repository at `root` holds a file the coverage glob matches: jest refuses a threshold key that matches no covered file,
+ * and a back end may have no file of a measured root yet (no projection, no integration), so a root without files gets no key (its files,
+ * once added, are measured and held at 100 like every other).
+ */
+function hasCoverageSubjects(root, glob) {
+  const fsx = require("node:fs")
+  const pathx = require("node:path")
+  const base = glob.slice(0, Math.max(0, glob.search(/[*?{]/))).replace(/[^/]*$/, "")
+  const patterns = braceVariants(glob).map(globRegExp)
+  const walk = (dir) => {
+    let entries
+    try {
+      entries = fsx.readdirSync(pathx.join(root, dir), { withFileTypes: true })
+    } catch {
+      return false
+    }
+    return entries.some((entry) => {
+      const rel = `${dir}${entry.name}`
+      if (entry.isDirectory()) return !["node_modules", "dist", "coverage"].includes(entry.name) && walk(`${rel}/`)
+      return patterns.some((pattern) => pattern.test(rel))
+    })
+  }
+  return walk(base)
+}
+
+/** The scope `{ roots, roles, excludes }` of an options object, or a refusal: the scope is rendered by `starci app sync`, never defaulted. */
+function coverageOf(options) {
+  const coverage = options?.coverage
+  const list = (value) => Array.isArray(value) && value.every((item) => typeof item === "string" && item.length > 0)
+  if (!coverage || !list(coverage.roots) || !list(coverage.roles) || !coverage.roles.length || !list(coverage.excludes)) {
+    throw new Error("starciJestConfig({ coverage: { roots, roles, excludes } }) needs the coverage scope starci app sync renders from the slot manifest; run \"npx starci app sync --write\"")
+  }
+  return coverage
+}
+
+function starciJestConfig(options) {
+  const coverage = coverageOf(options)
   const shared = {
     preset: "ts-jest",
     testEnvironment: "node",
@@ -122,9 +195,9 @@ function starciJestConfig() {
   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 } },
+    collectCoverageFrom: collectCoverageFrom(coverage),
+    // A glob key is applied to every matching file on its own: each measured file must reach 100, not the average.
+    coverageThreshold: Object.fromEntries(coverage.roots.map((root) => rootGlob(root, coverage.roles)).filter((glob) => hasCoverageSubjects(process.cwd(), glob)).map((glob) => [`./${glob}`, { ...COVERAGE_THRESHOLD }])),
     coverageDirectory: "coverage",
     // lcov is what Sonar imports (coverage/lcov.info); text-summary and text are what the developer reads.
     coverageReporters: ["text-summary", "text", "lcov"],
@@ -158,13 +231,16 @@ module.exports = {
   FakeClock,
   fakeCache,
   fakeLock,
-  recordingOutbox,
+  recordingEventBus,
+  recordingQueueOutbox,
+  fakeInbox,
   builder,
   fakeIds,
   FakeIds,
   collectCoverageFrom,
+  rootGlob,
   sonarExclusions,
-  COVERAGE_SOURCES,
+  hasCoverageSubjects,
   COVERAGE_EXCLUDES,
   COVERAGE_THRESHOLD,
   UNIT_COMPILER_OPTIONS,

package/index.d.ts

@@ -4,18 +4,32 @@ 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 { recordingEventBus, RecordingEventBus } from "./event-bus"
+export { recordingQueueOutbox, RecordingQueueOutbox } from "./queue"
+export { fakeInbox, FakeInbox } from "./inbox"
 export { builder } from "./builders"
 export { FakeClock } from "./clock"
 export { fakeIds, FakeIds } from "./ids"
 export { RefusalReason } from "./matchers"
 
-/** 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
+/** The coverage scope `starci app sync` renders from the slot manifest: the measured roots (a directory pattern per measured slot, a placeholder folder written as a star), the logic roles measured in them and the directories inside a root that are never measured (each ending in a double star). */
+export interface StarciCoverageScope {
+  readonly roots: readonly string[]
+  readonly roles: readonly string[]
+  readonly excludes: readonly string[]
+}
+export interface StarciJestOptions {
+  readonly coverage: StarciCoverageScope
+}
+/** The whole jest config: projects `unit`, `integration`, `e2e` and `contract`. It takes the coverage scope the managed repository config renders; without it it refuses. */
+export declare function starciJestConfig(options: StarciJestOptions): Config
 export declare const MODULE_NAME_MAPPER: Readonly<Record<string, string>>
-export declare function collectCoverageFrom(): string[]
+export declare function collectCoverageFrom(coverage: StarciCoverageScope): string[]
+/** The glob one measured root stands for: every file of a logic role below it. */
+export declare function rootGlob(root: string, roles: readonly string[]): string
+/** True when `root` holds a file the coverage `glob` matches (a threshold key that matches nothing is refused by jest). */
+export declare function hasCoverageSubjects(root: string, glob: string): boolean
 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 }>

package/package.json

@@ -1,8 +1,8 @@
 {
   "name": "@starci/jest-preset",
-  "version": "2.2.3",
-  "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",
+  "version": "2.2.5",
+  "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(), recordingEventBus(), recordingQueueOutbox(), fakeInbox(), FakeClock, fakeIds(), builder() and the Outcome matchers toBeRefused/toSucceedWith.",
+  "license": "MIT",
   "private": false,
   "main": "index.cjs",
   "types": "index.d.ts",
@@ -39,9 +39,17 @@
       "types": "./lock.d.ts",
       "default": "./lock.cjs"
     },
-    "./outbox": {
-      "types": "./outbox.d.ts",
-      "default": "./outbox.cjs"
+    "./event-bus": {
+      "types": "./event-bus.d.ts",
+      "default": "./event-bus.cjs"
+    },
+    "./queue": {
+      "types": "./queue.d.ts",
+      "default": "./queue.cjs"
+    },
+    "./inbox": {
+      "types": "./inbox.d.ts",
+      "default": "./inbox.cjs"
     },
     "./builders": {
       "types": "./builders.d.ts",
@@ -49,6 +57,7 @@
     }
   },
   "files": [
+    "LICENSE",
     "*.cjs",
     "*.d.ts",
     "!*.spec.*",

package/queue.cjs

@@ -0,0 +1,51 @@
+"use strict"
+
+/**
+ * `recordingQueueOutbox()` -- a `QueueOutbox` double that records what a typed queue producer writes, so a spec asserts on `outbox.jobs`.
+ *
+ * `write(tx, queue, payload)` records the job with the manager it was written through. `jobs` is every job in order, `jobsOf(queue)`
+ * the jobs of one queue, and `entries` adds `inTransaction`: whether `tx` was the view a `fakeTransaction` body received, so a spec proves
+ * a job is enqueued in the transaction of the change that needs it. `failNext('write', error)` makes the next write reject once.
+ */
+const { isTransactionManager } = require("./entity-manager.cjs")
+
+function recordingQueueOutbox() {
+  const written = []
+  const failures = new Map()
+  return {
+    async write(tx, queue, payload) {
+      if (failures.has("write")) {
+        const error = failures.get("write")
+        failures.delete("write")
+        throw error
+      }
+      written.push({ queue, payload, tx, inTransaction: isTransactionManager(tx) })
+    },
+    /** Every job written, in order: `{ queue, payload }`. */
+    get jobs() {
+      return written.map(({ queue, payload }) => ({ queue, payload }))
+    },
+    /** Every write with its manager and `inTransaction`. */
+    get entries() {
+      return [...written]
+    },
+    /** The jobs of one queue. */
+    jobsOf(queue) {
+      return this.jobs.filter((job) => job.queue === queue)
+    },
+    /** True when something was written and every write went through a transaction manager. */
+    get allInTransaction() {
+      return written.length > 0 && written.every((entry) => entry.inTransaction)
+    },
+    /** Makes the next write reject with `error`, once. */
+    failNext(operation, error) {
+      failures.set(operation, error)
+    },
+    clear() {
+      written.length = 0
+      failures.clear()
+    },
+  }
+}
+
+module.exports = { recordingQueueOutbox }

package/queue.d.ts

@@ -0,0 +1,26 @@
+/** One recorded job write. */
+export interface QueueWrite {
+  readonly queue: string
+  readonly payload: object
+  readonly tx: unknown
+  /** Whether `tx` was the view a `fakeTransaction` body received. */
+  readonly inTransaction: boolean
+}
+
+/** A `QueueOutbox` double that records the jobs a typed producer writes. */
+export interface RecordingQueueOutbox {
+  write(tx: unknown, queue: string, payload: object): Promise<void>
+  /** Every job written, in order. */
+  readonly jobs: ReadonlyArray<{ readonly queue: string; readonly payload: object }>
+  /** Every write with its manager. */
+  readonly entries: ReadonlyArray<QueueWrite>
+  jobsOf(queue: string): ReadonlyArray<{ readonly queue: string; readonly payload: object }>
+  /** True when something was written and every write went through a `fakeTransaction` manager. */
+  readonly allInTransaction: boolean
+  /** Makes the next write reject with `error`, once. */
+  failNext(operation: "write", error: Error): void
+  clear(): void
+}
+
+/** The queue outbox double. */
+export declare function recordingQueueOutbox(): RecordingQueueOutbox

package/world-runner.cjs

@@ -1,29 +1,76 @@
 "use strict"
 
 /**
- * The runner of the integration, e2e and contract projects: every spec file runs in a process of its own.
+ * The runner of the integration, e2e and contract projects: every spec file runs in a process of its own, bound to one data
+ * slot of the test world.
  *
- * Why: jest runs a file in a fresh vm context, but a context still reaches the globals of the process that hosts it, and
- * jest-environment-node exposes every global the host process had when the environment loaded. The test world's globalSetup
- * runs in jest's main process and loads application code there (the migrate step and its modules), so a framework that keeps
- * its registry on a process global (`@nestjs/graphql` keeps `GqlTypeMetadataStorage` on `global`) leaks it into every file
- * jest runs in that process; and a worker that runs several files carries whatever the first one left on its own global. In
- * one `npm run test:e2e` the second file then fails to boot with "Cannot determine a GraphQL output type". Resetting the
- * framework's storage would chase one framework at a time; a process per file isolates every one of them.
+ * Why a process per file: jest runs a file in a fresh vm context, but a context still reaches the globals of the process that
+ * hosts it, and jest-environment-node exposes every global the host process had when the environment loaded. The test world's
+ * globalSetup runs in jest's main process and loads application code there (the migrate step and its modules), so a framework
+ * that keeps its registry on a process global (`@nestjs/graphql` keeps `GqlTypeMetadataStorage` on `global`) leaks it into
+ * every file jest runs in that process; and a worker that runs several files carries whatever the first one left on its own
+ * global. A process per file isolates every framework at once.
  *
- * How: the stock jest-runner, driven one file at a time with a single-worker farm (`maxWorkers: 1` per file), which forks a
- * fresh child, runs the file there and ends the child. Never in band, even when jest would choose it (one worker, one test,
- * `--runInBand`): the main process holds the globalSetup's state.
+ * Why slots: the test world resets a slot's data (its databases, realm users, Redis DB, buckets and fakes) when a file boots,
+ * so two files must never share a slot at the same time. The globalSetup of `@starci/test-world` provisions N slots, each a
+ * complete, independent set of data namespaces, and publishes them in its state file (`STARCI_TEST_WORLD_STATE`, protocol
+ * {@link WORLD_STATE_VERSION}). The runner runs up to `min(--maxWorkers, N)` files at once and gives each a free slot: the
+ * file's process is forked with `STARCI_TEST_WORLD_SLOT=<k>`; the slot goes back to the pool when the file ends.
  *
- * ONE FILE AT A TIME, whatever `--maxWorkers` says: every file of a run shares the run's data (the test world resets the run's
- * databases, realm users, Redis DB and fakes when a file boots), so a second file running beside the first would wipe what the
- * first is using. The runner enforces it, so no flag or script can turn it off. Per-worker data namespaces are the known
- * limitation that lifts it (see CHANGELOG 2.2.0).
+ * How: the stock jest-runner, driven one file at a time per slot with a single-worker farm (`maxWorkers: 1` per file), which
+ * forks a fresh child, runs the file there and ends the child. jest-worker forks in the farm's constructor, which jest-runner
+ * calls before its first `await`, so the slot variable is set on `process.env` only for that synchronous span. Never in band,
+ * even when jest would choose it (`--runInBand`): the main process holds the globalSetup's state.
+ *
+ * The pair is exact: this runner reads protocol {@link WORLD_STATE_VERSION} only. Any other state file is the wrong
+ * `@starci/test-world` beside this preset, a typed failure naming both versions (re-pin both per canon-pins), never a fallback.
  */
 
 const { createRequire } = require("node:module")
+const fs = require("node:fs")
 const path = require("node:path")
 
+/** The state-file protocol of `@starci/test-world` this runner speaks (test-world 1.1.x). */
+const WORLD_STATE_VERSION = 2
+/** The variable that carries the path of the world's state file (set by its globalSetup in this process). */
+const STATE_FILE_ENV = "STARCI_TEST_WORLD_STATE"
+/** The variable that tells a file's process which slot it owns (1-based). */
+const SLOT_ENV = "STARCI_TEST_WORLD_SLOT"
+/** The failure code of a state file this runner cannot drive. */
+const WORLD_PAIR_MISMATCH = "JEST_PRESET_WORLD_PAIR_MISMATCH"
+
+const PRESET = (() => {
+  const own = JSON.parse(fs.readFileSync(path.join(__dirname, "package.json"), "utf8"))
+  return `${own.name}@${own.version}`
+})()
+
+/** A typed failure of the runner: `code` names it, the message says what to do. */
+function runnerError(code, detail) {
+  const error = new Error(`${code}: ${detail}`)
+  error.code = code
+  return error
+}
+
+/** The slot count the world published; a missing or foreign state file is a pair mismatch. */
+function worldSlots(env = process.env) {
+  const file = env[STATE_FILE_ENV]
+  const fix = `pin @starci/test-world and @starci/jest-preset together as knowledge/hfs/canon-pins.yaml pairs them (${PRESET} speaks state protocol ${WORLD_STATE_VERSION}, @starci/test-world 1.1.x)`
+  if (file === undefined || file === "") {
+    throw runnerError(WORLD_PAIR_MISMATCH, `${STATE_FILE_ENV} is not set: the world's globalSetup published no state file for ${PRESET}; ${fix}`)
+  }
+  let state
+  try {
+    state = JSON.parse(fs.readFileSync(file, "utf8"))
+  } catch (cause) {
+    throw runnerError(WORLD_PAIR_MISMATCH, `the world state file ${file} cannot be read (${cause instanceof Error ? cause.message : String(cause)}); ${fix}`)
+  }
+  const library = typeof state?.library === "string" ? state.library : "@starci/test-world before 1.1.0"
+  if (state?.version !== WORLD_STATE_VERSION || !Array.isArray(state.slots) || state.slots.length < 1) {
+    throw runnerError(WORLD_PAIR_MISMATCH, `${library} wrote state protocol ${String(state?.version)}, ${PRESET} needs ${WORLD_STATE_VERSION}; ${fix}`)
+  }
+  return state.slots.length
+}
+
 /**
  * The stock jest-runner of the jest that loads this preset: resolved through jest's own dependency chain
  * (jest -> @jest/core -> jest-runner) from the repository root, so the runner always matches the running jest.
@@ -50,20 +97,46 @@ class WorldRunner extends StockRunner {
     }
   }
 
-  /** Runs the files one after another, each in a fresh worker process; `--maxWorkers` and `serial` (in band) are never honoured. */
+  /** Runs the files up to `min(--maxWorkers, slots)` at once, each in a fresh process bound to a free slot; never in band. */
   async runTests(tests, watcher) {
-    const perFile = { ...this._globalConfig, maxWorkers: 1 }
-    for (const test of tests) {
-      if (watcher.isInterrupted()) return
-      const runner = new StockRunner(perFile, this._context)
-      const unsubscribe = this.#listeners.map(({ eventName, listener }) => runner.on(eventName, listener))
-      try {
-        await runner.runTests([test], watcher, { serial: false })
-      } finally {
-        for (const stop of unsubscribe) stop()
+    const slots = worldSlots()
+    const width = Math.max(1, Math.min(this._globalConfig.maxWorkers ?? 1, slots))
+    const queue = [...tests]
+    // one lane per slot: a lane owns its slot for the whole run and takes the next file when its current one ends
+    const lane = async (slot) => {
+      for (let test = queue.shift(); test !== undefined; test = queue.shift()) {
+        if (watcher.isInterrupted()) return
+        await this.#runOne(test, watcher, slot)
       }
     }
+    await Promise.all(Array.from({ length: Math.min(width, tests.length) }, (_, index) => lane(index + 1)))
+  }
+
+  /** One file in a fresh single-worker farm whose child is forked with the slot in its environment. */
+  async #runOne(test, watcher, slot) {
+    const runner = new StockRunner({ ...this._globalConfig, maxWorkers: 1 }, this._context)
+    const unsubscribe = this.#listeners.map(({ eventName, listener }) => runner.on(eventName, listener))
+    const before = process.env[SLOT_ENV]
+    let running
+    process.env[SLOT_ENV] = String(slot)
+    try {
+      // the farm (and its child) is created synchronously inside this call, before jest-runner's first await
+      running = runner.runTests([test], watcher, { serial: false })
+    } finally {
+      if (before === undefined) delete process.env[SLOT_ENV]
+      else process.env[SLOT_ENV] = before
+    }
+    try {
+      await running
+    } finally {
+      for (const stop of unsubscribe) stop()
+    }
   }
 }
 
+WorldRunner.WORLD_STATE_VERSION = WORLD_STATE_VERSION
+WorldRunner.SLOT_ENV = SLOT_ENV
+WorldRunner.WORLD_PAIR_MISMATCH = WORLD_PAIR_MISMATCH
+WorldRunner.worldSlots = worldSlots
+
 module.exports = WorldRunner

package/outbox.cjs

@@ -1,125 +0,0 @@
-"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.
- *
- * The claim side scripts what a worker's claim returns. `queueRecords(...records)` fills the backlog; `claimDue(params)` hands
- * out, in order, up to `params.limit` backlog records whose queue is in `params.queues` and removes them, so an empty backlog is
- * an empty claim and queueing the same record twice is a duplicate delivery. `claims` keeps every claim's params, `completed`,
- * `retried` and `buried` keep what the worker reported, and `failNext(operation, error)` makes the next call of that operation
- * reject once, so a spec drives the failure path.
- */
-const { isTransactionManager } = require("./entity-manager.cjs")
-
-function recordingOutbox() {
-  const written = []
-  const backlog = []
-  const claims = []
-  const completed = []
-  const retried = []
-  const buried = []
-  const failures = new Map()
-  const failIfScripted = (operation) => {
-    if (!failures.has(operation)) return
-    const error = failures.get(operation)
-    failures.delete(operation)
-    throw error
-  }
-  return {
-    async enqueue(manager, message) {
-      failIfScripted("enqueue")
-      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)
-    },
-    /** Adds records to the backlog `claimDue` hands out. */
-    queueRecords(...records) {
-      backlog.push(...records)
-    },
-    async claimDue(params) {
-      claims.push(params)
-      failIfScripted("claimDue")
-      const claimed = []
-      for (const record of [...backlog]) {
-        if (claimed.length >= params.limit) break
-        if (!params.queues.includes(record.queue)) continue
-        claimed.push(record)
-        backlog.splice(backlog.indexOf(record), 1)
-      }
-      return claimed
-    },
-    async complete(id) {
-      failIfScripted("complete")
-      completed.push(id)
-    },
-    async retry(params) {
-      failIfScripted("retry")
-      retried.push(params)
-    },
-    async bury(params) {
-      failIfScripted("bury")
-      buried.push(params)
-    },
-    /** Makes the next call of `operation` reject with `error`, once. */
-    failNext(operation, error) {
-      failures.set(operation, error)
-    },
-    /** The params of every `claimDue` call, in order. */
-    get claims() {
-      return [...claims]
-    },
-    /** The ids passed to `complete`, in order. */
-    get completed() {
-      return [...completed]
-    },
-    /** The params of every `retry`, in order. */
-    get retried() {
-      return [...retried]
-    },
-    /** The params of every `bury`, in order. */
-    get buried() {
-      return [...buried]
-    },
-    /** The records still waiting for a claim. */
-    get backlog() {
-      return [...backlog]
-    },
-    clear() {
-      for (const list of [written, backlog, claims, completed, retried, buried]) list.length = 0
-      failures.clear()
-    },
-  }
-}
-
-module.exports = { recordingOutbox }

package/outbox.d.ts

@@ -1,79 +0,0 @@
-/** 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
-}
-/** A message a worker has claimed, as the outbox port returns it. */
-export interface ClaimedRecord {
-  readonly id: string
-  readonly queue: string
-  readonly eventId: string
-  readonly payload: unknown
-  readonly attempts: number
-}
-/** What a worker asks for when it claims due messages. */
-export interface ClaimParams {
-  readonly at: Date
-  readonly queues: ReadonlyArray<string>
-  readonly limit: number
-  readonly visibilityMs: number
-}
-/** What a worker reports when a delivery failed and should be tried again. */
-export interface RetryParams {
-  readonly id: string
-  readonly at: Date
-  readonly error: string
-}
-/** What a worker reports when a message will not be delivered any more. */
-export interface BuryParams {
-  readonly id: string
-  readonly error: string
-}
-/** The outbox operations `failNext` can make reject. */
-export type OutboxOperation = "enqueue" | "claimDue" | "complete" | "retry" | "bury"
-
-/** An outbox double that records writes and scripts the claim side. */
-export interface RecordingOutbox<M extends RecordedMessage = RecordedMessage, R extends ClaimedRecord = ClaimedRecord> {
-  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>
-  /** Adds records to the backlog `claimDue` hands out; the same record twice is a duplicate delivery. */
-  queueRecords(...records: ReadonlyArray<R>): void
-  /** Hands out, in order, up to `limit` backlog records of the asked queues and removes them; an empty backlog is an empty claim. */
-  claimDue(params: ClaimParams): Promise<Array<R>>
-  complete(id: string): Promise<void>
-  retry(params: RetryParams): Promise<void>
-  bury(params: BuryParams): Promise<void>
-  /** Makes the next call of `operation` reject with `error`, once. */
-  failNext(operation: OutboxOperation, error: Error): void
-  /** The params of every `claimDue` call. */
-  readonly claims: ReadonlyArray<ClaimParams>
-  /** The ids passed to `complete`. */
-  readonly completed: ReadonlyArray<string>
-  /** The params of every `retry`. */
-  readonly retried: ReadonlyArray<RetryParams>
-  /** The params of every `bury`. */
-  readonly buried: ReadonlyArray<BuryParams>
-  /** The records still waiting for a claim. */
-  readonly backlog: ReadonlyArray<R>
-  clear(): void
-}
-
-/** The outbox double. */
-export declare function recordingOutbox<M extends RecordedMessage = RecordedMessage, R extends ClaimedRecord = ClaimedRecord>(): RecordingOutbox<M, R>