awaitly 2.0.0 → 3.0.0

package/dist/{types-BZ2f4MRR.d.cts → index-ICmfQi08.d.cts}

@@ -1,5 +1,4 @@
-import { U as UnexpectedError } from './errors-DtXvrCiO.cjs';
-import { StandardSchemaV1 } from '@standard-schema/spec';
+import { U as UnexpectedError } from './errors-sDSeaZBO.cjs';
 
 /**
  * Bound steps for the deps-first forms: run(deps, fn) and workflow({ steps }).
@@ -1922,1163 +1921,4 @@ declare const run: typeof runFn & {
     }) => AsyncResult<T, E, unknown>;
 };
 
-/**
- * awaitly/streaming - Types
- *
- * Core types for Result-aware streaming in workflows.
- * All stream operations return Result types, enabling typed error handling
- * throughout the streaming pipeline.
- */
-
-/** Discriminant for stream write errors */
-declare const STREAM_WRITE_ERROR: "STREAM_WRITE_ERROR";
-/** Discriminant for stream read errors */
-declare const STREAM_READ_ERROR: "STREAM_READ_ERROR";
-/** Discriminant for stream close errors */
-declare const STREAM_CLOSE_ERROR: "STREAM_CLOSE_ERROR";
-/** Discriminant for stream store errors */
-declare const STREAM_STORE_ERROR: "STREAM_STORE_ERROR";
-/** Discriminant for stream ended marker */
-declare const STREAM_ENDED: "STREAM_ENDED";
-/** Discriminant for stream backpressure errors */
-declare const STREAM_BACKPRESSURE_ERROR: "STREAM_BACKPRESSURE_ERROR";
-/**
- * Error returned when a write operation fails.
- */
-type StreamWriteError = {
-    type: typeof STREAM_WRITE_ERROR;
-    reason: "closed" | "aborted" | "store_error";
-    message: string;
-    cause?: unknown;
-};
-/**
- * Error returned when a read operation fails.
- */
-type StreamReadError = {
-    type: typeof STREAM_READ_ERROR;
-    reason: "closed" | "store_error";
-    message: string;
-    cause?: unknown;
-};
-/**
- * Error returned when closing a stream fails.
- */
-type StreamCloseError = {
-    type: typeof STREAM_CLOSE_ERROR;
-    reason: "already_closed" | "store_error";
-    message: string;
-    cause?: unknown;
-};
-/**
- * Error returned from StreamStore operations.
- */
-type StreamStoreError = {
-    type: typeof STREAM_STORE_ERROR;
-    reason: "read_error" | "write_error" | "metadata_error" | "close_error";
-    message: string;
-    cause?: unknown;
-};
-/**
- * Marker indicating stream has ended (not an error, but a terminal state).
- * Used as the "error" type when stream is exhausted.
- */
-type StreamEndedMarker = {
-    type: typeof STREAM_ENDED;
-    finalPosition: number;
-};
-/**
- * Backpressure error when writer is paused.
- */
-type StreamBackpressureError = {
-    type: typeof STREAM_BACKPRESSURE_ERROR;
-    bufferedCount: number;
-    highWaterMark: number;
-};
-/**
- * Union of all stream errors.
- */
-type StreamError = StreamWriteError | StreamReadError | StreamCloseError | StreamStoreError | StreamBackpressureError;
-/**
- * A single item in the stream with metadata.
- */
-interface StreamItem<T> {
-    /** The value stored in this stream item */
-    value: T;
-    /** Position in the stream (0-indexed) */
-    position: number;
-    /** Timestamp when item was written */
-    ts: number;
-}
-/**
- * Metadata about a stream.
- */
-interface StreamMetadata {
-    /** Unique identifier for the stream (workflowId + namespace) */
-    id: string;
-    /** Namespace within the workflow */
-    namespace: string;
-    /** Workflow ID that owns this stream */
-    workflowId: string;
-    /** Number of items in the stream */
-    length: number;
-    /** Whether the stream has been closed */
-    closed: boolean;
-    /** Timestamp when stream was created */
-    createdAt: number;
-    /** Timestamp when stream was last written to */
-    lastWriteAt?: number;
-    /** Timestamp when stream was closed */
-    closedAt?: number;
-}
-/**
- * Options for creating a writable stream.
- */
-interface StreamOptions {
-    /** Named streams (default: 'default') */
-    namespace?: string;
-    /** Backpressure threshold (default: 16) */
-    highWaterMark?: number;
-}
-/**
- * Options for creating a readable stream.
- */
-interface StreamReadOptions {
-    /** Named streams (default: 'default') */
-    namespace?: string;
-    /** Resume from position (0-indexed) */
-    startIndex?: number;
-}
-/**
- * Options for streamForEach operation.
- */
-interface StreamForEachOptions {
-    /** Name for the operation (used in events) */
-    name?: string;
-    /** Checkpoint after every N items (default: 1 = checkpoint each item) */
-    checkpointInterval?: number;
-    /** Maximum concurrent processors (default: 1 = sequential) */
-    concurrency?: number;
-}
-/**
- * Result from streamForEach operation.
- */
-interface StreamForEachResult<R> {
-    /** Results from each processed item */
-    results: R[];
-    /** Total items processed */
-    processedCount: number;
-    /** Position of last processed item */
-    lastPosition: number;
-}
-/**
- * Writable stream interface - never throws, returns Results.
- *
- * Use within a step to write values to a stream that can be consumed
- * by readers (e.g., HTTP response streaming, AI token streaming).
- *
- * @template T - Type of values written to the stream
- *
- * @example
- * ```typescript
- * const writer = step.getWritable<string>({ namespace: 'ai-response' });
- *
- * await step(() => generateAI({
- *   prompt: 'Hello',
- *   onToken: async (token) => { await writer.write(token); }
- * }), { key: 'generate' });
- *
- * await writer.close();
- * ```
- */
-interface StreamWriter<T> {
-    /**
-     * Write a value to the stream.
-     * Returns an error if the stream is closed, aborted, or store fails.
-     */
-    write(value: T): AsyncResult<void, StreamWriteError>;
-    /**
-     * Close the stream normally.
-     * Signals to readers that no more data will be written.
-     */
-    close(): AsyncResult<void, StreamCloseError>;
-    /**
-     * Abort the stream with a reason.
-     * Use for error conditions that should terminate the stream.
-     */
-    abort(reason: unknown): void;
-    /** Whether the stream is still writable */
-    readonly writable: boolean;
-    /** Current write position (number of items written) */
-    readonly position: number;
-    /** Stream namespace */
-    readonly namespace: string;
-}
-/**
- * Readable stream interface - returns STREAM_ENDED marker when complete.
- *
- * Use to consume values from a stream, with support for resuming from
- * a specific position.
- *
- * @template T - Type of values read from the stream
- *
- * @example
- * ```typescript
- * const reader = getStreamReader<string>(runId, { namespace: 'ai-response' });
- *
- * let result = await reader.read();
- * while (result.ok) {
- *   response.write(result.value);
- *   result = await reader.read();
- * }
- *
- * if (result.error.type === 'STREAM_ENDED') {
- *   console.log('Stream complete at position', result.error.finalPosition);
- * }
- * ```
- */
-interface StreamReader<T> {
-    /**
-     * Read the next value from the stream.
-     * Returns StreamEndedMarker when stream is exhausted.
-     */
-    read(): AsyncResult<T, StreamReadError | StreamEndedMarker>;
-    /**
-     * Close the reader (stop consuming).
-     * Does not affect the underlying stream.
-     */
-    close(): void;
-    /** Whether there may be more data to read */
-    readonly readable: boolean;
-    /** Current read position */
-    readonly position: number;
-    /** Stream namespace */
-    readonly namespace: string;
-}
-/** Unsubscribe function returned by subscribe */
-type Unsubscribe = () => void;
-/**
- * Storage backend for stream data.
- * Follows the same patterns as persistence.ts adapters.
- *
- * @example In-memory store
- * ```typescript
- * const store = createMemoryStreamStore();
- * ```
- *
- * @example File-based store
- * ```typescript
- * const store = createFileStreamStore({ directory: './streams', fs });
- * ```
- */
-interface StreamStore {
-    /**
-     * Append an item to the stream.
-     */
-    append<T>(workflowId: string, namespace: string, item: StreamItem<T>): AsyncResult<void, StreamStoreError>;
-    /**
-     * Read items from the stream starting at an index.
-     * @param startIndex - Position to start reading from (0-indexed)
-     * @param limit - Maximum number of items to read (default: all remaining)
-     */
-    read<T>(workflowId: string, namespace: string, startIndex: number, limit?: number): AsyncResult<StreamItem<T>[], StreamStoreError>;
-    /**
-     * Get metadata about a stream.
-     * Returns undefined if stream doesn't exist.
-     */
-    getMetadata(workflowId: string, namespace: string): AsyncResult<StreamMetadata | undefined, StreamStoreError>;
-    /**
-     * Mark stream as closed.
-     */
-    closeStream(workflowId: string, namespace: string): AsyncResult<void, StreamStoreError>;
-    /**
-     * Subscribe to new items in a stream.
-     * Callback is invoked for each new item written.
-     * Returns unsubscribe function.
-     */
-    subscribe<T>(workflowId: string, namespace: string, callback: (item: StreamItem<T>) => void): Unsubscribe;
-}
-/**
- * Check if an error is a StreamEndedMarker.
- */
-declare function isStreamEnded(error: unknown): error is StreamEndedMarker;
-/**
- * Check if an error is a StreamWriteError.
- */
-declare function isStreamWriteError(error: unknown): error is StreamWriteError;
-/**
- * Check if an error is a StreamReadError.
- */
-declare function isStreamReadError(error: unknown): error is StreamReadError;
-/**
- * Check if an error is a StreamStoreError.
- */
-declare function isStreamStoreError(error: unknown): error is StreamStoreError;
-/**
- * Check if an error is a StreamBackpressureError.
- */
-declare function isStreamBackpressureError(error: unknown): error is StreamBackpressureError;
-/**
- * Create a StreamWriteError.
- */
-declare function streamWriteError(reason: StreamWriteError["reason"], message: string, cause?: unknown): StreamWriteError;
-/**
- * Create a StreamReadError.
- */
-declare function streamReadError(reason: StreamReadError["reason"], message: string, cause?: unknown): StreamReadError;
-/**
- * Create a StreamCloseError.
- */
-declare function streamCloseError(reason: StreamCloseError["reason"], message: string, cause?: unknown): StreamCloseError;
-/**
- * Create a StreamStoreError.
- */
-declare function streamStoreError(reason: StreamStoreError["reason"], message: string, cause?: unknown): StreamStoreError;
-/**
- * Create a StreamEndedMarker.
- */
-declare function streamEnded(finalPosition: number): StreamEndedMarker;
-/**
- * Create a StreamBackpressureError.
- */
-declare function streamBackpressureError(bufferedCount: number, highWaterMark: number): StreamBackpressureError;
-
-/**
- * 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;
-    /**
-     * Declared workflow graph for strict runtime validation.
-     * Undeclared step/decision ids fail the run immediately.
-     * Overrides `graph` from creation-time options.
-     */
-    graph?: DeclaredGraph;
-    /**
-     * 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;
-    /**
-     * Declared workflow graph for strict runtime validation.
-     * When provided, any runtime step/decision id not present in the graph
-     * fails the workflow immediately, guaranteeing the static diagram matches
-     * what actually runs. Produce it with awaitly-analyze's renderWorkflowDSL,
-     * or pass a plain list of ids.
-     */
-    graph?: DeclaredGraph;
-    /**
-     * 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 { STREAM_ENDED as $, type AsyncResult as A, type BackoffStrategy as B, type WorkflowSnapshot as C, type DepValueOfReturn as D, EARLY_EXIT_SYMBOL as E, type ApprovalStepOptions as F, type GatedStepOptions as G, type Workflow as H, type WorkflowOptions as I, type SnapshotStore as J, type ResumeStateEntry as K, type StreamStore as L, type StreamReader as M, type CausesOfDeps as N, type Ok as O, type PendingApproval as P, type ExecutionOptions as Q, type Result as R, type StepOptions as S, type TimeoutOptions as T, type JSONValue as U, type MemoryCacheOptions as V, type WorkflowEvent as W, type RunConfig as X, type RunWithStateResult as Y, STREAM_BACKPRESSURE_ERROR as Z, STREAM_CLOSE_ERROR as _, type RetryOptions as a, STREAM_READ_ERROR as a0, STREAM_STORE_ERROR as a1, STREAM_WRITE_ERROR as a2, type SerializedCause as a3, SnapshotDecodeError as a4, SnapshotFormatError as a5, SnapshotMismatchError as a6, type SnapshotWarning as a7, type StepCache as a8, type StepErrorDiagnostics as a9, isWorkflowSnapshot as aA, looksLikeWorkflowSnapshot as aB, mergeSnapshots as aC, serializeError as aD, serializeThrown as aE, streamBackpressureError as aF, streamCloseError as aG, streamEnded as aH, streamReadError as aI, streamStoreError as aJ, streamWriteError as aK, validateSnapshot as aL, type StepMetadata as aa, type StreamBackpressureError as ab, type StreamCloseError as ac, type StreamEndedMarker as ad, type StreamError as ae, type StreamForEachOptions as af, type StreamForEachResult as ag, type StreamItem as ah, type StreamMetadata as ai, type StreamOptions as aj, type StreamReadError as ak, type StreamReadOptions as al, type StreamStoreError as am, type StreamWriteError as an, type StreamWriter as ao, type Unsubscribe as ap, type WorkflowFn as aq, type WorkflowSteps as ar, assertValidSnapshot as as, createMemoryCache as at, deserializeCauseNew as au, isStreamBackpressureError as av, isStreamEnded as aw, isStreamReadError as ax, isStreamStoreError as ay, isStreamWriteError as az, type BoundSteps as b, type EarlyExit as c, type RunOptions as d, type RunOptionsWithCatch as e, type RunOptionsWithoutCatch as f, type RunStep as g, STEP_TIMEOUT_MARKER as h, type ScopeType as i, type StepFailureMeta as j, type StepTimeoutError as k, type StepTimeoutMarkerMeta as l, createEarlyExit as m, getStepTimeoutMeta as n, isEarlyExit as o, isStepTimeoutError as p, type AnyResultFn as q, run as r, type ErrorsOfDeps as s, type WorkflowContext as t, type Err as u, type ApprovalRejected as v, type PendingHook as w, type ResumeState as x, type WorkflowCancelledError as y, type StepResult as z };
+export { type AsyncResult as A, type BackoffStrategy as B, type CauseOf as C, type DeclaredGraph as D, EARLY_EXIT_SYMBOL as E, type Ok as O, type Result as R, STEP_TIMEOUT_MARKER as S, type TimeoutOptions as T, type WorkflowEvent as W, type RunStep as a, type BoundSteps as b, type EarlyExit as c, type RetryOptions as d, type RunOptions as e, type RunOptionsWithCatch as f, type RunOptionsWithoutCatch as g, type ScopeType as h, type StepFailureMeta as i, type StepOptions as j, type StepTimeoutError as k, type StepTimeoutMarkerMeta as l, createEarlyExit as m, getStepTimeoutMeta as n, isEarlyExit as o, isStepTimeoutError as p, type Err as q, run as r, type ErrorOf as s, type StepErrorDiagnostics as t, type StepMetadata as u, type DepValueOfReturn as v, type ErrorsOf as w };