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

package/dist/services/memory-repair-work-completion.js

@@ -1,6 +1,6 @@
 import { AppError } from "../shared/errors.js";
 import { PreparedPublishedMemoryRepairWorkResult } from "./memory-repair-work-custody.js";
-import { prepareMemoryRepairPrivateOutputFromStage, prepareMemoryRepairPublicationSourceFromStage, registerMemoryRepairPublicationSourceFromStage, reserveMemoryRepairPublicationAgainstSourceFromStage, reserveMemorySecondRepairPublicationFromStage, restoreMemoryRepairPublicationFromStage, prepareMemorySecondRepairPublicationFromStage, restoreStartedMemorySecondRepairLaunchFromStage } from "./memory-review-handler.js";
+import { prepareMemoryRepairPrivateOutputFromStage, prepareMemoryRepairPublicationSourceFromStage, restoreMemoryRepairPublicationSourceFromStage, reserveMemoryRepairPublicationAgainstSourceFromStage, reserveMemorySecondRepairPublicationFromStage, restoreMemoryRepairPublicationFromStage, prepareMemorySecondRepairPublicationFromStage, restoreStartedMemorySecondRepairLaunchFromStage } from "./memory-review-handler.js";
 function refuse(reason) {
     throw new AppError("memory_work_result_preparation_required", "Repair completion requires registered private output and physical start custody", 1, { reason, effect: "no_effect" });
 }
@@ -47,47 +47,67 @@ export function prepareMemoryRepairWorkCompletion(context, work, result) {
         const publication = restore();
         if (!publication.bytes().equals(bytes))
             refuse("retained_result_changed");
-        return { scope, bytes, wave, publication };
+        return { scope, bytes, wave, publication, source: null };
     }
     const outcome = wave === 1 ? prepareMemoryRepairPrivateOutputFromStage(context, { ...scope, bytes }).result().outcome
         : restoreStartedMemorySecondRepairLaunchFromStage(context, scope).observeOutput(context, bytes).result.outcome;
-    if (outcome !== "accepted")
+    if (outcome !== "accepted" && outcome !== "reconciled")
         refuse("accepted_private_output_required_use_managed_fail_for_blocker");
-    if (wave === 1)
-        prepareMemoryRepairPublicationSourceFromStage(context, scope);
-    return { scope, bytes, wave, publication: null };
+    let source = null;
+    if (wave === 1) {
+        try {
+            source = restoreMemoryRepairPublicationSourceFromStage(context, scope);
+        }
+        catch (error) {
+            if (!(error instanceof AppError) || error.code !== "memory_repair_publication_source_invalid" || error.details.reason !== "registered_source_required")
+                throw error;
+            source = prepareMemoryRepairPublicationSourceFromStage(context, scope);
+        }
+    }
+    return { scope, bytes, wave, publication: null, source };
 }
 /** Called by managed Work finish after its normal Hook/actor admission.
- * Preparation is repeated before effects; no caller-supplied object grants
+ * Sealed owners revalidate before effects; no caller-supplied object grants
  * authority. Every action is terminal and advances the retained finite cursor. */
