@lenne.tech/nest-server 11.43.3 → 12.1.0

package/docs/choosing-a-database.md

@@ -0,0 +1,107 @@
+# Choosing a database
+
+Since 12.1.0 a `@lenne.tech/nest-server` project stores its data in **MongoDB** (the default), in **PostgreSQL**, in
+**MySQL 8.4 / MariaDB 11.8**, or in several of them, model by model. The framework's own modules (users, tenants, API
+tokens, AI, file metadata, locks, migrations) run on each, behind one `CrudService` and one security pipeline;
+Better-Auth runs on MongoDB and PostgreSQL. This document is the decision
+procedure — for a developer starting a project and for an AI agent asked to set one up. Configuration details are in
+`.claude/rules/configurable-features.md` (row "Data Sources"); the code rules in `.claude/rules/persistence.md`.
+
+## The procedure
+
+Work through the steps in order; the first one that decides, decides.
+
+1. **An external requirement wins.** The customer's operations team runs one database, a hosting contract names one,
+   an existing system the project must read is one: take that database. Nothing below outweighs it.
+2. **PostgreSQL** when the data is relational or reported on — accounting, invoices, bookings, inventory,
+   anything with joins, sums across records or reports a finance team reads — or when **tenant isolation must be
+   enforced by the database itself**. On PostgreSQL every tenant-scoped table carries forced row-level security, so
+   a query that forgets its tenant returns nothing instead of every tenant's rows; MongoDB has the framework's two
+   application layers only.
+3. **MongoDB** (the default) for document-shaped data — nested content, free-form attributes, structures that change
+   per customer — and whenever the signals above are absent. An existing MongoDB project stays on MongoDB: moving
+   databases is a data migration, not a configuration change.
+4. **Both (hybrid)** only with a concrete reason, written down: e.g. the finance models in PostgreSQL while the
+   content stays in MongoDB. The cost is real — two databases to run, back up and monitor, no transaction across
+   them, references across them resolved in the application. Route per model with `database.models`.
+5. **MySQL / MariaDB** only when required by step 1. What a project gives up there, and has to write into its own
+   documentation:
+   - **Tenant isolation lives in the application only.** Neither database has row-level security: the store's
+     policies keep tenants apart, and a query through `store.native()`, `store.raw()` or a connection of the project's
+     own reaches every tenant's rows unless it filters by `tenantId` itself. The boot says so once per source. A
+     trigger-based write guard was measured and not built: it cost up to half of MariaDB's write throughput and left
+     the native read open.
+   - **Better-Auth does not run there yet:** keep the user model (`users`) on PostgreSQL or MongoDB
+     (`database.models`), or sign in through the legacy endpoints only. The boot refuses the combination.
+   - **An indexed text field holds at most 255 characters** (a longer value is refused with 400); every other text is
+     unbounded. Indexing an existing text field later is a type change, i.e. a reviewed migration.
+   - **Schema changes are not transactional:** MySQL commits every DDL statement on its own, so a failed change leaves
+     the statements before it applied; the next boot completes the rest.
+6. **No database** (`database: false`) for a stateless service: a gateway, a renderer, a worker that only talks to
+   other APIs.
+
+When the signals are ambiguous, **ask** — and record the decision (database, SQL engine, date, reason) in the
+project's `CLAUDE.md`, so the next developer or agent does not re-decide it.
+
+## The SQL engine
+
+On every SQL database the framework compiles every query itself; the engine only carries the statements, so the
+choice does not change behaviour, tables or security — switching later is configuration only (`database.sqlEngine`).
+All three engines run on PostgreSQL, MySQL and MariaDB.
+
+| Engine | When |
+|---|---|
+| **TypeORM** (default) | unless the team asks for another — the widest ecosystem |
+| **Kysely** | the team writes typed SQL by hand in its own code and wants the builder it knows |
+| **Drizzle** | the team already uses Drizzle elsewhere (pinned to an exact release candidate until 1.0 GA) |
+
+Each engine is an optional peer dependency installed together with the database's driver (`pg`, or `mysql2` for MySQL
+and MariaDB). Project code that uses an engine's native API (`store.native()`) is the one part that does not move with a
+switch.
+
+## What a project installs
+
+| Database | Packages |
+|---|---|
+| MongoDB | `mongoose`, `@nestjs/mongoose`, `mongodb` (optional peers since 12.1.0 — the starter declares them) |
+| PostgreSQL | `pg` plus the engine (`typeorm`, `kysely` or `drizzle-orm`) — and **none** of MongoDB's packages (npm mode; a vendor-mode project keeps the three as `devDependencies`, because the vendored core imports their types) |
+| MySQL / MariaDB | `mysql2` plus the engine — the same rule for MongoDB's packages as on PostgreSQL |
+
+In **vendor mode** the core is the project's own source, and TypeScript resolves every package it names in an
+`import()` — whatever database the project uses. A vendor project therefore declares `pg` (with `@types/pg`), `mysql2`,
+`typeorm`, `kysely` and `drizzle-orm` (at least as `devDependencies`), or its build fails with TS2307. At runtime it loads only
+what its configuration uses.
+| Several | the sets combined |
+
+A project on PostgreSQL alone declares its models with the framework's own decorators, imported from
+`@lenne.tech/nest-server` rather than `@nestjs/mongoose` (`Schema`, `Prop`, `SchemaFactory`, `InjectModel`), and
+registers them with `CorePersistenceModule.forFeature()`. The same file works on MongoDB unchanged.
+
+## Configuration in one line each
+
+```typescript
+// MongoDB (default) — nothing to configure beyond `mongoose`
+mongoose: { uri: 'mongodb://127.0.0.1/project' }
+
+// PostgreSQL: the application role, and the owner role that migrates the schema
+database: { url: 'postgres://app@db/project', ownerUrl: 'postgres://owner@db/project', sqlEngine: 'typeorm' }
+
+// MySQL 8.4 or MariaDB 11.8: the scheme names the server (mysql:// or mariadb://)
+database: { url: 'mysql://app@db/project', ownerUrl: 'mysql://owner@db/project' }
+
+// Hybrid: PostgreSQL by default, these models in the project's MongoDB
+database: { url: 'postgres://app@db/project', ownerUrl: '…', models: { Article: 'mongoose' } },
+mongoose: { uri: 'mongodb://127.0.0.1/project' }
+
+// No database
+database: false
+```
+
+PostgreSQL always runs with **two roles**: the owner creates and migrates the schema, the application role owns
+nothing and has neither superuser nor `BYPASSRLS` — the boot refuses an application role that could bypass row-level
+security. PostgreSQL 15 or newer.
+
+MySQL and MariaDB run with **two accounts** too: the owner creates and migrates the schema and grants the application
+account `SELECT, INSERT, UPDATE, DELETE` on the database once; the boot refuses an application account that may alter,
+drop, index, trigger or grant — without row-level security, the tables and their constraints are what the store's
+policies rely on. MySQL 8.4 / MariaDB 11.8 or newer, and the URL's scheme must name the server it reaches.

