stageflow 0.1.0

package/dist/runtime/stageAttemptContext.js

@@ -0,0 +1,26 @@
+import { attemptAgentDir, attemptSessionPath, } from "../runstore/workspaceLayout.js";
+function createAttemptContext(attempt) {
+    return {
+        attempt,
+        eventOptions() {
+            if (attempt <= 1)
+                return undefined;
+            return { attempt };
+        },
+        sessionPath(workspaceDir, stageId) {
+            return attemptSessionPath(workspaceDir, stageId, attempt);
+        },
+        agentDirPath(workspaceDir, stageId) {
+            return attemptAgentDir(workspaceDir, stageId, attempt);
+        },
+    };
+}
+export function attemptContext(attempt) {
+    return createAttemptContext(attempt);
+}
+export function noAttemptContext() {
+    return createAttemptContext(1);
+}
+export function resumeSessionFilePath(workspaceDir, stageId, attempt) {
+    return attemptContext(attempt).sessionPath(workspaceDir, stageId);
+}

package/dist/runtime/stageConcurrency.d.ts

@@ -0,0 +1,10 @@
+export declare const UNLIMITED_CONCURRENCY: number;
+export declare const DEFAULT_MAX_ACTIVE_STAGES_PER_RUN: number;
+export declare const MAX_ACTIVE_STAGES_PER_RUN_ENV = "STAGEFLOW_MAX_ACTIVE_STAGES_PER_RUN";
+export declare const DEFAULT_MAX_ACTIVE_STAGE_PROCESSES: number;
+export declare const MAX_ACTIVE_STAGE_PROCESSES_ENV = "STAGEFLOW_MAX_ACTIVE_STAGE_PROCESSES";
+export declare const STAGE_EXECUTION_ENV = "STAGEFLOW_STAGE_EXECUTION";
+export type StageExecutionMode = "process" | "inprocess";
+export declare function readStageExecutionMode(env?: Record<string, string | undefined>, override?: StageExecutionMode): StageExecutionMode;
+export declare function readMaxActiveStagesPerRun(env?: Record<string, string | undefined>, override?: number): number;
+export declare function readMaxActiveStageProcesses(env?: Record<string, string | undefined>, override?: number): number;

package/dist/runtime/stageConcurrency.js

@@ -0,0 +1,51 @@
+export const UNLIMITED_CONCURRENCY = Number.POSITIVE_INFINITY;
+export const DEFAULT_MAX_ACTIVE_STAGES_PER_RUN = UNLIMITED_CONCURRENCY;
+export const MAX_ACTIVE_STAGES_PER_RUN_ENV = "STAGEFLOW_MAX_ACTIVE_STAGES_PER_RUN";
+export const DEFAULT_MAX_ACTIVE_STAGE_PROCESSES = UNLIMITED_CONCURRENCY;
+export const MAX_ACTIVE_STAGE_PROCESSES_ENV = "STAGEFLOW_MAX_ACTIVE_STAGE_PROCESSES";
+export const STAGE_EXECUTION_ENV = "STAGEFLOW_STAGE_EXECUTION";
+export function readStageExecutionMode(env = process.env, override) {
+    if (override !== undefined) {
+        return override;
+    }
+    if (env.VITEST === "true") {
+        return "inprocess";
+    }
+    const raw = env[STAGE_EXECUTION_ENV];
+    if (raw === "inprocess" || raw === "process") {
+        return raw;
+    }
+    return "process";
+}
+export function readMaxActiveStagesPerRun(env = process.env, override) {
+    if (override !== undefined) {
+        if (Number.isFinite(override) && override >= 1)
+            return override;
+        return DEFAULT_MAX_ACTIVE_STAGES_PER_RUN;
+    }
+    const raw = env[MAX_ACTIVE_STAGES_PER_RUN_ENV];
+    if (raw === undefined || raw.trim() === "") {
+        return DEFAULT_MAX_ACTIVE_STAGES_PER_RUN;
+    }
+    const n = Number.parseInt(raw, 10);
+    if (!Number.isFinite(n) || n < 1) {
+        return DEFAULT_MAX_ACTIVE_STAGES_PER_RUN;
+    }
+    return n;
+}
+export function readMaxActiveStageProcesses(env = process.env, override) {
+    if (override !== undefined) {
+        if (Number.isFinite(override) && override >= 1)
+            return override;
+        return DEFAULT_MAX_ACTIVE_STAGE_PROCESSES;
+    }
+    const raw = env[MAX_ACTIVE_STAGE_PROCESSES_ENV];
+    if (raw === undefined || raw.trim() === "") {
+        return DEFAULT_MAX_ACTIVE_STAGE_PROCESSES;
+    }
+    const n = Number.parseInt(raw, 10);
+    if (!Number.isFinite(n) || n < 1) {
+        return DEFAULT_MAX_ACTIVE_STAGE_PROCESSES;
+    }
+    return n;
+}

