@gfdelarue/testkit 0.4.5 → 0.5.0

package/README.md

@@ -4,17 +4,19 @@
 
 # @gfdelarue/testkit
 
-`@gfdelarue/testkit` is the orchestrator and managed distribution for product test
-suites. It discovers `*.testkit.ts` files, infers suite ownership from the
-filesystem, starts local services, provisions Docker-managed local Postgres
-databases, schedules suites, and collects results and artifacts. Coding agents
-use it to write tests and hunt bugs, and CI uses it to run those tests. It needs
-no account or server.
+`@gfdelarue/testkit` is a test runner and CLI for coding agents and CI. It runs
+a repository's ordinary Vitest test files, such as `src/sum.test.ts`, as they
+are, and typed `*.testkit.ts` suites for Playwright and Node. It assigns
+tests to groups by directory, starts only the local services a group uses,
+provisions Docker-managed local Postgres databases when a group needs one,
+schedules the files, and collects results and artifacts. It starts no service
+for a test whose group uses none. Coding agents use Testkit to write tests
+and hunt bugs, and CI uses it to run those tests. It needs no account or
+server.
 
 Testkit exists to replace false confidence with inspectable execution evidence.
-It cannot prove that an entire application works. It can make narrower claims
-that deserve trust: these tests genuinely executed; these were the runtimes,
-fixtures, and inputs supplied to the run; this is what passed, failed, was
+It makes claims that deserve trust: these tests genuinely executed; these were
+the runtimes, fixtures, and inputs supplied to the run; this is what passed, failed, was
 skipped, or did not run; and this is the evidence behind the result. Testkit
 retains provenance, logs, and verifiable artifacts so those claims can be
 audited rather than accepted on the strength of a green check mark.
@@ -111,6 +113,23 @@ 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.
 
