@fluidgrids/workflows 2026.1029.1 → 2026.1030.1

package/dist/testing/index.js

@@ -1,29 +1,32 @@
-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 { failedTaskResult } from '../chunk-G5H32GIG.js';
+import { isTier1Workflow, toIR } from '../chunk-SR7TR5KX.js';
+import { irHash, CODE_WORKFLOW_NODE_TYPE, normalizeDefinition } from '../chunk-NWQ5WRLE.js';
 import '../chunk-5LUIDMF4.js';
 import '../chunk-JZ4TOOLN.js';
 import '../chunk-E2VK7J2C.js';
 import '../chunk-7AAZGVKD.js';
-import { createHistoryFile, validateCommands, parseHistoryFile } from '../chunk-A36CCOWS.js';
+import { createHistoryFile, validateCommands, parseHistoryFile } from '../chunk-YEHR4NNE.js';
+import '../chunk-VU5S5A7V.js';
 import { isRecord } from '../chunk-PMCM2OH4.js';
-import { buildWorkflowRegistry, createWorkflowRuntime } from '../chunk-MJ5TGYVG.js';
-import { failureToError, signalName, ApplicationError, errorToFailure, CancelledFailure, DeterminismViolation } from '../chunk-KXJDRQ6G.js';
+import { buildWorkflowRegistry, createWorkflowRuntime } from '../chunk-2D3MYIIF.js';
+import { failureToError, signalName, ApplicationError, errorToFailure, CancelledFailure, DeterminismViolation } from '../chunk-6A2FGSUS.js';
 import '../chunk-M272AHEX.js';
 import { TASK_PRELUDE } from '../chunk-4LYSEANA.js';
-import { runRetryPolicyOf, toMs, isDurableWorkflow } from '../chunk-7ILGCUI6.js';
+import { isActivityImplementation, isActivityDefinition, ACTIVITY_IMPL_MARKER, ACTIVITY_MARKER, runRetryPolicyOf, toMs, findActivityImplementation, executeActivity, isDurableWorkflow } from '../chunk-C4F5KJTI.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 { COMMAND_FEATURES, codeFeaturesEnabledBy, applyEvent, projectRunState, isActivityOpen, hasUnprocessedInput, initialRunState, eventsForCommands, continueAsNewRetryShape, isChildOpen } from '../chunk-AE5Q6ZAJ.js';
+import '../chunk-AC6ZEXVR.js';
+import { RUNTIME_RELEASE, HISTORY_PROTOCOL, isCommandEvent, TERMINAL_EVENTS, isInputEvent, TERMINAL_COMMANDS, computeRetryDelay, computeRunRetryDelay } from '../chunk-5HIVIV53.js';
 import { createContext, Script } from 'vm';
 
 // src/testing/host.ts
 function drainJobs() {
   return new Promise((resolve) => setImmediate(resolve));
 }
