@jterrazz/test 16.1.0 → 17.0.0

package/docs/04-operating.md

@@ -1,101 +0,0 @@
-# 04 — Operating
-
-This repository ships one thing: the npm package `@jterrazz/test`. Nothing here deploys, nothing here runs as a service, and merging to `main` publishes nothing — a release is a deliberate, separate act. This chapter says what that act is, what leaves the tree when it happens, and what a consumer has to have for the published artefact to work.
-
-## Releasing
-
-A release is three steps, in this order.
-
-1. **Bump and land the version.** The version in `package.json` moves, alone, in a commit whose subject is `chore: <version> — <what changed>`. The commit log is the changelog: this repository carries no `CHANGELOG.md`, by decision, and the release notes plus that subject line are the record.
-2. **Create the GitHub release**, tagged at that commit. This is the trigger and the only one — `.github/workflows/release.yaml` listens on `release: types: [created]`.
-3. **Watch the gate.** The workflow delegates to the estate's `jterrazz/jterrazz-actions/.github/workflows/release-npm.yaml`, which runs the FULL validate job first — the same build, lint and test the push gate runs, chromium included — and publishes only if it is green.
-
-The publish step is `npm publish --access public --provenance`, on Node 24, with `id-token: write` granted so npm records a provenance attestation linking the tarball to the workflow run that built it. The registry is npm's, stated as `publishConfig` in the manifest.
-
-Because validate runs inside the release workflow, a red suite stops a publication rather than a merge. That is the design: the tree on `main` is always publishable, and nothing decides for you when it is published.
-
-## What leaves the tree
-
-The tarball is what `files` declares and nothing else: `dist/`, minus `dist/catalog.*` and `dist/coverage.*`, plus `docs/` and `schema/`. The catalogue generator is a development gesture with no consumer — it writes this repository's own projections — so it is built but never shipped.
-
-**The manual ships with the code**, because the code points at it: every relative link of the shipped `README.md` and every `(… — see docs/19-linting.md#…)` a rule message ends on is read from inside an install, and a chapter that is not there makes both a dead end. The `package-exports` meta-test holds it — a citation whose file the manifest does not publish fails the suite.
-
-The entries that reach a consumer are the whole public contract, and they are listed once — [01 — Architecture § What the tree publishes](01-architecture.md#what-the-tree-publishes). What matters here is only that the ROOT entry resolves by CONDITION: a bundler serving a page takes `browser`, node takes `import`, and both are described by one `types` entry.
-
-One binary ships with them: `jterrazz-test-check`, the conventions checker, pointed at `dist/checker.js`. It answers three runs — a specs tree by path, one workspace member with `--member`, and the whole project path-less (a path that is NOT a specs tree is read as a project root and takes that third run, anchored there) — and `--format json` publishes the findings under the `jterrazz-check(<id>)` codes ([19 — Linting](19-linting.md#the-member-pass-and-the-json-contract)). When `typescript check` runs it, which install it resolves it from, and what the floor version is, are the toolchain's: `@jterrazz/typescript` `docs/06-quality-checks.md` § The Test Conventions pass.
-
-## What a consumer must bring
-
-The package refuses to guess at its environment, so several things it uses are the consuming project's to install.
-
-- **`vitest ^5` is the required peer**, and the only one: the framework registers its matchers into vitest, and there is no standalone runner. Why 5 alone, why the four native seams became optional peers, and where every artefact goes: [ADR-008](decisions/008-vitest-5-node-24-and-the-native-seams-as-optional-peers.md).
-- **Every seam is an OPTIONAL peer**, loaded lazily by the one module that owns it and NAMED at startup when it is missing: `playwright` for a page, `appium`/`webdriverio` for a screen, `@vitest/browser-playwright`, `vitest-browser-react`, `vite`, `react` and `react-dom` for a component, and the four native ones — `better-sqlite3`, `pg`, `redis`, `testcontainers` — for the services a chain declares. A project that specifies none of those installs none of them.
-
-    The refusal names the facet that asked, the peer, and the install command of the package manager the project's own lockfile names. Under pnpm a native binding also has to be listed to be BUILT, so the message adds that line:
-
-    ```
-    sqlite() requires `better-sqlite3`, an optional peer dependency of @jterrazz/test: pnpm add -D better-sqlite3.
-    Under pnpm the binding is not built unless the package is listed: add "better-sqlite3" to `onlyBuiltDependencies`
-    in package.json (or `only-built-dependencies` in .npmrc) and reinstall.
-    ```
-
-    **A native peer has a second way of not being there**, and it is the one that costs an afternoon: the package installed, and its `.node` never compiled, because the package manager withheld the install script — npm since 11, pnpm since 10 and bun since 1.2 all do, by default. `sqlite()` opens one in-memory database the first time it loads the driver, so that failure is caught where it can be named rather than surfacing as a `bindings` stack trace from whichever spec seeded first:
-
-    ```
-    sqlite() found `better-sqlite3` but its native binding is not built — npm does not run a
-    dependency's install script unless it is told to: npm install-scripts approve better-sqlite3
-    && npm rebuild better-sqlite3.
-    ```
-
-    ([ADR-008](decisions/008-vitest-5-node-24-and-the-native-seams-as-optional-peers.md) records what the four seams cost as dependencies and what the change buys under each package manager.)
-
-- **The browser provider is pinned to the runner, patch included.** `@vitest/browser-playwright@X` peers `vitest: X` EXACTLY, so the two move together in one change or not at all. This package therefore declares the provider as `*` rather than a range of its own — a second, weaker statement of a constraint the provider already makes would be wrong the day the pair moves — and `component()` asserts the equality when the project is built, naming both versions:
-
-    ```bash
-    npm install -D vitest@5.0.1 @vitest/browser-playwright@5.0.1   # one unit, both versions
-    ```
-
-    The peer range is `^5` and nothing else: Vitest 5 is where the artefact paths the preset routes exist, and a package holding two majors would be holding two answers about where a run writes.
-
-- **Docker must be running** for the container-backed services. `sqlite()` and plain CLI specs need none.
-- **Node 24 or newer**, as `engines` states — the toolchain's floor, and vitest 5's.
-- **A chromium**, for a page or a component: `npx playwright install chromium`, once. The component facet drives the same browser the website facet does, through the same peer.
-- **The ARIA dialect a tree golden is written in is Playwright's**, produced by its `ariaSnapshot()` and therefore PINNED by the `playwright` peer: a major of that peer can reword a role line, and every committed `.aria.yaml` moves with it in one regeneration. It is the same dialect on a page and on a mounted unit ([07 — Component specs](07-component.md), [14 — Assertions](14-assertions.md)).
-- **A Vite the peer range names** — `^6.4 || ^7 || ^8`. `component()` reads the installed major and states the JSX default on the key that Vite transforms with (`oxc` from 8, `esbuild` before it), so a project that states no pipeline of its own gets the automatic runtime on every one of the three. This package's own suite runs on Vite 8.1; the Vite 7 path is exercised by a consumer, not by this suite — see [07 — Component specs](07-component.md).
-
-`msw` is a direct dependency, not a peer — outgoing interception is part of the framework rather than a choice a consumer makes.
-
-## The footprint it leaves
-
-Nothing persistent. Inside a consuming project the framework writes only under `.artifacts/` — vite's transform cache, the coverage directory if a provider is installed, and the SQLite schema template it reuses across runs. Everything else it creates is per-RUN scratch in the OS temp directory: the fresh working directory of each CLI spec, the per-worker database copies, the profile directory a browser or a simulator needs. One `rm -rf .artifacts` is a clean slate, and [02 — Developing](02-developing.md) holds the table of what lands where.
-
-Containers are the one resource that outlives a process badly, which is why `afterAll(cleanup)` is a rule and not a suggestion: a suite that forgets it leaks its infrastructure into the next one.
-
-## What a 16.0 adoption meets
-
-The renames and the new rows land through the toolchain's own flow, with three
-things to know before they surprise a reader:
-
-- **A member whose ROOT is the specs tree** (`packages: ['specs']`) is judged by
-  `jterrazz-test-check .` or by a path-less run from that member. The
-  toolchain's own walk looks for a CHILD directory named `specs`, so until it
-  makes the same move its Test Conventions pass reports the member findings
-  alone — `TODO.md` carries the ask.
-- **An include entry that names `.test.ts`** stops collecting the moment `--fix`
-  renames a facet spec. The mover names the ones it BROKE — a glob whose prefix
-  covers a file it moved, a literal naming one, and never a comment — so a
-  notice is always about a file that just moved; update them in the same commit,
-  and E7w holds the class afterwards.
-- **`typescript baseline` in an npm-hoisted member** cannot resolve oxlint
-  today, so the step the adopt flow prescribes "where red" has to be run from a
-  directory where `node_modules/.bin/oxlint` does resolve. Also in `TODO.md`.
-
-## Pitfalls
-
-- **Pushing the bump and expecting a publish.** `main` is not a release trigger. Without a created GitHub release, the version on npm does not move.
-- **Releasing from a red tree.** The workflow will refuse, and it refuses AFTER the tag exists — so the tag has to be re-cut once the fix lands.
-- **Adding a file to the tarball by putting it in the repository.** Only what `files` names ships. A new published asset is a manifest change, and a deliberate one.
-
-## Related
-
-[01 — Architecture](01-architecture.md) · [02 — Developing](02-developing.md) · [03 — Testing](03-testing.md)

package/docs/05-module-tests.md

@@ -1,152 +0,0 @@
-# 05 — Module tests (`*.test.ts`, beside the module)
-
-A module test is the majority kind: one file of source code, met through its own exports, with nothing started. It needs no constructor, no folder and no runner — it is the rung the doubles ladder opens on, and the one every other chapter measures itself against.
-
-| The shape           | Held below                                                         |
-| ------------------- | ------------------------------------------------------------------ |
-| What it specifies   | [What it specifies](#what-it-specifies)                            |
-| Where it is written | [The constructor: there is none](#the-constructor-there-is-none)   |
-| The chain           | [The chain: there is none either](#the-chain-there-is-none-either) |
-| What it may hold    | [What it may and may not do](#what-it-may-and-may-not-do)          |
-| The result          | [The result is the return value](#the-result-is-the-return-value)  |
-| What only it does   | [Unique here](#unique-here)                                        |
-| What it will refuse | [Pitfalls](#pitfalls)                                              |
-
-## What it specifies
-
-A module test answers one question: **given these inputs and these ports, what does this module return, and what does it ask of its collaborators?** Its subject is a unit of code, so it sits beside that code:
-
-```
-src/domain/posts/
-├── ranking.ts
-├── ranking.test.ts          # the module's spec — the `.test.ts` suffix IS the kind
-└── ranking.fixtures.ts      # the payloads it feeds itself, if any
-```
-
-The suffix decides which project collects the file and therefore which rules judge it. `unit()` takes `**/*.test.ts` outside `specs/` and excludes `**/*.test.tsx`; a `.test.ts` UNDER `specs/<facet>/` is rule C12's error, with the fix "rename it `.spec.ts`", and a rendered thing in a `.test.ts` is rule G4's, with the fix "rename it `.test.tsx`" ([07 — Component specs](07-component.md)).
-
-Nothing in this kind is slow, so the `unit` project is the one every developer runs on every save: this package gates its own at twelve seconds ([03 — Testing](03-testing.md#the-seven-projects)).
-
-## The constructor: there is none
-
-Every facet below this chapter starts something — a server, a database, a binary, a browser, a simulator — so every one of them has a `*.specification.ts` holding what was started. A module starts nothing. This kind has no folder under `specs/` at all — no specification file, and no project helper to configure beyond `unit()`.
-
-That is the fork's whole criterion, and it runs both ways: the moment a test needs a real service, a real binary or a real screen, it is no longer this kind, and the chapter that owns it says which one it became ([18 — Conventions § The fork](18-conventions.md#the-fork--which-kind-of-test-this-is)).
-
-## The chain: there is none either
-
-A module test is plain vitest: `test`, `expect`, the native matchers. What the framework adds are four primitives it may reach for by name — and each of them is a scope that gives back what it took.
-
-```typescript
-import { clock } from '@jterrazz/test';
-import { expect, test } from 'vitest';
-
-import { twoPosts } from './ranking.fixtures.js';
-import { rank } from './ranking.js';
-
-test('ranks a fresher post above an older one of equal score', () => {
-    // Given - two posts of equal score, one written this morning
-    using _ = clock.at('2026-03-04T09:30:00Z');
-
-    // Then - the fresher one leads
-    expect(rank(twoPosts).map((post) => post.id)).toStrictEqual(['fresh', 'stale']);
-});
-```
-
-## What it may and may not do
-
-The table is the rule set, and every row names the rule that holds it ([19 — Linting](19-linting.md)).
-
-| May                                                                                                                            | May not                                                                                                                                 | Rule         |
-| ------------------------------------------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------- | ------------ |
-| import its module and pure helpers; a sibling `<file>.fixtures.ts`                                                             | import a data asset (`.json` / `.txt` / `.sql` / `.yaml`); keep a `__mocks__/` or `__fixtures__/` directory                             | I4           |
-| `mockOf<Port>()` / `mockOf<Port>({ deep: false })` for an injected interface; `vi.fn<Fn>()`; `vi.spyOn` on an object passed in | `vi.mock` / `vi.doMock`, except a specifier on the consumer's `modules` allow-list with the reason written beside it                    | I4           |
-| `await using _ = await intercept(http.get(url), http.json(…))`                                                                 | `vi.stubGlobal('fetch')`, `msw/node`, `nock`                                                                                            | M3, F6       |
-| `using _ = clock.at('2026-03-04T09:30:00Z')`; `using _ = clock.run()`; `await clock.advance(ms)`                               | `Date.now()`, zero-argument `new Date()`, `Math.random()`, `randomUUID()` reaching an oracle; `vi.useFakeTimers` / `vi.setSystemTime`   | D16/D16w, M3 |
-| `vi.stubEnv('X', 'y')` for a module whose contract IS an env read — it restores itself                                         | `process.env.X = …`, a raw assignment nothing gives back                                                                                | E9w          |
-| flat `test()`; one level of `describe` for grouping; a `test.each` table (B4 judges the table once, not once per row)          | a nested `describe`; a `beforeEach` / `beforeAll` that builds the Given                                                                 | J10, J6w     |
-| `expect(text(value)).toContain(…)`; `toStrictEqual` against a literal                                                          | a golden (`toMatch('<file>')`) — a module with a golden is an integration spec ([06](06-integration.md)); any `toMatchSnapshot` matcher | D20          |
-| —                                                                                                                              | `document` / `window` / `navigator`; `@vitest-environment happy-dom`; `react-dom/server`                                                | G4, E5, F6   |
-
-A module that fetches a RELATIVE url is browser code and cannot run under node as it stands: either state where it resolves (`intercept(contracts, { origin })`, below) or specify it where it renders — a component spec.
-
-### Doubles
-
-`mockOf<Port>()` is the fourth rung of the ladder and the only one a module test builds itself. It is deep by default: reading a member nobody stubbed hands back another double, however far the port nests. `{ deep: false }` gives the flat proxy — every member of the port and nothing beneath them, which is what a port with a nested namespace wants when the test only ever touches the first level.
-
-```typescript
-const gateway = mockOf<PaymentGateway>();
-const settings = mockOf<Settings>({ deep: false });
-const onDone = vi.fn<() => void>();
-```
-
-Everything else the ladder refuses is refused here by name: `vi.mock` doubles a module for everyone, so it is I4's error unless a native module a consumer cannot inject earns an allow-list entry with its reason — matched in either spelling, `vi.mock('<spec>')` and the `vi.mock(import('<spec>'))` form `vitest/prefer-import-in-mock` asks for, so the two rules have a spelling they both accept; `vi.stubGlobal` is the network replaced by a function the test wrote, so it is M3's ([18 — Conventions § The doubles ladder](18-conventions.md#the-doubles-ladder)).
-
-### `intercept()` — the network, declared, with no chain
-
-A module that reaches the network states what it expects to find there, in the same contract vocabulary every facet uses — the same double, with no chain to hang it on.
-
-```typescript
-test('reads the feed the gateway publishes', async () => {
-    // Given - the feed answers with two posts
-    await using _ = await intercept(
-        http.get('https://console.test/api/posts'),
-        http.json({ posts: [{ id: 'fresh' }, { id: 'stale' }] }),
-    );
-
-    // Then - the client hands back what the feed carried
-    await expect(fetchPosts()).resolves.toHaveLength(2);
-});
-```
-
-The two awaits, `{ origin }` for a subject that calls a RELATIVE url, the refusal of an empty contract list, and everything about the contracts themselves — selection, `times`, `required`, the facades, the streams — are [16 — Contracts § `intercept()`](16-contracts.md#intercept--the-same-double-with-no-chain)'s.
-
-### Time
-
-`clock.at(iso)` pins `Date` and nothing else, so a subject that awaits, polls or renders keeps running. `clock.run(iso?)` takes the scheduler too — `setTimeout` and friends queue instead of firing — and `await clock.advance(ms)` is what makes them due; that is the one primitive for a subject whose behaviour IS elapsed time (a debounce, a retry backoff), where waiting for real would be the arbitrary sleep J2 forbids. One clock per test: a second scope taken inside the first is refused rather than nested, because ending the inner one would silently end the outer one too.
-
-### Fixtures
-
-A payload a module test feeds itself lives in a sibling `<file>.fixtures.ts` — TypeScript, type-checked with the test, reviewed in the same diff. A `.json` beside a module test is I4's error: an asset the compiler never reads is a second source of truth, and the kind that legitimately owns assets is the one that has a folder for them.
-
-### Tables
-
-`test.each` is the form for a rule with many cases, and B4 judges the table ONCE — the Given/Then narration is written on the table, not repeated in every row.
-
-```typescript
-test.each([
-    { expected: 'fresh', label: 'a fresher post of equal score', posts: equalScore },
-    { expected: 'high', label: 'a higher score of equal age', posts: equalAge },
-])(
-    // Given - $label
-    // Then - it leads the ranking
-    'ranks $label first',
-    ({ expected, posts }) => {
-        expect(rank(posts)[0]?.id).toBe(expected);
-    },
-);
-```
-
-## The result is the return value
-
-There is no result object here, because there is no chain to hand one back. The subject is the module's own return value, its thrown error, or a call recorded on a port double — and those are vitest's native matchers' to judge ([14 — Assertions](14-assertions.md#scalars--native-expect)). `text(value)` is the one helper that borrows the framework's stream vocabulary for a plain string.
-
-## Unique here
-
-- **It is the only kind with no folder.** Every other kind is collected by a path (`specs/<facet>/`); this one is collected by a suffix, beside what it specifies. Moving a module test away from its module is C18's error in one direction and C12's in the other.
-- **It is the only kind that may build its own double.** Below this chapter a double is DECLARED — a contract, a service, a seeded row — because the subject is an assembled product and the test does not hold its wiring. A module test is handed the wiring, so `mockOf` is in its hands.
-- **It is the only kind with no golden.** A golden is a file, and a file beside a module test is an asset; a module whose answer deserves a golden is describing something assembled, and the integration facet is where that goes ([06](06-integration.md#the-golden-half--a-pure-module-no-services-at-all)).
-- **It is the kind the budget is written for.** The `unit` project is the fast one, and this package gates its own at twelve seconds so the loop stays a loop.
-
-## Pitfalls
-
-- **Reaching for `vi.mock` to avoid injecting a port.** The mock outlives the test's intent: every importer of that specifier gets the double, and the design pressure the injection would have applied is gone. Double the port.
-- **`vi.setSystemTime` instead of `clock`.** A fake timer taken without `using` outlasts the test that took it, and the next test in the file inherits a clock nobody declared. M3 refuses it and names the primitive.
-- **Importing a `.json` payload.** I4 refuses it. Put the payload in `<file>.fixtures.ts`, where the compiler reads it.
-- **Nesting `describe`.** One level groups; two describe a structure the test file does not have. J10 refuses the second.
-- **Asserting on a DOM.** There is no document here, and there will not be one: G4 refuses the globals, E5 refuses the `@vitest-environment` comment that would conjure them, and the route is a `.test.tsx` in a real browser.
-- **Letting the Given drift into `beforeEach`.** A Given nobody can read in the test is a Given nobody maintains. J6w says so.
-
-## Related
-
-[02 — Developing](02-developing.md) · [03 — Testing](03-testing.md) · [06 — Integration specs](06-integration.md) · [07 — Component specs](07-component.md) · [14 — Assertions](14-assertions.md) · [15 — Tokens](15-tokens.md) · [16 — Contracts](16-contracts.md) · [18 — Conventions](18-conventions.md) · [19 — Linting](19-linting.md)

package/docs/06-integration.md

@@ -1,180 +0,0 @@
-# 06 — Integration specs: a module against the real thing
-
-`specification.integration()` specifies a MODULE — not an entry. No HTTP, no binary, no page: the subject is a function, and it is called. What makes it a spec rather than a module test beside its code is what it stands on — a real database, a declared contract, a golden file — and that is exactly the fork this facet closes.
-
-```typescript
-// specs/integration/integration.specification.ts
-import { postgres, specification } from '@jterrazz/test';
-import { afterAll } from 'vitest';
-
-export const { cleanup, integration } = await specification.integration({
-    services: { db: postgres() },
-});
-
-afterAll(cleanup);
-```
-
-```typescript
-// specs/integration/orders/orders.spec.ts
-import { expect, test } from 'vitest';
-
-import { listOrders } from '../../../src/orders/orders.js';
-import { integration } from '../integration.specification.js';
-
-test('reads the orders the day left behind', async () => {
-    // Given - two orders in the real database
-    const result = await integration
-        .seed('two-orders.sql')
-        .call(async ({ db }) => await listOrders(db.connectionString));
-
-    // Then - the module answered with both
-    expect(result.value).toMatch('two-orders.json');
-});
-```
-
-## What it specifies
-
-Three questions decide, in order ([18 — Conventions](18-conventions.md)):
-
-1. Does the subject answer HTTP, run as a binary, render a page or a screen? Then it is that facet's, not this one.
-2. Does it need a real service — a database, a cache, a process — or is its oracle a GOLDEN file? Then it is an integration spec.
-3. Otherwise it is a module test, `<file>.test.ts` beside `<file>.ts`, with no runner at all.
-
-The second question has two halves and both land here. A module against real infrastructure was, before this facet, a `specs/` folder running plain vitest with a hand-built sqlite template and a `beforeAll` starting a container. A module whose oracle is a golden was a `toMatchSnapshot` — a second golden mechanism beside the one the package owns. Neither needed a new idea; both needed a constructor.
-
-## The constructor
-
-| Option     | Means                                                                                                                                 |
-| ---------- | ------------------------------------------------------------------------------------------------------------------------------------- |
-| `services` | the named record the module is specified against — `postgres()`, `redis()`, `sqlite()`, `process()`. Omit it for the golden-only half |
-| `root`     | project-root override (rule A9), auto-discovered from the calling file                                                                |
-
-The handle is `{ integration, cleanup }`, destructured with those names (rule A3) and cleaned up with `afterAll(cleanup)` (rule A4).
-
-## The chain
-
-Setups: `.seed()`, `.intercept()`, `.clock()`. Terminal action: `.call(subject)` (rule B2).
-
-| Setup                            | Means                                                                                           |
-| -------------------------------- | ----------------------------------------------------------------------------------------------- |
-| `.seed('rows.sql')`              | run `_seeds/rows.sql` before the call; `{ database }` targets one of several                    |
-| `.intercept(contracts)`          | declare what the outside world replies ([16](16-contracts.md))                                  |
-| `.clock('2026-03-04T09:30:00Z')` | pin the module's `Date` for this chain ([18](18-conventions.md#time--one-primitive-two-depths)) |
-
-`.call(subject)` hands the STARTED services record to the subject, so the module is built with the real connection strings rather than with a double:
-
-```typescript
-const result = await integration.call(async ({ db }) => await listOrders(db.connectionString));
-```
-
-Databases reset at the start of every chain, exactly as on api and jobs (rules B1, B7): one spec is one call, and no spec depends on a previous one.
-
-## The result
-
-Two readings, never both.
-
-| Accessor         | Is                                                                                                                                            |
-| ---------------- | --------------------------------------------------------------------------------------------------------------------------------------------- |
-| `result.value`   | what the call RETURNED — a `TextAccessor` for a string, a `JsonAccessor<T>` for anything else, the union of both for a `T` that may be either |
-| `result.error`   | what it THREW, as text: an `Error`'s message, or the value itself. Empty when it returned                                                     |
-| `result.table()` | a table of a declared database, for row-level assertions                                                                                      |
-
-A refusal is a reading, never a `try`/`catch`:
-
-```typescript
-test('refuses an order that is not one', async () => {
-    // Given - the module asked to record an order worth nothing
-    const result = await integration.call(
-        async ({ db }) => await placeOrder(db.connectionString, { reference: 'ORD-4', total: 0 }),
-    );
-
-    // Then - what it threw is the reading, and nothing was written
-    expect(result.error).toMatch('refused.txt');
-    await expect(result.table('orders')).toBeEmpty();
-});
-```
-
-That is what keeps a spec of a refusal the same size as a spec of a success, and what stops an "it should throw" spec from passing when nothing throws at all — `await expect(result.error).toBeEmpty()` is how a chain says "and it did not refuse". The `await` is not optional: `toBeEmpty` answers a promise on every subject it takes, a dropped one passes the test while the real failure surfaces as an unhandled rejection, and rule D2 refuses the bare form.
-
-`.call<T>()` carries `T` through to the result, so one field is read where one field is what the spec means — `expect(result.value.value.ok).toBe(true)` for JSON, `result.value.text` for a string — and a golden file is kept for what a golden file is for: a shape worth freezing whole.
-
-**The accessor follows the value, and the type says so.** A subject typed exactly `string` reads as a `TextAccessor`; one that can never be a string reads as a `JsonAccessor<T>`; one that MAY be a string (`string | undefined`, `string | number`) is typed as the union of the two, and the spec narrows it — because only the value in hand decides, and a type that guessed handed back a `JsonAccessor` whose `.value` was silently `undefined` while the runtime had built a `TextAccessor`.
-
-**What crosses is JSON, not the object.** A non-string value is serialised, so a `Map`, a `Set`, a `Date` or a class instance arrives as the plain JSON it serialises to — `{}`, `{}`, an ISO string, an object of its own fields — while `T` still claims the original type. A call whose answer is one of those projects it to plain data INSIDE the call, where the projection is visible:
-
-```typescript
-// the Map is projected where the spec can see it, not silently at the seam
-const result = await integration.call(async () => Object.fromEntries(await loadIndex()));
-```
-
-Both accessors are the package's ordinary subjects, so the golden mechanism reaches them whole: `toMatch('<name>.json'|'<name>.txt')` under `_expected/`, the `{{token}}` grammar for what moves, `{ frozen }`, and `TEST_UPDATE=1` ([15](15-tokens.md), [14](14-assertions.md)).
-
-A call that a declared contract never accepted fails the CHAIN rather than becoming `result.error`: a refusal the module chose is the subject's behaviour, an undeclared outgoing call is the spec's own mistake (rule D7).
-
-## Unique here
-
-### The golden half — a pure module, no services at all
-
-`specification.integration()` with no options is the pure-module runner: nothing starts, and what earns the folder is the golden.
-
-```typescript
-export const { cleanup, integration } = await specification.integration();
-```
-
-A table of cases is one `.call()` inside `test.each`, which is what turns fifty-three hand-paired fixture files into one spec:
-
-```typescript
-test.each(CASES)('renders $name', async ({ name, input }) => {
-    // Given - one case of the table
-    const result = await integration.call(() => render(input));
-
-    // Then - the golden for that case
-    expect(result.value).toMatch(`${name}.json`);
-    await expect(result.error).toBeEmpty();
-});
-```
-
-The golden is named by a template literal, and the checker's C9 dead-fixture pass reads that form: a fixture whose name matches the literal's static ends is one the table could have asked for, so a wall of `_expected/` files stays alive without a hand-written literal each.
-
-### The `integration()` project
-
-`integration()` from `@jterrazz/test/vitest` is the canonical project: it collects `specs/integration/**/*.spec.ts`, carries the preset's budgets and artefact directory, and runs in group 0 with the other node facets.
-
-```typescript
-import { defineSpecConfig, integration, unit } from '@jterrazz/test/vitest';
-
-export default defineSpecConfig({ test: { projects: [unit(), integration()] } });
-```
-
-An env-gated sub-suite is an option, not a second project — the whole point of `{ include, exclude, timeout }`:
-
-```typescript
-integration({
-    exclude: process.env.E2E_NETWORK ? [] : ['specs/integration/network/**'],
-});
-```
-
-### Folder layout
-
-```
-specs/integration/
-├── integration.specification.ts   # the runner, at the facet root
-├── pure.specification.ts          # a second runner: no services, goldens only
-└── orders/                        # a domain
-    ├── orders.spec.ts             # under specs/, the suffix is .spec.ts (rule C12)
-    ├── _seeds/two-orders.sql      # ground: database state
-    └── _expected/                 # ground: every expected fixture, flat
-```
-
-**`required` is verified per `.call()`.** A chain's scope is ONE terminal action: the contracts it declared are checked when that call ends, and a contract declared `required` that was never requested fails there. A second `.call()` is a second chain with a second verification — it does not inherit the first's obligations.
-
-## Pitfalls
-
-- **Reaching for `try`/`catch`.** A thrown error is `result.error`. A `try` around `.call()` brings back the shape where a spec passes because nothing threw.
-- **Writing a module test here.** A module alone, with no service and no golden, belongs beside its code as `<file>.test.ts` (rule I2). The folder is not a home for tests that were hard to place.
-- **Goldening a volatile value.** An id, a timestamp or a duration inside `result.value` is tokened (`{{int}}`, `{{iso8601}}`), or pinned with `.clock()`. A literal that moves is a test that fails tomorrow (rule D16).
-- **Asserting on a double.** The facet exists so the subject meets the real thing. A `mockOf<T>()` inside `.call()` is a module test that started a container for nothing.
-
-## Related
-
-[10 — API specs](10-api.md) · [14 — Assertions](14-assertions.md) · [16 — Contracts](16-contracts.md) · [17 — Services](17-services.md) · [18 — Conventions](18-conventions.md)