@deksden-com/dd-flow-cli 0.9.0-beta.16 → 0.9.0-beta.160

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

@@ -0,0 +1,249 @@
+import path from "node:path";
+import fs from "node:fs";
+import { AppError } from "../shared/errors.js";
+import { entityReferenceVariants } from "../shared/entity-references.js";
+import { distillStages } from "../domain/distill-flow.js";
+import { requireProjectByRoot } from "./projects.js";
+import { resolveProjectRoot } from "../storage/paths.js";
+import { readFlowRunExecutionBundle } from "./runs.js";
+import { readDiagnosticSnapshot, readDiagnosticSnapshotCustody, diagnosticSnapshotPaths } from "./diagnostic-snapshot.js";
+import { PreparedDescriptorStageStart } from "./descriptor-stage-start.js";
+import { PreparedDescriptorStageCoordinator, readDescriptorStageInput } from "./descriptor-stage-coordinator.js";
+import { PreparedDescriptorStageSettlement, readAcceptedDescriptorStageSettlement } from "./descriptor-stage-settlement.js";
+import { PreparedDescriptorRunSettlement } from "./descriptor-run-settlement.js";
+import { readAcceptedStageData, prepareStageReport, acceptStageReport, publishStageReport, publishStagePacket, resolveStagePublicationPath } from "./stage-report-renderer.js";
+import { publishDistillBeforeDocuments } from "./distill-document-publication.js";
+import { validateDistillStageResult, assertDistillStageScope } from "./distill-stage-results.js";
+import { registerDistillStageGraph } from "./distill-work-registration.js";
+import { PreparedDistillWorkCollection } from "./distill-work-collection.js";
+import { collectDistillCandidates } from "./distill-work-results.js";
+import { readCompletedDistillPublication, readDistillPublicationReference, distillPublicationArtifact } from "./distill-publication-custody.js";
+import { verifyDiagnosticSources } from "./diagnostic-evidence.js";
+import { readDistillUserInputs } from "./distill-user-inputs.js";
+import { readPreparedMemoryFlowUserInputs } from "./memory-flow-user-inputs.js";
+import { assertDiagnosticSessionIndependence } from "./diagnostic-work-collection.js";
+import { stageLifecycleMatchKey } from "./hooks.js";
+import { hybridDigest } from "./hybrid-contracts.js";
+function refuse(reason) {
+    const correctable = reason.startsWith("changed_") || ["invalid_result_json", "invalid_result_details", "result_exceeds_bound",
+        "unsupported_critic_resolution", "unowned_publication_claim", "preservation_evidence_required", "destination_evidence_required"].includes(reason);
+    throw new AppError("distill_stage_invalid", "Distillation stage requires accepted research, scope and independent observed verification", 2, { reason, effect: "no_effect", ...(correctable ? { phase: "prepare", recoverable: true } : {}) });
+}
+function select(context, input) {
+    const project = requireProjectByRoot(context, resolveProjectRoot(input.projectRoot)), bundle = readFlowRunExecutionBundle(context, input);
+    if (!bundle || bundle.manifest.flow_id !== "mb-distill" || !distillStages.includes(input.stage))
+        refuse("registered_distill_stage_required");
+    const frozen = bundle.execution.snapshot().scope, snapshotSelection = { projectId: project.id, projectRoot: frozen.projectRoot,
+        sourceRoot: frozen.projectRoot, requestId: frozen.requestId, flowId: "mb-distill" };
+    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 } };
+}
+function observeSelectedPublication(publication) {
+    const root = publication.binding.write_scope.destination_root;
+    if (fs.realpathSync(root) !== root || !fs.lstatSync(root).isDirectory())
+        refuse("destination_changed");
+    const documents = JSON.parse(distillPublicationArtifact(publication.binding, publication.plan).toString("utf8")).documents;
+    verifyDiagnosticSources(root, documents);
+    for (const document of documents) {
+        let parent = root;
+        for (const part of document.path.split("/").slice(0, -1)) {
+            parent = path.join(parent, part);
+            if (!fs.lstatSync(parent).isDirectory())
+                refuse("destination_parent_changed");
+        }
+        const stat = fs.lstatSync(path.join(root, document.path));
+        if (!stat.isFile() || stat.nlink !== 1 || (stat.mode & 0o7777) !== document.mode)
+            refuse("published_output_changed");
+    }
+}
+/** Internal handlers until descriptor, launch and installed family gates close.
+ * Existing generic lifecycle owns all allocation and physical settlement. */
+export const distillStageHandlers = Object.freeze(distillStages.map(stage => Object.freeze({ flowId: "mb-distill", stage,
+    entryId: "distill-stage-entry", finishId: "distill-stage-finish", entry: startDistillStage, finish: finishDistillStage })));
+export function startDistillStage(context, input) {
+    const selected = select(context, input);
+    const start = PreparedDescriptorStageStart.prepare(context, input).apply(context);
+    const coordinator = PreparedDescriptorStageCoordinator.prepare(context, input).apply(context, writer => {
+        if (hybridDigest(readDiagnosticSnapshotCustody(writer, selected.snapshotSelection, input.runId)) !== hybridDigest(selected.snapshot))
+            refuse("snapshot_changed");
+    });
+    if (["extract", "review"].includes(input.stage))
+        registerDistillStageGraph(context, input);
+    return { ...start, ...coordinator };
+}
+/** Projection fills CLI-owned registers, never new semantic findings. Explicit
+ * conflicting proposals refuse instead of being silently promoted. */
+export function prepareDistillStageProjection(bytes, stage, prior, collection) {
+    if (!bytes.length || bytes.length > 1024 * 1024)
+        refuse("result_exceeds_bound");
+    let value;
+    try {
+        value = JSON.parse(new TextDecoder("utf-8", { fatal: true }).decode(bytes));
+    }
+    catch {
+        return refuse("invalid_result_json");
+    }
+    if (!value || typeof value !== "object" || !value.details || typeof value.details !== "object" || Array.isArray(value.details)
+        || !Array.isArray(value.details.limitations) || value.details.limitations.some(item => typeof item !== "string"))
+        refuse("invalid_result_details");
+    const details = value.details;
+    const insert = (key, expected) => {
+        const proposed = details[key];
+        if (proposed !== undefined && (!Array.isArray(proposed) || proposed.length && hybridDigest(proposed) !== hybridDigest(expected)))
+            refuse(`changed_${key}`);
+        Object.assign(details, { [key]: structuredClone(expected) });
+    };
+    if (prior)
+        insert("coverage", prior.details.coverage);
+    if (stage === "preflight") {
+        insert("candidates", []);
+        insert("decisions", []);
+    }
+    else if (stage === "extract") {
+        if (!collection)
+            refuse("author_work_required");
+        insert("candidates", collectDistillCandidates(collection).candidates);
+        insert("decisions", []);
+    }
+    else {
+        if (!prior)
+            refuse("predecessor_required");
+        insert("candidates", prior.details.candidates);
+        if (stage !== "review")
+            insert("decisions", prior.details.decisions);
+    }
+    if (stage === "finish") {
+        if (!prior)
+            refuse("verified_predecessor_required");
+        insert("verification", prior.details.verification);
+    }
+    details.limitations = [...new Set([...(prior?.details.limitations ?? []), ...(collection ?? []).flatMap(work => work.result.limitations), ...details.limitations])];
+    return Buffer.from(JSON.stringify(value));
+}
+function verificationOwner(context, input, selected, settlement) {
+    const receipt = (writer, stage) => readAcceptedDescriptorStageSettlement(writer, { ...selected.scope, stage }, selected.bundle, entityReferenceVariants(input.runId).map(reference => stageLifecycleMatchKey("stage_finish", reference, stage, input.projectRoot)));
+    const read = (writer) => {
+        const promotion = receipt(writer, "promote"), verification = input.stage === "finish" ? receipt(writer, "verify") : null;
+        const physical = (sessionId) => {
+            const row = writer.db.get("SELECT harness,provider_session_id FROM sessions WHERE project_id=? AND run_id=? AND session_id=?", [selected.scope.projectId, input.runId, sessionId]);
+            if (!row?.harness || !row.provider_session_id)
+                refuse("verification_physical_owner_missing");
+            return row;
+        };
+        const verifier = physical(verification?.binding.sessionId ?? settlement.coordinatorSessionId()), author = physical(promotion.binding.sessionId);
+        assertDiagnosticSessionIndependence([verifier], [author]);
+        return { promotion, verification, verifier, author };
+    };
+    const original = context.db.readSnapshot(() => read(context));
+    return (writer) => { if (hybridDigest(read(writer)) !== hybridDigest(original))
+        refuse("verification_owner_changed"); };
+}
+export function finishDistillStage(context, input) {
+    const selected = select(context, input), { bundle, snapshot, scope } = selected, stage = input.stage;
+    const packet = readDescriptorStageInput(context, scope, bundle, true, true), previousStage = packet.input.predecessor?.stage;
+    const previous = previousStage ? readAcceptedStageData(context, { ...scope, stage: previousStage }) : null;
+    const prior = previous ? JSON.parse(previous.bytes.toString("utf8")) : null;
+    const collection = ["extract", "review"].includes(stage) ? PreparedDistillWorkCollection.prepare(context, input) : null;
+    const works = collection?.results() ?? null;
+    let bytes = prepareDistillStageProjection(input.bytes, stage, prior, works);
+    const binding = { runId: input.runId, stage, inputSha256: packet.inputSha256, snapshotSha256: snapshot.source_sha256,
+        snapshotRoot: diagnosticSnapshotPaths(context, snapshot, input.runId).root, runRoot: packet.runRoot,
+        support: bundle.manifest.inventory.filter(ref => ref.path.startsWith("support/")),
+        predecessors: packet.input.predecessor ? [{ stage: packet.input.predecessor.stage, ...packet.input.predecessor.result }] : [],
+        writeScope: prior?.details.write_scope ?? null, promotionReceipt: prior?.details.promotion_receipt ?? null };
+    let publication = null;
+    if (["promote", "verify", "finish"].includes(stage) && prior?.details.decisions.some(decision => ["adopt", "adapt"].includes(decision.disposition))) {
+        const review = readAcceptedStageData(context, { ...scope, stage: "review" });
+        const promotion = stage === "promote" ? packet : readDescriptorStageInput(context, { ...scope, stage: "promote" }, bundle, true, true);
+        publication = readCompletedDistillPublication(context, { project_id: scope.projectId, run_id: input.runId, attempt: promotion.attempt,
+            input_sha256: promotion.inputSha256, bundle_sha256: bundle.sha256, review_sha256: review.result.sha256 });
+        if (stage === "promote" && publication.binding.user_inputs_sha256 !== hybridDigest(readDistillUserInputs(context, input, bundle)))
+            refuse("user_inputs_changed");
+        binding.writeScope = publication.binding.write_scope;
+        binding.promotionReceipt = readDistillPublicationReference(context, publication.binding, publication.plan, `${bundle.descriptor.stage("promote").directory}/publication.json`);
+        if (!binding.promotionReceipt)
+            refuse("publication_reference_required");
+        publishDistillBeforeDocuments(packet.runRoot, publication.plan, publication.beforeDocuments);
+        publishStagePacket(context, scope.projectId, input.runId, "promote", path.join(packet.runRoot, binding.promotionReceipt.path));
+        const value = JSON.parse(bytes.toString("utf8"));
+        if (value.details.write_scope != null && hybridDigest(value.details.write_scope) !== hybridDigest(binding.writeScope)
+            || value.details.promotion_receipt != null && hybridDigest(value.details.promotion_receipt) !== hybridDigest(binding.promotionReceipt))
+            refuse("unowned_publication_claim");
+        Object.assign(value.details, { write_scope: binding.writeScope, promotion_receipt: binding.promotionReceipt });
+        bytes = Buffer.from(JSON.stringify(value));
+        if (stage === "promote") {
+            const actual = publication.plan.classify(binding.writeScope.destination_root);
+            if (actual.completed !== actual.total)
+                refuse("publication_not_observed");
+        }
+        else
+            observeSelectedPublication(publication);
+    }
+    const result = validateDistillStageResult(bytes, bundle.descriptor.stageBlob(stage, "result_schema"), binding);
+    if (publication && ["verify", "finish"].includes(stage)) {
+        const artifact = JSON.parse(distillPublicationArtifact(publication.binding, publication.plan).toString("utf8"));
+        const evidence = result.details.verification.flatMap(check => check.evidence);
+        if (artifact.before_documents.some((document) => !evidence.some(ref => ref.root === "run" && ref.path === document.source.path && ref.sha256 === document.source.sha256)))
+            refuse("preservation_evidence_required");
+        if (artifact.documents.some((document) => !evidence.some(ref => ref.root === "destination" && ref.path === document.path && ref.sha256 === document.sha256))
+            || result.details.verification.some(check => !check.evidence.some(ref => ref.root === "destination" && binding.writeScope.paths.includes(ref.path))))
+            refuse("destination_evidence_required");
+    }
+    if (prior)
+        assertDistillStageScope(result, prior);
+    if (stage === "review")
+        for (const decision of result.details.decisions) {
+            if (!works?.some(work => work.result.decisions.some(vote => vote.candidate_id === decision.candidate_id && vote.disposition === decision.disposition)))
+                refuse("unsupported_critic_resolution");
+        }
+    const settlement = PreparedDescriptorStageSettlement.prepare(context, { ...input, bytes });
+    const independent = publication && ["verify", "finish"].includes(stage) ? verificationOwner(context, input, selected, settlement) : null;
+    const authors = stage === "finish" ? PreparedDistillWorkCollection.prepare(context, { ...input, stage: "extract" }) : null;
+    const critics = stage === "finish" ? PreparedDistillWorkCollection.prepare(context, { ...input, stage: "review" }) : null;
+    const report = authors && critics ? prepareStageReport({ run_id: input.runId, stage: "finish", verdict: "completed", summary: result.summary,
+        distillation: { result, origins: collectDistillCandidates(authors.results()).origins, critics: critics.results() },
+        semantic: { acceptance: result.details.decisions.map(decision => `${decision.candidate_id}: ${decision.disposition}; publication=${binding.writeScope?.candidate_ids.includes(decision.candidate_id) ? "observed" : "not_selected"}; ${decision.reason}`),
+            checks: result.details.verification.map(check => `${check.candidate_id}: ${check.verdict}; ${check.summary}`), evidence: result.details.verification.flatMap(check => check.evidence.map(ref => `${ref.root}:${ref.path}@${ref.sha256}`)),
+            next_action: "Completed only the accepted scope; rejected, duplicate and unselected candidates remain in the register." } }) : null;
+    const reportRoot = path.join(packet.runRoot, bundle.descriptor.stage(stage).directory);
+    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);
+        authors?.assertCustody(writer);
+        critics?.assertCustody(writer);
+        independent?.(writer);
+        if (publication) {
+            const { write_scope, user_inputs_sha256, ...identity } = publication.binding;
+            const current = readCompletedDistillPublication(writer, identity);
+            if (current.plan.sha256 !== publication.plan.sha256 || hybridDigest(current.binding) !== hybridDigest(publication.binding)
+                || stage === "promote" && hybridDigest(readPreparedMemoryFlowUserInputs(writer, scope, "mb-distill", bundle)) !== user_inputs_sha256
+                || hybridDigest(write_scope) !== hybridDigest(binding.writeScope)
+                || hybridDigest(readDistillPublicationReference(writer, current.binding, current.plan, `${bundle.descriptor.stage("promote").directory}/publication.json`)) !== hybridDigest(binding.promotionReceipt))
+                refuse("publication_changed");
+        }
+        if (report) {
+            const rows = writer.db.all("SELECT payload_json FROM audit_events WHERE project_id=? AND event_type='flow_run.stage_report' AND json_extract(payload_json,'$.run_id')=? AND json_extract(payload_json,'$.stage')='finish' AND json_extract(payload_json,'$.attempt')=? LIMIT 2", [scope.projectId, input.runId, packet.attempt]);
+            if (rows.length > 1)
+                refuse("ambiguous_terminal_report");
+            if (rows.length) {
+                const retained = JSON.parse(rows[0].payload_json);
+                if (retained.sha256 !== report.sha256 || hybridDigest(retained.bytes) !== hybridDigest(report.bytes)
+                    || resolveStagePublicationPath(writer, scope.projectId, input.runId, retained.root) !== reportRoot)
+                    refuse("terminal_report_changed");
+            }
+            else
+                acceptStageReport(writer, { ...scope, root: reportRoot, prepared: report });
+        }
+    };
+    const accepted = settlement.apply(context, fence);
+    if (stage !== "finish")
+        return accepted;
+    const complete = PreparedDescriptorRunSettlement.prepare(context, input).apply(context, fence);
+    publishStageReport(context, scope.projectId, input.runId, "finish", reportRoot);
+    return { ...accepted, ...complete, reports: ["json", "md", "html"].map(extension => path.join(reportRoot, `stage-report.${extension}`)) };
+}

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

