@voyantjs/workflows 0.6.7 → 0.6.9

package/src/runtime/ctx.ts

@@ -3,15 +3,14 @@
 // The executor owns the waitpoint-pending queue and the callbacks
 // into the orchestrator; ctx is a thin shell that delegates.
 
-import type {
-  Duration,
-  EnvironmentName,
-  RetryPolicy,
-  RunTrigger,
-  WaitpointKind,
-} from "../types.js";
+import type { SerializedError } from "../protocol/index.js"
+import type { Duration, RetryPolicy, WaitpointKind } from "../types.js"
 import type {
   EnvironmentContext,
+  GroupApi,
+  GroupScope,
+  InvokeApi,
+  InvokeOptions,
   MetadataApi,
   MetadataValue,
   ParallelApi,
@@ -21,34 +20,24 @@ import type {
   StepFn,
   StepOptions,
   StreamApi,
+  TokenWait,
+  Waitable,
   WaitForEventApi,
   WaitForSignalApi,
   WaitForTokenApi,
-  Waitable,
   WorkflowContext,
   WorkflowHandle,
-  InvokeApi,
-  InvokeOptions,
-  TokenWait,
-  GroupApi,
-  GroupScope,
-} from "../workflow.js";
-import type { JournalSlice, StepJournalEntry, WaitpointResolutionEntry } from "./journal.js";
-import type { SerializedError } from "../protocol/index.js";
+} from "../workflow.js"
+import { advanceClockTo, type ClockState, createRandomUUID, now } from "./determinism.js"
 import {
-  WaitpointPendingSignal,
-  RunCancelledSignal,
   CompensateRequestedSignal,
-  isWaitpointPending,
-  isRunCancelled,
   isCompensateRequested,
-} from "./errors.js";
-import {
-  type ClockState,
-  advanceClockTo,
-  createRandomUUID,
-  now,
-} from "./determinism.js";
+  isRunCancelled,
+  isWaitpointPending,
+  RunCancelledSignal,
+  WaitpointPendingSignal,
+} from "./errors.js"
+import type { JournalSlice, StepJournalEntry, WaitpointResolutionEntry } from "./journal.js"
 
 /**
  * Callbacks the executor provides for operations that must reach the
@@ -57,13 +46,13 @@ import {
 export interface RuntimeCallbacks {
   /** Run a new step and journal the result. Called only for steps not already in the journal. */
   runStep(args: {
-    stepId: string;
-    attempt: number;
-    input: unknown;
-    options: StepOptions<unknown>;
-    fn: StepFn<unknown>;
-    stepCtx: StepContext;
-  }): Promise<StepJournalEntry>;
+    stepId: string
+    attempt: number
+    input: unknown
+    options: StepOptions<unknown>
+    fn: StepFn<unknown>
+    stepCtx: StepContext
+  }): Promise<StepJournalEntry>
 
   /**
    * Called when a step completes successfully and had a `compensate`
@@ -72,13 +61,13 @@ export interface RuntimeCallbacks {
    * is invoked.
    */
   recordCompensable(args: {
-    stepId: string;
-    output: unknown;
-    compensate: (output: unknown) => Promise<void>;
-  }): void;
+    stepId: string
+    output: unknown
+    compensate: (output: unknown) => Promise<void>
+  }): void
 
   /** Current length of the compensable list. Used by `ctx.group` checkpoints. */
-  compensableLength(): number;
+  compensableLength(): number
 
   /**
    * Remove and return compensables added since `fromIndex`. Used by
@@ -86,10 +75,10 @@ export interface RuntimeCallbacks {
    * compensables.
    */
   spliceCompensable(fromIndex: number): Array<{
-    stepId: string;
-    output: unknown;
-    compensate: (output: unknown) => Promise<void>;
-  }>;
+    stepId: string
+    output: unknown
+    compensate: (output: unknown) => Promise<void>
+  }>
 
   /**
    * Called by `ctx.stream()` for each chunk produced by the source.
@@ -97,65 +86,65 @@ export interface RuntimeCallbacks {
    * journals the chunk; in tests the harness collects chunks.
    */
   pushStreamChunk(args: {
-    streamId: string;
-    seq: number;
-    encoding: "text" | "json" | "base64";
-    chunk: unknown;
-    final: boolean;
-  }): void;
+    streamId: string
+    seq: number
+    encoding: "text" | "json" | "base64"
+    chunk: unknown
+    final: boolean
+  }): void
 
   /** Register a new waitpoint; execution will yield after this returns. */
   registerWaitpoint(args: {
-    clientWaitpointId: string;
-    kind: WaitpointKind;
-    meta: Record<string, unknown>;
-    timeoutMs?: number;
-  }): void;
+    clientWaitpointId: string
+    kind: WaitpointKind
+    meta: Record<string, unknown>
+    timeoutMs?: number
+  }): void
 
   /** Push a metadata mutation; flushed on waitpoint yield and run completion. */
   pushMetadata(op: {
-    op: "set" | "increment" | "append" | "remove";
-    key: string;
-    value?: unknown;
-    target?: "self" | "parent" | "root";
-  }): void;
+    op: "set" | "increment" | "append" | "remove"
+    key: string
+    value?: unknown
+    target?: "self" | "parent" | "root"
+  }): void
 
   /** Increment invocation counter when the body resumes after eviction. */
-  readonly invocationCount: number;
+  readonly invocationCount: number
 
   /** Cancellation signal exposed as `ctx.signal`. */
