@gfdelarue/testkit 0.5.0 → 0.6.1

package/README.md

@@ -43,19 +43,25 @@ npm run testkit
 
 The command exits zero only when at least one test file completed and every
 required file passed. Test failures, infrastructure failures, interrupted or
-not-run files, an all-skipped selection, and an empty selection all fail the
-gate. `npm run testkit -- --allow-empty` is an explicit escape hatch for a job
+not-run files, a skipped file, and an empty selection all fail the gate. A file
+that a `skip` rule or its own `skip` metadata skips fails the gate even when
+every other file passes, and `--allow-empty` doesn't change that. `npm run testkit -- --allow-empty` is an explicit escape hatch for a job
 whose empty selection is intentional; it should not be the default CI command.
 
 Testkit writes the immutable, verifiable run bundle under
 `.testkit/results/runs/<run-id>/`. Upload `.testkit/results` with `if: always()`
-when CI evidence should survive a failed job.
+when CI evidence should survive a failed job. If the job can kill Testkit before
+it seals the run, run `testkit cleanup` before the upload, so the run is sealed
+and redacted first. See
+[Read run evidence without the CLI](#read-run-evidence-without-the-cli).
 
 ## Report a run to GitHub or Gitea
 
 `testkit ci report` reads the last run in the checkout and posts it in three
 places: one commit status, the job's step summary, and one pull request comment
-that it updates in place.
+that it updates in place. It updates only a comment that its token's user
+wrote, and posts a new comment when the tracker won't say who that user is. It
+leaves out a CI run or issue link that holds credentials or a secret.
 
 ```yaml
 permissions:
@@ -79,10 +85,17 @@ steps:
   it, as the `env` lines above do. Gitea Actions accepts the same lines.
 - Testkit reads the token from `GITHUB_TOKEN` or `GH_TOKEN` for GitHub, and
   from `GITEA_TOKEN` for Gitea. In a Gitea Actions job it also reads
-  `GITHUB_TOKEN`. With no token set, it asks `git credential fill`. The token
-  that `actions/checkout` keeps in the checkout does not answer that request.
-- Testkit reaches GitHub Enterprise Server only from a GitHub Actions job on
-  that server, so `testkit bug file` works there only in a job.
+  `GITHUB_TOKEN`. Outside such a job, it sends `GITEA_TOKEN` only to the host
+  that `GITEA_SERVER_URL` names, such as `https://gitea.example.com`. With no
+  token set, it asks `git credential fill`. The token that `actions/checkout`
+  keeps in the checkout does not answer that request.
+- Testkit sends a token only over HTTPS. A plain `http://` remote or repository
+  URL works only for a loopback host such as `127.0.0.1`.
+- A job's token reaches only the job's own repository. When `bugs.repository`
+  names another one, give the step a token that may write to it.
+- Testkit reaches GitHub Enterprise Server, and GitHub Enterprise Cloud with
+  data residency (`*.ghe.com`), only from a GitHub Actions job on that host, so
+  `testkit bug file` works there only in a job.
 - GitHub gives a pull request from a fork a read-only token. `ci report` then
   writes the step summary and fails when it posts the status. Add
   `continue-on-error: true` to the step when the repository takes pull requests
@@ -98,7 +111,7 @@ steps:
 Testkit files a confirmed bug as an issue in the repository's GitHub or Gitea.
 The issue names the regression test that fails because of the bug, the commit
 that introduced the faulty lines, and the command that reproduces the failure.
-[Bug records](docs/bug-records.md) gives the issue format.
+[`docs/bug-records.md`](https://app.unpkg.com/@gfdelarue/testkit/files/docs/bug-records.md) gives the issue format.
 
 1. Write a Testkit test that fails because of the bug.
 2. Write the bug record as a JSON file. `testkit bug guide` prints the fields
@@ -110,8 +123,15 @@ that introduced the faulty lines, and the command that reproduces the failure.
 
 `testkit bug file` runs the test at the checked-out commit and files the issue
 only when the test fails. It stops when tracked files have uncommitted changes,
-when no remote branch contains the commit, or when an open issue already covers
-the test. The token needs permission to create issues and labels.
+when no branch on the remote contains the commit, or when an open issue already
+covers the test. It asks the remote which branches hold the commit, with the
+checkout's Git credentials, so a branch that was rewound or deleted there
+doesn't count. When it can't tell, because a remote doesn't answer or a shallow
+clone's history stops short, it stops and says why. After it files, it reads the open issues again. If another checkout
+filed the same test at the same time and its issue is older, Testkit closes its
+own issue and stops, naming the older one. GitHub can list a new issue a few
+seconds late, so Testkit waits up to 7.5 seconds for its own and says so when
+it doesn't appear. The token needs permission to create issues and labels.
 
 `testkit bug record` saves the `--vitest-config`, `--vitest-project`, and
 `--vitest-runner` it was given in the draft, and asks for `--vitest-project`
@@ -130,6 +150,38 @@ fragment. It refuses `--database` and `--env`; pass those values through
 root, so a relative `--environment-file` needs `testkit bug file` run from
 there too.
 
+`testkit bug file --batch` files several drafts in one call: the ids it is
+given, or every unfiled draft under `.testkit/bugs/` when it is given none.
+
+- It checks the checkout once and reads the open issues before it runs the
+  tests. It stops before it files anything when tracked files have uncommitted
+  changes, when no remote branch contains the commit, or when it cannot read
+  the open issues.
+- It runs the drafts' tests in one `testkit run`, or one run for each
+  `--vitest-config`, `--vitest-project`, and `--vitest-runner` the drafts were
+  recorded with. Each draft is judged by its own file's result, so a file that
+  is skipped or fails outside its tests rules out only its own draft.
+- It reads the open issues again before it files, in case another checkout
+  filed one of the tests meanwhile.
+- It reports one line per draft: filed, already filed, rejected with the
+  reason, or not filed.
+  - A draft is rejected when its own checks fail, for example when its test
+    passes or an open issue already covers the test, and the batch carries on.
+  - When the tracker refuses a request, the batch stops filing and reports the
+    drafts it has not reached as not filed.
+- It exits non-zero when any draft is rejected or not filed. `--json` returns
+  the same list.
+
+Each draft records its issue as soon as the tracker returns it, so running the
+batch again files only what is left. An open issue whose facts match the ones a
+draft would file counts as that draft's issue, so a batch stopped between the
+two steps does not file the bug twice. When the tracker creates an issue
+without its labels, the batch stops, the draft stays unfiled, and Testkit
+closes that issue. If it can't, the message says so, and you close the issue.
+Then run the batch again with a token that may label issues. The batch creates
+at most one issue a second. When the tracker limits the rate, it stops and
+says when to run it again.
+
 ### Name the product's areas
 
 Add `areas` to `testkit.config.ts` so that each issue names the part of the
@@ -146,7 +198,7 @@ export default defineConfig({
 
 `testkit bug file` puts an `area:<id>` label on the issue. If no area claims
 the fault's file, it stops and names the file. Without `areas`, Testkit files
-bugs with no area. See [`areas`](testkit-config-schema.md#areas).
+bugs with no area. See the `areas` section of [`testkit-config-schema.md`](https://app.unpkg.com/@gfdelarue/testkit/files/testkit-config-schema.md).
 
 ### Pass a run whose failures are all filed
 
@@ -162,7 +214,8 @@ export default defineConfig({
 A run then passes when an open issue with the `testkit` label covers each
 failure. A new failure still fails the run, and closing an issue makes its
 test count again. When Testkit cannot read the issues, every failure is new.
-[Known failures](docs/bug-records.md#known-failures) gives the exact rule.
+The Known failures section of [`docs/bug-records.md`](https://app.unpkg.com/@gfdelarue/testkit/files/docs/bug-records.md) gives the
+exact rule.
 
 With `"allow"`, the run reads the open issues. In CI, pass the job's token to
 the `testkit run` step as well:
@@ -174,7 +227,9 @@ steps:
       GITHUB_TOKEN: ${{ github.token }}
 ```
 
-The job also needs the `issues: read` permission.
+The job also needs the `issues: read` permission. Testkit reads
+`GITHUB_TOKEN`, `GH_TOKEN` and `GITEA_TOKEN` itself and doesn't pass them to
+services or setup steps. A service that needs one declares it in its `env`.
 
 ### Run a campaign
 
@@ -264,8 +319,7 @@ the report to the chosen platform.
 
 Testkit has two built-in engines:
 
-- `node-vitest` runs plain Vitest test files and purpose-built `data` and
-  `contract` files with Node and Vitest.
+- `node-vitest` runs plain Vitest test files with Node and Vitest.
 - `playwright` runs `ui` files with Playwright and managed Chromium.
 
 A plain Vitest test file needs no Testkit suffix, directory, metadata, or
@@ -293,17 +347,16 @@ npx @gfdelarue/testkit setup playwright --with-deps # CI and fresh hosts
 ```
 
 Normal runs never install or download a browser.
-[Installation](docs/engines.md#installation) covers what an install contains,
-the supported platforms, and how to recover a broken one.
-[Typechecking](docs/engines.md#typechecking) covers the supported TypeScript
-versions and `tsconfig.playwright.json`.
+The Installation section of [`docs/engines.md`](https://app.unpkg.com/@gfdelarue/testkit/files/docs/engines.md) covers
+what an install contains, the supported platforms, and how to recover a broken
+one. Its Typechecking section covers the supported TypeScript versions and
+`tsconfig.playwright.json`.
 
 Testkit bounds the output it captures from each command it runs, and asks the
 command and its descendants to stop on cancellation or timeout.
 
-Managed task environment is engine input. Node/Vitest data and contract callbacks
-read immutable, enumerable `context.env`; and Playwright suites can read the
-same contract from `readPlaywrightContext()?.env`. Managed Node processes also
+Managed task environment is engine input. Playwright suites read it from
+`readPlaywrightContext()?.env`. Managed Node processes also
 expose each value as an immutable, non-enumerable `process.env.KEY` property so
 libraries that read `process.env` directly see it, but non-Node child processes
 do not receive consumer values unless the suite explicitly passes them.
@@ -315,17 +368,20 @@ reserves `APPDATA`, `ComSpec`, `HOME`, `LANG`, `LC_ALL`, `LOCALAPPDATA`, `PATH`,
 
 - Node/Vitest reserves `BASE_URL`, `FORCE_COLOR`, `NODE_OPTIONS`, `NO_COLOR`,
   `UPDATE_SNAPSHOT`, `VITEST_POOL_ID`, `VITEST_WORKER_ID`, and the `TESTKIT_`
-  keys it sets itself, listed in
-  [Environment](docs/engines.md#environment);
+  keys it sets itself, listed in the Environment section of
+  [`docs/engines.md`](https://app.unpkg.com/@gfdelarue/testkit/files/docs/engines.md);
   other `TESTKIT_` and `VITEST_` keys, such as
-  `TESTKIT_REQUIRE_COMPLETE_SUITE`, pass through;
+  `TESTKIT_REQUIRE_COMPLETE_SUITE`, pass through, though Vitest's own `TEST`,
+  `VITEST`, `VITEST_MODE`, `FORCE_TTY`, `MODE`, `DEV`, `PROD`, and `SSR`
+  replace a group's values;
 - Playwright reserves the `TESTKIT_`, `PLAYWRIGHT_`, `PWTEST_`, and `PW_TEST_`
-  prefixes plus `BASE_URL`, `FORCE_COLOR`, `NODE_OPTIONS`, and `NO_COLOR`.
+  prefixes plus `BASE_URL`, `DBUS_SESSION_BUS_ADDRESS`, `FC_FONTATIONS`,
+  `FORCE_COLOR`, `NODE_OPTIONS`, and `NO_COLOR`.
 
 Case-variant duplicates and invalid names or NUL-containing values fail instead
 of being normalized. Node/Vitest accepts at most 512 entries and
 4 MiB of UTF-8 key/value data. Playwright accepts at most 512 entries and 2 MiB
-of UTF-8 key/value data. [Environment](docs/engines.md#environment) lists the
+of UTF-8 key/value data. The Environment section of [`docs/engines.md`](https://app.unpkg.com/@gfdelarue/testkit/files/docs/engines.md) lists the
 complete limits, and [Named endpoints and databases](#named-endpoints-and-databases)
 covers the environment API.
 
@@ -344,12 +400,10 @@ npx @gfdelarue/testkit discover --json > .testkit/discovery.json
 npx @gfdelarue/testkit discover --output .testkit/discovery.json
 
 # Filter by type
-npx @gfdelarue/testkit --type contract
-npx @gfdelarue/testkit --type data
-npx @gfdelarue/testkit --type contract,data
 npx @gfdelarue/testkit --type ui
+npx @gfdelarue/testkit --type plain
 
-# Parallel file execution
+# Run up to 8 test tasks at once
 npx @gfdelarue/testkit --task-concurrency 8
 
 # One file-level wall clock budget for every suite file
@@ -357,15 +411,16 @@ npx @gfdelarue/testkit --file-timeout-seconds 60
 
 # Specific group / suite
 npx @gfdelarue/testkit --group frontend --type ui -s navigation
-npx @gfdelarue/testkit --group api --type contract -s health
-npx @gfdelarue/testkit --type contract,data -s contract:queries
+npx @gfdelarue/testkit --group api -s health
+npx @gfdelarue/testkit --group api --type plain
+npx @gfdelarue/testkit --type ui -s ui:checkout
 
 # Exact file
-npx @gfdelarue/testkit --type contract --file __testkit__/health.contract.testkit.ts
+npx @gfdelarue/testkit --type ui --file __testkit__/checkout.ui.testkit.ts
 npx @gfdelarue/testkit run --file src/sum.test.ts
 
 # Temporarily ignore repo-declared skip rules
-npx @gfdelarue/testkit --ignore-skip-rules --file __testkit__/billing.contract.testkit.ts
+npx @gfdelarue/testkit --ignore-skip-rules --file src/billing.test.ts
 
 # Lifecycle
 npx @gfdelarue/testkit status
@@ -380,15 +435,15 @@ npx @gfdelarue/testkit db schema refresh --service api
 npx @gfdelarue/testkit db schema verify --service api
 ```
 
-A `--type` that names test types, such as `--type contract,ui`, and typed suite
-selectors such as `contract:health` select typed files only. A run without them, or
-with `--type all`, also runs plain Vitest test files. To run every typed file
-and no plain one, name all three types: `--type ui,contract,data`.
+`--type ui` and typed suite selectors such as `ui:checkout` select typed files
+only. `--type plain` selects plain Vitest test files only. A run without
+`--type`, or with `--type all`, runs both. `--type` narrows the other filters,
+so `--group api --type plain` runs the `api` group's plain files and none of its
+UI files.
 
-`run`, `discover`, `artifacts`, and `workspace` select test groups with
-`--group`. On those commands `--service` is a deprecated alias for `--group`
-and prints a notice on stderr. `status`, `destroy`, `cleanup`, and `db schema`
-take `--service` to name a service.
+`run`, `discover`, `artifacts`, `workspace`, and `typecheck` select test groups
+with `--group`. `status`, `destroy`, `cleanup`, and `db schema` take `--service`
+to name a service.
 
 Database cleanup is scoped to the selected product. `cleanup --resources --global`
 is retired; use `--dir <product> cleanup --resources` for each product. After
@@ -396,10 +451,13 @@ deleting a product directory, remove its orphaned containers and volumes
 explicitly through Docker.
 
 Use `execution.taskConcurrency` in config and `--task-concurrency` on the CLI.
-`execution.workers`, `presets.nodeNext({ workers })` and `--workers` remain
-deprecated aliases through 0.2.x and will be removed in 0.3.0. When both names are
+A task is a typed file, a batch of typed files, or one Vitest invocation of
+plain files. Plain files in one invocation run with Vitest's file parallelism,
+which `taskConcurrency` doesn't limit.
+`execution.workers`, `presets.nodeNext({ workers })` and `--workers` are
+deprecated aliases. When both names are
 provided in config or on the CLI, their values must match. The CLI value overrides
-config after those checks. See the [execution settings](testkit-config-schema.md#execution).
+config after those checks. See the `execution` section of [`testkit-config-schema.md`](https://app.unpkg.com/@gfdelarue/testkit/files/testkit-config-schema.md).
 
 Batch `run` output stays intentionally short: one line per completed file,
 concise failure blocks, and a final summary. Service logs, captured runtime
@@ -495,7 +553,7 @@ The environment file is JSON:
   "handles": {
     "webhook": {
       "kind": "http-capture",
-      "url": "http://127.0.0.1:41000/webhook",
+      "url": "http://127.0.0.1:41000/__testkit__/<segment>/webhook",
       "requestsUrl": "http://127.0.0.1:41000/__testkit__/<capability>/requests",
       "resetUrl": "http://127.0.0.1:41000/__testkit__/<capability>/requests"
     }
@@ -586,7 +644,7 @@ assertLocalDatabaseUrl(process.env, "seed.ts");
 
 ## Setup
 
-See the [configuration schema](testkit-config-schema.md) for the complete,
+See [`testkit-config-schema.md`](https://app.unpkg.com/@gfdelarue/testkit/files/testkit-config-schema.md) for the complete,
 strict `testkit.config.ts` contract.
 
 Create `testkit.config.ts` at repo root:
@@ -672,7 +730,7 @@ neither:
 import { defineFile } from "@gfdelarue/testkit";
 
 export const testkit = defineFile({
-  engine: "node-vitest",
+  engine: "playwright",
   skip: "Billing is currently unavailable locally",
 });
 ```
@@ -682,15 +740,10 @@ A file can also name `locks`.
 one.
 
 In a typed file, the engine value is a required literal. The supported public
-authoring paths
-are `@gfdelarue/testkit/node-vitest/data`,
-`@gfdelarue/testkit/node-vitest/contract`, and `@gfdelarue/testkit/playwright`.
-Node/Vitest and Playwright suites may also import exact public APIs directly
-from Testkit's managed `vitest`, `@playwright/test`, `playwright`, and
-`playwright-core` packages.
-There are no legacy aliases or implicit-runner compatibility paths. A typed
-Node/Vitest file resolves `paths` from its nearest `tsconfig.json`, through
-Vite's `resolve.tsconfigPaths`.
+authoring path is `@gfdelarue/testkit/playwright`. Playwright suites may also
+import exact public APIs directly from Testkit's managed `@playwright/test`,
+`playwright`, and `playwright-core` packages.
+There are no legacy aliases or implicit-runner compatibility paths.
 
 `testkit.config.ts` is optional. Without it, Testkit runs every test file with
 zero setup: it starts no server, provisions no database, and loads no `.env`
@@ -727,7 +780,8 @@ setup processes, so set it deliberately.
 Testkit-owned Docker resources are labelled at creation time so they can be
 found again even if product-local `.testkit` state is deleted. `testkit destroy`
 removes labelled resources for the current product after service state is
-destroyed. `testkit cleanup --resources` cleans stale resources for the current
+destroyed. It leaves run results under `.testkit/results` and other files
+under `.testkit`, such as the compiled config and timings, in place. `testkit cleanup --resources` cleans stale resources for the current
 product. Both commands remove only the current product's resources and leave
 other products' alone, including their idle caches. Host-local Postgres data
 lives in a Testkit-labelled named Docker volume, so cleanup can find and remove
@@ -735,6 +789,10 @@ it. Database changes for one product run one at a time; other products don't
 wait for them. Use `cleanup --resources --dry-run` to preview the selected
 product's cleanup.
 
+A run's start and its post-run maintenance don't list or reclaim Docker
+resources. A run stops its retained database by name when it releases the run's
+resources.
+
 `database.template` is the database-side equivalent for reusable template DB
 state. When `database.sourceSchema` is configured, Testkit treats the configured
 source database as the schema source of truth. A normal `testkit run` resolves a
@@ -845,6 +903,8 @@ services: {
 }
 ```
 
+## Run evidence
+
 Every terminal run is sealed under `.testkit/results/runs/<run-id>/` with a
 canonical `run.json`, `provenance.json`, `manifest.json`, and the run's exact
 artifact/log/setup files. Payloads are SHA-256 addressed under
@@ -870,25 +930,56 @@ workspace API.
 Sealing replaces secrets with `<redacted>` in the run record and in every text
 file of the bundle. A key names a secret when it holds `PASSWORD`, `TOKEN`,
 `SECRET`, `PRIVATE_KEY`, `AUTH`, `COOKIE`, `SESSION`, or `API_KEY` in any letter
-case. Sealing redacts:
+case, or when its last word is `PASS`, `PASSWD`, `PAT`, `DSN`, `CREDENTIAL`, or
+`CREDENTIALS`. `AUTH` doesn't count in `AUTHOR` or `AUTHORITY`, so
+`GIT_AUTHOR_NAME` names no secret, though `AUTHORIZATION` still does. `SESSION`
+doesn't count before `COUNT`, `DURATION`, `EXPIR`, `LENGTH`, `LIMIT`, `MAX`,
+`TIMEOUT`, or `TTL`, as in `sessionCount` and `SESSION_TIMEOUT`. A key whose
+last two words are `API`, `PRIVATE`, `SIGNING`, or `ENCRYPTION` and then `KEY`,
+as in `apiKey`, `x-api-key`, and `privateKey`, names a secret too, and so does
+an upper-case key whose last word is `KEY`, such as `STRIPE_KEY`, unless the
+word before it is `PUBLIC` or `PUBLISHABLE`. Words break at any character other
+than a letter or a digit, and before an upper-case letter that follows a
+lower-case letter or a digit. Sealing redacts:
 
 - A `KEY=value` assignment under such a key, an `Authorization`,
-  `Proxy-Authorization`, `Cookie`, or `Set-Cookie` header value, a JSON string
-  value under such a key, even when the key is spelled with escapes, a
-  single-quoted `'password': '…'` value, and a URL's password, wherever they
-  appear. A quoted value ends at its closing quote and keeps its quotes, and a
-  value that starts with an auth scheme such as `Bearer` ends with its line.
-  A secret in one JSON value leaves the record's other values as they are.
+  `Proxy-Authorization`, `Cookie`, `Set-Cookie`, `Api-Key`, or `X-Api-Key`
+  header value, a JSON string value under such a key, even when the key is
+  spelled with escapes, a single-quoted string value under such a key, a token
+  of at least eight characters with a digit after `Bearer`, and a URL's
+  password, wherever they appear. A
+  quoted value ends at its closing quote and keeps its quotes, and a value that
+  starts with an auth scheme such as `Bearer` ends with its line. A secret in
+  one JSON value leaves the record's other values as they are.
+- Every string in a JSON array or object under such a key, unless the key
+  names a secret only through `AUTH`, `COOKIE`, or `SESSION`, so `tokens`,
+  `credentials`, and `privateKey` count and `session` and `auth` settings stay.
+  In an object with a `name` string and a `value` string, only the `value` and
+  members whose own key names a secret count. Numbers and booleans stay.
+- The value after `password:` or `passwd:`, or after a key whose last word is
+  one of those: a quoted value anywhere, as in `{ password: 'hunter2' }`, and
+  an unquoted value at the start of a line, as in YAML, when it is the line's
+  one word. A value that is one word of letters, perhaps followed by
+  punctuation such as `!` or `.`, stays, and so does an unquoted value after
+  other text, so `password: 'Required'`, `password: required!`, and
+  `rejects a password: too short` stay.
+- A token of at least 20 characters with a digit that stands alone as the user
+  of an `http` or `https` URL, as in `https://ghp_…@github.com`. A URL's
+  password may hold `/` and `@`, and sealing also finds it in a directory name,
+  which keeps one slash of the URL, as in `postgres:/app:…@db`.
+- A header or cookie stored as a `{"name": …, "value": …}` pair, as Playwright
+  traces and HAR files store them: the value when the name names a secret, and
+  every value in a `cookies` array.
 - The value of each such key, and of each key that `redact` names, in the
-  environment Testkit runs in. When the value is a URL, its password counts
-  too.
+  environment Testkit runs in. When the value is a URL, its password, or a
+  token that stands alone as its user, counts too.
 - The values the run's environment resolved: each value under such a key or a
-  key that `redact` names, and the password of each URL. A PostgreSQL URL's
-  password may also be a `password` query parameter, as libpq reads it. This
-  covers config `env`, env files, `local.env`, dependency services, base,
-  readiness, UI, and database URLs, `--env`, `--env-from`, and an
-  `--environment-file`. A value under such a key that is a URL counts only for
-  its password.
+  key that `redact` names, and the password or token user of each URL. A
+  PostgreSQL URL's password may also be a `password` query parameter, as libpq
+  reads it. This covers config `env`, env files, `local.env`, dependency
+  services, base, readiness, UI, and database URLs, `--env`, `--env-from`, and
+  an `--environment-file`. A value under such a key that is a URL counts only for
+  its password or token user.
 - The unguessable segment in each [HTTP capture's](#handles) operation URLs,
   from a setup module's capture or an `--environment-file` handle.
 
@@ -910,12 +1001,41 @@ and keys in the free-form data and metadata that tests attach. When output cuts
 the cut with `…` or `...`, sealing redacts the part that shows. `testkit run
 --json` and the run's progress output apply the same redaction.
 
+Sealing also redacts inside `.zip` and `.gz` files, and files that start like
+one, such as a Playwright `trace.zip`. It applies the rules above to each text
+entry, such as a trace's actions, network log, and page and API responses, and
+writes the archive again with the redacted entries. A text entry is valid UTF-8
+without binary control characters, or UTF-16 with a byte order mark. Other
+entries keep their bytes. A ZIP with a comment or extra fields is written again
+without them, and a gzip file is always written again without the name and
+comment in its header. A trace stays readable in the Playwright trace viewer,
+with `<redacted>` where a typed password or a token was.
+
+Sealing refuses an archive it can't redact:
+
+- one it can't read: encrypted, needing ZIP64 sizes, compressed with a method
+  other than deflate, larger than 512 MiB once expanded, or damaged, including
+  a ZIP with bytes that none of its entries account for;
+- one with a binary entry, such as a screenshot, that holds one of the values
+  above, as UTF-8 or UTF-16;
+- one that holds another archive.
+
+Sealing removes each file it refuses from the run's results and fails the run
+with the reason, for example:
+
+```text
+Refusing to archive compressed file whose entry inner/trace.zip is itself an archive, and removed it: …/.testkit/results/artifacts/frontend/task-1-01-bundle.zip
+```
+
+The run, or the `testkit stop`, `testkit cleanup` or next run that seals it
+later, then seals the rest of its results and records the reason.
+
 Some secrets stay visible:
 
 - What a setup module prints goes to the terminal as written.
-- Sealing does not look inside compressed or binary files, such as a Playwright
-  `trace.zip`. It refuses to seal a binary file that holds one of the values
-  above in plain bytes.
+- Sealing does not redact images or video, including the screenshots in a
+  trace. Text typed into a page shows in them. Sealing refuses and removes a
+  binary file that holds one of the values above as UTF-8 or UTF-16.
 - When a run's process is killed before it seals the run, `testkit stop`,
   `testkit cleanup`, or the next run seals it from another process. That
   process does not have the values the run's environment resolved or the
@@ -923,6 +1043,15 @@ Some secrets stay visible:
   values under the words above. The bundle's `archive.redaction.status` is then
   `source-targets-unavailable` instead of `applied`.
 
+Sealing also takes out local paths. In the run record, in every text file of
+the bundle, and in every text entry of a compressed file, a path under the
+product directory becomes relative to it, the product directory itself becomes
+`.`, and a path under your home directory starts with `~`. This covers engine
+reports, failure stacks, logs, and Playwright traces, and happens after
+redaction. Binary files and binary entries keep their paths. When sealing
+changes a file, the file's size and SHA-256 in `run.json` describe the sealed
+file.
+
 Use the artifact archive config to opt into pruning or atomic publication to
 an external directory. Local retention is indefinite by default:
 
@@ -964,6 +1093,73 @@ Programmatic consumers can import `listRunBundles`, `loadRunBundleArtifact`,
 `loadRunBundleManifest`, and `verifyRunBundle` from
 `@gfdelarue/testkit/workspace`.
 
+### Read run evidence without the CLI
+
+Run evidence is plain files, so you can investigate a run with `ls`, `grep`,
+`jq`, and `sha256sum` when `testkit` can't start, for example because the
+config no longer loads. A command that fails to load the config stops before it
+writes to `.testkit/results`, and `testkit artifacts` doesn't need the config.
+
+| Path under `.testkit/results/`  | What it holds                                                                                                                                                                                                          |
+| ------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `runs/<run-id>/run.json`        | A sealed run's record: `run.status`, `run.interruptReason`, and each file's `status`, `failureDetails`, and `artifacts`                                                                                                |
+| `runs/<run-id>/manifest.json`   | Every other file in the bundle, with its `sha256` and `bytes`                                                                                                                                                          |
+| `runs/<run-id>/provenance.json` | The run's CI, source, runtime, and redaction facts                                                                                                                                                                     |
+| `runs/<run-id>/files/`          | The run's `logs/`, `artifacts/`, and `setup/` files. Each `artifacts[].path` in `run.json` points here, relative to the product directory                                                                              |
+| `latest.json`                   | The record of the last run that Testkit finished writing up, with its publication and retention results. A run killed after it was sealed can be in `runs/` but not here, so `runs/<run-id>/run.json` is the authority |
+| `live.json`                     | The record of a run that isn't sealed, with `run.status` `running`                                                                                                                                                     |
+| `logs/`, `artifacts/`, `setup/` | The files that unsealed run has written so far                                                                                                                                                                         |
+
+Anything else under `.testkit/` can change between releases, including
+`objects/`, which stores the bytes behind each bundle's files.
+
+A run is sealed once `runs/<run-id>/` exists. Testkit writes the bundle under a
+hidden name in `runs/`, writes `manifest.json` last, and then renames the
+directory, so `runs/<run-id>/` is never partly written. Ignore names in `runs/`
+that start with `.`. A copy of a bundle, such as a CI upload, is whole when
+every file that its `manifest.json` lists has the listed `sha256`. A sealed
+`run.json` has `archive.status` `complete` and `run.status` `passed`, `failed`,
+or `interrupted`.
+
+`live.json` means a run is in progress, or its process died before Testkit
+finished with it. If `runs/<run-id>/` exists for the `run.id` in `live.json`,
+the run was sealed and the bundle is its record: `live.json` and the active
+directories are leftovers, which the next `testkit run`, `cleanup`, or `destroy`
+removes. Testkit replaces `live.json` whole on each update, so it always parses.
+Its `generatedAt` is the time of the last update, and each file's `status` is
+what it was then, so a file that was still running shows `not_run`. The files
+in `logs/`, `artifacts/`, and `setup/` aren't redacted until the run is sealed.
+
+How an unfinished run gets sealed:
+
+- When Ctrl-C, `SIGTERM`, or `testkit stop` interrupts the run, or its process
+  exits early, Testkit seals it straight away. `run.status` is `interrupted`,
+  or `failed` when nothing asked the run to stop, and `run.interruptReason`
+  says why.
+- When the process is killed with `SIGKILL`, by the out-of-memory killer, or
+  with its host, the run stays unsealed until the next `testkit run`,
+  `cleanup`, or `destroy` seals it, before doing anything else, with
+  `run.status` `interrupted` and `run.interruptReason`
+  `stale run process not active`. `testkit stop` seals it too, with its
+  `--reason` or `stop requested`. The sealed `run.finishedAt` is when the
+  command sealed it, not when the process died.
+
+Testkit keeps what reached the disk. It can't keep output that a process hadn't
+written yet, anything written after the disk filled up or became read-only, or
+work that a killed process would have done on its way out. A log can end
+mid-line.
+
+For example, to see what failed in the run that `latest.json` names and check
+its files:
+
+```sh
+cd .testkit/results
+run=runs/$(jq -r .run.id latest.json)
+jq '.run.status, .run.interruptReason' "$run/run.json"
+jq '.groups[].suites[].files[] | select(.status != "passed") | {path, status, failureDetails, artifacts: [.artifacts[].path]}' "$run/run.json"
+jq -r '.files[] | "\(.sha256)  \(.path)"' "$run/manifest.json" | (cd "$run" && sha256sum --check --quiet)
+```
+
 ## Authoring
 
 ### Named endpoints and databases
@@ -1016,14 +1212,14 @@ something its environment prepared. Today that is an HTTP capture, which a
 The handle is named after the capture's `id`:
 
 ```js
-// tests/webhook.contract.testkit.setup.mjs
+// tests/webhook.test.setup.mjs
 export async function setup({ sidecars }) {
   await sidecars.httpCapture({ id: "webhook", path: "/webhook" });
 }
 ```
 
 ```ts
-// tests/webhook.contract.testkit.ts
+// tests/webhook.test.ts
 import { handle } from "@gfdelarue/testkit/environment";
 
 const webhook = handle("webhook");
@@ -1045,6 +1241,14 @@ run's results, artifacts, and events, and the capture refuses any other
 operation. When Testkit releases the file's environment, the capture closes and
 the handle expires. Calling a handle never starts a sidecar or a service.
 
+The capture's `url` holds a second unguessable segment, which Testkit also
+keeps out of the run's records. The capture records a request only when its
+path starts with that segment, and answers any other path with 404. A captured
+request's `path` leaves the segment out: a request to `url` records `/webhook`,
+and one to `url` + `/42` records `/webhook/42`. The capture answers 403 to a
+request whose `Host` header isn't `127.0.0.1:<port>`, which keeps a web page
+from reaching it through DNS rebinding.
+
 - A name with no handle throws `EnvironmentValueMissingError` with `kind`
   `"handle"`, and the test ends as an infrastructure failure, as for a missing
   endpoint.
@@ -1069,7 +1273,8 @@ test, in any order.
   so read them and leave them unchanged.
 - When the test ends, leave its rows in place. Testkit resets the databases it
   provisions. By default, every run starts from a fresh clone of the template
-  database. See [`database.reset`](testkit-config-schema.md#database).
+  database. See `database.reset` in the `database` section of
+  [`testkit-config-schema.md`](https://app.unpkg.com/@gfdelarue/testkit/files/testkit-config-schema.md).
 - Clean up only what Testkit doesn't own, such as an account in a third-party
   sandbox. Register the cleanup as soon as the test creates the account. Give
   the account a unique name, so that a leftover from a cleanup that never ran
@@ -1077,19 +1282,20 @@ test, in any order.
 
 ```ts
 import { randomUUID } from "node:crypto";
-import { defineFile } from "@gfdelarue/testkit";
-import { contractScenario } from "@gfdelarue/testkit/node-vitest/contract";
-import { expect, onTestFinished } from "vitest";
+import { endpoint } from "@gfdelarue/testkit/environment";
+import { expect, onTestFinished, test } from "vitest";
 
 import { sandbox } from "../payments-sandbox.js";
 
-export const testkit = defineFile({ engine: "node-vitest" });
-
-contractScenario("a refund reaches the sandbox customer", async ({ http }) => {
+test("a refund reaches the sandbox customer", async () => {
   const customer = await sandbox.createCustomer({ email: `refund-${randomUUID()}@example.test` });
   onTestFinished(() => sandbox.deleteCustomer(customer.id));
 
-  const response = await http().post("/api/refunds", { customerId: customer.id, amountCents: 500 });
+  const response = await fetch(new URL("/api/refunds", endpoint("api")), {
+    method: "POST",
+    headers: { "content-type": "application/json" },
+    body: JSON.stringify({ customerId: customer.id, amountCents: 500 }),
+  });
   expect(response.status).toBe(201);
 });
 ```
@@ -1125,18 +1331,34 @@ Files that name the same lock never run at the same time within one run.
 Testkit doesn't share locks between runs, such as two CI jobs. Two tests that
 need a lock because they share rows need their own rows instead.
 
+A plain Vitest file names its locks in its group's `requirements`:
+
 ```ts
-export const testkit = defineFile({ engine: "node-vitest", locks: ["payments-sandbox-webhook"] });
+groups: {
+  payments: {
+    roots: ["src/payments"],
+    uses: ["api"],
+    requirements: {
+      files: [{ path: "src/payments/webhook.test.ts", locks: ["payments-sandbox-webhook"] }],
+    },
+  },
+},
+```
+
+A browser file can name them in `defineFile`:
+
+```ts
+export const testkit = defineFile({ engine: "playwright", locks: ["payments-sandbox-webhook"] });
 ```
 
 ### Node setup beside a test
 
-A test such as `tests/webhook.contract.testkit.ts` can have a sibling
-`tests/webhook.contract.testkit.setup.mjs`. Testkit runs its named `setup` export,
-or its default export, before starting the test engine:
+A test such as `tests/webhook.test.ts` can have a sibling
+`tests/webhook.test.setup.mjs`. Testkit runs its named `setup` export, or its
+default export, before starting the test engine:
 
 ```js
-// tests/webhook.contract.testkit.setup.mjs
+// tests/webhook.test.setup.mjs
 export async function setup({ sidecars }) {
   const capture = await sidecars.httpCapture({ path: "/webhook" });
   return {
@@ -1148,13 +1370,15 @@ export async function setup({ sidecars }) {
 Setup is part of preparing the file's environment. Testkit runs it once, after
 it acquires the services the file's group uses and before the test engine
 starts. Testkit never batches a Playwright file that has setup with other
-Playwright files. Files without setup still batch.
+Playwright files, and a plain Vitest file that has setup runs in its own Vitest
+invocation. Files without setup still batch.
 
 Setup runs with its own JavaScript state. It can use Node APIs, prepare
 external resources, and start HTTP capture listeners. Tests
-reach a capture by its `id` through [`handle()`](#handles). A capture's
-`requestsUrl` and `resetUrl` hold an unguessable segment that Testkit keeps out
-of the run's records, and its capture `path` may not start with `/__testkit__/`.
+reach a capture by its `id` through [`handle()`](#handles). A capture's `url`,
+`requestsUrl` and `resetUrl` hold unguessable segments that Testkit keeps out
+of the run's records. Its capture `path` may not start with `/__testkit__/` or
+contain `.` or `..` segments.
 The context contains `deadlineMs`, `signal`, `env`, `leaseDir`, `productDir`,
 `serviceName`, `testFile`, and `sidecars`. `serviceName` holds the name of the
 test's group. Setup has the same permissions as the Testkit process. It is not
@@ -1165,7 +1389,9 @@ setup modules. Its tests receive the environment file's `setupData` instead.
 
 Return plain JSON, or `{ data, cleanup }` with an optional cleanup function.
 Testkit passes the data to the engine as `setupData` and records it with the
-setup module path and sidecar handles. Bare `null` or `undefined`, and a
+setup module path and sidecar handles. Tests read it with `setupData()` from
+`@gfdelarue/testkit/environment`, which returns `{}` when the file has no setup
+module and throws outside a Testkit run. Bare `null` or `undefined`, and a
 cleanup-only result, give empty data. `{ data: null }` preserves `null`.
 Data must encode to at most 1 MiB of JSON. Invalid data reports its JSON path,
 such as `$.items[1]`.
@@ -1189,15 +1415,226 @@ most 256 connections.
 
 Discovery tries sibling `.setup.mjs`, sibling `.setup.js`, then the matching
 `.mjs` and `.js` files in `__setup__`, in that order. For the example above,
-the fallback is `tests/__setup__/webhook.contract.testkit.mjs`.
+the fallback is `tests/__setup__/webhook.test.mjs`.
 
 ### HTTP and persistence checks
 
 Use plain Vitest files for ordinary HTTP, service, and database checks. Read
 configured URLs with `endpoint(name)` and `database(name)` from
 `@gfdelarue/testkit/environment`, then use `fetch` or your application's
-database client. Use `contractScenario` when a typed contract file needs the
-managed contract context. Use `dataScenario` for structured data-flow evidence.
+database client.
+
+### Record data-flow evidence
+
+`dataFlow(context)` from `@gfdelarue/testkit/node-vitest/data` records what a
+plain Vitest test sees data do: metrics, counts, bytes, durations, money,
+ratios, sequences, records, actors, systems, transitions, events, findings,
+external calls, and cache, LLM, and RPC usage. Budgets check the recorded
+values, for example that a metric stays under a limit or that a sequence was
+recorded.
+
+```ts
+import { endpoint } from "@gfdelarue/testkit/environment";
+import { dataFlow } from "@gfdelarue/testkit/node-vitest/data";
+import { test } from "vitest";
+
+test("lists one page of orders", async (context) => {
+  const flow = dataFlow(context);
+  const response = await fetch(`${endpoint("api")}/orders?page=1`);
+  const body = await response.text();
+  flow.recordHttpRequest({
+    method: "GET",
+    path: "/orders",
+    status: response.status,
+    responseBytes: Buffer.byteLength(body),
+  });
+  flow.expectMetric("http.response.bytes").atMost(64_000);
+});
+```
+
+- `dataFlow` needs the context of a running test. Every call in one attempt
+  returns the same recorder, and a call without that context throws.
+- The library reads no URL, environment value, fixture file, or Testkit config.
+  Read named URLs from `@gfdelarue/testkit/environment`, log in from test code,
+  and read files with `fs`.
+- A failed budget fails its test when the test finishes. The failure detail has
+  the kind `data-flow-budget` and a key made of the test's full title and the
+  budget.
+- Testkit writes `data-flow.json` and `data-flow-report.md` for a file whose tests
+  recorded something. Each such test is one scenario, from its final attempt. A
+  test that records nothing adds nothing, and a file whose tests record
+  nothing gets no data-flow artifacts.
+
+### Slow the browser's network and CPU
+
+`emulateNetwork(page, conditions)` and `emulateCpu(page, slowdown)` from
+`@gfdelarue/testkit/playwright` slow a page the way Chrome DevTools'
+throttling does. A `ui` test can use them to fail when a change makes a page
+unusable on a slow connection or a slow device:
+
+```ts
+import { defineFile } from "@gfdelarue/testkit";
+import { emulateCpu, emulateNetwork, expect, test } from "@gfdelarue/testkit/playwright";
+
+export const testkit = defineFile({ engine: "playwright" });
+
+test("the dashboard is usable on a slow connection", async ({ page }) => {
+  await emulateNetwork(page, "slow-4g");
+  await page.goto("/dashboard");
+  await expect(page.getByRole("heading", { name: "Orders" })).toBeVisible({ timeout: 10_000 });
+});
+
+test("the dashboard is usable on a slow phone", async ({ page }) => {
+  await emulateCpu(page, 4);
+  await page.goto("/dashboard");
+  await expect(page.getByRole("heading", { name: "Orders" })).toBeVisible({ timeout: 10_000 });
+});
+```
+
+The assertion's timeout is the time limit. The helpers add no timing or
+metrics API.
+
+`emulateNetwork` takes a profile name or custom values. Each profile has the
+values of the DevTools preset of the same name in the Chromium that Testkit
+runs:
+
+| Profile     | DevTools preset | Download   | Upload     | Latency  |
+| ----------- | --------------- | ---------- | ---------- | -------- |
+| `"fast-4g"` | Fast 4G         | 8,100 kbps | 1,350 kbps | 165 ms   |
+| `"slow-4g"` | Slow 4G         | 1,440 kbps | 675 kbps   | 562.5 ms |
+| `"3g"`      | 3G              | 400 kbps   | 400 kbps   | 2,000 ms |
+
+DevTools renamed two presets in 2024: Slow 4G was Fast 3G, and 3G was Slow 3G.
+Custom values give speeds in kilobits per second and latency in milliseconds:
+
+```ts
+await emulateNetwork(page, { latencyMs: 300, downloadKbps: 400, uploadKbps: 200 });
+```
+
+`emulateCpu` makes the page's main thread, which runs its JavaScript and
+layout, `slowdown` times slower. DevTools' fixed CPU options are 4, 6, and 20.
+Testkit doesn't calibrate the slowdown to the machine, as DevTools' "Mid-tier
+mobile" and "Low-tier mobile" options do. `emulateCpu(page, 1)` restores full
+speed.
+
+- Call the helpers before `page.goto()`. Both settings last across navigations
+  until the page closes.
+- Neither setting reaches a cross-site iframe. Chromium runs one in a process
+  of its own, at full speed.
+- The network conditions apply to that page only. A popup it opens, or another
+  page, loads at full speed. Playwright's `browserContext.setOffline()` clears
+  them.
+- The CPU slowdown applies to the browser process that runs the page. A
+  same-site popup that keeps its `window.opener` shares that process and slows
+  down too, and closing it ends the slowdown. Call `emulateCpu` again after
+  closing one.
+- Like DevTools, `emulateNetwork` also sets `navigator.connection` until the
+  page navigates to another site.
+- An unknown profile name or field, a negative or non-finite value, a speed of
+  0, or a CPU slowdown outside 1 to 100 throws an error that names the value.
+
+Three things to keep in mind:
+
+- Set generous time limits. A CI runner has less CPU than a laptop, and a
+  [campaign](#run-a-campaign) files a failing test as a bug, so a tight limit
+  produces false bug reports.
+- A CPU slowdown multiplies the speed of the machine that runs the test, so 4
+  on a slow CI runner is much slower than 4 on a laptop. A time limit under a
+  CPU slowdown depends on the runner far more than one under network
+  conditions, which are the same on every machine.
+- Chromium holds each response for at least the latency and shares the
+  bandwidth among the page's requests, but it doesn't model TCP. The result
+  approximates a slow connection rather than reproducing one.
+
+### Check a ui test's browser traffic
+
+Testkit records the requests every `ui` test's pages send, with no change to the
+test. The record catches bugs that live in how a frontend uses its API, such as
+a checkout that sends its payment twice or a list page that fetches each row
+separately, even when no assertion checks for them.
+
+For each `ui` file whose tests sent requests, Testkit writes
+`browser-network.json` and `browser-network-report.md` from each test's final
+attempt. A test's section of the report looks like this:
+
+```md
+## checkout › pays for the cart (passed)
+
+21 requests, 452 KB received: script 312 KB, font 48 KB, document 41 KB, fetch 14 KB
+
+| Service | Request           | Count | Sent   | Received | Status |
+| ------- | ----------------- | ----- | ------ | -------- | ------ |
+| web     | GET /cart         | 1     | 0 B    | 41 KB    | 200    |
+| api     | GET /products/:id | 8     | 0 B    | 11 KB    | 200    |
+| api     | POST /payments    | 2     | 1.2 KB | 400 B    | 201    |
+
+Other origins: fonts.gstatic.com, 2 requests, 48 KB
+
+Leads:
+
+- `POST /payments` to api went out 2 times with the same body.
+```
+
+- Rows cover page loads and API calls, which are Playwright's `document`,
+  `fetch`, and `xhr` requests, to the services the test's group uses. A row
+  names the service rather than its URL, because each run gives services
+  different ports. Scripts, styles, images, and fonts count only toward the
+  totals by type. Requests to other origins appear by host name only.
+- A path's numbers, UUIDs, and hex strings of 16 or more characters become
+  `:id`, so eight product fetches make one row with a count of 8.
+- The record never holds query strings, headers, or bodies. Paths pass through
+  Testkit's redaction, and sealing redacts them again with the run's secrets.
+  To spot a repeated write, Testkit hashes each body in memory and keeps only
+  the count.
+- Sizes are body bytes as they crossed the network, so a compressed response
+  counts its compressed size and one that a `page.route()` handler fulfills
+  counts 0. Headers don't count.
+- Each test keeps 200 requests in detail, 100 rows, and 20 other origins. The
+  record counts the rest.
+- The leads point at two patterns: a POST, PUT, PATCH, or DELETE sent more than
+  once to the same URL with the same body, and a page load or API call that
+  failed or got a 4xx or 5xx status in a test that passed. A lead never fails a
+  test.
+- The record covers every context a test opens, including one from
+  `browser.newContext()`. It doesn't cover a context that a `beforeAll` hook
+  opens.
+
+To assert on the traffic, call `browserRequests()` from
+`@gfdelarue/testkit/playwright`. It returns the requests the test's pages have
+sent so far, oldest first:
+
+```ts
+import { browserRequests, expect, test } from "@gfdelarue/testkit/playwright";
+
+test("checkout charges the card once", async ({ page }) => {
+  await page.goto("/cart");
+  await page.getByRole("button", { name: "Pay" }).click();
+  await expect(page.getByText("Payment received")).toBeVisible();
+
+  const payments = (await browserRequests()).filter(
+    (request) => request.service === "api" && request.method === "POST" && request.path === "/payments",
+  );
+  expect(payments).toHaveLength(1);
+});
+```
+
+Each entry has `service`, the name of the service it went to or `null`,
+`method`, `url`, `path`, `resourceType`, `status`, `failure`, `requestBytes`,
+`responseBytes`, and `durationMs`. `path` is the URL's path as sent, without
+`:id`. Add up entries with plain array code, for example to check a page's
+weight:
+
+```ts
+const received = (await browserRequests()).reduce((total, request) => total + request.responseBytes, 0);
+expect(received).toBeLessThan(500_000);
+```
+
+`browserRequests()` waits up to 5 seconds for requests already in flight, so
+their entries have a status and sizes. It doesn't wait for EventSource streams.
+A request still unfinished after that has its status if the response's headers
+arrived, 0 response bytes, and a `durationMs` of `null`. A WebSocket connection
+appears with the `resourceType` `websocket` and no status, sizes, or duration.
+The record counts connections, not their messages.
 
 ## Discovery
 
@@ -1228,24 +1665,26 @@ Testkit supports Vitest 4.x. Another major, a broken installation, a root
 Vitest config that fails to load, or a Vitest that `package.json` declares but
 that is not installed fails before any test runs, naming the version and path.
 `--vitest-runner managed` avoids the repository's Vitest. A run that selects
-only typed files, with `--type` or with typed `--file` paths, `bug record` or
+only typed files, with `--type ui` or with typed `--file` paths, `bug record` or
 `bug file` for a typed test, and the commands that select no tests (`status`,
 `run status`, `doctor`, `destroy`, `cleanup`, and `db schema`) don't load the
 repository's Vitest, so they still work. A product that neither installs nor
 declares Vitest has no plain test files.
 
-All plain files in a run go to one Vitest invocation, so root global setup,
-teardown, and the repository's reporters run as often as they do under
-`vitest run`, and Testkit's reporter runs beside them. The invocation's deadline
-is the sum of its files' timeouts; Vitest's own test and hook timeouts apply
-inside it. A file that two projects select runs in both, its result combines
-both runs, and its evidence names each run's project. Files from different
-groups run together when their groups give them the same services, values, and
-locks; none may have a setup module or isolation other than `shared`.
-Otherwise the run stops before any file runs and names the groups and what
-differs. Services, locks, isolation, or a setup module stop it before Testkit
-provisions anything; values stop it before Vitest starts. Select one group with
-`--group`.
+Plain files run in one Vitest invocation per environment their groups give them.
+Groups that give their files the same values share one, such as `root` and the
+other groups that use no services. A group that uses a service Testkit starts
+gets an invocation of its own.
+Inside each invocation, root global setup, teardown, and the repository's
+reporters run as they do under `vitest run`, and Testkit's reporter runs beside
+them, so a run calls them once for each invocation. An invocation's deadline is
+the sum of its files' timeouts; Vitest's own test and hook timeouts apply inside
+it. A file that two projects select runs in both, its result combines both
+runs, and its evidence names each run's project. A file with a setup module,
+locks, or isolation other than `shared` runs in its own Vitest invocation with
+its own environment. Invocations run one after another unless
+`--task-concurrency` or `execution.taskConcurrency` is above 1. To run one group's
+files alone, select it with `--group`.
 
 Plain files see the host environment Testkit started with: `HOME`, `PATH`,
 temporary and XDG directories, locale, `CI`, `FORCE_COLOR`, `NO_COLOR`, and any
@@ -1259,14 +1698,21 @@ shell's environment and the group's values; as under `vitest run`, Vitest sets
 `TEST`, `VITEST`, and `NODE_ENV` after them. `--vitest-runner managed` leaves the
 shell's `NODE_OPTIONS` out.
 
+When Vitest detects a coding agent from the environment, such as `CLAUDECODE`,
+`AI_AGENT`, or `CURSOR_AGENT`, and the repository's Vitest config names no
+reporter, Vitest uses its agent reporter. That reporter prints no console output
+from a passing test, so the output is missing from the file's
+`node-vitest-stdout` artifact. A failing test's output still appears. Name a
+reporter in the Vitest config, such as `reporters: ["default"]`, to keep it.
+
 Two settings narrow the files Vitest selects: `discovery.exclude` in `testkit.config.ts`, and
 a declared group's `exclude`. Testkit's built-in exclusions for typed files,
-such as `dist`, `build`, and `coverage`, `discovery.roots`, and a legacy
-service's exclusions do not apply to plain files.
+such as `dist`, `build`, and `coverage`, and `discovery.roots` do not apply to
+plain files.
 
 A plain file belongs to the group whose roots contain it, or to the implicit
-`root` group, which uses no service. Legacy service ownership never claims a
-plain file. Testkit starts no service for a plain file in `root`.
+`root` group, which uses no service. Testkit starts no service for a plain
+file in `root`.
 
 The plain files in one directory form a suite named after that directory,
 relative to the group's root. In `root`, `--suite src` selects
@@ -1275,7 +1721,10 @@ its own suite, so `sum.test.ts` in a group rooted at `src` is in suite `sum`.
 When two suites in a group would share a name, Testkit lengthens the later
 ones with parent directories, such as `api-src`, and numbers them if that is
 not enough. `testkit typecheck` checks plain TypeScript test files and skips
-plain JavaScript ones, as `tsc` does without `allowJs`.
+plain JavaScript ones, as `tsc` does without `allowJs`. It adds the TypeScript
+files in each Vitest project's `setupFiles` to the program, so a test can use
+the matchers a setup file declares, such as those from
+`@testing-library/jest-dom/vitest`.
 
 ### Typed suites
 
@@ -1308,16 +1757,9 @@ production owner when a narrower owner exists.
 
 Concrete layouts:
 
-- `src/api/routes/__testkit__/auth-me.contract.testkit.ts`
-- `src/db/__testkit__/sessions-count-type.contract.testkit.ts`
 - `frontend/src/components/layout/__testkit__/navigation.ui.testkit.ts`
-- `src/internal/handler/repos/__testkit__/crud.contract.testkit.ts`
-
-`testkit` uses these suffixes automatically:
 
-- `*.contract.testkit.ts`
-- `*.data.testkit.ts`
-- `*.ui.testkit.ts`
+`testkit` uses the `*.ui.testkit.ts` suffix automatically.
 
 The suffix never chooses an engine. Each discovered typed file must also
 contain one root-package `defineFile(...)` declaration with a supported literal
@@ -1325,30 +1767,7 @@ engine.
 Unsupported pairs fail discovery; for example, a `*.ui.testkit.ts` file cannot
 declare `engine: "node-vitest"`.
 
-See [docs/test-types.md](docs/test-types.md) for the canonical type model.
-`*.contract.testkit.ts` files are Node-backed service/runtime contract suites.
-They use `contractScenario(...)` from
-`@gfdelarue/testkit/node-vitest/contract`, declare `engine: "node-vitest"`, and run
-through the `node-vitest-contract` profile for checks that need Node APIs but
-are not data-flow evidence suites. They are native Vitest suites:
-`contractScenario(...)` is the managed-context convenience, while direct public
-Vitest runner APIs remain valid for behavior such as `test.skip(...)` and
-`test.todo(...)`.
-
-`*.data.testkit.ts` files are Testkit data-flow/data-contract suites, not raw
-Vitest files with a Testkit suffix. They must use `dataScenario(...)` from
-`@gfdelarue/testkit/node-vitest/data`, declare `engine: "node-vitest"`, and record
-structured data-flow evidence through the data context. Supporting
-`count(...)`/`event(...)` calls are not enough by themselves; model actors,
-systems, records, transitions, external calls, payloads, budgets, cache/LLM/RPC
-usage, or reconciliation evidence. Data suites run through the
-`node-vitest-data` profile. Use a plain Vitest test file for plain Node
-assertions and HTTP or database integration, `contract` for typed service or
-protocol contracts, and `ui` when a browser is part of the assertion.
-Data suites use Vitest directly for assertions, hooks, and mocking.
-`dataScenario(...)` owns case registration: `testkit lint` reports native
-registration imports in data suites, and the data runner rejects any case that
-was not registered through the DSL.
+See [`docs/test-types.md`](https://app.unpkg.com/@gfdelarue/testkit/files/docs/test-types.md) for the canonical type model.
 
 Test groups own test files by directory. Declare them under `groups` in
 `testkit.config.ts`. Each group lists its repo-relative `roots` and the services
@@ -1378,18 +1797,19 @@ export default defineConfig({
   are also available by name; see
   [Named endpoints and databases](#named-endpoints-and-databases).
 - `skip`, `requirements`, and `runtimeIsolation` are group fields. See the
-  [config reference](testkit-config-schema.md#groups).
+  `groups` section of [`testkit-config-schema.md`](https://app.unpkg.com/@gfdelarue/testkit/files/testkit-config-schema.md).
 
-A config with `services` and no `groups` key uses legacy ownership. Each
-service owns the typed test files under its `local.cwd` and
-`discovery.roots`, as a group of the same name that uses that service. Testkit
-prints a notice on stderr when legacy ownership gives a file to a service.
-Legacy ownership will be removed; declare `groups` instead.
+Services own no test files. A config with `services` and no `groups` key
+fails to load when a service's `local.cwd` or `discovery.roots` holds a typed
+test file, which that service owned before 0.6.0. The error lists the `groups`
+entries that keep those files with their services. `status`, `destroy`,
+`cleanup`, and `db schema` still run on it. Otherwise every file belongs to
+`root`.
 
 Suite names are inferred from the colocated path:
 
-- `auth/__testkit__/*.contract.testkit.ts` => `auth`
-- `routes/__testkit__/auth-me.contract.testkit.ts` => `routes`
+- `auth/__testkit__/*.ui.testkit.ts` => `auth`
+- `routes/__testkit__/checkout.ui.testkit.ts` => `routes`
 
 Discovery is also a first-class CLI/API surface:
 
@@ -1446,11 +1866,16 @@ Testkit ignores an old `.testkit/history/` directory and leaves it in place.
 `@gfdelarue/testkit` provisions Docker-managed local Postgres automatically for
 services that define `database: database.postgres(...)`.
 
-Docker is also the required Postgres client runtime for Testkit-owned database
-operations. Testkit runs `psql` and `pg_dump` inside the configured Postgres
-client image instead of using host-installed binaries, which keeps local runs
-consistent across Linux, macOS, and native Windows. Override the client image
-with `TESTKIT_POSTGRES_CLIENT_IMAGE` when needed.
+Docker is also the required Postgres client runtime. Testkit doesn't use
+host-installed `psql` or `pg_dump`, which keeps local runs consistent across
+Linux, macOS, and native Windows. Testkit's own operations on the database it
+owns, such as declaring roles and taking schema snapshots, run inside the
+database container. So the `image` that `database.postgres()` uses must include
+`psql` and `pg_dump`, with a `pg_dump` at least as new as its server. Your SQL,
+in `sql-file` steps and `database-steps` helpers, runs `psql` in a separate
+client container from `postgres:16`. A `pg_dump` of an external database runs
+in `postgres:<its major version>`. `TESTKIT_POSTGRES_CLIENT_IMAGE` overrides
+the image of those client containers.
 
 Template steps, schema snapshots, and `database.steps` helpers work the same
 under Docker Desktop, rootless Docker, and Docker-in-Docker. Clients for
@@ -1476,7 +1901,7 @@ one with `database(name)` from `@gfdelarue/testkit/environment`. Declared `env`
 `{dbPort}`, `{dbName}`, `{dbUser}`, `{dbPassword}`, and `{dbSsl}` tokens, with
 `:serviceName` to read the database of a service listed in `dependsOn`. Testkit
 resolves them from the database provisioned for the current run. They are
-env-only; see [`env`](testkit-config-schema.md#env).
+env-only; see the `env` section of [`testkit-config-schema.md`](https://app.unpkg.com/@gfdelarue/testkit/files/testkit-config-schema.md).
 
 `db schema refresh` forces a source database dump into the `.testkit` source
 schema cache. `db schema verify` prepares local templates and verifies local