@voyantjs/workflows 0.6.7 → 0.6.9

package/src/runtime/executor.ts

@@ -4,22 +4,22 @@
 // Corresponds to the tenant-side handler of POST /__voyant/workflow-step
 // described in docs/runtime-protocol.md §2.1.
 
-import type { RunTrigger, RunStatus, WaitpointKind } from "../types.js";
-import type { SerializedError } from "../protocol/index.js";
-import type { WorkflowDefinition, StepOptions } from "../workflow.js";
-import type { JournalSlice, StepJournalEntry } from "./journal.js";
-import { createClock, createRandom } from "./determinism.js";
-import { buildCtx, type RuntimeCallbacks, type RuntimeEnvironment } from "./ctx.js";
+import type { SerializedError } from "../protocol/index.js"
+import { durationToMs, type RateLimiter } from "../rate-limit/index.js"
+import type { RunStatus, RunTrigger, WaitpointKind } from "../types.js"
+import type { StepOptions, WorkflowDefinition } from "../workflow.js"
+import { buildCtx, type RuntimeCallbacks, type RuntimeEnvironment } from "./ctx.js"
+import { createClock, createRandom } from "./determinism.js"
 import {
-  WaitpointPendingSignal,
-  RunCancelledSignal,
-  isWaitpointPending,
-  isRunCancelled,
   isCompensateRequested,
-} from "./errors.js";
-import { durationToMs, type RateLimiter } from "../rate-limit/index.js";
+  isRunCancelled,
+  isWaitpointPending,
+  RunCancelledSignal,
+  WaitpointPendingSignal,
+} from "./errors.js"
+import type { JournalSlice, StepJournalEntry } from "./journal.js"
 
