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

package/dist/services/diagnostic-stage-handlers.js

@@ -0,0 +1,108 @@
+import { AppError } from "../shared/errors.js";
+import { isDiagnosticFlow, diagnosticFlowStages } from "../domain/diagnostic-flows.js";
+import { readFlowRunExecutionBundle } from "./runs.js";
+import { requireProjectByRoot } from "./projects.js";
+import { resolveProjectRoot } from "../storage/paths.js";
+import { diagnosticSnapshotPaths, readDiagnosticSnapshot, readDiagnosticSnapshotCustody } from "./diagnostic-snapshot.js";
+import { PreparedDescriptorStageStart } from "./descriptor-stage-start.js";
+import { PreparedDescriptorStageCoordinator, readDescriptorStageInput } from "./descriptor-stage-coordinator.js";
+import { PreparedDescriptorStageSettlement } from "./descriptor-stage-settlement.js";
+import { PreparedDescriptorRunSettlement } from "./descriptor-run-settlement.js";
+import { assertDiagnosticCriticResolution, assertDiagnosticReportData, assertDiagnosticStageScope, sealDiagnosticStageLimitations, validateDiagnosticStageResult } from "./diagnostic-stage-results.js";
+import { readAcceptedStageData } from "./stage-report-renderer.js";
+import { registerDiagnosticStageGraph } from "./diagnostic-work-registration.js";
+import { PreparedDiagnosticWorkCollection } from "./diagnostic-work-collection.js";
+import { collectDiagnosticCandidates, sealDiagnosticCandidateIds } from "./diagnostic-work-results.js";
+import { hybridDigest } from "./hybrid-contracts.js";
+import { prepareDiagnosticReport } from "./diagnostic-report.js";
+import { prepareDiagnosticReportPublication } from "./diagnostic-report-publication.js";
+export const diagnosticStageHandlers = Object.freeze(Object.entries(diagnosticFlowStages).flatMap(([flowId, stages]) => stages.map(stage => Object.freeze({ flowId, stage, entryId: "diagnostic-stage-entry", finishId: "diagnostic-stage-finish",
+    entry: startDiagnosticStage, finish: finishDiagnosticStage }))));
+function refuse(reason) { throw new AppError("diagnostic_stage_invalid", "Diagnostic stage cannot accept this result", 2, { reason, effect: "no_effect" }); }
+function select(context, input) {
+    const bundle = readFlowRunExecutionBundle(context, input), project = requireProjectByRoot(context, resolveProjectRoot(input.projectRoot));
+    if (!bundle || !isDiagnosticFlow(bundle.manifest.flow_id)
+        || !diagnosticFlowStages[bundle.manifest.flow_id].includes(input.stage))
+        refuse("registered_diagnostic_stage_required");
+    const frozen = bundle.execution.snapshot().scope;
+    const snapshotSelection = { projectId: project.id, projectRoot: frozen.projectRoot, sourceRoot: frozen.projectRoot,
+        requestId: frozen.requestId, flowId: bundle.manifest.flow_id };
+    const snapshot = readDiagnosticSnapshot(context, snapshotSelection, input.runId);
+    if (!snapshot || snapshot.root !== frozen.workspace)
+        refuse("snapshot_required");
+    return { bundle, snapshot, snapshotSelection, scope: { projectId: project.id, runId: input.runId, stage: input.stage } };
+}
+export function startDiagnosticStage(context, input) {
+    const selected = select(context, input);
+    const fence = (writer) => {
+        if (hybridDigest(readDiagnosticSnapshotCustody(writer, selected.snapshotSelection, input.runId)) !== hybridDigest(selected.snapshot))
+            refuse("snapshot_changed");
+    };
+    const start = PreparedDescriptorStageStart.prepare(context, input).apply(context);
+    const coordinator = PreparedDescriptorStageCoordinator.prepare(context, input).apply(context, fence);
+    if (["audit", "analyze", "review"].includes(input.stage))
+        registerDiagnosticStageGraph(context, input);
+    return { ...start, ...coordinator };
+}
+/** Findings are data, not permission to repair. Only registered independent Work
+ * may contribute analysis/criticism; terminal acceptance closes runtime only. */
+export function finishDiagnosticStage(context, input) {
+    const selected = select(context, input), { bundle, snapshot, scope } = selected;
+    const stageInput = readDescriptorStageInput(context, scope, bundle, true, true);
+    const previousStage = stageInput.input.predecessor?.stage;
+    const previous = previousStage ? readAcceptedStageData(context, { ...scope, stage: previousStage }) : null;
+    const prior = previous ? JSON.parse(previous.bytes.toString("utf8")) : null;
+    const collection = ["audit", "analyze", "review"].includes(input.stage) ? PreparedDiagnosticWorkCollection.prepare(context, input) : null;
+    const candidates = ["audit", "analyze"].includes(input.stage) ? sealDiagnosticCandidateIds(input.bytes, collection.results()) : input.bytes;
+    const bytes = sealDiagnosticStageLimitations(candidates, [
+        ...(prior?.details.limitations ?? []), ...(collection?.results() ?? []).flatMap(work => work.result.limitations)
+    ], prior?.details.missing_expected_sources ?? []);
+    const result = validateDiagnosticStageResult(bytes, bundle.descriptor.stageBlob(input.stage, "result_schema"), {
+        flowId: selected.snapshotSelection.flowId, runId: input.runId, stage: input.stage,
+        inputSha256: stageInput.inputSha256, snapshotSha256: snapshot.source_sha256, snapshotRoot: diagnosticSnapshotPaths(context, snapshot, input.runId).root,
+        predecessors: stageInput.input.predecessor ? [{ stage: stageInput.input.predecessor.stage,
+                path: stageInput.input.predecessor.result.path, sha256: stageInput.input.predecessor.result.sha256 }] : []
+    });
+    if (prior) {
+        assertDiagnosticStageScope(result, prior);
+        if (prior.details.limitations.some(value => !result.details.limitations.includes(value)))
+            refuse("limitation_dropped");
+    }
+    if (collection) {
+        const works = collection.results();
+        if (works.some(work => work.result.limitations.some(value => !result.details.limitations.includes(value))))
+            refuse("worker_limitation_dropped");
+        if (input.stage !== "review") {
+            if (hybridDigest(result.details.findings) !== hybridDigest(collectDiagnosticCandidates(works).findings))
+                refuse("analysis_not_from_work");
+        }
+        else {
+            if (!prior || hybridDigest(result.details.findings) !== hybridDigest(prior.details.findings))
+                refuse("candidate_register_changed");
+            for (const decision of result.details.decisions) {
+                assertDiagnosticCriticResolution(decision, works.map(work => work.result.decisions));
+            }
+        }
+    }
+    if (input.stage === "report")
+        assertDiagnosticReportData(result, prior);
+    const analysis = input.stage === "report" ? PreparedDiagnosticWorkCollection.prepare(context, { ...input, stage: snapshot.flowId === "mb-audit" ? "audit" : "analyze" }) : null;
+    const critics = input.stage === "report" ? PreparedDiagnosticWorkCollection.prepare(context, { ...input, stage: "review" }) : null;
+    const publication = analysis && critics ? prepareDiagnosticReportPublication(context, { ...scope, attempt: stageInput.attempt, inputSha256: stageInput.inputSha256 }, prepareDiagnosticReport(result, analysis.results(), critics.results())) : null;
+    publication?.publish();
+    const fence = (writer) => {
+        if (hybridDigest(readDiagnosticSnapshotCustody(writer, selected.snapshotSelection, input.runId)) !== hybridDigest(snapshot))
+            refuse("snapshot_changed");
+        if (previous && hybridDigest(readAcceptedStageData(writer, { ...scope, stage: previousStage })) !== hybridDigest(previous))
+            refuse("predecessor_changed");
+        collection?.assertCustody(writer);
+        analysis?.assertCustody(writer);
+        critics?.assertCustody(writer);
+        publication?.retain(writer);
+    };
+    const settlement = PreparedDescriptorStageSettlement.prepare(context, { ...input, bytes }).apply(context, fence);
+    if (input.stage === "report")
+        return { ...settlement,
+            ...PreparedDescriptorRunSettlement.prepare(context, input).apply(context, fence), reports: publication.manifest.artifacts };
+    return settlement;
+}

