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

package/dist/services/memory-fix-sources.js

@@ -0,0 +1,85 @@
+import { AppError } from "../shared/errors.js";
+import { resolveProjectRoot } from "../storage/paths.js";
+import { hybridDigest } from "./hybrid-contracts.js";
+import { readDiagnosticRepairIntake } from "./diagnostic-repair-intake.js";
+import { ObservedMemorySources } from "./memory-source-observations.js";
+import { memorySourceKey } from "./memory-stage-results.js";
+import { MemoryRepairDocumentBaseline } from "./memory-repair-document-delta.js";
+function refuse(reason) {
+    throw new AppError("memory_fix_source_invalid", "Memory repair source observations changed or exceed their bounds", 2, { reason, effect: "no_effect" });
+}
+/** Only selected target metadata, including absence, becomes intake authority.
+ * Neighboring current documents remain protected by the later publication plan
+ * but unrelated edits do not invalidate target approval by themselves. */
+export function observeMemoryFixWriteTargets(projectRoot, paths) {
+    if (!paths.length)
+        return [];
+    const baseline = MemoryRepairDocumentBaseline.capture(projectRoot, paths);
+    return memoryFixWriteTargetsFromBaseline(baseline);
+}
+export function memoryFixWriteTargetsFromBaseline(baseline) {
+    const value = JSON.parse(baseline.bytes().toString("utf8"));
+    const entries = new Map(baseline.entries().map(entry => [entry.path, entry]));
+    return value.write_paths.slice().sort().map(logical => ({ path: logical, before: entries.get(logical) ?? null }));
+}
+/** Read-only drift evidence, never a replacement for the original finding or
+ * permission to repair/close it. The Stage owner must assess drift and revalidate
+ * this same observation before admitting any writer. Unavailable is not unchanged.
+ */
+export function observeMemoryFixSources(context, input) {
+    return observeSources(resolveProjectRoot(input.projectRoot), () => readDiagnosticRepairIntake(context, input));
+}
+/** The handler must first admit this intake from its own frozen RUN bundle.
+ * A scoped restore need not contain the neighboring source audit's SQL rows.
+ * This helper grants no intake/approval authority and never searches another Home.
+ */
+export function observeRetainedMemoryFixSources(projectRoot, intake) {
+    const retained = structuredClone(intake);
+    return observeSources(resolveProjectRoot(projectRoot), () => retained);
+}
+function observeSources(projectRoot, readIntake) {
+    const capture = () => {
+        const intake = readIntake(), references = new Map();
+        for (const finding of intake.selected_findings) {
+            for (const reference of [...finding.evidence, ...finding.resolution.evidence,
+                ...finding.critic_decisions.flatMap(critic => critic.decision.evidence)]) {
+                if (typeof reference.path !== "string" || reference.path.length > 4096 || reference.path.split("/").includes(".git")
+                    || !/^[a-f0-9]{64}$/.test(reference.sha256))
+                    refuse("invalid_original_source");
+                if (references.has(reference.path) && references.get(reference.path) !== reference.sha256)
+                    refuse("conflicting_original_source");
+                references.set(reference.path, reference.sha256);
+            }
+        }
+        if (references.size > 20_000)
+            refuse("source_inventory_exceeds_bound");
+        let total = 0;
+        const observations = [...references].sort(([a], [b]) => a < b ? -1 : a > b ? 1 : 0).map(([path, original_sha256]) => {
+            try {
+                const location = { root: "project", path };
+                const observed = ObservedMemorySources.capture({ project: projectRoot }, [location]);
+                total += observed.bytes(location).length;
+                if (total > 64 * 1024 * 1024)
+                    refuse("source_bytes_exceed_bound");
+                const current_sha256 = observed.hashes().get(memorySourceKey("project", path));
+                return { path, original_sha256, current_sha256,
+                    state: current_sha256 === original_sha256 ? "unchanged" : "changed", reason: null };
+            }
+            catch (error) {
+                if (!(error instanceof AppError) || error.code !== "memory_source_observation_failed")
+                    throw error;
+                return { path, original_sha256, current_sha256: null, state: "unavailable",
+                    reason: String(error.details?.reason ?? "source_unavailable") };
+            }
+        });
+        return { schema_id: "dd-flow/mb-fix-source-observation@1", source: intake.source,
+            finding_ids: intake.selected_findings.map(finding => finding.id), observations,
+            requires_reassessment: !observations.length || observations.some(source => source.state !== "unchanged"),
+            authorization: "not_granted" };
+    };
+    const original = capture();
+    return { snapshot: () => structuredClone(original), revalidate: () => {
+            if (hybridDigest(capture()) !== hybridDigest(original))
+                refuse("sources_changed_after_observation");
+        } };
+}

package/dist/services/memory-fix-stage-entry.js

