@warlock.js/core 5.29.0 → 5.30.0

package/llms-full.txt

@@ -1038,6 +1038,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
@@ -1193,12 +1211,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.
 - `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`):
@@ -1335,6 +1357,10 @@ For urlencoded bodies: fields decode via `URLSearchParams`. A key sent more than
 
 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:
@@ -2803,6 +2829,8 @@ export default httpConfigurations;
 
 `forceCloseConnections`: `"idle"` (default) closes idle keep-alive connections and lets active requests finish; `true` force-closes everything immediately; `false` waits for every connection.
 
+Under `"idle"`, a request that is still running when shutdown begins answers with `Connection: close`, and its keep-alive connection is closed as soon as the response finishes, so a browser's kept-alive connection does not hold the drain open until the timeout. Responses that had already sent their headers (streams, SSE) are closed when they end. Active responses are never cut short.
+
 ## The zero-downtime deploy flow
 
 ```
@@ -3227,6 +3255,16 @@ router.prefix("/auth", () => {
 router.get(["/health", "/healthz"], healthController);
 ```
 
+### Sensitive routes: keep input out of the logs
+
+```ts
+router.post("/accounts/credentials", accountsController.store, {
+  logging: { body: false, query: false },
+});
+```
+
+Request log entries otherwise include the body as received (before validation), so rejected fields would be logged too.
+
 ## Gotchas
 
 - **Never import `routes.ts`.** The framework auto-loads it. Importing causes a double-registration error.
@@ -4216,14 +4254,21 @@ pnpm 10+ will not run a dependency's install script unless the app names it. esb
 [ERR_PNPM_IGNORED_BUILDS] Ignored build scripts: esbuild@0.27.7
 ```
 
-Fix it once in the app's `pnpm-workspace.yaml`:
+Where the approval goes depends on the pnpm version (measured with real installs):
+
+| pnpm             | Approve esbuild in                                                           |
+| ---------------- | ---------------------------------------------------------------------------- |
+| 10.26+, 11, 12   | `pnpm-workspace.yaml`: `allowBuilds:` / `  esbuild: true`                    |
+| 10.5 – 10.25     | `pnpm-workspace.yaml`: `onlyBuiltDependencies:` / `  - esbuild`              |
+| 7 – 9, 10.0–10.4 | `package.json`: `"pnpm": { "onlyBuiltDependencies": ["esbuild"] }`, and no `pnpm-workspace.yaml` |
 
 ```yaml
+# pnpm 10.26 and later
 allowBuilds:
   esbuild: true
 ```
 
-Note pnpm reads this from `pnpm-workspace.yaml`, **not** from `package.json`'s `pnpm` field — pnpm 11 warns that the field is ignored and then carries on, so settings left there fail silently.
+pnpm 11 and 12 ignore `package.json`'s `pnpm` field and fail the install when the workspace file has only `onlyBuiltDependencies`, so keep `allowBuilds` there (listing both keys is fine). pnpm before 10.5 rejects a `pnpm-workspace.yaml` without a `packages:` field (`packages field missing or empty`), and adding `packages: ["."]` makes every later dependency add fail with `ERR_PNPM_ADDING_TO_ROOT` — so on those versions use the `package.json` field instead. `create-warlock` 5.30.0 checks the pnpm version and writes the right one, and `warlock add image` follows the same rule when it approves `sharp`.
 
 `warlock dev` checks for esbuild's native binary before starting (as `warlock build` already did) and fails fast with `EsbuildBinaryMissingError`, naming the same fix, instead of surfacing an opaque low-level error later from inside the bundler.
 
@@ -4934,7 +4979,7 @@ stream.send("second chunk\n");
 stream.end();
 ```
 
