@warlock.js/core 5.30.0 → 5.31.0

package/skills/store-file/SKILL.md

@@ -12,11 +12,13 @@ description: 'Read/write/delete files via the `storage` singleton — disks, dri
 ```ts
 import { storage } from "@warlock.js/core";
 
+declare const buffer: Buffer; // file contents
+
 const file = await storage.put(buffer, "uploads/photo.jpg");
 
-console.log(file.url);     // public URL
-console.log(file.name);    // "photo.jpg"
-console.log(file.hash);    // sha256
+console.log(file.url); // public URL
+console.log(file.name); // "photo.jpg"
+console.log(file.hash); // sha256
 ```
 
 That's the entire surface for the common case. `storage.put(...)` writes to the default driver and returns a `StorageFile`.
@@ -78,6 +80,12 @@ The `storage` singleton (and any `storage.use(name)` scoped view) exposes the sa
 ### Writing
 
 ```ts
+import { createReadStream } from "node:fs";
+import { storage, type Request } from "@warlock.js/core";
+
+declare const buffer: Buffer; // file contents
+declare const request: Request; // the current request
+
 // From buffer
 const file = await storage.put(buffer, "uploads/photo.jpg");
 
@@ -88,20 +96,16 @@ await storage.put(buffer, "uploads/photo.jpg", {
 });
 
 // From stream (large files)
-import { createReadStream } from "node:fs";
 await storage.putStream(createReadStream("./video.mp4"), "uploads/video.mp4");
 
 // From a URL (downloads then stores)
 await storage.putFromUrl("https://example.com/image.jpg", "uploads/image.jpg");
 
 // From base64 data URL
-await storage.putFromBase64(
-  "data:image/png;base64,iVBORw0KGgo...",
-  "uploads/photo.png",
-);
+await storage.putFromBase64("data:image/png;base64,iVBORw0KGgo...", "uploads/photo.png");
 
 // From an UploadedFile (multipart upload)
-await storage.put(request.file("image"), "uploads/avatar.jpg");
+await storage.put(request.file("image")!, "uploads/avatar.jpg"); // validate the upload first
 ```
 
 Every `put*` returns a `StorageFile`.
@@ -119,8 +123,8 @@ const json = await storage.getJson("config/settings.json");
 ### Existence + metadata
 
 ```ts
-await storage.exists("uploads/photo.jpg");                  // boolean
-const info = await storage.metadata("uploads/photo.jpg");   // { size, mimeType, lastModified, ... }
+await storage.exists("uploads/photo.jpg"); // boolean
+const info = await storage.metadata("uploads/photo.jpg"); // { size, mimeType, lastModified, ... }
 const bytes = await storage.size("uploads/photo.jpg");
 ```
 
@@ -162,10 +166,26 @@ const files = await storage.list("uploads", { recursive: true, limit: 100 });
 ### URLs
 
 ```ts
-storage.url("uploads/photo.jpg");                        // public URL (sync)
-await storage.temporaryUrl("private/doc.pdf", 3600);     // signed URL, expires in seconds
+storage.url("uploads/photo.jpg"); // public URL (sync)
+await storage.temporaryUrl("private/doc.pdf", 3600); // signed URL, expires in seconds
 ```
 
+## Private-address check without the framework — `@warlock.js/core/net`
+
+`putFromUrl` refuses private, loopback, link-local and cloud-metadata hosts. Its classifier is also a side-effect-free subpath that loads only `node:net`, so workers, CLIs and standalone agent processes can reuse the rules without booting Core:
+
+```ts
+import { isPrivateOrReservedIp } from "@warlock.js/core/net";
+
+const address = "10.0.0.1";
+
+if (isPrivateOrReservedIp(address)) {
+  throw new Error(`Refusing private address ${address}`);
+}
+```
+
+Same function as the root `@warlock.js/core` export.
+
 ## Switching drivers — `storage.use(name)`
 
 For a single call against a non-default driver, scope it:
@@ -183,7 +203,25 @@ console.log(localFile.url);
 
 ## Cached image variants follow their source
 
