@lenne.tech/nest-server 11.27.5 → 11.27.7

package/.claude/rules/architecture.md

@@ -60,6 +60,72 @@ Key areas: JWT, MongoDB, GraphQL, email, security, static assets
 - `CheckResponseInterceptor` - Filters restricted fields
 - `CheckSecurityInterceptor` - Processes `securityCheck()` methods
 
+## DI Token Placement (SWC-Safe)
+
+**Rule: DI tokens belong in an import-free leaf file (`*.constants.ts` / `*.enums.ts`) — never in `*.module.ts` or `*.service.ts`.**
+
+A token declared in a module that the service imports (or vice versa) makes the two files import each other. That cycle compiles fine under tsc, but `@Inject(TOKEN)` is a constructor-parameter decorator evaluated at **class-definition time** — so on the cycle it reads a `const` that is still in its temporal dead zone. Under SWC → CommonJS (`nest start -b swc`) the app dies at startup:
+
+```
+ReferenceError: Cannot access 'BETTER_AUTH_INSTANCE' before initialization
+```
+
+**This is invisible to `tsc`, to `pnpm test` (vitest runs SWC through Vite's cycle-tolerant module runner) and to `oxlint` (which has no `import/no-cycle` rule).** It is caught only by `pnpm run check:swc-tdz`.
+
+### The general rule: a cycle is fatal only when dereferenced at evaluation time
+
+The cycle alone is survivable. What kills it is **reading a TDZ-subject binding (`const` / `class` / `let`) while the module is still initializing**:
+
+| Deref location | Evaluated | Danger |
+|----------------|-----------|--------|
+| Decorator argument (`@UnifiedField({ type: X })`, `@Inject(TOKEN)`) | class-definition time | ☠️ **fatal on a cycle** |
+| `design:type` / `design:paramtypes` metadata (from `emitDecoratorMetadata`) | class-definition time | ☠️ **fatal on a cycle** — and userland cannot make it lazy |
+| Static / class field initializer | class-definition time | ☠️ **fatal on a cycle** |
+| Top-level `const alias = X` | module-evaluation time | ☠️ **fatal on a cycle** |
+| Inside a function or method body | call time | ✅ safe (both modules are done by then) |
+| `export function` declaration | hoisted | ✅ TDZ-immune — prefer over `const` arrows on cycle-adjacent files |
+| `import type` | erased | ✅ not a runtime edge at all |
+
+**A lazy thunk is often NOT enough.** `type: () => X` defers the decorator argument, but `emitDecoratorMetadata` still emits an eager `design:type` for the property, and SWC's `typeof` guard does not protect the member expression it compiles to. To be safe you must remove the **import edge** — merge the modules, or extract the shared binding into a leaf.
+
+### `check:swc-tdz` loads every module as its own entry point
+
+Whether such a cycle throws depends on **which module the graph is entered through**. A barrel-only check is not enough: `filter.input` ↔ `combined-filter.input` crashed on a direct `require()` of `combined-filter.input` while the barrel loaded green, because the barrel happened to pull `filter.input` in first. So the guard requires each compiled file separately (`scripts/check-swc-tdz.mjs`).
+
+### Status per module
+
+Repo-wide cycles went from **10 → 5**, and **every DI token in `src/core/` now lives in an import-free leaf**. The five that remain are, per an SWC-emit audit, **not runtime cycles at all** — type-only imports that madge reports but both compilers erase (their emits are empty).
+
+Both invariants are enforced by `tests/unit/import-cycle-invariants.spec.ts`, which fails if a token reappears in a `*.module.ts` / `*.service.ts` or if a leaf grows an import. That matters, because the guard below catches the *crash*, not the *disarming* of a safety property — those are different things, and only the second one is silent.
+
+| Module | Token / type leaf |
+|--------|-------------------|
+| `better-auth` | `core-better-auth.constants.ts` (tokens) + `core-better-auth.registry.ts` (static service refs, `import type` only, deliberately **not** barrel-exported) |
+| `ai` | `core-ai.constants.ts` (all 22 `AI_*` tokens) + `interfaces/ai-interaction-record.interface.ts` |
+| `tus` | `tus.constants.ts` (`TUS_CONFIG`) |
+| `tenant` | `core-tenant.enums.ts` |
+| `auth` | `interfaces/auth-provider.interface.ts` |
+| `common/helpers` | `id.helper.ts` (ID cluster, out of `db.helper`) + `clone.helper.ts` (`clone`/`deepFreeze`, out of `input.helper`) |
+| `common/inputs` | `FilterInput` + `CombinedFilterInput` merged into `filter.input.ts` — declaration order is load-bearing |
+| `common/decorators` | `restricted.decorator` is on **zero** cycles; its exports are hoisted `function` declarations (TDZ-immune) as defense in depth |
+
+Every old location re-exports what it lost, so no import path broke — the public API is byte-identical (472 exports, verified by diffing both versions).
+
+### What each of these actually was
+
+Worth knowing, because the pattern repeats:
+
+- **`CombinedFilterInput` was already crashing.** `require('.../combined-filter.input.js')` threw. It stayed hidden because the barrel happens to pull `filter.input` in first — a deep import or a reordering of `src/index.ts` would have surfaced it. A lazy thunk does **not** fix that shape: `emitDecoratorMetadata` still emits an eager `design:type`.
+- **`restricted.decorator` sat on two cycles at once**, in the file that drives field-level access control. Removing the `db.helper` edge felt like the fix and left the `config.service` one fully intact. **Removing one edge is not removing the cycle** — re-run madge and confirm the file appears in *zero* cycles.
+- **The AI interaction record was held apart by one keyword.** `import type` erases the edge; an IDE "organize imports" widening it to a value import would have armed a `design:paramtypes` deref, silently.
+- **`TUS_CONFIG` and the 22 `AI_*` tokens** never crashed — their graphs happened to be acyclic. Each was one back-import away, with nothing watching.
+
+### The lesson that cost the most time
+
+Removing one edge is not the same as removing the cycle. `restricted.decorator` was on **two** cycles through different paths; extracting the ID helpers out of `db.helper` felt like the fix and left the second one (via `config.service`) fully intact — with `madge` happily reporting the file as still cyclic. Always re-run `npx madge --circular --extensions ts src/` after an extraction and check the file appears in **zero** cycles, rather than assuming the edge you removed was the only one.
+
+Full background, failure analysis and the mistakes table: `.claude/rules/better-auth.md` §6.
+
 ## Model Inheritance
 
 - `CorePersistenceModel` - Base for database entities

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

@@ -199,6 +199,8 @@ The BetterAuth module provides two RolesGuard implementations:
 **Solution:** `BetterAuthRolesGuard` with NO constructor dependencies:
 
 ```typescript
+import { getBetterAuthTokenService } from './core-better-auth.registry';
+
 @Injectable()
 export class BetterAuthRolesGuard implements CanActivate {
   // NO constructor dependencies - avoids mixin DI conflict
@@ -207,14 +209,19 @@ export class BetterAuthRolesGuard implements CanActivate {
     // Use Reflect.getMetadata directly (not NestJS Reflector)
     const roles = Reflect.getMetadata('roles', context.getHandler());
 
-    // Access services via static module reference
-    const tokenService = CoreBetterAuthModule.getTokenServiceInstance();
+    // Read the token service from the registry LEAF — never from CoreBetterAuthModule.
+    // Importing the module here re-creates the guard <-> module import cycle (see §6).
+    const tokenService = getBetterAuthTokenService();
 
     // ... role checking logic identical to RolesGuard
   }
 }
 ```
 
+> The guard must NOT do `CoreBetterAuthModule.getTokenServiceInstance()`. That static accessor is
+> still public API and still works — but calling it *from the guard* means importing the module,
+> which is exactly the cycle §6 exists to prevent. Everywhere else, the static accessor is fine.
+
 ### Guard Selection Logic
 
 In `CoreBetterAuthModule.createDeferredModule()`:
@@ -250,6 +257,84 @@ Both guards implement identical security logic:
 2. **New system roles** → Add to BOTH guards
 3. **Token verification changes** → Update `BetterAuthTokenService` (shared by both)
 4. **Testing** → Test both Legacy Mode and IAM-Only Mode
+5. **Reaching services from `BetterAuthRolesGuard`** → go through `core-better-auth.registry.ts`,
+   **never** through `CoreBetterAuthModule` (see §6 — importing the module from the guard
+   re-creates an import cycle)
+
+## 6. DI Token Placement (SWC-Safe)
+
+### The rule
+
+**DI tokens and static service references belong in an import-free leaf file — never in
+`*.module.ts` or `*.service.ts`.**
+
+| File | Contents | Imports |
+|------|----------|---------|
+| `core-better-auth.constants.ts` | `BETTER_AUTH_INSTANCE`, `BETTER_AUTH_CONFIG`, `BETTER_AUTH_COOKIE_DOMAIN` | **none** |
+| `core-better-auth.registry.ts` | `BetterAuthTokenService` reference for `BetterAuthRolesGuard` | **`import type` only** (erased by tsc and SWC) |
+
+### The problem
+
+The tokens used to live in the module (`BETTER_AUTH_INSTANCE`) and the service (`BETTER_AUTH_CONFIG`,
+`BETTER_AUTH_COOKIE_DOMAIN`), so module and service imported each other.
+
+**Error (only under `nest start -b swc` / `nest build -b swc`):**
+
+```
+ReferenceError: Cannot access 'BETTER_AUTH_INSTANCE' before initialization
+```
+
+The lethal ingredient is **not the cycle by itself** — it is a cycle **plus a read of the cyclic
+binding at module-evaluation time**. `@Inject(BETTER_AUTH_INSTANCE)` is a constructor-parameter
+decorator, and decorator arguments are evaluated when the class is *defined*, i.e. while the module
+is still initializing. On a cycle, the importing side then reads a `const` that is still in its
+temporal dead zone.
+
+This is why the same cycle is harmless when both sides only dereference each other **inside method
+bodies** (deferred to call time) — and why such a cycle is nonetheless a loaded gun: hoisting a
+lazy lookup into a static field, or adding a typed constructor parameter (which emits
+`design:paramtypes` at top level), weaponizes it instantly.
+
+### The solution
+
+```typescript
+// core-better-auth.constants.ts — imports NOTHING
+export const BETTER_AUTH_INSTANCE = 'BETTER_AUTH_INSTANCE';
+
+// core-better-auth.module.ts AND core-better-auth.service.ts
+import { BETTER_AUTH_INSTANCE } from './core-better-auth.constants';
+```
+
+A file with zero imports can never be mid-evaluation when someone imports it — in any module
+system, under any compiler.
+
+### Why you cannot rely on the test suite here
+
+This bug class is **invisible** to everything except one specific step:
+
+| Tool | Sees it? | Why |
+|------|:--------:|-----|
+| `tsc` / `pnpm run build` | ❌ | Compiles the cycle without complaint |
+| `pnpm test` (vitest) | ❌ | vitest runs SWC through **Vite's module runner**, whose getter-based live bindings tolerate cycles |
+| `oxlint` | ❌ | oxlint does **not** implement `import/no-cycle` |
+| `pnpm run check:swc-tdz` | ✅ | SWC → CommonJS → `require()`: the exact path consumers hit |
+| `tests/unit/better-auth-di-tokens.spec.ts` | ✅ | Asserts the leaf invariant structurally |
+
+The bug shipped to `develop` with a fully green CI. Treat a green `pnpm test` as **no evidence** on
+this question.
+
+### Common mistakes
+
+| Mistake | Symptom | Fix |
+|---------|---------|-----|
+| Importing a token from `./core-better-auth.module` or `./core-better-auth.service` inside the better-auth module | Green tsc + green tests; `ReferenceError` for consumers on SWC | Import from `./core-better-auth.constants` |
+| Adding any runtime `import` to `core-better-auth.constants.ts` | `better-auth-di-tokens.spec.ts` fails | Keep it a leaf; move whatever you needed elsewhere |
+| Importing `CoreBetterAuthModule` into `better-auth-roles.guard.ts` | Re-creates the guard ↔ module cycle | Use `getBetterAuthTokenService()` from `./core-better-auth.registry` |
+| Hoisting `getBetterAuthTokenService()` into a static field / class property initializer | Evaluation-time deref → TDZ crash returns | Keep the lookup inside the method body |
+
+> The backward-compat re-exports in `core-better-auth.module.ts` / `core-better-auth.service.ts` are
+> marked `@deprecated` and exist **only** for external deep importers. Never use them from inside
+> the module — that is precisely the path that re-creates the cycle.
 
 ## Summary
 
@@ -260,3 +345,4 @@ Both guards implement identical security logic:
 | Testing | Full coverage, all tests pass, security tests included |
 | Customization | Use correct registration pattern, re-declare Resolver decorators |
 | Guards | Maintain both RolesGuard and BetterAuthRolesGuard in sync |
+| DI Tokens | Import-free leaf file only — never in `*.module.ts` / `*.service.ts` (§6) |

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

@@ -216,8 +216,8 @@ This pattern is currently applied to:
 | 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) |
 | Debug Process Input | `debugProcessInput` | Explicit Boolean | `false` (default). When `true`, logs a debug message when `prepareInput()` changes the input type during `process()`. Has performance cost due to `JSON.stringify` on every `process()` call — enable only for debugging |
 | JSONTransport Production Guard | `email.smtp` with `jsonTransport` | Runtime Guard | Throws `Error` when `email.smtp` has a truthy `jsonTransport` property in `production` or `staging` environments (read from config `env` field). JSONTransport silently discards all outgoing mail — the guard prevents accidental misconfiguration that causes password-reset, 2FA, and verification emails to vanish. Use `{ jsonTransport: true }` only in CI/e2e/local environments |