-`response.stream(contentType?)` returns a controller with `.send(chunk)`, `.render(reactNode)`, `.end()`, and an `.ended` getter. Use for large dynamic payloads where buffering would blow memory. Calling `.send()` after `.end()` throws.
+`response.stream(contentType?, { retainChunks? })` returns a controller with `.send(chunk)`, `.render(reactNode)`, `.end()`, and an `.ended` getter, plus `await .write(chunk)` / `await .drain()` (wait for a slow client; `false` once it left), `.backpressured`, `.signal` (aborted on client disconnect) and `.onDisconnect(fn)`. Use for large dynamic payloads where buffering would blow memory; loop on `await stream.write(chunk)` when the producer can outrun the client. Calling `.send()` after `.end()` throws; after a client disconnect it is a silent no-op. Written chunks are not kept on `response.body` unless `retainChunks` asks for a tail.
 
 ## Throwing HTTP errors
 
@@ -4958,6 +5003,12 @@ throw new ForbiddenError("permission.denied", { resource: "product", id });
 throw new ConflictError("user.duplicateEmail");
 ```
 
+A program that must not load the framework (a standalone helper, a worker
+bundle) imports the same classes from `@warlock.js/core/errors`, which pulls in
+nothing else. Domain errors that cannot extend `HttpError` get a status at the
+edge through `http.errorMapper` (`(error, request) => ({ status, message?, payload? }) | undefined`);
+anything unmapped and not an `HttpError` answers an opaque `500`.
+
 Each class takes `(message, payload?)`. The framework keeps the optional
 detail nested under `payload`:
 
@@ -4996,7 +5047,9 @@ sse.comment("keep-alive"); // invisible to the client, prevents timeout
 sse.end();
 ```
 
-`response.sse()` returns a controller with `send(event, data, id?)`, `comment(text)`, `end()`, `onDisconnect(handler)`, and an `.ended` getter. The `send` signature is positional — `event` name first, then the `data` payload (JSON-stringified for you), then an optional event `id`. After the client disconnects, `send`/`comment` become silent no-ops and any `onDisconnect` handlers fire — register cleanup there:
+For streams that can outrun the client (terminals, log tails, big feeds), `await sse.write(event, data)` instead of `send()`: it waits until the client has caught up and resolves `false` once the client is gone. `sse.drain()` waits without sending, `sse.backpressured` reports a backed-up transport, and `sse.signal` aborts on disconnect. Sent events are not kept on `response.body`; `response.sse({ retainEvents: n })` keeps the last `n` for logging/tests (default 0).
+
+`response.sse()` returns a controller with `send(event, data, id?)`, `comment(text)`, `end()`, `onDisconnect(handler)`, and an `.ended` getter. The `send` signature is positional — `event` name first, then the `data` payload (JSON-stringified for you), then an optional event `id`. Line breaks (and NUL) in the event name and `id` are removed, so values built from user input cannot inject SSE fields. After the client disconnects, `send`/`comment` become silent no-ops and any `onDisconnect` handlers fire (a handler that throws is logged; the rest still run) — register cleanup there:
 
 ```ts
 const sse = response.sse();
@@ -5331,7 +5384,11 @@ console.log(r2File.url);
 console.log(localFile.url);
 ```
 
-`storage.use(name)` returns a `ScopedStorage` with the same surface as `storage`. To change the default permanently, call `storage.setDefault(name)` — but you almost always want per-call scoping for clarity.
+`storage.use(name)` returns a `ScopedStorage` with the same surface as `storage`, directory operations included (`storage.use("private").deleteDirectory(dir)` type-checks; no cast). To change the default permanently, call `storage.setDefault(name)` — but you almost always want per-call scoping for clarity.
+
+## Cached image variants follow their source
+
+On a local disk, `delete`, `deleteMany`, `move` and `deleteDirectory` (for every file under it) also remove the file's cached image derivatives (the `?variant=` renders of `uploadedFileController`). For a file removed some other way, call `purgeImageVariants(path, { disk? })`; with no path it clears the disk's whole derivative cache. Serve another local disk's files and variants with `createUploadedFileController({ disk: "private" })`, or call `resolveImageVariant({ disk, path, variant, format? })` from your own authenticated route. A configured `uploads.images.cacheDirectory` is shared by every disk: never put it inside `public/` (Warlock warns once if you do).
 
 ## `StorageFile` — the OOP handle
 