-export interface StepRunner {
+export type StepRunner = (
   /**
    * Executes a step body and returns the journal entry to record.
    *
@@ -29,22 +29,22 @@ export interface StepRunner {
    * and use the run/workflow identity + step options to address the
    * remote container and POST the required context.
    */
-  (args: {
-    stepId: string;
-    attempt: number;
-    input: unknown;
-    fn: (stepCtx: import("../workflow.js").StepContext) => Promise<unknown>;
-    stepCtx: import("../workflow.js").StepContext;
+  args: {
+    stepId: string
+    attempt: number
+    input: unknown
+    fn: (stepCtx: import("../workflow.js").StepContext) => Promise<unknown>
+    stepCtx: import("../workflow.js").StepContext
     /** Identity of the run — used by dispatching runners. */
-    runId: string;
-    workflowId: string;
-    workflowVersion: string;
+    runId: string
+    workflowId: string
+    workflowVersion: string
     /** Project / organization id from the runtime environment — used by
      *  dispatching runners to resolve per-tenant bundle storage keys. */
-    projectId: string;
-    organizationId: string;
+    projectId: string
+    organizationId: string
     /** Merged step options (runtime, machine, timeout, …). */
-    options: import("../workflow.js").StepOptions<unknown>;
+    options: import("../workflow.js").StepOptions<unknown>
     /**
      * Current journal slice at dispatch time — steps already completed,
      * waitpoints already resolved, etc. Dispatching runners pass this
@@ -52,58 +52,58 @@ export interface StepRunner {
      * cached steps, and the container can stop cleanly after the
      * target step runs.
      */
-    journal: JournalSlice;
-  }): Promise<StepJournalEntry>;
-}
+    journal: JournalSlice
+  },
+) => Promise<StepJournalEntry>
 
 export interface WaitpointRegistration {
-  clientWaitpointId: string;
-  kind: WaitpointKind;
-  meta: Record<string, unknown>;
-  timeoutMs?: number;
+  clientWaitpointId: string
+  kind: WaitpointKind
+  meta: Record<string, unknown>
+  timeoutMs?: number
 }
 
 export interface MetadataMutation {
-  op: "set" | "increment" | "append" | "remove";
-  key: string;
-  value?: unknown;
-  target?: "self" | "parent" | "root";
+  op: "set" | "increment" | "append" | "remove"
+  key: string
+  value?: unknown
+  target?: "self" | "parent" | "root"
 }
 
 export interface CompensationReport {
-  stepId: string;
-  status: "ok" | "err";
-  error?: SerializedError;
-  durationMs: number;
+  stepId: string
+  status: "ok" | "err"
+  error?: SerializedError
+  durationMs: number
 }
 
 export interface StreamChunk {
-  streamId: string;
-  seq: number;
-  encoding: "text" | "json" | "base64";
-  chunk: unknown;
-  final: boolean;
-  at: number;
+  streamId: string
+  seq: number
+  encoding: "text" | "json" | "base64"
+  chunk: unknown
+  final: boolean
+  at: number
 }
 
 export interface ExecuteWorkflowStepRequest {
-  runId: string;
-  workflowId: string;
-  workflowVersion: string;
-  input: unknown;
-  journal: JournalSlice;
-  invocationCount: number;
-  environment: RuntimeEnvironment;
-  triggeredBy: RunTrigger;
-  runStartedAt: number;
-  tags: string[];
-  abortSignal?: AbortSignal;
+  runId: string
+  workflowId: string
+  workflowVersion: string
+  input: unknown
+  journal: JournalSlice
+  invocationCount: number
+  environment: RuntimeEnvironment
+  triggeredBy: RunTrigger
+  runStartedAt: number
+  tags: string[]
+  abortSignal?: AbortSignal
   /**
    * Default step executor (the "edge" runtime) — runs step bodies
    * in-process. Used for any step whose `options.runtime` is unset or
    * explicitly `"edge"`.
    */
-  stepRunner: StepRunner;
+  stepRunner: StepRunner
   /**
    * Optional runner for steps declared with `options.runtime === "node"`.
    * Typical impl dispatches to a Cloudflare Container sized for the
@@ -113,7 +113,7 @@ export interface ExecuteWorkflowStepRequest {
    * `NODE_RUNTIME_UNAVAILABLE` — declaring a runtime and then silently
    * falling back to edge would hide deployment bugs.
    */
-  nodeStepRunner?: StepRunner;
+  nodeStepRunner?: StepRunner
   /**
    * Optional rate limiter. When a step declares `options.rateLimit`,
    * the executor calls `rateLimiter.acquire(...)` before invoking the
@@ -121,9 +121,9 @@ export interface ExecuteWorkflowStepRequest {
    * fails with `RATE_LIMITER_MISSING` — declaring a limit and not
    * enforcing it would be silently dangerous.
    */
-  rateLimiter?: RateLimiter;
+  rateLimiter?: RateLimiter
   /** `() => number` used for compensation durations. Defaults to Date.now. */
-  now?: () => number;
+  now?: () => number
   /**
    * Optional per-chunk callback fired synchronously from
    * `ctx.stream.*` as each chunk is produced. Enables live streaming
@@ -131,75 +131,77 @@ export interface ExecuteWorkflowStepRequest {
    * Chunks are still accumulated in the response's `streamChunks`
    * array so the at-end delivery keeps working.
    */
-  onStreamChunk?: (chunk: StreamChunk) => void;
+  onStreamChunk?: (chunk: StreamChunk) => void
 }
 
 export type ExecuteWorkflowStepResponse =
   | {
-      status: "completed";
-      output: unknown;
-      metadataUpdates: MetadataMutation[];
-      journal: JournalSlice;
-      streamChunks: StreamChunk[];
+      status: "completed"
+      output: unknown
+      metadataUpdates: MetadataMutation[]
+      journal: JournalSlice
+      streamChunks: StreamChunk[]
     }
   | {
-      status: "failed";
-      error: SerializedError;
-      metadataUpdates: MetadataMutation[];
-      journal: JournalSlice;
-      streamChunks: StreamChunk[];
+      status: "failed"
+      error: SerializedError
+      metadataUpdates: MetadataMutation[]
+      journal: JournalSlice
+      streamChunks: StreamChunk[]
     }
   | {
-      status: "cancelled";
-      metadataUpdates: MetadataMutation[];
-      journal: JournalSlice;
-      compensations: CompensationReport[];
-      streamChunks: StreamChunk[];
+      status: "cancelled"
+      metadataUpdates: MetadataMutation[]
+      journal: JournalSlice
+      compensations: CompensationReport[]
+      streamChunks: StreamChunk[]
     }
   | {
-      status: "waiting";
-      waitpoints: WaitpointRegistration[];
-      metadataUpdates: MetadataMutation[];
-      journal: JournalSlice;
-      streamChunks: StreamChunk[];
+      status: "waiting"
+      waitpoints: WaitpointRegistration[]
+      metadataUpdates: MetadataMutation[]
+      journal: JournalSlice
+      streamChunks: StreamChunk[]
     }
   | {
-      status: "compensated";
+      status: "compensated"
       /** Only set when compensation was triggered by an uncaught body error. */
-      error?: SerializedError;
-      compensations: CompensationReport[];
-      metadataUpdates: MetadataMutation[];
-      journal: JournalSlice;
-      streamChunks: StreamChunk[];
+      error?: SerializedError
+      compensations: CompensationReport[]
+      metadataUpdates: MetadataMutation[]
+      journal: JournalSlice
+      streamChunks: StreamChunk[]
     }
   | {
-      status: "compensation_failed";
-      error?: SerializedError;
-      compensations: CompensationReport[];
-      metadataUpdates: MetadataMutation[];
-      journal: JournalSlice;
-      streamChunks: StreamChunk[];
-    };
+      status: "compensation_failed"
+      error?: SerializedError
+      compensations: CompensationReport[]
+      metadataUpdates: MetadataMutation[]
+      journal: JournalSlice
+      streamChunks: StreamChunk[]
+    }
 
 interface Compensable {
-  stepId: string;
-  output: unknown;
-  compensate: (output: unknown) => Promise<void>;
+  stepId: string
+  output: unknown
+  compensate: (output: unknown) => Promise<void>
 }
 
 export async function executeWorkflowStep(
   def: WorkflowDefinition,
   req: ExecuteWorkflowStepRequest,
 ): Promise<ExecuteWorkflowStepResponse> {
-  const abortSignal = req.abortSignal ?? new AbortController().signal;
-  const now = req.now ?? (() => Date.now());
-  const clock = createClock(req.runStartedAt);
-  const random = createRandom(req.runId);
-  const waitpoints: WaitpointRegistration[] = [];
-  const metadataUpdates: MetadataMutation[] = [];
-  const compensable: Compensable[] = [];
-  const streamChunks: StreamChunk[] = [];
-  const retryOverride: { current: import("../types.js").RetryPolicy | undefined } = { current: def.config.retry };
+  const abortSignal = req.abortSignal ?? new AbortController().signal
+  const now = req.now ?? (() => Date.now())
+  const clock = createClock(req.runStartedAt)
+  const random = createRandom(req.runId)
+  const waitpoints: WaitpointRegistration[] = []
+  const metadataUpdates: MetadataMutation[] = []
+  const compensable: Compensable[] = []
+  const streamChunks: StreamChunk[] = []
+  const retryOverride: { current: import("../types.js").RetryPolicy | undefined } = {
+    current: def.config.retry,
+  }
 
   const callbacks: RuntimeCallbacks = {
     invocationCount: req.invocationCount,
@@ -214,17 +216,17 @@ export async function executeWorkflowStep(
           projectId: req.environment.project.id,
           limiter: req.rateLimiter,
           signal: abortSignal,
-        });
+        })
       }
