@voyantjs/workflows 0.6.7 → 0.6.9

package/src/testing/index.ts

@@ -6,37 +6,53 @@
 // 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";
+import type { SerializedError } from "../protocol/index.js"
+import {
+  type CompensationReport,
+  type ExecuteWorkflowStepResponse,
+  executeWorkflowStep,
+  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"
+import type { RunStatus } from "../types.js"
+import type {
+  EnvironmentContext,
+  MetadataValue,
+  StepContext,
+  WorkflowDefinition,
+  WorkflowHandle,
+} from "../workflow.js"
+import { getWorkflow } from "../workflow.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>>;
+  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[]>;
+  waitForEvent?: Record<string, unknown | unknown[]>
   /** Map of signalName → payload. */
-  waitForSignal?: Record<string, unknown>;
+  waitForSignal?: Record<string, unknown>
   /** Map of tokenId → payload. */
-  waitForToken?: Record<string, unknown>;
+  waitForToken?: Record<string, unknown>
   /** Workflow invoke stubs keyed by child workflow id. */
-  invoke?: Record<string, unknown>;
+  invoke?: Record<string, unknown>
   /** Fake env bindings, passed through to `ctx.environment` for tests. */
-  env?: Record<string, unknown>;
-  environment?: Partial<EnvironmentContext>;
+  env?: Record<string, unknown>
+  environment?: Partial<EnvironmentContext>
   /** Fixed wall-clock basis for the run. Defaults to Date.now(). */
-  now?: () => number;
-  random?: () => number;
+  now?: () => number
+  random?: () => number
   /** Max resumption cycles. Defaults to 16 — guards runaway loops. */
-  maxInvocations?: number;
+  maxInvocations?: number
   /**
    * When true, the harness stops and returns a "waiting" TestResult as
    * soon as any registered waitpoint has no fixture resolution (instead
@@ -48,35 +64,35 @@ export interface TestOptions<_TIn> {
    * this flag, since a local dev loop is not the right place to
    * synthesize wall-clock delays.
    */
-  pauseOnWait?: boolean;
+  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[];
+  >
+  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;
+  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> };
-  };
+    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>(
@@ -84,33 +100,33 @@ export async function runWorkflowForTest<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 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;
+  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;
+  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() };
+  const cursors: FixtureCursors = { event: new Map(), signal: new Map() }
 
   while (invocationCount < maxInvocations) {
-    invocationCount += 1;
+    invocationCount += 1
 
     const response = await executeWorkflowStep(def as unknown as WorkflowDefinition, {
       runId: `run_test_${def.id}`,
@@ -137,17 +153,18 @@ export async function runWorkflowForTest<TIn, TOut>(
       runStartedAt: startedAt,
       tags: [],
       stepRunner: createStepRunner(opts, events, now),
-    });
+    })
 
-    last = response;
+    last = response
 
-    const newMutations = response.metadataUpdates.slice(metadataAppliedCount);
-    applyMetadata(metadata, newMutations);
-    metadataAppliedCount = response.metadataUpdates.length;
+    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);
+      const bucket = streams[chunk.streamId] ?? []
+      streams[chunk.streamId] = bucket
+      bucket.push(chunk)
     }
 
     if (response.status === "completed") {
@@ -160,20 +177,24 @@ export async function runWorkflowForTest<TIn, TOut>(
         compensations: [],
         streams,
         invocations: invocationCount,
-      };
+      }
     }
 
     if (response.status === "failed") {
       return {
         status: "failed",
-        error: { category: response.error.category, code: response.error.code, message: response.error.message },
+        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") {
@@ -185,7 +206,7 @@ export async function runWorkflowForTest<TIn, TOut>(
         compensations: response.compensations,
         streams,
         invocations: invocationCount,
-      };
+      }
     }
 
     if (response.status === "compensated" || response.status === "compensation_failed") {
@@ -204,28 +225,32 @@ export async function runWorkflowForTest<TIn, TOut>(
         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[] = [];
+    const stillPending: WaitpointRegistration[] = []
     for (const wp of response.waitpoints) {
-      const resolved = await resolveWaitpoint(wp, opts, now, events, cursors);
+      const resolved = await resolveWaitpoint(wp, opts, now, events, cursors)
       if (!resolved) {
         if (opts.pauseOnWait) {
-          stillPending.push(wp);
-          continue;
+          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 });
+      journal.waitpointsResolved[wp.clientWaitpointId] = resolved
+      events.push({
+        type: `waitpoint.resolved:${wp.kind}`,
+        at: resolved.resolvedAt,
+        data: resolved.payload ?? null,
+      })
     }
     if (stillPending.length > 0) {
       return {
@@ -247,14 +272,14 @@ export async function runWorkflowForTest<TIn, TOut>(
             signal: Object.fromEntries(cursors.signal.entries()),
           },
         },
-      };
+      }
     }
   }
 
   throw new Error(
     `test harness exceeded maxInvocations (${maxInvocations}). ` +
       `Last status: ${last?.status ?? "<none>"}. Possible infinite waitpoint loop.`,
-  );
+  )
 }
 
 /**
@@ -266,13 +291,13 @@ export async function runWorkflowForTest<TIn, TOut>(
 export type WaitpointInjection =
   | { kind: "EVENT"; eventType: string; payload?: unknown }
   | { kind: "SIGNAL"; name: string; payload?: unknown }
-  | { kind: "MANUAL"; tokenId: 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"]>;
+  pause: NonNullable<TestResult<unknown>["pause"]>
   /** The single waitpoint resolution to inject on resume. */
