@multiplier-labs/stepflow 0.3.4 → 0.3.8

package/src/core/orchestrator/persistence.ts

@@ -1,165 +0,0 @@
-/**
- * Orchestrator persistence layer.
- *
- * Wraps the storage adapter and event transport with intent-named helpers
- * so the orchestrator and step-runner can stay focused on control flow
- * instead of repeating field shapes for every status transition.
- *
- * All side-effect calls the orchestrator makes against storage or the event
- * transport flow through this module — keeping the rest of the pipeline
- * pure(-ish) and easy to read.
- */
-import type { StorageAdapter, WorkflowRunStepRecord } from '../../storage/types';
-import type { EventTransport, WorkflowEvent } from '../../events/types';
-import type { Logger, WorkflowError } from '../types';
-import { WorkflowEngineError } from '../../utils/errors';
-
-/**
- * Mark the run as running. On a fresh start, also stamp `startedAt`;
- * on resume, leave the original `startedAt` alone.
- */
-export async function markRunRunning(
-  storage: StorageAdapter,
-  runId: string,
-  isResume: boolean
-): Promise<void> {
-  await storage.updateRun(runId, {
-    status: 'running',
-    ...(isResume ? {} : { startedAt: new Date() }),
-  });
-}
-
-/**
- * Persist the workflow checkpoint after a step completes:
- * the accumulated step results plus the list of completed step keys.
- */
-export async function saveCheckpoint(
-  storage: StorageAdapter,
-  runId: string,
-  results: Record<string, unknown>,
-  completedSteps: string[]
-): Promise<void> {
-  await storage.updateRun(runId, {
-    context: { ...results },
-    completedSteps: [...completedSteps],
-  });
-}
-
-/**
- * Mark the run as succeeded, persisting results and finishedAt.
- */
-export async function markRunSucceeded(
-  storage: StorageAdapter,
-  runId: string,
-  results: Record<string, unknown>
-): Promise<void> {
-  await storage.updateRun(runId, {
-    status: 'succeeded',
-    context: results,
-    finishedAt: new Date(),
-  });
-}
-
-/**
- * Persist a non-success terminal state for the run (failed / canceled / timeout).
- * `status` is the storage-level status — the orchestrator decides this from the
- * raised error using `state-transitions.ts`.
- */
-export async function markRunFinal(
-  storage: StorageAdapter,
-  runId: string,
-  status: 'failed' | 'canceled',
-  results: Record<string, unknown>,
-  error: WorkflowError
-): Promise<void> {
-  await storage.updateRun(runId, {
-    status,
-    context: results,
-    error,
-    finishedAt: new Date(),
-  });
-}
-
-/**
- * Create a fresh step record in 'running' state for the given attempt.
- * Returns the persisted record so the caller can read its generated id.
- */
-export async function createStepRecord(
-  storage: StorageAdapter,
-  runId: string,
-  stepKey: string,
-  stepName: string,
-  attempt: number
-): Promise<WorkflowRunStepRecord> {
-  return storage.createStep({
-    runId,
-    stepKey,
-    stepName,
-    status: 'running',
-    attempt,
-    startedAt: new Date(),
-  });
-}
-
-/**
- * Mark a step as succeeded, recording its result and finishedAt.
- */
-export async function markStepSucceeded(
-  storage: StorageAdapter,
-  stepId: string,
-  result: unknown
-): Promise<void> {
-  await storage.updateStep(stepId, {
-    status: 'succeeded',
-    result,
-    finishedAt: new Date(),
-  });
-}
-
-/**
- * Mark a step as failed (or canceled, if the abort signal already fired)
- * with the normalized engine error attached.
- */
-export async function markStepFailed(
-  storage: StorageAdapter,
-  stepId: string,
-  error: unknown,
-  isCanceled: boolean
-): Promise<void> {
-  await storage.updateStep(stepId, {
-    status: isCanceled ? 'canceled' : 'failed',
-    error: WorkflowEngineError.fromError(error),
-    finishedAt: new Date(),
-  });
-}
-
-/**
- * Mark a step as canceled without an error payload — used when an in-flight
- * retry sleep is interrupted by an abort signal.
- */
-export async function markStepCanceled(
-  storage: StorageAdapter,
-  stepId: string
-): Promise<void> {
-  await storage.updateStep(stepId, {
-    status: 'canceled',
-    finishedAt: new Date(),
-  });
-}
-
-/**
- * Emit a workflow event without ever throwing back into the caller.
- * Event emission failures are logged but never abort the workflow,
- * so a flaky transport can't take down a run.
- */
-export function safeEmitEvent(
-  events: EventTransport,
-  logger: Logger,
-  event: WorkflowEvent
-): void {
-  try {
-    events.emit(event);
-  } catch (error) {
-    logger.error('Failed to emit event:', error);
-  }
-}

