@tiphys/kernel 0.0.0 → 0.1.0

package/dist/src/gates/manifest.d.ts

@@ -0,0 +1,99 @@
+import type { SchemaDocument } from "./validate.ts";
+/**
+ * THE GATE MANIFEST (kernel plan M2, M2-P1 step 6).
+ *
+ * One manifest per repository. It declares which gates exist, how each is
+ * invoked, what one unit of its work is, whether an unmet precondition
+ * fails the run, and which commands can destroy work.
+ *
+ * SCHEMA RESOLUTION FROM SOURCE AND FROM dist/ (step 5). The schema
+ * documents sit beside this module at `./schemas/*.json` and are resolved
+ * through `import.meta.url`, so the same code finds
+ * `src/gates/schemas/...` when run from source and
+ * `dist/src/gates/schemas/...` when run from the compiled entry. `tsc` does
+ * not copy JSON, which was MEASURED rather than assumed (the measurement is
+ * in the work history), so the build script copies the directory into
+ * `dist/` and criterion 10 witnesses both documents in `npm pack` output.
+ * They are deliberately NOT imported as modules: `resolveJsonModule` is off
+ * in both tsconfigs, and turning it on would inline the schema into the
+ * bundle and make the shipped document and the enforced document two
+ * different things.
+ *
+ * M2-C-6: the manifest path comes from the caller, so it is read through the
+ * DELIVERED `readRegularFileIfPresent`. A named pipe at the manifest path
+ * reports `error` naming the path and the type, and never blocks.
+ */
+export type PreconditionKind = "file-exists" | "file-absent" | "branch-matches" | "diff-touches" | "command-exit-zero";
+export declare const PRECONDITION_KINDS: readonly PreconditionKind[];
+export type RunParameter = "base" | "head" | "phase";
+export interface PreconditionSpec {
+    id: string;
+    kind: PreconditionKind;
+    path?: string;
+    pattern?: string;
+    paths?: string[];
+    command?: string[];
+}
+export interface GateEntry {
+    id: string;
+    command: string[];
+    unitLabel: string;
+    applicability: "required" | "conditional";
+    parameters?: RunParameter[];
+    precondition?: PreconditionSpec;
+    modes?: string[];
+}
+export interface GateManifest {
+    version: number;
+    gates: GateEntry[];
+    destructiveCommands: string[];
+}
+export type ManifestLoad = {
+    ok: true;
+    manifest: GateManifest;
+    sha256: string;
+    body: string;
+} | {
+    ok: false;
+    reason: string;
+    diagnostics: string[];
+};
+export declare function manifestSchema(): SchemaDocument;
+export declare function resultSchema(): SchemaDocument;
+/**
+ * Absolute paths of every schema document `manifest-self-check` validates.
+ *
+ * ENUMERATED, NOT ENUMERABLE-BY-HAND (fix round, M2-P1). This milestone's
+ * plan (kernel-plan-v1.md) adds four more schema documents to this same
+ * directory across M2-P2, M2-P4, M2-P5, M2-P6 and M2-P7. A fixed two-entry
+ * list here was the mechanism, not a fluke: it named the two documents that
+ * existed at the time this function was written and would keep returning
+ * exactly those two forever, so manifest-self-check would silently stop
+ * validating every document a later phase ships, while test/gates.test.ts's
+ * independent readdir-based parity check reddens correctly the moment a
+ * phase adds one (CR-812's test, `test/gates.test.ts` near line 2378). The
+ * fix is to make the SAME enumeration the source of truth here: read the
+ * directory beside this module, keep entries matching `*.schema.json`, and
+ * sort them by filename so the order is deterministic across platforms and
+ * across runs (readdir order is not guaranteed by POSIX). Every document a
+ * phase drops into `src/gates/schemas/` is then validated automatically,
+ * and the parity property the test checks becomes structural rather than
+ * a thing two call sites have to be kept in sync by hand.
+ */
+export declare function schemaDocumentPaths(): string[];
+/**
+ * Validate an already-parsed manifest document. Returns the diagnostics in
+ * the contract's deterministic order (by pointer, then message).
+ */
+export declare function validateManifestDocument(document: unknown): string[];
+/** Validate an already-parsed gate result record. */
+export declare function validateResultDocument(document: unknown): string[];
+/**
+ * Load and validate a manifest from a path the caller supplied.
+ *
+ * Fail closed at every step: not a regular file, absent, unparseable, or
+ * schema-invalid all produce `ok: false` with a reason. None of them
+ * produces a manifest with fewer gates in it, which is the failure this
+ * whole milestone exists to make impossible.
+ */
+export declare function loadManifest(path: string): ManifestLoad;

