@lenne.tech/nest-server 11.36.1 → 11.36.2

package/.claude/rules/testing.md

@@ -233,10 +233,33 @@ pnpm run check:mutations                    # apply every registered mutation, r
 pnpm run check:mutations -- --id=<id>       # one mutation
 pnpm run check:mutations -- --list          # the registry, without running anything
 pnpm run check:mutations -- --allow-dirty   # when the fix and its evidence share a working tree
+pnpm run check:mutations -- --jobs=4        # N mutations at a time (default: 2, or 4 on >=12 cores)
 ```
 
 Not part of `pnpm run check` — it edits source and re-runs whole e2e suites. It belongs in review
-and on the publish path. Between runs the registry is kept from rotting by
+and on the publish path.
+
+### The cost is vitest's cold start, not the tests
+
+Worth knowing before optimising the wrong thing: the specs behind all 29 e2e mutations add up to
+**~40 seconds**. The step takes ~740s. The remaining ~700s is paying vitest's startup — process
+spawn, transform, module graph, mongod connect, DB create and drop — once per mutation, 49 times.
+That work is largely single-threaded I/O and barely scales with cores: the full registry measures
+**744s on a 12-core laptop and 777s on a 4-vCPU CI runner**.
+
+So it parallelises well, and `--jobs` does exactly that: **744s → 399s (1.87×) at 4 jobs**. Verified
+by diffing all 49 verdicts against a sequential run — a parallel mode that changes a verdict is not
+an optimisation, it is a broken safety net.
+
+**A mutation writes into the source tree**, which is why N cannot simply run at once: two mutations
+in one tree would see each other's edits and the specs would answer about a source state nobody
+registered. Each worker therefore gets its own `git worktree`, with `node_modules` symlinked from
+the main checkout (pnpm's internal links are relative, so one symlink serves every worktree).
+
+That isolation has a consequence: a worktree is at **HEAD**, so parallel mode tests COMMITTED code.
+When `src/` or `tests/` is dirty — or `--allow-dirty` is passed — the run says so and falls back to
+sequential. A fast answer about the wrong source is worse than a slow answer about the right one.
+`tests/unit/mutation-jobs-planning.spec.ts` pins that decision. Between runs the registry is kept from rotting by
 `tests/unit/regression-evidence.spec.ts`, which asserts every `find` still matches its target
 **exactly once**: a stale mutation would silently become a no-op, and a no-op "confirms" evidence
 that was never checked.

package/FRAMEWORK-API.md

@@ -1,6 +1,6 @@
 # @lenne.tech/nest-server — Framework API Reference
 
-> Auto-generated from source code on 2026-08-22 (v11.36.1)
+> Auto-generated from source code on 2026-08-22 (v11.36.2)
 > File: `FRAMEWORK-API.md` — compact, machine-readable API surface for Claude Code
 
 ## CoreModule.forRoot()

package/migration-guides/11.36.1-to-11.36.2.md

@@ -0,0 +1,67 @@
+# Migration Guide: 11.36.1 → 11.36.2
+
+## Overview
+
+| Category | Details |
+|----------|---------|
+| **Breaking Changes** | None |
+| **New Features** | `check:mutations --jobs=N` — the regression-evidence gate now runs several mutations at once (§1) |
+| **Bugfixes** | None affecting runtime |
+| **Migration Effort** | **None.** Tooling-only release; nothing in `src/` changed |
+
+---
+
+## Quick Migration
+
+```bash
+pnpm update @lenne.tech/nest-server@11.36.2
+```
+
+That is the whole migration. This release changes no framework code, no configuration and no public
+API — `src/` is untouched. It is published so consuming projects stay on a current version and pick
+up the maintenance below.
+
+---
+
+## 1. Faster regression-evidence gate (framework repo only)
+
+Relevant if you run `pnpm run check:mutations`, or maintain a fork of this repo's tooling.
+
+`scripts/check-mutations.mjs` can now run several mutations in parallel:
+
+```bash
+pnpm run check:mutations                # auto: 2 workers, or 4 on a machine with >= 12 cores
+pnpm run check:mutations -- --jobs=4    # explicit
+pnpm run check:mutations -- --jobs=1    # force the previous sequential behaviour
+```
+
+**Measured: 744s → 399s (1.87×) at 4 jobs.** All 49 verdicts were diffed against a sequential run
+and are identical — a parallel mode that changes a verdict is a broken safety net, not a speedup.
+
+**Why it was slow in the first place, since it is easy to optimise the wrong thing:** the specs
+behind all 29 e2e mutations add up to about 40 seconds. The rest is paying vitest's cold start once
+per mutation, 49 times. That work is largely single-threaded I/O and barely scales with cores — the
+registry measures 744s on a 12-core laptop and 777s on a 4-vCPU CI runner.
+
+**How the isolation works.** A mutation writes into the source tree, so N cannot simply run at once:
+two mutations in one tree would see each other's edits. Each worker gets its own `git worktree`, with
+`node_modules` symlinked from the main checkout. A worktree is checked out at **HEAD**, so parallel
+mode tests committed code — when `src/` or `tests/` is dirty, or `--allow-dirty` is passed, the run
+prints why and falls back to sequential.
+
+---
+
+## 2. Dependency maintenance
+
+`@vitest/ui` was removed: no script passes `--ui` and no config imports it. Development-only, no
+runtime effect.
+
+---
+
+## Troubleshooting
+
+| Symptom | Cause | Fix |
+|---------|-------|-----|
+| `check:mutations` prints "(sequential: …)" | `src/` or `tests/` is dirty, or `--allow-dirty` was passed | Intended — a worktree at HEAD would test different code. Commit or stash to get the fast path |
+| `check:mutations` seems slower than before | More workers than cores helps nothing; each worker starts a vitest that forks again | Lower `--jobs`, or leave it unset and let it size itself |
+| A stale worktree is left behind | The run was killed with SIGKILL | `git worktree prune` |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lenne.tech/nest-server",
-  "version": "11.36.1",
+  "version": "11.36.2",
   "description": "Modern, fast, powerful Node.js web framework in TypeScript based on Nest with a GraphQL API and a connection to MongoDB (or other databases).",
   "keywords": [
     "node",
@@ -185,7 +185,6 @@
     "@types/nodemailer": "8.0.1",
     "@types/passport": "1.0.17",
     "@vitest/coverage-v8": "4.1.11",
-    "@vitest/ui": "4.1.11",
     "ansi-colors": "4.1.3",
     "bullmq": "6.2.0",
     "find-file-up": "2.0.1",