@lenne.tech/nest-server 12.0.0 → 12.1.0

package/.claude/rules/architecture.md

@@ -52,6 +52,11 @@ config is present, and keep their previous single-process behaviour when it is n
 `@Optional()` and always keep the non-configured fallback path — that is the pattern every core
 consumer follows. See `.claude/rules/configurable-features.md` for the full option reference.
 
+**MongoDB itself is optional since 12.1.0** — the same pattern one level down: `mongoose`, `@nestjs/mongoose` and
+`mongodb` are optional peers, reached only through `common/persistence/mongo/` (never a static value import in
+`src/core/`), and `CoreModule` connects MongoDB only when a data source uses it. `pnpm run check:without-mongodb`
+proves the build loads and runs with them unresolvable. Rules: `.claude/rules/persistence.md`.
+
 ## Core Modules (`src/core/modules/`)
 
 | Module | Purpose |
@@ -62,7 +67,7 @@ consumer follows. See `.claude/rules/configurable-features.md` for the full opti
 | **ErrorCode** | Centralized error codes with unique identifiers |
 | **File** | File upload/download with GridFS storage |
 | **HealthCheck** | Application health monitoring |
-| **Hub** | Build-free ADMIN-gated operator cockpit at `/hub` (config-gated per environment; 16 panels, runtime collectors, mailbox, admin actions) |
+| **Hub** | Build-free ADMIN-gated operator cockpit at `/hub` (config-gated per environment; 17 panels, runtime collectors, mailbox, admin actions) |
 | **Migrate** | Database migration utilities |
 | **Permissions** | ADMIN-gated security-map report (routes + roles + `@Restricted` fields); also surfaced in the Hub's "Routes / Permissions" panel |
 | **SystemSetup** | Initial admin creation for fresh deployments |

package/.claude/rules/better-auth.md

@@ -504,6 +504,51 @@ this protection must set `betterAuth.options.advanced.disableOriginCheck: false`
 removed. `tests/better-auth-signin-csrf.e2e-spec.ts` does; mutations `iam-signin-csrf-check-skipped` /
 `iam-signup-csrf-check-skipped`.
 
+## 11. Better-Auth on a SQL source — it follows the users table (db-agnostic phase 3)
+
+Better-Auth keeps its data where the user model lives. `DataSourceRuntime.iamStorage()` finds the persisted model whose
+table is `users`; when that model is routed to a SQL source, `CoreBetterAuthModule.createInstance()` hands Better-Auth
+the application role's `pg` pool of that source, and Better-Auth runs its own Kysely adapter on it (it recognises a pool
+by its `connect` method — the core imports no Kysely). On MongoDB nothing changes.
+
+| Piece | Where | Rule |
+|---|---|---|
+| Naming | `withSqlStorage()` in `better-auth-sql.helper.ts` | `user` → `users`, every table and field snake_case — the plugins' too, on copies, never the plugin objects; ids are ObjectId hex (`generateId`), so a Better-Auth user id IS the framework's id and `iamId` equals it |
+| One row per user | the same helper + `registerForeignColumns('users', …)` | Better-Auth's own columns (`name`, `email_verified`, `image`) live in the framework's `users` table; its required ones are added nullable first, so a row the user model writes alone stays valid, and the framework's schema planner does not report them as undeclared |
+| Schema | `applyBetterAuthSchema()` | Better-Auth validates its schema when the instance is created, so its migrations run BEFORE, as the owner, under the framework's schema lock, followed by the grants and the safe-role check. Without an owner connection the boot stops while anything is pending — the application role never runs DDL |
+| Framework access | `BetterAuthSqlStore` (`core-better-auth-sql.store.ts`), reached through the import-free leaf `core-better-auth-sql.registry.ts` | framework fields of the user row go through the user model's `DataStore` (its policies apply); Better-Auth's own fields and tables go through Better-Auth's `internalAdapter` / `adapter` (its hooks run — a deleted session reaches `wsSessionRevocationPlugin()`). Every MongoDB path keeps its code; the SQL branch sits beside it (`*OnSql` in the user mapper) |
+| Passkey challenges | `storeChallenge()` | Better-Auth verification values with the identifier prefix `lt-passkey-challenge:` — no table of the framework's own, expiry checked on read, expired ones removed as new ones arrive |
+| Expired rows | `BetterAuthSqlStore.deleteExpired()`, scheduled by `CoreBetterAuthService.startExpirySweep()` | Better-Auth never deletes an expired session and clears expired verification values only when one is looked up; on MongoDB the verification TTL index does it. On SQL the expiry sweep (`scheduleExpirySweep()`, every 15 min, one replica per interval) removes both — through Better-Auth's adapter, so its naming applies. Stopped in `onModuleDestroy()`, before the data sources close (mutation `iam-expired-sessions-kept`) |
+| Per-request path | token service, middlewares, guard, web and cookie helpers | ids are strings; only `BetterAuthMongoUsers` (`core-better-auth-mongo.users.ts`) knows what an ObjectId is. Pinned by `tests/unit/iam-request-path-ids.spec.ts` |
+| Boot steps | `CoreBetterAuthService.onModuleInit()` | `ensureIndices()` and the account-issuer backfill concern MongoDB's collections and are skipped on SQL |
+| Counting | `BetterAuthSqlStore.migrationCounts()` | counts in SQL (`count(*)`, `EXISTS` over `account`), names from `$context.tables`. **Never read a whole table through Better-Auth's `adapter.findMany()`**: without a `limit` it stops at 100 rows (`defaultFindManyLimit`), which capped the migration status at 100 migrated users (mutation `iam-migration-status-capped-at-a-page`) |
+| Readers outside the module | `CoreAiMcpOAuthService.loadUser()` | every native read of `users` needs the SQL branch too — an OAuth subject's roles came from MongoDB, i.e. nobody or a stale copy (mutation `mcp-oauth-user-on-mongo`). Find candidates with `grep -rn "collection('users')" src/core` |
+
+**Sign-up holds a pool connection while it hashes (accepted).** Better-Auth runs its Kysely adapter with transactions
+on a `pg` pool, and `/sign-up/email` hashes the password inside its transaction — on the framework's application pool
+(10 connections). A burst of concurrent sign-ups therefore makes other queries wait (measured: ~0.16 s at 20, ~1.3 s
+at 100). Kept on purpose: it is Better-Auth's standard behaviour on PostgreSQL, it makes user and account creation
+atomic, and switching it off would need a Kysely instance the core cannot rely on (`kysely` is an optional peer).
+`betterAuth.rateLimit` bounds it.
+
+**Not on SQL, and why that is no gap:** the account-issuer backfill (§8) repairs account documents better-auth 1.6
+wrote to MongoDB before the field existed. On a SQL source every account row is written with what the installed line
+expects — by Better-Auth itself, and by the framework's own writes through the issuer helper (`migrateAccountToIamOnSql()`,
+the system setup) — so there is nothing to backfill. Nothing is copied from MongoDB when a project routes its users to
+SQL.
+
+**The challenge cookie is named by Better-Auth.** The API middleware reads the passkey challenge token from the cookie
+Better-Auth sets and asks the instance for its name (`createAuthCookie(<key>).name`, `iam.better-auth-passkey` by
+default) — a hard-coded `better-auth.` prefix missed it after the cookie prefix began to follow the base path, so no
+mapping was stored and no `challengeId` returned, on every database (mutation `passkey-challenge-cookie-unprefixed`).
+`passkey.webAuthnChallengeCookie` is the KEY; it reaches the plugin as `advanced.webAuthnChallengeCookie`, the only
+place the plugin reads it.
+
+Tests: every IAM suite runs on MongoDB and on PostgreSQL with each engine (`.claude/rules/testing.md` → the IAM
+projects); `tests/better-auth-storage-paths.e2e-spec.ts` covers the four paths the stories pass either way (session
+token as bearer, token service, passkey challenge, e-mail verified), `tests/persistence-sql-wiring.e2e-spec.ts` the
+boot (one row, ownership, a second boot, the system setup).
+
 ## Summary
 
 | Principle | Requirement |
