stageflow 0.1.0

package/dist/runstore/disk/DiskRunStore.js

@@ -0,0 +1,238 @@
+import { appendFile, mkdir, readFile, readdir, writeFile } from "node:fs/promises";
+import path from "node:path";
+import { newRunId, runWorkspaceDir, runsDir } from "../paths.js";
+import { agentDir, artifactsDir, attemptAgentDir, attemptArtifactsDir, attemptEnvelopePath, attemptLogPath, envelopePath, stageDir, } from "../workspaceLayout.js";
+import { projectRunDetail, orderStageSnapshots } from "../runProjection.js";
+import { buildStageSnapshotFromStore } from "../stageSnapshot.js";
+import { buildRunSummaryFromDisk, fileExists, listStageIdsFromDisk, readRunMetaFromDisk, readStageLogFromDisk, taskIdFromCopy, } from "./catalogHelpers.js";
+const ensuredStageDirs = new Set();
+const EXECUTIONS_FILE = "executions.json";
+async function readStageLogFile(file) {
+    if (!(await fileExists(file)))
+        return [];
+    const text = await readFile(file, "utf8");
+    return text
+        .split("\n")
+        .map((line) => line.trim())
+        .filter(Boolean)
+        .map((line) => JSON.parse(line));
+}
+async function readExecutionsFromDisk(workspaceDir, stageId) {
+    const file = path.join(workspaceDir, "stages", stageId, EXECUTIONS_FILE);
+    if (!(await fileExists(file)))
+        return [];
+    const parsed = JSON.parse(await readFile(file, "utf8"));
+    return [...parsed].sort((a, b) => a.attempt - b.attempt);
+}
+async function writeExecutionsToDisk(workspaceDir, stageId, executions) {
+    const file = path.join(workspaceDir, "stages", stageId, EXECUTIONS_FILE);
+    await mkdir(path.dirname(file), { recursive: true });
+    const sorted = [...executions].sort((a, b) => a.attempt - b.attempt);
+    await writeFile(file, `${JSON.stringify(sorted, null, 2)}\n`);
+}
+export class DiskRunStore {
+    storeRoot;
+    constructor(storeRoot) {
+        this.storeRoot = storeRoot;
+    }
+    getWorkspaceDir(runId) {
+        return runWorkspaceDir(this.storeRoot, runId);
+    }
+    async createRun(input) {
+        const runId = newRunId();
+        const workspaceDir = this.getWorkspaceDir(runId);
+        await mkdir(workspaceDir, { recursive: true });
+        const now = new Date().toISOString();
+        const meta = {
+            run_id: runId,
+            pipeline_id: input.pipelineId,
+            created_at: now,
+            status: "running",
+            task_id: input.taskId,
+            updated_at: now,
+            ...(input.checkoutRoot !== undefined
+                ? { checkout_root: input.checkoutRoot }
+                : {}),
+            ...(input.pipelineDag ? { pipeline_dag: input.pipelineDag } : {}),
+        };
+        await Promise.all([
+            writeFile(path.join(workspaceDir, "meta.json"), `${JSON.stringify(meta, null, 2)}\n`),
+            writeFile(path.join(workspaceDir, "task.copy.yaml"), input.taskYaml),
+        ]);
+        return { runId, workspaceDir };
+    }
+    async updateRunStatus(runId, status) {
+        const workspaceDir = this.getWorkspaceDir(runId);
+        const meta = await readRunMetaFromDisk(workspaceDir);
+        meta.status = status;
+        meta.updated_at = new Date().toISOString();
+        await writeFile(path.join(workspaceDir, "meta.json"), `${JSON.stringify(meta, null, 2)}\n`);
+    }
+    async readRunMeta(runId) {
+        return readRunMetaFromDisk(this.getWorkspaceDir(runId));
+    }
+    async readTaskYaml(runId) {
+        return readFile(path.join(this.getWorkspaceDir(runId), "task.copy.yaml"), "utf8");
+    }
+    async ensureStageWorkspace(runId, stageId) {
+        const workspaceDir = this.getWorkspaceDir(runId);
+        const dir = stageDir(workspaceDir, stageId);
+        if (!ensuredStageDirs.has(dir)) {
+            await mkdir(artifactsDir(workspaceDir, stageId), { recursive: true });
+            await mkdir(agentDir(workspaceDir, stageId), { recursive: true });
+            ensuredStageDirs.add(dir);
+        }
+    }
+    async ensureAttemptWorkspace(runId, stageId, attempt) {
+        const workspaceDir = this.getWorkspaceDir(runId);
+        const key = `${runId}:${stageId}:${attempt}`;
+        if (!ensuredStageDirs.has(key)) {
+            await mkdir(attemptArtifactsDir(workspaceDir, stageId, attempt), {
+                recursive: true,
+            });
+            await mkdir(attemptAgentDir(workspaceDir, stageId, attempt), {
+                recursive: true,
+            });
+            ensuredStageDirs.add(key);
+        }
+        if (attempt === 1) {
+            await this.ensureStageWorkspace(runId, stageId);
+        }
+    }
+    async createStageExecution(runId, stageId) {
+        const workspaceDir = this.getWorkspaceDir(runId);
+        await this.ensureStageWorkspace(runId, stageId);
+        const executions = await readExecutionsFromDisk(workspaceDir, stageId);
+        const attempt = executions.length > 0 ? Math.max(...executions.map((e) => e.attempt)) + 1 : 1;
+        const execution = {
+            run_id: runId,
+            stage_id: stageId,
+            attempt,
+            status: "pending",
+            envelope: null,
+        };
+        executions.push(execution);
+        await writeExecutionsToDisk(workspaceDir, stageId, executions);
+        return execution;
+    }
+    async listStageExecutions(runId, stageId) {
+        return readExecutionsFromDisk(this.getWorkspaceDir(runId), stageId);
+    }
+    async getLatestStageExecution(runId, stageId) {
+        const executions = await this.listStageExecutions(runId, stageId);
+        return executions.length > 0 ? executions[executions.length - 1] : null;
+    }
+    async countStageAttempts(runId, stageId) {
+        const executions = await this.listStageExecutions(runId, stageId);
+        return executions.length;
+    }
+    async getStageExecution(runId, stageId, attempt) {
+        const executions = await this.listStageExecutions(runId, stageId);
+        const found = executions.find((e) => e.attempt === attempt);
+        if (!found) {
+            throw new Error(`Stage execution not found: ${runId}/${stageId} attempt ${attempt}`);
+        }
+        return found;
+    }
+    async updateStageExecution(runId, stageId, attempt, patch) {
+        const workspaceDir = this.getWorkspaceDir(runId);
+        const executions = await readExecutionsFromDisk(workspaceDir, stageId);
+        const index = executions.findIndex((e) => e.attempt === attempt);
+        if (index < 0) {
+            throw new Error(`Stage execution not found: ${runId}/${stageId} attempt ${attempt}`);
+        }
+        const current = executions[index];
+        executions[index] = {
+            ...current,
+            ...(patch.status !== undefined ? { status: patch.status } : {}),
+            ...(patch.started_at !== undefined ? { started_at: patch.started_at } : {}),
+            ...(patch.finished_at !== undefined ? { finished_at: patch.finished_at } : {}),
+            ...(patch.envelope !== undefined ? { envelope: patch.envelope } : {}),
+        };
+        await writeExecutionsToDisk(workspaceDir, stageId, executions);
+    }
+    async writeEnvelope(runId, stageId, envelope, options) {
+        const attempt = options?.attempt ?? 1;
+        await this.ensureStageWorkspace(runId, stageId);
+        if (attempt >= 2) {
+            await this.ensureAttemptWorkspace(runId, stageId, attempt);
+        }
+        const workspaceDir = this.getWorkspaceDir(runId);
+        const file = attempt >= 2
+            ? attemptEnvelopePath(workspaceDir, stageId, attempt)
+            : envelopePath(workspaceDir, stageId);
+        await writeFile(file, `${JSON.stringify(envelope, null, 2)}\n`);
+        try {
+            await this.updateStageExecution(runId, stageId, attempt, { envelope });
+        }
+        catch {
+            // no execution row yet
+        }
+    }
+    async readEnvelope(runId, stageId) {
+        const file = envelopePath(this.getWorkspaceDir(runId), stageId);
+        return JSON.parse(await readFile(file, "utf8"));
+    }
+    async appendStageEvent(runId, stageId, event, options) {
+        const attempt = options?.attempt ?? 1;
+        await this.ensureAttemptWorkspace(runId, stageId, attempt);
+        const file = attemptLogPath(this.getWorkspaceDir(runId), stageId, attempt);
+        const line = `${JSON.stringify({ ...event, at: new Date().toISOString() })}\n`;
+        await appendFile(file, line);
+    }
+    async listStageEvents(runId, stageId, attempt) {
+        const workspaceDir = this.getWorkspaceDir(runId);
+        if (attempt != null) {
+            return readStageLogFile(attemptLogPath(workspaceDir, stageId, attempt));
+        }
+        const events = [];
+        events.push(...(await readStageLogFromDisk(workspaceDir, stageId)));
+        const attemptsDir = path.join(workspaceDir, "stages", stageId, "attempts");
+        if (await fileExists(attemptsDir)) {
+            const entries = await readdir(attemptsDir, { withFileTypes: true });
+            const attemptNums = entries
+                .filter((e) => e.isDirectory())
+                .map((e) => Number.parseInt(e.name, 10))
+                .filter((n) => Number.isFinite(n) && n >= 2)
+                .sort((a, b) => a - b);
+            for (const n of attemptNums) {
+                events.push(...(await readStageLogFile(attemptLogPath(workspaceDir, stageId, n))));
+            }
+        }
+        return events.sort((a, b) => (a.at ?? "").localeCompare(b.at ?? ""));
+    }
+    async listRuns() {
+        const root = runsDir(this.storeRoot);
+        if (!(await fileExists(root)))
+            return [];
+        const entries = await readdir(root, { withFileTypes: true });
+        const summaries = [];
+        for (const entry of entries) {
+            if (!entry.isDirectory())
+                continue;
+            try {
+                summaries.push(await buildRunSummaryFromDisk(path.join(root, entry.name)));
+            }
+            catch {
+                // skip malformed run folders
+            }
+        }
+        summaries.sort((a, b) => b.created_at.localeCompare(a.created_at));
+        return summaries;
+    }
+    async readRun(runId) {
+        const workspaceDir = this.getWorkspaceDir(runId);
+        if (!(await fileExists(path.join(workspaceDir, "meta.json")))) {
+            throw new Error(`Run not found: ${runId}`);
+        }
+        const meta = await readRunMetaFromDisk(workspaceDir);
+        const task_yaml = await readFile(path.join(workspaceDir, "task.copy.yaml"), "utf8");
+        const stageIds = await listStageIdsFromDisk(workspaceDir, meta);
+        const loaded = await Promise.all(stageIds.map((id) => buildStageSnapshotFromStore(this, runId, id, workspaceDir)));
+        const stages = meta.pipeline_dag?.stage_ids?.length
+            ? orderStageSnapshots(meta.pipeline_dag.stage_ids, loaded)
+            : loaded;
+        const task_id = await taskIdFromCopy(workspaceDir, meta);
+        return projectRunDetail({ ...meta, task_id }, stages, task_yaml, meta.pipeline_dag ?? null);
+    }
+}

