vdelta 0.2.2 → 0.3.0

package/dist/adapter.d.ts

@@ -0,0 +1,155 @@
+/**
+ * The adapter seam. The core (`run` / `compare` / `gate`) never reaches into a
+ * concrete runner: it resolves an {@link Adapter} descriptor from the registry
+ * (`src/adapters/registry.ts`) and talks to it through this interface only.
+ *
+ * Every type here is a promotion of a shape that already existed on the vitest
+ * side, so the seam is a rearrangement of what already ran rather than a new
+ * mechanism: {@link RecordContext} is the recorder's context object verbatim,
+ * {@link DetectResult} is the runner-token scan's return value,
+ * {@link InstrumentedChild} is the argv/env injection `vdelta run` already
+ * performed, and {@link CommandSelector} is the §6.4 inclusion-intent split.
+ *
+ * Dependency direction inside an adapter is one-way: `detect` / `instrument` /
+ * `splitCommandSelector` know only the runner's *argv surface*, `record` knows
+ * only its *structured channel*.
+ */
+import type { RunRecord } from './schema.js';
+/**
+ * The three-valued capability convention (§3.4). The value set is closed
+ * (§14); capability *names* stay open so an adapter may declare its own.
+ */
+export declare const CAPABILITY_VALUES: readonly ["pass", "fail", "unsupported"];
+export type CapabilityValue = (typeof CAPABILITY_VALUES)[number];
+export type CapabilityDeclaration = Readonly<Record<string, CapabilityValue>>;
+/**
+ * Where the adapter's structured channel lands. A single capture file is the
+ * only kind today; per-process channels are follow-up F-2, at which point the
+ * channel's creation and teardown move from the core into the adapter.
+ */
+export interface CaptureChannel {
+    readonly kind: 'single-file';
+    readonly path: string;
+}
+/** What {@link Adapter.detect} returns; `null` means only "not mine". */
+export interface DetectResult {
+    /** argv index of the runner binary token. */
+    readonly tokenIndex: number;
+}
+/**
+ * The instrumented child invocation. `argv` fully replaces the caller's argv;
+ * `env` carries only the additions to layer onto the inherited environment.
+ */
+export interface InstrumentedChild {
+    readonly argv: readonly string[];
+    readonly env: Readonly<Record<string, string>>;
+}
+/** The §6.4 inclusion-intent split of a child argv (§5.1 canonical command). */
+export interface CommandSelector {
+    command: string[];
+    selector: string[];
+}
+/**
+ * Everything the recorder needs beyond the runner's own structured channel:
+ * repo identity, provenance, the canonicalized invocation and the child's raw
+ * streams. Runner-neutral by construction — no field carries runner vocabulary.
+ */
+export interface RecordContext {
+    worktree: string;
+    repoIdentity: string;
+    branch: string;
+    cwdRel: string;
+    command: string[];
+    selector: string[];
+    head: string | null;
+    treeDigest: string;
+    dirtyDiffDigest: string;
+    childExitCode: number;
+    rawStdout: string;
+    rawStderr: string;
+    adapterVersion: string;
+    recordedAtMs: number;
+}
+/**
+ * The capability names a declaration says the composition cannot meet, sorted
+ * (§4.2 disclosure rule). `unsupported` is the only degraded value: `fail`
+ * means the capability is met and the observation is red, not that evidence is
+ * missing. This is what a report's `failure_evidence.degraded_capabilities`
+ * and every per-test claim that carries it are derived from.
+ */
+export declare function degradedCapabilities(caps: CapabilityDeclaration): string[];
+/** §6.4 selector containment, as declared by an adapter that can decide it. */
+export type SelectorRelation = 'equal' | 'subset' | 'superset' | 'disjoint' | 'unknown';
+export type SelectorMatch = 'yes' | 'no' | 'unknown';
+/**
+ * The capture channel is unreadable, of an unsupported version, or malformed.
+ * The core maps this onto degraded raw passthrough (INV-5): veridelta is never
+ * worse than its absence.
+ */
+export declare class AdapterCaptureError extends Error {
+    constructor(message: string);
+}
+export interface Adapter {
+    readonly name: string;
+    readonly compositionId: string;
+    readonly declaredCapabilities: CapabilityDeclaration;
+    readonly declaredEnvVars: readonly string[];
+    /**
+     * Whether this argv is this adapter's invocation. `null` means "not mine"
+     * and nothing else — an adapter alone can never conclude "this is a wrapper
+     * command"; that is a registry-level conclusion.
+     */
+    detect(argv: readonly string[]): DetectResult | null;
+    /**
+     * The env that points this adapter's reporter at the channel.
+     *
+     * Exported to the child *whether or not* the adapter claimed the argv. A
+     * reporter registered in the project's own configuration (spec §4.2 ambient
+     * recording — the RECOMMENDED deployment) has no other way to find the
+     * channel, and it is deliberately inert without it. Gating this on argv
+     * detection would silently stop recording every wrapper invocation
+     * (`vdelta run -- npm test`), which is exactly the stream-severing §4.2
+     * warns about.
+     *
+     * The channel is one file today, so two adapters pointing their reporters at
+     * it would race (last writer wins). That is the pre-existing single-channel
+     * hazard follow-up F-2 exists for, not something detection was protecting
+     * against — pre-seam this env was exported unconditionally.
+     */
+    channelEnv(channel: CaptureChannel): Readonly<Record<string, string>>;
+    /**
+     * The reporter-injected argv plus the env additions for the child. Only
+     * applied when this adapter recognizes the argv: injecting runner flags into
+     * a command that is not that runner kills it outright (INV-5 — veridelta is
+     * never worse than its absence), and a wrapper cannot forward them anyway
+     * (§4.3-7). {@link channelEnv} is what covers the uninstrumented case.
+     */
+    instrument(argv: readonly string[], channel: CaptureChannel): InstrumentedChild;
+    /**
+     * Whether the capture now sitting in the channel is this adapter's, decided
+     * on the channel's own payload rather than on argv.
+     *
+     * Consulted only when no adapter claimed the argv: the ambient case, where
+     * the reporter came from the project's configuration instead of from
+     * {@link instrument}, so the argv carries no evidence of which runner ran.
+     * MUST NOT throw — an absent, empty, foreign or malformed channel is simply
+     * not a claim. A claim asserts authorship only; a payload this adapter owns
+     * but cannot use still fails in {@link record}, with its own diagnostic.
+     */
+    claimsCapture(channel: CaptureChannel): boolean;
+    /** §6.4 inclusion intent, decided purely on the runner's own CLI surface. */
+    splitCommandSelector(argv: readonly string[]): CommandSelector;
+    /**
+     * Read the capture channel, validate it, and build the Run record. Parsing
+     * and version checking belong to the *adapter* — the core knows nothing
+     * about the channel's payload. Failures throw {@link AdapterCaptureError},
+     * which the core maps onto degraded passthrough.
+     */
+    record(channel: CaptureChannel, ctx: RecordContext): RunRecord;
+    /**
+     * §6.4, optional. Undeclared means every relation is `unknown`, which is
+     * exactly the comparator's pre-seam behavior (`selector-relation-unknown`).
+     */
+    selectorRelation?(a: readonly string[], b: readonly string[]): SelectorRelation;
+    selectorMatches?(selector: readonly string[], testId: string): SelectorMatch;
+}

