@fluidgrids/workflows 2026.1028.2 → 2026.1029.1

package/dist/testing/index.js

@@ -1,20 +1,21 @@
-import { failedTaskResult } from '../chunk-IISBRUWJ.js';
-import { isTier1Workflow, toIR } from '../chunk-HWJZVOG7.js';
+import { failedTaskResult } from '../chunk-WXXNCHUY.js';
+import { isTier1Workflow, toIR } from '../chunk-FQSJI5NV.js';
 import { irHash, CODE_WORKFLOW_NODE_TYPE, normalizeDefinition } from '../chunk-BD7ZPG53.js';
 import '../chunk-5LUIDMF4.js';
 import '../chunk-JZ4TOOLN.js';
 import '../chunk-E2VK7J2C.js';
 import '../chunk-7AAZGVKD.js';
-import { createHistoryFile, validateCommands, parseHistoryFile } from '../chunk-VOKMAAJP.js';
+import { createHistoryFile, validateCommands, parseHistoryFile } from '../chunk-A36CCOWS.js';
 import { isRecord } from '../chunk-PMCM2OH4.js';
-import { buildWorkflowRegistry, createWorkflowRuntime } from '../chunk-VRHHBPT6.js';
-import { failureToError, signalName, toMs, errorToFailure, ApplicationError, CancelledFailure, DeterminismViolation } from '../chunk-C5OLWZ42.js';
-import '../chunk-LNUQE6D6.js';
+import { buildWorkflowRegistry, createWorkflowRuntime } from '../chunk-MJ5TGYVG.js';
+import { failureToError, signalName, ApplicationError, errorToFailure, CancelledFailure, DeterminismViolation } from '../chunk-KXJDRQ6G.js';
+import '../chunk-M272AHEX.js';
 import { TASK_PRELUDE } from '../chunk-4LYSEANA.js';
-import { isDurableWorkflow } from '../chunk-N23SKIG4.js';
-import { initialRunState, applyEvent, eventsForCommands, isActivityOpen, computeRetryDelay, isChildOpen } from '../chunk-ABFZWYHT.js';
-import { isInputEvent, HISTORY_PROTOCOL, TERMINAL_COMMANDS } from '../chunk-DJYMDLV5.js';
-import '../chunk-BO6OVILK.js';
+import { runRetryPolicyOf, toMs, isDurableWorkflow } from '../chunk-7ILGCUI6.js';
+import '../chunk-LNUQE6D6.js';
+import { initialRunState, applyEvent, isActivityOpen, eventsForCommands, continueAsNewRetryShape, isChildOpen } from '../chunk-FWBRQWRX.js';
+import { RUNTIME_RELEASE, isInputEvent, HISTORY_PROTOCOL, TERMINAL_COMMANDS } from '../chunk-2DDULZFM.js';
+import { computeRetryDelay, computeRunRetryDelay } from '../chunk-PWIUEWC3.js';
 import { createContext, Script } from 'vm';
 
 // src/testing/host.ts
@@ -38,6 +39,32 @@ async function runWorkflowTaskInProcess(registry, request) {
 }
 
 // src/testing/environment.ts