-On a local disk, `delete`, `deleteMany`, `move` and `deleteDirectory` (for every file under it) also remove the file's cached image derivatives (the `?variant=` renders of `uploadedFileController`). For a file removed some other way, call `purgeImageVariants(path, { disk? })`; with no path it clears the disk's whole derivative cache. Serve another local disk's files and variants with `createUploadedFileController({ disk: "private" })`, or call `resolveImageVariant({ disk, path, variant, format? })` from your own authenticated route. A configured `uploads.images.cacheDirectory` is shared by every disk: never put it inside `public/` (Warlock warns once if you do).
+On a local disk, `delete`, `deleteMany`, `move` and `deleteDirectory` (for every file under it) also remove the file's cached image derivatives (the `?variant=` renders of `uploadedFileController`). For a file removed some other way, call `purgeImageVariants(path, { disk? })`; with no path it clears that disk's derivative cache — or, when `uploads.images.cacheDirectory` is set (shared by every local disk), every disk's derivatives. Serve another local disk's files and variants with `createUploadedFileController({ disk: "private" })`, or call `resolveImageVariant({ disk, path, variant, format? })` from your own authenticated route. A configured `uploads.images.cacheDirectory` is shared by every disk: never put it inside `public/` (Warlock warns once if you do).
+
+Give derivatives a dedicated cache folder, even when it sits beneath a storage root. Full and per-file purges delete recognized image, source-manifest and temporary files in the generated shard/source/generation layout; they retain directories, unrelated files and symlinks. Eviction validates the same directory layout; it may remove empty generated generation directories, while user folders and unrelated entries are never touched. Per-file purges and stale-generation pruning also reject symlinked shard/source directories. Pruning removes only recognized files from older generation-shaped folders, retaining current-generation files and unrelated entries. Reserve generated-looking paths for derivatives and reclaim files from older cache layouts manually.
+
+### Bound the cache and render remote disks
+
+Set `uploads.images.maxCacheBytes` (default `512 * 1024 * 1024`) and `maxCacheAge` (seconds, default seven days). Hits older than the age render again. A write schedules a coalesced background check, at most once per minute; hits never walk the cache. The check walks the cache only on the first check after boot, when the byte estimate is over budget, when the oldest retained derivative has expired, or once per `maxCacheAge`. The sweep removes expired derivatives and evicts oldest files to meet the byte budget, retaining the file being returned even when it alone exceeds that budget. It also removes writer temporaries older than an hour (left by a crashed write), and a generation directory left without derivatives loses its `source.json` and then the empty directory once it is older than five minutes, which reclaims old object-storage generations after ETag changes. The byte budget can be exceeded until the next sweep; idle caches are cleaned after the next generated derivative. Use `Number.MAX_SAFE_INTEGER` for a practically unbounded budget. Keep the cache on a local, writable filesystem outside `public/`; it must not equal or contain any configured local storage root, including runtime-registered disks. Generation and purge use the same guard and compare realpaths, including symlinked directories and existing ancestors of paths not yet created. An overlapping setting throws `ImageVariantsConfigError` before cache removal, as does a cache or root that cannot be resolved (`ENOTDIR`, `EACCES`, `ELOOP`; the original error is its `cause`). The guard result is remembered per cache, disk root and configured local roots; a newly registered disk is checked again.
+
+```ts
+import { createUploadedFileController, generateImageVariants, router } from "@warlock.js/core";
+
+router.get("/cloud-images/*", createUploadedFileController({ disk: "r2" }));
+const descriptor = await generateImageVariants("products/photo.jpg", {
+  disk: "r2",
+  urlPrefix: "/cloud-images",
+});
+```
+
+For an object-storage disk, `descriptor.src` is the driver's original URL; variant URLs use `/cloud-images` and its controller accepts variant queries only (an original request there returns 404). Selecting a remote disk explicitly opts that route into cloud serving; the default `uploadedFileController` continues to return 404 when the default disk is cloud. `createUploadedFileController({ remote: true })` opts into the default cloud disk. Protect a remote route before serving private derivatives: an unguarded route exposes every allowed image in that bucket/prefix, including originals otherwise served only through signed URLs. Use signed original URLs separately for private buckets. `resolveImageVariant` also accepts remote disks. Requests read source metadata; an ETag, size and last-modified date select the cached generation without downloading the source on a hit. Without an ETag, bytes are downloaded and hashed. Concurrent loads for the same disk/path/version are shared, bounded by `maxSourceBytes`, and ingest generation downloads once for all variants and formats. The default remote cache is `<app>/storage/.cache/image-variants`. Bucket identity and the effective storage prefix isolate cached sources. After remote deletion or moving, call `purgeImageVariants(path, { disk: "r2" })` yourself; age/size cleanup also reclaims those derivatives.
 
 ## `StorageFile` — the OOP handle
 