@@ -518,3 +563,4 @@ removed. `tests/better-auth-signin-csrf.e2e-spec.ts` does; mutations `iam-signin
 | `account` reads / writes | Reads filter on `providerId` alone, never `issuer`. Writes set `issuer` only on better-auth 1.7.0–1.7.2, via the helper (§8) |
 | `openAPI()` plugin | Registered internally for `setupSwagger()`, kept off the router (`SERVER_ONLY`) unless the project registered it — never by a path check (§9) |
 | Direct `api.*` calls | Hand Better-Auth the request (CSRF headers only) + `asResponse: false`, or its login-CSRF check is skipped (§10) |
+| SQL source | Better-Auth follows the users table; the framework reaches its data through `BetterAuthSqlStore`, ids stay strings (§11) |

package/.claude/rules/configurable-features.md

@@ -321,7 +321,8 @@ This pattern is currently applied to:
 | Translate Response Interceptor | `security.translateResponseInterceptor` | Boolean Shorthand | `true` (enabled) |
 | Mongoose CastError Filter | `security.mongooseCastErrorFilter` | Explicit Boolean — **safe default** | **`true` since 11.42.16.** `MongooseCastErrorFilter`, registered by `CoreModule` as `APP_FILTER` (so `main.ts` and `Test.createTestingModule()` setups need nothing). A malformed id reached Mongoose and its `CastError` — not an `HttpException` — escaped every `@Catch(HttpException)` filter, so `GET /users/<malformed-id>` and every other `:id` route answered **500**. The filter decides by WHERE the failing value came from: a route parameter or a top-level GraphQL argument → **404** `ErrorCode.RESOURCE_NOT_FOUND` (answered like an unknown id); the query string, an update or filter body, or a nested GraphQL input → **400** `ErrorCode.INVALID_FIELD_FORMAT [<path>]`; a value the request does not contain (a broken stored id, a server-computed value) → **stays a 500**, with Nest's own body and log line (context `ExceptionsHandler`), because that is a data or code defect monitoring must keep seeing — relabelling it as a client error is the mistake the refusal tests pin (mutations `cast-error-server-value-relabelled-*`). Only primitives and arrays of primitives (`$in`) are matched: an object cast as a whole yields no candidates, so its inner strings cannot match the body by coincidence. Never sends the Mongoose message (it names the model). REST bodies use the `HttpExceptionLogFilter` shape (`{ ...exception }`). A project's own catch-all filter via `app.useGlobalFilters()` is consulted first and wins. Covers casts Mongoose raises while running a QUERY or an UPDATE (`findById`, filters, `findByIdAndUpdate` — `CrudService.update()`). NOT covered, both stay a 500: a malformed id in a document being CREATED (`save()` / `create()` / `insertMany()` — `CrudService.create()`), which Mongoose reports as a `ValidationError` wrapping the CastError (validate in the input: `validator: () => [IsMongoId()]`); and a `BSONError` from `new Types.ObjectId(bad)`, which carries no value (check the id in the service, `CoreFileService.isMalformedFileId()`). `false` restores the 500. Implementation: `common/filters/mongoose-cast-error.filter.ts` |
 | Secret Fields Removal | `security.secretFields` | Array | `['password', 'verificationToken', ...]` |
-| Multi-Tenancy | `multiTenancy` | Presence Implies Enabled | **`excludeSchemas` is an OFF SWITCH for isolation, per model** — a listed schema gets no tenant filter at all; since 11.35.0 the plugin WARNS once per model when the excluded schema declares `tenantId` (i.e. was built for isolation). The framework's own docs recommended `['User', 'Session']` until then; that is withdrawn — it is only right for the global-user model. Since 11.35.0 GraphQL operations over the WEBSOCKET also run inside a `RequestContext` (`CoreModule` installs a context-aware `execute`/`subscribe` pair inside `subscriptions`, where `ApolloDriver` forwards it): the tenant comes from the handshake header validated against an active membership, else from the subscriber's memberships, and an unresolvable tenant leaves the safety net to refuse the read rather than returning everything. `headerName: 'x-tenant-id'`, `membershipModel: 'TenantMember'`, `adminBypass: true`, `excludeSchemas: []`, `roleHierarchy: { member: 1, manager: 2, owner: 3 }`, `cacheTtlMs: 30000` (0 disables, process-local). System roles (`S_EVERYONE`, `S_USER`, `S_VERIFIED`) are checked as OR alternatives before real roles; method-level system roles take precedence; membership validated for context when system role grants access + header present. Hierarchy roles use level comparison, normal roles use exact match. Use `DefaultHR` or `createHierarchyRoles()` for type-safe role constants. Bypass: `RequestContext.runWithBypassTenantGuard()`. Cache invalidation: `invalidateUser(userId)` / `invalidateAll()` are **instance** methods on the singleton `CoreTenantGuard` — inject it and call `this.tenantGuard?.invalidateUser(userId)`, never `CoreTenantGuard.invalidateUser(...)` (there is no static). With `redis` configured, both additionally BROADCAST the invalidation to every replica (`<keyPrefix>:tenant-cache:invalidate` pub/sub); without Redis they clear the local process only, so other replicas stay stale until `cacheTtlMs`. A received broadcast clears locally without re-publishing. **`isTenantActive` (11.42.0)**: optional hook `(tenantId, { connection }) => boolean \| Promise<boolean>`, absent = every tenant active (no change). Asked AFTER the membership check on every path that establishes a tenant: 403 on header paths and for tenant API tokens, no enrichment on `S_EVERYONE`, dropped from the header-less tenant list, no tenant for a NEW WebSocket subscription, and since 11.42.3 an OPEN one is closed with 4403 on `invalidateTenant()` (or at its next event once `graphQl.subscriptionRevalidationMs` has passed — see the GraphQL Subscription Re-check row); an admin under `adminBypass` is exempt (someone must be able to switch it back on). Only `false` deactivates. Cached for `cacheTtlMs`; `invalidateTenant(tenantId)` clears and broadcasts (`{ scope: 'tenant' }`). A function, so `config.env.ts` only — not reachable through `NSC__*`. **`adminBypass: false` (11.42.0)** additionally withholds two things that went around it: `CoreUserService.update()` refuses changing another account's e-mail or password (`assertCredentialChangeAllowed()`, administrator targets included — promote-then-change — system work without a current user exempt), and the AI tool registry grants no ADMIN bypass |
+| Data Sources | `database` | Explicit Value — absent = today's `mongoose` config | **Absent → the `mongoose` configuration is the only data source, exactly as before; nothing SQL is loaded or installed.** A URL string (`'postgres://…'`) sets the default source (driver from the scheme, `sqlEngine` defaults to `typeorm`; `kysely` and `drizzle` are the alternatives — optional peers, each with `pg`); an object adds `ownerUrl` (default source), `sources` (name → URL or `{ url, ownerUrl, sqlEngine }`) and per-model exceptions (`models`); `false` means no database. Precedence for a model: `database.models` > the `dataSource` of a `CorePersistenceModule.forFeature()` definition > `@PersistedModel({ dataSource })` (read from the definition's `model:` class, otherwise from the decorated class named like the model; two such classes naming different sources refuse to guess) > default. When `database` sets a default and the project ALSO configures `mongoose` explicitly, that MongoDB becomes the source `mongoose` — only the project's own `mongoose` counts, because `CoreModule.forRoot()` always merges a fallback URI. **Since phase 1 (DEV-3829) PostgreSQL sources are wired**: only models registered with `CorePersistenceModule.forFeature()` are routed — **since phase 2 (DEV-3830) that includes the core's own models**: the user model (the reference `UserModule`), tenant memberships and API tokens, whose services switch to the routed store (a service that only received `@InjectModel()` follows its model's store; the Mongoose model of a model routed to SQL refuses every data access with a named error, so a direct `mainDbModel` call cannot split a model's data). **Since phase 3 (DEV-3831) Better-Auth follows the user model**: with the user model (table `users`) on a SQL source, Better-Auth runs its built-in Kysely adapter on that source's application pool — ONE `users` row per user shared with the user model (Better-Auth's own columns `name`, `email_verified`, `image` beside the framework's; its required ones are added nullable, so a row the user model writes alone stays valid), snake_case tables (`session`, `account`, `verification`, `jwks`, `two_factor`, `passkey`), ObjectId-hex ids. Its schema is applied as the OWNER at boot, under the same schema lock and grants as the framework's tables; without `ownerUrl` the application role only verifies and the boot stops while Better-Auth's migrations are pending. The framework's own reads and writes of Better-Auth's data follow it (session lookup by token, token service, JWKS, passkey challenge mappings — as Better-Auth verification values —, the e-mail-verified hook, user mapper, system setup, migration status — counted in SQL —, the MCP OAuth subject's roles); the MongoDB boot steps (indices, account-issuer backfill) are skipped there. Nothing is copied from MongoDB: a project that moves its users brings them over itself. **Since phase 4 (DEV-3832) the remaining core persistence follows too**: the AI module's eleven models and the three MCP OAuth stores (clients, codes, refresh tokens) are registered through `CorePersistenceModule.forFeature()` and run on their routed store (one code path; an upsert is update-then-insert with a retry on a duplicate, `sum()` replaces the budget aggregation, `find(…, { exclude })` the `-field` projection); the S3 and filesystem file metadata are two framework models (`CoreS3File`, `CoreFilesystemFile`, tables `s3_files` / `filesystem_files`) read and written through `fileMetadataCollection()` by the file service, the TUS hand-off and the Hub — GridFS stays MongoDB-only. A collection name with a hyphen becomes a table with an underscore. A TTL (`expires`, `index: { expireAfterSeconds }`) is a plain index on SQL; an **expiry sweep** (`scheduleExpirySweep()`, every 15 min, one replica per interval through a lease in the default SQL source's `lt_locks`, fail-open) deletes the expired rows of every routed TTL model, and — with Better-Auth on SQL — expired sessions and verification values. Nothing relies on it for correctness: every reader checks the expiry (an MCP authorization code older than ten minutes is refused on read on both databases). MongoDB keeps its TTL indexes and gets no sweep. The framework's leases (system-setup claim, cron, migrations) live in the default source: on MongoDB in the 12.0.0 documents (a rolling deploy with older replicas shares them), on SQL in `lt_locks`, namespaced, swept an hour after expiry. With `healthCheck.configs.database` every SQL source answers as `<key>:<source>`; `createMigrationStore(<owner URL>)` keeps the migration state in `lt_migrations` with an advisory run lock, on the first SQL engine installed (the CLI cannot read `database.sqlEngine`), and the Hub refuses to run migrations while that table is empty and the MongoDB collection is not (a `migrate.js` still writing MongoDB); the Hub's Persistence panel shows the routing. a SQL model's table is migrated as the OWNER (`ownerUrl`) when its store is created — without `ownerUrl` the application role only verifies and the boot stops while changes are pending; ONE owner connection per source, released once the application is bootstrapped — and the boot refuses an application role that is superuser, has `BYPASSRLS`, owns (or inherits the owner of) a framework table or may `TRUNCATE` it. Two roles in every environment (plan §3.9). Changes the framework never applies on its own (type change, new unique index, rename collision) stop the boot with the suggested statements; `migrate create <name> --sql` + `runSqlMigration()` apply them after review. **Since phase 5 (DEV-3833, 12.1.0) MongoDB is optional**: `mongoose`, `@nestjs/mongoose` and `mongodb` are optional peers, loaded through `common/persistence/mongo/mongo-packages.ts`; `CoreModule` connects MongoDB only when a source uses it (`usesMongoDb()` — `mongoose` configured explicitly, `database` naming MongoDB, or `database` absent), otherwise `@InjectConnection()` receives `null` and a model token without a connection is a stand-in that refuses data access. A configured MongoDB feature without the packages fails the boot with `MongoPackagesMissingError`. `database: false` runs a service without any database: a registered model's store refuses with the reason, Better-Auth is refused at boot. Proven by `pnpm run check:without-mongodb` (dist, packages hidden) and `check:without-mongodb:package` (the tarball installed without them, publish path). **Since phase 6 (DEV-3848) MySQL 8.4 and MariaDB 11.8 sources are wired** (`mysql://`, `mariadb://` — the scheme must name the server the URL reaches): `mysql2` is an optional peer beside the engine, all three engines run on one pool the framework creates (strict session with backslash escapes, UTC), `MysqlDataStore` writes the statements, the owner grants the application account `SELECT, INSERT, UPDATE, DELETE` on the database once and the boot refuses an application account that may alter, drop, index, trigger or grant; leases, migration state (`createMigrationStore()` / `runSqlMigration()` under `GET_LOCK`), the expiry sweep, health check and Hub work there. **Neither database has row-level security**: tenant isolation is the store's, the boot warns once per source, and native / raw access on a tenant table must filter by tenant itself. Better-Auth is refused at boot while the user model lives there. An indexed text field is `varchar(255)` (longer: 400); a DDL run is not transactional. Still refused with a named `DataSourceConfigError`: a second MongoDB source, and an `ownerUrl` without `url` — what `NSC__DATABASE__OWNER_URL` leaves of a `database` given as a URL string, because the environment merge replaces the string with an object (write `database: { url }`, or set `NSC__DATABASE__URL` too). An update path the model does not declare is dropped on SQL as by MongoDB's strict mode (`CrudService.update()` adds `updatedBy` to every update with a current user). URLs appear in errors and logs as scheme + host only. Implementation: `common/persistence/data-source.config.ts`, `data-source.runtime.ts`, `sql/` (plan: `.claude/plans/db-agnostic/PLAN.md` §3.9) |
+| Multi-Tenancy | `multiTenancy` | Presence Implies Enabled | **`excludeSchemas` is an OFF SWITCH for isolation, per model** — a listed schema gets no tenant filter at all; since 11.35.0 the plugin WARNS once per model when the excluded schema declares `tenantId` (i.e. was built for isolation). The framework's own docs recommended `['User', 'Session']` until then; that is withdrawn — it is only right for the global-user model. Since 11.35.0 GraphQL operations over the WEBSOCKET also run inside a `RequestContext` (`CoreModule` installs a context-aware `execute`/`subscribe` pair inside `subscriptions`, where `ApolloDriver` forwards it): the tenant comes from the handshake header validated against an active membership, else from the subscriber's memberships, and an unresolvable tenant leaves the safety net to refuse the read rather than returning everything. `headerName: 'x-tenant-id'`, `membershipModel: 'TenantMember'`, `adminBypass: true`, `excludeSchemas: []`, `roleHierarchy: { member: 1, manager: 2, owner: 3 }`, `cacheTtlMs: 30000` (0 disables, process-local). System roles (`S_EVERYONE`, `S_USER`, `S_VERIFIED`) are checked as OR alternatives before real roles; method-level system roles take precedence; membership validated for context when system role grants access + header present. Hierarchy roles use level comparison, normal roles use exact match. Use `DefaultHR` or `createHierarchyRoles()` for type-safe role constants. Bypass: `RequestContext.runWithBypassTenantGuard()`. Cache invalidation: `invalidateUser(userId)` / `invalidateAll()` are **instance** methods on the singleton `CoreTenantGuard` — inject it and call `this.tenantGuard?.invalidateUser(userId)`, never `CoreTenantGuard.invalidateUser(...)` (there is no static). With `redis` configured, both additionally BROADCAST the invalidation to every replica (`<keyPrefix>:tenant-cache:invalidate` pub/sub); without Redis they clear the local process only, so other replicas stay stale until `cacheTtlMs`. A received broadcast clears locally without re-publishing. **`isTenantActive` (11.42.0)**: optional hook `(tenantId, { connection, store }) => boolean \| Promise<boolean>`, absent = every tenant active (no change). `store(modelName)` (12.x, db-agnostic) is the data store of a model registered with `CorePersistenceModule.forFeature()`, wherever `database` routes it, and THROWS for any other model — an `undefined` would read as "active" in a hook written with `?.` and open every deactivated tenant. Asked AFTER the membership check on every path that establishes a tenant: 403 on header paths and for tenant API tokens, no enrichment on `S_EVERYONE`, dropped from the header-less tenant list, no tenant for a NEW WebSocket subscription, and since 11.42.3 an OPEN one is closed with 4403 on `invalidateTenant()` (or at its next event once `graphQl.subscriptionRevalidationMs` has passed — see the GraphQL Subscription Re-check row); an admin under `adminBypass` is exempt (someone must be able to switch it back on). Only `false` deactivates. Cached for `cacheTtlMs`; `invalidateTenant(tenantId)` clears and broadcasts (`{ scope: 'tenant' }`). A function, so `config.env.ts` only — not reachable through `NSC__*`. **`adminBypass: false` (11.42.0)** additionally withholds two things that went around it: `CoreUserService.update()` refuses changing another account's e-mail or password (`assertCredentialChangeAllowed()`, administrator targets included — promote-then-change — system work without a current user exempt), and the AI tool registry grants no ADMIN bypass |
 | GraphQL Subscription Re-check | `graphQl.subscriptionRevalidationMs` | Numeric — `0` = STRICTEST, `false` = off, invalid → default (a fifth shape: Family C's "invalid never means unbounded", but `0` asks for MORE checking, not less) | **30000 since 11.42.3.** Before, a WebSocket was authorized once, at the handshake, and every event and operation on it ran on that snapshot until the client reconnected. Every connection a `CoreModule` `onConnect` accepts is now registered (`registerWsConnection()`) and re-checked — at once when an invalidation names it (`CoreTenantGuard.invalidateUser()` / `invalidateTenant()` / `invalidateAll()`, `CoreUserService.setRoles()` and role/verification `update()`s, the legacy password reset, and Better-Auth deleting a session through `wsSessionRevocationPlugin()`), and otherwise before the next event or operation once the last check is older than this value. The check re-runs the handshake's own authentication (session store, Better-Auth JWT signature/expiry, or for legacy tokens `CoreAuthService.verifyJwt()` — signature/expiry, verified on the WebSocket since 11.42.3 — plus the device binding) and the tenant resolution; any difference in user id, roles, verification state or tenant scope closes the socket with **4403**, which the graphql-ws client retries — the user continues with current rights or is refused at the handshake. `0` re-checks on every event and operation (one session lookup each); `false` switches only the TIME-based check off, invalidations still apply. Process-local registry: an invalidation reaches other replicas only where the tenant guard's Redis broadcast carries it; everything else is bounded by the interval. A project that replaces `onConnect` through `graphQl.driver.subscriptions` must call `registerWsConnection()` itself to keep this. Implementation: `common/helpers/graphql-ws-connection.helper.ts` |
 | API Tokens | `apiTokens` | Boolean Shorthand + Presence Implies Enabled — absent = off | `prefix: 'ltt'`, `scopes: []` (vocabulary; empty = no token creatable, boot warning), `manageRole`: highest hierarchy role, `maxAssertionLifetimeSeconds: 900` (invalid → default, never unbounded — Family C), `rateLimit: { max: 600, windowSeconds: 60 }` per token (**on by default**, `false` disables; Redis-shared when configured), `userTokens: true`, `tenantTokens: true` (effective only with `multiTenancy`), `encryptionKey` → `SECRETS_ENCRYPTION_KEY` → dev default (boot FAILS in production/staging). Top-level, NOT under `multiTenancy`: user tokens must work without it. **Deny by default**: every guard refuses a token on a route without `@ApiTokenScopes()`, public routes included, via ONE shared function (`enforceApiTokenRoute`) called BEFORE each guard's public-route shortcut. USER tokens act as their user with global roles REMOVED (no admin bypass); TENANT tokens act with the lowest hierarchy role in their own tenant, and a route guarded ONLY by `S_SELF` / `S_CREATOR` refuses them (a tenant token is nobody's self — skipping those roles would grant for any target). A tenant token depends on no member, so it outlives an off-boarded or deleted tenant until the project calls `deleteAllForTenant()`. The boot refuses a hierarchy in which that lowest role reaches `manageRole`. A prefixed credential that fails answers 401 on every route (not anonymous); `CoreBetterAuthMiddleware` skips prefixed credentials entirely, cookie fallback included. A password reset that ends the user's sessions ends their USER tokens too (legacy reset always; IAM reset while `betterAuth.emailAndPassword.revokeSessionsOnPasswordReset` is on), wired through `core-api-token.registry.ts` so neither reset path imports the optional module. Implementation: `src/core/modules/api-token/` |
 | BetterAuth Tenant Skip | `betterAuth.skipTenantCheck` | Explicit Boolean | `true` (default). When `true` and no `X-Tenant-Id` header is sent, IAM endpoints (controller + resolver) skip `CoreTenantGuard` tenant validation. When header IS present, normal membership validation runs regardless. Set `false` for tenant-aware auth scenarios (subdomain-based, invite links, SSO per tenant) |
