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

package/dist/services/diagnostic-start.js

@@ -1,5 +1,6 @@
+import { createHash } from "node:crypto";
 import { AppError } from "../shared/errors.js";
-import { isDiagnosticFlow } from "../domain/diagnostic-flows.js";
+import { isSourceSnapshotFlow } from "../domain/source-snapshot-flows.js";
 import { PreparedInstalledFlowSource } from "./installed-flow-source.js";
 import { FrozenGenericExecution } from "./generic-execution.js";
 import { AdmittedFrozenEngine } from "./frozen-engine.js";
@@ -11,6 +12,7 @@ import { requireProjectByRoot } from "./projects.js";
 import { resolveProjectRoot } from "../storage/paths.js";
 import { hybridDigest } from "./hybrid-contracts.js";
 import { appendAudit } from "./audit.js";
+import { prepareReviewFixSourceIntake } from "./review-fix-intake-custody.js";
 const event = "diagnostic.request";
 function refuse(reason) { throw new AppError("diagnostic_request_invalid", "Diagnostic request requires its original frozen selection", 2, { reason, effect: "no_effect" }); }
 export function readDiagnosticRequest(context, scope) {
@@ -22,18 +24,47 @@ export function readDiagnosticRequest(context, scope) {
         refuse("ambiguous_request");
     const value = JSON.parse(rows[0].payload_json);
     if (value.schema_id !== "dd-flow/diagnostic-request@1" || value.project_id !== project.id
-        || hybridDigest(value.scope) !== hybridDigest(scope) || !isDiagnosticFlow(value.scope.flowId))
+        || hybridDigest(value.scope) !== hybridDigest(scope) || !isSourceSnapshotFlow(value.scope.flowId))
         refuse("request_scope_changed");
+    if (scope.flowId === "review-fix") {
+        try {
+            const source = value.repair_source;
+            if (!source || source.path !== "runtime/repair-intake.json" || typeof source.base64 !== "string"
+                || !/^[a-f0-9]{64}$/.test(source.sha256) || !Array.isArray(source.selection?.findingIds)
+                || !source.selection.findingIds.length || source.selection.findingIds.length > 4096)
+                refuse("repair_source_missing");
+            const bytes = Buffer.from(source.base64, "base64");
+            if (!bytes.length || bytes.length > 4 * 1024 * 1024 || bytes.toString("base64") !== source.base64
+                || createHash("sha256").update(bytes).digest("hex") !== source.sha256)
+                refuse("repair_source_changed");
+            const capsule = JSON.parse(new TextDecoder("utf-8", { fatal: true }).decode(bytes));
+            if (capsule.schema_id !== "dd-flow/review-fix-source-intake@1" || capsule.intake.authorization !== "not_granted"
+                || capsule.intake.source.id !== source.selection.sourceRunId
+                || hybridDigest(capsule.intake.selected_findings.map((finding) => finding.id)) !== hybridDigest(source.selection.findingIds))
+                refuse("repair_selection_changed");
+        }
+        catch (error) {
+            if (error instanceof AppError)
+                throw error;
+            return refuse("repair_source_invalid");
+        }
+    }
+    else if (value.repair_source !== undefined)
+        refuse("foreign_repair_source");
     return value;
 }
 /** Freeze all ambient choices before copying source or allocating a RUN. */
 export function retainDiagnosticRequest(context, input) {
     const { scope, source, execution, engine } = input;
     if (!(source instanceof PreparedInstalledFlowSource) || !(execution instanceof FrozenGenericExecution)
-        || !(engine instanceof AdmittedFrozenEngine) || !isDiagnosticFlow(scope.flowId) || !/^[A-Za-z0-9][A-Za-z0-9_.-]{0,95}$/.test(scope.requestId)
+        || !(engine instanceof AdmittedFrozenEngine) || !isSourceSnapshotFlow(scope.flowId) || !/^[A-Za-z0-9][A-Za-z0-9_.-]{0,95}$/.test(scope.requestId)
         || !input.objective.trim() || Buffer.byteLength(input.objective) > 64 * 1024)
         refuse("invalid_selection");
+    if ((scope.flowId === "review-fix") !== (input.repairSelection !== undefined))
+        refuse("repair_selection_required_only_for_review_fix");
     const project = requireProjectByRoot(context, scope.projectRoot), frozen = execution.snapshot();
+    if (scope.flowId === "review-fix" && frozen.settings.stage_session_mode === "same_session")
+        refuse("independent_scope_review_session_required");
     const workspace = diagnosticSnapshotRoot(context, { projectId: project.id, projectRoot: scope.projectRoot, sourceRoot: scope.projectRoot,
         requestId: scope.requestId, flowId: scope.flowId });
     if (frozen.scope.projectRoot !== scope.projectRoot || frozen.scope.requestId !== scope.requestId || frozen.scope.workspace !== workspace
@@ -41,15 +72,34 @@ export function retainDiagnosticRequest(context, input) {
         || frozen.settings.attached_session_receipt || frozen.settings.delegation.native_capacity_receipt)
         refuse("execution_selection_changed");
     source.revalidate();
-    engine.admitDiagnosticFlow(source, scope.flowId);
+    if (scope.flowId === "review-fix")
+        engine.admitReviewFixFlow(source);
+    else if (scope.flowId === "mb-distill")
+        engine.admitDistillFlow(source);
+    else
+        engine.admitDiagnosticFlow(source, scope.flowId);
     const manifest = engine.manifest();
     if (typeof manifest.integrity.checksum !== "string")
         refuse("engine_identity_missing");
+    let repairSource;
+    if (scope.flowId === "review-fix") {
+        const prior = readDiagnosticRequest(context, scope);
+        if (prior) {
+            if (hybridDigest(prior.repair_source.selection) !== hybridDigest(input.repairSelection))
+                refuse("repair_selection_changed");
+            repairSource = prior.repair_source;
+        }
+        else {
+            const prepared = prepareReviewFixSourceIntake(context, { projectRoot: scope.projectRoot, ...input.repairSelection });
+            repairSource = { selection: structuredClone(input.repairSelection), path: prepared.path, sha256: prepared.sha256, base64: prepared.bytes.toString("base64") };
+        }
+    }
     const value = { schema_id: "dd-flow/diagnostic-request@1", project_id: project.id, scope: structuredClone(scope),
         created_at: context.now(), objective: input.objective, selection: structuredClone(input.selection),
         source: source.snapshot(), source_sha256: source.sha256, execution: frozen, execution_sha256: execution.sha256,
         engine: { identity: { package_name: manifest.package_name, package_version: manifest.package_version, engine_version: manifest.engine_version,
-                integrity_checksum: manifest.integrity.checksum, snapshot_root: manifest.snapshot_root }, manifest_sha256: engine.manifestSha256 } };
+                integrity_checksum: manifest.integrity.checksum, snapshot_root: manifest.snapshot_root }, manifest_sha256: engine.manifestSha256 },
+        ...(repairSource ? { repair_source: repairSource } : {}) };
     if (Buffer.byteLength(JSON.stringify(value)) > 48 * 1024 * 1024)
         refuse("request_exceeds_bound");
     return context.db.writeTransaction(() => {
@@ -79,6 +129,6 @@ export function startDiagnosticRun(context, scope) {
         requestId: scope.requestId, projectRoot: scope.projectRoot, workspace: snapshot.root
     });
     const engine = AdmittedFrozenEngine.admitSelection(retained.engine.identity, retained.engine.manifest_sha256);
-    const bundle = prepareDiagnosticRunBundle(context, { source, execution, engine, boundAt: retained.created_at });
+    const bundle = prepareDiagnosticRunBundle(context, { source, execution, engine, boundAt: retained.created_at, requestText: retained.objective });
     return PreparedDescriptorRunStart.prepare(context, { bundle }).apply(context);
 }

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