-function registryOf(workflows) {
-  return buildWorkflowRegistry([["in-process", { ...workflows }]]);
+function registryOf(workflows, interceptors) {
+  return buildWorkflowRegistry([
+    ["in-process", { ...workflows, ...interceptors !== void 0 ? { interceptors } : {} }]
+  ]);
 }
 async function hostLoop(abi, requestJson) {
   abi.start(requestJson);
@@ -39,6 +42,32 @@ async function runWorkflowTaskInProcess(registry, request) {
 }
 
 // src/testing/environment.ts
+var QueryRejectedError = class extends Error {
+  constructor(runId, queryName, message) {
+    super(message);
+    this.runId = runId;
+    this.queryName = queryName;
+    this.name = "QueryRejectedError";
+  }
+  runId;
+  queryName;
+};
+var QueryFailedError = class extends Error {
+  constructor(runId, queryName, message) {
+    super(message);
+    this.runId = runId;
+    this.queryName = queryName;
+    this.name = "QueryFailedError";
+  }
+  runId;
+  queryName;
+};
+var UpdateRefusedError = class extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "UpdateRefusedError";
+  }
+};
 var WorkflowAlreadyStartedError = class extends Error {
   constructor(workflowKey, workflowId, existingRunId) {
     super(
@@ -96,7 +125,7 @@ var RunBlockedError = class extends Error {
   }
   runId;
 };
-var TestRunHandle = class {
+var TestRunHandle = class _TestRunHandle {
   constructor(env, runId) {
     this.env = env;
     this.runId = runId;
@@ -126,6 +155,22 @@ var TestRunHandle = class {
     this.env.terminate(this.runId, reason);
     await this.env.runUntilIdle(false);
   }
+  /** Send an update and run until idle (Phase C). */
+  update(update, args, options = {}) {
+    return this.env.update(this.runId, update, args, options);
+  }
+  /** Answer a query from the run's history (Phase C custom queries and the built-ins). */
+  query(query, args) {
+    return this.env.query(this.runId, query, args);
+  }
+  /** Reset the run (11 §2.7): a new run forked at a completed task; this one is terminated. */
+  async reset(options = {}) {
+    return new _TestRunHandle(this.env, await this.env.reset(this.runId, options));
+  }
+  /** Sink calls the run's tasks made (Phase C). */
+  sinkCalls() {
+    return this.env.sinkCallsOf(this.runId);
+  }
   /** Run until this run (or the last run of its continue-as-new chain) ends; its output. */
   async result() {
     return this.env.resultOf(this.runId);
@@ -149,6 +194,14 @@ var FAILED_STATUSES = /* @__PURE__ */ new Set([
   "TERMINATED",
   "TIMED_OUT"
 ]);
+function admittedPayload(update) {
+  return {
+    updateId: update.updateId,
+    name: update.name,
+    args: update.args,
+    ...update.headers !== void 0 ? { headers: { ...update.headers } } : {}
+  };
+}
 function toJsonValue(value) {
   if (value === void 0) return null;
   const text = JSON.stringify(value);
@@ -158,6 +211,8 @@ var TestWorkflowEnvironment = class _TestWorkflowEnvironment {
   clock;
   timeSkipping;
   enabled;
+  /** The bundle features the gate's flags enable, sent with every task (`request.features`). */
+  codeFeatures;
   failOnUnfinishedHandlers;
   historyRelease;
   dues = [];
@@ -173,19 +228,65 @@ var TestWorkflowEnvironment = class _TestWorkflowEnvironment {
   timers = [];
   mockedChildren = [];
   runCounter = 0;
+  updateCounter = 0;
   executor;
   workflowKeys;
+  interceptors;
+  activityImpls;
+  activityInterceptors;
+  connections;
+  sinks;
+  /** Attempts that handed their completion to an outside system (`completeAsync`), by token. */
+  asyncAttempts = /* @__PURE__ */ new Map();
   constructor(options) {
     this.clock = toDate(options.startTime);
     this.timeSkipping = options.timeSkipping !== false;
-    this.enabled = options.enabled ?? "parity";
+    this.enabled = options.enabled ?? new Set(COMMAND_FEATURES);
+    this.codeFeatures = codeFeaturesEnabledBy(this.enabled);
     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);
+    this.interceptors = options.interceptors;
+    this.registry = registryOf(this.workflows, this.interceptors);
     this.executor = options.taskExecutor;
     this.workflowKeys = { ...options.workflowKeys ?? {} };
+    this.activityImpls = [...options.activities ?? []];
+    for (const impl of this.activityImpls)
+      if (!isActivityImplementation(impl))
+        throw new TypeError("activities must be implementActivity() or defineActivity() values");
+    this.activityInterceptors = [...options.activityInterceptors ?? []];
+    this.connections = { ...options.connections ?? {} };
+    this.sinks = { ...options.sinks ?? {} };
+  }
+  /** Register a user-activity implementation (Phase C). A later one replaces an earlier of the same name. */
+  registerActivity(implementation) {
+    if (!isActivityImplementation(implementation))
+      throw new TypeError(
+        "registerActivity needs an implementActivity() or defineActivity() value"
+      );
+    const index = this.activityImpls.findIndex(
+      (impl) => impl.name === implementation.name && impl.dynamic === implementation.dynamic
+    );
+    if (index >= 0) this.activityImpls.splice(index, 1);
+    this.activityImpls.push(implementation);
+  }
+  /** Mock a user activity by name or declaration (Phase C). */
+  mockActivity(activity, fn) {
+    const name = typeof activity === "string" ? activity : activity.name;
+    if (typeof activity !== "string" && !isActivityDefinition(activity))
+      throw new TypeError("mockActivity needs an activity name or a declareActivity() value");
+    this.registerActivity(
+      Object.freeze({
+        __fluidgrids: ACTIVITY_MARKER,
+        name,
+        options: typeof activity === "string" ? {} : activity.options,
+        implementation: ACTIVITY_IMPL_MARKER,
+        // The mock receives the activity's JSON args, typed by the declaration.
+        fn: (ctx, args) => fn(args, ctx),
+        dynamic: false
+      })
+    );
   }
   /** Create an environment. */
   static async create(options = {}) {
@@ -217,6 +318,10 @@ var TestWorkflowEnvironment = class _TestWorkflowEnvironment {
     if (nodeType === void 0) this.held.clear();
     else this.held.delete(nodeType);
   }
+  /** The hold key of an attempt: its node type, or the task queue of a user activity. */
+  holdKeyOf(entry) {
+    return entry.kind === "user" ? entry.taskQueue ?? "" : entry.nodeType;
+  }
   isHeld(nodeType) {
     return this.held.has("*") || this.held.has(nodeType);
   }
@@ -232,11 +337,17 @@ var TestWorkflowEnvironment = class _TestWorkflowEnvironment {
     );
     const declared = this.workflows[workflowFn]?.options ?? {};
     const workflowKey = options.workflowKey ?? (typeof definition === "string" ? this.workflows[workflowFn]?.name ?? workflowFn : definition.name);
+    if (options.update !== void 0 && options.startDelay !== void 0)
+      throw new UpdateRefusedError(
+        "Update-with-start cannot be combined with a start delay (11 \xA72.6)"
+      );
     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);
+        if (options.update !== void 0)
+          this.addUpdate(this.run(existing), options.update, "PENDING");
         await this.runUntilIdle(false);
         return new TestRunHandle(this, existing);
       }
@@ -261,7 +372,11 @@ var TestWorkflowEnvironment = class _TestWorkflowEnvironment {
       ...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 } : {}
+      ...(options.versioningBehavior ?? declared.versioningBehavior) !== void 0 ? { versioningBehavior: options.versioningBehavior ?? declared.versioningBehavior } : {},
+      ...options.headers !== void 0 ? { headers: { ...options.headers } } : {},
+      ...options.searchAttributes !== void 0 ? { searchAttributes: toJsonValue(options.searchAttributes) } : {},
+      ...options.fairnessKey !== void 0 ? { fairnessKey: options.fairnessKey } : {},
+      ...options.fairnessWeight !== void 0 ? { fairnessWeight: options.fairnessWeight } : {}
     };
     const runId = this.createRun(
       workflowFn,
@@ -269,13 +384,245 @@ var TestWorkflowEnvironment = class _TestWorkflowEnvironment {
       { ...options.info, ...options.runId !== void 0 ? { runId: options.runId } : {} },
       void 0,
       {},
-      config
+      config,
+      options.update !== void 0 ? [this.newUpdate(options.update, "ADMITTED")] : []
     );
     for (const signal of options.signals ?? [])
       this.deliverSignal(runId, signal.name, signal.payload);
     await this.runUntilIdle(false);
     return new TestRunHandle(this, runId);
   }
+  /**
+   * Update-with-start (11 §2.6): start the run (or, with
+   * `idConflictPolicy: USE_EXISTING`, reach the open one) and deliver the
+   * update before any other task runs.
+   */
+  async startWithUpdate(definition, options) {
+    const updateId = options.update.updateId ?? this.nextUpdateId();
+    const handle = await this.start(definition, {
+      ...options,
+      update: { ...options.update, updateId }
+    });
+    return { handle, update: this.updateResultOf(handle.runId, updateId) };
+  }
+  nextUpdateId() {
+    this.updateCounter += 1;
+    return `u${this.updateCounter}`;
+  }
+  /** A new update row (not attached to a run yet). */
+  newUpdate(update, status) {
+    return {
+      updateId: update.updateId ?? this.nextUpdateId(),
+      name: update.name,
+      args: toJsonValue(update.args),
+      ...update.headers !== void 0 ? { headers: { ...update.headers } } : {},
+      status
+    };
+  }
+  /** Record an update on a run: pending (delivered by the next task) or admitted into history. */
+  addUpdate(run, update, status) {
+    const existing = update.updateId !== void 0 ? run.updates.get(update.updateId) : void 0;
+    if (existing) return existing;
+    const entry = this.newUpdate(update, status);
+    run.updates.set(entry.updateId, entry);
+    if (status === "ADMITTED")
+      this.append(run, { type: "UPDATE_ADMITTED", payload: admittedPayload(entry) });
+    else {
+      if (run.delayedUntil !== void 0) this.endDelay(run);
+      else this.scheduleTask(run);
+    }
+    return entry;
+  }
+  /** Schedule a workflow task for a run that has none (an update needs no input event). */
+  scheduleTask(run) {
+    if (run.state.status !== "RUNNING" || run.state.task.state !== "NONE") return;
+    if (run.delayedUntil !== void 0) 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);
+  }
+  /**
+   * Send an update to a run and run until idle (Phase C, 05 §6). The result
+   * is `REJECTED` (the validator refused it or no handler took it; nothing is
+   * written to history), `COMPLETED`, or `ACCEPTED` while its handler still
+   * waits (for a timer without time skipping, or with `waitFor: ACCEPTED`).
+   */
+  async update(runId, update, args, options = {}) {
+    const run = this.run(runId);
+    const name = typeof update === "string" ? update : update.name;
+    if (options.updateId !== void 0 && run.updates.has(options.updateId))
+      return this.updateResultOf(runId, options.updateId);
+    if (run.state.status !== "RUNNING")
+      throw new UpdateRefusedError(`Run ${runId} is ${run.state.status}; it takes no updates`);
+    const entry = this.addUpdate(
+      run,
+      {
+        name,
+        args,
+        ...options.updateId !== void 0 ? { updateId: options.updateId } : {},
+        ...options.headers !== void 0 ? { headers: options.headers } : {}
+      },
+      "PENDING"
+    );
+    await this.runUntilIdle(false);
+    return this.updateResultOf(runId, entry.updateId);
+  }
+  /** The current result of an update. */
+  updateResultOf(runId, updateId) {
+    const entry = this.run(runId).updates.get(updateId);
+    if (!entry) throw new Error(`Run ${runId} has no update ${updateId}`);
+    return {
+      updateId,
+      status: entry.status === "ADMITTED" ? "PENDING" : entry.status,
+      ...entry.result !== void 0 ? { result: entry.result } : {},
+      ...entry.failure !== void 0 ? { failure: entry.failure } : {}
+    };
+  }
+  /** Answer a query from the run's history (a replay-only `query` task). */
+  async query(runId, query, args) {
+    const run = this.run(runId);
+    const name = typeof query === "string" ? query : query.name;
+    const request = {
+      protocol: HISTORY_PROTOCOL,
+      kind: "query",
+      workflowFn: run.workflowFn,
+      info: run.info,
+      history: run.history,
+      nowMs: this.clock,
+      queries: [{ queryId: "q1", name, args: toJsonValue(args) }]
+    };
+    const result = await this.execute(request);
+    const answer = result.queryResults?.[0];
+    if (answer?.rejected === true)
+      throw new QueryRejectedError(runId, name, answer.error ?? `No handler for query ${name}`);
+    if (answer === void 0 || answer.error !== void 0)
+      throw new QueryFailedError(
+        runId,
+        name,
+        answer?.error ?? result.failure?.message ?? "The query was not answered"
+      );
+    return answer.value ?? null;
+  }
+  /** Sink calls the run's tasks made. */
+  sinkCallsOf(runId) {
+    return this.run(runId).sinkCalls.map((call) => ({ ...call, args: [...call.args] }));
+  }
+  /**
+   * Reset a run (11 §2.7): a new run whose history is the original's up to
+   * and including the chosen completed workflow task (with its commands),
+   * then `WORKFLOW_RESET`, then the signals (and, as `UPDATE_ADMITTED`, the
+   * accepted updates) received after that point. The original is terminated
+   * with reason `RESET`; children it started before the point follow the new
+   * run, the others get their parent-close policy. Returns the new run id.
+   */
+  async reset(runId, options = {}) {
+    const original = this.run(runId);
+    const history = original.history;
+    const points = [];
+    for (const event of history) {
+      if (event.type !== "WORKFLOW_TASK_COMPLETED") continue;
+      const taskId = typeof event.payload["taskId"] === "string" ? event.payload["taskId"] : "";
+      let end = event.seq;
+      let closes = false;
+      while (end < history.length) {
+        const next = history[end];
+        if (!next || !isCommandEvent(next) || next.taskId !== taskId) break;
+        if (TERMINAL_EVENTS.has(next.type)) closes = true;
+        end += 1;
+      }
+      if (!closes) points.push({ seq: event.seq, cut: end });
+    }
+    const point = options.toSeq !== void 0 ? [...points].reverse().find((entry) => entry.seq <= (options.toSeq ?? 0)) : options.to === "FIRST_TASK" ? points[0] : points[points.length - 1];
+    if (!point) throw new Error(`Run ${runId} has no completed workflow task to reset to`);
+    const cut = point.cut;
+    const copied = history.slice(0, cut).map((event) => ({ ...event, payload: { ...event.payload } }));
+    const later = history.slice(cut);
+    const reapplySignals = options.reapplySignals !== false;
+    const reapplyUpdates = options.reapplyUpdates !== false;
+    const keptChildren = new Set(
+      copied.filter((event) => event.type === "CHILD_RUN_INITIATED").map((event) => String(event.payload["childId"]))
+    );
+    this.runCounter += 1;
+    const newRunId = `run-${this.runCounter}`;
+    if (original.state.status === "RUNNING") {
+      original.resetTo = newRunId;
+      this.append(original, { type: "WORKFLOW_TERMINATED", payload: { reason: "RESET" } });
+      this.onClosed(original, keptChildren);
+    } else original.resetTo = newRunId;
+    const fork = {
+      runId: newRunId,
+      workflowFn: original.workflowFn,
+      history: copied,
+      state: projectRunState(copied),
+      taskCounter: copied.filter((event) => event.type === "WORKFLOW_TASK_SCHEDULED").length,
+      info: { ...original.info, runId: newRunId },
+      children: new Map([...original.children].filter(([childId]) => keptChildren.has(childId))),
+      config: { ...original.config },
+      ...original.parent ? { parent: original.parent } : {},
+      updates: /* @__PURE__ */ new Map(),
+      sinkCalls: []
+    };
+    this.runs.set(newRunId, fork);
+    this.runOrder.push(newRunId);
+    for (const [childId, childRunId] of fork.children) {
+      const child = childRunId !== void 0 ? this.runs.get(childRunId) : void 0;
+      if (child) child.parent = { runId: newRunId, childId };
+    }
+    this.append(fork, {
+      type: "WORKFLOW_RESET",
+      payload: {
+        fromRunId: runId,
+        toSeq: cut,
+        reapplySignals,
+        reapplyUpdates,
+        ...options.reason !== void 0 ? { reason: options.reason } : {}
+      }
+    });
+    for (const [activityId, activity] of Object.entries(fork.state.activities)) {
+      if (!isActivityOpen(activity)) continue;
+      const scheduled = copied[activity.scheduledSeq - 1];
+      if (scheduled?.type !== "ACTIVITY_SCHEDULED") continue;
+      this.afterCommand(fork, {
+        // The run-event schema checked the payload; it is the command that scheduled it.
+        ...scheduled.payload,
+        type: "SCHEDULE_ACTIVITY",
+        activityId
+      });
+    }
+    for (const [timerId, timer] of Object.entries(fork.state.timers))
+      if (timer.status === "PENDING")
+        this.timers.push({ runId: newRunId, timerId, fireAt: Date.parse(timer.fireAt) });
+    for (const event of later) {
+      if (event.type === "SIGNAL_RECEIVED" && reapplySignals)
+        this.append(fork, { type: "SIGNAL_RECEIVED", payload: { ...event.payload } });
+      if (reapplyUpdates && (event.type === "UPDATE_ACCEPTED" || event.type === "UPDATE_ADMITTED") && !fork.updates.has(String(event.payload["updateId"])) && fork.state.updates[String(event.payload["updateId"])] === void 0) {
+        const headers = event.payload["headers"];
+        this.addUpdate(
+          fork,
+          {
+            updateId: String(event.payload["updateId"]),
+            name: String(event.payload["name"]),
+            args: event.payload["args"] ?? null,
+            ...typeof headers === "object" && headers !== null && !Array.isArray(headers) ? (
+              // The run-event schema checked the headers map.
+              { headers }
+            ) : {}
+          },
+          "ADMITTED"
+        );
+      }
+    }
+    if (hasUnprocessedInput(fork.history)) this.scheduleTask(fork);
+    await this.runUntilIdle(false);
+    return newRunId;
+  }
   durationConfig(value, key) {
     const ms = optionalDuration(value, key);
     if (ms === void 0) return {};
@@ -351,7 +698,7 @@ var TestWorkflowEnvironment = class _TestWorkflowEnvironment {
       if (value === definition) return name2;
     const name = Object.hasOwn(this.workflows, definition.name) ? `${definition.name}#${this.runCounter}` : definition.name;
     this.workflows[name] = definition;
-    this.registry = registryOf(this.workflows);
+    this.registry = registryOf(this.workflows, this.interceptors);
     return name;
   }
   run(runId) {
@@ -359,7 +706,7 @@ var TestWorkflowEnvironment = class _TestWorkflowEnvironment {
     if (!run) throw new Error(`Unknown run ${runId}`);
     return run;
   }
-  createRun(workflowFn, input, info, parent, extraStarted = {}, config = { workflowKey: workflowFn, runAttempt: 1 }) {
+  createRun(workflowFn, input, info, parent, extraStarted = {}, config = { workflowKey: workflowFn, runAttempt: 1 }, admitted = []) {
     this.runCounter += 1;
     const runId = info.runId ?? `run-${this.runCounter}`;
     const snapshot = {
@@ -381,7 +728,9 @@ var TestWorkflowEnvironment = class _TestWorkflowEnvironment {
       info: snapshot,
       children: /* @__PURE__ */ new Map(),
       config,
-      ...parent ? { parent } : {}
+      ...parent ? { parent } : {},
+      updates: /* @__PURE__ */ new Map(),
+      sinkCalls: []
     };
     const firstTaskDelay = config.startDelayMs ?? config.firstTaskDelayMs;
     if (firstTaskDelay !== void 0 && firstTaskDelay > 0) {
@@ -394,19 +743,30 @@ var TestWorkflowEnvironment = class _TestWorkflowEnvironment {
       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: config.taskQueue ?? "managed",
-        randomnessSeed: runId,
-        ...extraStarted,
-        ...this.startedFields(config)
+    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: config.taskQueue ?? "managed",
+          randomnessSeed: runId,
+          ...extraStarted,
+          ...this.startedFields(config)
+        }
+      },
+      admitted.length === 0
+    );
+    if (admitted.length > 0) {
+      for (const update of admitted) {
+        run.updates.set(update.updateId, update);
+        this.append(run, { type: "UPDATE_ADMITTED", payload: admittedPayload(update) }, false);
       }
-    });
+      this.scheduleTask(run);
+    }
     return runId;
   }
   /** The R2 fields of `WORKFLOW_STARTED`, each written only when it is set. */
@@ -434,9 +794,13 @@ var TestWorkflowEnvironment = class _TestWorkflowEnvironment {
     if (config.lastCompletionResult !== void 0 && this.historyRelease >= 2)
       out["lastCompletionResult"] = config.lastCompletionResult;
     if (config.lastFailure !== void 0) out["lastFailure"] = toJsonValue(config.lastFailure);
+    if (config.headers !== void 0) out["headers"] = { ...config.headers };
+    if (config.searchAttributes !== void 0) out["searchAttributes"] = config.searchAttributes;
+    if (config.fairnessKey !== void 0) out["fairnessKey"] = config.fairnessKey;
+    if (config.fairnessWeight !== void 0) out["fairnessWeight"] = config.fairnessWeight;
     return out;
   }
-  append(run, draft) {
+  append(run, draft, schedule = true) {
     const event = {
       seq: run.history.length + 1,
       type: draft.type,
@@ -447,7 +811,7 @@ var TestWorkflowEnvironment = class _TestWorkflowEnvironment {
     applyEvent(run.state, event);
     run.history.push(event);
     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") {
+    if (schedule && 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 = {
@@ -465,19 +829,9 @@ var TestWorkflowEnvironment = class _TestWorkflowEnvironment {
   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);
+    this.scheduleTask(run);
   }
-  deliverSignal(runId, name, payload) {
+  deliverSignal(runId, name, payload, headers) {
     const run = this.runs.get(runId);
     if (!run || run.state.status !== "RUNNING") return false;
     this.append(run, {
@@ -485,7 +839,8 @@ var TestWorkflowEnvironment = class _TestWorkflowEnvironment {
       payload: {
         name,
         payload: toJsonValue(payload),
-        receivedAt: new Date(this.clock).toISOString()
+        receivedAt: new Date(this.clock).toISOString(),
+        ...headers !== void 0 ? { headers: { ...headers } } : {}
       }
     });
     return true;
@@ -523,7 +878,7 @@ var TestWorkflowEnvironment = class _TestWorkflowEnvironment {
         continue;
       }
       const attempt = this.attempts.find(
-        (entry) => entry.dueAt <= this.clock && !this.isHeld(entry.nodeType)
+        (entry) => entry.dueAt <= this.clock && !this.isHeld(this.holdKeyOf(entry))
       );
       if (attempt) {
         this.attempts = this.attempts.filter((entry) => entry !== attempt);
@@ -545,12 +900,12 @@ var TestWorkflowEnvironment = class _TestWorkflowEnvironment {
   }
   /** 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;
+    return this.isHeld(this.holdKeyOf(entry)) && entry.scheduleToStart !== void 0 ? entry.dueAt + entry.scheduleToStart : void 0;
   }
   nextDue() {
     const due = [...this.timers.map((timer) => timer.fireAt)];
     for (const entry of this.attempts) {
-      if (!this.isHeld(entry.nodeType)) due.push(entry.dueAt);
+      if (!this.isHeld(this.holdKeyOf(entry))) due.push(entry.dueAt);
       const deadline = this.heldDeadline(entry);
       if (deadline !== void 0) due.push(deadline);
     }
@@ -627,13 +982,25 @@ var TestWorkflowEnvironment = class _TestWorkflowEnvironment {
   async runTask(run) {
     const taskId = run.state.task.taskId ?? `${run.runId}-task-${run.taskCounter}`;
     this.append(run, { type: "WORKFLOW_TASK_STARTED", payload: { taskId, attempt: 1 } });
+    const delivered = [...run.updates.values()].filter(
+      (update) => update.status === "PENDING" || update.status === "ADMITTED"
+    );
+    const updates = delivered.map((update) => ({
+      updateId: update.updateId,
+      name: update.name,
+      args: update.args,
+      ...update.headers !== void 0 ? { headers: { ...update.headers } } : {},
+      ...update.status === "ADMITTED" ? { admitted: true } : {}
+    }));
     const request = {
       protocol: HISTORY_PROTOCOL,
       kind: "task",
       workflowFn: run.workflowFn,
       info: run.info,
       history: run.history,
-      nowMs: this.clock
+      nowMs: this.clock,
+      ...updates.length > 0 ? { updates } : {},
+      ...this.codeFeatures.length > 0 ? { features: [...this.codeFeatures] } : {}
     };
     const result = await this.executeWithLocalActivities(run, request);
     const fail = (cause, message) => {
@@ -648,7 +1015,11 @@ var TestWorkflowEnvironment = class _TestWorkflowEnvironment {
       run.taskFailure = result;
       return;
     }
-    const checked = validateCommands(result.commands, { enabled: this.enabled });
+    const relief = {
+      grantedLocalActivityIds: [],
+      deliveredUpdateIds: delivered.map((update) => update.updateId)
+    };
+    const checked = validateCommands(result.commands, { enabled: this.enabled, relief });
     if (!checked.ok) {
       fail(checked.cause, checked.issues.map((issue) => issue.message).join("; "));
       return;
@@ -656,7 +1027,18 @@ var TestWorkflowEnvironment = class _TestWorkflowEnvironment {
     const drafts = eventsForCommands(run.state, checked.commands, {
       taskId,
       nowMs: this.clock,
-      enabled: this.enabled
+      enabled: this.enabled,
+      relief,
+      updates: Object.fromEntries(
+        delivered.map((update) => [
+          update.updateId,
+          {
+            name: update.name,
+            args: update.args,
+            ...update.headers !== void 0 ? { headers: update.headers } : {}
+          }
+        ])
+      )
     });
     if (!drafts.ok) {
       fail(drafts.cause, drafts.issues.map((issue) => issue.message).join("; "));
@@ -664,12 +1046,55 @@ var TestWorkflowEnvironment = class _TestWorkflowEnvironment {
     }
     if (result.unfinishedHandlers !== void 0 && result.unfinishedHandlers.length > 0)
       run.unfinishedHandlers = result.unfinishedHandlers;
+    this.recordUpdateReplies(run, checked.commands, delivered);
+    this.runSinks(run, result.sinkCalls ?? []);
     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);
   }
+  /** What a task's update replies mean for the run's update rows. */
+  recordUpdateReplies(run, commands, delivered) {
+    const answered = /* @__PURE__ */ new Set();
+    for (const command of commands) {
+      if (command.type !== "ACCEPT_UPDATE" && command.type !== "REJECT_UPDATE" && command.type !== "COMPLETE_UPDATE")
+        continue;
+      const entry = run.updates.get(command.updateId);
+      if (!entry) continue;
+      answered.add(command.updateId);
+      if (command.type === "ACCEPT_UPDATE") entry.status = "ACCEPTED";
+      else if (command.type === "REJECT_UPDATE") {
+        entry.status = "REJECTED";
+        entry.failure = command.failure;
+      } else {
+        entry.status = "COMPLETED";
+        if (command.failure !== void 0) entry.failure = command.failure;
+        else entry.result = command.result ?? null;
+      }
+    }
+    for (const update of delivered)
+      if (!answered.has(update.updateId) && update.status === "PENDING") {
+        update.status = "REJECTED";
+        update.failure = {
+          errorType: "VALIDATION",
+          type: "UpdateNotHandled",
+          message: `The workflow task did not answer update "${update.name}"`
+        };
+      }
+  }
+  /** Keep a task's sink calls and call the configured sinks with them. */
+  runSinks(run, calls) {
+    for (const call of calls) {
+      run.sinkCalls.push(call);
+      const fn = this.sinks[call.sink]?.[call.fn];
+      if (fn === void 0) continue;
+      try {
+        fn(...call.args);
+      } catch {
+      }
+    }
+  }
   execute(request) {
     return this.executor ? this.executor(request) : runWorkflowTaskInProcess(this.registry, request);
   }
@@ -728,6 +1153,7 @@ var TestWorkflowEnvironment = class _TestWorkflowEnvironment {
   afterCommand(run, command) {
     switch (command.type) {
       case "SCHEDULE_ACTIVITY": {
+        const user = command.kind === "user";
         const attempt = {
           runId: run.runId,
           activityId: command.activityId,
@@ -735,11 +1161,14 @@ var TestWorkflowEnvironment = class _TestWorkflowEnvironment {
           dueAt: this.clock,
           scheduledAt: this.clock,
           args: command.args,
-          nodeType: command.nodeType,
-          operation: command.operation,
+          kind: command.kind,
+          nodeType: user ? "" : command.nodeType,
+          operation: user ? command.activityName : command.operation,
           retry: command.retry,
           cancelRequested: false,
-          ...command.connection !== void 0 ? { connection: command.connection } : {},
+          ...!user && command.connection !== void 0 ? { connection: command.connection } : {},
+          ...user ? { taskQueue: command.taskQueue } : {},
+          ...command.headers !== void 0 ? { headers: { ...command.headers } } : {},
           ...command.scheduleToCloseTimeout !== void 0 ? { scheduleToClose: command.scheduleToCloseTimeout } : {},
           ...command.scheduleToStartTimeout !== void 0 ? { scheduleToStart: command.scheduleToStartTimeout } : {}
         };
@@ -1020,40 +1449,151 @@ var TestWorkflowEnvironment = class _TestWorkflowEnvironment {
       });
       return;
     }
-    const mock = this.mocks.get(`${attempt.nodeType}#${attempt.operation}`) ?? this.mocks.get(attempt.nodeType);
     let failure;
     let result = null;
     let heartbeatDetails = attempt.heartbeatDetails;
+    let asyncToken;
     try {
-      if (!mock)
-        throw new ApplicationError(
-          `No mock for ${attempt.nodeType} ${attempt.operation} (use env.mock)`,
-          {
-            errorType: "VALIDATION",
-            nonRetryable: true,
-            type: "UnmockedActivity"
+      if (attempt.kind === "user") {
+        const impl = findActivityImplementation(this.activityImpls, attempt.operation);
+        if (!impl)
+          throw new ApplicationError(
+            `No implementation of activity ${attempt.operation} (use env.registerActivity or env.mockActivity)`,
+            { errorType: "VALIDATION", nonRetryable: true, type: "ActivityNotRegistered" }
+          );
+        const ctx = this.activityContext(
+          attempt,
+          (details) => {
+            heartbeatDetails = details;
+          },
+          (token) => {
+            asyncToken = token;
           }
         );
-      result = toJsonValue(
-        await mock(attempt.args, {
-          runId: attempt.runId,
-          activityId: attempt.activityId,
-          attempt: attempt.attempt,
-          nodeType: attempt.nodeType,
-          operation: attempt.operation,
-          ...attempt.connection !== void 0 ? { connection: attempt.connection } : {},
-          ...attempt.heartbeatDetails !== void 0 ? { heartbeatDetails: attempt.heartbeatDetails } : {},
-          heartbeat: (details) => {
-            heartbeatDetails = toJsonValue(details);
-          }
-        })
-      );
+        result = toJsonValue(
+          await executeActivity(impl, ctx, attempt.args, this.activityInterceptors)
+        );
+      } else {
+        const mock = this.mocks.get(`${attempt.nodeType}#${attempt.operation}`) ?? this.mocks.get(attempt.nodeType);
+        if (!mock)
+          throw new ApplicationError(
+            `No mock for ${attempt.nodeType} ${attempt.operation} (use env.mock)`,
+            {
+              errorType: "VALIDATION",
+              nonRetryable: true,
+              type: "UnmockedActivity"
+            }
+          );
+        result = toJsonValue(
+          await mock(attempt.args, {
+            runId: attempt.runId,
+            activityId: attempt.activityId,
+            attempt: attempt.attempt,
+            nodeType: attempt.nodeType,
+            operation: attempt.operation,
+            ...attempt.connection !== void 0 ? { connection: attempt.connection } : {},
+            ...attempt.heartbeatDetails !== void 0 ? { heartbeatDetails: attempt.heartbeatDetails } : {},
+            heartbeat: (details) => {
+              heartbeatDetails = toJsonValue(details);
+            }
+          })
+        );
+      }
     } catch (error) {
-      failure = errorToFailure(error, `node:${attempt.nodeType}`);
+      failure = errorToFailure(
+        error,
+        attempt.kind === "user" ? "sdk-ts" : `node:${attempt.nodeType}`
+      );
       delete failure.stackTrace;
     }
     if (run.state.status !== "RUNNING" || !isActivityOpen(run.state.activities[attempt.activityId] ?? activity))
       return;
+    if (asyncToken !== void 0 && failure === void 0) {
+      this.asyncAttempts.set(asyncToken, {
+        ...attempt,
+        ...heartbeatDetails !== void 0 ? { heartbeatDetails } : {}
+      });
+      return;
+    }
+    this.finishAttempt(run, attempt, failure, result, heartbeatDetails);
+  }
+  /** The `ActivityContext` of one user-activity attempt. */
+  activityContext(attempt, onHeartbeat, onAsync) {
+    const run = this.runs.get(attempt.runId);
+    const listeners = /* @__PURE__ */ new Set();
+    const signal = {
+      get aborted() {
+        return attempt.cancelRequested;
+      },
+      addEventListener: (_type, listener) => {
+        listeners.add(listener);
+      },
+      removeEventListener: (_type, listener) => {
+        listeners.delete(listener);
+      }
+    };
+    return {
+      info: {
+        runId: attempt.runId,
+        workspaceId: this.workspaceId,
+        ...run?.config.workflowKey !== void 0 ? { workflowKey: run.config.workflowKey } : {},
+        activityId: attempt.activityId,
+        activityName: attempt.operation,
+        taskQueue: attempt.taskQueue ?? "managed",
+        attempt: attempt.attempt,
+        ...attempt.heartbeatDetails !== void 0 ? { heartbeatDetails: attempt.heartbeatDetails } : {},
+        headers: { ...attempt.headers ?? {} }
+      },
+      heartbeat: (details) => {
+        onHeartbeat(toJsonValue(details));
+        return Promise.resolve({ cancelRequested: attempt.cancelRequested, paused: false });
+      },
+      cancellationSignal: signal,
+      completeAsync: () => {
+        const token = `test-task-token:${attempt.runId}:${attempt.activityId}:${attempt.attempt}`;
+        onAsync(token);
+        return Promise.resolve(token);
+      },
+      connection: (name) => {
+        const found = this.connections[name];
+        if (found === void 0)
+          return Promise.reject(
+            new ApplicationError(`No connection "${name}" in the test environment`, {
+              errorType: "AUTHORIZATION",
+              nonRetryable: true,
+              type: "ConnectionNotReleased"
+            })
+          );
+        return Promise.resolve({ ...found });
+      }
+    };
+  }
+  /** Complete an activity that called `completeAsync()` (`completeActivityAsync`). */
+  async completeActivityAsync(token, result) {
+    const attempt = this.takeAsync(token);
+    const run = this.run(attempt.runId);
+    this.finishAttempt(run, attempt, void 0, toJsonValue(result), attempt.heartbeatDetails);
+    await this.runUntilIdle(false);
+  }
+  /** Fail an activity that called `completeAsync()` (`failActivityAsync`); the retry policy applies. */
+  async failActivityAsync(token, error) {
+    const attempt = this.takeAsync(token);
+    const run = this.run(attempt.runId);
+    const failure = errorToFailure(error, "sdk-ts");
+    delete failure.stackTrace;
+    this.finishAttempt(run, attempt, failure, null, attempt.heartbeatDetails);
+    await this.runUntilIdle(false);
+  }
+  takeAsync(token) {
+    const attempt = this.asyncAttempts.get(token);
+    if (!attempt) throw new Error(`Unknown or used activity task token ${token}`);
+    this.asyncAttempts.delete(token);
+    return attempt;
+  }
+  /** Record an attempt's outcome: completion, a final failure or timeout, or the next attempt. */
+  finishAttempt(run, attempt, failure, result, heartbeatDetails) {
+    const open = run.state.activities[attempt.activityId];
+    if (run.state.status !== "RUNNING" || !open || !isActivityOpen(open)) return;
     const started = () => {
       this.append(run, {
         type: "ACTIVITY_STARTED",
@@ -1131,18 +1671,37 @@ var TestWorkflowEnvironment = class _TestWorkflowEnvironment {
     if (decision.delayMs > 0) config.firstTaskDelayMs = decision.delayMs;
     this.startSuccessor(run, run.state.input ?? null, config);
   }
-  onClosed(run) {
+  /**
+   * A run closed: drop its pending work, retry it, apply the parent-close
+   * policy to its children (except `keptChildren`, which follow a reset
+   * fork), settle its open updates and notify its parent.
+   */
+  onClosed(run, keptChildren = /* @__PURE__ */ new Set()) {
     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);
+    for (const [token, entry] of this.asyncAttempts)
+      if (entry.runId === run.runId) this.asyncAttempts.delete(token);
     this.retryRun(run);
     for (const [childId2, childRunId] of run.children) {
+      if (keptChildren.has(childId2)) continue;
       const child = run.state.children[childId2];
       if (!child || !isChildOpen(child) || childRunId === void 0) continue;
       if (child.parentClosePolicy === "TERMINATE") this.terminate(childRunId, "parent closed");
       else if (child.parentClosePolicy === "REQUEST_CANCEL")
         this.requestCancel(childRunId, "parent closed");
     }
+    for (const update of run.updates.values()) {
+      if (update.status !== "PENDING" && update.status !== "ACCEPTED" && update.status !== "ADMITTED")
+        continue;
+      const accepted = update.status === "ACCEPTED";
+      update.status = accepted ? "COMPLETED" : "REJECTED";
+      update.failure = {
+        errorType: accepted ? "PERMANENT" : "VALIDATION",
+        type: "RunClosed",
+        message: `The run closed before update "${update.name}" ${accepted ? "completed" : "was accepted"}`
+      };
+    }
     if (!run.parent) return;
     const parent = this.runs.get(run.parent.runId);
     if (!parent || parent.state.status !== "RUNNING") return;
@@ -1150,6 +1709,10 @@ var TestWorkflowEnvironment = class _TestWorkflowEnvironment {
     if (!parent.state.children[childId] || !isChildOpen(parent.state.children[childId])) return;
     const last = run.history[run.history.length - 1];
     if (!last) return;
+    if (run.resetTo !== void 0) {
+      parent.children.set(childId, run.resetTo);
+      return;
+    }
     if (run.continuedTo !== void 0) {
       const next = this.runs.get(run.continuedTo);
       if (next) {
@@ -1200,7 +1763,8 @@ var TestWorkflowEnvironment = class _TestWorkflowEnvironment {
   async resultOf(runId) {
     await this.runUntilIdle(this.timeSkipping);
     let run = this.run(runId);
-    while (run.continuedTo !== void 0) run = this.run(run.continuedTo);
+    while (run.continuedTo !== void 0 || run.resetTo !== void 0)
+      run = this.run(run.continuedTo ?? run.resetTo ?? run.runId);
     if (run.taskFailure) throw new WorkflowTaskFailedError(run.runId, run.taskFailure);
     if (this.failOnUnfinishedHandlers && run.unfinishedHandlers !== void 0)
       throw new UnfinishedHandlersError(run.runId, run.unfinishedHandlers);
@@ -1472,4 +2036,4 @@ async function runWorkflowTaskInVm(script, request, options = {}) {
   }
 }
 
-export { HistoryAssertionError, ReplayError, RunBlockedError, TestRunHandle, TestWorkflowEnvironment, UnfinishedHandlersError, WorkflowAlreadyStartedError, WorkflowFailedError, WorkflowTaskFailedError, assertHistory, bundleToScript, drainJobs, expectIR, jsonCopy, registryOf, replay, replayRequest, runWorkflowTaskInProcess, runWorkflowTaskInVm, simulate };
+export { HistoryAssertionError, QueryFailedError, QueryRejectedError, ReplayError, RunBlockedError, TestRunHandle, TestWorkflowEnvironment, UnfinishedHandlersError, UpdateRefusedError, WorkflowAlreadyStartedError, WorkflowFailedError, WorkflowTaskFailedError, assertHistory, bundleToScript, drainJobs, expectIR, jsonCopy, registryOf, replay, replayRequest, runWorkflowTaskInProcess, runWorkflowTaskInVm, simulate };