-      const runtime = args.options.runtime ?? "edge";
-      const runner = runtime === "node" ? req.nodeStepRunner : req.stepRunner;
+      const runtime = args.options.runtime ?? "edge"
+      const runner = runtime === "node" ? req.nodeStepRunner : req.stepRunner
       if (!runner) {
         const e = new Error(
           `step "${args.stepId}" declared runtime="node" but the handler has no nodeStepRunner wired; ` +
             `pass { nodeStepRunner } to createStepHandler() or remove options.runtime`,
-        );
-        (e as Error & { code?: string }).code = "NODE_RUNTIME_UNAVAILABLE";
-        throw e;
+        )
+        ;(e as Error & { code?: string }).code = "NODE_RUNTIME_UNAVAILABLE"
+        throw e
       }
       const entry = await runner({
         stepId: args.stepId,
@@ -239,42 +241,42 @@ export async function executeWorkflowStep(
         organizationId: req.environment.organization.id,
         options: args.options,
         journal: req.journal,
-      });
+      })
       // Stamp the runtime on the journal entry so downstream consumers
       // (journal persistence, dashboard events) can report where each
       // step actually ran.
-      entry.runtime = runtime;
-      return entry;
+      entry.runtime = runtime
+      return entry
     },
     registerWaitpoint(args) {
-      waitpoints.push(args);
+      waitpoints.push(args)
     },
     pushMetadata(op) {
-      metadataUpdates.push(op);
+      metadataUpdates.push(op)
     },
     recordCompensable(args) {
-      compensable.push(args);
+      compensable.push(args)
     },
     compensableLength(): number {
-      return compensable.length;
+      return compensable.length
     },
     spliceCompensable(fromIndex: number): Compensable[] {
-      return compensable.splice(fromIndex);
+      return compensable.splice(fromIndex)
     },
     pushStreamChunk(args) {
-      const chunk = { ...args, at: now() };
-      streamChunks.push(chunk);
+      const chunk = { ...args, at: now() }
+      streamChunks.push(chunk)
       // Fire the live hook synchronously. Errors are swallowed — a
       // misbehaving subscriber must not break the workflow body.
       if (req.onStreamChunk) {
         try {
-          req.onStreamChunk(chunk);
+          req.onStreamChunk(chunk)
         } catch {
           /* ignore */
         }
       }
     },
