@lenne.tech/nest-server 11.43.3 → 12.1.0

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
@@ -32,11 +32,11 @@ that every `*.spec.ts` / `*.test.ts` in the repo is claimed by **exactly one** r
 mis-named suite fails the build instead of silently passing. Type-only tests
 (`tests/types/*.type-test.ts`) are compiled by `pnpm run test:types`, never executed.
 
-## Infrastructure containers (Redis + S3)
+## Infrastructure containers (Redis + S3 + PostgreSQL + MySQL + MariaDB)
 
-**Eight** e2e suites talk to a **real** Redis and/or a **real** S3-compatible store rather than a
-mock, and they **fail loudly** when it is missing — a silently skipped infrastructure test is how an
-untested driver ships:
+**Twenty** e2e suites talk to a **real** Redis, a **real** S3-compatible store and/or a **real**
+PostgreSQL, MySQL or MariaDB rather than a mock, and they **fail loudly** when it is missing — a silently skipped
+infrastructure test is how an untested driver ships:
 
 | Suite | Needs |
 |-------|-------|
@@ -44,14 +44,29 @@ untested driver ships:
 | `tests/redis-consumers.e2e-spec.ts` | Redis |
 | `tests/multi-replica.e2e-spec.ts` | Redis |
 | `tests/s3-infra.e2e-spec.ts` | S3 |
-| `tests/file-storage-parity.e2e-spec.ts` | S3 |
-| `tests/file-storage-http-parity.e2e-spec.ts` | S3 |
+| `tests/file-storage-parity.e2e-spec.ts` | S3 + PostgreSQL |
+| `tests/file-storage-http-parity.e2e-spec.ts` | S3 + PostgreSQL |
 | `tests/redis-s3-bootstrap.e2e-spec.ts` | Redis + S3 |
 | `tests/graceful-shutdown.e2e-spec.ts` | Redis + S3 |
