@lenne.tech/nest-server 11.43.2 → 12.0.0

package/.claude/rules/architecture.md

@@ -76,6 +76,88 @@ consumer follows. See `.claude/rules/configurable-features.md` for the full opti
 - `CheckResponseInterceptor` - Filters restricted fields
 - `CheckSecurityInterceptor` - Processes `securityCheck()` methods
 
+## Module Format: an ESM package whose source is valid as CommonJS AND ESM (12.0.0+)
+
+All NestJS 12 packages are ESM-only, and so is this one since 12.0.0: `package.json` declares `"type": "module"`,
+`dist/` is one ESM build. A CommonJS project loads it through Node's `require(esm)` (Node 20.19+ / 22.12+;
+`engines.node` is `>= 22.15`) exactly as it loads every `@nestjs/*` package — verified against the unchanged
+nest-server-starter (type check, all tests, build, `migrate:list`, production start). `tsconfig.json` uses `module` /
+`moduleResolution: nodenext`, so `tsc` resolves exactly like Node, `exports` maps included, plus `isolatedModules`
+(NestJS 12's default; SWC compiles one file at a time anyway).
+
+**`require()` of the package must keep working, so the package must never contain top-level `await`** —
+`require(esm)` refuses a graph with it (`ERR_REQUIRE_ASYNC_MODULE`), and every CommonJS project would stop loading.
+
+**Two contracts stay CommonJS, through a directory-level `package.json` with `"type": "commonjs"`:**
+`src/core/modules/migrate/helpers/` (the TypeScript loader `ts-compiler.js`, whose path and function export every
+project's `--compiler ts:…` and `node -r …` name) and `bin/` (`bin/migrate.js`, the `migrate` binary). Both
+`package.json` files reach `dist/` and vendor projects like any other file, so the contracts hold in CommonJS and ESM
+projects alike.
+
+**No CommonJS module may sit inside the core's ES module graph and load other core modules.** Found the hard way:
+with `migration.helper.ts` compiled as CommonJS in `helpers/` and imported by the barrel, `require('@lenne.tech/nest-server')`
+returned the helper's exports instead of the barrel's — Node mixed up the module objects while a CommonJS module
+required ES modules of the graph it was being loaded for. The helper therefore lives in `migrate/migration.helper.ts`
+(ESM like the rest); `helpers/migration.helper.ts` is a CommonJS forwarder for the path existing
+`migrations-utils/migrate.js` files require, and nothing in the core imports it.
+
+**Enforced in three places, because vitest sees none of it** (it imports sources through its own module runner):
+`tests/unit/module-format-invariants.spec.ts` refuses a runtime import from a CommonJS directory into the graph and any
+top-level `await` (mutation `barrel-imports-cjs-forwarder`); `tests/unit/package-format-contracts.spec.ts` loads
+`bin/migrate.js`, the loader and the forwarder in place, in a child process, and checks that every CommonJS `.js` file
+sits in a CommonJS scope and that nest-cli copies the nested manifests into `dist/` (mutations
+`bin-manifest-type-module`, `nest-cli-assets-drop-json`, `migration-helper-forwarder-emptied`); and
+`pnpm run check:manifest` (after the build in `check`) does the same against the PACKED package, plus `require()` vs
+`import()` of `dist/index.js` in two fresh processes — the export lists must match.
+
+The **source** of `src/core/` must additionally be valid as **ESM**, because a vendor-mode project may be an ESM
+project (`"type": "module"`, what `nest new` generates since NestJS 12) and then compiles and runs the vendored core as
+ESM. Rules for code in `src/core/`, `src/index.ts`, `src/core.module.ts` and `src/test/`:
+
+| Rule | Why |
+|------|-----|
+| Relative specifiers name the emitted file: `./x.js`, `./dir/index.js` — never `./x` or `./dir` | ESM resolves no extension and no directory. `tsc` under `nodenext` keeps the specifier as written; the SWC loader and vitest map `.js` to `.ts` in a source run |
+| No `require()`, `__dirname` / `__filename`, `import x = require()`, `export =` (CommonJS only) and no `import.meta` (ESM only). Use static imports, `createRequire(join(process.cwd(), 'package.json'))` to load a PROJECT file, `callerDirectory()` (`common/helpers/module-location.helper.ts`) for "the directory of this file" | each of them fails in the other module system — inside a function only when it runs. Enforced by `tests/unit/module-format-invariants.spec.ts` (mutation `core-uses-dirname`), because `check:esm` sees only what fails while a module LOADS |
+| A CommonJS package without `__esModule` is a DEFAULT import (`import _ from 'lodash'`), one WITH it (graphql) a named or namespace import. Never a named import Node cannot see (`import { cloneDeep } from 'lodash'`, mongoose's `Connection` as a value) | ESM gets a CommonJS module's names from `cjs-module-lexer`, which misses lodash's and mongoose's. Under CommonJS the same line works, so only `pnpm run check:esm` notices |
+| `import type` for types — also in decorated signatures; `export type` for re-exported types | `isolatedModules` (TS1272 / TS1205): a value import of a type links under CommonJS and fails under ESM |
+| A cycle that forces laziness is broken with an import-free leaf, never with a lazy `require()` | `core-better-auth.registry.ts` → `isBetterAuthHandlerClass()` is how the tenant guard recognises the IAM handlers |
+| No deep imports into `@nestjs/*` packages whose `exports` map lists only the root (`jwt`, `mongoose`, `passport`, `schedule`, `swagger`, `terminus`) | `ERR_PACKAGE_PATH_NOT_EXPORTED` at runtime, `TS2307` at compile time. `@nestjs/common`, `core`, `platform-express` and `graphql` export `./*`, so their subpaths still resolve |
+| No relative dynamic `import()` at all | under `nodenext` a dynamic `import()` in CommonJS output stays a NATIVE `import()` and follows ESM resolution, while a source run in a CommonJS project turns it into `require()`. vitest accepts both, so only `tests/unit/module-format-invariants.spec.ts` sees it — the 12.0.0 migration runner shipped `await import('./helpers/migration.helper.js')` with every suite green |
+| A dual package (separate CJS and ESM builds — `@aws-sdk/*`, `@modelcontextprotocol/sdk`, `@getbrevo/brevo`, `bullmq`) is either lazy everywhere or static everywhere | a native `import()` loads the ESM build, a static import the CJS build — two module instances, and an `instanceof` across them fails. Take its types from the import EXPRESSION (`const load = () => import('x'); type X = Awaited<ReturnType<typeof load>>`), never from an `import type`: TypeScript types an `import()` the way it is emitted (ESM under `nodenext`, CJS under `module: commonjs`), while any fixed `import type` matches only one of the two (TS2322 in the other). And keep such a derived CLASS type out of public/protected signatures — under `module: commonjs` with declarations it cannot be named (TS2883); give the extension point a structural interface instead (`IBrevoSdkClient`) |
+| Write code that compiles under BOTH `nodenext` and `module: commonjs` | vendor consumers compile `src/core/` with their own tsconfig. Under TypeScript 6, `module: commonjs` without `moduleResolution` resolves as `bundler` and keeps the `require()` emit for `import()`. Enforced by `pnpm run typecheck:vendor` (`scripts/check-vendor-declarations.mjs` + `tsconfig.vendor-commonjs.json`, part of `check`): it compiles under `module: commonjs`, emits the declarations and fails on `typeof import("<package>")` or `import("<pkg>/…/dist/…")` in them — references that resolve in this repo's HOISTED `node_modules` and break in a consumer's isolated pnpm layout (TS2883). The nodenext build alone passed three 12.0.0 errors that only a vendor project saw |
+
+**`pnpm run check:esm`** (`scripts/check-esm-core.mjs`, part of `check`) is the proof of the ESM half: it copies what a
+vendor project receives into a temporary `"type": "module"` package, compiles it with `nodenext` and imports EVERY
+module plus the barrel in one process. It catches what no other step can — a named import Node cannot see, a type
+imported as a value, a missing extension — and reports each distinct cause once.
+
+**The TypeScript loader is three files.** `helpers/ts-compiler.cjs` is the implementation, `ts-compiler-hooks.mjs` the
+ESM hooks it registers through `module.register()` (resolve `.js` → `.ts`, compile ESM-scoped `.ts` with SWC — import
+attributes kept — and hand CommonJS-scoped files back), and `ts-compiler.js` the established entry path, a one-line
+CommonJS shim that `helpers/package.json` keeps CommonJS in every project. The SWC build (`check:swc-tdz`) does not
+emit `.cjs` / `.mjs` sources; its guard places them like `tsc` does. That guard also pins the SWC build to CommonJS
+(`tsconfig.swc-tdz.json`), because it checks what a CommonJS project runs under `nest start -b swc`; `@nestjs/cli` would
+otherwise emit ES modules for this `"type": "module"` package.
+
+**The build `target` stays `es2022`**, although NestJS 12's template uses `ES2023`: a vendor project compiles the core
+with its own lib, and the starter's is es2022 — see `tests/unit/toolchain-contract.spec.ts`. ES2023 changes no emitted
+syntax on Node 22, only which APIs the type-checker allows.
+
+**Type-aware lint.** `pnpm run lint` runs `oxlint --type-aware` (needs `oxlint-tsgolint`) with
+`typescript/no-floating-promises` as an error, as NestJS 12's template does: an un-awaited promise's rejection is
+unhandled, and Node ends the process on that by default. Mark a deliberate fire-and-forget with `void` and say why it
+cannot reject. The other type-aware rules the categories would turn on are switched off in `.oxlintrc.json`, each
+with the reason; `tests/unit/lint-type-aware.spec.ts` pins the flag, the backend and the rule, because without either
+half oxlint skips the rule silently.
+
+The SWC build (`nest start -b swc`, `check:swc-tdz`), the SWC source loader and vitest transform `import()`
+themselves; none of them is affected by the tsconfig's `module` setting. `tsconfig.tests.json` uses
+`module: preserve` + `moduleResolution: bundler` because that is how vitest resolves the specs. **Both vitest configs
+set `resolve.extensions` in Node's order** (`.js` before `.mjs`): graphql declares an extensionless `main` next to an
+`index.mjs`, Vite probes `.mjs` first, and an `import` of graphql then loaded a second, ESM copy — every subscription
+closed with 4500 ("Cannot use GraphQLSchema from another module or realm"). Pinned by
+`tests/unit/vitest-node-resolution.spec.ts`. Background: `migration-guides/11.43.x-to-12.0.x.md` §2–§3 and §17.
+
 ## DI Token Placement (SWC-Safe)
 
 **Rule: DI tokens belong in an import-free leaf file (`*.constants.ts` / `*.enums.ts`) — never in `*.module.ts` or `*.service.ts`.**

package/.claude/rules/module-deprecation.md

@@ -4,7 +4,7 @@ This document describes the deprecation strategy for Legacy Auth and the migrati
 
 ## Authentication System Roadmap
 
-### v11.x (Current - Backward Compatible)
+### v11.x – v12.x (Current - Backward Compatible)
 
 - **Legacy Auth** (CoreAuthService) is available for backwards compatibility
 - **BetterAuth** (IAM) can run standalone or alongside Legacy Auth
@@ -228,7 +228,8 @@ both Legacy Auth and BetterAuth transparently.
 | Version | Status | Changes |
 |---------|--------|---------|
 | v11.6.x | Released | BetterAuth introduced |
-| v11.7.x | Current | Legacy endpoint controls, IAuthProvider, migration status |
+| v11.7.x | Released | Legacy endpoint controls, IAuthProvider, migration status |
+| v12.0.x | Current | NestJS 12 — Legacy Auth unchanged, still available alongside IAM |
 | Future | Planned | BetterAuth default, simplified API, Legacy optional |
 
 ## Related Documentation

package/.claude/rules/package-management.md

@@ -169,11 +169,18 @@ Two ordering rules, both enforced by the contract test:
 Package overrides live in the `overrides:` section of **`pnpm-workspace.yaml`** (they moved out of `package.json`'s `pnpm.overrides` in the pnpm 11 upgrade). They force transitive dependencies to a security-patched version.
 
 **Keep the set minimal.** On the pnpm 11 upgrade the list was pruned from 36 to the 9 then still
-load-bearing (it has since grown back to 20, mostly as new advisories landed) — an override is only necessary if removing it lets the package resolve back INTO its vulnerable range (verify with a with/without lockfile diff; `pnpm audit` is the arbiter). Each surviving entry carries its CVE rationale as a comment. Remove an entry once its parent dependency ships a fixed version.
-
-**The one exception is a peer conflict nobody downstream can fix.** `'@nestjs/cli>webpack'` (added
-2026-10-20) carries no advisory: @nestjs/cli exact-pins a webpack that a newer transitive
-`schema-utils` refuses as a peer, so every fresh resolve fails `pnpm peers check`. Such an entry
+load-bearing (it has since grown back to as many as 20, mostly as new advisories landed). On
+2026-10-24 (nest-server 12.0.0) two fresh resolves showed that 16 of the remaining 18 changed nothing,
+and they were removed: **two entries remain** (`@graphql-tools/utils`, `multer`), both on an upstream
+EXACT pin with an open advisory. An override is only necessary if removing it lets the package resolve
+back INTO its vulnerable range (verify with a with/without lockfile diff; `pnpm audit` is the arbiter).
+"Cheap insurance against a parent re-pinning downwards" is not a reason to keep one: `pnpm audit` and
+`check:overrides` run on every `check` and report such a regression the day it happens. Each surviving entry carries its CVE rationale as a comment. Remove an entry once its parent dependency ships a fixed version.
+
+**The one exception is a peer conflict nobody downstream can fix.** `'@nestjs/cli>webpack'`
+(2026-10-20 until the move to @nestjs/cli 12 in nest-server 12.0.0, where webpack became an optional
+peer) carried no advisory: @nestjs/cli 11 exact-pinned a webpack that a newer transitive
+`schema-utils` refused as a peer, so every fresh resolve failed `pnpm peers check`. Such an entry
 is parent-scoped (`parent>child`), so only the stale pin moves, and it states the release that
 lets it go. For such an entry `pnpm peers check` is the arbiter, not `pnpm audit`.
 
@@ -256,9 +263,9 @@ from a casual read.
 
 **How to spot both — and the check that does NOT work.** "The same package appears twice under
 `overrides:`" is the obvious heuristic and it is wrong: several packages legitimately need one entry
-per major, because different majors coexist in the tree. This repo has three `brace-expansion`
-entries (1.x, 2.x, 5.x) and two for `js-yaml` (4.x, 5.x), all correct. Flagging those trains the
-reader to ignore the check.
+per major, because different majors coexist in the tree. This repo carried three `brace-expansion`
+entries (1.x, 2.x, 5.x) and two for `js-yaml` (4.x, 5.x) until 12.0.0, all correct. Flagging those
+trains the reader to ignore the check.
 
 The reliable tells are narrower:
 
@@ -401,12 +408,16 @@ plus one for the opposite failure, a guard that rejects a declaration which is s
 matters just as much: a check that cries wolf on correct entries is a check that gets switched off,
 which is how the hole this feature closes came about in the first place.
 
-**Current entry (since 2026-10-11):** `GHSA-vfj7-8cjw-p6xm` (braces, via nodemon / npm-watch), a
-dev-tooling-only path of an advisory with no patched release at all; the justification sits next to
-the entry in `pnpm-workspace.yaml`. **Do not copy it into nest-server-starter without thinking it
-through:** since lt CLI 1.42.0 the starter's `auditConfig` is hoisted as a union into every
-generated project, so an entry there hides the advisory in every customer workspace — including
-production paths this repository does not have.
+**No current entry (since 2026-10-24).** `GHSA-vfj7-8cjw-p6xm` (braces, via nodemon / npm-watch) was
+listed from 2026-10-11 to 2026-10-24: a dev-tooling-only path of an advisory with no patched release
+at all. GitHub withdrew the advisory on 2026-10-23, and `check:overrides` reported the entry as
+obsolete on the next run — the guard doing exactly its job, since a withdrawal changes nothing in
+this repository and `pnpm audit` simply stops mentioning it. The entry and its scope guard in
+`tests/unit/audit-suppression-scope.spec.ts` left together; the history is in git (the comment
+block above `ignoreGhsas` in `pnpm-workspace.yaml` before 12.0.0). **Before adding an entry, and before copying one into
+nest-server-starter:** since lt CLI 1.42.0 the starter's `auditConfig` is hoisted as a union into
+every generated project, so an entry there hides the advisory in every customer workspace —
+including production paths this repository does not have.
 
 **An entry whose package has left the declared range goes, even when the new version is no fix.**
 `GHSA-ch52-4w7c-c8xp` (http-cache-semantics `<= 4.2.0`) was listed from 2026-10-03 to 2026-10-11.
@@ -414,7 +425,7 @@ production paths this repository does not have.
 as "up to the newest release" and never followed. On 4.3.0 the suppression hid nothing and would
 have swallowed a range extension unseen; without it, an extension turns `pnpm audit` red, and that
 is the moment to re-argue the case. Do not record such a lift as the advisory being fixed. Write
-down that the version is merely outside the range, as `pnpm-workspace.yaml` does.
+down that the version is merely outside the range.
 
 ### Safe Override Workflow
 

package/.claude/rules/role-system.md

@@ -429,6 +429,14 @@ Three mechanisms keep those paths inside the user's rights:
 | AI tools (chat and `/ai/mcp`) | `AiToolRegistry.userCanAccess()` resolves tool roles like the guard under multi-tenancy (global vs membership role, `adminBypass` honoured), with the user as of the CURRENT request — an MCP session refreshes it on every request |
 | Data | `mongooseTenantPlugin` via `RequestContext` — tools run inside the HTTP request, so the validated tenant scopes them |
 
+**A route that authenticates its caller itself (11.43.3).** `@Roles(S_EVERYONE)` routes that resolve
+their own credential — `/ai/mcp` with an MCP OAuth access token — run AFTER the guards saw no user, so
+nothing turned the tenant header into a context and `RequestContext.currentUser` stayed empty (read as
+system work by the Mongoose plugins). `CoreAiMcpController.scopeLateResolvedUser()` now sets `req.user`
+and asks `CoreTenantGuard.resolveMembershipContext()` (via `core-tenant-context.registry.ts`), the
+guard's own `S_EVERYONE` decision. When you add such a route, do the same — never take the header's
+tenant at face value (mutations `mcp-oauth-user-tenant-unscoped`, `mcp-oauth-tenant-from-header`).
+
 **System work vs. an anonymous request.** Both have no current user. `assertTenantRole()` exempts
 system work (cron, migration, seed) and refuses the anonymous caller of a public route with 401 — told
 apart by `RequestContext.fromRequest`, which `RequestContextMiddleware` and the GraphQL WebSocket
@@ -476,6 +484,15 @@ socket therefore ends with its token: at expiry or at the next token refresh.
 **A guard that asks "is this request allowed?" once is not enough for a connection that outlives the
 answer.** When you add a long-lived channel (SSE, a WebSocket of your own), register it the same way.
 
+**Refusing the handshake itself (12.0.0).** `onConnect` refuses a missing or non-authenticating credential with
+`return refuseWsHandshake(extra.socket, reason)` — close code **4401**, which the graphql-ws client does not retry.
+Never by throwing: graphql-ws's ws adapter answers a throw with 4500 and logs "Internal error occurred during
+message handling. Please check your implementation." (until 12.0.0 that happened for every expired token). Never
+by a bare `false`: that closes with 4403, which the client RETRIES — with the same refused credential. 4403 stays
+reserved for a socket whose rights changed while it was open (above). Pinned by
+`tests/subscription-session-iam.e2e-spec.ts` / `tests/subscription-session-legacy.e2e-spec.ts` (mutations
+`iam-ws-handshake-refusal-throws`, `legacy-ws-handshake-refusal-throws`).
+
 ## Role Check Implementation
 
 The role system is evaluated in:

package/.claude/rules/testing.md

@@ -6,8 +6,8 @@
 
 | Runner | Config | Test files | Needs MongoDB |
 |--------|--------|-----------|:-------------:|
-| Unit | `vitest.config.ts` | `tests/unit/**/*.spec.ts` | No |
-| E2E | `vitest-e2e.config.ts` | `tests/**/*.e2e-spec.ts`, `tests/stories/**/*.story.test.ts` | Yes |
+| Unit | `vitest.config.mts` | `tests/unit/**/*.spec.ts` | No |
+| E2E | `vitest-e2e.config.mts` | `tests/**/*.e2e-spec.ts`, `tests/stories/**/*.story.test.ts` | Yes |
 
 **Test files NEVER live in `src/`.** Not a style preference — `src/` is this framework's shipping
 artifact: `package.json` → `files` ships all of `src` recursively into the npm tarball, and
@@ -93,7 +93,7 @@ pnpm run test:cov
 pnpm run test:ci
 
 # Debug open handles
-npx vitest run --config vitest-e2e.config.ts --reporter=hanging-process
+npx vitest run --config vitest-e2e.config.mts --reporter=hanging-process
 
 # Clean up leftover test artifacts (.txt, .bin files from failed file upload tests)
 pnpm run test:cleanup
@@ -105,6 +105,11 @@ pnpm run test:cleanup
   `NODE_ENV`; vitest defaults it to `test`, and `getEnvironmentConfig()` falls back to `config.local`.
 - Both runners load `tests/setup.ts` via `setupFiles` (Nest Logger restricted to `error`/`fatal`,
   `@UnifiedField` deprecation warnings filtered).
+- Both runners set `resolve.extensions` in **Node's order** (`.js` before `.mjs`). graphql has an extensionless
+  `main` next to an `index.mjs`; with Vite's default order an `import` of graphql loaded a second, ESM copy, and every
+  GraphQL subscription closed with 4500 ("Cannot use GraphQLSchema from another module or realm"). Pinned by
+  `tests/unit/vitest-node-resolution.spec.ts` (mutation `vitest-resolves-graphql-esm-build`). Consumer projects need
+  the same line — migration guide 12.0.x §17.
 - Database (E2E only): **one unique database per run** (`nest-server-e2e-run-<ts>-p<pid>`), created by `tests/global-setup.ts` so concurrent runs cannot interfere with each other. Specs needing an extra DB derive it via `deriveTestDbUri('<suffix>')` — never a hardcoded/`Date.now()` name (escapes the cleanup scheme).
 - DB lifecycle (`tests/db-lifecycle.reporter.ts`): run passes → DB dropped immediately + stale run DBs from crashed/failed runs collected; run fails → DB kept for debugging. Additionally `tests/global-setup.ts` runs a **startup sweep** (shared `isStaleTestDb()` predicate, dead-PID/age guarded) — leftovers are removed when the NEXT run starts, which survives SIGKILL (check watchdog) and `--reporter` CLI overrides. An externally set `MONGODB_URI` (CI) opts out of the scheme.
 - The drop guard (`SAFE_TEST_DB_PATTERN` + `NON_DISPOSABLE_DB_PATTERN`): nothing in the scheme drops
@@ -141,7 +146,7 @@ pnpm run test:cleanup
   Pinned by `tests/unit/db-lifecycle-guard.spec.ts` (registered mutation
   `safe-test-db-pattern-unanchored`; reverting the anchoring turns 13 cases red). **The refusal list
   in that spec IS the specification** — extend it rather than loosening the pattern.
-- Run governor (`tests/e2e-run-slots.ts`): machine-wide slot dir (`<tmpdir>/lt-e2e-run-slots`) caps concurrent e2e runs across ALL lt projects/sessions (default 2 on ≥8 cores). Further runs wait, logging `[e2e-governor] waiting…` every 15s (keeps the check watchdog fed — a queued run is NOT hung). The e2e config counts foreign slots at load time and drops to low-resource mode (reduced forks, raised timeouts) when another run is active — deterministic, unlike the lagging 1-min load average (kept as second signal). On a GitHub-hosted runner (`RUNNER_ENVIRONMENT=github-hosted`) the load signal alone raises the timeouts but does NOT cap the workers: such a runner runs one job per VM, and at config time the load is the job's own `vitest:unit` from a second earlier (0.84–0.92/core on every runner build). Measured there, the cap took the e2e step from 133 s to 198 s mean (+25 % normalised for runner speed). Keyed on `RUNNER_ENVIRONMENT`, not `CI`: a shared GitLab runner sets `CI`, carries real contention (2.6–5.0/core measured in a consuming project) and keeps the cap. The cap is `maxWorkers`; the `poolOptions.forks.maxForks` it replaced was removed in Vitest 4 and silently ignored. Knobs: `LT_E2E_MAX_RUNS` (0 disables), `LT_E2E_SLOT_DIR`, `LT_E2E_SLOT_TIMEOUT` (fail-open). A slot is reclaimed when its PID is dead OR it is older than six hours — liveness alone made a slot immortal once its PID was recycled. The slot directory is shared machine-wide (on a multi-user Linux host `/tmp`), so it is created 0700 and the slot file is written without following a planted symlink (unlink + `wx`, 0600). A slot that cannot be written does not abort the suite: the run proceeds ungoverned, because the governor is a throughput measure, not a correctness one. Pinned by `tests/unit/e2e-run-slots.spec.ts` (mutations `e2e-slot-*`).
+- Run governor (`tests/e2e-run-slots.mts`): machine-wide slot dir (`<tmpdir>/lt-e2e-run-slots`) caps concurrent e2e runs across ALL lt projects/sessions (default 2 on ≥8 cores). Further runs wait, logging `[e2e-governor] waiting…` every 15s (keeps the check watchdog fed — a queued run is NOT hung). The e2e config counts foreign slots at load time and drops to low-resource mode (reduced forks, raised timeouts) when another run is active — deterministic, unlike the lagging 1-min load average (kept as second signal). On a GitHub-hosted runner (`RUNNER_ENVIRONMENT=github-hosted`) the load signal alone raises the timeouts but does NOT cap the workers: such a runner runs one job per VM, and at config time the load is the job's own `vitest:unit` from a second earlier (0.84–0.92/core on every runner build). Measured there, the cap took the e2e step from 133 s to 198 s mean (+25 % normalised for runner speed). Keyed on `RUNNER_ENVIRONMENT`, not `CI`: a shared GitLab runner sets `CI`, carries real contention (2.6–5.0/core measured in a consuming project) and keeps the cap. The cap is `maxWorkers`; the `poolOptions.forks.maxForks` it replaced was removed in Vitest 4 and silently ignored. Knobs: `LT_E2E_MAX_RUNS` (0 disables), `LT_E2E_SLOT_DIR`, `LT_E2E_SLOT_TIMEOUT` (fail-open). A slot is reclaimed when its PID is dead OR it is older than six hours — liveness alone made a slot immortal once its PID was recycled. The slot directory is shared machine-wide (on a multi-user Linux host `/tmp`), so it is created 0700 and the slot file is written without following a planted symlink (unlink + `wx`, 0600). A slot that cannot be written does not abort the suite: the run proceeds ungoverned, because the governor is a throughput measure, not a correctness one. Pinned by `tests/unit/e2e-run-slots.spec.ts` (mutations `e2e-slot-*`).
 - `retry: 2` (e2e) is deliberate — with `retry: 5`, one spec file with broken app/socket state ground through 6 attempts × 30s timeout × 22 tests ≈ an hour at 0% CPU (looked like a deadlock; the check watchdog killed it). Never raise retry to paper over contention.
 - Infrastructure containers (E2E only, the **seven** specs listed under "Infrastructure containers"
   above) round-trip against a REAL Redis and/or a REAL S3-compatible store.
@@ -268,7 +273,7 @@ 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)
-pnpm run check:mutations -- --no-infra      # only the 165 that need no MongoDB
+pnpm run check:mutations -- --no-infra      # only the 185 that need no MongoDB
 pnpm run check:mutations -- --since=<ref>   # only mutations touching files changed since <ref>
 ```
 
@@ -287,7 +292,7 @@ when the registry, a vitest config or a setup file changed, since those can move
 commit, and in CI alongside the publish without blocking it. The price of caching is a cache that
 has to model each spec's full dependency closure correctly, and getting that wrong produces a stale
 PASS for a test that has since gone vacuous — exactly what the gate is there to prevent. Bad trade
-at 246 mutations.
+at 274 mutations.
 
 **Decided 2026-10-03 (repo owner): keep the full run.** Measured at 128 mutations, the CI job for
 11.41.6 took **14 minutes**. The trigger to revisit is that wall time, not the mutation count —
@@ -332,9 +337,9 @@ exactly the environment where the answer matters.
 
 ### The cost is vitest's cold start, not the tests
 
-Worth knowing before optimising the wrong thing: the specs behind all 81 e2e mutations add up to
+Worth knowing before optimising the wrong thing: the specs behind all 89 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, 246 times.
+spawn, transform, module graph, mongod connect, DB create and drop — once per mutation, 274 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**.
 
@@ -507,9 +512,9 @@ The writes that actually fed the RPC:
 
 | Source | Call |
 |--------|------|
-| `common/helpers/config.helper.ts` | `console.info` — "Configured for: …", "No local config.json found!" |
-| `common/services/config.service.ts` | `console.warn` from `mergeConfig` |
-| `common/services/rate-limit-store.ts` | `console.warn` from `InMemoryRateLimitStore.hit` |
+| `common/helpers/config.helper.ts` | `console.info` — "Configured for: …" (filtered in `tests/setup.ts` since 12.0.0), the local-config notice |
+| `common/services/config.service.ts` | `console.warn` from `mergeConfig` — since 12.0.0 only when `warn: true` is passed (the constructor used to default to it and dumped the whole config) |
+| `common/services/rate-limit-store.ts` | `console.warn` from `InMemoryRateLimitStore.hit` — a Nest `Logger` since 12.0.0, so no longer an RPC source |
 | `modules/hub/hub-buffer.ts` | `console.debug` from `readShared` |
 | `modules/better-auth/…-email-verification.service.ts` | `console.log` from `logAuthUrlForDevelopment` |
 
@@ -583,9 +588,10 @@ configuration that actually exists** — `grep` for the key in `config.env.ts` b
 
 ## Known coverage gap: no load-test baseline for the auth endpoints
 
-There is no `tests/k6/` in this repository — no config, no endpoint scripts, no baselines. That is
-recorded here rather than quietly absent, because one specific question is unanswered and a reader
-should not have to infer it from silence:
+`tests/k6/` holds a health-check load script and a memory soak test (`memory-test.sh`), but nothing
+for the auth endpoints — no endpoint scripts, no baselines for them. That is recorded here rather than
+quietly absent, because one specific question is unanswered and a reader should not have to infer it
+from silence:
 
 > Under concurrent password-reset load, at what request rate does the added key-derivation work
 > saturate the libuv threadpool?
@@ -622,7 +628,7 @@ environment that breaks it is the one nobody runs tests in by hand.
 **Before a release, run the unit suite the way a runner sees it:**
 
 ```bash
-CI=true npx vitest run --config vitest.config.ts --reporter=dot
+CI=true npx vitest run --config vitest.config.mts --reporter=dot
 ```
 
 Deliberately NOT wired into `check`. It would run all 2381 unit tests a second time — about 40s on
@@ -731,6 +737,9 @@ catches the *failure*, never the *disarming* of the safety property.
 | Internal calls forward the caller's `ServiceOptions` | `tests/unit/service-options-forwarding.spec.ts` |
 | The parity matrix is complete and honest | `tests/unit/file-storage-parity-matrix.spec.ts` |
 | Regression tests carry re-runnable evidence | `tests/unit/regression-evidence.spec.ts` |
+| The core is valid as CommonJS AND ESM (no `require()`, `__dirname`, `import x = require()`, `import.meta`, relative dynamic `import()`) | `tests/unit/module-format-invariants.spec.ts`; `pnpm run check:esm` proves the loading half |
+| The ESM package stays loadable by `require()` (no import from a CommonJS directory into the graph, no top-level `await`) and its CommonJS islands (`bin/`, `migrate/helpers/`) load in place | `tests/unit/module-format-invariants.spec.ts`, `tests/unit/package-format-contracts.spec.ts`; `pnpm run check:manifest` repeats it against the packed build |
+| Type-aware lint is armed (flag, `oxlint-tsgolint`, `no-floating-promises: error`) | `tests/unit/lint-type-aware.spec.ts` |
 
 `service-options-forwarding` is 11.33.1 generalised: inside `src/core/`, a method that HAS the
 caller's context must pass it to every internal call that accepts one. Passing a local derived from

package/CLAUDE.md

@@ -71,6 +71,20 @@ compatible with either downstream layout:
   repo's. The `src/server/` here is a framework-testing example, not
   a shipping component.
 
+- **ESM package (`"type": "module"`), source valid as CommonJS AND ESM
+  (12.0.0+).** CommonJS projects load the package through
+  `require(esm)` like every `@nestjs/*` package — so no top-level
+  `await` anywhere in it. `helpers/` (the TypeScript loader) and `bin/`
+  stay CommonJS through a directory `package.json`. A vendor-mode
+  project compiles the core with its own format. So in `src/core/`: relative imports end in `.js` / `/index.js`,
+  no `require()` / `__dirname` / `import x = require()` / `import.meta`
+  (use `createRequire()` for project files, `callerDirectory()` for
+  "this file's directory"), `import type` for types (`isolatedModules`),
+  no deep imports into `@nestjs/*` root-only packages, no relative
+  dynamic `import()`, and a dual package is lazy everywhere or static
+  everywhere. `pnpm run check:esm` proves it. See
+  `.claude/rules/architecture.md` → "Module Format".
+
 - **Keep top-level `src/index.ts` and `src/core.module.ts` consistent**
   with the core directory structure. The flatten-fix strips `./core/`
   from specifiers in these two files, so if you add re-exports there,
@@ -117,7 +131,7 @@ the update-agent contract.
 ```bash
 # Building & Running
 pnpm run build          # Build (outputs to dist/)
-pnpm start              # Start in local mode
+pnpm start              # Start in local mode (nodemon + SWC source loader — no type-check, `build` does that)
 pnpm run start:dev      # Development mode with watch
 
 # Testing (ALWAYS run before completing changes)
@@ -125,11 +139,11 @@ pnpm test               # Unit + E2E tests (Vitest); E2E half needs MongoDB
 pnpm run vitest:unit    # Unit tests only (fast, no MongoDB)
 pnpm run test:e2e       # E2E tests only
 pnpm run test:cov       # Both suites with coverage (coverage/unit + coverage/e2e)
-npx vitest run --config vitest-e2e.config.ts --reporter=hanging-process   # Debug open handles
+npx vitest run --config vitest-e2e.config.mts --reporter=hanging-process   # Debug open handles
 pnpm run test:cleanup   # Remove leftover test artifacts (.txt, .bin, .png) — Node, runs on Windows too
 
 # Linting & Formatting
-pnpm run lint           # oxlint check
+pnpm run lint           # oxlint --type-aware (no-floating-promises is an error, as in NestJS 12's template)
 pnpm run lint:fix       # Auto-fix
 pnpm run format         # oxfmt format
 
@@ -145,6 +159,15 @@ pnpm run check:overrides # Cross-checks every pnpm override and every auditConfi
                         # See .claude/rules/package-management.md → "Overrides AGE"
 pnpm peers check        # pnpm 11 builtin: unmet/missing peer dependencies, read from the lockfile
 
+pnpm run typecheck:vendor # src/ under `module: commonjs`, declarations EMITTED and scanned — how a
+                        # vendor-mode project compiles the core. Fails on type errors and on
+                        # declarations naming a type via `typeof import()` or a package's /dist/ path
+                        # (break in a consumer's isolated pnpm layout). The nodenext build sees
+                        # neither; see .claude/rules/architecture.md → "Module Format"
+pnpm run check:esm      # Compiles what a vendor project receives as a "type": "module" package and
+                        # imports EVERY module — the proof that the core runs as ESM. Catches a
+                        # named import Node cannot see in a CJS package, a type imported as a value,
+                        # a missing `.js`; see .claude/rules/architecture.md → "Module Format"
 pnpm run check:swc-tdz  # SWC→CJS build, loads EVERY module as its own entry point.
                         # The only step that catches a temporal-dead-zone crash from an
                         # import cycle — tsc, vitest and oxlint are all blind to it.
@@ -236,7 +259,9 @@ boundary under `adminBypass: false`. User-entered URLs (webhooks, export targets
 Since 11.42.3 an **open GraphQL WebSocket** is re-checked, not trusted for its lifetime: at once on an
 invalidation (tenant guard, role change, password reset, sign-out), otherwise every
 `graphQl.subscriptionRevalidationMs` (30 s); changed rights close it with 4403 and the client
-reconnects. A custom `onConnect` must call `registerWsConnection()` to keep that.
+reconnects. A custom `onConnect` must call `registerWsConnection()` to keep that, and refuses a credential
+with `return refuseWsHandshake(extra.socket, reason)` (4401) — never by throwing (graphql-ws: 4500 + an
+"internal error" log line) or a bare `false` (4403, which the client retries) (12.0.0).
 
 See `.claude/rules/role-system.md` for complete documentation.