@deksden-com/dd-flow-cli 0.9.0-beta.137 → 0.9.0-beta.139

package/dist/services/discovery/zcode-discovery.js

@@ -0,0 +1,2 @@
+import { discoverExecutable } from "./static.js";
+export const discoverZcode = (input) => discoverExecutable("zcode", ["zcode"], input);

package/dist/services/engines.js

@@ -6,31 +6,25 @@ import { spawn } from "node:child_process";
 import { commandText } from '../harness-runtime/lib/process-json.mjs';
 import { SETUP_STARTUP_MS, publishSetup } from '../harness-runtime/lib/setup-progress.mjs';
 import { createRequire } from "node:module";
+import { valid } from "semver";
 import { getCliBuildInfo } from "./build-info.js";
 import { AppError } from "../shared/errors.js";
 import { ensureDir, engineStoreRoot, engineVersionRoot, resolveProjectRoot } from "../storage/paths.js";
-import { classifyCliOperation } from "./cli-operation-classifier.js";
+import { classifyCliOperation, isRouterNative } from "./cli-operation-classifier.js";
 import { requireProtocol } from "./protocols.js";
 import { resolveCanonRootBeforeContext } from "./canon.js";
 import { appendAudit } from "./audit.js";
+import { readBoundedReleaseFile } from "./release-source.js";
 import { findProjectByRoot } from "./projects.js";
 import { parseCommandArgs } from "./lifecycle-command.js";
 import { allRunEngineBindings, locateRunRoot, readRunEngineBinding, runEngineBindingSchemaId, writeRunEngineBinding } from "./run-engine-bindings.js";
 export const engineManifestSchemaId = "dd-flow/engine-manifest@1";
