experimental-ash 0.22.2 → 0.23.0

package/dist/src/compiled/@workflow/core/private.d.ts

@@ -1,14 +1,63 @@
-export type Serializable = unknown;
-export type StepFunction<Args extends unknown[] = unknown[], Result = unknown> = ((
-  ...args: Args
-) => Promise<Result>) & {
-  maxRetries?: number | undefined;
-  stepId?: string | undefined;
+/**
+ * Utils used by the bundler when transforming code
+ */
+import type { CryptoKey } from './encryption.js';
+import type { EventsConsumer } from './events-consumer.js';
+import type { QueueItem } from './global.js';
+import type { Serializable } from './schemas.js';
+export type StepFunction<Args extends Serializable[] = any[], Result extends Serializable | unknown = unknown> = ((...args: Args) => Promise<Result>) & {
+    maxRetries?: number;
+    stepId?: string;
 };
+/**
+ * Register a step function to be served in the server bundle.
+ * Also sets the stepId property on the function for serialization support.
+ *
+ * Note: The SWC compiler plugin no longer generates calls to this function.
+ * Step registration is now inlined as a self-contained IIFE that writes
+ * directly to the global Map at Symbol.for("@workflow/core//registeredSteps").
+ * This function is kept for internal/test use only.
+ */
+export declare function registerStepFunction(stepId: string, stepFn: StepFunction): void;
+/**
+ * Find a registered step function by name
+ */
+export declare function getStepFunction(stepId: string): StepFunction | undefined;
 export interface WorkflowOrchestratorContext {
-  [key: string]: unknown;
+    runId: string;
+    encryptionKey: CryptoKey | undefined;
+    globalThis: typeof globalThis;
+    eventsConsumer: EventsConsumer;
+    /**
+     * Map of pending invocations keyed by correlationId.
+     * Using Map instead of Array for O(1) lookup/delete operations.
+     */
+    invocationsQueue: Map<string, QueueItem>;
+    onWorkflowError: (error: Error) => void;
+    generateUlid: () => string;
+    generateNanoid: () => string;
+    /**
+     * Sequential promise queue that ensures all event-driven promise resolutions
+     * (step results, hook payloads, failures, suspensions) happen in event log
+     * order. Every resolve, reject, or workflow error is chained through this
+     * queue so that even if individual operations take variable time (e.g.,
+     * async decryption), promises resolve deterministically.
+     */
+    promiseQueue: Promise<void>;
+    /**
+     * Counter of in-flight async data delivery operations (step result
+     * hydration, hook payload hydration). Suspensions must wait for this
+     * to reach 0 before firing, to avoid preempting data delivery.
+     */
+    pendingDeliveries: number;
 }
-export declare function __private_getClosureVars(): Record<string, unknown>;
-export declare function getStepFunction(stepId: string): StepFunction | undefined;
-export declare function registerStepFunction(stepId: string, stepFn: StepFunction): void;
+/**
+ * Schedule a callback to fire only after all pending data deliveries
+ * (step results, hook payloads) and async deserialization have completed.
+ * Uses a polling loop: setTimeout(0) → check pendingDeliveries →
+ * if > 0, wait for promiseQueue → repeat. This handles the multi-round
+ * delivery pattern where each hook payload delivery cycle appends new
+ * async work to the promiseQueue.
+ */
 export declare function scheduleWhenIdle(ctx: WorkflowOrchestratorContext, fn: () => void): void;
+//# sourceMappingURL=private.d.ts.map

package/dist/src/compiled/@workflow/core/runtime/constants.d.ts

@@ -0,0 +1,4 @@
+export declare const MAX_QUEUE_DELIVERIES = 48;
+export declare const REPLAY_TIMEOUT_MS = 240000;
+export declare const REPLAY_TIMEOUT_MAX_RETRIES = 3;
+//# sourceMappingURL=constants.d.ts.map

package/dist/src/compiled/@workflow/core/runtime/get-port-lazy.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Lazy loader for getPort that prevents bundlers (Turbopack, esbuild)
+ * from statically tracing @workflow/utils/get-port and its filesystem
+ * operations (readdir, readFile, readlink) into the flow route bundle.
+ *
+ * Uses createRequire with a dynamically constructed specifier so the
+ * dependency is invisible to bundler static analysis.
+ */
+export declare function getPortLazy(): Promise<number | undefined>;
+//# sourceMappingURL=get-port-lazy.d.ts.map

package/dist/src/compiled/@workflow/core/runtime/get-world-lazy.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Lazy accessor for the World singleton via globalThis symbols.
+ *
+ * This module exists to break the static import chain from step-side
+ * modules (serialization, run, helpers, start) to world.ts. Without it,
+ * esbuild bundles world.ts (and its transitive deps: world-local,
+ * world-vercel, process.cwd(), etc.) into the step registrations bundle,
+ * which triggers Turbopack NFT tracing errors in the V2 combined flow route.
+ *
+ * Resolution order, in priority:
+ *
+ * 1. `globalThis[WorldCacheKey]` — populated by a successful prior
+ *    `getWorld()` call. This is the steady-state hot path.
+ * 2. `globalThis[GetWorldFnKey]` — populated by the module-load side
+ *    effect at the bottom of `./world.ts`. Fires on every server bundle
+ *    that reaches this file via `workflow/api` (which imports
+ *    `./world-init.ts` for its side effect; see that file for the full
+ *    rationale). This is the cold-start path for routes that consume
+ *    `start` without any prior workflow run.
+ * 3. Dynamic `import('./world.js')` — last-resort fallback for
+ *    environments where neither (1) nor (2) is available (CJS test
+ *    runners, scripts that import deeply into `@workflow/core` without
+ *    going through `workflow/api`, future bundlers we haven't validated).
+ *    The specifier is built at runtime so esbuild can't trace it into
+ *    step bundles. Note: this branch is unreliable in webpack-bundled
+ *    routes because webpack inlines this module into the route file and
+ *    the relative path resolves against the bundle location — paths (1)
+ *    and (2) cover those cases instead.
+ */
+import type { World } from '../_workflow-world.js';
+export declare function getWorldLazy(): Promise<World>;
+//# sourceMappingURL=get-world-lazy.d.ts.map

package/dist/src/compiled/@workflow/core/runtime/helpers.d.ts

@@ -0,0 +1,97 @@
+import type { Event, HealthCheckPayload, ValidQueueName, WorkflowRun, World } from '../_workflow-world.js';
+import { type CryptoKey } from '../encryption.js';
+/**
+ * Validates a workflow name and returns the corresponding queue name.
+ * Ensures the workflow name only contains safe characters before
+ * interpolating it into the queue name string.
+ */
+export declare function getWorkflowQueueName(workflowName: string): ValidQueueName;
+/**
+ * Result of a health check operation.
+ */
+export interface HealthCheckResult {
+    healthy: boolean;
+    /** Error message if health check failed */
+    error?: string;
+    /** Latency if the health check was successful */
+    latencyMs?: number;
+    /** Spec version of the responding deployment */
+    specVersion?: number;
+}
+/**
+ * Checks if the given message is a health check payload.
+ * If so, returns the parsed payload. Otherwise returns undefined.
+ */
+export declare function parseHealthCheckPayload(message: unknown): HealthCheckPayload | undefined;
+/**
+ * Handles a health check message by writing the result to the world's stream.
+ * The caller can listen to this stream to get the health check response.
+ *
+ * @param healthCheck - The parsed health check payload
+ * @param endpoint - Which endpoint is responding ('workflow' or 'step')
+ */
+export declare function handleHealthCheckMessage(healthCheck: HealthCheckPayload, endpoint: 'workflow' | 'step', worldSpecVersion?: number): Promise<void>;
+export type HealthCheckEndpoint = 'workflow' | 'step';
+export interface HealthCheckOptions {
+    /** Timeout in milliseconds to wait for health check response. Default: 30000 (30s) */
+    timeout?: number;
+    /** Deployment ID to send the health check to. Falls back to process.env.VERCEL_DEPLOYMENT_ID. */
+    deploymentId?: string;
+}
+export declare function healthCheck(world: World, endpoint: HealthCheckEndpoint, options?: HealthCheckOptions): Promise<HealthCheckResult>;
+/**
+ * Loads workflow run events by iterating through all pages of paginated
+ * results. Events are returned in chronological (ascending) order for
+ * deterministic workflow replay.
+ *
+ * @param runId - The workflow run ID.
+ * @param afterCursor - If provided, only events after this cursor are
+ *   returned (incremental load). If omitted, all events are returned.
+ *   The returned cursor can be passed back in on a subsequent call for
+ *   incremental loading.
+ */
+export declare function loadWorkflowRunEvents(runId: string, afterCursor?: string): Promise<{
+    events: Event[];
+    cursor: string | null;
+}>;
+/**
+ * Wraps a request/response handler and adds a health check "mode"
+ * based on the presence of a `__health` query parameter.
+ */
+export declare function withHealthCheck(handler: (req: Request) => Promise<Response>, worldSpecVersion?: number): (req: Request) => Promise<Response>;
+/**
+ * Queues a message to the specified queue with tracing.
+ */
+export declare function queueMessage(world: World, ...args: Parameters<typeof world.queue>): Promise<void>;
+/**
+ * Calculates the queue overhead time in milliseconds for a given message.
+ */
+export declare function getQueueOverhead(message: {
+    requestedAt?: Date;
+}): {
+    [k: string]: number;
+} | undefined;
+/**
+ * Returns a memoized accessor for the per-run AES-256 encryption key.
+ *
+ * The first call resolves the key via `world.getEncryptionKeyForRun` (which
+ * may do HKDF derivation locally on Vercel, or a network fetch from
+ * external contexts) and imports it as a `CryptoKey`; subsequent calls
+ * await the same cached promise. If the world doesn't support encryption
+ * or the run has no key configured, the cached value is `undefined`.
+ *
+ * Used by step / workflow handlers to defer the (potentially expensive)
+ * key fetch until the first code path that actually needs it — typically
+ * input hydration on the success path, or error dehydration on a failure
+ * path. Both paths can race-call the accessor without triggering duplicate
+ * fetches.
+ *
+ * Errors thrown by `getEncryptionKeyForRun` propagate to every caller
+ * (the cached promise rejects). This is intentional: when encryption is
+ * configured, we never want to silently fall back to plaintext
+ * serialization. A propagated error in an event-emission path leaves the
+ * outer try/catch to log and surface the issue; the queue's redelivery
+ * semantics will retry the key fetch on the next attempt.
+ */
+export declare function memoizeEncryptionKey(world: World, runOrId: WorkflowRun | string): () => Promise<CryptoKey | undefined>;
+//# sourceMappingURL=helpers.d.ts.map

package/dist/src/compiled/@workflow/core/runtime/resume-hook.d.ts

@@ -0,0 +1,77 @@
+import { type Hook } from '../_workflow-world.js';
+import { type CryptoKey } from '../encryption.js';
+/**
+ * Get the hook by token to find the associated workflow run,
+ * and hydrate the `metadata` property if it was set from within
+ * the workflow run.
+ *
+ * @param token - The unique token identifying the hook
+ */
+export declare function getHookByToken(token: string): Promise<Hook>;
+/**
+ * Resumes a workflow run by sending a payload to a hook identified by its token.
+ *
+ * This function is called externally (e.g., from an API route or server action)
+ * to send data to a hook and resume the associated workflow run.
+ *
+ * @param tokenOrHook - The unique token identifying the hook, or the hook object itself
+ * @param payload - The data payload to send to the hook
+ * @returns Promise resolving to the hook
+ * @throws Error if the hook is not found or if there's an error during the process
+ *
+ * @example
+ *
+ * ```ts
+ * // In an API route
+ * import { resumeHook } from '@workflow/core/runtime';
+ *
+ * export async function POST(request: Request) {
+ *   const { token, data } = await request.json();
+ *
+ *   try {
+ *     const hook = await resumeHook(token, data);
+ *     return Response.json({ runId: hook.runId });
+ *   } catch (error) {
+ *     return new Response('Hook not found', { status: 404 });
+ *   }
+ * }
+ * ```
+ */
+export declare function resumeHook<T = any>(tokenOrHook: string | Hook, payload: T, encryptionKeyOverride?: CryptoKey): Promise<Hook>;
+/**
+ * Resumes a webhook by sending a {@link https://developer.mozilla.org/en-US/docs/Web/API/Request | Request}
+ * object to a hook identified by its token.
+ *
+ * This function is called externally (e.g., from an API route or server action)
+ * to send a request to a webhook and resume the associated workflow run.
+ *
+ * @param token - The unique token identifying the hook
+ * @param request - The request to send to the hook
+ * @returns Promise resolving to the response
+ * @throws Error if the hook is not found or if there's an error during the process
+ *
+ * @example
+ *
+ * ```ts
+ * // In an API route
+ * import { resumeWebhook } from '@workflow/core/runtime';
+ *
+ * export async function POST(request: Request) {
+ *   const url = new URL(request.url);
+ *   const token = url.searchParams.get('token');
+ *
+ *   if (!token) {
+ *     return new Response('Missing token', { status: 400 });
+ *   }
+ *
+ *   try {
+ *     const response = await resumeWebhook(token, request);
+ *     return response;
+ *   } catch (error) {
+ *     return new Response('Webhook not found', { status: 404 });
+ *   }
+ * }
+ * ```
+ */
+export declare function resumeWebhook(token: string, request: Request): Promise<Response>;
+//# sourceMappingURL=resume-hook.d.ts.map

package/dist/src/compiled/@workflow/core/runtime/run.d.ts

@@ -0,0 +1,134 @@
+import { WORKFLOW_DESERIALIZE, WORKFLOW_SERIALIZE } from '../_workflow-serde.js';
+import { type WorkflowRunStatus } from '../_workflow-world.js';
+import { type StopSleepOptions, type StopSleepResult } from './runs.js';
+/**
+ * A `ReadableStream` extended with workflow-specific helpers.
+ */
+export type WorkflowReadableStream<R = any> = ReadableStream<R> & {
+    /**
+     * Returns the tail index (index of the last known chunk, 0-based) of the
+     * underlying workflow stream. Useful for resolving a negative `startIndex`
+     * into an absolute position — for example, when building reconnection
+     * endpoints that need to inform the client where the stream starts.
+     *
+     * Returns `-1` when no chunks have been written yet.
+     */
+    getTailIndex(): Promise<number>;
+};
+/**
+ * Options for configuring a workflow's readable stream.
+ */
+export interface WorkflowReadableStreamOptions {
+    /**
+     * An optional namespace to distinguish between multiple streams associated
+     * with the same workflow run.
+     */
+    namespace?: string;
+    /**
+     * The index number of the starting chunk to begin reading the stream from.
+     * Negative values start from the end (e.g. -3 reads the last 3 chunks).
+     */
+    startIndex?: number;
+    /**
+     * Any asynchronous operations that need to be performed before the execution
+     * environment is paused / terminated
+     * (i.e. using [`waitUntil()`](https://developer.mozilla.org/docs/Web/API/ExtendableEvent/waitUntil) or similar).
+     */
+    ops?: Promise<any>[];
+    /**
+     * The global object to use for hydrating types from the global scope.
+     *
+     * Defaults to {@link [`globalThis`](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/globalThis)}.
+     */
+    global?: Record<string, any>;
+}
+/**
+ * A handler class for a workflow run.
+ */
+export declare class Run<TResult> {
+    #private;
+    static [WORKFLOW_SERIALIZE](instance: Run<unknown>): {
+        runId: string;
+        resilientStart: boolean;
+    };
+    static [WORKFLOW_DESERIALIZE](data: {
+        runId: string;
+        resilientStart?: boolean;
+    }): Run<unknown>;
+    /**
+     * The ID of the workflow run.
+     */
+    runId: string;
+    constructor(runId: string, opts?: {
+        resilientStart?: boolean;
+    });
+    /**
+     * Interrupts pending `sleep()` calls, resuming the workflow early.
+     *
+     * @param options - Optional settings to target specific sleep calls by correlation ID.
+     *   If not provided, all pending sleep calls will be interrupted.
+     * @returns A {@link StopSleepResult} object containing the number of sleep calls that were interrupted.
+     */
+    wakeUp(options?: StopSleepOptions): Promise<StopSleepResult>;
+    /**
+     * Cancels the workflow run.
+     */
+    cancel(): Promise<void>;
+    /**
+     * Whether the workflow run exists.
+     */
+    get exists(): Promise<boolean>;
+    /**
+     * The status of the workflow run.
+     */
+    get status(): Promise<WorkflowRunStatus>;
+    /**
+     * The return value of the workflow run.
+     * Polls the workflow return value until it is completed.
+     */
+    get returnValue(): Promise<TResult>;
+    /**
+     * The name of the workflow.
+     */
+    get workflowName(): Promise<string>;
+    /**
+     * The timestamp when the workflow run was created.
+     */
+    get createdAt(): Promise<Date>;
+    /**
+     * The timestamp when the workflow run started execution.
+     * Returns undefined if the workflow has not started yet.
+     */
+    get startedAt(): Promise<Date | undefined>;
+    /**
+     * The timestamp when the workflow run completed.
+     * Returns undefined if the workflow has not completed yet.
+     */
+    get completedAt(): Promise<Date | undefined>;
+    /**
+     * The readable stream of the workflow run.
+     */
+    get readable(): WorkflowReadableStream;
+    /**
+     * Retrieves the workflow run's default readable stream, which reads chunks
+     * written to the corresponding writable stream {@link getWritable}.
+     *
+     * The returned stream has an additional {@link WorkflowReadableStream.getTailIndex | getTailIndex()}
+     * helper that returns the index of the last known chunk. This is useful when
+     * building reconnection endpoints that need to inform clients where the
+     * stream starts.
+     *
+     * @param options - The options for the readable stream.
+     * @returns A `WorkflowReadableStream` for the workflow run.
+     */
+    getReadable<R = any>(options?: WorkflowReadableStreamOptions): WorkflowReadableStream<R>;
+}
+/**
+ * Retrieves a `Run` object for a given run ID.
+ *
+ * @param runId - The workflow run ID obtained from {@link start}.
+ * @returns A `Run` object.
+ * @throws WorkflowRunNotFoundError if the run ID is not found.
+ */
+export declare function getRun<TResult>(runId: string): Run<TResult>;
+//# sourceMappingURL=run.d.ts.map

package/dist/src/compiled/@workflow/core/runtime/runs.d.ts

@@ -0,0 +1,50 @@
+import { type World } from '../_workflow-world.js';
+export interface RecreateRunOptions {
+    deploymentId?: string;
+    specVersion?: number;
+}
+export interface StopSleepResult {
+    /** Number of pending sleeps that were stopped */
+    stoppedCount: number;
+}
+export interface ReadStreamOptions {
+    /**
+     * The index to start reading from. Defaults to 0.
+     * Negative values start from the end (e.g. -3 reads the last 3 chunks).
+     */
+    startIndex?: number;
+}
+export interface StopSleepOptions {
+    /**
+     * Optional list of specific correlation IDs to target.
+     * If provided, only these sleep calls will be interrupted.
+     * If not provided, all pending sleep calls will be interrupted.
+     */
+    correlationIds?: string[];
+}
+/**
+ * Start a new workflow run based on an existing run.
+ */
+export declare function recreateRunFromExisting(world: World, runId: string, options?: RecreateRunOptions): Promise<string>;
+/**
+ * Cancel a workflow run.
+ */
+export declare function cancelRun(world: World, runId: string): Promise<void>;
+/**
+ * Re-enqueue a workflow run.
+ */
+export declare function reenqueueRun(world: World, runId: string): Promise<void>;
+/**
+ * Wake up a workflow run by interrupting pending sleep() calls.
+ */
+export declare function wakeUpRun(world: World, runId: string, options?: StopSleepOptions): Promise<StopSleepResult>;
+/**
+ * Read from a stream by stream ID.
+ * Returns a ReadableStream of Uint8Array chunks.
+ */
+export declare function readStream(world: World, runId: string, streamId: string, options?: ReadStreamOptions): Promise<ReadableStream<Uint8Array>>;
+/**
+ * List all stream IDs for a workflow run.
+ */
+export declare function listStreams(world: World, runId: string): Promise<string[]>;
+//# sourceMappingURL=runs.d.ts.map

package/dist/src/compiled/@workflow/core/runtime/start.d.ts

@@ -0,0 +1,59 @@
+import type { World } from '../_workflow-world.js';
+import { Run } from './run.js';
+export interface StartOptionsBase {
+    /**
+     * The world to use for the workflow run creation,
+     * by default the world is inferred from the environment variables.
+     */
+    world?: World;
+    /**
+     * The spec version to use for the workflow run. Defaults to the latest version.
+     */
+    specVersion?: number;
+}
+export interface StartOptionsWithDeploymentId extends StartOptionsBase {
+    /**
+     * The deployment ID to use for the workflow run.
+     *
+     * By default, this is automatically inferred from environment variables
+     * when deploying to Vercel.
+     *
+     * Set to `'latest'` to automatically resolve the most recent deployment
+     * for the current environment (same production target or git branch).
+     * This is currently a Vercel-specific feature.
+     *
+     * **Note:** When `deploymentId` is provided, the argument and return types become `unknown`
+     * since there is no guarantee the types will be consistent across deployments.
+     */
+    deploymentId: 'latest' | (string & {});
+}
+export interface StartOptionsWithoutDeploymentId extends StartOptionsBase {
+    deploymentId?: undefined;
+}
+/**
+ * Options for starting a workflow run.
+ */
+export type StartOptions = StartOptionsWithDeploymentId | StartOptionsWithoutDeploymentId;
+/**
+ * Represents an imported workflow function.
+ */
+export type WorkflowFunction<TArgs extends unknown[], TResult> = (...args: TArgs) => Promise<TResult>;
+/**
+ * Represents the generated metadata of a workflow function.
+ */
+export type WorkflowMetadata = {
+    workflowId: string;
+};
+/**
+ * Starts a workflow run.
+ *
+ * @param workflow - The imported workflow function to start.
+ * @param args - The arguments to pass to the workflow (optional).
+ * @param options - The options for the workflow run (optional).
+ * @returns The unique run ID for the newly started workflow invocation.
+ */
+export declare function start<TArgs extends unknown[], TResult>(workflow: WorkflowFunction<TArgs, TResult> | WorkflowMetadata, args: unknown[], options: StartOptionsWithDeploymentId): Promise<Run<unknown>>;
+export declare function start<TResult>(workflow: WorkflowFunction<[], TResult> | WorkflowMetadata, options: StartOptionsWithDeploymentId): Promise<Run<unknown>>;
+export declare function start<TArgs extends unknown[], TResult>(workflow: WorkflowFunction<TArgs, TResult> | WorkflowMetadata, args: TArgs, options?: StartOptionsWithoutDeploymentId): Promise<Run<TResult>>;
+export declare function start<TResult>(workflow: WorkflowFunction<[], TResult> | WorkflowMetadata, options?: StartOptionsWithoutDeploymentId): Promise<Run<TResult>>;
+//# sourceMappingURL=start.d.ts.map

package/dist/src/compiled/@workflow/core/runtime/step-executor.d.ts

@@ -0,0 +1,40 @@
+import type { World } from '../_workflow-world.js';
+import type { CryptoKey } from '../encryption.js';
+export interface StepExecutorParams {
+    world: World;
+    workflowRunId: string;
+    workflowName: string;
+    workflowStartedAt: number;
+    stepId: string;
+    stepName: string;
+    encryptionKey?: CryptoKey;
+}
+/**
+ * Result of a step execution attempt. The caller decides what to do
+ * based on the result type (e.g., queue workflow continuation, replay inline, etc.).
+ */
+export type StepExecutionResult = {
+    type: 'completed';
+    hasPendingOps?: boolean;
+} | {
+    type: 'failed';
+} | {
+    type: 'retry';
+    timeoutSeconds: number;
+} | {
+    type: 'skipped';
+} | {
+    type: 'gone';
+} | {
+    type: 'throttled';
+    timeoutSeconds: number;
+};
+/**
+ * Executes a single step: creates step_started event, hydrates input,
+ * runs the step function, creates step_completed/step_failed/step_retrying events.
+ *
+ * Does NOT queue workflow continuation messages — the caller decides what to do next.
+ * Used by both the V1 step handler and the V2 combined handler.
+ */
+export declare function executeStep(params: StepExecutorParams): Promise<StepExecutionResult>;
+//# sourceMappingURL=step-executor.d.ts.map

package/dist/src/compiled/@workflow/core/runtime/step-handler.d.ts

@@ -0,0 +1,2 @@
+export declare const stepEntrypoint: (req: Request) => Promise<Response>;
+//# sourceMappingURL=step-handler.d.ts.map

package/dist/src/compiled/@workflow/core/runtime/suspension-handler.d.ts

@@ -0,0 +1,42 @@
+import type { Span } from '#compiled/@opentelemetry/api/index.js';
+import { type WorkflowRun, type World } from '../_workflow-world.js';
+import type { StepInvocationQueueItem, WorkflowSuspension } from '../global.js';
+export interface SuspensionHandlerParams {
+    suspension: WorkflowSuspension;
+    world: World;
+    run: WorkflowRun;
+    span?: Span;
+    requestId?: string;
+}
+/**
+ * Result of handling a suspension. Returns pending step items so the caller
+ * can decide which to execute inline vs queue to background.
+ */
+export interface SuspensionHandlerResult {
+    /** Pending step items with events created but NOT queued */
+    pendingSteps: StepInvocationQueueItem[];
+    /**
+     * Correlation IDs for which this suspension call actually wrote the
+     * step_created event (as opposed to catching EntityConflictError because
+     * a concurrent handler wrote it first). Only the handler that wrote the
+     * step_created event should queue / inline-execute the step — this
+     * guarantees a single owner per step, even when multiple handlers race
+     * into the same batch boundary.
+     */
+    createdStepCorrelationIds: Set<string>;
+    /** Timeout from waits, if any */
+    timeoutSeconds?: number;
+    /** Whether a hook conflict was detected (should re-invoke immediately) */
+    hasHookConflict: boolean;
+}
+/**
+ * Handles a workflow suspension by processing all pending operations (hooks, steps, waits).
+ * Creates events for all operations but does NOT queue step messages — returns the pending
+ * steps so the caller can decide which to execute inline vs queue to background.
+ *
+ * Processing order:
+ * 1. Hooks are processed first to prevent race conditions with webhook receivers
+ * 2. Step events and wait events are created in parallel
+ */
+export declare function handleSuspension({ suspension, world, run, span, requestId, }: SuspensionHandlerParams): Promise<SuspensionHandlerResult>;
+//# sourceMappingURL=suspension-handler.d.ts.map