@voyantjs/workflows 0.0.0

package/src/runtime/ctx.ts

@@ -0,0 +1,838 @@
+// Builds the `ctx` object passed to the workflow body.
+//
+// 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 {
+  EnvironmentContext,
+  MetadataApi,
+  MetadataValue,
+  ParallelApi,
+  RunContext,
+  StepApi,
+  StepContext,
+  StepFn,
+  StepOptions,
+  StreamApi,
+  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";
+import {
+  WaitpointPendingSignal,
+  RunCancelledSignal,
+  CompensateRequestedSignal,
+  isWaitpointPending,
+  isRunCancelled,
+  isCompensateRequested,
+} from "./errors.js";
+import {
+  type ClockState,
+  advanceClockTo,
+  createRandomUUID,
+  now,
+} from "./determinism.js";
+
+/**
+ * Callbacks the executor provides for operations that must reach the
+ * orchestrator (over HTTP in production, in-memory in tests).
+ */
+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>;
+
+  /**
+   * Called when a step completes successfully and had a `compensate`
+   * function declared. The executor collects these in completion order
+   * and runs them in reverse if the body throws or `ctx.compensate()`
+   * is invoked.
+   */
+  recordCompensable(args: {
+    stepId: string;
+    output: unknown;
+    compensate: (output: unknown) => Promise<void>;
+  }): void;
+
+  /** Current length of the compensable list. Used by `ctx.group` checkpoints. */
+  compensableLength(): number;
+
+  /**
+   * Remove and return compensables added since `fromIndex`. Used by
+   * `ctx.group` to run scoped rollback without touching outer
+   * compensables.
+   */
+  spliceCompensable(fromIndex: number): Array<{
+    stepId: string;
+    output: unknown;
+    compensate: (output: unknown) => Promise<void>;
+  }>;
+
+  /**
+   * Called by `ctx.stream()` for each chunk produced by the source.
+   * In production this emits a `stream.chunk` WebSocket event and
+   * journals the chunk; in tests the harness collects chunks.
+   */
+  pushStreamChunk(args: {
+    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;
+
+  /** 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;
+
+  /** Increment invocation counter when the body resumes after eviction. */
+  readonly invocationCount: number;
+
+  /** Cancellation signal exposed as `ctx.signal`. */
+  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 };
+}
+
+export interface CtxBuildArgs {
+  env: RuntimeEnvironment;
+  journal: JournalSlice;
+  callbacks: RuntimeCallbacks;
+  clock: ClockState;
+  random: () => number;
+  /** Mutated as ctx.setRetry is called; each step option inherits. */
+  retryOverride: { current: RetryPolicy | undefined };
+}
+
+export function buildCtx(args: CtxBuildArgs): WorkflowContext<unknown> {
+  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;
+
+  function checkCancel(): void {
+    if (callbacks.abortSignal.aborted) {
+      throw new RunCancelledSignal();
+    }
+  }
+
+  // ---- step ----
+
+  const step: StepApi = (async (
+    id: string,
+    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>);
+
+    // Journal hit? Return cached.
+    const cached = journal.stepResults[id];
+    if (cached) {
+      advanceClockTo(clock, cached.finishedAt);
+      if (cached.status === "ok") {
+        // Re-register compensable on replay so compensations are available
+        // if this invocation ends up rolling back.
+        if (opts.compensate) {
+          callbacks.recordCompensable({
+            stepId: id,
+            output: cached.output,
+            compensate: opts.compensate as (output: unknown) => Promise<void>,
+          });
+        }
+        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;
+    }
+
+    // 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;
+
+    // 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 fnWithTimeout: StepFn<unknown> =
+      timeoutMs !== undefined
+        ? async (stepCtx) => {
+            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);
+                }),
+              ]);
+            } finally {
+              if (timer !== undefined) clearTimeout(timer);
+            }
+          }
+        : fn;
+
+    while (attempt < policy.max) {
+      attempt += 1;
+      const stepCtx: StepContext = {
+        signal:
+          timeoutMs !== undefined
+            ? AbortSignal.any([callbacks.abortSignal, AbortSignal.timeout(timeoutMs)])
+            : callbacks.abortSignal,
+        attempt,
+        log: (level, msg, data) => {
+          console[level === "error" ? "error" : level === "warn" ? "warn" : "log"](`[${id}]`, msg, data ?? "");
+        },
+      };
+      const entry = await callbacks.runStep({
+        stepId: id,
+        attempt,
+        input: undefined,
+        options: mergedOpts,
+        fn: fnWithTimeout,
+        stepCtx,
+      });
+      lastEntry = entry;
+
+      if (entry.status === "ok") {
+        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;
+      }
+
+      // Failed attempt. Check if we should stop retrying.
+      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));
+    }
+
+    // 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;
+
+  // ---- waits ----
+
+  function yieldWaitpoint(
+    clientWaitpointId: string,
+    kind: WaitpointKind,
+    meta: Record<string, unknown>,
+    timeoutMs?: number,
+  ): never {
+    callbacks.registerWaitpoint({ clientWaitpointId, kind, meta, timeoutMs });
+    throw new WaitpointPendingSignal(clientWaitpointId);
+  }
+
+  function lookupWaitpoint(id: string): WaitpointResolutionEntry | undefined {
+    return journal.waitpointsResolved[id];
+  }
+
+  const sleep = async (duration: Duration): Promise<void> => {
+    checkCancel();
+    const id = `sleep:${nextClientId()}`;
+    const resolved = lookupWaitpoint(id);
+    if (resolved) {
+      advanceClockTo(clock, resolved.resolvedAt);
+      return;
+    }
+    const ms = toMs(duration);
+    yieldWaitpoint(id, "DATETIME", { durationMs: ms }, ms);
+  };
+
+  function makeWaitable<T>(
+    kind: WaitpointKind,
+    clientWaitpointId: string,
+    iterIdPrefix: string,
+    meta: Record<string, unknown>,
+    timeoutMs?: number,
+    onTimeout: "null" | "throw" = "null",
+  ): Waitable<T> {
+    // --- thenable: single first-match-wins resolution ---
+    const resolve = (): T | null => {
+      const resolved = lookupWaitpoint(clientWaitpointId);
+      if (!resolved) {
+        yieldWaitpoint(clientWaitpointId, kind, meta, timeoutMs);
+      }
+      advanceClockTo(clock, resolved.resolvedAt);
+      if (resolved.payload === undefined && onTimeout === "throw") {
+        throw new Error(`waitpoint ${clientWaitpointId} timed out`);
+      }
+      return (resolved.payload ?? null) as T | null;
+    };
+
+    // --- iterable: fresh waitpoint per .next() call ---
+    function makeIterator(): AsyncIterableIterator<T> {
+      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 (!resolvedIter) {
+            yieldWaitpoint(iterId, kind, { ...meta, iter: true }, timeoutMs);
+          }
+          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;
+          if (isStreamEnd(payload)) {
+            closed = true;
+            return { value: undefined as unknown as T, done: true };
+          }
+          if (payload === undefined && onTimeout === "throw") {
+            throw new Error(`waitpoint ${iterId} timed out`);
+          }
+          return { value: payload as T, done: false };
+        },
+        async return(): Promise<IteratorResult<T>> {
+          closed = true;
+          return { value: undefined as unknown as T, done: true };
+        },
+        [Symbol.asyncIterator]() {
+          return this;
+        },
+      };
+    }
+
+    const thenable: Waitable<T> = {
+      then(onFulfilled, onRejected) {
+        try {
+          const r = resolve();
+          return Promise.resolve(r).then(onFulfilled, onRejected);
+        } catch (e) {
+          return Promise.reject(e).then(onFulfilled, onRejected);
+        }
+      },
+      [Symbol.asyncIterator]() {
+        return makeIterator();
+      },
+      close() {
+        // no-op; `return()` on the iterator handles early break.
+      },
+    };
+    return thenable;
+  }
+
+  function isStreamEnd(payload: unknown): boolean {
+    return (
+      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}`;
+    return makeWaitable(
+      "EVENT",
+      thenableId,
+      iterPrefix,
+      { eventType },
+      opts?.timeout ? toMs(opts.timeout) : undefined,
+      opts?.onTimeout,
+    );
+  }) as WaitForEventApi;
+
+  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,
+      iterPrefix,
+      { signalName: name },
+      opts?.timeout ? toMs(opts.timeout) : undefined,
+      opts?.onTimeout,
+    );
+  }) as WaitForSignalApi;
+
+  const waitForToken: WaitForTokenApi = (async (opts?: {
+    tokenId?: string;
+    timeout?: Duration;
+    onTimeout?: "null" | "throw";
+  }) => {
+    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";
+
+    return {
+      tokenId,
+      url: `/__voyant/tokens/${tokenId}`,
+      wait: async (): Promise<unknown> => {
+        checkCancel();
+        const resolved = lookupWaitpoint(waitpointId);
+        if (resolved) {
+          advanceClockTo(clock, resolved.resolvedAt);
+          if (resolved.payload === undefined && onTimeout === "throw") {
+            throw new Error(`token ${tokenId} timed out`);
+          }
+          return resolved.payload ?? null;
+        }
+        yieldWaitpoint(waitpointId, "MANUAL", { tokenId }, timeoutMs);
+      },
+    } as TokenWait<unknown>;
+  }) as WaitForTokenApi;
+
+  // ---- invoke / parallel ----
+
+  const invoke: InvokeApi = (async <TIn, TOut>(
+    wf: WorkflowHandle<TIn, TOut>,
+    input: TIn,
+    opts?: InvokeOptions,
+  ): Promise<TOut> => {
+    checkCancel();
+    const id = `invoke:${wf.id}:${nextClientId()}`;
+    const resolved = journal.waitpointsResolved[id];
+    if (resolved) {
+      advanceClockTo(clock, resolved.resolvedAt);
+      if (resolved.error) {
+        const e = new Error(resolved.error.message);
+        (e as { code?: string }).code = resolved.error.code;
+        throw e;
+      }
+      return resolved.payload as TOut;
+    }
+    yieldWaitpoint(id, "RUN", {
+      childWorkflowId: wf.id,
+      childInput: input,
+      detach: opts?.detach ?? false,
+      tags: opts?.tags ?? [],
+      lockToVersion: opts?.lockToVersion,
+      idempotencyKey: opts?.idempotencyKey,
+    });
+  }) 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;
+
+    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;
+        try {
+          results[i] = await fn(items[i]!, i);
+        } catch (err) {
+          if (settle) {
+            errors.push({ index: i, error: err });
+          } else {
+            aborted = true;
+            throw err;
+          }
+        }
+      }
+    }
+
+    const workerCount = Math.min(concurrency, total);
+    const workers = Array.from({ length: workerCount }, () => worker());
+
+    if (settle) {
+      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;
+      }
+      return results;
+    }
+
+    await Promise.all(workers);
+    return results;
+  };
+
+  // ---- streams ----
+
+  const activeStreamIds = new Set<string>();
+
+  async function consumeStream(
+    streamId: string,
+    source: AsyncIterable<unknown>,
+    encoding: "text" | "json" | "base64",
+  ): Promise<void> {
+    checkCancel();
+    if (activeStreamIds.has(streamId)) {
+      throw new Error(`ctx.stream: duplicate streamId "${streamId}" within the same run`);
+    }
+    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;
+    }
+    let seq = 0;
+    const iter = source[Symbol.asyncIterator]();
+    try {
+      while (true) {
+        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;
+        }
+        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;
+    }
+  }
+
+  const streamImpl = async (
+    streamId: string,
+    sourceOrFn:
+      | AsyncIterable<unknown>
+      | (() => AsyncGenerator<unknown>),
+  ): Promise<void> => {
+    const source =
+      typeof sourceOrFn === "function"
+        ? (sourceOrFn as () => AsyncGenerator<unknown>)()
+        : 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;
+
+  // ---- groups ----
+
+  // `ctx.group(name, fn)` creates a compensation scope. Implementation
+  // strategy: the outer compensable list is the single source of truth;
+  // each group tracks a checkpoint index. If the scope's body throws or
+  // explicitly calls `scope.compensate()`, we splice off compensables
+  // added since the checkpoint and run them LIFO, leaving outer
+  // compensables untouched.
+  //
+  // If the scope body completes normally, compensables stay in the
+  // 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);
+    for (let i = scopeEntries.length - 1; i >= 0; i--) {
+      const c = scopeEntries[i]!;
+      try {
+        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
+        // machinery only sees the user error that triggered the scope
+        // unwind.
+      }
+    }
+  };
+
+  const group: GroupApi = async <T>(
+    _name: string,
+    fn: (scope: GroupScope) => Promise<T>,
+  ): Promise<T> => {
+    checkCancel();
+    const checkpointStart = callbacks.compensableLength();
+    try {
+      return await fn({
+        step,
+        compensate: async (): Promise<never> => {
+          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);
+      }
+      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 }); },
+    // 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;
+  }
+
+  return {
+    run: env.run,
+    workflow: env.workflow,
+    environment: env.environment,
+    project: env.project,
+    organization: env.organization,
+    invocationCount: callbacks.invocationCount,
+    signal: callbacks.abortSignal,
+    step,
+    sleep,
+    waitForEvent,
+    waitForSignal,
+    waitForToken,
+    invoke,
+    parallel,
+    stream,
+    group,
+    metadata,
+    now: () => now(clock),
+    random,
+    randomUUID: createRandomUUID(random),
+    setRetry,
+    compensate: async (): Promise<never> => {
+      checkCancel();
+      throw new CompensateRequestedSignal();
+    },
+  } satisfies WorkflowContext<unknown>;
+}
+
+// ---- helpers ----
+
+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";
+}
+
+function normalizeChunk(value: unknown, encoding: "text" | "json" | "base64"): unknown {
+  if (encoding === "text") {
+    return typeof value === "string" ? value : String(value);
+  }
+  if (encoding === "base64") {
+    if (value instanceof Uint8Array) {
+      return toBase64(value);
+    }
+    throw new Error("ctx.stream.bytes: expected Uint8Array chunks");
+  }
+  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");
+  if (g.btoa) {
+    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;
+  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]!;
+  }
+  return out;
+}
+
+interface ResolvedRetryPolicy {
+  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;
+  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);
+  // exponential
+  return Math.min(policy.initial * Math.pow(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 (typeof raw === "string") {
+    try { return toMs(raw as Duration); } catch { return undefined; }
+  }
+  return undefined;
+}
+
+/**
+ * In the real runtime, retry delay is expressed to the orchestrator as a
+ * `retryAfter` field on the step callback response, and the DO sets an
+ * alarm — no worker sits idle. In tests we skip the delay (pass it
+ * through `setTimeout(0)` at most) so the suite stays fast.
+ */
+async function maybeDelay(ms: number): Promise<void> {
+  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)));
+}
+
+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]);
+  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]}`);
+  }
+}
+
+// Re-exports used by the executor for metadata type checking.
+export type { MetadataValue };