package/dist/runstore/disk/catalogHelpers.d.ts

@@ -0,0 +1,11 @@
+import { type RunDetail, type RunMeta, type RunSummary, type StageLogEvent, type StageSnapshot } from "../port.js";
+import { listArtifactNames } from "../workspaceLayout.js";
+export { listArtifactNames };
+export declare function fileExists(filePath: string): Promise<boolean>;
+export declare function readStageLogFromDisk(workspaceDir: string, stageId: string): Promise<StageLogEvent[]>;
+export declare function loadStageSnapshotFromDisk(workspaceDir: string, stageId: string, store?: import("../port.js").RunStore, runId?: string): Promise<StageSnapshot>;
+export declare function listStageIdsFromDisk(workspaceDir: string, meta?: RunMeta): Promise<string[]>;
+export declare function taskIdFromCopy(workspaceDir: string, meta: RunMeta): Promise<string | undefined>;
+export declare function readRunMetaFromDisk(workspaceDir: string): Promise<RunMeta>;
+export declare function buildRunSummaryFromDisk(workspaceDir: string): Promise<RunSummary>;
+export declare function buildRunDetailFromDisk(workspaceDir: string): Promise<RunDetail>;

package/dist/runstore/disk/catalogHelpers.js

@@ -0,0 +1,102 @@
+import { readdir, readFile, access } from "node:fs/promises";
+import path from "node:path";
+import { loadTaskFromYaml } from "../../config/loadTask.js";
+import { derivePendingPrompt } from "../../hitl/qaTrail.js";
+import { stageStatusFromEvents, } from "../port.js";
+import { projectRunDetail, projectRunSummary, orderStageSnapshots } from "../runProjection.js";
+import { buildStageSnapshotFromStore } from "../stageSnapshot.js";
+import { envelopePath, listArtifactNames, stageLogPath, } from "../workspaceLayout.js";
+export { listArtifactNames };
+export async function fileExists(filePath) {
+    try {
+        await access(filePath);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+export async function readStageLogFromDisk(workspaceDir, stageId) {
+    const file = stageLogPath(workspaceDir, stageId);
+    if (!(await fileExists(file)))
+        return [];
+    const text = await readFile(file, "utf8");
+    return text
+        .split("\n")
+        .map((line) => line.trim())
+        .filter(Boolean)
+        .map((line) => JSON.parse(line));
+}
+export async function loadStageSnapshotFromDisk(workspaceDir, stageId, store, runId) {
+    if (store !== undefined && runId !== undefined) {
+        return buildStageSnapshotFromStore(store, runId, stageId, workspaceDir);
+    }
+    const events = await readStageLogFromDisk(workspaceDir, stageId);
+    const envFile = envelopePath(workspaceDir, stageId);
+    let envelope = null;
+    if (await fileExists(envFile)) {
+        envelope = JSON.parse(await readFile(envFile, "utf8"));
+    }
+    const artifacts = await listArtifactNames(workspaceDir, stageId, 1);
+    const last_at = events.length > 0 ? events[events.length - 1]?.at : undefined;
+    const pending = derivePendingPrompt(events);
+    return {
+        stage_id: stageId,
+        status: stageStatusFromEvents(events),
+        events,
+        envelope,
+        artifacts,
+        last_at,
+        attempt_count: 1,
+        ...(pending ? { pending_prompt: pending } : {}),
+    };
+}
+export async function listStageIdsFromDisk(workspaceDir, meta) {
+    if (meta?.pipeline_dag?.stage_ids?.length) {
+        return [...meta.pipeline_dag.stage_ids];
+    }
+    const stagesPath = path.join(workspaceDir, "stages");
+    if (!(await fileExists(stagesPath)))
+        return [];
+    const entries = await readdir(stagesPath, { withFileTypes: true });
+    return entries.filter((e) => e.isDirectory()).map((e) => e.name).sort();
+}
+export async function taskIdFromCopy(workspaceDir, meta) {
+    if (meta.task_id)
+        return meta.task_id;
+    const taskPath = path.join(workspaceDir, "task.copy.yaml");
+    if (!(await fileExists(taskPath)))
+        return undefined;
+    try {
+        const task = loadTaskFromYaml(await readFile(taskPath, "utf8"), "task.copy.yaml");
+        return task.id;
+    }
+    catch {
+        return undefined;
+    }
+}
+export async function readRunMetaFromDisk(workspaceDir) {
+    const file = path.join(workspaceDir, "meta.json");
+    return JSON.parse(await readFile(file, "utf8"));
+}
+export async function buildRunSummaryFromDisk(workspaceDir) {
+    const meta = await readRunMetaFromDisk(workspaceDir);
+    const stageIds = await listStageIdsFromDisk(workspaceDir, meta);
+    const loaded = await Promise.all(stageIds.map((id) => loadStageSnapshotFromDisk(workspaceDir, id)));
+    const stages = meta.pipeline_dag?.stage_ids?.length
+        ? orderStageSnapshots(meta.pipeline_dag.stage_ids, loaded)
+        : loaded;
+    const task_id = await taskIdFromCopy(workspaceDir, meta);
+    return projectRunSummary({ ...meta, task_id }, stages);
+}
+export async function buildRunDetailFromDisk(workspaceDir) {
+    const meta = await readRunMetaFromDisk(workspaceDir);
+    const task_yaml = await readFile(path.join(workspaceDir, "task.copy.yaml"), "utf8");
+    const stageIds = await listStageIdsFromDisk(workspaceDir, meta);
+    const loaded = await Promise.all(stageIds.map((id) => loadStageSnapshotFromDisk(workspaceDir, id)));
+    const stages = meta.pipeline_dag?.stage_ids?.length
+        ? orderStageSnapshots(meta.pipeline_dag.stage_ids, loaded)
+        : loaded;
+    const task_id = await taskIdFromCopy(workspaceDir, meta);
+    return projectRunDetail({ ...meta, task_id }, stages, task_yaml, meta.pipeline_dag ?? null);
+}

package/dist/runstore/layout.d.ts

@@ -0,0 +1,22 @@
+import type { StageEnvelope } from "../types/envelope.js";
+import type { RunMeta, RunStatus } from "./port.js";
+export type { RunMeta, RunStatus } from "./port.js";
+export { stageDir } from "./paths.js";
+export declare function runsRoot(rootDir: string): string;
+export declare function runDirFor(rootDir: string, runId: string): string;
+export declare function createRun(options: {
+    rootDir: string;
+    pipelineId: string;
+    taskYaml: string;
+    taskId?: string;
+}): Promise<{
+    runId: string;
+    runDir: string;
+}>;
+export declare function writeRunMeta(runDir: string, meta: RunMeta): Promise<void>;
+export declare function readRunMeta(runDir: string): Promise<RunMeta>;
+export declare function updateRunStatus(runDir: string, status: RunStatus): Promise<void>;
+export declare function ensureStageDirs(runDir: string, stageId: string): Promise<string>;
+export declare function writeEnvelope(runDir: string, stageId: string, envelope: StageEnvelope): Promise<string>;
+export declare function appendStageLog(runDir: string, stageId: string, event: Record<string, unknown>): Promise<void>;
+export declare function readEnvelope(runDir: string, stageId: string): Promise<StageEnvelope>;

package/dist/runstore/layout.js

@@ -0,0 +1,58 @@
+/**
+ * @deprecated Prefer createRunStore() + RunStore. Thin disk helpers for legacy callers.
+ */
+import { appendFile, mkdir, readFile, writeFile } from "node:fs/promises";
+import path from "node:path";
+import { DiskRunStore } from "./disk/DiskRunStore.js";
+import { storeRootFor } from "./paths.js";
+export { stageDir } from "./paths.js";
+function disk(rootDir) {
+    return new DiskRunStore(storeRootFor(rootDir));
+}
+export function runsRoot(rootDir) {
+    return path.join(storeRootFor(rootDir), "runs");
+}
+export function runDirFor(rootDir, runId) {
+    return path.join(runsRoot(rootDir), runId);
+}
+export async function createRun(options) {
+    const created = await disk(options.rootDir).createRun({
+        pipelineId: options.pipelineId,
+        taskYaml: options.taskYaml,
+        taskId: options.taskId,
+    });
+    return { runId: created.runId, runDir: created.workspaceDir };
+}
+export async function writeRunMeta(runDir, meta) {
+    await writeFile(path.join(runDir, "meta.json"), `${JSON.stringify(meta, null, 2)}\n`);
+}
+export async function readRunMeta(runDir) {
+    return JSON.parse(await readFile(path.join(runDir, "meta.json"), "utf8"));
+}
+export async function updateRunStatus(runDir, status) {
+    const meta = await readRunMeta(runDir);
+    meta.status = status;
+    meta.updated_at = new Date().toISOString();
+    await writeRunMeta(runDir, meta);
+}
+export async function ensureStageDirs(runDir, stageId) {
+    const dir = path.join(runDir, "stages", stageId);
+    await mkdir(path.join(dir, "artifacts"), { recursive: true });
+    return dir;
+}
+export async function writeEnvelope(runDir, stageId, envelope) {
+    const dir = await ensureStageDirs(runDir, stageId);
+    const file = path.join(dir, "envelope.json");
+    await writeFile(file, `${JSON.stringify(envelope, null, 2)}\n`);
+    return file;
+}
+export async function appendStageLog(runDir, stageId, event) {
+    const dir = await ensureStageDirs(runDir, stageId);
+    const file = path.join(dir, "log.jsonl");
+    const line = `${JSON.stringify({ ...event, at: new Date().toISOString() })}\n`;
+    await appendFile(file, line);
+}
+export async function readEnvelope(runDir, stageId) {
+    const file = path.join(runDir, "stages", stageId, "envelope.json");
+    return JSON.parse(await readFile(file, "utf8"));
+}

package/dist/runstore/paths.d.ts

@@ -0,0 +1,7 @@
+export declare function newRunId(): string;
+/** Root for factory state under a project: `<rootDir>/.stageflow`. */
+export declare function storeRootFor(rootDir: string): string;
+export declare function migrateLegacyStoreRoot(rootDir: string): void;
+export declare function runsDir(storeRoot: string): string;
+export declare function runWorkspaceDir(storeRoot: string, runId: string): string;
+export declare function stageDir(workspaceDir: string, stageId: string): string;

package/dist/runstore/paths.js

@@ -0,0 +1,60 @@
+import { randomBytes } from "node:crypto";
+import { readdirSync, renameSync, rmdirSync, statSync } from "node:fs";
+import path from "node:path";
+export function newRunId() {
+    const stamp = new Date().toISOString().replace(/[:.]/g, "-");
+    return `${stamp}-${randomBytes(3).toString("hex")}`;
+}
+/** Root for factory state under a project: `<rootDir>/.stageflow`. */
+export function storeRootFor(rootDir) {
+    return path.join(rootDir, ".stageflow");
+}
+function directoryState(dirPath) {
+    try {
+        const st = statSync(dirPath);
+        if (!st.isDirectory())
+            return "other";
+        return readdirSync(dirPath).length === 0 ? "empty" : "populated";
+    }
+    catch (err) {
+        if (err.code === "ENOENT")
+            return "missing";
+        throw err;
+    }
+}
+export function migrateLegacyStoreRoot(rootDir) {
+    const newPath = storeRootFor(rootDir);
+    const oldPath = path.join(rootDir, ".software-factory");
+    const newState = directoryState(newPath);
+    if (newState === "populated") {
+        return;
+    }
+    const oldState = directoryState(oldPath);
+    if (oldState !== "empty" && oldState !== "populated") {
+        return;
+    }
+    if (newState === "empty") {
+        rmdirSync(newPath);
+    }
+    try {
+        renameSync(oldPath, newPath);
+    }
+    catch (err) {
+        const code = err.code;
+        if (code === "ENOENT" &&
+            directoryState(oldPath) === "missing" &&
+            directoryState(newPath) === "populated") {
+            return;
+        }
+        throw err;
+    }
+}
+export function runsDir(storeRoot) {
+    return path.join(storeRoot, "runs");
+}
+export function runWorkspaceDir(storeRoot, runId) {
+    return path.join(runsDir(storeRoot), runId);
+}
+export function stageDir(workspaceDir, stageId) {
+    return path.join(workspaceDir, "stages", stageId);
+}

package/dist/runstore/pipelineDagSnapshot.d.ts

@@ -0,0 +1,5 @@
+import type { LoadedPipeline } from "../types/pipeline.js";
+import type { RunPipelineDagSnapshot } from "./port.js";
+export declare function buildPipelineDagSnapshotFromLoaded(loaded: LoadedPipeline): RunPipelineDagSnapshot;
+export declare function linearCompatDagSnapshot(stageIds: string[]): RunPipelineDagSnapshot;
+export declare function parsePipelineDagSnapshot(raw: unknown): RunPipelineDagSnapshot | null;

package/dist/runstore/pipelineDagSnapshot.js

@@ -0,0 +1,43 @@
+export function buildPipelineDagSnapshotFromLoaded(loaded) {
+    const gate_kinds = {};
+    for (const stage of loaded.stages) {
+        if (stage.gate_kinds?.length) {
+            gate_kinds[stage.id] = stage.gate_kinds;
+        }
+    }
+    return {
+        stage_ids: [...loaded.pipeline.stages],
+        nodes: loaded.dag.nodes,
+        roots: loaded.dag.roots,
+        childrenOf: loaded.dag.childrenOf,
+        ...(Object.keys(gate_kinds).length > 0 ? { gate_kinds } : {}),
+    };
+}
+export function linearCompatDagSnapshot(stageIds) {
+    const nodes = stageIds.map((id, index) => ({
+        id,
+        needs: index === 0 ? null : stageIds[index - 1],
+        ancestors: index === 0 ? [] : stageIds.slice(0, index),
+        stageIndex: index,
+    }));
+    const childrenOf = {};
+    for (let i = 1; i < stageIds.length; i++) {
+        const parent = stageIds[i - 1];
+        const child = stageIds[i];
+        childrenOf[parent] = [...(childrenOf[parent] ?? []), child];
+    }
+    return {
+        stage_ids: [...stageIds],
+        nodes,
+        roots: stageIds.length > 0 ? [stageIds[0]] : [],
+        childrenOf,
+    };
+}
+export function parsePipelineDagSnapshot(raw) {
+    if (!raw || typeof raw !== "object")
+        return null;
+    const value = raw;
+    if (!Array.isArray(value.stage_ids) || !Array.isArray(value.nodes))
+        return null;
+    return raw;
+}