@warlock.js/core 4.15.0 → 5.0.0

package/esm/warlock-config/normalize-build-config.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"normalize-build-config.mjs","names":[],"sources":["../../../../../../../core/src/warlock-config/normalize-build-config.ts"],"sourcesContent":["import type { WarlockConfig } from \"./types\";\n\ntype BuildConfig = NonNullable<WarlockConfig[\"build\"]>;\n\n/**\n * Fold the `outDirectory` alias into the canonical `outdir`.\n *\n * `outDirectory` is the name the documentation used for several releases\n * while the code only ever read `outdir`, so a config written from the docs\n * was silently ignored and the bundle still landed in `dist/`. Accepting both\n * keeps those configs working; `outdir` wins when both are set, since that is\n * the name esbuild uses and the one we tell people to prefer.\n *\n * Returns the input untouched when there is nothing to fold, so the common\n * case allocates nothing.\n */\nexport function normalizeBuildConfig<T extends BuildConfig>(build: T): T {\n  if (!build.outDirectory || build.outdir) {\n    return build;\n  }\n\n  return { ...build, outdir: build.outDirectory };\n}\n"],"mappings":";;;;;;;;;;;;;AAgBA,SAAgB,qBAA4C,OAAa;CACvE,IAAI,CAAC,MAAM,gBAAgB,MAAM,QAC/B,OAAO;CAGT,OAAO;EAAE,GAAG;EAAO,QAAQ,MAAM;CAAa;AAChD"}
+{"version":3,"file":"normalize-build-config.mjs","names":[],"sources":["../../../../../../../core/src/warlock-config/normalize-build-config.ts"],"sourcesContent":["import type { WarlockConfig } from \"./types\";\n\ntype BuildConfig = NonNullable<WarlockConfig[\"build\"]>;\n\n/**\n * Fold the `outDirectory` alias into the canonical `outdir`.\n *\n * `outDirectory` is the name the documentation used for several releases\n * while the code only ever read `outdir`, so a config written from the docs\n * was silently ignored and the bundle still landed in `dist/`. Accepting both\n * keeps those configs working; `outdir` wins when both are set, since that is\n * the name esbuild uses and the one we tell people to prefer.\n *\n * Returns the input untouched when there is nothing to fold, so the common\n * case allocates nothing.\n */\nexport function normalizeBuildConfig<T extends BuildConfig>(\n  build: T,\n): T & Pick<BuildConfig, \"outdir\"> {\n  if (!build.outDirectory || build.outdir) {\n    return build;\n  }\n\n  return { ...build, outdir: build.outDirectory };\n}\n"],"mappings":";;;;;;;;;;;;;AAgBA,SAAgB,qBACd,OACiC;CACjC,IAAI,CAAC,MAAM,gBAAgB,MAAM,QAC/B,OAAO;CAGT,OAAO;EAAE,GAAG;EAAO,QAAQ,MAAM;CAAa;AAChD"}

package/esm/warlock-config/types.d.mts

@@ -1,5 +1,6 @@
-import { CLICommand } from "../commands/cli-command.mjs";
 import { FileHealthCheckerContract } from "../dev-server/health-checker/file-health-checker.contract.mjs";
+import { Connector } from "../connectors/types.mjs";
+import { CLICommand } from "../commands/cli-command.mjs";
 import { MigrationConstructor } from "@warlock.js/cascade";
 import { BuildOptions } from "esbuild";
 
@@ -20,8 +21,16 @@ type WarlockConfig = {
   };
   /**
    * Build configuration
+   *
+   * `tsconfig` and `tsconfigRaw` are deliberately omitted alongside
+   * `entryPoints`. Either one applies the app's compiler options to EVERY
+   * file esbuild touches, workspace packages included — so an app-level
+   * `verbatimModuleSyntax: true` is imposed on package sources that were
+   * never written for it, and the bundle dies at import time with
+   * `Class extends value undefined`. The builder derives what it needs from
+   * the app's tsconfig itself (see `buildAliasMapFromTsconfig`).
    */
