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

package/dist/services/memory-corrected-review-inputs.js

@@ -1,6 +1,7 @@
 import { AppError } from "../shared/errors.js";
 import { hybridDigest } from "./hybrid-contracts.js";
 import { PreparedCompletedMemoryCorrectionWave } from "./memory-completed-correction-wave.js";
+import { isCompletedMemoryRepairClaim } from "./memory-repair-work-results.js";
 import { ObservedMemorySources } from "./memory-source-observations.js";
 import { memorySourceKey } from "./memory-stage-results.js";
 import { assertPreparedRunBundleSqlAuthority } from "./runs.js";
@@ -9,6 +10,7 @@ import { RetainedExecutionBundle } from "./execution-bundles.js";
 import { PreparedRetainedMemoryReviewAuthority } from "./memory-retained-review-authority.js";
 import { PreparedRetainedMemoryReviewResults } from "./memory-retained-review-results.js";
 import { PreparedRegisteredMemoryCorrections } from "./memory-repair-registration.js";
+import { memoryReviewViewWithinLimit } from "./memory-review-limits.js";
 const token = Symbol("corrected-memory-review-inputs");
 function refuse(reason) {
     throw new AppError("memory_corrected_review_input_invalid", "Re-review inputs lack settled corrections and current source custody", 2, { reason, effect: "no_effect" });
@@ -46,9 +48,8 @@ export function correctedMemoryReviewAssignments(input) {
     const finalProof = new Map();
     for (const repair of input.repairs) {
         reference(repair.reference.path, repair.reference.sha256, "run");
-        if (repair.result.outcome !== "accepted" || !Array.isArray(repair.unit_ids) || !repair.unit_ids.length
-            || repair.unit_ids.some((id) => !input.units.some(unit => unit.id === id && unit.applicability === "applicable"))
-            || !Array.isArray(repair.result.changes) || !repair.result.changes.length)
+        if (!isCompletedMemoryRepairClaim(repair.result) || !Array.isArray(repair.unit_ids) || !repair.unit_ids.length
+            || repair.unit_ids.some((id) => !input.units.some(unit => unit.id === id && unit.applicability === "applicable")))
             refuse("invalid_repair_projection");
         for (const change of repair.result.changes) {
             reference(change.path, change.after_sha256 ?? change.before_sha256);
@@ -97,6 +98,9 @@ export function correctedMemoryReviewAssignments(input) {
                     unit.artifacts.push({ ...current });
             }
         const inputs = new Map();
+        for (const ref of input.initialAssignments?.find(item => item.unit.id === original.id)?.inputs ?? [])
+            if (ref.root === "run" && /^upgrade-baseline-[a-f0-9]{64}\.bin$/.test(ref.path))
+                inputs.set(memorySourceKey(ref.root, ref.path), { ...ref });
         for (const ref of [...unit.evidence, ...unit.artifacts, ...input.repairs.map(repair => reference(repair.reference.path, repair.reference.sha256, "run"))]) {
             const physical = reference(ref.root === "canon" ? `.memory-bank/${ref.path}` : ref.path, ref.sha256, ref.root === "run" ? "run" : "workspace");
             const key = memorySourceKey(physical.root, physical.path), prior = inputs.get(key);
@@ -151,7 +155,7 @@ export class PreparedCorrectedMemoryReviewInputs {
         return prepared;
     }
     static prepareFromBundle(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");
         const original = PreparedRetainedMemoryReviewAuthority.prepare(context, input.scope, input.bundle);
         const review = PreparedRetainedMemoryReviewResults.prepare(context, original);
@@ -203,8 +207,9 @@ function prepareView(wave) {
         completed_correction_sha256: wave.sha256, original_review_sha256: review.sha256,
         source_policy: "review-inputs@1", source_sha256: source, base: original.base, run_inputs: runInputs,
         unit_inventory: structuredClone(original.unit_inventory), affected_unit_ids: wave.affectedUnitIds(), assignments,
+        ...(original.upgrade_baseline ? { upgrade_baseline: structuredClone(original.upgrade_baseline), preservation_invariants: structuredClone(original.preservation_invariants ?? []) } : {}),
         instruction: structuredClone(original.instruction), repairs: repairs.map(repair => ({ work_id: repair.work_id, authority_sha256: repair.authority_sha256, result: repair.reference })) };
-    if (Buffer.byteLength(JSON.stringify(view)) > 1024 * 1024)
+    if (!memoryReviewViewWithinLimit(view))
         refuse("unbounded_corrected_view");
     return view;
 }

package/dist/services/memory-corrected-review-receipt.js

@@ -1,3 +1,4 @@
+import { assertMemorySqlCustody } from "./memory-custody-snapshot.js";
 import { AppError } from "../shared/errors.js";
 import { appendAudit } from "./audit.js";
 import { hybridDigest } from "./hybrid-contracts.js";
@@ -81,7 +82,7 @@ export class PreparedMemoryCorrectedReviewReceipt {
             refuse("receipt_readback_failed");
     }
 }
-function acceptedReceipt(context, scope) {
+function acceptedReceipt(context, scope, flowId) {
     const data = readAcceptedStageData(context, { ...scope, stage: "review" }), rows = records(context, scope);
     if (rows.length !== 1 || Buffer.byteLength(rows[0].payload_json) > 2 * 1024 * 1024)
         refuse("accepted_receipt_missing");
@@ -99,7 +100,7 @@ function acceptedReceipt(context, scope) {
             || !/^[a-f0-9]{64}$/.test(retained.first_review_proof_sha256)))
         || typeof retained.corrected_input_sha256 !== "string" || !/^[a-f0-9]{64}$/.test(retained.corrected_input_sha256)
         || typeof retained.check_receipt_sha256 !== "string" || !/^[a-f0-9]{64}$/.test(retained.check_receipt_sha256)
-        || data.data_schema_id !== "dd-flow/mb-init-review-result@1" || retained.result_sha256 !== data.result.sha256
+        || data.data_schema_id !== (flowId === "mb-upgrade" ? "dd-flow/mb-upgrade-stage-result@1" : "dd-flow/mb-init-review-result@1") || retained.result_sha256 !== data.result.sha256
         || retained.input_sha256 !== data.input_sha256)
         refuse("accepted_receipt_changed");
     return { data, retained, authority: hybridDigest({ data: data.authority_sha256, receipt: retained }) };
@@ -109,24 +110,27 @@ function acceptedReceipt(context, scope) {
  * commit: generic settlement restores it; reviewers/checks/repairs may not be
  * substituted or re-admitted from today's project policy or documents. */
 export class PreparedAcceptedMemoryCorrectedReview {
+    #custodyKey = {};
     #scope;
     #authority;
     #history;
-    constructor(key, scope, authority, history) {
+    #flowId;
+    constructor(key, scope, authority, history, flowId) {
         if (key !== token)
             refuse("receipt_token_required");
         this.#scope = { ...scope };
         this.#authority = authority;
         this.#history = history;
+        this.#flowId = flowId;
         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)
             || !(input.bytes instanceof Uint8Array) || !input.bytes.length || input.bytes.length > 1024 * 1024)
             refuse("registered_memory_result_required");
         if (context.db.isOwnedWriteTransaction?.())
             refuse("preparation_outside_writer_required");
-        const accepted = context.db.readSnapshot(() => acceptedReceipt(context, input.scope));
+        const accepted = context.db.readSnapshot(() => acceptedReceipt(context, input.scope, input.bundle.descriptor.descriptor.id));
         if (!accepted.data.bytes.equals(Buffer.from(input.bytes)))
             refuse("accepted_result_bytes_changed");
         const hashes = { correctedInputSha256: accepted.retained.corrected_input_sha256, checkReceiptSha256: accepted.retained.check_receipt_sha256 };
@@ -151,20 +155,24 @@ export class PreparedAcceptedMemoryCorrectedReview {
         const schema = JSON.parse(input.bundle.descriptor.stageBlob("review", "result_schema").toString("utf8"));
         if (!new Ajv2020({ strict: true, strictRequired: false, validateFormats: false }).compile(schema)(value))
             refuse("accepted_result_schema_changed");
-        const prepared = new PreparedAcceptedMemoryCorrectedReview(token, input.scope, accepted.authority, history);
+        const prepared = new PreparedAcceptedMemoryCorrectedReview(token, input.scope, accepted.authority, history, input.bundle.descriptor.descriptor.id);
         prepared.revalidate(context);
         return prepared;
     }
     assertCustody(context) {
-        this.#history.assertCustody(context);
-        if (acceptedReceipt(context, this.#scope).authority !== this.#authority)
-            refuse("accepted_review_custody_changed");
+        const history = this.#history;
+        assertMemorySqlCustody(context, this.#custodyKey, () => {
+            history.assertCustody(context);
+            if (acceptedReceipt(context, this.#scope, this.#flowId).authority !== this.#authority)
+                refuse("accepted_review_custody_changed");
+        });
     }
     /** Final wave inputs selected by the independently accepted receipt. */
     reviewedSources(context) {
         this.assertCustody(context);
         return this.#history.retainedInputView().run_inputs;
     }
+    settledDocumentBaseline(context) { this.assertCustody(context); return this.#history.settledDocumentBaseline(); }
     finalChecks(context) { this.assertCustody(context); return this.#history.finalChecks(context); }
     revalidate(context) { this.#history.revalidate(context); this.assertCustody(context); }
 }

package/dist/services/memory-corrected-review-registration.js

@@ -6,6 +6,7 @@ import { isMemoryCorrectionInputOwner } from "./memory-correction-input-owner.js
 import { PreparedMemoryCorrectionCheckReceipt } from "./memory-correction-check-receipt.js";
 import { memoryCorrectedReviewBatch } from "./memory-corrected-review-batch.js";
 import { addWorkBatch, prepareWorkBatch, readWorkBatchCustody } from "./work-registry.js";
+import { memoryReviewRegistrationByteLimit } from "./memory-review-limits.js";
 const token = Symbol("registered-corrected-memory-review");
 const event = "memory.corrected_review_registration";
 function refuse(reason) {
@@ -40,7 +41,7 @@ function readRetainedRegistration(context, scope, inputSha256, checkReceiptSha25
     const rows = context.db.all("SELECT payload_json FROM audit_events WHERE project_id=? AND event_type=? AND json_extract(payload_json,'$.run_id')=? AND json_extract(payload_json,'$.scope.attempt')=? AND json_extract(payload_json,'$.scope.parent_work_id')=? AND json_extract(payload_json,'$.wave')=? LIMIT 2", [scope.project_id, event, scope.run_id, scope.attempt, scope.parent_work_id, wave]);
     if (!rows.length)
         return null;
-    if (rows.length !== 1 || Buffer.byteLength(rows[0].payload_json) > 2 * 1024 * 1024)
+    if (rows.length !== 1 || Buffer.byteLength(rows[0].payload_json) > memoryReviewRegistrationByteLimit)
         refuse("ambiguous_or_unbounded_registration");
     let receipt;
     try {
@@ -171,7 +172,7 @@ export function registerCorrectedMemoryReview(context, inputs, checks) {
                 refuse("review_registration_missing");
             const receipt = { schema_id: "dd-flow/memory-corrected-review-registration@1", run_id: scope.run_id, scope: view.scope, wave: view.wave,
                 input_sha256: inputs.sha256, view, check_receipt_sha256: checks.sha256, batch_sha256: hybridDigest(batch.works), work_ids: ids };
-            if (Buffer.byteLength(JSON.stringify(receipt)) > 2 * 1024 * 1024)
+            if (Buffer.byteLength(JSON.stringify(receipt)) > memoryReviewRegistrationByteLimit)
                 refuse("unbounded_registration");
             appendAudit(context, { projectId: scope.project_id, eventType: event, payload: receipt });
         }

package/dist/services/memory-correction-check-receipt.js

@@ -65,7 +65,7 @@ export class PreparedMemoryCorrectionCheckReceipt {
         evidence.assertOwner({ projectId: view.scope.project_id, runId: view.scope.run_id, scope: "aggregate" });
         const receipt = { schema_id: "dd-flow/memory-correction-checks@1", project_id: view.scope.project_id, run_id: view.scope.run_id,
             wave: view.wave, review_input_sha256: view.scope.input_sha256, corrected_input_sha256: corrected.sha256,
-            completed_correction_sha256: view.completed_correction_sha256, profile_sha256: corrected.verificationProfileHash(context),
+            completed_correction_sha256: view.completed_correction_sha256, profile_sha256: policy.profileHash(),
             declarations_sha256: hybridDigest(policy.declarations()), checks: evidence.retainedReferences(context) };
         if (!receipt.checks.length || receipt.checks.length > 4096 || Buffer.byteLength(JSON.stringify(receipt)) > 2 * 1024 * 1024)
             refuse("unbounded_check_receipt");
@@ -81,7 +81,8 @@ export class PreparedMemoryCorrectionCheckReceipt {
             refuse("prepared_check_owners_required");
         if (context.db.isOwnedWriteTransaction?.())
             refuse("preparation_outside_writer_required");
-        if (!context.db.readSnapshot(() => stored(context, corrected))) {
+        const existing = context.db.readSnapshot(() => stored(context, corrected));
+        if (!existing) {
             const view = corrected.value(), projectRoot = corrected.bundle().execution.snapshot().scope.projectRoot;
             const args = ["--run", view.scope.run_id, "--project-root", projectRoot, "--wave", String(view.wave), "--json"];
             throw new AppError("memory_correction_checks_invalid", "Correction checks have not been registered for the settled corrected view", 2, { reason: "registered_check_receipt_required", phase: "prepare", effect: "no_effect", recoverable: true,
@@ -90,7 +91,22 @@ export class PreparedMemoryCorrectionCheckReceipt {
         const bundle = corrected.bundle(), scope = corrected.value().scope;
         const policy = PreparedMemoryVerificationChecks.prepare(context, { projectId: scope.project_id, runId: scope.run_id,
             execution: bundle.execution, flow: bundle.descriptor, corrected });
-        return PreparedMemoryCorrectionCheckReceipt.prepare(context, corrected, policy);
+        // Registered execution belongs to its original environment, not the
+        // controller/reviewer's current shell. Keep exact current document and
+        // policy custody, then restore the sealed execution instead of selecting
+        // fresh evidence using the observer's environment.
+        const view = corrected.value(), receipt = historicalReceipt(context, { projectId: scope.project_id, runId: scope.run_id,
+            wave: view.wave, receiptSha256: hybridDigest(existing), correctedInputSha256: corrected.sha256 });
+        const expected = { schema_id: "dd-flow/memory-correction-checks@1", project_id: scope.project_id, run_id: scope.run_id,
+            wave: view.wave, review_input_sha256: scope.input_sha256, corrected_input_sha256: corrected.sha256,
+            completed_correction_sha256: view.completed_correction_sha256, profile_sha256: policy.profileHash(),
+            declarations_sha256: hybridDigest(policy.declarations()), checks: receipt.checks };
+        if (hybridDigest(receipt) !== hybridDigest(expected))
+            refuse("registered_check_receipt_changed");
+        const evidence = PreparedRetainedCheckEvidence.prepare(context, { projectId: scope.project_id, runId: scope.run_id, references: receipt.checks });
+        const prepared = new PreparedMemoryCorrectionCheckReceipt(token, corrected, policy, evidence, receipt, true);
+        prepared.revalidate(context);
+        return prepared;
     }
     value() {
         return structuredClone(this.#receipt);
@@ -111,7 +127,7 @@ export class PreparedMemoryCorrectionCheckReceipt {
         const existing = stored(context, this.#corrected);
         if ((this.#registered && !existing) || (existing && hybridDigest(existing) !== this.sha256))
             refuse("registered_check_receipt_changed");
-        if (hybridDigest(this.#evidence.retainedReferences(context)) !== hybridDigest(this.#receipt.checks))
+        if ("retainedReferences" in this.#evidence && hybridDigest(this.#evidence.retainedReferences(context)) !== hybridDigest(this.#receipt.checks))
             refuse("selected_check_evidence_changed");
     }
     revalidate(context) {

package/dist/services/memory-custody-snapshot.js

@@ -0,0 +1,36 @@
+import { AppError } from "../shared/errors.js";
+const snapshots = new WeakMap();
+function synchronous(read) {
+    const value = read();
+    if (value && typeof value.then === "function") {
+        void Promise.resolve(value).catch(() => { });
+        throw new AppError("read_snapshot_async", "Memory custody traversal must be synchronous", 1);
+    }
+    return value;
+}
+export function withMemoryCustodySnapshot(context, read) {
+    if (snapshots.has(context))
+        return synchronous(read);
+    return context.db.readSnapshot(() => {
+        snapshots.set(context, new Set());
+        try {
+            return synchronous(read);
+        }
+        finally {
+            snapshots.delete(context);
+        }
+    });
+}
+/** Only SQL custody may share a completed proof within this synchronous
+ * snapshot. Physical revalidation stays outside this memo, and the next
+ * traversal always rereads SQL. Failed checks never become reusable proof.
+ * Prepared owners supply private keys, never their externally visible object. */
+export function assertMemorySqlCustody(context, owner, validate) {
+    withMemoryCustodySnapshot(context, () => {
+        const checked = snapshots.get(context);
+        if (checked.has(owner))
+            return;
+        synchronous(validate);
+        checked.add(owner);
+    });
+}

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

@@ -13,14 +13,23 @@ import { ObservedMemorySources } from "./memory-source-observations.js";
 import { memorySourceKey, PreparedMemoryStageResult } from "./memory-stage-results.js";
 import { PreparedDescriptorStageSettlement } from "./descriptor-stage-settlement.js";
 import { assertPreparedRunBundleSqlAuthority } from "./runs.js";
-import { readMemoryInitBootstrapReadiness } from "./memory-init-bootstrap-readiness.js";
-import { readMemoryInitGitPolicy } from "./memory-init-git-policy.js";
 import { reviewedMemoryGitFiles } from "./memory-git-integration.js";
+import { readMemoryFinishGitSelection, readMemoryUpgradeFinishInventory } from "./memory-finish-integration.js";
 const token = Symbol("memory-finish-evidence"), event = "memory.finish_evidence";
 const hash = (bytes) => createHash("sha256").update(bytes).digest("hex");
 function refuse(reason) {
     throw new AppError("memory_finish_evidence_invalid", "Finish evidence lacks independently prepared acceptance custody", 2, { reason, effect: "no_effect" });
 }
+export function parseMemoryFinishProposal(bytes) {
+    if (!(bytes instanceof Uint8Array) || !bytes.length || bytes.length > 1024 * 1024)
+        refuse("invalid_result_bytes");
+    try {
+        return JSON.parse(new TextDecoder("utf-8", { fatal: true }).decode(bytes));
+    }
+    catch {
+        throw new AppError("memory_finish_evidence_invalid", "Finish proposal must be valid UTF-8 JSON. Correct only the proposal syntax, then use retry_command; do not rerun integration or settled checks", 2, { reason: "invalid_result_json", phase: "prepare", effect: "no_effect", recoverable: true, result_sha256: hash(bytes) });
+    }
+}
 /** Terminal inventory and receipts belong to the accepted review/evidence
  * owners. Optional echoes cannot introduce new references or semantic claims. */
 export function projectMemoryFinishResult(value, owner, resultSha256) {
@@ -77,11 +86,24 @@ function acceptance(context, scope) {
         refuse("ambiguous_finish_acceptance");
     return rows[0] ? JSON.parse(rows[0].payload_json) : null;
 }
+/** Terminal parsing inherits the accepted scope and named old-data criteria;
+ * no fresh version inference or mutable project sources are consulted. */
+function upgradeBinding(context, scope, bundle) {
+    if (bundle.descriptor.descriptor.id !== "mb-upgrade")
+        refuse("upgrade_preservation_binding_changed");
+    const preflight = readAcceptedStageData(context, { ...scope, stage: "preflight" });
+    const diff = readAcceptedStageData(context, { ...scope, stage: "diff-analysis" });
+    const preservationInvariants = JSON.parse(preflight.bytes.toString("utf8")).details.preservation_invariants;
+    const minimumMode = JSON.parse(diff.bytes.toString("utf8")).details.mode;
+    if (!["patch", "targeted_minor", "full_migration"].includes(minimumMode) || !Array.isArray(preservationInvariants))
+        refuse("upgrade_preservation_binding_changed");
+    return { minimumMode, preservationInvariants };
+}
 /** SQL-only historical byte/projection custody. Callers must independently
  * prepare the genuine accepted review owner outside their writer. This does
  * not re-observe today's integration checkout or grant RUN closure. */
 export function readAcceptedMemoryFinishEvidence(context, input) {
-    if (!(input.bundle instanceof RetainedExecutionBundle) || input.bundle.descriptor.descriptor.id !== "mb-init"
+    if (!(input.bundle instanceof RetainedExecutionBundle) || !["mb-init", "mb-upgrade"].includes(input.bundle.descriptor.descriptor.id)
         || !PreparedMemoryFinishReview.isPrepared(input.review))
         refuse("registered_memory_review_required");
     const scope = { ...input.scope, stage: "finish" };
@@ -96,7 +118,7 @@ export function readAcceptedMemoryFinishEvidence(context, input) {
         || evidence.attempt !== stage.attempt || evidence.input_sha256 !== stage.input_sha256
         || evidence.bundle_sha256 !== input.bundle.sha256 || evidence.review_sha256 !== reviewData.result.sha256
         || !input.review.bytes().equals(reviewData.bytes)
-        || data.data_schema_id !== "dd-flow/mb-init-finish-result@1" || data.input_sha256 !== stage.input_sha256
+        || data.data_schema_id !== (input.bundle.descriptor.descriptor.id === "mb-upgrade" ? "dd-flow/mb-upgrade-stage-result@1" : "dd-flow/mb-init-finish-result@1") || data.input_sha256 !== stage.input_sha256
         || hybridDigest(evidence.checks) !== hybridDigest(input.review.finalChecks(context)))
         refuse("accepted_finish_evidence_changed");
     const expectedAcceptance = { schema_id: "dd-flow/memory-finish-acceptance@1", project_id: scope.projectId, run_id: scope.runId,
@@ -134,16 +156,18 @@ export function readAcceptedMemoryFinishEvidence(context, input) {
         refuse("historical_evidence_projection_changed");
     const frozen = input.bundle.execution.snapshot().scope;
     const request = { requestId: frozen.requestId, projectRoot: frozen.projectRoot, workspaceRoot: frozen.workspace };
-    const bootstrap = readMemoryInitBootstrapReadiness(context, request), policy = readMemoryInitGitPolicy(context, request);
-    if (!bootstrap || !policy || bootstrap.projectId !== scope.projectId
-        || bootstrap.authority.binding.execution_sha256 !== input.bundle.execution.sha256
-        || bootstrap.authority.binding.git_policy_sha256 !== hybridDigest(policy)
-        || policy.target_sha256 !== hybridDigest(bootstrap.authority.binding.target)
-        || readiness.value.bootstrap_authority_sha256 !== hybridDigest(bootstrap.authority)
-        || readiness.value.pack_sha256 !== bootstrap.authority.binding.pack_sha256)
+    const selected = readMemoryFinishGitSelection(context, scope, input.bundle), policy = selected.policy;
+    const packSha256 = selected.kind === "init" ? selected.readiness.authority.binding.pack_sha256 : selected.readiness.authority.receipt.upgrade_target.pack_sha256;
+    if (readiness.value.bootstrap_authority_sha256 !== hybridDigest(selected.readiness.authority)
+        || readiness.value.pack_sha256 !== packSha256)
         refuse("historical_terminal_bootstrap_policy_changed");
     const integrated = integration.value;
-    const reviewedFiles = reviewedMemoryGitFiles(input.review.reviewedSources(context));
+    const upgrade = selected.kind === "upgrade" ? readMemoryUpgradeFinishInventory(context, scope, input.bundle, input.review) : null;
+    const reviewedFiles = upgrade?.references ?? reviewedMemoryGitFiles(input.review.reviewedSources(context));
+    if (upgrade && (integrated.upgrade_inventory_sha256 !== hybridDigest(upgrade)
+        || integrated.removed_files_sha256 !== (upgrade.removals.length ? hybridDigest(upgrade.removals) : undefined)
+        || hybridDigest([readiness.value.migration_record]) !== hybridDigest([upgrade.migrationRecord])))
+        refuse("historical_upgrade_inventory_changed");
     if (integrated.schema_id !== "dd-flow/memory-git-integration-observation@1"
         || integrated.project_root !== request.projectRoot || integrated.workspace_root !== request.workspaceRoot
         || integrated.repository !== policy.repository || integrated.workspace_branch !== policy.workspace_branch
@@ -167,11 +191,13 @@ export function readAcceptedMemoryFinishEvidence(context, input) {
         runId: scope.runId, stage: "finish", inputSha256: stage.input_sha256,
         predecessors: [{ stage: "review", result: reviewData.result, input_sha256: reviewData.input_sha256 }],
         unitIds: reviewed.units.map((unit) => unit.id), sources,
+        ...(upgrade ? { upgrade: upgradeBinding(context, scope, input.bundle) } : {}),
         historicalEvidence: new Set(reviewed.units.flatMap((unit) => unit.evidence.map(ref => `${memorySourceKey(ref.root, ref.path)}\0${ref.sha256}`)))
     });
     const value = result.value(), references = { coverage: evidence.coverage,
         checks: evidence.checks.map(({ path, sha256 }) => ({ path, sha256 })),
-        integration: evidence.integration, normal_flow_readiness: evidence.normal_flow_readiness };
+        integration: evidence.integration, normal_flow_readiness: evidence.normal_flow_readiness,
+        ...(upgrade ? { migration_record: upgrade.migrationRecord } : {}) };
     if (value.outcome !== "accepted" || hybridDigest(value.units) !== hybridDigest(reviewed.units)
         || hybridDigest(value.findings) !== hybridDigest(reviewed.findings) || hybridDigest(value.details) !== hybridDigest(references))
         refuse("historical_finish_result_projection_changed");
@@ -209,7 +235,7 @@ export class PreparedMemoryFinishEvidence {
         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");
@@ -258,7 +284,8 @@ export class PreparedMemoryFinishEvidence {
     references() {
         const value = this.#receipt;
         return { coverage: { ...value.coverage }, checks: value.checks.map(({ path, sha256 }) => ({ path, sha256 })),
-            integration: { ...value.integration }, normal_flow_readiness: { ...value.normal_flow_readiness } };
+            integration: { ...value.integration }, normal_flow_readiness: { ...value.normal_flow_readiness },
+            ...(this.#bundle.descriptor.descriptor.id === "mb-upgrade" ? { migration_record: this.#readiness.value().migration_record } : {}) };
     }
     /** Fresh terminal result preparation, never a historical replay reader.
      * The proposal cannot replace accepted review coverage or CLI evidence. */
@@ -274,18 +301,13 @@ export class PreparedMemoryFinishEvidence {
         if (typeof review.input_sha256 !== "string")
             refuse("accepted_review_input_missing");
         const reviewed = JSON.parse(this.#review.bytes().toString("utf8"));
-        let proposal;
-        try {
-            proposal = JSON.parse(new TextDecoder("utf-8", { fatal: true }).decode(bytes));
-        }
-        catch {
-            refuse("invalid_result_bytes");
-        }
+        const proposal = parseMemoryFinishProposal(bytes);
         const canonical = projectMemoryFinishResult(proposal, { units: reviewed.units, findings: reviewed.findings, details: this.references() }, hash(bytes));
         const result = PreparedMemoryStageResult.prepare(Buffer.from(JSON.stringify(canonical)), bundle.descriptor, {
             runId: this.#scope.runId, stage: "finish", inputSha256: this.#input.inputSha256,
             predecessors: [{ stage: "review", result: review.result, input_sha256: review.input_sha256 }],
             unitIds: reviewed.units.map((unit) => unit.id), sources: sources.hashes(),
+            ...(bundle.descriptor.descriptor.id === "mb-upgrade" ? { upgrade: upgradeBinding(context, this.#scope, bundle) } : {}),
             historicalEvidence: new Set(reviewed.units.flatMap((unit) => unit.evidence.map(ref => `${memorySourceKey(ref.root, ref.path)}\0${ref.sha256}`)))
         });
         const value = result.value();

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

@@ -1,3 +1,4 @@
+import { assertMemorySqlCustody, withMemoryCustodySnapshot } from "./memory-custody-snapshot.js";
 import { AppError } from "../shared/errors.js";
 import { RetainedExecutionBundle } from "./execution-bundles.js";
 import { readAcceptedStageData } from "./stage-report-renderer.js";
@@ -32,6 +33,7 @@ function selected(context, scope) {
 /** Closed review predecessor proof only. It does not establish integration,
  * normal-flow readiness, terminal Stage acceptance or RUN completion. */
 export class PreparedMemoryFinishReview {
+    #custodyKey = {};
     static isPrepared(value) {
         return typeof value === "object" && value !== null && #review in value;
     }
@@ -51,40 +53,52 @@ export class PreparedMemoryFinishReview {
         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)
             || input.bundle.descriptor.successor("review", "accepted") !== "finish")
             refuse("registered_memory_bundle_required");
         if (context.db.isOwnedWriteTransaction?.())
             refuse("preparation_outside_writer_required");
-        assertPreparedRunBundleSqlAuthority(context, input.scope, input.bundle);
-        const data = context.db.readSnapshot(() => selected(context, input.scope));
-        const review = data.corrected
-            ? PreparedAcceptedMemoryCorrectedReview.prepare(context, { ...input, bytes: data.data.bytes })
-            : PreparedAcceptedMemoryInitialReview.prepare(context, { ...input, bytes: data.data.bytes });
-        const prepared = new PreparedMemoryFinishReview(token, input.scope, review, data);
-        prepared.revalidate(context);
-        return prepared;
+        return withMemoryCustodySnapshot(context, () => {
+            assertPreparedRunBundleSqlAuthority(context, input.scope, input.bundle);
+            const data = context.db.readSnapshot(() => selected(context, input.scope));
+            const review = data.corrected
+                ? PreparedAcceptedMemoryCorrectedReview.prepare(context, { ...input, bytes: data.data.bytes })
+                : PreparedAcceptedMemoryInitialReview.prepare(context, { ...input, bytes: data.data.bytes });
+            const prepared = new PreparedMemoryFinishReview(token, input.scope, review, data);
+            prepared.revalidate(context);
+            return prepared;
+        });
     }
     bytes() { return Buffer.from(this.#bytes); }
     reviewedSources(context) { this.assertCustody(context); return this.#review.reviewedSources(context); }
+    reviewedDocumentInventory(context) {
+        this.assertCustody(context);
+        return this.#review instanceof PreparedAcceptedMemoryCorrectedReview ? this.#review.settledDocumentBaseline(context).entries() : null;
+    }
     finalChecks(context) { this.assertCustody(context); return this.#review.finalChecks(context); }
     assertCustody(context) {
-        this.#review.assertCustody(context);
-        const data = selected(context, this.#scope);
-        if (data.corrected !== this.#corrected || data.data.authority_sha256 !== this.#authority
-            || !data.data.bytes.equals(this.#bytes))
-            refuse("accepted_review_changed");
+        const review = this.#review;
+        assertMemorySqlCustody(context, this.#custodyKey, () => {
+            review.assertCustody(context);
+            const data = selected(context, this.#scope);
+            if (data.corrected !== this.#corrected || data.data.authority_sha256 !== this.#authority
+                || !data.data.bytes.equals(this.#bytes))
+                refuse("accepted_review_changed");
+        });
+    }
+    revalidate(context) {
+        const review = this.#review;
+        withMemoryCustodySnapshot(context, () => { review.revalidate(context); this.assertCustody(context); });
     }
-    revalidate(context) { this.#review.revalidate(context); this.assertCustody(context); }
 }
-/** Productive terminal entry awaiting the complete six-stage registry. Opens
- * only after historical review proof; no provider dispatch or Git mutation.
+/** Shared terminal entry for registered Memory flows. Opens only after
+ * historical review proof; no provider dispatch or Git mutation.
  * Terminal settlement must separately prove integration and readiness. */
 export function startMemoryFinish(context, input) {
     if (!(input.bytes instanceof Uint8Array) || input.bytes.length > 1024 * 1024)
         refuse("invalid_input_bytes");
     const bundle = readFlowRunExecutionBundle(context, input);
-    if (!bundle || bundle.descriptor.descriptor.id !== "mb-init" || !bundle.descriptor.descriptor.terminal_stages.includes("finish")
+    if (!bundle || !["mb-init", "mb-upgrade"].includes(bundle.descriptor.descriptor.id) || !bundle.descriptor.descriptor.terminal_stages.includes("finish")
         || bundle.descriptor.successor("review", "accepted") !== "finish")
         refuse("registered_memory_bundle_required");
     const project = requireProjectByRoot(context, resolveProjectRoot(input.projectRoot)), scope = { projectId: project.id, runId: input.runId };
@@ -107,7 +121,7 @@ export function replayAcceptedMemoryFinish(context, input) {
     if (context.db.isOwnedWriteTransaction?.())
         refuse("preparation_outside_writer_required");
     const bundle = readFlowRunExecutionBundle(context, input);
-    if (!bundle || bundle.descriptor.descriptor.id !== "mb-init")
+    if (!bundle || !["mb-init", "mb-upgrade"].includes(bundle.descriptor.descriptor.id))
         refuse("registered_memory_bundle_required");
     const project = requireProjectByRoot(context, resolveProjectRoot(input.projectRoot)), scope = { projectId: project.id, runId: input.runId };
     const review = PreparedMemoryFinishReview.prepare(context, { scope, bundle });
@@ -149,7 +163,7 @@ export function settleAcceptedMemoryRun(context, input) {
     if (context.db.isOwnedWriteTransaction?.())
         refuse("preparation_outside_writer_required");
     const bundle = readFlowRunExecutionBundle(context, input);
-    if (!bundle || bundle.descriptor.descriptor.id !== "mb-init"
+    if (!bundle || !["mb-init", "mb-upgrade"].includes(bundle.descriptor.descriptor.id)
         || !bundle.descriptor.descriptor.terminal_stages.includes("finish"))
         refuse("registered_memory_bundle_required");
     const project = requireProjectByRoot(context, resolveProjectRoot(input.projectRoot)), scope = { projectId: project.id, runId: input.runId };
@@ -175,14 +189,14 @@ export function settleAcceptedMemoryRun(context, input) {
  * Publication has its own exact receipt and does not accept the Stage. */
 export function registerMemoryFinishEvidenceFromStage(context, input) {
     const bundle = readFlowRunExecutionBundle(context, input);
-    if (!bundle || bundle.descriptor.descriptor.id !== "mb-init")
+    if (!bundle || !["mb-init", "mb-upgrade"].includes(bundle.descriptor.descriptor.id))
         refuse("registered_memory_bundle_required");
     const project = requireProjectByRoot(context, resolveProjectRoot(input.projectRoot));
     return PreparedMemoryFinishEvidence.prepare(context, { scope: { projectId: project.id, runId: input.runId }, bundle }).register(context);
 }
 export function integrateMemoryFinishFromStage(context, input) {
     const bundle = readFlowRunExecutionBundle(context, input);
-    if (!bundle || bundle.descriptor.descriptor.id !== "mb-init")
+    if (!bundle || !["mb-init", "mb-upgrade"].includes(bundle.descriptor.descriptor.id))
         refuse("registered_memory_bundle_required");
     const project = requireProjectByRoot(context, resolveProjectRoot(input.projectRoot));
     return integrateMemoryFinish(context, { scope: { projectId: project.id, runId: input.runId }, bundle });
@@ -196,7 +210,7 @@ export function finishMemoryFinish(context, input) {
     if (context.db.isOwnedWriteTransaction?.())
         refuse("preparation_outside_writer_required");
     const bundle = readFlowRunExecutionBundle(context, input);
-    if (!bundle || bundle.descriptor.descriptor.id !== "mb-init")
+    if (!bundle || !["mb-init", "mb-upgrade"].includes(bundle.descriptor.descriptor.id))
         refuse("registered_memory_bundle_required");
     const project = requireProjectByRoot(context, resolveProjectRoot(input.projectRoot)), scope = { projectId: project.id, runId: input.runId };
     const run = assertPreparedRunBundleSqlAuthority(context, scope, bundle);