@tiphys/kernel 0.0.0 → 0.2.0

package/dist/src/gates/red-witness.js

@@ -0,0 +1,482 @@
+import { mkdirSync, writeFileSync } from "node:fs";
+import { join, relative, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import { pathsIdentifySameObject } from "../path-identity.js";
+import { refuseOpenForWrite, singleLine } from "../task.js";
+import { loadManifest } from "./manifest.js";
+import { exitCodeForStatus, makeGateResult, renderGateResult } from "./result.js";
+import { listWitnessSpecFiles, loadWitnessSpec, memberTouchedFiles, parseWitnessSpec, phaseOwnedMemberIndices, } from "../witness/spec.js";
+import { SPAWN_GREP, computePhaseDiff, evaluateWitness, gitIn, makeScratchRoot, readTestFilesAtHead, removeScratchRoot, resolveRepoRoot, shellSpawnsAndParses, } from "../witness/run.js";
+/**
+ * THE RED-WITNESS GATE (kernel plan M2, M2-P2 steps 6 and 7).
+ *
+ * Registered in gates.manifest.json as `red-witness`, applicability
+ * `required`, precondition `diff-touches` on `src/` and `bin/`, unitLabel
+ * `witnesses evaluated`. Invoked by the runner as
+ *
+ *   node src/gates/red-witness.ts --result <path> --evidence <dir>
+ *     --base <ref> --head <ref>
+ *
+ * plus `--baseline <ref>` when invoked directly: merge-time re-verification
+ * is a PARAMETER, not an enforcement (M2-D-08); it defaults to `--base`.
+ *
+ * WHAT THE GATE DECIDES.
+ *   - Every witness spec changed in the phase diff (the phase's OWN
+ *     witnesses) is evaluated by the harness.
+ *   - Every STORED witness any of whose dangerous-state members touches a
+ *     changed file is re-evaluated; one now green against any of its own
+ *     members is red with reason "witness no longer guards its behavior"
+ *     naming the witness and the measured rate (M2R-002, the N-401 shape).
+ *   - A changed source file under src/ or bin/ with no witness spec
+ *     covering it is RED, never not-applicable (step 7).
+ *   - `--base` absent is `error` (M2-C-3).
+ *
+ * DEPTH REQUIREMENT, documented rather than assumed (STATE.md CR-902
+ * carry-forward): the gate needs `--base` and `--head` resolvable with
+ * history (the diff is base...head, a merge-base diff) and an UNSHALLOW
+ * repository, because the harness scratch-clones it and git refuses to
+ * clone from a shallow source. Both are satisfied by `fetch-depth: 0` on
+ * the CI checkout, which is owned by the workflow's owner, not this phase.
+ * A shallow repository is `error` naming the requirement. On pull_request
+ * events the checkout HEAD is a synthetic merge commit, so the audited
+ * head is always taken from `--head`, never from the checkout.
+ */
+const USAGE = "usage: node src/gates/red-witness.ts --result <path> --evidence <dir> " +
+    "--base <ref> [--head <ref>] [--baseline <ref>] [--phase <id>]";
+function parseArgs(argv) {
+    const options = {};
+    const known = new Map([
+        ["--result", "result"],
+        ["--evidence", "evidence"],
+        ["--base", "base"],
+        ["--head", "head"],
+        ["--baseline", "baseline"],
+        ["--phase", "phase"],
+    ]);
+    for (let index = 0; index < argv.length; index += 2) {
+        const flag = argv[index];
+        const field = known.get(flag);
+        if (field === undefined) {
+            return { usageError: `unknown option ${flag}` };
+        }
+        const value = argv[index + 1];
+        if (value === undefined || value.startsWith("--")) {
+            return { usageError: `${flag} requires a value` };
+        }
+        options[field] = value;
+    }
+    return { options };
+}
+function now() {
+    return new Date().toISOString();
+}
+function errorOutcome(startedAt, detail) {
+    const result = makeGateResult({
+        gate: "red-witness",
+        status: "error",
+        units: 0,
+        unitLabel: "witnesses evaluated",
+        startedAt,
+        endedAt: now(),
+        detail,
+    });
+    return {
+        result,
+        exitCode: exitCodeForStatus(result.status),
+        evaluations: [],
+        reEvaluationMs: 0,
+    };
+}
+/**
+ * True when the repo-relative path is a phase-audited source path.
+ *
+ * WHY `plugin/src/` AND NOT `plugin/`. This list is the COVERAGE OBLIGATION:
+ * a changed path here must be touched by some witness's dangerous state or the
+ * gate reports it uncovered. `src/` and `bin/` are source trees, and the plugin
+ * package's source tree is `plugin/src/`. Adding bare `plugin/` would pull in
+ * `plugin/package.json` and `plugin/tsconfig.json`, which no witness mutates
+ * and which would therefore redden every plugin phase for its own packaging.
+ *
+ * WHY IT IS NOT THE SAME LIST AS THE GATE'S PRECONDITION, which reads
+ * `src/`, `bin/`, `plugin/`. The precondition decides whether the gate RUNS.
+ * This decides what it REQUIRES. T-038 widened the first and left the second,
+ * so from that fix until this one a diff touching only `plugin/` ran the gate
+ * and took no obligation from it: a plugin phase shipping ZERO witnesses was
+ * green. Found by M4-P29 while reading this file for a different reason.
+ */
+function isAuditedSource(path) {
+    return (path.startsWith("src/") ||
+        path.startsWith("bin/") ||
+        path.startsWith("plugin/src/"));
+}
+/**
+ * Run the red-witness gate against a repository. Exported so tests can
+ * drive it without a subprocess; the CLI below is a thin shell over it.
+ */
+export function runRedWitnessGate(run) {
+    const startedAt = now();
+    const rootProbe = resolveRepoRoot(run.repoRoot);
+    if (rootProbe.root === undefined) {
+        return errorOutcome(startedAt, rootProbe.reason);
+    }
+    const repoRoot = rootProbe.root;
+    const shallow = gitIn(repoRoot, ["rev-parse", "--is-shallow-repository"]);
+    if (!shallow.ok) {
+        return errorOutcome(startedAt, shallow.reason);
+    }
+    if (shallow.stdout.trim() === "true") {
+        return errorOutcome(startedAt, "this repository is a shallow clone; the red-witness gate requires " +
+            "full history (fetch-depth: 0) because the phase diff is a " +
+            "merge-base diff and the harness scratch-clones the repository, " +
+            "which git refuses from a shallow source");
+    }
+    const diffOutcome = computePhaseDiff(repoRoot, run.base, run.head ?? "HEAD");
+    if (!diffOutcome.ok) {
+        return errorOutcome(startedAt, diffOutcome.reason);
+    }
+    const diff = diffOutcome.diff;
+    const manifestPath = join(repoRoot, "gates.manifest.json");
+    const manifest = loadManifest(manifestPath);
+    if (!manifest.ok) {
+        return errorOutcome(startedAt, `the destructiveCommands list could not be read (rule (e) needs it): ` +
+            `${manifest.reason}${manifest.diagnostics.length > 0 ? `: ${manifest.diagnostics.join("; ")}` : ""}`);
+    }
+    const behaviorsShown = gitIn(repoRoot, [
+        "show",
+        `${diff.headSha}:test/behaviors.json`,
+    ]);
+    if (!behaviorsShown.ok) {
+        return errorOutcome(startedAt, `test/behaviors.json could not be read at the audited head: ${behaviorsShown.reason}`);
+    }
+    let behaviors;
+    try {
+        behaviors = new Set(Object.keys(JSON.parse(behaviorsShown.stdout)));
+    }
+    catch (error) {
+        return errorOutcome(startedAt, `test/behaviors.json does not parse at the audited head: ${singleLine(String(error))}`);
+    }
+    const testFilesOutcome = readTestFilesAtHead(repoRoot, diff.headSha);
+    if (!testFilesOutcome.ok) {
+        return errorOutcome(startedAt, testFilesOutcome.reason);
+    }
+    // Rule (f)'s derivation: the spawn grep over the changed files' head
+    // contents (deleted files have no head content and cannot be touched by a
+    // member either). Shell scripts (*.sh) are screened by the shell
+    // spawn-and-parse derivation instead of the JS token grep (CR-H2), so a
+    // bin/ shell script that classifies another program's output (the V-2
+    // shape) is not invisible to the capture obligation.
+    const spawningChangedFiles = [];
+    for (const [path, file] of diff.files) {
+        if (file.status === "D") {
+            continue;
+        }
+        const shown = gitIn(repoRoot, ["show", `${diff.headSha}:${path}`]);
+        if (!shown.ok) {
+            continue;
+        }
+        const spawns = path.endsWith(".sh")
+            ? shellSpawnsAndParses(shown.stdout)
+            : SPAWN_GREP.test(shown.stdout);
+        if (spawns) {
+            spawningChangedFiles.push(path);
+        }
+    }
+    spawningChangedFiles.sort();
+    const witnessDir = join(repoRoot, "witness");
+    const listing = listWitnessSpecFiles(witnessDir);
+    if (!listing.ok) {
+        return errorOutcome(startedAt, listing.reason);
+    }
+    const reasons = [];
+    const specs = [];
+    const seenIds = new Map();
+    for (const path of listing.paths) {
+        const loaded = loadWitnessSpec(path);
+        const repoRelative = relative(repoRoot, path).split("\\").join("/");
+        if (!loaded.ok) {
+            reasons.push(`${loaded.reason}${loaded.diagnostics.length > 0 ? `: ${loaded.diagnostics.join("; ")}` : ""}`);
+            continue;
+        }
+        const previous = seenIds.get(loaded.spec.id);
+        if (previous !== undefined) {
+            reasons.push(`witness id ${loaded.spec.id} is declared by both ${previous} and ${repoRelative}`);
+            continue;
+        }
+        seenIds.set(loaded.spec.id, repoRelative);
+        specs.push({ spec: loaded.spec, path, repoRelative });
+    }
+    const readPatchAtHead = (patchPath) => {
+        const shown = gitIn(repoRoot, ["show", `${diff.headSha}:${patchPath}`]);
+        return shown.ok ? shown.stdout : undefined;
+    };
+    const own = specs.filter((entry) => diff.files.has(entry.repoRelative));
+    const stored = specs.filter((entry) => !diff.files.has(entry.repoRelative));
+    /**
+     * A patch member's body at the MERGE BASE, the old side of the ownership
+     * comparison. `readPatchAtHead` above is the new side. Two readers rather
+     * than one because the whole point of reading the body is that the same path
+     * can hold different content on the two revisions.
+     */
+    const readPatchAtMergeBase = (patchPath) => {
+        const shown = gitIn(repoRoot, ["show", `${diff.mergeBaseSha}:${patchPath}`]);
+        return shown.ok ? shown.stdout : undefined;
+    };
+    /**
+     * The members of an own spec that THIS PHASE AUTHORED, which is rule (d)'s
+     * scope. Membership in `own` is file-granular ("some byte of this spec
+     * changed") and rule (d)'s obligation is member-granular ("this declared
+     * dangerous state must intersect the diff"), so the two are reconciled here
+     * rather than by handing the harness a boolean for the whole file.
+     *
+     * The old side is read at the MERGE BASE, which is the revision the diff
+     * itself is taken against. A baseline that is absent, unreadable or invalid
+     * yields `undefined`, and `phaseOwnedMemberIndices` then owns every member:
+     * an added spec is wholly the phase's, and so is one whose previous version
+     * cannot be established.
+     *
+     * The WHOLE spec goes in, not just its members, because the spec's claim
+     * (`behavior` and `tests`) is part of what rule (d) is an obligation on. See
+     * `claimRePointed` for which fields are in that set, why the other four are
+     * not, and why the comparison is DIRECTIONAL: re-pointing a claim takes the
+     * obligation, extending its named tests does not.
+     */
+    const ownedMembersOf = (entry) => {
+        const readers = { head: readPatchAtHead, baseline: readPatchAtMergeBase };
+        const shown = gitIn(repoRoot, [
+            "show",
+            `${diff.mergeBaseSha}:${entry.repoRelative}`,
+        ]);
+        if (!shown.ok) {
+            return phaseOwnedMemberIndices(entry.spec, undefined, readers);
+        }
+        const baseline = parseWitnessSpec(shown.stdout, `${diff.mergeBaseSha}:${entry.repoRelative}`);
+        return phaseOwnedMemberIndices(entry.spec, baseline.ok ? baseline.spec : undefined, readers);
+    };
+    const triggeredStored = stored.filter((entry) => entry.spec.dangerousStates.some((member) => memberTouchedFiles(member, readPatchAtHead).some((file) => diff.files.has(file))));
+    // Coverage (step 7): source changed with no witness spec covering it is
+    // red, never not-applicable. Coverage semantics are decision D-P2-2 in
+    // the work history.
+    const covered = new Set();
+    for (const entry of specs) {
+        for (const member of entry.spec.dangerousStates) {
+            for (const file of memberTouchedFiles(member, readPatchAtHead)) {
+                covered.add(file);
+            }
+        }
+    }
+    const uncovered = [];
+    for (const [path, file] of diff.files) {
+        if (file.status === "D" || !isAuditedSource(path)) {
+            continue;
+        }
+        if (!covered.has(path)) {
+            uncovered.push(path);
+        }
+    }
+    uncovered.sort();
+    if (uncovered.length > 0) {
+        reasons.push(`source changed with no witness spec covering it: ${uncovered.join(", ")}`);
+    }
+    const evaluations = [];
+    let reEvaluationMs = 0;
+    const scratchRoot = makeScratchRoot();
+    try {
+        const baseInputs = {
+            repoRoot,
+            headSha: diff.headSha,
+            baselineRef: run.baseline ?? run.base,
+            diff,
+            destructiveCommands: manifest.manifest.destructiveCommands,
+            behaviors,
+            testFiles: testFilesOutcome.files,
+            spawningChangedFiles,
+            scratchRoot,
+        };
+        for (const entry of own) {
+            const inputs = {
+                ...baseInputs,
+                phaseOwnedMembers: ownedMembersOf(entry),
+            };
+            if (run.hooks !== undefined) {
+                inputs.hooks = run.hooks;
+            }
+            const evaluation = evaluateWitness(entry.spec, entry.repoRelative, inputs);
+            evaluations.push(evaluation);
+            if (evaluation.status !== "green") {
+                reasons.push(`witness ${evaluation.witness}: ${evaluation.status}: ${evaluation.reasons.join("; ")}`);
+            }
+        }
+        const reEvaluationStart = Date.now();
+        for (const entry of triggeredStored) {
+            // A stored witness is one the phase diff does not touch at all, so no
+            // member of it is the phase's and rule (d) has nothing to apply to.
+            const inputs = {
+                ...baseInputs,
+                phaseOwnedMembers: new Set(),
+            };
+            if (run.hooks !== undefined) {
+                inputs.hooks = run.hooks;
+            }
+            const evaluation = evaluateWitness(entry.spec, entry.repoRelative, inputs);
+            evaluations.push(evaluation);
+            if (evaluation.status === "red") {
+                const rates = evaluation.members
+                    .filter((member) => member.rate !== undefined)
+                    .map((member) => `member ${String(member.index)} red ` +
+                    `${String(member.rate?.red)}/${String(member.rate?.total)}`)
+                    .join(", ");
+                reasons.push(`witness ${evaluation.witness} no longer guards its behavior ` +
+                    `(${rates === "" ? evaluation.reasons.join("; ") : rates})`);
+            }
+            else if (evaluation.status === "error") {
+                reasons.push(`witness ${evaluation.witness}: error: ${evaluation.reasons.join("; ")}`);
+            }
+        }
+        reEvaluationMs = Date.now() - reEvaluationStart;
+    }
+    finally {
+        removeScratchRoot(scratchRoot);
+    }
+    let status = "green";
+    if (evaluations.some((evaluation) => evaluation.status === "error")) {
+        status = "error";
+    }
+    else if (reasons.length > 0) {
+        status = "red";
+    }
+    const evidence = [];
+    if (run.evidenceDir !== undefined) {
+        const recordsPath = join(run.evidenceDir, "witness-records.json");
+        const refusal = refuseOpenForWrite(recordsPath);
+        if (refusal === undefined) {
+            try {
+                mkdirSync(run.evidenceDir, { recursive: true });
+                writeFileSync(recordsPath, `${JSON.stringify({
+                    base: diff.baseSha,
+                    head: diff.headSha,
+                    spawningChangedFiles,
+                    uncoveredSources: uncovered,
+                    reEvaluationMs,
+                    evaluations,
+                }, null, 2)}\n`);
+                evidence.push("witness-records.json");
+            }
+            catch {
+                // The record still carries the verdict; evidence is best-effort.
+            }
+        }
+    }
+    const detail = `${String(evaluations.length)} witness(es) evaluated ` +
+        `(${String(own.length)} own, ${String(triggeredStored.length)} stored ` +
+        `re-evaluated in ${String(reEvaluationMs)}ms); ` +
+        (reasons.length === 0
+            ? "every witness red against every declared dangerous state and green at head"
+            : reasons.join("; "));
+    const result = makeGateResult({
+        gate: "red-witness",
+        status,
+        units: evaluations.length,
+        unitLabel: "witnesses evaluated",
+        startedAt,
+        endedAt: now(),
+        detail,
+        evidence,
+    });
+    return {
+        result,
+        exitCode: exitCodeForStatus(result.status),
+        evaluations,
+        reEvaluationMs,
+    };
+}
+function main(argv) {
+    const parsed = parseArgs(argv);
+    if (parsed.options === undefined) {
+        process.stderr.write(`tiphys red-witness: ${parsed.usageError}\n${USAGE}\n`);
+        return 64;
+    }
+    const options = parsed.options;
+    if (options.result === undefined) {
+        process.stderr.write(`tiphys red-witness: --result is required\n${USAGE}\n`);
+        return 64;
+    }
+    let outcome;
+    if (options.base === undefined) {
+        // M2-C-3 (M2R-003): a required invocation parameter absent is error,
+        // never not-applicable and never a guess.
+        outcome = errorOutcome(now(), "--base was not supplied; the phase diff cannot be computed (M2-C-3)");
+    }
+    else {
+        const run = { repoRoot: process.cwd(), base: options.base };
+        if (options.head !== undefined) {
+            run.head = options.head;
+        }
+        if (options.baseline !== undefined) {
+            run.baseline = options.baseline;
+        }
+        if (options.evidence !== undefined) {
+            run.evidenceDir = options.evidence;
+        }
+        try {
+            outcome = runRedWitnessGate(run);
+        }
+        catch (error) {
+            // No throw may escape as exit 1: that is the RED code (the runner's
+            // own crash-discipline rule, applied to this gate).
+            outcome = errorOutcome(now(), `the red-witness gate failed: ${singleLine(error.message ?? String(error))}`);
+        }
+    }
+    const refusal = refuseOpenForWrite(options.result);
+    if (refusal !== undefined) {
+        process.stderr.write(`tiphys red-witness: ${refusal}\n`);
+        return 21;
+    }
+    try {
+        writeFileSync(options.result, renderGateResult(outcome.result));
+    }
+    catch (error) {
+        process.stderr.write(`tiphys red-witness: the result record could not be written: ${singleLine(String(error))}\n`);
+        return 21;
+    }
+    process.stdout.write(`red-witness: ${outcome.result.status} (${outcome.result.detail})\n`);
+    return outcome.exitCode;
+}
+const invokedDirectly = (() => {
+    const entry = process.argv[1];
+    if (entry === undefined) {
+        return false;
+    }
+    // IDENTITY, NOT STRING EQUALITY (M4-P2 fix round, 2026-09-16). Going
+    // through a URL does not change what is compared: `resolve` leaves the
+    // caller's spelling intact while `import.meta.url` is canonical, so an
+    // invocation through a symlink leaves this gate silently not running.
+    return pathsIdentifySameObject(fileURLToPath(import.meta.url), entry);
+})();
+if (invokedDirectly) {
+    // `process.exitCode`, NEVER `process.exit(main(...))` (M4-P29). This gate
+    // runs as a SUBPROCESS, so fd 1 is a buffered stream the parent owns and a
+    // write to one is QUEUED rather than completed. `process.exit` ends the
+    // process without draining that queue, so everything past the buffer is
+    // DISCARDED, while the exit code survives and the loss is silent.
+    //
+    // BE EXACT ABOUT WHICH STREAM, because the ceiling differs by a factor of
+    // two and the obvious word is the wrong one. `spawnSync`, which is how the
+    // registry runner invokes gates (src/gates/run.ts:1528), hands a child
+    // SOCKETPAIRS, not pipes; a shell pipeline, a `tee` or a CI log collector
+    // hands it a real pipe. Measured at the pre-fix parent commit on this
+    // container, same invocation, only the reader changed:
+    //
+    //   reader            wrote     delivered
+    //   regular file      176,530   176,530
+    //   shell pipe        176,530    65,536   (one pipe buffer)
+    //   spawnSync         434,530   146,176   (the socket send buffer)
+    //
+    // A regular file never truncates, which is why this survives casual
+    // testing. This gate is the measured instance rather than a hypothetical
+    // one: its single stdout line carries the whole `detail`, and `detail`
+    // grows with the number of uncovered sources and of red witnesses.
+    // Assigning `process.exitCode` lets the process end normally, which drains
+    // the queue first, and the full capture is
+    // witness/captures/m4-p29-gate-cli-stdio.txt.
+    process.exitCode = main(process.argv.slice(2));
+}