-  readonly abortSignal: AbortSignal;
+  readonly abortSignal: AbortSignal
 }
 
 export interface RuntimeEnvironment {
-  readonly run: RunContext;
-  readonly workflow: { id: string; version: string };
-  readonly environment: EnvironmentContext;
-  readonly project: { id: string; slug: string };
-  readonly organization: { id: string; slug: string };
+  readonly run: RunContext
+  readonly workflow: { id: string; version: string }
+  readonly environment: EnvironmentContext
+  readonly project: { id: string; slug: string }
+  readonly organization: { id: string; slug: string }
 }
 
 export interface CtxBuildArgs {
-  env: RuntimeEnvironment;
-  journal: JournalSlice;
-  callbacks: RuntimeCallbacks;
-  clock: ClockState;
-  random: () => number;
+  env: RuntimeEnvironment
+  journal: JournalSlice
+  callbacks: RuntimeCallbacks
+  clock: ClockState
+  random: () => number
   /** Mutated as ctx.setRetry is called; each step option inherits. */
-  retryOverride: { current: RetryPolicy | undefined };
+  retryOverride: { current: RetryPolicy | undefined }
 }
 
 export function buildCtx(args: CtxBuildArgs): WorkflowContext<unknown> {
-  const { env, journal, callbacks, clock, random, retryOverride } = args;
+  const { env, journal, callbacks, clock, random, retryOverride } = args
 
   // Per-ctx client-id counter. Reset on each ctx (= each invocation),
   // which means ids are stable relative to body execution order.
-  let clientIdSeq = 0;
-  const nextClientId = (): number => ++clientIdSeq;
+  let clientIdSeq = 0
+  const nextClientId = (): number => ++clientIdSeq
 
   function checkCancel(): void {
     if (callbacks.abortSignal.aborted) {
-      throw new RunCancelledSignal();
+      throw new RunCancelledSignal()
     }
   }
 
@@ -166,14 +155,15 @@ export function buildCtx(args: CtxBuildArgs): WorkflowContext<unknown> {
     optsOrFn: StepOptions<unknown> | StepFn<unknown>,
     maybeFn?: StepFn<unknown>,
   ) => {
-    checkCancel();
-    const opts: StepOptions<unknown> = typeof optsOrFn === "function" ? {} : optsOrFn;
-    const fn: StepFn<unknown> = typeof optsOrFn === "function" ? optsOrFn : (maybeFn as StepFn<unknown>);
+    checkCancel()
+    const opts: StepOptions<unknown> = typeof optsOrFn === "function" ? {} : optsOrFn
+    const fn: StepFn<unknown> =
+      typeof optsOrFn === "function" ? optsOrFn : (maybeFn as StepFn<unknown>)
 
     // Journal hit? Return cached.
-    const cached = journal.stepResults[id];
+    const cached = journal.stepResults[id]
     if (cached) {
-      advanceClockTo(clock, cached.finishedAt);
+      advanceClockTo(clock, cached.finishedAt)
       if (cached.status === "ok") {
         // Re-register compensable on replay so compensations are available
         // if this invocation ends up rolling back.
@@ -182,54 +172,54 @@ export function buildCtx(args: CtxBuildArgs): WorkflowContext<unknown> {
             stepId: id,
             output: cached.output,
             compensate: opts.compensate as (output: unknown) => Promise<void>,
-          });
+          })
         }
-        return cached.output;
+        return cached.output
       }
       // Journaled error rethrows on replay so catch blocks behave consistently.
-      const e = new Error(cached.error?.message ?? "step failed");
-      (e as { code?: string }).code = cached.error?.code;
-      throw e;
+      const e = new Error(cached.error?.message ?? "step failed")
+      ;(e as { code?: string }).code = cached.error?.code
+      throw e
     }
 
     // Execute a new step via the callback, with the retry loop.
     const mergedOpts: StepOptions<unknown> = {
       ...opts,
       retry: opts.retry ?? retryOverride.current,
-    };
-    const policy = normalizeRetry(mergedOpts.retry);
-    let attempt = 0;
-    let lastEntry: StepJournalEntry | undefined;
+    }
+    const policy = normalizeRetry(mergedOpts.retry)
+    let attempt = 0
+    let lastEntry: StepJournalEntry | undefined
 
     // Per-step timeout: compose the run-level abort signal with a
     // per-call AbortSignal.timeout so cooperative step bodies (fetch,
     // setTimeout wrappers, custom AbortSignal observers) stop early
     // on timeout. Hard enforcement for uncooperative bodies is done
     // below by racing the wrapped fn against a timeout rejection.
-    const timeoutMs = mergedOpts.timeout !== undefined ? toMs(mergedOpts.timeout) : undefined;
+    const timeoutMs = mergedOpts.timeout !== undefined ? toMs(mergedOpts.timeout) : undefined
     const fnWithTimeout: StepFn<unknown> =
       timeoutMs !== undefined
         ? async (stepCtx) => {
-            let timer: ReturnType<typeof setTimeout> | undefined;
+            let timer: ReturnType<typeof setTimeout> | undefined
             try {
               return await Promise.race([
                 fn(stepCtx),
                 new Promise<never>((_, reject) => {
                   timer = setTimeout(() => {
-                    const e = new Error(`step "${id}" timed out after ${timeoutMs}ms`);
-                    (e as Error & { code?: string }).code = "TIMEOUT";
-                    reject(e);
-                  }, timeoutMs);
+                    const e = new Error(`step "${id}" timed out after ${timeoutMs}ms`)
+                    ;(e as Error & { code?: string }).code = "TIMEOUT"
+                    reject(e)
+                  }, timeoutMs)
                 }),
-              ]);
+              ])
             } finally {
-              if (timer !== undefined) clearTimeout(timer);
+              if (timer !== undefined) clearTimeout(timer)
             }
           }
