@voyantjs/workflows 0.0.0

package/src/testing/index.ts

@@ -0,0 +1,729 @@
+// @voyantjs/workflows/testing
+//
+// In-process test harness with mocked steps, waits, and invokes.
+// Contract in docs/sdk-surface.md §11.
+//
+// Drives `executeWorkflowStep` across resumptions. Steps resolve
+// from a user-supplied stub map; waitpoints resolve from fixtures.
+
+import type { WorkflowHandle, StepContext, EnvironmentContext, MetadataValue } from "../workflow.js";
+import type { WorkflowDefinition } from "../workflow.js";
+import { getWorkflow } from "../workflow.js";
+import type { RunStatus } from "../types.js";
+import type { SerializedError } from "../protocol/index.js";
+import { executeWorkflowStep, type CompensationReport, type ExecuteWorkflowStepResponse, type MetadataMutation, type StreamChunk, type WaitpointRegistration } from "../runtime/executor.js";
+import type { JournalSlice, StepJournalEntry, WaitpointResolutionEntry } from "../runtime/journal.js";
+import { emptyJournal } from "../runtime/journal.js";
+
+export interface TestOptions<_TIn> {
+  /** Map of stepId → function run in place of the real step body. */
+  steps?: Record<string, (stepCtx: StepContext) => unknown | Promise<unknown>>;
+  /**
+   * Map of eventType → payload (or payload array). First
+   * match-per-eventType wins.
+   */
+  waitForEvent?: Record<string, unknown | unknown[]>;
+  /** Map of signalName → payload. */
+  waitForSignal?: Record<string, unknown>;
+  /** Map of tokenId → payload. */
+  waitForToken?: Record<string, unknown>;
+  /** Workflow invoke stubs keyed by child workflow id. */
+  invoke?: Record<string, unknown>;
+  /** Fake env bindings, passed through to `ctx.environment` for tests. */
+  env?: Record<string, unknown>;
+  environment?: Partial<EnvironmentContext>;
+  /** Fixed wall-clock basis for the run. Defaults to Date.now(). */
+  now?: () => number;
+  random?: () => number;
+  /** Max resumption cycles. Defaults to 16 — guards runaway loops. */
+  maxInvocations?: number;
+  /**
+   * When true, the harness stops and returns a "waiting" TestResult as
+   * soon as any registered waitpoint has no fixture resolution (instead
+   * of throwing). Callers can then persist the run and resume it later
+   * via `resumeWorkflowForTest` once the waitpoint is resolved from a
+   * live source (e.g. a dashboard HTTP injection).
+   *
+   * DATETIME waitpoints (sleeps) are always auto-resolved regardless of
+   * this flag, since a local dev loop is not the right place to
+   * synthesize wall-clock delays.
+   */
+  pauseOnWait?: boolean;
+}
+
+export interface TestResult<TOut> {
+  status: Extract<
+    RunStatus,
+    "completed" | "failed" | "cancelled" | "compensated" | "compensation_failed" | "waiting"
+  >;
+  output?: TOut;
+  error?: { category: SerializedError["category"]; code: string; message: string };
+  steps: { id: string; status: "ok" | "err" | "skipped"; duration: number; output?: unknown }[];
+  events: { type: string; at: number; data: unknown }[];
+  metadata: Record<string, MetadataValue>;
+  compensations: CompensationReport[];
+  /** Chunks emitted via `ctx.stream()` / `ctx.stream.{text,json,bytes}`, grouped by streamId in emission order. */
+  streams: Record<string, StreamChunk[]>;
+  invocations: number;
+  /**
+   * Populated when `status === "waiting"`. Holds the persisted executor
+   * state needed to resume the run via `resumeWorkflowForTest`.
+   */
+  pause?: {
+    journal: JournalSlice;
+    pendingWaitpoints: WaitpointRegistration[];
+    startedAt: number;
+    invocationCount: number;
+    metadataAppliedCount: number;
+    fixtureCursors: { event: Record<string, number>; signal: Record<string, number> };
+  };
+}
+
+export async function runWorkflowForTest<TIn, TOut>(
+  workflow: WorkflowHandle<TIn, TOut>,
+  input: TIn,
+  opts: TestOptions<TIn> = {},
+): Promise<TestResult<TOut>> {
+  const def = workflow as WorkflowDefinition<TIn, TOut>;
+  const now = opts.now ?? (() => Date.now());
+  const startedAt = now();
+  const journal: JournalSlice = emptyJournal();
+  const metadata: Record<string, MetadataValue> = {};
+  const events: TestResult<TOut>["events"] = [];
+  const streams: Record<string, StreamChunk[]> = {};
+  const maxInvocations = opts.maxInvocations ?? 16;
+
+  const environment: EnvironmentContext = {
+    name: opts.environment?.name ?? "development",
+    git: opts.environment?.git,
+  };
+
+  let invocationCount = 0;
+  let last: ExecuteWorkflowStepResponse | undefined;
+  // Track how many metadata mutations have already been applied so we
+  // only apply the delta on each invocation. Otherwise replays
+  // double-count `increment` / duplicate `append` values. (Positional
+  // dedup; mirrors what the real orchestrator does with journaled ids.)
+  let metadataAppliedCount = 0;
+  // Per-fixture cursors into iterable event/signal arrays, persisted
+  // across invocations so replay doesn't restart consumption.
+  const cursors: FixtureCursors = { event: new Map(), signal: new Map() };
+
+  while (invocationCount < maxInvocations) {
+    invocationCount += 1;
+
+    const response = await executeWorkflowStep(def as unknown as WorkflowDefinition, {
+      runId: `run_test_${def.id}`,
+      workflowId: def.id,
+      workflowVersion: "test",
+      input,
+      journal,
+      invocationCount,
+      environment: {
+        run: {
+          id: `run_test_${def.id}`,
+          number: 1,
+          attempt: 1,
+          triggeredBy: { kind: "api" },
+          tags: [],
+          startedAt,
+        },
+        workflow: { id: def.id, version: "test" },
+        environment,
+        project: { id: "prj_test", slug: "test" },
+        organization: { id: "org_test", slug: "test" },
+      },
+      triggeredBy: { kind: "api" },
+      runStartedAt: startedAt,
+      tags: [],
+      stepRunner: createStepRunner(opts, events, now),
+    });
+
+    last = response;
+
+    const newMutations = response.metadataUpdates.slice(metadataAppliedCount);
+    applyMetadata(metadata, newMutations);
+    metadataAppliedCount = response.metadataUpdates.length;
+
+    for (const chunk of response.streamChunks) {
+      const bucket = streams[chunk.streamId] ??= [];
+      bucket.push(chunk);
+    }
+
+    if (response.status === "completed") {
+      return {
+        status: "completed",
+        output: response.output as TOut,
+        steps: stepsFromJournal(journal),
+        events,
+        metadata,
+        compensations: [],
+        streams,
+        invocations: invocationCount,
+      };
+    }
+
+    if (response.status === "failed") {
+      return {
+        status: "failed",
+        error: { category: response.error.category, code: response.error.code, message: response.error.message },
+        steps: stepsFromJournal(journal),
+        events,
+        metadata,
+        compensations: [],
+        streams,
+        invocations: invocationCount,
+      };
+    }
+
+    if (response.status === "cancelled") {
+      return {
+        status: "cancelled",
+        steps: stepsFromJournal(journal),
+        events,
+        metadata,
+        compensations: response.compensations,
+        streams,
+        invocations: invocationCount,
+      };
+    }
+
+    if (response.status === "compensated" || response.status === "compensation_failed") {
+      return {
+        status: response.status,
+        error: response.error
+          ? {
+              category: response.error.category,
+              code: response.error.code,
+              message: response.error.message,
+            }
+          : undefined,
+        steps: stepsFromJournal(journal),
+        events,
+        metadata,
+        compensations: response.compensations,
+        streams,
+        invocations: invocationCount,
+      };
+    }
+
+    // Waiting: resolve waitpoints from fixtures and loop. Waitpoints
+    // that have no fixture match either throw (default) or, when
+    // `pauseOnWait` is set, park the run and return a "waiting" result.
+    const stillPending: WaitpointRegistration[] = [];
+    for (const wp of response.waitpoints) {
+      const resolved = await resolveWaitpoint(wp, opts, now, events, cursors);
+      if (!resolved) {
+        if (opts.pauseOnWait) {
+          stillPending.push(wp);
+          continue;
+        }
+        throw new Error(
+          `test harness: waitpoint ${wp.clientWaitpointId} (${wp.kind}) has no fixture resolution. ` +
+            `Provide one via TestOptions.waitForEvent / waitForSignal / (sleeps auto-resolve), ` +
+            `or set TestOptions.pauseOnWait to park the run.`,
+        );
+      }
+      journal.waitpointsResolved[wp.clientWaitpointId] = resolved;
+      events.push({ type: `waitpoint.resolved:${wp.kind}`, at: resolved.resolvedAt, data: resolved.payload ?? null });
+    }
+    if (stillPending.length > 0) {
+      return {
+        status: "waiting",
+        steps: stepsFromJournal(journal),
+        events,
+        metadata,
+        compensations: [],
+        streams,
+        invocations: invocationCount,
+        pause: {
+          journal,
+          pendingWaitpoints: stillPending,
+          startedAt,
+          invocationCount,
+          metadataAppliedCount,
+          fixtureCursors: {
+            event: Object.fromEntries(cursors.event.entries()),
+            signal: Object.fromEntries(cursors.signal.entries()),
+          },
+        },
+      };
+    }
+  }
+
+  throw new Error(
+    `test harness exceeded maxInvocations (${maxInvocations}). ` +
+      `Last status: ${last?.status ?? "<none>"}. Possible infinite waitpoint loop.`,
+  );
+}
+
+/**
+ * A single injected waitpoint resolution — the tenant-side analogue of
+ * the orchestrator delivering an event, signal, or token payload to a
+ * parked run. The matcher (`kind` + `key`) identifies which pending
+ * waitpoint to resolve; `payload` is the value surfaced to the body.
+ */
+export type WaitpointInjection =
+  | { kind: "EVENT"; eventType: string; payload?: unknown }
+  | { kind: "SIGNAL"; name: string; payload?: unknown }
+  | { kind: "MANUAL"; tokenId: string; payload?: unknown };
+
+export interface ResumeOptions<TIn> extends TestOptions<TIn> {
+  /** Persisted pause state returned from a previous `runWorkflowForTest` or `resumeWorkflowForTest`. */
+  pause: NonNullable<TestResult<unknown>["pause"]>;
+  /** The single waitpoint resolution to inject on resume. */
+  injection: WaitpointInjection;
+}
+
+/**
+ * Resume a parked run. Matches the injection against one of the
+ * `pause.pendingWaitpoints`, records it in the journal, and re-enters
+ * the executor loop until the next pause or terminal state.
+ */
+export async function resumeWorkflowForTest<TIn, TOut>(
+  workflow: WorkflowHandle<TIn, TOut>,
+  input: TIn,
+  opts: ResumeOptions<TIn>,
+): Promise<TestResult<TOut>> {
+  const def = workflow as WorkflowDefinition<TIn, TOut>;
+  const now = opts.now ?? (() => Date.now());
+  const maxInvocations = opts.maxInvocations ?? 16;
+
+  const matched = matchWaitpoint(opts.pause.pendingWaitpoints, opts.injection);
+  if (!matched) {
+    throw new Error(
+      `resume: no pending waitpoint matches injection kind=${opts.injection.kind}, ` +
+        `key=${injectionKey(opts.injection)}`,
+    );
+  }
+
+  const journal = cloneJournal(opts.pause.journal);
+  journal.waitpointsResolved[matched.clientWaitpointId] = {
+    kind: matched.kind,
+    resolvedAt: now(),
+    payload: opts.injection.payload,
+    source: "live",
+    matchedEventId: opts.injection.kind === "EVENT" ? `evt_live_${opts.injection.eventType}` : undefined,
+  };
+
+  const events: TestResult<TOut>["events"] = [
+    {
+      type: `waitpoint.resolved:${matched.kind}`,
+      at: now(),
+      data: opts.injection.payload ?? null,
+    },
+  ];
+  const metadata: Record<string, MetadataValue> = {};
+  const streams: Record<string, StreamChunk[]> = {};
+  const cursors: FixtureCursors = {
+    event: new Map(Object.entries(opts.pause.fixtureCursors.event)),
+    signal: new Map(Object.entries(opts.pause.fixtureCursors.signal)),
+  };
+
+  const environment: EnvironmentContext = {
+    name: opts.environment?.name ?? "development",
+    git: opts.environment?.git,
+  };
+
+  let invocationCount = opts.pause.invocationCount;
+  let metadataAppliedCount = opts.pause.metadataAppliedCount;
+  let last: ExecuteWorkflowStepResponse | undefined;
+
+  // Remaining pending waitpoints from the previous pause (still parked).
+  let carryover = opts.pause.pendingWaitpoints.filter((w) => w.clientWaitpointId !== matched.clientWaitpointId);
+
+  while (invocationCount < maxInvocations) {
+    invocationCount += 1;
+
+    const response = await executeWorkflowStep(def as unknown as WorkflowDefinition, {
+      runId: `run_test_${def.id}`,
+      workflowId: def.id,
+      workflowVersion: "test",
+      input,
+      journal,
+      invocationCount,
+      environment: {
+        run: {
+          id: `run_test_${def.id}`,
+          number: 1,
+          attempt: 1,
+          triggeredBy: { kind: "api" },
+          tags: [],
+          startedAt: opts.pause.startedAt,
+        },
+        workflow: { id: def.id, version: "test" },
+        environment,
+        project: { id: "prj_test", slug: "test" },
+        organization: { id: "org_test", slug: "test" },
+      },
+      triggeredBy: { kind: "api" },
+      runStartedAt: opts.pause.startedAt,
+      tags: [],
+      stepRunner: createStepRunner(opts, events, now),
+    });
+
+    last = response;
+
+    const newMutations = response.metadataUpdates.slice(metadataAppliedCount);
+    applyMetadata(metadata, newMutations);
+    metadataAppliedCount = response.metadataUpdates.length;
+
+    for (const chunk of response.streamChunks) {
+      const bucket = streams[chunk.streamId] ??= [];
+      bucket.push(chunk);
+    }
+
+    if (response.status === "completed") {
+      return {
+        status: "completed",
+        output: response.output as TOut,
+        steps: stepsFromJournal(journal),
+        events,
+        metadata,
+        compensations: [],
+        streams,
+        invocations: invocationCount,
+      };
+    }
+    if (response.status === "failed") {
+      return {
+        status: "failed",
+        error: { category: response.error.category, code: response.error.code, message: response.error.message },
+        steps: stepsFromJournal(journal),
+        events,
+        metadata,
+        compensations: [],
+        streams,
+        invocations: invocationCount,
+      };
+    }
+    if (response.status === "cancelled") {
+      return {
+        status: "cancelled",
+        steps: stepsFromJournal(journal),
+        events,
+        metadata,
+        compensations: response.compensations,
+        streams,
+        invocations: invocationCount,
+      };
+    }
+    if (response.status === "compensated" || response.status === "compensation_failed") {
+      return {
+        status: response.status,
+        error: response.error
+          ? { category: response.error.category, code: response.error.code, message: response.error.message }
+          : undefined,
+        steps: stepsFromJournal(journal),
+        events,
+        metadata,
+        compensations: response.compensations,
+        streams,
+        invocations: invocationCount,
+      };
+    }
+
+    const stillPending: WaitpointRegistration[] = [...carryover];
+    for (const wp of response.waitpoints) {
+      const resolved = await resolveWaitpoint(wp, opts, now, events, cursors);
+      if (!resolved) {
+        if (opts.pauseOnWait) {
+          stillPending.push(wp);
+          continue;
+        }
+        throw new Error(
+          `resume: waitpoint ${wp.clientWaitpointId} (${wp.kind}) has no fixture resolution. ` +
+            `Provide one via TestOptions.waitForEvent / waitForSignal, or set pauseOnWait.`,
+        );
+      }
+      journal.waitpointsResolved[wp.clientWaitpointId] = resolved;
+      events.push({ type: `waitpoint.resolved:${wp.kind}`, at: resolved.resolvedAt, data: resolved.payload ?? null });
+    }
+    carryover = []; // consumed into stillPending
+
+    if (stillPending.length > 0) {
+      return {
+        status: "waiting",
+        steps: stepsFromJournal(journal),
+        events,
+        metadata,
+        compensations: [],
+        streams,
+        invocations: invocationCount,
+        pause: {
+          journal,
+          pendingWaitpoints: stillPending,
+          startedAt: opts.pause.startedAt,
+          invocationCount,
+          metadataAppliedCount,
+          fixtureCursors: {
+            event: Object.fromEntries(cursors.event.entries()),
+            signal: Object.fromEntries(cursors.signal.entries()),
+          },
+        },
+      };
+    }
+  }
+
+  throw new Error(
+    `resume: exceeded maxInvocations (${maxInvocations}). Last status: ${last?.status ?? "<none>"}.`,
+  );
+}
+
+function matchWaitpoint(
+  pending: readonly WaitpointRegistration[],
+  inj: WaitpointInjection,
+): WaitpointRegistration | undefined {
+  for (const wp of pending) {
+    if (wp.kind !== inj.kind) continue;
+    if (inj.kind === "EVENT" && wp.meta.eventType === inj.eventType) return wp;
+    if (inj.kind === "SIGNAL" && wp.meta.signalName === inj.name) return wp;
+    if (inj.kind === "MANUAL" && wp.meta.tokenId === inj.tokenId) return wp;
+  }
+  return undefined;
+}
+
+function injectionKey(inj: WaitpointInjection): string {
+  if (inj.kind === "EVENT") return inj.eventType;
+  if (inj.kind === "SIGNAL") return inj.name;
+  return inj.tokenId;
+}
+
+function cloneJournal(j: JournalSlice): JournalSlice {
+  return {
+    stepResults: { ...j.stepResults },
+    waitpointsResolved: { ...j.waitpointsResolved },
+    compensationsRun: { ...j.compensationsRun },
+    metadataState: { ...j.metadataState },
+    streamsCompleted: { ...j.streamsCompleted },
+  };
+}
+
+function createStepRunner(
+  opts: TestOptions<unknown>,
+  events: TestResult<unknown>["events"],
+  now: () => number,
+) {
+  return async (args: {
+    stepId: string;
+    attempt: number;
+    input: unknown;
+    fn: (stepCtx: StepContext) => Promise<unknown>;
+    stepCtx: StepContext;
+  }): Promise<StepJournalEntry> => {
+    const startedAt = now();
+    const mock = opts.steps?.[args.stepId];
+    try {
+      const output = mock ? await mock(args.stepCtx) : await args.fn(args.stepCtx);
+      const finishedAt = now();
+      events.push({ type: "step.ok", at: finishedAt, data: { stepId: args.stepId, output } });
+      return {
+        attempt: args.attempt,
+        status: "ok",
+        output,
+        startedAt,
+        finishedAt,
+      };
+    } catch (err) {
+      const finishedAt = now();
+      const e = err as Error;
+      const code = (err as { code?: string }).code ?? "UNKNOWN";
+      events.push({ type: "step.err", at: finishedAt, data: { stepId: args.stepId, message: e.message, code } });
+      const retryAfter = (err as { retryAfter?: unknown }).retryAfter;
+      return {
+        attempt: args.attempt,
+        status: "err",
+        error: {
+          category: "USER_ERROR",
+          code,
+          message: e.message,
+          name: e.name,
+          stack: e.stack,
+          data: retryAfter !== undefined ? { retryAfter } : undefined,
+        },
+        startedAt,
+        finishedAt,
+      };
+    }
+  };
+}
+
+async function resolveWaitpoint(
+  wp: WaitpointRegistration,
+  opts: TestOptions<unknown>,
+  now: () => number,
+  parentEvents: TestResult<unknown>["events"],
+  cursors: FixtureCursors,
+): Promise<WaitpointResolutionEntry | null> {
+  const at = now();
+  if (wp.kind === "DATETIME") {
+    return { kind: "DATETIME", resolvedAt: at, source: "replay" };
+  }
+  if (wp.kind === "EVENT") {
+    const eventType = wp.meta.eventType as string;
+    const isIter = wp.meta.iter === true;
+    const fixture = opts.waitForEvent?.[eventType];
+    if (fixture === undefined) return null;
+    if (isIter) {
+      return resolveIterableFixture(fixture, cursors.event, eventType, at, "EVENT", `evt_test_${eventType}`);
+    }
+    const payload = Array.isArray(fixture) ? fixture[0] : fixture;
+    return { kind: "EVENT", resolvedAt: at, matchedEventId: `evt_test_${eventType}`, payload, source: "live" };
+  }
+  if (wp.kind === "SIGNAL") {
+    const name = wp.meta.signalName as string;
+    const isIter = wp.meta.iter === true;
+    const fixture = opts.waitForSignal?.[name];
+    if (fixture === undefined) return null;
+    if (isIter) {
+      return resolveIterableFixture(fixture, cursors.signal, name, at, "SIGNAL");
+    }
+    return { kind: "SIGNAL", resolvedAt: at, payload: fixture, source: "live" };
+  }
+  if (wp.kind === "MANUAL") {
+    const tokenId = wp.meta.tokenId as string;
+    const fixture = opts.waitForToken?.[tokenId];
+    if (fixture === undefined) return null;
+    return { kind: "MANUAL", resolvedAt: at, payload: fixture, source: "live" };
+  }
+  if (wp.kind === "RUN") {
+    const childWorkflowId = wp.meta.childWorkflowId as string;
+    const childInput = wp.meta.childInput;
+    // Allow test-level override: `invoke: { [childId]: value | (input) => value }`.
+    const override = opts.invoke?.[childWorkflowId];
+    if (override !== undefined) {
+      const payload = typeof override === "function"
+        ? await (override as (input: unknown) => unknown | Promise<unknown>)(childInput)
+        : override;
+      parentEvents.push({
+        type: "child.resolved-from-fixture",
+        at: now(),
+        data: { childWorkflowId, payload },
+      });
+      return { kind: "RUN", resolvedAt: now(), payload, source: "replay" };
+    }
+
+    // Otherwise run the child workflow in-process.
+    const child = getWorkflow(childWorkflowId);
+    if (!child) {
+      throw new Error(
+        `test harness: ctx.invoke target "${childWorkflowId}" is not registered. ` +
+          `Import the child workflow module, or provide a stub via TestOptions.invoke.`,
+      );
+    }
+    parentEvents.push({
+      type: "child.started",
+      at: now(),
+      data: { childWorkflowId, input: childInput },
+    });
+    const childResult = await runWorkflowForTest(
+      child as unknown as WorkflowHandle<unknown, unknown>,
+      childInput,
+      {
+        steps: opts.steps,
+        waitForEvent: opts.waitForEvent,
+        waitForSignal: opts.waitForSignal,
+        waitForToken: opts.waitForToken,
+        invoke: opts.invoke,
+        env: opts.env,
+        environment: opts.environment,
+        now: opts.now,
+        random: opts.random,
+        maxInvocations: opts.maxInvocations,
+      },
+    );
+    parentEvents.push({
+      type: "child.finished",
+      at: now(),
+      data: { childWorkflowId, status: childResult.status, output: childResult.output },
+    });
+    if (childResult.status === "completed") {
+      return { kind: "RUN", resolvedAt: now(), payload: childResult.output, source: "replay" };
+    }
+    // Child failed / cancelled / compensated with error / compensation_failed.
+    const err = childResult.error ?? {
+      category: "USER_ERROR" as const,
+      code: "CHILD_RUN_ENDED",
+      message: `child run ended with status ${childResult.status}`,
+    };
+    return {
+      kind: "RUN",
+      resolvedAt: now(),
+      source: "replay",
+      error: err,
+    };
+  }
+  return null;
+}
+
+export interface FixtureCursors {
+  event: Map<string, number>;
+  signal: Map<string, number>;
+}
+
+const STREAM_END_MARKER = { __voyantStreamEnd: true } as const;
+
+function resolveIterableFixture(
+  fixture: unknown,
+  cursors: Map<string, number>,
+  key: string,
+  at: number,
+  kind: "EVENT" | "SIGNAL",
+  matchedEventId?: string,
+): WaitpointResolutionEntry {
+  const array = Array.isArray(fixture) ? fixture : [fixture];
+  const idx = cursors.get(key) ?? 0;
+  cursors.set(key, idx + 1);
+  if (idx >= array.length) {
+    // Stream is exhausted — signal the tenant-side iterator to terminate.
+    return {
+      kind,
+      resolvedAt: at,
+      payload: STREAM_END_MARKER,
+      source: "replay",
+      matchedEventId,
+    };
+  }
+  return {
+    kind,
+    resolvedAt: at,
+    payload: array[idx],
+    source: "live",
+    matchedEventId,
+  };
+}
+
+function applyMetadata(
+  state: Record<string, MetadataValue>,
+  updates: MetadataMutation[],
+): void {
+  for (const u of updates) {
+    switch (u.op) {
+      case "set":
+        state[u.key] = u.value as MetadataValue;
+        break;
+      case "increment": {
+        const cur = typeof state[u.key] === "number" ? (state[u.key] as number) : 0;
+        state[u.key] = cur + ((u.value as number) ?? 1);
+        break;
+      }
+      case "append": {
+        const cur = Array.isArray(state[u.key]) ? (state[u.key] as MetadataValue[]) : [];
+        state[u.key] = [...cur, u.value as MetadataValue];
+        break;
+      }
+      case "remove":
+        delete state[u.key];
+        break;
+    }
+  }
+}
+
+function stepsFromJournal(j: JournalSlice): TestResult<unknown>["steps"] {
+  return Object.entries(j.stepResults).map(([id, entry]) => ({
+    id,
+    status: entry.status,
+    duration: entry.finishedAt - entry.startedAt,
+    output: entry.output,
+  }));
+}