runsheet 0.4.0 → 0.6.0

package/dist/index.d.ts

@@ -1,6 +1,26 @@
-import { ParserSchema, Result, Success, Failure } from 'composable-functions';
-export { Failure, Result, Success } from 'composable-functions';
-
+/**
+ * A schema that can parse/validate unknown data.
+ *
+ * This is the structural interface that Zod schemas (and other schema
+ * libraries) satisfy. runsheet does not depend on any specific schema
+ * library — any object with a `safeParse` method works.
+ *
+ * @typeParam T - The validated output type.
+ */
+type StepSchema<T> = {
+    safeParse(data: unknown): {
+        success: true;
+        data: T;
+    } | {
+        success: false;
+        error: {
+            issues: readonly {
+                path: readonly (string | number)[];
+                message: string;
+            }[];
+        };
+    };
+};
 /**
  * The type-erased context shape used at runtime by the pipeline engine.
  *
@@ -34,18 +54,18 @@ type Step = {
     /** Unique name identifying this step in metadata and rollback reports. */
     readonly name: string;
     /** Optional schema that validates the accumulated context before `run`. */
-    readonly requires: ParserSchema<StepContext> | undefined;
+    readonly requires: StepSchema<StepContext> | undefined;
     /** Optional schema that validates the step's output after `run`. */
-    readonly provides: ParserSchema<StepOutput> | undefined;
+    readonly provides: StepSchema<StepOutput> | undefined;
     /**
      * Execute the step. Receives the accumulated context and returns a
-     * `Result` — either `{ success: true, data }` or
-     * `{ success: false, errors }`.
+     * {@link StepResult} — either a success with `data` or a failure with
+     * `error`, `failedStep`, and `rollback`.
      *
      * Step authors never call this directly; the pipeline engine calls it
-     * after validating `requires` and wrapping with middleware.
+     * after wrapping with middleware.
      */
-    readonly run: (ctx: Readonly<StepContext>) => Promise<Result<StepOutput>>;
+    readonly run: (ctx: Readonly<StepContext>) => Promise<StepResult<StepOutput>>;
     /**
      * Optional rollback handler, called when a later step fails.
      *
@@ -62,6 +82,10 @@ type Step = {
  * Phantom type brands for compile-time tracking of step I/O types.
  * These symbols never exist at runtime — they only guide TypeScript's
  * type checker through the builder's progressive type narrowing.
+ *
+ * `RequiresBrand` uses a function type for contravariance: a step that
+ * requires `StepContext` (anything) is usable where a narrower context
+ * is available. `ProvidesBrand` is covariant (a plain value brand).
  */
 declare const RequiresBrand: unique symbol;
 declare const ProvidesBrand: unique symbol;
@@ -76,13 +100,17 @@ declare const ProvidesBrand: unique symbol;
  * schemas or generics. When assigned to `Step` (e.g., in a pipeline's
  * step array), the intersection collapses to the erased signatures.
  *
+ * The typed properties appear BEFORE the `Step` intersection so that
+ * TypeScript's overload resolution picks the concrete signatures first
+ * when calling `run()` directly on a `TypedStep`.
+ *
  * @typeParam Requires - The context shape this step reads from.
  * @typeParam Provides - The output shape this step produces.
  *
  * @example
  * ```ts
  * // Hover over `step.run` to see:
- * //   (ctx: Readonly<{ amount: number }>) => Promise<Result<{ chargeId: string }>>
+ * //   (ctx: Readonly<{ amount: number }>) => Promise<StepResult<{ chargeId: string }>>
  * const step = defineStep({
  *   name: 'charge',
  *   requires: z.object({ amount: z.number() }),
@@ -91,15 +119,15 @@ declare const ProvidesBrand: unique symbol;
  * });
  * ```
  */
-type TypedStep<Requires extends StepContext = StepContext, Provides extends StepContext = StepContext> = Step & {
-    readonly [RequiresBrand]: Requires;
+type TypedStep<Requires extends StepContext = StepContext, Provides extends StepContext = StepContext> = {
+    readonly [RequiresBrand]: (ctx: Requires) => void;
     readonly [ProvidesBrand]: Provides;
     /** Optional schema that validates the accumulated context before `run`. */
-    readonly requires: ParserSchema<Requires> | undefined;
+    readonly requires: StepSchema<Requires> | undefined;
     /** Optional schema that validates the step's output after `run`. */
-    readonly provides: ParserSchema<Provides> | undefined;
+    readonly provides: StepSchema<Provides> | undefined;
     /** Execute the step with concrete input/output types. */
-    readonly run: (ctx: Readonly<Requires>) => Promise<Result<Provides>>;
+    readonly run: (ctx: Readonly<Requires>) => Promise<StepResult<Provides>>;
     /**
      * Optional rollback handler, called when a later step fails.
      *
@@ -107,13 +135,30 @@ type TypedStep<Requires extends StepContext = StepContext, Provides extends Step
      * @param output - The frozen output this step produced.
      */
     readonly rollback: ((ctx: Readonly<Requires>, output: Readonly<Provides>) => Promise<void>) | undefined;
-};
+} & Step;
 /** Convert a union type to an intersection type. */
 type UnionToIntersection<U> = [U] extends [never] ? unknown : (U extends unknown ? (x: U) => void : never) extends (x: infer I) => void ? I : never;