@@ -0,0 +1,105 @@
+import path from "node:path";
+import { Ajv2020 } from "ajv/dist/2020.js";
+import { AppError } from "../shared/errors.js";
+import { distillAspects } from "../domain/distill-flow.js";
+import { hybridDigest } from "./hybrid-contracts.js";
+import { verifyDiagnosticCoverage, verifyDiagnosticSources } from "./diagnostic-evidence.js";
+function refuse(reason) {
+    throw new AppError("distill_stage_result_invalid", "Distillation stage result lacks its exact input, reviewed scope or publication proof", 2, { reason, effect: "no_effect", ...(reason === "invalid_schema" ? { phase: "prepare", recoverable: true } : {}) });
+}
+const portable = (value) => Boolean(value) && !path.posix.isAbsolute(value) && !path.win32.isAbsolute(value)
+    && !value.includes("\\") && !value.includes("\0") && value.split("/").every(part => Boolean(part) && ![".", "..", ".git", "node_modules"].includes(part));
+/** Shape/evidence checks do not establish independent Work or publication
+ * custody. The registered handler must prepare those bindings and fence them
+ * again in its settlement transaction. */
+export function validateDistillStageResult(bytes, schemaBytes, binding) {
+    if (!bytes.length || bytes.length > 1024 * 1024 || !schemaBytes.length || 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/distill-stage-result@1")
+                refuse("frozen_schema_invalid");
+            return new Ajv2020({ strict: false, validateFormats: false }).compile(schema);
+        }
+        catch {
+            return refuse("frozen_schema_invalid");
+        }
+    })();
+    let result;
+    try {
+        result = JSON.parse(new TextDecoder("utf-8", { fatal: true }).decode(bytes));
+    }
+    catch {
+        return refuse("invalid_schema");
+    }
+    if (!validate(result))
+        refuse("invalid_schema");
+    if (result.flow_id !== "mb-distill" || result.run_id !== binding.runId || result.stage !== binding.stage
+        || result.input_sha256 !== binding.inputSha256 || result.snapshot_sha256 !== binding.snapshotSha256
+        || hybridDigest(result.predecessors) !== hybridDigest(binding.predecessors))
+        refuse("foreign_stage_binding");
+    const details = result.details;
+    verifyDiagnosticCoverage(binding.snapshotRoot, distillAspects.map(aspect => aspect.id), details.coverage);
+    const ids = new Set();
+    const baseline = (refs) => {
+        if (refs.some(ref => !binding.support.some(source => source.path === ref.path && source.sha256 === ref.sha256)))
+            refuse("foreign_baseline");
+    };
+    for (const candidate of details.candidates) {
+        if (ids.has(candidate.id) || !details.coverage.some(row => row.id === candidate.aspect_id && row.applicability === "applicable"))
+            refuse("candidate_outside_selection");
+        ids.add(candidate.id);
+        baseline(candidate.baseline_refs);
+        verifyDiagnosticSources(binding.snapshotRoot, [...candidate.source_refs, ...candidate.usage_refs]);
+    }
+    const decided = new Set();
+    for (const decision of details.decisions) {
+        if (!ids.has(decision.candidate_id) || decided.has(decision.candidate_id))
+            refuse("foreign_or_duplicate_decision");
+        decided.add(decision.candidate_id);
+        baseline(decision.baseline_refs);
+        verifyDiagnosticSources(binding.snapshotRoot, decision.source_refs);
+    }
+    if (!["preflight", "extract"].includes(binding.stage) && decided.size !== ids.size)
+        refuse("unresolved_candidate");
+    if (hybridDigest(details.write_scope) !== hybridDigest(binding.writeScope)
+        || hybridDigest(details.promotion_receipt) !== hybridDigest(binding.promotionReceipt))
+        refuse("unowned_publication_claim");
+    const scope = binding.writeScope;
+    if (!["verify", "finish"].includes(binding.stage) && details.verification.length)
+        refuse("verification_before_publication_review");
+    if (scope) {
+        if (!["promote", "verify", "finish"].includes(binding.stage) || !path.isAbsolute(scope.destination_root)
+            || path.resolve(scope.destination_root) !== scope.destination_root || scope.paths.some(value => !portable(value))
+            || scope.candidate_ids.some(id => !details.decisions.some(decision => decision.candidate_id === id && ["adopt", "adapt"].includes(decision.disposition))))
+            refuse("invalid_write_scope");
+        verifyDiagnosticSources(binding.runRoot, [scope.approval_source]);
+    }
+    if (binding.promotionReceipt)
+        verifyDiagnosticSources(binding.runRoot, [binding.promotionReceipt]);
+    if (binding.stage === "promote" && details.decisions.some(decision => ["adopt", "adapt"].includes(decision.disposition))
+        && (!scope || !binding.promotionReceipt))
+        refuse("promotion_requires_accepted_scope_and_receipt");
+    const verified = new Set();
+    for (const observation of details.verification) {
+        if (!scope?.candidate_ids.includes(observation.candidate_id) || verified.has(observation.candidate_id))
+            refuse("foreign_verification");
+        verified.add(observation.candidate_id);
+        for (const evidence of observation.evidence)
+            verifyDiagnosticSources(evidence.root === "run" ? binding.runRoot : scope.destination_root, [evidence]);
+    }
+    if (["verify", "finish"].includes(binding.stage) && details.decisions.some(decision => ["adopt", "adapt"].includes(decision.disposition))
+        && (!scope || !binding.promotionReceipt || scope.candidate_ids.some(id => !verified.has(id))
+            || details.verification.some(observation => observation.verdict !== "verified")))
+        refuse("unverified_promotion");
+    return result;
+}
+export function assertDistillStageScope(result, prior) {
+    if (hybridDigest(result.details.coverage) !== hybridDigest(prior.details.coverage)
+        || prior.details.limitations.some(value => !result.details.limitations.includes(value))
+        || (prior.stage !== "preflight" && hybridDigest(result.details.candidates) !== hybridDigest(prior.details.candidates))
+        || (!["preflight", "extract"].includes(prior.stage) && hybridDigest(result.details.decisions) !== hybridDigest(prior.details.decisions))
+        || (prior.details.write_scope && hybridDigest(result.details.write_scope) !== hybridDigest(prior.details.write_scope)))
+        refuse("accepted_scope_changed");
+}