@@ -195,33 +233,33 @@ const file = storage.file("uploads/photo.jpg");
 
 ### Sync properties (no I/O)
 
-| Property         | Description                                    |
-| ---------------- | ---------------------------------------------- |
-| `file.path`      | full storage path (`"uploads/photo.jpg"`)      |
-| `file.name`      | basename (`"photo.jpg"`)                       |
-| `file.extension` | lowercased ext, no dot (`"jpg"`)               |
-| `file.directory` | parent directory                               |
-| `file.driver`    | driver name (`"local"` / `"s3"` / …)           |
-| `file.url`       | public URL (uses cached value if present)      |
-| `file.hash`      | sha256, set by `put*` operations               |
-| `file.isDeleted` | `true` after `file.delete()`                   |
+| Property         | Description                               |
+| ---------------- | ----------------------------------------- |
+| `file.path`      | full storage path (`"uploads/photo.jpg"`) |
+| `file.name`      | basename (`"photo.jpg"`)                  |
+| `file.extension` | lowercased ext, no dot (`"jpg"`)          |
+| `file.directory` | parent directory                          |
+| `file.driver`    | driver name (`"local"` / `"s3"` / …)      |
+| `file.url`       | public URL (uses cached value if present) |
+| `file.hash`      | sha256, set by `put*` operations          |
+| `file.isDeleted` | `true` after `file.delete()`              |
 
 ### Async data
 
 ```ts
-await file.data();        // full StorageFileData with size/mimeType/url/hash
+await file.data(); // full StorageFileData with size/mimeType/url/hash
 await file.size();
 await file.mimeType();
 await file.lastModified();
-await file.etag();        // cloud only
+await file.etag(); // cloud only
 ```
 
 ### Operations
 
 ```ts
-await file.copy("backups/photo.jpg");      // → new StorageFile at the copy
-await file.move("archive/photo.jpg");      // → returns this; path is updated in place
-await file.delete();                       // marks isDeleted
+await file.copy("backups/photo.jpg"); // → new StorageFile at the copy
+await file.move("archive/photo.jpg"); // → returns this; path is updated in place
+await file.delete(); // marks isDeleted
 const buffer = await file.contents();
 const stream = await file.stream();
 ```
@@ -279,20 +317,22 @@ await cloud.getRegion();
 Local storage signs URLs with an HMAC token (no presigned URL — there is no S3 here). Validate inbound tokens before serving:
 
 ```ts
-import { storage } from "@warlock.js/core";
+import { storage, type RequestHandler } from "@warlock.js/core";
 
-const result = await storage.validateTemporaryToken(token);
+export const temporaryFileController: RequestHandler = async ({ request, response }) => {
+  const result = await storage.validateTemporaryToken(String(request.input("token")));
 
-if (!result.valid) {
-  return response.forbidden({ error: result.error });
-}
+  if (!result.valid) {
+    return response.forbidden({ error: result.error });
+  }
 
-if (result.absolutePath) {
-  return response.sendFile(result.absolutePath);
-}
+  if (result.absolutePath) {
+    return response.sendFile(result.absolutePath);
+  }
 
-const stream = await result.getStream!();
-stream.pipe(response.raw);
+  const stream = await result.getStream!();
+  stream.pipe(response.raw);
+};
 ```
 
 Cloud drivers always return `{ valid: false }` from `validateTemporaryToken` — they validate via presigned URL on the cloud side.
@@ -319,16 +359,16 @@ await storage.use("tenant-s3").put(buffer, "data.csv");
 
 `storage.on(event, handler)` subscribes to lifecycle hooks. Event types:
 
