@fluidgrids/workflows 2026.1028.2 → 2026.1030.1

package/dist/testing/index.d.cts

@@ -1,12 +1,13 @@
-import { h as DurableWorkflow, O as Operation, j as Duration, l as SignalDefinition } from '../workflow-J-yYixny.cjs';
-import { i as HistoryFile, m as RunState } from '../file-BOoHZgoQ.cjs';
-import { a6 as WorkflowInfoSnapshot, a7 as WorkflowTaskRequest, a8 as WorkflowTaskResult, U as RunEventRecord, F as Failure, V as RunEventType } from '../types-CpBBjaGX.cjs';
-import { a as Json, b as WorkflowDefinition, m as WorkflowNode } from '../types-BGoPzgcl.cjs';
-import { x as Tier1Workflow } from '../workflow-FXUkpIBc.cjs';
+import { x as Duration, X as WorkflowRetryOptions, v as DurableWorkflow, h as ActivityImplementation, i as ActivityInboundInterceptor, e as ActivityDefinition, c as ActivityContext, O as Operation, U as UpdateDefinition, Q as QueryDefinition, G as SignalDefinition } from '../workflow-DS32Gtws.cjs';
+import { k as WorkflowInterceptorsFactory, M as MarkedInterceptorsFactory } from '../interceptors-CqkNZVfI.cjs';
+import { C as CommandGate, p as HistoryFile, x as RunState } from '../file-BxYpwjRQ.cjs';
+import { b as WorkflowInfoSnapshot, ay as WorkflowIdReusePolicy, ax as WorkflowIdConflictPolicy, at as VersioningBehavior, M as Headers, az as WorkflowTaskRequest, aA as WorkflowTaskResult, F as Failure, aj as SinkCall, R as RunEventRecord, U as UnfinishedHandler, ac as RunEventType } from '../types-Bv2i4cBX.cjs';
+import { a as Json, J as JsonObject, W as WorkflowDefinition, m as WorkflowNode } from '../types-V7jEEUaL.cjs';
+import { x as Tier1Workflow } from '../workflow-BJPFv3cp.cjs';
 import { E as EsbuildApi } from '../lower-types-DQNBfWQn.cjs';
 import { WorkflowRegistry } from '../runtime/index.cjs';
 import 'esbuild';
