@dzhechkov/harness-core 0.8.6 → 0.8.11

package/dist/integrations-verify.js

@@ -0,0 +1,194 @@
+/** Bounded, non-executing target registration verification. */
+import { spawnSync } from 'node:child_process';
+import { accessSync, constants, existsSync, mkdtempSync, realpathSync, rmSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { delimiter, isAbsolute, join, relative, resolve, sep } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { CLAUDE_MCP_RECEIPT, assessClaudeMcpEvidence } from './integration-evidence.js';
+import { TARGET_INTEGRATION_POLICY } from './target-integrations.js';
+export const INTEGRATION_PROBE_TIMEOUT_MS = 30_000;
+export const INTEGRATION_PROBE_STREAM_MAX_BYTES = 1024 * 1024;
+export const INTEGRATION_PROBE_AGGREGATE_MAX_BYTES = 2 * 1024 * 1024;
+/** Resolve PATH once and reject a project-controlled probe binary before spawning it. */
+export function resolveIntegrationExecutable(command, cwd, pathValue = process.env['PATH'] ?? '') {
+    const candidates = isAbsolute(command)
+        ? [command]
+        : command.includes('/') || command.includes('\\')
+            ? [resolve(cwd, command)]
+            : pathValue.split(delimiter).map((dir) => join(dir.length === 0 ? cwd : dir, command));
+    for (const candidate of candidates) {
+        if (!existsSync(candidate))
+            continue;
+        try {
+            accessSync(candidate, constants.X_OK);
+            const actual = realpathSync(candidate);
+            const rel = relative(realpathSync(cwd), actual);
+            if (rel === '' || (!rel.startsWith(`..${sep}`) && rel !== '..' && !isAbsolute(rel))) {
+                return { ok: false, errorCode: 'UNSAFE_EXECUTABLE' };
+            }
+            return { ok: true, path: actual };
+        }
+        catch {
+            continue;
+        }
+    }
+    return { ok: false, errorCode: 'ENOENT' };
+}
+export const defaultIntegrationProcessPort = {
+    run(request) {
+        const executable = resolveIntegrationExecutable(request.command, request.cwd);
+        if (!executable.ok) {
+            return { status: null, signal: null, stdout: new Uint8Array(), stderr: new Uint8Array(), errorCode: executable.errorCode };
+        }
+        const workerPath = fileURLToPath(new URL('./integration-probe-worker.js', import.meta.url));
+        const result = spawnSync(process.execPath, [workerPath], {
+            input: JSON.stringify({
+                ...request,
+                command: executable.path,
+                streamMaxBytes: INTEGRATION_PROBE_STREAM_MAX_BYTES,
+                aggregateMaxBytes: INTEGRATION_PROBE_AGGREGATE_MAX_BYTES,
+            }),
+            cwd: request.cwd,
+            timeout: request.timeoutMs + 5_000,
+            killSignal: 'SIGKILL',
+            maxBuffer: 4 * 1024 * 1024,
+            encoding: 'utf8',
+            windowsHide: true,
+        });
+        if (result.error !== undefined || result.status !== 0) {
+            return {
+                status: result.status,
+                signal: result.signal,
+                stdout: new Uint8Array(),
+                stderr: new Uint8Array(),
+                errorCode: result.error?.code ?? 'PROCESS_ERROR',
+            };
+        }
+        let observation;
+        try {
+            observation = JSON.parse(result.stdout);
+        }
+        catch {
+            return { status: null, signal: null, stdout: new Uint8Array(), stderr: new Uint8Array(), errorCode: 'PROCESS_ERROR' };
+        }
+        return {
+            status: observation.status,
+            signal: observation.signal,
+            stdout: Buffer.from(observation.stdoutBase64, 'base64'),
+            stderr: Buffer.from(observation.stderrBase64, 'base64'),
+            ...(observation.errorCode !== undefined ? { errorCode: observation.errorCode } : {}),
+        };
+    },
+};
+function decodeBounded(observation) {
+    const stdout = Buffer.from(observation.stdout);
+    const stderr = Buffer.from(observation.stderr);
+    if (stdout.length > INTEGRATION_PROBE_STREAM_MAX_BYTES || stderr.length > INTEGRATION_PROBE_STREAM_MAX_BYTES ||
+        stdout.length + stderr.length > INTEGRATION_PROBE_AGGREGATE_MAX_BYTES)
+        return 'LIVE_PROBE_FAILED';
+    try {
+        const decoder = new TextDecoder('utf-8', { fatal: true });
+        return { stdout: decoder.decode(stdout), stderr: decoder.decode(stderr) };
+    }
+    catch {
+        return 'LIVE_PROBE_FAILED';
+    }
+}
+function parseClaudeVersion(text) {
+    return /(?:Claude Code\s+)?(\d+\.\d+\.\d+)/i.exec(text)?.[1];
+}
+function failed(options, reasonCode, remediation, runtimeVersion) {
+    return {
+        ok: false,
+        target: options.target,
+        component: options.component,
+        registrations: [],
+        reasonCode,
+        remediation,
+        ...(runtimeVersion !== undefined ? { runtimeVersion } : {}),
+    };
+}
+function parseClaudeProjectRegistration(options, id, observation, runtimeVersion) {
+    if (observation.errorCode === 'ETIMEDOUT' || observation.signal === 'SIGKILL') {
+        return failed(options, 'LIVE_PROBE_TIMEOUT', `Claude mcp get exceeded ${INTEGRATION_PROBE_TIMEOUT_MS}ms`, runtimeVersion);
+    }
+    if (observation.errorCode !== undefined) {
+        return failed(options, 'LIVE_PROBE_FAILED', `Claude registration probe failed before a trustworthy observation (${observation.errorCode})`, runtimeVersion);
+    }
+    const text = decodeBounded(observation);
+    if (typeof text === 'string')
+        return failed(options, text, 'Claude registration output was oversized or invalid UTF-8', runtimeVersion);
+    if (observation.status !== 0)
+        return failed(options, 'POST_WRITE_REGISTRATION_NOT_OBSERVED', `claude mcp get ${id} did not observe the project registration`, runtimeVersion);
+    const output = `${text.stdout}\n${text.stderr}`;
+    const escapedId = id.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+    // Claude 2.1.235 prints either `Name: <id>` or an exact `<id>:` heading depending on the
+    // installation channel. Require one whole attributable line; a prose mention is not evidence.
+    if (!new RegExp(`^(?:Name\\s*:\\s*${escapedId}|${escapedId}:)\\s*$`, 'im').test(output) ||
+        !/Scope\s*:\s*Project\b/i.test(output)) {
+        return failed(options, 'POST_WRITE_REGISTRATION_NOT_OBSERVED', `claude mcp get ${id} did not attribute the exact id to project scope`, runtimeVersion);
+    }
+    const pending = /pending approval/i.test(output);
+    return {
+        ok: true,
+        target: options.target,
+        component: options.component,
+        runtimeVersion,
+        evidenceVersion: CLAUDE_MCP_RECEIPT.runtimeVersion,
+        registrations: [{ id, scope: 'project', registered: true, approval: pending ? 'pending' : 'unknown', ready: !pending }],
+    };
+}
+/**
+ * Verify only code-owned native list/get surfaces. Manifest command/URL fields
+ * are intentionally absent from this API, so they cannot be executed here.
+ */
+export function verifyTargetIntegration(options) {
+    const port = options.processPort ?? defaultIntegrationProcessPort;
+    if (options.target !== 'claude-code' || options.component !== 'mcp') {
+        const cell = TARGET_INTEGRATION_POLICY[options.target][options.component];
+        return failed(options, cell.reasonCode ?? 'NO_QUALIFYING_LIVE_RECEIPT', 'no qualifying exact-version live receipt exists for this target/component');
+    }
+    const versionObs = port.run({ command: 'claude', args: ['--version'], cwd: options.projectRoot, timeoutMs: INTEGRATION_PROBE_TIMEOUT_MS });
+    if (versionObs.errorCode === 'ENOENT')
+        return failed(options, 'TARGET_BINARY_UNAVAILABLE', 'install Claude Code and rerun dz integrations-verify');
+    if (versionObs.errorCode === 'ETIMEDOUT' || versionObs.signal === 'SIGKILL')
+        return failed(options, 'LIVE_PROBE_TIMEOUT', `Claude version probe exceeded ${INTEGRATION_PROBE_TIMEOUT_MS}ms`);
+    if (versionObs.errorCode !== undefined)
+        return failed(options, 'LIVE_PROBE_FAILED', `Claude version probe failed before a trustworthy observation (${versionObs.errorCode})`);
+    const versionText = decodeBounded(versionObs);
+    if (typeof versionText === 'string')
+        return failed(options, versionText, 'Claude version output was oversized or invalid UTF-8');
+    if (versionObs.status !== 0)
+        return failed(options, 'LIVE_PROBE_FAILED', 'Claude version probe exited non-zero');
+    const runtimeVersion = parseClaudeVersion(`${versionText.stdout}\n${versionText.stderr}`);
+    if (runtimeVersion === undefined)
+        return failed(options, 'LIVE_PROBE_FAILED', 'Claude version output did not contain an attributable semantic version');
+    const evidence = assessClaudeMcpEvidence(runtimeVersion);
+    if (!evidence.eligible)
+        return failed(options, evidence.reasonCode ?? 'RECEIPT_STALE', `expected Claude Code ${CLAUDE_MCP_RECEIPT.runtimeVersion}; rerun after a matching receipt is recorded`, runtimeVersion);
+    if ((options.phase ?? 'preflight') === 'preflight') {
+        const probeId = 'dz-registration-probe';
+        const probeRoot = mkdtempSync(join(tmpdir(), 'dz-claude-mcp-probe-'));
+        try {
+            writeFileSync(join(probeRoot, '.mcp.json'), `${JSON.stringify({
+                mcpServers: { [probeId]: { type: 'stdio', command: 'node', args: ['-e', 'process.exit(0)'] } },
+            }, null, 2)}\n`, { flag: 'wx', mode: 0o600 });
+            const observation = port.run({
+                command: 'claude', args: ['mcp', 'get', probeId], cwd: probeRoot, timeoutMs: INTEGRATION_PROBE_TIMEOUT_MS,
+            });
+            const parsed = parseClaudeProjectRegistration(options, probeId, observation, runtimeVersion);
+            return parsed.ok ? { ...parsed, registrations: [] } : parsed;
+        }
+        finally {
+            rmSync(probeRoot, { recursive: true, force: true });
+        }
+    }
+    const id = options.registrationId;
+    if (id === undefined)
+        return failed(options, 'LIVE_PROBE_FAILED', 'post-write verification requires an exact registration id', runtimeVersion);
+    return parseClaudeProjectRegistration(options, id, port.run({ command: 'claude', args: ['mcp', 'get', id], cwd: options.projectRoot, timeoutMs: INTEGRATION_PROBE_TIMEOUT_MS }), runtimeVersion);
+}
+export function runIntegrationsVerify(options) {
+    return verifyTargetIntegration(options);
+}
+//# sourceMappingURL=integrations-verify.js.map

package/dist/integrations-verify.js.map

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

package/dist/lesson-generalization.d.ts

@@ -0,0 +1,29 @@
+export type LessonForm = 'specific' | 'class';
+export type LessonMatchedForm = 'specific' | 'class' | 'both';
+export interface LessonFormsInput {
+    readonly specific: string;
+    readonly classForm?: string;
+    readonly classAdvisory?: string;
+}
+export interface LessonFormRankedHit<T> {
+    readonly key: string;
+    readonly value: T;
+    readonly matchedForm: LessonForm;
+}
+export interface MergedLessonFormHit<T> {
+    readonly key: string;
+    readonly value: T;
+    readonly matchedForm: LessonMatchedForm;
+    readonly score: number;
+}
+export declare function normalizeLessonForms(specific: string, classInput?: unknown): LessonFormsInput;
+export declare function validateClassTemplate(specific: string, classTemplate: string): {
+    readonly ok: true;
+} | {
+    readonly ok: false;
+    readonly reason: string;
+};
+export declare function lessonPairIdOf(specific: string, classTemplate: string, ts: string): string;
+export declare function mergeLessonMatchedForms(left: LessonMatchedForm | undefined, right: LessonMatchedForm | undefined): LessonMatchedForm | undefined;
+export declare function mergeLessonFormHits<T>(specificHits: readonly LessonFormRankedHit<T>[], classHits: readonly LessonFormRankedHit<T>[], limit: number): MergedLessonFormHit<T>[];
+//# sourceMappingURL=lesson-generalization.d.ts.map

package/dist/lesson-generalization.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"lesson-generalization.d.ts","sourceRoot":"","sources":["../src/lesson-generalization.ts"],"names":[],"mappings":"AAEA,MAAM,MAAM,UAAU,GAAG,UAAU,GAAG,OAAO,CAAC;AAC9C,MAAM,MAAM,iBAAiB,GAAG,UAAU,GAAG,OAAO,GAAG,MAAM,CAAC;AAE9D,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,aAAa,CAAC,EAAE,MAAM,CAAC;CACjC;AAED,MAAM,WAAW,mBAAmB,CAAC,CAAC;IACpC,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,KAAK,EAAE,CAAC,CAAC;IAClB,QAAQ,CAAC,WAAW,EAAE,UAAU,CAAC;CAClC;AAED,MAAM,WAAW,mBAAmB,CAAC,CAAC;IACpC,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,KAAK,EAAE,CAAC,CAAC;IAClB,QAAQ,CAAC,WAAW,EAAE,iBAAiB,CAAC;IACxC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;CACxB;AAED,wBAAgB,oBAAoB,CAAC,QAAQ,EAAE,MAAM,EAAE,UAAU,CAAC,EAAE,OAAO,GAAG,gBAAgB,CAQ7F;AAUD,wBAAgB,qBAAqB,CACnC,QAAQ,EAAE,MAAM,EAChB,aAAa,EAAE,MAAM,GACpB;IAAE,QAAQ,CAAC,EAAE,EAAE,IAAI,CAAA;CAAE,GAAG;IAAE,QAAQ,CAAC,EAAE,EAAE,KAAK,CAAC;IAAC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;CAAE,CAwBzE;AAED,wBAAgB,cAAc,CAAC,QAAQ,EAAE,MAAM,EAAE,aAAa,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,GAAG,MAAM,CAM1F;AAED,wBAAgB,uBAAuB,CACrC,IAAI,EAAE,iBAAiB,GAAG,SAAS,EACnC,KAAK,EAAE,iBAAiB,GAAG,SAAS,GACnC,iBAAiB,GAAG,SAAS,CAI/B;AAED,wBAAgB,mBAAmB,CAAC,CAAC,EACnC,YAAY,EAAE,SAAS,mBAAmB,CAAC,CAAC,CAAC,EAAE,EAC/C,SAAS,EAAE,SAAS,mBAAmB,CAAC,CAAC,CAAC,EAAE,EAC5C,KAAK,EAAE,MAAM,GACZ,mBAAmB,CAAC,CAAC,CAAC,EAAE,CAsB1B"}