-| Event          | Fires                              |
-| -------------- | ---------------------------------- |
-| `beforePut`    | before write                       |
-| `afterPut`     | after successful write             |
-| `beforeDelete` | before delete                      |
-| `afterDelete`  | after delete                       |
-| `beforeCopy`   | before copy                        |
-| `afterCopy`    | after copy                         |
-| `beforeMove`   | before move                        |
-| `afterMove`    | after move                         |
+| Event          | Fires                  |
+| -------------- | ---------------------- |
+| `beforePut`    | before write           |
+| `afterPut`     | after successful write |
+| `beforeDelete` | before delete          |
+| `afterDelete`  | after delete           |
+| `beforeCopy`   | before copy            |
+| `afterCopy`    | after copy             |
+| `beforeMove`   | before move            |
+| `afterMove`    | after move             |
 
 ```ts
 storage.on("afterPut", ({ location, file }) => {
@@ -378,10 +418,10 @@ export const uploadAvatarController: GuardedRequestHandler = async ({ request, r
 ### Direct browser upload via presigned URL
 
 ```ts
-const uploadUrl = await storage.use("r2").getPresignedUploadUrl(
-  `uploads/${userId}/${filename}`,
-  { expiresIn: 600, contentType: mimeType },
-);
+const uploadUrl = await storage.use("r2").getPresignedUploadUrl(`uploads/${userId}/${filename}`, {
+  expiresIn: 600,
+  contentType: mimeType,
+});
 
 return response.success({ uploadUrl });
 ```

package/skills/test-fakes/SKILL.md

@@ -0,0 +1,123 @@
+---
+name: test-fakes
+description: 'The test fakes Warlock installs by default in the test environment — `mailFake`, `queueFake`, `cacheFake`, `storageFake`, `clockFake`, `idsFake` — and their assertions (`assertSent`, `assertPushed`, `assertHas`, `assertExists`, `travel`), plus how to opt out (`tests.fakes`, `setupTest({ fakes })`). Triggers: `mailFake`, `queueFake`, `cacheFake`, `storageFake`, `clockFake`, `idsFake`, `installTestFakes`, `restoreTestFakes`, `tests.fakes`, `FakeAssertionError`, `clock.now`, `ids.uuid`, `setDispatchInterceptor`; "assert an email was sent", "assert a job was dispatched", "freeze time in a test", "deterministic ids", "tests without Redis", "keep the real cache driver in tests". Typical import `import { mailFake, queueFake } from "@warlock.js/core/tests"`. Skip: HTTP request helpers — the `test-http` topic; fixtures — the `model-factories` topic.'
+---
+
+# Warlock — test fakes
+
+In the test environment six fakes are installed for you: `setupTest()` installs them in every test file once its connectors are up, `startHttpTestServer()` installs them in the shared server, and teardown restores them. Nothing is delivered, pushed to Redis, uploaded to a bucket, and time and ids are deterministic.
+
+| Fake          | Replaces                                                        |
+| ------------- | --------------------------------------------------------------- |
+| `mailFake`    | Mail delivery: `sendMail()` / `Mail` sends are captured         |
+| `queueFake`   | `@warlock.js/queue` dispatch: jobs are recorded, not pushed     |
+| `cacheFake`   | The cache's current driver: a fresh in-memory driver            |
+| `storageFake` | Every storage driver (local, S3, R2, Spaces): a temp directory  |
+| `clockFake`   | `clock` from `@warlock.js/core`: frozen at 2026-01-01T00:00:00Z |
+| `idsFake`     | `ids` from `@warlock.js/core`: numbered UUIDs and tokens        |
+
+## Assert what your code did
+
+```ts
+// with: import { cacheFake, mailFake, queueFake, storageFake } from "@warlock.js/core/tests";
+//       plus your job (buildReport) and service (requestReportService)
+beforeEach(() => {
+  mailFake.clear();
+  queueFake.clear();
+});
+
+it("queues the report, mails the requester and caches the request", async () => {
+  await requestReportService({ reportId: "r-1", email: "ada@example.test" });
+
+  mailFake.assertSent({ to: "ada@example.test", subject: /report requested/i });
+  mailFake.assertSentCount(1);
+  queueFake.assertPushed(buildReport, { reportId: "r-1" });
+  queueFake.assertNotPushed("reports.cleanup");
+  await cacheFake.assertHas("reports.r-1.status");
+  await storageFake.assertMissing("reports/r-1.pdf");
+});
+```
+
+- **mail** — `assertSent(matcher?)` returns the first match; `assertNotSent`, `assertSentCount(n, matcher?)`, `assertNothingSent()`, `sent(matcher?)`, `clear()`. Matcher: a predicate or `{ to, subject, from, contains }` (`to` matches to/cc/bcc, `subject` a string or RegExp, `contains` the HTML or text body).
+- **queue** — `assertPushed(jobOrName, payloadSubset?)`, `assertNotPushed`, `assertPushedCount(n, job?)`, `assertNothingPushed()`, `pushed(job?, matcher?)`. Each record has `id`, `name`, `queue`, `payload`, `options` (`delay`, `priority`, `jobId`) and `pushedAt`. An explicit `jobId` stays idempotent and `job.find(id)` answers from the record. Jobs are not run — call the handler to test it.
+- **cache** — `assertHas(key)`, `assertMissing(key)`, `assertStored(key, value)` (deep equality), `driver()`, `clear()`. TTLs, tags, namespaces and locks are the real memory driver's.
+- **storage** — `assertExists(path, driver?)`, `assertMissing(path, driver?)`, `files(driver?)`, `root()`. Each configured driver name gets a folder under one temp root, shared with the HTTP test server through `WARLOCK_TEST_STORAGE_ROOT`; the process that created it deletes it.
+- A failed assertion throws `FakeAssertionError` listing what was recorded.
+
+## Time and ids
+
+```ts
+import { clock, ids } from "@warlock.js/core";
+import { clockFake, idsFake } from "@warlock.js/core/tests";
+import { expect, it } from "vitest";
+
+it("is deterministic", () => {
+  expect(clock.now().toISOString()).toBe("2026-01-01T00:00:00.000Z");
+
+  clockFake.travel(90_000); // +1m30s
+  clockFake.travelTo("2030-05-05T10:00:00Z");
+
+  expect(ids.uuid()).toBe("00000000-0000-4000-8000-000000000001");
+  expect(ids.uuid()).toBe(idsFake.uuid(2));
+});
+```
+
+Only `clock` and `ids` are faked — `Date`, `setTimeout` and drivers keep real time, so nothing stalls. In app code, read time through `clock.now()` / `clock.timestamp()` and make identifiers with `ids.uuid()` / `ids.token(length)` wherever a test needs to control them; outside tests they are the system clock and `node:crypto`.
+
+## Where a fake records
+
+A fake records in the process that runs the code. A request served by the shared `startHttpTestServer()` runs in Vitest's main process, so its mail is captured there, not in your test. Serve it in the worker with `createTestHttpServer()` (the `test-http` topic) and the worker's fakes see it:
+
+```ts
+import { createTestHttpServer, mailFake } from "@warlock.js/core/tests";
+import { it } from "vitest";
+
+it("mails the requester", async () => {
+  const app = await createTestHttpServer({
+    loadAppModules: true,
+    importModule: (file) => import(file),
+  });
+
+  try {
+    await app.post("/reports", { reportId: "r-1", email: "ada@example.test" });
+    mailFake.assertSent({ to: "ada@example.test" });
+  } finally {
+    await app.close();
+  }
+});
+```
+
+## Opting out
+
+Precedence: the `fakes` option > `tests.fakes` in `src/config/tests.ts` > all on.
+
+```ts title="src/config/tests.ts"
+const testsConfigurations = {
+  fakes: { cache: false }, // keep the configured cache driver; `fakes: false` keeps every real driver
+};
+
+export default testsConfigurations;
+```
+
+```ts title="src/test-setup.ts"
+import { setupTest, teardownTest } from "@warlock.js/core/tests";
+import { afterAll } from "vitest";
+
+await setupTest({ importModule: (file) => import(file), fakes: { storage: false } });
+
+afterAll(teardownTest);
+```
+
+An unknown fake name or a non-boolean value fails setup with the list of known fakes. Without `setupTest()`, call `installTestFakes(selection?)` / `restoreTestFakes()` yourself.
+
+## Gotchas
+
+- **Recorded state lives for the test file.** Call `clear()` in `beforeEach` when tests in one file must not see each other's mails or jobs.
+- **Real deliveries in tests need an opt-out.** A test that relied on a real SMTP sink, a Redis cache shared between the HTTP server and the workers, or a real bucket now gets the fake — set that fake to `false`.
+- **The queue seam is public.** `setDispatchInterceptor({ dispatch, find? })` from `@warlock.js/queue` replaces the broker for every job in the process; `queueFake` is built on it.
+
+## See also
+
+- The `test-service` topic — `setupTest()` and its lifecycle.
+- The `test-http` topic — `createTestHttpServer()` and the HTTP helpers.
+- The `model-factories` topic — deterministic fixtures.

package/skills/test-http/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: test-http
-description: '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 — the `test-service` topic; controller shape — the `create-controller` topic; competing libs `supertest`, `light-my-request`, `nock`.'
+description: '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 })`, `startHttpTestServer({ port: 0 })`, `stopHttpTestServer`, `createTestHttpServer`, `TestHttpServer`, `createTestRequestClient`, `snapshotResponse`, `actingAs`, `AuthenticatedTestClient`, `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", "ephemeral test port", "test with the real Fastify plugins", "assert mail sent by a request", "response snapshot"; typical import `import { testGet, testPost, expectJson } from "@warlock.js/core/tests"`. Skip: pure unit tests — the `test-service` topic; controller shape — the `create-controller` topic; competing libs `supertest`, `light-my-request`, `nock`.'
 ---
 
 # Warlock — HTTP integration tests
@@ -38,6 +38,52 @@ describe("Users API", () => {
 
 No `beforeAll`, no manual server start — the project's `src/test-global-setup.ts` brought the HTTP server up once before any test ran.
 
+## Signed-in requests — `actingAs(user)`
+
+```ts
+import type { Auth } from "@warlock.js/auth";
+import { actingAs, expectJson } from "@warlock.js/core/tests";
+import { expect } from "vitest";
+
+export async function expectNoUnreadNotifications(user: Auth) {
+  const client = await actingAs(user);
+  try {
+    const body = await expectJson<{ count: number }>(
+      await client.get("/notifications/unread-count"),
+    );
+    expect(body.count).toBe(0);
+  } finally {
+    await client.dispose();
+  }
+}
+```
+
+`actingAs()` requires `NODE_ENV="test"` before issuing any credentials.
+Cookie-only auth middleware needs the app's login route rather than this Bearer client.
+
+The helper calls the user's real `generateAccessToken()` and sends its persisted
+credential as a Bearer header. Auth middleware, account policy and token expiry
+still apply. It does not test the app's login route or create a user for you.
+Use your login route directly when testing credentials/session cookies.
+
+Each client owns its identity, so parallel users and anonymous `testGet()` calls
+remain separate. Extra headers/signals use the normal helper options; a supplied
+Authorization header is replaced by the bound user's token. `client.dispose()`
+revokes only that token. Fixture owners clean up their own users and rows.
+
+## Generated notification specs
+
+Install test support before notifications (`warlock add test`, then
+`warlock add notifications`) to emit a shared fixture and signed-in `.spec.ts`
+cases for list/unread-count/mark-read/mark-all. They use the configured
+`auth.userType.user` model with `actingAs()` and a second recipient to check
+isolation. Run against a migrated test database; customize required user fields
+in `notifications/tests/notifications.fixture.ts`. Cleanup revokes the fixture's
+tokens and deletes only its rows/users.
+
+Existing Vitest configurations must include both test extensions:
+`include: ["src/app/**/*.{test,spec}.ts"]`.
+
 ## The bootstrap — `startHttpTestServer` / `stopHttpTestServer`
 
 ```ts