-/** Extract the Requires type from a step. Returns `StepContext` for untyped (erased) steps. */
-type ExtractRequires<T extends Step> = T extends TypedStep<infer R, StepContext> ? R : StepContext;
-/** Extract the Provides type from a step. Returns `object` for untyped (erased) steps. */
-type ExtractProvides<T extends Step> = T extends TypedStep<StepContext, infer P> ? P : object;
+/**
+ * Extract the Requires type from a step via its phantom brand.
+ * Returns `StepContext` for untyped (erased) steps.
+ *
+ * Matches the contravariant function brand directly — avoids full
+ * structural matching on `TypedStep` which would fail due to
+ * `run` parameter contravariance in conditional types.
+ */
+type ExtractRequires<T extends Step> = T extends {
+    readonly [RequiresBrand]: (ctx: infer R) => void;
+} ? R : StepContext;
+/**
+ * Extract the Provides type from a step via its phantom brand.
+ * Returns `object` for untyped (erased) steps.
+ *
+ * Matches the covariant value brand directly — avoids full structural
+ * matching which would fail for steps with non-trivial Requires types.
+ */
+type ExtractProvides<T extends Step> = T extends {
+    readonly [ProvidesBrand]: infer P;
+} ? P : object;
 /**
  * Retry policy for a step's `run` function.
  *
@@ -160,23 +205,23 @@ type StepConfig<Requires extends StepContext, Provides extends StepContext> = {
     /**
      * Optional Zod (or Standard Schema compatible) schema that validates
      * the accumulated context before `run` is called. When provided, a
-     * schema validation failure produces a `Result` error — the step's
+     * schema validation failure produces a `StepResult` error — the step's
      * `run` function is never invoked.
      */
-    requires?: ParserSchema<Requires>;
+    requires?: StepSchema<Requires>;
     /**
      * Optional Zod (or Standard Schema compatible) schema that validates
      * the step's output after `run` returns. When provided, a schema
-     * validation failure produces a `Result` error even though `run`
+     * validation failure produces a `StepResult` error even though `run`
      * succeeded.
      */
-    provides?: ParserSchema<Provides>;
+    provides?: StepSchema<Provides>;
     /**
      * The step implementation. Receives the accumulated context (frozen)
      * and returns the step's output. Can be sync or async.
      *
      * To signal failure, throw an error. The pipeline catches it and
-     * produces a `Result` failure — do not return failure objects.
+     * produces a `StepResult` failure — do not return failure objects.
      *
      * @param ctx - The frozen accumulated context up to this point.
      * @returns The step's output, which is merged into the accumulated context.
@@ -219,7 +264,7 @@ type RollbackFailure = {
     readonly error: Error;
 };
 /**
- * Summary of rollback execution after a pipeline failure.
+ * Summary of rollback execution after a step or pipeline failure.
  *
  * Rollback is best-effort: every completed step's rollback handler is
  * attempted in reverse order, regardless of whether earlier handlers
@@ -232,69 +277,153 @@ type RollbackReport = {
     readonly failed: readonly RollbackFailure[];
 };
 /**
- * Metadata about a pipeline execution, present on both success and failure
+ * Metadata about a step execution, present on both success and failure
  * results. Useful for logging, debugging, and observability.
  */
