stageflow 0.1.0

package/dist/runstore/sqlite/SqliteRunStore.js

@@ -0,0 +1,460 @@
+import Database from "better-sqlite3";
+import { mkdir } from "node:fs/promises";
+import path from "node:path";
+import { projectRunDetail, projectRunSummary, orderStageSnapshots } from "../runProjection.js";
+import { buildStageSnapshotFromStore } from "../stageSnapshot.js";
+import { parsePipelineDagSnapshot } from "../pipelineDagSnapshot.js";
+import { newRunId, runWorkspaceDir } from "../paths.js";
+import { attemptAgentDir, attemptArtifactsDir, stageDir, } from "../workspaceLayout.js";
+import { importDiskRunsIfEmpty } from "./migrateFromDisk.js";
+import { SCHEMA_SQL } from "./schema.js";
+const ensuredStageDirs = new Set();
+const DEFAULT_SQLITE_BUSY_TIMEOUT_MS = 5000;
+function readSqliteBusyTimeoutMs() {
+    const raw = process.env.STAGEFLOW_SQLITE_BUSY_TIMEOUT_MS;
+    if (raw === undefined || raw.trim() === "") {
+        return DEFAULT_SQLITE_BUSY_TIMEOUT_MS;
+    }
+    const parsed = Number.parseInt(raw, 10);
+    if (!Number.isFinite(parsed) || parsed < 0) {
+        return DEFAULT_SQLITE_BUSY_TIMEOUT_MS;
+    }
+    return parsed;
+}
+function ensureCheckoutRootColumn(db) {
+    const cols = db.prepare(`PRAGMA table_info(runs)`).all();
+    if (!cols.some((c) => c.name === "checkout_root")) {
+        db.exec(`ALTER TABLE runs ADD COLUMN checkout_root TEXT`);
+    }
+}
+function ensurePipelineDagColumn(db) {
+    const cols = db.prepare(`PRAGMA table_info(runs)`).all();
+    if (!cols.some((c) => c.name === "pipeline_dag_json")) {
+        db.exec(`ALTER TABLE runs ADD COLUMN pipeline_dag_json TEXT`);
+    }
+}
+function ensureStageExecutionsTable(db) {
+    db.exec(`
+CREATE TABLE IF NOT EXISTS stage_executions (
+  run_id TEXT NOT NULL,
+  stage_id TEXT NOT NULL,
+  attempt INTEGER NOT NULL,
+  status TEXT NOT NULL,
+  started_at TEXT,
+  finished_at TEXT,
+  envelope_json TEXT,
+  PRIMARY KEY (run_id, stage_id, attempt),
+  FOREIGN KEY (run_id) REFERENCES runs(run_id)
+);
+CREATE INDEX IF NOT EXISTS idx_stage_executions_run_stage
+  ON stage_executions (run_id, stage_id, attempt);
+`);
+}
+function ensureStageEventsAttemptColumn(db) {
+    const cols = db
+        .prepare(`PRAGMA table_info(stage_events)`)
+        .all();
+    if (!cols.some((c) => c.name === "attempt")) {
+        db.exec(`ALTER TABLE stage_events ADD COLUMN attempt INTEGER NOT NULL DEFAULT 1`);
+        db.exec(`
+CREATE INDEX IF NOT EXISTS idx_stage_events_run_stage_attempt_at
+  ON stage_events (run_id, stage_id, attempt, at);
+`);
+    }
+}
+function executionFromRow(row) {
+    return {
+        run_id: row.run_id,
+        stage_id: row.stage_id,
+        attempt: row.attempt,
+        status: row.status,
+        ...(row.started_at != null ? { started_at: row.started_at } : {}),
+        ...(row.finished_at != null ? { finished_at: row.finished_at } : {}),
+        envelope: row.envelope_json
+            ? JSON.parse(row.envelope_json)
+            : null,
+    };
+}
+export class SqliteRunStore {
+    storeRoot;
+    db;
+    migratePromise;
+    constructor(storeRoot) {
+        this.storeRoot = storeRoot;
+        const dbPath = path.join(storeRoot, "state.db");
+        this.db = new Database(dbPath);
+        this.db.pragma("journal_mode = WAL");
+        this.db.pragma(`busy_timeout = ${readSqliteBusyTimeoutMs()}`);
+        this.db.exec(SCHEMA_SQL);
+        ensureCheckoutRootColumn(this.db);
+        ensurePipelineDagColumn(this.db);
+        ensureStageExecutionsTable(this.db);
+        ensureStageEventsAttemptColumn(this.db);
+        this.migratePromise = importDiskRunsIfEmpty(this.db, storeRoot).then(() => undefined);
+    }
+    /** Await one-shot disk import before catalog reads (create paths also wait). */
+    async ready() {
+        await this.migratePromise;
+    }
+    getWorkspaceDir(runId) {
+        return runWorkspaceDir(this.storeRoot, runId);
+    }
+    async createRun(input) {
+        await this.ready();
+        const runId = newRunId();
+        const workspaceDir = this.getWorkspaceDir(runId);
+        await mkdir(path.join(workspaceDir, "stages"), { recursive: true });
+        const now = new Date().toISOString();
+        this.db
+            .prepare(`INSERT INTO runs
+          (run_id, pipeline_id, task_id, task_yaml, status, created_at, updated_at, checkout_root, pipeline_dag_json)
+         VALUES
+          (@run_id, @pipeline_id, @task_id, @task_yaml, @status, @created_at, @updated_at, @checkout_root, @pipeline_dag_json)`)
+            .run({
+            run_id: runId,
+            pipeline_id: input.pipelineId,
+            task_id: input.taskId ?? null,
+            task_yaml: input.taskYaml,
+            status: "running",
+            created_at: now,
+            updated_at: now,
+            checkout_root: input.checkoutRoot ?? null,
+            pipeline_dag_json: input.pipelineDag
+                ? JSON.stringify(input.pipelineDag)
+                : null,
+        });
+        return { runId, workspaceDir };
+    }
+    async updateRunStatus(runId, status) {
+        await this.ready();
+        const result = this.db
+            .prepare(`UPDATE runs SET status = @status, updated_at = @updated_at WHERE run_id = @run_id`)
+            .run({
+            run_id: runId,
+            status,
+            updated_at: new Date().toISOString(),
+        });
+        if (result.changes === 0) {
+            throw new Error(`Run not found: ${runId}`);
+        }
+    }
+    async readRunMeta(runId) {
+        await this.ready();
+        return this.runMetaFromRow(this.getRunRow(runId));
+    }
+    async readTaskYaml(runId) {
+        await this.ready();
+        return this.getRunRow(runId).task_yaml;
+    }
+    async ensureStageWorkspace(runId, stageId) {
+        await this.ready();
+        this.getRunRow(runId);
+        const workspaceDir = this.getWorkspaceDir(runId);
+        const dir = stageDir(workspaceDir, stageId);
+        if (!ensuredStageDirs.has(dir)) {
+            await mkdir(dir, { recursive: true });
+            ensuredStageDirs.add(dir);
+        }
+        this.db
+            .prepare(`INSERT OR IGNORE INTO stages (run_id, stage_id, status)
+         VALUES (@run_id, @stage_id, @status)`)
+            .run({ run_id: runId, stage_id: stageId, status: "pending" });
+    }
+    async ensureAttemptWorkspace(runId, stageId, attempt) {
+        await this.ready();
+        await this.ensureStageWorkspace(runId, stageId);
+        this.getRunRow(runId);
+        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);
+        }
+    }
+    async createStageExecution(runId, stageId) {
+        await this.ready();
+        this.getRunRow(runId);
+        return this.db.transaction(() => {
+            const maxRow = this.db
+                .prepare(`SELECT MAX(attempt) AS max_attempt FROM stage_executions
+           WHERE run_id = ? AND stage_id = ?`)
+                .get(runId, stageId);
+            const attempt = (maxRow?.max_attempt ?? 0) + 1;
+            this.db
+                .prepare(`INSERT INTO stage_executions (run_id, stage_id, attempt, status)
+           VALUES (@run_id, @stage_id, @attempt, @status)`)
+                .run({
+                run_id: runId,
+                stage_id: stageId,
+                attempt,
+                status: "pending",
+            });
+            const row = this.db
+                .prepare(`SELECT run_id, stage_id, attempt, status, started_at, finished_at, envelope_json
+           FROM stage_executions
+           WHERE run_id = ? AND stage_id = ? AND attempt = ?`)
+                .get(runId, stageId, attempt);
+            return executionFromRow(row);
+        })();
+    }
+    async listStageExecutions(runId, stageId) {
+        await this.ready();
+        const rows = this.db
+            .prepare(`SELECT run_id, stage_id, attempt, status, started_at, finished_at, envelope_json
+         FROM stage_executions
+         WHERE run_id = ? AND stage_id = ?
+         ORDER BY attempt ASC`)
+            .all(runId, stageId);
+        return rows.map(executionFromRow);
+    }
+    async getLatestStageExecution(runId, stageId) {
+        await this.ready();
+        const row = this.db
+            .prepare(`SELECT run_id, stage_id, attempt, status, started_at, finished_at, envelope_json
+         FROM stage_executions
+         WHERE run_id = ? AND stage_id = ?
+         ORDER BY attempt DESC
+         LIMIT 1`)
+            .get(runId, stageId);
+        return row ? executionFromRow(row) : null;
+    }
+    async countStageAttempts(runId, stageId) {
+        await this.ready();
+        const row = this.db
+            .prepare(`SELECT COUNT(*) AS n FROM stage_executions
+         WHERE run_id = ? AND stage_id = ?`)
+            .get(runId, stageId);
+        return row.n;
+    }
+    async getStageExecution(runId, stageId, attempt) {
+        await this.ready();
+        const row = this.db
+            .prepare(`SELECT run_id, stage_id, attempt, status, started_at, finished_at, envelope_json
+         FROM stage_executions
+         WHERE run_id = ? AND stage_id = ? AND attempt = ?`)
+            .get(runId, stageId, attempt);
+        if (!row) {
+            throw new Error(`Stage execution not found: ${runId}/${stageId} attempt ${attempt}`);
+        }
+        return executionFromRow(row);
+    }
+    async updateStageExecution(runId, stageId, attempt, patch) {
+        await this.ready();
+        const sets = [];
+        const params = {
+            run_id: runId,
+            stage_id: stageId,
+            attempt,
+        };
+        if (patch.status !== undefined) {
+            sets.push("status = @status");
+            params.status = patch.status;
+        }
+        if (patch.started_at !== undefined) {
+            sets.push("started_at = @started_at");
+            params.started_at = patch.started_at;
+        }
+        if (patch.finished_at !== undefined) {
+            sets.push("finished_at = @finished_at");
+            params.finished_at = patch.finished_at;
+        }
+        if (patch.envelope !== undefined) {
+            sets.push("envelope_json = @envelope_json");
+            params.envelope_json =
+                patch.envelope != null ? JSON.stringify(patch.envelope) : null;
+        }
+        if (sets.length === 0)
+            return;
+        const result = this.db
+            .prepare(`UPDATE stage_executions SET ${sets.join(", ")}
+         WHERE run_id = @run_id AND stage_id = @stage_id AND attempt = @attempt`)
+            .run(params);
+        if (result.changes === 0) {
+            throw new Error(`Stage execution not found: ${runId}/${stageId} attempt ${attempt}`);
+        }
+    }
+    async writeEnvelope(runId, stageId, envelope, options) {
+        const attempt = options?.attempt ?? 1;
+        await this.ensureAttemptWorkspace(runId, stageId, attempt);
+        this.db
+            .prepare(`INSERT INTO stages
+           (run_id, stage_id, status, summary, envelope_json)
+         VALUES
+           (@run_id, @stage_id, @status, @summary, @envelope_json)
+         ON CONFLICT(run_id, stage_id) DO UPDATE SET
+           summary = excluded.summary,
+           envelope_json = excluded.envelope_json`)
+            .run({
+            run_id: runId,
+            stage_id: stageId,
+            status: envelope.status === "success" ? "succeeded" : "failed",
+            summary: envelope.summary,
+            envelope_json: JSON.stringify(envelope),
+        });
+        await this.updateStageExecution(runId, stageId, attempt, { envelope });
+    }
+    async readEnvelope(runId, stageId) {
+        await this.ready();
+        const execution = await this.getLatestStageExecution(runId, stageId);
+        if (execution?.envelope != null) {
+            return execution.envelope;
+        }
+        const fromStages = this.readEnvelopeFromDb(runId, stageId);
+        if (fromStages != null) {
+            return fromStages;
+        }
+        throw new Error(`Envelope not found: ${runId}/${stageId}`);
+    }
+    readEnvelopeFromDb(runId, stageId) {
+        const row = this.db
+            .prepare(`SELECT envelope_json FROM stages WHERE run_id = ? AND stage_id = ?`)
+            .get(runId, stageId);
+        if (row?.envelope_json == null) {
+            return null;
+        }
+        return JSON.parse(row.envelope_json);
+    }
+    async appendStageEvent(runId, stageId, event, options) {
+        const attempt = options?.attempt ?? 1;
+        await this.ensureAttemptWorkspace(runId, stageId, attempt);
+        const at = new Date().toISOString();
+        const eventName = event.event;
+        const rest = { ...event };
+        delete rest.event;
+        delete rest.at;
+        this.db
+            .prepare(`INSERT INTO stage_events (run_id, stage_id, attempt, at, event, payload_json)
+         VALUES (@run_id, @stage_id, @attempt, @at, @event, @payload_json)`)
+            .run({
+            run_id: runId,
+            stage_id: stageId,
+            attempt,
+            at,
+            event: eventName,
+            payload_json: Object.keys(rest).length > 0 ? JSON.stringify(rest) : null,
+        });
+        this.updateStageStatusDenorm(runId, stageId, eventName, at);
+    }
+    /**
+     * @remarks Intentional denormalization: mirrors lifecycle events into
+     * `stages.status` for legacy compatibility. This column is not the
+     * authoritative source for snapshot projection; status is event-derived
+     * in `buildStageSnapshotFromStore`.
+     */
+    updateStageStatusDenorm(runId, stageId, eventName, at) {
+        if (eventName === "started" || eventName === "resumed") {
+            this.db
+                .prepare(`UPDATE stages SET status = 'running', started_at = COALESCE(started_at, @at)
+           WHERE run_id = @run_id AND stage_id = @stage_id`)
+                .run({ run_id: runId, stage_id: stageId, at });
+        }
+        else if (eventName === "waiting_for_input") {
+            this.db
+                .prepare(`UPDATE stages SET status = 'waiting_for_input'
+           WHERE run_id = @run_id AND stage_id = @stage_id`)
+                .run({ run_id: runId, stage_id: stageId });
+        }
+        else if (eventName === "succeeded" || eventName === "failed") {
+            this.db
+                .prepare(`UPDATE stages SET status = @status, finished_at = @at
+           WHERE run_id = @run_id AND stage_id = @stage_id`)
+                .run({
+                run_id: runId,
+                stage_id: stageId,
+                status: eventName,
+                at,
+            });
+        }
+    }
+    async listStageEvents(runId, stageId, attempt) {
+        await this.ready();
+        return this.loadEvents(runId, stageId, attempt);
+    }
+    async listRuns() {
+        await this.ready();
+        const rows = this.db
+            .prepare(`SELECT run_id, pipeline_id, task_id, task_yaml, status, created_at, updated_at, checkout_root, pipeline_dag_json
+         FROM runs ORDER BY created_at DESC`)
+            .all();
+        const summaries = [];
+        for (const row of rows) {
+            const dagSnapshot = this.readPipelineDagSnapshotFromRow(row);
+            const stages = await this.loadStageSnapshots(row.run_id, dagSnapshot?.stage_ids);
+            summaries.push(projectRunSummary(this.runMetaFromRow(row), stages));
+        }
+        return summaries;
+    }
+    async readRun(runId) {
+        await this.ready();
+        const row = this.getRunRow(runId);
+        const dagSnapshot = this.readPipelineDagSnapshotFromRow(row);
+        const stages = await this.loadStageSnapshots(runId, dagSnapshot?.stage_ids);
+        return projectRunDetail(this.runMetaFromRow(row), stages, row.task_yaml, dagSnapshot);
+    }
+    readPipelineDagSnapshotFromRow(row) {
+        if (!row.pipeline_dag_json)
+            return null;
+        return parsePipelineDagSnapshot(JSON.parse(row.pipeline_dag_json));
+    }
+    runMetaFromRow(row) {
+        return {
+            run_id: row.run_id,
+            pipeline_id: row.pipeline_id,
+            created_at: row.created_at,
+            status: row.status,
+            task_id: row.task_id ?? undefined,
+            updated_at: row.updated_at,
+            ...(row.checkout_root != null ? { checkout_root: row.checkout_root } : {}),
+        };
+    }
+    getRunRow(runId) {
+        const row = this.db
+            .prepare(`SELECT run_id, pipeline_id, task_id, task_yaml, status, created_at, updated_at, checkout_root, pipeline_dag_json
+         FROM runs WHERE run_id = ?`)
+            .get(runId);
+        if (!row)
+            throw new Error(`Run not found: ${runId}`);
+        return row;
+    }
+    loadEvents(runId, stageId, attempt) {
+        const rows = attempt
+            ? this.db
+                .prepare(`SELECT at, event, payload_json FROM stage_events
+             WHERE run_id = ? AND stage_id = ? AND attempt = ?
+             ORDER BY id ASC`)
+                .all(runId, stageId, attempt)
+            : this.db
+                .prepare(`SELECT at, event, payload_json FROM stage_events
+             WHERE run_id = ? AND stage_id = ?
+             ORDER BY id ASC`)
+                .all(runId, stageId);
+        return rows.map((row) => {
+            const payload = row.payload_json
+                ? JSON.parse(row.payload_json)
+                : {};
+            return { event: row.event, at: row.at, ...payload };
+        });
+    }
+    async loadStageSnapshots(runId, stageIds) {
+        const workspaceDir = this.getWorkspaceDir(runId);
+        const rows = this.db
+            .prepare(`SELECT stage_id FROM stages WHERE run_id = ? ORDER BY stage_id ASC`)
+            .all(runId);
+        const ids = stageIds?.length
+            ? stageIds
+            : rows.map((row) => row.stage_id);
+        const snapshots = await Promise.all(ids.map((stageId) => buildStageSnapshotFromStore(this, runId, stageId, workspaceDir)));
+        if (stageIds?.length) {
+            return orderStageSnapshots(stageIds, snapshots);
+        }
+        return snapshots;
+    }
+}
+export function openSqliteRunStore(storeRoot) {
+    return new SqliteRunStore(storeRoot);
+}