-  };
+  }
 
   const ctx = buildCtx({
     env: req.environment,
@@ -283,48 +285,54 @@ export async function executeWorkflowStep(
     clock,
     random,
     retryOverride,
-  });
+  })
 
   try {
-    const output = await def.config.run(req.input, ctx);
+    const output = await def.config.run(req.input, ctx)
     // If the body registered a waitpoint but a user try/catch swallowed
     // the internal yield signal, honour the waitpoint — the body can't
     // both register a waitpoint and complete in the same invocation.
     if (waitpoints.length > 0) {
-      return { status: "waiting", waitpoints, metadataUpdates, journal: req.journal, streamChunks };
+      return { status: "waiting", waitpoints, metadataUpdates, journal: req.journal, streamChunks }
     }
-    return { status: "completed", output, metadataUpdates, journal: req.journal, streamChunks };
+    return { status: "completed", output, metadataUpdates, journal: req.journal, streamChunks }
   } catch (err) {
     if (isWaitpointPending(err)) {
-      return { status: "waiting", waitpoints, metadataUpdates, journal: req.journal, streamChunks };
+      return { status: "waiting", waitpoints, metadataUpdates, journal: req.journal, streamChunks }
     }
     // Same guard for the error path: a swallowed signal shouldn't let
     // the body claim failure while waitpoints are pending.
     if (waitpoints.length > 0 && !isRunCancelled(err) && !isCompensateRequested(err)) {
-      return { status: "waiting", waitpoints, metadataUpdates, journal: req.journal, streamChunks };
+      return { status: "waiting", waitpoints, metadataUpdates, journal: req.journal, streamChunks }
     }
     if (isRunCancelled(err)) {
       // Default: compensate on cancel. Terminal status stays `cancelled`
       // to reflect why the run ended.
-      const compensations = await runCompensations(compensable, now);
-      return { status: "cancelled", metadataUpdates, journal: req.journal, compensations, streamChunks };
+      const compensations = await runCompensations(compensable, now)
+      return {
+        status: "cancelled",
+        metadataUpdates,
+        journal: req.journal,
+        compensations,
+        streamChunks,
+      }
     }
     if (isCompensateRequested(err)) {
-      const compensations = await runCompensations(compensable, now);
-      const anyErr = compensations.some((c) => c.status === "err");
+      const compensations = await runCompensations(compensable, now)
+      const anyErr = compensations.some((c) => c.status === "err")
       return {
         status: anyErr ? "compensation_failed" : "compensated",
         compensations,
         metadataUpdates,
         journal: req.journal,
         streamChunks,
-      };
+      }
     }
 
     // Uncaught user error. Run compensations LIFO; adjust terminal status
     // based on whether compensations were registered and all succeeded.