package/dist/runtime/stageHitl.d.ts

@@ -0,0 +1,95 @@
+import type { OpaqueAnswer, OpaqueWaitRequest, StageHandle } from "../agent/port.js";
+import type { RunStore } from "../runstore/port.js";
+import { type StageAttemptContext } from "./stageAttemptContext.js";
+import { type AskOperatorPrompt } from "../tools/askOperator.js";
+export type DeliverAnswerResult = {
+    ok: true;
+} | {
+    ok: false;
+    reason: string;
+    status: 404 | 409 | 400 | 500;
+};
+export type DeliverAnswerPrefixResult = {
+    ok: true;
+    mode: "live";
+} | {
+    ok: true;
+    mode: "restart";
+} | {
+    ok: false;
+    reason: string;
+    status: 400;
+};
+export type AnswerPromptAssertContext = {
+    runId: string;
+    stageId: string;
+    answer: OpaqueAnswer;
+    pendingRequest?: OpaqueWaitRequest;
+};
+export type AssertAnswerMatchesPrompt = (ctx: AnswerPromptAssertContext) => void | Promise<void>;
+export type HitlWaitEnterContext = {
+    runId: string;
+    stageId: string;
+    request: OpaqueWaitRequest;
+    attempt?: number;
+};
+export type HitlAnswerDeliverContext = {
+    runId: string;
+    stageId: string;
+    answer: OpaqueAnswer;
+    pendingRequest?: OpaqueWaitRequest;
+    attempt?: number;
+};
+export type HitlQaHooks = {
+    onWaitEnter?: (ctx: HitlWaitEnterContext) => void | Promise<void>;
+    onAnswerDeliver?: (ctx: HitlAnswerDeliverContext) => void | Promise<void>;
+};
+export type HitlSeams = {
+    assertAnswerMatchesPrompt?: AssertAnswerMatchesPrompt;
+    qaHooks?: HitlQaHooks;
+};
+export declare function tryParsePendingPrompt(pendingRequest: OpaqueWaitRequest | undefined): AskOperatorPrompt | undefined;
+export declare const t2AssertAnswerMatchesPrompt: AssertAnswerMatchesPrompt;
+export declare function createDefaultHitlQaHooks(store: RunStore): HitlQaHooks;
+export declare function recordWaitEnter(options: {
+    store: RunStore;
+    runId: string;
+    stageId: string;
+    request: OpaqueWaitRequest;
+    attemptCtx?: StageAttemptContext;
+    qaHooks: HitlQaHooks;
+}): Promise<void>;
+export declare function waitKey(runId: string, stageId: string): string;
+/**
+ * HITL coordinator: wait-enter + answer-deliver (live and restart), with a
+ * single pending source for the T2 assert gate.
+ */
+export declare class StageHitlController {
+    private readonly options;
+    private readonly live;
+    private readonly assertAnswerMatchesPrompt;
+    private readonly qaHooks;
+    constructor(options: {
+        store: RunStore;
+        seams?: HitlSeams;
+    });
+    hasLiveWait(runId: string, stageId: string): boolean;
+    private latestAttemptForStage;
+    private attemptEventOptions;
+    /**
+     * KTD6 wait-enter: T3 wait-enter hook → lifecycle waiting_for_input → park.
+     */
+    enterWait(runId: string, stageId: string, handle: StageHandle, request: OpaqueWaitRequest, attemptCtx?: StageAttemptContext): Promise<void>;
+    private parkUntilAnswer;
+    clearLiveWait(runId: string, stageId: string): void;
+    /**
+     * Resolve pending for assert: live park map, else trail-derived T2 prompt.
+     * Non-T2 string fixtures yield undefined (assert pass-through).
+     */
+    private resolvePendingRequest;
+    /**
+     * KTD6 answer-deliver prefix for live and restart:
+     * resolve pending → assert → answer hook → resumed → live unpark or restart ok.
+     */
+    deliverAnswerPrefix(runId: string, stageId: string, opaqueAnswer: OpaqueAnswer, attemptCtx?: StageAttemptContext): Promise<DeliverAnswerPrefixResult>;
+}