package/dist/runstore/sqlite/migrateFromDisk.d.ts

@@ -0,0 +1,5 @@
+import type Database from "better-sqlite3";
+/**
+ * One-shot import of legacy disk run folders into SQLite when the DB has no runs yet.
+ */
+export declare function importDiskRunsIfEmpty(db: Database.Database, storeRoot: string): Promise<number>;

package/dist/runstore/sqlite/migrateFromDisk.js

@@ -0,0 +1,108 @@
+import { readdir } from "node:fs/promises";
+import path from "node:path";
+import { buildRunDetailFromDisk, fileExists, readRunMetaFromDisk, } from "../disk/catalogHelpers.js";
+import { runsDir } from "../paths.js";
+/**
+ * One-shot import of legacy disk run folders into SQLite when the DB has no runs yet.
+ */
+export async function importDiskRunsIfEmpty(db, storeRoot) {
+    const count = db.prepare("SELECT COUNT(*) AS n FROM runs").get().n;
+    if (count > 0)
+        return 0;
+    const root = runsDir(storeRoot);
+    if (!(await fileExists(root)))
+        return 0;
+    const entries = await readdir(root, { withFileTypes: true });
+    let imported = 0;
+    const insertRun = db.prepare(`
+    INSERT OR IGNORE INTO runs
+      (run_id, pipeline_id, task_id, task_yaml, status, created_at, updated_at, checkout_root)
+    VALUES
+      (@run_id, @pipeline_id, @task_id, @task_yaml, @status, @created_at, @updated_at, @checkout_root)
+  `);
+    const upsertStage = db.prepare(`
+    INSERT INTO stages
+      (run_id, stage_id, status, summary, envelope_json, started_at, finished_at)
+    VALUES
+      (@run_id, @stage_id, @status, @summary, @envelope_json, @started_at, @finished_at)
+    ON CONFLICT(run_id, stage_id) DO UPDATE SET
+      status = excluded.status,
+      summary = excluded.summary,
+      envelope_json = excluded.envelope_json,
+      started_at = excluded.started_at,
+      finished_at = excluded.finished_at
+  `);
+    const insertEvent = db.prepare(`
+    INSERT INTO stage_events (run_id, stage_id, attempt, at, event, payload_json)
+    VALUES (@run_id, @stage_id, @attempt, @at, @event, @payload_json)
+  `);
+    const insertExecution = db.prepare(`
+    INSERT INTO stage_executions
+      (run_id, stage_id, attempt, status, started_at, finished_at, envelope_json)
+    VALUES
+      (@run_id, @stage_id, @attempt, @status, @started_at, @finished_at, @envelope_json)
+  `);
+    for (const entry of entries) {
+        if (!entry.isDirectory())
+            continue;
+        const workspaceDir = path.join(root, entry.name);
+        try {
+            if (!(await fileExists(path.join(workspaceDir, "meta.json"))))
+                continue;
+            const detail = await buildRunDetailFromDisk(workspaceDir);
+            const meta = await readRunMetaFromDisk(workspaceDir);
+            db.transaction(() => {
+                insertRun.run({
+                    run_id: detail.run_id,
+                    pipeline_id: detail.pipeline_id,
+                    task_id: detail.task_id ?? null,
+                    task_yaml: detail.task_yaml,
+                    status: detail.status,
+                    created_at: detail.created_at,
+                    updated_at: detail.updated_at ?? meta.updated_at ?? detail.created_at,
+                    checkout_root: meta.checkout_root ?? null,
+                });
+                for (const stage of detail.stages) {
+                    const started = stage.events.find((e) => e.event === "started")?.at ?? null;
+                    const finished = [...stage.events]
+                        .reverse()
+                        .find((e) => e.event === "succeeded" || e.event === "failed")?.at ?? null;
+                    upsertStage.run({
+                        run_id: detail.run_id,
+                        stage_id: stage.stage_id,
+                        status: stage.status,
+                        summary: stage.envelope?.summary ?? null,
+                        envelope_json: stage.envelope ? JSON.stringify(stage.envelope) : null,
+                        started_at: started,
+                        finished_at: finished,
+                    });
+                    insertExecution.run({
+                        run_id: detail.run_id,
+                        stage_id: stage.stage_id,
+                        attempt: 1,
+                        status: stage.status,
+                        started_at: started,
+                        finished_at: finished,
+                        envelope_json: stage.envelope ? JSON.stringify(stage.envelope) : null,
+                    });
+                    for (const ev of stage.events) {
+                        const { event, at, ...rest } = ev;
+                        insertEvent.run({
+                            run_id: detail.run_id,
+                            stage_id: stage.stage_id,
+                            attempt: 1,
+                            at: at ?? new Date().toISOString(),
+                            event,
+                            payload_json: Object.keys(rest).length > 0 ? JSON.stringify(rest) : null,
+                        });
+                    }
+                }
+            })();
+            imported += 1;
+        }
+        catch {
+            // skip malformed run folders
+        }
+    }
+    return imported;
+}