package/dist/adapter.js

@@ -0,0 +1,30 @@
+/**
+ * The three-valued capability convention (§3.4). The value set is closed
+ * (§14); capability *names* stay open so an adapter may declare its own.
+ */
+export const CAPABILITY_VALUES = ['pass', 'fail', 'unsupported'];
+/**
+ * The capability names a declaration says the composition cannot meet, sorted
+ * (§4.2 disclosure rule). `unsupported` is the only degraded value: `fail`
+ * means the capability is met and the observation is red, not that evidence is
+ * missing. This is what a report's `failure_evidence.degraded_capabilities`
+ * and every per-test claim that carries it are derived from.
+ */
+export function degradedCapabilities(caps) {
+    return Object.entries(caps)
+        .filter(([, value]) => value === 'unsupported')
+        .map(([name]) => name)
+        .sort();
+}
+/**
+ * The capture channel is unreadable, of an unsupported version, or malformed.
+ * The core maps this onto degraded raw passthrough (INV-5): veridelta is never
+ * worse than its absence.
+ */
+export class AdapterCaptureError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'AdapterCaptureError';
+    }
+}
+//# sourceMappingURL=adapter.js.map

package/dist/adapter.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"adapter.js","sourceRoot":"","sources":["../src/adapter.ts"],"names":[],"mappings":"AAkBA;;;GAGG;AACH,MAAM,CAAC,MAAM,iBAAiB,GAAG,CAAC,MAAM,EAAE,MAAM,EAAE,aAAa,CAAU,CAAA;AAyDzE;;;;;;GAMG;AACH,MAAM,UAAU,oBAAoB,CAAC,IAA2B;IAC9D,OAAO,MAAM,CAAC,OAAO,CAAC,IAAI,CAAC;SACxB,MAAM,CAAC,CAAC,CAAC,EAAE,KAAK,CAAC,EAAE,EAAE,CAAC,KAAK,KAAK,aAAa,CAAC;SAC9C,GAAG,CAAC,CAAC,CAAC,IAAI,CAAC,EAAE,EAAE,CAAC,IAAI,CAAC;SACrB,IAAI,EAAE,CAAA;AACX,CAAC;AAWD;;;;GAIG;AACH,MAAM,OAAO,mBAAoB,SAAQ,KAAK;IAC5C,YAAY,OAAe;QACzB,KAAK,CAAC,OAAO,CAAC,CAAA;QACd,IAAI,CAAC,IAAI,GAAG,qBAAqB,CAAA;IACnC,CAAC;CACF"}

package/dist/adapters/registry.d.ts

