@jterrazz/test 16.1.1 → 18.0.0

package/docs/03-testing.md

@@ -1,495 +0,0 @@
-# 03 — Testing
-
-What proves a change here: this package specifies itself with itself. The suites under `specs/` are written with `@jterrazz/test` against fixture apps, the module tests sit beside the modules they cover, and a family of meta-tests runs the framework on its own output. This chapter says which suite answers for what, and what a change owes each of them.
-
-**The suffix says the kind.** `.test.ts` is the UNIT's word and sits beside the module it covers; `.test.tsx` is the same law for a rendered unit; `.spec.ts` is the ASSEMBLED product's word and lives under `specs/<facet>/`; a literate document stays `<case>.spec.yaml`. C12 holds both directions and its `--fix` renames with `git mv`, so a reader can tell what a file proves without opening it.
-
-| Ground          | Where                                     | Proves                                                                 |
-| --------------- | ----------------------------------------- | ---------------------------------------------------------------------- |
-| Module tests    | `src/**/<file>.test.ts`                   | One module's behaviour, beside it (rule I2)                            |
-| Component tests | `specs/component-app/<file>.test.tsx`     | A rendered unit, beside it, in a real Chromium ([07](07-component.md)) |
-| Product specs   | `specs/<facet>/<domain>/<aspect>.spec.ts` | The framework's own facets, through the public surface                 |
-| Spec documents  | `specs/cli/literate/*.spec.yaml`          | The document format, collected as test files by `literate()`           |
-| Meta-tests      | `src/lint/*.test.ts`                      | The framework applied to itself and to its own projections             |
-
-## The seven projects
-
-`test.projects` in `vitest.config.ts` declares seven, and which one you can run is decided by what is installed and running on the machine.
-
-| Project       | Collects                                                                                        | Needs                                                                |
-| ------------- | ----------------------------------------------------------------------------------------------- | -------------------------------------------------------------------- |
-| `unit`        | `src/**/*.test.ts` + `specs/lint/**/*.test.ts`, built by `unit()`                               | Nothing — the lint specs need `npm run build` first                  |
-| `cli`         | `specs/cli/**`, built by `cli()` — its documents included, through `literate()`                 | Nothing — the Docker specs self-skip                                 |
-| `api`         | `specs/api/**/*.spec.ts`, built by `api()` (node mode, in-process Hono)                         | Docker                                                               |
-| `jobs`        | `specs/jobs/**`, built by `jobs()`                                                              | Docker                                                               |
-| `integration` | `specs/integration/**`, built by `integration({ serial: true })` — the container seams included | Docker                                                               |
-| `website`     | `specs/website/**`, built by `website()`                                                        | playwright + `npx playwright install chromium`; no Docker            |
-| `component`   | `specs/component-app/**/*.test.tsx`, built by `component()`                                     | the same chromium; no Docker. Runs in its own group, after `website` |
-
-Every project the package runs comes from a helper, so `--project api` means the same tree here as in any consumer — `unit()` included, with the globs it takes naming the one specs tree that is no facet's. A member without `"type": "module"` writes its config as `vitest.config.mts`: the helpers ship ESM only, a CJS config would have to `require()` them, and `roleOf` already reads `.mts` as the config role — so the rules that judge a config still find it.
-
-Why a file is reached by its ROLE and named by its suffix, and what was weighed against it: [ADR-006](decisions/006-the-catalogue-reaches-a-file-by-its-role.md).
-
-**`specs/lint/` is a repository suite, and it keeps `.test.ts`.** A repository suite covers a TREE rather than one assembled product: these files run the plugin and the checker over fixture PROJECTS, one per rule, and what they specify is a convention over a repository's shape. Its first level is not one of the six facets, so C12's rename clause never reaches it, C1's declared depth is what judges it, and `unit()` is what collects it — the shape the constitution calls [the third door](18-conventions.md#the-third-door-a-repository-suite).
-
-**The `unit` project's budget is the whole suite's floor.** It collects the module tests and the lint suite and runs with no service, no browser and no container, so it is the one project a developer runs on every save: the same tree takes between nine and eleven seconds on consecutive runs of a developer machine, and **the budget it may not pass is twelve**. The budget is set above the range and not at the best measurement, because a budget set at the best measurement is a budget that fails on noise. The meta-test that proves every rule's reach (`k4-reach-per-path`) runs inside it on ONE oxlint run for the same reason.
-
-Every FACET folder under `specs/` belongs to a constructor, and the one folder that is not a facet says so in its name: `specs/component-app/` is the rendered subject this package ships, and its component tests sit beside its components because that is what a rendered unit's test does (A2, I2). A probe of a container seam — the postgres and redis handles — is a module against a real service, so it is an integration spec: `specs/integration/<seam>/`, on `specification.integration({ services })` and its one terminal action. What the seam answers BEFORE it reaches a container, and the one adapter the public entry does not publish (`TestcontainersAdapter`), are module tests beside their modules under `src/seams/` — a spec reaches the framework through its public entry, and a probe that cannot is telling you where it belongs (rule F3).
-
-```bash
-npm test                            # every project — Docker and chromium both required
-npx vitest --run --project unit     # the loop: no infrastructure, after npm run build
-npx vitest --run --project website  # after npx playwright install chromium
-npx vitest --run --project component  # the same chromium, a mounted unit at a time
-```
-
-There is no mobile tree under `specs/`, and that is a hole this chapter states rather than hides: an iOS simulator is not something CI provisions, so the mobile facet is proven by module tests under `src/facets/mobile/` — the simulator resolution, the page-source projection, the ambiguity messages — and by nothing end-to-end.
-
-A second hole is the RENDERER's, and it is not this repository's to close: a React Native screen never reaches the real Chromium the component facet mounts in, so jest stays on that surface until the `react-native-web` spike says otherwise — [07 — Component specs](07-component.md) lists it with the other three shapes the facet does not take.
-
-## How a spec tree is laid out
-
-The layout is the one the conventions enforce on every consumer (rule C1), and this repository is its first consumer. A facet carries its runners at its ROOT and its tests one level down, in domain folders:
-
-```
-specs/
-├── api/
-│   ├── api.specification.ts          # runners at the facet root
-│   ├── intercepts.specification.ts
-│   └── requests/                     # a domain
-│       ├── requests.spec.ts
-│       ├── _requests/                # ground: complete requests, *.http
-│       └── _expected/                # ground: every expected fixture, flat
-└── _fixtures/                        # the SHARED pool, reached as $FIXTURES/…
-```
-
-**A domain shared by two facets carries the same name in both.** Six
-capabilities belong to no facet in particular — a runner's `lifecycle`, the
-declared network (`intercepts`), the ground a chain loads (`seeding`), what a
-result answers (`assertions`), the `{{token}}` engine (`tokens`) and the pinned
-calendar (`clock`) — and a facet that gives one of them a FOLDER calls it by
-that name, so `specs/api/clock/` and `specs/website/clock/` are the same
-question asked of two constructors. Everything else is one facet's own, and a
-name that is one facet's own is never another's: two names for one capability
-is the drift the vocabulary exists to stop.
-
-It says nothing about where a METHOD may appear. `.seed()` is used inside jobs'
-`triggering/` scenarios and integration's `call/` ones, because seeding is the
-Given there and not the subject; a capability earns a folder when it is what
-the specs in it are ABOUT.
-
-The vocabulary is declared in `src/lint/domains.ts` and `domains.test.ts` holds
-the tree equal to it in both directions — a folder nothing declares fails, and
-a declared name nothing carries fails too.
-
-<!-- GENERATED:domains — do not edit by hand; run `npm run docs`. Source: src/lint/domains.ts -->
-
-| Facet         | Shared domains it carries                                        | Its own                                               |
-| ------------- | ---------------------------------------------------------------- | ----------------------------------------------------- |
-| `api`         | `assertions/`, `clock/`, `intercepts/`, `lifecycle/`, `seeding/` | `initiation-errors/`, `requests/`, `responses/`       |
-| `cli`         | `assertions/`, `seeding/`, `tokens/`                             | `directory/`, `docker/`, `env/`, `exec/`, `literate/` |
-| `integration` | `clock/`, `intercepts/`                                          | `call/`, `golden/`, `postgres/`, `redis/`             |
-| `jobs`        | —                                                                | `triggering/`                                         |
-| `website`     | `assertions/`, `clock/`                                          | `console/`, `fetch/`, `services/`, `visit/`           |
-
-<!-- /GENERATED:domains -->
-
-A test at a facet root is forbidden and a `*.specification.ts` inside a domain is forbidden; a leading underscore means ground, never a domain. Which of the two legal shapes a given tree takes — its own domain, or sibling tests in a named group folder — is decided by the assets, and that judgement is the process channel's ([18 — Conventions](18-conventions.md)).
-
-The fixture apps the specs drive live in the pool: `app` and `website-app` for the served facets, `cli-app`, `docker-cli`, `checker-cli` and `lint-cli` for the command facets, the `broken-*` trees for the infrastructure failure paths, and `lint-violations/` — a violation/compliant twin per lint rule.
-
-**The component tree is the one exception, and the exception is the rule it dogfoods.** A rendered unit's test sits BESIDE the unit, so `specs/component-app/` holds the fixture app and its specs as neighbours — a table with a contract, a form carrying every verb, a modal hook with its Host in the test, a routed link, a vanilla-DOM list, a clock stamp, a noisy panel, a responsive note, a control that refuses input and a pair of links whose names overlap. It is not under `_fixtures/`: ground is what a spec stands on from a distance, and here the spec stands next to it. The exception is HELD by rules, not granted by omission: I2 requires every one of those `.test.tsx` files to have the `.tsx` (or the `.ts` of a hook) of the same basename beside it, and C1's row says a `.test.tsx` is out of its reach because a rendered unit never lives in a facet/domain tree.
-
-## The layered reading
-
-The package proves itself in five layers, and they are meant to be read from the inside out: a module against its own exports, a rule against its own fixtures, a facet against its own tree, the built binary against a fixture project, and the CORPUS against what a meta-test says it must keep true. Each layer judges something the one below it cannot — and the meta-tests are counted apart rather than folded into the module tests, because what they judge is the one thing a test beside a module cannot see.
-
-<!-- GENERATED:layers — do not edit by hand; run `npm run docs`. Source: src/lint/matrix.ts -->
-
-| Layer                   | Where                                                   | What it judges                                                           | Files |
-| ----------------------- | ------------------------------------------------------- | ------------------------------------------------------------------------ | ----- |
-| Module tests            | `src/**/*.test.ts` beside the module                    | one module, through its own exports, with nothing started                | 54    |
-| Rule tests              | `src/lint/rules/<facet>/<rule>.test.ts` beside the rule | one rule: what it flags, what it leaves alone, and the message it prints | 56    |
-| The package’s own specs | `specs/<facet>/`                                        | the framework's own facets, each met through its constructor             | 67    |
-| The lint suite          | `specs/lint/**`                                         | the built binary end to end, over fixture projects                       | 88    |
-| Meta-tests              | `src/lint/*.test.ts`                                    | the corpus itself: the catalogue, the matrix, the cards, the floor       | 18    |
-
-<!-- /GENERATED:layers -->
-
-The counts are generated: a layer that stops growing while the surface does is visible here before it is visible in a bug.
-
-## The lint suite is end-to-end
-
-`specs/lint/**` runs the REAL oxlint binary and the real checker over the fixture projects and goldens their output, grouped by convention family (`runners/`, `chains/`, `files/`, `assertions/`, `imports/`, `architecture/`, `hygiene/`, `website/`, `checker/`, `meta/`). Because it loads `dist/oxlint.js`, `npm run build` must precede it — the same ordering `npm run lint` depends on.
-
-Its goldens are full snapshots, not greps: `specs/lint/checker/_expected/*.txt` holds the exact lines the checker prints, including the chapter each message points a consumer at. A message that changes its wording moves its golden with it, in the same commit.
-
-## Coverage is a ratchet, not a threshold
-
-`npx vitest --run --coverage` turns on v8 — the runtime's own counter, so there
-is no instrumentation pass and the numbers do not move when the bundler does —
-and writes three reports where the preset sends them ([02 — Developing §
-Artefacts live under `.artifacts/`](02-developing.md#artefacts-live-under-artifacts)):
-`text` for the person who ran it, `html` for the one chasing a line, and
-`json-summary`, which is the one a machine reads.
-
-`npm run coverage` records where the suite stands in `coverage.baseline.json`;
-`npm run coverage:check` refuses a run that fell below it. Neither runs the
-suite: both read the report of the LAST `--coverage` run, which is why
-`make test` runs the suite WITH coverage (`npm test -- --coverage`) before the
-gate — a plain `npm test` would leave it judging an older run, or, on a fresh
-clone where `.artifacts/` does not exist yet, nothing at all. That target is
-the one CI calls ([What CI runs](#what-ci-runs)), so the floor is judged on
-every push. It only ever rises: lowering it is an edit to a committed file,
-with a commit body saying why.
-
-### One floor, over the whole suite
-
-The baseline is keyed by scope and the CLI
-takes `--scope`, so a project can keep its own; this repository records `all`
-and nothing else, because the projects overlap — the browser projects and the
-node ones both execute `model/`, and four floors summing to more than the tree
-would ratchet on which project happened to run. A scope missing any of the four
-metrics is refused rather than read as a zero, since a floor of zero forbids
-nothing.
-
-### Why a ratchet and not a threshold
-
-A fixed threshold would be a number somebody picked. Set it where the project
-stands and it forbids nothing; set it where the project should be and every run
-is red until it gets there, which is how a gate becomes something people pass
-with `--no-verify`. A ratchet asks the only question a gate can answer
-honestly: is this change worse than the last one?
-
-### What the report excludes
-
-What the report EXCLUDES is the shape of the answer, not a way to raise the
-number: `node_modules/` (Browser Mode instruments the page's bundle, and
-react-dom alone is 19 000 statements), `specs/` and `_fixtures/` (a spec is a
-test and the app it drives is ground), the type-only and config files.
-
-## Modules with no sibling test
-
-I2 says a module test lives beside its module. It never said every module has
-one, and it cannot: a barrel executes nothing, a `*.port.ts` declares a shape,
-and a facet's constructor is proven by the tree that constructs it. What was
-missing is the LIST of the ones that do not, and why — a module with real
-behaviour, no sibling test and nobody able to say what covers it is the silence
-this section closes.
-
-`src/lint/siblings.ts` declares the kinds, each naming the PATHS it claims —
-never a prefix, because a kind claiming `src/seams/` would claim every module
-written there next year and K7 would be a poster. **K7** fails on a module that
-matches none of them, which is what makes a new, unclaimed module fail the
-suite on the day it lands.
-
-<!-- GENERATED:siblings — do not edit by hand; run `npm run docs`. Source: src/lint/siblings.ts -->
-
-Today **80 modules** have no sibling test, and every one of them is claimed:
-
-| Kind                                    | Proven instead by                                                                                                                                                                                                                              |
-| --------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| composition root or barrel (4)          | it wires and re-exports; what it publishes is held by `package-exports.test.ts` and by every spec that imports the entry                                                                                                                       |
-| type-only declaration (11)              | it declares a shape and executes nothing; the compiler is its test, and `type-channel.test-d.ts` holds what the compiler must refuse                                                                                                           |
-| constant data (3)                       | it is a table, not a behaviour; every reader of it asserts on it (`preset.test.ts` for the artefact paths, `plugin.test.ts` for the manifest)                                                                                                  |
-| the facet file set, as a re-export (12) | the six node facets share one builder, so these name it rather than implement it — `builder.test.ts` and `facet-matrix.test.ts` hold the thing they name                                                                                       |
-| a facet's vitest project (7)            | `projects.test.ts` builds every one of them and asserts the project it produces                                                                                                                                                                |
-| a mobile module that needs a device (2) | the mobile facet has no tree under `specs/` and cannot have one here (M1); what a device is NOT needed for — resolving the simulator, projecting the page source, wording the ambiguity — has its own sibling test, and these two are the rest |
-| a facet module (8)                      | the facet is proven end to end by its own tree under `specs/<facet>/`, which is what the constructor exists to make possible                                                                                                                   |
-| a result accessor (7)                   | an accessor is what a terminal action hands back: it is exercised by every spec that asserts on a result, and `result.test.ts` holds the base                                                                                                  |
-| a seam adapter (12)                     | a seam is proven through the facet that drives it — a probe that could only reach it directly is an integration spec under `specs/integration/<seam>/` (chapter 03)                                                                            |
-| a bundled CLI entry (3)                 | it is argument parsing over a module that has its own tests, and `specs/lint/` runs the built binary end to end                                                                                                                                |
-| a lint-layer module (4)                 | the lint layer is proven by the rule tests beside each rule and by `specs/lint/`, which runs the real oxlint binary and the real checker over fixture projects                                                                                 |
-| a chain or runner internal (7)          | it is reached through the chain, so its proof is the facet specs that drive the chain — a direct test would assert on a seam nothing else speaks to                                                                                            |
-
-<!-- /GENERATED:siblings -->
-
-A new module that matches no kind fails the meta-test, which is the moment to
-write the test — not six months later, when a coverage number moved.
-
-## The capability matrix
-
-The catalogue in [19 — Linting](19-linting.md) answers "which conventions are
-mechanized". This answers the other half: for each thing the framework can DO,
-which facets declare it, and how many of the package's own test files exercise
-it there.
-
-It is generated by `npm run docs` from the facet declaration
-(`src/lint/facet-matrix.ts`), the `{{token}}` list the runner and the checker
-already share, and a scan of the trees each column owns. The same table is the
-skill's `references/matrix.md`.
-
-<!-- GENERATED:matrix — do not edit by hand; run `npm run docs`. Source: src/lint/matrix.ts -->
-
-What the framework can do, and how many of this package’s own test FILES carry the literal that exercises it, per facet (comments stripped, so a sentence about a capability never counts as a test of it). A blank (`—`) is a capability the facet does not declare; a `0` is a declared capability nothing here exercises, and every one of them is named under **Exemptions** with the reason it is accepted. `matrix.test.ts` fails on a `0` that is not.
-
-### Constructor option
-
-| Capability  | api | jobs | cli | integration | website | mobile | component | module |
-| ----------- | --- | ---- | --- | ----------- | ------- | ------ | --------- | ------ |
-| `services`  | 2   | 1    | 1   | 2           | 1       | 0      | —         | —      |
-| `root`      | 2   | 1    | 0   | 2           | 0       | 0      | 0         | —      |
-| `server`    | 4   | —    | —   | —           | 3       | —      | —         | —      |
-| `jobs`      | —   | 2    | —   | —           | —       | —      | —         | —      |
-| `url`       | —   | —    | —   | —           | 0       | —      | —         | —      |
-| `backend`   | —   | —    | —   | —           | 0       | 0      | —         | —      |
-| `external`  | —   | —    | —   | —           | 0       | —      | —         | —      |
-| `device`    | —   | —    | —   | —           | —       | 0      | —         | —      |
-| `app`       | —   | —    | —   | —           | —       | 0      | —         | —      |
-| `timeouts`  | —   | —    | —   | —           | —       | 0      | —         | —      |
-| `defaults`  | —   | —    | 1   | —           | —       | —      | —         | —      |
-| `env`       | —   | —    | 4   | —           | —       | —      | —         | —      |
-| `docker`    | —   | —    | 1   | —           | —       | —      | —         | —      |
-| `serve`     | —   | —    | 4   | —           | —       | —      | —         | —      |
-| `transform` | —   | —    | 2   | —           | 1       | —      | —         | —      |
-| `wrap`      | —   | —    | —   | —           | —       | —      | 1         | —      |
-| `vite`      | —   | —    | —   | —           | —       | —      | 1         | —      |
-| `clock`     | —   | —    | —   | —           | —       | —      | 0         | —      |
-| `locale`    | —   | —    | —   | —           | —       | —      | 0         | —      |
-| `timezone`  | —   | —    | —   | —           | —       | —      | 0         | —      |
-| `viewport`  | —   | —    | —   | —           | —       | —      | 0         | —      |
-
-### Setup
-
-| Capability     | api | jobs | cli | integration | website | mobile | component | module |
-| -------------- | --- | ---- | --- | ----------- | ------- | ------ | --------- | ------ |
-| `.clock()`     | 1   | 0    | —   | 1           | 1       | —      | 1         | —      |
-| `.intercept()` | 3   | 1    | —   | 1           | 0       | 0      | 4         | —      |
-| `.seed()`      | 4   | 1    | 1   | 2           | —       | —      | —         | —      |
-| `.headers()`   | 1   | —    | —   | —           | 1       | —      | —         | —      |
-| `.fixture()`   | —   | —    | 6   | —           | —       | —      | —         | —      |
-| `.env()`       | —   | —    | 1   | —           | —       | —      | —         | —      |
-| `.wrap()`      | —   | —    | —   | —           | —       | —      | 2         | —      |
-| `.viewport()`  | —   | —    | —   | —           | —       | —      | 1         | —      |
-
-### Terminal action
-
-| Capability   | api | jobs | cli | integration | website | mobile | component | module |
-| ------------ | --- | ---- | --- | ----------- | ------- | ------ | --------- | ------ |
-| `.get()`     | 9   | —    | —   | —           | —       | —      | —         | —      |
-| `.post()`    | 1   | —    | —   | —           | —       | —      | —         | —      |
-| `.put()`     | 1   | —    | —   | —           | —       | —      | —         | —      |
-| `.delete()`  | 1   | —    | —   | —           | —       | —      | —         | —      |
-| `.request()` | 1   | —    | —   | —           | —       | —      | —         | —      |
-| `.trigger()` | —   | 1    | —   | —           | —       | —      | —         | —      |
-| `.call()`    | —   | —    | —   | 6           | —       | —      | —         | —      |
-| `.exec()`    | —   | —    | 7   | —           | —       | —      | —         | —      |
-| `.run()`     | —   | —    | 2   | —           | —       | —      | —         | —      |
-| `.visit()`   | —   | —    | —   | —           | 11      | —      | —         | —      |
-| `.fetch()`   | —   | —    | —   | —           | 2       | —      | —         | —      |
-| `.open()`    | —   | —    | —   | —           | —       | 0      | —         | —      |
-| `.render()`  | —   | —    | —   | —           | —       | —      | 15        | —      |
-
-### Verb
-
-| Capability | api | jobs | cli | integration | website | mobile | component | module |
-| ---------- | --- | ---- | --- | ----------- | ------- | ------ | --------- | ------ |
-| `see`      | —   | —    | —   | —           | 6       | 0      | 15        | —      |
-| `fill`     | —   | —    | —   | —           | 3       | 0      | 2         | —      |
-| `click`    | —   | —    | —   | —           | 4       | —      | 5         | —      |
-| `gone`     | —   | —    | —   | —           | 2       | —      | 4         | —      |
-| `press`    | —   | —    | —   | —           | 0       | —      | 2         | —      |
-| `hover`    | —   | —    | —   | —           | 0       | —      | 1         | —      |
-| `check`    | —   | —    | —   | —           | 0       | —      | 2         | —      |
-| `select`   | —   | —    | —   | —           | 1       | —      | 2         | —      |
-| `goto`     | —   | —    | —   | —           | 0       | —      | —         | —      |
-| `tap`      | —   | —    | —   | —           | —       | 0      | —         | —      |
-| `rerender` | —   | —    | —   | —           | —       | —      | 1         | —      |
-| `unmount`  | —   | —    | —   | —           | —       | —      | 1         | —      |
-
-### Descriptor
-
-| Capability      | api | jobs | cli | integration | website | mobile | component | module |
-| --------------- | --- | ---- | --- | ----------- | ------- | ------ | --------- | ------ |
-| `button`        | —   | —    | —   | —           | 4       | 0      | 5         | —      |
-| `field`         | —   | —    | —   | —           | 4       | 0      | 3         | —      |
-| `content`       | —   | —    | —   | —           | 3       | 0      | 10        | —      |
-| `testId`        | —   | —    | —   | —           | 0       | 0      | 1         | —      |
-| `heading`       | —   | —    | —   | —           | 1       | —      | 1         | —      |
-| `link`          | —   | —    | —   | —           | 3       | —      | 2         | —      |
-| `dialog`        | —   | —    | —   | —           | 0       | —      | 1         | —      |
-| `status`        | —   | —    | —   | —           | 0       | —      | 3         | —      |
-| `table`         | —   | —    | —   | —           | 0       | —      | 1         | —      |
-| `row`           | —   | —    | —   | —           | 0       | —      | 1         | —      |
-| `listitem`      | —   | —    | —   | —           | 0       | —      | 1         | —      |
-| `option`        | —   | —    | —   | —           | 1       | —      | 1         | —      |
-| `banner`        | —   | —    | —   | —           | 0       | —      | 0         | —      |
-| `complementary` | —   | —    | —   | —           | 0       | —      | 0         | —      |
-| `contentinfo`   | —   | —    | —   | —           | 1       | —      | 0         | —      |
-| `form`          | —   | —    | —   | —           | 0       | —      | 0         | —      |
-| `main`          | —   | —    | —   | —           | 1       | —      | 1         | —      |
-| `navigation`    | —   | —    | —   | —           | 1       | —      | 2         | —      |
-| `region`        | —   | —    | —   | —           | 1       | —      | 1         | —      |
-| `search`        | —   | —    | —   | —           | 0       | —      | 0         | —      |
-| `within`        | —   | —    | —   | —           | 2       | —      | 5         | —      |
-| `focused`       | —   | —    | —   | —           | 1       | —      | 1         | —      |
-| `selected`      | —   | —    | —   | —           | 1       | —      | 1         | —      |
-| `valued`        | —   | —    | —   | —           | 1       | —      | 2         | —      |
-| `disabled`      | —   | —    | —   | —           | 1       | —      | 1         | —      |
-| `enabled`       | —   | —    | —   | —           | 1       | —      | 1         | —      |
-
-### Result accessor
-
-| Capability      | api | jobs | cli | integration | website | mobile | component | module |
-| --------------- | --- | ---- | --- | ----------- | ------- | ------ | --------- | ------ |
-| `.response`     | 7   | —    | —   | —           | —       | —      | —         | —      |
-| `.status`       | 3   | —    | —   | —           | 2       | —      | —         | —      |
-| `.table()`      | 4   | 1    | 1   | 1           | —       | —      | —         | —      |
-| `.file()`       | 0   | —    | 5   | 0           | —       | —      | —         | —      |
-| `.directory()`  | 0   | —    | 2   | 0           | —       | —      | —         | —      |
-| `.stdout`       | —   | —    | 5   | —           | —       | —      | —         | —      |
-| `.stderr`       | —   | —    | 2   | —           | —       | —      | —         | —      |
-| `.exitCode`     | —   | —    | 8   | —           | —       | —      | —         | —      |
-| `.filesystem`   | —   | —    | 1   | —           | —       | —      | —         | —      |
-| `.container()`  | —   | —    | 1   | —           | —       | —      | —         | —      |
-| `.containerIds` | —   | —    | 1   | —           | —       | —      | —         | —      |
-| `.value`        | —   | —    | —   | 6           | —       | —      | —         | —      |
-| `.error`        | —   | —    | —   | 5           | —       | —      | —         | —      |
-| `.tree`         | —   | —    | —   | —           | 2       | —      | 4         | —      |
-| `.content`      | —   | —    | —   | —           | 4       | 0      | 12        | —      |
-| `.console`      | —   | —    | —   | —           | 1       | —      | 3         | —      |
-| `.errors`       | —   | —    | —   | —           | 4       | —      | 5         | —      |
-| `.html`         | —   | —    | —   | —           | 0       | —      | 5         | —      |
-| `.title`        | —   | —    | —   | —           | 0       | —      | —         | —      |
-| `.url`          | —   | —    | —   | —           | 2       | —      | —         | —      |
-| `.head`         | —   | —    | —   | —           | 3       | —      | —         | —      |
-| `.jsonLd`       | —   | —    | —   | —           | 1       | —      | —         | —      |
-| `.canonical`    | —   | —    | —   | —           | 1       | —      | —         | —      |
-| `.alternates`   | —   | —    | —   | —           | 1       | —      | —         | —      |
-| `.links`        | —   | —    | —   | —           | 0       | —      | —         | —      |
-| `.meta()`       | —   | —    | —   | —           | 2       | —      | —         | —      |
-| `.body`         | —   | —    | —   | —           | 1       | —      | —         | —      |
-| `.json`         | —   | —    | 2   | —           | 1       | —      | —         | —      |
-| `.headers`      | —   | —    | —   | —           | 1       | —      | —         | —      |
-| `.location`     | —   | —    | —   | —           | 1       | —      | —         | —      |
-| `.screen`       | —   | —    | —   | —           | —       | 0      | —         | —      |
-
-### Golden
-
-| Capability          | api | jobs | cli | integration | website | mobile | component | module |
-| ------------------- | --- | ---- | --- | ----------- | ------- | ------ | --------- | ------ |
-| `toMatch('<name>')` | 3   | 0    | 6   | 5           | 5       | —      | 1         | 6      |
-| `toMatchRows()`     | 4   | 1    | 1   | 1           | —       | —      | 0         | 4      |
-| `.http exchange`    | 3   | —    | —   | —           | —       | —      | —         | 7      |
-| `.aria.yaml tree`   | —   | —    | —   | —           | 1       | —      | 1         | —      |
-| `.json body`        | 0   | —    | 2   | 5           | 2       | —      | —         | 10     |
-| `.txt stream`       | 1   | —    | 8   | 2           | 2       | —      | —         | 12     |
-| `{ frozen }`        | 2   | —    | 5   | —           | —       | —      | 1         | 3      |
-
-### Time & doubles
-
-| Capability    | api | jobs | cli | integration | website | mobile | component | module |
-| ------------- | --- | ---- | --- | ----------- | ------- | ------ | --------- | ------ |
-| `clock()`     | —   | —    | —   | —           | —       | —      | —         | 4      |
-| `intercept()` | —   | —    | —   | —           | —       | —      | —         | 1      |
-| `mockOf()`    | —   | —    | —   | —           | —       | —      | —         | 6      |
-| `match.*`     | —   | —    | —   | —           | —       | —      | —         | 22     |
-
-### Token
-
-| Capability     | api | jobs | cli | integration | website | mobile | component | module |
-| -------------- | --- | ---- | --- | ----------- | ------- | ------ | --------- | ------ |
-| `{{any}}`      | 0   | —    | 2   | 0           | 0       | —      | —         | 1      |
-| `{{base64}}`   | 0   | —    | 0   | 0           | 0       | —      | —         | 2      |
-| `{{date}}`     | 0   | —    | 0   | 0           | 0       | —      | —         | 1      |
-| `{{duration}}` | 0   | —    | 1   | 0           | 0       | —      | —         | 2      |
-| `{{email}}`    | 0   | —    | 0   | 0           | 0       | —      | —         | 1      |
-| `{{float}}`    | 0   | —    | 0   | 0           | 0       | —      | —         | 2      |
-| `{{hex}}`      | 0   | —    | 0   | 0           | 0       | —      | —         | 2      |
-| `{{int}}`      | 0   | —    | 0   | 0           | 0       | —      | —         | 1      |
-| `{{ip}}`       | 0   | —    | 0   | 0           | 0       | —      | —         | 1      |
-| `{{iso8601}}`  | 0   | —    | 0   | 0           | 0       | —      | —         | 2      |
-| `{{number}}`   | 0   | —    | 0   | 0           | 0       | —      | —         | 1      |
-| `{{path}}`     | 0   | —    | 0   | 0           | 0       | —      | —         | 1      |
-| `{{port}}`     | 0   | —    | 0   | 0           | 0       | —      | —         | 2      |
-| `{{semver}}`   | 0   | —    | 2   | 0           | 0       | —      | —         | 1      |
-| `{{sha}}`      | 0   | —    | 0   | 0           | 0       | —      | —         | 1      |
-| `{{string}}`   | 0   | —    | 1   | 0           | 0       | —      | —         | 1      |
-| `{{time}}`     | 0   | —    | 0   | 0           | 0       | —      | —         | 1      |
-| `{{ulid}}`     | 0   | —    | 0   | 0           | 0       | —      | —         | 1      |
-| `{{url}}`      | 0   | —    | 2   | 0           | 0       | —      | —         | 1      |
-| `{{uuid}}`     | 0   | —    | 0   | 0           | 0       | —      | —         | 3      |
-| `{{workdir}}`  | 0   | —    | 5   | 0           | 0       | —      | —         | 1      |
-
-### Exemptions
-
-- no mobile tree: an iOS simulator is not something CI provisions (M1) — `services`·mobile, `root`·mobile, `backend`·mobile, `device`·mobile, `app`·mobile, `timeouts`·mobile, `.intercept()`·mobile, `.open()`·mobile, `see`·mobile, `fill`·mobile, `tap`·mobile, `button`·mobile, `field`·mobile, `content`·mobile, `testId`·mobile, `.content`·mobile, `.screen`·mobile
-- the surface ships and this package does not specify it here yet — `root`·cli, `root`·website, `root`·component, `backend`·website, `external`·website, `clock`·component, `locale`·component, `timezone`·component, `viewport`·component, `.clock()`·jobs, `.intercept()`·website, `press`·website, `hover`·website, `check`·website, `goto`·website, `testId`·website, `dialog`·website, `status`·website, `table`·website, `row`·website, `listitem`·website, `banner`·website, `banner`·component, `complementary`·website, `complementary`·component, `contentinfo`·component, `form`·website, `form`·component, `search`·website, `search`·component, `.file()`·api, `.file()`·integration, `.directory()`·api, `.directory()`·integration, `.html`·website, `.title`·website, `.links`·website, `toMatchRows()`·component, `.json body`·api
-- the package serves its own fixture site, so `server` is what it proves; `url` targets an already-running deployment, which is a consumer shape (A11 states the XOR) — `url`·website
-- a job's oracle is the table it wrote (`toMatchRows`): its result carries no file and no directory — `toMatch('<name>')`·jobs
-- the engine owns the family (proven in the module column); a facet uses the ones its goldens need — `{{any}}`·api, `{{any}}`·integration, `{{any}}`·website, `{{base64}}`·api, `{{base64}}`·cli, `{{base64}}`·integration, `{{base64}}`·website, `{{date}}`·api, `{{date}}`·cli, `{{date}}`·integration, `{{date}}`·website, `{{duration}}`·api, `{{duration}}`·integration, `{{duration}}`·website, `{{email}}`·api, `{{email}}`·cli, `{{email}}`·integration, `{{email}}`·website, `{{float}}`·api, `{{float}}`·cli, `{{float}}`·integration, `{{float}}`·website, `{{hex}}`·api, `{{hex}}`·cli, `{{hex}}`·integration, `{{hex}}`·website, `{{int}}`·api, `{{int}}`·cli, `{{int}}`·integration, `{{int}}`·website, `{{ip}}`·api, `{{ip}}`·cli, `{{ip}}`·integration, `{{ip}}`·website, `{{iso8601}}`·api, `{{iso8601}}`·cli, `{{iso8601}}`·integration, `{{iso8601}}`·website, `{{number}}`·api, `{{number}}`·cli, `{{number}}`·integration, `{{number}}`·website, `{{path}}`·api, `{{path}}`·cli, `{{path}}`·integration, `{{path}}`·website, `{{port}}`·api, `{{port}}`·cli, `{{port}}`·integration, `{{port}}`·website, `{{semver}}`·api, `{{semver}}`·integration, `{{semver}}`·website, `{{sha}}`·api, `{{sha}}`·cli, `{{sha}}`·integration, `{{sha}}`·website, `{{string}}`·api, `{{string}}`·integration, `{{string}}`·website, `{{time}}`·api, `{{time}}`·cli, `{{time}}`·integration, `{{time}}`·website, `{{ulid}}`·api, `{{ulid}}`·cli, `{{ulid}}`·integration, `{{ulid}}`·website, `{{url}}`·api, `{{url}}`·integration, `{{url}}`·website, `{{uuid}}`·api, `{{uuid}}`·cli, `{{uuid}}`·integration, `{{uuid}}`·website, `{{workdir}}`·api, `{{workdir}}`·integration, `{{workdir}}`·website
-
-<!-- /GENERATED:matrix -->
-
-## The meta-test channel
-
-Several truths about this package cannot be asserted from outside it, so they are asserted by running it on itself. Each of these exists because a defect class was found once and made unrepeatable (rule K1).
-
-The table is GENERATED from the files, because the channel grows faster than a hand-kept list: what a row holds is the file's own `describe` titles, so a meta-test that lands is a row the next `npm run docs` writes.
-
-<!-- GENERATED:meta-tests — do not edit by hand; run `npm run docs`. Source: src/lint/meta-tests.ts -->
-
-**19 files** are the channel — every `*.test.ts` directly under `src/lint/`, plus the suite that needs the real binary. What each one holds is its own `describe` titles, read from the file:
-
-| Meta-test                                   | Holds                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                | Tests |
-| ------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----- |
-| `src/lint/ast.test.ts`                      | specsAnchor                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          | 7     |
-| `src/lint/cards.test.ts`                    | signature cards — generation freshness (meta-test) · signature cards — completeness against the facet declaration (meta-test) · the skill routes to the cards (meta-test) · signature cards — what a card says                                                                                                                                                                                                                                                                                       | 15    |
-| `src/lint/checker-crossfile.test.ts`        | checker suppression — suppressedLines (checker-disable comments)                                                                                                                                                                                                                                                                                                                                                                                                                                     | 9     |
-| `src/lint/checker-member.test.ts`           | the member pass — what a workspace member owes                                                                                                                                                                                                                                                                                                                                                                                                                                                       | 18    |
-| `src/lint/checker-spec.test.ts`             | fixSpecDocument — key order and block scalars                                                                                                                                                                                                                                                                                                                                                                                                                                                        | 5     |
-| `src/lint/checker.test.ts`                  | conventions checker — findUnknownTokens (D4) · conventions checker — findKnownTokens (D10) · conventions checker — checkConventionFiles (D4)                                                                                                                                                                                                                                                                                                                                                         | 8     |
-| `src/lint/coverage.test.ts`                 | the coverage ratchet                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 | 8     |
-| `src/lint/docs-typecheck.test.ts`           | docs-typecheck — block selection · docs-typecheck — the published samples typecheck · docs-typecheck — the corpus does not await a sync matcher · docs-typecheck — harness                                                                                                                                                                                                                                                                                                                           | 6     |
-| `src/lint/domains.test.ts`                  | the spec tree’s domain vocabulary                                                                                                                                                                                                                                                                                                                                                                                                                                                                    | 4     |
-| `src/lint/env-allowlist.test.ts`            | framework env reads — e1-env-allowlist (meta-test)                                                                                                                                                                                                                                                                                                                                                                                                                                                   | 4     |
-| `src/lint/facet-matrix.test.ts`             | facet capability declaration (K1 guard)                                                                                                                                                                                                                                                                                                                                                                                                                                                              | 6     |
-| `src/lint/matrix.test.ts`                   | capability matrix (meta-test K6)                                                                                                                                                                                                                                                                                                                                                                                                                                                                     | 5     |
-| `src/lint/meta-tests.test.ts`               | the meta-test channel, read off its own files                                                                                                                                                                                                                                                                                                                                                                                                                                                        | 3     |
-| `src/lint/oxlint-pin.test.ts`               | the oxlint pin — the toolchain owns it and this manifest mirrors it                                                                                                                                                                                                                                                                                                                                                                                                                                  | 2     |
-| `src/lint/package-exports.test.ts`          | package-exports — F1 reads the published contract · package-exports — the root has two runtimes and one type surface · package-exports — the tarball carries what a message points at                                                                                                                                                                                                                                                                                                                | 8     |
-| `src/lint/plugin.test.ts`                   | the composable fragment — what a consumer wires · the upstream options this vocabulary owns (ADR-005) · conventions catalogue — generation freshness (meta-test) · conventions catalogue — completeness (meta-test) · testing fragment — standalone oxlint config · conventions catalogue — the channels answer for themselves (meta-test) · conventions catalogue — E2E inventory (meta-test) · the corpus’ own coordinates (meta-test K8) · the corpus never offers an option the rulebook refuses | 34    |
-| `src/lint/role.test.ts`                     | roleOf — the kind a path states · isTestRole — the three kinds that DECLARE tests · isTestFile — what the test conventions reach                                                                                                                                                                                                                                                                                                                                                                     | 14    |
-| `src/lint/siblings.test.ts`                 | modules with no sibling test (meta-test K7)                                                                                                                                                                                                                                                                                                                                                                                                                                                          | 4     |
-| `specs/lint/meta/k4-reach-per-path.test.ts` | lint — k4-reach-per-path (meta-test)                                                                                                                                                                                                                                                                                                                                                                                                                                                                 | 4     |
-
-<!-- /GENERATED:meta-tests -->
-
-One proof of the channel declares no test and appears in no row: `src/type-channel.test-d.ts` states what the COMPILER refuses — A8, A11, B1, B3, D1, M2, W6 — as an `@ts-expect-error` per row, and `typescript check` fails the day the line it marks starts compiling. It runs under the typechecker the whole repository already runs, never under a vitest project.
-
-`src/lint/plugin.test.ts` also holds the seven-channel contract: every row of
-every channel carries the proof that channel can give — a rule file and a
-fixture pair, an assertion on a resolved upstream option, a bundled checker
-pass, a `// RUNTIME <ID>` marker above the spec that drives the refusal, a line
-of the type-channel file, a named meta-test. A row that loses its proof fails
-that test rather than going quietly stale.
-
-The freshness meta-test is the reason a documentation change can turn the suite red: edit the generated catalogue by hand and it fails, correctly. Regenerate instead — the gesture is [02 — Developing](02-developing.md)'s.
-
-## Goldens and update mode
-
-A fixture this repository compares against is regenerated, never hand-tuned, and the gesture here is the `unit` project:
-
-```bash
-TEST_UPDATE=1 npx vitest --run --project unit   # or: npx vitest --run -u
-```
-
-What update mode writes, what it preserves and the discipline it asks for are [15 — Tokens § Update mode](15-tokens.md#update-mode-tokens-are-preserved)'s, whole.
-
-## What CI runs
-
-The workflow is `.github/workflows/validate.yaml`, on every push to `main` and every pull request, delegating to the estate's shared `validate.yaml`. It restores `.artifacts/`, then runs `make build`, `make lint` and `make test` in that order, with chromium provisioned because the website specs drive a real browser. The same three targets are what a local run owes before a push; the ordering is not decorative, since lint loads what build produced.
-
-**`make test` carries the floor.** It runs the suite WITH coverage and then `npm run coverage:check`, so the ratchet is judged on every push rather than trusted to whoever remembered to type `make check` — a gate CI never runs is a courtesy, not a gate. `make check` is still the whole verdict locally: build, lint, then that same target.
-
-## Pitfalls
-
-- **Running the lint specs on a stale `dist/`.** `specs/lint/**` and `oxlint.config.ts` both load `dist/oxlint.js`. Without `npm run build`, the suite judges the previous build's rules and reports a green that means nothing.
-- **Hand-editing a golden under `specs/lint/checker/_expected/`.** Those are full-output snapshots of a real binary. Change the message in the code and regenerate with `TEST_UPDATE=1`; a hand-tuned golden asserts your typing, not the checker's output.
-- **Expecting `npm test` to pass with Docker stopped.** Only `unit` and `cli` are infrastructure-free. The Docker-backed tests self-skip inside them, but `api`, `jobs` and `integration` fail honestly.
-- **Adding a test at a facet root.** `specs/<facet>/<aspect>.spec.ts` is refused by `c1-domain-structure` in this repository's default depth — the runner lives at the root, the tests live one level down.
-- **Writing a facet spec with the unit’s suffix.** `c12-spec-file-name` refuses it and `jterrazz-test-check specs --fix` renames it with `git mv` — and names every `include`/`exclude` entry of the member the rename broke — the globs whose prefix covers a file it moved and the literals naming one — since an entry the rename leaves behind collects nothing and the run stays green with fewer files. The reverse — a `.spec.ts` with no `specs/` ancestor — is the member pass's finding.
-
-## Related
-
-[01 — Architecture](01-architecture.md) · [02 — Developing](02-developing.md) · [14 — Assertions](14-assertions.md) · [18 — Conventions](18-conventions.md) · [19 — Linting](19-linting.md)