@deksden-com/dd-flow-cli 0.9.0-beta.136 → 0.9.0-beta.138

package/dist/services/execution-policy.js

@@ -5,6 +5,8 @@ import { AppError } from "../shared/errors.js";
 import { harnessKey } from "./harness-config.js";
 import { vnextStages } from "../domain/stage-catalog.js";
 import { prepareFileBytes, prepareJsonText } from "../cli/input-preparation.js";
+import { operatorSettingsPath, readOperatorProfiles, readOperatorProfileInput, resolveOperatorProfile } from "./operator-profiles.js";
+import { selectOnboardingExecutor } from "./executor-onboarding.js";
 /** Read once so the frozen policy and its provenance describe the same bytes. */
 export function loadExecutionRoutingInput(file) {
     const { file: source_path, bytes } = prepareFileBytes(file, "execution routing");
@@ -48,23 +50,20 @@ export function isExecutionRouting(value) {
 export function loadAgentProfile(ddFlowHome, id) {
     if (typeof id !== "string" || !/^[A-Za-z0-9][A-Za-z0-9._-]*$/.test(id))
         throw new AppError("agent_profile_invalid", "Agent profile id is invalid", 2, { id });
+    if (fs.existsSync(operatorSettingsPath(ddFlowHome)))
+        return resolveOperatorProfile(readOperatorProfiles(ddFlowHome), id);
     const file = path.join(ddFlowHome, "agent-profiles", `${id}.json`);
-    let value;
+    if (!fs.existsSync(file))
+        throw new AppError("agent_profile_missing", "Agent profile is unavailable", 1, { id });
+    let profile;
     try {
-        value = JSON.parse(fs.readFileSync(file, "utf8"));
+        profile = readOperatorProfileInput(file);
     }
-    catch (cause) {
-        throw new AppError("agent_profile_missing", "Agent profile is unavailable", 1, { id, file, cause: String(cause) });
+    catch {
+        throw new AppError("agent_profile_invalid", "Agent profile must be a bounded valid regular JSON file", 2, { id });
     }
-    if (!value || typeof value !== "object" || Array.isArray(value))
-        throw new AppError("agent_profile_invalid", "Agent profile must be an object", 2, { id, file });
-    const profile = value;
-    if (profile.schema_id !== "dd-flow/agent-profile@1" || profile.id !== id
-        || Object.keys(profile).some(key => !["schema_id", "id", "harness", "provider", "model", "reasoning", "mode", "permission"].includes(key))
-        || !["codex", "zcode", "agy", "opencode", "grok", "droid"].includes(String(profile.harness))
-        || !nonempty(profile.provider) || !nonempty(profile.model) || !nonempty(profile.reasoning) || !nonempty(profile.mode)
-        || (profile.permission !== "allow" && profile.permission !== "deny")) {
-        throw new AppError("agent_profile_invalid", "Agent profile does not match dd-flow/agent-profile@1", 2, { id, file });
+    if (profile.id !== id) {
+        throw new AppError("agent_profile_invalid", "Agent profile does not match its selected ID", 2, { id });
     }
     // Only execution settings enter RUN evidence; never copy arbitrary profile fields.
     return { schema_id: profile.schema_id, id, harness: profile.harness, provider: profile.provider, model: profile.model, reasoning: profile.reasoning, mode: profile.mode, permission: profile.permission };
@@ -73,10 +72,16 @@ export function snapshotAgentProfiles(ddFlowHome, policy) {
     if (!isExecutionRouting(policy))
         throw new AppError("execution_profile_invalid", "Execution routing contains an invalid stage, profile or delegation policy", 2);
     const profiles = Object.create(null);
+    const settings = fs.existsSync(operatorSettingsPath(ddFlowHome)) ? readOperatorProfiles(ddFlowHome) : undefined;
     for (const override of [policy, ...Object.values(policy.stage_overrides ?? {})]) {
         for (const id of [override.agent_profile_id, override.delegation?.agent_profile_id]) {
-            if (id !== undefined && !Object.hasOwn(profiles, id))
-                profiles[id] = loadAgentProfile(ddFlowHome, id);
+            if (id !== undefined && !Object.hasOwn(profiles, id)) {
+                const profile = settings ? selectOnboardingExecutor({}, () => settings, { allowSkip: false, projectProfileId: id }).profile : loadAgentProfile(ddFlowHome, id);
+                profiles[id] = profile;
+                // Routing labels may be aliases. Default worker resolution uses the
+                // complete coordinator's canonical ID, which must also be frozen.
+                profiles[profile.id] = profile;
+            }
         }
     }
     // Validate every declared route now, including stages not reached by this run.
@@ -177,5 +182,4 @@ export function validateExecutionOverride(value) {
     if (override.delegation !== undefined)
         validateDelegation(override.delegation);
 }
-function nonempty(value) { return typeof value === "string" && Boolean(value.trim()); }
 function digest(value) { return crypto.createHash("sha256").update(JSON.stringify(value)).digest("hex"); }

package/dist/services/external-work-launch.js

@@ -18,6 +18,10 @@ import { qualifyAgyHooks } from "../harness-runtime/lib/dd-agy-daemon.mjs";
 import { lifecycleRetryInstruction } from "../harness-runtime/lib/delegation-instructions.mjs";
 import { continueCodexCapacity } from "./codex-capacity.js";
 import { errorRecord } from "./run-controller-state.js";
+import { readFlowRunExecutionBundle } from "./runs.js";
+import { stageWorkIds } from "./stage-work-graph.js";
+import { hybridDigest } from "./hybrid-contracts.js";
+import { prepareMemoryRepairDispatchFromStage, prepareMemorySecondRepairDispatchFromStage, prepareExternalMemoryRepairCopyFromStage, prepareMemorySecondRepairLaunchFromStage } from "./memory-review-handler.js";
 /**
  * Creates an external provider root for one already-created Work.  The launch
  * is not a Work claim: only the worker's trusted `work start` hook binds it.
@@ -38,8 +42,6 @@ export async function launchExternalWork(context, input) {
         throw new AppError("invalid_run_state", "External Work dispatch requires a running RUN", 2, { run_id: work.run_id, status: run.status });
     const generation = assertRunMutationAllowed(context, work.project_id, work.run_id);
     const snapshot = JSON.parse(run.index_json);
-    if (!snapshot.execution_profile?.agent_profiles)
-        throw new AppError("execution_profile_not_frozen", "External dispatch requires a RUN with frozen agent profiles; recreate the RUN with the current engine", 1, { work_id: work.work_id });
     const override = workOverride(work.payload_json);
     const policy = snapshot.execution_profile?.settings?.execution ?? {};
     const stage = snapshot.current_stage ?? [...(snapshot.stage_runs ?? [])].reverse().find((entry) => entry.status === "running")?.stage;
@@ -47,12 +49,66 @@ export async function launchExternalWork(context, input) {
         throw new AppError("execution_stage_mismatch", "Requested stage does not match the RUN's current stage", 2, { requested_stage: input.stage, current_stage: stage ?? null });
     if (!stage && Object.keys(policy.stage_overrides ?? {}).length)
         throw new AppError("execution_stage_missing", "Stage overrides require an authoritative RUN stage", 1, { run_id: work.run_id });
-    const resolved = resolveExecutionPolicy({ ddFlowHome: context.ddFlowHome, policy, profiles: snapshot.execution_profile.agent_profiles, ...(stage ? { stage } : {}), ...(override ? { work: override } : {}) });
+    const bundle = readFlowRunExecutionBundle(context, { projectRoot: run.project_root, runId: work.run_id });
+    let resolved;
+    if (bundle) {
+        if (!stage)
+            throw new AppError("execution_stage_missing", "Bound Work requires an authoritative RUN stage", 1);
+        if (snapshot.current_stage !== stage || !snapshot.stage_runs?.some(entry => entry.stage === stage && entry.status === "running")
+            || !stageWorkIds(context, work.project_id, work.run_id, stage).has(work.work_id)) {
+            throw new AppError("execution_stage_mismatch", "Bound Work does not belong to the active running stage", 2);
+        }
+        if (override?.delegation !== undefined)
+            throw new AppError("generic_execution_invalid", "Work cannot replace the RUN's frozen delegation", 2);
+        const route = bundle.execution.work(stage, override?.agent_profile_id);
+        const selected = { coordinator: route.coordinator, worker: route.worker,
+            delegation: { mode: route.delegation.mode, max_parallel: route.delegation.mode === "external" ? route.delegation.max_parallel : null } };
+        resolved = { ...selected, profile_hash: crypto.createHash("sha256").update(JSON.stringify(selected)).digest("hex") };
+    }
+    else {
+        if (!snapshot.execution_profile?.agent_profiles)
+            throw new AppError("execution_profile_not_frozen", "External dispatch requires a RUN with frozen agent profiles; recreate the RUN with the current engine", 1, { work_id: work.work_id });
+        resolved = resolveExecutionPolicy({ ddFlowHome: context.ddFlowHome, policy, profiles: snapshot.execution_profile.agent_profiles, ...(stage ? { stage } : {}), ...(override ? { work: override } : {}) });
+    }
     if (resolved.delegation.mode !== "external")
         throw new AppError("external_launch_not_selected", "This Work's frozen policy selects native delegation", 2, { work_id: work.work_id });
+    let payload = null;
+    try {
+        payload = work.payload_json ? JSON.parse(work.payload_json) : null;
+    }
+    catch { /* Legacy non-memory payload handling remains owned by the Work registry. */ }
+    const repairWave = payload?.kind === "memory-repair" ? payload.memory_repair?.wave : undefined;
+    if (payload?.kind === "memory-repair" && (payload.read_only !== false || ![1, 2].includes(repairWave ?? 0)
+        || bundle?.descriptor.descriptor.id !== "mb-init" || stage !== "review")) {
+        throw new AppError("memory_repair_launch_invalid", "Repair dispatch requires its registered memory review wave", 2, { phase: "prepare", effect: "no_effect" });
+    }
+    const repairScope = { projectRoot: run.project_root, runId: work.run_id, workId: work.work_id };
+    const prepareRepairPacket = repairWave === 1 ? prepareMemoryRepairDispatchFromStage : prepareMemorySecondRepairDispatchFromStage;
+    const repairPacket = repairWave ? prepareRepairPacket(context, repairScope) : null;
+    const assertRepairPacket = (effect = "no_effect") => {
+        if (!repairPacket)
+            return;
+        try {
+            const expected = { coordinator: resolved.coordinator, worker: resolved.worker, delegation: resolved.delegation };
+            const actual = { coordinator: repairPacket.profile.coordinator, worker: repairPacket.profile.worker, delegation: repairPacket.profile.delegation };
+            if (repairPacket.work_id !== work.work_id || repairPacket.profile.profile_hash !== resolved.profile_hash
+                || hybridDigest(actual) !== hybridDigest(expected) || hybridDigest(prepareRepairPacket(context, repairScope)) !== hybridDigest(repairPacket)) {
+                throw new AppError("memory_repair_launch_invalid", "Repair ready copy or frozen route changed before dispatch", 2, { phase: "prepare", effect: "no_effect" });
+            }
+        }
+        catch (error) {
+            if (effect === "partial")
+                throw new AppError("memory_repair_launch_pending", "Repair launch files are retained but dispatch custody changed", 1, { effect, work_id: work.work_id, operation_id: operationId, state_dir: root, next_action: "reconcile_exact_request", cause: errorRecord(error) });
+            throw error;
+        }
+    };
+    assertRepairPacket();
     const agyWorker = runtimeHarness(resolved.worker) === "antigravity-cli";
+    if (agyWorker && repairPacket)
+        throw new AppError("memory_repair_launch_invalid", "Repair copy hook qualification is required before Antigravity dispatch", 2, { phase: "prepare", effect: "no_effect" });
     if (agyWorker)
         await qualifyAgyHooks(run.workspace_root);
+    assertRepairPacket();
     const operationId = `OPR-${crypto.randomUUID()}`;
     const root = path.join(run.run_root, "external-launches", operationId);
     const journal = path.join(root, "adapter.events.jsonl");
@@ -76,8 +132,10 @@ export async function launchExternalWork(context, input) {
         reviewCopy = { root: path.relative(run.run_root, isolatedWorkspace).split(path.sep).join("/"), sha256: reviewExecutionCopyHash(isolatedWorkspace, run.workspace_root, true, reviewInputs, reviewBase), source_sha256: after };
     }
     const now = context.now();
-    const flowExecutable = prepareHarnessFlowExecutable(context, root);
-    const env = { ...context.env, DD_FLOW_BIN: flowExecutable, DD_FLOW_INVOCATION_SCOPE: undefined, DD_FLOW_CURRENT_INVOCATION: undefined, ...(isolatedWorkspace ? { DD_FLOW_READ_ONLY_WORKSPACE: isolatedWorkspace } : {}) };
+    const flowExecutable = prepareHarnessFlowExecutable(context, root, bundle?.engine());
+    const env = { ...context.env, DD_FLOW_BIN: flowExecutable, DD_FLOW_INVOCATION_SCOPE: undefined, DD_FLOW_CURRENT_INVOCATION: undefined,
+        DD_FLOW_MEMORY_REPAIR_WORKSPACE: repairPacket?.copy_root, ...(repairPacket ? { DD_FLOW_READ_ONLY_WORKSPACE: undefined } : {}),
+        ...(isolatedWorkspace ? { DD_FLOW_READ_ONLY_WORKSPACE: isolatedWorkspace } : {}) };
     // An external Codex root is a fresh thread, so it does not inherit the
     // coordinator's managed PreToolUse hook.  Its first `work start` must emit
     // that hook event to bind the Work to the physical session.
@@ -89,8 +147,9 @@ export async function launchExternalWork(context, input) {
     let runtimeContext = { ...context, env };
     const runtimeOwner = { schema_id: "dd-flow/runtime-owner@1", owner_id: `run:${work.run_id}:work:${work.work_id}`, role: "worker", project_id: work.project_id, run_id: work.run_id, work_id: work.work_id, operation_id: operationId, state_dir: root, dd_flow_home: context.ddFlowHome, dd_flow_bin: flowExecutable, resource_home: context.env.DD_FLOW_RESOURCE_HOME ?? context.ddFlowHome, budget: runtimeBudgetForRun(context, work.project_id, work.run_id) };
     const executable = resolveHarnessCommand(context.ddFlowHome, runtimeHarness(resolved.worker), "adapter");
-    context.db.run("INSERT INTO work_launches (operation_id, work_id, profile_json, profile_hash, status, state_dir, journal_path, provider_session_id, adapter_receipt_json, created_at, updated_at) VALUES (?, ?, ?, ?, 'launching', ?, ?, NULL, NULL, ?, ?)", [operationId, work.work_id, JSON.stringify({ ...resolved, runtime_adapter: { executable, owner: runtimeOwner }, ...(reviewCopy ? { review_copy: reviewCopy } : {}) }), resolved.profile_hash, root, journal, now, now]);
-    const common = ["--dd-flow-bin", flowExecutable, "--state-dir", root, "--journal", journal, "--cwd", isolatedWorkspace ?? run.workspace_root, "--provider", resolved.worker.provider, "--model", resolved.worker.model, "--reasoning", resolved.worker.reasoning, "--mode", resolved.worker.mode, "--permission", resolved.worker.permission, "--project-root", run.project_root, "--dd-flow-home", context.ddFlowHome, ...harnessRuntimeArguments(context.ddFlowHome, runtimeHarness(resolved.worker)), "--json"];
+    assertRepairPacket("partial");
+    context.db.run("INSERT INTO work_launches (operation_id, work_id, profile_json, profile_hash, status, state_dir, journal_path, provider_session_id, adapter_receipt_json, created_at, updated_at) VALUES (?, ?, ?, ?, 'launching', ?, ?, NULL, NULL, ?, ?)", [operationId, work.work_id, JSON.stringify({ ...resolved, runtime_adapter: { executable, owner: runtimeOwner }, ...(reviewCopy ? { review_copy: reviewCopy } : {}), ...(repairPacket ? { memory_repair_copy: repairPacket.profile.memory_repair_copy } : {}) }), resolved.profile_hash, root, journal, now, now]);
+    const common = ["--dd-flow-bin", flowExecutable, "--state-dir", root, "--journal", journal, "--cwd", repairPacket?.copy_root ?? isolatedWorkspace ?? run.workspace_root, "--provider", resolved.worker.provider, "--model", resolved.worker.model, "--reasoning", resolved.worker.reasoning, "--mode", resolved.worker.mode, "--permission", resolved.worker.permission, "--project-root", run.project_root, "--dd-flow-home", context.ddFlowHome, ...harnessRuntimeArguments(context.ddFlowHome, runtimeHarness(resolved.worker)), "--json"];
     const evidence = (value) => fs.appendFileSync(journal, `${JSON.stringify({ type: "adapter_call", at: context.now(), ...value })}\n`);
     try {
         const call = (args, timeoutMs, id = `${operationId}:${args[0]}.${args[1]}`) => runHarnessAdapter({ executable, args, harness: runtimeHarness(resolved.worker), env: runtimeContext.env, operationId: id, runtimeOwner, ...(timeoutMs !== undefined ? { timeoutMs } : {}), ...(input.signal ? { signal: input.signal } : {}), ...(input.progress ? { progress: input.progress } : {}), onEvidence: evidence, onNativeOutcome: value => {
@@ -111,7 +170,15 @@ export async function launchExternalWork(context, input) {
         runtimeContext = managedInvocationContext(runtimeContext, { harness: runtimeHarness(resolved.worker), stateDir: root, sessionId,
             projectRoot: run.project_root, runId: work.run_id, generation });
         assertRunMutationAllowed(context, work.project_id, work.run_id, generation);
-        assertWorkLaunchReady(context, work.work_id);
+        assertWorkLaunchReady(runtimeContext, work.work_id);
+        if (repairPacket) {
+            const owner = repairWave === 1
+                ? prepareExternalMemoryRepairCopyFromStage(context, { ...repairScope, workspaceRoot: repairPacket.copy_root })
+                : prepareMemorySecondRepairLaunchFromStage(context, repairScope);
+            if (owner.root() !== repairPacket.copy_root)
+                throw new AppError("memory_repair_launch_invalid", "Physical repair launch differs from the prepared copy", 1, { effect: "partial", next_action: "reconcile_exact_request" });
+            owner.revalidate(context);
+        }
         if (reviewCopy && reviewSourceHash(run.workspace_root, reviewInputs, reviewBase) !== reviewCopy.source_sha256)
             throw new AppError("read_only_input_changed", "Authoritative review workspace changed after the execution copy was made", 2, { work_id: work.work_id });
         const promptFile = path.join(root, "launch.md");
@@ -178,8 +245,15 @@ export async function launchExternalWork(context, input) {
     }
     catch (error) {
         const saved = context.db.get("SELECT adapter_receipt_json FROM work_launches WHERE operation_id = ?", [operationId]);
-        context.db.run("UPDATE work_launches SET status = 'failed', adapter_receipt_json = ?, updated_at = ? WHERE operation_id = ?", [JSON.stringify({ ...(saved?.adapter_receipt_json ? JSON.parse(saved.adapter_receipt_json) : {}), error: errorRecord(error) }), context.now(), operationId]);
-        throw error;
+        let failure = error;
+        if (repairPacket) {
+            const physical = context.db.get("SELECT provider_session_id FROM work_launches WHERE operation_id = ?", [operationId]);
+            failure = new AppError("memory_repair_launch_pending", "Repair launch retains runtime effects; reconcile the exact request before continuing", 1, { effect: error instanceof AppError && error.details.effect === "unknown" ? "unknown" : "partial",
+                work_id: work.work_id, operation_id: operationId, provider_session_id: physical?.provider_session_id ?? null,
+                next_action: "reconcile_exact_request", cause: errorRecord(error) });
+        }
+        context.db.run("UPDATE work_launches SET status = 'failed', adapter_receipt_json = ?, updated_at = ? WHERE operation_id = ?", [JSON.stringify({ ...(saved?.adapter_receipt_json ? JSON.parse(saved.adapter_receipt_json) : {}), error: errorRecord(failure) }), context.now(), operationId]);
+        throw failure;
     }
 }
 export function writeReviewGitEvidence(source, copy, base, explicitInputs = []) {
@@ -192,7 +266,13 @@ export function writeReviewGitEvidence(source, copy, base, explicitInputs = [])
     if (!base || base === "unknown")
         throw new AppError("review_git_evidence_missing", "Git review source has no frozen base commit", 1, { workspace_root: source });
     const paths = (reviewSourcePaths(source, explicitInputs, base) ?? []).map(file => `:(literal)${file}`);
-    for (const [name, args] of [["status.txt", ["status", "--short", "--untracked-files=all"]], ["diff.patch", ["diff", "--no-ext-diff", "--no-renames", "--binary", base]]]) {
+    const commands = [["status.txt", ["status", "--short", "--untracked-files=all"]],
+        ["diff.patch", ["diff", "--no-ext-diff", "--no-renames", "--binary", ...(base === "unborn" ? ["--cached"] : [base])]]];
+    // No revision exists in an unborn repository. Retain both index additions
+    // and subsequent working edits; untracked bytes are in the filtered copy.
+    if (base === "unborn")
+        commands.push(["diff-working.patch", ["diff", "--no-ext-diff", "--no-renames", "--binary"]]);
+    for (const [name, args] of commands) {
         const result = paths.length ? spawnSync("git", ["-C", source, ...args, "--", ...paths], { encoding: "utf8", maxBuffer: 64 * 1024 * 1024 }) : { status: 0, stdout: "", stderr: "", error: undefined };
         if (result.status !== 0 || result.error)
             throw new AppError("review_git_evidence_failed", "Could not collect read-only Git evidence for reviewer", 1, { workspace_root: source, command: name, cause: result.error?.message ?? result.stderr });

package/dist/services/flow-catalog.js

@@ -0,0 +1,21 @@
+import { vnextStages } from "../domain/stage-catalog.js";
+import { sdlcHandlerIdentities, memoryInitHandlerIdentities } from "../domain/stage-handler-identities.js";
+import { AppError } from "../shared/errors.js";
+/** Engine-owned catalog, not descriptor discovery or permission to execute a RUN. */
+export function listBundledFlows() {
+    return [
+        { id: "sdlc", handler_status: "registered", entry_stage: "specify", terminal_stages: ["merge"],
+            stages: vnextStages.map(stage => ({ id: stage.id, directory: stage.directory,
+                entry_handler: sdlcHandlerIdentities[stage.id].entryId, finish_handler: sdlcHandlerIdentities[stage.id].finishId })),
+            edges: vnextStages.flatMap(stage => stage.next.map((to, index) => ({ from: stage.id, to, on: index ? "not-applicable" : "accepted" }))) },
+        { id: "mb-init", handler_status: "registered", entry_stage: "preflight", terminal_stages: ["finish"],
+            stages: Object.values(memoryInitHandlerIdentities).map((handler, index) => ({ id: handler.stage, directory: `${String(index + 1).padStart(2, "0")}-${handler.stage}`, entry_handler: handler.entryId, finish_handler: handler.finishId })),
+            edges: ["preflight", "discover", "compose", "verify", "review"].flatMap((from, index) => [{ from, to: ["discover", "compose", "verify", "review", "finish"][index], on: "accepted" }, ...(from === "verify" ? [{ from, to: "review", on: "needs_repair" }] : [])]) }
+    ];
+}
+export function showBundledFlow(id) {
+    const flow = listBundledFlows().find(candidate => candidate.id === id);
+    if (!flow)
+        throw new AppError("flow_not_found", "Unknown bundled flow", 2, { effect: "no_effect", flow_id: id });
+    return flow;
+}

package/dist/services/flow-descriptors.js

@@ -0,0 +1,82 @@
+import { createHash } from "node:crypto";
+import { AppError } from "../shared/errors.js";
+import { validateFlowDescriptor, validateHybridShape } from "./hybrid-contracts.js";
+const digest = (bytes) => createHash("sha256").update(bytes).digest("hex");
+const blobLimit = 1024 * 1024;
+function freeze(value) {
+    if (value !== null && typeof value === "object") {
+        for (const child of Object.values(value))
+            freeze(child);
+        Object.freeze(value);
+    }
+}
+/** Admitted retained bytes only. This is not a RUN/storage/dispatch permission. */
+export class ResolvedFlowDescriptor {
+    sha256;
+    descriptor;
+    #bytes;
+    #blobs;
+    constructor(bytes, descriptor, blobs) {
+        this.sha256 = digest(bytes);
+        this.#bytes = bytes;
+        this.#blobs = blobs;
+        freeze(descriptor);
+        this.descriptor = descriptor;
+        Object.freeze(this);
+    }
+    /** Context comes from the engine materializer, never descriptor-owned allowlists. */
+    static admit(input, expectedSha256, context) {
+        const details = { phase: "prepare", effect: "no_effect" };
+        if (input.byteLength > blobLimit || !/^[a-f0-9]{64}$/.test(expectedSha256)) {
+            throw new AppError("flow_descriptor_invalid", "Flow descriptor identity or size is invalid", 2, details);
+        }
+        const bytes = Buffer.from(input);
+        if (digest(bytes) !== expectedSha256)
+            throw new AppError("flow_descriptor_integrity", "Flow descriptor bytes do not match the selected identity", 1, details);
+        let value;
+        try {
+            value = JSON.parse(new TextDecoder("utf-8", { fatal: true }).decode(bytes));
+        }
+        catch {
+            throw new AppError("flow_descriptor_invalid", "Flow descriptor must be valid UTF-8 JSON", 2, details);
+        }
+        const shape = validateHybridShape("flow-descriptor", value);
+        if (shape.length)
+            throw new AppError("flow_descriptor_invalid", "Flow descriptor shape is invalid", 2, { ...details, issues: shape });
+        const blobs = new Map();
+        let total = 0;
+        for (const [name, source] of context.blobs) {
+            total += source.byteLength;
+            if (source.byteLength > blobLimit || total > 32 * blobLimit)
+                throw new AppError("flow_descriptor_invalid", "Flow descriptor blobs exceed the bounded inventory", 2, details);
+            blobs.set(name, Buffer.from(source));
+        }
+        const issues = validateFlowDescriptor(value, { ...context, blobs });
+        if (issues.length)
+            throw new AppError("flow_descriptor_invalid", "Flow descriptor context is invalid", 2, { ...details, issues });
+        return new ResolvedFlowDescriptor(bytes, value, blobs);
+    }
+    stage(id) {
+        const stage = this.descriptor.stages.find(candidate => candidate.id === id);
+        if (!stage)
+            throw new AppError("flow_stage_invalid", "Stage does not belong to the resolved flow", 2, { flow_id: this.descriptor.id, stage: id, effect: "no_effect" });
+        return stage;
+    }
+    successor(id, outcome) {
+        this.stage(id);
+        if (outcome !== "accepted" && outcome !== "not-applicable" && outcome !== "needs_repair") {
+            throw new AppError("flow_transition_invalid", "Unknown stage outcome", 2, { flow_id: this.descriptor.id, stage: id, outcome, effect: "no_effect" });
+        }
+        const edge = this.descriptor.edges.find(candidate => candidate.from === id && candidate.on === outcome);
+        if (edge)
+            return edge.to;
+        if (this.descriptor.terminal_stages.includes(id))
+            return null;
+        throw new AppError("flow_transition_invalid", "No declared successor for this stage outcome", 2, { flow_id: this.descriptor.id, stage: id, outcome, effect: "no_effect" });
+    }
+    descriptorBytes() { return Buffer.from(this.#bytes); }
+    stageBlob(id, kind) {
+        const reference = this.stage(id)[kind];
+        return Buffer.from(this.#blobs.get(reference.path));
+    }
+}

package/dist/services/frozen-engine.js

@@ -0,0 +1,242 @@
+import crypto from "node:crypto";
+import fs from "node:fs";
+import path from "node:path";
+import { spawnSync } from "node:child_process";
+import { Ajv } from "ajv/dist/ajv.js";
+import { AppError } from "../shared/errors.js";
+import { engineSnapshotChecksum } from "./engines.js";
+import { readBoundedReleaseFile } from "./release-source.js";
+import { shellArgument } from "./runtime-command.js";
+import { hybridDigest } from "./hybrid-contracts.js";
+import { isMemoryInitResourceStorageFacts } from "./memory-init-resource-storage.js";
+import { memoryInitStartupInputSchemas } from "./memory-init-startup-custody.js";
+function storageProbeRefuse(reason) {
+    throw new AppError("frozen_engine_storage_incompatible", "Selected frozen engine cannot admit memory-init storage", 1, { reason, effect: "no_effect" });
+}
+const hash = (bytes) => crypto.createHash("sha256").update(bytes).digest("hex");
+function refuse(reason) {
+    throw new AppError("frozen_engine_invalid", "Frozen engine cannot be admitted", 1, { reason, phase: "prepare", effect: "no_effect" });
+}
+function json(bytes) {
+    try {
+        return JSON.parse(new TextDecoder("utf-8", { fatal: true }).decode(bytes));
+    }
+    catch {
+        return refuse("invalid_utf8_json");
+    }
+}
+function shape(name, value, property) {
+    const schema = JSON.parse(fs.readFileSync(new URL(`../schemas/${name}.schema.json`, import.meta.url), "utf8"));
+    return new Ajv({ strict: false, validateFormats: false }).compile(property ? schema.properties[property] : schema)(value) === true;
+}
+function containedFile(root, relative) {
+    if (path.isAbsolute(relative) || relative.split(/[\\/]/).some(part => part === ".." || part === "." || !part))
+        refuse("escaping_engine_path");
+    const parts = relative.split(/[\\/]/);
+    let current = root;
+    for (const [index, part] of parts.entries()) {
+        current = path.join(current, part);
+        const stat = fs.lstatSync(current);
+        if (stat.isSymbolicLink() || (index === parts.length - 1 ? !stat.isFile() : !stat.isDirectory()))
+            refuse("non_regular_engine_path");
+    }
+    return current;
+}
+/** New-bundle admission only. It does not replace historical binding or storage admission. */
+export class AdmittedFrozenEngine {
+    manifestSha256;
+    entrypoint;
+    nodeExecutable;
+    #manifest;
+    #bytes;
+    constructor(manifest, bytes, entrypoint) {
+        this.#manifest = manifest;
+        this.#bytes = bytes;
+        this.manifestSha256 = hash(bytes);
+        this.entrypoint = entrypoint;
+        this.nodeExecutable = fs.realpathSync(process.execPath);
+        Object.freeze(this);
+    }
+    /** Both hashes are independently selected by the RUN/bundle authority. No subprocess probe. */
+    static admit(binding, expectedManifestSha256) {
+        if (!shape("run-engine-binding", binding) || !/^[a-f0-9]{64}$/.test(expectedManifestSha256))
+            refuse("invalid_binding_identity");
+        return AdmittedFrozenEngine.fromIdentity(binding.engine, expectedManifestSha256);
+    }
+    /** Pre-RUN selection: no invented RUN id, binding or allocation authority. */
+    static admitSelection(identity, expectedManifestSha256) {
+        if (!shape("run-engine-binding", identity, "engine") || !/^[a-f0-9]{64}$/.test(expectedManifestSha256))
+            refuse("invalid_selection_identity");
+        return AdmittedFrozenEngine.fromIdentity(identity, expectedManifestSha256);
+    }
+    static fromIdentity(identity, expectedManifestSha256) {
+        try {
+            const root = path.resolve(identity.snapshot_root);
+            if (!path.isAbsolute(identity.snapshot_root) || !fs.lstatSync(root).isDirectory())
+                refuse("missing_or_linked_snapshot");
+            const bytes = readBoundedReleaseFile(path.join(root, "engine.json"), 1024 * 1024);
+            if (hash(bytes) !== expectedManifestSha256)
+                refuse("manifest_bytes_changed");
+            const value = json(bytes);
+            if (!shape("engine-manifest", value))
+                refuse("invalid_manifest_shape");
+            const manifest = value;
+            if (manifest.package_name !== identity.package_name || manifest.package_version !== identity.package_version
+                || manifest.engine_version !== identity.engine_version || path.resolve(manifest.snapshot_root) !== root
+                || manifest.integrity.mode !== "full_content" || manifest.integrity.checksum !== identity.integrity_checksum)
+                refuse("foreign_manifest_identity");
+            if (engineSnapshotChecksum(root) !== identity.integrity_checksum)
+                refuse("executable_snapshot_changed");
+            const entrypoint = containedFile(root, manifest.entrypoint);
+            if (!manifest.schema_registry || manifest.schema_registry.entries.length === 0)
+                refuse("missing_schema_registry");
+            const names = new Set(), paths = new Set();
+            for (const entry of manifest.schema_registry.entries) {
+                if (names.has(entry.name) || paths.has(entry.path))
+                    refuse("ambiguous_schema_registry");
+                names.add(entry.name);
+                paths.add(entry.path);
+                const schemaBytes = readBoundedReleaseFile(containedFile(root, entry.path), 1024 * 1024);
+                if (hash(schemaBytes) !== entry.checksum || json(schemaBytes)?.$id !== entry.id)
+                    refuse("schema_registry_identity_changed");
+            }
+            return new AdmittedFrozenEngine(manifest, bytes, entrypoint);
+        }
+        catch (error) {
+            if (error instanceof AppError && error.code === "frozen_engine_invalid")
+                throw error;
+            return refuse("snapshot_unavailable_or_unreadable");
+        }
+    }
+    manifest() { return structuredClone(this.#manifest); }
+    manifestBytes() { return Buffer.from(this.#bytes); }
+    /** Qualify actual descriptor handlers in this immutable executable, not the
+     * invoking CLI catalog. No storage or productive operation is admitted. */
+    admitMemoryInitFlow(source, startupInputSchema) {
+        const fail = (reason) => {
+            throw new AppError("frozen_engine_flow_incompatible", "Selected frozen engine cannot admit memory-init handlers", 1, { reason, phase: "prepare", effect: "no_effect" });
+        };
+        const revalidate = () => {
+            try {
+                if (hash(readBoundedReleaseFile(path.join(this.#manifest.snapshot_root, "engine.json"), 1024 * 1024)) !== this.manifestSha256
+                    || engineSnapshotChecksum(this.#manifest.snapshot_root) !== this.#manifest.integrity.checksum)
+                    fail("engine_changed_during_admission");
+                // Historical checksums exclude every engine.json path, including a
+                // nested directory. New memory execution must not admit unhashed code;
+                // do not change the checksum algorithm used by existing SDLC RUNs.
+                if (fs.readdirSync(this.#manifest.snapshot_root, { recursive: true, withFileTypes: true })
+                    .some(entry => entry.name === "engine.json" && path.resolve(entry.parentPath) !== this.#manifest.snapshot_root))
+                    fail("unhashed_engine_path");
+            }
+            catch (error) {
+                if (error instanceof AppError && error.code === "frozen_engine_flow_incompatible")
+                    throw error;
+                fail("engine_unavailable_during_admission");
+            }
+        };
+        if (startupInputSchema !== undefined && !memoryInitStartupInputSchemas.includes(startupInputSchema))
+            fail("unsupported_startup_input_schema");
+        const input = Buffer.from(JSON.stringify({ source: source.snapshot(), source_sha256: source.sha256,
+            ...(startupInputSchema === undefined ? {} : { startup_input_schema: startupInputSchema }) }));
+        if (input.length > 64 * 1024 * 1024)
+            fail("unbounded_source");
+        const expected = { schema_id: startupInputSchema === undefined ? "dd-flow/memory-init-engine-flow@1" : "dd-flow/memory-init-engine-flow@2",
+            ...(startupInputSchema === undefined ? {} : { startup_input_schema: startupInputSchema }),
+            flow_id: "mb-init", source_sha256: source.sha256,
+            descriptor_sha256: source.descriptorReference().sha256, stages: source.resolveRegisteredFlow().descriptor.stages.map(stage => stage.id) };
+        revalidate();
+        const env = Object.fromEntries(Object.entries(process.env).filter(([key]) => !["NODE_OPTIONS", "NODE_PATH"].includes(key) && !key.startsWith("DD_FLOW_")));
+        const result = spawnSync(this.nodeExecutable, [this.entrypoint, "runtime", "flow", "admit", "--operation", "memory-init", "--json"], { input, cwd: this.#manifest.snapshot_root, env: { ...env, DD_FLOW_ENGINE_MODE: "1", DD_FLOW_ENGINE_HOME: this.#manifest.snapshot_root },
+            timeout: 15000, maxBuffer: 1024 * 1024, shell: false, windowsHide: true });
+        if (result.error || result.signal || result.status !== 0)
+            fail("selected_engine_probe_failed");
+        revalidate();
+        let response;
+        try {
+            response = JSON.parse(new TextDecoder("utf-8", { fatal: true }).decode(result.stdout));
+        }
+        catch {
+            return fail("invalid_probe_json");
+        }
+        if (!response || typeof response !== "object" || Array.isArray(response) || Object.keys(response).sort().join() !== "action,facts,ok,sha256"
+            || response.ok !== true || response.action !== "runtime_flow_admit" || !response.facts || typeof response.facts !== "object" || Array.isArray(response.facts)
+            || hybridDigest(response.facts) !== hybridDigest(expected)
+            || response.sha256 !== hybridDigest(expected))
+            fail("invalid_probe_response");
+        return { facts: structuredClone(expected), sha256: hybridDigest(expected), engine_manifest_sha256: this.manifestSha256,
+            engine_sha256: this.#manifest.integrity.checksum };
+    }
+    /** Execute admission in the selected immutable engine, never in the invoking CLI.
+     * This qualifies storage connections only, not provider or flow readiness.
+     */
+    admitMemoryInitStorage(home, resourceHome) {
+        for (const root of [home, resourceHome]) {
+            if (!path.isAbsolute(root) || path.resolve(root) !== root || fs.realpathSync(root) !== root)
+                storageProbeRefuse("noncanonical_storage_home");
+        }
+        const revalidateEngine = () => {
+            if (hash(readBoundedReleaseFile(path.join(this.#manifest.snapshot_root, "engine.json"), 1024 * 1024)) !== this.manifestSha256
+                || engineSnapshotChecksum(this.#manifest.snapshot_root) !== this.#manifest.integrity.checksum)
+                storageProbeRefuse("engine_changed_during_admission");
+        };
+        revalidateEngine();
+        const env = Object.fromEntries(Object.entries(process.env).filter(([key]) => !["NODE_OPTIONS", "NODE_PATH"].includes(key)));
+        const result = spawnSync(this.nodeExecutable, [this.entrypoint, "runtime", "storage", "admit", "--operation", "memory-init", "--json"], { env: { ...env, DD_FLOW_HOME: home, DD_FLOW_RESOURCE_HOME: resourceHome, DD_FLOW_ENGINE_MODE: "1", DD_FLOW_ENGINE_HOME: this.#manifest.snapshot_root },
+            timeout: 15000, maxBuffer: 1024 * 1024, shell: false, windowsHide: true });
+        if (result.error || result.signal || result.status !== 0)
+            storageProbeRefuse("selected_engine_probe_failed");
+        revalidateEngine();
+        let response;
+        try {
+            response = JSON.parse(new TextDecoder("utf-8", { fatal: true }).decode(result.stdout));
+        }
+        catch {
+            return storageProbeRefuse("invalid_probe_json");
+        }
+        if (!response || typeof response !== "object" || Array.isArray(response) || Object.keys(response).sort().join() !== "action,facts,ok,sha256"
+            || response.ok !== true || response.action !== "runtime_storage_admit")
+            storageProbeRefuse("invalid_probe_response");
+        const facts = response.facts, run = facts?.run;
+        if (!facts || Object.keys(facts).sort().join() !== "operation,outcome,resource,route,run,schema_id"
+            || facts.schema_id !== "dd-flow/memory-init-engine-storage@1" || facts.operation !== "memory-init"
+            || facts.route !== "verified-no-op" || facts.outcome !== "no-op" || response.sha256 !== hybridDigest(facts)
+            || !isMemoryInitResourceStorageFacts(facts.resource) || facts.resource.store_path !== path.join(resourceHome, "runtime.sqlite")
+            || !run || Object.keys(run).sort().join() !== "executing_writer_version,operation,outcome,route,schema_id,schema_sha256,store_dev,store_ino,store_kind,store_path"
+            || run.schema_id !== "dd-flow/memory-init-runtime-storage@1" || run.operation !== "memory-init" || run.store_kind !== "run"
+            || run.store_path !== path.join(home, "db.sqlite") || run.route !== "verified-no-op" || run.outcome !== "no-op"
+            || run.executing_writer_version !== 2 || typeof run.schema_sha256 !== "string" || !/^[a-f0-9]{64}$/.test(run.schema_sha256))
+            storageProbeRefuse("invalid_probe_facts");
+        for (const store of [run, facts.resource]) {
+            const stat = fs.lstatSync(store.store_path);
+            if (!stat.isFile() || stat.nlink !== 1 || stat.dev !== store.store_dev || stat.ino !== store.store_ino)
+                storageProbeRefuse("storage_identity_changed");
+        }
+        return { facts: structuredClone(facts), sha256: response.sha256, engine_manifest_sha256: this.manifestSha256,
+            engine_sha256: this.#manifest.integrity.checksum };
+    }
+    /** Read an exact registered schema from this snapshot, never the mutable CLI. */
+    schema(name) {
+        try {
+            if (!fs.lstatSync(this.#manifest.snapshot_root).isDirectory())
+                refuse("missing_or_linked_snapshot");
+            const entry = this.#manifest.schema_registry?.entries.find(item => item.name === name);
+            if (!entry)
+                refuse("schema_not_registered");
+            const bytes = readBoundedReleaseFile(containedFile(this.#manifest.snapshot_root, entry.path), 1024 * 1024);
+            if (hash(bytes) !== entry.checksum || json(bytes).$id !== entry.id)
+                refuse("schema_registry_identity_changed");
+            return Buffer.from(bytes);
+        }
+        catch (error) {
+            if (error instanceof AppError && error.code === "frozen_engine_invalid")
+                throw error;
+            return refuse("schema_unavailable");
+        }
+    }
+    /** No PATH/dd-flow fallback or mutable launcher environment reference. */
+    command(home, args) {
+        if (!path.isAbsolute(home))
+            refuse("runtime_home_not_absolute");
+        return `DD_FLOW_HOME=${shellArgument(home)} DD_FLOW_ENGINE_MODE=1 DD_FLOW_ENGINE_HOME=${shellArgument(this.#manifest.snapshot_root)} ${[this.nodeExecutable, this.entrypoint, ...args].map(shellArgument).join(" ")}`;
+    }
+}