@deksden-com/dd-flow-cli 0.9.0-beta.14 → 0.9.0-beta.141

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

@@ -0,0 +1,435 @@
+import path from "node:path";
+import fs from "node:fs";
+import { createHash } from "node:crypto";
+import { AppError } from "../shared/errors.js";
+import { RetainedExecutionBundle } from "./execution-bundles.js";
+import { PreparedMemoryFinishReview } from "./memory-finish-handler.js";
+import { PreparedMemoryFinishReadiness } from "./memory-finish-readiness.js";
+import { readDescriptorStageInput } from "./descriptor-stage-coordinator.js";
+import { appendAudit } from "./audit.js";
+import { hybridDigest } from "./hybrid-contracts.js";
+import { prepareStagePacket, acceptStagePacket, publishStagePacket, resolveStagePublicationPath, readAcceptedStageData } from "./stage-report-renderer.js";
+import { ObservedMemorySources } from "./memory-source-observations.js";
+import { memorySourceKey, PreparedMemoryStageResult } from "./memory-stage-results.js";
+import { PreparedDescriptorStageSettlement } from "./descriptor-stage-settlement.js";
+import { assertPreparedRunBundleSqlAuthority } from "./runs.js";
+import { readMemoryInitBootstrapReadiness } from "./memory-init-bootstrap-readiness.js";
+import { readMemoryInitGitPolicy } from "./memory-init-git-policy.js";
+import { reviewedMemoryGitFiles } from "./memory-git-integration.js";
+const token = Symbol("memory-finish-evidence"), event = "memory.finish_evidence";
+const hash = (bytes) => createHash("sha256").update(bytes).digest("hex");
+function refuse(reason) {
+    throw new AppError("memory_finish_evidence_invalid", "Finish evidence lacks independently prepared acceptance custody", 2, { reason, effect: "no_effect" });
+}
+/** Terminal inventory and receipts belong to the accepted review/evidence
+ * owners. Optional echoes cannot introduce new references or semantic claims. */
+export function projectMemoryFinishResult(value, owner, resultSha256) {
+    if (!value || typeof value !== "object" || Array.isArray(value))
+        return value;
+    const candidate = value;
+    function reject() {
+        if (resultSha256 === undefined)
+            refuse("terminal_result_projection_changed");
+        throw new AppError("memory_finish_evidence_invalid", "Omit units, findings and details: the CLI preserves accepted review coverage and its finish evidence. Put the completion assessment in summary; correct this proposal without rerunning integration or settled checks", 2, { reason: "terminal_result_projection_changed", phase: "prepare", effect: "no_effect", recoverable: true, result_sha256: resultSha256 });
+    }
+    const subset = (provided, accepted) => Array.isArray(provided)
+        && provided.every(item => accepted.some(original => hybridDigest(item) === hybridDigest(original)));
+    if (candidate.units !== undefined) {
+        if (!Array.isArray(candidate.units))
+            reject();
+        const seen = new Set();
+        for (const unit of candidate.units) {
+            if (!unit || typeof unit !== "object" || Array.isArray(unit))
+                reject();
+            const selected = owner.units.find(original => original.id === unit.id);
+            if (!selected || seen.has(unit.id))
+                reject();
+            seen.add(unit.id);
+            for (const [key, claim] of Object.entries(unit)) {
+                if (!Object.hasOwn(selected, key) || (["artifacts", "evidence"].includes(key)
+                    ? !subset(claim, selected[key]) : hybridDigest(claim) !== hybridDigest(selected[key])))
+                    reject();
+            }
+        }
+    }
+    if (candidate.findings !== undefined && !subset(candidate.findings, owner.findings))
+        reject();
+    if (candidate.details !== undefined) {
+        if (!candidate.details || typeof candidate.details !== "object" || Array.isArray(candidate.details))
+            reject();
+        for (const [key, claim] of Object.entries(candidate.details)) {
+            if (!Object.hasOwn(owner.details, key) || (key === "checks" ? !subset(claim, owner.details.checks)
+                : hybridDigest(claim) !== hybridDigest(owner.details[key])))
+                reject();
+        }
+    }
+    return { ...candidate, units: owner.units, findings: owner.findings, details: owner.details };
+}
+function records(context, scope) {
+    const rows = context.db.all("SELECT payload_json FROM audit_events WHERE project_id=? AND event_type=? AND json_extract(payload_json,'$.run_id')=? LIMIT 2", [scope.projectId, event, scope.runId]);
+    if (rows.length > 1 || rows.some(row => Buffer.byteLength(row.payload_json) > 2 * 1024 * 1024))
+        refuse("ambiguous_evidence_receipt");
+    return rows[0] ? JSON.parse(rows[0].payload_json) : null;
+}
+function acceptance(context, scope) {
+    const rows = context.db.all("SELECT payload_json FROM audit_events WHERE project_id=? AND event_type='memory.finish_acceptance' AND json_extract(payload_json,'$.run_id')=? LIMIT 2", [scope.projectId, scope.runId]);
+    if (rows.length > 1 || rows.some(row => Buffer.byteLength(row.payload_json) > 2 * 1024 * 1024))
+        refuse("ambiguous_finish_acceptance");
+    return rows[0] ? JSON.parse(rows[0].payload_json) : null;
+}
+/** SQL-only historical byte/projection custody. Callers must independently
+ * prepare the genuine accepted review owner outside their writer. This does
+ * not re-observe today's integration checkout or grant RUN closure. */
+export function readAcceptedMemoryFinishEvidence(context, input) {
+    if (!(input.bundle instanceof RetainedExecutionBundle) || input.bundle.descriptor.descriptor.id !== "mb-init"
+        || !PreparedMemoryFinishReview.isPrepared(input.review))
+        refuse("registered_memory_review_required");
+    const scope = { ...input.scope, stage: "finish" };
+    input.review.assertCustody(context);
+    const run = assertPreparedRunBundleSqlAuthority(context, scope, input.bundle), index = JSON.parse(run.index_json);
+    const stage = index.stage_runs.find((item) => item.stage === "finish");
+    const evidence = records(context, scope), accepted = acceptance(context, scope);
+    const data = readAcceptedStageData(context, scope), reviewData = readAcceptedStageData(context, { ...scope, stage: "review" });
+    if (!stage || stage.status !== "done" || !evidence || !accepted
+        || evidence.schema_id !== "dd-flow/memory-finish-evidence@1"
+        || evidence.project_id !== scope.projectId || evidence.run_id !== scope.runId || evidence.stage !== "finish"
+        || evidence.attempt !== stage.attempt || evidence.input_sha256 !== stage.input_sha256
+        || evidence.bundle_sha256 !== input.bundle.sha256 || evidence.review_sha256 !== reviewData.result.sha256
+        || !input.review.bytes().equals(reviewData.bytes)
+        || data.data_schema_id !== "dd-flow/mb-init-finish-result@1" || data.input_sha256 !== stage.input_sha256
+        || hybridDigest(evidence.checks) !== hybridDigest(input.review.finalChecks(context)))
+        refuse("accepted_finish_evidence_changed");
+    const expectedAcceptance = { schema_id: "dd-flow/memory-finish-acceptance@1", project_id: scope.projectId, run_id: scope.runId,
+        stage: "finish", attempt: stage.attempt, input_sha256: stage.input_sha256, bundle_sha256: input.bundle.sha256,
+        evidence_sha256: hybridDigest(evidence), result_sha256: data.result.sha256 };
+    if (hybridDigest(accepted) !== hybridDigest(expectedAcceptance))
+        refuse("accepted_finish_receipt_changed");
+    const root = run.run_root ?? run.run_dir;
+    const packet = (ref, name) => {
+        if (!ref || typeof ref.path !== "string" || typeof ref.sha256 !== "string" || !/^[a-f0-9]{64}$/.test(ref.sha256)
+            || ref.path !== `${input.bundle.descriptor.stage("finish").directory}/evidence/${name}.json`)
+            refuse("historical_evidence_reference_changed");
+        const rows = context.db.all("SELECT payload_json FROM audit_events WHERE project_id=? AND event_type='flow_run.stage_packet' AND json_extract(payload_json,'$.run_id')=? AND json_extract(payload_json,'$.stage')='finish' AND json_extract(payload_json,'$.sha256')=? LIMIT 2", [scope.projectId, scope.runId, ref.sha256]);
+        if (rows.length !== 1 || Buffer.byteLength(rows[0].payload_json) > 4 * 1024 * 1024)
+            refuse("historical_evidence_packet_missing");
+        const value = JSON.parse(rows[0].payload_json);
+        if (value.attempt !== stage.attempt || typeof value.base64 !== "string" || typeof value.file !== "string"
+            || resolveStagePublicationPath(context, scope.projectId, scope.runId, value.file) !== path.join(root, ref.path))
+            refuse("historical_evidence_packet_changed");
+        const bytes = Buffer.from(value.base64, "base64");
+        if (!bytes.length || bytes.length > 2 * 1024 * 1024 || bytes.toString("base64") !== value.base64 || hash(bytes) !== ref.sha256)
+            refuse("historical_evidence_bytes_changed");
+        return { bytes, value: JSON.parse(bytes.toString("utf8")) };
+    };
+    const coverage = packet(evidence.coverage, "coverage"), integration = packet(evidence.integration, "integration"), readiness = packet(evidence.normal_flow_readiness, "normal-flow-readiness");
+    const reviewed = JSON.parse(input.review.bytes().toString("utf8"));
+    if (hybridDigest(coverage.value) !== hybridDigest({ schema_id: "dd-flow/memory-finish-coverage@1", project_id: scope.projectId,
+        run_id: scope.runId, bundle_sha256: input.bundle.sha256, review_sha256: reviewData.result.sha256,
+        units: reviewed.units, findings: reviewed.findings }) || hybridDigest(readiness.value) !== evidence.readiness_sha256
+        || hybridDigest(readiness.value.integration) !== hybridDigest(integration.value)
+        || readiness.value.schema_id !== "dd-flow/memory-finish-readiness-observation@1"
+        || hybridDigest(readiness.value.scope) !== hybridDigest(input.scope)
+        || readiness.value.bundle_sha256 !== input.bundle.sha256 || readiness.value.execution_sha256 !== input.bundle.execution.sha256
+        || readiness.value.readiness !== "entry_prepared" || readiness.value.model_access !== "unknown")
+        refuse("historical_evidence_projection_changed");
+    const frozen = input.bundle.execution.snapshot().scope;
+    const request = { requestId: frozen.requestId, projectRoot: frozen.projectRoot, workspaceRoot: frozen.workspace };
+    const bootstrap = readMemoryInitBootstrapReadiness(context, request), policy = readMemoryInitGitPolicy(context, request);
+    if (!bootstrap || !policy || bootstrap.projectId !== scope.projectId
+        || bootstrap.authority.binding.execution_sha256 !== input.bundle.execution.sha256
+        || bootstrap.authority.binding.git_policy_sha256 !== hybridDigest(policy)
+        || policy.target_sha256 !== hybridDigest(bootstrap.authority.binding.target)
+        || readiness.value.bootstrap_authority_sha256 !== hybridDigest(bootstrap.authority)
+        || readiness.value.pack_sha256 !== bootstrap.authority.binding.pack_sha256)
+        refuse("historical_terminal_bootstrap_policy_changed");
+    const integrated = integration.value;
+    const reviewedFiles = reviewedMemoryGitFiles(input.review.reviewedSources(context));
+    if (integrated.schema_id !== "dd-flow/memory-git-integration-observation@1"
+        || integrated.project_root !== request.projectRoot || integrated.workspace_root !== request.workspaceRoot
+        || integrated.repository !== policy.repository || integrated.workspace_branch !== policy.workspace_branch
+        || integrated.integration_ref !== `refs/heads/${policy.integration_branch}`
+        || integrated.reviewed_files_sha256 !== hybridDigest(reviewedFiles)
+        || !reviewedFiles.some(ref => ref.path === ".memory-bank/index.md")
+        || [integrated.workspace_head, integrated.integration_head, integrated.memory_tree]
+            .some(value => typeof value !== "string" || !/^[a-f0-9]{40,64}$/.test(value))
+        || [integrated.tracked_index_entry_sha256, integrated.memory_index_visibility_sha256, integrated.memory_status_sha256]
+            .some(value => typeof value !== "string" || !/^[a-f0-9]{64}$/.test(value)))
+        refuse("historical_terminal_integration_policy_changed");
+    const sources = new Map();
+    for (const ref of input.review.reviewedSources(context)) {
+        sources.set(memorySourceKey(ref.root, ref.path), ref.sha256);
+        if (ref.root === "workspace")
+            sources.set(memorySourceKey("project", ref.path), ref.sha256);
+    }
+    for (const ref of [evidence.coverage, evidence.integration, evidence.normal_flow_readiness, ...evidence.checks])
+        sources.set(memorySourceKey("run", ref.path), ref.sha256);
+    const result = PreparedMemoryStageResult.prepare(data.bytes, input.bundle.descriptor, {
+        runId: scope.runId, stage: "finish", inputSha256: stage.input_sha256,
+        predecessors: [{ stage: "review", result: reviewData.result, input_sha256: reviewData.input_sha256 }],
+        unitIds: reviewed.units.map((unit) => unit.id), sources,
+        historicalEvidence: new Set(reviewed.units.flatMap((unit) => unit.evidence.map(ref => `${memorySourceKey(ref.root, ref.path)}\0${ref.sha256}`)))
+    });
+    const value = result.value(), references = { coverage: evidence.coverage,
+        checks: evidence.checks.map(({ path, sha256 }) => ({ path, sha256 })),
+        integration: evidence.integration, normal_flow_readiness: evidence.normal_flow_readiness };
+    if (value.outcome !== "accepted" || hybridDigest(value.units) !== hybridDigest(reviewed.units)
+        || hybridDigest(value.findings) !== hybridDigest(reviewed.findings) || hybridDigest(value.details) !== hybridDigest(references))
+        refuse("historical_finish_result_projection_changed");
+    input.review.assertCustody(context);
+    return { receipt: structuredClone(accepted), evidence: structuredClone(evidence), result: data,
+        packets: [coverage, integration, readiness].map((item, i) => ({ ...item,
+            reference: structuredClone([evidence.coverage, evidence.integration, evidence.normal_flow_readiness][i]) })) };
+}
+/** Independently constructed terminal artifacts, retained atomically and
+ * published by the existing Stage packet mechanism. This is not a Stage/RUN
+ * acceptance receipt: publication can be pending after the SQL commit. */
+export class PreparedMemoryFinishEvidence {
+    static isPrepared(value) {
+        return typeof value === "object" && value !== null && #review in value;
+    }
+    #scope;
+    #bundle;
+    #review;
+    #readiness;
+    #input;
+    #packets;
+    #receipt;
+    #registered;
+    constructor(key, scope, bundle, review, readiness, input, packets, receipt, registered) {
+        if (key !== token)
+            refuse("evidence_token_required");
+        this.#scope = scope;
+        this.#bundle = bundle;
+        this.#review = review;
+        this.#readiness = readiness;
+        this.#input = input;
+        this.#packets = packets;
+        this.#receipt = structuredClone(receipt);
+        this.#registered = registered;
+        Object.freeze(this);
+    }
+    static prepare(context, input) {
+        if (!(input.bundle instanceof RetainedExecutionBundle) || input.bundle.descriptor.descriptor.id !== "mb-init")
+            refuse("registered_memory_bundle_required");
+        if (context.db.isOwnedWriteTransaction?.())
+            refuse("preparation_outside_writer_required");
+        const scope = { ...input.scope, stage: "finish" }, selected = context.db.readSnapshot(() => readDescriptorStageInput(context, scope, input.bundle));
+        const prior = context.db.readSnapshot(() => records(context, scope));
+        const review = PreparedMemoryFinishReview.prepare(context, input), readiness = PreparedMemoryFinishReadiness.prepare(context, input);
+        const value = JSON.parse(review.bytes().toString("utf8")), ready = readiness.value(), checks = review.finalChecks(context);
+        const materials = [
+            { name: "coverage", value: { schema_id: "dd-flow/memory-finish-coverage@1", project_id: scope.projectId, run_id: scope.runId,
+                    bundle_sha256: input.bundle.sha256, review_sha256: hash(review.bytes()), units: value.units, findings: value.findings } },
+            { name: "integration", value: ready.integration }, { name: "normal-flow-readiness", value: ready }
+        ];
+        const packets = materials.map(item => {
+            const bytes = Buffer.from(`${JSON.stringify(item.value, null, 2)}\n`);
+            if (bytes.length > 2 * 1024 * 1024)
+                refuse("evidence_artifact_exceeds_bound");
+            const file = path.join(selected.runRoot, input.bundle.descriptor.stage("finish").directory, "evidence", `${item.name}.json`);
+            if (!prior) {
+                try {
+                    fs.lstatSync(file);
+                    refuse("evidence_custody_missing");
+                }
+                catch (error) {
+                    if (error.code !== "ENOENT")
+                        throw error;
+                }
+                if (context.db.get("SELECT 1 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')='finish' AND json_extract(payload_json,'$.sha256')=? LIMIT 1", [scope.projectId, scope.runId, hash(bytes)]))
+                    refuse("evidence_custody_missing");
+            }
+            return prepareStagePacket(file, bytes);
+        });
+        const reference = (index) => ({ path: path.relative(selected.runRoot, packets[index].file).split(path.sep).join("/"), sha256: packets[index].sha256 });
+        const receipt = { schema_id: "dd-flow/memory-finish-evidence@1", project_id: scope.projectId, run_id: scope.runId, stage: "finish",
+            attempt: selected.attempt, input_sha256: selected.inputSha256, bundle_sha256: input.bundle.sha256,
+            review_sha256: hash(review.bytes()), readiness_sha256: hybridDigest(ready), coverage: reference(0), checks,
+            integration: reference(1), normal_flow_readiness: reference(2) };
+        if (Buffer.byteLength(JSON.stringify(receipt)) > 2 * 1024 * 1024)
+            refuse("evidence_receipt_exceeds_bound");
+        if (prior && hybridDigest(prior) !== hybridDigest(receipt))
+            refuse("evidence_request_conflict");
+        const prepared = new PreparedMemoryFinishEvidence(token, scope, input.bundle, review, readiness, selected, packets, receipt, !!prior);
+        prepared.assertCustody(context);
+        return prepared;
+    }
+    receipt() { return structuredClone(this.#receipt); }
+    references() {
+        const value = this.#receipt;
+        return { coverage: { ...value.coverage }, checks: value.checks.map(({ path, sha256 }) => ({ path, sha256 })),
+            integration: { ...value.integration }, normal_flow_readiness: { ...value.normal_flow_readiness } };
+    }
+    /** Fresh terminal result preparation, never a historical replay reader.
+     * The proposal cannot replace accepted review coverage or CLI evidence. */
+    prepareResult(context, bytes) {
+        const bundle = this.#bundle;
+        if (!(bytes instanceof Uint8Array) || !bytes.length || bytes.length > 1024 * 1024)
+            refuse("invalid_result_bytes");
+        if (context.db.isOwnedWriteTransaction?.())
+            refuse("physical_preparation_outside_writer_required");
+        this.revalidate(context);
+        const sources = this.captureSources(context);
+        const review = readAcceptedStageData(context, { ...this.#scope, stage: "review" });
+        if (typeof review.input_sha256 !== "string")
+            refuse("accepted_review_input_missing");
+        const reviewed = JSON.parse(this.#review.bytes().toString("utf8"));
+        let proposal;
+        try {
+            proposal = JSON.parse(new TextDecoder("utf-8", { fatal: true }).decode(bytes));
+        }
+        catch {
+            refuse("invalid_result_bytes");
+        }
+        const canonical = projectMemoryFinishResult(proposal, { units: reviewed.units, findings: reviewed.findings, details: this.references() }, hash(bytes));
+        const result = PreparedMemoryStageResult.prepare(Buffer.from(JSON.stringify(canonical)), bundle.descriptor, {
+            runId: this.#scope.runId, stage: "finish", inputSha256: this.#input.inputSha256,
+            predecessors: [{ stage: "review", result: review.result, input_sha256: review.input_sha256 }],
+            unitIds: reviewed.units.map((unit) => unit.id), sources: sources.hashes(),
+            historicalEvidence: new Set(reviewed.units.flatMap((unit) => unit.evidence.map(ref => `${memorySourceKey(ref.root, ref.path)}\0${ref.sha256}`)))
+        });
+        const value = result.value();
+        if (value.outcome !== "accepted" || hybridDigest(value.units) !== hybridDigest(reviewed.units)
+            || hybridDigest(value.findings) !== hybridDigest(reviewed.findings)
+            || hybridDigest(value.details) !== hybridDigest(this.references()))
+            refuse("terminal_result_projection_changed");
+        sources.revalidate();
+        this.revalidate(context);
+        this.assertRegisteredCustody(context);
+        return result;
+    }
+    /** Fresh Stage acceptance only. RUN closure and accepted historical replay
+     * require their independent terminal readers; neither is granted here. */
+    settleFresh(context, input) {
+        const scope = this.#scope;
+        if (context.db.isOwnedWriteTransaction?.())
+            refuse("settlement_preparation_outside_writer_required");
+        if (acceptance(context, scope))
+            refuse("use_accepted_finish_replay");
+        const result = this.prepareResult(context, input.bytes);
+        const receipt = { schema_id: "dd-flow/memory-finish-acceptance@1", project_id: scope.projectId, run_id: scope.runId,
+            stage: "finish", attempt: this.#input.attempt, input_sha256: this.#input.inputSha256,
+            bundle_sha256: this.#bundle.sha256, evidence_sha256: hybridDigest(this.#receipt), result_sha256: result.sha256 };
+        const settlement = PreparedDescriptorStageSettlement.prepare(context, {
+            projectRoot: this.#bundle.execution.snapshot().scope.projectRoot, runId: scope.runId, stage: "finish",
+            hookEventId: input.hookEventId, bytes: result.bytes()
+        });
+        this.revalidate(context);
+        try {
+            return settlement.apply(context, writer => {
+                this.assertRegisteredCustody(writer);
+                if (!writer.db.isOwnedWriteTransaction?.())
+                    refuse("owned_acceptance_writer_required");
+                if (acceptance(writer, scope))
+                    refuse("fresh_acceptance_already_exists");
+                appendAudit(writer, { projectId: scope.projectId, eventType: "memory.finish_acceptance", payload: receipt });
+                if (hybridDigest(acceptance(writer, scope)) !== hybridDigest(receipt))
+                    refuse("finish_acceptance_readback_failed");
+            });
+        }
+        catch (error) {
+            if (hybridDigest(acceptance(context, scope)) === hybridDigest(receipt))
+                throw new AppError("memory_finish_acceptance_pending", "Finish acceptance committed; terminal recovery remains required", 1, { effect: "committed", run_id: scope.runId, result_sha256: result.sha256,
+                    next_action: "reconcile_accepted_finish", cause: error instanceof AppError ? error.code : "finish_settlement_failure" });
+            throw error;
+        }
+    }
+    assertCustody(context) {
+        this.#review.assertCustody(context);
+        this.#readiness.assertCustody(context);
+        if (hybridDigest(readDescriptorStageInput(context, this.#scope, this.#bundle)) !== hybridDigest(this.#input))
+            refuse("finish_input_changed");
+        const prior = records(context, this.#scope);
+        if (this.#registered && !prior || prior && hybridDigest(prior) !== hybridDigest(this.#receipt))
+            refuse("evidence_receipt_changed");
+        if (prior)
+            for (const packet of this.#packets) {
+                const rows = context.db.all("SELECT payload_json FROM audit_events WHERE project_id=? AND event_type='flow_run.stage_packet' AND json_extract(payload_json,'$.run_id')=? AND json_extract(payload_json,'$.stage')='finish' AND json_extract(payload_json,'$.sha256')=? LIMIT 2", [this.#scope.projectId, this.#scope.runId, packet.sha256]);
+                if (rows.length !== 1 || Buffer.byteLength(rows[0].payload_json) > 4 * 1024 * 1024)
+                    refuse("evidence_packet_custody_missing");
+                const stored = JSON.parse(rows[0].payload_json);
+                if (stored.attempt !== this.#input.attempt || stored.base64 !== packet.bytes.toString("base64")
+                    || resolveStagePublicationPath(context, this.#scope.projectId, this.#scope.runId, stored.file) !== packet.file)
+                    refuse("evidence_packet_changed");
+            }
+    }
+    assertRegisteredCustody(context) {
+        if (!this.#registered)
+            refuse("registered_evidence_required");
+        this.assertCustody(context);
+    }
+    /** Only independently selected final sources may bind terminal result bytes. */
+    captureSources(context) {
+        const bundle = this.#bundle;
+        if (context.db.isOwnedWriteTransaction?.())
+            refuse("physical_preparation_outside_writer_required");
+        this.assertRegisteredCustody(context);
+        const expected = new Map();
+        const add = (location, sha256) => {
+            const key = memorySourceKey(location.root, location.path), prior = expected.get(key);
+            if (prior && prior.sha256 !== sha256)
+                refuse("conflicting_terminal_sources");
+            expected.set(key, { location, sha256 });
+        };
+        for (const ref of this.#review.reviewedSources(context)) {
+            add({ root: ref.root, path: ref.path }, ref.sha256);
+            if (ref.root === "workspace")
+                add({ root: "project", path: ref.path }, ref.sha256);
+        }
+        for (const ref of [this.#receipt.coverage, this.#receipt.integration, this.#receipt.normal_flow_readiness, ...this.#receipt.checks])
+            add({ root: "run", path: ref.path }, ref.sha256);
+        const frozen = bundle.execution.snapshot().scope;
+        const observed = ObservedMemorySources.capture({ run: this.#input.runRoot, project: frozen.projectRoot, workspace: frozen.workspace }, [...expected.values()].map(item => item.location));
+        const hashes = observed.hashes();
+        for (const [key, item] of expected)
+            if (hashes.get(key) !== item.sha256)
+                refuse("terminal_source_bytes_changed");
+        this.assertRegisteredCustody(context);
+        return observed;
+    }
+    revalidate(context) {
+        const readiness = this.#readiness;
+        if (context.db.isOwnedWriteTransaction?.())
+            refuse("physical_revalidation_outside_writer_required");
+        this.#review.revalidate(context);
+        readiness.revalidate(context);
+        this.assertCustody(context);
+    }
+    register(context) {
+        const scope = this.#scope;
+        if (context.db.isOwnedWriteTransaction?.())
+            refuse("registration_outside_writer_required");
+        try {
+            this.revalidate(context);
+            const replay = context.db.writeTransaction(() => {
+                this.assertCustody(context);
+                if (records(context, this.#scope))
+                    return true;
+                for (const packet of this.#packets)
+                    acceptStagePacket(context, { ...this.#scope, prepared: packet });
+                appendAudit(context, { projectId: this.#scope.projectId, eventType: event, payload: this.#receipt });
+                this.assertCustody(context);
+                return false;
+            }, "memory.registerFinishEvidence");
+            this.#registered = true;
+            for (const packet of this.#packets)
+                publishStagePacket(context, this.#scope.projectId, this.#scope.runId, "finish", packet.file);
+            const observed = ObservedMemorySources.capture({ run: this.#input.runRoot }, this.#packets.map(packet => ({ root: "run", path: path.relative(this.#input.runRoot, packet.file).split(path.sep).join("/") })));
+            const hashes = observed.hashes();
+            for (const ref of [this.#receipt.coverage, this.#receipt.integration, this.#receipt.normal_flow_readiness])
+                if (hashes.get(memorySourceKey("run", ref.path)) !== ref.sha256)
+                    refuse("published_evidence_changed");
+            this.revalidate(context);
+            return { receipt: this.receipt(), references: this.references(), replay };
+        }
+        catch (error) {
+            const retained = records(context, scope);
+            if (retained && hybridDigest(retained) === hybridDigest(this.#receipt)) {
+                this.#registered = true;
+                throw new AppError("memory_finish_evidence_pending", "Finish evidence retained; publication or revalidation requires recovery", 1, { effect: "committed", run_id: this.#scope.runId, receipt_sha256: hybridDigest(this.#receipt),
+                    next_action: "reconcile_exact_finish_evidence", cause: error instanceof AppError ? error.code : "evidence_publication_failure" });
+            }
+            throw error;
+        }
+    }
+}

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

@@ -0,0 +1,215 @@
+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 {
+    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) || input.bundle.descriptor.descriptor.id !== "mb-init"
+            || input.bundle.descriptor.successor("review", "accepted") !== "finish")
+            refuse("registered_memory_bundle_required");
+        if (context.db.isOwnedWriteTransaction?.())
+            refuse("preparation_outside_writer_required");
+        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); }
+    finalChecks(context) { this.assertCustody(context); return this.#review.finalChecks(context); }
+    assertCustody(context) {
+        this.#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) { this.#review.revalidate(context); this.assertCustody(context); }
+}
+/** Productive terminal entry awaiting the complete six-stage registry. 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 || bundle.descriptor.descriptor.id !== "mb-init" || !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 || bundle.descriptor.descriptor.id !== "mb-init")
+        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 || bundle.descriptor.descriptor.id !== "mb-init"
+        || !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 || bundle.descriptor.descriptor.id !== "mb-init")
+        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 || bundle.descriptor.descriptor.id !== "mb-init")
+        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 || bundle.descriptor.descriptor.id !== "mb-init")
+        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" });
+    }
+}