package/docs/native-driver-security.md

@@ -135,6 +135,31 @@ this.getNativeConnection('');          // throws Error
 
 ---
 
+## Native access on PostgreSQL (12.1.0+)
+
+On a model routed to PostgreSQL there is no Mongoose model and no native collection: `getNativeCollection()` /
+`getNativeConnection()` refuse, and so does every Mongoose data method of the model (`routed-model.guard.ts`). The data
+store has the two native tiers instead, with the same mandatory, logged reason:
+
+| Tier | API | What still protects the data |
+|---|---|---|
+| 2 | `this.dataStore.native(reason)` — the engine's own API (TypeORM `EntityManager`, Kysely, Drizzle), bound to the store's transaction | row-level security (same connection, tenant scope set), HTTP interceptors |
+| 3 | `this.dataStore.raw(reason)` — raw SQL on that connection | row-level security, HTTP interceptors |
+
+The framework's before-layer policies (tenant stamping, audit fields, password hashing, role guard, system roles) do
+**not** run on tiers 2 and 3 — exactly as the Mongoose plugins do not run on the native MongoDB driver. Row-level
+security does: a query without a tenant scope on a tenant-scoped table fails (42501 → 403) instead of reading every
+tenant. Parameters only; a table or column name never comes from user input.
+
+**On MySQL and MariaDB there is no row-level security** — tiers 2 and 3 have nothing below them but the HTTP
+interceptors. A native or raw query on a tenant-scoped table reaches every tenant's rows unless it filters by
+`tenantId` itself, and a native write is not stamped with a tenant. The boot warns once per source; the persistence
+matrix asserts the difference (`native-api-tenant-refused`, DIFFERENT-BY-DESIGN for those columns).
+
+Rules for all of it: `.claude/rules/persistence.md` → "Native access in three tiers".
+
+---
+
 ## Review Checklist
 
 When reviewing code (manual or AI), check for `.collection.` and `.db.collection(`:
