@jagreehal/workflow 1.4.0 → 1.5.0

package/dist/index.d.cts

@@ -1,2 +1,3266 @@
-export { AsyncResult, BackoffStrategy, CauseOf, EmptyInputError, ErrorOf, Errors, ExtractCause, ExtractError, ExtractValue, MaybeAsyncResult, PromiseRejectedError, PromiseRejectionCause, Result, RetryOptions, RunOptions, RunOptionsWithCatch, RunOptionsWithoutCatch, RunStep, STEP_TIMEOUT_MARKER, ScopeType, SettledError, StepOptions, StepTimeoutError, StepTimeoutMarkerMeta, TimeoutOptions, UnexpectedCause, UnexpectedError, UnexpectedStepFailureCause, UnwrapError, WorkflowEvent, all, allAsync, allSettled, allSettledAsync, andThen, any, anyAsync, err, from, fromNullable, fromPromise, getStepTimeoutMeta, isErr, isOk, isStepTimeoutError, isUnexpectedError, map, mapError, mapErrorTry, mapTry, match, ok, partition, run, tap, tapError, tryAsync, unwrap, unwrapOr, unwrapOrElse } from './core.cjs';
-export { AnyResultFn, ApprovalRejected, ApprovalStepOptions, CausesOfDeps, ErrorsOfDeps, PendingApproval, ResumeState, ResumeStateEntry, StepCache, Workflow, WorkflowOptions, WorkflowOptionsStrict, WorkflowStrict, clearStep, createApprovalStep, createHITLCollector, createStepCollector, createWorkflow, getPendingApprovals, hasPendingApproval, injectApproval, isApprovalRejected, isPendingApproval, isStepComplete, pendingApproval } from './workflow.cjs';
+import { WorkflowEvent, Result, AsyncResult, UnexpectedError, StepOptions, RetryOptions, TimeoutOptions, StepFailureMeta } from './core.cjs';
+export { BackoffStrategy, CauseOf, EmptyInputError, ErrorOf, Errors, ExtractCause, ExtractError, ExtractValue, MaybeAsyncResult, PromiseRejectedError, PromiseRejectionCause, RunOptions, RunOptionsWithCatch, RunOptionsWithoutCatch, RunStep, STEP_TIMEOUT_MARKER, ScopeType, SettledError, StepTimeoutError, StepTimeoutMarkerMeta, UnexpectedCause, UnexpectedStepFailureCause, UnwrapError, all, allAsync, allSettled, allSettledAsync, andThen, any, anyAsync, err, from, fromNullable, fromPromise, getStepTimeoutMeta, isErr, isOk, isStepTimeoutError, isUnexpectedError, map, mapError, mapErrorTry, mapTry, match, ok, partition, run, tap, tapError, tryAsync, unwrap, unwrapOr, unwrapOrElse } from './core.cjs';
+import { ResumeState, ResumeStateEntry, Workflow, WorkflowStrict, StepCache, AnyResultFn as AnyResultFn$1, ErrorsOfDeps as ErrorsOfDeps$1 } from './workflow.cjs';
+export { ApprovalRejected, ApprovalStepOptions, CausesOfDeps, PendingApproval, WorkflowOptions, WorkflowOptionsStrict, clearStep, createApprovalStep, createHITLCollector, createStepCollector, createWorkflow, getPendingApprovals, hasPendingApproval, injectApproval, isApprovalRejected, isPendingApproval, isStepComplete, pendingApproval } from './workflow.cjs';
+import { CollectableEvent, VisualizerOptions, DecisionStartEvent, DecisionBranchEvent, DecisionEndEvent, OutputFormat } from './visualize.cjs';
+
+/**
+ * @jagreehal/workflow/conditional
+ *
+ * Conditional step execution helpers for workflows.
+ * These helpers allow you to conditionally execute steps based on runtime conditions,
+ * with proper event emission for skipped steps.
+ */
+
+/**
+ * Options for conditional execution.
+ */
+type ConditionalOptions = {
+    /**
+     * Human-readable name for the conditional step.
+     * Used in step_skipped events for debugging and visualization.
+     */
+    name?: string;
+    /**
+     * Stable identity key for the conditional step.
+     * Used in step_skipped events for tracking and visualization.
+     */
+    key?: string;
+    /**
+     * Optional reason explaining why the step was skipped.
+     * Included in step_skipped events.
+     */
+    reason?: string;
+};
+/**
+ * Context for conditional execution, used to emit events.
+ */
+type ConditionalContext = {
+    /**
+     * The workflow ID for event emission.
+     */
+    workflowId: string;
+    /**
+     * Event emitter function.
+     */
+    onEvent?: (event: WorkflowEvent<unknown>) => void;
+};
+/**
+ * Type for operations that can be either sync or async.
+ */
+type MaybeAsync<T> = T | Promise<T>;
+/**
+ * Type for the operation function passed to conditional helpers.
+ */
+type Operation<T> = () => MaybeAsync<T>;
+/**
+ * Run a step only if condition is true, return undefined if skipped.
+ *
+ * Use this when you want to conditionally execute a step and handle
+ * the undefined case yourself. For a version with a default value,
+ * use `whenOr`.
+ *
+ * @param condition - Boolean condition to evaluate
+ * @param operation - Function that performs the step (only called if condition is true)
+ * @param options - Optional configuration for the conditional step
+ * @param ctx - Optional context for event emission
+ * @returns The result of the operation if condition is true, undefined otherwise
+ *
+ * @example
+ * ```typescript
+ * const result = await workflow(async (step) => {
+ *   const user = await step(fetchUser(id));
+ *
+ *   // Only runs if user is premium
+ *   const premium = await when(
+ *     user.isPremium,
+ *     () => step(() => fetchPremiumData(user.id), { name: 'premium-data' }),
+ *     { name: 'check-premium', reason: 'User is not premium' }
+ *   );
+ *
+ *   return { user, premium };
+ * });
+ * ```
+ */
+declare function when<T>(condition: boolean, operation: Operation<T>, options?: ConditionalOptions, ctx?: ConditionalContext): Promise<T | undefined>;
+/**
+ * Synchronous overload for when the operation returns a non-Promise value.
+ */
+declare function when<T>(condition: boolean, operation: () => T, options?: ConditionalOptions, ctx?: ConditionalContext): T | undefined | Promise<T | undefined>;
+/**
+ * Run a step only if condition is false, return undefined if skipped.
+ *
+ * Use this when you want to conditionally execute a step when a condition
+ * is NOT met. For a version with a default value, use `unlessOr`.
+ *
+ * @param condition - Boolean condition to evaluate
+ * @param operation - Function that performs the step (only called if condition is false)
+ * @param options - Optional configuration for the conditional step
+ * @param ctx - Optional context for event emission
+ * @returns The result of the operation if condition is false, undefined otherwise
+ *
+ * @example
+ * ```typescript
+ * const result = await workflow(async (step) => {
+ *   const user = await step(fetchUser(id));
+ *
+ *   // Only runs if user is NOT verified
+ *   const verification = await unless(
+ *     user.isVerified,
+ *     () => step(() => sendVerificationEmail(user.email), { name: 'send-verification' }),
+ *     { name: 'check-verification', reason: 'User is already verified' }
+ *   );
+ *
+ *   return { user, verification };
+ * });
+ * ```
+ */
+declare function unless<T>(condition: boolean, operation: Operation<T>, options?: ConditionalOptions, ctx?: ConditionalContext): Promise<T | undefined>;
+/**
+ * Synchronous overload for unless when the operation returns a non-Promise value.
+ */
+declare function unless<T>(condition: boolean, operation: () => T, options?: ConditionalOptions, ctx?: ConditionalContext): T | undefined | Promise<T | undefined>;
+/**
+ * Run a step only if condition is true, return default value if skipped.
+ *
+ * Use this when you want to conditionally execute a step and provide
+ * a fallback value when the condition is not met.
+ *
+ * @param condition - Boolean condition to evaluate
+ * @param operation - Function that performs the step (only called if condition is true)
+ * @param defaultValue - Value to return if condition is false
+ * @param options - Optional configuration for the conditional step
+ * @param ctx - Optional context for event emission
+ * @returns The result of the operation if condition is true, defaultValue otherwise
+ *
+ * @example
+ * ```typescript
+ * const result = await workflow(async (step) => {
+ *   const user = await step(fetchUser(id));
+ *
+ *   // Get premium limits or use default for non-premium users
+ *   const limits = await whenOr(
+ *     user.isPremium,
+ *     () => step(() => fetchPremiumLimits(user.id), { name: 'premium-limits' }),
+ *     { maxRequests: 100, maxStorage: 1000 }, // default for non-premium
+ *     { name: 'check-premium-limits', reason: 'Using default limits for non-premium user' }
+ *   );
+ *
+ *   return { user, limits };
+ * });
+ * ```
+ */
+declare function whenOr<T, D>(condition: boolean, operation: Operation<T>, defaultValue: D, options?: ConditionalOptions, ctx?: ConditionalContext): Promise<T | D>;
+/**
+ * Synchronous overload for whenOr when the operation returns a non-Promise value.
+ */
+declare function whenOr<T, D>(condition: boolean, operation: () => T, defaultValue: D, options?: ConditionalOptions, ctx?: ConditionalContext): T | D | Promise<T | D>;
+/**
+ * Run a step only if condition is false, return default value if skipped.
+ *
+ * Use this when you want to conditionally execute a step when a condition
+ * is NOT met, with a fallback value for when the condition is true.
+ *
+ * @param condition - Boolean condition to evaluate
+ * @param operation - Function that performs the step (only called if condition is false)
+ * @param defaultValue - Value to return if condition is true
+ * @param options - Optional configuration for the conditional step
+ * @param ctx - Optional context for event emission
+ * @returns The result of the operation if condition is false, defaultValue otherwise
+ *
+ * @example
+ * ```typescript
+ * const result = await workflow(async (step) => {
+ *   const user = await step(fetchUser(id));
+ *
+ *   // Generate new token if user is NOT authenticated, otherwise use existing
+ *   const token = await unlessOr(
+ *     user.isAuthenticated,
+ *     () => step(() => generateNewToken(user.id), { name: 'generate-token' }),
+ *     user.existingToken, // use existing token if authenticated
+ *     { name: 'check-auth-for-token', reason: 'Using existing token for authenticated user' }
+ *   );
+ *
+ *   return { user, token };
+ * });
+ * ```
+ */
+declare function unlessOr<T, D>(condition: boolean, operation: Operation<T>, defaultValue: D, options?: ConditionalOptions, ctx?: ConditionalContext): Promise<T | D>;
+/**
+ * Synchronous overload for unlessOr when the operation returns a non-Promise value.
+ */
+declare function unlessOr<T, D>(condition: boolean, operation: () => T, defaultValue: D, options?: ConditionalOptions, ctx?: ConditionalContext): T | D | Promise<T | D>;
+/**
+ * Create a set of conditional helpers bound to a workflow context.
+ *
+ * Use this factory when you want to automatically emit step_skipped events
+ * to the workflow's event stream without passing context manually.
+ *
+ * @param ctx - The workflow context containing workflowId and onEvent
+ * @returns Object with bound when, unless, whenOr, and unlessOr functions
+ *
+ * @example
+ * ```typescript
+ * const result = await run(async (step) => {
+ *   const ctx = { workflowId, onEvent };
+ *   const { when, whenOr } = createConditionalHelpers(ctx);
+ *
+ *   const user = await step(fetchUser(id));
+ *
+ *   const premium = await when(
+ *     user.isPremium,
+ *     () => step(() => fetchPremiumData(user.id)),
+ *     { name: 'premium-data' }
+ *   );
+ *
+ *   return { user, premium };
+ * }, { onEvent, workflowId });
+ * ```
+ */
+declare function createConditionalHelpers(ctx: ConditionalContext): {
+    /**
+     * Run a step only if condition is true, return undefined if skipped.
+     */
+    when: <T>(condition: boolean, operation: Operation<T>, options?: ConditionalOptions) => MaybeAsync<T | undefined>;
+    /**
+     * Run a step only if condition is false, return undefined if skipped.
+     */
+    unless: <T>(condition: boolean, operation: Operation<T>, options?: ConditionalOptions) => MaybeAsync<T | undefined>;
+    /**
+     * Run a step only if condition is true, return default value if skipped.
+     */
+    whenOr: <T, D>(condition: boolean, operation: Operation<T>, defaultValue: D, options?: ConditionalOptions) => MaybeAsync<T | D>;
+    /**
+     * Run a step only if condition is false, return default value if skipped.
+     */
+    unlessOr: <T, D>(condition: boolean, operation: Operation<T>, defaultValue: D, options?: ConditionalOptions) => MaybeAsync<T | D>;
+};
+
+/**
+ * Circuit Breaker for Steps
+ *
+ * Prevents cascading failures by tracking step failure rates and
+ * short-circuiting calls when a threshold is exceeded.
+ *
+ * Uses the circuit breaker pattern with three states:
+ * - CLOSED: Normal operation (steps executing)
+ * - OPEN: Fast-fail mode (steps blocked)
+ * - HALF_OPEN: Testing if service recovered
+ *
+ * @example
+ * ```typescript
+ * import { createCircuitBreaker } from '@jagreehal/workflow';
+ *
+ * const breaker = createCircuitBreaker({
+ *   failureThreshold: 5,
+ *   resetTimeout: 30000,
+ *   halfOpenMax: 3,
+ * });
+ *
+ * const result = await workflow(async (step) => {
+ *   const data = await breaker.execute(
+ *     () => step(() => callExternalApi()),
+ *     { name: 'external-api' }
+ *   );
+ *   return data;
+ * });
+ * ```
+ */
+
+/**
+ * Circuit breaker state.
+ */
+type CircuitState = "CLOSED" | "OPEN" | "HALF_OPEN";
+/**
+ * Configuration for circuit breaker behavior.
+ */
+interface CircuitBreakerConfig {
+    /**
+     * Number of failures within the window before opening the circuit.
+     * @default 5
+     */
+    failureThreshold: number;
+    /**
+     * Time in ms to wait before transitioning from OPEN to HALF_OPEN.
+     * @default 30000 (30 seconds)
+     */
+    resetTimeout: number;
+    /**
+     * Time window in ms for counting failures.
+     * Failures older than this are discarded.
+     * @default 60000 (1 minute)
+     */
+    windowSize: number;
+    /**
+     * Maximum number of test requests allowed in HALF_OPEN state.
+     * If all succeed, circuit closes. If any fail, circuit reopens.
+     * @default 3
+     */
+    halfOpenMax: number;
+    /**
+     * Optional callback when circuit state changes.
+     */
+    onStateChange?: (from: CircuitState, to: CircuitState, name?: string) => void;
+}
+/**
+ * Error thrown when the circuit is open and calls are blocked.
+ */
+declare class CircuitOpenError extends Error {
+    readonly type: "CIRCUIT_OPEN";
+    readonly circuitName: string;
+    readonly state: CircuitState;
+    readonly retryAfterMs: number;
+    constructor(options: {
+        circuitName: string;
+        state: CircuitState;
+        retryAfterMs: number;
+        message?: string;
+    });
+}
+/**
+ * Type guard for CircuitOpenError.
+ */
+declare function isCircuitOpenError(error: unknown): error is CircuitOpenError;
+/**
+ * Circuit breaker statistics.
+ */
+interface CircuitBreakerStats {
+    state: CircuitState;
+    failureCount: number;
+    successCount: number;
+    lastFailureTime: number | null;
+    lastSuccessTime: number | null;
+    halfOpenSuccesses: number;
+}
+/**
+ * Circuit breaker instance for protecting external calls.
+ */
+interface CircuitBreaker {
+    /**
+     * Execute an operation with circuit breaker protection.
+     * Throws CircuitOpenError if the circuit is open.
+     *
+     * @param operation - The operation to execute
+     * @param options - Optional name for logging/metrics
+     * @returns The operation result
+     * @throws CircuitOpenError if circuit is open
+     */
+    execute<T>(operation: () => T | Promise<T>, options?: {
+        name?: string;
+    }): Promise<T>;
+    /**
+     * Execute a Result-returning operation with circuit breaker protection.
+     * Returns a CircuitOpenError result instead of throwing.
+     *
+     * @param operation - The operation returning a Result
+     * @param options - Optional name for logging/metrics
+     * @returns Result with the value or CircuitOpenError
+     */
+    executeResult<T, E>(operation: () => Result<T, E> | AsyncResult<T, E>, options?: {
+        name?: string;
+    }): AsyncResult<T, E | CircuitOpenError>;
+    /**
+     * Get current circuit state.
+     */
+    getState(): CircuitState;
+    /**
+     * Get circuit breaker statistics.
+     */
+    getStats(): CircuitBreakerStats;
+    /**
+     * Manually reset the circuit breaker to CLOSED state.
+     */
+    reset(): void;
+    /**
+     * Manually open the circuit (for testing or manual intervention).
+     */
+    forceOpen(): void;
+    /**
+     * Record a manual success (useful for health checks).
+     */
+    recordSuccess(): void;
+    /**
+     * Record a manual failure (useful for health checks).
+     */
+    recordFailure(error?: unknown): void;
+}
+/**
+ * Create a circuit breaker instance.
+ *
+ * @param name - Name for this circuit breaker (used in errors and logging)
+ * @param config - Configuration options
+ * @returns A CircuitBreaker instance
+ *
+ * @example
+ * ```typescript
+ * const apiBreaker = createCircuitBreaker('external-api', {
+ *   failureThreshold: 5,
+ *   resetTimeout: 30000,
+ * });
+ *
+ * // In workflow
+ * const data = await apiBreaker.execute(() =>
+ *   step(() => fetchFromApi(id))
+ * );
+ * ```
+ */
+declare function createCircuitBreaker(name: string, config?: Partial<CircuitBreakerConfig>): CircuitBreaker;
+/**
+ * Preset configurations for common use cases.
+ */
+declare const circuitBreakerPresets: {
+    /**
+     * Aggressive circuit breaker for critical paths.
+     * Opens quickly (3 failures) and recovers slowly (60s).
+     */
+    readonly critical: {
+        failureThreshold: number;
+        resetTimeout: number;
+        windowSize: number;
+        halfOpenMax: number;
+    };
+    /**
+     * Standard circuit breaker for typical API calls.
+     * Balanced between stability and availability.
+     */
+    readonly standard: {
+        failureThreshold: number;
+        resetTimeout: number;
+        windowSize: number;
+        halfOpenMax: number;
+    };
+    /**
+     * Lenient circuit breaker for non-critical operations.
+     * Opens slowly (10 failures) and recovers quickly (15s).
+     */
+    readonly lenient: {
+        failureThreshold: number;
+        resetTimeout: number;
+        windowSize: number;
+        halfOpenMax: number;
+    };
+};
+
+/**
+ * Saga / Compensation Pattern
+ *
+ * Define compensating actions for steps that need rollback on downstream failures.
+ * When a workflow fails after some steps have completed, compensations run in
+ * reverse order automatically.
+ *
+ * @example
+ * ```typescript
+ * import { createSagaWorkflow, ok, err } from '@jagreehal/workflow';
+ *
+ * const checkout = createSagaWorkflow({ reserveInventory, chargeCard, sendEmail });
+ *
+ * const result = await checkout(async (saga) => {
+ *   const reservation = await saga.step(
+ *     () => reserveInventory(items),
+ *     { compensate: (res) => releaseInventory(res.reservationId) }
+ *   );
+ *
+ *   const payment = await saga.step(
+ *     () => chargeCard(amount),
+ *     { compensate: (p) => refundPayment(p.txId) }
+ *   );
+ *
+ *   await saga.step(() => sendEmail(userId)); // No compensation needed
+ *
+ *   return { reservation, payment };
+ * });
+ * // On failure: compensations run in reverse order automatically
+ * ```
+ */
+
+/**
+ * A compensation action to run on rollback.
+ */
+type CompensationAction<T> = (value: T) => void | Promise<void>;
+/**
+ * Options for a saga step.
+ */
+interface SagaStepOptions<T> {
+    /**
+     * Name for the step (used in logging and events).
+     */
+    name?: string;
+    /**
+     * Compensation action to run if a later step fails.
+     * Receives the value returned by this step.
+     */
+    compensate?: CompensationAction<T>;
+}
+/**
+ * Error returned when compensation actions fail.
+ */
+interface SagaCompensationError {
+    type: "SAGA_COMPENSATION_ERROR";
+    /** The original error that triggered the saga rollback */
+    originalError: unknown;
+    /** Errors from failed compensation actions */
+    compensationErrors: Array<{
+        stepName?: string;
+        error: unknown;
+    }>;
+}
+/**
+ * Type guard for SagaCompensationError.
+ */
+declare function isSagaCompensationError(error: unknown): error is SagaCompensationError;
+/**
+ * Saga execution context provided to the workflow callback.
+ */
+interface SagaContext<E = unknown> {
+    /**
+     * Execute a step with optional compensation.
+     *
+     * @param operation - The operation to execute (returns Result)
+     * @param options - Step options including compensation action
+     * @returns The unwrapped success value
+     */
+    step: <T, StepE extends E, StepC = unknown>(operation: () => Result<T, StepE, StepC> | AsyncResult<T, StepE, StepC>, options?: SagaStepOptions<T>) => Promise<T>;
+    /**
+     * Execute a throwing operation with optional compensation.
+     *
+     * @param operation - The operation to execute (may throw)
+     * @param options - Step options including error mapping and compensation
+     * @returns The success value
+     */
+    tryStep: <T, Err extends E>(operation: () => T | Promise<T>, options: {
+        error: Err;
+        name?: string;
+        compensate?: CompensationAction<T>;
+    } | {
+        onError: (cause: unknown) => Err;
+        name?: string;
+        compensate?: CompensationAction<T>;
+    }) => Promise<T>;
+    /**
+     * Get all recorded compensations (for debugging/testing).
+     */
+    getCompensations: () => Array<{
+        name?: string;
+        hasValue: boolean;
+    }>;
+}
+/**
+ * Saga event types for observability.
+ */
+type SagaEvent = {
+    type: "saga_start";
+    sagaId: string;
+    ts: number;
+} | {
+    type: "saga_success";
+    sagaId: string;
+    ts: number;
+    durationMs: number;
+} | {
+    type: "saga_error";
+    sagaId: string;
+    ts: number;
+    durationMs: number;
+    error: unknown;
+} | {
+    type: "saga_compensation_start";
+    sagaId: string;
+    ts: number;
+    stepCount: number;
+} | {
+    type: "saga_compensation_step";
+    sagaId: string;
+    stepName?: string;
+    ts: number;
+    success: boolean;
+    error?: unknown;
+} | {
+    type: "saga_compensation_end";
+    sagaId: string;
+    ts: number;
+    durationMs: number;
+    success: boolean;
+    failedCount: number;
+};
+/**
+ * Options for createSagaWorkflow.
+ */
+interface SagaWorkflowOptions<E> {
+    /**
+     * Called when errors occur.
+     */
+    onError?: (error: E | UnexpectedError | SagaCompensationError, stepName?: string) => void;
+    /**
+     * Event stream for saga lifecycle events.
+     */
+    onEvent?: (event: SagaEvent | WorkflowEvent<E | UnexpectedError>) => void;
+    /**
+     * Whether to throw if compensation actions fail.
+     * If false, original error is returned with compensation errors attached.
+     * @default false
+     */
+    throwOnCompensationFailure?: boolean;
+}
+/**
+ * Result type for saga workflow.
+ */
+type SagaResult<T, E> = Result<T, E | UnexpectedError | SagaCompensationError, unknown>;
+/**
+ * Helper type for Result-returning functions.
+ */
+type AnyResultFn = (...args: any[]) => Result<any, any, any> | Promise<Result<any, any, any>>;
+/**
+ * Extract union of error types from a deps object.
+ */
+type ErrorsOfDeps<Deps extends Record<string, AnyResultFn>> = {
+    [K in keyof Deps]: Deps[K] extends (...args: never[]) => infer R ? R extends Promise<infer PR> ? PR extends {
+        ok: false;
+        error: infer E;
+    } ? E : never : R extends {
+        ok: false;
+        error: infer E;
+    } ? E : never : never;
+}[keyof Deps];
+/**
+ * Create a saga workflow with automatic compensation on failure.
+ *
+ * @param deps - Object mapping names to Result-returning functions
+ * @param options - Saga workflow options
+ * @returns A saga executor function
+ *
+ * @example
+ * ```typescript
+ * const saga = createSagaWorkflow({ reserveInventory, chargeCard });
+ *
+ * const result = await saga(async (ctx) => {
+ *   const reservation = await ctx.step(
+ *     () => reserveInventory(items),
+ *     { compensate: (res) => releaseInventory(res.id) }
+ *   );
+ *
+ *   const payment = await ctx.step(
+ *     () => chargeCard(amount),
+ *     { compensate: (p) => refundPayment(p.txId) }
+ *   );
+ *
+ *   return { reservation, payment };
+ * });
+ * ```
+ */
+declare function createSagaWorkflow<const Deps extends Readonly<Record<string, AnyResultFn>>>(deps: Deps, options?: SagaWorkflowOptions<ErrorsOfDeps<Deps>>): <T>(fn: (saga: SagaContext<ErrorsOfDeps<Deps>>, deps: Deps) => Promise<T>) => Promise<SagaResult<T, ErrorsOfDeps<Deps>>>;
+/**
+ * Run a saga with explicit compensation registration.
+ *
+ * Lower-level API for when you don't want automatic error inference
+ * from a deps object.
+ *
+ * @example
+ * ```typescript
+ * const result = await runSaga<CheckoutResult, CheckoutError>(async (saga) => {
+ *   const reservation = await saga.step(
+ *     () => reserveInventory(items),
+ *     { compensate: (res) => releaseInventory(res.id) }
+ *   );
+ *   return { reservation };
+ * });
+ * ```
+ */
+declare function runSaga<T, E>(fn: (saga: SagaContext<E>) => Promise<T>, options?: Omit<SagaWorkflowOptions<E>, "onEvent"> & {
+    onEvent?: (event: SagaEvent) => void;
+}): Promise<SagaResult<T, E>>;
+
+/**
+ * Rate Limiting / Concurrency Control
+ *
+ * Control throughput for steps that hit rate-limited APIs or shared resources.
+ *
+ * @example
+ * ```typescript
+ * import { createRateLimiter, createConcurrencyLimiter } from '@jagreehal/workflow';
+ *
+ * // Rate limiting (requests per second)
+ * const rateLimiter = createRateLimiter({ maxPerSecond: 10 });
+ *
+ * // Concurrency limiting (max concurrent)
+ * const concurrencyLimiter = createConcurrencyLimiter({ maxConcurrent: 5 });
+ *
+ * const result = await workflow(async (step) => {
+ *   // Wrap operations with rate limiting
+ *   const data = await rateLimiter.execute(() =>
+ *     step(() => callRateLimitedApi())
+ *   );
+ *
+ *   // Wrap batch operations with concurrency control
+ *   const results = await concurrencyLimiter.executeAll(
+ *     ids.map(id => () => step(() => fetchItem(id)))
+ *   );
+ *
+ *   return { data, results };
+ * });
+ * ```
+ */
+
+/**
+ * Configuration for rate limiter.
+ */
+interface RateLimiterConfig {
+    /**
+     * Maximum operations per second.
+     */
+    maxPerSecond: number;
+    /**
+     * Burst capacity - allows brief spikes above the rate.
+     * @default maxPerSecond * 2
+     */
+    burstCapacity?: number;
+    /**
+     * Strategy when rate limit is exceeded.
+     * - 'wait': Wait until a slot is available (default)
+     * - 'reject': Reject immediately with error
+     * @default 'wait'
+     */
+    strategy?: "wait" | "reject";
+}
+/**
+ * Configuration for concurrency limiter.
+ */
+interface ConcurrencyLimiterConfig {
+    /**
+     * Maximum concurrent operations.
+     */
+    maxConcurrent: number;
+    /**
+     * Strategy when limit is reached.
+     * - 'queue': Queue and wait (default)
+     * - 'reject': Reject immediately
+     * @default 'queue'
+     */
+    strategy?: "queue" | "reject";
+    /**
+     * Maximum queue size (only for 'queue' strategy).
+     * @default Infinity
+     */
+    maxQueueSize?: number;
+}
+/**
+ * Error when rate/concurrency limit is exceeded and strategy is 'reject'.
+ */
+interface RateLimitExceededError {
+    type: "RATE_LIMIT_EXCEEDED";
+    limiterName: string;
+    retryAfterMs?: number;
+}
+/**
+ * Error when concurrency limit queue is full.
+ */
+interface QueueFullError {
+    type: "QUEUE_FULL";
+    limiterName: string;
+    queueSize: number;
+    maxQueueSize: number;
+}
+/**
+ * Type guard for RateLimitExceededError.
+ */
+declare function isRateLimitExceededError(error: unknown): error is RateLimitExceededError;
+/**
+ * Type guard for QueueFullError.
+ */
+declare function isQueueFullError(error: unknown): error is QueueFullError;
+/**
+ * Statistics for rate limiter.
+ */
+interface RateLimiterStats {
+    availableTokens: number;
+    maxTokens: number;
+    tokensPerSecond: number;
+    waitingCount: number;
+}
+/**
+ * Statistics for concurrency limiter.
+ */
+interface ConcurrencyLimiterStats {
+    activeCount: number;
+    maxConcurrent: number;
+    queueSize: number;
+    maxQueueSize: number;
+}
+/**
+ * Rate limiter interface.
+ */
+interface RateLimiter {
+    /**
+     * Execute an operation with rate limiting.
+     * @param operation - The operation to execute
+     * @returns The operation result
+     */
+    execute<T>(operation: () => T | Promise<T>): Promise<T>;
+    /**
+     * Execute a Result-returning operation with rate limiting.
+     */
+    executeResult<T, E>(operation: () => Result<T, E> | AsyncResult<T, E>): AsyncResult<T, E | RateLimitExceededError>;
+    /**
+     * Get current statistics.
+     */
+    getStats(): RateLimiterStats;
+    /**
+     * Reset the rate limiter.
+     */
+    reset(): void;
+}
+/**
+ * Create a token bucket rate limiter.
+ *
+ * @param name - Name for the limiter (used in errors)
+ * @param config - Rate limiter configuration
+ * @returns A RateLimiter instance
+ *
+ * @example
+ * ```typescript
+ * const limiter = createRateLimiter('api-calls', {
+ *   maxPerSecond: 10,
+ *   burstCapacity: 20,
+ * });
+ *
+ * // In workflow
+ * const data = await limiter.execute(() =>
+ *   step(() => callApi())
+ * );
+ * ```
+ */
+declare function createRateLimiter(name: string, config: RateLimiterConfig): RateLimiter;
+/**
+ * Concurrency limiter interface.
+ */
+interface ConcurrencyLimiter {
+    /**
+     * Execute an operation with concurrency limiting.
+     * @param operation - The operation to execute
+     * @returns The operation result
+     */
+    execute<T>(operation: () => T | Promise<T>): Promise<T>;
+    /**
+     * Execute multiple operations with concurrency control.
+     * @param operations - Array of operation factories
+     * @returns Array of results (in order)
+     */
+    executeAll<T>(operations: Array<() => T | Promise<T>>): Promise<T[]>;
+    /**
+     * Execute a Result-returning operation with concurrency limiting.
+     */
+    executeResult<T, E>(operation: () => Result<T, E> | AsyncResult<T, E>): AsyncResult<T, E | QueueFullError>;
+    /**
+     * Get current statistics.
+     */
+    getStats(): ConcurrencyLimiterStats;
+    /**
+     * Reset the concurrency limiter.
+     */
+    reset(): void;
+}
+/**
+ * Create a concurrency limiter.
+ *
+ * @param name - Name for the limiter (used in errors)
+ * @param config - Concurrency limiter configuration
+ * @returns A ConcurrencyLimiter instance
+ *
+ * @example
+ * ```typescript
+ * const limiter = createConcurrencyLimiter('db-pool', {
+ *   maxConcurrent: 10,
+ * });
+ *
+ * // Execute with concurrency control
+ * const results = await limiter.executeAll(
+ *   ids.map(id => () => fetchItem(id))
+ * );
+ * ```
+ */
+declare function createConcurrencyLimiter(name: string, config: ConcurrencyLimiterConfig): ConcurrencyLimiter;
+/**
+ * Configuration for combined rate + concurrency limiter.
+ */
+interface CombinedLimiterConfig {
+    /**
+     * Rate limiting configuration.
+     */
+    rate?: RateLimiterConfig;
+    /**
+     * Concurrency limiting configuration.
+     */
+    concurrency?: ConcurrencyLimiterConfig;
+}
+/**
+ * Create a combined rate + concurrency limiter.
+ *
+ * Operations are first rate-limited, then concurrency-limited.
+ *
+ * @param name - Name for the limiter
+ * @param config - Combined limiter configuration
+ * @returns An object with both limiters and a combined execute function
+ *
+ * @example
+ * ```typescript
+ * const limiter = createCombinedLimiter('api', {
+ *   rate: { maxPerSecond: 10 },
+ *   concurrency: { maxConcurrent: 5 },
+ * });
+ *
+ * const result = await limiter.execute(() => callApi());
+ * ```
+ */
+declare function createCombinedLimiter(name: string, config: CombinedLimiterConfig): {
+    rate?: RateLimiter;
+    concurrency?: ConcurrencyLimiter;
+    execute: <T>(operation: () => T | Promise<T>) => Promise<T>;
+};
+/**
+ * Preset configurations for common use cases.
+ */
+declare const rateLimiterPresets: {
+    /**
+     * Typical API rate limit (10 req/s).
+     */
+    readonly api: {
+        maxPerSecond: number;
+        burstCapacity: number;
+        strategy: "wait";
+    };
+    /**
+     * Database pool limit (concurrent connections).
+     */
+    readonly database: {
+        maxConcurrent: number;
+        strategy: "queue";
+        maxQueueSize: number;
+    };
+    /**
+     * Aggressive rate limit for external APIs (5 req/s).
+     */
+    readonly external: {
+        maxPerSecond: number;
+        burstCapacity: number;
+        strategy: "wait";
+    };
+};
+
+/**
+ * Workflow Versioning and Migration
+ *
+ * Handle schema changes when resuming workflows that were persisted
+ * with older step shapes.
+ *
+ * @example
+ * ```typescript
+ * import { createVersionedWorkflow } from '@jagreehal/workflow';
+ *
+ * const workflow = createVersionedWorkflow(
+ *   { fetchUser, chargeCard },
+ *   {
+ *     version: 2,
+ *     migrations: {
+ *       1: (state) => migrateV1ToV2(state),
+ *     },
+ *     resumeState: loadState(runId),
+ *   }
+ * );
+ * ```
+ */
+
+/**
+ * Version number type.
+ */
+type Version = number;
+/**
+ * Migration function that transforms state from one version to the next.
+ */
+type MigrationFn = (state: ResumeState) => ResumeState | Promise<ResumeState>;
+/**
+ * Map of migrations keyed by the source version.
+ * Migration at key N transforms state from version N to version N+1.
+ */
+type Migrations = Record<Version, MigrationFn>;
+/**
+ * Versioned state includes the version number.
+ */
+interface VersionedState {
+    version: Version;
+    state: ResumeState;
+}
+/**
+ * Configuration for versioned workflow.
+ */
+interface VersionedWorkflowConfig {
+    /**
+     * Current workflow version.
+     */
+    version: Version;
+    /**
+     * Migrations for upgrading old states.
+     * Key is the source version, value transforms to next version.
+     */
+    migrations?: Migrations;
+    /**
+     * Strict mode - fail if state version is higher than current.
+     * @default true
+     */
+    strictVersioning?: boolean;
+}
+/**
+ * Error when version migration fails.
+ */
+interface MigrationError {
+    type: "MIGRATION_ERROR";
+    fromVersion: Version;
+    toVersion: Version;
+    cause: unknown;
+}
+/**
+ * Error when state version is incompatible.
+ */
+interface VersionIncompatibleError {
+    type: "VERSION_INCOMPATIBLE";
+    stateVersion: Version;
+    currentVersion: Version;
+    reason: string;
+}
+/**
+ * Type guard for MigrationError.
+ */
+declare function isMigrationError(error: unknown): error is MigrationError;
+/**
+ * Type guard for VersionIncompatibleError.
+ */
+declare function isVersionIncompatibleError(error: unknown): error is VersionIncompatibleError;
+/**
+ * Migrate state from one version to another.
+ *
+ * @param state - The versioned state to migrate
+ * @param targetVersion - The target version
+ * @param migrations - Migration functions
+ * @returns The migrated state or an error
+ *
+ * @example
+ * ```typescript
+ * const migrated = await migrateState(
+ *   { version: 1, state: oldState },
+ *   3,
+ *   {
+ *     1: (s) => transformV1ToV2(s),
+ *     2: (s) => transformV2ToV3(s),
+ *   }
+ * );
+ * ```
+ */
+declare function migrateState(state: VersionedState, targetVersion: Version, migrations: Migrations): Promise<Result<VersionedState, MigrationError | VersionIncompatibleError>>;
+/**
+ * Create a versioned resume state loader.
+ *
+ * This wraps a state loader to automatically apply migrations
+ * when loading older state versions.
+ *
+ * @param config - Versioning configuration
+ * @returns A function that loads and migrates state
+ *
+ * @example
+ * ```typescript
+ * const loadVersionedState = createVersionedStateLoader({
+ *   version: 3,
+ *   migrations: {
+ *     1: migrateV1ToV2,
+ *     2: migrateV2ToV3,
+ *   },
+ * });
+ *
+ * // In workflow
+ * const workflow = createWorkflow(deps, {
+ *   resumeState: () => loadVersionedState(savedState),
+ * });
+ * ```
+ */
+declare function createVersionedStateLoader(config: VersionedWorkflowConfig): (versionedState: VersionedState | null | undefined) => Promise<Result<ResumeState | undefined, MigrationError | VersionIncompatibleError>>;
+/**
+ * Create versioned state from current resume state.
+ *
+ * Use this when saving state to storage.
+ *
+ * @param state - The current resume state
+ * @param version - The current workflow version
+ * @returns A versioned state object
+ *
+ * @example
+ * ```typescript
+ * const collector = createStepCollector();
+ * // ... run workflow ...
+ *
+ * const versionedState = createVersionedState(collector.getState(), 2);
+ * await db.saveWorkflowState(workflowId, versionedState);
+ * ```
+ */
+declare function createVersionedState(state: ResumeState, version: Version): VersionedState;
+/**
+ * Parse versioned state from JSON.
+ *
+ * Handles the serialization/deserialization of ResumeState with Map.
+ *
+ * @param json - The JSON string or parsed object
+ * @returns The versioned state or null if invalid
+ *
+ * @example
+ * ```typescript
+ * const json = await db.loadWorkflowState(workflowId);
+ * const versionedState = parseVersionedState(json);
+ * if (versionedState) {
+ *   const loader = createVersionedStateLoader(config);
+ *   const state = await loader(versionedState);
+ * }
+ * ```
+ */
+interface SerializedVersionedState {
+    version: number;
+    state: {
+        steps: Array<[string, ResumeStateEntry]>;
+    };
+}
+declare function parseVersionedState(json: string | SerializedVersionedState | null | undefined): VersionedState | null;
+/**
+ * Serialize versioned state to JSON.
+ *
+ * Converts the Map to an array for JSON serialization.
+ *
+ * @param state - The versioned state
+ * @returns JSON string
+ *
+ * @example
+ * ```typescript
+ * const json = stringifyVersionedState(versionedState);
+ * await db.saveWorkflowState(workflowId, json);
+ * ```
+ */
+declare function stringifyVersionedState(state: VersionedState): string;
+/**
+ * Create a migration that renames step keys.
+ *
+ * @param renames - Map of old key to new key
+ * @returns A migration function
+ *
+ * @example
+ * ```typescript
+ * const migrations = {
+ *   1: createKeyRenameMigration({
+ *     'user:fetch': 'user:load',
+ *     'order:create': 'order:submit',
+ *   }),
+ * };
+ * ```
+ */
+declare function createKeyRenameMigration(renames: Record<string, string>): MigrationFn;
+/**
+ * Create a migration that removes specific step keys.
+ *
+ * @param keysToRemove - Array of keys to remove
+ * @returns A migration function
+ *
+ * @example
+ * ```typescript
+ * const migrations = {
+ *   1: createKeyRemoveMigration(['deprecated:step', 'old:cache']),
+ * };
+ * ```
+ */
+declare function createKeyRemoveMigration(keysToRemove: string[]): MigrationFn;
+/**
+ * Create a migration that transforms step values.
+ *
+ * @param transforms - Map of key to transform function
+ * @returns A migration function
+ *
+ * @example
+ * ```typescript
+ * const migrations = {
+ *   1: createValueTransformMigration({
+ *     'user:fetch': (entry) => ({
+ *       ...entry,
+ *       result: entry.result.ok
+ *         ? ok({ ...entry.result.value, newField: 'default' })
+ *         : entry.result,
+ *     }),
+ *   }),
+ * };
+ * ```
+ */
+declare function createValueTransformMigration(transforms: Record<string, (entry: ResumeStateEntry) => ResumeStateEntry>): MigrationFn;
+/**
+ * Compose multiple migrations into a single migration.
+ *
+ * @param migrations - Array of migration functions
+ * @returns A single migration function that applies all migrations in order
+ *
+ * @example
+ * ```typescript
+ * const migrations = {
+ *   1: composeMigrations([
+ *     createKeyRenameMigration({ 'old': 'new' }),
+ *     createKeyRemoveMigration(['deprecated']),
+ *   ]),
+ * };
+ * ```
+ */
+declare function composeMigrations(migrations: MigrationFn[]): MigrationFn;
+
+/**
+ * Autotel Integration
+ *
+ * First-class OpenTelemetry spans and metrics from the workflow event stream
+ * using the autotel library.
+ *
+ * @example
+ * ```typescript
+ * import { createAutotelAdapter } from '@jagreehal/workflow/autotel';
+ * import { init } from 'autotel';
+ *
+ * // Initialize autotel
+ * init({ service: 'checkout-api' });
+ *
+ * // Create adapter
+ * const otel = createAutotelAdapter({ serviceName: 'checkout' });
+ *
+ * // Use with workflow
+ * const workflow = createWorkflow(deps, { onEvent: otel.handleEvent });
+ *
+ * // Automatic spans: workflow > step > retry attempts
+ * // Automatic metrics: step_duration, retry_count, error_rate
+ * ```
+ */
+
+/**
+ * Configuration for the autotel adapter.
+ */
+interface AutotelAdapterConfig {
+    /**
+     * Service name for spans (used as prefix).
+     */
+    serviceName?: string;
+    /**
+     * Whether to create spans for each step.
+     * @default true
+     */
+    createStepSpans?: boolean;
+    /**
+     * Whether to record metrics for steps.
+     * @default true
+     */
+    recordMetrics?: boolean;
+    /**
+     * Custom attributes to add to all spans.
+     */
+    defaultAttributes?: Record<string, string | number | boolean>;
+    /**
+     * Whether to record retry events as span events.
+     * @default true
+     */
+    recordRetryEvents?: boolean;
+    /**
+     * Whether to mark workflow errors as span errors.
+     * @default true
+     */
+    markErrorsOnSpan?: boolean;
+}
+/**
+ * Metrics collected by the adapter.
+ */
+interface AutotelMetrics {
+    stepDurations: Array<{
+        name: string;
+        durationMs: number;
+        success: boolean;
+        attributes?: Record<string, string | number | boolean>;
+    }>;
+    retryCount: number;
+    errorCount: number;
+    cacheHits: number;
+    cacheMisses: number;
+    /** Default attributes applied to all metrics */
+    defaultAttributes: Record<string, string | number | boolean>;
+}
+/**
+ * Autotel adapter interface.
+ */
+interface AutotelAdapter {
+    /**
+     * Handle workflow events (pass to onEvent option).
+     */
+    handleEvent: (event: WorkflowEvent<unknown>) => void;
+    /**
+     * Get current active spans count (for debugging).
+     */
+    getActiveSpansCount: () => {
+        workflows: number;
+        steps: number;
+    };
+    /**
+     * Get collected metrics.
+     */
+    getMetrics: () => AutotelMetrics;
+    /**
+     * Reset adapter state.
+     */
+    reset: () => void;
+}
+/**
+ * Create an autotel adapter for workflow observability.
+ *
+ * This adapter translates workflow events into metrics and tracking data.
+ * When autotel is installed and initialized, it will also create OpenTelemetry spans.
+ *
+ * @param config - Adapter configuration
+ * @returns An AutotelAdapter instance
+ *
+ * @example
+ * ```typescript
+ * import { createAutotelAdapter } from '@jagreehal/workflow/autotel';
+ *
+ * const otel = createAutotelAdapter({ serviceName: 'checkout' });
+ *
+ * const workflow = createWorkflow(deps, {
+ *   onEvent: otel.handleEvent,
+ * });
+ * ```
+ */
+declare function createAutotelAdapter(config?: AutotelAdapterConfig): AutotelAdapter;
+/**
+ * Create an event handler that integrates with autotel's trace() function.
+ *
+ * This is a higher-level integration that creates actual OpenTelemetry spans
+ * for each workflow and step when autotel is initialized.
+ *
+ * @param options - Configuration options
+ * @returns An event handler function
+ *
+ * @example
+ * ```typescript
+ * import { createAutotelEventHandler } from '@jagreehal/workflow/autotel';
+ * import { init } from 'autotel';
+ *
+ * init({ service: 'checkout-api' });
+ *
+ * const handler = createAutotelEventHandler({ serviceName: 'checkout' });
+ *
+ * const workflow = createWorkflow(deps, {
+ *   onEvent: handler,
+ * });
+ * ```
+ */
+declare function createAutotelEventHandler(options?: {
+    serviceName?: string;
+    includeStepDetails?: boolean;
+}): (event: WorkflowEvent<unknown>) => void;
+/**
+ * Wrapper type for autotel trace function.
+ * Use this when you want to explicitly type the autotel integration.
+ */
+type AutotelTraceFn = <T>(name: string, fn: (ctx: {
+    setAttribute: (key: string, value: unknown) => void;
+}) => T | Promise<T>) => T | Promise<T>;
+/**
+ * Create a workflow wrapper that adds autotel tracing.
+ *
+ * This creates a higher-order function that wraps workflow execution
+ * in an autotel trace span.
+ *
+ * @param traceFn - The autotel trace function
+ * @param options - Wrapper options
+ * @returns A workflow wrapper function
+ *
+ * @example
+ * ```typescript
+ * import { trace } from 'autotel';
+ * import { withAutotelTracing } from '@jagreehal/workflow/autotel';
+ *
+ * const traced = withAutotelTracing(trace, { serviceName: 'checkout' });
+ *
+ * const result = await traced('process-order', async () => {
+ *   return workflow(async (step) => {
+ *     // ... workflow logic
+ *   });
+ * });
+ * ```
+ */
+declare function withAutotelTracing(traceFn: AutotelTraceFn, options?: {
+    serviceName?: string;
+}): <T>(name: string, fn: () => T | Promise<T>, attributes?: Record<string, string | number | boolean>) => Promise<T>;
+
+/**
+ * @jagreehal/workflow/webhook
+ *
+ * Webhook and event trigger adapters for exposing workflows as HTTP endpoints.
+ * Framework-agnostic handlers that work with Express, Hono, Fastify, etc.
+ */
+
+/**
+ * Generic HTTP request representation.
+ * Abstracts away framework-specific request objects.
+ */
+interface WebhookRequest<Body = unknown> {
+    /** HTTP method (GET, POST, PUT, DELETE, etc.) */
+    method: string;
+    /** Request path (e.g., "/api/checkout") */
+    path: string;
+    /** Request headers */
+    headers: Record<string, string | string[] | undefined>;
+    /** Parsed request body (JSON) */
+    body: Body;
+    /** Query parameters */
+    query: Record<string, string | string[] | undefined>;
+    /** Path parameters (e.g., { id: "123" }) */
+    params: Record<string, string>;
+    /** Raw request object from framework (for advanced use cases) */
+    raw?: unknown;
+}
+/**
+ * Generic HTTP response representation.
+ */
+interface WebhookResponse<T = unknown> {
+    /** HTTP status code */
+    status: number;
+    /** Response headers */
+    headers?: Record<string, string>;
+    /** Response body (will be JSON serialized) */
+    body: T;
+}
+/**
+ * Error response body structure.
+ */
+interface ErrorResponseBody {
+    error: {
+        type: string;
+        message?: string;
+        details?: unknown;
+    };
+}
+/**
+ * Input validation result.
+ */
+type ValidationResult<T, E = string> = Result<T, E>;
+/**
+ * Standard validation error type.
+ */
+interface ValidationError {
+    type: "VALIDATION_ERROR";
+    message: string;
+    field?: string;
+    details?: unknown;
+}
+/**
+ * Type guard for ValidationError.
+ */
+declare function isValidationError(e: unknown): e is ValidationError;
+/**
+ * Configuration for creating a webhook handler.
+ *
+ * @template TInput - The validated input type
+ * @template TOutput - The workflow output type
+ * @template TError - The workflow error type
+ * @template TBody - The raw request body type
+ */
+interface WebhookHandlerConfig<TInput, TOutput, TError, TBody = unknown> {
+    /**
+     * Validate and transform the incoming request.
+     * Return ok(input) to proceed, or err(validationError) to reject.
+     *
+     * @param req - The incoming request
+     * @returns Validated input or validation error
+     */
+    validateInput: (req: WebhookRequest<TBody>) => ValidationResult<TInput, ValidationError> | Promise<ValidationResult<TInput, ValidationError>>;
+    /**
+     * Map workflow result to HTTP response.
+     * Called for both success and error cases.
+     *
+     * @param result - The workflow result
+     * @param req - The original request (for context)
+     * @returns HTTP response
+     */
+    mapResult: (result: Result<TOutput, TError | UnexpectedError>, req: WebhookRequest<TBody>) => WebhookResponse;
+    /**
+     * Optional: Map validation errors to HTTP response.
+     * Defaults to 400 Bad Request with error details.
+     *
+     * @param error - The validation error
+     * @param req - The original request
+     * @returns HTTP response
+     */
+    mapValidationError?: (error: ValidationError, req: WebhookRequest<TBody>) => WebhookResponse<ErrorResponseBody>;
+    /**
+     * Optional: Handle unexpected errors during request processing.
+     * Defaults to 500 Internal Server Error.
+     *
+     * @param error - The unexpected error
+     * @param req - The original request
+     * @returns HTTP response
+     */
+    mapUnexpectedError?: (error: unknown, req: WebhookRequest<TBody>) => WebhookResponse<ErrorResponseBody>;
+    /**
+     * Optional: Request middleware.
+     * Transform or enrich the request before validation.
+     *
+     * @param req - The incoming request
+     * @returns Transformed request
+     */
+    beforeValidation?: (req: WebhookRequest<TBody>) => WebhookRequest<TBody> | Promise<WebhookRequest<TBody>>;
+    /**
+     * Optional: Response middleware.
+     * Transform the response before sending.
+     *
+     * @param response - The response to send
+     * @param req - The original request
+     * @returns Transformed response
+     */
+    afterResponse?: (response: WebhookResponse, req: WebhookRequest<TBody>) => WebhookResponse | Promise<WebhookResponse>;
+}
+/**
+ * A webhook handler function that processes requests.
+ */
+type WebhookHandler<TBody = unknown> = (req: WebhookRequest<TBody>) => Promise<WebhookResponse>;
+/**
+ * Default validation error mapper.
+ * Returns 400 Bad Request with error details.
+ */
+declare function defaultValidationErrorMapper(error: ValidationError): WebhookResponse<ErrorResponseBody>;
+/**
+ * Default unexpected error mapper.
+ * Returns 500 Internal Server Error.
+ */
+declare function defaultUnexpectedErrorMapper(_error: unknown): WebhookResponse<ErrorResponseBody>;
+/**
+ * Create a webhook handler for a workflow.
+ *
+ * This factory creates an HTTP handler function that:
+ * 1. Validates the incoming request
+ * 2. Executes the workflow with the validated input
+ * 3. Maps the result to an HTTP response
+ *
+ * The handler is framework-agnostic and returns a standard response object.
+ * Use framework adapters (createExpressHandler, createHonoHandler, etc.) to
+ * integrate with specific frameworks.
+ *
+ * @template TInput - The validated input type passed to the workflow
+ * @template TOutput - The workflow output type
+ * @template TError - The workflow error type
+ * @template TBody - The raw request body type
+ * @template TDeps - The workflow dependencies type
+ *
+ * @param workflow - The workflow function to execute
+ * @param workflowFn - The workflow body function (step, deps, input) => output
+ * @param config - Handler configuration
+ * @returns A webhook handler function
+ *
+ * @example
+ * ```typescript
+ * const checkoutWorkflow = createWorkflow({ chargeCard, sendEmail });
+ *
+ * const handler = createWebhookHandler(
+ *   checkoutWorkflow,
+ *   async (step, deps, input: CheckoutInput) => {
+ *     const charge = await step(() => deps.chargeCard(input.amount));
+ *     await step(() => deps.sendEmail(input.email, charge.receiptUrl));
+ *     return { chargeId: charge.id };
+ *   },
+ *   {
+ *     validateInput: (req) => {
+ *       const { amount, email } = req.body;
+ *       if (!amount || !email) {
+ *         return err({ type: 'VALIDATION_ERROR', message: 'Missing required fields' });
+ *       }
+ *       return ok({ amount, email });
+ *     },
+ *     mapResult: (result) => {
+ *       if (result.ok) {
+ *         return { status: 200, body: result.value };
+ *       }
+ *       if (result.error === 'CARD_DECLINED') {
+ *         return { status: 402, body: { error: { type: 'CARD_DECLINED' } } };
+ *       }
+ *       return { status: 500, body: { error: { type: 'UNKNOWN' } } };
+ *     },
+ *   }
+ * );
+ *
+ * // Use with Express
+ * app.post('/checkout', async (req, res) => {
+ *   const response = await handler(toWebhookRequest(req));
+ *   res.status(response.status).json(response.body);
+ * });
+ * ```
+ */
+declare function createWebhookHandler<TInput, TOutput, TError, TBody = unknown, TDeps = unknown>(workflow: Workflow<TError, TDeps> | WorkflowStrict<TError, unknown, TDeps>, workflowFn: (step: Parameters<Parameters<Workflow<TError, TDeps>>[1]>[0], deps: TDeps, input: TInput) => TOutput | Promise<TOutput>, config: WebhookHandlerConfig<TInput, TOutput, TError, TBody>): WebhookHandler<TBody>;
+/**
+ * Configuration for a simple webhook handler without workflow.
+ */
+interface SimpleHandlerConfig<TInput, TOutput, TError, TBody = unknown> {
+    validateInput: (req: WebhookRequest<TBody>) => ValidationResult<TInput, ValidationError> | Promise<ValidationResult<TInput, ValidationError>>;
+    handler: (input: TInput, req: WebhookRequest<TBody>) => AsyncResult<TOutput, TError>;
+    mapResult: (result: Result<TOutput, TError>, req: WebhookRequest<TBody>) => WebhookResponse;
+    mapValidationError?: (error: ValidationError, req: WebhookRequest<TBody>) => WebhookResponse<ErrorResponseBody>;
+    mapUnexpectedError?: (error: unknown, req: WebhookRequest<TBody>) => WebhookResponse<ErrorResponseBody>;
+}
+/**
+ * Create a simple webhook handler without workflow orchestration.
+ * Useful for simple endpoints that don't need step-based error handling.
+ *
+ * @example
+ * ```typescript
+ * const handler = createSimpleHandler({
+ *   validateInput: (req) => {
+ *     const { id } = req.params;
+ *     if (!id) return err({ type: 'VALIDATION_ERROR', message: 'Missing id' });
+ *     return ok({ id });
+ *   },
+ *   handler: async ({ id }) => {
+ *     const user = await db.findUser(id);
+ *     return user ? ok(user) : err('NOT_FOUND' as const);
+ *   },
+ *   mapResult: (result) => {
+ *     if (result.ok) return { status: 200, body: result.value };
+ *     return { status: 404, body: { error: { type: 'NOT_FOUND' } } };
+ *   },
+ * });
+ * ```
+ */
+declare function createSimpleHandler<TInput, TOutput, TError, TBody = unknown>(config: SimpleHandlerConfig<TInput, TOutput, TError, TBody>): WebhookHandler<TBody>;
+/**
+ * Standard error mapping configuration.
+ */
+interface ErrorMapping<TError> {
+    /** The error value to match */
+    error: TError;
+    /** HTTP status code for this error */
+    status: number;
+    /** Optional custom message */
+    message?: string;
+}
+/**
+ * Create a result mapper from error mappings.
+ * Provides a declarative way to map workflow errors to HTTP responses.
+ *
+ * @param mappings - Array of error mappings
+ * @param defaultStatus - Default status for unmapped errors (default: 500)
+ * @returns A mapResult function for use in handler config
+ *
+ * @example
+ * ```typescript
+ * const mapResult = createResultMapper<CheckoutOutput, CheckoutError>([
+ *   { error: 'NOT_FOUND', status: 404, message: 'Resource not found' },
+ *   { error: 'CARD_DECLINED', status: 402, message: 'Payment failed' },
+ *   { error: 'RATE_LIMITED', status: 429, message: 'Too many requests' },
+ * ]);
+ *
+ * const handler = createWebhookHandler(workflow, workflowFn, {
+ *   validateInput,
+ *   mapResult,
+ * });
+ * ```
+ */
+declare function createResultMapper<TOutput, TError>(mappings: ErrorMapping<TError>[], options?: {
+    defaultStatus?: number;
+    successStatus?: number;
+}): (result: Result<TOutput, TError | UnexpectedError>) => WebhookResponse;
+/**
+ * Express-style request object (minimal interface).
+ */
+interface ExpressLikeRequest {
+    method: string;
+    path: string;
+    headers: Record<string, string | string[] | undefined>;
+    body: unknown;
+    query: Record<string, string | string[] | undefined>;
+    params: Record<string, string>;
+}
+/**
+ * Express-style response object (minimal interface).
+ */
+interface ExpressLikeResponse {
+    status(code: number): ExpressLikeResponse;
+    set(headers: Record<string, string>): ExpressLikeResponse;
+    json(body: unknown): void;
+}
+/**
+ * Convert an Express-like request to WebhookRequest.
+ *
+ * @param req - Express-like request object
+ * @returns WebhookRequest
+ *
+ * @example
+ * ```typescript
+ * app.post('/checkout', async (req, res) => {
+ *   const webhookReq = toWebhookRequest(req);
+ *   const response = await handler(webhookReq);
+ *   res.status(response.status).json(response.body);
+ * });
+ * ```
+ */
+declare function toWebhookRequest<TBody = unknown>(req: ExpressLikeRequest): WebhookRequest<TBody>;
+/**
+ * Send a WebhookResponse using an Express-like response object.
+ *
+ * @param res - Express-like response object
+ * @param response - WebhookResponse to send
+ *
+ * @example
+ * ```typescript
+ * app.post('/checkout', async (req, res) => {
+ *   const response = await handler(toWebhookRequest(req));
+ *   sendWebhookResponse(res, response);
+ * });
+ * ```
+ */
+declare function sendWebhookResponse(res: ExpressLikeResponse, response: WebhookResponse): void;
+/**
+ * Create an Express-compatible middleware from a webhook handler.
+ *
+ * @param handler - Webhook handler function
+ * @returns Express middleware function
+ *
+ * @example
+ * ```typescript
+ * const handler = createWebhookHandler(workflow, workflowFn, config);
+ * const middleware = createExpressHandler(handler);
+ * app.post('/checkout', middleware);
+ * ```
+ */
+declare function createExpressHandler<TBody = unknown>(handler: WebhookHandler<TBody>): (req: ExpressLikeRequest, res: ExpressLikeResponse) => Promise<void>;
+/**
+ * Create a validation error.
+ *
+ * @param message - Error message
+ * @param field - Optional field name
+ * @param details - Optional additional details
+ * @returns ValidationError
+ */
+declare function validationError(message: string, field?: string, details?: unknown): ValidationError;
+/**
+ * Create a required field validator.
+ *
+ * @param fields - Field names to validate
+ * @returns Validation function
+ *
+ * @example
+ * ```typescript
+ * const validateRequired = requireFields(['email', 'password']);
+ *
+ * const validateInput = (req) => {
+ *   const result = validateRequired(req.body);
+ *   if (!result.ok) return result;
+ *   return ok(req.body as LoginInput);
+ * };
+ * ```
+ */
+declare function requireFields(fields: string[]): (body: Record<string, unknown>) => ValidationResult<void, ValidationError>;
+/**
+ * Compose multiple validators into a single validator.
+ *
+ * @param validators - Validators to compose
+ * @returns Combined validator function
+ *
+ * @example
+ * ```typescript
+ * const validate = composeValidators(
+ *   requireFields(['email', 'password']),
+ *   validateEmailFormat,
+ *   validatePasswordStrength
+ * );
+ * ```
+ */
+declare function composeValidators<T>(...validators: Array<(input: T) => ValidationResult<void, ValidationError>>): (input: T) => ValidationResult<void, ValidationError>;
+/**
+ * Generic event message for queue-based triggers.
+ */
+interface EventMessage<T = unknown> {
+    /** Unique message ID */
+    id: string;
+    /** Event type/name */
+    type: string;
+    /** Event payload */
+    payload: T;
+    /** Event metadata */
+    metadata?: {
+        timestamp?: number;
+        source?: string;
+        correlationId?: string;
+        [key: string]: unknown;
+    };
+}
+/**
+ * Result of processing an event.
+ */
+interface EventProcessingResult {
+    /** Whether the event was processed successfully */
+    success: boolean;
+    /** Should the message be acknowledged (removed from queue)? */
+    ack: boolean;
+    /** Optional error details */
+    error?: {
+        type: string;
+        message?: string;
+        retryable?: boolean;
+    };
+}
+/**
+ * Configuration for event trigger handlers.
+ */
+interface EventTriggerConfig<TPayload, TOutput, TError> {
+    /** Validate the event payload */
+    validatePayload: (event: EventMessage<TPayload>) => ValidationResult<TPayload, ValidationError>;
+    /** Map workflow result to processing result */
+    mapResult: (result: Result<TOutput, TError | UnexpectedError>, event: EventMessage<TPayload>) => EventProcessingResult;
+    /** Optional: Determine if error is retryable */
+    isRetryable?: (error: TError | UnexpectedError) => boolean;
+}
+/**
+ * Event handler function type.
+ */
+type EventHandler<TPayload = unknown> = (event: EventMessage<TPayload>) => Promise<EventProcessingResult>;
+/**
+ * Create an event handler for queue-based triggers.
+ *
+ * @example
+ * ```typescript
+ * const handler = createEventHandler(
+ *   checkoutWorkflow,
+ *   async (step, deps, payload: CheckoutPayload) => {
+ *     const charge = await step(() => deps.chargeCard(payload.amount));
+ *     return { chargeId: charge.id };
+ *   },
+ *   {
+ *     validatePayload: (event) => {
+ *       if (!event.payload.amount) {
+ *         return err({ type: 'VALIDATION_ERROR', message: 'Missing amount' });
+ *       }
+ *       return ok(event.payload);
+ *     },
+ *     mapResult: (result) => ({
+ *       success: result.ok,
+ *       ack: result.ok || !isRetryableError(result.error),
+ *       error: result.ok ? undefined : { type: String(result.error) },
+ *     }),
+ *   }
+ * );
+ *
+ * // Use with SQS, RabbitMQ, etc.
+ * queue.consume(async (message) => {
+ *   const result = await handler(message);
+ *   if (result.ack) await message.ack();
+ *   else await message.nack();
+ * });
+ * ```
+ */
+declare function createEventHandler<TPayload, TOutput, TError, TDeps = unknown>(workflow: Workflow<TError, TDeps> | WorkflowStrict<TError, unknown, TDeps>, workflowFn: (step: Parameters<Parameters<Workflow<TError, TDeps>>[1]>[0], deps: TDeps, payload: TPayload) => TOutput | Promise<TOutput>, config: EventTriggerConfig<TPayload, TOutput, TError>): EventHandler<TPayload>;
+
+/**
+ * @jagreehal/workflow/policies
+ *
+ * Policy-Driven Step Middleware - Reusable bundles of StepOptions
+ * that can be composed and applied per-workflow or per-step.
+ */
+
+/**
+ * A policy is a partial StepOptions that can be merged with other policies.
+ */
+type Policy = Partial<StepOptions>;
+/**
+ * A policy factory that creates policies based on context.
+ */
+type PolicyFactory<T = void> = T extends void ? () => Policy : (context: T) => Policy;
+/**
+ * Named policy with metadata.
+ */
+interface NamedPolicy {
+    name: string;
+    policy: Policy;
+    description?: string;
+}
+/**
+ * Merge multiple policies into a single StepOptions object.
+ * Later policies override earlier ones for conflicting properties.
+ * Retry and timeout options are deep-merged.
+ *
+ * @param policies - Policies to merge (in order of precedence)
+ * @returns Merged StepOptions
+ *
+ * @example
+ * ```typescript
+ * const merged = mergePolicies(
+ *   timeoutPolicies.api,      // timeout: 5000ms
+ *   retryPolicies.transient,  // retry: 3 attempts
+ *   { name: 'fetch-user' }    // name override
+ * );
+ * ```
+ */
+declare function mergePolicies(...policies: Policy[]): StepOptions;
+/**
+ * Create a policy applier that merges base policies with step-specific options.
+ *
+ * @param basePolicies - Base policies to apply to all steps
+ * @returns A function that applies policies to step options
+ *
+ * @example
+ * ```typescript
+ * const applyPolicy = createPolicyApplier(
+ *   timeoutPolicies.api,
+ *   retryPolicies.transient
+ * );
+ *
+ * // In workflow
+ * const user = await step(
+ *   () => fetchUser(id),
+ *   applyPolicy({ name: 'fetch-user', key: 'user:' + id })
+ * );
+ * ```
+ */
+declare function createPolicyApplier(...basePolicies: Policy[]): (stepOptions?: StepOptions | string) => StepOptions;
+/**
+ * Create a named policy bundle for reuse across workflows.
+ *
+ * @param name - Policy bundle name
+ * @param policies - Policies to include in the bundle
+ * @returns Named policy object
+ */
+declare function createPolicyBundle(name: string, ...policies: Policy[]): NamedPolicy;
+/**
+ * Create a retry policy with the given options.
+ */
+declare function retryPolicy(options: RetryOptions): Policy;
+/**
+ * Pre-built retry policies for common scenarios.
+ */
+declare const retryPolicies: {
+    /**
+     * No retry - fail immediately on error.
+     */
+    readonly none: Partial<StepOptions>;
+    /**
+     * Quick retry for transient errors (3 attempts, fast backoff).
+     */
+    readonly transient: Partial<StepOptions>;
+    /**
+     * Standard retry for API calls (3 attempts, moderate backoff).
+     */
+    readonly standard: Partial<StepOptions>;
+    /**
+     * Aggressive retry for critical operations (5 attempts, longer backoff).
+     */
+    readonly aggressive: Partial<StepOptions>;
+    /**
+     * Fixed interval retry (useful for polling).
+     */
+    readonly fixed: (attempts: number, delayMs: number) => Policy;
+    /**
+     * Linear backoff retry.
+     */
+    readonly linear: (attempts: number, initialDelay: number) => Policy;
+    /**
+     * Custom retry policy builder.
+     */
+    readonly custom: (options: Partial<RetryOptions> & {
+        attempts: number;
+    }) => Policy;
+};
+/**
+ * Create a timeout policy with the given options.
+ */
+declare function timeoutPolicy(options: TimeoutOptions): Policy;
+/**
+ * Pre-built timeout policies for common scenarios.
+ */
+declare const timeoutPolicies: {
+    /**
+     * No timeout.
+     */
+    readonly none: Policy;
+    /**
+     * Fast timeout for quick operations (1 second).
+     */
+    readonly fast: Partial<StepOptions>;
+    /**
+     * Standard API timeout (5 seconds).
+     */
+    readonly api: Partial<StepOptions>;
+    /**
+     * Extended timeout for slower operations (30 seconds).
+     */
+    readonly extended: Partial<StepOptions>;
+    /**
+     * Long timeout for batch operations (2 minutes).
+     */
+    readonly long: Partial<StepOptions>;
+    /**
+     * Custom timeout in milliseconds.
+     */
+    readonly ms: (ms: number) => Policy;
+    /**
+     * Custom timeout in seconds.
+     */
+    readonly seconds: (seconds: number) => Policy;
+    /**
+     * Timeout with custom error.
+     */
+    readonly withError: <E>(ms: number, error: E) => Policy;
+    /**
+     * Timeout with AbortSignal support.
+     */
+    readonly withSignal: (ms: number) => Policy;
+};
+/**
+ * Pre-built combined policies for common service patterns.
+ */
+declare const servicePolicies: {
+    /**
+     * Policy for external HTTP APIs.
+     * - 5 second timeout
+     * - 3 retries with exponential backoff
+     */
+    readonly httpApi: StepOptions;
+    /**
+     * Policy for database operations.
+     * - 30 second timeout
+     * - 2 retries for transient errors
+     */
+    readonly database: StepOptions;
+    /**
+     * Policy for cache operations.
+     * - 1 second timeout
+     * - No retry (cache misses are not errors)
+     */
+    readonly cache: StepOptions;
+    /**
+     * Policy for message queue operations.
+     * - 30 second timeout
+     * - 5 retries with longer backoff
+     */
+    readonly messageQueue: StepOptions;
+    /**
+     * Policy for file operations.
+     * - 2 minute timeout
+     * - 3 retries
+     */
+    readonly fileSystem: StepOptions;
+    /**
+     * Policy for third-party services with rate limits.
+     * - 10 second timeout
+     * - 5 retries with linear backoff
+     */
+    readonly rateLimited: StepOptions;
+};
+/**
+ * Options for withPolicies workflow wrapper.
+ */
+interface WithPoliciesOptions {
+    /**
+     * Base policies applied to all steps.
+     */
+    policies: Policy[];
+    /**
+     * Step-specific policy overrides by name or key pattern.
+     */
+    overrides?: Record<string, Policy>;
+}
+/**
+ * Create step options with policies applied.
+ * This is a helper for applying policies inline.
+ *
+ * @param policies - Policies to apply
+ * @param stepOptions - Step-specific options
+ * @returns Merged StepOptions
+ *
+ * @example
+ * ```typescript
+ * const user = await step(
+ *   () => fetchUser(id),
+ *   withPolicy(servicePolicies.httpApi, { name: 'fetch-user' })
+ * );
+ * ```
+ */
+declare function withPolicy(policy: Policy, stepOptions?: StepOptions | string): StepOptions;
+/**
+ * Create step options with multiple policies applied.
+ *
+ * @param policies - Policies to apply (in order)
+ * @param stepOptions - Step-specific options
+ * @returns Merged StepOptions
+ *
+ * @example
+ * ```typescript
+ * const user = await step(
+ *   () => fetchUser(id),
+ *   withPolicies([timeoutPolicies.api, retryPolicies.standard], { name: 'fetch-user' })
+ * );
+ * ```
+ */
+declare function withPolicies(policies: Policy[], stepOptions?: StepOptions | string): StepOptions;
+/**
+ * Create a policy that applies conditionally.
+ *
+ * @param condition - Condition to check
+ * @param policy - Policy to apply if condition is true
+ * @param elsePolicy - Policy to apply if condition is false (optional)
+ * @returns The selected policy
+ *
+ * @example
+ * ```typescript
+ * const policy = conditionalPolicy(
+ *   isProduction,
+ *   servicePolicies.httpApi,     // Use in production
+ *   retryPolicies.none           // Skip in development
+ * );
+ * ```
+ */
+declare function conditionalPolicy(condition: boolean, policy: Policy, elsePolicy?: Policy): Policy;
+/**
+ * Create a policy based on environment.
+ *
+ * @param envPolicies - Map of environment names to policies
+ * @param currentEnv - Current environment (defaults to NODE_ENV)
+ * @param defaultPolicy - Default policy if environment not found
+ * @returns The selected policy
+ *
+ * @example
+ * ```typescript
+ * const policy = envPolicy({
+ *   production: servicePolicies.httpApi,
+ *   development: retryPolicies.none,
+ *   test: retryPolicies.none,
+ * });
+ * ```
+ */
+declare function envPolicy(envPolicies: Record<string, Policy>, currentEnv?: string, defaultPolicy?: Policy): Policy;
+/**
+ * A registry for managing named policies.
+ */
+interface PolicyRegistry {
+    /**
+     * Register a named policy.
+     */
+    register(name: string, policy: Policy): void;
+    /**
+     * Get a policy by name.
+     */
+    get(name: string): Policy | undefined;
+    /**
+     * Check if a policy exists.
+     */
+    has(name: string): boolean;
+    /**
+     * Get all registered policy names.
+     */
+    names(): string[];
+    /**
+     * Create step options using a registered policy.
+     */
+    apply(policyName: string, stepOptions?: StepOptions | string): StepOptions;
+}
+/**
+ * Create a policy registry for managing named policies.
+ *
+ * @returns PolicyRegistry instance
+ *
+ * @example
+ * ```typescript
+ * const registry = createPolicyRegistry();
+ *
+ * // Register policies
+ * registry.register('api', servicePolicies.httpApi);
+ * registry.register('db', servicePolicies.database);
+ *
+ * // Use in workflow
+ * const user = await step(
+ *   () => fetchUser(id),
+ *   registry.apply('api', { name: 'fetch-user' })
+ * );
+ * ```
+ */
+declare function createPolicyRegistry(): PolicyRegistry;
+/**
+ * Fluent builder for constructing step options.
+ */
+interface StepOptionsBuilder {
+    /**
+     * Set step name.
+     */
+    name(name: string): StepOptionsBuilder;
+    /**
+     * Set step key for caching.
+     */
+    key(key: string): StepOptionsBuilder;
+    /**
+     * Apply a policy.
+     */
+    policy(policy: Policy): StepOptionsBuilder;
+    /**
+     * Set timeout in milliseconds.
+     */
+    timeout(ms: number): StepOptionsBuilder;
+    /**
+     * Set retry options.
+     */
+    retry(options: RetryOptions): StepOptionsBuilder;
+    /**
+     * Set retry attempts (with default exponential backoff).
+     */
+    retries(attempts: number): StepOptionsBuilder;
+    /**
+     * Build the final StepOptions.
+     */
+    build(): StepOptions;
+}
+/**
+ * Create a fluent builder for step options.
+ *
+ * @returns StepOptionsBuilder instance
+ *
+ * @example
+ * ```typescript
+ * const options = stepOptions()
+ *   .name('fetch-user')
+ *   .key('user:123')
+ *   .timeout(5000)
+ *   .retries(3)
+ *   .build();
+ *
+ * const user = await step(() => fetchUser(id), options);
+ * ```
+ */
+declare function stepOptions(): StepOptionsBuilder;
+
+/**
+ * @jagreehal/workflow/persistence
+ *
+ * Pluggable Persistence Adapters for StepCache and ResumeState.
+ * Provides adapters for Redis, file system, and in-memory storage,
+ * plus helpers for JSON-safe serialization of causes.
+ */
+
+/**
+ * JSON-safe representation of a Result.
+ */
+interface SerializedResult {
+    ok: boolean;
+    value?: unknown;
+    error?: unknown;
+    cause?: SerializedCause;
+}
+/**
+ * JSON-safe representation of a cause value.
+ * Handles Error objects and other non-JSON-safe types.
+ */
+interface SerializedCause {
+    type: "error" | "value" | "undefined";
+    errorName?: string;
+    errorMessage?: string;
+    errorStack?: string;
+    value?: unknown;
+}
+/**
+ * JSON-safe representation of StepFailureMeta.
+ */
+interface SerializedMeta {
+    origin: "result" | "throw";
+    resultCause?: SerializedCause;
+    thrown?: SerializedCause;
+}
+/**
+ * JSON-safe representation of a ResumeStateEntry.
+ */
+interface SerializedEntry {
+    result: SerializedResult;
+    meta?: SerializedMeta;
+}
+/**
+ * JSON-safe representation of ResumeState.
+ */
+interface SerializedState {
+    version: number;
+    entries: Record<string, SerializedEntry>;
+    metadata?: Record<string, unknown>;
+}
+/**
+ * Serialize a cause value to a JSON-safe format.
+ */
+declare function serializeCause(cause: unknown): SerializedCause;
+/**
+ * Deserialize a cause value from JSON-safe format.
+ */
+declare function deserializeCause(serialized: SerializedCause): unknown;
+/**
+ * Serialize a Result to a JSON-safe format.
+ */
+declare function serializeResult(result: Result<unknown, unknown, unknown>): SerializedResult;
+/**
+ * Deserialize a Result from JSON-safe format.
+ */
+declare function deserializeResult(serialized: SerializedResult): Result<unknown, unknown, unknown>;
+/**
+ * Serialize StepFailureMeta to a JSON-safe format.
+ */
+declare function serializeMeta(meta: StepFailureMeta): SerializedMeta;
+/**
+ * Deserialize StepFailureMeta from JSON-safe format.
+ */
+declare function deserializeMeta(serialized: SerializedMeta): StepFailureMeta;
+/**
+ * Serialize a ResumeStateEntry to a JSON-safe format.
+ */
+declare function serializeEntry(entry: ResumeStateEntry): SerializedEntry;
+/**
+ * Deserialize a ResumeStateEntry from JSON-safe format.
+ */
+declare function deserializeEntry(serialized: SerializedEntry): ResumeStateEntry;
+/**
+ * Serialize ResumeState to a JSON-safe format.
+ */
+declare function serializeState(state: ResumeState, metadata?: Record<string, unknown>): SerializedState;
+/**
+ * Deserialize ResumeState from JSON-safe format.
+ */
+declare function deserializeState(serialized: SerializedState): ResumeState;
+/**
+ * Convert ResumeState to a JSON string.
+ */
+declare function stringifyState(state: ResumeState, metadata?: Record<string, unknown>): string;
+/**
+ * Parse ResumeState from a JSON string.
+ */
+declare function parseState(json: string): ResumeState;
+/**
+ * Options for the in-memory cache adapter.
+ */
+interface MemoryCacheOptions {
+    /**
+     * Maximum number of entries to store.
+     * Oldest entries are evicted when limit is reached.
+     */
+    maxSize?: number;
+    /**
+     * Time-to-live in milliseconds.
+     * Entries are automatically removed after this duration.
+     */
+    ttl?: number;
+}
+/**
+ * Create an in-memory StepCache with optional LRU eviction and TTL.
+ *
+ * @param options - Cache options
+ * @returns StepCache implementation
+ *
+ * @example
+ * ```typescript
+ * const cache = createMemoryCache({ maxSize: 1000, ttl: 60000 });
+ * const workflow = createWorkflow(deps, { cache });
+ * ```
+ */
+declare function createMemoryCache(options?: MemoryCacheOptions): StepCache;
+/**
+ * Options for the file system cache adapter.
+ */
+interface FileCacheOptions {
+    /**
+     * Directory to store cache files.
+     */
+    directory: string;
+    /**
+     * File extension for cache files.
+     * @default '.json'
+     */
+    extension?: string;
+    /**
+     * Custom file system interface (for testing or custom implementations).
+     */
+    fs?: FileSystemInterface;
+}
+/**
+ * Minimal file system interface for cache operations.
+ */
+interface FileSystemInterface {
+    readFile(path: string): Promise<string>;
+    writeFile(path: string, data: string): Promise<void>;
+    unlink(path: string): Promise<void>;
+    exists(path: string): Promise<boolean>;
+    readdir(path: string): Promise<string[]>;
+    mkdir(path: string, options?: {
+        recursive?: boolean;
+    }): Promise<void>;
+}
+/**
+ * Create a file system-based StepCache.
+ * Each step result is stored as a separate JSON file.
+ *
+ * @param options - Cache options
+ * @returns StepCache implementation (async operations wrapped in sync interface)
+ *
+ * @example
+ * ```typescript
+ * import * as fs from 'fs/promises';
+ *
+ * const cache = createFileCache({
+ *   directory: './workflow-cache',
+ *   fs: {
+ *     readFile: (path) => fs.readFile(path, 'utf-8'),
+ *     writeFile: (path, data) => fs.writeFile(path, data, 'utf-8'),
+ *     unlink: fs.unlink,
+ *     exists: async (path) => fs.access(path).then(() => true).catch(() => false),
+ *     readdir: fs.readdir,
+ *     mkdir: fs.mkdir,
+ *   },
+ * });
+ * ```
+ */
+declare function createFileCache(options: FileCacheOptions): StepCache & {
+    /** Initialize the cache directory. Call before using the cache. */
+    init(): Promise<void>;
+    /** Get a result asynchronously. */
+    getAsync(key: string): Promise<Result<unknown, unknown, unknown> | undefined>;
+    /** Set a result asynchronously. */
+    setAsync(key: string, result: Result<unknown, unknown, unknown>): Promise<void>;
+    /** Delete a result asynchronously. */
+    deleteAsync(key: string): Promise<boolean>;
+    /** Clear all results asynchronously. */
+    clearAsync(): Promise<void>;
+};
+/**
+ * Generic key-value store interface.
+ * Implement this for Redis, DynamoDB, etc.
+ */
+interface KeyValueStore {
+    get(key: string): Promise<string | null>;
+    set(key: string, value: string, options?: {
+        ttl?: number;
+    }): Promise<void>;
+    delete(key: string): Promise<boolean>;
+    exists(key: string): Promise<boolean>;
+    keys(pattern: string): Promise<string[]>;
+}
+/**
+ * Options for key-value store cache adapter.
+ */
+interface KVCacheOptions {
+    /**
+     * Key-value store implementation.
+     */
+    store: KeyValueStore;
+    /**
+     * Key prefix for all cache entries.
+     * @default 'workflow:'
+     */
+    prefix?: string;
+    /**
+     * Time-to-live in seconds for cache entries.
+     */
+    ttl?: number;
+}
+/**
+ * Create a StepCache backed by a key-value store (Redis, DynamoDB, etc.).
+ *
+ * @param options - Cache options
+ * @returns StepCache implementation with async methods
+ *
+ * @example
+ * ```typescript
+ * // With Redis
+ * import { createClient } from 'redis';
+ *
+ * const redis = createClient();
+ * await redis.connect();
+ *
+ * const cache = createKVCache({
+ *   store: {
+ *     get: (key) => redis.get(key),
+ *     set: (key, value, opts) => redis.set(key, value, { EX: opts?.ttl }),
+ *     delete: (key) => redis.del(key).then(n => n > 0),
+ *     exists: (key) => redis.exists(key).then(n => n > 0),
+ *     keys: (pattern) => redis.keys(pattern),
+ *   },
+ *   prefix: 'myapp:workflow:',
+ *   ttl: 3600, // 1 hour
+ * });
+ * ```
+ */
+declare function createKVCache(options: KVCacheOptions): StepCache & {
+    /** Get a result asynchronously. */
+    getAsync(key: string): Promise<Result<unknown, unknown, unknown> | undefined>;
+    /** Set a result asynchronously. */
+    setAsync(key: string, result: Result<unknown, unknown, unknown>): Promise<void>;
+    /** Check if key exists asynchronously. */
+    hasAsync(key: string): Promise<boolean>;
+    /** Delete a result asynchronously. */
+    deleteAsync(key: string): Promise<boolean>;
+    /** Clear all results asynchronously. */
+    clearAsync(): Promise<void>;
+};
+/**
+ * Interface for persisting workflow state.
+ */
+interface StatePersistence {
+    /**
+     * Save workflow state.
+     */
+    save(runId: string, state: ResumeState, metadata?: Record<string, unknown>): Promise<void>;
+    /**
+     * Load workflow state.
+     */
+    load(runId: string): Promise<ResumeState | undefined>;
+    /**
+     * Delete workflow state.
+     */
+    delete(runId: string): Promise<boolean>;
+    /**
+     * List all saved workflow IDs.
+     */
+    list(): Promise<string[]>;
+}
+/**
+ * Create a state persistence adapter using a key-value store.
+ *
+ * @param store - Key-value store implementation
+ * @param prefix - Key prefix for state entries
+ * @returns StatePersistence implementation
+ */
+declare function createStatePersistence(store: KeyValueStore, prefix?: string): StatePersistence;
+/**
+ * Create a cache that hydrates from persistent storage on first access.
+ *
+ * @param memoryCache - In-memory cache for fast access
+ * @param persistence - Persistent storage for durability
+ * @returns Hydrating cache implementation
+ */
+declare function createHydratingCache(memoryCache: StepCache, persistence: StatePersistence, runId: string): StepCache & {
+    hydrate(): Promise<void>;
+};
+
+/**
+ * @jagreehal/workflow/devtools
+ *
+ * Developer tools for workflow debugging, visualization, and analysis.
+ * Provides timeline rendering, run diffing, and live visualization.
+ */
+
+/**
+ * A recorded workflow run with events and metadata.
+ */
+interface WorkflowRun {
+    /** Unique identifier for this run */
+    id: string;
+    /** Workflow name */
+    name?: string;
+    /** Start timestamp */
+    startTime: number;
+    /** End timestamp (undefined if still running) */
+    endTime?: number;
+    /** Duration in milliseconds */
+    durationMs?: number;
+    /** Whether the workflow succeeded */
+    success?: boolean;
+    /** Error if the workflow failed */
+    error?: unknown;
+    /** All events from this run */
+    events: CollectableEvent[];
+    /** Custom metadata */
+    metadata?: Record<string, unknown>;
+}
+/**
+ * Difference between two workflow runs.
+ */
+interface RunDiff {
+    /** Steps that were added in the new run */
+    added: StepDiff[];
+    /** Steps that were removed from the new run */
+    removed: StepDiff[];
+    /** Steps that changed between runs */
+    changed: StepDiff[];
+    /** Steps that are identical */
+    unchanged: string[];
+    /** Overall status change */
+    statusChange?: {
+        from: "success" | "error" | "running";
+        to: "success" | "error" | "running";
+    };
+    /** Duration change in milliseconds */
+    durationChange?: number;
+}
+/**
+ * Information about a step difference.
+ */
+interface StepDiff {
+    /** Step name or key */
+    step: string;
+    /** Type of change */
+    type: "added" | "removed" | "status" | "duration" | "error";
+    /** Previous value (for changes) */
+    from?: unknown;
+    /** New value (for changes) */
+    to?: unknown;
+}
+/**
+ * Timeline entry for a step.
+ */
+interface TimelineEntry {
+    /** Step name */
+    name: string;
+    /** Step key (if any) */
+    key?: string;
+    /** Start time (relative to workflow start) */
+    startMs: number;
+    /** End time (relative to workflow start) */
+    endMs?: number;
+    /** Duration in milliseconds */
+    durationMs?: number;
+    /** Step status */
+    status: "pending" | "running" | "success" | "error" | "skipped" | "cached";
+    /** Error if failed */
+    error?: unknown;
+    /** Parent scope (for nested steps) */
+    parent?: string;
+    /** Retry attempt number */
+    attempt?: number;
+}
+/**
+ * Devtools configuration options.
+ */
+interface DevtoolsOptions extends VisualizerOptions {
+    /** Enable console logging of events */
+    logEvents?: boolean;
+    /** Maximum number of runs to keep in history */
+    maxHistory?: number;
+    /** Custom logger function */
+    logger?: (message: string) => void;
+}
+/**
+ * Devtools instance for workflow debugging.
+ */
+interface Devtools {
+    /** Handle a workflow event */
+    handleEvent: (event: WorkflowEvent<unknown>) => void;
+    /** Handle a decision event */
+    handleDecisionEvent: (event: DecisionStartEvent | DecisionBranchEvent | DecisionEndEvent) => void;
+    /** Get the current run */
+    getCurrentRun: () => WorkflowRun | undefined;
+    /** Get run history */
+    getHistory: () => WorkflowRun[];
+    /** Get a specific run by ID */
+    getRun: (id: string) => WorkflowRun | undefined;
+    /** Compare two runs */
+    diff: (runId1: string, runId2: string) => RunDiff | undefined;
+    /** Compare current run with a previous run */
+    diffWithPrevious: () => RunDiff | undefined;
+    /** Render current state */
+    render: () => string;
+    /** Render to a specific format */
+    renderAs: (format: OutputFormat) => string;
+    /** Render as Mermaid diagram */
+    renderMermaid: () => string;
+    /** Render as ASCII timeline */
+    renderTimeline: () => string;
+    /** Get timeline data for current run */
+    getTimeline: () => TimelineEntry[];
+    /** Clear all history */
+    clearHistory: () => void;
+    /** Reset current run */
+    reset: () => void;
+    /** Export run data as JSON */
+    exportRun: (runId?: string) => string;
+    /** Import run data from JSON */
+    importRun: (json: string) => WorkflowRun;
+}
+/**
+ * Create a devtools instance for workflow debugging.
+ *
+ * @example
+ * ```typescript
+ * const devtools = createDevtools({ workflowName: 'checkout' });
+ *
+ * const workflow = createWorkflow(deps, {
+ *   onEvent: devtools.handleEvent,
+ * });
+ *
+ * await workflow(async (step) => { ... });
+ *
+ * // Visualize
+ * console.log(devtools.render());
+ * console.log(devtools.renderMermaid());
+ *
+ * // Compare with previous run
+ * const diff = devtools.diffWithPrevious();
+ * ```
+ */
+declare function createDevtools(options?: DevtoolsOptions): Devtools;
+/**
+ * Render a run diff as a string.
+ */
+declare function renderDiff(diff: RunDiff): string;
+/**
+ * Quick visualization helper for a single workflow run.
+ */
+declare function quickVisualize(workflowFn: (handleEvent: (event: WorkflowEvent<unknown>) => void) => Promise<unknown>, options?: DevtoolsOptions): Promise<string>;
+/**
+ * Create an event handler that logs to console with pretty formatting.
+ */
+declare function createConsoleLogger(options?: {
+    prefix?: string;
+    colors?: boolean;
+}): (event: WorkflowEvent<unknown>) => void;
+
+/**
+ * @jagreehal/workflow/hitl
+ *
+ * Human-in-the-Loop Orchestration Helpers.
+ * Provides pollers, webhook handlers, and resume injectors
+ * for production-ready approval workflows.
+ */
+
+/**
+ * Options passed to the workflow factory by the HITL orchestrator.
+ */
+interface HITLWorkflowFactoryOptions {
+    /** Resume state for replaying completed steps */
+    resumeState?: ResumeState;
+    /** Event handler for tracking workflow events (required for HITL) */
+    onEvent: (event: WorkflowEvent<unknown>) => void;
+}
+/**
+ * Approval status returned from the approval store.
+ */
+type ApprovalStatus<T = unknown> = {
+    status: "pending";
+} | {
+    status: "approved";
+    value: T;
+    approvedBy?: string;
+    approvedAt?: number;
+} | {
+    status: "rejected";
+    reason: string;
+    rejectedBy?: string;
+    rejectedAt?: number;
+} | {
+    status: "expired";
+    expiredAt: number;
+};
+/**
+ * Interface for approval storage backends.
+ */
+interface ApprovalStore {
+    /**
+     * Get the status of an approval.
+     */
+    getApproval(key: string): Promise<ApprovalStatus>;
+    /**
+     * Create or update a pending approval request.
+     */
+    createApproval(key: string, options?: {
+        metadata?: Record<string, unknown>;
+        expiresAt?: number;
+        requestedBy?: string;
+    }): Promise<void>;
+    /**
+     * Grant an approval.
+     */
+    grantApproval<T>(key: string, value: T, options?: {
+        approvedBy?: string;
+    }): Promise<void>;
+    /**
+     * Reject an approval.
+     */
+    rejectApproval(key: string, reason: string, options?: {
+        rejectedBy?: string;
+    }): Promise<void>;
+    /**
+     * Cancel a pending approval.
+     */
+    cancelApproval(key: string): Promise<void>;
+    /**
+     * List all pending approvals.
+     */
+    listPending(options?: {
+        prefix?: string;
+    }): Promise<string[]>;
+}
+/**
+ * Saved workflow state for resumption.
+ */
+interface SavedWorkflowState {
+    /** Unique identifier for this workflow run */
+    runId: string;
+    /** Workflow name/type */
+    workflowName: string;
+    /** Resume state with step results */
+    resumeState: ResumeState;
+    /** Pending approval keys */
+    pendingApprovals: string[];
+    /** Input that was passed to the workflow */
+    input?: unknown;
+    /** Custom metadata */
+    metadata?: Record<string, unknown>;
+    /** When the workflow was started */
+    startedAt: number;
+    /** When the state was last updated */
+    updatedAt: number;
+}
+/**
+ * Interface for workflow state storage.
+ */
+interface WorkflowStateStore {
+    /**
+     * Save workflow state.
+     */
+    save(state: SavedWorkflowState): Promise<void>;
+    /**
+     * Load workflow state by run ID.
+     */
+    load(runId: string): Promise<SavedWorkflowState | undefined>;
+    /**
+     * Delete workflow state.
+     */
+    delete(runId: string): Promise<void>;
+    /**
+     * List all saved workflow states.
+     */
+    list(options?: {
+        workflowName?: string;
+        hasPendingApprovals?: boolean;
+    }): Promise<string[]>;
+    /**
+     * Find workflows waiting for a specific approval.
+     */
+    findByPendingApproval(approvalKey: string): Promise<string[]>;
+}
+/**
+ * Options for the HITL orchestrator.
+ */
+interface HITLOrchestratorOptions {
+    /** Approval store for managing approval states */
+    approvalStore: ApprovalStore;
+    /** Workflow state store for persisting workflow state */
+    workflowStateStore: WorkflowStateStore;
+    /** Default expiration time for approvals (in milliseconds) */
+    defaultExpirationMs?: number;
+    /** Logger function */
+    logger?: (message: string) => void;
+}
+/**
+ * Result of executing a workflow that may pause for approval.
+ * Uses unknown for error type since workflows add UnexpectedError to the union.
+ */
+type HITLExecutionResult<T, E> = {
+    status: "completed";
+    result: Result<T, E | unknown>;
+} | {
+    status: "paused";
+    runId: string;
+    pendingApprovals: string[];
+    reason?: string;
+} | {
+    status: "resumed";
+    runId: string;
+    result: Result<T, E | unknown>;
+};
+/**
+ * Poller configuration.
+ */
+interface PollerOptions {
+    /** Polling interval in milliseconds */
+    intervalMs: number;
+    /** Maximum number of polls (undefined = unlimited) */
+    maxPolls?: number;
+    /** Timeout for the entire polling operation */
+    timeoutMs?: number;
+    /** Callback when polling starts */
+    onPollStart?: () => void;
+    /** Callback when a poll completes */
+    onPollComplete?: (result: ApprovalStatus) => void;
+}
+/**
+ * Create an in-memory approval store for development/testing.
+ */
+declare function createMemoryApprovalStore(): ApprovalStore;
+/**
+ * Create an in-memory workflow state store for development/testing.
+ */
+declare function createMemoryWorkflowStateStore(): WorkflowStateStore;
+/**
+ * HITL orchestrator interface.
+ */
+interface HITLOrchestrator {
+    /**
+     * Execute a workflow that may pause for approvals.
+     * If the workflow pauses, state is automatically saved.
+     *
+     * The workflowFactory receives options including onEvent handler which MUST be
+     * passed to createWorkflow for HITL tracking to work.
+     */
+    execute<T, E, TInput>(workflowName: string, workflowFactory: (options: HITLWorkflowFactoryOptions) => Workflow<E, unknown>, workflowFn: (step: unknown, deps: unknown, input: TInput) => Promise<T>, input: TInput, options?: {
+        runId?: string;
+        metadata?: Record<string, unknown>;
+    }): Promise<HITLExecutionResult<T, E>>;
+    /**
+     * Resume a paused workflow after approvals have been granted.
+     */
+    resume<T, E, TInput>(runId: string, workflowFactory: (options: HITLWorkflowFactoryOptions) => Workflow<E, unknown>, workflowFn: (step: unknown, deps: unknown, input: TInput) => Promise<T>): Promise<HITLExecutionResult<T, E>>;
+    /**
+     * Grant an approval and automatically resume any waiting workflows.
+     */
+    grantApproval<T>(approvalKey: string, value: T, options?: {
+        approvedBy?: string;
+        autoResume?: boolean;
+    }): Promise<{
+        grantedAt: number;
+        resumedWorkflows: string[];
+    }>;
+    /**
+     * Reject an approval.
+     */
+    rejectApproval(approvalKey: string, reason: string, options?: {
+        rejectedBy?: string;
+    }): Promise<void>;
+    /**
+     * Poll for an approval to be granted.
+     */
+    pollApproval<T>(approvalKey: string, options?: PollerOptions): Promise<ApprovalStatus<T>>;
+    /**
+     * Get the status of a workflow run.
+     */
+    getWorkflowStatus(runId: string): Promise<SavedWorkflowState | undefined>;
+    /**
+     * List all pending workflows.
+     */
+    listPendingWorkflows(workflowName?: string): Promise<string[]>;
+    /**
+     * Clean up completed workflows older than the specified age.
+     */
+    cleanup(maxAgeMs: number): Promise<number>;
+}
+/**
+ * Create a HITL orchestrator for managing approval workflows.
+ *
+ * @example
+ * ```typescript
+ * const orchestrator = createHITLOrchestrator({
+ *   approvalStore: createMemoryApprovalStore(),
+ *   workflowStateStore: createMemoryWorkflowStateStore(),
+ * });
+ *
+ * // Execute workflow - IMPORTANT: pass onEvent to createWorkflow!
+ * const result = await orchestrator.execute(
+ *   'order-approval',
+ *   ({ resumeState, onEvent }) => createWorkflow(deps, { resumeState, onEvent }),
+ *   async (step, deps, input) => {
+ *     const order = await step(() => deps.createOrder(input));
+ *     const approval = await step(() => deps.requireApproval(order.id), { key: `approval:${order.id}` });
+ *     await step(() => deps.processOrder(order.id));
+ *     return { orderId: order.id, approvedBy: approval.approvedBy };
+ *   },
+ *   { items: [...], total: 100 }
+ * );
+ *
+ * if (result.status === 'paused') {
+ *   console.log(`Workflow paused, waiting for: ${result.pendingApprovals}`);
+ * }
+ *
+ * // Later, grant approval
+ * await orchestrator.grantApproval(
+ *   `approval:${orderId}`,
+ *   { approvedBy: 'manager@example.com' },
+ *   { autoResume: true }
+ * );
+ * ```
+ */
+declare function createHITLOrchestrator(options: HITLOrchestratorOptions): HITLOrchestrator;
+/**
+ * Approval webhook request body.
+ */
+interface ApprovalWebhookRequest {
+    /** Approval key */
+    key: string;
+    /** Action: approve, reject, or cancel */
+    action: "approve" | "reject" | "cancel";
+    /** Value to inject (for approve) */
+    value?: unknown;
+    /** Reason (for reject) */
+    reason?: string;
+    /** Who performed this action */
+    actorId?: string;
+}
+/**
+ * Approval webhook response.
+ */
+interface ApprovalWebhookResponse {
+    success: boolean;
+    message: string;
+    data?: {
+        key: string;
+        action: string;
+        timestamp: number;
+    };
+}
+/**
+ * Create a webhook handler for approval actions.
+ *
+ * @example
+ * ```typescript
+ * const handleApproval = createApprovalWebhookHandler(approvalStore);
+ *
+ * // Express
+ * app.post('/api/approvals', async (req, res) => {
+ *   const result = await handleApproval(req.body);
+ *   res.json(result);
+ * });
+ * ```
+ */
+declare function createApprovalWebhookHandler(store: ApprovalStore): (request: ApprovalWebhookRequest) => Promise<ApprovalWebhookResponse>;
+/**
+ * Create an approval checker function for use in approval steps.
+ * This wraps the approval store with the standard checkApproval interface.
+ *
+ * @example
+ * ```typescript
+ * const checkApproval = createApprovalChecker(approvalStore);
+ *
+ * const requireManagerApproval = createApprovalStep<{ approvedBy: string }>({
+ *   key: 'manager-approval',
+ *   checkApproval: checkApproval('manager-approval'),
+ *   pendingReason: 'Waiting for manager approval',
+ * });
+ * ```
+ */
+declare function createApprovalChecker<T>(store: ApprovalStore): (key: string) => () => Promise<{
+    status: "pending";
+} | {
+    status: "approved";
+    value: T;
+} | {
+    status: "rejected";
+    reason: string;
+}>;
+
+/**
+ * @jagreehal/workflow/testing
+ *
+ * Deterministic Workflow Testing Harness.
+ * Provides tools for scripting step outcomes and asserting workflow behavior.
+ */
+
+/**
+ * A scripted outcome for a step.
+ */
+type ScriptedOutcome<T = unknown, E = unknown> = {
+    type: "ok";
+    value: T;
+} | {
+    type: "err";
+    error: E;
+} | {
+    type: "throw";
+    error: unknown;
+};
+/**
+ * Step invocation record.
+ */
+interface StepInvocation {
+    /** Step name */
+    name?: string;
+    /** Step key */
+    key?: string;
+    /** Invocation order (0-indexed) */
+    order: number;
+    /** Timestamp when step was invoked */
+    timestamp: number;
+    /** Duration in milliseconds */
+    durationMs?: number;
+    /** Result of the step */
+    result?: Result<unknown, unknown>;
+    /** Whether the step was from cache */
+    cached?: boolean;
+}
+/**
+ * Assertion result.
+ */
+interface AssertionResult {
+    passed: boolean;
+    message: string;
+    expected?: unknown;
+    actual?: unknown;
+}
+/**
+ * Test harness options.
+ */
+interface TestHarnessOptions {
+    /** Whether to record step invocations */
+    recordInvocations?: boolean;
+    /** Custom clock for deterministic timing */
+    clock?: () => number;
+}
+/**
+ * Mock step function that returns scripted outcomes.
+ */
+type MockStep<E> = {
+    /** Execute with a Result-returning operation */
+    <T, StepE extends E>(operation: () => Result<T, StepE> | AsyncResult<T, StepE>, options?: StepOptions | string): Promise<T>;
+    /** Execute with a direct Result */
+    <T, StepE extends E>(result: Result<T, StepE> | AsyncResult<T, StepE>, options?: StepOptions | string): Promise<T>;
+    /** step.try for catching throws */
+    try: <T, Err extends E>(operation: () => T | Promise<T>, options: {
+        error: Err;
+        name?: string;
+        key?: string;
+    } | {
+        onError: (cause: unknown) => Err;
+        name?: string;
+        key?: string;
+    }) => Promise<T>;
+};
+/**
+ * Workflow test harness interface.
+ */
+interface WorkflowHarness<E, Deps> {
+    /**
+     * Script step outcomes in order.
+     * Each outcome will be returned for the corresponding step invocation.
+     */
+    script(outcomes: ScriptedOutcome[]): void;
+    /**
+     * Script a specific step outcome by name or key.
+     */
+    scriptStep(nameOrKey: string, outcome: ScriptedOutcome): void;
+    /**
+     * Run the workflow with scripted outcomes.
+     */
+    run<T>(fn: (step: MockStep<E>, deps: Deps) => Promise<T>): Promise<Result<T, E | unknown>>;
+    /**
+     * Run the workflow with input.
+     */
+    runWithInput<T, TInput>(input: TInput, fn: (step: MockStep<E>, deps: Deps, input: TInput) => Promise<T>): Promise<Result<T, E | unknown>>;
+    /**
+     * Get recorded step invocations.
+     */
+    getInvocations(): StepInvocation[];
+    /**
+     * Assert that steps were invoked in order.
+     */
+    assertSteps(expectedNames: string[]): AssertionResult;
+    /**
+     * Assert that a step was invoked with specific options.
+     */
+    assertStepCalled(nameOrKey: string): AssertionResult;
+    /**
+     * Assert that a step was NOT invoked.
+     */
+    assertStepNotCalled(nameOrKey: string): AssertionResult;
+    /**
+     * Assert the workflow result.
+     */
+    assertResult<T>(result: Result<T, unknown>, expected: Result<T, unknown>): AssertionResult;
+    /**
+     * Clear all state for a new test.
+     */
+    reset(): void;
+}
+/**
+ * Create a test harness for a workflow.
+ *
+ * @example
+ * ```typescript
+ * const harness = createWorkflowHarness({ fetchUser, chargeCard });
+ *
+ * // Script step outcomes
+ * harness.script([
+ *   { type: 'ok', value: { id: '1', name: 'Alice' } },
+ *   { type: 'ok', value: { transactionId: 'tx_123' } },
+ * ]);
+ *
+ * // Run the workflow
+ * const result = await harness.run(async (step, { fetchUser, chargeCard }) => {
+ *   const user = await step(() => fetchUser('1'), 'fetch-user');
+ *   const charge = await step(() => chargeCard(100), 'charge-card');
+ *   return { user, charge };
+ * });
+ *
+ * // Assert
+ * expect(result.ok).toBe(true);
+ * harness.assertSteps(['fetch-user', 'charge-card']);
+ * ```
+ */
+declare function createWorkflowHarness<Deps extends Record<string, AnyResultFn$1>>(deps: Deps, options?: TestHarnessOptions): WorkflowHarness<ErrorsOfDeps$1<Deps>, Deps>;
+/**
+ * Create a mock Result-returning function.
+ *
+ * @example
+ * ```typescript
+ * const fetchUser = createMockFn<User, 'NOT_FOUND'>();
+ *
+ * fetchUser.returns(ok({ id: '1', name: 'Alice' }));
+ * // or
+ * fetchUser.returnsOnce(ok({ id: '1', name: 'Alice' }));
+ * fetchUser.returnsOnce(err('NOT_FOUND'));
+ * ```
+ */
+declare function createMockFn<T, E>(): MockFunction<T, E>;
+/**
+ * Mock function interface.
+ */
+interface MockFunction<T, E> {
+    (...args: unknown[]): AsyncResult<T, E>;
+    /** Set the default return value */
+    returns(result: Result<T, E>): MockFunction<T, E>;
+    /** Queue a return value for the next call */
+    returnsOnce(result: Result<T, E>): MockFunction<T, E>;
+    /** Get all call arguments */
+    getCalls(): unknown[][];
+    /** Get the number of times the function was called */
+    getCallCount(): number;
+    /** Reset the mock */
+    reset(): void;
+}
+/**
+ * Workflow snapshot for comparison.
+ */
+interface WorkflowSnapshot {
+    /** Step invocations */
+    invocations: StepInvocation[];
+    /** Final result */
+    result: Result<unknown, unknown>;
+    /** Events emitted */
+    events?: WorkflowEvent<unknown>[];
+    /** Total duration */
+    durationMs?: number;
+}
+/**
+ * Create a snapshot of a workflow execution.
+ */
+declare function createSnapshot(invocations: StepInvocation[], result: Result<unknown, unknown>, events?: WorkflowEvent<unknown>[]): WorkflowSnapshot;
+/**
+ * Compare two workflow snapshots.
+ */
+declare function compareSnapshots(snapshot1: WorkflowSnapshot, snapshot2: WorkflowSnapshot): {
+    equal: boolean;
+    differences: string[];
+};
+/**
+ * Create a deterministic clock for testing.
+ */
+declare function createTestClock(startTime?: number): {
+    now: () => number;
+    advance: (ms: number) => void;
+    set: (time: number) => void;
+    reset: () => void;
+};
+/**
+ * Helper to create ok outcomes.
+ */
+declare function okOutcome<T>(value: T): ScriptedOutcome<T, never>;
+/**
+ * Helper to create err outcomes.
+ */
+declare function errOutcome<E>(error: E): ScriptedOutcome<never, E>;
+/**
+ * Helper to create throw outcomes.
+ */
+declare function throwOutcome(error: unknown): ScriptedOutcome<never, never>;
+
+export { AnyResultFn$1 as AnyResultFn, type ApprovalStatus, type ApprovalStore, type ApprovalWebhookRequest, type ApprovalWebhookResponse, type AssertionResult, AsyncResult, type AutotelAdapter, type AutotelAdapterConfig, type AutotelMetrics, type AutotelTraceFn, type CircuitBreaker, type CircuitBreakerConfig, type CircuitBreakerStats, CircuitOpenError, type CircuitState, type CombinedLimiterConfig, type CompensationAction, type ConcurrencyLimiter, type ConcurrencyLimiterConfig, type ConcurrencyLimiterStats, type ConditionalContext, type ConditionalOptions, type Devtools, type DevtoolsOptions, type ErrorMapping, type ErrorResponseBody, ErrorsOfDeps$1 as ErrorsOfDeps, type EventHandler, type EventMessage, type EventProcessingResult, type EventTriggerConfig, type ExpressLikeRequest, type ExpressLikeResponse, type FileCacheOptions, type FileSystemInterface, type HITLExecutionResult, type HITLOrchestrator, type HITLOrchestratorOptions, type HITLWorkflowFactoryOptions, type KVCacheOptions, type KeyValueStore, type MemoryCacheOptions, type MigrationError, type MigrationFn, type Migrations, type MockFunction, type MockStep, type NamedPolicy, type Policy, type PolicyFactory, type PolicyRegistry, type PollerOptions, type QueueFullError, type RateLimitExceededError, type RateLimiter, type RateLimiterConfig, type RateLimiterStats, Result, ResumeState, ResumeStateEntry, RetryOptions, type RunDiff, type SagaCompensationError, type SagaContext, type SagaEvent, type SagaResult, type SagaStepOptions, type SagaWorkflowOptions, type SavedWorkflowState, type ScriptedOutcome, type SerializedCause, type SerializedEntry, type SerializedMeta, type SerializedResult, type SerializedState, type SimpleHandlerConfig, type StatePersistence, StepCache, type StepDiff, type StepInvocation, StepOptions, type StepOptionsBuilder, type TestHarnessOptions, type TimelineEntry, TimeoutOptions, UnexpectedError, type ValidationError, type ValidationResult, type Version, type VersionIncompatibleError, type VersionedState, type VersionedWorkflowConfig, type WebhookHandler, type WebhookHandlerConfig, type WebhookRequest, type WebhookResponse, type WithPoliciesOptions, Workflow, WorkflowEvent, type WorkflowHarness, type WorkflowRun, type WorkflowSnapshot, type WorkflowStateStore, WorkflowStrict, circuitBreakerPresets, compareSnapshots, composeMigrations, composeValidators, conditionalPolicy, createApprovalChecker, createApprovalWebhookHandler, createAutotelAdapter, createAutotelEventHandler, createCircuitBreaker, createCombinedLimiter, createConcurrencyLimiter, createConditionalHelpers, createConsoleLogger, createDevtools, createEventHandler, createExpressHandler, createFileCache, createHITLOrchestrator, createHydratingCache, createKVCache, createKeyRemoveMigration, createKeyRenameMigration, createMemoryApprovalStore, createMemoryCache, createMemoryWorkflowStateStore, createMockFn, createPolicyApplier, createPolicyBundle, createPolicyRegistry, createRateLimiter, createResultMapper, createSagaWorkflow, createSimpleHandler, createSnapshot, createStatePersistence, createTestClock, createValueTransformMigration, createVersionedState, createVersionedStateLoader, createWebhookHandler, createWorkflowHarness, defaultUnexpectedErrorMapper, defaultValidationErrorMapper, deserializeCause, deserializeEntry, deserializeMeta, deserializeResult, deserializeState, envPolicy, errOutcome, isCircuitOpenError, isMigrationError, isQueueFullError, isRateLimitExceededError, isSagaCompensationError, isValidationError, isVersionIncompatibleError, mergePolicies, migrateState, okOutcome, parseState, parseVersionedState, quickVisualize, rateLimiterPresets, renderDiff, requireFields, retryPolicies, retryPolicy, runSaga, sendWebhookResponse, serializeCause, serializeEntry, serializeMeta, serializeResult, serializeState, servicePolicies, stepOptions, stringifyState, stringifyVersionedState, throwOutcome, timeoutPolicies, timeoutPolicy, toWebhookRequest, unless, unlessOr, validationError, when, whenOr, withAutotelTracing, withPolicies, withPolicy };