@warlock.js/core 5.29.0 → 5.31.0

package/skills/add-connector/SKILL.md

@@ -10,11 +10,7 @@ A **connector** is a long-lived subsystem owned by the framework: database, HTTP
 ## The shape
 
 ```ts title="src/connectors/queue-connector.ts"
-import {
-  BaseConnector,
-  ConnectorLifecyclePhase,
-  type ConnectorName,
-} from "@warlock.js/core";
+import { BaseConnector, ConnectorLifecyclePhase, type ConnectorName } from "@warlock.js/core";
 
 export class QueueConnector extends BaseConnector {
   public readonly name: ConnectorName = "queue";
@@ -40,14 +36,14 @@ That's the connector class. The file's home is `src/connectors/<name>.ts` by con
 
 ## `BaseConnector` — required surface
 
-| Member          | Type                          | Notes                                                                                |
-| --------------- | ----------------------------- | ------------------------------------------------------------------------------------ |
-| `name`          | `ConnectorName`               | Unique. Used in preload lists (`preload.connectors: ["queue"]`).                     |
-| `priority`      | `number`                      | Lower starts first. See built-in `ConnectorPriority` enum for the existing ordering. |
-| `lifecyclePhase`| `ConnectorLifecyclePhase`     | `Early` (default) or `Late`. See phase semantics below.                              |
-| `watchedFiles`  | `string[]` (protected)        | Relative paths; touching any triggers a restart in dev.                              |
-| `start()`       | `() => Promise<void>`         | The work that brings the subsystem online. Set `this.active = true` on success.     |
-| `shutdown()`    | `() => Promise<void>`         | Inverse — close connections, drain queues. Set `this.active = false`.                |
+| Member           | Type                      | Notes                                                                                |
+| ---------------- | ------------------------- | ------------------------------------------------------------------------------------ |
+| `name`           | `ConnectorName`           | Unique. Used in preload lists (`preload.connectors: ["queue"]`).                     |
+| `priority`       | `number`                  | Lower starts first. See built-in `ConnectorPriority` enum for the existing ordering. |
+| `lifecyclePhase` | `ConnectorLifecyclePhase` | `Early` (default) or `Late`. See phase semantics below.                              |
+| `watchedFiles`   | `string[]` (protected)    | Relative paths; touching any triggers a restart in dev.                              |
+| `start()`        | `() => Promise<void>`     | The work that brings the subsystem online. Set `this.active = true` on success.      |
+| `shutdown()`     | `() => Promise<void>`     | Inverse — close connections, drain queues. Set `this.active = false`.                |
 
 Optional overrides:
 
@@ -61,19 +57,19 @@ Optional overrides:
 
 Lower number = earlier. The built-in ordering, from `ConnectorPriority` in `@warlock.js/core/src/connectors/types.ts`:
 
-| Connector     | Priority | Phase   |
-| ------------- | -------- | ------- |
-| `logger`      | 0        | Early   |
-| `mailer`      | 1        | Early   |
-| `database`    | 2        | Early   |
-| `communicator`| 3        | Early   |
-| `cache`       | 4        | Early   |
-| `http`        | 5        | **Late**|
-| `storage`     | 6        | Early   |
-| `socket`      | 7        | **Late**|
-| `notifications`| 8       | Early   |
-| `access`      | 9        | Early   |
-| `ai`          | 10       | Early   |
+| Connector       | Priority | Phase    |
+| --------------- | -------- | -------- |
+| `logger`        | 0        | Early    |
+| `mailer`        | 1        | Early    |
+| `database`      | 2        | Early    |
+| `communicator`  | 3        | Early    |
+| `cache`         | 4        | Early    |
+| `http`          | 5        | **Late** |
+| `storage`       | 6        | Early    |
+| `socket`        | 7        | **Late** |
+| `notifications` | 8        | Early    |
+| `access`        | 9        | Early    |
+| `ai`            | 10       | Early    |
 
 Pick a number that places your connector where it belongs. If your queue needs the database, set `priority > 2` (e.g. `11`). If you replace the cache, set `< 4` to win.
 
@@ -85,7 +81,7 @@ Negative priorities are fine for "start before everything" — the project's `sr
 
 `ConnectorLifecyclePhase` exists because **HTTP and socket need user code loaded first**: they scan the router (which user `routes.ts` files populate) and the container (which app `main.ts` files mutate). So the framework boots in two passes:
 
