@deksden-com/dd-flow-cli 0.9.0-beta.9 → 0.9.0-beta.90

package/dist/services/runtime-scope-stop.js

@@ -0,0 +1,99 @@
+import crypto from "node:crypto";
+import fs from "node:fs";
+import path from "node:path";
+import { AppError } from "../shared/errors.js";
+import { runHarnessAdapter } from "./harness-adapter.js";
+import { managedLeaseReleased, managedProcessBinding, managedProcessStatus, processIsAlive, processTreeIsAlive, resourceHome, stopManagedProcess } from "./managed-processes.js";
+import { fenceRuntimeBudget, runtimeBudgetStatus, scopeLocalProcessRole } from "./runtime-budget.js";
+import { retainedDaemonOperations } from "./run-control.js";
+import { historicalDaemonSettlement } from "./native-daemon-history.js";
+import { managedProviderBelongsToDaemon } from "./managed-daemon-binding.js";
+/** Native daemons own cancellation after the observing CLI disconnects. */
+export async function stopRuntimeScope(context, scopeId, requestId) {
+    const fence = fenceRuntimeBudget(context, scopeId, requestId);
+    const inventory = runtimeBudgetStatus(context, scopeId).processes;
+    const nodes = await Promise.all(inventory.filter(record => record.kind.endsWith("-daemon")).map(async (record) => {
+        try {
+            const historical = historicalDaemonSettlement(context, scopeId, record);
+            if (historical)
+                return historical;
+            const metadata = JSON.parse(record.metadata_json);
+            if (!metadata.state_dir || !path.isAbsolute(metadata.state_dir) || !metadata.adapter_executable || !path.isAbsolute(metadata.adapter_executable))
+                throw new AppError("runtime_scope_owner_unknown", "Native stop requires its retained directory and executable", 1);
+            const file = path.join(metadata.state_dir, "daemon.json");
+            const read = () => JSON.parse(fs.readFileSync(file, "utf8"));
+            const state = read();
+            const owner = state.config?.runtime_owner;
+            if (!state.daemon_id || !owner || owner.budget?.scope_id !== scopeId || owner.owner_id !== record.owner_id || owner.role !== metadata.role || owner.state_dir !== metadata.state_dir || owner.adapter_executable !== metadata.adapter_executable || owner.resource_home !== resourceHome(context) || (owner.project_id ?? null) !== record.project_id || (owner.run_id ?? null) !== record.run_id || (owner.work_id ?? null) !== record.work_id || !record.operation_id?.startsWith(`${owner.operation_id}:`) || state.resource_process?.id !== record.id || state.resource_process.lease_token !== record.lease_token || state.pid !== record.pid)
+                throw new AppError("runtime_scope_owner_unknown", "Native owner does not match its registration", 1);
+            const closed = state.shutdown_state === "clean" && state.active_tree === false && !processTreeIsAlive(record)
+                ? retainedDaemonOperations(metadata.state_dir).find(operation => operation.daemon_id === state.daemon_id && operation.operation === "daemon.stop" && operation.state === "completed" && operation.result?.stopped === true && operation.result?.clean === true) : undefined;
+            const operationId = closed ? String(closed.operation_id) : `scope-stop:${crypto.createHash("sha256").update(JSON.stringify([scopeId, record.id, state.daemon_id])).digest("hex")}`;
+            const requested = path.join(metadata.state_dir, "operations", crypto.createHash("sha256").update(operationId).digest("hex"), "requested.json");
+            const prior = fs.existsSync(requested);
+            const current = managedProcessStatus(context).find(item => item.id === record.id);
+            if (!current || current.lease_token !== record.lease_token || current.pid !== record.pid || current.pid_started_at !== record.pid_started_at)
+                throw new AppError("runtime_scope_owner_changed", "Native registration changed before control", 1);
+            if (!prior && !processIsAlive(current))
+                throw new AppError("runtime_scope_outcome_unknown", "Dead native owner requires retained shutdown evidence", 1);
+            const env = { ...context.env, DD_FLOW_HOME: owner.dd_flow_home, DD_FLOW_BIN: owner.dd_flow_bin, DD_FLOW_RESOURCE_HOME: owner.resource_home };
+            delete env.DD_FLOW_CONTROL_TOKEN;
+            delete env.DD_FLOW_CONTROLLER_TOKEN;
+            const receipt = await runHarnessAdapter({ executable: metadata.adapter_executable,
+                args: prior ? ["daemon", "operation", "--operation-id", operationId, "--state-dir", metadata.state_dir, "--json"] : ["daemon", "stop", "--cancel-tree", "--state-dir", metadata.state_dir, "--json"],
+                env, operationId: prior ? `${operationId}:observe` : operationId, timeoutMs: 30_000 });
+            if (prior && (receipt.operation_id !== operationId || receipt.daemon_id !== state.daemon_id || receipt.operation !== "daemon.stop" || receipt.state !== "completed"))
+                throw new AppError("runtime_scope_outcome_unknown", "Native close operation has not completed", 1);
+            const result = (prior ? receipt.result : receipt);
+            const after = read();
+            const finalOwner = managedProcessStatus(context).find(item => item.id === record.id);
+            if (!finalOwner || finalOwner.lease_token !== record.lease_token || finalOwner.pid !== record.pid || finalOwner.pid_started_at !== record.pid_started_at || after.resource_process?.id !== record.id || after.resource_process.lease_token !== record.lease_token || JSON.stringify(after.config?.runtime_owner) !== JSON.stringify(owner))
+                throw new AppError("runtime_scope_owner_changed", "Native ownership changed during control", 1);
+            if (result?.stopped !== true || result.clean !== true || after.daemon_id !== state.daemon_id || after.shutdown_state !== "clean" || after.active_tree !== false || processTreeIsAlive(finalOwner))
+                throw new AppError("runtime_scope_not_settled", "Native close has not proved whole-tree settlement", 1);
+            const processes = managedProcessStatus(context).filter(item => managedProviderBelongsToDaemon(item, finalOwner, after) && item.operation_id?.startsWith(`${owner.operation_id}:`) && !processTreeIsAlive(item)).map(item => ({ process_id: item.id, native_settled: true, binding: managedProcessBinding(item, resourceHome(context)) }));
+            return { process_id: record.id, state_dir: metadata.state_dir, settled: true, operation_id: operationId, owner_operation_id: owner.operation_id, processes };
+        }
+        catch (error) {
+            return { process_id: record.id, settled: false, reason: error instanceof AppError ? error.code : "runtime_scope_control_failed", message: String(error) };
+        }
+    }));
+    const covered = new Set(nodes.map(node => node.process_id));
+    for (const record of runtimeBudgetStatus(context, scopeId).processes) {
+        if (covered.has(record.id))
+            continue;
+        if (managedLeaseReleased(record)) {
+            nodes.push({ process_id: record.id, settled: true });
+            continue;
+        }
+        const metadata = JSON.parse(record.metadata_json);
+        // RUN control owns active controllers/checks. Adopt only its already-finished
+        // physical registrations here; death alone is not a completed RUN operation.
+        if ((record.kind === "run-controller" && metadata.role === "controller" && record.operation_id
+            || record.kind === "check" && metadata.role === "check" && record.check_id)
+            && record.project_id && record.run_id && ["stopped", "failed"].includes(record.state)
+            && record.pid && record.pid_started_at && !processTreeIsAlive(record)) {
+            const operationId = record.operation_id ?? record.check_id;
+            nodes.push({ process_id: record.id, state_dir: metadata.state_dir ?? "", settled: true, operation_id: operationId, owner_operation_id: operationId });
+            continue;
+        }
+        if (scopeLocalProcessRole(record) && record.operation_id && record.pid && record.pid_started_at) {
+            try {
+                await stopManagedProcess(context, { id: record.id, leaseToken: record.lease_token, force: false, graceMs: 500, reason: `scope-stop:${scopeId}` });
+                nodes.push({ process_id: record.id, state_dir: "", settled: true, operation_id: record.operation_id, owner_operation_id: record.operation_id });
+            }
+            catch (error) {
+                nodes.push({ process_id: record.id, settled: false, reason: "runtime_scope_resource_unsettled", message: String(error) });
+            }
+            continue;
+        }
+        const binding = JSON.stringify(managedProcessBinding(record, resourceHome(context)));
+        const parent = nodes.find(node => node.settled && node.state_dir === metadata.state_dir && "processes" in node && node.processes?.some(item => item.process_id === record.id && item.native_settled && JSON.stringify(item.binding) === binding));
+        if (parent && !processTreeIsAlive(record)) {
+            nodes.push({ process_id: record.id, state_dir: metadata.state_dir, settled: true, operation_id: parent.operation_id, owner_operation_id: parent.owner_operation_id });
+        }
+        else
+            nodes.push({ process_id: record.id, settled: false, reason: "runtime_scope_resource_unsettled", message: "Resource needs its own settlement proof" });
+    }
+    return { scope_id: scopeId, fence, settled: nodes.every(node => node.settled), nodes };
+}

