/**
 * The ordered Stage pipeline that assembles a boot context.
 *
 * Where a traditional program crams "read the flags, find the config, pick a
 * model, stand up the tools, wire the agent" into one sprawling `main()`, this
 * module factors that startup into a sequence of small, named {@link Stage}s.
 * Each stage is a pure-ish transformation `C → C` over an immutable context
 * value: it reads what earlier stages produced, computes one more piece, and
 * returns a *new* context carrying that addition. {@link runStages} threads an
 * initial context through the list, left to right, awaiting each.
 *
 * Two properties make this worth the indirection:
 *
 *   - **Immutability.** A stage never mutates the context it is handed; it
 *     returns a fresh object (conventionally `{ ...ctx, field }`). The reducer
 *     keeps only the latest value, so a stage that forgets to thread a field
 *     forward is a visible bug, not a silent shared-state mutation.
 *   - **Order is data.** The boot order lives in an array, not in the call
 *     structure of a function body. Inserting, reordering, or removing a step is
 *     an edit to a list — and each step carries a `name` for tracing and errors.
 *
 * The pipeline is generic over the context type `C`; the concrete
 * {@link import("./context").BootContext} and the concrete stage list live in
 * their own modules so this one stays a tiny, reusable reducer.
 */
/**
 * One ordered step of a boot pipeline.
 *
 * A stage is the unit of startup work: it takes the context produced by every
 * earlier stage and returns the context the next stage will see, having folded
 * in whatever it is responsible for. It may be synchronous or asynchronous; the
 * runner awaits either.
 *
 * @typeParam C the context type threaded through the pipeline.
 */
export interface Stage<C> {
    /** A short, stable label for this step — used in tracing and error context. */
    readonly name: string;
    /**
     * Fold this stage's contribution into the context.
     *
     * Implementations must treat `ctx` as immutable and return a *new* context
     * rather than mutating the argument. Returning the same reference (when a
     * stage is a genuine no-op) is permitted but discouraged for clarity.
     */
    apply(ctx: C): Promise<C> | C;
}
/**
 * Reduce an initial context through an ordered list of stages.
 *
 * Each stage receives the output of the previous one; the resolved value of the
 * final stage is the fully assembled context. Stages run strictly in order —
 * never concurrently — because a later stage routinely depends on an earlier
 * one's contribution (a model id needs the loaded settings; the agent factory
 * needs the assembled tools).
 *
 * The `initial` context is treated as immutable along with every intermediate:
 * the function holds a single `ctx` binding and reassigns it to each stage's
 * return value, so the caller's original object is never written to.
 *
 * @typeParam C the context type threaded through the pipeline.
 * @param initial the seed context the first stage receives.
 * @param stages the ordered steps to apply.
 * @returns the context produced by the last stage.
 */
export declare function runStages<C>(initial: C, stages: readonly Stage<C>[]): Promise<C>;