package/dist/runtime/stageHitl.js

@@ -0,0 +1,198 @@
+import { appendOperatorAnswer, appendOperatorPrompt, derivePendingPrompt, } from "../hitl/qaTrail.js";
+import { deriveExecutionPatchFromEvent } from "../runstore/stageExecution.js";
+import { attemptContext } from "./stageAttemptContext.js";
+import { AskOperatorError, assertAnswerMatchesPrompt, normalizePromptIds, parseAskOperatorAnswer, parseAskOperatorParams, } from "../tools/askOperator.js";
+export function tryParsePendingPrompt(pendingRequest) {
+    if (pendingRequest === undefined) {
+        return undefined;
+    }
+    try {
+        return normalizePromptIds(parseAskOperatorParams(pendingRequest));
+    }
+    catch {
+        return undefined;
+    }
+}
+export const t2AssertAnswerMatchesPrompt = (ctx) => {
+    const prompt = tryParsePendingPrompt(ctx.pendingRequest);
+    if (prompt === undefined) {
+        return;
+    }
+    try {
+        const answer = parseAskOperatorAnswer(ctx.answer);
+        assertAnswerMatchesPrompt(prompt, answer);
+    }
+    catch (err) {
+        if (err instanceof AskOperatorError) {
+            throw err;
+        }
+        throw new AskOperatorError(err instanceof Error ? err.message : String(err));
+    }
+};
+export function createDefaultHitlQaHooks(store) {
+    return {
+        async onWaitEnter(ctx) {
+            const prompt = tryParsePendingPrompt(ctx.request);
+            if (!prompt)
+                return;
+            const options = attemptContext(ctx.attempt ?? 1).eventOptions();
+            await appendOperatorPrompt(store, ctx.runId, ctx.stageId, prompt, options);
+        },
+        async onAnswerDeliver(ctx) {
+            let answer;
+            try {
+                answer = parseAskOperatorAnswer(ctx.answer);
+            }
+            catch {
+                return;
+            }
+            const options = attemptContext(ctx.attempt ?? 1).eventOptions();
+            await appendOperatorAnswer(store, ctx.runId, ctx.stageId, answer, options);
+        },
+    };
+}
+export async function recordWaitEnter(options) {
+    const { store, runId, stageId, request, qaHooks } = options;
+    const resolvedAttempt = options.attemptCtx?.attempt ??
+        ((await store.getLatestStageExecution(runId, stageId))?.attempt ?? 1);
+    const resolvedCtx = options.attemptCtx ?? attemptContext(resolvedAttempt);
+    await qaHooks.onWaitEnter?.({
+        runId,
+        stageId,
+        request,
+        attempt: resolvedAttempt,
+    });
+    const event = { event: "waiting_for_input" };
+    await store.appendStageEvent(runId, stageId, event, resolvedCtx.eventOptions());
+    try {
+        const execution = await store.getStageExecution(runId, stageId, resolvedAttempt);
+        const patch = deriveExecutionPatchFromEvent(event, execution);
+        if (Object.keys(patch).length === 0)
+            return;
+        await store.updateStageExecution(runId, stageId, resolvedAttempt, patch);
+    }
+    catch {
+        // no execution row yet
+    }
+}
+export function waitKey(runId, stageId) {
+    return `${runId}\0${stageId}`;
+}
+/**
+ * HITL coordinator: wait-enter + answer-deliver (live and restart), with a
+ * single pending source for the T2 assert gate.
+ */
+export class StageHitlController {
+    options;
+    live = new Map();
+    assertAnswerMatchesPrompt;
+    qaHooks;
+    constructor(options) {
+        this.options = options;
+        this.assertAnswerMatchesPrompt =
+            options.seams?.assertAnswerMatchesPrompt ?? t2AssertAnswerMatchesPrompt;
+        this.qaHooks =
+            options.seams?.qaHooks ?? createDefaultHitlQaHooks(options.store);
+    }
+    hasLiveWait(runId, stageId) {
+        return this.live.has(waitKey(runId, stageId));
+    }
+    async latestAttemptForStage(runId, stageId) {
+        const latest = await this.options.store.getLatestStageExecution(runId, stageId);
+        return latest?.attempt ?? 1;
+    }
+    attemptEventOptions(attempt) {
+        return attemptContext(attempt).eventOptions();
+    }
+    /**
+     * KTD6 wait-enter: T3 wait-enter hook → lifecycle waiting_for_input → park.
+     */
+    async enterWait(runId, stageId, handle, request, attemptCtx) {
+        await recordWaitEnter({
+            store: this.options.store,
+            runId,
+            stageId,
+            request,
+            attemptCtx,
+            qaHooks: this.qaHooks,
+        });
+        console.error(`Stage ${stageId} waiting for input.`);
+        await this.parkUntilAnswer(runId, stageId, handle, request);
+    }
+    parkUntilAnswer(runId, stageId, handle, pendingRequest) {
+        const key = waitKey(runId, stageId);
+        const existing = this.live.get(key);
+        if (existing) {
+            existing.reject(new Error(`duplicate wait registration for ${runId}/${stageId}`));
+            this.live.delete(key);
+        }
+        return new Promise((resolve, reject) => {
+            this.live.set(key, { handle, pendingRequest, resolve, reject });
+        });
+    }
+    clearLiveWait(runId, stageId) {
+        const key = waitKey(runId, stageId);
+        const entry = this.live.get(key);
+        if (!entry)
+            return;
+        this.live.delete(key);
+        entry.reject(new Error("wait cancelled"));
+    }
+    /**
+     * Resolve pending for assert: live park map, else trail-derived T2 prompt.
+     * Non-T2 string fixtures yield undefined (assert pass-through).
+     */
+    async resolvePendingRequest(runId, stageId) {
+        const live = this.live.get(waitKey(runId, stageId));
+        if (live) {
+            return live.pendingRequest;
+        }
+        const attempt = await this.latestAttemptForStage(runId, stageId);
+        const events = await this.options.store.listStageEvents(runId, stageId, attempt);
+        const pending = derivePendingPrompt(events);
+        return pending ?? undefined;
+    }
+    /**
+     * KTD6 answer-deliver prefix for live and restart:
+     * resolve pending → assert → answer hook → resumed → live unpark or restart ok.
+     */
+    async deliverAnswerPrefix(runId, stageId, opaqueAnswer, attemptCtx) {
+        const key = waitKey(runId, stageId);
+        const live = this.live.get(key);
+        const attempt = attemptCtx?.attempt ?? (await this.latestAttemptForStage(runId, stageId));
+        const resolvedCtx = attemptCtx ?? attemptContext(attempt);
+        const pendingRequest = await this.resolvePendingRequest(runId, stageId);
+        try {
+            await this.assertAnswerMatchesPrompt({
+                runId,
+                stageId,
+                answer: opaqueAnswer,
+                pendingRequest,
+            });
+        }
+        catch (err) {
+            return {
+                ok: false,
+                reason: err instanceof Error ? err.message : String(err),
+                status: 400,
+            };
+        }
+        await this.qaHooks.onAnswerDeliver?.({
+            runId,
+            stageId,
+            answer: opaqueAnswer,
+            pendingRequest,
+            attempt,
+        });
+        await this.options.store.appendStageEvent(runId, stageId, {
+            event: "resumed",
+        }, this.attemptEventOptions(resolvedCtx.attempt));
+        if (live) {
+            this.live.delete(key);
+            live.handle.deliverAnswer(opaqueAnswer);
+            live.resolve();
+            return { ok: true, mode: "live" };
+        }
+        return { ok: true, mode: "restart" };
+    }
+}

