@asaidimu/utils-pipeline 1.0.2 → 1.0.4

package/index.d.ts

@@ -1182,22 +1182,27 @@ interface State {
     [key: string]: any;
 }
 /**
- * Instructs the engine to pause the pipeline.
- * The `pause` field is the `stageId` at which the pipeline should resume.
+ * Instructs the factory to pause the pipeline.
+ *
+ * - `pause`   — the `stageId` at which the pipeline should resume.
+ * - `timeout` — how long (ms) the registry should hold the live RunContext
+ *               before running the deferred container export and clearing the
+ *               strong reference. Omit to use the registry's configured default.
+ *               A value of 0 means export immediately on pause (no deferral).
+ * - `persist` — kept for backward compatibility; when true the registry will
+ *               always export the container bundle at expiry regardless of
+ *               whether resume was called. Ignored if timeout is 0.
  */
 interface PauseInstruction {
     readonly pause: string;
-    /**
-     * If true, the engine will snapshot the entire ArtifactContainer
-     * and store the bundle in the checkpoint. Defaults to false.
-     */
+    readonly timeout?: number;
     readonly persist?: boolean;
 }
 /**
  * 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)
+ * - `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;
@@ -1220,6 +1225,10 @@ type PipelineStageRouter<S extends object> = (state: S, results: Record<string,
  *
  * The checkpoint is always written atomically with the state patches of the
  * stage that triggered the pause.
+ *
+ * `containerBundle` is intentionally absent at write time — the factory never
+ * exports. The registry writes it into the checkpoint (via writeCheckpoint)
+ * when the pause timeout fires and the live RunContext is about to be released.
  */
 interface PipelineCheckpoint {
     readonly runId: string;
@@ -1228,9 +1237,10 @@ interface PipelineCheckpoint {
     readonly pausedAtStageId: string;
     readonly pausedAtStageLabel: string;
     readonly pausedOn: string;
+    /** Written by the registry at timeout expiry, never by the factory. */
     readonly containerBundle?: ExportedContainerState;
 }
-/** Engine‑internal namespace for all checkpoint data. */
+/** Factory-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.
@@ -1391,10 +1401,14 @@ type EventPath = readonly PathNode[];
 /**
  * All events emitted during a run.
  *
- * stage:paused (#6) is a dedicated event for stages that pause, distinct from
+ * stage:paused (#8) 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.
+ *
+ * pipeline:paused carries `pauseTimeout` forwarded from the PauseInstruction
+ * so the PipelineRegistry can arm its cleanup timer with the correct duration
+ * without re-reading or re-parsing the instruction.
  */
 interface RunEventMap<S extends object> {
     "pipeline:start": {
@@ -1417,6 +1431,12 @@ interface RunEventMap<S extends object> {
         runId: string;
         checkpoint: PipelineCheckpoint;
         finalState: S;
+        /**
+         * The timeout value from the PauseInstruction, forwarded verbatim.
+         * Undefined means the registry should use its configured default.
+         * 0 means export immediately (no deferral window).
+         */
+        pauseTimeout: number | undefined;
     };
     "pipeline:failure": {
         path: EventPath;
@@ -1503,8 +1523,8 @@ interface ScopedEventBus<S extends object> {
     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}.
+ * A unit of execution returned by {@link PipelineFactory.prepare} or
+ * {@link PipelineFactory.resume}.
  *
  * Subscribe to lifecycle events via {@link on}, abort via {@link abort}, and
  * start execution with {@link run}.
@@ -1529,27 +1549,30 @@ interface RunContext<S extends object> {
      */
     run(): Promise<Result<PipelineRunResult<S>>>;
 }
-/** Minimal logger interface used by the engine. */
+/** Minimal logger interface used by the factory. */
 interface EngineLogger {
     info: (msg: string, ctx?: any) => void;
     error: (msg: string, ctx?: any) => void;
+    warn: (msg: string, ctx?: any) => void;
 }
 /**
- * Configuration for {@link PipelineEngine}.
+ * Configuration for {@link PipelineFactory}.
  *
  * @typeParam S - The shape of the state managed by the pipeline.
  */
-interface PipelineEngineOptions<S extends object = State> {
+interface PipelineFactoryOptions<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.
+     * The factory does **not** hold a global store; each run receives its own
+     * isolated store instance from this function.
      *
-     * For a new run (`prepare`), the factory should return an empty store.
+     * For a new run (`prepare`), the function 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).
+     *
+     * The returned store is owned by the run, not by PipelineFactory.
      */
     storeFactory: (runId: string) => Promise<DataStore<S>>;
     /**
@@ -1558,37 +1581,68 @@ interface PipelineEngineOptions<S extends object = State> {
      * If omitted, the store remains empty.
      */
     initialStateFactory?: () => S;
+    /**
+     * Optional registry to register every RunContext with after construction.
+     * When provided, prepare() and resume() call registry.register() before
+     * returning, passing both the RunContext and the run's DataStore so the
+     * registry can drive deferred export without needing a reference to the factory.
+     */
+    registry?: PipelineRegistryBinding<S>;
 }
 /**
- * The entry point for creating and resuming pipeline runs.
+ * Narrow interface the factory uses to register runs with the registry.
+ * Typed as an interface rather than the full PipelineRegistry class so that
+ * the factory remains decoupled from the registry's full surface.
+ */
+interface PipelineRegistryBinding<S extends object> {
+    has(id: string): boolean;
+    register(context: RunContext<S>, store: DataStore<S>): void;
+    /**
+     * Called by resume() before constructing a new RunContext.
+     * Returns the existing live RunContext if the registry still holds a strong
+     * reference for this runId (i.e. the pause timeout has not yet fired).
+     * Returns null if no live context exists and reconstruction is needed.
+     */
+    getLiveContext(runId: string): RunContext<S> | null;
+    /** Returns the checkpoint for a paused run, if available. */
+    getCheckpoint(runId: string): PipelineCheckpoint | null;
+}
+/**
+ * A pure factory for creating and resuming pipeline runs.
+ *
+ * PipelineFactory is stateless between runs. It holds only the pipeline
+ * definition (topology), a storeFactory function, and an optional logger and
+ * registry binding. It does not own any DataStore, timer, or live run state.
  *
  * @typeParam S - The shape of the state object.
  *
  * @example
  * ```ts
- * const engine = new PipelineEngine(myDefinition, {
+ * const factory = new PipelineFactory(myDefinition, {
  *   storeFactory: (runId) => createMyStore(runId),
  *   initialStateFactory: () => ({ counter: 0 }),
+ *   registry: PipelineRegistry.default,
  * });
  *
- * const ctx = await engine.prepare({ stage: "validate" });
+ * const ctx = await factory.prepare({ stage: "validate" });
  * ctx.on("pipeline:success", (e) => console.log("done", e.finalState));
  * const result = await ctx.run();
  * ```
  */
-declare class PipelineEngine<S extends object> {
+declare class PipelineFactory<S extends object> {
     private readonly definition;
     private readonly logger;
     private readonly storeFactory;
     private readonly initialStateFactory;
+    private readonly registry;
     private readonly index;
     /**
-     * Constructs an engine tied to a fixed pipeline definition.
+     * Constructs a factory tied to a fixed pipeline definition.
      *
      * @param definition - The pipeline topology (stages, steps, routers).
-     * @param options    - Engine configuration. `storeFactory` is mandatory.
+     * @param options    - Factory configuration. `storeFactory` is mandatory.
      */
-    constructor(definition: RoutingPipelineDefinition<S>, options: PipelineEngineOptions<S>);
+    constructor(definition: RoutingPipelineDefinition<S>, options: PipelineFactoryOptions<S>);
     /**
      * Prepare an isolated {@link RunContext} for a **new** run.
      *
@@ -1596,6 +1650,9 @@ declare class PipelineEngine<S extends object> {
      * initial state from `initialStateFactory`. No execution occurs until
      * `runContext.run()` is called.
      *
+     * If a registry is configured, the context and store are registered before
+     * this method returns.
+     *
      * @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.
@@ -1605,9 +1662,18 @@ declare class PipelineEngine<S extends object> {
     /**
      * 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.
+     * **Fast path (registry hit):** If a registry is configured and still holds
+     * a live strong reference for `runId` (i.e. the pause timeout has not fired),
+     * the existing RunContext is returned directly. No store read, no
+     * ArtifactContainer.from() — zero serialization cost.
+     *
+     * **Slow path (store reconstruction):** If no live context exists (timeout
+     * expired, process restarted, or no registry), the store is read, the
+     * checkpoint is validated, and a fresh RunContext is built from the
+     * containerBundle (if the registry wrote one at expiry) or from scratch.
+     *
+     * The context is registered with the registry before this method returns
+     * (slow path only — the fast path context is already registered).
      *
      * @param runId - The identifier of the paused run.
      * @returns A result containing the `RunContext`, or a failure if no
@@ -1619,7 +1685,7 @@ declare class PipelineEngine<S extends object> {
      *
      * 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.
+     * which is the only reference RunContextImpl holds to the factory.
      *
      * A single {@link ArtifactContainer} is created per run at root level and
      * shared across all sub-pipelines. Steps are registered under namespaced keys
@@ -1630,16 +1696,330 @@ declare class PipelineEngine<S extends object> {
      * 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.
+     * @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.
+     * @param artifactBundle - Optional exported container state for store-based resume.
      */
     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, artifactBundle?: ExportedContainerState): Promise<RunContext<S>>;
 }
+/**
+ * Writes a checkpoint into the store using the typed EngineStoreEnvelope.
+ * The write is synchronous from the store's perspective (the transaction
+ * boundary lives in the caller). No `any` cast is required because
+ * EngineStoreEnvelope fully types the factory-internal key namespace.
+ *
+ * Exported so the PipelineRegistry can update an existing checkpoint with a
+ * containerBundle at timeout expiry without duplicating the write logic.
+ */
+declare function writeCheckpoint(store: DataStore<any>, checkpoint: PipelineCheckpoint): Promise<void>;
+/**
+ * Reads a checkpoint from the store using the typed EngineStoreEnvelope.
+ * Returns null if no checkpoint exists for the given pipelineId / runId pair.
+ * Synchronous — the store's get() is a synchronous snapshot read.
+ */
+declare function readCheckpoint(store: DataStore<any>, pipelineId: string | undefined, runId: string): PipelineCheckpoint | null;
+/**
+ * Removes a checkpoint from the store.
+ * Called by the registry when a paused run expires and no resume arrived,
+ * after the containerBundle (if any) has been written into the checkpoint.
+ * Exported so the registry can clear stale checkpoints without reaching into
+ * the factory's internals.
+ */
+declare function clearCheckpoint(store: DataStore<any>, pipelineId: string, runId: string): Promise<void>;
+
+/**
+ * @file pipeline-registry.ts
+ * @description Stateful coordination layer for pipeline runs.
+ *
+ * The registry is the single source of truth for live run state. It owns:
+ *
+ *  1. Strong references to RunContext instances — it decides when a context
+ *     becomes GC-eligible by nulling the reference inside its RunRecord.
+ *
+ *  2. Pause timers — armed when a pipeline pauses, cancelled when resume()
+ *     is called before expiry.
+ *
+ *  3. Deferred container export — on timer expiry the registry exports the
+ *     ArtifactContainer and writes the bundle into the persisted checkpoint
+ *     via writeCheckpoint(), then nulls the context reference.
+ *
+ *  4. A WeakRef index — allows external observers to list and watch runs
+ *     without the registry preventing GC of completed or expired records.
+ *
+ *  5. A FinalizationRegistry — passively removes stale WeakRef entries from
+ *     the index after GC collects a context nobody else held.
+ *
+ * GC eligibility rules:
+ *  - Completed runs (succeeded / failed): the registry nulls the strong ref
+ *    immediately on the terminal event. If no external caller holds a reference
+ *    the context is GC-eligible right away.
+ *  - Paused runs: the registry holds the strong ref for `pauseTimeout` ms
+ *    (from the PauseInstruction, or the registry default). During that window
+ *    resume() returns the live context directly — zero reconstruction cost.
+ *    When the timer fires the registry exports, updates the checkpoint, nulls
+ *    the ref, and fires onExpired.
+ *
+ * Named instances:
+ *  PipelineRegistry.default  — module-level singleton, importable from anywhere.
+ *  PipelineRegistry.get(name) — named registries for test isolation or domain
+ *                               separation within the same process.
+ */
+
+/**
+ * The status of a run as tracked by the registry.
+ * Mirrors PipelineRunResult["status"] but adds "running" for in-flight runs.
+ */
+type RunStatus = "prepared" | "running" | "paused" | "succeeded" | "failed";
+/**
+ * A read-only snapshot of a run's metadata, returned by list() and get().
+ *
+ * `context` is the live RunContext if the registry still holds a strong
+ * reference (i.e. the run has not completed/expired). It is null once the
+ * context has been released. Callers who receive a non-null context should
+ * not store it long-term — they will prevent GC if they do.
+ */
+interface RunInfo<S extends object> {
+    readonly runId: string;
+    readonly pipelineId: string;
+    readonly status: RunStatus;
+    readonly startedAt: string;
+    readonly pausedAt: string | undefined;
+    readonly checkpoint: PipelineCheckpoint | undefined;
+    readonly context: RunContext<S> | null;
+}
+/**
+ * Configuration for a {@link PipelineRegistry} instance.
+ */
+interface PipelineRegistryOptions {
+    /**
+     * Default pause timeout in milliseconds.
+     * Used when a PauseInstruction carries no explicit `timeout` field.
+     * Defaults to 5 minutes (300_000 ms).
+     */
+    defaultPauseTimeout?: number;
+    /**
+     * Called when a paused run's timeout fires and the context is about to
+     * be released. Receives the runId and the final checkpoint (which now
+     * includes the containerBundle if export succeeded).
+     *
+     * Use this to notify external systems (e.g. send a "run expired" webhook,
+     * update a database record, schedule a retry).
+     */
+    onExpired?: (runId: string, checkpoint: PipelineCheckpoint) => void;
+    /**
+     * Called when a container export fails at timeout expiry.
+     * The checkpoint is cleared from the store and the context is still
+     * released, but without a containerBundle — a subsequent resume() would
+     * need to rebuild the container from scratch via the factory's slow path.
+     */
+    onExportFailed?: (runId: string, error: unknown) => void;
+    /** Logger. Defaults to console. */
+    logger?: EngineLogger;
+}
+/**
+ * Stateful coordination layer for pipeline runs.
+ *
+ * @typeParam S - The state shape. Use the base `State` type when the registry
+ *               manages runs across multiple pipeline definitions with different
+ *               state shapes (the common case for a module-level singleton).
+ *
+ * @example
+ * ```ts
+ * // Module-level singleton — importable from anywhere
+ * import { PipelineRegistry } from "./pipeline-registry";
+ *
+ * // In your factory setup:
+ * const factory = new PipelineFactory(definition, {
+ *   storeFactory,
+ *   registry: PipelineRegistry.default,
+ * });
+ *
+ * // From anywhere in the app:
+ * const runs = PipelineRegistry.default.list();
+ * const info = PipelineRegistry.default.get(runId);
+ * ```
+ */
+declare class PipelineRegistry<S extends object = State> implements PipelineRegistryBinding<S> {
+    private static readonly instances;
+    /**
+     * The module-level default registry.
+     * Importable from anywhere in the process. Manages runs across all pipeline
+     * factories that reference it.
+     */
+    static readonly default: PipelineRegistry<any>;
+    /**
+     * Returns a named registry, creating it on first access.
+     * Useful for test isolation (each test suite gets its own registry) or
+     * domain separation (one registry per bounded context).
+     *
+     * @param name - A stable identifier for the registry instance.
+     * @param options - Applied only on first creation; ignored on subsequent calls.
+     */
+    static get<S extends object = State>(name: string, options?: PipelineRegistryOptions): PipelineRegistry<S>;
+    /**
+     * Destroys a named registry instance, cancelling all active timers and
+     * releasing all strong references. The instance is removed from the
+     * static map so the next call to get(name) creates a fresh registry.
+     *
+     * Primarily useful in tests.
+     */
+    static destroy(name: string): void;
+    private readonly defaultPauseTimeout;
+    private readonly onExpired;
+    private readonly onExportFailed;
+    private readonly logger;
+    /**
+     * Strong-reference map. The registry is the last strong holder of each
+     * RunContext. Nulling record.context is the moment GC eligibility begins.
+     */
+    private readonly records;
+    /**
+     * Weak-reference index. Allows external callers to observe runs without
+     * the registry preventing GC of completed or expired contexts.
+     * Entries are added in register() and removed either explicitly in
+     * releaseContext() or passively by the FinalizationRegistry callback.
+     */
+    private readonly weakIndex;
+    /**
+     * Passively cleans up stale WeakRef entries after GC collects a context.
+     * The held value is the runId so the callback can remove the correct entry.
+     */
+    private readonly finalizer;
+    constructor(options?: PipelineRegistryOptions);
+    /**
+     * Registers a new RunContext with the registry.
+     *
+     * Called by PipelineFactory.prepare() and PipelineFactory.resume() (slow
+     * path) immediately after constructing a RunContext. The store is passed
+     * here so the registry never needs to reach back into the factory.
+     *
+     * The registry wires pipeline:paused, pipeline:success, and pipeline:failure
+     * listeners onto the context's event bus. These listeners drive all
+     * subsequent state transitions (arming timers, releasing refs, etc.).
+     *
+     * `container` is extracted from the context via the RegistrableRunContext
+     * interface — a narrow extension of RunContext that RunContextImpl satisfies
+     * by exposing its container reference for registry use only.
+     *
+     * @param context - The RunContext to track.
+     * @param store   - The run's DataStore (owned by the run, borrowed by registry).
+     */
+    register(context: RunContext<S>, store: DataStore<S>): void;
+    getCheckpoint(runId: string): PipelineCheckpoint | null;
+    /**
+     * Returns the live RunContext for a paused run if the registry still holds
+     * a strong reference (i.e. the pause timeout has not yet fired).
+     *
+     * Called by PipelineFactory.resume() as the fast path check. If this
+     * returns non-null, the factory skips store reconstruction entirely.
+     *
+     * The timer is cancelled here — the caller (factory) takes responsibility
+     * for the context from this point and will re-register it via register()
+     * after wiring new event listeners.
+     *
+     * @param runId - The run identifier to look up.
+     * @returns The live RunContext, or null if not found / already released.
+     */
+    getLiveContext(runId: string): RunContext<S> | null;
+    /**
+     * Returns a snapshot of all tracked runs regardless of status.
+     * Completed and expired runs remain in the map until explicitly pruned
+     * via prune() or dispose().
+     */
+    list(): RunInfo<S>[];
+    /**
+     * Returns runs matching a given status.
+     *
+     * @param status - Filter by run status.
+     */
+    listByStatus(status: RunStatus): RunInfo<S>[];
+    /**
+     * Checks if a run id is registered
+     * @param runId - The run identifier.
+     */
+    has(runId: string): boolean;
+    /**
+     * Returns the RunInfo for a specific run, or undefined if not tracked.
+     *
+     * @param runId - The run identifier.
+     */
+    get(runId: string): RunInfo<S> | undefined;
+    /**
+     * Removes all terminal runs (succeeded / failed) and expired paused runs
+     * (context already null) from the records map.
+     *
+     * Call periodically or on a schedule to prevent unbounded memory growth in
+     * long-running processes.
+     */
+    prune(): void;
+    /**
+     * Cancels all active timers, releases all strong context references, and
+     * unsubscribes all event listeners.
+     *
+     * Does not clear the records map — call prune() afterward if needed.
+     * After dispose() the registry should not be used further.
+     */
+    dispose(): void;
+    private onRun;
+    private onPaused;
+    private onSucceeded;
+    private onFailed;
+    /**
+     * Runs when the pause timeout fires (or immediately when timeout === 0).
+     *
+     * Sequence:
+     *  1. Export the ArtifactContainer to get the bundle.
+     *  2. Write the bundle into the persisted checkpoint via writeCheckpoint().
+     *  3. Null the strong context reference → GC-eligible.
+     *  4. Call onExpired callback.
+     *
+     * On export failure:
+     *  1. Log the error and call onExportFailed.
+     *  2. Clear the checkpoint from the store entirely (no partial bundle).
+     *  3. Null the strong ref anyway — we cannot hold it indefinitely.
+     *
+     * The store is not closed here — the registry borrowed it from the run;
+     * the storeFactory caller owns its lifecycle.
+     */
+    private runExpirySequence;
+    private cancelTimer;
+    private unwire;
+    /**
+     * Nulls the strong context reference and removes the WeakRef from the index.
+     * After this call the context is GC-eligible if no external holder remains.
+     */
+    private releaseContext;
+}
+/**
+ * A narrow extension of RunContext that RunContextImpl satisfies internally.
+ *
+ * These two fields are the only things the registry needs from the context
+ * beyond the public RunContext interface. They are not part of the public
+ * surface — callers accessing a RunContext never see them. The registry casts
+ * to this interface inside register() to extract them.
+ *
+ * RunContextImpl must be updated to expose these two fields so the registry
+ * can access them. Since RunContextImpl is package-private, this coupling is
+ * contained within the package and does not leak to consumers.
+ */
+interface RegistrableRunContext<S extends object> extends RunContext<S> {
+    /**
+     * The shared ArtifactContainer for this run.
+     * Used by the registry for deferred export at pause timeout.
+     * Tagged with double-underscore to signal it is registry-internal.
+     */
+    readonly __registryContainer: ArtifactContainer<any, S>;
+    /**
+     * The pipeline definition id this run belongs to.
+     * Used by the registry to populate RunRecord.pipelineId.
+     */
+    readonly __registryPipelineId: string;
+}
 
-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 };
+export { type EngineLogger, type EntryAddress, type EventPath, PIPELINE_DATA_KEY, type PathNode, type PauseInstruction, Pipeline, type PipelineCheckpoint, type PipelineContext, type PipelineDefinition, type PipelineEventMap, PipelineFactory, type PipelineFactoryOptions, PipelineRegistry, type PipelineRegistryBinding, type PipelineRegistryOptions, type PipelineRunResult, type PipelineStageRouter, type PipelineStep, type PipelineStepDefinition, type RegistrableRunContext, Result, type RoutingInstruction, type RoutingPipelineDefinition, type RunContext, type RunEventHandler, type RunEventMap, type RunInfo, type RunStatus, SequentialExecutionContext, type Stage, type StageCarry, type State, type Step, type StepStageRouter, type SubPipelineAddress, clearCheckpoint, isPauseInstruction, readCheckpoint, writeCheckpoint };