package/dist/services/runtime-scope-worker.js

@@ -0,0 +1,243 @@
+import crypto from "node:crypto";
+import fs from "node:fs";
+import path from "node:path";
+import { spawn } from "node:child_process";
+import { fileURLToPath } from "node:url";
+import { setTimeout as delay } from "node:timers/promises";
+import { AppError } from "../shared/errors.js";
+import { getResourceDatabase } from "../storage/database.js";
+import { confirmManagedProcess, finishManagedProcess, heartbeatManagedProcess, processIsAlive, processStartedAt, registerManagedProcess, resourceHome } from "./managed-processes.js";
+import { publicRuntimeScopeWorker, requestRuntimeScopeControl, runtimeBudgetStatus, prepareRuntimeScopeFence, parseRuntimeBudget } from "./runtime-budget.js";
+import { controlRuntimeScopeRuns } from "./runtime-scope-control.js";
+import { prepareRuntimeScopeResume, recordRuntimeScopeResume } from "./runtime-scope-resume.js";
+import { recoveryObservationBudget, renewRecoveryObservation, withRecoveryObservation } from "./recovery-observation-budget.js";
+export async function launchRuntimeScopeResume(context, input) {
+    const resume = recordRuntimeScopeResume(context, input);
+    if (!resume.current)
+        return { scope_id: input.scopeId, resume, current: false, settled: false };
+    if (resume.status === "released")
+        return { scope_id: input.scopeId, resume, release: resume.release, current: true, dispatch_blocked: resume.dispatch_blocked, settled: false };
+    const control = runtimeBudgetStatus(context, input.scopeId).control;
+    if (control?.generation !== input.generation)
+        throw new AppError("runtime_scope_control_superseded", "Scope resume source changed before owner launch", 1);
+    const owner = await launchRuntimeScopeControl(context, input.scopeId, control.request_id, control.requested_mode, undefined, undefined, input.requestId);
+    return { ...owner, resume, dispatch_blocked: true, settled: false };
+}
+const keyFor = (scope, generation) => crypto.createHash("sha256").update(JSON.stringify([scope, generation])).digest("hex");
+function birth() {
+    const started = processStartedAt(process.pid);
+    if (!started)
+        throw new AppError("runtime_scope_owner_unknown", "Scope owner birth identity is unavailable", 1);
+    return { pid: process.pid, pid_started_at: started };
+}
+export function prepareRuntimeScopeReconciliation(context, scopeId, generation, requestId) {
+    prepareRuntimeScopeFence(scopeId, requestId);
+    if (!Number.isSafeInteger(generation) || generation < 1)
+        throw new AppError("validation", "Scope reconciliation requires a positive integer generation", 2);
+    renewRecoveryObservation({}, requestId);
+    const db = getResourceDatabase(resourceHome(context), "read_existing");
+    try {
+        const row = db.get("SELECT metadata_json FROM managed_resources WHERE resource_kind = 'scope-control' AND resource_key = ?", [scopeId]);
+        const control = row ? JSON.parse(row.metadata_json) : null;
+        if (!control || control.generation !== generation)
+            throw new AppError("runtime_scope_control_superseded", "Reconciliation requires the current controlled scope generation", 1);
+        return control;
+    }
+    finally {
+        db.close?.();
+    }
+}
+export async function reconcileRuntimeScopeControl(context, scopeId, generation, requestId) {
+    const control = prepareRuntimeScopeReconciliation(context, scopeId, generation, requestId);
+    return launchRuntimeScopeControl(context, scopeId, control.request_id, control.requested_mode, undefined, requestId);
+}
+export async function launchRuntimeScopeControl(context, scopeId, requestId, mode, manifest, reconcileId, resumeId, prepared) {
+    const control = requestRuntimeScopeControl(context, scopeId, requestId, mode, manifest, prepared), db = getResourceDatabase(resourceHome(context)), key = keyFor(scopeId, control.generation);
+    let worker;
+    db.beginWriteTransaction();
+    try {
+        const current = db.get("SELECT metadata_json FROM managed_resources WHERE resource_kind = 'scope-control' AND resource_key = ?", [scopeId]);
+        const prior = db.get("SELECT metadata_json FROM managed_resources WHERE resource_kind = 'scope-control-worker' AND resource_key = ?", [key]);
+        const existing = prior ? JSON.parse(prior.metadata_json) : null;
+        if (existing) {
+            const identity = existing.owner ?? existing.launcher;
+            if (!identity || !Number.isSafeInteger(identity.pid) || identity.pid < 1 || typeof identity.pid_started_at !== "string" || !identity.pid_started_at || !["starting", "running", "completed", "failed", "superseded"].includes(existing.status))
+                throw new AppError("runtime_scope_owner_unknown", "Retained scope owner has no verifiable birth identity", 1);
+        }
+        if (!current || JSON.parse(current.metadata_json).generation !== control.generation || db.get("SELECT 1 FROM managed_resources WHERE resource_kind = 'provider-fence' AND resource_key = ?", [scopeId])) {
+            db.exec("COMMIT");
+            return { scope_id: scopeId, control, current: false, settled: false, worker: existing ? publicRuntimeScopeWorker(existing) : null };
+        }
+        if (existing && (existing.owner ? processIsAlive(existing.owner) : existing.status !== "failed" && processIsAlive(existing.launcher))) {
+            db.exec("COMMIT");
+            return { scope_id: scopeId, control, current: true, settled: false, worker: publicRuntimeScopeWorker(existing) };
+        }
+        if (existing?.status === "completed" && !reconcileId && !resumeId) {
+            db.exec("COMMIT");
+            return { scope_id: scopeId, control, current: true, settled: false, worker: publicRuntimeScopeWorker(existing) };
+        }
+        const renewal = resumeId ? `resume:${resumeId}` : reconcileId;
+        const snapshot = renewal ? renewRecoveryObservation(existing?.snapshot ?? {}, renewal) : existing?.snapshot;
+        if (existing && recoveryObservationBudget(snapshot).state().remaining_ms === 0) {
+            db.exec("COMMIT");
+            return { scope_id: scopeId, control, current: true, settled: false, worker: publicRuntimeScopeWorker(existing) };
+        }
+        const cleanupRequest = resumeId ? undefined : reconcileId ?? existing?.reconcile_id;
+        worker = { scope_id: scopeId, generation: control.generation, request_id: requestId, mode, token: crypto.randomUUID(), status: "starting", launcher: birth(), ...(snapshot ? { snapshot } : {}), ...(cleanupRequest ? { reconcile_id: cleanupRequest } : {}) };
+        const now = context.now();
+        db.run("INSERT INTO managed_resources (resource_kind,resource_key,owner_id,lease_token,lease_expires_at,process_id,metadata_json,created_at,updated_at) VALUES ('scope-control-worker',?,?,?,?,NULL,?,?,?) ON CONFLICT(resource_kind,resource_key) DO UPDATE SET lease_token = excluded.lease_token, metadata_json = excluded.metadata_json, updated_at = excluded.updated_at", [key, scopeId, worker.token, now, JSON.stringify(worker), now, now]);
+        db.exec("COMMIT");
+    }
+    catch (error) {
+        db.exec("ROLLBACK");
+        throw error;
+    }
+    try {
+        const entry = fileURLToPath(new URL("../cli.js", import.meta.url));
+        if (!fs.existsSync(entry))
+            throw new AppError("harness_runtime_unbuilt", "Build the CLI before launching scope control", 1);
+        const directory = path.join(resourceHome(context), "scope-controls", key);
+        fs.mkdirSync(directory, { recursive: true, mode: 0o700 });
+        const log = fs.openSync(path.join(directory, "control.log"), "a", 0o600);
+        try {
+            const env = { ...context.env, DD_FLOW_HOME: context.ddFlowHome, DD_FLOW_RESOURCE_HOME: resourceHome(context), DD_FLOW_ENGINE_MODE: "1", DD_FLOW_SCOPE_CONTROL_TOKEN: worker.token };
+            delete env.DD_FLOW_CONTROL_TOKEN;
+            delete env.DD_FLOW_CONTROLLER_TOKEN;
+            const child = spawn(process.execPath, [entry, "runtime", "scope", "serve", "--scope-id", scopeId, "--generation", String(control.generation), "--json"], { env, detached: true, stdio: ["ignore", log, log] });
+            await new Promise((resolve, reject) => { child.once("spawn", resolve); child.once("error", reject); });
+            child.unref();
+        }
+        finally {
+            fs.closeSync(log);
+        }
+    }
+    catch (error) {
+        db.run("UPDATE managed_resources SET metadata_json = json_set(metadata_json, '$.status', 'failed', '$.error', ?), updated_at = ? WHERE resource_kind = 'scope-control-worker' AND resource_key = ? AND lease_token = ? AND json_extract(metadata_json, '$.owner') IS NULL", [String(error), context.now(), key, worker.token]);
+    }
+    const retained = db.get("SELECT metadata_json FROM managed_resources WHERE resource_kind = 'scope-control-worker' AND resource_key = ?", [key]);
+    return { scope_id: scopeId, control, current: true, settled: false, worker: publicRuntimeScopeWorker(JSON.parse(retained.metadata_json)) };
+}
+export function prepareRuntimeScopeServing(context, scopeId, generation) {
+    parseRuntimeBudget(JSON.stringify({ schema_id: "dd-flow/runtime-budget@1", scope_id: scopeId, per_harness: {} }));
+    if (!Number.isSafeInteger(generation) || generation < 1)
+        throw new AppError("validation", "Scope worker requires a positive integer generation", 2);
+    const token = context.env.DD_FLOW_SCOPE_CONTROL_TOKEN;
+    if (!token)
+        throw new AppError("runtime_scope_owner_unknown", "Scope worker requires its launch token", 1);
+    const key = keyFor(scopeId, generation), db = getResourceDatabase(resourceHome(context), "read_existing");
+    try {
+        requireStartingScopeWorker(db, key, token);
+    }
+    finally {
+        db.close?.();
+    }
+    return { key, token };
+}
+function requireStartingScopeWorker(db, key, token) {
+    const row = db.get("SELECT metadata_json FROM managed_resources WHERE resource_kind = 'scope-control-worker' AND resource_key = ? AND lease_token = ?", [key, token]);
+    if (!row)
+        throw new AppError("runtime_scope_owner_unknown", "Scope worker claim changed", 1);
+    const worker = JSON.parse(row.metadata_json);
+    if (worker.owner || worker.status !== "starting")
+        throw new AppError("runtime_scope_already_owned", "Scope control already has a physical owner", 1);
+    return worker;
+}
+export async function serveRuntimeScopeControl(context, scopeId, generation) {
+    const { key, token } = prepareRuntimeScopeServing(context, scopeId, generation);
+    const db = getResourceDatabase(resourceHome(context));
+    let worker;
+    db.beginWriteTransaction();
+    try {
+        worker = requireStartingScopeWorker(db, key, token);
+        worker.owner = birth();
+        worker.status = "running";
+        db.run("UPDATE managed_resources SET metadata_json = ?, updated_at = ? WHERE resource_kind = 'scope-control-worker' AND resource_key = ? AND lease_token = ?", [JSON.stringify(worker), context.now(), key, token]);
+        db.exec("COMMIT");
+    }
+    catch (error) {
+        db.exec("ROLLBACK");
+        throw error;
+    }
+    let heartbeat;
+    // A fence must never be held indefinitely by an observer that cannot obtain
+    // fresh provider evidence. A later operator request continues the retained
+    // budget; this owner records why it stopped without claiming settlement.
+    const observation = recoveryObservationBudget(worker.snapshot);
+    try {
+        const record = registerManagedProcess(context, { kind: "scope-control", ownerId: key, operationId: `scope-control:${key}:${token}`, ownerPid: process.pid, metadata: { role: "control", scope_id: scopeId, generation } });
+        worker.process_id = record.id;
+        worker.process_lease_token = record.lease_token;
+        confirmManagedProcess(context, { id: record.id, leaseToken: record.lease_token, pid: process.pid, processGroupId: process.pid, ownerPid: process.pid });
+        db.run("UPDATE managed_resources SET metadata_json = ?, updated_at = ? WHERE resource_kind = 'scope-control-worker' AND resource_key = ? AND lease_token = ?", [JSON.stringify(worker), context.now(), key, token]);
+        let leaseLost = false;
+        heartbeat = setInterval(() => { try {
+            if (!heartbeatManagedProcess(context, { id: record.id, leaseToken: record.lease_token }))
+                leaseLost = true;
+        }
+        catch {
+            leaseLost = true;
+        } }, 10_000);
+        heartbeat.unref();
+        for (;;) {
+            if (leaseLost)
+                throw new AppError("runtime_scope_owner_changed", "Scope worker lost its managed lease", 1);
+            if (observation.exhausted()) {
+                worker.status = "failed";
+                worker.error = "recovery_observation_budget_exhausted";
+                worker.snapshot = {
+                    ...(worker.snapshot ?? {}),
+                    status: "recovery_blocked",
+                    settled: false,
+                    pending_reasons: ["recovery_observation_budget_exhausted"],
+                    error: { code: "recovery_observation_budget_exhausted", message: "Scope recovery observation exceeded its 120 second budget" },
+                    recovery_observation: observation.state(),
+                };
+                return { scope_id: scopeId, generation, status: "recovery_blocked", settled: false, error: worker.error };
+            }
+            const status = runtimeBudgetStatus(context, scopeId);
+            const release = status.release;
+            if (release?.current === true && release.generation === generation) {
+                worker.status = "completed";
+                worker.snapshot = release;
+                break;
+            }
+            if (status.control?.generation !== generation || status.fence) {
+                worker.status = "superseded";
+                break;
+            }
+            const resume = status.resume;
+            const outcome = await withRecoveryObservation(observation, async () => (worker.reconcile_id ? null : await prepareRuntimeScopeResume(context, scopeId, generation, resume?.generation === generation ? resume.request_id : undefined))
+                ?? await controlRuntimeScopeRuns(context, scopeId, worker.request_id, worker.mode, worker.reconcile_id));
+            observation.exhausted();
+            worker.snapshot = { ...outcome, recovery_observation: observation.state() };
+            db.run("UPDATE managed_resources SET metadata_json = ?, updated_at = ? WHERE resource_kind = 'scope-control-worker' AND resource_key = ? AND lease_token = ?", [JSON.stringify(worker), context.now(), key, token]);
+            if (worker.snapshot.drain?.physical_settled === true) {
+                worker.status = "completed";
+                break;
+            }
+            await delay(observation.nextDelay());
+        }
+        return { scope_id: scopeId, generation, status: worker.status };
+    }
+    catch (error) {
+        if (error instanceof AppError && error.code === "runtime_scope_control_superseded") {
+            const release = runtimeBudgetStatus(context, scopeId).release;
+            worker.status = release?.current === true && release.generation === generation ? "completed" : "superseded";
+            if (worker.status === "completed")
+                worker.snapshot = release;
+            return { scope_id: scopeId, generation, status: worker.status };
+        }
+        worker.status = "failed";
+        worker.error = String(error);
+        throw error;
+    }
+    finally {
+        if (heartbeat)
+            clearInterval(heartbeat);
+        observation.exhausted();
+        worker.snapshot = { ...(worker.snapshot ?? {}), recovery_observation: observation.state() };
+        db.run("UPDATE managed_resources SET metadata_json = ?, updated_at = ? WHERE resource_kind = 'scope-control-worker' AND resource_key = ? AND lease_token = ?", [JSON.stringify(worker), context.now(), key, token]);
+        if (worker.process_id && worker.process_lease_token)
+            finishManagedProcess(context, { id: worker.process_id, leaseToken: worker.process_lease_token, state: worker.status === "failed" ? "failed" : "stopped", reason: "scope_owner_exited" });
+    }
+}

