@deksden-com/dd-flow-cli 0.7.0 → 0.8.0

package/dist/services/eval-snapshots.js

@@ -0,0 +1,404 @@
+import crypto from "node:crypto";
+import { spawnSync } from "node:child_process";
+import fs from "node:fs";
+import path from "node:path";
+import { createContext } from "../runtime/context.js";
+import { AppError } from "../shared/errors.js";
+import { resolveProjectRoot } from "../storage/paths.js";
+import { registerProject, requireProjectByRoot } from "./projects.js";
+import { getFlowRunStatus, startFlowRun } from "./runs.js";
+import { readVnextFlowDefinition } from "./vnext-specify.js";
+/** Capture the only flow boundary which exists before `stage start --bootstrap` creates a RUN. */
+export function createEvalBootstrapSnapshot(context, input) {
+    const projectRoot = resolveProjectRoot(input.projectRoot);
+    const output = path.resolve(input.output);
+    if (fs.existsSync(output))
+        throw new AppError("snapshot_exists", "Snapshot output already exists", 1, { output });
+    if (isInside(physicalPath(projectRoot), physicalPath(output)))
+        throw new AppError("snapshot_output_inside_project", "Bootstrap snapshot output must be outside the project tree", 1, { output });
+    if (isInside(physicalPath(context.ddFlowHome), physicalPath(output)))
+        throw new AppError("snapshot_output_inside_runtime", "Bootstrap snapshot output must be outside DD_FLOW_HOME", 1, { output });
+    fs.mkdirSync(output, { recursive: true });
+    fs.cpSync(projectRoot, path.join(output, "project"), { recursive: true, verbatimSymlinks: true, filter: (source) => path.basename(source) !== ".git" });
+    const manifest = {
+        schema_id: "dd-eval/bootstrap-snapshot@1",
+        stage: "specify",
+        project_root: projectRoot,
+        project_sha256: treeHash(path.join(output, "project")),
+        project_git: snapshotProjectGit(projectRoot, output)
+    };
+    writeJson(path.join(output, "bootstrap.json"), manifest);
+    return { ok: true, snapshot: output, ...manifest };
+}
+/** Restore a pre-RUN project state; `stage start --bootstrap` creates runtime state afterwards. */
+export function restoreEvalBootstrapSnapshot(_context, input) {
+    const snapshot = path.resolve(input.snapshot);
+    const manifest = readBootstrapManifest(snapshot);
+    const projectRoot = resolveProjectRoot(input.projectRoot);
+    const sourceProject = path.join(snapshot, "project");
+    if (treeHash(sourceProject) !== manifest.project_sha256)
+        throw new AppError("snapshot_checksum_mismatch", "Bootstrap project checksum does not match manifest", 1, { snapshot });
+    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" };
+}
+/**
+ * Snapshot a deliberately dedicated DD_FLOW_HOME. Eval checkpoints are not a
+ * general runtime export format: a shared home fails closed instead of trying
+ * to infer a safe subset of SQLite rows.
+ */
+export function createEvalRunSnapshot(context, input) {
+    const projectRoot = resolveProjectRoot(input.projectRoot);
+    // Snapshot is read-only at the control-plane boundary. An invalid workspace
+    // root must fail without registering a second project in a dedicated home.
+    const project = requireProjectByRoot(context, projectRoot);
+    const status = getFlowRunStatus(context, { projectRoot, runId: input.runId });
+    assertDedicatedHome(context, project.id, input.runId);
+    if (input.candidate)
+        assertTerminalCandidate(status.index.stage_runs ?? []);
+    else if (input.stageEntry)
+        assertStageEntry(status.index.stage_runs ?? [], input.stageEntry);
+    else
+        throw new AppError("usage", "Snapshot requires exactly one of stageEntry or candidate", 2);
+    const activeChildren = input.candidate
+        ? context.db.get("SELECT COUNT(*) AS count FROM works WHERE project_id = ? AND run_id = ? AND parent_work_id IS NOT NULL AND status IN ('created', 'running', 'paused')", [project.id, input.runId])?.count ?? 0
+        : context.db.get("SELECT COUNT(*) AS count FROM works WHERE project_id = ? AND run_id = ? AND parent_work_id IS NOT NULL AND (status IN ('running', 'paused') OR (status = 'created' AND (? <> 'code' OR COALESCE(result_schema, '') NOT LIKE 'dd-flow/code-work-result@%')))", [project.id, input.runId, input.stageEntry])?.count ?? 0;
+    if (activeChildren > 0)
+        throw new AppError("snapshot_not_quiescent", `${input.candidate ? "Candidate" : "Stage-entry"} snapshot requires no active child Work`, 1, { run_id: input.runId, active_children: activeChildren });
+    const output = path.resolve(input.output);
+    if (fs.existsSync(output))
+        throw new AppError("snapshot_exists", "Snapshot output already exists", 1, { output });
+    if (isInside(physicalPath(context.ddFlowHome), physicalPath(output)))
+        throw new AppError("snapshot_output_inside_runtime", "Snapshot output must be outside DD_FLOW_HOME", 1, { output });
+    const workspaceRoot = String(status.run.workspace_root ?? projectRoot);
+    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 });
+    context.db.exec("PRAGMA wal_checkpoint(TRUNCATE)");
+    fs.mkdirSync(output, { recursive: true });
+    fs.cpSync(context.ddFlowHome, path.join(output, "runtime"), {
+        recursive: true,
+        verbatimSymlinks: true,
+        filter: (source) => path.basename(source) !== "engines"
+    });
+    fs.cpSync(projectRoot, path.join(output, "project"), {
+        recursive: true,
+        verbatimSymlinks: true,
+        filter: (source) => path.basename(source) !== ".git"
+    });
+    const projectGit = snapshotProjectGit(projectRoot, output);
+    const workspace = snapshotWorkspace(workspaceRoot, projectRoot, output);
+    const manifest = {
+        schema_id: "dd-flow/eval-run-snapshot@5",
+        run_id: input.runId,
+        project_id: project.id,
+        project_root: projectRoot,
+        dd_flow_home: context.ddFlowHome,
+        purpose: input.candidate ? "candidate" : "stage_entry",
+        stage_entry: input.candidate ? null : input.stageEntry,
+        created_at: context.now(),
+        runtime_sha256: treeHash(path.join(output, "runtime")),
+        project_sha256: treeHash(path.join(output, "project")),
+        project_git: projectGit,
+        workspace,
+        source_status: status
+    };
+    writeJson(path.join(output, "snapshot.json"), manifest);
+    return { ok: true, snapshot: output, ...manifest };
+}
+export function restoreEvalRunSnapshot(context, input) {
+    const snapshot = path.resolve(input.snapshot);
+    const manifest = readManifest(snapshot);
+    if (manifest.purpose === "candidate")
+        throw new AppError("snapshot_candidate_not_restorable", "A terminal candidate snapshot is evidence, not a stage-entry fixture", 1, { snapshot });
+    if (!manifest.stage_entry)
+        throw new AppError("snapshot_invalid", "Stage-entry snapshot has no target stage", 1, { snapshot });
+    const projectRoot = resolveProjectRoot(input.projectRoot);
+    const existing = fs.readdirSync(context.ddFlowHome).filter((name) => !["db.sqlite", "db.sqlite-wal", "db.sqlite-shm"].includes(name));
+    if (existing.length > 0)
+        throw new AppError("restore_home_not_empty", "Snapshot restore requires an empty DD_FLOW_HOME", 1, { dd_flow_home: context.ddFlowHome, existing });
+    const sourceRuntime = path.join(snapshot, "runtime");
+    const sourceProject = path.join(snapshot, "project");
+    if (treeHash(sourceRuntime) !== manifest.runtime_sha256)
+        throw new AppError("snapshot_checksum_mismatch", "Snapshot runtime checksum does not match manifest", 1, { snapshot });
+    if (treeHash(sourceProject) !== manifest.project_sha256)
+        throw new AppError("snapshot_checksum_mismatch", "Snapshot project checksum does not match manifest", 1, { snapshot });
+    clearProjectTree(projectRoot, false);
+    restoreProjectGit(snapshot, manifest.project_git, projectRoot);
+    replaceProjectTree(projectRoot, sourceProject);
+    const workspaceRoot = restoreWorkspace(snapshot, manifest, projectRoot, context.ddFlowHome);
+    context.db.close?.();
+    fs.rmSync(context.ddFlowHome, { recursive: true, force: true });
+    fs.cpSync(sourceRuntime, context.ddFlowHome, { recursive: true, verbatimSymlinks: true });
+    // The dispatch context was intentionally closed before replacing db.sqlite.
+    // A fresh process owns all subsequent normal commands.
+    const restored = createContext({ ...context.env, DD_FLOW_HOME: context.ddFlowHome });
+    try {
+        rebaseRuntime(restored, manifest.project_root, projectRoot, sourceWorkspaceRoot(manifest), workspaceRoot, manifest.dd_flow_home, context.ddFlowHome);
+        registerProject(restored, { root: projectRoot });
+        const project = requireProjectByRoot(restored, projectRoot);
+        const status = getFlowRunStatus(restored, { projectRoot, runId: manifest.run_id });
+        assertStageEntry(status.index.stage_runs ?? [], manifest.stage_entry);
+        const runHome = status.run.run_home_path ?? path.join(context.ddFlowHome, "projects", project.id, "runs", manifest.run_id);
+        return {
+            ok: true,
+            schema_id: "dd-flow/eval-run-restore@1",
+            snapshot,
+            run_id: status.run.id,
+            project_root: projectRoot,
+            workspace_root: workspaceRoot,
+            dd_flow_home: context.ddFlowHome,
+            run_home: runHome,
+            target_stage: manifest.stage_entry,
+            next_command: `dd-flow stage start ${status.run.id} --stage ${manifest.stage_entry} --project-root ${JSON.stringify(projectRoot)} --json`
+        };
+    }
+    finally {
+        restored.db.close?.();
+    }
+}
+export function prepareVnextSpecifyRun(context, input) {
+    const projectRoot = resolveProjectRoot(input.projectRoot);
+    const definition = readVnextFlowDefinition(projectRoot);
+    if (!definition)
+        throw new AppError("not_found", "vNext SPECIFY flow definition is missing", 1, { project_root: projectRoot });
+    const started = startFlowRun(context, {
+        projectRoot,
+        flowKind: definition.id === "mb-sdlc-vnext-protocolize" ? "vnext_protocolize" : "vnext_specify",
+        subjectType: "discussion",
+        subjectId: "SPECIFY",
+        slug: input.slug,
+        nextAction: "start_specify"
+    });
+    return { ok: true, run_id: started.run.id, run_home: started.run.run_home_path, target_stage: "specify" };
+}
+function assertDedicatedHome(context, projectId, runId) {
+    const projects = context.db.get("SELECT COUNT(*) AS count FROM projects")?.count ?? 0;
+    const runs = context.db.get("SELECT COUNT(*) AS count FROM runs")?.count ?? 0;
+    const own = context.db.get("SELECT COUNT(*) AS count FROM runs WHERE project_id = ? AND id = ?", [projectId, runId])?.count ?? 0;
+    if (projects !== 1 || runs !== 1 || own !== 1)
+        throw new AppError("snapshot_home_not_dedicated", "Snapshot requires a dedicated DD_FLOW_HOME with exactly one project and RUN", 1, { projects, runs, run_id: runId });
+}
+function assertStageEntry(stages, target) {
+    if (stages.some((entry) => entry.stage === target))
+        throw new AppError("snapshot_target_started", "Stage-entry snapshot requires its target stage to be unstarted", 1, { target });
+    const unfinished = stages.filter((entry) => entry.status !== "done");
+    if (unfinished.length > 0)
+        throw new AppError("snapshot_predecessor_incomplete", "Stage-entry snapshot requires completed predecessor stages", 1, { target, unfinished });
+}
+function assertTerminalCandidate(stages) {
+    const unfinished = stages.filter((entry) => entry.status !== "done");
+    if (unfinished.length > 0)
+        throw new AppError("snapshot_candidate_incomplete", "Candidate snapshot requires every started stage to be done", 1, { unfinished });
+}
+function rebaseRuntime(context, oldRoot, newRoot, oldWorkspace, newWorkspace, oldHome, newHome) {
+    context.db.exec("PRAGMA foreign_keys = OFF");
+    context.db.exec("BEGIN IMMEDIATE");
+    try {
+        context.db.run("UPDATE projects SET root = ?", [newRoot]);
+        context.db.run("UPDATE runs SET project_root = ?, workspace_root = ?", [newRoot, newWorkspace]);
+        for (const column of ["runtime_path", "run_dir", "run_index_path", "run_home_path", "run_root", "index_json"])
+            rewriteDatabaseColumn(context, "runs", column, oldRoot, newRoot, oldWorkspace, newWorkspace, oldHome, newHome);
+        context.db.run("UPDATE protocols SET project_root = ?", [newRoot]);
+        for (const column of ["state_path", "plan_path"])
+            rewriteDatabaseColumn(context, "protocols", column, oldRoot, newRoot, oldWorkspace, newWorkspace, oldHome, newHome);
+        context.db.run("UPDATE sessions SET project_root = ?, status = CASE WHEN status = 'active' THEN 'stopped' ELSE status END, stop_reason = CASE WHEN status = 'active' THEN 'snapshot_restored' ELSE stop_reason END", [newRoot]);
+        for (const column of ["workspace_path", "cwd", "transcript_path"])
+            rewriteDatabaseColumn(context, "sessions", column, oldRoot, newRoot, oldWorkspace, newWorkspace, oldHome, newHome);
+        for (const column of ["prompt_path", "result_path"])
+            rewriteDatabaseColumn(context, "work_sessions", column, oldRoot, newRoot, oldWorkspace, newWorkspace, oldHome, newHome);
+        for (const column of ["stdout_path", "stderr_path", "receipt_path", "artifacts_json"])
+            rewriteDatabaseColumn(context, "check_receipts", column, oldRoot, newRoot, oldWorkspace, newWorkspace, oldHome, newHome);
+        rewriteDatabaseColumn(context, "usage", "source_locator", oldRoot, newRoot, oldWorkspace, newWorkspace, oldHome, newHome);
+        for (const column of ["worktree_path", "worktrunk_metadata_json", "last_command_result_json"])
+            rewriteDatabaseColumn(context, "worktree_records", column, oldRoot, newRoot, oldWorkspace, newWorkspace, oldHome, newHome);
+        context.db.run("UPDATE work_sessions SET status = CASE WHEN status = 'running' THEN 'completed' ELSE status END, completed_at = COALESCE(completed_at, ?), updated_at = ?", [context.now(), context.now()]);
+        context.db.run("DELETE FROM codex_session_bindings");
+        context.db.run("COMMIT");
+    }
+    catch (error) {
+        context.db.exec("ROLLBACK");
+        throw error;
+    }
+    finally {
+        context.db.exec("PRAGMA foreign_keys = ON");
+    }
+    rewriteStructuredFiles(context.ddFlowHome, oldRoot, newRoot, oldWorkspace, newWorkspace, oldHome, newHome);
+}
+function rewriteStructuredFiles(root, oldRoot, newRoot, oldWorkspace, newWorkspace, oldHome, newHome) {
+    const visit = (dir) => {
+        for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+            const file = path.join(dir, entry.name);
+            // DD_FLOW_HOME also contains the restored checkout and installed tools.
+            // They are project/tool bytes, not flow records; parsing every *.json
+            // there breaks on valid JSON-with-comments such as tsconfig files.
+            if (entry.isDirectory() && ![".git", "checkouts", "engines", "node_modules", "tools"].includes(entry.name))
+                visit(file);
+            else if (entry.isFile() && entry.name.endsWith(".json")) {
+                const value = JSON.parse(fs.readFileSync(file, "utf8"));
+                writeJson(file, rebaseStructuredValue(value, oldRoot, newRoot, oldWorkspace, newWorkspace, oldHome, newHome));
+            }
+            else if (entry.isFile() && entry.name.endsWith(".jsonl")) {
+                const lines = fs.readFileSync(file, "utf8").split("\n").filter(Boolean).map((line) => JSON.stringify(rebaseStructuredValue(JSON.parse(line), oldRoot, newRoot, oldWorkspace, newWorkspace, oldHome, newHome)));
+                fs.writeFileSync(file, `${lines.join("\n")}\n`);
+            }
+        }
+    };
+    visit(root);
+}
+function rewriteDatabaseColumn(context, table, column, oldRoot, newRoot, oldWorkspace, newWorkspace, oldHome, newHome) { for (const row of context.db.all(`SELECT rowid AS rid, ${column} AS value FROM ${table} WHERE ${column} IS NOT NULL`)) {
+    if (!row.value)
+        continue;
+    const value = column.endsWith("_json") || column === "index_json" ? JSON.stringify(rebaseStructuredValue(JSON.parse(row.value), oldRoot, newRoot, oldWorkspace, newWorkspace, oldHome, newHome)) : rebasePathString(row.value, oldRoot, newRoot, oldWorkspace, newWorkspace, oldHome, newHome);
+    if (value !== row.value)
+        context.db.run(`UPDATE ${table} SET ${column} = ? WHERE rowid = ?`, [value, row.rid]);
+} }
+function rebaseStructuredValue(value, oldRoot, newRoot, oldWorkspace, newWorkspace, oldHome, newHome) { if (typeof value === "string")
+    return rebasePathString(value, oldRoot, newRoot, oldWorkspace, newWorkspace, oldHome, newHome); if (Array.isArray(value))
+    return value.map((item) => rebaseStructuredValue(item, oldRoot, newRoot, oldWorkspace, newWorkspace, oldHome, newHome)); if (value && typeof value === "object")
+    return Object.fromEntries(Object.entries(value).map(([key, item]) => [key, rebaseStructuredValue(item, oldRoot, newRoot, oldWorkspace, newWorkspace, oldHome, newHome)])); return value; }
+function rebasePathString(value, oldRoot, newRoot, oldWorkspace, newWorkspace, oldHome, newHome) { for (const [oldPrefix, newPrefix] of [[oldHome, newHome], [oldWorkspace, newWorkspace], [oldRoot, newRoot]])
+    if (value === oldPrefix || value.startsWith(`${oldPrefix}${path.sep}`))
+        return `${newPrefix}${value.slice(oldPrefix.length)}`; return value; }
+function snapshotWorkspace(workspaceRoot, projectRoot, output) {
+    if (samePath(workspaceRoot, projectRoot))
+        return { kind: "project" };
+    const branch = git(workspaceRoot, ["symbolic-ref", "--quiet", "--short", "HEAD"]);
+    if (!branch)
+        throw new AppError("snapshot_workspace_invalid", "Feature workspace must be on a named Git branch", 1, { workspace_root: workspaceRoot });
+    const baseRef = git(workspaceRoot, ["rev-parse", "HEAD"]);
+    if (!baseRef)
+        throw new AppError("snapshot_workspace_invalid", "Feature workspace has no readable HEAD", 1, { workspace_root: workspaceRoot });
+    const workspace = path.join(output, "workspace");
+    const bundle = path.join(output, "workspace.bundle");
+    fs.cpSync(workspaceRoot, workspace, { recursive: true, verbatimSymlinks: true, filter: (source) => path.basename(source) !== ".git" });
+    runGit(projectRoot, ["bundle", "create", bundle, branch]);
+    return { kind: "git_worktree", source_root: workspaceRoot, branch, base_ref: baseRef, sha256: treeHash(workspace), bundle_sha256: fileHash(bundle) };
+}
+function restoreWorkspace(snapshot, manifest, projectRoot, ddFlowHome) {
+    if (manifest.workspace.kind === "project")
+        return projectRoot;
+    const source = path.join(snapshot, "workspace");
+    const bundle = path.join(snapshot, "workspace.bundle");
+    if (treeHash(source) !== manifest.workspace.sha256)
+        throw new AppError("snapshot_checksum_mismatch", "Snapshot workspace checksum does not match manifest", 1, { snapshot });
+    if (!fs.existsSync(bundle) || fileHash(bundle) !== manifest.workspace.bundle_sha256)
+        throw new AppError("snapshot_checksum_mismatch", "Snapshot workspace Git bundle does not match manifest", 1, { snapshot });
+    const managedRoot = physicalPath(manifest.dd_flow_home);
+    const sourceRoot = physicalPath(manifest.workspace.source_root);
+    const workspaceRoot = isInside(managedRoot, sourceRoot)
+        ? path.join(ddFlowHome, path.relative(managedRoot, sourceRoot))
+        : path.join(path.dirname(projectRoot), "workspace");
+    if (fs.existsSync(workspaceRoot))
+        throw new AppError("snapshot_workspace_target_exists", "Snapshot feature workspace target already exists", 1, { workspace_root: workspaceRoot });
+    runGit(projectRoot, ["fetch", bundle, `+refs/heads/${manifest.workspace.branch}:refs/heads/${manifest.workspace.branch}`]);
+    if (git(projectRoot, ["rev-parse", `refs/heads/${manifest.workspace.branch}`]) !== manifest.workspace.base_ref)
+        throw new AppError("snapshot_workspace_restore_failed", "Snapshot Git bundle did not restore the frozen feature base", 1, { branch: manifest.workspace.branch, expected_base: manifest.workspace.base_ref });
+    runGit(projectRoot, ["worktree", "add", workspaceRoot, manifest.workspace.branch]);
+    replaceProjectTree(workspaceRoot, source);
+    return fs.realpathSync(workspaceRoot);
+}
+function sourceWorkspaceRoot(manifest) {
+    return manifest.workspace.kind === "project" ? manifest.project_root : manifest.workspace.source_root;
+}
+function snapshotProjectGit(projectRoot, output) {
+    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 bundle = path.join(output, "project.bundle");
+    runGit(projectRoot, ["bundle", "create", bundle, "--all"]);
+    return { branch, head, bundle_sha256: fileHash(bundle) };
+}
+function restoreProjectGit(snapshot, source, projectRoot) {
+    const bundle = path.join(snapshot, "project.bundle");
+    if (!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]);
+}
+function git(root, args) {
+    const result = spawnSync("git", ["-C", root, ...args], { encoding: "utf8" });
+    return result.status === 0 ? result.stdout.trim() : null;
+}
+function runGit(root, args) {
+    const result = spawnSync("git", ["-C", root, ...args], { encoding: "utf8" });
+    if (result.status !== 0)
+        throw new AppError("snapshot_workspace_restore_failed", "Could not restore feature worktree", 1, { stderr: result.stderr.trim(), args });
+}
+function samePath(left, right) { return path.resolve(left) === path.resolve(right); }
+function treeHash(root) {
+    const hash = crypto.createHash("sha256");
+    const visit = (dir, relative) => {
+        for (const entry of fs.readdirSync(dir, { withFileTypes: true }).sort((a, b) => a.name.localeCompare(b.name))) {
+            const file = path.join(dir, entry.name);
+            const rel = path.join(relative, entry.name);
+            if (entry.isDirectory())
+                visit(file, rel);
+            else if (entry.isFile()) {
+                hash.update(rel);
+                hash.update(fs.readFileSync(file));
+            }
+            else if (entry.isSymbolicLink()) {
+                hash.update(rel);
+                hash.update(`symlink:${fs.readlinkSync(file)}`);
+            }
+        }
+    };
+    visit(root, "");
+    return hash.digest("hex");
+}
+function fileHash(file) { return crypto.createHash("sha256").update(fs.readFileSync(file)).digest("hex"); }
+function readManifest(snapshot) {
+    const file = path.join(snapshot, "snapshot.json");
+    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"].includes(value.purpose) || (value.purpose === "stage_entry" && !value.stage_entry) || (value.purpose === "candidate" && 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.project_git.branch || !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 });
+    return value;
+}
+function readBootstrapManifest(snapshot) {
+    const file = path.join(snapshot, "bootstrap.json");
+    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)
+        throw new AppError("snapshot_invalid", "Bootstrap snapshot manifest is invalid", 1, { snapshot });
+    return value;
+}
+function replaceProjectTree(projectRoot, source) {
+    if (!fs.existsSync(projectRoot) || !fs.statSync(projectRoot).isDirectory())
+        throw new AppError("project_missing", "Snapshot restore target project is missing", 1, { project_root: projectRoot });
+    clearProjectTree(projectRoot, true);
+    fs.cpSync(source, projectRoot, { recursive: true, verbatimSymlinks: true });
+}
+function clearProjectTree(projectRoot, preserveGit) {
+    if (!fs.existsSync(projectRoot) || !fs.statSync(projectRoot).isDirectory())
+        throw new AppError("project_missing", "Snapshot restore target project is missing", 1, { project_root: projectRoot });
+    for (const entry of fs.readdirSync(projectRoot)) {
+        if (preserveGit && entry === ".git")
+            continue;
+        fs.rmSync(path.join(projectRoot, entry), { recursive: true, force: true });
+    }
+}
+function physicalPath(value) {
+    const missing = [];
+    let current = path.resolve(value);
+    while (!fs.existsSync(current)) {
+        missing.unshift(path.basename(current));
+        current = path.dirname(current);
+    }
+    return path.join(fs.realpathSync(current), ...missing);
+}
+function isInside(root, candidate) {
+    const relative = path.relative(root, candidate);
+    return relative === "" || (!relative.startsWith(`..${path.sep}`) && relative !== ".." && !path.isAbsolute(relative));
+}
+function writeJson(file, value) { fs.writeFileSync(file, `${JSON.stringify(value, null, 2)}\n`); }