@@ -90,23 +136,75 @@ startHttpTestServer({ port: 2032 }).
 
 This runs whether or not you passed a port, so a collision never reaches you as a bare `EADDRINUSE` from inside Fastify. The failure is a `PortInUseError` carrying `port` and `host`. The same check is available on its own — `assertPortIsAvailable(port, host)` throws it, `isPortAvailable(port, host)` returns a boolean.
 
-### Port `0` is refused
-
-`port: 0` — "let the OS pick one" — is not supported, and says so rather than half-working:
+### Port `0` — let the OS pick
 
+```ts
+await startHttpTestServer({ port: 0 });
 ```
-startHttpTestServer() cannot run on port 0. Pass an explicit port — e.g.
-startHttpTestServer({ port: 3999 }) — or set `http.port` in your config. Test workers
-are separate processes that resolve the server's URL from the port published at
-startup, and an OS-assigned port is not knowable to them.
-```
 
-The reason is the worker handoff described above: the port the OS assigns is never recorded anywhere the workers can read, so `getTestServerUrl()` would resolve `0` and send every request to `http://host:0`.
+`port: 0` binds whatever free port the OS hands out — what `warlock add test` generates. There is nothing to preflight; once the HTTP connector has bound, the port it actually took is published as `WARLOCK_TEST_SERVER_PORT`, so `testGet()`, `actingAs()` and friends follow it. If the connector bound nothing (no `src/config/http.ts`, or a worker-only role), startup fails saying so instead of publishing `0`. A negative port is refused.
+
+⚠ **Changed in 5.31.0.** `port: 0` used to be refused, because the bound port was not recorded anywhere the workers could read. `HttpConnector.start()` now records the port `listen()` returned, and that is what gets published.
 
 ### If startup fails, nothing is left behind
 
 `startHttpTestServer()` owns the connectors it starts. A failure part-way through — a bad config, a connector that won't boot — tears down whatever came up, withdraws the published port, and **rethrows the original error**; a failure during that cleanup is logged but never replaces the cause. `stopHttpTestServer()` withdraws the port and resets its state even when the shutdown itself throws, and still surfaces that failure.
 