@@ -7463,7 +7520,7 @@ Each is documented inline (JSDoc + `@example`) — read the file under `@warlock
 - **Rate limit** caps **requests per time window** — 5 logins/minute per IP. Use for abuse prevention, cost-control on cheap-but-spammable endpoints.
 - **Concurrency limit** caps **in-flight requests at any instant** — 3 simultaneous report generations. Use for expensive endpoints where parallel calls would overload the worker (CPU-bound, large memory, slow third-party).
 
-Both counters are **process-local**. With N replicas the effective cap is N × value. For globally-shared rate limits, configure `@fastify/rate-limit` with a Redis store via `http.rateLimit` instead.
+Both counters are **process-local** by default. With N replicas the effective cap is N × value. `rateLimit` can count in `@warlock.js/cache` instead: `store: "cache"` on the limiter, or `http.rateLimit.store: "cache"` for every limiter (give conditionally created limiters a `name`). It needs a counting driver (`redis`, `pg`, or memory for one process): `null` and `file` are refused, and a cache outage fails open with the error logged at most once a minute. The concurrency cap has no shared mode.
 
 ```ts
 import { middleware } from "@warlock.js/core";
@@ -7504,7 +7561,7 @@ Server errors (5xx) are not cached — clients can retry past a 5xx. 4xx respons
 
 ## Rate limit across servers
 