package/dist/runtime/stageProcessLauncher.d.ts

@@ -0,0 +1,45 @@
+import type { OperatorCatalog } from "./stageAttemptBootstrap.js";
+export type StageLaunchInput = {
+    runId: string;
+    stageId: string;
+    rootDir: string;
+    mode?: "run" | "resume";
+    resumeAnswer?: unknown;
+    attempt?: number;
+    sessionFilePath?: string;
+    operatorCatalog?: OperatorCatalog;
+};
+export type StageLaunchResult = {
+    type: "succeeded";
+} | {
+    type: "failed";
+    reason: string;
+} | {
+    type: "waiting";
+};
+export type ActiveStageProcess = {
+    runId: string;
+    stageId: string;
+    startedAt: number;
+};
+export type StageProcessLauncherOptions = {
+    maxActiveStageProcesses?: number;
+    env?: Record<string, string | undefined>;
+    cliEntry?: string;
+};
+export declare class StageProcessLauncher {
+    private readonly maxActive;
+    private readonly env;
+    private readonly cliEntry;
+    private readonly active;
+    private readonly waitQueue;
+    private slotsHeld;
+    constructor(options?: StageProcessLauncherOptions);
+    activeCount(): number;
+    getActiveStageProcesses(): ActiveStageProcess[];
+    launch(input: StageLaunchInput): Promise<StageLaunchResult>;
+    cancelRun(runId: string, killAfterMs?: number): Promise<void>;
+    private waitForCapacity;
+    private releaseCapacity;
+    private spawnAndWait;
+}

package/dist/runtime/stageProcessLauncher.js

@@ -0,0 +1,199 @@
+import { fork } from "node:child_process";
+import { fileURLToPath } from "node:url";
+import { readMaxActiveStageProcesses, } from "./stageConcurrency.js";
+import { SF_STAGE_WORKER, STAGE_WORKER_EXIT, } from "./stageWorkerProtocol.js";
+function activeKey(runId, stageId) {
+    return `${runId}\0${stageId}`;
+}
+function isStageWorkerResult(value) {
+    if (!value || typeof value !== "object")
+        return false;
+    const type = value.type;
+    return type === "succeeded" || type === "failed" || type === "waiting";
+}
+function resultFromExitCode(code) {
+    if (code === STAGE_WORKER_EXIT.SUCCEEDED) {
+        return { type: "succeeded" };
+    }
+    if (code === STAGE_WORKER_EXIT.WAITING) {
+        return { type: "waiting" };
+    }
+    if (code === STAGE_WORKER_EXIT.FAILED) {
+        return { type: "failed", reason: "stage failed" };
+    }
+    return {
+        type: "failed",
+        reason: code === null ? "stage process exited" : `stage process exit ${code}`,
+    };
+}
+function resultFromWorkerMessage(msg) {
+    if (msg.type === "succeeded") {
+        return { type: "succeeded" };
+    }
+    if (msg.type === "waiting") {
+        return { type: "waiting" };
+    }
+    return { type: "failed", reason: msg.reason };
+}
+export class StageProcessLauncher {
+    maxActive;
+    env;
+    cliEntry;
+    active = new Map();
+    waitQueue = [];
+    slotsHeld = 0;
+    constructor(options = {}) {
+        this.env = options.env ?? process.env;
+        this.maxActive = readMaxActiveStageProcesses(this.env, options.maxActiveStageProcesses);
+        this.cliEntry =
+            options.cliEntry ??
+                fileURLToPath(new URL("../cli.js", import.meta.url));
+    }
+    activeCount() {
+        return this.active.size;
+    }
+    getActiveStageProcesses() {
+        return [...this.active.values()].map(({ runId, stageId, startedAt }) => ({
+            runId,
+            stageId,
+            startedAt,
+        }));
+    }
+    async launch(input) {
+        await this.waitForCapacity();
+        return this.spawnAndWait(input);
+    }
+    async cancelRun(runId, killAfterMs = 5000) {
+        const children = [...this.active.values()].filter((entry) => entry.runId === runId);
+        if (children.length === 0) {
+            return;
+        }
+        await Promise.all(children.map((entry) => new Promise((resolve) => {
+            const child = entry.child;
+            let settled = false;
+            const finish = () => {
+                if (settled)
+                    return;
+                settled = true;
+                resolve();
+            };
+            child.once("exit", finish);
+            child.kill("SIGTERM");
+            if (killAfterMs > 0) {
+                setTimeout(() => {
+                    if (!child.killed) {
+                        child.kill("SIGKILL");
+                    }
+                }, killAfterMs);
+            }
+        })));
+    }
+    async waitForCapacity() {
+        if (!Number.isFinite(this.maxActive)) {
+            return;
+        }
+        if (this.slotsHeld < this.maxActive) {
+            this.slotsHeld += 1;
+            return;
+        }
+        await new Promise((resolve) => {
+            this.waitQueue.push(resolve);
+        });
+        return this.waitForCapacity();
+    }
+    releaseCapacity() {
+        if (!Number.isFinite(this.maxActive)) {
+            return;
+        }
+        this.slotsHeld -= 1;
+        if (this.waitQueue.length > 0) {
+            const next = this.waitQueue.shift();
+            next?.();
+        }
+    }
+    spawnAndWait(input) {
+        const mode = input.mode ?? (input.resumeAnswer !== undefined ? "resume" : "run");
+        const args = [
+            "internal",
+            "run-stage",
+            "--run-id",
+            input.runId,
+            "--stage-id",
+            input.stageId,
+            "--mode",
+            mode,
+        ];
+        if (input.resumeAnswer !== undefined) {
+            args.push("--resume-answer", JSON.stringify(input.resumeAnswer));
+        }
+        if (input.attempt !== undefined) {
+            args.push("--attempt", String(input.attempt));
+        }
+        if (input.sessionFilePath !== undefined) {
+            args.push("--session-file", input.sessionFilePath);
+        }
+        if (input.operatorCatalog?.agentDir !== undefined) {
+            args.push("--operator-agent-dir", input.operatorCatalog.agentDir);
+        }
+        const child = fork(this.cliEntry, args, {
+            cwd: input.rootDir,
+            env: { ...process.env, ...this.env, [SF_STAGE_WORKER]: "1" },
+            stdio: ["pipe", "pipe", "pipe", "ipc"],
+        });
+        const key = activeKey(input.runId, input.stageId);
+        const tracked = {
+            child,
+            runId: input.runId,
+            stageId: input.stageId,
+            startedAt: Date.now(),
+        };
+        this.active.set(key, tracked);
+        if (child.stderr) {
+            let stderrBuffer = "";
+            child.stderr.on("data", (chunk) => {
+                stderrBuffer += chunk.toString();
+                const lines = stderrBuffer.split("\n");
+                stderrBuffer = lines.pop() ?? "";
+                for (const line of lines) {
+                    process.stderr.write(`[stage:${input.stageId}] ${line}\n`);
+                }
+            });
+            child.stderr.on("end", () => {
+                if (stderrBuffer.length > 0) {
+                    process.stderr.write(`[stage:${input.stageId}] ${stderrBuffer}\n`);
+                    stderrBuffer = "";
+                }
+            });
+        }
+        return new Promise((resolve) => {
+            let settled = false;
+            const cleanup = () => {
+                this.active.delete(key);
+                this.releaseCapacity();
+            };
+            const finish = (result) => {
+                if (settled)
+                    return;
+                settled = true;
+                cleanup();
+                resolve(result);
+            };
+            child.on("message", (message) => {
+                if (!isStageWorkerResult(message))
+                    return;
+                finish(resultFromWorkerMessage(message));
+            });
+            child.on("exit", (code) => {
+                if (settled)
+                    return;
+                finish(resultFromExitCode(code));
+            });
+            child.on("error", (err) => {
+                finish({
+                    type: "failed",
+                    reason: err instanceof Error ? err.message : String(err),
+                });
+            });
+        });
+    }
+}