-    const compensations = await runCompensations(compensable, now);
-    const serialized = serializeError(err);
+    const compensations = await runCompensations(compensable, now)
+    const serialized = serializeError(err)
 
     if (compensations.length === 0) {
       return {
@@ -333,10 +341,10 @@ export async function executeWorkflowStep(
         metadataUpdates,
         journal: req.journal,
         streamChunks,
-      };
+      }
     }
 
-    const anyErr = compensations.some((c) => c.status === "err");
+    const anyErr = compensations.some((c) => c.status === "err")
     return {
       status: anyErr ? "compensation_failed" : "compensated",
       error: serialized,
@@ -344,7 +352,7 @@ export async function executeWorkflowStep(
       metadataUpdates,
       journal: req.journal,
       streamChunks,
-    };
+    }
   }
 }
 
@@ -352,31 +360,31 @@ async function runCompensations(
   compensable: readonly Compensable[],
   now: () => number,
 ): Promise<CompensationReport[]> {
-  const reports: CompensationReport[] = [];
+  const reports: CompensationReport[] = []
   // Reverse order: last-completed compensates first.
   for (let i = compensable.length - 1; i >= 0; i--) {
-    const c = compensable[i]!;
-    const startedAt = now();
+    const c = compensable[i]!
+    const startedAt = now()
     try {
-      await c.compensate(c.output);
-      reports.push({ stepId: c.stepId, status: "ok", durationMs: now() - startedAt });
+      await c.compensate(c.output)
+      reports.push({ stepId: c.stepId, status: "ok", durationMs: now() - startedAt })
     } catch (err) {
       reports.push({
         stepId: c.stepId,
         status: "err",
         error: serializeError(err),
         durationMs: now() - startedAt,
-      });
+      })
       // Continue with remaining compensations; don't abort on one failure.
     }
   }
-  return reports;
+  return reports
 }
 
 function serializeError(err: unknown): SerializedError {
   if (err instanceof Error) {
-    const code = (err as { code?: string }).code;
-    const cause = (err as { cause?: unknown }).cause;
+    const code = (err as { code?: string }).code
+    const cause = (err as { cause?: unknown }).cause
     return {
       category: "USER_ERROR",
       code: typeof code === "string" ? code : "UNKNOWN",
@@ -384,44 +392,43 @@ function serializeError(err: unknown): SerializedError {
       name: err.name,
       stack: err.stack,
       cause: cause !== undefined ? serializeError(cause) : undefined,
-    };
+    }
   }
-  return { category: "USER_ERROR", code: "UNKNOWN", message: String(err) };
+  return { category: "USER_ERROR", code: "UNKNOWN", message: String(err) }
 }
 
 async function acquireRateLimit(args: {
-  spec: NonNullable<StepOptions<unknown>["rateLimit"]>;
-  stepId: string;
-  input: unknown;
-  runId: string;
-  projectId: string;
-  limiter: RateLimiter | undefined;
-  signal: AbortSignal;
+  spec: NonNullable<StepOptions<unknown>["rateLimit"]>
+  stepId: string
+  input: unknown
+  runId: string
+  projectId: string
+  limiter: RateLimiter | undefined
+  signal: AbortSignal
 }): Promise<void> {
-  const ctx = { run: { id: args.runId }, project: { id: args.projectId } };
-  const key =
-    typeof args.spec.key === "function" ? args.spec.key(args.input, ctx) : args.spec.key;
+  const ctx = { run: { id: args.runId }, project: { id: args.projectId } }
+  const key = typeof args.spec.key === "function" ? args.spec.key(args.input, ctx) : args.spec.key
   const limit =
-    typeof args.spec.limit === "function" ? args.spec.limit(args.input) : args.spec.limit;
+    typeof args.spec.limit === "function" ? args.spec.limit(args.input) : args.spec.limit
   const units =
     args.spec.units === undefined
       ? 1
       : typeof args.spec.units === "function"
         ? args.spec.units(args.input)
-        : args.spec.units;
-  const windowMs = durationToMs(args.spec.window);
-  const onLimit = args.spec.onLimit ?? "queue";
+        : args.spec.units
+  const windowMs = durationToMs(args.spec.window)
+  const onLimit = args.spec.onLimit ?? "queue"
 
   if (!args.limiter) {
     const e = new Error(
       `step "${args.stepId}" declared options.rateLimit but the handler has no rateLimiter wired; ` +
         `pass { rateLimiter } to createStepHandler()`,
-    );
-    (e as Error & { code?: string }).code = "RATE_LIMITER_MISSING";
-    throw e;
+    )
+    ;(e as Error & { code?: string }).code = "RATE_LIMITER_MISSING"
+    throw e
   }