-`http.rateLimit` passes `@fastify/rate-limit` options through — set `redis` for a store shared by all servers; `enabled: false` turns the global limiter off. The per-route `middleware.rateLimit()` counters stay in-process.
+Set `http.rateLimit.store: "cache"` to count in the configured `@warlock.js/cache` driver, shared by every server on a Redis or Postgres cache; the per-route `middleware.rateLimit()` follows it. `http.rateLimit` also passes `@fastify/rate-limit` options through (its own `redis` option needs an ioredis client, not the cache's node-redis one); `enabled: false` turns the global limiter off.
 
 ## `maxBodySize` vs the global `http.bodyLimit`
 
@@ -8699,7 +8756,7 @@ const uploadAvatarSchema = v.object({
 });
 ```
 
-Full file chain: `.image()`, `.accept(extensions)`, `.mimeType(types)`, `.pdf()`, `.excel()`, `.word()`, `.minSize(n)`, `.maxSize(n)`, `.minWidth(px)`, `.maxWidth(px)`, `.minHeight(px)`, `.maxHeight(px)`. See the `upload-file` topic for the full upload flow.
+Full file chain: `.image()`, `.accept(extensions)`, `.mimeType(types)`, `.pdf()`, `.excel()`, `.word()`, `.minSize(n)`, `.maxSize(n)`, `.minWidth(px)`, `.maxWidth(px)`, `.minHeight(px)`, `.maxHeight(px)`. Every rule returns `this`, so the field's output type stays `UploadedFile` through the chain; `.saveTo(dir)` switches it to `string` (the saved path). See the `upload-file` topic for the full upload flow.
 
 ### Optional file field
 

package/package.json

@@ -25,12 +25,12 @@
     "@mongez/slug": "^1.0.7",
     "@mongez/supportive-is": "^3.0.0",
     "@mongez/time-wizard": "^1.0.6",
-    "@warlock.js/cache": "5.29.0",
-    "@warlock.js/cascade": "5.29.0",
-    "@warlock.js/context": "5.29.0",
-    "@warlock.js/fs": "5.29.0",
-    "@warlock.js/logger": "5.29.0",
-    "@warlock.js/seal": "5.29.0",
+    "@warlock.js/cache": "5.30.0",
+    "@warlock.js/cascade": "5.30.0",
+    "@warlock.js/context": "5.30.0",
+    "@warlock.js/fs": "5.30.0",
+    "@warlock.js/logger": "5.30.0",
+    "@warlock.js/seal": "5.30.0",
     "bcryptjs": "^3.0.3",
     "chokidar": "^5.0.0",
     "dayjs": "^1.11.19",
@@ -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.29.0",
-    "@warlock.js/ai": "5.29.0",
-    "@warlock.js/herald": "5.29.0",
-    "@warlock.js/notifications": "5.29.0",
-    "@warlock.js/devtools": "5.29.0",
+    "@warlock.js/access": "5.30.0",
+    "@warlock.js/ai": "5.30.0",
+    "@warlock.js/herald": "5.30.0",
+    "@warlock.js/notifications": "5.30.0",
+    "@warlock.js/devtools": "5.30.0",
     "nodemailer": "^8.0.5",
     "react": "^19.2.3",
     "react-dom": "^19.2.3",
@@ -112,7 +112,8 @@
   },
   "repository": {
     "type": "git",
-    "url": "https://github.com/warlockjs/framework"
+    "url": "git+https://github.com/warlockjs/framework.git",
+    "directory": "packages/core"
   },
   "keywords": [
     "nodejs",
@@ -127,7 +128,7 @@
   ],
   "author": "hassanzohdy",
   "license": "MIT",
-  "version": "5.29.0",
+  "version": "5.30.0",
   "type": "module",
   "main": "./esm/index.mjs",
   "module": "./esm/index.mjs",
@@ -157,6 +158,12 @@
         "default": "./esm/vite/index.mjs"
       }
     },
+    "./errors": {
+      "import": {
+        "types": "./esm/errors/index.d.mts",
+        "default": "./esm/errors/index.mjs"
+      }
+    },
     "./production/route-registration-child": {
       "import": {
         "types": "./esm/production/route-registration-child.d.mts",

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
@@ -225,12 +243,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.
 - `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`):

package/skills/create-controller/SKILL.md

@@ -55,6 +55,10 @@ For urlencoded bodies: fields decode via `URLSearchParams`. A key sent more than
 
 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:

package/skills/health-checks/SKILL.md

@@ -92,6 +92,8 @@ export default httpConfigurations;
 
 `forceCloseConnections`: `"idle"` (default) closes idle keep-alive connections and lets active requests finish; `true` force-closes everything immediately; `false` waits for every connection.
 
+Under `"idle"`, a request that is still running when shutdown begins answers with `Connection: close`, and its keep-alive connection is closed as soon as the response finishes, so a browser's kept-alive connection does not hold the drain open until the timeout. Responses that had already sent their headers (streams, SSE) are closed when they end. Active responses are never cut short.
+
 ## The zero-downtime deploy flow
 
 ```

package/skills/register-route/SKILL.md

@@ -158,6 +158,16 @@ router.prefix("/auth", () => {
 router.get(["/health", "/healthz"], healthController);
 ```
 
+### Sensitive routes: keep input out of the logs
+
+```ts
+router.post("/accounts/credentials", accountsController.store, {
+  logging: { body: false, query: false },
+});
+```
+
+Request log entries otherwise include the body as received (before validation), so rejected fields would be logged too.
+
 ## Gotchas
 
 - **Never import `routes.ts`.** The framework auto-loads it. Importing causes a double-registration error.

package/skills/run-app/SKILL.md

@@ -303,14 +303,21 @@ pnpm 10+ will not run a dependency's install script unless the app names it. esb
 [ERR_PNPM_IGNORED_BUILDS] Ignored build scripts: esbuild@0.27.7
 ```
 
-Fix it once in the app's `pnpm-workspace.yaml`:
+Where the approval goes depends on the pnpm version (measured with real installs):
+
+| pnpm             | Approve esbuild in                                                           |
+| ---------------- | ---------------------------------------------------------------------------- |
+| 10.26+, 11, 12   | `pnpm-workspace.yaml`: `allowBuilds:` / `  esbuild: true`                    |
+| 10.5 – 10.25     | `pnpm-workspace.yaml`: `onlyBuiltDependencies:` / `  - esbuild`              |
+| 7 – 9, 10.0–10.4 | `package.json`: `"pnpm": { "onlyBuiltDependencies": ["esbuild"] }`, and no `pnpm-workspace.yaml` |
 
 ```yaml
+# pnpm 10.26 and later
 allowBuilds:
   esbuild: true
 ```
 
-Note pnpm reads this from `pnpm-workspace.yaml`, **not** from `package.json`'s `pnpm` field — pnpm 11 warns that the field is ignored and then carries on, so settings left there fail silently.
+pnpm 11 and 12 ignore `package.json`'s `pnpm` field and fail the install when the workspace file has only `onlyBuiltDependencies`, so keep `allowBuilds` there (listing both keys is fine). pnpm before 10.5 rejects a `pnpm-workspace.yaml` without a `packages:` field (`packages field missing or empty`), and adding `packages: ["."]` makes every later dependency add fail with `ERR_PNPM_ADDING_TO_ROOT` — so on those versions use the `package.json` field instead. `create-warlock` 5.30.0 checks the pnpm version and writes the right one, and `warlock add image` follows the same rule when it approves `sharp`.
 
 `warlock dev` checks for esbuild's native binary before starting (as `warlock build` already did) and fails fast with `EsbuildBinaryMissingError`, naming the same fix, instead of surfacing an opaque low-level error later from inside the bundler.
 

package/skills/send-response/SKILL.md

@@ -96,7 +96,7 @@ stream.send("second chunk\n");
 stream.end();
 ```
 
-`response.stream(contentType?)` returns a controller with `.send(chunk)`, `.render(reactNode)`, `.end()`, and an `.ended` getter. Use for large dynamic payloads where buffering would blow memory. Calling `.send()` after `.end()` throws.
+`response.stream(contentType?, { retainChunks? })` returns a controller with `.send(chunk)`, `.render(reactNode)`, `.end()`, and an `.ended` getter, plus `await .write(chunk)` / `await .drain()` (wait for a slow client; `false` once it left), `.backpressured`, `.signal` (aborted on client disconnect) and `.onDisconnect(fn)`. Use for large dynamic payloads where buffering would blow memory; loop on `await stream.write(chunk)` when the producer can outrun the client. Calling `.send()` after `.end()` throws; after a client disconnect it is a silent no-op. Written chunks are not kept on `response.body` unless `retainChunks` asks for a tail.
 
 ## Throwing HTTP errors
 
@@ -120,6 +120,12 @@ throw new ForbiddenError("permission.denied", { resource: "product", id });
 throw new ConflictError("user.duplicateEmail");
 ```
 
+A program that must not load the framework (a standalone helper, a worker
+bundle) imports the same classes from `@warlock.js/core/errors`, which pulls in
+nothing else. Domain errors that cannot extend `HttpError` get a status at the
+edge through `http.errorMapper` (`(error, request) => ({ status, message?, payload? }) | undefined`);
+anything unmapped and not an `HttpError` answers an opaque `500`.
+
 Each class takes `(message, payload?)`. The framework keeps the optional
 detail nested under `payload`:
 
@@ -158,7 +164,9 @@ sse.comment("keep-alive"); // invisible to the client, prevents timeout
 sse.end();
 ```
 
-`response.sse()` returns a controller with `send(event, data, id?)`, `comment(text)`, `end()`, `onDisconnect(handler)`, and an `.ended` getter. The `send` signature is positional — `event` name first, then the `data` payload (JSON-stringified for you), then an optional event `id`. After the client disconnects, `send`/`comment` become silent no-ops and any `onDisconnect` handlers fire — register cleanup there:
+For streams that can outrun the client (terminals, log tails, big feeds), `await sse.write(event, data)` instead of `send()`: it waits until the client has caught up and resolves `false` once the client is gone. `sse.drain()` waits without sending, `sse.backpressured` reports a backed-up transport, and `sse.signal` aborts on disconnect. Sent events are not kept on `response.body`; `response.sse({ retainEvents: n })` keeps the last `n` for logging/tests (default 0).
+
+`response.sse()` returns a controller with `send(event, data, id?)`, `comment(text)`, `end()`, `onDisconnect(handler)`, and an `.ended` getter. The `send` signature is positional — `event` name first, then the `data` payload (JSON-stringified for you), then an optional event `id`. Line breaks (and NUL) in the event name and `id` are removed, so values built from user input cannot inject SSE fields. After the client disconnects, `send`/`comment` become silent no-ops and any `onDisconnect` handlers fire (a handler that throws is logged; the rest still run) — register cleanup there:
 
 ```ts
 const sse = response.sse();

package/skills/store-file/SKILL.md

@@ -179,7 +179,11 @@ console.log(r2File.url);
 console.log(localFile.url);
 ```
 
-`storage.use(name)` returns a `ScopedStorage` with the same surface as `storage`. To change the default permanently, call `storage.setDefault(name)` — but you almost always want per-call scoping for clarity.
+`storage.use(name)` returns a `ScopedStorage` with the same surface as `storage`, directory operations included (`storage.use("private").deleteDirectory(dir)` type-checks; no cast). To change the default permanently, call `storage.setDefault(name)` — but you almost always want per-call scoping for clarity.
+
+## Cached image variants follow their source
+
+On a local disk, `delete`, `deleteMany`, `move` and `deleteDirectory` (for every file under it) also remove the file's cached image derivatives (the `?variant=` renders of `uploadedFileController`). For a file removed some other way, call `purgeImageVariants(path, { disk? })`; with no path it clears the disk's whole derivative cache. Serve another local disk's files and variants with `createUploadedFileController({ disk: "private" })`, or call `resolveImageVariant({ disk, path, variant, format? })` from your own authenticated route. A configured `uploads.images.cacheDirectory` is shared by every disk: never put it inside `public/` (Warlock warns once if you do).
 
 ## `StorageFile` — the OOP handle
 

package/skills/use-middleware/SKILL.md

@@ -39,7 +39,7 @@ Each is documented inline (JSDoc + `@example`) — read the file under `@warlock
 - **Rate limit** caps **requests per time window** — 5 logins/minute per IP. Use for abuse prevention, cost-control on cheap-but-spammable endpoints.
 - **Concurrency limit** caps **in-flight requests at any instant** — 3 simultaneous report generations. Use for expensive endpoints where parallel calls would overload the worker (CPU-bound, large memory, slow third-party).
 
-Both counters are **process-local**. With N replicas the effective cap is N × value. For globally-shared rate limits, configure `@fastify/rate-limit` with a Redis store via `http.rateLimit` instead.
+Both counters are **process-local** by default. With N replicas the effective cap is N × value. `rateLimit` can count in `@warlock.js/cache` instead: `store: "cache"` on the limiter, or `http.rateLimit.store: "cache"` for every limiter (give conditionally created limiters a `name`). It needs a counting driver (`redis`, `pg`, or memory for one process): `null` and `file` are refused, and a cache outage fails open with the error logged at most once a minute. The concurrency cap has no shared mode.
 
 ```ts
 import { middleware } from "@warlock.js/core";
@@ -80,7 +80,7 @@ Server errors (5xx) are not cached — clients can retry past a 5xx. 4xx respons
 
 ## Rate limit across servers
 
-`http.rateLimit` passes `@fastify/rate-limit` options through — set `redis` for a store shared by all servers; `enabled: false` turns the global limiter off. The per-route `middleware.rateLimit()` counters stay in-process.
+Set `http.rateLimit.store: "cache"` to count in the configured `@warlock.js/cache` driver, shared by every server on a Redis or Postgres cache; the per-route `middleware.rateLimit()` follows it. `http.rateLimit` also passes `@fastify/rate-limit` options through (its own `redis` option needs an ioredis client, not the cache's node-redis one); `enabled: false` turns the global limiter off.
 
 ## `maxBodySize` vs the global `http.bodyLimit`
 

package/skills/validate-input/SKILL.md

@@ -168,7 +168,7 @@ const uploadAvatarSchema = v.object({
 });
 ```
 
-Full file chain: `.image()`, `.accept(extensions)`, `.mimeType(types)`, `.pdf()`, `.excel()`, `.word()`, `.minSize(n)`, `.maxSize(n)`, `.minWidth(px)`, `.maxWidth(px)`, `.minHeight(px)`, `.maxHeight(px)`. See the `upload-file` topic for the full upload flow.
+Full file chain: `.image()`, `.accept(extensions)`, `.mimeType(types)`, `.pdf()`, `.excel()`, `.word()`, `.minSize(n)`, `.maxSize(n)`, `.minWidth(px)`, `.maxWidth(px)`, `.minHeight(px)`, `.maxHeight(px)`. Every rule returns `this`, so the field's output type stays `UploadedFile` through the chain; `.saveTo(dir)` switches it to `string` (the saved path). See the `upload-file` topic for the full upload flow.
 
 ### Optional file field