@@ -332,7 +333,7 @@ This pattern is currently applied to:
 | Central Redis | `redis` | Boolean Shorthand + Presence Implies Enabled | `host: 'localhost'`, `port: 6379`, `db: 0`, `keyPrefix: <package.json name, slugified>` (per APPLICATION, not per framework — a constant default silently collides when two apps share one Redis; set it explicitly when sharing IS intended); `url` (takes precedence over host/port/db/credentials), `username`/`password`, `options` (passed to the ioredis constructor). `true` / `{}` enables with defaults; `{ enabled: false }` pre-configures without enabling; **absent = every consumer keeps its process-local fallback** (that fallback is the whole backward-compatibility story of 11.33.0). Requires the OPTIONAL peer `ioredis` — configured-but-missing **fails the boot** with a named error rather than crashing on first use. `keyPrefix` is applied by the framework per key, NOT as ioredis `keyPrefix` (that would collide with BullMQ's own prefix). One `CoreRedisService` serves all features: shared client (`getClient()`), one cached subscriber (`getSubscriber()` — a subscribing client cannot run commands), dedicated connections (`createClient(label)`); all are tracked and quit on shutdown. Switches on automatically: exact cross-replica rate limits via `RedisRateLimitStore` (see the Legacy Auth / BetterAuth / AI rate-limit rows), cron dedup (see Cron Job Deduplication row), `CoreRedisPubSub` as `PUB_SUB` for cluster-wide GraphQL subscriptions (**payloads must be JSON-serializable — `Date`, class instances, `Map`/`Set`, `undefined` do not survive**), tenant-cache invalidation broadcast, Hub collector mirroring, MCP session registry (turns a wrong-replica request from a misleading `404` into a `409` — `/ai/mcp` still REQUIRES sticky sessions, sessions are not portable) |
 | File Access Roles | `file.downloadRoles`, `file.uploadRoles`, `file.deleteRoles` | Config-Driven Role List | `[RoleEnum.ADMIN]` each. **These are the only breaking change a single-replica project gets in 11.33.0** — six members moved from `@Roles(S_EVERYONE)` to these knobs: `GET /files/id/:id`, `GET /files/:filename` and `getFileInfo` (`downloadRoles`), `uploadFile` / `uploadFiles` (`uploadRoles`), `deleteFile` (`deleteRoles`). Plain role STRINGS, not `RoleEnum` members, so project roles work (`['company-admin', 'editor']`). Applied at boot by `applyFileRoles()` via `Reflect.defineMetadata('roles', …)` on the base-class methods — the same runtime mechanism `CorePermissionsModule` uses, because the value is only known from config. **`[]`, a non-array, or an array holding a non-string is REJECTED with a warning and the default applies** — an all-empty role set reads to the guards as "no roles required" and would OPEN the route, the exact opposite of the intent. **ADMIN is always unioned in**: both `CoreFileController` and `CoreFileResolver` carry a class-level `@Roles(RoleEnum.ADMIN)` and the guards UNION class + handler metadata, so these knobs can grant but never exclude admins. Both classes also carry `@SkipTenantCheck()` — GridFS and the S3 metadata collection are reached outside Mongoose, so `mongooseTenantPlugin` never scopes them and a role name alone cannot express a per-tenant rule; roles resolve against `user.roles`, never `membership.role`. **A subclass that OVERRIDES a member opts out permanently** (decorator metadata lives on the function object, and an override is a different function) — inherit the member instead. **Since 11.35.1 that opt-out is REPORTED**: `CoreFileAccessAuditInitializer` reads the roles off the class the project actually registered at `onApplicationBootstrap` (the earliest point at which the route table exists, which is why it is a provider and not part of `applyFileRoles()`) and warns when a member is open beyond ADMIN for a reason the configuration cannot explain — the case the construction-time warning below is structurally blind to. It only REPORTS: overwriting an override's metadata, the way `TusModule.applyRoles()` does, would silently relax a route a project pinned on purpose. Roles are the coarse filter only; per-file rules belong in `CoreFileService.checkRights()`, which now receives `currentUser` and can read raw metadata via `getRawFileInfo()`. **Since 11.35.0 a reused FILENAME resolves to the most recent file** in all three stores (`uploadDate` desc, `_id` tie-break) and every by-name read path resolves a document and then reads by ID — under GridFS the by-name metadata lookup answered the oldest document while `openDownloadStreamByName()` served the newest, so a per-file rule approved one file and the bytes of another came back. Consequence: `duplicateById()` keeps the source's filename and the copy carries no metadata, so the copy now wins the name and an `ownerId` rule refuses it — give the copy its own metadata or its own name. **Since 11.35.0 `CoreFileService` WARNS at construction** when `multiTenancy` is active AND a knob names a role other than ADMIN AND `checkRights()` is not overridden — the file stores are reached outside Mongoose, so these role names resolve against `user.roles` (global) and every holder reaches every tenant's files; only `checkRights()` can narrow that. Silent on the admin-only default and silent when a per-file rule exists. Implementation: `src/core/modules/file/file-roles.config.ts` (`FILE_ROLE_DEFAULTS`, `FILE_ROLE_MEMBERS`, the three warnings, the shared `hasDeclaredFilePolicy()` silencer) + `file-roles.helper.ts` (`applyFileRoles`) + `core-file-access-audit.initializer.ts` (the registered-class audit) |
 | TUS Roles | `tus.roles` | Config-Driven Role List | `[RoleEnum.S_USER]` (was `S_EVERYONE` — breaking). A TUS upload writes into the SAME store the download routes guard, and the termination extension (on by default) can delete from it, so anonymous writes into a store only privileged callers may read is the wrong way round. Applied by `TusModule.applyRoles()` onto the registered controller class **and** onto `handleTus` / `handleTusWithId`. Same rejection rule as the file roles: `[]` / non-array / non-string → warning + `DEFAULT_TUS_CONFIG.roles`. **`OPTIONS` is deliberately exempt**: `handleTusOptions` / `handleTusOptionsWithId` keep their own handler-level `@Roles(RoleEnum.S_EVERYONE)`, because that is the CORS preflight — browsers send it WITHOUT credentials, and it returns server capabilities only. Gating it would make every browser upload fail before the first byte. `CoreTusController` also carries `@SkipTenantCheck()`. A custom controller is covered as long as it INHERITS the handlers; one that re-declares `@All()` / `@Roles()` carries its own metadata and thereby opts out — the documented way to hard-code a policy config must not be able to change. **Set `roles: [RoleEnum.S_EVERYONE]` explicitly if you accept attachments on a public form.** **Since 11.35.0 `tus.roles` is no longer the only gate**: `onUploadCreate` records the authenticated creator under `TUS_OWNER_METADATA_KEY` (`ltOwnerId`, always OVERWRITING any client-supplied value) and `onIncomingRequest` refuses HEAD/PATCH/DELETE naming an upload the caller does not own — with **404**, the file module's refusal policy. Before that, any authenticated caller who learned an upload id could APPEND BYTES to somebody else's upload, which are then migrated into the file store under the victim's filename. The finished file also gains `metadata.ownerId`, without which the documented per-file ownership rule could never authorize a tus-uploaded file (admin-only in practice). An OWNER-LESS upload stays reachable — uploads predating 11.35.0 have none, and neither does a deliberately public form. `readRequestUserId()` / `assertUploadOwnership()` are `protected`. **Since 11.41.9 the tenant is recorded too, but ONLY with `multiTenancy` configured** (not `enabled: false`) and a tenant guard registered: `onUploadCreate` validates the tenant header against the caller's active memberships through `core-tenant-context.registry.ts` (the routes carry `@SkipTenantCheck()`, so the guard did not), refuses a non-member with **403**, writes it under `TUS_TENANT_METADATA_KEY` (`ltTenantId`, always overwritten like the owner key) and the finished file gains `metadata.tenantId`. No header → tenant-less, as before; without `multiTenancy` nothing is read or written. A project hooks in through `TusModule.forRoot({ service })` (a `CoreTusService` subclass, constructed by the module as `(connection, options)` — project providers come from `options.moduleRef` at call time) and the `protected onUploadCreate(req, upload)`, the one point where `Upload-Length` is known and nothing is stored yet; an override must return `super.onUploadCreate()`. Note that `@tus/server` v2 hands its hooks a WHATWG `ServerRequest`, so a guard's `req.user` is reachable only via `runtime.node.req`. **CORS (11.42.1)**: the tus handler's `Access-Control-Allow-Origin` comes from `buildCorsConfig()` (or `tus.allowedOrigins`), plus `allowedCredentials` — without it `@tus/server` answered `*`, which browsers refuse on a credentialed request, so cookie-authenticated uploads across split app/API origins failed in every browser while the server answered 201; no credentialed CORS configured → the `*` default stays. **compression (11.42.2)**: `@tus/server` finishes responses with `res.end(callback)`, which `compression`'s two-argument `res.end(chunk, encoding)` patch reads as a chunk (`ERR_INVALID_ARG_TYPE … Received function`); with the starter's `filter: () => true, threshold: 0` every finished upload HUNG without an answer AFTER the file was stored (headers already sent, so no error response could follow). `CoreTusService` wraps `server.handle()` and normalises `res.end` per response (`normalizeEndCallback()`, callback on `finish`/`close`), so no `main.ts` change is needed. Implementation: `src/core/modules/tus/tus.module.ts`, `src/core/modules/tus/core-tus.service.ts`, `src/core/modules/tus/tus.constants.ts` |
-| File Storage | `file.storage` + `file.storageDir` + `s3` | Explicit Enum with DERIVED default | `'filesystem' \| 'gridfs' \| 's3'`. **Unset → derived**, most capable first: `'s3'` when `s3.bucket` is set, else `'gridfs'` when `mongoose.uri` is set, else `'filesystem'`. **Set → enforced**: an unavailable store FAILS THE BOOT (`assertFileStorageAvailable()`), it never falls back — a silent fallback puts files in a store the operator does not believe they are in, unrecoverably. A DERIVED driver is enforced too (`s3.bucket` set but `s3Service` not forwarded to `super()` → boot error). Metadata always lives in MongoDB whichever driver holds the bytes (`fs.files` / `s3-files` / `filesystem-files`) — it has to stay queryable for `findFileInfo()` and `checkRights()`. Reads consult ALL stores so switching drivers is forward-only with no migration; writes go to the active driver only. `'filesystem'` is pod-local: not shared between replicas, lost on restart unless `storageDir` is a mounted volume. `s3`: `bucket` (required — the one thing S3 cannot default, hence the eligibility test), `region: 'us-east-1'`, `forcePathStyle: false`, `autoCreateBucket: false` (off by design: production buckets come from infrastructure code, whose credentials usually cannot CreateBucket), `stagingBucket: bucket`, `presignedDownloads: false` (`true`/`{}` → `expiresInSeconds: 300`), `endpoint` (MinIO/RustFS), `accessKeyId`/`secretAccessKey` (omit → AWS default credential chain), `enabled: false` to pre-configure. Requires the OPTIONAL peer `@aws-sdk/client-s3`, plus `@aws-sdk/s3-request-presigner` for presigned downloads. **Uploads are never buffered on the S3 path** (11.41.7): a known length (`FileUploadSource.size`, TUS, a buffer) goes up as one streamed PutObject up to `CoreS3Service.MAX_SINGLE_PUT_BYTES` (5 GiB — AWS S3 refuses more in one request, `EntityTooLarge`) and as a multipart upload above it, an unknown one — every GraphQL and streamed REST upload — as a multipart upload via the OPTIONAL peer `@aws-sdk/lib-storage`. Missing peer → one boot warning and the old in-memory buffering, NOT a boot failure (multipart optimises a path that works without it). `size` must be the file's EXACT length — never a multipart request's `Content-Length`; anything but a positive integer counts as unknown (`isKnownUploadSize()`), and the recorded length of an unknown-length upload comes from a HEAD of the stored object. `presignedDownloads` makes `GET /files/id/:id` answer `302` to a time-limited S3 URL instead of streaming — the URL is a bearer capability, authorized once at issue time. The resolved driver is logged at boot (`[CoreFileStorage] File storage: …`) |
+| File Storage | `file.storage` + `file.storageDir` + `s3` | Explicit Enum with DERIVED default | `'filesystem' \| 'gridfs' \| 's3'`. **Unset → derived**, most capable first: `'s3'` when `s3.bucket` is set, else `'filesystem'` with `database: false` or when `database` routes the file metadata to a SQL source (`fileMetadataSqlSource()`; GridFS would put bytes and metadata into MongoDB — an explicit `'gridfs'` keeps working), else `'gridfs'` when `mongoose.uri` is set, else `'filesystem'`. **Set → enforced**: an unavailable store FAILS THE BOOT (`assertFileStorageAvailable()`), it never falls back — a silent fallback puts files in a store the operator does not believe they are in, unrecoverably. A DERIVED driver is enforced too (`s3.bucket` set but `s3Service` not forwarded to `super()` → boot error). Metadata stays queryable whichever driver holds the bytes (`fs.files` / `s3-files` / `filesystem-files`, the latter two as the tables `s3_files` / `filesystem_files` when `database` routes them to a SQL source) — `findFileInfo()` and `checkRights()` need it. Reads consult ALL stores so switching drivers is forward-only with no migration; writes go to the active driver only. `'filesystem'` is pod-local: not shared between replicas, lost on restart unless `storageDir` is a mounted volume. `s3`: `bucket` (required — the one thing S3 cannot default, hence the eligibility test), `region: 'us-east-1'`, `forcePathStyle: false`, `autoCreateBucket: false` (off by design: production buckets come from infrastructure code, whose credentials usually cannot CreateBucket), `stagingBucket: bucket`, `presignedDownloads: false` (`true`/`{}` → `expiresInSeconds: 300`), `endpoint` (MinIO/RustFS), `accessKeyId`/`secretAccessKey` (omit → AWS default credential chain), `enabled: false` to pre-configure. Requires the OPTIONAL peer `@aws-sdk/client-s3`, plus `@aws-sdk/s3-request-presigner` for presigned downloads. **Uploads are never buffered on the S3 path** (11.41.7): a known length (`FileUploadSource.size`, TUS, a buffer) goes up as one streamed PutObject up to `CoreS3Service.MAX_SINGLE_PUT_BYTES` (5 GiB — AWS S3 refuses more in one request, `EntityTooLarge`) and as a multipart upload above it, an unknown one — every GraphQL and streamed REST upload — as a multipart upload via the OPTIONAL peer `@aws-sdk/lib-storage`. Missing peer → one boot warning and the old in-memory buffering, NOT a boot failure (multipart optimises a path that works without it). `size` must be the file's EXACT length — never a multipart request's `Content-Length`; anything but a positive integer counts as unknown (`isKnownUploadSize()`), and the recorded length of an unknown-length upload comes from a HEAD of the stored object. `presignedDownloads` makes `GET /files/id/:id` answer `302` to a time-limited S3 URL instead of streaming — the URL is a bearer capability, authorized once at issue time. The resolved driver is logged at boot (`[CoreFileStorage] File storage: …`) |
 | TUS S3 Staging | `tus.s3Staging` | Explicit Boolean (default ON when S3 configured) | `true` when `s3` is configured, otherwise inert. Stages in-progress uploads in `s3.stagingBucket` via `@tus/s3-store` instead of `tus.uploadDir` on local disk, so resumable uploads survive replica restarts and need no sticky sessions. Set `false` to force local disk. Missing OPTIONAL peer `@tus/s3-store` → warning + fall back to local disk (NOT a boot failure). **Give the staging bucket a lifecycle rule expiring incomplete multipart uploads** — the framework's own expiration cleanup is skipped in S3 mode (S3 is the right place for that policy), so aborted uploads otherwise accumulate parts nothing removes |
 | TUS Configuration Source, Path & Extensions | `tus` (server config) / `TusModule.forRoot({ config })` | Enabled by Default + explicit-config-wins | **Since 11.42.9 `TusModule.forRoot()` without `config` reads the server config's `tus` key** (`ConfigService.get('tus')`, the zero-config rule `CoreBetterAuthModule.forRoot()` follows); an explicit `config` wins. Before, the key was never read: `tus: false`, `allowedTypes`, `maxSize`, `roles` in `config.env.ts` did nothing — real projects had upload restrictions they believed were enforced. **`path`** has three readings (`applyPath()`): unset → follows the controller's route; a new route (`/uploads`) → mounts the registered controller there (writes `PATH_METADATA`, config wins like the roles; the declared route is remembered per class and restored by a later `forRoot()` without `path`); a path ENDING with the controller's route (`/api/tus`, `/files/tus`) → the PUBLIC URL: the controller stays and upload URLs use it. The third reading is load-bearing: it was the only working setting under a global prefix or a prefix-stripping proxy before 11.42.9, and treating it as a route doubled the prefix (`/api/api/tus`, 404 on every upload — caught in the second pre-release review). The upload URL (`Location`) is built from the path the creation request arrived at (`uploadCollectionPath(req)`), or from `path` when that is longer and ends with it (proxy strip); `@tus/server` built it from `path` alone, which broke every resume below a global prefix, a URI version or a project route. **`relativeLocation`** (new): the framework owns `generateUrl`, which takes precedence over `@tus/server`'s option of that name, so it is honoured from `tus.relativeLocation` AND from the tus server's own options (a vendored core may pass it there). **Extensions**: `@tus/server` consults no flag, so `creation`, `creationWithUpload` and `termination` are enforced by `CoreTusService` — the store's advertised `extensions` are narrowed, and `assertExtensionEnabled()` answers 501 inside the server's `onIncomingRequest` / `onUploadCreate` options (not in the overridable hook, so an override without `super` cannot reopen it). `checksum` / `concatenation` have no effect: neither built-in store supports them. `configure(false)` now yields a DISABLED config (before it kept the defaults and started a tus server behind a module with no endpoint). Implementation: `tus.module.ts`, `core-tus.service.ts` |
 | Health Check | `healthCheck` | Presence Implies Enabled | Absent → no endpoints. Any object registers `GET /health-check` + the `healthCheck` query; **`enabled: false` leaves them out (honoured since 11.42.9 — before, it was declared and ignored)**. Individual checks under `configs.*` each have their own `enabled`. Implementation: `core.module.ts` |

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

@@ -171,8 +171,10 @@ Package overrides live in the `overrides:` section of **`pnpm-workspace.yaml`**
 **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 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
+and they were removed, leaving `@graphql-tools/utils` and `multer`, both on an upstream EXACT pin with
+an open advisory. Those two left on 2026-10-29 (nest-server 12.1.0), once `@nestjs/graphql` 14.1.0 and
+`@nestjs/platform-express` 12.3.2 moved their pins past the fixes: **the set is empty** (`overrides: {}`,
+written explicitly so `check:overrides` reads it as a decision). 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.
@@ -337,6 +339,26 @@ on `FIX AVAILABLE` (a `first_patched_version` now exists) or on a withdrawn advi
 API is reported as `UNVERIFIED` and tolerated locally — but **fails under `CI`**, because a skip
 nobody reads is indistinguishable from a check that ran.
 
+**A fix nobody named is still a fix.** GitHub leaves `first_patched_version` null on some advisories
+after a release outside the vulnerable range shipped: GHSA-86w9-cpqp-85rv (node-forge) read
+`<= 1.4.0` / null a day after 1.4.1 was published. Until 12.0.x the guard skipped such an advisory,
+so its suppression passed every run. It now reads the package's packument from the registry pnpm
+installs from and, per vulnerable copy in the lockfile, looks for a stable release above it that
+lies outside **every** range the advisory lists. A deprecated release is held back, not ruled out: it
+counts only when every such release is deprecated, because some packages deprecate all of them
+(node-sass: 132 of 132 stable releases), and ruling them out reads a published fix as "no fix" for good.
+
+| Finding | Verdict |
+|---------|---------|
+| every copy has such a release, past `minimumReleaseAge` | `FIX AVAILABLE`, naming it — `unusableFixConsumers` applies as for a named fix |
+| one is published but younger than `minimumReleaseAge` | passes, printed as `pending` with the date the gate clears (pnpm would refuse it, so failing would order a `minimumReleaseAgeExclude` nobody decided on) |
+| some copy has none | passes — the suppression is still justified |
+| no version the lockfile resolves is in the range any more | `NOT IN TREE` — the entry hides nothing |
+| registry or lockfile unreadable | `UNVERIFIED`, with the reason (fails under `CI`) |
+
+`--advisory-file` runs stay offline: they take packuments from `--packument-file` and never ask the
+registry.
+
 One consequence worth knowing before you reach for this mechanism: the guard fires when the advisory
 has a patched version for **any** affected range. For most findings that is the honest outcome — a
 fix exists, take it, and the case is an override problem rather than a suppression problem.

package/.claude/rules/persistence.md

@@ -0,0 +1,100 @@
+# Persistence Rules (MongoDB, PostgreSQL, MySQL and MariaDB)
+
+These rules apply to every model, service and query — in `src/core/` and in projects. The design and its
+reasoning are in `.claude/plans/db-agnostic/PLAN.md` (framework repository); which database a project uses is decided by
+`docs/choosing-a-database.md`; the configuration reference is the "Data Sources" row of
+`.claude/rules/configurable-features.md`.
+
+## One pipeline, one store per model
+
+`CrudService` runs every call through the same security pipeline (`process()`) and hands the database work to the
+model's **data store** (`DataStore<T>`, `common/persistence/data-store.interface.ts`): `MongooseDataStore` on MongoDB,
+`SqlDataStore` on PostgreSQL, `MysqlDataStore` (the same policies, MySQL's statements) on MySQL and MariaDB. What else
+differs per SQL database — schema, role check, leases — is the source's `SqlDialect` (`sql/sql-dialect.ts`). A model
+reaches its store by being registered with
+`CorePersistenceModule.forFeature([{ name, schema, model }])`; `database` routes it to a source.
+
+| Do | Never |
+|---|---|
+| Register a model with `CorePersistenceModule.forFeature()` | `MongooseModule.forFeature()` for a model that may live in SQL — it stays on MongoDB and nothing routes it |
+| Declare models with the framework's `Schema`, `Prop`, `SchemaFactory`, `InjectModel` (from `@lenne.tech/nest-server`, or `common/persistence/mongo/mongoose-compat.js` inside the core) | Import them from `@nestjs/mongoose` in the core — the core must load where MongoDB's libraries are not installed (`pnpm run check:without-mongodb`) |
+| Reach a model through `this.dataStore` in a `CrudService`, or `@InjectStore(Model)` elsewhere | Call `this.mainDbModel.find(…)` — on a model routed to SQL the Mongoose model refuses every data method (`routed-model.guard.ts`) |
+| Write ids as 24-hex strings (`generateId()`, `newObjectId()`, `isObjectIdLike()`) | `new Types.ObjectId()` / `instanceof Types.ObjectId` in the core — Mongoose may not be installed |
+| Query with the Mongo-operator subset the SQL compiler supports (`$eq $ne $gt $gte $lt $lte $in $nin $exists $type $regex $not $and $or $nor $elemMatch $all $size`, dotted paths) | Build an aggregation pipeline for something the port offers (`count`, `sum`, `distinct`, `find` with `sort` / `skip` / `limit` / `sample`) |
+
+## MongoDB's libraries are optional peers (12.1.0+)
+
+`mongoose`, `@nestjs/mongoose` and `mongodb` are loaded through `common/persistence/mongo/mongo-packages.ts` — never by
+a static value import in `src/core/`. `import type` is fine (erased), and so is the compat module, which records each
+declaration and applies the real decorator where Mongoose is installed.
+
+| Need | Use |
+|---|---|
+| The packages, where a feature cannot work without them (GridFS, a MongoDB migration) | `requireMongoPackages('<feature, in configuration words>')` — throws `MongoPackagesMissingError` naming what to install |
+| Whether they are there | `optionalMongoPackages()` / `hasMongoPackages()` |
+| A GridFS bucket | `createGridFsBucket(db, { bucketName })` |
+| A Mongoose query check | `isMongooseQuery(value)` |
+| An inline schema (no class) | `createSchema(definition, options)`; free-form fields `{ type: Object }` |
+| An ObjectId field type in a decorator | `objectIdType()` |
+
+Where Mongoose is not installed, a model's descriptor comes from what its decorators recorded
+(`mongo/model-declarations.ts`), read through `mongo/declared-schema.view.ts`, which builds paths and indexes exactly
+as Mongoose would. `tests/unit/persistence-model-descriptor.spec.ts` proves both sources agree for every shipped
+model — **a new model the framework ships goes into `SHIPPED_MODELS` there.**
+
+`CoreModule` connects MongoDB only when a source uses it (`usesMongoDb()`); otherwise `NoMongoConnectionModule`
+provides `null` for the connection token, and `@InjectConnection()` receives `null`. A service that uses the connection
+on its MongoDB path checks it.
+
+## Native access in three tiers
+
+| Tier | API | What still protects the data |
+|---|---|---|
+| 1 | `CrudService` / `DataStore` | everything: before-layer policies, database layer (RLS on PostgreSQL), tenant row check, output pipeline |
+| 2 | `store.native(reason)` — the engine's own API, bound to the store's transaction | MongoDB: the Mongoose plugins. PostgreSQL: row-level security (same connection). MySQL / MariaDB: **nothing in the database**. HTTP interceptors |
+| 3 | `store.raw(reason)` / `getNativeConnection(reason)` | PostgreSQL: row-level security. HTTP interceptors. Nothing else |
+
+`reason` is mandatory and logged. Parameters only — an identifier (table, column) never comes from user input.
+
+**MySQL and MariaDB: tenant isolation is the application's.** Neither database has row-level security, and a trigger
+guard was measured and rejected (plan, phase 6). On these sources a tier-2/3 query on a tenant-scoped table MUST filter
+by `tenantId` (and a write MUST set it) itself — a review treats a missing filter there as a cross-tenant leak, not a
+style issue. The boot warns once per source.
+
+## High-frequency paths
+
+The "use direct Mongoose in system-internal hot paths" advice in `CLAUDE.md` applies to MongoDB, where the Mongoose
+plugins still fire on `Model.create()` / `findByIdAndUpdate()`. The database-neutral form of the same advice is the
+data store: `this.dataStore.insert()`, `updateById()`, `findById()`, `pushToArray()` skip `process()` (no cloning, no
+output pipeline) and keep every policy — on MongoDB through the plugins, on PostgreSQL in the store. Prefer the store in
+new code; it is the fast path on both databases.
+
+## Schema on SQL
+
+The framework creates and evolves tables from the model descriptors when a store is created, as the **owner** role:
+new tables, columns, indexes and grants are applied; anything that could lose or reject data (type change, new unique
+index, a rename collision, a table losing tenant isolation) stops the boot with the suggested statements — write a
+migration (`migrate create <name> --sql`, `runSqlMigration()`). Declare a renamed field with
+`@UnifiedField({ renamedFrom: 'oldName' })`. Never enable an engine's own `synchronize` or migration generator.
+
+On MySQL / MariaDB a text field that is part of an index is `varchar(255)` (a longer value: 400), every other text
+`longtext` — so adding an index to an existing text field is a type change. An index over more than 3072 bytes indexes a
+prefix when it is a lookup index and is refused when unique. DDL commits on its own there: a run is serialized by
+`GET_LOCK`, not a transaction, and a failed change leaves the statements before it applied.
+
+## Updates on MySQL / MariaDB
+
+Two operators on one path, or on a path and a path inside it, are refused (`Updating the path … would create a
+conflict`) — MongoDB's own rule; PostgreSQL chains them. Write such an update as one operator per path.
+
+On every SQL database a path segment `__proto__`, `constructor` or `prototype` is refused: a compiler that builds an
+object from path segments would otherwise reach `Object.prototype` — on MySQL that switched tenant isolation off for the
+whole process. Never build an update path from request data without validating it against the model.
+
+## Tests
+
+A suite proves a behaviour on both databases: the `e2e` vitest project runs it on MongoDB, the `postgres` project on
+PostgreSQL (`.claude/rules/testing.md`). MySQL and MariaDB are proven through the matrices (persistence, core modules,
+where parity) and their own suites, not by a third run of the whole e2e suite. Read and prepare data through `tests/helpers/iam-test-db.ts` or the
+application's stores — never through a MongoDB client of the suite's own, which reads the wrong database on
+PostgreSQL. A contract with several implementations is a matrix (`tests/helpers/persistence-matrix.ts`).

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

@@ -417,6 +417,15 @@ otherwise lets the role guard check `user.roles` — fail-closed, warned once. P
 **Configured is not registered.** When you add a guard that delegates to another one, ask whether
 the other one RUNS, not whether it is configured.
 
+**Registered is not ordered (DEV-3830).** Global guards run in registration order, and `CoreModule` registers
+`CoreTenantModule` ahead of a project's `AuthModule` — so with legacy JWTs (no middleware identifies them) the tenant
+guard ran before the role guard, found nobody on the request and answered every tenant route with 401. Never noticed
+because every multi-tenant suite signed in through IAM, where the middleware sets the user first. The tenant guard now
+lets the application's role guard identify the caller when nobody is on the request yet (`ROLE_GUARD` token, provided by
+the module that registers the role guard, resolved through `ModuleRef` so it is always THIS application's guard). The
+role guard then runs twice on such a request; it is stateless, and its 401/403 is the answer either way. Pinned by
+`tests/core-module-parity.e2e-spec.ts` (mutation `tenant-guard-before-identification`).
+
 ## Every entry point, not just the route (11.42.0)
 
 A `@Roles()` decides who may call a ROUTE. An operation is also reached from MCP tools, AI tools,

package/.claude/rules/testing.md

@@ -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
@@ -212,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
@@ -273,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 185 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>
 ```
 
@@ -292,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 274 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 —
@@ -337,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 89 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, 274 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**.
 
@@ -735,11 +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