package/dist/services/distill-user-inputs.js

@@ -0,0 +1,4 @@
+import { readMemoryFlowUserInputs } from "./memory-flow-user-inputs.js";
+export function readDistillUserInputs(context, input, retainedBundle) {
+    return readMemoryFlowUserInputs(context, input, "mb-distill", retainedBundle);
+}

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

@@ -0,0 +1,42 @@
+import { distillAspects } from "../domain/distill-flow.js";
+import { AppError } from "../shared/errors.js";
+import { hybridDigest } from "./hybrid-contracts.js";
+function refuse(reason) {
+    throw new AppError("distill_work_batch_invalid", "Distillation requires its accepted complete aspect selection", 2, { reason, effect: "no_effect" });
+}
+/** One selected aspect is one independent semantic unit. Capacity changes
+ * scheduling in the existing Work runtime, never selection or dependencies. */
+export function distillWorkBatch(input) {
+    const ids = input.coverage.map(row => row.id);
+    if (input.flow_id !== "mb-distill" || !["extract", "review"].includes(input.stage)
+        || ids.length !== distillAspects.length || new Set(ids).size !== ids.length
+        || distillAspects.some(aspect => !ids.includes(aspect.id))
+        || input.coverage.some(row => !row.reason.trim() || !["applicable", "not_applicable", "blocked", "out_of_scope"].includes(row.applicability)))
+        refuse("invalid_coverage");
+    const selected = distillAspects.filter(aspect => input.coverage.some(row => row.id === aspect.id && row.applicability === "applicable"));
+    if (input.stage === "extract" && input.candidates.length)
+        refuse("extract_cannot_accept_candidates");
+    if (new Set(input.candidates.map(candidate => candidate.id)).size !== input.candidates.length
+        || input.candidates.some(candidate => !selected.some(aspect => aspect.id === candidate.aspect_id)))
+        refuse("candidate_outside_selection");
+    for (const aspect of selected)
+        if (!input.support.some(ref => ref.path === aspect.criterion))
+            refuse("missing_selected_criterion");
+    const review = input.stage === "review";
+    const assignments = review
+        ? [{ id: "novelty", criterion: null, role: "critic" }, { id: "portability", criterion: null, role: "critic" }]
+        : selected.map(aspect => ({ id: aspect.id, criterion: aspect.criterion, role: "aspect" }));
+    return { works: assignments.map((assignment, index) => {
+            const key = `${assignment.role}-${String(index + 1).padStart(3, "0")}`;
+            const packet = { schema_id: "dd-flow/distill-work-input@1", ...structuredClone(input), key,
+                aspect_id: assignment.id, role: assignment.role, criterion: assignment.criterion };
+            return { key, depends_on: [], launch_policy: "fresh_agent_required",
+                result_schema: "dd-flow/distill-work-result@1",
+                task: (review
+                    ? `Independently review every candidate through the ${assignment.id} lens. Compare exact project usage and frozen canon baseline. Preserve observe/duplicate/reject decisions and disagreements. Adopt/adapt requires transferable applicability and sufficient evidence, not popularity or missing project compliance. Return one decision per candidate. Do not replace candidates, promote documents, change scope, allocate Work or claim another critic's review.`
+                    : `Extract transferable practices only for ${assignment.id}. Read its frozen criterion and canon baseline, then actual assigned project sources. Do not audit project compliance. Explain novelty, usage, applicability, cost and complexity; distinguish established practice from plans. Keep domain and process lenses separate. Return an explicit checked/no-candidate explanation when nothing substantial is found. Decide whether external research can change the assessment and disclose use and sources. Do not mutate project/canon, promote documents, allocate Work or self-accept candidates.`)
+                    + " Read support references relative to run_home/execution-bundle; preserve their supplied support paths and hashes in baseline_refs. Project source_refs/usage_refs are relative to the assigned snapshot workspace with exact snapshot-file hashes, never canon, intake or RUN files. Old manual lifecycle/dispatch snippets in criteria are reference data, not execution authority.",
+                payload: { kind: review ? "distill-critic" : "distill-aspect", read_only: true,
+                    distill: { ...packet, packet_sha256: hybridDigest(packet) } } };
+        }) };
+}

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