@@ -0,0 +1,72 @@
+/**
+ * The adapter registry: the one place the core is allowed to know which
+ * concrete adapters exist. A static array in a fixed order — no registration
+ * API until adapters become external plugins.
+ *
+ * Detection is deliberately *total*: every adapter's `detect` is evaluated and
+ * the outcome distinguishes zero, one, and several matches, because only the
+ * registry can tell "no adapter recognizes this argv" (a wrapper command such
+ * as `pnpm test`) from "this adapter is not the one". Zero and ambiguous both
+ * stay recordable-but-degraded at the call site, never a hard failure (INV-5).
+ */
+import type { Adapter, CaptureChannel, DetectResult } from '../adapter.js';
+/** Every known adapter, in a deterministic order. */
+export declare const ADAPTERS: readonly Adapter[];
+/** Known adapter names, in registry order — for diagnostics and `--adapter`. */
+export declare function adapterNames(adapters?: readonly Adapter[]): readonly string[];
+/**
+ * Look an adapter up by name without failing. Callers that must stay
+ * fail-closed rather than abort — the comparator and the gate, which resolve
+ * `record.instrument.adapter` from records they did not write — use this.
+ */
+export declare function findAdapter(name: string, adapters?: readonly Adapter[]): Adapter | undefined;
+/**
+ * Resolve an explicitly requested adapter name. An unknown name is user input
+ * error, not a degradation path: silently passing through would turn a typo
+ * into a silent loss of recording, which is the opposite of INV-5's intent.
+ */
+export declare function resolveAdapter(name: string, adapters?: readonly Adapter[]): Adapter;
+/**
+ * The env additions every registered adapter needs to find the channel, in
+ * registry order. Exported to the child unconditionally, detection or no
+ * detection: a reporter configured in the project itself (spec §4.2 ambient
+ * recording) is inert without it, and pre-seam `vdelta run` set it on every
+ * child for exactly that reason.
+ *
+ * Later adapters win on a colliding name. With one single-file channel that
+ * collision is the F-2 hazard, not a decision this function can make.
+ */
+export declare function ambientChannelEnv(channel: CaptureChannel, adapters?: readonly Adapter[]): Record<string, string>;
+/**
+ * Which adapter owns the capture that landed in the channel, or `null` when
+ * none claims it. The ambient counterpart of {@link detectAdapter}: the argv
+ * said nothing, so the payload decides.
+ *
+ * Registry order breaks a tie. Two adapters claiming one capture would mean
+ * two reporters wrote to the same single-file channel, which is the F-2
+ * last-writer-wins hazard rather than an ambiguity the user could resolve —
+ * there is no argv to name a winner with, so degrading here would discard a
+ * capture that is genuinely present.
+ */
+export declare function claimCapture(channel: CaptureChannel, adapters?: readonly Adapter[]): Adapter | null;
+/**
+ * Outcome of evaluating every adapter's `detect` against one child argv.
+ * `none` and `ambiguous` are both "the registry declines to choose": the
+ * caller degrades to raw passthrough and says why.
+ */
+export type AdapterDetection = {
+    readonly kind: 'none';
+} | {
+    readonly kind: 'unique';
+    readonly adapter: Adapter;
+    readonly detected: DetectResult;
+} | {
+    readonly kind: 'ambiguous';
+    readonly candidates: readonly Adapter[];
+};
+/**
+ * Evaluate *all* adapters against the argv. Never short-circuits on the first
+ * match: two adapters claiming the same argv is a distinguishable outcome that
+ * must reach the user as a candidate list, not be hidden by registry order.
+ */
+export declare function detectAdapter(argv: readonly string[], adapters?: readonly Adapter[]): AdapterDetection;

package/dist/adapters/registry.js

@@ -0,0 +1,78 @@
+import { vitestAdapter } from './vitest/adapter.js';
+/** Every known adapter, in a deterministic order. */
+export const ADAPTERS = [vitestAdapter];
+/** Known adapter names, in registry order — for diagnostics and `--adapter`. */
+export function adapterNames(adapters = ADAPTERS) {
+    return adapters.map((a) => a.name);
+}
+/**
+ * Look an adapter up by name without failing. Callers that must stay
+ * fail-closed rather than abort — the comparator and the gate, which resolve
+ * `record.instrument.adapter` from records they did not write — use this.
+ */
+export function findAdapter(name, adapters = ADAPTERS) {
+    return adapters.find((a) => a.name === name);
+}
+/**
+ * Resolve an explicitly requested adapter name. An unknown name is user input
+ * error, not a degradation path: silently passing through would turn a typo
+ * into a silent loss of recording, which is the opposite of INV-5's intent.
+ */
+export function resolveAdapter(name, adapters = ADAPTERS) {
+    const adapter = findAdapter(name, adapters);
+    if (adapter === undefined) {
+        throw new Error(`unknown adapter '${name}' — known adapters: ${adapterNames(adapters).join(', ')}`);
+    }
+    return adapter;
+}
+/**
+ * The env additions every registered adapter needs to find the channel, in
+ * registry order. Exported to the child unconditionally, detection or no
+ * detection: a reporter configured in the project itself (spec §4.2 ambient
+ * recording) is inert without it, and pre-seam `vdelta run` set it on every
+ * child for exactly that reason.
+ *
+ * Later adapters win on a colliding name. With one single-file channel that
+ * collision is the F-2 hazard, not a decision this function can make.
+ */
+export function ambientChannelEnv(channel, adapters = ADAPTERS) {
+    const env = {};
+    for (const adapter of adapters) {
+        Object.assign(env, adapter.channelEnv(channel));
+    }
+    return env;
+}
+/**
+ * Which adapter owns the capture that landed in the channel, or `null` when
+ * none claims it. The ambient counterpart of {@link detectAdapter}: the argv
+ * said nothing, so the payload decides.
+ *
+ * Registry order breaks a tie. Two adapters claiming one capture would mean
+ * two reporters wrote to the same single-file channel, which is the F-2
+ * last-writer-wins hazard rather than an ambiguity the user could resolve —
+ * there is no argv to name a winner with, so degrading here would discard a
+ * capture that is genuinely present.
+ */
+export function claimCapture(channel, adapters = ADAPTERS) {
+    return adapters.find((a) => a.claimsCapture(channel)) ?? null;
+}
+/**
+ * Evaluate *all* adapters against the argv. Never short-circuits on the first
+ * match: two adapters claiming the same argv is a distinguishable outcome that
+ * must reach the user as a candidate list, not be hidden by registry order.
+ */
+export function detectAdapter(argv, adapters = ADAPTERS) {
+    const matches = [];
+    for (const adapter of adapters) {
+        const detected = adapter.detect(argv);
+        if (detected !== null)
+            matches.push({ adapter, detected });
+    }
+    if (matches.length === 0)
+        return { kind: 'none' };
+    if (matches.length > 1)
+        return { kind: 'ambiguous', candidates: matches.map((m) => m.adapter) };
+    const only = matches[0];
+    return { kind: 'unique', adapter: only.adapter, detected: only.detected };
+}
+//# sourceMappingURL=registry.js.map