+## In the worker, with the production plugins — `createTestHttpServer()`
+
+The shared server runs in Vitest's main process, so the test fakes in a worker never see what a request did there. `createTestHttpServer()` serves requests inside the worker instead, built the way production builds it: `startHttpServer()`, every plugin `registerHttpPlugins()` registers (rate limit with its cache store, CORS, multipart, cookies), the router's real route registration, an OS-assigned port.
+
+```ts
+import { createTestHttpServer, mailFake, type TestHttpServer } from "@warlock.js/core/tests";
+import { afterEach, expect, it } from "vitest";
+
+let app: TestHttpServer | undefined;
+
+afterEach(async () => {
+  await app?.close();
+});
+
+it("answers through the real plugins and lets the fakes see the handler", async () => {
+  app = await createTestHttpServer({
+    routes: (router) =>
+      router.post("/echo", ({ request, response }) =>
+        response.success({ name: request.input("name") }),
+      ),
+  });
+
+  const response = await app.post("/echo", { name: "Ada" });
+
+  expect(response.status).toBe(200);
+  mailFake.assertNothingSent();
+});
+```
+
+- `loadAppModules: true` (with `importModule: (file) => import(file)`, as `setupTest()` takes it) serves every app route; modules load once per process. Needs `setupTest()` to have run in the worker.
+- `routes: (router) => …` registers routes for this server only; `close()` removes them.
+- It returns `url`, `port`, `server` (Fastify, for `inject()`), the request helpers, `actingAs(user)` bound to it, and `close()`.
+- `createTestRequestClient(baseUrl)` gives the same helpers bound to any URL.
+
+## Response snapshots — `snapshotResponse()`
+
+```ts
+import { snapshotResponse, testPost } from "@warlock.js/core/tests";
+import { expect, it } from "vitest";
+
+it("creates a post", async () => {
+  const response = await testPost("/posts", { title: "Hello" });
+
+  expect(
+    await snapshotResponse(response, { redact: ["post.id", "post.createdAt"] }),
+  ).toMatchSnapshot();
+});
+```
+
+The snapshot is `{ status, contentType, body }`; redacted paths read `"[redacted]"`, and `*` matches any key or index (`"posts.*.id"`). It consumes the body.
+
+## Fakes in the server process
+
+`startHttpTestServer()` installs the test fakes too (mail, queue, cache, storage, clock, ids — see the `test-fakes` topic), honouring `tests.fakes` and its own `fakes` option. They record in the main process, so assert on request side effects with `createTestHttpServer()`; the storage fake's temp root is shared with the workers (`WARLOCK_TEST_STORAGE_ROOT`).
+
 ## Project wiring — `src/test-global-setup.ts` + `vite.config.ts`
 
 ```ts title="src/test-global-setup.ts"
@@ -117,7 +215,7 @@ The reason is the worker handoff described above: the port the OS assigns is nev
 import { startHttpTestServer, stopHttpTestServer } from "@warlock.js/core/tests";
 
 export async function setup() {
-  await startHttpTestServer();
+  await startHttpTestServer({ port: 0 });
 }
 
 export async function teardown() {
@@ -137,7 +235,7 @@ export default defineConfig({
     setupFiles: ["./src/test-setup.ts"], // ← setupTest + afterAll(teardownTest), per test file
     environment: "node",
     globals: false,
-    include: ["src/app/**/*.test.ts"],
+    include: ["src/app/**/*.{test,spec}.ts"],
   },
 });
 ```