package/dist/services/runtime-service.js

@@ -0,0 +1,97 @@
+import fs from "node:fs";
+import crypto from "node:crypto";
+import path from "node:path";
+import { AppError } from "../shared/errors.js";
+import { assertRunMutationAllowed } from "./run-recovery.js";
+import { requireProjectByRoot } from "./projects.js";
+import { resolveRun } from "./runs.js";
+import { codeExecutionEnvironment, runCheck } from "./code-checks.js";
+import { confirmManagedProcess, finishManagedProcess, heartbeatManagedProcess, managedProcessStatus, processTreeIsAlive, registerManagedProcess, reservePorts, resourceHome, stopManagedProcess } from "./managed-processes.js";
+export function prepareRuntimeService(context, input) {
+    if (!Number.isFinite(input.timeoutMs) || input.timeoutMs <= 0)
+        throw new AppError("validation", "Readiness timeout must be positive and finite", 2);
+    if (typeof input.command !== "string" || !input.command.trim() || !Array.isArray(input.ports) || !input.ports.length || input.ports.some(name => typeof name !== "string" || !/^[a-z][a-z0-9_]*$/.test(name)) || new Set(input.ports).size !== input.ports.length || !input.ports.includes(input.readyPort) || typeof input.readyPath !== "string" || !input.readyPath.startsWith("/") || input.readyPath.startsWith("//"))
+        throw new AppError("validation", "Declare unique lowercase port names, a ready-port from that list and a local /ready-path", 2);
+    const project = requireProjectByRoot(context, path.resolve(input.projectRoot));
+    const run = resolveRun(context, project.id, input.runId);
+    if (!run?.run_root || !run.workspace_root)
+        throw new AppError("not_found", "Registered RUN with a materialized workspace is required", 2);
+    const generation = assertRunMutationAllowed(context, project.id, run.id);
+    return { project, run, runHome: run.run_root, generation };
+}
+export async function startRuntimeService(context, input) {
+    const { project, run, runHome, generation } = prepareRuntimeService(context, input);
+    input = { ...input, runId: run.id };
+    const id = `PROC-${crypto.randomUUID()}`;
+    const directory = path.join(runHome, "runtime", id);
+    fs.mkdirSync(directory, { recursive: true });
+    const record = registerManagedProcess(context, { id, kind: "runtime-service", ownerId: `run:${input.runId}`, ownerPid: process.pid, runId: input.runId, projectId: project.id, stdoutPath: path.join(directory, "stdout.log"), stderrPath: path.join(directory, "stderr.log"), metadata: { command: input.command } });
+    const receiptPath = path.join(directory, "service.json");
+    let stdout, stderr;
+    let settled = false, ready = false;
+    const receipt = { schema_id: "dd-flow/runtime-service@1", process_id: record.id, run_id: input.runId, status: "starting", started_at: context.now(), receipt_path: receiptPath, stdout_path: path.join(directory, "stdout.log"), stderr_path: path.join(directory, "stderr.log") };
+    const save = () => { const temporary = `${receiptPath}.${process.pid}.tmp`; fs.writeFileSync(temporary, JSON.stringify(receipt, null, 2)); fs.renameSync(temporary, receiptPath); };
+    try {
+        const allocation = await reservePorts(context, { ownerId: record.owner_id, processId: record.id, names: input.ports });
+        const environment = { ...codeExecutionEnvironment(run.workspace_root), ...Object.fromEntries(Object.entries(allocation.ports).map(([name, port]) => [`DD_FLOW_PORT_${name.toUpperCase()}`, String(port)])), DD_FLOW_EVIDENCE_DIR: directory, DD_FLOW_CHECK_COMPLETION_FILE: path.join(directory, "completion.json") };
+        const quoted = (value) => `'${value.replaceAll("'", "'\\''")}'`;
+        Object.assign(receipt, { ports: allocation.ports, environment: Object.fromEntries(Object.entries(environment).filter(([key]) => key.startsWith("DD_FLOW_PORT_"))), stop_command: `DD_FLOW_HOME=${quoted(context.ddFlowHome)} DD_FLOW_RESOURCE_HOME=${quoted(resourceHome(context))} dd-flow runtime process stop --id ${record.id} --lease-token ${record.lease_token} --json` });
+        save();
+        input.progress?.(`service ${record.id} preparing; receipt: ${receiptPath}`);
+        assertRunMutationAllowed(context, project.id, run.id, generation);
+        stdout = fs.openSync(String(receipt.stdout_path), "a");
+        stderr = fs.openSync(String(receipt.stderr_path), "a");
+        const running = runCheck(input.command, run.workspace_root, environment, stdout, stderr, elapsed => input.progress?.(`service ${record.id} alive (${elapsed}s); receipt: ${receiptPath}`), pid => confirmManagedProcess(context, { id: record.id, leaseToken: record.lease_token, pid, processGroupId: process.platform === "win32" ? null : pid }), () => heartbeatManagedProcess(context, { id: record.id, leaseToken: record.lease_token }));
+        void running.then(() => { settled = true; });
+        const deadline = performance.now() + input.timeoutMs;
+        while (!settled && performance.now() < deadline) {
+            try {
+                const response = await fetch(`http://127.0.0.1:${allocation.ports[input.readyPort]}${input.readyPath}`, { signal: AbortSignal.timeout(1_000), redirect: "error" });
+                await response.body?.cancel();
+                ready = response.ok;
+            }
+            catch { /* Startup is observed until the declared deadline. */ }
+            if (ready)
+                break;
+            await new Promise(resolve => setTimeout(resolve, 100));
+        }
+        if (!ready) {
+            await stopManagedProcess(context, { id: record.id, leaseToken: record.lease_token });
+            await running;
+            throw new AppError("service_not_ready", "Service did not pass its declared HTTP readiness check; inspect retained logs", 2, { receipt_path: receiptPath });
+        }
+        Object.assign(receipt, { status: "ready", ready_at: context.now() });
+        save();
+        input.progress?.(`service ready: ${JSON.stringify(receipt)}; keep this supervisor running, use its exact stop command when finished`);
+        const outcome = await running;
+        const current = managedProcessStatus(context).find(item => item.id === record.id);
+        if (current.state === "stopping") {
+            const settleBy = performance.now() + 5_000;
+            while (processTreeIsAlive(current) && performance.now() < settleBy)
+                await new Promise(resolve => setTimeout(resolve, 25));
+        }
+        if (processTreeIsAlive(current))
+            throw new AppError("process_tree_not_settled", "Service still owns live children; retain resources", 2, { process_id: record.id });
+        if (!["stopped", "failed"].includes(current.state))
+            finishManagedProcess(context, { id: record.id, leaseToken: record.lease_token, state: current.state === "stopping" || outcome.exitCode === 0 ? "stopped" : "failed", reason: current.state === "stopping" ? "requested_stop" : outcome.error });
+        Object.assign(receipt, { status: managedProcessStatus(context).find(item => item.id === record.id).state, finished_at: context.now(), exit_code: outcome.exitCode });
+        save();
+        if (receipt.status === "failed")
+            throw new AppError("service_failed", "Service exited unsuccessfully; inspect retained logs", 2, receipt);
+        return receipt;
+    }
+    catch (error) {
+        const current = managedProcessStatus(context).find(item => item.id === record.id);
+        if (!processTreeIsAlive(current))
+            finishManagedProcess(context, { id: record.id, leaseToken: record.lease_token, state: "failed", reason: error instanceof Error ? error.message : String(error) });
+        Object.assign(receipt, { status: "failed", error: error instanceof Error ? error.message : String(error), cleanup_pending: processTreeIsAlive(current) });
+        save();
+        throw error;
+    }
+    finally {
+        if (stdout !== undefined)
+            fs.closeSync(stdout);
+        if (stderr !== undefined)
+            fs.closeSync(stderr);
+    }
+}

