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

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

@@ -0,0 +1,491 @@
+import { AppError } from "../shared/errors.js";
+import { RetainedExecutionBundle } from "./execution-bundles.js";
+import { assertPreparedRunBundleSqlAuthority } from "./runs.js";
+import { PreparedMemoryFinishReview } from "./memory-finish-handler.js";
+import { readMemoryInitBootstrapReadiness } from "./memory-init-bootstrap-readiness.js";
+import { readMemoryInitGitPolicy } from "./memory-init-git-policy.js";
+import { hybridDigest } from "./hybrid-contracts.js";
+import { assertReviewedProjectGitInventory, observeReviewedProjectGitIntegration } from "./project-git-integration.js";
+import { observeReviewedMemoryGitIntegration, reviewedMemoryGitFiles, isReviewedMemoryGitFile, assertMemoryGitRemovalSources } from "./memory-git-integration.js";
+import { createHash } from "node:crypto";
+import { readBoundedReleaseFile } from "./release-source.js";
+import { spawnSync } from "node:child_process";
+import { ObservedMemorySources } from "./memory-source-observations.js";
+import { memorySourceKey } from "./memory-stage-results.js";
+import { readMemoryInitProjectBootstrap } from "./memory-init-project-bootstrap.js";
+import { readPublishedMemoryReferenceInventory } from "./memory-layer-publication.js";
+import { readDescriptorStageInput } from "./descriptor-stage-coordinator.js";
+import { appendAudit } from "./audit.js";
+import fs from "node:fs";
+import path from "node:path";
+import { readMemoryUpgradeBootstrapReadiness } from "./memory-upgrade-bootstrap-readiness.js";
+import { readUpgradeStorageReadiness } from "./memory-upgrade-storage-readiness.js";
+import { readCompletedMemoryUpgradePublication } from "./memory-upgrade-publication-custody.js";
+import { readDescriptorRootWork } from "./descriptor-root-work.js";
+import { stageGraphScope } from "./stage-work-graph.js";
+import { selectMemoryCompositionRegistration } from "./memory-composition-registration.js";
+import { readAcceptedStageData } from "./stage-report-renderer.js";
+import { localEnvironmentAllowed } from "./workspace-files.js";
+import { observeMemoryDocumentInventory } from "./memory-repair-document-delta.js";
+const token = Symbol("memory-finish-integration");
+function refuse(reason) {
+    throw new AppError("memory_finish_integration_invalid", "Finish lacks policy-bound reviewed Git integration", 2, { reason, effect: "no_effect" });
+}
+export function readMemoryFinishGitSelection(context, scope, bundle) {
+    assertPreparedRunBundleSqlAuthority(context, scope, bundle);
+    const frozen = bundle.execution.snapshot().scope;
+    const request = { requestId: frozen.requestId, projectRoot: frozen.projectRoot, workspaceRoot: frozen.workspace };
+    if (bundle.descriptor.descriptor.id === "mb-upgrade") {
+        const readiness = readMemoryUpgradeBootstrapReadiness(context, request), storage = readUpgradeStorageReadiness(context, request);
+        const git = storage?.selection?.payload.git;
+        if (!readiness?.hasGitPolicy || !storage?.selection || !git || readiness.projectId !== scope.projectId
+            || readiness.authority.binding.execution_sha256 !== bundle.execution.sha256
+            || readiness.authority.binding.storage_sha256 !== storage.sha256)
+            refuse("policy_bootstrap_binding_changed");
+        return { kind: "upgrade", readiness, storage, policy: { scope: request, ...git.policy },
+            selection: { projectRoot: request.projectRoot, workspaceRoot: request.workspaceRoot,
+                integrationBranch: git.policy.integration_branch, gitExecutable: git.executable }, gitSha256: git.probe.executable_sha256 };
+    }
+    const readiness = readMemoryInitBootstrapReadiness(context, request), policy = readMemoryInitGitPolicy(context, request);
+    if (!readiness || !policy || readiness.projectId !== scope.projectId
+        || readiness.authority.binding.execution_sha256 !== bundle.execution.sha256
+        || readiness.authority.binding.git_policy_sha256 !== hybridDigest(policy)
+        || policy.target_sha256 !== hybridDigest(readiness.authority.binding.target))
+        refuse("policy_bootstrap_binding_changed");
+    const selection = { projectRoot: request.projectRoot, workspaceRoot: request.workspaceRoot,
+        integrationBranch: policy.integration_branch, gitExecutable: readiness.authority.binding.target.tools.git };
+    const gitSha256 = readiness.authority.binding.target.tool_probes?.git.executable_sha256;
+    if (typeof gitSha256 !== "string" || !/^[a-f0-9]{64}$/.test(gitSha256))
+        refuse("pinned_git_executable_required");
+    return { kind: "init", readiness, policy, selection, gitSha256 };
+}
+function assertGitExecutable(selection, sha256) {
+    if (createHash("sha256").update(readBoundedReleaseFile(selection.gitExecutable, 64 * 1024 * 1024)).digest("hex") !== sha256)
+        refuse("pinned_git_executable_changed");
+}
+/** Projection only: accepted review may advance project/customized documents,
+ * not canonical defaults, opaque links or CLI recovery records. */
+export function projectMemoryUpgradeFinishInventory(plan, inventory, changes, reviewed, settledDocuments = null) {
+    const files = new Map(plan.beforeFiles().map(entry => [`.memory-bank/${entry.path}`, { ...entry, path: `.memory-bank/${entry.path}` }]));
+    const removed = new Set();
+    const removals = [];
+    for (const action of plan.actions()) {
+        const logical = `.memory-bank/${action.path}`;
+        if (action.after)
+            files.set(logical, { ...action.after, path: logical });
+        else {
+            files.delete(logical);
+            removed.add(logical);
+            if (!action.before || action.before.kind !== "file")
+                refuse("unsupported_upgrade_removal");
+            removals.push({ root: "workspace", path: logical, sha256: action.before.sha256,
+                ...((action.before.mode & 0o111) ? { git_mode: "100755" } : {}) });
+        }
+    }
+    const ownership = new Map(inventory.entries.map(entry => [`.memory-bank/${entry.path}`, entry.ownership]));
+    const semantic = new Set(changes.filter(change => change.action === "semantic-work" && change.to).map(change => change.to));
+    const rootFiles = [];
+    const settled = new Map(settledDocuments?.map(entry => [entry.path, entry]));
+    for (const ref of reviewedMemoryGitFiles(reviewed)) {
+        if (ref.path === ".mb-lint.json") {
+            rootFiles.push(ref);
+            continue;
+        }
+        const before = files.get(ref.path);
+        if (removed.has(ref.path) || before && before.kind !== "file")
+            refuse("reviewed_upgrade_path_not_current_file");
+        if (before?.sha256 === ref.sha256)
+            continue;
+        const owner = ownership.get(ref.path), namespace = /^\.memory-bank\/(?:dd-flow|mbb)\//.test(ref.path);
+        if (ref.path.startsWith(".memory-bank/archive/mb-upgrade/") || owner === "generated"
+            || (owner === "canonical" || namespace && owner !== "project" && owner !== "local-customized") && !semantic.has(ref.path))
+            refuse("review_changed_protected_upgrade_output");
+        const after = settled.get(ref.path);
+        if (!before && (!after || after.kind !== "file" || after.sha256 !== ref.sha256))
+            refuse("unretained_reviewed_output_mode");
+        files.set(ref.path, { path: ref.path, kind: "file", mode: before?.mode ?? (after.mode & 0o777), sha256: ref.sha256 });
+    }
+    const entries = [...files.values()].sort((a, b) => a.path.localeCompare(b.path, "en"));
+    if (settledDocuments && hybridDigest(settledDocuments.filter(entry => entry.kind !== "directory")
+        .map(entry => ({ ...entry, mode: entry.mode & 0o777 })).sort((a, b) => a.path.localeCompare(b.path, "en"))) !== hybridDigest(entries))
+        refuse("unreviewed_repair_inventory_change");
+    const references = [...rootFiles, ...entries.filter(entry => entry.kind === "file"
+            && entry.path.split("/").every(part => localEnvironmentAllowed(part) && ![".git", "node_modules", ".dd-flow"].includes(part)))
+            .map(entry => ({ root: "workspace", path: entry.path, sha256: entry.sha256,
+            ...((entry.mode & 0o111) ? { git_mode: "100755" } : {}) }))].sort((a, b) => a.path.localeCompare(b.path, "en"));
+    return { entries, references, removals: removals.sort((a, b) => a.path.localeCompare(b.path, "en")) };
+}
+export function readMemoryUpgradeFinishInventory(context, scope, bundle, review) {
+    if (!PreparedMemoryFinishReview.isPrepared(review))
+        refuse("accepted_review_required");
+    const reviewed = review.reviewedSources(context);
+    const selected = readMemoryFinishGitSelection(context, scope, bundle);
+    if (selected.kind !== "upgrade" || !selected.storage.selection)
+        refuse("upgrade_selection_required");
+    const root = readDescriptorRootWork(context, scope, bundle);
+    const registration = selectMemoryCompositionRegistration(context, { ...stageGraphScope(context, scope.projectId, scope.runId, "upgrade"),
+        stage: "upgrade", parent_work_id: root.workId });
+    const published = readCompletedMemoryUpgradePublication(context, { scope: registration.scope,
+        selection_sha256: selected.storage.selection.sha256, execution_sha256: bundle.execution.sha256,
+        registration_sha256: hybridDigest(registration), bootstrap_sha256: hybridDigest(selected.readiness.authority) });
+    const accepted = readAcceptedStageData(context, { ...scope, stage: "upgrade" }), value = JSON.parse(accepted.bytes.toString("utf8"));
+    const recordPath = `.memory-bank/archive/mb-upgrade/${selected.storage.selection.sha256}/migration.json`;
+    const record = published.plan.outputs().find(entry => `.memory-bank/${entry.path}` === recordPath);
+    const migrationRecord = record && { path: recordPath, sha256: record.sha256 };
+    if (!migrationRecord || accepted.data_schema_id !== "dd-flow/mb-upgrade-stage-result@1" || value.stage !== "upgrade" || value.outcome !== "accepted"
+        || accepted.input_sha256 !== registration.input_sha256 || hybridDigest([value.details?.migration_record]) !== hybridDigest([migrationRecord])
+        || !reviewed.some(ref => ref.root === "workspace" && ref.path === migrationRecord.path && ref.sha256 === migrationRecord.sha256))
+        refuse("accepted_upgrade_migration_record_changed");
+    const diff = readAcceptedStageData(context, { ...scope, stage: "diff-analysis" }), changes = JSON.parse(diff.bytes.toString("utf8")).details.path_map;
+    return { ...projectMemoryUpgradeFinishInventory(published.plan, selected.storage.selection.payload.current.inventory.inventory, changes, reviewed, review.reviewedDocumentInventory(context)),
+        migrationRecord, publicationSha256: published.plan.sha256, binding: published.binding };
+}
+export function observeMemoryUpgradeFinishInventory(root, expected) {
+    const snapshot = observeMemoryDocumentInventory(root);
+    const entries = snapshot.entries().filter(entry => entry.kind !== "directory").map(entry => ({ ...entry, mode: entry.mode & 0o777 }));
+    if (hybridDigest(entries.sort((a, b) => a.path.localeCompare(b.path, "en"))) !== hybridDigest(expected.entries))
+        refuse("upgrade_finish_inventory_changed");
+    return snapshot;
+}
+/** Physical Git operation only; callers must independently select accepted files
+ * and retain each mutation's intent. No ambient Git redirection or whole-tree add. */
+export function integrateReviewedMemoryFiles(selection, environment, references, runId, mutation, policy, removals = []) {
+    if (!Array.isArray(references) || !Array.isArray(removals) || !references.length
+        || references.length + removals.length > 4096 || !references.some(ref => ref?.path === ".memory-bank/index.md")
+        || [...references, ...removals].some(ref => !isReviewedMemoryGitFile(ref))
+        || removals.some(ref => !ref.path.startsWith(".memory-bank/") || ref.path === ".memory-bank/index.md"))
+        refuse("invalid_owned_inventory");
+    return integrateReviewedFiles(selection, environment, references, mutation, policy, removals, () => observeReviewedMemoryGitIntegration(selection, environment, references, removals), `chore(${runId.toLowerCase()}): integrate reviewed Memory Bank`);
+}
+/** Physical project-file variant only. Accepted review and the original dirty
+ * baseline remain the caller's responsibility; this is not a RUN authority. */
+export function integrateReviewedProjectFiles(selection, environment, references, runId, mutation, policy, removals = []) {
+    assertReviewedProjectGitInventory(references, removals);
+    return integrateReviewedFiles(selection, environment, references, mutation, policy, removals, () => observeReviewedProjectGitIntegration(selection, environment, references, removals), `chore(${runId.toLowerCase()}): integrate reviewed project changes`);
+}
+function integrateReviewedFiles(selection, environment, references, mutation, policy, removals, observe, message) {
+    const env = { ...Object.fromEntries(Object.entries(environment).filter(([key]) => !key.startsWith("GIT_"))), GIT_LITERAL_PATHSPECS: "1" };
+    const git = (directory, args, write = false, absent = false) => {
+        const result = spawnSync(selection.gitExecutable, ["-c", "core.fsmonitor=false",
+            ...(write && process.platform !== "win32" ? ["-c", "core.filemode=true"] : []), "-C", directory, ...args], { env, encoding: "utf8", timeout: 30000, maxBuffer: 16 * 1024 * 1024, shell: false, windowsHide: true });
+        if (absent && !result.error && !result.signal && result.status !== 0)
+            return "";
+        if (result.error || result.signal || result.status !== 0)
+            throw new AppError("memory_finish_integration_invalid", write ? "Git integration did not return success; inspect the original operation before retrying" : "Git integration preparation failed", 2, { reason: "git_operation_failed", effect: write ? "unknown" : "no_effect", operation: args[0], stderr: result.stderr,
+                next_action: write ? "reconcile_original_integration" : "resolve_git_configuration_or_workspace" });
+        return args.includes("-z") ? result.stdout : result.stdout.trim();
+    };
+    const paths = [...references, ...removals].map(ref => ref.path);
+    if (new Set(paths).size !== paths.length)
+        refuse("invalid_owned_inventory");
+    const source = fs.realpathSync(selection.workspaceRoot), target = fs.realpathSync(selection.projectRoot);
+    const assertModes = () => {
+        if (process.platform === "win32")
+            return;
+        for (const ref of references) {
+            const executable = (fs.lstatSync(path.join(source, ref.path)).mode & 0o111) !== 0;
+            if (executable !== (ref.git_mode === "100755"))
+                refuse("reviewed_workspace_mode_changed");
+        }
+    };
+    assertModes();
+    assertMemoryGitRemovalSources(source, removals);
+    const branch = git(source, ["symbolic-ref", "--short", "HEAD"]);
+    if (target === source ? branch !== selection.integrationBranch
+        : git(target, ["symbolic-ref", "--short", "HEAD"]) !== selection.integrationBranch)
+        refuse("integration_branch_changed");
+    const common = (directory) => fs.realpathSync(path.resolve(directory, git(directory, ["rev-parse", "--git-common-dir"])));
+    if (common(source) !== common(target))
+        refuse("foreign_repository");
+    if (policy && (common(source) !== policy.repository || branch !== policy.workspace_branch))
+        refuse("policy_repository_or_branch_changed");
+    const observed = ObservedMemorySources.capture({ workspace: source }, references.map(({ root, path }) => ({ root, path })));
+    const hashes = observed.hashes();
+    for (const ref of references)
+        if (hashes.get(memorySourceKey(ref.root, ref.path)) !== ref.sha256)
+            refuse("reviewed_workspace_bytes_changed");
+    try {
+        return observe();
+    }
+    catch (error) {
+        if (!(error instanceof AppError) || !["memory_git_integration_invalid", "project_git_integration_invalid"].includes(error.code))
+            throw error;
+    }
+    const visibility = git(source, ["ls-files", "-v", "--", ...paths]);
+    if (visibility.split("\n").filter(Boolean).some(line => !line.startsWith("H ")))
+        refuse("owned_index_visibility_override");
+    if (git(source, ["diff", "--name-only", "--diff-filter=U"]))
+        refuse("unmerged_workspace");
+    const sourceHead = git(source, ["rev-parse", "--verify", "HEAD"], false, true);
+    let ownedHead = sourceHead;
+    const changedCommit = () => {
+        throw new AppError("memory_finish_integration_invalid", "The scoped commit changed before integration completed; reconcile its original effect", 2, { reason: "scoped_commit_changed", effect: "unknown", next_action: "reconcile_original_integration" });
+    };
+    const assertOwnedHead = () => { if (git(source, ["rev-parse", "HEAD"]) !== ownedHead)
+        changedCommit(); };
+    const deleting = [];
+    let removedBytes = 0;
+    for (const ref of removals) {
+        const entry = git(source, ["ls-tree", "-z", "HEAD", "--", ref.path], false, true);
+        if (!entry)
+            continue;
+        if (!new RegExp(`^${ref.git_mode ?? "100644"} blob [a-f0-9]{40,64}\\t`).test(entry))
+            refuse("removed_memory_source_changed");
+        const content = spawnSync(selection.gitExecutable, ["-C", source, "cat-file", "blob", `HEAD:${ref.path}`], { env, timeout: 10000, maxBuffer: 16 * 1024 * 1024, shell: false, windowsHide: true });
+        if (content.error || content.signal || content.status !== 0 || createHash("sha256").update(content.stdout).digest("hex") !== ref.sha256)
+            refuse("removed_memory_source_changed");
+        removedBytes += content.stdout.length;
+        if (removedBytes > 64 * 1024 * 1024)
+            refuse("removed_memory_bytes_exceed_bound");
+        deleting.push(ref.path);
+    }
+    if (source !== target) {
+        const targetHead = git(target, ["rev-parse", "HEAD"]), base = git(source, ["merge-base", targetHead, sourceHead]);
+        const changes = git(source, ["diff", "--name-only", "-z", base, sourceHead]).split("\0").filter(Boolean);
+        if (changes.some(logical => !paths.includes(logical)))
+            refuse("feature_contains_unowned_changes");
+        if (git(target, ["diff", "--cached", "--name-only"]) || git(target, ["diff", "--name-only", "--diff-filter=U"]))
+            refuse("integration_target_index_not_clean");
+    }
+    const needsCommit = deleting.length > 0 || references.some(ref => {
+        const bytes = spawnSync(selection.gitExecutable, ["-C", source, "cat-file", "blob", `HEAD:${ref.path}`], { env, timeout: 10000, maxBuffer: 16 * 1024 * 1024, shell: false, windowsHide: true });
+        const entry = git(source, ["ls-tree", "-z", "HEAD", "--", ref.path], false, true);
+        return bytes.status !== 0 || createHash("sha256").update(bytes.stdout).digest("hex") !== ref.sha256
+            || !entry.startsWith(`${ref.git_mode ?? "100644"} blob `);
+    });
+    const assertSourceBeforeMutation = () => {
+        observed.revalidate();
+        assertModes();
+        assertMemoryGitRemovalSources(source, removals);
+        if (git(source, ["rev-parse", "--verify", "HEAD"], false, true) !== sourceHead
+            || git(source, ["symbolic-ref", "--short", "HEAD"]) !== branch)
+            refuse("source_git_baseline_changed");
+    };
+    if (needsCommit) {
+        git(source, ["var", "GIT_AUTHOR_IDENT"]);
+        git(source, ["var", "GIT_COMMITTER_IDENT"]);
+        mutation("commit", sourceHead, () => {
+            assertSourceBeforeMutation();
+            const commitPaths = [...references.map(ref => ref.path), ...deleting];
+            git(source, ["add", "-f", "--", ...commitPaths], true);
+            git(source, ["commit", "--only", "-m", message, "--", ...commitPaths], true);
+        });
+        // Hooks or a concurrent writer may have changed history/index after the
+        // original admission. Never carry an unowned commit into the merge.
+        ownedHead = git(source, ["rev-parse", "HEAD"]);
+        const parentAndSubject = git(source, ["show", "-s", "--format=%P%n%s", ownedHead]);
+        const committedPaths = git(source, ["diff-tree", "--root", "--no-commit-id", "--no-renames", "--name-only", "-r", "-z", ownedHead]).split("\0").filter(Boolean);
+        if (parentAndSubject !== `${sourceHead}\n${message}`.trim() || committedPaths.some(logical => !paths.includes(logical)))
+            changedCommit();
+    }
+    else if (git(source, ["diff", "--cached", "--name-only", "-z", "--", ...paths])) {
+        // The reviewed tree can already equal HEAD while a selected pre-existing
+        // staged version differs. Settle only its admitted index effect; do not
+        // manufacture an empty commit or disturb unrelated staged entries.
+        const indexedRemovals = removals.length ? git(source, ["ls-files", "--cached", "-z", "--", ...removals.map(ref => ref.path)]).split("\0").filter(Boolean) : [];
+        mutation("commit", sourceHead, () => {
+            assertSourceBeforeMutation();
+            git(source, ["add", "-f", "--", ...references.map(ref => ref.path), ...indexedRemovals], true);
+        });
+        assertOwnedHead();
+    }
+    observed.revalidate();
+    assertOwnedHead();
+    if (source !== target) {
+        const head = ownedHead, targetHead = git(target, ["rev-parse", "HEAD"]);
+        if (head !== targetHead) {
+            mutation("merge", targetHead, () => {
+                assertOwnedHead();
+                if (git(target, ["rev-parse", "HEAD"]) !== targetHead
+                    || git(target, ["symbolic-ref", "--short", "HEAD"]) !== selection.integrationBranch
+                    || git(target, ["diff", "--cached", "--name-only"]))
+                    refuse("target_git_baseline_changed");
+                git(target, ["merge", "--no-edit", "--no-autostash", head], true);
+            });
+        }
+    }
+    const result = observe();
+    assertOwnedHead();
+    return result;
+}
+/** The admitted Memory finish operation. A retained intent never licenses a
+ * second dispatch: replay first observes completed Git effects, or reports unknown. */
+export function integrateMemoryFinish(context, input) {
+    if (!(input.bundle instanceof RetainedExecutionBundle) || !["mb-init", "mb-upgrade"].includes(input.bundle.descriptor.descriptor.id))
+        refuse("registered_memory_bundle_required");
+    if (context.db.isOwnedWriteTransaction?.())
+        refuse("preparation_outside_writer_required");
+    const stageScope = { ...input.scope, stage: "finish" };
+    readDescriptorStageInput(context, stageScope, input.bundle);
+    const review = PreparedMemoryFinishReview.prepare(context, input);
+    const selected = context.db.readSnapshot(() => readMemoryFinishGitSelection(context, input.scope, input.bundle));
+    const request = { requestId: selected.policy.scope.requestId, projectRoot: selected.selection.projectRoot,
+        workspaceRoot: selected.selection.workspaceRoot };
+    let upgrade = null;
+    let references;
+    if (selected.kind === "upgrade") {
+        upgrade = readMemoryUpgradeFinishInventory(context, input.scope, input.bundle, review);
+        references = upgrade.references;
+    }
+    else {
+        const bootstrap = readMemoryInitProjectBootstrap(context, request);
+        if (!bootstrap)
+            refuse("accepted_bootstrap_required");
+        const published = readPublishedMemoryReferenceInventory(context.ddFlowHome, { ...request, targetSha256: bootstrap.receipt.target_sha256,
+            layerSha256: bootstrap.receipt.layer_sha256, installationSha256: selected.readiness.authority.binding.installation_manifest_sha256,
+            packSha256: selected.readiness.authority.binding.pack_sha256 }, selected.readiness.authority.binding.target, bootstrap.receipt.layer_publication_sha256, bootstrap.receipt.draft_identity_sha256);
+        const files = new Map(reviewedMemoryGitFiles(review.reviewedSources(context)).map(ref => [ref.path, ref]));
+        for (const [logical, sha256] of published.artifacts) {
+            const ref = { root: "workspace", path: logical, sha256 };
+            if (files.has(ref.path)) {
+                if (published.canon.has(logical.slice(".memory-bank/".length)) && files.get(ref.path).sha256 !== ref.sha256)
+                    refuse("selected_canon_changed");
+            }
+            else
+                files.set(ref.path, ref);
+        }
+        references = [...files.values()].sort((a, b) => a.path.localeCompare(b.path, "en"));
+    }
+    const snapshot = upgrade ? observeMemoryUpgradeFinishInventory(selected.selection.workspaceRoot, upgrade) : null;
+    const removals = upgrade?.removals ?? [];
+    const identity = hybridDigest({ scope: input.scope, bundle: input.bundle.sha256, policy: selected.policy,
+        review: review.bytes().toString("base64"), references, ...(upgrade ? { upgrade } : {}) });
+    const events = context.db.all(`SELECT payload_json FROM audit_events WHERE project_id=?
+    AND event_type='memory.finish_integration_intent' AND json_extract(payload_json,'$.run_id')=?`, [input.scope.projectId, input.scope.runId]);
+    const intents = events.map(row => JSON.parse(row.payload_json));
+    if (intents.length > 2 || intents.some(value => value.identity !== identity))
+        refuse("integration_intent_changed");
+    assertGitExecutable(selected.selection, selected.gitSha256);
+    if (intents.length) {
+        try {
+            observeReviewedMemoryGitIntegration(selected.selection, context.env, references, removals);
+            const accepted = PreparedMemoryFinishIntegration.prepare(context, input);
+            return { integrated: true, replayed: true, integration: accepted.value() };
+        }
+        catch (error) {
+            const commit = intents.length === 1 && intents[0].phase === "commit" ? intents[0] : null;
+            const result = spawnSync(selected.selection.gitExecutable, ["-C", selected.selection.workspaceRoot, "log", "-1", "--format=%P%n%s"], { env: Object.fromEntries(Object.entries(context.env).filter(([key]) => !key.startsWith("GIT_"))), encoding: "utf8", timeout: 10000 });
+            // Only a physically completed original scoped commit can continue to the
+            // not-yet-issued merge. Never rerun a commit or unresolved merge intent.
+            if (!commit || result.status !== 0 || result.stdout.trim() !== `${commit.baseline}\nchore(${input.scope.runId.toLowerCase()}): integrate reviewed Memory Bank`.trim()
+                || selected.selection.workspaceRoot === selected.selection.projectRoot)
+                throw new AppError("memory_finish_integration_pending", "Original integration has not been physically proven; do not redispatch Git mutations", 1, { effect: "unknown", next_action: "reconcile_original_integration", cause: error instanceof AppError ? error.details.reason : "observation_failed" });
+        }
+    }
+    let dispatched = false;
+    try {
+        const integration = integrateReviewedMemoryFiles(selected.selection, context.env, references, input.scope.runId, (phase, baseline, action) => {
+            if (intents.some(value => value.phase === phase))
+                throw new AppError("memory_finish_integration_pending", "Original Git mutation remains unresolved", 1, { effect: "unknown", next_action: "reconcile_original_integration" });
+            review.revalidate(context);
+            assertGitExecutable(selected.selection, selected.gitSha256);
+            snapshot?.revalidate();
+            context.db.writeTransaction(() => {
+                readDescriptorStageInput(context, stageScope, input.bundle);
+                review.assertCustody(context);
+                if (hybridDigest(readMemoryFinishGitSelection(context, input.scope, input.bundle)) !== hybridDigest(selected))
+                    refuse("integration_custody_changed");
+                if (upgrade && hybridDigest(readMemoryUpgradeFinishInventory(context, input.scope, input.bundle, review)) !== hybridDigest(upgrade))
+                    refuse("upgrade_inventory_custody_changed");
+                const current = context.db.all(`SELECT payload_json FROM audit_events WHERE project_id=?
+        AND event_type='memory.finish_integration_intent' AND json_extract(payload_json,'$.run_id')=?`, [input.scope.projectId, input.scope.runId])
+                    .map(row => JSON.parse(row.payload_json));
+                if (current.some(value => value.identity !== identity || value.phase === phase) || current.length > 1)
+                    throw new AppError("memory_finish_integration_pending", "The original Git mutation already has an owner; observe its effect without redispatch", 1, { effect: "unknown", next_action: "reconcile_original_integration" });
+                appendAudit(context, { projectId: input.scope.projectId, eventType: "memory.finish_integration_intent",
+                    payload: { run_id: input.scope.runId, identity, phase, baseline } });
+            }, "memoryFinish.integrate");
+            dispatched = true;
+            action();
+        }, selected.policy, removals);
+        snapshot?.revalidate();
+        if (upgrade)
+            observeMemoryUpgradeFinishInventory(selected.selection.projectRoot, upgrade);
+        return { integrated: true, replayed: false, integration: { ...integration, ...(upgrade ? { upgrade_inventory_sha256: hybridDigest(upgrade) } : {}) } };
+    }
+    catch (error) {
+        if (!dispatched)
+            throw error;
+        throw new AppError("memory_finish_integration_pending", "The retained original Git operation requires physical reconciliation; do not redispatch", 1, { effect: "unknown", next_action: "reconcile_original_integration", cause: error instanceof AppError ? error.details.reason : "git_operation_failed" });
+    }
+}
+/** Fresh terminal integration proof: independent accepted review + explicit
+ * retained policy/bootstrap + exact committed reviewed MB bytes. Read-only:
+ * no Git integration is performed and no normal-flow readiness, Stage/RUN
+ * completion, permission or historical replay authority is granted here. */
+export class PreparedMemoryFinishIntegration {
+    static isPrepared(value) {
+        return typeof value === "object" && value !== null && #review in value;
+    }
+    #scope;
+    #bundle;
+    #review;
+    #retainedSha256;
+    #selection;
+    #observation;
+    #gitSha256;
+    #upgradeSha256;
+    constructor(key, scope, bundle, review, selected, observation, upgradeSha256 = null) {
+        if (key !== token)
+            refuse("finish_integration_token_required");
+        this.#scope = { ...scope };
+        this.#bundle = bundle;
+        this.#review = review;
+        this.#retainedSha256 = hybridDigest(selected);
+        this.#selection = structuredClone(selected.selection);
+        this.#observation = structuredClone(observation);
+        this.#gitSha256 = selected.gitSha256;
+        this.#upgradeSha256 = upgradeSha256;
+        Object.freeze(this);
+    }
+    static prepare(context, input) {
+        if (!(input.bundle instanceof RetainedExecutionBundle) || !["mb-init", "mb-upgrade"].includes(input.bundle.descriptor.descriptor.id))
+            refuse("registered_memory_bundle_required");
+        if (context.db.isOwnedWriteTransaction?.())
+            refuse("preparation_outside_writer_required");
+        const review = PreparedMemoryFinishReview.prepare(context, input);
+        const selected = context.db.readSnapshot(() => readMemoryFinishGitSelection(context, input.scope, input.bundle));
+        const upgrade = selected.kind === "upgrade" ? readMemoryUpgradeFinishInventory(context, input.scope, input.bundle, review) : null;
+        const references = upgrade?.references ?? reviewedMemoryGitFiles(review.reviewedSources(context));
+        assertGitExecutable(selected.selection, selected.gitSha256);
+        if (upgrade)
+            for (const root of new Set([selected.selection.projectRoot, selected.selection.workspaceRoot]))
+                observeMemoryUpgradeFinishInventory(root, upgrade);
+        const observation = { ...observeReviewedMemoryGitIntegration(selected.selection, context.env, references, upgrade?.removals),
+            ...(upgrade ? { upgrade_inventory_sha256: hybridDigest(upgrade) } : {}) };
+        assertGitExecutable(selected.selection, selected.gitSha256);
+        if (observation.repository !== selected.policy.repository || observation.workspace_branch !== selected.policy.workspace_branch)
+            refuse("policy_repository_or_branch_changed");
+        const prepared = new PreparedMemoryFinishIntegration(token, input.scope, input.bundle, review, selected, observation, upgrade ? hybridDigest(upgrade) : null);
+        prepared.revalidate(context);
+        return prepared;
+    }
+    value() { return structuredClone(this.#observation); }
+    /** SQL-only writer fence; physical observation must precede the writer. */
+    assertCustody(context) {
+        this.#review.assertCustody(context);
+        if (hybridDigest(readMemoryFinishGitSelection(context, this.#scope, this.#bundle)) !== this.#retainedSha256)
+            refuse("finish_integration_custody_changed");
+        if (this.#upgradeSha256 !== null && hybridDigest(readMemoryUpgradeFinishInventory(context, this.#scope, this.#bundle, this.#review)) !== this.#upgradeSha256)
+            refuse("upgrade_inventory_custody_changed");
+    }
+    revalidate(context) {
+        const review = this.#review;
+        if (context.db.isOwnedWriteTransaction?.())
+            refuse("physical_revalidation_outside_writer_required");
+        review.revalidate(context);
+        this.assertCustody(context);
+        const upgrade = this.#upgradeSha256 === null ? null : readMemoryUpgradeFinishInventory(context, this.#scope, this.#bundle, this.#review);
+        const references = upgrade?.references ?? reviewedMemoryGitFiles(this.#review.reviewedSources(context));
+        assertGitExecutable(this.#selection, this.#gitSha256);
+        if (upgrade)
+            for (const root of new Set([this.#selection.projectRoot, this.#selection.workspaceRoot]))
+                observeMemoryUpgradeFinishInventory(root, upgrade);
+        const observed = { ...observeReviewedMemoryGitIntegration(this.#selection, context.env, references, upgrade?.removals),
+            ...(upgrade ? { upgrade_inventory_sha256: hybridDigest(upgrade) } : {}) };
+        if (hybridDigest(observed) !== hybridDigest(this.#observation))
+            refuse("finish_integration_observation_changed");
+        assertGitExecutable(this.#selection, this.#gitSha256);
+        this.assertCustody(context);
+    }
+}