package/dist/lesson-generalization.js

@@ -0,0 +1,84 @@
+import { createHash } from 'node:crypto';
+export function normalizeLessonForms(specific, classInput) {
+    if (classInput === undefined || (typeof classInput === 'string' && classInput.trim() === '')) {
+        return { specific };
+    }
+    if (typeof classInput !== 'string') {
+        return { specific, classAdvisory: 'class form must be text; the specific lesson was kept' };
+    }
+    return { specific, classForm: classInput.trim() };
+}
+function normalizedText(value) {
+    return value.normalize('NFC').toLocaleLowerCase('und').replace(/\s+/gu, ' ').trim();
+}
+function escapedLiteral(value) {
+    return normalizedText(value).replace(/[.*+?^${}()|[\]\\]/g, '\\$&').replace(/\s+/g, '\\s+');
+}
+export function validateClassTemplate(specific, classTemplate) {
+    const slot = /:([A-Za-z][A-Za-z0-9_-]*)/g;
+    const parts = [];
+    let slots = 0;
+    let cursor = 0;
+    for (const match of classTemplate.matchAll(slot)) {
+        const index = match.index ?? 0;
+        const literal = classTemplate.slice(cursor, index);
+        if (literal.includes(':'))
+            return { ok: false, reason: 'invalid :slot name' };
+        parts.push(escapedLiteral(literal), '(.+?)');
+        slots += 1;
+        cursor = index + match[0].length;
+    }
+    const tail = classTemplate.slice(cursor);
+    if (tail.includes(':'))
+        return { ok: false, reason: 'invalid :slot name' };
+    if (slots === 0)
+        return { ok: false, reason: 'class form must contain at least one :slot' };
+    parts.push(escapedLiteral(tail));
+    try {
+        return new RegExp(`^${parts.join('')}$`, 'u').test(normalizedText(specific))
+            ? { ok: true }
+            : { ok: false, reason: 'class form does not syntactically cover the specific lesson' };
+    }
+    catch {
+        return { ok: false, reason: 'class form contains an invalid template' };
+    }
+}
+export function lessonPairIdOf(specific, classTemplate, ts) {
+    const digest = createHash('sha256')
+        .update(`${specific}\u0000${classTemplate}\u0000${ts}`)
+        .digest('hex')
+        .slice(0, 16);
+    return `lesson-pair:${digest}`;
+}
+export function mergeLessonMatchedForms(left, right) {
+    if (left === undefined)
+        return right;
+    if (right === undefined || left === right)
+        return left;
+    return 'both';
+}
+export function mergeLessonFormHits(specificHits, classHits, limit) {
+    const merged = new Map();
+    const add = (hit, rank) => {
+        const current = merged.get(hit.key) ?? { value: hit.value, specific: false, classForm: false, score: 0 };
+        if (hit.matchedForm === 'specific')
+            current.specific = true;
+        else
+            current.classForm = true;
+        current.score += 1 / (60 + rank + 1);
+        merged.set(hit.key, current);
+    };
+    specificHits.forEach(add);
+    classHits.forEach(add);
+    const safeLimit = Number.isFinite(limit) ? Math.max(0, Math.trunc(limit)) : merged.size;
+    return [...merged.entries()]
+        .sort((a, b) => b[1].score - a[1].score || a[0].localeCompare(b[0]))
+        .slice(0, safeLimit)
+        .map(([key, hit]) => ({
+        key,
+        value: hit.value,
+        matchedForm: hit.specific && hit.classForm ? 'both' : hit.classForm ? 'class' : 'specific',
+        score: hit.score,
+    }));
+}
+//# sourceMappingURL=lesson-generalization.js.map

