@astrosheep/keiyaku 2.9.3 → 2.9.5

package/build/core/audit.js

@@ -0,0 +1,650 @@
+import * as fs from "node:fs/promises";
+import * as os from "node:os";
+import * as path from "node:path";
+import { createHash } from "node:crypto";
+import { Buffer } from "node:buffer";
+import { FlowError, asMessage } from "../flow-error.js";
+import { createGit, wrapGitError } from "../git/core.js";
+import { readStructuredDiff } from "../git/diff/structured.js";
+import { readLedger } from "./ledger.js";
+import { hasStrandableProjectionGeneration } from "./projection/index.js";
+import { readRenewRecoverySession } from "./renew-session.js";
+import { rewriteRenewBranch } from "./renew.js";
+import { effectiveScope, findOpenArc, getFence, getMaxArc, receiptsAfterFence } from "./seal.js";
+import { queueMembership, readQueueReadModel } from "./settlement/queue.js";
+import { resolveVerificationCommands, runVerificationCommand, verificationExecutor, } from "./settlement/verification.js";
+import { markdownSourceSections, scopePathEvidence } from "./scope.js";
+import { normalizeSectionTitle } from "./markdown/titles.js";
+import { commissionTarget, latestBase } from "./status/drift.js";
+import { deriveContractState, isTerminalState } from "./status/lifecycle.js";
+import { resolveContractDeliveryCwd } from "./worktree-path.js";
+import { KEIYAKU_FILE } from "../keiyaku.js";
+async function resolveObject(cwd, revision, kind) {
+    const git = createGit(cwd);
+    try {
+        return (await git.raw(["rev-parse", "--verify", `${revision}^{${kind}}`])).trim();
+    }
+    catch (error) {
+        throw wrapGitError(`rev-parse ${revision}^{${kind}}`, error, cwd);
+    }
+}
+async function pinCoordinates(input) {
+    const ledger = await readLedger(input.cwd, input.contractId);
+    if (!ledger)
+        throw new FlowError("INTERNAL_STATE", `contract ${input.contractId} not found or not active`);
+    const bind = ledger.entries.find((entry) => entry.kind === "bind");
+    const target = commissionTarget(ledger.entries);
+    const base = latestBase(ledger.entries);
+    if (!bind || !target || !base)
+        throw new FlowError("INTERNAL_STATE", `contract ${input.contractId} is missing pinned audit coordinates`);
+    const [deliveryHead, deliveryTree, targetHead, targetTree] = await Promise.all([
+        resolveObject(input.cwd, input.deliveryRef, "commit"),
+        resolveObject(input.cwd, input.deliveryRef, "tree"),
+        resolveObject(input.cwd, target.ref, "commit"),
+        resolveObject(input.cwd, target.ref, "tree"),
+    ]);
+    return {
+        criteria: effectiveCriteria(ledger.entries),
+        base,
+        entries: ledger.entries,
+        coordinates: {
+            ledger: { head: ledger.head },
+            delivery: { ref: input.deliveryRef, head: deliveryHead, tree: deliveryTree },
+            target: { ref: target.ref, head: targetHead, tree: targetTree },
+        },
+    };
+}
+async function createCandidate(sourceRoot, pinned, contractId) {
+    const cwd = await fs.mkdtemp(path.join(os.tmpdir(), "keiyaku-audit-"));
+    const git = createGit(sourceRoot);
+    try {
+        await git.raw(["clone", "--quiet", "--no-hardlinks", "--no-checkout", sourceRoot, cwd]);
+        const candidateGit = createGit(cwd);
+        await candidateGit.raw(["config", "user.name", "Keiyaku Audit"]);
+        await candidateGit.raw(["config", "user.email", "audit@keiyaku.invalid"]);
+        await candidateGit.raw(["checkout", "--quiet", "-B", `keiyaku/${contractId}`, pinned.coordinates.delivery.head]);
+        if (pinned.base === pinned.coordinates.target.head) {
+            return {
+                cwd,
+                rehearsal: { status: "fresh" },
+                candidate: {
+                    base: pinned.coordinates.target.head,
+                    head: pinned.coordinates.delivery.head,
+                    tree: pinned.coordinates.delivery.tree,
+                    rewritten: false,
+                },
+            };
+        }
+        try {
+            await rewriteRenewBranch({
+                cwd,
+                contractId,
+                oldHead: pinned.coordinates.delivery.head,
+                recoveryRef: "refs/keiyaku/audit/disposable",
+                newBase: pinned.coordinates.target.head,
+                oldBase: pinned.base,
+            });
+        }
+        catch (error) {
+            if (error instanceof FlowError && error.code === "CLOSE_MERGE_CONFLICT" && error.facts?.kind === "renew_conflict") {
+                return {
+                    cwd,
+                    rehearsal: {
+                        status: "conflict",
+                        paths: [...error.facts.conflictPaths],
+                        pathCapture: error.facts.conflictPathCapture.status === "captured" ? "captured" : "failed",
+                        ...(error.facts.conflictPathCapture.status === "failed" ? { diagnostic: error.facts.conflictPathCapture.diagnostic } : {}),
+                    },
+                    candidate: null,
+                };
+            }
+            return { cwd, rehearsal: { status: "unknown", cause: { code: error instanceof FlowError ? error.code : "INTERNAL_STATE", message: asMessage(error) } }, candidate: null };
+        }
+        const [head, tree] = await Promise.all([resolveObject(cwd, "HEAD", "commit"), resolveObject(cwd, "HEAD", "tree")]);
+        return {
+            cwd,
+            rehearsal: { status: "clean", oldBase: pinned.base, newBase: pinned.coordinates.target.head, oldHead: pinned.coordinates.delivery.head },
+            candidate: { base: pinned.coordinates.target.head, head, tree, rewritten: true },
+        };
+    }
+    catch (error) {
+        return { cwd, rehearsal: { status: "unknown", cause: { code: error instanceof FlowError ? error.code : "INTERNAL_STATE", message: asMessage(error) } }, candidate: null };
+    }
+}
+function importLine(line) {
+    const text = line.content.trim();
+    return /^(?:import\b|export\s+(?:\*|\{)|(?:const|let|var)\s+[^=]+\s*=\s*require\s*\(|[^=]+\brequire\s*\(|[^=]+\bimport\s*\()/.test(text);
+}
+function identifierRename(before, after) {
+    const left = before.match(/[A-Za-z_$][\w$]*/g) ?? [];
+    const right = after.match(/[A-Za-z_$][\w$]*/g) ?? [];
+    if (left.length !== right.length)
+        return null;
+    const differences = left.flatMap((value, index) => value === right[index] ? [] : [{ from: value, to: right[index] }]);
+    if (differences.length !== 1)
+        return null;
+    const rename = differences[0];
+    const expression = new RegExp(`\\b${rename.from.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")}\\b`, "g");
+    return before.replace(expression, rename.to) === after ? rename : null;
+}
+function explainFile(file, matcher) {
+    const explanations = [];
+    const explained = new Set();
+    if (file.status === "R" && file.oldPath) {
+        explanations.push({ kind: "file-rename", from: file.oldPath, to: file.path, similarity: file.similarity ?? 0 });
+    }
+    for (const hunk of file.hunks) {
+        const changed = hunk.lines.filter((line) => line.kind !== "context");
+        for (const line of changed) {
+            if (!importLine(line))
+                continue;
+            explanations.push({ kind: "import", hunk: hunk.index, oldLine: line.oldLine, newLine: line.newLine });
+            explained.add(`${hunk.index}:${line.kind}:${line.oldLine}:${line.newLine}`);
+        }
+        const deletions = changed.filter((line) => line.kind === "deletion" && !importLine(line));
+        const additions = changed.filter((line) => line.kind === "addition" && !importLine(line));
+        if (deletions.length === additions.length) {
+            deletions.forEach((deletion, index) => {
+                const addition = additions[index];
+                const rename = identifierRename(deletion.content, addition.content);
+                if (!rename)
+                    return;
+                explanations.push({ kind: "symbol-rename", ...rename, hunk: hunk.index, oldLine: deletion.oldLine, newLine: addition.newLine });
+                explained.add(`${hunk.index}:${deletion.kind}:${deletion.oldLine}:${deletion.newLine}`);
+                explained.add(`${hunk.index}:${addition.kind}:${addition.oldLine}:${addition.newLine}`);
+            });
+        }
+    }
+    const residue = file.binary ? [{ hunk: -1, oldLine: null, newLine: null, kind: "binary", content: "binary content changed" }] : [];
+    for (const hunk of file.hunks) {
+        for (const line of hunk.lines) {
+            if (line.kind === "context")
+                continue;
+            const key = `${hunk.index}:${line.kind}:${line.oldLine}:${line.newLine}`;
+            if (!explained.has(key))
+                residue.push({ hunk: hunk.index, oldLine: line.oldLine, newLine: line.newLine, kind: line.kind, content: line.content });
+        }
+    }
+    const klass = matcher.matched ? "in-scope" : residue.length === 0 && explanations.length > 0 ? "downgraded" : "violated";
+    return { path: file.path, ...(file.oldPath ? { oldPath: file.oldPath } : {}), matcher, explanations, residue, class: klass };
+}
+async function evaluateScope(cwd, entries, diff) {
+    const matchers = await scopePathEvidence(cwd, effectiveScope(entries), diff.files.map((file) => file.path));
+    return diff.files.map((file, index) => explainFile(file, matchers[index]));
+}
+function rawHunk(file, hunk) {
+    const lines = [
+        `${file.status} ${file.oldPath ? `${file.oldPath} -> ` : ""}${file.path} · +${file.insertions} -${file.deletions}`,
+        hunk.header,
+        ...hunk.lines.map((line) => `${line.kind === "addition" ? "+" : line.kind === "deletion" ? "-" : " "}${line.content}`),
+    ];
+    return lines.join("\n");
+}
+function rawFile(file) {
+    return `${file.status} ${file.oldPath ? `${file.oldPath} -> ` : ""}${file.path} · +${file.insertions} -${file.deletions}`;
+}
+function moduleFor(pathname) {
+    const segments = pathname.split("/");
+    return segments.length > 1 ? segments.slice(0, -1).join("/") : ".";
+}
+function isAuthorityBoundary(pathname) {
+    return /(^|\/)(auth(?:entication|orization)?|schema|schemas|migrations?|api|config|ci|\.github|permissions?|concurrency)(\/|$)|(^|\/)(package|tsconfig|vite|webpack|eslint|prettier)\.(json|ya?ml|[cm]?[jt]s)$/.test(pathname);
+}
+function isGeneratedOrLowPriority(pathname, file) {
+    return file.binary || /(^|\/)(vendor|generated|dist|build)(\/|$)|(^|\/)([^/]+\.)?(lock|min)\.(json|ya?ml|js|css)$|(?:^|\/)(package-lock\.json|pnpm-lock\.yaml|yarn\.lock)$/.test(pathname);
+}
+function isSource(pathname) {
+    return /\.(?:[cm]?[jt]sx?|py|go|rs|java|kt|rb|php|cs|swift)$/.test(pathname) && !/(^|\/)(test|tests|__tests__|spec)(\/|\.)/.test(pathname);
+}
+function hasRelatedTest(file, all) {
+    const stem = file.path.replace(/\.[^.]+$/, "").replace(/\/index$/, "");
+    return all.some((candidate) => candidate.path !== file.path && /(test|tests|__tests__|spec)/.test(candidate.path) && candidate.path.replace(/\.(?:[cm]?[jt]sx?|py|go|rs|java|kt|rb|php|cs|swift)$/, "").includes(stem.split("/").at(-1) ?? ""));
+}
+function portfolioTier(file, scope, all) {
+    if (scope.class === "violated")
+        return { tier: 0, mandatory: true };
+    if (isAuthorityBoundary(file.path))
+        return { tier: 1, mandatory: true };
+    if (/(^|\/)(package\.json|workspace|pnpm-workspace|turbo|nx)\b/.test(file.path))
+        return { tier: 2, mandatory: false };
+    if (isGeneratedOrLowPriority(file.path, file))
+        return { tier: 6, mandatory: false };
+    if (isSource(file.path) && !hasRelatedTest(file, all))
+        return { tier: 3, mandatory: false };
+    if (file.status === "R" || scope.class === "downgraded")
+        return { tier: 5, mandatory: false };
+    return { tier: 4, mandatory: false };
+}
+function stablePortfolioOrder(left, right) {
+    if (left.tier !== right.tier)
+        return left.tier - right.tier;
+    const leftValue = 1000 - left.tier * 100;
+    const rightValue = 1000 - right.tier * 100;
+    const ratio = rightValue / Math.max(right.bytes, 1) - leftValue / Math.max(left.bytes, 1);
+    if (ratio !== 0)
+        return ratio;
+    return left.path.localeCompare(right.path) || (left.hunk ?? -1) - (right.hunk ?? -1);
+}
+async function writeDiffArtifact(input) {
+    const body = JSON.stringify({ version: 1, base: input.base, deliveryHead: input.deliveryHead, targetHead: input.targetHead, diff: input.diff });
+    const digest = createHash("sha256").update(body).digest("hex");
+    const directory = path.join(os.tmpdir(), "keiyaku-audit-artifacts");
+    const artifact = path.join(directory, `${digest}.json`);
+    await fs.mkdir(directory, { recursive: true });
+    try {
+        await fs.writeFile(artifact, body, { encoding: "utf8", flag: "wx", mode: 0o444 });
+    }
+    catch (error) {
+        if (error.code !== "EEXIST")
+            throw error;
+    }
+    return artifact;
+}
+function retrieval(artifact, pathname, hunk) {
+    return { kind: "immutable-artifact", artifact, argv: ["cat", artifact], path: pathname, hunk };
+}
+function presentDiff(diff, scope, budget, artifact) {
+    const candidates = [];
+    for (let fileIndex = 0; fileIndex < diff.files.length; fileIndex += 1) {
+        const file = diff.files[fileIndex];
+        const row = scope[fileIndex];
+        const policy = portfolioTier(file, row, diff.files);
+        const chunks = file.hunks.length === 0
+            ? [{ hunk: null, content: rawFile(file) }]
+            : file.hunks.map((hunk) => ({ hunk: hunk.index, content: rawHunk(file, hunk) }));
+        for (const chunk of chunks) {
+            const bytes = Buffer.byteLength(chunk.content);
+            candidates.push({ path: file.path, hunk: chunk.hunk, content: chunk.content, bytes, cost: bytes + 1, tier: policy.tier, mandatory: policy.mandatory, module: moduleFor(file.path) });
+        }
+    }
+    const selected = [];
+    const selectedKeys = new Set();
+    let used = 0;
+    const take = (candidate) => {
+        const key = `${candidate.path}\0${candidate.hunk ?? "file"}`;
+        if (selectedKeys.has(key))
+            return;
+        selectedKeys.add(key);
+        selected.push(candidate);
+        used += candidate.cost;
+    };
+    for (const candidate of [...candidates].filter((item) => item.mandatory).sort(stablePortfolioOrder)) {
+        if (used + candidate.cost <= budget)
+            take(candidate);
+    }
+    const modules = [...new Set(candidates.map((candidate) => candidate.module))].sort();
+    for (const module of modules) {
+        const representative = candidates.filter((candidate) => candidate.module === module && !selectedKeys.has(`${candidate.path}\0${candidate.hunk ?? "file"}`)).sort(stablePortfolioOrder)[0];
+        if (representative && used + representative.cost <= budget)
+            take(representative);
+    }
+    for (const candidate of [...candidates].sort(stablePortfolioOrder)) {
+        if (selectedKeys.has(`${candidate.path}\0${candidate.hunk ?? "file"}`))
+            continue;
+        if (used + candidate.cost <= budget)
+            take(candidate);
+    }
+    const omissions = candidates
+        .filter((candidate) => !selectedKeys.has(`${candidate.path}\0${candidate.hunk ?? "file"}`))
+        .sort((left, right) => left.path.localeCompare(right.path) || (left.hunk ?? -1) - (right.hunk ?? -1))
+        .map((candidate) => ({
+        path: candidate.path,
+        hunk: candidate.hunk,
+        bytes: candidate.bytes,
+        reason: candidate.hunk === null && candidate.content === rawFile(diff.files.find((file) => file.path === candidate.path)) ? "no-raw-hunks" : used + candidate.cost > budget ? "budget" : "not-selected",
+        retrieval: retrieval(artifact, candidate.path, candidate.hunk),
+    }));
+    return { budget: { limit: budget, used }, selected: selected.sort((left, right) => left.path.localeCompare(right.path) || (left.hunk ?? -1) - (right.hunk ?? -1)), omissions };
+}
+function fileFacts(diff, scope) {
+    return diff.files.map((file, index) => {
+        const row = scope[index];
+        return {
+            path: file.path,
+            ...(file.oldPath ? { oldPath: file.oldPath } : {}),
+            status: file.status,
+            stats: { insertions: file.insertions, deletions: file.deletions, binary: file.binary },
+            matcher: row.matcher,
+            explanations: row.explanations,
+            residue: row.residue,
+            class: row.class,
+        };
+    });
+}
+function appendedScopeTerms(entries) {
+    return entries.flatMap((entry) => entry.kind === "amend" && entry.data.scopeDelta ? entry.data.scopeDelta.add : []);
+}
+function effectiveCriteria(entries) {
+    const bind = entries.find((entry) => entry.kind === "bind");
+    if (!bind)
+        return [];
+    const criteria = [...bind.data.checks];
+    for (const entry of entries) {
+        if (entry.kind !== "amend")
+            continue;
+        for (const section of markdownSourceSections(entry.data.amendment)) {
+            if (section.level !== 2 || normalizeSectionTitle(section.title) !== "checks")
+                continue;
+            const content = entry.data.amendment.slice(section.contentStart, section.end);
+            for (const line of content.split(/\r?\n/)) {
+                const match = line.match(/^\s*-\s+(.+)$/);
+                if (match)
+                    criteria.push(match[1].trim());
+            }
+        }
+    }
+    return criteria;
+}
+async function evaluateVerification(cwd, head) {
+    let commands;
+    try {
+        commands = await resolveVerificationCommands(cwd);
+    }
+    catch (error) {
+        return { status: "unknown", cause: { code: error instanceof FlowError ? error.code : "INTERNAL_STATE", message: asMessage(error) }, results: [] };
+    }
+    if (commands.length === 0)
+        return { status: "not_configured", results: [] };
+    const results = [];
+    for (const command of commands) {
+        const argv = [command.command, ...command.args];
+        const known = verificationExecutor(command);
+        if ("cause" in known) {
+            results.push({ status: "unverifiable", label: command.label, command: command.command, argv, head, cause: known.cause });
+            continue;
+        }
+        let execution;
+        try {
+            execution = await runVerificationCommand(cwd, command);
+        }
+        catch (error) {
+            return { status: "unknown", cause: { code: error instanceof FlowError ? error.code : "INTERNAL_STATE", message: asMessage(error) }, results: [] };
+        }
+        results.push({ status: "executed", label: command.label, executor: known.executor, body: known.body, command: command.command, argv, head, exitCode: execution.code, durationMs: execution.durationMs, stdout: execution.stdout, stderr: execution.stderr });
+    }
+    return { status: "evaluated", results };
+}
+async function deliveryResidue(cwd) {
+    const git = createGit(cwd);
+    const fields = (await git.raw(["status", "--porcelain=v1", "-z", "--untracked-files=all"])).split("\0");
+    const staged = new Set();
+    const unstaged = new Set();
+    const untracked = new Set();
+    for (let index = 0; index < fields.length; index += 1) {
+        const field = fields[index];
+        if (!field)
+            continue;
+        const xy = field.slice(0, 2);
+        const filePath = field.slice(3);
+        if (filePath === KEIYAKU_FILE || filePath.startsWith(".keiyaku/recovery/")) {
+            if (xy[0] === "R" || xy[0] === "C")
+                index += 1;
+            continue;
+        }
+        if (xy === "??")
+            untracked.add(filePath);
+        else {
+            if (xy[0] !== " ")
+                staged.add(filePath);
+            if (xy[1] !== " ")
+                unstaged.add(filePath);
+            if (xy[0] === "R" || xy[0] === "C")
+                index += 1;
+        }
+    }
+    const tracked = new Set([...staged, ...unstaged]);
+    return { tracked: [...tracked], staged: [...staged], unstaged: [...unstaged], untracked: [...untracked] };
+}
+async function deliveryCoordinate(cwd) {
+    const [head, tree, residue] = await Promise.all([
+        resolveObject(cwd, "HEAD", "commit"),
+        resolveObject(cwd, "HEAD", "tree"),
+        deliveryResidue(cwd),
+    ]);
+    return { head, tree, residue, residueFingerprint: await residueFingerprint(cwd, residue) };
+}
+function residueKey(residue) {
+    return JSON.stringify({
+        tracked: [...residue.tracked].sort(),
+        staged: [...residue.staged].sort(),
+        unstaged: [...residue.unstaged].sort(),
+        untracked: [...residue.untracked].sort(),
+    });
+}
+async function residueFingerprint(cwd, residue) {
+    const git = createGit(cwd);
+    const digest = createHash("sha256").update(residueKey(residue));
+    const tracked = [...residue.tracked].sort();
+    if (tracked.length > 0) {
+        digest.update(await git.raw(["diff", "--no-color", "--no-ext-diff", "--binary", "HEAD", "--", ...tracked]));
+    }
+    for (const pathname of [...residue.untracked].sort()) {
+        const absolute = path.join(cwd, pathname);
+        const stat = await fs.lstat(absolute);
+        digest.update(pathname).update("\0").update(String(stat.mode)).update("\0");
+        if (stat.isSymbolicLink())
+            digest.update(await fs.readlink(absolute));
+        else
+            digest.update(await fs.readFile(absolute));
+        digest.update("\0");
+    }
+    return digest.digest("hex");
+}
+async function evaluateReadiness(input) {
+    const bind = input.pinned.entries.find((entry) => entry.kind === "bind");
+    const lifecycle = deriveContractState(input.pinned.entries);
+    const [residue, looseCommits, session, queue, liveProjection, dependencies] = await Promise.all([
+        deliveryResidue(input.deliveryCwd),
+        receiptsAfterFence(input.root, input.pinned.entries, input.pinned.coordinates.delivery.head),
+        readRenewRecoverySession(input.root, input.contractId),
+        readQueueReadModel(input.root),
+        hasStrandableProjectionGeneration({ cwd: input.root, commissionId: input.contractId, deliveryWorktree: input.deliveryCwd, nowMs: Date.now() }),
+        Promise.all((bind.data.after ?? []).map(async (id) => {
+            const ledger = await readLedger(input.root, id);
+            const state = ledger ? deriveContractState(ledger.entries) : { state: "missing" };
+            return { id, satisfied: ledger !== null && isTerminalState(state), state: state.state };
+        })),
+    ]);
+    const membership = queueMembership(queue, input.contractId);
+    return {
+        deliveryResidue: residue,
+        arc: { open: findOpenArc(input.pinned.entries)?.data.arc ?? (getMaxArc(input.pinned.entries) === 0 ? 0 : null), max: getMaxArc(input.pinned.entries), fence: getFence(input.pinned.entries), looseCommits },
+        renewSession: { open: session !== null },
+        rewriteGuard: { liveProjection },
+        dependencies,
+        petition: {
+            state: lifecycle.state,
+            queue: membership ? { position: membership.position, length: membership.queueLength, head: membership.queueHead, diagnostics: membership.diagnostics.map((item) => item.kind) } : null,
+        },
+    };
+}
+function coordinateChanges(before, after) {
+    const changes = [];
+    if (before.ledger.head !== after.ledger.head)
+        changes.push(`ledger ${before.ledger.head} -> ${after.ledger.head}`);
+    if (before.delivery.head !== after.delivery.head || before.delivery.tree !== after.delivery.tree)
+        changes.push(`delivery ${before.delivery.head}/${before.delivery.tree} -> ${after.delivery.head}/${after.delivery.tree}`);
+    if (before.target.head !== after.target.head || before.target.tree !== after.target.tree)
+        changes.push(`target ${before.target.head}/${before.target.tree} -> ${after.target.head}/${after.target.tree}`);
+    return changes;
+}
+function quote(value) {
+    return `'${value.replace(/'/g, `'"'"'`)}'`;
+}
+function collectFindings(input) {
+    const findings = [];
+    const selector = `keiyaku @${input.contractId}`;
+    if (input.rehearsal.status === "clean")
+        findings.push({ code: "BASE_DRIFT", detail: "delivery is stale; disposable renew rehearsal was clean", nextCommand: `${selector} renew` });
+    if (input.rehearsal.status === "conflict")
+        findings.push({ code: "RENEW_CONFLICT", detail: `renew rehearsal conflicts at ${input.rehearsal.paths.join(", ") || "unknown paths"}`, nextCommand: `${selector} renew --resolve` });
+    if (input.rehearsal.status === "unknown")
+        findings.push({ code: "RENEW_UNKNOWN", detail: input.rehearsal.cause.message, nextCommand: `${selector} audit` });
+    const violated = input.scope?.filter((row) => row.class === "violated") ?? [];
+    if (violated.length > 0)
+        findings.push({ code: "SCOPE_RESIDUE", detail: `${violated.length} changed paths contain unexplained out-of-scope residue`, nextCommand: `${selector} renew --append-scope ${quote(violated[0].path)}` });
+    if (input.verification.status === "evaluated") {
+        for (const result of input.verification.results) {
+            if (result.status === "unverifiable")
+                findings.push({ code: "VERIFICATION_UNVERIFIABLE", detail: `${result.label}: ${result.cause}`, nextCommand: `${selector} audit` });
+            else if (result.exitCode !== 0)
+                findings.push({ code: "VERIFICATION_FAILED", detail: `${result.label} exited ${result.exitCode}`, nextCommand: `cd ${quote(input.deliveryCwd)} && ${result.argv.map(quote).join(" ")}` });
+        }
+    }
+    else if (input.verification.status === "unknown") {
+        findings.push({ code: "VERIFICATION_UNVERIFIABLE", detail: input.verification.cause.message, nextCommand: `${selector} audit` });
+    }
+    const residue = input.readiness.deliveryResidue;
+    if (residue.tracked.length + residue.untracked.length > 0)
+        findings.push({ code: "DELIVERY_RESIDUE", detail: `${residue.tracked.length} tracked and ${residue.untracked.length} untracked delivery paths`, nextCommand: `git -C ${quote(input.deliveryCwd)} status --short` });
+    if (input.readiness.arc.max > 0 && input.readiness.arc.open === null && input.readiness.arc.looseCommits.length > 0)
+        findings.push({ code: "LOOSE_COMMITS", detail: `${input.readiness.arc.looseCommits.length} loose commits after fence`, nextCommand: `printf '# Continue\\n\\n## Objective\\nReceipt loose commits.\\n\\n## Brief\\nContinue delivery.\\n' | ${selector} arc` });
+    if (input.readiness.renewSession.open)
+        findings.push({ code: "RENEW_SESSION_OPEN", detail: "renew recovery session is open", nextCommand: `${selector} renew --continue` });
+    if (input.readiness.rewriteGuard.liveProjection)
+        findings.push({ code: "LIVE_REWRITE_GUARD", detail: "a live projection owns the delivery worktree", nextCommand: "keiyaku status" });
+    for (const dependency of input.readiness.dependencies.filter((item) => !item.satisfied))
+        findings.push({ code: "DEPENDENCY_OPEN", detail: `dependency ${dependency.id} is ${dependency.state}`, nextCommand: `keiyaku @${dependency.id} log` });
+    if (input.readiness.petition.state === "petitioned" && input.readiness.petition.queue?.position !== 1)
+        findings.push({ code: "PETITION_QUEUE", detail: `petition queue position ${input.readiness.petition.queue?.position ?? "unknown"}`, nextCommand: "keiyaku status" });
+    return findings;
+}
+function coordinateRaceReport(input) {
+    const findings = [{
+            code: "COORDINATE_RACE",
+            detail: input.detail,
+            nextCommand: `keiyaku @${input.contractId} audit`,
+        }];
+    return {
+        contract: input.contractId,
+        coordinates: input.pinned.coordinates,
+        terms: { criteria: input.pinned.criteria, scope: effectiveScope(input.pinned.entries), appendScope: appendedScopeTerms(input.pinned.entries) },
+        rehearsal: { status: "unknown", cause: { code: "COORDINATE_RACE", message: input.detail } },
+        candidate: null,
+        diff: null,
+        presentation: null,
+        files: null,
+        scope: null,
+        verification: { status: "not_evaluated", reason: "coordinate_race", results: [] },
+        readiness: null,
+        findings,
+        counts: { files: 0, selected: 0, omitted: 0, inScope: 0, downgraded: 0, violated: 0, findings: findings.length },
+    };
+}
+export async function auditContract(input) {
+    const contractId = input.address.binding.commissionId;
+    const root = input.address.repo.stableRoot;
+    const deliveryRef = `refs/heads/keiyaku/${contractId}`;
+    const pinned = await pinCoordinates({ cwd: root, contractId, deliveryRef });
+    let deliveryCwd;
+    let pinnedDeliveryCoordinate;
+    try {
+        deliveryCwd = await resolveContractDeliveryCwd(input.cwd, contractId);
+        pinnedDeliveryCoordinate = await deliveryCoordinate(deliveryCwd);
+    }
+    catch (error) {
+        return coordinateRaceReport({ contractId, pinned, detail: `registered delivery worktree could not be read at pinned coordinate: ${asMessage(error)}` });
+    }
+    if (pinnedDeliveryCoordinate.head !== pinned.coordinates.delivery.head || pinnedDeliveryCoordinate.tree !== pinned.coordinates.delivery.tree) {
+        return coordinateRaceReport({
+            contractId,
+            pinned,
+            detail: `registered delivery worktree ${pinnedDeliveryCoordinate.head}/${pinnedDeliveryCoordinate.tree} does not match pinned delivery ref ${pinned.coordinates.delivery.head}/${pinned.coordinates.delivery.tree}`,
+        });
+    }
+    const readiness = await evaluateReadiness({ root, deliveryCwd, contractId, pinned });
+    const disposable = await createCandidate(root, pinned, contractId);
+    let diff = null;
+    let scope = null;
+    let presentation = null;
+    let files = null;
+    let reportCandidate = null;
+    let verification;
+    try {
+        if (disposable.candidate) {
+            const rawDiff = await readStructuredDiff(disposable.cwd, disposable.candidate.base, disposable.candidate.head, { excludePaths: [path.join(".keiyaku", "KEIYAKU.md")] });
+            const artifactDiff = { ...rawDiff, ...(disposable.candidate.rewritten ? { to: "renew-artifact" } : {}) };
+            const artifact = await writeDiffArtifact({
+                base: disposable.candidate.base,
+                deliveryHead: pinned.coordinates.delivery.head,
+                targetHead: pinned.coordinates.target.head,
+                diff: artifactDiff,
+            });
+            const stamp = path.basename(artifact, ".json");
+            reportCandidate = disposable.candidate.rewritten
+                ? { kind: "renew-artifact", base: disposable.candidate.base, deliveryHead: pinned.coordinates.delivery.head, targetHead: pinned.coordinates.target.head, artifact, stamp }
+                : { kind: "delivery", base: disposable.candidate.base, head: disposable.candidate.head, tree: disposable.candidate.tree };
+            diff = { ...rawDiff, ...(disposable.candidate.rewritten ? { to: `artifact:${stamp}` } : {}) };
+            scope = await evaluateScope(disposable.cwd, pinned.entries, diff);
+            presentation = presentDiff(diff, scope, input.diffBudgetBytes ?? 32_000, artifact);
+            files = fileFacts(diff, scope);
+            verification = await evaluateVerification(disposable.cwd, disposable.candidate.rewritten ? `artifact:${stamp}` : disposable.candidate.head);
+        }
+        else {
+            verification = { status: "not_evaluated", reason: disposable.rehearsal.status === "conflict" ? "renew_conflict" : "renew_unknown", results: [] };
+        }
+        await input.afterEvidence?.();
+    }
+    finally {
+        await fs.rm(disposable.cwd, { recursive: true, force: true });
+    }
+    let rechecked = null;
+    let finalCoordinateReadFailure = null;
+    try {
+        rechecked = await pinCoordinates({ cwd: root, contractId, deliveryRef });
+    }
+    catch (error) {
+        finalCoordinateReadFailure = asMessage(error);
+    }
+    let deliveryCoordinateChanged = false;
+    let deliveryPathChanged = false;
+    try {
+        const recheckedDeliveryCwd = await resolveContractDeliveryCwd(input.cwd, contractId);
+        deliveryPathChanged = path.resolve(deliveryCwd) !== path.resolve(recheckedDeliveryCwd);
+    }
+    catch {
+        deliveryPathChanged = true;
+    }
+    try {
+        const recheckedDeliveryCoordinate = await deliveryCoordinate(deliveryCwd);
+        deliveryCoordinateChanged =
+            pinnedDeliveryCoordinate.head !== recheckedDeliveryCoordinate.head
+                || pinnedDeliveryCoordinate.tree !== recheckedDeliveryCoordinate.tree
+                || pinnedDeliveryCoordinate.residueFingerprint !== recheckedDeliveryCoordinate.residueFingerprint;
+    }
+    catch {
+        deliveryCoordinateChanged = true;
+    }
+    const findings = collectFindings({ contractId, deliveryCwd, rehearsal: disposable.rehearsal, scope, verification, readiness });
+    const changes = rechecked ? coordinateChanges(pinned.coordinates, rechecked.coordinates) : [`final coordinate reread failed: ${finalCoordinateReadFailure}`];
+    if (deliveryPathChanged)
+        changes.push("delivery worktree coordinate changed");
+    if (deliveryCoordinateChanged)
+        changes.push("delivery worktree bytes or HEAD changed");
+    if (changes.length > 0)
+        findings.push({ code: "COORDINATE_RACE", detail: `audit coordinates changed while evidence was collected: ${changes.join("; ")}`, nextCommand: `keiyaku @${contractId} audit` });
+    const countScope = (klass) => scope?.filter((row) => row.class === klass).length ?? 0;
+    return {
+        contract: contractId,
+        coordinates: pinned.coordinates,
+        terms: { criteria: pinned.criteria, scope: effectiveScope(pinned.entries), appendScope: appendedScopeTerms(pinned.entries) },
+        rehearsal: disposable.rehearsal,
+        candidate: reportCandidate,
+        diff,
+        presentation,
+        files,
+        scope,
+        verification,
+        readiness,
+        findings,
+        counts: {
+            files: files?.length ?? 0,
+            selected: presentation?.selected.length ?? 0,
+            omitted: presentation?.omissions.length ?? 0,
+            inScope: countScope("in-scope"),
+            downgraded: countScope("downgraded"),
+            violated: countScope("violated"),
+            findings: findings.length,
+        },
+    };
+}