@gate-forge/witness 0.0.0-stage → 0.9.0

package/dist/adapter/contract-suite.js

@@ -0,0 +1,348 @@
+/**
+ * The runner-adapter contract suite (plan 2026-09-25 phase 0).
+ *
+ * One shared conformance suite every runner adapter must pass. The suite
+ * owns the ASSERTIONS; a {@link RunnerContractHost} owns only the
+ * runner mechanics (which files to materialize, how to spawn the runner,
+ * where its structured report lands). Nothing here parses a runner's
+ * output — the adapter does that, and the suite checks the adapter did
+ * it honestly.
+ *
+ * The suite is deliberately framework-free (no test runner import): each
+ * adapter's package runs {@link runRunnerAdapterContract} and asserts
+ * the returned violation list is empty. That keeps one implementation
+ * of "what a runner adapter must do" instead of N look-alike copies.
+ *
+ * Grading always runs through `superviseExecution`
+ * (`@gate-forge/core`) — the neutral completeness rules. The suite never
+ * invents a verdict of its own, so a contract pass means the adapter
+ * feeds the same enforcement point a Playwright run feeds.
+ */
+import { superviseExecution } from '@gate-forge/core';
+/** The session context a run wires for a planned test. */
+function sessionContext(overrides = {}) {
+    return {
+        witnessUrl: 'http://127.0.0.1:1',
+        runToken: 'contract-suite-run-token',
+        sessionId: 'contract-suite-session',
+        sessionToken: 'contract-suite-session-token',
+        sessionProxyUrl: 'http://127.0.0.1:1/session/contract-suite-session',
+        appBaseUrl: 'http://127.0.0.1:2',
+        ...overrides,
+    };
+}
+/**
+ * The identity key an adapter's outcome `logicalKey` encodes: the
+ * repo-relative file and the full title path, joined the way the engine
+ * already keys claim injections (`<file>#<titlePath.join('>')>`). The
+ * contract reads it back so a scenario can grade an outcome the adapter
+ * did not plan — which is exactly what an unplanned run produces.
+ */
+function identityOfOutcome(logicalKey) {
+    const hash = logicalKey.indexOf('#');
+    if (hash < 0)
+        return { file: logicalKey, titlePath: [] };
+    return {
+        file: logicalKey.slice(0, hash),
+        titlePath: logicalKey.slice(hash + 1).split('>'),
+    };
+}
+/** The identity key an enumerated test is joined on. */
+function identityOfTest(test) {
+    return `${test.project ?? '-'}\u0000${test.file}\u0000${test.titlePath.join('>')}`;
+}
+/** The identity key a scenario's planned test is joined on. */
+function identityOfScenario(scenario) {
+    return `${scenario.project ?? '-'}\u0000${scenario.file}\u0000${scenario.titlePath.join('>')}`;
+}
+/**
+ * The canonical scenario for one kind, with the host's own scenario
+ * naming when it declared one (runner-native file/title path; see
+ * {@link RunnerContractHost.scenario}).
+ */
+function scenarioFor(host, kind) {
+    return contractScenario(kind, { project: host.project, ...(host.scenario ?? {}) });
+}
+/** The planned instance for a scenario (the expected set, fixed pre-run). */
+function plannedOf(scenario) {
+    return scenario.expectedLogicalKeys.map((logicalKey) => ({
+        logicalKey,
+        project: scenario.project,
+        file: scenario.file,
+        titlePath: scenario.titlePath,
+        blockingAnnotations: [],
+    }));
+}
+/** Env names that must never reach a runner child through any channel. */
+const FORBIDDEN_CHILD_ENV = [
+    'GATEFORGE_WITNESS_VERIFIER_KEY',
+    'GATEFORGE_WITNESS_VERIFIER_KEY_FILE',
+    'GATEFORGE_OBLIGATIONS',
+    'GATEFORGE_OUTCOMES_FILE',
+    'GATEFORGE_ADAPTERS_DIR',
+    'GATEFORGE_CLASSIFICATIONS',
+    'GATEFORGE_ADAPTER_BASE_URL',
+];
+/** The scenarios every adapter is graded on, in a stable order. */
+export const CONTRACT_SCENARIOS = [
+    'pass',
+    'fail',
+    'skip',
+    'retry',
+    'unplanned',
+    'zero',
+];
+/** Builds the canonical scenario for one kind (single planned test). */
+export function contractScenario(kind, overrides = {}) {
+    const file = overrides.file ?? 'e2e/contract.spec.ts';
+    const titlePath = overrides.titlePath ?? ['contract'];
+    return {
+        kind,
+        file,
+        titlePath,
+        project: overrides.project ?? null,
+        expectedLogicalKeys: overrides.expectedLogicalKeys ?? [
+            `${file}#${titlePath.join('>')}`,
+        ],
+    };
+}
+/**
+ * Runs the full contract against one adapter.
+ *
+ * Every check is fail-closed: an adapter that throws, reports a missing
+ * field, or grades a dishonest run green produces a violation. The
+ * returned list is the whole result — an empty list is a pass.
+ *
+ * Args:
+ *   adapter: the adapter under test.
+ *   host: the runner mechanics for `adapter.runner`.
+ *
+ * Returns:
+ *   Promise<ContractViolation[]>: every contract case that failed.
+ */
+export async function runRunnerAdapterContract(adapter, host) {
+    const violations = [];
+    const fail = (name, detail) => {
+        violations.push({ case: name, detail });
+    };
+    if (host.runner !== adapter.runner) {
+        fail('runner-name-matches', `the contract host serves '${host.runner}' but the adapter reports '${adapter.runner}'`);
+        return violations;
+    }
+    if (adapter.capabilities.inventory !== 'available') {
+        fail('capabilities-declared', `a witness-producing adapter must declare inventory 'available' (got '${adapter.capabilities.inventory}')`);
+    }
+    if (adapter.capabilities.execute !== 'available') {
+        fail('capabilities-declared', `a witness-producing adapter must declare execute 'available' (got '${adapter.capabilities.execute}')`);
+    }
+    await checkEnumeration(adapter, host, fail);
+    await checkTagging(adapter, fail);
+    checkReportParsing(adapter, host, fail);
+    await checkExecute(adapter, host, fail);
+    for (const kind of CONTRACT_SCENARIOS) {
+        await checkScenario(adapter, host, kind, fail);
+    }
+    return violations;
+}
+/** The expected set must be listed before the run, and never faked empty. */
+async function checkEnumeration(adapter, host, fail) {
+    const scenario = scenarioFor(host, 'pass');
+    const root = await host.materialize(scenario);
+    let enumeration;
+    try {
+        enumeration = await adapter.enumerate(root);
+    }
+    catch (error) {
+        fail('enumeration-lists-the-expected-set', `enumerate threw: ${errorMessage(error)}`);
+        return;
+    }
+    if (enumeration.status !== 'discovered') {
+        fail('enumeration-lists-the-expected-set', `enumerate returned '${enumeration.status}' (${enumeration.detail}) for a project that has tests`);
+        return;
+    }
+    // Joined on IDENTITY (project + file + title path), the same join
+    // supervision uses — never on a key format the contract would have to
+    // predict for every runner.
+    const found = new Set(enumeration.tests.map(identityOfTest));
+    if (!found.has(identityOfScenario(scenario))) {
+        fail('enumeration-lists-the-expected-set', `enumerate omitted the planned test (saw [${[...found].join(' | ')}])`);
+    }
+    for (const test of enumeration.tests) {
+        if (test.file === '' || test.titlePath.length === 0) {
+            fail('enumeration-carries-identity', `enumerated test '${test.logicalKey}' has no file/titlePath identity — supervision cannot join it`);
+        }
+    }
+    const emptyRoot = await host.materialize(scenarioFor(host, 'zero'));
+    let empty;
+    try {
+        empty = await adapter.enumerate(emptyRoot);
+    }
+    catch (error) {
+        fail('zero-tests-never-reads-as-discovered', `enumerate threw: ${errorMessage(error)}`);
+        return;
+    }
+    if (empty.status !== 'unavailable' || empty.tests.length !== 0) {
+        fail('zero-tests-never-reads-as-discovered', `a project with no runnable tests must enumerate as 'unavailable', got '${empty.status}' with ${String(empty.tests.length)} test(s)`);
+    }
+}
+/**
+ * The tag must vary per session: a constant tag is unattributed traffic
+ * wearing a tag, which is exactly the rule the witness already enforces
+ * for traffic that bypasses every session channel.
+ */
+async function checkTagging(adapter, fail) {
+    const first = adapter.childEnv({ logicalKey: 'a#one', frameworkId: 'one', project: null }, sessionContext());
+    const second = adapter.childEnv({ logicalKey: 'a#two', frameworkId: 'two', project: null }, sessionContext({ sessionId: 'contract-suite-session-2', sessionToken: 'contract-suite-session-token-2', sessionProxyUrl: 'http://127.0.0.1:1/session/contract-suite-session-2' }));
+    if (first.tagChannel === 'none' || second.tagChannel === 'none') {
+        fail('traffic-is-tagged', `childEnv reported tagChannel 'none' — a runner whose traffic cannot be attributed can never produce witness evidence`);
+    }
+    const identity = new Set([...first.identityVars, ...second.identityVars]);
+    if (identity.size === 0) {
+        fail('traffic-is-tagged', 'childEnv declared no identity variables — nothing tags the test');
+        return;
+    }
+    const differing = [...identity].filter((name) => first.vars[name] !== second.vars[name]);
+    if (differing.length === 0) {
+        fail('tag-varies-per-session', `no identity variable (${[...identity].join(', ')}) differs between two sessions — every test would be attributed to the same session`);
+    }
+    for (const [name, value] of Object.entries({ ...first.vars, ...second.vars })) {
+        if (FORBIDDEN_CHILD_ENV.includes(name)) {
+            fail('child-env-carries-no-parent-side-wiring', `childEnv leaked parent-side '${name}' to the runner child`);
+        }
+        if (value === '') {
+            fail('child-env-carries-no-parent-side-wiring', `childEnv emitted an empty value for '${name}'`);
+        }
+    }
+    const channel = first.tagChannel;
+    if (channel === 'session-proxy' && (first.vars['GATEFORGE_SESSION_PROXY_URL'] ?? '') === '') {
+        fail('traffic-is-tagged', "tagChannel 'session-proxy' requires GATEFORGE_SESSION_PROXY_URL in the child env");
+    }
+}
+/** An unreadable report is never a green run, and never a fabricated set. */
+function checkReportParsing(adapter, host, fail) {
+    const garbage = adapter.parseResults({ processExit: 0, report: '' });
+    if (garbage.complete) {
+        fail('unreadable-report-fails-closed', 'parseResults read an empty report as a complete run — a missing report never proves anything');
+    }
+    if (garbage.outcomes.length !== 0) {
+        fail('unreadable-report-fails-closed', `parseResults invented ${String(garbage.outcomes.length)} outcome(s) from an empty report`);
+    }
+    const noExit = adapter.parseResults({ processExit: null, report: '' });
+    if (noExit.complete) {
+        fail('unreadable-report-fails-closed', 'a run with no exit status is incomplete, never complete');
+    }
+    // A row the adapter cannot identify belongs to NO test: untagged
+    // traffic is never attributed, which is the same rule the witness
+    // applies to a request that bypassed every session channel.
+    const untagged = adapter.parseResults({ processExit: 0, report: host.untaggedReport() });
+    if (untagged.complete) {
+        fail('untagged-traffic-is-not-attributed', 'a report whose rows carry no runner framework id graded complete — a test the adapter cannot identify is never attributed to a test');
+    }
+}
+/**
+ * The job-3 check: the adapter must be able to RUN a suite itself, not
+ * only read reports. One real supervised `execute` over the `pass`
+ * project, graded exactly like a scenario.
+ */
+async function checkExecute(adapter, host, fail) {
+    const name = 'execute-runs-a-suite';
+    const scenario = scenarioFor(host, 'pass');
+    const root = await host.materialize(scenario);
+    const request = host.executeRequest(root, scenario);
+    let envelope;
+    try {
+        envelope = await adapter.execute(request);
+    }
+    catch (error) {
+        fail(name, `execute threw: ${errorMessage(error)}`);
+        return;
+    }
+    if (envelope.outcomes.length === 0) {
+        fail(name, 'execute reported no outcomes for a project that has a passing test');
+        return;
+    }
+    const graded = superviseExecution(plannedOf(scenario), {
+        processExit: envelope.processExit,
+        complete: envelope.complete,
+        ...(envelope.incompleteDetail !== undefined ? { incompleteDetail: envelope.incompleteDetail } : {}),
+        outcomes: envelope.outcomes.map((outcome) => ({
+            ...identityOfOutcome(outcome.logicalKey),
+            logicalKey: outcome.logicalKey,
+            project: outcome.project,
+            status: outcome.status,
+            attempt: outcome.attempt,
+            expectedFailure: outcome.expectedFailure ?? false,
+        })),
+        fixtureOutcome: envelope.fixtureOutcome ?? 'unknown',
+        shards: envelope.shards ?? null,
+        retriesDetected: envelope.retriesDetected ?? false,
+        ...(envelope.retriesDetail !== undefined ? { retriesDetail: envelope.retriesDetail } : {}),
+    });
+    if (!graded.complete) {
+        fail(name, `execute ran the passing project but supervision blocked it: ${graded.findings[0]?.detail ?? ''}`);
+    }
+}
+/** One scenario: run it and assert supervision blocks exactly as it must. */
+async function checkScenario(adapter, host, kind, fail) {
+    const name = `scenario-${kind}`;
+    const scenario = scenarioFor(host, kind);
+    const root = await host.materialize(scenario);
+    let observation;
+    try {
+        observation = await host.run(adapter, root, scenario);
+    }
+    catch (error) {
+        fail(name, `the host could not run the scenario: ${errorMessage(error)}`);
+        return;
+    }
+    const planned = plannedOf(scenario);
+    const graded = superviseExecution(planned, {
+        processExit: observation.envelope.processExit,
+        complete: observation.envelope.complete,
+        ...(observation.envelope.incompleteDetail !== undefined
+            ? { incompleteDetail: observation.envelope.incompleteDetail }
+            : {}),
+        outcomes: observation.envelope.outcomes.map((outcome) => ({
+            ...identityOfOutcome(outcome.logicalKey),
+            logicalKey: outcome.logicalKey,
+            project: outcome.project,
+            status: outcome.status,
+            attempt: outcome.attempt,
+            expectedFailure: outcome.expectedFailure ?? false,
+        })),
+        fixtureOutcome: observation.envelope.fixtureOutcome ?? 'unknown',
+        shards: observation.envelope.shards ?? null,
+        retriesDetected: observation.envelope.retriesDetected ?? false,
+        ...(observation.envelope.retriesDetail !== undefined
+            ? { retriesDetail: observation.envelope.retriesDetail }
+            : {}),
+    });
+    const causes = graded.findings.map((finding) => finding.cause);
+    switch (kind) {
+        case 'pass':
+            if (!graded.complete) {
+                fail(name, `a complete first-attempt passing run was blocked: ${graded.findings[0]?.detail ?? ''}`);
+            }
+            if (observation.envelope.outcomes.length !== scenario.expectedLogicalKeys.length) {
+                fail(name, `a passing run reported ${String(observation.envelope.outcomes.length)} outcome(s) for ${String(scenario.expectedLogicalKeys.length)} planned test(s)`);
+            }
+            return;
+        case 'zero':
+            if (graded.complete) {
+                fail(name, 'a run that executed no test graded complete — nothing executed proves nothing');
+            }
+            return;
+        default:
+            if (graded.complete) {
+                fail(name, `a '${kind}' run graded complete — it must block`);
+            }
+            if (!causes.includes('TEST_NOT_EXECUTED') && !causes.includes('TEST_FAILED') && !causes.includes('RUN_INCOMPLETE')) {
+                fail(name, `a '${kind}' run blocked with no typed cause (saw [${causes.join(', ')}])`);
+            }
+    }
+}
+/** Single-line message of an unknown thrown value. */
+function errorMessage(error) {
+    return error instanceof Error ? error.message : String(error);
+}
+//# sourceMappingURL=contract-suite.js.map