@@ -0,0 +1,24 @@
+import { AppError } from "../shared/errors.js";
+import { memoryFixStages } from "../domain/memory-fix-flow.js";
+import { readFlowRunExecutionBundle } from "./runs.js";
+import { requireProjectByRoot } from "./projects.js";
+import { resolveProjectRoot } from "../storage/paths.js";
+import { readMemoryFixSourceIntake, assertMemoryFixSourceIntakeCustody } from "./memory-fix-intake-custody.js";
+import { PreparedDescriptorStageStart } from "./descriptor-stage-start.js";
+import { PreparedDescriptorStageCoordinator } from "./descriptor-stage-coordinator.js";
+/** Registered entry implementation, not standalone RUN-start permission.
+ * Generic runtime alone owns attempts, root Work, coordinator and replay.
+ */
+export function startMemoryFixStage(context, input) {
+    const project = requireProjectByRoot(context, resolveProjectRoot(input.projectRoot));
+    const bundle = readFlowRunExecutionBundle(context, input);
+    if (!bundle || bundle.manifest.flow_id !== "mb-fix" || !memoryFixStages.includes(input.stage))
+        throw new AppError("memory_fix_stage_invalid", "Memory repair requires its registered five-stage flow and retained intake", 2, { reason: "memory_fix_stage_required", effect: "no_effect" });
+    bundle.descriptor.stage(input.stage);
+    const source = readMemoryFixSourceIntake(context, input, bundle);
+    const scope = { projectId: project.id, runId: input.runId };
+    const fence = (writer) => assertMemoryFixSourceIntakeCustody(writer, scope, bundle, source.sha256);
+    const start = PreparedDescriptorStageStart.prepare(context, input).apply(context, fence);
+    const coordinator = PreparedDescriptorStageCoordinator.prepare(context, input).apply(context, fence);
+    return { ...start, ...coordinator, intake_sha256: source.sha256, source_intake: source.reference };
+}

package/dist/services/memory-fix-stage-handlers.js