package/dist/services/diagnostic-stage-results.js

@@ -0,0 +1,132 @@
+import { Ajv2020 } from "ajv/dist/2020.js";
+import { diagnosticFlowStages } from "../domain/diagnostic-flows.js";
+import { diagnosticAspects } from "../domain/diagnostic-aspects.js";
+import { AppError } from "../shared/errors.js";
+import { hybridDigest } from "./hybrid-contracts.js";
+import { verifyDiagnosticCoverage, verifyDiagnosticSources } from "./diagnostic-evidence.js";
+const refuse = (reason) => {
+    throw new AppError("diagnostic_stage_result_invalid", "Diagnostic result does not match its frozen stage", 2, { reason, effect: "no_effect", ...(reason === "result_schema_invalid" ? { phase: "prepare", recoverable: true } : {}) });
+};
+/** Accepted limitations and missing-source observations belong to predecessor/Work custody, not a coordinator's
+ * transcription. Keep its annotations too; validate the complete sealed result
+ * with the frozen schema afterwards, without truncating overflowing data. */
+export function sealDiagnosticStageLimitations(bytes, required, acceptedMissingSources = []) {
+    if ((!required.length && !acceptedMissingSources.length) || !bytes.length || bytes.length > 1024 * 1024)
+        return bytes;
+    let value;
+    try {
+        value = JSON.parse(new TextDecoder("utf-8", { fatal: true }).decode(bytes));
+    }
+    catch {
+        return bytes;
+    }
+    let changed = false;
+    for (const [key, expected] of [["limitations", required], ["missing_expected_sources", acceptedMissingSources]]) {
+        if (!expected.length)
+            continue;
+        const proposed = value?.details?.[key];
+        if (!Array.isArray(proposed) || proposed.some(item => typeof item !== "string"))
+            return bytes;
+        const missing = [...new Set(expected.filter(item => !proposed.includes(item)))];
+        if (missing.length) {
+            value.details[key] = [...missing, ...proposed];
+            changed = true;
+        }
+    }
+    return changed ? Buffer.from(JSON.stringify(value)) : bytes;
+}
+export function assertDiagnosticStageScope(result, prior) {
+    const coverageScope = (value) => value.details.coverage.map(({ id, applicability }) => ({ id, applicability }));
+    if (result.details.focus.mode !== prior.details.focus.mode
+        // New source gaps are analytical observations, not an expansion of scope.
+        // Previously accepted gaps still cannot disappear from the result.
+        || prior.details.missing_expected_sources.some(source => !result.details.missing_expected_sources.includes(source))
+        || hybridDigest(coverageScope(result)) !== hybridDigest(coverageScope(prior)))
+        throw new AppError("diagnostic_stage_invalid", "Diagnostic stage cannot accept this result", 2, { reason: "accepted_scope_changed", effect: "no_effect" });
+    // Focus prose is retained selection, not a new stage heading. A different
+    // proposal is never accepted, but can copy the exact predecessor and retry.
+    if (hybridDigest(result.details.focus) !== hybridDigest(prior.details.focus))
+        throw new AppError("diagnostic_stage_invalid", "Copy details.focus unchanged from the accepted predecessor; put the stage summary in summary, not the retained focus", 2, { reason: "accepted_focus_changed", effect: "no_effect", phase: "prepare", recoverable: true });
+    // Applicability is already accepted. Analytical progress belongs in findings,
+    // sources and limitations, not edits to the retained preflight annotations.
+    if (hybridDigest(result.details.coverage) !== hybridDigest(prior.details.coverage))
+        throw new AppError("diagnostic_stage_invalid", "Copy details.coverage unchanged from the accepted predecessor; put new observations in findings, sources or limitations", 2, { reason: "accepted_coverage_annotations_changed", effect: "no_effect", phase: "prepare", recoverable: true });
+}
+export function assertDiagnosticReportData(result, prior) {
+    // Reporting may disclose additional uncertainty, never revise reviewed facts
+    // or erase any accepted limitation. This comparison does not rewrite either result.
+    if (!prior || prior.details.limitations.some(value => !result.details.limitations.includes(value))
+        || hybridDigest({ ...result.details, limitations: prior.details.limitations }) !== hybridDigest(prior.details))
+        throw new AppError("diagnostic_stage_invalid", "Diagnostic stage cannot accept this result", 2, { reason: "report_changed_reviewed_data", effect: "no_effect" });
+}
+export function assertDiagnosticCriticResolution(decision, critics) {
+    const selected = decision;
+    const votes = critics.flat().filter(item => item.finding_id === decision.finding_id);
+    // Duplicate/rejected entries remain trace, not accepted findings. Their
+    // supported severity may be reconciled separately without inventing a vote.
+    // An accepted finding still requires one critic to endorse the whole pair.
+    const nonAccepting = ["duplicate", "rejected"].includes(selected.disposition);
+    if (votes.some(item => item.disposition === selected.disposition && item.severity === selected.severity)
+        || nonAccepting && votes.some(item => item.disposition === selected.disposition)
+            && votes.some(item => item.severity === selected.severity))
+        return;
+    throw new AppError("diagnostic_stage_invalid", "Use a supported critic resolution; preserve all independent critic decisions and explain disagreements", 2, { reason: "unsupported_critic_resolution", effect: "no_effect", phase: "prepare", recoverable: true,
+        finding_id: selected.finding_id, supported_resolutions: votes.map(item => ({ disposition: item.disposition, severity: item.severity })) });
+}
+/** Frozen schema and exact CLI-issued identity precede semantic evidence checks.
+ * This does not assert that independent Work/critics have settled. */
+export function validateDiagnosticStageResult(bytes, schemaBytes, binding) {
+    if (!bytes.length || bytes.length > 1024 * 1024 || schemaBytes.length > 1024 * 1024)
+        refuse("result_exceeds_bound");
+    const validate = (() => {
+        try {
+            const schema = JSON.parse(new TextDecoder("utf-8", { fatal: true }).decode(schemaBytes));
+            if (schema.$id !== "dd-flow/diagnostic-stage-result@1")
+                refuse("frozen_schema_invalid");
+            return new Ajv2020({ strict: false, validateFormats: false }).compile(schema);
+        }
+        catch {
+            return refuse("frozen_schema_invalid");
+        }
+    })();
+    let value;
+    try {
+        value = JSON.parse(new TextDecoder("utf-8", { fatal: true }).decode(bytes));
+    }
+    catch {
+        return refuse("result_schema_invalid");
+    }
+    if (!validate(value))
+        refuse("result_schema_invalid");
+    if (value.flow_id !== binding.flowId || value.run_id !== binding.runId || value.stage !== binding.stage
+        || !diagnosticFlowStages[binding.flowId].includes(binding.stage)
+        || value.input_sha256 !== binding.inputSha256 || value.snapshot_sha256 !== binding.snapshotSha256
+        || hybridDigest(value.predecessors) !== hybridDigest(binding.predecessors))
+        refuse("foreign_result_binding");
+    if ((binding.flowId === "mb-audit") !== (value.details.focus.mode === "memory_bank"))
+        refuse("foreign_focus");
+    verifyDiagnosticCoverage(binding.snapshotRoot, diagnosticAspects[binding.flowId].map(item => item.id), value.details.coverage);
+    verifyDiagnosticSources(binding.snapshotRoot, value.details.sources);
+    const ids = new Set();
+    for (const finding of value.details.findings) {
+        if (ids.has(finding.id) || !value.details.coverage.some(item => item.id === finding.aspect_id && item.applicability === "applicable")
+            || !finding.evidence.length)
+            refuse("finding_outside_coverage");
+        ids.add(finding.id);
+        verifyDiagnosticSources(binding.snapshotRoot, finding.evidence);
+    }
+    const decided = new Set();
+    for (const decision of value.details.decisions) {
+        if (!ids.has(decision.finding_id) || decided.has(decision.finding_id))
+            refuse("foreign_or_duplicate_decision");
+        decided.add(decision.finding_id);
+        verifyDiagnosticSources(binding.snapshotRoot, decision.evidence);
+    }
+    if (binding.stage === "preflight" && (ids.size || decided.size))
+        refuse("preflight_cannot_claim_analysis");
+    if (["audit", "analyze"].includes(binding.stage) && decided.size)
+        refuse("analysis_cannot_claim_independent_review");
+    if (["review", "report"].includes(binding.stage) && decided.size !== ids.size)
+        refuse("unresolved_finding");
+    return value;
+}

