awaitly 1.35.0 → 2.0.0

package/dist/persistence-entry-B-8PjnSR.d.cts

@@ -1,831 +0,0 @@
-import { R as Result, f as ErrorOf, ae as WorkflowEvent, av as StepFailureMeta, af as RunStep, ai as BoundSteps, c as AsyncResult, C as CauseOf } from './run-entry-DGs0tySr.cjs';
-import { S as StreamStore } from './types-C5jLEUqY.cjs';
-import { StandardSchemaV1 } from '@standard-schema/spec';
-import { UnexpectedError } from './errors.cjs';
-
-/**
- * awaitly/persistence
- *
- * Simplified Persistence API for workflow snapshots.
- * Provides JSON-serializable snapshot format and store adapters.
- */
-
-/**
- * Enforce JSON-safety at type level.
- * Only allows values that can be safely serialized with JSON.stringify.
- */
-type JSONValue = null | boolean | number | string | JSONValue[] | {
-    [k: string]: JSONValue;
-};
-/**
- * Canonical error wire format - handles both Error instances and thrown non-Errors.
- * This is the single source of truth for serialized errors in snapshots.
- */
-type SerializedCause = {
-    type: "error";
-    name: string;
-    message: string;
-    stack?: string;
-    cause?: SerializedCause;
-} | {
-    type: "thrown";
-    originalType?: string;
-    value?: JSONValue;
-    stringRepresentation: string;
-    truncated?: true;
-};
-/**
- * Single source of truth for step outcome (no error/cause confusion).
- * Uses discriminated union with `ok` field.
- */
-type StepResult = {
-    ok: true;
-    value: JSONValue;
-} | {
-    ok: false;
-    error: JSONValue;
-    cause: SerializedCause;
-    meta?: {
-        origin: "result" | "throw";
-    };
-};
-/**
- * JSON-serializable workflow snapshot.
- * Designed to be passed directly to JSON.stringify without special handling.
- *
- * @example
- * ```typescript
- * // Persist
- * localStorage.setItem('wf-123', JSON.stringify(wf.getSnapshot()));
- *
- * // Restore (safe pattern - storage can be empty/corrupt)
- * const raw = localStorage.getItem('wf-123');
- * const snapshot = raw ? JSON.parse(raw) : null;
- * createWorkflow(deps, { snapshot });  // null = fresh start
- * ```
- */
-interface WorkflowSnapshot {
-    /** Snapshot format version (literal type - bump when shape changes) */
-    formatVersion: 1;
-    /** Workflow name (from createWorkflow first argument). */
-    workflowName?: string;
-    /** Step results keyed by step ID. Uses Object.create(null) internally. */
-    steps: Record<string, StepResult>;
-    /** Execution state metadata */
-    execution: {
-        status: "running" | "completed" | "failed";
-        /** ISO timestamp (UTC toISOString()) */
-        lastUpdated: string;
-        /** ISO timestamp if finished */
-        completedAt?: string;
-        /**
-         * For paused/running workflows: the step key of the current step.
-         * Aligns with Workflow Diagram DSL step state ids (see awaitly/workflow diagram-dsl)
-         * so visualizers can highlight the current node.
-         */
-        currentStepId?: string;
-    };
-    /** Optional metadata for workflow identification and replay */
-    metadata?: {
-        /** Detect wrong snapshot for wrong workflow */
-        workflowId?: string;
-        /** Optional: detect definition changes (user-supplied, advisory only) */
-        definitionHash?: string;
-        /** Original input for replay */
-        input?: JSONValue;
-        [key: string]: JSONValue | undefined;
-    };
-    /** Warnings for lossy serialization (keeps step results pure) */
-    warnings?: Array<{
-        type: "lossy_value";
-        stepId: string;
-        path: string;
-        reason: "non-json" | "circular" | "encode-failed";
-    }>;
-}
-/**
- * Warning entry for lossy value serialization.
- */
-type SnapshotWarning = NonNullable<WorkflowSnapshot["warnings"]>[number];
-/**
- * Error thrown when snapshot structure is invalid.
- */
-declare class SnapshotFormatError extends Error {
-    readonly errors: string[];
-    constructor(message: string, errors?: string[]);
-}
-/**
- * Error thrown when snapshot doesn't match workflow (unknown steps, workflowId mismatch).
- */
-declare class SnapshotMismatchError extends Error {
-    readonly mismatchType: "unknown_steps" | "workflow_id" | "definition_hash";
-    readonly details?: {
-        unknownSteps?: string[];
-        snapshotWorkflowId?: string;
-        expectedWorkflowId?: string;
-        snapshotHash?: string;
-        expectedHash?: string;
-    } | undefined;
-    constructor(message: string, mismatchType: "unknown_steps" | "workflow_id" | "definition_hash", details?: {
-        unknownSteps?: string[];
-        snapshotWorkflowId?: string;
-        expectedWorkflowId?: string;
-        snapshotHash?: string;
-        expectedHash?: string;
-    } | undefined);
-}
-/**
- * Error thrown when decode fails during restore.
- */
-declare class SnapshotDecodeError extends Error {
-    readonly stepId: string;
-    readonly originalError?: unknown | undefined;
-    constructor(message: string, stepId: string, originalError?: unknown | undefined);
-}
-/**
- * Light check to see if an object looks like a WorkflowSnapshot.
- * Cheap check for basic structure - use validateSnapshot() for full validation.
- *
- * @example
- * ```typescript
- * const raw = JSON.parse(localStorage.getItem('wf-123') || 'null');
- * if (looksLikeWorkflowSnapshot(raw)) {
- *   createWorkflow(deps, { snapshot: raw });
- * }
- * ```
- */
-declare function looksLikeWorkflowSnapshot(obj: unknown): obj is WorkflowSnapshot;
-/**
- * Type guard for WorkflowSnapshot. Same as looksLikeWorkflowSnapshot; use for consistent naming with isResumeState / isSerializedResumeState.
- */
-declare const isWorkflowSnapshot: typeof looksLikeWorkflowSnapshot;
-/**
- * Full validation with detailed errors.
- * Returns either a validated snapshot or an array of validation errors.
- */
-declare function validateSnapshot(obj: unknown): {
-    valid: true;
-    snapshot: WorkflowSnapshot;
-} | {
-    valid: false;
-    errors: string[];
-};
-/**
- * Throwing helper for cleaner code.
- * Validates a snapshot and throws SnapshotFormatError if invalid.
- *
- * @throws {SnapshotFormatError} If snapshot is invalid
- */
-declare function assertValidSnapshot(obj: unknown): WorkflowSnapshot;
-/**
- * Merge two snapshots (for incremental updates).
- * Delta steps overwrite base steps; execution from delta; metadata shallow merge.
- */
-declare function mergeSnapshots(base: WorkflowSnapshot, delta: WorkflowSnapshot): WorkflowSnapshot;
-/**
- * Serialize an Error object to SerializedCause format.
- * Preserves Error.cause recursively.
- */
-declare function serializeError(error: Error): SerializedCause;
-/**
- * Serialize a non-Error thrown value to SerializedCause format.
- */
-declare function serializeThrown(value: unknown): SerializedCause;
-/**
- * Deserialize a SerializedCause back to its original form.
- */
-declare function deserializeCauseNew(serialized: SerializedCause): unknown;
-/**
- * Simplified store interface for workflow snapshot persistence.
- * Works directly with WorkflowSnapshot objects.
- *
- * Adapters may implement an extended contract (see awaitly/workflow): save can accept
- * WorkflowSnapshot | ResumeState; load can return WorkflowSnapshot | ResumeState | null.
- * Use isWorkflowSnapshot / isSerializedResumeState and serializeResumeState / deserializeResumeState
- * when branching. For type-safe restore, use store.loadResumeState(id) or toResumeState(await store.load(id)).
- *
- * @example
- * ```typescript
- * import { postgres } from 'awaitly-postgres';
- * import { createWorkflow } from 'awaitly/workflow';
- *
- * const store = postgres('postgresql://localhost/mydb');
- * const workflow = createWorkflow(deps);
- *
- * // Run and persist resume state
- * const { result, resumeState } = await workflow.runWithState(fn);
- * await store.save('wf-123', resumeState);
- *
- * // Restore
- * const loaded = await store.load('wf-123');
- * const resumeState = toResumeState(loaded);
- * if (resumeState) await workflow.run(fn, { resumeState });
- * ```
- */
-interface SnapshotStore {
-    /** Save a workflow snapshot (upsert - insert or update). Adapters may also accept ResumeState. */
-    save(id: string, snapshot: WorkflowSnapshot): Promise<void>;
-    /** Load a workflow snapshot. Returns null if not found. Adapters may return ResumeState when stored as such. */
-    load(id: string): Promise<WorkflowSnapshot | null>;
-    /** Delete a workflow snapshot. */
-    delete(id: string): Promise<void>;
-    /** List workflow IDs with their last update time. */
-    list(options?: {
-        prefix?: string;
-        limit?: number;
-    }): Promise<Array<{
-        id: string;
-        updatedAt: string;
-    }>>;
-    /** Clean shutdown for tests/graceful exit. */
-    close(): Promise<void>;
-}
-/**
- * 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;
-
-/**
- * Workflow type definitions.
- * Pure types and interfaces; no runtime code.
- */
-
-/**
- * Interface for step result caching.
- * Implement this interface to provide custom caching strategies.
- * A simple Map<string, Result> works for in-memory caching.
- *
- * ## When Cache is Populated
- *
- * The cache `set()` method is called after each step completes (success or error)
- * when the step has a `key` option. Both calling patterns work identically:
- *
- * ```typescript
- * // Function-wrapped pattern - cache is populated
- * await step(() => fetchUser("1"), { key: "user:1" });
- *
- * // Direct AsyncResult pattern - cache is also populated
- * await step(fetchUser("1"), { key: "user:1" });
- * ```
- *
- * Note: Cache stores Result<unknown, unknown, unknown> because different steps
- * have different value/error/cause types. The actual runtime values are preserved;
- * only the static types are widened. For error results, the cause value is encoded
- * in CachedErrorCause to preserve metadata for proper replay.
- *
- * @example
- * // Simple in-memory cache
- * const cache = new Map<string, Result<unknown, unknown, unknown>>();
- *
- * // Or implement custom cache with TTL, LRU, etc.
- * const cache: StepCache = {
- *   get: (key) => myCache.get(key),
- *   set: (key, result) => myCache.set(key, result, { ttl: 60000 }),
- *   has: (key) => myCache.has(key),
- *   delete: (key) => myCache.delete(key),
- *   clear: () => myCache.clear(),
- * };
- */
-interface StepCache {
-    get(key: string): Result<unknown, unknown, unknown> | undefined;
-    set(key: string, result: Result<unknown, unknown, unknown>, options?: {
-        ttl?: number;
-    }): void;
-    has(key: string): boolean;
-    delete(key: string): boolean;
-    clear(): void;
-}
-/**
- * Entry for a saved step result with optional metadata.
- * The meta field preserves origin information for proper replay.
- */
-interface ResumeStateEntry {
-    result: Result<unknown, unknown, unknown>;
-    /** Optional metadata for error origin (from step_complete event) */
-    meta?: StepFailureMeta;
-}
-/**
- * Resume state for workflow replay.
- * Pre-populate step results to skip execution on resume.
- *
- * Note: When saving to persistent storage, you may need custom serialization
- * for complex cause types. JSON.stringify works for simple values, but Error
- * objects and other non-plain types require special handling.
- *
- * @example
- * // Collect from step_complete events using the helper
- * const collector = createResumeStateCollector();
- * const workflow = createWorkflow({ fetchUser }, {
- *   onEvent: collector.handleEvent,
- * });
- * // Later: collector.getResumeState() returns ResumeState
- *
- * @example
- * // Resume with saved state
- * const workflow = createWorkflow({ fetchUser }, {
- *   resumeState: { steps: savedSteps }
- * });
- */
-interface ResumeState {
-    /** Map of step keys to their cached results with optional metadata */
-    steps: Map<string, ResumeStateEntry>;
-}
-/**
- * Constraint for Result-returning functions
- * Used by createWorkflow to ensure only valid functions are passed
- */
-type AnyResultFn = (...args: any[]) => Result<any, any, any> | Promise<Result<any, any, any>>;
-/**
- * Extract union of error types from a deps object
- * Example: ErrorsOfDeps<{ fetchUser: typeof fetchUser, fetchPosts: typeof fetchPosts }>
- * yields: 'NOT_FOUND' | 'FETCH_ERROR'
- */
-type ErrorsOfDeps<Deps extends Record<string, AnyResultFn>> = {
-    [K in keyof Deps]: ErrorOf<Deps[K]>;
-}[keyof Deps];
-/**
- * Extract union of cause types from a deps object.
- * Example: CausesOfDeps<{ fetchUser: typeof fetchUser }> where fetchUser returns Result<User, "NOT_FOUND", Error>
- * yields: Error
- *
- * Note: This represents the domain cause types from declared functions.
- * However, workflow results may also have unknown causes from step.try failures
- * or uncaught exceptions, so the actual Result cause type is `unknown`.
- */
-type CausesOfDeps<Deps extends Record<string, AnyResultFn>> = CauseOf<Deps[keyof Deps]>;
-/**
- * Execution-time options that can override creation-time options.
- * Pass these to `workflow.run(fn, execOptions)` for per-run configuration.
- *
- * Rule: Use `workflow(...)` for normal runs. Use `workflow.run(...)` when you need per-run hooks/options.
- *
- * @example
- * ```typescript
- * const workflow = createWorkflow(deps, { cache, onEvent: defaultHandler });
- *
- * // Normal run uses creation-time options
- * await workflow(async ({ step }) => { ... });
- *
- * // Per-run options override creation-time options
- * await workflow.run(async ({ step }) => { ... }, { onEvent: viz.handleEvent });
- *
- * // Pre-bind defaults with .with() (overridable by .run())
- * const visualized = workflow.with({ onEvent: viz.handleEvent });
- * await visualized(async ({ step }) => { ... });
- * ```
- */
-type ExecutionOptions<E, U = UnexpectedError, C = void> = {
-    /**
-     * Event handler for workflow and step lifecycle events.
-     * Overrides `onEvent` from creation-time options.
-     */
-    onEvent?: (event: WorkflowEvent<E | U, C>, ctx: C) => void;
-    /**
-     * Error handler called when a step fails.
-     * Overrides `onError` from creation-time options.
-     */
-    onError?: (error: E | U, stepName?: string, ctx?: C) => void;
-    /**
-     * AbortSignal for workflow-level cancellation.
-     * Overrides `signal` from creation-time options.
-     */
-    signal?: AbortSignal;
-    /**
-     * Factory to create per-run context. Can be async.
-     * Overrides `createContext` from creation-time options.
-     */
-    createContext?: () => C | Promise<C>;
-    /**
-     * Resume state for workflow replay. Can be a factory function (sync or async).
-     * Overrides `resumeState` from creation-time options.
-     */
-    resumeState?: ResumeState | (() => ResumeState | Promise<ResumeState>);
-    /**
-     * Hook to check if workflow should run (concurrency control).
-     * Overrides `shouldRun` from creation-time options.
-     */
-    shouldRun?: (workflowId: string, context: C) => boolean | Promise<boolean>;
-    /**
-     * Hook called before workflow execution starts.
-     * Overrides `onBeforeStart` from creation-time options.
-     */
-    onBeforeStart?: (workflowId: string, context: C) => boolean | Promise<boolean>;
-    /**
-     * Hook called after each step completes (only for steps with a `key`).
-     * Overrides `onAfterStep` from creation-time options.
-     */
-    onAfterStep?: (stepKey: string, result: Result<unknown, unknown, unknown>, workflowId: string, context: C) => void | Promise<void>;
-    /**
-     * Enable strict mode for this specific run (analyzer validation only).
-     */
-    strict?: boolean;
-    /**
-     * Enable development warnings for this run.
-     * Only active when NODE_ENV !== 'production'.
-     */
-    devWarnings?: boolean;
-};
-/**
- * Per-run configuration. Extends ExecutionOptions with dep overrides.
- * Pass to `workflow.run(fn, config)` or `workflow.run(name, fn, config)`.
- */
-type RunConfig<E, U = UnexpectedError, C = void, Deps = unknown> = ExecutionOptions<E, U, C> & {
-    /** Override creation-time deps (partial merge). */
-    deps?: Partial<Deps>;
-    /** Step result cache for this run. */
-    cache?: StepCache;
-    /** Restore workflow from a previously saved snapshot. */
-    snapshot?: WorkflowSnapshot | null;
-    /** Stream store for this run. */
-    streamStore?: StreamStore;
-};
-/**
- * Workflow options. Error union is always closed: E | U.
- * When catchUnexpected is omitted, U defaults to UnexpectedError.
- */
-type WorkflowOptions<E, U = UnexpectedError, C = void, Errs extends readonly string[] = readonly string[]> = {
-    /** Standard Schema for input validation. Works with Zod, Valibot, ArkType, etc. */
-    inputSchema?: StandardSchemaV1;
-    /** Input data to validate against inputSchema and pass to workflow context. */
-    input?: unknown;
-    /** Short description for labels/tooltips (static analysis) */
-    description?: string;
-    /** Full markdown documentation (static analysis) */
-    markdown?: string;
-    /**
-     * Map uncaught exceptions (and cancellation) to your error type U.
-     * When omitted, U = UnexpectedError and the default mapper returns an UnexpectedError instance.
-     */
-    catchUnexpected?: (cause: unknown) => U;
-    /**
-     * Declared errors for the workflow (strict validation).
-     * When provided, the analyzer validates that computed errors match declared errors.
-     */
-    errors?: Errs;
-    onError?: (error: E | U, stepName?: string, ctx?: C) => void;
-    /**
-     * Unified event stream for workflow and step lifecycle.
-     *
-     * Context is automatically included in `event.context` when provided via `createContext`.
-     * The separate `ctx` parameter is provided for convenience.
-     */
-    onEvent?: (event: WorkflowEvent<E | U, C>, ctx: C) => void;
-    /** Create per-run context for event correlation */
-    createContext?: () => C;
-    /** Step result cache - only steps with a `key` option are cached */
-    cache?: StepCache;
-    /** Pre-populate cache from saved state for workflow resume. Prefer `snapshot` option. */
-    resumeState?: ResumeState | (() => ResumeState | Promise<ResumeState>);
-    /**
-     * Restore workflow from a previously saved snapshot.
-     * Pass `null` for fresh start (e.g., when store.load() returns nothing).
-     */
-    snapshot?: WorkflowSnapshot | null;
-    /**
-     * Custom serialization for encoding/decoding values during snapshot operations.
-     */
-    serialization?: {
-        encode?: (value: unknown) => JSONValue;
-        decode?: (value: JSONValue) => unknown;
-    };
-    snapshotSerialization?: {
-        strict?: boolean;
-    };
-    onUnknownSteps?: "warn" | "error" | "ignore";
-    onDefinitionChange?: "warn" | "error" | "ignore";
-    /**
-     * External AbortSignal for workflow-level cancellation.
-     * Cancellation is mapped through catchUnexpected (default: UnexpectedError with cause.thrown = WorkflowCancelledError).
-     */
-    signal?: AbortSignal;
-    onBeforeStart?: (workflowId: string, context: C) => boolean | Promise<boolean>;
-    onAfterStep?: (stepKey: string, result: Result<unknown, unknown, unknown>, workflowId: string, context: C) => void | Promise<void>;
-    shouldRun?: (workflowId: string, context: C) => boolean | Promise<boolean>;
-    streamStore?: StreamStore;
-    /**
-     * Enable development warnings.
-     * Only active when NODE_ENV !== 'production'.
-     */
-    devWarnings?: boolean;
-};
-/**
- * Workflow context provided to callbacks, containing workflow metadata
- * and data store for step outputs.
- * This allows conditional helpers and other utilities to access workflowId, onEvent, and context.
- */
-type WorkflowContext<C = void, Input = Record<string, unknown>, Data = Record<string, unknown>> = {
-    /**
-     * Unique ID for this workflow run.
-     */
-    workflowId: string;
-    /**
-     * Event emitter function for workflow events.
-     * Can be used with conditional helpers to emit step_skipped events.
-     */
-    onEvent?: (event: WorkflowEvent<unknown, C>) => void;
-    /**
-     * Per-run context created by createContext (or undefined if not provided).
-     * Automatically included in all workflow events.
-     */
-    context?: C;
-    /**
-     * Workflow-level AbortSignal (if provided in workflow options).
-     * Use this to check cancellation or pass to operations that support AbortSignal.
-     *
-     * @example
-     * ```typescript
-     * const result = await workflow(async ({ step, deps, ctx }) => {
-     *   // Pass signal to fetch
-     *   const response = await fetch(url, { signal: ctx.signal });
-     *   // Or check manually
-     *   if (ctx.signal?.aborted) return early();
-     * });
-     * ```
-     */
-    signal?: AbortSignal;
-    /**
-     * Input data passed to the workflow.
-     * Access via `ctx.input.key` for static analysis tracking.
-     *
-     * @example
-     * ```typescript
-     * await step('getCart', () => getCart(ctx.input.cartId), {
-     *   errors: ['CART_NOT_FOUND'],
-     * });
-     * ```
-     */
-    input: Input;
-    /**
-     * Get a value from the workflow data store by key.
-     * Preferred over `ctx.get()` for static analysis as it's easier to trace.
-     *
-     * @param key - The key to retrieve
-     * @returns The value at that key
-     *
-     * @example
-     * ```typescript
-     * // Use ctx.ref() inside step callbacks for tracked dependencies
-     * await step('charge', () => chargeCard(ctx.ref('cart').total), {
-     *   errors: ['CARD_DECLINED'],
-     * });
-     * ```
-     */
-    ref: <K extends keyof Data>(key: K) => Data[K];
-    /**
-     * Set a value in the workflow data store.
-     * Prefer using `out` option on steps instead for better static analysis.
-     *
-     * @param key - The key to set
-     * @param value - The value to store
-     *
-     * @example
-     * ```typescript
-     * // Prefer out option:
-     * await step('getCart', () => getCart(id), { out: 'cart' });
-     *
-     * // Escape hatch (less analyzable):
-     * const cart = await step('getCart', () => getCart(id));
-     * ctx.set('cart', cart);
-     * ```
-     */
-    set: <K extends string>(key: K, value: unknown) => void;
-    /**
-     * Get a value from the workflow data store.
-     * Prefer `ctx.ref()` for better static analysis.
-     *
-     * @param key - The key to retrieve
-     * @returns The value at that key (or undefined)
-     */
-    get: <K extends keyof Data>(key: K) => Data[K] | undefined;
-};
-/**
- * Bound steps for a workflow's deps: each dep key becomes a step function
- * with the dep's arguments that unwraps ok / early-exits on err — same as
- * the deps-first run(deps, fn) form. `never` deps (no deps) yield no steps.
- */
-type WorkflowSteps<Deps> = [Deps] extends [
-    Record<string, (...args: never[]) => unknown>
-] ? BoundSteps<Deps> : Record<string, never>;
-/** Workflow function type (no args). E is the full step error union (deps errors + any ExtraE from step.workflow/withFallback). */
-type WorkflowFn<T, E, Deps, C = void> = (context: {
-    step: RunStep<E>;
-    steps: WorkflowSteps<Deps>;
-    deps: Deps;
-    ctx: WorkflowContext<C>;
-}) => T | Promise<T>;
-/**
- * Return type of runWithState: result plus resume state for persistence.
- * resumeState is always present, even when the run fails or returns an error Result.
- */
-type RunWithStateResult<T, E, U> = {
-    result: Result<T, E | U, unknown>;
-    resumeState: ResumeState;
-};
-/**
- * Workflow return type. Error union is always closed: E | ExtraE | U (default U = UnexpectedError).
- * ExtraE is inferred from the callback when using step.workflow or step.withFallback with errors not in deps.
- * Methods: .run() (4 overloads) and .runWithState() (4 overloads) for run-and-persist flows.
- *
- * Cause type is `unknown` because step.try/catchUnexpected receive thrown values.
- */
-interface Workflow<E, U = UnexpectedError, Deps = unknown, C = void> {
-    /**
-     * Pre-bind dependency overrides and return another `Workflow`.
-     * Chain `.withDeps()` and call `.run()` / `.runWithState()` as normal.
-     * Precedence: createWorkflow deps < withDeps deps < run config deps.
-     */
-    withDeps(overrides: Partial<Deps>): Workflow<E, U, Deps, C>;
-    /**
-     * Execute workflow (anonymous run).
-     * ExtraE is inferred from the callback (e.g. from step.workflow / step.withFallback); result is Result<T, E | ExtraE | U>.
-     * T is inferred from the callback return type. For nested workflows (calling another workflow.run() inside the callback),
-     * inference can sometimes fall back to `any`; adding an explicit return type to the callback (e.g.
-     * `async (ctx): Promise<{ user: User; enriched: Enriched }> => { ... }`) gives the compiler a target and preserves types.
-     */
-    run<T, ExtraE = never>(fn: WorkflowFn<T, E | ExtraE, Deps, C>): AsyncResult<T, E | ExtraE | U, unknown>;
-    /**
-     * Execute workflow with config overrides.
-     */
-    run<T, ExtraE = never>(fn: WorkflowFn<T, E | ExtraE, Deps, C>, config: RunConfig<E, U, C, Deps>): AsyncResult<T, E | ExtraE | U, unknown>;
-    /**
-     * Execute named workflow run (for logging, tracing, resume).
-     */
-    run<T, ExtraE = never>(name: string, fn: WorkflowFn<T, E | ExtraE, Deps, C>): AsyncResult<T, E | ExtraE | U, unknown>;
-    /**
-     * Execute named workflow run with config overrides.
-     */
-    run<T, ExtraE = never>(name: string, fn: WorkflowFn<T, E | ExtraE, Deps, C>, config: RunConfig<E, U, C, Deps>): AsyncResult<T, E | ExtraE | U, unknown>;
-    /**
-     * Execute workflow and return result plus resume state for persistence.
-     * resumeState is always present (even on failure) so callers can persist partial state.
-     * Same overloads as run(); does not throw — follows the same "never throw, always Result" contract as run().
-     *
-     * @example
-     * const { result, resumeState } = await workflow.runWithState(fn);
-     * await store.save(id, resumeState);
-     */
-    runWithState<T, ExtraE = never>(fn: WorkflowFn<T, E | ExtraE, Deps, C>): Promise<RunWithStateResult<T, E | ExtraE, U>>;
-    /**
-     * Execute workflow with config overrides and return result plus resume state.
-     */
-    runWithState<T, ExtraE = never>(fn: WorkflowFn<T, E | ExtraE, Deps, C>, config: RunConfig<E, U, C, Deps>): Promise<RunWithStateResult<T, E | ExtraE, U>>;
-    /**
-     * Execute named workflow run and return result plus resume state.
-     */
-    runWithState<T, ExtraE = never>(name: string, fn: WorkflowFn<T, E | ExtraE, Deps, C>): Promise<RunWithStateResult<T, E | ExtraE, U>>;
-    /**
-     * Execute named workflow run with config overrides and return result plus resume state.
-     */
-    runWithState<T, ExtraE = never>(name: string, fn: WorkflowFn<T, E | ExtraE, Deps, C>, config: RunConfig<E, U, C, Deps>): Promise<RunWithStateResult<T, E | ExtraE, U>>;
-}
-/**
- * Error returned when a workflow is cancelled via AbortSignal.
- *
- * @example
- * ```typescript
- * const controller = new AbortController();
- * const workflow = createWorkflow(deps, { signal: controller.signal });
- *
- * // Later:
- * controller.abort('User navigated away');
- *
- * const result = await workflowPromise;
- * if (!result.ok && isWorkflowCancelled(result.error)) {
- *   console.log('Cancelled:', result.error.reason);
- * }
- * ```
- */
-type WorkflowCancelledError = {
-    type: "WORKFLOW_CANCELLED";
-    /** Reason from AbortSignal.reason (if provided) */
-    reason?: string;
-    /** Last successfully completed keyed step (for resume purposes) */
-    lastStepKey?: string;
-};
-/**
- * Standard error type for steps awaiting human approval.
- * Use this as the error type for approval-gated steps.
- *
- * @example
- * const requireApproval = async (userId: string): AsyncResult<Approval, PendingApproval> => {
- *   const status = await checkApprovalStatus(userId);
- *   if (status === 'pending') {
- *     return err({ type: 'PENDING_APPROVAL', stepKey: `approval:${userId}` });
- *   }
- *   return ok(status.approval);
- * };
- */
-type PendingApproval = {
-    type: "PENDING_APPROVAL";
-    /** Step key for correlation when resuming */
-    stepKey: string;
-    /** Optional reason for the pending state */
-    reason?: string;
-    /** Optional metadata for the approval request */
-    metadata?: Record<string, unknown>;
-};
-/**
- * Standard error type for steps awaiting an HTTP callback (webhook).
- * Use with injectHook() to resume when the app receives the callback.
- * stepKey is always "hook:" + hookId for resume state.
- */
-type PendingHook = {
-    type: "PENDING_HOOK";
-    hookId: string;
-    /** Step key used in resume state; always "hook:" + hookId */
-    stepKey: string;
-    metadata?: Record<string, unknown>;
-};
-/**
- * Error returned when approval is rejected.
- */
-type ApprovalRejected = {
-    type: "APPROVAL_REJECTED";
-    /** Step key for correlation */
-    stepKey: string;
-    /** Reason the approval was rejected */
-    reason: string;
-};
-/**
- * Options for creating an approval-gated step.
- */
-interface ApprovalStepOptions<T> {
-    /** Stable key for this approval step (used for resume) */
-    key: string;
-    /** Function to check current approval status from external source */
-    checkApproval: () => Promise<{
-        status: "pending";
-    } | {
-        status: "approved";
-        value: T;
-    } | {
-        status: "rejected";
-        reason: string;
-    }>;
-    /** Optional reason shown when pending */
-    pendingReason?: string;
-    /** Optional metadata for the approval request */
-    metadata?: Record<string, unknown>;
-}
-/**
- * Options for creating a gated (pre-approval) step.
- */
-interface GatedStepOptions<TArgs, T> {
-    /** Stable key for this gated step (used for approval tracking) */
-    key: string;
-    /**
-     * Condition to check if approval is required.
-     * If returns true, execution pauses for approval.
-     * If returns false, operation executes immediately.
-     */
-    requiresApproval: boolean | ((args: TArgs) => boolean | Promise<boolean>);
-    /**
-     * Human-readable description of what this operation does.
-     * Shown in the approval UI so humans understand what they're approving.
-     */
-    description: string | ((args: TArgs) => string);
-    /**
-     * Check if approval has been granted externally.
-     * If not provided, the step always returns PendingApproval when gated.
-     */
-    checkApproval?: () => Promise<{
-        status: "pending";
-    } | {
-        status: "approved";
-        value?: T;
-    } | {
-        status: "rejected";
-        reason: string;
-    }>;
-    /**
-     * Optional metadata to include in the approval request.
-     * The args are automatically included as `pendingArgs`.
-     */
-    metadata?: Record<string, unknown>;
-}
-
-export { type AnyResultFn as A, deserializeCauseNew as B, type CausesOfDeps as C, serializeError as D, type ErrorsOfDeps as E, serializeThrown as F, type GatedStepOptions as G, type JSONValue as J, type MemoryCacheOptions as M, type PendingApproval as P, type ResumeState as R, type SnapshotStore as S, type WorkflowCancelledError as W, type WorkflowSnapshot as a, type WorkflowContext as b, type Workflow as c, type ApprovalRejected as d, type ApprovalStepOptions as e, type PendingHook as f, type StepResult as g, type WorkflowOptions as h, type ExecutionOptions as i, type ResumeStateEntry as j, type RunConfig as k, type RunWithStateResult as l, type SerializedCause as m, SnapshotDecodeError as n, SnapshotFormatError as o, SnapshotMismatchError as p, type SnapshotWarning as q, type StepCache as r, type WorkflowFn as s, type WorkflowSteps as t, assertValidSnapshot as u, isWorkflowSnapshot as v, looksLikeWorkflowSnapshot as w, mergeSnapshots as x, validateSnapshot as y, createMemoryCache as z };