-import '../activation-BBh1p82z.cjs';
+import '../activation-DqUfpHzk.cjs';
 
 /**
  * `TestWorkflowEnvironment` (spec 10 §1): an in-process engine for tier-2
@@ -18,24 +19,50 @@ import '../activation-BBh1p82z.cjs';
  * the conformance fixtures are recorded with it and then replayed in QuickJS
  * and in `vm`.
  *
+ * R2 adds local activities (run through `mock`, retried inside the task),
+ * start delay, run and execution timeouts and run-level retry on the fake
+ * clock, workflow-id policies and workflow-id targets, held activity queues
+ * for schedule-to-start timeouts, heartbeat details on retry, and the handler
+ * drain check (`failOnUnfinishedHandlers`, default true).
+ *
+ * C-R1 (Phase C) adds updates (`update`, update-with-start), custom queries
+ * (`query`), reset (`reset`, a forked run with signals and updates
+ * re-applied), user activities (`registerActivity`, `mockActivity`, async
+ * completion), search attributes and headers at the start, workflow
+ * interceptors, activity interceptors and sinks.
+ *
  * Divergences from the service (documented, accepted for Phase B):
  * - Workflow tasks run in this process without the determinism shims.
  * - A failed workflow task is not retried forever: the run stops, and
  *   `result()` rejects with {@link WorkflowTaskFailedError}.
  * - Every task is a first attempt (no transient attempts), and activity
  *   start-to-close and heartbeat timeouts are not timed; a mock may throw a
- *   `TimeoutFailure` to simulate one. Schedule-to-close is honoured.
+ *   `TimeoutFailure` to simulate one. Schedule-to-close is honoured, and
+ *   schedule-to-start while a node type is held (`holdActivities`).
+ * - Local-activity retries do not wait for their backoff: the task's clock
+ *   is its start time, as in the worker, and the fake clock does not move.
+ * - The workflow-task timeout is recorded, not enforced.
  * - Graph child runs are mocks (`mockChild`).
+ * - Task queues are not checked: a user activity runs on any queue (the
+ *   service refuses one on `managed`), and paused activities, pause rules
+ *   and activity options updates are service operations without a test form.
  */
 
 /** What a mock receives besides the activity's args. */
 interface ActivityMockInfo {
     runId: string;
+    /** `a<n>` for an activity, `l<n>` for a local activity. */
     activityId: string;
     attempt: number;
     nodeType: string;
     operation: string;
     connection?: string;
+    /** True when the call is a local activity (`ctx.localActivity`). */
+    local?: boolean;
+    /** Details the previous attempt recorded with `heartbeat` (11 §2.4); activities only. */
+    heartbeatDetails?: Json;
+    /** Record heartbeat details for the next attempt (activities only). */
+    heartbeat?: (details?: unknown) => void;
 }
 type ActivityMock = (args: Json, info: ActivityMockInfo) => unknown;
 type ChildMock = (input: Json, info: {
@@ -49,8 +76,21 @@ interface TestEnvironmentOptions {
     startTime?: number | string | Date;
     /** Tier-2 functions by export name, for `ctx.child(fn)` and by-name starts. */
     workflows?: Readonly<Record<string, DurableWorkflow<never, unknown>>>;
-    /** Command set the environment accepts; default `parity`. */
-    enabled?: 'core' | 'parity';
+    /** Command set the environment accepts: a feature set or a release level; default `parity`. */
+    enabled?: CommandGate;
+    /**
+     * Turn the drain warning (a workflow that finishes while a signal handler
+     * with policy `WARN_AND_ABANDON` still runs, 11 §2.18) into a failure of
+     * `result()` (`UnfinishedHandlersError`). Default true.
+     */
+    failOnUnfinishedHandlers?: boolean;
+    /**
+     * The runtime release whose history fields the environment writes (default
+     * {@link RUNTIME_RELEASE}). Release 1 omits the R2 start fields that the
+     * Phase B core service never wrote (`lastCompletionResult` on a
+     * continue-as-new), so R1 conformance histories record unchanged.
+     */
+    historyRelease?: number;
     /** Workspace id written into run info. */
     workspaceId?: string;
     /**
@@ -61,6 +101,61 @@ interface TestEnvironmentOptions {
     taskExecutor?: (request: WorkflowTaskRequest) => Promise<WorkflowTaskResult> | WorkflowTaskResult;
     /** Workflow keys of tier-2 functions (key -> export name), for `ctx.child('<key>')` with a task executor. */
     workflowKeys?: Readonly<Record<string, string>>;
+    /** Workflow interceptors, as a bundle would export them as `interceptors` (in-process tasks only). */
+    interceptors?: WorkflowInterceptorsFactory | MarkedInterceptorsFactory;
+    /** User-activity implementations (`implementActivity`, `defineActivity`, `dynamicActivity`). */
+    activities?: ReadonlyArray<ActivityImplementation<never, unknown>>;
+    /** Activity inbound interceptors around every user activity, first outermost. */
+    activityInterceptors?: readonly ActivityInboundInterceptor[];
+    /** Connections `ActivityContext.connection(name)` returns. */
+    connections?: Readonly<Record<string, Record<string, Json>>>;
+    /** Sink implementations called with each task's sink calls after the task completes. */
+    sinks?: Readonly<Record<string, Readonly<Record<string, (...args: Json[]) => void>>>>;
+}
+/** The state of an update (Phase C, 05 §6). */
+type UpdateStatus = 'PENDING' | 'ACCEPTED' | 'REJECTED' | 'COMPLETED';
+/** What `update` returns (`UpdateResult` of `updateWorkflowRun`). */
+interface UpdateResult {
+    updateId: string;
+    status: UpdateStatus;
+    result?: Json;
+    failure?: Failure;
+}
+/** Options of `update`. */
+interface UpdateOptions {
+    /** Idempotency: a repeat with the same id returns the first result. Default `u<n>`. */
+    updateId?: string;
+    /** `COMPLETED` (default) runs until idle, `ACCEPTED` returns once the update is accepted. */
+    waitFor?: 'ACCEPTED' | 'COMPLETED';
+    headers?: Headers;
+}
+/** Options of `reset` (11 §2.7). */
+interface ResetOptions {
+    /** The last `WORKFLOW_TASK_COMPLETED` at or before this seq is the reset point. */
+    toSeq?: number;
+    /** `FIRST_TASK` or `LAST_TASK` (default) instead of a seq. */
+    to?: 'FIRST_TASK' | 'LAST_TASK';
+    reason?: string;
+    /** Re-append signals received after the reset point (default true). */
+    reapplySignals?: boolean;
+    /** Re-append updates accepted after the reset point as `UPDATE_ADMITTED` (default true). */
+    reapplyUpdates?: boolean;
+}
+/** A query found no handler (`rejected`, `VALIDATION`). */
+declare class QueryRejectedError extends Error {
+    readonly runId: string;
+    readonly queryName: string;
+    constructor(runId: string, queryName: string, message: string);
+}
+/** A query handler threw, or the replay failed. */
+declare class QueryFailedError extends Error {
+    readonly runId: string;
+    readonly queryName: string;
+    constructor(runId: string, queryName: string, message: string);
+}
+/** An update to a run that is not open, or an update-with-start on a delayed start. */
+declare class UpdateRefusedError extends Error {
+    constructor(message: string);
 }
 interface StartOptions {
     input?: unknown;
@@ -71,6 +166,57 @@ interface StartOptions {
         payload?: unknown;
     }>;
     info?: Partial<WorkflowInfoSnapshot>;
+    /** The workflow key for workflow-id policies and targets; default the declaration's name. */
+    workflowKey?: string;
+    /** The business id (11 §2.1); unique among the open runs of the workflow key. */
+    workflowId?: string;
+    /** Default `ALLOW_DUPLICATE`. */
+    idReusePolicy?: WorkflowIdReusePolicy;
+    /** Default `FAIL`. */
+    idConflictPolicy?: WorkflowIdConflictPolicy;
+    /** Delay the first workflow task (11 §2.23); a signal ends the delay. */
+    startDelay?: Duration;
+    /** Bounds the whole chain; default the declaration's `executionTimeout`. */
+    executionTimeout?: Duration;
+    /** Bounds one run; default the declaration's `runTimeout`. */
+    runTimeout?: Duration;
+    /** Recorded only; default the declaration's `workflowTaskTimeout`. */
+    workflowTaskTimeout?: Duration;
+    /** Run-level retry; default the declaration's `retry`. */
+    retry?: WorkflowRetryOptions;
+    summary?: string;
+    details?: string;
+    /** The run's memo (`ctx.info.context`). */
+    memo?: JsonObject;
+    /** Default the declaration's `versioningBehavior`. */
+    versioningBehavior?: VersioningBehavior;
+    /** Headers of the start (`WORKFLOW_STARTED.headers`, interceptors). */
+    headers?: Headers;
+    /** Search attributes at the start (Phase C). */
+    searchAttributes?: JsonObject;
+    /** Fairness of the run's tasks (Phase C). */
+    fairnessKey?: string;
+    fairnessWeight?: number;
+    /** Update-with-start (11 §2.6): admitted right after `WORKFLOW_STARTED`. */
+    update?: {
+        name: string;
+        args?: unknown;
+        updateId?: string;
+        headers?: Headers;
+    };
+}
+/** A start found an open run with the same workflow id (`idConflictPolicy: FAIL`) or a refused closed one. */
+declare class WorkflowAlreadyStartedError extends Error {
+    readonly workflowKey: string;
+    readonly workflowId: string;
+    readonly existingRunId: string;
+    constructor(workflowKey: string, workflowId: string, existingRunId: string);
+}
+/** The workflow finished while signal handlers still ran (`failOnUnfinishedHandlers`). */
+declare class UnfinishedHandlersError extends Error {
+    readonly runId: string;
+    readonly handlers: UnfinishedHandler[];
+    constructor(runId: string, handlers: UnfinishedHandler[]);
 }
 /** A run's workflow failed (`WORKFLOW_FAILED`). */
 declare class WorkflowFailedError extends Error {
@@ -104,6 +250,14 @@ declare class TestRunHandle<Out = Json> {
     cancel(reason?: string): Promise<void>;
     /** Terminate the run without running code. */
     terminate(reason?: string): Promise<void>;
+    /** Send an update and run until idle (Phase C). */
+    update<Args, Result>(update: UpdateDefinition<Args, Result> | string, args?: Args, options?: UpdateOptions): Promise<UpdateResult>;
+    /** Answer a query from the run's history (Phase C custom queries and the built-ins). */
+    query<Result, Args>(query: QueryDefinition<Result, Args> | string, args?: Args): Promise<Result>;
+    /** Reset the run (11 §2.7): a new run forked at a completed task; this one is terminated. */
+    reset(options?: ResetOptions): Promise<TestRunHandle<Out>>;
+    /** Sink calls the run's tasks made (Phase C). */
+    sinkCalls(): SinkCall[];
     /** Run until this run (or the last run of its continue-as-new chain) ends; its output. */
     result(): Promise<Out>;
     /** The projected state of the run. */
@@ -114,6 +268,12 @@ declare class TestWorkflowEnvironment {
     private clock;
     private readonly timeSkipping;
     private readonly enabled;
+    /** The bundle features the gate's flags enable, sent with every task (`request.features`). */
+    private readonly codeFeatures;
+    private readonly failOnUnfinishedHandlers;
+    private readonly historyRelease;
+    private dues;
+    private readonly held;
     private readonly workspaceId;
     private readonly runs;
     private readonly runOrder;
@@ -125,19 +285,89 @@ declare class TestWorkflowEnvironment {
     private timers;
     private mockedChildren;
     private runCounter;
+    private updateCounter;
     private readonly executor;
     private readonly workflowKeys;
+    private readonly interceptors;
+    private readonly activityImpls;
+    private readonly activityInterceptors;
+    private readonly connections;
+    private readonly sinks;
+    /** Attempts that handed their completion to an outside system (`completeAsync`), by token. */
+    private readonly asyncAttempts;
     private constructor();
+    /** Register a user-activity implementation (Phase C). A later one replaces an earlier of the same name. */
+    registerActivity(implementation: ActivityImplementation<never, unknown>): void;
+    /** Mock a user activity by name or declaration (Phase C). */
+    mockActivity<In, Out>(activity: ActivityDefinition<In, Out> | string, fn: (args: In, ctx: ActivityContext) => Out | Promise<Out>): void;
     /** Create an environment. */
     static create(options?: TestEnvironmentOptions): Promise<TestWorkflowEnvironment>;
     /** The fake clock, in epoch milliseconds. */
     now(): number;
     /** Mock a node operation (by node type, and operation when given). */
     mock<In, Out>(operation: Operation<In, Out> | string, impl: (args: In, info: ActivityMockInfo) => Out | Promise<Out>, operationName?: string): void;
+    /**
+     * 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?: string): void;
+    /** Release held activity queues (all when no node type is given). */
+    releaseActivities(nodeType?: string): void;
+    /** The hold key of an attempt: its node type, or the task queue of a user activity. */
+    private holdKeyOf;
+    private isHeld;
     /** Mock a child workflow started by key (graph or durable). */
     mockChild(workflowKey: string, impl: ChildMock): void;
     /** Start a run of a tier-2 function (by declaration, or by export name with a task executor). */
     start<In, Out>(definition: DurableWorkflow<In, Out> | string, options?: StartOptions): Promise<TestRunHandle<Out>>;
+    /**
+     * 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.
+     */
+    startWithUpdate<In, Out>(definition: DurableWorkflow<In, Out> | string, options: StartOptions & {
+        update: NonNullable<StartOptions['update']>;
+    }): Promise<{
+        handle: TestRunHandle<Out>;
+        update: UpdateResult;
+    }>;
+    private nextUpdateId;
+    /** A new update row (not attached to a run yet). */
+    private newUpdate;
+    /** Record an update on a run: pending (delivered by the next task) or admitted into history. */
+    private addUpdate;
+    /** Schedule a workflow task for a run that has none (an update needs no input event). */
+    private scheduleTask;
+    /**
+     * 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`).
+     */
+    update<Args, Result>(runId: string, update: UpdateDefinition<Args, Result> | string, args?: Args, options?: UpdateOptions): Promise<UpdateResult>;
+    /** The current result of an update. */
+    updateResultOf(runId: string, updateId: string): UpdateResult;
+    /** Answer a query from the run's history (a replay-only `query` task). */
+    query(runId: string, query: QueryDefinition<unknown, unknown> | string, args?: unknown): Promise<Json>;
+    /** Sink calls the run's tasks made. */
+    sinkCallsOf(runId: string): SinkCall[];
+    /**
+     * 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.
+     */
+    reset(runId: string, options?: ResetOptions): Promise<string>;
+    private durationConfig;
+    /**
+     * 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}.
+     */
+    private useExisting;
     /** Advance the clock by `duration`, firing timers and running work as it comes due. */
     sleep(duration: Duration): Promise<void>;
     /** Every run, in start order. */
@@ -150,20 +380,68 @@ declare class TestWorkflowEnvironment {
     private ensureRegistered;
     private run;
     private createRun;
+    /** The R2 fields of `WORKFLOW_STARTED`, each written only when it is set. */
+    private startedFields;
     private append;
-    deliverSignal(runId: string, name: string, payload: unknown): boolean;
+    /** End a start delay: the first workflow task is scheduled now. */
+    private endDelay;
+    deliverSignal(runId: string, name: string, payload: unknown, headers?: Headers): boolean;
     requestCancel(runId: string, reason?: string): boolean;
     terminate(runId: string, reason: string): void;
     /** Run every runnable task and activity; skip time when allowed and idle. */
     runUntilIdle(skipTime: boolean): Promise<void>;
+    /** When a held attempt's schedule-to-start timeout expires, if it has one. */
+    private heldDeadline;
     private nextDue;
+    /** Expire held attempts whose schedule-to-start timeout passed (not retried, 11 §2.3). */
+    private expireHeld;
+    /** Fire run-level deadlines: the end of a start delay, run and execution timeouts. */
+    private fireRunDues;
     private fireDue;
     private runTask;
+    /** What a task's update replies mean for the run's update rows. */
+    private recordUpdateReplies;
+    /** Keep a task's sink calls and call the configured sinks with them. */
+    private runSinks;
+    private execute;
+    /**
+     * 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.
+     */
+    private executeWithLocalActivities;
+    private runLocalActivity;
     private afterCommand;
+    /** What a successor of a run inherits (continue-as-new, run retry). */
+    private chainConfig;
+    /** Start the next run of a chain; the closed run's parent and handles follow it. */
+    private startSuccessor;
     private resolveTarget;
+    /** The open run of a workflow id, else its latest run (11 §2.1). */
+    private resolveWorkflowId;
     private startChild;
     private runMockedChild;
     private runAttempt;
+    /** The `ActivityContext` of one user-activity attempt. */
+    private activityContext;
+    /** Complete an activity that called `completeAsync()` (`completeActivityAsync`). */
+    completeActivityAsync(token: string, result?: unknown): Promise<void>;
+    /** Fail an activity that called `completeAsync()` (`failActivityAsync`); the retry policy applies. */
+    failActivityAsync(token: string, error: unknown): Promise<void>;
+    private takeAsync;
+    /** Record an attempt's outcome: completion, a final failure or timeout, or the next attempt. */
+    private finishAttempt;
+    /**
+     * 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`.
+     */
+    private retryRun;
+    /**
+     * 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.
+     */
     private onClosed;
     resultOf(runId: string): Promise<Json>;
     /** Every tier-2 function registered, by export name. */
@@ -297,9 +575,12 @@ declare function runWorkflowTaskInVm(script: string, request: WorkflowTaskReques
 
 /** Let every queued promise job run. */
 declare function drainJobs(): Promise<void>;
-/** A registry from export names to workflow functions. */
-declare function registryOf(workflows: Readonly<Record<string, DurableWorkflow<never, unknown>>>): WorkflowRegistry;
+/**
+ * A registry from export names to workflow functions, with the workflow
+ * interceptors a bundle would export as `interceptors`.
+ */
+declare function registryOf(workflows: Readonly<Record<string, DurableWorkflow<never, unknown>>>, interceptors?: WorkflowInterceptorsFactory | MarkedInterceptorsFactory): WorkflowRegistry;
 /** Run one workflow task in process. */
 declare function runWorkflowTaskInProcess(registry: WorkflowRegistry, request: WorkflowTaskRequest): Promise<WorkflowTaskResult>;
 
-export { type ActivityMock, type ActivityMockInfo, type ChildMock, type ExpectedEvent, HistoryAssertionError, type IRSnapshot, type NodeMock, type NodeMockResult, ReplayError, type ReplayInput, RunBlockedError, type SimulateOptions, type SimulatedStep, type SimulationResult, type StartOptions, type TestEnvironmentOptions, TestRunHandle, TestWorkflowEnvironment, WorkflowFailedError, WorkflowTaskFailedError, assertHistory, bundleToScript, drainJobs, expectIR, jsonCopy, registryOf, replay, replayRequest, runWorkflowTaskInProcess, runWorkflowTaskInVm, simulate };
+export { type ActivityMock, type ActivityMockInfo, type ChildMock, type ExpectedEvent, HistoryAssertionError, type IRSnapshot, type NodeMock, type NodeMockResult, QueryFailedError, QueryRejectedError, ReplayError, type ReplayInput, type ResetOptions, RunBlockedError, type SimulateOptions, type SimulatedStep, type SimulationResult, type StartOptions, type TestEnvironmentOptions, TestRunHandle, TestWorkflowEnvironment, UnfinishedHandlersError, type UpdateOptions, UpdateRefusedError, type UpdateResult, type UpdateStatus, WorkflowAlreadyStartedError, WorkflowFailedError, WorkflowTaskFailedError, assertHistory, bundleToScript, drainJobs, expectIR, jsonCopy, registryOf, replay, replayRequest, runWorkflowTaskInProcess, runWorkflowTaskInVm, simulate };