package/dist/src/gates/manifest.js

@@ -0,0 +1,208 @@
+import { createHash } from "node:crypto";
+import { readdirSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+import { readRegularFileIfPresent } from "../task.js";
+import { DIAGNOSTIC_MESSAGES, formatDiagnostics, loadSchema, validate, } from "./validate.js";
+export const PRECONDITION_KINDS = [
+    "file-exists",
+    "file-absent",
+    "branch-matches",
+    "diff-touches",
+    "command-exit-zero",
+];
+const schemaDirectory = new URL("./schemas/", import.meta.url);
+function readSchemaDocument(name) {
+    const path = fileURLToPath(new URL(name, schemaDirectory));
+    const read = readRegularFileIfPresent(path);
+    if (read.kind !== "read") {
+        throw new Error(read.kind === "absent"
+            ? `schema document ${path} is missing from this installation`
+            : read.reason);
+    }
+    const parsed = JSON.parse(read.body);
+    const loaded = loadSchema(parsed, name);
+    if (!loaded.ok) {
+        throw new Error(loaded.reason);
+    }
+    return loaded.schema;
+}
+/** The two schema documents this milestone ships, loaded once. */
+let cachedManifestSchema;
+let cachedResultSchema;
+export function manifestSchema() {
+    if (cachedManifestSchema === undefined) {
+        cachedManifestSchema = readSchemaDocument("gate-manifest.schema.json");
+    }
+    return cachedManifestSchema;
+}
+export function resultSchema() {
+    if (cachedResultSchema === undefined) {
+        cachedResultSchema = readSchemaDocument("gate-result.schema.json");
+    }
+    return cachedResultSchema;
+}
+/**
+ * Absolute paths of every schema document `manifest-self-check` validates.
+ *
+ * ENUMERATED, NOT ENUMERABLE-BY-HAND (fix round, M2-P1). This milestone's
+ * plan (kernel-plan-v1.md) adds four more schema documents to this same
+ * directory across M2-P2, M2-P4, M2-P5, M2-P6 and M2-P7. A fixed two-entry
+ * list here was the mechanism, not a fluke: it named the two documents that
+ * existed at the time this function was written and would keep returning
+ * exactly those two forever, so manifest-self-check would silently stop
+ * validating every document a later phase ships, while test/gates.test.ts's
+ * independent readdir-based parity check reddens correctly the moment a
+ * phase adds one (CR-812's test, `test/gates.test.ts` near line 2378). The
+ * fix is to make the SAME enumeration the source of truth here: read the
+ * directory beside this module, keep entries matching `*.schema.json`, and
+ * sort them by filename so the order is deterministic across platforms and
+ * across runs (readdir order is not guaranteed by POSIX). Every document a
+ * phase drops into `src/gates/schemas/` is then validated automatically,
+ * and the parity property the test checks becomes structural rather than
+ * a thing two call sites have to be kept in sync by hand.
+ */
+export function schemaDocumentPaths() {
+    const directory = fileURLToPath(schemaDirectory);
+    return readdirSync(directory)
+        .filter((name) => name.endsWith(".schema.json"))
+        .sort()
+        .map((name) => fileURLToPath(new URL(name, schemaDirectory)));
+}
+/**
+ * The kind-specific required fields, checked here rather than in the schema.
+ *
+ * WHY NOT IN THE SCHEMA. Expressing "kind file-exists requires path" needs
+ * conditional composition (`if`/`then`, or `oneOf`), and both are outside
+ * M2-D-04's closed keyword set, which DR-0013 decided against growing. So
+ * the check lives in code and emits the SAME `INVALID <pointer> <message>`
+ * diagnostics, which keeps one diagnostic contract rather than two. When
+ * M3-P1 swaps in Ajv the constraint can move into the schema without any
+ * consumer noticing, because the output line is unchanged.
+ */
+const REQUIRED_FIELD_FOR_KIND = {
+    "file-exists": "path",
+    "file-absent": "path",
+    "branch-matches": "pattern",
+    "diff-touches": "paths",
+    "command-exit-zero": "command",
+};
+function preconditionFieldDiagnostics(manifest) {
+    const found = [];
+    const gates = manifest.gates;
+    if (!Array.isArray(gates)) {
+        return found;
+    }
+    for (let index = 0; index < gates.length; index += 1) {
+        const gate = gates[index];
+        const precondition = gate?.precondition;
+        if (precondition === undefined || precondition === null) {
+            continue;
+        }
+        const kind = precondition["kind"];
+        if (typeof kind !== "string" || !PRECONDITION_KINDS.includes(kind)) {
+            continue;
+        }
+        const field = REQUIRED_FIELD_FOR_KIND[kind];
+        if (precondition[field] === undefined) {
+            found.push({
+                pointer: `#/gates/${index}/precondition/${field}`,
+                message: DIAGNOSTIC_MESSAGES.required(field),
+            });
+        }
+    }
+    return found;
+}
+/** Every duplicate gate id, as diagnostics. A registry keyed by name cannot hold two. */
+function duplicateIdDiagnostics(manifest) {
+    const found = [];
+    const gates = manifest.gates;
+    if (!Array.isArray(gates)) {
+        return found;
+    }
+    const seen = new Set();
+    for (let index = 0; index < gates.length; index += 1) {
+        const id = gates[index]?.id;
+        if (typeof id !== "string") {
+            continue;
+        }
+        if (seen.has(id)) {
+            found.push({
+                pointer: `#/gates/${index}/id`,
+                message: DIAGNOSTIC_MESSAGES.duplicateId(JSON.stringify(id)),
+            });
+        }
+        seen.add(id);
+    }
+    return found;
+}
+/**
+ * Validate an already-parsed manifest document. Returns the diagnostics in
+ * the contract's deterministic order (by pointer, then message).
+ */
+export function validateManifestDocument(document) {
+    const diagnostics = [
+        ...validate(manifestSchema(), document),
+        ...preconditionFieldDiagnostics(document),
+        ...duplicateIdDiagnostics(document),
+    ];
+    diagnostics.sort((a, b) => {
+        if (a.pointer !== b.pointer) {
+            return a.pointer < b.pointer ? -1 : 1;
+        }
+        if (a.message === b.message) {
+            return 0;
+        }
+        return a.message < b.message ? -1 : 1;
+    });
+    return formatDiagnostics(diagnostics);
+}
+/** Validate an already-parsed gate result record. */
+export function validateResultDocument(document) {
+    return formatDiagnostics(validate(resultSchema(), document));
+}
+/**
+ * Load and validate a manifest from a path the caller supplied.
+ *
+ * Fail closed at every step: not a regular file, absent, unparseable, or
+ * schema-invalid all produce `ok: false` with a reason. None of them
+ * produces a manifest with fewer gates in it, which is the failure this
+ * whole milestone exists to make impossible.
+ */
+export function loadManifest(path) {
+    const read = readRegularFileIfPresent(path);
+    if (read.kind === "absent") {
+        return {
+            ok: false,
+            reason: `manifest ${path} does not exist`,
+            diagnostics: [],
+        };
+    }
+    if (read.kind === "refused") {
+        return { ok: false, reason: read.reason, diagnostics: [] };
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(read.body);
+    }
+    catch (error) {
+        return {
+            ok: false,
+            reason: `manifest ${path} does not parse as JSON: ${error.message}`,
+            diagnostics: [],
+        };
+    }
+    const diagnostics = validateManifestDocument(parsed);
+    if (diagnostics.length > 0) {
+        return {
+            ok: false,
+            reason: `manifest ${path} is not a valid gate manifest`,
+            diagnostics,
+        };
+    }
+    return {
+        ok: true,
+        manifest: parsed,
+        sha256: createHash("sha256").update(read.body).digest("hex"),
+        body: read.body,
+    };
+}

package/dist/src/gates/migrations.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/src/gates/migrations.js

@@ -0,0 +1,36 @@
+import { realpathSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+import { runReleaseGate } from "./release.js";
+/**
+ * THE MIGRATIONS GATE ENTRY (kernel plan M2, M2-P7 step 4). A thin entry
+ * point that names the declared `migrations` verification and calls the one
+ * contract module, `src/gates/release.ts`. Deploy verification and
+ * migration verification are two INSTANCES of one post-merge verification
+ * contract, not two contracts (DR-0014, investigation section 1): the two
+ * registry entries exist so that a project can declare one and not the
+ * other, and so the evidence bundle shows two lines rather than one
+ * aggregate that hides which half was skipped.
+ *
+ * The two inventories are not symmetric (plan criterion 8): a declared
+ * REPOSITORY migrations location containing zero migrations is
+ * not-applicable, but a non-empty repository inventory with an EMPTY
+ * applied inventory is red, never not-applicable, because that is the
+ * recorded incident exactly ("migrations skipped by a flake while the code
+ * deployed anyway"). The asymmetry lives in the migrations-command adapter;
+ * this entry is shape-identical to deploy's.
+ */
+function isMain() {
+    const argv1 = process.argv[1];
+    if (argv1 === undefined) {
+        return false;
+    }
+    try {
+        return realpathSync(argv1) === realpathSync(fileURLToPath(import.meta.url));
+    }
+    catch {
+        return false;
+    }
+}
+if (isMain()) {
+    process.exitCode = await runReleaseGate("migrations", process.argv.slice(2));
+}

package/dist/src/gates/pin.d.ts

@@ -0,0 +1,114 @@
+/**
+ * RUN PINNING (kernel plan M2, M2-P1 step 3; M2-C-5; M2-D-06).
+ *
+ * T-004 lesson 3: "a test run is only evidence if you can prove what it
+ * ran". In that incident no artifact recorded the content of the source
+ * files during a failing run, so a forensic reconstruction was the only way
+ * to establish that the tree had been rewritten underneath the run, and the
+ * root cause was never awarded.
+ *
+ * A pin is that artifact: the file set of the tree that was actually
+ * executed, with sha256, size and mtimeMs per file, taken at the start and
+ * at the end of the run. ANY difference in ANY of the four fields (the
+ * path's presence included) is a difference and makes the run's record
+ * `error`.
+ *
+ * WHY ctimeMs IS PINNED TOO (CR-809, added in fix round 1). mtime is
+ * SETTABLE FROM USERSPACE. `cp -p`, `rsync -a` and `tar -x` all restore it
+ * through `utimensat` at nanosecond precision, so a rewrite performed by any
+ * of those three ordinary commands passes a pin of {sha256, size, mtimeMs}
+ * without a mark, and T-004's incident is a rewrite. ctime is the inode
+ * change time: no userspace call sets it, and `utimensat` BUMPS it, so the
+ * very act of restoring mtime is what makes the change visible. It also
+ * catches replace-by-rename, which changes the inode.
+ *
+ * This is a strict ADDITION to M2-C-5's four fields, never a substitution:
+ * the constraint says any difference in file set, sha256, size or mtime makes
+ * the record `error`, and pinning a fifth field can only make more runs
+ * `error`, never fewer. M2-P2 criterion 7 and M2-P3 criterion 8 are pin
+ * witnesses and should be read against five fields, not four.
+ *
+ * The residue, stated rather than left to be discovered: ctime is not
+ * forgeable from userspace, but it is not a cryptographic seal either. A
+ * privileged actor with raw device access can write any inode field it
+ * likes. That is outside anything this kernel can measure.
+ *
+ * WHY mtimeMs IS PINNED AND A CONTENT HASH IS NOT ENOUGH. T-004's forensics
+ * describe a BYTE-IDENTICAL rewrite: `src/lock.ts` was replaced with
+ * pristine content 42.8 seconds into the failing run. A content-only pin
+ * passes that unchanged, and the whole value of the pin would be lost at
+ * precisely the shape the incident actually had. M2-P2 criterion 7 turns
+ * that into a witness rather than an assertion.
+ *
+ * M2-C-6 IS OBEYED BY REUSE, NOT BY REIMPLEMENTATION. The walk reads paths
+ * it did not create, so every open is preceded by the DELIVERED
+ * `classifyEntry` from src/task.ts. There is no second copy of "may this
+ * path be opened" here: T-005 records that this project paid for that class
+ * twice because the second component reimplemented the mechanism. The one
+ * `readFileSync` in this module sits on the line after the probe, and it is
+ * the only read of an externally supplied path anywhere in `src/gates/` that
+ * is not `readRegularFileIfPresent`, which returns UTF-8 text and therefore
+ * cannot hash a binary file honestly.
+ *
+ * `lstatSync` and `statSync` here are PROBES, not opens: they are the same
+ * two syscalls `classifyEntry` itself performs, they answer questions about
+ * the directory entry, and neither can block on a named pipe. They are used
+ * only to decide directory-ness and to read size and mtime, never to decide
+ * whether a path may be opened, which stays the delivered helper's job.
+ *
+ * FAIL CLOSED ON ANYTHING THAT IS NOT A REGULAR FILE OR A REAL DIRECTORY.
+ * A named pipe, socket or device node inside a pinned root makes `takePin`
+ * THROW with a reason naming the path and the observed type. It never opens
+ * the path, so it never blocks, and the caller turns the throw into an
+ * `error` record. Directory symlinks are deliberately not followed: a pin
+ * that follows them can be made to walk outside its declared roots or to
+ * loop, and neither is a measurement.
+ */
+export interface PinFile {
+    /** `join(root, ...)` for the root exactly as the caller supplied it. */
+    path: string;
+    sha256: string;
+    size: number;
+    mtimeMs: number;
+    /** Inode change time. Not settable from userspace; see the header. */
+    ctimeMs: number;
+}
+export interface Pin {
+    roots: string[];
+    takenAt: string;
+    /**
+     * `files.length`, carried explicitly so a vacuous pin is visible in the
+     * RECORD and not only to a caller who thinks to check (CR-804). Nothing in
+     * the shape used to distinguish "the tree did not change" from "no tree was
+     * measured", at the module two other phases consume as primary evidence.
+     */
+    fileCount: number;
+    files: PinFile[];
+}
+export type PinFieldName = "sha256" | "size" | "mtimeMs" | "ctimeMs";
+export type PinDifference = {
+    path: string;
+    kind: "added";
+} | {
+    path: string;
+    kind: "removed";
+} | {
+    path: string;
+    kind: "changed";
+    fields: PinFieldName[];
+};
+/**
+ * Pin the given roots. Throws with a reason naming the path and the observed
+ * type when a root, or anything under it, is neither a regular file nor a
+ * real directory (M2-C-6, fail closed). Callers wrap this with `runStep`
+ * from src/task.ts and report `error`.
+ */
+export declare function takePin(roots: string[]): Pin;
+/**
+ * Every difference between two pins, in a deterministic order (by path).
+ * A byte-identical rewrite that changes only mtimeMs is a difference, which
+ * is the whole reason mtimeMs is in the record.
+ */
+export declare function comparePins(a: Pin, b: Pin): PinDifference[];
+/** One line per difference, for a record's detail text. */
+export declare function describePinDifference(difference: PinDifference): string;

package/dist/src/gates/pin.js

@@ -0,0 +1,154 @@
+import { createHash } from "node:crypto";
+import { lstatSync, readFileSync, readdirSync, statSync } from "node:fs";
+import { join } from "node:path";
+import { classifyEntry } from "../task.js";
+function hashFile(path) {
+    // THE PROBE, then the open. The order is the point (MECHANISMS.md, CR-520).
+    const entry = classifyEntry(path);
+    if (entry.kind !== "regular") {
+        throw new Error(entry.kind === "absent" || entry.kind === "dangling"
+            ? `${path} vanished while the pin was being taken`
+            : entry.reason);
+    }
+    const stats = statSync(path);
+    const body = readFileSync(path);
+    return {
+        path,
+        sha256: createHash("sha256").update(body).digest("hex"),
+        size: stats.size,
+        mtimeMs: stats.mtimeMs,
+        ctimeMs: stats.ctimeMs,
+    };
+}
+/**
+ * True only for a REAL directory, never for a symlink that resolves to one.
+ * lstat answers about the link itself, so a symlinked directory falls
+ * through to the regular-file probe and is refused there.
+ */
+function isRealDirectory(path) {
+    try {
+        return lstatSync(path).isDirectory();
+    }
+    catch {
+        return false;
+    }
+}
+function walk(root, dir, into) {
+    const names = readdirSync(dir).sort();
+    for (const name of names) {
+        const path = join(dir, name);
+        if (isRealDirectory(path)) {
+            walk(root, path, into);
+            continue;
+        }
+        const entry = classifyEntry(path);
+        if (entry.kind === "absent" || entry.kind === "dangling") {
+            // Raced away, or a dangling symlink: nothing to hash, and nothing
+            // hidden either, because a later pin reports it as added.
+            continue;
+        }
+        if (entry.kind !== "regular") {
+            throw new Error(`${entry.reason}; refusing to pin ${root}`);
+        }
+        into.push(hashFile(path));
+    }
+}
+/**
+ * Pin the given roots. Throws with a reason naming the path and the observed
+ * type when a root, or anything under it, is neither a regular file nor a
+ * real directory (M2-C-6, fail closed). Callers wrap this with `runStep`
+ * from src/task.ts and report `error`.
+ */
+export function takePin(roots) {
+    const files = [];
+    if (roots.length === 0) {
+        throw new Error("a pin over no roots measures nothing (M2-C-5)");
+    }
+    for (const root of roots) {
+        const before = files.length;
+        if (isRealDirectory(root)) {
+            walk(root, root, files);
+            // THE VACUITY FLOOR (CR-804). A root a caller DECLARED that holds no
+            // files is a configuration error, not a measurement of an unchanged
+            // tree, and the two are indistinguishable in the result. M2-P2 pins
+            // "the clone's source and test roots"; if a scratch clone puts sources
+            // one directory deeper than the computed root, a silent empty pin
+            // reports no difference and the gate goes green on evidence nobody
+            // took. The rule lives HERE, in the module that carries the mechanism,
+            // rather than in each consumer (T-005).
+            if (files.length === before) {
+                throw new Error(`pin root ${root} contributed no files; a declared root that holds nothing is a configuration error, not an unchanged tree (M2-C-5)`);
+            }
+            continue;
+        }
+        const entry = classifyEntry(root);
+        if (entry.kind === "absent" || entry.kind === "dangling") {
+            throw new Error(`pin root ${root} does not exist`);
+        }
+        if (entry.kind === "regular") {
+            files.push(hashFile(root));
+            continue;
+        }
+        throw new Error(`${entry.reason}; refusing to pin ${root}`);
+    }
+    files.sort((a, b) => (a.path < b.path ? -1 : a.path > b.path ? 1 : 0));
+    return {
+        roots: [...roots],
+        takenAt: new Date().toISOString(),
+        fileCount: files.length,
+        files,
+    };
+}
+/**
+ * Every difference between two pins, in a deterministic order (by path).
+ * A byte-identical rewrite that changes only mtimeMs is a difference, which
+ * is the whole reason mtimeMs is in the record.
+ */
+export function comparePins(a, b) {
+    const before = new Map(a.files.map((f) => [f.path, f]));
+    const after = new Map(b.files.map((f) => [f.path, f]));
+    const paths = [...new Set([...before.keys(), ...after.keys()])].sort();
+    const differences = [];
+    for (const path of paths) {
+        const start = before.get(path);
+        const end = after.get(path);
+        if (start === undefined && end !== undefined) {
+            differences.push({ path, kind: "added" });
+            continue;
+        }
+        if (start !== undefined && end === undefined) {
+            differences.push({ path, kind: "removed" });
+            continue;
+        }
+        if (start === undefined || end === undefined) {
+            continue;
+        }
+        const fields = [];
+        if (start.sha256 !== end.sha256) {
+            fields.push("sha256");
+        }
+        if (start.size !== end.size) {
+            fields.push("size");
+        }
+        if (start.mtimeMs !== end.mtimeMs) {
+            fields.push("mtimeMs");
+        }
+        if (start.ctimeMs !== end.ctimeMs) {
+            fields.push("ctimeMs");
+        }
+        if (fields.length > 0) {
+            differences.push({ path, kind: "changed", fields });
+        }
+    }
+    return differences;
+}
+/** One line per difference, for a record's detail text. */
+export function describePinDifference(difference) {
+    if (difference.kind === "added") {
+        return `${difference.path} was added during the run`;
+    }
+    if (difference.kind === "removed") {
+        return `${difference.path} was removed during the run`;
+    }
+    return `${difference.path} changed during the run (${difference.fields.join(", ")})`;
+}

package/dist/src/gates/red-witness.d.ts

@@ -0,0 +1,22 @@
+import type { GateResult } from "./result.ts";
+import type { WitnessEvaluation, WitnessHooks } from "../witness/run.ts";
+export interface RedWitnessOutcome {
+    result: GateResult;
+    exitCode: number;
+    evaluations: WitnessEvaluation[];
+    /** Wall-clock cost of the stored-witness re-evaluation, milliseconds. */
+    reEvaluationMs: number;
+}
+export interface RedWitnessRun {
+    repoRoot: string;
+    base: string;
+    head?: string;
+    baseline?: string;
+    evidenceDir?: string;
+    hooks?: WitnessHooks;
+}
+/**
+ * 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 declare function runRedWitnessGate(run: RedWitnessRun): RedWitnessOutcome;