-        : fn;
+        : fn
 
     while (attempt < policy.max) {
-      attempt += 1;
+      attempt += 1
       const stepCtx: StepContext = {
         signal:
           timeoutMs !== undefined
@@ -237,9 +227,13 @@ export function buildCtx(args: CtxBuildArgs): WorkflowContext<unknown> {
             : callbacks.abortSignal,
         attempt,
         log: (level, msg, data) => {
-          console[level === "error" ? "error" : level === "warn" ? "warn" : "log"](`[${id}]`, msg, data ?? "");
+          console[level === "error" ? "error" : level === "warn" ? "warn" : "log"](
+            `[${id}]`,
+            msg,
+            data ?? "",
+          )
         },
-      };
+      }
       const entry = await callbacks.runStep({
         stepId: id,
         attempt,
@@ -247,42 +241,42 @@ export function buildCtx(args: CtxBuildArgs): WorkflowContext<unknown> {
         options: mergedOpts,
         fn: fnWithTimeout,
         stepCtx,
-      });
-      lastEntry = entry;
+      })
+      lastEntry = entry
 
       if (entry.status === "ok") {
-        journal.stepResults[id] = entry;
-        advanceClockTo(clock, entry.finishedAt);
+        journal.stepResults[id] = entry
+        advanceClockTo(clock, entry.finishedAt)
         if (opts.compensate) {
           callbacks.recordCompensable({
             stepId: id,
             output: entry.output,
             compensate: opts.compensate as (output: unknown) => Promise<void>,
-          });
+          })
         }
-        return entry.output;
+        return entry.output
       }
 
       // Failed attempt. Check if we should stop retrying.
-      if (entry.error?.code === "FATAL") break;
-      if (attempt >= policy.max) break;
+      if (entry.error?.code === "FATAL") break
+      if (attempt >= policy.max) break
 
       // In production the step handler returns { retryAfter } to the DO
       // which sets an alarm; here the spike/test harness continues
       // immediately. retryAfter from RetryableError wins over the policy
       // backoff when set.
-      const retryAfter = readRetryAfter(entry.error);
-      await maybeDelay(retryAfter ?? backoffDelay(policy, attempt));
+      const retryAfter = readRetryAfter(entry.error)
+      await maybeDelay(retryAfter ?? backoffDelay(policy, attempt))
     }
 
     // Retries exhausted (or never retried).
-    const finalEntry = lastEntry!;
-    journal.stepResults[id] = finalEntry;
-    advanceClockTo(clock, finalEntry.finishedAt);
-    const e = new Error(finalEntry.error?.message ?? "step failed");
-    (e as { code?: string }).code = finalEntry.error?.code;
-    throw e;
-  }) as StepApi;
+    const finalEntry = lastEntry!
+    journal.stepResults[id] = finalEntry
+    advanceClockTo(clock, finalEntry.finishedAt)
+    const e = new Error(finalEntry.error?.message ?? "step failed")
+    ;(e as { code?: string }).code = finalEntry.error?.code
+    throw e
+  }) as StepApi
 
   // ---- waits ----
 
