@fluidgrids/workflows 2026.1027.1 → 2026.1028.2

package/dist/testing/index.d.cts

@@ -0,0 +1,305 @@
+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 { E as EsbuildApi } from '../lower-types-DQNBfWQn.cjs';
+import { WorkflowRegistry } from '../runtime/index.cjs';
+import 'esbuild';
+import '../activation-BBh1p82z.cjs';
+
+/**
+ * `TestWorkflowEnvironment` (spec 10 §1): an in-process engine for tier-2
+ * workflows. It keeps histories in memory, runs workflow tasks through the
+ * real runtime ABI, appends exactly the events `history/apply.ts` prescribes,
+ * runs activities against mocks with the shared retry policy, fires timers on
+ * a fake clock, and runs child workflows, signals, cancellation and the
+ * parent-close policy. The histories it records are valid service histories:
+ * the conformance fixtures are recorded with it and then replayed in QuickJS
+ * and in `vm`.
+ *
+ * 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.
+ * - Graph child runs are mocks (`mockChild`).
+ */
+
+/** What a mock receives besides the activity's args. */
+interface ActivityMockInfo {
+    runId: string;
+    activityId: string;
+    attempt: number;
+    nodeType: string;
+    operation: string;
+    connection?: string;
+}
+type ActivityMock = (args: Json, info: ActivityMockInfo) => unknown;
+type ChildMock = (input: Json, info: {
+    runId: string;
+    childId: string;
+}) => unknown;
+interface TestEnvironmentOptions {
+    /** Advance the clock to the next timer whenever every run is idle (default true). */
+    timeSkipping?: boolean;
+    /** Start of the fake clock. Default 2026-01-01T00:00:00.000Z. */
+    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';
+    /** Workspace id written into run info. */
+    workspaceId?: string;
+    /**
+     * Run workflow tasks somewhere else than in this process, for example in
+     * an isolate over a built bundle (`runWorkflowTaskInVm`, the QuickJS
+     * runner). Start runs by export name then.
+     */
+    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>>;
+}
+interface StartOptions {
+    input?: unknown;
+    runId?: string;
+    /** Signals delivered right after the start (signal-with-start). */
+    signals?: Array<{
+        name: string;
+        payload?: unknown;
+    }>;
+    info?: Partial<WorkflowInfoSnapshot>;
+}
+/** A run's workflow failed (`WORKFLOW_FAILED`). */
+declare class WorkflowFailedError extends Error {
+    readonly runId: string;
+    readonly failure: Failure;
+    constructor(runId: string, failure: Failure);
+}
+/** A workflow task failed; the test environment stops the run instead of retrying forever. */
+declare class WorkflowTaskFailedError extends Error {
+    readonly runId: string;
+    readonly result: WorkflowTaskResult;
+    constructor(runId: string, result: WorkflowTaskResult);
+}
+/** The run is still open and nothing more can happen without outside input. */
+declare class RunBlockedError extends Error {
+    readonly runId: string;
+    constructor(runId: string);
+}
+/** A handle to a run of the test environment. */
+declare class TestRunHandle<Out = Json> {
+    private readonly env;
+    readonly runId: string;
+    constructor(env: TestWorkflowEnvironment, runId: string);
+    /** The run's history so far. */
+    history(): RunEventRecord[];
+    /** The history as a history file. */
+    historyFile(extra?: Partial<Omit<HistoryFile, 'format' | 'formatVersion' | 'workflowFn' | 'events'>>): HistoryFile;
+    /** Deliver a signal and run until idle (without skipping time). */
+    signal<P>(signal: SignalDefinition<P> | string, payload?: P): Promise<void>;
+    /** Request cancellation and run until idle (without skipping time). */
+    cancel(reason?: string): Promise<void>;
+    /** Terminate the run without running code. */
+    terminate(reason?: string): Promise<void>;
+    /** 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. */
+    state(): RunState;
+}
+/** The in-process test engine. */
+declare class TestWorkflowEnvironment {
+    private clock;
+    private readonly timeSkipping;
+    private readonly enabled;
+    private readonly workspaceId;
+    private readonly runs;
+    private readonly runOrder;
+    private readonly mocks;
+    private readonly childMocks;
+    private readonly workflows;
+    private registry;
+    private attempts;
+    private timers;
+    private mockedChildren;
+    private runCounter;
+    private readonly executor;
+    private readonly workflowKeys;
+    private constructor();
+    /** 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;
+    /** 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>>;
+    /** Advance the clock by `duration`, firing timers and running work as it comes due. */
+    sleep(duration: Duration): Promise<void>;
+    /** Every run, in start order. */
+    runIds(): string[];
+    historyOf(runId: string): RunEventRecord[];
+    historyFileOf(runId: string, extra?: Partial<Omit<HistoryFile, 'format' | 'formatVersion' | 'workflowFn' | 'events'>>): HistoryFile;
+    /** The failed workflow task that stopped a run, if one did. */
+    taskFailureOf(runId: string): WorkflowTaskResult | undefined;
+    stateOf(runId: string): RunState;
+    private ensureRegistered;
+    private run;
+    private createRun;
+    private append;
+    deliverSignal(runId: string, name: string, payload: unknown): 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>;
+    private nextDue;
+    private fireDue;
+    private runTask;
+    private afterCommand;
+    private resolveTarget;
+    private startChild;
+    private runMockedChild;
+    private runAttempt;
+    private onClosed;
+    resultOf(runId: string): Promise<Json>;
+    /** Every tier-2 function registered, by export name. */
+    registered(): Readonly<Record<string, DurableWorkflow<never, unknown>>>;
+}
+
+/** A history to replay: a history file, its text, or the events. */
+type ReplayInput = HistoryFile | string | RunEventRecord[];
+/** A replay that did not pass. */
+declare class ReplayError extends Error {
+    readonly result: WorkflowTaskResult;
+    constructor(result: WorkflowTaskResult);
+}
+/** The task request that replays `history` (kind `verify`). */
+declare function replayRequest(workflowFn: string, history: RunEventRecord[], info?: Partial<WorkflowInfoSnapshot>, nowMs?: number): WorkflowTaskRequest;
+/**
+ * Replay a history against tier-2 functions in process. `workflows` is one
+ * function or a map by export name. Returns the task result; throws
+ * `DeterminismViolation` on a mismatch and {@link ReplayError} on any other
+ * task failure.
+ */
+declare function replay(workflows: DurableWorkflow<never, unknown> | Readonly<Record<string, DurableWorkflow<never, unknown>>>, input: ReplayInput, options?: {
+    workflowFn?: string;
+    info?: Partial<WorkflowInfoSnapshot>;
+    nowMs?: number;
+}): Promise<WorkflowTaskResult>;
+
+/** One expected event: its type and, optionally, a subset of its payload. */
+interface ExpectedEvent {
+    type: RunEventType;
+    payload?: Record<string, unknown>;
+}
+/** An assertion that did not hold. */
+declare class HistoryAssertionError extends Error {
+    constructor(message: string);
+}
+/**
+ * Assert that `expected` appears in `history` in order (other events may be
+ * in between, unless `exact`). Payloads match when they contain the expected
+ * fields.
+ */
+declare function assertHistory(history: readonly RunEventRecord[] | {
+    history(): RunEventRecord[];
+}, expected: readonly ExpectedEvent[], options?: {
+    exact?: boolean;
+    ignore?: readonly RunEventType[];
+}): void;
+/** The IR of a tier-1 workflow or a definition, normalised, with its `irHash`. */
+interface IRSnapshot {
+    definition: WorkflowDefinition;
+    irHash: string;
+    /** Throws unless `other` has the same `irHash`. */
+    toEqualIR(other: Tier1Workflow | WorkflowDefinition): void;
+}
+/** Snapshot helper for tier-1 workflows: `expect(expectIR(wf).definition).toMatchSnapshot()`. */
+declare function expectIR(value: Tier1Workflow | WorkflowDefinition): IRSnapshot;
+/** A JSON copy, for comparing results across engines. */
+declare function jsonCopy(value: unknown): Json;
+
+/**
+ * `simulate(ir, { trigger, mocks })`: walk a tier-1 graph without a cluster
+ * (spec 10 §1, reduced form accepted for Phase B, PLAN-B §9.1 item 5).
+ *
+ * It starts at the trigger node(s), passes each node's output to the nodes its
+ * edges lead to, and calls a mock for every node (by node id first, then by
+ * node type). Documented divergences from the engine:
+ * - No expressions are evaluated and no node runs for real: a node without a
+ *   mock passes its input through.
+ * - Routing nodes follow the handle a mock returns (`{ handle: 'true' }`);
+ *   without one, every outgoing edge is followed. Loops run their body once.
+ * - `internal:code-workflow` nodes run the tier-2 function in a
+ *   `TestWorkflowEnvironment` when it is registered in `workflows`, else they
+ *   need a mock.
+ * - Error policies, retries, waits and merges are not modelled; a node is
+ *   visited at most `maxVisits` times (default 1).
+ */
+
+/** What a node mock returns: an output, or an output and the handle to follow. */
+type NodeMockResult = Json | {
+    output: Json;
+    handle?: string;
+};
+type NodeMock = (input: Json, node: WorkflowNode) => NodeMockResult | Promise<NodeMockResult>;
+interface SimulateOptions {
+    /** The trigger output (the first node's output). */
+    trigger?: Json;
+    /** Mocks by node id or node type. */
+    mocks?: Readonly<Record<string, NodeMock>>;
+    /** Tier-2 functions by export name, for code-workflow nodes. */
+    workflows?: Readonly<Record<string, DurableWorkflow<never, unknown>>>;
+    /** Visits per node. Default 1. */
+    maxVisits?: number;
+}
+interface SimulatedStep {
+    nodeId: string;
+    type: string;
+    input: Json;
+    output: Json;
+    handle?: string;
+}
+interface SimulationResult {
+    steps: SimulatedStep[];
+    /** Output of every visited node by id (the last visit). */
+    outputs: Record<string, Json>;
+}
+/** Simulate a definition. */
+declare function simulate(definition: WorkflowDefinition, options?: SimulateOptions): Promise<SimulationResult>;
+
+/** Turn an ES module bundle into a script for `vm` (the exports land on `__fluidgridsBundle`). */
+declare function bundleToScript(bundle: string, esbuild?: EsbuildApi): Promise<string>;
+/**
+ * Run one task; `script` comes from {@link bundleToScript}. Node drains the
+ * context's promise jobs after every call (`microtaskMode: 'afterEvaluate'`);
+ * Bun has no such mode and runs them on the host queue, so the loop also
+ * yields to the host between calls. The result is the same on both.
+ */
+declare function runWorkflowTaskInVm(script: string, request: WorkflowTaskRequest, options?: {
+    timeoutMs?: number;
+}): Promise<WorkflowTaskResult>;
+
+/**
+ * Run a workflow task in this process through the same runtime ABI the
+ * isolate uses: `start`, `step` until `done` with the promise jobs drained in
+ * between, `complete`. The test environment and `replay()` use it.
+ *
+ * In-process execution does not install the determinism shims (`Date.now()`
+ * and `Math.random()` are the real ones here); replay a recorded history in
+ * the isolate (`createWorkflowTaskRunner`) or with `runWorkflowTaskInVm` for
+ * that check.
+ */
+
+/** 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;
+/** 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 };

package/dist/testing/index.d.ts

@@ -0,0 +1,305 @@
+import { h as DurableWorkflow, O as Operation, j as Duration, l as SignalDefinition } from '../workflow-C2a05WUJ.js';
+import { i as HistoryFile, m as RunState } from '../file-yuPCFU5b.js';
+import { a6 as WorkflowInfoSnapshot, a7 as WorkflowTaskRequest, a8 as WorkflowTaskResult, U as RunEventRecord, F as Failure, V as RunEventType } from '../types-DV-HX_Gt.js';
+import { a as Json, b as WorkflowDefinition, m as WorkflowNode } from '../types-BGoPzgcl.js';
+import { x as Tier1Workflow } from '../workflow-Bpr3vnA_.js';
+import { E as EsbuildApi } from '../lower-types-DQNBfWQn.js';
+import { WorkflowRegistry } from '../runtime/index.js';
+import 'esbuild';
+import '../activation-DnhG7SmF.js';
+
+/**
+ * `TestWorkflowEnvironment` (spec 10 §1): an in-process engine for tier-2
+ * workflows. It keeps histories in memory, runs workflow tasks through the
+ * real runtime ABI, appends exactly the events `history/apply.ts` prescribes,
+ * runs activities against mocks with the shared retry policy, fires timers on
+ * a fake clock, and runs child workflows, signals, cancellation and the
+ * parent-close policy. The histories it records are valid service histories:
+ * the conformance fixtures are recorded with it and then replayed in QuickJS
+ * and in `vm`.
+ *
+ * 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.
+ * - Graph child runs are mocks (`mockChild`).
+ */
+
+/** What a mock receives besides the activity's args. */
+interface ActivityMockInfo {
+    runId: string;
+    activityId: string;
+    attempt: number;
+    nodeType: string;
+    operation: string;
+    connection?: string;
+}
+type ActivityMock = (args: Json, info: ActivityMockInfo) => unknown;
+type ChildMock = (input: Json, info: {
+    runId: string;
+    childId: string;
+}) => unknown;
+interface TestEnvironmentOptions {
+    /** Advance the clock to the next timer whenever every run is idle (default true). */
+    timeSkipping?: boolean;
+    /** Start of the fake clock. Default 2026-01-01T00:00:00.000Z. */
+    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';
+    /** Workspace id written into run info. */
+    workspaceId?: string;
+    /**
+     * Run workflow tasks somewhere else than in this process, for example in
+     * an isolate over a built bundle (`runWorkflowTaskInVm`, the QuickJS
+     * runner). Start runs by export name then.
+     */
+    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>>;
+}
+interface StartOptions {
+    input?: unknown;
+    runId?: string;
+    /** Signals delivered right after the start (signal-with-start). */
+    signals?: Array<{
+        name: string;
+        payload?: unknown;
+    }>;
+    info?: Partial<WorkflowInfoSnapshot>;
+}
+/** A run's workflow failed (`WORKFLOW_FAILED`). */
+declare class WorkflowFailedError extends Error {
+    readonly runId: string;
+    readonly failure: Failure;
+    constructor(runId: string, failure: Failure);
+}
+/** A workflow task failed; the test environment stops the run instead of retrying forever. */
+declare class WorkflowTaskFailedError extends Error {
+    readonly runId: string;
+    readonly result: WorkflowTaskResult;
+    constructor(runId: string, result: WorkflowTaskResult);
+}
+/** The run is still open and nothing more can happen without outside input. */
+declare class RunBlockedError extends Error {
+    readonly runId: string;
+    constructor(runId: string);
+}
+/** A handle to a run of the test environment. */
+declare class TestRunHandle<Out = Json> {
+    private readonly env;
+    readonly runId: string;
+    constructor(env: TestWorkflowEnvironment, runId: string);
+    /** The run's history so far. */
+    history(): RunEventRecord[];
+    /** The history as a history file. */
+    historyFile(extra?: Partial<Omit<HistoryFile, 'format' | 'formatVersion' | 'workflowFn' | 'events'>>): HistoryFile;
+    /** Deliver a signal and run until idle (without skipping time). */
+    signal<P>(signal: SignalDefinition<P> | string, payload?: P): Promise<void>;
+    /** Request cancellation and run until idle (without skipping time). */
+    cancel(reason?: string): Promise<void>;
+    /** Terminate the run without running code. */
+    terminate(reason?: string): Promise<void>;
+    /** 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. */
+    state(): RunState;
+}
+/** The in-process test engine. */
+declare class TestWorkflowEnvironment {
+    private clock;
+    private readonly timeSkipping;
+    private readonly enabled;
+    private readonly workspaceId;
+    private readonly runs;
+    private readonly runOrder;
+    private readonly mocks;
+    private readonly childMocks;
+    private readonly workflows;
+    private registry;
+    private attempts;
+    private timers;
+    private mockedChildren;
+    private runCounter;
+    private readonly executor;
+    private readonly workflowKeys;
+    private constructor();
+    /** 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;
+    /** 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>>;
+    /** Advance the clock by `duration`, firing timers and running work as it comes due. */
+    sleep(duration: Duration): Promise<void>;
+    /** Every run, in start order. */
+    runIds(): string[];
+    historyOf(runId: string): RunEventRecord[];
+    historyFileOf(runId: string, extra?: Partial<Omit<HistoryFile, 'format' | 'formatVersion' | 'workflowFn' | 'events'>>): HistoryFile;
+    /** The failed workflow task that stopped a run, if one did. */
+    taskFailureOf(runId: string): WorkflowTaskResult | undefined;
+    stateOf(runId: string): RunState;
+    private ensureRegistered;
+    private run;
+    private createRun;
+    private append;
+    deliverSignal(runId: string, name: string, payload: unknown): 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>;
+    private nextDue;
+    private fireDue;
+    private runTask;
+    private afterCommand;
+    private resolveTarget;
+    private startChild;
+    private runMockedChild;
+    private runAttempt;
+    private onClosed;
+    resultOf(runId: string): Promise<Json>;
+    /** Every tier-2 function registered, by export name. */
+    registered(): Readonly<Record<string, DurableWorkflow<never, unknown>>>;
+}
+
+/** A history to replay: a history file, its text, or the events. */
+type ReplayInput = HistoryFile | string | RunEventRecord[];
+/** A replay that did not pass. */
+declare class ReplayError extends Error {
+    readonly result: WorkflowTaskResult;
+    constructor(result: WorkflowTaskResult);
+}
+/** The task request that replays `history` (kind `verify`). */
+declare function replayRequest(workflowFn: string, history: RunEventRecord[], info?: Partial<WorkflowInfoSnapshot>, nowMs?: number): WorkflowTaskRequest;
+/**
+ * Replay a history against tier-2 functions in process. `workflows` is one
+ * function or a map by export name. Returns the task result; throws
+ * `DeterminismViolation` on a mismatch and {@link ReplayError} on any other
+ * task failure.
+ */
+declare function replay(workflows: DurableWorkflow<never, unknown> | Readonly<Record<string, DurableWorkflow<never, unknown>>>, input: ReplayInput, options?: {
+    workflowFn?: string;
+    info?: Partial<WorkflowInfoSnapshot>;
+    nowMs?: number;
+}): Promise<WorkflowTaskResult>;
+
+/** One expected event: its type and, optionally, a subset of its payload. */
+interface ExpectedEvent {
+    type: RunEventType;
+    payload?: Record<string, unknown>;
+}
+/** An assertion that did not hold. */
+declare class HistoryAssertionError extends Error {
+    constructor(message: string);
+}
+/**
+ * Assert that `expected` appears in `history` in order (other events may be
+ * in between, unless `exact`). Payloads match when they contain the expected
+ * fields.
+ */
+declare function assertHistory(history: readonly RunEventRecord[] | {
+    history(): RunEventRecord[];
+}, expected: readonly ExpectedEvent[], options?: {
+    exact?: boolean;
+    ignore?: readonly RunEventType[];
+}): void;
+/** The IR of a tier-1 workflow or a definition, normalised, with its `irHash`. */
+interface IRSnapshot {
+    definition: WorkflowDefinition;
+    irHash: string;
+    /** Throws unless `other` has the same `irHash`. */
+    toEqualIR(other: Tier1Workflow | WorkflowDefinition): void;
+}
+/** Snapshot helper for tier-1 workflows: `expect(expectIR(wf).definition).toMatchSnapshot()`. */
+declare function expectIR(value: Tier1Workflow | WorkflowDefinition): IRSnapshot;
+/** A JSON copy, for comparing results across engines. */
+declare function jsonCopy(value: unknown): Json;
+
+/**
+ * `simulate(ir, { trigger, mocks })`: walk a tier-1 graph without a cluster
+ * (spec 10 §1, reduced form accepted for Phase B, PLAN-B §9.1 item 5).
+ *
+ * It starts at the trigger node(s), passes each node's output to the nodes its
+ * edges lead to, and calls a mock for every node (by node id first, then by
+ * node type). Documented divergences from the engine:
+ * - No expressions are evaluated and no node runs for real: a node without a
+ *   mock passes its input through.
+ * - Routing nodes follow the handle a mock returns (`{ handle: 'true' }`);
+ *   without one, every outgoing edge is followed. Loops run their body once.
+ * - `internal:code-workflow` nodes run the tier-2 function in a
+ *   `TestWorkflowEnvironment` when it is registered in `workflows`, else they
+ *   need a mock.
+ * - Error policies, retries, waits and merges are not modelled; a node is
+ *   visited at most `maxVisits` times (default 1).
+ */
+
+/** What a node mock returns: an output, or an output and the handle to follow. */
+type NodeMockResult = Json | {
+    output: Json;
+    handle?: string;
+};
+type NodeMock = (input: Json, node: WorkflowNode) => NodeMockResult | Promise<NodeMockResult>;
+interface SimulateOptions {
+    /** The trigger output (the first node's output). */
+    trigger?: Json;
+    /** Mocks by node id or node type. */
+    mocks?: Readonly<Record<string, NodeMock>>;
+    /** Tier-2 functions by export name, for code-workflow nodes. */
+    workflows?: Readonly<Record<string, DurableWorkflow<never, unknown>>>;
+    /** Visits per node. Default 1. */
+    maxVisits?: number;
+}
+interface SimulatedStep {
+    nodeId: string;
+    type: string;
+    input: Json;
+    output: Json;
+    handle?: string;
+}
+interface SimulationResult {
+    steps: SimulatedStep[];
+    /** Output of every visited node by id (the last visit). */
+    outputs: Record<string, Json>;
+}
+/** Simulate a definition. */
+declare function simulate(definition: WorkflowDefinition, options?: SimulateOptions): Promise<SimulationResult>;
+
+/** Turn an ES module bundle into a script for `vm` (the exports land on `__fluidgridsBundle`). */
+declare function bundleToScript(bundle: string, esbuild?: EsbuildApi): Promise<string>;
+/**
+ * Run one task; `script` comes from {@link bundleToScript}. Node drains the
+ * context's promise jobs after every call (`microtaskMode: 'afterEvaluate'`);
+ * Bun has no such mode and runs them on the host queue, so the loop also
+ * yields to the host between calls. The result is the same on both.
+ */
+declare function runWorkflowTaskInVm(script: string, request: WorkflowTaskRequest, options?: {
+    timeoutMs?: number;
+}): Promise<WorkflowTaskResult>;
+
+/**
+ * Run a workflow task in this process through the same runtime ABI the
+ * isolate uses: `start`, `step` until `done` with the promise jobs drained in
+ * between, `complete`. The test environment and `replay()` use it.
+ *
+ * In-process execution does not install the determinism shims (`Date.now()`
+ * and `Math.random()` are the real ones here); replay a recorded history in
+ * the isolate (`createWorkflowTaskRunner`) or with `runWorkflowTaskInVm` for
+ * that check.
+ */
+
+/** 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;
+/** 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 };