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

package/dist/services/installed-flow-source.js

@@ -50,7 +50,7 @@ export class PreparedInstalledFlowSource {
     }
     static fromInstalledRelease(home, expectedInstallationSha256, flowId) {
         try {
-            if (!path.isAbsolute(home) || !/^[a-f0-9]{64}$/.test(expectedInstallationSha256) || flowId !== "mb-init")
+            if (!path.isAbsolute(home) || !/^[a-f0-9]{64}$/.test(expectedInstallationSha256) || !["mb-init", "mb-upgrade"].includes(flowId))
                 refuse("invalid_selection");
             const selected = readSetupStatus(home);
             if (!selected.installation || selected.installation_readiness !== "installed")
@@ -120,6 +120,18 @@ export class PreparedInstalledFlowSource {
      * or admit its engine/storage; those remain the bootstrap owner's duties.
      */
     static restoreRetained(input, expectedSha256) {
+        const result = this.restoreRetainedData(input, expectedSha256);
+        try {
+            result.resolveRegisteredFlow();
+            return result;
+        }
+        catch {
+            return refuse("invalid_retained_source");
+        }
+    }
+    /** Data recovery before storage/engine admission. This cannot register a
+     * handler; productive restoration still uses restoreRetained above. */
+    static restoreRetainedData(input, expectedSha256) {
         try {
             if (!input || typeof input !== "object" || Array.isArray(input) || typeof expectedSha256 !== "string"
                 || !/^[a-f0-9]{64}$/.test(expectedSha256))
@@ -132,7 +144,7 @@ export class PreparedInstalledFlowSource {
                 || typeof value.canon.archive_sha256 !== "string" || !/^[a-f0-9]{64}$/.test(value.canon.archive_sha256)
                 || typeof value.canon.version !== "string" || !/^\d+\.\d+\.\d+(?:-[A-Za-z0-9.-]+)?$/.test(value.canon.version)
                 || !value.descriptor || Object.keys(value.descriptor).sort().join() !== "path,sha256"
-                || value.descriptor.path !== "mb-init/flow-descriptor.json" || typeof value.descriptor.sha256 !== "string" || !/^[a-f0-9]{64}$/.test(value.descriptor.sha256)
+                || !["mb-init/flow-descriptor.json", "mb-upgrade/flow-descriptor.json"].includes(value.descriptor.path) || typeof value.descriptor.sha256 !== "string" || !/^[a-f0-9]{64}$/.test(value.descriptor.sha256)
                 || !Array.isArray(value.blobs) || value.blobs.length < 1 || value.blobs.length > 129)
                 refuse("invalid_retained_source");
             const blobs = new Map(), folded = new Set();
@@ -154,10 +166,19 @@ export class PreparedInstalledFlowSource {
             const descriptor = blobs.get(value.descriptor.path);
             if (!descriptor || hash(descriptor) !== value.descriptor.sha256)
                 refuse("retained_source_changed");
-            const result = new PreparedInstalledFlowSource(null, value.installation_sha256, "mb-init", { ...value.descriptor }, { ...value.canon }, blobs);
+            const flowId = value.descriptor.path.startsWith("mb-upgrade/") ? "mb-upgrade" : "mb-init";
+            const declared = JSON.parse(descriptor.toString("utf8"));
+            if (validateHybridShape("flow-descriptor", declared).length || declared.id !== flowId || declared.origin !== "canon")
+                refuse("invalid_retained_source");
+            for (const stage of declared.stages)
+                for (const kind of ["instruction", "result_schema"]) {
+                    const reference = stage[kind], content = blobs.get(reference.path);
+                    if (!content || hash(content) !== reference.sha256)
+                        refuse("retained_source_changed");
+                }
+            const result = new PreparedInstalledFlowSource(null, value.installation_sha256, flowId, { ...value.descriptor }, { ...value.canon }, blobs);
             if (result.sha256 !== expectedSha256)
                 refuse("retained_source_changed");
-            result.resolveRegisteredFlow();
             return result;
         }
         catch (error) {

package/dist/services/lifecycle-invocations.js

@@ -8,16 +8,15 @@ import { AppError, errorRecord } from "../shared/errors.js";
 import { shortEntityReference } from "../shared/entity-references.js";
 import { resolveWorkReference } from "../storage/work-references.js";
 import { commandOption, commandPosition, continuationCommand, lifecycleCommandFromPayload, parseLifecycleCommand, shellSuffixOffset } from "./lifecycle-command.js";
-import { requireProjectByRoot } from "./projects.js";
-import { assertRunMutationAllowed, assertStageSettlementAllowed, assertWorkSettlementAllowed, recoveryGuard, recoveryPacketReceipt } from "./run-recovery.js";
+import { requireProjectByRoot } from "./project-registry.js";
+import { assertRunMutationAllowed, assertStageSettlementAllowed, assertWorkSettlementAllowed, recoveryGuard, recoveryPacketReceipt } from "./run-recovery-guard.js";
 import { readNativeDaemonState, requireManagedDaemonBinding } from "./managed-daemon-binding.js";
 import { managedProcessStatus, processIsAlive, processStartedAt } from "./managed-processes.js";
 import { appendEvent } from "./run-controller-state.js";
-import { recoverCommittedWorkStart } from "./work-registry.js";
 import { observeCommandHook } from "./hooks.js";
 import { runtimeHarness } from "./execution-policy.js";
 import { normalizedPathAlias, resolveContextualPaths } from "./command-context.js";
-import { isRegisteredRepair } from "./repair-intents.js";
+import { isRegisteredRepair } from "./repair-receipt.js";
 import { stageAttempt } from "./stage-work-graph.js";
 import { contextualPathOptionsForLifecycle } from "../cli/command-inputs.js";
 import { canonicalPath } from "../storage/paths.js";
@@ -1930,9 +1929,38 @@ export async function awaitLifecycleInvocation(context, input) {
             return { outcome: JSON.parse(row.outcome_json), replay: true };
         if (row.status === "executing") {
             const scope = JSON.parse(row.scope_json);
+            const parsed = invocation(row.command);
+            if (parsed.operation === "stage_resume" && scope.runId) {
+                input.assertCurrent(scope);
+                const { recoverCommittedStageResume } = await import("./stage-pause.js");
+                const result = recoverCommittedStageResume(context, { id: row.id, projectRoot: scope.projectRoot, runId: scope.runId, generation: scope.generation, stage: commandOption(parsed, "stage") ?? "", workId: commandOption(parsed, "work") ?? "" });
+                if (result) {
+                    const { preparePromptDelivery } = await import("./prompt-delivery.js");
+                    const delivered = preparePromptDelivery(result);
+                    const previousScope = context.env.DD_FLOW_INVOCATION_SCOPE;
+                    context.env.DD_FLOW_INVOCATION_SCOPE = row.scope_json;
+                    try {
+                        bindLifecyclePublishedPacket(context, String(result.worker_prompt_markdown));
+                    }
+                    finally {
+                        if (previousScope === undefined)
+                            delete context.env.DD_FLOW_INVOCATION_SCOPE;
+                        else
+                            context.env.DD_FLOW_INVOCATION_SCOPE = previousScope;
+                    }
+                    const project = requireProjectByRoot(context, scope.projectRoot);
+                    const event = row.event_key ? context.db.get("SELECT id FROM hook_events WHERE project_id = ? AND event_key = ?", [project.id, row.event_key]) : null;
+                    if (event)
+                        observeLifecycleCommand(context, row.command, { project_id: project.id, id: event.id })({ result: delivered });
+                    const outcome = { result: delivered, effect: "committed" };
+                    settleLifecycleInvocation(context, row.id, outcome);
+                    return { outcome, replay: true };
+                }
+            }
             if (invocation(row.command).operation === "work_start" && row.event_key) {
                 input.assertCurrent(scope);
-                const result = recoverCommittedWorkStart(context, row.id, row.event_key, scope.generation);
+                const { recoverCommittedWorkStart } = await import("./work-registry.js");
+                const result = recoverCommittedWorkStart(context, row.id, row.event_key, scope.generation, undefined, input.progress);
                 if (result) {
                     const outcome = { result, effect: "committed" };
                     settleLifecycleInvocation(context, row.id, outcome);

package/dist/services/memory-accepted-composition.js

@@ -35,15 +35,16 @@ export class PreparedAcceptedMemoryComposition {
     }
     static prepare(context, input) {
         const { scope, bundle } = input;
-        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 stage = bundle.descriptor.descriptor.id === "mb-init" ? "compose" : "upgrade";
         const run = assertPreparedRunBundleSqlAuthority(context, scope, bundle), root = readDescriptorRootWork(context, scope, bundle);
-        const registration = selectMemoryCompositionRegistration(context, { ...stageGraphScope(context, scope.projectId, scope.runId, "compose"), stage: "compose", parent_work_id: root.workId });
+        const registration = selectMemoryCompositionRegistration(context, { ...stageGraphScope(context, scope.projectId, scope.runId, stage), stage, parent_work_id: root.workId });
         const blueprint = PreparedMemoryResultBinding.prepareRegisteredComposition(context, { ...scope, flow: bundle.descriptor, execution: bundle.execution, bundle, acceptedReplay: true,
             registrationScope: registration.scope });
         const outputs = PreparedMemoryCompositionAcceptance.prepare(context, { scope: registration.scope, flow: bundle.descriptor, engine: bundle.engine(), binding: blueprint.binding() });
-        const composed = readAcceptedStageData(context, { ...scope, stage: "compose" }), runRoot = run.run_root ?? run.run_dir;
-        const binding = PreparedMemoryResultBinding.prepare(context, { ...scope, stage: "compose", flow: bundle.descriptor, execution: bundle.execution, bundle, acceptedReplay: true,
+        const composed = readAcceptedStageData(context, { ...scope, stage }), runRoot = run.run_root ?? run.run_dir;
+        const binding = PreparedMemoryResultBinding.prepare(context, { ...scope, stage, flow: bundle.descriptor, execution: bundle.execution, bundle, acceptedReplay: true,
             sources: captureMemoryCompositionSources(context, bundle, runRoot, composed.bytes, outputs), historicalEvidence: outputs.historicalEvidence() });
         if (!binding.acceptedBytes()?.equals(composed.bytes))
             refuse("accepted_composition_changed");

package/dist/services/memory-completed-correction-wave.js

@@ -1,9 +1,11 @@
+import { assertMemorySqlCustody } from "./memory-custody-snapshot.js";
 import { AppError } from "../shared/errors.js";
 import { hybridDigest } from "./hybrid-contracts.js";
 import { PreparedRegisteredMemoryCorrections } from "./memory-repair-registration.js";
 import { PreparedRetainedSecondMemoryRepairs } from "./memory-retained-second-repairs.js";
 import { PreparedSettledMemoryRepair } from "./memory-repair-history.js";
 import { PreparedMemoryRepairWorkspace } from "./memory-repair-workspace.js";
+import { isCompletedMemoryRepairClaim } from "./memory-repair-work-results.js";
 import { reviewSourcePaths } from "./review-copy.js";
 import { readAcceptedStageData } from "./stage-report-renderer.js";
 const token = Symbol("completed-memory-correction-wave");
@@ -41,8 +43,7 @@ export function memoryCorrectionAffectedUnits(units, repairs, composition = [])
     const affected = new Set(), changed = new Set();
     for (const repair of repairs) {
         if (!repair || !Array.isArray(repair.unit_ids) || !repair.unit_ids.length || new Set(repair.unit_ids).size !== repair.unit_ids.length
-            || repair.unit_ids.some((id) => !applicable.has(id)) || repair.result?.outcome !== "accepted"
-            || !Array.isArray(repair.result.changes) || !repair.result.changes.length)
+            || repair.unit_ids.some((id) => !applicable.has(id)) || !isCompletedMemoryRepairClaim(repair.result))
             refuse("invalid_settled_repair_projection");
         for (const id of repair.unit_ids)
             affected.add(id);
@@ -138,6 +139,7 @@ const nonMemory = (entry) => entry.path !== ".memory-bank" && !entry.path.starts
  * review. Reconstruction starts at independently retained first-wave state;
  * neither current files nor a second writer's claimed before-view are anchors. */
 export class PreparedHistoricalSecondMemoryCorrectionWave {
+    #custodyKey = {};
     static isPrepared(value) {
         return typeof value === "object" && value !== null && #registration in value;
     }
@@ -167,11 +169,11 @@ export class PreparedHistoricalSecondMemoryCorrectionWave {
         for (const history of histories) {
             if (!prefixes.has(hybridDigest(history.before().entries())))
                 refuse("unexplained_historical_input_view");
-            baseline = baseline.composeSettledDelta(history.before(), history.after());
+            baseline = baseline.composeSettledDelta(history.before(), history.after(), history.result().outcome);
             prefixes.add(hybridDigest(baseline.entries()));
         }
         const batch = registration.batch(), receipt = registration.receipt(), first = registration.initialInputView();
-        const compose = readAcceptedStageData(context, { ...input.scope, stage: "compose" });
+        const compose = readAcceptedStageData(context, { ...input.scope, stage: input.bundle.descriptor.descriptor.id === "mb-upgrade" ? "upgrade" : "compose" });
         const affected = memoryCorrectionAffectedUnits(memoryCorrectionCurrentUnits(first.unit_inventory, first.assignments), histories.map(history => ({ result: history.result(),
             unit_ids: batch.works.find(item => receipt.work_ids[item.key] === history.workId).payload.memory_repair.unit_ids })), JSON.parse(compose.bytes.toString("utf8")).details.works);
         const prepared = new PreparedHistoricalSecondMemoryCorrectionWave(historicalToken, registration, selected, histories, baseline, affected);
@@ -189,10 +191,13 @@ export class PreparedHistoricalSecondMemoryCorrectionWave {
             unit_ids: batch.works.find(item => receipt.work_ids[item.key] === history.workId).payload.memory_repair.unit_ids }));
     }
     assertCustody(context) {
-        if (hybridDigest(selection(context, this.#registration)) !== hybridDigest(this.#selected))
-            refuse("historical_second_graph_changed");
-        for (const history of this.#histories)
-            history.assertCustody(context);
+        const registration = this.#registration;
+        assertMemorySqlCustody(context, this.#custodyKey, () => {
+            if (hybridDigest(selection(context, registration)) !== hybridDigest(this.#selected))
+                refuse("historical_second_graph_changed");
+            for (const history of this.#histories)
+                history.assertCustody(context);
+        });
     }
     revalidate(context) {
         this.#registration.revalidate(context);
@@ -207,6 +212,7 @@ export class PreparedHistoricalSecondMemoryCorrectionWave {
  * from today's filesystem. This owner neither allocates reviewers nor marks
  * repair findings resolved; independent re-review must consume it separately. */
 export class PreparedCompletedMemoryCorrectionWave {
+    #custodyKey = {};
     static isPrepared(value) {
         return typeof value === "object" && value !== null && #selected in value;
     }
@@ -252,7 +258,7 @@ export class PreparedCompletedMemoryCorrectionWave {
         for (const history of histories) {
             if (!known.has(hybridDigest(history.before().entries())))
                 refuse("unexplained_historical_input_view");
-            baseline = baseline.composeSettledDelta(history.before(), history.after());
+            baseline = baseline.composeSettledDelta(history.before(), history.after(), history.result().outcome);
             known.add(hybridDigest(baseline.entries()));
         }
         const view = PreparedRetainedSecondMemoryRepairs.isPrepared(registration) ? registration.initialInputView()
@@ -272,7 +278,7 @@ export class PreparedCompletedMemoryCorrectionWave {
         if (histories.some(history => hybridDigest(history.workspaceManifest().entries().filter(nonMemory)) !== sourceSha256))
             refuse("non_memory_source_changed");
         const batch = registration.batch(), receipt = registration.receipt();
-        const compose = readAcceptedStageData(context, { projectId: receipt.scope.project_id, runId: receipt.run_id, stage: "compose" });
+        const compose = readAcceptedStageData(context, { projectId: receipt.scope.project_id, runId: receipt.run_id, stage: bundle.descriptor.descriptor.id === "mb-upgrade" ? "upgrade" : "compose" });
         const dependencies = JSON.parse(compose.bytes.toString("utf8")).details.works;
         const currentUnits = PreparedRetainedSecondMemoryRepairs.isPrepared(registration)
             ? memoryCorrectionCurrentUnits(registration.initialInputView().unit_inventory, registration.initialInputView().assignments)
@@ -292,11 +298,13 @@ export class PreparedCompletedMemoryCorrectionWave {
     repairResults() { return this.#histories.map(history => ({ work_id: history.workId, result: history.result(), reference: history.reference(), authority_sha256: history.sha256 })); }
     /** Only SQL custody is inspected inside the future review-allocation writer. */
     assertCustody(context) {
-        const selected = this.#selected;
-        if (hybridDigest(selection(context, this.#registration)) !== hybridDigest(selected))
-            refuse("completed_wave_custody_changed");
-        for (const history of this.#histories)
-            history.assertCustody(context);
+        assertMemorySqlCustody(context, this.#custodyKey, () => {
+            const selected = this.#selected;
+            if (hybridDigest(selection(context, this.#registration)) !== hybridDigest(selected))
+                refuse("completed_wave_custody_changed");
+            for (const history of this.#histories)
+                history.assertCustody(context);
+        });
     }
     /** Fresh allocation fence, before adding successor reviewers. General
      * custody deliberately stays valid when those admitted children exist. */

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

@@ -20,6 +20,14 @@ import { PreparedMemoryCompositionAcceptance } from "./memory-composition-accept
 import { readAcceptedStageData } from "./stage-report-renderer.js";
 import { ObservedMemorySources } from "./memory-source-observations.js";
 import { PreparedCheckEvidence } from "./code-checks.js";
+import { captureMemoryUpgradeSources } from "./memory-upgrade-analysis-handler.js";
+import { PreparedMemoryUpgradeBootstrapReadiness, readMemoryUpgradeBootstrapReadiness } from "./memory-upgrade-bootstrap-readiness.js";
+import { readUpgradeStorageReadiness } from "./memory-upgrade-storage-readiness.js";
+import { PreparedMemoryUpgradePublication } from "./memory-upgrade-publication.js";
+import { PreparedMemoryLayer } from "./memory-layer.js";
+import { appendAudit } from "./audit.js";
+import { assertImportAdmission } from "../storage/import-guard.js";
+import { readMemoryUpgradePublication, upgradePublicationKey, upgradePublicationReceipt, upgradePublicationIntentEvent, upgradePublicationCompleteEvent } from "./memory-upgrade-publication-custody.js";
 function refuse(reason) {
     throw new AppError("memory_compose_handler_invalid", "Memory composition lacks retained scope, plan or output custody", 2, { reason, effect: "no_effect" });
 }
@@ -27,12 +35,30 @@ function selected(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.successor("discover", "accepted") !== "compose"
-        || bundle.descriptor.successor("compose", "accepted") !== "verify")
+    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, stage: "compose" };
+    const stage = bundle.descriptor.descriptor.id === "mb-init" ? "compose" : "upgrade";
+    if (bundle.descriptor.successor(stage === "compose" ? "discover" : "diff-analysis", "accepted") !== stage
+        || bundle.descriptor.successor(stage, "accepted") !== "verify")
+        refuse("registered_memory_bundle_required");
+    const project = requireProjectByRoot(context, resolveProjectRoot(input.projectRoot)), scope = { projectId: project.id, runId: input.runId, stage };
     const run = assertPreparedRunBundleSqlAuthority(context, scope, bundle), index = JSON.parse(run.index_json);
-    return { bundle, scope, run, accepted: index.stage_runs.find((stage) => stage.stage === "compose")?.status === "done" };
+    return { bundle, scope, run, accepted: index.stage_runs.find((item) => item.stage === stage)?.status === "done" };
+}
+function compositionBaseline(context, bundle) {
+    if (bundle.descriptor.descriptor.id === "mb-init")
+        return PreparedMemoryBaselinePreservation.prepare(context, bundle.execution);
+    const selected = bundle.execution.snapshot().scope;
+    const scope = { requestId: selected.requestId, projectRoot: selected.projectRoot, workspaceRoot: selected.workspace };
+    const ready = readMemoryUpgradeBootstrapReadiness(context, scope);
+    if (!ready?.hasPreservationBaseline || ready.authority.binding.execution_sha256 !== bundle.execution.sha256)
+        refuse("accepted_upgrade_bootstrap_required");
+    const authority = hybridDigest(ready.authority);
+    return {
+        assertCustody(writer) { const current = readMemoryUpgradeBootstrapReadiness(writer, scope); if (!current || hybridDigest(current.authority) !== authority)
+            refuse("upgrade_bootstrap_changed"); },
+        revalidate(reader) { PreparedMemoryUpgradeBootstrapReadiness.assertForRetainedRun(reader, bundle); this.assertCustody(reader); }
+    };
 }
 /** SQL-only physical binding proof; allocation/prompt custody is checked
  * separately. No new Session, hook claim or provider invocation is created.
@@ -70,14 +96,14 @@ export function registerMemoryCompositionFromStage(context, input) {
     const { bundle, scope, accepted } = selected(context, input);
     if (accepted)
         refuse("use_accepted_finish_replay");
-    const coordinator = PreparedDescriptorStageCoordinator.prepare(context, { ...input, stage: "compose" });
+    const coordinator = PreparedDescriptorStageCoordinator.prepare(context, { ...input, stage: scope.stage });
     const allocated = context.db.readSnapshot(() => {
         coordinator.assertAllocatedCustody(context);
         const root = readDescriptorRootWork(context, scope, bundle);
         return { workId: root.workId, physical: coordinatorSession(context, scope, bundle, root.workId) };
     });
     const binding = PreparedMemoryResultBinding.prepare(context, { ...scope, flow: bundle.descriptor, execution: bundle.execution, bundle,
-        sources: captureMemoryPreflightSources(context, bundle, input.bytes) });
+        sources: scope.stage === "compose" ? captureMemoryPreflightSources(context, bundle, input.bytes) : captureMemoryUpgradeSources(context, bundle, scope.stage, input.bytes) });
     let composition;
     try {
         composition = PreparedMemoryStageResult.prepare(input.bytes, bundle.descriptor, binding.binding());
@@ -94,7 +120,7 @@ export function registerMemoryCompositionFromStage(context, input) {
     const ordinaryDefaults = readDescriptorStageInput(context, scope, bundle).input.ordinary_defaults;
     if (ordinaryDefaults) {
         assertMemoryOrdinaryConfigurationCoverage(composition.value(), ordinaryDefaults);
-        if (ordinaryDefaults.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')='compose' LIMIT 1", [scope.projectId, scope.runId])) {
+        if (scope.stage === "compose" && ordinaryDefaults.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')='compose' LIMIT 1", [scope.projectId, scope.runId])) {
             throw new AppError("memory_stage_result_invalid", "Resolve the missing ordinary configuration choice through the existing compose pause/answer path before registering Work", 2, { phase: "prepare", effect: "no_effect", recoverable: true, reason: "ordinary_configuration_choice_required", missing: ordinaryDefaults.missing });
         }
     }
@@ -114,25 +140,136 @@ export function startMemoryComposition(context, input) {
     const { bundle, scope, accepted } = selected(context, input);
     if (accepted)
         refuse("use_accepted_finish_replay");
-    const preservation = PreparedMemoryBaselinePreservation.prepare(context, bundle.execution);
-    const inherited = context.db.readSnapshot(() => ({ discovery: readAcceptedStageData(context, { ...scope, stage: "discover" }), preflight: readAcceptedStageData(context, { ...scope, stage: "preflight" }) }));
+    const preservation = compositionBaseline(context, bundle), discoveryStage = scope.stage === "compose" ? "discover" : "diff-analysis";
+    const inherited = context.db.readSnapshot(() => ({ discovery: readAcceptedStageData(context, { ...scope, stage: discoveryStage }), preflight: readAcceptedStageData(context, { ...scope, stage: "preflight" }) }));
     const preflight = JSON.parse(inherited.preflight.bytes.toString("utf8")), discovery = JSON.parse(inherited.discovery.bytes.toString("utf8"));
-    if (preflight.schema_id !== "dd-flow/mb-init-preflight-result@1" || preflight.run_id !== input.runId || preflight.outcome !== "accepted"
-        || discovery.schema_id !== "dd-flow/mb-init-discover-result@1"
+    if (preflight.schema_id !== (scope.stage === "compose" ? "dd-flow/mb-init-preflight-result@1" : "dd-flow/mb-upgrade-stage-result@1") || preflight.run_id !== input.runId || preflight.outcome !== "accepted"
+        || discovery.schema_id !== (scope.stage === "compose" ? "dd-flow/mb-init-discover-result@1" : "dd-flow/mb-upgrade-stage-result@1")
+        || preflight.stage !== "preflight" || discovery.stage !== discoveryStage
         || discovery.run_id !== input.runId || discovery.outcome !== "accepted")
         refuse("accepted_discovery_and_baseline_required");
     const fence = (writer) => {
         preservation.assertCustody(writer);
-        if (readAcceptedStageData(writer, { ...scope, stage: "discover" }).authority_sha256 !== inherited.discovery.authority_sha256
+        if (readAcceptedStageData(writer, { ...scope, stage: discoveryStage }).authority_sha256 !== inherited.discovery.authority_sha256
             || readAcceptedStageData(writer, { ...scope, stage: "preflight" }).authority_sha256 !== inherited.preflight.authority_sha256)
             refuse("inherited_custody_changed");
     };
-    const start = PreparedDescriptorStageStart.prepare(context, { ...input, stage: "compose" });
+    const start = PreparedDescriptorStageStart.prepare(context, { ...input, stage: scope.stage });
     preservation.revalidate(context);
-    const stage = start.apply(context, fence), coordinator = PreparedDescriptorStageCoordinator.prepare(context, { ...input, stage: "compose" });
+    const stage = start.apply(context, fence), coordinator = PreparedDescriptorStageCoordinator.prepare(context, { ...input, stage: scope.stage });
     preservation.revalidate(context);
     return { ...stage, ...coordinator.apply(context, fence) };
 }
+/** Mechanical upgrade continuation, not final Stage acceptance. Reuses the
+ * registered blueprint and settled Work; the plan is retained in SQL before
+ * the first filesystem effect. No provider or second controller is launched.
+ * Kept outside the registry until the complete upgrade lifecycle is admitted.
+ */
+export function publishMemoryUpgradeFromStage(context, input) {
+    const { bundle, scope, accepted } = selected(context, { ...input, bytes: Buffer.alloc(0) });
+    if (scope.stage !== "upgrade" || accepted)
+        refuse("active_upgrade_publication_required");
+    const coordinator = PreparedDescriptorStageCoordinator.prepare(context, { ...input, stage: "upgrade" });
+    const allocated = context.db.readSnapshot(() => {
+        coordinator.assertAllocatedCustody(context);
+        const root = readDescriptorRootWork(context, scope, bundle);
+        return { workId: root.workId, physical: coordinatorSession(context, scope, bundle, root.workId) };
+    });
+    const registration = selectMemoryCompositionRegistration(context, { ...stageGraphScope(context, scope.projectId, scope.runId, "upgrade"), stage: "upgrade", parent_work_id: allocated.workId });
+    const binding = PreparedMemoryResultBinding.prepareRegisteredComposition(context, { ...scope, flow: bundle.descriptor, execution: bundle.execution, bundle, registrationScope: registration.scope });
+    const outputs = PreparedMemoryCompositionAcceptance.prepareForUpgradePublication(context, { scope: registration.scope, flow: bundle.descriptor, engine: bundle.engine(), binding: binding.binding() });
+    const frozen = bundle.execution.snapshot().scope, bootstrapScope = { requestId: frozen.requestId, projectRoot: frozen.projectRoot, workspaceRoot: frozen.workspace };
+    const ready = readMemoryUpgradeBootstrapReadiness(context, bootstrapScope), storage = readUpgradeStorageReadiness(context, bootstrapScope);
+    if (!ready || !storage?.selection || ready.authority.binding.storage_sha256 !== storage.sha256)
+        refuse("accepted_upgrade_bootstrap_required");
+    const identity = { scope: registration.scope, selection_sha256: storage.selection.sha256, execution_sha256: bundle.execution.sha256,
+        registration_sha256: hybridDigest(registration), bootstrap_sha256: hybridDigest(ready.authority),
+        work_custody_sha256: outputs.custodySha256() };
+    const fence = (writer) => {
+        assertPreparedRunBundleSqlAuthority(writer, scope, bundle);
+        coordinator.assertAllocatedCustody(writer);
+        binding.assertCustody(writer);
+        outputs.assertCustody(writer);
+        if (readDescriptorRootWork(writer, scope, bundle).workId !== allocated.workId
+            || coordinatorSession(writer, scope, bundle, allocated.workId) !== allocated.physical)
+            refuse("upgrade_publication_coordinator_changed");
+        const current = readMemoryUpgradeBootstrapReadiness(writer, bootstrapScope), retained = readUpgradeStorageReadiness(writer, bootstrapScope);
+        if (!current || hybridDigest(current.authority) !== identity.bootstrap_sha256 || retained?.selection?.sha256 !== identity.selection_sha256)
+            refuse("upgrade_publication_dependencies_changed");
+    };
+    const read = (reader) => readMemoryUpgradePublication(reader, identity);
+    let plan = read(context)?.plan;
+    if (!plan) {
+        binding.revalidate(context);
+        outputs.revalidate(context);
+        const selected = storage.selection.payload, layer = selected.layer;
+        if (!selected.current.old_tree || !selected.current.version_source)
+            refuse("upgrade_publication_baseline_required");
+        const target = PreparedMemoryLayer.restoreRetained(new Map(layer.files.map(file => [file.path, Buffer.from(file.base64, "base64")])), layer.sha256, layer.installation_sha256);
+        const diff = readAcceptedStageData(context, { ...scope, stage: "diff-analysis" }), details = JSON.parse(diff.bytes.toString("utf8")).details;
+        plan = PreparedMemoryUpgradePublication.prepare({ selectionSha256: storage.selection.sha256, inventory: selected.current.inventory,
+            oldTree: selected.current.old_tree, layer: target, changes: details.path_map, versionSource: selected.current.version_source });
+        const before = new Map(plan.beforeFiles().map(file => [file.path, file]));
+        const settled = new Map(outputs.settledArtifacts().filter(item => item.artifact.root === "workspace").map(item => [item.artifact.path, item.artifact.sha256]));
+        for (const entry of selected.current.inventory.inventory.entries)
+            if (entry.current && !before.has(entry.path))
+                refuse("unsettled_semantic_removal");
+        for (const [name, file] of before) {
+            const original = selected.current.inventory.inventory.entries.find(entry => entry.path === name)?.current;
+            if (original && file.kind === original.kind && file.mode === original.mode && file.sha256 === original.sha256)
+                continue;
+            if (file.kind !== "file" || original && file.mode !== original.mode || settled.get(`.memory-bank/${name}`) !== file.sha256)
+                refuse("unsettled_semantic_change");
+        }
+        const prepared = plan;
+        plan = context.db.writeTransaction(() => {
+            fence(context);
+            const prior = read(context)?.plan;
+            if (prior) {
+                if (prior.sha256 !== prepared.sha256)
+                    refuse("upgrade_publication_plan_changed");
+                return prior;
+            }
+            const now = context.now();
+            context.db.run("INSERT INTO runtime_config (key,value_json,created_at,updated_at) VALUES (?,?,?,?)", [upgradePublicationKey(identity), JSON.stringify({ binding: identity, plan_json: prepared.bytes().toString("utf8"), plan_sha256: prepared.sha256 }), now, now]);
+            appendAudit(context, { projectId: scope.projectId, eventType: upgradePublicationIntentEvent, payload: upgradePublicationReceipt(identity, prepared) });
+            const retained = read(context);
+            if (!retained)
+                refuse("upgrade_publication_intent_readback_failed");
+            return retained.plan;
+        });
+    }
+    const publication = plan;
+    try {
+        while (true) {
+            assertImportAdmission(context.ddFlowHome);
+            context.db.readSnapshot(() => { fence(context); if (read(context)?.plan.sha256 !== publication.sha256)
+                refuse("upgrade_publication_intent_changed"); });
+            if (publication.applyNextAction().status === "applied")
+                break;
+        }
+        context.db.writeTransaction(() => {
+            fence(context);
+            if (read(context)?.plan.sha256 !== publication.sha256)
+                refuse("upgrade_publication_intent_changed");
+            if (!read(context)?.completed)
+                appendAudit(context, { projectId: scope.projectId, eventType: upgradePublicationCompleteEvent, payload: upgradePublicationReceipt(identity, publication, true) });
+            if (!read(context)?.completed)
+                refuse("upgrade_publication_completion_readback_failed");
+        });
+        const state = publication.classify();
+        if (state.completed !== state.total)
+            refuse("upgrade_publication_not_complete");
+        const record = publication.outputs().find(output => output.path === `archive/mb-upgrade/${identity.selection_sha256}/migration.json`);
+        if (!record)
+            refuse("upgrade_migration_record_missing");
+        return { status: "applied", publication_sha256: publication.sha256, migration_record: { path: `.memory-bank/${record.path}`, sha256: record.sha256 },
+            artifacts: publication.outputs().map(output => ({ root: "workspace", path: `.memory-bank/${output.path}`, sha256: output.sha256 })) };
+    }
+    catch (error) {
+        throw new AppError("memory_upgrade_publication_pending", "Preserve the accepted SQL plan and reconcile this upgrade continuation", 1, { effect: "publication_pending", publication_sha256: publication.sha256, cause: error instanceof Error ? error.message : String(error) });
+    }
+}
 /** Agent references are selectors, not permissions. Supplement independent
  * baseline evidence only with current outputs admitted by completed Work.
  */
@@ -207,7 +344,10 @@ export function captureMemoryCompositionSources(context, bundle, runRoot, bytes,
     }
     // Keep evidence/artifact roles for the shared collector; settled child output
     // references already have their independent output owner above.
-    const observedBaseline = captureMemoryPreflightSources(context, bundle, Buffer.from(JSON.stringify(value))), locations = new Map();
+    const observedBaseline = bundle.descriptor.descriptor.id === "mb-upgrade"
+        ? captureMemoryUpgradeSources(context, bundle, value.stage, Buffer.from(JSON.stringify(value)))
+        : captureMemoryPreflightSources(context, bundle, Buffer.from(JSON.stringify(value)));
+    const locations = new Map();
     for (const key of observedBaseline.hashes().keys()) {
         const [root, logical] = key.split("\0");
         locations.set(key, { root: root, path: logical });
@@ -230,27 +370,29 @@ export function captureMemoryCompositionSources(context, bundle, runRoot, bytes,
  * Semantic quality remains the following VERIFY and independent REVIEW gates.
  */
 export function finishMemoryComposition(context, input) {
-    const { bundle, scope, run, accepted } = selected(context, input), root = readDescriptorRootWork(context, scope, bundle);
+    const { bundle, scope, run, accepted } = selected(context, input);
+    const root = readDescriptorRootWork(context, scope, bundle);
     if (!input.bytes.length)
         refuse("invalid_result_bytes");
-    const registration = selectMemoryCompositionRegistration(context, { ...stageGraphScope(context, scope.projectId, scope.runId, scope.stage), stage: "compose", parent_work_id: root.workId });
+    const registration = selectMemoryCompositionRegistration(context, { ...stageGraphScope(context, scope.projectId, scope.runId, scope.stage), stage: scope.stage, parent_work_id: root.workId });
     const registrationScope = registration.scope;
     const blueprintBinding = PreparedMemoryResultBinding.prepareRegisteredComposition(context, { ...scope, flow: bundle.descriptor, execution: bundle.execution, bundle,
         registrationScope, acceptedReplay: accepted });
     const outputs = PreparedMemoryCompositionAcceptance.prepare(context, { scope: registrationScope, flow: bundle.descriptor, engine: bundle.engine(), binding: blueprintBinding.binding() });
-    const sources = captureMemoryCompositionSources(context, bundle, run.run_root ?? run.run_dir, input.bytes, outputs);
+    const bytes = outputs.projectResult(input.bytes);
+    const sources = captureMemoryCompositionSources(context, bundle, run.run_root ?? run.run_dir, bytes, outputs);
     const binding = PreparedMemoryResultBinding.prepare(context, { ...scope, flow: bundle.descriptor, execution: bundle.execution, bundle, sources, acceptedReplay: accepted, historicalEvidence: outputs.historicalEvidence() });
     const replay = binding.acceptedBytes();
-    if (replay && !replay.equals(input.bytes))
+    if (replay && !replay.equals(bytes))
         refuse("accepted_result_changed");
-    const result = PreparedMemoryStageResult.prepare(input.bytes, bundle.descriptor, binding.binding());
+    const result = PreparedMemoryStageResult.prepare(bytes, bundle.descriptor, binding.binding());
     outputs.assertResult(result);
     const ordinaryDefaults = readDescriptorStageInput(context, scope, bundle, true, accepted).input.ordinary_defaults;
     if (ordinaryDefaults && !replay) {
         const selected = bundle.execution.snapshot().scope;
         assertMemoryOrdinaryConfigurationOutputs(context, selected.workspace, ordinaryDefaults, result.value().units.flatMap(unit => unit.artifacts), { requestId: selected.requestId, projectRoot: selected.projectRoot, workspaceRoot: selected.workspace });
     }
-    const settlement = PreparedDescriptorStageSettlement.prepare(context, { ...input, stage: "compose", bytes: result.bytes() });
+    const settlement = PreparedDescriptorStageSettlement.prepare(context, { ...input, stage: scope.stage, bytes: result.bytes() });
     blueprintBinding.revalidate(context);
     binding.revalidate(context);
     outputs.revalidate(context);