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

package/dist/services/memory-finish-handler.js

@@ -0,0 +1,229 @@
+import { assertMemorySqlCustody, withMemoryCustodySnapshot } from "./memory-custody-snapshot.js";
+import { AppError } from "../shared/errors.js";
+import { RetainedExecutionBundle } from "./execution-bundles.js";
+import { readAcceptedStageData } from "./stage-report-renderer.js";
+import { PreparedAcceptedMemoryInitialReview } from "./memory-review-receipt.js";
+import { PreparedAcceptedMemoryCorrectedReview } from "./memory-corrected-review-receipt.js";
+import { PreparedDescriptorStageStart } from "./descriptor-stage-start.js";
+import { PreparedDescriptorStageCoordinator } from "./descriptor-stage-coordinator.js";
+import { assertPreparedRunBundleSqlAuthority, readFlowRunExecutionBundle } from "./runs.js";
+import { requireProjectByRoot } from "./projects.js";
+import { resolveProjectRoot } from "../storage/paths.js";
+import path from "node:path";
+import { hybridDigest } from "./hybrid-contracts.js";
+import { readAcceptedMemoryFinishEvidence, PreparedMemoryFinishEvidence, projectMemoryFinishResult } from "./memory-finish-evidence.js";
+import { PreparedDescriptorStageSettlement } from "./descriptor-stage-settlement.js";
+import { publishStagePacket } from "./stage-report-renderer.js";
+import { PreparedDescriptorRunSettlement } from "./descriptor-run-settlement.js";
+import { integrateMemoryFinish } from "./memory-finish-integration.js";
+const token = Symbol("memory-finish-review-predecessor");
+function refuse(reason) {
+    throw new AppError("memory_finish_handler_invalid", "Memory finish lacks independently accepted predecessor custody", 2, { reason, effect: "no_effect" });
+}
+function selected(context, scope) {
+    const data = readAcceptedStageData(context, { ...scope, stage: "review" });
+    // A missing corrected acceptance receipt must never reopen initial review.
+    // Existing repair registration independently selects the corrected branch.
+    const corrected = !!context.db.get(`SELECT 1 FROM audit_events WHERE project_id=?
+    AND event_type IN ('memory.repair_registration','memory.second_repair_registration','memory.corrected_review_acceptance')
+    AND json_extract(payload_json,'$.run_id')=?
+    AND (json_extract(payload_json,'$.scope.input_sha256')=? OR json_extract(payload_json,'$.input_sha256')=?) LIMIT 1`, [scope.projectId, scope.runId, data.input_sha256, data.input_sha256]);
+    return { data, corrected };
+}
+/** Closed review predecessor proof only. It does not establish integration,
+ * normal-flow readiness, terminal Stage acceptance or RUN completion. */
+export class PreparedMemoryFinishReview {
+    #custodyKey = {};
+    static isPrepared(value) {
+        return typeof value === "object" && value !== null && #review in value;
+    }
+    #scope;
+    #review;
+    #authority;
+    #corrected;
+    #bytes;
+    constructor(key, scope, review, data) {
+        if (key !== token)
+            refuse("finish_review_token_required");
+        this.#scope = { ...scope };
+        this.#review = review;
+        this.#authority = data.data.authority_sha256;
+        this.#corrected = data.corrected;
+        this.#bytes = Buffer.from(data.data.bytes);
+        Object.freeze(this);
+    }
+    static prepare(context, input) {
+        if (!(input.bundle instanceof RetainedExecutionBundle) || !["mb-init", "mb-upgrade"].includes(input.bundle.descriptor.descriptor.id)
+            || input.bundle.descriptor.successor("review", "accepted") !== "finish")
+            refuse("registered_memory_bundle_required");
+        if (context.db.isOwnedWriteTransaction?.())
+            refuse("preparation_outside_writer_required");
+        return withMemoryCustodySnapshot(context, () => {
+            assertPreparedRunBundleSqlAuthority(context, input.scope, input.bundle);
+            const data = context.db.readSnapshot(() => selected(context, input.scope));
+            const review = data.corrected
+                ? PreparedAcceptedMemoryCorrectedReview.prepare(context, { ...input, bytes: data.data.bytes })
+                : PreparedAcceptedMemoryInitialReview.prepare(context, { ...input, bytes: data.data.bytes });
+            const prepared = new PreparedMemoryFinishReview(token, input.scope, review, data);
+            prepared.revalidate(context);
+            return prepared;
+        });
+    }
+    bytes() { return Buffer.from(this.#bytes); }
+    reviewedSources(context) { this.assertCustody(context); return this.#review.reviewedSources(context); }
+    reviewedDocumentInventory(context) {
+        this.assertCustody(context);
+        return this.#review instanceof PreparedAcceptedMemoryCorrectedReview ? this.#review.settledDocumentBaseline(context).entries() : null;
+    }
+    finalChecks(context) { this.assertCustody(context); return this.#review.finalChecks(context); }
+    assertCustody(context) {
+        const review = this.#review;
+        assertMemorySqlCustody(context, this.#custodyKey, () => {
+            review.assertCustody(context);
+            const data = selected(context, this.#scope);
+            if (data.corrected !== this.#corrected || data.data.authority_sha256 !== this.#authority
+                || !data.data.bytes.equals(this.#bytes))
+                refuse("accepted_review_changed");
+        });
+    }
+    revalidate(context) {
+        const review = this.#review;
+        withMemoryCustodySnapshot(context, () => { review.revalidate(context); this.assertCustody(context); });
+    }
+}
+/** Shared terminal entry for registered Memory flows. Opens only after
+ * historical review proof; no provider dispatch or Git mutation.
+ * Terminal settlement must separately prove integration and readiness. */
+export function startMemoryFinish(context, input) {
+    if (!(input.bytes instanceof Uint8Array) || input.bytes.length > 1024 * 1024)
+        refuse("invalid_input_bytes");
+    const bundle = readFlowRunExecutionBundle(context, input);
+    if (!bundle || !["mb-init", "mb-upgrade"].includes(bundle.descriptor.descriptor.id) || !bundle.descriptor.descriptor.terminal_stages.includes("finish")
+        || bundle.descriptor.successor("review", "accepted") !== "finish")
+        refuse("registered_memory_bundle_required");
+    const project = requireProjectByRoot(context, resolveProjectRoot(input.projectRoot)), scope = { projectId: project.id, runId: input.runId };
+    const run = assertPreparedRunBundleSqlAuthority(context, scope, bundle);
+    if (JSON.parse(run.index_json).stage_runs.some((stage) => stage.stage === "finish" && stage.status === "done"))
+        refuse("use_accepted_finish_replay");
+    const review = PreparedMemoryFinishReview.prepare(context, { scope, bundle });
+    const start = PreparedDescriptorStageStart.prepare(context, { ...input, stage: "finish" });
+    review.revalidate(context);
+    const stage = start.apply(context, writer => review.assertCustody(writer));
+    const coordinator = PreparedDescriptorStageCoordinator.prepare(context, { ...input, stage: "finish" });
+    review.revalidate(context);
+    return { ...stage, ...coordinator.apply(context, writer => review.assertCustody(writer)) };
+}
+/** Restore accepted finish projections using historical custody only. This
+ * never re-admits current project bytes or closes the root Work/RUN. */
+export function replayAcceptedMemoryFinish(context, input) {
+    if (!(input.bytes instanceof Uint8Array) || !input.bytes.length || input.bytes.length > 1024 * 1024)
+        refuse("invalid_input_bytes");
+    if (context.db.isOwnedWriteTransaction?.())
+        refuse("preparation_outside_writer_required");
+    const bundle = readFlowRunExecutionBundle(context, input);
+    if (!bundle || !["mb-init", "mb-upgrade"].includes(bundle.descriptor.descriptor.id))
+        refuse("registered_memory_bundle_required");
+    const project = requireProjectByRoot(context, resolveProjectRoot(input.projectRoot)), scope = { projectId: project.id, runId: input.runId };
+    const review = PreparedMemoryFinishReview.prepare(context, { scope, bundle });
+    const retained = context.db.readSnapshot(() => readAcceptedMemoryFinishEvidence(context, { scope, bundle, review }));
+    let proposal;
+    try {
+        proposal = JSON.parse(new TextDecoder("utf-8", { fatal: true }).decode(input.bytes));
+    }
+    catch {
+        refuse("invalid_input_bytes");
+    }
+    const canonical = JSON.parse(retained.result.bytes.toString("utf8"));
+    if (hybridDigest(projectMemoryFinishResult(proposal, canonical)) !== hybridDigest(canonical))
+        refuse("accepted_finish_bytes_changed");
+    const authority = hybridDigest(retained);
+    const settlement = PreparedDescriptorStageSettlement.prepare(context, { ...input, stage: "finish", bytes: retained.result.bytes });
+    review.revalidate(context);
+    try {
+        const result = settlement.apply(context, writer => {
+            if (hybridDigest(readAcceptedMemoryFinishEvidence(writer, { scope, bundle, review })) !== authority)
+                refuse("accepted_finish_custody_changed");
+        });
+        const run = assertPreparedRunBundleSqlAuthority(context, scope, bundle), root = run.run_root ?? run.run_dir;
+        for (const packet of retained.packets)
+            publishStagePacket(context, scope.projectId, scope.runId, "finish", path.join(root, packet.reference.path));
+        review.revalidate(context);
+        if (hybridDigest(context.db.readSnapshot(() => readAcceptedMemoryFinishEvidence(context, { scope, bundle, review }))) !== authority)
+            refuse("accepted_finish_custody_changed");
+        return result;
+    }
+    catch (error) {
+        throw new AppError("memory_finish_replay_pending", "Accepted finish remains retained; projection recovery is incomplete", 1, { effect: "committed", run_id: scope.runId, next_action: "reconcile_accepted_finish",
+            cause: error instanceof AppError ? error.code : "finish_replay_failure" });
+    }
+}
+/** Close only the independently accepted terminal RUN. This does not perform
+ * Git integration, create evidence or accept a fresh finish proposal. */
+export function settleAcceptedMemoryRun(context, input) {
+    if (context.db.isOwnedWriteTransaction?.())
+        refuse("preparation_outside_writer_required");
+    const bundle = readFlowRunExecutionBundle(context, input);
+    if (!bundle || !["mb-init", "mb-upgrade"].includes(bundle.descriptor.descriptor.id)
+        || !bundle.descriptor.descriptor.terminal_stages.includes("finish"))
+        refuse("registered_memory_bundle_required");
+    const project = requireProjectByRoot(context, resolveProjectRoot(input.projectRoot)), scope = { projectId: project.id, runId: input.runId };
+    const review = PreparedMemoryFinishReview.prepare(context, { scope, bundle });
+    const retained = context.db.readSnapshot(() => readAcceptedMemoryFinishEvidence(context, { scope, bundle, review }));
+    const authority = hybridDigest(retained);
+    const settlement = PreparedDescriptorRunSettlement.prepare(context, { ...input, stage: "finish" });
+    review.revalidate(context);
+    try {
+        return settlement.apply(context, writer => {
+            if (hybridDigest(readAcceptedMemoryFinishEvidence(writer, { scope, bundle, review })) !== authority)
+                refuse("accepted_finish_custody_changed");
+        });
+    }
+    catch (error) {
+        if (context.db.get("SELECT status FROM runs WHERE project_id=? AND id=?", [scope.projectId, scope.runId])?.status === "done")
+            throw new AppError("memory_run_settlement_pending", "Accepted memory RUN committed; projection recovery remains required", 1, { effect: "committed", run_id: scope.runId, next_action: "reconcile_accepted_memory_run",
+                cause: error instanceof AppError ? error.code : "run_settlement_failure" });
+        throw error;
+    }
+}
+/** CLI-owned evidence publication before the coordinator proposes its result.
+ * Publication has its own exact receipt and does not accept the Stage. */
+export function registerMemoryFinishEvidenceFromStage(context, input) {
+    const bundle = readFlowRunExecutionBundle(context, input);
+    if (!bundle || !["mb-init", "mb-upgrade"].includes(bundle.descriptor.descriptor.id))
+        refuse("registered_memory_bundle_required");
+    const project = requireProjectByRoot(context, resolveProjectRoot(input.projectRoot));
+    return PreparedMemoryFinishEvidence.prepare(context, { scope: { projectId: project.id, runId: input.runId }, bundle }).register(context);
+}
+export function integrateMemoryFinishFromStage(context, input) {
+    const bundle = readFlowRunExecutionBundle(context, input);
+    if (!bundle || !["mb-init", "mb-upgrade"].includes(bundle.descriptor.descriptor.id))
+        refuse("registered_memory_bundle_required");
+    const project = requireProjectByRoot(context, resolveProjectRoot(input.projectRoot));
+    return integrateMemoryFinish(context, { scope: { projectId: project.id, runId: input.runId }, bundle });
+}
+/** Complete the actual terminal handler, with separately published evidence.
+ * A lost accepted receipt cannot fall back to fresh acceptance or regenerate
+ * terminal artifacts. Stage success precedes independently fenced RUN closure. */
+export function finishMemoryFinish(context, input) {
+    if (!(input.bytes instanceof Uint8Array) || !input.bytes.length || input.bytes.length > 1024 * 1024)
+        refuse("invalid_input_bytes");
+    if (context.db.isOwnedWriteTransaction?.())
+        refuse("preparation_outside_writer_required");
+    const bundle = readFlowRunExecutionBundle(context, input);
+    if (!bundle || !["mb-init", "mb-upgrade"].includes(bundle.descriptor.descriptor.id))
+        refuse("registered_memory_bundle_required");
+    const project = requireProjectByRoot(context, resolveProjectRoot(input.projectRoot)), scope = { projectId: project.id, runId: input.runId };
+    const run = assertPreparedRunBundleSqlAuthority(context, scope, bundle);
+    const stage = JSON.parse(run.index_json).stage_runs.find((item) => item.stage === "finish");
+    const accepted = stage?.status === "done";
+    const result = accepted ? replayAcceptedMemoryFinish(context, input)
+        : PreparedMemoryFinishEvidence.prepare(context, { scope, bundle }).settleFresh(context, input);
+    try {
+        const terminal = settleAcceptedMemoryRun(context, input);
+        return { ...result, run_id: terminal.run_id, terminal };
+    }
+    catch (error) {
+        throw new AppError("memory_finish_terminal_pending", "Finish Stage accepted; terminal RUN closure remains incomplete", 1, { effect: "committed", run_id: scope.runId, next_action: "reconcile_accepted_memory_run",
+            cause: error instanceof AppError ? error.code : "terminal_closure_failure" });
+    }
+}