-const routerNativeFamilies = new Set(["engine", "version", "schema"]);
 const sourceFile = fileURLToPath(import.meta.url);
 export function isEngineMode(env) {
     return env.DD_FLOW_ENGINE_MODE === "1";
 }
 export function isRouterNativeCommand(args) {
-    const first = args[0];
-    if (!first || first === "--version")
-        return true;
-    if (first === "--help" || first === "-h")
-        return true;
-    if (args.includes("--help") || args.includes("-h"))
-        return true;
-    return first === "run" && args[1] === "reconcile" || routerNativeFamilies.has(first) || first === "codex" && args[1] === "hook" && args[2] === "handle";
+    return isRouterNative(args);
 }
 export function installCurrentEngine(context, input = {}) {
     const installation = prepareInstallation(context, input);
@@ -56,6 +50,27 @@ function* prepareInstallation(context, input) {
     if (!packageRoot) {
         throw new AppError("engine_install_failed", "Cannot locate package root for current dd-flow engine", 1);
     }
+    return yield* installPackageSnapshot(context, packageRoot, build.package_name, build.version, input);
+}
+/** Delivery from an independently selected package, not the invoking CLI.
+ * The caller owns release/dependency qualification of expectedChecksum.
+ * Existing snapshots are preserved even when not yet bound to a RUN. */
+export function installPackageEngine(context, input) {
+    if (!path.isAbsolute(input.packageRoot) || fs.realpathSync(input.packageRoot) !== input.packageRoot
+        || !/^(?:@[a-z0-9][a-z0-9._-]*\/)?[a-z0-9][a-z0-9._-]*$/.test(input.packageName)
+        || valid(input.version) !== input.version
+        || !/^[a-f0-9]{64}$/.test(input.expectedChecksum)) {
+        throw new AppError("engine_install_failed", "Selected package requires a canonical root and independent content checksum", 1, { effect: "no_effect" });
+    }
+    const metadata = JSON.parse(readBoundedReleaseFile(path.join(input.packageRoot, "package.json"), 1024 * 1024).toString("utf8"));
+    if (metadata.name !== input.packageName || metadata.version !== input.version
+        || snapshotFilesChecksum(packageSnapshotFiles(input.packageRoot)) !== input.expectedChecksum) {
+        throw new AppError("engine_install_failed", "Selected package identity or contents changed before delivery", 1, { effect: "no_effect" });
+    }
+    return installPackageSnapshot(context, input.packageRoot, input.packageName, input.version, { force: true, forRouting: true }, input.expectedChecksum, input.validateStaged).next().value;
+}
+function* installPackageSnapshot(context, packageRoot, packageName, version, input, expectedChecksum, validateStaged) {
+    const build = { package_name: packageName, version };
     const target = engineVersionRoot(context.ddFlowHome, build.package_name, build.version);
     const manifestPath = path.join(target, "engine.json");
     const existing = readManifest(manifestPath);
@@ -90,11 +105,20 @@ function* prepareInstallation(context, input) {
         copyPackageSnapshot(packageRoot, tmp);
         const stagedManifest = buildManifest(context, build.package_name, build.version, packageRoot, target, tmp);
         const stagedChecksum = stagedManifest.integrity.checksum;
+        if (expectedChecksum !== undefined && stagedChecksum !== expectedChecksum) {
+            throw new AppError("engine_install_failed", "Selected package changed during delivery", 1, { effect: "partial", path: tmp });
+        }
+        try {
+            validateStaged?.(tmp);
+        }
+        catch (error) {
+            throw new AppError("engine_install_failed", "Staged package no longer matches its selected release", 1, { effect: "partial", path: tmp, reason: error instanceof AppError ? error.details.reason ?? error.code : "staged_selection_changed" });
+        }
         const activationTarget = input.force
             && existing
             && stagedChecksum
             && stagedChecksum !== existing.integrity.checksum
-            && engineIsBound(context.ddFlowHome, existing)
+            && (expectedChecksum !== undefined || engineIsBound(context.ddFlowHome, existing))
             ? `${target}--${stagedChecksum}`
             : target;
         const duplicate = stagedChecksum ? findInstalledManifest(context.ddFlowHome, {
@@ -194,7 +218,6 @@ export async function routeArgsThroughEngine(context, args, io, stdin, env, reso
     const bound = boundRunEngineForArgs(context, args, resolvedProjectRoot ?? resolveExplicitProjectRoot(args) ?? undefined);
     if (bound) {
         const entrypoint = resolveManifestEntrypoint(bound.manifest);
-        await probeEntrypoint(bound.manifest, undefined, context.ddFlowHome, process.env);
         return spawnEngine(bound.manifest, entrypoint, args, io, stdin, env, getCliBuildInfo().version);
     }
     const selection = selectEngine(context, { projectRoot: resolvedProjectRoot ?? resolveExplicitProjectRoot(args) ?? undefined, env }, { allowCurrentInProcess: true }, classification);
@@ -213,15 +236,8 @@ export async function routeArgsThroughEngine(context, args, io, stdin, env, reso
         return Promise.resolve({ routed: true, exitCode: 0, inProcess: true });
     }
     const entrypoint = resolveManifestEntrypoint(selection.selected);
-    try {
-        await probeEntrypoint(selection.selected, undefined, context.ddFlowHome, process.env);
-    }
-    catch (cause) {
-        const error = cause;
-        if (error.code !== 'engine_probe_failed')
-            throw error;
-        throw new AppError('missing_engine', 'Selected engine cannot load its runtime dependencies', 1, { probe: error.details });
-    }
+    // The admitted immutable entrypoint executes the requested operation itself.
+    // A separate --version process adds no operation-specific admission.
     return spawnEngine(selection.selected, entrypoint, args, io, stdin, env, current.version);
 }
 export async function prepareRunEngineBind(context, input) {
@@ -694,7 +710,8 @@ function buildManifest(context, packageName, version, packageRoot, snapshotRoot,
         supports_contracts: {
             compatibility: ["dd-flow/compatibility@1"],
             version: ["dd-flow/version-report@1"],
-            status: ["dd-flow/status-report@1"]
+            status: ["dd-flow/status-report@1"],
+            hybrid: ["dd-flow/flow-descriptor@1", "dd-flow/execution-settings@1", "dd-flow/execution-bundle@1", "dd-flow/memory-bootstrap-receipt@2"]
         },
         schema_registry: buildSchemaRegistry(checksumRoot),
         integrity: {

package/dist/services/eval-snapshots.js

@@ -16,13 +16,26 @@ import { validateRunOperationalDecision } from "./vnext-execution-profile.js";
 import { readVnextFlowDefinition } from "./vnext-specify.js";
 import { captureRecoveryDatabase, readRecoveryResourceEvidence } from "./recovery-snapshot-database.js";
 import { resourceHome } from "./managed-processes.js";
+import { getResourceDatabase } from "../storage/database.js";
 import { codexHomeSharedEntries } from "./hooks.js";
 import { prepareOutputFile } from "../cli/input-preparation.js";
 import { localEnvironmentAllowed, projectServicePathFilter } from "./workspace-files.js";
 import { cleanupScopeWriters } from "./scope-writer-cleanup.js";
+import { PreparedInstalledFlowSource } from "./installed-flow-source.js";
+import { readSetupStatus } from "./setup.js";
 import { isObservationOperation, nativeInventoryVersion, retainedDaemonOperations } from "./run-control.js";
 /** Capture the only flow boundary which exists before `stage start --bootstrap` creates a RUN. */
 export function prepareEvalBootstrapSnapshot(context, input) {
+    let source;
+    if (input.flow !== undefined && input.flow !== "sdlc") {
+        if (input.flow !== "mb-init")
+            throw new AppError("snapshot_flow_unsupported", "Bootstrap snapshot flow is not registered", 2, { phase: "prepare", effect: "no_effect" });
+        const home = context.env.DD_FLOW_CONFIG_HOME ?? context.ddFlowHome;
+        const selected = readSetupStatus(home);
+        if (!selected.installation)
+            throw new AppError("snapshot_flow_unavailable", "Bootstrap snapshot requires the selected installed flow", 2, { phase: "prepare", effect: "no_effect" });
+        source = PreparedInstalledFlowSource.fromInstalledRelease(home, selected.installation.manifest_sha256, input.flow);
+    }
     const projectRoot = resolveProjectRoot(input.projectRoot);
     const output = path.resolve(input.output);
     if (fs.existsSync(output))
@@ -40,10 +53,10 @@ export function prepareEvalBootstrapSnapshot(context, input) {
             throw error;
         throw new AppError(error.code, error.message, 2, { ...error.details, phase: "prepare", effect: "no_effect", recoverable: true });
     }
-    return { projectRoot, output };
+    return { projectRoot, output, source };
 }
 export function createEvalBootstrapSnapshot(context, input) {
-    const { projectRoot, output } = prepareEvalBootstrapSnapshot(context, input);
+    const { projectRoot, output, source } = prepareEvalBootstrapSnapshot(context, input);
     const temporary = `${output}.partial-${crypto.randomUUID()}`;
     const before = bootstrapSourceVersion(projectRoot);
     try {
@@ -53,8 +66,9 @@ export function createEvalBootstrapSnapshot(context, input) {
         if (before !== after)
             throw new AppError("snapshot_source_changed", "Bootstrap source changed during snapshot capture", 1, { phase: "bootstrap", recoverable: true });
         const manifest = {
-            schema_id: "dd-eval/bootstrap-snapshot@1",
-            stage: "specify",
+            schema_id: source ? "dd-eval/bootstrap-snapshot@2" : "dd-eval/bootstrap-snapshot@1",
+            stage: source?.resolveRegisteredFlow().descriptor.stages[0]?.id ?? "specify",
+            ...(source ? { flow: { id: "mb-init", source_sha256: source.sha256, descriptor_sha256: source.descriptorReference().sha256 } } : {}),
             project_root: projectRoot,
             project_sha256: treeHash(path.join(temporary, "project")),
             project_git: snapshotProjectGit(projectRoot, temporary)
@@ -62,6 +76,7 @@ export function createEvalBootstrapSnapshot(context, input) {
         writeJson(path.join(temporary, "bootstrap.json"), manifest);
         if (after !== bootstrapSourceVersion(projectRoot))
             throw new AppError("snapshot_source_changed", "Bootstrap source changed while preserving Git evidence", 1, { phase: "bootstrap", recoverable: true });
+        source?.revalidate();
         syncSnapshotTree(temporary);
         fs.renameSync(temporary, output);
         syncPath(path.dirname(output));
@@ -97,7 +112,7 @@ export function restoreEvalBootstrapSnapshot(_context, input, prepared = prepare
     clearProjectTree(projectRoot, false);
     restoreProjectGit(snapshot, manifest.project_git, projectRoot);
     replaceProjectTree(projectRoot, sourceProject);
-    return { ok: true, schema_id: "dd-eval/bootstrap-restore@1", snapshot, project_root: projectRoot, target_stage: "specify" };
+    return { ok: true, schema_id: "dd-eval/bootstrap-restore@1", snapshot, project_root: projectRoot, target_stage: manifest.stage, ...(manifest.flow ? { flow: manifest.flow } : {}) };
 }
 /**
  * Eval fixtures require a dedicated home. Sealed recovery exports instead
@@ -204,7 +219,7 @@ export function prepareEvalRunSnapshotCreation(context, input) {
     if (isInside(physicalPath(projectRoot), physicalPath(output)) || isInside(physicalPath(workspaceRoot), physicalPath(output)))
         throw new AppError("snapshot_output_inside_project", "Snapshot output must be outside the project and RUN workspace trees", 1, { output });
     prepareOutputFile(output);
-    prepareSnapshotProjectGit(projectRoot);
+    prepareSnapshotProjectGit(projectRoot, recovery && status.run.flow_kind === "mb-init");
     prepareSnapshotWorkspace(workspaceRoot, projectRoot);
     return { projectRoot, project, status, recovery, output, workspaceRoot, activeChildren };
 }
@@ -262,7 +277,7 @@ function captureEvalRunSnapshot(context, input) {
         verbatimSymlinks: true,
         filter: projectPayloadFilter(projectRoot)
     });
-    const projectGit = snapshotProjectGit(projectRoot, output);
+    const projectGit = snapshotProjectGit(projectRoot, output, recovery && status.run.flow_kind === "mb-init");
     const workspace = snapshotWorkspace(workspaceRoot, projectRoot, output);
     // Accepted Work results are captured in SQLite. Their file representations
     // are retained evidence, not a second authority or a checkpoint gate.
@@ -276,7 +291,7 @@ function captureEvalRunSnapshot(context, input) {
         }
     }
     const manifest = {
-        schema_id: "dd-flow/eval-run-snapshot@5",
+        schema_id: projectGit.state === "unborn" ? "dd-flow/eval-run-snapshot@6" : "dd-flow/eval-run-snapshot@5",
         run_id: input.runId,
         project_id: project.id,
         project_root: projectRoot,
@@ -793,27 +808,31 @@ function assertRestoreTargetSeparation(snapshot, targets) {
 function sourceWorkspaceRoot(manifest) {
     return manifest.workspace.kind === "project" ? manifest.project_root : manifest.workspace.source_root;
 }
-function prepareSnapshotProjectGit(projectRoot) {
+function prepareSnapshotProjectGit(projectRoot, allowUnborn = false) {
     const branch = git(projectRoot, ["symbolic-ref", "--quiet", "--short", "HEAD"]);
-    const head = git(projectRoot, ["rev-parse", "HEAD"]);
-    if (!branch || !head)
-        throw new AppError("snapshot_project_git_invalid", "Snapshot requires a project on a named Git branch with a readable HEAD", 1, { project_root: projectRoot });
+    const head = git(projectRoot, ["rev-parse", "--verify", "HEAD"]);
+    if (!branch || !head && !(allowUnborn && git(projectRoot, ["for-each-ref", "--format=%(refname)"]) === ""))
+        throw new AppError("snapshot_project_git_invalid", "Snapshot requires a named Git branch and readable HEAD, or an admitted empty-ref Memory recovery", 1, { project_root: projectRoot });
     return { branch, head };
 }
-function snapshotProjectGit(projectRoot, output) {
-    const { branch, head } = prepareSnapshotProjectGit(projectRoot);
+function snapshotProjectGit(projectRoot, output, allowUnborn = false) {
+    const { branch, head } = prepareSnapshotProjectGit(projectRoot, allowUnborn);
+    if (head === null)
+        return { branch, head: null, bundle_sha256: null, state: "unborn", ...snapshotIndex(projectRoot, output, "project") };
     const bundle = path.join(output, "project.bundle");
     runGit(projectRoot, ["bundle", "create", bundle, `refs/heads/${branch}`]);
     return { branch, head, bundle_sha256: fileHash(bundle), ...snapshotIndex(projectRoot, output, "project") };
 }
 function restoreProjectGit(snapshot, source, projectRoot) {
     const bundle = path.join(snapshot, "project.bundle");
-    if (!fs.existsSync(bundle) || fileHash(bundle) !== source.bundle_sha256)
+    if (source.state === "unborn" ? fs.existsSync(bundle) : !fs.existsSync(bundle) || fileHash(bundle) !== source.bundle_sha256)
         throw new AppError("snapshot_checksum_mismatch", "Snapshot project Git bundle checksum does not match manifest", 1, { snapshot });
     fs.rmSync(path.join(projectRoot, ".git"), { recursive: true, force: true });
     runGit(projectRoot, ["init", "-b", source.branch]);
-    runGit(projectRoot, ["fetch", bundle, `+refs/heads/${source.branch}:refs/remotes/snapshot/${source.branch}`]);
-    runGit(projectRoot, ["checkout", "-B", source.branch, source.head]);
+    if (source.state !== "unborn") {
+        runGit(projectRoot, ["fetch", bundle, `+refs/heads/${source.branch}:refs/remotes/snapshot/${source.branch}`]);
+        runGit(projectRoot, ["checkout", "-B", source.branch, source.head]);
+    }
     restoreIndex(snapshot, "project", source, projectRoot);
 }
 const mergeStateFiles = ["MERGE_HEAD", "MERGE_MSG", "MERGE_MODE", "ORIG_HEAD", "AUTO_MERGE"];
@@ -912,7 +931,9 @@ export function verifyRecoverySnapshot(snapshot, input, checkWorkingState = true
         const expectedModes = manifest.payload_modes?.[entry.name];
         if (checkWorkingState && expectedModes && treeModesHash(entry.root, allowed) !== expectedModes)
             throw new AppError("recovery_workspace_drift", "Executable file modes changed after recovery capture", 1, { payload: entry.name });
-        if (checkWorkingState && (treeHash(entry.root, allowed) !== entry.hash || git(entry.root, ["rev-parse", "HEAD"]) !== entry.head || git(entry.root, ["symbolic-ref", "--quiet", "--short", "HEAD"]) !== entry.git.branch || (entry.git.index_sha256 && crypto.createHash("sha256").update(entry.git.index_format === "entries@1" ? indexEntries(entry.root) : indexPatch(entry.root)).digest("hex") !== entry.git.index_sha256)))
+        if (checkWorkingState && (treeHash(entry.root, allowed) !== entry.hash || git(entry.root, ["rev-parse", "--verify", "HEAD"]) !== entry.head
+            || entry.head === null && git(entry.root, ["for-each-ref", "--format=%(refname)"]) !== ""
+            || git(entry.root, ["symbolic-ref", "--quiet", "--short", "HEAD"]) !== entry.git.branch || (entry.git.index_sha256 && crypto.createHash("sha256").update(entry.git.index_format === "entries@1" ? indexEntries(entry.root) : indexPatch(entry.root)).digest("hex") !== entry.git.index_sha256)))
             throw new AppError("recovery_workspace_drift", "Working files or Git state changed after recovery capture", 1, { payload: entry.name });
     }
 }
@@ -935,9 +956,23 @@ function verifySnapshotPayload(snapshot, manifest) {
     const payloads = [{ name: "project", hash: manifest.project_sha256, git: manifest.project_git }, ...(manifest.workspace.kind === "git_worktree" ? [{ name: "workspace", hash: manifest.workspace.sha256, git: manifest.workspace }] : [])];
     for (const payload of payloads)
         verifyGitSnapshotPayload(snapshot, payload);
+    if (manifest.schema_id === "dd-flow/eval-run-snapshot@6") {
+        const db = new DatabaseSync(path.join(snapshot, "runtime", "db.sqlite"), { readOnly: true });
+        try {
+            const row = db.prepare("SELECT flow_kind, project_root, workspace_root FROM runs WHERE id=?").get(manifest.run_id);
+            if (!row || row.flow_kind !== "mb-init" || row.project_root !== manifest.project_root || row.workspace_root !== manifest.project_root)
+                throw new AppError("snapshot_invalid", "Unborn recovery must belong to its captured Memory RUN", 1, { snapshot });
+        }
+        finally {
+            db.close();
+        }
+    }
 }
 function verifyGitSnapshotPayload(snapshot, payload) {
-    if (treeHash(path.join(snapshot, payload.name)) !== payload.hash || fileHash(path.join(snapshot, `${payload.name}.bundle`)) !== payload.git.bundle_sha256 || payload.git.index_sha256 && fileHash(path.join(snapshot, `${payload.name}.index.patch`)) !== payload.git.index_sha256 || payload.git.index_format === "entries@1" && (!payload.git.index_objects_sha256 || fileHash(path.join(snapshot, `${payload.name}.index.pack`)) !== payload.git.index_objects_sha256))
+    const bundle = path.join(snapshot, `${payload.name}.bundle`);
+    const invalidBundle = payload.git.state === "unborn" ? payload.git.bundle_sha256 !== null || fs.existsSync(bundle)
+        : !fs.existsSync(bundle) || fileHash(bundle) !== payload.git.bundle_sha256;
+    if (treeHash(path.join(snapshot, payload.name)) !== payload.hash || invalidBundle || payload.git.index_sha256 && fileHash(path.join(snapshot, `${payload.name}.index.patch`)) !== payload.git.index_sha256 || payload.git.index_format === "entries@1" && (!payload.git.index_objects_sha256 || fileHash(path.join(snapshot, `${payload.name}.index.pack`)) !== payload.git.index_objects_sha256))
         throw new AppError("snapshot_checksum_mismatch", "Snapshot payload or Git index checksum does not match", 1, { payload: payload.name });
 }
 function git(root, args) {
@@ -1073,8 +1108,8 @@ function runtimeSnapshotKind(file, excluded, providerHomes = []) {
     }
     return "ordinary";
 }
-/** Productive writers are fenced separately. Compare exactly the copied
- * source set; SQLite serialization includes committed WAL pages without
+/** Productive writers are fenced separately. Compare the copied source set
+ * without idle diagnostic appends; SQLite includes committed WAL pages without
  * mistaking a physical checkpoint for new logical content. */
 function snapshotSourceVersion(context, input, retainedDatabases, retainedJournals) {
     const databases = retainedDatabases ?? new Map();
@@ -1085,6 +1120,11 @@ function snapshotSourceVersion(context, input, retainedDatabases, retainedJourna
     if (!run)
         throw new AppError("not_found", "Snapshot RUN is not registered", 1);
     const entries = new Map();
+    const diagnosticLogs = new Set(getResourceDatabase(resourceHome(context), "read_existing").all("SELECT stdout_path,stderr_path,metadata_json FROM managed_processes WHERE project_id=? AND run_id=? AND kind IN ('codex-daemon','zcode-daemon','grok-daemon','agy-daemon','opencode-daemon','droid-daemon')", [project.id, input.runId]).flatMap(row => {
+        const directory = JSON.parse(row.metadata_json).state_dir;
+        const log = typeof directory === "string" && path.isAbsolute(directory) ? path.join(directory, "daemon.log") : null;
+        return log && isInside(context.ddFlowHome, log) && row.stdout_path === log && row.stderr_path === log ? [log] : [];
+    }));
     const excluded = codexHomeSnapshotExclusions(context, project.id, input.runId);
     const providerHomes = input.recoveryId === undefined ? grokProviderHomes(context.ddFlowHome) : [];
     const observations = new Map();
@@ -1132,7 +1172,12 @@ function snapshotSourceVersion(context, input, retainedDatabases, retainedJourna
                 }
                 entries.set(key, `sqlite:${sqliteSemanticFingerprint(db)}:${stat.mode & 0o111}`);
             }
-            else if (stat.isFile() && ["adapter.events.jsonl", "events.jsonl", "model-observations.jsonl", "timeline.jsonl", "daemon.log", "controller.log"].includes(path.basename(file))) {
+            else if (stat.isFile() && diagnosticLogs.has(file)) {
+                // Daemon stdout/stderr can append while an otherwise settled Session is idle.
+                // Keep its identity/mode fenced; the copied bytes remain sealed in the snapshot.
+                entries.set(key, `diagnostic-log:${stat.dev}:${stat.ino}:${stat.mode & 0o111}`);
+            }
+            else if (stat.isFile() && (["adapter.events.jsonl", "events.jsonl", "model-observations.jsonl", "timeline.jsonl", "controller.log"].includes(path.basename(file)) || native && file === path.join(directory, "daemon.log"))) {
                 const bytes = fs.readFileSync(file);
                 let cut = journals.get(file);
                 if (!cut && !retainedJournals) {
@@ -1409,11 +1454,20 @@ function readManifest(snapshot) {
     if (!fs.existsSync(file))
         throw new AppError("snapshot_missing", "Snapshot manifest is missing", 1, { snapshot });
     const value = JSON.parse(fs.readFileSync(file, "utf8"));
-    if (value.schema_id !== "dd-flow/eval-run-snapshot@5" || !value.run_id || !value.project_root || !value.dd_flow_home || typeof value.purpose !== "string" || !["stage_entry", "candidate", "incomplete", "recovery"].includes(value.purpose) || (value.purpose === "stage_entry" && !value.stage_entry) || (value.purpose !== "stage_entry" && value.stage_entry !== null) || !value.runtime_sha256 || !value.project_sha256 || !value.project_git || !value.workspace)
+    if (!["dd-flow/eval-run-snapshot@5", "dd-flow/eval-run-snapshot@6"].includes(String(value.schema_id)) || !value.run_id || !value.project_root || !value.dd_flow_home || typeof value.purpose !== "string" || !["stage_entry", "candidate", "incomplete", "recovery"].includes(value.purpose) || (value.purpose === "stage_entry" && !value.stage_entry) || (value.purpose !== "stage_entry" && value.stage_entry !== null) || !value.runtime_sha256 || !value.project_sha256 || !value.project_git || !value.workspace)
         throw new AppError("snapshot_invalid", "Snapshot manifest is invalid", 1, { snapshot });
     if (value.runtime_payload_policy !== undefined && (value.runtime_payload_policy !== "flow-evidence@1" || value.purpose === "recovery"))
         throw new AppError("snapshot_invalid", "Snapshot runtime payload policy is invalid for its purpose", 1, { snapshot });
-    if (!value.project_git.branch || !value.project_git.head || !value.project_git.bundle_sha256)
+    const unborn = value.schema_id === "dd-flow/eval-run-snapshot@6";
+    if (!value.project_git.branch || (unborn
+        ? value.purpose !== "recovery" || value.workspace.kind !== "project" || value.project_git.state !== "unborn"
+            || value.project_git.head !== null || value.project_git.bundle_sha256 !== null
+            || value.project_git.index_format !== "entries@1" || !/^[a-f0-9]{64}$/.test(value.project_git.index_sha256 ?? "")
+            || !/^[a-f0-9]{64}$/.test(value.project_git.index_objects_sha256 ?? "")
+            || Object.keys(value.project_git).sort().join() !== "branch,bundle_sha256,head,index_format,index_objects_sha256,index_sha256,state"
+            || typeof value.project_git.branch !== "string"
+            || spawnSync("git", ["check-ref-format", "--branch", value.project_git.branch], { encoding: "utf8" }).status !== 0
+        : value.project_git.state !== undefined || !value.project_git.head || !value.project_git.bundle_sha256))
         throw new AppError("snapshot_invalid", "Snapshot project Git metadata is incomplete", 1, { snapshot });
     if (value.workspace.kind === "git_worktree" && (!value.workspace.branch || !value.workspace.base_ref || !value.workspace.bundle_sha256))
         throw new AppError("snapshot_invalid", "Snapshot worktree manifest is incomplete", 1, { snapshot });
@@ -1424,7 +1478,11 @@ function readBootstrapManifest(snapshot) {
     if (!fs.existsSync(file))
         throw new AppError("snapshot_missing", "Bootstrap snapshot manifest is missing", 1, { snapshot });
     const value = JSON.parse(fs.readFileSync(file, "utf8"));
-    if (value.schema_id !== "dd-eval/bootstrap-snapshot@1" || value.stage !== "specify" || !value.project_root || !value.project_sha256 || !value.project_git?.branch || !value.project_git.head || !value.project_git.bundle_sha256)
+    const validBoundary = value.schema_id === "dd-eval/bootstrap-snapshot@1" ? value.stage === "specify" && value.flow === undefined
+        : value.schema_id === "dd-eval/bootstrap-snapshot@2" && value.flow?.id === "mb-init" && value.stage === "preflight"
+            && Object.keys(value.flow).sort().join() === "descriptor_sha256,id,source_sha256"
+            && /^[a-f0-9]{64}$/.test(value.flow.source_sha256) && /^[a-f0-9]{64}$/.test(value.flow.descriptor_sha256);
+    if (!validBoundary || !value.project_root || !value.project_sha256 || !value.project_git?.branch || !value.project_git.head || !value.project_git.bundle_sha256)
         throw new AppError("snapshot_invalid", "Bootstrap snapshot manifest is invalid", 1, { snapshot });
     return value;
 }

package/dist/services/execution-bundles.js

@@ -0,0 +1,263 @@
+import crypto from "node:crypto";
+import fs from "node:fs";
+import path from "node:path";
+import { Ajv2020 } from "ajv/dist/2020.js";
+import { AppError } from "../shared/errors.js";
+import { ResolvedFlowDescriptor } from "./flow-descriptors.js";
+import { AdmittedFrozenEngine } from "./frozen-engine.js";
+import { FrozenGenericExecution } from "./generic-execution.js";
+import { hybridDigest, validateHybridContract, validateHybridShape } from "./hybrid-contracts.js";
+import { readBoundedReleaseFile } from "./release-source.js";
+import { acquireInstallationLock } from "./installation-lock.js";
+const hash = (bytes) => crypto.createHash("sha256").update(bytes).digest("hex");
+const limit = 1024 * 1024;
+function refuse(reason, issues) {
+    throw new AppError("execution_bundle_invalid", "Execution bundle cannot be admitted", 1, { reason, phase: "prepare", effect: "no_effect", ...(issues ? { issues } : {}) });
+}
+function json(bytes) {
+    try {
+        return JSON.parse(new TextDecoder("utf-8", { fatal: true }).decode(bytes));
+    }
+    catch {
+        return refuse("invalid_utf8_json");
+    }
+}
+function frozen(value) {
+    if (value !== null && typeof value === "object") {
+        for (const child of Object.values(value))
+            frozen(child);
+        Object.freeze(value);
+    }
+}
+function directory(file) {
+    if (!fs.lstatSync(file).isDirectory())
+        refuse("non_regular_bundle_directory");
+}
+function fileIn(root, logical, create = false) {
+    const parts = logical.split("/");
+    let current = root;
+    for (const part of parts.slice(0, -1)) {
+        current = path.join(current, part);
+        if (create && !fs.existsSync(current))
+            fs.mkdirSync(current, { mode: 0o700 });
+        directory(current);
+    }
+    return path.join(current, parts.at(-1));
+}
+/** Retained contract data only. RUN generation, physical ownership and writer admission remain separate. */
+export class RetainedExecutionBundle {
+    sha256;
+    manifest;
+    descriptor;
+    execution;
+    #bytes;
+    #blobs;
+    #admission;
+    #engine;
+    constructor(bytes, manifest, blobs, admission, descriptor, execution) {
+        frozen(manifest);
+        this.manifest = manifest;
+        this.sha256 = hash(bytes);
+        this.#bytes = bytes;
+        this.#blobs = blobs;
+        this.#admission = admission;
+        this.descriptor = descriptor;
+        this.execution = execution;
+        Object.freeze(this);
+    }
+    static admit(input, expectedSha256, sourceBlobs, selected) {
+        if (input.byteLength > limit || !/^[a-f0-9]{64}$/.test(expectedSha256))
+            refuse("invalid_bundle_identity");
+        const bytes = Buffer.from(input);
+        if (hash(bytes) !== expectedSha256)
+            refuse("manifest_bytes_changed");
+        const value = json(bytes), shape = validateHybridShape("execution-bundle", value);
+        if (shape.length)
+            refuse("invalid_bundle_shape", shape);
+        const manifest = value;
+        if (manifest.run_id !== selected.runId || selected.executionScope.projectRoot !== selected.bundleProjectRoot)
+            refuse("foreign_run_identity");
+        const admission = structuredClone(selected);
+        const names = manifest.inventory.map(ref => ref.path), folded = new Set();
+        for (const name of names) {
+            const normalized = name.toLowerCase();
+            if (folded.has(normalized) || ["manifest.json", "publication.json"].includes(normalized)
+                || names.some(other => other !== name && other.toLowerCase().startsWith(`${normalized}/`)))
+                refuse("conflicting_bundle_path");
+            folded.add(normalized);
+        }
+        const blobs = new Map();
+        let total = 0;
+        for (const reference of manifest.inventory) {
+            const source = sourceBlobs.get(reference.path);
+            if (!source || source.byteLength === 0 || source.byteLength > limit || (total += source.byteLength) > 32 * limit)
+                refuse("missing_or_unbounded_blob");
+            blobs.set(reference.path, Buffer.from(source));
+        }
+        const context = { ...admission, blobs };
+        const issues = validateHybridContract("execution-bundle", manifest, context);
+        if (issues.length)
+            refuse("invalid_bundle_context", issues);
+        if (!admission.descriptorContext)
+            refuse("missing_handler_context");
+        const descriptor = ResolvedFlowDescriptor.admit(blobs.get(manifest.descriptor.path), manifest.descriptor.sha256, { ...admission.descriptorContext, blobs });
+        for (const stage of descriptor.descriptor.stages) {
+            try {
+                new TextDecoder("utf-8", { fatal: true }).decode(descriptor.stageBlob(stage.id, "instruction"));
+            }
+            catch {
+                refuse("invalid_instruction_encoding");
+            }
+        }
+        const profiles = json(blobs.get(manifest.profile_settings.path));
+        const snapshot = { schema_id: "dd-flow/frozen-execution@1", scope: admission.executionScope,
+            settings: json(blobs.get(manifest.execution_settings.path)), profiles: profiles.profiles };
+        const execution = FrozenGenericExecution.restore(snapshot, hybridDigest(snapshot), descriptor, admission.executionScope, admission.receipts);
+        const admitted = new RetainedExecutionBundle(bytes, manifest, blobs, admission, descriptor, execution);
+        admitted.engine();
+        return admitted;
+    }
+    /** Read only the retained inventory. Mutable canon/profile sources are never consulted. */
+    static read(root, expectedSha256, admission) {
+        try {
+            directory(root);
+            const bytes = readBoundedReleaseFile(path.join(root, "manifest.json"), limit);
+            if (hash(bytes) !== expectedSha256)
+                refuse("manifest_bytes_changed");
+            const value = json(bytes), issues = validateHybridShape("execution-bundle", value);
+            if (issues.length)
+                refuse("invalid_bundle_shape", issues);
+            const manifest = value, blobs = new Map();
+            for (const ref of manifest.inventory)
+                blobs.set(ref.path, readBoundedReleaseFile(fileIn(root, ref.path), limit));
+            return RetainedExecutionBundle.admit(bytes, expectedSha256, blobs, admission);
+        }
+        catch (error) {
+            if (error instanceof AppError && ["execution_bundle_invalid", "frozen_engine_invalid"].includes(error.code))
+                throw error;
+            return refuse("retained_bundle_unavailable");
+        }
+    }
+    manifestBytes() { return Buffer.from(this.#bytes); }
+    blob(logical) {
+        const bytes = this.#blobs.get(logical);
+        if (!bytes)
+            refuse("unlisted_bundle_blob");
+        return Buffer.from(bytes);
+    }
+    admission() { return structuredClone(this.#admission); }
+    engine() {
+        // An issued bundle already admitted this exact immutable engine. Fresh
+        // read/admit creates a new owner; publication explicitly rechecks below.
+        return this.#engine ??= this.#admitEngine();
+    }
+    #admitEngine() {
+        const binding = json(this.blob(this.manifest.engine_binding.path));
+        const engine = AdmittedFrozenEngine.admit(binding, this.manifest.engine_manifest.sha256);
+        if (!engine.manifestBytes().equals(this.blob(this.manifest.engine_manifest.path)))
+            refuse("engine_manifest_bytes_changed");
+        const manifest = engine.manifest(), contracts = new Set(Object.values(manifest.supports_contracts).flat());
+        for (const id of ["dd-flow/flow-descriptor@1", "dd-flow/execution-settings@1", "dd-flow/execution-bundle@1"]) {
+            if (!contracts.has(id))
+                refuse("engine_contract_not_supported");
+        }
+        for (const reference of this.manifest.bootstrap_receipts) {
+            const receipt = json(this.blob(reference.path));
+            if (receipt.schema_id !== "dd-flow/memory-bootstrap-receipt@2")
+                continue;
+            if (!contracts.has(receipt.schema_id))
+                refuse("engine_contract_not_supported");
+            const entries = manifest.schema_registry.entries.filter(entry => entry.id === receipt.schema_id);
+            const entry = entries[0];
+            if (entries.length !== 1 || !entry)
+                refuse("unregistered_bootstrap_schema");
+            try {
+                const validate = new Ajv2020({ strict: true, validateFormats: false }).compile(json(engine.schema(entry.name)));
+                if (!validate(receipt))
+                    refuse("invalid_frozen_bootstrap_shape", validate.errors);
+            }
+            catch (error) {
+                if (error instanceof AppError)
+                    throw error;
+                refuse("invalid_frozen_bootstrap_schema");
+            }
+        }
+        for (const stage of this.descriptor.descriptor.stages) {
+            const bytes = this.descriptor.stageBlob(stage.id, "result_schema"), schema = json(bytes);
+            if (!manifest.schema_registry.entries.some(entry => entry.id === schema.$id && entry.checksum === hash(bytes)))
+                refuse("unregistered_stage_schema");
+        }
+        return engine;
+    }
+    /** Deterministic publication under the RUN's existing root and immutable engine binding. */
+    materialize(runRoot) {
+        this.#admitEngine();
+        directory(runRoot);
+        if (hash(readBoundedReleaseFile(path.join(runRoot, "engine-binding.json"), limit)) !== this.manifest.engine_binding.sha256)
+            refuse("run_engine_binding_changed");
+        const target = path.join(runRoot, "execution-bundle"), pending = path.join(runRoot, `.execution-bundle.pending-${this.sha256}`);
+        const lock = acquireInstallationLock(path.join(runRoot, "execution-bundle.lock"), this.sha256);
+        let publicationStarted = false;
+        try {
+            if (fs.existsSync(target)) {
+                RetainedExecutionBundle.read(target, this.sha256, this.#admission);
+                return { path: target, sha256: this.sha256, changed: false };
+            }
+            const owner = Buffer.from(JSON.stringify({ schema_id: "dd-flow/bundle-publication@1", sha256: this.sha256, run_id: this.manifest.run_id }));
+            publicationStarted = true;
+            if (!fs.existsSync(pending)) {
+                fs.mkdirSync(pending, { mode: 0o700 });
+                fs.writeFileSync(path.join(pending, "publication.json"), owner, { flag: "wx", mode: 0o600 });
+            }
+            directory(pending);
+            if (!readBoundedReleaseFile(path.join(pending, "publication.json"), limit).equals(owner))
+                refuse("foreign_pending_publication");
+            const write = (logical, bytes) => {
+                const file = fileIn(pending, logical, true);
+                if (fs.existsSync(file)) {
+                    if (!readBoundedReleaseFile(file, limit).equals(bytes))
+                        refuse("retained_blob_changed");
+                    return;
+                }
+                const temporary = path.join(pending, `.write-${hash(Buffer.from(logical))}.tmp`);
+                if (fs.existsSync(temporary)) {
+                    const stat = fs.lstatSync(temporary);
+                    if (!stat.isFile() || stat.nlink !== 1)
+                        refuse("foreign_pending_write");
+                    fs.unlinkSync(temporary);
+                }
+                // This temporary is owned by the exact publication receipt and lock.
+                // A crashed partial write is deterministic; no productive operation is retried.
+                const fd = fs.openSync(temporary, fs.constants.O_WRONLY | fs.constants.O_CREAT | fs.constants.O_EXCL | (fs.constants.O_NOFOLLOW ?? 0), 0o600);
+                try {
+                    fs.writeFileSync(fd, bytes);
+                    fs.fsyncSync(fd);
+                }
+                finally {
+                    fs.closeSync(fd);
+                }
+                fs.renameSync(temporary, file);
+            };
+            for (const [logical, bytes] of this.#blobs)
+                write(logical, bytes);
+            write("manifest.json", this.#bytes);
+            RetainedExecutionBundle.read(pending, this.sha256, this.#admission);
+            if (fs.existsSync(target))
+                refuse("concurrent_bundle_publication");
+            fs.renameSync(pending, target);
+            return { path: target, sha256: this.sha256, changed: true };
+        }
+        catch (error) {
+            if (!publicationStarted)
+                throw error;
+            throw new AppError("execution_bundle_publication_failed", "Execution bundle publication requires recovery", 1, {
+                phase: "publication", effect: "partial", run_id: this.manifest.run_id,
+                sha256: this.sha256, pending_path: pending,
+                reason: error instanceof AppError ? error.code : "publication_io_failure",
+            });
+        }
+        finally {
+            lock.release();
+        }
+    }
+}