@@ -0,0 +1,282 @@
+import path from "node:path";
+import { createHash } from "node:crypto";
+import { AppError } from "../shared/errors.js";
+import { resolveProjectRoot } from "../storage/paths.js";
+import { entityReferenceVariants } from "../shared/entity-references.js";
+import { requireProjectByRoot } from "./projects.js";
+import { readFlowRunExecutionBundle, assertPreparedRunBundleSqlAuthority } from "./runs.js";
+import { readDescriptorStageInput } from "./descriptor-stage-coordinator.js";
+import { PreparedDescriptorStageSettlement, readAcceptedDescriptorStageSettlement, readActiveDescriptorStageCoordinator } from "./descriptor-stage-settlement.js";
+import { readAcceptedStageData, prepareStagePacket, acceptStagePacket, resolveStagePublicationPath, prepareStageReport, acceptStageReport, publishStageReport } from "./stage-report-renderer.js";
+import { readMemoryFixSourceIntake, assertMemoryFixSourceIntakeCustody } from "./memory-fix-intake-custody.js";
+import { finishMemoryFixIntake, readAcceptedMemoryFixIntakeEvidence } from "./memory-fix-intake-settlement.js";
+import { readMemoryFixPublication, readMemoryFixPublicationReference } from "./memory-fix-publication.js";
+import { memoryFixBeforeDocumentReferences, publishMemoryFixBeforeDocuments } from "./distill-document-publication.js";
+import { readPreparedMemoryFlowUserInputs } from "./memory-flow-user-inputs.js";
+import { validateMemoryFixStageResult, assertMemoryFixStageScope, memoryFixClosureProjection } from "./memory-fix-stage-results.js";
+import { PreparedDescriptorRunSettlement } from "./descriptor-run-settlement.js";
+import { prepareMemoryFixFinishIntegration } from "./memory-fix-finish-integration.js";
+import { stageLifecycleMatchKey } from "./hooks.js";
+import { assertDiagnosticSessionIndependence } from "./diagnostic-work-collection.js";
+import { hybridDigest } from "./hybrid-contracts.js";
+import { memoryFixStages } from "../domain/memory-fix-flow.js";
+import { startMemoryFixStage } from "./memory-fix-stage-entry.js";
+/** Engine-owned handlers only; source admission does not allocate or start a RUN. */
+export const memoryFixStageHandlers = Object.freeze(memoryFixStages.map(stage => Object.freeze({
+    flowId: "mb-fix", stage, entryId: "memory-fix-stage-entry", finishId: "memory-fix-stage-finish",
+    entry: startMemoryFixStage, finish: finishMemoryFixStage
+})));
+function refuse(reason) {
+    const correctable = reason.startsWith("changed_") || ["invalid_result_json", "invalid_result_details", "result_exceeds_bound",
+        "preservation_evidence_required", "output_evidence_required"].includes(reason);
+    throw new AppError("memory_fix_stage_invalid", "Repair Stage requires its admitted publication and independent observations", 2, { reason, effect: "no_effect", ...(correctable ? { phase: "prepare", recoverable: true } : {}) });
+}
+function readTerminalReport(context, scope, attempt, root) {
+    const rows = context.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, scope.runId, attempt]);
+    if (!rows.length)
+        return null;
+    if (rows.length !== 1 || Buffer.byteLength(rows[0].payload_json) > 8 * 1024 * 1024)
+        refuse("terminal_report_custody_invalid");
+    try {
+        const retained = JSON.parse(rows[0].payload_json);
+        const report = prepareStageReport(JSON.parse(retained.bytes.json));
+        if (retained.sha256 !== report.sha256 || hybridDigest(retained.bytes) !== hybridDigest(report.bytes)
+            || resolveStagePublicationPath(context, scope.projectId, scope.runId, retained.root) !== root)
+            refuse("terminal_report_changed");
+        return report;
+    }
+    catch (error) {
+        if (error instanceof AppError)
+            throw error;
+        return refuse("terminal_report_custody_invalid");
+    }
+}
+/** Common Stage settlement; public launch still requires the real RUN factory,
+ * command dispatch and installed family acceptance. */
+export function finishMemoryFixStage(context, input) {
+    if (input.stage === "intake")
+        return finishMemoryFixIntake(context, input);
+    if (!["repair", "verify", "review", "finish"].includes(input.stage))
+        refuse("repair_stage_required");
+    const stage = input.stage;
+    const project = requireProjectByRoot(context, resolveProjectRoot(input.projectRoot));
+    const bundle = readFlowRunExecutionBundle(context, input);
+    if (!bundle || bundle.manifest.flow_id !== "mb-fix")
+        refuse("memory_fix_bundle_required");
+    const scope = { projectId: project.id, runId: input.runId, stage };
+    const source = readMemoryFixSourceIntake(context, input, bundle), run = assertPreparedRunBundleSqlAuthority(context, scope, bundle);
+    const packet = readDescriptorStageInput(context, scope, bundle, true, true);
+    const previousStage = stage === "repair" ? "intake" : stage === "verify" ? "repair" : stage === "review" ? "verify" : "review";
+    const previous = readAcceptedStageData(context, { ...scope, stage: previousStage });
+    if (packet.input.predecessor?.stage !== previousStage || hybridDigest(packet.input.predecessor.result) !== hybridDigest(previous.result))
+        refuse("predecessor_changed");
+    const prior = JSON.parse(previous.bytes.toString("utf8"));
+    const intakeFile = path.join(packet.runRoot, bundle.descriptor.stage("intake").directory, "intake-evidence.json");
+    const intake = readAcceptedMemoryFixIntakeEvidence(context, scope, intakeFile);
+    if (intake.intake_sha256 !== source.sha256)
+        refuse("source_intake_changed");
+    const publication = readMemoryFixPublication(context, { project_id: project.id, run_id: input.runId });
+    const repairInput = stage === "repair" ? packet : readDescriptorStageInput(context, { ...scope, stage: "repair" }, bundle, true, true);
+    const intakeResult = readAcceptedStageData(context, { ...scope, stage: "intake" });
+    if (intake.write_scope) {
+        if (!publication?.completed || publication.binding.bundle_sha256 !== bundle.sha256
+            || publication.binding.attempt !== repairInput.attempt || publication.binding.input_sha256 !== repairInput.inputSha256
+            || publication.binding.intake_sha256 !== source.sha256 || publication.binding.source_observation_sha256 !== intake.source_observation_sha256
+            || hybridDigest(publication.binding.intake_result) !== hybridDigest(intakeResult.result)
+            || hybridDigest(publication.binding.write_scope) !== hybridDigest(intake.write_scope))
+            refuse("completed_publication_required");
+    }
+    else if (publication)
+        refuse("publication_without_accepted_scope");
+    const reference = publication ? readMemoryFixPublicationReference(context, publication, `${bundle.descriptor.stage("repair").directory}/publication.json`) : null;
+    if (publication && !reference)
+        refuse("publication_reference_required");
+    if (!input.bytes.length || input.bytes.length > 1024 * 1024)
+        refuse("result_exceeds_bound");
+    let result;
+    try {
+        result = JSON.parse(new TextDecoder("utf-8", { fatal: true }).decode(input.bytes));
+    }
+    catch {
+        return refuse("invalid_result_json");
+    }
+    if (!result?.details || typeof result.details !== "object" || !Array.isArray(result.details.limitations))
+        refuse("invalid_result_details");
+    const insert = (object, field, expected) => {
+        const proposed = object[field];
+        if (proposed != null && !(Array.isArray(proposed) && !proposed.length) && hybridDigest(proposed) !== hybridDigest(expected))
+            refuse(`changed_${field}`);
+        Object.assign(object, { [field]: structuredClone(expected) });
+    };
+    for (const [field, expected] of Object.entries({ schema_id: "dd-flow/mb-fix-stage-result@1", flow_id: "mb-fix", run_id: input.runId, stage,
+        input_sha256: packet.inputSha256, intake_sha256: source.sha256, source_observation_sha256: intake.source_observation_sha256,
+        predecessors: [{ stage: previousStage, ...previous.result }] }))
+        insert(result, field, expected);
+    insert(result.details, "routing", intake.routing);
+    insert(result.details, "write_scope", intake.write_scope);
+    insert(result.details, "repair_receipt", reference);
+    if (stage === "review" || stage === "finish")
+        insert(result.details, "verification", prior.details.verification);
+    if (stage === "finish")
+        insert(result.details, "review", prior.details.review);
+    result.details.limitations = [...new Set([...prior.details.limitations, ...source.intake.limitations, ...result.details.limitations])];
+    const bytes = Buffer.from(JSON.stringify(result));
+    const index = JSON.parse(run.index_json), replay = index.stage_runs.some((entry) => entry.stage === stage && entry.status === "done");
+    const logicalReadback = `${bundle.descriptor.stage(stage).directory}/publication-readback.json`;
+    const readback = prepareStagePacket(path.join(packet.runRoot, logicalReadback), Buffer.from(JSON.stringify({
+        schema_id: "dd-flow/mb-fix-publication-readback@1", run_id: input.runId, stage, input_sha256: packet.inputSha256,
+        result_sha256: createHash("sha256").update(bytes).digest("hex"), publication: reference,
+        documents: publication ? publication.binding.write_scope.paths.map(logical => ({ path: logical,
+            after: publication.plan.state(publication.plan.actions().length).entries().find(entry => entry.path === logical) ?? null })) : []
+    })));
+    if (replay) {
+        if (!readAcceptedStageData(context, scope).bytes.equals(bytes))
+            refuse("accepted_result_changed");
+    }
+    else {
+        if (publication) {
+            const actual = publication.plan.classify(run.workspace_root);
+            if (actual.completed !== actual.total)
+                refuse("publication_not_observed");
+            publishMemoryFixBeforeDocuments(packet.runRoot, publication.plan, publication.beforeDocuments);
+        }
+        result = validateMemoryFixStageResult(bytes, bundle.descriptor.stageBlob(stage, "result_schema"), {
+            runId: input.runId, stage, inputSha256: packet.inputSha256, intakeSha256: source.sha256, sourceObservationSha256: intake.source_observation_sha256,
+            findingIds: source.intake.selected_findings.map(finding => finding.id), projectRoot: run.workspace_root, runRoot: packet.runRoot,
+            predecessors: [{ stage: previousStage, ...previous.result }], writeScope: intake.write_scope, repairReceipt: reference
+        });
+        if (publication && stage !== "repair") {
+            const evidence = result.details.verification.flatMap(item => item.evidence);
+            if (memoryFixBeforeDocumentReferences(publication.plan).some(document => !evidence.some(ref => ref.root === "run"
+                && ref.path === document.source.path && ref.sha256 === document.source.sha256)))
+                refuse("preservation_evidence_required");
+            const after = publication.plan.state(publication.plan.actions().length).entries();
+            if (publication.binding.write_scope.paths.some(logical => {
+                const document = after.find(entry => entry.path === logical);
+                return document?.kind === "file" && !evidence.some(ref => ref.root === "project" && ref.path === logical && ref.sha256 === document.sha256);
+            }))
+                refuse("output_evidence_required");
+        }
+        assertMemoryFixStageScope(result, prior);
+    }
+    const settlement = PreparedDescriptorStageSettlement.prepare(context, { ...input, bytes });
+    const keys = (name) => entityReferenceVariants(input.runId).map(ref => stageLifecycleMatchKey("stage_finish", ref, name, input.projectRoot));
+    const repairKeys = stage !== "repair" || replay ? keys("repair") : [];
+    const verifyKeys = stage === "review" || stage === "finish" ? keys("verify") : [];
+    const reviewKeys = stage === "finish" ? keys("review") : [];
+    const readOwner = (writer) => {
+        const physical = (sessionId) => {
+            const session = writer.db.get("SELECT harness,provider_session_id FROM sessions WHERE project_id=? AND run_id=? AND session_id=?", [project.id, input.runId, sessionId]);
+            if (!session?.harness || !session.provider_session_id)
+                refuse("physical_owner_missing");
+            return session;
+        };
+        const repair = stage !== "repair" || replay ? readAcceptedDescriptorStageSettlement(writer, { ...scope, stage: "repair" }, bundle, repairKeys) : null;
+        const verify = stage === "review" || stage === "finish" ? readAcceptedDescriptorStageSettlement(writer, { ...scope, stage: "verify" }, bundle, verifyKeys) : null;
+        const review = stage === "finish" ? readAcceptedDescriptorStageSettlement(writer, { ...scope, stage: "review" }, bundle, reviewKeys) : null;
+        const authorId = repair?.binding.sessionId ?? settlement.coordinatorSessionId(), author = physical(authorId);
+        const authorProof = repair ? { work_id: repair.work_id, work_session_id: repair.work_session_id, session_id: authorId,
+            ...author, start_hook: repair.binding.startHook, association_sha256: repair.binding.associationSha256,
+            physical_binding_sha256: repair.binding.physicalBindingSha256, prompt_path: repair.binding.promptPath }
+            : readActiveDescriptorStageCoordinator(writer, scope, bundle);
+        if (publication && hybridDigest(publication.binding.author) !== hybridDigest(authorProof))
+            refuse("publication_author_changed");
+        if (stage === "finish") {
+            assertDiagnosticSessionIndependence([physical(verify.binding.sessionId)], [author]);
+            assertDiagnosticSessionIndependence([physical(review.binding.sessionId)], [author, physical(verify.binding.sessionId)]);
+        }
+        else if (stage !== "repair")
+            assertDiagnosticSessionIndependence([physical(settlement.coordinatorSessionId())], [author, ...(verify ? [physical(verify.binding.sessionId)] : [])]);
+        return { repair, verify, review, author };
+    };
+    const owner = context.db.readSnapshot(() => readOwner(context));
+    const closure = stage === "finish" ? memoryFixClosureProjection(result) : null;
+    const reportRoot = path.join(packet.runRoot, bundle.descriptor.stage(stage).directory);
+    const retainedReport = stage === "finish" ? readTerminalReport(context, scope, packet.attempt, reportRoot) : null;
+    if (stage === "finish" && replay && !retainedReport)
+        refuse("accepted_terminal_report_missing");
+    const acceptedRepair = !!closure && !!publication && !closure.some(item => item.status === "open");
+    const integration = stage === "finish" && acceptedRepair && (!replay || run.status !== "done")
+        ? prepareMemoryFixFinishIntegration(context, scope, bundle) : null;
+    const integrationOutcome = replay && retainedReport ? retainedReport.normalized.integration
+        : integration ? { state: "integrated", observation: integration.value() }
+            : { state: publication ? "not_integrated_open_findings" : "not_applicable" };
+    const report = closure ? prepareStageReport({ run_id: input.runId, stage: "finish",
+        verdict: closure.some(item => item.status === "open") ? "completed_with_open_findings" : "completed", summary: result.summary,
+        memory_fix: { result, closure, source: source.intake.source, source_intake: source.reference,
+            unselected_ids: source.intake.unselected_ids, limitations: source.intake.limitations }, integration: integrationOutcome,
+        semantic: { acceptance: closure.map(item => `${item.finding_id}: ${item.status}; route=${item.route}`),
+            checks: result.details.verification.map(item => `${item.finding_id}: ${item.verdict}; ${item.summary}`),
+            evidence: [...result.details.verification, ...result.details.review].flatMap(item => item.evidence.map(ref => `${ref.root}:${ref.path}@${ref.sha256}`)),
+            next_action: closure.some(item => item.status === "open") ? "Open findings remain open; retain unintegrated work for explicit follow-up. Do not silently retry or close DEF records."
+                : "Only this accepted scope is complete; routed, deferred and unselected findings are not repaired by this RUN." } }) : null;
+    if (report && Buffer.byteLength(JSON.stringify(report.bytes)) > 7 * 1024 * 1024)
+        refuse("terminal_report_exceeds_bound");
+    if (retainedReport && report && retainedReport.sha256 !== report.sha256)
+        refuse("accepted_terminal_report_changed");
+    integration?.revalidate();
+    if (!replay && publication) {
+        const observed = publication.plan.classify(run.workspace_root);
+        if (observed.completed !== observed.total)
+            refuse("publication_not_observed");
+    }
+    const fence = (writer) => {
+        assertMemoryFixSourceIntakeCustody(writer, scope, bundle, source.sha256);
+        if (hybridDigest(readAcceptedStageData(writer, { ...scope, stage: previousStage })) !== hybridDigest(previous)
+            || hybridDigest(readAcceptedMemoryFixIntakeEvidence(writer, scope, intakeFile)) !== hybridDigest(intake)
+            || hybridDigest(readOwner(writer)) !== hybridDigest(owner))
+            refuse("stage_authority_changed");
+        const current = readMemoryFixPublication(writer, { project_id: project.id, run_id: input.runId });
+        if (publication && (!current?.completed || current.plan.sha256 !== publication.plan.sha256 || hybridDigest(current.binding) !== hybridDigest(publication.binding)
+            || hybridDigest(readMemoryFixPublicationReference(writer, current, reference.path)) !== hybridDigest(reference)))
+            refuse("publication_changed");
+        if (!publication && current)
+            refuse("publication_without_accepted_scope");
+        if (stage === "repair" && !replay && intake.user_inputs_sha256 !== hybridDigest(readPreparedMemoryFlowUserInputs(writer, scope, "mb-fix", bundle)))
+            refuse("user_inputs_changed");
+        const rows = writer.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')=? AND json_extract(payload_json,'$.attempt')=? LIMIT 33", [project.id, input.runId, stage, packet.attempt]);
+        if (rows.length > 32 || rows.some(row => Buffer.byteLength(row.payload_json) > 8 * 1024 * 1024))
+            refuse("readback_custody_invalid");
+        const packets = rows.map(row => JSON.parse(row.payload_json)).filter(value => typeof value.file === "string"
+            && resolveStagePublicationPath(writer, project.id, input.runId, value.file) === readback.file);
+        if (packets.length > 1 || packets.some(value => value.sha256 !== readback.sha256 || value.base64 !== readback.bytes.toString("base64")))
+            refuse("readback_custody_changed");
+        if (!packets.length) {
+            if (replay)
+                refuse("accepted_readback_missing");
+            acceptStagePacket(writer, { ...scope, prepared: readback });
+        }
+        integration?.assertCustody(writer);
+        if (report) {
+            const currentReport = readTerminalReport(writer, scope, packet.attempt, reportRoot);
+            if (currentReport && currentReport.sha256 !== report.sha256)
+                refuse("terminal_report_changed");
+            if (!currentReport) {
+                if (replay)
+                    refuse("accepted_terminal_report_missing");
+                acceptStageReport(writer, { ...scope, root: reportRoot, prepared: report });
+            }
+        }
+    };
+    try {
+        const accepted = settlement.apply(context, fence);
+        if (stage !== "finish")
+            return accepted;
+        integration?.revalidate();
+        const complete = PreparedDescriptorRunSettlement.prepare(context, input).apply(context, fence);
+        publishStageReport(context, project.id, input.runId, "finish", reportRoot);
+        return { ...accepted, ...complete, closure, reports: ["json", "md", "html"].map(extension => path.join(reportRoot, `stage-report.${extension}`)) };
+    }
+    catch (error) {
+        if (stage !== "finish")
+            throw error;
+        let committed = false;
+        try {
+            committed = readAcceptedStageData(context, scope).bytes.equals(bytes);
+        }
+        catch { /* No accepted terminal data. */ }
+        if (!committed)
+            throw error;
+        throw new AppError("memory_fix_finish_pending", "Accepted finish requires projection or RUN settlement reconciliation", 1, { effect: "committed", run_id: input.runId, next_action: "reconcile_accepted_finish", cause: error instanceof AppError ? error.code : "finish_settlement_failed" });
+    }
+}

