@warlock.js/core 5.29.0 → 5.31.0

package/skills/upload-file/SKILL.md

@@ -77,30 +77,30 @@ For multi-file uploads, use an array schema (`v.array(v.file())`) — the valida
 
 From `@warlock.js/core/src/http/uploaded-file.ts`:
 
-| Member                              | Returns                | Notes                                                  |
-| ----------------------------------- | ---------------------- | ------------------------------------------------------ |
-| `file.name`                         | `string`               | sanitized original filename                            |
-| `file.mimeType`                     | `string`               | e.g. `"image/jpeg"`                                    |
-| `file.extension`                    | `string`               | lowercased, no dot — e.g. `"jpg"`                      |
-| `file.isImage` / `isVideo` / `isAudio` | `boolean`           | MIME-type prefix checks                                |
-| `await file.size()`                 | `number` (bytes)       | buffers the file on first call                         |
-| `await file.buffer()`               | `Buffer`               | cached after first call                                |
-| `await file.dimensions()`           | `{ width?, height? }`  | empty object if not an image                           |
-| `await file.metadata()`             | `{ name, mimeType, extension, size, width?, height? }` | one-shot metadata |
-| `await file.toImage()`              | `Image`                | for advanced transforms outside the fluent API         |
-| `await file.toJSON()`               | metadata + base64      | for serialization / debugging                          |
+| Member                                 | Returns                                                | Notes                                          |
+| -------------------------------------- | ------------------------------------------------------ | ---------------------------------------------- |
+| `file.name`                            | `string`                                               | sanitized original filename                    |
+| `file.mimeType`                        | `string`                                               | e.g. `"image/jpeg"`                            |
+| `file.extension`                       | `string`                                               | lowercased, no dot — e.g. `"jpg"`              |
+| `file.isImage` / `isVideo` / `isAudio` | `boolean`                                              | MIME-type prefix checks                        |
+| `await file.size()`                    | `number` (bytes)                                       | buffers the file on first call                 |
+| `await file.buffer()`                  | `Buffer`                                               | cached after first call                        |
+| `await file.dimensions()`              | `{ width?, height? }`                                  | empty object if not an image                   |
+| `await file.metadata()`                | `{ name, mimeType, extension, size, width?, height? }` | one-shot metadata                              |
+| `await file.toImage()`                 | `Image`                                                | for advanced transforms outside the fluent API |
+| `await file.toJSON()`                  | metadata + base64                                      | for serialization / debugging                  |
 
 Image transforms (chainable, no-op for non-images):
 
-| Method                          | Notes                                  |
-| ------------------------------- | -------------------------------------- |
-| `.resize(width, height?)`       | proportional if `height` omitted       |
-| `.format(format)`               | `"jpeg" | "png" | "webp" | "avif" | ...` — extension is auto-updated |
-| `.quality(1–100)`               | JPEG/WebP/AVIF only                    |
-| `.rotate(deg)`                  | positive = clockwise                   |
-| `.blur(sigma?)`                 | default `3`, min `0.3`                 |
-| `.grayscale()`                  | —                                      |
-| `.transform(opts | callback)`   | full sharp/`ImageTransformOptions` control |
+| Method                    | Notes                            |
+| ------------------------- | -------------------------------- |
+| `.resize(width, height?)` | proportional if `height` omitted |
+| `.format(format)`         | `"jpeg"                          | "png"                                      | "webp" | "avif" | ...` — extension is auto-updated |
+| `.quality(1–100)`         | JPEG/WebP/AVIF only              |
+| `.rotate(deg)`            | positive = clockwise             |
+| `.blur(sigma?)`           | default `3`, min `0.3`           |
+| `.grayscale()`            | —                                |
+| `.transform(opts          | callback)`                       | full sharp/`ImageTransformOptions` control |
 
 Save:
 
@@ -112,7 +112,7 @@ await file.saveAs(fullPath, options?);  // explicit path, returns StorageFile
 Driver selection:
 
 ```ts
-await file.use("s3").save("avatars");        // single upload
+await file.use("s3").save("avatars"); // single upload
 await file.use("r2").saveAs("cdn/x.webp");
 ```
 
