@warlock.js/core 5.25.0 → 5.26.0

package/llms-full.txt

@@ -1197,6 +1197,8 @@ Same shape — TS validates the union; runtime picks the `default` key.
 - `socket.adapter` — adapter factory for cross-server broadcast.
 - `cache.silenceSingleServerWarning`, `storage.silenceSingleServerWarning`, `socket.silenceSingleServerWarning` — silence the production warnings for in-memory cache, local storage, and adapter-less sockets.
 
+`http.modelValidationErrorStatus` sets the status for a Cascade model-write validation failure (a model failing its own schema on save). It defaults to `500` with an opaque body, because request input is already validated with a `422` before the model is touched. Set a `4xx` (e.g. `422`) to treat it as a client error instead; the response then carries `{ errors }`.
+
 ## Per-env knobs
 
 For one-off switches gated on environment, the canonical pattern is `Application.isProduction` (also `isDevelopment`, `isTest`):
@@ -1380,6 +1382,10 @@ Two pieces:
 
 If validation fails, the framework returns a 400 with an `errors` payload and your handler never runs.
 
+### Validating route params
+
+`handler.validation = { params: v.object({ id: v.int().min(1) }) }` validates path segments (e.g. `/posts/:id`). Number and boolean validators convert the string segments; the app's schema object is never changed. Parsed values replace `request.params` (`request.input("id")` is a number) and merge into `request.validated()`, with params winning over body fields. Failures answer like a `schema` failure.
+
 ### Typing a guarded handler
 
 Routes behind `authMiddleware` need `request.locals.user` typed. Project conventions add a `GuardedRequest<TSchema>` (overriding `locals` to `RequestLocals & { user: User }`) and a paired `GuardedRequestHandler<TSchema>` alias in `app/auth/requests/guarded.request`:
@@ -1934,6 +1940,10 @@ export class Product extends Model {
 
 This is convention, not a framework requirement. Controllers/services that import the resource explicitly work the same way.
 
+### `id` and Mongo `_id`
+
+The output `id` falls back to `_id` when the record has no `id`; an explicit `id` always wins. If a collection uses native ObjectIds, set `public primaryKey = "_id"` on the model so `Model.find(hex)` resolves the `id` your resource emits.
+
 ## Output-only rule
 
 Resources map fields. They do not:
@@ -3786,6 +3796,7 @@ export default defineConfig({
     sourcemap: true, // default — true | false | "inline" | "linked"
     singleBundle: false, // default — one runnable file, deps inlined
     esmShim: true, // default — require/__filename/__dirname for bundled CJS
+    routeRegistrationTimeoutMs: 30_000, // default — route-registration child deadline
   },
 });
 ```
@@ -3799,6 +3810,7 @@ Defaults are sensible for the typical "Node service" deployment. Knobs to actual
 - **`sourcemap: false`** — skip source maps entirely. Smaller artifact, but stack traces in production logs lose their file:line precision (and `warlock start` will not enable `--enable-source-maps` since there's nothing to map).
 - **`singleBundle: true`** — inline dependencies so `node dist/app.js` runs with no `node_modules` and no launcher. Sets `packages: "bundle"` + `splitting: false` as **defaults you can override**. ⚠ Native `.node` addons are still emitted alongside — "single bundle" is one JS file _plus_ any native addons. Do NOT reach for it as the default: keeping deps external is right when you deploy the folder.
 - **`esmShim: false`** — only if you are certain nothing in the graph is CommonJS. Leave it on.
+- **`routeRegistrationTimeoutMs`** — increase on busy CI runners when static route registration needs more than 30 seconds. `WARLOCK_ROUTE_REGISTRATION_TIMEOUT_MS` overrides this value for a build; invalid values warn and use 30,000ms.
 
 ⚠ **The trap this replaced.** Setting `packages: "bundle"` by hand used to produce a clean build whose process died on start with `Error: Dynamic require of "node:assert" is not supported`. The output is ESM; bundled CJS deps call `require(...)` and read `__dirname`, and neither exists in an ES module, so the bundler substitutes a throwing stub. **A green `warlock build` was not evidence the bundle ran.** `esmShim` now injects `createRequire(import.meta.url)` and friends automatically for any ESM build, so both `singleBundle` and a hand-written `packages: "bundle"` work. An existing hand-written `banner` is preserved — the shim is prepended, not substituted.
 
@@ -5265,7 +5277,7 @@ Some tests need the full stack: route matching, middleware chain, validation, co
 
 `startHttpTestServer()` is the bootstrap. `testGet` / `testPost` / `expectJson` are the call helpers. Both ship in `@warlock.js/core/tests`.
 
-⚠ **Changed in 4.13.0 — the import is a subpath now.** These helpers used to be re-exported from the package root; they are not any more, because that put the test helpers into every application's production module graph. `import { testGet } from "@warlock.js/core"` now fails with *"has no exported member"* — **add `/tests` to the specifier and nothing else changes.**
+⚠ **Changed in 4.13.0 — the import is a subpath now.** These helpers used to be re-exported from the package root; they are not any more, because that put the test helpers into every application's production module graph. `import { testGet } from "@warlock.js/core"` now fails with _"has no exported member"_ — **add `/tests` to the specifier and nothing else changes.**
 
 ## The shape
 
@@ -5306,7 +5318,7 @@ import { startHttpTestServer, stopHttpTestServer } from "@warlock.js/core/tests"
 - Loads `warlock.config.ts` + bootstrap + `filesOrchestrator` (without file watching).
 - Loads `src/config/*.ts`.
 - Loads every module (`routes.ts`, `main.ts`, `events/*.ts`).
-- Starts **ALL** connectors, including HTTP.
+- Starts **ALL** connectors, including HTTP, by default.
 
 Unlike the dev server, it doesn't watch files, doesn't do HMR, doesn't run health checkers. Just a working HTTP endpoint listening on the configured port.
 
@@ -5326,6 +5338,14 @@ The explicit port wins over `http.port` — including over `HTTP_PORT` in `.env`
 
 The request helpers follow with no extra wiring: the bound port is published as `WARLOCK_TEST_SERVER_PORT`, which the workers inherit, and `getTestServerUrl()` prefers it over their own `.env`-resolved `http.port`. `stopHttpTestServer()` withdraws it.
 
+### API-only suites — `startHttpTestServer({ web: false })`
+
+```ts
+await startHttpTestServer({ web: false });
+```
+
+Use this in `globalSetup` for a suite that exercises API routes only. It still boots the HTTP connector and every other configured connector, but excludes the optional `web` connector before its lifecycle begins. That means web's lazy delegate never constructs `WebConnector`, and Vite is never created. Omitting `web` keeps the default full-stack behavior.
+
 ### The port is preflighted
 
 Before binding, the test server checks the resolved port is free and fails with an instruction if it isn't:
@@ -5381,8 +5401,8 @@ import { defineConfig } from "vitest/config";
 export default defineConfig({
   plugins: [lowerStage3Decorators(), mongezVite()],
   test: {
-    globalSetup: "./src/test-global-setup.ts",  // ← starts the HTTP server
-    setupFiles: ["./src/test-setup.ts"],         // ← setupTest + afterAll(teardownTest), per test file
+    globalSetup: "./src/test-global-setup.ts", // ← starts the HTTP server
+    setupFiles: ["./src/test-setup.ts"], // ← setupTest + afterAll(teardownTest), per test file
     environment: "node",
     globals: false,
     include: ["src/app/**/*.test.ts"],