package/dist/lesson-generalization.js.map

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

package/dist/mutation-gate.d.ts

@@ -77,6 +77,10 @@ export interface MutationObservation {
     readonly rebaselineExitCode?: number | null;
     /** named no-exit reason for the restored-tree attribution run, when it produced none. */
     readonly rebaselineFailureReason?: string;
+    /** parsed failing files from a RED restored-tree run; absent when no red rebaseline ran. */
+    readonly rebaselineAttribution?: BaselineAttribution;
+    /** bounded log proving an internal runner failure received at most one retry. */
+    readonly internalAttemptLog?: string;
 }
 export interface MutationEntryResult {
     readonly id: string;
@@ -102,6 +106,26 @@ export interface MutationEntryResult {
     /** human sentence for the report line — names the undefended property on a green suite. */
     readonly detail: string;
 }
+export type InternalRunnerAttemptOutcome = 'completed' | 'runner-internal-error';
+export interface InternalRunnerAttempt {
+    readonly attempt: 1 | 2;
+    readonly outcome: InternalRunnerAttemptOutcome;
+    readonly detail: string;
+}
+export interface InternalRunnerRetryResult<T> {
+    /** The completed attempt's value. null means both attempts threw internally. */
+    readonly value: T | null;
+    readonly attempts: readonly InternalRunnerAttempt[];
+    /** Closed by construction: a runner receives either zero retries or exactly one. */
+    readonly internalRetries: 0 | 1;
+    /** Named reason consumed by the existing no-exit → INCONCLUSIVE arm. */
+    readonly failureReason?: `runner-internal-error: ${string}`;
+}
+/**
+ * Run one internal runner invocation. Only a THROWN internal error is retried; normal green/red
+ * observations and ordinary no-exit observations are values and therefore never retried.
+ */
+export declare function runWithOneInternalRetry<T>(runner: () => T): InternalRunnerRetryResult<T>;
 export interface ParsedRegistry {
     readonly registry: MutationRegistry | null;
     /** every defect found — ANY error makes the registry unusable (a half-valid registry that runs
@@ -215,50 +239,29 @@ export interface RunFailureClassification {
  * and never silently passes on output it cannot read.
  */
 export declare function classifyRunFailure(rawOutput: string): RunFailureClassification;
+export type BaselineAttributionSource = 'node-test' | 'vitest' | 'unparseable';
+export interface BaselineAttribution {
+    readonly parsedFrom: BaselineAttributionSource;
+    /** Package-relative failing paths, in first-seen order. */
+    readonly failingFiles: readonly string[];
+    /** Failing paths that match a registry file exactly (or by package-relative suffix). */
+    readonly covered: readonly string[];
+    /** Failing paths with no matching registry file. */
+    readonly extraneous: readonly string[];
+}
+/** Parse the failing FILE paths already exposed by supported node --test and vitest shapes. */
+export declare function attributeBaselineRedness(rawOutput: string, registryFiles: readonly string[]): BaselineAttribution;
+export type BaselineFailureReason = 'runner-internal-error' | 'runner-no-exit' | 'extraneous-red-in-allowlist' | 'baseline-red-covered-files' | 'baseline-red-files-unparseable';
 export interface BaselineResult {
     readonly ok: boolean;
     readonly detail: string;
+    readonly reason?: BaselineFailureReason;
 }
 /**
  * A RED baseline in the scratch copy is a SETUP error, never a mutation result: every subsequent
  * "red under mutation" would be noise, and every "green" a lie about an unrunnable copy.
  */
-export declare function classifyBaseline(exitCode: number | null, runFailureReason?: string): BaselineResult;
-/**
- * Classify one entry's observation.
- *
- * PRECEDENCE LATTICE (checked top to bottom; each verdict is justified by what it invalidates
- * BELOW it — a verdict may only outrank another when it makes that other's evidence meaningless):
- *   1. NOT_APPLIED            — nothing was mutated, so no run observation means anything;
- *   2. MUTATION_UNPARSEABLE   — the mutated file is not even syntactically a module; a non-parsing
- *                               file never RUNS, so no load- or count-signal can exist (which is
- *                               why it sits above MUTATION_LOAD_FATAL);
- *   3. MUTATION_LOAD_FATAL    — the run happened, but its own output says a test FILE died at
- *                               load: the redness is structural and every count from that same run
- *                               is non-attributable — so it outranks every count-based verdict AND
- *                               the flaky-rebaseline check (a structurally-broken run needs no
- *                               attribution analysis);
- *   4. INCONCLUSIVE (no exit) — the run produced nothing to classify at all;
- *   5. RECEIPT_MISMATCH       — the harness declared its own receipt contract broken, which
- *                               invalidates BOTH the green reading and every count-based reading
- *                               of the same run;
- *   6. UNDEFENDED (exit 0)    — the disjoint GREEN arm: mutually exclusive with every red-based
- *                               verdict below;
- *   7. INCONCLUSIVE (unrecognised output) — red, but the shape is unreadable: counts parsed out of
- *                               unrecognised output must not reach BELOW_MIN/OVER_FAILING/PROVEN;
- *   8. INCONCLUSIVE (flaky rebaseline)    — red, readable, but not attributable;
- *   9. BELOW_MIN → 10. OVER_FAILING       — reliable-count contract checks, both failing;
- *  11. PROVEN                 — applied, red, behavioural, attributable, within bounds.
- *
- * THE DROP DECISION (SPEC §Reporting, decided here + justified): `failing < observed` but still
- * `>= minFailing` is a LOUD WARNING, not a failure. Two reasons, both load-bearing:
- *   • the count is a BEST-EFFORT secondary parsed from runner output — making it verdict-deciding
- *    would let a count-parse failure flip red/green, which the design decisions forbid;
- *   • `observed` is a historical measurement, `minFailing` is the entry's declared CONTRACT. A
- *     contract violation fails (BELOW_MIN — only ever on a reliable count); history drifting down
- *     while the contract still holds is the early warning, reported loudly so a human re-pins
- *     `observed` or investigates — silently normalising it would erase the signal.
- */
+export declare function classifyBaseline(exitCode: number | null, runFailureReason?: string, attribution?: BaselineAttribution): BaselineResult;
 export declare function classifyMutationOutcome(obs: MutationObservation): MutationEntryResult;
 /** Exit contract: 0 all proven · 1 any entry failed (or red baseline) · (2 = usage/setup, CLI-side). */
 export declare function mutationGateExitCode(results: readonly MutationEntryResult[], baselineOk: boolean): number;

package/dist/mutation-gate.d.ts.map

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

package/dist/mutation-gate.js

@@ -19,6 +19,39 @@
 //   3. Never mutate the working tree (enforced by the executor: scratch copy only).
 //   4. The gate has its own discrimination proof (the deliberately-undefended fixture in
 //      harness-cli/test/fixtures/mutation-gate-undefended — excluded from any real registry).
+function internalRunnerErrorHead(error) {
+    const raw = error instanceof Error ? error.message : String(error);
+    const firstLine = raw.split(/\r?\n/, 1)[0]?.trim() || 'unknown internal runner error';
+    return Array.from(firstLine).slice(0, 160).join('');
+}
+/**
+ * Run one internal runner invocation. Only a THROWN internal error is retried; normal green/red
+ * observations and ordinary no-exit observations are values and therefore never retried.
+ */
+export function runWithOneInternalRetry(runner) {
+    const attempts = [];
+    for (const attempt of [1, 2]) {
+        try {
+            const value = runner();
+            attempts.push({ attempt, outcome: 'completed', detail: `attempt ${attempt}: completed` });
+            return { value, attempts, internalRetries: attempt === 1 ? 0 : 1 };
+        }
+        catch (error) {
+            const head = internalRunnerErrorHead(error);
+            attempts.push({
+                attempt,
+                outcome: 'runner-internal-error',
+                detail: `attempt ${attempt}: runner-internal-error: ${head}`,
+            });
+        }
+    }
+    return {
+        value: null,
+        attempts,
+        internalRetries: 1,
+        failureReason: 'runner-internal-error: persistent after 2/2 attempts',
+    };
+}
 // ── Registry parsing — declarative DATA, validated loudly ─────────────────────────────────────
 const SAFE_ID = /^[a-z0-9][a-z0-9-]{0,79}$/;
 /** same shape as discrimination-gate's path rule: package-relative, no traversal, no metacharacters. */
@@ -355,17 +388,81 @@ export function classifyRunFailure(rawOutput) {
         evidence: 'output matches neither node --test (TAP + # duration_ms) nor vitest (RUN v / Test Files) — no classifier for this runner; structural-vs-behavioural redness cannot be told apart, so the verdict may not be PROVEN',
     };
 }
+function normaliseReportedFile(raw) {
+    let value = raw.trim().replace(/^['"]|['"]$/g, '').replace(/:\d+(?::\d+)?$/, '');
+    value = value.replace(/\\/g, '/');
+    const testSegment = value.lastIndexOf('/test/');
+    if (testSegment >= 0)
+        value = value.slice(testSegment + 1);
+    if (!value.includes('/') || !/\.(?:test|spec)\.[cm]?[jt]sx?$/.test(value))
+        return null;
+    return value;
+}
+/** Parse the failing FILE paths already exposed by supported node --test and vitest shapes. */
+export function attributeBaselineRedness(rawOutput, registryFiles) {
+    const output = stripSgr(rawOutput);
+    const files = [];
+    const add = (raw) => {
+        const file = normaliseReportedFile(raw);
+        if (file !== null && !files.includes(file))
+            files.push(file);
+    };
+    const vitestMatches = [...output.matchAll(/^\s*FAIL\s+(\S+)/gm)];
+    for (const match of vitestMatches)
+        add(match[1] ?? '');
+    const tapMatches = [...output.matchAll(/^not ok \d+\s+-\s+(.+)$/gm)];
+    for (const match of tapMatches)
+        add(match[1] ?? '');
+    for (const match of output.matchAll(/^\s*location:\s*['"]([^'"]+)['"]\s*$/gm)) {
+        add(match[1] ?? '');
+    }
+    const parsedFrom = files.length === 0
+        ? 'unparseable'
+        : vitestMatches.length > 0 ? 'vitest' : 'node-test';
+    if (parsedFrom === 'unparseable') {
+        return { parsedFrom, failingFiles: [], covered: [], extraneous: [] };
+    }
+    const normalisedRegistry = registryFiles
+        .map((file) => normaliseReportedFile(file) ?? file.replace(/\\/g, '/'));
+    const covered = files.filter((file) => normalisedRegistry.some((registryFile) => file === registryFile || file.endsWith(`/${registryFile}`) || registryFile.endsWith(`/${file}`)));
+    const extraneous = files.filter((file) => !covered.includes(file));
+    return { parsedFrom, failingFiles: files, covered, extraneous };
+}
 /**
  * A RED baseline in the scratch copy is a SETUP error, never a mutation result: every subsequent
  * "red under mutation" would be noise, and every "green" a lie about an unrunnable copy.
  */
-export function classifyBaseline(exitCode, runFailureReason) {
+export function classifyBaseline(exitCode, runFailureReason, attribution) {
     if (exitCode === 0)
         return { ok: true, detail: 'baseline suite green in the scratch copy' };
     if (exitCode === null) {
-        return { ok: false, detail: `baseline suite produced no exit code (${runFailureReason ?? 'unknown timeout/spawn failure'}) — the copy is not runnable; fix the copy, do not read this as a mutation result` };
+        const internal = runFailureReason?.startsWith('runner-internal-error:') === true;
+        return {
+            ok: false,
+            reason: internal ? 'runner-internal-error' : 'runner-no-exit',
+            detail: `baseline INCONCLUSIVE — suite produced no exit code (${runFailureReason ?? 'unknown timeout/spawn failure'}) — the copy is not runnable; do not read this as a mutation result`,
+        };
+    }
+    if (attribution === undefined || attribution.parsedFrom === 'unparseable') {
+        return {
+            ok: false,
+            reason: 'baseline-red-files-unparseable',
+            detail: `baseline suite RED (exit ${exitCode}) in the UNMUTATED scratch copy — failing files: unparseable from runner output — the broken copy cannot prove anything`,
+        };
+    }
+    const failing = `failing files: ${attribution.failingFiles.join(', ')}`;
+    if (attribution.extraneous.length > 0 && attribution.covered.length === 0) {
+        return {
+            ok: false,
+            reason: 'extraneous-red-in-allowlist',
+            detail: `baseline suite RED (exit ${exitCode}) in the UNMUTATED scratch copy — ${failing} — extraneous red in the testCommand allowlist; the registry entries themselves are not disproven`,
+        };
     }
-    return { ok: false, detail: `baseline suite RED (exit ${exitCode}) in the UNMUTATED scratch copy — a broken copy cannot prove anything; fix the copy (node_modules link? path-dependent test?) before trusting any verdict` };
+    return {
+        ok: false,
+        reason: 'baseline-red-covered-files',
+        detail: `baseline suite RED (exit ${exitCode}) in the UNMUTATED scratch copy — ${failing} — broken-copy baseline redness touches registry-covered files; fix the copy before evaluating mutations`,
+    };
 }
 // ── Classification (rules 1 + 2, and the drop decision) ───────────────────────────────────────
 /**
@@ -403,7 +500,7 @@ export function classifyBaseline(exitCode, runFailureReason) {
  *     while the contract still holds is the early warning, reported loudly so a human re-pins
  *     `observed` or investigates — silently normalising it would erase the signal.
  */
-export function classifyMutationOutcome(obs) {
+function classifyMutationOutcomeWithoutAttemptLog(obs) {
     const e = obs.entry;
     const minFailing = e.minFailing ?? 1;
     const base = {
@@ -499,12 +596,15 @@ export function classifyMutationOutcome(obs) {
     // not come back green, so the suite is flaky and an unrelated neighbour may be what went red.
     // Not attributable ⇒ INCONCLUSIVE (a failure, never a pass).
     if (obs.rebaselineExitCode !== undefined && obs.rebaselineExitCode !== 0) {
+        const failing = obs.rebaselineAttribution === undefined || obs.rebaselineAttribution.parsedFrom === 'unparseable'
+            ? 'failing files: unparseable from runner output'
+            : `failing files: ${obs.rebaselineAttribution.failingFiles.join(', ')}`;
         return {
             ...base,
             applied: true,
             verdict: 'INCONCLUSIVE',
             drop: false,
-            detail: `suite red under the mutation BUT the restored baseline did not reproduce green (${obs.rebaselineExitCode === null ? `no exit code: ${obs.rebaselineFailureReason ?? 'unknown timeout / spawn failure'}` : `exit ${obs.rebaselineExitCode}`}) — the suite is flaky; the redness is not attributable to the protection and may be an unrelated neighbour`,
+            detail: `suite red under the mutation BUT the restored baseline did not reproduce green (${obs.rebaselineExitCode === null ? `no exit code: ${obs.rebaselineFailureReason ?? 'unknown timeout / spawn failure'}` : `exit ${obs.rebaselineExitCode}`}) — mutation did not revert / flaky restored-tree route; ${failing}; the redness is not attributable to the protection`,
         };
     }
     if (obs.failingCount !== null && obs.failingCount < minFailing) {
@@ -540,6 +640,12 @@ export function classifyMutationOutcome(obs) {
             : `suite red under the mutation (${obs.failingCount === null ? 'failing count unavailable — exit code is the verdict' : `${obs.failingCount} failing`}) — the test discriminates`,
     };
 }
+export function classifyMutationOutcome(obs) {
+    const result = classifyMutationOutcomeWithoutAttemptLog(obs);
+    if (obs.internalAttemptLog === undefined)
+        return result;
+    return { ...result, detail: `${result.detail}; ${obs.internalAttemptLog}` };
+}
 /** Verdicts that fail the gate. INCONCLUSIVE and NOT_APPLIED fail (inconclusive ≠ pass). */
 const FAILING_VERDICTS = new Set(['UNDEFENDED', 'RECEIPT_MISMATCH', 'NOT_APPLIED', 'BELOW_MIN', 'MUTATION_UNPARSEABLE', 'MUTATION_LOAD_FATAL', 'OVER_FAILING', 'INCONCLUSIVE']);
 /** Exit contract: 0 all proven · 1 any entry failed (or red baseline) · (2 = usage/setup, CLI-side). */