@deksden-com/dd-flow-cli 0.9.0-beta.16 → 0.9.0-beta.160

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

@@ -0,0 +1,54 @@
+import { prepareCommandRoute } from "./command-inputs.js";
+import { parseOutputOptions } from "./output-options.js";
+import { readBoundedUtf8Stream, prepareJsonText } from "./input-preparation.js";
+import { PreparedInstalledFlowSource } from "../services/installed-flow-source.js";
+import { PreparedProjectFlowSource } from "../services/project-flow-source.js";
+import { hybridDigest } from "../services/hybrid-contracts.js";
+import { AppError, errorRecord } from "../shared/errors.js";
+import { writePreparationError } from "./error-output.js";
+import { memoryInitStartupInputSchemas } from "../services/memory-init-startup-custody.js";
+import { isDiagnosticFlow } from "../domain/diagnostic-flows.js";
+import { isDeliveryFlow } from "../domain/delivery-flows.js";
+/** Executing engine's real handler admission only. The caller owns independent
+ * release/source selection; this command never opens storage or creates a RUN. */
+export async function runMemoryFlowAdmissionCli(args, io = process) {
+    try {
+        const output = parseOutputOptions(args), route = prepareCommandRoute(output.args);
+        if (route.key !== "runtime flow admit" || output.responseFile || output.progressJsonl) {
+            throw new AppError("usage", "Flow admission accepts bounded stdin and stdout output only", 2, { effect: "no_effect" });
+        }
+        const input = prepareJsonText(await readBoundedUtf8Stream(io.stdin, 64 * 1024 * 1024), { file: "<stdin>", label: "flow admission" }).value;
+        if (!input || typeof input !== "object" || Array.isArray(input)
+            || !["source,source_sha256", "source,source_sha256,startup_input_schema"].includes(Object.keys(input).sort().join())) {
+            throw new AppError("usage", "Flow admission requires an exact source snapshot and independent digest", 2, { effect: "no_effect" });
+        }
+        const selected = input;
+        const operation = route.parsed.options.get("operation")?.[0] ?? "";
+        const flowId = isDeliveryFlow(operation) ? operation : operation === "interactive" ? "interactive" : operation === "review-fix" ? "review-fix" : operation === "mb-fix" ? "mb-fix" : operation === "mb-distill" ? "mb-distill" : isDiagnosticFlow(operation) ? operation : operation === "memory-upgrade" ? "mb-upgrade" : "mb-init";
+        const startupSchema = memoryInitStartupInputSchemas.find(schema => schema === selected.startup_input_schema);
+        if (Object.hasOwn(selected, "startup_input_schema") && (startupSchema === undefined || flowId !== "mb-init")) {
+            throw new AppError("usage", "Executing engine does not support the requested startup input schema", 2, { effect: "no_effect" });
+        }
+        if (typeof selected.source_sha256 !== "string" || !/^[a-f0-9]{64}$/.test(selected.source_sha256)) {
+            throw new AppError("usage", "Flow admission requires a SHA-256 source digest", 2, { effect: "no_effect" });
+        }
+        const source = flowId === "interactive"
+            ? PreparedProjectFlowSource.restoreRetained(selected.source, selected.source_sha256)
+            : PreparedInstalledFlowSource.restoreRetained(selected.source, selected.source_sha256);
+        const flow = source.resolveRegisteredFlow();
+        if (flow.descriptor.id !== flowId)
+            throw new AppError("usage", "Flow source does not match the requested engine admission operation", 2, { effect: "no_effect" });
+        const facts = { schema_id: isDeliveryFlow(flowId) ? "dd-flow/delivery-engine-flow@1" : flowId === "interactive" ? "dd-flow/interactive-engine-flow@1" : flowId === "review-fix" ? "dd-flow/review-fix-engine-flow@1" : flowId === "mb-fix" ? "dd-flow/memory-fix-engine-flow@1" : flowId === "mb-distill" ? "dd-flow/distill-engine-flow@1" : isDiagnosticFlow(flowId) ? "dd-flow/diagnostic-engine-flow@1" : flowId === "mb-upgrade" ? "dd-flow/memory-upgrade-engine-flow@1"
+                : startupSchema === undefined ? "dd-flow/memory-init-engine-flow@1" : "dd-flow/memory-init-engine-flow@2",
+            ...(startupSchema === undefined ? {} : { startup_input_schema: startupSchema }),
+            flow_id: flowId, source_sha256: source.sha256,
+            descriptor_sha256: source.descriptorReference().sha256, stages: flow.descriptor.stages.map(stage => stage.id) };
+        io.stdout.write(`${JSON.stringify({ ok: true, action: "runtime_flow_admit", facts, sha256: hybridDigest(facts) }, null, output.json ? undefined : 2)}\n`);
+        return 0;
+    }
+    catch (error) {
+        const record = errorRecord(error);
+        writePreparationError(io, args, record);
+        return record.exitCode;
+    }
+}