-  injection: WaitpointInjection;
+  injection: WaitpointInjection
 }
 
 /**
@@ -285,26 +310,27 @@ export async function resumeWorkflowForTest<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 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);
+  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);
+  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,
-  };
+    matchedEventId:
+      opts.injection.kind === "EVENT" ? `evt_live_${opts.injection.eventType}` : undefined,
+  }
 
   const events: TestResult<TOut>["events"] = [
     {
@@ -312,28 +338,30 @@ export async function resumeWorkflowForTest<TIn, TOut>(
       at: now(),
       data: opts.injection.payload ?? null,
     },
-  ];
-  const metadata: Record<string, MetadataValue> = {};
-  const streams: Record<string, StreamChunk[]> = {};
+  ]
+  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;
+  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);
+  let carryover = opts.pause.pendingWaitpoints.filter(
+    (w) => w.clientWaitpointId !== matched.clientWaitpointId,
+  )
 
   while (invocationCount < maxInvocations) {
-    invocationCount += 1;
+    invocationCount += 1
 
     const response = await executeWorkflowStep(def as unknown as WorkflowDefinition, {
       runId: `run_test_${def.id}`,
@@ -360,17 +388,18 @@ export async function resumeWorkflowForTest<TIn, TOut>(
       runStartedAt: opts.pause.startedAt,
       tags: [],
       stepRunner: createStepRunner(opts, events, now),
-    });
+    })
 
-    last = response;
+    last = response
 
-    const newMutations = response.metadataUpdates.slice(metadataAppliedCount);
-    applyMetadata(metadata, newMutations);
-    metadataAppliedCount = response.metadataUpdates.length;
+    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);
+      const bucket = streams[chunk.streamId] ?? []
+      streams[chunk.streamId] = bucket
+      bucket.push(chunk)
     }
 
     if (response.status === "completed") {
@@ -383,19 +412,23 @@ export async function resumeWorkflowForTest<TIn, TOut>(
         compensations: [],
         streams,
         invocations: invocationCount,
-      };
+      }
     }
     if (response.status === "failed") {
       return {
         status: "failed",
-        error: { category: response.error.category, code: response.error.code, message: response.error.message },
+        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 {
@@ -406,13 +439,17 @@ export async function resumeWorkflowForTest<TIn, TOut>(
         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 }
+          ? {
+              category: response.error.category,
+              code: response.error.code,
+              message: response.error.message,
+            }
           : undefined,
         steps: stepsFromJournal(journal),
         events,
@@ -420,26 +457,30 @@ export async function resumeWorkflowForTest<TIn, TOut>(
         compensations: response.compensations,
         streams,
         invocations: invocationCount,
-      };
+      }
     }
 
-    const stillPending: WaitpointRegistration[] = [...carryover];
+    const stillPending: WaitpointRegistration[] = [...carryover]
     for (const wp of response.waitpoints) {
-      const resolved = await resolveWaitpoint(wp, opts, now, events, cursors);
+      const resolved = await resolveWaitpoint(wp, opts, now, events, cursors)
       if (!resolved) {
         if (opts.pauseOnWait) {
-          stillPending.push(wp);
-          continue;
+          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 });
+      journal.waitpointsResolved[wp.clientWaitpointId] = resolved
+      events.push({
+        type: `waitpoint.resolved:${wp.kind}`,
+        at: resolved.resolvedAt,
+        data: resolved.payload ?? null,
+      })
     }
-    carryover = []; // consumed into stillPending
+    carryover = [] // consumed into stillPending
 
     if (stillPending.length > 0) {
       return {
@@ -461,13 +502,13 @@ export async function resumeWorkflowForTest<TIn, TOut>(
             signal: Object.fromEntries(cursors.signal.entries()),
           },
         },
-      };
+      }
     }
   }
 
   throw new Error(
     `resume: exceeded maxInvocations (${maxInvocations}). Last status: ${last?.status ?? "<none>"}.`,
-  );
+  )
 }
 
 function matchWaitpoint(
@@ -475,18 +516,18 @@ function matchWaitpoint(
   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;
+    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;
+  return undefined
 }
 
 function injectionKey(inj: WaitpointInjection): string {
-  if (inj.kind === "EVENT") return inj.eventType;
-  if (inj.kind === "SIGNAL") return inj.name;
-  return inj.tokenId;
+  if (inj.kind === "EVENT") return inj.eventType
+  if (inj.kind === "SIGNAL") return inj.name
+  return inj.tokenId
 }
 
 function cloneJournal(j: JournalSlice): JournalSlice {
@@ -496,7 +537,7 @@ function cloneJournal(j: JournalSlice): JournalSlice {
     compensationsRun: { ...j.compensationsRun },
     metadataState: { ...j.metadataState },
     streamsCompleted: { ...j.streamsCompleted },
-  };
+  }
 }
 
 function createStepRunner(
@@ -505,31 +546,35 @@ function createStepRunner(
   now: () => number,
 ) {
   return async (args: {
-    stepId: string;
-    attempt: number;
-    input: unknown;
-    fn: (stepCtx: StepContext) => Promise<unknown>;
-    stepCtx: StepContext;
+    stepId: string
+    attempt: number
+    input: unknown
+    fn: (stepCtx: StepContext) => Promise<unknown>
+    stepCtx: StepContext
   }): Promise<StepJournalEntry> => {
-    const startedAt = now();
-    const mock = opts.steps?.[args.stepId];
+    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 } });
+      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;
+      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",
@@ -543,9 +588,9 @@ function createStepRunner(
         },
         startedAt,
         finishedAt,
-      };
+      }
     }
-  };
+  }
 }
 
 async function resolveWaitpoint(
@@ -555,67 +600,87 @@ async function resolveWaitpoint(
   parentEvents: TestResult<unknown>["events"],
   cursors: FixtureCursors,
 ): Promise<WaitpointResolutionEntry | null> {
-  const at = now();
+  const at = now()
   if (wp.kind === "DATETIME") {
-    return { kind: "DATETIME", resolvedAt: at, source: "replay" };
+    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;
+    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}`);
+      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",
     }
-    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;
+    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 resolveIterableFixture(fixture, cursors.signal, name, at, "SIGNAL")
     }
-    return { kind: "SIGNAL", resolvedAt: at, payload: fixture, source: "live" };
+    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" };
+    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;
+    const childWorkflowId = wp.meta.childWorkflowId as string
+    const childInput = wp.meta.childInput
+    const detach = wp.meta.detach === true
     // Allow test-level override: `invoke: { [childId]: value | (input) => value }`.
-    const override = opts.invoke?.[childWorkflowId];
+    const override = opts.invoke?.[childWorkflowId]
     if (override !== undefined) {
-      const payload = typeof override === "function"
-        ? await (override as (input: unknown) => unknown | Promise<unknown>)(childInput)
-        : override;
+      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" };
+        data: { childWorkflowId, payload, detach },
+      })
+      return {
+        kind: "RUN",
+        resolvedAt: now(),
+        payload: detach ? undefined : payload,
+        source: "replay",
+      }
     }
 
     // Otherwise run the child workflow in-process.
-    const child = getWorkflow(childWorkflowId);
+    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,
@@ -630,38 +695,42 @@ async function resolveWaitpoint(
         now: opts.now,
         random: opts.random,
         maxInvocations: opts.maxInvocations,
+        pauseOnWait: detach || opts.pauseOnWait,
       },
-    );
+    )
     parentEvents.push({
       type: "child.finished",
       at: now(),
-      data: { childWorkflowId, status: childResult.status, output: childResult.output },
-    });
+      data: { childWorkflowId, status: childResult.status, output: childResult.output, detach },
+    })
+    if (detach) {
+      return { kind: "RUN", resolvedAt: now(), payload: undefined, source: "replay" }
+    }
     if (childResult.status === "completed") {
-      return { kind: "RUN", resolvedAt: now(), payload: childResult.output, source: "replay" };
+      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;
+  return null
 }
 
 export interface FixtureCursors {
-  event: Map<string, number>;
-  signal: Map<string, number>;
+  event: Map<string, number>
+  signal: Map<string, number>
 }
 
-const STREAM_END_MARKER = { __voyantStreamEnd: true } as const;
+const STREAM_END_MARKER = { __voyantStreamEnd: true } as const
 
 function resolveIterableFixture(
   fixture: unknown,
@@ -671,9 +740,9 @@ function resolveIterableFixture(
   kind: "EVENT" | "SIGNAL",
   matchedEventId?: string,
 ): WaitpointResolutionEntry {
-  const array = Array.isArray(fixture) ? fixture : [fixture];
-  const idx = cursors.get(key) ?? 0;
-  cursors.set(key, idx + 1);
+  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 {
@@ -682,7 +751,7 @@ function resolveIterableFixture(
       payload: STREAM_END_MARKER,
       source: "replay",
       matchedEventId,
-    };
+    }
   }
   return {
     kind,
@@ -690,31 +759,28 @@ function resolveIterableFixture(
     payload: array[idx],
     source: "live",
     matchedEventId,
-  };
+  }
 }
 
-function applyMetadata(
-  state: Record<string, MetadataValue>,
-  updates: MetadataMutation[],
-): void {
+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;
+        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;
+        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;
+        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;
+        delete state[u.key]
+        break
     }
   }
 }
@@ -725,5 +791,5 @@ function stepsFromJournal(j: JournalSlice): TestResult<unknown>["steps"] {
     status: entry.status,
     duration: entry.finishedAt - entry.startedAt,
     output: entry.output,
-  }));
+  }))
 }