@deksden-com/dd-flow-cli 0.9.0-beta.144 → 0.9.0-beta.145

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

@@ -5,7 +5,7 @@ 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 { observeReviewedMemoryGitIntegration, reviewedMemoryGitFiles } from "./memory-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";
@@ -17,14 +17,34 @@ 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" });
 }
-function retained(context, scope, bundle) {
+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
@@ -36,18 +56,103 @@ function retained(context, scope, bundle) {
     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 { readiness, policy, selection, gitSha256 };
+    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) {
-    const env = Object.fromEntries(Object.entries(environment).filter(([key]) => !key.startsWith("GIT_")));
+export function integrateReviewedMemoryFiles(selection, environment, references, runId, mutation, policy, removals = []) {
+    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", "-C", directory, ...args], { env, encoding: "utf8", timeout: 30000, maxBuffer: 16 * 1024 * 1024, shell: false, windowsHide: true });
+        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)
@@ -55,13 +160,26 @@ export function integrateReviewedMemoryFiles(selection, environment, references,
                 next_action: write ? "reconcile_original_integration" : "resolve_git_configuration_or_workspace" });
         return result.stdout.trim();
     };
-    const paths = references.map(ref => ref.path);
-    if (!paths.length || paths.length > 4096 || !paths.includes(".memory-bank/index.md") || new Set(paths).size !== paths.length
-        || references.some(ref => ref.root !== "workspace" || !(ref.path.startsWith(".memory-bank/") || ref.path === ".mb-lint.json")
-            || ref.path.split("/").some(part => !part || part === "." || part === "..") || /[\\\0]/.test(ref.path)
-            || !/^[a-f0-9]{64}$/.test(ref.sha256)))
+    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");
+    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)
@@ -77,7 +195,7 @@ export function integrateReviewedMemoryFiles(selection, environment, references,
         if (hashes.get(memorySourceKey(ref.root, ref.path)) !== ref.sha256)
             refuse("reviewed_workspace_bytes_changed");
     try {
-        return observeReviewedMemoryGitIntegration(selection, environment, references);
+        return observeReviewedMemoryGitIntegration(selection, environment, references, removals);
     }
     catch (error) {
         if (!(error instanceof AppError) || error.code !== "memory_git_integration_invalid")
@@ -89,6 +207,22 @@ export function integrateReviewedMemoryFiles(selection, environment, references,
     if (git(source, ["diff", "--name-only", "--diff-filter=U"]))
         refuse("unmerged_workspace");
     const sourceHead = git(source, ["rev-parse", "--verify", "HEAD"], false, true);
+    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);
@@ -97,20 +231,25 @@ export function integrateReviewedMemoryFiles(selection, environment, references,
         if (git(target, ["diff", "--cached", "--name-only"]) || git(target, ["diff", "--name-only", "--diff-filter=U"]))
             refuse("integration_target_index_not_clean");
     }
-    const needsCommit = references.some(ref => {
+    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 });
-        return bytes.status !== 0 || createHash("sha256").update(bytes.stdout).digest("hex") !== ref.sha256;
+        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 `);
     });
     if (needsCommit) {
         git(source, ["var", "GIT_AUTHOR_IDENT"]);
         git(source, ["var", "GIT_COMMITTER_IDENT"]);
         mutation("commit", sourceHead, () => {
             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");
-            git(source, ["add", "-f", "--", ...paths], true);
-            git(source, ["commit", "--only", "-m", `chore(${runId.toLowerCase()}): integrate reviewed Memory Bank`, "--", ...paths], true);
+            const commitPaths = [...references.map(ref => ref.path), ...deleting];
+            git(source, ["add", "-f", "--", ...commitPaths], true);
+            git(source, ["commit", "--only", "-m", `chore(${runId.toLowerCase()}): integrate reviewed Memory Bank`, "--", ...commitPaths], true);
         });
     }
     observed.revalidate();
@@ -126,40 +265,50 @@ export function integrateReviewedMemoryFiles(selection, environment, references,
             });
         }
     }
-    return observeReviewedMemoryGitIntegration(selection, environment, references);
+    return observeReviewedMemoryGitIntegration(selection, environment, references, removals);
 }
 /** 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) || input.bundle.descriptor.descriptor.id !== "mb-init")
+    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(() => retained(context, input.scope, input.bundle));
+    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 };
-    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");
+    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);
         }
-        else
-            files.set(ref.path, ref);
+        references = [...files.values()].sort((a, b) => a.path.localeCompare(b.path, "en"));
     }
-    const 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 });
+        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));
@@ -168,7 +317,7 @@ export function integrateMemoryFinish(context, input) {
     assertGitExecutable(selected.selection, selected.gitSha256);
     if (intents.length) {
         try {
-            observeReviewedMemoryGitIntegration(selected.selection, context.env, references);
+            observeReviewedMemoryGitIntegration(selected.selection, context.env, references, removals);
             const accepted = PreparedMemoryFinishIntegration.prepare(context, input);
             return { integrated: true, replayed: true, integration: accepted.value() };
         }
@@ -189,11 +338,14 @@ export function integrateMemoryFinish(context, input) {
                 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(retained(context, input.scope, input.bundle)) !== hybridDigest(selected))
+                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));
@@ -204,8 +356,11 @@ export function integrateMemoryFinish(context, input) {
             }, "memoryFinish.integrate");
             dispatched = true;
             action();
-        }, selected.policy);
-        return { integrated: true, replayed: false, integration };
+        }, 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)
@@ -228,7 +383,8 @@ export class PreparedMemoryFinishIntegration {
     #selection;
     #observation;
     #gitSha256;
-    constructor(key, scope, bundle, review, selected, observation) {
+    #upgradeSha256;
+    constructor(key, scope, bundle, review, selected, observation, upgradeSha256 = null) {
         if (key !== token)
             refuse("finish_integration_token_required");
         this.#scope = { ...scope };
@@ -238,22 +394,28 @@ export class PreparedMemoryFinishIntegration {
         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) || input.bundle.descriptor.descriptor.id !== "mb-init")
+        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(() => retained(context, input.scope, input.bundle));
-        const references = reviewedMemoryGitFiles(review.reviewedSources(context));
+        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);
-        const observation = observeReviewedMemoryGitIntegration(selected.selection, context.env, references);
+        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);
+        const prepared = new PreparedMemoryFinishIntegration(token, input.scope, input.bundle, review, selected, observation, upgrade ? hybridDigest(upgrade) : null);
         prepared.revalidate(context);
         return prepared;
     }
@@ -261,8 +423,10 @@ export class PreparedMemoryFinishIntegration {
     /** SQL-only writer fence; physical observation must precede the writer. */
     assertCustody(context) {
         this.#review.assertCustody(context);
-        if (hybridDigest(retained(context, this.#scope, this.#bundle)) !== this.#retainedSha256)
+        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;
@@ -270,9 +434,15 @@ export class PreparedMemoryFinishIntegration {
             refuse("physical_revalidation_outside_writer_required");
         review.revalidate(context);
         this.assertCustody(context);
-        const references = reviewedMemoryGitFiles(this.#review.reviewedSources(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 (hybridDigest(observeReviewedMemoryGitIntegration(this.#selection, context.env, references)) !== hybridDigest(this.#observation))
+        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);

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

@@ -2,7 +2,7 @@ var _a;
 import { createHash } from "node:crypto";
 import { AppError } from "../shared/errors.js";
 import { RetainedExecutionBundle } from "./execution-bundles.js";
-import { PreparedMemoryFinishIntegration } from "./memory-finish-integration.js";
+import { PreparedMemoryFinishIntegration, readMemoryUpgradeFinishInventory, observeMemoryUpgradeFinishInventory } from "./memory-finish-integration.js";
 import { PreparedMemoryFinishReview } from "./memory-finish-handler.js";
 import { observeMemoryNormalFlowEntry } from "./memory-normal-flow-entry.js";
 import { readMemoryInitBootstrapReadiness } from "./memory-init-bootstrap-readiness.js";
@@ -12,6 +12,9 @@ import { ObservedMemorySources } from "./memory-source-observations.js";
 import { readBoundedReleaseFile } from "./release-source.js";
 import { memorySourceKey } from "./memory-stage-results.js";
 import { hybridDigest } from "./hybrid-contracts.js";
+import { readMemoryUpgradeBootstrapReadiness } from "./memory-upgrade-bootstrap-readiness.js";
+import { readUpgradeStorageReadiness } from "./memory-upgrade-storage-readiness.js";
+import { getProjectVersionStatus } from "./version-status.js";
 const token = Symbol("memory-finish-readiness");
 function refuse(reason) {
     throw new AppError("memory_finish_readiness_invalid", "Finish lacks reviewed ordinary-flow readiness", 2, { reason, effect: "no_effect" });
@@ -19,13 +22,32 @@ function refuse(reason) {
 function accepted(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 bootstrap = readMemoryUpgradeBootstrapReadiness(context, request), storage = readUpgradeStorageReadiness(context, request);
+        if (!bootstrap?.hasGitPolicy || !bootstrap.hasLintCapability || !storage?.selection || bootstrap.projectId !== scope.projectId
+            || bootstrap.authority.binding.execution_sha256 !== bundle.execution.sha256
+            || bootstrap.authority.binding.storage_sha256 !== storage.sha256)
+            refuse("accepted_bootstrap_required");
+        return { kind: "upgrade", request, bootstrap, storage };
+    }
     const bootstrap = readMemoryInitBootstrapReadiness(context, request), registration = readMemoryInitProjectBootstrap(context, request);
     if (!bootstrap || !registration || bootstrap.projectId !== scope.projectId
         || bootstrap.authority.binding.execution_sha256 !== bundle.execution.sha256)
         refuse("accepted_bootstrap_required");
-    return { request, bootstrap, registration };
+    return { kind: "init", request, bootstrap, registration };
 }
 function tools(selected) {
+    if (selected.kind === "upgrade") {
+        const git = selected.storage.selection.payload.git, lint = selected.bootstrap.authority.binding.lint;
+        if (!git || !lint)
+            refuse("selected_tool_changed");
+        for (const tool of [git, lint]) {
+            const expected = "probe" in tool ? tool.probe.executable_sha256 : tool.executable_sha256;
+            if (createHash("sha256").update(readBoundedReleaseFile(tool.executable, 64 * 1024 * 1024)).digest("hex") !== expected)
+                refuse("selected_tool_changed");
+        }
+        return;
+    }
     const target = selected.bootstrap.authority.binding.target;
     for (const name of ["git", "wt", "mb-lint"]) {
         const expected = target.tool_probes?.[name].executable_sha256;
@@ -61,25 +83,49 @@ export class PreparedMemoryFinishReadiness {
     static observe(context, scope, bundle, review, integration) {
         const selected = context.db.readSnapshot(() => accepted(context, scope, bundle));
         tools(selected);
-        const layer = readRetainedMemoryLayer(context.ddFlowHome, { ...selected.request,
-            targetSha256: selected.registration.receipt.target_sha256, layerSha256: selected.registration.receipt.layer_sha256,
-            installationSha256: selected.bootstrap.authority.binding.installation_manifest_sha256 });
-        if (layer.packSha256 !== selected.bootstrap.authority.binding.pack_sha256)
-            refuse("selected_pack_changed");
-        const files = layer.files();
-        for (const root of new Set([selected.request.projectRoot, selected.request.workspaceRoot])) {
-            const observed = ObservedMemorySources.capture({ project: root }, [...files.keys()].map(logical => ({ root: "project", path: `.memory-bank/${logical}` })));
-            const hashes = observed.hashes();
-            for (const [logical, bytes] of files)
-                if (hashes.get(memorySourceKey("project", `.memory-bank/${logical}`)) !== createHash("sha256").update(bytes).digest("hex"))
-                    refuse("installed_pack_bytes_changed");
-            observed.revalidate();
+        const files = new Map();
+        let packSha256;
+        let upgrade = null;
+        if (selected.kind === "upgrade") {
+            upgrade = readMemoryUpgradeFinishInventory(context, scope, bundle, review);
+            if (integration.value().upgrade_inventory_sha256 !== hybridDigest(upgrade))
+                refuse("upgrade_integration_inventory_changed");
+            for (const item of upgrade.entries)
+                if (item.kind === "file")
+                    files.set(item.path.slice(".memory-bank/".length), item.sha256);
+            for (const root of new Set([selected.request.projectRoot, selected.request.workspaceRoot])) {
+                observeMemoryUpgradeFinishInventory(root, upgrade);
+                const version = getProjectVersionStatus({ projectRoot: root, rootSource: "explicit", canon: null });
+                const release = selected.storage.selection.release;
+                if (!version || version.memory_bank.version !== release.canon.version || version.flow_pack.canon_version_at_source_commit !== release.canon.version
+                    || version.flow_pack.source_commit !== release.canon.commit)
+                    refuse("upgrade_versions_inconsistent");
+            }
+            packSha256 = selected.bootstrap.authority.receipt.upgrade_target.pack_sha256;
+        }
+        else {
+            const layer = readRetainedMemoryLayer(context.ddFlowHome, { ...selected.request,
+                targetSha256: selected.registration.receipt.target_sha256, layerSha256: selected.registration.receipt.layer_sha256,
+                installationSha256: selected.bootstrap.authority.binding.installation_manifest_sha256 });
+            if (layer.packSha256 !== selected.bootstrap.authority.binding.pack_sha256)
+                refuse("selected_pack_changed");
+            for (const [logical, bytes] of layer.files())
+                files.set(logical, createHash("sha256").update(bytes).digest("hex"));
+            for (const root of new Set([selected.request.projectRoot, selected.request.workspaceRoot])) {
+                const observed = ObservedMemorySources.capture({ project: root }, [...files.keys()].map(logical => ({ root: "project", path: `.memory-bank/${logical}` })));
+                const hashes = observed.hashes();
+                for (const [logical, sha256] of files)
+                    if (hashes.get(memorySourceKey("project", `.memory-bank/${logical}`)) !== sha256)
+                        refuse("installed_pack_bytes_changed");
+                observed.revalidate();
+            }
+            packSha256 = layer.packSha256;
         }
         const entry = observeMemoryNormalFlowEntry(context, selected.request.projectRoot);
         const reviewed = new Map(review.reviewedSources(context).filter(ref => ref.root === "workspace").map(ref => [ref.path, ref.sha256]));
         for (const source of entry.sources) {
             const canonical = files.get(source.path.slice(".memory-bank/".length));
-            if (canonical ? createHash("sha256").update(canonical).digest("hex") !== source.sha256 : reviewed.get(source.path) !== source.sha256)
+            if (canonical ? canonical !== source.sha256 : reviewed.get(source.path) !== source.sha256)
                 refuse("entry_source_not_reviewed_or_selected_canon");
         }
         tools(selected);
@@ -87,11 +133,12 @@ export class PreparedMemoryFinishReadiness {
         review.assertCustody(context);
         return { schema_id: "dd-flow/memory-finish-readiness-observation@1", scope: { ...scope },
             bundle_sha256: bundle.sha256, execution_sha256: bundle.execution.sha256,
-            bootstrap_authority_sha256: hybridDigest(selected.bootstrap.authority), pack_sha256: layer.packSha256,
-            integration: integration.value(), entry, readiness: "entry_prepared", model_access: "unknown" };
+            bootstrap_authority_sha256: hybridDigest(selected.bootstrap.authority), pack_sha256: packSha256,
+            integration: integration.value(), entry, readiness: "entry_prepared", model_access: "unknown",
+            ...(upgrade ? { migration_record: upgrade.migrationRecord } : {}) };
     }
     static prepare(context, input) {
-        if (!(input.bundle instanceof RetainedExecutionBundle) || input.bundle.descriptor.descriptor.id !== "mb-init")
+        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");