runsheet 0.0.1

package/dist/index.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/index.ts","../src/define-step.ts","../src/errors.ts","../src/middleware.ts","../src/when.ts","../src/pipeline.ts","../src/builder.ts"],"sourcesContent":["export { defineStep } from './define-step.js';\nexport { RunsheetError } from './errors.js';\nexport type { RunsheetErrorCode } from './errors.js';\nexport { buildPipeline } from './pipeline.js';\nexport type { Pipeline, PipelineConfig } from './pipeline.js';\nexport { when } from './when.js';\nexport type { ConditionalStep } from './when.js';\nexport type { StepMiddleware, StepInfo, StepExecutor } from './middleware.js';\nexport { createPipeline } from './builder.js';\nexport type { PipelineBuilder } from './builder.js';\n\nexport type {\n  Step,\n  TypedStep,\n  StepConfig,\n  StepContext,\n  StepOutput,\n  PipelineResult,\n  PipelineSuccess,\n  PipelineFailure,\n  PipelineExecutionMeta,\n  RollbackReport,\n  RollbackFailure,\n} from './types.js';\n\n// Re-export Result types so consumers never need to import composable-functions\nexport type { Result, Success, Failure } from 'composable-functions';\n","import { composable } from 'composable-functions';\nimport type { StepConfig, StepContext, Step, TypedStep } from './types.js';\n\n/**\n * Define a pipeline step.\n *\n * Returns a frozen {@link TypedStep} with concrete types for `run`,\n * `rollback`, `requires`, and `provides`. The `run` function can be\n * sync or async — both are supported.\n *\n * **With schemas** (runtime validation + type inference):\n * ```ts\n * const charge = defineStep({\n *   name: 'charge',\n *   requires: z.object({ amount: z.number() }),\n *   provides: z.object({ chargeId: z.string() }),\n *   run: async (ctx) => ({ chargeId: 'ch_123' }),\n * });\n * ```\n *\n * **With generics only** (no runtime validation):\n * ```ts\n * const log = defineStep<{ order: Order }, { loggedAt: Date }>({\n *   name: 'log',\n *   run: async (ctx) => ({ loggedAt: new Date() }),\n * });\n * ```\n *\n * **Invariants:**\n * - The returned step object is always frozen (immutable).\n * - The `run` function is wrapped with `composable()` from\n *   composable-functions, which catches thrown errors and produces\n *   `Result` values. Step authors should throw to signal failure.\n * - This is the single type-erasure cast point in the library.\n *\n * @typeParam Requires - The context shape this step reads from.\n * @typeParam Provides - The output shape this step produces.\n * @param config - The step configuration. See {@link StepConfig}.\n * @returns A frozen {@link TypedStep} ready for use in pipelines.\n */\nexport function defineStep<Requires extends StepContext, Provides extends StepContext>(\n  config: StepConfig<Requires, Provides>,\n): TypedStep<Requires, Provides> {\n  const wrappedRun = composable(config.run);\n\n  // The cast below is the single point where typed step functions are erased\n  // to the runtime Step representation. This is safe because:\n  // 1. Schema validation at step boundaries (requires/provides) enforces\n  //    correct types at runtime before and after each step executes.\n  // 2. The pipeline accumulates context immutably, so the runtime object\n  //    structurally matches what the typed function expects.\n  // 3. The phantom brands on TypedStep preserve compile-time type tracking\n  //    through the builder API without affecting runtime behavior.\n  return Object.freeze({\n    name: config.name,\n    requires: config.requires ?? undefined,\n    provides: config.provides ?? undefined,\n    run: wrappedRun as unknown as Step['run'],\n    rollback: config.rollback\n      ? async (ctx: Readonly<StepContext>, output: Readonly<StepContext>) => {\n          await (config.rollback as NonNullable<typeof config.rollback>)(\n            ctx as Readonly<Requires>,\n            output as Readonly<Provides>,\n          );\n        }\n      : undefined,\n  }) as TypedStep<Requires, Provides>;\n}\n","/**\n * Error codes for errors produced by the runsheet library itself.\n *\n * Use these to distinguish library errors from application errors\n * in a pipeline's `errors` array:\n *\n * ```ts\n * if (!result.success) {\n *   for (const error of result.errors) {\n *     if (error instanceof RunsheetError) {\n *       console.log(error.code); // 'REQUIRES_VALIDATION', etc.\n *     }\n *   }\n * }\n * ```\n */\nexport type RunsheetErrorCode =\n  | 'REQUIRES_VALIDATION'\n  | 'PROVIDES_VALIDATION'\n  | 'ARGS_VALIDATION'\n  | 'PREDICATE';\n\n/**\n * Base error class for all errors produced by the runsheet library.\n *\n * Application errors (thrown by step `run` or `rollback` functions)\n * are never wrapped in `RunsheetError` — they pass through as-is.\n * If you see a `RunsheetError` in a result's `errors` array, the\n * library itself produced it.\n *\n * Use `instanceof RunsheetError` to distinguish library errors from\n * application errors, and the `code` property to identify the\n * specific failure.\n */\nexport class RunsheetError extends Error {\n  /** Discriminant code identifying the type of library error. */\n  readonly code: RunsheetErrorCode;\n\n  /**\n   * @param code - The error code.\n   * @param message - A human-readable description of the failure.\n   */\n  constructor(code: RunsheetErrorCode, message: string) {\n    super(message);\n    this.name = 'RunsheetError';\n    this.code = code;\n  }\n}\n","import type { Result } from 'composable-functions';\nimport type { Step, StepContext, StepOutput } from './types.js';\n\n/**\n * Metadata about the step being executed, passed to middleware.\n *\n * This is a read-only view of the step's public configuration.\n * Middleware can use it for logging, metrics, or conditional behavior.\n */\nexport type StepInfo = {\n  /** The step's name. */\n  readonly name: string;\n  /** The step's requires schema, or `undefined` if not provided. */\n  readonly requires: Step['requires'];\n  /** The step's provides schema, or `undefined` if not provided. */\n  readonly provides: Step['provides'];\n};\n\n/**\n * A function that executes a step (or the next middleware in the chain).\n *\n * Receives the frozen accumulated context and returns a `Result` — either\n * `{ success: true, data }` or `{ success: false, errors }`.\n */\nexport type StepExecutor = (ctx: Readonly<StepContext>) => Promise<Result<StepOutput>>;\n\n/**\n * Middleware that wraps the entire step lifecycle, including schema\n * validation.\n *\n * A middleware receives the step metadata and a `next` function, and\n * returns a new executor. Call `next(ctx)` to proceed to the next\n * middleware (or the actual step execution). You can:\n *\n * - **Observe**: read the context or result for logging/metrics.\n * - **Transform**: modify the result before returning it.\n * - **Short-circuit**: return a `Result` without calling `next`.\n *\n * If a middleware throws, the pipeline catches it and treats it as a\n * step failure (triggering rollback for previously completed steps).\n *\n * @example\n * ```ts\n * const timing: StepMiddleware = (step, next) => async (ctx) => {\n *   const start = performance.now();\n *   const result = await next(ctx);\n *   console.log(`${step.name}: ${performance.now() - start}ms`);\n *   return result;\n * };\n * ```\n *\n * @param step - Metadata about the step being wrapped.\n * @param next - The next executor in the chain. Call it to continue.\n * @returns A new executor that wraps `next`.\n */\nexport type StepMiddleware = (step: StepInfo, next: StepExecutor) => StepExecutor;\n\n/**\n * Compose an array of middlewares around a step executor.\n *\n * First middleware in the array is the outermost wrapper (executes\n * first on the way in, last on the way out).\n *\n * @param middlewares - Middleware functions, in declaration order.\n * @param step - Metadata about the step being wrapped.\n * @param executor - The base step executor to wrap.\n * @returns A composed executor with all middleware applied.\n */\nexport function applyMiddleware(\n  middlewares: readonly StepMiddleware[],\n  step: StepInfo,\n  executor: StepExecutor,\n): StepExecutor {\n  return middlewares.reduceRight<StepExecutor>((next, mw) => mw(step, next), executor);\n}\n","import type { Step, StepContext, TypedStep } from './types.js';\n\n/**\n * A step with a conditional predicate attached.\n *\n * The pipeline engine checks for the `predicate` property to decide\n * whether to execute or skip the step. Use the {@link when} function\n * to create conditional steps — don't construct this type directly.\n */\nexport type ConditionalStep = Step & {\n  /** Returns `true` to execute the step, `false` to skip it. */\n  readonly predicate: (ctx: Readonly<StepContext>) => boolean;\n};\n\n/**\n * Wrap a step with a guard predicate.\n *\n * The step only executes when the predicate returns `true`. When\n * skipped:\n * - No context snapshot is taken.\n * - No rollback entry is created.\n * - The step name is recorded in `result.meta.stepsSkipped`.\n *\n * If the predicate throws, the pipeline treats it as a step failure\n * and triggers rollback for any previously completed steps.\n *\n * @example\n * ```ts\n * const steps = [\n *   validateOrder,\n *   when((ctx) => ctx.order.amount > 100, notifyManager),\n *   sendConfirmation,\n * ];\n * ```\n *\n * @typeParam Requires - Inferred from the step's requires type.\n * @typeParam Provides - Inferred from the step's provides type.\n * @param predicate - Guard function. Receives the current accumulated\n *   context (frozen). Return `true` to execute, `false` to skip.\n * @param step - The step to conditionally execute.\n * @returns A frozen {@link TypedStep} with the predicate attached.\n */\nexport function when<Requires extends StepContext, Provides extends StepContext>(\n  predicate: (ctx: Readonly<Requires>) => boolean,\n  step: TypedStep<Requires, Provides>,\n): TypedStep<Requires, Provides> {\n  return Object.freeze({\n    ...step,\n    predicate: predicate as ConditionalStep['predicate'],\n  }) as TypedStep<Requires, Provides>;\n}\n\n/** Type guard for conditional steps. */\nexport function isConditionalStep(step: Step): step is ConditionalStep {\n  return 'predicate' in step && typeof (step as StepContext)['predicate'] === 'function';\n}\n","import type { ParserSchema, Result } from 'composable-functions';\nimport type {\n  ExtractProvides,\n  PipelineFailure,\n  PipelineResult,\n  PipelineSuccess,\n  RollbackFailure,\n  RollbackReport,\n  Step,\n  StepContext,\n  StepOutput,\n  UnionToIntersection,\n} from './types.js';\nimport type { StepMiddleware } from './middleware.js';\nimport type { RunsheetErrorCode } from './errors.js';\nimport { RunsheetError } from './errors.js';\nimport { applyMiddleware } from './middleware.js';\nimport { isConditionalStep } from './when.js';\n\n// ---------------------------------------------------------------------------\n// Pipeline configuration\n// ---------------------------------------------------------------------------\n\n/**\n * Internal configuration shape for the pipeline engine.\n *\n * Users typically don't construct this directly — use `buildPipeline()`\n * or `createPipeline()` instead.\n */\nexport type PipelineConfig = {\n  /** Pipeline name, used in execution metadata and error messages. */\n  readonly name: string;\n  /** Steps to execute in order. */\n  readonly steps: readonly Step[];\n  /** Optional middleware applied to every step. First in array = outermost. */\n  readonly middleware?: readonly StepMiddleware[];\n  /** Optional schema that validates the pipeline's input arguments. */\n  readonly argsSchema?: ParserSchema<StepContext>;\n};\n\n// ---------------------------------------------------------------------------\n// Pipeline\n// ---------------------------------------------------------------------------\n\n/**\n * A built pipeline, ready to execute.\n *\n * Call `run(args)` to execute the pipeline. The result is a\n * {@link PipelineResult} — either a success with the fully accumulated\n * context, or a failure with error details and a rollback report.\n *\n * Pipeline objects are frozen (immutable) and can be called repeatedly.\n *\n * @typeParam Args - The input type accepted by `run()`.\n * @typeParam Ctx - The accumulated output type on success.\n */\nexport type Pipeline<Args extends StepContext, Ctx> = {\n  /** The pipeline's name, as provided at build time. */\n  readonly name: string;\n  /**\n   * Execute the pipeline.\n   *\n   * @param args - The initial arguments. Merged into the context before\n   *   the first step runs. Validated against `argsSchema` if one was\n   *   provided.\n   * @returns A {@link PipelineResult} — discriminate on `success` to\n   *   access `data` (on success) or `errors`/`rollback` (on failure).\n   */\n  readonly run: (args: Args) => Promise<PipelineResult<Ctx>>;\n};\n\n// ---------------------------------------------------------------------------\n// Schema validation\n// ---------------------------------------------------------------------------\n\nfunction validateSchema<T>(\n  schema: ParserSchema<T> | undefined,\n  data: unknown,\n  label: string,\n  code: RunsheetErrorCode,\n): { success: true; data: T } | { success: false; errors: RunsheetError[] } {\n  if (!schema) return { success: true, data: data as T };\n\n  const parsed = schema.safeParse(data);\n  if (parsed.success) return { success: true, data: parsed.data };\n\n  const errors = parsed.error.issues.map(\n    (issue) => new RunsheetError(code, `${label}: ${issue.path.join('.')}: ${issue.message}`),\n  );\n  return { success: false, errors };\n}\n\n// ---------------------------------------------------------------------------\n// Rollback\n// ---------------------------------------------------------------------------\n\nasync function executeRollback(\n  executedSteps: readonly Step[],\n  snapshots: readonly StepContext[],\n  outputs: readonly StepOutput[],\n): Promise<RollbackReport> {\n  const completed: string[] = [];\n  const failed: RollbackFailure[] = [];\n\n  for (let i = executedSteps.length - 1; i >= 0; i--) {\n    const step = executedSteps[i];\n    if (!step.rollback) continue;\n\n    try {\n      await step.rollback(snapshots[i], outputs[i]);\n      completed.push(step.name);\n    } catch (err) {\n      failed.push({\n        step: step.name,\n        error: err instanceof Error ? err : new Error(String(err)),\n      });\n    }\n  }\n\n  return Object.freeze({ completed, failed });\n}\n\n// ---------------------------------------------------------------------------\n// Execution state — accumulated during pipeline run\n// ---------------------------------------------------------------------------\n\ntype ExecutionState = {\n  context: StepContext;\n  readonly snapshots: StepContext[];\n  readonly outputs: StepOutput[];\n  readonly executedSteps: Step[];\n  readonly stepsExecuted: string[];\n  readonly stepsSkipped: string[];\n};\n\nfunction createExecutionState(args: StepContext): ExecutionState {\n  return {\n    context: Object.freeze({ ...args }),\n    snapshots: [],\n    outputs: [],\n    executedSteps: [],\n    stepsExecuted: [],\n    stepsSkipped: [],\n  };\n}\n\n// ---------------------------------------------------------------------------\n// Result constructors\n// ---------------------------------------------------------------------------\n\nfunction pipelineFailure(\n  pipelineName: string,\n  args: StepContext,\n  state: ExecutionState,\n  failedStep: string,\n  errors: Error[],\n  rollback: RollbackReport,\n): PipelineFailure {\n  return Object.freeze({\n    success: false as const,\n    errors,\n    meta: Object.freeze({\n      pipeline: pipelineName,\n      args,\n      stepsExecuted: state.stepsExecuted,\n      stepsSkipped: state.stepsSkipped,\n    }),\n    failedStep,\n    rollback,\n  });\n}\n\nfunction pipelineSuccess(\n  pipelineName: string,\n  args: StepContext,\n  state: ExecutionState,\n): PipelineSuccess<StepContext> {\n  return Object.freeze({\n    success: true as const,\n    data: state.context,\n    errors: [] as [],\n    meta: Object.freeze({\n      pipeline: pipelineName,\n      args,\n      stepsExecuted: state.stepsExecuted,\n      stepsSkipped: state.stepsSkipped,\n    }),\n  });\n}\n\n// ---------------------------------------------------------------------------\n// Step executor — the full lifecycle (validate requires → run → validate provides)\n// ---------------------------------------------------------------------------\n\nfunction createStepExecutor(\n  step: Step,\n): (ctx: Readonly<StepContext>) => Promise<Result<StepOutput>> {\n  return async (ctx) => {\n    // Validate requires\n    const requiresCheck = validateSchema(\n      step.requires,\n      ctx,\n      `${step.name} requires`,\n      'REQUIRES_VALIDATION',\n    );\n    if (!requiresCheck.success) {\n      return { success: false as const, errors: requiresCheck.errors };\n    }\n\n    // Execute step run\n    const result = await step.run(ctx);\n    if (!result.success) return result;\n\n    // Validate provides\n    const providesCheck = validateSchema(\n      step.provides,\n      result.data,\n      `${step.name} provides`,\n      'PROVIDES_VALIDATION',\n    );\n    if (!providesCheck.success) {\n      return { success: false as const, errors: providesCheck.errors };\n    }\n\n    return {\n      success: true as const,\n      data: providesCheck.data as StepOutput,\n      errors: [] as [],\n    };\n  };\n}\n\n// ---------------------------------------------------------------------------\n// Pipeline execution\n// ---------------------------------------------------------------------------\n\nasync function executePipeline(\n  config: PipelineConfig,\n  args: StepContext,\n): Promise<PipelineResult<StepContext>> {\n  // Validate pipeline args if schema provided\n  if (config.argsSchema) {\n    const argsCheck = validateSchema(\n      config.argsSchema,\n      args,\n      `${config.name} args`,\n      'ARGS_VALIDATION',\n    );\n    if (!argsCheck.success) {\n      const state = createExecutionState(args);\n      return pipelineFailure(\n        config.name,\n        args,\n        state,\n        config.name,\n        argsCheck.errors,\n        Object.freeze({ completed: [], failed: [] }),\n      );\n    }\n  }\n\n  const state = createExecutionState(args);\n  const middlewares = config.middleware ?? [];\n\n  for (const step of config.steps) {\n    // Evaluate conditional predicate\n    try {\n      if (isConditionalStep(step) && !step.predicate(state.context)) {\n        state.stepsSkipped.push(step.name);\n        continue;\n      }\n    } catch (err) {\n      const message = err instanceof Error ? err.message : String(err);\n      const error = new RunsheetError('PREDICATE', `${step.name} predicate: ${message}`);\n      if (err instanceof Error) error.cause = err;\n      const rollback = await executeRollback(state.executedSteps, state.snapshots, state.outputs);\n      return pipelineFailure(config.name, args, state, step.name, [error], rollback);\n    }\n\n    // Snapshot pre-step context\n    state.snapshots.push(state.context);\n\n    // Build executor with middleware wrapping the full lifecycle\n    const baseExecutor = createStepExecutor(step);\n    const executor = applyMiddleware(\n      middlewares,\n      { name: step.name, requires: step.requires, provides: step.provides },\n      baseExecutor,\n    );\n\n    // Execute (try/catch handles middleware throws outside the Result boundary)\n    let result: Result<StepOutput>;\n    try {\n      result = await executor(state.context);\n    } catch (err) {\n      const error = err instanceof Error ? err : new Error(String(err));\n      state.snapshots.pop();\n      const rollback = await executeRollback(state.executedSteps, state.snapshots, state.outputs);\n      return pipelineFailure(config.name, args, state, step.name, [error], rollback);\n    }\n\n    if (!result.success) {\n      // Remove the snapshot we just pushed — the step didn't complete\n      state.snapshots.pop();\n      const rollback = await executeRollback(state.executedSteps, state.snapshots, state.outputs);\n      return pipelineFailure(config.name, args, state, step.name, result.errors, rollback);\n    }\n\n    // Track step output and accumulate context\n    const output = result.data;\n    state.outputs.push(output);\n    state.executedSteps.push(step);\n    state.stepsExecuted.push(step.name);\n    state.context = Object.freeze({ ...state.context, ...output });\n  }\n\n  return pipelineSuccess(config.name, args, state);\n}\n\n// ---------------------------------------------------------------------------\n// Public API\n// ---------------------------------------------------------------------------\n\n/**\n * Build a pipeline from an array of steps.\n *\n * The result type is inferred from the steps — `pipeline.run()` returns\n * a {@link PipelineResult} whose `data` is the intersection of the\n * initial `Args` and all step output types.\n *\n * @example\n * ```ts\n * const pipeline = buildPipeline({\n *   name: 'placeOrder',\n *   steps: [validateOrder, chargePayment, sendConfirmation],\n *   middleware: [logging, timing],\n *   argsSchema: z.object({ orderId: z.string() }),\n * });\n *\n * const result = await pipeline.run({ orderId: '123' });\n * if (result.success) {\n *   result.data.chargeId; // string — fully typed\n * }\n * ```\n *\n * **Execution semantics:**\n * - Steps execute sequentially in array order.\n * - Context is frozen (`Object.freeze`) at every step boundary.\n * - Conditional steps (wrapped with `when()`) are skipped when their\n *   predicate returns false — no snapshot, no rollback entry.\n * - On step failure, rollback handlers for all previously completed\n *   steps execute in reverse order (best-effort).\n * - Middleware wraps the full step lifecycle including schema validation.\n *\n * **Invariants:**\n * - The returned pipeline object is frozen (immutable).\n * - Errors thrown by steps, predicates, or middleware are caught and\n *   returned as `PipelineFailure` — `run()` never throws.\n *\n * @typeParam Args - The pipeline's input type. Inferred from `argsSchema`\n *   if provided, otherwise defaults to `StepContext`.\n * @typeParam S - The step types in the array. Inferred automatically —\n *   do not specify manually.\n * @param config - Pipeline configuration.\n * @param config.name - Pipeline name, used in metadata and error messages.\n * @param config.steps - Steps to execute in order.\n * @param config.middleware - Optional middleware applied to every step.\n *   First in array = outermost wrapper.\n * @param config.argsSchema - Optional schema that validates `args` before\n *   any steps run. Validation failure produces a `PipelineFailure` with\n *   `failedStep` set to the pipeline name.\n * @returns A frozen {@link Pipeline} whose `run()` method executes the\n *   steps and returns a {@link PipelineResult}.\n */\nexport function buildPipeline<\n  Args extends StepContext = StepContext,\n  S extends Step = Step,\n>(config: {\n  readonly name: string;\n  readonly steps: readonly S[];\n  readonly middleware?: readonly StepMiddleware[];\n  readonly argsSchema?: ParserSchema<Args>;\n}): Pipeline<Args, Args & UnionToIntersection<ExtractProvides<S>>> {\n  return Object.freeze({\n    name: config.name,\n    run: (args: Args) => executePipeline(config as PipelineConfig, args),\n  }) as Pipeline<Args, Args & UnionToIntersection<ExtractProvides<S>>>;\n}\n","import type { ParserSchema } from 'composable-functions';\nimport type { Step, StepContext, TypedStep } from './types.js';\nimport type { StepMiddleware } from './middleware.js';\nimport { buildPipeline } from './pipeline.js';\nimport type { Pipeline } from './pipeline.js';\n\n// ---------------------------------------------------------------------------\n// Builder types\n// ---------------------------------------------------------------------------\n\n/**\n * A fluent pipeline builder that progressively narrows the accumulated\n * context type as steps are added.\n *\n * Each method returns a new, frozen builder — builders are immutable.\n * This means you can safely fork a builder to create variants:\n *\n * ```ts\n * const base = createPipeline('order').step(validate);\n * const withCharge = base.step(charge).build();\n * const withoutCharge = base.build(); // unaffected by the fork\n * ```\n *\n * @typeParam Args - The pipeline's initial input type.\n * @typeParam Ctx - The accumulated context type so far (grows with each `.step()`).\n */\nexport type PipelineBuilder<Args extends StepContext, Ctx extends StepContext> = {\n  /**\n   * Add a step to the pipeline.\n   *\n   * The step's `Requires` type must be satisfied by the current `Ctx`.\n   * The returned builder's `Ctx` expands to include the step's `Provides`.\n   *\n   * @typeParam Provides - The output type of the step being added.\n   * @param step - A {@link TypedStep} (from `defineStep` or `when`).\n   * @returns A new builder with the expanded context type.\n   */\n  readonly step: <Provides extends StepContext>(\n    step: TypedStep<Ctx, Provides>,\n  ) => PipelineBuilder<Args, Ctx & Provides>;\n\n  /**\n   * Add middleware to the pipeline.\n   *\n   * Middleware is applied to every step. Multiple `.use()` calls\n   * accumulate — earlier middleware is outermost (executes first).\n   *\n   * @param middleware - One or more {@link StepMiddleware} functions.\n   * @returns A new builder with the middleware added.\n   */\n  readonly use: (...middleware: StepMiddleware[]) => PipelineBuilder<Args, Ctx>;\n\n  /**\n   * Build the pipeline.\n   *\n   * @returns A frozen {@link Pipeline} ready to execute with `run()`.\n   */\n  readonly build: () => Pipeline<Args, Ctx>;\n};\n\n// ---------------------------------------------------------------------------\n// Internal builder state (immutable — each method returns a new builder)\n// ---------------------------------------------------------------------------\n\ntype BuilderState = {\n  readonly name: string;\n  readonly steps: readonly Step[];\n  readonly middleware: readonly StepMiddleware[];\n  readonly argsSchema: ParserSchema<StepContext> | undefined;\n};\n\nfunction makeBuilder<Args extends StepContext, Ctx extends StepContext>(\n  state: BuilderState,\n): PipelineBuilder<Args, Ctx> {\n  return Object.freeze({\n    step: <Provides extends StepContext>(step: TypedStep<Ctx, Provides>) =>\n      makeBuilder<Args, Ctx & Provides>({\n        ...state,\n        steps: [...state.steps, step],\n      }),\n\n    use: (...middleware: StepMiddleware[]) =>\n      makeBuilder<Args, Ctx>({\n        ...state,\n        middleware: [...state.middleware, ...middleware],\n      }),\n\n    build: () =>\n      buildPipeline({\n        name: state.name,\n        steps: state.steps,\n        middleware: state.middleware.length > 0 ? state.middleware : undefined,\n        argsSchema: state.argsSchema as ParserSchema<Args> | undefined,\n      }) as Pipeline<Args, Ctx>,\n  });\n}\n\n// ---------------------------------------------------------------------------\n// Public API\n// ---------------------------------------------------------------------------\n\n/**\n * Start building a pipeline with the fluent builder API.\n *\n * The builder gives progressive type narrowing — each `.step()` call\n * extends the known context type, so TypeScript catches mismatches\n * at compile time.\n *\n * **Type-only args** (no runtime validation):\n * ```ts\n * createPipeline<{ orderId: string }>('placeOrder')\n *   .step(validateOrder)\n *   .step(chargePayment)\n *   .build();\n * ```\n *\n * **Schema args** (runtime validation + type inference):\n * ```ts\n * createPipeline('placeOrder', z.object({ orderId: z.string() }))\n *   .step(validateOrder)\n *   .step(chargePayment)\n *   .build();\n * ```\n *\n * @typeParam Args - The pipeline's input type. Inferred from `argsSchema`\n *   if provided, otherwise specify via generic parameter.\n * @param name - Pipeline name, used in metadata and error messages.\n * @param argsSchema - Optional schema that validates pipeline input\n *   at runtime. When provided, `Args` is inferred from the schema.\n * @returns A frozen {@link PipelineBuilder} ready for `.step()`,\n *   `.use()`, and `.build()`.\n */\nexport function createPipeline<Args extends StepContext>(\n  name: string,\n  argsSchema?: ParserSchema<Args>,\n): PipelineBuilder<Args, Args> {\n  return makeBuilder<Args, Args>({\n    name,\n    steps: [],\n    middleware: [],\n    argsSchema,\n  });\n}\n"],"mappings":"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","names":["state"]}