package/dist/cli/memory-init-invocation.js

@@ -0,0 +1,85 @@
+import path from "node:path";
+import { AppError } from "../shared/errors.js";
+import { hybridDigest } from "../services/hybrid-contracts.js";
+import { prepareCommandRoute } from "./command-inputs.js";
+const stages = new Set(["preflight", "discover", "compose", "verify", "review", "finish"]);
+const upgradeStages = new Set(["preflight", "diff-analysis", "upgrade", "verify", "review", "finish"]);
+function refuse(message) {
+    throw new AppError("usage", message, 2, { phase: "prepare", effect: "no_effect" });
+}
+/** Pure invocation preparation. File bytes, stored replay and productive
+ * authority remain with their existing owners; no ambient defaults here. */
+export function prepareMemoryInitInvocation(args) {
+    return prepareMemoryInvocation(args, "mb-init");
+}
+export function prepareMemoryUpgradeInvocation(args) {
+    return prepareMemoryInvocation(args, "mb-upgrade");
+}
+function prepareMemoryInvocation(args, flowId) {
+    const route = prepareCommandRoute(args);
+    if (!(flowId === "mb-init" ? ["init", "flow mb-init"] : ["upgrade", "flow mb-upgrade"]).includes(route.key))
+        refuse(`Use ${flowId === "mb-init" ? "init" : "upgrade"} or flow ${flowId}`);
+    const options = route.parsed.options;
+    const value = (name) => options.get(name)?.[0];
+    const scope = { projectRoot: value("project-root"), workspaceRoot: value("workspace-root"), requestId: value("request-id") };
+    if (![scope.projectRoot, scope.workspaceRoot].every(path.isAbsolute)
+        || !/^[A-Za-z0-9][A-Za-z0-9_.-]{0,95}$/.test(scope.requestId))
+        refuse("Init needs absolute roots and a bounded request id");
+    const execution = {};
+    const maxParallel = value("max-parallel");
+    const delegation = value("delegation"), nativeConfigHome = value("native-config-home");
+    if (maxParallel !== undefined || delegation !== undefined)
+        execution.delegation = {
+            mode: delegation === "native" ? "native" : "external", max_parallel: Number(maxParallel ?? 1)
+        };
+    if (delegation === "native" && Number(maxParallel ?? 1) > 15)
+        refuse("Native concurrency must be 1..15");
+    if (nativeConfigHome !== undefined && (!path.isAbsolute(nativeConfigHome) || delegation !== "native")
+        || options.has("allow-live-probe") && delegation !== "native")
+        refuse("Native probe options require explicit native delegation; an optional config home must be absolute");
+    const profile = value("profile");
+    const profileFile = value("profile-file");
+    if (profileFile !== undefined && (!path.isAbsolute(profileFile) || profile !== undefined))
+        refuse("--profile-file must be absolute and is exclusive with --profile");
+    if (profile !== undefined)
+        execution.rootProfile = profile;
+    for (const assignment of options.get("stage-profile") ?? []) {
+        const at = assignment.indexOf("="), stage = assignment.slice(0, at), profile = assignment.slice(at + 1);
+        if (at < 1 || !(flowId === "mb-init" ? stages : upgradeStages).has(stage) || !profile.trim() || execution.stageProfiles?.[stage] !== undefined)
+            refuse("--stage-profile requires a unique stage=profile assignment");
+        (execution.stageProfiles ??= {})[stage] = profile;
+    }
+    if (options.has("work-profile")) {
+        execution.workProfiles = [...options.get("work-profile")];
+        if (new Set(execution.workProfiles).size !== execution.workProfiles.length)
+            refuse("--work-profile must not repeat a profile");
+    }
+    const intakeFile = value("intake-file"), intakeSha256 = value("intake-sha256");
+    if (Boolean(intakeFile) !== Boolean(intakeSha256)
+        || intakeSha256 !== undefined && !/^[a-f0-9]{64}$/.test(intakeSha256)
+        || intakeFile !== undefined && !path.isAbsolute(intakeFile))
+        refuse("Original intake needs an absolute --intake-file and --intake-sha256 pair");
+    const gitRoute = value("git-route"), integrationBranch = value("integration-branch");
+    if (Boolean(gitRoute) !== Boolean(integrationBranch))
+        refuse("--git-route and --integration-branch must be supplied together");
+    const gitPolicy = gitRoute === undefined ? undefined : {
+        route: gitRoute, integrationBranch: integrationBranch
+    };
+    if (options.has("prepare-only") && options.has("detach"))
+        refuse("--prepare-only does not launch a controller and is exclusive with --detach");
+    return { scope, execution, gitPolicy, intakeFile, intakeSha256, profileFile, nativeConfigHome, allowLiveProbe: options.has("allow-live-probe"), nonInteractive: options.has("non-interactive"), detach: options.has("detach"), prepareOnly: options.has("prepare-only") };
+}
+/** Omitted selectors replay the retained choices, never current aliases.
+ * Supplied selectors must equal the original raw selection, not merely resolve
+ * to today's equivalent profile. Intake paths are locators, hashes bind bytes. */
+export function assertMemoryInitInvocationReplay(invocation, original, intakeSha256) {
+    if (hybridDigest(invocation.scope) !== hybridDigest(original.scope)
+        || invocation.intakeSha256 !== undefined && invocation.intakeSha256 !== intakeSha256
+        || invocation.gitPolicy !== undefined && hybridDigest(invocation.gitPolicy) !== hybridDigest(original.git_policy)
+        || Object.entries(invocation.execution).some(([key, value]) => !Object.hasOwn(original.execution, key)
+            || hybridDigest(value) !== hybridDigest(key === "delegation" && invocation.execution.delegation?.mode === "native"
+                ? { mode: original.execution.delegation?.mode, max_parallel: original.execution.delegation?.max_parallel }
+                : original.execution[key]))) {
+        throw new AppError("memory_init_request_conflict", "Request id belongs to different original init inputs", 1, { effect: "no_effect", next_action: "replay_exact_request_or_choose_new_id" });
+    }
+}