package/dist/services/diagnostic-start.js

@@ -0,0 +1,84 @@
+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 { prepareDiagnosticSnapshot, diagnosticSnapshotRoot } from "./diagnostic-snapshot.js";
+import { prepareDiagnosticRunBundle } from "./diagnostic-run-bundle.js";
+import { PreparedDescriptorRunStart } from "./descriptor-run-start.js";
+import { readRunStartRequest } from "./run-start-custody.js";
+import { requireProjectByRoot } from "./projects.js";
+import { resolveProjectRoot } from "../storage/paths.js";
+import { hybridDigest } from "./hybrid-contracts.js";
+import { appendAudit } from "./audit.js";
+const event = "diagnostic.request";
+function refuse(reason) { throw new AppError("diagnostic_request_invalid", "Diagnostic request requires its original frozen selection", 2, { reason, effect: "no_effect" }); }
+export function readDiagnosticRequest(context, scope) {
+    const project = requireProjectByRoot(context, resolveProjectRoot(scope.projectRoot));
+    const rows = context.db.all("SELECT payload_json FROM audit_events WHERE project_id=? AND event_type=? AND json_extract(payload_json,'$.scope.requestId')=? LIMIT 2", [project.id, event, scope.requestId]);
+    if (!rows.length)
+        return null;
+    if (rows.length !== 1 || Buffer.byteLength(rows[0].payload_json) > 48 * 1024 * 1024)
+        refuse("ambiguous_request");
+    const value = JSON.parse(rows[0].payload_json);
+    if (value.schema_id !== "dd-flow/diagnostic-request@1" || value.project_id !== project.id
+        || hybridDigest(value.scope) !== hybridDigest(scope) || !isDiagnosticFlow(value.scope.flowId))
+        refuse("request_scope_changed");
+    return value;
+}
+/** Freeze all ambient choices before copying source or allocating a RUN. */
+export function retainDiagnosticRequest(context, input) {
+    const { scope, source, execution, engine } = input;
+    if (!(source instanceof PreparedInstalledFlowSource) || !(execution instanceof FrozenGenericExecution)
+        || !(engine instanceof AdmittedFrozenEngine) || !isDiagnosticFlow(scope.flowId) || !/^[A-Za-z0-9][A-Za-z0-9_.-]{0,95}$/.test(scope.requestId)
+        || !input.objective.trim() || Buffer.byteLength(input.objective) > 64 * 1024)
+        refuse("invalid_selection");
+    const project = requireProjectByRoot(context, scope.projectRoot), frozen = execution.snapshot();
+    const workspace = diagnosticSnapshotRoot(context, { projectId: project.id, projectRoot: scope.projectRoot, sourceRoot: scope.projectRoot,
+        requestId: scope.requestId, flowId: scope.flowId });
+    if (frozen.scope.projectRoot !== scope.projectRoot || frozen.scope.requestId !== scope.requestId || frozen.scope.workspace !== workspace
+        || frozen.settings.flow_id !== scope.flowId || frozen.settings.descriptor_sha256 !== source.resolveRegisteredFlow().sha256
+        || frozen.settings.attached_session_receipt || frozen.settings.delegation.native_capacity_receipt)
+        refuse("execution_selection_changed");
+    source.revalidate();
+    engine.admitDiagnosticFlow(source, scope.flowId);
+    const manifest = engine.manifest();
+    if (typeof manifest.integrity.checksum !== "string")
+        refuse("engine_identity_missing");
+    const value = { schema_id: "dd-flow/diagnostic-request@1", project_id: project.id, scope: structuredClone(scope),
+        created_at: context.now(), objective: input.objective, selection: structuredClone(input.selection),
+        source: source.snapshot(), source_sha256: source.sha256, execution: frozen, execution_sha256: execution.sha256,
+        engine: { identity: { package_name: manifest.package_name, package_version: manifest.package_version, engine_version: manifest.engine_version,
+                integrity_checksum: manifest.integrity.checksum, snapshot_root: manifest.snapshot_root }, manifest_sha256: engine.manifestSha256 } };
+    if (Buffer.byteLength(JSON.stringify(value)) > 48 * 1024 * 1024)
+        refuse("request_exceeds_bound");
+    return context.db.writeTransaction(() => {
+        const prior = readDiagnosticRequest(context, scope);
+        if (prior) {
+            if (hybridDigest({ ...value, created_at: prior.created_at }) !== hybridDigest(prior))
+                refuse("request_changed");
+            return prior;
+        }
+        if (readRunStartRequest(context, project.id, scope.requestId))
+            refuse("foreign_run_request");
+        appendAudit(context, { projectId: project.id, eventType: event, payload: value });
+        return value;
+    });
+}
+export function startDiagnosticRun(context, scope) {
+    const retained = readDiagnosticRequest(context, scope);
+    if (!retained)
+        refuse("original_request_required");
+    const project = requireProjectByRoot(context, scope.projectRoot);
+    if (readRunStartRequest(context, project.id, scope.requestId))
+        return PreparedDescriptorRunStart.restore(context, scope).apply(context);
+    const snapshot = prepareDiagnosticSnapshot(context, { projectId: project.id, projectRoot: scope.projectRoot, sourceRoot: scope.projectRoot,
+        requestId: scope.requestId, flowId: scope.flowId });
+    const source = PreparedInstalledFlowSource.restoreRetained(retained.source, retained.source_sha256);
+    const execution = FrozenGenericExecution.restore(retained.execution, retained.execution_sha256, source.resolveRegisteredFlow(), {
+        requestId: scope.requestId, projectRoot: scope.projectRoot, workspace: snapshot.root
+    });
+    const engine = AdmittedFrozenEngine.admitSelection(retained.engine.identity, retained.engine.manifest_sha256);
+    const bundle = prepareDiagnosticRunBundle(context, { source, execution, engine, boundAt: retained.created_at });
+    return PreparedDescriptorRunStart.prepare(context, { bundle }).apply(context);
+}