@@ -204,13 +302,16 @@ All accept a relative path (leading `/` optional) and a standard `RequestInit`.
 ```ts
 import { expectJson, parseJsonResponse } from "@warlock.js/core/tests";
 
+type MyShape = { id: number; name: string };
+declare const response: Response; // from testGet / testPost / fetch
+
 // Parse-only
-const body = await parseJsonResponse<MyShape>(response);
+const parsed = await parseJsonResponse<MyShape>(response);
 
 // Assert status + parse in one call
-const body = await expectJson<MyShape>(response); // expects 200
-const body = await expectJson<MyShape>(response, 201); // expects 201
-const body = await expectJson<MyShape>(response, 404); // expects 404 (testing error paths)
+const ok = await expectJson<MyShape>(response); // expects 200
+const created = await expectJson<MyShape>(response, 201); // expects 201
+const missing = await expectJson<MyShape>(response, 404); // expects 404 (testing error paths)
 ```
 
 `expectJson` throws with the actual status + response body when the assertion fails — no chasing "got 500" messages without context.
@@ -263,10 +364,10 @@ import { User } from "src/app/users/models/user";
 
 it("GET /me returns the current user", async () => {
   const user = await User.create({ email: "auth@e.com", password: "secret" });
-  const { accessToken } = await authService.generateTokens(user);
+  const { accessToken } = await authService.createTokenPair(user);
 
   const response = await testGet("/me", {
-    headers: { Authorization: `Bearer ${accessToken}` },
+    headers: { Authorization: `Bearer ${accessToken.token}` },
   });
 
   const { user: me } = await expectJson<{ user: { email: string } }>(response);
@@ -290,8 +391,8 @@ export async function createUserAndToken(overrides: Partial<{ email: string }> =
     password: "test-secret",
   });
 
-  const { accessToken } = await authService.generateTokens(user);
-  return { user, accessToken, authHeader: { Authorization: `Bearer ${accessToken}` } };
+  const { accessToken } = await authService.createTokenPair(user);
+  return { user, accessToken, authHeader: { Authorization: `Bearer ${accessToken.token}` } };
 }
 ```
 
@@ -342,7 +443,7 @@ This is fine for normal test flow. It bites when you're inside a transaction the
 ## Gotchas
 
 - **`globalSetup` must export `setup` and `teardown`.** Vitest reads them by name. A typo in the export gets you a confusing "server not running" error on the first `testGet` call.
-- **Port conflicts.** If `http.port` matches your running dev server, the preflight fails with a `PortInUseError` naming the port. Either stop the dev server or pass a free one: `startHttpTestServer({ port: 3999 })`.
+- **Port conflicts.** If `http.port` matches your running dev server, the preflight fails with a `PortInUseError` naming the port. Pass `startHttpTestServer({ port: 0 })` to let the OS pick, or a fixed free one: `startHttpTestServer({ port: 3999 })`.
 - **Auth tokens need a real user.** Generating a JWT with a non-existent `user_id` works — but the auth middleware's user-loading step will reject the request with 401 because it can't find the user in the DB.
 - **`expectJson` parses the body once.** If you call it twice on the same response, the second call gets an already-consumed stream error. Capture the result.
 - **The HTTP server's connection is NOT torn down between test files.** Data persists across files within a single `vitest` run. Either truncate in `afterEach` / `afterAll`, or design your tests to be order-independent.
@@ -351,6 +452,9 @@ This is fine for normal test flow. It bites when you're inside a transaction the
 ## See also
 
 - The `test-service` topic — pure unit tests against services/repositories/models (no HTTP).
+- The `test-fakes` topic — mail, queue, cache, storage, clock and ids fakes and their assertions.
+- The `model-factories` topic — `defineFactory()` for deterministic fixtures.
+- The `make-endpoint` topic — `warlock make endpoint` writes an endpoint with its HTTP test.
 - The `create-controller` topic — the controller shape your HTTP tests are exercising.
 - The `warlock-conventions` topic — module layout, where `tests/*.test.ts` files live.
 - The `write-cli-command` topic — `warlock add test` scaffolds both global + worker setup files.