package/dist/adapters/registry.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"registry.js","sourceRoot":"","sources":["../../src/adapters/registry.ts"],"names":[],"mappings":"AAYA,OAAO,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAA;AAEnD,qDAAqD;AACrD,MAAM,CAAC,MAAM,QAAQ,GAAuB,CAAC,aAAa,CAAC,CAAA;AAE3D,gFAAgF;AAChF,MAAM,UAAU,YAAY,CAC1B,WAA+B,QAAQ;IAEvC,OAAO,QAAQ,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,CAAA;AACpC,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,WAAW,CACzB,IAAY,EACZ,WAA+B,QAAQ;IAEvC,OAAO,QAAQ,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,KAAK,IAAI,CAAC,CAAA;AAC9C,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,cAAc,CAC5B,IAAY,EACZ,WAA+B,QAAQ;IAEvC,MAAM,OAAO,GAAG,WAAW,CAAC,IAAI,EAAE,QAAQ,CAAC,CAAA;IAC3C,IAAI,OAAO,KAAK,SAAS,EAAE,CAAC;QAC1B,MAAM,IAAI,KAAK,CACb,oBAAoB,IAAI,uBAAuB,YAAY,CAAC,QAAQ,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CACnF,CAAA;IACH,CAAC;IACD,OAAO,OAAO,CAAA;AAChB,CAAC;AAED;;;;;;;;;GASG;AACH,MAAM,UAAU,iBAAiB,CAC/B,OAAuB,EACvB,WAA+B,QAAQ;IAEvC,MAAM,GAAG,GAA2B,EAAE,CAAA;IACtC,KAAK,MAAM,OAAO,IAAI,QAAQ,EAAE,CAAC;QAC/B,MAAM,CAAC,MAAM,CAAC,GAAG,EAAE,OAAO,CAAC,UAAU,CAAC,OAAO,CAAC,CAAC,CAAA;IACjD,CAAC;IACD,OAAO,GAAG,CAAA;AACZ,CAAC;AAED;;;;;;;;;;GAUG;AACH,MAAM,UAAU,YAAY,CAC1B,OAAuB,EACvB,WAA+B,QAAQ;IAEvC,OAAO,QAAQ,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,aAAa,CAAC,OAAO,CAAC,CAAC,IAAI,IAAI,CAAA;AAC/D,CAAC;AAgBD;;;;GAIG;AACH,MAAM,UAAU,aAAa,CAC3B,IAAuB,EACvB,WAA+B,QAAQ;IAEvC,MAAM,OAAO,GAAmD,EAAE,CAAA;IAClE,KAAK,MAAM,OAAO,IAAI,QAAQ,EAAE,CAAC;QAC/B,MAAM,QAAQ,GAAG,OAAO,CAAC,MAAM,CAAC,IAAI,CAAC,CAAA;QACrC,IAAI,QAAQ,KAAK,IAAI;YAAE,OAAO,CAAC,IAAI,CAAC,EAAE,OAAO,EAAE,QAAQ,EAAE,CAAC,CAAA;IAC5D,CAAC;IACD,IAAI,OAAO,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,EAAE,IAAI,EAAE,MAAM,EAAE,CAAA;IACjD,IAAI,OAAO,CAAC,MAAM,GAAG,CAAC;QACpB,OAAO,EAAE,IAAI,EAAE,WAAW,EAAE,UAAU,EAAE,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,OAAO,CAAC,EAAE,CAAA;IACzE,MAAM,IAAI,GAAG,OAAO,CAAC,CAAC,CAAE,CAAA;IACxB,OAAO,EAAE,IAAI,EAAE,QAAQ,EAAE,OAAO,EAAE,IAAI,CAAC,OAAO,EAAE,QAAQ,EAAE,IAAI,CAAC,QAAQ,EAAE,CAAA;AAC3E,CAAC"}

