@gfdelarue/testkit 0.4.5 → 0.6.0

package/testkit-config-schema.md

@@ -12,13 +12,6 @@ export default defineConfig({
     taskConcurrency: 8,
     fileTimeoutSeconds: 60,
   },
-  profiles: {
-    http: {
-      raw: {
-        options: { vus: 1, iterations: 1 },
-      },
-    },
-  },
   toolchains: {
     frontendNode: toolchain.node({
       cwd: "frontend",
@@ -63,42 +56,53 @@ export default defineConfig({
       },
     }),
   },
+  groups: {
+    api: { roots: ["src"], uses: ["api"] },
+    frontend: {
+      roots: ["frontend"],
+      uses: ["frontend", "api"],
+      skip: { suites: [{ selector: "ui:billing", reason: "Billing UI is placeholder-only" }] },
+    },
+  },
 });
 ```
 
-Every test file must declare its execution engine. The same file-local metadata
-may also declare skip and lock intent:
+Every typed test file must declare its execution engine. A plain Vitest test
+file declares nothing and runs under the general `node-vitest` profile. The
+file-local metadata of a typed file may also declare skip and lock intent:
 
 ```ts
 import { defineFile } from "@gfdelarue/testkit";
 
 export const testkit = defineFile({
-  engine: "k6",
+  engine: "node-vitest",
   skip: "Billing is currently unavailable locally",
-  locks: ["global-worker-loop"],
+  locks: ["payments-sandbox-webhook"],
 });
 ```
 
+Files that name the same lock never run at the same time within one run. Use a
+lock only for a resource that can't be duplicated, such as the one webhook URL
+of a sandbox account. Tests that share rows need their own rows, not a lock.
+See [Give each test its own data](README.md#give-each-test-its-own-data).
+
 The engine is intentionally not a `testkit.config.ts` field and is never
 inferred from the filename. `defineFile` comes only from the root package, the
 argument must be a direct object literal, and `engine` must be one of the
-literal values `"k6"`, `"node-vitest"`, or `"playwright"`.
+literal values `"node-vitest"` or `"playwright"`.
 
-The filename suffix determines the test type, and the engine catalog resolves
-the pair to exactly one runner profile:
+The filename suffix determines the test type, and each engine and test type
+pair runs under exactly one runner profile:
 
-| Test type            | Engine        | Profile                |
-| -------------------- | ------------- | ---------------------- |
-| `int`, `e2e`, `load` | `k6`          | `k6-http`              |
-| `dal`                | `k6`          | `k6-dal`               |
-| `data`               | `node-vitest` | `node-vitest-data`     |
-| `contract`           | `node-vitest` | `node-vitest-contract` |
-| `ui`                 | `playwright`  | `playwright-ui`        |
+| Test type          | Engine        | Profile         |
+| ------------------ | ------------- | --------------- |
+| none, a plain file | `node-vitest` | `node-vitest`   |
+| `ui`               | `playwright`  | `playwright-ui` |
 
-Missing metadata, dynamic values, and unsupported engine/test-type pairs are
-discovery errors. There is no default-engine or legacy-runner compatibility
-path. See [Engine Architecture](docs/engine-architecture.md) for the managed
-distribution contract.
+For a typed file, missing metadata, dynamic values, and unsupported
+engine/test-type pairs are discovery errors. There is no default-engine or legacy-runner compatibility
+path. See [Installation](docs/engines.md#installation) for what an install
+contains and the supported platforms.
 
 ## Tooling Adapters
 
@@ -115,24 +119,32 @@ runtime-policy modules under `src/` just to cooperate with managed runs.
 
 ## Top-Level Fields
 
+The top-level keys are `areas`, `artifacts`, `bugs`, `discovery`, `execution`,
+`fingerprints`, `groups`, `lint`, `redact`, `services`, `toolchains`, and `ui`.
+Testkit refuses a config with any other top-level key. The error names the key
+and the closest known key when one is close.
+
 ### `execution`
 
 Default execution settings for the repo.
 
-- `taskConcurrency`: maximum concurrent test tasks across the run (default `1`)
+- `taskConcurrency`: maximum concurrent test tasks across the run (default `1`).
+  A typed file, a batch of typed files, or one Vitest invocation of plain files
+  is one task. Plain files in one invocation run with Vitest's file
+  parallelism, which the Vitest config's `fileParallelism` and `maxWorkers`
+  control.
 - `fileTimeoutSeconds`
 
-`execution.workers` and `presets.nodeNext({ workers })` remain deprecated aliases
-through 0.2.x and will be removed in 0.3.0. Use `taskConcurrency` in new config.
-If both names are present, their values must match. The normalized configuration
-contains only `taskConcurrency`.
+`execution.workers` and `presets.nodeNext({ workers })` are deprecated aliases.
+Use `taskConcurrency` in new config.
+If both names are present, their values must match.
 
-`--task-concurrency` overrides the configured value. The CLI alias `--workers`
-also remains available through 0.2.x; contradictory CLI aliases are rejected
-before applying CLI precedence. Contradictory config aliases are rejected even
+`--task-concurrency` overrides the configured value. The deprecated CLI alias
+`--workers` also works; contradictory CLI aliases are rejected before applying
+CLI precedence. Contradictory config aliases are rejected even
 when the CLI supplies an override.
 
-Schema-19 evidence retains its configured `run.workers` field. Observed
+Run documents keep the configured `run.workers` field. Observed
 `workerCount`, Playwright's own `workers`, `runtime.instances` and
 `runtime.maxConcurrentTasks` keep their existing meanings.
 
@@ -144,15 +156,31 @@ helpers like `waitFor()` consume this budget automatically.
 Optional `testkit lint` settings. Omit it to run the default rules.
 
 - `rules`: map of rule name to `true`, `false`, or an options object.
-  `engineImports`, `configImports`, `dataSuiteContract`, `dalParallelSafety`,
-  and `uiSpecShape` default to enabled; `unitTestBoundaries` and
-  `testkitBoundary` default to disabled.
+  `engineImports`, `configImports`, and `uiSpecShape` default to enabled; `unitTestBoundaries` and
+  `testkitBoundary` default to disabled. `dataSuiteContract` was removed in
+  0.6.0, and `testkit lint` rejects a config that sets it.
 - Rule options: `enabled` (default `true`), `include`, `exclude`. `testkitBoundary`
   also accepts `allowed` and `trackedOnly`.
 - `ui`: `maxLines` (default `220`) and `maxTests` (default `8`) for UI suites.
 
 Enabled-rule findings and syntax errors fail the command. There are no severity
-levels. The repository's `docs/lint.md` describes each rule.
+levels. The rules report:
+
+- `engineImports`: a value import the suite's engine can't load, such as Vitest
+  in a UI suite. Type-only imports
+  are allowed.
+- `configImports`: `testkit.config.ts` importing a repo-local `__testkit__`
+  helper module.
+- `uiSpecShape`: a UI suite longer than `ui.maxLines` lines or with more than
+  `ui.maxTests` tests.
+- `unitTestBoundaries`: test doubles, module replacement, `process.env` reads,
+  and network, filesystem, or child-process access in plain `*.test.*` and
+  `*.spec.*` files outside `__testkit__`.
+- `testkitBoundary`: a JavaScript, TypeScript, or JSON file with `testkit`, in
+  any letter case, in its path, other than the root `testkit.config.ts`,
+  `testkit.config.mts`, `testkit.config.mjs`, and `testkit.config.js`, and files
+  under `**/__testkit__/**`. `allowed` replaces that list of globs, and
+  `trackedOnly` limits the rule to files Git tracks.
 
 ### `areas`
 
@@ -204,6 +232,35 @@ Optional settings for bug filing and for runs that meet a filed bug.
 
 [Bug records](docs/bug-records.md) describes the issues Testkit files.
 
+### `redact`
+
+Optional env key names whose values sealing redacts, beyond the keys that hold
+`PASSWORD`, `TOKEN`, `SECRET`, `PRIVATE_KEY`, `AUTH`, `COOKIE`, `SESSION`, or
+`API_KEY`.
+
+```ts
+export default defineConfig({
+  redact: ["STRIPE_SK", "PGPASS"],
+});
+```
+
+- Testkit matches each name in any letter case and trims spaces around it.
+- A value under a named key counts from every source a run's environment
+  resolves (config `env`, env files, `local.env`, dependency services, `--env`,
+  `--env-from`, and an `--environment-file`) and from the environment Testkit
+  runs in. It applies the same way to a configured run and a supplied run.
+- A value 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, such a value counts whole and for its password.
+- `redact` doesn't add text forms. `STRIPE_SK=…` in a log is redacted when its
+  value is one Testkit resolved.
+- An entry that isn't a string, or is empty, fails config loading with a
+  message that names the entry:
+  `testkit.config.ts redact[1] must be a string`.
+
+The sealing section of the [README](README.md) describes what else sealing
+redacts.
+
 ### `ui`
 
 Targets for Playwright `ui` files. Read through `createUiSandbox`,
@@ -222,7 +279,69 @@ runs. The backend falls back to `TESTKIT_BACKEND_BASE_URL` and then
 
 ### `services`
 
-Map of service name to service config.
+Map of service name to service config. A service describes what Testkit can
+start. It owns no test files; [`groups`](#groups) assigns them.
+
+### `groups`
+
+Map of group name to the test files the group owns and the services its tests
+use.
+
+```ts
+groups: {
+  api: { roots: ["services/api"], uses: ["api"] },
+  web: { roots: ["apps/web"], uses: ["web", "api"] },
+}
+```
+
+- `roots`
+  - required non-empty list of repo-relative directories
+  - a file belongs to the group with the deepest root that contains it
+  - two groups with roots at the same depth leave a file ambiguous, and
+    `testkit discover` reports `ambiguous_test`
+- `uses`
+  - ordered list of service names; defaults to `[]`
+  - a run starts these services and their `dependsOn` for the group's files,
+    and starts no other service
+  - when two used services set the same name, such as `BASE_URL`,
+    `DATABASE_URL`, or an `env` entry, the first in `uses` wins
+  - tests read each used service's URL and database by its name with
+    `endpoint()` and `database()` from `@gfdelarue/testkit/environment`
+  - the group's default URL and database are also available by the group's
+    name; a group named after a used service whose value is not the default
+    gets no values, and its files end as an infrastructure failure
+  - a dependency starts but gives the group no values; a used service can pass
+    one on, for example with `{serviceContextUrl:api}` in its `env`
+- `exclude`
+  - repo-relative paths the group does not own; a file that every group
+    containing it excludes is dropped, plain Vitest test files included
+- `skip`, `requirements`
+  - test policy for the group's files, with the shapes described under
+    [Service Fields](#service-fields)
+- `runtimeIsolation`
+  - `shared` or `resetBefore` for the group's files, or an object with a
+    `default` policy and `suites` and `files` rules; see
+    [`runtimeIsolation`](#runtimeisolation)
+
+Files that no group's roots claim belong to the implicit group `root`, which
+uses no service. `root` is reserved. With no `testkit.config.ts`, every file
+belongs to `root`, and `groups: {}` gives every file to `root`.
+
+Testkit assigns no files by a service's `discovery`. With `groups` set, it
+rejects a service's `discovery`, `skip`, `requirements`, or `runtimeIsolation`
+with a message naming the group field to use. The `discovery` that
+`database.fixture()` adds by default is the exception.
+
+#### Configs without `groups`
+
+Before 0.6.0, a config with `services` and no `groups` key gave each service
+the typed `*.testkit.ts` files under its `local.cwd` and `discovery.roots`. Such
+a config now fails to load when a service's directories hold a typed file. The
+error lists a `groups` entry for each of those services, with its `roots`,
+`uses`, and any `exclude`, so the files keep their services. `status`,
+`destroy`, `cleanup`, and `db schema` still run on such a config. A group also
+owns the plain Vitest files under its roots, which a service never did. When no
+service's directories hold a typed file, every file belongs to `root`.
 
 ### `toolchains`
 
@@ -245,12 +364,11 @@ Node toolchain fields:
   - explicit npm version or range
 
 `cwd` must be product-relative and may not contain a parent-directory segment.
-For `install: "download"`, resolution is limited to Testkit's platform-specific
-trusted Node release manifest. Testkit verifies the archive's exact size,
-SHA-256, entry and file counts, unpacked size, and complete installed-tree
-digest before reusing the repo-local `.testkit/_toolchains/node` cache. The
-trusted official Linux archives require glibc; download mode rejects a musl
-host before fetching or creating cache state.
+For `install: "download"`, Testkit downloads only the official Node releases
+it lists for the platform, verifies each download, and caches it under the
+repo-local `.testkit/_toolchains/node`. A cache entry that changed after
+installation fails verification. The official Linux archives require glibc, so
+download mode fails on a musl host before downloading anything.
 
 `detect: "auto"` checks the toolchain cwd for:
 
@@ -263,68 +381,12 @@ host before fetching or creating cache state.
 - `package.json#packageManager`
 - `package.json#engines.npm`
 
-### `profiles.http`
+### `profiles`
 
-Named HTTP profiles. k6 suites reference them by name, and Node/Vitest data
-suites request them through `flow.http({ profile })`.
-
-When a run selects k6, every repository HTTP profile must be JSON-only,
-including profiles used only by Node/Vitest suites. The orchestrator serializes
-the whole collection into a versioned engine input, so any profile containing
-a function fails configuration validation. Put k6 setup and header functions in the suite
-module through `defineHttpSuite({ auth, headers, rawHeaders })`, or in a
-shared `__testkit__/helpers/` module the suites import.
-
-```ts
-profiles: {
-  http: {
-    raw: {
-      options: { vus: 1, iterations: 1 },
-    },
-  },
-}
-
-defineHttpSuite({ profile: "raw" }, ...)
-```
-
-For runs without k6, Node/Vitest data profiles load in-process and may carry `auth`,
-`headers`, and `rawHeaders` functions. `auth.setup` or `auth.setupAsync`
-returns a session bundle of named actors; `headers` maps the bundle and the
-requested actor to request headers.
-
-```ts
-interface SessionBundle {
-  actors: Record<string, { session: { jwt: string } }>;
-  primaryActor: string;
-}
-
-profiles: {
-  http: {
-    default: {
-      auth: {
-        async setupAsync({ env, http }): Promise<SessionBundle> {
-          const login = await http.post(`${env.BASE}/api/v1/auth/login`, body);
-          const jwt = login.cookies?.session?.[0]?.value;
-          if (!jwt) throw new Error("Login response did not set the session cookie");
-          return { actors: { primary: { session: { jwt } } }, primaryActor: "primary" };
-        },
-        headers(setupData): Record<string, string> {
-          const bundle = setupData as SessionBundle | null;
-          return bundle
-            ? { Authorization: `Bearer ${bundle.actors[bundle.primaryActor].session.jwt}` }
-            : {};
-        },
-      },
-    },
-  },
-}
-```
-
-Repository profile setup data is typed as `unknown`. The example gives its
-test-owned setup result a name and uses that type in the corresponding header
-builder. In a repository that also runs k6, keep the named repository profile
-JSON-only and pass the Node functions from the data suite through
-`flow.http({ profile: "default", auth: { setupAsync, headers } })` instead.
+Testkit 0.6.0 removed HTTP profiles. A config that sets `profiles` fails to
+load. A test logs in with `fetch` or its own client against the URL from
+`@gfdelarue/testkit/environment`, as
+[Record data-flow evidence](README.md#record-data-flow-evidence) shows.
 
 ## Service Fields
 
@@ -340,61 +402,74 @@ Local runtime configuration.
 - `shutdownTimeoutMs`
 - `env`
 
+#### Readiness
+
+A local service starts and must then be ready before `readyTimeoutMs` runs out.
+The default is 120000 ms. Tests receive nothing from the service until then.
+
+- With a `readyUrl`, the service is ready when that URL returns a 2xx status,
+  after up to 20 redirects. `app.node` defaults `readyUrl` to `{baseUrl}/health`,
+  and `app.next` defaults it to `baseUrl`.
+- `baseUrl` must also answer HTTP, unless the `readyUrl` has the same origin.
+  Any response counts, including a 4xx or 5xx status. A port that accepts
+  connections but does not answer HTTP does not count.
+- `readyUrl: false` removes the 2xx check. Testkit still waits for `baseUrl` to
+  answer HTTP.
+- A process with no HTTP endpoint, such as a worker or a queue consumer, declares
+  no `baseUrl`. It is ready once it has started. Testkit hands its groups no URL
+  for it, and `{baseUrl:<service>}` fails to resolve.
+
+```ts
+services: {
+  worker: { local: { start: "node worker.mjs" } },
+},
+```
+
+`app.node` and `app.next` always set a `baseUrl`, so declare a process without
+an HTTP endpoint with `local` directly.
+
 `services.<name>.local.shutdownTimeoutMs` is an optional positive finite integer
 in milliseconds. It sets how long a launched local service may take to exit
 after Testkit requests shutdown before Testkit force-kills it. Omitted or
 `undefined` values use the 1000 ms process-launch default. Strings, zero,
 negative numbers, fractions, `NaN`, and infinities are rejected.
 
-On POSIX, Testkit sends SIGTERM immediately and returns as soon as the owned
-process group exits. A surviving root or descendant receives SIGKILL when the
-allowance expires. Repeated stop requests and cancellation reuse the first
-deadline; a root exiting before its descendants does not restart the clock.
-The allowance also applies to cleanup after readiness failure or cancellation
-during startup. It does not change engine, build-command, or database timeouts.
+On POSIX, Testkit asks the service and its descendants to stop, and
+force-kills any that are still running when the allowance expires. Repeated
+stop requests and cancellation keep the first deadline. The allowance also
+applies to cleanup after a readiness failure or a cancellation during startup.
+It doesn't change engine, build-command, or database timeouts.
 
 `stop`, `run stop`, active `cleanup`, and `destroy` wait for the recorded service
-allowances before forcing an unresponsive controller. After SIGINT, the
-controller gets at least two seconds and any remaining service allowance plus
-three seconds for forced termination. It then receives SIGTERM and gets five
-seconds to finalize before SIGKILL. Recovery uses the policy recorded when the
-service launched, including any shutdown time already spent.
-
-On Windows, the current process adapter uses forceful `taskkill /T /F` and
-cannot deliver cooperative SIGTERM. Increasing this option does not give a
-Windows service a graceful cleanup interval. Process ownership checks still
-apply; this option does not guarantee cleanup of detached resources or Compose
-containers.
+allowances before they force an unresponsive run to stop. Recovery uses the
+allowance recorded when the service launched, less any shutdown time already
+spent.
 
 Both `app.node({ shutdownTimeoutMs: 5000 })` and
 `app.next({ shutdownTimeoutMs: 5000 })` place the option under `local`.
 
 #### Ports
 
-Testkit asks the OS for a free port for each service in each runtime instance:
-it binds `127.0.0.1:0`, binds the same port on `::1` when the host has IPv6, and
-holds both sockets until it has resolved the service's toolchain and is about to
-spawn it. Another process cannot take the port while Testkit holds it. The
-remaining gap runs from that release until the service binds the port, which
-includes the service's own startup time. The service receives the port as `PORT` and
-as `{port}`. `baseUrl` must use `{port}`, or `{port:<its own name>}`, as its
-port, for example `http://127.0.0.1:{port}`. `app.node` and `app.next` default to that `baseUrl`.
+Testkit asks the OS for a free port for each service in each runtime instance,
+on `127.0.0.1` and, when the host has IPv6, on `::1`. The service receives the
+port as `PORT` and as `{port}`. A `baseUrl` must use `{port}`, or
+`{port:<its own name>}`, as its port, for example `http://127.0.0.1:{port}`.
+`app.node` and `app.next` default to that `baseUrl`.
 
 `local.port`, the `port` option of `app.node` and `app.next`, and a literal port
 in `baseUrl` or `readyUrl` are config errors. The error names the service and
 the key. Delete the setting and use `{port}`. Testkit has no setting that pins
 a service to a fixed port.
 
-If a service exits before it becomes ready, Testkit assigns it a fresh port and
-starts it again. Testkit holds each port that a service already tried, so a
-retry never gets one back. A service that already started and whose `start`, env,
-`readyUrl`, or `runtime.prepare` steps name the moved service is stopped and
-started again with the new value. The fingerprinted `runtime.prepare` steps of
-every service that has not started yet run again first. Each service gets three attempts in
-total. After the third, the run fails as an infrastructure failure whose error
-lists each attempt's port and exit status and the last attempt's output. A
-startup that fails another way after an earlier attempt, such as a readiness
-timeout, also lists every port tried.
+If a service exits before it becomes ready, Testkit starts it again on a fresh
+port, never one the service already tried. A service that already started and
+whose `start`, env, `readyUrl`, or `runtime.prepare` steps name the moved
+service is stopped and started again with the new value, and the
+`runtime.prepare` steps of every service that hasn't started yet run again
+first. Each service gets three attempts in total. After the third, the run fails
+as an infrastructure failure whose error lists each attempt's port and exit
+status and the last attempt's output. A startup that fails another way after an
+earlier attempt, such as a readiness timeout, also lists every port tried.
 
 A `runtime.prepare` step whose environment or command includes a service URL or
 port, such as a Next build that embeds `NEXT_PUBLIC_API_URL: "{baseUrl:api}"`,
@@ -403,7 +478,8 @@ such values at start time when the build should be cached.
 
 `run.json` records each service's starts under `environment.services` as they
 happen, with its `runtimeLabel`, `serviceName`, `baseUrl`, `readyUrl`, `port`,
-and each attempt's port and outcome. A run whose startup fails keeps the
+and each attempt's port and outcome. `baseUrl` and `readyUrl` are `null` when the
+service declares none. A run whose startup fails keeps the
 attempts it made, and a service restarted for a moved peer shows both starts.
 The recorded URLs drop credentials, query values, and fragments, so
 `http://127.0.0.1:41234/health?apiKey=x` is stored as
@@ -436,6 +512,11 @@ the service. Plain services take a string record. `app.node(...)` and
 `app.next(...)` take `{ values, databases }` and place the result under
 `local.env`; `local.env` overrides `env` when both set a name.
 
+Tasks never receive a value under a name that a source schema in their runtime
+reads: `TESTKIT_SCHEMA_SOURCE_DATABASE_URL`, any service's
+`TESTKIT_<SERVICE>_SCHEMA_SOURCE_DATABASE_URL`, or a name passed to
+`database.schema.fromEnv()`. Service processes still receive it.
+
 Values support the template tokens listed under [`local`](#local), including
 the database tokens:
 
@@ -458,9 +539,8 @@ that run. A repeated run never sees a previous run's connection details.
 
 Database tokens resolve only in `env` and `local.env` values. Testkit rejects
 them at config load in `local.start`, `local.cwd`, `runtime.prepare`, and
-`database.template` strings, because it resolves those strings while laying out
-the runtime, before any database exists. Commands read `DATABASE_URL` or a
-declared env entry at run time instead.
+`database.template` strings, which resolve before any database exists. Commands
+read `DATABASE_URL` or a declared env entry at run time instead.
 
 Source-schema discovery fails when the env entry it reads as the source URL
 points at the service's own database. A source schema has to come from a
@@ -481,11 +561,30 @@ to the matching `{db*:api}` token. `env.values` entries override expanded names.
 ### `envFile` / `envFiles`
 
 Optional extra env files loaded into the declared service/task environment for
-migrations, seeds, services, and every execution engine. k6 exposes task values
-through `__ENV`; Node/Vitest data and contract contexts expose them through
-immutable `context.env`; and managed Playwright contexts expose them through
-`readPlaywrightContext().env`. Direct managed-Node `process.env.KEY` reads are a
-non-enumerable compatibility overlay, not the consumer-input contract.
+migrations, seeds, services, and every execution engine. Node/Vitest tests read
+task values from `process.env`, and managed Playwright contexts expose them
+through `readPlaywrightContext().env`.
+
+Testkit reads a service's env files only when a selected group uses the service
+or a used service depends on it. Loading the config reads none of them, so a
+missing or unreadable file of an unused service changes nothing. A missing file
+is skipped.
+
+Without `envFile` or `envFiles`, a service uses whichever of these exist, in
+this order: `<local.cwd>/.env.testkit`, `<local.cwd>/.env`, `.env.testkit`, and
+`.env`. With them, it uses `envFile` and then each `envFiles` entry. A later file
+overrides an earlier one, `env` overrides every file, and `local.env` overrides
+`env`. A group that uses several services takes each name from the first service
+in its `uses` that sets it.
+
+A service that declares only `env`, `envFile`, or `envFiles` starts nothing, and
+neither does a `dependsOn` edge between such services. Their groups get the
+values, and the config's `ui` settings, with no runtime slot, build, database,
+server, or teardown. Without a
+running service, their values can use only `{service}`, `{stateDir}`,
+`{productDir}`, `{lease}`, `{leaseDir}`, `{bin}`, and `{pathList}`. Any other
+token, such as `{runtime}`, `{prepareDir}`, `{port}`, or `{dbUrl}`, fails the
+group's tasks with an infrastructure failure that names the token.
 
 Environment names are validated case-insensitively. All engines reserve
 `APPDATA`, `ComSpec`, `HOME`, `LANG`, `LC_ALL`, `LOCALAPPDATA`, `PATH`, `PATHEXT`,
@@ -493,18 +592,17 @@ Environment names are validated case-insensitively. All engines reserve
 `XDG_CONFIG_HOME`, and `XDG_DATA_HOME`. Engine-specific reservations and limits
 are:
 
-| Engine        | Additional reservations                                                                                                     | Consumer environment limit                  |
-| ------------- | --------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------- |
-| `k6`          | prefixes `K6_`, `TESTKIT_`; exact keys `BASE_URL`, `GODEBUG`                                                                | 128 entries; 16,384 environment-block units |
-| `node-vitest` | prefixes `TESTKIT_`, `VITEST_`; exact keys `BASE_URL`, `FORCE_COLOR`, `NODE_OPTIONS`, `NO_COLOR`, `UPDATE_SNAPSHOT`         | 512 entries; 4 MiB of UTF-8 key/value data  |
-| `playwright`  | prefixes `TESTKIT_`, `PLAYWRIGHT_`, `PWTEST_`, `PW_TEST_`; exact keys `BASE_URL`, `FORCE_COLOR`, `NODE_OPTIONS`, `NO_COLOR` | 512 entries; 2 MiB of UTF-8 key/value data  |
+| Engine        | Additional reservations                                                                                                                                    | Consumer environment limit                 |
+| ------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------ |
+| `node-vitest` | exact keys `BASE_URL`, `FORCE_COLOR`, `NODE_OPTIONS`, `NO_COLOR`, `UPDATE_SNAPSHOT`, `VITEST_POOL_ID`, `VITEST_WORKER_ID`, and the `TESTKIT_` keys it sets | 512 entries; 4 MiB of UTF-8 key/value data |
+| `playwright`  | prefixes `TESTKIT_`, `PLAYWRIGHT_`, `PWTEST_`, `PW_TEST_`; exact keys `BASE_URL`, `FORCE_COLOR`, `NODE_OPTIONS`, `NO_COLOR`                                | 512 entries; 2 MiB of UTF-8 key/value data |
 
 Empty names, names containing `=` or NUL, values containing NUL, and
 case-variant duplicates are rejected. The limits apply after env files and
-configured service/runtime values have been merged. Node/Vitest and Playwright
-carry consumer values in bounded owned input files; k6 carries them in its
-physical process environment. The aggregate input and physical spawn ceilings
-are documented in [Engine Architecture](docs/engine-architecture.md#managed-environment).
+configured service/runtime values have been merged.
+[Environment](docs/engines.md#environment) lists the `TESTKIT_` keys Node/Vitest
+sets and the limits on all of a test's inputs together. Node/Vitest passes other
+`TESTKIT_` and `VITEST_` keys through, such as `TESTKIT_REQUIRE_COMPLETE_SUITE`.
 
 ### `database`
 
@@ -524,6 +622,19 @@ materialize the database as host-local Docker Postgres.
 - `template.verify`
 
 `binding` may be `shared` or `per-runtime`.
+
+`reset` defaults to `true`. Each time Testkit sets up a runtime instance, it
+drops that instance's database and clones it again from the cached template,
+so every run starts from the template's state. A run sets up an instance the
+first time a test needs it. If a failure invalidates the instance, such as an
+infrastructure failure or a setup cleanup that throws, Testkit sets it up again
+before the next test uses it. Between setups, every test on the instance uses
+the same database.
+With `binding: "shared"`, every runtime instance uses one database. Testkit
+resets it once per run, when the first instance sets it up.
+`reset: false` keeps the runtime database from the previous run, with every row
+that earlier runs wrote, until the template changes.
+
 `runtimeConnections` is the service runtime slot's Postgres connection budget.
 `maxConnections` and `reservedConnections` describe the backing host-local
 Postgres capacity used for scheduler admission.
@@ -534,10 +645,9 @@ Template stages are ordered arrays of typed step objects:
 - `{ kind: "sql-file", path: "db/schema.sql" }`
 - `{ kind: "module", target: "src/testkit/verify-seed.ts#verifySeed" }`
 
-Local files and ordinary external packages are valid module targets. Exact
-`@gfdelarue/testkit` module targets come from one Testkit-owned registry and are
-validated during config loading; unknown Testkit subpaths fail before any step
-is executed.
+Local files and ordinary external packages are valid module targets. An
+unsupported or private `@gfdelarue/testkit` target fails when the config loads,
+before any step runs.
 
 `verify` runs after template migrate/seed and must succeed before the template DB
 is cached for reuse.
@@ -581,19 +691,21 @@ existing role unchanged and rolls back any roles created in the same operation.
 Existing object grants and ownership remain untouched. Setup evidence records
 the prerequisite operation, including created or reused roles and conflicts.
 
-Testkit sorts role declarations before hashing them, so declaration order does
-not independently change the template fingerprint. Repository and source-cache
-invalidation still apply; editing the config file can change the repository
-cache key. Changing role names or configured template inputs triggers a rebuild.
-Roles persist when templates
-are rebuilt, replay fails, service caches are removed, or declarations are
-removed. Removing a declaration stops ensuring that role. Destroying the owned
-PostgreSQL volume removes its roles, and the next provisioning creates the
-declared roles again.
+Changing role names or configured template inputs rebuilds the template. Role
+order doesn't count as a change, but editing the config file, even to reorder
+roles, can still rebuild it, because the file is part of the repository. Roles
+persist when templates are rebuilt, replay fails, service caches are removed, or
+declarations are removed. Removing a declaration stops ensuring that role.
+Destroying the owned PostgreSQL volume removes its roles, and the next
+provisioning creates the declared roles again.
 
 ### `databaseFrom`
 
-Reuse another service's provisioned `DATABASE_URL`.
+Use another service's database. The service gets the database that the named
+service provisioned in the same runtime instance, as `DATABASE_URL` and in
+`{dbUrl}` and the other database placeholders. List the named service in
+`dependsOn` so that it runs in the same runtime. A service cannot declare both
+`database` and `databaseFrom`.
 
 ### `runtime`
 
@@ -615,24 +727,25 @@ When configured, `testkit` applies the resolved toolchain to:
 - `runtime.prepare` command/module steps
 - local service `start` commands
 
-The resolved toolchain identity is also included in runtime preparation
-fingerprints so prepared artifacts are not reused across incompatible Node/npm
-versions.
+Changing the resolved Node or npm version invalidates prepared artifacts, so
+`runtime.prepare` runs again.
 
 ### `skip`
 
-Repo-declared skip rules. Skipped files remain visible in run artifacts and
-`testkit.status.json` with `status: "skipped"` and the configured reason.
+Skip rules for a group's files, set as `groups.<name>.skip`. Skipped files remain
+visible in run artifacts with `status: "skipped"` and the configured reason.
 
 Prefer file-local `export const testkit = defineFile({ ... })` metadata
-for per-file skips and locks. Repo-level `skip` is mainly for broad suite-level
-policy.
+for per-file skips and locks in a typed file. Repo-level `skip` is mainly for
+broad suite-level policy. A plain Vitest file has no file-local metadata, so its
+skips, locks, and isolation go in `skip.files`, `requirements.files`, and
+`runtimeIsolation.files`.
 
 ```ts
 skip: {
   files: [
     {
-      path: "__testkit__/billing/billing.int.testkit.ts",
+      path: "src/billing/billing.test.ts",
       reason: "Billing is currently unavailable",
     },
   ],
@@ -650,12 +763,13 @@ skip: {
 - `files[].reason`
   - required non-empty explanation recorded in artifacts
 - `suites[].selector`
-  - existing suite selector syntax, including typed selectors like `int:health`
-    and `ui:billing`
+  - existing suite selector syntax, including typed selectors like `ui:billing`
 - `suites[].reason`
   - required non-empty explanation recorded in artifacts
 
-Use `--ignore-skip-rules` on the CLI to run matched files anyway.
+A run that skips a selected file fails, even when every other file passes, and
+`--allow-empty` doesn't change that. Use `--ignore-skip-rules` on the CLI to run
+skipped files anyway.
 
 ### `runtime`
 
@@ -692,24 +806,29 @@ runtime: {
 
 ### `requirements`
 
-Service-local task lock rules.
+Task lock rules for a group's files, set as `groups.<name>.requirements`.
 
 ```ts
 requirements: {
   suites: [
-    { selector: "ui:billing", locks: ["billing-ledger"] },
+    { selector: "ui:checkout", locks: ["payments-sandbox-webhook"] },
   ],
   files: [
     {
-      path: "src/api/routes/__testkit__/crawls-worker-concurrency.int.testkit.ts",
-      locks: ["global-worker-loop"],
+      path: "src/api/routes/payout-webhook.test.ts",
+      locks: ["payments-sandbox-webhook"],
     },
   ],
 }
 ```
 
+Files that need the same lock never run at the same time within one run.
+Testkit holds locks for one run only, so two runs, such as two CI jobs, don't
+wait for each other. Use a lock for a resource that can't be duplicated, never
+for tests that share rows.
+
 - `suites[].selector`
-  - typed selector like `int:health` or `ui:billing`
+  - typed selector like `ui:billing`
 - `suites[].locks`
   - named locks required by matching files
 - `files[].path`
@@ -717,6 +836,61 @@ requirements: {
 - `files[].locks`
   - named locks required by that file
 
+### `runtimeIsolation`
+
+What a group's files share with each other in a run, set as
+`groups.<name>.runtimeIsolation`. A file can set its own with
+`defineFile({ runtimeIsolation: "resetBefore" })`.
+
+```ts
+runtimeIsolation: {
+  default: "shared",
+  suites: [{ selector: "ui:admin", policy: "resetBefore" }],
+  files: [{ path: "src/orders/purge.test.ts", policy: "resetBefore" }],
+}
+```
+
+A string sets the policy for every file, as in `runtimeIsolation: "resetBefore"`.
+A file's `defineFile` policy wins over a `files` rule, which wins over a
+`suites` rule, which wins over `default`. The default is `shared`.
+
+- `shared`
+  - files on the same runtime instance share its services and its database for
+    the whole run
+  - each run starts from a database freshly cloned from the template, unless
+    `database.reset` is `false`, but within a run every file sees the rows that
+    other files wrote
+  - a test creates the rows it needs and filters by them, so rows from other
+    files don't change its result
+- `resetBefore`
+  - 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 all point at the clone
+  - Testkit drops the clone when the file finishes; if that fails, the end of
+    the run drops it, and the clone of a run that died is dropped when the next
+    run sets up that runtime
+  - use it for a test that changes a whole table or schema, such as an
+    unfiltered `DELETE` or a migration test
+  - a file whose environment reaches no database that Testkit provisions,
+    including every file run on supplied values, ends as an environment failure
+
+`resetBefore` isolates only the test's own database access. The group's
+services keep running against the runtime's database, so a request the test
+sends to an API server reads and writes the shared database, not the clone.
+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, for example an
+`api-isolated` service declared with the same options as `api`. Groups that use
+the same services share their runtimes, so a separate group alone doesn't give
+the test its own server. The second entry gets its own runtime, server, and
+database, which the files in that group still share.
+
+`resetAfter` and `exclusive` were 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 test-owned rows.
+
 ## Config Surface
 
 `@gfdelarue/testkit/config` exports:
@@ -728,89 +902,59 @@ requirements: {
 - `database.fixture(...)`
 - `toolchain.node(...)`
 
-The `@gfdelarue/testkit/k6` subpath exports the k6 suite authoring surface:
-
-- `defineHttpSuite(...)`
-- `defineDalSuite(...)`
-- `defineDalFixtures(...)`
+## Discovery Conventions
 
-`defineDalFixtures(...)` is the first-class DAL seeding model. DAL suites receive
-`fixtures` plus a deterministic `fixtureScope`, and that scope provides:
+Plain Vitest test files are the files the repository's own Vitest config
+selects, as `vitest run` lists them from the product directory:
 
-- `id(label)` / `uuid(label)`
-- `slug(label)`
-- `email(label)`
-- `string(label, options)`
-- `token(label)`
-- `seed(kind, key, signature, create)`
-- `records()`
+- the root `vitest.config.*` or `vite.config.*`, or the file
+  `--vitest-config` names, and its projects; without a config, Vitest's
+  defaults, which match `**/*.{test,spec}.?(c|m)[jt]s?(x)` outside
+  `node_modules` and `.git`
+- narrowed only by `discovery.exclude` and a declared group's `exclude`
+- owned by the group whose roots contain them, or by `root`
 
-## Discovery Conventions
+`--vitest-runner managed` lists them with Testkit's own Vitest and its default
+rules instead, without the repository's config.
 
-Suites are discovered from the filesystem:
+Typed suites are discovered from the filesystem:
 
 - only files inside `__testkit__/`
-- service ownership comes from the deepest matching `local.cwd`
-- `discovery.roots` can override ownership for shared-root edge cases
+- a file belongs to the group with the deepest matching root in
+  `groups.<name>.roots`
+- files that no group claims belong to the implicit group `root`
 
-Supported suffixes:
+The supported suffix is `*.ui.testkit.ts`.
 
-- `*.int.testkit.ts`
-- `*.e2e.testkit.ts`
-- `*.contract.testkit.ts`
-- `*.data.testkit.ts`
-- `*.dal.testkit.ts`
-- `*.load.testkit.ts`
-- `*.ui.testkit.ts`
-
-Every discovered file must also export `defineFile({ engine: "..." })` from the
-root package. The suffix supplies `testType`; the required engine declaration
+Every discovered typed file must also export `defineFile({ engine: "..." })`
+from the root package. The suffix supplies `testType`; the required engine declaration
 supplies `engineId`; and Testkit derives `profileId` from the catalog. None of
 those identities are silently rewritten later in the run.
 
-`*.contract.testkit.ts` is a Node-backed service/runtime contract suite type. It
-declares `engine: "node-vitest"`, uses
-`@gfdelarue/testkit/node-vitest/contract`, runs through
-`node-vitest-contract`, and is the right place for checks that need Node APIs
-but are not data-flow evidence suites. Contract files are native Vitest suites:
-`contractScenario(...)` provides managed Testkit context when needed, while
-direct public Vitest runner APIs remain valid.
-
-`*.data.testkit.ts` is a Testkit-owned data-flow/data-contract suite type. It
-declares `engine: "node-vitest"`, uses
-`@gfdelarue/testkit/node-vitest/data`, records evidence through
-`dataScenario(...)`, and runs through `node-vitest-data`. Data suites may use
-non-registering public Vitest APIs such as `expect`, but `dataScenario(...)`
-owns case registration. Ordinary Node/Vitest assertions, DOM/browser checks,
-and service-local loopback checks belong in the appropriate non-data suite
-type.
-
-Examples:
-
-- `src/api/routes/__testkit__/auth/me.int.testkit.ts`
-- `src/api/routes/__testkit__/runtime.contract.testkit.ts`
-- `src/api/routes/__testkit__/agent-flow.data.testkit.ts`
-- `src/db/__testkit__/sessions/count-type.dal.testkit.ts`
-- `frontend/__testkit__/navigation/navigation.ui.testkit.ts`
+Example: `frontend/__testkit__/navigation/navigation.ui.testkit.ts`.
 
 `testkit discover` exposes that inventory directly without running suites:
 
 - `testkit discover`
-  - compact human output grouped by service, type, and suite
+  - compact human output grouped by group, type, and suite
 - `testkit discover --output-mode verbose`
-  - includes canonical paths, IDs, locks, dependencies, and skip reasons
+  - includes group roots and uses, canonical paths, IDs, locks, and skip reasons
 - `testkit discover --json`
   - returns a machine-readable document with stable field names and enums
 - `testkit discover --output .testkit/discovery.json`
   - writes that same machine-readable document to disk
 
 The discovery JSON/API surface is exported from `@gfdelarue/testkit/workspace`.
-Each file entry includes canonical machine fields such as:
+The document has `schemaVersion: 10`. Its `groups` list holds each group's
+`name`, `roots`, `uses`, `source` (`groups`, `services`, or `implicit`), and
+file and suite counts. Each file entry includes canonical machine fields such
+as:
 
 - `id`
 - `path`
-- `service`
+- `group`
 - `suiteName`
+- `suiteLabel`
 - `testType`
 - `engineId`
 - `profileId`
@@ -818,20 +962,7 @@ Each file entry includes canonical machine fields such as:
 - `skipped`
 - `skipReason`
 - `locks`
-- `dependsOn`
+- `runtimeIsolation`
 
 Human-friendly labels such as `displayName` are additive. They are intended for
 compact CLI output and should not be treated as the only identifier.
-
-`testkit` also persists a lightweight history index at
-`.testkit/history/tests.json`. Discovery surfaces may expose:
-
-- `firstSeenAt`
-- `lastSeenAt`
-- `lastRunAt`
-- `runCount`
-- `passCount`
-- `failCount`
-- `skipCount`
-- `avgDurationMs`
-- `lastStatus`