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

package/dist/services/plan-runtime.js

@@ -54,8 +54,8 @@ export function boundCanonicalPlan(context, input) {
     refreshProtocolRuns(context, input.projectId, input.protocolId);
     return canonical;
 }
-export function planWithProgress(context, input) {
-    const canonical = boundCanonicalPlan(context, input);
+export function planWithProgress(context, input, options = {}) {
+    const canonical = options.bind === false ? readCanonicalPlan(input.planPath, input.protocolId) : boundCanonicalPlan(context, input);
     const rows = context.db.all(`SELECT item_id, plan_revision, plan_sha256, status, summary, evidence_json, block_reason, user_required
      FROM plan_progress WHERE project_id = ? AND protocol_id = ?`, [input.projectId, input.protocolId]);
     const progress = new Map(rows.map((row) => [row.item_id, row]));
@@ -67,8 +67,8 @@ export function planWithProgress(context, input) {
         }
     };
 }
-export function planSummary(context, input) {
-    const { canonical, plan } = planWithProgress(context, input);
+export function planSummary(context, input, options = {}) {
+    const { canonical, plan } = planWithProgress(context, input, options);
     return {
         plan_id: plan.plan_id,
         revision: canonical.revision,

package/dist/services/plans.js

@@ -7,11 +7,11 @@ import { resolveProjectRoot } from "../storage/paths.js";
 import { planSummary, planWithProgress, updatePlanProgress } from "./plan-runtime.js";
 export function getPlanStatus(context, input) {
     const protocol = scopedProtocol(context, input.projectRoot, input.protocolId);
-    const current = planWithProgress(context, { projectId: protocol.project_id, protocolId: protocol.id, planPath: protocol.plan_path });
+    const current = planWithProgress(context, { projectId: protocol.project_id, protocolId: protocol.id, planPath: protocol.plan_path }, { bind: false });
     return {
         ok: true,
         protocol_id: protocol.id,
-        plan: planSummary(context, { projectId: protocol.project_id, protocolId: protocol.id, planPath: protocol.plan_path }),
+        plan: planSummary(context, { projectId: protocol.project_id, protocolId: protocol.id, planPath: protocol.plan_path }, { bind: false }),
         binding: { revision: current.canonical.revision, sha256: current.canonical.sha256, path: protocol.plan_path },
         blocked_items: current.plan.items
             .filter((item) => item.status === "blocked")
@@ -69,7 +69,9 @@ function updatePlanItem(context, projectRoot, protocolId, itemId, transform) {
 }
 function scopedProtocol(context, projectRoot, protocolId) {
     const project = requireProjectByRoot(context, resolveProjectRoot(projectRoot));
-    return requireProtocol(context, protocolId, project.id);
+    const protocol = requireProtocol(context, protocolId, project.id);
+    readProtocolRuntimeState(context, protocol);
+    return protocol;
 }
 function assertDependenciesClosed(plan, item) {
     const openDependencies = item.depends_on

package/dist/services/protocols.js

@@ -100,7 +100,7 @@ export function getProtocolStatus(context, input) {
         diagnostics: [...runtime.diagnostics, ...runDiagnostics.diagnostics, ...lifecycle.diagnostics],
         latest_run: runDiagnostics.latest_run,
         state,
-        plan: plan ? planSummary(context, { projectId: protocol.project_id, protocolId: protocol.id, planPath: protocol.plan_path }) : state.plan,
+        plan: plan ? planSummary(context, { projectId: protocol.project_id, protocolId: protocol.id, planPath: protocol.plan_path }, { bind: false }) : state.plan,
         merge_queue: queue,
         branch_context: getProtocolBranchContext(context, { protocolId: protocol.id, projectRoot: project.root }).branch_context,
         flow_guidance: buildProtocolFlowGuidance({ state, latestRun: runDiagnostics.latest_run, queueStatus: queue?.status ?? null }),
@@ -734,6 +734,7 @@ function releaseRelatedMergeLocks(context, protocol, reason) {
 }
 export function readProtocolRuntimeState(context, protocol) {
     const diagnostics = [];
+    normalizeProtocolPlanPath(context, protocol, diagnostics);
     try {
         return { state: readStateFile(protocol.state_path, protocol.id), diagnostics };
     }
@@ -764,7 +765,7 @@ export function readProtocolRuntimeState(context, protocol) {
     }
     const plan = canonicalPlanIfPresent(context, protocol);
     const summary = plan
-        ? planSummary(context, { projectId: protocol.project_id, protocolId: protocol.id, planPath: protocol.plan_path })
+        ? planSummary(context, { projectId: protocol.project_id, protocolId: protocol.id, planPath: protocol.plan_path }, { bind: false })
         : { plan_id: null, total: 0, done: 0, blocked: 0 };
     const flowContract = loadProjectFlowContract(protocol.project_root);
     const state = {
@@ -782,6 +783,9 @@ export function readProtocolRuntimeState(context, protocol) {
         flow_contract: flowContract,
         updated_at: protocol.updated_at
     };
+    if (!context.db.writable) {
+        return { state, diagnostics };
+    }
     const stableStatePath = runtimeStateJsonPath(context.ddFlowHome, protocol.project_id, protocol.id);
     const stablePlanPath = planJsonPath(protocol.project_root, protocol.id);
     ensureDir(path.dirname(stableStatePath));
@@ -798,6 +802,23 @@ export function readProtocolRuntimeState(context, protocol) {
     });
     return { state, diagnostics };
 }
+function normalizeProtocolPlanPath(context, protocol, diagnostics) {
+    const canonicalPlanPath = planJsonPath(protocol.project_root, protocol.id);
+    if (protocol.plan_path === canonicalPlanPath || !fs.existsSync(canonicalPlanPath))
+        return;
+    diagnostics.push({
+        code: "protocol_plan_relocated",
+        severity: "warning",
+        old_path: protocol.plan_path,
+        path: canonicalPlanPath,
+        source: "project_canonical_plan",
+        recommended_action: "use the project canonical plan as the sole semantic plan source"
+    });
+    if (context.db.writable) {
+        context.db.run("UPDATE protocols SET plan_path = ?, updated_at = ? WHERE project_id = ? AND id = ?", [canonicalPlanPath, context.now(), protocol.project_id, protocol.id]);
+    }
+    protocol.plan_path = canonicalPlanPath;
+}
 export function protocolRunDiagnostics(context, protocol, state) {
     const runs = linkedRunsForProtocol(context, protocol, 5);
     const latest = runs[0];

package/dist/services/run-engine-bindings.js

@@ -0,0 +1,157 @@
+import fs from "node:fs";
+import path from "node:path";
+import { AppError } from "../shared/errors.js";
+export const runEngineBindingSchemaId = "dd-flow/run-engine-binding@1";
+export function findRunHome(ddFlowHome, projectRoot, runIdOrAlias) {
+    const projectsRoot = path.join(ddFlowHome, "projects");
+    if (!fs.existsSync(projectsRoot))
+        return null;
+    const expectedRoot = realpathOrResolve(projectRoot);
+    const matches = [];
+    for (const projectId of fs.readdirSync(projectsRoot)) {
+        const runsRoot = path.join(projectsRoot, projectId, "runs");
+        if (!isDirectory(runsRoot))
+            continue;
+        for (const runId of fs.readdirSync(runsRoot)) {
+            if (!runIdMatches(runId, runIdOrAlias))
+                continue;
+            const runHome = path.join(runsRoot, runId);
+            const authorityPath = path.join(runHome, "run.json");
+            const bindingPath = path.join(runHome, "engine-binding.json");
+            const binding = readRunEngineBinding(bindingPath, { allowMissing: true });
+            const authorityRoot = binding?.project_root ?? projectRootFromAuthority(authorityPath);
+            if (!authorityRoot || realpathOrResolve(authorityRoot) !== expectedRoot)
+                continue;
+            matches.push({ project_id: projectId, run_id: runId, run_home: runHome, authority_path: authorityPath, binding_path: bindingPath });
+        }
+    }
+    if (matches.length > 1) {
+        throw new AppError("ambiguous_id", `RUN id is ambiguous for project: ${runIdOrAlias}`, 2, {
+            project_root: expectedRoot,
+            candidates: matches.map((match) => match.run_id)
+        });
+    }
+    return matches[0] ?? null;
+}
+export function readRunEngineBinding(file, options = {}) {
+    if (!fs.existsSync(file)) {
+        if (options.allowMissing)
+            return null;
+        throw new AppError("run_engine_binding_missing", "RUN engine binding is missing", 1, { path: file });
+    }
+    let value;
+    try {
+        value = JSON.parse(fs.readFileSync(file, "utf8"));
+    }
+    catch (error) {
+        throw new AppError("run_engine_binding_invalid", "RUN engine binding is not valid JSON", 2, { path: file, cause: String(error) });
+    }
+    if (!isRunEngineBinding(value)) {
+        throw new AppError("run_engine_binding_invalid", "RUN engine binding is invalid", 2, { path: file });
+    }
+    return value;
+}
+export function writeRunEngineBinding(file, binding) {
+    const existing = readRunEngineBinding(file, { allowMissing: true });
+    if (existing) {
+        if (sameEngine(existing.engine, binding.engine) && existing.run_id === binding.run_id && realpathOrResolve(existing.project_root) === realpathOrResolve(binding.project_root)) {
+            return { changed: false, binding: existing };
+        }
+        throw new AppError("run_engine_binding_immutable", "RUN engine binding cannot be changed", 1, {
+            path: file,
+            current: existing.engine,
+            requested: binding.engine
+        });
+    }
+    fs.mkdirSync(path.dirname(file), { recursive: true });
+    const temporary = `${file}.tmp-${process.pid}-${Date.now()}`;
+    fs.writeFileSync(temporary, `${JSON.stringify(binding, null, 2)}\n`);
+    fs.renameSync(temporary, file);
+    return { changed: true, binding };
+}
+export function allRunEngineBindings(ddFlowHome) {
+    const projectsRoot = path.join(ddFlowHome, "projects");
+    if (!fs.existsSync(projectsRoot))
+        return [];
+    const bindings = [];
+    for (const projectId of fs.readdirSync(projectsRoot)) {
+        const runsRoot = path.join(projectsRoot, projectId, "runs");
+        if (!isDirectory(runsRoot))
+            continue;
+        for (const runId of fs.readdirSync(runsRoot)) {
+            const binding = readRunEngineBinding(path.join(runsRoot, runId, "engine-binding.json"), { allowMissing: true });
+            if (binding)
+                bindings.push(binding);
+        }
+    }
+    return bindings;
+}
+function isRunEngineBinding(value) {
+    if (!value || typeof value !== "object" || Array.isArray(value))
+        return false;
+    const record = value;
+    const engine = record.engine;
+    const probe = record.probe;
+    return record.schema_id === runEngineBindingSchemaId
+        && typeof record.run_id === "string"
+        && typeof record.project_root === "string"
+        && typeof record.bound_at === "string"
+        && ["run_creation", "legacy_recovery"].includes(String(record.source))
+        && typeof record.reason === "string"
+        && Boolean(engine && typeof engine === "object" && !Array.isArray(engine)
+            && typeof engine.package_name === "string"
+            && typeof engine.package_version === "string"
+            && typeof engine.engine_version === "string"
+            && /^[a-f0-9]{64}$/.test(String(engine.integrity_checksum))
+            && typeof engine.snapshot_root === "string")
+        && Boolean(probe && typeof probe === "object" && !Array.isArray(probe)
+            && ["not_required", "passed"].includes(String(probe.status))
+            && (typeof probe.command === "string" || probe.command === null));
+}
+function sameEngine(left, right) {
+    return left.package_name === right.package_name
+        && left.package_version === right.package_version
+        && left.engine_version === right.engine_version
+        && left.integrity_checksum === right.integrity_checksum
+        && left.snapshot_root === right.snapshot_root;
+}
+function projectRootFromAuthority(file) {
+    try {
+        const value = JSON.parse(fs.readFileSync(file, "utf8"));
+        const execution = recordValue(value.execution);
+        const workspace = recordValue(value.workspace);
+        const project = recordValue(value.project);
+        return stringValue(execution?.project_root)
+            ?? stringValue(workspace?.project_root)
+            ?? stringValue(project?.root)
+            ?? stringValue(value.project_root);
+    }
+    catch {
+        return null;
+    }
+}
+function runIdMatches(fullId, idOrAlias) {
+    return fullId === idOrAlias || /^RUN-[0-9]+$/.test(idOrAlias) && fullId.startsWith(`${idOrAlias}-`);
+}
+function isDirectory(value) {
+    try {
+        return fs.statSync(value).isDirectory();
+    }
+    catch {
+        return false;
+    }
+}
+function realpathOrResolve(value) {
+    try {
+        return fs.realpathSync(value);
+    }
+    catch {
+        return path.resolve(value);
+    }
+}
+function recordValue(value) {
+    return value && typeof value === "object" && !Array.isArray(value) ? value : null;
+}
+function stringValue(value) {
+    return typeof value === "string" && value.length > 0 ? value : null;
+}

package/dist/services/run-projection.js

@@ -1,21 +1,33 @@
 import fs from "node:fs";
 import path from "node:path";
+import { reconcileSessionCoverageRows } from "../domain/session-coverage.js";
 export function refreshRunSessionProjection(context, projectId, runId) {
-    const run = context.db.get("SELECT id, project_root, subject_type, subject_id, runtime_path, run_index_path, index_json FROM flow_runs WHERE project_id = ? AND id = ?", [projectId, runId]);
+    const run = context.db.get("SELECT id, status, project_root, subject_type, subject_id, runtime_path, run_index_path, index_json FROM flow_runs WHERE project_id = ? AND id = ?", [projectId, runId]);
     if (!run)
         return;
     const index = JSON.parse(run.index_json);
-    const sessions = context.db.all(`SELECT session_id, parent_session_id, role, session_kind, worker_id, current_stage, status,
+    const sessionRows = context.db.all(`SELECT session_id, parent_session_id, role, session_kind, worker_id, current_stage, status,
             created_at, updated_at, stopped_at, coverage_units_json
-       FROM flow_sessions WHERE project_id = ? AND run_id = ? ORDER BY created_at, session_id`, [projectId, runId]).map(sessionProjection);
+       FROM flow_sessions WHERE project_id = ? AND run_id = ? ORDER BY created_at, session_id`, [projectId, runId]);
+    const sessions = sessionRows.map(sessionProjection);
+    const coverage = reconcileSessionCoverageRows(sessionRows);
+    const sessionCoverage = {
+        status: coverage.status,
+        expected: coverage.expected_unit_ids,
+        observed: coverage.observed_unit_ids,
+        missing: coverage.missing_unit_ids,
+        diagnostics: coverage.diagnostics
+    };
     const plan = run.subject_type === "protocol" ? planProjection(context, projectId, run.subject_id, run.project_root) : {};
     const workers = workerProjection(context, projectId, runId);
     if (JSON.stringify(index.sessions ?? []) === JSON.stringify(sessions)
+        && JSON.stringify(index.session_coverage) === JSON.stringify(sessionCoverage)
         && JSON.stringify(index.plan_ref) === JSON.stringify(plan.plan_ref)
         && JSON.stringify(index.plan_progress) === JSON.stringify(plan.plan_progress)
         && JSON.stringify(index.workers ?? {}) === JSON.stringify(workers))
         return;
     index.sessions = sessions;
+    index.session_coverage = sessionCoverage;
     if (plan.plan_ref)
         index.plan_ref = plan.plan_ref;
     if (plan.plan_progress)
@@ -31,6 +43,7 @@ export function refreshRunSessionProjection(context, projectId, runId) {
     index.runtime_revision = runtimeRevision;
     const authoritative = runtime ?? { ...index, schema_id: "dd-flow/flow-run@2" };
     authoritative.sessions = sessions;
+    authoritative.session_coverage = sessionCoverage;
     if (plan.plan_ref)
         authoritative.plan_ref = plan.plan_ref;
     if (plan.plan_progress)
@@ -38,7 +51,8 @@ export function refreshRunSessionProjection(context, projectId, runId) {
     authoritative.workers = workers;
     authoritative.updated_at = index.updated_at;
     authoritative.runtime_revision = runtimeRevision;
-    writeJson(run.runtime_path, authoritative);
+    if (run.status !== "discarded" || fs.existsSync(run.runtime_path))
+        writeJson(run.runtime_path, authoritative);
     context.db.run("UPDATE flow_runs SET index_json = ?, updated_at = ? WHERE project_id = ? AND id = ?", [JSON.stringify(index), index.updated_at, projectId, runId]);
 }
 function planProjection(context, projectId, protocolId, projectRoot) {

package/dist/services/runs.js

@@ -3,7 +3,7 @@ import fs from "node:fs";
 import path from "node:path";
 import { spawnSync } from "node:child_process";
 import { formatFullId, isFullEntityId, isShortEntityId, parseFullEntityId } from "../domain/entity-ids.js";
-import { checksumForFlowFlagValues, isFlowFlagDowngrade, loadProjectFlowContract, resolveFlowFlags } from "../domain/flow-contract.js";
+import { checksumForFlowFlagValues, isFlowFlagDowngrade, loadCanonicalFlowContract, loadProjectFlowContract, resolveFlowFlags } from "../domain/flow-contract.js";
 import { AppError } from "../shared/errors.js";
 import { ensureDir, projectRunHome, projectRunJsonPath, resolveProjectRoot } from "../storage/paths.js";
 import { appendAudit } from "./audit.js";
@@ -12,6 +12,8 @@ import { buildRunFlowGuidance } from "./flow-guidance.js";
 import { readProtocolRuntimeState, requireProtocol } from "./protocols.js";
 import { checkpointRunUsage, usageForRun } from "./usage.js";
 import { refreshRunSessionProjection } from "./run-projection.js";
+import { resolveCanonRoot } from "./canon.js";
+import { bindCurrentEngineToRun } from "./engines.js";
 const runSchemaId = "dd-flow/flow-run@2";
 const runtimeSchemaId = "dd-flow/flow-run@2";
 const runIdType = "RUN";
@@ -30,7 +32,9 @@ const allowedRunFlowKinds = [
 ];
 export function startFlowRun(context, input) {
     const projectRoot = resolveProjectRoot(input.projectRoot);
-    const flowContract = loadProjectFlowContract(projectRoot);
+    const flowContract = input.flowKind === "mb-upgrade"
+        ? loadUpgradeFlowContract(context, projectRoot)
+        : loadProjectFlowContract(projectRoot);
     registerProject(context, { root: projectRoot });
     const project = requireProjectByRoot(context, projectRoot);
     const workspaceRoot = resolveWorkspaceRoot(input.workspaceRoot ?? projectRoot);
@@ -107,6 +111,7 @@ export function startFlowRun(context, input) {
     };
     ensureDir(path.dirname(runtimePath));
     ensureDir(runHome);
+    bindCurrentEngineToRun(context, { projectRoot, runId, runHome });
     writeJsonFile(runtimePath, runtimeSnapshotForIndex(index, 1));
     context.db.run(`INSERT INTO flow_runs
       (id, short_id, slug, project_id, project_root, workspace_root, flow_kind, subject_type, subject_id,
@@ -151,14 +156,23 @@ export function startFlowRun(context, input) {
     });
     return { ok: true, run: flowRunSummary(requireRunById(context, project.id, runId)), index };
 }
+function loadUpgradeFlowContract(context, projectRoot) {
+    const canon = resolveCanonRoot(context, context.env.DD_MEMORYBANK ? { explicitRoot: context.env.DD_MEMORYBANK } : {});
+    if (!canon.ok || !canon.canon) {
+        throw new AppError("canon_unavailable", "mb-upgrade RUN requires the pinned canonical Memory Bank", 1, {
+            project_root: projectRoot,
+            blockers: canon.blockers,
+            bootstrap: canon.bootstrap
+        });
+    }
+    return loadCanonicalFlowContract(canon.canon.flow_root);
+}
 export function getFlowRunStatus(context, input) {
     const project = requireProjectByRoot(context, resolveProjectRoot(input.projectRoot));
     const run = resolveRun(context, project.id, input.runId);
-    refreshRunSessionProjection(context, project.id, run.id);
-    const refreshedRun = requireRunById(context, project.id, run.id);
-    const index = authoritativeIndex(refreshedRun);
-    const runtime = readRuntimeSnapshot(refreshedRun.runtime_path);
-    return { ok: true, run: flowRunSummary(refreshedRun), index, ...(runtime ? { runtime } : {}), flow_guidance: guidanceForRun(context, refreshedRun, index) };
+    const index = authoritativeIndex(run);
+    const runtime = readRuntimeSnapshot(run.runtime_path);
+    return { ok: true, run: flowRunSummary(run), index, ...(runtime ? { runtime } : {}), flow_guidance: guidanceForRun(context, run, index) };
 }
 export function getFlowRunFlagsStatus(context, input) {
     const project = requireProjectByRoot(context, resolveProjectRoot(input.projectRoot));
@@ -428,6 +442,7 @@ export function completeFlowRun(context, input) {
         };
     }
     persistRunState(context, project, run, index);
+    closeRunOrchestrators(context, project.id, run, status, now);
     refreshRunSessionProjection(context, project.id, run.id);
     appendAudit(context, {
         projectId: project.id,
@@ -439,6 +454,30 @@ export function completeFlowRun(context, input) {
     const updatedRun = requireRunById(context, project.id, run.id);
     return { ok: true, run: flowRunSummary(updatedRun), index, flow_guidance: guidanceForRun(context, updatedRun, index) };
 }
+function closeRunOrchestrators(context, projectId, run, status, now) {
+    if (!["done", "blocked", "cancelled", "failed"].includes(status))
+        return;
+    const active = context.db.all(`SELECT session_id FROM flow_sessions
+     WHERE project_id = ? AND run_id = ? AND session_kind = 'orchestrator'
+       AND status IN ('pending', 'active', 'waiting_user', 'blocked', 'stopping')`, [projectId, run.id]);
+    if (active.length === 0)
+        return;
+    const reason = `run_${status}`;
+    context.db.run(`UPDATE flow_sessions SET status = 'stopped', stop_reason = ?, updated_at = ?, stopped_at = ?
+     WHERE project_id = ? AND run_id = ? AND session_kind = 'orchestrator'
+       AND status IN ('pending', 'active', 'waiting_user', 'blocked', 'stopping')`, [reason, now, now, projectId, run.id]);
+    context.db.run(`UPDATE flow_session_segments SET ended_at = ?
+     WHERE project_id = ? AND run_id = ? AND session_id IN (${active.map(() => "?").join(", ")}) AND ended_at IS NULL`, [now, projectId, run.id, ...active.map((session) => session.session_id)]);
+    for (const session of active) {
+        appendRunTimeline(runArtifactRoot(run), {
+            at: now,
+            type: "session_stopped",
+            run_id: run.id,
+            session_id: session.session_id,
+            reason
+        });
+    }
+}
 const timelineSections = ["stages", "events", "sessions", "usage", "artifacts"];
 export function getFlowRunTimeline(context, input) {
     const project = requireProjectByRoot(context, resolveProjectRoot(input.projectRoot));
@@ -511,6 +550,14 @@ export function appendFlowRunTimelineEvent(context, projectId, runId, event) {
     appendRunTimeline(runArtifactRoot(run), { run_id: run.id, ...event });
 }
 function guidanceForRun(context, run, index) {
+    if (run.status === "discarded") {
+        return buildRunFlowGuidance({
+            stageRuns: index.stage_runs,
+            protocolStage: "cancelled",
+            runId: run.id,
+            runDir: index.run_home?.relative_path ?? path.posix.join("runs", run.id)
+        });
+    }
     if (run.subject_type === "protocol") {
         try {
             const protocol = requireProtocol(context, run.subject_id, run.project_id);

package/dist/services/schema-validation.js

@@ -5,6 +5,7 @@ import { fileURLToPath } from "node:url";
 import { Ajv } from "ajv/dist/ajv.js";
 import { normalizeFlowContract } from "../domain/flow-contract.js";
 import { AppError } from "../shared/errors.js";
+import { findRunHome, readRunEngineBinding } from "./run-engine-bindings.js";
 export function captureMemoryBankBaseline(input) {
     const projectRoot = path.resolve(input.projectRoot);
     const paths = normalizeMemoryBankPaths(projectRoot, input.paths);
@@ -116,6 +117,9 @@ export function validateSchema(options) {
     };
 }
 function resolveSchema(options) {
+    const bound = resolveRunBoundSchema(options);
+    if (bound)
+        return bound;
     const fileNames = [`${options.schemaName}.schema.json`];
     const projectRoot = path.resolve(options.projectRoot ?? process.cwd());
     const roots = [
@@ -145,6 +149,98 @@ function resolveSchema(options) {
         source: found.source
     };
 }
+const historicalSchemaRegistry = {
+    "294fd5f24ec6a4f938f15dfd98a4b303c2e026753062c3c6c8b15e09029a1128": [{
+            name: "merge-stage-report",
+            id: "dd-flow/merge-stage-report@2/engine-0.4.2",
+            path: "dist/schemas/merge-stage-report-legacy-0.4.2.schema.json",
+            checksum: "d861630cafd51e71e5440dadac2628413501e8b063ff19bef7d16966dc7077e3"
+        }],
+    "0fc717e17c359242662b76d8c2518bf4c4237366221e69bb979d2959d5ae8b60": [{
+            name: "merge-stage-report",
+            id: "dd-flow/stage-report@1",
+            path: "dist/schemas/stage-report.schema.json",
+            checksum: "d9889af7f2c0afb47e2abab330aea3e1750879d0738d87d38d2d20e3fe0403f3"
+        }]
+};
+function resolveRunBoundSchema(options) {
+    if (!options.projectRoot || options.schemaDir)
+        return null;
+    const data = readJson(path.resolve(options.file), "input file");
+    const root = asRecord(data);
+    const run = root ? asRecord(objectValue(root, "run")) : undefined;
+    const runId = run ? objectValue(run, "run_id") : objectValue(root ?? {}, "run_id");
+    if (typeof runId !== "string")
+        return null;
+    const projectRoot = path.resolve(options.projectRoot);
+    const located = findRunHome(options.ddFlowHome ?? process.env.DD_FLOW_HOME ?? path.join(path.dirname(projectRoot), ".dd-flow"), projectRoot, runId);
+    if (!located || !isInside(located.run_home, path.resolve(options.file)))
+        return null;
+    const binding = readRunEngineBinding(located.binding_path, { allowMissing: true });
+    if (!binding)
+        return null;
+    const manifestPath = path.join(binding.engine.snapshot_root, "engine.json");
+    const manifest = readJson(manifestPath, "bound engine manifest");
+    const integrity = asRecord(objectValue(manifest, "integrity"));
+    if (manifest.package_version !== binding.engine.package_version || manifest.engine_version !== binding.engine.engine_version || integrity?.checksum !== binding.engine.integrity_checksum) {
+        throw new AppError("run_engine_binding_invalid", "RUN engine binding does not match its engine manifest", 1, { binding: binding.engine, manifest: manifestPath });
+    }
+    const registry = asRecord(objectValue(manifest, "schema_registry"));
+    const entries = Array.isArray(registry?.entries) ? registry.entries.filter((entry) => Boolean(asRecord(entry))) : [];
+    const registered = entries.map(asSchemaRegistryEntry).find((entry) => entry?.name === options.schemaName);
+    const historical = !registered ? historicalSchemaRegistry[binding.engine.integrity_checksum]?.find((entry) => entry.name === options.schemaName) : undefined;
+    const profile = registered ?? historical;
+    if (registry && !registered) {
+        throw new AppError("schema_not_found", `Schema not registered for RUN-bound engine: ${options.schemaName}`, 2, { run_id: runId, engine: binding.engine });
+    }
+    if (!profile) {
+        throw new AppError("schema_not_found", `Schema not found for RUN-bound engine: ${options.schemaName}`, 2, { run_id: runId, engine: binding.engine });
+    }
+    const relativePath = profile.path;
+    const schemaPath = historical
+        ? path.join(bundledSchemaDir(), path.basename(relativePath))
+        : resolveInside(binding.engine.snapshot_root, relativePath);
+    if (!schemaPath || !fs.existsSync(schemaPath)) {
+        throw new AppError("schema_not_found", `Schema not found for RUN-bound engine: ${options.schemaName}`, 2, { run_id: runId, engine: binding.engine, path: relativePath });
+    }
+    if (checksum(schemaPath) !== profile.checksum) {
+        throw new AppError("schema_registry_invalid", "RUN-bound engine schema does not match its registry checksum", 1, { run_id: runId, schema: options.schemaName, path: schemaPath });
+    }
+    const schema = readJson(schemaPath, "schema");
+    const id = objectValue(asRecord(schema) ?? {}, "$id");
+    if (id !== profile.id) {
+        throw new AppError("schema_registry_invalid", "RUN-bound engine schema does not match its registry id", 1, { run_id: runId, schema: options.schemaName, path: schemaPath });
+    }
+    return {
+        name: options.schemaName,
+        id: typeof id === "string" ? id : options.schemaName,
+        path: schemaPath,
+        source: historical ? "engine_legacy_registry" : "run_bound_engine",
+        engine: { package_version: binding.engine.package_version, engine_version: binding.engine.engine_version, integrity_checksum: binding.engine.integrity_checksum, snapshot_root: binding.engine.snapshot_root }
+    };
+}
+function asSchemaRegistryEntry(value) {
+    const name = objectValue(value, "name");
+    const id = objectValue(value, "id");
+    const schemaPath = objectValue(value, "path");
+    const entryChecksum = objectValue(value, "checksum");
+    return typeof name === "string" && typeof id === "string" && typeof schemaPath === "string" && typeof entryChecksum === "string"
+        ? { name, id, path: schemaPath, checksum: entryChecksum }
+        : null;
+}
+function resolveInside(root, relativePath) {
+    if (path.isAbsolute(relativePath))
+        return null;
+    const candidate = path.resolve(root, relativePath);
+    return isInside(root, candidate) ? candidate : null;
+}
+function isInside(root, candidate) {
+    const relative = path.relative(path.resolve(root), path.resolve(candidate));
+    return relative === "" || (!relative.startsWith("..") && !path.isAbsolute(relative));
+}
+function checksum(file) {
+    return crypto.createHash("sha256").update(fs.readFileSync(file)).digest("hex");
+}
 function bundledSchemaDir() {
     return path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..", "schemas");
 }