-export function publishMemoryRepairWorkCompletion(context, work, result) {
+export function publishMemoryRepairWorkCompletion(context, work, result, progress) {
+    progress?.(`Memory repair ${work.work_id}: preparing publication`);
     const prepared = prepareMemoryRepairWorkCompletion(context, work, result);
     const { scope, bytes, wave } = prepared;
+    progress?.(`Memory repair ${work.work_id}: publication input verified`);
     try {
         if (!prepared.publication) {
             if (wave === 1) {
-                registerMemoryRepairPublicationSourceFromStage(context, scope);
+                // Registration revalidates this invocation's source before and after
+                // its SQL effect; do not rebuild the entire same history graph again.
+                prepared.source.register(context);
+                progress?.(`Memory repair ${work.work_id}: publication source registered`);
                 reserveMemoryRepairPublicationAgainstSourceFromStage(context, { ...scope, bytes });
             }
             else
                 reserveMemorySecondRepairPublicationFromStage(context, { ...scope, bytes });
+            progress?.(`Memory repair ${work.work_id}: publication reserved`);
         }
         const publication = prepared.publication ?? (wave === 1 ? restoreMemoryRepairPublicationFromStage(context, scope) : prepareMemorySecondRepairPublicationFromStage(context, scope));
+        progress?.(`Memory repair ${work.work_id}: publication restored`);
         const initial = publication.revalidate(context);
         let completed = initial.completed;
+        progress?.(`Memory repair ${work.work_id}: publication ready (${completed}/${initial.total})`);
         // The actual retained plan, not agent output or a guessed retry count,
         // bounds execution. Even an already applied plan reconciles completion.
         do {
             const step = publication.applyNextAction(context);
             if (step.total !== initial.total || step.completed < completed || step.completed > initial.total)
                 refuse("publication_cursor_changed");
+            if (step.status !== "applied" && step.completed !== completed + 1)
+                refuse("publication_did_not_advance");
+            progress?.(`Memory repair ${work.work_id}: publication advanced (${step.completed}/${step.total})`);
             if (step.status === "applied")
                 break;
-            if (step.completed !== completed + 1)
-                refuse("publication_did_not_advance");
             completed = step.completed;
         } while (completed < initial.total);
-        return PreparedPublishedMemoryRepairWorkResult.prepare(context, publication);
+        const published = PreparedPublishedMemoryRepairWorkResult.prepare(context, publication);
+        progress?.(`Memory repair ${work.work_id}: published result verified`);
+        return published;
     }
     catch (error) {
         throw new AppError("memory_repair_completion_pending", "Repair publication requires exact-request reconciliation before another completion attempt", 1, { effect: error instanceof AppError && error.details.effect === "unknown" ? "unknown" : "partial",

package/dist/services/memory-repair-work-results.js

@@ -4,6 +4,16 @@ import { AppError } from "../shared/errors.js";
 import { AdmittedFrozenEngine } from "./frozen-engine.js";
 import { memoryRepairWorkerSchema } from "./memory-repair-registration.js";
 import { memorySourceKey } from "./memory-stage-results.js";
+import { parseMemoryWorkResultProposal } from "./memory-work-result-json.js";
+/** Claim shape only, never settlement or finding closure. Reconciliation
+ * preserves documents and requires current grounded evidence plus the same
+ * fresh check and independent re-review owners as a physical repair. */
+export function isCompletedMemoryRepairClaim(value) {
+    return Array.isArray(value?.changes) && (value.outcome === "accepted" && value.changes.length > 0
+        || value.outcome === "reconciled" && value.changes.length === 0 && Array.isArray(value.resolutions) && value.resolutions.length > 0
+            && value.resolutions.every(resolution => Array.isArray(resolution?.delta_paths) && resolution.delta_paths.length === 0
+                && Array.isArray(resolution.evidence) && resolution.evidence.some(ref => ref?.root === "workspace")));
+}
 function refuse(reason) {
     throw new AppError("memory_repair_work_result_invalid", "Repair result differs from registered findings and bounded write paths", 2, { reason, effect: "no_effect" });
 }
@@ -24,7 +34,7 @@ export function validateMemoryRepairWorkResult(bytes, engine, binding) {
             || !binding.workId || binding.packet?.result_schema !== memoryRepairWorkerSchema)
             refuse("invalid_preparation_binding");
         const schema = JSON.parse(new TextDecoder("utf-8", { fatal: true }).decode(engine.schema("memory-repair-work-result")));
-        const value = JSON.parse(new TextDecoder("utf-8", { fatal: true }).decode(bytes));
+        const value = parseMemoryWorkResultProposal(bytes, "memory_repair_work_result_invalid");
         if (schema.$id !== memoryRepairWorkerSchema)
             refuse("invalid_result_schema");
         const packet = binding.packet;
@@ -67,6 +77,15 @@ export function validateMemoryRepairWorkResult(bytes, engine, binding) {
                 if (sources.get(key) !== ref.sha256)
                     refuse("foreign_or_stale_resolution_evidence");
             }
+            if (value.outcome === "reconciled") {
+                if (value.changes.length || resolution.delta_paths.length)
+                    refuse("reconciliation_has_document_delta");
+                if (!resolution.evidence.some(ref => ref.root === "workspace"))
+                    refuse("reconciliation_without_current_evidence");
+                continue;
+            }
+            if (!resolution.delta_paths.length)
+                refuse("resolution_without_actual_delta");
             const causal = value.changes.filter(change => resolution.delta_paths.includes(change.path));
             if (causal.some(change => change.after_sha256 !== null)) {
                 if (!resolution.evidence.some(ref => ref.root === "workspace" && causal.some(change => change.path === ref.path && change.after_sha256 !== null && change.after_sha256 === ref.sha256)))
@@ -75,7 +94,7 @@ export function validateMemoryRepairWorkResult(bytes, engine, binding) {
             else if (!resolution.evidence.some(ref => ref.root === "run"))
                 refuse("deletion_without_retained_evidence");
         }
-        if (value.outcome === "accepted" && (!value.changes.length || ids.size !== packet.findings.length))
+        if (value.outcome !== "blocked" && (!isCompletedMemoryRepairClaim(value) || ids.size !== packet.findings.length))
             refuse("incomplete_repair_claim");
         if (value.outcome === "blocked" && (value.changes.length || value.resolutions.length))
             refuse("blocked_repair_has_productive_claims");

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

@@ -72,16 +72,25 @@ export class PreparedMemoryRepairWorkspace {
         const exportedFiles = new Set(exported.entries().filter(entry => entry.kind === "file").map(entry => entry.path));
         const selected = candidates.filter(logical => allowed(path.join(source, logical))
             && logical.split("/").every(part => ![".git", "node_modules", ".dd-flow"].includes(part.normalize("NFC").toLowerCase()))).filter(logical => {
+            const stat = fs.lstatSync(path.join(source, logical), { throwIfNoEntry: false });
+            // The sanitized writer copy contains regular inputs only. This applies
+            // to project command links too; never follow or materialize their targets.
+            if (stat?.isSymbolicLink())
+                return false;
             if (!logical.startsWith(".memory-bank/") || exportedFiles.has(logical))
                 return true;
             // Git's cached inventory includes tracked deletions. A retained export
             // can explain an absent MB file, never a present unselected object.
-            if (fs.lstatSync(path.join(source, logical), { throwIfNoEntry: false }))
+            if (stat)
                 refuse("exported_source_changed");
             return false;
         });
         const observed = ObservedMemorySources.capture({ workspace: source }, selected.map(logical => ({ root: "workspace", path: logical })));
-        const hashes = observed.hashes(), entries = new Map(exported.entries().map(entry => [entry.path, entry]));
+        const hashes = observed.hashes(), entries = new Map(exported.entries().map(entry => {
+            if (entry.kind === "link")
+                refuse("linked_exported_source");
+            return [entry.path, { ...entry, kind: entry.kind }];
+        }));
         for (const logical of selected) {
             const file = path.join(source, logical), stat = fs.lstatSync(file);
             const entry = { path: logical, kind: "file", mode: stat.mode & 0o7777, sha256: hashes.get(memorySourceKey("workspace", logical)) };

package/dist/services/memory-repair-writer-copy.js

@@ -9,6 +9,7 @@ import { PreparedSecondMemoryRepairBaseline } from "./memory-second-repair-basel
 import { PreparedMemoryRepairWorkspace } from "./memory-repair-workspace.js";
 import { runtimeHarness } from "./execution-policy.js";
 import { hookSessionIdentity } from "./hooks.js";
+import { isCompletedMemoryRepairClaim } from "./memory-repair-work-results.js";
 import { RetainedMemoryRepairPublicationPlan } from "./memory-repair-publication-plan.js";
 import { PreparedMemoryRepairPublicationSource } from "./memory-repair-publication-source.js";
 import { retainedMemoryRepairPublicationPlans } from "./memory-repair-publication-intent.js";
@@ -668,7 +669,7 @@ export class PreparedMemoryRepairPrivateOutput {
      * Reservation alone grants no permission to apply files or settle Work.
      */
     reservePublication(context) {
-        if (this.#result.outcome !== "accepted")
+        if (!isCompletedMemoryRepairClaim(this.#result))
             refuse("accepted_private_output_required");
         this.revalidate(context);
         const start = this.#copy.startedReceipt(), actions = this.#transition.actions();

package/dist/services/memory-result-binding.js

@@ -1,4 +1,5 @@
 import { Ajv2020 } from "ajv/dist/2020.js";
+import { readMemoryUpgradeEvidence } from "./memory-upgrade-evidence.js";
 import { AppError } from "../shared/errors.js";
 import { ResolvedFlowDescriptor } from "./flow-descriptors.js";
 import { FrozenGenericExecution } from "./generic-execution.js";
@@ -14,6 +15,9 @@ import { stageLifecycleMatchKey } from "./hooks.js";
 import { captureRegisteredMemoryCompositionSources } from "./memory-preflight-handler.js";
 import { memoryCompositionRegistrationDigest } from "./memory-composition-registration.js";
 import { PreparedCheckEvidence } from "./code-checks.js";
+import { readMemoryUpgradeBootstrapReadiness } from "./memory-upgrade-bootstrap-readiness.js";
+import { readUpgradeStorageReadiness } from "./memory-upgrade-storage-readiness.js";
+import { upgradeAuthoringPaths } from "./memory-upgrade-inventory.js";
 function refuse() { throw new AppError("memory_result_binding_custody_invalid", "Memory result binding lacks independently accepted stage custody", 1, { effect: "no_effect" }); }
 /** Select identity, predecessor and unit coverage from SQL, not result fields. */
 function select(context, input) {
@@ -26,15 +30,17 @@ function select(context, input) {
     const run = context.db.get("SELECT index_json, project_root, workspace_root FROM runs WHERE project_id = ? AND id = ?", [input.projectId, input.runId]);
     if (!run)
         refuse();
-    const index = JSON.parse(run.index_json), frozen = input.execution.snapshot();
+    const index = JSON.parse(run.index_json), frozen = input.execution.snapshot(), flowId = input.flow.descriptor.id;
+    const upgrade = flowId === "mb-upgrade";
+    const schemaId = (stage) => upgrade ? "dd-flow/mb-upgrade-stage-result@1" : `dd-flow/mb-init-${stage}-result@1`;
     if (assertRunBundleSqlAuthority(context, input, index.execution_bundle)) {
         if (!input.bundle || input.bundle.execution.sha256 !== input.execution.sha256 || input.bundle.descriptor.sha256 !== input.flow.sha256)
             refuse();
         assertPreparedRunBundleSqlAuthority(context, input, input.bundle);
     }
     const stage = index.stage_runs?.find((item) => item.stage === input.stage);
-    if (input.flow.descriptor.id !== "mb-init" || frozen.settings.flow_id !== "mb-init" || frozen.settings.descriptor_sha256 !== input.flow.sha256
-        || index.execution_bundle && (index.execution_bundle.flow_id !== "mb-init" || index.execution_bundle.descriptor_sha256 !== input.flow.sha256)
+    if (!["mb-init", "mb-upgrade"].includes(flowId) || frozen.settings.flow_id !== flowId || frozen.settings.descriptor_sha256 !== input.flow.sha256
+        || index.execution_bundle && (index.execution_bundle.flow_id !== flowId || index.execution_bundle.descriptor_sha256 !== input.flow.sha256)
         || frozen.scope.projectRoot !== run.project_root || frozen.scope.workspace !== run.workspace_root
         || (input.acceptedReplay ? stage?.status !== "done" : index.current_stage !== input.stage || stage?.status !== "running") || stage.dir !== input.flow.stage(input.stage).directory
         || typeof stage.attempt !== "string" || !/^try-[0-9]{3,}$/.test(stage.attempt)
@@ -42,7 +48,7 @@ function select(context, input) {
         refuse();
     const accepted = input.acceptedReplay ? readAcceptedStageData(context, input) : null;
     const acceptedValue = accepted ? JSON.parse(accepted.bytes.toString("utf8")) : null;
-    if (accepted && (accepted.data_schema_id !== `dd-flow/mb-init-${input.stage}-result@1`
+    if (accepted && (accepted.data_schema_id !== schemaId(input.stage)
         || acceptedValue.schema_id !== accepted.data_schema_id || acceptedValue.run_id !== input.runId
         || acceptedValue.stage !== input.stage || !(acceptedValue.outcome === "accepted" || input.stage === "verify" && acceptedValue.outcome === "needs_repair" && input.flow.successor("verify", "needs_repair") === "review")
         || acceptedValue.input_sha256 !== stage.input_sha256))
@@ -56,33 +62,87 @@ function select(context, input) {
     const value = predecessor ? JSON.parse(predecessor.bytes.toString("utf8")) : null;
     const preflight = entry ? null : readAcceptedStageData(context, { ...input, stage: "preflight" });
     const preflightValue = preflight ? JSON.parse(preflight.bytes.toString("utf8")) : null;
-    if (preflight && (preflight.data_schema_id !== "dd-flow/mb-init-preflight-result@1"
+    if (preflight && (preflight.data_schema_id !== schemaId("preflight")
         || preflightValue.schema_id !== preflight.data_schema_id || preflightValue.run_id !== input.runId
         || preflightValue.stage !== "preflight" || preflightValue.outcome !== "accepted"
         || preflightValue.input_sha256 !== preflight.input_sha256
         || typeof preflight.input_sha256 !== "string" || !/^[a-f0-9]{64}$/.test(preflight.input_sha256)))
         refuse();
-    if (predecessor && (predecessor.data_schema_id !== `dd-flow/mb-init-${edges[0].from}-result@1`
+    if (predecessor && (predecessor.data_schema_id !== schemaId(edges[0].from)
         || value.schema_id !== predecessor.data_schema_id || value.run_id !== input.runId || value.stage !== edges[0].from
         || !(value.outcome === "accepted" || edges[0].from === "verify" && value.outcome === "needs_repair" && input.flow.successor("verify", "needs_repair") === input.stage)
         || typeof predecessor.input_sha256 !== "string" || !/^[a-f0-9]{64}$/.test(predecessor.input_sha256)
         || value.input_sha256 !== predecessor.input_sha256 || !Array.isArray(value.units)))
         refuse();
-    const unitIds = ["preflight", "discover"].includes(input.stage) ? null : value?.units.map((unit) => unit.id);
+    const unitIds = ["preflight", upgrade ? "diff-analysis" : "discover"].includes(input.stage) ? null : value?.units.map((unit) => unit.id);
     if (unitIds !== null && (!Array.isArray(unitIds) || unitIds.some(id => typeof id !== "string") || new Set(unitIds).size !== unitIds.length))
         refuse();
+    let upgradeBinding;
+    let upgradeAuthority = null;
+    let upgradeDiffValue = null;
+    const retainedEvidence = new Set(input.historicalEvidence ?? []);
+    if (upgrade) {
+        const scope = { requestId: frozen.scope.requestId, projectRoot: frozen.scope.projectRoot, workspaceRoot: frozen.scope.workspace };
+        const ready = readMemoryUpgradeBootstrapReadiness(context, scope), storage = readUpgradeStorageReadiness(context, scope);
+        if (!ready?.hasPreservationBaseline || ready.projectId !== input.projectId || !storage?.selection
+            || ready.authority.binding.execution_sha256 !== input.execution.sha256
+            || ready.authority.binding.storage_sha256 !== storage.sha256)
+            refuse();
+        const selected = storage.selection.payload;
+        if (selected.impact.chain.status !== "ok" || !selected.current.old_tree)
+            refuse();
+        const modes = ["patch", "targeted_minor", "full_migration"];
+        let minimum = selected.current.flow_pack_canon_version ? 2 : 0;
+        for (const step of selected.impact.chain.steps) {
+            const rank = modes.indexOf(step.minimum_upgrade_mode);
+            if (rank < 0 || typeof step.path_migration !== "boolean" || typeof step.runtime_migration !== "boolean")
+                refuse();
+            minimum = Math.max(minimum, step.path_migration || step.runtime_migration ? 2 : rank);
+        }
+        const invariants = preflightValue?.details.preservation_invariants;
+        if (!entry && !Array.isArray(invariants))
+            refuse();
+        const oldEvidence = readMemoryUpgradeEvidence(context, scope), evidence = oldEvidence.reference;
+        upgradeBinding = { minimumMode: modes[minimum], evidenceIndex: { path: evidence.path, sha256: evidence.sha256 }, ...(entry ? {} : { preservationInvariants: structuredClone(invariants) }) };
+        let diffAuthority = null;
+        if (!["preflight", "diff-analysis"].includes(input.stage)) {
+            const diff = readAcceptedStageData(context, { ...input, stage: "diff-analysis" });
+            const diffValue = JSON.parse(diff.bytes.toString("utf8"));
+            if (diff.data_schema_id !== schemaId("diff-analysis") || diffValue.schema_id !== diff.data_schema_id
+                || diffValue.stage !== "diff-analysis" || diffValue.run_id !== input.runId || diffValue.outcome !== "accepted"
+                || diffValue.input_sha256 !== diff.input_sha256 || !Array.isArray(diffValue.details?.path_map))
+                refuse();
+            upgradeBinding.authoringPaths = upgradeAuthoringPaths(selected.current.inventory.inventory, diffValue.details.path_map);
+            upgradeBinding.mechanicalUnits = new Set(diffValue.details.path_map
+                .map(change => change.unit_id).filter(id => !upgradeBinding.authoringPaths.has(id)));
+            upgradeDiffValue = diffValue;
+            diffAuthority = diff.authority_sha256;
+        }
+        // Old snapshots authorize historical evidence only, never current artifacts
+        // or reads through links/private paths. They do not replace source observation.
+        for (const { source } of oldEvidence.index.entries) {
+            retainedEvidence.add(`${memorySourceKey("workspace", source.path)}\0${source.sha256}`);
+            if (scope.projectRoot === scope.workspaceRoot)
+                retainedEvidence.add(`${memorySourceKey("project", source.path)}\0${source.sha256}`);
+        }
+        upgradeAuthority = hybridDigest({ bootstrap: ready.authority, storage: storage.sha256, diff: diffAuthority,
+            upgrade: { ...upgradeBinding, ...(upgradeBinding.authoringPaths ? { authoringPaths: [...upgradeBinding.authoringPaths] } : {}),
+                ...(upgradeBinding.mechanicalUnits ? { mechanicalUnits: [...upgradeBinding.mechanicalUnits].sort() } : {}) } });
+    }
     const binding = { runId: input.runId, stage: input.stage, inputSha256: stage.input_sha256,
         predecessors: predecessor ? [{ stage: edges[0].from, result: predecessor.result, input_sha256: predecessor.input_sha256 }] : [],
         unitIds, sources: new Map([...input.sources.hashes(), ...(input.checks?.artifactReferences() ?? []).map(ref => [memorySourceKey(ref.root, ref.path), ref.sha256])]),
-        historicalEvidence: new Set([...input.historicalEvidence ?? [], ...(value?.units ?? []).flatMap((unit) => unit.evidence.map(ref => `${memorySourceKey(ref.root, ref.path)}\0${ref.sha256}`))]),
+        historicalEvidence: new Set([...retainedEvidence, ...(value?.units ?? []).flatMap((unit) => unit.evidence.map(ref => `${memorySourceKey(ref.root, ref.path)}\0${ref.sha256}`))]),
         execution: input.execution, executionSha256: input.execution.sha256,
+        ...(upgradeBinding ? { upgrade: upgradeBinding } : {}),
         ...(preflight ? { preflight: { result: preflight.result, input_sha256: preflight.input_sha256,
                 semantic_scope: preflightValue.details.semantic_scope } } : {}) };
     const authority = hybridDigest({ projectId: input.projectId, runId: input.runId, stage: input.stage,
         attempt: stage.attempt, input: stage.input_sha256, directory: stage.dir, predecessor: predecessor?.authority_sha256 ?? null,
         anchor: index.execution_bundle ?? null, execution: input.execution.sha256, preflight: preflight?.authority_sha256 ?? null,
-        accepted: accepted?.authority_sha256 ?? null, settlement: settlement ? hybridDigest(settlement) : null });
-    return { binding, authority, predecessorStage: edges[0]?.from, value, preflightValue, accepted, acceptedValue };
+        accepted: accepted?.authority_sha256 ?? null, settlement: settlement ? hybridDigest(settlement) : null,
+        ...(upgrade ? { upgrade: upgradeAuthority } : {}) });
+    return { binding, authority, predecessorStage: edges[0]?.from, value, preflightValue, accepted, acceptedValue, upgradeDiffValue };
 }
 /** Controller-owned input for result preparation and writer-safe rechecking.
  * Semantic/check acceptance still belongs to productive stage handlers.
@@ -127,9 +187,14 @@ export class PreparedMemoryResultBinding {
             if (!new Ajv2020({ strict: true, strictRequired: false, validateFormats: false }).compile(schema)(selected.preflightValue))
                 refuse();
         }
+        if (selected.upgradeDiffValue) {
+            const schema = JSON.parse(input.flow.stageBlob("diff-analysis", "result_schema").toString("utf8"));
+            if (!new Ajv2020({ strict: true, strictRequired: false, validateFormats: false }).compile(schema)(selected.upgradeDiffValue))
+                refuse();
+        }
         // Productive bound discovery/composition preserve independently accepted source
         // bytes. Unbound data-only SDK fixtures gain no bootstrap qualification.
-        const preservation = input.bundle && ["discover", "compose"].includes(input.stage) ? PreparedMemoryBaselinePreservation.prepare(context, input.execution) : null;
+        const preservation = input.flow.descriptor.id === "mb-init" && input.bundle && ["discover", "compose"].includes(input.stage) ? PreparedMemoryBaselinePreservation.prepare(context, input.execution) : null;
         const prepared = new PreparedMemoryResultBinding(preparedInput, selected, preservation);
         prepared.assertCustody(context);
         return prepared;
@@ -139,7 +204,7 @@ export class PreparedMemoryResultBinding {
             || input.bundle.execution.sha256 !== input.execution.sha256 || input.bundle.descriptor.sha256 !== input.flow.sha256)
             refuse();
         const observed = captureRegisteredMemoryCompositionSources(context, input.bundle, input.registrationScope);
-        const prepared = this.prepare(context, { ...input, stage: "compose", sources: observed.sources });
+        const prepared = this.prepare(context, { ...input, stage: input.registrationScope.stage, sources: observed.sources });
         if (prepared.#binding.inputSha256 !== observed.inputSha256)
             refuse();
         prepared.#registration = { scope: structuredClone(input.registrationScope), sha256: observed.registrationSha256 };
@@ -149,6 +214,7 @@ export class PreparedMemoryResultBinding {
     }
     binding() {
         return { ...this.#binding, historicalEvidence: new Set(this.#binding.historicalEvidence), predecessors: structuredClone(this.#binding.predecessors), unitIds: structuredClone(this.#binding.unitIds),
+            ...(this.#binding.upgrade ? { upgrade: structuredClone(this.#binding.upgrade) } : {}),
             ...(this.#binding.preflight ? { preflight: structuredClone(this.#binding.preflight) } : {}), sources: new Map(this.#binding.sources) };
     }
     /** Retained accepted data for handler replay, never caller-supplied bytes. */

package/dist/services/memory-retained-review-authority.js

@@ -18,16 +18,17 @@ function refuse(reason) {
 }
 function original(context, scope, bundle) {
     const phase = readMemoryReviewPhase(context, scope, bundle), registration = readRegisteredMemoryReview(context, phase, 0);
-    const compose = readAcceptedStageData(context, { ...scope, stage: "compose" });
+    const upgrade = bundle.descriptor.descriptor.id === "mb-upgrade", authoring = upgrade ? "upgrade" : "compose";
+    const compose = readAcceptedStageData(context, { ...scope, stage: authoring });
     const verify = readAcceptedStageData(context, { ...scope, stage: "verify" });
     const composed = JSON.parse(compose.bytes.toString("utf8")), verified = JSON.parse(verify.bytes.toString("utf8"));
     const view = registration.view;
     if (registration.input_sha256 !== hybridDigest(view) || view.wave !== 0 || view.scope.bundle_sha256 !== bundle.sha256
         || view.scope.execution_sha256 !== bundle.execution.sha256 || view.source_policy !== "review-inputs@1"
-        || compose.data_schema_id !== "dd-flow/mb-init-compose-result@1" || composed.schema_id !== compose.data_schema_id
-        || composed.run_id !== scope.runId || composed.stage !== "compose" || composed.outcome !== "accepted"
+        || compose.data_schema_id !== (upgrade ? "dd-flow/mb-upgrade-stage-result@1" : "dd-flow/mb-init-compose-result@1") || composed.schema_id !== compose.data_schema_id
+        || composed.run_id !== scope.runId || composed.stage !== authoring || composed.outcome !== "accepted"
         || composed.input_sha256 !== compose.input_sha256 || hybridDigest(composed.units) !== hybridDigest(view.unit_inventory)
-        || verify.data_schema_id !== "dd-flow/mb-init-verify-result@1" || verified.schema_id !== verify.data_schema_id
+        || verify.data_schema_id !== (upgrade ? "dd-flow/mb-upgrade-stage-result@1" : "dd-flow/mb-init-verify-result@1") || verified.schema_id !== verify.data_schema_id
         || verified.run_id !== scope.runId || verified.stage !== "verify" || !["accepted", "needs_repair"].includes(verified.outcome)
         || verified.input_sha256 !== verify.input_sha256)
         refuse("changed_original_review_binding");
@@ -74,27 +75,35 @@ export class PreparedRetainedMemoryReviewAuthority {
         Object.freeze(this);
     }
     static prepare(context, scope, bundle) {
-        if (!(bundle instanceof RetainedExecutionBundle) || bundle.descriptor.descriptor.id !== "mb-init")
+        if (!(bundle instanceof RetainedExecutionBundle) || !["mb-init", "mb-upgrade"].includes(bundle.descriptor.descriptor.id))
             refuse("registered_memory_bundle_required");
         const generation = assertRunMutationAllowed(context, scope.projectId, scope.runId);
         const selected = context.db.readSnapshot(() => original(context, scope, bundle));
         const run = assertPreparedRunBundleSqlAuthority(context, scope, bundle), root = run.run_root ?? run.run_dir;
-        const observed = ObservedMemorySources.capture({ run: root }, [selected.compose, selected.verify].map(data => ({ root: "run", path: data.result.path })));
+        const upgrade = bundle.descriptor.descriptor.id === "mb-upgrade";
+        const refs = upgrade ? selected.registration.view.run_inputs.filter(ref => ref.root === "run" || !ref.path.startsWith(".memory-bank/"))
+            : [selected.compose, selected.verify].map(data => ({ root: "run", ...data.result }));
+        const observed = ObservedMemorySources.capture({ run: root, workspace: bundle.execution.snapshot().scope.workspace }, refs.map(({ root, path }) => ({ root, path })));
         const hashes = observed.hashes();
         if ([selected.compose, selected.verify].some(data => hashes.get(memorySourceKey("run", data.result.path)) !== data.result.sha256))
             refuse("retained_predecessor_bytes_changed");
+        if (refs.some(ref => hashes.get(memorySourceKey(ref.root, ref.path)) !== ref.sha256))
+            refuse("retained_source_bytes_changed");
         const coordinator = PreparedDescriptorStageCoordinator.prepare(context, {
             projectRoot: bundle.execution.snapshot().scope.projectRoot, runId: scope.runId, stage: "review"
         });
         coordinator.assertAllocatedCustody(context);
         const session = readDescriptorCoordinatorSession(context, { scope: { ...scope, stage: "review" }, bundle,
             workId: selected.registration.scope.parent_work_id }, refuse);
-        const preservation = PreparedMemoryBaselinePreservation.prepare(context, bundle.execution);
         // Historical accepted compose binding intentionally observes only retained
         // predecessor files. It does not claim today's repaired documents still
         // have the original output hashes or rerun current project policy.
-        const compose = PreparedMemoryResultBinding.prepare(context, { ...scope, stage: "compose", flow: bundle.descriptor,
+        const compose = PreparedMemoryResultBinding.prepare(context, { ...scope, stage: upgrade ? "upgrade" : "compose", flow: bundle.descriptor,
             execution: bundle.execution, bundle, acceptedReplay: true, sources: observed });
+        // The historical upgrade binding retains its original bootstrap/old tree;
+        // observed inputs preserve old RUN copies and original non-MB sources.
+        // Current repaired MB bytes belong to separately settled repair views.
+        const preservation = upgrade ? compose : PreparedMemoryBaselinePreservation.prepare(context, bundle.execution);
         if (!compose.acceptedBytes()?.equals(selected.compose.bytes))
             refuse("accepted_composition_changed");
         const verify = PreparedAcceptedMemoryVerification.prepare(context, { ...scope, bytes: selected.verify.bytes });

package/dist/services/memory-retained-second-baseline.js

@@ -46,7 +46,7 @@ export class PreparedRetainedSecondMemoryBaseline {
     static prepare(context, input) {
         if (!PreparedRetainedSecondMemoryRepairs.isPrepared(input.registration))
             refuse("retained_second_registration_required");
-        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");

package/dist/services/memory-retained-second-repairs.js

@@ -1,11 +1,12 @@
 import { createHash } from "node:crypto";
+import { assertMemorySqlCustody } from "./memory-custody-snapshot.js";
 import { AppError } from "../shared/errors.js";
 import { RetainedExecutionBundle } from "./execution-bundles.js";
 import { hybridDigest } from "./hybrid-contracts.js";
 import { PreparedHistoricalOriginalMemoryReview } from "./memory-historical-original-review.js";
 import { PreparedHistoricalCorrectedMemoryReview } from "./memory-historical-corrected-review.js";
 import { readRetainedCorrectedMemoryReviewRegistration } from "./memory-corrected-review-registration.js";
-import { validateMemoryReviewCorrectionPlan } from "./memory-review-correction-plan.js";
+import { validateMemoryReviewCorrectionPlan, memoryRepairCanonicalPaths } from "./memory-review-correction-plan.js";
 import { memoryRepairBatch, memoryRepairWorkerSchema } from "./memory-repair-registration.js";
 import { readWorkBatchCustody } from "./work-registry.js";
 const token = Symbol("retained-second-memory-repairs");
@@ -59,6 +60,7 @@ function assertAllocation(context, receipt, batch) {
 /** Retained second graph only. Does not grant current source/write admission,
  * allocate replacement Works or dispatch providers after receipt loss. */
 export class PreparedRetainedSecondMemoryRepairs {
+    #custodyKey = {};
     static isPrepared(value) {
         return typeof value === "object" && value !== null && #receipt in value;
     }
@@ -86,7 +88,7 @@ export class PreparedRetainedSecondMemoryRepairs {
         return this.#prepare(context, input, true);
     }
     static #prepare(context, input, closed) {
-        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");
@@ -105,6 +107,7 @@ export class PreparedRetainedSecondMemoryRepairs {
             refuse("changed_first_review");
         const view = first.view, assignments = new Map(view.assignments.map(item => [item.unit.id, item.unit]));
         const plan = validateMemoryReviewCorrectionPlan(bytes, input.bundle.engine(), { runId: scope.run_id, wave: 2,
+            canonicalPaths: memoryRepairCanonicalPaths(context, input.bundle),
             reviewSha256: receipt.review_sha256, units: view.unit_inventory.map(unit => assignments.get(unit.id) ?? unit), findings: history.projection().findings });
         if (history.projection().outcome === "blocked")
             refuse("blocked_first_review");
@@ -147,10 +150,13 @@ export class PreparedRetainedSecondMemoryRepairs {
     firstEffectiveReviewProof(context) { this.assertCustody(context); return this.#history.effectiveReviewProof(context); }
     verificationProfileHash(context) { this.assertCustody(context); return this.#history.verificationProfileHash(context); }
     assertCustody(context) {
-        this.#history.assertCustody(context);
-        if (hybridDigest(selected(context, this.#receipt.scope)) !== hybridDigest(this.#receipt))
-            refuse("registration_changed");
-        assertAllocation(context, this.#receipt, this.#batch);
+        const history = this.#history;
+        assertMemorySqlCustody(context, this.#custodyKey, () => {
+            history.assertCustody(context);
+            if (hybridDigest(selected(context, this.#receipt.scope)) !== hybridDigest(this.#receipt))
+                refuse("registration_changed");
+            assertAllocation(context, this.#receipt, this.#batch);
+        });
     }
     revalidate(context) { this.#history.revalidate(context); this.assertCustody(context); }
 }

package/dist/services/memory-review-correction-plan.js

@@ -8,32 +8,66 @@ import { ObservedMemorySources } from "./memory-source-observations.js";
 import { memorySourceKey } from "./memory-stage-results.js";
 import { reviewSourceHash, reviewEnvironmentAllowed } from "./review-copy.js";
 import { memoryProjectConfigurationPath } from "./memory-composition-graph.js";
+import { RetainedExecutionBundle } from "./execution-bundles.js";
+import { readUpgradeStorageReadiness } from "./memory-upgrade-storage-readiness.js";
+import { readAcceptedStageData } from "./stage-report-renderer.js";
+import { upgradeAuthoringPaths } from "./memory-upgrade-inventory.js";
 function refuse(reason) {
     throw new AppError("memory_review_correction_invalid", "Correction plan differs from retained material findings", 2, { reason, effect: "no_effect" });
 }
 const alias = (value) => value.normalize("NFC").toLowerCase();
-const overlap = (a, b) => alias(a) === alias(b) || alias(a).startsWith(`${alias(b)}/`) || alias(b).startsWith(`${alias(a)}/`);
+const overlapAliases = (a, b) => a === b || a.startsWith(`${b}/`) || b.startsWith(`${a}/`);
+const overlap = (a, b) => overlapAliases(alias(a), alias(b));
 /** Exact project-owned document paths shared by graph and physical admission. */
-export function assertMemoryRepairWritePaths(paths) {
+export function assertMemoryRepairWritePaths(paths, canonicalPaths = new Set()) {
     if (!Array.isArray(paths) || !paths.length || paths.length > 512)
         refuse("foreign_correction_write");
     if (paths.some(logical => typeof logical !== "string"))
         refuse("foreign_correction_write");
-    if (new Set(paths.map(alias)).size !== paths.length)
+    const normalizedPaths = paths.map(alias);
+    if (new Set(normalizedPaths).size !== paths.length)
         refuse("aliased_correction_paths");
-    for (const logical of paths) {
-        if (typeof logical !== "string" || !logical.startsWith(".memory-bank/") || logical.includes("\\") || logical.includes("\0")
-            || logical.length > 4096 || logical.split("/").some(part => !part || part === "." || part === "..")
-            || logical.split("/").some(part => !reviewEnvironmentAllowed(alias(part)) || [".git", "node_modules", ".dd-flow"].includes(alias(part)))
-            || !memoryProjectConfigurationPath(logical)
-                && [".memory-bank/dd-flow", ".memory-bank/mbb"].some(canonical => overlap(logical, canonical)))
+    for (const [index, logical] of paths.entries()) {
+        if (typeof logical !== "string")
+            refuse("foreign_correction_write");
+        const parts = logical.split("/");
+        if (!logical.startsWith(".memory-bank/") || logical.includes("\\") || logical.includes("\0")
+            || logical.length > 4096 || parts.some(part => !part || part === "." || part === "..")
+            || parts.some(part => { const normalized = alias(part); return !reviewEnvironmentAllowed(normalized) || [".git", "node_modules", ".dd-flow"].includes(normalized); })
+            || !memoryProjectConfigurationPath(logical) && !canonicalPaths.has(logical)
+                && [".memory-bank/dd-flow", ".memory-bank/mbb"].some(canonical => overlapAliases(normalizedPaths[index], canonical)))
             refuse("foreign_correction_write");
     }
 }
+/** Exact exceptions from the original CLI-selected ownership inventory, not
+ * path names or authority fields supplied in a repair proposal. Canonical
+ * defaults, generated markers, links and directory aliases remain excluded. */
+export function memoryRepairCanonicalPaths(context, bundle) {
+    if (!(bundle instanceof RetainedExecutionBundle) || !["mb-init", "mb-upgrade"].includes(bundle.descriptor.descriptor.id))
+        refuse("registered_memory_bundle_required");
+    if (bundle.descriptor.descriptor.id === "mb-init")
+        return new Set();
+    const frozen = bundle.execution.snapshot().scope;
+    const storage = readUpgradeStorageReadiness(context, { requestId: frozen.requestId, projectRoot: frozen.projectRoot, workspaceRoot: frozen.workspace }), selected = storage?.selection;
+    if (!selected || selected.payload.execution.sha256 !== bundle.execution.sha256)
+        refuse("retained_upgrade_selection_required");
+    const data = readAcceptedStageData(context, { projectId: storage.receipt.project_id, runId: bundle.manifest.run_id, stage: "diff-analysis" });
+    const diff = JSON.parse(data.bytes.toString("utf8"));
+    if (data.data_schema_id !== "dd-flow/mb-upgrade-stage-result@1" || diff.stage !== "diff-analysis" || diff.outcome !== "accepted")
+        refuse("accepted_upgrade_diff_required");
+    const inventory = selected.payload.current.inventory.inventory;
+    const paths = [...upgradeAuthoringPaths(inventory, diff.details.path_map).values()].flat();
+    return new Set(paths.filter(logical => {
+        const entry = inventory.entries.find(entry => `.memory-bank/${entry.path}` === logical);
+        return [".memory-bank/dd-flow/", ".memory-bank/mbb/"].some(prefix => logical.startsWith(prefix))
+            && logical.split("/").every(part => reviewEnvironmentAllowed(alias(part)) && ![".git", "node_modules", ".dd-flow"].includes(alias(part)))
+            && (!entry || ["project", "local-customized"].includes(entry.ownership));
+    }));
+}
 /** Semantic graph checks after strict frozen-schema admission. This projection
  * is not Work allocation, source-byte admission or filesystem permission.
  */
-export function validateMemoryReviewCorrectionGraph(plan, units, findings) {
+export function validateMemoryReviewCorrectionGraph(plan, units, findings, canonicalPaths = new Set()) {
     const material = new Map(findings.filter(finding => finding.severity !== "minor" && finding.status === "open").map(finding => [finding.id, finding]));
     if (!material.size)
         refuse("no_material_correction_required");
@@ -47,7 +81,7 @@ export function validateMemoryReviewCorrectionGraph(plan, units, findings) {
             refuse("missing_correction_task");
         if (work.depends_on.some(key => !byKey.has(key) || key === work.key))
             refuse("foreign_correction_dependency");
-        assertMemoryRepairWritePaths(work.write_paths);
+        assertMemoryRepairWritePaths(work.write_paths, canonicalPaths);
         const targetUnits = new Set();
         for (const id of work.finding_ids) {
             const finding = material.get(id);
@@ -109,7 +143,7 @@ export function validateMemoryReviewCorrectionPlan(bytes, engine, binding) {
             refuse("invalid_correction_schema");
         if (value.run_id !== binding.runId || value.wave !== binding.wave || value.review_sha256 !== binding.reviewSha256)
             refuse("foreign_correction_identity");
-        validateMemoryReviewCorrectionGraph(value, binding.units, binding.findings);
+        validateMemoryReviewCorrectionGraph(value, binding.units, binding.findings, binding.canonicalPaths);
         return structuredClone(value);
     }
     catch (error) {
@@ -144,6 +178,7 @@ export class PreparedMemoryInitialCorrectionPlan {
         if (results.some(result => result.outcome === "blocked"))
             refuse("blocked_review_requires_resolution");
         const value = validateMemoryReviewCorrectionPlan(bytes, bundle.engine(), { runId: registration.run_id, wave: 1,
+            canonicalPaths: memoryRepairCanonicalPaths(context, bundle),
             reviewSha256: review.sha256, units: registration.view.unit_inventory, findings: memoryReviewWaveProjection(results, registration.view.diagnostic_findings).findings });
         for (const work of value.works)
             bundle.execution.work("review", work.profile_id ?? undefined);