package/dist/adapter/contract-suite.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"contract-suite.js","sourceRoot":"","sources":["../../src/adapter/contract-suite.ts"],"names":[],"mappings":"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"}

package/dist/adapter/contract.d.ts

@@ -0,0 +1,266 @@
+/**
+ * The runner-adapter contract (plan 2026-09-25 phase 0): the four jobs
+ * every test runner performs so the witness can produce the SAME trusted
+ * evidence for it.
+ *
+ * WHY this shape. The witness is an HTTP proxy plus a DB/queue reader; a
+ * proxy does not care who sends the traffic. Everything runner-specific
+ * collapses into four operations:
+ *
+ * 1. `enumerate()` — LIST the tests BEFORE the run. The expected set is
+ *    fixed first (the same rule the Playwright path already follows).
+ * 2. `childEnv()` — TAG every request with the test identity: a
+ *    per-test session proxy URL (what Playwright uses today) or a signed
+ *    session header.
+ * 3. `execute()` — RUN the suite under trusted supervision.
+ * 4. `parseResults()` — READ the outcome in a structured format (native
+ *    JSON or JUnit XML). Terminal colors are never parsed.
+ *
+ * Honesty rules baked into the contract (frozen JSON keys, cause codes
+ * and exit codes — additions only):
+ * - A runner's own "passed" is never authority. `parseResults` produces
+ *   reporter INPUT; the verdict comes from `superviseExecution` in
+ *   `@gate-forge/core` plus the witness-issued session trace.
+ * - An empty enumeration is `unavailable`, never a discovered run of
+ *   zero tests: nothing executed proves nothing.
+ * - A runner that cannot attribute its traffic (no session tag) says so
+ *   with `tagChannel: 'none'`; the supervisor then refuses to attribute
+ *   ANY exchange to that test instead of guessing.
+ * - `execute` and `parseResults` share the envelope so a caller can read
+ *   a runner's report without spawning the runner.
+ */
+import type { RunnerCapabilities, RunnerExecutionEnvelope } from '@gate-forge/core';
+/** Runner name the contract's cross-references accept today. */
+export type RunnerName = 'playwright' | 'cypress' | 'pytest' | 'vitest' | (string & {});
+/**
+ * How a runner's traffic is attributed to one test.
+ *
+ * - `session-proxy`: the test addresses the witness through a per-test
+ *   session proxy prefix (Playwright's `page`-level proxy today).
+ * - `signed-header`: the test carries a per-test signed session header
+ *   on every request (no proxy address to rewrite).
+ * - `none`: the runner cannot tag its traffic. Traffic is NEVER
+ *   attributed to a test in this mode — the same fail-closed rule the
+ *   Playwright path applies to "bypassed every session channel".
+ */
+export type RunnerTagChannel = 'session-proxy' | 'signed-header' | 'none';
+/**
+ * One test the runner is expected to run, enumerated BEFORE the run.
+ *
+ * Mirrors `PlannedInstanceInput` from `@gate-forge/core` so the
+ * expected set crosses into supervision without a lossy re-shape.
+ */
+export interface RunnerTestIdentity {
+    /** Stable logical key (the identity join key). */
+    logicalKey: string;
+    /** Runner project, or null when the runner reports none. */
+    project: string | null;
+    /** Repo-relative posix file (the identity join key). */
+    file: string;
+    /** Full title path (the identity join key). */
+    titlePath: readonly string[];
+    /** Blocking annotations observed pre-run (`.skip` / `.only` / `.fixme`). */
+    blockingAnnotations: readonly string[];
+    /**
+     * The runner's own id for this test, EXACTLY as the runner-side
+     * reporter writes it into the lifecycle spool (additive, plan
+     * 2026-09-25 runner-agnostic evidence): the pytest node id, the
+     * `<file>#<title path>` key for vitest and cypress. Optional — the
+     * trusted supervisor registers the expected set with it so the
+     * witness-side trace names the same identities the child will spool;
+     * a missing id falls back to the logical key.
+     */
+    frameworkId?: string;
+}
+/** Outcome of one `enumerate()` call (never a silent empty success). */
+export interface RunnerEnumeration {
+    /**
+     * `discovered` only when the runner reported a real, non-empty test
+     * set. A zero-test run, a missing runner, and a collection error are
+     * all `unavailable` — nothing executed proves nothing.
+     */
+    status: 'discovered' | 'unavailable';
+    /** Single-cause detail (bounded), always populated when unavailable. */
+    detail: string;
+    /** The enumerated tests (empty exactly when `status` is `unavailable`). */
+    tests: readonly RunnerTestIdentity[];
+    /** Runner version the enumeration observed, when the runner reports one. */
+    engineVersion?: string;
+}
+/** The one test a `childEnv()` call is tagging. */
+export interface RunnerSessionTag {
+    /** The logical key the traffic will be attributed to. */
+    logicalKey: string;
+    /** The runner's own instance id for this test (spec id, node id). */
+    frameworkId: string;
+    /** Runner project, or null. */
+    project: string | null;
+}
+/**
+ * Run-scoped wiring the adapter needs to build a child's environment.
+ *
+ * Every field is NON-SECRET: the witness's run token and the per-test
+ * session token are the only signing material a test may hold, and
+ * neither can mint, seal or re-seal a session (the supervisor's channel
+ * is verifier-key authenticated and unreachable from the suite).
+ */
+export interface RunnerChildEnvContext {
+    /** Absolute witness base URL the child talks to. */
+    witnessUrl: string;
+    /** Run token the child presents on witness calls. */
+    runToken: string;
+    /** Per-test session id the supervisor opened for the tagged test. */
+    sessionId: string;
+    /** Per-test session token the child presents for interval/HTTP calls. */
+    sessionToken: string;
+    /** Absolute per-test session proxy prefix (empty for header tagging). */
+    sessionProxyUrl: string;
+    /** Absolute base URL of the application under test. */
+    appBaseUrl: string;
+}
+/** The environment one tagged test's process must see. */
+export interface RunnerChildEnv {
+    /**
+     * The variables to ADD to the runner child. The adapter never returns
+     * a wholesale `process.env` copy: the caller owns the allowlist.
+     */
+    vars: Readonly<Record<string, string>>;
+    /** How the child's traffic is attributed (see {@link RunnerTagChannel}). */
+    tagChannel: RunnerTagChannel;
+    /**
+     * The variable names carrying the TEST IDENTITY. At least one must
+     * differ between two sessions of the same run — the contract suite
+     * asserts exactly that, because a constant tag is unattributed
+     * traffic wearing a tag.
+     */
+    identityVars: readonly string[];
+    /**
+     * The runner-side mechanism the tag travels on (a support-file
+     * injection, a plugin fixture, an interceptor). Diagnostic: it is what
+     * a failing run's report should name.
+     */
+    mechanism: string;
+}
+/** The raw, structured results of one runner execution. */
+export interface RunnerRawResults {
+    /** The runner process exit status (null when it never started). */
+    processExit: number | null;
+    /**
+     * The working directory the report's file paths are relative to, when
+     * the runner reports ABSOLUTE paths (some JSON reporters do). Absent
+     * means the report's paths are already repo-relative — or that the
+     * adapter attributes nothing, rather than guessing a base.
+     */
+    cwd?: string;
+    /**
+     * The runner's structured report: native JSON, JUnit XML, or the
+     * witness-facing outcomes document. Never terminal output.
+     */
+    report: string;
+    /** True when the runner reported the run was sharded. */
+    sharded?: boolean;
+    /** Shard completeness detail, when the runner reported shards. */
+    shardDetail?: string;
+    /**
+     * Setup/teardown/runner-body outcome the runner reported. Absent =
+     * unknown, which grades fail-closed downstream.
+     */
+    fixtureOutcome?: 'passed' | 'failed' | 'unknown';
+}
+/** What `execute()` is asked to run. */
+export interface RunnerExecuteRequest {
+    /** Exact logical keys selected for the run (never a wildcard). */
+    logicalKeys: readonly string[];
+    /** Absolute run-state directory (excluded from tracked inputs). */
+    stateDir: string;
+    /** Run id the execution binds to. */
+    runId: string;
+    /** Whole-run wall-clock bound; expiry is an incomplete run. */
+    timeoutMs: number;
+    /** Absolute repo root the runner configuration lives under. */
+    cwd: string;
+    /**
+     * Selection mode (additive; absent = `full-relevant-suite`, whose
+     * execution is byte-identical to before). A `named-selection` run
+     * executes ONLY the named tests: the adapter narrows below file
+     * granularity wherever its runner can, and any test it cannot
+     * exclude is reported, never silently graded.
+     */
+    mode?: 'full-relevant-suite' | 'mapped-selection' | 'named-selection';
+    /**
+     * Exact repo-relative `file:line` locations of the selected tests, as
+     * the plan fixed them before the run. Playwright executes exactly
+     * these. Undefined = file granularity.
+     */
+    testLocations?: readonly string[];
+    /**
+     * The runner's own project names to run, exactly as `enumerate`
+     * reported them. Part of the identity join key, so a run that does
+     * not select them grades its outcomes against a different identity
+     * than the expected set was fixed with.
+     */
+    projects?: readonly string[];
+}
+/**
+ * The runner-adapter contract.
+ *
+ * @typeParam TReport - the runner's native report shape, when an adapter
+ *   wants to expose it (the contract itself only needs the text).
+ */
+export interface RunnerAdapter<TReport = unknown> {
+    /** Runner name this adapter serves, e.g. `cypress`. */
+    readonly runner: RunnerName;
+    /** Declared capabilities — callers honor, never assume. */
+    readonly capabilities: RunnerCapabilities;
+    /**
+     * Job 1: lists the runner's tests BEFORE the run.
+     *
+     * Args:
+     *   cwd: absolute repo root the runner configuration lives under.
+     *
+     * Returns:
+     *   Promise<RunnerEnumeration>: the expected set, or an `unavailable`
+     *   verdict with a single cause. Never an empty `discovered` list.
+     */
+    enumerate(cwd: string): Promise<RunnerEnumeration>;
+    /**
+     * Job 2: builds the environment that tags one test's traffic.
+     *
+     * Args:
+     *   session: the test being tagged.
+     *   context: run-scoped, non-secret witness wiring.
+     *
+     * Returns:
+     *   RunnerChildEnv: the variables plus the channel the tag travels on.
+     */
+    childEnv(session: RunnerSessionTag, context: RunnerChildEnvContext): RunnerChildEnv;
+    /**
+     * Job 3: runs the suite under trusted supervision.
+     *
+     * Args:
+     *   request: the exact selection, run identity, and wall-clock bound.
+     *
+     * Returns:
+     *   Promise<RunnerExecutionEnvelope>: the structured outcome envelope
+     *   (a runner exit code alone is never a gate result).
+     */
+    execute(request: RunnerExecuteRequest): Promise<RunnerExecutionEnvelope>;
+    /**
+     * Job 4: reads one structured report into the outcome envelope.
+     *
+     * Args:
+     *   raw: the runner's structured report plus its exit status.
+     *
+     * Returns:
+     *   RunnerExecutionEnvelope: reporter INPUT for supervision, never a
+     *   verdict. An unreadable report is `complete: false`.
+     */
+    parseResults(raw: RunnerRawResults): RunnerExecutionEnvelope;
+    /**
+     * The runner's native parsed report, for callers that need the
+     * runner-specific shape (diagnostics surfaces). Optional: an adapter
+     * whose report is only ever read as an envelope omits it.
+     */
+    parseReport?(raw: RunnerRawResults): TReport;
+}
+//# sourceMappingURL=contract.d.ts.map

