@gfdelarue/testkit 0.3.0

package/docs/engine-architecture.md

@@ -0,0 +1,631 @@
+# 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.
+
+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. Windows does not expose an equivalent portable post-termination
+proof. 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.
+
+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.
+
+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.