-| Cookies | `cookies` | Boolean Shorthand (default true) | `true` (enabled), `exposeTokenInBody: false`. When enabled: loads `cookie-parser`, sets CORS `credentials: true`, sets signed httpOnly session cookies. When `exposeTokenInBody: true`: token stays in response body alongside cookies (for hybrid JWT+Cookie auth). JWT via `Authorization: Bearer` always works independently |
-| CORS | `cors` | Boolean Shorthand | `enabled: true`, `allowAll: false`, `deriveAppUrl: true`. Origins come from `appUrl`/`baseUrl`, resolved by the shared `resolveServerUrls()` helper (`cookies.helper.ts`) that ALL three CORS layers use (GraphQL, REST, BetterAuth `trustedOrigins`) — they can no longer drift. `appUrl` resolution: explicit → localhost default (`http://localhost:3001`, only for `env: local`/`ci`/`e2e` with a localhost `baseUrl`) → derived from `baseUrl` by stripping a leading `api.` label (`https://api.example.com` → `https://example.com`). **Security:** the derived origin receives credentialed CORS; set `deriveAppUrl: false` when the apex domain is not trusted, then list the frontend origin via `appUrl`/`allowedOrigins`. The derivation never yields a bare TLD (`https://api.dev` unchanged) and never emits the opaque `null` origin (non-http(s) `baseUrl` passes through verbatim). `allowAll: true` mirrors request origin. `enabled: false` disables CORS on all layers including BetterAuth. Explicit `betterAuth.trustedOrigins` always takes precedence |
+| Cookies | `cookies` | Boolean Shorthand (default true) | `true` (enabled), `exposeTokenInBody: false`. When enabled: loads `cookie-parser`, sets CORS `credentials: true`, sets signed httpOnly session cookies. When `exposeTokenInBody: true`: token stays in response body alongside cookies (for hybrid JWT+Cookie auth). JWT via `Authorization: Bearer` always works independently. **BetterAuth cookie name (since v11.27.6):** `createBetterAuthInstance()` pins `advanced.useSecureCookies: false` so BetterAuth's native handlers read the same UNPREFIXED `<cookiePrefix>.session_token` the helper writes (fixes a `401` split-brain on 2FA/passkey/`/token`); the `Secure` attribute is still applied on an `https://` baseURL via `advanced.defaultCookieAttributes`. Opt back into the `__Secure-` prefix with `betterAuth.options.advanced.useSecureCookies: true` only when BetterAuth manages cookies entirely |
+| CORS | `cors` | Boolean Shorthand | `enabled: true`, `allowAll: false`, `deriveAppUrl: true`. Origins come from `appUrl`/`baseUrl`, resolved by the shared `resolveServerUrls()` helper (`cookies.helper.ts`) that ALL three CORS layers use (GraphQL, REST, BetterAuth `trustedOrigins`) — they can no longer drift. `appUrl` resolution: explicit → derived from a **host-split** localhost `baseUrl` (its `api.` label strips to a sibling host: `https://api.crm.localhost` → `https://crm.localhost`, as served by `lt dev up`; the port is preserved) → localhost default (`http://localhost:3001`, only for `env: local`/`ci`/`e2e` with a **port-split** localhost `baseUrl` — one host, API `:3000`, app `:3001`; `https://api.localhost` strips to the bare `localhost` the API already answers on and is therefore a port split, not a host split) → derived from `baseUrl` by stripping a leading `api.` label (`https://api.example.com` → `https://example.com`). **Security:** the derived origin receives credentialed CORS; set `deriveAppUrl: false` when the apex domain is not trusted, then list the frontend origin via `appUrl`/`allowedOrigins` (a host-split localhost `baseUrl` then falls back to the localhost default). The derivation never yields a bare TLD (`https://api.dev` unchanged) and never emits the opaque `null` origin (non-http(s) `baseUrl` passes through verbatim). `allowAll: true` mirrors the request origin for REST/GraphQL, but BetterAuth's `trustedOrigins` still resolve to `[appUrl]` (+ passkey origins) — an origin check has no "allow everything" mode, so a separately hosted frontend must appear in `appUrl`/`allowedOrigins` (or set `betterAuth.trustedOrigins` explicitly). `enabled: false` disables CORS on all layers including BetterAuth (`trustedOrigins: []`, which still trusts BetterAuth's own `baseURL`). Explicit `betterAuth.trustedOrigins` always takes precedence |
 | AI Assistant | `ai` | Presence Implies Enabled | Core: `maxIterations: 5`, `defaultMode: 'auto'` (or `'plan'`), `rateLimit` (presence implies enabled: `max: 20`, `windowSeconds: 60`), `systemPrompt`, `documentation` (injected into the system prompt), `encryptionSecret`. **DB-backed LLM connections** (`aiConnections`, admin CRUD) with AES-256-GCM-encrypted API keys (`AiCryptoService`, secret from `ai.encryptionSecret` / `NSC__AI__ENCRYPTION_SECRET` / `SECRETS_ENCRYPTION_KEY`; `apiKeyEncrypted` is a global `secretFields` entry, never returned — only `hasApiKey`); optional `defaultConnection` one-time seed. **Provider abstraction** (`ILlmProvider`, default `OpenAiCompatibleProvider` for any OpenAI-compatible endpoint via `fetch`; per-connection `supportsNativeTools`/`supportsJsonResponse` capabilities, emulated tool calling when native tools are unavailable). **Tool registry** (`AiToolRegistry`, tools self-register, role-filtered; tools may be `mutating`/`destructive` and define `authorize()` for pre-flight data-level checks). **Plan mode** (`input.mode: 'plan'`): full plan → pre-flight authorize ALL steps → all-or-nothing execution with a translated (de/en) error when any step is not permitted. **Confirmation policy**: `confirmation.mutating: { default, enforced }` + client `input.requireConfirmation` (ignored when enforced); `destructive` always confirms. **Client metadata** (`input.metadata`: URL/nav/console logs, untrusted+capped). **Multi-turn conversations** (`aiConversations`, owner-scoped). **SSE streaming** (`POST /ai/stream`). **Audit** (`audit: false` → persist to `aiInteractions`, admin-readable). **Token budgets** (`budget: { period: 'day'|'month'|'none', user: { maxTokens?, maxPrompts? }, tenant: { maxTokens?, maxPrompts? } }`, requires audit): per-user AND per-tenant limits with config defaults; admins override per user/tenant at runtime (`aiBudgetLimits`, `CoreAiBudgetService`). Resolution: override → default → unlimited (missing/0 = unlimited). Enforced before the run (HTTP 429 + translated). Each response carries a compact `budget` summary (promptTokens, usedTokens, remainingTokens, resetAt); full breakdown via `aiUsage` query / `GET /ai/usage`. **Self-optimizing prompts**: the system prompt is assembled from keyed fragments (`CoreAiPromptBuilderService` ships built-in defaults; works with zero rows). Admin-editable overrides per slot (`aiSlots`, admin CRUD, `/ai/slots`) scoped by `key`/`locale`/`capability`/`tenantId`, with tenant override/reset semantics and placeholder tokens resolved at run time via the placeholder registry. **Governed learning loop** (`promptLearning: { enabled: true, autoApply: false }`): tool errors record `suggested` hints (`aiPromptHints`, admin CRUD, `/ai/prompt-hints`) that only reach the prompt once admin-approved (or auto-approved when `autoApply`); hints only ADD guidance, never relax permissions. **Context window** (`contextWindow`, default 8192; auto-detected per connection via `ILlmProvider.detectContextWindow()` — Ollama `/api/show` probe / known-model table / Claude alias — and persisted): per-user/session history is trimmed (oldest non-system turns dropped, last truncated) and tool-results capped to `maxToolResultChars` (default 12000) so a session never overflows the model. **MCP server** (`mcp: false` → `/ai/mcp` Streamable HTTP, Bearer auth, lazy `@modelcontextprotocol/sdk`; `mcp: { oauth: true, oauthSecret }` adds OAuth 2.1 — HMAC tokens + PKCE S256 + dynamic registration via `mountAiMcpOAuth(app)` in main.ts). Overrides via `CoreModule.forRoot(env, { ai: { budgetService, connectionResolver, connectionService, controller, conversationService, interactionService, mcpClientService, modeService, placeholderRegistry, preferenceService, promptBuilder, promptHintService, promptService, resolver, service, slotService, toolGrantService, toolPolicyService } })` |
 
 ## Module Override Pattern (via `ICoreModuleOverrides`)

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