@@ -292,25 +286,25 @@ export function buildCtx(args: CtxBuildArgs): WorkflowContext<unknown> {
     meta: Record<string, unknown>,
     timeoutMs?: number,
   ): never {
-    callbacks.registerWaitpoint({ clientWaitpointId, kind, meta, timeoutMs });
-    throw new WaitpointPendingSignal(clientWaitpointId);
+    callbacks.registerWaitpoint({ clientWaitpointId, kind, meta, timeoutMs })
+    throw new WaitpointPendingSignal(clientWaitpointId)
   }
 
   function lookupWaitpoint(id: string): WaitpointResolutionEntry | undefined {
-    return journal.waitpointsResolved[id];
+    return journal.waitpointsResolved[id]
   }
 
   const sleep = async (duration: Duration): Promise<void> => {
-    checkCancel();
-    const id = `sleep:${nextClientId()}`;
-    const resolved = lookupWaitpoint(id);
+    checkCancel()
+    const id = `sleep:${nextClientId()}`
+    const resolved = lookupWaitpoint(id)
     if (resolved) {
-      advanceClockTo(clock, resolved.resolvedAt);
-      return;
+      advanceClockTo(clock, resolved.resolvedAt)
+      return
     }
-    const ms = toMs(duration);
-    yieldWaitpoint(id, "DATETIME", { durationMs: ms }, ms);
-  };
+    const ms = toMs(duration)
+    yieldWaitpoint(id, "DATETIME", { durationMs: ms }, ms)
+  }
 
   function makeWaitable<T>(
     kind: WaitpointKind,
@@ -322,69 +316,70 @@ export function buildCtx(args: CtxBuildArgs): WorkflowContext<unknown> {
   ): Waitable<T> {
     // --- thenable: single first-match-wins resolution ---
     const resolve = (): T | null => {
-      const resolved = lookupWaitpoint(clientWaitpointId);
+      const resolved = lookupWaitpoint(clientWaitpointId)
       if (!resolved) {
-        yieldWaitpoint(clientWaitpointId, kind, meta, timeoutMs);
+        yieldWaitpoint(clientWaitpointId, kind, meta, timeoutMs)
       }
-      advanceClockTo(clock, resolved.resolvedAt);
+      advanceClockTo(clock, resolved.resolvedAt)
       if (resolved.payload === undefined && onTimeout === "throw") {
-        throw new Error(`waitpoint ${clientWaitpointId} timed out`);
+        throw new Error(`waitpoint ${clientWaitpointId} timed out`)
       }
-      return (resolved.payload ?? null) as T | null;
-    };
+      return (resolved.payload ?? null) as T | null
+    }
 
     // --- iterable: fresh waitpoint per .next() call ---
     function makeIterator(): AsyncIterableIterator<T> {
-      let closed = false;
+      let closed = false
       return {
         async next(): Promise<IteratorResult<T>> {
-          if (closed) return { value: undefined as unknown as T, done: true };
-          checkCancel();
-          const iterId = `${iterIdPrefix}:iter:${nextClientId()}`;
-          const resolvedIter = lookupWaitpoint(iterId);
+          if (closed) return { value: undefined as unknown as T, done: true }
+          checkCancel()
+          const iterId = `${iterIdPrefix}:iter:${nextClientId()}`
+          const resolvedIter = lookupWaitpoint(iterId)
           if (!resolvedIter) {
-            yieldWaitpoint(iterId, kind, { ...meta, iter: true }, timeoutMs);
+            yieldWaitpoint(iterId, kind, { ...meta, iter: true }, timeoutMs)
           }
-          advanceClockTo(clock, resolvedIter.resolvedAt);
+          advanceClockTo(clock, resolvedIter.resolvedAt)
           // End-of-stream marker. Harness / orchestrator writes this to
           // tell the iterator the source has no more events.
-          const payload = resolvedIter.payload as unknown;
+          const payload = resolvedIter.payload as unknown
           if (isStreamEnd(payload)) {
-            closed = true;
-            return { value: undefined as unknown as T, done: true };
+            closed = true
+            return { value: undefined as unknown as T, done: true }
           }
           if (payload === undefined && onTimeout === "throw") {
-            throw new Error(`waitpoint ${iterId} timed out`);
+            throw new Error(`waitpoint ${iterId} timed out`)
           }
-          return { value: payload as T, done: false };
+          return { value: payload as T, done: false }
         },
         async return(): Promise<IteratorResult<T>> {
-          closed = true;
-          return { value: undefined as unknown as T, done: true };
+          closed = true
+          return { value: undefined as unknown as T, done: true }
         },
         [Symbol.asyncIterator]() {
-          return this;
+          return this
         },
-      };
+      }
     }
 
     const thenable: Waitable<T> = {
+      // biome-ignore lint/suspicious/noThenProperty: Waitable intentionally implements PromiseLike for `await`.
       then(onFulfilled, onRejected) {
         try {
-          const r = resolve();
-          return Promise.resolve(r).then(onFulfilled, onRejected);
+          const r = resolve()
+          return Promise.resolve(r).then(onFulfilled, onRejected)
         } catch (e) {
-          return Promise.reject(e).then(onFulfilled, onRejected);
+          return Promise.reject(e).then(onFulfilled, onRejected)
         }
       },
       [Symbol.asyncIterator]() {
-        return makeIterator();
+        return makeIterator()
       },
       close() {
         // no-op; `return()` on the iterator handles early break.
       },
-    };
-    return thenable;
+    }
+    return thenable
   }
 
   function isStreamEnd(payload: unknown): boolean {
@@ -392,13 +387,16 @@ export function buildCtx(args: CtxBuildArgs): WorkflowContext<unknown> {
       typeof payload === "object" &&
       payload !== null &&
       (payload as { __voyantStreamEnd?: boolean }).__voyantStreamEnd === true
-    );
+    )
   }
 
-  const waitForEvent: WaitForEventApi = ((eventType: string, opts?: { timeout?: Duration; onTimeout?: "null" | "throw" }) => {
-    checkCancel();
-    const thenableId = `event:${eventType}:${nextClientId()}`;
-    const iterPrefix = `event:${eventType}`;
+  const waitForEvent: WaitForEventApi = ((
+    eventType: string,
+    opts?: { timeout?: Duration; onTimeout?: "null" | "throw" },
+  ) => {
+    checkCancel()
+    const thenableId = `event:${eventType}:${nextClientId()}`
+    const iterPrefix = `event:${eventType}`
     return makeWaitable(
       "EVENT",
       thenableId,
@@ -406,13 +404,16 @@ export function buildCtx(args: CtxBuildArgs): WorkflowContext<unknown> {
       { eventType },
       opts?.timeout ? toMs(opts.timeout) : undefined,
       opts?.onTimeout,
-    );
-  }) as WaitForEventApi;
+    )
+  }) as WaitForEventApi
 
