@asaidimu/utils-pipeline 1.0.0 → 1.0.1

package/index.d.mts

@@ -282,94 +282,6 @@ type PipelineStepDefinition = Omit<PipelineStep, "order">;
  * Outer array index → stage `order`. Inner arrays → parallel slots within a stage.
  */
 type PipelineDefinition = Array<PipelineStepDefinition | PipelineStepDefinition[]>;
-/**
- * Returned by a routing step action to redirect execution to another step.
- * Use the `routeTo()` helper to construct this.
- */
-interface RoutingInstruction {
-    /** Key of the step to jump to. May refer to any registered step, including earlier ones. */
-    next: string;
-    /** Value to place in the carry under the target step's key before jumping. */
-    value: any;
-    /** Maximum number of times this loop point may be visited before the engine hard-fails. */
-    maxIterations?: number;
-    /**
-     * Optional guard evaluated after each iteration increment.
-     * Return false to terminate the loop cleanly (emits `loop:terminated` with reason
-     * `"condition_failed"` and exits with the last successful carry).
-     */
-    condition?: (carry: StageCarry, iteration: number) => boolean | Promise<boolean>;
-}
-/**
- * Context injected into every routing step action.
- * Analogous to `ArtifactFactoryContext` — the step interacts with the engine through this.
- */
-interface PipelineStepContext {
-    /**
-     * Abort signal scoped to this execution run.
-     * Check this inside long-running actions to respect cancellation.
-     */
-    signal: AbortSignal;
-    /**
-     * Reads a value from the current carry AND registers a dependency edge in the
-     * execution graph so the engine knows which carry keys this step depends on.
-     *
-     * Steps with no `use()` calls have no declared dependencies and will always
-     * re-execute when their stage is revisited — the safe conservative fallback.
-     *
-     * @param key The carry key to read (always the key of a previous step).
-     * @returns The value stored under that key in the current carry.
-     */
-    use<K extends string>(key: K): StageCarry[K];
-    /**
-     * The number of times this specific step has been executed in the current
-     * routing chain. Zero on first execution, increments on each re-visit.
-     * Useful for backoff logic or conditional behaviour without external state.
-     */
-    iteration: number;
-}
-/**
- * A single executable step in a routing pipeline.
- * May return a plain result OR a `RoutingInstruction` to redirect execution.
- *
- * @template TIn  Shape of the incoming StageCarry this step expects to read.
- * @template TOut Value type this step produces on a non-routing success.
- */
-interface RoutingPipelineStep<TIn extends StageCarry = StageCarry, TOut = any> {
-    /** Unique identifier. Used as the carry key for this step's output. */
-    key: string;
-    /** Execution order. Steps sharing the same order run concurrently. */
-    order: number;
-    /**
-     * Business logic for this step.
-     * @param input Accumulated carry from all previous stages.
-     * @param ctx   Engine-provided context: signal, use(), iteration.
-     * @returns A Result wrapping either a plain output value or a RoutingInstruction.
-     */
-    action: (input: TIn, ctx: PipelineStepContext) => Promise<Result<TOut | RoutingInstruction>>;
-}
-/** Step definition without an explicit `order` — derived from array position. */
-type RoutingPipelineStepDefinition = Omit<RoutingPipelineStep, "order">;
-/**
- * Declarative routing pipeline shape passed to the constructor.
- * Outer array index → stage `order`. Inner arrays → parallel slots within a stage.
- */
-type RoutingPipelineDefinition = Array<RoutingPipelineStepDefinition | RoutingPipelineStepDefinition[]>;
-/** Per-step loop tracking state, maintained inside a RoutingExecutionContext. */
-interface LoopContext {
-    /** Number of times this step has been visited in the current routing chain. */
-    iteration: number;
-    /** Hard ceiling on iterations for this step (if specified via routeTo options). */
-    maxIterations?: number;
-    /** Timestamp of the first visit — useful for timeout / telemetry. */
-    startTime: number;
-    /** History of values and source steps passed through this loop point. */
-    history: Array<{
-        value: any;
-        fromStep: string | undefined;
-        timestamp: number;
-    }>;
-}
 
 /**
  * Isolated runtime for one sequential pipeline run.
@@ -499,4 +411,1197 @@ declare class Pipeline {
     private sortObjectKeys;
 }
 
-export { type LoopContext, Pipeline, type PipelineDefinition, type PipelineEventMap, type PipelineStep, type PipelineStepContext, type PipelineStepDefinition, Result, type RoutingInstruction, type RoutingPipelineDefinition, type RoutingPipelineStep, type RoutingPipelineStepDefinition, SequentialExecutionContext, type StageCarry, SystemError };
+/**
+ * Utility type for representing partial updates to the state, allowing deep nesting.
+ * It makes all properties optional and applies the same transformation recursively
+ * to nested objects and array elements, allowing for selective updates while
+ * preserving the original structure. It also includes the original type T and
+ * undefined as possibilities for the top level and nested values.
+ */
+type DeepPartial<T> = T extends object ? T extends readonly (infer U)[] ? readonly (DeepPartial<U> | undefined)[] | undefined | T : T extends (infer U)[] ? (DeepPartial<U> | undefined)[] | undefined | T : {
+    [K in keyof T]?: T[K] extends object ? DeepPartial<T[K]> | undefined : T[K] | undefined;
+} | undefined | T : T | undefined | symbol;
+/**
+ * Extended store state for monitoring the current execution status (e.g., if an update is in progress).
+ */
+interface StoreExecutionState<T> {
+    /** Indicates if a state update process is currently executing. */
+    executing: boolean;
+    /** The changes (DeepPartial) currently being processed in the execution cycle. Null if none. */
+    changes: DeepPartial<T> | null;
+    /** A queue of pending state update functions/objects to be applied sequentially. */
+    pendingChanges: Array<StateUpdater<T>>;
+    /** Names of all currently registered middlewares. */
+    middlewares: string[];
+    /** Details of the middleware currently running. Null if none. */
+    runningMiddleware: {
+        id: string;
+        name: string;
+        startTime: number;
+    } | null;
+    /** Indicates if the store is currently within an active transaction block. */
+    transactionActive: boolean;
+}
+/**
+ * Event types emitted by the state store for observability and debugging.
+ */
+type StoreEvent = "update:start" | "update:complete" | "middleware:start" | "middleware:complete" | "middleware:error" | "middleware:blocked" | "middleware:executed" | "transaction:start" | "transaction:complete" | "transaction:error" | "persistence:ready" | "persistence:queued" | "persistence:success" | "persistence:retry" | "persistence:failed" | "persistence:queue_cleared" | "persistence:init_error" | "action:start" | "action:complete" | "action:error" | "selector:accessed" | "selector:changed";
+/**
+ * Represents a state update, which can be:
+ * 1. The full new state (`T`).
+ * 2. A partial update object (`DeepPartial<T>`).
+ * 3. A function that receives the current state and returns a partial update (sync or async).
+ */
+type StateUpdater<T> = T | DeepPartial<T> | ((state: T) => DeepPartial<T> | Promise<DeepPartial<T>>);
+/**
+ * Core types for the reactive data store
+ */
+/**
+ * Type for a Transform Middleware function.
+ * It modifies (transforms) the incoming changes and must return a `DeepPartial<T>`.
+ */
+type TransformMiddleware<T> = (state: T, changes: DeepPartial<T>) => Promise<DeepPartial<T>> | DeepPartial<T>;
+/**
+ * Type for a Blocking Middleware function.
+ * It determines whether the state update should proceed or be blocked.
+ * It returns a boolean or an object containing a `block` boolean and an optional `error`.
+ */
+type BlockingMiddleware<T> = (state: T, changes: DeepPartial<T>) => Promise<boolean | {
+    block: boolean;
+    error?: Error;
+}> | boolean | {
+    block: boolean;
+    error?: Error;
+};
+/**
+ * Type representing the configuration object passed to the `use` method to register a middleware.
+ */
+interface MiddlewareConfig<T> {
+    /** The middleware function (can be a transform or blocking middleware). */
+    action: TransformMiddleware<T> | BlockingMiddleware<T>;
+    /** An optional, human-readable name for the middleware. */
+    name?: string;
+    /** If true, the middleware is treated as a blocking middleware (must return a boolean or `{ block: boolean }`). */
+    block?: boolean;
+}
+/**
+ * Interface for a reactive selector result, providing access to the value and subscription capabilities.
+ */
+interface ReactiveSelector<S> {
+    /** Unique identifier for the selector. */
+    id: string;
+    /** Function to get the current computed value of the selector. */
+    get: () => S;
+    /**
+     * Subscribes a callback function to run whenever the selector's result changes.
+     * Returns an unsubscribe function.
+     */
+    subscribe: (callback: (state: S) => void) => () => void;
+}
+interface ActionWatcher {
+    /** Unique identifier for the action */
+    name: string;
+    /** Function to get the current computed value of the action. */
+    status: () => boolean;
+    /**
+     * Subscribes a callback function to run whenever the action's status changes.
+     * Returns an unsubscribe function.
+     */
+    subscribe: (callback: () => void) => () => void;
+}
+interface TransactionOptions {
+    /** If true, blocks resolution until changes are fully committed to the database row */
+    flush?: boolean;
+}
+/**
+ * Interface defining the contract for the core data state store.
+ * T must be an object type.
+ */
+interface DataStore<T extends object> {
+    /**
+     * Gets the current state of the store.
+     * @param clone If true, returns a deep clone of the state; otherwise, returns the internal state reference.
+     * @returns The current state T.
+     */
+    get(clone?: boolean): T;
+    /**
+     * Registers a named action function that can modify the state.
+     * @param action The action configuration object.
+     * @returns A function to unregister the action.
+     */
+    register<R extends any[]>(action: {
+        name: string;
+        fn: (state: T, ...args: R) => DeepPartial<T> | Promise<DeepPartial<T>>;
+        debounce?: {
+            delay: number;
+            condition?: (previous: R, current: R) => boolean;
+        };
+    }): () => void;
+    /**
+     * Executes (dispatches) a previously registered action by its name.
+     * @param name The name of the action.
+     * @param args The parameters to pass to the action function.
+     * @returns A promise that resolves to the final state after the action and subsequent updates are complete.
+     */
+    dispatch<R extends any[]>(name: string, ...args: R): Promise<T>;
+    /**
+     * Sets or updates the state using a StateUpdater.
+     * @param update The new state, partial state, or a function returning a partial state.
+     * @param options Configuration options for the set operation.
+     * @returns A promise that resolves to the current state when the update is complete.
+     */
+    set(update: StateUpdater<T>, options?: {
+        force?: boolean;
+        actionId?: string;
+    }): Promise<T>;
+    /**
+     * Creates a reactive selector that computes a derived value and tracks dependencies.
+     * @param selector A function to compute the derived state value S from the full state T.
+     * @returns A `ReactiveSelector<S>` object.
+     */
+    select<S>(selector: (state: T) => S): ReactiveSelector<S>;
+    /**
+     * Subscribes a callback to run when the data at the specified path(s) changes.
+     * @param path A single path string or an array of path strings to watch.
+     * @param callback The function to execute when a change occurs in the watched path(s).
+     * @param options Extra options to pass to the event bus
+     * @returns An unsubscribe function.
+     */
+    watch(path: string | Array<string>, callback: (state: T) => void, options?: SubscribeOptions): () => void;
+    /**
+     * Subscribes to execution‑status changes of a registered action.
+     *
+     * The provided callback is called **every time** the action transitions
+     * between idle and running (i.e. on `action:start`, `action:complete`, or
+     * `action:error` for the given name). The current status can also be read
+     * synchronously with `isActionRunning(name)`.
+     *
+     * **Deferred listener teardown**
+     * To avoid unnecessary churn when subscriptions are rapidly created and
+     * destroyed, the underlying event listeners are not removed immediately
+     * on unsubscribe. Instead, a *pending reset* is queued via `queueMicrotask`.
+     * If a new subscription for the same action arrives before that microtask
+     * executes, the reset is silently cancelled and the already‑established
+     * listeners are reused. This keeps the subscription infrastructure stable
+     * and prevents cascading notifications that could otherwise arise from
+     * repeated subscribe‑unsubscribe‑subscribe cycles.
+     *
+     * @param name - The name of the action to watch.
+     * @returns An ActionWatcher
+     */
+    watchAction(name: string): ActionWatcher;
+    /**
+     * Executes an operation function within a transaction block.
+     * All state updates (`set` or actions) within the transaction are batched and applied atomically (all or nothing).
+     * @param operation The function containing the state updates.
+     * @returns A promise that resolves to the return value of the operation function.
+     */
+    transaction<R>(operation: () => R | Promise<R>, options?: TransactionOptions): Promise<R>;
+    /**
+     * Registers a middleware function to intercept state updates.
+     * @param props The middleware configuration.
+     * @returns A function to unregister the middleware.
+     */
+    use(props: MiddlewareConfig<T>): () => boolean;
+    /**
+     * Subscribes a listener to a specific store event type.
+     * @param event The type of store event to listen for.
+     * @param listener The callback function to execute when the event fires.
+     * @returns An unsubscribe function.
+     */
+    on(event: StoreEvent, listener: (data: any) => void): () => void;
+    /**
+     * Returns the unique identifier of the store instance.
+     */
+    id(): string;
+    /**
+     * Checks whether the store is fully initialized and ready for use.
+     */
+    isReady(): boolean;
+    /**
+     * Returns a promise that resolves once the store is fully initialised.
+     * Safe to call multiple times — all callers share the same latch.
+     *
+     * @param timeout - Optional maximum wait time in milliseconds.
+     * @throws {TimeoutError} If the store does not become ready within the timeout.
+     *
+     * @example
+     * await store.ready();
+     * const state = store.get();
+     */
+    ready(timeout?: number): Promise<void>;
+    /**
+     * Returns a readonly snapshot of the current execution state of the store.
+     */
+    state(): Readonly<StoreExecutionState<T>>;
+}
+
+/**
+ * Defines the lifecycle and sharing strategy for an artifact within the container.
+ */
+
+/**
+ * Defines the lifecycle and sharing strategy for an artifact.
+ */
+type ArtifactScope = 
+/**
+ * **Singleton:** A single instance of the artifact is created and shared across all resolutions
+ * within the container. It is created once (often lazily) and reused until invalidated.
+ */
+"singleton"
+/**
+ * **Transient:** A new instance of the artifact is created every time it is resolved.
+ * Transient artifacts do not participate in caching or shared state management.
+ */
+ | "transient";
+/**
+ * Represents a snapshot of an artifact's state and dependencies for debugging purposes.
+ * Provides insight into the artifact's current status and its position within the dependency graph.
+ */
+interface ArtifactDebugNode {
+    /** The unique identifier (key) of the artifact. */
+    id: string;
+    /** The scope of the artifact (Singleton or Transient). */
+    scope: ArtifactScope;
+    /**
+     * The current status of the artifact, indicating its lifecycle phase.
+     * - `'active'`: The artifact is successfully built and its instance is available.
+     * - `'error'`: The artifact failed to build due to an external (runtime) error.
+     * - `'idle'`: The artifact has not yet been built (for lazy singletons) or has been disposed.
+     * - `'building'`: The artifact's factory is currently executing.
+     * - `'pending'`: The artifact is waiting to be built, often after an invalidation and before any debounce.
+     */
+    status: "active" | "error" | "idle" | "building" | "pending" | "debouncing";
+    /** A list of artifact keys that this artifact directly depends on. */
+    dependencies: string[];
+    /** A list of artifact keys that directly depend on this artifact (its consumers). */
+    dependents: string[];
+    /** A list of state paths (selectors) that this artifact depends on. */
+    stateDependencies: string[];
+    /** The number of times this artifact's factory has been successfully executed/rebuilt. */
+    buildCount: number;
+}
+/**
+ * Context provided to the `use` callback within an artifact factory.
+ * It allows an artifact to declare dependencies on other artifacts and state slices.
+ * @template TRegistry The type mapping artifact keys to their artifact types.
+ * @template TState The type of the global state managed by the DataStore.
+ */
+interface UseDependencyContext<TRegistry extends Record<string, any>, TState extends object> {
+    /**
+     * Resolves another artifact from the container and registers a dependency on it.
+     * If the dependency changes, the current artifact will be invalidated and rebuilt.
+     * @template K The key of the artifact to resolve.
+     * @param key The key of the artifact to resolve.
+     * @param params Parameters with which to resolve the artifact
+     * @returns A Promise that resolves to a `ResolvedArtifact` containing the instance
+     * or an external error.
+     * @throws {SystemError} if the key is missing or if resolving creates a circular dependency.
+     */
+    resolve<K extends keyof TRegistry>(key: K, params?: any): Promise<ResolvedArtifact<TRegistry[K]>>;
+    /**
+     * Resolves another artifact from the container and registers a dependency on it.
+     * If the dependency changes, the current artifact will be invalidated and rebuilt.
+     * @template K The key of the artifact to resolve.
+     * @param key The key of the artifact to resolve.
+     * @param params Parameters with which to resolve the artifact
+     * @returns A Promise that resolves to a the resolved instance, unlike
+     * resolve, this will throw an error if resolution fails.
+     * @throws {SystemError} if any error occurs during resolution.
+     */
+    require<K extends keyof TRegistry>(key: K, params?: any): Promise<TRegistry[K]>;
+    /**
+     * Selects a slice of the global state and registers a dependency on it.
+     * If the selected state slice changes (based on a deep comparison), the current
+     * artifact will be invalidated and rebuilt.
+     * @template S The type of the selected state slice.
+     * @param selector A function that takes the full state and returns a slice of state.
+     * @returns The selected slice of state.
+     */
+    select<S>(selector: (state: TState) => S, options?: SubscribeOptions): S;
+}
+/**
+ * Context object provided to an artifact stream producer function (`ctx.stream` callback).
+ * It contains methods and properties necessary for managing the stream and communicating
+ * new artifact values to the container and its consumers.
+ *
+ * @template TState The type of the global state.
+ * @template TArtifact The type of the artifact being streamed.
+ */
+type ArtifactStreamContext<TState, TArtifact> = {
+    /**
+     * The current value of the artifact. This is `undefined` before the first value is emitted.
+     * Useful for diffing or migrating state during an update.
+     * @returns The current artifact value or `undefined`.
+     */
+    value: () => TArtifact | undefined;
+    /**
+     * An AbortSignal that indicates if the stream has been cancelled or aborted
+     * from the consumer side (e.g., due to container disposal or artifact invalidation).
+     * Producers should check this signal and stop processing when it is set to prevent leaks.
+     */
+    signal: AbortSignal;
+    /**
+     * A function to asynchronously emit a new value of the artifact to the container.
+     * Calling this function updates the artifact's resolved value, triggers invalidation
+     * for its dependents, and updates the `value()` property for subsequent emissions.
+     *
+     * @param value The new artifact value to emit.
+     * @returns A Promise that resolves when the value has been sent and dependents have been notified.
+     */
+    emit: (value: TArtifact) => Promise<void>;
+    /**
+     * Dispatches a state update to the global store, analogous to a standard `setState`.
+     * **Note:** This does not automatically register a dependency for the current artifact.
+     * @param update A `StateUpdater` function or a partial state object.
+     * @param options Optional settings for the update, including `force` and `actionId`.
+     * @returns A Promise that resolves when the state update is complete.
+     */
+    set(update: StateUpdater<TState>, options?: {
+        force?: boolean;
+        actionId?: string;
+    }): Promise<any>;
+};
+/**
+ * The full context provided to an artifact's factory function.
+ * This context allows the artifact to interact with the container,
+ * declare dependencies, manage its lifecycle, and update its value.
+ * @template TRegistry The type mapping artifact keys to their artifact types.
+ * @template TState The type of the global state managed by the DataStore.
+ * @template TArtifact The type of the artifact being created by the factory.
+ */
+type ArtifactFactoryContext<TRegistry extends Record<string, any>, TState extends object, TArtifact, TExtra extends Record<string, any> = {}> = TExtra & {
+    /**
+     * Returns the current global state object. This is a non-reactive read;
+     * changes to the state will not automatically invalidate the artifact
+     * unless explicitly selected via `ctx.use` and `ctx.select`.
+     * @returns The current global state.
+     */
+    state(): TState;
+    /**
+     * The previous instance of the artifact if it's a Singleton and is being rebuilt
+     * after an invalidation. This is `undefined` on the initial build.
+     * Useful for diffing, migrating state, or reusing resources during an update.
+     */
+    previous?: TArtifact;
+    /**
+     * Executes a callback within a dependency tracking context.
+     * Any `resolve` or `select` calls made inside this callback will register
+     * dependencies for the current artifact.
+     * @template R The return type of the callback.
+     * @param callback The function to execute to resolve dependencies.
+     * @returns A Promise resolving to the result of the callback.
+     */
+    use<R>(callback: (ctx: UseDependencyContext<TRegistry, TState>) => R | Promise<R>): Promise<R>;
+    /**
+     * Registers a cleanup function to be executed when the **current instance** of the
+     * artifact is invalidated and before its new instance is built. This is useful
+     * for releasing resources (e.g., event listeners) specific to the *previous* instance.
+     * @param cleanup The cleanup function.
+     */
+    onCleanup(cleanup: ArtifactCleanup): void;
+    /**
+     * Registers a dispose function to be executed when the artifact is
+     * permanently removed from the container or the container itself is disposed.
+     * This is for final, permanent resource release.
+     * @param callback The dispose function.
+     */
+    onDispose(callback: ArtifactCleanup): void;
+    /**
+     * Starts a streaming process for a Singleton artifact.
+     * The callback receives an `ArtifactStreamContext` to emit values and manage the
+     * stream's lifecycle. It can return a cleanup function (or a Promise resolving
+     * to one) to handle resource disposal.
+     * * @param callback - The streaming logic implementation. Can be synchronous or
+     * asynchronous, optionally returning a cleanup function.
+     * @throws {SystemError} If called on a Transient artifact, as they do not
+     * support persistent streaming states.
+     */
+    stream(callback: (ctx: ArtifactStreamContext<TState, TArtifact>) => (void | (() => void | Promise<void>)) | Promise<void | (() => void | Promise<void>)>): void;
+    stream(callback: (ctx: ArtifactStreamContext<TState, TArtifact>) => (void | (() => void | Promise<void>)) | Promise<void | (() => void | Promise<void>)>): void;
+    /**
+     * An AbortSignal that indicates if the artifacts has been unregistered
+     */
+    signal: AbortSignal;
+    /** For parameterized artifacts: the parameters that were passed during resolve/watch. */
+    params?: any;
+};
+/**
+ * A function that performs cleanup or disposal logic for an artifact, potentially asynchronously.
+ * Used for `onCleanup` and `onDispose` callbacks.
+ */
+type ArtifactCleanup = () => void | Promise<void>;
+/**
+ * Common properties shared across all possible states of a resolved artifact.
+ * @template TArtifact The type of the resolved artifact instance.
+ */
+interface ResolvedArtifactBase {
+    /**
+     * A function to manually trigger cleanup associated with this specific
+     * resolved instance. This is typically only relevant for Transient artifacts
+     * where the consumer is responsible for cleanup.
+     */
+    cleanup?: ArtifactCleanup;
+    /**
+     * Manually invalidates this artifact, triggering its rebuild and
+     * cascading invalidations to its dependents.
+     * @param replace If `true`, forces immediate rebuild without debounce delay.
+     * @param fatal If `true`, the artifact will not be rebuilt until next resolve
+     * regardless of the lazy option during registration.
+     */
+    invalidate(replace?: boolean, fatal?: boolean): Promise<void>;
+}
+/**
+ * State of an artifact that is successfully built and ready for use.
+ * The instance is guaranteed to be present.
+ * @template TArtifact The type of the resolved artifact instance.
+ */
+interface ReadyArtifact<TArtifact> extends ResolvedArtifactBase {
+    /** The successfully resolved instance of the artifact. */
+    instance: TArtifact;
+    /** Indicates whether the artifact is ready and has an instance. */
+    ready: true;
+    error?: undefined;
+}
+/**
+ * State of an artifact that failed to build due to an external error.
+ * The instance is guaranteed to be absent.
+ */
+interface ErrorArtifact extends ResolvedArtifactBase {
+    instance?: undefined;
+    ready: false;
+    /**
+     * Any runtime or external error that occurred during the artifact's factory
+     * execution (e.g., network fetch failed).
+     */
+    error: any;
+}
+/**
+ * State of an artifact that is pending, idle, or currently building.
+ * Both instance and error are absent.
+ */
+interface PendingArtifact extends ResolvedArtifactBase {
+    /** The instance is absent while pending or idle. Always undefined. */
+    instance?: undefined;
+    ready: false;
+    error?: undefined;
+}
+/**
+ * The result of an artifact resolution. This is a union type representing
+ * the artifact in one of three possible states: Ready, Error, or Pending/Idle.
+ *
+ * This structure allows consuming code to narrow the type based on the
+ * boolean flag `ready` or the presence of the `error` property.
+ *
+ * @template TArtifact The type of the resolved artifact instance.
+ */
+type ResolvedArtifact<TArtifact> = ReadyArtifact<TArtifact> | ErrorArtifact | PendingArtifact;
+type KeyedResolvedArtifact<TRegistry, K extends keyof TRegistry> = ResolvedArtifact<TRegistry[K]> & {
+    [P in K]?: TRegistry[K];
+};
+/**
+ * The factory function responsible for creating an artifact's instance.
+ * It receives an `ArtifactFactoryContext` to interact with the container
+ * and declare dependencies.
+ * @template TRegistry The type mapping artifact keys to their artifact types.
+ * @template TState The type of the global state managed by the DataStore.
+ * @template TArtifact The type of the artifact this factory produces.
+ * @param context The context for creating the artifact.
+ * @returns The artifact instance or a Promise resolving to it.
+ */
+type ArtifactFactory<TRegistry extends Record<string, any>, TState extends object, TArtifact, TExtra extends Record<string, any> = {}> = (context: ArtifactFactoryContext<TRegistry, TState, TArtifact, TExtra>) => TArtifact | Promise<TArtifact>;
+/**
+ * An interface for observing changes to an artifact without direct resolution,
+ * typically used for UI binding or monitoring.
+ * Provides a way to get the current resolved artifact and subscribe to updates.
+ * @template TArtifact The type of the artifact being watched.
+ */
+interface ArtifactObserver<TRegistry, K extends keyof TRegistry> {
+    /** The unique identifier (key) of the artifact being watched. */
+    id: string;
+    /**
+     * Number of active references (watchers) to this observer instance.
+     * Incremented on each `watch()` call, decremented on each `dispose()` call.
+     */
+    count: number;
+    /**
+     * Retrieves the current `ResolvedArtifact` for the watched key.
+     * @param resolve Flag indicating whether we should resolve the artifact
+     * immediately. Defaults to `false`
+     * @returns The resolved artifact, including its instance and status.
+     */
+    get(resolve?: boolean): KeyedResolvedArtifact<TRegistry, K>;
+    /**
+     * Subscribes a callback function to be invoked whenever the artifact's
+     * state (instance, error, or readiness) changes.
+     * @param callback The function to call on updates. It receives the new `ResolvedArtifact`.
+     * @param eager a boolean indicating whether we should immediately call the
+     * callback after subscription. Defaults to `true`
+     * @returns A function to unsubscribe the callback and stop receiving updates.
+     */
+    subscribe(callback: (artifact: KeyedResolvedArtifact<TRegistry, K>) => void, eager?: boolean): () => void;
+    /**
+     * Resolves another artifact from the container and registers a dependency on it.
+     * If the dependency changes, the current artifact will be invalidated and rebuilt.
+     * @returns A Promise that resolves to a `ResolvedArtifact` containing the instance
+     * or an external error.
+     * @throws {SystemError} if resolution fails.
+     */
+    resolve(): Promise<KeyedResolvedArtifact<TRegistry, K>>;
+}
+/**
+ * Configuration options for defining an artifact. These options control
+ * its lifecycle, instantiation, and error handling behavior.
+ * @template TState The type of the global state.
+ * @template TArtifact The resolved type of the artifact instance.
+ * @template TRegistry The type mapping of all artifacts in the container.
+ */
+interface ArtifactTemplate<TState extends object, TArtifact, TRegistry extends Record<string, any> = Record<string, any>, TExtra extends Record<string, any> = {}> {
+    /** The unique key identifying this artifact within the registry. */
+    key: keyof TRegistry;
+    /** The factory function responsible for creating the artifact's instance. */
+    factory: ArtifactFactory<TRegistry, TState, TArtifact, TExtra>;
+    /**
+     * The scope of the artifact, determining its lifecycle and sharing strategy.
+     * Defaults to `ArtifactScopes.Singleton`.
+     */
+    scope?: ArtifactScope;
+    /**
+     * If `true` (default), the artifact's factory is executed only when the artifact
+     * is first requested (lazy instantiation). If `false`, the artifact is built
+     * immediately upon registration (only applies to Singleton scopes).
+     */
+    lazy?: boolean;
+    /**
+     * Maximum time in milliseconds allowed for the artifact's factory function
+     * to complete execution. If exceeded, the factory will time out.
+     */
+    timeout?: number;
+    /**
+     * Number of times to retry the artifact's factory on failure due to an
+     * external (runtime) error (e.g., an exception in an async dependency).
+     * SystemErrors (e.g., key not found) are not retried. Defaults to `0`.
+     */
+    retries?: number;
+    /**
+     * Base debounce time in milliseconds for invalidation events originating
+     * from this artifact's dependencies. This delays the rebuild process to
+     * aggregate multiple rapid changes.
+     */
+    debounce?: number;
+    /** If defined, the artifact is parameterized. Receives the user‑supplied params and returns a unique string key. */
+    paramKey?: (params: Record<string, unknown>) => string;
+    virtual?: true;
+}
+
+/**
+ * A dependency injection container for managing the lifecycle, dependencies,
+ * and instances of "artifacts" (any JavaScript/TypeScript object or value).
+ *
+ * Separated concerns:
+ * - ArtifactRegistry: Stores artifact templates (factories + options)
+ * - ArtifactCache: Stores resolved singleton instances
+ * - ArtifactDependencyGraph: Tracks artifact dependencies using DependencyGraph
+ * - ArtifactManager: Handles lifecycle (build, invalidate, dispose)
+ * - ArtifactObserverManager: Manages watchers and subscriptions
+ *
+ * @template TRegistry A type that maps artifact keys to their types
+ * @template TState The type of the global state object
+ */
+declare class ArtifactContainer<TRegistry extends Record<string, any> = Record<string, any>, TState extends object = any> {
+    private readonly registry;
+    private readonly cache;
+    private readonly graph;
+    private readonly manager;
+    private readonly observer;
+    private readonly store;
+    /**
+     * Creates a new ArtifactContainer instance.
+     * @param store An object providing functions to interact with a global data store
+     */
+    constructor(store: Pick<DataStore<TState>, "watch" | "get" | "set">);
+    /**
+     * Provides debug information about all artifacts currently registered in this container.
+     *
+     * Status mapping:
+     * - `"building"` — factory is currently executing (buildOnce.running())
+     * - `"debouncing"` — invalidation is pending behind a debounce timer
+     * - `"error"` — last build attempt failed
+     * - `"active"` — successfully built and instance is available
+     * - `"idle"` — not yet built (lazy) or has been disposed
+     *
+     * @returns An array of ArtifactDebugNode objects
+     */
+    debugInfo(): ArtifactDebugNode[];
+    /**
+     * Registers a new artifact with the container.
+     * If an artifact with the same key already exists, it will be overwritten and disposed.
+     * For Singleton, non-lazy artifacts, the factory will be immediately invoked.
+     *
+     * @param params The registration parameters
+     * @returns A cleanup function that unregisters the artifact
+     */
+    register<K extends keyof TRegistry>(params: ArtifactTemplate<TState, TRegistry[K], TRegistry>): () => void;
+    /**
+     * Returns a boolean indicating whether a template exists for an artifact.
+     *
+     * @param key The unique identifier of the artifact.
+     * @returns boolean.
+     */
+    has<K extends keyof TRegistry>(key: K): boolean;
+    /**
+     * Unregisters an artifact from the container, disposing of its current instance
+     * and removing all associated resources and dependency links.
+     *
+     * Also evicts the observer watcher cache entry so singleton watchers do not
+     * outlive the artifact's registration.
+     *
+     * @param key The unique identifier of the artifact
+     */
+    unregister<K extends keyof TRegistry>(key: K, params?: Record<string, unknown>): Promise<void>;
+    /**
+     * Resolves an artifact by its key, returning its instance or an error.
+     * Handles dependency resolution, cycle detection, caching, and retry logic.
+     *
+     * The keyed index property (`artifact[key]`) is set inside `cache.package()`
+     * so it is always consistent with `artifact.instance`. No post-hoc mutation
+     * is needed here.
+     *
+     * @param key The unique identifier for the artifact
+     * @param params Parameters with which to resolve the artifact
+     * @returns A Promise that resolves to a ResolvedArtifact
+     * @throws {ArtifactNotFoundError} if the artifact is not found
+     */
+    resolve<K extends keyof TRegistry>(key: K, params?: Record<string, unknown>): Promise<KeyedResolvedArtifact<TRegistry, K>>;
+    /**
+     * Resolves an artifact by its key, returning its instance directly.
+     * Throws if resolution fails.
+     *
+     * @param key The unique identifier for the artifact
+     * @param params Parameters with which to resolve the artifact
+     * @returns A Promise that resolves to the artifact instance
+     * @throws {ArtifactNotFoundError} if the artifact is not found
+     * @throws the artifact's error if resolution failed
+     */
+    require<K extends keyof TRegistry>(key: K, params?: Record<string, unknown>): Promise<TRegistry[K]>;
+    /**
+     * Returns an ArtifactObserver for a given artifact key.
+     * The observer allows subscribing to changes in the artifact's resolved value.
+     *
+     * @param key The unique identifier for the artifact
+     * @param params Parameters with which to resolve the artifact
+     * @param ttl Delay before the watcher is cleaned up if we have no subscriber
+     * @returns An ArtifactObserver instance
+     */
+    watch<K extends keyof TRegistry>(key: K, params?: Record<string, unknown>, ttl?: number): ArtifactObserver<TRegistry, K>;
+    /**
+     * Peeks at the resolved instance of an artifact without triggering resolution
+     * or registering a dependency.
+     *
+     * @param key The unique identifier for the artifact
+     * @returns The artifact instance if already built, otherwise undefined
+     */
+    peek<K extends keyof TRegistry>(key: K, params?: Record<string, unknown>): TRegistry[K] | undefined;
+    /**
+     * Invalidates an artifact, triggering rebuild and cascade to dependents.
+     *
+     * @param key The artifact key to invalidate
+     * @param options.replace If true, forces immediate rebuild bypassing debounce
+     * @param options.params for parametized artifacts
+     */
+    invalidate<K extends keyof TRegistry>(key: K, options?: {
+        replace?: boolean;
+        params?: Record<string, unknown>;
+    }): Promise<void>;
+    /**
+     * Notifies observers that an artifact has changed.
+     * Called by ArtifactManager during stream propagation.
+     *
+     * @param key The artifact key
+     */
+    notifyObservers(key: string): void;
+    /**
+     * Checks if an artifact has active watchers.
+     * Called by ArtifactManager to determine if lazy artifacts should rebuild.
+     *
+     * @param key The artifact key
+     * @returns True if the artifact has active watchers
+     */
+    hasWatchers(key: string): boolean;
+    /**
+     * Disposes of the entire container and all artifacts registered within it.
+     * Releases all resources, stops all watchers, and clears all internal state.
+     *
+     * Returns a Promise that resolves once all artifact teardowns have settled.
+     * Callers should await this method to guarantee full resource release.
+     */
+    dispose(): Promise<void>;
+}
+
+/**
+ * @file routing-pipeline.ts
+ * @description A production-grade, asynchronous, type-safe pipeline engine featuring conditional
+ * routing, checkpoint-based pause/resume mechanisms, concurrent step/sub-pipeline execution,
+ * atomic state transactions, and lifecycle event streaming.
+ */
+
+/** A generic state shape used by the pipeline. */
+interface State {
+    [key: string]: any;
+}
+/**
+ * Instructs the engine to pause the pipeline.
+ * The `pause` field is the `stageId` at which the pipeline should resume.
+ */
+interface PauseInstruction {
+    readonly pause: string;
+}
+/**
+ * All possible outcomes of a router:
+ * - `string`    → jump to a named stage
+ * - `null`      → terminate the pipeline
+ * - `undefined` → advance to the next stage in order (or natural end)
+ * - `PauseInstruction` → suspend and write a checkpoint
+ */
+type RoutingInstruction = string | null | undefined | PauseInstruction;
+/** Type guard for a pause instruction. */
+declare function isPauseInstruction(v: RoutingInstruction): v is PauseInstruction;
+/**
+ * Router used inside a **steps‑mode** stage.
+ * Receives the full state and a record of step results keyed by step id.
+ */
+type StepStageRouter<S extends object> = (state: S, results: Record<string, Result<DeepPartial<S>>>) => RoutingInstruction;
+/**
+ * Router used inside a **pipelines‑mode** stage.
+ * Receives the full state and a record of sub‑pipeline results keyed by
+ * sub‑pipeline id.
+ */
+type PipelineStageRouter<S extends object> = (state: S, results: Record<string, Result<PipelineRunResult<S>>>) => RoutingInstruction;
+/**
+ * Persisted checkpoint written to the run's store under the internal key
+ * `__pipeline_data__.<pipelineId>.<runId>`.
+ *
+ * The checkpoint is always written atomically with the state patches of the
+ * stage that triggered the pause.
+ */
+interface PipelineCheckpoint {
+    readonly runId: string;
+    readonly pipelineId: string;
+    readonly resumeAt: EntryAddress;
+    readonly pausedAtStageId: string;
+    readonly pausedAtStageLabel: string;
+    readonly pausedOn: string;
+}
+/** Engine‑internal namespace for all checkpoint data. */
+declare const PIPELINE_DATA_KEY: "__pipeline_data__";
+/**
+ * Run-scoped context injected into every step action as a second argument.
+ *
+ * All fields are immutable and captured at step registration time. Steps can
+ * use `runId` and `pipelineId` to initiate external async operations (e.g.
+ * storing a callback reference for webhook-driven pause/resume). The `signal`
+ * allows long-running async work inside a step to honour pipeline abort.
+ *
+ * For sub-pipeline steps, `pipelineId` reflects the sub-pipeline's own id,
+ * not the root definition id.
+ *
+ * @example
+ * ```ts
+ * const step: Step<MyState> = {
+ *   id: "send-email",
+ *   label: "Send approval email",
+ *   action: async (ctx, pcxt) => {
+ *     await emailService.send({
+ *       to: ctx.state().approverEmail,
+ *       callbackToken: pcxt.runId,   // stored so the webhook can resume
+ *     });
+ *     return {};
+ *   },
+ * };
+ * ```
+ */
+interface PipelineContext {
+    /** The unique identifier of the current run. */
+    readonly runId: string;
+    /**
+     * The id of the pipeline definition this step belongs to.
+     * For sub-pipeline steps this is the sub-pipeline's own id, not the root id.
+     */
+    readonly pipelineId: string;
+    /** The id of the stage this step belongs to. */
+    readonly stageId: string;
+    /** The id of this step. */
+    readonly stepId: string;
+    /**
+     * The AbortSignal for this run. Steps performing long-running async work
+     * should check or pass this signal so they can be cancelled promptly
+     * when `runContext.abort()` is called.
+     */
+    readonly signal: AbortSignal;
+}
+/**
+ * A single unit of work.
+ *
+ * The `action` receives an {@link ArtifactFactoryContext} typed to the
+ * pipeline's state shape `S`, and a {@link PipelineContext} carrying the
+ * run-scoped identifiers and abort signal. It must return a partial state
+ * patch on success, or throw on failure.
+ *
+ * The `PipelineContext` is captured at step registration time and is always
+ * consistent with this step's position in the pipeline tree.
+ */
+interface Step<S extends object = State> {
+    id: string;
+    label: string;
+    scope?: ArtifactScope;
+    timeout?: number;
+    retries?: number;
+    action: (ctx: ArtifactFactoryContext<{}, S, {}>, pcxt: PipelineContext) => Promise<DeepPartial<S>>;
+}
+/**
+ * A stage groups steps (steps mode) or sub‑pipelines (pipelines mode).
+ * Exactly one mode is active: if `pipelines` is non‑empty, steps are ignored.
+ */
+interface Stage<S extends object = State> {
+    id: string;
+    order: number;
+    label: string;
+    timeout?: number;
+    /** Steps defined for this stage. Used only when `pipelines` is empty. */
+    steps?: Record<string, Step<S>>;
+    /** Router for steps mode. */
+    router?: StepStageRouter<S>;
+    /** Sub‑pipelines for this stage. Non‑empty → pipelines mode. */
+    pipelines?: RoutingPipelineDefinition<S>[];
+    /** Router for pipelines mode. */
+    pipelinesRouter?: PipelineStageRouter<S>;
+}
+/**
+ * A pipeline definition is a collection of stages.
+ * Every pipeline has a unique `id` and a human‑readable `label`.
+ */
+interface RoutingPipelineDefinition<S extends object = State> {
+    id: string;
+    label: string;
+    stages: Stage<S>[];
+}
+/**
+ * Describes a specific entry point inside a sub‑pipeline.
+ */
+interface SubPipelineAddress {
+    /** Zero‑based index into the parent stage's `pipelines` array. */
+    index: number;
+    /** Stage id within the sub‑pipeline to start from. */
+    stage: string;
+    /** Optional step id to run (all other steps in the entry stage are skipped). */
+    step?: string;
+}
+/**
+ * Describes where in the pipeline tree execution should begin.
+ * Everything after the entry point executes normally.
+ */
+interface EntryAddress {
+    /** Stage id to start from. All earlier stages are skipped. */
+    stage: string;
+    /** If provided, only this step runs in the entry stage. */
+    step?: string;
+    /** If provided, the stage must be in pipelines mode; only this sub‑pipeline is launched. */
+    pipeline?: SubPipelineAddress;
+}
+/**
+ * The outcome of a pipeline run, as a discriminated union on `status`.
+ *
+ * Each variant carries exactly the fields that are always present for that
+ * outcome. Callers narrow with `result.status` and get full type-safety for
+ * variant-specific fields without defensive optional checks.
+ *
+ * - `succeeded` — pipeline ran to completion; `finalState` reflects all committed patches.
+ * - `paused`    — a router issued a pause instruction; `checkpoint` encodes the resume address.
+ * - `failed`    — a step, router, or transaction threw; `error` carries the cause.
+ */
+type PipelineRunResult<S extends object> = {
+    status: "succeeded";
+    runId: string;
+    finalState: S;
+} | {
+    status: "paused";
+    runId: string;
+    finalState: S;
+    checkpoint: PipelineCheckpoint;
+} | {
+    status: "failed";
+    runId: string;
+    finalState: S;
+    error: SystemError;
+};
+/** A node in the event path tree. */
+type PathNode = {
+    kind: "pipeline";
+    id: string;
+    label: string;
+} | {
+    kind: "stage";
+    id: string;
+    label: string;
+} | {
+    kind: "step";
+    id: string;
+    label: string;
+};
+/** Ordered list of ancestors from the root pipeline down to the event emitter. */
+type EventPath = readonly PathNode[];
+/**
+ * All events emitted during a run.
+ *
+ * stage:paused (#6) is a dedicated event for stages that pause, distinct from
+ * stage:success. Consumers should listen to both if they want to react to all
+ * terminal stage outcomes. stage:success is only emitted when the stage
+ * advances (or terminates) — never when it pauses.
+ */
+interface RunEventMap<S extends object> {
+    "pipeline:start": {
+        path: EventPath;
+        pipelineId: string;
+        pipelineLabel: string;
+        runId: string;
+    };
+    "pipeline:success": {
+        path: EventPath;
+        pipelineId: string;
+        pipelineLabel: string;
+        runId: string;
+        finalState: S;
+    };
+    "pipeline:paused": {
+        path: EventPath;
+        pipelineId: string;
+        pipelineLabel: string;
+        runId: string;
+        checkpoint: PipelineCheckpoint;
+        finalState: S;
+    };
+    "pipeline:failure": {
+        path: EventPath;
+        pipelineId: string;
+        pipelineLabel: string;
+        runId: string;
+        error: SystemError;
+    };
+    "stage:start": {
+        path: EventPath;
+        stageId: string;
+        stageLabel: string;
+        runId: string;
+        mode: "steps" | "pipelines";
+    };
+    "stage:success": {
+        path: EventPath;
+        stageId: string;
+        stageLabel: string;
+        runId: string;
+        nextInstruction: RoutingInstruction;
+    };
+    /** Emitted when a stage's router returns a pause instruction. Distinct from stage:success. */
+    "stage:paused": {
+        path: EventPath;
+        stageId: string;
+        stageLabel: string;
+        runId: string;
+        checkpoint: PipelineCheckpoint;
+    };
+    "stage:failure": {
+        path: EventPath;
+        stageId: string;
+        stageLabel: string;
+        runId: string;
+        error: SystemError;
+    };
+    "router:evaluated": {
+        path: EventPath;
+        stageId: string;
+        stageLabel: string;
+        runId: string;
+        instruction: RoutingInstruction;
+        interpretation: "jump" | "terminate" | "advance" | "natural-end" | "pause";
+    };
+    "step:start": {
+        path: EventPath;
+        stepId: string;
+        stepLabel: string;
+        runId: string;
+    };
+    "step:success": {
+        path: EventPath;
+        stepId: string;
+        stepLabel: string;
+        runId: string;
+    };
+    "step:failure": {
+        path: EventPath;
+        stepId: string;
+        stepLabel: string;
+        runId: string;
+        error: unknown;
+    };
+    "subpipeline:fork": {
+        path: EventPath;
+        stageId: string;
+        stageLabel: string;
+        runId: string;
+        subPipelineIds: string[];
+    };
+    "subpipeline:join": {
+        path: EventPath;
+        stageId: string;
+        stageLabel: string;
+        runId: string;
+        results: Record<string, Result<PipelineRunResult<S>>>;
+    };
+}
+/** Callback type for event subscriptions. */
+type RunEventHandler<S extends object, K extends keyof RunEventMap<S>> = (payload: RunEventMap<S>[K]) => void;
+interface ScopedEventBus<S extends object> {
+    emit<K extends keyof RunEventMap<S>>(event: K, payload: RunEventMap<S>[K]): void;
+    on<K extends keyof RunEventMap<S>>(event: K, handler: RunEventHandler<S, K>): () => void;
+}
+/**
+ * A unit of execution returned by {@link PipelineEngine.prepare} or
+ * {@link PipelineEngine.resume}.
+ *
+ * Subscribe to lifecycle events via {@link on}, abort via {@link abort}, and
+ * start execution with {@link run}.
+ */
+interface RunContext<S extends object> {
+    /** The unique identifier of this run (UUID v7). */
+    readonly id: string;
+    /**
+     * Subscribe to lifecycle events for this run.
+     * Sub‑pipeline events bubble here with full ancestry paths.
+     * Returns an unsubscribe function.
+     */
+    on<K extends keyof RunEventMap<S>>(event: K, handler: RunEventHandler<S, K>): () => void;
+    /** Cancel the run. Propagation occurs at the next stage boundary. */
+    abort(): void;
+    /**
+     * Execute the pipeline from the configured entry point.
+     *
+     * Once‑gated: concurrent callers join the in‑flight promise.
+     * A failed run is permanently sealed — obtain a new `RunContext` to retry.
+     * Never throws; failures are returned in a `Result`.
+     */
+    run(): Promise<Result<PipelineRunResult<S>>>;
+}
+/** Minimal logger interface used by the engine. */
+interface EngineLogger {
+    info: (msg: string, ctx?: any) => void;
+    error: (msg: string, ctx?: any) => void;
+}
+/**
+ * Configuration for {@link PipelineEngine}.
+ *
+ * @typeParam S - The shape of the state managed by the pipeline.
+ */
+interface PipelineEngineOptions<S extends object = State> {
+    /** Logger (defaults to a no‑op). */
+    logger?: EngineLogger;
+    /**
+     * **Required.** A factory that, given a `runId`, returns a `DataStore<S>`.
+     * The engine does **not** hold a global store; each run receives its own
+     * isolated store instance.
+     *
+     * For a new run (`prepare`), the factory should return an empty store.
+     * For a resumed run (`resume`), it must return the **same** store that was
+     * used during the original run (so that state and checkpoints are preserved).
+     */
+    storeFactory: (runId: string) => Promise<DataStore<S>>;
+    /**
+     * Optional factory that produces the initial state for every **new** run.
+     * The returned object is written to the store during `prepare()`.
+     * If omitted, the store remains empty.
+     */
+    initialStateFactory?: () => S;
+}
+/**
+ * The entry point for creating and resuming pipeline runs.
+ *
+ * @typeParam S - The shape of the state object.
+ *
+ * @example
+ * ```ts
+ * const engine = new PipelineEngine(myDefinition, {
+ *   storeFactory: (runId) => createMyStore(runId),
+ *   initialStateFactory: () => ({ counter: 0 }),
+ * });
+ *
+ * const ctx = await engine.prepare({ stage: "validate" });
+ * ctx.on("pipeline:success", (e) => console.log("done", e.finalState));
+ * const result = await ctx.run();
+ * ```
+ */
+declare class PipelineEngine<S extends object> {
+    private readonly definition;
+    private readonly logger;
+    private readonly storeFactory;
+    private readonly initialStateFactory;
+    private readonly index;
+    /**
+     * Constructs an engine tied to a fixed pipeline definition.
+     *
+     * @param definition - The pipeline topology (stages, steps, routers).
+     * @param options    - Engine configuration. `storeFactory` is mandatory.
+     */
+    constructor(definition: RoutingPipelineDefinition<S>, options: PipelineEngineOptions<S>);
+    /**
+     * Prepare an isolated {@link RunContext} for a **new** run.
+     *
+     * A fresh store is obtained via `storeFactory`, optionally seeded with the
+     * initial state from `initialStateFactory`. No execution occurs until
+     * `runContext.run()` is called.
+     *
+     * @param entry - Optional address describing where to start execution.
+     *                Omit to start from the lowest‑order stage.
+     * @param runId - Optional run identifier (UUID v7). Generated if omitted.
+     * @returns A promise that resolves with a ready‑to‑run `RunContext`.
+     */
+    prepare(entry?: EntryAddress, runId?: string): Promise<RunContext<S>>;
+    /**
+     * Reconstruct a {@link RunContext} for a previously paused run.
+     *
+     * The store for the given `runId` must still contain the checkpoint and
+     * state at the time of the pause. The context is returned ready to run;
+     * no state is altered until `runContext.run()` is called.
+     *
+     * @param runId - The identifier of the paused run.
+     * @returns A result containing the `RunContext`, or a failure if no
+     *          checkpoint exists or the pipeline id does not match.
+     */
+    resume(runId: string): Promise<Result<RunContext<S>>>;
+    /**
+     * Constructs a {@link RunContextImpl} with all necessary dependencies.
+     *
+     * This method is package-internal. External callers use prepare() or resume().
+     * Sub-pipelines access it through the {@link SubPipelineFactory} interface,
+     * which is the only reference RunContextImpl holds to the engine.
+     *
+     * A single {@link ArtifactContainer} is created per run at root level and
+     * shared across all sub-pipelines. Steps are registered under namespaced keys
+     * encoding their full lineage (keyPrefix:stageId:stepId), ensuring cache
+     * isolation without allocating separate containers per sub-pipeline.
+     *
+     * The {@link AbortController} is created here and its signal is immediately
+     * threaded into {@link registerSteps} so that every step factory closure
+     * captures the correct signal at registration time.
+     *
+     * @param runId      - The run identifier (same for parent and sub‑pipelines).
+     * @param pipeline   - The pipeline (sub‑)definition.
+     * @param entry      - Entry address; `undefined` means start from the beginning.
+     * @param store      - The shared store instance for this run.
+     * @param parentBus  - Parent scoped bus for event bubbling (root runs pass undefined).
+     * @param parentPath - Event path from the root.
+     * @param container  - Shared container (created once at root; passed down to sub-pipelines).
+     * @param keyPrefix  - Namespacing prefix for artifact keys within the shared container.
+     */
+    buildRunContext(runId: string, pipeline: RoutingPipelineDefinition<S>, entry: EntryAddress | undefined, store: DataStore<S>, parentBus: ScopedEventBus<S> | undefined, parentPath: EventPath, container?: ArtifactContainer<Record<string, DeepPartial<S>>, S>, keyPrefix?: string): RunContext<S>;
+}
+
+export { type EngineLogger, type EntryAddress, type EventPath, PIPELINE_DATA_KEY, type PathNode, type PauseInstruction, Pipeline, type PipelineCheckpoint, type PipelineContext, type PipelineDefinition, PipelineEngine, type PipelineEngineOptions, type PipelineEventMap, type PipelineRunResult, type PipelineStageRouter, type PipelineStep, type PipelineStepDefinition, Result, type RoutingInstruction, type RoutingPipelineDefinition, type RunContext, type RunEventHandler, type RunEventMap, SequentialExecutionContext, type Stage, type StageCarry, type State, type Step, type StepStageRouter, type SubPipelineAddress, isPauseInstruction };