@gfdelarue/testkit 0.3.0

package/testkit-config-schema.md

@@ -0,0 +1,718 @@
+# testkit.config.ts Reference
+
+`@gfdelarue/testkit` is configured with an optional repo-root `testkit.config.ts`.
+
+## Example
+
+```ts
+import { app, database, defineConfig, toolchain } from "@gfdelarue/testkit/config";
+
+export default defineConfig({
+  execution: {
+    taskConcurrency: 8,
+    fileTimeoutSeconds: 60,
+  },
+  profiles: {
+    http: {
+      raw: {
+        options: { vus: 1, iterations: 1 },
+      },
+    },
+  },
+  toolchains: {
+    frontendNode: toolchain.node({
+      cwd: "frontend",
+      detect: "auto",
+      install: "download",
+    }),
+  },
+  services: {
+    api: app.node({
+      cwd: ".",
+      entry: "src/index.ts",
+      port: 3004,
+      envFiles: [".env.testkit"],
+      database: database.postgres({
+        runtimeConnections: 20,
+        sourceSchema: database.schema.fromEnv("PRODUCTION_DATABASE_URL"),
+        template: {
+          inputs: ["db/schema.sql", "scripts/seed.ts"],
+          migrate: [{ kind: "sql-file", path: "db/schema.sql" }],
+          seed: [{ kind: "command", run: "npm run db:seed" }],
+          verify: [{ kind: "module", target: "src/testkit/verify-seed.ts#verifySeed" }],
+        },
+      }),
+      runtime: {
+        instances: 1,
+        maxConcurrentTasks: 4,
+      },
+    }),
+    frontend: app.next({
+      cwd: "frontend",
+      mode: "start",
+      port: 3000,
+      dependsOn: ["api"],
+      envFiles: ["frontend/.env.testkit"],
+      env: {
+        values: {
+          NEXT_PUBLIC_API_URL: "{baseUrl:api}",
+        },
+      },
+      runtime: {
+        instances: 1,
+        maxConcurrentTasks: 2,
+        toolchain: "frontendNode",
+      },
+    }),
+  },
+});
+```
+
+Every test file must declare its execution engine. The same file-local metadata
+may also declare skip and lock intent:
+
+```ts
+import { defineFile } from "@gfdelarue/testkit";
+
+export const testkit = defineFile({
+  engine: "k6",
+  skip: "Billing is currently unavailable locally",
+  locks: ["global-worker-loop"],
+});
+```
+
+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"`.
+
+The filename suffix determines the test type, and the engine catalog resolves
+the pair to 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`        |
+
+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.
+
+## Tooling Adapters
+
+`@gfdelarue/testkit` also ships package-owned helpers for the most common consumer
+tooling surfaces:
+
+- `@gfdelarue/testkit/drizzle`
+- `@gfdelarue/testkit/playwright`
+- `@gfdelarue/testkit/tooling/vitest`
+- `@gfdelarue/testkit/env`
+
+These helpers exist so consumer repos do not need repo-local `testkit`
+runtime-policy modules under `src/` just to cooperate with managed runs.
+
+## Top-Level Fields
+
+### `execution`
+
+Default execution settings for the repo.
+
+- `taskConcurrency`: maximum concurrent test tasks across the run (default `1`)
+- `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`.
+
+`--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
+when the CLI supplies an override.
+
+Schema-19 evidence retains its configured `run.workers` field. Observed
+`workerCount`, Playwright's own `workers`, `runtime.instances` and
+`runtime.maxConcurrentTasks` keep their existing meanings.
+
+`fileTimeoutSeconds` is the single per-file wall clock budget for the repo. Runtime
+helpers like `waitFor()` consume this budget automatically.
+
+### `lint`
+
+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.
+- 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.
+
+### `ui`
+
+Targets for Playwright `ui` files. Read through `createUiSandbox`,
+`resolveFrontendBaseUrl`, and `resolveBackendBaseUrl` from
+`@gfdelarue/testkit/playwright`.
+
+- `frontendBaseUrl`: browser target
+- `backendBaseUrl`: API target for `createAuthedApiClient`
+- `allowRemote`: permit non-loopback targets (default `false`)
+
+Sandbox options passed in the test win over this block. When neither sets a
+target, the frontend falls back to `TESTKIT_FRONTEND_BASE_URL` and then
+`BASE_URL`, which Testkit sets to the run's base URL for managed Playwright
+runs. The backend falls back to `TESTKIT_BACKEND_BASE_URL` and then
+`API_BASE_URL`. The `allowRemote` guard applies to every source.
+
+### `services`
+
+Map of service name to service config.
+
+### `toolchains`
+
+Optional reusable runtime toolchain profiles.
+
+Currently supported:
+
+- `toolchain.node({ ... })`
+
+Node toolchain fields:
+
+- `cwd`
+- `detect`
+  - `"auto"` or `"off"`
+- `install`
+  - `"require-host"` or `"download"`
+- `node`
+  - explicit Node version or range
+- `npm`
+  - 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.
+
+`detect: "auto"` checks the toolchain cwd for:
+
+- `package.json#volta.node`
+- `.nvmrc`
+- `.node-version`
+- `.tool-versions` (`nodejs`)
+- `package.json#engines.node`
+- `package.json#volta.npm`
+- `package.json#packageManager`
+- `package.json#engines.npm`
+
+### `profiles.http`
+
+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.
+
+## Service Fields
+
+### `local`
+
+Local runtime configuration.
+
+- `start`
+- `cwd`
+- `port`
+- `baseUrl`
+- `readyUrl`
+- `readyTimeoutMs`
+- `shutdownTimeoutMs`
+- `env`
+
+`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.
+
+`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.
+
+Both `app.node({ port: 3000, shutdownTimeoutMs: 5000 })` and
+`app.next({ port: 3000, shutdownTimeoutMs: 5000 })` place the option under `local`.
+
+Template tokens are supported in strings:
+
+- `{runtime}`
+- `{service}`
+- `{stateDir}`
+- `{prepareDir}`
+- `{lease}`
+- `{leaseDir}`
+- `{port}` / `{port:serviceName}`
+- `{baseUrl}` / `{baseUrl:serviceName}`
+- `{readyUrl}` / `{readyUrl:serviceName}`
+
+### `dependsOn`
+
+Runtime dependencies for service startup order.
+
+### `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.
+
+Environment names are validated case-insensitively. All engines reserve
+`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 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  |
+
+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).
+
+### `database`
+
+Use `database.postgres(...)` when a service needs Postgres, with `template`
+stages when you need explicit migrate/seed/verify behavior. Managed test runs
+materialize the database as host-local Docker Postgres.
+
+- `binding`
+- `maxConnections`
+- `reservedConnections`
+- `reset`
+- `roles`
+- `runtimeConnections`
+- `template.inputs`
+- `template.migrate`
+- `template.seed`
+- `template.verify`
+
+`binding` may be `shared` or `per-runtime`.
+`runtimeConnections` is the service runtime slot's Postgres connection budget.
+`maxConnections` and `reservedConnections` describe the backing host-local
+Postgres capacity used for scheduler admission.
+
+Template stages are ordered arrays of typed step objects:
+
+- `{ kind: "command", run: "npm run db:seed" }`
+- `{ 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.
+
+`verify` runs after template migrate/seed and must succeed before the template DB
+is cached for reuse.
+
+`roles` declares cluster-wide local roles through either `database.postgres(...)`
+or `database.fixture(...)`:
+
+```ts
+database.fixture({
+  roles: [
+    { name: "proof_app", login: false },
+    { name: "proof_reader", login: false },
+  ],
+  sourceSchema: database.schema.fromEnv("TESTKIT_SOURCE_SCHEMA_URL"),
+});
+```
+
+Each declaration requires a `name` and explicit `login: false`. No other
+attributes are accepted. An omitted list means no declared roles. Names retain
+their exact case and whitespace, and Testkit quotes them as SQL identifiers.
+Names must be non-empty valid Unicode, contain no NUL, and fit within 63 UTF-8
+bytes. Duplicate names, the resolved bootstrap username, and PostgreSQL-reserved
+role names are rejected. The reserved names are exactly `public`, `none`, and
+names beginning with lowercase `pg_`. Quoted names such as `PUBLIC` and
+`current_user` refer to ordinary roles and are accepted.
+
+Testkit creates missing roles in the owned local cluster before template lookup,
+source-schema replay, migrate, seed, and verify. Roles also precede template
+stages when source-schema import is disabled. Each role has `NOLOGIN`, `INHERIT`,
+`NOSUPERUSER`, `NOCREATEDB`, `NOCREATEROLE`, `NOREPLICATION`, `NOBYPASSRLS`, no
+password or expiration, and the default connection limit of `-1`. Testkit creates
+no memberships and copies no source role credentials or attributes. These
+declarations establish schema prerequisites. They do not reproduce production
+authorization behavior.
+
+Every provisioning attempt checks existing declared roles, including template
+cache hits. A role is reusable only if all declared local attributes match and
+it has no memberships or role-specific settings. A conflict reports the role and
+conflicting attribute names before replay or test execution. Testkit leaves the
+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.
+
+### `databaseFrom`
+
+Reuse another service's provisioned `DATABASE_URL`.
+
+### `runtime`
+
+Shared runtime topology and preparation behavior.
+
+- `instances`
+- `maxConcurrentTasks`
+- `toolchain`
+- `prepare.inputs`
+- `prepare.steps`
+
+`runtime.toolchain` may be either:
+
+- a string referencing a top-level `toolchains` profile
+- an inline `toolchain.node({ ... })` object
+
+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.
+
+### `skip`
+
+Repo-declared skip rules. Skipped files remain visible in run artifacts and
+`testkit.status.json` 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.
+
+```ts
+skip: {
+  files: [
+    {
+      path: "__testkit__/billing/billing.int.testkit.ts",
+      reason: "Billing is currently unavailable",
+    },
+  ],
+  suites: [
+    {
+      selector: "ui:billing",
+      reason: "Billing UI is placeholder-only",
+    },
+  ],
+}
+```
+
+- `files[].path`
+  - exact repo-relative file path
+- `files[].reason`
+  - required non-empty explanation recorded in artifacts
+- `suites[].selector`
+  - existing suite selector syntax, including typed selectors like `int:health`
+    and `ui:billing`
+- `suites[].reason`
+  - required non-empty explanation recorded in artifacts
+
+Use `--ignore-skip-rules` on the CLI to run matched files anyway.
+
+### `runtime`
+
+Service-local runtime instance settings.
+
+```ts
+runtime: {
+  instances: 1,
+  maxConcurrentTasks: 4,
+  prepare: {
+    inputs: ["frontend/src", "frontend/public", "frontend/package.json"],
+    steps: [{ kind: "command", run: "npm run build", cwd: "frontend" }],
+  },
+}
+```
+
+- `instances`
+  - number of reusable local runtime instances for that service graph
+- `maxConcurrentTasks`
+  - maximum number of concurrent file tasks admitted to each runtime instance
+  - omit it to leave concurrency bounded only by the outer `taskConcurrency` setting
+- `prepare`
+  - optional runtime-generation preparation hook
+  - runs once per runtime instance before local services start
+  - fingerprints declared `inputs` plus referenced step files/module inputs
+  - use this for build-once/start-many shared runtimes such as `next build` +
+    `next start`
+- `prepare.inputs`
+  - extra repo-relative inputs that should invalidate prepared artifacts when
+    they change
+- `prepare.steps`
+  - ordered lifecycle steps using the same step DSL as `database.template`
+  - each step supports `cwd` and `inputs`
+
+### `requirements`
+
+Service-local task lock rules.
+
+```ts
+requirements: {
+  suites: [
+    { selector: "ui:billing", locks: ["billing-ledger"] },
+  ],
+  files: [
+    {
+      path: "src/api/routes/__testkit__/crawls-worker-concurrency.int.testkit.ts",
+      locks: ["global-worker-loop"],
+    },
+  ],
+}
+```
+
+- `suites[].selector`
+  - typed selector like `int:health` or `ui:billing`
+- `suites[].locks`
+  - named locks required by matching files
+- `files[].path`
+  - exact repo-relative test file path
+- `files[].locks`
+  - named locks required by that file
+
+## Config Surface
+
+`@gfdelarue/testkit/config` exports:
+
+- `defineConfig`
+- `app.node(...)`
+- `app.next(...)`
+- `database.postgres(...)`
+- `database.fixture(...)`
+- `toolchain.node(...)`
+
+The `@gfdelarue/testkit/k6` subpath exports the k6 suite authoring surface:
+
+- `defineHttpSuite(...)`
+- `defineDalSuite(...)`
+- `defineDalFixtures(...)`
+
+`defineDalFixtures(...)` is the first-class DAL seeding model. DAL suites receive
+`fixtures` plus a deterministic `fixtureScope`, and that scope provides:
+
+- `id(label)` / `uuid(label)`
+- `slug(label)`
+- `email(label)`
+- `string(label, options)`
+- `token(label)`
+- `seed(kind, key, signature, create)`
+- `records()`
+
+## Discovery Conventions
+
+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
+
+Supported suffixes:
+
+- `*.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
+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`
+
+`testkit discover` exposes that inventory directly without running suites:
+
+- `testkit discover`
+  - compact human output grouped by service, type, and suite
+- `testkit discover --output-mode verbose`
+  - includes canonical paths, IDs, locks, dependencies, 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:
+
+- `id`
+- `path`
+- `service`
+- `suiteName`
+- `testType`
+- `engineId`
+- `profileId`
+- `contract`
+- `skipped`
+- `skipReason`
+- `locks`
+- `dependsOn`
+
+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`
+
+## Optional local Cloud verification rule
+
+```ts
+cloud?: {
+	verification?: {
+		minimumConfirmingRuns?: number;
+	};
+};
+```
+
+`cloud.verification.minimumConfirmingRuns` is an integer from 1 through 64,
+defaulting to 2. It controls whether Testkit submits a new `finding.verify`
+campaign report. It counts distinct full run IDs from available cited accepted
+receipts. Explicit unverified reports do not require confirming evidence.
+
+Cloud never reads or receives this config and independently enforces its
+GUI-configured minimum. A local rejection and a Cloud rejection both produce
+nonzero CLI status with structured diagnostics. See
+[Campaign reporting and recovery](docs/testkit-cloud-boundary.md#report-an-externally-executed-campaign)
+for examples, config directory selection, and exact retry behavior.