@@ -122,15 +122,15 @@ await file.use("r2").saveAs("cdn/x.webp");
 type SaveOptions = {
   name?: "random" | "original" | string; // default "random"
   prefix?:
-    | true                                  // default datetime prefix
-    | string                                // static prefix
+    | true // default datetime prefix
+    | string // static prefix
     | {
-        format?: string;                    // dayjs-style format
+        format?: string; // dayjs-style format
         randomLength?: number;
-        as?: "file" | "directory";          // default "file"
+        as?: "file" | "directory"; // default "file"
       };
   driver?: StorageDriverName;
-  validate?: FileValidationOptions;         // throws on mismatch
+  validate?: FileValidationOptions; // throws on mismatch
 };
 ```
 
@@ -166,12 +166,12 @@ await file.saveAs("avatars/profile-123.png");
 ```ts
 const stored = await file.save("avatars");
 
-stored.path;          // "avatars/x7k9m2p4.webp" (after format transform)
-stored.url;           // public URL (driver-dependent)
+stored.path; // "avatars/x7k9m2p4.webp" (after format transform)
+stored.url; // public URL (driver-dependent)
 await stored.size();
 await stored.mimeType();
 stored.extension;
-await stored.data();  // full info object incl. hash
+await stored.data(); // full info object incl. hash
 ```
 
 `StorageFile` is the standard handle returned by every `Storage.put()` / `UploadedFile.save()` call. Use it from then on — the `UploadedFile` is best discarded after save.
@@ -278,9 +278,7 @@ Each chain produces a fresh transform — but `UploadedFile` is stateful, so do
 ### Saving to S3 with a content type override
 
 ```ts