-  await args.limiter.acquire({ key, limit, units, windowMs, onLimit, signal: args.signal });
+  await args.limiter.acquire({ key, limit, units, windowMs, onLimit, signal: args.signal })
 }
 
-export { WaitpointPendingSignal, RunCancelledSignal };
-export type { RunStatus };
+export type { RunStatus }
+export { RunCancelledSignal, WaitpointPendingSignal }

package/src/runtime/journal.ts

@@ -3,45 +3,45 @@
 //
 // Wire shape defined in docs/runtime-protocol.md §2.1 (JournalSlice).
 
-import type { WaitpointKind } from "../types.js";
-import type { SerializedError } from "../protocol/index.js";
+import type { SerializedError } from "../protocol/index.js"
+import type { WaitpointKind } from "../types.js"
 
 export interface StepJournalEntry {
-  attempt: number;
-  status: "ok" | "err";
-  output?: unknown;
-  error?: SerializedError;
-  startedAt: number;
-  finishedAt: number;
+  attempt: number
+  status: "ok" | "err"
+  output?: unknown
+  error?: SerializedError
+  startedAt: number
+  finishedAt: number
   /**
    * Which runtime actually executed the step. Set by the executor when
    * routing between `stepRunner` (edge) and `nodeStepRunner`.
    * Informational only — doesn't affect replay.
    */
-  runtime?: "edge" | "node";
+  runtime?: "edge" | "node"
 }
 
 export interface WaitpointResolutionEntry {
-  kind: WaitpointKind;
-  resolvedAt: number;
-  matchedEventId?: string;
-  payload?: unknown;
-  source: "live" | "inbox" | "replay";
+  kind: WaitpointKind
+  resolvedAt: number
+  matchedEventId?: string
+  payload?: unknown
+  source: "live" | "inbox" | "replay"
   /** Populated for RUN waitpoints when the child run ended in a failure state. */
-  error?: SerializedError;
+  error?: SerializedError
 }
 
 export interface CompensationJournalEntry {
-  status: "ok" | "err";
-  finishedAt: number;
-  error?: SerializedError;
+  status: "ok" | "err"
+  finishedAt: number
+  error?: SerializedError
 }
 
 export interface JournalSlice {
-  stepResults: Record<string, StepJournalEntry>;
-  waitpointsResolved: Record<string, WaitpointResolutionEntry>;
-  compensationsRun: Record<string, CompensationJournalEntry>;
-  metadataState: Record<string, unknown>;
+  stepResults: Record<string, StepJournalEntry>
+  waitpointsResolved: Record<string, WaitpointResolutionEntry>
+  compensationsRun: Record<string, CompensationJournalEntry>
+  metadataState: Record<string, unknown>
   /**
    * Stream ids whose generator has already been consumed in a prior
    * invocation. The orchestrator already has the chunks on the run
@@ -49,7 +49,7 @@ export interface JournalSlice {
    * (generators often have side effects — LLM calls, file reads,
    * billable API usage).
    */
-  streamsCompleted: Record<string, { chunkCount: number }>;
+  streamsCompleted: Record<string, { chunkCount: number }>
 }
 
 export function emptyJournal(): JournalSlice {
@@ -59,7 +59,7 @@ export function emptyJournal(): JournalSlice {
     compensationsRun: {},
     metadataState: {},
     streamsCompleted: {},
-  };
+  }
 }
 
 /**
@@ -75,5 +75,5 @@ export function forkJournal(j: JournalSlice): JournalSlice {
     compensationsRun: { ...j.compensationsRun },
     metadataState: { ...j.metadataState },
     streamsCompleted: { ...j.streamsCompleted },
-  };
+  }
 }