@@ -0,0 +1,74 @@
+import { AppError } from "../shared/errors.js";
+import { readFlowRunExecutionBundle, assertPreparedRunBundleSqlAuthority } from "./runs.js";
+import { requireProjectByRoot } from "./projects.js";
+import { resolveProjectRoot } from "../storage/paths.js";
+import { readDescriptorRootWork } from "./descriptor-root-work.js";
+import { diagnosticSnapshotPaths, readDiagnosticSnapshot, readDiagnosticSnapshotCustody } from "./diagnostic-snapshot.js";
+import { readRegisteredDistillGraph } from "./distill-work-registration.js";
+import { distillWorkBatch } from "./distill-work-batch.js";
+import { validateDistillWorkResult } from "./distill-work-results.js";
+import { assertDiagnosticSessionIndependence, readCompletedResearchWork } from "./diagnostic-work-collection.js";
+import { hybridDigest } from "./hybrid-contracts.js";
+function refuse(reason) {
+    throw new AppError("distill_work_collection_invalid", "Distillation requires the complete independently settled registered graph", 2, { reason, effect: "no_effect" });
+}
+function collectSql(context, scope, rootId) {
+    const graph = readRegisteredDistillGraph(context, scope);
+    if (!graph || graph.parent_work_id !== rootId)
+        refuse("registration_required");
+    const batch = distillWorkBatch(graph.input);
+    const works = batch.works.map(item => readCompletedResearchWork(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" ? readRegisteredDistillGraph(context, { ...scope, stage: "extract" }) : null;
+    if (scope.stage === "review" && !authorGraph)
+        refuse("author_graph_missing");
+    const authors = authorGraph ? Object.values(authorGraph.work_ids).map(id => readCompletedResearchWork(context, scope, id)) : [];
+    assertDiagnosticSessionIndependence(works.map(work => work.session), [...coordinators, ...authors.map(work => work.session)]);
+    return { graph, works, authors, coordinators };
+}
+export class PreparedDistillWorkCollection {
+    #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 project = requireProjectByRoot(context, resolveProjectRoot(input.projectRoot)), bundle = readFlowRunExecutionBundle(context, input);
+        if (!bundle || bundle.manifest.flow_id !== "mb-distill")
+            refuse("distill_bundle_required");
+        const scope = { projectId: project.id, runId: input.runId, stage: input.stage }, frozen = bundle.execution.snapshot().scope;
+        const snapshot = readDiagnosticSnapshot(context, { projectId: project.id, projectRoot: frozen.projectRoot,
+            sourceRoot: frozen.projectRoot, requestId: frozen.requestId, flowId: "mb-distill" }, 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 = distillWorkBatch(sql.graph.input), schema = bundle.blob("schemas/distill-work-result.schema.json");
+        const results = sql.works.map((work, index) => ({ workId: work.workId,
+            result: validateDistillWorkResult(Buffer.from(work.result), schema, diagnosticSnapshotPaths(context, snapshot, input.runId).root, sql.graph.input, {
+                workId: work.workId, aspectId: batch.works[index].payload.distill.aspect_id, role: batch.works[index].payload.distill.role
+            }) }));
+        return new PreparedDistillWorkCollection(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/distill-work-registration.js

@@ -0,0 +1,93 @@
+import { AppError } from "../shared/errors.js";
+import { readFlowRunExecutionBundle, assertPreparedRunBundleSqlAuthority } from "./runs.js";
+import { requireProjectByRoot } from "./projects.js";
+import { resolveProjectRoot } from "../storage/paths.js";
+import { readDescriptorStageInput } from "./descriptor-stage-coordinator.js";
+import { readDescriptorRootWork } from "./descriptor-root-work.js";
+import { readAcceptedStageData } from "./stage-report-renderer.js";
+import { diagnosticSnapshotPaths, readDiagnosticSnapshot, readDiagnosticSnapshotCustody } from "./diagnostic-snapshot.js";
+import { validateDistillStageResult } from "./distill-stage-results.js";
+import { distillWorkBatch } from "./distill-work-batch.js";
+import { prepareWorkBatch, addWorkBatch, readWorkBatchCustody } from "./work-registry.js";
+import { stageGraphScope } from "./stage-work-graph.js";
+import { appendAudit } from "./audit.js";
+import { hybridDigest } from "./hybrid-contracts.js";
+const event = "distill.work_registration";
+function refuse(reason) {
+    throw new AppError("distill_work_registration_invalid", "Distillation graph requires its accepted predecessor and frozen stage", 2, { reason, effect: "no_effect" });
+}
+export function readRegisteredDistillGraph(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/distill-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 = distillWorkBatch(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: "distill-graph" }))
+            refuse("changed_work_custody");
+    }
+    return receipt;
+}
+export function registerDistillStageGraph(context, input) {
+    const bundle = readFlowRunExecutionBundle(context, input), project = requireProjectByRoot(context, resolveProjectRoot(input.projectRoot));
+    if (!bundle || bundle.manifest.flow_id !== "mb-distill" || !["extract", "review"].includes(input.stage))
+        refuse("distill_stage_required");
+    const frozen = bundle.execution.snapshot().scope, scope = { projectId: project.id, runId: input.runId, stage: input.stage };
+    const selection = readDescriptorStageInput(context, scope, bundle), root = readDescriptorRootWork(context, scope, bundle);
+    const snapshotScope = { projectId: project.id, projectRoot: frozen.projectRoot, sourceRoot: frozen.projectRoot, requestId: frozen.requestId, flowId: "mb-distill" };
+    const snapshot = readDiagnosticSnapshot(context, snapshotScope, input.runId);
+    if (!snapshot || snapshot.root !== frozen.workspace)
+        refuse("snapshot_required");
+    const previousStage = input.stage === "extract" ? "preflight" : "extract";
+    if (selection.input.predecessor?.stage !== previousStage)
+        refuse("predecessor_required");
+    const previousScope = { ...scope, stage: previousStage }, accepted = readAcceptedStageData(context, previousScope);
+    const priorInput = readDescriptorStageInput(context, previousScope, bundle, true, true);
+    const support = bundle.manifest.inventory.filter(ref => ref.path.startsWith("support/"));
+    const previous = validateDistillStageResult(accepted.bytes, bundle.descriptor.stageBlob(previousStage, "result_schema"), {
+        runId: input.runId, stage: previousStage, inputSha256: priorInput.inputSha256, snapshotSha256: snapshot.source_sha256,
+        snapshotRoot: diagnosticSnapshotPaths(context, snapshot, input.runId).root, runRoot: selection.runRoot, support, writeScope: null, promotionReceipt: null,
+        predecessors: priorInput.input.predecessor ? [{ stage: priorInput.input.predecessor.stage, ...priorInput.input.predecessor.result }] : []
+    });
+    const workInput = { flow_id: "mb-distill", 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.candidates : [], support };
+    const batch = distillWorkBatch(workInput), batchInput = { parentWorkId: root.workId, stage: input.stage, requestKey: "distill-graph", value: batch };
+    const prepared = batch.works.length ? prepareWorkBatch(context, batchInput) : [];
+    return context.db.writeTransaction(() => {
+        assertPreparedRunBundleSqlAuthority(context, scope, bundle);
+        if (hybridDigest(readDiagnosticSnapshotCustody(context, snapshotScope, 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/distill-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 = readRegisteredDistillGraph(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 readRegisteredDistillGraph(context, scope);
+    });
+}