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

package/dist/services/distill-publication-custody.js

@@ -0,0 +1,162 @@
+import { AppError } from "../shared/errors.js";
+import { RetainedMemoryRepairPublicationPlan } from "./memory-repair-publication-plan.js";
+import { hybridDigest } from "./hybrid-contracts.js";
+import { appendAudit } from "./audit.js";
+import path from "node:path";
+import { createHash } from "node:crypto";
+import { resolveStagePublicationPath } from "./stage-report-renderer.js";
+import { validateDistillBeforeDocuments, distillBeforeDocumentReferences } from "./distill-document-publication.js";
+const intentEvent = "distill.publication_intent", completeEvent = "distill.publication_complete";
+const key = (binding) => `distill_publication:${hybridDigest({ project_id: binding.project_id, run_id: binding.run_id })}`;
+function refuse(reason) {
+    throw new AppError("distill_publication_custody_invalid", "Publication requires its original approved binding and retained plan", 1, { reason, effect: "no_effect" });
+}
+const receipt = (binding, plan, completed = false) => ({
+    schema_id: completed ? "dd-flow/distill-publication-complete@1" : "dd-flow/distill-publication-intent@1",
+    run_id: binding.run_id, binding_sha256: hybridDigest(binding), plan_sha256: plan.sha256
+});
+/** SQL custody only. The caller derives binding from the active Stage,
+ * accepted review and delivered user input, never from model authority fields.
+ * An existing intent cannot adopt today's partly changed destination as baseline. */
+export function readDistillPublication(context, binding) {
+    return context.db.readSnapshot(() => {
+        const row = context.db.get("SELECT value_json FROM runtime_config WHERE key=?", [key(binding)]);
+        const events = (type) => context.db.all("SELECT payload_json FROM audit_events WHERE project_id=? AND event_type=? AND json_extract(payload_json,'$.run_id')=? LIMIT 2", [binding.project_id, type, binding.run_id]);
+        const intents = events(intentEvent), completions = events(completeEvent);
+        if (!row && !intents.length && !completions.length)
+            return null;
+        if (!row || intents.length !== 1 || completions.length > 1 || Buffer.byteLength(row.value_json) > 180 * 1024 * 1024
+            || [...intents, ...completions].some(value => Buffer.byteLength(value.payload_json) > 32768))
+            refuse("missing_or_unbounded_custody");
+        try {
+            const value = JSON.parse(row.value_json);
+            if (!value || Object.keys(value).sort().join() !== "before_documents,binding,plan_json,plan_sha256" || hybridDigest(value.binding) !== hybridDigest(binding)
+                || typeof value.plan_json !== "string")
+                refuse("binding_changed");
+            const plan = RetainedMemoryRepairPublicationPlan.restore(Buffer.from(value.plan_json), value.plan_sha256);
+            const beforeDocuments = validateDistillBeforeDocuments(plan, value.before_documents);
+            if (hybridDigest(JSON.parse(intents[0].payload_json)) !== hybridDigest(receipt(binding, plan))
+                || completions.length && hybridDigest(JSON.parse(completions[0].payload_json)) !== hybridDigest(receipt(binding, plan, true)))
+                refuse("receipt_changed");
+            return { plan, beforeDocuments, completed: completions.length === 1 };
+        }
+        catch (error) {
+            if (error instanceof AppError)
+                throw error;
+            return refuse("invalid_retained_publication");
+        }
+    });
+}
+export function retainDistillPublication(context, binding, plan, assertAuthority, beforeDocuments = []) {
+    if (!(plan instanceof RetainedMemoryRepairPublicationPlan) || typeof assertAuthority !== "function")
+        refuse("prepared_plan_required");
+    const paths = JSON.parse(Buffer.from(JSON.parse(plan.bytes().toString("utf8")).before_base64, "base64").toString("utf8")).write_paths;
+    if (hybridDigest([...paths].sort()) !== hybridDigest([...binding.write_scope.paths].sort()))
+        refuse("plan_scope_changed");
+    const originals = validateDistillBeforeDocuments(plan, beforeDocuments);
+    return context.db.writeTransaction(() => {
+        assertAuthority();
+        const prior = readDistillPublication(context, binding);
+        if (prior) {
+            if (prior.plan.sha256 !== plan.sha256 || hybridDigest(prior.beforeDocuments) !== hybridDigest(originals))
+                refuse("original_plan_required");
+            return { changed: false, plan: prior.plan };
+        }
+        // A new intent must describe the original destination, not an already
+        // applied prefix or a different directory with coincidentally similar paths.
+        if (plan.classify(binding.write_scope.destination_root).completed !== 0)
+            refuse("original_destination_required");
+        const now = context.now();
+        const value = JSON.stringify({ binding, plan_json: plan.bytes().toString("utf8"), plan_sha256: plan.sha256, before_documents: originals });
+        if (Buffer.byteLength(value) > 180 * 1024 * 1024)
+            refuse("unbounded_publication_custody");
+        context.db.run("INSERT INTO runtime_config(key,value_json,created_at,updated_at) VALUES (?,?,?,?)", [key(binding), value, now, now]);
+        appendAudit(context, { projectId: binding.project_id, eventType: intentEvent, payload: receipt(binding, plan) });
+        if (readDistillPublication(context, binding)?.plan.sha256 !== plan.sha256)
+            refuse("intent_not_retained");
+        return { changed: true, plan };
+    });
+}
+/** Physical readback precedes the short SQL writer; the owner fences its
+ * accepted inputs in that writer. This receipt is not independent verification
+ * or terminal RUN acceptance. */
+export function completeDistillPublication(context, binding, assertAuthority) {
+    if (typeof assertAuthority !== "function")
+        refuse("authority_fence_required");
+    const retained = readDistillPublication(context, binding);
+    if (!retained)
+        refuse("intent_required");
+    const actual = retained.plan.classify(binding.write_scope.destination_root);
+    if (actual.completed !== actual.total)
+        refuse("publication_not_applied");
+    return context.db.writeTransaction(() => {
+        assertAuthority();
+        const current = readDistillPublication(context, binding);
+        if (!current || current.plan.sha256 !== retained.plan.sha256)
+            refuse("intent_changed");
+        // The authority fence may perform reads/callbacks. Never certify an earlier
+        // filesystem observation if the destination changed while it ran.
+        const observed = current.plan.classify(binding.write_scope.destination_root);
+        if (observed.completed !== observed.total)
+            refuse("publication_not_applied");
+        if (!current.completed)
+            appendAudit(context, { projectId: binding.project_id, eventType: completeEvent, payload: receipt(binding, current.plan, true) });
+        if (!readDistillPublication(context, binding)?.completed)
+            refuse("completion_not_retained");
+        return { changed: !current.completed, plan: current.plan, receipt: receipt(binding, current.plan, true) };
+    });
+}
+/** Read original completed intent for downstream Stage handoff, never infer a
+ * write scope from its result proposal or recapture today's destination. */
+export function readCompletedDistillPublication(context, expected) {
+    return context.db.readSnapshot(() => {
+        const row = context.db.get("SELECT value_json FROM runtime_config WHERE key=?", [key(expected)]);
+        if (!row || Buffer.byteLength(row.value_json) > 180 * 1024 * 1024)
+            refuse("completed_intent_required");
+        let binding;
+        try {
+            binding = JSON.parse(row.value_json).binding;
+        }
+        catch {
+            return refuse("invalid_retained_publication");
+        }
+        if (!binding || !binding.write_scope || !Array.isArray(binding.write_scope.paths)
+            || typeof binding.user_inputs_sha256 !== "string" || !/^[a-f0-9]{64}$/.test(binding.user_inputs_sha256)
+            || hybridDigest(binding) !== hybridDigest({ ...expected, write_scope: binding.write_scope, user_inputs_sha256: binding.user_inputs_sha256 }))
+            refuse("binding_changed");
+        const retained = readDistillPublication(context, binding);
+        if (!retained?.completed)
+            refuse("publication_not_complete");
+        return { binding: structuredClone(binding), plan: retained.plan, beforeDocuments: retained.beforeDocuments };
+    });
+}
+/** Serialization only, not proof of effects or Stage acceptance. Both publisher
+ * and handoff reader use exactly these bytes selected from committed intent. */
+export function distillPublicationArtifact(binding, plan) {
+    const encoded = JSON.parse(plan.bytes().toString("utf8"));
+    const after = JSON.parse(Buffer.from(encoded.after_base64, "base64").toString("utf8"));
+    return Buffer.from(JSON.stringify({ schema_id: "dd-flow/distill-publication@1", binding, plan_sha256: plan.sha256,
+        documents: after.entries.filter((entry) => binding.write_scope.paths.includes(entry.path)),
+        before_documents: distillBeforeDocumentReferences(plan), receipt: receipt(binding, plan, true) }));
+}
+/** Retained packet custody, not a file with a persuasive name. Return null only
+ * when publication has not retained this projection; conflicting custody refuses.
+ * Identical old retries remain readable, but publishers must not append more. */
+export function readDistillPublicationReference(context, binding, plan, logicalPath) {
+    if (!logicalPath || path.isAbsolute(logicalPath) || logicalPath.includes("\\") || logicalPath.split("/").some(part => !part || part === "." || part === ".."))
+        refuse("invalid_publication_locator");
+    const run = context.db.get("SELECT run_root FROM runs WHERE project_id=? AND id=?", [binding.project_id, binding.run_id]);
+    if (!run?.run_root)
+        refuse("run_home_required");
+    const file = path.join(run.run_root, logicalPath), bytes = distillPublicationArtifact(binding, plan), sha256 = createHash("sha256").update(bytes).digest("hex");
+    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,'$.stage')='promote' AND json_extract(payload_json,'$.attempt')=? LIMIT 33", [binding.project_id, binding.run_id, binding.attempt]);
+    if (rows.length > 32 || rows.some(row => Buffer.byteLength(row.payload_json) > 8 * 1024 * 1024))
+        refuse("unbounded_publication_packets");
+    const packets = rows.map(row => JSON.parse(row.payload_json)).filter(packet => typeof packet.file === "string"
+        && resolveStagePublicationPath(context, binding.project_id, binding.run_id, packet.file) === file);
+    if (!packets.length)
+        return null;
+    if (packets.some(packet => packet.sha256 !== sha256 || packet.base64 !== bytes.toString("base64")))
+        refuse("publication_packet_changed");
+    return { root: "run", path: logicalPath, sha256 };
+}

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) } } };
+        }) };
+}