@@ -17,7 +17,7 @@ export function assertDiagnosticSessionIndependence(workers, excluded) {
         || new Set(keys).size !== keys.length || keys.some(key => excludedKeys.has(key)))
         refuse("physical_session_reused");
 }
-function completedWork(context, scope, workId) {
+export function readCompletedResearchWork(context, scope, workId) {
     const work = context.db.get("SELECT status,result FROM works WHERE project_id=? AND run_id=? AND work_id=?", [scope.projectId, scope.runId, workId]);
     if (work?.status !== "completed" || !work.result || Buffer.byteLength(work.result) > 1024 * 1024)
         refuse("work_not_completed");
@@ -36,12 +36,12 @@ function collectSql(context, scope, rootId) {
     if (!graph || graph.parent_work_id !== rootId)
         refuse("registration_required");
     const batch = diagnosticWorkBatch(graph.input);
-    const works = batch.works.map(item => completedWork(context, scope, graph.work_ids[item.key]));
+    const works = batch.works.map(item => readCompletedResearchWork(context, scope, graph.work_ids[item.key]));
     const coordinators = context.db.all("SELECT s.harness,s.provider_session_id FROM work_sessions ws JOIN sessions s ON s.project_id=? AND s.run_id=? AND s.session_id=ws.session_id WHERE ws.work_id=?", [scope.projectId, scope.runId, rootId]);
     const authorGraph = scope.stage === "review" ? readRegisteredDiagnosticGraph(context, { ...scope, stage: graph.input.flow_id === "mb-audit" ? "audit" : "analyze" }) : null;
     if (scope.stage === "review" && !authorGraph)
         refuse("author_graph_missing");
-    const authors = authorGraph ? Object.values(authorGraph.work_ids).map(id => completedWork(context, scope, id)) : [];
+    const authors = authorGraph ? Object.values(authorGraph.work_ids).map(id => readCompletedResearchWork(context, scope, id)) : [];
     assertDiagnosticSessionIndependence(works.map(value => value.session), [...coordinators, ...authors.map(value => value.session)]);
     return { graph, works, authors, coordinators };
 }

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