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

package/dist/cli/memory-init.js

@@ -13,7 +13,7 @@ import { PreparedMemoryInitLintCapability } from "../services/memory-init-lint-c
 import { PreparedMemoryInitWorktrunkCapability } from "../services/memory-init-worktrunk-capability.js";
 import { produceMemoryInitNativeCapacity } from "../services/memory-init-native-capacity.js";
 import { openMemoryInitStores, assertMemoryInitStorePrerequisites } from "../services/memory-init-stores.js";
-import { prepareMemoryInitControllerStart } from "../services/memory-init-controller-start.js";
+import { prepareMemoryInitControllerStart, prepareMemoryUpgradeControllerStart } from "../services/memory-init-controller-start.js";
 import { runControllerStatus } from "../services/run-controller.js";
 import { requireRun } from "../services/run-controller-state.js";
 import { requireProjectByRoot } from "../services/projects.js";
@@ -159,73 +159,7 @@ export async function runMemoryInitCli(args, env = process.env, io = process) {
         // Beyond this boundary, absence of a success receipt is not no-effect.
         effects = true;
         const started = startMemoryInitRun(context, invocation.scope, prepared ? () => prepared : undefined);
-        if (invocation.prepareOnly) {
-            const run = requireRun(context, requireProjectByRoot(context, invocation.scope.projectRoot).id, started.runId);
-            const response = { ok: true, action: "flow_mb_init_prepared", flow_id: "mb-init", ...started,
-                run_id: started.runId, request_id: invocation.scope.requestId, run_root: run.run_root,
-                project_root: run.project_root, workspace_root: run.workspace_root };
-            await writeMemoryInitObservation(io.stdout, `${JSON.stringify(writeResponseFile(response, output), null, output.json || output.progressJsonl ? undefined : 2)}\n`);
-            return 0;
-        }
-        const launch = prepareMemoryInitControllerStart(context, invocation.scope);
-        // Use the existing RUN-bound router: a global CLI must not launch its own
-        // controller code in place of the independently frozen RUN executable.
-        const receiptChunks = [];
-        let receiptSize = 0, oversizedReceipt = false;
-        const capture = new Writable({ write(chunk, _, next) {
-                receiptSize += Buffer.byteLength(chunk);
-                if (receiptSize > 1024 * 1024)
-                    oversizedReceipt = true;
-                else
-                    receiptChunks.push(Buffer.from(chunk));
-                next();
-            } });
-        const routed = await routeArgsThroughEngine(context, ["run", "drive", "launch", "--project-root", launch.input.projectRoot,
-            "--run", launch.input.runId, "--request-id", launch.input.requestId, "--context-file", launch.input.contextFile,
-            "--context-sha256", launch.input.contextSha256, "--json"], { stdout: capture, stderr: io.stderr }, undefined, { ...env, DD_FLOW_ENGINE_MODE: undefined }, invocation.scope.projectRoot);
-        if (!routed?.routed || routed.inProcess || routed.exitCode !== 0 || oversizedReceipt)
-            throw new AppError("memory_init_controller_launch_unknown", "Observe or reconcile the exact RUN-bound controller launch", 1, { effect: "unknown" });
-        let receipt;
-        try {
-            receipt = JSON.parse(new TextDecoder("utf-8", { fatal: true }).decode(Buffer.concat(receiptChunks)));
-        }
-        catch {
-            throw new AppError("memory_init_controller_launch_unknown", "Selected engine returned no valid controller receipt", 1, { effect: "unknown" });
-        }
-        const accepted = receipt.controller;
-        if (receipt.ok !== true || !accepted || accepted.run_id !== started.runId || accepted.request_id !== invocation.scope.requestId)
-            throw new AppError("memory_init_controller_launch_unknown", "Selected engine returned a foreign controller receipt", 1, { effect: "unknown" });
-        const emit = (result) => writeMemoryInitObservation(io.stdout, `${JSON.stringify(result, null, output.json || output.progressJsonl ? undefined : 2)}\n`);
-        if (output.progressJsonl && !await emit({ ok: true, action: "flow_accepted", flow_id: "mb-init", ...started, ...receipt }))
-            return 0;
-        let result = receipt;
-        if (!invocation.detach) {
-            let after = 0;
-            let recentEvents = [];
-            for (;;) {
-                // The client has no ownership of the detached controller process.
-                if (io.stdout.destroyed)
-                    return 0;
-                result = runControllerStatus(context, { projectRoot: invocation.scope.projectRoot, runId: started.runId, after });
-                const events = result.events, controller = result.controller;
-                after = result.next_cursor;
-                recentEvents = [...recentEvents, ...events].slice(-100);
-                if (output.progressJsonl && events.length && !await emit({ ok: true, action: "flow_progress", flow_id: "mb-init", ...result }))
-                    return 0;
-                if (!controller)
-                    throw new AppError("memory_init_controller_receipt_missing", "Observe or reconcile the retained controller", 1, { effect: "unknown" });
-                if (["completed", "cancelled", "superseded", "recovery_required", "failed", "waiting_for_user", "waiting_for_context"].includes(controller.status)) {
-                    result = { ...result, events: recentEvents };
-                    break;
-                }
-                await delay(250);
-            }
-        }
-        const response = { ...result, action: "flow_mb_init", flow_id: "mb-init", run_id: started.runId, request_id: invocation.scope.requestId };
-        if (!await emit(writeResponseFile(response, output)))
-            return 0;
-        const status = result.controller?.status;
-        return ["recovery_required", "failed", "cancelled", "superseded"].includes(status ?? "") ? 1 : 0;
+        return await launchAndObserveMemoryFlow(context, invocation, started, "mb-init", output, env, io);
     }
     catch (error) {
         const record = errorRecord(error);
@@ -238,3 +172,75 @@ export async function runMemoryInitCli(args, env = process.env, io = process) {
         context?.db.close?.();
     }
 }