-  const waitForSignal: WaitForSignalApi = ((name: string, opts?: { timeout?: Duration; onTimeout?: "null" | "throw" }) => {
-    checkCancel();
-    const thenableId = `signal:${name}:${nextClientId()}`;
-    const iterPrefix = `signal:${name}`;
+  const waitForSignal: WaitForSignalApi = ((
+    name: string,
+    opts?: { timeout?: Duration; onTimeout?: "null" | "throw" },
+  ) => {
+    checkCancel()
+    const thenableId = `signal:${name}:${nextClientId()}`
+    const iterPrefix = `signal:${name}`
     return makeWaitable(
       "SIGNAL",
       thenableId,
@@ -420,39 +421,39 @@ export function buildCtx(args: CtxBuildArgs): WorkflowContext<unknown> {
       { signalName: name },
       opts?.timeout ? toMs(opts.timeout) : undefined,
       opts?.onTimeout,
-    );
-  }) as WaitForSignalApi;
+    )
+  }) as WaitForSignalApi
 
   const waitForToken: WaitForTokenApi = (async (opts?: {
-    tokenId?: string;
-    timeout?: Duration;
-    onTimeout?: "null" | "throw";
+    tokenId?: string
+    timeout?: Duration
+    onTimeout?: "null" | "throw"
   }) => {
-    checkCancel();
+    checkCancel()
     // Allocate a stable id per call. User-supplied `tokenId` is kept
     // verbatim so external systems can reference the same value.
-    const tokenId = opts?.tokenId ?? `tok_${nextClientId()}`;
-    const waitpointId = `token:${tokenId}`;
-    const timeoutMs = opts?.timeout ? toMs(opts.timeout) : undefined;
-    const onTimeout = opts?.onTimeout ?? "null";
+    const tokenId = opts?.tokenId ?? `tok_${nextClientId()}`
+    const waitpointId = `token:${tokenId}`
+    const timeoutMs = opts?.timeout ? toMs(opts.timeout) : undefined
+    const onTimeout = opts?.onTimeout ?? "null"
 
     return {
       tokenId,
       url: `/__voyant/tokens/${tokenId}`,
       wait: async (): Promise<unknown> => {
-        checkCancel();
-        const resolved = lookupWaitpoint(waitpointId);
+        checkCancel()
+        const resolved = lookupWaitpoint(waitpointId)
         if (resolved) {
-          advanceClockTo(clock, resolved.resolvedAt);
+          advanceClockTo(clock, resolved.resolvedAt)
           if (resolved.payload === undefined && onTimeout === "throw") {
-            throw new Error(`token ${tokenId} timed out`);
+            throw new Error(`token ${tokenId} timed out`)
           }
-          return resolved.payload ?? null;
+          return resolved.payload ?? null
         }
-        yieldWaitpoint(waitpointId, "MANUAL", { tokenId }, timeoutMs);
+        yieldWaitpoint(waitpointId, "MANUAL", { tokenId }, timeoutMs)
       },
-    } as TokenWait<unknown>;
-  }) as WaitForTokenApi;
+    } as TokenWait<unknown>
+  }) as WaitForTokenApi
 
   // ---- invoke / parallel ----
 
@@ -461,17 +462,17 @@ export function buildCtx(args: CtxBuildArgs): WorkflowContext<unknown> {
     input: TIn,
     opts?: InvokeOptions,
   ): Promise<TOut> => {
-    checkCancel();
-    const id = `invoke:${wf.id}:${nextClientId()}`;
-    const resolved = journal.waitpointsResolved[id];
+    checkCancel()
+    const id = `invoke:${wf.id}:${nextClientId()}`
+    const resolved = journal.waitpointsResolved[id]
     if (resolved) {
-      advanceClockTo(clock, resolved.resolvedAt);
+      advanceClockTo(clock, resolved.resolvedAt)
       if (resolved.error) {
-        const e = new Error(resolved.error.message);
-        (e as { code?: string }).code = resolved.error.code;
-        throw e;
+        const e = new Error(resolved.error.message)
+        ;(e as { code?: string }).code = resolved.error.code
+        throw e
       }
-      return resolved.payload as TOut;
+      return resolved.payload as TOut
     }
     yieldWaitpoint(id, "RUN", {
       childWorkflowId: wf.id,
@@ -480,133 +481,131 @@ export function buildCtx(args: CtxBuildArgs): WorkflowContext<unknown> {
       tags: opts?.tags ?? [],
       lockToVersion: opts?.lockToVersion,
       idempotencyKey: opts?.idempotencyKey,
-    });
-  }) as InvokeApi;
+    })
+  }) as InvokeApi
 
   const parallel: ParallelApi = async <T, R>(
     items: readonly T[],
     fn: (item: T, index: number) => Promise<R>,
     opts?: { concurrency?: number; settle?: boolean },
   ): Promise<R[]> => {
-    checkCancel();
-    const total = items.length;
-    if (total === 0) return [];
-    const concurrency = Math.max(1, opts?.concurrency ?? total);
-    const settle = opts?.settle ?? false;
+    checkCancel()
+    const total = items.length
+    if (total === 0) return []
+    const concurrency = Math.max(1, opts?.concurrency ?? total)
+    const settle = opts?.settle ?? false
 
-    const results: R[] = new Array(total);
-    const errors: { index: number; error: unknown }[] = [];
-    let cursor = 0;
-    let aborted = false;
+    const results: R[] = new Array(total)
+    const errors: { index: number; error: unknown }[] = []
+    let cursor = 0
+    let aborted = false
 
     async function worker(): Promise<void> {
       while (!aborted) {
-        const i = cursor++;
-        if (i >= total) return;
+        const i = cursor++
+        if (i >= total) return
         try {
-          results[i] = await fn(items[i]!, i);
+          results[i] = await fn(items[i]!, i)
         } catch (err) {
           if (settle) {
-            errors.push({ index: i, error: err });
+            errors.push({ index: i, error: err })
           } else {
-            aborted = true;
-            throw err;
+            aborted = true
+            throw err
           }
         }
       }
     }
 
-    const workerCount = Math.min(concurrency, total);
-    const workers = Array.from({ length: workerCount }, () => worker());
+    const workerCount = Math.min(concurrency, total)
+    const workers = Array.from({ length: workerCount }, () => worker())
 
     if (settle) {
-      await Promise.all(workers);
+      await Promise.all(workers)
       if (errors.length > 0) {
         // Attach details so callers can inspect which items failed.
         const agg = new AggregateError(
           errors.map((e) => (e.error instanceof Error ? e.error : new Error(String(e.error)))),
           `ctx.parallel: ${errors.length}/${total} iteration${errors.length === 1 ? "" : "s"} failed`,
-        );
-        (agg as { failedIndices?: number[] }).failedIndices = errors.map((e) => e.index);
-        throw agg;
+        )
+        ;(agg as { failedIndices?: number[] }).failedIndices = errors.map((e) => e.index)
+        throw agg
       }
-      return results;
+      return results
     }
 