package/src/core/orchestrator/plan-resolution.ts

@@ -1,140 +0,0 @@
-/**
- * Plan resolution — turns ExecuteOptions into the runtime artefacts
- * the orchestrator needs to start running steps.
- *
- * Today the engine has no separate planner module: the "plan" is just the
- * declarative WorkflowDefinition combined with the optional resume
- * checkpoint and the supplied input/metadata. This module is the seam
- * where, in the future, recipe/plan resolution and input validation can
- * grow without bloating execute-workflow.ts.
- *
- * Responsibilities:
- *   1. Build the WorkflowContext from the run options + checkpoint, with a
- *      `context.emit` helper that routes through safeEmitEvent.
- *   2. Set up the workflow-level timeout: returns a handle the caller
- *      clears in both the success and failure paths, and a getter for
- *      the WorkflowTimeoutError that fired (so the catch block can
- *      surface it instead of the abort-derived error).
- *   3. Compute the initial set of completed-step keys (used by the loop
- *      to skip steps already done in a previous run).
- */
-import type {
-  WorkflowDefinition,
-  WorkflowContext,
-  Logger,
-  SpawnChildOptions,
-} from '../types';
-import type { EventTransport } from '../../events/types';
-import { WorkflowTimeoutError } from '../../utils/errors';
-import { createScopedLogger } from '../../utils/logger';
-import { safeEmitEvent } from './persistence';
-
-/**
- * Inputs needed to resolve a workflow plan + build its execution context.
- */
-export interface BuildContextOptions {
-  runId: string;
-  definition: WorkflowDefinition;
-  input: Record<string, unknown>;
-  metadata: Record<string, unknown>;
-  events: EventTransport;
-  logger: Logger;
-  abortController: AbortController;
-  spawnChild: (options: SpawnChildOptions) => Promise<string>;
-  /** Existing checkpoint results to preload into context.results. */
-  checkpointResults?: Record<string, unknown>;
-}
-
-/**
- * Build the WorkflowContext that will be threaded through every step
- * handler. On resume, preload `context.results` from the checkpoint.
- */
-export function buildContext(options: BuildContextOptions): WorkflowContext {
-  const {
-    runId,
-    definition,
-    input,
-    metadata,
-    events,
-    logger,
-    abortController,
-    spawnChild,
-    checkpointResults,
-  } = options;
-
-  return {
-    runId,
-    stepId: '', // set per-step by the step-runner before each handler call
-    kind: definition.kind,
-    input,
-    results: checkpointResults ? { ...checkpointResults } : {},
-    metadata,
-    logger: createScopedLogger(logger, runId),
-    signal: abortController.signal,
-    spawnChild,
-    emit: (eventType: string, payload?: unknown) => {
-      safeEmitEvent(events, logger, {
-        runId,
-        kind: definition.kind,
-        eventType,
-        timestamp: new Date(),
-        payload,
-      });
-    },
-  };
-}
-
-/**
- * Handle returned by setupWorkflowTimeout. The orchestrator must call
- * `clear()` on both success and failure paths to release the timer, and
- * may read `getTimeoutError()` in the catch path: if non-null, the abort
- * was triggered by our timeout (not user cancellation), and the caller
- * should surface that error instead of the generic abort-derived one.
- */
-export interface WorkflowTimeoutHandle {
-  clear: () => void;
-  getTimeoutError: () => WorkflowTimeoutError | undefined;
-}
-
-/**
- * Arm a workflow-level timeout if the definition specifies one.
- *
- * On fire: constructs a WorkflowTimeoutError (recoverable via
- * `getTimeoutError`) and aborts the controller, which causes any
- * in-flight step handler racing the abort signal to reject.
- *
- * If the definition has no timeout, returns no-op handles.
- */
-export function setupWorkflowTimeout(
-  runId: string,
-  definition: WorkflowDefinition,
-  abortController: AbortController
-): WorkflowTimeoutHandle {
-  if (!definition.timeout) {
-    return {
-      clear: () => {},
-      getTimeoutError: () => undefined,
-    };
-  }
-
-  let timeoutError: WorkflowTimeoutError | undefined;
-  const timeoutId = setTimeout(() => {
-    timeoutError = new WorkflowTimeoutError(runId, definition.timeout!);
-    abortController.abort();
-  }, definition.timeout);
-
-  return {
-    clear: () => clearTimeout(timeoutId),
-    getTimeoutError: () => timeoutError,
-  };
-}
-
-/**
- * Initial list of step keys to consider already complete — empty for a
- * fresh run, the checkpoint's set for a resume.
- */
-export function initialCompletedSteps(
-  checkpoint?: { completedStepKeys: Set<string> }
-): string[] {
-  return checkpoint ? Array.from(checkpoint.completedStepKeys) : [];
-}

