@astrosheep/keiyaku 2.9.4 → 2.9.6

package/build/core/amend.js

@@ -5,91 +5,33 @@ import { refreshContractView } from "./contract-view.js";
 import { deriveContractState, isTerminalState } from "./status/lifecycle.js";
 import { resolveContractAddress, withResolvedAddress } from "./addressing.js";
 import { resolveDefaultBranch } from "./status/drift.js";
-import { isBlankScopePatternLine, normalizeScopePattern, ScopePatternError } from "./scope.js";
+import { markdownSourceSections, normalizeScopePattern, validateScopeFragmentLines } from "./scope.js";
 import { normalizeSectionTitle } from "./markdown/titles.js";
 import { resolveContractDeliveryCwd } from "./worktree-path.js";
 function amendScopeHeading(name) {
     return `## Scope ${name[0].toUpperCase()}${name.slice(1)}`;
 }
-function sourceLines(markdown) {
-    const lines = [];
-    let start = 0;
-    while (start < markdown.length) {
-        const newline = markdown.indexOf("\n", start);
-        const end = newline === -1 ? markdown.length : newline;
-        const next = newline === -1 ? markdown.length : newline + 1;
-        const raw = markdown.slice(start, end);
-        lines.push({ text: raw.endsWith("\r") ? raw.slice(0, -1) : raw, start, end, next });
-        start = next;
-    }
-    return lines;
-}
-function amendHeading(line) {
-    const match = line.match(/^ {0,3}(#{1,2})(?!#)[ \t]+(.+)$/);
-    if (!match)
-        return null;
-    const level = match[1].length;
-    const title = normalizeSectionTitle(match[2]);
-    if (level !== 2)
-        return { level };
-    if (title === "scope add")
-        return { level, name: "add" };
-    return { level };
-}
-function amendFence(line) {
-    const match = line.match(/^ {0,3}(`{3,}|~{3,})/);
-    if (!match)
-        return null;
-    const marker = match[1];
-    return { delimiter: marker[0], length: marker.length };
-}
 function parseAmendScopeSections(markdown) {
-    const lines = sourceLines(markdown);
     const sections = {};
-    let active;
-    let fence;
-    let frontMatterEnd = -1;
-    if (lines[0]?.text.trim() === "---") {
-        for (let index = 1; index < lines.length; index += 1) {
-            if (lines[index].text.trim() === "---") {
-                frontMatterEnd = index;
-                break;
-            }
-        }
-    }
-    const finishActive = (end) => {
-        if (!active)
-            return;
-        sections[active.name] = { ...active, end };
-        active = undefined;
-    };
-    for (let index = 0; index < lines.length; index += 1) {
-        const line = lines[index];
-        if (index <= frontMatterEnd)
-            continue;
-        const marker = amendFence(line.text);
-        if (fence) {
-            if (marker && marker.delimiter === fence.delimiter && marker.length >= fence.length) {
-                fence = undefined;
-            }
+    for (const section of markdownSourceSections(markdown)) {
+        if (section.level !== 2)
             continue;
+        const title = normalizeSectionTitle(section.title);
+        if (title === "scope add") {
+            throw new FlowError("INVALID_KEIYAKU_DRAFT", "Scope Add is obsolete; use ## Scope Append with a fenced gitignore-subset block");
         }
-        if (marker) {
-            fence = marker;
+        if (title !== "scope append")
             continue;
+        if (sections.append) {
+            throw new FlowError("INVALID_KEIYAKU_DRAFT", `amend input may contain ${amendScopeHeading("append")} at most once`);
         }
-        const heading = amendHeading(line.text);
-        if (!heading)
-            continue;
-        finishActive(line.start);
-        if (!heading.name)
-            continue;
-        if (sections[heading.name]) {
-            throw new FlowError("INVALID_KEIYAKU_DRAFT", `amend input may contain ${amendScopeHeading(heading.name)} at most once`);
-        }
-        active = { name: heading.name, start: line.start, contentStart: line.next };
+        sections.append = {
+            name: "append",
+            start: section.start,
+            contentStart: section.contentStart,
+            end: section.end,
+        };
     }
-    finishActive(markdown.length);
     let prose = markdown;
     for (const section of Object.values(sections).sort((left, right) => right.start - left.start)) {
         prose = `${prose.slice(0, section.start)}${prose.slice(section.end)}`;
@@ -97,30 +39,14 @@ function parseAmendScopeSections(markdown) {
     return { sections, prose };
 }
 function scopePatterns(markdown, section) {
-    const patterns = markdown
-        .slice(section.contentStart, section.end)
-        .split(/\r?\n/)
-        .filter((line) => !isBlankScopePatternLine(line))
-        .map((pattern) => {
-        try {
-            // Do not trim() here: gitignore treats trailing `\ ` as a significant space.
-            return normalizeScopePattern(pattern);
-        }
-        catch (error) {
-            if (error instanceof ScopePatternError) {
-                throw new FlowError("INVALID_KEIYAKU_DRAFT", error.message);
-            }
-            throw error;
-        }
+    return validateScopeFragmentLines(markdown.slice(section.contentStart, section.end).split(/\r?\n/), {
+        heading: amendScopeHeading(section.name),
+        emptyMessage: `amend input has an empty ${amendScopeHeading(section.name)} section`,
     });
-    if (patterns.length === 0) {
-        throw new FlowError("INVALID_KEIYAKU_DRAFT", `amend input has an empty ${amendScopeHeading(section.name)} section`);
-    }
-    return patterns;
 }
 export function buildAmendInput(markdown, cwd, contractId, contractAddressSource) {
     const { sections, prose } = parseAmendScopeSections(markdown);
-    const add = sections.add ? scopePatterns(markdown, sections.add) : [];
+    const append = sections.append ? scopePatterns(markdown, sections.append) : [];
     if (!prose.trim()) {
         throw new FlowError("EMPTY_PARAM", "amendment cannot be empty");
     }
@@ -129,7 +55,7 @@ export function buildAmendInput(markdown, cwd, contractId, contractAddressSource
         ...(contractId ? { contractId } : {}),
         ...(contractAddressSource ? { contractAddressSource } : {}),
         amendment: prose,
-        ...(sections.add ? { scopeDelta: { add } } : {}),
+        ...(sections.append ? { scopeDelta: { add: append } } : {}),
     };
 }
 function requireAmendment(value) {

package/build/core/arc.js

@@ -9,7 +9,7 @@ import { parseCommandMarkdown, requireMarkdownTextSection, requireMarkdownTitle,
 import { resolveContractAddress, withResolvedAddress } from "./addressing.js";
 import { activeLedgerRef, appendWithRetry, readLedger } from "./ledger.js";
 import { refreshContractView } from "./contract-view.js";
-import { findOpenArc, getMaxArc, sealCurrentArc } from "./seal.js";
+import { appendScopeTerms, findOpenArc, getMaxArc, sealCurrentArc } from "./seal.js";
 import { deriveContractState, isTerminalState } from "./status/lifecycle.js";
 import { resolveDefaultBranch } from "./status/drift.js";
 import { persistResponseHistory } from "./transcripts.js";
@@ -61,6 +61,14 @@ export async function openArc(input) {
         throw new FlowError("INTERNAL_STATE", `contract ${input.contractId} not found or not active`);
     }
     assertArcOpenable(input.contractId, ledger.entries);
+    await appendScopeTerms({
+        cwd: input.cwd,
+        renderCwd,
+        contractId: input.contractId,
+        patterns: input.appendScope,
+        actor: input.actor,
+        nowMs: input.nowMs,
+    });
     // Seal capture needs delivery HEAD; ledger append may use hub or delivery (shared refs).
     const sealed = await sealCurrentArc({
         cwd: renderCwd,
@@ -68,7 +76,6 @@ export async function openArc(input) {
         contractId: input.contractId,
         sealedBy: "arc",
         nowMs: input.nowMs,
-        waivePaths: input.waivePaths,
     });
     const at = new Date(input.nowMs).toISOString();
     let arcNumber = 0;
@@ -93,7 +100,7 @@ export async function openArc(input) {
     await refreshContractView({ ledgerCwd: input.cwd, renderCwd, contractId: input.contractId });
     return { contractId: input.contractId, arc: arcNumber, ledgerHead: result.head, sealed };
 }
-export function buildArcInput(content, cwd, waivePaths = [], contractId, contractAddressSource) {
+export function buildArcInput(content, cwd, appendScope = [], contractId, contractAddressSource) {
     const parts = parseCommandMarkdown(content);
     return {
         cwd,
@@ -102,7 +109,7 @@ export function buildArcInput(content, cwd, waivePaths = [], contractId, contrac
         title: requireMarkdownTitle(parts),
         objective: requireMarkdownTextSection(parts, "Objective"),
         brief: requireMarkdownTextSection(parts, "Brief"),
-        waivePaths,
+        appendScope,
     };
 }
 async function readBranchLabels(cwd) {
@@ -126,16 +133,17 @@ export async function arcKeiyaku(input) {
         const title = normalizeInlineTitle(requireText("title", input.title));
         const objective = requireText("objective", input.objective);
         const brief = requireText("brief", input.brief);
+        const nowMs = Date.now();
         const opened = await openArc({
             cwd: input.cwd,
             renderCwd,
             contractId,
             actor: ACTOR_IDENTITY,
-            nowMs: Date.now(),
+            nowMs,
             title,
             objective,
             brief,
-            waivePaths: input.waivePaths,
+            appendScope: input.appendScope,
         });
         const { currentBranch, baseBranch } = await readBranchLabels(renderCwd);
         const summary = opened.sealed

package/build/core/audit/candidate.js

@@ -0,0 +1,48 @@
+import * as fs from "node:fs/promises";
+import * as os from "node:os";
+import * as path from "node:path";
+import { FlowError, asMessage } from "../../flow-error.js";
+import { createGit, wrapGitError } from "../../git/core.js";
+import { readStructuredDiff } from "../../git/diff/structured.js";
+import { rewriteRenewBranch } from "../renew.js";
+async function resolveObject(cwd, revision, kind) {
+    try {
+        return (await createGit(cwd).raw(["rev-parse", "--verify", `${revision}^{${kind}}`])).trim();
+    }
+    catch (error) {
+        throw wrapGitError(`rev-parse ${revision}^{${kind}}`, error, cwd);
+    }
+}
+export async function createAuditCandidate(input) {
+    const cwd = await fs.mkdtemp(path.join(os.tmpdir(), "keiyaku-audit-"));
+    const git = createGit(input.root);
+    try {
+        await git.raw(["clone", "--quiet", "--no-hardlinks", "--no-checkout", input.root, 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/${input.contractId}`, input.frozen.coordinates.delivery.head]);
+        if (input.frozen.base === input.frozen.coordinates.target.head)
+            return { cwd, rehearsal: { status: "fresh" }, candidate: { base: input.frozen.coordinates.target.head, head: input.frozen.coordinates.delivery.head, tree: input.frozen.coordinates.delivery.tree, rewritten: false } };
+        try {
+            await rewriteRenewBranch({ cwd, contractId: input.contractId, oldHead: input.frozen.coordinates.delivery.head, recoveryRef: "refs/keiyaku/audit/disposable", newBase: input.frozen.coordinates.target.head, oldBase: input.frozen.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: input.frozen.base, newBase: input.frozen.coordinates.target.head, oldHead: input.frozen.coordinates.delivery.head }, candidate: { base: input.frozen.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 };
+    }
+}
+export async function disposeAuditCandidate(candidate) { await fs.rm(candidate.cwd, { recursive: true, force: true }); }
+export async function readAuditCandidateDiff(candidateResult) {
+    const candidate = candidateResult.candidate;
+    if (!candidate)
+        return null;
+    return readStructuredDiff(candidateResult.cwd, candidate.base, candidate.head, { excludePaths: [".keiyaku/KEIYAKU.md"] });
+}

package/build/core/audit/coordinates.js

@@ -0,0 +1,180 @@
+import * as fs from "node:fs/promises";
+import * as path from "node:path";
+import { createHash } from "node:crypto";
+import { FlowError, asMessage } from "../../flow-error.js";
+import { createGit, wrapGitError } from "../../git/core.js";
+import { readLedger } from "../ledger.js";
+import { hasStrandableProjectionGeneration } from "../projection/index.js";
+import { readRenewRecoverySession } from "../renew-session.js";
+import { effectiveScope, findOpenArc, getFence, getMaxArc, receiptsAfterFence } from "../seal.js";
+import { queueMembership, readQueueReadModel } from "../settlement/queue.js";
+import { markdownSourceSections } 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);
+    }
+}
+export function appendedScopeTerms(entries) {
+    return entries.flatMap((entry) => entry.kind === "amend" && entry.data.scopeDelta ? entry.data.scopeDelta.add : []);
+}
+export 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;
+            for (const line of entry.data.amendment.slice(section.contentStart, section.end).split(/\r?\n/)) {
+                const match = line.match(/^\s*-\s+(.+)$/);
+                if (match)
+                    criteria.push(match[1].trim());
+            }
+        }
+    }
+    return criteria;
+}
+async function pinLedgerCoordinates(input) {
+    const ledger = await readLedger(input.root, 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.root, input.deliveryRef, "commit"), resolveObject(input.root, input.deliveryRef, "tree"),
+        resolveObject(input.root, target.ref, "commit"), resolveObject(input.root, target.ref, "tree"),
+    ]);
+    return {
+        criteria: effectiveCriteria(ledger.entries), scope: effectiveScope(ledger.entries), appendScope: appendedScopeTerms(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 deliveryResidue(cwd) {
+    const fields = (await createGit(cwd).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] };
+}
+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 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) };
+}
+async function readReadiness(input) {
+    const bind = input.frozen.entries.find((entry) => entry.kind === "bind");
+    const lifecycle = deriveContractState(input.frozen.entries);
+    const [residue, looseCommits, session, queue, liveProjection, dependencies] = await Promise.all([
+        deliveryResidue(input.deliveryCwd), receiptsAfterFence(input.root, input.frozen.entries, input.frozen.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.frozen.entries)?.data.arc ?? (getMaxArc(input.frozen.entries) === 0 ? 0 : null), max: getMaxArc(input.frozen.entries), fence: getFence(input.frozen.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 } };
+}
+export async function pinAuditSnapshot(input) {
+    const contractId = input.address.binding.commissionId;
+    const root = input.address.repo.stableRoot;
+    const deliveryRef = `refs/heads/keiyaku/${contractId}`;
+    return pinLedgerCoordinates({ root, contractId, deliveryRef });
+}
+export function initialCoordinateRace(input) {
+    return { which: "delivery-worktree", pinned: input.frozen.coordinates.delivery, observed: input.observed };
+}
+export async function pinAuditCoordinates(input) {
+    const contractId = input.address.binding.commissionId;
+    const root = input.address.repo.stableRoot;
+    const frozen = await pinAuditSnapshot({ address: input.address });
+    const deliveryCwd = await resolveContractDeliveryCwd(input.cwd, contractId);
+    const coordinate = await deliveryCoordinate(deliveryCwd);
+    if (coordinate.head !== frozen.coordinates.delivery.head || coordinate.tree !== frozen.coordinates.delivery.tree)
+        throw new Error(`registered delivery worktree ${coordinate.head}/${coordinate.tree} does not match pinned delivery ref ${frozen.coordinates.delivery.head}/${frozen.coordinates.delivery.tree}`);
+    const readiness = await readReadiness({ root, deliveryCwd, contractId, frozen });
+    return { ...frozen, deliveryCwd, deliveryCoordinate: coordinate, readiness };
+}
+export async function rereadCoordinateRace(input) {
+    const contractId = input.address.binding.commissionId;
+    const root = input.address.repo.stableRoot;
+    const deliveryRef = `refs/heads/keiyaku/${contractId}`;
+    let after;
+    try {
+        after = await pinLedgerCoordinates({ root, contractId, deliveryRef });
+    }
+    catch (error) {
+        return { which: "ledger", pinned: input.frozen.coordinates.ledger, observed: asMessage(error) };
+    }
+    if (after.coordinates.ledger.head !== input.frozen.coordinates.ledger.head)
+        return { which: "ledger", pinned: input.frozen.coordinates.ledger, observed: after.coordinates.ledger };
+    if (after.coordinates.delivery.head !== input.frozen.coordinates.delivery.head || after.coordinates.delivery.tree !== input.frozen.coordinates.delivery.tree)
+        return { which: "delivery", pinned: input.frozen.coordinates.delivery, observed: after.coordinates.delivery };
+    if (after.coordinates.target.head !== input.frozen.coordinates.target.head || after.coordinates.target.tree !== input.frozen.coordinates.target.tree)
+        return { which: "target", pinned: input.frozen.coordinates.target, observed: after.coordinates.target };
+    try {
+        const deliveryCwd = await resolveContractDeliveryCwd(input.cwd, contractId);
+        const observed = await deliveryCoordinate(deliveryCwd);
+        if (path.resolve(deliveryCwd) !== path.resolve(input.frozen.deliveryCwd) || observed.head !== input.frozen.deliveryCoordinate.head || observed.tree !== input.frozen.deliveryCoordinate.tree || observed.residueFingerprint !== input.frozen.deliveryCoordinate.residueFingerprint)
+            return { which: "delivery-worktree", pinned: { cwd: input.frozen.deliveryCwd, ...input.frozen.deliveryCoordinate }, observed: { cwd: deliveryCwd, ...observed } };
+    }
+    catch (error) {
+        return { which: "delivery-worktree", pinned: { cwd: input.frozen.deliveryCwd, ...input.frozen.deliveryCoordinate }, observed: asMessage(error) };
+    }
+    return null;
+}

package/build/core/audit/evidence.js

@@ -0,0 +1,158 @@
+import { FlowError, asMessage } from "../../flow-error.js";
+import { scopePathEvidence } from "../scope.js";
+import { verificationExecutor, resolveVerificationCommands, runVerificationCommand } from "../settlement/verification.js";
+function importLine(line) {
+    return /^(?:import\b|export\s+(?:\*|\{)|(?:const|let|var)\s+[^=]+\s*=\s*require\s*\(|[^=]+\brequire\s*\(|[^=]+\bimport\s*\()/.test(line.content.trim());
+}
+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 });
+        }
+    return { path: file.path, ...(file.oldPath ? { oldPath: file.oldPath } : {}), matcher, explanations, residue, class: matcher.matched ? "in-scope" : residue.length === 0 && explanations.length > 0 ? "downgraded" : "violated" };
+}
+export async function evaluateScope(input) {
+    const matchers = await scopePathEvidence(input.cwd, input.frozen.scope, input.diff.files.map((file) => file.path));
+    return input.diff.files.map((file, index) => explainFile(file, matchers[index]));
+}
+function rawHunk(file, hunk) {
+    return [`${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}`)].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 byteLength(content) { return new TextEncoder().encode(content).byteLength; }
+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 ratio = (1000 - right.tier * 100) / Math.max(right.bytes, 1) - (1000 - left.tier * 100) / Math.max(left.bytes, 1); return ratio || left.path.localeCompare(right.path) || (left.hunk ?? -1) - (right.hunk ?? -1); }
+function retrieval(from, to, pathname, hunk) { return { kind: "git-coordinate", from, to, argv: ["git", "diff", "--no-color", "--no-ext-diff", "--unified=3", `${from}..${to}`, "--", pathname], path: pathname, hunk }; }
+export function presentDiff(input) {
+    const { diff, scope, budget } = input;
+    const candidates = [];
+    for (let fileIndex = 0; fileIndex < diff.files.length; fileIndex += 1) {
+        const file = diff.files[fileIndex];
+        const policy = portfolioTier(file, scope[fileIndex], 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 = byteLength(chunk.content);
+            candidates.push({ path: file.path, hunk: chunk.hunk, content: chunk.content, bytes, cost: bytes, tier: policy.tier, mandatory: policy.mandatory, module: moduleFor(file.path) });
+        }
+    }
+    const selected = [];
+    const selectedKeys = new Set();
+    let used = 0;
+    const keyFor = (candidate) => `${candidate.path}\0${candidate.hunk ?? "file"}`;
+    const take = (candidate) => { const key = keyFor(candidate); 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);
+    for (const module of [...new Set(candidates.map((candidate) => candidate.module))].sort()) {
+        const representative = candidates.filter((candidate) => candidate.module === module && !selectedKeys.has(keyFor(candidate))).sort(stablePortfolioOrder)[0];
+        if (representative && used + representative.cost <= budget)
+            take(representative);
+    }
+    for (const candidate of [...candidates].sort(stablePortfolioOrder))
+        if (!selectedKeys.has(keyFor(candidate)) && used + candidate.cost <= budget)
+            take(candidate);
+    const omissions = candidates.filter((candidate) => !selectedKeys.has(keyFor(candidate))).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 ? "no-raw-hunks" : used + candidate.cost > budget ? "budget" : "not-selected", retrieval: retrieval(input.retrievalCoordinates.from, input.retrievalCoordinates.to, 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 }; }); }
+export 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;
+        }
+        try {
+            const execution = await runVerificationCommand(cwd, command);
+            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 });
+        }
+        catch (error) {
+            return { status: "unknown", cause: { code: error instanceof FlowError ? error.code : "INTERNAL_STATE", message: asMessage(error) }, results: [] };
+        }
+    }
+    return { status: "evaluated", results };
+}
+export async function collectEvidence(input) {
+    const candidate = input.candidateResult.candidate;
+    if (!candidate)
+        return null;
+    if (!input.diff)
+        return null;
+    const diff = input.diff;
+    const scope = await evaluateScope({ cwd: input.candidateResult.cwd, frozen: input.frozen, diff });
+    return { diff, scope, presentation: presentDiff({ diff, scope, budget: input.diffBudgetBytes, retrievalCoordinates: { from: input.frozen.base, to: input.frozen.coordinates.delivery.head } }), files: fileFacts(diff, scope), verification: await evaluateVerification(input.candidateResult.cwd, candidate.head), candidate };
+}