+/** Shared foreground observer only; the existing RUN-bound controller owns
+ * physical Sessions. Neither alias gains another orchestration lifecycle. */
+export async function launchAndObserveMemoryFlow(context, invocation, started, flowId, output, env, io) {
+    const action = flowId === "mb-init" ? "flow_mb_init" : "flow_mb_upgrade";
+    if (invocation.prepareOnly) {
+        const run = requireRun(context, requireProjectByRoot(context, invocation.scope.projectRoot).id, started.runId);
+        const response = { ok: true, action: `${action}_prepared`, flow_id: flowId, ...started,
+            run_id: started.runId, request_id: invocation.scope.requestId, run_root: run.run_root,
+            project_root: run.project_root, workspace_root: run.workspace_root };
+        await writeMemoryInitObservation(io.stdout, `${JSON.stringify(writeResponseFile(response, output), null, output.json || output.progressJsonl ? undefined : 2)}\n`);
+        return 0;
+    }
+    const launch = (flowId === "mb-init" ? prepareMemoryInitControllerStart : prepareMemoryUpgradeControllerStart)(context, invocation.scope);
+    // Use the existing RUN-bound router: a global CLI must not launch its own
+    // controller code in place of the independently frozen RUN executable.
+    const receiptChunks = [];
+    let receiptSize = 0, oversizedReceipt = false;
+    const capture = new Writable({ write(chunk, _, next) {
+            receiptSize += Buffer.byteLength(chunk);
+            if (receiptSize > 1024 * 1024)
+                oversizedReceipt = true;
+            else
+                receiptChunks.push(Buffer.from(chunk));
+            next();
+        } });
+    const routed = await routeArgsThroughEngine(context, ["run", "drive", "launch", "--project-root", launch.input.projectRoot,
+        "--run", launch.input.runId, "--request-id", launch.input.requestId, "--context-file", launch.input.contextFile,
+        "--context-sha256", launch.input.contextSha256, "--json"], { stdout: capture, stderr: io.stderr }, undefined, { ...env, DD_FLOW_ENGINE_MODE: undefined }, invocation.scope.projectRoot);
+    if (!routed?.routed || routed.inProcess || routed.exitCode !== 0 || oversizedReceipt)
+        throw new AppError("memory_init_controller_launch_unknown", "Observe or reconcile the exact RUN-bound controller launch", 1, { effect: "unknown" });
+    let receipt;
+    try {
+        receipt = JSON.parse(new TextDecoder("utf-8", { fatal: true }).decode(Buffer.concat(receiptChunks)));
+    }
+    catch {
+        throw new AppError("memory_init_controller_launch_unknown", "Selected engine returned no valid controller receipt", 1, { effect: "unknown" });
+    }
+    const accepted = receipt.controller;
+    if (receipt.ok !== true || !accepted || accepted.run_id !== started.runId || accepted.request_id !== invocation.scope.requestId)
+        throw new AppError("memory_init_controller_launch_unknown", "Selected engine returned a foreign controller receipt", 1, { effect: "unknown" });
+    const emit = (result) => writeMemoryInitObservation(io.stdout, `${JSON.stringify(result, null, output.json || output.progressJsonl ? undefined : 2)}\n`);
+    if (output.progressJsonl && !await emit({ ok: true, action: "flow_accepted", flow_id: flowId, ...started, ...receipt }))
+        return 0;
+    let result = receipt;
+    if (!invocation.detach) {
+        let after = 0;
+        let recentEvents = [];
+        for (;;) {
+            // The client has no ownership of the detached controller process.
+            if (io.stdout.destroyed)
+                return 0;
+            result = runControllerStatus(context, { projectRoot: invocation.scope.projectRoot, runId: started.runId, after });
+            const events = result.events, controller = result.controller;
+            after = result.next_cursor;
+            recentEvents = [...recentEvents, ...events].slice(-100);
+            if (output.progressJsonl && events.length && !await emit({ ok: true, action: "flow_progress", flow_id: flowId, ...result }))
+                return 0;
+            if (!controller)
+                throw new AppError("memory_init_controller_receipt_missing", "Observe or reconcile the retained controller", 1, { effect: "unknown" });
+            if (["completed", "cancelled", "superseded", "recovery_required", "failed", "waiting_for_user", "waiting_for_context"].includes(controller.status)) {
+                result = { ...result, events: recentEvents };
+                break;
+            }
+            await delay(250);
+        }
+    }
+    const response = { ...result, action, flow_id: flowId, run_id: started.runId, request_id: invocation.scope.requestId };
+    if (!await emit(writeResponseFile(response, output)))
+        return 0;
+    const status = result.controller?.status;
+    return ["recovery_required", "failed", "cancelled", "superseded"].includes(status ?? "") ? 1 : 0;
+}