package/dist/adapters/vitest/adapter.d.ts

@@ -0,0 +1,19 @@
+import { type Adapter, type CapabilityDeclaration, type CommandSelector } from '../../adapter.js';
+/**
+ * The invocation's selector is its inclusion intent (§6.4): the vitest CLI
+ * positional filters. The canonical command excludes them (§5.1).
+ *
+ * `--flag value` pairs for known value-taking flags (see
+ * {@link VITEST_VALUE_FLAGS}) are folded into a single `--flag=value`
+ * canonical token so that this form and the pre-joined `--flag=value` form
+ * produce byte-identical `command` arrays (and thus the same stream key).
+ */
+export declare function splitCommandSelector(cmd: readonly string[]): CommandSelector;
+/**
+ * Initial capability declaration for `vitest-native/1` (§3.4). Reproduces the
+ * composition's documented standing byte for byte: only `source-region-text`
+ * is degraded (CE-1 — vitest's structured channel carries no failing-source
+ * region text), everything else this composition claims is met.
+ */
+export declare const VITEST_CAPABILITIES: CapabilityDeclaration;
+export declare const vitestAdapter: Adapter;

package/dist/adapters/vitest/adapter.js

@@ -0,0 +1,192 @@
+/**
+ * vitest adapter, descriptor side: the runner-facing half of the seam
+ * (`src/adapter.ts`). Everything vitest-specific about *invoking* a run lives
+ * here — locating the vitest binary in the child argv, injecting the capture
+ * reporter, and splitting inclusion intent out of the command (§6.4) using
+ * vitest's own CLI surface. The recorder half (capture → RunRecord) stays in
+ * `./recorder.ts`; this module only owns reading and parsing the channel.
+ */
+import { readFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { AdapterCaptureError, } from '../../adapter.js';
+import { ADAPTER_NAME, buildRunRecord, COMPOSITION_ID, DECLARED_ENV_VARS, } from './recorder.js';
+/**
+ * Absolute path of the in-process vitest reporter that writes the capture.
+ * Resolved relative to this module so it points at the built sibling
+ * (`dist/adapters/vitest/reporter.js`) rather than at a source path.
+ */
+function reporterModulePath() {
+    return join(dirname(fileURLToPath(import.meta.url)), 'reporter.js');
+}
+/**
+ * The one env var the capture reporter reads (`reporter.ts:61`). Held here
+ * rather than inline so `channelEnv` and the reporter's contract stay a single
+ * fact; the reporter is inert without it, by design, so that it can sit
+ * permanently in a project's vitest config (spec §4.2 ambient recording).
+ */
+const CAPTURE_FILE_ENV = 'VDELTA_CAPTURE_FILE';
+function channelEnv(channel) {
+    return { [CAPTURE_FILE_ENV]: channel.path };
+}
+/** Parse the channel, or `undefined` when there is nothing readable in it. */
+function readCapture(channel) {
+    try {
+        return JSON.parse(readFileSync(channel.path, 'utf8'));
+    }
+    catch {
+        return undefined;
+    }
+}
+/** Locate the vitest invocation inside the child argv; null when absent. */
+function findVitestToken(cmd) {
+    for (let i = 0; i < cmd.length; i++) {
+        const token = cmd[i];
+        if (/(^|[\\/])vitest(\.mjs|\.js)?$/.test(token) || token === 'vitest')
+            return i;
+    }
+    return null;
+}
+/**
+ * vitest 4.x CLI flags that always take their value as a *separate* argv
+ * token (`--flag value`), never combined into the flag token itself. Used
+ * by {@link splitCommandSelector} to recognize `--flag value` pairs and fold
+ * them into a single `--flag=value` canonical token so that space-separated
+ * and `=`-joined invocations normalize to the same command array (and
+ * therefore the same stream key — see `streamKey` in src/compare.ts).
+ *
+ * Deliberately excludes flags whose value is *optional*
+ * (`--changed`, `--silent`, `--coverage`, `--browser`, `--inspect`, etc.):
+ * for those, the token following the flag cannot be distinguished from a
+ * positional selector without vitest's own arg-parsing rules, so folding
+ * them here would risk silently swallowing a selector token. Flags outside
+ * this list keep the historical (pre-fix) behavior: a space-separated value
+ * is treated as a selector token, which may cause selector-based stream
+ * splitting and an abstain (`comparability: 'none'`) rather than a
+ * false-positive comparison.
+ *
+ * Maintenance: this list targets vitest 4.x. Revisit when bumping the
+ * vitest minor/major version (see issue #15 Open Question — no automated
+ * mechanism keeps this in sync with vitest's own CLI surface).
+ */
+const VITEST_VALUE_FLAGS = new Set([
+    '--project',
+    '--config',
+    '-c',
+    '--root',
+    '-r',
+    '--dir',
+    '--reporter',
+    '--outputFile',
+    '--pool',
+    '--maxWorkers',
+    '--minWorkers',
+    '--environment',
+    '--testNamePattern',
+    '-t',
+    '--testTimeout',
+    '--hookTimeout',
+    '--teardownTimeout',
+    '--retry',
+    '--bail',
+    '--maxConcurrency',
+    '--shard',
+    '--exclude',
+    '--mode',
+    '--workspace',
+]);
+/**
+ * The invocation's selector is its inclusion intent (§6.4): the vitest CLI
+ * positional filters. The canonical command excludes them (§5.1).
+ *
+ * `--flag value` pairs for known value-taking flags (see
+ * {@link VITEST_VALUE_FLAGS}) are folded into a single `--flag=value`
+ * canonical token so that this form and the pre-joined `--flag=value` form
+ * produce byte-identical `command` arrays (and thus the same stream key).
+ */
+export function splitCommandSelector(cmd) {
+    const idx = findVitestToken(cmd);
+    if (idx === null)
+        return { command: [...cmd], selector: [] };
+    const command = cmd.slice(0, idx + 1);
+    const selector = [];
+    for (let i = idx + 1; i < cmd.length; i++) {
+        const token = cmd[i];
+        if (token === 'run' && i === idx + 1) {
+            command.push(token);
+            continue;
+        }
+        if (!token.startsWith('-')) {
+            selector.push(token);
+            continue;
+        }
+        if (token.includes('=')) {
+            command.push(token);
+            continue;
+        }
+        const next = cmd[i + 1];
+        if (VITEST_VALUE_FLAGS.has(token) &&
+            next !== undefined &&
+            !next.startsWith('-')) {
+            command.push(`${token}=${next}`);
+            i++;
+            continue;
+        }
+        command.push(token);
+    }
+    return { command, selector };
+}
+/**
+ * Initial capability declaration for `vitest-native/1` (§3.4). Reproduces the
+ * composition's documented standing byte for byte: only `source-region-text`
+ * is degraded (CE-1 — vitest's structured channel carries no failing-source
+ * region text), everything else this composition claims is met.
+ */
+export const VITEST_CAPABILITIES = {
+    verdicts: 'pass',
+    'source-location': 'pass',
+    suppression: 'pass',
+    inventory: 'pass',
+    'failure-evidence': 'pass',
+    'source-region-text': 'unsupported',
+};
+export const vitestAdapter = {
+    name: ADAPTER_NAME,
+    compositionId: COMPOSITION_ID,
+    declaredCapabilities: VITEST_CAPABILITIES,
+    declaredEnvVars: DECLARED_ENV_VARS,
+    detect(argv) {
+        const i = findVitestToken(argv);
+        return i === null ? null : { tokenIndex: i };
+    },
+    channelEnv,
+    instrument(argv, channel) {
+        return {
+            argv: [
+                ...argv,
+                '--reporter=default',
+                `--reporter=${reporterModulePath()}`,
+                '--includeTaskLocation',
+            ],
+            env: channelEnv(channel),
+        };
+    },
+    splitCommandSelector,
+    claimsCapture(channel) {
+        // Authorship only, and from the payload's own self-identification
+        // (`capture.ts:34`, a literal `'vitest'`). Deliberately not a version or
+        // shape check: a capture this adapter wrote but cannot read must reach
+        // `record` so the run degrades with *that* diagnostic ("unsupported
+        // capture version N") instead of the generic "is the child a vitest
+        // invocation?", which is what the pre-seam code path said.
+        return readCapture(channel)?.runner === 'vitest';
+    },
+    record(channel, ctx) {
+        const capture = readCapture(channel);
+        if (capture === undefined) {
+            throw new AdapterCaptureError('no capture from the vitest reporter — is the child a vitest invocation?');
+        }
+        return buildRunRecord(capture, ctx);
+    },
+};
+//# sourceMappingURL=adapter.js.map

package/dist/adapters/vitest/adapter.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"adapter.js","sourceRoot":"","sources":["../../../src/adapters/vitest/adapter.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AACH,OAAO,EAAE,YAAY,EAAE,MAAM,SAAS,CAAA;AACtC,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAA;AACzC,OAAO,EAAE,aAAa,EAAE,MAAM,UAAU,CAAA;AACxC,OAAO,EAEL,mBAAmB,GAIpB,MAAM,kBAAkB,CAAA;AAEzB,OAAO,EACL,YAAY,EACZ,cAAc,EACd,cAAc,EACd,iBAAiB,GAClB,MAAM,eAAe,CAAA;AAEtB;;;;GAIG;AACH,SAAS,kBAAkB;IACzB,OAAO,IAAI,CAAC,OAAO,CAAC,aAAa,CAAC,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,aAAa,CAAC,CAAA;AACrE,CAAC;AAED;;;;;GAKG;AACH,MAAM,gBAAgB,GAAG,qBAAqB,CAAA;AAE9C,SAAS,UAAU,CAAC,OAAuB;IACzC,OAAO,EAAE,CAAC,gBAAgB,CAAC,EAAE,OAAO,CAAC,IAAI,EAAE,CAAA;AAC7C,CAAC;AAED,8EAA8E;AAC9E,SAAS,WAAW,CAAC,OAAuB;IAC1C,IAAI,CAAC;QACH,OAAO,IAAI,CAAC,KAAK,CAAC,YAAY,CAAC,OAAO,CAAC,IAAI,EAAE,MAAM,CAAC,CAAY,CAAA;IAClE,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,SAAS,CAAA;IAClB,CAAC;AACH,CAAC;AAED,4EAA4E;AAC5E,SAAS,eAAe,CAAC,GAAsB;IAC7C,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,GAAG,CAAC,MAAM,EAAE,CAAC,EAAE,EAAE,CAAC;QACpC,MAAM,KAAK,GAAG,GAAG,CAAC,CAAC,CAAE,CAAA;QACrB,IAAI,+BAA+B,CAAC,IAAI,CAAC,KAAK,CAAC,IAAI,KAAK,KAAK,QAAQ;YACnE,OAAO,CAAC,CAAA;IACZ,CAAC;IACD,OAAO,IAAI,CAAA;AACb,CAAC;AAED;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,MAAM,kBAAkB,GAAwB,IAAI,GAAG,CAAC;IACtD,WAAW;IACX,UAAU;IACV,IAAI;IACJ,QAAQ;IACR,IAAI;IACJ,OAAO;IACP,YAAY;IACZ,cAAc;IACd,QAAQ;IACR,cAAc;IACd,cAAc;IACd,eAAe;IACf,mBAAmB;IACnB,IAAI;IACJ,eAAe;IACf,eAAe;IACf,mBAAmB;IACnB,SAAS;IACT,QAAQ;IACR,kBAAkB;IAClB,SAAS;IACT,WAAW;IACX,QAAQ;IACR,aAAa;CACd,CAAC,CAAA;AAEF;;;;;;;;GAQG;AACH,MAAM,UAAU,oBAAoB,CAAC,GAAsB;IACzD,MAAM,GAAG,GAAG,eAAe,CAAC,GAAG,CAAC,CAAA;IAChC,IAAI,GAAG,KAAK,IAAI;QAAE,OAAO,EAAE,OAAO,EAAE,CAAC,GAAG,GAAG,CAAC,EAAE,QAAQ,EAAE,EAAE,EAAE,CAAA;IAC5D,MAAM,OAAO,GAAa,GAAG,CAAC,KAAK,CAAC,CAAC,EAAE,GAAG,GAAG,CAAC,CAAC,CAAA;IAC/C,MAAM,QAAQ,GAAa,EAAE,CAAA;IAC7B,KAAK,IAAI,CAAC,GAAG,GAAG,GAAG,CAAC,EAAE,CAAC,GAAG,GAAG,CAAC,MAAM,EAAE,CAAC,EAAE,EAAE,CAAC;QAC1C,MAAM,KAAK,GAAG,GAAG,CAAC,CAAC,CAAE,CAAA;QACrB,IAAI,KAAK,KAAK,KAAK,IAAI,CAAC,KAAK,GAAG,GAAG,CAAC,EAAE,CAAC;YACrC,OAAO,CAAC,IAAI,CAAC,KAAK,CAAC,CAAA;YACnB,SAAQ;QACV,CAAC;QACD,IAAI,CAAC,KAAK,CAAC,UAAU,CAAC,GAAG,CAAC,EAAE,CAAC;YAC3B,QAAQ,CAAC,IAAI,CAAC,KAAK,CAAC,CAAA;YACpB,SAAQ;QACV,CAAC;QACD,IAAI,KAAK,CAAC,QAAQ,CAAC,GAAG,CAAC,EAAE,CAAC;YACxB,OAAO,CAAC,IAAI,CAAC,KAAK,CAAC,CAAA;YACnB,SAAQ;QACV,CAAC;QACD,MAAM,IAAI,GAAG,GAAG,CAAC,CAAC,GAAG,CAAC,CAAC,CAAA;QACvB,IACE,kBAAkB,CAAC,GAAG,CAAC,KAAK,CAAC;YAC7B,IAAI,KAAK,SAAS;YAClB,CAAC,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC,EACrB,CAAC;YACD,OAAO,CAAC,IAAI,CAAC,GAAG,KAAK,IAAI,IAAI,EAAE,CAAC,CAAA;YAChC,CAAC,EAAE,CAAA;YACH,SAAQ;QACV,CAAC;QACD,OAAO,CAAC,IAAI,CAAC,KAAK,CAAC,CAAA;IACrB,CAAC;IACD,OAAO,EAAE,OAAO,EAAE,QAAQ,EAAE,CAAA;AAC9B,CAAC;AAED;;;;;GAKG;AACH,MAAM,CAAC,MAAM,mBAAmB,GAA0B;IACxD,QAAQ,EAAE,MAAM;IAChB,iBAAiB,EAAE,MAAM;IACzB,WAAW,EAAE,MAAM;IACnB,SAAS,EAAE,MAAM;IACjB,kBAAkB,EAAE,MAAM;IAC1B,oBAAoB,EAAE,aAAa;CACpC,CAAA;AAED,MAAM,CAAC,MAAM,aAAa,GAAY;IACpC,IAAI,EAAE,YAAY;IAClB,aAAa,EAAE,cAAc;IAC7B,oBAAoB,EAAE,mBAAmB;IACzC,eAAe,EAAE,iBAAiB;IAElC,MAAM,CAAC,IAAI;QACT,MAAM,CAAC,GAAG,eAAe,CAAC,IAAI,CAAC,CAAA;QAC/B,OAAO,CAAC,KAAK,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,UAAU,EAAE,CAAC,EAAE,CAAA;IAC9C,CAAC;IAED,UAAU;IAEV,UAAU,CAAC,IAAI,EAAE,OAAO;QACtB,OAAO;YACL,IAAI,EAAE;gBACJ,GAAG,IAAI;gBACP,oBAAoB;gBACpB,cAAc,kBAAkB,EAAE,EAAE;gBACpC,uBAAuB;aACxB;YACD,GAAG,EAAE,UAAU,CAAC,OAAO,CAAC;SACzB,CAAA;IACH,CAAC;IAED,oBAAoB;IAEpB,aAAa,CAAC,OAAO;QACnB,kEAAkE;QAClE,yEAAyE;QACzE,uEAAuE;QACvE,oEAAoE;QACpE,oEAAoE;QACpE,2DAA2D;QAC3D,OAAO,WAAW,CAAC,OAAO,CAAC,EAAE,MAAM,KAAK,QAAQ,CAAA;IAClD,CAAC;IAED,MAAM,CAAC,OAAO,EAAE,GAAG;QACjB,MAAM,OAAO,GAAG,WAAW,CAAC,OAAO,CAAC,CAAA;QACpC,IAAI,OAAO,KAAK,SAAS,EAAE,CAAC;YAC1B,MAAM,IAAI,mBAAmB,CAC3B,yEAAyE,CAC1E,CAAA;QACH,CAAC;QACD,OAAO,cAAc,CAAC,OAAO,EAAE,GAAG,CAAC,CAAA;IACrC,CAAC;CACF,CAAA"}

package/dist/adapters/vitest/recorder.d.ts

@@ -1,30 +1,21 @@
+import { AdapterCaptureError, type RecordContext } from '../../adapter.js';
 import { type RunRecord } from '../../schema.js';
 import type { Capture, CapturedTest } from './capture.js';
 export declare const ADAPTER_NAME = "vitest";
 export declare const COMPOSITION_ID = "vitest-native/1";
-/** CE-1: vitest's structured channel has no failing-source-region text (expC Q1). */
-export declare const DEGRADED_CAPABILITIES: string[];
 /** Env vars whose values (fingerprinted, never stored) are comparison-relevant. */
 export declare const DECLARED_ENV_VARS: readonly ["CI", "NODE_ENV", "TZ", "LANG"];
-export declare class RecorderError extends Error {
+/**
+ * A capture the recorder cannot turn into a record: unsupported capture
+ * version, or an ambiguity it refuses to guess through (§12 fail-closed).
+ * A subtype of `AdapterCaptureError` so the core degrades to raw passthrough
+ * (INV-5) without knowing which adapter raised it.
+ */
+export declare class RecorderError extends AdapterCaptureError {
     constructor(message: string);
 }
-export interface RecordContext {
-    worktree: string;
-    repoIdentity: string;
-    branch: string;
-    cwdRel: string;
-    command: string[];
-    selector: string[];
-    head: string | null;
-    treeDigest: string;
-    dirtyDiffDigest: string;
-    childExitCode: number;
-    rawStdout: string;
-    rawStderr: string;
-    adapterVersion: string;
-    recordedAtMs: number;
-}
+/** Re-exported from the seam: the context shape is runner-neutral (§4.1). */
+export type { RecordContext };
 export declare function buildRunRecord(capture: Capture, ctx: RecordContext): RunRecord;
 /** The effective evidence-affecting configuration (§3.1, contract §5.4). */
 export declare function instrumentConfigDigest(capture: Capture): string;

package/dist/adapters/vitest/recorder.js

@@ -11,16 +11,21 @@
  */
 import { readFileSync, realpathSync } from 'node:fs';
 import { isAbsolute, join, relative } from 'node:path';
+import { AdapterCaptureError } from '../../adapter.js';
 import { canonicalDigest } from '../../digest.js';
 import { redactText, redactValue } from '../../redact.js';
 import { SCHEMA_VERSION, } from '../../schema.js';
 export const ADAPTER_NAME = 'vitest';
 export const COMPOSITION_ID = 'vitest-native/1';
-/** CE-1: vitest's structured channel has no failing-source-region text (expC Q1). */
-export const DEGRADED_CAPABILITIES = ['source-region-text'];
 /** Env vars whose values (fingerprinted, never stored) are comparison-relevant. */
 export const DECLARED_ENV_VARS = ['CI', 'NODE_ENV', 'TZ', 'LANG'];
-export class RecorderError extends Error {
+/**
+ * A capture the recorder cannot turn into a record: unsupported capture
+ * version, or an ambiguity it refuses to guess through (§12 fail-closed).
+ * A subtype of `AdapterCaptureError` so the core degrades to raw passthrough
+ * (INV-5) without knowing which adapter raised it.
+ */
+export class RecorderError extends AdapterCaptureError {
     constructor(message) {
         super(message);
         this.name = 'RecorderError';