package/build/core/audit/facade.js

@@ -0,0 +1,42 @@
+import { createAuditCandidate, disposeAuditCandidate, readAuditCandidateDiff } from "./candidate.js";
+import { initialCoordinateRace, pinAuditCoordinates, pinAuditSnapshot, rereadCoordinateRace } from "./coordinates.js";
+import { collectEvidence } from "./evidence.js";
+import { collectFindings, emptyRaceReport } from "./report.js";
+import { readinessFromFacts } from "./readiness.js";
+export async function auditContract(input) {
+    const contractId = input.address.binding.commissionId;
+    let frozen;
+    try {
+        frozen = await pinAuditCoordinates({ cwd: input.cwd, address: input.address });
+    }
+    catch (error) {
+        const fallback = await pinAuditSnapshot({ address: input.address }).catch(() => null);
+        if (!fallback)
+            throw error;
+        return emptyRaceReport({ contractId, coordinates: fallback.coordinates, terms: { criteria: fallback.criteria, scope: fallback.scope, appendScope: fallback.appendScope }, detail: error instanceof Error ? error.message : String(error), race: initialCoordinateRace({ frozen: fallback, observed: error instanceof Error ? error.message : String(error) }) });
+    }
+    const candidateResult = await createAuditCandidate({ root: input.address.repo.stableRoot, contractId, frozen });
+    let evidence = null;
+    let verification;
+    try {
+        const diff = await readAuditCandidateDiff(candidateResult);
+        evidence = await collectEvidence({ candidateResult, frozen, diff, diffBudgetBytes: input.diffBudgetBytes ?? 32_000 });
+        verification = evidence?.verification ?? { status: "not_evaluated", reason: candidateResult.rehearsal.status === "conflict" ? "renew_conflict" : "renew_unknown", results: [] };
+        await input.afterEvidence?.();
+    }
+    finally {
+        await disposeAuditCandidate(candidateResult);
+    }
+    const race = await rereadCoordinateRace({ cwd: input.cwd, address: input.address, frozen });
+    if (race) {
+        const detail = typeof race.observed === "string"
+            ? `final coordinate reread failed: ${race.observed}`
+            : race.which === "delivery-worktree"
+                ? "delivery worktree bytes or HEAD changed"
+                : `audit coordinates changed while evidence was collected: ${race.which}`;
+        return emptyRaceReport({ contractId, coordinates: frozen.coordinates, terms: { criteria: frozen.criteria, scope: frozen.scope, appendScope: frozen.appendScope }, detail, race });
+    }
+    const readiness = readinessFromFacts(frozen.readiness);
+    const findings = collectFindings({ contractId, deliveryCwd: frozen.deliveryCwd, rehearsal: candidateResult.rehearsal, scope: evidence?.scope ?? null, verification, readiness });
+    return { contract: contractId, coordinates: frozen.coordinates, terms: { criteria: frozen.criteria, scope: frozen.scope, appendScope: frozen.appendScope }, rehearsal: candidateResult.rehearsal, candidate: evidence ? (evidence.candidate.rewritten ? { kind: "renew-rehearsal", base: evidence.candidate.base, head: evidence.candidate.head, tree: evidence.candidate.tree, deliveryHead: frozen.coordinates.delivery.head, targetHead: frozen.coordinates.target.head } : { kind: "delivery", base: evidence.candidate.base, head: evidence.candidate.head, tree: evidence.candidate.tree }) : null, diff: evidence?.diff ?? null, presentation: evidence?.presentation ?? null, files: evidence?.files ?? null, scope: evidence?.scope ?? null, verification, readiness, findings, counts: { files: evidence?.files.length ?? 0, selected: evidence?.presentation.selected.length ?? 0, omitted: evidence?.presentation.omissions.length ?? 0, inScope: evidence?.scope.filter((row) => row.class === "in-scope").length ?? 0, downgraded: evidence?.scope.filter((row) => row.class === "downgraded").length ?? 0, violated: evidence?.scope.filter((row) => row.class === "violated").length ?? 0, findings: findings.length } };
+}