package/dist/index.d.cts

@@ -0,0 +1,600 @@
+import { ParserSchema, Result, Success, Failure } from 'composable-functions';
+export { Failure, Result, Success } from 'composable-functions';
+
+/**
+ * The type-erased context shape used at runtime by the pipeline engine.
+ *
+ * This is the base type for all step inputs. Concrete step types narrow
+ * this via their `Requires`/`Provides` type parameters, but the pipeline
+ * engine operates on `StepContext` internally since it handles
+ * heterogeneous step arrays.
+ */
+type StepContext = Record<string, unknown>;
+/**
+ * The type-erased output shape produced by a step at runtime.
+ *
+ * Structurally identical to {@link StepContext}, but semantically distinct:
+ * context is what flows *in*, output is what a step *produces*. This
+ * separation makes the pipeline code easier to follow.
+ */
+type StepOutput = Record<string, unknown>;
+/**
+ * Runtime step representation used by the pipeline engine.
+ *
+ * This type is non-generic — the pipeline engine operates on these without
+ * needing to know individual step type parameters. Schema validation at
+ * step boundaries ensures type correctness at runtime.
+ *
+ * All step objects are frozen (immutable). Use {@link TypedStep} when you
+ * need compile-time type information for a specific step.
+ *
+ * @see {@link TypedStep} for the compile-time typed variant
+ */
+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;
+    /** Optional schema that validates the step's output after `run`. */
+    readonly provides: ParserSchema<StepOutput> | undefined;
+    /**
+     * Execute the step. Receives the accumulated context and returns a
+     * `Result` — either `{ success: true, data }` or
+     * `{ success: false, errors }`.
+     *
+     * Step authors never call this directly; the pipeline engine calls it
+     * after validating `requires` and wrapping with middleware.
+     */
+    readonly run: (ctx: Readonly<StepContext>) => Promise<Result<StepOutput>>;
+    /**
+     * Optional rollback handler, called when a later step fails.
+     *
+     * @param ctx - The frozen context snapshot from *before* this step ran.
+     * @param output - The frozen output this step produced.
+     */
+    readonly rollback: ((ctx: Readonly<StepContext>, output: Readonly<StepOutput>) => Promise<void>) | undefined;
+};
+/**
+ * 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.
+ */
+declare const RequiresBrand: unique symbol;
+declare const ProvidesBrand: unique symbol;
+/**
+ * A step with compile-time type information.
+ *
+ * Extends the runtime {@link Step} with phantom brands and concrete typed
+ * signatures. This is the type returned by `defineStep()`.
+ *
+ * When held as a `TypedStep<R, P>`, the `run`, `rollback`, `requires`,
+ * and `provides` properties all carry concrete types matching the step's
+ * schemas or generics. When assigned to `Step` (e.g., in a pipeline's
+ * step array), the intersection collapses to the erased signatures.
+ *
+ * @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 }>>
+ * const step = defineStep({
+ *   name: 'charge',
+ *   requires: z.object({ amount: z.number() }),
+ *   provides: z.object({ chargeId: z.string() }),
+ *   run: async (ctx) => ({ chargeId: `ch_${ctx.amount}` }),
+ * });
+ * ```
+ */
+type TypedStep<Requires extends StepContext = StepContext, Provides extends StepContext = StepContext> = Step & {
+    readonly [RequiresBrand]: Requires;
+    readonly [ProvidesBrand]: Provides;
+    /** Optional schema that validates the accumulated context before `run`. */
+    readonly requires: ParserSchema<Requires> | undefined;
+    /** Optional schema that validates the step's output after `run`. */
+    readonly provides: ParserSchema<Provides> | undefined;
+    /** Execute the step with concrete input/output types. */
+    readonly run: (ctx: Readonly<Requires>) => Promise<Result<Provides>>;
+    /**
+     * Optional rollback handler, called when a later step fails.
+     *
+     * @param ctx - The frozen context snapshot from *before* this step ran.
+     * @param output - The frozen output this step produced.
+     */
+    readonly rollback: ((ctx: Readonly<Requires>, output: Readonly<Provides>) => Promise<void>) | undefined;
+};
+/** 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 Provides type from a step. Returns `object` for untyped (erased) steps. */
+type ExtractProvides<T extends Step> = T extends TypedStep<StepContext, infer P> ? P : object;
+/**
+ * Configuration object passed to `defineStep()`.
+ *
+ * Schemas are optional — omit them for generics-only steps that rely on
+ * compile-time type safety without runtime validation.
+ *
+ * @typeParam Requires - The context shape this step reads from.
+ * @typeParam Provides - The output shape this step produces.
+ */
+type StepConfig<Requires extends StepContext, Provides extends StepContext> = {
+    /** Unique name identifying this step in metadata and rollback reports. */
+    name: string;
+    /**
+     * 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
+     * `run` function is never invoked.
+     */
+    requires?: ParserSchema<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`
+     * succeeded.
+     */
+    provides?: ParserSchema<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.
+     *
+     * @param ctx - The frozen accumulated context up to this point.
+     * @returns The step's output, which is merged into the accumulated context.
+     */
+    run: (ctx: Readonly<Requires>) => Provides | Promise<Provides>;
+    /**
+     * Optional rollback handler, called when a *later* step fails.
+     * Receives the pre-step context snapshot and this step's output.
+     * Can be sync or async.
+     *
+     * Rollback is best-effort: if this handler throws, remaining
+     * rollbacks still execute. The error is captured in the
+     * {@link RollbackReport}.
+     *
+     * @param ctx - The frozen context snapshot from *before* this step ran.
+     * @param output - The frozen output this step produced.
+     */
+    rollback?: (ctx: Readonly<Requires>, output: Readonly<Provides>) => void | Promise<void>;
+};
+/**
+ * Record of a single rollback handler that threw during rollback execution.
+ *
+ * Non-Error exceptions (e.g., thrown strings) are wrapped in an `Error`.
+ */
+type RollbackFailure = {
+    /** Name of the step whose rollback handler failed. */
+    readonly step: string;
+    /** The error thrown by the rollback handler. */
+    readonly error: Error;
+};
+/**
+ * Summary of rollback execution after a pipeline failure.
+ *
+ * Rollback is best-effort: every completed step's rollback handler is
+ * attempted in reverse order, regardless of whether earlier handlers
+ * threw. This report tells you exactly what succeeded and what didn't.
+ */
+type RollbackReport = {
+    /** Step names whose rollback handlers completed successfully, in execution order. */
+    readonly completed: readonly string[];
+    /** Steps whose rollback handlers threw, with the captured errors. */
+    readonly failed: readonly RollbackFailure[];
+};
+/**
+ * Metadata about a pipeline 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()`. */
+    readonly args: Readonly<StepContext>;
+    /** 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.
+ *
+ * Extends composable-functions' `Success<T>` with pipeline execution
+ * metadata. The `data` property contains the fully accumulated context
+ * (initial args merged with all step outputs).
+ *
+ * @typeParam T - The accumulated context type.
+ */
+type PipelineSuccess<T> = Success<T> & {
+    /** Pipeline execution metadata. */
+    readonly meta: PipelineExecutionMeta;
+};
+/**
+ * A failed pipeline result.
+ *
+ * Extends composable-functions' `Failure` with the name of the step that
+ * failed, a rollback report, and pipeline execution metadata.
+ *
+ * On failure, rollback handlers for all previously completed steps are
+ * executed in reverse order before this result is returned.
+ */
+type PipelineFailure = Failure & {
+    /** Pipeline execution metadata. */
+    readonly meta: PipelineExecutionMeta;
+    /** 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.
+ *
+ * Use the `success` discriminant to narrow:
+ *
+ * ```ts
+ * const result = await pipeline.run(args);
+ * if (result.success) {
+ *   result.data;       // fully typed accumulated context
+ *   result.meta;       // execution metadata
+ * } else {
+ *   result.errors;     // what went wrong
+ *   result.failedStep; // which step failed
+ *   result.rollback;   // { completed: [...], failed: [...] }
+ * }
+ * ```
+ *
+ * @typeParam T - The accumulated context type on success.
+ */
+type PipelineResult<T> = PipelineSuccess<T> | PipelineFailure;
+
+/**
+ * Define a pipeline step.
+ *
+ * Returns a frozen {@link TypedStep} with concrete types for `run`,
+ * `rollback`, `requires`, and `provides`. The `run` function can be
+ * sync or async — both are supported.
+ *
+ * **With schemas** (runtime validation + type inference):
+ * ```ts
+ * const charge = defineStep({
+ *   name: 'charge',
+ *   requires: z.object({ amount: z.number() }),
+ *   provides: z.object({ chargeId: z.string() }),
+ *   run: async (ctx) => ({ chargeId: 'ch_123' }),
+ * });
+ * ```
+ *
+ * **With generics only** (no runtime validation):
+ * ```ts
+ * const log = defineStep<{ order: Order }, { loggedAt: Date }>({
+ *   name: 'log',
+ *   run: async (ctx) => ({ loggedAt: new Date() }),
+ * });
+ * ```
+ *
+ * **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.
+ * - This is the single type-erasure cast point in the library.
+ *
+ * @typeParam Requires - The context shape this step reads from.
+ * @typeParam Provides - The output shape this step produces.
+ * @param config - The step configuration. See {@link StepConfig}.
+ * @returns A frozen {@link TypedStep} ready for use in pipelines.
+ */
+declare function defineStep<Requires extends StepContext, Provides extends StepContext>(config: StepConfig<Requires, Provides>): TypedStep<Requires, Provides>;
+
+/**
+ * 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:
+ *
+ * ```ts
+ * if (!result.success) {
+ *   for (const error of result.errors) {
+ *     if (error instanceof RunsheetError) {
+ *       console.log(error.code); // 'REQUIRES_VALIDATION', etc.
+ *     }
+ *   }
+ * }
+ * ```
+ */
+type RunsheetErrorCode = 'REQUIRES_VALIDATION' | 'PROVIDES_VALIDATION' | 'ARGS_VALIDATION' | 'PREDICATE';
+/**
+ * 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.
+ *
+ * Use `instanceof RunsheetError` to distinguish library errors from
+ * application errors, and the `code` property to identify the
+ * specific failure.
+ */
+declare class RunsheetError extends Error {
+    /** Discriminant code identifying the type of library error. */
+    readonly code: RunsheetErrorCode;
+    /**
+     * @param code - The error code.
+     * @param message - A human-readable description of the failure.
+     */
+    constructor(code: RunsheetErrorCode, message: string);
+}
+
+/**
+ * Metadata about the step being executed, passed to middleware.
+ *
+ * This is a read-only view of the step's public configuration.
+ * Middleware can use it for logging, metrics, or conditional behavior.
+ */
+type StepInfo = {
+    /** The step's name. */
+    readonly name: string;
+    /** The step's requires schema, or `undefined` if not provided. */
+    readonly requires: Step['requires'];
+    /** The step's provides schema, or `undefined` if not provided. */
+    readonly provides: Step['provides'];
+};
+/**
+ * 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 }`.
+ */
+type StepExecutor = (ctx: Readonly<StepContext>) => Promise<Result<StepOutput>>;
+/**
+ * Middleware that wraps the entire step lifecycle, including schema
+ * validation.
+ *
+ * A middleware receives the step metadata and a `next` function, and
+ * returns a new executor. Call `next(ctx)` to proceed to the next
+ * middleware (or the actual step execution). You can:
+ *
+ * - **Observe**: read the context or result for logging/metrics.
+ * - **Transform**: modify the result before returning it.
+ * - **Short-circuit**: return a `Result` without calling `next`.
+ *
+ * If a middleware throws, the pipeline catches it and treats it as a
+ * step failure (triggering rollback for previously completed steps).
+ *
+ * @example
+ * ```ts
+ * const timing: StepMiddleware = (step, next) => async (ctx) => {
+ *   const start = performance.now();
+ *   const result = await next(ctx);
+ *   console.log(`${step.name}: ${performance.now() - start}ms`);
+ *   return result;
+ * };
+ * ```
+ *
+ * @param step - Metadata about the step being wrapped.
+ * @param next - The next executor in the chain. Call it to continue.
+ * @returns A new executor that wraps `next`.
+ */
+type StepMiddleware = (step: StepInfo, next: StepExecutor) => StepExecutor;
+
+/**
+ * Internal configuration shape for the pipeline engine.
+ *
+ * Users typically don't construct this directly — use `buildPipeline()`
+ * or `createPipeline()` instead.
+ */
+type PipelineConfig = {
+    /** Pipeline name, used in execution metadata and error messages. */
+    readonly name: string;
+    /** Steps to execute in order. */
+    readonly steps: readonly Step[];
+    /** 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>;
+};
+/**
+ * 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.
+ *
+ * Pipeline objects are frozen (immutable) and can be called repeatedly.
+ *
+ * @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',
+ *   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.
+ *
+ * **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: {
+    readonly name: string;
+    readonly steps: readonly S[];
+    readonly middleware?: readonly StepMiddleware[];
+    readonly argsSchema?: ParserSchema<Args>;
+}): Pipeline<Args, Args & UnionToIntersection<ExtractProvides<S>>>;
+
+/**
+ * A step with a conditional predicate attached.
+ *
+ * The pipeline engine checks for the `predicate` property to decide
+ * whether to execute or skip the step. Use the {@link when} function
+ * to create conditional steps — don't construct this type directly.
+ */
+type ConditionalStep = Step & {
+    /** Returns `true` to execute the step, `false` to skip it. */
+    readonly predicate: (ctx: Readonly<StepContext>) => boolean;
+};
+/**
+ * Wrap a step with a guard predicate.
+ *
+ * The step only executes when the predicate returns `true`. When
+ * 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.
+ *
+ * @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 step - The step to conditionally execute.
+ * @returns A frozen {@link TypedStep} with the predicate attached.
+ */
+declare function when<Requires extends StepContext, Provides extends StepContext>(predicate: (ctx: Readonly<Requires>) => boolean, step: TypedStep<Requires, Provides>): TypedStep<Requires, Provides>;
+
+/**
+ * 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 = createPipeline('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`.
+     * 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>;
+};
+/**
+ * Start building a pipeline with the fluent builder API.
+ *
+ * The builder gives progressive type narrowing — each `.step()` call
+ * extends the known context type, so TypeScript catches mismatches
+ * at compile time.
+ *
+ * **Type-only args** (no runtime validation):
+ * ```ts
+ * createPipeline<{ orderId: string }>('placeOrder')
+ *   .step(validateOrder)
+ *   .step(chargePayment)
+ *   .build();
+ * ```
+ *
+ * **Schema args** (runtime validation + type inference):
+ * ```ts
+ * createPipeline('placeOrder', z.object({ orderId: z.string() }))
+ *   .step(validateOrder)
+ *   .step(chargePayment)
+ *   .build();
+ * ```
+ *
+ * @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 argsSchema - Optional schema that validates pipeline input
+ *   at runtime. When provided, `Args` is inferred from the schema.
+ * @returns A frozen {@link PipelineBuilder} ready for `.step()`,
+ *   `.use()`, and `.build()`.
+ */
+declare function createPipeline<Args extends StepContext>(name: string, argsSchema?: ParserSchema<Args>): PipelineBuilder<Args, Args>;
+
+export { type ConditionalStep, type Pipeline, type PipelineBuilder, type PipelineConfig, type PipelineExecutionMeta, type PipelineFailure, type PipelineResult, type PipelineSuccess, 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, when };