@jterrazz/test 16.1.1 → 18.0.0

package/docs/16-contracts.md

@@ -1,438 +0,0 @@
-# 16 — Contracts: the outside world, declared
-
-Everything the outside world replies is declared as a **contract**: a request to match and a response to serve, together in one named artifact. There is no second form — no mock format, no fixture-path string, no `.http` intercept file. Contracts are the whole vocabulary, on all four facets that reach the network.
-
-## The principle
-
-> **TypeScript is behavior. `.json` is data. `.http` is a document at the boundary of YOUR OWN api** (`_requests/`, `_expected/`) — never a mock format.
-
-A contract is behavior: it decides what matches and what is served, it can count, it can be required, it can compose. That belongs in TypeScript, where the type checker and the app's own builders are reachable. A 200-line payload is not behavior — it is data, and it goes to a sibling `.json` the contract imports. And `.http` keeps the one role it is good at: a complete, readable document of a request your api receives or a response your api returns.
-
-## `defineContract`
-
-```typescript
-import { defineContract, http } from '@jterrazz/test';
-
-export default defineContract({
-    request: http.get('/articles/{{uuid}}'),
-    response: http.json({ id: 'a-1', title: 'Fauci and the lab leak' }),
-});
-```
-
-| Field       | Meaning                                                                                                                     |
-| ----------- | --------------------------------------------------------------------------------------------------------------------------- |
-| `request`   | What outgoing call this contract speaks for — a provider builder (`http.*`, `openai.*`, `anthropic.*`)                      |
-| `response`  | The reply: a fixed value, or `(request) => ContractResponse` evaluated per served request                                   |
-| `times?`    | How many times it may serve. **Omitted = unlimited** (a re-render or a retry replays it). `n` = exhausted after `n` serves. |
-| `required?` | The chain FAILS unless it was actually requested — at least once, or exactly `times` times when `times` is set.             |
-
-### Selection
-
-One engine-agnostic queue serves every facet. An observed request matches a contract when the method matches (`'*'` accepted), the url matches, the declared query params and headers are a **subset** of the observed ones, and the `match` predicate — if any — passes on the body.
-
-**The first contract in list order that matches AND is not exhausted wins.** That single rule covers the two shapes you need:
-
-```typescript
-import { defineContracts, http } from '@jterrazz/test';
-
-// A retry sequence: three failures, then an unlimited tail.
-export default defineContracts(
-    { request: http.get('/quote'), response: http.error(500), times: 3 },
-    { request: http.get('/quote'), response: http.json({ quote: 'recovered' }) },
-);
-```
-
-If every matching contract is exhausted, or nothing matches at all, the spec fails (strict — see [below](#strict-by-construction-rule-d7)). A chain that declares **no** contract is not guarded at all: strictness begins with the first `.intercept()`.
-
-### `times` and `required` — saying what you mean
-
-`times` is how a spec asserts a **call count** without reaching for a spy: `times: 3` on a failing contract plus an unlimited success tail says "the app retries exactly three times before it succeeds". `required: true` is the other half — it turns a declaration nobody exercised into a failure:
-
-```typescript
-import { defineContract, http } from '@jterrazz/test';
-
-// If the screen never asks for the 1M range, the spec fails — instead of
-// passing green on a chart that silently rendered the default range.
-export default defineContract({
-    request: http.get('/indicators', { query: { range: '1M' } }),
-    required: true,
-    response: http.json({ points: [] }),
-});
-```
-
-Without `required`, a contract nobody calls is invisible: the test passes, and the assertion it was supposed to protect never ran.
-
-## `defineContracts` — it's contracts all the way down
-
-A test imports **one** artifact: the world its feature lives in. `defineContracts` composes contracts, lists, and other composites into it, recursively, order preserved.
-
-```typescript
-import { defineContracts, http } from '@jterrazz/test';
-
-const events = defineContracts({
-    request: http.get('/events'),
-    response: http.json({ items: [] }),
-});
-
-// A composite extends a composite — same function, all the way down.
-export default defineContracts(events, {
-    request: http.get('/articles/{{uuid}}'),
-    response: http.json({ id: 'a-1' }),
-});
-```
-
-### `.with()` — replacement by route, then prepend
-
-`.with(...)` derives a **variant** without mutating the base. Two steps, in this order:
-
-1. Every base contract whose **route** an override claims is removed. Same route = same `method` + the same declared url pattern (string equality of the declared path, `.source` equality for a RegExp).
-2. The overrides are **prepended**, keeping their own order.
-
-The prepend is what makes a _more specific_ override work without deleting the generic route it lives beside: `/articles/gone-1` does not claim the route `/articles/{{uuid}}`, so the generic contract survives — but the override is checked first, so the one article that is gone answers 410 while every other article still answers 200.
-
-```typescript
-import { defineContract, defineContracts, http } from '@jterrazz/test';
-
-const newsroom = defineContracts(
-    { request: http.get('/events'), response: http.json({ items: [] }) },
-    { request: http.get('/articles/{{uuid}}'), response: http.json({ id: 'a-1' }) },
-);
-
-export default newsroom;
-
-// A scenario: one article is gone, the rest of the world is unchanged.
-export const withArticleGone = (id: string) =>
-    newsroom.with(
-        defineContract({
-            request: http.get(`/articles/${id}`),
-            response: http.error(410, { error: 'gone' }),
-        }),
-    );
-```
-
-## The facade pattern
-
-The file layout follows the same split: a **public facade** per feature, **internal units** under it.
-
-```
-specs/<facet>/<feature>/
-├── <feature>.test.ts
-└── contracts/
-    ├── newsroom.contracts.ts              PUBLIC — default export = the world,
-    │                                      named exports = its scenarios
-    ├── http/
-    │   ├── events.ts                      a unit contract
-    │   ├── events.response.json           the payload it serves
-    │   ├── events.fr.response.json        a qualified payload — same owner
-    │   └── article-gone.ts                a factory: (id) => Contract
-    ├── openai/
-    │   ├── classify-article.ts
-    │   └── classify-article.request.ts    the exact prompt it matches
-    └── anthropic/
-        └── draft-reply.ts
-```
-
-The rules, enforced by [C4, C10 and C11](19-linting.md):
-
-- The **root** holds only `*.contracts.ts` facades and the provider directories `http`, `openai`, `anthropic`. The folder carries the provider — filenames drop it and go back to being business names.
-- A facade default-exports a `defineContracts(...)` composition; its **named exports are scenario factories** (`withArticleGone(id)`), so every variant of the world is named next to the world.
-- A unit contract is `<provider>/<kebab-name>.ts` and default-exports `defineContract(...)` or a factory returning one. Its `request` builder must name its own folder.
-- Data with real mass goes to a sibling `.response.json` (served) or `.request.ts` (matched). The stem before the FIRST dot pairs the data with its contract: `events.fr.response.json` belongs to `events.ts`. An orphan payload is an error.
-- **Tests import only `*.contracts.ts`.** Provider folders are internal — reaching into one from a test is an error (C10). A scenario belongs in the facade, not in the test.
-- Shared data has ONE owner: a second contract imports `./events.response.json` directly. No copies, no `shared/` folder.
-
-A unit contract may import `@jterrazz/test`, its neighbours inside `contracts/`, **and the app's own source** — importing the app's real prompt builder is preferred over pinning its output, so a domain change surfaces as a type error or a readable diff instead of a silent "unmatched request".
-
-```typescript
-// contracts/newsroom.contracts.ts — the facade a test imports
-import { defineContracts } from '@jterrazz/test';
-
-import articleGone from './http/article-gone.js';
-import events from './http/events.js';
-
-const newsroom = defineContracts(events);
-
-export default newsroom;
-
-export const withArticleGone = (id: string) => newsroom.with(articleGone(id));
-```
-
-```typescript
-// contracts/http/events.ts — a unit, with its payload beside it
-import { defineContract, http } from '@jterrazz/test';
-
-import payload from './events.response.json' with { type: 'json' };
-
-export default defineContract({
-    request: http.get('/events'),
-    response: http.json(payload),
-});
-```
-
-## Using them: `.intercept()`
-
-Every facet that reaches the network takes the same three forms:
-
-| Form                                | Use                                                        |
-| ----------------------------------- | ---------------------------------------------------------- |
-| `.intercept(contracts)`             | A composite — the normal case, one import per feature      |
-| `.intercept(contract)` / `([a, b])` | A single contract or a list                                |
-| `.intercept(request, response)`     | An inline pair, for one-off plumbing that deserves no name |
-
-```typescript
-import { http } from '@jterrazz/test';
-import { expect, test } from 'vitest';
-
-import { api } from '../api.specification.js';
-import newsroom from './contracts/newsroom.contracts.js';
-
-test('serves the declared world', async () => {
-    // Given - a one-off inline pair alongside the feature's world
-    const result = await api
-        .intercept(newsroom)
-        .intercept(http.any(/analytics\.example/), http.json({ ok: true }))
-        .get('/report');
-
-    // Then - the report rendered
-    expect(result.status).toBe(200);
-});
-```
-
-Repeated `.intercept()` calls **append**. Composition and override semantics live in `defineContracts` / `.with()`, never in call order.
-
-## `intercept()` — the same double, with no chain
-
-A module test has no runner and therefore no chain to hang contracts on, and its subject can still reach the network. `intercept(...)` is that case, and it takes the same three forms:
-
-```typescript
-import { http, intercept } from '@jterrazz/test';
-import { expect, test } from 'vitest';
-
-test('reads the rate off the provider', async () => {
-    // Given - the one call this module makes, declared for the block
-    await using _ = await intercept(http.get('https://rates.test/eur'), http.json({ rate: 1.07 }));
-
-    // Then - the module answers with what the provider replied
-    const response = await fetch('https://rates.test/eur');
-    await expect(response.json()).resolves.toStrictEqual({ rate: 1.07 });
-});
-```
-
-The scope is an `AsyncDisposable`: the handlers come off at the end of the block however the block ends, and an outgoing request no contract accepted is thrown THERE — the same strictness a chain gets (rule D7), which is what makes it a guard and not a convenience.
-
-**The refusal lands at DISPOSAL, not at the call.** An undeclared request is not rejected where the subject made it: the `fetch` proceeds and fails on its own, and the violation is raised when the scope closes. That is the right place, because a subject that catches its own network failures — a retry loop, an `onError` callback, a fallback value — would swallow a rejection thrown at the call site and the spec would pass on a call nobody declared. Disposal happens after the subject is done, so nothing can catch it.
-
-`await using _ = await intercept(…)` carries two awaits and both are load-bearing. The inner one waits for the engine to be listening; without it the subject could reach the real network before the first handler is in place. The shape refuses that spelling rather than leaving it to discipline: `intercept()` answers a promise, a promise is not an `AsyncDisposable`, and `await using _ = intercept(…)` does not compile.
-
-A file that declares the same world in several tests factors it into a function, and the two awaits survive the move — the helper is `async`, and it awaits what it hands back:
-
-```typescript
-async function rateProvider() {
-    return await intercept(http.get('https://rates.test/eur'), http.json({ rate: 1.07 }));
-}
-
-// In each test: await using _ = await rateProvider();
-```
-
-Both keywords are the rulebook's, not taste: a function returning a promise is `async` (`typescript/promise-function-async`) and a returned promise is awaited (`typescript/return-await`), so the other spellings do not lint.
-
-It is real in both runtimes — msw's server under node, msw's worker in a page — so a module test and a component test declare the outside world the same way. What it replaces is `vi.stubGlobal('fetch')` and a direct `msw/node` import, which rules F6 and F8 refuse a test and a consumer respectively.
-
-**A subject that fetches a PATH states where the path lives.** `fetch('/api/posts')` is browser code: under node the URL has no base, so the request fails before any contract can answer it. `intercept(contracts, { origin: 'http://console.test' })` gives the block that base — the relative call resolves against it, the contracts match as they would any other request (a path-form contract ignores the origin, an absolute one compares it), and `fetch` is put back when the scope ends. It is the seam's own wrapping, so no test has to own one.
-
-```typescript
-await using _ = await intercept(posts, { origin: 'http://console.test' });
-```
-
-**An empty list is refused.** `intercept(defineContracts())` guards nothing, and a subject with no network needs no intercept at all — the message says so. "This subject makes no network call" is said the other way round: declare the call with `http.unreachable()` on every feed it could reach, and the spec fails if it makes one.
-
-**A cancelled body does not settle, and here is why.** `response.body.cancel()` never resolves while msw is listening. Reading the same body with `.text()`/`.json()` resolves at once, and so does a `getReader().read()`; only the cancellation hangs.
-
-The cause is msw's, above the interceptor, and it is the STREAMS specification working as written: msw hands the caller one branch of a TEED stream — the other branch is its own, for the `response` lifecycle event it emits — and a tee branch's `cancel()` resolves only once BOTH branches have been cancelled. msw never cancels its own, so the caller's promise stays pending forever.
-
-Four measurements place it, on msw 2.15.0 with `@mswjs/interceptors` 0.41.9 under node 24:
-
-| Setup                                            | `body.cancel()` |
-| ------------------------------------------------ | --------------- |
-| a real server, nothing installed                 | 12 ms           |
-| `FetchInterceptor` alone, passing through        | 12 ms           |
-| msw listening, the request passing THROUGH to it | never           |
-| msw listening, the reply MOCKED                  | never           |
-
-So it is neither undici, nor the mocked body, nor `@mswjs/interceptors`, nor this package's seam: a passthrough request hangs exactly as a mocked one does, and the one thing both have that the interceptor alone has not is msw's tee. The nearest upstream issue, [mswjs/interceptors#799](https://github.com/mswjs/interceptors/issues/799), is a passthrough body closed as fixed, and it is the wrong layer. The repro is `specs/api/intercepts/body-cancel.spec.ts`, skipped: it is the acceptance test of the fix.
-
-That is the ONE escape rule M3 sanctions, and it is narrow because the upstream option carries no allow-list. A subject whose own code cancels a body keeps `vi.stubGlobal('fetch')`, behind a directive written on the call that states the defect:
-
-```typescript
-// oxlint-disable-next-line vitest/no-restricted-vi-methods -- reason: the subject cancels the reply body, which never settles through intercept() under msw's node interceptor (docs/16 § A cancelled body does not settle)
-vi.stubGlobal('fetch', fetchStub);
-```
-
-Every other subject has `intercept()`, and this one gets it back the day the seam answers.
-
-**Around a `.render()` the chain's registration wins.** A rendered unit's network is declared on the chain — `component.intercept(c).render(…)` — because the render registers its contracts last and its strictness is total ([07](07-component.md)). A module-scope `intercept()` opened around a `.render()` is shadowed by it and proves nothing. In a `.test.tsx`, `intercept()` is for code the TEST calls itself, never for what the render fetches.
-
-## Two engines, one queue
-
-| Facets              | Engine                                            | Notes                                                                               |
-| ------------------- | ------------------------------------------------- | ----------------------------------------------------------------------------------- |
-| `api`, `jobs`       | **MSW**, in-process                               | The app runs here, so its outgoing requests pass through this process               |
-| `website`, `mobile` | the **declared stub backend** (plain `node:http`) | Started by the runner, its URL injected/exposed; CORS and `OPTIONS` handled for you |
-
-Both consume the **same** selection queue, so a contract behaves identically on either side: first match wins, `times` exhausts, `required` verifies at chain end. The old divergence — consume-once on MSW, sticky-last on the stub — is gone; "sticky" is now just the default (`times` omitted), written down.
-
-The stub resets between chains, the way databases do: one chain = one terminal action, and its contracts replace the previous chain's wholesale.
-
-## Request builders
-
-### `http.*` — any URL
-
-```typescript
-import { http } from '@jterrazz/test';
-
-http.get('https://rates.example.com/v1/latest');
-http.get('/articles/{{uuid}}'); // path form: any origin, structural segment
-http.post('https://api.shoply.dev/orders', {
-    body: { user: { role: 'admin' } },
-    headers: { 'x-tenant': 'acme' },
-    query: { lang: 'en' },
-});
-```
-
-`http.get | post | put | patch | delete | any(urlOrPath, filter?)`. A **path-form** url (`'/articles/{{uuid}}'`) matches that path on **any origin** — the app's real host does not matter — and `{{token}}` segments match structurally ([15 — Tokens](15-tokens.md)).
-
-The optional `filter` narrows beyond method + URL, and these are **filters**, so subset is the right default:
-
-- `body`: an object is a deep **subset** match whose leaves may be `match.*` matchers; a string is a containment test; a RegExp is a `test()` over the raw text body.
-- `headers` / `query`: subset match (header names case-insensitive); a string value is **exact**, a RegExp is `test()`.
-
-### `openai.*` / `anthropic.*`
-
-| Builder                             | Targets                                                         | Filters                                           |
-| ----------------------------------- | --------------------------------------------------------------- | ------------------------------------------------- |
-| `openai.chat(filter?)`              | Chat Completions API                                            | `model`, `system`, `user`, `tools`, `temperature` |
-| `openai.responses(filter?, url?)`   | Responses API (AI-SDK style); `url` overrides the endpoint      | `model`, `system`, `user`, `tools`                |
-| `anthropic.messages(filter?, url?)` | Messages API; `url` overrides the endpoint for a custom gateway | `model`, `system`, `user`, `tools`                |
-
-### Matching: strings are EXACT
-
-A string filter on a provider builder means **exact equality**. Looser matching is explicit — a RegExp, or the code-only matcher `match.includes(...)`:
-
-```typescript
-import { defineContract, match, openai } from '@jterrazz/test';
-
-// Exact — the app's own builder produces the prompt, so it cannot drift.
-const PROMPT = 'Classify the article into one of: TECH, POLITICS, SPORT.';
-
-export default defineContract({
-    request: openai.chat({ user: PROMPT }),
-    response: openai.reply({ category: 'TECH' }),
-});
-
-// Looser, on purpose: per-run data makes an exact prompt impractical.
-export const byPrefix = defineContract({
-    request: openai.chat({ user: match.includes('Classify the article') }),
-    response: openai.reply({ category: 'TECH' }),
-});
-```
-
-Exactness is the default because a substring filter silently cross-matches: two prompts sharing a preamble both match the first contract, and the spec goes green on the wrong reply. `match.includes` is a code-only matcher, like `match.regex` — the `{{token}}` file vocabulary does not grow.
-
-## Response builders
-
-| Response                                   | Produces                                                                            |
-| ------------------------------------------ | ----------------------------------------------------------------------------------- |
-| `http.json(body, init?)`                   | JSON response — `init: { status?, headers?, delay? }`                               |
-| `http.text(body, init?)`                   | `text/plain` response                                                               |
-| `http.error(status, body?)`                | HTTP error, optional JSON body                                                      |
-| `http.empty(status = 204)`                 | Empty response                                                                      |
-| `http.stream(chunks, init?)`               | A body that arrives in PIECES — `init: { contentType?, delay?, status?, headers? }` |
-| `http.sse(events, init?)`                  | A server-sent event stream: one chunk per event, `text/event-stream`                |
-| `http.unreachable()`                       | No response at all: the request fails in TRANSPORT and the caller's `fetch` rejects |
-| `openai.reply(data)`                       | `data` wrapped in a valid Chat Completions envelope                                 |
-| `anthropic.reply(data)`                    | `data` (object or text) wrapped in a Messages envelope                              |
-| `openai.error(status)` / `anthropic.error` | Provider HTTP error (e.g. `429` rate limit)                                         |
-| `openai.timeout()` / `anthropic.timeout()` | A provider that never answers within the caller's timeout                           |
-| `openai.malformed(text)`                   | HTTP 200 whose assistant content is `text` — an unparseable payload to handle       |
-
-The point: your contract states the **business payload** (`{ category: 'TECH' }`) and the builder produces the provider's full wire format around it.
-
-`http.unreachable()` is the one that is not a reply. A subject usually has two failure branches — "the server said no" and "nothing answered" — and only a status can express the first. The second is what a caller meets when the service is not running, and it is the branch behind a message like _the server did not answer, check that it is running_; `http.error(503)` tests the other one. Both engines honour it: msw's node interceptor and its service worker share the response shape.
-
-### Streamed replies
-
-A subject that reads a reply AS IT LANDS — a token-by-token render, a progress bar, a client that reconnects on a half-read body — is specified by the chunks and their order, which a single serialised body cannot state. `http.stream()` and `http.sse()` say that, and all three engines honour them: msw's server, msw's worker, and the `node:http` stub the website and mobile facets serve from.
-
-```typescript
-import { http, intercept } from '@jterrazz/test';
-import { expect, test } from 'vitest';
-
-test('renders a streamed reply as its pieces land', async () => {
-    // Given - a provider answering in three pieces, ten milliseconds apart
-    await using _ = await intercept(
-        http.get('https://tokens.test/stream'),
-        http.stream(['Hel', 'lo, ', 'world'], { contentType: 'text/plain', delay: 10 }),
-    );
-
-    // Then - the reader sees them in that order
-    const response = await fetch('https://tokens.test/stream');
-    await expect(response.text()).resolves.toBe('Hello, world');
-});
-```
-
-`http.sse(events)` frames each event the way an `EventSource` reads it — `event:`, `id:`, `retry:` and one `data:` line per line of payload, then the blank line that ends the frame — and serves the lot as `text/event-stream`. An object payload is JSON; a string is sent as-is.
-
-| `SseEvent` field | Becomes                                                           |
-| ---------------- | ----------------------------------------------------------------- |
-| `data`           | the `data:` lines — an object is JSON, a string is sent verbatim  |
-| `event`          | the `event:` name; omitted, the client sees the default `message` |
-| `id`             | the `id:` the client echoes as `Last-Event-ID` when it reconnects |
-| `retry`          | the `retry:` hint, in milliseconds                                |
-
-Provider streams — `openai.reply({ stream: true })` and its Anthropic twin — are not here: no test on the workbench mocks a provider's wire protocol for a stream, and the three that stream mock the AI SDK's model instead. They arrive when one does.
-
-### Dynamic responses
-
-A `response` may be a function of the incoming request — `(request: MatchableRequest) => ContractResponse` — evaluated per served request:
-
-```typescript
-import { defineContract, http } from '@jterrazz/test';
-
-export default defineContract({
-    request: http.post('https://gateway.shoply.dev/v1/echo'),
-    response: (request) => http.json({ received: request.body }),
-});
-```
-
-The `request` handed to it is the same `MatchableRequest` the match ran on: `{ body, headers, url }`, with `body` already parsed when the payload is JSON. Prefer a fixed response whenever the reply is known ahead of time — a dynamic one is for echo endpoints, request-derived ids, and per-call variation.
-
-## Strict by construction (rule D7)
-
-The moment a chain declares one contract, the network is guarded: every outgoing request during the action must match a declared, non-exhausted contract. Anything else fails the spec with an explicit error that rejects the action promise (never an unhandled rejection):
-
-```
-Unmatched outgoing HTTP request during spec: POST https://api.openai.com/v1/chat/completions
-Declared contracts:
-  - POST https://api.openai.com/v1/chat/completions (exhausted)
-Every outgoing request of a chain that declares contracts must match one — declare it, or raise `times`.
-```
-
-At chain end the same channel verifies `required` contracts: one that was declared and never requested fails the spec, naming its route.
-
-Two scoping notes:
-
-- **A chain with zero contracts does not guard its network** — a deliberate, documented boundary.
-
-## Pitfalls
-
-- **Reaching into a provider folder from a test.** `import events from './contracts/http/events.js'` is an error (C10). Add a named scenario export to the facade instead — that is what facades are for.
-- **Pinning a prompt by copying it.** A 550-line prompt pasted into a contract is a fossil. Import the app's real builder, or match a stable prefix with `match.includes` — the contract pins the _interaction_, not the wording.
-- **Expecting a substring to match.** Provider string filters are exact. A prompt that "should obviously match" but does not is almost always a whitespace or a template difference — use `match.includes` if that is genuinely what you mean.
-- **Writing a call count as a loop.** `for (…) chain.intercept(garbage)` is `times: 8`. The loop hides the number the spec is actually asserting.
-- **Relying on declaration specificity instead of order.** Selection is first-match. `.with()` prepends precisely so an override wins without deleting the generic route — outside `.with()`, order is yours to get right.
-- **Letting a pipeline hit the network.** An unintercepted call is a test escaping the sandbox, not extra realism. Once one contract is declared, D7 turns a stray call into a failure.
-- **Duplicating a payload.** The 45-line article exists ONCE, as a `.response.json`; the second contract imports it.
-
-## Related
-
-[10 — API specs](10-api.md) · [11 — Jobs specs](11-jobs.md) · [08 — Website specs](08-website.md) · [09 — Mobile specs](09-mobile.md) · [18 — Conventions](18-conventions.md)

package/docs/17-services.md

@@ -1,188 +0,0 @@
-# 17 — Services: databases, caches, and their init scripts
-
-Infrastructure is declared as a **named record** of service factories on the runner. The record key is the ONLY name a service has: it is your test vocabulary in `.seed()` / `.table()` targeting, it types the `server`/`jobs` factory parameters, it is the name the startup report prints, and — kebab-cased — it is the folder the service reads its init script from. A handle carries no second name of its own.
-
-## Service factories
-
-All four import from the package root (rule F1):
-
-```typescript
-import { postgres, process, redis, sqlite } from '@jterrazz/test';
-```
-
-| Factory      | Backing                                            | Options                                                       | Connection string shape               |
-| ------------ | -------------------------------------------------- | ------------------------------------------------------------- | ------------------------------------- |
-| `postgres()` | Docker container                                   | `image`, `env`                                                | `postgresql://user:pass@host:port/db` |
-| `redis()`    | Docker container                                   | `image`                                                       | `redis://host:port`                   |
-| `sqlite()`   | **No Docker** — a template file copied per worker  | `init` (SQL file) or `prismaSchema` (runs `prisma db push`)   | `file:/…/….sqlite`                    |
-| `process()`  | **No Docker** — a child process the framework owns | `command`, `ready`, `port`, `cwd`, `env`, `before`, `timeout` | `http://127.0.0.1:port`               |
-
-**Each factory names its own optional peer**, and names it at startup rather than at install time: `postgres()` and `redis()` need `testcontainers` (and `pg` / `redis` for the driver a table read uses), `sqlite()` needs `better-sqlite3`, and `process()` needs nothing but node. A project that declares none of them installs none of them — the seams are optional peers since 16.0, loaded lazily by the one module that owns each ([04 — Operating](04-operating.md#what-a-consumer-must-bring)). The refusal, when one is missing, names the facet that asked, the peer, the install command of the package manager the project's own lockfile names, and — under pnpm — the `onlyBuiltDependencies` line a native binding also needs before it is built at all.
-
-`image` overrides the container image and `env` (postgres only) the environment variables; each factory carries a default for both, so a record that states neither still starts a real service. After the runner starts, each service handle exposes `.connectionString`, which is what you pass to your app:
-
-```typescript
-export const { api, cleanup } = await specification.api({
-    services: {
-        db: postgres(), // → reported as "db", init from docker/db/
-        analyticsDb: postgres(), // → "analytics-db", init from docker/analytics-db/
-        cache: redis(), // → "cache"
-    },
-    server: ({ db, analyticsDb, cache }) =>
-        createApp({
-            databaseUrl: db.connectionString,
-            analyticsDatabaseUrl: analyticsDb.connectionString,
-            redisUrl: cache.connectionString,
-        }),
-});
-```
-
-## `process()` — the one shape an external process takes
-
-A site's dev server, an API the site calls, the bundler a simulator loads from: each of them is a command, a way of knowing it is ready, and a lifetime. `process()` is the one shape for all three, and the framework owns the lifetime — without it each would be declared somewhere else, and the last one would be a `beforeAll` spawning a child and an `afterAll` that sometimes forgets to kill it.
-
-The options type is `ProcessOptions` — one shape for the one external process every facet starts.
-
-| Option    | Means                                                                                                                                                                                   |
-| --------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `command` | the shell command that starts it, receiving the chosen port as `PORT`                                                                                                                   |
-| `ready`   | a **path** polled until it answers (default `/`), or a **RegExp** over the child's output whose one capture group is the port                                                           |
-| `port`    | a fixed port instead of a free one the OS assigns                                                                                                                                       |
-| `cwd`     | a working directory relative to the project root                                                                                                                                        |
-| `env`     | the child's environment — an object, or a function of the services started beside it                                                                                                    |
-| `before`  | a one-shot command run ONCE per evaluation of the specification module — under vitest's default isolation, once per test file — which must exit 0: a build, a migration, a fixture load |
-| `timeout` | the readiness budget, in milliseconds (default 30 000)                                                                                                                                  |
-
-It sits in a `services` record like any other service, so it starts after the databases and can be handed their connection strings, and it is stopped with the specification:
-
-```typescript
-import { postgres, process, specification } from '@jterrazz/test';
-
-const api = process({
-    before: 'make build',
-    command: 'bin/server web --port $PORT',
-    env: ({ db }) => ({ DATABASE_URL: db.connectionString }),
-    ready: '/health',
-});
-
-export const { cleanup, website } = await specification.website({
-    server: (services) =>
-        process({
-            command: 'next dev',
-            env: { NEXT_PUBLIC_API_URL: services.api.connectionString },
-        }),
-    services: { api, db: postgres() },
-});
-```
-
-`website()` and `mobile()` take a `services` record for exactly this: a site started beside the API it calls, a simulator started beside its Metro bundler (`process({ command: 'expo start', ready: /Metro waiting on .*:(\d+)/ })`). What used to be a bundler bootstrap the repository maintained is a declaration.
-
-**The run's id is minted, never sampled.** Every process of one specification is handed `TEST_RUN_ID` in its environment — one value per RUN, where a run is one evaluation of the specification module, so two test files importing the same specification get a child each with an id of its own. A test that needs a label unique to its run reads that variable; it never builds one from `Date.now()` or `Math.random()`, which rule D16 refuses under an oracle and which makes two runs of the same suite disagree.
-
-## The services record — three jobs for one key
-
-1. **Vocabulary.** The key is how tests target the service: `.seed('x.sql', { database: 'analyticsDb' })`, `result.table('events', { database: 'analyticsDb' })`. Typed — a typo is a compile error.
-2. **Typing.** The `server` / `jobs` factory receives the exact same record, fully typed, once everything is started (rule A8).
-3. **Identity.** The key is the name the service is known by: the startup report prints it, and its **kebab-case** conversion is the folder the init script is read from — `analyticsDb` reports as `analytics-db` and initialises from `docker/analytics-db/init.sql`, with no option to state anywhere:
-
-    ```typescript
-    services: {
-        db: postgres(), // → "db"
-        analyticsDb: postgres(), // → "analytics-db"
-    }
-    ```
-
-In CLI mode, the record additionally drives env injection into the child process: `<KEY>_URL` per service — the key uppercased to **CONSTANT_CASE** at camelCase boundaries (`analyticsDb` → `ANALYTICS_DB_URL`) — plus `DATABASE_URL` / `REDIS_URL` when unambiguous (rule B6 — see [CLI specs](12-cli.md#auto-injected-connection-urls-rule-b6)).
-
-### The `database:` rule (A7)
-
-With **2 or more databases** in the record, `database:` is mandatory on every `.seed()` and `.table()`. With exactly **one**, it is forbidden (redundant). There is no in-between: the option is either always present or never present within a project.
-
-```typescript
-// one database → no database: anywhere
-await migrateCli.seed('legacy-schema.sql').exec('up');
-await expect(result.table('schema_migrations')).toMatchRows({ … });
-
-// two databases → database: everywhere
-await api.seed('catalog.sql', { database: 'db' }).request('new-order.http');
-await expect(result.table('events', { database: 'analyticsDb' })).toMatchRows({ … });
-```
-
-## `docker/<service>/init.sql`
-
-```
-docker/
-├── db/
-│   └── init.sql            # schema for the "db" service — runs on service start
-└── analytics-db/
-    └── init.sql            # schema for the "analytics-db" service
-```
-
-- `docker/<service>/init.sql` executes when the corresponding service starts — matched by the **kebab-case of the record key**, so the analytics schema above belongs to `analytics-db/` (the folder `analyticsDb` names).
-- A project with one database needs no folder of its own: a postgres handle falls back to `docker/postgres/init.sql` when nothing sits under its own name.
-- Testcontainers starts each declared service from the handle's image and environment. There is no second definition of the stack to keep in step.
-
-## A contract's `required` is verified per `.call()`
-
-A chain's scope is ONE terminal action, and a contract's `required` is checked at the end of it — not at the end of the test, and not at the end of the file. A spec that declares a contract and then performs two actions has declared it for the first one: the second starts a fresh registration, and a `required` contract unmet by the action it belongs to fails that action's chain.
-
-This is the same boundary rule B1 already states from the other side — one chain, one action — read from the contract's end. A test that wants a contract to hold across two actions writes two chains, each declaring what it expects to see.
-
-## Per-worker isolation (rule G2)
-
-Vitest runs test files in parallel workers; the framework isolates them automatically — no configuration, no sharding:
-
-| Service      | Isolation strategy                  |
-| ------------ | ----------------------------------- |
-| `postgres()` | Cloned schema per worker            |
-| `redis()`    | Dedicated database index per worker |
-| `sqlite()`   | Template file copied per worker     |
-
-On top of worker isolation, **every chain resets the databases** (rule B1): a spec starts from seeds, never from a previous spec's leftovers.
-
-## Root auto-discovery (rule A9)
-
-The framework locates the project root by walking **up from the specification file** to the **nearest** directory carrying `package.json`, so in a workspace the member being tested wins over the repository root above it. The `root` option is an override for the cases where the convention cannot work (e.g. fixtures deliberately kept outside the package) — pointing `root` at the directory the walk would find anyway is redundant (future lint warning).
-
-## SQLite without Docker
-
-For CLIs (or apps) on SQLite, tests run with zero Docker:
-
-```typescript
-export const { cli, cleanup } = await specification.cli('shoply', {
-    services: {
-        db: sqlite({ init: './schema.sql' }), // schema from a SQL file
-        // or: db: sqlite({ prismaSchema: './prisma/schema.prisma' })
-    },
-});
-```
-
-`sqlite()` builds a template database once (from `init` SQL or by running `prisma db push` on `prismaSchema`), then hands each worker its own copy. `.seed()` and `result.table()` work identically to Postgres.
-
-`prismaSchema` is resolved against the **current working directory** and passed to the CLI as `npx prisma db push --force-reset --schema <absolute path>` — the schema is named explicitly, so it does not have to be the one Prisma would discover from a `prisma.config.ts` at the cwd. Declare no `prismaSchema` and the bare invocation runs, leaving discovery to Prisma.
-
-### Where the template lives
-
-The template is a **project** artefact: `<root>/.artifacts/vitest/sqlite/template-<sha8>.sqlite`, under the root A9 discovered ([above](#root-auto-discovery-rule-a9)) and covered by the same `.gitignore` line as everything else in `.artifacts/` ([02 — Developing](02-developing.md#artefacts-live-under-artifacts)).
-
-It used to live in the machine-global OS tmpdir, where two checkouts of one repository shared a single file: whichever ran first built it, the other silently inherited that schema, and a branch that changed the schema poisoned the branch beside it. A path under the project root cannot be reached from another checkout at all. Deleting `.artifacts/` is how you force a cold rebuild.
-
-The file name stays **keyed on the schema** — the digest taken over the kind of schema (`init` / `prismaSchema`), its resolved path and its content. Within one project that is what makes reuse mean "the same schema": edit a schema and the next run builds a new template instead of reading the old one, whose header is perfectly valid and whose tables are wrong.
-
-### One worker builds, the others wait
-
-Workers race for a cold cache, so the build is serialised by a lock beside the template — and a worker that loses the race **waits** for the winner rather than building too. It is taken with an exclusive create, so exactly one worker can win it; the check-then-write it replaced let several believe they had won, and the concurrent `prisma db push` calls that followed died on `database is locked`. A suite kept sequential (`fileParallelism: false`) only for that reason can go parallel again.
-
-Two more properties fall out of it: the winner builds on a private path and **renames** the finished file into place, so a reader never sees a half-built template (the SQLite header is written long before the tables are); and a lock nobody has touched for two minutes is treated as a crashed holder's and broken, so a killed worker cannot wedge the suite.
-
-## Pitfalls
-
-- **Naming the `init.sql` folder after the raw record key.** The folder is the key's **kebab-case** form: key `analyticsDb` reads `docker/analytics-db/init.sql`, not `docker/analyticsDb/`.
-- **Sharing state across specs "because the container is shared".** The container is shared; the data is not — chains reset databases (rule B1), and workers are isolated (rule G2).
-- **Passing `root` that auto-discovery would have found.** Redundant override (rule A9).
-- **Reading a green local run as proof that `prismaSchema` is wired.** The template is cached across runs, so a checkout that built it once never re-runs `db push` — a schema path that would fail on a fresh clone (or in CI) stays invisible. Delete `.artifacts/vitest/sqlite/` to test the cold path.
-- **Counting `sqlite()` + `redis()` as "2 databases" for rule A7.** The rule counts **databases**; with one SQL database and one redis, `database:` stays forbidden on `.seed()`/`.table()` and `DATABASE_URL`/`REDIS_URL` are both unambiguous for CLI injection (rule B6).
-
-## Related
-
-[10 — API specs](10-api.md) · [11 — Jobs specs](11-jobs.md) · [12 — CLI specs](12-cli.md) · [18 — Conventions](18-conventions.md)