package/dist/runstore/sqlite/schema.d.ts

@@ -0,0 +1 @@
+export declare const SCHEMA_SQL = "\nCREATE TABLE IF NOT EXISTS runs (\n  run_id TEXT PRIMARY KEY,\n  pipeline_id TEXT NOT NULL,\n  task_id TEXT,\n  task_yaml TEXT NOT NULL,\n  status TEXT NOT NULL,\n  created_at TEXT NOT NULL,\n  updated_at TEXT NOT NULL,\n  checkout_root TEXT,\n  pipeline_dag_json TEXT\n);\n\nCREATE TABLE IF NOT EXISTS stages (\n  run_id TEXT NOT NULL,\n  stage_id TEXT NOT NULL,\n  status TEXT,\n  summary TEXT,\n  envelope_json TEXT,\n  started_at TEXT,\n  finished_at TEXT,\n  PRIMARY KEY (run_id, stage_id),\n  FOREIGN KEY (run_id) REFERENCES runs(run_id)\n);\n\nCREATE TABLE IF NOT EXISTS stage_events (\n  id INTEGER PRIMARY KEY AUTOINCREMENT,\n  run_id TEXT NOT NULL,\n  stage_id TEXT NOT NULL,\n  at TEXT NOT NULL,\n  event TEXT NOT NULL,\n  payload_json TEXT,\n  FOREIGN KEY (run_id) REFERENCES runs(run_id)\n);\n\nCREATE INDEX IF NOT EXISTS idx_runs_status_created\n  ON runs (status, created_at DESC);\n\nCREATE INDEX IF NOT EXISTS idx_runs_pipeline_created\n  ON runs (pipeline_id, created_at DESC);\n\nCREATE INDEX IF NOT EXISTS idx_stage_events_run_stage_at\n  ON stage_events (run_id, stage_id, at);\n\nCREATE TABLE IF NOT EXISTS stage_executions (\n  run_id TEXT NOT NULL,\n  stage_id TEXT NOT NULL,\n  attempt INTEGER NOT NULL,\n  status TEXT NOT NULL,\n  started_at TEXT,\n  finished_at TEXT,\n  envelope_json TEXT,\n  PRIMARY KEY (run_id, stage_id, attempt),\n  FOREIGN KEY (run_id) REFERENCES runs(run_id)\n);\n\nCREATE INDEX IF NOT EXISTS idx_stage_executions_run_stage\n  ON stage_executions (run_id, stage_id, attempt);\n";

