awaitly 1.35.0 → 2.0.0

package/dist/{run-entry-BOuNyVoO.d.ts → types-BZ2f4MRR.d.cts}

@@ -1,4 +1,5 @@
-import { UnexpectedError } from './errors.js';
+import { U as UnexpectedError } from './errors-DtXvrCiO.cjs';
+import { StandardSchemaV1 } from '@standard-schema/spec';
 
 /**
  * Bound steps for the deps-first forms: run(deps, fn) and workflow({ steps }).
@@ -12,6 +13,7 @@ type AnyFunction$1 = (...args: never[]) => unknown;
 /**
  * Success value of a dependency's return type. Result-returning deps
  * contribute their `ok` value; plain (non-Result) deps pass through as-is.
+ * Shared with the policy wrappers, which normalize the same way.
  */
 type DepValueOfReturn<R> = [Extract<Awaited<R>, {
     ok: true;
@@ -39,9 +41,9 @@ type BoundSteps<Deps extends Record<string, AnyFunction$1>> = {
 };
 
 /**
- * awaitly/core
+ * Core module (internal): Result primitives and the run() function.
  *
- * Core Result primitives and run() function.
+ * Surfaced through the root `awaitly` entry (formerly `awaitly/core`).
  * Use this module for minimal bundle size when you don't need the full workflow capabilities
  * (like retries, timeout, or state persistence) provided by `createWorkflow`.
  *
@@ -65,7 +67,7 @@ type DurationInput = string | DurationObject;
  *
  * @example
  * ```typescript
- * const success = Awaitly.ok(42);
+ * const success = ok(42);
  * // Type shown: Ok<number>
  * ```
  */
@@ -83,7 +85,7 @@ type Ok<T> = {
  *
  * @example
  * ```typescript
- * const failure = Awaitly.err({ type: "NOT_FOUND", message: "User not found" });
+ * const failure = err({ type: "NOT_FOUND", message: "User not found" });
  * // Type shown: Err<{ type: string; message: string }>
  * ```
  */
@@ -107,185 +109,7 @@ type Result<T, E = unknown, C = unknown> = Ok<T> | Err<E, C>;
  * Use this for asynchronous operations that might fail.
  */
 type AsyncResult<T, E = unknown, C = unknown> = Promise<Result<T, E, C>>;
-/** Discriminant for PromiseRejectedError type - use in switch statements */
-declare const PROMISE_REJECTED: "PROMISE_REJECTED";
-/**
- * Named error constant for unexpected/unhandled errors.
- * Used by the analyzer when a step doesn't declare errors.
- */
-declare const AWAITLY_UNEXPECTED: "AWAITLY_UNEXPECTED";
-/**
- * Named error constant for cancelled operations.
- */
-declare const AWAITLY_CANCELLED: "AWAITLY_CANCELLED";
-/**
- * Named error constant for timed-out operations.
- */
-declare const AWAITLY_TIMEOUT: "AWAITLY_TIMEOUT";
-/**
- * Helper to create a tuple of string literal tags with preserved literal types.
- * Use this when you need to store error tags in a variable while keeping
- * TypeScript's literal type inference (avoiding widening to string[]).
- *
- * @param t - The string literal tags
- * @returns The same array with preserved literal types
- *
- * @example
- * ```typescript
- * // Without tags() - type widens to string[]
- * const errs = ['CART_NOT_FOUND', 'CART_EMPTY'];  // string[]
- *
- * // With tags() - literal types preserved
- * const errs = tags('CART_NOT_FOUND', 'CART_EMPTY');  // ['CART_NOT_FOUND', 'CART_EMPTY']
- *
- * await step('getCart', () => getCart(id), {
- *   errors: errs,  // Analyzer can extract literal types
- *   out: 'cart',
- * });
- * ```
- */
-declare const tags: <const T extends readonly string[]>(...t: T) => T;
-
-type PromiseRejectedError = {
-    type: typeof PROMISE_REJECTED;
-    cause: unknown;
-};
-/** Cause type for promise rejections in async batch helpers */
-type PromiseRejectionCause = {
-    type: "PROMISE_REJECTION";
-    reason: unknown;
-};
-type EmptyInputError = {
-    type: "EMPTY_INPUT";
-    message: string;
-};
 type MaybeAsyncResult<T, E, C = unknown> = Result<T, E, C> | Promise<Result<T, E, C>>;
-/**
- * Creates a successful Result.
- * Use this when an operation completes successfully.
- *
- * @remarks When to use: Wrap a successful value in a Result for consistent return types.
- *
- * @param value - The success value to wrap
- * @returns An Ok object with `{ ok: true, value }`
- *
- * @example
- * ```typescript
- * const success = Awaitly.ok(42);
- * // Type: Ok<number>
- *
- * function divide(a: number, b: number): Result<number, string> {
- *   if (b === 0) return Awaitly.err("Division by zero");
- *   return Awaitly.ok(a / b);
- * }
- * ```
- */
-declare function ok<T>(value: T): Ok<T>;
-/**
- * Creates a failed Result.
- * Use this when an operation fails.
- *
- * @remarks When to use: Return a typed failure without throwing so callers can handle it explicitly.
- *
- * @param error - The error value describing what went wrong (e.g., error code, object)
- * @returns An Err object with `{ ok: false, error }`
- *
- * @example
- * ```typescript
- * // Simple error
- * const r1 = Awaitly.err("NOT_FOUND");
- * // Type: Err<"NOT_FOUND">
- *
- * // Error with context (include in error object)
- * const r2 = Awaitly.err({ type: "PROCESSING_FAILED", cause: originalError });
- * // Type: Err<{ type: string; cause: Error }>
- * ```
- */
-declare function err<E, C = unknown>(error: E, options?: {
-    cause?: C;
-}): Err<E, C>;
-/**
- * Checks if a Result is successful.
- * Use this to narrow the type of a Result to the success case.
- *
- * @remarks When to use: Prefer functional-style checks or array filtering over `result.ok`.
- *
- * @param r - The Result to check
- * @returns `true` if successful, allowing access to `r.value`
- *
- * @example
- * ```typescript
- * const r = someOperation();
- * if (isOk(r)) {
- *   // Use r.value (Type is T)
- *   processValue(r.value);
- * } else {
- *   // Handle r.error (Type is E)
- *   handleError(r.error);
- * }
- * ```
- */
-declare const isOk: <T, E, C>(r: Result<T, E, C>) => r is Ok<T>;
-/**
- * Checks if a Result is a failure.
- * Use this to narrow the type of a Result to the error case.
- *
- * @remarks When to use: Prefer functional-style checks or array filtering over `result.ok`.
- *
- * @param r - The Result to check
- * @returns `true` if failed, allowing access to `r.error` and `r.cause`
- *
- * @example
- * ```typescript
- * if (isErr(r)) {
- *   // Handle error case early
- *   return;
- * }
- * // Proceed with success case
- * ```
- */
-declare const isErr: <T, E, C>(r: Result<T, E, C>) => r is Err<E, C>;
-/**
- * Checks if an error is an UnexpectedError.
- * Used internally by the framework but exported for advanced custom handling.
- * Indicates an error that wasn't typed/expected in the `run` signature.
- *
- * @remarks When to use: Distinguish unexpected failures from your typed error union.
- */
-declare const isUnexpectedError: (e: unknown) => e is UnexpectedError;
-/**
- * Type for exhaustive error handlers mapping string literal errors and UnexpectedError.
- * Each key in E gets a handler, plus UnexpectedError is required.
- */
-type MatchErrorHandlers<E extends string, R> = {
-    [K in Exclude<E, "UnexpectedError">]: (error: K) => R;
-} & {
-    UnexpectedError: (error: UnexpectedError) => R;
-};
-/**
- * Exhaustive pattern matching for error types.
- * Handles both string literal errors and UnexpectedError, ensuring all cases are covered.
- *
- * @param error - The error to match (string literal or UnexpectedError)
- * @param handlers - Object with a handler for each error case plus UnexpectedError
- * @returns The result of the matched handler
- *
- * @example
- * ```typescript
- * type FetchError = "NOT_FOUND" | "FETCH_ERROR";
- * const result: Result<User, FetchError | UnexpectedError> = await fetchUser();
- *
- * if (!result.ok) {
- *   return matchError(result.error, {
- *     NOT_FOUND: () => 404,
- *     FETCH_ERROR: () => 500,
- *     UnexpectedError: (e) => { throw e.cause; }
- *   });
- * }
- * ```
- */
-declare function matchError<E extends string, R>(handlers: MatchErrorHandlers<E, R>): (error: E | UnexpectedError) => R;
-declare function matchError<E extends string, R>(error: E | UnexpectedError, handlers: MatchErrorHandlers<E, R>): R;
 type AnyFunction = (...args: never[]) => unknown;
 /**
  * Helper to extract the error type from Result or AsyncResult return values.
@@ -305,12 +129,6 @@ type ErrorOfReturn<R> = [Extract<Awaited<R>, {
  * Extract error type from a single function's return type
  */
 type ErrorOf<T extends AnyFunction> = ErrorOfReturn<ReturnType<T>>;
-/**
- * Extract union of error types from multiple functions (tuple form)
- */
-type Errors<T extends AnyFunction[]> = {
-    [K in keyof T]: ErrorOf<T[K]>;
-}[number];
 /**
  * Extract union of error types from a deps object.
  *
@@ -324,27 +142,6 @@ type Errors<T extends AnyFunction[]> = {
 type ErrorsOf<Deps extends Record<string, AnyFunction>> = {
     [K in keyof Deps]: ErrorOf<Deps[K]>;
 }[keyof Deps];
-/**
- * Extract value type from Result
- */
-type ExtractValue<T> = T extends {
-    ok: true;
-    value: infer U;
-} ? U : never;
-/**
- * Extract error type from Result
- */
-type ExtractError<T> = T extends {
-    ok: false;
-    error: infer E;
-} ? E : never;
-/**
- * Extract cause type from Result
- */
-type ExtractCause<T> = T extends {
-    ok: false;
-    cause?: infer C;
-} ? C : never;
 /**
  * Helper to extract the cause type from Result or AsyncResult return values.
  * Works even when a function is declared to return a union of both forms.
@@ -617,14 +414,6 @@ interface StepErrorDiagnostics {
     cumulativeDurationMs?: number;
     origin: 'result' | 'throw' | 'timeout';
 }
-/** Extract canonical error tag. Priority: _tag > tag > code > Error.name > "unknown".
- * Tags are case-sensitive, whitespace-trimmed, otherwise raw.
- * Note: Error.name is fallback-grade (often too coarse like "Error", "TypeError"). */
-declare function extractErrorTag(error: unknown): string;
-/** Look up ErrorClassification from errorMeta for a given tag. */
-declare function lookupErrorClassification(tag: string, errorMeta?: Record<string, ErrorClassification>): ErrorClassification | undefined;
-/** Extract StepMetadata from StepOptions (returns undefined when empty). */
-declare function extractStepMetadata(options: StepOptions): StepMetadata | undefined;
 /**
  * Backoff strategy for retry operations.
  */
@@ -1702,6 +1491,18 @@ type WorkflowEvent<E, C = unknown> = {
     ts: number;
     metadata?: StepMetadata;
     context?: C;
+} | {
+    type: "decision";
+    workflowId: string;
+    workflowName?: string;
+    decisionId: string;
+    label?: string;
+    branch: string;
+    value: unknown;
+    phase?: "start" | "end";
+    durationMs?: number;
+    ts: number;
+    context?: C;
 } | {
     type: "scope_start";
     workflowId: string;
@@ -1874,6 +1675,23 @@ type WorkflowEvent<E, C = unknown> = {
     lastStepKey?: string;
     context?: C;
 };
+/**
+ * A declared workflow graph for strict runtime validation.
+ *
+ * Pass either a list of step/decision ids or a WorkflowDiagramDSL-shaped
+ * object (`{ states: [{ id }] }`, as produced by awaitly-analyze).
+ * When provided, any runtime step or decision id not present in the graph
+ * fails the workflow immediately — so the static diagram is guaranteed to
+ * match what actually runs. Ids containing `{...}` placeholders
+ * (e.g. "item-{i}") match any value in that position.
+ */
+type DeclaredGraph = readonly string[] | {
+    readonly states: ReadonlyArray<{
+        readonly id: string;
+        /** Authored id when the unique diagram id needed a collision suffix. */
+        readonly semanticId?: string;
+    }>;
+};
 type RunOptionsWithCatch<E, C = void> = {
     /**
      * Handler for expected errors.
@@ -1909,6 +1727,11 @@ type RunOptionsWithCatch<E, C = void> = {
      * Useful for passing request IDs, user IDs, or loggers.
      */
     context?: C;
+    /**
+     * Declared workflow graph for strict runtime validation.
+     * Undeclared step/decision ids fail the workflow immediately.
+     */
+    graph?: DeclaredGraph;
     /**
      * @internal External signal for workflow-level cancellation.
      * Used by createWorkflow() to pass the workflow signal to steps.
@@ -1936,6 +1759,11 @@ type RunOptionsWithoutCatch<E, C = void> = {
      */
     workflowName?: string;
     context?: C;
+    /**
+     * Declared workflow graph for strict runtime validation.
+     * Undeclared step/decision ids fail the workflow immediately.
+     */
+    graph?: DeclaredGraph;
     /**
      * @internal External signal for workflow-level cancellation.
      * Used by createWorkflow() to pass the workflow signal to steps.
@@ -2010,7 +1838,7 @@ declare function isEarlyExit<E>(e: unknown): e is EarlyExit<E>;
 /**
  * run() with catchUnexpected: closed union Result<T, E>.
  */
-declare function run<T, E, C = void>(fn: (context: {
+declare function runFn<T, E, C = void>(fn: (context: {
     step: RunStep<E>;
 }) => Promise<T> | T, options: RunOptionsWithCatch<E, C>): AsyncResult<T, E, unknown>;
 /**
@@ -2019,7 +1847,7 @@ declare function run<T, E, C = void>(fn: (context: {
  * uncaught exceptions are possible. Step errors pass through as-is.
  * When E is never (default), step is RunStep<unknown> so any operation is allowed.
  */
-declare function run<T, E = never, C = void>(fn: (context: {
+declare function runFn<T, E = never, C = void>(fn: (context: {
     step: [E] extends [never] ? RunStep<unknown> : RunStep<E>;
 }) => Promise<T> | T, options?: {
     onError?: (error: E | UnexpectedError, stepName?: string, ctx?: C) => void;
@@ -2027,6 +1855,7 @@ declare function run<T, E = never, C = void>(fn: (context: {
     workflowId?: string;
     workflowName?: string;
     context?: C;
+    graph?: DeclaredGraph;
     /** @internal External signal for workflow-level cancellation. */
     _workflowSignal?: AbortSignal;
 }): AsyncResult<T, E | UnexpectedError, unknown>;
@@ -2053,7 +1882,7 @@ declare function run<T, E = never, C = void>(fn: (context: {
  * // result.error: OrderNotFound | UserNotFound | ChargeDeclined | UnexpectedError
  * ```
  */
-declare function run<const Deps extends Record<string, AnyFunction>, T, C = void>(deps: Deps, fn: (steps: BoundSteps<Deps>, context: {
+declare function runFn<const Deps extends Record<string, AnyFunction>, T, C = void>(deps: Deps, fn: (steps: BoundSteps<Deps>, context: {
     step: [ErrorsOf<Deps>] extends [never] ? RunStep<unknown> : RunStep<ErrorsOf<Deps>>;
 }) => Promise<T> | T, options?: {
     onError?: (error: ErrorsOf<Deps> | UnexpectedError, stepName?: string, ctx?: C) => void;
@@ -2061,11 +1890,20 @@ declare function run<const Deps extends Record<string, AnyFunction>, T, C = void
     workflowId?: string;
     workflowName?: string;
     context?: C;
+    graph?: DeclaredGraph;
     /** @internal External signal for workflow-level cancellation. */
     _workflowSignal?: AbortSignal;
 }): AsyncResult<T, ErrorsOf<Deps> | UnexpectedError, unknown>;
-declare namespace run {
-    var strict: <T, E, C = void>(fn: (context: {
+/**
+ * The public run(): the engine with `.strict` attached.
+ *
+ * Assembled with a PURE-annotated Object.assign instead of a top-level
+ * `run.strict = ...` mutation — a top-level property assignment is a side
+ * effect that pins run (and the whole step engine) into every consumer
+ * bundle even when only Result primitives are imported.
+ */
+declare const run: typeof runFn & {
+    strict: <T, E, C = void>(fn: (context: {
         step: RunStep<E>;
     }) => Promise<T> | T, options: {
         onError?: (error: E, stepName?: string, ctx?: C) => void;
@@ -2082,1427 +1920,1165 @@ declare namespace run {
         /** @internal External signal for workflow-level cancellation. */
         _workflowSignal?: AbortSignal;
     }) => AsyncResult<T, E, unknown>;
-}
+};
+
 /**
- * Error thrown when `unwrap()` is called on an error Result.
+ * awaitly/streaming - Types
  *
- * This error is thrown to prevent silent failures when using `unwrap()`.
- * Prefer using `unwrapOr`, `unwrapOrElse`, or pattern matching with `match` or `isOk`/`isErr`.
+ * Core types for Result-aware streaming in workflows.
+ * All stream operations return Result types, enabling typed error handling
+ * throughout the streaming pipeline.
  */
-declare class UnwrapError<E = unknown, C = unknown> extends Error {
-    readonly error: E;
-    readonly cause?: C | undefined;
-    constructor(error: E, cause?: C | undefined);
-}
+
+/** 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;
+};
 /**
- * Unwraps a Result, throwing an error if it's a failure.
- *
- * @remarks When to use: Only at boundaries or tests where a failure should be fatal.
- *
- * ## When to Use
- *
- * Use `unwrap()` when:
- * - You're certain the Result is successful (e.g., after checking with `isOk`)
- * - You're in a context where errors should crash (e.g., tests, initialization)
- * - You need the value immediately and can't handle errors gracefully
- *
- * ## Why Avoid This
- *
- * **Prefer alternatives** in production code:
- * - `unwrapOr(defaultValue)` - Provide a fallback value
- * - `unwrapOrElse(fn)` - Compute fallback from error
- * - `match()` - Handle both cases explicitly
- * - `isOk()` / `isErr()` - Type-safe pattern matching
- *
- * Throwing errors makes error handling harder and can crash your application.
- *
- * @param r - The Result to unwrap
- * @returns The success value if the Result is successful
- * @throws {UnwrapError} If the Result is an error (includes the error and cause)
- *
- * @example
- * ```typescript
- * // Safe usage after checking
- * const result = someOperation();
- * if (isOk(result)) {
- *   const value = unwrap(result); // Safe - we know it's ok
- * }
- *
- * // Unsafe usage (not recommended)
- * const value = unwrap(someOperation()); // May throw!
- * ```
+ * 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.
  */
-declare const unwrap: <T, E, C>(r: Result<T, E, C>) => T;
+type StreamCloseError = {
+    type: typeof STREAM_CLOSE_ERROR;
+    reason: "already_closed" | "store_error";
+    message: string;
+    cause?: unknown;
+};
 /**
- * Unwraps a Result, returning a default value if it's a failure.
- *
- * @remarks When to use: Provide a safe fallback without branching.
- *
- * ## When to Use
- *
- * Use `unwrapOr()` when:
- * - You have a sensible default value for errors
- * - You want to continue execution even on failure
- * - The default value is cheap to compute (use `unwrapOrElse` if expensive)
- *
- * ## Why Use This
- *
- * - **Safe**: Never throws, always returns a value
- * - **Simple**: One-liner for common error handling
- * - **Type-safe**: TypeScript knows you'll always get a `T`
- *
- * @param r - The Result to unwrap
- * @param defaultValue - The value to return if the Result is an error
- * @returns The success value if successful, otherwise the default value
- *
- * @example
- * ```typescript
- * // Provide default for missing data
- * const user = unwrapOr(fetchUser(id), { id: 'anonymous', name: 'Guest' });
- *
- * // Provide default for numeric operations
- * const count = unwrapOr(parseCount(input), 0);
- *
- * // Provide default for optional features
- * const config = unwrapOr(loadConfig(), getDefaultConfig());
- * ```
+ * Error returned from StreamStore operations.
  */
-declare const unwrapOr: <T, E, C>(r: Result<T, E, C>, defaultValue: T) => T;
+type StreamStoreError = {
+    type: typeof STREAM_STORE_ERROR;
+    reason: "read_error" | "write_error" | "metadata_error" | "close_error";
+    message: string;
+    cause?: unknown;
+};
 /**
- * Unwraps a Result, computing a default value from the error if it's a failure.
- *
- * @remarks When to use: Compute a fallback from the error (logging, metrics, or derived defaults).
- *
- * ## When to Use
- *
- * Use `unwrapOrElse()` when:
- * - The default value is expensive to compute (lazy evaluation)
- * - You need to log or handle the error before providing a default
- * - The default depends on the error type or cause
- * - You want to transform the error into a success value
- *
- * ## Why Use This Instead of `unwrapOr`
- *
- * - **Lazy**: Default is only computed if needed (better performance)
- * - **Error-aware**: You can inspect the error before providing default
- * - **Flexible**: Default can depend on error type or cause
- *
- * @param r - The Result to unwrap
- * @param fn - Function that receives the error and optional cause, returns the default value
- * @returns The success value if successful, otherwise the result of calling `fn(error, cause)`
- *
- * @example
- * ```typescript
- * // Compute default based on error type
- * const port = unwrapOrElse(parsePort(env.PORT), (error) => {
- *   if (error === 'INVALID_FORMAT') return 3000;
- *   if (error === 'OUT_OF_RANGE') return 8080;
- *   return 4000; // default
- * });
- *
- * // Log error before providing default
- * const data = unwrapOrElse(fetchData(), (error, cause) => {
- *   console.error('Failed to fetch:', error, cause);
- *   return getCachedData();
- * });
- *
- * // Transform error into success value
- * const result = unwrapOrElse(operation(), (error) => {
- *   return { success: false, reason: String(error) };
- * });
- * ```
+ * Marker indicating stream has ended (not an error, but a terminal state).
+ * Used as the "error" type when stream is exhausted.
  */
-declare const unwrapOrElse: <T, E, C>(r: Result<T, E, C>, fn: (error: E, cause?: C) => T) => T;
+type StreamEndedMarker = {
+    type: typeof STREAM_ENDED;
+    finalPosition: number;
+};
 /**
- * Alias for `unwrap`. Returns the success value or throws.
- *
- * The Result is already computed; use when you want the value or throw (e.g. at boundaries or in tests).
- *
- * @param r - The Result to unwrap
- * @returns The success value if the Result is successful
- * @throws {UnwrapError} If the Result is an error (includes the error and cause)
+ * Backpressure error when writer is paused.
  */
-declare const runOrThrow: <T, E, C>(r: Result<T, E, C>) => T;
+type StreamBackpressureError = {
+    type: typeof STREAM_BACKPRESSURE_ERROR;
+    bufferedCount: number;
+    highWaterMark: number;
+};
 /**
- * Awaits a Promise of a Result, then returns the success value or rejects.
- *
- * The returned promise **resolves with T** on success and **rejects with UnwrapError** on failure.
- * UnwrapError extends Error and carries the original `error` and `cause` from the Err.
- *
- * @param ar - A Promise or thenable that resolves to a Result
- * @returns A Promise that resolves with the success value or rejects with UnwrapError
+ * Union of all stream errors.
  */
-declare const runOrThrowAsync: <T, E, C>(ar: PromiseLike<Result<T, E, C>>) => Promise<T>;
+type StreamError = StreamWriteError | StreamReadError | StreamCloseError | StreamStoreError | StreamBackpressureError;
 /**
- * Convenience alias for `unwrapOr(r, null)`. Returns the success value or null.
- *
- * @param r - The Result to unwrap
- * @returns The success value if successful, otherwise null
+ * 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.
  */
-declare const runOrNull: <T, E, C>(r: Result<T, E, C>) => T | null;
+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;
+}
 /**
- * Convenience alias for `unwrapOr(r, undefined)`. Returns the success value or undefined.
- *
- * @param r - The Result to unwrap
- * @returns The success value if successful, otherwise undefined
+ * Options for creating a writable stream.
  */
-declare const runOrUndefined: <T, E, C>(r: Result<T, E, C>) => T | undefined;
+interface StreamOptions {
+    /** Named streams (default: 'default') */
+    namespace?: string;
+    /** Backpressure threshold (default: 16) */
+    highWaterMark?: number;
+}
 /**
- * Wraps a synchronous throwing function in a Result.
- *
- * @remarks When to use: Wrap sync code that might throw so exceptions become Err values.
- *
- * ## When to Use
- *
- * Use `from()` when:
- * - You have a synchronous function that throws exceptions
- * - You want to convert exceptions to typed errors
- * - You're integrating with libraries that throw (e.g., JSON.parse, fs.readFileSync)
- * - You need to handle errors without try/catch blocks
- *
- * ## Why Use This
+ * 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.
  *
- * - **Type-safe errors**: Convert thrown exceptions to typed Result errors
- * - **No try/catch**: Cleaner code without nested try/catch blocks
- * - **Composable**: Results can be chained with `andThen`, `map`, etc.
- * - **Explicit errors**: Forces you to handle errors explicitly
+ * Use within a step to write values to a stream that can be consumed
+ * by readers (e.g., HTTP response streaming, AI token streaming).
  *
- * @param fn - The synchronous function to execute (may throw)
- * @returns A Result with the function's return value or the thrown error
+ * @template T - Type of values written to the stream
  *
  * @example
  * ```typescript
- * // Wrap JSON.parse
- * const parsed = from(() => JSON.parse('{"key": "value"}'));
- * // parsed: { ok: true, value: { key: "value" } }
+ * const writer = step.getWritable<string>({ namespace: 'ai-response' });
  *
- * const error = from(() => JSON.parse('invalid'));
- * // error: { ok: false, error: SyntaxError }
+ * await step(() => generateAI({
+ *   prompt: 'Hello',
+ *   onToken: async (token) => { await writer.write(token); }
+ * }), { key: 'generate' });
+ *
+ * await writer.close();
  * ```
  */
-declare function from<T>(fn: () => T): Ok<T> | Err<unknown, unknown>;
+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;
+}
 /**
- * Wraps a synchronous throwing function in a Result with custom error mapping.
+ * Readable stream interface - returns STREAM_ENDED marker when complete.
  *
- * Use this overload when you want to map thrown exceptions to your typed error union.
+ * Use to consume values from a stream, with support for resuming from
+ * a specific position.
  *
- * @param fn - The synchronous function to execute (may throw)
- * @param onError - Function to map the thrown exception to a typed error
- * @returns A Result with the function's return value or the mapped error
+ * @template T - Type of values read from the stream
  *
  * @example
  * ```typescript
- * // Map exceptions to typed errors
- * const parsed = from(
- *   () => JSON.parse(input),
- *   (cause) => ({ type: 'PARSE_ERROR' as const, cause })
- * );
- * // parsed.error: { type: 'PARSE_ERROR', cause: SyntaxError }
- *
- * // Map to simple error codes
- * const value = from(
- *   () => riskyOperation(),
- *   () => 'OPERATION_FAILED' as const
- * );
- * ```
- */
-declare function from<T, E>(fn: () => T, onError: (cause: unknown) => E): Ok<T> | Err<E, unknown>;
-/**
- * Wraps a Promise in a Result, converting rejections to errors.
- *
- * @remarks When to use: Wrap a Promise and keep the raw rejection as Err; use tryAsync to map errors.
+ * const reader = getStreamReader<string>(runId, { namespace: 'ai-response' });
  *
- * ## When to Use
- *
- * Use `fromPromise()` when:
- * - You have an existing Promise that might reject
- * - You want to convert Promise rejections to typed errors
- * - You're working with libraries that return Promises (fetch, database clients)
- * - You need to handle rejections without .catch() chains
- *
- * ## Why Use This
- *
- * - **Type-safe errors**: Convert Promise rejections to typed Result errors
- * - **Composable**: Results can be chained with `andThen`, `map`, etc.
- * - **Explicit handling**: Forces you to handle errors explicitly
- * - **No .catch() chains**: Cleaner than Promise.catch() patterns
- *
- * @param promise - The Promise to await (may reject)
- * @returns A Promise resolving to a Result with the resolved value or rejection reason
+ * let result = await reader.read();
+ * while (result.ok) {
+ *   response.write(result.value);
+ *   result = await reader.read();
+ * }
  *
- * @example
- * ```typescript
- * // Wrap fetch
- * const result = await fromPromise(
- *   fetch('/api').then(r => r.json())
- * );
- * // result.ok: true if fetch succeeded, false if rejected
+ * if (result.error.type === 'STREAM_ENDED') {
+ *   console.log('Stream complete at position', result.error.finalPosition);
+ * }
  * ```
  */
-declare function fromPromise<T>(promise: Promise<T>): Promise<Ok<T> | Err<unknown, unknown>>;
+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;
 /**
- * Wraps a Promise in a Result with custom error mapping.
- *
- * Use this overload when you want to map Promise rejections to your typed error union.
+ * Storage backend for stream data.
+ * Follows the same patterns as persistence.ts adapters.
  *
- * @param promise - The Promise to await (may reject)
- * @param onError - Function to map the rejection reason to a typed error
- * @returns A Promise resolving to a Result with the resolved value or mapped error
+ * @example In-memory store
+ * ```typescript
+ * const store = createMemoryStreamStore();
+ * ```
  *
- * @example
+ * @example File-based store
  * ```typescript
- * // Map fetch errors to typed errors
- * const result = await fromPromise(
- *   fetch('/api').then(r => {
- *     if (!r.ok) throw new Error(`HTTP ${r.status}`);
- *     return r.json();
- *   }),
- *   () => 'FETCH_FAILED' as const
- * );
- * // result.error: 'FETCH_FAILED' if fetch failed
- *
- * // Map with error details
- * const data = await fromPromise(
- *   db.query(sql),
- *   (cause) => ({ type: 'DB_ERROR' as const, message: String(cause) })
- * );
+ * const store = createFileStreamStore({ directory: './streams', fs });
  * ```
  */
-declare function fromPromise<T, E>(promise: Promise<T>, onError: (cause: unknown) => E): Promise<Ok<T> | Err<E, unknown>>;
-/**
- * Wraps an async function in a Result, catching both thrown exceptions and Promise rejections.
- *
- * @remarks When to use: Wrap async work and map thrown/rejected values into your typed error union.
- *
- * ## When to Use
- *
- * Use `tryAsync()` when:
- * - You have an async function that might throw or reject
- * - You want to convert both exceptions and rejections to typed errors
- * - You're creating new async functions (use `fromPromise` for existing Promises)
- * - You need to handle errors without try/catch or .catch()
- *
- * ## Why Use This Instead of `fromPromise`
- *
- * - **Function form**: Takes a function, not a Promise (lazy evaluation)
- * - **Catches both**: Handles both thrown exceptions and Promise rejections
- * - **Cleaner syntax**: No need to wrap in Promise manually
- *
- * @param fn - The async function to execute (may throw or reject)
- * @returns A Promise resolving to a Result with the function's return value or error
- *
- * @example
- * ```typescript
- * // Wrap async function
- * const result = await tryAsync(async () => {
- *   const data = await fetchData();
- *   return processData(data);
- * });
- * ```
+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 tryAsync<T>(fn: () => Promise<T>): AsyncResult<T, unknown>;
+declare function isStreamEnded(error: unknown): error is StreamEndedMarker;
 /**
- * Wraps an async function in a Result with custom error mapping.
- *
- * Use this overload when you want to map errors to your typed error union.
- *
- * @param fn - The async function to execute (may throw or reject)
- * @param onError - Function to map the error (exception or rejection) to a typed error
- * @returns A Promise resolving to a Result with the function's return value or mapped error
- *
- * @example
- * ```typescript
- * // Map errors to typed errors
- * const result = await tryAsync(
- *   async () => await fetchData(),
- *   () => 'FETCH_ERROR' as const
- * );
- *
- * // Map with error details
- * const data = await tryAsync(
- *   async () => await processFile(path),
- *   (cause) => ({ type: 'PROCESSING_ERROR' as const, cause })
- * );
- * ```
+ * Check if an error is a StreamWriteError.
  */
-declare function tryAsync<T, E>(fn: () => Promise<T>, onError: (cause: unknown) => E): AsyncResult<T, E>;
+declare function isStreamWriteError(error: unknown): error is StreamWriteError;
 /**
- * Converts a nullable value to a Result.
- *
- * @remarks When to use: Turn null/undefined into a typed error before continuing.
- *
- * ## When to Use
- *
- * Use `fromNullable()` when:
- * - You have a value that might be `null` or `undefined`
- * - You want to treat null/undefined as an error case
- * - You're working with APIs that return nullable values (DOM APIs, optional properties)
- * - You want to avoid null checks scattered throughout your code
- *
- * ## Why Use This
- *
- * - **Type-safe**: Converts nullable types to non-nullable Results
- * - **Explicit errors**: Forces you to handle null/undefined cases
- * - **Composable**: Results can be chained with `andThen`, `map`, etc.
- * - **No null checks**: Eliminates need for `if (value == null)` checks
- *
- * @param value - The value that may be null or undefined
- * @param onNull - Function that returns an error when value is null/undefined
- * @returns A Result with the value if not null/undefined, otherwise the error from `onNull`
- *
- * @example
- * ```typescript
- * // Convert DOM element lookup
- * const element = fromNullable(
- *   document.getElementById('app'),
- *   () => 'ELEMENT_NOT_FOUND' as const
- * );
- *
- * // Convert optional property
- * const userId = fromNullable(
- *   user.id,
- *   () => 'USER_ID_MISSING' as const
- * );
- *
- * // Convert database query result
- * const record = fromNullable(
- *   await db.find(id),
- *   () => ({ type: 'NOT_FOUND' as const, id })
- * );
- * ```
+ * Check if an error is a StreamReadError.
  */
-declare function fromNullable<T, E>(value: T | null | undefined, onNull: () => E): Result<T, E>;
+declare function isStreamReadError(error: unknown): error is StreamReadError;
 /**
- * Transforms the success value of a Result.
- *
- * @remarks When to use: Transform only the Ok value while leaving Err untouched.
- *
- * ## When to Use
- *
- * Use `map()` when:
- * - You need to transform a success value to another type
- * - You want to apply a pure function to the value
- * - You're building a pipeline of transformations
- * - The transformation cannot fail (use `andThen` if it can fail)
- *
- * ## Why Use This
- *
- * - **Functional style**: Composable, chainable transformations
- * - **Error-preserving**: Errors pass through unchanged
- * - **Type-safe**: TypeScript tracks the transformation
- * - **No unwrapping**: Avoids manual `if (r.ok)` checks
- *
- * @param r - The Result to transform
- * @param fn - Pure function that transforms the success value (must not throw)
- * @returns A new Result with the transformed value, or the original error if `r` was an error
- *
- * @example
- * ```typescript
- * // Transform numeric value
- * const doubled = map(ok(21), n => n * 2);
- * // doubled: { ok: true, value: 42 }
- *
- * // Transform object property
- * const name = map(fetchUser(id), user => user.name);
- *
- * // Chain transformations
- * const formatted = map(
- *   map(parseNumber(input), n => n * 2),
- *   n => `Result: ${n}`
- * );
- * ```
+ * Check if an error is a StreamStoreError.
  */
-declare function map<T, U>(r: Ok<T>, fn: (value: T) => U): Ok<U>;
-declare function map<T, U, E, C>(r: Err<E, C>, fn: (value: T) => U): Err<E, C>;
-declare function map<T, U, E, C>(r: Result<T, E, C>, fn: (value: T) => U): Result<U, E, C>;
+declare function isStreamStoreError(error: unknown): error is StreamStoreError;
 /**
- * Transforms the error value of a Result.
- *
- * @remarks When to use: Retype or normalize errors while leaving Ok values unchanged.
- *
- * ## When to Use
- *
- * Use `mapError()` when:
- * - You need to normalize or transform error types
- * - You want to convert errors to a different error type
- * - You're building error handling pipelines
- * - You need to format error messages or codes
- *
- * ## Why Use This
- *
- * - **Error normalization**: Convert errors to a common format
- * - **Type transformation**: Change error type while preserving value type
- * - **Composable**: Can be chained with other transformers
- * - **Success-preserving**: Success values pass through unchanged
- *
- * @param r - The Result to transform
- * @param fn - Function that transforms the error value (must not throw)
- * @returns A new Result with the original value, or the transformed error if `r` was an error
- *
- * @example
- * ```typescript
- * // Normalize error codes
- * const normalized = mapError(err('not_found'), e => e.toUpperCase());
- * // normalized: { ok: false, error: 'NOT_FOUND' }
- *
- * // Convert error types
- * const typed = mapError(
- *   err('404'),
- *   code => ({ type: 'HTTP_ERROR' as const, status: parseInt(code) })
- * );
- *
- * // Format error messages
- * const formatted = mapError(
- *   err('PARSE_ERROR'),
- *   code => `Failed to parse: ${code}`
- * );
- * ```
+ * Check if an error is a StreamBackpressureError.
  */
-declare function mapError<T, E, F, C>(r: Result<T, E, C>, fn: (error: E) => F): Result<T, F, C>;
+declare function isStreamBackpressureError(error: unknown): error is StreamBackpressureError;
 /**
- * Pattern matches on a Result, calling the appropriate handler.
- *
- * @remarks When to use: Handle both Ok and Err in a single expression that returns a value.
- *
- * ## When to Use
- *
- * Use `match()` when:
- * - You need to handle both success and error cases
- * - You want to transform a Result to a different type
- * - You need exhaustive handling (both cases must be handled)
- * - You're building user-facing messages or responses
- *
- * ## Why Use This
- *
- * - **Exhaustive**: Forces you to handle both success and error cases
- * - **Type-safe**: TypeScript ensures both handlers are provided
- * - **Functional**: Pattern matching style, similar to Rust's `match` or Haskell's `case`
- * - **Single expression**: Can be used in expressions, not just statements
+ * 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
  *
- * @param r - The Result to match
- * @param handlers - Object with `ok` and `err` handler functions
- * @param handlers.ok - Function called with the success value
- * @param handlers.err - Function called with the error and optional cause
- * @returns The return value of the appropriate handler (both must return the same type `R`)
+ * 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
- * // Build user-facing messages
- * const message = match(result, {
- *   ok: (user) => `Hello ${user.name}`,
- *   err: (error) => `Error: ${error}`,
- * });
- *
- * // Transform to API response
- * const response = match(operation(), {
- *   ok: (data) => ({ status: 200, body: data }),
- *   err: (error) => ({ status: 400, error: String(error) }),
- * });
+ * // Persist
+ * localStorage.setItem('wf-123', JSON.stringify(wf.getSnapshot()));
  *
- * // Handle with cause
- * const response = match(result, {
- *   ok: (value) => ({ status: 'success', data: value }),
- *   err: (error, cause) => ({ status: 'error', error, cause }),
- * });
+ * // 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
  * ```
  */
-declare function match<T, E, C, R>(handlers: {
-    ok: (value: T) => R;
-    err: (error: E, cause?: C) => R;
-}): (r: Result<T, E, C>) => R;
-declare function match<T, E, C, R>(r: Ok<T>, handlers: {
-    ok: (value: T) => R;
-    err: (error: E, cause?: C) => R;
-}): R;
-declare function match<T, E, C, R>(r: Err<E, C>, handlers: {
-    ok: (value: T) => R;
-    err: (error: E, cause?: C) => R;
-}): R;
-declare function match<T, E, C, R>(r: Result<T, E, C>, handlers: {
-    ok: (value: T) => R;
-    err: (error: E, cause?: C) => R;
-}): R;
-/**
- * Chains Results together (flatMap/monadic bind).
- *
- * @remarks When to use: Chain dependent operations that return Result without nested branching.
- *
- * ## When to Use
- *
- * Use `andThen()` when:
- * - You need to chain operations that can fail
- * - The next operation depends on the previous success value
- * - You're building a pipeline of dependent operations
- * - You want to avoid nested `if (r.ok)` checks
- *
- * ## Why Use This Instead of `map`
- *
- * - **Can fail**: The chained function returns a Result (can fail)
- * - **Short-circuits**: If first Result fails, second operation never runs
- * - **Error accumulation**: Errors from both operations are in the union
- * - **Composable**: Can chain multiple operations together
- *
- * ## Common Pattern
- *
- * This is the fundamental building block for Result pipelines:
- * ```typescript
- * andThen(operation1(), value1 =>
- *   andThen(operation2(value1), value2 =>
- *     ok({ value1, value2 })
- *   )
- * )
- * ```
- *
- * @param r - The first Result
- * @param fn - Function that takes the success value and returns a new Result (may fail)
- * @returns The Result from `fn` if `r` was successful, otherwise the original error
- *
- * @example
- * ```typescript
- * // Chain dependent operations
- * const userPosts = andThen(
- *   fetchUser('1'),
- *   user => fetchPosts(user.id)
- * );
- *
- * // Build complex pipelines
- * const result = andThen(parseInput(input), parsed =>
- *   andThen(validate(parsed), validated =>
- *     process(validated)
- *   )
- * );
- *
- * // Chain with different error types
- * const data = andThen(
- *   fetchUser(id), // Returns Result<User, 'FETCH_ERROR'>
- *   user => fetchPosts(user.id) // Returns Result<Post[], 'NOT_FOUND'>
- * );
- * // data.error: 'FETCH_ERROR' | 'NOT_FOUND'
- * ```
+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.
  */
-declare function andThen<T, U>(r: Ok<T>, fn: (value: T) => Ok<U>): Ok<U>;
-declare function andThen<T, F, C2>(r: Ok<T>, fn: (value: T) => Err<F, C2>): Err<F, C2>;
-declare function andThen<T, U, F, C2>(r: Ok<T>, fn: (value: T) => Result<U, F, C2>): Result<U, F, C2>;
-declare function andThen<T, U, E, F, C1, C2>(r: Err<E, C1>, fn: (value: T) => Result<U, F, C2>): Err<E, C1>;
-declare function andThen<T, U, E, F, C1, C2>(r: Result<T, E, C1>, fn: (value: T) => Result<U, F, C2>): Result<U, E | F, C1 | C2>;
+type SnapshotWarning = NonNullable<WorkflowSnapshot["warnings"]>[number];
 /**
- * Executes a side effect on a successful Result without changing it.
- *
- * @remarks When to use: Add side effects (logging, metrics) on Ok without changing the Result.
- *
- * ## When to Use
- *
- * Use `tap()` when:
- * - You need to log, debug, or observe success values
- * - You want to perform side effects in a pipeline
- * - You need to mutate external state based on success
- * - You're debugging and want to inspect values without breaking the chain
- *
- * ## Why Use This
- *
- * - **Non-breaking**: Doesn't change the Result, just performs side effect
- * - **Composable**: Can be inserted anywhere in a pipeline
- * - **Type-preserving**: Returns the same Result type
- * - **Lazy**: Side effect only runs if Result is successful
- *
- * @param r - The Result to tap
- * @param fn - Side effect function called with the success value (return value ignored)
- * @returns The original Result unchanged (for chaining)
+ * 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
- * // Log success values
- * const logged = tap(result, user => console.log('Got user:', user.name));
- * // logged === result, but console.log was called
- *
- * // Debug in pipeline
- * const debugged = pipe(
- *   fetchUser(id),
- *   r => tap(r, user => console.log('Fetched:', user)),
- *   r => map(r, user => user.name)
- * );
- *
- * // Mutate external state
- * const tracked = tap(result, data => {
- *   analytics.track('operation_success', data);
- * });
+ * const raw = JSON.parse(localStorage.getItem('wf-123') || 'null');
+ * if (looksLikeWorkflowSnapshot(raw)) {
+ *   createWorkflow(deps, { snapshot: raw });
+ * }
  * ```
  */
-declare function tap<T, E, C>(r: Result<T, E, C>, fn: (value: T) => void): Result<T, E, C>;
+declare function looksLikeWorkflowSnapshot(obj: unknown): obj is WorkflowSnapshot;
 /**
- * Executes a side effect on an error Result without changing it.
- *
- * @remarks When to use: Add side effects (logging, metrics) on Err without changing the Result.
- *
- * ## When to Use
- *
- * Use `tapError()` when:
- * - You need to log, debug, or observe error values
- * - You want to perform side effects on errors in a pipeline
- * - You need to report errors to external systems (logging, monitoring)
- * - You're debugging and want to inspect errors without breaking the chain
- *
- * ## Why Use This
+ * 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.
  *
- * - **Non-breaking**: Doesn't change the Result, just performs side effect
- * - **Composable**: Can be inserted anywhere in a pipeline
- * - **Type-preserving**: Returns the same Result type
- * - **Lazy**: Side effect only runs if Result is an error
+ * @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.
  *
- * @param r - The Result to tap
- * @param fn - Side effect function called with the error and optional cause (return value ignored)
- * @returns The original Result unchanged (for chaining)
+ * 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
- * // Log errors
- * const logged = tapError(result, (error, cause) => {
- *   console.error('Error:', error, cause);
- * });
+ * import { postgres } from 'awaitly-postgres';
+ * import { createWorkflow } from 'awaitly/workflow';
  *
- * // Report to error tracking
- * const tracked = tapError(result, (error, cause) => {
- *   errorTracker.report(error, cause);
- * });
+ * const store = postgres('postgresql://localhost/mydb');
+ * const workflow = createWorkflow(deps);
  *
- * // Debug in pipeline
- * const debugged = pipe(
- *   operation(),
- *   r => tapError(r, (err, cause) => console.error('Failed:', err)),
- *   r => mapError(r, err => 'FORMATTED_ERROR')
- * );
+ * // 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 });
  * ```
  */
-declare function tapError<T, E, C>(r: Result<T, E, C>, fn: (error: E, cause?: C) => void): Result<T, E, C>;
+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>;
+}
 /**
- * Transforms the success value of a Result, catching any errors thrown by the transform.
- *
- * @remarks When to use: Transform Ok values with a function that might throw and capture the failure.
- *
- * ## When to Use
- *
- * Use `mapTry()` when:
- * - Your transform function might throw exceptions
- * - You want to convert transform errors to typed errors
- * - You're working with libraries that throw (e.g., JSON.parse, Date parsing)
- * - You need to handle both Result errors and transform exceptions
- *
- * ## Why Use This Instead of `map`
- *
- * - **Exception-safe**: Catches exceptions from the transform function
- * - **Error mapping**: Converts thrown exceptions to typed errors
- * - **Dual error handling**: Handles both Result errors and transform exceptions
- *
- * @param result - The Result to transform
- * @param transform - Function to transform the success value (may throw exceptions)
- * @param onError - Function to map thrown exceptions to a typed error
- * @returns A Result with:
- *   - Transformed value if both Result and transform succeed
- *   - Original error if Result was an error
- *   - Transform error if transform threw an exception
- *
- * @example
- * ```typescript
- * // Safe JSON parsing
- * const parsed = mapTry(
- *   ok('{"key": "value"}'),
- *   JSON.parse,
- *   () => 'PARSE_ERROR' as const
- * );
- *
- * // Safe date parsing
- * const date = mapTry(
- *   ok('2024-01-01'),
- *   str => new Date(str),
- *   () => 'INVALID_DATE' as const
- * );
- *
- * // Transform with error details
- * const processed = mapTry(
- *   result,
- *   value => riskyTransform(value),
- *   (cause) => ({ type: 'TRANSFORM_ERROR' as const, cause })
- * );
- * ```
+ * Options for the in-memory cache adapter.
  */
-declare function mapTry<T, U, E, F, C>(result: Result<T, E, C>, transform: (value: T) => U, onError: (cause: unknown) => F): Result<U, E | F, C | unknown>;
+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;
+}
 /**
- * Transforms the error value of a Result, catching any errors thrown by the transform.
- *
- * @remarks When to use: Transform errors when the mapping might throw and you want that captured.
- *
- * ## When to Use
- *
- * Use `mapErrorTry()` when:
- * - Your error transform function might throw exceptions
- * - You're doing complex error transformations (e.g., string formatting, object construction)
- * - You want to handle both Result errors and transform exceptions
- * - You need to safely normalize error types
+ * Create an in-memory StepCache with optional LRU eviction and TTL.
  *
- * ## Why Use This Instead of `mapError`
- *
- * - **Exception-safe**: Catches exceptions from the error transform function
- * - **Error mapping**: Converts thrown exceptions to typed errors
- * - **Dual error handling**: Handles both Result errors and transform exceptions
- *
- * @param result - The Result to transform
- * @param transform - Function to transform the error value (may throw exceptions)
- * @param onError - Function to map thrown exceptions to a typed error
- * @returns A Result with:
- *   - Original value if Result was successful
- *   - Transformed error if both Result was error and transform succeeded
- *   - Transform error if transform threw an exception
+ * @param options - Cache options
+ * @returns StepCache implementation
  *
  * @example
  * ```typescript
- * // Safe error formatting
- * const formatted = mapErrorTry(
- *   err('not_found'),
- *   e => e.toUpperCase(), // Might throw if e is not a string
- *   () => 'FORMAT_ERROR' as const
- * );
- *
- * // Complex error transformation
- * const normalized = mapErrorTry(
- *   result,
- *   error => ({ type: 'NORMALIZED', message: String(error) }),
- *   () => 'TRANSFORM_ERROR' as const
- * );
+ * const cache = createMemoryCache({ maxSize: 1000, ttl: 60000 });
+ * const workflow = createWorkflow(deps, { cache });
  * ```
  */
-declare function mapErrorTry<T, E, F, G, C>(result: Result<T, E, C>, transform: (error: E) => F, onError: (cause: unknown) => G): Result<T, F | G, C | unknown>;
+declare function createMemoryCache(options?: MemoryCacheOptions): StepCache;
+
+/**
+ * Workflow type definitions.
+ * Pure types and interfaces; no runtime code.
+ */
+
 /**
- * Transforms both the success value and error value of a Result simultaneously.
+ * Interface for step result caching.
+ * Implement this interface to provide custom caching strategies.
+ * A simple Map<string, Result> works for in-memory caching.
  *
- * ## When to Use
+ * ## When Cache is Populated
  *
- * Use `bimap()` when:
- * - You need to transform both success and error in one operation
- * - You're normalizing Results to a common format
- * - You want symmetric transformation of both cases
- * - You're building adapters between different Result types
+ * 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:
  *
- * ## Why Use This Instead of `map` + `mapError`
+ * ```typescript
+ * // Function-wrapped pattern - cache is populated
+ * await step(() => fetchUser("1"), { key: "user:1" });
  *
- * - **Single operation**: Transforms both cases in one call
- * - **Clearer intent**: Shows you're handling both cases symmetrically
- * - **Less code**: Avoids chaining map and mapError
+ * // Direct AsyncResult pattern - cache is also populated
+ * await step(fetchUser("1"), { key: "user:1" });
+ * ```
  *
- * @param r - The Result to transform
- * @param onOk - Function that transforms the success value
- * @param onErr - Function that transforms the error value
- * @returns A new Result with transformed value or transformed error
+ * 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
- * ```typescript
- * // Normalize to API response format
- * const response = bimap(
- *   fetchUser(id),
- *   user => ({ status: 'success', data: user }),
- *   error => ({ status: 'error', code: error })
- * );
- *
- * // Transform types
- * const stringified = bimap(
- *   parseNumber(input),
- *   n => `Value: ${n}`,
- *   e => `Error: ${e}`
- * );
- *
- * // Adapt between error types
- * const adapted = bimap(
- *   externalResult,
- *   value => internalValue(value),
- *   error => internalError(error)
- * );
- * ```
+ * // 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.
  */
-declare function bimap<T, U, E, F, C>(r: Result<T, E, C>, onOk: (value: T) => U, onErr: (error: E) => F): Result<U, F, C>;
+interface ResumeStateEntry {
+    result: Result<unknown, unknown, unknown>;
+    /** Optional metadata for error origin (from step_complete event) */
+    meta?: StepFailureMeta;
+}
 /**
- * Recovers from an error by returning a new Result.
- * Similar to neverthrow's `.orElse()`.
- *
- * @remarks When to use: Recover from Err by returning a fallback Result or retyping the error.
- *
- * ## When to Use
- *
- * Use `orElse()` when:
- * - You want to recover from errors with fallback operations
- * - The recovery might also fail (returns a Result)
- * - You need to chain fallback strategies
- * - You're implementing retry or fallback patterns
+ * Resume state for workflow replay.
+ * Pre-populate step results to skip execution on resume.
  *
- * ## Why Use This
+ * 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.
  *
- * - **Fallback chains**: Try alternative operations on failure
- * - **Error recovery**: Convert errors to success with fallback values
- * - **Composable**: Can chain multiple orElse calls for cascading fallbacks
- * - **Type-safe**: TypeScript tracks the error union through recovery
- *
- * @param r - The Result to potentially recover from
- * @param fn - Function that takes the error and returns a new Result (may succeed or fail)
- * @returns The original Result if successful, or the result of the recovery function
+ * @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
- * ```typescript
- * // Fallback to default user
- * const user = orElse(
- *   fetchUser(id),
- *   error => error === 'NOT_FOUND' ? ok(defaultUser) : err(error)
- * );
- *
- * // Try cache, then database, then fail
- * const data = orElse(
- *   orElse(
- *     fetchFromCache(key),
- *     () => fetchFromDatabase(key)
- *   ),
- *   () => err('DATA_UNAVAILABLE' as const)
- * );
- *
- * // Convert specific errors to success
- * const result = orElse(
- *   riskyOperation(),
- *   error => error.code === 'RETRY' ? ok(defaultValue) : err(error)
- * );
- * ```
+ * // Resume with saved state
+ * const workflow = createWorkflow({ fetchUser }, {
+ *   resumeState: { steps: savedSteps }
+ * });
  */
-declare function orElse<T, E, E2, C, C2>(r: Result<T, E, C>, fn: (error: E, cause?: C) => Result<T, E2, C2>): Result<T, E2, C2>;
+interface ResumeState {
+    /** Map of step keys to their cached results with optional metadata */
+    steps: Map<string, ResumeStateEntry>;
+}
 /**
- * Async version of orElse for recovering from errors with async operations.
- *
- * @param r - The Result or AsyncResult to potentially recover from
- * @param fn - Async function that takes the error and returns a new Result
- * @returns Promise of the original Result if successful, or the result of the recovery function
- *
- * @example
- * ```typescript
- * // Try primary API, fall back to secondary
- * const data = await orElseAsync(
- *   await fetchFromPrimaryApi(),
- *   async (error) => {
- *     if (error === 'UNAVAILABLE') {
- *       return await fetchFromSecondaryApi();
- *     }
- *     return err(error);
- *   }
- * );
- * ```
+ * Constraint for Result-returning functions
+ * Used by createWorkflow to ensure only valid functions are passed
  */
-declare function orElseAsync<T, E, E2, C, C2>(r: Result<T, E, C> | Promise<Result<T, E, C>>, fn: (error: E, cause?: C) => Result<T, E2, C2> | Promise<Result<T, E2, C2>>): Promise<Result<T, E2, C2>>;
+type AnyResultFn = (...args: any[]) => Result<any, any, any> | Promise<Result<any, any, any>>;
 /**
- * Recovers from an error by returning a plain value (not a Result).
- * Useful when you want to provide a default value on error.
- *
- * ## When to Use
- *
- * Use `recover()` when:
- * - You want to provide a fallback value on error
- * - Recovery cannot fail (unlike orElse which returns a Result)
- * - You're implementing default value patterns
- * - You want to guarantee a successful Result
- *
- * ## Why Use This Instead of `orElse`
- *
- * - **Simpler**: Recovery function returns plain value, not Result
- * - **Guaranteed success**: Always returns ok() after recovery
- * - **Clearer intent**: Shows recovery cannot fail
- *
- * @param r - The Result to potentially recover from
- * @param fn - Function that takes the error and returns a recovery value
- * @returns The original Result if successful, or ok(recoveryValue) if error
- *
- * @example
- * ```typescript
- * // Provide default user on NOT_FOUND
- * const user = recover(
- *   fetchUser(id),
- *   error => error === 'NOT_FOUND' ? defaultUser : guestUser
- * );
- *
- * // Convert all errors to default
- * const config = recover(
- *   loadConfig(),
- *   () => defaultConfig
- * );
- *
- * // Recover with error-based defaults
- * const value = recover(
- *   parseNumber(input),
- *   error => error === 'EMPTY' ? 0 : -1
- * );
- * ```
+ * Extract union of error types from a deps object
+ * Example: ErrorsOfDeps<{ fetchUser: typeof fetchUser, fetchPosts: typeof fetchPosts }>
+ * yields: 'NOT_FOUND' | 'FETCH_ERROR'
  */
-declare function recover<T, E, C>(r: Result<T, E, C>, fn: (error: E, cause?: C) => T): Ok<T>;
+type ErrorsOfDeps<Deps extends Record<string, AnyResultFn>> = {
+    [K in keyof Deps]: ErrorOf<Deps[K]>;
+}[keyof Deps];
 /**
- * Async version of recover for recovering with async operations.
+ * Extract union of cause types from a deps object.
+ * Example: CausesOfDeps<{ fetchUser: typeof fetchUser }> where fetchUser returns Result<User, "NOT_FOUND", Error>
+ * yields: Error
  *
- * @param r - The Result or AsyncResult to potentially recover from
- * @param fn - Async function that takes the error and returns a recovery value
- * @returns Promise of ok(value) - either original or recovered
- *
- * @example
- * ```typescript
- * // Recover by fetching default from API
- * const user = await recoverAsync(
- *   await fetchUser(id),
- *   async (error) => await fetchDefaultUser()
- * );
- * ```
+ * 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`.
  */
-declare function recoverAsync<T, E, C>(r: Result<T, E, C> | Promise<Result<T, E, C>>, fn: (error: E, cause?: C) => T | Promise<T>): Promise<Ok<T>>;
+type CausesOfDeps<Deps extends Record<string, AnyResultFn>> = CauseOf<Deps[keyof Deps]>;
 /**
- * Validates and type-narrows a value to a Result.
- *
- * Since this library uses plain objects for Results, serialization is trivial -
- * the serialized form IS the Result. This function validates the structure and
- * provides type-safe narrowing.
- *
- * ## When to Use
- *
- * Use `hydrate()` when:
- * - Receiving Results over RPC/network
- * - Deserializing Results from storage
- * - Validating untrusted data as Results
+ * Execution-time options that can override creation-time options.
+ * Pass these to `workflow.run(fn, execOptions)` for per-run configuration.
  *
- * @param value - The unknown value to validate as a Result
- * @returns The value as a typed Result, or null if invalid
+ * Rule: Use `workflow(...)` for normal runs. Use `workflow.run(...)` when you need per-run hooks/options.
  *
  * @example
  * ```typescript
- * // Deserialize from JSON
- * const parsed = JSON.parse(jsonString);
- * const result = hydrate<User, ApiError>(parsed);
- * if (result) {
- *   // result is Result<User, ApiError>
- * }
+ * const workflow = createWorkflow(deps, { cache, onEvent: defaultHandler });
  *
- * // Validate RPC response
- * const rpcResponse = await fetchFromService();
- * const result = hydrate<Data, ServiceError>(rpcResponse);
- * ```
- */
-declare function hydrate<T, E, C = unknown>(value: unknown): Result<T, E, C> | null;
-/**
- * Type guard to check if a value is a valid serialized Result.
+ * // Normal run uses creation-time options
+ * await workflow(async ({ step }) => { ... });
  *
- * @param value - The value to check
- * @returns True if the value is a valid Result structure
+ * // Per-run options override creation-time options
+ * await workflow.run(async ({ step }) => { ... }, { onEvent: viz.handleEvent });
  *
- * @example
- * ```typescript
- * if (isSerializedResult(data)) {
- *   // data is Result<unknown, unknown, unknown>
- *   if (data.ok) {
- *     console.log(data.value);
- *   }
- * }
+ * // Pre-bind defaults with .with() (overridable by .run())
+ * const visualized = workflow.with({ onEvent: viz.handleEvent });
+ * await visualized(async ({ step }) => { ... });
  * ```
  */
-declare function isSerializedResult(value: unknown): value is Result<unknown, unknown, unknown>;
-type AllValues<T extends readonly Result<unknown, unknown, unknown>[]> = {
-    [K in keyof T]: T[K] extends Ok<infer V> ? V : T[K] extends Err<unknown, unknown> ? never : T[K] extends Result<infer V, unknown, unknown> ? V : never;
+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;
 };
-type AllErrors<T extends readonly Result<unknown, unknown, unknown>[]> = {
-    [K in keyof T]: T[K] extends Ok<unknown> ? never : T[K] extends Err<infer E, unknown> ? E : T[K] extends Result<unknown, infer E, unknown> ? E : never;
-}[number];
-type AllCauses<T extends readonly Result<unknown, unknown, unknown>[]> = {
-    [K in keyof T]: T[K] extends Ok<unknown> ? never : T[K] extends Err<unknown, infer C> ? C : T[K] extends Result<unknown, unknown, infer C> ? C : never;
-}[number];
-type AllResult<T extends readonly Result<unknown, unknown, unknown>[]> = [
-    AllErrors<T>
-] extends [never] ? Ok<AllValues<T>> : Result<AllValues<T>, AllErrors<T>, AllCauses<T>>;
 /**
- * Combines multiple Results into one, requiring all to succeed.
- *
- * ## When to Use
- *
- * Use `all()` when:
- * - You have multiple independent operations that all must succeed
- * - You want to short-circuit on the first error (fail-fast)
- * - You need all values together (e.g., combining API responses)
- * - Performance matters (stops on first error, doesn't wait for all)
- *
- * ## Why Use This
- *
- * - **Fail-fast**: Stops immediately on first error (better performance)
- * - **Type-safe**: TypeScript infers the array type from input
- * - **Short-circuit**: Doesn't evaluate remaining Results after error
- * - **Composable**: Can be chained with other operations
- *
- * ## Important
- *
- * - **Short-circuits**: Returns first error immediately, doesn't wait for all Results
- * - **All must succeed**: If any Result fails, the entire operation fails
- * - **Use `allSettled`**: If you need to collect all errors (e.g., form validation)
- *
- * @param results - Array of Results to combine (all must succeed)
- * @returns A Result with an array of all success values, or the first error encountered
- *
- * @example
- * ```typescript
- * // Combine multiple successful Results
- * const combined = all([Awaitly.ok(1), Awaitly.ok(2), Awaitly.ok(3)]);
- * // combined: { ok: true, value: [1, 2, 3] }
- *
- * // Short-circuits on first error
- * const error = all([Awaitly.ok(1), Awaitly.err('ERROR'), Awaitly.ok(3)]);
- * // error: { ok: false, error: 'ERROR' }
- * // Note: Awaitly.ok(3) is never evaluated
- *
- * // Combine API responses
- * const data = all([
- *   fetchUser(id),
- *   fetchPosts(id),
- *   fetchComments(id)
- * ]);
- * // data.value: [user, posts, comments] if all succeed
- * ```
+ * 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.
  */
-declare function all<const T extends readonly Result<unknown, unknown, unknown>[]>(results: T): AllResult<T>;
+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;
+};
 /**
- * Combines multiple Results or Promises of Results into one (async version of `all`).
- *
- * ## When to Use
- *
- * Use `allAsync()` when:
- * - You have multiple async operations that all must succeed
- * - You want to run operations in parallel (better performance)
- * - You want to short-circuit on the first error (fail-fast)
- * - You need all values together from parallel operations
- *
- * ## Why Use This Instead of `all`
- *
- * - **Parallel execution**: All Promises start immediately (faster)
- * - **Async support**: Works with Promises and AsyncResults
- * - **Promise rejection handling**: Converts Promise rejections to `PromiseRejectedError`
- *
- * ## Important
- *
- * - **Short-circuits**: Returns first error immediately, cancels remaining operations
- * - **Parallel**: All operations start simultaneously (unlike sequential `andThen`)
- * - **Use `allSettledAsync`**: If you need to collect all errors
- *
- * @param results - Array of Results or Promises of Results to combine (all must succeed)
- * @returns A Promise resolving to a Result with an array of all success values, or the first error
- *
- * @example
- * ```typescript
- * // Parallel API calls
- * const combined = await allAsync([
- *   fetchUser('1'),
- *   fetchPosts('1'),
- *   fetchComments('1')
- * ]);
- * // All three calls start simultaneously
- * // combined: { ok: true, value: [user, posts, comments] } if all succeed
- *
- * // Mix Results and Promises
- * const data = await allAsync([
- *   ok(cachedUser), // Already resolved
- *   fetchPosts(userId), // Promise
- * ]);
- * ```
+ * 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.
  */
-declare function allAsync<const T extends readonly (Result<unknown, unknown, unknown> | Promise<Result<unknown, unknown, unknown>>)[]>(results: T): Promise<Result<{
-    [K in keyof T]: T[K] extends Result<infer V, unknown, unknown> | Promise<Result<infer V, unknown, unknown>> ? V : never;
-}, {
-    [K in keyof T]: T[K] extends Result<unknown, infer E, unknown> | Promise<Result<unknown, infer E, unknown>> ? E : never;
-}[number] | PromiseRejectedError, {
-    [K in keyof T]: T[K] extends Result<unknown, unknown, infer C> | Promise<Result<unknown, unknown, infer C>> ? C : never;
-}[number] | PromiseRejectionCause>>;
-type SettledError<E, C = unknown> = {
-    error: E;
-    cause?: C;
+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;
 };
-type AllSettledResult<T extends readonly Result<unknown, unknown, unknown>[]> = [
-    AllErrors<T>
-] extends [never] ? Ok<AllValues<T>> : Result<AllValues<T>, SettledError<AllErrors<T>, AllCauses<T>>[]>;
 /**
- * Combines multiple Results, collecting all errors instead of short-circuiting.
- *
- * ## When to Use
- *
- * Use `allSettled()` when:
- * - You need to see ALL errors, not just the first one
- * - You're doing form validation (show all field errors)
- * - You want to collect partial results (some succeed, some fail)
- * - You need to process all Results regardless of failures
- *
- * ## Why Use This Instead of `all`
- *
- * - **Collects all errors**: Returns array of all errors, not just first
- * - **No short-circuit**: Evaluates all Results even if some fail
- * - **Partial success**: Can see which operations succeeded and which failed
- * - **Better UX**: Show users all validation errors at once
- *
- * ## Important
- *
- * - **No short-circuit**: All Results are evaluated (slower if many fail early)
- * - **Error array**: Returns array of `{ error, cause }` objects, not single error
- * - **Use `all`**: If you want fail-fast behavior (better performance)
- *
- * @param results - Array of Results to combine (all are evaluated)
- * @returns A Result with:
- *   - Array of all success values if all succeed
- *   - Array of `{ error, cause }` objects if any fail
- *
- * @example
- * ```typescript
- * // Form validation - show all errors
- * const validated = allSettled([
- *   validateEmail(email),
- *   validatePassword(password),
- *   validateAge(age),
- * ]);
- * // If email and password fail:
- * // { ok: false, error: [
- * //   { error: 'INVALID_EMAIL' },
- * //   { error: 'WEAK_PASSWORD' }
- * // ]}
- *
- * // Collect partial results
- * const results = allSettled([
- *   fetchUser('1'), // succeeds
- *   fetchUser('2'), // fails
- *   fetchUser('3'), // succeeds
- * ]);
- * // Can see which succeeded and which failed
- * ```
+ * 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.
  */
-declare function allSettled<const T extends readonly Result<unknown, unknown, unknown>[]>(results: T): AllSettledResult<T>;
+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>;
 /**
- * Splits an array of Results into separate arrays of success values and errors.
- *
- * ## When to Use
- *
- * Use `partition()` when:
- * - You have an array of Results and need to separate successes from failures
- * - You want to process successes and errors separately
- * - You're collecting results from multiple operations (some may fail)
- * - You need to handle partial success scenarios
- *
- * ## Why Use This
- *
- * - **Simple separation**: One call splits successes and errors
- * - **Type-safe**: TypeScript knows `values` is `T[]` and `errors` is `E[]`
- * - **No unwrapping**: Doesn't require manual `if (r.ok)` checks
- * - **Preserves order**: Maintains original array order in both arrays
- *
- * ## Common Pattern
- *
- * Often used after `Promise.all()` with Results:
- * ```typescript
- * const results = await Promise.all(ids.map(id => fetchUser(id)));
- * const { values: users, errors } = partition(results);
- * // Process successful users, handle errors separately
- * ```
+ * 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.
  *
- * @param results - Array of Results to partition
- * @returns An object with:
- *   - `values`: Array of all success values (type `T[]`)
- *   - `errors`: Array of all error values (type `E[]`)
+ * 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
- * // Split successes and errors
- * const results = [ok(1), err('ERROR_1'), ok(3), err('ERROR_2')];
- * const { values, errors } = partition(results);
- * // values: [1, 3]
- * // errors: ['ERROR_1', 'ERROR_2']
- *
- * // Process batch operations
- * const userResults = await Promise.all(userIds.map(id => fetchUser(id)));
- * const { values: users, errors: fetchErrors } = partition(userResults);
+ * const controller = new AbortController();
+ * const workflow = createWorkflow(deps, { signal: controller.signal });
  *
- * // Process successful users
- * users.forEach(user => processUser(user));
+ * // Later:
+ * controller.abort('User navigated away');
  *
- * // Handle errors
- * fetchErrors.forEach(error => logError(error));
+ * const result = await workflowPromise;
+ * if (!result.ok && isWorkflowCancelled(result.error)) {
+ *   console.log('Cancelled:', result.error.reason);
+ * }
  * ```
  */
-declare function partition<T, E, C>(results: readonly Result<T, E, C>[]): {
-    values: T[];
-    errors: E[];
+type WorkflowCancelledError = {
+    type: "WORKFLOW_CANCELLED";
+    /** Reason from AbortSignal.reason (if provided) */
+    reason?: string;
+    /** Last successfully completed keyed step (for resume purposes) */
+    lastStepKey?: string;
 };
-type AnyValue<T extends readonly Result<unknown, unknown, unknown>[]> = T[number] extends Result<infer U, unknown, unknown> ? U : never;
-type AnyErrors<T extends readonly Result<unknown, unknown, unknown>[]> = {
-    -readonly [K in keyof T]: T[K] extends Result<unknown, infer E, unknown> ? E : never;
-}[number];
-type AnyCauses<T extends readonly Result<unknown, unknown, unknown>[]> = {
-    -readonly [K in keyof T]: T[K] extends Result<unknown, unknown, infer C> ? C : never;
-}[number];
 /**
- * Returns the first successful Result from an array (succeeds fast).
- *
- * ## When to Use
- *
- * Use `any()` when:
- * - You have multiple fallback options and need the first that succeeds
- * - You're trying multiple strategies (e.g., cache → DB → API)
- * - You want fail-fast success (stops on first success)
- * - You have redundant data sources and any one will do
- *
- * ## Why Use This
- *
- * - **Succeeds fast**: Returns immediately on first success (better performance)
- * - **Fallback pattern**: Perfect for trying multiple options
- * - **Short-circuits**: Stops evaluating after first success
- * - **Type-safe**: TypeScript infers the success type
- *
- * ## Important
- *
- * - **First success wins**: Returns first successful Result, ignores rest
- * - **All errors**: If all fail, returns first error (not all errors)
- * - **Empty array**: Returns `EmptyInputError` if array is empty
- * - **Use `all`**: If you need ALL to succeed
- *
- * @param results - Array of Results to check (evaluated in order)
- * @returns The first successful Result, or first error if all fail, or `EmptyInputError` if empty
+ * Standard error type for steps awaiting human approval.
+ * Use this as the error type for approval-gated steps.
  *
  * @example
- * ```typescript
- * // Try multiple fallback strategies
- * const data = any([
- *   fetchFromCache(id),
- *   fetchFromDB(id),
- *   fetchFromAPI(id)
- * ]);
- * // Returns first that succeeds
- *
- * // Try multiple formats
- * const parsed = any([
- *   parseJSON(input),
- *   parseXML(input),
- *   parseYAML(input)
- * ]);
- *
- * // All errors case
- * const allErrors = any([err('A'), err('B'), err('C')]);
- * // allErrors: { ok: false, error: 'A' } (first error)
- * ```
+ * 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);
+ * };
  */
-declare function any<const T extends readonly Result<unknown, unknown, unknown>[]>(results: T): Result<AnyValue<T>, AnyErrors<T> | EmptyInputError, AnyCauses<T>>;
-type AnyAsyncValue<T extends readonly MaybeAsyncResult<unknown, unknown, unknown>[]> = Awaited<T[number]> extends Result<infer U, unknown, unknown> ? U : never;
-type AnyAsyncErrors<T extends readonly MaybeAsyncResult<unknown, unknown, unknown>[]> = {
-    -readonly [K in keyof T]: Awaited<T[K]> extends Result<unknown, infer E, unknown> ? E : never;
-}[number];
-type AnyAsyncCauses<T extends readonly MaybeAsyncResult<unknown, unknown, unknown>[]> = {
-    -readonly [K in keyof T]: Awaited<T[K]> extends Result<unknown, unknown, infer C> ? C : never;
-}[number];
+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>;
+};
 /**
- * Returns the first successful Result from an array of Results or Promises (async version of `any`).
- *
- * ## When to Use
- *
- * Use `anyAsync()` when:
- * - You have multiple async fallback options and need the first that succeeds
- * - You're trying multiple async strategies in parallel (cache → DB → API)
- * - You want fail-fast success from parallel operations
- * - You have redundant async data sources and any one will do
- *
- * ## Why Use This Instead of `any`
- *
- * - **Parallel execution**: All Promises start immediately (faster)
- * - **Async support**: Works with Promises and AsyncResults
- * - **Promise rejection handling**: Converts Promise rejections to `PromiseRejectedError`
- *
- * ## Important
- *
- * - **First success wins**: Returns first successful Result (from any Promise)
- * - **Parallel**: All operations run simultaneously
- * - **All errors**: If all fail, returns first error encountered
- *
- * @param results - Array of Results or Promises of Results to check (all start in parallel)
- * @returns A Promise resolving to the first successful Result, or first error if all fail
- *
- * @example
- * ```typescript
- * // Try multiple async fallbacks in parallel
- * const data = await anyAsync([
- *   fetchFromCache(id), // Fastest wins
- *   fetchFromDB(id),
- *   fetchFromAPI(id)
- * ]);
- *
- * // Try multiple API endpoints
- * const response = await anyAsync([
- *   fetch('/api/v1/data'),
- *   fetch('/api/v2/data'),
- *   fetch('/backup-api/data')
- * ]);
- * ```
+ * 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.
  */
-declare function anyAsync<const T extends readonly MaybeAsyncResult<unknown, unknown, unknown>[]>(results: T): Promise<Result<AnyAsyncValue<T>, AnyAsyncErrors<T> | EmptyInputError | PromiseRejectedError, AnyAsyncCauses<T> | PromiseRejectionCause>>;
-type AllAsyncValues<T extends readonly MaybeAsyncResult<unknown, unknown, unknown>[]> = {
-    [K in keyof T]: Awaited<T[K]> extends Result<infer V, unknown, unknown> ? V : never;
+type PendingHook = {
+    type: "PENDING_HOOK";
+    hookId: string;
+    /** Step key used in resume state; always "hook:" + hookId */
+    stepKey: string;
+    metadata?: Record<string, unknown>;
 };
-type AllAsyncErrors<T extends readonly MaybeAsyncResult<unknown, unknown, unknown>[]> = {
-    [K in keyof T]: Awaited<T[K]> extends Result<unknown, infer E, unknown> ? E : never;
-}[number];
-type AllAsyncCauses<T extends readonly MaybeAsyncResult<unknown, unknown, unknown>[]> = {
-    [K in keyof T]: Awaited<T[K]> extends Result<unknown, unknown, infer C> ? C : never;
-}[number];
 /**
- * Combines multiple Results or Promises of Results, collecting all errors (async version of `allSettled`).
- *
- * ## When to Use
- *
- * Use `allSettledAsync()` when:
- * - You have multiple async operations and need ALL errors reported
- * - You're doing async form validation (show all field errors at once)
- * - You want to run operations in parallel and collect all results
- *
- * ## Behavior
- *
- * **Note:** Unlike `Promise.allSettled()`, this returns a Result:
- * - `ok(values[])` if ALL succeed
- * - `err(SettledError[])` if ANY fail (with all collected errors)
- *
- * This is consistent with awaitly's philosophy - all functions return Results.
- * `Promise.allSettled()` always succeeds with per-item status objects; this function
- * returns a single Result indicating overall success or failure.
- *
- * ## Why Use This Instead of `allSettled`
- *
- * - **Parallel execution**: All Promises start immediately (faster)
- * - **Async support**: Works with Promises and AsyncResults
- * - **Promise rejection handling**: Converts Promise rejections to `PromiseRejectedError`
- *
- * ## Important
- *
- * - **No short-circuit**: All operations complete (even if some fail)
- * - **Parallel**: All operations run simultaneously
- * - **Error array**: Returns array of `SettledError` objects (`{ error, cause? }`)
- *
- * @param results - Array of Results or Promises of Results to combine (all are evaluated)
- * @returns A Promise resolving to a Result with:
- *   - `ok(values[])` - Array of all success values if ALL succeed
- *   - `err(errors[])` - Array of `SettledError` objects if ANY fail
- *
- * @example
- * ```typescript
- * // Async form validation - see all errors at once
- * const validated = await allSettledAsync([
- *   validateEmailAsync(email),
- *   validatePasswordAsync(password),
- *   checkUsernameAvailableAsync(username),
- * ]);
- *
- * if (!validated.ok) {
- *   // validated.error is array of all validation failures
- *   console.log('Errors:', validated.error.map(e => e.error));
- * }
- *
- * // Parallel API calls with error collection
- * const results = await allSettledAsync([
- *   fetchUser('1'),
- *   fetchUser('2'),
- *   fetchUser('3'),
- * ]);
- * ```
+ * 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.
  */
-declare function allSettledAsync<const T extends readonly MaybeAsyncResult<unknown, unknown, unknown>[]>(results: T): Promise<Result<AllAsyncValues<T>, SettledError<AllAsyncErrors<T> | PromiseRejectedError, AllAsyncCauses<T> | PromiseRejectionCause>[]>>;
+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 { orElseAsync as $, AWAITLY_CANCELLED as A, extractStepMetadata as B, type CauseOf as C, from as D, type EmptyInputError as E, fromNullable as F, fromPromise as G, hydrate as H, isErr as I, isOk as J, isSerializedResult as K, isUnexpectedError as L, type MatchErrorHandlers as M, lookupErrorClassification as N, type Ok as O, PROMISE_REJECTED as P, map as Q, type Result as R, type SettledError as S, mapError as T, UnwrapError as U, mapErrorTry as V, mapTry as W, match as X, matchError as Y, ok as Z, orElse as _, AWAITLY_TIMEOUT as a, partition as a0, recover as a1, recoverAsync as a2, runOrNull as a3, runOrThrow as a4, runOrThrowAsync as a5, runOrUndefined as a6, tags as a7, tap as a8, tapError as a9, tryAsync as aa, unwrap as ab, unwrapOr as ac, unwrapOrElse as ad, type WorkflowEvent as ae, type RunStep as af, type RetryOptions as ag, type BackoffStrategy as ah, type BoundSteps as ai, type StepOptions as aj, type RunOptions as ak, type RunOptionsWithCatch as al, type RunOptionsWithoutCatch as am, STEP_TIMEOUT_MARKER as an, type ScopeType as ao, type StepTimeoutError as ap, type StepTimeoutMarkerMeta as aq, type TimeoutOptions as ar, getStepTimeoutMeta as as, isStepTimeoutError as at, run as au, type StepFailureMeta as av, EARLY_EXIT_SYMBOL as aw, type EarlyExit as ax, createEarlyExit as ay, isEarlyExit as az, AWAITLY_UNEXPECTED as b, type AsyncResult as c, type Err as d, type ErrorClassification as e, type ErrorOf as f, type Errors as g, type ErrorsOf as h, type ExtractCause as i, type ExtractError as j, type ExtractValue as k, type MaybeAsyncResult as l, type PromiseRejectedError as m, type PromiseRejectionCause as n, type StepErrorDiagnostics as o, type StepMetadata as p, all as q, allAsync as r, allSettled as s, allSettledAsync as t, andThen as u, any as v, anyAsync as w, bimap as x, err as y, extractErrorTag as z };
+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 };