-    await Promise.all(workers);
-    return results;
-  };
+    await Promise.all(workers)
+    return results
+  }
 
   // ---- streams ----
 
-  const activeStreamIds = new Set<string>();
+  const activeStreamIds = new Set<string>()
 
   async function consumeStream(
     streamId: string,
     source: AsyncIterable<unknown>,
     encoding: "text" | "json" | "base64",
   ): Promise<void> {
-    checkCancel();
+    checkCancel()
     if (activeStreamIds.has(streamId)) {
-      throw new Error(`ctx.stream: duplicate streamId "${streamId}" within the same run`);
+      throw new Error(`ctx.stream: duplicate streamId "${streamId}" within the same run`)
     }
-    activeStreamIds.add(streamId);
+    activeStreamIds.add(streamId)
     // Replay skip: the prior invocation already drained this source
     // and the orchestrator has the chunks. Re-iterating would double
     // any side effects (LLM calls, billable APIs, file reads).
     if (journal.streamsCompleted[streamId]) {
-      return;
+      return
     }
-    let seq = 0;
-    const iter = source[Symbol.asyncIterator]();
+    let seq = 0
+    const iter = source[Symbol.asyncIterator]()
     try {
       while (true) {
-        checkCancel();
-        const { value, done } = await iter.next();
+        checkCancel()
+        const { value, done } = await iter.next()
         if (done) {
-          callbacks.pushStreamChunk({ streamId, seq: seq + 1, encoding, chunk: null, final: true });
-          journal.streamsCompleted[streamId] = { chunkCount: seq + 1 };
-          return;
+          callbacks.pushStreamChunk({ streamId, seq: seq + 1, encoding, chunk: null, final: true })
+          journal.streamsCompleted[streamId] = { chunkCount: seq + 1 }
+          return
         }
-        seq += 1;
-        const chunk = normalizeChunk(value, encoding);
-        callbacks.pushStreamChunk({ streamId, seq, encoding, chunk, final: false });
+        seq += 1
+        const chunk = normalizeChunk(value, encoding)
+        callbacks.pushStreamChunk({ streamId, seq, encoding, chunk, final: false })
       }
     } catch (err) {
       // Emit a final frame so consumers know the stream closed, then
       // propagate so the workflow body's error handling kicks in. No
       // journal entry — a failed stream should re-iterate on replay
       // (so the error surfaces deterministically).
-      callbacks.pushStreamChunk({ streamId, seq: seq + 1, encoding, chunk: null, final: true });
-      throw err;
+      callbacks.pushStreamChunk({ streamId, seq: seq + 1, encoding, chunk: null, final: true })
+      throw err
     }
   }
 
   const streamImpl = async (
     streamId: string,
-    sourceOrFn:
-      | AsyncIterable<unknown>
-      | (() => AsyncGenerator<unknown>),
+    sourceOrFn: AsyncIterable<unknown> | (() => AsyncGenerator<unknown>),
   ): Promise<void> => {
     const source =
       typeof sourceOrFn === "function"
         ? (sourceOrFn as () => AsyncGenerator<unknown>)()
-        : sourceOrFn;
-    await consumeStream(streamId, source, inferEncoding(source));
-  };
+        : sourceOrFn
+    await consumeStream(streamId, source, inferEncoding(source))
+  }
 
   // Typed shape variants. Each forwards to consumeStream with a fixed encoding.
-  (streamImpl as unknown as { text: StreamApi["text"] }).text = async (id, source) => {
-    await consumeStream(id, source, "text");
-  };
-  (streamImpl as unknown as { json: StreamApi["json"] }).json = async (id, source) => {
-    await consumeStream(id, source, "json");
-  };
-  (streamImpl as unknown as { bytes: StreamApi["bytes"] }).bytes = async (id, source) => {
-    await consumeStream(id, source, "base64");
-  };
-
-  const stream = streamImpl as unknown as StreamApi;
+  ;(streamImpl as unknown as { text: StreamApi["text"] }).text = async (id, source) => {
+    await consumeStream(id, source, "text")
+  }
+  ;(streamImpl as unknown as { json: StreamApi["json"] }).json = async (id, source) => {
+    await consumeStream(id, source, "json")
+  }
+  ;(streamImpl as unknown as { bytes: StreamApi["bytes"] }).bytes = async (id, source) => {
+    await consumeStream(id, source, "base64")
+  }
+
+  const stream = streamImpl as unknown as StreamApi
 
   // ---- groups ----
 