-1. **Early phase** runs before user code imports — for things user code needs *at import time* (database/cache so models work, logger so app modules can `log.info`).
+1. **Early phase** runs before user code imports — for things user code needs _at import time_ (database/cache so models work, logger so app modules can `log.info`).
 2. **Late phase** runs after user code imports — for things that consume registrations user code just made (HTTP reads the router, socket reads HTTP's instance).
 
 If your connector is a self-contained service (queue client, scheduler), `Early` is correct. If it depends on app-level registrations, `Late`. Default is `Early` — don't change it without a reason.
@@ -161,11 +157,7 @@ The manager swallows errors from individual `shutdown()`s (logs and continues)
 ### Queue worker (depends on DB)
 
 ```ts title="src/connectors/queue-worker-connector.ts"
-import {
-  BaseConnector,
-  ConnectorLifecyclePhase,
-  type ConnectorName,
-} from "@warlock.js/core";
+import { BaseConnector, ConnectorLifecyclePhase, type ConnectorName } from "@warlock.js/core";
 import { startWorker, stopWorker } from "app/queue/services/worker.service";
 
 export class QueueWorkerConnector extends BaseConnector {
@@ -191,11 +183,7 @@ export class QueueWorkerConnector extends BaseConnector {
 ### Scheduler (Late — wants the router up first)
 
 ```ts
-import {
-  BaseConnector,
-  ConnectorLifecyclePhase,
-  type ConnectorName,
-} from "@warlock.js/core";
+import { BaseConnector, ConnectorLifecyclePhase, type ConnectorName } from "@warlock.js/core";
 
 export class SchedulerConnector extends BaseConnector {
   public readonly name: ConnectorName = "scheduler";
@@ -231,7 +219,7 @@ See the [Registering a connector](#registering-a-connector) section above for th
 - **`shutdown()` must be idempotent.** SIGINT can fire twice on Windows. The manager guards re-entry with its own flag, but individual connectors get called once per shutdown loop — guard with `if (!this.active) return`.
 - **Don't reach across connector boundaries in `start()`.** The manager's `start()` loop runs all `boot()`s first, then all `start()`s — wiring across connectors goes through the `container`, not through imports. Use `container.tryGet("http.server")` when the other connector is genuinely optional (e.g. socket falls back to its own raw server when HTTP isn't configured); use `container.get("http.server")` when its absence would be a bug — it throws a named `ContainerKeyMissingError` instead of handing back `undefined`.
 - **Production build still needs config registration.** Placing the connector under `src/connectors/<name>.ts` does not auto-register it. Put the same instance in `warlock.config.ts > connectors`; that array is what build-time contribution discovery and runtime boot share.
-- **`watchedFiles` is restart-trigger, not dependency.** It says "I want to restart when this file changes." It does *not* mean the framework reloads that file first — that's the file orchestrator's job.
+- **`watchedFiles` is restart-trigger, not dependency.** It says "I want to restart when this file changes." It does _not_ mean the framework reloads that file first — that's the file orchestrator's job.
 
 ## See also
 

package/skills/benchmark-code/SKILL.md

@@ -12,18 +12,21 @@ description: 'Wrap a function with `measure(name, fn, options?)` to time it and
 ```ts
 import { measure } from "@warlock.js/core";
 
+declare const db: { users: { findOne(query: { id: number }): Promise<{ id: number } | null> } }; // your data layer
+declare const id: number;
+
 const result = await measure("db.findUser", () => db.users.findOne({ id }));
 
 if (result.success) {
-  console.log(result.value);          // T
-  console.log(result.latency);        // ms
-  console.log(result.state);          // "excellent" | "good" | "poor"
+  console.log(result.value); // T
+  console.log(result.latency); // ms
+  console.log(result.state); // "excellent" | "good" | "poor"
 } else {
   console.error(result.error);
 }
 ```
 
-`measure()` always *returns* — it never re-throws. The return type is `BenchmarkSuccessResult<T> | BenchmarkErrorResult`, discriminated by `result.success`. The one exception: `shouldBenchmarkError` returning false re-throws (see below).
+`measure()` always _returns_ — it never re-throws. The return type is `BenchmarkSuccessResult<T> | BenchmarkErrorResult`, discriminated by `result.success`. The one exception: `shouldBenchmarkError` returning false re-throws (see below).
 
 ## `BenchmarkResult` — what you get back
 
@@ -89,7 +92,7 @@ await measure("http.outbound", () => fetch(url), {
 
 ## Selective error capture — `shouldBenchmarkError`
 
-Business errors (4xx, validation) are not infrastructure problems and shouldn't pollute your latency stats. Return `false` to *re-throw* the error without producing a benchmark result:
+Business errors (4xx, validation) are not infrastructure problems and shouldn't pollute your latency stats. Return `false` to _re-throw_ the error without producing a benchmark result:
 
 ```ts
 await measure("create-user", () => createUser(input), {
@@ -119,18 +122,19 @@ For high-volume operations where you want p50/p95/p99 rather than per-call hooks
 ```ts
 import { BenchmarkProfiler, ConsoleChannel, measure } from "@warlock.js/core";
 
+declare const db: { users: { findOne(query: { id: number }): Promise<{ id: number } | null> } }; // your data layer
+
 const profiler = new BenchmarkProfiler({
-  maxSamples: 1000,                  // ring buffer per operation name
-  channels: [new ConsoleChannel()],  // where stats go on flush()
-  flushEvery: 60_000,                // auto-flush every minute
+  maxSamples: 1000, // ring buffer per operation name
+  channels: [new ConsoleChannel()], // where stats go on flush()
+  flushEvery: 60_000, // auto-flush every minute
 });
 
 for (let i = 0; i < 5; i++) {
-  await measure(
-    "db.findUser",
-    () => db.users.findOne({ id: i }),
-    { profiler, latencyRange: { excellent: 50, poor: 300 } },
-  );
+  await measure("db.findUser", () => db.users.findOne({ id: i }), {
+    profiler,
+    latencyRange: { excellent: 50, poor: 300 },
+  });
 }
 
 const stats = profiler.stats("db.findUser");
@@ -146,6 +150,8 @@ Wire a profiler globally through `BenchmarkConfigurations.profiler` in `src/conf
 ```ts
 import type { BenchmarkChannel, BenchmarkStats } from "@warlock.js/core";
 
+declare const datadog: { gauge(metric: string, value: number): Promise<void> }; // your metrics client
+
 export class DatadogChannel implements BenchmarkChannel {
   public async onFlush(stats: Record<string, BenchmarkStats>): Promise<void> {
     for (const [name, operationStats] of Object.entries(stats)) {
@@ -164,9 +170,12 @@ When percentiles aren't enough — you need the actual failing inputs/errors for
 ```ts
 import { BenchmarkSnapshots, measure } from "@warlock.js/core";
 
+declare const stripe: { charge(payload: { amount: number }): Promise<{ id: string }> }; // your payment client
+declare const payload: { amount: number };
+
 const snapshots = new BenchmarkSnapshots({
   maxSnapshots: 100,
-  capture: "error",        // "error" (default, safe) | "value" | "all"
+  capture: "error", // "error" (default, safe) | "value" | "all"
 });
 
 await measure("payment.charge", () => stripe.charge(payload), { snapshotContainer: snapshots });
@@ -180,11 +189,7 @@ const failed = snapshots.getSnapshots("payment.charge");
 ## Globals via `src/config/benchmark.ts`
 
 ```ts title="src/config/benchmark.ts"
-import {
-  BenchmarkProfiler,
-  ConsoleChannel,
-  type BenchmarkConfigurations,
-} from "@warlock.js/core";
+import { BenchmarkProfiler, ConsoleChannel, type BenchmarkConfigurations } from "@warlock.js/core";
 
 const benchmarkConfig: BenchmarkConfigurations = {
   enabled: true,
@@ -235,18 +240,19 @@ const result = await measure(
 import { measure } from "@warlock.js/core";
 import { retry } from "@mongez/reinforcements";
 
-await measure("publish-event", () =>
-  retry(() => bus.publish(event), { attempts: 4, delay: 200 }),
-);
+declare const bus: { publish(event: unknown): Promise<void> }; // your event bus
+declare const event: { type: string };
+
+await measure("publish-event", () => retry(() => bus.publish(event), { attempts: 4, delay: 200 }));
 ```
 
-The `latency` is the *total* time including retries — useful for the SLO you actually care about. (`retry` moved to `@mongez/reinforcements`; `count` is now `attempts` — total tries.)
+The `latency` is the _total_ time including retries — useful for the SLO you actually care about. (`retry` moved to `@mongez/reinforcements`; `count` is now `attempts` — total tries.)
 
 ## Gotchas
 
 - **Name collisions aggregate.** Two calls to `measure("foo", …)` share one profiler bucket. Make `name` specific (`db.findUser`, not `db.query`) so percentiles mean something.
 - **`measure()` doesn't propagate AbortSignal.** If `fn` is cancellable, plumb that through yourself — the wrapper only times.
-- **Don't `measure()` synchronous trivia.** A `Math.round` call isn't worth a microsecond of overhead. Reserve for things that *can* be slow.
+- **Don't `measure()` synchronous trivia.** A `Math.round` call isn't worth a microsecond of overhead. Reserve for things that _can_ be slow.
 - **Snapshots with `"value"` retain references.** If `value` holds a request stream or a large buffer, you've kept it in memory until eviction.
 - **`shouldBenchmarkError` re-throws.** Make sure the caller is ready for that, or set it conservatively (`true` by default).
 

package/skills/build-restful/SKILL.md

@@ -133,15 +133,15 @@ router.restfulResource("/users", new UsersRestful());
 
 This registers:
 
-| Path        | Verb     | Method        |
-| ----------- | -------- | ------------- |
-| `/users`    | `GET`    | `list()`      |
-| `/users/:id`| `GET`    | `get()`       |
-| `/users`    | `POST`   | `create()`    |
-| `/users/:id`| `PUT`    | `update()`    |
-| `/users/:id`| `PATCH`  | `patch()`     |
-| `/users/:id`| `DELETE` | `delete()`    |
-| `/users`    | `DELETE` | `bulkDelete()`|
+| Path         | Verb     | Method         |
+| ------------ | -------- | -------------- |
+| `/users`     | `GET`    | `list()`       |
+| `/users/:id` | `GET`    | `get()`        |
+| `/users`     | `POST`   | `create()`     |
+| `/users/:id` | `PUT`    | `update()`     |
+| `/users/:id` | `PATCH`  | `patch()`      |
+| `/users/:id` | `DELETE` | `delete()`     |
+| `/users`     | `DELETE` | `bulkDelete()` |
 
 `bulkDelete` expects an array of ids in the `id` field; it 400s otherwise. All actions except `bulkDelete` only register when the corresponding method is defined on the class — `Restful` provides them all by default.
 
@@ -176,11 +176,11 @@ router.restfulResource("/users", new UsersRestful(), {
 
 Override any of these `protected async` methods:
 
-| Hook                            | When                                      |
-| ------------------------------- | ----------------------------------------- |
-| `beforeCreate(request, response, model)` | New model instance, before `create`       |
-| `onCreate(request, response, record)`    | After successful `create`                 |
-| `beforeUpdate(request, response, record, old?)` | Before `update`                    |
+| Hook                                            | When                                |
+| ----------------------------------------------- | ----------------------------------- |
+| `beforeCreate(request, response, model)`        | New model instance, before `create` |
+| `onCreate(request, response, record)`           | After successful `create`           |
+| `beforeUpdate(request, response, record, old?)` | Before `update`                     |
 | `onUpdate(request, response, record, old)`      | After successful `update`           |
 | `beforePatch(request, response, record, old?)`  | Before `patch`                      |
 | `onPatch(request, response, record, old)`       | After successful `patch`            |

package/skills/build-url/SKILL.md

@@ -14,11 +14,11 @@ Use URL helpers whenever you need to render a string that goes into a browser, a
 ```ts
 import { url, publicUrl, assetsUrl, uploadsUrl } from "@warlock.js/core";
 
-url();                       // → "http://localhost:3000"
-url("/health");              // → "http://localhost:3000/health"
+url(); // → "http://localhost:3000"
+url("/health"); // → "http://localhost:3000/health"
 
-publicUrl("favicon.ico");    // → "http://localhost:3000/public/favicon.ico"
-assetsUrl("logo.png");       // → "http://localhost:3000/public/assets/logo.png"
+publicUrl("favicon.ico"); // → "http://localhost:3000/public/favicon.ico"
+assetsUrl("logo.png"); // → "http://localhost:3000/public/assets/logo.png"
 uploadsUrl("avatars/42.png"); // → "http://localhost:3000/uploads/avatars/42.png"
 ```
 
@@ -54,13 +54,13 @@ setBaseUrl("https://cdn.example.com");
 
 ## Full inventory
 
-| Helper                | Resolves to                              | Use for                                     |
-| --------------------- | ---------------------------------------- | ------------------------------------------- |
-| `url(path?)`          | `<baseUrl>/<path>`                       | Arbitrary absolute URL on the same host.    |
-| `publicUrl(path?)`    | `<baseUrl>/public/<path>`                | Files served out of the `public/` folder.   |
-| `assetsUrl(path?)`    | `<baseUrl>/public/assets/<path>`         | Assets inside `public/assets/`.             |
-| `uploadsUrl(path?)`   | `<baseUrl>/uploads/<path>`               | User-uploaded files served over HTTP.       |
-| `setBaseUrl(url)`     | (sets the anchor for all of the above)   | Override at runtime — rarely needed.        |
+| Helper              | Resolves to                            | Use for                                   |
+| ------------------- | -------------------------------------- | ----------------------------------------- |
+| `url(path?)`        | `<baseUrl>/<path>`                     | Arbitrary absolute URL on the same host.  |
+| `publicUrl(path?)`  | `<baseUrl>/public/<path>`              | Files served out of the `public/` folder. |
+| `assetsUrl(path?)`  | `<baseUrl>/public/assets/<path>`       | Assets inside `public/assets/`.           |
+| `uploadsUrl(path?)` | `<baseUrl>/uploads/<path>`             | User-uploaded files served over HTTP.     |
+| `setBaseUrl(url)`   | (sets the anchor for all of the above) | Override at runtime — rarely needed.      |
 
 `assetsUrl` is just `publicUrl` with `assets/` prepended — they share the same `/public/` mount point.
 
@@ -70,12 +70,12 @@ setBaseUrl("https://cdn.example.com");
 
 The most common confusion. They look related but resolve completely differently:
 
-| Goal                                          | Helper            | Returns                                     |
-| --------------------------------------------- | ----------------- | ------------------------------------------- |
-| **Read** a file from the filesystem           | `uploadsPath(...)` | `<cwd>/storage/uploads/<path>` (filesystem) |
-| **Render** an `<img src>` for the same file   | `uploadsUrl(...)`  | `<baseUrl>/uploads/<path>` (HTTP URL)       |
-| **Write** to public folder                    | `publicPath(...)`  | `<cwd>/public/<path>` (filesystem)          |
-| **Embed** an asset URL in a response          | `publicUrl(...)`   | `<baseUrl>/public/<path>` (HTTP URL)        |
+| Goal                                        | Helper             | Returns                                     |
+| ------------------------------------------- | ------------------ | ------------------------------------------- |
+| **Read** a file from the filesystem         | `uploadsPath(...)` | `<cwd>/storage/uploads/<path>` (filesystem) |
+| **Render** an `<img src>` for the same file | `uploadsUrl(...)`  | `<baseUrl>/uploads/<path>` (HTTP URL)       |
+| **Write** to public folder                  | `publicPath(...)`  | `<cwd>/public/<path>` (filesystem)          |
+| **Embed** an asset URL in a response        | `publicUrl(...)`   | `<baseUrl>/public/<path>` (HTTP URL)        |
 
 Pick by the consumer:
 
@@ -144,7 +144,7 @@ await sendWebhook({
   url: vendor.callback_url,
   payload: {
     order_id: order.id,
-    receipt_url: url(`/orders/${order.id}/receipt`),  // → "https://api.example.com/orders/42/receipt"
+    receipt_url: url(`/orders/${order.id}/receipt`), // → "https://api.example.com/orders/42/receipt"
   },
 });
 ```

package/skills/configure-app/SKILL.md

@@ -70,6 +70,24 @@ const httpConfigurations: HttpConfigurations = {
 export default httpConfigurations;
 ```
 
+### `serverOptions` — native Fastify/Node server options (5.30.0)
+
+`http.serverOptions` is passed to Fastify when the server is created, and its
+`http` key goes on to Node's `http.createServer()`. It is typed as
+`HttpServerOptions`. The request header limit, for example, is
+`serverOptions.http.maxHeaderSize` (Node's default is 16KB); a top-level
+`maxHeaderSize` is not a Fastify option and is ignored:
+
+```ts
+serverOptions: {
+  http: { maxHeaderSize: 32 * 1024 },
+},
+```
+
+Framework-owned settings (`trustProxy`, `bodyLimit`,
+`gracefulShutdown.forceCloseConnections`) have their own `http.*` keys;
+setting them in `serverOptions` as well overrides those keys.
+
 ### `csp` — Content-Security-Policy (5.12.0)
 
 Opt-in (`enabled: true`) `Content-Security-Policy` header, built per-request
@@ -97,16 +115,16 @@ same nonce reaches the page's `<script>` tags.
 
 ## Which layer holds what
 
-| Setting                                                | Layer                          |
-| ------------------------------------------------------ | ------------------------------ |
-| Build/bundler options (minify, sourcemap, outFile)     | `warlock.config.ts > build`    |
-| Dev server (HMR scope, health checkers, typings)       | `warlock.config.ts > devServer`|
-| Package migrations (external `@warlock.js/*` packages) | `warlock.config.ts > database` |
-| CLI commands (registered via `warlock <cmd>`)          | `warlock.config.ts > cli`      |
-| HTTP server tuning per env (port, host, retry)         | `warlock.config.ts > server`   |
-| HTTP runtime (CORS, cookies, rate limits, upload size) | `src/config/http.ts`           |
-| App identity (name, baseUrl, publicUrl, timezone, locales) | `src/config/app.ts`        |
-| Subsystem configs (auth, mail, storage, cache, ai, …)  | `src/config/<name>.ts`         |
+| Setting                                                    | Layer                           |
+| ---------------------------------------------------------- | ------------------------------- |
+| Build/bundler options (minify, sourcemap, outFile)         | `warlock.config.ts > build`     |
+| Dev server (HMR scope, health checkers, typings)           | `warlock.config.ts > devServer` |
+| Package migrations (external `@warlock.js/*` packages)     | `warlock.config.ts > database`  |
+| CLI commands (registered via `warlock <cmd>`)              | `warlock.config.ts > cli`       |
+| HTTP server tuning per env (port, host, retry)             | `warlock.config.ts > server`    |
+| HTTP runtime (CORS, cookies, rate limits, upload size)     | `src/config/http.ts`            |
+| App identity (name, baseUrl, publicUrl, timezone, locales) | `src/config/app.ts`             |
+| Subsystem configs (auth, mail, storage, cache, ai, …)      | `src/config/<name>.ts`          |
 
 Heuristic: if the setting changes how the framework **boots, builds, or scaffolds**, it goes in `warlock.config.ts`. If it changes how a **subsystem behaves at runtime**, it goes in `src/config/`.
 
@@ -121,10 +139,10 @@ Heuristic: if the setting changes how the framework **boots, builds, or scaffold
 ```ts
 import { env } from "@warlock.js/core";
 
-env("HTTP_PORT", 3000);             // number
-env("CACHE_LOGGING", false);        // boolean
+env("HTTP_PORT", 3000); // number
+env("CACHE_LOGGING", false); // boolean
 env("BASE_URL", "http://localhost:3000"); // string
-env("REDIS_URL");                   // undefined if unset
+env("REDIS_URL"); // undefined if unset
 ```
 
 `env` is re-exported from `@warlock.js/core` (sourced from `@mongez/dotenv`). Use this — not `process.env.X` — so callers consistently get coerced values.
@@ -160,6 +178,35 @@ The `ConfigRegistry` interface is augmented by generated typings — once you ad
 
 That's the contract. Filename → config key. No registration, no manifest, no side effects.
 
+### Validate a config file at boot: `configSchema`
+
+Export a `configSchema` next to the default export. The value is validated
+before it is registered (dev boot, each hot reload, production start); every
+problem in every config file is reported in one `InvalidConfigError`, naming
+the env variable to set. Values are never printed; an invalid config never
+reaches its special handler; a bad hot reload keeps the previous value.
+
+```ts
+// src/config/payments.ts
+import { defineConfigSchema, env, type ConfigOf } from "@warlock.js/core";
+import { v } from "@warlock.js/seal";
+
+export const configSchema = defineConfigSchema(
+  v.object({ apiKey: v.string(), webhookSecret: v.string() }),
+  { env: { apiKey: "PAYMENTS_API_KEY", webhookSecret: "PAYMENTS_WEBHOOK_SECRET" } },
+);
+
+const paymentsConfig: ConfigOf<typeof configSchema> = {
+  apiKey: env("PAYMENTS_API_KEY"),
+  webhookSecret: env("PAYMENTS_WEBHOOK_SECRET"),
+};
+
+export default paymentsConfig;
+```
+
+Nested keys use dotted paths in the `env` map (`"smtp.password"`). Files
+without a `configSchema` load as before.
+
 ## Special handlers
 
 Some subsystems need to do extra work when their config loads (e.g. set the active locale, register a driver). Those have a special handler attached internally — for the most part you don't see them. The takeaway: changing a config file at dev time fires the handler again automatically.
@@ -225,12 +272,16 @@ Same shape — TS validates the union; runtime picks the `default` key.
 
 ## Multi-server settings (5.20.0)
 
-- `http.rateLimit` — `@fastify/rate-limit` options (`redis`, `nameSpace`, ...); `enabled: false` disables.
+- `http.rateLimit` — `@fastify/rate-limit` options (`nameSpace`, ...); `store: "cache"` counts in `@warlock.js/cache` so every server shares the limit (per-route `middleware.rateLimit()` follows it; `skipOnError` defaults to `true`, so a cache outage fails open; the `null` and `file` cache drivers are refused); `redis` needs an ioredis client; `enabled: false` disables. Static files (public folder, `router.directory()` mounts, `router.file()` routes, web build assets) are exempt unless `staticFiles: true`.
 - `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 }`.
 
+`http.errorMapper(error, request)` maps errors that are not an `HttpError` to `{ status, message?, payload? }` (return `undefined` to keep the default opaque `500`). A mapped 5xx keeps the opaque message unless the mapper sets one.
+
+`http.logging` controls what request log entries carry: `{ body?: boolean, query?: boolean, redactQueryParams?: string[] }` (body/query default `true`). A route's `logging` option overrides it — use `logging: { body: false, query: false }` on routes that accept secrets or arbitrary text. Entries carry `request.toLogSnapshot()`, never the `Request` object, with credential query values masked in the URL.
+
 ## Per-env knobs
 
 For one-off switches gated on environment, the canonical pattern is `Application.isProduction` (also `isDevelopment`, `isTest`):
@@ -306,3 +357,67 @@ Internal `@warlock.js/*` packages read from `config.get("<name>")` the same way
 - The `pick-cache-driver` topic of the `warlock-js-cache` skill — picking and registering a cache driver in `src/config/cache.ts`.
 - The `send-mail` topic — the `src/config/mail.ts` shape.
 - The `store-file` topic — the `src/config/storage.ts` shape.
+
+## Hide input for a family of URLs
+
+```ts
+import type { HttpConfigurations } from "@warlock.js/core";
+
+export default {
+  logging: {
+    private: [
+      { path: "/api/private", body: false, query: false },
+      { path: /^\/credentials(?:\/|$)/, body: false },
+    ],
+  },
+} satisfies HttpConfigurations;
+```
+
+String paths match a prefix at a segment boundary. Both string and regex rules
+are checked against several pathname candidates: the raw path, the decoded path,
+and the decoded path with dot segments resolved, each with repeated and trailing
+slashes collapsed. Any match suppresses input, so normalization never narrows a
+raw-path match. The matched route pattern is checked too, and the rules apply
+even when no route matches. Matching rules combine and only remove input; a
+route cannot re-enable fields they suppress. `query: false` also removes the
+logged URL's query string.
+
+With private policies configured, a request path that does not decode withholds
+both body and query. The same holds for the matched route pattern: a route
+pattern containing a `%` that does not decode (such as `/files/100%`) withholds
+body and query on every request to that route. An undecodable configured prefix
+suppresses its selected fields for all requests. Rules assume case-sensitive
+routing defaults; with case-insensitive routing, use a regex with `i` and
+include any custom semicolon delimiters in the matcher. The URL's original path
+spelling is retained in the snapshot.
+
+The rules are prepared once per `private` array. To change them at runtime, set
+a new array (`config.set("http.logging.private", [...])`) rather than editing the
+existing one in place.
+
+When upgrading from 5.29, update redaction censors that inspect `context.request`:
+it is a `RequestLogSnapshot`, with `url` and `route` (a string), rather than a
+Request instance with `baseRequest.url` or `route.path`. Custom log calls can use
+`request.toLogSnapshot()` to apply these same policies.
+
+## Map domain errors at the HTTP edge
+
+```ts title="src/config/http.ts"
+import type { HttpConfigurations } from "@warlock.js/core";
+
+class InventoryConflict extends Error {}
+
+export default {
+  errorMapper(error) {
+    if (error instanceof InventoryConflict) {
+      return { status: 409, message: error.message };
+    }
+    return undefined;
+  },
+  logging: { body: true, query: true, redactQueryParams: ["token"] },
+} satisfies HttpConfigurations;
+```
+
+Keep the domain error class in an app module imported by both the service and
+this config. Return `undefined` for errors you do not recognize; a mapped 5xx
+is opaque unless the mapper explicitly chooses a public message.

package/skills/create-controller/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: create-controller
-description: 'Author HTTP controllers in @warlock.js/core — RequestHandler signature, validated input via seal schemas, response helpers, attaching metadata. Controllers are thin functions; business logic moves to services or use-cases. Triggers: `RequestHandler`, `Request<TSchema>`, `GuardedRequestHandler`, `request.validated`, `request.input`, `controller.validation`, `controller.responseSchema`, `response.success`, `response.successCreate`; "write a controller", "attach a schema to a handler", "thin controller pattern", "guarded request type", "type the API response"; typical import `import { type RequestHandler } from "@warlock.js/core"`. Skip: response helper menu — the `send-response` topic; schema authoring — the `validate-input` topic; URL wiring — the `register-route` topic; competing patterns: `express` middleware functions, `@nestjs/common` `@Controller`/`@Get` decorators.'
+description: 'Author HTTP controllers in @warlock.js/core — RequestHandler signature, validated input via seal schemas, response helpers, attaching metadata. Controllers are thin functions; business logic moves to services or use-cases. Triggers: `RequestHandler`, `Request<TSchema>`, `GuardedRequestHandler`, `request.validated`, `request.signal`, `request.input`, `controller.validation`, `controller.responseSchema`, `response.success`, `response.successCreate`; "write a controller", "attach a schema to a handler", "thin controller pattern", "guarded request type", "type the API response"; typical import `import { type RequestHandler } from "@warlock.js/core"`. Skip: response helper menu — the `send-response` topic; schema authoring — the `validate-input` topic; URL wiring — the `register-route` topic; competing patterns: `express` middleware functions, `@nestjs/common` `@Controller`/`@Get` decorators.'
 ---
 
 # Warlock — create a controller
@@ -45,16 +45,20 @@ Prefer `request.validated()` once a schema is attached — it's typed.
 
 `request.input()` / `.all()` / `.validated()` read the same way regardless of how the body arrived — every content type below feeds the same parsed bag:
 
-| Content type                         | Parsed by                       | Notes                                                                |
-| ------------------------------------ | -------------------------------- | --------------------------------------------------------------------- |
-| `application/json`                   | Fastify (built-in)               | objects/arrays parsed as-is                                           |
-| `multipart/form-data`                | `@fastify/multipart`             | fields + files; see the `upload-file` topic          |
-| `application/x-www-form-urlencoded`  | Warlock's own content-type parser (`http/parse-urlencoded-body.ts`) | plain HTML forms, OAuth `form_post` callbacks (e.g. Apple Sign in)    |
+| Content type                        | Parsed by                                                           | Notes                                                              |
+| ----------------------------------- | ------------------------------------------------------------------- | ------------------------------------------------------------------ |
+| `application/json`                  | Fastify (built-in)                                                  | objects/arrays parsed as-is                                        |
+| `multipart/form-data`               | `@fastify/multipart`                                                | fields + files; see the `upload-file` topic                        |
+| `application/x-www-form-urlencoded` | Warlock's own content-type parser (`http/parse-urlencoded-body.ts`) | plain HTML forms, OAuth `form_post` callbacks (e.g. Apple Sign in) |
 
 For urlencoded bodies: fields decode via `URLSearchParams`. A key sent more than once (`tag=a&tag=b`) becomes an array (`request.input("tag")` → `["a", "b"]`); every other key is a plain string. Bracket-notation keys (`a[b]=1`) are **not** expanded by the urlencoded parser itself — nesting only happens through the same shared bracket-key logic every body type already goes through, so it behaves exactly like a JSON or query-string key of that shape, no differently than today.
 
 All three content types are held to the same `http.bodyLimit` — an over-limit urlencoded body is rejected with the same `413` a JSON body would get.
 
+### Stopping work when the client disconnects
+
+`request.signal` is an `AbortSignal` that aborts when the client disconnects before the response finished (never on normal completion, never because the body finished reading). Pass it to long-running services, composed with a deadline when you need one: `AbortSignal.any([request.signal, AbortSignal.timeout(30_000)])`. Read it per request; never cache it on a shared service.
+
 ## Returning output
 
 Pick the helper that matches the outcome. Full surface in the `send-response` topic. Quick map:
@@ -159,12 +163,12 @@ loginController.responseSchema = {
 
 A body is an object whose values are one of:
 
-| Value                                           | Meaning                                     |
-| ----------------------------------------------- | ------------------------------------------- |
-| a cast string, with the resource suffixes       | `"string"`, `"number?"`, `"string[]"`, `"date[]?"` (`?` is `T \| null`, key always present) |
-| a resource                                      | one `ResourceOutput` object                 |
-| `[Resource]`                                    | an array of that resource                   |
-| a nested plain object of any of the above       | recursed                                    |
+| Value                                     | Meaning                                                                                     |
+| ----------------------------------------- | ------------------------------------------------------------------------------------------- |
+| a cast string, with the resource suffixes | `"string"`, `"number?"`, `"string[]"`, `"date[]?"` (`?` is `T \| null`, key always present) |
+| a resource                                | one `ResourceOutput` object                                                                 |
+| `[Resource]`                              | an array of that resource                                                                   |
+| a nested plain object of any of the above | recursed                                                                                    |
 
 The output types follow the same rules as `defineResource` (`ResponseBodyOutput<B>` and `ResponseSchemaOutput<S>` are exported if you need the type of a body or of the whole schema).
 
@@ -276,3 +280,16 @@ No `if (!product)` branch in the controller. The error class carries the HTTP se
 - The `register-route` topic — wiring a controller to a URL.
 - The `send-response` topic — full Response helper surface.
 - The `warlock-conventions` topic — controller-service-repository layering.
+
+## Complete cancellation example
+
+```ts title="src/app/catalog/controllers/remote-catalog.controller.ts"
+import type { RequestHandler } from "@warlock.js/core";
+
+export const remoteCatalogController: RequestHandler = async ({ request, response }) => {
+  const signal = AbortSignal.any([request.signal, AbortSignal.timeout(30_000)]);
+  const upstream = await fetch("https://example.com/catalog.json", { signal });
+  if (!upstream.ok) return response.badRequest({ error: "Catalog unavailable" });
+  return response.success({ catalog: await upstream.json() });
+};
+```