package/dist/services/memory-fix-stage-results.js

@@ -0,0 +1,106 @@
+import { Ajv2020 } from "ajv/dist/2020.js";
+import { AppError } from "../shared/errors.js";
+import { hybridDigest } from "./hybrid-contracts.js";
+import { validateMemoryFixRouting } from "./diagnostic-repair-intake.js";
+import { assertMemoryRepairWritePaths } from "./memory-review-correction-plan.js";
+import { verifyDiagnosticSources } from "./diagnostic-evidence.js";
+function refuse(reason) {
+    throw new AppError("memory_fix_stage_result_invalid", "Memory repair result requires its selected input, bounded publication and independent observations", 2, { reason, effect: "no_effect", ...(reason === "invalid_schema" ? { phase: "prepare", recoverable: true } : {}) });
+}
+/** Contract/evidence validation only. Registered handlers must prove actual
+ * delivered consent, source-drift assessment, publication and distinct physical
+ * writer/verifier/reviewer ownership before settlement or finding closure.
+ */
+export function validateMemoryFixStageResult(bytes, schemaBytes, binding) {
+    if (!bytes.length || bytes.length > 1024 * 1024 || !schemaBytes.length || schemaBytes.length > 1024 * 1024)
+        refuse("result_exceeds_bound");
+    let result;
+    try {
+        result = JSON.parse(new TextDecoder("utf-8", { fatal: true }).decode(bytes));
+    }
+    catch {
+        return refuse("invalid_schema");
+    }
+    const validate = (() => {
+        try {
+            const schema = JSON.parse(new TextDecoder("utf-8", { fatal: true }).decode(schemaBytes));
+            if (schema.$id !== "dd-flow/mb-fix-stage-result@1")
+                refuse("frozen_schema_invalid");
+            return new Ajv2020({ strict: true, validateFormats: false }).compile(schema);
+        }
+        catch {
+            return refuse("frozen_schema_invalid");
+        }
+    })();
+    if (!validate(result) || result?.schema_id !== "dd-flow/mb-fix-stage-result@1" || result.flow_id !== "mb-fix"
+        || typeof result.summary !== "string" || !result.summary.trim())
+        refuse("invalid_schema");
+    if (result.run_id !== binding.runId || result.stage !== binding.stage || result.input_sha256 !== binding.inputSha256
+        || result.intake_sha256 !== binding.intakeSha256 || result.source_observation_sha256 !== binding.sourceObservationSha256
+        || hybridDigest(result.predecessors) !== hybridDigest(binding.predecessors))
+        refuse("foreign_stage_binding");
+    const details = result.details, routing = validateMemoryFixRouting(binding.findingIds, details.routing);
+    if (hybridDigest(routing) !== hybridDigest(details.routing))
+        refuse("routing_order_changed");
+    const repairs = routing.filter(decision => decision.route === "memory_repair").map(decision => decision.finding_id);
+    if (hybridDigest(details.write_scope) !== hybridDigest(binding.writeScope)
+        || hybridDigest(details.repair_receipt) !== hybridDigest(binding.repairReceipt))
+        refuse("unowned_repair_claim");
+    if (details.write_scope) {
+        const scope = details.write_scope, paths = [...new Set(routing.flatMap(decision => decision.write_paths))].sort();
+        assertMemoryRepairWritePaths(scope.paths);
+        if (hybridDigest(scope.finding_ids) !== hybridDigest(repairs)
+            || hybridDigest([...scope.paths].sort()) !== hybridDigest(paths))
+            refuse("repair_scope_changed");
+    }
+    if (!repairs.length && (details.write_scope || details.repair_receipt))
+        refuse("publication_without_repair_findings");
+    if (repairs.length && !details.write_scope)
+        refuse("intake_requires_approved_scope");
+    if (binding.stage === "intake" && details.repair_receipt)
+        refuse("repair_before_intake");
+    if (binding.stage !== "intake" && repairs.length && (!details.write_scope || !details.repair_receipt))
+        refuse("repair_requires_scope_and_receipt");
+    // Approval/publication authority is independently selected from SQL by the
+    // handler. Re-reading mutable projections here neither proves user consent
+    // nor strengthens that custody, and would break supported projection restore.
+    const verify = binding.stage === "verify" || binding.stage === "review" || binding.stage === "finish";
+    const review = binding.stage === "review" || binding.stage === "finish";
+    const observations = (items, expected) => {
+        const ids = items.map(item => item.finding_id);
+        if (new Set(ids).size !== ids.length || ids.length !== expected.length || expected.some(id => !ids.includes(id)))
+            refuse("incomplete_finding_observations");
+        for (const item of items) {
+            if (!item.summary.trim())
+                refuse("invalid_schema");
+            for (const evidence of item.evidence)
+                verifyDiagnosticSources(evidence.root === "run" ? binding.runRoot : binding.projectRoot, [evidence]);
+        }
+    };
+    observations(details.verification, verify ? repairs : []);
+    observations(details.review, review ? binding.findingIds : []);
+    if (details.verification.some(item => item.verdict === "resolved" && !item.evidence.length))
+        refuse("closure_without_evidence");
+    if (details.review.some(item => item.disposition === "accept" && !item.evidence.length))
+        refuse("closure_without_evidence");
+    return result;
+}
+export function assertMemoryFixStageScope(result, prior) {
+    if (result.intake_sha256 !== prior.intake_sha256 || result.source_observation_sha256 !== prior.source_observation_sha256
+        || hybridDigest(result.details.routing) !== hybridDigest(prior.details.routing)
+        || hybridDigest(result.details.write_scope) !== hybridDigest(prior.details.write_scope)
+        || prior.details.limitations.some(value => !result.details.limitations.includes(value))
+        || prior.stage !== "intake" && hybridDigest(result.details.repair_receipt) !== hybridDigest(prior.details.repair_receipt)
+        || ["verify", "review"].includes(prior.stage) && hybridDigest(result.details.verification) !== hybridDigest(prior.details.verification)
+        || prior.stage === "review" && hybridDigest(result.details.review) !== hybridDigest(prior.details.review))
+        refuse("accepted_scope_changed");
+}
+/** Proposed report projection, never a DEF mutation or independent ownership proof. */
+export function memoryFixClosureProjection(result) {
+    if (result.stage !== "finish")
+        refuse("finish_required");
+    return result.details.routing.map(decision => ({ finding_id: decision.finding_id, route: decision.route,
+        status: decision.route === "defer" ? "deferred" : decision.route !== "memory_repair" ? "routed"
+            : result.details.verification.some(item => item.finding_id === decision.finding_id && item.verdict === "resolved")
+                && result.details.review.some(item => item.finding_id === decision.finding_id && item.disposition === "accept") ? "closed" : "open" }));
+}

