knodin 0.7.6 → 0.8.3

package/dist/src/release-preflight.js

@@ -0,0 +1,513 @@
+import { spawnSync } from "node:child_process";
+import { createHash, createPublicKey } from "node:crypto";
+import fs from "node:fs";
+import path from "node:path";
+import { compareBytes } from "./compare.js";
+import { validateRootCeremonyManifest } from "./update-ceremony.js";
+import { canonicalizeUpdateMetadata, verifyUpdateRootChain, } from "./update-trust.js";
+export const RELEASE_PREFLIGHT_DEPENDENCIES = [
+    "C60",
+    "C62",
+    "C63",
+    "C64",
+    "C65",
+    "C66",
+    "C75",
+];
+export const RELEASE_PREFLIGHT_REPOSITORY_COMMANDS = [
+    "npm ci --ignore-scripts",
+    "npm run lint",
+    "npm run typecheck",
+    "npm run build",
+    "npm run test",
+    "npm run test:pack-install",
+    "npm run check:roadmap",
+    "npm run verify:c95",
+];
+export const RELEASE_PREFLIGHT_REPLAY_COMMANDS = {
+    competitive: [
+        "npm run audit:token-optimizer",
+        'REPLAY_OUTPUT="$(mktemp -t knodin-c67-token-optimizer.XXXXXX.json)" && npm run bench:token-optimizer -- "$REPLAY_OUTPUT"',
+    ],
+    trust: [
+        "npx vitest run src/__tests__/unit/update-trust.spec.ts src/__tests__/unit/update-ceremony.spec.ts",
+    ],
+    defense: [
+        "npx vitest run src/__tests__/unit/update-policy.spec.ts src/__tests__/unit/update-policy-cli.spec.ts",
+    ],
+    attestation: [
+        "npx vitest run src/__tests__/unit/release-attestation.spec.ts src/__tests__/unit/release-attestation-cli.spec.ts src/__tests__/unit/release-workflow.spec.ts src/__tests__/unit/release-candidate-workflow.spec.ts",
+    ],
+};
+const COMMAND_CATEGORIES = [
+    "repository",
+    "competitive",
+    "trust",
+    "defense",
+    "attestation",
+];
+const TARGET_PLATFORMS = ["macOS", "Linux", "Windows"];
+const MAX_MANIFEST_BYTES = 1 * 1_024 * 1_024;
+const MAX_EVIDENCE_BYTES = 16 * 1_024 * 1_024;
+const MAX_TOTAL_EVIDENCE_BYTES = 128 * 1_024 * 1_024;
+const COMMIT = /^(?:[a-f0-9]{40}|[a-f0-9]{64})$/;
+const SHA256 = /^[a-f0-9]{64}$/;
+const SEMVER = /^(?:0|[1-9]\d*)\.(?:0|[1-9]\d*)\.(?:0|[1-9]\d*)(?:-(?:0|[1-9]\d*|[A-Za-z-][0-9A-Za-z-]*)(?:\.(?:0|[1-9]\d*|[A-Za-z-][0-9A-Za-z-]*))*)?(?:\+[0-9A-Za-z-]+(?:\.[0-9A-Za-z-]+)*)?$/;
+const REPOSITORY_PATH = /^[A-Za-z0-9._+/-]+$/;
+const IMMUTABLE_EVIDENCE_PATH = /^(?:docs\/evidence|benchmarks\/evaluations)\//;
+const RUNTIME_NAME = /^[a-z][a-z0-9._-]{0,31}$/;
+const RUNTIME_VERSION = /^[0-9A-Za-z][0-9A-Za-z._+-]{0,63}$/;
+const TERMINAL_STATUS = /^(?:implemented(?: \([^()\n]+\)| — [^\n]+)?|evaluated — [^\n]+|certified(?: with [^\n]+| — [^\n]+)?|closed(?:; [^\n]+| — [^\n]+)?|done(?: — [^\n]+)?)$/;
+function fail(message) {
+    throw new Error(`release preflight failed: ${message}`);
+}
+function record(value, label) {
+    if (value === null || typeof value !== "object" || Array.isArray(value))
+        fail(`${label} must be an object`);
+    return value;
+}
+function exactKeys(value, expected, label) {
+    const keys = Object.keys(value).sort(compareBytes);
+    const wanted = [...expected].sort(compareBytes);
+    if (keys.length !== wanted.length || keys.some((key, index) => key !== wanted[index]))
+        fail(`${label} must contain exactly: ${wanted.join(", ")}`);
+}
+function text(value, label, maximum) {
+    if (typeof value !== "string" || value.length === 0 || value.length > maximum)
+        fail(`${label} must be a non-empty bounded string`);
+    return value;
+}
+function safeRelativePath(value, label) {
+    const candidate = text(value, label, 512);
+    if (path.isAbsolute(candidate) ||
+        candidate.includes("\\") ||
+        candidate.includes("\0") ||
+        !REPOSITORY_PATH.test(candidate) ||
+        candidate.split("/").some((part) => part === "" || part === "." || part === ".."))
+        fail(`${label} must be a normalized repository-relative path`);
+    return candidate;
+}
+function boundedStringArray(value, label, options) {
+    if (!Array.isArray(value) || value.length === 0 || value.length > options.maximumItems)
+        fail(`${label} must be a non-empty bounded array`);
+    const result = value.map((item, index) => text(item, `${label}[${index}]`, options.maximumLength));
+    if (new Set(result).size !== result.length)
+        fail(`${label} must not contain duplicates`);
+    return result;
+}
+function parsePlan(value) {
+    const plan = record(value, "release plan");
+    exactKeys(plan, [
+        "schemaVersion",
+        "version",
+        "tag",
+        "sourceCommit",
+        "workflow",
+        "runtimes",
+        "certifiedTargetPlatforms",
+        "trustRootSha256",
+        "trustRootPath",
+        "trustCeremonyManifestPath",
+        "trustReviewReceiptPath",
+        "verificationCommands",
+        "dependencyEvidence",
+        "evidenceDirectory",
+    ], "release plan");
+    if (plan.schemaVersion !== 1)
+        fail("schemaVersion must be 1");
+    const version = text(plan.version, "version", 128);
+    if (!SEMVER.test(version))
+        fail("version must be semantic");
+    const tag = text(plan.tag, "tag", 129);
+    if (tag !== `v${version}`)
+        fail("tag must equal v followed by package version");
+    const sourceCommit = text(plan.sourceCommit, "source commit", 64);
+    if (!COMMIT.test(sourceCommit))
+        fail("source commit must be a lowercase full commit digest");
+    const workflow = record(plan.workflow, "workflow");
+    exactKeys(workflow, ["path", "commit"], "workflow");
+    const workflowPath = safeRelativePath(workflow.path, "workflow path");
+    if (workflowPath !== ".github/workflows/release-candidate.yml")
+        fail("workflow path must select the C64 nonpublishing candidate workflow");
+    const workflowCommit = text(workflow.commit, "workflow commit", 64);
+    if (!COMMIT.test(workflowCommit))
+        fail("workflow commit must be a lowercase full commit digest");
+    if (workflowCommit !== sourceCommit)
+        fail("workflow commit must equal source commit");
+    if (!Array.isArray(plan.runtimes) || plan.runtimes.length < 2 || plan.runtimes.length > 16)
+        fail("runtimes must contain a bounded runtime set including node and npm");
+    const runtimes = plan.runtimes.map((candidate, index) => {
+        const runtime = record(candidate, `runtimes[${index}]`);
+        exactKeys(runtime, ["name", "version"], `runtimes[${index}]`);
+        const name = text(runtime.name, `runtimes[${index}].name`, 32);
+        const runtimeVersion = text(runtime.version, `runtimes[${index}].version`, 64);
+        if (!RUNTIME_NAME.test(name) || !RUNTIME_VERSION.test(runtimeVersion))
+            fail(`runtimes[${index}] has an invalid name or version`);
+        return { name, version: runtimeVersion };
+    });
+    const runtimeNames = runtimes.map(({ name }) => name);
+    if (new Set(runtimeNames).size !== runtimeNames.length ||
+        !runtimeNames.includes("node") ||
+        !runtimeNames.includes("npm"))
+        fail("runtimes must uniquely include node and npm");
+    const certifiedTargetPlatforms = boundedStringArray(plan.certifiedTargetPlatforms, "certified target platforms", { maximumItems: 3, maximumLength: 16 });
+    if (certifiedTargetPlatforms.length !== TARGET_PLATFORMS.length ||
+        TARGET_PLATFORMS.some((platform) => !certifiedTargetPlatforms.includes(platform)))
+        fail("certified target platforms must contain exactly macOS, Linux, and Windows");
+    const trustRootSha256 = text(plan.trustRootSha256, "trust-root digest", 64);
+    if (!SHA256.test(trustRootSha256))
+        fail("trust-root digest must be a lowercase SHA-256 digest");
+    const trustRootPath = safeRelativePath(plan.trustRootPath, "trust-root path");
+    const trustCeremonyManifestPath = safeRelativePath(plan.trustCeremonyManifestPath, "trust ceremony manifest path");
+    const trustReviewReceiptPath = safeRelativePath(plan.trustReviewReceiptPath, "trust review receipt path");
+    const commandsRecord = record(plan.verificationCommands, "verification commands");
+    exactKeys(commandsRecord, COMMAND_CATEGORIES, "verification commands");
+    const verificationCommands = {};
+    for (const category of COMMAND_CATEGORIES) {
+        verificationCommands[category] = boundedStringArray(commandsRecord[category], `${category} verification commands`, { maximumItems: 32, maximumLength: 512 });
+        for (const command of verificationCommands[category]) {
+            if (/[^\x20-\x7e]/.test(command))
+                fail(`${category} verification commands must be exact single-line printable commands`);
+        }
+    }
+    if (verificationCommands.repository.length !== RELEASE_PREFLIGHT_REPOSITORY_COMMANDS.length ||
+        RELEASE_PREFLIGHT_REPOSITORY_COMMANDS.some((command, index) => verificationCommands.repository[index] !== command))
+        fail("repository verification commands must equal the canonical ordered gate set");
+    for (const category of ["competitive", "trust", "defense", "attestation"]) {
+        const expected = RELEASE_PREFLIGHT_REPLAY_COMMANDS[category];
+        if (verificationCommands[category].length !== expected.length ||
+            expected.some((command, index) => verificationCommands[category][index] !== command))
+            fail(`${category} verification commands must equal the canonical ordered replay set`);
+    }
+    const evidenceRecord = record(plan.dependencyEvidence, "dependency evidence");
+    exactKeys(evidenceRecord, RELEASE_PREFLIGHT_DEPENDENCIES, "dependency evidence");
+    const dependencyEvidence = {};
+    for (const dependency of RELEASE_PREFLIGHT_DEPENDENCIES) {
+        dependencyEvidence[dependency] = boundedStringArray(evidenceRecord[dependency], `${dependency} evidence paths`, { maximumItems: 32, maximumLength: 512 }).map((candidate, index) => safeRelativePath(candidate, `${dependency} evidence paths[${index}]`));
+    }
+    return {
+        schemaVersion: 1,
+        version,
+        tag,
+        sourceCommit,
+        workflow: { path: workflowPath, commit: workflowCommit },
+        runtimes,
+        certifiedTargetPlatforms,
+        trustRootSha256,
+        trustRootPath,
+        trustCeremonyManifestPath,
+        trustReviewReceiptPath,
+        verificationCommands,
+        dependencyEvidence,
+        evidenceDirectory: safeRelativePath(plan.evidenceDirectory, "evidence directory"),
+    };
+}
+function readBoundedRegularFile(repositoryRoot, file, label, maximum) {
+    const lexical = path.resolve(file);
+    let stat;
+    try {
+        stat = fs.lstatSync(lexical);
+    }
+    catch {
+        return fail(`${label} does not exist`);
+    }
+    if (!stat.isFile() || stat.isSymbolicLink())
+        fail(`${label} must be a regular non-symlink file`);
+    let canonical;
+    try {
+        canonical = fs.realpathSync(lexical);
+    }
+    catch {
+        return fail(`${label} cannot be resolved`);
+    }
+    if (canonical === repositoryRoot ||
+        !canonical.startsWith(`${repositoryRoot}${path.sep}`) ||
+        (label !== "release-plan manifest" && canonical !== lexical))
+        fail(`${label} must not traverse a symlink or leave the repository`);
+    const noFollow = "O_NOFOLLOW" in fs.constants ? fs.constants.O_NOFOLLOW : 0;
+    let descriptor;
+    try {
+        descriptor = fs.openSync(lexical, fs.constants.O_RDONLY | noFollow);
+        const opened = fs.fstatSync(descriptor);
+        if (!opened.isFile() || opened.dev !== stat.dev || opened.ino !== stat.ino)
+            fail(`${label} changed while it was being validated`);
+        if (opened.size === 0 || opened.size > maximum)
+            fail(`${label} exceeds its non-empty byte budget`);
+        const bounded = Buffer.allocUnsafe(maximum + 1);
+        let offset = 0;
+        while (offset < bounded.byteLength) {
+            const count = fs.readSync(descriptor, bounded, offset, bounded.byteLength - offset, null);
+            if (count === 0)
+                break;
+            offset += count;
+        }
+        if (offset > maximum)
+            fail(`${label} exceeds its non-empty byte budget`);
+        const after = fs.fstatSync(descriptor);
+        if (after.dev !== opened.dev || after.ino !== opened.ino || after.size !== offset)
+            fail(`${label} changed while it was being read`);
+        const bytes = Buffer.from(bounded.subarray(0, offset));
+        return {
+            bytes,
+            relativePath: path.relative(repositoryRoot, canonical).split(path.sep).join("/"),
+            size: opened.size,
+        };
+    }
+    finally {
+        if (descriptor !== undefined)
+            fs.closeSync(descriptor);
+    }
+}
+function parseJson(bytes, label) {
+    try {
+        return JSON.parse(bytes.toString("utf8"));
+    }
+    catch {
+        return fail(`${label} must be valid JSON`);
+    }
+}
+function defaultGit(repositoryRoot) {
+    const run = (args, allowFailure = false) => {
+        const result = spawnSync("git", args, {
+            cwd: repositoryRoot,
+            encoding: "utf8",
+            timeout: 10_000,
+            maxBuffer: 1 * 1_024 * 1_024,
+            env: {
+                PATH: process.env.PATH,
+                SYSTEMROOT: process.env.SYSTEMROOT,
+                WINDIR: process.env.WINDIR,
+            },
+        });
+        if (result.error)
+            throw result.error;
+        if (!allowFailure && result.status !== 0)
+            fail(`git ${args[0] ?? "command"} failed without mutating the checkout`);
+        return { status: result.status, stdout: result.stdout.trim() };
+    };
+    const runBytes = (args) => {
+        const result = spawnSync("git", args, {
+            cwd: repositoryRoot,
+            timeout: 10_000,
+            maxBuffer: MAX_EVIDENCE_BYTES + 1,
+            env: {
+                PATH: process.env.PATH,
+                SYSTEMROOT: process.env.SYSTEMROOT,
+                WINDIR: process.env.WINDIR,
+            },
+        });
+        if (result.error)
+            throw result.error;
+        if (result.status !== 0 || !Buffer.isBuffer(result.stdout))
+            fail(`git ${args[0] ?? "command"} could not read a source-bound blob`);
+        if (result.stdout.byteLength === 0 || result.stdout.byteLength > MAX_EVIDENCE_BYTES)
+            fail("source-bound Git blob exceeds its non-empty byte budget");
+        return result.stdout;
+    };
+    return {
+        headCommit: () => run(["rev-parse", "HEAD"]).stdout,
+        statusPorcelain: () => run(["status", "--porcelain=v1", "--untracked-files=all"]).stdout,
+        tagObjectType: (tag) => run(["cat-file", "-t", `refs/tags/${tag}`]).stdout,
+        tagCommit: (tag) => run(["rev-parse", `${tag}^{commit}`]).stdout,
+        isTracked: (relativePath) => run(["ls-files", "--error-unmatch", "--", relativePath], true).status === 0,
+        fileAtCommit: (commit, relativePath) => runBytes(["show", `${commit}:${relativePath}`]),
+    };
+}
+function requireTaggedBytes(git, commit, relativePath, bytes, label) {
+    const tagged = git.fileAtCommit(commit, relativePath);
+    if (!tagged.equals(bytes))
+        fail(`${label} bytes do not equal the exact source-commit blob`);
+}
+function verifyRoadmap(roadmap) {
+    const activeLedger = /### Track A — Active local-work ledger\n[\s\S]*?\n\| ID \| State \| Previous state \| Depends on \| Exit evidence \|\n\|---\|---\|---\|---\|---\|\n((?:\| C[^\n]+\n)*)\n### Track B — Parked external-evidence ledger/.exec(roadmap);
+    const parkedLedger = /### Track B — Parked external-evidence ledger\n[\s\S]*?\n\| ID \| State \| Previous state \| Depends on \| Exit evidence \|\n\|---\|---\|---\|---\|---\|\n((?:\| C[^\n]+\n)*)\n### Goal-loop ordering/.exec(roadmap);
+    if (!activeLedger || !parkedLedger)
+        fail("two-track roadmap ledger is missing or malformed");
+    const activeIds = new Set([...activeLedger[1].matchAll(/^\| (C\d+) \|/gm)].map((match) => match[1]));
+    const parkedIds = new Set([...parkedLedger[1].matchAll(/^\| (C\d+) \|/gm)].map((match) => match[1]));
+    if (parkedIds.size > 0)
+        fail(`Track B remains parked (${parkedIds.size} external item${parkedIds.size === 1 ? "" : "s"}: ${[...parkedIds].join(", ")})`);
+    const evidencePaths = new Map();
+    for (const dependency of RELEASE_PREFLIGHT_DEPENDENCIES) {
+        if (activeIds.has(dependency))
+            fail(`${dependency} remains in Track A`);
+        const header = dependency === "C75" ? "C69–C75" : dependency;
+        const section = new RegExp(String.raw `(^#{2,3} ${header} —[^\n]*\n[\s\S]*?)(?=^#{2,3} C(?:\d+|\d+–C\d+) —|(?![\s\S]))`, "m").exec(roadmap);
+        if (!section)
+            fail(`${dependency} has no authoritative item status`);
+        const statusMatch = /^- Status: ([^\n]+)$/m.exec(section[1]);
+        if (!statusMatch)
+            fail(`${dependency} has no authoritative item status`);
+        const status = statusMatch[1].trim();
+        if (!TERMINAL_STATUS.test(status))
+            fail(`${dependency} has nonterminal status ${JSON.stringify(status)}`);
+        const evidenceLabel = dependency === "C75" ? "C75 Evidence" : "Evidence";
+        const evidenceField = new RegExp(String.raw `^- ${evidenceLabel}: ([\s\S]*?)(?=\n\n|\n- [A-Z][^\n]*:|(?![\s\S]))`, "m").exec(section[1]);
+        if (!evidenceField)
+            fail(`${dependency} has no explicit authoritative evidence field`);
+        const paths = [...evidenceField[1].matchAll(/`([^`]+)`/g)].map((match) => match[1]);
+        if (paths.length === 0 || new Set(paths).size !== paths.length)
+            fail(`${dependency} authoritative evidence field must name distinct paths`);
+        if (!paths.some((candidate) => IMMUTABLE_EVIDENCE_PATH.test(candidate)))
+            fail(`${dependency} must declare at least one immutable evidence or evaluation path`);
+        evidencePaths.set(dependency, paths);
+    }
+    return evidencePaths;
+}
+function verifyFreshEvidenceDirectory(repositoryRoot, plan) {
+    const expected = `docs/evidence/releases/${plan.version}`;
+    if (plan.evidenceDirectory !== expected)
+        fail(`evidence directory must be the version-bound path ${expected}`);
+    const parts = plan.evidenceDirectory.split("/");
+    let candidate = repositoryRoot;
+    for (const part of parts) {
+        candidate = path.join(candidate, part);
+        let stat;
+        try {
+            stat = fs.lstatSync(candidate);
+        }
+        catch (error) {
+            if (error.code === "ENOENT")
+                continue;
+            throw error;
+        }
+        if (stat.isSymbolicLink())
+            fail("evidence directory must not traverse a symlink");
+        if (candidate !== path.join(repositoryRoot, plan.evidenceDirectory) && !stat.isDirectory())
+            fail("every existing evidence-directory prefix must be a directory");
+        if (candidate === path.join(repositoryRoot, plan.evidenceDirectory))
+            fail("evidence directory already exists and must not be overwritten");
+    }
+}
+function verifyProductionTrust(plan, evidence) {
+    const paths = [plan.trustRootPath, plan.trustCeremonyManifestPath, plan.trustReviewReceiptPath];
+    if (new Set(paths).size !== paths.length ||
+        paths.some((candidate) => !plan.dependencyEvidence.C62.includes(candidate)))
+        fail("production trust artifacts must be three distinct C62 dependency-evidence paths");
+    const rootBytes = evidence.get(plan.trustRootPath);
+    const manifestBytes = evidence.get(plan.trustCeremonyManifestPath);
+    const receiptBytes = evidence.get(plan.trustReviewReceiptPath);
+    if (!rootBytes || !manifestBytes || !receiptBytes)
+        fail("production trust artifacts were not retained in the validated evidence set");
+    const manifest = validateRootCeremonyManifest(parseJson(manifestBytes, "production root ceremony manifest"));
+    if (manifest.purpose !== "production")
+        fail("trust ceremony manifest must record a production ceremony");
+    const rootEnvelope = parseJson(rootBytes, "production root envelope");
+    let digest;
+    try {
+        for (const role of ["root", "targets", "snapshot", "timestamp"]) {
+            const rootRole = rootEnvelope.signed.roles[role];
+            if (rootRole.threshold !== manifest.thresholds[role] ||
+                [...rootRole.keyids].sort(compareBytes).join("\0") !==
+                    [...manifest.roleKeyIds[role]].sort(compareBytes).join("\0"))
+                fail(`production ceremony ${role} role does not match the signed root`);
+        }
+        for (const key of Object.values(rootEnvelope.signed.keys)) {
+            const canonical = createPublicKey(key.keyval.public)
+                .export({ type: "spki", format: "pem" })
+                .toString();
+            if (canonical !== key.keyval.public)
+                fail("production root keys must use canonical public SPKI PEM only");
+        }
+        digest = createHash("sha256").update(canonicalizeUpdateMetadata(rootEnvelope)).digest("hex");
+        verifyUpdateRootChain(rootEnvelope, digest, []);
+    }
+    catch (error) {
+        fail(`production trust root must be a valid self-threshold-signed root envelope: ${error instanceof Error ? error.message : "invalid root"}`);
+    }
+    if (digest !== plan.trustRootSha256)
+        fail("trust-root digest does not match the canonical C62 root envelope");
+    const receipt = record(parseJson(receiptBytes, "production root review receipt"), "production root review receipt");
+    exactKeys(receipt, [
+        "schemaVersion",
+        "ceremonyId",
+        "rootEnvelopeSha256",
+        "reviewerId",
+        "reviewedAt",
+        "decision",
+        "authentication",
+        "productionActivation",
+    ], "production root review receipt");
+    const reviewedAt = text(receipt.reviewedAt, "production root review time", 64);
+    const reviewedTime = new Date(reviewedAt);
+    if (receipt.schemaVersion !== 1 ||
+        receipt.ceremonyId !== manifest.ceremonyId ||
+        receipt.rootEnvelopeSha256 !== digest ||
+        typeof receipt.reviewerId !== "string" ||
+        manifest.custodians.some(({ id }) => id === receipt.reviewerId) ||
+        receipt.decision !== "approved" ||
+        receipt.authentication !== "externally-authenticated" ||
+        receipt.productionActivation !== false ||
+        !Number.isFinite(reviewedTime.getTime()) ||
+        reviewedTime.toISOString() !== reviewedAt ||
+        reviewedTime.getTime() > Date.now())
+        fail("production root review receipt is not independent, authenticated, and digest-bound");
+}
+export function evaluateReleasePreflight(options) {
+    const repositoryRoot = fs.realpathSync(options.repositoryRoot);
+    const manifestFile = readBoundedRegularFile(repositoryRoot, path.resolve(options.planPath), "release-plan manifest", MAX_MANIFEST_BYTES);
+    const plan = parsePlan(parseJson(manifestFile.bytes, "release-plan manifest"));
+    const git = options.git ?? defaultGit(repositoryRoot);
+    if (git.statusPorcelain() !== "")
+        fail("checkout must be clean before release mutation");
+    if (git.headCommit() !== plan.sourceCommit)
+        fail("checkout HEAD does not equal source commit");
+    if (git.tagObjectType(plan.tag) !== "tag")
+        fail("release tag must be an annotated tag object");
+    if (git.tagCommit(plan.tag) !== plan.sourceCommit)
+        fail("release tag does not resolve to the source commit");
+    const packageFile = readBoundedRegularFile(repositoryRoot, path.join(repositoryRoot, "package.json"), "package manifest", MAX_MANIFEST_BYTES);
+    if (!git.isTracked(packageFile.relativePath))
+        fail("package manifest must be checked in");
+    requireTaggedBytes(git, plan.sourceCommit, packageFile.relativePath, packageFile.bytes, "package manifest");
+    const packageManifest = record(parseJson(packageFile.bytes, "package manifest"), "package manifest");
+    if (packageManifest.version !== plan.version)
+        fail("package version does not equal release-plan version");
+    const workflowFile = readBoundedRegularFile(repositoryRoot, path.join(repositoryRoot, plan.workflow.path), "C64 candidate workflow", MAX_MANIFEST_BYTES);
+    if (!git.isTracked(workflowFile.relativePath))
+        fail("C64 candidate workflow must be checked in");
+    requireTaggedBytes(git, plan.sourceCommit, workflowFile.relativePath, workflowFile.bytes, "C64 candidate workflow");
+    const roadmapFile = readBoundedRegularFile(repositoryRoot, path.join(repositoryRoot, "roadmap/competitive-roadmap.md"), "authoritative roadmap", MAX_EVIDENCE_BYTES);
+    if (!git.isTracked(roadmapFile.relativePath))
+        fail("authoritative roadmap must be checked in");
+    requireTaggedBytes(git, plan.sourceCommit, roadmapFile.relativePath, roadmapFile.bytes, "authoritative roadmap");
+    const roadmapEvidence = verifyRoadmap(roadmapFile.bytes.toString("utf8"));
+    let totalEvidenceBytes = 0;
+    const uniquePaths = new Set();
+    const evidenceBytes = new Map();
+    for (const dependency of RELEASE_PREFLIGHT_DEPENDENCIES) {
+        const declared = plan.dependencyEvidence[dependency];
+        const authoritative = roadmapEvidence.get(dependency) ?? [];
+        if (declared.length !== authoritative.length ||
+            [...declared]
+                .sort(compareBytes)
+                .some((candidate, index) => candidate !== [...authoritative].sort(compareBytes)[index]))
+            fail(`${dependency} evidence paths must equal its complete authoritative Evidence field`);
+        for (const relativePath of plan.dependencyEvidence[dependency]) {
+            if (uniquePaths.has(relativePath))
+                fail(`evidence path is declared more than once: ${relativePath}`);
+            uniquePaths.add(relativePath);
+            const evidence = readBoundedRegularFile(repositoryRoot, path.join(repositoryRoot, relativePath), `${dependency} evidence ${relativePath}`, MAX_EVIDENCE_BYTES);
+            if (evidence.relativePath !== relativePath)
+                fail(`${dependency} evidence path must be normalized`);
+            if (!git.isTracked(relativePath))
+                fail(`${dependency} evidence must be checked in: ${relativePath}`);
+            requireTaggedBytes(git, plan.sourceCommit, relativePath, evidence.bytes, `${dependency} evidence ${relativePath}`);
+            evidenceBytes.set(relativePath, evidence.bytes);
+            totalEvidenceBytes += evidence.size;
+            if (totalEvidenceBytes > MAX_TOTAL_EVIDENCE_BYTES)
+                fail("dependency evidence exceeds the aggregate byte budget");
+        }
+    }
+    verifyProductionTrust(plan, evidenceBytes);
+    verifyFreshEvidenceDirectory(repositoryRoot, plan);
+    return {
+        ok: true,
+        version: plan.version,
+        tag: plan.tag,
+        sourceCommit: plan.sourceCommit,
+        workflowCommit: plan.workflow.commit,
+        evidenceDirectory: plan.evidenceDirectory,
+        dependencies: [...RELEASE_PREFLIGHT_DEPENDENCIES],
+    };
+}

package/dist/src/repair-lease.js

@@ -0,0 +1,85 @@
+import crypto from "node:crypto";
+import fs from "node:fs";
+import path from "node:path";
+const MAX_LEASE_BYTES = 4_096;
+function leasePath(repo) {
+    return path.join(path.resolve(repo), ".knodin", "repair.lock");
+}
+function processIsAlive(pid) {
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+function readLease(target) {
+    try {
+        const stat = fs.statSync(target);
+        if (!stat.isFile() || stat.size <= 0 || stat.size > MAX_LEASE_BYTES)
+            return null;
+        const value = JSON.parse(fs.readFileSync(target, "utf8"));
+        if (value.schemaVersion !== 1 ||
+            !Number.isInteger(value.pid) ||
+            (value.pid ?? 0) <= 0 ||
+            typeof value.startedAt !== "string" ||
+            !Number.isFinite(Date.parse(value.startedAt)) ||
+            typeof value.nonce !== "string" ||
+            !value.nonce)
+            return null;
+        return value;
+    }
+    catch {
+        return null;
+    }
+}
+function writeLease(target, record) {
+    fs.writeFileSync(target, `${JSON.stringify(record)}\n`, {
+        encoding: "utf8",
+        flag: "wx",
+        mode: 0o600,
+    });
+}
+function removeStaleLeaseOrThrow(target) {
+    const current = readLease(target);
+    if (current && processIsAlive(current.pid)) {
+        throw new Error(`knodin repair: another repair is already in progress (pid ${current.pid}, started ${current.startedAt}); wait for it to finish, then run \`knodin status\``);
+    }
+    try {
+        fs.unlinkSync(target);
+    }
+    catch (error) {
+        if (error.code !== "ENOENT")
+            throw error;
+    }
+}
+/** Atomically serialize repair post-processing across independent CLI/MCP processes. */
+export function acquireRepairLease(repo) {
+    const target = leasePath(repo);
+    fs.mkdirSync(path.dirname(target), { recursive: true });
+    const record = {
+        schemaVersion: 1,
+        pid: process.pid,
+        startedAt: new Date().toISOString(),
+        nonce: crypto.randomUUID(),
+    };
+    for (let attempt = 0; attempt < 2; attempt += 1) {
+        try {
+            writeLease(target, record);
+            return {
+                release() {
+                    const current = readLease(target);
+                    if (current?.nonce === record.nonce)
+                        fs.rmSync(target, { force: true });
+                },
+            };
+        }
+        catch (error) {
+            if (error.code !== "EEXIST")
+                throw error;
+            removeStaleLeaseOrThrow(target);
+        }
+    }
+    throw new Error("knodin repair: could not acquire the repository repair lease; retry shortly");
+}