@@ -97,9 +97,23 @@ peerDependencies may use ranges when necessary for compatibility with consuming
 
 The `pnpm-lock.yaml` file must always be committed. It provides additional reproducibility even if someone accidentally introduces a version range.
 
+## Package Manager: pnpm 11
+
+This repo is pinned to **pnpm 11** via the `packageManager` field (corepack/`pnpm/action-setup` follow it, so CI and Docker use it automatically — no version is hardcoded anywhere else).
+
+pnpm 11 **no longer reads the `pnpm` field in `package.json`**, and `.npmrc` is auth/registry only. All pnpm-specific settings live in **`pnpm-workspace.yaml`**:
+
+- `overrides:` — the security overrides (see below)
+- `allowBuilds:` — a **map** of `pkg: true|false` classifying every package that has an install script (canonical v11 form; replaces `onlyBuiltDependencies`). Native builds we need are `true` (`bcrypt`, `@swc/core`, …); telemetry like `@scarf/scarf` is `false`. **Every build-script package must be classified**, or `pnpm install` exits non-zero with `ERR_PNPM_IGNORED_BUILDS` and appends a broken stub.
+- `nodeLinker`, `autoInstallPeers`, `strictPeerDependencies`, `peerDependencyRules` — moved here from `.npmrc` (camelCase).
+
+`pnpm audit`: pnpm 10.x is broken (npm retired the legacy audit endpoint → HTTP 410); pnpm 11 uses the working bulk-advisory endpoint. `scripts/check.mjs` degrades the retired-endpoint failure to a non-blocking warning as a safety net, so `check` stays green + honest even if a future endpoint change lands.
+
 ## Overrides
 