+`testkit bug record` saves the `--vitest-config`, `--vitest-project`, and
+`--vitest-runner` it was given in the draft, and asks for `--vitest-project`
+when two Vitest projects run the test's file. `testkit bug file` reruns with
+them, and the issue's reproduce command carries them. With
+`TESTKIT_REQUIRE_COMPLETE_SUITE=1`, it reruns every file the selection lists,
+then reads the recorded failure.
+
+`testkit bug file` takes the same [supplied values](#run-against-a-supplied-environment)
+as `testkit run` and reruns the test on them. The issue's reproduce command
+carries those flags, so `testkit bug file` refuses inputs that would put a raw
+secret in it. It takes `--env-from` and `--environment-file`, and takes
+`--base-url` and `--endpoint` only for URLs without credentials, a query, or a
+fragment. It refuses `--database` and `--env`; pass those values through
+`--env-from` or the environment file. The command runs from the repository
+root, so a relative `--environment-file` needs `testkit bug file` run from
+there too.
+
 ### Name the product's areas
 
 Add `areas` to `testkit.config.ts` so that each issue names the part of the
@@ -243,28 +262,28 @@ the report to the chosen platform.
 
 ## Execution engines
 
-Testkit has three explicit built-in engines rather than one implicit runtime:
-
-- `k6` runs `int`, `e2e`, `load`, and `dal` files with native k6
-  and xk6-sql semantics.
-- `node-vitest` runs purpose-built `data` and `contract` files with Node and
-  Vitest.
-- `playwright` runs `ui` files with Playwright and a managed Chromium.
-
-Every test file must export `defineFile({ engine: "..." })`. The filename
-suffix supplies the public test type; Testkit validates that explicit pair and
-derives a runner profile. It never infers a default engine or falls back to a
-different engine.
-
-Consumers declare only `@gfdelarue/testkit`. The root package owns the three
-adapters and exact JavaScript tools it executes. The k6 engine ships as
-separately versioned npm packages built from
-[gfdelarue/testkit-k6](https://github.com/gfdelarue/testkit-k6); npm installs
-the compatible k6 target package and its shared source package through the
-root's optional dependency graph, and Testkit resolves that direct executable
-without consulting `PATH`. Node/Vitest and Playwright resolve their managed public packages from the
-installed Testkit root, so product-local tool copies do not select Testkit's
-runtime.
+Testkit has two built-in engines:
+
+- `node-vitest` runs plain Vitest test files and purpose-built `data` and
+  `contract` 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
+wrapper. It keeps its native `vitest` imports and its repository paths, has no
+test type, and runs under the engine's general `node-vitest` profile. Testkit
+does not evaluate `testkit.config.ts` in the test's process, and it installs the
+values of the services the test's group uses before the test's imports
+evaluate. See [Plain Vitest test files](#plain-vitest-test-files) for which
+files Testkit runs.
+
+Every typed `*.testkit.ts` file must export `defineFile({ engine: "..." })`. The
+filename suffix supplies the public test type; Testkit validates that explicit
+pair and derives a runner profile. It never infers a default engine for a typed
+file or falls back to a different engine.
+
+Consumers declare only `@gfdelarue/testkit`, which installs the exact versions
+of the tools its engines run. A product's own copies of Vitest, Playwright, or
+their tools don't change what Testkit runs.
 
 Playwright browser installation is explicit:
 
@@ -273,26 +292,16 @@ npx @gfdelarue/testkit setup playwright
 npx @gfdelarue/testkit setup playwright --with-deps # CI and fresh hosts
 ```
 
-Setup and execution share one canonical Playwright registry. Normal runs never
-install or download a browser. See [Engine Architecture](docs/engine-architecture.md)
-for the authoring, installation, trust, and failure contracts.
-
-Managed commands use the same Execa-backed adapter on hosted Linux and Windows
-runners. Testkit passes exact argv, cwd, and environment values, bounds captured
-output, applies cancellation and timeouts, and asks the platform adapter to
-terminate descendants. Persisted recovery identities remain birth-fenced so a
-later cleanup does not signal a reused process ID.
-
-The five k6 target packages share one exact-version source package that carries
-the AGPL corresponding source archive and licenses. Runtime evidence records
-the package name and version and the k6 version observed by executing the
-installed binary. The
-[testkit-k6 README](https://github.com/gfdelarue/testkit-k6#readme) documents
-the reproducible build, the expected executable digests, and the license
-notes.
-
-Managed task environment is engine input rather than ambient host state. k6
-suites read it through native `__ENV`; Node/Vitest data and contract callbacks
+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`.
+
+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
 expose each value as an immutable, non-enumerable `process.env.KEY` property so
@@ -304,21 +313,21 @@ reserves `APPDATA`, `ComSpec`, `HOME`, `LANG`, `LC_ALL`, `LOCALAPPDATA`, `PATH`,
 `PATHEXT`, `SystemRoot`, `TEMP`, `TMP`, `TMPDIR`, `USERPROFILE`,
 `XDG_CACHE_HOME`, `XDG_CONFIG_HOME`, and `XDG_DATA_HOME`. In addition:
 
-- k6 reserves the `K6_` and `TESTKIT_` prefixes plus `BASE_URL` and `GODEBUG`;
-- Node/Vitest reserves the `TESTKIT_` and `VITEST_` prefixes plus `BASE_URL`,
-  `FORCE_COLOR`, `NODE_OPTIONS`, `NO_COLOR`, and `UPDATE_SNAPSHOT`;
+- 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);
+  other `TESTKIT_` and `VITEST_` keys, such as
+  `TESTKIT_REQUIRE_COMPLETE_SUITE`, pass through;
 - Playwright reserves the `TESTKIT_`, `PLAYWRIGHT_`, `PWTEST_`, and `PW_TEST_`
   prefixes plus `BASE_URL`, `FORCE_COLOR`, `NODE_OPTIONS`, and `NO_COLOR`.
 
 Case-variant duplicates and invalid names or NUL-containing values fail instead
-of being normalized. k6 accepts at most 128 consumer entries and 16,384
-environment-block character units. Node/Vitest accepts at most 512 entries and
+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. The smaller k6 limit is required because native k6
-receives consumer values in its physical process environment; Node/Vitest and
-Playwright transport them through owned runtime-input files. See
-[Engine Architecture](docs/engine-architecture.md#managed-environment) for the
-complete transport and aggregate-input limits.
+of UTF-8 key/value data. [Environment](docs/engines.md#environment) lists the
+complete limits, and [Named endpoints and databases](#named-endpoints-and-databases)
+covers the environment API.
 
 ## Usage
 
@@ -335,10 +344,9 @@ npx @gfdelarue/testkit discover --json > .testkit/discovery.json
 npx @gfdelarue/testkit discover --output .testkit/discovery.json
 
 # Filter by type
-npx @gfdelarue/testkit --type int
-npx @gfdelarue/testkit --type dal
-npx @gfdelarue/testkit --type e2e
-npx @gfdelarue/testkit --type int,e2e,dal
+npx @gfdelarue/testkit --type contract
+npx @gfdelarue/testkit --type data
+npx @gfdelarue/testkit --type contract,data
 npx @gfdelarue/testkit --type ui
 
 # Parallel file execution
@@ -347,16 +355,17 @@ npx @gfdelarue/testkit --task-concurrency 8
 # One file-level wall clock budget for every suite file
 npx @gfdelarue/testkit --file-timeout-seconds 60
 
-# Specific service / suite
-npx @gfdelarue/testkit --service frontend --type ui -s navigation
-npx @gfdelarue/testkit --service api --type int -s health
-npx @gfdelarue/testkit --type int,e2e,dal -s dal:queries
+# 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
 
 # Exact file
-npx @gfdelarue/testkit --type int --file __testkit__/health.int.testkit.ts
+npx @gfdelarue/testkit --type contract --file __testkit__/health.contract.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.int.testkit.ts
+npx @gfdelarue/testkit --ignore-skip-rules --file __testkit__/billing.contract.testkit.ts
 
 # Lifecycle
 npx @gfdelarue/testkit status
@@ -371,6 +380,16 @@ 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`.
+
+`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.
+
 Database cleanup is scoped to the selected product. `cleanup --resources --global`
 is retired; use `--dir <product> cleanup --resources` for each product. After
 deleting a product directory, remove its orphaned containers and volumes
@@ -386,15 +405,125 @@ Batch `run` output stays intentionally short: one line per completed file,
 concise failure blocks, and a final summary. Service logs, captured runtime
 output, and emitted artifacts are persisted under `.testkit/results/`.
 
+Text output is coloured in a terminal and plain otherwise. As in Node,
+`NO_COLOR` turns colour off and `FORCE_COLOR` overrides it: `0` or `false`
+turns colour off and any other value turns it on.
+
 Testkit seals an immutable local run bundle. `testkit run` prints
 `Run ID: <id>` after sealing in text output and returns `runId` in `--json`
 output, for passed and failed runs.
 
-Test execution also maintains a scheduler cache at `.testkit/timings.json`.
-Completed file-level task durations are used to rank future runs with a
-longest-estimated-duration-first policy, so slow files start earlier when
-workers are available. Run artifacts include compact scheduler metadata under
-`planning` so ordering decisions are inspectable.
+Testkit starts the files that took longest in earlier runs first, so slow
+files start while workers are free. The run document records the order under
+`planning`.
+
+### Run against a supplied environment
+
+`testkit run` can take the values its tests need instead of provisioning them.
+Every selected group then runs on those values alone. Testkit starts none of
+the group's services, creates no database, and runs no `.setup.*` module beside
+a test. It also ignores the env values and env files those services declare, so
+supply every value the tests read. Groups, selection, skip rules, and other
+policy work as before.
+
+```bash
+npx @gfdelarue/testkit run --group checks \
+  --base-url http://127.0.0.1:3000 \
+  --endpoint api=http://127.0.0.1:3001 \
+  --database store=postgres://app:password@127.0.0.1:5432/store \
+  --env FEATURE_FLAG=on \
+  --env-from API_TOKEN=CI_API_TOKEN
+
+npx @gfdelarue/testkit run --environment-file supplied.json
+```
+
+- `--base-url URL` supplies the default endpoint, which tests receive as
+  `BASE_URL`.
+- `--endpoint NAME=URL` supplies a named endpoint, usually named after the
+  service it stands in for.
+- `--database NAME=URL` supplies a named PostgreSQL database.
+- `--env NAME=VALUE` supplies an environment value.
+- `--env-from NAME=HOST_KEY` supplies the value of host variable `HOST_KEY`
+  under `NAME`.
+- `--environment-file PATH` reads values, prepared setup data, and handle
+  descriptors from a file.
+
+Every flag except `--base-url` and `--environment-file` can be repeated. Tests
+read named values with `endpoint(name)` and `database(name)` from
+`@gfdelarue/testkit/environment`. An `--env`, `--env-from`, or file `env` entry
+named `BASE_URL` or `DATABASE_URL` sets the default endpoint or database, and an
+empty database URL means no database. Without an explicit default, a group's
+`BASE_URL` and `DATABASE_URL` are those of the first service in its `uses` that
+has a supplied endpoint or database. Either way the default is also available
+by the group's name, as in a configured run, so it may not differ from a named
+endpoint or database with that name.
+
+Testkit reads host variables only through `--env-from`. A `BASE_URL` or
+`DATABASE_URL` already set in the shell does not switch a run to supplied
+values. Two inputs may define the same value only if they agree. Any other
+repeat, such as `--base-url` and `--env BASE_URL` with different URLs, or a
+missing `--env-from` host variable, fails the run before it starts. Before a
+test starts, each supplied endpoint must give a valid HTTP response. A 4xx or
+5xx response counts as valid.
+
+Each supplied database must also accept a connection before a test starts.
+Testkit connects, signs in with the URL's credentials, runs `SELECT 1`, and
+disconnects. It handles trust, password, md5, and SCRAM-SHA-256 authentication.
+TLS follows the URL's `sslmode` as in libpq. The default, `prefer`, tries TLS
+first and then a plain connection, and `allow` tries them the other way round.
+`verify-ca` and `verify-full` need `sslrootcert`, set to a CA file or to
+`system`, and `sslrootcert=system` alone means `verify-full`. `host=/path`
+connects through the Unix socket in that directory and ignores `sslmode`. The
+check reads only the URL. It ignores `PG*` variables, `~/.pgpass`, and
+`~/.postgresql/root.crt`, and it presents no client certificate. A database
+that is unreachable, fails TLS, rejects the credentials, does not exist, or is
+not PostgreSQL fails the run before any test starts. The message names the
+database, never its URL.
+
+The environment file is JSON:
+
+```json
+{
+  "version": 1,
+  "baseUrl": "http://127.0.0.1:3000",
+  "databaseUrl": "postgres://app:password@127.0.0.1:5432/app",
+  "endpoints": { "api": "http://127.0.0.1:3001" },
+  "databases": { "store": "postgres://app:password@127.0.0.1:5432/store" },
+  "env": { "FEATURE_FLAG": "on" },
+  "ui": {},
+  "setupData": { "actor": "Grace" },
+  "handles": {
+    "webhook": {
+      "kind": "http-capture",
+      "url": "http://127.0.0.1:41000/webhook",
+      "requestsUrl": "http://127.0.0.1:41000/__testkit__/<capability>/requests",
+      "resetUrl": "http://127.0.0.1:41000/__testkit__/<capability>/requests"
+    }
+  }
+}
+```
+
+Only `version` is required, and this Testkit reads version 1. `baseUrl`,
+`databaseUrl`, and `ui` may be `null`, as an environment rendered by Testkit
+writes them, and `null` there counts as absent. Tests receive
+`setupData` as the data a setup module would have returned: `{}` when the file
+leaves it out, and `null` when the file sets it to `null`. `handles` entries must each name a `kind`, and tests reach them with
+[`handle(name)`](#handles). An `http-capture` entry holds the `url`,
+`requestsUrl`, and `resetUrl` that a capture sidecar reports, and gives the
+test the same handle a setup module's capture would. Other kinds are handed on,
+and `handle()` throws `EnvironmentHandleError` with `"unsupported"` for them. Any other field, such as
+service or database configuration, is rejected. Errors name the file and the
+field and do not repeat the file's contents.
+
+A run records the values its tests received in this shape. Each acquisition in
+`run.json`'s `environment` section has them under `values`, with secrets and
+capture capabilities redacted. Its `setupData` is the supplied setup data or
+what the file's setup module returned, and `{}` without either. Sealing redacts
+setup data under a key that names a secret or that `redact` lists, and records
+the rest as returned, so list any other sensitive key in `redact`. With
+`"version": 1` added, an
+acquisition's `values` are an environment file that gives a second run the
+same values, unless redaction changed one of them.
 
 ## Tooling Adapters
 
@@ -430,23 +559,17 @@ export default defineConfig({
 // playwright.config.ts
 import { defineTestkitConfig, devices } from "@gfdelarue/testkit/playwright";
 
-export default defineTestkitConfig(
-  {
-    testDir: "./__testkit__",
-    projects: [{ name: "chromium", use: { ...devices["Desktop Chrome"] } }],
-  },
-  {
-    dotenvFiles: [".env.local"],
-  },
-);
+export default defineTestkitConfig({
+  testDir: "./__testkit__",
+  projects: [{ name: "chromium", use: { ...devices["Desktop Chrome"] } }],
+});
 ```
 
 Managed UI suites use `@gfdelarue/testkit/playwright` for Testkit's Playwright
 helpers and re-exported authoring API. They may also import exact public exports
 from the managed `@playwright/test`, `playwright`, and `playwright-core`
-packages. Testkit pins both runtime resolution and type resolution, so
-product-local Playwright installs cannot split the test registry or supply a
-different compile-time API.
+packages. Those imports resolve to Testkit's pinned versions at run time and
+when typechecking, whatever Playwright version the product installs.
 
 For scripts and app-runtime code, `@gfdelarue/testkit/env` provides shared helpers
 for managed runtime detection, dotenv loading, and local-database safety:
@@ -541,26 +664,33 @@ and attempts under `environment.services`. A config that sets `local.port`, the
 `port` option of `app.node` or `app.next`, or a literal port in `local.baseUrl`
 or `local.readyUrl` fails to load; delete it and use `{port}`.
 
-Every test file declares its execution engine and any file-local scheduling
-metadata next to the test:
+Every typed test file declares its execution engine and any file-local
+scheduling metadata next to the test. A plain Vitest test file declares
+neither:
 
 ```ts
 import { defineFile } from "@gfdelarue/testkit";
 
 export const testkit = defineFile({
-  engine: "k6",
+  engine: "node-vitest",
   skip: "Billing is currently unavailable locally",
-  locks: ["global-worker-loop"],
 });
 ```
 
-The engine value is a required literal. The supported public authoring paths
-are `@gfdelarue/testkit/k6`, `@gfdelarue/testkit/node-vitest/data`,
+A file can also name `locks`.
+[Give each test its own data](#give-each-test-its-own-data) says when to use
+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.
+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`.
 
 `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`
@@ -584,10 +714,9 @@ for:
 - repo-declared suite/file skip policies with explicit reasons
 
 `runtime.prepare` is the generic build-once hook for shared runtimes. It runs
-once per runtime generation before local services start, fingerprints declared
-inputs, and writes cache state under the service runtime directory. This is the
-right way to move expensive browser targets from `next dev` / watch mode to
-stable build-and-start flows.
+once per runtime generation before local services start, and runs again when
+its declared inputs change. This is the right way to move expensive browser
+targets from `next dev` / watch mode to stable build-and-start flows.
 
 Setup steps (`runtime.prepare`, database `template`, and other Testkit-run
 Node commands) inherit `NODE_OPTIONS`. `TESTKIT_SETUP_NODE_OPTIONS` appends
@@ -599,18 +728,12 @@ 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
-product. Both commands filter Docker inventory by the product ownership label
-and preserve other products, including idle caches. Host-local Postgres data
-lives in a Testkit-labelled named Docker
-volume instead of an image-declared anonymous volume, so cleanup can account for
-and remove it safely. Each created volume receives a never-reused random
-generation in both its name and labels; cleanup re-inspects the complete
-generation immediately before Docker's name-based removal. Docker has no
-immutable volume ID or conditional-delete API, so direct Docker-daemon
-principals are part of the host trust boundary and must not replace that
-unguessable name during the final removal call. Testkit serializes database
-mutations for the same product; independent products can proceed concurrently.
-Use `cleanup --resources --dry-run` to preview the selected product's cleanup.
+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
+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.
 
 `database.template` is the database-side equivalent for reusable template DB
 state. When `database.sourceSchema` is configured, Testkit treats the configured
@@ -622,34 +745,16 @@ schema still matches the source dump. If local replay differs, Testkit refreshes
 from the source once for the current cache key and retries. If it still differs,
 the run fails with schema diagnostics under `.testkit/results/schema`.
 
-Source schema cache keys are derived automatically from repo state:
-
-- clean git worktrees use `commits/<sha>`
-- dirty git worktrees use `dirty/<sha>-<fingerprint>`
-- non-git directories use `nogit/<fingerprint>`
-
-Dirty worktree fingerprints compare the complete index to `HEAD`, then compare
-the physical worktree bytes, node types, and executable modes to the index.
-This intentionally detects changes hidden by Git stat flags, sparse checkout,
-or clean/smudge and EOL normalization. For untracked files, repository
-`.gitignore` files are respected; host-global excludes, `core.excludesFile`, and
-`.git/info/exclude` do not alter Testkit's cache identity.
-
-Fingerprint Git commands disable replacement objects and optional locks and do
-not read system or user Git configuration. Git path records are decoded from
-their byte-preserving quoted form and must be valid UTF-8. Uninitialized
-gitlinks and special filesystem nodes fail explicitly instead of being assigned
-an incomplete or ambiguous identity. Testkit reads the complete HEAD, index,
-untracked, submodule, and physical snapshot twice and fails if the observations
-differ.
-
-Physical reads open regular files by descriptor and verify every pathname
-component before and after use; on POSIX, ancestor directory descriptors remain
-open during the read. Node does not expose a portable `openat`/Windows reparse-
-handle traversal API, so this detects ordinary replacement races but is not a
-security boundary against a same-user adversary able to perform a perfectly
-timed replace-and-restore ABA attack. Run Testkit against source trees that are
-not concurrently controlled by an untrusted local process.
+Testkit keys the source schema cache on the repository's state. A clean
+worktree shares the entry for its commit. A dirty worktree or a directory
+outside Git gets its own entry, keyed on the content of its files.
+
+The key changes when a file's bytes, type, or executable mode changes, including
+changes Git's own status can hide, such as sparse checkout or line-ending
+normalization, and when a submodule moves. Untracked files are included unless
+the repository's `.gitignore` files exclude them; global or per-clone Git
+excludes don't count. A path Testkit can't read, or a tree that changes while
+Testkit reads it, fails the run instead of producing a key.
 
 Testkit-owned outputs are always excluded from fingerprints: `.testkit/`,
 and `.next-testkit/`. `testkit.config.ts` is normal repo
@@ -674,22 +779,16 @@ Template setup executes in three explicit phases:
 
 Schema drift is checked after each successful `migrate` and `seed` step, and
 `verify` only runs once local replay matches the source schema. Source refreshes
-use Dockerized `pg_dump --schema-only --no-owner --no-privileges`, so
-seed/reference data is never written into the baseline and host `pg_dump`
-installations are not used. Keep schema-changing setup in its own step where
-possible; a single command that changes schema and then fails before exiting
-cannot be refreshed at the midpoint.
-
-Source schema refreshes are intentionally single-connection and pooler-safe.
-If a Neon pooled source URL is configured, Testkit rewrites it to the matching
-direct Neon endpoint before running Dockerized `pg_dump` and records the
-original/resolved host classifications beside the resolved cache entry. Unknown
-PgBouncer/pooler URLs fail closed; configure a direct source URL for those
-providers. Concurrent refreshes for the same service and cache key are
-serialized with a cache-local lock so multiple Testkit processes do not
-stampede the source database. Testkit also maintains
-`.testkit/db/<service>/source-schemas/index.json` and prunes old inactive cache
-entries automatically.
+dump the schema only, in Docker, so seed and reference data never enter the
+baseline and no host `pg_dump` is needed. Keep schema-changing setup in its own
+step where possible; a single command that changes schema and then fails before
+exiting cannot be refreshed at the midpoint.
+
+A source schema refresh uses one connection. A Neon pooled source URL is
+rewritten to the matching direct Neon endpoint. Other PgBouncer or pooler URLs
+fail; configure a direct source URL for those providers. Refreshes of the same
+cache entry run one at a time, even from separate Testkit processes, and
+Testkit prunes old inactive cache entries automatically.
 
 For most repos, prefer declarative step objects directly inside
 `database.postgres({ template: ... })` and `runtime.prepare.steps`.
@@ -699,10 +798,9 @@ The supported shapes are:
 - `{ kind: "sql-file", path: "..." }`
 - `{ kind: "module", target: "file.ts#exportName" }`
 
-Local files and ordinary external packages remain valid module targets.
-Testkit-owned `@gfdelarue/testkit` targets are validated against Testkit's exact
-configured-step module registry while config is loaded, so a misspelled or
-private Testkit subpath fails before preparation or database setup starts.
+Local files and ordinary external packages remain valid module targets. An
+unsupported or private `@gfdelarue/testkit` target fails when the config loads,
+before preparation or database setup starts.
 
 `runtime.toolchain` is the first-class way to make those prepare/start commands
 run under the correct Node toolchain instead of whatever `node`/`npm` happened
@@ -720,16 +818,12 @@ to launch `testkit`. Node toolchains support:
   - `package.json#packageManager`
   - `package.json#engines.npm`
 
-Downloaded toolchains resolve only through Testkit's target-specific trusted
-Node release manifest. The archive URL, compressed size, SHA-256, archive
-shape, unpacked size, and complete installed-tree digest are fixed before any
-download. An unlisted version or platform fails closed. The verified cache is
-kept under `.testkit/_toolchains/node`; external cache redirects, linked cache
-ancestors, modified installed content, and escaping executable links are
-rejected. `runtime.toolchain.cwd` is always a normalized product-relative path
-and cannot contain a parent-directory segment. The trusted official Linux Node
-archives are glibc builds; `install: "download"` fails before fetch or cache
-mutation on musl instead of pretending those binaries are compatible.
+`install: "download"` supports the Node versions and platforms Testkit lists,
+and fails before downloading for any other. Downloads are cached under
+`.testkit/_toolchains/node`, and a modified cache entry fails instead of
+running. `runtime.toolchain.cwd` is a product-relative path and cannot contain
+a parent-directory segment. The official Linux Node archives are glibc builds,
+so `install: "download"` fails on musl before it downloads anything.
 
 Example:
 
@@ -758,6 +852,77 @@ artifact/log/setup files. Payloads are SHA-256 addressed under
 removing their logical per-run paths. `.testkit/results/latest.json` remains a
 convenience projection; it is not the historical authority.
 
+`run.json` is schema 20. `groups` holds each group's suites and files.
+`environment` is the run's environment record. For each acquisition, it holds:
+
+- the source that prepared it: `configured`, `static`, `supplied`, or `none`;
+- the tasks it served and the services it started;
+- each file's setup;
+- how it was released;
+- the values its tests received.
+
+It also holds each service's start attempts, the service and setup logs, the
+run's capacity and database backend, and the values tests asked for that the
+environment lacked. Runs that Testkit 0.4.x stored as schema 19 stay readable
+through `testkit artifacts`, `ci report`, known-failure checks, and the
+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:
+
+- 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.
+- 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.
+- 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.
+- The unguessable segment in each [HTTP capture's](#handles) operation URLs,
+  from a setup module's capture or an `--environment-file` handle.
+
+Name a secret's key in `redact` when it holds none of the words above:
+
+```ts
+export default defineConfig({
+  redact: ["STRIPE_SK", "PGPASS"],
+});
+```
+
+Testkit matches the names in any letter case, in a configured run and a
+supplied run alike. `redact` adds keys whose values sealing redacts; the forms
+in the first item still use the words above.
+
+A value shorter than eight characters is not redacted on its own. Sealing also
+redacts a value's JSON-escaped forms, each line of a value that spans lines,
+and keys in the free-form data and metadata that tests attach. When output cuts a secret short and marks
+the cut with `…` or `...`, sealing redacts the part that shows. `testkit run
+--json` and the run's progress output apply the same redaction.
+
+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.
+- 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
+  `redact` list, so it redacts only the first item and its own environment's
+  values under the words above. The bundle's `archive.redaction.status` is then
+  `source-targets-unavailable` instead of `applied`.
+
 Use the artifact archive config to opt into pruning or atomic publication to
 an external directory. Local retention is indefinite by default:
 
@@ -801,254 +966,320 @@ Programmatic consumers can import `listRunBundles`, `loadRunBundleArtifact`,
 
 ## Authoring
 
-### Node setup beside a test
+### Named endpoints and databases
 
-A test such as `tests/webhook.int.testkit.ts` can have a sibling
-`tests/webhook.int.testkit.setup.mjs`. Testkit runs its named `setup` export,
-or its default export, before starting the test engine:
+`@gfdelarue/testkit/environment` gives a test the URL and database of each
+service its group uses, by the service's name:
+
+```ts
+import { database, endpoint } from "@gfdelarue/testkit/environment";
+
+const response = await fetch(new URL("/health", endpoint("api")));
+const reportsDatabase = database("reports");
+```
+
+Both functions return strings. A service's database is the one Testkit
+provisions for it, or the `DATABASE_URL` its `env` declares. The module works
+in Vitest and Playwright files and in the modules they import.
+Testkit installs the values before any of that code loads, so module-level code
+and native hooks can read them, such as a Playwright config and its
+`globalSetup` or a Vitest `beforeAll`.
+
+A name with no value throws `EnvironmentValueMissingError`, with `kind`,
+`valueName`, and the `available` names. `valueName` is `null` when the missing
+value is the run's default URL. Outside a Testkit run every call throws it.
+
+A test that fails on this error, or a file whose imports throw it, ends as an
+infrastructure failure in Vitest and Playwright. The run fails, and
+`testkit bug file` refuses to file it. A test that catches the error and
+carries on is unaffected. When the run gives a test no base URL, a Playwright
+`page.goto()` to a relative URL ends the same way.
+
+`BASE_URL` and `DATABASE_URL` hold the values of the first service
+in `uses` that has each one. Playwright gives `BASE_URL` and `baseURL` in
+canonical form, so an origin ends with `/`. `endpoint()` returns the URL
+unchanged in every engine.
+
+The group's default endpoint and database are also available by the group's
+name, whether the run starts its services or takes supplied values. For a group
+`checks` that uses `api`, `endpoint("checks")` and `endpoint("api")` return the
+same URL. A group whose default differs from a used service's value with the
+group's name, such as a group `api` with `uses: ["web", "api"]`, gets no
+values: its files end as an infrastructure failure that names the group, and
+other groups still run.
+
+### Handles
+
+`handle(name)` from `@gfdelarue/testkit/environment` gives a test an object for
+something its environment prepared. Today that is an HTTP capture, which a
+[setup module](#node-setup-beside-a-test) starts with `sidecars.httpCapture()`.
+The handle is named after the capture's `id`:
 
 ```js
-// tests/webhook.int.testkit.setup.mjs
+// tests/webhook.contract.testkit.setup.mjs
 export async function setup({ sidecars }) {
-  const capture = await sidecars.httpCapture({ path: "/webhook" });
-  return {
-    data: { webhookUrl: capture.url, requestsUrl: capture.requestsUrl },
-  };
+  await sidecars.httpCapture({ id: "webhook", path: "/webhook" });
 }
 ```
 
-Setup runs in a Node worker thread with its own JavaScript state. It can use
-Node APIs, prepare external resources, and start HTTP capture listeners.
-The context contains `deadlineMs`, `signal`, `env`, `leaseDir`, `productDir`,
-`serviceName`, `testFile`, and `sidecars`. The worker shares the host process's
-permissions. It is not a sandbox for untrusted code.
-
-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
-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]`, without invoking property getters.
-
-Setup shares the task's absolute deadline. On failure or cancellation, Testkit
-runs registered cleanup and closes its sidecars. Once setup succeeds, those
-resources remain available until task cleanup. Cleanup callbacks run in reverse
-registration order. The runner uses the task timeout for cleanup, capped at
-60 seconds. A hung worker is terminated so it cannot keep its listeners open.
-
-Thrown setup errors, deadline expiry, and invalid data fail the task with the
-setup module path. Consumer cleanup errors fail the task; Testkit cleanup or
-worker failures count as infrastructure failures. Cleanup remains idempotent.
-HTTP capture retains at most 100 requests by default, configurable up to 1,000.
-Each body defaults to 1 MiB, configurable up to 8 MiB, and retained bodies total
-at most 8 MiB per listener. A setup can create up to 16 listeners, each with at
-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.int.testkit.mjs`.
-
-### HTTP suites
-
 ```ts
-import { defineFile } from "@gfdelarue/testkit";
-import { defineHttpSuite, expect } from "@gfdelarue/testkit/k6";
-
-export const testkit = defineFile({ engine: "k6" });
-
-const suite = defineHttpSuite(({ rawReq }) => {
-  const response = rawReq.get("/health");
-  expect.status(response, 200, "health returns 200");
-});
+// tests/webhook.contract.testkit.ts
+import { handle } from "@gfdelarue/testkit/environment";
 
-export const options = suite.options;
-export const setup = suite.setup;
-export default suite.exec;
+const webhook = handle("webhook");
+await placeOrder({ callbackUrl: webhook.url });
+const [delivery] = await webhook.requests();
+await webhook.reset();
 ```
 
-Testkit helper suites are authored as native-shaped k6 modules: re-export the
-helper's `options` and `setup`, and default-export its `exec` function. Testkit
-does not inspect source text or invent k6 lifecycle exports.
-
-Suite-owned authentication lives in the k6 module. `auth.setup` receives the
-resolved env and a raw HTTP client, returns a session bundle of named actors,
-and `auth.headers` turns the bundle plus the requested actor into headers:
+A capture handle has `kind` (`"http-capture"`), `url` (where the product sends
+its requests), `requests()`, which returns the captured requests oldest first,
+and `reset()`, which forgets them. Both methods return a Promise in
+Vitest and Playwright. Each call fails after 10 seconds if the capture hasn't
+answered in full.
+
+A handle is a reference, not a connection. It can list or reset its own capture
+and nothing else. The capture's operation URLs hold an unguessable segment, so
+holding the handle is the authority. Testkit keeps that segment out of the
+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.
+
+- A name with no handle throws `EnvironmentValueMissingError` with `kind`
+  `"handle"`, and the test ends as an infrastructure failure, as for a missing
+  endpoint.
+- Every capture created without an `id` gets the id `http-capture`. If two do,
+  `handle("http-capture")` throws `EnvironmentHandleAmbiguousError` with the
+  `count`. Give each capture a distinct `id`.
+- A call that the capture refuses, such as one from a stale or forged
+  reference, throws `EnvironmentHandleError` with `reason` `"refused"`. A call
+  whose capture no longer answers throws it with `"unavailable"`, and a
+  descriptor this Testkit cannot use throws it with `"invalid"` or
+  `"unsupported"`. These end the test as ordinary failures.
+
+### Give each test its own data
+
+Testkit runs test files at the same time. Files on one runtime share its
+services and its database. Write each test so that it passes beside any other
+test, in any order.
+
+- Create the rows the test needs, and filter every query and update to them.
+  Don't depend on rows that another test creates, and don't count, update, or
+  delete across a whole table. Every test sees the rows from `template.seed`,
+  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).
+- 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
+  can't collide with the next run.
 
 ```ts
+import { randomUUID } from "node:crypto";
 import { defineFile } from "@gfdelarue/testkit";
-import { defineHttpSuite } from "@gfdelarue/testkit/k6";
-
-import { organizationHeaders, sessionAuth } from "../helpers/session.js";
-
-export const testkit = defineFile({ engine: "k6" });
+import { contractScenario } from "@gfdelarue/testkit/node-vitest/contract";
+import { expect, onTestFinished } from "vitest";
 
-const suite = defineHttpSuite(
-  {
-    auth: sessionAuth(["reviewer", "outsider"]),
-    rawHeaders: organizationHeaders,
-  },
-  ({ actor, actors, req }) => {
-    req.get("/api/auth/session");
-    req("GET", "/api/auth/session");
-    actor?.req.get("/api/auth/session");
-    req.as("outsider").get("/api/auth/session");
-    actors.get("reviewer").rawReq.get("/api/auth/session");
-  },
-);
+import { sandbox } from "../payments-sandbox.js";
 
-export const options = suite.options;
-export const setup = suite.setup;
-export default suite.exec;
-```
+export const testkit = defineFile({ engine: "node-vitest" });
 
-```ts
-// __testkit__/helpers/session.ts
-import type { AuthAdapter, AuthSessionBundle } from "@gfdelarue/testkit/k6";
+contractScenario("a refund reaches the sandbox customer", async ({ http }) => {
+  const customer = await sandbox.createCustomer({ email: `refund-${randomUUID()}@example.test` });
+  onTestFinished(() => sandbox.deleteCustomer(customer.id));
 
-export function sessionAuth(actorNames: string[]): AuthAdapter<AuthSessionBundle> {
-  return {
-    setup({ env, http }) {
-      const actors = Object.fromEntries(
-        actorNames.map((actorName, actorIndex) => [
-          actorName,
-          { actorIndex, actorName, session: login(http, env.BASE, actorName) },
-        ]),
-      );
-      return { actors, primaryActor: actorNames[0] };
-    },
-    headers(bundle, { actor }) {
-      const session = bundle?.actors[actor ?? bundle.primaryActor ?? ""]?.session;
-      return session ? { Authorization: `Bearer ${session.jwt}` } : {};
-    },
-  };
-}
+  const response = await http().post("/api/refunds", { customerId: customer.id, amountCents: 500 });
+  expect(response.status).toBe(201);
+});
 ```
 
-Named HTTP profiles in `testkit.config.ts` stay JSON-only for k6 suites, because
-the orchestrator serializes them across the Node/k6 boundary. Node/Vitest data
-profiles are loaded in-process and may define `auth` and header functions
-directly. See the [config reference](testkit-config-schema.md#profileshttp).
+A [Node setup module](#node-setup-beside-a-test) returns its cleanup with its
+data. Testkit runs only the cleanup that `setup` returns. If a step in `setup`
+can throw after `setup` creates something, undo the creation before rethrowing.
 
-DAL suites:
+A test that has to count or change a whole table needs a database that other
+tests don't write to. Give the test a group of its own, and have the group use
+a service with its own database. Below, the `ledger` group owns the test files
+under `src/ledger`, and its tests get the database of `ledger-db`, built from
+the same schema:
 
 ```ts
-import { defineFile } from "@gfdelarue/testkit";
-import { defineDalFixtures, defineDalSuite } from "@gfdelarue/testkit/k6";
-
-export const testkit = defineFile({ engine: "k6" });
-
-const fixtures = defineDalFixtures(({ db, fixtureScope }) => ({
-  widget() {
-    return fixtureScope.seed("widget", "primary", { name: "Primary Widget" }, () => {
-      const widgetId = fixtureScope.id("widget");
-      db.exec(`
-        INSERT INTO widgets (id, name)
-        VALUES ('${widgetId}', 'Primary Widget')
-      `);
-      return { widgetId };
-    });
-  },
-}));
-
-const suite = defineDalSuite({ fixtures }, ({ db, fixtureScope, fixtures }) => {
-  const widget = fixtures.widget();
-  db.query(`select id from widgets where id = '${widget.widgetId}'`);
-  fixtureScope.records();
-});
-
-export const options = suite.options;
-export const setup = suite.setup;
-export default suite.exec;
+services: {
+  api: app.node({
+    // ...
+  }),
+  "ledger-db": database.fixture({
+    template: { migrate: [{ kind: "sql-file", path: "db/schema.sql" }] },
+  }),
+},
+groups: {
+  api: { roots: ["src"], uses: ["api"] },
+  ledger: { roots: ["src/ledger"], uses: ["ledger-db"] },
+},
 ```
 
-DAL files run at the same time as other tests, including other DAL files of the
-same service. If two files share rows that one of them changes, give both the
-same lock, for example `defineFile({ engine: "k6", locks: ["widgets"] })`, and
-Testkit runs them one at a time. Runtime services reserve a configurable
-Postgres connection budget for each active runtime slot. Use `database.postgres({ runtimeConnections })` for the
-service pool size and `database.postgres({ maxConnections,
-reservedConnections })` for the backing Postgres capacity.
+`locks` is an escape hatch for a resource that can't be duplicated, such as a
+payment provider's sandbox account with one webhook URL that some tests change.
+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.
 
-`defineDalFixtures(...)` is the package-owned DAL seeding model. It gives every
-suite a deterministic `fixtureScope` with:
+```ts
+export const testkit = defineFile({ engine: "node-vitest", locks: ["payments-sandbox-webhook"] });
+```
 
-- `fixtureScope.id(label)` / `uuid(label)`
-- `fixtureScope.slug(label)`
-- `fixtureScope.email(label)`
-- `fixtureScope.string(label, options)`
-- `fixtureScope.token(label)`
-- `fixtureScope.seed(kind, key, signature, create)`
-- `fixtureScope.records()`
+### Node setup beside a test
 
-`testkit` enforces strict fixture behavior:
+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:
 
-- one logical fixture per `kind + key`
-- identical reseeds reuse the same seeded value
-- conflicting reseeds fail immediately
-- dependency cycles fail immediately
-- seeded fixture records are persisted as a `testkit.dal-fixtures` artifact
+```js
+// tests/webhook.contract.testkit.setup.mjs
+export async function setup({ sidecars }) {
+  const capture = await sidecars.httpCapture({ path: "/webhook" });
+  return {
+    data: { webhookUrl: capture.url, requestsUrl: capture.requestsUrl },
+  };
+}
+```
 
-The first-class k6 authoring namespace:
+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.
 
-```ts
-import { checks, expect, parse, waitFor } from "@gfdelarue/testkit/k6";
-
-const suite = defineHttpSuite(({ actor, rawReq, req }) => {
-  const me = req.get("/api/v1/me");
-  expect.status(me, 200, "authenticated session loads");
-  expect.json(me, (body) => typeof body.data?.id === "string", "response includes user id");
-
-  checks.authGate(rawReq, "sessions", {
-    get: ["/api/v1/sessions"],
-  });
-
-  actor?.rawHeaders();
-
-  const upload = req.multipart.post("/api/v1/uploads", {
-    fields: { name: "fixture" },
-    files: [
-      {
-        field: "file",
-        data: "hello",
-        filename: "fixture.txt",
-        contentType: "text/plain",
-      },
-    ],
-  });
+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__/`.
+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
+a sandbox for untrusted code.
 
-  expect.status(upload, 201, "upload is accepted");
-  parse.safeJson(upload);
-});
-```
+A run on [supplied values](#run-against-a-supplied-environment) does not run
+setup modules. Its tests receive the environment file's `setupData` instead.
 
-Use native k6 imports for checks, groups, metrics, and low-level HTTP:
+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
+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]`.
 
-```ts
-import { check, group } from "k6";
-import http from "k6/http";
-import { Rate, Trend } from "k6/metrics";
-```
+Setup shares the task's absolute deadline. On failure or cancellation, Testkit
+runs registered cleanup and closes its sidecars. Once setup succeeds, those
+resources remain available until the test and its native hooks finish and
+Testkit releases the file's environment. Cleanup callbacks run in reverse
+registration order. The runner uses the task timeout for cleanup, capped at
+60 seconds. Testkit stops a setup that hangs past that limit, which closes its
+listeners.
 
-The [k6 authoring guide](https://github.com/gfdelarue/testkit/blob/master/docs/k6-authoring-layer.md)
-describes the optional evidence recorder and migration from retired Testkit
-primitive, metric, option, and assertion aliases.
+Thrown setup errors, deadline expiry, and invalid data fail the task with the
+setup module path. Consumer cleanup errors fail the task; a failure in
+Testkit's own cleanup, or a setup that stops unexpectedly, counts as an
+infrastructure failure. Cleanup remains idempotent.
+HTTP capture retains at most 100 requests by default, configurable up to 1,000.
+Each body defaults to 1 MiB, configurable up to 8 MiB, and retained bodies total
+at most 8 MiB per listener. A setup can create up to 16 listeners, each with at
+most 256 connections.
 
-`waitFor()` consumes the file budget configured by `execution.fileTimeoutSeconds`.
-Consumers should not set local timeout values in test files.
+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`.
 
-```ts
-import { parse, waitFor } from "@gfdelarue/testkit/k6";
+### HTTP and persistence checks
 
-const response = waitFor(
-  () => req.get("/api/v1/jobs/123"),
-  (res) => parse.json(res).data?.status === "completed",
-  { description: "job 123 to complete" },
-);
-```
+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.
 
 ## Discovery
 
-`testkit` discovers suites from `__testkit__/` directories.
+Testkit discovers plain Vitest test files and typed suites.
+
+### Plain Vitest test files
+
+Testkit runs plain Vitest test files with the repository's own Vitest and its
+config, as `vitest run` does from the product directory. It loads the root
+`vitest.config.*` or `vite.config.*` the way Vitest does and lists the files
+that config's projects select, without running global setup. Nested configs and
+package scripts have no effect. Without a config, Vitest's defaults select files
+that match `**/*.{test,spec}.?(c|m)[jt]s?(x)`, outside `node_modules` and
+`.git`.
+
+`discover`, `run`, `typecheck`, `bug record`, and `bug file` take three flags
+that change the selection:
+
+- `--vitest-config <path>` uses that config, relative to the product
+  directory. A missing file, or one outside the product directory, fails before
+  any test runs.
+- `--vitest-project <name>` runs only that project. An unknown name fails and
+  lists the projects.
+- `--vitest-runner managed` runs plain files with Testkit's own Vitest and its
+  default rules, without the repository's config.
+
+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
+`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 see the host environment Testkit started with: `HOME`, `PATH`,
+temporary and XDG directories, locale, `CI`, `FORCE_COLOR`, `NO_COLOR`, and any
+other variable reach config loading, setup files, and the tests as they do
+under `vitest run`. Unlike `vitest run`, ambient `BASE_URL` and `DATABASE_URL`
+never reach them; those come only from the group's environment, from
+provisioned services or supplied values. Testkit loads no env files for plain
+files, and Vitest's own env handling and `test.env` work as usual. Testkit puts
+its own `--import` in front of the shell's `NODE_OPTIONS`. Preloads in it see the
+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.
+
+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.
+
+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`.
+
+The plain files in one directory form a suite named after that directory,
+relative to the group's root. In `root`, `--suite src` selects
+`src/sum.test.ts` and `src/sum.spec.ts`. A file directly in a group's root names
+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`.
+
+### Typed suites
+
+`testkit` discovers typed suites from `__testkit__/` directories.
 
 Place each `__testkit__/` directory as a peer of the thing being tested. The
 target is the smallest owned directory or package surface that honestly contains
@@ -1077,25 +1308,22 @@ production owner when a narrower owner exists.
 
 Concrete layouts:
 
-- `src/api/routes/__testkit__/auth-me.int.testkit.ts`
-- `src/db/__testkit__/sessions-count-type.dal.testkit.ts`
+- `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.int.testkit.ts`
+- `src/internal/handler/repos/__testkit__/crud.contract.testkit.ts`
 
 `testkit` uses these suffixes automatically:
 
-- `*.int.testkit.ts`
-- `*.e2e.testkit.ts`
 - `*.contract.testkit.ts`
 - `*.data.testkit.ts`
-- `*.dal.testkit.ts`
-- `*.load.testkit.ts`
 - `*.ui.testkit.ts`
 
-The suffix never chooses an engine. Each discovered file must also contain one
-root-package `defineFile(...)` declaration with a supported literal engine.
+The suffix never chooses an engine. Each discovered typed file must also
+contain one root-package `defineFile(...)` declaration with a supported literal
+engine.
 Unsupported pairs fail discovery; for example, a `*.ui.testkit.ts` file cannot
-declare `engine: "k6"`.
+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.
@@ -1114,30 +1342,61 @@ 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 `contract` for plain Node assertions and
-Node-side service or protocol contracts, `int` or `e2e` for k6-backed HTTP
-integration, and `ui` when a browser is part of the assertion.
+`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.
 
-Ownership is inferred from:
+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
+its tests `use`:
+
+```ts
+export default defineConfig({
+  services: {
+    api: app.node({ cwd: "services/api", start: "node dist/server.js" }),
+    web: app.next({ cwd: "apps/web", dependsOn: ["api"] }),
+  },
+  groups: {
+    api: { roots: ["services/api"], uses: ["api"] },
+    web: { roots: ["apps/web"], uses: ["web", "api"] },
+  },
+});
+```
 
-- the deepest matching service root from `services.<name>.local.cwd`
-- optional `services.<name>.discovery.roots` overrides for shared-root edge cases
+- A file belongs to the group with the deepest root that contains it. When two
+  groups have roots at the same depth, discovery reports `ambiguous_test`.
+- Files that no group's roots claim belong to the implicit group `root`, which
+  uses no service. With no `testkit.config.ts`, every file belongs to `root`.
+- A run starts the services that the selected files' groups use, with their
+  `dependsOn`, and nothing else. A test gets `BASE_URL`, `DATABASE_URL`, and
+  `env` values only from the services its group uses. When two of them set the
+  same name, the first in `uses` wins. Each used service's URL and database
+  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).
+
+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.
 
 Suite names are inferred from the colocated path:
 
-- `auth/__testkit__/*.int.testkit.ts` => `auth`
-- `routes/__testkit__/auth-me.int.testkit.ts` => `routes`
+- `auth/__testkit__/*.contract.testkit.ts` => `auth`
+- `routes/__testkit__/auth-me.contract.testkit.ts` => `routes`
 
 Discovery is also a first-class CLI/API surface:
 
 - `testkit discover`
-  - human-first compact output with service -> type -> suite -> file hierarchy
+  - human-first compact output with group -> type -> suite -> file hierarchy
 - `testkit discover --output-mode verbose`
-  - explicit paths, IDs, locks, dependencies, and skip reasons
+  - group roots and uses, explicit paths, IDs, locks, and skip reasons
 - `testkit discover --json`
   - machine-readable output with stable enums, canonical paths, and summary data
 - `testkit discover --output .testkit/discovery.json`
@@ -1166,7 +1425,7 @@ identifier plus canonical metadata such as:
 - `path`
 - `service`
 - `suiteName`
-- `testType`
+- `testType`, absent for a plain Vitest test file
 - `engineId`
 - `profileId`
 - `contract`
@@ -1177,8 +1436,10 @@ identifier plus canonical metadata such as:
 - `displayName`
 
 Discovery output has no cross-run counts, last outcomes, durations, or trends.
-See the [status and history migration](https://github.com/gfdelarue/testkit/blob/master/docs/release-notes.md#local-status-and-history-removal)
-for the removed discovery fields and consumer migration.
+Testkit 0.2.1 removed `testkit.status.json`, `.testkit/history/`, and
+discovery's `history`, `files[].history`, and `summary.latestResults` fields.
+To check one run, read its bundle under `.testkit/results/runs/<run-id>/`.
+Testkit ignores an old `.testkit/history/` directory and leaves it in place.
 
 ## Local Databases
 
@@ -1191,13 +1452,10 @@ 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.
 
-Client containers for a Testkit-owned database join that database container's
-network namespace (`--network container:<id>`) and connect over loopback. The
-route does not depend on the Docker daemon sharing the Testkit process's host
-network, so template steps, schema snapshots, and `database.steps` helpers work
-the same under Docker Desktop, rootless Docker, and Docker-in-Docker. Clients
-for external databases, such as `sourceSchema` URLs, still connect from the
-platform's host address.
+Template steps, schema snapshots, and `database.steps` helpers work the same
+under Docker Desktop, rootless Docker, and Docker-in-Docker. Clients for
+external databases, such as `sourceSchema` URLs, connect from the platform's
+host address, so those databases must be reachable from there.
 
 - normal test runs always use transient host-managed Postgres
 - template databases are cached
@@ -1213,7 +1471,8 @@ The service process receives its provisioned database as `DATABASE_URL`. Every
 task gets the same `DATABASE_URL` when its service declares a database, and its
 service's URL as `BASE_URL` when the service declares a server, whatever its
 engine. The provisioned `DATABASE_URL` replaces one that the service's `env`
-declares. Declared `env` values can also use the `{dbUrl}`, `{dbHost}`,
+declares. A test whose group uses several services with databases reads each
+one with `database(name)` from `@gfdelarue/testkit/environment`. Declared `env` values can also use the `{dbUrl}`, `{dbHost}`,
 `{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
@@ -1224,59 +1483,3 @@ schema cache. `db schema verify` prepares local templates and verifies local
 replay against the cached/refreshed source schema. `--skip-schema-source-verify`
 is available as a narrow escape hatch when users need to run tests while schema
 verification is temporarily blocked.
-
-## Development Tests
-
-```bash
-npm test
-npm run test:unit
-npm run test:integration
-npm run test:system
-npm run test:live
-npm run test:integration -- fixture-package
-```
-
-The four lanes use Vitest directly. Unit tests (source and pure tooling) run in
-parallel; integration and system files run serially; live tests are explicitly
-opt-in and serial. Pass ordinary Vitest filters after npm's `--` separator.
-`npm test` runs the first three lanes and never collects live cases.
-
-Live tests cover credentials, external services, network-acquired runtimes,
-alternate toolchains, and Docker/platform matrices. An explicitly selected live
-test fails clearly when its prerequisites are unavailable; it does not silently
-skip.
-
-Repository commands use npm's native timing support, enabled project-wide by
-the tracked `.npmrc`. Build, lint, and release modes support `help`; release
-provides `bump`, `check`, `consumer-lock`, and `plan` modes.
-A push to `master` publishes only when it raises `version` in `package.json`
-and the new version is above npm's latest. To release, run
-`npm run release -- bump <version>` and merge the pull request once its checks
-pass. The
-[publish workflow](https://github.com/gfdelarue/testkit/blob/master/docs/release-gates.md)
-publishes that exact version through npm trusted publishing and tags the
-merged commit. Any other merge publishes nothing.
-
-The static audit retains package/lock/runtime policy, engine dependency/import
-intent, retired engine/product references, minimal repository traversal, the
-dependency direction between top-level `src/` modules, and the test execution
-boundary. An import outside the direction table in
-`scripts/lint/audits/import-direction.ts` fails lint. The table may allow
-directions that no import uses. Test execution code may import only test
-execution and shared kernel code, apart from a committed list of existing
-imports that only shrinks. The
-[dependency direction notes](https://github.com/gfdelarue/testkit/blob/master/docs/dependency-direction.md)
-describe both rules. Other implementation-shape audits stay out of lint.
-
-JavaScript modules under `test/fixtures/**` describe fixture behavior and keep
-their fixture-owned paths. Outside fixtures, only `bin/testkit.mjs` and the
-documented raw Node process probe remain `.mjs`; the probe is a program, not a
-Vitest suite.
-
-GitHub Actions run a narrow installed Node/Vitest consumer smoke on dedicated
-Orthrus Ubuntu x64 and Windows x64 self-hosted runners for pull requests from
-this repository and manual dispatches. Fork pull requests skip this workflow's
-jobs. Local `npm test`,
-`npm run test:unit`, `npm run test:integration`, and `npm run test:system` remain
-the full developer entrypoints. PostgreSQL and Docker compatibility are explicit
-opt-in dispatcher cases. The smoke workflow is not five-platform release proof.