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

package/dist/services/descriptor-stage-start.js

@@ -0,0 +1,175 @@
+import path from "node:path";
+import { createHash } from "node:crypto";
+import { Ajv2020 } from "ajv/dist/2020.js";
+import { Ajv } from "ajv/dist/ajv.js";
+import { AppError } from "../shared/errors.js";
+import { requireProjectByRoot } from "./projects.js";
+import { resolveProjectRoot } from "../storage/paths.js";
+import { readFlowRunExecutionBundle, assertPreparedRunBundleSqlAuthority, prepareFlowRunStageAttachment, attachFlowRunStage } from "./runs.js";
+import { acceptStagePacket, prepareStagePacket, publishStagePacket, readAcceptedStageData } from "./stage-report-renderer.js";
+import { appendAudit } from "./audit.js";
+import { prepareMemoryOrdinaryDefaults } from "./memory-ordinary-defaults.js";
+import { readMemoryUpgradeEvidence, readIssuedMemoryUpgradeTarget } from "./memory-upgrade-evidence.js";
+import { observeMemoryNormalFlowEntryDiagnostic } from "./memory-normal-flow-entry.js";
+import { readDescriptorStageInput } from "./descriptor-stage-coordinator.js";
+import { readMemoryFinishGitSelection } from "./memory-finish-integration.js";
+import { readMemoryInitGitPolicy } from "./memory-init-git-policy.js";
+const hash = (bytes) => createHash("sha256").update(bytes).digest("hex");
+const event = "flow_run.descriptor_stage_start";
+function refuse(reason) { throw new AppError("descriptor_stage_start_invalid", "Stage start lacks exact retained input custody", 1, { reason, effect: "no_effect" }); }
+/** Atomic generic stage entry; Work/Session launch remains the handler's responsibility. */
+export class PreparedDescriptorStageStart {
+    #scope;
+    #bundle;
+    #packet;
+    #receipt;
+    #attachment;
+    #predecessor;
+    constructor(scope, bundle, packet, receipt, attachment, predecessor) {
+        this.#scope = scope;
+        this.#bundle = bundle;
+        this.#packet = packet;
+        this.#receipt = receipt;
+        this.#attachment = attachment;
+        this.#predecessor = predecessor;
+        Object.freeze(this);
+    }
+    static prepare(context, input) {
+        if (!(input.bytes instanceof Uint8Array) || input.bytes.byteLength > 1024 * 1024)
+            refuse("unbounded_input");
+        const project = requireProjectByRoot(context, resolveProjectRoot(input.projectRoot));
+        const bundle = readFlowRunExecutionBundle(context, input);
+        if (!bundle)
+            refuse("frozen_bundle_required");
+        return context.db.readSnapshot(() => {
+            const scope = { projectId: project.id, runId: input.runId, stage: input.stage };
+            const run = assertPreparedRunBundleSqlAuthority(context, scope, bundle), declared = bundle.descriptor.stage(input.stage);
+            if (!run.run_root)
+                refuse("run_root_missing");
+            const prior = context.db.all("SELECT payload_json FROM audit_events WHERE project_id=? AND event_type=? AND json_extract(payload_json,'$.run_id')=? AND json_extract(payload_json,'$.stage')=? LIMIT 2", [project.id, event, input.runId, input.stage]);
+            if (prior.length > 1)
+                refuse("ambiguous_start_receipt");
+            const retained = prior[0] ? JSON.parse(prior[0].payload_json) : null;
+            const attachment = retained ? null : prepareFlowRunStageAttachment(context, { projectRoot: input.projectRoot, runId: input.runId, stage: input.stage, dir: declared.directory, status: "running" });
+            const attempt = retained?.attempt ?? attachment.attempt;
+            if (typeof attempt !== "string" || !/^try-[0-9]{3,}$/.test(attempt))
+                refuse("invalid_attempt");
+            const index = JSON.parse(run.index_json), target = index.stage_runs?.find((stage) => stage.stage === input.stage);
+            const previous = index.stage_runs?.filter((stage) => stage.status === "done" && (!target || stage.order < target.order))
+                .sort((a, b) => b.order - a.order)[0];
+            const accepted = previous ? readAcceptedStageData(context, { ...scope, stage: previous.stage }) : null;
+            if (accepted) {
+                const schema = JSON.parse(bundle.descriptor.stageBlob(previous.stage, "result_schema").toString("utf8"));
+                const ajv = schema.$schema?.includes("2020-12") ? new Ajv2020({ strict: false, validateFormats: false }) : new Ajv({ strict: false, validateFormats: false });
+                if (schema.$id && accepted.data_schema_id !== schema.$id || !ajv.compile(schema)(JSON.parse(accepted.bytes.toString("utf8"))))
+                    refuse("invalid_predecessor_result");
+            }
+            const predecessor = accepted ? { stage: previous.stage, authority: accepted.authority_sha256 } : null;
+            const frozen = bundle.execution.snapshot().scope;
+            const upgradeEvidence = bundle.descriptor.descriptor.id === "mb-upgrade" ? readMemoryUpgradeEvidence(context, { requestId: frozen.requestId, projectRoot: frozen.projectRoot, workspaceRoot: frozen.workspace }) : null;
+            const upgradeTarget = upgradeEvidence ? readIssuedMemoryUpgradeTarget(context, { requestId: frozen.requestId, projectRoot: frozen.projectRoot, workspaceRoot: frozen.workspace }, project.id) : null;
+            let ordinaryDefaults;
+            if (bundle.descriptor.descriptor.id === "mb-init" && input.stage === "compose"
+                || bundle.descriptor.descriptor.id === "mb-upgrade" && ["diff-analysis", "upgrade"].includes(input.stage)) {
+                if (retained) {
+                    const rows = context.db.all("SELECT payload_json FROM audit_events WHERE project_id=? AND event_type='flow_run.stage_packet' AND json_extract(payload_json,'$.run_id')=? AND json_extract(payload_json,'$.file')=? LIMIT 2", [project.id, input.runId, retained.file]);
+                    if (rows.length !== 1)
+                        refuse("input_packet_custody_missing");
+                    ordinaryDefaults = JSON.parse(Buffer.from(JSON.parse(rows[0].payload_json).base64, "base64").toString("utf8")).ordinary_defaults;
+                }
+                else if (bundle.descriptor.descriptor.id === "mb-upgrade" && input.stage === "upgrade") {
+                    // Accepted analysis owns the missing paths before authoring is allocated.
+                    ordinaryDefaults = readDescriptorStageInput(context, { ...scope, stage: "diff-analysis" }, bundle, true, true).input.ordinary_defaults;
+                }
+                else {
+                    const selected = bundle.execution.snapshot().scope;
+                    const requestScope = { requestId: selected.requestId, projectRoot: selected.projectRoot, workspaceRoot: selected.workspace };
+                    const hasInitPolicy = bundle.descriptor.descriptor.id === "mb-init" && readMemoryInitGitPolicy(context, requestScope) !== null;
+                    const gitSelection = bundle.descriptor.descriptor.id === "mb-upgrade" || hasInitPolicy ? readMemoryFinishGitSelection(context, scope, bundle) : null;
+                    const targetContract = upgradeTarget?.index.entries.find(entry => entry.path === ".memory-bank/dd-flow/flow-contract.json");
+                    const contractBytes = targetContract ? upgradeTarget.artifacts.find(file => file.path === targetContract.retained.path) : undefined;
+                    if (bundle.descriptor.descriptor.id === "mb-upgrade" && !contractBytes)
+                        refuse("issued_target_contract_missing");
+                    const targetTemplate = contractBytes ? JSON.parse(Buffer.from(contractBytes.base64, "base64").toString("utf8")).workspace?.feature_branch_template : undefined;
+                    ordinaryDefaults = prepareMemoryOrdinaryDefaults(context, selected.workspace, bundle.execution.settings.root_profile, requestScope, gitSelection?.selection.integrationBranch, targetTemplate);
+                }
+            }
+            let ordinaryEntry;
+            if (upgradeEvidence && input.stage === "verify") {
+                if (retained) {
+                    const rows = context.db.all("SELECT payload_json FROM audit_events WHERE project_id=? AND event_type='flow_run.stage_packet' AND json_extract(payload_json,'$.run_id')=? AND json_extract(payload_json,'$.file')=? LIMIT 2", [project.id, input.runId, retained.file]);
+                    if (rows.length !== 1)
+                        refuse("input_packet_custody_missing");
+                    ordinaryEntry = JSON.parse(Buffer.from(JSON.parse(rows[0].payload_json).base64, "base64").toString("utf8")).ordinary_entry;
+                }
+                else
+                    ordinaryEntry = observeMemoryNormalFlowEntryDiagnostic(context, frozen.workspace);
+            }
+            const bytes = Buffer.from(JSON.stringify({ schema_id: "dd-flow/descriptor-stage-input@1", run_id: input.runId, stage: input.stage, attempt,
+                bundle_sha256: bundle.sha256, descriptor_sha256: bundle.descriptor.sha256, execution_sha256: bundle.execution.sha256,
+                predecessor: accepted ? { stage: previous.stage, result: accepted.result, input_sha256: accepted.input_sha256 ?? null, authority_sha256: accepted.authority_sha256 } : null,
+                payload_base64: Buffer.from(input.bytes).toString("base64"), ...(ordinaryDefaults !== undefined ? { ordinary_defaults: ordinaryDefaults } : {}),
+                ...(upgradeEvidence ? { upgrade_baseline: upgradeEvidence.reference } : {}),
+                ...(ordinaryEntry !== undefined ? { ordinary_entry: ordinaryEntry } : {}),
+                ...(upgradeTarget ? { upgrade_target: upgradeTarget.reference } : {}) }));
+            if (bytes.length > 1024 * 1024)
+                refuse("unbounded_input_packet");
+            const file = path.join(run.run_root, declared.directory, "stage-input.json");
+            const packet = prepareStagePacket(file, bytes);
+            const receipt = { schema_id: "dd-flow/descriptor-stage-start@1", run_id: input.runId, stage: input.stage, attempt, bundle_sha256: bundle.sha256, input_sha256: hash(bytes), file };
+            if (retained && JSON.stringify(retained) !== JSON.stringify(receipt))
+                refuse("changed_start_request");
+            const prepared = new PreparedDescriptorStageStart(scope, bundle, packet, receipt, attachment, predecessor);
+            if (retained)
+                prepared.assertCustody(context);
+            return prepared;
+        });
+    }
+    assertCustody(context) {
+        this.assertPredecessor(context);
+        const run = assertPreparedRunBundleSqlAuthority(context, this.#scope, this.#bundle), index = JSON.parse(run.index_json);
+        const stage = index.stage_runs?.find((value) => value.stage === this.#scope.stage);
+        if (stage?.attempt !== this.#receipt.attempt || stage.input_sha256 !== this.#receipt.input_sha256 || stage.dir !== this.#bundle.descriptor.stage(this.#scope.stage).directory)
+            refuse("stage_input_changed");
+        const packets = context.db.all("SELECT payload_json FROM audit_events WHERE project_id=? AND event_type='flow_run.stage_packet' AND json_extract(payload_json,'$.run_id')=? AND json_extract(payload_json,'$.stage')=? AND json_extract(payload_json,'$.file')=? LIMIT 2", [this.#scope.projectId, this.#scope.runId, this.#scope.stage, this.#packet.file]);
+        if (packets.length !== 1)
+            refuse("input_packet_custody_missing");
+        const packet = JSON.parse(packets[0].payload_json);
+        if (packet.attempt !== this.#receipt.attempt || packet.sha256 !== this.#packet.sha256 || packet.base64 !== this.#packet.bytes.toString("base64"))
+            refuse("input_packet_custody_changed");
+    }
+    assertPredecessor(context) {
+        if (this.#predecessor && readAcceptedStageData(context, { ...this.#scope, stage: this.#predecessor.stage }).authority_sha256 !== this.#predecessor.authority)
+            refuse("predecessor_changed");
+    }
+    apply(context, assertHandlerCustody) {
+        const retainedRun = assertPreparedRunBundleSqlAuthority(context, this.#scope, this.#bundle);
+        const current = readFlowRunExecutionBundle(context, { projectRoot: retainedRun.project_root, runId: this.#scope.runId });
+        if (!current || current.sha256 !== this.#bundle.sha256)
+            refuse("physical_bundle_changed");
+        const changed = context.db.writeTransaction(() => {
+            assertPreparedRunBundleSqlAuthority(context, this.#scope, this.#bundle);
+            assertHandlerCustody?.(context);
+            this.assertPredecessor(context);
+            const prior = context.db.all("SELECT payload_json FROM audit_events WHERE project_id=? AND event_type=? AND json_extract(payload_json,'$.run_id')=? AND json_extract(payload_json,'$.stage')=? LIMIT 2", [this.#scope.projectId, event, this.#scope.runId, this.#scope.stage]);
+            if (prior.length) {
+                if (prior.length !== 1 || prior[0].payload_json !== JSON.stringify(this.#receipt))
+                    refuse("start_receipt_changed");
+                this.assertCustody(context);
+                return false;
+            }
+            if (!this.#attachment)
+                refuse("start_receipt_missing");
+            attachFlowRunStage(context, { projectRoot: this.#attachment.run.project_root, runId: this.#scope.runId, stage: this.#scope.stage,
+                dir: this.#bundle.descriptor.stage(this.#scope.stage).directory, status: "running", inputSha256: this.#packet.sha256 }, this.#attachment);
+            acceptStagePacket(context, { ...this.#scope, prepared: this.#packet });
+            appendAudit(context, { projectId: this.#scope.projectId, eventType: event, payload: this.#receipt });
+            this.assertCustody(context);
+            return true;
+        }, "descriptorStage.start");
+        publishStagePacket(context, this.#scope.projectId, this.#scope.runId, this.#scope.stage, this.#packet.file);
+        const run = assertPreparedRunBundleSqlAuthority(context, this.#scope, this.#bundle);
+        const status = JSON.parse(run.index_json).stage_runs.find((value) => value.stage === this.#scope.stage)?.status;
+        return { changed, stage: this.#scope.stage, status: status, run_status: run.status, attempt: this.#receipt.attempt, input_sha256: this.#packet.sha256, input_path: this.#packet.file };
+    }
+}

package/dist/services/diagnostic-evidence.js

@@ -0,0 +1,73 @@
+import fs from "node:fs";
+import path from "node:path";
+import { createHash } from "node:crypto";
+import { AppError } from "../shared/errors.js";
+const refuse = (reason, details = {}) => {
+    const correctable = ["invalid_source_reference", "source_hash_changed", "source_missing"].includes(reason);
+    const message = reason === "source_hash_changed"
+        ? "Citation sha256 does not match its assigned snapshot file; correct the result using source_path and actual_source_sha256, then retry. No result was accepted."
+        : reason === "source_missing" ? "Citation is absent from the original project snapshot. Cite an existing project source instead; generated .dd-flow/review-evidence observations are not project sources. For a missing link target cite the existing referring document and record the absence as a limitation. Correct the result, then retry; no result was accepted."
+            : correctable ? "Use snapshot-relative evidence paths with forward slashes (for example src/index.ts), without absolute paths, dot segments or .git; sha256 must be 64 lowercase hex characters"
+                : "Diagnostic evidence does not match the assigned snapshot and coverage";
+    throw new AppError("diagnostic_evidence_invalid", message, 2, { ...details, reason, effect: "no_effect", ...(correctable ? { phase: "prepare", recoverable: true } : {}) });
+};
+/** Run after schema validation; schema-shaped hashes are not evidence by themselves. */
+export function verifyDiagnosticSources(root, sources) {
+    const canonicalRoot = fs.realpathSync(root), seen = new Map();
+    for (const source of sources) {
+        if (!source.path || source.path.length > 4096 || source.path.includes("\\") || path.posix.isAbsolute(source.path) || path.win32.isAbsolute(source.path)
+            || source.path.split("/").some(part => !part || part === "." || part === ".." || part === ".git")
+            || !/^[a-f0-9]{64}$/.test(source.sha256))
+            refuse("invalid_source_reference");
+        if (seen.has(source.path) && seen.get(source.path) !== source.sha256)
+            refuse("conflicting_source_reference");
+        seen.set(source.path, source.sha256);
+        let bytes;
+        try {
+            const file = fs.realpathSync(path.join(canonicalRoot, source.path)), relative = path.relative(canonicalRoot, file);
+            if (relative === ".." || relative.startsWith(".." + path.sep) || path.isAbsolute(relative))
+                refuse("escaping_source_reference");
+            const stat = fs.statSync(file);
+            if (!stat.isFile() || stat.size > 16 * 1024 * 1024)
+                refuse("unbounded_source_reference");
+            bytes = fs.readFileSync(file);
+        }
+        catch (error) {
+            if (error instanceof AppError)
+                throw error;
+            if (["ENOENT", "ENOTDIR"].includes(error.code ?? "")) {
+                return refuse("source_missing", { source_path: source.path });
+            }
+            return refuse("source_unavailable");
+        }
+        const actual = createHash("sha256").update(bytes).digest("hex");
+        if (actual !== source.sha256)
+            refuse("source_hash_changed", {
+                source_path: source.path, provided_source_sha256: source.sha256, actual_source_sha256: actual
+            });
+    }
+}
+export function verifyDiagnosticCoverage(root, baseline, coverage) {
+    const ids = coverage.map(value => value.id);
+    if (new Set(ids).size !== ids.length || ids.length !== baseline.length || baseline.some(id => !ids.includes(id)))
+        refuse("incomplete_aspect_coverage");
+    for (const value of coverage) {
+        if (!value.reason.trim())
+            refuse("missing_applicability_reason");
+        verifyDiagnosticSources(root, value.evidence);
+    }
+}
+/** Each independent critic must account for every candidate, including rejected findings. */
+export function verifyDiagnosticCritic(root, candidates, decisions) {
+    const ids = candidates.map(value => value.id), reviewed = decisions.map(value => value.finding_id);
+    if (new Set(ids).size !== ids.length || new Set(reviewed).size !== reviewed.length
+        || ids.length !== reviewed.length || ids.some(id => !reviewed.includes(id)))
+        refuse("incomplete_critic_coverage");
+    for (const candidate of candidates) {
+        if (!candidate.evidence.length)
+            refuse("finding_without_evidence");
+        verifyDiagnosticSources(root, candidate.evidence);
+    }
+    for (const decision of decisions)
+        verifyDiagnosticSources(root, decision.evidence);
+}

package/dist/services/diagnostic-report-publication.js

@@ -0,0 +1,72 @@
+import fs from "node:fs";
+import path from "node:path";
+import { AppError } from "../shared/errors.js";
+import { hybridDigest } from "./hybrid-contracts.js";
+import { appendAudit } from "./audit.js";
+import { prepareStagePacket, acceptStagePacket } from "./stage-report-renderer.js";
+import { publishImmutableInput } from "../storage/immutable-input.js";
+import { renderDiagnosticReport } from "./diagnostic-report.js";
+function refuse(reason) { throw new AppError("diagnostic_report_publication_invalid", "Diagnostic report publication requires its owned stage and exact bytes", 2, { reason, effect: "no_effect" }); }
+/** Files are immutable candidates until retain is called in the Stage acceptance
+ * writer. Interrupted publication can replay before any terminal acceptance. */
+export function prepareDiagnosticReportPublication(context, scope, report) {
+    const run = context.db.get("SELECT run_root,index_json FROM runs WHERE project_id=? AND id=?", [scope.projectId, scope.runId]);
+    const stage = run ? JSON.parse(run.index_json).stage_runs.find((value) => value.stage === scope.stage) : null;
+    if (!run?.run_root || scope.stage !== "report" || stage?.attempt !== scope.attempt || stage.input_sha256 !== scope.inputSha256
+        || report.run.id !== scope.runId || !["running", "done"].includes(stage.status))
+        refuse("foreign_stage");
+    const directory = path.join(run.run_root, stage.dir);
+    if (fs.realpathSync(run.run_root) !== run.run_root || fs.realpathSync(directory) !== directory
+        || !directory.startsWith(run.run_root + path.sep))
+        refuse("unsafe_report_directory");
+    const rendered = renderDiagnosticReport(report);
+    const packets = Object.entries(rendered).map(([kind, bytes]) => {
+        if (bytes.length > 4 * 1024 * 1024)
+            refuse("report_exceeds_bound");
+        const suffix = kind === "markdown" ? "md" : kind;
+        const file = path.join(directory, `diagnostic-report.${suffix}`);
+        try {
+            if (!fs.lstatSync(file).isFile() || fs.lstatSync(file).isSymbolicLink())
+                refuse("unsafe_report_file");
+        }
+        catch (error) {
+            if (error.code !== "ENOENT")
+                throw error;
+        }
+        return prepareStagePacket(file, bytes);
+    });
+    const manifest = { schema_id: "dd-flow/diagnostic-report-publication@1", run_id: scope.runId, stage: scope.stage, attempt: scope.attempt,
+        input_sha256: scope.inputSha256, artifacts: packets.map(packet => ({ path: path.relative(run.run_root, packet.file).split(path.sep).join("/"), sha256: packet.sha256 })) };
+    const retained = (writer) => writer.db.all("SELECT payload_json FROM audit_events WHERE project_id=? AND event_type='diagnostic.report' AND json_extract(payload_json,'$.run_id')=? AND json_extract(payload_json,'$.attempt')=? LIMIT 2", [scope.projectId, scope.runId, scope.attempt]);
+    return {
+        manifest,
+        publish() {
+            if (fs.realpathSync(directory) !== directory)
+                refuse("report_directory_changed");
+            for (const packet of packets)
+                publishImmutableInput(packet.file, packet.bytes, "diagnostic_report_conflict");
+        },
+        /** SQL-only. The existing packet ledger retains recoverable authoritative
+         * bytes in the same transaction as Stage completion. */
+        retain(writer) {
+            const rows = retained(writer);
+            if (rows.length) {
+                if (rows.length !== 1 || hybridDigest(JSON.parse(rows[0].payload_json)) !== hybridDigest(manifest))
+                    refuse("report_custody_changed");
+                for (const packet of packets) {
+                    const records = writer.db.all("SELECT payload_json FROM audit_events WHERE project_id=? AND event_type='flow_run.stage_packet' AND json_extract(payload_json,'$.run_id')=? AND json_extract(payload_json,'$.stage')=? AND json_extract(payload_json,'$.attempt')=? AND json_extract(payload_json,'$.file')=? LIMIT 2", [scope.projectId, scope.runId, scope.stage, scope.attempt, packet.file]);
+                    if (records.length !== 1 || Buffer.byteLength(records[0].payload_json) > 6 * 1024 * 1024
+                        || hybridDigest(JSON.parse(records[0].payload_json)) !== hybridDigest({ run_id: scope.runId, stage: scope.stage,
+                            attempt: scope.attempt, file: packet.file, sha256: packet.sha256, base64: packet.bytes.toString("base64") }))
+                        refuse("report_packet_custody_changed");
+                }
+                return;
+            }
+            if (stage.status !== "running")
+                refuse("report_receipt_missing");
+            for (const packet of packets)
+                acceptStagePacket(writer, { ...scope, prepared: packet });
+            appendAudit(writer, { projectId: scope.projectId, eventType: "diagnostic.report", payload: manifest });
+        }
+    };
+}

package/dist/services/diagnostic-report.js

@@ -0,0 +1,67 @@
+import { AppError } from "../shared/errors.js";
+import { hybridDigest } from "./hybrid-contracts.js";
+import { collectDiagnosticCandidates } from "./diagnostic-work-results.js";
+function refuse(reason) { throw new AppError("diagnostic_report_invalid", "Diagnostic report requires the reviewed candidate and critic registers", 2, { reason, effect: "no_effect" }); }
+/** Projection only. The handler separately owns source checks, physical critic
+ * independence, SQL custody, publication and terminal RUN settlement. */
+export function prepareDiagnosticReport(result, analysis, critics) {
+    if (result.stage !== "report" || !critics.length
+        || [...analysis, ...critics].some(work => work.workId !== work.result.work_id || work.result.run_id !== result.run_id || work.result.flow_id !== result.flow_id))
+        refuse("foreign_work");
+    const candidates = collectDiagnosticCandidates(analysis);
+    if (hybridDigest(candidates.findings) !== hybridDigest(result.details.findings))
+        refuse("candidate_register_changed");
+    for (const critic of critics) {
+        const ids = critic.result.decisions.map(value => value.finding_id);
+        if (critic.result.stage !== "review" || critic.result.findings.length || new Set(ids).size !== ids.length
+            || ids.length !== candidates.findings.length || candidates.findings.some(value => !ids.includes(value.id)))
+            refuse("incomplete_critic");
+    }
+    const decisions = new Map(result.details.decisions.map(value => [value.finding_id, value]));
+    if (decisions.size !== candidates.findings.length || result.details.decisions.length !== decisions.size
+        || candidates.findings.some(value => !decisions.has(value.id)))
+        refuse("incomplete_resolution");
+    const findings = candidates.findings.map((finding, index) => ({ ...finding, origin: candidates.origins[index],
+        resolution: decisions.get(finding.id),
+        critic_decisions: critics.map(work => ({ work_id: work.workId, decision: work.result.decisions.find(value => value.finding_id === finding.id) })) }));
+    const incomplete = result.details.coverage.some(value => value.applicability === "blocked" || value.applicability === "out_of_scope")
+        || result.details.missing_expected_sources.length > 0 || result.details.limitations.length > 0;
+    const accepted = findings.filter(value => !["rejected", "duplicate"].includes(value.resolution.disposition));
+    const sourceMap = new Map();
+    for (const source of [...result.details.sources, ...result.details.coverage.flatMap(value => value.evidence),
+        ...analysis.flatMap(value => value.result.sources), ...critics.flatMap(value => value.result.sources),
+        ...findings.flatMap(value => [...value.evidence, ...value.resolution.evidence, ...value.critic_decisions.flatMap(critic => critic.decision.evidence)])]) {
+        if (sourceMap.has(source.path) && sourceMap.get(source.path).sha256 !== source.sha256)
+            refuse("conflicting_source_versions");
+        sourceMap.set(source.path, structuredClone(source));
+    }
+    return {
+        schema_id: "dd-flow/diagnostic-report@1",
+        run: { id: result.run_id, flow_id: result.flow_id, snapshot_sha256: result.snapshot_sha256 },
+        summary: result.summary, review_focus: structuredClone(result.details.focus), source_map: [...sourceMap.values()],
+        aspect_coverage: structuredClone(result.details.coverage),
+        critic_pass: critics.map(work => ({ work_id: work.workId, role: work.result.aspect_id, summary: work.result.summary,
+            semantic_sha256: hybridDigest(work.result), decisions: structuredClone(work.result.decisions), limitations: [...work.result.limitations] })),
+        findings_register: findings,
+        conformance_summary: { assessment: incomplete ? "incomplete" : accepted.length ? "findings" : "no_accepted_findings_in_selected_scope",
+            accepted_findings: accepted.length, rejected_or_duplicate_findings: findings.length - accepted.length,
+            applicable_aspects: result.details.coverage.filter(value => value.applicability === "applicable").length,
+            blocked_aspects: result.details.coverage.filter(value => value.applicability === "blocked").length,
+            missing_expected_sources: [...result.details.missing_expected_sources] },
+        review_fix_recommendation: { authorization: "not_granted", candidate_ids: findings.filter(value => value.resolution.disposition === "review_fix_candidate").map(value => value.id) },
+        deferrals: { authorization: "not_granted", candidate_ids: findings.filter(value => value.resolution.disposition === "def_candidate").map(value => value.id),
+            observed_sources: [...sourceMap.values()].filter(value => /(?:^|\/)DEF(?:-MBU)?-[^/]+/.test(value.path)) },
+        limitations: [...result.details.limitations],
+        dashboard_links: critics.map(work => ({ work_id: work.workId, result: `run://${result.run_id}/works/${work.workId}/result.json` }))
+    };
+}
+/** HTML embeds exactly the authoritative JSON value; untrusted prose is text,
+ * never HTML or executable script. Markdown remains a compact companion. */
+export function renderDiagnosticReport(report) {
+    const json = Buffer.from(JSON.stringify(report, null, 2) + "\n");
+    const escape = (text) => text.replace(/[&<>"']/g, value => ({ "&": "&amp;", "<": "&lt;", ">": "&gt;", '"': "&quot;", "'": "&#39;" })[value]);
+    const embedded = json.toString("utf8").replace(/</g, "\\u003c").replace(/>/g, "\\u003e").replace(/&/g, "\\u0026");
+    const markdown = Buffer.from(`# ${report.run.flow_id} · ${report.run.id}\n\n${report.summary}\n\nAssessment: ${report.conformance_summary.assessment}\n\n${report.findings_register.length} findings retained; ${report.critic_pass.length} independent critic passes.\n\nAuthoritative data: diagnostic-report.json\n`);
+    const html = Buffer.from(`<!doctype html><html lang="en"><meta charset="utf-8"><title>${escape(report.run.flow_id)} · ${escape(report.run.id)}</title><body><h1>${escape(report.review_focus.title)}</h1><p>${escape(report.summary)}</p><p>${escape(report.conformance_summary.assessment)}</p><h2>Coverage</h2><ul>${report.aspect_coverage.map(value => `<li>${escape(value.id)}: ${escape(value.applicability)} — ${escape(value.reason)}</li>`).join("")}</ul><h2>Findings</h2><pre>${escape(JSON.stringify(report.findings_register, null, 2))}</pre><script id="diagnostic-report-data" type="application/json">${embedded}</script></body></html>\n`);
+    return { json, markdown, html };
+}

package/dist/services/diagnostic-run-bundle.js

@@ -0,0 +1,74 @@
+import { createHash } from "node:crypto";
+import { AppError } from "../shared/errors.js";
+import { isDiagnosticFlow } from "../domain/diagnostic-flows.js";
+import { PreparedInstalledFlowSource } from "./installed-flow-source.js";
+import { FrozenGenericExecution } from "./generic-execution.js";
+import { AdmittedFrozenEngine } from "./frozen-engine.js";
+import { RetainedExecutionBundle } from "./execution-bundles.js";
+import { readDiagnosticSnapshot } from "./diagnostic-snapshot.js";
+import { requireProjectByRoot } from "./projects.js";
+import { nextDescriptorRunId } from "./descriptor-run-start.js";
+import { bundledHandlerContext } from "./stage-handlers.js";
+import { hybridDigest } from "./hybrid-contracts.js";
+const bytes = (value) => Buffer.from(JSON.stringify(value));
+const hash = (value) => createHash("sha256").update(value).digest("hex");
+function refuse(reason) { throw new AppError("diagnostic_run_bundle_invalid", "Diagnostic bundle requires its frozen source, execution and snapshot", 2, { reason, effect: "no_effect" }); }
+/** Initial construction only. Retry after allocation restores the retained RUN
+ * bundle, never current operator settings/canon. boundAt belongs to the request. */
+export function prepareDiagnosticRunBundle(context, input) {
+    if (!(input.source instanceof PreparedInstalledFlowSource) || !(input.execution instanceof FrozenGenericExecution)
+        || !(input.engine instanceof AdmittedFrozenEngine) || !Number.isFinite(Date.parse(input.boundAt)))
+        refuse("unprepared_selection");
+    const frozen = input.execution.snapshot(), flowId = frozen.settings.flow_id;
+    if (!isDiagnosticFlow(flowId))
+        refuse("diagnostic_flow_required");
+    const project = requireProjectByRoot(context, frozen.scope.projectRoot);
+    const snapshot = readDiagnosticSnapshot(context, { projectId: project.id, projectRoot: frozen.scope.projectRoot,
+        sourceRoot: frozen.scope.projectRoot, requestId: frozen.scope.requestId, flowId });
+    if (!snapshot || snapshot.root !== frozen.scope.workspace)
+        refuse("snapshot_selection_changed");
+    input.source.revalidate();
+    const flow = input.source.resolveRegisteredFlow();
+    if (flow.descriptor.id !== flowId || flow.sha256 !== frozen.settings.descriptor_sha256)
+        refuse("flow_selection_changed");
+    input.engine.admitDiagnosticFlow(input.source, flowId);
+    const manifest = input.engine.manifest(), checksum = manifest.integrity.checksum;
+    if (typeof checksum !== "string")
+        refuse("engine_identity_missing");
+    const runId = nextDescriptorRunId(context, { projectRoot: frozen.scope.projectRoot, requestId: frozen.scope.requestId, slug: flowId });
+    const binding = { schema_id: "dd-flow/run-engine-binding@1", run_id: runId,
+        project_root: frozen.scope.projectRoot, bound_at: input.boundAt, source: "run_creation", reason: "Request-bound read-only diagnostic",
+        engine: { package_name: manifest.package_name, package_version: manifest.package_version, engine_version: manifest.engine_version,
+            integrity_checksum: checksum, snapshot_root: manifest.snapshot_root }, probe: { status: "not_required", command: null } };
+    const blobs = input.source.blobs();
+    const put = (logical, content) => {
+        if (blobs.has(logical))
+            refuse("bundle_path_collision");
+        blobs.set(logical, content);
+        return { path: logical, sha256: hash(content) };
+    };
+    for (const ref of [frozen.settings.attached_session_receipt, frozen.settings.delegation.native_capacity_receipt]) {
+        if (!ref)
+            continue;
+        const content = input.receiptBytes?.get(ref.sha256);
+        if (!content || hash(content) !== ref.sha256 || !input.receipts?.has(ref.sha256))
+            refuse("execution_receipt_missing");
+        put(ref.path, Buffer.from(content));
+    }
+    const profiles = { schema_id: "dd-flow/profile-settings@1", profiles: frozen.profiles, aliases: {}, default_profile: null };
+    const profile = put("runtime/profiles.json", bytes({ ...profiles, revision: hybridDigest(profiles) }));
+    const execution = put("runtime/execution.json", bytes(frozen.settings));
+    const engineBinding = put("runtime/engine-binding.json", bytes(binding));
+    const engineManifest = put("runtime/engine-manifest.json", input.engine.manifestBytes());
+    put("runtime/diagnostic-snapshot.json", bytes(snapshot));
+    const provenance = { canon: input.source.canonProvenance(), project_pack: null };
+    const bundle = { schema_id: "dd-flow/execution-bundle@1", run_id: runId, flow_id: flowId,
+        descriptor: input.source.descriptorReference(), execution_settings: execution, profile_settings: profile,
+        engine_binding: engineBinding, engine_manifest: engineManifest, bootstrap_receipts: [], ...provenance,
+        inventory: [...blobs].map(([logical, content]) => ({ path: logical, sha256: hash(content) })) };
+    const encoded = bytes(bundle);
+    return RetainedExecutionBundle.admit(encoded, hash(encoded), blobs, { runId, executionScope: frozen.scope,
+        bundleProjectRoot: frozen.scope.projectRoot, descriptorSha256: flow.sha256, engineChecksum: checksum,
+        engineBindingSha256: engineBinding.sha256, engineManifestSha256: engineManifest.sha256,
+        descriptorContext: bundledHandlerContext(new Map()), bundleProvenance: provenance, receipts: input.receipts ?? new Map() });
+}

package/dist/services/diagnostic-snapshot.js

@@ -0,0 +1,159 @@
+import fs from "node:fs";
+import path from "node:path";
+import { execFileSync } from "node:child_process";
+import { AppError } from "../shared/errors.js";
+import { isDiagnosticFlow } from "../domain/diagnostic-flows.js";
+import { hybridDigest } from "./hybrid-contracts.js";
+import { appendAudit } from "./audit.js";
+import { reviewSourceHash, reviewSourceFilter, reviewExecutionCopyHash } from "./review-copy.js";
+import { projectPacketLocators, runContextRelocations } from "./stage-context.js";
+const intentEvent = "diagnostic.snapshot_intent", readyEvent = "diagnostic.snapshot_ready";
+function refuse(reason) { throw new AppError("diagnostic_snapshot_invalid", "Read-only diagnosis requires its retained unchanged snapshot", 1, { reason, effect: "no_effect" }); }
+const inside = (root, file) => { const relative = path.relative(root, file); return relative === "" || !relative.startsWith(".." + path.sep) && relative !== ".." && !path.isAbsolute(relative); };
+function rows(context, input, event) {
+    return context.db.all("SELECT payload_json FROM audit_events WHERE project_id=? AND event_type=? AND json_extract(payload_json,'$.requestId')=? LIMIT 2", [input.projectId, event, input.requestId]);
+}
+function destination(context, input) {
+    return path.join(context.ddFlowHome, "diagnostic-snapshots", hybridDigest(input), "workspace");
+}
+/** Deterministic destination for freezing execution before the first copy. */
+export function diagnosticSnapshotRoot(context, input) {
+    validate(context, input);
+    return destination(context, input);
+}
+function physicalSnapshot(context, value, runId) {
+    return runId ? JSON.parse(projectPacketLocators(JSON.stringify(value), runContextRelocations(context, value.projectId, runId))) : value;
+}
+/** Only physical locators are projected through existing RUN import receipts.
+ * The immutable source selection and SQL custody remain byte-for-byte original. */
+export function diagnosticSnapshotPaths(context, value, runId) {
+    const physical = physicalSnapshot(context, value, runId);
+    return { root: physical.root, sourceRoot: physical.sourceRoot };
+}
+function validate(context, input, runId) {
+    const physical = physicalSnapshot(context, input, runId);
+    if (!isDiagnosticFlow(input.flowId) || !input.requestId?.trim() || input.requestId.length > 200
+        || !path.isAbsolute(physical.projectRoot) || physical.projectRoot !== physical.sourceRoot
+        || fs.realpathSync(physical.sourceRoot) !== physical.sourceRoot)
+        refuse("invalid_selection");
+    const project = context.db.get("SELECT root,status FROM projects WHERE id=?", [input.projectId]);
+    if (project?.root !== physical.projectRoot || project.status !== "active")
+        refuse("project_not_active");
+    if (inside(physical.sourceRoot, context.ddFlowHome))
+        refuse("runtime_inside_source");
+}
+function retained(context, input, runId) {
+    const records = rows(context, input, intentEvent);
+    if (records.length > 1)
+        refuse("ambiguous_snapshot");
+    if (!records.length)
+        return null;
+    if (Buffer.byteLength(records[0].payload_json) > 16 * 1024)
+        refuse("unbounded_snapshot");
+    const value = JSON.parse(records[0].payload_json);
+    if (value.schema_id !== "dd-flow/diagnostic-snapshot@1" || physicalSnapshot(context, value, runId).root !== destination(context, input)
+        || hybridDigest({ ...value, ...input }) !== hybridDigest(value) || !/^[a-f0-9]{64}$/.test(value.source_sha256))
+        refuse("snapshot_selection_changed");
+    return value;
+}
+function verifyFiles(value, requirePrivateGit = true) {
+    if (!fs.lstatSync(value.root).isDirectory() || fs.realpathSync(value.root) !== value.root
+        || reviewSourceHash(value.sourceRoot) !== value.source_sha256
+        || reviewExecutionCopyHash(value.root, value.sourceRoot, false) !== value.source_sha256)
+        refuse("source_or_copy_changed");
+    if (requirePrivateGit && !fs.lstatSync(path.join(value.root, ".git")).isDirectory())
+        refuse("private_git_required");
+}
+function seal(context, input, value) {
+    context.db.writeTransaction(() => {
+        if (hybridDigest(retained(context, input)) !== hybridDigest(value))
+            refuse("snapshot_custody_changed");
+        const ready = rows(context, input, readyEvent);
+        if (ready.length > 1 || ready.length === 1 && hybridDigest(JSON.parse(ready[0].payload_json)) !== hybridDigest(value))
+            refuse("snapshot_custody_changed");
+        if (!ready.length)
+            appendAudit(context, { projectId: input.projectId, eventType: readyEvent, payload: { ...value } });
+    });
+}
+/** SQL-owned selection plus freshly checked physical source/copy; never adopts a caller's claimed path. */
+export function readDiagnosticSnapshot(context, input, runId) {
+    validate(context, input, runId);
+    const value = readDiagnosticSnapshotCustody(context, input, runId);
+    if (!value)
+        return null;
+    verifyFiles(physicalSnapshot(context, value, runId));
+    return value;
+}
+/** SQL-only custody check for an already physically validated selection.
+ * Callers must perform readDiagnosticSnapshot before entering a writer. */
+export function readDiagnosticSnapshotCustody(context, input, runId) {
+    const value = retained(context, input, runId);
+    if (!value)
+        return null;
+    const ready = rows(context, input, readyEvent);
+    if (ready.length !== 1 || hybridDigest(JSON.parse(ready[0].payload_json)) !== hybridDigest(value))
+        refuse("snapshot_not_ready");
+    return value;
+}
+export function assertDiagnosticSnapshot(context, snapshot) {
+    const input = { projectId: snapshot.projectId, projectRoot: snapshot.projectRoot, sourceRoot: snapshot.sourceRoot, requestId: snapshot.requestId, flowId: snapshot.flowId };
+    const selected = readDiagnosticSnapshot(context, input);
+    if (!selected || hybridDigest(selected) !== hybridDigest(snapshot))
+        refuse("snapshot_binding_changed");
+}
+/** Copies only established review-visible inputs, never environment files or Git internals.
+ * Existing partial copies are verified, not overwritten. Reports belong outside this workspace. */
+export function prepareDiagnosticSnapshot(context, input) {
+    validate(context, input);
+    const prior = retained(context, input);
+    if (prior) {
+        if (rows(context, input, readyEvent).length)
+            return readDiagnosticSnapshot(context, input);
+        verifyFiles(prior);
+        seal(context, input, prior);
+        return prior;
+    }
+    const root = destination(context, input), env = { ...context.env, GIT_OPTIONAL_LOCKS: "0" };
+    for (const key of Object.keys(env))
+        if (key.startsWith("GIT_") && key !== "GIT_OPTIONAL_LOCKS")
+            delete env[key];
+    const git = (...args) => {
+        try {
+            return execFileSync("git", ["-c", "core.fsmonitor=false", "-C", input.sourceRoot, ...args], { env, encoding: "utf8", stdio: ["ignore", "pipe", "pipe"], maxBuffer: 1024 * 1024 }).trim();
+        }
+        catch {
+            return null;
+        } // Git absence is explicit missing evidence, never a clean verdict.
+    };
+    const value = { ...input, schema_id: "dd-flow/diagnostic-snapshot@1", root, source_sha256: reviewSourceHash(input.sourceRoot),
+        git: { head: git("rev-parse", "HEAD"), branch: git("symbolic-ref", "--quiet", "--short", "HEAD"), status: git("status", "--porcelain=v1") } };
+    let current = context.ddFlowHome;
+    for (const part of path.relative(context.ddFlowHome, path.dirname(root)).split(path.sep)) {
+        current = path.join(current, part);
+        if (fs.existsSync(current)) {
+            if (!fs.lstatSync(current).isDirectory() || fs.realpathSync(current) !== current)
+                refuse("unsafe_snapshot_parent");
+        }
+        else
+            fs.mkdirSync(current, { mode: 0o700 });
+    }
+    if (fs.existsSync(root))
+        refuse("unowned_snapshot_directory");
+    context.db.writeTransaction(() => {
+        if (rows(context, input, intentEvent).length)
+            refuse("snapshot_already_reserved");
+        appendAudit(context, { projectId: input.projectId, eventType: intentEvent, payload: { ...value } });
+    });
+    fs.mkdirSync(root, { mode: 0o700 });
+    fs.cpSync(input.sourceRoot, root, { recursive: true, verbatimSymlinks: true, force: false, errorOnExist: true, filter: reviewSourceFilter(input.sourceRoot) });
+    verifyFiles(value, false);
+    // A private, independent index makes ordinary controller Git observations safe.
+    // No project worktree/index, hooks, commits or branch is changed.
+    execFileSync("git", ["-c", "init.templateDir=", "init", "--quiet", "--initial-branch=diagnostic-snapshot", root], { env, stdio: "pipe" });
+    // A tracked source can also match .gitignore. Keep the selected safe files
+    // tracked in the private index so subsequent review copies cannot omit it.
+    execFileSync("git", ["-C", root, "add", "--force", "--all", "--", "."], { env, stdio: "pipe" });
+    verifyFiles(value);
+    seal(context, input, value);
+    return value;
+}