package/dist/cli/memory-storage-admission.js

@@ -17,6 +17,7 @@ export function runMemoryStorageAdmissionCli(args, env = process.env, io = proce
         if (route.key !== "runtime storage admit" || output.responseFile || output.progressJsonl) {
             throw new AppError("usage", "Storage admission accepts stdout output only", 2, { effect: "no_effect" });
         }
+        const operation = route.parsed.options.get("operation")[0];
         const home = env.DD_FLOW_HOME;
         if (!home || !path.isAbsolute(home) || path.resolve(home) !== home || fs.realpathSync(home) !== home) {
             throw new AppError("usage", "Storage admission requires an explicit canonical absolute DD_FLOW_HOME", 2, { effect: "no_effect" });
@@ -27,7 +28,7 @@ export function runMemoryStorageAdmissionCli(args, env = process.env, io = proce
         const resource = PreparedMemoryInitResourceStorage.prepare({ ddFlowHome: home, env });
         const context = createContext(env, "prepared_existing");
         const facts = withStoreCleanup(() => {
-            const run = PreparedMemoryInitRuntimeStorage.prepare(context);
+            const run = operation === "memory-upgrade" ? PreparedMemoryInitRuntimeStorage.prepareUpgrade(context) : PreparedMemoryInitRuntimeStorage.prepare(context);
             const resourceWriter = getResourceDatabase(path.dirname(resource.facts().store_path), "prepared_existing");
             return withStoreCleanup(() => {
                 if (resourceWriter.get("SELECT dd_flow_writer_version() AS version")?.version !== resource.facts().executing_writer_version) {
@@ -38,7 +39,7 @@ export function runMemoryStorageAdmissionCli(args, env = process.env, io = proce
                 if (!current.isFile() || current.nlink !== 1 || current.dev !== owner.dev || current.ino !== owner.ino) {
                     throw new AppError("run_storage_changed", "RUN store changed during admission", 1, { effect: "no_effect" });
                 }
-                return { schema_id: "dd-flow/memory-init-engine-storage@1", operation: "memory-init", route: "verified-no-op", outcome: "no-op",
+                return { schema_id: `dd-flow/${operation}-engine-storage@1`, operation, route: "verified-no-op", outcome: "no-op",
                     run: { ...run.facts(), store_dev: owner.dev, store_ino: owner.ino }, resource: resource.facts() };
             }, () => resourceWriter.close?.());
         }, () => context.db.close?.());

package/dist/cli/memory-storage-qualification.js

@@ -0,0 +1,105 @@
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { Writable } from "node:stream";
+import { DatabaseSync } from "node:sqlite";
+import { getDatabase, getResourceDatabase } from "../storage/database.js";
+import { canonicalPath } from "../storage/paths.js";
+import { prepareCommandRoute } from "./command-inputs.js";
+import { parseOutputOptions } from "./output-options.js";
+import { runMemoryStorageAdmissionCli } from "./memory-storage-admission.js";
+import { writePreparationError } from "./error-output.js";
+import { AppError, errorRecord } from "../shared/errors.js";
+import { hybridDigest } from "../services/hybrid-contracts.js";
+import { captureStoreMigrationState } from "../storage/writer-migration.js";
+import { PreparedPairedWriterMigration, observeDrainedMigrationStores } from "../storage/paired-writer-migration.js";
+import { assertImportAdmission } from "../storage/import-guard.js";
+/** Capability only. Exercise the actual target migration/admission on private
+ * WAL-aware copies before paying for a native probe. Never grants real-store
+ * write admission, productive migration proof or a runtime permit. */
+export function runMemoryStorageQualificationCli(args, env = process.env, io = process) {
+    let temporary;
+    try {
+        const output = parseOutputOptions(args), route = prepareCommandRoute(output.args);
+        if (route.key !== "runtime storage qualify" || output.responseFile || output.progressJsonl)
+            throw new AppError("usage", "Storage qualification accepts stdout output only", 2, { effect: "no_effect" });
+        const home = env.DD_FLOW_HOME, resource = env.DD_FLOW_RESOURCE_HOME;
+        for (const root of [home, resource])
+            if (!root || !path.isAbsolute(root) || canonicalPath(root, false) !== root)
+                throw new AppError("usage", "Qualification requires both explicit canonical storage Homes", 2, { effect: "no_effect" });
+        for (const root of new Set([home, resource]))
+            assertImportAdmission(root);
+        const stores = [{ database: path.join(home, "db.sqlite") }, { database: path.join(resource, "runtime.sqlite") }];
+        const admit = (selected) => {
+            let stdout = "", stderr = "";
+            const collect = (write) => new Writable({ write(chunk, _encoding, done) { write(chunk.toString()); done(); } });
+            const code = runMemoryStorageAdmissionCli(["runtime", "storage", "admit", "--operation", "memory-upgrade", "--json"], selected, { stdout: collect(chunk => { stdout += chunk; }), stderr: collect(chunk => { stderr += chunk; }) });
+            return { code, stdout, stderr };
+        };
+        const current = admit(env);
+        let selectedRoute = "verified-no-op";
+        if (current.code !== 0) {
+            // No simulation of a live runtime: the normal admission above remains
+            // sufficient for compatible stores; changed stores must already drain.
+            temporary = fs.realpathSync(fs.mkdtempSync(path.join(os.tmpdir(), "dd-upgrade-capability-")));
+            const runHome = path.join(temporary, "run"), resourceHome = path.join(temporary, "resource");
+            fs.mkdirSync(runHome);
+            fs.mkdirSync(resourceHome);
+            const copies = [path.join(runHome, "db.sqlite"), path.join(resourceHome, "runtime.sqlite")];
+            stores.forEach((store, index) => {
+                if (!fs.existsSync(store.database)) {
+                    if (["-wal", "-shm", "-journal"].some(suffix => fs.existsSync(store.database + suffix)))
+                        throw new AppError("storage_capability_invalid", "Missing source store retains sidecars", 1, { effect: "no_effect" });
+                    const fresh = index === 0 ? getDatabase(runHome, "create_new") : getResourceDatabase(resourceHome, "create_new");
+                    fresh.close?.();
+                    return;
+                }
+                const owner = fs.lstatSync(store.database);
+                if (!owner.isFile() || owner.nlink !== 1)
+                    throw new AppError("storage_capability_invalid", "Source store must have one regular physical owner", 1, { effect: "no_effect" });
+                const reader = new DatabaseSync(store.database, { readOnly: true });
+                try {
+                    reader.exec(`VACUUM INTO '${copies[index].replaceAll("'", "''")}'`);
+                    const copy = new DatabaseSync(copies[index], { readOnly: true });
+                    try {
+                        if (hybridDigest(captureStoreMigrationState(reader)) !== hybridDigest(captureStoreMigrationState(copy)))
+                            throw new AppError("storage_capability_invalid", "Source changed during private qualification", 1, { effect: "no_effect" });
+                    }
+                    finally {
+                        copy.close();
+                    }
+                    const after = fs.lstatSync(store.database);
+                    if (after.dev !== owner.dev || after.ino !== owner.ino || after.nlink !== 1)
+                        throw new AppError("storage_capability_invalid", "Source store owner changed", 1, { effect: "no_effect" });
+                }
+                finally {
+                    reader.close();
+                }
+            });
+            let checked = admit({ ...env, DD_FLOW_HOME: runHome, DD_FLOW_RESOURCE_HOME: resourceHome });
+            if (checked.code !== 0) {
+                observeDrainedMigrationStores(stores.filter(store => fs.existsSync(store.database)));
+                PreparedPairedWriterMigration.prepare({ requestId: "capability-only", requestFile: path.join(temporary, "plan.json"), projectRoot: temporary,
+                    workspaceRoot: temporary, runHome, resourceHome, selectionSha256: hybridDigest(stores), bootstrapSchema: "memory-upgrade@1" }).apply();
+                checked = admit({ ...env, DD_FLOW_HOME: runHome, DD_FLOW_RESOURCE_HOME: resourceHome });
+                selectedRoute = "migration";
+            }
+            if (checked.code !== 0)
+                throw new AppError("storage_capability_invalid", "Target cannot admit its privately migrated copies", 1, { effect: "no_effect", admission: JSON.parse(checked.stderr) });
+        }
+        const facts = { schema_id: "dd-flow/memory-upgrade-storage-capability@1", operation: "memory-upgrade", route: selectedRoute,
+            source_stores: stores.map(store => store.database), productive_admission: false };
+        io.stdout.write(`${JSON.stringify({ ok: true, action: "runtime_storage_qualify", facts, sha256: hybridDigest(facts) })}\n`);
+        return 0;
+    }
+    catch (error) {
+        const record = errorRecord(error);
+        record.details = { ...record.details, effect: "no_effect" };
+        writePreparationError(io, args, record);
+        return record.exitCode;
+    }
+    finally {
+        if (temporary)
+            fs.rmSync(temporary, { recursive: true, force: true });
+    }
+}

package/dist/cli/memory-storage-transition.js

@@ -0,0 +1,123 @@
+import fs from "node:fs";
+import path from "node:path";
+import { createHash } from "node:crypto";
+import { prepareCommandRoute } from "./command-inputs.js";
+import { parseOutputOptions } from "./output-options.js";
+import { AppError, errorRecord } from "../shared/errors.js";
+import { writePreparationError } from "./error-output.js";
+import { restoreMemoryUpgradeSelection } from "../services/memory-upgrade-selection.js";
+import { assertMemoryUpgradeProjectCurrent } from "../services/memory-upgrade-storage-readiness.js";
+import { PreparedPairedWriterMigration, PreparedPairedWriterRecovery } from "../storage/paired-writer-migration.js";
+import { readBoundedReleaseFile } from "../services/release-source.js";
+import { shellArgument } from "../services/runtime-command.js";
+function refuse(reason) { throw new AppError("memory_storage_transition_invalid", "Storage transition requires the original upgrade and its selected immutable engine", 1, { reason, effect: "no_effect" }); }
+const hash = (bytes) => createHash("sha256").update(bytes).digest("hex");
+/** Pre-context transport: no initialize/prepared-existing database connection,
+ * router fallback, provider or RUN creation. Executed by the selected engine. */
+export function runMemoryStorageTransitionCli(args, env = process.env, io = process) {
+    let effects = false;
+    try {
+        const output = parseOutputOptions(args), route = prepareCommandRoute(output.args);
+        if (route.key !== "runtime storage transition" || output.responseFile || output.progressJsonl)
+            throw new AppError("usage", "Storage transition accepts stdout output only", 2, { effect: "no_effect" });
+        const option = (key) => route.parsed.options.get(key)?.[0];
+        const action = option("action"), expected = option("expected-sha256"), recoveryId = option("recovery-id");
+        if (env.DD_FLOW_INVOCATION_READONLY === "1" && !["status", "recovery-status"].includes(action))
+            refuse("readonly_invocation");
+        if (action !== "plan" && (!expected || !/^[a-f0-9]{64}$/.test(expected)))
+            throw new AppError("usage", "This action requires --expected-sha256 from its retained request", 2, { effect: "no_effect" });
+        if ((action === "recovery-plan") !== Boolean(recoveryId))
+            throw new AppError("usage", "--recovery-id is required only for recovery-plan", 2, { effect: "no_effect" });
+        if (["apply", "recovery-plan", "recover"].includes(action) && !route.parsed.options.has("offline"))
+            throw new AppError("usage", "Storage mutation requires --offline after draining all runtime owners", 2, { effect: "no_effect" });
+        const home = env.DD_FLOW_HOME, resource = env.DD_FLOW_RESOURCE_HOME;
+        for (const root of [home, resource])
+            if (!root || !path.isAbsolute(root) || fs.realpathSync(root) !== root)
+                refuse("explicit_canonical_homes_required");
+        const scope = { requestId: option("request-id"), projectRoot: option("project-root"), workspaceRoot: option("workspace-root") };
+        const selected = restoreMemoryUpgradeSelection(home, scope), engine = selected.engine;
+        if (option("selection-sha256") !== selected.sha256)
+            refuse("original_selection_changed");
+        if (!process.argv[1] || fs.realpathSync(process.argv[1]) !== engine.entrypoint)
+            refuse("selected_engine_entrypoint_required");
+        const file = path.join(path.dirname(selected.original.candidate.retain().file), "storage-migration.json");
+        const pairedId = `upgrade-${selected.sha256.slice(0, 32)}`;
+        const assertProjectCurrent = () => {
+            if (!selected.payload.git || !selected.oldTree)
+                refuse("productive_upgrade_selection_required");
+            assertMemoryUpgradeProjectCurrent(selected, scope, env);
+        };
+        const restorePair = (sha) => {
+            const pair = PreparedPairedWriterMigration.restore(file, sha), material = pair.recoveryMaterial();
+            if (material.intent.selection_sha256 !== selected.sha256 || material.intent.request_id !== pairedId
+                || material.intent.project_root !== scope.projectRoot || material.intent.workspace_root !== scope.workspaceRoot
+                || material.intent.stores[0]?.home !== home || material.intent.stores[1]?.home !== resource)
+                refuse("retained_pair_scope_changed");
+            return pair;
+        };
+        const command = (next, sha) => `DD_FLOW_RESOURCE_HOME=${shellArgument(resource)} ${engine.command(home, [
+            "runtime", "storage", "transition", "--action", next, "--project-root", scope.projectRoot, "--workspace-root", scope.workspaceRoot,
+            "--request-id", scope.requestId, "--selection-sha256", selected.sha256, "--expected-sha256", sha, ...(["apply", "recover"].includes(next) ? ["--offline"] : []), "--json"
+        ])}`;
+        let result;
+        if (action === "plan") {
+            let pair;
+            if (fs.existsSync(file))
+                pair = restorePair(expected ?? hash(readBoundedReleaseFile(file, 16 * 1024 * 1024)));
+            else {
+                if (expected)
+                    refuse("original_pair_missing");
+                assertProjectCurrent();
+                pair = PreparedPairedWriterMigration.prepare({ requestId: pairedId, requestFile: file, projectRoot: scope.projectRoot, workspaceRoot: scope.workspaceRoot,
+                    runHome: home, resourceHome: resource, selectionSha256: selected.sha256, bootstrapSchema: "memory-upgrade@1" });
+            }
+            effects = true;
+            const request = pair.retain();
+            result = { request, apply_command: command("apply", pair.sha256), status_command: command("status", pair.sha256) };
+        }
+        else if (action === "recover" || action === "recovery-status") {
+            const recovery = PreparedPairedWriterRecovery.restore(file + ".recovery.json", expected), reference = recovery.migrationReference();
+            if (reference.path !== file)
+                refuse("recovery_migration_scope_changed");
+            restorePair(reference.sha256);
+            if (action === "recover") {
+                effects = true;
+                result = recovery.apply();
+            }
+            else
+                result = recovery.reconcile();
+        }
+        else {
+            const pair = restorePair(expected);
+            if (action === "status") {
+                const observed = pair.reconcile();
+                result = { status: observed.status,
+                    proof: fs.existsSync(file + ".result.json") ? pair.readEvidence() : null,
+                    outcomes: observed.outcomes.map(outcome => ({ status: outcome.status, ...(outcome.reason ? { reason: outcome.reason } : {}) })) };
+            }
+            else if (action === "apply") {
+                if (pair.reconcile().status === "not_applied")
+                    assertProjectCurrent();
+                effects = true;
+                pair.apply();
+                result = { status: "applied", proof: pair.readEvidence() };
+            }
+            else {
+                const recovery = PreparedPairedWriterRecovery.prepare(pair, recoveryId);
+                effects = true;
+                const request = recovery.retain();
+                result = { request, recover_command: command("recover", request.sha256), status_command: command("recovery-status", request.sha256) };
+            }
+        }
+        io.stdout.write(`${JSON.stringify({ ok: true, action: "runtime_storage_transition", operation: action, scope, selection_sha256: selected.sha256,
+            engine: { manifest_sha256: engine.manifestSha256, sha256: engine.manifest().integrity.checksum }, result }, null, output.json ? undefined : 2)}\n`);
+        return 0;
+    }
+    catch (error) {
+        const record = errorRecord(error);
+        if (effects)
+            record.details = { ...record.details, effect: "unknown", next_action: "reconcile_exact_request" };
+        writePreparationError(io, args, record);
+        return record.exitCode;
+    }
+}

package/dist/cli/memory-upgrade.js

@@ -0,0 +1,189 @@
+import { createHash } from "node:crypto";
+import fs from "node:fs";
+import path from "node:path";
+import { createContext } from "../runtime/context.js";
+import { AppError, errorRecord } from "../shared/errors.js";
+import { resolveDdFlowHome } from "../storage/paths.js";
+import { hybridDigest } from "../services/hybrid-contracts.js";
+import { readSetupStatus } from "../services/setup.js";
+import { readOperatorProfiles, readOperatorProfileInput } from "../services/operator-profiles.js";
+import { onboardExecutor } from "../services/executor-onboarding.js";
+import { readMemoryUpgradeRequestCandidate, prepareMemoryUpgradeRequestCandidate } from "../services/memory-init-request-candidate.js";
+import { readMemoryUpgradeRequestInput } from "../services/memory-init-request-input.js";
+import { PreparedMemoryUpgradeSelection, readMemoryUpgradeSelection, restoreMemoryUpgradeSelection } from "../services/memory-upgrade-selection.js";
+import { PreparedUpgradeStorageReadiness, readUpgradeStorageReadiness, assertMemoryUpgradeProjectCurrent } from "../services/memory-upgrade-storage-readiness.js";
+import { startMemoryUpgradeRun, registerMemoryUpgradeProject } from "../services/memory-upgrade-start.js";
+import { openMemoryInitStores, assertMemoryInitStorePrerequisites } from "../services/memory-init-stores.js";
+import { PreparedInstalledFlowSource } from "../services/installed-flow-source.js";
+import { selectMemoryInitInstalledEngine } from "../services/memory-init-engine-release.js";
+import { FrozenGenericExecution } from "../services/generic-execution.js";
+import { prepareMemoryInitHarnessCommands } from "../services/memory-init-project-bootstrap.js";
+import { produceMemoryInitNativeCapacity, restoreCompletedMemoryNativeCapacity } from "../services/memory-init-native-capacity.js";
+import { inspectMemoryLintExecutable, inspectMemoryGitExecutable } from "../services/memory-init-preflight.js";
+import { PreparedMemoryInitLintCapability } from "../services/memory-init-lint-capability.js";
+import { observeMemoryGitPolicySelection } from "../services/memory-init-git-policy.js";
+import { parseRuntimeBudget } from "../services/runtime-budget.js";
+import { launchAndObserveMemoryFlow } from "./memory-init.js";
+import { prepareMemoryUpgradeInvocation, assertMemoryInitInvocationReplay } from "./memory-init-invocation.js";
+import { askExecutorChoice } from "./executor-onboarding.js";
+import { parseOutputOptions } from "./output-options.js";
+import { prepareResponseDestination } from "./response-file.js";
+import { prepareFileBytes } from "./input-preparation.js";
+import { writePreparationError } from "./error-output.js";
+/** Upgrade never enters init's project publication path. Read-only original
+ * request lookup precedes ambient selection; writable stores are opened only
+ * after retaining the target/current selection, without initializing existing
+ * stores. Pristine stores use shared pair publication, never init documents.
+ * Storage-changing transitions must first settle their explicit migration.
+ */
+export async function runMemoryUpgradeCli(args, env = process.env, io = process) {
+    let context, effects = false;
+    try {
+        const output = parseOutputOptions(args), invocation = prepareMemoryUpgradeInvocation(output.args);
+        parseRuntimeBudget(env.DD_FLOW_RUNTIME_BUDGET);
+        if (output.responseFile)
+            prepareResponseDestination(output.responseFile);
+        const home = resolveDdFlowHome(env), scope = invocation.scope;
+        const reader = createContext(env, "read_existing");
+        let storage;
+        try {
+            storage = readUpgradeStorageReadiness(reader, scope);
+        }
+        finally {
+            reader.db.close?.();
+        }
+        const candidate = storage ? null : readMemoryUpgradeRequestCandidate(home, scope);
+        const original = storage?.receipt.selection?.request_input ?? candidate?.input;
+        if (storage && !original)
+            throw new AppError("memory_upgrade_original_request_required", "Historical storage metadata cannot select a fresh upgrade", 1, { effect: "no_effect" });
+        if (original) {
+            const objective = new TextDecoder("utf-8", { fatal: true, ignoreBOM: true }).decode(Buffer.from(original.intake_base64, "base64"));
+            const raw = readMemoryUpgradeRequestInput(original, scope, objective);
+            if (invocation.profileFile)
+                invocation.execution.rootProfile = readOperatorProfileInput(invocation.profileFile);
+            assertMemoryInitInvocationReplay(invocation, raw.selection, original.intake_sha256);
+            if (invocation.nativeConfigHome) {
+                const selected = storage?.selection?.payload.execution ?? readMemoryUpgradeSelection(home, scope)?.payload.execution;
+                const reference = selected?.snapshot.settings.delegation.native_capacity_receipt;
+                const encoded = selected?.receipt_blobs?.find(([sha]) => sha === reference?.sha256)?.[1];
+                if (!encoded || JSON.parse(Buffer.from(encoded, "base64").toString("utf8")).input.native_config_home !== invocation.nativeConfigHome)
+                    throw new AppError("memory_upgrade_request_conflict", "Original native configuration selection changed", 1, { effect: "no_effect" });
+            }
+            if (!storage && !readMemoryUpgradeSelection(home, scope)) {
+                // A raw candidate is not resolved selection authority. Resume only its
+                // original target/profile request; never replace it with new CLI input.
+                effects = true;
+                const native = raw.selection.execution.delegation?.mode === "native"
+                    ? await restoreCompletedMemoryNativeCapacity({ home, scope, env }) : undefined;
+                if (native && hybridDigest(native.reference) !== hybridDigest(raw.selection.execution.delegation?.nativeCapacityReceipt))
+                    throw new AppError("memory_upgrade_request_conflict", "Completed probe differs from the original request", 1, { effect: "unknown" });
+                PreparedMemoryUpgradeSelection.prepare(home, scope, candidate.candidate, { env, now: new Date().toISOString(),
+                    ...(native ? { receipts: native.receipts, receiptBytes: native.receiptBytes } : {}) }).retain();
+            }
+        }
+        else {
+            if (!invocation.intakeFile || !invocation.intakeSha256 || !invocation.gitPolicy)
+                throw new AppError("usage", "Fresh upgrade requires original intake file/hash and explicit Git policy", 2, { effect: "no_effect" });
+            const intake = prepareFileBytes(invocation.intakeFile, "original upgrade intake", 64 * 1024).bytes;
+            if (createHash("sha256").update(intake).digest("hex") !== invocation.intakeSha256)
+                throw new AppError("memory_upgrade_intake_changed", "Original intake differs from its declared hash", 2, { effect: "no_effect" });
+            let objective;
+            try {
+                objective = new TextDecoder("utf-8", { fatal: true, ignoreBOM: true }).decode(intake);
+            }
+            catch {
+                throw new AppError("usage", "Original upgrade intake must be UTF-8", 2, { effect: "no_effect" });
+            }
+            const setup = readSetupStatus(home), installation = setup.installation;
+            if (!installation || setup.installation_readiness !== "installed")
+                throw new AppError("memory_upgrade_setup_required", "Install the target release with setup before project upgrade", 1, { effect: "no_effect" });
+            const stdin = io.stdin ?? process.stdin;
+            const selected = await onboardExecutor({
+                ...(typeof invocation.execution.rootProfile === "string" ? { profileId: invocation.execution.rootProfile } : {}),
+                ...(invocation.profileFile ? { profileFile: invocation.profileFile } : {})
+            }, () => readOperatorProfiles(home), { allowSkip: false, nonInteractive: invocation.nonInteractive || output.json || output.progressJsonl
+                    || !stdin.isTTY || !io.stderr.isTTY }, settings => askExecutorChoice(settings, { stdin, stderr: io.stderr }, { allowSave: false, allowSkip: false }));
+            if (selected.source === "explicit-file" || selected.source === "explicit-profile")
+                invocation.execution.rootProfile = selected.profile;
+            else if (invocation.execution.rootProfile === undefined && selected.source === "explicit-id")
+                invocation.execution.rootProfile = selected.profile.id;
+            let native;
+            if (invocation.execution.delegation?.mode === "native") {
+                if (!invocation.allowLiveProbe)
+                    throw new AppError("usage", "Fresh native upgrade requires --allow-live-probe", 2, { effect: "no_effect" });
+                const source = PreparedInstalledFlowSource.fromInstalledRelease(home, installation.manifest_sha256, "mb-upgrade");
+                const engine = selectMemoryInitInstalledEngine(home, installation.manifest_sha256);
+                engine.admitMemoryUpgradeFlow(source);
+                if (!fs.existsSync(path.join(home, "db.sqlite")))
+                    assertMemoryInitStorePrerequisites(env, scope);
+                engine.qualifyMemoryUpgradeStorage(home, env.DD_FLOW_RESOURCE_HOME ?? home);
+                observeMemoryGitPolicySelection(env, { scope, gitExecutable: inspectMemoryGitExecutable(env).executable, selection: invocation.gitPolicy });
+                const lint = inspectMemoryLintExecutable(env);
+                PreparedMemoryInitLintCapability.prepareExecutable(lint.executable, lint.probe, env, { temporaryConfiguration: true });
+                const execution = FrozenGenericExecution.prepare(source.resolveRegisteredFlow(), readOperatorProfiles(home), {
+                    ...invocation.execution, delegation: { mode: "external", max_parallel: invocation.execution.delegation.max_parallel ?? 1 }
+                }, { requestId: scope.requestId, projectRoot: scope.projectRoot, workspace: scope.workspaceRoot });
+                prepareMemoryInitHarnessCommands({ ddFlowHome: home }, execution);
+                const snapshot = execution.snapshot(), profile = snapshot.profiles.find(entry => entry.id === snapshot.settings.root_profile).profile;
+                if (snapshot.profiles.some(entry => hybridDigest({ ...entry.profile, id: profile.id }) !== hybridDigest(profile)))
+                    throw new AppError("generic_execution_invalid", "Native delegation cannot change execution profiles", 2, { effect: "no_effect" });
+                effects = true;
+                native = await produceMemoryInitNativeCapacity({ home, scope, profile, maximum: invocation.execution.delegation.max_parallel ?? 1,
+                    ...(invocation.nativeConfigHome ? { nativeConfigHome: invocation.nativeConfigHome } : {}), allowLiveProbe: true, env,
+                    requestSha256: hybridDigest({ flow: "mb-upgrade", scope, execution: invocation.execution, gitPolicy: invocation.gitPolicy,
+                        objective, intake: invocation.intakeSha256, target: installation.manifest_sha256 }) });
+                invocation.execution.delegation.nativeCapacityReceipt = native.reference;
+            }
+            const raw = { schema_id: "dd-flow/memory-upgrade-request-selection@1", scope,
+                execution: invocation.execution, git_policy: invocation.gitPolicy, objective, engine_checksum: null,
+                receipts: [...native?.receipts ?? []], target_installation_sha256: installation.manifest_sha256 };
+            const prepared = prepareMemoryUpgradeRequestCandidate(home, scope, Buffer.from(JSON.stringify(raw)), intake);
+            effects = true;
+            prepared.retain();
+            PreparedMemoryUpgradeSelection.prepare(home, scope, prepared, { env, now: new Date().toISOString(),
+                ...(native ? { receipts: native.receipts, receiptBytes: native.receiptBytes } : {}) }).retain();
+        }
+        if (!storage) {
+            const selected = restoreMemoryUpgradeSelection(home, scope);
+            if (!fs.existsSync(path.join(home, "db.sqlite"))) {
+                assertMemoryUpgradeProjectCurrent(selected, scope, env);
+                effects = true;
+                // Shared store creation owns pristine/replay checks and never writes
+                // project documents. Existing stores still take explicit migration.
+                const fresh = openMemoryInitStores(env, { scope, selectionSha256: selected.sha256 });
+                fresh.context.db.close?.();
+            }
+            try {
+                selected.engine.admitMemoryUpgradeStorage(home, env.DD_FLOW_RESOURCE_HOME ?? home);
+            }
+            catch (error) {
+                if (!(error instanceof AppError) || error.code !== "frozen_engine_storage_incompatible")
+                    throw error;
+                // Retain only the selected engine's explicit plan. Never apply it as a
+                // side effect of starting upgrade or open the old stores for writes.
+                effects = true;
+                const planned = selected.engine.transitionMemoryUpgradeStorage({ home, resourceHome: env.DD_FLOW_RESOURCE_HOME ?? home,
+                    scope, selectionSha256: selected.sha256, action: "plan" });
+                throw new AppError("memory_upgrade_storage_transition_required", "Drain runtime owners, apply the retained storage plan, then repeat this exact upgrade request", 1, { effect: "partial", storage_effect: "no_effect", migration: planned.result });
+            }
+        }
+        context = createContext(env, "prepared_existing", undefined, { resourceDatabaseMode: "prepared_existing" });
+        effects = true;
+        if (!storage) {
+            registerMemoryUpgradeProject(context, scope);
+            PreparedUpgradeStorageReadiness.prepareFromSelection(context, scope).apply(context);
+        }
+        const started = startMemoryUpgradeRun(context, scope);
+        return await launchAndObserveMemoryFlow(context, invocation, started, "mb-upgrade", output, env, io);
+    }
+    catch (error) {
+        const record = errorRecord(error);
+        if (effects)
+            record.details = { ...record.details, effect: record.details.effect === "partial" ? "partial" : "unknown", next_action: "observe_or_reconcile_exact_request" };
+        writePreparationError(io, args, record);
+        return record.exitCode;
+    }
+    finally {
+        context?.db.close?.();
+    }
+}