-type PipelineExecutionMeta = {
-    /** The pipeline's name as passed to `buildPipeline` or `createPipeline`. */
-    readonly pipeline: string;
-    /** The original arguments passed to `pipeline.run()`. */
+type StepMeta = {
+    /** The step's name (or pipeline name for pipeline-steps). */
+    readonly name: string;
+    /** The original arguments/context passed to `step.run()`. */
     readonly args: Readonly<StepContext>;
+};
+/**
+ * Extended metadata for orchestrator results (pipelines, parallel,
+ * choice).
+ *
+ * Includes orchestration detail — which steps ran — on top of the
+ * base {@link StepMeta}. Present on results from `pipeline()`,
+ * `parallel()`, and `choice()`.
+ */
+type AggregateMeta = StepMeta & {
     /** Names of steps that executed successfully, in order. */
     readonly stepsExecuted: readonly string[];
-    /** Names of conditional steps that were skipped (predicate returned false). */
-    readonly stepsSkipped: readonly string[];
 };
 /**
- * A successful pipeline result.
+ * A successful step result.
  *
- * Extends composable-functions' `Success<T>` with pipeline execution
- * metadata. The `data` property contains the fully accumulated context
- * (initial args merged with all step outputs).
+ * The `data` property contains the step's output (or the fully
+ * accumulated context for pipeline-steps).
  *
- * @typeParam T - The accumulated context type.
+ * @typeParam T - The output type.
  */
-type PipelineSuccess<T> = Success<T> & {
-    /** Pipeline execution metadata. */
-    readonly meta: PipelineExecutionMeta;
+type StepSuccess<T> = {
+    readonly success: true;
+    /** The step's output data. */
+    readonly data: T;
+    /** Step execution metadata. */
+    readonly meta: StepMeta;
 };
 /**
- * A failed pipeline result.
- *
- * Extends composable-functions' `Failure` with the name of the step that
- * failed, a rollback report, and pipeline execution metadata.
+ * A failed step result.
  *
- * On failure, rollback handlers for all previously completed steps are
- * executed in reverse order before this result is returned.
+ * Contains the error that caused the failure, the name of the step
+ * that failed, and a rollback report.
  */
-type PipelineFailure = Failure & {
-    /** Pipeline execution metadata. */
-    readonly meta: PipelineExecutionMeta;
+type StepFailure = {
+    readonly success: false;
+    /** The error that caused the failure. Use `AggregateError` when multiple errors occur. */
+    readonly error: Error;
+    /** Step execution metadata. */
+    readonly meta: StepMeta;
     /** Name of the step that failed. */
     readonly failedStep: string;
     /** Report of which rollback handlers succeeded and which threw. */
     readonly rollback: RollbackReport;
 };
 /**
- * The result of running a pipeline — either a success or a failure.
+ * The result of running a step — either a success or a failure.
  *
  * Use the `success` discriminant to narrow:
  *
  * ```ts
- * const result = await pipeline.run(args);
+ * const result = await step.run(ctx);
  * if (result.success) {
- *   result.data;       // fully typed accumulated context
+ *   result.data;       // the step's output
  *   result.meta;       // execution metadata
  * } else {
- *   result.errors;     // what went wrong
+ *   result.error;      // what went wrong
  *   result.failedStep; // which step failed
  *   result.rollback;   // { completed: [...], failed: [...] }
  * }
  * ```
  *
- * @typeParam T - The accumulated context type on success.
+ * @typeParam T - The output type on success.
  */
-type PipelineResult<T> = PipelineSuccess<T> | PipelineFailure;
+type StepResult<T> = StepSuccess<T> | StepFailure;
+/**
+ * A successful orchestrator result.
+ *
+ * Identical to {@link StepSuccess} but with {@link AggregateMeta}
+ * instead of {@link StepMeta}, providing orchestration detail.
+ *
+ * @typeParam T - The accumulated output type.
+ */
+type AggregateSuccess<T> = {
+    readonly success: true;
+    /** The accumulated output after all inner steps. */
+    readonly data: T;
+    /** Orchestrator execution metadata including step tracking. */
+    readonly meta: AggregateMeta;
+};
+/**
+ * A failed orchestrator result.
+ *
+ * Identical to {@link StepFailure} but with {@link AggregateMeta}
+ * instead of {@link StepMeta}, providing orchestration detail.
+ */
+type AggregateFailure = {
+    readonly success: false;
+    /** The error that caused the failure. */
+    readonly error: Error;
+    /** Orchestrator execution metadata including step tracking. */
+    readonly meta: AggregateMeta;
+    /** Name of the step that failed. */
+    readonly failedStep: string;
+    /** Report of which rollback handlers succeeded and which threw. */
+    readonly rollback: RollbackReport;
+};
+/**
+ * The result of running an orchestrator — extends {@link StepResult}
+ * with richer metadata.
+ *
+ * `AggregateResult<T>` is assignable to `StepResult<T>`, so
+ * orchestrators (`pipeline`, `parallel`, `choice`) satisfy the `Step`
+ * interface while providing orchestration detail to callers.
+ *
+ * ```ts
+ * const checkout = pipeline({ name: 'checkout', steps: [...] });
+ * const result = await checkout.run({ orderId: '123' });
+ * if (result.success) {
+ *   result.meta.stepsExecuted; // string[] — which steps ran
+ * } else {
+ *   result.meta.stepsExecuted; // string[] — which steps ran
+ *   result.failedStep;         // which step failed
+ *   result.rollback;           // { completed, failed }
+ * }
+ * ```
+ *
+ * @typeParam T - The accumulated output type on success.
+ */
+type AggregateResult<T> = AggregateSuccess<T> | AggregateFailure;
+/**
+ * A step that orchestrates other steps and returns rich results.
+ *
+ * Extends {@link TypedStep} with a narrower `run()` that returns
+ * {@link AggregateResult} instead of {@link StepResult}. This is the
+ * type returned by `pipeline()`, `parallel()`, and `choice()`.
+ *
+ * The `run` property uses an explicit overloaded function type:
+ * the first overload returns `AggregateResult` (matched when calling
+ * directly), the second preserves the erased `Step.run` signature
+ * (for `Step` assignability when used in pipeline arrays).
+ *
+ * @typeParam Requires - The input type.
+ * @typeParam Provides - The accumulated output type.
+ */
+type AggregateStep<Requires extends StepContext = StepContext, Provides extends StepContext = StepContext> = {
+    /** Execute the orchestrator and return an {@link AggregateResult}. */
+    readonly run: (ctx: Readonly<Requires>) => Promise<AggregateResult<Provides>>;
+} & TypedStep<Requires, Provides>;
 
 /**
  * Define a pipeline step.
@@ -323,9 +452,8 @@ type PipelineResult<T> = PipelineSuccess<T> | PipelineFailure;
  *
  * **Invariants:**
  * - The returned step object is always frozen (immutable).
- * - The `run` function is wrapped with `composable()` from
- *   composable-functions, which catches thrown errors and produces
- *   `Result` values. Step authors should throw to signal failure.
+ * - The `run` function catches thrown errors and produces
+ *   `StepResult` values. Step authors should throw to signal failure.
  * - This is the single type-erasure cast point in the library.
  *
  * @typeParam Requires - The context shape this step reads from.
@@ -338,31 +466,28 @@ declare function defineStep<Requires extends StepContext, Provides extends StepC
 /**
  * Error codes for errors produced by the runsheet library itself.
  *
- * Use these to distinguish library errors from application errors
- * in a pipeline's `errors` array:
+ * Use these to distinguish library errors from application errors:
  *
  * ```ts
  * if (!result.success) {
- *   for (const error of result.errors) {
- *     if (error instanceof RunsheetError) {
- *       console.log(error.code); // 'REQUIRES_VALIDATION', etc.
- *     }
+ *   if (result.error instanceof RunsheetError) {
+ *     console.log(result.error.code); // 'REQUIRES_VALIDATION', etc.
  *   }
  * }
  * ```
  */
-type RunsheetErrorCode = 'REQUIRES_VALIDATION' | 'PROVIDES_VALIDATION' | 'ARGS_VALIDATION' | 'PREDICATE' | 'TIMEOUT' | 'RETRY_EXHAUSTED' | 'STRICT_OVERLAP';
+type RunsheetErrorCode = 'REQUIRES_VALIDATION' | 'PROVIDES_VALIDATION' | 'ARGS_VALIDATION' | 'PREDICATE' | 'TIMEOUT' | 'RETRY_EXHAUSTED' | 'STRICT_OVERLAP' | 'CHOICE_NO_MATCH' | 'ROLLBACK' | 'UNKNOWN';
 /**
  * Base error class for all errors produced by the runsheet library.
  *
  * Application errors (thrown by step `run` or `rollback` functions)
  * are never wrapped in `RunsheetError` — they pass through as-is.
- * If you see a `RunsheetError` in a result's `errors` array, the
- * library itself produced it.
+ * If you see a `RunsheetError` as `result.error`, the library itself
+ * produced it.
  *
  * Use `instanceof RunsheetError` to distinguish library errors from
- * application errors, and the `code` property to identify the
- * specific failure.
+ * application errors. Use `instanceof` on a subclass (e.g.,
+ * `TimeoutError`) or check the `code` property for specific failures.
  */
 declare class RunsheetError extends Error {
     /** Discriminant code identifying the type of library error. */
@@ -373,6 +498,58 @@ declare class RunsheetError extends Error {
      */
     constructor(code: RunsheetErrorCode, message: string);
 }
+/** Schema validation failed on the accumulated context before a step ran. */
+declare class RequiresValidationError extends RunsheetError {
+    constructor(message: string);
+}
+/** Schema validation failed on a step's output after it ran. */
+declare class ProvidesValidationError extends RunsheetError {
+    constructor(message: string);
+}
+/** Schema validation failed on the pipeline's input arguments. */
+declare class ArgsValidationError extends RunsheetError {
+    constructor(message: string);
+}
+/** A `when()` or `choice()` predicate threw an error. */
+declare class PredicateError extends RunsheetError {
+    constructor(message: string);
+}
+/** A step exceeded its configured timeout. */
+declare class TimeoutError extends RunsheetError {
+    /** The timeout duration in milliseconds that was exceeded. */
+    readonly timeoutMs: number;
+    constructor(message: string, timeoutMs: number);
+}
+/** A step failed after exhausting all retry attempts. */
+declare class RetryExhaustedError extends RunsheetError {
+    /** Total number of attempts (initial + retries). */
+    readonly attempts: number;
+    constructor(message: string, attempts: number);
+}
+/** Two steps provide the same key (strict mode, detected at build time). */
+declare class StrictOverlapError extends RunsheetError {
+    /** The key that is provided by multiple steps. */
+    readonly key: string;
+    /** The names of the two steps that both provide the key. */
+    readonly steps: readonly [string, string];
+    constructor(message: string, key: string, steps: readonly [string, string]);
+}
+/** No branch matched in a `choice()` step. */
+declare class ChoiceNoMatchError extends RunsheetError {
+    constructor(message: string);
+}
+/** A non-Error value was thrown and caught by the pipeline engine. */
+declare class UnknownError extends RunsheetError {
+    /** The original thrown value before stringification. */
+    readonly originalValue: unknown;
+    constructor(message: string, originalValue: unknown);
+}
+/** One or more rollback handlers failed in a combinator. */
+declare class RollbackError extends RunsheetError {
+    /** The individual errors from each failed rollback handler. */
+    readonly causes: readonly Error[];
+    constructor(message: string, causes?: readonly Error[]);
+}
 
 /**
  * Metadata about the step being executed, passed to middleware.
@@ -391,10 +568,9 @@ type StepInfo = {
 /**
  * A function that executes a step (or the next middleware in the chain).
  *
- * Receives the frozen accumulated context and returns a `Result` — either
- * `{ success: true, data }` or `{ success: false, errors }`.
+ * Receives the frozen accumulated context and returns a {@link StepResult}.
  */
-type StepExecutor = (ctx: Readonly<StepContext>) => Promise<Result<StepOutput>>;
+type StepExecutor = (ctx: Readonly<StepContext>) => Promise<StepResult<StepOutput>>;
 /**
  * Middleware that wraps the entire step lifecycle, including schema
  * validation.
@@ -405,7 +581,7 @@ type StepExecutor = (ctx: Readonly<StepContext>) => Promise<Result<StepOutput>>;
  *
  * - **Observe**: read the context or result for logging/metrics.
  * - **Transform**: modify the result before returning it.
- * - **Short-circuit**: return a `Result` without calling `next`.
+ * - **Short-circuit**: return a `StepResult` without calling `next`.
  *
  * If a middleware throws, the pipeline catches it and treats it as a
  * step failure (triggering rollback for previously completed steps).
@@ -426,11 +602,58 @@ type StepExecutor = (ctx: Readonly<StepContext>) => Promise<Result<StepOutput>>;
  */
 type StepMiddleware = (step: StepInfo, next: StepExecutor) => StepExecutor;
 
+/**
+ * A fluent pipeline builder that progressively narrows the accumulated
+ * context type as steps are added.
+ *
+ * Each method returns a new, frozen builder — builders are immutable.
+ *
+ * This means you can safely fork a builder to create variants:
+ *
+ * ```ts
+ * const base = pipeline({ name: 'order' }).step(validate);
+ * const withCharge = base.step(charge).build();
+ * const withoutCharge = base.build(); // unaffected by the fork
+ * ```
+ *
+ * @typeParam Args - The pipeline's initial input type.
+ * @typeParam Ctx - The accumulated context type so far (grows with each `.step()`).
+ */
+type PipelineBuilder<Args extends StepContext, Ctx extends StepContext> = {
+    /**
+     * Add a step to the pipeline.
+     *
+     * The step's `Requires` type must be satisfied by the current `Ctx`
+     * (checked via phantom brands — a step that requires less than `Ctx`
+     * is always accepted). The returned builder's `Ctx` expands to
+     * include the step's `Provides`.
+     *
+     * @typeParam S - The step type being added.
+     * @param step - A {@link Step} (from `defineStep`, `when`, `pipeline`, etc.).
+     * @returns A new builder with the expanded context type.
+     */
+    readonly step: <S extends Step>(step: S & ([Ctx] extends [ExtractRequires<S>] ? unknown : never)) => PipelineBuilder<Args, Ctx & ExtractProvides<S>>;
+    /**
+     * Add middleware to the pipeline.
+     *
+     * Middleware is applied to every step. Multiple `.use()` calls
+     * accumulate — earlier middleware is outermost (executes first).
+     *
+     * @param middleware - One or more {@link StepMiddleware} functions.
+     * @returns A new builder with the middleware added.
+     */
+    readonly use: (...middleware: StepMiddleware[]) => PipelineBuilder<Args, Ctx>;
+    /**
+     * Build the pipeline. Returns an {@link AggregateStep} — pipelines
+     * are steps whose `run()` returns {@link AggregateResult}.
+     */
+    readonly build: () => AggregateStep<Args, Ctx>;
+};
+
 /**
  * Internal configuration shape for the pipeline engine.
  *
- * Users typically don't construct this directly — use `buildPipeline()`
- * or `createPipeline()` instead.
+ * Users typically don't construct this directly — use `pipeline()`.
  */
 type PipelineConfig = {
     /** Pipeline name, used in execution metadata and error messages. */
@@ -440,7 +663,7 @@ type PipelineConfig = {
     /** Optional middleware applied to every step. First in array = outermost. */
     readonly middleware?: readonly StepMiddleware[];
     /** Optional schema that validates the pipeline's input arguments. */
-    readonly argsSchema?: ParserSchema<StepContext>;
+    readonly argsSchema?: StepSchema<StepContext>;
     /**
      * When `true`, throws at build time if two or more steps provide the
      * same key. Only checks steps that have a `provides` schema with an
@@ -450,89 +673,57 @@ type PipelineConfig = {
     readonly strict?: boolean;
 };
 /**
- * A built pipeline, ready to execute.
- *
- * Call `run(args)` to execute the pipeline. The result is a
- * {@link PipelineResult} — either a success with the fully accumulated
- * context, or a failure with error details and a rollback report.
+ * Create a pipeline — either directly from steps, or via the fluent
+ * builder API.
  *
- * Pipeline objects are frozen (immutable) and can be called repeatedly.
+ * **With steps** — returns an {@link AggregateStep} immediately:
  *
- * @typeParam Args - The input type accepted by `run()`.
- * @typeParam Ctx - The accumulated output type on success.
- */
-type Pipeline<Args extends StepContext, Ctx> = {
-    /** The pipeline's name, as provided at build time. */
-    readonly name: string;
-    /**
-     * Execute the pipeline.
-     *
-     * @param args - The initial arguments. Merged into the context before
-     *   the first step runs. Validated against `argsSchema` if one was
-     *   provided.
-     * @returns A {@link PipelineResult} — discriminate on `success` to
-     *   access `data` (on success) or `errors`/`rollback` (on failure).
-     */
-    readonly run: (args: Args) => Promise<PipelineResult<Ctx>>;
-};
-/**
- * Build a pipeline from an array of steps.
- *
- * The result type is inferred from the steps — `pipeline.run()` returns
- * a {@link PipelineResult} whose `data` is the intersection of the
- * initial `Args` and all step output types.
- *
- * @example
  * ```ts
- * const pipeline = buildPipeline({
- *   name: 'placeOrder',
+ * const checkout = pipeline({
+ *   name: 'checkout',
  *   steps: [validateOrder, chargePayment, sendConfirmation],
  *   middleware: [logging, timing],
  *   argsSchema: z.object({ orderId: z.string() }),
  * });
- *
- * const result = await pipeline.run({ orderId: '123' });
- * if (result.success) {
- *   result.data.chargeId; // string — fully typed
- * }
  * ```
  *
- * **Execution semantics:**
- * - Steps execute sequentially in array order.
- * - Context is frozen (`Object.freeze`) at every step boundary.
- * - Conditional steps (wrapped with `when()`) are skipped when their
- *   predicate returns false — no snapshot, no rollback entry.
- * - On step failure, rollback handlers for all previously completed
- *   steps execute in reverse order (best-effort).
- * - Middleware wraps the full step lifecycle including schema validation.
+ * **Without steps** — returns a {@link PipelineBuilder} with
+ * progressive type narrowing:
  *
- * **Invariants:**
- * - The returned pipeline object is frozen (immutable).
- * - Errors thrown by steps, predicates, or middleware are caught and
- *   returned as `PipelineFailure` — `run()` never throws.
- *
- * @typeParam Args - The pipeline's input type. Inferred from `argsSchema`
- *   if provided, otherwise defaults to `StepContext`.
- * @typeParam S - The step types in the array. Inferred automatically —
- *   do not specify manually.
- * @param config - Pipeline configuration.
- * @param config.name - Pipeline name, used in metadata and error messages.
- * @param config.steps - Steps to execute in order.
- * @param config.middleware - Optional middleware applied to every step.
- *   First in array = outermost wrapper.
- * @param config.argsSchema - Optional schema that validates `args` before
- *   any steps run. Validation failure produces a `PipelineFailure` with
- *   `failedStep` set to the pipeline name.
- * @returns A frozen {@link Pipeline} whose `run()` method executes the
- *   steps and returns a {@link PipelineResult}.
- */
-declare function buildPipeline<Args extends StepContext = StepContext, S extends Step = Step>(config: {
+ * ```ts
+ * const checkout = pipeline({ name: 'checkout' })
+ *   .step(validateOrder)
+ *   .step(chargePayment)
+ *   .build();
+ *
+ * // With schema (runtime validation):
+ * pipeline({
+ *   name: 'checkout',
+ *   argsSchema: z.object({ orderId: z.string() }),
+ * }).step(validateOrder).build();
+ *
+ * // Type-only args (no runtime validation):
+ * pipeline<{ orderId: string }>({ name: 'checkout' })
+ *   .step(validateOrder)
+ *   .build();
+ * ```
+ *
+ * Pipelines ARE steps — they can be used directly in another
+ * pipeline's steps array for composition.
+ */
+declare function pipeline<Args extends StepContext = StepContext, S extends Step = Step>(config: {
     readonly name: string;
     readonly steps: readonly S[];
     readonly middleware?: readonly StepMiddleware[];
-    readonly argsSchema?: ParserSchema<Args>;
+    readonly argsSchema?: StepSchema<Args>;
     readonly strict?: boolean;
-}): Pipeline<Args, Args & UnionToIntersection<ExtractProvides<S>>>;
+}): AggregateStep<Args, Args & UnionToIntersection<ExtractProvides<S>>>;
+declare function pipeline<Args extends StepContext = StepContext>(config: {
+    readonly name: string;
+    readonly middleware?: readonly StepMiddleware[];
+    readonly argsSchema?: StepSchema<Args>;
+    readonly strict?: boolean;
+}): PipelineBuilder<Args, Args>;
 
 /**
  * A step with a conditional predicate attached.
@@ -552,24 +743,9 @@ type ConditionalStep = Step & {
  * skipped:
  * - No context snapshot is taken.
  * - No rollback entry is created.
- * - The step name is recorded in `result.meta.stepsSkipped`.
- *
- * If the predicate throws, the pipeline treats it as a step failure
- * and triggers rollback for any previously completed steps.
+ * - The step name is not recorded in the pipeline's `meta.stepsExecuted`.
  *
- * @example
- * ```ts
- * const steps = [
- *   validateOrder,
- *   when((ctx) => ctx.order.amount > 100, notifyManager),
- *   sendConfirmation,
- * ];
- * ```
- *
- * @typeParam Requires - Inferred from the step's requires type.
- * @typeParam Provides - Inferred from the step's provides type.
- * @param predicate - Guard function. Receives the current accumulated
- *   context (frozen). Return `true` to execute, `false` to skip.
+ * @param predicate - Guard function. Return `true` to execute, `false` to skip.
  * @param step - The step to conditionally execute.
  * @returns A frozen {@link TypedStep} with the predicate attached.
  */
@@ -577,6 +753,7 @@ declare function when<Requires extends StepContext, Provides extends StepContext
 
 /** Ensure a type satisfies StepContext, falling back to StepContext. */
 type AsContext<T> = T extends StepContext ? T : StepContext;
+
 /**
  * Run multiple steps concurrently and merge their outputs.
  *
@@ -586,8 +763,8 @@ type AsContext<T> = T extends StepContext ? T : StepContext;
  * steps are rolled back in reverse array order before the failure
  * propagates.
  *
- * The returned step acts as a single step from the pipeline's
- * perspective — middleware wraps the group as a whole.
+ * Returns an {@link AggregateStep} with orchestration metadata
+ * tracking which inner steps executed.
  *
  * Inner steps retain their own `requires`/`provides` validation,
  * `retry`, and `timeout` behavior. Conditional steps (via `when()`)
@@ -595,7 +772,7 @@ type AsContext<T> = T extends StepContext ? T : StepContext;
  *
  * @example
  * ```ts
- * const pipeline = buildPipeline({
+ * const p = pipeline({
  *   name: 'checkout',
  *   steps: [
  *     validateOrder,
@@ -606,105 +783,182 @@ type AsContext<T> = T extends StepContext ? T : StepContext;
  * ```
  *
  * @param steps - Two or more steps to execute concurrently.
- * @returns A frozen {@link TypedStep} whose `Requires` is the
+ * @returns A frozen {@link AggregateStep} whose `Requires` is the
  *   intersection of all inner steps' requires, and `Provides` is the
  *   intersection of all inner steps' provides.
  */
-declare function parallel<S extends readonly TypedStep[]>(...steps: [...S]): TypedStep<AsContext<UnionToIntersection<ExtractRequires<S[number]>>>, AsContext<UnionToIntersection<ExtractProvides<S[number]>>>>;
+declare function parallel<S extends readonly Step[]>(...steps: [...S]): AggregateStep<AsContext<UnionToIntersection<ExtractRequires<S[number]>>>, AsContext<UnionToIntersection<ExtractProvides<S[number]>>>>;
 
+/** A [predicate, step] tuple used by {@link choice}. */
+type BranchTuple = readonly [(ctx: Readonly<StepContext>) => boolean, Step];
+/** Extract the Requires type from a branch tuple's step. */
+type BranchRequires<T> = T extends readonly [unknown, infer S extends Step] ? ExtractRequires<S> : T extends Step ? ExtractRequires<T> : StepContext;
+/** Extract the Provides type from a branch tuple's step. */
+type BranchProvides<T> = T extends readonly [unknown, infer S extends Step] ? ExtractProvides<S> : T extends Step ? ExtractProvides<T> : StepContext;
 /**
- * A fluent pipeline builder that progressively narrows the accumulated
- * context type as steps are added.
+ * Execute the first branch whose predicate returns `true`.
  *
- * Each method returns a new, frozen builder — builders are immutable.
- * This means you can safely fork a builder to create variants:
+ * Similar to an AWS Step Functions Choice state — predicates are evaluated
+ * in order, and the first match wins. Exactly one branch executes. If no
+ * predicate matches, the step fails with a `CHOICE_NO_MATCH` error.
+ *
+ * A bare step (without a predicate tuple) can be passed as the last argument
+ * to serve as a default branch — it is equivalent to `[() => true, step]`.
+ *
+ * Returns an {@link AggregateStep} with orchestration metadata
+ * tracking which branch executed.
  *
+ * All branches should provide the same output shape so that
+ * subsequent steps can rely on a consistent context type.
+ *
+ * @example
  * ```ts
- * const base = createPipeline('order').step(validate);
- * const withCharge = base.step(charge).build();
- * const withoutCharge = base.build(); // unaffected by the fork
+ * const p = pipeline({
+ *   name: 'payment',
+ *   steps: [
+ *     validateOrder,
+ *     choice(
+ *       [(ctx) => ctx.method === 'card', chargeCard],
+ *       [(ctx) => ctx.method === 'bank', chargeBankTransfer],
+ *       chargeDefault, // default
+ *     ),
+ *     sendReceipt,
+ *   ],
+ * });
  * ```
  *
- * @typeParam Args - The pipeline's initial input type.
- * @typeParam Ctx - The accumulated context type so far (grows with each `.step()`).
+ * @param branches - One or more `[predicate, step]` tuples, optionally
+ *   followed by a bare step as the default.
+ * @returns A frozen {@link AggregateStep} that executes the first
+ *   matching branch.
  */
-type PipelineBuilder<Args extends StepContext, Ctx extends StepContext> = {
-    /**
-     * Add a step to the pipeline.
-     *
-     * The step's `Requires` type must be satisfied by the current `Ctx`.
-     * The returned builder's `Ctx` expands to include the step's `Provides`.
-     *
-     * @typeParam Provides - The output type of the step being added.
-     * @param step - A {@link TypedStep} (from `defineStep` or `when`).
-     * @returns A new builder with the expanded context type.
-     */
-    readonly step: <Provides extends StepContext>(step: TypedStep<Ctx, Provides>) => PipelineBuilder<Args, Ctx & Provides>;
-    /**
-     * Add middleware to the pipeline.
-     *
-     * Middleware is applied to every step. Multiple `.use()` calls
-     * accumulate — earlier middleware is outermost (executes first).
-     *
-     * @param middleware - One or more {@link StepMiddleware} functions.
-     * @returns A new builder with the middleware added.
-     */
-    readonly use: (...middleware: StepMiddleware[]) => PipelineBuilder<Args, Ctx>;
-    /**
-     * Build the pipeline.
-     *
-     * @returns A frozen {@link Pipeline} ready to execute with `run()`.
-     */
-    readonly build: () => Pipeline<Args, Ctx>;
-};
+declare function choice<B extends readonly BranchTuple[]>(...branches: [...B]): AggregateStep<AsContext<UnionToIntersection<BranchRequires<B[number]>>>, AsContext<UnionToIntersection<BranchProvides<B[number]>>>>;
+declare function choice<B extends readonly BranchTuple[], D extends Step>(...args: [...B, D]): AggregateStep<AsContext<UnionToIntersection<BranchRequires<B[number]> | ExtractRequires<D>>>, AsContext<UnionToIntersection<BranchProvides<B[number]> | ExtractProvides<D>>>>;
+
 /**
- * Start building a pipeline with the fluent builder API.
+ * Iterate over a collection and run a function or step per item, concurrently.
  *
- * The builder gives progressive type narrowing — each `.step()` call
- * extends the known context type, so TypeScript catches mismatches
- * at compile time.
+ * **Function form:** `(item, ctx) => result` — items can be any type.
  *
- * **Type-only args** (no runtime validation):
- * ```ts
- * createPipeline<{ orderId: string }>('placeOrder')
- *   .step(validateOrder)
- *   .step(chargePayment)
- *   .build();
- * ```
+ * **Step form:** each item must be an object whose keys are spread into
+ * the pipeline context before the step runs.
  *
- * **Schema args** (runtime validation + type inference):
+ * The step receives `{ ...ctx, ...item }`. The step's own
+ * `requires`/`provides` validation, `retry`, and `timeout` apply
+ * per item. On partial failure, succeeded items are rolled back
+ * (if the step has a rollback handler).
+ *
+ * @example
  * ```ts
- * createPipeline('placeOrder', z.object({ orderId: z.string() }))
- *   .step(validateOrder)
- *   .step(chargePayment)
- *   .build();
+ * // Function form
+ * const pipeline = pipeline({
+ *   name: 'notify',
+ *   steps: [
+ *     map('emails', (ctx) => ctx.users, async (user) => {
+ *       await sendEmail(user.email);
+ *       return { email: user.email, sentAt: new Date() };
+ *     }),
+ *   ],
+ * });
+ *
+ * // Step form
+ * const pipeline = pipeline({
+ *   name: 'process',
+ *   steps: [
+ *     map('results', (ctx) => ctx.items, processItem),
+ *   ],
+ * });
  * ```
  *
- * **Strict mode** (no schema):
+ * @param key - The output key under which results are collected.
+ * @param collection - A selector that extracts the collection from context.
+ * @param fnOrStep - A per-item function or a step to execute for each item.
+ * @returns A frozen {@link TypedStep} that provides `{ [key]: Result[] }`.
+ */
+declare function map<K extends string, Item, Result, Ctx extends StepContext = StepContext>(key: K, collection: (ctx: Readonly<Ctx>) => Item[], fn: (item: Item, ctx: Readonly<Ctx>) => Result | Promise<Result>): TypedStep<Ctx, Record<K, Awaited<Result>[]>>;
+declare function map<K extends string, S extends Step, Ctx extends StepContext = StepContext>(key: K, collection: (ctx: Readonly<Ctx>) => StepContext[], step: S): TypedStep<Ctx, Record<K, ExtractProvides<S>[]>>;
+
+/**
+ * Filter a collection from context using a predicate, concurrently.
+ *
+ * Extracts a collection from the pipeline context, evaluates the
+ * predicate for each item via `Promise.allSettled`, and collects
+ * items that pass into an array under the given key.
+ *
+ * Original order is preserved.
+ *
+ * The predicate can be sync or async. If any predicate throws, the
+ * entire step fails — no partial results are returned.
+ *
+ * There is no rollback (filtering is a pure operation with nothing
+ * to undo).
+ *
+ * @example
  * ```ts
- * createPipeline('placeOrder', { strict: true })
+ * const pipeline = pipeline({
+ *   name: 'notify',
+ *   steps: [
+ *     filter(
+ *       'eligible',
+ *       (ctx) => ctx.users,
+ *       (user) => user.optedIn,
+ *     ),
+ *     map('emails', (ctx) => ctx.eligible, sendEmail),
+ *   ],
+ * });
+ *
+ * // Async predicate
+ * filter('valid', (ctx) => ctx.orders, async (order) => {
+ *   const inventory = await checkInventory(order.sku);
+ *   return inventory.available >= order.quantity;
+ * });
  * ```
  *
- * **Schema + strict mode:**
+ * @param key - The output key under which filtered results are collected.
+ * @param collection - A selector that extracts the collection from context.
+ * @param predicate - A per-item predicate. Return `true` to keep, `false` to discard.
+ * @returns A frozen {@link TypedStep} that provides `{ [key]: Item[] }`.
+ */
+declare function filter<K extends string, Item, Ctx extends StepContext = StepContext>(key: K, collection: (ctx: Readonly<Ctx>) => Item[], predicate: (item: Item, ctx: Readonly<Ctx>) => boolean | Promise<boolean>): TypedStep<Ctx, Record<K, Item[]>>;
+
+/**
+ * Map each item in a collection to an array, then flatten one level.
+ *
+ * Extracts a collection from the pipeline context, runs the callback
+ * for each item via `Promise.allSettled`, and flattens the per-item
+ * arrays into a single array under the given key.
+ *
+ * The callback can be sync or async. If any callback throws, the
+ * entire step fails — no partial results are returned.
+ *
+ * There is no rollback (pure transformation with nothing to undo).
+ *
+ * @example
  * ```ts
- * createPipeline('placeOrder', z.object({ orderId: z.string() }), { strict: true })
+ * // Expand orders into line items
+ * const pipeline = pipeline({
+ *   name: 'process',
+ *   steps: [
+ *     flatMap(
+ *       'lineItems',
+ *       (ctx) => ctx.orders,
+ *       (order) => order.items,
+ *     ),
+ *   ],
+ * });
+ *
+ * // Async callback
+ * flatMap('emails', (ctx) => ctx.teams, async (team) => {
+ *   const members = await fetchMembers(team.id);
+ *   return members.map((m) => m.email);
+ * });
  * ```
  *
- * @typeParam Args - The pipeline's input type. Inferred from `argsSchema`
- *   if provided, otherwise specify via generic parameter.
- * @param name - Pipeline name, used in metadata and error messages.
- * @param schemaOrOptions - A schema for runtime args validation, or a
- *   {@link PipelineOptions} object.
- * @param options - When the second argument is a schema, pass options here.
- * @returns A frozen {@link PipelineBuilder} ready for `.step()`,
- *   `.use()`, and `.build()`.
- */
-type PipelineOptions = {
-    strict?: boolean;
-};
-declare function createPipeline<Args extends StepContext>(name: string): PipelineBuilder<Args, Args>;
-declare function createPipeline<Args extends StepContext>(name: string, argsSchema: ParserSchema<Args>): PipelineBuilder<Args, Args>;
-declare function createPipeline<Args extends StepContext>(name: string, options: PipelineOptions): PipelineBuilder<Args, Args>;
-declare function createPipeline<Args extends StepContext>(name: string, argsSchema: ParserSchema<Args>, options: PipelineOptions): PipelineBuilder<Args, Args>;
+ * @param key - The output key under which flattened results are collected.
+ * @param collection - A selector that extracts the collection from context.
+ * @param fn - A per-item callback that returns an array (or Promise of array).
+ * @returns A frozen {@link TypedStep} that provides `{ [key]: Item[] }`.
+ */
+declare function flatMap<K extends string, Item, Result, Ctx extends StepContext = StepContext>(key: K, collection: (ctx: Readonly<Ctx>) => Item[], fn: (item: Item, ctx: Readonly<Ctx>) => Result[] | Promise<Result[]>): TypedStep<Ctx, Record<K, Result[]>>;
 
-export { type ConditionalStep, type ExtractProvides, type ExtractRequires, type Pipeline, type PipelineBuilder, type PipelineConfig, type PipelineExecutionMeta, type PipelineFailure, type PipelineResult, type PipelineSuccess, type RetryPolicy, type RollbackFailure, type RollbackReport, RunsheetError, type RunsheetErrorCode, type Step, type StepConfig, type StepContext, type StepExecutor, type StepInfo, type StepMiddleware, type StepOutput, type TypedStep, buildPipeline, createPipeline, defineStep, parallel, when };
+export { type AggregateFailure, type AggregateMeta, type AggregateResult, type AggregateStep, type AggregateSuccess, ArgsValidationError, ChoiceNoMatchError, type ConditionalStep, type ExtractProvides, type ExtractRequires, type PipelineBuilder, type PipelineConfig, PredicateError, ProvidesValidationError, RequiresValidationError, RetryExhaustedError, type RetryPolicy, RollbackError, type RollbackFailure, type RollbackReport, RunsheetError, type RunsheetErrorCode, type Step, type StepConfig, type StepContext, type StepExecutor, type StepFailure, type StepInfo, type StepMeta, type StepMiddleware, type StepOutput, type StepResult, type StepSchema, type StepSuccess, StrictOverlapError, TimeoutError, type TypedStep, UnknownError, choice, defineStep, filter, flatMap, map, parallel, pipeline, when };