package/dist/services/diagnostic-work-batch.js

@@ -0,0 +1,34 @@
+import { AppError } from "../shared/errors.js";
+import { hybridDigest } from "./hybrid-contracts.js";
+/** Only applicable aspects receive analytical Work. Critics receive all candidates,
+ * including candidates they may reject; no empty pseudo-Work proves coverage. */
+export function diagnosticWorkBatch(input) {
+    const review = input.stage === "review";
+    if (!review && input.stage !== (input.flow_id === "mb-audit" ? "audit" : "analyze")) {
+        throw new AppError("diagnostic_work_batch_invalid", "Diagnostic Work stage belongs to another flow", 2, { effect: "no_effect" });
+    }
+    const applicable = input.coverage.filter(value => value.applicability === "applicable");
+    const architecture = applicable.some(value => value.id ===
+        (input.flow_id === "mb-audit" ? "05" : "architecture_harmonization_review"));
+    const assignments = review
+        ? ["universal", ...(architecture ? ["architecture"] : [])].map(id => ({ id, role: "critic" }))
+        : applicable.map(value => ({ id: value.id, role: "aspect" }));
+    return { works: assignments.map((assignment, index) => {
+            const key = `${assignment.role}-${String(index + 1).padStart(3, "0")}`;
+            const packet = { schema_id: "dd-flow/diagnostic-work-input@1", flow_id: input.flow_id, run_id: input.run_id,
+                stage: input.stage, key, aspect_id: assignment.id, role: assignment.role,
+                input_sha256: input.input_sha256, snapshot_sha256: input.snapshot_sha256,
+                instruction: input.instruction, coverage: input.coverage, support: input.support ?? [],
+                candidates: review ? input.candidates : [] };
+            return { key, depends_on: [], launch_policy: "fresh_agent_required",
+                result_schema: "dd-flow/diagnostic-work-result@1",
+                task: (review
+                    ? `Independently assess every supplied candidate as the ${assignment.id} critic. Read the assigned immutable snapshot. Retain rejected findings and explain disagreement. Do not invent implementation, checks, sources or completion. Return exactly one decision per candidate using the assigned diagnostic result schema. Do not edit project files, repair findings, allocate Work or coordinate the Stage.`
+                    : `Examine only the assigned aspect ${JSON.stringify(assignment.id)} using the frozen instruction and actual snapshot sources. Distinguish implemented behavior from plans and absent evidence. Cite exact sources for material findings; retain uncertainty and active DEFs. Do not edit project files, execute project setup, repair findings, allocate Work or claim independent review. Return the assigned diagnostic Work result.`)
+                    + " Read applicable criterion files in diagnostic.support relative to run_home. They are frozen reference criteria, not executable/manual lifecycle instructions or implemented project facts. Cite snapshot sources as project evidence, not canon references."
+                    + " Every sources/evidence path must be relative to the assigned snapshot workspace root, using forward slashes (for example src/index.ts or .memory-bank/index.md), with the SHA256 of its exact snapshot bytes. Never cite absolute paths, .git, intake transport files, RUN packets or canon support as snapshot evidence; never invent a relative path for a file outside the snapshot."
+                    + " Files under .dd-flow/review-evidence are CLI-generated observations, not original project sources: do not put them in sources/evidence or infer the original repository's history or unborn state from the working copy's Git metadata. For missing linked targets cite the existing referring project document and describe the absence as a limitation, not as a source file.",
+                payload: { kind: review ? "diagnostic-critic" : "diagnostic-aspect", read_only: true,
+                    diagnostic: { ...packet, packet_sha256: hybridDigest(packet) } } };
+        }) };
+}