package/dist/cli/memory-init.js

@@ -0,0 +1,250 @@
+import { createHash } from "node:crypto";
+import { spawnSync } from "node:child_process";
+import { setTimeout as delay } from "node:timers/promises";
+import { Writable } from "node:stream";
+import { once } from "node:events";
+import { createContext } from "../runtime/context.js";
+import { AppError, errorRecord } from "../shared/errors.js";
+import { hybridDigest } from "../services/hybrid-contracts.js";
+import { readMemoryInitStartupInput } from "../services/memory-init-startup-custody.js";
+import { readMemoryInitRequestInput } from "../services/memory-init-request-input.js";
+import { prepareMemoryInitFreshRequest, prepareMemoryInitSelection, startMemoryInitRun } from "../services/memory-init-start.js";
+import { PreparedMemoryInitLintCapability } from "../services/memory-init-lint-capability.js";
+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, prepareMemoryUpgradeControllerStart, prepareInteractiveControllerStart, prepareDeliveryControllerStart } from "../services/memory-init-controller-start.js";
+import { isDeliveryFlow } from "../domain/delivery-flows.js";
+import { runControllerStatus } from "../services/run-controller.js";
+import { requireRun } from "../services/run-controller-state.js";
+import { requireProjectByRoot } from "../services/projects.js";
+import { routeArgsThroughEngine } from "../services/engines.js";
+import { parseRuntimeBudget } from "../services/runtime-budget.js";
+import { prepareFileBytes } from "./input-preparation.js";
+import { prepareMemoryInitInvocation, assertMemoryInitInvocationReplay } from "./memory-init-invocation.js";
+import { parseOutputOptions } from "./output-options.js";
+import { prepareResponseDestination, writeResponseFile } from "./response-file.js";
+import { writePreparationError } from "./error-output.js";
+import { onboardExecutor } from "../services/executor-onboarding.js";
+import { readOperatorProfiles, readOperatorProfileInput } from "../services/operator-profiles.js";
+import { resolveDdFlowHome } from "../storage/paths.js";
+import { askExecutorChoice } from "./executor-onboarding.js";
+import { isSourceSnapshotFlow } from "../domain/source-snapshot-flows.js";
+import { prepareDiagnosticControllerStart, prepareMemoryFixControllerStart } from "../services/memory-init-controller-start.js";
+/** Backpressure bounds the observing client's output; closing it never controls the RUN. */
+export async function writeMemoryInitObservation(stdout, text) {
+    const disconnected = () => Boolean(stdout.destroyed);
+    if (disconnected())
+        return false;
+    const waiting = new AbortController();
+    try {
+        // Observe errors even when write returns true: a short pipe write can
+        // report EPIPE asynchronously. Writable emits callback errors as events.
+        const closed = once(stdout, "close", { signal: waiting.signal });
+        const written = new Promise(resolve => {
+            stdout.write(text, error => { if (!error)
+                resolve(); });
+        });
+        await Promise.race([written, closed]);
+        return !disconnected();
+    }
+    catch (error) {
+        if (error.code === "EPIPE")
+            return false;
+        throw error;
+    }
+    finally {
+        waiting.abort();
+    }
+}
+/** Both public spellings enter this owner. The controller, never this observer,
+ * owns Sessions and productive dispatch; disconnect does not request stop. */
+export async function runMemoryInitCli(args, env = process.env, io = process) {
+    let context;
+    let effects = false;
+    try {
+        const output = parseOutputOptions(args), invocation = prepareMemoryInitInvocation(output.args);
+        parseRuntimeBudget(env.DD_FLOW_RUNTIME_BUDGET);
+        if (output.responseFile)
+            prepareResponseDestination(output.responseFile);
+        const reader = createContext(env, "read_existing");
+        let retained;
+        try {
+            retained = readMemoryInitStartupInput(reader, invocation.scope);
+        }
+        finally {
+            reader.db.close?.();
+        }
+        let prepared;
+        if (retained) {
+            if (retained.payload.schema_id !== "dd-flow/memory-init-startup-input@3")
+                throw new AppError("memory_init_original_request_required", "Public init replay requires independently retained original input", 1, { effect: "no_effect" });
+            const raw = readMemoryInitRequestInput(retained.payload.request_input, invocation.scope, retained.payload.objective);
+            // A supplied file is an explicit selector and must still match. Omitted
+            // files never reopen mutable profile inputs during exact replay.
+            if (invocation.profileFile)
+                invocation.execution.rootProfile = readOperatorProfileInput(invocation.profileFile);
+            assertMemoryInitInvocationReplay(invocation, raw.selection, retained.payload.request_input.intake_sha256);
+            if (invocation.nativeConfigHome) {
+                const reference = retained.payload.execution.snapshot.settings.delegation.native_capacity_receipt;
+                const encoded = retained.payload.execution.receipt_blobs?.find(([checksum]) => checksum === reference?.sha256)?.[1];
+                if (!encoded || JSON.parse(Buffer.from(encoded, "base64").toString("utf8")).input.native_config_home !== invocation.nativeConfigHome)
+                    throw new AppError("memory_init_request_conflict", "Native private configuration selection changed", 1, { effect: "no_effect" });
+            }
+            context = openMemoryInitStores(env, { scope: invocation.scope, selectionSha256: hybridDigest(raw.selection) }).context;
+        }
+        else {
+            if (!invocation.intakeFile || !invocation.intakeSha256 || !invocation.gitPolicy)
+                throw new AppError("usage", "Fresh init requires original intake file/hash and explicit Git route/integration branch", 2, { phase: "prepare", effect: "no_effect" });
+            const raw = prepareFileBytes(invocation.intakeFile, "original init intake", 64 * 1024).bytes;
+            if (createHash("sha256").update(raw).digest("hex") !== invocation.intakeSha256)
+                throw new AppError("memory_init_intake_changed", "Original intake bytes differ from --intake-sha256", 2, { phase: "prepare", effect: "no_effect" });
+            let objective;
+            try {
+                objective = new TextDecoder("utf-8", { fatal: true, ignoreBOM: true }).decode(raw);
+            }
+            catch {
+                throw new AppError("usage", "Original init intake must be UTF-8", 2, { phase: "prepare", effect: "no_effect" });
+            }
+            // Controller birth/lease confirmation uses this OS observation. Known
+            // inability must refuse before candidate, stores or project publication.
+            const identity = spawnSync("ps", ["-o", "lstart=", "-p", String(process.pid)], { env: { ...env, TZ: "UTC", LC_ALL: "C" }, encoding: "utf8", timeout: 1000, shell: false, windowsHide: true });
+            if (identity.error || identity.signal || identity.status !== 0 || !identity.stdout.trim())
+                throw new AppError("memory_init_runtime_unavailable", "Controller physical identity observation is unavailable", 1, { phase: "prepare", effect: "no_effect", next_action: "restore_system_process_observation" });
+            const stdin = io.stdin ?? process.stdin;
+            const nonInteractive = invocation.nonInteractive || output.json || output.progressJsonl
+                || !stdin.isTTY || !io.stderr.isTTY;
+            const selected = await onboardExecutor({
+                ...(typeof invocation.execution.rootProfile === "string" ? { profileId: invocation.execution.rootProfile } : {}),
+                ...(invocation.profileFile ? { profileFile: invocation.profileFile } : {})
+            }, () => readOperatorProfiles(resolveDdFlowHome(env)), { allowSkip: false, nonInteractive }, 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 init requires --allow-live-probe", 2, { effect: "no_effect" });
+                const admissionReader = createContext(env, "read_existing");
+                let profile;
+                try {
+                    const baseline = prepareMemoryInitSelection(admissionReader, invocation.scope, { execution: {
+                            ...invocation.execution, delegation: { mode: "external", max_parallel: invocation.execution.delegation.max_parallel ?? 1 }
+                        }, gitPolicy: invocation.gitPolicy, objective });
+                    PreparedMemoryInitLintCapability.prepare(baseline.target, env);
+                    PreparedMemoryInitWorktrunkCapability.prepare(baseline.target, env);
+                    baseline.engine.admitMemoryInitFlow(baseline.source, "dd-flow/memory-init-startup-input@3");
+                    assertMemoryInitStorePrerequisites(env, invocation.scope);
+                    const snapshot = baseline.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" });
+                }
+                finally {
+                    admissionReader.db.close?.();
+                }
+                // From here a failed reply cannot imply no effect: daemon/child custody
+                // is independent from later startup publication and RUN allocation.
+                effects = true;
+                native = await produceMemoryInitNativeCapacity({ home: resolveDdFlowHome(env), scope: invocation.scope, profile,
+                    maximum: invocation.execution.delegation.max_parallel ?? 1,
+                    ...(invocation.nativeConfigHome !== undefined ? { nativeConfigHome: invocation.nativeConfigHome } : {}),
+                    allowLiveProbe: invocation.allowLiveProbe, env, requestSha256: hybridDigest({ scope: invocation.scope,
+                        execution: invocation.execution, gitPolicy: invocation.gitPolicy, objective, intake: invocation.intakeSha256 }) });
+                invocation.execution.delegation.nativeCapacityReceipt = native.reference;
+            }
+            const owner = prepareMemoryInitFreshRequest(env, invocation.scope, { execution: invocation.execution, gitPolicy: invocation.gitPolicy, objective,
+                ...(native ? { receipts: native.receipts, receiptBytes: native.receiptBytes } : {}) }, raw);
+            context = owner.context;
+            prepared = owner.prepared;
+        }
+        // Beyond this boundary, absence of a success receipt is not no-effect.
+        effects = true;
+        const started = startMemoryInitRun(context, invocation.scope, prepared ? () => prepared : undefined);
+        return await launchAndObserveMemoryFlow(context, invocation, started, "mb-init", 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?.();
+    }
+}
+/** 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 = `flow_${flowId.replaceAll("-", "_")}`;
+    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 = isDeliveryFlow(flowId) ? prepareDeliveryControllerStart(context, invocation.scope, flowId) : flowId === "interactive" ? prepareInteractiveControllerStart(context, invocation.scope) : flowId === "mb-fix" ? prepareMemoryFixControllerStart(context, invocation.scope) : isSourceSnapshotFlow(flowId) ? prepareDiagnosticControllerStart(context, invocation.scope, flowId)
+        : (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

@@ -0,0 +1,54 @@
+import fs from "node:fs";
+import path from "node:path";
+import { prepareCommandRoute } from "./command-inputs.js";
+import { parseOutputOptions } from "./output-options.js";
+import { createContext } from "../runtime/context.js";
+import { getResourceDatabase } from "../storage/database.js";
+import { withStoreCleanup } from "../storage/native-cleanup.js";
+import { PreparedMemoryInitRuntimeStorage } from "../services/memory-init-storage.js";
+import { PreparedMemoryInitResourceStorage } from "../services/memory-init-resource-storage.js";
+import { hybridDigest } from "../services/hybrid-contracts.js";
+import { AppError, errorRecord } from "../shared/errors.js";
+import { writePreparationError } from "./error-output.js";
+/** Selected engine's non-migrating operation admission. No AppContext initialize. */
+export function runMemoryStorageAdmissionCli(args, env = process.env, io = process) {
+    try {
+        const output = parseOutputOptions(args), route = prepareCommandRoute(output.args);
+        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" });
+        }
+        const file = path.join(home, "db.sqlite"), owner = fs.lstatSync(file);
+        if (!owner.isFile() || owner.nlink !== 1)
+            throw new AppError("run_storage_unprepared", "RUN storage must be a regular single-linked file", 1, { effect: "no_effect" });
+        const resource = PreparedMemoryInitResourceStorage.prepare({ ddFlowHome: home, env });
+        const context = createContext(env, "prepared_existing");
+        const facts = withStoreCleanup(() => {
+            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) {
+                    throw new AppError("store_writer_incompatible", "Resource connection writer differs from admitted storage", 1, { effect: "no_effect" });
+                }
+                resource.revalidate({ ddFlowHome: home, env });
+                const current = fs.lstatSync(file);
+                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/${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?.());
+        io.stdout.write(`${JSON.stringify({ ok: true, action: "runtime_storage_admit", facts, sha256: hybridDigest(facts) }, null, output.json ? undefined : 2)}\n`);
+        return 0;
+    }
+    catch (error) {
+        const record = errorRecord(error);
+        writePreparationError(io, args, record);
+        return record.exitCode;
+    }
+}

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 });
+    }
+}