@gfdelarue/testkit 0.4.5 → 0.6.0

package/docs/engine-architecture.md

@@ -1,682 +0,0 @@
-# Engine Architecture
-
-Testkit is one orchestrator and managed distribution with several explicitly
-named execution engines. It unifies discovery, application and database
-lifecycle, scheduling, cancellation, environment and fixture delivery, result
-collection, artifacts, reporting, and evidence publication. It does not flatten
-the engines into one test language.
-
-| Engine        | Runner profile(s)                          | Test types                  | Native technology   |
-| ------------- | ------------------------------------------ | --------------------------- | ------------------- |
-| `k6`          | `k6-http`, `k6-dal`                        | `int`, `e2e`, `load`, `dal` | k6 and xk6-sql      |
-| `node-vitest` | `node-vitest-data`, `node-vitest-contract` | `data`, `contract`          | Node and Vitest     |
-| `playwright`  | `playwright-ui`                            | `ui`                        | Playwright/Chromium |
-
-Every file declares its engine explicitly:
-
-```ts
-import { defineFile } from "@gfdelarue/testkit";
-
-export const testkit = defineFile({ engine: "k6" });
-```
-
-The filename suffix supplies the public test type. Discovery validates the
-literal engine/type pair and resolves one catalog profile. There is no default
-engine, catch-all runner, or fallback to a different engine.
-
-## Source ownership
-
-Each engine owns its Node adapter and consumer runtime under
-`src/engines/<engine>/{adapter,runtime}`. The k6 runtime has a separate TypeScript
-realm with k6 globals; its adapter runs in Node. Shared host execution and
-evidence helpers remain under `src/engines/adapters`, and neutral wire contracts
-remain under `src/engines/contracts`.
-
-Public package specifiers keep their names. Their emitted targets use the
-corresponding `dist/engines/<engine>/runtime` directory. k6 configuration
-hydration belongs to its runtime. The generated entrypoint registers the hydrated
-value in both the k6 and public config registries before the consumer evaluates.
-The config authoring module does not import engine implementation values.
-
-Run policy, scheduling, and per-file setup live in `src/app/run`. The
-`environment` capability exposes runtime planning, run provisioning, and
-maintenance to the run, status, stop, cleanup, destroy, and schema use cases.
-`process/runs` owns persisted run identity and stop mechanics. `evidence` owns
-setup logs, timings, and run-bundle storage. The run use case projects engine
-results into evidence-owned inputs before storage.
-
-Database stage sequencing, SQL execution, and PostgreSQL clients live in
-`database`. Command and module execution remain in `steps`, below database
-orchestration. Product-imported Node helpers live in `config/runtime`; they
-have no loader or engine dependency. Their public package specifiers remain
-stable, and `config/build-assets` and `config/next-runtime-tsconfig` are now
-ordinary package exports with declarations.
-
-Domain owns canonical engine, test-type, runner-profile and outcome vocabulary.
-Engine contracts and configuration loading import it directly. Persisted identity
-checks require exact strings; user-facing test-type formatting still trims input.
-
-Configuration has three owners. `config/authoring` is a host-neutral directory for
-the product DSL. `config/loader` discovers and normalizes product configuration.
-Its engine imports target the catalog, which owns profile and package import
-policy and selects engine configuration projection. The k6 adapter owns the
-Node-to-k6 repository configuration envelope. `config/runtime` holds the Node
-helpers imported by product code. Package export names remain unchanged.
-
-## Engine-native authoring
-
-The root package owns file identity and orchestration. Engine-specific concepts
-remain visible through engine-specific subpaths.
-
-A k6 file may use scenarios, executors, VUs, iterations, thresholds, `setup`,
-`teardown`, and `handleSummary` directly:
-
-```ts
-import { defineFile } from "@gfdelarue/testkit";
-import { check } from "k6";
-import http from "k6/http";
-
-export const testkit = defineFile({ engine: "k6" });
-
-export const options = {
-  scenarios: {
-    smoke: { executor: "shared-iterations", iterations: 1, vus: 1 },
-  },
-  thresholds: { checks: ["rate==1"] },
-};
-
-export default function run() {
-  check(http.get(`${__ENV.BASE}/health`), {
-    healthy: (response) => response.status === 200,
-  });
-}
-```
-
-Node/Vitest owns data and contract suites:
-
-```ts
-import { defineFile } from "@gfdelarue/testkit";
-import { dataScenario } from "@gfdelarue/testkit/node-vitest/data";
-import { expect } from "vitest";
-
-export const testkit = defineFile({ engine: "node-vitest" });
-
-dataScenario("records checkout traffic", ({ count, record }) => {
-  record("checkout", { count: 1 });
-  count("orders", 1);
-  expect(1).toBe(1);
-});
-```
-
-Playwright owns UI suites and keeps ordinary Playwright configuration:
-
-```ts
-import { defineFile } from "@gfdelarue/testkit";
-import { expect, test } from "@playwright/test";
-
-export const testkit = defineFile({ engine: "playwright" });
-
-test("shows the account", async ({ page }) => {
-  await page.goto("/account");
-  await expect(page.getByRole("heading", { name: "Account" })).toBeVisible();
-});
-```
-
-`testkit typecheck` discovers suites, groups them by engine/profile and nearest
-consumer tsconfig, writes deterministic projects, and runs native `tsc --noEmit`.
-Config uses Node types and ES2022 libraries; k6 uses its bundled ambient types and
-ES2022; Node/Vitest uses Node types and ES2022; Playwright adds DOM and DOM.Iterable.
-Data and contract suites have separate programs, with restricted Vitest value
-exports in the data program. Each compiler invocation has cancellation, a deadline,
-and captured diagnostics. A failure reports the completed program prefix.
-
-Consumer TypeScript 5.9.3 and 6.0.2 are supported and tested. Each program uses
-the compiler installed beside its nearest tsconfig or in an ancestor directory,
-then falls back to Testkit's bundled compiler. Config checking starts at the
-product root. Runtime toolchain settings do not select the typecheck compiler.
-Other compiler versions are not covered by this compatibility guarantee.
-
-TypeScript owns transitive imports, workspace links, and type errors. Consumer
-compiler options and aliases are inherited, but ordinary tsconfig `files`,
-`include`, and project references do not add application roots. Generated paths
-select Testkit's authoring declarations and pinned native public exports over
-conflicting consumer packages. A helper shared by engines must typecheck in each
-program. Typechecking does not establish runtime package provenance: managed
-runtime resolution and collection enforce package identity and cross-engine/data
-registration restrictions. Direct import feedback belongs to lint; its migration
-to ESLint is tracked in #22. No second dependency graph runs before TypeScript.
-
-Generated configurations clear `baseUrl` and use explicit relative path targets.
-Aliases inherited from a config with `baseUrl` retain their target directory and
-fallback order. Typecheck does not insert a deprecation suppression or require
-consumers to edit generated files.
-
-### Playwright support files
-
-Playwright programs always include discovered UI suites and the service's selected
-`playwright.config.*`. Typechecking never evaluates that config. For support files
-that are named dynamically or as strings, add a `tsconfig.playwright.json` in the
-service directory or an ancestor inside the product root:
-
-```json
-{
-  "extends": "./tsconfig.json",
-  "files": ["global/setup.ts", "global/teardown.ts"],
-  "include": ["fixtures/**/*.ts", "reporters/**/*.ts", "projects/**/*.ts"],
-  "exclude": ["projects/generated/**"]
-}
-```
-
-The nearest companion takes precedence over the ordinary consumer tsconfig for
-that Playwright scope. TypeScript parses its `extends`, `files`, `include`, and
-`exclude`; selected support roots join the same generated Playwright program.
-Use it for global setup/teardown, reporters, fixtures, dependency projects, and
-teardown projects, including every variant of a dynamic multi-project config.
-An empty companion can provide options alone. Without a companion, only the
-implicit roots, their TypeScript imports, and existing Next ambient/fixture defaults
-are checked. The generated projects do not execute project references.
-
-This changes earlier behavior: Testkit no longer uses Playwright private config
-loaders to discover string-named support modules. Consumers must include those
-modules explicitly. TypeScript follows imported helpers normally; it does not
-infer files from runtime configuration strings or functions.
-
-k6-only ambient declarations are normal package-owned build outputs, not
-independently maintained source `.d.ts` files or production `node_modules/@types`
-dependencies. The build copies the exact pinned `@types/k6` and xk6-sql
-declarations and their licenses into `dist/engines/k6/runtime/ambient-types`; generated k6
-projects select that private type root explicitly. They also load Testkit's
-generated console-global declaration and map the native xk6-sql PostgreSQL
-driver specifier to its generated declaration. The host-neutral, Node/Vitest,
-Playwright, and ordinary automatic-discovery consumer projects load none of
-these files, so installing Testkit cannot leak k6 globals into another authoring
-universe.
-
-## Run composition
-
-`runAll` constructs the local environment and engine manager and calls the
-production evidence writers directly. The environment owns provisioning and
-lifecycle finalization. Its `finish` operation holds the
-product lifecycle fence while committing terminal state, cleaning owned
-resources, and sealing evidence. Recovery preserves the committed interruption
-and any cleanup residue while recording the original failure.
-
-Runtime management, engine input preparation, setup workers, and lifecycle
-cleanup call their production implementations directly. Reporter callbacks keep
-the five-second production timeout. Orchestration integration tests invoke
-`runAll` with real consumer configuration, tests, and setup modules.
-
-## Adapter contract
-
-Each adapter implements the host-neutral engine API through a fixed literal
-catalog. The manager resolves a discriminated, engine-specific installation and
-passes it to the matching typed executor. Testkit supplies:
-
-- an invocation, profile, task, lease, and deadline identity;
-- endpoints plus bounded environment, fixture, and setup inputs;
-- one cancellation signal;
-- owned temporary and artifact directories;
-- a structured observer for task lifecycle and evidence.
-
-The adapter returns bounded structured outcomes, failures, logs, metrics, and
-artifact references. The contract standardizes lifecycle and evidence, not the
-engine's test language.
-
-The Node host composes built-in engines in `src/engines/definitions.ts`.
-Each definition owns its profiles, readiness ownership, installation resolver,
-and lazy executor loader. Catalog and runner orchestration views derive from
-that table. The host-neutral API contains only contracts and identities.
-
-Each execution receives a fresh `EngineInvocationScope`; mutable invocation
-state never lives in an imported module singleton. The adapter registers cleanup
-immediately after allocating each owned resource. After execution, the host
-closes the observer and drains the scope exactly once in reverse registration
-order. Every cleanup handler is attempted, cleanup has its own bounded deadline,
-and any cleanup failure fails the invocation. Adapters do not carry a second
-preparation or execution cleanup path.
-
-The workspace can also provide a caller-owned `cacheDirectory`. Node/Vitest and
-Playwright use a private child directory for Node's compilation cache so fresh
-CLI and worker processes can reuse compiled code across files. Evaluated modules,
-consumer globals, runtime inputs, and native runner state remain process-local.
-Test execution shares the cache across every task of one run and removes it
-when the run's tasks finish.
-Adapters leave invocation temporary directories empty after cleanup. Callers
-that omit `cacheDirectory` retain execution without a shared compilation cache.
-Explicit consumer Node cache controls or V8 coverage disable automatic caching,
-and an unavailable cache falls back to normal execution.
-On Windows, automatic cache allocation and Node startup use the extended path
-form so deeply nested product directories can retain compilation caching.
-
-Test execution places engine workspaces and the compilation cache below
-`.testkit/_execution/node_modules/testkit-engine`, and each task's lease
-directory below `.testkit/_execution/leases`. Playwright skips the
-`node_modules` tree before collecting files, so concurrent discovery cannot
-traverse another task's temporary outputs as they change. Consumer test
-directories, ignore rules, dependency projects, and snapshot paths keep their
-original configuration. Releasing a lease removes its directory and engine
-workspace; the end of the run removes the cache.
-
-Adapters prepare the task batch before executing it. Shared `executeEngineTasks`
-starts tasks in order and defers evidence and terminal notifications until all
-tasks settle. It gives an expired task deadline precedence over cancellation,
-and cancellation precedence over preparation failure. Only successful
-preparation reaches the engine's execution function; its prepared files and
-runtime input are required by the type. Each adapter keeps its native command,
-input verification, result classification, and installation evidence.
-
-The shared workspace reader resolves consumer files physically before checking
-lexical containment with `src/process/files/paths.ts`. A symlink to an outside file
-is rejected. A contained name such as `..fixtures/input.json` remains valid.
-
-Observer lifecycle events are checked and buffered by the host. Internal adapters
-use typed requests and results; native reports are validated at each adapter.
-An adapter cannot suppress an observer-contract failure by catching the callback
-error: the stream remains poisoned. `taskStarted` and `evidenceRecorded` are
-optional lifecycle and additive/advisory evidence notifications; they do not
-replace the returned result. The validated returned result is authoritative,
-and every emitted `taskFinished` outcome must exactly match that task's returned
-outcome. Buffered events are committed only after result validation,
-terminal-result coherence, and successful invocation cleanup, so a failed
-invocation cannot publish a terminal pass.
-
-## Managed native reports
-
-Testkit's Vitest 4.1.11 and Playwright 1.59.1 reporters use their public
-reporter APIs. Vitest supplies final test and suite results through
-`onTestRunEnd`. Playwright supplies cases and their native attempts through
-`onBegin` and `onEnd`. Testkit no longer requests either engine's generic JSON
-report as its evidence protocol. The managed Playwright config appends the
-Testkit reporter to consumer reporters, including consumer JSON reporters.
-Node/Vitest uses Testkit's generated Vitest config.
-
-Each reporter exclusively creates a private report in its invocation workspace.
-The schema version is `1`; the envelope identifies `engineId`, `invocationId`,
-`taskId`, and `sourceFile`, and carries an engine-specific `result`. Vitest
-records summary counts, final failed test identities and locations, and runtime
-errors. Playwright records case outcomes, all-attempt durations, retry numbers,
-stdout and stderr, attachments, and the last failed attempt's error details.
-Testkit keeps product and infrastructure classification in the adapters.
-
-Playwright body attachments use private files beneath the task's artifact
-directory. The reporter records each file path with its attachment name,
-content type, spec identity, title, and retry number. Native path attachments
-use the same descriptor. Attachment bytes do not enter the report's JSON
-strings. The managed workspace creates the attachment directory exclusively.
-The reporter uses generated filenames and applies the 64 MiB individual and
-256 MiB aggregate budgets to raw bytes across both attachment forms.
-
-An attachment budget or I/O failure becomes a bounded error descriptor with
-the attachment's identity. The collector retains valid outcomes, structured
-assertion details, and accepted attachments when another attachment fails.
-`PLAYWRIGHT_ATTACHMENT_LIMIT` takes precedence over normal spec classification
-and includes the rejected attachment's identity, budget, limit, and observed
-bytes. Attachment I/O errors produce a distinct infrastructure failure when
-there is no spec failure. All attachment errors remain in structured evidence
-when a spec failure determines the task result.
-Cancellation, timeout, and process termination failures keep their precedence.
-Every attachment rejection remains in structured evidence.
-
-The collector checks file containment, regular-file identity, and actual byte
-budgets before making immutable snapshots. The invocation scope removes the
-reporter's temporary attachment directory after collection, including failed
-and cancelled runs. Bundle sealing still redacts declared secrets in text
-before hashing and rejects binary files that contain a sensitive environment
-value.
-
-The report limit is 16 MiB for Vitest and 64 MiB for Playwright. Both use the
-existing JSON limits of depth 64, 100,000 nodes, 100,000 entries per collection,
-and 1 MiB of UTF-8 data per string. The adapter reads a stable regular file,
-checks the envelope against the invocation and validates the engine payload
-before promoting evidence. Attachment containment, file identity, aggregate
-limits, and invocation cleanup remain adapter responsibilities. Bundle
-redaction remains in `src/evidence/bundles.ts`.
-The promoted artifact kinds are `engine.testkit-vitest-report` and
-`engine.testkit-playwright-report`. All three engines use the shared
-`src/engines/adapters/evidence-files.ts` reader and writer for stable bounded
-reads and private atomic evidence publication. Engine-specific report decoding
-and k6's whole-directory native-summary publication stay local.
-
-The reporters are private emitted modules at
-`dist/engines/{node-vitest,playwright}/adapter/reporter.js`.
-`nativeReporterFile` in `src/engines/adapters/native-report.ts` resolves the
-executing Testkit package with three parent-directory hops from its own module.
-The locator uses each engine's adapter directory. These reporters add no package export.
-
-Fixture alias selection belongs to
-`src/engines/contracts/fixture-manifest.ts`. It matches declared aliases exactly
-and reports unknown or ambiguous names with candidate paths in manifest order.
-Engine entrypoints normalize the requested name and retain their own fixture
-loading and usage accounting. k6 retains its native binary values; Node data
-and contract fixtures retain their Node file readers.
-
-## Managed environment
-
-All three host writers use `src/engines/runtime-input-file.ts` for bounded
-UTF-8 JSON serialization, exclusive private temporary files, atomic rename,
-and SHA-256 identity. Node/Vitest and k6 verify the prepared file through its
-shared reader. Playwright's generated preload awaits that reader before
-validating its schema and installing context. Reads check containment,
-owner-only permissions on POSIX, no-follow opening, byte bounds, and file
-identity before and after reading. Each engine keeps its schema, task identity,
-environment policy, and context installation at its own boundary.
-
-The Playwright preload imports the private emitted
-`dist/engines/runtime-input-file.js` module. `ownedRuntimeInputModuleUrl` resolves
-that target from its own module with two parent-directory hops. The managed
-resolver trusts the generated preload as an importer of this exact entrypoint.
-The #55 path inventory must retain this generated import and locator when
-moving engine code. The module adds no package export. The k6 guest keeps its
-host-neutral `open` and `k6/crypto` reader; no Node filesystem code enters its
-bundle. Host input limits measure UTF-8 bytes, while the k6 guest's string
-bounds measure JavaScript character units.
-
-Testkit treats the environment declared for a task as invocation input, not as
-ambient orchestrator state. The complete, enumerable consumer environment is
-available through the engine-native authoring surface:
-
-- k6 files read it from native `__ENV`;
-- Node/Vitest data and contract callbacks read it from immutable
-  `context.env`;
-- Playwright files read immutable `context.env` from
-  `readPlaywrightContext()` when the invocation is Testkit-managed.
-
-An unmanaged Node/Vitest authoring context has an immutable empty `env`.
-`readPlaywrightContext()` returns `null` outside a managed invocation because
-there is no Testkit endpoint, fixture, or task context to represent.
-
-The merged consumer environment is validated case-insensitively at the engine
-adapter boundary. Empty names, names containing `=` or NUL, values containing
-NUL, and case-variant duplicates are rejected. Every engine reserves the exact
-host-process keys `APPDATA`, `ComSpec`, `HOME`, `LANG`, `LC_ALL`,
-`LOCALAPPDATA`, `PATH`, `PATHEXT`, `SystemRoot`, `TEMP`, `TMP`, `TMPDIR`,
-`USERPROFILE`, `XDG_CACHE_HOME`, `XDG_CONFIG_HOME`, and `XDG_DATA_HOME`.
-
-Engine-specific reservations and consumer limits are:
-
-| Engine        | Reserved prefixes                                | Additional exact reserved keys                                           | Consumer environment limit                                                                                                  |
-| ------------- | ------------------------------------------------ | ------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------- |
-| `k6`          | `K6_`, `TESTKIT_`                                | `BASE_URL`, `GODEBUG`                                                    | 128 entries and 16,384 environment-block character units; the complete physical spawn environment is capped at 24,576 units |
-| `node-vitest` | `TESTKIT_`, `VITEST_`                            | `BASE_URL`, `FORCE_COLOR`, `NODE_OPTIONS`, `NO_COLOR`, `UPDATE_SNAPSHOT` | 512 entries and 4 MiB of UTF-8 key/value data; the complete owned runtime-input document is capped at 8 MiB                 |
-| `playwright`  | `TESTKIT_`, `PLAYWRIGHT_`, `PWTEST_`, `PW_TEST_` | `BASE_URL`, `FORCE_COLOR`, `NODE_OPTIONS`, `NO_COLOR`                    | 512 entries and 2 MiB of UTF-8 key/value data; the complete owned runtime-input document is capped at 4 MiB                 |
-
-The prefix and exact-key comparisons are case-insensitive. k6's size uses the
-same key-length plus value-length plus separator-unit calculation as the
-physical environment block. Node/Vitest's file-backed consumer values are not
-part of its separately bounded 24,576-unit physical spawn environment.
-Playwright likewise keeps file-backed consumer values outside its physical
-spawn environment, which is separately capped at 64 entries and 24 KiB. These
-reservations prevent consumer configuration from overriding endpoint,
-cancellation, deadline, reporter, module-resolution, or native-runner controls.
-
-Engine subprocesses run with a sanitized operating-system environment. Managed
-Node processes expose direct `process.env.KEY` reads through an immutable,
-non-enumerable overlay, so libraries that read `process.env` see consumer
-values, but `process.env` is not the enumerable consumer-input contract. A Node
-child which inherits Testkit's bootstrap can rehydrate that overlay; a non-Node
-native child does not receive consumer values in its physical environment
-unless consumer code explicitly passes the values it intends to disclose. This
-keeps enumeration, object spread, mutation behavior, and native-process
-disclosure deliberate and consistent across platforms.
-
-Process execution is owned once by the root package's private `src/process/`
-adapter. Engine adapters do not carry separate launch or cleanup code. Process
-code never imports an engine module.
-
-The adapter uses Execa for direct argv execution, working directory,
-environment, bounded capture, streaming, timeout, cancellation, and graceful
-then forced termination. `killDescendants: true` creates a separate process
-group on POSIX and uses `taskkill /T` on Windows. This is best-effort process-tree
-termination, not workload containment. A descendant which creates a new session
-or moves work into another service is outside the contract.
-
-Testkit checks a POSIX process group after every completion path and records a
-cleanup error when signalling fails or the group remains after forced
-termination. On Windows, a bounded command that Testkit cancels or times out is
-stopped by the packaged native helper instead of `taskkill`. The helper
-terminates the command and its descendants, parents first, and waits up to four
-seconds for every one of them to exit. A loaded Windows host can take seconds to
-finish a terminated process, and until then the process still holds its files.
-A member that outlives the deadline, or that the helper cannot open or
-terminate, becomes the `terminationError`, and the command then returns without
-waiting for output that a surviving process holds open. Windows offers no
-equivalent check after a command exits on its own or for service handles. A null
-`terminationError` therefore means Testkit observed no cleanup failure; it does
-not prove that every descendant exited. Workloads that require
-hard containment need a container, VM, cgroup, service manager, or Windows Job
-Object owned outside this adapter.
-
-The Windows executable CLI supplies a Job Object through a packaged native
-helper before running an action. Its descendants inherit that job, and closing
-the helper's job handle after the CLI exits terminates the remaining process
-tree. Help, parser errors, and guard commands do not start the helper. Library
-imports retain the adapter's best-effort cleanup contract and do not assign the
-consumer process or unrelated children to a job. Ordinary builds verify the
-committed helpers' source provenance, hashes, and native architectures. Updating
-them requires the pinned Go compiler described in
-[`scripts/build/windows-owner/README.md`](https://github.com/gfdelarue/testkit/blob/master/scripts/build/windows-owner/README.md).
-
-New Windows run manifests use the same helper to publish a completed file with
-a native rename that rejects an existing destination. Removing a temporary
-hard link can make later Windows replacements fail with access denied. The
-native publication avoids that sequence while preserving complete-file
-visibility and duplicate run-ID rejection. This file operation does not create
-a Job Object, so library consumers retain control of their process ownership.
-
-Each runtime instance reserves an OS-assigned port for every local service when
-it first prepares, by listening on `127.0.0.1:0` and on the same port at `::1`
-when IPv6 is available, and keeping both sockets open.
-Template resolution reads the reserved ports into `{port}`, `baseUrl`, and
-`readyUrl`, and the resolved config carries the port as `local.assignedPort`.
-Service startup resolves the toolchain and prepares the invocation, then closes
-the reservation immediately before it spawns the service and passes the port as
-`PORT`. A service that exits before it becomes ready gets a fresh reservation,
-and the instance's configs are resolved again. The context keeps holding every
-port a service already tried, so the OS cannot hand one back.
-Already started services whose start command, resolved env, readiness URL, or
-prepare steps changed are stopped and started again, and the fingerprinted
-`runtime.prepare` steps of every service not yet started run again before the
-next attempt. Each service gets three attempts in total. Runtime cleanup closes
-any reservation a service never claimed. Schema refresh and verify resolve
-their configs with ports reserved the same way and released at once, because
-they start no services.
-
-Long-running application services keep the live Execa handle for readiness,
-output drain, explicit stop, and normal teardown. Once the child reports spawn,
-Testkit records its creation identity and the POSIX process-group ID needed for
-recovery after an abnormal coordinator exit. Recovery checks the recorded
-identity before signalling. Provider-owned resources such as containers retain
-their own stronger cleanup identity.
-
-The internal call sites require the following behaviour:
-
-| Consumer                                               | Output                 | Stop conditions                                 | Recovery requirement                              |
-| ------------------------------------------------------ | ---------------------- | ----------------------------------------------- | ------------------------------------------------- |
-| k6, Node/Vitest, and Playwright engines                | Bounded capture        | completion, timeout, cancellation, output limit | None after a returned result                      |
-| Playwright setup and installation resolution           | Bounded capture        | completion, timeout, cancellation               | None                                              |
-| Local application services                             | Caller-drained streams | explicit stop, cancellation, unexpected exit    | Child creation identity and POSIX process group   |
-| Database, Docker, Git, build, and maintenance commands | Bounded capture        | completion, timeout, cancellation               | Provider identity where the provider supplies one |
-
-The adapter reports command failure separately from an observed cleanup failure.
-Consumers must treat either as an infrastructure failure when cleanup is part of
-their operation's contract.
-
-## Managed appliance distribution
-
-Consumers declare one Testkit dependency:
-
-```text
-@gfdelarue/testkit
-  optional -> @gfdelarue/testkit-engine-k6-<target>
-                required -> @gfdelarue/testkit-engine-k6-source
-```
-
-The root package owns every JavaScript adapter and exact direct tool package.
-Its `optionalDependencies` pin the five k6 target packages
-(`@gfdelarue/testkit-engine-k6-darwin-arm64`, `-darwin-x64`, `-linux-arm64`,
-`-linux-x64`, and `-win32-x64`) at one exact version. npm selects the one
-package whose `os` and `cpu` match the host. Each target package depends on
-`@gfdelarue/testkit-engine-k6-source` at the same exact version. The source
-package carries the AGPL corresponding source archive and the licenses.
-
-The k6 packages are built and published from
-[gfdelarue/testkit-k6](https://github.com/gfdelarue/testkit-k6) through
-GitHub Actions with npm trusted publishing. They follow their own version line,
-independent of the Testkit version. The executable is k6 1.7.1 with xk6-sql and
-its PostgreSQL driver, built reproducibly with xk6. The k6 version is metadata
-in each package manifest (`testkit.k6Version`). The testkit-k6 README documents
-the build, the expected executable digests, and the license notes. The six k6
-packages are transitive implementation and compliance artifacts, not
-selectable Testkit engines.
-
-This is a managed-appliance contract, not a promise to prune unused engines.
-After an ordinary install the root-owned Node/Vitest and Playwright tools and
-the compatible k6 target/source pair are present regardless of the profiles a
-consumer currently uses. Installing with optional dependencies omitted is
-unsupported because k6 and upstream JavaScript packages use platform
-optionals. If a consumer installs with `--omit=optional`, k6 resolution fails
-with `K6OptionalPackageMissingError`.
-
-The consumer lockfile is the JavaScript and native-package reproducibility
-boundary. npm integrity in that lock is the trust boundary for the k6
-packages. Testkit does not download k6, parse a provenance file, or verify the
-executable against a digest at launch. Playwright's installer and selected
-browser registry own Chromium and FFmpeg. Testkit does not create a second
-package graph, extracted engine cache, or private browser descriptor inventory.
-
-## Root-anchored resolution
-
-All managed package resolution starts from an anchor inside the installed
-`@gfdelarue/testkit` root. A consumer's own Vitest, Vite, esbuild, TypeScript,
-or Playwright packages cannot select or replace Testkit's execution tools or
-authoring bridge.
-
-For a root-owned direct package, resolution:
-
-- resolves a declared public entrypoint from the Testkit anchor;
-- finds and realpaths the owning manifest without crossing the selected package
-  boundary;
-- validates containment, package name, and the exact version declared by the
-  root manifest;
-- resolves only public entrypoints Testkit actually exercises; and
-- distinguishes an absent direct package from a present but broken package,
-  preserving the original loader cause for the latter.
-
-Testkit does not inventory upstream private transitives or reinterpret their
-version ranges. npm and the selected direct package remain responsible for
-that graph. A clean reinstall with optionals is the recovery path for a broken
-installation.
-
-Node/Vitest resolves Vitest, Vite, TypeScript, and esbuild through this anchor.
-Generated configuration, authoring aliases, helpers, and subprocesses use the
-same managed paths. Evidence reports the direct tools actually exercised by
-the run and does not enumerate private native bindings. Healthy runs exercise
-these capabilities in the native engine process. The controller imports and
-checks them only to diagnose a failed engine launch with no native report;
-it does not run a duplicate empty compilation before each run.
-
-Playwright selects one physical family: `@playwright/test` from the Testkit
-anchor, `playwright` from that package, and `playwright-core` from the selected
-`playwright`. All three versions must match the root's exact declarations. One
-registry resolver is shared by setup and run for the default, configured
-absolute, configured relative, and hermetic `0` modes.
-
-Browser installation is explicit:
-
-```text
-testkit setup playwright
-testkit setup playwright --with-deps
-testkit setup playwright --force
-```
-
-The command invokes the authoritative public Playwright CLI with `install
-chromium --no-shell`. Normal execution never installs a browser. Installation
-resolution obtains `chromium.executablePath()` in a fresh process under the
-canonical registry environment and validates that public executable path.
-The runner waits for the HTTP endpoint before starting the task. Playwright
-launches Chromium when consumer tests request it; there is no additional
-browser launch or navigation for readiness. Native launch failures retain
-Playwright's cause and are classified as infrastructure failures. Consumer
-global setup and teardown remain intact. A real video flow proves FFmpeg
-capability without exposing a private FFmpeg path.
-
-k6 resolution maps the current platform and architecture to one fixed optional
-package and resolves its `./binary` export from the Testkit anchor. It validates
-the exact package name/version, declared target, containment, executable name,
-regular-file status, POSIX execute permission, and mandatory `k6 version`
-probe. The probe must report `EXPECTED_K6_VERSION` (`1.7.1`). There is no
-environment, consumer-package, or system-`PATH` fallback. Evidence records
-`installationKind: "direct-package"`, the package name, the package version,
-and the runtime-observed version; it does not claim that the installed binary
-was rehashed at launch.
-
-Linux k6 and Node/Vitest support glibc and musl. Playwright rejects musl before
-setup or execution. macOS supports arm64 and x64, and Windows supports x64 on
-Windows 10 or Windows Server 2016 and newer.
-
-## Trust and recovery
-
-| Material                         | Installer and authority                                   | Testkit check                                                                | Recovery                                                           |
-| -------------------------------- | --------------------------------------------------------- | ---------------------------------------------------------------------------- | ------------------------------------------------------------------ |
-| Root and JavaScript dependencies | npm plus the consumer lockfile                            | Root-anchored direct identity, version, entrypoint, and exercised capability | Repeat the consumer's frozen install                               |
-| k6 target                        | npm optional package                                      | Package/target/version, contained executable, mode, and version probe        | Reinstall including optionals                                      |
-| Chromium and FFmpeg              | Pinned Playwright installer and registry                  | Public Chromium path, native launch errors, and video capability             | `testkit setup playwright --force`; add `--with-deps` where needed |
-| k6 source and licenses           | npm package built and published from gfdelarue/testkit-k6 | npm integrity in the consumer lock; provenance and SBOM are review material  | Pin a new k6 package version in the root manifest and reinstall    |
-| Managed Node                     | Existing managed-toolchain pipeline                       | Existing archive and tree integrity checks                                   | Use the existing managed-Node repair path                          |
-
-npm authenticates registry tarballs represented in the consumer lock. It does
-not continuously authenticate every extracted file after installation. Each k6
-package ships `metadata/provenance.json` with its builder inputs and executable
-digest and an SPDX SBOM of the linked Go modules, and npm records provenance
-attestations at publish. Those are review material; the lock integrity is the
-boundary Testkit relies on.
-Likewise, Playwright owns browser revision mapping, download locking, and cache
-maintenance. This architecture intentionally does not promise byte-identical
-transitive JavaScript graphs or browser installations from the Testkit version
-alone.
-
-Process supervision remains independent of installation. Every invocation gets
-a fresh scope, bounded environment, cancellation/deadline handling, descendant
-ownership, result validation, evidence budgets, and cleanup. The adapter code
-is loaded through fixed typed internal imports after installation preflight;
-root Testkit version identifies that code.
-
-## Upgrading k6
-
-Testkit does not build k6. To change the k6 version, an extension, or a build
-input, cut a release in
-[gfdelarue/testkit-k6](https://github.com/gfdelarue/testkit-k6) by tagging
-`vX.Y.Z`. Its workflow builds the five executables, checks them against the
-expected digests in its contract, and publishes the six packages. Then bump
-the five pins in Testkit's root `package.json` to the new version in one
-commit and run `npm install`. If the k6 version changed, update
-`EXPECTED_K6_VERSION` in `src/engines/installations/k6.ts` in the same commit.
-The release contract rejects a root manifest whose five pins differ.
-
-## Installed consumer and release proof
-
-System acceptance installs the root Testkit tarball and fetches the pinned
-public engine packages directly from npm. CI transfers only the root tarball
-and its manifest to Ubuntu and Windows. Consumer lockfiles must match the
-engine versions and integrity values pinned in the checkout.
-
-The opt-in live compatibility tests mirror engine packages into a fixture
-registry to exercise controlled registry and lockfile scenarios. Their consumer
-manifest declares only `@gfdelarue/testkit`. They exercise the minimum and pinned-current
-npm 11 with self-consumed and reciprocal frozen hoisted locks, plus
-pinned-current nested and linked layouts. One checked-in portable hoisted lock
-is consumed without rewriting on all five supported targets.
-
-The orthogonal fixtures also prove hostile consumer tool conflicts, exact
-direct-version failures, broken-installation causes, omitted-optional
-diagnostics, no system-k6 fallback, Linux libc behavior, and physical presence
-of the selected k6 target and source packages. Real packed suites exercise k6,
-Node/Vitest, and Playwright after explicit browser setup, including the four
-Playwright registry modes.
-
-## Adding engines
-
-Future engines must add an explicit engine ID, profiles, a typed internal
-installation and executor, honest evidence, supported-host behavior, and real
-packed/native acceptance. They must not add a consumer-selectable internal
-package boundary or weaken another engine's native semantics.