package/dist/services/diagnostic-work-collection.js

@@ -0,0 +1,97 @@
+import { AppError } from "../shared/errors.js";
+import { isDiagnosticFlow } from "../domain/diagnostic-flows.js";
+import { readFlowRunExecutionBundle, assertPreparedRunBundleSqlAuthority } from "./runs.js";
+import { requireProjectByRoot } from "./projects.js";
+import { resolveProjectRoot } from "../storage/paths.js";
+import { readRegisteredDiagnosticGraph } from "./diagnostic-work-registration.js";
+import { diagnosticWorkBatch } from "./diagnostic-work-batch.js";
+import { validateDiagnosticWorkResult } from "./diagnostic-work-results.js";
+import { diagnosticSnapshotPaths, readDiagnosticSnapshot, readDiagnosticSnapshotCustody } from "./diagnostic-snapshot.js";
+import { readDescriptorRootWork } from "./descriptor-root-work.js";
+import { hybridDigest } from "./hybrid-contracts.js";
+function refuse(reason) { throw new AppError("diagnostic_work_collection_invalid", "Diagnostic graph is not independently settled", 2, { reason, effect: "no_effect" }); }
+const physicalKey = (session) => `${session.harness}\0${session.provider_session_id}`;
+export function assertDiagnosticSessionIndependence(workers, excluded) {
+    const keys = workers.map(physicalKey), excludedKeys = new Set(excluded.map(physicalKey));
+    if (workers.some(value => !value.harness || !value.provider_session_id)
+        || new Set(keys).size !== keys.length || keys.some(key => excludedKeys.has(key)))
+        refuse("physical_session_reused");
+}
+function completedWork(context, scope, workId) {
+    const work = context.db.get("SELECT status,result FROM works WHERE project_id=? AND run_id=? AND work_id=?", [scope.projectId, scope.runId, workId]);
+    if (work?.status !== "completed" || !work.result || Buffer.byteLength(work.result) > 1024 * 1024)
+        refuse("work_not_completed");
+    const sessions = context.db.all("SELECT ws.id,ws.session_id,ws.status,s.harness,s.provider_session_id,ws.hook_event_id FROM work_sessions ws JOIN sessions s ON s.project_id=? AND s.session_id=ws.session_id AND s.run_id=? WHERE ws.work_id=? AND ws.status IN ('running','completed') LIMIT 3", [scope.projectId, scope.runId, workId]);
+    if (sessions.length !== 1 || sessions[0].status !== "completed")
+        refuse("work_session_not_settled");
+    const session = sessions[0];
+    const hook = context.db.get("SELECT session_id,harness,provider_session_id,status FROM hook_events WHERE project_id=? AND event_key=?", [scope.projectId, session.hook_event_id]);
+    if (!hook || hook.status !== "claimed" || hook.session_id !== session.session_id
+        || physicalKey(hook) !== physicalKey(session))
+        refuse("physical_work_owner_missing");
+    return { workId, result: work.result, session };
+}
+function collectSql(context, scope, rootId) {
+    const graph = readRegisteredDiagnosticGraph(context, scope);
+    if (!graph || graph.parent_work_id !== rootId)
+        refuse("registration_required");
+    const batch = diagnosticWorkBatch(graph.input);
+    const works = batch.works.map(item => completedWork(context, scope, graph.work_ids[item.key]));
+    const coordinators = context.db.all("SELECT s.harness,s.provider_session_id FROM work_sessions ws JOIN sessions s ON s.project_id=? AND s.run_id=? AND s.session_id=ws.session_id WHERE ws.work_id=?", [scope.projectId, scope.runId, rootId]);
+    const authorGraph = scope.stage === "review" ? readRegisteredDiagnosticGraph(context, { ...scope, stage: graph.input.flow_id === "mb-audit" ? "audit" : "analyze" }) : null;
+    if (scope.stage === "review" && !authorGraph)
+        refuse("author_graph_missing");
+    const authors = authorGraph ? Object.values(authorGraph.work_ids).map(id => completedWork(context, scope, id)) : [];
+    assertDiagnosticSessionIndependence(works.map(value => value.session), [...coordinators, ...authors.map(value => value.session)]);
+    return { graph, works, authors, coordinators };
+}
+/** File/schema/evidence checks occur before settlement. assertCustody is SQL-only
+ * and keeps the selected results and physical owners stable in its writer. */
+export class PreparedDiagnosticWorkCollection {
+    #scope;
+    #rootId;
+    #sql;
+    #snapshot;
+    #results;
+    constructor(scope, rootId, sql, snapshot, results) {
+        this.#scope = scope;
+        this.#rootId = rootId;
+        this.#sql = sql;
+        this.#snapshot = snapshot;
+        this.#results = results;
+        Object.freeze(this);
+    }
+    static prepare(context, input) {
+        const bundle = readFlowRunExecutionBundle(context, input), project = requireProjectByRoot(context, resolveProjectRoot(input.projectRoot));
+        if (!bundle || !isDiagnosticFlow(bundle.manifest.flow_id))
+            refuse("diagnostic_bundle_required");
+        const scope = { projectId: project.id, runId: input.runId, stage: input.stage };
+        const frozen = bundle.execution.snapshot().scope;
+        const snapshot = readDiagnosticSnapshot(context, { projectId: project.id, projectRoot: frozen.projectRoot,
+            sourceRoot: frozen.projectRoot, requestId: frozen.requestId, flowId: bundle.manifest.flow_id }, input.runId);
+        if (!snapshot || snapshot.root !== frozen.workspace)
+            refuse("snapshot_required");
+        const root = readDescriptorRootWork(context, scope, bundle);
+        const sql = context.db.readSnapshot(() => {
+            assertPreparedRunBundleSqlAuthority(context, scope, bundle);
+            return collectSql(context, scope, root.workId);
+        });
+        if (sql.graph.bundle_sha256 !== bundle.sha256 || sql.graph.input.snapshot_sha256 !== snapshot.source_sha256)
+            refuse("foreign_graph");
+        const batch = diagnosticWorkBatch(sql.graph.input), schema = bundle.blob("schemas/diagnostic-work-result.schema.json");
+        const results = sql.works.map((work, index) => ({ workId: work.workId,
+            result: validateDiagnosticWorkResult(Buffer.from(work.result), schema, diagnosticSnapshotPaths(context, snapshot, input.runId).root, sql.graph.input, {
+                workId: work.workId, aspectId: batch.works[index].payload.diagnostic.aspect_id,
+                role: batch.works[index].payload.diagnostic.role
+            }) }));
+        return new PreparedDiagnosticWorkCollection(scope, root.workId, sql, snapshot, results);
+    }
+    results() { return structuredClone(this.#results); }
+    assertCustody(context) {
+        const s = this.#snapshot;
+        if (hybridDigest(collectSql(context, this.#scope, this.#rootId)) !== hybridDigest(this.#sql)
+            || hybridDigest(readDiagnosticSnapshotCustody(context, { projectId: s.projectId, projectRoot: s.projectRoot,
+                sourceRoot: s.sourceRoot, requestId: s.requestId, flowId: s.flowId }, this.#scope.runId)) !== hybridDigest(s))
+            refuse("collection_changed");
+    }
+}

package/dist/services/diagnostic-work-registration.js

@@ -0,0 +1,101 @@
+import { AppError } from "../shared/errors.js";
+import { isDiagnosticFlow } from "../domain/diagnostic-flows.js";
+import { requireProjectByRoot } from "./projects.js";
+import { resolveProjectRoot } from "../storage/paths.js";
+import { readFlowRunExecutionBundle, assertPreparedRunBundleSqlAuthority } from "./runs.js";
+import { readDescriptorStageInput } from "./descriptor-stage-coordinator.js";
+import { readDescriptorRootWork } from "./descriptor-root-work.js";
+import { diagnosticSnapshotPaths, readDiagnosticSnapshot, readDiagnosticSnapshotCustody } from "./diagnostic-snapshot.js";
+import { readAcceptedStageData } from "./stage-report-renderer.js";
+import { validateDiagnosticStageResult } from "./diagnostic-stage-results.js";
+import { diagnosticWorkBatch } from "./diagnostic-work-batch.js";
+import { addWorkBatch, prepareWorkBatch, readWorkBatchCustody } from "./work-registry.js";
+import { stageGraphScope } from "./stage-work-graph.js";
+import { hybridDigest } from "./hybrid-contracts.js";
+import { appendAudit } from "./audit.js";
+const event = "diagnostic.work_registration";
+function refuse(reason) { throw new AppError("diagnostic_work_registration_invalid", "Diagnostic graph lacks its assigned stage authority", 2, { reason, effect: "no_effect" }); }
+/** SQL-only reader. An explicitly registered empty graph is distinct from no graph. */
+export function readRegisteredDiagnosticGraph(context, scope) {
+    const graph = stageGraphScope(context, scope.projectId, scope.runId, scope.stage);
+    const rows = 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')=? AND json_extract(payload_json,'$.attempt')=? LIMIT 2", [scope.projectId, event, scope.runId, scope.stage, graph.attempt]);
+    if (!rows.length)
+        return null;
+    if (rows.length !== 1 || Buffer.byteLength(rows[0].payload_json) > 2 * 1024 * 1024)
+        refuse("ambiguous_registration");
+    const receipt = JSON.parse(rows[0].payload_json);
+    if (receipt.schema_id !== "dd-flow/diagnostic-work-registration@1" || receipt.run_id !== scope.runId
+        || receipt.stage !== scope.stage || receipt.attempt !== graph.attempt || !receipt.work_ids
+        || receipt.input.run_id !== scope.runId || receipt.input.stage !== scope.stage
+        || receipt.input.input_sha256 !== receipt.input_sha256)
+        refuse("foreign_registration");
+    const batch = diagnosticWorkBatch(receipt.input);
+    if (receipt.batch_sha256 !== hybridDigest(batch.works) || batch.works.length !== Object.keys(receipt.work_ids).length
+        || new Set(Object.values(receipt.work_ids)).size !== batch.works.length)
+        refuse("changed_batch");
+    for (const item of batch.works) {
+        const id = receipt.work_ids[item.key];
+        if (!id)
+            refuse("missing_work");
+        const custody = readWorkBatchCustody(context, id);
+        if (custody.item_key !== item.key || custody.batch_sha256 !== receipt.batch_sha256
+            || hybridDigest(custody.work_ids) !== hybridDigest(receipt.work_ids)
+            || hybridDigest(custody.scope) !== hybridDigest({ ...graph, stage: scope.stage,
+                parent_work_id: receipt.parent_work_id, request_key: "diagnostic-graph" }))
+            refuse("changed_work_custody");
+    }
+    return receipt;
+}
+/** The registered handler calls this only after generic Stage entry. Applicability
+ * and candidates come from the accepted predecessor, not a caller-owned batch. */
+export function registerDiagnosticStageGraph(context, input) {
+    const bundle = readFlowRunExecutionBundle(context, input), project = requireProjectByRoot(context, resolveProjectRoot(input.projectRoot));
+    if (!bundle || !isDiagnosticFlow(bundle.manifest.flow_id) || !["audit", "analyze", "review"].includes(input.stage))
+        refuse("diagnostic_stage_required");
+    const flowId = bundle.manifest.flow_id, frozen = bundle.execution.snapshot().scope;
+    const scope = { projectId: project.id, runId: input.runId, stage: input.stage };
+    const selection = readDescriptorStageInput(context, scope, bundle), root = readDescriptorRootWork(context, scope, bundle);
+    const snapshotSelection = { projectId: project.id, projectRoot: frozen.projectRoot, sourceRoot: frozen.projectRoot, requestId: frozen.requestId, flowId };
+    const snapshot = readDiagnosticSnapshot(context, snapshotSelection, input.runId);
+    if (!snapshot || snapshot.root !== frozen.workspace)
+        refuse("snapshot_required");
+    const previousStage = input.stage === "review" ? flowId === "mb-audit" ? "audit" : "analyze" : "preflight";
+    if (selection.input.predecessor?.stage !== previousStage)
+        refuse("predecessor_required");
+    const previousScope = { ...scope, stage: previousStage };
+    const accepted = readAcceptedStageData(context, previousScope), previousInput = readDescriptorStageInput(context, previousScope, bundle, true, true);
+    const previous = validateDiagnosticStageResult(accepted.bytes, bundle.descriptor.stageBlob(previousStage, "result_schema"), {
+        flowId, runId: input.runId, stage: previousStage, inputSha256: previousInput.inputSha256,
+        snapshotRoot: diagnosticSnapshotPaths(context, snapshot, input.runId).root, snapshotSha256: snapshot.source_sha256,
+        predecessors: previousInput.input.predecessor ? [{ stage: previousInput.input.predecessor.stage,
+                path: previousInput.input.predecessor.result.path, sha256: previousInput.input.predecessor.result.sha256 }] : []
+    });
+    const workInput = { flow_id: flowId, run_id: input.runId, stage: input.stage,
+        input_sha256: selection.inputSha256, snapshot_sha256: snapshot.source_sha256,
+        instruction: bundle.descriptor.stageBlob(input.stage, "instruction").toString("utf8"),
+        coverage: previous.details.coverage, candidates: input.stage === "review" ? previous.details.findings : [],
+        support: bundle.manifest.inventory.filter(ref => ref.path.startsWith("support/")).map(ref => ({ path: `execution-bundle/${ref.path}`, sha256: ref.sha256 })) };
+    const batch = diagnosticWorkBatch(workInput), batchInput = { parentWorkId: root.workId, stage: input.stage, requestKey: "diagnostic-graph", value: batch };
+    const prepared = batch.works.length ? prepareWorkBatch(context, batchInput) : [];
+    return context.db.writeTransaction(() => {
+        assertPreparedRunBundleSqlAuthority(context, scope, bundle);
+        if (hybridDigest(readDiagnosticSnapshotCustody(context, snapshotSelection, input.runId)) !== hybridDigest(snapshot)
+            || hybridDigest(readDescriptorStageInput(context, scope, bundle)) !== hybridDigest(selection)
+            || hybridDigest(readAcceptedStageData(context, previousScope)) !== hybridDigest(accepted)
+            || readDescriptorRootWork(context, scope, bundle).workId !== root.workId)
+            refuse("stage_authority_changed");
+        const expected = { schema_id: "dd-flow/diagnostic-work-registration@1", run_id: input.runId, stage: input.stage,
+            attempt: selection.attempt, parent_work_id: root.workId, bundle_sha256: bundle.sha256,
+            input_sha256: selection.inputSha256, input: workInput, batch_sha256: hybridDigest(batch.works) };
+        const prior = readRegisteredDiagnosticGraph(context, scope);
+        if (prior) {
+            if (hybridDigest({ ...prior, work_ids: undefined }) !== hybridDigest(expected))
+                refuse("registration_changed");
+            return prior;
+        }
+        const workIds = batch.works.length ? addWorkBatch(context, { ...batchInput, prepared }).work_ids : {};
+        const receipt = { ...expected, work_ids: workIds };
+        appendAudit(context, { projectId: project.id, eventType: event, payload: receipt });
+        return readRegisteredDiagnosticGraph(context, scope);
+    });
+}