package/dist/adapter/contract.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"contract.d.ts","sourceRoot":"","sources":["../../src/adapter/contract.ts"],"names":[],"mappings":"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"}

package/dist/adapter/contract.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=contract.js.map

package/dist/adapter/contract.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"contract.js","sourceRoot":"","sources":["../../src/adapter/contract.ts"],"names":[],"mappings":""}

package/dist/adapter/index.d.ts

@@ -0,0 +1,8 @@
+/**
+ * `@gate-forge/witness/adapter` — the runner-adapter contract and the
+ * conformance suite every runner must pass (plan 2026-09-25 phase 0).
+ */
+export type { RunnerAdapter, RunnerChildEnv, RunnerChildEnvContext, RunnerEnumeration, RunnerExecuteRequest, RunnerName, RunnerRawResults, RunnerSessionTag, RunnerTagChannel, RunnerTestIdentity, } from './contract.js';
+export type { ContractObservation, ContractScenario, ContractScenarioKind, ContractViolation, RunnerContractHost, } from './contract-suite.js';
+export { CONTRACT_SCENARIOS, contractScenario, runRunnerAdapterContract } from './contract-suite.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/adapter/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/adapter/index.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,YAAY,EACV,aAAa,EACb,cAAc,EACd,qBAAqB,EACrB,iBAAiB,EACjB,oBAAoB,EACpB,UAAU,EACV,gBAAgB,EAChB,gBAAgB,EAChB,gBAAgB,EAChB,kBAAkB,GACnB,MAAM,eAAe,CAAC;AACvB,YAAY,EACV,mBAAmB,EACnB,gBAAgB,EAChB,oBAAoB,EACpB,iBAAiB,EACjB,kBAAkB,GACnB,MAAM,qBAAqB,CAAC;AAC7B,OAAO,EAAE,kBAAkB,EAAE,gBAAgB,EAAE,wBAAwB,EAAE,MAAM,qBAAqB,CAAC"}