package/dist/services/schema-validation.js

@@ -94,8 +94,11 @@ export function validateSchema(options) {
         throw new AppError("usage", "--schema must be a schema name such as mb-upgrade-review-data", 2);
     }
     const filePath = path.resolve(options.file);
-    const data = readJson(filePath, "input file");
-    const schemaResolution = resolveSchema(options);
+    const data = Object.hasOwn(options, "data") ? options.data : readJson(filePath, "input file");
+    // `data` may have come from stdin or from the prepare phase.  Do not reopen
+    // `options.file` merely to infer the RUN-bound schema: apart from being a
+    // second read of caller input, `<stdin>` is not a filesystem path at all.
+    const schemaResolution = resolveSchema(options, data);
     const schema = readJson(schemaResolution.path, "schema");
     // Ajv's default export only carries the draft-07 meta-schema.  New stage
     // contracts may deliberately use draft 2020-12, so choose the validator
@@ -133,8 +136,8 @@ export function validateSchema(options) {
         errors: []
     };
 }
-function resolveSchema(options) {
-    const bound = resolveRunBoundSchema(options);
+function resolveSchema(options, data) {
+    const bound = resolveRunBoundSchema(options, data);
     if (bound)
         return bound;
     const fileNames = [`${options.schemaName}.schema.json`];
@@ -180,10 +183,9 @@ const historicalSchemaRegistry = {
             checksum: "d9889af7f2c0afb47e2abab330aea3e1750879d0738d87d38d2d20e3fe0403f3"
         }]
 };
-function resolveRunBoundSchema(options) {
+function resolveRunBoundSchema(options, data) {
     if (!options.runRoot || 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 inferredRunId = run ? objectValue(run, "run_id") : objectValue(root ?? {}, "run_id");
@@ -268,13 +270,13 @@ function readJson(file, label) {
         text = fs.readFileSync(file, "utf8");
     }
     catch (error) {
-        throw new AppError("validation", `Cannot read ${label}: ${file}`, 2, { cause: String(error) });
+        throw new AppError(label === "input file" ? "validation" : "schema_registry_invalid", `Cannot read ${label}: ${file}`, label === "input file" ? 2 : 1, { cause: String(error) });
     }
     try {
         return JSON.parse(text);
     }
     catch (error) {
-        throw new AppError("invalid_json", `Invalid JSON in ${label}: ${file}`, 2, { cause: String(error) });
+        throw new AppError(label === "input file" ? "invalid_json" : "schema_registry_invalid", `Invalid JSON in ${label}: ${file}`, label === "input file" ? 2 : 1, { cause: String(error) });
     }
 }
 function formatAjvError(error) {