@@ -621,11 +620,11 @@ export function buildCtx(args: CtxBuildArgs): WorkflowContext<unknown> {
   // outer list — they'll still be rolled back if the enclosing workflow
   // later throws.
   const runScopedCompensations = async (fromIndex: number): Promise<void> => {
-    const scopeEntries = callbacks.spliceCompensable(fromIndex);
+    const scopeEntries = callbacks.spliceCompensable(fromIndex)
     for (let i = scopeEntries.length - 1; i >= 0; i--) {
-      const c = scopeEntries[i]!;
+      const c = scopeEntries[i]!
       try {
-        await c.compensate(c.output);
+        await c.compensate(c.output)
       } catch {
         // One bad compensation in a scope does not abort the others.
         // Errors here don't surface to the executor — the outer rollback
@@ -633,54 +632,58 @@ export function buildCtx(args: CtxBuildArgs): WorkflowContext<unknown> {
         // unwind.
       }
     }
-  };
+  }
 
   const group: GroupApi = async <T>(
     _name: string,
     fn: (scope: GroupScope) => Promise<T>,
   ): Promise<T> => {
-    checkCancel();
-    const checkpointStart = callbacks.compensableLength();
+    checkCancel()
+    const checkpointStart = callbacks.compensableLength()
     try {
       return await fn({
         step,
         compensate: async (): Promise<never> => {
-          await runScopedCompensations(checkpointStart);
-          throw new CompensateRequestedSignal();
+          await runScopedCompensations(checkpointStart)
+          throw new CompensateRequestedSignal()
         },
-      });
+      })
     } catch (err) {
       // Only run scoped compensations for real user errors — internal
       // signals (waitpoint yield, cancellation, compensate-requested)
       // are re-thrown unchanged so the executor can route them.
-      if (
-        !isWaitpointPending(err) &&
-        !isRunCancelled(err) &&
-        !isCompensateRequested(err)
-      ) {
-        await runScopedCompensations(checkpointStart);
+      if (!isWaitpointPending(err) && !isRunCancelled(err) && !isCompensateRequested(err)) {
+        await runScopedCompensations(checkpointStart)
       }
-      throw err;
+      throw err
     }
-  };
+  }
 
   // ---- metadata ----
 
   const metadata: MetadataApi = {
-    set(key, value) { callbacks.pushMetadata({ op: "set", key, value }); },
-    increment(key, by = 1) { callbacks.pushMetadata({ op: "increment", key, value: by }); },
-    append(key, value) { callbacks.pushMetadata({ op: "append", key, value }); },
-    remove(key) { callbacks.pushMetadata({ op: "remove", key }); },
+    set(key, value) {
+      callbacks.pushMetadata({ op: "set", key, value })
+    },
+    increment(key, by = 1) {
+      callbacks.pushMetadata({ op: "increment", key, value: by })
+    },
+    append(key, value) {
+      callbacks.pushMetadata({ op: "append", key, value })
+    },
+    remove(key) {
+      callbacks.pushMetadata({ op: "remove", key })
+    },
     // Mutations are pushed immediately via `callbacks.pushMetadata`
     // and collected on the response envelope; no explicit flush is
     // needed.
     flush: async () => {},
-  };
+  }
 
   // ---- retry override ----
 
   function setRetry(policy: RetryPolicy): void {
-    retryOverride.current = policy;
+    retryOverride.current = policy
   }
 
   return {
@@ -706,10 +709,10 @@ export function buildCtx(args: CtxBuildArgs): WorkflowContext<unknown> {
     randomUUID: createRandomUUID(random),
     setRetry,
     compensate: async (): Promise<never> => {
-      checkCancel();
-      throw new CompensateRequestedSignal();
+      checkCancel()
+      throw new CompensateRequestedSignal()
     },
-  } satisfies WorkflowContext<unknown>;
+  } satisfies WorkflowContext<unknown>
 }
 
 // ---- helpers ----
@@ -717,92 +720,94 @@ export function buildCtx(args: CtxBuildArgs): WorkflowContext<unknown> {
 function inferEncoding(source: unknown): "text" | "json" | "base64" {
   // Default to json for the generic ctx.stream(id, generator) call. The
   // typed variants (text/json/bytes) override this.
-  void source;
-  return "json";
+  void source
+  return "json"
 }
 
 function normalizeChunk(value: unknown, encoding: "text" | "json" | "base64"): unknown {
   if (encoding === "text") {
-    return typeof value === "string" ? value : String(value);
+    return typeof value === "string" ? value : String(value)
   }
   if (encoding === "base64") {
     if (value instanceof Uint8Array) {
-      return toBase64(value);
+      return toBase64(value)
     }
-    throw new Error("ctx.stream.bytes: expected Uint8Array chunks");
+    throw new Error("ctx.stream.bytes: expected Uint8Array chunks")
   }
-  return value; // json — pass through
+  return value // json — pass through
 }
 
 function toBase64(bytes: Uint8Array): string {
   // Node + modern runtimes provide Buffer or btoa. Use Buffer when
   // available for efficiency; fall back to manual encode for isolates.
   const g = globalThis as unknown as {
-    Buffer?: { from(b: Uint8Array): { toString(enc: "base64"): string } };
-    btoa?: (s: string) => string;
-  };
-  if (g.Buffer) return g.Buffer.from(bytes).toString("base64");
+    Buffer?: { from(b: Uint8Array): { toString(enc: "base64"): string } }
+    btoa?: (s: string) => string
+  }
+  if (g.Buffer) return g.Buffer.from(bytes).toString("base64")
   if (g.btoa) {
-    let s = "";
-    for (let i = 0; i < bytes.length; i++) s += String.fromCharCode(bytes[i]!);
-    return g.btoa(s);
+    let s = ""
+    for (let i = 0; i < bytes.length; i++) s += String.fromCharCode(bytes[i]!)
+    return g.btoa(s)
   }
   // Manual fallback (rare).
-  const chars = "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789+/";
-  let out = "";
-  let i = 0;
+  const chars = "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789+/"
+  let out = ""
+  let i = 0
   while (i < bytes.length) {
-    const b1 = bytes[i++]!;
-    const b2 = i < bytes.length ? bytes[i++]! : 0;
-    const b3 = i < bytes.length ? bytes[i++]! : 0;
-    out += chars[b1 >> 2]!;
-    out += chars[((b1 & 3) << 4) | (b2 >> 4)]!;
-    out += i - 1 > bytes.length ? "=" : chars[((b2 & 15) << 2) | (b3 >> 6)]!;
-    out += i > bytes.length ? "=" : chars[b3 & 63]!;
+    const b1 = bytes[i++]!
+    const b2 = i < bytes.length ? bytes[i++]! : 0
+    const b3 = i < bytes.length ? bytes[i++]! : 0
+    out += chars[b1 >> 2]!
+    out += chars[((b1 & 3) << 4) | (b2 >> 4)]!
+    out += i - 1 > bytes.length ? "=" : chars[((b2 & 15) << 2) | (b3 >> 6)]!
+    out += i > bytes.length ? "=" : chars[b3 & 63]!
   }
-  return out;
+  return out
 }
 
 interface ResolvedRetryPolicy {
-  max: number;
-  backoff: "exponential" | "linear" | "fixed";
-  initial: number;   // ms
-  maxDelay: number;  // ms
+  max: number
+  backoff: "exponential" | "linear" | "fixed"
+  initial: number // ms
+  maxDelay: number // ms
 }
 