-
-`tests/global-setup.ts` starts both containers automatically, so `pnpm test` works from a clean
+| `tests/persistence-sql-executor.e2e-spec.ts` | PostgreSQL |
+| `tests/persistence-sql-where.e2e-spec.ts` | PostgreSQL + MySQL + MariaDB (and MongoDB) |
+| `tests/persistence-sql-schema.e2e-spec.ts` | PostgreSQL |
+| `tests/persistence-sql-store.e2e-spec.ts` | PostgreSQL |
+| `tests/persistence-parity.e2e-spec.ts` | PostgreSQL + MySQL + MariaDB (and MongoDB) |
+| `tests/persistence-lock-store.e2e-spec.ts` | PostgreSQL + MySQL + MariaDB (and MongoDB) |
+| `tests/persistence-sql-wiring.e2e-spec.ts` | PostgreSQL (and MongoDB) |
+| `tests/core-module-parity.e2e-spec.ts` | PostgreSQL + MySQL + MariaDB (and MongoDB) |
+| `tests/migrate/sql-state-store.e2e-spec.ts` | PostgreSQL + MySQL + MariaDB |
+| `tests/persistence-mysql-executor.e2e-spec.ts` | MySQL + MariaDB |
+| `tests/persistence-mysql-schema.e2e-spec.ts` | MySQL + MariaDB |
+| `tests/persistence-mysql-wiring.e2e-spec.ts` | MySQL + MariaDB |
+
+Beyond these twenty, the `postgres` vitest project runs the whole e2e suite once more on PostgreSQL (see "Behaviour
+matrices" below), so without the PostgreSQL container that project fails as a whole while `e2e` runs.
+
+`tests/global-setup.ts` starts all five containers automatically, so `pnpm test` works from a clean
 machine with no manual docker command. It is idempotent (a running container is reused) and never
-fatal: without Docker every other suite still runs, and the eight above report their own actionable
+fatal: without Docker every other suite still runs, and the twenty above report their own actionable
 error.
 
 ```bash
@@ -60,10 +75,28 @@ pnpm run test:infra:status   # what is running
 pnpm run test:infra:down     # stop and remove
 ```
 
-| | Redis | S3 (RustFS) |
-|---|---|---|
-| Port | 6380 (6379 is an auth-protected TurboOps Redis on lt dev machines) | 9102 |
-| Container | `nest-server-2985-redis` | `nest-server-2985-rustfs` |
+| | Redis | S3 (RustFS) | PostgreSQL | MySQL 8.4 | MariaDB 11.8 |
+|---|---|---|---|---|---|
+| Port | 6380 (6379 is an auth-protected TurboOps Redis on lt dev machines) | 9102 | 5440 | 3316 | 3317 |
+| Container | `nest-server-2985-redis` | `nest-server-2985-rustfs` | `nest-server-2985-postgres` | `nest-server-2985-mysql` | `nest-server-2985-mariadb` |
+
+**PostgreSQL runs with two roles, as every environment does** (`.claude/plans/db-agnostic/PLAN.md`
+§3.9): `nest_owner` owns the databases and their schema, `nest_app` owns nothing and has neither
+superuser nor `BYPASSRLS` — so a suite running as the application role meets row-level security the
+way production does. The readiness step creates `nest_app`, which is why the container is started
+through `pnpm run test:infra` (or the CI action) and not by a bare `docker run`. Each suite creates
+its own database through `tests/helpers/postgres-test-db.ts`, named after the run
+(`deriveTestDbUri()`), refused unless it passes the drop guard, and dropped in `afterAll`. Overridable
+via `PG_HOST`, `PG_PORT`, `PG_OWNER_USER`, `PG_OWNER_PASSWORD`, `PG_APP_USER`, `PG_APP_PASSWORD`.
+
+**MySQL and MariaDB run with two accounts the same way** (phase 6): `nest_owner` may do anything,
+`nest_app` holds nothing until `tests/helpers/mysql-test-db.ts` creates a suite's database and grants it
+`SELECT, INSERT, UPDATE, DELETE` there — and revokes that grant before the drop, because a database-level
+grant outlives its database. Database names follow the PostgreSQL scheme and pass the same drop guard.
+Overridable via `MYSQL_HOST`, `MYSQL_PORT`, `MARIADB_HOST`, `MARIADB_PORT`, `MYSQL_OWNER_USER`,
+`MYSQL_OWNER_PASSWORD`, `MYSQL_APP_USER`, `MYSQL_APP_PASSWORD`. MySQL and MariaDB are not a third run of the
+whole e2e suite: the matrices carry their columns (persistence: one per engine; core modules and where
+parity: one per server).
 
 **CI provisions its own** containers in `.github/workflows/*.yml` and sets `LT_TEST_INFRA=0` so the
 automatic start stays out of the way. Same images, same ports — only who starts them differs. Set
@@ -93,7 +126,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 +138,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 +179,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.
@@ -207,6 +245,70 @@ exactly that (`getRawFileInfoByName()` consulted two of the three stores), and e
 | Route-contract executor (boots the real `ServerModule` per driver) | `tests/file-storage-http-parity.e2e-spec.ts` |
 | Structural guard | `tests/unit/file-storage-parity-matrix.spec.ts` |
 
+**It has a database dimension (DEV-3832).** S3 and filesystem metadata follow `database` to a SQL table, so a column
+is a driver WITH its metadata database: `s3` / `filesystem` / `gridfs` (MongoDB, the names they always had) plus
+`s3@postgres` and `filesystem@postgres`, which run every case. `gridfs@postgres` is declared `IMPOSSIBLE` case by case
+— GridFS keeps bytes and metadata together in MongoDB — and the guard refuses a case that runs for a driver on MongoDB
+but not on PostgreSQL. The PostgreSQL environment routes the two metadata models through a real `DataSourceRuntime`
+(`routeFileMetadataToPostgres()`); the HTTP executor installs that runtime before it compiles `ServerModule`, as
+`CoreModule.forRoot()` would. **The harness reads and plants through the stores, never through
+`fileMetadataCollection()`**: a harness using the routing it checks follows a broken routing to MongoDB and stays green
+(mutation `file-metadata-routing-ignored` turns 22 cells red only because of that).
+
+The **core modules** follow it one level up: `tests/helpers/core-module-matrix.ts` declares what the framework's own
+modules answer through REST and GraphQL — users and legacy sign-in, tenant memberships and the tenant guard, API
+tokens, health check, Hub panels — and `tests/core-module-parity.e2e-spec.ts` assembles them like the reference server
+once with MongoDB alone and once with PostgreSQL as the default source (default engine; the persistence matrix covers
+the engines). `tests/unit/core-module-parity-matrix.spec.ts` is its structural guard. The PostgreSQL column signs in
+through the legacy endpoints with `betterAuth: false`, so it proves the legacy-auth path on SQL; IAM on SQL is the job of
+the projects below.
+
+The **whole e2e suite runs on both databases** (12.1.0+): the `e2e` project on MongoDB, the `postgres` project again
+with PostgreSQL as the default data source (`POSTGRES_E2E_ENGINE`, the default engine TypeORM). Each test file gets a
+PostgreSQL database of its own (`tests/postgres-file.setup.ts`, created before the file's first import and dropped in
+its `afterAll`): two suites with different `multiTenancy` sharing one database stop each other's boot, because a table
+that loses tenant isolation refuses to start. A `describe` whose configuration differs from the rest of its file — or
+that needs an empty user base, as the system setup does — takes one more of its own through
+`ownPostgresDatabase()` / `onOwnPostgresDatabase()` (`tests/helpers/postgres-test-db.ts`). The project runs every e2e
+file except those in `POSTGRES_E2E_EXCLUDED` (`vitest.include-globs.mts`), each with one of two reasons: `MONGODB-ONLY:`
+(the suite checks a MongoDB mechanism against MongoDB itself, and names where its PostgreSQL counterpart is proven) or
+`OWN-DATABASES:` (a parity matrix or a suite that creates its PostgreSQL databases itself). An entry is a claim about the
+suite, never a way to get a run green: a suite that fails on PostgreSQL because it reads MongoDB directly belongs on
+the neutral helpers. `tests/unit/postgres-e2e-coverage.spec.ts` keeps the list honest (existing suites, one of the two
+reasons, an upper bound on its size).
+
+A suite stays database-neutral through three rules. It reads and prepares users, sessions, accounts and reset tokens
+through `tests/helpers/iam-test-db.ts` — `openIamTestDb(uri, { users: 'mongodb' })` for an application built on
+`CoreModule.forRoot()` alone, which registers no user model and therefore keeps its users on MongoDB. It reads a model
+the application registered with `CorePersistenceModule.forFeature()` through that model's store
+(`app.get(getStoreToken(name), { strict: false })`, inside `RequestContext.runWithBypassTenantGuard()` for a
+tenant-scoped one) — never through a MongoDB client, which would read the wrong database on PostgreSQL. And it keeps
+what is genuinely MongoDB's on MongoDB (`iamDb.mongo`: GridFS, a model registered with `MongooseModule.forFeature()`
+alone). Where a behaviour differs by design — PostgreSQL's CHECK constraint refuses a stored system role that MongoDB
+lets a raw insert plant — the case asserts what happens instead, per `iamDb.driver`.
+
+The **IAM suites** run on the two other engines as well, through vitest projects in `vitest-e2e.config.mts`:
+`iam-sql-kysely` and `iam-sql-drizzle` (`IAM_SQL_ENGINES`), each over the files in `IAM_SQL_TEST_INCLUDE`
+(`vitest.include-globs.mts`: the Better-Auth stories, privilege escalation, sign-in CSRF, migration status, the storage
+paths, the bidirectional sync, and since phase 4 the AI suite and both MCP OAuth suites). A project's global setup (`tests/iam-sql.global-setup.ts`) creates its PostgreSQL
+database per run and drops it afterwards; its setup file (`tests/iam-sql.setup.ts`) points `NSC__DATABASE__URL`,
+`NSC__DATABASE__OWNER_URL` and `NSC__DATABASE__SQL_ENGINE` at it, so the unchanged `ServerModule` boots with its users —
+and Better-Auth with them — on PostgreSQL. The suites read and prepare state through `tests/helpers/iam-test-db.ts`,
+which answers from whichever database the run routes the users to (camelCase fields, string ids, a column never written
+left out rather than `null`), never through a MongoDB client of their own; the AI suite does the same through
+`tests/helpers/ai-test-stores.ts` (the stores the application routes the AI models to, `system()` for fixtures that span
+tenants). `tests/ai-mcp-oauth-tenant.e2e-spec.ts` boots with `multiTenancy` and therefore creates a PostgreSQL database
+of its own in those projects: a table that loses tenant isolation stops the boot of a suite configured without it, so
+two suites with different `multiTenancy` must never share one. Keep the root config free of `include`: with
+`extends: true` it is merged into every project, and the IAM projects would run the whole suite. vitest runs the global
+setup of EVERY project before any test, and the project setups before the root one — so a throw in
+`tests/iam-sql.global-setup.ts` used to stop the whole run, MongoDB project included, before the root setup could start
+the containers. The IAM setup therefore starts the test infrastructure itself (once per run) and never throws: a
+database it still cannot create (no Docker) makes every suite of that project fail in `tests/iam-sql.setup.ts` with the
+reason, never fall back to MongoDB, while the `e2e` project runs. `--project e2e` runs MongoDB alone.
+
+The **data store** contract follows the same discipline: `tests/helpers/persistence-matrix.ts` declares the cases (CRUD contract plus the security policies), `tests/persistence-parity.e2e-spec.ts` executes them against a store obtained via `CorePersistenceModule.forFeature()` + `@InjectStore()` with every security plugin registered, and `tests/unit/persistence-parity-matrix.spec.ts` guards that every (case, database) cell is declared. It has ten columns: `mongodb`, PostgreSQL once per engine (`postgres-typeorm`, `postgres-kysely`, `postgres-drizzle`) — a `SqlDataStore` over the schema the migrator created, connected as the application role, so row-level security binds every case — and MySQL and MariaDB once per engine (`mysql-*`, `mariadb-*`, phase 6), a `MysqlDataStore` connected as the DML-only application account. Without row-level security there, `native-api-tenant-refused` is DIFFERENT-BY-DESIGN for those six columns and its complement asserts that a native query reaches every tenant while the store still isolates. Each tenant layer of the SQL store is additionally proven ALONE in `tests/persistence-sql-store.e2e-spec.ts` — the matrix runs them together, where one layer hides the loss of another.
+
 ### A cell is EXECUTED, IMPOSSIBLE, or DIFFERENT-BY-DESIGN — never merely absent
 
 Omitting a case for one implementation and declaring it impossible there produce the same artefact