package/dist/runstore/sqlite/schema.js

@@ -0,0 +1,59 @@
+export const SCHEMA_SQL = `
+CREATE TABLE IF NOT EXISTS runs (
+  run_id TEXT PRIMARY KEY,
+  pipeline_id TEXT NOT NULL,
+  task_id TEXT,
+  task_yaml TEXT NOT NULL,
+  status TEXT NOT NULL,
+  created_at TEXT NOT NULL,
+  updated_at TEXT NOT NULL,
+  checkout_root TEXT,
+  pipeline_dag_json TEXT
+);
+
+CREATE TABLE IF NOT EXISTS stages (
+  run_id TEXT NOT NULL,
+  stage_id TEXT NOT NULL,
+  status TEXT,
+  summary TEXT,
+  envelope_json TEXT,
+  started_at TEXT,
+  finished_at TEXT,
+  PRIMARY KEY (run_id, stage_id),
+  FOREIGN KEY (run_id) REFERENCES runs(run_id)
+);
+
+CREATE TABLE IF NOT EXISTS stage_events (
+  id INTEGER PRIMARY KEY AUTOINCREMENT,
+  run_id TEXT NOT NULL,
+  stage_id TEXT NOT NULL,
+  at TEXT NOT NULL,
+  event TEXT NOT NULL,
+  payload_json TEXT,
+  FOREIGN KEY (run_id) REFERENCES runs(run_id)
+);
+
+CREATE INDEX IF NOT EXISTS idx_runs_status_created
+  ON runs (status, created_at DESC);
+
+CREATE INDEX IF NOT EXISTS idx_runs_pipeline_created
+  ON runs (pipeline_id, created_at DESC);
+
+CREATE INDEX IF NOT EXISTS idx_stage_events_run_stage_at
+  ON stage_events (run_id, stage_id, at);
+
+CREATE TABLE IF NOT EXISTS stage_executions (
+  run_id TEXT NOT NULL,
+  stage_id TEXT NOT NULL,
+  attempt INTEGER NOT NULL,
+  status TEXT NOT NULL,
+  started_at TEXT,
+  finished_at TEXT,
+  envelope_json TEXT,
+  PRIMARY KEY (run_id, stage_id, attempt),
+  FOREIGN KEY (run_id) REFERENCES runs(run_id)
+);
+
+CREATE INDEX IF NOT EXISTS idx_stage_executions_run_stage
+  ON stage_executions (run_id, stage_id, attempt);
+`;

