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

package/dist/services/memory-stage-dispatch.js

@@ -6,6 +6,9 @@ import { startMemoryVerification, finishMemoryVerification } from "./memory-veri
 import { startMemoryReview, finishMemoryReview } from "./memory-review-handler.js";
 import { startMemoryFinish, finishMemoryFinish } from "./memory-finish-handler.js";
 import { memoryInitHandlerIdentities as ids } from "../domain/stage-handler-identities.js";
+import { memoryUpgradeHandlerIdentities as upgradeIds } from "../domain/stage-handler-identities.js";
+import { startMemoryUpgradeAnalysis, finishMemoryUpgradeAnalysis } from "./memory-upgrade-analysis-handler.js";
+import { parseMemoryWorkResultProposal } from "./memory-work-result-json.js";
 // Engine-owned functions only; this is dispatch, not descriptor admission.
 export const memoryInitStageHandlers = Object.freeze({
     preflight: Object.freeze({ ...ids.preflight, entry: startMemoryPreflight, finish: finishMemoryPreflight }),
@@ -15,6 +18,18 @@ export const memoryInitStageHandlers = Object.freeze({
     review: Object.freeze({ ...ids.review, entry: startMemoryReview, finish: finishMemoryReview }),
     finish: Object.freeze({ ...ids.finish, entry: startMemoryFinish, finish: finishMemoryFinish })
 });
+export const memoryUpgradeStageHandlers = Object.freeze({
+    preflight: Object.freeze({ ...upgradeIds.preflight,
+        entry: (context, input) => startMemoryUpgradeAnalysis(context, { ...input, stage: "preflight" }),
+        finish: (context, input) => finishMemoryUpgradeAnalysis(context, { ...input, stage: "preflight" }) }),
+    "diff-analysis": Object.freeze({ ...upgradeIds["diff-analysis"],
+        entry: (context, input) => startMemoryUpgradeAnalysis(context, { ...input, stage: "diff-analysis" }),
+        finish: (context, input) => finishMemoryUpgradeAnalysis(context, { ...input, stage: "diff-analysis" }) }),
+    upgrade: Object.freeze({ ...upgradeIds.upgrade, entry: startMemoryComposition, finish: finishMemoryComposition }),
+    verify: Object.freeze({ ...upgradeIds.verify, entry: startMemoryVerification, finish: finishMemoryVerification }),
+    review: Object.freeze({ ...upgradeIds.review, entry: startMemoryReview, finish: finishMemoryReview }),
+    finish: Object.freeze({ ...upgradeIds.finish, entry: startMemoryFinish, finish: finishMemoryFinish })
+});
 function stage(input) {
     if (!Object.hasOwn(memoryInitStageHandlers, input.stage) || !(input.bytes instanceof Uint8Array) || input.bytes.length > 1024 * 1024)
         throw new AppError("memory_stage_dispatch_invalid", "Memory stage dispatch requires a bounded declared stage input", 2, { effect: "no_effect", phase: "prepare" });
@@ -24,5 +39,27 @@ export function startMemoryStage(context, input) {
     return memoryInitStageHandlers[stage(input)].entry(context, input);
 }
 export function finishMemoryStage(context, input) {
-    return memoryInitStageHandlers[stage(input)].finish(context, input);
+    const selected = stage(input);
+    validateFinishProposal(input.bytes);
+    return memoryInitStageHandlers[selected].finish(context, input);
+}
+// Syntax belongs to the submitted proposal, not retained composition/receipt
+// custody. Validate it before any stage-specific projection parses the bytes.
+function validateFinishProposal(bytes) {
+    if (!bytes.length)
+        throw new AppError("memory_stage_dispatch_invalid", "Memory finish requires a nonempty result proposal", 2, { effect: "no_effect", phase: "prepare" });
+    parseMemoryWorkResultProposal(bytes, "memory_stage_result_invalid");
+}
+function upgradeStage(input) {
+    if (!Object.hasOwn(memoryUpgradeStageHandlers, input.stage) || !(input.bytes instanceof Uint8Array) || input.bytes.length > 1024 * 1024)
+        throw new AppError("memory_stage_dispatch_invalid", "Memory stage dispatch requires a bounded declared stage input", 2, { effect: "no_effect", phase: "prepare" });
+    return input.stage;
+}
+export function startMemoryUpgradeStage(context, input) {
+    return memoryUpgradeStageHandlers[upgradeStage(input)].entry(context, input);
+}
+export function finishMemoryUpgradeStage(context, input) {
+    const selected = upgradeStage(input);
+    validateFinishProposal(input.bytes);
+    return memoryUpgradeStageHandlers[selected].finish(context, input);
 }

package/dist/services/memory-stage-results.js

@@ -3,19 +3,38 @@ import { createHash } from "node:crypto";
 import { Ajv2020 } from "ajv/dist/2020.js";
 import { AppError } from "../shared/errors.js";
 import { hybridDigest } from "./hybrid-contracts.js";
-import { validateMemoryCompositionGraph } from "./memory-composition-graph.js";
+import { validateMemoryCompositionGraph, memoryCompositionOutputAllowed } from "./memory-composition-graph.js";
 import { FrozenGenericExecution } from "./generic-execution.js";
-const stages = ["preflight", "discover", "compose", "verify", "review", "finish"];
+const memoryStages = {
+    "mb-init": ["preflight", "discover", "compose", "verify", "review", "finish"],
+    "mb-upgrade": ["preflight", "diff-analysis", "upgrade", "verify", "review", "finish"]
+};
 const sha = (value) => /^[a-f0-9]{64}$/.test(value);
-function refuse(reason) {
-    throw new AppError("memory_stage_result_invalid", "Memory stage result is not bound to its retained input", 2, { reason, phase: "prepare", effect: "no_effect" });
+// Proposal relationships/scopes can be corrected before any acceptance or Work
+// allocation. Missing/foreign runtime bindings and identities remain fatal.
+const correctableProposalReasons = new Set([
+    "unsafe_reference_path",
+    "foreign_predecessor_reference", "duplicate_unit", "changed_unit_coverage", "duplicate_finding", "foreign_finding_unit",
+    "duplicate_fact", "foreign_fact_unit", "foreign_unit_reference", "unobserved_or_changed_source",
+    "duplicate_preservation_invariant", "weakened_upgrade_mode", "changed_preservation_invariants", "missing_applicable_unit_preservation",
+    "duplicate_preservation_assessment", "incomplete_preservation_assessment", "foreign_preservation_unit", "unreviewable_preservation_unit", "unapproved_composition_profile",
+    "unresolved_composition_applicability", "duplicate_composition_work", "unknown_composition_dependency", "duplicate_composition_scope",
+    "unbounded_composition_write", "foreign_composition_write", "canonical_composition_write", "private_composition_write",
+    "authority_composition_write", "foreign_composition_run_write", "cyclic_composition_dependency", "invalid_assembly_membership",
+    "mechanical_unit_cannot_allocate_agent_work", "inapplicable_composition_work", "incomplete_composition_coverage",
+    "assembly_precedes_unit_writers", "unordered_composition_writers", "unordered_composition_read_write"
+]);
+function refuse(reason, details = {}) {
+    throw new AppError("memory_stage_result_invalid", reason === "missing_applicable_unit_preservation"
+        ? "Every applicable upgrade unit requires a source-backed preservation invariant. In preflight add the invariant; in diff-analysis keep the accepted invariants unchanged and assign the planned work to their existing units"
+        : "Memory stage result is not bound to its retained input", 2, { ...details, reason, phase: "prepare", effect: "no_effect" });
 }
-function contained(logical, allowRoot = false) {
+function contained(logical, allowRoot = false, proposal = false) {
     if (allowRoot && logical === ".")
         return;
     if (!logical || path.posix.isAbsolute(logical) || path.win32.isAbsolute(logical) || logical.includes("\\")
         || logical.includes("\0") || logical.split("/").some(segment => !segment || segment === "." || segment === ".."))
-        refuse("unsafe_reference_path");
+        refuse("unsafe_reference_path", { recoverable: proposal });
 }
 export function memorySourceKey(root, logical) { return `${root}\0${logical}`; }
 function unique(values, reason) {
@@ -34,23 +53,36 @@ export class PreparedMemoryStageResult {
     #routes;
     #executionSha256;
     #preflight;
-    constructor(bytes, value, routes, executionSha256, preflight) {
+    #upgradeWritePaths;
+    #mechanicalUnits;
+    #preservationInvariants;
+    #upgradeEvidenceIndex;
+    constructor(bytes, value, routes, executionSha256, preflight, upgradeWritePaths, mechanicalUnits, preservationInvariants, upgradeEvidenceIndex) {
         this.#bytes = Buffer.from(bytes);
         this.#value = structuredClone(value);
         this.#routes = structuredClone(routes);
         this.#executionSha256 = executionSha256;
         this.#preflight = structuredClone(preflight);
+        this.#upgradeWritePaths = upgradeWritePaths ? new Set(upgradeWritePaths) : null;
+        this.#mechanicalUnits = new Set(mechanicalUnits);
+        this.#preservationInvariants = structuredClone(preservationInvariants);
+        this.#upgradeEvidenceIndex = structuredClone(upgradeEvidenceIndex);
         this.sha256 = createHash("sha256").update(bytes).digest("hex");
         Object.freeze(this);
     }
     static prepare(input, flow, binding) {
         try {
-            if (input.byteLength < 1 || input.byteLength > 1024 * 1024 || flow.descriptor.id !== "mb-init"
+            const stages = memoryStages[flow.descriptor.id], upgrade = flow.descriptor.id === "mb-upgrade";
+            if (input.byteLength < 1 || input.byteLength > 1024 * 1024 || !stages
                 || !stages.includes(binding.stage) || !binding.runId || !sha(binding.inputSha256))
                 refuse("invalid_input_binding");
+            if (upgrade && (!binding.upgrade || !["patch", "targeted_minor", "full_migration"].includes(binding.upgrade.minimumMode)))
+                refuse("missing_upgrade_impact_binding");
+            if (binding.upgrade?.evidenceIndex && (binding.upgrade.evidenceIndex.path !== "upgrade-baseline.json" || !sha(binding.upgrade.evidenceIndex.sha256)))
+                refuse("invalid_upgrade_evidence_binding");
             const bytes = Buffer.from(input), value = JSON.parse(new TextDecoder("utf-8", { fatal: true }).decode(bytes));
             const schema = JSON.parse(new TextDecoder("utf-8", { fatal: true }).decode(flow.stageBlob(binding.stage, "result_schema")));
-            if (schema.$id !== `dd-flow/mb-init-${binding.stage}-result@1`)
+            if (schema.$id !== (upgrade ? "dd-flow/mb-upgrade-stage-result@1" : `dd-flow/mb-init-${binding.stage}-result@1`))
                 refuse("invalid_result_schema");
             const validate = new Ajv2020({ strict: true, strictRequired: false, validateFormats: false }).compile(schema);
             if (!validate(value))
@@ -71,7 +103,7 @@ export class PreparedMemoryStageResult {
                 refuse("foreign_predecessor_reference");
             const units = unique(value.units.map(unit => unit.id), "duplicate_unit");
             if (binding.unitIds === null) {
-                if (!["preflight", "discover"].includes(binding.stage))
+                if (!["preflight", upgrade ? "diff-analysis" : "discover"].includes(binding.stage))
                     refuse("missing_unit_inventory");
             }
             else {
@@ -97,11 +129,11 @@ export class PreparedMemoryStageResult {
                     return;
                 const record = node;
                 if (typeof record.unit_id === "string" && !units.has(record.unit_id))
-                    refuse("foreign_unit_reference");
+                    refuse("foreign_unit_reference", { unit_id: record.unit_id.slice(0, 256) });
                 if (Array.isArray(record.unit_ids) && record.unit_ids.some(id => typeof id !== "string" || !units.has(id)))
-                    refuse("foreign_unit_reference");
+                    refuse("foreign_unit_reference", { unit_ids: record.unit_ids.filter(id => typeof id !== "string" || !units.has(id)).slice(0, 8).map(id => String(id).slice(0, 256)) });
                 if (typeof record.path === "string" && (typeof record.root === "string" || typeof record.sha256 === "string"))
-                    contained(record.path, typeof record.root === "string" && record.sha256 === undefined);
+                    contained(record.path, typeof record.root === "string" && record.sha256 === undefined, true);
                 if (typeof record.root === "string" && typeof record.path === "string" && typeof record.sha256 === "string") {
                     const key = memorySourceKey(record.root, record.path);
                     if (binding.sources.get(key) !== record.sha256 && !(role === "evidence" && binding.historicalEvidence?.has(`${key}\0${record.sha256}`)))
@@ -110,15 +142,60 @@ export class PreparedMemoryStageResult {
                 Object.entries(record).forEach(([key, child]) => visit(child, key === "evidence" || key === "artifacts" ? key : role));
             };
             visit(value);
+            if (upgrade) {
+                const invariants = value.details.preservation_invariants;
+                if (invariants)
+                    unique(invariants.map(item => String(item.id)), "duplicate_preservation_invariant");
+                const expected = binding.upgrade.preservationInvariants;
+                if (binding.stage !== "preflight" && !expected)
+                    refuse("missing_upgrade_preservation_binding");
+                if (binding.stage === "diff-analysis") {
+                    const modes = ["patch", "targeted_minor", "full_migration"];
+                    if (modes.indexOf(String(value.details.mode)) < modes.indexOf(binding.upgrade.minimumMode))
+                        refuse("weakened_upgrade_mode");
+                    const ordered = (items) => [...items].sort((a, b) => String(a.id).localeCompare(String(b.id), "en"));
+                    if (hybridDigest(ordered(invariants)) !== hybridDigest(ordered(expected)))
+                        refuse("changed_preservation_invariants");
+                    for (const change of value.details.path_map) {
+                        if (change.from !== null)
+                            contained(change.from, false, true);
+                        if (change.to !== null)
+                            contained(change.to, false, true);
+                    }
+                }
+                const unreviewable = (invariants ?? expected ?? []).filter(item => !value.units.some(unit => unit.id === item.unit_id && unit.applicability === "applicable"));
+                if (unreviewable.length)
+                    refuse("unreviewable_preservation_unit", {
+                        unit_ids: [...new Set(unreviewable.map(item => item.unit_id))].slice(0, 8),
+                        invariant_ids: unreviewable.map(item => item.id).slice(0, 8),
+                        hint: binding.stage === "preflight"
+                            ? "Each preservation criterion needs an applicable assessment unit. Bind a no-migration criterion to an applicable provenance/readiness unit; this does not require migration Work or an apply receipt."
+                            : "Keep each retained preservation criterion assigned to an applicable assessment unit. Correct proposed applicability, not accepted invariant identities or predecessor bytes."
+                    });
+                if (binding.stage === "preflight" || binding.stage === "diff-analysis") {
+                    const uncovered = value.units.filter(unit => unit.applicability === "applicable" && !invariants.some(item => item.unit_id === unit.id));
+                    if (uncovered.length)
+                        refuse("missing_applicable_unit_preservation", { unit_ids: uncovered.map(unit => unit.id).slice(0, 8) });
+                }
+                if (binding.stage === "verify") {
+                    const assessments = value.details.preservation_assessments;
+                    const selected = unique(assessments.map(item => item.invariant_id), "duplicate_preservation_assessment");
+                    if (selected.size !== expected.length || expected.some(item => !selected.has(String(item.id))))
+                        refuse("incomplete_preservation_assessment");
+                    if (assessments.some(item => expected.find(original => original.id === item.invariant_id)?.unit_id !== item.unit_id))
+                        refuse("foreign_preservation_unit");
+                }
+            }
             let routes = null;
-            if (binding.stage === "compose") {
-                validateMemoryCompositionGraph(value);
+            const authoringPaths = upgrade && binding.stage === "upgrade" ? binding.upgrade?.authoringPaths : undefined;
+            if (binding.stage === "compose" || authoringPaths) {
+                validateMemoryCompositionGraph(value, authoringPaths, authoringPaths ? binding.upgrade?.mechanicalUnits : undefined);
                 if (!(binding.execution instanceof FrozenGenericExecution) || binding.execution.settings.flow_id !== flow.descriptor.id
                     || binding.execution.settings.descriptor_sha256 !== flow.sha256 || binding.execution.sha256 !== binding.executionSha256)
                     refuse("missing_or_foreign_composition_execution");
                 const works = value.details.works;
                 try {
-                    routes = works.map(work => ({ key: work.key, execution: binding.execution.work("compose", work.profile_id ?? undefined) }));
+                    routes = works.map(work => ({ key: work.key, execution: binding.execution.work(binding.stage, work.profile_id ?? undefined) }));
                 }
                 catch {
                     refuse("unapproved_composition_profile");
@@ -141,16 +218,29 @@ export class PreparedMemoryStageResult {
                     }
                 }
             }
-            return new PreparedMemoryStageResult(bytes, value, routes, routes ? binding.executionSha256 : null, binding.preflight ?? null);
+            return new PreparedMemoryStageResult(bytes, value, routes, routes ? binding.executionSha256 : null, binding.preflight ?? null, authoringPaths ? new Set([...authoringPaths.values()].flatMap(paths => [...paths])) : null, authoringPaths ? binding.upgrade?.mechanicalUnits ?? new Set() : new Set(), upgrade ? binding.upgrade?.preservationInvariants ?? [] : [], upgrade ? binding.upgrade?.evidenceIndex ?? null : null);
         }
         catch (error) {
-            if (error instanceof AppError && error.code === "memory_stage_result_invalid")
+            if (error instanceof AppError && error.code === "memory_stage_result_invalid") {
+                if (correctableProposalReasons.has(String(error.details.reason)) && error.details.recoverable !== false)
+                    throw new AppError(error.code, `Correct the proposed result (${error.details.reason}) without changing retained RUN, predecessor or execution bindings`, error.exitCode, { ...error.details, recoverable: true, result_sha256: createHash("sha256").update(input).digest("hex") });
                 throw error;
+            }
             return refuse("invalid_result_or_binding");
         }
     }
     bytes() { return Buffer.from(this.#bytes); }
+    mechanicalUnitIds() { return new Set(this.#mechanicalUnits); }
+    preservationInvariants() { return structuredClone(this.#preservationInvariants); }
     value() { return structuredClone(this.#value); }
+    authoringStage() {
+        if (!this.#routes || !["compose", "upgrade"].includes(this.#value.stage))
+            refuse("not_a_composition_result");
+        return this.#value.stage;
+    }
+    allowsCompositionOutput(root, logical) {
+        return memoryCompositionOutputAllowed(logical, root === "workspace" && this.#upgradeWritePaths ? this.#upgradeWritePaths : undefined);
+    }
     compositionRoutes() {
         if (!this.#routes)
             refuse("not_a_composition_result");
@@ -161,8 +251,7 @@ export class PreparedMemoryStageResult {
      * this result's predecessor/source custody before passing the batch to its writer.
      */
     compositionBatch(binding) {
-        if (!this.#routes || this.#value.stage !== "compose")
-            refuse("not_a_composition_result");
+        const stage = this.authoringStage();
         // Registration assigns unfinished authoring; only final acceptance attests
         // settled outputs. A repairable blueprint is not a blocked dispatch.
         if (this.#value.outcome === "blocked")
@@ -184,12 +273,14 @@ export class PreparedMemoryStageResult {
                 if (typeof work.task !== "string" || !work.task.trim() || work.task.length > 16384)
                     refuse("missing_composition_work_task");
                 const packet = { schema_id: "dd-flow/memory-composition-work-packet@1", run_id: binding.runId,
-                    stage: "compose", key: work.key, role: work.role, unit_ids: work.unit_ids,
+                    stage, key: work.key, role: work.role, unit_ids: work.unit_ids,
                     task: work.task, depends_on: work.depends_on, result_schema: binding.resultSchema,
                     read_scopes: work.read_scopes, write_scopes: work.write_scopes,
                     compose_result_sha256: this.sha256, compose_input_sha256: binding.inputSha256,
                     execution_sha256: binding.executionSha256, predecessors: this.#value.predecessors };
-                const scopedPacket = { ...packet, ...(this.#preflight ? { preflight: structuredClone(this.#preflight) } : {}) };
+                const scopedPacket = { ...packet, ...(this.#preflight ? { preflight: structuredClone(this.#preflight) } : {}),
+                    ...(this.#upgradeEvidenceIndex ? { upgrade_baseline: { root: "run", ...this.#upgradeEvidenceIndex },
+                        preservation_invariants: this.#preservationInvariants.filter(item => work.unit_ids.includes(String(item.unit_id))) } : {}) };
                 return { key: work.key, task: work.task, depends_on: [...work.depends_on],
                     launch_policy: "fresh_agent_required", result_schema: binding.resultSchema,
                     payload: structuredClone({ memory_composition: { ...scopedPacket, packet_sha256: hybridDigest(scopedPacket) },

package/dist/services/memory-upgrade-analysis-handler.js

@@ -0,0 +1,243 @@
+import fs from "node:fs";
+import path from "node:path";
+import { createHash } from "node:crypto";
+import { AppError } from "../shared/errors.js";
+import { requireProjectByRoot } from "./projects.js";
+import { resolveProjectRoot } from "../storage/paths.js";
+import { assertPreparedRunBundleSqlAuthority, readFlowRunExecutionBundle } from "./runs.js";
+import { hybridDigest } from "./hybrid-contracts.js";
+import { PreparedMemoryUpgradeBootstrapReadiness, readMemoryUpgradeBootstrapReadiness } from "./memory-upgrade-bootstrap-readiness.js";
+import { readUpgradeStorageReadiness, resolveUpgradeHistoricalScope } from "./memory-upgrade-storage-readiness.js";
+import { PreparedDescriptorStageStart } from "./descriptor-stage-start.js";
+import { PreparedDescriptorStageCoordinator, readDescriptorStageInput } from "./descriptor-stage-coordinator.js";
+import { assertMemoryOrdinaryUpgradeConfigurationCoverage } from "./memory-ordinary-defaults.js";
+import { PreparedDescriptorStageSettlement } from "./descriptor-stage-settlement.js";
+import { PreparedMemoryResultBinding } from "./memory-result-binding.js";
+import { PreparedMemoryStageResult } from "./memory-stage-results.js";
+import { ObservedMemorySources } from "./memory-source-observations.js";
+import { readAcceptedStageData } from "./stage-report-renderer.js";
+import { localEnvironmentAllowed, workspaceGitFiles } from "./workspace-files.js";
+import { validateUpgradePathMap } from "./memory-upgrade-inventory.js";
+import { readMemoryUpgradeEvidence, readIssuedMemoryUpgradeTarget } from "./memory-upgrade-evidence.js";
+function refuse(reason) {
+    throw new AppError("memory_upgrade_analysis_handler_invalid", "Upgrade analysis requires its accepted bootstrap and original project", 2, { reason, effect: "no_effect" });
+}
+function rejectResult(bytes, reason, reference) {
+    const message = reason === "missing_impact_checks" ? "Include every required check from the issued adjacent release-impact chain in the proposed analysis result"
+        : reason === "symlink_source_reference" ? "Cite the issued run upgrade-baseline.json project_link_metadata for link identity, and a selected regular target file for contents; direct symlink sources are not admitted"
+            : reason === "analysis_not_accepted" ? "Accepted analysis cannot carry unresolved major/blocking findings. Represent planned upgrade work in units, path_map and required_checks; for a real blocker use the issued pause command. Do not mark unresolved work resolved merely to pass this gate"
+                : "Correct the result evidence using issued stage inputs and old/target references; controller response views and logs are not admitted evidence";
+    throw new AppError("memory_stage_result_invalid", message, 2, { reason, phase: "prepare", effect: "no_effect", recoverable: true,
+        result_sha256: createHash("sha256").update(bytes).digest("hex"),
+        ...(reference ? { reference: { root: String(reference.root).slice(0, 32), path: String(reference.path).slice(0, 1024) } } : {}) });
+}
+function selected(context, input) {
+    if (!["preflight", "diff-analysis"].includes(input.stage) || !(input.bytes instanceof Uint8Array) || input.bytes.length > 1024 * 1024)
+        refuse("invalid_stage_input");
+    const bundle = readFlowRunExecutionBundle(context, input);
+    if (!bundle || bundle.descriptor.descriptor.id !== "mb-upgrade"
+        || bundle.descriptor.descriptor.entry_stage !== "preflight" || bundle.descriptor.successor("preflight", "accepted") !== "diff-analysis")
+        refuse("registered_upgrade_bundle_required");
+    const project = requireProjectByRoot(context, resolveProjectRoot(input.projectRoot));
+    const scope = { projectId: project.id, runId: input.runId, stage: input.stage };
+    const run = assertPreparedRunBundleSqlAuthority(context, scope, bundle), index = JSON.parse(run.index_json);
+    const frozen = bundle.execution.snapshot().scope;
+    const bootstrapScope = { requestId: frozen.requestId, projectRoot: frozen.projectRoot, workspaceRoot: frozen.workspace };
+    const ready = readMemoryUpgradeBootstrapReadiness(context, bootstrapScope);
+    if (!ready?.hasPreservationBaseline || ready.projectId !== project.id || ready.authority.binding.execution_sha256 !== bundle.execution.sha256)
+        refuse("accepted_upgrade_bootstrap_required");
+    const predecessor = input.stage === "diff-analysis" ? readAcceptedStageData(context, { ...scope, stage: "preflight" }) : null;
+    const authority = hybridDigest(ready.authority);
+    const fence = (writer) => {
+        const current = readMemoryUpgradeBootstrapReadiness(writer, bootstrapScope);
+        if (!current || hybridDigest(current.authority) !== authority
+            || predecessor && readAcceptedStageData(writer, { ...scope, stage: "preflight" }).authority_sha256 !== predecessor.authority_sha256)
+            refuse("analysis_dependencies_changed");
+    };
+    return { bundle, scope, bootstrapScope, predecessor, fence, accepted: index.stage_runs.find((stage) => stage.stage === input.stage)?.status === "done" };
+}
+/** Agent references select current observations from the CLI inventory, not
+ * arbitrary local files. Canonical/receipt inputs come from the retained RUN
+ * bundle; old document evidence is independently supplied by the SQL binding.
+ */
+function sources(context, input, state) {
+    let value;
+    try {
+        value = JSON.parse(new TextDecoder("utf-8", { fatal: true }).decode(input.bytes));
+    }
+    catch {
+        return rejectResult(input.bytes, "invalid_result_json");
+    }
+    const storage = readUpgradeStorageReadiness(context, state.bootstrapScope);
+    if (!storage?.selection)
+        refuse("retained_selection_required");
+    const run = assertPreparedRunBundleSqlAuthority(context, state.scope, state.bundle);
+    const workspace = run.workspace_root ?? run.project_root;
+    const projectIsWorkspace = workspace === run.project_root;
+    const allowed = new Set([...(workspaceGitFiles(workspace, ["--cached", "--others", "--exclude-standard"]) ?? []),
+        ...storage.selection.payload.current.inventory.inventory.entries.filter(entry => entry.current?.kind === "file" || entry.target).map(entry => `.memory-bank/${entry.path}`)]);
+    const allowedRun = new Set(state.bundle.manifest.inventory.map(entry => `execution-bundle/${entry.path}`));
+    const oldEvidence = readMemoryUpgradeEvidence(context, state.bootstrapScope);
+    const oldRunHashes = new Map([[oldEvidence.reference.path, oldEvidence.reference.sha256],
+        ...oldEvidence.index.entries.map(entry => [entry.retained.path, entry.retained.sha256])]);
+    const target = readIssuedMemoryUpgradeTarget(context, state.bootstrapScope, state.scope.projectId);
+    if (target)
+        for (const ref of [target.reference, ...target.index.entries.map(entry => entry.retained)]) {
+            allowedRun.add(ref.path);
+            oldRunHashes.set(ref.path, ref.sha256);
+        }
+    const inputStage = JSON.parse(run.index_json).stage_runs.find((stage) => stage.stage === state.scope.stage);
+    const inputPath = `${state.bundle.descriptor.stage(state.scope.stage).directory}/stage-input.json`;
+    if (typeof inputStage?.input_sha256 === "string")
+        allowedRun.add(inputPath);
+    allowedRun.add(oldEvidence.reference.path);
+    for (const entry of oldEvidence.index.entries)
+        allowedRun.add(entry.retained.path);
+    if (state.predecessor)
+        allowedRun.add(state.predecessor.result.path);
+    const position = state.bundle.descriptor.descriptor.stages.findIndex(stage => stage.id === state.scope.stage);
+    for (const stage of state.bundle.descriptor.descriptor.stages.slice(0, position)) {
+        const accepted = readAcceptedStageData(context, { ...state.scope, stage: stage.id });
+        allowedRun.add(accepted.result.path);
+        // Accepted invariants can cite the packet that originally established
+        // their scope. Retain that exact issued input, not arbitrary RUN files.
+        if (typeof accepted.input_sha256 === "string") {
+            const logical = `${stage.directory}/stage-input.json`;
+            allowedRun.add(logical);
+            oldRunHashes.set(logical, accepted.input_sha256);
+        }
+    }
+    const historical = new Set(oldEvidence.index.entries.map(entry => `${entry.source.path}\0${entry.source.sha256}`));
+    const locations = new Map(), pending = [{ value, role: "source" }];
+    let nodes = 0;
+    while (pending.length) {
+        if (++nodes > 100_000)
+            rejectResult(input.bytes, "unbounded_result_tree");
+        const item = pending.pop(), node = item.value;
+        if (Array.isArray(node)) {
+            for (const child of node)
+                pending.push({ value: child, role: item.role });
+            continue;
+        }
+        if (!node || typeof node !== "object")
+            continue;
+        const ref = node;
+        if (typeof ref.root === "string" && typeof ref.path === "string" && typeof ref.sha256 === "string") {
+            if (ref.root === "workspace" || ref.root === "project" && projectIsWorkspace) {
+                if (!allowed.has(ref.path) || ref.path.split("/").some(part => [".git", "node_modules", ".dd-flow"].includes(part) || !localEnvironmentAllowed(part)))
+                    rejectResult(input.bytes, "unselected_project_source", ref);
+                if (!(item.role === "evidence" && historical.has(`${ref.path}\0${ref.sha256}`))) {
+                    // Historical retained bytes need not exist in today's tree.
+                    let parent = workspace;
+                    for (const part of ref.path.split("/").slice(0, -1)) {
+                        parent = path.join(parent, part);
+                        if (!fs.lstatSync(parent).isDirectory())
+                            rejectResult(input.bytes, "symlink_source_reference", ref);
+                    }
+                    if (fs.lstatSync(path.join(workspace, ref.path), { throwIfNoEntry: false })?.isSymbolicLink())
+                        rejectResult(input.bytes, "symlink_source_reference", ref);
+                }
+            }
+            else if (ref.root === "run") {
+                if (!allowedRun.has(ref.path))
+                    rejectResult(input.bytes, "unselected_run_source", ref);
+                if (ref.path === inputPath && ref.sha256 !== inputStage?.input_sha256)
+                    rejectResult(input.bytes, "changed_stage_input", ref);
+                if (oldRunHashes.has(ref.path) && oldRunHashes.get(ref.path) !== ref.sha256)
+                    rejectResult(input.bytes, "changed_old_evidence", ref);
+            }
+            else
+                rejectResult(input.bytes, "unselected_source_root", ref);
+            // The accepted old tree remains evidence after a canonical path is
+            // replaced or archived. It never qualifies a current output artifact.
+            if (!(item.role === "evidence" && ["workspace", "project"].includes(ref.root) && historical.has(`${ref.path}\0${ref.sha256}`)))
+                locations.set(`${ref.root}\0${ref.path}`, { root: ref.root, path: ref.path });
+        }
+        for (const [key, child] of Object.entries(ref))
+            pending.push({ value: child, role: key === "evidence" || key === "artifacts" ? key : item.role });
+    }
+    return ObservedMemorySources.capture({ workspace, ...(projectIsWorkspace ? { project: workspace } : {}), run: run.run_root ?? run.run_dir }, [...locations.values()]);
+}
+/** Shared upgrade observation path for registered authoring/review consumers.
+ * The source witness grants no Stage, Work or canonical-write authority. */
+export function captureMemoryUpgradeSources(context, bundle, stage, bytes) {
+    if (bundle.descriptor.descriptor.id !== "mb-upgrade" || !(bytes instanceof Uint8Array) || bytes.length > 1024 * 1024)
+        refuse("invalid_stage_input");
+    bundle.descriptor.stage(stage);
+    const frozen = bundle.execution.snapshot().scope;
+    const bootstrapScope = { requestId: frozen.requestId, projectRoot: frozen.projectRoot, workspaceRoot: frozen.workspace };
+    const { projectId } = resolveUpgradeHistoricalScope(context, bootstrapScope);
+    const scope = { projectId, runId: bundle.manifest.run_id, stage };
+    const ready = readMemoryUpgradeBootstrapReadiness(context, bootstrapScope);
+    if (!ready?.hasPreservationBaseline || ready.projectId !== projectId || ready.authority.binding.execution_sha256 !== bundle.execution.sha256)
+        refuse("accepted_upgrade_bootstrap_required");
+    const edges = bundle.descriptor.descriptor.edges.filter(edge => edge.to === stage && edge.on === "accepted");
+    if (edges.length !== (stage === bundle.descriptor.descriptor.entry_stage ? 0 : 1))
+        refuse("invalid_stage_predecessor");
+    const predecessor = edges.length ? readAcceptedStageData(context, { ...scope, stage: edges[0].from }) : null;
+    return sources(context, { bytes }, { bundle, scope, bootstrapScope, predecessor });
+}
+/** Upgrade analysis uses the registered six-stage group. Generic lifecycle
+ * owns Work, prompts and dispatch; RUN admission still owns bootstrap readiness.
+ */
+export function startMemoryUpgradeAnalysis(context, input) {
+    const state = selected(context, input);
+    if (state.accepted)
+        refuse("use_accepted_finish_replay");
+    PreparedMemoryUpgradeBootstrapReadiness.assertForRetainedRun(context, state.bundle);
+    const start = PreparedDescriptorStageStart.prepare(context, input);
+    const stage = start.apply(context, state.fence);
+    const coordinator = PreparedDescriptorStageCoordinator.prepare(context, input);
+    PreparedMemoryUpgradeBootstrapReadiness.assertForRetainedRun(context, state.bundle);
+    return { ...stage, ...coordinator.apply(context, state.fence) };
+}
+export function finishMemoryUpgradeAnalysis(context, input) {
+    const state = selected(context, input);
+    if (state.accepted) {
+        // Historical acknowledgement must not reinterpret old artifacts after the
+        // upgrade has intentionally changed them. SQL settlement owns acceptance.
+        const binding = PreparedMemoryResultBinding.prepare(context, { ...state.scope, flow: state.bundle.descriptor,
+            execution: state.bundle.execution, bundle: state.bundle, sources: ObservedMemorySources.capture({}, []), acceptedReplay: true });
+        if (!binding.acceptedBytes()?.equals(input.bytes))
+            refuse("accepted_result_changed");
+        const settlement = PreparedDescriptorStageSettlement.prepare(context, input);
+        return settlement.apply(context, writer => { state.fence(writer); binding.assertCustody(writer); });
+    }
+    const observed = sources(context, input, state);
+    const binding = PreparedMemoryResultBinding.prepare(context, { ...state.scope, flow: state.bundle.descriptor,
+        execution: state.bundle.execution, bundle: state.bundle, sources: observed, acceptedReplay: state.accepted });
+    const accepted = binding.acceptedBytes();
+    if (accepted && !accepted.equals(input.bytes))
+        refuse("accepted_result_changed");
+    const result = PreparedMemoryStageResult.prepare(input.bytes, state.bundle.descriptor, binding.binding()), value = result.value();
+    if (value.outcome !== "accepted" || value.findings.some(finding => finding.severity !== "minor" && finding.status !== "resolved"))
+        rejectResult(input.bytes, "analysis_not_accepted");
+    const details = value.details;
+    if (input.stage === "diff-analysis") {
+        const defaults = readDescriptorStageInput(context, state.scope, state.bundle).input.ordinary_defaults;
+        if (defaults) {
+            assertMemoryOrdinaryUpgradeConfigurationCoverage(value, defaults);
+            if (defaults.missing.length && !context.db.get("SELECT 1 FROM audit_events WHERE project_id=? AND event_type='flow_run.stage_resumed' AND json_extract(payload_json,'$.run_id')=? AND json_extract(payload_json,'$.stage')='diff-analysis' LIMIT 1", [state.scope.projectId, state.scope.runId])) {
+                throw new AppError("memory_stage_result_invalid", "Resolve the ordinary configuration choice through the existing diff-analysis pause/answer path before accepting the upgrade plan", 2, { phase: "prepare", effect: "no_effect", recoverable: true, reason: "ordinary_configuration_choice_required", missing: defaults.missing });
+            }
+        }
+        const storage = readUpgradeStorageReadiness(context, state.bootstrapScope);
+        const checks = details.required_checks;
+        if (!storage?.selection || storage.selection.payload.impact.chain.steps.some(step => !Array.isArray(step.required_checks)
+            || step.required_checks.some(check => typeof check !== "string" || !checks.includes(check))))
+            rejectResult(input.bytes, "missing_impact_checks");
+        try {
+            validateUpgradePathMap(storage.selection.payload.current.inventory.inventory, details.path_map);
+        }
+        catch (error) {
+            if (!(error instanceof AppError) || error.code !== "upgrade_inventory_invalid")
+                throw error;
+            throw new AppError("memory_stage_result_invalid", "Correct the proposed upgrade path map before it becomes an immutable accepted plan", 2, { reason: "invalid_upgrade_path_map", cause: error.details.reason, pointer: "/details/path_map", phase: "prepare", effect: "no_effect",
+                recoverable: true, result_sha256: result.sha256 });
+        }
+    }
+    const settlement = PreparedDescriptorStageSettlement.prepare(context, { ...input, bytes: result.bytes() });
+    PreparedMemoryUpgradeBootstrapReadiness.assertForRetainedRun(context, state.bundle);
+    binding.revalidate(context);
+    return settlement.apply(context, writer => { state.fence(writer); binding.assertCustody(writer); });
+}