@@ -150,4 +175,8 @@ When reviewing code (manual or AI), check for `.collection.` and `.db.collection
    → Are data being written?
      YES → Verify tenantId/audit is set manually.
      NO  → Allowed (read-only).
+
+3. Is it store.native() / store.raw() on a MySQL or MariaDB source, on a tenant-scoped table?
+   → Every statement filters by tenantId (read) or sets it (write) itself — the database does not.
+     MISSING → Security violation: the query reaches every tenant. Use the store (tier 1).
 ```

package/docs/security-overrides.md

@@ -16,10 +16,30 @@ used to **exact-pin**, to a vulnerable version:
 
 | Package | Advisory | Why it cannot resolve forward on its own |
 |---------|----------|------------------------------------------|
-| `ws` | [GHSA-96hv-2xvq-fx4p](https://github.com/advisories/GHSA-96hv-2xvq-fx4p) — high: memory-exhaustion DoS + uninitialized memory disclosure. Patched `>=8.21.0` | Older `@nestjs/graphql` releases declare `"ws": "8.20.1"` — an **exact pin**, not a caret. 13.4.5, the version this framework declares, pins `8.21.3` |
-| `js-yaml` | [GHSA-pm4m-ph32-ghv5](https://github.com/advisories/GHSA-pm4m-ph32-ghv5) — high: exponential parsing time in flow collections (DoS), patched `>=5.2.2`; [GHSA-r3ph-w7gj-g6xm](https://github.com/advisories/GHSA-r3ph-w7gj-g6xm) — moderate: `maxTotalMergeKeys` does not bound CPU use for empty merge sources, covers `<=5.4.0`, patched `>=5.4.1` (published 2026-09-29) | `@nestjs/swagger` declares js-yaml as an **exact pin**, the same shape as the `ws` case: older releases `5.2.1`, 11.4.7 — the version this framework declares, and the newest 11.x — `5.3.0`. No swagger update reaches the fix, so **this entry is load-bearing again** |
-| `@graphql-tools/utils` | [GHSA-7mx3-vvmw-hjmv](https://github.com/advisories/GHSA-7mx3-vvmw-hjmv) — high: prototype pollution in `mergeDeep`, which runs while the GraphQL schema is assembled. Covers `<=12.0.0`, patched `>=12.0.1` (added 2026-10-06) | `@nestjs/graphql` 13.4.5 — the version this framework declares, and the newest 13.x — declares `"@graphql-tools/utils": "12.0.0"`, an **exact pin**. Only `@nestjs/graphql` 14.x moves it, so **this entry is load-bearing**. `@apollo/server` reaches it too, through `@graphql-tools/schema` / `merge` — and in a lockfile that still holds schema 10.0.x (resolved before 2026-08-12), as **utils 11.x**: vulnerable too, with no 11.x fix, and outside the override key. Lift it with `pnpm update --depth Infinity @graphql-tools/schema @graphql-tools/merge`; the current releases request utils `^12.0.3`, which needs Node >=22.15 — the framework's own floor since 11.42.10, which is why the snippet below targets 12.0.3 |
-| `multer` | [GHSA-wc9g-mqfw-jrwm](https://github.com/advisories/GHSA-wc9g-mqfw-jrwm), [GHSA-535w-7cp7-47q4](https://github.com/advisories/GHSA-535w-7cp7-47q4), [GHSA-qfvm-cv95-jqjf](https://github.com/advisories/GHSA-qfvm-cv95-jqjf) — high: DoS via crafted multipart input; [GHSA-qvfw-j98x-7q72](https://github.com/advisories/GHSA-qvfw-j98x-7q72) — low: file size limit bypass. Patched `>=2.3.0` | `@nestjs/platform-express` up to 11.2.5 declares `"multer": "2.2.0"` — an **exact pin**. A direct `multer` dependency does not move it: you get both copies, and FileInterceptor uses the vulnerable one. 11.2.6, which this framework declared from 11.41.4, pins `2.4.0`, and so does 11.2.7, declared since 11.41.7 |
+| `ws` | [GHSA-96hv-2xvq-fx4p](https://github.com/advisories/GHSA-96hv-2xvq-fx4p) — high: memory-exhaustion DoS + uninitialized memory disclosure. Patched `>=8.21.0` | Older `@nestjs/graphql` releases declare `"ws": "8.20.1"` — an **exact pin**, not a caret. 13.4.5 pins `8.21.3`; 14.0.3, the version this framework declares since 12.0.0, pins `8.22.0` |
+| `js-yaml` | [GHSA-pm4m-ph32-ghv5](https://github.com/advisories/GHSA-pm4m-ph32-ghv5) — high: exponential parsing time in flow collections (DoS), patched `>=5.2.2`; [GHSA-r3ph-w7gj-g6xm](https://github.com/advisories/GHSA-r3ph-w7gj-g6xm) — moderate: `maxTotalMergeKeys` does not bound CPU use for empty merge sources, covers `<=5.4.0`, patched `>=5.4.1` (published 2026-09-29) | `@nestjs/swagger` declares js-yaml as an **exact pin**, the same shape as the `ws` case: older releases `5.2.1`, 11.4.7 — the newest 11.x — `5.3.0`, which no 11.x update moves, so the entry is **load-bearing on @nestjs/swagger 11**. 12.0.3, the version this framework declares since 12.0.0, pins `5.5.0`, which clears both advisories: on @nestjs/swagger 12 the entry is inert |
+| `@graphql-tools/utils` | [GHSA-7mx3-vvmw-hjmv](https://github.com/advisories/GHSA-7mx3-vvmw-hjmv) — high: prototype pollution in `mergeDeep`, which runs while the GraphQL schema is assembled. Covers `<=12.0.0`, patched `>=12.0.1` (added 2026-10-06); [GHSA-c4qx-w738-7hr3](https://github.com/advisories/GHSA-c4qx-w738-7hr3) — high: prototype pollution in `mergeIncrementalResult` via non-primitive path segments. Covers `>=10.10.1 <=12.0.1`, patched `>=12.0.2` (published 2026-10-22) | `@nestjs/graphql` declares utils as an **exact pin**: 13.4.5 — the newest 13.x — `12.0.0`, and 14.0.3, the version this framework declares since 12.0.0, `12.0.1`. 12.0.1 clears the first advisory and is covered by the second, so **this entry is load-bearing on 13.x and on 14.0.x**. 14.1.0, the version this framework declares since 12.1.0, pins `12.1.0`, which clears both: there the entry is inert. `@apollo/server` reaches utils too, through `@graphql-tools/schema` / `merge` — and in a lockfile that still holds schema 10.0.x (resolved before 2026-08-12), as **utils 11.x**: vulnerable too, with no 11.x fix, and outside the override key. Lift it with `pnpm update --depth Infinity @graphql-tools/schema @graphql-tools/merge`; the current releases request utils `^12.1.0`, which needs Node >=22.15 — the framework's own floor since 11.42.10 |
+| `multer` | [GHSA-wc9g-mqfw-jrwm](https://github.com/advisories/GHSA-wc9g-mqfw-jrwm), [GHSA-535w-7cp7-47q4](https://github.com/advisories/GHSA-535w-7cp7-47q4), [GHSA-qfvm-cv95-jqjf](https://github.com/advisories/GHSA-qfvm-cv95-jqjf) — high: DoS via crafted multipart input; [GHSA-qvfw-j98x-7q72](https://github.com/advisories/GHSA-qvfw-j98x-7q72) — low: file size limit bypass. Patched `>=2.3.0`; [GHSA-q7qp-rjg7-q26m](https://github.com/advisories/GHSA-q7qp-rjg7-q26m) — high: DoS via a pending asynchronous `fileFilter` after request teardown. Covers `>=2.0.0 <2.5.0`, patched `>=2.5.0` (published 2026-10-22) | `@nestjs/platform-express` declares multer as an **exact pin**: up to 11.2.5 `2.2.0`, 11.2.6 / 11.2.7 `2.4.0`, and so does 12.2.0, the version this framework declared in 12.0.x. 2.4.0 is covered by GHSA-q7qp-rjg7-q26m, so **this entry is load-bearing up to @nestjs/platform-express 12.2.0**. 12.3.2, the version this framework declares since 12.1.0, pins `2.5.0`: there the entry is inert. A direct `multer` dependency does not move the pin: you get both copies, and FileInterceptor uses the vulnerable one |
+
+**Status since 12.1.0** (verified 2026-10-29): with the `@nestjs/*` versions this framework declares, **no
+entry is needed**. `@nestjs/platform-express` 12.3.2 pins `multer` 2.5.0 and `@nestjs/graphql` 14.1.0 pins
+`@graphql-tools/utils` 12.1.0, both past their advisories, and nest-server's own `overrides:` block is empty:
+a fresh resolve of its tree with and without the two entries below yields the same packages and the same
+audit. Raise your project's `@nestjs/*` pins to the framework's (`pnpm run update` does it), then remove both
+entries — an inert entry is not insurance, `pnpm audit` reports a regression the day it happens. Keep them
+only while your project still pins `@nestjs/platform-express` below 12.3.2 or `@nestjs/graphql` below 14.1.0.
+
+**Status since 12.0.0** (`@nestjs/*` 12, verified 2026-10-24): `multer` is load-bearing again
+(GHSA-q7qp-rjg7-q26m covers the `2.4.0` that `@nestjs/platform-express` 12.2.0 pins) and so is
+`@graphql-tools/utils` (GHSA-c4qx-w738-7hr3 covers the `12.0.1` that `@nestjs/graphql` 14.0.3 pins);
+`js-yaml` is inert, because `@nestjs/swagger` 12.0.4 pins the patched `5.5.0`. Three further
+advisories from the same weeks need **no override**, because every requester's range already reaches
+the fix — but an existing lockfile keeps the old version until it is refreshed:
+`body-parser` 2.4.0 (GHSA-27r3-jxmh-p828, high), `fast-uri` 3.1.9 (four advisories, up to moderate)
+and `zod` 4.6.6+ (GHSA-mrhx-c7xc-m3w5, high):
+`pnpm update --depth Infinity body-parser fast-uri zod`. If your own `pnpm-workspace.yaml` carries an
+entry for one of them, raise its key and target instead — an entry whose target sits below the fix
+pins the vulnerable version in place.
 
 **Status since 11.42.4:** `@graphql-tools/utils` joins `js-yaml` as load-bearing — no `@nestjs/graphql`
 13.x resolves past the exact pin. The 11.42.4 release also covers `proxy-addr` (GHSA-jqcg-44mw-7w3h,
@@ -42,38 +62,47 @@ entries. None of them is optional in practice.
 ## The fix
 
 Add this to your project's `pnpm-workspace.yaml` (pnpm 11+; in pnpm 10 and earlier it lives under
-`pnpm.overrides` in `package.json`):
+`pnpm.overrides` in `package.json`). On nest-server **12.0.x** these two entries are all it takes — a fresh
+resolve of nest-server 12.0.0's own tree with and without every other former entry audits identically. On
+**12.1.x** neither is needed once your `@nestjs/*` pins match the framework's (see "Status since 12.1.0"):
 
 ```yaml
 overrides:
-  # @nestjs/graphql exact-pins ws@8.20.1 (GHSA-96hv-2xvq-fx4p, high, patched >=8.21.0).
-  # An exact pin cannot resolve forward — the override is the only fix.
-  # Keep the target in LOCKSTEP with your direct `ws` dependency (see the note below).
-  # Remove once @nestjs/graphql stops pinning it.
-  'ws@>=8.0.0 <8.21.0': '8.21.3'
-
-  # @nestjs/swagger exact-pins js-yaml (11.4.7: 5.3.0) — GHSA-r3ph-w7gj-g6xm (moderate, patched >=5.4.1)
-  # and, for older swagger releases, GHSA-pm4m-ph32-ghv5 (high, patched >=5.2.2).
-  # Same shape as the ws entry: an exact pin cannot resolve forward. LOAD-BEARING since 11.41.5.
-  # Remove once @nestjs/swagger pins >=5.4.1 itself.
-  'js-yaml@>=5.0.0 <5.4.2': '5.4.2'
-
-  # @nestjs/platform-express <=11.2.5 exact-pins multer@2.2.0 (GHSA-wc9g-mqfw-jrwm and three more, patched >=2.3.0).
-  # Keep the target in LOCKSTEP with the multer version @lenne.tech/nest-server declares (2.4.0 since 11.41.4).
-  # Inert on @nestjs/platform-express 11.2.6+, which pins 2.4.0 itself.
-  'multer@>=2.0.0 <2.4.0': '2.4.0'
-
-  # @nestjs/graphql 13.4.5 exact-pins @graphql-tools/utils@12.0.0 — GHSA-7mx3-vvmw-hjmv (high, patched >=12.0.1).
+  # @nestjs/platform-express exact-pins multer: 2.2.0 up to 11.2.5 (GHSA-wc9g-mqfw-jrwm and three more,
+  # patched >=2.3.0), 2.4.0 in 11.2.6 / 11.2.7 / 12.2.0 — GHSA-q7qp-rjg7-q26m (high, patched >=2.5.0).
+  # LOAD-BEARING again since nest-server 12.0.0: the key must reach the exact 2.4.0 pin.
+  # Keep the target in LOCKSTEP with the multer version @lenne.tech/nest-server declares (2.5.0 since 12.0.0).
+  # Remove once @nestjs/platform-express pins >=2.5.0 itself — 12.3.2 does (nest-server 12.1.0).
+  'multer@>=2.0.0 <2.5.0': '2.5.0'
+
+  # @nestjs/graphql exact-pins @graphql-tools/utils — 13.4.5: 12.0.0 (GHSA-7mx3-vvmw-hjmv, high, patched
+  # >=12.0.1); 14.0.3 (nest-server 12.0.0): 12.0.1 (GHSA-c4qx-w738-7hr3, high, patched >=12.0.2).
+  # The key below reaches both pins.
   # Target the newest 12.x, so the caret requesters (@graphql-tools/schema / merge) are not held back —
   # @graphql-tools/schema 10.1.5 requests ^12.1.0, so a lower target leaves a second copy in the tree.
   # 12.0.2+ requires Node >=22.15 via @whatwg-node/promise-helpers@2 — the floor this framework declares
-  # since 11.42.10. On an older Node, take 12.0.1 instead.
+  # since 11.42.10. There is no older way out: 12.0.1 is covered by GHSA-c4qx-w738-7hr3, so a Node
+  # below 22.15 has no patched utils at all — raise Node.
   # Does NOT reach a utils 11.x pulled in by an older @graphql-tools/schema 10.0.x — refresh that one instead:
   #   pnpm update --depth Infinity @graphql-tools/schema @graphql-tools/merge
-  # Remove once @nestjs/graphql pins >=12.0.1 in the major you use.
+  # Remove once @nestjs/graphql pins >=12.0.2 in the major you use — 14.1.0 does (nest-server 12.1.0).
   '@graphql-tools/utils@>=12.0.0 <12.1.0': '12.1.0'
 ```
 
+### Only on nest-server 11.x: `ws` and `js-yaml`
+
+`@nestjs/graphql` 13 and `@nestjs/swagger` 11 exact-pin vulnerable versions of these two; their 12.x
+successors pin patched ones (`ws` 8.22.0, `js-yaml` 5.5.0). On nest-server 12 remove both entries — an
+inert `ws` entry is not harmless there: pnpm rewrites `graphql-ws`'s `ws` peer range to the override
+target, so a target below 8.22.0 makes `pnpm peers check` report `unmet peer ws`.
+
+```yaml
+  # nest-server 11.x only (@nestjs/graphql 13 exact-pins ws; GHSA-96hv-2xvq-fx4p, patched >=8.21.0)
+  'ws@>=8.0.0 <8.21.0': '8.21.3'
+  # nest-server 11.x only (@nestjs/swagger 11.4.7 exact-pins js-yaml 5.3.0; GHSA-r3ph-w7gj-g6xm, patched >=5.4.1)
+  'js-yaml@>=5.0.0 <5.4.2': '5.4.2'
+```
+
 ### Retired: `@hono/node-server` (removed 2026-08-22, nest-server 11.36.1)
 
 This list used to carry a third entry. `@modelcontextprotocol/sdk` declared `@hono/node-server@^1.19.9`
@@ -90,16 +119,17 @@ tree to `2.0.11` even though nothing needed help any more.
 
 ### The `ws` target must stay in lockstep with the declared `ws` version
 
-`8.21.3` is not an arbitrary "latest patch" — it is the version `@lenne.tech/nest-server` declares as
-an ordinary **dependency**, so it is already in your tree whether or not you list `ws` yourself.
-The override target has to equal it.
+This applies while a project carries a `ws` entry at all, i.e. on nest-server 11.x. `8.22.0` (since 12.0.0;
+`8.21.3` before) is not an arbitrary "latest patch" — it is the version
+`@lenne.tech/nest-server` declares as an ordinary **dependency**, so it is already in your tree whether
+or not you list `ws` yourself. The override target has to equal it.
 
 Under `nodeLinker: hoisted` (what this framework and the starters use), a lower target does not
 merely leave you one patch behind: it puts a **second, older `ws` copy** in the tree next to the
 declared one. The transitive consumers resolve to the override target, the declared dependency stays
 where its `package.json` pins it, and you now carry two `ws` versions — of which only one is visible
 when you read a manifest. The target was raised `8.21.1` → `8.21.3` on 2026-08-10 for exactly this
-reason.
+reason, and to `8.22.0` with nest-server 12.0.0.
 
 **Rule:** whenever the `ws` version declared by `@lenne.tech/nest-server` (or by your own
 `package.json`, if you list it) moves, move this override target with it in the same commit. The