@@ -5418,7 +5438,7 @@ Everything is built on native `fetch` — no extra dependency, no special wire f
 ```ts
 import { getTestServerUrl } from "@warlock.js/core/tests";
 
-const url = getTestServerUrl();  // → "http://localhost:2031" (defaults)
+const url = getTestServerUrl(); // → "http://localhost:2031" (defaults)
 ```
 
 Reads `http.host` (default `"localhost"`) and `http.port` (default `2031`) from config — unless `startHttpTestServer` published a port, which wins, since a worker's own config never sees the `{ port }` option passed in `globalSetup`. If you change the HTTP config, helpers follow automatically.
@@ -5456,9 +5476,9 @@ import { expectJson, parseJsonResponse } from "@warlock.js/core/tests";
 const body = await parseJsonResponse<MyShape>(response);
 
 // Assert status + parse in one call
-const body = await expectJson<MyShape>(response);          // expects 200
-const body = await expectJson<MyShape>(response, 201);     // expects 201
-const body = await expectJson<MyShape>(response, 404);     // expects 404 (testing error paths)
+const body = await expectJson<MyShape>(response); // expects 200
+const body = await expectJson<MyShape>(response, 201); // expects 201
+const body = await expectJson<MyShape>(response, 404); // expects 404 (testing error paths)
 ```
 
 `expectJson` throws with the actual status + response body when the assertion fails — no chasing "got 500" messages without context.
@@ -5494,7 +5514,7 @@ describe("Products API — happy path", () => {
 
 ```ts
 it("rejects missing required fields with 400", async () => {
-  const response = await testPost("/products", { name: "" });  // price missing
+  const response = await testPost("/products", { name: "" }); // price missing
   const body = await expectJson<{ errors: Array<{ key: string }> }>(response, 400);
 
   expect(body.errors.some((e) => e.key === "price")).toBe(true);
@@ -5619,13 +5639,13 @@ For unit tests, you import the thing under test and call it directly. No HTTP, n
 
 ⚠ **Corrected in 4.14.0 — `setupTest` is CALLED once per TEST FILE, not once per worker.** Every version of this skill through 4.13.0 said "per worker", the generated `src/test-setup.ts` carries a `Per-Worker Test Setup` comment saying the same thing, and **both were wrong.** Vitest runs `setupFiles` before **each test file**, and the setup module's registry is rebuilt every time — measured across all four `pool` × `isolate` combinations.
 
-⛔ **If your project was generated before 4.14.0, fix BOTH the comment and the call.** The comment is false, **and** the generated `setupTest({ connectors: true })` is now an *explicit* value that overrides your `src/config/tests.ts`. **Bare `setupTest()` is the correct call.**
+⛔ **If your project was generated before 4.14.0, fix BOTH the comment and the call.** The comment is false, **and** the generated `setupTest({ connectors: true })` is now an _explicit_ value that overrides your `src/config/tests.ts`. **Bare `setupTest()` is the correct call.**
 
 **The lifetime is FILE-SCOPED, on purpose.** Your setup file bootstraps the framework and its `afterAll(teardownTest)` closes it, once per test file. **One owner, one pairing — correct under every pool, every isolation setting, and watch mode.**
 
-⚠ **A worker-scoped lifetime is possible and is deliberately not shipped yet.** Lifecycle state now lives in the worker runtime, so leaving the framework running would let every file in a worker share one bootstrap. Two things block claiming it: under `pool: "threads"` we cannot observe whether Node reclaims a torn-down thread's sockets and pools, and **in watch mode Vitest reuses workers between reruns, so there is no recycle and no cleanup owner.** It gets taken when the real cost is measured and the integration is chosen, not inherited. See *Lifecycle and repeated calls* below.
+⚠ **A worker-scoped lifetime is possible and is deliberately not shipped yet.** Lifecycle state now lives in the worker runtime, so leaving the framework running would let every file in a worker share one bootstrap. Two things block claiming it: under `pool: "threads"` we cannot observe whether Node reclaims a torn-down thread's sockets and pools, and **in watch mode Vitest reuses workers between reruns, so there is no recycle and no cleanup owner.** It gets taken when the real cost is measured and the integration is chosen, not inherited. See _Lifecycle and repeated calls_ below.
 
-⚠ **Changed in 4.13.0 — the import is a subpath now.** `setupTest` used to be re-exported from the package root; it is not any more, because that put the test helpers into every application's production module graph. `import { setupTest } from "@warlock.js/core"` now fails with *"has no exported member"* — **add `/tests` to the specifier and nothing else changes.**
+⚠ **Changed in 4.13.0 — the import is a subpath now.** `setupTest` used to be re-exported from the package root; it is not any more, because that put the test helpers into every application's production module graph. `import { setupTest } from "@warlock.js/core"` now fails with _"has no exported member"_ — **add `/tests` to the specifier and nothing else changes.**
 
 ## The shape
 
@@ -5642,7 +5662,7 @@ describe("registerUserService", () => {
     });
 
     expect(user.get("email")).toBe("test@example.com");
-    expect(user.get("password")).not.toBe("secret");  // hashed by useHashedPassword()
+    expect(user.get("password")).not.toBe("secret"); // hashed by useHashedPassword()
 
     const found = await usersRepository.first({ email: "test@example.com" });
     expect(found).toBeDefined();
@@ -5667,18 +5687,18 @@ What it does (in order):
 3. Runs `bootstrap()` — env, app, prestart hooks.
 4. Initializes the `filesOrchestrator` (module/route/config discovery, no file watching).
 5. Loads all `src/config/*.ts` files.
-6. Resolves the connector selection — **an explicit parameter wins, then `tests.connectors` from config, then the `true` default.** See *Selecting connectors* below.
+6. Resolves the connector selection — **an explicit parameter wins, then `tests.connectors` from config, then the `true` default.** See _Selecting connectors_ below.
 7. Starts the chosen connectors — but **never `http`** when you pass a boolean. HTTP is the global-setup's job.
 
 The result: DB/cache/logger/storage connections your code can use. Models save, repositories query, services run. Same code as production, just isolated to the test process.
 
 ### The `connectors` parameter
 
-| Value                  | Boots                                                            | Use when                                              |
-| ---------------------- | ---------------------------------------------------------------- | ----------------------------------------------------- |
-| `true` *(default)*     | Every connector except `http` — via `startWithout(["http"])` (db, cache, logger, storage, and socket if configured) | Most service / repository / model tests.              |
-| `false`                | None                                                             | Pure logic tests with no DB / cache touches (parsers, validators, util functions). |
-| `["database", "cache"]` | Just those, in that order                                        | A test that only needs DB but not, say, the storage driver. |
+| Value                   | Boots                                                                                                               | Use when                                                                           |
+| ----------------------- | ------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------- |
+| `true` _(default)_      | Every connector except `http` — via `startWithout(["http"])` (db, cache, logger, storage, and socket if configured) | Most service / repository / model tests.                                           |
+| `false`                 | None                                                                                                                | Pure logic tests with no DB / cache touches (parsers, validators, util functions). |
+| `["database", "cache"]` | Just those, in that order                                                                                           | A test that only needs DB but not, say, the storage driver.                        |
 
 The default `true` is the sane choice. Reach for `false` when the unit you're testing genuinely doesn't talk to any framework subsystem — pulling up a DB connection **for every file** just to test a string parser is wasted setup time.
 
@@ -5694,25 +5714,25 @@ export default testsConfigurations;
 
 ⚠ **BREAKING in 4.14.0 — the precedence flipped.**
 
-| | Order |
-|---|---|
-| **4.13.0 and earlier** | `tests.connectors` config **>** `setupTest({ connectors })` parameter **>** `true` |
-| **4.14.0 onward** | **explicit `setupTest({ connectors })` parameter** **>** `tests.connectors` config **>** `true` |
+|                        | Order                                                                                           |
+| ---------------------- | ----------------------------------------------------------------------------------------------- |
+| **4.13.0 and earlier** | `tests.connectors` config **>** `setupTest({ connectors })` parameter **>** `true`              |
+| **4.14.0 onward**      | **explicit `setupTest({ connectors })` parameter** **>** `tests.connectors` config **>** `true` |
 
-**An explicit call-site value now beats project config.** If your project sets `tests.connectors` *and* some test file passes `connectors` explicitly, **that file will start a different connector set after upgrading.** Search for `setupTest({` across your tests before you upgrade — a call passing `connectors` was previously ignored and is now honoured.
+**An explicit call-site value now beats project config.** If your project sets `tests.connectors` _and_ some test file passes `connectors` explicitly, **that file will start a different connector set after upgrading.** Search for `setupTest({` across your tests before you upgrade — a call passing `connectors` was previously ignored and is now honoured.
 
 **"Explicit" means you supplied a non-`undefined` value.** Both of these fall through to config:
 
 ```ts
-await setupTest();                       // → tests.connectors, else true
-await setupTest({});                     // → tests.connectors, else true
+await setupTest(); // → tests.connectors, else true
+await setupTest({}); // → tests.connectors, else true
 await setupTest({ connectors: undefined }); // → tests.connectors, else true — NOT "start none"
 ```
 
 The `undefined` rule is deliberate: an optional variable that happens to be `undefined` must not silently erase your project config.
 
 ```ts
-await setupTest({ connectors: false });        // → none, even if config says otherwise
+await setupTest({ connectors: false }); // → none, even if config says otherwise
 await setupTest({ connectors: ["database"] }); // → exactly that, even if config differs
 ```
 
@@ -5739,7 +5759,7 @@ afterAll(teardownTest);
 ⛔ **Three things changed here in 4.14.0. If you generated this file earlier, replace all three — it is not a comment fix.**
 
 1. **`afterAll(teardownTest)` is new and mandatory.** Nothing else closes the framework your tests started. This is what makes the lifetime file-scoped and owned rather than left running.
-2. **The call is now bare `setupTest()`, not `setupTest({ connectors: true })`.** Under the flipped precedence, passing `true` is an *explicit* value and would override `tests.connectors` for **every file in the project.** Bare means "whatever this project configured, else the default".
+2. **The call is now bare `setupTest()`, not `setupTest({ connectors: true })`.** Under the flipped precedence, passing `true` is an _explicit_ value and would override `tests.connectors` for **every file in the project.** Bare means "whatever this project configured, else the default".
 3. **The comment used to say `Per-Worker Test Setup` / "Runs in EACH Vitest worker thread".** False — see the top of this skill.
 
 ```ts title="vite.config.ts"
@@ -5750,8 +5770,8 @@ import { defineConfig } from "vitest/config";
 export default defineConfig({
   plugins: [lowerStage3Decorators(), mongezVite()],
   test: {
-    globalSetup: "./src/test-global-setup.ts",  // ← HTTP server (see test-http skill)
-    setupFiles: ["./src/test-setup.ts"],         // ← runs setupTest before EACH test file
+    globalSetup: "./src/test-global-setup.ts", // ← HTTP server (see test-http skill)
+    setupFiles: ["./src/test-setup.ts"], // ← runs setupTest before EACH test file
     environment: "node",
     globals: false,
     include: ["src/app/**/*.test.ts"],
@@ -5797,9 +5817,9 @@ describe("createProductService", () => {
   it("rejects duplicate names", async () => {
     await Product.create({ name: "Existing", price: 10 });
 
-    await expect(
-      createProductService({ name: "Existing", price: 20 }),
-    ).rejects.toThrow(/already exists/i);
+    await expect(createProductService({ name: "Existing", price: 20 })).rejects.toThrow(
+      /already exists/i,
+    );
   });
 });
 ```
@@ -5869,7 +5889,7 @@ afterEach(async () => {
 
 Vitest runs the tests within one file sequentially, so an `afterEach` truncate gives each test a clean slate.
 
-⚠ **Cross-*file* isolation is not solved by this.** Separate workers get separate **connections**, not separate **rows** — two files pointed at the same database see each other's committed data regardless of pool or worker count. **Truncate what your file wrote; don't assume the worker boundary did it for you.** Real data isolation (DB-per-worker, transaction-per-test) is a separate piece of work and is not in this release.
+⚠ **Cross-_file_ isolation is not solved by this.** Separate workers get separate **connections**, not separate **rows** — two files pointed at the same database see each other's committed data regardless of pool or worker count. **Truncate what your file wrote; don't assume the worker boundary did it for you.** Real data isolation (DB-per-worker, transaction-per-test) is a separate piece of work and is not in this release.
 
 ### Skipping connectors for pure logic tests
 
@@ -5879,7 +5899,7 @@ import { setupTest } from "@warlock.js/core/tests";
 import { slugify } from "../utils/slugify";
 
 beforeAll(async () => {
-  await setupTest({ connectors: false });  // starts no connectors at all
+  await setupTest({ connectors: false }); // starts no connectors at all
 });
 
 describe("slugify", () => {
@@ -5906,7 +5926,7 @@ beforeAll(async () => {
 });
 
 afterAll(async () => {
-  await teardownTest();      // ← REQUIRED, see below
+  await teardownTest(); // ← REQUIRED, see below
 });
 ```
 
@@ -5927,16 +5947,16 @@ afterAll(async () => {
 
 `setupTest` / `teardownTest` are a pair. **The harness that calls one owns calling the other in the same context.**
 
-| Call | Behaviour |
-|---|---|
-| `setupTest(x)` while idle | bootstraps |
-| `setupTest(x)` while already ready with the **same** effective options | no-op |
-| `setupTest(y)` while ready or starting with **different** effective options | ⛔ **rejects**, naming active vs requested |
-| two concurrent `setupTest(x)` calls | share one startup |
-| `setupTest` after a failed setup | allowed — a failed setup unwinds and returns to idle |
-| `teardownTest()` while idle | no-op |
-| two concurrent `teardownTest()` calls | share one shutdown |
-| `setupTest(y)` after a **successful** teardown | allowed, different options fine |
+| Call                                                                        | Behaviour                                            |
+| --------------------------------------------------------------------------- | ---------------------------------------------------- |
+| `setupTest(x)` while idle                                                   | bootstraps                                           |
+| `setupTest(x)` while already ready with the **same** effective options      | no-op                                                |
+| `setupTest(y)` while ready or starting with **different** effective options | ⛔ **rejects**, naming active vs requested           |
+| two concurrent `setupTest(x)` calls                                         | share one startup                                    |
+| `setupTest` after a failed setup                                            | allowed — a failed setup unwinds and returns to idle |
+| `teardownTest()` while idle                                                 | no-op                                                |
+| two concurrent `teardownTest()` calls                                       | share one shutdown                                   |
+| `setupTest(y)` after a **successful** teardown                              | allowed, different options fine                      |
 
 **"Same options" is compared by meaning, not by literal value** — connector arrays are deduplicated and compared as sets, so `["cache", "database"]` and `["database", "cache", "cache"]` are the same selection.
 
@@ -5951,7 +5971,7 @@ afterAll(async () => {
 ```ts title="src/config/tests.ts"
 const testsConfigurations = {
   connectors: ["database", "logger"],
-  setupTimeout: 120000,   // milliseconds — this is the default
+  setupTimeout: 120000, // milliseconds — this is the default
 };
 
 export default testsConfigurations;
@@ -5970,9 +5990,9 @@ in `src/config/tests.ts` — milliseconds, default 120000.
 1. **It bounds the setup ATTEMPT, not teardown separately.** `teardownTest()` awaits the same attempt, so it inherits the bound — **one timer, not two.** A second teardown-side deadline was tried and rejected: it re-introduced the unbounded re-entry this whole guard exists to remove.
 2. **Expiry poisons the lifecycle**, it does not return to `idle`. The attempt may have started connectors nobody can now account for, so pretending the runtime is clean would be worse than refusing.
 3. **⛔ An invalid `setupTimeout` throws, naming the bad value.** Zero, negative and non-numeric all fail loudly rather than falling back to the default — a silent fallback would hide a typo behind a working suite.
-4. **The bound is measured from when the attempt started**, not from when config was read. `tests.setupTimeout` is only readable after `loadConfigFiles()`, which happens *inside* the window being bounded; re-arming naively would give you the default plus your configured value.
+4. **The bound is measured from when the attempt started**, not from when config was read. `tests.setupTimeout` is only readable after `loadConfigFiles()`, which happens _inside_ the window being bounded; re-arming naively would give you the default plus your configured value.
 
-⚠ **What is proven and what is not.** The nine guards above were each seen to fail under their own mutation. **But every spec injects its scheduler**, so the default *value* is tested while the production timer — and whether its `unref` actually releases the worker — is not. **And no spec observes a real hang**: the stuck attempt is a mock gate, not a socket that never returns. These prove what the lifecycle *decides*, not what a genuinely wedged connector does.
+⚠ **What is proven and what is not.** The nine guards above were each seen to fail under their own mutation. **But every spec injects its scheduler**, so the default _value_ is tested while the production timer — and whether its `unref` actually releases the worker — is not. **And no spec observes a real hang**: the stuck attempt is a mock gate, not a socket that never returns. These prove what the lifecycle _decides_, not what a genuinely wedged connector does.
 
 ### State is per worker runtime, not per module
 
@@ -6003,6 +6023,16 @@ In both cases the guard's scope matches the resource's scope, which is the point
 - [`warlock-conventions/SKILL.md`](../warlock-conventions/SKILL.md) — where tests live in a module (`tests/*.test.ts`).
 - [`write-cli-command/SKILL.md`](../write-cli-command/SKILL.md) — `warlock add test` for the initial scaffold.
 
+## App modules and `importModule`
+
+Under Vitest, test files run through vite-node while Warlock's own native `import()` of app modules (config, routes, events) does not, so app classes such as `User` can exist twice in one worker and `instanceof` fails. Pass `importModule` to `setupTest` so Warlock loads app modules through the test's own module graph:
+
+```ts
+setupTest({ importModule: (file) => import(file) });
+```
+
+The generated `src/test-setup.ts` already does this. Without it, `setupTest()` under Vitest warns once.
+
 
 ## update-packages  `@warlock.js/core/update-packages/SKILL.md`
 
@@ -6764,7 +6794,7 @@ cors: {
 
 ---
 name: use-localization
-description: 'Multi-locale translations via `groupedTranslations` (declare keys), `t()` / `request.t()` / `request.trans()` (look up), `request.getLocaleCode()` (detect locale from headers/query), `getLocalized` (pick the right value from a localized-array column). Triggers: `groupedTranslations`, `t`, `request.t`, `request.trans`, `request.transFrom`, `request.getLocaleCode`, `request.setLocaleCode`, `getLocalized`; "add a translation key", "resolve a localized error message", "detect request locale", "pick the right per-locale column value"; typical import `import { t, getLocalized } from "@warlock.js/core"`. Skip: resource output — `@warlock.js/core/define-resource/SKILL.md`; module scaffold — `@warlock.js/core/create-module/SKILL.md`; competing libs `i18next`, `react-intl`, raw `@mongez/localization`.'
+description: 'Multi-locale translations via `groupedTranslations` (declare keys), `t()` (look up; always use it in app code, never `request.t()`), `request.getLocaleCode()` (detect locale from headers/query), `getLocalized` (pick the right value from a localized-array column). Triggers: `groupedTranslations`, `t`, `request.t`, `request.trans`, `request.transFrom`, `request.getLocaleCode`, `request.setLocaleCode`, `getLocalized`; "add a translation key", "resolve a localized error message", "detect request locale", "pick the right per-locale column value"; typical import `import { t, getLocalized } from "@warlock.js/core"`. Skip: resource output — `@warlock.js/core/define-resource/SKILL.md`; module scaffold — `@warlock.js/core/create-module/SKILL.md`; competing libs `i18next`, `react-intl`, raw `@mongez/localization`.'
 ---
 
 # Warlock — translate keys + pick localized values
@@ -6779,7 +6809,7 @@ Both pivot on **the request's locale** — auto-detected from headers / query st
 ## The shape
 
 ```ts
-// 1. Declare keys (auto-loaded from src/app/<module>/utils/locales.ts)
+// 1. Declare keys (auto-loaded from src/app/<module>/utils/locales.json)
 import { groupedTranslations } from "@mongez/localization";
 
 groupedTranslations("products", {
@@ -6791,8 +6821,7 @@ groupedTranslations("products", {
 import { t } from "@warlock.js/core";
 
 throw new ResourceNotFoundError(t("products.notFound"));
-// or via the request:
-return response.success({ message: request.t("products.created") });
+return response.success({ message: t("products.created") });
 
 // 3. Pick a value from a localized-array column
 import { getLocalized } from "@warlock.js/core";
@@ -6801,7 +6830,26 @@ const name = getLocalized(product.get("name_translations"));
 // → reads the current request's locale, returns the matching value
 ```
 
-## Declaring translations — `groupedTranslations`
+## Declaring translations — module `locales.json`
+
+Prefer a data-only dictionary in `src/app/<module>/utils/locales.json`. The
+module folder is its default group, so this example registers
+`products.notFound`; a root `$group` string replaces that group when a module
+needs a different namespace. The module loader validates the strict JSON
+shape, flattens nested keys, and rejects duplicate ownership. Do not import the
+file yourself.
+
+```json title="src/app/products/utils/locales.json"
+{
+  "notFound": { "en": "Product not found", "ar": "المنتج غير موجود" },
+  "errors": { "outOfStock": { "en": "Product out of stock", "ar": "المنتج غير متوفر" } }
+}
+```
+
+`utils/locales.ts` with `groupedTranslations` remains supported but is
+deprecated and will be removed in v6. Migrate it with `warlock doctor --fix`.
+
+### Legacy `groupedTranslations`
 
 Every module owns its translation namespace under `src/app/<module>/utils/locales.ts`. The file is auto-loaded at boot — you don't import it from anywhere; the framework picks it up via the module loader.
 
@@ -6838,31 +6886,25 @@ t("products.outOfStock", { name: "Pen", count: 0 });
 
 Placeholders use the `:name` syntax. The lookup helper substitutes them from the second argument.
 
-## Looking up translations — `t()`, `request.t()`, `request.trans()`
+## Looking up translations — always `t()`
 
-Three calls, same job, slightly different reachability:
+**Rule: app code translates with `t()` from `@warlock.js/core`.** It works everywhere: controllers, services, page and layout loaders, `metadata`, events and jobs. It returns a `string`.
 
 ```ts
-// 1. Top-level helper — works inside or outside a request.
-//    Inside a request: uses request's locale.
-//    Outside: uses the global default locale.
 import { t } from "@warlock.js/core";
 
 t("products.notFound");
 t("products.outOfStock", { name: "Pen", count: 0 });
-
-// 2. On the request object — explicit, scoped to that request.
-request.t("products.notFound");
-
-// 3. Alias for request.t — same behavior.
-request.trans("products.notFound");
 ```
 
-All three lookups go through `@mongez/localization`'s `trans()` under the hood, with the locale pulled from the request context (or the global default).
+- Inside a request (a controller or a page loader) it uses the request's locale. In a page it first checks the route's `locales.json` snapshot, then falls back to module translations (`groupedTranslations` or module `locales.json`).
+- Outside a request (jobs, CLI) it uses the configured default locale.
+- `request.t()` / `request.trans()` are the per-request binding that `t()` delegates to. Don't call them in app code: `t()` gives the same result without threading `request` through services.
+- Don't wrap it in `String(...)`; it is already typed `string`.
 
 ### Web `useTrans()` key checking
 
-When an app uses `@warlock.js/web`, `warlock dev` writes `.warlock/typings/translations.d.ts` from literal `groupedTranslations("group", { key: ... })` registrations. It augments web's `TranslationKeyRegistry`, so `useTrans()("products.notFound")` is checked against registered keys and a typo fails TypeScript. Before the generated file exists, `useTrans()` accepts `string` for a non-breaking first boot. Dynamic groups/keys and placeholders are not inferred.
+When an app uses `@warlock.js/web`, `warlock dev` writes `.warlock/typings/translations.d.ts` from module `locales.json` dictionaries and literal `groupedTranslations("group", { key: ... })` registrations. It augments web's `TranslationKeyRegistry`, so `useTrans()("products.notFound")` is checked against registered keys and a typo fails TypeScript. Before the generated file exists, `useTrans()` accepts `string` for a non-breaking first boot. Dynamic TypeScript groups/keys and placeholders are not inferred.
 
 `useTrans()` now works correctly across hydration (5.15.0): the hydration
 payload ships a `translations` key with the active locale's keywords, and
@@ -6908,7 +6950,7 @@ export default {
 request.setLocaleCode("ar");
 ```
 
-After this, every `request.t(...)` and `getLocalized(...)` in the same request returns Arabic. Useful for user-preference overrides (e.g. "this user has set their language to ar in their profile — switch the request's locale on auth").
+After this, every `t(...)` and `getLocalized(...)` in the same request returns Arabic. Useful for user-preference overrides (e.g. "this user has set their language to ar in their profile — switch the request's locale on auth").
 
 ## Localized columns — `getLocalized`
 
@@ -7005,6 +7047,7 @@ The error's message is locale-aware — the `inject-request-context` middleware
 import { type GuardedRequestHandler } from "app/auth/requests/guarded.request";
 import { type CreateProductSchema } from "../schema/create-product.schema";
 import { createProductService } from "../services/create-product.service";
+import { t } from "@warlock.js/core";
 
 export const createProductController: GuardedRequestHandler<CreateProductSchema> = async ({
   request,
@@ -7012,7 +7055,7 @@ export const createProductController: GuardedRequestHandler<CreateProductSchema>
 }) => {
   const product = await createProductService(request.validated());
   return response.success({
-    message: request.t("products.created"),
+    message: t("products.created"),
     product,
   });
 };
@@ -7052,11 +7095,11 @@ await Product.create({
 GET /products/42?locale=ar
 ```
 
-`request.getLocaleCode()` returns `"ar"` — every `request.t(...)` and resource-output `getLocalized` returns Arabic. No app code changes required.
+`request.getLocaleCode()` returns `"ar"` — every `t(...)` and resource-output `getLocalized` returns Arabic. No app code changes required.
 
 ## Gotchas
 
-- **Locales files are auto-loaded — don't import them.** `src/app/<module>/utils/locales.ts` is picked up by the module loader on boot. Importing it manually causes double-registration warnings.
+- **Locales files are auto-loaded — don't import them.** `src/app/<module>/utils/locales.json` is picked up by the module loader on boot. Importing legacy `locales.ts` manually causes double-registration warnings.
 - **Group names should match module URL slugs.** `groupedTranslations("products", ...)` for the `/products` module. Mismatch breaks the convention but doesn't throw.
 - **Every key needs every locale.** If a key is missing for the active locale, the lookup falls back to the key string itself (`"products.notFound"` literally appears in the response). Always ship all locales together when adding a key.
 - **`t()` outside a request uses the global default.** `Application.environment === "test"` or background jobs without a request context get the configured `app.localeCode`, not whatever the most recent request used.
@@ -7069,8 +7112,8 @@ GET /products/42?locale=ar
 
 - [`send-response/SKILL.md`](../send-response/SKILL.md) — error helpers that pair with translated messages (`response.notFound({ error: t("...") })`).
 - [`define-resource/SKILL.md`](../define-resource/SKILL.md) — using `getLocalized` inside resource output for clean per-locale responses.
-- [`create-module/SKILL.md`](../create-module/SKILL.md) — the `utils/locales.ts` file is part of the generated module scaffold.
-- [`warlock-conventions/SKILL.md`](../warlock-conventions/SKILL.md) — `utils/locales.ts` is auto-loaded; the suffix is mandatory.
+- [`create-module/SKILL.md`](../create-module/SKILL.md) — the `utils/locales.json` file is part of the generated module scaffold.
+- [`warlock-conventions/SKILL.md`](../warlock-conventions/SKILL.md) — `utils/locales.json` is auto-loaded; the suffix is mandatory.
 
 ## Route-owned web translations (5.17)
 
@@ -7084,9 +7127,9 @@ GET /products/42?locale=ar
 }
 ```
 
-This produces `account.title` and `account.actions.save`. Keep every leaf complete for the configured locale list. The page pipeline selects an immutable snapshot for its route source and locale. `useTrans()`, `request.t()`, and `request.trans()` use that snapshot; a missing scoped key returns the key itself. With no route-locales manifest, the existing global `@mongez/localization` registry remains the legacy fallback path.
+This produces `account.title` and `account.actions.save`. Keep every leaf complete for the configured locale list. The page pipeline selects an immutable snapshot for its route source and locale. `useTrans()` and `t()` use that snapshot; a missing scoped key returns the key itself. With no route-locales manifest, the existing global `@mongez/localization` registry remains the legacy fallback path.
 
-When a route-locales snapshot applies, `request.t()`, `request.trans()`, and `request.transFrom(locale, key, placeholders?)` resolve through it; without one, they retain the existing global-registry behavior. The underlying `transFromKeywords(locale, keywords, key, placeholders?, converter?)` is supplied by `@mongez/localization` 3.5.0. Error pages rebind to their own snapshot, while framework fallback uses the app/root snapshot. Development HMR add/edit/delete publishes a new snapshot, and the snapshot revision keeps page-cache entries from reusing old JSON. Generated `.warlock` typings contain the flattened route keys; do not maintain a second handwritten key union.
+When a route-locales snapshot applies, `t()` (through the request binding) and `request.transFrom(locale, key, placeholders?)` resolve through it; without one, they retain the existing global-registry behavior. The underlying `transFromKeywords(locale, keywords, key, placeholders?, converter?)` is supplied by `@mongez/localization` 3.5.0. Error pages rebind to their own snapshot, while framework fallback uses the app/root snapshot. Development HMR add/edit/delete publishes a new snapshot, and the snapshot revision keeps page-cache entries from reusing old JSON. Generated `.warlock` typings contain the flattened route keys; do not maintain a second handwritten key union.
 
 
 ## use-middleware  `@warlock.js/core/use-middleware/SKILL.md`

package/llms.txt

@@ -33,7 +33,7 @@
 - [update-packages](@warlock.js/core/update-packages/SKILL.md): Keep a project current with `warlock update` — bump every `@warlock.js/*` dependency in package.json to its latest published version (range operator preserved), then run the lockfile-detected package manager install. Also covers the `warlock dev` update notice, its `u` update-and-restart keyboard shortcut, and the `devServer.checkForUpdates` toggle. Triggers: `warlock update`, `--no-install`, `--dry-run`, `--check`, `checkForUpdates`, `fetchLatestVersion`, `isNewerVersion`; "update warlock packages", "upgrade the framework", "is there a new warlock version", "update notice in the dev server", "press u to update", "dev server keyboard shortcut", "update check offline", "bump @warlock.js/* to latest"; typical CLI `warlock update`. Skip: dev/build/start runtime — `@warlock.js/core/run-app/SKILL.md`; writing a custom command — `@warlock.js/core/write-cli-command/SKILL.md`; installing a NEW feature package (auth, mail, storage) — that is `warlock add`; releasing/publishing the framework — workspace release tooling, not this command.
 - [upload-file](@warlock.js/core/upload-file/SKILL.md): Handle multipart file uploads — read via `request.file()` or `request.validated()`, validate with `v.file()`, save via `UploadedFile.save()` or the storage layer, transform images inline. Triggers: `UploadedFile`, `request.file`, `v.file`, `.save`, `.saveAs`, `.resize`, `.format`, `.quality`, `.image`, `.mimeType`, `.maxSize`; "accept a file upload", "validate file size and mime", "save to S3 or local disk", "resize an uploaded image on save"; typical import `import type { UploadedFile, RequestHandler } from "@warlock.js/core"`. Skip: storage drivers + presigned URLs — `@warlock.js/core/store-file/SKILL.md`; image-only transforms — `@warlock.js/core/process-image/SKILL.md`; schema rules — `@warlock.js/core/validate-input/SKILL.md`; competing libs `multer`, `formidable`, `busboy`.
 - [use-app-context](@warlock.js/core/use-app-context/SKILL.md): Read app-wide context — the `Application` static class (env, version, uptime, runtime strategy, boot lifecycle) plus the `app` runtime accessor (live Fastify, socket.io, router, database via the DI container). Triggers: `Application.isProduction`, `Application.environment`, `Application.runtimeStrategy`, `Application.uptime`, `Application.version`, `Application.onceBooted`, `Application.whenBooted`, `Application.isBooted`, `Application.onShutdown`, `Application.isShuttingDown`, `app.http`, `app.socket`, `app.database`, `app.router`; "branch on environment", "reach the live Fastify instance", "framework version in health endpoint", "dev vs production runtime check", "run code once the app is fully booted", "after all connectors started", "app booted hook", "run cleanup before shutdown", "graceful shutdown hook"; typical import `import { Application, app } from "@warlock.js/core"`. Skip: path helpers — `@warlock.js/core/resolve-path/SKILL.md`; connector start order — `@warlock.js/core/add-connector/SKILL.md`; competing patterns: bare `process.env.NODE_ENV`, ad-hoc Fastify imports.
-- [use-localization](@warlock.js/core/use-localization/SKILL.md): Multi-locale translations via `groupedTranslations` (declare keys), `t()` / `request.t()` / `request.trans()` (look up), `request.getLocaleCode()` (detect locale from headers/query), `getLocalized` (pick the right value from a localized-array column). Triggers: `groupedTranslations`, `t`, `request.t`, `request.trans`, `request.transFrom`, `request.getLocaleCode`, `request.setLocaleCode`, `getLocalized`; "add a translation key", "resolve a localized error message", "detect request locale", "pick the right per-locale column value"; typical import `import { t, getLocalized } from "@warlock.js/core"`. Skip: resource output — `@warlock.js/core/define-resource/SKILL.md`; module scaffold — `@warlock.js/core/create-module/SKILL.md`; competing libs `i18next`, `react-intl`, raw `@mongez/localization`.
+- [use-localization](@warlock.js/core/use-localization/SKILL.md): Multi-locale translations via `groupedTranslations` (declare keys), `t()` (look up; always use it in app code, never `request.t()`), `request.getLocaleCode()` (detect locale from headers/query), `getLocalized` (pick the right value from a localized-array column). Triggers: `groupedTranslations`, `t`, `request.t`, `request.trans`, `request.transFrom`, `request.getLocaleCode`, `request.setLocaleCode`, `getLocalized`; "add a translation key", "resolve a localized error message", "detect request locale", "pick the right per-locale column value"; typical import `import { t, getLocalized } from "@warlock.js/core"`. Skip: resource output — `@warlock.js/core/define-resource/SKILL.md`; module scaffold — `@warlock.js/core/create-module/SKILL.md`; competing libs `i18next`, `react-intl`, raw `@mongez/localization`.
 - [use-middleware](@warlock.js/core/use-middleware/SKILL.md): Attach built-in HTTP middleware to routes via the `middleware` namespace from `@warlock.js/core` — rateLimit, concurrencyLimit, maxBodySize, idempotency, maintenance, ipFilter, cache. Plus `X-Request-Id` correlation, wired automatically. Triggers: `middleware.rateLimit`, `middleware.concurrencyLimit`, `middleware.maxBodySize`, `middleware.idempotency`, `middleware.maintenance`, `middleware.ipFilter`, `middleware.cache`, `X-Request-Id`, `Idempotency-Key`; "add rate limiting", "dedupe writes by idempotency key", "cap concurrent requests", "block IPs", "cache a GET response"; typical import `import { middleware } from "@warlock.js/core"`. Skip: author custom middleware — `@warlock.js/core/write-middleware/SKILL.md`; cache singleton — `@warlock.js/cache/cache-basics/SKILL.md`; competing libs `@fastify/rate-limit` direct, `express-rate-limit`, `helmet`.
 - [use-model-transformers](@warlock.js/core/use-model-transformers/SKILL.md): Three schema-side helpers — `useHashedPassword()` (bcrypt on save) attaches via `.addTransformer(...)`; `useComputedSlug(field?, scope?)` (auto-slug from another field) and `useComputedModel(callback)` (arbitrary computed-on-save value) attach via `v.computed(...)`. Triggers: `useHashedPassword`, `useComputedSlug`, `useComputedModel`, `.addTransformer`, `v.computed`, `ComputedCallback`; "auto-hash a password field", "auto-slug from title on save", "derive a value at write time", "declarative model transformers"; typical import `import { useHashedPassword, useComputedSlug } from "@warlock.js/core"`. Skip: bcrypt setup details — `@warlock.js/core/hash-password/SKILL.md`; repository writes — `@warlock.js/core/use-repository/SKILL.md`; output filtering — `@warlock.js/core/define-resource/SKILL.md`; competing patterns: manual `await hashPassword(input)` in services, ORM lifecycle hooks.
 - [use-repository](@warlock.js/core/use-repository/SKILL.md): Subclass `RepositoryManager` for data access — declare `source`, `filterBy`, `defaultOptions`, then call `list()`/`listCached()`/`find()`/`create()`/`update()`/`delete()`, the active/cached/cursor variants, and the `filterBy`-aware aggregates `sum()`/`avg()`/`min()`/`max()`/`groupBy()`/`aggregate()`. Triggers: `RepositoryManager`, `FilterRules`, `RepositoryOptions`, `.list`, `.listCached`, `.find`, `.findCached`, `.create`, `.update`, `.delete`, `.sum`, `.avg`, `.min`, `.max`, `.groupBy`, `.aggregate`, `simpleSelectColumns`; "create a repository", "filter rules for a list endpoint", "cursor vs page pagination", "cached vs uncached read", "sum/avg/group-by with filters"; typical import `import { RepositoryManager } from "@warlock.js/core"`. Skip: cache singleton — `@warlock.js/cache/cache-basics/SKILL.md`; use-case pipelines — `@warlock.js/core/write-use-case/SKILL.md`; wire mapping — `@warlock.js/core/define-resource/SKILL.md`; competing libs `typeorm` Repository, `prisma.client.<model>`, `@nestjs/typeorm`.

package/package.json

@@ -8,12 +8,12 @@
     "warlock": "bin/warlock.js"
   },
   "dependencies": {
-    "@fastify/cookie": "^10.0.0",
-    "@fastify/cors": "^11.2.0",
-    "@fastify/http-proxy": "^11.4.1",
-    "@fastify/multipart": "^9.3.0",
-    "@fastify/rate-limit": "^10.3.0",
-    "@fastify/static": "^8.3.0",
+    "@fastify/cookie": "^11.1.2",
+    "@fastify/cors": "^11.3.0",
+    "@fastify/http-proxy": "^11.6.3",
+    "@fastify/multipart": "^10.1.2",
+    "@fastify/rate-limit": "^11.2.0",
+    "@fastify/static": "^10.1.5",
     "@mongez/concat-route": "^1.2.1",
     "@mongez/config": "^1.2.2",
     "@mongez/copper": "^2.1.3",
@@ -25,12 +25,12 @@
     "@mongez/slug": "^1.0.7",
     "@mongez/supportive-is": "^2.1.5",
     "@mongez/time-wizard": "^1.0.6",
-    "@warlock.js/cache": "5.25.0",
-    "@warlock.js/cascade": "5.25.0",
-    "@warlock.js/context": "5.25.0",
-    "@warlock.js/fs": "5.25.0",
-    "@warlock.js/logger": "5.25.0",
-    "@warlock.js/seal": "5.25.0",
+    "@warlock.js/cache": "5.26.0",
+    "@warlock.js/cascade": "5.26.0",
+    "@warlock.js/context": "5.26.0",
+    "@warlock.js/fs": "5.26.0",
+    "@warlock.js/logger": "5.26.0",
+    "@warlock.js/seal": "5.26.0",
     "bcryptjs": "^3.0.3",
     "chokidar": "^5.0.0",
     "dayjs": "^1.11.19",
@@ -38,8 +38,8 @@
     "esbuild": "^0.27.2",
     "eslint": "^9.18.0",
     "fast-glob": "^3.3.3",
-    "fastify": "^5.6.2",
-    "find-my-way": "^9.3.0",
+    "fastify": "^5.12.5",
+    "find-my-way": "^9.9.0",
     "get-tsconfig": "^5.0.0-beta.5",
     "import-meta-resolve": "^4.2.0",
     "mime": "^4.1.0",
@@ -52,11 +52,11 @@
     "@aws-sdk/lib-storage": "^3.955.0",
     "@aws-sdk/s3-request-presigner": "^3.955.0",
     "@react-email/render": "^2.0.5",
-    "@warlock.js/access": "5.25.0",
-    "@warlock.js/ai": "5.25.0",
-    "@warlock.js/herald": "5.25.0",
-    "@warlock.js/notifications": "5.25.0",
-    "@warlock.js/devtools": "5.25.0",
+    "@warlock.js/access": "5.26.0",
+    "@warlock.js/ai": "5.26.0",
+    "@warlock.js/herald": "5.26.0",
+    "@warlock.js/notifications": "5.26.0",
+    "@warlock.js/devtools": "5.26.0",
     "nodemailer": "^8.0.5",
     "react": "^19.2.3",
     "react-dom": "^19.2.3",
@@ -127,7 +127,7 @@
   ],
   "author": "hassanzohdy",
   "license": "MIT",
-  "version": "5.25.0",
+  "version": "5.26.0",
   "type": "module",
   "main": "./esm/index.mjs",
   "module": "./esm/index.mjs",

package/skills/README.md

@@ -34,7 +34,7 @@ Each folder holds one `SKILL.md` (an agent-facing how-to for a single task). The
 - [use-app-context](use-app-context/SKILL.md) — read app-wide context via the `Application` static class and the `app` runtime accessor.
 - [add-connector](add-connector/SKILL.md) — extend the lifecycle with a `BaseConnector` subclass (`start`/`shutdown`/`watchedFiles`).
 - [wire-socket](wire-socket/SKILL.md) — configure Socket.IO, reach the live server via `getSocketServer()` / `app.socket`.
-- [use-localization](use-localization/SKILL.md) — multi-locale translations: `groupedTranslations`, `t()` / `request.t()`, locale resolution.
+- [use-localization](use-localization/SKILL.md) — multi-locale translations: `groupedTranslations`, `t()` (always, never `request.t()`), locale resolution.
 
 ## Use-cases & services
 

package/skills/create-controller/SKILL.md

@@ -102,6 +102,10 @@ Two pieces:
 
 If validation fails, the framework returns a 400 with an `errors` payload and your handler never runs.
 
+### Validating route params
+
+`handler.validation = { params: v.object({ id: v.int().min(1) }) }` validates path segments (e.g. `/posts/:id`). Number and boolean validators convert the string segments; the app's schema object is never changed. Parsed values replace `request.params` (`request.input("id")` is a number) and merge into `request.validated()`, with params winning over body fields. Failures answer like a `schema` failure.
+
 ### Typing a guarded handler
 
 Routes behind `authMiddleware` need `request.locals.user` typed. Project conventions add a `GuardedRequest<TSchema>` (overriding `locals` to `RequestLocals & { user: User }`) and a paired `GuardedRequestHandler<TSchema>` alias in `app/auth/requests/guarded.request`: