@osolmaz/pi-workflows 0.2.0 → 0.4.0

package/src/workflows/engine.ts

@@ -1,10 +1,20 @@
 import { randomUUID } from "node:crypto";
 import { isDeepStrictEqual } from "node:util";
-import { CancelledError, errorMessage, isAbortLikeError, TimeoutError } from "./errors.js";
+import { resolveArtifacts } from "./artifacts.js";
+import {
+  CancelledError,
+  errorMessage,
+  isAbortLikeError,
+  isClaimLostError,
+  isRunParkedError,
+  RunParkedError,
+  TimeoutError,
+  WorkflowSourceChangedError,
+} from "./errors.js";
 import { resolveNext, resolveNextForOutcome, validateWorkflowDefinition } from "./graph.js";
 import { extractJsonValue } from "./json.js";
 import { runShellAction, shellResultFromError } from "./shell.js";
-import { RUN_STATE_SCHEMA, WorkflowRunStore, createRunId } from "./store.js";
+import { RUN_STATE_SCHEMA, WorkflowRunStore, createRunId, readRunBundle } from "./store.js";
 import type {
   AgentNodeDefinition,
   AgentStepExecutor,
@@ -22,6 +32,7 @@ import type {
   WorkflowNodeResult,
   WorkflowRunResult,
   WorkflowRunState,
+  WorkflowSource,
   WorkflowStepRecord,
   WorkflowTraceEventDraft,
 } from "./types.js";
@@ -29,6 +40,7 @@ import type {
 const DEFAULT_NODE_TIMEOUT_MS = 15 * 60_000;
 const DEFAULT_MAX_STEPS = 100;
 const TITLE_TIMEOUT_MS = 30_000;
+const TIMEOUT_RESOLUTION_TIMEOUT_MS = 30_000;
 // Covers the shell SIGTERM → SIGKILL escalation (1s) plus stdio close.
 const ABORT_CLEANUP_GRACE_MS = 2_000;
 
@@ -70,6 +82,7 @@ export class WorkflowEngine {
   private readonly onRunFinishing?: WorkflowEngineOptions["onRunFinishing"];
   private activeAbort: AbortController | null = null;
   private cancelled = false;
+  private parked = false;
   private paused = false;
   private wakePause: (() => void) | null = null;
 
@@ -96,6 +109,17 @@ export class WorkflowEngine {
     this.wakePause?.();
   }
 
+  /**
+   * Stop without a terminal event so another runner can claim and resume
+   * the run. The active node aborts; its partial attempt is never recorded,
+   * so resume reruns that node from its last persisted boundary.
+   */
+  park(): void {
+    this.parked = true;
+    this.activeAbort?.abort(new CancelledError());
+    this.wakePause?.();
+  }
+
   /**
    * Request a pause. The current step finishes normally; the engine then
    * holds before dispatching the next node until `resume` (or `cancel`).
@@ -118,17 +142,26 @@ export class WorkflowEngine {
   async run(
     workflow: WorkflowDefinition,
     input: unknown,
-    options: { workflowPath?: string } = {},
+    options: { workflowSource?: WorkflowSource; runId?: string } = {},
   ): Promise<WorkflowRunResult> {
     validateWorkflowDefinition(workflow);
     // Fail before any bundle exists so bad input cannot leave a partial run
     // on disk or silently change shape when state.json round-trips.
     const normalizedInput = input === undefined ? null : input;
     assertJsonSerializable(normalizedInput, "Workflow run input");
+    if (options.runId !== undefined && !/^[A-Za-z0-9][A-Za-z0-9._-]{0,199}$/.test(options.runId)) {
+      throw new Error(`Invalid workflow run id: ${JSON.stringify(options.runId)}`);
+    }
     this.cancelled = false;
     this.paused = false;
+    this.parked = false;
 
-    const state = await this.createRunState(workflow, normalizedInput, options.workflowPath);
+    const state = await this.createRunState(
+      workflow,
+      normalizedInput,
+      options.workflowSource,
+      options.runId,
+    );
     const runDir = await this.store.initializeRunBundle(workflow, state);
     await this.persist(runDir, state, {
       scope: "run",
@@ -147,13 +180,266 @@ export class WorkflowEngine {
     try {
       await this.executeGraph(workflow, state, runDir);
     } catch (error) {
-      const cancelled = this.cancelled || isAbortLikeError(error);
+      if (isRunParkedError(error) || this.parked) {
+        return { runDir, state };
+      }
+      await this.finishAfterError(runDir, state, error);
+      return { runDir, state };
+    }
+    return { runDir, state };
+  }
+
+  /**
+   * Resume an interrupted run at the node it stopped on. The caller must
+   * hold the run's queue claim. Completed nodes replay from the recorded
+   * state; only the interrupted node and everything downstream rerun.
+   */
+  async resumeRun(
+    workflow: WorkflowDefinition,
+    runId: string,
+    options: { workflowSource?: WorkflowSource; force?: boolean } = {},
+  ): Promise<WorkflowRunResult> {
+    validateWorkflowDefinition(workflow);
+    // Reset before any await: a park or cancel landing during preparation
+    // must survive, or a host drain would hang while the run executes.
+    this.cancelled = false;
+    this.paused = false;
+    this.parked = false;
+    const bundle = await this.store.prepareRunResume(runId);
+    const { runDir } = bundle;
+    const state = bundle.state;
+    const sourceMismatch = workflowSourceMismatch(state, options.workflowSource);
+    if (sourceMismatch && options.force !== true) {
+      throw new WorkflowSourceChangedError(runId);
+    }
+
+    const point = this.resumePointFor(workflow, state, "wait");
+    // A resumed run starts unpaused; the operator can pause again. The
+    // interrupted node's stale in-flight markers go away before the resume
+    // event so the projection matches what the engine is about to do.
+    delete state.paused;
+    delete state.currentNode;
+    delete state.currentAttemptId;
+    delete state.currentNodeStartedAt;
+    delete state.statusDetail;
+    await this.persist(runDir, state, {
+      scope: "run",
+      type: "run_resumed",
+      payload: {
+        ...(point.nodeId !== null ? { resumeAt: point.nodeId } : {}),
+        replayedSteps: state.steps.length,
+        ...(sourceMismatch ? { workflowSourceMismatch: true, forced: true } : {}),
+      },
+    });
+    await this.onRunStarted?.(runDir, state);
+
+    if (point.nodeId === null) {
+      // The last recorded transition already finished the graph; the crash
+      // happened before the terminal event was written. A finished
+      // checkpoint restores its waiting gate rather than completing.
+      if (point.waitingOn !== undefined) {
+        await this.finishRun(runDir, state, "waiting", {
+          waitingOn: point.waitingOn,
+          finalOutput: point.lastOutput,
+        });
+      } else if (point.failedResult === undefined) {
+        await this.finishRun(runDir, state, "completed", { finalOutput: point.lastOutput });
+      } else {
+        const timedOut = point.failedResult.outcome === "timed_out";
+        await this.finishRun(runDir, state, timedOut ? "timed_out" : "failed", {
+          error: point.failedResult.error ?? `Workflow node failed: ${point.failedResult.nodeId}`,
+        });
+      }
+      return { runDir, state };
+    }
+
+    try {
+      await this.executeGraph(
+        workflow,
+        state,
+        runDir,
+        point.nodeId,
+        state.steps.length,
+        point.lastOutput,
+      );
+    } catch (error) {
+      if (isRunParkedError(error) || this.parked) {
+        return { runDir, state };
+      }
+      await this.finishAfterError(runDir, state, error);
+      return { runDir, state };
+    }
+    return { runDir, state };
+  }
+
+  /**
+   * Start a continuation run from a checkpointed parent. The new run gets a
+   * fresh bundle and trace, carries forward the parent's outputs, results,
+   * and step accounting, and continues routing after the checkpoint.
+   */
+  async continueRun(
+    workflow: WorkflowDefinition,
+    parentRunId: string,
+    input: unknown,
+    options: { workflowSource?: WorkflowSource; runId?: string; force?: boolean } = {},
+  ): Promise<WorkflowRunResult> {
+    validateWorkflowDefinition(workflow);
+    this.cancelled = false;
+    this.paused = false;
+    this.parked = false;
+    const parent = await readRunBundle(this.store.runDirFor(parentRunId));
+    if (parent === null) {
+      throw new Error(`Cannot continue from unreadable workflow run: ${parentRunId}`);
+    }
+    if (parent.state.status !== "waiting" || parent.state.waitingOn === undefined) {
+      throw new Error(
+        `Cannot continue workflow run ${parentRunId} with status ${parent.state.status}`,
+      );
+    }
+    const sourceMismatch = workflowSourceMismatch(parent.state, options.workflowSource);
+    if (sourceMismatch && options.force !== true) {
+      throw new WorkflowSourceChangedError(parentRunId);
+    }
+
+    const normalizedInput = input === undefined ? null : input;
+    assertJsonSerializable(normalizedInput, "Workflow run input");
+    if (options.runId !== undefined && !/^[A-Za-z0-9][A-Za-z0-9._-]{0,199}$/.test(options.runId)) {
+      throw new Error(`Invalid workflow run id: ${JSON.stringify(options.runId)}`);
+    }
+
+    const state = await this.createRunState(
+      workflow,
+      normalizedInput,
+      options.workflowSource,
+      options.runId,
+    );
+    state.parentRunId = parentRunId;
+    // Artifact references point into the parent's bundle, so carried values
+    // are fully resolved here and re-externalized into the new bundle.
+    state.outputs = (await resolveArtifacts(
+      parent.state.outputs,
+      parent.runDir,
+    )) as WorkflowRunState["outputs"];
+    state.results = (await resolveArtifacts(
+      parent.state.results,
+      parent.runDir,
+    )) as WorkflowRunState["results"];
+    state.steps = (await resolveArtifacts(
+      parent.state.steps,
+      parent.runDir,
+    )) as WorkflowRunState["steps"];
+    state.carriedStepCount = state.steps.length;
+
+    const runDir = await this.store.initializeRunBundle(workflow, state);
+    await this.persist(runDir, state, {
+      scope: "run",
+      type: "run_started",
+      payload: {
+        workflowName: workflow.name,
+        ...(state.runTitle ? { runTitle: state.runTitle } : {}),
+        input: state.input,
+        continuedFrom: parentRunId,
+        checkpoint: parent.state.waitingOn,
+        carriedSteps: state.steps.length,
+      },
+    });
+    await this.onRunStarted?.(runDir, state);
+
+    const point = this.resumePointFor(workflow, state, "continue");
+    if (point.nodeId === null) {
+      // The checkpoint was the final node; the answer completes the chain.
+      await this.finishRun(runDir, state, "completed", { finalOutput: point.lastOutput });
+      return { runDir, state };
+    }
+    try {
+      await this.executeGraph(
+        workflow,
+        state,
+        runDir,
+        point.nodeId,
+        state.steps.length,
+        point.lastOutput,
+      );
+    } catch (error) {
+      if (isRunParkedError(error) || this.parked) {
+        return { runDir, state };
+      }
+      await this.finishAfterError(runDir, state, error);
+      return { runDir, state };
+    }
+    return { runDir, state };
+  }
+
+  /**
+   * Find where a resumed run continues. An in-flight node reruns; otherwise
+   * routing continues from the last recorded step. A null nodeId means the
+   * graph was already done when the crash hit.
+   */
+  private resumePointFor(
+    workflow: WorkflowDefinition,
+    state: WorkflowRunState,
+    checkpointBehavior: "wait" | "continue",
+  ): {
+    nodeId: string | null;
+    lastOutput?: unknown;
+    failedResult?: WorkflowNodeResult;
+    waitingOn?: string;
+  } {
+    if (state.currentNode !== undefined) {
+      if (workflow.nodes[state.currentNode] === undefined) {
+        throw new Error(`Resume node is missing from the workflow: ${state.currentNode}`);
+      }
+      return { nodeId: state.currentNode };
+    }
+    const lastStep = state.steps.at(-1);
+    if (lastStep === undefined) {
+      return { nodeId: workflow.startAt };
+    }
+    const result = state.results[lastStep.nodeId];
+    if (result === undefined) {
+      return { nodeId: lastStep.nodeId };
+    }
+    if (result.outcome === "ok") {
+      // A recorded checkpoint means the run should be waiting; a crash
+      // before the run_waiting persist restores the gate instead of
+      // routing past it. The gate applies to this run's own checkpoint
+      // only: a continuation's carried steps end with the parent's
+      // already-answered checkpoint, and routing must continue from it.
+      const isCarriedStep = state.steps.length <= (state.carriedStepCount ?? 0);
+      if (
+        checkpointBehavior === "wait" &&
+        !isCarriedStep &&
+        workflow.nodes[lastStep.nodeId]?.nodeType === "checkpoint"
+      ) {
+        return { nodeId: null, waitingOn: lastStep.nodeId, lastOutput: result.output };
+      }
+      const next = resolveNext(workflow.edges, lastStep.nodeId, result.output, result);
+      return next === null
+        ? { nodeId: null, lastOutput: result.output }
+        : { nodeId: next, lastOutput: result.output };
+    }
+    const next = resolveNextForOutcome(workflow.edges, lastStep.nodeId, result);
+    return next === null ? { nodeId: null, failedResult: result } : { nodeId: next };
+  }
+
+  private async finishAfterError(
+    runDir: string,
+    state: WorkflowRunState,
+    error: unknown,
+  ): Promise<void> {
+    const cancelled = this.cancelled || isAbortLikeError(error);
+    try {
       await this.finishRun(runDir, state, cancelled ? "cancelled" : "failed", {
         error: errorMessage(error),
       });
-      return { runDir, state };
+    } catch (finishError) {
+      // A fenced-out runner must not touch the bundle, including terminal
+      // projections. Propagate the claim loss instead of the node error.
+      if (isClaimLostError(finishError)) {
+        throw finishError;
+      }
+      throw error;
     }
-    return { runDir, state };
   }
 
   /**
@@ -185,16 +471,17 @@ export class WorkflowEngine {
   private async createRunState(
     workflow: WorkflowDefinition,
     input: unknown,
-    workflowPath: string | undefined,
+    workflowSource: WorkflowSource | undefined,
+    runId: string | undefined,
   ): Promise<WorkflowRunState> {
     const now = new Date().toISOString();
     return {
       schema: RUN_STATE_SCHEMA,
       traceSeq: 0,
-      runId: createRunId(workflow.name),
+      runId: runId ?? createRunId(workflow.name),
       workflowName: workflow.name,
       ...(await this.resolveTitleBounded(workflow, input)),
-      ...(workflowPath !== undefined ? { workflowPath } : {}),
+      ...(workflowSource !== undefined ? { workflowSource } : {}),
       startedAt: now,
       updatedAt: now,
       status: "running",
@@ -209,11 +496,14 @@ export class WorkflowEngine {
     workflow: WorkflowDefinition,
     state: WorkflowRunState,
     runDir: string,
+    startNodeId: string | null = workflow.startAt,
+    executedStepsBase = 0,
+    initialLastOutput?: unknown,
   ): Promise<void> {
     const maxSteps = workflow.maxSteps ?? this.maxSteps;
-    let currentNodeId: string | null = workflow.startAt;
-    let executedSteps = 0;
-    let lastOutput: unknown;
+    let currentNodeId: string | null = startNodeId;
+    let executedSteps = executedStepsBase;
+    let lastOutput: unknown = initialLastOutput;
 
     while (currentNodeId !== null) {
       await this.holdWhilePaused(state, runDir);
@@ -230,6 +520,11 @@ export class WorkflowEngine {
       }
 
       const attempt = await this.executeNode(workflow, state, runDir, currentNodeId, node);
+      if (this.parked) {
+        // Do not record the aborted attempt: the projection keeps the node
+        // as in-flight, and resume reruns it with a fresh attempt.
+        throw new RunParkedError();
+      }
       this.recordAttempt(state, attempt);
       // The terminal node event carries the output, receipt, and conversation
       // linkage so the trace alone is sufficient to reconstruct the run.
@@ -279,6 +574,9 @@ export class WorkflowEngine {
    * never interrupts a node mid-flight; it only delays the next dispatch.
    */
   private async holdWhilePaused(state: WorkflowRunState, runDir: string): Promise<void> {
+    if (this.parked) {
+      throw new RunParkedError();
+    }
     if (this.cancelled) {
       throw new CancelledError();
     }
@@ -287,12 +585,15 @@ export class WorkflowEngine {
     }
     state.paused = true;
     await this.persist(runDir, state, { scope: "run", type: "run_paused", payload: {} });
-    while (this.paused && !this.cancelled) {
+    while (this.paused && !this.cancelled && !this.parked) {
       await new Promise<void>((resolve) => {
         this.wakePause = resolve;
       });
     }
     this.wakePause = null;
+    if (this.parked) {
+      throw new RunParkedError();
+    }
     delete state.paused;
     if (this.cancelled) {
       throw new CancelledError();
@@ -449,31 +750,43 @@ export class WorkflowEngine {
     node: WorkflowNodeDefinition,
     meta: NodeExecutionMeta,
   ): Promise<NodeExecution> {
-    const timeoutMs = node.timeoutMs ?? this.defaultNodeTimeoutMs;
     const abort = new AbortController();
+    const context = this.createNodeContext(state, abort.signal);
+    let timer: NodeJS.Timeout | undefined;
+    let dispatchSettled: Promise<void> | undefined;
     this.activeAbort = abort;
-    if (this.cancelled) {
-      throw new CancelledError();
-    }
-
-    const timer = setTimeout(() => {
-      abort.abort(new TimeoutError(timeoutMs));
-    }, timeoutMs);
-    const dispatched = this.dispatchNode(
-      workflow,
-      state,
-      runDir,
-      nodeId,
-      attemptId,
-      node,
-      abort.signal,
-      meta,
-    );
-    const dispatchSettled = dispatched.then(
-      () => undefined,
-      () => undefined,
-    );
     try {
+      if (this.parked) {
+        // A park that landed during the node_started persist must not let the
+        // node dispatch: its discarded side effects would rerun on resume.
+        throw new RunParkedError();
+      }
+      if (this.cancelled) {
+        throw new CancelledError();
+      }
+
+      const timeoutMs = await this.resolveNodeTimeout(node, context, abort);
+      if (abort.signal.aborted) {
+        throw abortError(abort.signal);
+      }
+      timer = setTimeout(() => {
+        abort.abort(new TimeoutError(timeoutMs));
+      }, timeoutMs);
+      const dispatched = this.dispatchNode(
+        workflow,
+        state,
+        runDir,
+        nodeId,
+        attemptId,
+        node,
+        context,
+        abort.signal,
+        meta,
+      );
+      dispatchSettled = dispatched.then(
+        () => undefined,
+        () => undefined,
+      );
       // Race the dispatch against the abort signal so timeouts and cancel
       // take effect even for node callbacks that never observe the signal.
       const execution = await Promise.race([dispatched, abortRejection(abort.signal)]);
@@ -485,7 +798,7 @@ export class WorkflowEngine {
       assertJsonSerializable(execution.output, `Node ${nodeId} output`);
       return execution;
     } catch (error) {
-      if (node.nodeType === "action" && "exec" in node) {
+      if (node.nodeType === "action" && "exec" in node && dispatchSettled !== undefined) {
         // Give the killed shell command a short grace period to close so its
         // action receipt lands in `meta` before the failed attempt persists.
         await Promise.race([
@@ -495,9 +808,37 @@ export class WorkflowEngine {
       }
       const reason: unknown = abort.signal.aborted ? abort.signal.reason : undefined;
       throw reason instanceof TimeoutError || reason instanceof CancelledError ? reason : error;
+    } finally {
+      if (timer !== undefined) {
+        clearTimeout(timer);
+      }
+      if (this.activeAbort === abort) {
+        this.activeAbort = null;
+      }
+    }
+  }
+
+  private async resolveNodeTimeout(
+    node: WorkflowNodeDefinition,
+    context: WorkflowNodeContext,
+    abort: AbortController,
+  ): Promise<number> {
+    const configured = node.timeoutMs;
+    if (typeof configured !== "function") {
+      return assertValidTimeout(configured ?? this.defaultNodeTimeoutMs);
+    }
+    const timer = setTimeout(
+      () => abort.abort(new TimeoutError(TIMEOUT_RESOLUTION_TIMEOUT_MS)),
+      TIMEOUT_RESOLUTION_TIMEOUT_MS,
+    );
+    try {
+      const resolved = await Promise.race([
+        Promise.resolve(configured(context)),
+        abortRejection(abort.signal),
+      ]);
+      return assertValidTimeout(resolved);
     } finally {
       clearTimeout(timer);
-      this.activeAbort = null;
     }
   }
 
@@ -508,10 +849,10 @@ export class WorkflowEngine {
     nodeId: string,
     attemptId: string,
     node: WorkflowNodeDefinition,
+    context: WorkflowNodeContext,
     signal: AbortSignal,
     meta: NodeExecutionMeta,
   ): Promise<NodeExecution> {
-    const context = this.createNodeContext(state, signal);
     switch (node.nodeType) {
       case "agent":
         return await this.runAgentNode(
@@ -730,7 +1071,13 @@ async function runShellActionNode(
   return { output, promptText: null, action: shellReceipt(result) };
 }
 
-/** Rejects with the abort reason once the signal fires; never resolves. */
+function assertValidTimeout(value: number): number {
+  if (!Number.isFinite(value) || value <= 0) {
+    throw new Error("Node timeoutMs must resolve to a finite positive number");
+  }
+  return value;
+}
+
 /** The error carried by an aborted signal, normalized to an Error. */
 function abortError(signal: AbortSignal): Error {
   const reason: unknown = signal.reason ?? new CancelledError();
@@ -755,6 +1102,22 @@ function abortRejection(signal: AbortSignal): Promise<never> {
  * Failing here turns a bad callback return value into a normal node failure
  * instead of corrupting the run state.
  */
+function workflowSourceMismatch(
+  state: WorkflowRunState,
+  source: WorkflowSource | undefined,
+): boolean {
+  if (source === undefined) return false;
+  if (state.workflowSource !== undefined) {
+    return !isDeepStrictEqual(state.workflowSource, source);
+  }
+  // Bounded compatibility check for pre-catalog file runs. Startup normally
+  // converts these records with migrateLegacyWorkflowSources first.
+  return (
+    state.workflowHash !== undefined &&
+    (source.kind !== "file" || state.workflowHash !== source.hash)
+  );
+}
+
 function assertJsonSerializable(value: unknown, what: string): void {
   let encoded: string | undefined;
   try {
@@ -803,7 +1166,7 @@ export function appendStepContract(
     `Workflow step contract (workflow: ${workflowName}, step: ${nodeId}, attempt: ${attemptId})`,
     "",
     "Complete this step by calling the `workflow` tool exactly once with:",
-    `{"step": ${JSON.stringify(nodeId)}, "attempt": ${JSON.stringify(attemptId)}, "output": <your result>}`,
+    `{"action": "submit", "step": ${JSON.stringify(nodeId)}, "attempt": ${JSON.stringify(attemptId)}, "output": <your result>}`,
     `Expected output: ${expectedOutput ?? "a JSON object with your result"}`,
     "The step is complete only after the workflow tool accepts the output.",
     "If the tool reports a validation error, correct the output and call it again.",

package/src/workflows/errors.ts

@@ -15,6 +15,51 @@ export class CancelledError extends Error {
   }
 }
 
+/**
+ * Thrown when a runner writes to a run bundle after losing its queue claim.
+ * The current claim holder owns the run from that point on, so the fenced
+ * writer must stop touching the bundle immediately.
+ */
+export class ClaimLostError extends Error {
+  readonly runId: string;
+
+  constructor(runId: string) {
+    super(`Workflow run claim lost: ${runId}`);
+    this.name = "ClaimLostError";
+    this.runId = runId;
+  }
+}
+
+/**
+ * Internal stop signal for close-to-park: the engine halts without writing
+ * a terminal event, leaving a resumable bundle for the next claim holder.
+ */
+export class RunParkedError extends Error {
+  constructor() {
+    super("Workflow run was parked");
+    this.name = "RunParkedError";
+  }
+}
+
+export function isRunParkedError(error: unknown): error is RunParkedError {
+  return error instanceof RunParkedError;
+}
+
+/** The workflow source changed after the run started; resume needs force. */
+export class WorkflowSourceChangedError extends Error {
+  readonly runId: string;
+
+  constructor(runId: string) {
+    super(`Workflow source changed since run ${runId} started; pass force to resume anyway`);
+    this.name = "WorkflowSourceChangedError";
+    this.runId = runId;
+  }
+}
+
+export function isClaimLostError(error: unknown): error is ClaimLostError {
+  return error instanceof ClaimLostError;
+}
+
 export function isAbortLikeError(error: unknown): boolean {
   return error instanceof CancelledError || (error instanceof Error && error.name === "AbortError");
 }

package/src/workflows/graph.ts

@@ -58,11 +58,6 @@ function validateWorkflowEdge(
   outgoingEdges: Set<string>,
 ): void {
   assertKnownNode(workflow, edge.from, "Workflow edge references unknown from-node");
-  if (workflow.nodes[edge.from]?.nodeType === "checkpoint") {
-    // A checkpoint terminates the run as `waiting` and nothing resumes it,
-    // so an outgoing edge would make its targets silently unreachable.
-    throw new Error(`Workflow checkpoint node must not declare an outgoing edge: ${edge.from}`);
-  }
   if (outgoingEdges.has(edge.from)) {
     throw new Error(`Workflow node must not declare multiple outgoing edges: ${edge.from}`);
   }

package/src/workflows/index.ts

@@ -21,6 +21,7 @@ export {
   discoverWorkflows,
   loadWorkflowFile,
   resolveWorkflowRef,
+  resolveWorkflowSource,
   workflowFileStem,
   workflowSearchDirs,
   type DiscoveredWorkflow,
@@ -83,6 +84,7 @@ export type {
   WorkflowRunResult,
   WorkflowRunState,
   WorkflowRunStatus,
+  WorkflowSource,
   WorkflowSessionBinding,
   WorkflowSessionEntryRecord,
   WorkflowStepRecord,