@deksden-com/dd-flow-cli 0.9.0-beta.120 → 0.9.0-beta.122

package/dist/services/verification-matrix.js

@@ -0,0 +1,325 @@
+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 } from "./stage-report-renderer.js";
+import { assertRunMutationAllowed } from "./run-recovery.js";
+export const verificationMatrixContract = "dd-flow/verification-matrix@1";
+/** A view of already validated facts: never a gate or a receipt selector. */
+export function buildVerificationMatrix(input) {
+    const sourceCatalog = new Map();
+    for (const source of input.sources) {
+        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) {
+    if (!metadata)
+        return "";
+    return `<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 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 predecessor = input.stage === "plan-review" ? "plan" : input.stage === "code" ? "plan-review" : input.stage === "code-review" ? "code" : input.stage === "merge" ? "code-review" : null;
+    const priorMatrix = input.role === "input" && predecessor ? latestRunVerificationMatrix(context, input.projectId, input.runId, predecessor) : null;
+    if (!skeleton) {
+        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");
+        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) });
+        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 } };
+    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);
+    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);
+        safePath(run.run_root, path.relative(run.run_root, packet.file), false);
+        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 && 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 sourcePackets = matrix.sources.filter(source => source.role.startsWith("plan:") && 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 && 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 => ({ ...item, path: relative(item.path) })) };
+}
+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/vnext-code-review.js

@@ -17,6 +17,7 @@ import { addWorkBatch, prepareWorkBatch, bindStageCoordinatorWork, finishStageCo
 import { withStageSettlement, prepareFlowRunStageAttachment } from "./runs.js";
 import { vnextStageDirectory } from "../domain/stage-catalog.js";
 import { acceptStageReport, prepareStageReport } from "./stage-report-renderer.js";
+import { prepareRunVerificationMatrix, acceptVerificationMatrix, commitVerificationMatrixStart, resumeVerificationMatrix, verificationMatrixInstruction, latestRunVerificationMatrix, publishVerificationMatrix } from "./verification-matrix.js";
 import { applyExternalStageContext, prepareExternalStageContext } from "./stage-context.js";
 import { readFanoutDescriptor, writeFanoutDescriptor } from "./vnext-fanout.js";
 import { stageGraphScope } from "./stage-work-graph.js";
@@ -50,7 +51,7 @@ export function prepareVnextCodeReviewStart(context, input) {
     const common = { projectRoot, project, run, home, root, rootWork, existingPrompt };
     if (prior && fs.existsSync(existingPrompt))
         return { ...common, resumed: true, prior, prompt: fs.readFileSync(existingPrompt, "utf8"), orchestration: readFanoutDescriptor(root) };
-    prepareFlowRunStageAttachment(context, { projectRoot, runId: run.id, stage, dir: stageDir, status: "running", dataSchemaId: "dd-flow/stage-report@1" });
+    const attachment = prepareFlowRunStageAttachment(context, { projectRoot, runId: run.id, stage, dir: stageDir, status: "running", dataSchemaId: "dd-flow/stage-report@1" });
     const mode = effectiveMode(home, run);
     const cycle = reviewCycle(run);
     const codeReportSha256 = sha256File(path.join(home, "05-code", "stage-report.json"));
@@ -61,7 +62,8 @@ export function prepareVnextCodeReviewStart(context, input) {
     const checks = mode.mode === "off" ? [] : acceptedCodeChecks(context, project.id, run.id).map(({ id, purpose }) => ({ id, purpose }));
     for (const name of ["review-context.json", ...(mode.mode === "off" ? ["decision.json"] : ["review-work-batch.json", "fanout.json"])])
         prepareOutputFile(path.join(root, name));
-    return { ...common, resumed: false, mode, cycle, codeReportSha256, groups, batch, items, template, checks };
+    const matrix = mode.mode === "off" ? null : prepareRunVerificationMatrix(context, { projectId: project.id, runId: run.id, stage, role: "input", stageAttempt: attachment.attempt });
+    return { ...common, resumed: false, mode, cycle, codeReportSha256, groups, batch, items, template, checks, matrix };
 }
 export function startVnextCodeReview(context, input, prepared = prepareVnextCodeReviewStart(context, input)) {
     const { projectRoot, project, run, root, rootWork, existingPrompt } = prepared;
@@ -69,6 +71,8 @@ export function startVnextCodeReview(context, input, prepared = prepareVnextCode
     assertStageStartHookEvent(context, { projectId: project.id, eventKey: input.hookEventId, runId: run.id, stage, projectRoot, ...(input.contextSha256 ? { contextSha256: input.contextSha256 } : {}) });
     fs.mkdirSync(root, { recursive: true });
     if (prepared.resumed) {
+        if (effectiveMode(prepared.home, run).mode !== "off")
+            resumeVerificationMatrix(context, project.id, run.id, stage);
         const externalContext = applyExternalStageContext({ stageRoot: root, promptPath: existingPrompt, ...(input.externalContext ? { loaded: input.externalContext } : {}) });
         const binding = bindStageCoordinatorWork(context, { workId: rootWork.work_id, hookEventId: input.hookEventId, stage, promptPath: existingPrompt, resultPath: path.join(root, "stage-report.json"), ...(input.contextSha256 ? { contextSha256: input.contextSha256 } : {}) });
         const prompt = fs.readFileSync(existingPrompt, "utf8");
@@ -76,6 +80,7 @@ export function startVnextCodeReview(context, input, prepared = prepareVnextCode
         return { ok: true, resumed: true, run_id: run.id, stage, stage_status: prepared.prior, id: binding.work_session_id, prompt_path: existingPrompt, worker_prompt_markdown: prompt, ...(externalContext ? { external_context: externalContext } : {}), ...(orchestration ? { orchestration } : {}), next: { finish_command: finishCommand(context, run.id, projectRoot, path.join(root, "decision.json")) } };
     }
     const { mode, cycle, groups, batch, items, template, checks, codeReportSha256 } = prepared;
+    prepareFlowRunStageAttachment(context, { projectRoot, runId: run.id, stage, dir: stageDir, status: "running", dataSchemaId: "dd-flow/stage-report@1" }, true);
     const aspectMapChecksums = mode.mode === "off" ? [] : fs.readdirSync(path.join(run.run_root, "03-plan"), { withFileTypes: true })
         .filter(entry => entry.isDirectory() && fs.existsSync(path.join(run.run_root, "03-plan", entry.name, "aspect-map.json")))
         .map(entry => ({ path: `03-plan/${entry.name}/aspect-map.json`, sha256: sha256File(path.join(run.run_root, "03-plan", entry.name, "aspect-map.json")) }))
@@ -90,18 +95,21 @@ export function startVnextCodeReview(context, input, prepared = prepareVnextCode
         fs.writeFileSync(promptPath, prompt);
         const externalContext = applyExternalStageContext({ stageRoot: root, promptPath, ...(input.externalContext ? { loaded: input.externalContext } : {}) });
         const binding = bindStageCoordinatorWork(context, { workId: rootWork.work_id, hookEventId: input.hookEventId, stage, promptPath, resultPath: path.join(root, "stage-report.json"), ...(input.contextSha256 ? { contextSha256: input.contextSha256 } : {}) });
-        attachFlowRunStage(context, { projectRoot, runId: run.id, stage, dir: stageDir, status: "running", dataSchemaId: "dd-flow/stage-report@1" });
+        const attachmentInput = { projectRoot, runId: run.id, stage, dir: stageDir, status: "running", dataSchemaId: "dd-flow/stage-report@1" };
+        attachFlowRunStage(context, attachmentInput, prepareFlowRunStageAttachment(context, attachmentInput));
         return { ok: true, run_id: run.id, stage, mode: mode.mode, mode_source: mode.source, id: binding.work_session_id, prompt_path: promptPath, worker_prompt_markdown: fs.readFileSync(promptPath, "utf8"), ...(externalContext ? { external_context: externalContext } : {}), next: { finish_command: finishCommand(context, run.id, projectRoot, path.join(root, "decision.json")) } };
     }
     const batchFile = path.join(root, "review-work-batch.json");
     fs.writeFileSync(batchFile, `${JSON.stringify(batch, null, 2)}\n`);
-    const prompt = `${orchestratorPrompt(context, { projectRoot, run, root, rootWork, mode: mode.mode, groups, template, checks })}\n${stageLifecycleInstruction}\n`;
+    const prompt = `${orchestratorPrompt(context, { projectRoot, run, root, rootWork, mode: mode.mode, groups, template, checks })}\n${stageLifecycleInstruction}\n${verificationMatrixInstruction(prepared.matrix?.metadata ?? null, prepared.home, "reviewing whether current evidence proves the accepted obligations")}\n`;
     fs.writeFileSync(promptPath, prompt);
     const externalContext = applyExternalStageContext({ stageRoot: root, promptPath, ...(input.externalContext ? { loaded: input.externalContext } : {}) });
     const binding = bindStageCoordinatorWork(context, { workId: rootWork.work_id, hookEventId: input.hookEventId, stage, promptPath, resultPath: path.join(root, "stage-report.json"), ...(input.contextSha256 ? { contextSha256: input.contextSha256 } : {}) });
     const registered = addWorkBatch(context, { parentWorkId: rootWork.work_id, value: batch, prepared: items, stage, cycle });
     const orchestration = writeFanoutDescriptor(root, { stage, parent_work_id: rootWork.work_id, dispatch: "none", capacity_required: true, scope: stageGraphScope(context, project.id, run.id, stage) });
-    attachFlowRunStage(context, { projectRoot, runId: run.id, stage, dir: stageDir, status: "running", dataSchemaId: "dd-flow/stage-report@1", inputSha256: sha256Value(JSON.stringify({ batch: sha256File(batchFile), aspect_maps: aspectMapChecksums })) });
+    const attachmentInput = { projectRoot, runId: run.id, stage, dir: stageDir, status: "running", dataSchemaId: "dd-flow/stage-report@1", inputSha256: sha256Value(JSON.stringify({ batch: sha256File(batchFile), aspect_maps: aspectMapChecksums })) };
+    const attachment = prepareFlowRunStageAttachment(context, attachmentInput);
+    commitVerificationMatrixStart(context, prepared.matrix, () => attachFlowRunStage(context, attachmentInput, attachment));
     appendFlowRunTimelineEvent(context, project.id, run.id, { type: "code_review_started", work_id: rootWork.work_id, mode: mode.mode, mode_source: mode.source, groups, registered });
     return { ok: true, run_id: run.id, stage, mode: mode.mode, mode_source: mode.source, id: binding.work_session_id, prompt_path: promptPath, worker_prompt_markdown: fs.readFileSync(promptPath, "utf8"), ...(externalContext ? { external_context: externalContext } : {}), orchestration, review: { groups, works: registered }, next: { finish_command: finishCommand(context, run.id, projectRoot, path.join(root, "decision.json")) } };
 }
@@ -208,7 +216,8 @@ export async function finishVnextCodeReview(context, input) {
             fs.writeFileSync(temporary, `${JSON.stringify({ ...reviewContext, accepted_decision: decision }, null, 2)}\n`);
             fs.renameSync(temporary, contextFile);
             const repair = addVnextCodeReviewRepair(context, { projectRoot, runId: run.id, findingIds: fixIds, checkRefsByFinding, decisionReasonsByFinding: Object.fromEntries(canonical.decision.findings.map((item) => [item.finding_ref, item.reason])), objective: `Resolve accepted CODE-REVIEW findings: ${fixIds.join(", ")}` });
-            return { ok: true, run_id: run.id, stage, outcome: "repair_required", repair, instruction: "The repair Work is already registered: do not invoke its start_command in this coordinator Session. End this Turn so the controller can launch it in a fresh child Session. When it completes, invoke next.finish_command; this review cycle uses the decision already accepted by the runtime.", next: { finish_command: finishCommand(context, run.id, projectRoot, decisionFile) } };
+            const retained = latestRunVerificationMatrix(context, project.id, run.id, stage, "input");
+            return { ok: true, run_id: run.id, stage, outcome: "repair_required", repair, ...(retained ? { verification_matrix: retained.metadata } : {}), instruction: `The repair Work is already registered: do not invoke its start_command in this coordinator Session. End this Turn so the controller can launch it in a fresh child Session. When it completes, invoke next.finish_command; this review cycle uses the decision already accepted by the runtime.\n${verificationMatrixInstruction(retained?.metadata ?? null, home, "the accepted review decision and repair")}`, next: { finish_command: finishCommand(context, run.id, projectRoot, decisionFile) } };
         }
         repairs = reviewRepairWorks(context, project.id, run.id, root, cycle);
         const incompleteRepairs = repairs.filter((work) => work.status !== "completed");
@@ -224,16 +233,21 @@ export async function finishVnextCodeReview(context, input) {
         appendFlowRunTimelineEvent(context, project.id, run.id, { type: "check_retry_requested", check_receipt_id: input.retryCheckId, stage, reason: input.retryReason ?? "operator retry" });
     }
     const receipts = await runCodeChecks(context, { projectId: project.id, runId: run.id, runHome: home, workspaceRoot: run.workspace_root, artifactDir: stageDir, scope: "aggregate", checks: finalChecks, ...(input.retryCheckId ? { retryReceiptId: input.retryCheckId, retryReason: input.retryReason } : {}), ...(input.progress ? { progress: input.progress } : {}) });
+    const matrix = prepareRunVerificationMatrix(context, { projectId: project.id, runId: run.id, stage, role: "output", receipts, semanticFile: decisionFile });
     const failed = receipts.filter((receipt) => receipt.status !== "passed");
-    if (failed.length)
+    if (failed.length) {
+        context.db.writeTransaction(() => acceptVerificationMatrix(context, matrix));
+        publishVerificationMatrix(context, matrix);
         throw new AppError("code_review_gate_failed", "CODE-REVIEW repair changed the project but the aggregate gate failed", 2, {
             failures: failed,
             outcome: "repair_required",
             retry_after_workspace_change: true,
             workspace_fingerprint: failed[0].workspace_fingerprint,
             continuation: registerAggregateCodeRepair(context, { projectRoot, runId: run.id, stage, failures: failed, checks: finalChecks, generation }),
-            instruction: "Repair Work is already registered. End this Turn so the controller can launch a fresh child; after it finishes, repeat finish with the already accepted review decision. Do not redo review."
+            ...(matrix ? { verification_matrix: matrix.metadata } : {}),
+            instruction: `Repair Work is already registered. End this Turn so the controller can launch a fresh child; after it finishes, repeat finish with the already accepted review decision. Do not redo review.\n${verificationMatrixInstruction(matrix?.metadata ?? null, home, "the current aggregate failures and repair")}`
         });
+    }
     const stopTarget = executionStopTarget(run);
     const nextAction = stopTarget === "merge_completed" ? "start_merge" : "code_review_completed";
     const now = context.now();
@@ -245,6 +259,8 @@ export async function finishVnextCodeReview(context, input) {
     let mergeRequest = null;
     assertRunMutationAllowed(context, project.id, run.id, generation);
     const prepareMerge = nextAction === "start_merge" ? prepareVnextMergeRequest(context, { projectRoot, runId: run.id, acceptedPaths }) : null;
+    if (matrix)
+        Object.assign(report.semantic, { verification_matrix: matrix.metadata });
     const preparedReport = prepareStageReport(report);
     const completionInput = { projectRoot, runId: run.id, stage, status: "done", data: "stage-report.json", dataSchemaId: "dd-flow/stage-report@1", report: "stage-report.md", stageReport: "stage-report.html", dataSha256: preparedReport.sha256, git: report.mechanical.git };
     withStageSettlement(context, () => {
@@ -256,6 +272,7 @@ export async function finishVnextCodeReview(context, input) {
         }
         mergeRequest = prepareMerge?.() ?? null;
         const preparedCompletion = prepareFlowRunStageCompletion(context, completionInput);
+        acceptVerificationMatrix(context, matrix);
         acceptStageReport(context, { projectId: project.id, runId: run.id, stage, root, prepared: preparedReport });
         completeFlowRunStage(context, completionInput, preparedCompletion);
         appendFlowRunTimelineEvent(context, project.id, run.id, { type: "code_review_completed", work_id: rootWork.work_id, outcome });