-const file = await uploadedFile
-  .use("s3")
-  .save("documents", { name: "original" });
+const file = await uploadedFile.use("s3").save("documents", { name: "original" });
 
 // or, full storage layer:
 await storage.use("s3").put(await uploadedFile.buffer(), "documents/report.pdf", {

package/skills/use-app-context/SKILL.md

@@ -17,8 +17,8 @@ if (Application.isProduction) {
 }
 
 const uploadsDir = Application.uploadsPath;
-const uptimeMs   = Application.uptime;
-const version    = Application.version;
+const uptimeMs = Application.uptime;
+const version = Application.version;
 ```
 
 Every member is a getter — values are computed on access, not snapshotted at boot. That's deliberate: tests flip the environment, the dev server flips the runtime strategy, and the framework caches its own version. You always read the current value.
@@ -26,10 +26,10 @@ Every member is a getter — values are computed on access, not snapshotted at b
 ## Environment
 
 ```ts
-Application.environment      // "development" | "production" | "test"
-Application.isProduction     // === "production"
-Application.isDevelopment    // === "development"
-Application.isTest           // === "test"
+Application.environment; // "development" | "production" | "test"
+Application.isProduction; // === "production"
+Application.isDevelopment; // === "development"
+Application.isTest; // === "test"
 ```
 
 Backed by `process.env.NODE_ENV`. `setEnvironment` mutates it:
@@ -50,7 +50,7 @@ const httpConfigurations: HttpConfigurations = {
     secret: env("COOKIE_SECRET", "super-secret-key-change-me"),
     options: {
       httpOnly: true,
-      secure: Application.isProduction,   // true on prod (HTTPS only), false in dev
+      secure: Application.isProduction, // true on prod (HTTPS only), false in dev
       path: "/",
     },
   },
@@ -61,13 +61,13 @@ export default httpConfigurations;
 
 ## Runtime strategy
 
-`runtimeStrategy` is a separate axis from `environment`. It marks how the *framework itself* is running:
+`runtimeStrategy` is a separate axis from `environment`. It marks how the _framework itself_ is running:
 
 - `"development"` — dev server (file watcher, HMR, transpile cache on disk).
 - `"production"` — built bundle running from `dist/`.
 
 ```ts
-Application.runtimeStrategy           // "production" | "development"
+Application.runtimeStrategy; // "production" | "development"
 Application.setRuntimeStrategy("production");
 ```
 
@@ -77,7 +77,7 @@ Most app code shouldn't care about `runtimeStrategy` — branch on `environment`
 
 ## Lifecycle: boot & shutdown
 
-`Application.onceBooted(callback)` runs a callback the moment the app is fully booted — every connector in **both** phases is active and all app files (locales, events, main, routes) are loaded. It's the only hook that fires *after* the late phase (http, socket) is up.
+`Application.onceBooted(callback)` runs a callback the moment the app is fully booted — every connector in **both** phases is active and all app files (locales, events, main, routes) are loaded. It's the only hook that fires _after_ the late phase (http, socket) is up.
 
 ```ts
 import { Application } from "@warlock.js/core";
@@ -87,18 +87,18 @@ Application.onceBooted(({ environment, runtimeStrategy, bootDurationMs }) => {
 });
 ```
 
-Why a dedicated hook instead of code at the bottom of `main.ts`? **App files load before the late phase.** `main.ts`, `events.ts`, `routes.ts`, and locales are all imported *between* the early and late connector phases — so when `main.ts` runs, http/socket are not listening yet. `onceBooted` defers your callback until the whole sequence finishes, which makes it the safe place to touch `app.http` / `app.socket` from `main.ts`-level code.
+Why a dedicated hook instead of code at the bottom of `main.ts`? **App files load before the late phase.** `main.ts`, `events.ts`, `routes.ts`, and locales are all imported _between_ the early and late connector phases — so when `main.ts` runs, http/socket are not listening yet. `onceBooted` defers your callback until the whole sequence finishes, which makes it the safe place to touch `app.http` / `app.socket` from `main.ts`-level code.
 
-It's a **latch**, not a plain event listener: register before boot and it queues; register *after* boot and it fires on the next microtask. A late subscriber never silently misses the signal.
+It's a **latch**, not a plain event listener: register before boot and it queues; register _after_ boot and it fires on the next microtask. A late subscriber never silently misses the signal.
 
 ```ts
-Application.isBooted;           // boolean — has boot finished?
+Application.isBooted; // boolean — has boot finished?
 await Application.whenBooted(); // Promise<BootContext> — await instead of a callback
 ```
 
 `whenBooted()` is the promise form, resolving with the same `BootContext` (`{ environment, runtimeStrategy, bootDurationMs? }`). `bootDurationMs` is set by the dev server (which times boot) and omitted by the production entry.
 
-The framework fires the latch for you — the dev server and the production bundle each call it once, right after the late phase. App code only ever *reads* it via `onceBooted` / `whenBooted` / `isBooted`; the internal `markBooted` is a framework entry point, not for application use.
+The framework fires the latch for you — the dev server and the production bundle each call it once, right after the late phase. App code only ever _reads_ it via `onceBooted` / `whenBooted` / `isBooted`; the internal `markBooted` is a framework entry point, not for application use.
 
 ### Run something once everything is listening
 
@@ -120,6 +120,8 @@ This is the right home for "warm a cache", "register a recurring job", "ping a r
 ```ts title="src/app/main.ts"
 import { Application } from "@warlock.js/core";
 
+declare function startQueueConsumer(): { stop(): Promise<void> }; // your long-running worker
+
 Application.onceBooted(() => {
   const consumer = startQueueConsumer();
 
@@ -140,12 +142,12 @@ For path helpers (`appPath`, `configPath`, `uploadsPath`, …) anchored at `proc
 The most-used helpers are also surfaced as no-argument getters on `Application`:
 
 ```ts
-Application.rootPath        // <cwd>
-Application.srcPath         // <cwd>/src
-Application.appPath         // <cwd>/src/app
-Application.publicPath      // <cwd>/public
-Application.storagePath     // <cwd>/storage
-Application.uploadsPath     // <cwd>/storage/uploads (or override)
+Application.rootPath; // <cwd>
+Application.srcPath; // <cwd>/src
+Application.appPath; // <cwd>/src/app
+Application.publicPath; // <cwd>/public
+Application.storagePath; // <cwd>/storage
+Application.uploadsPath; // <cwd>/storage/uploads (or override)
 ```
 
 Reach for those when you want the directory itself; reach for the helpers (e.g. `appPath("orders/routes.ts")`) when you need a file inside.
@@ -153,9 +155,9 @@ Reach for those when you want the directory itself; reach for the helpers (e.g.
 ## Version and uptime
 
 ```ts
-Application.version        // "1.0.0" (semver, cached after first read)
-Application.uptime         // ms since process start
-Application.startedAt      // Date object — wall time when the process booted
+Application.version; // "1.0.0" (semver, cached after first read)
+Application.uptime; // ms since process start
+Application.startedAt; // Date object — wall time when the process booted
 ```
 
 `version` is the `@warlock.js/core` package version, lazily loaded once. `uptime` is `process.uptime() * 1000` — the Node-process uptime, not "the framework's uptime." If you spawn workers, each worker has its own.
@@ -175,13 +177,13 @@ The project's home page surfaces the version in a footer:
 ```ts
 import { app } from "@warlock.js/core";
 
-app.http        // Fastify instance (after http connector starts)
-app.socket      // socket.io Server (after socket connector starts)
-app.router      // the Router singleton
-app.database    // Cascade's DataSource
+app.http; // Fastify instance (after http connector starts)
+app.socket; // socket.io Server (after socket connector starts)
+app.router; // the Router singleton
+app.database; // Cascade's DataSource
 ```
 
-Each property is a getter backed by the framework's DI container (`container.tryGet("http.server")` etc. — `router` uses `container.get(...)`, which throws instead, since it is never legitimately absent). The container is populated by connectors during their `boot()`/`start()` phase — read these accessors only after the relevant connector has run. `http`, `socket`, and `database` are thin `container.tryGet(...)` reads, so before the connector boots they return `undefined` (they do **not** throw); chaining off an `undefined` accessor is what blows up. `http` and `socket` are *late*-phase connectors — they boot **after** app code is imported, so these accessors are not populated at the top level of a module's `main.ts`. From inside controllers, services, use-cases, or any code that runs while a request is in flight, every accessor is safe.
+Each property is a getter backed by the framework's DI container (`container.tryGet("http.server")` etc. — `router` uses `container.get(...)`, which throws instead, since it is never legitimately absent). The container is populated by connectors during their `boot()`/`start()` phase — read these accessors only after the relevant connector has run. `http`, `socket`, and `database` are thin `container.tryGet(...)` reads, so before the connector boots they return `undefined` (they do **not** throw); chaining off an `undefined` accessor is what blows up. `http` and `socket` are _late_-phase connectors — they boot **after** app code is imported, so these accessors are not populated at the top level of a module's `main.ts`. From inside controllers, services, use-cases, or any code that runs while a request is in flight, every accessor is safe.
 
 Typical uses (note: from runtime code, after bootstrap — not at module-import time):
 
@@ -201,7 +203,7 @@ export function setupChatSocket() {
 ```ts title="raw DataSource for an out-of-Cascade query"
 import { app } from "@warlock.js/core";
 
-const result = await app.database.client.query("SELECT NOW()");
+const result = await app.database?.driver.query("SELECT NOW()"); // { rows, rowCount }
 ```
 
 Reach for `app.*` as the escape hatch. If a typed framework primitive wraps the same thing (`router.get(...)` over `app.http.route(...)`, repository methods over raw `app.database` queries), prefer that — the typed surface keeps you on the rails the rest of the framework is designed around.
@@ -212,9 +214,14 @@ Reach for `app.*` as the escape hatch. If a typed framework primitive wraps the
 
 ```ts title="src/config/log.ts"
 import { Application, type LogConfigurations } from "@warlock.js/core";
+import { ConsoleLog } from "@warlock.js/logger";
 
 const logConfig: LogConfigurations = {
-  level: Application.isProduction ? "info" : "debug",
+  channels: [
+    new ConsoleLog({
+      levels: Application.isProduction ? ["info", "warn", "error", "fatal"] : undefined, // undefined = all
+    }),
+  ],
 };
 
 export default logConfig;
@@ -289,7 +296,7 @@ cors: {
 - **`version` is `null` until the first `await`.** The version loader is async (it reads `package.json`). On a cold start before any framework code has run `getWarlockVersion()`, `Application.version` returns `null`. The framework does load it during bootstrap, so anywhere downstream of bootstrap is fine — controllers, services, connectors after `start()`. CLI commands without `preload.bootstrap` may see `null`.
 - **`Application` is static, not a DI registration.** Don't try to inject it. There's nothing to inject — it's a class with only static members.
 - **`app.*` accessors return `undefined` before their connector boots — they don't throw.** `app.socket` / `app.database` / `app.http` are populated by their respective connectors during boot; until then each getter returns `undefined` (a bare `container.tryGet(...)`). Reading them earlier (eager module-load code, the top level of a `main.ts` for the late-phase `http`/`socket`, certain CLI commands without the right `preload.connectors`) hands you `undefined`, and chaining off it throws. Safe everywhere downstream of bootstrap — including inside `Application.onceBooted(...)`. `app.router` is the exception: it reads via `container.get(...)`, which throws a named `ContainerKeyMissingError` instead of handing back `undefined`, because the router is never a legitimate absence.
-- **`onceBooted` is a latch, not `events.on`.** A callback registered *after* boot completed still runs (next microtask) instead of silently missing the signal — so register it wherever it reads best, including module top-level in `main.ts`. A listener that throws is caught and logged; it can't break boot or the other listeners.
+- **`onceBooted` is a latch, not `events.on`.** A callback registered _after_ boot completed still runs (next microtask) instead of silently missing the signal — so register it wherever it reads best, including module top-level in `main.ts`. A listener that throws is caught and logged; it can't break boot or the other listeners.
 - **`onShutdown` runs before connectors close, not after.** That ordering is deliberate so cleanup can still use db/cache/http — but it means a hook that hangs delays connector teardown (bounded only by your process manager's kill timeout). Keep teardown fast; for HTTP draining the framework already bounds it via `http.gracefulShutdown.timeout`.
 
 ## See also

package/skills/use-middleware/SKILL.md

@@ -22,15 +22,15 @@ For authoring your OWN middleware (custom guards, enrichment, etc.), see the `wr
 
 All seven are factories — call them to get a `Middleware`. All set `errorCode` on the response so clients can branch without parsing error text (see `HttpErrorCodes` from `@warlock.js/core`). Error messages are translation-driven — keys live under the `http` group in `src/app/shared/utils/locales.ts`.
 
-| Factory | What it does | Status on reject |
-|---|---|---|
-| `middleware.rateLimit({ max, duration })` | Per-route/group cap on top of global `@fastify/rate-limit` | 429 + `Retry-After` |
-| `middleware.concurrencyLimit(n)` | Cap in-flight requests; no queue, fast reject | 429 + `Retry-After: 1` |
-| `middleware.maxBodySize("2mb")` | Per-route `Content-Length` cap | 413 |
-| `middleware.idempotency()` | Dedupe writes by `Idempotency-Key` header; cached replay | 422 on conflict |
-| `middleware.maintenance()` | Globally toggle 503 with allowlist bypass | 503 + `Retry-After` |
-| `middleware.ipFilter({ allow, deny })` | Allowlist/denylist by client IP | 403 (fail-closed) |
-| `middleware.cache(opts)` | Cache + replay successful JSON responses | n/a |
+| Factory                                   | What it does                                               | Status on reject       |
+| ----------------------------------------- | ---------------------------------------------------------- | ---------------------- |
+| `middleware.rateLimit({ max, duration })` | Per-route/group cap on top of global `@fastify/rate-limit` | 429 + `Retry-After`    |
+| `middleware.concurrencyLimit(n)`          | Cap in-flight requests; no queue, fast reject              | 429 + `Retry-After: 1` |
+| `middleware.maxBodySize("2mb")`           | Per-route `Content-Length` cap                             | 413                    |
+| `middleware.idempotency()`                | Dedupe writes by `Idempotency-Key` header; cached replay   | 422 on conflict        |
+| `middleware.maintenance()`                | Globally toggle 503 with allowlist bypass                  | 503 + `Retry-After`    |
+| `middleware.ipFilter({ allow, deny })`    | Allowlist/denylist by client IP                            | 403 (fail-closed)      |
+| `middleware.cache(opts)`                  | Cache + replay successful JSON responses                   | n/a                    |
 
 Each is documented inline (JSDoc + `@example`) — read the file under `@warlock.js/core/src/http/middleware/<name>.middleware.ts` for the full option surface.
 
@@ -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. The cache-backed limiter passes its window TTL into every atomic increment, so counters recreated after a seed expires still expire even with no driver default TTL.
 
 ```ts
 import { middleware } from "@warlock.js/core";
@@ -47,7 +47,7 @@ import { middleware } from "@warlock.js/core";
 router.post("/ai/summarize", summarizeController, {
   middleware: [
     middleware.rateLimit({ max: 60, duration: 60 * 60 * 1000 }), // 60/hr per user
-    middleware.concurrencyLimit(5),                              // ≤5 in-flight at once
+    middleware.concurrencyLimit(5), // ≤5 in-flight at once
   ],
 });
 ```
@@ -70,7 +70,7 @@ Lifecycle:
 1. **Method not eligible** (GET / HEAD) → pass through.
 2. **No `Idempotency-Key` header** → pass through (the primitive is opt-in by the client).
 3. **Key already in flight** (concurrent duplicate) → 409 with `Retry-After`. The key is reserved create-only before the handler runs (`reservationTtl`, default 60s, or `http.idempotency.reservationTtl`). A 5xx frees the reservation; if the cache is down it fails open. Use a shared cache (redis/pg) across servers.
-3b. **Key + same body within TTL** (default 24h) → replays the cached response with `Idempotent-Replay: true`. Handler does NOT re-run.
+   3b. **Key + same body within TTL** (default 24h) → replays the cached response with `Idempotent-Replay: true`. Handler does NOT re-run.
 4. **Key + different body** → 422 `IdempotencyKeyConflict`. Client bug — same key must mean same intent.
 5. **Cache miss** → runs handler; on response sent, caches `{ status, body, bodyHash }` for TTL.
 
@@ -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`
 
@@ -124,12 +124,12 @@ export default {
 
 ⚠ **Opt in with the narrowest shape your topology allows, not with `true`.** `http.trustProxy` takes a trusted-proxy list, and `detectIp()` resolves the chain the same way Fastify's `request.ip` does:
 
-| `http.trustProxy` | Client IP |
-| --- | --- |
-| `false` *(default)* | Socket peer address |
-| `"10.0.0.0/8"` / `"loopback, 10.0.0.0/8"` / `["10.0.0.0/8", "192.168.0.0/16"]` | Walks left while each hop is a listed proxy, stops at the first that isn't |
-| `(address, hop) => boolean` | Your own predicate |
-| `true` | Trusts the whole chain — the leftmost hop, i.e. **whatever the client put there** if your edge appends rather than overwrites |
+| `http.trustProxy`                                                              | Client IP                                                                                                                     |
+| ------------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------- |
+| `false` _(default)_                                                            | Socket peer address                                                                                                           |
+| `"10.0.0.0/8"` / `"loopback, 10.0.0.0/8"` / `["10.0.0.0/8", "192.168.0.0/16"]` | Walks left while each hop is a listed proxy, stops at the first that isn't                                                    |
+| `(address, hop) => boolean`                                                    | Your own predicate                                                                                                            |
+| `true`                                                                         | Trusts the whole chain — the leftmost hop, i.e. **whatever the client put there** if your edge appends rather than overwrites |
 
 ⚠ **Since 5.2 the value is validated at boot, and a hop count is refused.** The accepted shapes are exactly `boolean`, a non-empty string (comma-separated IPs/CIDRs), a non-empty `string[]`, and an `(address, hop) => boolean` predicate. Missing or nullish means `false`. Anything else — a **number**, `""`, `[]`, a mixed array, a plain object — throws a `TypeError` while the HTTP server is being constructed instead of being silently coerced:
 
@@ -212,10 +212,7 @@ import { authMiddleware } from "@warlock.js/auth";
 import { middleware, router } from "@warlock.js/core";
 
 router.post("/auth/login", loginController, {
-  middleware: [
-    middleware.rateLimit({ max: 5, duration: 60_000 }),
-    middleware.maxBodySize("4kb"),
-  ],
+  middleware: [middleware.rateLimit({ max: 5, duration: 60_000 }), middleware.maxBodySize("4kb")],
 });
 
 router.group({ middleware: [authMiddleware("client")] }, () => {
@@ -247,9 +244,9 @@ import { ulid } from "ulid"; // if you prefer ULID over the default random strin
 
 export default {
   requestId: {
-    header: "X-Request-Id",   // outbound + inbound header name
-    generator: () => ulid(),  // optional override
-    enabled: true,            // set false to disable both inherit + echo
+    header: "X-Request-Id", // outbound + inbound header name
+    generator: () => ulid(), // optional override
+    enabled: true, // set false to disable both inherit + echo
   },
 };
 ```
@@ -272,3 +269,26 @@ export default {
 - The `register-route` topic — where middleware attaches: `router.group` and route-options.
 - The `send-response` topic — the response helpers used to short-circuit (`tooManyRequests`, `contentTooLarge`, `serviceUnavailable`, etc.).
 - The `cache-basics` topic of the `warlock-js-cache` skill — the cache singleton (`@warlock.js/cache`) that backs `middleware.idempotency` and `middleware.cache`.
+
+## Shared counters with a complete config
+
+```ts title="src/config/http.ts"
+import type { HttpConfigurations } from "@warlock.js/core";
+
+export default {
+  rateLimit: { store: "cache", max: 100, timeWindow: "1m" },
+} satisfies HttpConfigurations;
+```
+
+Configure the same Redis or Postgres cache on each server before enabling this;
+a process-local memory driver shares no counters across replicas. Route-specific
+limits get independent counters. Moving from the memory store to `store: "cache"`
+starts fresh windows; this store was introduced in 5.30.
+
+```ts title="src/app/private/routes.ts"
+import { router } from "@warlock.js/core";
+
+router.post("/private/preview", ({ response }) => response.success({ ready: true }), {
+  logging: { body: false, query: false },
+});
+```

package/skills/use-model-transformers/SKILL.md

@@ -7,11 +7,11 @@ description: 'Three schema-side helpers — `useHashedPassword()` (bcrypt on sav
 
 Three helpers in `@warlock.js/core` plug into Seal schemas to compute or mutate a field at write time. They sit between "controllers + services" (the mutable-input layer) and "the database row" (the stored state) — so the value the DB sees is always derived, even if the caller didn't think about it.
 
-| Helper | Job | Attaches via | Behavior |
-| --- | --- | --- | --- |
-| `useHashedPassword()` | bcrypt-hash a password field on save | `.addTransformer(useHashedPassword())` on the field | Hash on new row; hash on change; pass through on no-change |
-| `useComputedSlug(field?, scope?)` | Derive a slug from another field | `v.computed(useComputedSlug("title"))` | Compute on every save where the source field is set |
-| `useComputedModel(callback)` | Any custom derived value | `v.computed(useComputedModel(...))` | Runs your callback with `(data, model, context)` |
+| Helper                            | Job                                  | Attaches via                                        | Behavior                                                   |
+| --------------------------------- | ------------------------------------ | --------------------------------------------------- | ---------------------------------------------------------- |
+| `useHashedPassword()`             | bcrypt-hash a password field on save | `.addTransformer(useHashedPassword())` on the field | Hash on new row; hash on change; pass through on no-change |
+| `useComputedSlug(field?, scope?)` | Derive a slug from another field     | `v.computed(useComputedSlug("title"))`              | Compute on every save where the source field is set        |
+| `useComputedModel(callback)`      | Any custom derived value             | `v.computed(useComputedModel(...))`                 | Runs your callback with `(data, model, context)`           |
 
 All three are imported from `@warlock.js/core` (despite living in `src/database/utils.ts` under the hood).
 
@@ -53,12 +53,12 @@ password: v.string().addTransformer(useHashedPassword()),
 
 What it does at save time:
 
-| Situation                       | Behavior                                    |
-| ------------------------------- | ------------------------------------------- |
-| New row, password set           | Hash the value before insert.               |
-| Existing row, password changed  | Re-hash the new value.                      |
+| Situation                        | Behavior                                              |
+| -------------------------------- | ----------------------------------------------------- |
+| New row, password set            | Hash the value before insert.                         |
+| Existing row, password changed   | Re-hash the new value.                                |
 | Existing row, password unchanged | Pass through (no re-hashing — stored hash preserved). |
-| Empty / undefined value         | Pass through untouched.                     |
+| Empty / undefined value          | Pass through untouched.                               |
 
 Calls `authService.hashPassword(String(value))` under the hood — same bcryptjs path as the standalone `hashPassword()` helper. See the `hash-password` topic for full bcrypt setup (salt rounds, `npm install bcryptjs`).
 
@@ -69,7 +69,7 @@ Without the transformer, every code path that writes a password has to remember:
 ```ts
 await User.create({
   email: input.email,
-  password: await hashPassword(input.password),  // easy to forget
+  password: await hashPassword(input.password), // easy to forget
 });
 ```
 
@@ -83,17 +83,17 @@ Pass plaintext to `User.create({ password: input.password })` and the transforme
 slug: v.computed(useComputedSlug("title")),
 ```
 
-- **`field`** *(default `"title"`)* — the source field name to slugify.
-- **`scope`** — `"sibling"` *(default)* or `"global"`. `"sibling"` reads `data[field]` from the same object being saved; `"global"` reads `get(context.allValues, field)` (the root context — useful in nested schemas where the source field lives on a parent).
+- **`field`** _(default `"title"`)_ — the source field name to slugify.
+- **`scope`** — `"sibling"` _(default)_ or `"global"`. `"sibling"` reads `data[field]` from the same object being saved; `"global"` reads `get(context.allValues, field)` (the root context — useful in nested schemas where the source field lives on a parent).
 
 What it does:
 
-| Situation                          | Behavior                                   |
-| ---------------------------------- | ------------------------------------------ |
-| Source field has a value           | Return `slugify(value)` — overwrite the slug. |
-| Source field is empty / undefined  | Return `model.get(field)` — i.e. the model's existing value for the **source** field (e.g. the stored `title`), not the existing slug. |
+| Situation                         | Behavior                                                                                                                               |
+| --------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------- |
+| Source field has a value          | Return `slugify(value)` — overwrite the slug.                                                                                          |
+| Source field is empty / undefined | Return `model.get(field)` — i.e. the model's existing value for the **source** field (e.g. the stored `title`), not the existing slug. |
 
-So if a caller sets `title: "Hello World"` without touching `slug`, the saved row has `slug: "hello-world"`. If they explicitly set `slug: "custom-handle"` AND leave `title` populated, the computed field **still overwrites** with the slugified title — because the source value is set. (Note the empty-source fallback returns `model.get(field)` keyed by the *source* field name, not the slug — a quirk of the implementation; if `title` is also empty on the model you get whatever the source field holds, which may be `undefined`.)
+So if a caller sets `title: "Hello World"` without touching `slug`, the saved row has `slug: "hello-world"`. If they explicitly set `slug: "custom-handle"` AND leave `title` populated, the computed field **still overwrites** with the slugified title — because the source value is set. (Note the empty-source fallback returns `model.get(field)` keyed by the _source_ field name, not the slug — a quirk of the implementation; if `title` is also empty on the model you get whatever the source field holds, which may be `undefined`.)
 
 To allow explicit slug overrides, branch in your service before calling save, or skip the transformer for that one save (model-level mutation).
 
@@ -121,14 +121,23 @@ The general-purpose computed-value helper. Use it when the value depends on the
 
 ```ts
 import { useComputedModel } from "@warlock.js/core";
-
-slug: v.computed(useComputedModel((data, model, context) => {
-  // data    — the current schema-level input object
-  // model   — the Model instance being saved
-  // context — Seal's SchemaContext (allValues, rootContext, etc.)
-
-  return `${data.category}-${slugify(data.title)}`;
-})),
+import { v } from "@warlock.js/seal";
+
+declare function slugify(text: string): string;
+
+const productSchema = v.object({
+  title: v.string().required(),
+  category: v.string().required(),
+  slug: v.computed(
+    useComputedModel((data, model, context) => {
+      // data    — the current schema-level input object
+      // model   — the Model instance being saved
+      // context — Seal's SchemaContext (allValues, rootContext, etc.)
+
+      return `${data.category}-${slugify(data.title)}`;
+    }),
+  ),
+});
 ```
 
 `useComputedSlug` is implemented on top of `useComputedModel` — they share the same signature. Reach for `useComputedSlug` for the common slug case; reach for `useComputedModel` when you need to combine fields, branch on env, or call out to a service.
@@ -137,8 +146,8 @@ slug: v.computed(useComputedModel((data, model, context) => {
 
 ```ts
 type ComputedCallbackModel = (
-  data: any,         // the schema input being saved
-  model: Model,      // the Cascade model instance
+  data: any, // the schema input being saved
+  model: Model, // the Cascade model instance
   context: SchemaContext,
 ) => any | Promise<any>;
 ```

package/skills/use-repository/SKILL.md

@@ -216,7 +216,7 @@ import { $agg } from "@warlock.js/cascade";
 const byStatus = await ordersRepository.groupBy(
   "status",
   { count: $agg.count(), total: $agg.sum("total") },
-  { paidAfter: "2026-01-01" },   // a filterBy key
+  { paidAfter: "2026-01-01" }, // a filterBy key
 );
 
 // one summary row over the whole filtered set (null when empty)
@@ -226,7 +226,7 @@ const summary = await ordersRepository.aggregate(
 );
 ```
 
-`fields` accepts a string, a `string[]`, or a column map; `aggregates` is a map of result alias → aggregate expression. Because filters are applied first, you never have to re-implement `filterBy` logic for a stats endpoint — the same inputs scope the count *and* the sums.
+`fields` accepts a string, a `string[]`, or a column map; `aggregates` is a map of result alias → aggregate expression. Because filters are applied first, you never have to re-implement `filterBy` logic for a stats endpoint — the same inputs scope the count _and_ the sums.
 
 ### Chunking