@deksden-com/dd-flow-cli 0.9.0-beta.152 → 0.9.0-beta.156

package/dist/services/distill-promotion.js

@@ -0,0 +1,197 @@
+import fs from "node:fs";
+import path from "node:path";
+import { createHash } from "node:crypto";
+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 { readAcceptedStageData, prepareStagePacket, acceptStagePacket, publishStagePacket } from "./stage-report-renderer.js";
+import { diagnosticSnapshotPaths, readDiagnosticSnapshot, readDiagnosticSnapshotCustody } from "./diagnostic-snapshot.js";
+import { validateDistillStageResult } from "./distill-stage-results.js";
+import { PreparedDistillWorkCollection } from "./distill-work-collection.js";
+import { collectDistillCandidates } from "./distill-work-results.js";
+import { readDistillUserInputs } from "./distill-user-inputs.js";
+import { readPreparedMemoryFlowUserInputs } from "./memory-flow-user-inputs.js";
+import { prepareDistillDocumentPlan, applyDistillDocumentStep, captureDistillBeforeDocuments, publishDistillBeforeDocuments } from "./distill-document-publication.js";
+import { readDistillPublication, retainDistillPublication, completeDistillPublication, distillPublicationArtifact, readDistillPublicationReference } from "./distill-publication-custody.js";
+import { hybridDigest } from "./hybrid-contracts.js";
+function refuse(reason) {
+    throw new AppError("distill_promotion_invalid", "Promotion requires accepted review, delivered agreement and its exact destination", 2, { reason, effect: "no_effect" });
+}
+const hash = (bytes) => createHash("sha256").update(bytes).digest("hex");
+const within = (root, target) => { const relative = path.relative(root, target); return !relative || !path.isAbsolute(relative) && relative !== ".." && !relative.startsWith(`..${path.sep}`); };
+function destination(root, protectedRoots) {
+    if (!path.isAbsolute(root) || path.resolve(root) !== root || fs.realpathSync(root) !== root || !fs.lstatSync(root).isDirectory())
+        refuse("physical_destination_required");
+    for (const protectedRoot of protectedRoots) {
+        const resolved = fs.existsSync(protectedRoot) ? fs.realpathSync(protectedRoot) : path.resolve(protectedRoot);
+        if (within(resolved, root) || within(root, resolved))
+            refuse("destination_overlaps_source_or_runtime");
+    }
+    const stat = fs.lstatSync(root);
+    return { dev: stat.dev, ino: stat.ino };
+}
+/** The coordinator owns the semantic interpretation of agreement and proposed
+ * wording. This owner admits only actual user-source references and accepted
+ * independently reviewed candidates, then fences the full input set on effects.
+ * It does not infer agreement from a file named approval or from critic votes.
+ * No public launch/handler registration is implied by this internal owner. */
+export class PreparedDistillPromotion {
+    #binding;
+    #plan;
+    #fence;
+    #publication;
+    #beforeDocuments;
+    #runRoot;
+    constructor(binding, plan, fence, publication, beforeDocuments, runRoot) {
+        this.#binding = structuredClone(binding);
+        this.#plan = plan;
+        this.#fence = fence;
+        this.#publication = { ...publication };
+        Object.freeze(this);
+        this.#beforeDocuments = structuredClone(beforeDocuments);
+        this.#runRoot = runRoot;
+    }
+    static prepare(context, input) {
+        if (!input.proposal || typeof input.proposal !== "object" || Array.isArray(input.proposal))
+            refuse("invalid_proposal_json");
+        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: "promote" };
+        const stageInput = readDescriptorStageInput(context, scope, bundle);
+        if (stageInput.input.predecessor?.stage !== "review")
+            refuse("accepted_review_required");
+        const accepted = readAcceptedStageData(context, { ...scope, stage: "review" });
+        if (hybridDigest(stageInput.input.predecessor.result) !== hybridDigest(accepted.result))
+            refuse("review_predecessor_changed");
+        const frozen = bundle.execution.snapshot().scope, 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("source_snapshot_required");
+        const reviewInput = readDescriptorStageInput(context, { ...scope, stage: "review" }, bundle, true, true);
+        const review = validateDistillStageResult(accepted.bytes, bundle.descriptor.stageBlob("review", "result_schema"), {
+            runId: input.runId, stage: "review", inputSha256: reviewInput.inputSha256, snapshotSha256: snapshot.source_sha256,
+            snapshotRoot: diagnosticSnapshotPaths(context, snapshot, input.runId).root, runRoot: stageInput.runRoot,
+            support: bundle.manifest.inventory.filter(ref => ref.path.startsWith("support/")), writeScope: null, promotionReceipt: null,
+            predecessors: reviewInput.input.predecessor ? [{ stage: reviewInput.input.predecessor.stage, ...reviewInput.input.predecessor.result }] : []
+        });
+        const authors = PreparedDistillWorkCollection.prepare(context, { ...input, stage: "extract" });
+        const critics = PreparedDistillWorkCollection.prepare(context, { ...input, stage: "review" }), criticResults = critics.results();
+        if (hybridDigest(review.details.candidates) !== hybridDigest(collectDistillCandidates(authors.results()).candidates))
+            refuse("review_candidates_changed");
+        for (const decision of review.details.decisions) {
+            if (!criticResults.some(work => work.result.decisions.some(vote => vote.candidate_id === decision.candidate_id && vote.disposition === decision.disposition)))
+                refuse("unsupported_review_resolution");
+        }
+        const users = readDistillUserInputs(context, input, bundle), proposal = structuredClone(input.proposal), selected = proposal.write_scope;
+        if (proposal.user_inputs_sha256 !== hybridDigest(users))
+            refuse("user_inputs_changed");
+        if (!selected || typeof selected.destination_root !== "string" || !Array.isArray(selected.candidate_ids) || !selected.candidate_ids.length
+            || new Set(selected.candidate_ids).size !== selected.candidate_ids.length || !Array.isArray(selected.paths) || !selected.paths.length
+            || new Set(selected.paths).size !== selected.paths.length || selected.paths.some(value => typeof value !== "string") || !selected.approval_source
+            || selected.approval_source.root !== "run" || !users.sources.some(source => ["request", "answer"].includes(source.role)
+            && source.path === selected.approval_source.path && source.sha256 === selected.approval_source.sha256))
+            refuse("delivered_agreement_required");
+        if (selected.candidate_ids.some(id => !review.details.decisions.some(decision => decision.candidate_id === id && ["adopt", "adapt"].includes(decision.disposition))))
+            refuse("unaccepted_candidate");
+        if (!Array.isArray(proposal.outputs) || !proposal.outputs.length || proposal.outputs.length > 4096
+            || proposal.outputs.some(output => !output || typeof output.content !== "string" || !selected.paths.includes(output.path)
+                || !Array.isArray(output.candidate_ids) || !output.candidate_ids.length || new Set(output.candidate_ids).size !== output.candidate_ids.length
+                || output.candidate_ids.some(id => !selected.candidate_ids.includes(id)))
+            || hybridDigest(proposal.outputs.map(output => output.path).sort()) !== hybridDigest([...selected.paths].sort())
+            || selected.candidate_ids.some(id => !proposal.outputs.some(output => output.candidate_ids.includes(id))))
+            refuse("output_scope_changed");
+        if (proposal.outputs.some(output => Buffer.byteLength(output.content) > 16 * 1024 * 1024)
+            || proposal.outputs.reduce((sum, output) => sum + Buffer.byteLength(output.content), 0) > 64 * 1024 * 1024)
+            refuse("unbounded_output");
+        const protectedRoots = [frozen.projectRoot, frozen.workspace, stageInput.runRoot, context.ddFlowHome];
+        const physical = destination(selected.destination_root, protectedRoots);
+        const binding = { project_id: project.id, run_id: input.runId, attempt: stageInput.attempt,
+            input_sha256: stageInput.inputSha256, bundle_sha256: bundle.sha256, review_sha256: accepted.result.sha256,
+            user_inputs_sha256: proposal.user_inputs_sha256, write_scope: selected };
+        const previous = readDistillPublication(context, binding);
+        const outputs = proposal.outputs.map(output => ({ path: output.path, bytes: Buffer.from(output.content) }));
+        const plan = previous?.plan ?? prepareDistillDocumentPlan(selected.destination_root, outputs, new Set(selected.paths));
+        const beforeDocuments = previous?.beforeDocuments ?? captureDistillBeforeDocuments(selected.destination_root, plan);
+        // Replay compares proposed bytes with the retained after-view; it never
+        // recaptures a partly changed destination or replaces the original intent.
+        const encoded = JSON.parse(plan.bytes().toString("utf8"));
+        const after = JSON.parse(Buffer.from(encoded.after_base64, "base64").toString("utf8"));
+        if (outputs.some(output => !after.entries.some((entry) => entry.path === output.path && entry.kind === "file" && entry.sha256 === hash(output.bytes))))
+            refuse("original_outputs_required");
+        const fence = (writer) => {
+            assertPreparedRunBundleSqlAuthority(writer, scope, bundle);
+            if (hybridDigest(readDescriptorStageInput(writer, scope, bundle)) !== hybridDigest(stageInput)
+                || hybridDigest(readAcceptedStageData(writer, { ...scope, stage: "review" })) !== hybridDigest(accepted)
+                || hybridDigest(readDiagnosticSnapshotCustody(writer, snapshotScope, input.runId)) !== hybridDigest(snapshot)
+                || hybridDigest(readPreparedMemoryFlowUserInputs(writer, scope, "mb-distill", bundle)) !== proposal.user_inputs_sha256
+                || hybridDigest(destination(selected.destination_root, protectedRoots)) !== hybridDigest(physical))
+                refuse("promotion_authority_changed");
+            authors.assertCustody(writer);
+            critics.assertCustody(writer);
+        };
+        const logical = `${bundle.descriptor.stage("promote").directory}/publication.json`;
+        return new PreparedDistillPromotion(binding, plan, fence, { file: path.join(stageInput.runRoot, logical), logical }, beforeDocuments, stageInput.runRoot);
+    }
+    binding() { return structuredClone(this.#binding); }
+    assertCustody(context) { this.#fence(context); }
+    applyStep(context) {
+        const fence = () => this.#fence(context), root = this.#binding.write_scope.destination_root;
+        retainDistillPublication(context, this.#binding, this.#plan, fence, this.#beforeDocuments);
+        publishDistillBeforeDocuments(this.#runRoot, this.#plan, this.#beforeDocuments);
+        const result = applyDistillDocumentStep(root, this.#plan, fence);
+        if (result.status !== "applied")
+            return { ...result, status: "partial" };
+        try {
+            const completed = completeDistillPublication(context, this.#binding, fence);
+            return { ...result, status: "applied", receipt: completed.receipt };
+        }
+        catch (error) {
+            // Files may already be published even though the final SQL observation
+            // failed. Do not report no_effect or let a caller replace the old intent.
+            throw new AppError("distill_publication_pending", "Reconcile the retained publication before claiming completion", 1, { effect: "publication_pending", plan_sha256: this.#plan.sha256, cause: error instanceof Error ? error.message : String(error) });
+        }
+    }
+    apply(context) {
+        const maximum = this.#plan.actions().length;
+        for (let step = 0; step <= maximum; step++) {
+            const result = this.applyStep(context);
+            if (result.status !== "applied")
+                continue;
+            try {
+                const packet = prepareStagePacket(this.#publication.file, distillPublicationArtifact(this.#binding, this.#plan));
+                context.db.writeTransaction(() => {
+                    this.#fence(context);
+                    const completed = readDistillPublication(context, this.#binding);
+                    if (!completed?.completed || completed.plan.sha256 !== this.#plan.sha256)
+                        refuse("completed_publication_required");
+                    if (!readDistillPublicationReference(context, this.#binding, this.#plan, this.#publication.logical))
+                        acceptStagePacket(context, { projectId: this.#binding.project_id, runId: this.#binding.run_id, stage: "promote", prepared: packet });
+                });
+                publishStagePacket(context, this.#binding.project_id, this.#binding.run_id, "promote", packet.file);
+                return { ...result, publication: { root: "run", path: this.#publication.logical, sha256: packet.sha256 } };
+            }
+            catch (error) {
+                throw new AppError("distill_publication_pending", "Published documents require their retained result projection before Stage acceptance", 1, { effect: "publication_pending", plan_sha256: this.#plan.sha256, cause: error instanceof Error ? error.message : String(error) });
+            }
+        }
+        return refuse("publication_did_not_progress");
+    }
+}
+export function publishDistillFromStage(context, input) {
+    if (!input.bytes.length || input.bytes.length > 1024 * 1024)
+        refuse("unbounded_proposal");
+    let proposal;
+    try {
+        proposal = JSON.parse(new TextDecoder("utf-8", { fatal: true }).decode(input.bytes));
+    }
+    catch {
+        return refuse("invalid_proposal_json");
+    }
+    if (!proposal || typeof proposal !== "object" || Array.isArray(proposal))
+        refuse("invalid_proposal_json");
+    return PreparedDistillPromotion.prepare(context, { projectRoot: input.projectRoot, runId: input.runId, proposal }).apply(context);
+}

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