@gfdelarue/testkit 0.5.0 → 0.6.0

package/docs/release-notes.md

@@ -0,0 +1,2116 @@
+# 0.6.0
+
+0.6.0 removes the `contract` and `data` test types and legacy service
+ownership, and refuses config keys that Testkit doesn't read. To upgrade from
+0.5.0, work through these steps in order:
+
+1. If `testkit.config.ts` has `services` and no `groups`, add the groups that
+   the load error lists before you rename any typed file. The error lists a
+   group only for a service that still owns a typed file. Then, with or without
+   that step, move each service's `skip`, `requirements`, and
+   `runtimeIsolation` to its group. Move its `discovery.roots` and
+   `discovery.exclude` to the group's `roots` and `exclude`, as paths from the
+   product directory, and delete its `discovery`. See
+   [Remove legacy service ownership](#remove-legacy-service-ownership).
+2. Replace `--service` with `--group` on `run`, `discover`, `artifacts`, and
+   `workspace`, even if the config already has `groups`. See the same section.
+3. Turn each `*.contract.testkit.ts` file into a plain Vitest file. See
+   [Remove the contract test type](#remove-the-contract-test-type).
+4. Turn each `*.data.testkit.ts` file into a plain Vitest file that calls
+   `dataFlow(context)`, and delete `profiles` from `testkit.config.ts`. See
+   [Remove the data test type](#remove-the-data-test-type).
+5. Delete each config key that the load error names, or move its value to the
+   key that applies. See
+   [A config with an unknown key fails to load](#a-config-with-an-unknown-key-fails-to-load).
+6. Remove leftover `int`, `e2e`, `dal`, and `load` selectors. Delete or migrate
+   leftover files of those types, and files that declare `engine: "k6"`. 0.5.0
+   stopped running them, and 0.6.0 no longer flags them. See
+   [Testkit no longer recognises the types and engine that 0.5.0 removed](#testkit-no-longer-recognises-the-types-and-engine-that-050-removed).
+
+A config that sets `profiles` or an unknown top-level key fails to load before
+Testkit checks its groups. If that happens at step 1, delete those keys as
+steps 4 and 5 say, and load the config again.
+
+Upgrading from 0.4.x? Work through [0.4.5](#045) and then [0.5.0](#050) first.
+0.4.5 makes `local.port` a config error. 0.5.0 adds `groups`, which step 1
+needs, and removes the `int`, `e2e`, `dal`, and `load` types, whose files 0.6.0
+ignores without a warning.
+
+## Breaking changes
+
+### Remove legacy service ownership
+
+Only `groups` assign test files to services
+([gfdelarue/testkit#241](https://github.com/gfdelarue/testkit/issues/241)).
+Before 0.6.0, a config with `services` and no `groups` key gave each service the
+typed files under its `local.cwd` and `discovery.roots`, and printed a notice.
+That legacy ownership is gone. A config that relied on it fails to load and
+lists the groups to add:
+
+```text
+testkit.config.ts has services and no groups. Testkit 0.6.0 removed legacy service ownership, so services no longer own the test files under their directories. Add these groups to keep each typed test file with the service that owned it:
+
+groups: {
+  api: { roots: ["services/api"], uses: ["api"] },
+  web: { roots: ["apps/web"], uses: ["web"] },
+},
+
+A group also owns the plain Vitest files under its roots.
+Migrate with "Remove legacy service ownership" in node_modules/@gfdelarue/testkit/docs/release-notes.md.
+```
+
+- The error lists each service that owned a typed file, or excluded one under
+  its directories, with that service's `roots`, `uses`, and `exclude` as 0.5.0
+  resolved them.
+- `run`, `typecheck`, and `discover --strict` stop with it. `discover` without
+  `--strict` reports it as a `config_invalid` diagnostic. `status`,
+  `run status`, `destroy`, `cleanup`, and `db schema` still run, so you can
+  stop 0.5.0 services before you migrate.
+- A config whose services held no typed file, such as one with only a database
+  service, loads, and every file belongs to `root`.
+
+Migrate a two-service config:
+
+```ts
+// Before
+export default defineConfig({
+  services: {
+    api: app.node({ cwd: "services/api", start: "node dist/server.js", runtimeIsolation: "resetBefore" }),
+    web: app.next({ cwd: "apps/web", dependsOn: ["api"] }),
+  },
+});
+```
+
+```ts
+// After
+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"], runtimeIsolation: "resetBefore" },
+    web: { roots: ["apps/web"], uses: ["web"] },
+  },
+});
+```
+
+- Move a service's `skip`, `requirements`, and `runtimeIsolation` to its group.
+  `ServiceConfig` no longer declares them, and beside `groups` Testkit rejects
+  them on a service with a message that names the group field.
+- Move a service's `discovery.roots` and `discovery.exclude` to its group's
+  `roots` and `exclude`, and delete the service's `discovery`. A service's
+  `discovery` paths are relative to its `local.cwd`, and a group's are relative
+  to the product directory. The root `__testkit__` of a service whose
+  `local.cwd` is `services/api` becomes `services/api/__testkit__`. The error
+  above prints them that way. Beside `groups`, Testkit rejects a service's
+  `discovery` with a message that names the group's fields:
+
+  ```text
+  services.api.discovery applies to tests, and services own no tests when groups is set; move its roots and exclude to groups.api.roots and groups.api.exclude, as paths from the product directory
+  ```
+
+  The `discovery` that `database.fixture()` adds by default is still accepted.
+
+- A group's roots also claim plain Vitest files, which a service never did, and
+  a run starts the group's services for them. A service with no
+  `discovery.roots` and `local.cwd: "."` gets the root `.`, so its group owns
+  every plain file. To keep plain files in `root`, narrow the roots to the
+  directories that hold typed files.
+
+`run`, `discover`, `artifacts`, and `workspace` no longer take `--service` as an
+alias for `--group`:
+
+```text
+Testkit 0.6.0 removed --service from run, discover, artifacts, and workspace; use --group api
+```
+
+`status`, `destroy`, `cleanup`, and `db schema` keep `--service`, which names a
+service there.
+
+A discovered group's `source` is `groups` or `implicit`, and `TestGroupSource`
+no longer includes `services`. `inspectWorkspace()` from
+`@gfdelarue/testkit/workspace` no longer takes a `notice` callback.
+
+### Remove the contract test type
+
+This release removes the `contract` test type. A contract file becomes a plain
+Vitest file, which Testkit runs as it is. These are removed:
+
+- the `*.contract.testkit.ts` suffix and the `node-vitest-contract` profile
+- the `@gfdelarue/testkit/node-vitest/contract` export, with
+  `contractScenario`, `readContractContext`, `createHttpClient`, and their
+  types
+
+Wherever you can name `contract`, Testkit fails with a message that names the
+release and this section:
+
+```text
+__testkit__/health.contract.testkit.ts: Testkit 0.6.0 removed the contract test type. Migrate with "Remove the contract test type" in node_modules/@gfdelarue/testkit/docs/release-notes.md.
+```
+
+- `discover`, `run`, and `typecheck` stop on a leftover
+  `*.contract.testkit.ts` file unless a group excludes it, and `lint` and
+  `doctor` stop on any leftover file. A run stops even when the repository's
+  plain files would pass.
+- `testkit run contract`, `--type contract`, `--suite contract:<name>`, and
+  `contract:` selectors in `skip`, `requirements`, and `runtimeIsolation` stop
+  with the same message.
+- `bug file` refuses an unfiled draft for a contract file. For a draft it
+  already filed, it still returns the issue.
+- `status`, `run status`, `destroy`, `cleanup`, and `db schema` still run while
+  leftover files remain.
+- Stored runs whose suites are `contract` on `node-vitest-contract` stay
+  readable through `testkit artifacts`, `ci report`, and the workspace API.
+
+Migrate each contract file:
+
+| In a contract file                                                                   | In the plain Vitest file                                            |
+| ------------------------------------------------------------------------------------ | ------------------------------------------------------------------- |
+| `import { contractScenario, expect } from "@gfdelarue/testkit/node-vitest/contract"` | `import { expect, test } from "vitest"`                             |
+| `contractScenario(name, run)`                                                        | `test(name, run)`                                                   |
+| `contractScenario(name, { timeoutMs }, run)`                                         | `test(name, run, timeoutMs)`                                        |
+| `export const testkit = defineFile({ engine: "node-vitest" })`                       | Delete it and its import                                            |
+| `name.contract.testkit.ts`                                                           | A name your Vitest config includes, such as `name.test.ts`          |
+| `name.contract.testkit.setup.mjs`                                                    | `name.test.setup.mjs`                                               |
+| `context.baseUrl` and `context.http()`                                               | `endpoint(name)` from `@gfdelarue/testkit/environment`, and `fetch` |
+| `context.env`                                                                        | `process.env`                                                       |
+| `context.setupData`                                                                  | `setupData()` from `@gfdelarue/testkit/environment`                 |
+| `context.fixture("a.json")`                                                          | `readFileSync(new URL("./__fixtures__/a.json", import.meta.url))`   |
+| `context.serviceName`, `task`, `engineId`, and `profileId`                           | Nothing. Vitest owns test identity.                                 |
+
+A plain file has no `defineFile` metadata. Move its `skip`, `locks`, and
+`runtimeIsolation` to the group's `skip.files`, `requirements.files`, and
+`runtimeIsolation.files` in `testkit.config.ts`. A plain file gets services only
+from a declared group. See
+[Remove legacy service ownership](#remove-legacy-service-ownership).
+
+A typed file's tests and hooks could run until the file's timeout. Under the
+repository's Vitest, a plain file gets Vitest's own limits: 5 seconds for a test
+and 10 seconds for a hook, unless the Vitest config sets `testTimeout` and
+`hookTimeout`. Give a slow test its timeout, as in `test(name, run, timeoutMs)`,
+or set the limits in the config. Under `--vitest-runner managed`, Testkit sets
+them to the remaining time of the Vitest invocation, which starts with the sum
+of its files' timeouts.
+
+Each typed file was its own task, so with the default `taskConcurrency` of 1,
+typed files ran one at a time. Plain files that share a Vitest invocation run
+with Vitest's file parallelism, which `taskConcurrency` doesn't limit. If
+migrated tests can't run side by side, give each its own rows, or set
+`fileParallelism: false` or `maxWorkers` in the Vitest config. Under
+`--vitest-runner managed`, they run one at a time.
+
+Renaming a test file changes the path that bug issues name. A failure is known
+only when an open issue's `test.file` equals the failing file's path. After you
+rename a file, edit `test.file` in the facts block of each open issue that
+names it, so that `bugs.knownFailures: "allow"` still treats its failures as
+known. Issues and bug drafts that record `testType: "contract"` stay readable.
+
+### Remove the data test type
+
+This release removes the `data` test type. Its recording and budgets are now a
+library that a plain Vitest test calls: `dataFlow(context)` from
+`@gfdelarue/testkit/node-vitest/data`
+([gfdelarue/testkit#240](https://github.com/gfdelarue/testkit/issues/240)).
+These are removed:
+
+- the `*.data.testkit.ts` suffix, the `node-vitest-data` profile, and the data
+  runner
+- `dataScenario`, `createHttpClient`, `readDataContext`, and the `expect`
+  re-export from `@gfdelarue/testkit/node-vitest/data`, with the types of the
+  scenario context, the HTTP client, its actors, and fixtures
+- the `dataSuiteContract` lint rule
+- HTTP profiles: `profiles.http` in `testkit.config.ts`, and
+  `registerRepoConfig`, `getRepoConfig`, `clearRepoConfig`, `RepoConfig`, the
+  `HttpProfile*` types, `HttpRequestParams`, `RuntimeCookie`, `RuntimeEnv`, and
+  `RuntimeHeaders` from `@gfdelarue/testkit/config`
+- `*.data.testkit.ts` from the `testkitExcludes()` globs of
+  `@gfdelarue/testkit/tooling/vitest`
+- the `description` field of a scenario in `data-flow.json`, which only
+  `dataScenario` options could set
+
+Wherever you can name `data`, Testkit fails with a message that names the
+release and this section:
+
+```text
+__testkit__/flow.data.testkit.ts: Testkit 0.6.0 removed the data test type. Migrate with "Remove the data test type" in node_modules/@gfdelarue/testkit/docs/release-notes.md.
+```
+
+Testkit stops in the same places as for `contract`, above. A config that sets
+`profiles` fails to load, and `testkit lint` rejects a config that sets
+`lint.rules.dataSuiteContract`, with messages that name this section. Stored
+runs whose suites are `data` on `node-vitest-data`, and issues whose facts
+block says `"testType": "data"`, stay readable.
+
+Migrate each data file:
+
+| In a data file                                                                       | In the plain Vitest file                                                                                                        |
+| ------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------- |
+| `import { dataScenario, expect } from "@gfdelarue/testkit/node-vitest/data"`         | `import { dataFlow } from "@gfdelarue/testkit/node-vitest/data"` and `import { expect, test } from "vitest"`                    |
+| `dataScenario(name, (flow) => { ... })`                                              | `test(name, (context) => { const flow = dataFlow(context); ... })`                                                              |
+| `dataScenario(name, { timeoutMs }, run)`                                             | `test(name, run, timeoutMs)`                                                                                                    |
+| A helper that takes `DataScenarioContext`                                            | A helper that takes `DataFlow` from `@gfdelarue/testkit/node-vitest/data`                                                       |
+| `export const testkit = defineFile({ engine: "node-vitest" })`                       | Delete it and its import                                                                                                        |
+| `name.data.testkit.ts`                                                               | A name your Vitest config includes, such as `name.test.ts`                                                                      |
+| `flow.http()`, `flow.http({ profile })`, `createHttpClient`, and HTTP actor sessions | `fetch`, or your own client, against `endpoint(name)` from `@gfdelarue/testkit/environment`, then `flow.recordHttpRequest(...)` |
+| `profiles.http` in `testkit.config.ts`                                               | Log in from test code, and delete `profiles`                                                                                    |
+| `flow.fixture(name)`                                                                 | `readFileSync(...)`, and `flow.count(...)` and `flow.bytes(...)` if the test should record the file                             |
+| `flow.baseUrl`, `flow.env`, and `readDataContext()`                                  | `endpoint(name)` and `database(name)` from `@gfdelarue/testkit/environment`, and `process.env`                                  |
+| `flow.setupData`                                                                     | `setupData()` from `@gfdelarue/testkit/environment`                                                                             |
+| `flow.serviceName` and `flow.task`                                                   | Nothing. Vitest owns test identity.                                                                                             |
+| `lint.rules.dataSuiteContract`                                                       | Delete it                                                                                                                       |
+| `--type data` or `--suite data:<name>`                                               | `--type plain`, with `--group` or `--file` to narrow it                                                                         |
+
+A Shell test, before and after, abridged to one budget. Both versions leave out
+the `record`, `bytes`, and `count` calls before it and the `message` option of
+`equals`:
+
+```ts
+// Before: src/browser/__testkit__/browser-profile-history-work.data.testkit.ts
+import { defineFile } from "@gfdelarue/testkit";
+import { dataScenario } from "@gfdelarue/testkit/node-vitest/data";
+
+export const testkit = defineFile({ engine: "node-vitest" });
+
+dataScenario("shell BrowserTab profile and history path stays model-owned", async (flow) => {
+  const measurement = await measureBrowserProfileHistoryWork();
+  flow.expectMetric("shell.browser-profile-history.profileModelFiles").equals(2);
+});
+```
+
+```ts
+// After: src/browser/__testkit__/browser-profile-history-work.test.ts
+import { dataFlow } from "@gfdelarue/testkit/node-vitest/data";
+import { test } from "vitest";
+
+test("shell BrowserTab profile and history path stays model-owned", async (context) => {
+  const flow = dataFlow(context);
+  const measurement = await measureBrowserProfileHistoryWork();
+  flow.expectMetric("shell.browser-profile-history.profileModelFiles").equals(2);
+});
+```
+
+The migrated file keeps its metrics, budgets, `data-flow.json`,
+`data-flow-report.md`, and `data-flow-budget` failure details. As for a contract
+file, move its `defineFile` metadata to the group, give slow tests a timeout,
+check that its tests can run side by side, and after renaming it, edit
+`test.file` in the open issues that name it. See
+[Remove the contract test type](#remove-the-contract-test-type).
+
+Testkit no longer imports `testkit.config.ts` into any test process. A data test
+that relied on a side effect of that import, such as a value the config set in
+`process.env`, has to do that work itself.
+
+### A config with an unknown key fails to load
+
+`testkit.config.ts` used to load with keys that Testkit doesn't read, so a
+misspelled key such as `executoin` had no effect and no warning
+([gfdelarue/testkit#218](https://github.com/gfdelarue/testkit/issues/218)).
+Testkit now refuses such a config when it loads it, whether the file calls
+`defineConfig` or exports a plain object. The error names each unknown key, and
+the closest known key when one is close:
+
+```text
+testkit.config.ts has unknown keys "executoin" (mispelled "execution"?), "madeUpKey"; it accepts areas, artifacts, bugs, discovery, execution, fingerprints, groups, lint, redact, services, toolchains, ui
+```
+
+The same check now runs inside these blocks:
+
+- `discovery`, at the top level
+- each `groups` entry
+- `skip`, `requirements`, and `runtimeIsolation`, and the rules in their
+  `files` and `suites` lists, in a group
+- `artifacts`, `artifacts.retention`, and `artifacts.publication`
+- `fingerprints`
+- each `toolchains` entry, and a service's inline `runtime.toolchain`
+
+`execution`, `lint`, `bugs`, and each `areas` entry already rejected unknown
+keys. A config that sets `profiles` still fails with the message in
+[Remove the data test type](#remove-the-data-test-type).
+
+A key that Testkit never read never took effect. Delete it, or move its value
+to the key that applies. For example, `global: { fileTimeoutSeconds: 120 }`
+never set a timeout; `execution: { fileTimeoutSeconds: 120 }` does.
+
+### Testkit no longer recognises the types and engine that 0.5.0 removed
+
+0.5.0 named the release and its migration when it found an `int`, `e2e`, `dal`,
+or `load` file or selector, or a file that declared `engine: "k6"`. One minor
+release later, those checks are gone:
+
+- Discovery ignores a leftover `*.int.testkit.ts`, `*.e2e.testkit.ts`,
+  `*.dal.testkit.ts`, or `*.load.testkit.ts` file, and `discover`, `run`,
+  `lint`, `typecheck`, and `doctor` no longer reject it. If the repository's
+  Vitest config selects such a file, Testkit runs it as a plain Vitest file,
+  and `bug record` records a bug for it without a test type.
+- `--type int`, `--suite int:<name>`, and `int:` selectors in `skip`,
+  `requirements`, and `runtimeIsolation` fail as unknown types, such as
+  `Unknown type "int"`. Unless the Vitest config selects such a file,
+  `run --file` with it fails because it matches no suite.
+- Stored runs and bug drafts that name these types stay readable, and
+  `bug file` still returns the issue of a filed draft.
+- A typed file that declares `engine: "k6"` fails as any unknown engine does:
+  `unsupported engine "k6"; expected one of: node-vitest, playwright`.
+
+## New behaviour
+
+### A plain Vitest file with per-file needs runs in its own invocation
+
+In 0.5.0, a plain Vitest file with a setup module, locks that differ from the
+other plain files', or isolation other than `shared` stopped the run when other
+plain files ran with it. Such a file now runs in its own Vitest invocation, with
+its own environment, beside the invocation that runs the rest. Its setup module
+runs before its invocation starts, its locks hold for that invocation, and
+`resetBefore` gives it its own database clone. Root global setup, teardown, and
+the repository's reporters run once for each invocation.
+
+### A bare `testkit run` runs plain files from groups that use different services
+
+In 0.5.0, a run stopped before it started anything when its plain Vitest files
+belonged to groups that gave them different services or values
+([gfdelarue/testkit#378](https://github.com/gfdelarue/testkit/issues/378)). A
+repository with unit tests in `root` and plain files in a service-backed group
+couldn't pass the one-command CI gate the README recommends. Now plain files
+run in one Vitest invocation per environment their groups give them, each
+against its own group's services. 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. Root global setup, teardown, and the
+repository's reporters run once for each invocation, so a run calls them once
+more for each extra invocation. Invocations run one after another unless
+`--task-concurrency` or `execution.taskConcurrency` is above 1.
+
+### `--type plain` selects only plain Vitest files
+
+With `ui` the only test type, a run could select UI files with `--type ui` but
+had no way to select plain Vitest test files without them
+([gfdelarue/testkit#380](https://github.com/gfdelarue/testkit/issues/380)).
+`run` and `discover` now accept `--type plain`, which selects plain files only.
+It narrows `--group`, `--suite`, and `--file` like any other type, so
+`--group api --type plain` runs the `api` group's plain files and none of its UI
+files. `testkit run plain` does the same as `testkit run --type plain`.
+
+`--type ui,plain` selects the same files as `--type all`. A run whose `--type`
+names `plain` reports it in `run.types`, as it does `ui`.
+
+### `typecheck` reads Vitest setup files and takes `--group`
+
+`testkit typecheck` built the Node/Vitest program from the plain test files and
+what they import. A file in the Vitest config's `setupFiles` is named only as a
+string, so the program never reached it. Matchers that a setup file declares,
+such as `toBeInTheDocument` from `@testing-library/jest-dom/vitest`, failed with
+`TS2339` although `tsc` and `vitest run` accepted them
+([gfdelarue/testkit#379](https://github.com/gfdelarue/testkit/issues/379)).
+
+Each plain file's program now includes the TypeScript setup files of its Vitest
+project, and `typecheck` checks them like the test files. A setup file with a
+type error now fails `typecheck`. Files whose projects load different setup
+files go to separate programs, and the label of a program with setup files names
+them, as in `node-vitest with tests/setup.ts`. A JavaScript setup file, or a package named
+directly in `setupFiles`, still adds no types, so import the package from a
+TypeScript setup file.
+
+`typecheck --group <name>` checks the config and the files that group owns. A
+group's setup files are those of the Vitest projects its files belong to.
+
+### `setupData()` reads a file's setup data
+
+`setupData()` from `@gfdelarue/testkit/environment` returns the data the file's
+setup module returned, or the `setupData` of a supplied environment file. It
+works in plain Vitest files and Playwright files. A file
+without setup data gets `{}`. Outside a Testkit run, `setupData()` throws.
+
+### A run's result no longer depends on post-run maintenance
+
+After a run seals its evidence, Testkit tidies the product's local state:
+
+- it removes other runs' stale manifests;
+- it removes the product's unreferenced database containers and volumes;
+- it stops the idle retained database.
+
+That maintenance now runs after the seal and has its own result:
+
+- A failure no longer changes the run's status, exit code, or sealed evidence. `testkit run` prints `Notice: Post-run maintenance failed: <reason>. The run's result is unchanged.` on stderr.
+- `.testkit/results/maintenance.json` records the latest run's maintenance result. `testkit status` shows a warning while that result is failed.
+- When Testkit can't read part of the `.testkit` tree to inventory its storage, `run.json` records `"storage": { "testkit": { "status": "failed", "error": "…" } }` and the run keeps its result.
+
+A run that fails to release its own resources, such as dropping its task databases, still fails. A group whose tests passed now reports that failure as an infrastructure failure, `INFRA`, instead of a test failure, `FAIL`. So does a failure while sealing the run.
+
+### Retired-type errors name the installed release notes
+
+The package now ships `docs/release-notes.md`. Each error that points at a
+migration names the section and the installed file, such as
+`Migrate with "Remove the contract test type" in node_modules/@gfdelarue/testkit/docs/release-notes.md`.
+It used to name `docs/release-notes.md#…`, which the package didn't ship.
+
+## Fixes
+
+### `campaign finish` lists plain Vitest tests
+
+The summary's "Testkit tests added or changed" list held only `*.testkit.ts`
+files, so it left out the plain Vitest test files that Testkit has run since
+0.5.0. It now also lists changed files named like a Vitest test, such as
+`refund.test.ts` or `refund.spec.js`.
+
+### `typecheck` uses the repository's `lib` for plain files
+
+The Node/Vitest program set `lib` to ES2022 in place of the `lib` of the
+repository's tsconfig. A plain file that runs in a jsdom or happy-dom
+environment failed `typecheck` with `Cannot find name 'document'`, or, when a
+package brought in the DOM library alone, with `TS2488` on a `NodeList` spread,
+although the repository's own `tsc` accepted it
+([gfdelarue/testkit#398](https://github.com/gfdelarue/testkit/issues/398)).
+
+A Node/Vitest program now uses the `lib` of the tsconfig it extends, and
+ES2022 only when there is no tsconfig. A test that uses a library its tsconfig
+leaves out now fails `typecheck` as it fails `tsc`.
+
+### A UI file's launch options keep managed Chromium
+
+A UI file that set `launchOptions` with `test.use` lost the `executablePath`
+of the Chromium that Testkit manages, because the file's value replaced the
+config's. Playwright then started its headless shell where one was installed,
+and failed to launch where none was. The headless shell never restores a page
+from the back/forward cache, so a file couldn't test that
+([gfdelarue/testkit#373](https://github.com/gfdelarue/testkit/issues/373)).
+
+Testkit now sets the managed `executablePath` after the file's launch options,
+whether the file imports `test` from `@playwright/test`, `playwright/test`, or
+`@gfdelarue/testkit/playwright`. The file's other options still apply.
+[Browser launch options](engines.md#browser-launch-options) shows how a file
+turns on the back/forward cache.
+
+### A group's `NODE_ENV` reaches plain files under the managed runner
+
+Under `--vitest-runner managed`, a service that set a key Vitest or Vite writes
+itself failed the Node/Vitest files in the groups that use it. Such keys
+include `NODE_ENV`, `TEST`, `VITEST_MODE`, `SSR`, and a `VITE_` value that a
+`.env` file also sets. With `NODE_ENV` or `VITEST_MODE`, each file took 60
+seconds to fail, the time Vitest waits for a worker that never starts
+([gfdelarue/testkit#384](https://github.com/gfdelarue/testkit/issues/384)).
+These keys now behave as under the repository's Vitest: tests see the group's
+`NODE_ENV` and `VITE_` values, and Vitest's own `TEST`, `VITEST`,
+`VITEST_MODE`, `FORCE_TTY`, `MODE`, `DEV`, `PROD`, and `SSR`.
+
+When the Node/Vitest driver or a Vitest worker fails while it installs the
+run's input, its files now fail at once with `NODE_VITEST_START_FAILED` and the
+cause, instead of after Vitest's 60-second wait:
+
+```text
+Vitest could not start: Node/Vitest runtime input size changed after preparation
+```
+
+### A UI file can import from a `.tsx` module that contains JSX
+
+A UI file that imported anything from a `.tsx` module of the product that
+contains JSX failed before its tests ran:
+
+```text
+Error: Playwright consumers may not import managed package file outside exact public exports: playwright (resolved /…/node_modules/playwright/jsx-runtime from file:///…/src/view.tsx)
+```
+
+Playwright compiles the module's JSX to import its runtime by an absolute path,
+`<playwright>/jsx-runtime`, instead of by the specifier `playwright/jsx-runtime`
+([gfdelarue/testkit#390](https://github.com/gfdelarue/testkit/issues/390)).
+Testkit now reads a path in a managed Playwright package that names one of the
+package's exact exports as that export, so the runtime resolves to Testkit's
+pinned Playwright.
+
+### A test's data-flow evidence comes from its final repeat
+
+When a repository's `aroundEach` hook failed a later repeat of a test before it
+called `runTest`, the test's `data-flow.json` entry and `data-flow-budget`
+details came from the earlier repeat
+([gfdelarue/testkit#359](https://github.com/gfdelarue/testkit/issues/359)). Only
+Vitest 4.1's `aroundEach` could do this. `dataFlow` now records the test's
+configured repeats, and Testkit keeps a test's evidence only from its final
+repeat.
+
+### A cancelled `sql-file` step stops
+
+A `sql-file` database step ignored its caller's cancellation and its step
+deadline, so its Postgres client ran until the SQL finished or the client's own
+30-minute timeout passed, even after the run was cancelled
+([gfdelarue/testkit#381](https://github.com/gfdelarue/testkit/issues/381)). It
+now stops as `command` and `module` steps do, when its caller cancels it or its
+step deadline passes, and its server query ends with it. The step deadline
+defaults to 60 minutes, so a `sql-file` step that 0.5.0 stopped at 30 minutes
+can now run for up to 60.
+
+### A cancelled admin query says when its server query may still run
+
+When Testkit cancelled a database admin query that runs through `docker exec`,
+or found it stalled, and then failed to end the query's server backend, the
+error named only the cancellation while the server query kept running
+([gfdelarue/testkit#382](https://github.com/gfdelarue/testkit/issues/382)). The
+error now also names the failed termination and its reason, and Testkit doesn't
+retry that attempt.
+
+# 0.5.0
+
+## Remove k6
+
+This release removes the k6 engine and the `int`, `e2e`, `dal`, and `load` test
+types. Testkit runs plain Vitest files, typed Vitest `contract` and `data`
+files, and Playwright `ui` files.
+
+Wherever you can name a retired type, Testkit fails with a message that names
+the release and this section:
+
+```text
+__testkit__/health.int.testkit.ts: Testkit 0.5.0 removed the int test type. Migrate with docs/release-notes.md#remove-k6.
+```
+
+- Discovery rejects a file of a retired type unless a group excludes it. A
+  file that still declares `engine: "k6"` fails the same way, naming the k6
+  engine.
+- `--type`, `--suite`, and the selectors in `skip`, `requirements`, and
+  `runtimeIsolation` reject a retired type.
+- `lint`, `typecheck`, and `doctor` stop on a retired file with the same
+  message.
+- `bug file` refuses an unfiled draft for a retired type. For a draft it
+  already filed, it still returns the issue.
+- `status`, `run status`, `destroy`, `cleanup`, and `db schema` still run while
+  retired files remain, so you can inspect and clean up local state before you
+  migrate.
+- Stored runs and bug drafts that name a retired type stay readable.
+
+These are removed with the engine:
+
+- the `@gfdelarue/testkit/k6` export and the k6 binary packages
+- the k6 HTTP and DAL helpers and the k6 execution options
+- the synchronous response types `RuntimeHttpClient`, `RuntimeResponse*`,
+  `RuntimeHttpTrace*`, and `RuntimeHeaderValue`, from the
+  `@gfdelarue/testkit/config` and `@gfdelarue/testkit/node-vitest/data`
+  declarations
+- the `dalParallelSafety` lint rule. Delete it from `lint.rules`, because
+  Testkit rejects an unknown rule.
+
+To migrate, move HTTP, database, and service-flow checks to plain Vitest files.
+Read named endpoints and databases from `@gfdelarue/testkit/environment`, and
+use `fetch` or your application's database client. `contract` and `data` files
+keep their APIs, HTTP profiles still configure the `data` HTTP clients, and
+`ui` files still run on Playwright. Testkit has no replacement for load tests.
+
+## Plain Vitest test files run
+
+Testkit runs a repository's ordinary Vitest test files, such as
+`src/sum.test.ts` and `src/sum.spec.ts`, as they are
+([gfdelarue/testkit#237](https://github.com/gfdelarue/testkit/issues/237)):
+
+- A plain file needs no Testkit suffix, `__testkit__` directory, `defineFile`,
+  or wrapper, and keeps its native `vitest` imports.
+- Testkit finds plain files the way the repository's Vitest config selects
+  them, as the next section describes.
+- `discovery.exclude` and a declared group's `exclude` narrow the list.
+  Testkit's built-in exclusions, `discovery.roots`, and a legacy service's
+  rules apply only to typed files, so a legacy service's `exclude` doesn't drop
+  a plain file.
+- A plain file belongs to the implicit `root` group unless a declared group's
+  roots claim it, and it gets the values of the services its group uses.
+  Testkit starts no service for a plain file in `root`.
+- Plain files have no test type. They run under the general `node-vitest`
+  profile, and a bug filed from one records no `testType`. A `--type` that
+  names test types and typed suite selectors leave them out; `--type all`
+  includes them.
+- The plain files in one directory form a suite named after that directory,
+  relative to the group's root, and a file directly in a group's root names
+  its own suite. In `discover --json` plain files have no `testType`, and their
+  IDs have no type segment: `root|node-vitest|node-vitest|src/sum.test.ts`.
+  `summary.byTestType` counts typed files only. `testkit discover` lists them
+  under `Vitest`.
+- `typecheck` checks plain TypeScript test files and skips plain JavaScript
+  ones.
+- `unitTestBoundaries` stays off by default and only reports. Its messages no
+  longer tell a unit test to move to a Testkit suite.
+
+A bare `testkit run` in a repository with ordinary Vitest files now runs them
+too. To run typed files only, name their types:
+`--type data,contract,ui`.
+
+## Plain Vitest test files run with the repository's Vitest
+
+Plain files run with the repository's own Vitest installation and config
+([gfdelarue/testkit#238](https://github.com/gfdelarue/testkit/issues/238)):
+
+- Testkit loads the root `vitest.config.*` or `vite.config.*` as `vitest run`
+  does from the product directory, and lists the files its projects select
+  without running global setup. Nested configs and package scripts have no
+  effect. The notice that Testkit ignored a root Vitest config is gone.
+- `discover`, `run`, `typecheck`, `bug record`, and `bug file` take
+  `--vitest-config <path>`, `--vitest-project <name>`, and
+  `--vitest-runner repo|managed`. `managed` keeps the previous behaviour:
+  Testkit's own Vitest with its default rules and no repository config.
+- Testkit supports Vitest 4.x. Another major, a broken installation, a root
+  Vitest config that fails to load, or a Vitest that the product declares but
+  has not installed fails before any test runs, with a message that names the
+  path. Most of these messages also suggest `--vitest-runner managed`. 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 files.
+- All plain files in a run go to one Vitest invocation. 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, and Vitest's own test and hook
+  timeouts apply inside it. A file that two projects select runs in both, 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.
+  Different services or locks, isolation other than `shared`, or a setup
+  module stop the run before Testkit provisions anything; different values
+  stop it before Vitest starts. When `testkit stop` cuts the invocation short,
+  every file that hasn't finished, started or not, is cancelled.
+- Testkit sets only `allowOnly: false`, `includeTaskLocation: true`,
+  `passWithNoTests: false`, and `update: "none"` over the repository's config,
+  so a plain file's failure `location` has a line and column. A project that
+  sets `includeTaskLocation: false` itself keeps that setting.
+- Plain files see the host environment Testkit started with, from config
+  loading to the test, including `FORCE_COLOR`, `NO_COLOR`, and the shell's
+  `NODE_OPTIONS`, to which Testkit adds its own `--import`. Unlike
+  `vitest run`, ambient `BASE_URL` and `DATABASE_URL` never reach them; those
+  come only from the group's environment. Testkit loads no env files for them.
+- Node/Vitest processes no longer receive `TESTKIT_INTERNAL_FILE_DEADLINE_MS`
+  or `TESTKIT_INTERNAL_FILE_TIMEOUT_SECONDS`, which nothing in them read.
+- Testkit's own output honours `NO_COLOR` in a terminal and treats
+  `FORCE_COLOR=0` or `FORCE_COLOR=false` as no colour, as Node does.
+- Node/Vitest reserves the exact keys it sets itself instead of the whole
+  `TESTKIT_` and `VITEST_` prefixes, so a policy key such as
+  `TESTKIT_REQUIRE_COMPLETE_SUITE` reaches the run from either environment
+  source.
+- `bug record` saves the Vitest selectors it was given in the local draft, and
+  asks for `--vitest-project` when two projects run the test's file.
+  `bug file` reruns with them, and the issue's reproduce command carries them.
+  With `TESTKIT_REQUIRE_COMPLETE_SUITE=1`, `bug file` reruns every file the
+  selection lists before it reads the recorded failure.
+- Typed node-vitest files keep Testkit's own Vitest and its authoring entry
+  points. Testkit no longer checks which packages their imports resolve to.
+- Typed node-vitest files now resolve `paths` from their nearest
+  `tsconfig.json`, through Vite, instead of from the product root's
+  `tsconfig.json` or `tsconfig.build.json`. A repository whose `paths` are only
+  in `tsconfig.build.json` must move them into a `tsconfig.json`.
+- Engine evidence names only the Vitest version in `directPackages`, and its
+  `installationKind` is `repository-package` when the repository's Vitest ran.
+
+## A run that stops on an error names it
+
+`testkit run` names an error that stops the whole run rather than one test
+file, such as the planning refusal for plain Vitest files that cannot share
+one invocation (#352). Before, the default output showed only
+`Runtime errors: N`, and the message needed `--output-mode debug` or `--json`.
+
+- The text output prints `FAIL run error` and the message when the error
+  happens.
+- `--output-mode events` writes a `run.error` event with `message`, once for
+  each error, not once for each group.
+- The debug summary labels each group's error `error:` instead of
+  `worker error:`.
+
+## A failed coverage threshold fails the run, not each file
+
+When the repository's Vitest config enables coverage with thresholds and the
+coverage falls short, Vitest exits 1 after its tests pass. Testkit used to
+mark every file in the run as an unexplained infrastructure failure. Each file
+now keeps its own outcome, and the run fails with a run error that carries
+Vitest's message:
+
+```text
+FAIL run error
+    Vitest failed the run after its tests passed: ERROR: Coverage for lines (50%) does not meet global threshold (100%)
+```
+
+The thresholds apply to the files Testkit runs, as they do to
+`vitest run <file>`, so `testkit run --file` can fail on coverage while the
+whole suite passes.
+
+## Record data-flow evidence in a plain Vitest test
+
+`dataFlow(context)` from `@gfdelarue/testkit/node-vitest/data` gives a plain
+Vitest test the recorder that `dataScenario()` passes to its callback:
+
+```ts
+import { test } from "vitest";
+import { dataFlow } from "@gfdelarue/testkit/node-vitest/data";
+
+test("lists one page of orders", async (context) => {
+  const flow = dataFlow(context);
+  flow.count("orders.queries", 1);
+  flow.budget("orders.queries").atMost(1);
+});
+```
+
+- Every call in one attempt returns the same recorder. Without the context of
+  a running test, `dataFlow` throws and says how to call it.
+- A failed budget fails the test that declared it when the test finishes.
+- The file's `data-flow.json` lists one scenario for each test that recorded
+  data, named by the test's full title and taken from its final attempt. A
+  skipped test, or one that records nothing, adds no scenario.
+- `dataScenario()` now runs on `dataFlow()`. A scenario inside a `describe`
+  block is named by its full title, the `describe` names and its own name
+  joined by spaces. It used to have its own name only.
+- Typed `data` files still register every case with `dataScenario()`.
+
+## Readiness leaves no connection open
+
+Testkit no longer holds a connection to a service after its readiness check.
+The check used `fetch`, and when it gave up on a slow attempt and tried again,
+the connection pool could open a connection that never carried a request. A
+Node service that calls `server.close()` on SIGTERM waits for that connection,
+so it ran past its `local.shutdownTimeoutMs` grace, one second by default, and
+Testkit killed it with SIGKILL. Its shutdown work, such as flushing logs, did
+not finish.
+
+The readiness check now opens its own connections without keep-alive and
+closes all of them when it returns, whether the service became ready, timed
+out, exited, or the run was cancelled. It sends the headers `fetch` sent, with
+`Connection: close`. It still follows up to 20 redirects and still needs a 2xx
+response. A redirect fails the attempt when its `Location` holds a username or
+password, as with `fetch`. A redirect with more than one `Location` also fails
+the attempt. `fetch` joined the values into one URL instead.
+
+Other changes:
+
+- A `readyUrl` that holds a username and password now sends them as Basic
+  authentication, including after a relative redirect. `fetch` refused such a
+  URL, so readiness used to time out.
+- A `readyUrl` on a port that `fetch` blocks, such as 6666, now works.
+- Readiness connects to the service directly. With `NODE_USE_ENV_PROXY` or
+  `--use-env-proxy`, it no longer goes through `HTTP_PROXY` or `HTTPS_PROXY`.
+
+## Every service URL answers HTTP before tests start
+
+A local service's `baseUrl` now has to answer HTTP before any test receives it.
+Any response counts, including a 4xx or 5xx status, because only the test knows
+which status is wrong. A port that accepts connections but does not answer HTTP
+does not count. Testkit retries until `readyTimeoutMs` runs out and then fails
+the service's startup, so its tasks end `not_run` with an infrastructure
+failure.
+
+- A service whose `readyUrl` has the same origin as its `baseUrl` is checked
+  only at its `readyUrl`, which still needs a 2xx response. `app.node` and
+  `app.next` default to such a `readyUrl`.
+- `readyUrl: false` used to mean the service was ready once it had started. It
+  now removes only the 2xx check, and `baseUrl` must still answer HTTP.
+- `local.baseUrl` is optional. A process without an HTTP endpoint, such as a
+  worker, declares none: `worker: { local: { start: "node worker.mjs" } }`. It is
+  ready once it has started, and its groups get no URL for it.
+  `{baseUrl:worker}` fails to resolve, and `run.json` records its `baseUrl` as
+  `null`.
+- A `readyUrl` that is not an HTTP URL fails startup at once instead of at
+  `readyTimeoutMs`.
+
+This breaks a config whose local service never answers HTTP at its `baseUrl`,
+including one with `readyUrl: false`. Delete the service's `baseUrl`. `app.node`
+and `app.next` always set one, so declare such a service as a plain `local`
+block instead.
+
+Playwright tasks no longer check their URL themselves. That check opened a TCP
+connection, only for a URL outside the local machine, and ran inside the file
+timeout. The `TESTKIT_HTTP_ENDPOINT_PREFLIGHT` variables and the
+`http_endpoint_readiness` failure detail are gone.
+
+## A port that another process answers no longer counts as ready
+
+Testkit releases a service's port just before it starts the service. If another
+process took the port in between and answered HTTP, readiness passed. The
+service then failed to bind and exited, and the run stopped
+([gfdelarue/testkit#339](https://github.com/gfdelarue/testkit/issues/339)).
+After readiness passes, Testkit now checks that every listener on the port
+belongs to the service. If one doesn't, Testkit stops the service and starts it
+again on a fresh port, within the same three attempts, and records the attempt
+as `another process held the port`. The check runs on Linux and Windows. On
+macOS, and for a listener Testkit can't attribute, readiness counts as before.
+
+## A slow database probe no longer ends readiness
+
+Testkit gives a local Postgres container 60 seconds to accept connections and
+probes it with `docker exec pg_isready`, at most 10 seconds per probe. A probe
+that ran past its 10 seconds used to fail the database at once with `Docker
+local Postgres readiness probe ... exceeded its managed deadline`, even with
+most of the 60 seconds left. A busy Docker daemon can make one probe that slow.
+That probe now counts as one failed attempt, and Testkit keeps probing until the
+database answers or the 60 seconds run out. Cancelling the run still stops
+readiness at once.
+
+## A slow database query is no longer cut off at 15 seconds
+
+Testkit gave each `docker exec psql` admin query 15 seconds, then failed its
+operation with `Docker Postgres admin query ... exceeded its managed deadline`.
+A `CREATE DATABASE` that waited for a lock on its template, or ran slowly on a
+busy Docker host, failed this way while Postgres was still doing the work
+([gfdelarue/testkit#334](https://github.com/gfdelarue/testkit/issues/334)).
+A query now runs for as long as its Postgres backend is active. Every 15
+seconds Testkit looks for the query's session in `pg_stat_activity`. When two
+checks in a row miss it, or a check fails, Testkit stops the query, terminates
+its backend, and reports the same error.
+
+## Docker reads go to the CLI after a direct read times out
+
+Each Docker metadata operation reads the engine directly for up to 5 seconds,
+then runs the docker CLI for the rest of its deadline. Once a direct read times
+out, later operations in the process go straight to the CLI, instead of losing
+another 5 seconds each. A deadline error now says how long each step took:
+
+```text
+Docker container inventory exceeded its managed deadline: the direct read took 5.0 s, then the docker CLI ran 25.0 s
+```
+
+## Node/Vitest failures keep their errors
+
+These changes apply to every node-vitest file
+([gfdelarue/testkit#237](https://github.com/gfdelarue/testkit/issues/237)):
+
+- A file whose import throws now fails with that error as a `vitest-error`,
+  instead of `NODE_VITEST_NO_TESTS`. A file that defines no tests still fails
+  with `NODE_VITEST_NO_TESTS`.
+- A `vitest-error` from an import or a suite-level hook such as `beforeAll`
+  keeps the error's stack in `stack`, and its `message` now starts with the
+  error's name, such as `TypeError:`.
+- A `vitest-test` failure's `message` is the error's name and its whole
+  message, as Vitest prints them, such as
+  `AssertionError: expected 2 to be 3 // Object.is equality`. The stack moves
+  to `stack`. The message used to be the error's stack text. For a test that
+  hits its own timeout, that text didn't contain "Test timed out".
+- After retries, a `vitest-test` failure describes the final attempt. The
+  earlier attempts' errors stay in the native report.
+- A `vitest-test` failure's `location` gives the line and column where the
+  test is declared, beside its path. It used to give the path alone.
+- A missing or invalid native report is an infrastructure failure,
+  `NODE_VITEST_REPORT_INVALID`, whatever Vitest's exit code. A nonzero exit
+  used to make it a product failure.
+- The `testkit-vitest-report` artifact lists every case with its state and the
+  number of attempts Vitest made, so a retried test's attempts are in the run's
+  evidence.
+
+## `bug record` and `bug file` check the test a bug names
+
+- `bug record` records a bug only for a test that Testkit discovers. It used
+  to accept any existing file whose name gave a type, so a draft could name a
+  file that `bug file` could not run. A misplaced typed file now stops
+  `bug record` with discovery's own error, as it stops `testkit run`.
+- A draft records `testType` only when the test file's name gives one.
+- `bug file` refuses a node-vitest test when another test in the same file has
+  the same full title, whether that test passed or failed. An issue names its
+  test by file and title, so it could not tell the two apart. Give each test
+  its own title, then record the bug again
+  ([gfdelarue/testkit#237](https://github.com/gfdelarue/testkit/issues/237)).
+
+## `cleanup --dir` cleans the product it names
+
+`testkit cleanup --dir` cleans the product that `--dir` names when that product
+has no config. It used to clean the directory it was run from. A run with
+nothing to run, from a product with no config, wrote its results there too
+([gfdelarue/testkit#322](https://github.com/gfdelarue/testkit/issues/322)).
+
+## Env files are read only for the services a run uses
+
+Loading `testkit.config.ts` no longer reads any env file. Testkit reads a
+service's `envFile`, `envFiles`, or default `.env.testkit` and `.env` files only
+when a selected group uses the service or a used service depends on it. A
+missing or unreadable file of an unused service no longer stops a run. File
+order and precedence are unchanged. A later file overrides an earlier one, `env`
+overrides every file, `local.env` overrides `env`, and a group takes each name
+from the first service in its `uses` that sets it.
+
+- A service that declares only `env` or env files starts nothing, and neither
+  does a `dependsOn` edge between such services. Their groups get the values
+  with no runtime slot, `testkit.runtime.ensure`, graph directory, or teardown.
+  Such a service used to take a runtime slot.
+- A group that uses a service now gets the config's `ui` settings even when its
+  services declare nothing else. It used to get them only when a service
+  declared env values or a dependency.
+- Because nothing starts for it, such a service's `env` and `ui` can use only
+  `{service}`, `{stateDir}`, `{productDir}`, `{lease}`, `{leaseDir}`, `{bin}`,
+  and `{pathList}`. `{runtime}` and `{prepareDir}` used to resolve against the
+  runtime it no longer takes. They and every port, URL, and database token now
+  fail the group's tasks with an infrastructure failure that names the token.
+- `defineTestkitConfig` from `@gfdelarue/testkit/playwright` no longer loads
+  dotenv files. It used to load `.env.local` outside a Testkit run, and also
+  inside one with `onlyWhenAllowed: false`. Its `cwd`, `dotenvFiles`,
+  `onlyWhenAllowed`, and `override` options are removed, and passing one throws.
+  In a Testkit run, the services a group uses have already provided their
+  values when the config loads. To load a file when you run Playwright on its
+  own, do it in `playwright.config.ts` with a dotenv library of your own.
+  `@gfdelarue/testkit/env` does not resolve inside a managed Playwright run, so
+  importing it there fails the run.
+- `archive.declaredEnvironmentKeys` in `run.json` and the bundle provenance lists
+  the names a used service declares in `env`. It no longer includes names that
+  only an env file sets.
+
+## Test groups
+
+`testkit.config.ts` takes a `groups` key. A group owns the test files under its
+`roots` and names 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"] },
+  },
+});
+```
+
+- A file belongs to the group with the deepest root that contains it. Files
+  that no group claims belong to the implicit group `root`, which uses no
+  service. With no config, every file is in `root`. In a repository without
+  services, discovery, file IDs, and run results now name `root` where they
+  named `app`.
+- A test gets values only from the services its group uses. When two of them
+  set the same name, such as `BASE_URL`, `DATABASE_URL`, or an `env` entry, the
+  first in `uses` wins.
+- `skip`, `requirements`, and `runtimeIsolation` belong to the group. Beside
+  `groups`, Testkit rejects them on a service with a message naming the group
+  field to use, and it ignores a service's `discovery`. `groups: {}` gives
+  every file to `root`.
+
+A config with `services` and no `groups` key keeps legacy ownership: each
+service owns the typed files under its `local.cwd` and `discovery.roots`. A
+typed file outside every service root now belongs to `root`; discovery used to
+fail it with `unowned_test`. When legacy ownership gives a file to a service,
+`run`, `discover`, `workspace`, and `typecheck` print a notice once on stderr.
+Legacy ownership and the `--service` alias on test-selecting commands will be
+removed
+([gfdelarue/testkit#241](https://github.com/gfdelarue/testkit/issues/241)).
+
+`run`, `discover`, `artifacts`, and `workspace` take `--group <name>`. On those
+four commands `--service` still works as an alias for `--group` and prints a
+notice. Passing both with different names is a usage error. Other commands,
+such as `status`, `destroy`, `cleanup`, and `db schema`, keep `--service` for
+services. `workspace --group` filters discovery and targets but not service
+status, which `workspace --service` used to filter.
+
+`discover --json` is schema 10:
+
+- `services[]` is `groups[]`. Each group has `name`, `roots`, `uses`, `source`
+  (`groups`, `services`, or `implicit`), `suiteCount`, `fileCount`,
+  `activeFileCount`, and `skippedFileCount`. `localCwd`, `dependsOn`, and
+  `discovered` are gone. `root` is always listed.
+- On files and suites, `service` is `group` and `groupLabel` is `suiteLabel`.
+  `dependsOn` and `contract.executionHost` are gone.
+- `filters.service` is `filters.group`, `summary.services` is
+  `summary.groups`, and `summary.byService` is `summary.byGroup`.
+  `ambiguous_test` diagnostics list `groupNames`. `unowned_test` no longer
+  occurs.
+- File and suite IDs keep their format, with the group name first.
+
+`workspace --json` is schema 3. It embeds the schema 10 summary and
+diagnostics, and its targets carry `group` in place of `service`.
+`@gfdelarue/testkit/workspace` exports `DiscoveryGroup` in place of
+`DiscoveryService`, and `discoverTests` and `inspectWorkspace` take a `group`
+option in place of `service`.
+
+## Test ownership
+
+`testkit discover` and the loader now assign test files to owners through one
+resolver, which `groups` builds on (#233). Under legacy ownership, owner names
+and file IDs stay the same, with these changes:
+
+- `run` and `typecheck` find a Playwright config by walking up from the common
+  parent of the owning service's discovery roots to the product directory. They
+  used to look only in the service's rendered `local.cwd`. A service with
+  `discovery: { roots: ["apps/web/e2e"] }` now uses
+  `apps/web/playwright.config.ts`.
+- A service named `root` is rejected and must be renamed, because `root` is
+  the implicit group that owns files no other group claims.
+- A `discovery.exclude` entry that names a single file now drops that file in
+  every mode. Before, it was ignored when the config declared no services, and
+  with services a file outside every service root was reported as
+  `unowned_test`.
+- A file that two discovery roots of the same service both claim is no longer
+  ambiguous. With `local.cwd: "api"` and `discovery.roots: [".", "../api"]`, a
+  file under `api` used to be reported as `ambiguous_test` naming `api, api`.
+  It now belongs to `api`.
+- A file that overlapping repository `discovery.roots` both reach, such as
+  `[".", "src"]`, is listed once. Its suite used to list it twice.
+- Two suites in a group and type no longer get the same name. When short names
+  collided, the fallback could give a suite a numbered name that another
+  directory already had, such as `a-b-2`, and merge the two suites.
+
+A run builds its tasks from test groups and starts only the services those
+groups use, with their `dependsOn`. Under legacy ownership each service owns
+its tests as a group that uses that service, so a run starts the same services
+as before. Two things change:
+
+- A task gets values only from the services its group uses. Its endpoints no
+  longer include a `dependsOn` service, so a Playwright test's
+  `readPlaywrightContext().endpoints` lists only its own service. A used
+  service can still pass a dependency's URL on through `env`, for example with
+  `endpoint.serviceContextUrl("api")`.
+- A service whose selected files are all skipped no longer reserves a runtime
+  instance or database capacity. `run.json` leaves it out of
+  `environment.capacity.instanceCount` and
+  `environment.capacity.resourceBudgets`.
+
+## Locks left by a dead process
+
+Testkit runs, database work, and Node toolchain installs take locks that other
+Testkit processes on the host respect. A process that dies while it holds or
+waits for one of these locks leaves a claim behind, and the next process to find
+the claim removes it. When several processes found the same dead claim, each of
+them deleted it. On Windows, a process could get `EPERM` while another was still
+deleting the claim, and its command failed
+([gfdelarue/testkit#255](https://github.com/gfdelarue/testkit/issues/255)).
+
+A process now renames a dead claim out of the lock directory before it deletes
+it, and only the process whose rename succeeds deletes the claim. The others
+treat the claim as gone. Two ordinary renames of one directory can both succeed
+on Windows, so there Testkit's Windows helper makes the rename through a handle
+that keeps every other process from renaming or deleting the claim until the
+move is done. A permission error still fails the command. On Windows, another
+process reading the claim can block the rename for a moment, so Testkit retries
+it for up to about ten seconds first. A process that dies
+between the rename and the deletion leaves a `<lock>.dir.reclaiming-<id>`
+directory next to the lock. It no longer affects the lock, and you can delete
+it.
+
+## Windows locks wait out a briefly held file
+
+On Windows, an antivirus scanner, an indexer, or another Testkit process
+checking a lock can hold a lock file open for a moment. Releasing a lock, and
+creating or removing a lock's directory, failed on the first such `EPERM`,
+`EBUSY` or `EACCES` error
+([gfdelarue/testkit#270](https://github.com/gfdelarue/testkit/issues/270)).
+A failed release left the lock held until its process exited, so in a
+long-running process every later wait for that lock timed out. A new
+acquisition also failed while the previous lock directory was still being
+deleted.
+
+These steps now retry for about one and a half seconds on those errors and
+throw if the error persists. Release still refuses to remove a lock whose owner
+or ticket has changed, and on Windows it checks that again before every
+attempt. It then moves the claim out of the lock directory before deleting it,
+so a process that dies in between leaves a `<lock>.dir.releasing-<id>`
+directory that no longer affects the lock and that you can delete. Linux and
+macOS behave as before.
+
+## Database bindings stay in memory
+
+Testkit used to write each runtime database's URL to a `database_url` file in
+the runtime's state directory, then read the file back for `runtime.prepare`
+steps, service processes, `{db*}` placeholders, and test values. Each runtime
+instance now keeps the binding that provisioning returns and passes it to those
+consumers directly
+([gfdelarue/testkit#140](https://github.com/gfdelarue/testkit/issues/140)).
+
+- `databaseFrom` now supplies a database. A service with
+  `databaseFrom: "api"` gets `api`'s database from the same runtime instance as
+  `DATABASE_URL`, in `{dbUrl}` and the other database placeholders, and in its
+  `runtime.prepare` steps and fingerprint. It used to get no database at all.
+  The named service must provision its database in the same runtime, so list it
+  in `dependsOn`. Otherwise the run fails with an error that says so.
+- Testkit no longer writes `database_url` or `local_template_database_name` to
+  runtime state directories under `.testkit/_graphs`, and ignores copies that
+  an earlier version left there. A script that read `database_url` should read
+  `DATABASE_URL` or a `{dbUrl}` env value instead.
+- A database template counts as cached only after its rebuild finishes.
+  Testkit removes the template's cached fingerprint before a rebuild and writes
+  it again at the end. If a process was killed during a rebuild, the old
+  fingerprint used to stay next to a partly built template, and the next run
+  cloned that template.
+
+## A file with setup runs in its own acquisition
+
+Testkit now runs a file's `.setup.mjs`, `.setup.js`, or `__setup__` module as
+part of preparing the file's environment, after it acquires the services the
+group uses. Setup still runs once per file, shares the file's deadline, and
+keeps its sidecars until the test finishes. Cleanup failures keep their
+classification: a consumer cleanup error fails the test, and a Testkit cleanup
+error is an infrastructure failure.
+
+A Playwright file with setup no longer shares a batch with other Playwright
+files of its group. It gets an acquisition of its own, as a file with locks
+does. Files without setup still batch.
+In `run.json`, such a file has no `runtimeBatch`.
+
+## Handles: an HTTP capture by name
+
+Tests can now use an HTTP capture that their file's setup module started,
+through `handle(name)` from `@gfdelarue/testkit/environment`. A capture's
+handle is named after its `id` and has `url`, `requests()`, and `reset()`, and
+both methods return Promises. A run on supplied values gets the same handle
+from an `http-capture` entry under `handles` in its environment file. See
+[Handles](../README.md#handles).
+
+- A capture's `requestsUrl` and `resetUrl` now hold an unguessable segment,
+  `/__testkit__/<capability>/requests`, which Testkit keeps out of the run's
+  results, artifacts, and events. Setups that hand those URLs to their tests
+  keep working. A request to any other `/__testkit__/` path gets `404`, and a
+  method other than `GET` or `DELETE` on the requests URL gets `405`. The old
+  fixed `/__testkit__/requests` path no longer answers.
+- A capture `path` may not start with `/__testkit__/`.
+- A missing handle ends the test as an infrastructure failure, like a missing
+  endpoint or database. A name that several captures share throws
+  `EnvironmentHandleAmbiguousError`. A refused, unavailable, invalid, or
+  unsupported handle throws `EnvironmentHandleError` with that `reason`.
+
+## Named endpoints and databases
+
+Tests can read each used service's URL and database by name from the new
+`@gfdelarue/testkit/environment` module:
+
+```ts
+import { database, endpoint } from "@gfdelarue/testkit/environment";
+
+const api = endpoint("api");
+const reports = database("reports");
+```
+
+- `endpoint(name)` returns the URL of the service `name` that the test's group
+  uses, and `database(name)` returns that service's database URL. A service's
+  database is the one Testkit provisions for it, or the `DATABASE_URL` its
+  `env` declares.
+- The functions work in node-vitest and Playwright files and in the modules
+  they import. Testkit installs the values before the test file and the
+  product code it imports load, 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`. Its `kind` is
+  `"endpoint"` or `"database"`, `valueName` is the name asked for, or `null`
+  when the missing value is the run's default URL, and `available` lists the
+  names the run provides. Outside a Testkit run every call throws it.
+- A test that fails on `EnvironmentValueMissingError`, or a file whose imports
+  throw it, now ends as an infrastructure failure, not a test failure, in
+  node-vitest and Playwright. Its failure key is
+  `TESTKIT_ENVIRONMENT_VALUE_MISSING`. The run fails, and `testkit bug file`
+  refuses to file it, as it does for a server that never became ready. A test
+  that catches the error and carries on is unaffected, and a failed query, a
+  failed assertion against a reachable service, or a refused connection stays
+  a test failure.
+- 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` stay. They hold the endpoint and database of the
+  first service in `uses` that has one. Playwright's `BASE_URL` and `baseURL`
+  keep their canonical form, so an origin ends with `/`. `endpoint()` returns
+  the URL unchanged in every engine.
+- `readPlaywrightContext()` gains `databases`.
+- `testkit.config.ts` and lifecycle step modules cannot import the module.
+
+## Source schema credentials stay out of tests
+
+Testkit kept `TESTKIT_SCHEMA_SOURCE_DATABASE_URL` and the service's own
+`TESTKIT_<SERVICE>_SCHEMA_SOURCE_DATABASE_URL` out of the values it gives a
+group's tests. A name chosen with `database.schema.fromEnv()`, or another
+service's `TESTKIT_<SERVICE>_SCHEMA_SOURCE_DATABASE_URL`, still reached tests
+when a used service's `env` set it, so tests could receive a source database
+URL, often a production database. Tests no longer receive a value under any
+name that the source schema of a service in their runtime reads, whichever
+service sets it
+([gfdelarue/testkit#279](https://github.com/gfdelarue/testkit/issues/279)).
+
+## A suite selector's type is the text before its colon
+
+The text before the first colon of a suite selector is now always the test
+type ([gfdelarue/testkit#283](https://github.com/gfdelarue/testkit/issues/283)).
+A selector such as `Int:auth` or `v2-api:auth` used to name a plain suite with
+that whole name. It now fails with `Unknown suite selector type`.
+
+## A shared database keeps its rows when another runtime instance starts
+
+With `binding: "shared"`, every runtime instance of a service uses one
+database. Testkit reset that database each time it set up an instance, and a
+run sets up an instance the first time a test needs it. An instance set up
+partway through a run dropped the shared database while tests on other
+instances were using it
+([gfdelarue/testkit#284](https://github.com/gfdelarue/testkit/issues/284)).
+Postgres terminated their connections, and their rows disappeared.
+
+Testkit now resets a shared database once per run, when the first instance sets
+it up. Later instances use it as it is, and so does an instance that Testkit
+sets up again after a failure. If the database no longer exists, the instance
+clones it again from the template. `reset: false` and the default `per-runtime`
+binding behave as before.
+
+## `resetBefore` gives a file its own database
+
+`runtimeIsolation` accepted `shared`, `resetBefore`, `resetAfter`, and
+`exclusive`, but only batching read it. `resetBefore` and `resetAfter` reset
+nothing, and `exclusive` didn't keep other files off the runtime
+([gfdelarue/testkit#281](https://github.com/gfdelarue/testkit/issues/281)).
+
+`resetBefore` now works. Before the file runs, Testkit clones each database it
+provisions that the file's environment reaches, from the template that database
+came from. That includes a database a used service names in its env, such as
+`{dbUrl:audit}`. The file's
+`.setup.*` module, `database()`, `DATABASE_URL`, and `{dbUrl}`-style values in
+the group's service env point at the clone, and Testkit drops it when the file
+finishes. A clone took 0.1–0.15 s from an empty template and about 0.35 s from
+a 117 MB one, on Linux and on the Windows CI runner. Use it for a test that
+changes a whole table, such as an unfiltered `DELETE` or a migration test.
+
+Running services keep the runtime's database, so `resetBefore` isolates only
+the test's own database access. A request the test sends to an API server
+still reads and writes the shared database. When the server's writes must be
+isolated too, give the test its own group whose `uses` names a second service
+entry for the same server. Groups that use the same services share their
+runtimes.
+
+A `resetBefore` file on supplied values, or whose environment reaches no
+database Testkit provisions, ends as an environment failure.
+
+`resetAfter` and `exclusive` are removed. A config or `defineFile` that sets
+either fails to load with a message that names the replacement: `resetBefore`
+on the file that needs a clean database, or `shared` with tests that create
+and filter by their own rows. This is a breaking removal.
+
+## Run tests against supplied values
+
+`testkit run` takes `--base-url`, `--endpoint NAME=URL`, `--database NAME=URL`,
+`--env NAME=VALUE`, `--env-from NAME=HOST_KEY`, and `--environment-file PATH`
+([gfdelarue/testkit#235](https://github.com/gfdelarue/testkit/issues/235)).
+With any of them, every selected group runs on the supplied values. Testkit
+starts none of its services, creates no database, and runs no `.setup.*`
+module, and the group keeps its name, selection, and policy. Tests read named
+endpoints and databases through `@gfdelarue/testkit/environment`. The environment
+file is versioned JSON holding values, the setup data tests receive, and handle
+descriptors. Conflicting values, a missing `--env-from` host variable, and an
+invalid or unknown-version file fail before the run starts.
+
+Before a test receives a supplied endpoint, Testkit checks that it answers
+HTTP, for up to 30 seconds. Any response counts, including a 404 or 500. An
+endpoint that refuses connections or never answers HTTP ends the run as an
+infrastructure failure.
+
+Before a test receives a supplied database, Testkit connects to it, signs in,
+and runs `SELECT 1`. A database that is unreachable, fails TLS, rejects the
+credentials, does not exist, or is not PostgreSQL ends the run as an
+infrastructure failure, so `testkit bug file` refuses it. Without the check,
+the test ran and failed on the connection error, which read as a product bug.
+The check speaks the PostgreSQL protocol itself, with trust, password, md5, and
+SCRAM-SHA-256 authentication, TLS from `sslmode`, and Unix sockets through
+`host=/path`.
+[Run against a supplied environment](../README.md#run-against-a-supplied-environment)
+describes the flags and the file.
+
+`testkit bug file` takes the same flags and reruns the recorded test on them.
+The issue's reproduce command carries `--base-url`, `--endpoint`, `--env-from`,
+and `--environment-file` as given. `testkit bug file` refuses `--database`,
+`--env`, and URLs with credentials, a query, or a fragment, so the command never
+holds a raw secret.
+
+## A file reads the same values from every source
+
+A file now gets the same names and setup data whether the run starts its
+services or takes supplied values
+([gfdelarue/testkit#326](https://github.com/gfdelarue/testkit/issues/326)):
+
+- A group's default endpoint and database are available by the group's name in
+  a configured run too. For a group `checks` that uses `api`,
+  `endpoint("checks")` used to throw `EnvironmentValueMissingError` unless the
+  values were supplied. Supplied values now also name a default taken from
+  `uses` after the group, not only an explicit one such as `--base-url`.
+- A run refuses a group whose default differs from a used service's endpoint or
+  database with the group's name, such as a group `api` with
+  `uses: ["web", "api"]`. From either source, that group's files end as an
+  infrastructure failure that names the group, and other groups still run,
+  including groups that use the same services. A supplied run used to fail
+  before it started. Rename the group, or list the service of that name first
+  in `uses`.
+- Each acquisition in `run.json` records `setupData`: the supplied setup data or
+  what the file's setup module returned, and `{}` without either, which is what
+  tests already received. A configured acquisition used to leave it out.
+- A configured acquisition no longer records a service's `BASE_URL` env value
+  under `env`. Tests never received it there, because every engine sets
+  `BASE_URL` from the group's default endpoint.
+
+So an acquisition's recorded `values`, with `"version": 1` added, work as an
+`--environment-file` that gives a second run the same values.
+
+## Sealed runs redact the secrets a run's environment resolved
+
+Sealing took the secrets it redacts from the environment Testkit runs in. A
+value that reached a service or a test from `.env.testkit`, another env file,
+config `env`, or `local.env` stayed in the sealed run whenever a server log, a
+test's output, or an assertion message printed it
+([gfdelarue/testkit#186](https://github.com/gfdelarue/testkit/issues/186)).
+Values from `--env`, `--env-from`, and `--environment-file` had the same gap.
+
+A run now keeps, in memory, the values its environment resolves for each
+service, dependency services included, and for supplied input. Sealing redacts
+each value at least eight characters long under a key that holds `PASSWORD`,
+`TOKEN`, `SECRET`, `PRIVATE_KEY`, `AUTH`, `COOKIE`, `SESSION`, or `API_KEY`,
+and the password of each resolved URL. A configured run and a supplied run that
+print the same secrets seal the same redactions. Testkit takes a runtime's
+values before it prepares the runtime's database, and adds the values that
+depend on the database once it is ready, so a failed database seed, a run
+stopped during startup and a server that never becomes ready are redacted too.
+
+- Sealing also redacts a value's JSON-escaped forms, each line of a value that
+  spans lines, keys in the free-form data and metadata that tests attach, and
+  the part of a secret that output shows before a `…` or `...` cut.
+- `testkit run --json` and the run's progress output apply the same redaction.
+  They used to show unredacted test results.
+- When a run's process is killed before it seals the run, the process that
+  seals it later does not have these values. It redacts patterns and its own
+  environment only, and the bundle's `archive.redaction.status` reads
+  `source-targets-unavailable` instead of `applied`.
+- A secret under another key name, such as `STRIPE_SK`, counts when `redact`
+  names its key. Sealing still does not look inside compressed files such as
+  Playwright traces
+  ([gfdelarue/testkit#187](https://github.com/gfdelarue/testkit/issues/187)).
+
+## Stored run results redact whole secrets
+
+Sealing redacted a `KEY=value` secret only up to its first space, and left
+header and JSON string secrets whole. A test title such as
+`rejects PASSWORD="first-part example-secret" with 401` was stored as
+`rejects PASSWORD=<redacted> example-secret" with 401`, in `run.json`,
+`latest.json`, and the run's JSON artifacts
+([gfdelarue/testkit#213](https://github.com/gfdelarue/testkit/issues/213)).
+
+Sealing, the run's returned result and progress output, and error messages now
+use the rules `testkit bug file` uses, which `docs/bug-records.md` describes. A
+quoted value ends at its closing quote and is written as `"<redacted>"`, so
+redacting the text again changes nothing. Filed issues and CI reports show it
+the same way. A value that starts with an auth scheme such as `Bearer` ends
+with its line, and `Authorization`, `Proxy-Authorization`, `Cookie`, and
+`Set-Cookie` header values and JSON string values under a secret's key are
+redacted, also when the key is spelled with escapes such as `"\u0074oken"`. A
+single-quoted `'password': '…'` value, which only error messages redacted
+before, is redacted by the same rules, and it ends at the next apostrophe that
+no backslash precedes. A value that starts with `\"` or `\'`, as a quoted
+value does inside a JSON string, ends at the matching escaped quote. Sealing
+reads JSON value by value: a JSON artifact, a log line from its first `{` or
+`[`, and a string that holds JSON. It redacts each decoded string, redacts a
+string member under a secret's key, and rewrites only the strings it changes,
+so a secret in one value leaves the record's other values, and numbers, spacing
+and line endings keep their exact bytes.
+
+## Name more secret keys with `redact`
+
+A secret under a key that holds none of `PASSWORD`, `TOKEN`, `SECRET`,
+`PRIVATE_KEY`, `AUTH`, `COOKIE`, `SESSION`, or `API_KEY`, such as `STRIPE_SK`,
+stayed in a sealed run unless it was a URL's password
+([gfdelarue/testkit#186](https://github.com/gfdelarue/testkit/issues/186)).
+
+`redact` in `testkit.config.ts` names more keys:
+
+```ts
+export default defineConfig({
+  redact: ["STRIPE_SK", "PGPASS"],
+});
+```
+
+Testkit matches the names in any letter case. A value under one counts the way
+a value under a built-in key does, from every source a run's environment
+resolves and from the environment Testkit runs in, in a configured run and a
+supplied run alike. It counts when it is at least eight characters long. A
+resolved value that is a URL counts only for its password; in the environment
+Testkit runs in, it counts whole and for its password. The bundle's
+`sensitiveEnvironmentKeys` lists such a key when the environment Testkit runs
+in holds it. `redact` doesn't add text forms: `STRIPE_SK=…` in a log is redacted
+when its value is one Testkit resolved. A config whose `redact` isn't a list of
+non-empty strings fails to load, and the message names the entry.
+
+## A PostgreSQL URL's query password is redacted
+
+libpq also reads a password from the URL's query string, as in
+`postgres://db.internal/app?password=…`. Sealing treated only a password before
+the `@` as a resolved secret, so a test that printed that password on its own
+left it in the sealed run. A `postgres://` or `postgresql://` URL's `password`
+query parameter now counts as the URL's password, both raw and percent-decoded.
+
+## Retention keeps the objects that every stored run lists
+
+Retention, and the cleanup after a failed seal, free the stored objects under
+`.testkit/results/objects` that no run bundle lists. They used to count only the
+bundles whose `run.json` this Testkit could read, so an object that only an
+unreadable bundle listed was freed. The bundle's own files stayed readable, but
+the object store no longer held what its manifest named.
+
+- An object is now kept while any bundle's `manifest.json` lists it, whether or
+  not Testkit can read that bundle's `run.json`.
+- While a bundle has no readable manifest, retention frees no object. Its
+  decision records `garbageCollection.status: "not_started"` and names the
+  bundle, and the decision's status is `failed`.
+
+## Run documents are schema 20
+
+`run.json`, `latest.json` and `live.json` move from schema 19 to schema 20.
+Each field that named the service owning a test now names its group, and the
+facts that depend on how the environment was provided move into one
+`environment` record. Testkit still reads schema-19 runs stored by 0.4.x through
+`testkit artifacts`, `ci report`, known-failure checks and the workspace API,
+and finalizes a 0.4.x `live.json` as schema 19.
+
+Renamed fields:
+
+| Schema 19                       | Schema 20                     |
+| ------------------------------- | ----------------------------- |
+| `services`                      | `groups`                      |
+| `summary.services`              | `summary.groups`              |
+| `summary.diagnostics[].service` | `summary.diagnostics[].group` |
+| `run.serviceFilter`             | `run.groupFilter`             |
+| `planning.tasks[].service`      | `planning.tasks[].group`      |
+
+Moved into `environment`:
+
+| Schema 19                  | Schema 20                              |
+| -------------------------- | -------------------------------------- |
+| `run.runtimeInstanceCount` | `environment.capacity.instanceCount`   |
+| `run.runtimeStats`         | `environment.capacity.runtimeStats`    |
+| `planning.resourceBudgets` | `environment.capacity.resourceBudgets` |
+| `run.dbBackend`            | `environment.dbBackend`                |
+| `services[].dbBackend`     | `environment.groups[].dbBackend`       |
+| `environment.services`     | `environment.services` (unchanged)     |
+| `logs`                     | `environment.logs`                     |
+| `setup.operations`         | `environment.setupOperations`          |
+
+`environment` also gains these fields:
+
+- `acquisitions`: one entry for each environment the run acquired. It records:
+  - the source that prepared it: `configured`, `static`, `supplied` or `none`;
+  - the tasks it served, its runtime and services;
+  - each file's setup;
+  - its release outcome;
+  - its timings, as ISO times;
+  - the values its tests received, in the `--environment-file` shape with
+    secrets and capture capabilities redacted.
+- `cleanup`: the run's cleanup outcome.
+- `missingValues`: the named values tests asked for that their environment
+  lacked.
+
+The same rename reaches the run's other outputs:
+
+- `--output-mode events`:
+  - `run.service_plans` is now `run.group_plans`, with `groups[].group`.
+  - `run.service_skipped` is now `run.group_skipped`, with `group`.
+  - `run.task_planned_skip`, `run.task_started`, `run.task_finished` and
+    `run.runtime_error` carry `group` instead of `service`.
+  - `run.summary` results no longer carry `dbBackend`.
+  - Events about a real service keep `service`: `run.local_service_starting`,
+    `run.toolchain_resolved` and `run.setup_finished`.
+- The run summary reads `groups N/M passed` and `N/M groups failed`.
+- `testkit run --json` prints the schema-20 `runArtifact`. Its `results` no
+  longer carry `dbBackend`.
+- `testkit artifacts --json` names each artifact's `group` instead of its
+  `service`.
+- In `@gfdelarue/testkit/workspace`:
+  - `loadRunBundleArtifact`, `latestRunArtifact` and `liveRunArtifact` return a
+    schema-19 or schema-20 document.
+  - A run summary counts `groups` instead of `services`.
+
+A run bundle's `provenance.json` keeps its `scenario.serviceFilter` field, which
+now holds the group filter. The `--service` flag still selects a group.
+
+## One declaration file per entry point
+
+Each public entry point now has one bundled declaration file under
+`dist/types/`, and the package ships 14 of its own `.d.ts` files instead of
+the 483 that 0.4.5 shipped. The root `types` field and each export's `types`
+condition point at the bundles. A bundle exports the entry point's own names
+and every interface and type alias its public signatures use, so types that
+consumers received but could not import, such as `DataEvidence` or
+`RunBundleManifest`, now have importable names. Public signatures no longer
+name internal types:
+
+- `@gfdelarue/testkit/playwright`: `EngineJsonObject`, `EngineJsonValue` and
+  `EngineJsonPrimitive` are now `JsonObject`, `JsonValue` and `JsonPrimitive`.
+- `@gfdelarue/testkit/config/database-steps`: `DatabaseStepContext` no longer
+  has `ownedContainer`, which Testkit supplies itself.
+- `@gfdelarue/testkit/workspace`: a run bundle's `archive.retention` is typed
+  as `RunBundleRetentionSummary`, with its status, time, policy and error. The
+  stored block still holds the garbage collection and removal details.
+  `WorkspaceServiceStatus` and `WorkspaceRuntimeGraphStatus` type `product`,
+  `caches` and `desired` directly instead of through the internal status model.
+- `__testkitRegisterNodeVitestRepositoryConfiguration` is no longer declared.
+  It remains a runtime export for Testkit's generated setup modules.
+- `UnknownRecord` is gone; the signatures that used it say
+  `Record<string, unknown>`.
+
+A project that referenced a declaration file by its path under `dist/` must
+import the package subpath instead. See
+[gfdelarue/testkit#214](https://github.com/gfdelarue/testkit/issues/214).
+
+## Engine documentation in the package
+
+The package ships `docs/engines.md` in place of `docs/engine-architecture.md`.
+`docs/engines.md` covers engine authoring, typechecking, the environment a test
+receives, Playwright attachments, installation, and the supported platforms.
+The README and the configuration reference no longer describe Testkit's
+internals, and every relative link in the shipped docs resolves inside the
+package ([gfdelarue/testkit#214](https://github.com/gfdelarue/testkit/issues/214)).
+
+# 0.4.5
+
+## Service ports come from the OS
+
+Testkit no longer computes service ports. It used to add a fixed stride to
+`local.port`, or to the port in `local.baseUrl`, for each runtime instance and
+graph. Two runs of the same repository on one host computed the same ports and
+collided, whether they were two CI jobs on one runner or two agent worktrees.
+
+- Every service in every runtime instance now gets a port from the OS. Testkit
+  binds `127.0.0.1:0` and the same port on `::1`, holds both until just before
+  it spawns the service, and passes the port as `PORT` and `{port}`.
+- A service that exits before it becomes ready gets a fresh port and starts
+  again, up to three attempts in total. A service that already started and
+  reads the moved service's URL or port restarts with the new value. A retry
+  never gets a port the service already tried. The final error is an
+  infrastructure failure that lists each attempt's port and outcome and the last
+  attempt's output.
+- `run.json` gains `environment.services`: each service's `runtimeLabel`,
+  `serviceName`, `baseUrl`, `readyUrl`, `port`, and every start attempt, recorded
+  as it happens, including those of a startup that fails. Recorded URLs drop
+  credentials, query values, and fragments.
+- The prepare fingerprint now covers the environment that `runtime.prepare`
+  steps see, with its templates resolved, instead of the raw env templates and
+  the service's `start`, `baseUrl`, and `readyUrl`. A prepare step that embeds a
+  service URL or port rebuilds on every run.
+
+This breaks existing configs:
+
+- `local.port` and the `port` option of `app.node` and `app.next` are config
+  errors. Delete them and use `{port}` in `start`, `baseUrl`, and `readyUrl`.
+- A literal port in `local.baseUrl` or `local.readyUrl` is a config error, and
+  `local.baseUrl` must contain `{port}`. `app.node` and `app.next` already
+  default to `http://127.0.0.1:{port}`.
+- A literal URL in another service's env no longer follows that service's port.
+  Use `{baseUrl:<service>}` or `{port:<service>}`.
+- There is no setting that pins a service to a fixed port.
+
+## Stopped Windows commands
+
+On Windows, a cancelled or timed-out command now waits up to four seconds for
+its process tree to exit before it returns. It used to return as soon as its
+root process exited. The Playwright adapter then removed Chromium's profile
+while terminated browser processes still held it, and the run failed with
+`EBUSY` ([gfdelarue/testkit#205](https://github.com/gfdelarue/testkit/issues/205)).
+A terminated process on a loaded host can take longer than four seconds to
+exit. The command then returns a termination error that names the process, and
+the run can still end in an infrastructure failure. A process in the tree that
+Testkit cannot open or terminate is reported the same way, and so is a process
+whose parent exited before Testkit could confirm that it belongs to the tree.
+Testkit leaves both running. Once termination fails, the command returns
+without waiting for output that a surviving process holds open. It then
+terminates only the root, through the process handle Node opened when it
+started it. It no longer starts `taskkill` against the root's process id,
+which another process may have reused.
+
+`testkit stop` now gives a Windows run its five-second finalization window
+before it forces the run, as it does on POSIX. It used to force a Windows run
+as soon as the two-second grace ended, and the run exited with code 1.
+
+## Baseline-relative data budgets removed
+
+`relativeToBaseline()` is removed from the metric budgets that `budget(name)`
+and `expectMetric(name)` return in `@gfdelarue/testkit/node-vitest/data`. The
+`DataBaselineBudgetOptions` type is removed with it. Nothing compared the
+metric with the named run, so these budgets always reported passed. A scenario
+that still calls `relativeToBaseline()` fails with a `TypeError`, and
+TypeScript reports the missing method. Use `atMost`, `atLeast`, `lessThan`,
+`greaterThan`, or `equals` with a fixed value instead.
+
+Budget records in `data-flow.json` no longer have the `baseline_relative`
+operator or the `policy` and `thresholdVersion` fields. This is a breaking
+removal. See [gfdelarue/testkit#224](https://github.com/gfdelarue/testkit/issues/224).
+
+## `createDataTrace()` removed
+
+`createDataTrace()` is removed from `@gfdelarue/testkit/node-vitest/data`. The
+context it returned never reached the run's report, so its metrics, evidence,
+and findings were lost, and its budgets were never checked. A failing budget on
+a trace passed. Record data inside `dataScenario()` and use the context it
+passes to the callback. This is a breaking removal. See
+[gfdelarue/testkit#242](https://github.com/gfdelarue/testkit/issues/242).
+
+## Bug records: optional `testType`
+
+For tools that read the facts block in Testkit's issues:
+
+- `testType` may be absent. Testkit writes it when the test file's name gives a
+  type, and a later release files bugs for test files whose names give none.
+  Read a version 1 block without `testType` as valid. The format version stays
+  `1`.
+- Every type that a Testkit release has written stays readable: `ui`, `e2e`,
+  `int`, `contract`, `data`, `dal`, and `load`. Issues keep the type they were
+  filed with, so a reader keeps a type after Testkit stops writing it.
+- `"testType": null` is invalid, as for every other optional field.
+
+This release still writes `testType` on every issue it files.
+
+Four category texts no longer assume the product is a server. They are the
+boundary rules of the `missing-validation` cause and the `workflow-breakdown`
+impact, and the definition and boundary rule of the
+`availability-or-performance` impact. Every id and every list's order is
+unchanged.
+
+## Tests that need nothing run with zero setup
+
+Testkit no longer starts a server that `testkit.config.ts` does not declare, so
+a config that relied on an inferred server breaks. Before, a service without
+`local` got `{bin:next} dev -p {port}` when its directory had a `next.config.*`
+file, `go run ./cmd/server` when it had `cmd/server/`, and
+`{bin:tsx} watch src/index.ts` when it had `package.json` and `src/`. A repo
+with no config got the same server for its implicit `app` owner. Loading a
+config also failed when a suite's type expected a server that Testkit could not
+resolve. Both are gone. To keep a server that Testkit used to infer, declare
+it, for example `services: { app: app.node({ entry: "src/index.ts" }) }`.
+
+- An owner that declares no `local`, `database`, `databaseFrom`, `dependsOn`,
+  `runtime.build`, `runtime.prepare` step, `runtime.toolchain`, or env values
+  gets no setup. Its tasks reserve no port, claim no runtime slot, run no
+  `testkit.runtime.ensure`, and write nothing under `.testkit/_graphs`. A run
+  made only of such tasks records no `environment.services` and does no
+  Postgres or Docker maintenance.
+- With no config, the implicit `app` owner loads no `.env` or `.env.testkit`
+  file. A service in `testkit.config.ts` still loads them.
+- Only `data` tests import `testkit.config.ts` in the test process, for their
+  HTTP profiles. In other Node/Vitest tests, `getRepoConfig()` returns `null`.
+- `testkit status`, `doctor`, `typecheck`, and `destroy` work in a repo whose
+  owners declare nothing. `destroy` lists Docker containers only when a service
+  declares a database or local database state exists.
+
+## A test's type no longer decides its setup or its values
+
+A task now gets everything its service declares, whatever its test type. A
+`dal` task used to get its service's database, `runtime.build` and
+`runtime.prepare` steps, and toolchain, but not the server in `local`. That
+server now starts for `dal` tasks too, and Testkit waits for its `readyUrl`
+before the test runs. If the server fails to start, the `dal` task ends with an
+infrastructure failure. A service that declares only a database still starts no
+server.
+
+Every task gets `BASE_URL` when its service has a URL and `DATABASE_URL` when
+its service has a database, on every engine. Tasks other than k6 `dal` used to
+get `DATABASE_URL` only from declared `env`, and k6 `dal` tasks never got
+`BASE_URL`. The provisioned `DATABASE_URL` replaces one that the service's
+`env` declares.
+
+k6 and Playwright files run without a URL or a database. A file that checks
+constants, or a Playwright test that builds its page with `page.setContent()`,
+passes. A file that reads a value its service does not provide fails where it
+reads it, for example with `BASE_URL env var required` from k6 or
+`Cannot navigate to invalid URL` from `page.goto("/")`. Testkit records these as
+product failures.
+
+Without a URL, a Playwright test gets no `BASE_URL`, and
+`readPlaywrightContext().baseUrl` is `null`. `PlaywrightTestContext.baseUrl` is
+now typed `string | null`. Testkit also leaves `use.baseURL` from your
+`playwright.config.*` in place. With a URL, Testkit's `use.baseURL` still
+replaces yours.
+
+`dal` files of one service now run at the same time. Every `dal` task used to
+take a `database:<service>` lock. The lock kept two `dal` files of one service
+from overlapping, but not a `dal` file and another test on the same database. If
+two files share rows that one of them changes, give both the same `locks` entry
+in `defineFile`.
+
+## Test runs
+
+- `--file-timeout-seconds` now sets each file's timeout. Testkit used to record
+  the flag's value in the results and run each file under the timeout from
+  `testkit.config.ts` (#212).
+- A task's lease directory, `TESTKIT_LEASE_DIR`, is now under
+  `.testkit/_execution/leases/`. Engine workspaces and the compilation cache
+  are under `.testkit/_execution/node_modules/testkit-engine/`. Testkit removes
+  them when the task or the run ends.
+- Test processes no longer get `TESTKIT_RUNTIME_ID`. The lease ID still
+  identifies each task. Setup steps and servers that Testkit starts still get
+  `TESTKIT_RUNTIME_ID`.
+
+# 0.4.1
+
+## Bug filing, campaigns, and CI reports
+
+Testkit now files confirmed bugs as issues on GitHub or Gitea and reports runs
+there. None of it needs an account or a server.
+
+- `testkit bug guide` prints the bug record format. `testkit bug record` checks
+  a record and stores a draft. `testkit bug file` runs the recorded test, and
+  files the issue when the test fails.
+- `testkit campaign start`, `status`, and `finish` give a coding agent a target,
+  list what it recorded, and write the summary for the pull request that adds
+  the tests.
+- `testkit ci report` posts the last run as one commit status, the job's step
+  summary, and one pull request comment that it updates in place.
+- `areas` in `testkit.config.ts` maps source paths to the product's areas. Each
+  filed issue gets an `area:<id>` label.
+- `bugs.knownFailures` decides what a filed bug does to a run. The default,
+  `"fail"`, keeps the gate as it was. With `"allow"`, a run passes when an open
+  issue with the `testkit` label covers every failure.
+
+The package now ships `docs/bug-records.md`, the reference for the issue
+format, the facts block, the known-failure rule, the commit status, and the
+pull request comment.
+
+Run results under `.testkit/results/` gain failure details.
+
+- Vitest. An error outside a test is a failure detail of kind `vitest-error`.
+  A file that fails for a reason other than its failed tests keeps its engine
+  failure beside the details of those tests. That reason is a timeout, too much
+  output, a signal, or an exit code other than 1.
+- Playwright. A `playwright-spec` detail's key now holds the names of the
+  `describe` blocks before the spec's title. A spec that fails in a file other
+  than the selected one is a detail of kind `playwright-other-file-spec`. A
+  `PLAYWRIGHT_SPECS_FAILED` failure carries `runStatus`, `failOnFlakyTests`,
+  `reportErrors`, `attachmentFailures`, `evidenceErrors`, and `exitCode` or
+  `exitSignal` in its details.
+- k6. A failed assertion's detail carries `labelled`, which says whether the
+  script gave the assertion a label. Two assertions with one key and two titles
+  are two details. A `K6_THRESHOLDS_FAILED` failure carries `failedChecks` and
+  `exitCode` or `exitSignal`. A `K6_RUNTIME_EXCEPTION` failure carries
+  `summaryRead`, `exitCode` or `exitSignal`, and `phase` when the suite threw
+  during `setup` or `exec`. A script that does not load carries no phase.
+
+A Playwright file whose specs a helper module declares now runs when the helper
+has the file's own extension. Testkit matched a spec to its file by the module
+that called `test()`, so such a file failed with
+`Selected Playwright task did not execute any tests`. A file whose every spec
+comes from one helper with another extension, such as a `.ts` file and a `.js`
+helper, still fails that way. Playwright takes the helper for the file's source
+and leaves the file out of the run.
+
+# 0.4.0
+
+## Testkit Cloud commands removed
+
+This release removes the `testkit cloud` commands, the `cloud` config key, and
+the `docs/cloud-control.md` and `docs/testkit-cloud-boundary.md` references.
+Testkit no longer publishes runs, findings, or campaign reports to Testkit
+Cloud. `testkit cloud` with any arguments now exits with status 2 and an error
+that names this release. The package no longer depends on `undici` or `yazl`.
+
+Testkit ignores a `cloud` key that remains in `testkit.config.ts`.
+`defineConfig` still accepts the key when the config sets other fields, so
+`testkit typecheck` passes. A config object annotated as `TestkitConfig` gets a
+TypeScript unknown-property error. Delete the key.
+
+Run bundles under `.testkit/results/` are unchanged. `testkit run` seals them
+and `testkit artifacts` reads them as before, and `artifacts.publication` still
+copies sealed bundles to a local directory. This is a breaking removal.
+
+# 0.2.7
+
+Playwright body attachments above 768 KiB now retain their bytes and test
+results. Testkit stores attachment bodies in private files and applies the
+existing 64 MiB individual and 256 MiB aggregate limits to body and path
+attachments together. Rejected attachments retain named errors alongside spec
+outcomes, assertion details, and accepted neighboring attachments. Temporary
+attachment files are removed after collection, including failed and cancelled
+runs. Text-secret redaction and binary-secret rejection still apply when sealing
+run evidence.
+
+Fixed in [gfdelarue/testkit#154](https://github.com/gfdelarue/testkit/pull/154).
+
+# 0.2.6
+
+`testkit run --json` now emits one valid JSON document when services or test
+files are skipped. Human progress messages no longer appear before the result.
+Run IDs, exit codes, and structured skip information remain available to CI
+consumers. Compact and debug output retain their existing messages.
+
+Fixed in [gfdelarue/testkit#147](https://github.com/gfdelarue/testkit/pull/147).
+
+# 0.2.5
+
+This release includes the changes merged in
+[gfdelarue/testkit#134](https://github.com/gfdelarue/testkit/pull/134),
+[gfdelarue/testkit#135](https://github.com/gfdelarue/testkit/pull/135), and
+[gfdelarue/testkit#136](https://github.com/gfdelarue/testkit/pull/136).
+Database schema preparation and Docker commands share their existing operations.
+Archive handling removes the unused Tar extraction path and shares accounting
+across the remaining formats.
+
+## Embedded OIDC provider removed
+
+The `auth` config export, including `auth.providers.oidc()`, and the
+`@gfdelarue/testkit/config/oidc-provider` and
+`@gfdelarue/testkit/config/oidc-provider-runtime` subpaths are removed.
+Projects that need a test identity provider must supply one through ordinary
+managed services and configure their applications to use it. Testkit no longer
+implements an identity-provider server.
+
+Consumer-owned API and browser authentication helpers remain supported.
+This is a breaking removal; external package consumers have not been inventoried.
+
+# 0.2.4
+
+The k6 engine now installs from public npm packages. The root manifest pins the
+five `@gfdelarue/testkit-engine-k6-<target>` packages at 1.0.0, and npm selects
+the one matching the host together with the shared
+`@gfdelarue/testkit-engine-k6-source` package. The packages are built and
+published with provenance from
+[gfdelarue/testkit-k6](https://github.com/gfdelarue/testkit-k6) on their own
+version line; the executable remains k6 1.7.1 with xk6-sql. Testkit no longer
+vendors binaries or builds k6, and installing it no longer needs registry
+credentials. The resolver checks the installed package's manifest and probes
+the executable once; a version other than the pinned one fails with
+`TESTKIT_K6_ENGINE_VERSION_MISMATCH`. Installing with `--omit=optional` is
+unsupported. The 0.2.x engine packages are deprecated.
+
+`database.postgres` and `database.fixture` accept `roles`, an array of
+`{ name, login: false }` declarations. Testkit creates these local roles before
+source-schema replay, so imported policies can reference roles absent from a
+fresh cluster. Existing roles must match the ordinary NOLOGIN role contract,
+including on template cache hits. Conflicts stop provisioning without altering
+existing roles. Roles persist until the owned PostgreSQL volume is destroyed.
+This fixes [gfdelarue/testkit#129](https://github.com/gfdelarue/testkit/issues/129).
+
+## `auth.fixture` removed
+
+`@gfdelarue/testkit/config` no longer exports `auth.fixture`, `auth.contracts`,
+`auth.topologies`, or `auth.profile`. `auth.providers.oidc` remains. The
+generated-actor profile descriptors, the `auth-fixture` k6 wire kind, and the
+`__testkitAuthProfile` suite metadata are removed with them. k6 repository
+profiles are JSON-only; a profile that carries a function fails validation.
+
+Move signup, login, and header projection into the k6 suite module or a shared
+`__testkit__/helpers/` module. `defineHttpSuite({ auth: { setup, headers },
+rawHeaders })` keeps the session bundle, `actor`, `actors`, and `req.as(...)`
+runtime. Node/Vitest data profiles keep in-process `auth.setup`,
+`auth.setupAsync`, `headers`, and `rawHeaders` functions on
+`profiles.http.<name>`. Testkit 0.6.0 removed HTTP profiles; see
+[Remove the data test type](#remove-the-data-test-type).
+
+This is a breaking removal. The migrated consumers are the two in-repository
+system fixtures. External consumers of the retired API have not been inventoried.
+
+Local service commands on Windows keep their quoted executable paths and
+arguments, and Testkit creates its temporary directories on Windows even when
+the path exceeds `MAX_PATH`. Sensitive-text redaction runs in linear time on
+long input.
+
+The undocumented `TESTKIT_PSQL_IMAGE` and `TESTKIT_PG_DUMP_IMAGE` aliases and
+the `TESTKIT_OIDC_CONFIG_JSON` override are removed. Use the documented
+`TESTKIT_POSTGRES_CLIENT_IMAGE`; the OIDC provider is configured only through
+the repository configuration. `TESTKIT_CLOUD_URL`, `TESTKIT_SETUP_NODE_OPTIONS`,
+and the Playwright `TESTKIT_FRONTEND_BASE_URL` and `TESTKIT_BACKEND_BASE_URL`
+fallbacks are now documented in the README.
+
+# 0.2.3
+
+Configured commands on Windows preserve quoted paths and arguments when
+invoking `cmd.exe`. TypeScript builds can now write prepared output directories
+without receiving literal quote characters in `--outDir`.
+
+`testkit typecheck` supports consumer TypeScript 5.9.3 and 6.0.2. Generated
+configurations clear the deprecated `baseUrl` option while preserving inherited
+aliases and Testkit's type mappings. This fixes the TS5101 failure reported in
+[gfdelarue/testkit#117](https://github.com/gfdelarue/testkit/issues/117), including
+consumers with a separate frontend compiler.
+
+Database state scans now enumerate only the directories Testkit owns under
+`.testkit` (`_infra/local-postgres`, `_dbcache`, graph runtime services, and
+top-level service directories carrying a `database_backend` marker). Unrelated
+content beneath `.testkit`, such as a consumer virtualenv or the managed Node
+toolchain's own `npm` links, no longer fails run start or resource cleanup with
+`Refusing unsafe Testkit database state symlink`. Container and volume
+references are read only from owned state, so stray files elsewhere no longer
+keep stale resources alive. This addresses
+[gfdelarue/testkit#118](https://github.com/gfdelarue/testkit/issues/118).
+
+Local services accept `local.shutdownTimeoutMs`, a positive finite integer in
+milliseconds that defaults to 1000. `app.node()` and `app.next()` forward the
+same option. On POSIX, shutdown sends SIGTERM immediately and SIGKILL only when
+the allowance expires. Cancellation, repeated stop requests, descendant cleanup,
+and maintenance recovery share the first deadline. Windows retains forceful
+`taskkill /T /F`. This fixes
+[gfdelarue/testkit#116](https://github.com/gfdelarue/testkit/issues/116).
+
+`stop`, `run stop`, active `cleanup`, and `destroy` let the controller finish
+service shutdown before escalating. After SIGINT, they wait at least two
+seconds and until outstanding service deadlines plus three seconds for forced
+termination have elapsed. They then send the controller SIGTERM, allow five
+seconds for finalization, and use SIGKILL if it remains active. A controller
+with no registered services retains the two-second grace and five-second
+finalization windows.
+
+The `.scenario.testkit.ts` category, `defineScenarioSuite()` and `--seed` are
+removed. Use `.e2e.testkit.ts` for product journeys or `.int.testkit.ts` for
+service checks, and replace the scenario choice/resource/step helpers with
+ordinary test code. `defineHttpSuite()` remains available. Native k6
+`options.scenarios`, executors, groups and lifecycle hooks are unchanged.
+
+Discovery ignores the retired suffix, so migrate those files before upgrading;
+a mixed run can still pass using its remaining supported files. Saved scenario
+results remain readable. New run documents omit `scenarioSeed`, and provenance
+omits `scenario.seed` while retaining its generic run-selection fields.
+
+# 0.2.2
+
+PostgreSQL clients for Testkit-owned databases now join the database container's
+network namespace. Template rebuilds, schema checks and snapshots, and database
+steps no longer depend on Docker host networking reaching a published port.
+This addresses the failure reported with Docker Desktop and WSL2 in
+[gfdelarue/testkit#111](https://github.com/gfdelarue/testkit/issues/111).
+External `sourceSchema` database URLs retain their existing routing.
+
+# 0.2.1
+
+This release adds explicit Cloud campaign reporting and optional local
+verification policy. It also includes the configuration changes below.
+Consumers pinned to 0.2.0 keep their existing behavior until they upgrade.
+
+The pinned Vitest version is 4.1.11, which fixes the `@vitest/mocker` path
+traversal advisory GHSA-82fw-gwwq-j7x9.
+
+## Next app Clerk preset
+
+`app.next` no longer accepts an `auth` option. The only value it took,
+`"disabled-clerk"`, set six product-private environment variables and was never
+documented. Put the variables in `env.values` instead:
+
+```ts
+app.next({
+  port: 3000,
+  env: {
+    values: {
+      DISABLE_CLERK_AUTH: "1",
+      NEXT_PUBLIC_DISABLE_CLERK_AUTH: "1",
+      NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY: "",
+      CLERK_PUBLISHABLE_KEY: "",
+      CLERK_SECRET_KEY: "",
+      CLERK_WEBHOOK_SECRET: "",
+    },
+  },
+});
+```
+
+## Fly.io request routing header
+
+The k6 and Node/Vitest HTTP runtimes no longer read `MACHINE_ID` from the
+environment or add a `fly-force-instance-id` header to requests. The Fly.io
+infrastructure was removed earlier and nothing documented the header. The
+`routeParams` field on `RuntimeEnv`, the `routeHeaders` option on the k6
+`createHttpClient`, and the matching positional argument on `makeReq` and
+`makeRawReq` are removed with it. A test that needs a routing header sets it
+through `headers` or `rawHeaders` on its HTTP profile.
+
+## Lint rules are booleans
+
+`testkit lint` no longer has severity levels or ratchet mode. Each rule is
+enabled or disabled, enabled-rule findings fail the command, and results depend
+only on current source. `lint.level` and the rule levels `off`, `warn`,
+`ratchet`, and `strict` are rejected with migration guidance. Replace them with
+`true`, `false`, or `{ enabled: boolean }` alongside the existing `include`,
+`exclude`, `allowed`, and `trackedOnly` options:
+
+```ts
+lint: {
+  rules: {
+    dalParallelSafety: false,
+    unitTestBoundaries: { include: ["src/**/*.test.ts"] },
+  },
+}
+```
+
+Results and `.testkit/lint/latest.json` drop `level`, `severity`,
+`ratchetStatus`, `fingerprint`, `notes`, and the warning and debt counts.
+`base.json` and `ratchet.json` are no longer written. The `TestkitLintLevel`
+type is removed. Unit-test boundary findings now report every source location
+instead of one per file and operation.
+
+## Environment overrides
+
+Three undocumented environment variables are no longer read:
+
+- `TESTKIT_PSQL_IMAGE` and `TESTKIT_PG_DUMP_IMAGE` were aliases for the
+  documented `TESTKIT_POSTGRES_CLIENT_IMAGE`. Rename them.
+- `TESTKIT_OIDC_CONFIG_JSON` let the environment replace the OIDC provider
+  config, including client secrets and users, at launch. Configure the provider
+  explicitly instead. The embedded provider is removed in 0.2.5;
+  see [Embedded OIDC provider removed](#embedded-oidc-provider-removed).
+
+`TESTKIT_CLOUD_URL`, `TESTKIT_SETUP_NODE_OPTIONS`, and the Playwright
+`TESTKIT_FRONTEND_BASE_URL` and `TESTKIT_BACKEND_BASE_URL` fallbacks keep their
+behavior and are now documented in the README and config schema.
+
+## Playwright typecheck support roots
+
+`testkit typecheck` no longer evaluates Playwright configuration or traverses a
+separate dependency/provenance graph. It runs native TypeScript over engine-profiled
+projects. Add `tsconfig.playwright.json` with explicit `files`/`include` entries for
+string-named setup, teardown, reporter, fixture, and support-project modules.
+Discovered UI suites and the selected Playwright config remain implicit roots.
+See the [support-file contract](engines.md#playwright-support-files).
+Managed runtime enforcement remains authoritative; direct import lint feedback
+moves to ESLint under #22.
+
+## Data-profile Vitest imports
+
+Data suites now receive restricted Vitest runtime exports. Native case
+registration is rejected through helpers and aliases as well as direct imports.
+Data imports omit runner classes, Vitest runtime subpaths, and Testkit contract
+registration. A native collection check also rejects cases obtained through
+`import.meta.vitest` or the native global. Assertions, mocks, hooks, and root type-only imports
+remain supported.
+
+`testkit typecheck` reports data suites under `node-vitest-data` and checks them
+separately from contract suites sharing the same tsconfig. Direct-import lint
+feedback remains; managed imports and native collection checks replace
+whole-program provenance analysis.
+
+## UI authentication fixtures
+
+The product-specific UI authentication API is deprecated and removed in the next
+release. Remove `ui.auth(...)` and its authentication configuration from
+`testkit.config.ts`. The provisioning, login, session-storage, authenticated-shell,
+and provisioned-sandbox exports from `@gfdelarue/testkit/playwright` are removed.
+Their identity, session, profile, and sandbox types are removed too.
+
+Move signup, login, SQL seeding, session extraction, local storage, and
+application readiness into your own Playwright fixtures. Use native
+`test.extend`, request contexts, page locators, and browser storage APIs.
+Testkit retains `createUiSandbox`, runtime context, target safety, and settling
+helpers. Put generic `frontendBaseUrl`, `backendBaseUrl`, and `allowRemote`
+settings directly under `ui`, or pass them as sandbox options.
+The separate `auth.fixture` API is removed too; see above.
+
+## Configuration metadata
+
+Auth and Node toolchain builders keep their existing names and options. Their
+returned objects no longer carry the redundant `json-session`, `auth-topology`,
+`testkit-oidc-provider`, or `node` kind fields. Remove reads of those metadata
+fields and omit `kind: "node"` from inline toolchain configuration. The
+`auth.topologies` builders are removed with `auth.fixture` (see above).
+
+Existing database state directories and verified Node toolchain caches remain
+usable. The database state marker keeps its filename and no longer stores a
+backend value. Node toolchain environment variables and cache fingerprints
+retain their existing values.
+
+## Local status and history removal
+
+Testkit now keeps immutable run bundles locally and publishes selected bundles
+explicitly to Testkit Cloud. These flags and outputs are removed:
+
+- `testkit run --write-status` and `--allow-partial-status`. Both are unknown flags.
+- The product-root `testkit.status.json` snapshot and `run` JSON's `statusArtifact` field.
+- `.testkit/history/tests.json`, its per-test counts, durations, timestamps, and last status.
+- Discovery JSON's `history`, `files[].history`, and `summary.latestResults` fields.
+  Compact and verbose discovery output no longer render history or pass rates.
+- Workspace JSON's `history`, `discovery.history`, and
+  `discovery.summary.latestResults` fields. Targets no longer have source `history`;
+  discovery file targets no longer receive a last status from history.
+- Run planning's `tasks[].historyKey` and the `history` estimate source.
+
+Remove the retired flags from scripts. Consumers of a single run should verify
+its bundle at `.testkit/results/runs/<run-id>/`. Consumers of cross-run counts,
+last outcomes, durations, or trends should use Testkit Cloud. The `status`
+command still reports current runtime and process state.
+
+`testkit run` prints the sealed run ID and returns it as `runId` with `--json`,
+including failed runs. Use `testkit cloud publish --run <run-id>` to publish
+that exact bundle. Publication has its own exit status. See the
+[README CI recipe](../README.md) for preserving the test outcome while
+publishing evidence. The newest-bundle default remains available interactively.
+
+Old `.testkit/history/` files are ignored and left untouched. Testkit does not
+migrate their contents. `.testkit/timings.json` and its schema 2 are unchanged.
+Without usable timings, the scheduler uses a default estimate until execution
+records a timing. Existing status files are no longer excluded from repository
+fingerprints; remove them from the product repository if they are obsolete.
+
+Run schema 19, bundle schema 2, provenance schema 3, and retention schema 1 are
+unchanged. Retention still prunes bundles and unreferenced objects but no longer
+appends the write-only `decisions.jsonl` ledger. Legacy ledger metadata in a
+supplied bundle remains readable and validated when present.
+
+Cloud receipts follow the current publication API: `decisionReasons` contains
+`{ ruleId, message }` objects, and `policyId` plus `policyRevision` identify the
+evaluated policy. They replace the client's stale string reasons and
+`policyVersion` fields. Text publication output prints each reason's message.