package/dist/services/memory-fix-workspace.js

@@ -0,0 +1,127 @@
+import fs from "node:fs";
+import path from "node:path";
+import { spawnSync } from "node:child_process";
+import { AppError } from "../shared/errors.js";
+import { projectCheckoutRoot, resolveProjectRoot } from "../storage/paths.js";
+import { requireProjectByRoot } from "./projects.js";
+import { loadVnextWorkspacePolicy } from "./vnext-workspace-policy.js";
+import { prepareManagedWorktree, createManagedWorktree } from "./worktrees.js";
+import { inspectMemoryGitExecutable } from "./memory-init-preflight.js";
+import { prepareMemoryFixGitPolicy } from "./memory-fix-finish-integration.js";
+import { hybridDigest } from "./hybrid-contracts.js";
+import { appendAudit } from "./audit.js";
+const intentEvent = "memory_fix.workspace_intent", readyEvent = "memory_fix.workspace_ready";
+function refuse(reason) { throw new AppError("memory_fix_workspace_invalid", "Repair workspace requires its original project-scoped selection", 2, { reason, effect: "no_effect" }); }
+function pending(reason, details = {}) {
+    throw new AppError("memory_fix_workspace_pending", "Reconcile the original workspace creation before redispatch", 1, { reason, effect: "unknown", next_action: "reconcile_original_workspace", ...details });
+}
+/** Worktrunk owns physical creation. This wrapper retains one intent before
+ * dispatch and never reruns an unresolved creation or adopts a foreign tree. */
+export async function prepareMemoryFixWorkspace(context, input) {
+    if (context.db.isOwnedWriteTransaction?.())
+        refuse("preparation_outside_writer_required");
+    const projectRoot = resolveProjectRoot(input.projectRoot), project = requireProjectByRoot(context, projectRoot);
+    if (projectRoot !== input.projectRoot || !/^[A-Za-z0-9][A-Za-z0-9_.-]{0,95}$/.test(input.requestId))
+        refuse("invalid_scope");
+    if (input.selectionSha256 !== undefined && !/^[a-f0-9]{64}$/.test(input.selectionSha256))
+        refuse("invalid_selection_identity");
+    const scope = { projectRoot, requestId: input.requestId };
+    const read = (event) => {
+        const rows = context.db.all("SELECT payload_json FROM audit_events WHERE project_id=? AND event_type=? AND json_extract(payload_json,'$.scope.requestId')=? LIMIT 2", [project.id, event, input.requestId]);
+        if (!rows.length)
+            return null;
+        if (rows.length !== 1 || Buffer.byteLength(rows[0].payload_json) > 32768)
+            pending("ambiguous_workspace_custody");
+        try {
+            const value = JSON.parse(rows[0].payload_json);
+            if (hybridDigest(value.scope) !== hybridDigest(scope))
+                pending("workspace_scope_changed");
+            return value;
+        }
+        catch {
+            return pending("invalid_workspace_custody");
+        }
+    };
+    const observe = (intent) => {
+        const policy = prepareMemoryFixGitPolicy(context.env, { scope: { ...scope, workspaceRoot: intent.workspace_root }, gitExecutable: intent.git_executable, selection: intent.git_policy });
+        const git = JSON.parse(policy.bytes.toString("utf8")).policy;
+        if (intent.creation && (git.workspace_branch !== intent.creation.branch || git.initial_head !== intent.creation.base))
+            refuse("created_workspace_baseline_changed");
+        const stat = fs.lstatSync(intent.workspace_root);
+        if (!stat.isDirectory() || fs.realpathSync(intent.workspace_root) !== intent.workspace_root)
+            refuse("workspace_identity_changed");
+        return { policy_sha256: policy.sha256, owner: { dev: stat.dev, ino: stat.ino } };
+    };
+    const retainReady = (intent, actual) => context.db.writeTransaction(() => {
+        const intentSha256 = hybridDigest(intent), value = { scope, intent_sha256: intentSha256, ...actual };
+        if (hybridDigest(read(intentEvent)) !== intentSha256)
+            pending("workspace_custody_changed");
+        const current = read(readyEvent);
+        if (current) {
+            if (hybridDigest(current) !== hybridDigest(value))
+                pending("workspace_custody_changed");
+            return;
+        }
+        appendAudit(context, { projectId: project.id, eventType: readyEvent, payload: value });
+    });
+    const prior = read(intentEvent);
+    let ready = read(readyEvent);
+    if (prior) {
+        if (input.workspaceRoot !== undefined && input.workspaceRoot !== prior.workspace_root
+            || input.selectionSha256 !== undefined && input.selectionSha256 !== prior.selection_sha256
+            || input.gitPolicy !== undefined && hybridDigest(input.gitPolicy) !== hybridDigest(prior.git_policy))
+            refuse("request_changed");
+        if (!ready && prior.creation && fs.existsSync(prior.workspace_root)) {
+            // Read-only reconciliation of an original creation with a lost reply.
+            // Exact private path/repository/branch/base and a clean tree are required;
+            // no second Worktrunk call, reset or adoption of changed user work occurs.
+            const actual = observe(prior), result = spawnSync(prior.git_executable, ["-c", "core.fsmonitor=false", "-C", prior.workspace_root, "status", "--porcelain=v1", "-z", "--untracked-files=all"], { env: { ...Object.fromEntries(Object.entries(context.env).filter(([key]) => !key.startsWith("GIT_"))), GIT_OPTIONAL_LOCKS: "0" }, timeout: 5000, maxBuffer: 1024 * 1024 });
+            if (result.error || result.signal || result.status !== 0 || result.stdout.length)
+                pending("created_workspace_not_pristine");
+            retainReady(prior, actual);
+            ready = read(readyEvent);
+        }
+        if (!ready || ready.intent_sha256 !== hybridDigest(prior))
+            pending("workspace_creation_unresolved");
+        const actual = observe(prior);
+        if (hybridDigest(actual) !== hybridDigest({ policy_sha256: ready.policy_sha256, owner: ready.owner }))
+            refuse("workspace_changed_before_request_retention");
+        return { workspaceRoot: prior.workspace_root, gitPolicy: prior.git_policy, gitExecutable: prior.git_executable };
+    }
+    if (ready)
+        pending("workspace_intent_missing");
+    const defaults = input.gitPolicy ? null : loadVnextWorkspacePolicy(projectRoot).workspace;
+    const gitPolicy = input.gitPolicy ?? { route: defaults.route, integrationBranch: defaults.integration_branch };
+    const gitExecutable = inspectMemoryGitExecutable(context.env).executable;
+    const key = hybridDigest({ project_id: project.id, scope }).slice(0, 16);
+    const workspaceRoot = input.workspaceRoot ?? (gitPolicy.route === "integration_branch_direct" ? projectRoot
+        : path.join(projectCheckoutRoot(context.ddFlowHome, project.id), "worktrees", `mb-fix-${key}`, path.basename(projectRoot)));
+    const creation = input.workspaceRoot === undefined && gitPolicy.route === "feature_worktree"
+        ? prepareManagedWorktree({ projectRoot, branch: `codex/mb-fix-${key}`, base: gitPolicy.integrationBranch, path: workspaceRoot }) : null;
+    const intent = { scope, workspace_root: workspaceRoot, git_policy: structuredClone(gitPolicy), git_executable: gitExecutable,
+        selection_sha256: input.selectionSha256 ?? null, creation };
+    if (!creation)
+        observe(intent);
+    const claimed = context.db.writeTransaction(() => {
+        if (read(intentEvent) || read(readyEvent))
+            return false;
+        appendAudit(context, { projectId: project.id, eventType: intentEvent, payload: intent });
+        return true;
+    });
+    if (!claimed)
+        pending("workspace_creation_already_owned");
+    try {
+        if (creation) {
+            const created = await createManagedWorktree(context, creation, creation);
+            if (created.worktreePath !== workspaceRoot)
+                pending("unexpected_worktrunk_workspace", { expected_workspace_root: workspaceRoot, observed_workspace_root: created.worktreePath });
+        }
+        retainReady(intent, observe(intent));
+        return { workspaceRoot, gitPolicy, gitExecutable };
+    }
+    catch (error) {
+        if (error instanceof AppError && error.code === "memory_fix_workspace_pending")
+            throw error;
+        return pending(error instanceof AppError ? error.code : "workspace_creation_failed");
+    }
+}