+var WorkflowAlreadyStartedError = class extends Error {
+  constructor(workflowKey, workflowId, existingRunId) {
+    super(
+      `Workflow ${workflowKey} already has a run with workflow id "${workflowId}" (${existingRunId})`
+    );
+    this.workflowKey = workflowKey;
+    this.workflowId = workflowId;
+    this.existingRunId = existingRunId;
+    this.name = "WorkflowAlreadyStartedError";
+  }
+  workflowKey;
+  workflowId;
+  existingRunId;
+};
+var UnfinishedHandlersError = class extends Error {
+  constructor(runId, handlers) {
+    super(
+      `Run ${runId} finished while handlers were still running: ${handlers.map((handler) => `${handler.kind} ${handler.name} x${handler.count}`).join(", ")} (await ctx.allHandlersFinished(), or set unfinishedPolicy: 'ABANDON')`
+    );
+    this.runId = runId;
+    this.handlers = handlers;
+    this.name = "UnfinishedHandlersError";
+  }
+  runId;
+  handlers;
+};
 var WorkflowFailedError = class extends Error {
   constructor(runId, failure) {
     super(`Run ${runId} failed: ${failure.message}`);
@@ -113,6 +140,15 @@ function toDate(value) {
   if (value instanceof Date) return value.getTime();
   return typeof value === "number" ? value : Date.parse(value);
 }
+function optionalDuration(value, what) {
+  return value === void 0 ? void 0 : toMs(value, what);
+}
+var FAILED_STATUSES = /* @__PURE__ */ new Set([
+  "FAILED",
+  "CANCELLED",
+  "TERMINATED",
+  "TIMED_OUT"
+]);
 function toJsonValue(value) {
   if (value === void 0) return null;
   const text = JSON.stringify(value);
@@ -122,6 +158,10 @@ var TestWorkflowEnvironment = class _TestWorkflowEnvironment {
   clock;
   timeSkipping;
   enabled;
+  failOnUnfinishedHandlers;
+  historyRelease;
+  dues = [];
+  held = /* @__PURE__ */ new Set();
   workspaceId;
   runs = /* @__PURE__ */ new Map();
   runOrder = [];
@@ -139,6 +179,8 @@ var TestWorkflowEnvironment = class _TestWorkflowEnvironment {
     this.clock = toDate(options.startTime);
     this.timeSkipping = options.timeSkipping !== false;
     this.enabled = options.enabled ?? "parity";
+    this.failOnUnfinishedHandlers = options.failOnUnfinishedHandlers !== false;
+    this.historyRelease = options.historyRelease ?? RUNTIME_RELEASE;
     this.workspaceId = options.workspaceId ?? "test-workspace";
     this.workflows = { ...options.workflows ?? {} };
     this.registry = registryOf(this.workflows);
@@ -162,6 +204,22 @@ var TestWorkflowEnvironment = class _TestWorkflowEnvironment {
       impl
     );
   }
+  /**
+   * Hold the activity queue of a node type (every node type when omitted):
+   * attempts wait instead of starting, and a `scheduleToStartTimeout` expires
+   * (`ACTIVITY_TIMED_OUT { timeoutType: SCHEDULE_TO_START }`, not retried).
+   */
+  holdActivities(nodeType = "*") {
+    this.held.add(nodeType);
+  }
+  /** Release held activity queues (all when no node type is given). */
+  releaseActivities(nodeType) {
+    if (nodeType === void 0) this.held.clear();
+    else this.held.delete(nodeType);
+  }
+  isHeld(nodeType) {
+    return this.held.has("*") || this.held.has(nodeType);
+  }
   /** Mock a child workflow started by key (graph or durable). */
   mockChild(workflowKey, impl) {
     this.childMocks.set(workflowKey, impl);
@@ -172,17 +230,85 @@ var TestWorkflowEnvironment = class _TestWorkflowEnvironment {
       // A declared workflow is stored by its declaration; its input type is the caller's.
       this.ensureRegistered(definition)
     );
+    const declared = this.workflows[workflowFn]?.options ?? {};
+    const workflowKey = options.workflowKey ?? (typeof definition === "string" ? this.workflows[workflowFn]?.name ?? workflowFn : definition.name);
+    if (options.workflowId !== void 0) {
+      const existing = this.useExisting(workflowKey, options);
+      if (existing !== void 0) {
+        for (const signal of options.signals ?? [])
+          this.deliverSignal(existing, signal.name, signal.payload);
+        await this.runUntilIdle(false);
+        return new TestRunHandle(this, existing);
+      }
+    }
+    const executionTimeoutMs = optionalDuration(
+      options.executionTimeout ?? declared.executionTimeout,
+      "executionTimeout"
+    );
+    const retry = options.retry ?? declared.retry;
+    const config = {
+      workflowKey,
+      runAttempt: 1,
+      ...options.workflowId !== void 0 ? { businessId: options.workflowId } : {},
+      ...executionTimeoutMs !== void 0 ? { executionTimeoutMs, executionDeadline: this.clock + executionTimeoutMs } : {},
+      ...this.durationConfig(options.runTimeout ?? declared.runTimeout, "runTimeoutMs"),
+      ...this.durationConfig(
+        options.workflowTaskTimeout ?? declared.workflowTaskTimeout,
+        "workflowTaskTimeoutMs"
+      ),
+      ...this.durationConfig(options.startDelay, "startDelayMs"),
+      ...retry !== void 0 ? { retry: runRetryPolicyOf(retry) } : {},
+      ...options.summary !== void 0 ? { summary: options.summary } : {},
+      ...options.details !== void 0 ? { details: options.details } : {},
+      ...options.memo !== void 0 ? { memo: toJsonValue(options.memo) } : {},
+      ...(options.versioningBehavior ?? declared.versioningBehavior) !== void 0 ? { versioningBehavior: options.versioningBehavior ?? declared.versioningBehavior } : {}
+    };
     const runId = this.createRun(
       workflowFn,
       toJsonValue(options.input),
       { ...options.info, ...options.runId !== void 0 ? { runId: options.runId } : {} },
-      void 0
+      void 0,
+      {},
+      config
     );
     for (const signal of options.signals ?? [])
       this.deliverSignal(runId, signal.name, signal.payload);
     await this.runUntilIdle(false);
     return new TestRunHandle(this, runId);
   }
+  durationConfig(value, key) {
+    const ms = optionalDuration(value, key);
+    if (ms === void 0) return {};
+    const out = {};
+    out[key] = ms;
+    return out;
+  }
+  /**
+   * The workflow-id policies of a start (11 §2.1): the open run to use, or
+   * undefined to start a new run (after terminating the open one for
+   * `TERMINATE_EXISTING`). Throws {@link WorkflowAlreadyStartedError}.
+   */
+  useExisting(workflowKey, options) {
+    const workflowId = options.workflowId ?? "";
+    const runs = this.runOrder.map((id) => this.run(id)).filter(
+      (run) => run.config.workflowKey === workflowKey && run.config.businessId === workflowId
+    );
+    const open = runs.find((run) => run.state.status === "RUNNING");
+    if (open) {
+      const conflict = options.idConflictPolicy ?? "FAIL";
+      if (conflict === "USE_EXISTING") return open.runId;
+      if (conflict === "FAIL")
+        throw new WorkflowAlreadyStartedError(workflowKey, workflowId, open.runId);
+      this.terminate(open.runId, "ID_CONFLICT");
+      return void 0;
+    }
+    const last = runs[runs.length - 1];
+    if (!last) return void 0;
+    const reuse = options.idReusePolicy ?? "ALLOW_DUPLICATE";
+    if (reuse === "REJECT_DUPLICATE" || reuse === "ALLOW_DUPLICATE_FAILED_ONLY" && !FAILED_STATUSES.has(last.state.status))
+      throw new WorkflowAlreadyStartedError(workflowKey, workflowId, last.runId);
+    return void 0;
+  }
   /** Advance the clock by `duration`, firing timers and running work as it comes due. */
   async sleep(duration) {
     const until = this.clock + toMs(duration, "sleep duration");
@@ -233,7 +359,7 @@ var TestWorkflowEnvironment = class _TestWorkflowEnvironment {
     if (!run) throw new Error(`Unknown run ${runId}`);
     return run;
   }
-  createRun(workflowFn, input, info, parent, extraStarted = {}) {
+  createRun(workflowFn, input, info, parent, extraStarted = {}, config = { workflowKey: workflowFn, runAttempt: 1 }) {
     this.runCounter += 1;
     const runId = info.runId ?? `run-${this.runCounter}`;
     const snapshot = {
@@ -254,18 +380,62 @@ var TestWorkflowEnvironment = class _TestWorkflowEnvironment {
       taskCounter: 0,
       info: snapshot,
       children: /* @__PURE__ */ new Map(),
+      config,
       ...parent ? { parent } : {}
     };
+    const firstTaskDelay = config.startDelayMs ?? config.firstTaskDelayMs;
+    if (firstTaskDelay !== void 0 && firstTaskDelay > 0) {
+      run.delayedUntil = this.clock + firstTaskDelay;
+      this.dues.push({ runId, kind: "start", at: run.delayedUntil });
+    }
+    if (config.runTimeoutMs !== void 0)
+      this.dues.push({ runId, kind: "runTimeout", at: this.clock + config.runTimeoutMs });
+    if (config.executionDeadline !== void 0)
+      this.dues.push({ runId, kind: "executionTimeout", at: config.executionDeadline });
     this.runs.set(runId, run);
     this.runOrder.push(runId);
     this.append(run, {
       type: "WORKFLOW_STARTED",
       // The service writes the seed of ctx.random()/ctx.uuid() into the start
       // event so the history replays on its own; it uses the run id.
-      payload: { workflowFn, input, taskQueue: "managed", randomnessSeed: runId, ...extraStarted }
+      payload: {
+        workflowFn,
+        input,
+        taskQueue: config.taskQueue ?? "managed",
+        randomnessSeed: runId,
+        ...extraStarted,
+        ...this.startedFields(config)
+      }
     });
     return runId;
   }
+  /** The R2 fields of `WORKFLOW_STARTED`, each written only when it is set. */
+  startedFields(config) {
+    const out = {};
+    if (config.businessId !== void 0) {
+      out["businessId"] = config.businessId;
+      out["workflowId"] = config.businessId;
+    }
+    if (config.startDelayMs !== void 0) out["startDelayMs"] = config.startDelayMs;
+    if (config.retry !== void 0 || config.runAttempt > 1) out["runAttempt"] = config.runAttempt;
+    if (config.summary !== void 0) out["summary"] = config.summary;
+    if (config.details !== void 0) out["details"] = config.details;
+    if (config.memo !== void 0) out["context"] = config.memo;
+    const timeouts = {};
+    if (config.executionTimeoutMs !== void 0)
+      timeouts["executionTimeout"] = config.executionTimeoutMs;
+    if (config.runTimeoutMs !== void 0) timeouts["runTimeout"] = config.runTimeoutMs;
+    if (config.workflowTaskTimeoutMs !== void 0)
+      timeouts["workflowTaskTimeout"] = config.workflowTaskTimeoutMs;
+    if (Object.keys(timeouts).length > 0) out["timeouts"] = timeouts;
+    if (config.retry !== void 0) out["retry"] = toJsonValue(config.retry);
+    if (config.versioningBehavior !== void 0)
+      out["versioningBehavior"] = config.versioningBehavior;
+    if (config.lastCompletionResult !== void 0 && this.historyRelease >= 2)
+      out["lastCompletionResult"] = config.lastCompletionResult;
+    if (config.lastFailure !== void 0) out["lastFailure"] = toJsonValue(config.lastFailure);
+    return out;
+  }
   append(run, draft) {
     const event = {
       seq: run.history.length + 1,
@@ -276,7 +446,8 @@ var TestWorkflowEnvironment = class _TestWorkflowEnvironment {
     };
     applyEvent(run.state, event);
     run.history.push(event);
-    if (isInputEvent(event) && run.state.status === "RUNNING" && run.state.task.state === "NONE") {
+    if (run.delayedUntil !== void 0 && event.type === "SIGNAL_RECEIVED") this.endDelay(run);
+    if (run.delayedUntil === void 0 && isInputEvent(event) && run.state.status === "RUNNING" && run.state.task.state === "NONE") {
       run.taskCounter += 1;
       const taskId = `${run.runId}-task-${run.taskCounter}`;
       const scheduled = {
@@ -290,6 +461,22 @@ var TestWorkflowEnvironment = class _TestWorkflowEnvironment {
     }
     return event;
   }
+  /** End a start delay: the first workflow task is scheduled now. */
+  endDelay(run) {
+    run.delayedUntil = void 0;
+    this.dues = this.dues.filter((due) => !(due.runId === run.runId && due.kind === "start"));
+    if (run.state.status !== "RUNNING" || run.state.task.state !== "NONE") return;
+    run.taskCounter += 1;
+    const taskId = `${run.runId}-task-${run.taskCounter}`;
+    const scheduled = {
+      seq: run.history.length + 1,
+      type: "WORKFLOW_TASK_SCHEDULED",
+      payload: { taskId },
+      createdAt: new Date(this.clock).toISOString()
+    };
+    applyEvent(run.state, scheduled);
+    run.history.push(scheduled);
+  }
   deliverSignal(runId, name, payload) {
     const run = this.runs.get(runId);
     if (!run || run.state.status !== "RUNNING") return false;
@@ -311,6 +498,11 @@ var TestWorkflowEnvironment = class _TestWorkflowEnvironment {
       type: "WORKFLOW_CANCEL_REQUESTED",
       payload: reason !== void 0 ? { reason } : {}
     });
+    if (run.delayedUntil !== void 0) {
+      run.delayedUntil = void 0;
+      this.append(run, { type: "WORKFLOW_CANCELLED", payload: {} });
+      this.onClosed(run);
+    }
     return true;
   }
   terminate(runId, reason) {
@@ -330,7 +522,9 @@ var TestWorkflowEnvironment = class _TestWorkflowEnvironment {
         await this.runTask(task);
         continue;
       }
-      const attempt = this.attempts.find((entry) => entry.dueAt <= this.clock);
+      const attempt = this.attempts.find(
+        (entry) => entry.dueAt <= this.clock && !this.isHeld(entry.nodeType)
+      );
       if (attempt) {
         this.attempts = this.attempts.filter((entry) => entry !== attempt);
         await this.runAttempt(attempt);
@@ -349,16 +543,78 @@ var TestWorkflowEnvironment = class _TestWorkflowEnvironment {
     }
     throw new Error("The test environment did not settle after 100000 steps");
   }
+  /** When a held attempt's schedule-to-start timeout expires, if it has one. */
+  heldDeadline(entry) {
+    return this.isHeld(entry.nodeType) && entry.scheduleToStart !== void 0 ? entry.dueAt + entry.scheduleToStart : void 0;
+  }
   nextDue() {
-    const due = [
-      ...this.timers.map((timer) => timer.fireAt),
-      ...this.attempts.map((entry) => entry.dueAt)
-    ];
+    const due = [...this.timers.map((timer) => timer.fireAt)];
+    for (const entry of this.attempts) {
+      if (!this.isHeld(entry.nodeType)) due.push(entry.dueAt);
+      const deadline = this.heldDeadline(entry);
+      if (deadline !== void 0) due.push(deadline);
+    }
+    for (const entry of this.dues) due.push(entry.at);
     return due.length === 0 ? void 0 : Math.min(...due);
   }
+  /** Expire held attempts whose schedule-to-start timeout passed (not retried, 11 §2.3). */
+  expireHeld() {
+    const expired = this.attempts.filter((entry) => {
+      const deadline = this.heldDeadline(entry);
+      return deadline !== void 0 && deadline <= this.clock;
+    });
+    if (expired.length === 0) return false;
+    this.attempts = this.attempts.filter((entry) => !expired.includes(entry));
+    for (const entry of expired) {
+      const run = this.runs.get(entry.runId);
+      const activity = run?.state.activities[entry.activityId];
+      if (!run || run.state.status !== "RUNNING" || !activity || !isActivityOpen(activity))
+        continue;
+      this.append(run, {
+        type: "ACTIVITY_TIMED_OUT",
+        payload: {
+          activityId: entry.activityId,
+          attempt: entry.attempt,
+          timeoutType: "SCHEDULE_TO_START"
+        }
+      });
+    }
+    return true;
+  }
+  /** Fire run-level deadlines: the end of a start delay, run and execution timeouts. */
+  fireRunDues() {
+    const due = this.dues.filter((entry) => entry.at <= this.clock).sort((a, b) => a.at - b.at);
+    if (due.length === 0) return false;
+    this.dues = this.dues.filter((entry) => !due.includes(entry));
+    for (const entry of due) {
+      const run = this.runs.get(entry.runId);
+      if (!run || run.state.status !== "RUNNING") continue;
+      if (entry.kind === "start") {
+        if (run.delayedUntil !== void 0) this.endDelay(run);
+        continue;
+      }
+      const timeoutType = entry.kind === "runTimeout" ? "WORKFLOW_RUN" : "WORKFLOW_EXECUTION";
+      const failure = {
+        errorType: "TIMEOUT",
+        message: timeoutType === "WORKFLOW_RUN" ? "The run timeout expired" : "The execution timeout of the chain expired",
+        type: "TimeoutFailure",
+        timeoutType,
+        source: "engine"
+      };
+      run.delayedUntil = void 0;
+      this.append(run, {
+        type: "WORKFLOW_TIMED_OUT",
+        payload: { timeoutType, failure: toJsonValue(failure) }
+      });
+      this.onClosed(run);
+    }
+    return true;
+  }
   fireDue() {
+    const expired = this.expireHeld();
+    const fired = this.fireRunDues();
     const due = this.timers.filter((timer) => timer.fireAt <= this.clock).sort((a, b) => a.fireAt - b.fireAt);
-    if (due.length === 0) return false;
+    if (due.length === 0) return expired || fired;
     this.timers = this.timers.filter((timer) => !due.includes(timer));
     for (const timer of due) {
       const run = this.runs.get(timer.runId);
@@ -379,7 +635,7 @@ var TestWorkflowEnvironment = class _TestWorkflowEnvironment {
       history: run.history,
       nowMs: this.clock
     };
-    const result = this.executor ? await this.executor(request) : await runWorkflowTaskInProcess(this.registry, request);
+    const result = await this.executeWithLocalActivities(run, request);
     const fail = (cause, message) => {
       this.append(run, {
         type: "WORKFLOW_TASK_FAILED",
@@ -406,12 +662,69 @@ var TestWorkflowEnvironment = class _TestWorkflowEnvironment {
       fail(drafts.cause, drafts.issues.map((issue) => issue.message).join("; "));
       return;
     }
+    if (result.unfinishedHandlers !== void 0 && result.unfinishedHandlers.length > 0)
+      run.unfinishedHandlers = result.unfinishedHandlers;
     this.append(run, { type: "WORKFLOW_TASK_COMPLETED", taskId, payload: { taskId } });
     for (const draft of drafts.events) this.append(run, draft);
     for (const command of checked.commands)
       if (run.state.status === "RUNNING" || TERMINAL_COMMANDS.has(command.type))
         this.afterCommand(run, command);
   }
+  execute(request) {
+    return this.executor ? this.executor(request) : runWorkflowTaskInProcess(this.registry, request);
+  }
+  /**
+   * Run a workflow task as the worker does (11 §2.12): while it asks for
+   * local activities, run each through its mock and run the same task again
+   * with the outcomes, up to 1,000 rounds.
+   */
+  async executeWithLocalActivities(run, request) {
+    const outcomes = /* @__PURE__ */ new Map();
+    let result = await this.execute(request);
+    for (let round = 0; result.outcome === "localActivityRequested"; round++) {
+      if (round >= 1e3)
+        return {
+          ...result,
+          outcome: "failed",
+          commands: [],
+          failure: { cause: "INTERNAL", message: "The task asked for local activities 1000 times" }
+        };
+      for (const wanted of result.localActivityRequests ?? [])
+        outcomes.set(wanted.localActivityId, await this.runLocalActivity(run, wanted));
+      result = await this.execute({ ...request, localActivityResults: [...outcomes.values()] });
+    }
+    return result;
+  }
+  async runLocalActivity(run, wanted) {
+    const mock = this.mocks.get(`${wanted.nodeType}#${wanted.operation}`) ?? this.mocks.get(wanted.nodeType);
+    try {
+      if (!mock)
+        throw new ApplicationError(
+          `No mock for ${wanted.nodeType} ${wanted.operation} (use env.mock)`,
+          { errorType: "VALIDATION", nonRetryable: true, type: "UnmockedActivity" }
+        );
+      const result = toJsonValue(
+        await mock(wanted.args, {
+          runId: run.runId,
+          activityId: wanted.localActivityId,
+          attempt: wanted.attempt,
+          nodeType: wanted.nodeType,
+          operation: wanted.operation,
+          local: true,
+          ...wanted.connection !== void 0 ? { connection: wanted.connection } : {}
+        })
+      );
+      return { localActivityId: wanted.localActivityId, result, attempts: wanted.attempt };
+    } catch (error) {
+      const failure = errorToFailure(error, `node:${wanted.nodeType}`);
+      delete failure.stackTrace;
+      return {
+        localActivityId: wanted.localActivityId,
+        failure: toJsonValue(failure),
+        attempts: wanted.attempt
+      };
+    }
+  }
   afterCommand(run, command) {
     switch (command.type) {
       case "SCHEDULE_ACTIVITY": {
@@ -427,7 +740,8 @@ var TestWorkflowEnvironment = class _TestWorkflowEnvironment {
           retry: command.retry,
           cancelRequested: false,
           ...command.connection !== void 0 ? { connection: command.connection } : {},
-          ...command.scheduleToCloseTimeout !== void 0 ? { scheduleToClose: command.scheduleToCloseTimeout } : {}
+          ...command.scheduleToCloseTimeout !== void 0 ? { scheduleToClose: command.scheduleToCloseTimeout } : {},
+          ...command.scheduleToStartTimeout !== void 0 ? { scheduleToStart: command.scheduleToStartTimeout } : {}
         };
         this.attempts.push(attempt);
         return;
@@ -502,18 +816,25 @@ var TestWorkflowEnvironment = class _TestWorkflowEnvironment {
         return;
       }
       case "CONTINUE_AS_NEW": {
-        const next = this.createRun(
-          run.workflowFn,
-          command.input,
-          {
-            ...run.info,
-            runId: void 0,
-            continuedFromRunId: run.runId,
-            firstRunId: run.info.firstRunId ?? run.runId
-          },
-          run.parent
-        );
-        run.continuedTo = next;
+        const options = command.options;
+        const config = {
+          ...this.chainConfig(run.config),
+          // The run timeout restarts and the attempt count resets; the
+          // execution timeout of the chain carries over (11 §2.20).
+          lastCompletionResult: command.input
+        };
+        if (typeof options["taskQueue"] === "string") config.taskQueue = options["taskQueue"];
+        if (typeof options["workflowTaskTimeout"] === "number")
+          config.workflowTaskTimeoutMs = options["workflowTaskTimeout"];
+        if (options["versioningBehavior"] === "PINNED" || options["versioningBehavior"] === "AUTO_UPGRADE")
+          config.versioningBehavior = options["versioningBehavior"];
+        const memo = options["context"];
+        if (typeof memo === "object" && memo !== null && !Array.isArray(memo)) config.memo = memo;
+        else if (Object.keys(run.state.context).length > 0) config.memo = { ...run.state.context };
+        const retry = options["retry"];
+        if (continueAsNewRetryShape(options) === "run" && typeof retry === "object" && retry !== null && !Array.isArray(retry))
+          config.retry = retry;
+        this.startSuccessor(run, command.input, config);
         this.onClosed(run);
         return;
       }
@@ -526,11 +847,62 @@ var TestWorkflowEnvironment = class _TestWorkflowEnvironment {
         return;
     }
   }
+  /** What a successor of a run inherits (continue-as-new, run retry). */
+  chainConfig(config) {
+    const out = { workflowKey: config.workflowKey, runAttempt: 1 };
+    for (const key of [
+      "businessId",
+      "executionDeadline",
+      "executionTimeoutMs",
+      "runTimeoutMs",
+      "workflowTaskTimeoutMs",
+      "retry",
+      "versioningBehavior",
+      "taskQueue",
+      "memo"
+    ])
+      if (config[key] !== void 0) Object.assign(out, { [key]: config[key] });
+    return out;
+  }
+  /** Start the next run of a chain; the closed run's parent and handles follow it. */
+  startSuccessor(run, input, config) {
+    const next = this.createRun(
+      run.workflowFn,
+      input,
+      {
+        ...run.info,
+        runId: void 0,
+        continuedFromRunId: run.runId,
+        firstRunId: run.info.firstRunId ?? run.runId
+      },
+      run.parent,
+      {},
+      config
+    );
+    run.continuedTo = next;
+    return next;
+  }
   resolveTarget(run, target) {
     if ("runId" in target) return target.runId;
     if ("parent" in target) return run.parent?.runId ?? run.info.parentRunId ?? void 0;
-    if ("childId" in target) return run.children.get(target.childId);
-    return void 0;
+    if ("childId" in target) {
+      let childRunId = run.children.get(target.childId);
+      while (childRunId !== void 0) {
+        const next = this.runs.get(childRunId)?.continuedTo;
+        if (next === void 0) break;
+        childRunId = next;
+      }
+      return childRunId;
+    }
+    return this.resolveWorkflowId(target.workflowKey, target.workflowId, target.firstRunId);
+  }
+  /** The open run of a workflow id, else its latest run (11 §2.1). */
+  resolveWorkflowId(workflowKey, workflowId, firstRunId) {
+    const matching = this.runOrder.map((id) => this.run(id)).filter(
+      (candidate) => candidate.config.workflowKey === workflowKey && candidate.config.businessId === workflowId && (firstRunId === void 0 || (candidate.info.firstRunId ?? candidate.runId) === firstRunId)
+    );
+    const open = matching.find((candidate) => candidate.state.status === "RUNNING");
+    return (open ?? matching[matching.length - 1])?.runId;
   }
   startChild(run, command) {
     const byFn = command.workflowFn !== void 0 && (this.executor !== void 0 || this.registry.byName.has(command.workflowFn));
@@ -563,6 +935,28 @@ var TestWorkflowEnvironment = class _TestWorkflowEnvironment {
       });
       return;
     }
+    const options = command.options;
+    const ms = (key) => typeof options[key] === "number" ? options[key] : void 0;
+    const executionTimeoutMs = ms("executionTimeout");
+    const childKey = command.workflowKey ?? this.registry.byName.get(workflowFn)?.name ?? workflowFn;
+    const config = { workflowKey: childKey, runAttempt: 1 };
+    if (typeof options.workflowId === "string") config.businessId = options.workflowId;
+    if (executionTimeoutMs !== void 0) {
+      config.executionTimeoutMs = executionTimeoutMs;
+      config.executionDeadline = this.clock + executionTimeoutMs;
+    }
+    const runTimeoutMs = ms("runTimeout");
+    if (runTimeoutMs !== void 0) config.runTimeoutMs = runTimeoutMs;
+    const taskTimeoutMs = ms("workflowTaskTimeout");
+    if (taskTimeoutMs !== void 0) config.workflowTaskTimeoutMs = taskTimeoutMs;
+    const startDelayMs = ms("startDelay");
+    if (startDelayMs !== void 0) config.startDelayMs = startDelayMs;
+    if (typeof options.summary === "string") config.summary = options.summary;
+    if (typeof options.details === "string") config.details = options.details;
+    if (options.context !== void 0) config.memo = options.context;
+    if (options.versioningBehavior !== void 0)
+      config.versioningBehavior = options.versioningBehavior;
+    if (options.retry !== void 0) config.retry = options.retry;
     const childRunId = this.createRun(
       workflowFn,
       command.input,
@@ -571,7 +965,8 @@ var TestWorkflowEnvironment = class _TestWorkflowEnvironment {
       {
         parentRunId: run.runId,
         parentClosePolicy: command.options.parentClosePolicy
-      }
+      },
+      config
     );
     run.children.set(command.childId, childRunId);
     this.append(run, {
@@ -628,6 +1023,7 @@ var TestWorkflowEnvironment = class _TestWorkflowEnvironment {
     const mock = this.mocks.get(`${attempt.nodeType}#${attempt.operation}`) ?? this.mocks.get(attempt.nodeType);
     let failure;
     let result = null;
+    let heartbeatDetails = attempt.heartbeatDetails;
     try {
       if (!mock)
         throw new ApplicationError(
@@ -645,7 +1041,11 @@ var TestWorkflowEnvironment = class _TestWorkflowEnvironment {
           attempt: attempt.attempt,
           nodeType: attempt.nodeType,
           operation: attempt.operation,
-          ...attempt.connection !== void 0 ? { connection: attempt.connection } : {}
+          ...attempt.connection !== void 0 ? { connection: attempt.connection } : {},
+          ...attempt.heartbeatDetails !== void 0 ? { heartbeatDetails: attempt.heartbeatDetails } : {},
+          heartbeat: (details) => {
+            heartbeatDetails = toJsonValue(details);
+          }
         })
       );
     } catch (error) {
@@ -686,7 +1086,8 @@ var TestWorkflowEnvironment = class _TestWorkflowEnvironment {
       this.attempts.push({
         ...attempt,
         attempt: attempt.attempt + 1,
-        dueAt: this.clock + decision2.delayMs
+        dueAt: this.clock + decision2.delayMs,
+        ...heartbeatDetails !== void 0 ? { heartbeatDetails } : {}
       });
       return;
     }
@@ -695,7 +1096,8 @@ var TestWorkflowEnvironment = class _TestWorkflowEnvironment {
       this.attempts.push({
         ...attempt,
         attempt: attempt.attempt + 1,
-        dueAt: this.clock + decision.delayMs
+        dueAt: this.clock + decision.delayMs,
+        ...heartbeatDetails !== void 0 ? { heartbeatDetails } : {}
       });
       return;
     }
@@ -709,9 +1111,31 @@ var TestWorkflowEnvironment = class _TestWorkflowEnvironment {
       }
     });
   }
+  /**
+   * Run-level retry (11 §2.17): a failed or run-timed-out run whose policy
+   * allows another attempt is followed by a new run of the chain after the
+   * backoff, with `runAttempt + 1` and the failure as `lastFailure`.
+   */
+  retryRun(run) {
+    if (run.continuedTo !== void 0) return;
+    const last = run.history[run.history.length - 1];
+    if (!last || last.type !== "WORKFLOW_FAILED" && last.type !== "WORKFLOW_TIMED_OUT") return;
+    const failure = last.payload["failure"] ?? { errorType: "TIMEOUT", message: "timed out", timeoutType: "WORKFLOW_RUN" };
+    const decision = computeRunRetryDelay(run.config.retry, run.config.runAttempt, failure);
+    if (!decision.retry) return;
+    const config = {
+      ...this.chainConfig(run.config),
+      runAttempt: run.config.runAttempt + 1,
+      lastFailure: failure
+    };
+    if (decision.delayMs > 0) config.firstTaskDelayMs = decision.delayMs;
+    this.startSuccessor(run, run.state.input ?? null, config);
+  }
   onClosed(run) {
     this.timers = this.timers.filter((timer) => timer.runId !== run.runId);
     this.attempts = this.attempts.filter((entry) => entry.runId !== run.runId);
+    this.dues = this.dues.filter((entry) => entry.runId !== run.runId);
+    this.retryRun(run);
     for (const [childId2, childRunId] of run.children) {
       const child = run.state.children[childId2];
       if (!child || !isChildOpen(child) || childRunId === void 0) continue;
@@ -766,7 +1190,10 @@ var TestWorkflowEnvironment = class _TestWorkflowEnvironment {
       default:
         this.append(parent, {
           type: "CHILD_RUN_TIMED_OUT",
-          payload: { ...base, timeoutType: "WORKFLOW_RUN" }
+          payload: {
+            ...base,
+            timeoutType: last.payload["timeoutType"] === "WORKFLOW_EXECUTION" ? "WORKFLOW_EXECUTION" : "WORKFLOW_RUN"
+          }
         });
     }
   }
@@ -775,10 +1202,21 @@ var TestWorkflowEnvironment = class _TestWorkflowEnvironment {
     let run = this.run(runId);
     while (run.continuedTo !== void 0) run = this.run(run.continuedTo);
     if (run.taskFailure) throw new WorkflowTaskFailedError(run.runId, run.taskFailure);
+    if (this.failOnUnfinishedHandlers && run.unfinishedHandlers !== void 0)
+      throw new UnfinishedHandlersError(run.runId, run.unfinishedHandlers);
     const last = run.history[run.history.length - 1];
     switch (run.state.status) {
       case "COMPLETED":
         return run.state.output ?? null;
+      case "TIMED_OUT":
+        throw new WorkflowFailedError(
+          run.runId,
+          last?.payload["failure"] ?? {
+            errorType: "TIMEOUT",
+            message: "timed out",
+            type: "TimeoutFailure"
+          }
+        );
       case "FAILED":
         throw new WorkflowFailedError(
           run.runId,
@@ -1034,4 +1472,4 @@ async function runWorkflowTaskInVm(script, request, options = {}) {
   }
 }
 
-export { HistoryAssertionError, ReplayError, RunBlockedError, TestRunHandle, TestWorkflowEnvironment, WorkflowFailedError, WorkflowTaskFailedError, assertHistory, bundleToScript, drainJobs, expectIR, jsonCopy, registryOf, replay, replayRequest, runWorkflowTaskInProcess, runWorkflowTaskInVm, simulate };
+export { HistoryAssertionError, ReplayError, RunBlockedError, TestRunHandle, TestWorkflowEnvironment, UnfinishedHandlersError, WorkflowAlreadyStartedError, WorkflowFailedError, WorkflowTaskFailedError, assertHistory, bundleToScript, drainJobs, expectIR, jsonCopy, registryOf, replay, replayRequest, runWorkflowTaskInProcess, runWorkflowTaskInVm, simulate };