package/dist/runstore/stageExecution.d.ts

@@ -0,0 +1,13 @@
+import type { StageEnvelope } from "../types/envelope.js";
+import type { StageLogEvent, StageSnapshot } from "./port.js";
+export type StageExecutionPatch = {
+    status?: StageSnapshot["status"];
+    started_at?: string;
+    finished_at?: string;
+    envelope?: StageEnvelope | null;
+};
+export declare function executionStatusFromEvents(events: StageLogEvent[]): StageSnapshot["status"];
+export declare function deriveExecutionPatchFromEvent(event: StageLogEvent, current: Pick<StageSnapshot, "status"> & {
+    started_at?: string;
+    finished_at?: string;
+}): StageExecutionPatch;

package/dist/runstore/stageExecution.js

@@ -0,0 +1,22 @@
+import { stageStatusFromEvents } from "./port.js";
+export function executionStatusFromEvents(events) {
+    return stageStatusFromEvents(events);
+}
+export function deriveExecutionPatchFromEvent(event, current) {
+    const patch = {};
+    const eventName = event.event;
+    const at = event.at ?? new Date().toISOString();
+    if (eventName === "started" || eventName === "resumed") {
+        patch.status = "running";
+        if (!current.started_at)
+            patch.started_at = at;
+    }
+    else if (eventName === "waiting_for_input") {
+        patch.status = "waiting_for_input";
+    }
+    else if (eventName === "succeeded" || eventName === "failed") {
+        patch.status = eventName;
+        patch.finished_at = at;
+    }
+    return patch;
+}

package/dist/runstore/stageSnapshot.d.ts

@@ -0,0 +1,2 @@
+import type { RunStore, StageSnapshot } from "./port.js";
+export declare function buildStageSnapshotFromStore(store: RunStore, runId: string, stageId: string, workspaceDir: string): Promise<StageSnapshot>;