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

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

@@ -0,0 +1,280 @@
+import fs from "node:fs";
+import path from "node:path";
+import { createHash } from "node:crypto";
+import { AppError } from "../shared/errors.js";
+import { hybridDigest } from "./hybrid-contracts.js";
+import { MemoryRepairDocumentBaseline, orderMemoryDocumentEntries } from "./memory-repair-document-delta.js";
+import { RetainedMemoryRepairPublicationPlan } from "./memory-repair-publication-plan.js";
+import { stageRetainedMemoryRepairFile, verifyRetainedMemoryRepairFile } from "./memory-repair-publication-files.js";
+import { acquireInstallationLock } from "./installation-lock.js";
+import { publishImmutableInput } from "../storage/immutable-input.js";
+import { ObservedMemorySources } from "./memory-source-observations.js";
+const hash = (bytes) => createHash("sha256").update(bytes).digest("hex");
+function refuse(reason) {
+    throw new AppError("distill_publication_invalid", "Distillation publication requires its exact retained document plan", 2, { reason, effect: "no_effect" });
+}
+function beforeFiles(plan) {
+    const encoded = JSON.parse(plan.bytes().toString("utf8"));
+    const before = JSON.parse(Buffer.from(encoded.before_base64, "base64").toString("utf8"));
+    return before.entries.filter((entry) => entry.kind === "file" && before.write_paths.includes(entry.path))
+        .map((entry) => ({ path: entry.path, sha256: entry.sha256 }));
+}
+/** Selected original text only. Protected neighboring/private document bytes
+ * must never be exported as verifier context. No destination write occurs. */
+export function captureDistillBeforeDocuments(root, plan) {
+    const selected = beforeFiles(plan), observed = ObservedMemorySources.capture({ workspace: root }, selected.map(entry => ({ root: "workspace", path: entry.path })));
+    return validateDistillBeforeDocuments(plan, selected.map(entry => ({ ...entry, base64: observed.bytes({ root: "workspace", path: entry.path }).toString("base64") })));
+}
+/** SQL decoding is filesystem-free. The original before-view, not a fresh file,
+ * determines exact membership and hashes, including originally empty files. */
+export function validateDistillBeforeDocuments(plan, value) {
+    const expected = beforeFiles(plan);
+    if (!Array.isArray(value) || value.length !== expected.length || value.length > 4096)
+        refuse("original_documents_required");
+    let total = 0;
+    const seen = new Set();
+    for (const document of value) {
+        if (!document || typeof document !== "object" || Object.keys(document).sort().join() !== "base64,path,sha256"
+            || typeof document.base64 !== "string" || document.base64.length > 24 * 1024 * 1024 || seen.has(document.path)
+            || !expected.some(entry => entry.path === document.path && entry.sha256 === document.sha256))
+            refuse("original_document_changed");
+        const bytes = Buffer.from(document.base64, "base64");
+        total += bytes.length;
+        if (bytes.length > 16 * 1024 * 1024 || total > 64 * 1024 * 1024 || bytes.toString("base64") !== document.base64 || hash(bytes) !== document.sha256)
+            refuse("original_document_changed");
+        seen.add(document.path);
+    }
+    const byPath = new Map(value.map(document => [document.path, document]));
+    return expected.map(entry => ({ ...entry, base64: byPath.get(entry.path).base64 }));
+}
+export function distillBeforeDocumentReferences(plan) {
+    return beforeDocumentReferences(plan, "distill");
+}
+export function memoryFixBeforeDocumentReferences(plan) {
+    return beforeDocumentReferences(plan, "memory-fix");
+}
+function beforeDocumentReferences(plan, namespace) {
+    return beforeFiles(plan).map(entry => ({ destination_path: entry.path,
+        source: { root: "run", path: `artifacts/${namespace}/before/${entry.sha256}.md`, sha256: entry.sha256 } }));
+}
+/** Restore original verifier inputs from retained SQL bytes before target
+ * effects, including after a lost projection. Never read the changed target. */
+export function publishDistillBeforeDocuments(runRoot, plan, documents) {
+    return publishBeforeDocuments(runRoot, plan, documents, "distill");
+}
+export function publishMemoryFixBeforeDocuments(runRoot, plan, documents) {
+    return publishBeforeDocuments(runRoot, plan, documents, "memory-fix");
+}
+function publishBeforeDocuments(runRoot, plan, documents, family) {
+    const retained = validateDistillBeforeDocuments(plan, documents);
+    if (!retained.length)
+        return;
+    if (!path.isAbsolute(runRoot) || fs.realpathSync(runRoot) !== runRoot || !fs.lstatSync(runRoot).isDirectory())
+        refuse("unsafe_baseline_home");
+    const artifacts = privateDirectory(runRoot, "artifacts"), namespace = privateDirectory(artifacts, family), directory = privateDirectory(namespace, "before");
+    for (const document of retained)
+        publishImmutableInput(path.join(directory, `${document.sha256}.md`), Buffer.from(document.base64, "base64"), "distill_before_document_conflict");
+}
+/** Physical plan only, not scope approval or RUN/Work authority. The caller
+ * independently selects canonical exceptions and retains this plan in SQL
+ * before any apply. Capture protects the entire destination Memory Bank,
+ * including unrelated files and opaque private/link entries. */
+export function prepareDistillDocumentPlan(destinationRoot, outputs, canonicalPaths = new Set()) {
+    return prepareDocumentPlan(destinationRoot, outputs, canonicalPaths, "distill");
+}
+/** Physical bounded repair plan only. A null output explicitly requests removal
+ * of that selected existing document. Intake/Work/user authority belongs to the
+ * caller; this helper never expands selection or admits canonical exceptions. */
+export function prepareMemoryFixDocumentPlan(destinationRoot, outputs) {
+    return prepareDocumentPlan(destinationRoot, outputs, new Set(), "memory_fix");
+}
+function prepareDocumentPlan(destinationRoot, outputs, canonicalPaths, family) {
+    const refuse = (reason) => { throw new AppError(`${family}_publication_invalid`, "Publication requires its exact retained document plan", 2, { reason, effect: "no_effect" }); };
+    if (!outputs.length || outputs.length > 4096 || new Set(outputs.map(output => output.path)).size !== outputs.length)
+        refuse("invalid_output_selection");
+    let total = 0;
+    for (const output of outputs) {
+        if (output.bytes === null && family === "memory_fix")
+            continue;
+        if (!(output.bytes instanceof Uint8Array) || output.bytes.length > 16 * 1024 * 1024 || (total += output.bytes.length) > 64 * 1024 * 1024)
+            refuse("unbounded_output");
+        try {
+            new TextDecoder("utf-8", { fatal: true }).decode(output.bytes);
+        }
+        catch {
+            refuse("non_text_document");
+        }
+    }
+    const selected = [...outputs].sort((a, b) => a.path < b.path ? -1 : a.path > b.path ? 1 : 0);
+    const before = MemoryRepairDocumentBaseline.capture(destinationRoot, selected.map(output => output.path), canonicalPaths);
+    const entries = new Map(before.entries().map(entry => [entry.path, entry]));
+    const actions = [];
+    for (const output of selected) {
+        if (output.bytes === null) {
+            const prior = entries.get(output.path);
+            if (!prior || prior.kind !== "file")
+                return refuse("delete_requires_existing_document");
+            entries.delete(output.path);
+            actions.push({ path: output.path, before: prior, after: null, bytes_base64: null });
+            continue;
+        }
+        const parts = output.path.split("/");
+        for (let length = 1; length < parts.length; length++) {
+            const logical = parts.slice(0, length).join("/");
+            if (!entries.has(logical)) {
+                const after = { path: logical, kind: "directory", mode: 0o755, sha256: null };
+                entries.set(logical, after);
+                actions.push({ path: logical, before: null, after, bytes_base64: null });
+            }
+        }
+        const prior = entries.get(output.path) ?? null;
+        const after = { path: output.path, kind: "file", mode: prior?.mode ?? 0o644, sha256: hash(output.bytes) };
+        if (hybridDigest(prior) === hybridDigest(after))
+            continue;
+        entries.set(output.path, after);
+        actions.push({ path: output.path, before: prior, after, bytes_base64: Buffer.from(output.bytes).toString("base64") });
+    }
+    const beforeData = JSON.parse(before.bytes().toString("utf8"));
+    const afterMaterial = { ...beforeData, entries: orderMemoryDocumentEntries(entries.values()) };
+    const after = MemoryRepairDocumentBaseline.restore(Buffer.from(JSON.stringify(afterMaterial)), hybridDigest({ ...afterMaterial, schema_id: undefined }));
+    const receipt = { before_sha256: before.sha256, before_base64: before.bytes().toString("base64"),
+        after_sha256: after.sha256, after_base64: after.bytes().toString("base64"), actions };
+    before.revalidate(destinationRoot);
+    return RetainedMemoryRepairPublicationPlan.restore(Buffer.from(JSON.stringify(receipt)), hybridDigest(receipt));
+}
+function privateDirectory(parent, name) {
+    const directory = path.join(parent, name);
+    if (!fs.lstatSync(directory, { throwIfNoEntry: false }))
+        fs.mkdirSync(directory, { mode: 0o700 });
+    const stat = fs.lstatSync(directory);
+    if (!stat.isDirectory() || fs.realpathSync(directory) !== directory)
+        refuse("unsafe_staging_directory");
+    return directory;
+}
+function syncDirectory(directory) {
+    const fd = fs.openSync(directory, fs.constants.O_RDONLY | (fs.constants.O_NOFOLLOW ?? 0));
+    try {
+        fs.fsyncSync(fd);
+    }
+    finally {
+        fs.closeSync(fd);
+    }
+}
+/** One recoverable physical step of an independently retained plan. This
+ * grants no publication authority: its owner must fence SQL/source/scope
+ * custody on every call, then retain the actual completion separately.
+ * A changed prefix is never recaptured or overwritten on retry. */
+export function applyDistillDocumentStep(destinationRoot, plan, assertAuthority) {
+    return applyDocumentStep(destinationRoot, plan, assertAuthority, "distill");
+}
+/** Same prefix/recovery mechanics as distill, with selected removals moved into
+ * private staging rather than erased. No Stage or publication authority here. */
+export function applyMemoryFixDocumentStep(destinationRoot, plan, assertAuthority) {
+    return applyDocumentStep(destinationRoot, plan, assertAuthority, "memory_fix");
+}
+function applyDocumentStep(destinationRoot, plan, assertAuthority, family) {
+    const refuse = (reason) => { throw new AppError(`${family}_publication_invalid`, "Publication requires its exact retained document plan", 2, { reason, effect: "no_effect" }); };
+    if (!(plan instanceof RetainedMemoryRepairPublicationPlan) || typeof assertAuthority !== "function")
+        refuse("retained_plan_and_authority_required");
+    const actions = plan.actions();
+    if (family === "distill" && actions.some(action => !action.after))
+        refuse("distillation_does_not_delete_documents");
+    assertAuthority();
+    const initial = plan.classify(destinationRoot);
+    const removedDirectory = path.join(destinationRoot, ".dd-flow/memory-fix-publications", plan.sha256);
+    for (const [index, action] of actions.slice(0, initial.completed).entries())
+        if (!action.after) {
+            if (fs.realpathSync(removedDirectory) !== removedDirectory || (fs.lstatSync(removedDirectory).mode & 0o7777) !== 0o700)
+                refuse("removed_document_custody_changed");
+            const logical = `removed-${index}.md`, location = { root: "workspace", path: logical };
+            const original = ObservedMemorySources.capture({ workspace: removedDirectory }, [location]);
+            const stat = fs.lstatSync(path.join(removedDirectory, logical));
+            if (hash(original.bytes(location)) !== action.before.sha256 || !stat.isFile() || stat.nlink !== 1
+                || (stat.mode & 0o7777) !== action.before.mode)
+                refuse("removed_document_custody_changed");
+            syncDirectory(removedDirectory);
+        }
+    for (const action of actions.slice(0, initial.completed))
+        syncDirectory(path.dirname(path.join(destinationRoot, action.path)));
+    if (initial.completed === initial.total) {
+        assertAuthority();
+        return { ...initial, status: "applied", replayed: true };
+    }
+    const service = privateDirectory(destinationRoot, ".dd-flow"), namespace = privateDirectory(service, family === "distill" ? "distill-publications" : "memory-fix-publications");
+    const directory = privateDirectory(namespace, plan.sha256);
+    if ((fs.lstatSync(directory).mode & 0o7777) !== 0o700)
+        refuse("nonprivate_staging_directory");
+    publishImmutableInput(path.join(directory, "owner.json"), Buffer.from(JSON.stringify({ schema_id: family === "distill" ? "dd-flow/distill-document-staging@1" : "dd-flow/memory-fix-document-staging@1", destination_root: destinationRoot, plan_sha256: plan.sha256 })), `${family}_staging_conflict`);
+    const lock = acquireInstallationLock(path.join(namespace, "destination.lock"), plan.sha256);
+    let effected = false, released = false;
+    const release = () => { lock.release(); released = true; };
+    try {
+        lock.assertOwnership();
+        assertAuthority();
+        const current = plan.classify(destinationRoot);
+        if (current.completed !== initial.completed)
+            refuse("publication_cursor_changed");
+        const action = actions[current.completed], destination = path.join(destinationRoot, action.path);
+        if (!action.after) {
+            const removed = path.join(directory, `removed-${current.completed}.md`);
+            if (fs.lstatSync(removed, { throwIfNoEntry: false }))
+                refuse("foreign_removed_document");
+            assertAuthority();
+            lock.assertOwnership();
+            if (plan.classify(destinationRoot).completed !== current.completed)
+                refuse("publication_cursor_changed");
+            effected = true;
+            fs.renameSync(destination, removed);
+            syncDirectory(directory);
+        }
+        else if (action.after.kind === "file") {
+            const staged = stageRetainedMemoryRepairFile(directory, `action-${current.completed}.tmp`, plan.output(action.path), action.after.mode);
+            verifyRetainedMemoryRepairFile(staged.path, plan.output(action.path), action.after.mode);
+            assertAuthority();
+            lock.assertOwnership();
+            if (plan.classify(destinationRoot).completed !== current.completed)
+                refuse("publication_cursor_changed");
+            effected = true;
+            fs.renameSync(staged.path, destination);
+            syncDirectory(directory);
+        }
+        else {
+            const staged = path.join(directory, `directory-${current.completed}.tmp`);
+            if (!fs.lstatSync(staged, { throwIfNoEntry: false }))
+                fs.mkdirSync(staged, { mode: 0o700 });
+            const stat = fs.lstatSync(staged);
+            if (!stat.isDirectory() || fs.realpathSync(staged) !== staged || fs.readdirSync(staged).length
+                || ![0o700, action.after.mode].includes(stat.mode & 0o7777))
+                refuse("foreign_staged_directory");
+            fs.chmodSync(staged, action.after.mode);
+            syncDirectory(staged);
+            assertAuthority();
+            lock.assertOwnership();
+            if (plan.classify(destinationRoot).completed !== current.completed)
+                refuse("publication_cursor_changed");
+            effected = true;
+            fs.renameSync(staged, destination);
+            syncDirectory(directory);
+        }
+        syncDirectory(path.dirname(destination));
+        const observed = plan.classify(destinationRoot);
+        if (observed.completed !== current.completed + 1)
+            refuse("unexpected_publication_effect");
+        release();
+        return { ...observed, status: observed.completed === observed.total ? "applied" : "partial", replayed: false };
+    }
+    catch (error) {
+        let releaseFailure;
+        if (!released)
+            try {
+                release();
+            }
+            catch (failure) {
+                releaseFailure = failure instanceof Error ? failure.message : String(failure);
+            }
+        if (!effected && !releaseFailure)
+            throw error;
+        throw new AppError(`${family}_publication_pending`, "Reconcile the same retained publication; do not prepare a new baseline", 1, { effect: effected ? "publication_pending" : "no_effect", plan_sha256: plan.sha256, cause: error instanceof Error ? error.message : String(error),
+            ...(releaseFailure ? { release_failure: releaseFailure } : {}) });
+    }
+}

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