package/src/core/orchestrator/state-transitions.ts

@@ -1,109 +0,0 @@
-/**
- * Pure state-transition decisions for the orchestrator.
- *
- * Every function in here is deterministic and side-effect-free: given
- * the current shape of an event, error, or step config they return what
- * the next state should be. The orchestrator and step-runner read these
- * decisions and apply them via persistence helpers.
- *
- * State-transition rules captured here:
- *
- *   Run terminal status:
- *     - WorkflowTimeoutError       → status='failed',   eventType='run.timeout'
- *     - WorkflowCanceledError      → status='canceled', eventType='run.canceled'
- *     - any other error            → status='failed',   eventType='run.failed'
- *
- *   Step error policy resolution (precedence):
- *     - step.onError                        > definition.defaultOnError > 'fail'
- *     - step.maxRetries                     > 3
- *     - step.retryDelay (ms)                > 1000
- *     - step.retryBackoff (multiplier)      > 2
- *
- *   Step retry decision (after a non-cancellation failure):
- *     - onError === 'skip'                            → 'skip'
- *     - onError === 'retry' && attempt <= maxRetries  → 'retry'
- *     - otherwise (incl. retries exhausted, 'fail')   → 'fail'
- */
-import type { WorkflowDefinition, WorkflowStep } from '../types';
-import { WorkflowCanceledError, WorkflowTimeoutError } from '../../utils/errors';
-
-/**
- * Storage-level statuses the orchestrator may persist for a non-success run.
- */
-export type RunFinalStatus = 'failed' | 'canceled';
-
-/**
- * Event types emitted on a non-success run completion.
- */
-export type RunFinalEventType = 'run.timeout' | 'run.canceled' | 'run.failed';
-
-/**
- * Result of mapping an error to a terminal run state.
- */
-export interface RunFinalDecision {
-  status: RunFinalStatus;
-  eventType: RunFinalEventType;
-}
-
-/**
- * Map a thrown workflow error to the final run status + event type.
- * Note: a workflow timeout is persisted as `failed` for storage compatibility,
- * but the emitted event distinguishes it via `run.timeout`.
- */
-export function decideRunFinalState(error: unknown): RunFinalDecision {
-  if (error instanceof WorkflowTimeoutError) {
-    return { status: 'failed', eventType: 'run.timeout' };
-  }
-  if (error instanceof WorkflowCanceledError) {
-    return { status: 'canceled', eventType: 'run.canceled' };
-  }
-  return { status: 'failed', eventType: 'run.failed' };
-}
-
-/**
- * Step-level error policy resolved from a step + workflow definition.
- */
-export interface StepErrorPolicy {
-  onError: 'fail' | 'skip' | 'retry';
-  maxRetries: number;
-  retryDelay: number;
-  retryBackoff: number;
-}
-
-/**
- * Resolve the effective error policy for a step.
- * Step-level config overrides workflow defaults; workflow defaults override
- * the engine defaults (`fail` / 3 / 1000ms / 2x).
- */
-export function resolveStepErrorPolicy<TInput>(
-  step: WorkflowStep<TInput>,
-  definition: WorkflowDefinition<TInput>
-): StepErrorPolicy {
-  return {
-    onError: step.onError ?? definition.defaultOnError ?? 'fail',
-    maxRetries: step.maxRetries ?? 3,
-    retryDelay: step.retryDelay ?? 1000,
-    retryBackoff: step.retryBackoff ?? 2,
-  };
-}
-
-/**
- * Decision returned after a step attempt fails.
- *
- *  - 'skip'  : swallow the error and treat the step as a no-op (returns undefined)
- *  - 'retry' : back off and try again
- *  - 'fail'  : escalate (StepError) and abort the workflow
- */
-export type StepFailureAction = 'skip' | 'retry' | 'fail';
-
-/**
- * Decide what to do after a step attempt has failed (and was not canceled).
- */
-export function decideStepFailureAction(
-  policy: StepErrorPolicy,
-  attempt: number
-): StepFailureAction {
-  if (policy.onError === 'skip') return 'skip';
-  if (policy.onError === 'retry' && attempt <= policy.maxRetries) return 'retry';
-  return 'fail';
-}