-Package overrides are configured in the `pnpm.overrides` section of `package.json` and are typically used to force transitive dependencies to a security-patched version.
+Package overrides live in the `overrides:` section of **`pnpm-workspace.yaml`** (they moved out of `package.json`'s `pnpm.overrides` in the pnpm 11 upgrade). They force transitive dependencies to a security-patched version.
+
+**Keep the set minimal.** On the pnpm 11 upgrade the list was pruned from 36 to the 9 still load-bearing — an override is only necessary if removing it lets the package resolve back INTO its vulnerable range (verify with a with/without lockfile diff; `pnpm audit` is the arbiter). Each surviving entry carries its CVE rationale as a comment. Remove an entry once its parent dependency ships a fixed version.
 
 ### Rule: Override Targets MUST Be Fixed Versions
 
@@ -115,19 +129,14 @@ The **target** of an override (the value on the right-hand side) MUST be a fixed
 
 The **key** (left-hand side) of an override entry selects which installed versions the override applies to. Both forms are valid:
 
-```json
-{
-  "pnpm": {
-    "overrides": {
-      // Form 1: Replace ALL versions of a package with a fixed one
-      "lodash": "4.17.23",
-
-      // Form 2: Replace only vulnerable versions with a fixed patched one
-      "minimatch@<3.1.4": "3.1.4",
-      "path-to-regexp@>=8.0.0 <8.4.0": "8.4.2"
-    }
-  }
-}
+```yaml
+# pnpm-workspace.yaml
+overrides:
+  # Form 1: Replace ALL versions of a package with a fixed one
+  'lodash': '4.17.23'
+  # Form 2: Replace only vulnerable versions with a fixed patched one
+  'minimatch@<3.1.4': '3.1.4'
+  'path-to-regexp@>=8.0.0 <8.4.0': '8.4.2'
 ```
 
 Form 2 is preferred for security-driven overrides because it leaves non-vulnerable versions untouched, which reduces the blast radius of the override.

package/.claude/rules/testing.md

@@ -2,20 +2,34 @@
 
 ## Test Framework
 
-- **Vitest** - Primary test framework (migrated from Jest)
-- Configuration: `vitest.config.ts`
-- Test files: `tests/` directory with `.e2e-spec.ts` suffix
+**Vitest**, split across two runners. Which one claims a file is decided purely by its filename:
+
+| Runner | Config | Test files | Needs MongoDB |
+|--------|--------|-----------|:-------------:|
+| Unit | `vitest.config.ts` | `src/**/*.spec.ts`, `tests/unit/**/*.spec.ts` | No |
+| E2E | `vitest-e2e.config.ts` | `tests/**/*.e2e-spec.ts`, `tests/stories/**/*.story.test.ts` | Yes |
+
+A file matching neither pattern would run nowhere. `tests/unit/test-file-routing.spec.ts` asserts
+that every `*.spec.ts` / `*.test.ts` in the repo is claimed by **exactly one** runner, so a
+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.
 
 ## Running Tests
 
 ```bash
-# Run all E2E tests (default)
+# Unit + E2E (default) — the E2E half needs MongoDB
 pnpm test
 
-# Run with coverage
+# Unit tests only (fast, no MongoDB)
+pnpm run vitest:unit
+
+# E2E tests only
+pnpm run test:e2e
+
+# Both suites with coverage → coverage/unit + coverage/e2e
 pnpm run test:cov
 
-# Run in CI mode
+# Run in CI mode (unit + E2E with NODE_ENV=ci)
 pnpm run test:ci
 
 # Debug open handles
@@ -27,11 +41,15 @@ pnpm run test:cleanup
 
 ## Test Environment
 
-- Environment: `NODE_ENV=e2e` (via `pnpm test` → `vitest-e2e.config.ts`)
-- Database: **one unique database per run** (`nest-server-e2e-run-<ts>-p<pid>`), created by `tests/global-setup.ts` so concurrent runs cannot interfere with each other
+- Environment: `NODE_ENV=e2e` for the E2E runner (`pnpm run vitest`). The unit runner sets no
+  `NODE_ENV`; vitest defaults it to `test`, and `getEnvironmentConfig()` falls back to `config.local`.
+- Both runners load `tests/setup.ts` via `setupFiles` (Nest Logger restricted to `error`/`fatal`,
+  `@UnifiedField` deprecation warnings filtered).
+- Database (E2E only): **one unique database per run** (`nest-server-e2e-run-<ts>-p<pid>`), created by `tests/global-setup.ts` so concurrent runs cannot interfere with each other
 - DB lifecycle (`tests/db-lifecycle.reporter.ts`): run passes → DB dropped immediately + stale run DBs from crashed/failed runs collected; run fails → DB kept for debugging, removed by the next successful run. An externally set `MONGODB_URI` (CI) opts out of the scheme.
 - Test helper: `src/test/test.helper.ts`
-- Coverage: Collected from `src/**/*.{ts,js}`
+- Coverage: Collected from `src/**/*.{ts,js}`. The two runners are separate vitest processes, so
+  they write separate reports (`coverage/unit`, `coverage/e2e`) rather than overwriting each other.
 
 ## Test Best Practices
 

package/CLAUDE.md

@@ -106,15 +106,23 @@ pnpm start              # Start in local mode
 pnpm run start:dev      # Development mode with watch
 
 # Testing (ALWAYS run before completing changes)
-pnpm test               # Run E2E tests (Vitest)
-pnpm run test:cov       # With coverage
+pnpm test               # Unit + E2E tests (Vitest); E2E half needs MongoDB
+pnpm run vitest:unit    # Unit tests only (fast, no MongoDB)
+pnpm run test:e2e       # E2E tests only
+pnpm run test:cov       # Both suites with coverage (coverage/unit + coverage/e2e)
 npx vitest run --config vitest-e2e.config.ts --reporter=hanging-process   # Debug open handles
 pnpm run test:cleanup   # Remove leftover test artifacts (.txt, .bin)
 
 # Linting & Formatting
-pnpm run lint           # ESLint check
+pnpm run lint           # oxlint check
 pnpm run lint:fix       # Auto-fix
-pnpm run format         # Prettier format
+pnpm run format         # oxfmt format
+
+# Import-cycle / SWC safety (part of `check`)
+pnpm run check:swc-tdz  # SWC→CJS build, loads EVERY module as its own entry point.
+                        # The only step that catches a temporal-dead-zone crash from an
+                        # import cycle — tsc, vitest and oxlint are all blind to it.
+                        # See .claude/rules/architecture.md → "DI Token Placement (SWC-Safe)"
 
 # Package Development
 pnpm run build:dev      # Build for local development (use with pnpm link)

package/FRAMEWORK-API.md

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

package/bin/migrate.js

@@ -5,36 +5,95 @@
  *
  * This is a shim that makes the nest-server migration CLI available as "migrate"
  * for drop-in compatibility with projects using the @nodepit/migrate package.
+ *
+ * The same file has to work from three locations, because `lt fullstack
+ * convert-mode` copies it verbatim into vendored projects:
+ *
+ *   npm mode     node_modules/@lenne.tech/nest-server/bin/  → ../dist/core/**.js
+ *   vendor repo  <project>/bin/                             → ../dist/src/core/**.js
+ *                                                             (or ../src/core/**.ts via ts-node)
+ *   vendor image <project>/dist/bin/                        → ../src/core/**.js
+ *
+ * Compiled candidates are probed first, so a production image never reaches the
+ * ts-node branch — ts-node is a devDependency and gets pruned there.
+ *
+ * NOTE on the vendored-image layout: it assumes the build preserves the `src/`
+ * prefix (`dist/src/core/...`, matching `lt fullstack convert-mode`). A project
+ * that instead flattens `rootDir: 'src'` to `dist/core/...` is still resolved in
+ * *repo* mode (candidate 1) but not from the `dist/bin/` image variant.
+ *
+ * The resolver is exported (and pure, with an injectable `existsSync`) so the
+ * three-layout probe + not-found branch can be unit-tested without spawning a
+ * migration run; the CLI only executes when this file is invoked directly.
  */
 
 const fs = require('fs');
-// Check if running from built dist or src
 const path = require('path');
 
-const distPath = path.join(__dirname, '../dist/core/modules/migrate/cli/migrate-cli.js');
-const srcPath = path.join(__dirname, '../src/core/modules/migrate/cli/migrate-cli.ts');
-
-let cliPath;
-
-if (fs.existsSync(distPath)) {
-  // Production: use built version
-  cliPath = distPath;
-} else if (fs.existsSync(srcPath)) {
-  // Development: register ts-node and use source
-  try {
-    require('ts-node/register');
-    cliPath = srcPath;
-  } catch (e) {
-    console.error('Error: ts-node is required in development mode');
-    console.error('Install it with: npm install --save-dev ts-node');
-    process.exit(1);
+const CLI_SUBPATH = 'core/modules/migrate/cli/migrate-cli';
+
+/**
+ * Resolve the migrate CLI entry across the npm + vendored layouts.
+ *
+ * Compiled `.js` candidates (most specific first) are probed before the TypeScript
+ * source, so a production image with `ts-node` pruned never picks the source path.
+ *
+ * @param {string} dirname - Directory of the shim (`__dirname` at runtime).
+ * @param {(p: string) => boolean} [existsSync] - Injected for tests; defaults to `fs.existsSync`.
+ * @returns {{ cliPath: string | null, needsTsNode: boolean, candidates: string[] }}
+ *   `cliPath` is the resolved entry (null when nothing matched); `needsTsNode` is true only for the
+ *   TypeScript-source fallback; `candidates` is every path probed, for the not-found diagnostic.
+ */
+function resolveCliPath(dirname, existsSync = fs.existsSync) {
+  const compiledCandidates = [
+    // npm package layout: bin/ → dist/core/...
+    path.join(dirname, '..', 'dist', `${CLI_SUBPATH}.js`),
+    // vendored build output: dist/bin/ → dist/src/core/...
+    path.join(dirname, '..', 'src', `${CLI_SUBPATH}.js`),
+    // vendored repo root: bin/ → dist/src/core/...
+    path.join(dirname, '..', 'dist', 'src', `${CLI_SUBPATH}.js`),
+  ];
+  // TypeScript source, used for local development via ts-node.
+  const sourcePath = path.join(dirname, '..', 'src', `${CLI_SUBPATH}.ts`);
+  const candidates = [...compiledCandidates, sourcePath];
+
+  const compiled = compiledCandidates.find((candidate) => existsSync(candidate));
+  if (compiled) {
+    return { candidates, cliPath: compiled, needsTsNode: false };
+  }
+  if (existsSync(sourcePath)) {
+    return { candidates, cliPath: sourcePath, needsTsNode: true };
   }
-} else {
-  console.error('Error: Migration CLI not found');
-  console.error('Make sure @lenne.tech/nest-server is properly built');
-  process.exit(1);
+  return { candidates, cliPath: null, needsTsNode: false };
 }
 
-// Load and run the CLI
-const { main } = require(cliPath);
-main();
+module.exports = { CLI_SUBPATH, resolveCliPath };
+
+// Only run the CLI when invoked directly (`node bin/migrate.js` / the `migrate` bin).
+// Importing this module for tests must not spawn a migration run.
+if (require.main === module) {
+  const { candidates, cliPath, needsTsNode } = resolveCliPath(__dirname);
+
+  if (!cliPath) {
+    console.error('Error: Migration CLI not found. Looked for:');
+    for (const candidate of candidates) {
+      console.error(`  - ${candidate}`);
+    }
+    process.exit(1);
+  }
+
+  if (needsTsNode) {
+    // Development: register ts-node so the TypeScript source can be required.
+    try {
+      require('ts-node/register');
+    } catch {
+      console.error('Error: ts-node is required to run migrations from TypeScript sources');
+      console.error('Install it with: pnpm add -D ts-node');
+      process.exit(1);
+    }
+  }
+
+  // Load and run the CLI
+  const { main } = require(cliPath);
+  main();
+}

package/dist/core/common/decorators/restricted.decorator.d.ts

@@ -6,9 +6,9 @@ export type RestrictedType = (RequireAtLeastOne<{
     processType?: ProcessType;
     roles?: string | string[];
 }, 'memberOf' | 'roles'> | string | string[])[];
-export declare const Restricted: (...rolesOrMember: RestrictedType) => ClassDecorator & PropertyDecorator;
-export declare const getRestricted: (object: unknown, propertyKey?: string) => RestrictedType;
-export declare const checkRestricted: (data: any, user: {
+export declare function Restricted(...rolesOrMember: RestrictedType): ClassDecorator & PropertyDecorator;
+export declare function getRestricted(object: unknown, propertyKey?: string): RestrictedType;
+export declare function checkRestricted(data: any, user: {
     emailVerified?: any;
     hasRole: (roles: string[]) => boolean;
     id: any;
@@ -28,4 +28,4 @@ export declare const checkRestricted: (data: any, user: {
     processType?: ProcessType;
     removeUndefinedFromResultArray?: boolean;
     throwError?: boolean;
-}, processedObjects?: WeakSet<object>) => any;
+}, processedObjects?: WeakSet<object>): any;