-  build?: Omit<BuildOptions, 'entryPoints'> & {
+  build?: Omit<BuildOptions, "entryPoints" | "tsconfig" | "tsconfigRaw"> & {
     /**
      * Output directory
      *
@@ -91,6 +100,31 @@ type WarlockConfig = {
      */
     sourcemap?: boolean | "inline" | "linked";
   };
+  /**
+   * Connectors this application adds beyond the built-in ones.
+   *
+   * ONE key drives both halves of a connector's life:
+   *
+   * - `warlock build` reads this array STATICALLY and drains each
+   *   connector's `build` contribution. It never calls `boot()`/`start()` —
+   *   listing a connector here does not run it.
+   * - `warlock dev` and the generated production entry register the same
+   *   array with the connectors manager, which is what actually boots it.
+   *
+   * A second key ("built for X" beside "boots X") was rejected precisely
+   * because the two would drift, and that drift is silent: a green build
+   * with no client bundle.
+   *
+   * @example
+   * ```typescript
+   * import { webConnector } from "@warlock.js/web/connector";
+   *
+   * export default defineConfig({
+   *   connectors: [webConnector({ pagesDirectory: "pages" })],
+   * });
+   * ```
+   */
+  connectors?: Connector[];
   /**
    * CLI configuration
    */

package/esm/warlock-config/types.d.mts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.mts","names":[],"sources":["../../../../../../../core/src/warlock-config/types.ts"],"mappings":";;;;;;;;AAUA;;;KAAY,aAAA;EAaF;;;EATR,MAAA;IACE,IAAA;IACA,IAAA;IACA,cAAA;EAAA;EAFA;;;EAQF,KAAA,GAAQ,IAAA,CAAK,YAAA;IAAL;;;;;IAMN,MAAA;IAkDA;;;;;;;;;;IAvCA,YAAA;IAqFiB;;;;;IA/EjB,OAAA;IAwIA;;;;;;;AAuBO;;;;;;;;;IA9IP,YAAA;;;;;;;;;;;;;;;;IAgBA,OAAA;;;;;;IAMA,MAAA;;;;;;IAMA,SAAA;EAAA;;;;EAMF,GAAA;IACE,QAAA,GAAW,UAAA;EAAA;;;;EAMb,SAAA;;;;IAIE,KAAA;;;;;;MAME,OAAA;;;;;;MAMA,OAAA;IAAA;;;;IAKF,cAAA,GAAiB,yBAAA;;;;;IAKjB,eAAA;;;;;;;;;IASA,eAAA;;;;;;;;;IASA,qBAAA;;;;;;;;;;IAUA,mBAAA;EAAA;;;;EAMF,QAAA;;;;;;;;;;;;;;;;;;IAkBE,UAAA,GAAa,KAAA,CAAM,oBAAA;EAAA;;;;;;;EASrB,OAAA;;;;;;;IAOE,OAAA;;;;;;IAOA,OAAA;EAAA;AAAA"}
+{"version":3,"file":"types.d.mts","names":[],"sources":["../../../../../../../core/src/warlock-config/types.ts"],"mappings":";;;;;;;;;AAWA;;;KAAY,aAAA;EAqBF;;;EAjBR,MAAA;IACE,IAAA;IACA,IAAA;IACA,cAAA;EAAA;EAHF;;;;;;;;;;;EAiBA,KAAA,GAAQ,IAAA,CAAK,YAAA;IA8DX;;;;;IAxDA,MAAA;IA+FW;;;;;;;;;;IApFX,YAAA;IAsJF;;;;;IAhJE,OAAA;IAyLA;;AAAO;;;;;;;;;;;;;;IAxKP,YAAA;;;;;;;;;;;;;;;;IAgBA,OAAA;;;;;;IAMA,MAAA;;;;;;IAMA,SAAA;EAAA;;;;;;;;;;;;;;;;;;;;;;;;;EA2BF,UAAA,GAAa,SAAA;;;;EAKb,GAAA;IACE,QAAA,GAAW,UAAA;EAAA;;;;EAMb,SAAA;;;;IAIE,KAAA;;;;;;MAME,OAAA;;;;;;MAMA,OAAA;IAAA;;;;IAKF,cAAA,GAAiB,yBAAA;;;;;IAKjB,eAAA;;;;;;;;;IASA,eAAA;;;;;;;;;IASA,qBAAA;;;;;;;;;;IAUA,mBAAA;EAAA;;;;EAMF,QAAA;;;;;;;;;;;;;;;;;;IAkBE,UAAA,GAAa,KAAA,CAAM,oBAAA;EAAA;;;;;;;EASrB,OAAA;;;;;;;IAOE,OAAA;;;;;;IAOA,OAAA;EAAA;AAAA"}

package/llms-full.txt

@@ -4692,7 +4692,7 @@ export default defineConfig({
   plugins: [lowerStage3Decorators(), mongezVite()],
   test: {
     globalSetup: "./src/test-global-setup.ts",  // ← starts the HTTP server
-    setupFiles: ["./src/test-setup.ts"],         // ← per-worker setupTest (see test-service skill)
+    setupFiles: ["./src/test-setup.ts"],         // ← setupTest + afterAll(teardownTest), per test file
     environment: "node",
     globals: false,
     include: ["src/app/**/*.test.ts"],
@@ -4700,7 +4700,13 @@ export default defineConfig({
 });
 ```
 
-Both files (and this config, with `lowerStage3Decorators()` first so decorated models load) are created by `warlock add test`. The split is intentional: `globalSetup` runs ONCE in the main vitest process; `setupFiles` runs per worker thread.
+Both files (and this config, with `lowerStage3Decorators()` first so decorated models load) are created by `warlock add test`. The split is intentional: `globalSetup` runs **ONCE** in the main vitest process; `setupFiles` runs **before every test file**.
+
+⚠ **Corrected in 4.14.0.** This line previously said `setupFiles` runs "per worker thread". **It does not** — Vitest runs it before each test file, and the setup module's registry is rebuilt every time. Measured across all four `pool` × `isolate` combinations.
+
+**So the service-layer framework is file-scoped: bootstrapped by `setupTest` and closed by the `afterAll(teardownTest)` the setup file registers, once per test file.** ⚠ **`setupTest` alone is not the whole wiring — the paired teardown is mandatory from 4.14.0**; see the `test-service` skill.
+
+**HTTP is the exception and stays in `globalSetup`**, which genuinely does run once in the main vitest process and owns a real port. **That split is the point:** one server for the whole run, one framework per test file.
 
 ## HTTP request helpers
 
@@ -4901,14 +4907,22 @@ This is fine for normal test flow. It bites when you're inside a transaction the
 
 ---
 name: test-service
-description: 'Pure unit tests against services, repositories, models, and use-cases — `setupTest({ connectors })` bootstraps each Vitest worker with its own DB/cache connections so you can call your code directly. Triggers: `setupTest`, `src/test-setup.ts`, `tests.connectors`, `Application.setEnvironment`; "unit-test a service", "test a repository query", "vitest setupFiles", "skip connectors for pure-logic tests"; typical import `import { setupTest } from "@warlock.js/core/tests"`. Skip: HTTP integration — `@warlock.js/core/test-http/SKILL.md`; warlock add test scaffold — `@warlock.js/core/write-cli-command/SKILL.md`; competing tooling: jest direct, `supertest`, `nock`.'
+description: 'Pure unit tests against services, repositories, models, and use-cases — `setupTest({ connectors })` bootstraps the framework with its own DB/cache connections so you can call your code directly, and `teardownTest()` closes it. Triggers: `setupTest`, `teardownTest`, `src/test-setup.ts`, `tests.connectors`, `tests.setupTimeout`, `Application.setEnvironment`; "unit-test a service", "test a repository query", "vitest setupFiles", "skip connectors for pure-logic tests"; typical import `import { setupTest, teardownTest } from "@warlock.js/core/tests"`. Skip: HTTP integration — `@warlock.js/core/test-http/SKILL.md`; warlock add test scaffold — `@warlock.js/core/write-cli-command/SKILL.md`; competing tooling: jest direct, `supertest`, `nock`.'
 ---
 
 # Warlock — test a service
 
-For unit tests, you import the thing under test and call it directly. No HTTP, no fetch, no controllers. Framework testing in Warlock is about getting your **service layer** under test efficiently — and that means each Vitest worker needs its own bootstrapped framework with a DB connection.
+For unit tests, you import the thing under test and call it directly. No HTTP, no fetch, no controllers. Framework testing in Warlock is about getting your **service layer** under test efficiently — and that means your tests need a bootstrapped framework with a DB connection.
+
+`setupTest()` is the one-call bootstrap that provides that environment; `teardownTest()` closes it.
+
+⚠ **Corrected in 4.14.0 — `setupTest` is CALLED once per TEST FILE, not once per worker.** Every version of this skill through 4.13.0 said "per worker", the generated `src/test-setup.ts` carries a `Per-Worker Test Setup` comment saying the same thing, and **both were wrong.** Vitest runs `setupFiles` before **each test file**, and the setup module's registry is rebuilt every time — measured across all four `pool` × `isolate` combinations.
 
-`setupTest()` is the one-call bootstrap that gives each worker that environment.
+⛔ **If your project was generated before 4.14.0, fix BOTH the comment and the call.** The comment is false, **and** the generated `setupTest({ connectors: true })` is now an *explicit* value that overrides your `src/config/tests.ts`. **Bare `setupTest()` is the correct call.**
+
+**The lifetime is FILE-SCOPED, on purpose.** Your setup file bootstraps the framework and its `afterAll(teardownTest)` closes it, once per test file. **One owner, one pairing — correct under every pool, every isolation setting, and watch mode.**
+
+⚠ **A worker-scoped lifetime is possible and is deliberately not shipped yet.** Lifecycle state now lives in the worker runtime, so leaving the framework running would let every file in a worker share one bootstrap. Two things block claiming it: under `pool: "threads"` we cannot observe whether Node reclaims a torn-down thread's sockets and pools, and **in watch mode Vitest reuses workers between reruns, so there is no recycle and no cleanup owner.** It gets taken when the real cost is measured and the integration is chosen, not inherited. See *Lifecycle and repeated calls* below.
 
 ⚠ **Changed in 4.13.0 — the import is a subpath now.** `setupTest` used to be re-exported from the package root; it is not any more, because that put the test helpers into every application's production module graph. `import { setupTest } from "@warlock.js/core"` now fails with *"has no exported member"* — **add `/tests` to the specifier and nothing else changes.**
 
@@ -4935,9 +4949,9 @@ describe("registerUserService", () => {
 });
 ```
 
-No `beforeAll(setupTest)` in this file — the project's `src/test-setup.ts` (registered as `setupFiles` in `vite.config.ts`) already ran it once per worker before any test executed.
+No `beforeAll(setupTest)` in this file — the project's `src/test-setup.ts` (registered as `setupFiles` in `vite.config.ts`) already ran it **before this file's tests executed**, as it does before every test file.
 
-## `setupTest({ connectors })` — the worker bootstrap
+## `setupTest({ connectors })` — the bootstrap
 
 ```ts
 import { setupTest } from "@warlock.js/core/tests";
@@ -4952,10 +4966,10 @@ What it does (in order):
 3. Runs `bootstrap()` — env, app, prestart hooks.
 4. Initializes the `filesOrchestrator` (module/route/config discovery, no file watching).
 5. Loads all `src/config/*.ts` files.
-6. Reads `tests.connectors` from config (overrides the parameter if set).
+6. Resolves the connector selection — **an explicit parameter wins, then `tests.connectors` from config, then the `true` default.** See *Selecting connectors* below.
 7. Starts the chosen connectors — but **never `http`** when you pass a boolean. HTTP is the global-setup's job.
 
-The result: each worker has its own DB/cache/logger/storage connections. Models save, repositories query, services run. Same code as production, just isolated to the test process.
+The result: DB/cache/logger/storage connections your code can use. Models save, repositories query, services run. Same code as production, just isolated to the test process.
 
 ### The `connectors` parameter
 
@@ -4965,9 +4979,9 @@ The result: each worker has its own DB/cache/logger/storage connections. Models
 | `false`                | None                                                             | Pure logic tests with no DB / cache touches (parsers, validators, util functions). |
 | `["database", "cache"]` | Just those, in that order                                        | A test that only needs DB but not, say, the storage driver. |
 
-The default `true` is the sane choice. Reach for `false` when the unit you're testing genuinely doesn't talk to any framework subsystem — pulling up a DB connection per worker just to test a string parser is wasted setup time.
+The default `true` is the sane choice. Reach for `false` when the unit you're testing genuinely doesn't talk to any framework subsystem — pulling up a DB connection **for every file** just to test a string parser is wasted setup time.
 
-### Override via config — `src/config/tests.ts`
+### Selecting connectors — `src/config/tests.ts`
 
 ```ts title="src/config/tests.ts"
 const testsConfigurations = {
@@ -4977,7 +4991,33 @@ const testsConfigurations = {
 export default testsConfigurations;
 ```
 
-If `tests.connectors` is set, **it wins over the `setupTest({ connectors })` parameter**. Use this when every test file in the project agrees on the same minimal connector list — saves repeating the explicit array in `test-setup.ts`.
+⚠ **BREAKING in 4.14.0 — the precedence flipped.**
+
+| | Order |
+|---|---|
+| **4.13.0 and earlier** | `tests.connectors` config **>** `setupTest({ connectors })` parameter **>** `true` |
+| **4.14.0 onward** | **explicit `setupTest({ connectors })` parameter** **>** `tests.connectors` config **>** `true` |
+
+**An explicit call-site value now beats project config.** If your project sets `tests.connectors` *and* some test file passes `connectors` explicitly, **that file will start a different connector set after upgrading.** Search for `setupTest({` across your tests before you upgrade — a call passing `connectors` was previously ignored and is now honoured.
+
+**"Explicit" means you supplied a non-`undefined` value.** Both of these fall through to config:
+
+```ts
+await setupTest();                       // → tests.connectors, else true
+await setupTest({});                     // → tests.connectors, else true
+await setupTest({ connectors: undefined }); // → tests.connectors, else true — NOT "start none"
+```
+
+The `undefined` rule is deliberate: an optional variable that happens to be `undefined` must not silently erase your project config.
+
+```ts
+await setupTest({ connectors: false });        // → none, even if config says otherwise
+await setupTest({ connectors: ["database"] }); // → exactly that, even if config differs
+```
+
+⚠ **The generated `src/test-setup.ts` calls `setupTest()` with no argument, on purpose.** If you "helpfully" change it to `setupTest({ connectors: true })`, you have made it explicit and **erased the `tests.connectors` layer for the whole project.**
+
+Use `tests.connectors` when every test file agrees on the same minimal list — it saves repeating the array, and individual files can still override it.
 
 ## Project wiring — `src/test-setup.ts` + `vite.config.ts`
 
@@ -4985,14 +5025,22 @@ The `warlock add test` feature creates both files. The standard wiring:
 
 ```ts title="src/test-setup.ts"
 /**
- * Per-Worker Test Setup
- * Runs in EACH Vitest worker thread before tests execute.
+ * Test Setup
+ * Runs before EACH test file — not once per worker.
  */
-import { setupTest } from "@warlock.js/core/tests";
+import { afterAll } from "vitest";
+import { setupTest, teardownTest } from "@warlock.js/core/tests";
 
-await setupTest({ connectors: true });
+await setupTest();
+afterAll(teardownTest);
 ```
 
+⛔ **Three things changed here in 4.14.0. If you generated this file earlier, replace all three — it is not a comment fix.**
+
+1. **`afterAll(teardownTest)` is new and mandatory.** Nothing else closes the framework your tests started. This is what makes the lifetime file-scoped and owned rather than left running.
+2. **The call is now bare `setupTest()`, not `setupTest({ connectors: true })`.** Under the flipped precedence, passing `true` is an *explicit* value and would override `tests.connectors` for **every file in the project.** Bare means "whatever this project configured, else the default".
+3. **The comment used to say `Per-Worker Test Setup` / "Runs in EACH Vitest worker thread".** False — see the top of this skill.
+
 ```ts title="vite.config.ts"
 import { lowerStage3Decorators } from "@warlock.js/core/vite";
 import mongezVite from "@mongez/vite";
@@ -5002,7 +5050,7 @@ export default defineConfig({
   plugins: [lowerStage3Decorators(), mongezVite()],
   test: {
     globalSetup: "./src/test-global-setup.ts",  // ← HTTP server (see test-http skill)
-    setupFiles: ["./src/test-setup.ts"],         // ← runs setupTest per worker
+    setupFiles: ["./src/test-setup.ts"],         // ← runs setupTest before EACH test file
     environment: "node",
     globals: false,
     include: ["src/app/**/*.test.ts"],
@@ -5107,7 +5155,9 @@ afterEach(async () => {
 });
 ```
 
-Vitest runs tests in a single worker file sequentially, so an `afterEach` truncate gives each test a clean slate. For cross-file isolation, run the suite with `vitest --pool=forks --maxWorkers=N` and rely on the per-worker connection — each file's data stays within its worker until the run ends.
+Vitest runs the tests within one file sequentially, so an `afterEach` truncate gives each test a clean slate.
+
+⚠ **Cross-*file* isolation is not solved by this.** Separate workers get separate **connections**, not separate **rows** — two files pointed at the same database see each other's committed data regardless of pool or worker count. **Truncate what your file wrote; don't assume the worker boundary did it for you.** Real data isolation (DB-per-worker, transaction-per-test) is a separate piece of work and is not in this release.
 
 ### Skipping connectors for pure logic tests
 
@@ -5127,14 +5177,109 @@ describe("slugify", () => {
 });
 ```
 
-`setupTest` is idempotent per worker (`isSetupComplete` flag) — calling it again with different options after `src/test-setup.ts` already ran is a no-op. **That includes a `connectors: false` call: if `src/test-setup.ts` already ran `setupTest()` in this worker, the example above changes nothing.** To genuinely skip connectors, either set `tests.connectors: false` in config (project-wide) or rely on the default in `src/test-setup.ts` being what you want most of the time.
+⛔ **BREAKING in 4.14.0 — the example above now REJECTS if your project has a `src/test-setup.ts`.**
+
+Through 4.13.0 a second `setupTest` call with different options was a **silent no-op** — you asked for no connectors, got all of them, and nothing told you. In 4.14.0 a conflicting call **rejects with an error naming both the active and the requested selection**, because silently ignoring what you asked for is worse than failing.
+
+**If `src/test-setup.ts` already ran `setupTest()` in this file, use one of these instead:**
+
+```ts
+// 1. Tear down first, then set up differently — and PUT IT BACK when the file ends.
+import { afterAll, beforeAll } from "vitest";
+import { setupTest, teardownTest } from "@warlock.js/core/tests";
+
+beforeAll(async () => {
+  await teardownTest();
+  await setupTest({ connectors: false });
+});
+
+afterAll(async () => {
+  await teardownTest();      // ← REQUIRED, see below
+});
+```
+
+⛔ **The `afterAll` is not optional** — without it you leave a `connectors: false` runtime ready when the file ends.
 
-⚠ **Config beats the parameter.** If `tests.connectors` is set at all, `setupTest({ connectors })` cannot override it — the config value wins. That is the current contract, not an accident; a per-call override is under discussion for a later release.
+⚠ **This pattern interacts with the `afterAll(teardownTest)` in your setup file, and the relative ordering of the two has not been verified.** `teardownTest` is idempotent, so whichever runs second finds an idle lifecycle and no-ops — but **do not build anything on a particular order until someone has measured it.** This is the strongest argument for option 2 below.
+
+```ts
+// 2. Or don't call setupTest at all — a pure-logic test needs nothing from it.
+//    The connectors your setup file started are already running; you simply don't use them.
+```
+
+**3. Or set `tests.connectors: false` in `src/config/tests.ts`** if no test file in the project needs connectors.
+
+**Option 2 is usually right, and option 1 is easy to get wrong.** Tearing down and re-bootstrapping costs a full framework startup — twice, once for your file and once for the next — to avoid a DB connection you were never going to use. **Reach for option 1 only when a connector's mere presence breaks the thing you're testing**, not to save setup time.
+
+## Lifecycle and repeated calls
+
+`setupTest` / `teardownTest` are a pair. **The harness that calls one owns calling the other in the same context.**
+
+| Call | Behaviour |
+|---|---|
+| `setupTest(x)` while idle | bootstraps |
+| `setupTest(x)` while already ready with the **same** effective options | no-op |
+| `setupTest(y)` while ready or starting with **different** effective options | ⛔ **rejects**, naming active vs requested |
+| two concurrent `setupTest(x)` calls | share one startup |
+| `setupTest` after a failed setup | allowed — a failed setup unwinds and returns to idle |
+| `teardownTest()` while idle | no-op |
+| two concurrent `teardownTest()` calls | share one shutdown |
+| `setupTest(y)` after a **successful** teardown | allowed, different options fine |
+
+**"Same options" is compared by meaning, not by literal value** — connector arrays are deduplicated and compared as sets, so `["cache", "database"]` and `["database", "cache", "cache"]` are the same selection.
+
+⚠ **A failed shutdown poisons the lifecycle.** If `teardownTest()` rejects because the shutdown layer reported a failure, later `setupTest` calls **refuse until the Vitest worker is recycled** or a retried teardown fully succeeds. This is deliberate: a cleared flag does not prove that ports, sockets, pools or timers actually closed, and pretending otherwise hands you a "clean" run built on a leaked runtime.
+
+⚠ **What it cannot detect:** `connectorsManager.shutdown()` catches and logs individual connector failures internally. Those never reach this lifecycle, so they never poison it. It surfaces what that layer reports — no more.
+
+### `tests.setupTimeout` — the setup attempt is bounded
+
+**New in 4.14.0.** A setup attempt that never settles used to leave the lifecycle stuck in `starting` and take the worker down with an out-of-memory crash. It is now bounded.
+
+```ts title="src/config/tests.ts"
+const testsConfigurations = {
+  connectors: ["database", "logger"],
+  setupTimeout: 120000,   // milliseconds — this is the default
+};
+
+export default testsConfigurations;
+```
+
+**Default: `120000` (two minutes)** — far above a healthy cold start, below the point where you'd stop watching the terminal. When it expires:
+
+```
+setupTest() did not finish within 120000ms and is stuck in the "starting" state. The
+lifecycle is now poisoned: whatever that attempt had already started is not known to be
+closed, so later setupTest() calls refuse until the Vitest worker is recycled. If your
+cold start is legitimately slower than this, raise the bound with `tests.setupTimeout`
+in `src/config/tests.ts` — milliseconds, default 120000.
+```
+
+1. **It bounds the setup ATTEMPT, not teardown separately.** `teardownTest()` awaits the same attempt, so it inherits the bound — **one timer, not two.** A second teardown-side deadline was tried and rejected: it re-introduced the unbounded re-entry this whole guard exists to remove.
+2. **Expiry poisons the lifecycle**, it does not return to `idle`. The attempt may have started connectors nobody can now account for, so pretending the runtime is clean would be worse than refusing.
+3. **⛔ An invalid `setupTimeout` throws, naming the bad value.** Zero, negative and non-numeric all fail loudly rather than falling back to the default — a silent fallback would hide a typo behind a working suite.
+4. **The bound is measured from when the attempt started**, not from when config was read. `tests.setupTimeout` is only readable after `loadConfigFiles()`, which happens *inside* the window being bounded; re-arming naively would give you the default plus your configured value.
+
+⚠ **What is proven and what is not.** The nine guards above were each seen to fail under their own mutation. **But every spec injects its scheduler**, so the default *value* is tested while the production timer — and whether its `unref` actually releases the worker — is not. **And no spec observes a real hang**: the stuck attempt is a mock gate, not a socket that never returns. These prove what the lifecycle *decides*, not what a genuinely wedged connector does.
+
+### State is per worker runtime, not per module
+
+The lifecycle state lives in the worker runtime, not in a module variable. That matters because **Vitest rebuilds the module registry between test files while the worker itself keeps running** — so a module-level flag resets exactly where live DB connections and pools survive. Scope:
+
+- **`pool: "forks"`** — state is per worker **process**.
+- **`pool: "threads"`** — state is per worker **thread**. It does **not** cross threads; `globalThis` is per realm, not per process.
+
+In both cases the guard's scope matches the resource's scope, which is the point.
+
+⚠ **Not guaranteed:** under `threads` with `isolate: true`, Vitest tears the thread down while the process lives on. **Whether Node reclaims that thread's sockets and pools is unmeasured**, and nothing in this lifecycle can observe it.
 
 ## Gotchas
 
-- **`setupTest` is idempotent per worker.** Second + later calls early-return. You can't "swap" the connector set mid-run — the first call wins, including the one in `src/test-setup.ts`. Choose your worker default carefully.
-- **Per-worker connections are separate from the HTTP server's connections.** A row inserted by a service-level test is on the worker's connection; the HTTP test server has its own. They don't see each other unless they're both pointing at the same physical DB and the inserting test has already committed.
+- **`setupTest` runs per test file, not per worker** — every version of this skill through 4.13.0 said otherwise. **You pay one framework bootstrap per test file**, which is what 4.13.0 already cost; the difference is that it is now a chosen lifetime rather than a side effect of a module flag resetting.
+- ⛔ **Never delete the `afterAll(teardownTest)` from your setup file.** Without it nothing closes what `setupTest` opened, and the connectors outlive the file that started them.
+- ⛔ **You can't swap the connector set by calling `setupTest` again — it rejects now.** Through 4.13.0 the second call was silently ignored. Tear down first, or don't call it.
+- **These connections are separate from the HTTP test server's.** A row inserted by a service-level test is on this connection; the HTTP test server has its own. They only see each other if both point at the same physical DB **and** the inserting test has committed.
+- **`setupTest` takes over the process's `connectorsManager` for its lifetime.** Teardown is manager-wide, so **mixing `setupTest` with manually started connectors is unsupported** — teardown may close yours too.
 - **`NODE_ENV` is set to `"test"`** by `setupTest`. Code that branches on `Application.isProduction` / `Application.isDevelopment` sees `false` for both. If your tests need production-like config (cookies, CORS), set those values in `src/config/*.ts` explicitly under the test branch — don't rely on the env flag.
 - **No HTTP from this layer.** `setupTest({ connectors: true })` never starts the HTTP connector by design. Don't try to `request.app.http` your way to a fetch test — use the `test-http` skill instead.
 - **Don't import `vitest-setup` from `@warlock.js/core/src/...`.** The public surface is `import { setupTest } from "@warlock.js/core/tests"`. Reaching into source paths breaks when the package layout shifts.
@@ -6308,7 +6453,18 @@ export default {
 
 `deny` wins over `allow`. If the IP can't be read (empty / unparseable), the request is rejected with 403. Reads via `request.detectIp()`.
 
-⚠ **Since 4.13.0 `http.trustProxy` defaults to `false`**, so `request.detectIp()` returns the socket address and **`X-Real-IP` / `X-Forwarded-For` are ignored unless you opt in.** Set `trustProxy: true` **only when you are genuinely behind a proxy that overwrites those headers** — before 4.13.0 the default was `true`, which meant any client could set its own forwarding header and be believed.
+⚠ **Since 4.13.0 `http.trustProxy` defaults to `false`**, so `request.detectIp()` returns the socket address and **`X-Real-IP` / `X-Forwarded-For` are ignored unless you opt in.** Before 4.13.0 the default was `true`, which meant any client could set its own forwarding header and be believed.
+
+⚠ **Opt in with the narrowest shape your topology allows, not with `true`.** Since 4.15.0 `http.trustProxy` takes a hop count or 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 |
+| `2` | Walks past the 2 rightmost `X-Forwarded-For` hops — for an edge that **appends** (the usual case: nginx, ALB, most CDNs) |
+| `"10.0.0.0/8"` / `["10.0.0.0/8", "192.168.0.0/16"]` | Walks left while each hop is a listed proxy |
+| `true` | Trusts the whole chain — the leftmost hop, i.e. **whatever the client put there** if your edge appends rather than overwrites |
+
+With `true`, any client that can reach the process directly picks its own IP and this allowlist is decorative. `X-Real-IP` is honoured only under `true` — it carries no chain to check a hop count or proxy list against — so if your edge sets only that header, have it set `X-Forwarded-For` too.
 
 ```ts
 import { middleware } from "@warlock.js/core";

package/llms.txt

@@ -27,7 +27,7 @@
 - [send-response](@warlock.js/core/send-response/SKILL.md): Send HTTP responses via @warlock.js/core's Response helpers — success/error variants, status helpers, redirects, files, streams, and SSE. Picking the right helper carries the HTTP semantic without manual status codes. Triggers: `response.success`, `response.successCreate`, `response.notFound`, `response.forbidden`, `response.badRequest`, `response.sendFile`, `response.stream`, `response.sse`, `response.replay`, `ResourceNotFoundError`, `ForbiddenError`; "return a 201 from a controller", "send a file", "stream Server-Sent Events", "throw HTTP-shaped errors from services"; typical import `import type { RequestHandler, Response } from "@warlock.js/core"`. Skip: controller shape — `@warlock.js/core/create-controller/SKILL.md`; route registration — `@warlock.js/core/register-route/SKILL.md`; competing patterns: hand-rolled status codes via `reply.code(404).send(...)`, raw Fastify reply.
 - [store-file](@warlock.js/core/store-file/SKILL.md): Read/write/delete files via the `storage` singleton — disks, drivers (local/S3/R2/DO Spaces), `storage.use(name)`, `StorageFile` handles, presigned URLs. Triggers: `storage.put`, `storage.get`, `storage.use`, `StorageFile`, `storageConfigurations`, `getPresignedUrl`, `getPresignedUploadUrl`; "save an uploaded file", "switch between local and S3", "generate a presigned URL", "read file metadata"; typical import `import { storage } from "@warlock.js/core"`. Skip: multipart parsing + image chain — `@warlock.js/core/upload-file/SKILL.md`; image transforms — `@warlock.js/core/process-image/SKILL.md`; storage config shape — `@warlock.js/core/configure-app/SKILL.md`; competing libs `@aws-sdk/client-s3`, `multer`, `formidable`.
 - [test-http](@warlock.js/core/test-http/SKILL.md): Integration tests against a real HTTP server — `startHttpTestServer()` boots one shared server in globalSetup, then `testGet` / `testPost` / `expectJson` make typed requests against it. Triggers: `startHttpTestServer`, `startHttpTestServer({ port })`, `stopHttpTestServer`, `testGet`, `testPost`, `testPut`, `testPatch`, `testDelete`, `expectJson`, `getTestServerUrl`, `testRequest`, `PortInUseError`, `assertPortIsAvailable`, `isPortAvailable`; "integration-test a controller", "end-to-end HTTP test", "globalSetup HTTP server", "assert status and body shape", "test server port already in use", "EADDRINUSE while running tests", "run tests while the dev server is up"; typical import `import { testGet, testPost, expectJson } from "@warlock.js/core/tests"`. Skip: pure unit tests — `@warlock.js/core/test-service/SKILL.md`; controller shape — `@warlock.js/core/create-controller/SKILL.md`; competing libs `supertest`, `light-my-request`, `nock`.
-- [test-service](@warlock.js/core/test-service/SKILL.md): Pure unit tests against services, repositories, models, and use-cases — `setupTest({ connectors })` bootstraps each Vitest worker with its own DB/cache connections so you can call your code directly. Triggers: `setupTest`, `src/test-setup.ts`, `tests.connectors`, `Application.setEnvironment`; "unit-test a service", "test a repository query", "vitest setupFiles", "skip connectors for pure-logic tests"; typical import `import { setupTest } from "@warlock.js/core/tests"`. Skip: HTTP integration — `@warlock.js/core/test-http/SKILL.md`; warlock add test scaffold — `@warlock.js/core/write-cli-command/SKILL.md`; competing tooling: jest direct, `supertest`, `nock`.
+- [test-service](@warlock.js/core/test-service/SKILL.md): Pure unit tests against services, repositories, models, and use-cases — `setupTest({ connectors })` bootstraps the framework with its own DB/cache connections so you can call your code directly, and `teardownTest()` closes it. Triggers: `setupTest`, `teardownTest`, `src/test-setup.ts`, `tests.connectors`, `tests.setupTimeout`, `Application.setEnvironment`; "unit-test a service", "test a repository query", "vitest setupFiles", "skip connectors for pure-logic tests"; typical import `import { setupTest, teardownTest } from "@warlock.js/core/tests"`. Skip: HTTP integration — `@warlock.js/core/test-http/SKILL.md`; warlock add test scaffold — `@warlock.js/core/write-cli-command/SKILL.md`; competing tooling: jest direct, `supertest`, `nock`.
 - [update-packages](@warlock.js/core/update-packages/SKILL.md): Keep a project current with `warlock update` — bump every `@warlock.js/*` dependency in package.json to its latest published version (range operator preserved), then run the lockfile-detected package manager install. Also covers the `warlock dev` update notice, its `u` update-and-restart keyboard shortcut, and the `devServer.checkForUpdates` toggle. Triggers: `warlock update`, `--no-install`, `--dry-run`, `--check`, `checkForUpdates`, `fetchLatestVersion`, `isNewerVersion`; "update warlock packages", "upgrade the framework", "is there a new warlock version", "update notice in the dev server", "press u to update", "dev server keyboard shortcut", "update check offline", "bump @warlock.js/* to latest"; typical CLI `warlock update`. Skip: dev/build/start runtime — `@warlock.js/core/run-app/SKILL.md`; writing a custom command — `@warlock.js/core/write-cli-command/SKILL.md`; installing a NEW feature package (auth, mail, storage) — that is `warlock add`; releasing/publishing the framework — workspace release tooling, not this command.
 - [upload-file](@warlock.js/core/upload-file/SKILL.md): Handle multipart file uploads — read via `request.file()` or `request.validated()`, validate with `v.file()`, save via `UploadedFile.save()` or the storage layer, transform images inline. Triggers: `UploadedFile`, `request.file`, `v.file`, `.save`, `.saveAs`, `.resize`, `.format`, `.quality`, `.image`, `.mimeType`, `.maxSize`; "accept a file upload", "validate file size and mime", "save to S3 or local disk", "resize an uploaded image on save"; typical import `import type { UploadedFile, RequestHandler } from "@warlock.js/core"`. Skip: storage drivers + presigned URLs — `@warlock.js/core/store-file/SKILL.md`; image-only transforms — `@warlock.js/core/process-image/SKILL.md`; schema rules — `@warlock.js/core/validate-input/SKILL.md`; competing libs `multer`, `formidable`, `busboy`.
 - [use-app-context](@warlock.js/core/use-app-context/SKILL.md): Read app-wide context — the `Application` static class (env, version, uptime, runtime strategy, boot lifecycle) plus the `app` runtime accessor (live Fastify, socket.io, router, database via the DI container). Triggers: `Application.isProduction`, `Application.environment`, `Application.runtimeStrategy`, `Application.uptime`, `Application.version`, `Application.onceBooted`, `Application.whenBooted`, `Application.isBooted`, `Application.onShutdown`, `Application.isShuttingDown`, `app.http`, `app.socket`, `app.database`, `app.router`; "branch on environment", "reach the live Fastify instance", "framework version in health endpoint", "dev vs production runtime check", "run code once the app is fully booted", "after all connectors started", "app booted hook", "run cleanup before shutdown", "graceful shutdown hook"; typical import `import { Application, app } from "@warlock.js/core"`. Skip: path helpers — `@warlock.js/core/resolve-path/SKILL.md`; connector start order — `@warlock.js/core/add-connector/SKILL.md`; competing patterns: bare `process.env.NODE_ENV`, ad-hoc Fastify imports.

package/package.json

@@ -1,6 +1,9 @@
 {
   "name": "@warlock.js/core",
   "description": "A robust nodejs framework for building blazing fast applications",
+  "warlock": {
+    "environment": "server"
+  },
   "bin": {
     "warlock": "bin/warlock.js"
   },
@@ -11,24 +14,24 @@
     "@fastify/multipart": "^9.3.0",
     "@fastify/rate-limit": "^10.3.0",
     "@fastify/static": "^8.3.0",
-    "@mongez/concat-route": "^1.1.4",
-    "@mongez/config": "^1.1.4",
+    "@mongez/concat-route": "^1.2.0",
+    "@mongez/config": "^1.2.1",
     "@mongez/copper": "^2.1.2",
-    "@mongez/dotenv": "^1.3.1",
-    "@mongez/events": "^2.2.6",
-    "@mongez/http": "^3.3.8",
-    "@mongez/localization": "^3.4.6",
-    "@mongez/reinforcements": "^3.3.0",
+    "@mongez/dotenv": "^1.3.2",
+    "@mongez/events": "^2.2.7",
+    "@mongez/http": "^3.5.0",
+    "@mongez/localization": "^3.4.7",
+    "@mongez/reinforcements": "^4.0.1",
     "@mongez/slug": "^1.0.7",
-    "@mongez/supportive-is": "^2.1.3",
+    "@mongez/supportive-is": "^2.1.4",
     "@mongez/time-wizard": "^1.0.6",
-    "@warlock.js/auth": "4.15.0",
-    "@warlock.js/cache": "4.15.0",
-    "@warlock.js/cascade": "4.15.0",
-    "@warlock.js/context": "4.15.0",
-    "@warlock.js/logger": "4.15.0",
-    "@warlock.js/seal": "4.15.0",
-    "@warlock.js/fs": "4.15.0",
+    "@warlock.js/auth": "5.0.0",
+    "@warlock.js/cache": "5.0.0",
+    "@warlock.js/cascade": "5.0.0",
+    "@warlock.js/context": "5.0.0",
+    "@warlock.js/logger": "5.0.0",
+    "@warlock.js/seal": "5.0.0",
+    "@warlock.js/fs": "5.0.0",
     "chokidar": "^5.0.0",
     "dayjs": "^1.11.19",
     "es-module-lexer": "^2.0.0",
@@ -54,10 +57,10 @@
     "react": "^19.2.3",
     "react-dom": "^19.2.3",
     "@react-email/render": "^2.0.5",
-    "@warlock.js/herald": "4.15.0",
-    "@warlock.js/ai": "4.15.0",
-    "@warlock.js/access": "4.15.0",
-    "@warlock.js/notifications": "4.15.0"
+    "@warlock.js/herald": "5.0.0",
+    "@warlock.js/ai": "5.0.0",
+    "@warlock.js/access": "5.0.0",
+    "@warlock.js/notifications": "5.0.0"
   },
   "peerDependenciesMeta": {
     "sharp": {
@@ -120,7 +123,7 @@
   ],
   "author": "hassanzohdy",
   "license": "MIT",
-  "version": "4.15.0",
+  "version": "5.0.0",
   "type": "module",
   "main": "./esm/index.mjs",
   "module": "./esm/index.mjs",

package/skills/request-memo/SKILL.md

@@ -0,0 +1,142 @@
+---
+name: request-memo
+description: 'Memoize async work for one HTTP request with `requestMemo<T>(key, fn)` — the v5 replacement for removed `fromRequest`, with single-flight promise sharing, settled-success reuse, rejection eviction, and no cross-request fallback. Triggers: `requestMemo`, `fromRequest`, `fromRequest removed`, `request-scoped cache`, `single-flight`, `current request memo`; "migrate off fromRequest", "load this once per request", "deduplicate concurrent loaders", "cache a repository lookup during one request"; typical import `import { requestMemo } from "@warlock.js/core"`. Skip: middleware-written request state — `@warlock.js/core/use-request-locals/SKILL.md`; process-wide or cross-request caching — `@warlock.js/core/use-middleware/SKILL.md`; competing patterns: dynamic `request[key]` properties, module-global `Map`, payload `request.get()` / `request.set()`.'
+---
+
+# Warlock — memoize work for one request
+
+`requestMemo()` is the v5 replacement for the removed `fromRequest()`. Use it when several code paths in the same HTTP request may need the same asynchronously computed value and the work should run once.
+
+## The exact signature
+
+From `core/src/http/context/request-memo.ts`:
+
+```ts
+export function requestMemo<T>(key: string, fn: () => Promise<T>): Promise<T>
+```
+
+Import it from the package root:
+
+```ts
+import { requestMemo } from "@warlock.js/core";
+```
+
+`fn` takes no arguments and must return a promise. Close over the current request or the inputs needed by the loader.
+
+## Migrate from v4 to v5
+
+### Before — v4 `fromRequest()`
+
+```ts title="src/app/tenants/utils/current-tenant.ts"
+import { fromRequest, type Request } from "@warlock.js/core";
+
+type Tenant = { id: string };
+
+async function loadTenant(id: string): Promise<Tenant> {
+  return { id };
+}
+
+export function currentTenant(request: Request): Promise<Tenant> {
+  const tenantId = String(request.header("x-tenant-id") ?? "");
+
+  return fromRequest("tenants.current", () => loadTenant(tenantId));
+}
+```
+
+### After — v5 `requestMemo()`
+
+```ts title="src/app/tenants/utils/current-tenant.ts"
+import { requestMemo, type Request } from "@warlock.js/core";
+
+type Tenant = { id: string };
+
+async function loadTenant(id: string): Promise<Tenant> {
+  return { id };
+}
+
+export function currentTenant(request: Request): Promise<Tenant> {
+  const tenantId = String(request.header("x-tenant-id") ?? "");
+
+  return requestMemo("tenants.current", () => loadTenant(tenantId));
+}
+```
+
+The call-site migration is usually the import and function name. The complete v5 example above also shows the callback-shape migration: if a v4 callback used the `Request` argument supplied by `fromRequest`, capture the surrounding `request` variable because `requestMemo`'s `fn` receives no arguments.
+
+## Single-flight behavior
+
+Within one request, the first call for a key invokes `fn` and stores its promise. Every concurrent caller using that key receives that exact promise, so parallel consumers do not duplicate the work. After the promise resolves, later calls during the same request keep receiving the cached successful promise.
+
+```ts title="src/app/catalog/controllers/show-product.controller.ts"
+import { requestMemo, type RequestHandler } from "@warlock.js/core";
+
+let loads = 0;
+
+async function loadProduct(): Promise<{ id: string }> {
+  loads += 1;
+  return { id: "product-1" };
+}
+
+export const showProductController: RequestHandler = async ({ response }) => {
+  const first = requestMemo("catalog.product", loadProduct);
+  const second = requestMemo("catalog.product", loadProduct);
+  const [product, sameProduct] = await Promise.all([first, second]);
+
+  return response.success({ product, sameProduct, loads });
+};
+```
+
+For that request, `first === second` and `loads` is `1`.
+
+A rejection is not cached. The rejected entry is deleted immediately, so a later call with the same key retries `fn`. Callers already sharing the rejected promise all observe that rejection.
+
+## Lifetime and isolation
+
+The memo table is attached indirectly to the current request-context store through a `WeakMap`. Each incoming request gets a fresh store, so:
+
+- two concurrent requests never share entries, even when they use the same key;
+- resolved values live only for the request's context lifetime;
+- the store and its memo entries are eligible for garbage collection after the request ends;
+- no value is written onto the `Request` object.
+
+Calling `requestMemo()` outside the HTTP request pipeline throws synchronously. It deliberately has no process-global fallback. For data meant to survive across requests, use an explicit application cache instead.
+
+## Why it replaces `fromRequest()`
+
+`fromRequest()` memoized through dynamic `request[key]` properties. That only type-checked because v4's `Request` had a `[key: string]: any` index signature. v5 removed both the unsafe index signature and `fromRequest()`; `requestMemo()` keeps the one-request lifetime without mutating `Request` or turning values into `any`.
+
+The new helper also provides real single-flight behavior: it stores the in-flight promise. The old helper awaited its callback before writing the result onto `Request`, so concurrent v4 callers could run the same callback more than once.
+
+## Key design
+
+Keys share one string namespace within a request. Use stable, namespaced keys and include every input that changes the result:
+
+```ts
+import { requestMemo } from "@warlock.js/core";
+
+type Product = { id: string };
+
+async function findProduct(id: string): Promise<Product> {
+  return { id };
+}
+
+export function productById(id: string): Promise<Product> {
+  return requestMemo(`catalog.product:${id}`, () => findProduct(id));
+}
+```
+
+Reusing one key for different result types is a caller bug: TypeScript cannot compare the generic type arguments used at separate call sites.
+
+## Gotchas
+
+- **Do not call it during bootstrap, in a CLI command, or from a background job.** There is no active HTTP request context there, so it throws.
+- **Do not omit result-changing inputs from the key.** `catalog.product` is wrong when different IDs may be loaded during one request; use `catalog.product:${id}`.
+- **Do not use `request.set()` as a replacement.** It writes to the request input payload read by `all()`, `input()`, and `validated()`.
+- **Failures retry.** If repeated failures must also be cached, this primitive is not that policy; catch and convert the failure into a successful result deliberately, or use another cache.
+- **Use `request.locals` for state written by middleware and read downstream.** Memoization and request attachment are separate jobs.
+
+## See also
+
+- [`use-request-locals/SKILL.md`](../use-request-locals/SKILL.md) — typed per-request data written by middleware.
+- [`write-middleware/SKILL.md`](../write-middleware/SKILL.md) — authoring and registering middleware.
+- [`create-controller/SKILL.md`](../create-controller/SKILL.md) — consuming request-scoped values from controllers.