package/dist/runtime/stageRecovery.d.ts

@@ -0,0 +1,10 @@
+import type { RunStore } from "../runstore/port.js";
+import { type StageAttemptContext } from "./stageAttemptContext.js";
+export declare function failStageAsInterrupted(options: {
+    store: RunStore;
+    runId: string;
+    stageId: string;
+    reason: string;
+    attemptCtx?: StageAttemptContext;
+}): Promise<void>;
+export declare function syncRunStatusFromStages(store: RunStore, runId: string): Promise<void>;

package/dist/runtime/stageRecovery.js

@@ -0,0 +1,43 @@
+import { deriveStatusFromStages } from "../runstore/port.js";
+import { deriveExecutionPatchFromEvent } from "../runstore/stageExecution.js";
+import { attemptContext, } from "./stageAttemptContext.js";
+export async function failStageAsInterrupted(options) {
+    const { store, runId, stageId, reason, attemptCtx } = options;
+    let attemptNum;
+    let attemptOpt;
+    if (attemptCtx !== undefined) {
+        attemptNum = attemptCtx.attempt;
+        attemptOpt = attemptCtx.eventOptions();
+    }
+    else {
+        const latest = await store.getLatestStageExecution(runId, stageId);
+        if (latest !== null) {
+            attemptNum = latest.attempt;
+            attemptOpt = attemptContext(latest.attempt).eventOptions();
+        }
+        else {
+            attemptNum = 1;
+            attemptOpt = undefined;
+        }
+    }
+    const event = { event: "failed", reason };
+    await store.appendStageEvent(runId, stageId, event, attemptOpt);
+    try {
+        const execution = await store.getStageExecution(runId, stageId, attemptNum);
+        const patch = deriveExecutionPatchFromEvent(event, execution);
+        if (Object.keys(patch).length === 0)
+            return;
+        await store.updateStageExecution(runId, stageId, attemptNum, patch);
+    }
+    catch {
+        // no execution row yet
+    }
+}
+export async function syncRunStatusFromStages(store, runId) {
+    const run = await store.readRun(runId);
+    const derived = deriveStatusFromStages(run.stages);
+    const meta = await store.readRunMeta(runId);
+    if ((meta.status ?? "created") !== derived) {
+        await store.updateRunStatus(runId, derived);
+    }
+}