@deksden-com/dd-flow-cli 0.9.0-beta.15 → 0.9.0-beta.150

package/dist/services/verification-matrix.js

@@ -0,0 +1,393 @@
+import crypto from "node:crypto";
+import fs from "node:fs";
+import path from "node:path";
+import { AppError } from "../shared/errors.js";
+import { vnextStageDirectory } from "../domain/stage-catalog.js";
+import { checkReceiptEvidenceValid, checkReceipts, effectiveCheckDeclarations } from "./code-checks.js";
+import { acceptStagePacket, prepareStagePacket, publishStagePacket, resolveStagePublicationPath } from "./stage-report-renderer.js";
+import { assertRunMutationAllowed } from "./run-recovery.js";
+import { acceptedIntentContract, acceptedIntentSourceRole, prepareAcceptedIntentSources } from "./accepted-intent.js";
+export const verificationMatrixContract = "dd-flow/verification-matrix@1";
+export const finalCheckCoverageContract = "dd-flow/final-check-coverage@1";
+/** A view of already validated facts: never a gate or a receipt selector. */
+export function buildVerificationMatrix(input) {
+    const sourceCatalog = new Map();
+    const pathChecksums = new Map();
+    for (const source of input.sources) {
+        const location = JSON.stringify([source.root, source.path]);
+        if (pathChecksums.has(location) && pathChecksums.get(location) !== source.sha256)
+            throw new AppError("verification_matrix_source_changed", "Matrix source aliases have conflicting checksums", 1, { root: source.root, path: source.path });
+        pathChecksums.set(location, source.sha256);
+        const identity = JSON.stringify([source.role, source.root, source.path]);
+        const prior = sourceCatalog.get(identity);
+        if (prior && prior.sha256 !== source.sha256)
+            throw new AppError("verification_matrix_source_changed", "Matrix source identity has conflicting checksums", 1, { role: source.role, root: source.root, path: source.path, expected: prior.sha256, current: source.sha256 });
+        sourceCatalog.set(identity, source);
+    }
+    const sources = [...sourceCatalog.values()].sort((a, b) => compare(`${a.role}:${a.root}:${a.path}`, `${b.role}:${b.root}:${b.path}`));
+    const facts = new Map((input.facts ?? []).map(fact => [fact.canonical_ref, fact]));
+    const fact = (check, canonicalRef) => facts.get(canonicalRef) ?? { id: check.id, canonical_ref: canonicalRef, declaration: check, result: null, disposition: input.header.completeness === "skeleton" || input.header.completeness === "declared" ? "not_run" : "not_due" };
+    const protocols = Object.keys(input.ownership).sort(compare);
+    const requirements = protocols.flatMap(protocolId => input.requirements.filter(item => input.ownership[protocolId].includes(item.id)).map(item => {
+        const plan = input.plans.find(value => value.protocol_id === protocolId);
+        return { protocol_id: protocolId, ...item, plan_items: (plan?.items ?? []).filter(value => value.requirement_refs.includes(item.id)).map(value => ({ id: value.id, check_refs: unique(value.verification.check_refs), work_ids: unique((input.works ?? []).filter(work => work.protocol_id === protocolId && work.plan_item_id === value.id).map(work => work.work_id)) })).sort((a, b) => compare(a.id, b.id)) };
+    })).sort((a, b) => compare(`${a.protocol_id}:${a.id}`, `${b.protocol_id}:${b.id}`));
+    const criteria = protocols.flatMap(protocolId => input.criteria.filter(item => input.ownership[protocolId].includes(item.id)).flatMap(item => {
+        const plan = input.plans.find(value => value.protocol_id === protocolId);
+        const entries = plan?.acceptance.filter(value => value.criterion_id === item.id) ?? [];
+        return (entries.length ? entries : [null]).map(entry => ({ protocol_id: protocolId, criterion_id: item.id, statement: item.statement, gate: entry?.gate ?? null, check_refs: unique(entry?.check_refs ?? []), declaration: entry, checks: unique(entry?.check_refs ?? []).map(id => {
+                const check = plan?.checks.find(value => value.id === id);
+                if (!check)
+                    throw new AppError("verification_matrix_source_invalid", "Validated PLAN references an absent check", 1, { protocol_id: protocolId, check_id: id });
+                return fact(check, `${protocolId}/${id}`);
+            }) }));
+    })).sort((a, b) => compare(`${a.protocol_id}:${a.criterion_id}:${a.gate}`, `${b.protocol_id}:${b.criterion_id}:${b.gate}`));
+    const policyChecks = (input.policyChecks ?? []).map(check => fact(check, check.canonical_ref ?? check.id)).sort((a, b) => compare(a.canonical_ref, b.canonical_ref));
+    const projectedFacts = [...new Map([...criteria.flatMap(row => row.checks), ...policyChecks].map(fact => [fact.canonical_ref, fact])).values()].sort((a, b) => compare(a.canonical_ref, b.canonical_ref));
+    const descriptor = { header: input.header, sources, facts: projectedFacts };
+    return canonical({ schema_id: verificationMatrixContract, header: { ...input.header, source_fingerprint: digest(stableJson(descriptor)) }, sources, requirements, criteria, policy_checks: policyChecks, ...(input.semanticAssessment ? { semantic_assessment: input.semanticAssessment } : {}) });
+}
+export function renderVerificationMatrix(matrix) {
+    const h = matrix.header;
+    const status = (check) => check.disposition === "unavailable" ? `unavailable (reported native status: ${check.result?.status ?? "none"}; ${check.reason ?? "missing exact proof"})` : String(check.result?.status ?? check.disposition);
+    return [`# Verification matrix`, "", `RUN: ${escape(h.run_id)}; stage: ${escape(h.stage)} / ${escape(h.stage_attempt)}; role: ${h.role}; completeness: ${h.completeness}.`, "", "This generated view is not semantic acceptance. A retained passed check proves only its declared contour and proof limits.", "", "## Requirements", "", "| Protocol | Requirement | Statement | PLAN items / checks |", "| --- | --- | --- | --- |", ...matrix.requirements.map(row => `| ${escape(row.protocol_id)} | ${escape(row.id)} | ${escape(row.statement)} | ${escape(row.plan_items.map(item => `${item.id}: ${item.check_refs.join(", ")}`).join("; "))} |`), "", "## Acceptance criteria", "", "| Protocol | Criterion | Gate | Checks / native results | Proof limits |", "| --- | --- | --- | --- | --- |", ...matrix.criteria.map(row => `| ${escape(row.protocol_id)} | ${escape(row.criterion_id)} | ${escape(row.gate ?? "not declared")} | ${escape(row.checks.map(check => `${check.canonical_ref}: ${status(check)}`).join("; "))} | ${escape(JSON.stringify(row.declaration?.proof_limits ?? []))} |`), "", "## Policy checks", "", ...matrix.policy_checks.map(check => `- ${escape(check.canonical_ref)}: ${escape(status(check))}`), "", "## Sources", "", ...matrix.sources.map(source => `- ${escape(source.role)}: ${escape(`${source.root}:${source.path}`)} (${source.sha256})`), ""].join("\n");
+}
+export function verificationMatrixInstruction(metadata, runHome, task) {
+    const contract = `<verification_evidence_contract>\nCheck prerequisites must be executable in the check command or supported project policy; purpose prose and list order do not prepare an environment. A readiness gate is final verification, not implicit setup before the first CODE Work. PLAN and PLAN-REVIEW must compare claimed prerequisites with the actual launch path: a description saying migrate-before-check cannot repair a command that checks before migration. Prefer the existing self-contained project verification alias.\nBrowser checks must prove the expected surface exists and the measured set is nonempty before asserting layout geometry. An empty DOM is not evidence of no overlap. Derive navigation from the actual UI and accepted specification. Review whether the test can fail for the intended defect; a green named contour does not prove complete product semantics. Keep native test outcome separate from observation/cleanup: passed assertions with unknown cleanup are neither PASS nor a product assertion failure. Use retained native diagnostics and proof limits; generic timeouts or infrastructure errors do not authorize source repair. Do not patch the candidate product outside the assigned flow Work.\n</verification_evidence_contract>\n`;
+    if (!metadata)
+        return contract;
+    const originals = metadata.accepted_sources?.length ? ["Original accepted inputs (ordered intake, then question/answer pairs):", "A question is retained only to interpret its delivered user answer. Agent recommendations and options are not accepted decisions unless that answer explicitly adopts them.", ...metadata.accepted_sources.map(source => `- ${source.role}: ${safePath(runHome, source.path, false)} (sha256 ${source.sha256})`)].join("\n") : "Original accepted-input coverage is unavailable for this historical RUN. Do not treat SPECIFY as the original user input or claim that semantic preservation was verified.";
+    const originalContract = `<accepted_intent_sources>\n${originals}\nCompare original accepted inputs with SPECIFY, effective amendments, PLAN and observable implementation. Preserve material actors, operations, UI/API surfaces, state transitions and exceptions when applicable. API evidence does not prove UI behavior. Later text supersedes an earlier accepted decision only when explicitly accepted as such; unresolved conflicts are material questions, not last-text-wins. Report lost obligations with source and R/AC references. Never edit immutable accepted SPECIFY to conceal a finding. Use the supported upstream correction route; if unavailable or a wholly missing R/AC needs a new accepted revision, report an actionable blocker rather than repairing only PLAN. Do not fabricate HITL references. A structurally complete matrix is not semantic acceptance.\n</accepted_intent_sources>\n`;
+    return `${contract}${originalContract}<verification_matrix>\nRuntime generated the technical verification matrix: ${safePath(runHome, metadata.markdown.path, false)}; structured data: ${safePath(runHome, metadata.json.path, false)}. Source fingerprint: ${metadata.source_fingerprint}; completeness: ${metadata.completeness}. Read it before ${task}. This is a derived view of the named accepted requirements, PLAN and receipts, not semantic acceptance. Do not edit these generated files or manually duplicate receipt IDs/hashes/results. Record insufficient proof or violated criteria in the ordinary Stage/Work result with evidence references; modify only your assigned source/test/result documents. Review inputs remain read-only. A passed check proves only its named contour and limits, not all business semantics or production readiness.\n</verification_matrix>\n`;
+}
+/** Attachment and packet authority share a short transaction, then both files
+ * must be visible before the prompt claims they are ready. */
+export function commitVerificationMatrixStart(context, prepared, attach) {
+    context.db.writeTransaction(() => { attach(); acceptVerificationMatrix(context, prepared); });
+    publishVerificationMatrix(context, prepared);
+}
+export function resumeVerificationMatrix(context, projectId, runId, stage) {
+    const retained = latestRunVerificationMatrix(context, projectId, runId, stage, "input");
+    const run = context.db.get("SELECT index_json FROM runs WHERE project_id = ? AND id = ?", [projectId, runId]);
+    if (run && JSON.parse(run.index_json).verification_matrix_contract === verificationMatrixContract && !retained)
+        throw new AppError("verification_matrix_packet_missing", "Marked Stage has no retained input matrix", 1, { stage, run_id: runId });
+    publishVerificationMatrix(context, retained);
+    return retained;
+}
+/** Resolve bounded authority outside the owning write transaction. */
+export function prepareRunVerificationMatrix(context, input) {
+    const run = context.db.get("SELECT run_root, workspace_root, index_json FROM runs WHERE project_id = ? AND id = ?", [input.projectId, input.runId]);
+    if (!run)
+        throw new AppError("not_found", "Matrix RUN is missing", 1);
+    const index = JSON.parse(run.index_json);
+    if (index.verification_matrix_contract !== verificationMatrixContract)
+        return null;
+    const generation = assertRunMutationAllowed(context, input.projectId, input.runId);
+    if (!run.run_root)
+        throw new AppError("runtime_missing", "Matrix RUN home is missing", 1);
+    const home = run.run_root, workspace = run.workspace_root;
+    const owning = index.stage_runs?.find(item => item.stage === input.stage);
+    const attempt = input.stageAttempt ?? owning?.attempt ?? "try-001";
+    const sources = [], packets = [];
+    const intentContract = index.accepted_intent_contract;
+    if (intentContract !== undefined && intentContract !== acceptedIntentContract)
+        throw new AppError("accepted_intent_contract_unsupported", "Unknown accepted-input custody contract", 1, { contract: intentContract });
+    const intent = prepareAcceptedIntentSources(context, { projectId: input.projectId, runId: input.runId, home, stageDirectory: vnextStageDirectory(input.stage), marked: index.accepted_intent_contract === acceptedIntentContract });
+    sources.push(...intent.sources);
+    packets.push(...intent.packets);
+    const readSource = (role, root, relative, expected) => {
+        const file = safePath(root === "run" ? home : workspace, relative), bytes = fs.readFileSync(file), sha = digest(bytes);
+        if (expected && sha !== expected)
+            throw new AppError("verification_matrix_source_changed", "Matrix source differs from accepted bytes", 1, { role, path: relative, expected, current: sha });
+        sources.push({ role, root, path: slash(relative), sha256: sha });
+        return JSON.parse(bytes.toString("utf8"));
+    };
+    const specifySha = index.stage_runs?.find(item => item.stage === "specify")?.data_sha256;
+    const protocolizeSha = index.stage_runs?.find(item => item.stage === "protocolize")?.data_sha256;
+    if (!specifySha || !protocolizeSha)
+        throw new AppError("verification_matrix_source_unbound", "Marked matrix needs accepted SPECIFY and PROTOCOLIZE source checksums", 1);
+    const specify = readSource("specify", "run", "01-specify/specify.json", specifySha);
+    const protocolize = readSource("protocolize", "run", "02-protocolize/protocolize-result.json", protocolizeSha);
+    const amendments = new Map((protocolize.obligation_amendments ?? []).map(item => [item.target_id, item.replacement]));
+    const effective = (items) => items.map(item => ({ ...item, statement: amendments.get(item.id) ?? item.statement }));
+    // PROTOCOLIZE data_sha256 binds protocolize-result.json, not its derived
+    // Stage report. The report has a separate exact publication receipt.
+    const reportReceipts = context.db.all("SELECT payload_json FROM audit_events WHERE project_id = ? AND event_type = 'flow_run.stage_report' ORDER BY id DESC", [input.projectId]);
+    const protocolPublication = reportReceipts.map(row => JSON.parse(row.payload_json)).find(item => item.run_id === input.runId && item.stage === "protocolize" && item.attempt === index.stage_runs?.find(stage => stage.stage === "protocolize")?.attempt);
+    if (!protocolPublication)
+        throw new AppError("verification_matrix_source_unbound", "Marked matrix needs the retained PROTOCOLIZE report receipt", 1);
+    const protocolReport = readSource("protocolize_report", "run", "02-protocolize/stage-report.json", protocolPublication?.sha256);
+    const protocols = protocolReport.semantic.acceptance;
+    const ownership = Object.fromEntries(protocols.map((protocol, i) => [protocol, protocolize.obligation_ownership.filter(item => item.member_keys.includes(protocolize.delivery.members[i].key)).map(item => item.obligation_id)]));
+    const skeleton = input.stage === "plan" && input.role === "input";
+    const plans = [];
+    const reviewSkipped = index.settings?.code_review?.mode === "off" && Boolean(index.settings.code_review.reason?.trim()) && !index.stage_runs?.some(item => item.stage === "code-review");
+    const predecessor = input.stage === "plan-review" ? "plan" : input.stage === "code" ? "plan-review" : input.stage === "code-review" ? "code" : input.stage === "merge" ? reviewSkipped ? "code" : "code-review" : null;
+    const priorMatrix = input.role === "input" && predecessor ? latestRunVerificationMatrix(context, input.projectId, input.runId, predecessor, "output") : null;
+    if (input.role === "input" && predecessor && !priorMatrix)
+        throw new AppError("verification_matrix_packet_missing", "Marked Stage requires its accepted predecessor output matrix", 1, { stage: input.stage, predecessor });
+    if (!skeleton) {
+        const batchPath = "03-plan/code-work-batch.json", batchFile = safePath(home, batchPath);
+        if (!fs.existsSync(batchFile))
+            throw new AppError("verification_matrix_source_missing", "Marked matrix requires its generated CODE batch", 1, { path: batchPath });
+        const batchBytes = fs.readFileSync(batchFile), batchSha = digest(batchBytes);
+        const acceptedBatch = priorMatrix?.matrix.sources.find(source => source.role === "code_work_batch");
+        if (acceptedBatch && acceptedBatch.sha256 !== batchSha)
+            throw new AppError("verification_matrix_source_changed", "CODE batch differs from accepted predecessor matrix", 1, { path: batchPath, expected: acceptedBatch.sha256, current: batchSha });
+        const batchSnapshot = `${vnextStageDirectory(input.stage)}/verification/sources/${batchSha}/code-work-batch.json`;
+        packets.push(prepareStagePacket(safePath(home, batchSnapshot), batchBytes));
+        sources.push({ role: "code_work_batch", root: "run", path: batchSnapshot, sha256: batchSha });
+        if (input.stage === "merge" && input.role === "output")
+            sources.push({ role: "code_work_batch_current", root: "run", path: batchPath, sha256: batchSha });
+        for (const protocol of protocols) {
+            const relative = `.memory-bank/protocol/${protocol}/plan.json`, file = safePath(workspace, relative);
+            // PLAN bytes are retained before MERGE cleanup; later recovery does not
+            // depend on a feature checkout remaining on disk.
+            let bytes;
+            if (fs.existsSync(file))
+                bytes = fs.readFileSync(file);
+            else {
+                const retained = latestRunVerificationMatrix(context, input.projectId, input.runId, "merge", "input");
+                const prior = retained?.matrix.sources.find(source => source.role === `plan:${protocol}` && source.root === "run");
+                if (!prior)
+                    throw new AppError("verification_matrix_source_missing", "Accepted PLAN was removed without retained source", 1, { protocol_id: protocol });
+                bytes = fs.readFileSync(safePath(home, prior.path));
+                if (digest(bytes) !== prior.sha256)
+                    throw new AppError("verification_matrix_source_changed", "Retained PLAN checksum differs", 1, { protocol_id: protocol });
+            }
+            const plan = JSON.parse(bytes.toString("utf8"));
+            const acceptedSource = priorMatrix?.matrix.sources.find(source => source.role === `plan:${protocol}`);
+            if (acceptedSource && digest(bytes) !== acceptedSource.sha256)
+                throw new AppError("verification_matrix_source_changed", "PLAN differs from accepted predecessor matrix", 1, { protocol_id: protocol, expected: acceptedSource.sha256, current: digest(bytes) });
+            if (plan.protocol_id !== protocol || !Array.isArray(plan.checks) || !Array.isArray(plan.items) || !Array.isArray(plan.acceptance))
+                throw new AppError("verification_matrix_source_invalid", "Matrix requires a validated structured PLAN", 1, { protocol_id: protocol });
+            const sha = digest(bytes), snapshot = `${vnextStageDirectory(input.stage)}/verification/sources/${sha}/plan.json`;
+            packets.push(prepareStagePacket(safePath(home, snapshot), bytes));
+            sources.push({ role: `plan:${protocol}`, root: "run", path: snapshot, sha256: sha });
+            plans.push(plan);
+        }
+    }
+    const semanticFile = input.semanticFile;
+    let semanticAssessment;
+    if (semanticFile && fs.existsSync(semanticFile)) {
+        const relative = path.relative(home, semanticFile);
+        readSource("semantic_assessment", "run", relative);
+        const source = sources[sources.length - 1];
+        semanticAssessment = { root: source.root, path: source.path, sha256: source.sha256 };
+    }
+    const mergeAcceptanceFile = path.join(home, "07-merge", "merge-gate-acceptance.json");
+    const final = input.stage === "merge" && input.role === "output";
+    let merge;
+    let policyChecks = [];
+    if (!skeleton && input.stage !== "merge")
+        policyChecks = effectiveCheckDeclarations(workspace, [], ["work", "code", "readiness", "merge", "release"]);
+    let selected = input.receipts ?? [];
+    if (!input.receipts && priorMatrix && ["code-review", "merge"].includes(input.stage)) {
+        const ids = new Set([...priorMatrix.matrix.criteria.flatMap(row => row.checks), ...priorMatrix.matrix.policy_checks].flatMap(fact => typeof fact.result?.id === "string" ? [fact.result.id] : []));
+        selected = checkReceipts(context, { projectId: input.projectId, runId: input.runId }).filter(receipt => ids.has(receipt.id));
+    }
+    let finalBindings;
+    if (input.stage === "merge") {
+        const gate = readSource("merge_gate", "run", "07-merge/merge-gate.json");
+        if (index.final_check_coverage_contract === finalCheckCoverageContract) {
+            for (const role of final ? ["baseline", "source", "target"] : ["baseline", "source"])
+                readSource(`check_profile_${role}`, "run", `07-merge/check-profile-${role}.json`);
+        }
+        const semanticRefs = new Set(plans.flatMap(plan => plan.acceptance.flatMap(entry => entry.check_refs.map(id => `${plan.protocol_id}/${id}`))));
+        policyChecks = gate.checks.filter(check => !semanticRefs.has(check.canonical_ref ?? check.id));
+        if (final) {
+            const acceptance = readSource("merge_acceptance", "run", "07-merge/merge-gate-acceptance.json");
+            if (acceptance.run_id !== input.runId || acceptance.gate_hash !== gate.gate_hash || acceptance.profile_hash !== gate.profile_hash || !acceptance.accepted_tree)
+                throw new AppError("verification_matrix_binding_invalid", "Final matrix has foreign MERGE acceptance", 1);
+            finalBindings = new Map();
+            for (const binding of acceptance.receipts)
+                for (const ref of binding.binding_refs) {
+                    if (finalBindings.has(ref))
+                        throw new AppError("verification_matrix_binding_ambiguous", "Final acceptance repeats a check binding", 1, { check_ref: ref });
+                    finalBindings.set(ref, binding.id);
+                }
+            const persisted = checkReceipts(context, { projectId: input.projectId, runId: input.runId });
+            selected = acceptance.receipts.map(binding => {
+                const receipt = selected.find(item => item.id === binding.id && item.input_hash === binding.input_hash);
+                if (!receipt)
+                    throw new AppError("verification_matrix_binding_invalid", "Final matrix lacks bound receipt", 1, { receipt_id: binding.id });
+                const original = persisted.find(item => item.id === binding.id && item.input_hash === binding.input_hash);
+                if (!original)
+                    throw new AppError("verification_matrix_binding_invalid", "Final matrix lacks retained native execution receipt", 1, { receipt_id: binding.id });
+                return original;
+            });
+            merge = { merge_request_id: acceptance.merge_request_id, work_id: acceptance.work_id, gate_hash: acceptance.gate_hash, profile_hash: acceptance.profile_hash, accepted_tree: acceptance.accepted_tree, acceptance_ref: { root: "run", path: "07-merge/merge-gate-acceptance.json", sha256: digest(fs.readFileSync(mergeAcceptanceFile)) } };
+        }
+    }
+    const declarations = [...plans.flatMap(plan => plan.checks.map(check => ({ ...check, canonical_ref: `${plan.protocol_id}/${check.id}` }))), ...policyChecks];
+    const facts = declarations.map(check => {
+        const ref = check.canonical_ref ?? check.id;
+        // Unscoped CODE IDs are permitted only by the accepted PSET validator's
+        // uniqueness rule. Never silently alias the same short ID across sources.
+        const uniqueShortId = plans.filter(plan => plan.checks.some(candidate => candidate.id === check.id)).length === 1;
+        const matches = selected.filter(receipt => finalBindings ? finalBindings.get(ref) === receipt.id : receipt.check_refs.includes(ref) || (input.stage !== "merge" && uniqueShortId && receipt.check_refs.includes(check.id)));
+        if (matches.length > 1)
+            throw new AppError("verification_matrix_binding_ambiguous", "Matrix was supplied multiple current receipts for one declaration", 1, { check_ref: ref });
+        const receipt = matches[0];
+        const due = input.stage === "merge" ? check.run_at !== "release" : ["work", "code", "readiness"].includes(check.run_at);
+        if (!receipt)
+            return { id: check.id, canonical_ref: ref, declaration: check, result: null, disposition: skeleton || input.stage.startsWith("plan") ? "not_run" : due && input.role === "output" ? "unavailable" : "not_due" };
+        const valid = receipt.status !== "passed" || checkReceiptEvidenceValid(receipt);
+        const portable = portableReceipt(receipt, home);
+        const receiptFile = safePath(home, portable.receipt_path);
+        if (!fs.existsSync(receiptFile))
+            return { id: check.id, canonical_ref: ref, declaration: check, result: portable, disposition: "unavailable", reason: "receipt_file_missing" };
+        const bytes = fs.readFileSync(receiptFile);
+        sources.push({ role: `receipt:${ref}`, root: "run", path: portable.receipt_path, sha256: digest(bytes) });
+        const retainedReceipt = JSON.parse(bytes.toString("utf8"));
+        for (const artifact of retainedReceipt.artifacts ?? []) {
+            if (path.isAbsolute(artifact.path) || artifact.path.includes("\0") || artifact.path.split(/[\\/]/).includes(".."))
+                throw new AppError("verification_matrix_path_invalid", "Native artifact must remain inside its evidence directory", 1, { path: artifact.path });
+            const artifactPath = slash(path.join(path.dirname(portable.receipt_path), "artifacts", artifact.path));
+            const artifactFile = safePath(home, artifactPath);
+            if (fs.existsSync(artifactFile))
+                sources.push({ role: `artifact:${ref}:${artifact.path}`, root: "run", path: artifactPath, sha256: digest(fs.readFileSync(artifactFile)) });
+        }
+        if (receipt.status !== "aborted" && fs.existsSync(receipt.completion_path)) {
+            const completionPath = portable.completion_path;
+            const completionFile = safePath(home, completionPath);
+            sources.push({ role: `completion:${ref}`, root: "run", path: completionPath, sha256: digest(fs.readFileSync(completionFile)) });
+        }
+        return { id: check.id, canonical_ref: ref, declaration: check, result: portable, disposition: valid ? "retained" : "unavailable", ...(!valid ? { reason: "receipt_evidence_invalid" } : {}) };
+    });
+    const works = context.db.all("SELECT work_id, payload_json FROM works WHERE project_id = ? AND run_id = ?", [input.projectId, input.runId]).flatMap(work => {
+        const source = work.payload_json ? JSON.parse(work.payload_json).source : null;
+        return source ? [{ work_id: work.work_id, protocol_id: source.protocol_id, plan_item_id: source.plan_item_id }] : [];
+    });
+    const repair = index.variables?.["merge.source_repair"];
+    const header = { project_id: input.projectId, run_id: input.runId, stage: input.stage, stage_attempt: attempt, role: input.role, completeness: input.completeness ?? (skeleton ? "skeleton" : input.stage.startsWith("plan") ? "declared" : final ? "final" : "execution"), ...(repair?.cycle ? { review_cycle: repair.cycle } : {}), ...(merge ? { merge } : {}) };
+    const matrix = buildVerificationMatrix({ header, sources, requirements: effective(specify.requirements), criteria: effective(specify.acceptance_criteria), ownership, plans, policyChecks, facts, works, ...(semanticAssessment ? { semanticAssessment } : {}) });
+    const root = `${vnextStageDirectory(input.stage)}/verification/${matrix.header.source_fingerprint}`;
+    const json = prepareStagePacket(safePath(home, `${root}/verification-matrix.json`), Buffer.from(stableJson(matrix)));
+    const markdown = prepareStagePacket(safePath(home, `${root}/verification-matrix.md`), Buffer.from(renderVerificationMatrix(matrix)));
+    packets.push(json, markdown);
+    const metadata = { contract: verificationMatrixContract, role: header.role, completeness: header.completeness, source_fingerprint: matrix.header.source_fingerprint, json: { path: slash(path.relative(home, json.file)), sha256: json.sha256 }, markdown: { path: slash(path.relative(home, markdown.file)), sha256: markdown.sha256 } };
+    if (intent.sources.length)
+        metadata.accepted_sources = intent.sources;
+    if (index.final_check_coverage_contract === finalCheckCoverageContract)
+        metadata.coverage_contract = finalCheckCoverageContract;
+    const predecessors = (index.stage_runs ?? []).filter(item => item.stage !== input.stage && item.status === "done").map(item => ({ stage: item.stage, ...(item.attempt ? { attempt: item.attempt } : {}), ...(item.data_sha256 ? { data_sha256: item.data_sha256 } : {}) }));
+    return { projectId: input.projectId, runId: input.runId, stage: input.stage, home, attempt, generation, packets, matrix, metadata, predecessors };
+}
+/** Called inside the existing owning settlement; publication is after COMMIT. */
+export function acceptVerificationMatrix(context, prepared) {
+    if (!prepared)
+        return;
+    assertRunMutationAllowed(context, prepared.projectId, prepared.runId, prepared.generation);
+    const run = context.db.get("SELECT index_json FROM runs WHERE project_id = ? AND id = ?", [prepared.projectId, prepared.runId]);
+    const index = JSON.parse(run.index_json);
+    if (index.stage_runs?.find(item => item.stage === prepared.stage)?.attempt !== prepared.attempt)
+        throw new AppError("verification_matrix_owner_changed", "Matrix owning attempt changed during preparation", 1, { stage: prepared.stage, expected_attempt: prepared.attempt });
+    for (const source of prepared.predecessors ?? []) {
+        const current = index.stage_runs?.find(item => item.stage === source.stage);
+        if (current?.attempt !== source.attempt || current?.data_sha256 !== source.data_sha256)
+            throw new AppError("verification_matrix_source_changed", "Accepted predecessor changed after matrix preparation", 1, { stage: source.stage });
+    }
+    for (const packet of prepared.packets)
+        acceptStagePacket(context, { projectId: prepared.projectId, runId: prepared.runId, stage: prepared.stage, prepared: packet });
+}
+export function publishVerificationMatrix(context, prepared) {
+    if (!prepared)
+        return;
+    for (const packet of prepared.packets) {
+        publishStagePacket(context, prepared.projectId, prepared.runId, prepared.stage, packet.file);
+        if (!fs.existsSync(packet.file) || digest(fs.readFileSync(packet.file)) !== packet.sha256)
+            throw new AppError("publication_pending", "Matrix packet is not published with its accepted checksum", 1, { file: packet.file, effect: "committed" });
+    }
+}
+export function latestRunVerificationMatrix(context, projectId, runId, stage, role) {
+    const run = context.db.get("SELECT run_root, index_json FROM runs WHERE project_id = ? AND id = ?", [projectId, runId]);
+    if (!run?.run_root)
+        return null;
+    const index = JSON.parse(run.index_json);
+    if (index.accepted_intent_contract !== undefined && index.accepted_intent_contract !== acceptedIntentContract)
+        throw new AppError("accepted_intent_contract_unsupported", "Unknown accepted-input custody contract", 1, { contract: index.accepted_intent_contract });
+    const attempt = index.stage_runs?.find(item => item.stage === stage)?.attempt;
+    const rows = context.db.all("SELECT payload_json FROM audit_events WHERE project_id = ? AND event_type = 'flow_run.stage_packet' ORDER BY id DESC", [projectId]);
+    for (const row of rows) {
+        const packet = JSON.parse(row.payload_json);
+        if (packet.run_id !== runId || packet.stage !== stage || packet.attempt !== attempt || !packet.file.endsWith("/verification-matrix.json"))
+            continue;
+        const bytes = Buffer.from(packet.base64, "base64");
+        if (digest(bytes) !== packet.sha256)
+            throw new AppError("stage_packet_invalid", "Retained matrix packet is corrupt", 1);
+        const matrix = JSON.parse(bytes.toString("utf8"));
+        if (role && matrix.header.role !== role)
+            continue;
+        if (matrix.schema_id !== verificationMatrixContract || matrix.header.run_id !== runId || matrix.header.stage !== stage || matrix.header.stage_attempt !== attempt)
+            throw new AppError("stage_packet_invalid", "Retained matrix owner differs from its packet", 1);
+        packet.file = resolveStagePublicationPath(context, projectId, runId, packet.file);
+        const mdFile = packet.file.replace(/\.json$/, ".md");
+        const paired = rows.map(row => JSON.parse(row.payload_json)).find(item => item.run_id === runId && item.stage === stage && item.attempt === attempt && resolveStagePublicationPath(context, projectId, runId, item.file) === mdFile);
+        if (!paired)
+            throw new AppError("stage_packet_invalid", "Retained matrix lacks its exact Markdown packet", 1);
+        const mdBytes = Buffer.from(paired.base64, "base64");
+        if (digest(mdBytes) !== paired.sha256)
+            throw new AppError("stage_packet_invalid", "Retained matrix Markdown checksum differs", 1);
+        const md = { file: mdFile, bytes: mdBytes, sha256: paired.sha256 };
+        const json = { file: packet.file, bytes, sha256: packet.sha256 };
+        const metadata = { contract: verificationMatrixContract, role: matrix.header.role, completeness: matrix.header.completeness, source_fingerprint: matrix.header.source_fingerprint, json: { path: slash(path.relative(run.run_root, packet.file)), sha256: packet.sha256 }, markdown: { path: slash(path.relative(run.run_root, mdFile)), sha256: md.sha256 } };
+        const acceptedSources = matrix.sources.filter(source => acceptedIntentSourceRole(source.role)).sort((a, b) => a.role === "accepted_intake" ? -1 : b.role === "accepted_intake" ? 1 : compare(a.role, b.role));
+        if (index.accepted_intent_contract === acceptedIntentContract && !acceptedSources.some(source => source.role === "accepted_intake"))
+            throw new AppError("accepted_intent_source_gap", "Marked matrix is missing its original accepted intake", 1, { stage, run_id: runId });
+        if (acceptedSources.length)
+            metadata.accepted_sources = acceptedSources;
+        if (index.final_check_coverage_contract === finalCheckCoverageContract)
+            metadata.coverage_contract = finalCheckCoverageContract;
+        const sourcePackets = matrix.sources.filter(source => (source.role.startsWith("plan:") || source.role === "code_work_batch" || acceptedIntentSourceRole(source.role)) && source.root === "run").map(source => {
+            const file = safePath(run.run_root, source.path, false);
+            const retained = rows.map(row => JSON.parse(row.payload_json)).find(item => item.run_id === runId && item.stage === stage && item.attempt === attempt && resolveStagePublicationPath(context, projectId, runId, item.file) === file && item.sha256 === source.sha256);
+            if (!retained)
+                throw new AppError("stage_packet_invalid", "Matrix PLAN source lacks retained bytes", 1, { path: source.path });
+            const bytes = Buffer.from(retained.base64, "base64");
+            if (digest(bytes) !== source.sha256)
+                throw new AppError("stage_packet_invalid", "Matrix PLAN source checksum differs", 1, { path: source.path });
+            return { file, bytes, sha256: source.sha256 };
+        });
+        const prepared = { projectId, runId, stage, home: run.run_root, attempt: packet.attempt, packets: [...sourcePackets, json, md], matrix, metadata };
+        return prepared;
+    }
+    return null;
+}
+function portableReceipt(receipt, home) {
+    const relative = (file) => slash(path.relative(home, safePath(home, path.relative(home, file))));
+    return { ...receipt, receipt_path: relative(receipt.receipt_path), completion_path: relative(receipt.completion_path), stdout_path: relative(receipt.stdout_path), stderr_path: relative(receipt.stderr_path), artifacts: receipt.artifacts.map(item => {
+            const artifactPath = path.isAbsolute(item.path) ? path.relative(path.join(path.dirname(receipt.receipt_path), "artifacts"), item.path) : item.path;
+            if (path.isAbsolute(artifactPath) || artifactPath.includes("\0") || artifactPath.split(/[\\/]/).includes(".."))
+                throw new AppError("verification_matrix_path_invalid", "Native artifact must remain inside its evidence directory", 1, { path: item.path });
+            safePath(home, path.join(path.dirname(relative(receipt.receipt_path)), "artifacts", artifactPath));
+            return { ...item, path: slash(artifactPath) };
+        }) };
+}
+function safePath(root, relative, inspectFilesystem = true) {
+    if (path.isAbsolute(relative) || relative.split(/[\\/]/).includes(".."))
+        throw new AppError("verification_matrix_path_invalid", "Matrix reference must remain inside its declared root", 1, { path: relative });
+    const resolved = path.resolve(root, relative);
+    // Retained packet resolution is SQL-only and can run in a settlement writer.
+    // Publication and all new filesystem inputs enforce realpath containment.
+    if (!inspectFilesystem)
+        return resolved;
+    let ancestor = resolved;
+    while (!fs.existsSync(ancestor) && path.dirname(ancestor) !== ancestor)
+        ancestor = path.dirname(ancestor);
+    if (fs.existsSync(ancestor)) {
+        const actual = fs.realpathSync(ancestor), realRoot = fs.realpathSync(root);
+        if (actual !== realRoot && !actual.startsWith(`${realRoot}${path.sep}`))
+            throw new AppError("verification_matrix_path_invalid", "Matrix source escapes its root through a symlink", 1, { path: relative });
+    }
+    return resolved;
+}
+function digest(value) { return crypto.createHash("sha256").update(value).digest("hex"); }
+function compare(a, b) { return a < b ? -1 : a > b ? 1 : 0; }
+function unique(items) { return [...new Set(items)].sort(compare); }
+function slash(value) { return value.split(path.sep).join("/"); }
+function escape(value) { return value.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;").replace(/\|/g, "&#124;").replace(/[\r\n]+/g, "<br>").replace(/`/g, "&#96;"); }
+function canonical(value) { if (Array.isArray(value))
+    return value.map(canonical); if (value && typeof value === "object")
+    return Object.fromEntries(Object.entries(value).sort(([a], [b]) => compare(a, b)).map(([key, item]) => [key, canonical(item)])); return value; }
+function stableJson(value) { return `${JSON.stringify(canonical(value), null, 2)}\n`; }

package/dist/services/version-status.js

@@ -2,7 +2,7 @@ import fs from "node:fs";
 import path from "node:path";
 import { spawnSync } from "node:child_process";
 import { parse as parseYaml } from "yaml";
-const canonicalOnlyFlowNames = ["mb-init.md", "mb-upgrade.md", "mb-distill.md"];
+export const canonicalOnlyFlowNames = Object.freeze(["mb-init.md", "mb-upgrade.md", "mb-distill.md", "mb-audit.md", "review.md"]);
 export function resolveStatusProjectRoot(input) {
     if (input.requestedRoot) {
         const absolute = path.resolve(input.requestedRoot);