@@ -268,7 +370,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 222 that need no MongoDB
 pnpm run check:mutations -- --since=<ref>   # only mutations touching files changed since <ref>
 ```
 
@@ -287,7 +389,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 249 mutations.
+at 407 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 +434,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 84 e2e mutations add up to
+Worth knowing before optimising the wrong thing: the specs behind all 185 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, 249 times.
+spawn, transform, module graph, mongod connect, DB create and drop — once per mutation, 407 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 +609,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 +685,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 +725,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
@@ -729,8 +832,12 @@ catches the *failure*, never the *disarming* of the safety property.
 |-----------|-------|
 | DI tokens live in import-free leaves (SWC/TDZ) | `tests/unit/import-cycle-invariants.spec.ts` |
 | 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` |
+| The parity matrix is complete and honest | `tests/unit/file-storage-parity-matrix.spec.ts`, `tests/unit/persistence-parity-matrix.spec.ts`, `tests/unit/core-module-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` |
+| The core needs no MongoDB library (12.1.0+): no static value import of `mongoose` / `@nestjs/mongoose` / `mongodb`, both model-description sources agree | `pnpm run check:without-mongodb` (dist, packages unresolvable; `:package` installs the tarball without them); `tests/unit/persistence-model-descriptor.spec.ts`; `tests/unit/import-cycle-invariants.spec.ts` (the compat leaf) |
 
 `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,
@@ -93,6 +107,15 @@ compatible with either downstream layout:
   other entry on that list, was never imported by framework code — only by the
   pre-commit hook's `extras/sync-version.ts` — and left together with `husky`
   in 11.41.8; its list entry is now inert.
+  **Since 12.1.0 `mongoose`, `@nestjs/mongoose` and `mongodb` are OPTIONAL peers** (an npm-mode project on
+  PostgreSQL alone installs none of them): a vendor-mode project that keeps data in MongoDB must declare them
+  itself — the CLI's vendoring step has to add them for a MongoDB project (lt CLI ticket of the db-agnostic
+  epic). **Every vendor project — on whatever database — declares the SQL packages the core names in a literal
+  `import()`: `pg` (with `@types/pg`), `mysql2`, `typeorm`, `kysely`, `drizzle-orm`** (at least as `devDependencies`): the vendored core
+  is the project's own source, and `tsc` fails with TS2307 on a dynamic `import()` of a missing package. A SQL vendor
+  project also keeps the three MongoDB packages as `devDependencies`: the
+  vendored core is the project's own source and imports their TYPES (`import type { Connection } from
+  'mongoose'`), so its `tsc` fails with TS2307 without them; at runtime it loads none of them.
   **A peer listed there must ALSO stay in `devDependencies`**: the CLI reads
   the version from the upstream devDeps, so removing it as "redundant with
   the peer range" silently leaves vendor consumers without the package, with
@@ -117,7 +140,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 +148,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 +168,18 @@ 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:without-mongodb # dist/ with mongoose, @nestjs/mongoose and mongodb unresolvable: loads, boots on
+                        # PostgreSQL, CRUD, Better-Auth sign-up/in, file storage. `:package` installs the packed
+                        # tarball into a project WITHOUT them (publish path). See .claude/rules/persistence.md
 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.
@@ -167,7 +202,7 @@ pnpm run reinit         # Clean reinstall + tests + build
 - `src/core/common/` - Decorators, helpers, interceptors, services
 - `src/core/modules/` - ApiToken, Auth, BetterAuth, ErrorCode, File, HealthCheck, Hub, Migrate, Permissions, SystemSetup, Tus, User
   - **ApiToken** - Opt-in (`apiTokens`) USER and TENANT tokens + signed assertions. Denied on every route without `@ApiTokenScopes()`; all three guards share `enforceApiTokenRoute()`. See `src/core/modules/api-token/README.md`.
-  - **Hub** - Build-free ADMIN-gated operator cockpit at `/hub` (config-gated per environment; 16 panels, runtime collectors, mailbox, admin actions). See `src/core/modules/hub/README.md`.
+  - **Hub** - Build-free ADMIN-gated operator cockpit at `/hub` (config-gated per environment; 17 panels, runtime collectors, mailbox, admin actions). See `src/core/modules/hub/README.md`.
   - **Permissions** - ADMIN-gated security-map report (routes + roles + `@Restricted` fields); also surfaced in the Hub's "Routes / Permissions" panel.
 - **Optional central infrastructure** (11.33.0+) - `CoreRedisService` (`redis` config) and `CoreS3Service` (`s3` config) turn process-local state into shared state for multi-replica deployments: rate-limit counters, cron deduplication, GraphQL subscriptions, tenant-cache invalidation, Hub collectors, file storage (`file.storage: 's3'`; the driver is otherwise derived — S3 → GridFS → filesystem — and an unavailable one fails the boot rather than falling back) and TUS staging. Both are inert without their config, and their client libraries are **optional peer dependencies** (`ioredis`, `bullmq`, `@aws-sdk/client-s3`, `@aws-sdk/lib-storage`, `@aws-sdk/s3-request-presigner`, `@tus/s3-store`) — a project that uses neither installs nothing extra. When adding a distributed feature, always keep the non-configured fallback path.
 
@@ -236,7 +271,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.
 
@@ -331,6 +368,7 @@ Detailed documentation in `.claude/rules/`:
 | `migration-guides.md` | Process for creating version migration guides |
 | `configurable-features.md` | Configuration patterns: "Presence implies enabled" and "Boolean shorthand" (`true` / `{}`) |
 | `package-management.md` | Fixed package versions only - no `^`, `~`, or ranges |
+| `persistence.md` | MongoDB and PostgreSQL: the data store, `forFeature()`, optional MongoDB libraries, native tiers, hot paths per database |
 | `framework-compatibility.md` | Maintenance obligations for FRAMEWORK-API.md, shipped docs, cross-repo dependencies |
 
 ## Native MongoDB Driver — Security Rules
@@ -420,6 +458,12 @@ These alternatives bypass `process()` but keep Mongoose plugins (Tenant, Audit,
 
 ### High-Frequency Path Design Rules
 
+**Per database (12.1.0+):** the rules below name Mongoose APIs because on MongoDB the Mongoose plugins still fire on
+`Model.create()` / `findByIdAndUpdate()`. On PostgreSQL there is no Mongoose model to call (a model routed to SQL
+refuses every Mongoose data method), and the policies live in the store. The neutral form of every rule below is the
+data store — `this.dataStore.insert()`, `updateById()`, `findById()`, `pushToArray()` skip `process()` and keep every
+policy on both databases; prefer it in new code (`.claude/rules/persistence.md` → "High-frequency paths").
+
 These rules apply when building features that execute many times per minute (monitoring, metrics, queue processors). These paths are always system-internal — no user context, no authorization needed.
 
 1. **`Model.create(doc)` over `new Model().save()`** for single documents — `create()` is ~3x faster and uses ~9x less memory. For batch inserts (N>1), use `Model.insertMany(docs)` — a single call with N documents is ~2.5x faster than N parallel `save()` calls.
@@ -483,7 +527,7 @@ Details: [`docs/process-performance-optimization.md`](docs/process-performance-o
 | [`docs/REQUEST-LIFECYCLE.md`](docs/REQUEST-LIFECYCLE.md) | Complete request lifecycle, security architecture, interceptor chain, decorator reference, CrudService pipeline, Safety Net, diagrams |
 | [`docs/native-driver-security.md`](docs/native-driver-security.md) | Native MongoDB Driver restrictions, secure alternatives, review checklist |
 | [`docs/process-performance-optimization.md`](docs/process-performance-optimization.md) | process() pipeline performance optimizations, SubDocument array handling (pushToArray/pullFromArray) |
-| [`docs/security-overrides.md`](docs/security-overrides.md) | Why pnpm `overrides:` do NOT reach consumers, which two are load-bearing, and the rules for writing your own |
+| [`docs/security-overrides.md`](docs/security-overrides.md) | Why pnpm `overrides:` do NOT reach consumers, which entries a project still needs (none on 12.1 with the declared `@nestjs/*` versions), and the rules for writing your own |
 | [`docs/brevo-manual-test.md`](docs/brevo-manual-test.md) | Manual smoke test for `BrevoService` against the live Brevo API (framework repo only) |
 
 <!-- lt-dev:url-block:start -->