@warlock.js/core 5.29.0 → 5.31.0

package/CHANGELOG.md

@@ -6,12 +6,176 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 
 > ⚠ **Versioning: `@warlock.js/*` does not follow SemVer strictly — breaking changes may ship in a minor.** This is a deliberate decision, not an oversight: the framework is pre-adoption and the cost of a major per behaviour fix currently outweighs the benefit. **Pin an exact version or a tilde range (`~4.13.0`) if you need to opt into changes rather than receive them.** Every breaking change is marked **BREAKING** in its entry and summarised in an _Upgrading_ section at the top of the release. **This policy will change once the framework has consumers beyond its author.**
 
+## 5.31.0 - 2026-10-18
+
+### Security
+
+- In every release up to and including 5.30.0, the global `http.rateLimit` did not apply to application routes in production, and per-route `rateLimit` options had no effect in production (development enforced them). 5.31 enforces both: the shared bucket now covers pages and API routes. Static files (the public folder, `router.directory()` mounts, `router.file()` routes and the web build's assets) and the built-in liveness and readiness probes are exempt by default; `http.rateLimit.staticFiles: true` and `http.health.rateLimit: true` opt them into the global policy.
+
+### Upgrading
+
+- **BREAKING:** rate limits now apply to production and development application routes and web page routes. The default is 60 requests/minute per IP, in one bucket shared by pages and API routes. Review `http.rateLimit.max`; behind a proxy configure trusted `http.trustProxy` addresses or a suitable `keyGenerator` so clients do not share the proxy's quota. Set `http.rateLimit.global: false` to keep blanket quotas off while retaining explicit per-route limits. Static files (the public folder, `router.directory()` mounts, `router.file()`/`cachedFile()`/`files()`/`cachedFiles()` routes and the web build's assets) are exempt unless `http.rateLimit.staticFiles: true` counts them, so a page load's assets do not spend the quota. Files served by a route handler, such as `router.get("/uploads/*", createUploadedFileController())`, are not static mounts and do count against the limit; give such a route `rateLimit: false` or its own limit when pages load many of them. Built-in `/health` and `/ready` are exempt unless `http.health.rateLimit: true` opts them back in. Exempt any other route with `rateLimit: false`. `warlock upgrade --from 5.30 --to 5.31.0` lists an `http` config without `rateLimit` for review (codemod `rate-limit-defaults`).
+- **BREAKING:** upgrade development, CI and production runtimes to Node.js 22.15 or newer before running the CLI. `warlock upgrade --from 5.30 --to 5.31.0` raises `engines.node`, `.nvmrc` and `.node-version` (codemod `node-22-15`).
+- **BREAKING (tests only):** `setupTest()` and `startHttpTestServer()` install test fakes for mail, queue, cache, storage, clock and ids by default. Suites that relied on real deliveries, a Redis cache shared between the HTTP test server and the workers, real buckets or jobs processed by a worker set `fakes: false` (or `{ cache: false }`, etc.) in `src/config/tests.ts`, or pass `fakes` to either call.
+
+- `warlock dev` now writes the generated section of `AGENTS.md` at the project root (creating the file when it is missing; hand-written content outside the `warlock:generated` markers is left as it is) and `.warlock/dev-server.json`. Commit `AGENTS.md`, or set `devServer.agentsMd: false` to keep the dev server from touching it.
+
+### Added
+
+- `@warlock.js/core/net`: a side-effect-free subpath exporting the SSRF IP classifier `isPrivateOrReservedIp` (the same function the root exports). It loads only `node:net`, so workers, CLIs and standalone processes — `@warlock.js/ai` among them — can reuse the private-address rules without loading the HTTP server, database, cache or mail modules behind the root entry.
+- `http.rateLimit.staticFiles` (default `false`) decides whether static files count against the global rate limiter. Each static mount can decide for itself: `router.directory(options, { rateLimit })` and a fourth `{ rateLimit }` argument on `router.file()`, `cachedFile()`, `files()` and `cachedFiles()` take `true` (global limiter), `false` (exempt) or `{ max, timeWindow, errorMessage? }` (own limit and bucket).
+- Route validation can answer with an application's own failure body. `validation.onFailure(result, { request, response, route })` returns `{ status?, body }` for a failed `schema` or `params` (no `status` uses `validation.response.status`, 422 by default); `validation.response.body(result, route)` in the validation config does the same for every route. The route hook wins, either may return `undefined` to fall through, and the framework body is unchanged when neither is set. Routes also accept a `validation` option merged over the handler's own, so one handler can serve several routes with different failure codes. `ValidationConfiguration` now types `response` and `responseStatus`.
+- `warlock generate.openapi` documents a custom validation failure body from the handler's `responseSchema` entry for the failure status instead of the framework's `ValidationFailed` shape; without one, the configured status is documented without a body and a route-level hook produces a warning.
+- `evaluateConditionalRequest()`, `matchesIfNoneMatch()`, `matchesIfMatch()` and `parseEntityTagList()` expose the framework's RFC 9110 precondition handling for application handlers that set their own ETags.
+- A route's `rateLimit` option also accepts `false` to exempt the route from the global limiter, and `true` to keep it under the global policy (the default for application routes).
+- Production runtime support for Bun and Deno. An app built on Node with `warlock build` starts and serves on Bun 1.4.3 and Deno 2.9.7, either directly (`bun dist/app.js`, `deno run -A dist/app.js`) or through `warlock start` run with that runtime. A `runtimes` CI workflow builds a fixture app with pages, API routes, file cache, file logging and static files from the packed framework, starts it on Node, Bun and Deno, and checks every route plus a clean `SIGTERM` shutdown. The "Supported runtimes" docs page lists the commands for each runtime.
+- `detectJavaScriptRuntime()`, `describeJavaScriptRuntime()`, `nodeOnlyCommandError()`, `assertNodeOnlyCommand()` and `unverifiedBuildRuntimeNotice()` report which runtime is executing (`{ type: "node" | "bun" | "deno", version }`), and let a CLI command refuse to run anywhere but Node.
+- `warlock inspect [--json] [--section routes,models,…]` prints the app's facts from its booted registries: routes (middleware chain, auth guard, CSRF, rate limit, logging, request/response JSON Schema), models (table, columns, relations, resource), resources, config keys with types (never values), event listeners, pages (layout chain, loaders, actions, guard), queue jobs, scheduled tasks and installed `@warlock.js/*` versions. Boots like `warlock doctor` — no connection, no port. The report is versioned (`schemaVersion: 1`, fields only ever added) and published as JSON Schema: `schemas/inspect-report.schema.json` and `INSPECT_REPORT_JSON_SCHEMA`. `inspectApp()` returns the same object inside any process where the app is booted; `bootForInspect()` boots first.
+- `warlock check [--changed] [--base <ref>] [--skip …] [--json]` is one verify command: an incremental typecheck (in a child process, so running out of memory is reported), the app's ESLint/oxlint, the tests the change affects (`vitest run` / `vitest related`), and convention checks (importing an auto-loaded file, `.js` import extensions, relative imports across modules, `experimentalDecorators`). One JSON object per problem — `{ code, category, severity, source, file, line, column, message, hint, skill, docs, rule }` — and exit codes that split your code (1) from this machine (2: Node version, missing tool, unreachable database/Redis, busy port, git unavailable, tool crash). It detects and reports only; it never stops processes or frees ports.
+- `warlock check`'s conventions step also reports security and code-style problems from source, the same with ESLint, Oxlint or no linter: `request.all()` passed to a query, a service or `inApp()` (`WL9005`); a POST/PUT/PATCH/DELETE route with no auth middleware and no `public: true` (`WL9006`, the source-side twin of the `warlock dev` warning, sharing its guard-name rule); a `redirect()` / `navigateTo()` / `<Link to|href>` target read from request input without `safeRedirect()` / `safeRedirectTarget()` or an `isSafeRedirect()` check (`WL9007`); a raw email, credential or request body in a log call (`WL9008`, using the logger's default censored keys); a regex with an unbounded quantifier run on request input (`WL9009`); and, as warnings, `await log.*()` (`WL9010`), a second controller in one file (`WL9011`) and a `kind` union discriminator (`WL9012`). A `// warlock-check-ignore WL9006` comment on the problem's line or the line above records a deliberate exception. The generated `AGENTS.md` conventions list and the `warlock-conventions` skill cover every code.
+- `warlock typecheck [--changed] [--base <ref>] [--project <tsconfig>] [--json]` typechecks with the TypeScript compiler API, keeping incremental state in `.warlock/cache/typecheck.tsbuildinfo`; `--changed` checks only the changed files and the files importing them.
+- Stable error codes: a `WL` + four-digit registry (`ERROR_CODES`, first digit = area: config, boot, routing, validation, http, database, cli, environment, convention), each with a one-line fix, a skill and a docs anchor, exported from `@warlock.js/core` and `@warlock.js/core/errors` with `explainErrorCode()`, `errorCodeOf()` (also maps `ECONNREFUSED`/`EADDRINUSE` and follows `cause`) and `WarlockError`. Framework error classes carry a `code` (`ModuleLoadError` → `WL2001`, `ContainerKeyMissingError` → `WL2004`, `CliOptionValueError` → `WL7001`, …); a duplicate route name throws `RouteNameTakenError` (`WL3001`), and unknown route names, missing URL params, invalid controller actions and refused connector lists throw coded `WarlockError`s with unchanged messages. `warlock explain <CODE> [--json]` prints a code's meaning and fix; `warlock explain` lists them all.
+- `warlock doctor --json` prints the report as JSON, and every `warn`/`fail` finding (also in the plain report) carries its error code with the same `hint` / `skill` / `docs` fields `warlock check --json` uses.
+- `@warlock.js/core/tooling` subpath: `inspectApp`, `runCheck`, `runTypecheck`, `CHECK_EXIT_CODES` and the shared `ToolingProblem` type, kept off the root barrel because it loads the TypeScript compiler and ESLint.
+- Skills `warlock-inspect` and `warlock-check`; `warlock-doctor` covers `--json` and error codes. Docs pages for `warlock inspect`, `warlock check` / `typecheck` and the error-code reference.
+- `warlock make endpoint <module>/<name>` (also `generate.endpoint` / `make.endpoint`) generates one endpoint from its request schema: `--schema` (a seal object schema file), `--method`, `--path`, `--resource`, and `--auth` (default) or `--public`. It writes the schema module, a service taking validated input, the resource shaped from the schema fields, one controller reading `request.validated()` with its `validation` and an OpenAPI `responseSchema`, the route (in a `guarded()` block, or marked `public: true`), the success message in `utils/locales.json`, and `tests/<name>.test.ts`, which requests the endpoint over the real HTTP stack with a valid input derived from the schema, a missing required field, and for guarded routes an anonymous `401` plus a signed-in case. Existing files are skipped and reported unless `--force`; a controller already in `routes.ts` is not registered twice. `warlock make <generator>` dispatches to every generator, like `warlock generate`.
+- Every `generate.*` command, `make` and `add` accept `--dry-run` (write nothing; `add` also installs nothing, running feature setup against an in-memory copy of the files) and `--json` (one versioned report on stdout listing files written, files skipped because they exist, per-file actions, command details and messages; also printed when the command fails). `add --list --json` includes the feature catalog.
+- Test fakes at `@warlock.js/core/tests`, installed by default in the test environment: `mailFake`, `queueFake`, `cacheFake`, `storageFake`, `clockFake` and `idsFake`, with assertion helpers (`assertSent`, `assertSentCount`, `assertPushed`, `assertNotPushed`, `assertHas`, `assertStored`, `assertExists`, `travel`, ...) whose failures list what was recorded. `installTestFakes()` / `restoreTestFakes()` and the `fakes` option of `setupTest()` / `startHttpTestServer()` control them; `tests.fakes` configures them per project. The storage fake's temp root is shared between the HTTP test server and the workers.
+- `clock` (`now()`, `timestamp()`) and `ids` (`uuid()`, `token(length)`) runtime helpers. Outside tests they are the system clock and `node:crypto`; in tests the fakes make them deterministic without touching `Date` or timers.
+- `defineFactory(Model, (seed) => attributes)` model factories with `make()`, `makeMany(n)`, `create()`, `create(n)`, `createMany(n)`, named states (`state()` / `with()`) and a deterministic seed (`text`, `email`, `uuid`, `date`, `number`, `pick`); `resetFactorySequences()`.
+- `createTestHttpServer({ routes?, loadAppModules?, importModule? })` serves requests inside the test worker with the production Fastify setup, plugins and route registration on an OS-assigned port, returning request helpers, `actingAs(user)` and `close()`; the worker's fakes see what handlers did. `createTestRequestClient(baseUrl)` binds the request helpers to any URL, and `actingAs(user, client?)` accepts one.
+- `startHttpTestServer({ port: 0 })` binds a free port and publishes the bound port to the workers; `warlock add test` now generates it.
+- `snapshotResponse(response, { redact })` reduces a response to status, content type and body with volatile paths redacted, for `toMatchSnapshot()`.
+- `warlock test [filters...]` runs the project's own Vitest with `--changed` (optionally `--since <ref>`), `--related <files>`, `--watch`, `--test-name-pattern` and `--json`; change-scoped runs pass when no test is affected.
+- `Storage` exposes `isInitialized`, `driverNames()` and `getDefaultName()`; mail exposes `getExplicitMailMode()` and `resetMailMode()`.
+- `warlock upgrade --to <version>` applies the mechanical edits for each breaking change between the installed release and the target, lists every place that needs a decision with `file:line`, a hint and the skill to read, and moves every `@warlock.js/*` dependency to the target. `--dry-run` prints a unified diff and writes nothing, `--json` prints the result, `--from` sets the version upgrading from; without it the command reads the installed `@warlock.js/core`, which is already the target once the new release is installed, so pass it (`warlock upgrade --from 5.30 --to 5.31.0`). With no `--from` and the installed version equal to the target, the command stops and asks for `--from <previous version>`. Codemods for 5.30 and 5.31: `logger-sync-calls`, `request-log-snapshot`, `head-viewport`, `node-22-15`, `warlock-versions`, plus review lists for `seal-validate-result`, `ai-tool-dispatch`, `ai-anthropic-body`, `ai-finish-reason`, `rate-limit-defaults`, `seal-refine-output`, `seal-container-catch`, `seal-union-output` and `ai-compaction-opt-in`. Source edits use `ts-morph`, an optional peer loaded only by this command; without it the command prints the install command and changes nothing.
+- Route option `public?: boolean` (also on `router.group()`, inherited by its routes; a route's own `public: false` opts back out) records that a mutating route is intentionally reachable without signing in. It changes nothing at runtime.
+- `warlock dev` warns once per route about POST/PUT/PATCH/DELETE routes that have no auth middleware and no `public: true`, listing method, path and route file; HMR-added routes are reported when they commit. Page routes are skipped, production never checks, and `http.warnUnguardedRoutes: false` turns it off. Middleware counts as a guard when marked with the new `markAuthGuard(middleware, isGuard?)` (`authMiddleware()` marks itself) or, unmarked, when its function name contains `auth` or `guard`; `isAuthGuardMiddleware()`, `isUnguardedMutatingRoute()` and `reportUnguardedMutatingRoutes()` are exported for tooling.
+- `safeRedirect(target, { allowedOrigins, fallback })` and `isSafeRedirect(target, options?)`: an allowlist for redirect targets taken from request input. Same-origin paths and absolute http(s) URLs on an allowed origin pass; `//host`, `/\host`, other schemes, credentials in the URL and control characters fall back to `"/"` (or `fallback`). `response.redirect()` itself is unchanged.
+- `escapeHeaderValue(value)` makes any value a valid header value: CR/LF/NUL and other control characters (tab kept) are removed, non-Latin-1 characters become `?`, and the result is trimmed, so request input cannot split a header or make Node throw a 500.
+- Typed, validated configuration: a `src/config/<name>.ts` file may export `configSchema = defineConfigSchema(validator, { env })` next to its default export (`ConfigOf<typeof configSchema>` types the value). Dev boot, each config hot reload and the production loader `warlock build` generates validate it before registration and throw one `InvalidConfigError` listing every problem in every config file (key path, rule message, the environment variable to set), never the values. An invalid config never reaches its special handler; an invalid hot reload keeps the previous value. Files without a schema load as before.
+- `warlock mcp` serves the app to coding agents over the Model Context Protocol — stdio by default, or `--http` (Streamable HTTP on `127.0.0.1`; `--token` / `WARLOCK_MCP_TOKEN` required for any other host). Tools: `inspect_app` and one `inspect_<section>` per inspect section (with filters, e.g. `inspect_routes { unguardedWrites: true }`), `db_schema` (tables, columns, keys and relations from the models), `docs_search` / `docs_read` (offline, over the installed `@warlock.js/*` skills, READMEs and llms files only), `explain`, `check_run`, `test_run` (one file, the tests related to changed files, or the suite), `requests_recent` (devtools: phases, queries with `nPlusOne` flags, logs, timings) and `generate_make` / `generate_add`, which run the generator in a throw-away copy of the project and return a unified diff. Read-only by default: writing needs `--allow-writes`, otherwise `write: true` is refused (`WL7005`). `@warlock.js/ai-tools` is a new optional peer, imported only by this command; a missing one fails with `WL7003` and the install line. Tool names use `_` because model APIs refuse `.` in tool names.
+- `warlock dev --mcp` (or `devServer.mcp: true | { port, token, allowWrites }`) serves the same tools from the dev server over loopback HTTP, reading the live registries after each hot reload.
+- `warlock dev` records its address, devtools mount and MCP endpoint in `.warlock/dev-server.json` (removed on shutdown); `warlock trace` and `requests_recent` read it.
+- `warlock trace <method> <url> [--body json|@file] [--header k:v] [--json]` sends one request to the running dev server (correlated by `x-request-id`) and prints its devtools timeline as a versioned report (`schemaVersion: 1`): middleware with timings, the validation result and errors, handler time, queries with N+1 flags, logs, cache operations, mails, the response (authorization and cookie headers redacted, bodies capped) and timings. Devtools is checked before anything is sent: `WL8008` when the dev server is not running, `WL8009` when devtools is not, `WL5004` when devtools recorded no timeline; failures exit 2 for this machine and 1 otherwise.
+- `warlock agents-md [--write] [--json]` generates the app-specific section of `AGENTS.md` from the booted app — modules with route and model counts, a routes summary with unguarded writes flagged, models, the conventions `warlock check` enforces, the installed skills and the verify commands — between `<!-- warlock:generated:start -->` and `<!-- warlock:generated:end -->`. Content outside the markers is never changed; malformed markers fail with `WL7501` and nothing is written. `warlock dev` refreshes the section on boot and after reloads (debounced, written only when it changed); `devServer.agentsMd: false` turns that off.
+- `warlock board init|add|status|send|watch [--json]` is a file-based protocol for two coding agents (an implementer and a reviewer) in a git-ignored `.warlock/board/`: items with the states todo, in-progress, ready-for-review, changes-requested, approved and blocked (refused moves fail with `WL7403`), append-only numbered messages per recipient (`to-<agent>/NNNN-<slug>.md`), `VERDICT: APPROVED` / `VERDICT: CHANGES REQUESTED` lines that move the item, and a `watch` that blocks until a new message arrives or times out (`WL7404`, exit 3). New codes `WL7401`–`WL7404` cover the board.
+- `runTests({ files | changed | base })` runs the app's vitest for one file, the tests related to changed files, or the suite, with the `warlock check` problem shape. It and the building blocks of the commands above (`startWarlockMcpServer`, `createMcpContext`, `createWarlockMcpTools`, `searchDocs`, `buildDbSchema`, `sandboxBackend`, `applyGeneration`, `traceRequest`, `connectDevtools`, `renderAgentsMdSection`, `writeAgentsMd`, `createAgentsMdRefresher`, `initBoard`, `watchBoard`, …) are exported from `@warlock.js/core/tooling`.
+- Skills `warlock-mcp`, `warlock-trace`, `warlock-agents-md` and `warlock-board`; `warlock-inspect` points agents at the MCP tools. Docs pages for `warlock mcp`, `warlock trace`, `warlock agents-md` and `warlock board`, and the new codes on the error-code reference.
+
+- End-to-end configuration recipes cover a non-default R2 image disk, variant ingestion and serving, and shared Redis rate-limit windows across two servers with outage behavior.
+- The `upgrade-from-5-29` skill guides application upgrades through logger delivery, tool concurrency, request snapshots, auth counter/lock resets, image cache layouts and viewport metadata. It covers Seal result narrowing and refinement/container/union behavior, AI finish reasons and replay, bounded workspace reads, and production rate-limit migration in 5.31; cut-off AI agent answers (`AgentIncompleteError` with `report.status: "incomplete"`, `continueOnOutputLimit`, per-run `modelOptions` and the Anthropic adapter's larger default `max_tokens`); the AI cost changes (per-provider cache billing, `totalCost`, the new built-in model prices and removed defaults, and `ProviderOverloadedError`); and the AI workspace changes (the larger `tools.all()` set, the new `WorkspaceOps` / `Workspace` methods, nested-command refusals and `dispose()`).
+- Skills include complete examples for request cancellation, stream/SSE backpressure and retention, HTTP error mapping, shared rate limits and signed-in test clients.
+- Notification scaffolds with test support emit real signed-in controller specs and isolated two-recipient fixtures for listing, unread counts, marking one/all read, query validation and ownership checks. Fixtures use the configured auth model and revoke/delete only their own credentials and rows.
+- `actingAs(user)` at `@warlock.js/core/tests` issues a real persisted access token and returns isolated authenticated HTTP helpers. Middleware remains active; `client.dispose()` revokes only its token.
+- Optional Oxlint background file checks during development. Install Oxlint in the app and add `.oxlintrc.json`, `.oxlintrc.jsonc`, `oxlint.config.ts` or `oxlint.config.mts`; changed files are linted in sequential batches in a worker and JSON diagnostics appear with rule, location and severity. Large boot scans stay within platform command-line limits, tool/config failures include actionable CLI output, and results omit source contents. Both configured ESLint and Oxlint run by default; ESLint still needs only its app configuration and uses core's own dependency. `devServer.healthCheckers` also accepts `{ typescript?, eslint?, oxlint? }` switches while preserving custom arrays and `false`.
+- Real Redis integration coverage for cache-backed HTTP rate-limit stores, including concurrent requests, preserved deadlines and counters recreated after a seeded key expires. Local runs opt in with `WARLOCK_REDIS_INTEGRATION=1`; CI requires a live Redis service. Tests use UUID prefixes and clean only their own keys.
+- Image variants support object-storage disks through `resolveImageVariant`, `createUploadedFileController` and `generateImageVariants({ disk, urlPrefix })`. Remote originals retain their driver URL; derivatives are cached locally, with bounded source reads and generation keys that isolate buckets and tenant prefixes. ETag metadata avoids downloads on cache hits; sources without an ETag use content hashes. Concurrent downloads are shared, and ingest downloads once for all variants/formats. The default public uploads controller keeps returning 404 for cloud default disks; an explicit `disk` or `remote: true` deliberately opts a controller into cloud serving.
+- `uploads.images.maxCacheBytes` (default 512 MiB) and `maxCacheAge` (default seven days) bound cached derivatives. Expired hits render again; cleanup removes expired and oldest files, retaining the derivative being returned even when it alone exceeds the byte budget. Writes schedule a coalesced background sweep at most once per minute; hits never walk the cache and the byte budget is eventual. Idle caches are reclaimed after their next generated derivative.
+- SSE supports unnamed events (`send(undefined, data)`) and raw string payloads through a fourth `{ raw: true }` argument, with safe multiline `data:` encoding. SSE and streams accept explicit cache `headers` before flushing while protecting protocol/drain headers and keeping safe cache defaults.
+- SSE and stream controllers gain synchronous `enqueue()` with a byte cap (`maxQueuedBytes`, default 1 MiB for enqueue), disconnect/drop overflow policies with a visible `dropped` counter, ordered draining and flushing accepted queued output on `end()`.
+- `http.logging.private` applies path-prefix or regular-expression policies to decoded, normalized request URLs, including unmatched requests. Matching policies check raw, decoded and resolved paths plus the matched route pattern, remove input before snapshots are built and cannot be overridden by per-route logging. Dev-dispatch error URLs use the same policy.
+
+### Fixed
+
+- Skill examples compile against the current API: the LLM-streaming example iterates `agent.stream()` events (`agent.trip.streaming` / `event.delta`), the raw-query example uses `app.database?.driver.query(...)`, the environment-aware logging example sets per-channel `levels` (`LogConfigurations` has no `level`), the authenticated-test examples use `authService.createTokenPair(user)` and `accessToken.token`, `devServer.healthCheckers` shows a valid value, and examples import or declare everything they use.
+- Running `bin/warlock.js` from a source checkout (no `esm/` build next to it) no longer crashes every booting command (`doctor`, `inspect`, `mcp`, `routes`) on Node.js 22.15 with `TypeError: t is not a function` from `dayjs.extend`. The bin's TypeScript `load` hook ran in the main thread, and on 22.15 that hands a CommonJS package the empty, not-yet-run exports of a file an ES module also imports (`@mongez/time-wizard` requiring the dayjs `utc` and `timezone` plugins). The hook now runs in a `module.register()` loader worker. Bare subpaths of a package consumed as source, such as `@warlock.js/core/net`, now resolve to the directory's `index.ts` instead of failing with `ERR_UNSUPPORTED_DIR_IMPORT`, so `warlock mcp` loads `@warlock.js/ai` from source. The published package, which loads compiled output without hooks, was not affected.
+- Conditional requests follow RFC 9110: `If-None-Match` uses weak comparison on both sides (a weak current ETag now matches its strong form) and parses quoted tags containing commas; `If-Match` uses strong comparison, so a `W/` tag never satisfies it. `response.sendFile()`, `sendBuffer()`/`sendImage()` with an `etag` and the uploads variant controller answer a failed `If-Match` or `If-Unmodified-Since` with 412, and evaluate the headers in the RFC order.
+- The development wildcard dispatcher applies the global rate limiter per matched route instead of to every request, so a route exempted with `rateLimit: false` or `serverOptions: { config: { rateLimit: false } }`, a static file route and an unmatched URL are not counted, exactly as in production. Routes with a wildcard path share the global bucket in both modes.
+- `warlock generate.module` list controllers validate their query (`page`, `limit`) with a schema and pass `request.validated()` to the list service instead of `request.all()`; the web starter's contact route is registered with `public: true`.
+- React module-resolution regressions preserve the ESM package boundary in isolated fixtures and report child-process stderr before checking output, so missing and broken React installations are tested correctly under Node.js 22.15.
+- The TypeScript worker configured-root regression uses the framework's real source-worker bootstrap on Node.js 22.15, retaining its declaration, update and deletion checks instead of starting an unsupported direct `.ts` worker entry. The same assertions also run against a built `.mjs` worker without loader hooks.
+- Upgrade guidance names `AgentConfig.compaction`, covers sub-agent dispatch and blank/default validation changes, and explains which routes the production rate quotas cover. In 5.31, `purgeImageVariants()` preserves legacy two-level cache files; retire them manually, correcting the earlier 5.30 cleanup suggestion.
+- Per-file image-cache purges refuse symlinked shard directories for local and object-storage disks. Stale-generation pruning now removes only recognized cache files from older generation-shaped folders, preserving current-generation files, unrelated entries, directories and symlinks.
+- The error-handling guide gives the schema-validation failure status as 422, matching the framework default, and the validation skill's introduction no longer says 400.
+- The validation skill shows the HTTP 422 body as strict JSON that can be copied into a JSON parser.
+- Image-variant purges remove only recognized cache files and retain the cache root, directories, unrelated files and symlinks. Purge and background eviction validate every shard/source/generation path component, so a cache nested inside storage cannot recursively delete uploads. Use a dedicated derivative folder.
+- Notification test fixtures roll back partially created users, tokens and rows on setup failure, attempt all cleanup operations and clear their reference before teardown. `actingAs()` refuses non-test environments before issuing credentials and revokes a newly issued blank token before rejecting it.
+- Image-variant generation and purging reject a cache directory that equals or contains any configured local storage root, including runtime-registered disks and symlink aliases. Validation happens in the shared cache-directory resolver, so `purgeImageVariants()` cannot bypass it and delete uploads through an overlapping cache setting.
+- Oxlint failures preserve stdout config errors alongside stderr warnings and bound command diagnostics without echoing file arguments. Health-worker shutdown waits briefly for child cleanup before forced termination.
+- Generator selection prompts reject an empty choices list before opening terminal input; indexed reads retain their validated bounds under stricter compiler checks.
+- Framework HTTP/2 servers start with default shutdown options and track sessions even without HTTP/1 idle-connection support. Graceful HTTP/2 drains close sessions after active streams finish without setting forbidden connection headers. SSE and stream helpers omit HTTP/1 framing headers on HTTP/2.
+- Both sse() and stream() ignore caller Content-Length, Transfer-Encoding, Content-Type, Connection, Keep-Alive, Proxy-Connection and Upgrade option headers. HTTP/1.1 retains chunked framing and reusable connections; HTTP/1.0 remains close-delimited without Transfer-Encoding.
+- Generated Vitest configuration discovers both `.test.ts` and `.spec.ts`, including notification controller specs. Existing apps should use `include: ["src/app/**/*.{test,spec}.ts"]`.
+- Source health-check workers start on Node.js 22.15 through a JavaScript bootstrap and tsx's import API; passing a `.ts` entry directly to a worker could fail before its loader hook ran. Published `.mjs` workers keep their direct startup path.
+- The cache-backed rate limiter supplies its per-window TTL on every atomic increment, so a key that expires after the create-only seed cannot be recreated without an expiry.
+- The CLI rejects unsupported Node versions with one clear message and a non-zero exit before loading the published entry or registering the source loader.
+- Image-variant cache sweeps remove writer temporaries left by a crashed write once they are an hour old, and remove a generation's `source.json` and then its empty directory (after a five-minute grace, never through a symlink) once its derivatives are gone, so object-storage generations no longer pile up when ETags change. Scheduled checks skip the cache walk while the estimate is within budget and nothing has expired; the first check after boot and one per `maxCacheAge` still walk.
+- A cache directory or disk root that cannot be resolved (`ENOTDIR`, `EACCES`, `ELOOP`) now throws `ImageVariantsConfigError`, with the original error as its `cause`, instead of the raw file-system error. The cache-overlap guard remembers its result per cache, disk root and configured local roots instead of resolving every path on each variant request; a newly registered disk is checked again.
+- Dev-server Oxlint checks no longer abort a boot scan on one over-long path: it runs in its own batch and, if the OS still refuses it, only that file is reported as unchecked. Batches count each argument's `argv` pointer on POSIX, hold at most 500 files, and a batch whose report overflows the output buffer is split and retried. Shutdown sends SIGKILL 250 ms after SIGTERM to a CLI child that ignores it, and an interrupted check reports a cancellation instead of a 30-second timeout.
+
+### Changed
+
+- `warlock dev` exits with code 1 and a clear error when it is started on Bun or Deno: the development server is Node-only. Before, it started partway and then failed in confusing ways. The error names the runtime and points to the production start commands. `warlock build` on Bun or Deno still runs, but prints a notice that only the Node build is verified.
+- A source checkout of `@warlock.js/core` run by a runtime without `module.registerHooks` now prints what is missing, instead of failing with "registerHooks is not a function".
+- Static file serving loads `@fastify/static` on the first file request instead of at boot, including existing public folders and `router.directory` mounts. The directory globber loads at boot only for `wildcard: false`. Concurrent first requests share initialization; upstream headers, ranges, listings, decorators and exact routes for `wildcard: false` are preserved.
+- Request-log privacy rules (`http.logging.private`) are prepared once per configured array instead of on every log snapshot: each string prefix is normalised a single time, and a regex rule's need for a fresh copy (global or sticky flags) is decided once. Setting a new array applies its rules; editing the existing array in place is no longer picked up. The logging docs and `configure-app` skill now also say that a route pattern containing a `%` that does not decode withholds body and query on every request to that route.
+- **BREAKING:** Node.js 22.15 or newer is required (`engines.node: ">=22.15"`): the `warlock` CLI loads TypeScript through `module.registerHooks`, which Node added in 22.15. `warlock upgrade --from 5.30 --to 5.31.0` raises the app's `engines.node`, `.nvmrc` and `.node-version` (codemod `node-22-15`).
+
+## 5.30.0 - 2026-10-16
+
+### Upgrading
+
+- **BREAKING (only for a custom log channel that reads `context.request` or `context.response`):** request log entries now carry a plain `RequestLogSnapshot` instead of the `Request`/`Response` instances. Read the fields you need from the snapshot, or call `request.toLogSnapshot()` in your own log calls. `warlock upgrade --from 5.29 --to 5.31.0` rewrites the reads that have a snapshot field and lists the rest (codemod `request-log-snapshot`).
+- **The image-variant cache moves to a new layout:** derivatives cached by 5.29 under `<cacheDirectory>/<2 hex>/<hash>.<ext>` are no longer read; each is re-rendered on its next request. Delete those old two-level files once (or call `purgeImageVariants()`) to reclaim the space.
+
+### Added
+
+- **`request.signal`**: an `AbortSignal` that aborts when the client disconnects before the response finishes (not when the request body finishes reading, never on normal completion); its listener is attached on first access and removed when the response closes.
+- **Stream backpressure**: `response.stream()`'s controller gains `write(data)` (sends, then waits until the client can take more; `false` once it is gone), `drain()`, `backpressured`, `signal` (aborted on client disconnect, not on `end()`) and `onDisconnect(fn)`, matching `response.sse()`.
+- **SSE backpressure**: `sse.write(event, data, id?)` sends and waits until the client can take more (`false` once it is gone), plus `sse.drain()`, `sse.backpressured` and `sse.signal` (aborted on disconnect).
+- **`http.serverOptions` is typed** (`HttpServerOptions`), including Node's native `http` options such as `serverOptions.http.maxHeaderSize`; it was already forwarded to Fastify but the config type could not express it.
+- **`@warlock.js/core/errors`**: a side-effect-free subpath with `HttpError` and its subclasses (`BadRequestError`, `ResourceNotFoundError`, …). A standalone helper or worker can import it without bundling Cascade, Cache or the MongoDB driver; the classes are the same ones the root exports, so `instanceof` holds across both.
+- **`http.errorMapper`**: map errors that are not an `HttpError` to `{ status, message?, payload? }` (or an `HttpError`), so domain errors shared with non-HTTP processes need not extend Core. A mapped 5xx stays opaque unless the mapper sets a message; a mapper that throws is logged and ignored.
+- **Per-route request logging policy**: `logging: { body?: boolean, query?: boolean }` on a route, with app-wide defaults under `http.logging` (plus `redactQueryParams`). It is applied before any log entry is built, so a schema- or middleware-rejected body never reaches a log channel.
+- **`request.toLogSnapshot()`**, `buildRequestLogSnapshot()` and `redactUrlCredentials()`: the bounded, plain-data view of a request that log entries now carry.
+- **`purgeImageVariants(path?, { disk? })`** removes one file's cached image derivatives, or a disk's whole derivative cache.
+- **`createUploadedFileController({ disk })`** serves the originals and variants of any local disk, and **`resolveImageVariant({ disk?, path, variant, format? })`** resolves (and renders on a miss) one variant for an app's own route, e.g. a private disk behind auth. `uploadedFileController` is `createUploadedFileController()`.
+- **Shared rate limits:** `http.rateLimit.store: "cache"` counts in `@warlock.js/cache`, so every process on a shared driver (Redis, Postgres) shares the limit; `middleware.rateLimit()` follows it or takes its own `store` and a stable `name`. A `@fastify/rate-limit` store class can be passed as `store` too. Windows are fixed and clock-aligned. Each route with its own `rateLimit` counts separately (namespaced by method and URL from the plugin's `routeInfo`, hashed so `/users/:id` and `/users/id` never merge). A cache outage fails open on both limiters (`skipOnError` defaults to `true` for this store) and is logged at most once a minute. The `null` and `file` cache drivers are refused with `UnsupportedRateLimitDriverError` (one stores nothing, the other never sweeps expired windows and does not share increments between processes).
+
+### Changed
+
+- **`response.stream()` no longer keeps rendered chunks.** `response.body` after `end()` holds the last `retainChunks` chunks written by `send()`, `write()` or `render()` (`response.stream(type, { retainChunks })`, default 0); it used to hold every `render()` chunk.
+- `response.stream()`: after the client disconnects, `send()`/`render()` are silent no-ops and `ended` is `true` (they used to write to the closed socket); `send()` after `end()` still throws.
+- **`@fastify/static` is only loaded when there is something to serve** — at least one `router.directory()`, or an existing public folder (`storage.publicRoot`, which now also accepts `false` to turn it off). Its directory-listing module calls `os.cpus()` at load, which cost a measured ~0.4–0.5 s of cold start in an app that served neither. With no public folder, `reply.sendFile` is no longer decorated by that plugin; `response.sendFile()` is unaffected.
+- `@warlock.js/core/errors` also resolves inside the framework repository (a root `errors/index.ts` re-export, not published), so workspace packages and tests can import it by its package name.
+- **`response.sse()` no longer keeps every sent event.** `response.body` after `end()` holds the last `retainEvents` events (`response.sse({ retainEvents })`, default 0), so long-lived streams no longer grow with their history.
+- **BREAKING (only for a custom log channel that reads `context.request`/`context.response`):** **request log entries carry a `RequestLogSnapshot`, not the `Request`/`Response` instances** (`context.request` is `{ id, method, url, route, name, ip, userAgent, query?, body? }`; `response.log` adds `{ statusCode }`). Native request/reply graphs no longer reach log channels, and credential-bearing query values (`secret`, `token`, `apiKey`, `signature`, `code`, `X-Amz-*`, …) are masked in the logged URL. `warlock upgrade --from 5.29 --to 5.31.0` applies the mechanical part (codemod `request-log-snapshot`).
+- **`warlock add notifications` writes a smaller, convention-following module**: `models/notification/` (model with a `NotificationResource`, migration), `resources/`, a validated `schema/list-notifications.schema.ts` (`limit` capped at 50, no `request.all()`), a guarded `types/notifications-request.type.ts`, `services/`, `utils/locales.json`, one controller per file for list / unread-count / mark-read / mark-all-read registered through `router.route()`, a commented `gate()` permission hook, and a 401 spec per controller when the app has the test feature. The clear-all and delete endpoints are no longer generated. Apps that already have a notification model (5.29 layout included) are skipped, and a freshly ejected `config/notifications.ts` then imports the 5.29 model path. In an app that already has `src/app/notifications`, no second model or migration is added, existing files are kept (and listed), and `notFound` is merged into an existing `utils/locales.json`. The mark-read controller turns a numeric `:id` into a number (integer ids on the default MongoDB stack) and keeps other ids as strings; the list query drops unknown keys such as a cache-busting `_` instead of rejecting them.
+- Image derivatives are cached per source (`<cacheDirectory>/<2 hex>/<sourceKey>/<size-mtime>/<hash>.<ext>`). Deleting or moving a file through a local disk (`delete`, `deleteMany`, `move`, and `deleteDirectory` for every file under it) removes its derivatives, and a rewritten source's old derivatives are pruned once a new one is written, so the cache no longer grows forever. Pruning re-checks the source first, so a request that read an older version never deletes the newer version's derivatives, and a derivative pruned mid-request is rendered again instead of answering 500.
+- Concurrent variant requests for the same file on two disks (a mirror copied with its mtime) no longer share one generation, which left the second target unwritten and answered 500.
+- A warning is logged once when the image-variant cache sits inside the public folder: a configured `uploads.images.cacheDirectory` is shared by every local disk, so private derivatives there would be publicly served.
+- `storage.use(name)` (and `StorageManagerContract.use`) is typed as `ScopedStorage`, the class it returns, so `deleteDirectory`, `copyDirectory`, `moveDirectory`, `emptyDirectory`, `putFromUrl`, `prepend` and `append` type-check without a cast.
+- `middleware.rateLimit()` returns an async middleware (its in-memory path still completes synchronously).
+- The `run-app` skill lists where each pnpm version reads build approvals (`allowBuilds` on 10.26+, workspace `onlyBuiltDependencies` on 10.5–10.25, `package.json` before 10.5); it used to say only `allowBuilds` works.
+
+### Fixed
+
+- Graceful shutdown no longer waits out its timeout on keep-alive connections whose request finished during the drain: in-flight responses answer `Connection: close` and connections are closed as they go idle (default `forceCloseConnections: "idle"`), so later connectors still shut down. Active responses are never cut short.
+- A `response.sse()` or `response.stream()` started after graceful shutdown began keeps the drain's `Connection: close`; its own `Connection: keep-alive` used to override it and hold `close()` until the shutdown timeout.
+- `response.sse()` removes line breaks and NUL from event names and ids, and writes a multi-line `comment()` as one comment line per line, so values built from user input cannot inject SSE fields or events.
+- An `onDisconnect` handler on `response.sse()` or `response.stream()` that throws is logged and no longer crashes the process or skips the handlers after it.
+- `warlock.config.ts` loads when it imports local TypeScript without an extension (`./src/connectors/local`) or through a tsconfig `paths` alias, on Node without native TypeScript and with native type stripping alike. The fallback bundles the config's local graph with esbuild, keeps packages external (one `BaseConnector`/container identity), runs the config once, rethrows its own errors unchanged, keeps each inlined module's `import.meta.url`, and removes its temp file.
+- `v.file()` rule methods (`maxSize`, `image`, `accept`, `mimeType`, …) return `this`, so the `UploadedFile` output type survives the chain; `saveTo()` is typed as a `string` output.
+- The dev server and the HTTP test server register module `src/app/<module>/utils/locales.json` dictionaries at boot; they were left out of the boot file set, so `t()` printed raw keys until the file was edited.
+- The HTTP test server no longer keeps Vitest's main process alive after teardown: the loader-hook `MessagePort` is unreferenced except while a version-bump flush waits for its acknowledgement.
+- A quoted config key (`"machine-thumb"`, `'single-quoted'`) is written to `.warlock/typings/config.d.ts` without its quotes, so the generated file stays valid TypeScript; computed keys are skipped, and a quoted storage driver name is no longer quoted twice. The typings manifest now records its generator version, and a manifest written by an older version is discarded, so a `config.d.ts` broken by 5.29 is regenerated on the first boot after upgrading instead of only when a config file changes.
+- The circular-dependency check no longer reports a file as importing itself because a comment mentions `import("./same-file")`: the regex fallback ignores comments and self imports are not dependency edges. Comments are found with the TypeScript parser, so a regex literal such as `/\/*$/` or `//` inside JSX text is never mistaken for one and the imports after it are kept. A pure `export type { X } from` re-export adds no dependency edge on either parsing path.
+- `warlock add web`'s `src/web/root.tsx` stub notes that `<Head />` renders the viewport tag (`metadata.viewport` changes or disables it) and does not hand-write a second one.
+- Mail logs no longer print recipient addresses: send, development, test-mode, partial-rejection and error lines show `m***@example.com`. `MailResult` and a thrown `MailError` still carry the real addresses.
+- `http.rateLimit` had no way to share counts between processes except an ioredis client, which the node-redis connection of `@warlock.js/cache` cannot provide.
+- Request log snapshots mask credential query parameters (`code`, `signature`, `sig`, `X-Amz-*`, `X-Goog-*`, the logger's secret keys and `http.logging.redactQueryParams`) in the parsed `query` too, not only in `url`; OAuth authorization codes no longer reach log lines. New `redactQueryCredentials()`.
+- `warlock.config.ts` fallback: a catch-all tsconfig `paths` pattern (`"*": ["./types/*"]`) no longer inlines packages into the config bundle; an alias is inlined only when it resolves outside `node_modules`.
+- `warlock.config.ts` fallback: `import.meta.url`/`dirname`/`filename` are replaced only where they are real expressions, so the same words inside a string or comment no longer break or alter the bundled config.
+- `warlock.config.ts` fallback runs only for the config's own unresolved relative or aliased imports (not for a package that is not installed, or a module missing inside `node_modules`), and also when native type stripping refuses the TypeScript (`ERR_UNSUPPORTED_TYPESCRIPT_SYNTAX`, `ERR_UNSUPPORTED_NODE_MODULES_TYPE_STRIPPING`). A loading error in the bundled config names `warlock.config.ts` instead of the temporary module.
+- `warlock add image` on pnpm 9 and 10.0–10.4 no longer creates a settings-only `pnpm-workspace.yaml` (`packages field missing or empty`): the sharp approval goes where the installed pnpm reads it (`package.json` `pnpm.onlyBuiltDependencies` before 10.5, the workspace's `onlyBuiltDependencies` on 10.5–10.25, `allowBuilds` from 10.26). Inside a parent pnpm workspace no per-app file is written.
+
 ## 5.29.0 - 2026-10-01
 
 ### Added
 
-- **`nullable(Resource)`**: a resource that may be `null`, accepted as a `defineResource` field and in `responseSchema` bodies. A field outputs `null` (not omitted) for null/undefined input; `ResourceOutput`/`ResponseBodyOutput` type it as `Output | null`; OpenAPI documents it as `oneOf [resource, null]`; route types emit `… | null` (FORMAI).
-- **`[Resource]` list fields in `defineResource`**: each item is mapped through the resource, `[]` stays `[]`, and the output type is an array (the same syntax `responseSchema` already accepts). Plain `Resource` fields behave as before (FORMAI).
+- **`nullable(Resource)`**: a resource that may be `null`, accepted as a `defineResource` field and in `responseSchema` bodies. A field outputs `null` (not omitted) for null/undefined input; `ResourceOutput`/`ResponseBodyOutput` type it as `Output | null`; OpenAPI documents it as `oneOf [resource, null]`; route types emit `… | null`.
+- **`[Resource]` list fields in `defineResource`**: each item is mapped through the resource, `[]` stays `[]`, and the output type is an array (the same syntax `responseSchema` already accepts). Plain `Resource` fields behave as before.
 
 ### Fixed
 
@@ -603,14 +767,14 @@ _Released in lockstep with the `@warlock.js/*` family; no package-specific chang
   verbatim and live, and its failure summary now reports whether a cause actually arrived:
   `the cause is printed above, in the application's own output` when output was seen, and
   `no output was captured from the application process — its cause did not reach this
-terminal` when none was. It previously pointed at "above" unconditionally, which on a
+  terminal` when none was. It previously pointed at "above" unconditionally, which on a
   silent child meant pointing at an empty terminal
 
 - **The HTTP connector now preflights its port before binding.** `warlock dev` and
   `warlock start` both go through `HttpConnector.start()`, which now calls
   `assertPortIsAvailable(port, host)` immediately before `listen()`. A collision now
   surfaces as `EADDRINUSE: Port <port> is already in use on <host>. Stop the dev server
-(or whatever else is listening on port <port>) and run again...` — the code and the
+  (or whatever else is listening on port <port>) and run again...` — the code and the
   port named in the same sentence — instead of a bare `EADDRINUSE` thrown from inside
   Fastify with no indication of which port it meant. `EACCES` on the port is treated
   the same way, since "cannot bind" is one problem from the operator's side. The test

package/README.md

@@ -12,36 +12,41 @@ yarn create warlock my-backend-app
 
 `@warlock.js/core` bundles the runtime primitives an application boots on:
 
-| Primitive          | What it does                                                            |
-| ------------------ | ----------------------------------------------------------------------- |
-| Application        | Boot/shutdown lifecycle, boot hooks, health & readiness endpoints       |
-| HTTP + router      | Fastify-backed server, route groups, RESTful resource routes            |
-| Middleware         | Request pipeline guards and transformers                                |
-| Storage            | Disk-contained local + remote file storage                              |
-| Repositories       | Cached query layer over Cascade models                                  |
-| Use-cases          | Composable application services with history                            |
-| Validation         | Framework validators (file, database rules) layered on `@warlock.js/seal` |
-| Mail               | Mail sending and templating                                             |
-| Cache              | Application cache facade                                                 |
-| Socket             | Real-time socket layer                                                  |
-| Dev-server         | `warlock dev` with type generation and update notices                   |
-| CLI                | `warlock` generators, migrations, and project commands                  |
+| Primitive     | What it does                                                              |
+| ------------- | ------------------------------------------------------------------------- |
+| Application   | Boot/shutdown lifecycle, boot hooks, health & readiness endpoints         |
+| HTTP + router | Fastify-backed server, route groups, RESTful resource routes              |
+| Middleware    | Request pipeline guards and transformers                                  |
+| Storage       | Disk-contained local + remote file storage                                |
+| Repositories  | Cached query layer over Cascade models                                    |
+| Use-cases     | Composable application services with history                              |
+| Validation    | Framework validators (file, database rules) layered on `@warlock.js/seal` |
+| Mail          | Mail sending and templating                                               |
+| Cache         | Application cache facade                                                  |
+| Socket        | Real-time socket layer                                                    |
+| Dev-server    | `warlock dev` with type generation and update notices                     |
+| CLI           | `warlock` generators, migrations, and project commands                    |
 
 ## Optional peer dependencies
 
 Core keeps these as **optional** peers — install a package only when you use the
 feature that needs it:
 
-| Install                                                                          | Needed for                                  |
-| -------------------------------------------------------------------------------- | ------------------------------------------- |
-| `sharp`                                                                          | image processing / resizing                 |
-| `socket.io`                                                                      | the socket layer                            |
-| `nodemailer`                                                                     | sending mail                                |
-| `@aws-sdk/client-s3` + `@aws-sdk/lib-storage` + `@aws-sdk/s3-request-presigner`  | S3 storage driver + presigned URLs          |
-| `@aws-sdk/client-sesv2`                                                          | the AWS SES mail driver                     |
-| `react` + `react-dom` + `@react-email/render`                                    | React Email templates                       |
-| `@warlock.js/herald`                                                             | the Herald message-broker connector         |
+| Install                                                                         | Needed for                          |
+| ------------------------------------------------------------------------------- | ----------------------------------- |
+| `sharp`                                                                         | image processing / resizing         |
+| `socket.io`                                                                     | the socket layer                    |
+| `nodemailer`                                                                    | sending mail                        |
+| `@aws-sdk/client-s3` + `@aws-sdk/lib-storage` + `@aws-sdk/s3-request-presigner` | S3 storage driver + presigned URLs  |
+| `@aws-sdk/client-sesv2`                                                         | the AWS SES mail driver             |
+| `react` + `react-dom` + `@react-email/render`                                   | React Email templates               |
+| `@warlock.js/herald`                                                            | the Herald message-broker connector |
 
 ## Documentation
 
 Full documentation is available at the [official documentation](https://warlock.js.org).
+
+For an application moving from 5.29, use the shipped
+[upgrade skill](skills/upgrade-from-5-29/SKILL.md). It covers logger delivery,
+tool concurrency, request-log snapshots, counters, derivative caches and viewport
+metadata, with an additional checklist for 5.31's runtime and Seal changes.

package/bin/source-load-hook.mjs

@@ -0,0 +1,63 @@
+/**
+ * The TypeScript `load` hook `bin/warlock.js` registers when `@warlock.js/core`
+ * runs from source (no `esm/` build next to the bin).
+ *
+ * It runs on Node's loader worker thread (`module.register()`), not in the
+ * main thread (`module.registerHooks()`), and that placement is the fix for a
+ * real crash, not a style choice. On Node 22.15, an in-thread `load` hook makes
+ * the ESM loader hand every imported CommonJS file its source, which puts that
+ * file in `require.cache` while the module graph is still being linked but
+ * before it has run. A CommonJS package that `require()`s the same file in
+ * that window gets its empty, unfilled `exports` object instead of the real
+ * value. Core's own graph has exactly that shape: the scheduler imports
+ * `dayjs/plugin/utc.js` and `dayjs/plugin/timezone.js`, and
+ * `@mongez/time-wizard` `require()`s both, so every booting command
+ * (`doctor`, `inspect`, `mcp`, `routes`) died in `bootstrap()` with
+ * `TypeError: t is not a function` from `dayjs.extend`. Node 26.3 does not
+ * have the defect; a worker-thread hook does not trigger it on either.
+ *
+ * Non-TypeScript URLs (npm `.js`, `node:` builtins, JSON) fall through to the
+ * next loader untouched. When the dev server registers its own loader later,
+ * that loader's hooks run before this one (later registrations run first), so
+ * it owns the TypeScript path from then on and this hook is never reached for
+ * a `.ts` file again.
+ */
+import { readFileSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+import { transformSync } from "esbuild";
+
+const TS_FILE = /\.(ts|tsx|mts|cts)$/;
+const VERSION_QUERY = /\?v=\d+$/;
+
+/** Set by `initialize()` from the `data` the bin passes to `register()`. */
+let transpileOptions = { target: "node22", tsconfigRaw: "{}" };
+
+/**
+ * Receive the transpile options from the main thread.
+ *
+ * @param {{ target: string, tsconfigRaw: string }} data
+ */
+export function initialize(data) {
+  transpileOptions = data;
+}
+
+/**
+ * Transpile TypeScript with esbuild; pass everything else down the chain.
+ */
+export async function load(url, context, nextLoad) {
+  const cleanUrl = url.replace(VERSION_QUERY, "");
+
+  if (!TS_FILE.test(cleanUrl)) return nextLoad(url, context);
+
+  const absolutePath = fileURLToPath(cleanUrl);
+  const { code } = transformSync(readFileSync(absolutePath, "utf8"), {
+    loader: absolutePath.endsWith(".tsx") ? "tsx" : "ts",
+    format: "esm",
+    target: transpileOptions.target,
+    sourcefile: absolutePath,
+    sourcemap: "inline",
+    tsconfigRaw: transpileOptions.tsconfigRaw,
+  });
+
+  return { format: "module", source: code, shortCircuit: true };
+}

package/bin/warlock.js

@@ -4,6 +4,41 @@ import { existsSync } from "node:fs";
 import path from "node:path";
 import { fileURLToPath, pathToFileURL } from "node:url";
 
+const [nodeMajor, nodeMinor] = process.versions.node.split(".").map(Number);
+if (nodeMajor < 22 || (nodeMajor === 22 && nodeMinor < 15)) {
+  console.error(`[warlock] requires Node 22.15 or newer (running ${process.versions.node}).`);
+  process.exit(1);
+}
+
+// Bun and Deno report the Node version they emulate in `process.versions.node`
+// and add their own entry, so the check above passes on both. `warlock dev` is
+// the one command that cannot run there (it is built on Node's module loader
+// hooks), and it is refused here, before anything loads, so the refusal reads
+// the same whether the CLI runs from published output or from source. The
+// `dev` command repeats this check for callers that bypass this file.
+const foreignRuntimeName = process.versions.bun
+  ? "Bun"
+  : process.versions.deno
+    ? "Deno"
+    : undefined;
+
+if (foreignRuntimeName && process.argv[2] === "dev") {
+  const foreignRuntime = `${foreignRuntimeName} ${process.versions.bun ?? process.versions.deno}`;
+  const start = process.versions.bun ? "bun dist/app.js" : "deno run -A dist/app.js";
+
+  console.error(
+    [
+      `✖ warlock dev runs on Node.js only — this process is ${foreignRuntime}.`,
+      "  The development server compiles TypeScript and hot-reloads modules through Node's module loader hooks.",
+      "  Run it with Node.js 22.15 or newer: npx warlock dev",
+      `  ${foreignRuntimeName} can run the production build: build it with Node (npx warlock build),`,
+      `  then start it with ${start}.`,
+      "  Supported runtimes: https://warlock.js.org/v/latest/core/digging-deeper/supported-runtimes/",
+    ].join("\n"),
+  );
+  process.exit(1);
+}
+
 const binDir = path.dirname(fileURLToPath(import.meta.url));
 
 /**
@@ -49,8 +84,19 @@ async function bootFromSource() {
   }
 
   const { registerHooks } = await import("node:module");
-  const { readFileSync } = await import("node:fs");
-  const { transformSync } = await import("esbuild");
+
+  // Bun has no `module.registerHooks`. Only a source checkout reaches this
+  // path (published packages ship compiled output), so say what is missing
+  // instead of failing on "registerHooks is not a function".
+  if (typeof registerHooks !== "function") {
+    console.error(
+      "[warlock] Running @warlock.js/core from TypeScript source needs Node's module.registerHooks " +
+        "(Node 22.15 or newer); this runtime does not provide it. Use Node, or install the published package.",
+    );
+    process.exit(1);
+  }
+
+  const { register } = await import("node:module");
   const { getTsconfig, resolvePathAlias } = await import("get-tsconfig");
 
   // Same target the dev loader and the production builder pin, so a file
@@ -58,8 +104,6 @@ async function bootFromSource() {
   // get anywhere else in the toolchain. Drifting from it would make the CLI a
   // third, subtly different dialect.
   const TRANSPILE_TARGET = "node22";
-  const TS_FILE = /\.(ts|tsx|mts|cts)$/;
-  const VERSION_QUERY = /\?v=\d+$/;
 
   // Read from cwd, not from core: `jsx`, `experimentalDecorators` and friends
   // are the *app's* call, and this is the same source of truth the dev
@@ -70,59 +114,44 @@ async function bootFromSource() {
   });
 
   /**
-   * Handover switch. Verified behaviour: in-thread hooks run *before*
-   * `register()` worker hooks and delegate down the chain. So once the dev
-   * server registers its own loader, these hooks would still intercept every
-   * `.ts` first and short-circuit — silently bypassing the dev loader's
-   * transpile cache and, worse, its `?v=N` HMR stamping.
+   * Handover switch for the in-thread `resolve` hook below. Verified
+   * behaviour: in-thread hooks run *before* `register()` worker hooks and
+   * delegate down the chain, so once the dev server registers its own loader
+   * this hook would still resolve every `.ts` first and short-circuit,
+   * bypassing the dev loader's `?v=N` HMR stamping.
    *
-   * Setting `active = false` makes both hooks pure pass-throughs, handing the
-   * TypeScript path over intact. `registerLoader()` should flip it just before
-   * it calls `register()`; until it does, these hooks stay in charge, which is
-   * the correct default for every non-dev command.
+   * Setting `active = false` makes it a pure pass-through. `registerLoader()`
+   * should flip it just before it calls `register()`; until it does, this
+   * hook stays in charge, which is the correct default for every non-dev
+   * command. (The `load` hook needs no switch: it is a worker hook, and the
+   * dev loader's worker hooks, registered later, run before it.)
    */
   const bootstrapLoader = { active: true };
   globalThis.__warlockBootstrapLoader = bootstrapLoader;
 
   /**
-   * `load` hook. In-thread (`registerHooks`) rather than the worker-thread
-   * `register()`, which is what lets stage 2 below exist at all: a worker hook
-   * could not hand a transpiled function back to this thread.
+   * `load` hook — transpiles TypeScript with esbuild. It runs on Node's
+   * loader worker thread (`register()`), NOT in this thread
+   * (`registerHooks()`): on Node 22.15 an in-thread `load` hook makes a
+   * CommonJS package that `require()`s a file which an ES module also imports
+   * receive that file's empty, not-yet-run `exports`, which crashed every
+   * booting command inside `dayjs.extend`. See `source-load-hook.mjs`.
    */
-  function load(url, context, nextLoad) {
-    const cleanUrl = url.replace(VERSION_QUERY, "");
-
-    // Not TypeScript → not ours. npm `.js`, `node:`, JSON all fall through.
-    if (!bootstrapLoader.active || !TS_FILE.test(cleanUrl)) return nextLoad(url, context);
-
-    const absolutePath = fileURLToPath(cleanUrl);
-    const { code } = transformSync(readFileSync(absolutePath, "utf8"), {
-      loader: absolutePath.endsWith(".tsx") ? "tsx" : "ts",
-      format: "esm",
-      target: TRANSPILE_TARGET,
-      sourcefile: absolutePath,
-      sourcemap: "inline",
-      tsconfigRaw,
-    });
-
-    return { format: "module", source: code, shortCircuit: true };
-  }
-
-  registerHooks({ load });
+  register(pathToFileURL(path.join(binDir, "source-load-hook.mjs")).href, {
+    data: { target: TRANSPILE_TARGET, tsconfigRaw },
+  });
 
   // Stage 2 — the reuse. With `load` live, core's own resolver can be pulled
   // in as TypeScript. It is imported by exact absolute path on purpose: it is
   // a leaf module whose only import is `node:url`, so it needs no extension
   // probing to load, which is precisely the thing we don't have yet.
-  const { ownResolve } = await import(
-    pathToFileURL(
-      path.join(binDir, "..", "src", "dev-server", "loader", "own-resolver.ts"),
-    ).href
+  const { ownResolve, probeFile } = await import(
+    pathToFileURL(path.join(binDir, "..", "src", "dev-server", "loader", "own-resolver.ts")).href
   );
 
   let pathsMatcher = null;
   if (tsconfig) {
-    pathsMatcher = specifier => resolvePathAlias(tsconfig, specifier);
+    pathsMatcher = (specifier) => resolvePathAlias(tsconfig, specifier);
   }
 
   /**
@@ -131,6 +160,14 @@ async function bootFromSource() {
    * `null` for (bare npm, `node:`, `file:`) falls through to Node's default,
    * which keeps `exports`/`node_modules` semantics intact.
    *
+   * One fallback on top: a bare subpath of a package consumed as source, such
+   * as `@warlock.js/core/net` (imported by `@warlock.js/ai`). Core declares no
+   * `exports` map in source form, so Node's default resolver lands on the
+   * `net/` directory and refuses it (`ERR_UNSUPPORTED_DIR_IMPORT`); the
+   * published package maps the subpath to its built entry instead. The
+   * directory's `index.ts` is what TypeScript and vitest resolve the same
+   * specifier to, so that is what this resolves it to as well.
+   *
    * The dev loader's version of this also stamps `?v=N` for HMR. That is
    * deliberately absent: the CLI process has no watcher, and the dev server
    * registers its own full loader when it boots.
@@ -143,7 +180,30 @@ async function bootFromSource() {
     // Producing the URL ourselves means `nextResolve` was never called, so the
     // chain has to be short-circuited explicitly or Node raises
     // ERR_LOADER_CHAIN_INCOMPLETE.
-    return owned ? { url: owned, shortCircuit: true } : nextResolve(specifier, context);
+    if (owned) return { url: owned, shortCircuit: true };
+
+    try {
+      return nextResolve(specifier, context);
+    } catch (error) {
+      const index = bootstrapLoader.active ? directoryIndexOf(error) : null;
+
+      if (index) return { url: index, shortCircuit: true };
+
+      throw error;
+    }
+  }
+
+  /**
+   * The `index.ts` (or `.tsx`/`.js`/`.jsx`) inside the directory Node refused
+   * to import, as a `file:` URL, or `null` when the error is anything else.
+   */
+  function directoryIndexOf(error) {
+    if (error?.code !== "ERR_UNSUPPORTED_DIR_IMPORT" || typeof error.url !== "string") return null;
+
+    const directory = fileURLToPath(error.url).replace(/\\/g, "/").replace(/\/$/, "");
+    const hit = probeFile(`${directory}/index`, existsSync);
+
+    return hit ? pathToFileURL(hit).href : null;
   }
 
   registerHooks({ resolve });

package/esm/application/app.d.mts

@@ -3,7 +3,7 @@ import { DataSource } from "@warlock.js/cascade";
 import { FastifyInstance } from "fastify";
 import { Server } from "socket.io";
 
-//#region ../core/src/application/app.d.ts
+//#region ../../packages/core/src/application/app.d.ts
 type RuntimeApplication = {
   socket: Server | undefined;
   http: FastifyInstance | undefined;

package/esm/application/app.d.mts.map

@@ -1 +1 @@
-{"version":3,"file":"app.d.mts","names":[],"sources":["../../../../../../../core/src/application/app.ts"],"mappings":";;;;;;KAMK,kBAAA;EACH,MAAA,EAAQ,MAAA;EACR,IAAA,EAAM,eAAA;EACN,MAAA,EAAQ,MAAA;EACR,QAAA,EAAU,UAAA;AAAA;AAAA,cAGC,GAAA,EAAK,kBAkCjB"}
+{"version":3,"file":"app.d.mts","names":[],"sources":["../../../../../../../../packages/core/src/application/app.ts"],"mappings":";;;;;;KAMK,kBAAA;EACH,MAAA,EAAQ,MAAA;EACR,IAAA,EAAM,eAAA;EACN,MAAA,EAAQ,MAAA;EACR,QAAA,EAAU,UAAA;AAAA;AAAA,cAGC,GAAA,EAAK,kBAkCjB"}