-function normalizeRetry(
-  input: RetryPolicy | { max: 0 } | undefined,
-): ResolvedRetryPolicy {
-  if (!input) return { max: 1, backoff: "exponential", initial: 1000, maxDelay: 60_000 };
-  const max = input.max ?? 3;
-  const policy = input as RetryPolicy;
+function normalizeRetry(input: RetryPolicy | { max: 0 } | undefined): ResolvedRetryPolicy {
+  if (!input) return { max: 1, backoff: "exponential", initial: 1000, maxDelay: 60_000 }
+  const max = input.max ?? 3
+  const policy = input as RetryPolicy
   return {
     max: Math.max(1, max),
     backoff: policy.backoff ?? "exponential",
     initial: policy.initial !== undefined ? toMs(policy.initial) : 1000,
     maxDelay: policy.maxDelay !== undefined ? toMs(policy.maxDelay) : 60_000,
-  };
+  }
 }
 
 function backoffDelay(policy: ResolvedRetryPolicy, attempt: number): number {
   // `attempt` is 1-indexed; delay applies *before* the next attempt.
-  if (policy.backoff === "fixed") return Math.min(policy.initial, policy.maxDelay);
-  if (policy.backoff === "linear") return Math.min(policy.initial * attempt, policy.maxDelay);
+  if (policy.backoff === "fixed") return Math.min(policy.initial, policy.maxDelay)
+  if (policy.backoff === "linear") return Math.min(policy.initial * attempt, policy.maxDelay)
   // exponential
-  return Math.min(policy.initial * Math.pow(2, attempt - 1), policy.maxDelay);
+  return Math.min(policy.initial * 2 ** (attempt - 1), policy.maxDelay)
 }
 
 function readRetryAfter(err: SerializedError | undefined): number | undefined {
-  if (!err) return undefined;
-  if (err.code !== "RETRYABLE") return undefined;
-  const raw = (err.data as { retryAfter?: unknown } | undefined)?.retryAfter;
-  if (raw === undefined) return undefined;
-  if (typeof raw === "number") return raw;
-  if (raw instanceof Date) return raw.getTime() - Date.now();
+  if (!err) return undefined
+  if (err.code !== "RETRYABLE") return undefined
+  const raw = (err.data as { retryAfter?: unknown } | undefined)?.retryAfter
+  if (raw === undefined) return undefined
+  if (typeof raw === "number") return raw
+  if (raw instanceof Date) return raw.getTime() - Date.now()
   if (typeof raw === "string") {
-    try { return toMs(raw as Duration); } catch { return undefined; }
+    try {
+      return toMs(raw as Duration)
+    } catch {
+      return undefined
+    }
   }
-  return undefined;
+  return undefined
 }
 
 /**
@@ -812,27 +817,34 @@ function readRetryAfter(err: SerializedError | undefined): number | undefined {
  * through `setTimeout(0)` at most) so the suite stays fast.
  */
 async function maybeDelay(ms: number): Promise<void> {
-  if (ms <= 0) return;
+  if (ms <= 0) return
   // Cap at 10ms in-process regardless of declared delay. Test harness
   // doesn't model real time; production replaces this with a DO alarm.
-  await new Promise((resolve) => setTimeout(resolve, Math.min(ms, 10)));
+  await new Promise((resolve) => setTimeout(resolve, Math.min(ms, 10)))
 }
 
 function toMs(d: Duration): number {
-  if (typeof d === "number") return d;
-  const m = /^(\d+)(ms|s|m|h|d|w)$/.exec(d);
-  if (!m) throw new Error(`invalid duration: ${String(d)}`);
-  const n = Number(m[1]);
+  if (typeof d === "number") return d
+  const m = /^(\d+)(ms|s|m|h|d|w)$/.exec(d)
+  if (!m) throw new Error(`invalid duration: ${String(d)}`)
+  const n = Number(m[1])
   switch (m[2]) {
-    case "ms": return n;
-    case "s":  return n * 1000;
-    case "m":  return n * 60_000;
-    case "h":  return n * 3_600_000;
-    case "d":  return n * 86_400_000;
-    case "w":  return n * 604_800_000;
-    default:   throw new Error(`invalid duration unit: ${m[2]}`);
+    case "ms":
+      return n
+    case "s":
+      return n * 1000
+    case "m":
+      return n * 60_000
+    case "h":
+      return n * 3_600_000
+    case "d":
+      return n * 86_400_000
+    case "w":
+      return n * 604_800_000
+    default:
+      throw new Error(`invalid duration unit: ${m[2]}`)
   }
 }
 
 // Re-exports used by the executor for metadata type checking.
-export type { MetadataValue };
+export type { MetadataValue }