tubeless 0.2.11 → 0.2.13

package/dist/core/pipeline-steps.d.ts

@@ -1,3 +1,5 @@
+import { type ArtifactLoader, type ArtifactSaver, type ArtifactResult } from "./pipeline-artifacts.js";
+import { type IterationDecision, type IterationState } from "./iteration.js";
 import type { ToMappedChildStepProgressOptions } from "./mapped-child-progress.js";
 import { STEP_NESTED_PIPELINE, STEP_OPTIONS_SCHEMA, STEP_REMOTE } from "./pipeline-step-metadata.js";
 import type { InferSchemaInput, InferSchemaOutput, Pipeline, PipelineExecutionContext, PipelinePlanStep, PipelineRun, PipelineRunControls, PipelineStepContext, RemoteStepAdapter, StandardSchemaV1, StepSkipDecision } from "./pipeline-types.js";
@@ -79,8 +81,11 @@ type ChildPipelineStepDefinitionBase<TParentOptions extends object, TDeps extend
     description?: string;
     dryRun?: "skip";
     controls?: PipelineRunControlsOf<TChildPipeline> | ((inputs: RequiredInputs<TDeps> & OptionalInputs<TOptionalDeps>, context: PipelineExecutionContext<TParentOptions>) => PipelineRunControlsOf<TChildPipeline>);
+} & ([TParentOptions] extends [PipelineOptionsOf<NoInfer<TChildPipeline>>] ? {
+    mapOptions?(inputs: RequiredInputs<TDeps> & OptionalInputs<TOptionalDeps>, context: PipelineExecutionContext<TParentOptions>): PipelineOptionsOf<TChildPipeline>;
+} : {
     mapOptions(inputs: RequiredInputs<TDeps> & OptionalInputs<TOptionalDeps>, context: PipelineExecutionContext<TParentOptions>): PipelineOptionsOf<TChildPipeline>;
-};
+});
 /** Child step without policy skip (dependents see the full child result type). */
 type ChildPipelineStepDefinition<TParentOptions extends object, TDeps extends readonly AnyStep<TParentOptions>[], TOptionalDeps extends readonly AnyStep<TParentOptions>[], TChildPipeline extends Pipeline<object, unknown>> = ChildPipelineStepDefinitionBase<TParentOptions, TDeps, TOptionalDeps, TChildPipeline>;
 /**
@@ -165,6 +170,12 @@ declare function createStepFactory<TOptions extends object, TInputOptions extend
             skip?: never;
         }): TOptionsSchema extends StandardSchemaV1<unknown, unknown> ? Step<TId, TOut, TOptions, TInputOptions, TOut, TOptionsSchema> : Step<TId, TOut, TOptions, TInputOptions, TOut, StandardSchemaV1<unknown, unknown> | undefined>;
     };
+    loadArtifact: <TId extends string, const TDeps extends readonly AnyStep<TOptions>[] = [], const TOptionalDeps extends readonly AnyStep<TOptions>[] = [], TValue = unknown>(id: TId, definition: Omit<PlainStepFields<TOptions, TDeps, TOptionalDeps, ArtifactResult<TValue>>, "run"> & {
+        load: ArtifactLoader<RequiredInputs<TDeps> & OptionalInputs<TOptionalDeps>, TValue, TOptions>;
+    }) => TOptionsSchema extends StandardSchemaV1<unknown, unknown> ? Step<TId, TValue, TOptions, TInputOptions, TValue, TOptionsSchema> : Step<TId, TValue, TOptions, TInputOptions, TValue, StandardSchemaV1<unknown, unknown> | undefined>;
+    saveArtifact: <TId extends string, const TDeps extends readonly AnyStep<TOptions>[] = [], const TOptionalDeps extends readonly AnyStep<TOptions>[] = [], TValue = unknown>(id: TId, definition: Omit<PlainStepFields<TOptions, TDeps, TOptionalDeps, ArtifactResult<TValue>>, "run"> & {
+        save: ArtifactSaver<RequiredInputs<TDeps> & OptionalInputs<TOptionalDeps>, TValue, TOptions>;
+    }) => TOptionsSchema extends StandardSchemaV1<unknown, unknown> ? Step<TId, TValue, TOptions, TInputOptions, TValue, TOptionsSchema> : Step<TId, TValue, TOptions, TInputOptions, TValue, StandardSchemaV1<unknown, unknown> | undefined>;
     fromPipeline: {
         <TId extends string, TChildPipeline extends Pipeline<object, unknown>, const TDeps extends readonly AnyStep<TOptions>[] = [], const TOptionalDeps extends readonly AnyStep<TOptions>[] = []>(id: TId, definition: ChildPipelineStepDefinition<TOptions, TDeps, TOptionalDeps, TChildPipeline> & {
             skip?: never;
@@ -209,5 +220,17 @@ declare function createStepFactory<TOptions extends object, TInputOptions extend
             mapResult(value: PipelineResultOf<TChildPipeline>, result: PipelineRun<PipelineResultOf<TChildPipeline>>, item: TItem, index: number, context: PipelineStepContext<TOptions>): TOut;
         }): TOptionsSchema extends StandardSchemaV1<unknown, unknown> ? Step<TId, PolicySkippedOutput<readonly TOut[], TDecision>, TOptions, TInputOptions, PolicySkippedOutput<readonly TOut[], TDecision>, TOptionsSchema> : Step<TId, PolicySkippedOutput<readonly TOut[], TDecision>, TOptions, TInputOptions, PolicySkippedOutput<readonly TOut[], TDecision>, StandardSchemaV1<unknown, unknown> | undefined>;
     };
+    iteratePipeline: <const TId extends string, TChild extends Pipeline<object, unknown>, TState, TResult, const TDeps extends readonly AnyStep<TOptions>[] = []>(id: TId, definition: {
+        pipeline: TChild;
+        name?: string;
+        description?: string;
+        dependsOn?: TDeps;
+        maxIterations: number;
+        dryRun?: "skip";
+        controls?: PipelineRunControlsOf<TChild>;
+        initialState(inputs: RequiredInputs<TDeps>, context: PipelineExecutionContext<TOptions>): TState;
+        mapOptions(state: IterationState<NoInfer<TState>>, inputs: RequiredInputs<TDeps>, context: PipelineExecutionContext<TOptions>): PipelineOptionsOf<TChild>;
+        transition(result: PipelineResultOf<TChild>, state: IterationState<NoInfer<TState>>, context: PipelineExecutionContext<TOptions>): IterationDecision<NoInfer<TState>, TResult> | Promise<IterationDecision<NoInfer<TState>, TResult>>;
+    }) => TOptionsSchema extends StandardSchemaV1<unknown, unknown> ? Step<TId, Awaited<TResult>, TOptions, TInputOptions, Awaited<TResult>, TOptionsSchema> : Step<TId, Awaited<TResult>, TOptions, TInputOptions, Awaited<TResult>, StandardSchemaV1<unknown, unknown> | undefined>;
 };
 export {};

package/dist/core/pipeline-steps.js

@@ -1,4 +1,6 @@
+import {} from "./pipeline-artifacts.js";
 import { createMappedChildRunner, createSingleChildRunner } from "./child-execution.js";
+import { createIterationRunner } from "./iteration.js";
 import { STEP_NESTED_PIPELINE, STEP_OPTIONS_SCHEMA, STEP_REMOTE, } from "./pipeline-step-metadata.js";
 export function createSteps(optionsSchema) {
     return createStepFactory(optionsSchema);
@@ -14,6 +16,34 @@ function createStepFactory(optionsSchema) {
     function step(id, definition) {
         return buildStep(id, definition);
     }
+    /** Read an artifact as an ordinary step, publishing only its typed value. */
+    function loadArtifact(id, definition) {
+        const { load, dryRun, ...fields } = definition;
+        const wrap = (handler) => async (inputs, context) => {
+            const loaded = await handler(inputs, context);
+            context.recordArtifact({ operation: "read", artifact: loaded.artifact });
+            return loaded.value;
+        };
+        return step(id, {
+            ...fields,
+            run: wrap(load),
+            dryRun: typeof dryRun === "function" ? wrap(dryRun) : dryRun,
+        });
+    }
+    /** Write an artifact as an ordinary step. Dry runs skip unless a preview is supplied. */
+    function saveArtifact(id, definition) {
+        const { save, dryRun, ...fields } = definition;
+        const wrap = (handler) => async (inputs, context) => {
+            const saved = await handler(inputs, context);
+            context.recordArtifact({ operation: "write", artifact: saved.artifact });
+            return saved.value;
+        };
+        return step(id, {
+            ...fields,
+            run: wrap(save),
+            dryRun: typeof dryRun === "function" ? wrap(dryRun) : "skip",
+        });
+    }
     const buildPipelineStep = (id, config) => {
         const definition = {
             [STEP_NESTED_PIPELINE]: {
@@ -89,11 +119,43 @@ function createStepFactory(optionsSchema) {
     function forEachPipeline(id, definition) {
         return buildMappedPipelineStep(id, definition);
     }
+    function iteratePipeline(id, definition) {
+        if (!Number.isSafeInteger(definition.maxIterations) || definition.maxIterations < 1) {
+            throw new RangeError("iteratePipeline maxIterations must be a positive safe integer");
+        }
+        const controls = definition.controls ? structuredClone(definition.controls) : undefined;
+        if (controls) {
+            if (controls.targets)
+                Object.freeze(controls.targets);
+            if (controls.stepIds)
+                Object.freeze(controls.stepIds);
+            Object.freeze(controls);
+        }
+        const config = { ...definition, stepId: id, controls };
+        return buildStep(id, {
+            [STEP_NESTED_PIPELINE]: {
+                mode: "iterate",
+                maxIterations: config.maxIterations,
+                controls: config.controls,
+                pipelineId: config.pipeline.id,
+                identity: config.pipeline.definition?.identity,
+                stepIds: config.pipeline.stepIds,
+            },
+            name: config.name,
+            description: config.description,
+            dependsOn: config.dependsOn,
+            dryRun: config.dryRun,
+            run: createIterationRunner(config),
+        });
+    }
     const factory = {
         step,
+        loadArtifact,
+        saveArtifact,
         fromPipeline,
         fromRemote,
         forEachPipeline,
+        iteratePipeline,
     };
     return factory;
 }

package/dist/core/pipeline-steps.js.map

@@ -1 +1 @@
-{"version":3,"file":"pipeline-steps.js","sourceRoot":"","sources":["../../src/core/pipeline-steps.ts"],"names":[],"mappings":"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","sourcesContent":["import { createMappedChildRunner, createSingleChildRunner } from \"./child-execution.js\";\nimport type { ToMappedChildStepProgressOptions } from \"./mapped-child-progress.js\";\nimport {\n  STEP_NESTED_PIPELINE,\n  STEP_OPTIONS_SCHEMA,\n  STEP_REMOTE,\n} from \"./pipeline-step-metadata.js\";\nimport type {\n  InferSchemaInput,\n  InferSchemaOutput,\n  Pipeline,\n  PipelineExecutionContext,\n  PipelinePlanStep,\n  PipelineRun,\n  PipelineRunControls,\n  PipelineStepContext,\n  RemoteStepAdapter,\n  StandardSchemaV1,\n  StepSkipDecision,\n} from \"./pipeline-types.js\";\n\n/**\n * A step's dependencies are references to the dependency's own step object, not string ids\n * into a hand-maintained output-type map. This buys two things no amount of extra generics\n * on a string-keyed design could:\n *  - a step used before its dependency exists is a compile error (JS temporal dead zone on\n *    `const`), so out-of-order and self/cyclic dependencies are caught by the language, not\n *    a bespoke runtime check\n *  - each step only ever states its own id/deps; the output-type map is derived, never\n *    restated, and callers of `definePipeline`/`createSteps` never write out its generics\n */\ntype AnyStepDryRunHandler<TOptions extends object> = {\n  bivarianceHack(\n    inputs: Record<string, unknown>,\n    context: PipelineStepContext<TOptions>\n  ): unknown | Promise<unknown>;\n}[\"bivarianceHack\"];\n\n/** Runtime shape shared by every declared pipeline step. */\nexport interface AnyStep<TOptions extends object = object> {\n  readonly [STEP_NESTED_PIPELINE]?: NonNullable<PipelinePlanStep[\"nestedPipeline\"]>;\n  readonly [STEP_REMOTE]?: NonNullable<PipelinePlanStep[\"remote\"]>;\n  readonly [STEP_OPTIONS_SCHEMA]?: StandardSchemaV1;\n  readonly id: string;\n  readonly dependsOn?: readonly AnyStep<TOptions>[];\n  readonly optionalDependsOn?: readonly AnyStep<TOptions>[];\n  readonly skipAfterFailureOf?: readonly AnyStep<TOptions>[];\n  /** Optional human-facing display name. Stable machine identity remains `id`. */\n  readonly name?: string;\n  readonly description?: string;\n  /**\n   * Dry-run policy. Omitted runs the normal handler, `\"skip\"` structurally\n   * skips it, and a handler substitutes for `run` while preserving its output.\n   */\n  readonly dryRun?: \"skip\" | AnyStepDryRunHandler<TOptions>;\n  /** Optional Standard Schema for values published by this step. */\n  readonly outputSchema?: StandardSchemaV1;\n  /**\n   * Optional runtime skip. Return a non-empty reason (or `{ reason, value }`) to\n   * skip without calling `run`. Policy skips unlock dependents; structural skips\n   * (dry-run, filtered, …) do not use this hook.\n   */\n  skip?(\n    inputs: Record<string, unknown>,\n    context: PipelineExecutionContext<TOptions>\n  ): StepSkipDecision | Promise<StepSkipDecision>;\n  run(inputs: Record<string, unknown>, context: PipelineStepContext<TOptions>): unknown;\n}\n\n/** The step fields that `buildStep` merges onto the id-bearing shell. */\ntype StepDefinitionBody<TOptions extends object> = Omit<AnyStep<TOptions>, \"id\">;\n\n/** Typed pipeline step carrying its stable ID, output, and option types. */\nexport interface Step<\n  TId extends string,\n  TOut,\n  TOptions extends object,\n  TInputOptions extends object = TOptions,\n  TRunOut = TOut,\n  TOptionsSchema extends StandardSchemaV1 | undefined = StandardSchemaV1 | undefined,\n> extends AnyStep<TOptions> {\n  readonly [STEP_OPTIONS_SCHEMA]?: TOptionsSchema;\n  readonly id: TId;\n  run(\n    inputs: Record<string, unknown>,\n    context: PipelineStepContext<TOptions>\n  ): TRunOut | Promise<TRunOut>;\n  /** Type-only: carries this step's output type for sibling inference. Never set at runtime. */\n  readonly __outputType?: TOut;\n  /** Type-only: carries pre-validation run options for pipeline call-site inference. */\n  readonly __inputOptionsType?: TInputOptions;\n}\n\n/**\n * Extract a step's output type for dependency typing.\n * Prefer matching `Step<…, TOut, …>` over `{ __outputType?: infer T }`: optional-property\n * inference collapses `TOut | undefined` to `TOut`, which hides policy-skip widening.\n */\nexport type StepOutput<S> =\n  S extends Step<string, infer TOut, infer _TOptions, infer _TInputOptions, infer _TRunOut>\n    ? TOut\n    : never;\n\ninterface StepToken {\n  readonly id: string;\n  readonly __outputType?: unknown;\n}\n\ntype RequiredInputs<TDeps extends readonly StepToken[]> = {\n  [S in TDeps[number] as S[\"id\"]]: StepOutput<S>;\n};\n\ntype OptionalInputs<TDeps extends readonly StepToken[]> = {\n  [S in TDeps[number] as S[\"id\"]]?: StepOutput<S>;\n};\n\ntype PipelineResultOf<TPipeline> =\n  TPipeline extends Pipeline<object, infer TResult, infer _TStepId, infer _TTargetId>\n    ? TResult\n    : never;\n\ntype PipelineOptionsOf<TPipeline> =\n  TPipeline extends Pipeline<infer TOptions, unknown, infer _TStepId, infer _TTargetId>\n    ? TOptions\n    : never;\n\ntype PipelineRunControlsOf<TPipeline> =\n  TPipeline extends Pipeline<infer _TOptions, unknown, infer TStepId, infer TTargetId>\n    ? PipelineRunControls<TStepId, TTargetId>\n    : never;\n\ntype ChildPipelineStepDefinitionBase<\n  TParentOptions extends object,\n  TDeps extends readonly AnyStep<TParentOptions>[],\n  TOptionalDeps extends readonly AnyStep<TParentOptions>[],\n  TChildPipeline extends Pipeline<object, unknown>,\n> = {\n  pipeline: TChildPipeline;\n  dependsOn?: TDeps;\n  optionalDependsOn?: TOptionalDeps;\n  skipAfterFailureOf?: readonly AnyStep<TParentOptions>[];\n  name?: string;\n  description?: string;\n  dryRun?: \"skip\";\n  controls?:\n    | PipelineRunControlsOf<TChildPipeline>\n    | ((\n        inputs: RequiredInputs<TDeps> & OptionalInputs<TOptionalDeps>,\n        context: PipelineExecutionContext<TParentOptions>\n      ) => PipelineRunControlsOf<TChildPipeline>);\n  mapOptions(\n    inputs: RequiredInputs<TDeps> & OptionalInputs<TOptionalDeps>,\n    context: PipelineExecutionContext<TParentOptions>\n  ): PipelineOptionsOf<TChildPipeline>;\n};\n\n/** Child step without policy skip (dependents see the full child result type). */\ntype ChildPipelineStepDefinition<\n  TParentOptions extends object,\n  TDeps extends readonly AnyStep<TParentOptions>[],\n  TOptionalDeps extends readonly AnyStep<TParentOptions>[],\n  TChildPipeline extends Pipeline<object, unknown>,\n> = ChildPipelineStepDefinitionBase<TParentOptions, TDeps, TOptionalDeps, TChildPipeline>;\n\n/**\n * Presentation options for opaque `forEachPipeline` progress.\n * Defaults are domain-neutral (`N/M items · K running · key/step`).\n * Override `formatMessage` when a domain wants its own noun (images, shards, …).\n */\nexport type MappedChildProgressOptions = ToMappedChildStepProgressOptions;\n\ntype MappedChildPipelineStepDefinition<\n  TParentOptions extends object,\n  TDeps extends readonly AnyStep<TParentOptions>[],\n  TOptionalDeps extends readonly AnyStep<TParentOptions>[],\n  TChildPipeline extends Pipeline<object, unknown>,\n  TItem,\n> = {\n  pipeline: TChildPipeline;\n  dependsOn?: TDeps;\n  optionalDependsOn?: TOptionalDeps;\n  skipAfterFailureOf?: readonly AnyStep<TParentOptions>[];\n  name?: string;\n  description?: string;\n  dryRun?: \"skip\";\n  items(\n    inputs: RequiredInputs<TDeps> & OptionalInputs<TOptionalDeps>,\n    context: PipelineExecutionContext<TParentOptions>\n  ): readonly TItem[] | Promise<readonly TItem[]>;\n  key(item: TItem, index: number): string;\n  concurrency?:\n    | number\n    | ((\n        inputs: RequiredInputs<TDeps> & OptionalInputs<TOptionalDeps>,\n        context: PipelineExecutionContext<TParentOptions>\n      ) => number);\n  /**\n   * How the opaque parent step reports live fan-out progress.\n   * Purely presentational — does not change scheduling or results.\n   */\n  progress?: MappedChildProgressOptions;\n  controls?:\n    | PipelineRunControlsOf<TChildPipeline>\n    | ((\n        item: TItem,\n        index: number,\n        inputs: RequiredInputs<TDeps> & OptionalInputs<TOptionalDeps>,\n        context: PipelineExecutionContext<TParentOptions>\n      ) => PipelineRunControlsOf<TChildPipeline>);\n  mapOptions(\n    item: TItem,\n    index: number,\n    inputs: RequiredInputs<TDeps> & OptionalInputs<TOptionalDeps>,\n    context: PipelineExecutionContext<TParentOptions>\n  ): PipelineOptionsOf<TChildPipeline>;\n};\n\ntype StepSkipPredicate<\n  TOptions extends object,\n  TDeps extends readonly AnyStep<TOptions>[],\n  TOptionalDeps extends readonly AnyStep<TOptions>[],\n  TOut,\n  TDecision extends StepSkipDecision<TOut> = StepSkipDecision<TOut>,\n> = (\n  inputs: RequiredInputs<TDeps> & OptionalInputs<TOptionalDeps>,\n  context: PipelineExecutionContext<TOptions>\n) => TDecision | Promise<TDecision>;\n\ntype PolicySkippedOutput<TOut, TDecision> = [\n  Exclude<Awaited<TDecision>, false | null | undefined>,\n] extends [{ reason: string; value: unknown }]\n  ? TOut\n  : TOut | undefined;\n\ntype StepDryRunPolicy<\n  TOptions extends object,\n  TDeps extends readonly AnyStep<TOptions>[],\n  TOptionalDeps extends readonly AnyStep<TOptions>[],\n  TOut,\n> =\n  | \"skip\"\n  | ((\n      inputs: RequiredInputs<TDeps> & OptionalInputs<TOptionalDeps>,\n      context: PipelineStepContext<TOptions>\n    ) => TOut | Promise<TOut>);\n\ntype PlainStepFields<\n  TOptions extends object,\n  TDeps extends readonly AnyStep<TOptions>[],\n  TOptionalDeps extends readonly AnyStep<TOptions>[],\n  TOut,\n> = {\n  dependsOn?: TDeps;\n  optionalDependsOn?: TOptionalDeps;\n  skipAfterFailureOf?: readonly AnyStep<TOptions>[];\n  name?: string;\n  description?: string;\n  dryRun?: StepDryRunPolicy<TOptions, TDeps, TOptionalDeps, TOut>;\n  outputSchema?: never;\n  run(\n    inputs: RequiredInputs<TDeps> & OptionalInputs<TOptionalDeps>,\n    context: PipelineStepContext<TOptions>\n  ): TOut | Promise<TOut>;\n};\n\ntype SchemaStepFields<\n  TOptions extends object,\n  TDeps extends readonly AnyStep<TOptions>[],\n  TOptionalDeps extends readonly AnyStep<TOptions>[],\n  TSchema extends StandardSchemaV1,\n> = Omit<\n  PlainStepFields<TOptions, TDeps, TOptionalDeps, InferSchemaInput<TSchema>>,\n  \"outputSchema\"\n> & {\n  outputSchema: TSchema;\n};\n\ntype RemoteStepDefinitionBase<\n  TParentOptions extends object,\n  TDeps extends readonly AnyStep<TParentOptions>[],\n  TOptionalDeps extends readonly AnyStep<TParentOptions>[],\n  TPayload,\n  TSchema extends StandardSchemaV1,\n> = {\n  adapter: RemoteStepAdapter<TParentOptions, TPayload, InferSchemaInput<TSchema>>;\n  mapInput(\n    inputs: RequiredInputs<TDeps> & OptionalInputs<TOptionalDeps>,\n    context: PipelineStepContext<TParentOptions>\n  ): TPayload;\n  outputSchema: TSchema;\n  dependsOn?: TDeps;\n  optionalDependsOn?: TOptionalDeps;\n  skipAfterFailureOf?: readonly AnyStep<TParentOptions>[];\n  name?: string;\n  description?: string;\n  dryRun?: StepDryRunPolicy<TParentOptions, TDeps, TOptionalDeps, InferSchemaInput<TSchema>>;\n};\n\n/** Step constructors scoped to one pipeline's domain option types. */\ntype StepFactory<\n  TOptions extends object,\n  TInputOptions extends object = TOptions,\n  TOptionsSchema extends StandardSchemaV1 | undefined = undefined,\n> = ReturnType<typeof createStepFactory<TOptions, TInputOptions, TOptionsSchema>>;\n\n/**\n * Create typed step constructors for one pipeline definition.\n * Returns a step factory scoped to one pipeline's domain options. Pass built-in\n * run controls as the second argument to `run` / `runOrThrow`, or through a\n * child step's separate `controls` field.\n */\nexport function createSteps<TOptions extends object = {}>(): StepFactory<TOptions>;\nexport function createSteps<const TSchema extends StandardSchemaV1<object, object> | undefined>(\n  optionsSchema: TSchema\n): StepFactory<\n  TSchema extends StandardSchemaV1 ? InferSchemaOutput<TSchema> : object,\n  TSchema extends StandardSchemaV1 ? InferSchemaInput<TSchema> : object,\n  TSchema\n>;\nexport function createSteps(\n  optionsSchema?: StandardSchemaV1<object, object>\n): StepFactory<object, object, StandardSchemaV1 | undefined> {\n  return createStepFactory<object, object, StandardSchemaV1 | undefined>(optionsSchema);\n}\n\nfunction createStepFactory<\n  TOptions extends object,\n  TInputOptions extends object = TOptions,\n  TOptionsSchema extends StandardSchemaV1 | undefined = undefined,\n>(optionsSchema?: TOptionsSchema) {\n  // Preserve the runtime schema in the step type so adapters cannot infer flags\n  // from erased TypeScript-only options.\n  type BuiltStep<\n    TId extends string,\n    TOut,\n    TStepOptions extends object,\n    TInput extends object,\n    TRunOut = TOut,\n  > = TOptionsSchema extends StandardSchemaV1\n    ? Step<TId, TOut, TStepOptions, TInput, TRunOut, TOptionsSchema>\n    : Step<TId, TOut, TStepOptions, TInput, TRunOut>;\n  const buildStep = (id: string, definition: StepDefinitionBody<TOptions>): AnyStep<TOptions> => {\n    const built: AnyStep<TOptions> = { id, ...definition };\n    if (optionsSchema) {\n      Object.defineProperty(built, STEP_OPTIONS_SCHEMA, { value: optionsSchema });\n    }\n    return built;\n  };\n\n  function step<\n    TId extends string,\n    TSchema extends StandardSchemaV1,\n    const TDeps extends readonly AnyStep<TOptions>[] = [],\n    const TOptionalDeps extends readonly AnyStep<TOptions>[] = [],\n    TDecision extends StepSkipDecision<InferSchemaInput<TSchema>> = StepSkipDecision<\n      InferSchemaInput<TSchema>\n    >,\n  >(\n    id: TId,\n    definition: SchemaStepFields<TOptions, TDeps, TOptionalDeps, TSchema> & {\n      skip:\n        | StepSkipPredicate<TOptions, TDeps, TOptionalDeps, InferSchemaInput<TSchema>, TDecision>\n        | undefined;\n    }\n  ): BuiltStep<\n    TId,\n    PolicySkippedOutput<InferSchemaOutput<TSchema>, TDecision>,\n    TOptions,\n    TInputOptions,\n    InferSchemaInput<TSchema>\n  >;\n  function step<\n    TId extends string,\n    const TDeps extends readonly AnyStep<TOptions>[] = [],\n    const TOptionalDeps extends readonly AnyStep<TOptions>[] = [],\n    TOut = unknown,\n    TDecision extends StepSkipDecision<NoInfer<TOut>> = StepSkipDecision<NoInfer<TOut>>,\n  >(\n    id: TId,\n    definition: PlainStepFields<TOptions, TDeps, TOptionalDeps, TOut> & {\n      skip: StepSkipPredicate<TOptions, TDeps, TOptionalDeps, NoInfer<TOut>, TDecision> | undefined;\n    }\n  ): BuiltStep<TId, PolicySkippedOutput<TOut, TDecision>, TOptions, TInputOptions>;\n  function step<\n    TId extends string,\n    TSchema extends StandardSchemaV1,\n    const TDeps extends readonly AnyStep<TOptions>[] = [],\n    const TOptionalDeps extends readonly AnyStep<TOptions>[] = [],\n  >(\n    id: TId,\n    definition: SchemaStepFields<TOptions, TDeps, TOptionalDeps, TSchema> & { skip?: never }\n  ): BuiltStep<TId, InferSchemaOutput<TSchema>, TOptions, TInputOptions, InferSchemaInput<TSchema>>;\n  function step<\n    TId extends string,\n    const TDeps extends readonly AnyStep<TOptions>[] = [],\n    const TOptionalDeps extends readonly AnyStep<TOptions>[] = [],\n    TOut = unknown,\n  >(\n    id: TId,\n    definition: PlainStepFields<TOptions, TDeps, TOptionalDeps, TOut> & { skip?: never }\n  ): BuiltStep<TId, TOut, TOptions, TInputOptions>;\n  function step(id: string, definition: StepDefinitionBody<TOptions>): AnyStep<TOptions> {\n    return buildStep(id, definition);\n  }\n\n  const buildPipelineStep = (\n    id: string,\n    config: ChildPipelineStepDefinitionBase<\n      TOptions,\n      readonly AnyStep<TOptions>[],\n      readonly AnyStep<TOptions>[],\n      Pipeline<object, unknown>\n    > & {\n      skip?: StepSkipPredicate<\n        TOptions,\n        readonly AnyStep<TOptions>[],\n        readonly AnyStep<TOptions>[],\n        unknown\n      >;\n      mapResult?: (\n        value: unknown,\n        result: PipelineRun<unknown>,\n        context: PipelineStepContext<TOptions>\n      ) => unknown;\n    }\n  ) => {\n    const definition: StepDefinitionBody<TOptions> = {\n      [STEP_NESTED_PIPELINE]: {\n        mode: \"single\" as const,\n        pipelineId: config.pipeline.id,\n        identity: config.pipeline.definition?.identity,\n        stepIds: config.pipeline.stepIds,\n      },\n      dependsOn: config.dependsOn,\n      optionalDependsOn: config.optionalDependsOn,\n      skipAfterFailureOf: config.skipAfterFailureOf,\n      name: config.name,\n      description: config.description,\n      dryRun: config.dryRun,\n      run: createSingleChildRunner(config),\n    };\n\n    const skip = config.skip;\n    if (skip !== undefined) {\n      definition.skip = skip;\n    }\n    return buildStep(id, definition);\n  };\n\n  function fromPipeline<\n    TId extends string,\n    TChildPipeline extends Pipeline<object, unknown>,\n    const TDeps extends readonly AnyStep<TOptions>[] = [],\n    const TOptionalDeps extends readonly AnyStep<TOptions>[] = [],\n  >(\n    id: TId,\n    definition: ChildPipelineStepDefinition<TOptions, TDeps, TOptionalDeps, TChildPipeline> & {\n      skip?: never;\n      mapResult?: undefined;\n    }\n  ): BuiltStep<TId, PipelineResultOf<TChildPipeline>, TOptions, TInputOptions>;\n  function fromPipeline<\n    TId extends string,\n    TChildPipeline extends Pipeline<object, unknown>,\n    TOut,\n    const TDeps extends readonly AnyStep<TOptions>[] = [],\n    const TOptionalDeps extends readonly AnyStep<TOptions>[] = [],\n  >(\n    id: TId,\n    definition: ChildPipelineStepDefinitionBase<TOptions, TDeps, TOptionalDeps, TChildPipeline> & {\n      skip?: never;\n      mapResult(\n        value: PipelineResultOf<TChildPipeline>,\n        result: PipelineRun<PipelineResultOf<TChildPipeline>>,\n        context: PipelineStepContext<TOptions>\n      ): TOut;\n    }\n  ): BuiltStep<TId, Awaited<TOut>, TOptions, TInputOptions>;\n  function fromPipeline<\n    TId extends string,\n    TChildPipeline extends Pipeline<object, unknown>,\n    const TDeps extends readonly AnyStep<TOptions>[] = [],\n    const TOptionalDeps extends readonly AnyStep<TOptions>[] = [],\n    TDecision extends StepSkipDecision<PipelineResultOf<TChildPipeline>> = StepSkipDecision<\n      PipelineResultOf<TChildPipeline>\n    >,\n  >(\n    id: TId,\n    definition: ChildPipelineStepDefinitionBase<TOptions, TDeps, TOptionalDeps, TChildPipeline> & {\n      skip:\n        | StepSkipPredicate<\n            TOptions,\n            TDeps,\n            TOptionalDeps,\n            PipelineResultOf<TChildPipeline>,\n            TDecision\n          >\n        | undefined;\n      mapResult?: undefined;\n    }\n  ): BuiltStep<\n    TId,\n    PolicySkippedOutput<PipelineResultOf<TChildPipeline>, TDecision>,\n    TOptions,\n    TInputOptions\n  >;\n  function fromPipeline<\n    TId extends string,\n    TChildPipeline extends Pipeline<object, unknown>,\n    TOut,\n    const TDeps extends readonly AnyStep<TOptions>[] = [],\n    const TOptionalDeps extends readonly AnyStep<TOptions>[] = [],\n    TDecision extends StepSkipDecision<NoInfer<Awaited<TOut>>> = StepSkipDecision<\n      NoInfer<Awaited<TOut>>\n    >,\n  >(\n    id: TId,\n    definition: ChildPipelineStepDefinitionBase<TOptions, TDeps, TOptionalDeps, TChildPipeline> & {\n      skip:\n        | StepSkipPredicate<TOptions, TDeps, TOptionalDeps, NoInfer<Awaited<TOut>>, TDecision>\n        | undefined;\n      mapResult(\n        value: PipelineResultOf<TChildPipeline>,\n        result: PipelineRun<PipelineResultOf<TChildPipeline>>,\n        context: PipelineStepContext<TOptions>\n      ): TOut;\n    }\n  ): BuiltStep<TId, PolicySkippedOutput<Awaited<TOut>, TDecision>, TOptions, TInputOptions>;\n  function fromPipeline(\n    id: string,\n    definition: Parameters<typeof buildPipelineStep>[1]\n  ): AnyStep<TOptions> {\n    return buildPipelineStep(id, definition);\n  }\n\n  const buildRemoteStep = (\n    id: string,\n    config: {\n      adapter: RemoteStepAdapter<object, unknown, unknown>;\n      mapInput(inputs: Record<string, unknown>, context: PipelineStepContext<TOptions>): unknown;\n      outputSchema: StandardSchemaV1;\n      dependsOn?: readonly AnyStep<TOptions>[];\n      optionalDependsOn?: readonly AnyStep<TOptions>[];\n      skipAfterFailureOf?: readonly AnyStep<TOptions>[];\n      name?: string;\n      description?: string;\n      dryRun?: \"skip\" | AnyStepDryRunHandler<TOptions>;\n      skip?: StepSkipPredicate<\n        TOptions,\n        readonly AnyStep<TOptions>[],\n        readonly AnyStep<TOptions>[],\n        unknown\n      >;\n    }\n  ) => {\n    const remote: NonNullable<PipelinePlanStep[\"remote\"]> = { engine: config.adapter.engine };\n    if (config.adapter.target !== undefined) remote.target = config.adapter.target;\n    const definition: StepDefinitionBody<TOptions> = {\n      [STEP_REMOTE]: remote,\n      dependsOn: config.dependsOn,\n      optionalDependsOn: config.optionalDependsOn,\n      skipAfterFailureOf: config.skipAfterFailureOf,\n      name: config.name,\n      description: config.description,\n      dryRun: config.dryRun,\n      outputSchema: config.outputSchema,\n      run: (inputs: Record<string, unknown>, context: PipelineStepContext<TOptions>) =>\n        config.adapter.invoke(config.mapInput(inputs, context), context),\n    };\n    const skip = config.skip;\n    if (skip !== undefined) {\n      definition.skip = skip;\n    }\n    return buildStep(id, definition);\n  };\n\n  function fromRemote<\n    TId extends string,\n    TSchema extends StandardSchemaV1,\n    TPayload,\n    const TDeps extends readonly AnyStep<TOptions>[] = [],\n    const TOptionalDeps extends readonly AnyStep<TOptions>[] = [],\n  >(\n    id: TId,\n    definition: RemoteStepDefinitionBase<TOptions, TDeps, TOptionalDeps, TPayload, TSchema> & {\n      skip?: never;\n    }\n  ): BuiltStep<TId, InferSchemaOutput<TSchema>, TOptions, TInputOptions, InferSchemaInput<TSchema>>;\n  function fromRemote<\n    TId extends string,\n    TSchema extends StandardSchemaV1,\n    TPayload,\n    const TDeps extends readonly AnyStep<TOptions>[] = [],\n    const TOptionalDeps extends readonly AnyStep<TOptions>[] = [],\n    TDecision extends StepSkipDecision<InferSchemaInput<TSchema>> = StepSkipDecision<\n      InferSchemaInput<TSchema>\n    >,\n  >(\n    id: TId,\n    definition: RemoteStepDefinitionBase<TOptions, TDeps, TOptionalDeps, TPayload, TSchema> & {\n      skip:\n        | StepSkipPredicate<TOptions, TDeps, TOptionalDeps, InferSchemaInput<TSchema>, TDecision>\n        | undefined;\n    }\n  ): BuiltStep<\n    TId,\n    PolicySkippedOutput<InferSchemaOutput<TSchema>, TDecision>,\n    TOptions,\n    TInputOptions,\n    InferSchemaInput<TSchema>\n  >;\n  function fromRemote(\n    id: string,\n    definition: Parameters<typeof buildRemoteStep>[1]\n  ): AnyStep<TOptions> {\n    return buildRemoteStep(id, definition);\n  }\n\n  const buildMappedPipelineStep = (\n    id: string,\n    config: MappedChildPipelineStepDefinition<\n      TOptions,\n      readonly AnyStep<TOptions>[],\n      readonly AnyStep<TOptions>[],\n      Pipeline<object, unknown>,\n      unknown\n    > & {\n      mapResult?: (\n        value: unknown,\n        result: PipelineRun<unknown>,\n        item: unknown,\n        index: number,\n        context: PipelineStepContext<TOptions>\n      ) => unknown;\n      skip?: StepSkipPredicate<\n        TOptions,\n        readonly AnyStep<TOptions>[],\n        readonly AnyStep<TOptions>[],\n        unknown\n      >;\n    }\n  ) => {\n    const definition: StepDefinitionBody<TOptions> = {\n      [STEP_NESTED_PIPELINE]: {\n        mode: \"for-each\" as const,\n        concurrency:\n          typeof config.concurrency === \"function\" ? \"dynamic\" : (config.concurrency ?? 1),\n        pipelineId: config.pipeline.id,\n        identity: config.pipeline.definition?.identity,\n        stepIds: config.pipeline.stepIds,\n      },\n      dependsOn: config.dependsOn,\n      optionalDependsOn: config.optionalDependsOn,\n      skipAfterFailureOf: config.skipAfterFailureOf,\n      name: config.name,\n      description: config.description,\n      dryRun: config.dryRun,\n      run: createMappedChildRunner(config),\n    };\n\n    const skip = config.skip;\n    if (skip !== undefined) {\n      definition.skip = skip;\n    }\n    return buildStep(id, definition);\n  };\n\n  function forEachPipeline<\n    TId extends string,\n    TChildPipeline extends Pipeline<object, unknown>,\n    TItem,\n    const TDeps extends readonly AnyStep<TOptions>[] = [],\n    const TOptionalDeps extends readonly AnyStep<TOptions>[] = [],\n  >(\n    id: TId,\n    definition: MappedChildPipelineStepDefinition<\n      TOptions,\n      TDeps,\n      TOptionalDeps,\n      TChildPipeline,\n      TItem\n    > & {\n      skip?: never;\n      mapResult?: undefined;\n    }\n  ): BuiltStep<TId, readonly PipelineResultOf<TChildPipeline>[], TOptions, TInputOptions>;\n  function forEachPipeline<\n    TId extends string,\n    TChildPipeline extends Pipeline<object, unknown>,\n    TItem,\n    TOut,\n    const TDeps extends readonly AnyStep<TOptions>[] = [],\n    const TOptionalDeps extends readonly AnyStep<TOptions>[] = [],\n  >(\n    id: TId,\n    definition: MappedChildPipelineStepDefinition<\n      TOptions,\n      TDeps,\n      TOptionalDeps,\n      TChildPipeline,\n      TItem\n    > & {\n      skip?: never;\n      mapResult(\n        value: PipelineResultOf<TChildPipeline>,\n        result: PipelineRun<PipelineResultOf<TChildPipeline>>,\n        item: TItem,\n        index: number,\n        context: PipelineStepContext<TOptions>\n      ): TOut;\n    }\n  ): BuiltStep<TId, readonly TOut[], TOptions, TInputOptions>;\n  function forEachPipeline<\n    TId extends string,\n    TChildPipeline extends Pipeline<object, unknown>,\n    TItem,\n    const TDeps extends readonly AnyStep<TOptions>[] = [],\n    const TOptionalDeps extends readonly AnyStep<TOptions>[] = [],\n    TDecision extends StepSkipDecision<readonly PipelineResultOf<TChildPipeline>[]> =\n      StepSkipDecision<readonly PipelineResultOf<TChildPipeline>[]>,\n  >(\n    id: TId,\n    definition: MappedChildPipelineStepDefinition<\n      TOptions,\n      TDeps,\n      TOptionalDeps,\n      TChildPipeline,\n      TItem\n    > & {\n      skip:\n        | StepSkipPredicate<\n            TOptions,\n            TDeps,\n            TOptionalDeps,\n            readonly PipelineResultOf<TChildPipeline>[],\n            TDecision\n          >\n        | undefined;\n      mapResult?: undefined;\n    }\n  ): BuiltStep<\n    TId,\n    PolicySkippedOutput<readonly PipelineResultOf<TChildPipeline>[], TDecision>,\n    TOptions,\n    TInputOptions\n  >;\n  function forEachPipeline<\n    TId extends string,\n    TChildPipeline extends Pipeline<object, unknown>,\n    TItem,\n    TOut,\n    const TDeps extends readonly AnyStep<TOptions>[] = [],\n    const TOptionalDeps extends readonly AnyStep<TOptions>[] = [],\n    TDecision extends StepSkipDecision<NoInfer<readonly TOut[]>> = StepSkipDecision<\n      NoInfer<readonly TOut[]>\n    >,\n  >(\n    id: TId,\n    definition: MappedChildPipelineStepDefinition<\n      TOptions,\n      TDeps,\n      TOptionalDeps,\n      TChildPipeline,\n      TItem\n    > & {\n      skip:\n        | StepSkipPredicate<TOptions, TDeps, TOptionalDeps, NoInfer<readonly TOut[]>, TDecision>\n        | undefined;\n      mapResult(\n        value: PipelineResultOf<TChildPipeline>,\n        result: PipelineRun<PipelineResultOf<TChildPipeline>>,\n        item: TItem,\n        index: number,\n        context: PipelineStepContext<TOptions>\n      ): TOut;\n    }\n  ): BuiltStep<TId, PolicySkippedOutput<readonly TOut[], TDecision>, TOptions, TInputOptions>;\n  function forEachPipeline(\n    id: string,\n    definition: Parameters<typeof buildMappedPipelineStep>[1]\n  ): AnyStep<TOptions> {\n    return buildMappedPipelineStep(id, definition);\n  }\n\n  const factory = {\n    step,\n    fromPipeline,\n    fromRemote,\n    forEachPipeline,\n  };\n\n  return factory;\n}\n"]}
+{"version":3,"file":"pipeline-steps.js","sourceRoot":"","sources":["../../src/core/pipeline-steps.ts"],"names":[],"mappings":"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","sourcesContent":["import {\n  type ArtifactLoader,\n  type ArtifactSaver,\n  type ArtifactResult,\n} from \"./pipeline-artifacts.js\";\nimport { createMappedChildRunner, createSingleChildRunner } from \"./child-execution.js\";\nimport { createIterationRunner, type IterationDecision, type IterationState } from \"./iteration.js\";\nimport type { ToMappedChildStepProgressOptions } from \"./mapped-child-progress.js\";\nimport {\n  STEP_NESTED_PIPELINE,\n  STEP_OPTIONS_SCHEMA,\n  STEP_REMOTE,\n} from \"./pipeline-step-metadata.js\";\nimport type {\n  InferSchemaInput,\n  InferSchemaOutput,\n  Pipeline,\n  PipelineExecutionContext,\n  PipelinePlanStep,\n  PipelineRun,\n  PipelineRunControls,\n  PipelineStepContext,\n  RemoteStepAdapter,\n  StandardSchemaV1,\n  StepSkipDecision,\n} from \"./pipeline-types.js\";\n\n/**\n * A step's dependencies are references to the dependency's own step object, not string ids\n * into a hand-maintained output-type map. This buys two things no amount of extra generics\n * on a string-keyed design could:\n *  - a step used before its dependency exists is a compile error (JS temporal dead zone on\n *    `const`), so out-of-order and self/cyclic dependencies are caught by the language, not\n *    a bespoke runtime check\n *  - each step only ever states its own id/deps; the output-type map is derived, never\n *    restated, and callers of `definePipeline`/`createSteps` never write out its generics\n */\ntype AnyStepDryRunHandler<TOptions extends object> = {\n  bivarianceHack(\n    inputs: Record<string, unknown>,\n    context: PipelineStepContext<TOptions>\n  ): unknown | Promise<unknown>;\n}[\"bivarianceHack\"];\n\n/** Runtime shape shared by every declared pipeline step. */\nexport interface AnyStep<TOptions extends object = object> {\n  readonly [STEP_NESTED_PIPELINE]?: NonNullable<PipelinePlanStep[\"nestedPipeline\"]>;\n  readonly [STEP_REMOTE]?: NonNullable<PipelinePlanStep[\"remote\"]>;\n  readonly [STEP_OPTIONS_SCHEMA]?: StandardSchemaV1;\n  readonly id: string;\n  readonly dependsOn?: readonly AnyStep<TOptions>[];\n  readonly optionalDependsOn?: readonly AnyStep<TOptions>[];\n  readonly skipAfterFailureOf?: readonly AnyStep<TOptions>[];\n  /** Optional human-facing display name. Stable machine identity remains `id`. */\n  readonly name?: string;\n  readonly description?: string;\n  /**\n   * Dry-run policy. Omitted runs the normal handler, `\"skip\"` structurally\n   * skips it, and a handler substitutes for `run` while preserving its output.\n   */\n  readonly dryRun?: \"skip\" | AnyStepDryRunHandler<TOptions>;\n  /** Optional Standard Schema for values published by this step. */\n  readonly outputSchema?: StandardSchemaV1;\n  /**\n   * Optional runtime skip. Return a non-empty reason (or `{ reason, value }`) to\n   * skip without calling `run`. Policy skips unlock dependents; structural skips\n   * (dry-run, filtered, …) do not use this hook.\n   */\n  skip?(\n    inputs: Record<string, unknown>,\n    context: PipelineExecutionContext<TOptions>\n  ): StepSkipDecision | Promise<StepSkipDecision>;\n  run(inputs: Record<string, unknown>, context: PipelineStepContext<TOptions>): unknown;\n}\n\n/** The step fields that `buildStep` merges onto the id-bearing shell. */\ntype StepDefinitionBody<TOptions extends object> = Omit<AnyStep<TOptions>, \"id\">;\n\n/** Typed pipeline step carrying its stable ID, output, and option types. */\nexport interface Step<\n  TId extends string,\n  TOut,\n  TOptions extends object,\n  TInputOptions extends object = TOptions,\n  TRunOut = TOut,\n  TOptionsSchema extends StandardSchemaV1 | undefined = StandardSchemaV1 | undefined,\n> extends AnyStep<TOptions> {\n  readonly [STEP_OPTIONS_SCHEMA]?: TOptionsSchema;\n  readonly id: TId;\n  run(\n    inputs: Record<string, unknown>,\n    context: PipelineStepContext<TOptions>\n  ): TRunOut | Promise<TRunOut>;\n  /** Type-only: carries this step's output type for sibling inference. Never set at runtime. */\n  readonly __outputType?: TOut;\n  /** Type-only: carries pre-validation run options for pipeline call-site inference. */\n  readonly __inputOptionsType?: TInputOptions;\n}\n\n/**\n * Extract a step's output type for dependency typing.\n * Prefer matching `Step<…, TOut, …>` over `{ __outputType?: infer T }`: optional-property\n * inference collapses `TOut | undefined` to `TOut`, which hides policy-skip widening.\n */\nexport type StepOutput<S> =\n  S extends Step<string, infer TOut, infer _TOptions, infer _TInputOptions, infer _TRunOut>\n    ? TOut\n    : never;\n\ninterface StepToken {\n  readonly id: string;\n  readonly __outputType?: unknown;\n}\n\ntype RequiredInputs<TDeps extends readonly StepToken[]> = {\n  [S in TDeps[number] as S[\"id\"]]: StepOutput<S>;\n};\n\ntype OptionalInputs<TDeps extends readonly StepToken[]> = {\n  [S in TDeps[number] as S[\"id\"]]?: StepOutput<S>;\n};\n\ntype PipelineResultOf<TPipeline> =\n  TPipeline extends Pipeline<object, infer TResult, infer _TStepId, infer _TTargetId>\n    ? TResult\n    : never;\n\ntype PipelineOptionsOf<TPipeline> =\n  TPipeline extends Pipeline<infer TOptions, unknown, infer _TStepId, infer _TTargetId>\n    ? TOptions\n    : never;\n\ntype PipelineRunControlsOf<TPipeline> =\n  TPipeline extends Pipeline<infer _TOptions, unknown, infer TStepId, infer TTargetId>\n    ? PipelineRunControls<TStepId, TTargetId>\n    : never;\n\ntype ChildPipelineStepDefinitionBase<\n  TParentOptions extends object,\n  TDeps extends readonly AnyStep<TParentOptions>[],\n  TOptionalDeps extends readonly AnyStep<TParentOptions>[],\n  TChildPipeline extends Pipeline<object, unknown>,\n> = {\n  pipeline: TChildPipeline;\n  dependsOn?: TDeps;\n  optionalDependsOn?: TOptionalDeps;\n  skipAfterFailureOf?: readonly AnyStep<TParentOptions>[];\n  name?: string;\n  description?: string;\n  dryRun?: \"skip\";\n  controls?:\n    | PipelineRunControlsOf<TChildPipeline>\n    | ((\n        inputs: RequiredInputs<TDeps> & OptionalInputs<TOptionalDeps>,\n        context: PipelineExecutionContext<TParentOptions>\n      ) => PipelineRunControlsOf<TChildPipeline>);\n} & ([TParentOptions] extends [PipelineOptionsOf<NoInfer<TChildPipeline>>]\n  ? {\n      mapOptions?(\n        inputs: RequiredInputs<TDeps> & OptionalInputs<TOptionalDeps>,\n        context: PipelineExecutionContext<TParentOptions>\n      ): PipelineOptionsOf<TChildPipeline>;\n    }\n  : {\n      mapOptions(\n        inputs: RequiredInputs<TDeps> & OptionalInputs<TOptionalDeps>,\n        context: PipelineExecutionContext<TParentOptions>\n      ): PipelineOptionsOf<TChildPipeline>;\n    });\n\n/** Child step without policy skip (dependents see the full child result type). */\ntype ChildPipelineStepDefinition<\n  TParentOptions extends object,\n  TDeps extends readonly AnyStep<TParentOptions>[],\n  TOptionalDeps extends readonly AnyStep<TParentOptions>[],\n  TChildPipeline extends Pipeline<object, unknown>,\n> = ChildPipelineStepDefinitionBase<TParentOptions, TDeps, TOptionalDeps, TChildPipeline>;\n\n/**\n * Presentation options for opaque `forEachPipeline` progress.\n * Defaults are domain-neutral (`N/M items · K running · key/step`).\n * Override `formatMessage` when a domain wants its own noun (images, shards, …).\n */\nexport type MappedChildProgressOptions = ToMappedChildStepProgressOptions;\n\ntype MappedChildPipelineStepDefinition<\n  TParentOptions extends object,\n  TDeps extends readonly AnyStep<TParentOptions>[],\n  TOptionalDeps extends readonly AnyStep<TParentOptions>[],\n  TChildPipeline extends Pipeline<object, unknown>,\n  TItem,\n> = {\n  pipeline: TChildPipeline;\n  dependsOn?: TDeps;\n  optionalDependsOn?: TOptionalDeps;\n  skipAfterFailureOf?: readonly AnyStep<TParentOptions>[];\n  name?: string;\n  description?: string;\n  dryRun?: \"skip\";\n  items(\n    inputs: RequiredInputs<TDeps> & OptionalInputs<TOptionalDeps>,\n    context: PipelineExecutionContext<TParentOptions>\n  ): readonly TItem[] | Promise<readonly TItem[]>;\n  key(item: TItem, index: number): string;\n  concurrency?:\n    | number\n    | ((\n        inputs: RequiredInputs<TDeps> & OptionalInputs<TOptionalDeps>,\n        context: PipelineExecutionContext<TParentOptions>\n      ) => number);\n  /**\n   * How the opaque parent step reports live fan-out progress.\n   * Purely presentational — does not change scheduling or results.\n   */\n  progress?: MappedChildProgressOptions;\n  controls?:\n    | PipelineRunControlsOf<TChildPipeline>\n    | ((\n        item: TItem,\n        index: number,\n        inputs: RequiredInputs<TDeps> & OptionalInputs<TOptionalDeps>,\n        context: PipelineExecutionContext<TParentOptions>\n      ) => PipelineRunControlsOf<TChildPipeline>);\n  mapOptions(\n    item: TItem,\n    index: number,\n    inputs: RequiredInputs<TDeps> & OptionalInputs<TOptionalDeps>,\n    context: PipelineExecutionContext<TParentOptions>\n  ): PipelineOptionsOf<TChildPipeline>;\n};\n\ntype StepSkipPredicate<\n  TOptions extends object,\n  TDeps extends readonly AnyStep<TOptions>[],\n  TOptionalDeps extends readonly AnyStep<TOptions>[],\n  TOut,\n  TDecision extends StepSkipDecision<TOut> = StepSkipDecision<TOut>,\n> = (\n  inputs: RequiredInputs<TDeps> & OptionalInputs<TOptionalDeps>,\n  context: PipelineExecutionContext<TOptions>\n) => TDecision | Promise<TDecision>;\n\ntype PolicySkippedOutput<TOut, TDecision> = [\n  Exclude<Awaited<TDecision>, false | null | undefined>,\n] extends [{ reason: string; value: unknown }]\n  ? TOut\n  : TOut | undefined;\n\ntype StepDryRunPolicy<\n  TOptions extends object,\n  TDeps extends readonly AnyStep<TOptions>[],\n  TOptionalDeps extends readonly AnyStep<TOptions>[],\n  TOut,\n> =\n  | \"skip\"\n  | ((\n      inputs: RequiredInputs<TDeps> & OptionalInputs<TOptionalDeps>,\n      context: PipelineStepContext<TOptions>\n    ) => TOut | Promise<TOut>);\n\ntype PlainStepFields<\n  TOptions extends object,\n  TDeps extends readonly AnyStep<TOptions>[],\n  TOptionalDeps extends readonly AnyStep<TOptions>[],\n  TOut,\n> = {\n  dependsOn?: TDeps;\n  optionalDependsOn?: TOptionalDeps;\n  skipAfterFailureOf?: readonly AnyStep<TOptions>[];\n  name?: string;\n  description?: string;\n  dryRun?: StepDryRunPolicy<TOptions, TDeps, TOptionalDeps, TOut>;\n  outputSchema?: never;\n  run(\n    inputs: RequiredInputs<TDeps> & OptionalInputs<TOptionalDeps>,\n    context: PipelineStepContext<TOptions>\n  ): TOut | Promise<TOut>;\n};\n\ntype SchemaStepFields<\n  TOptions extends object,\n  TDeps extends readonly AnyStep<TOptions>[],\n  TOptionalDeps extends readonly AnyStep<TOptions>[],\n  TSchema extends StandardSchemaV1,\n> = Omit<\n  PlainStepFields<TOptions, TDeps, TOptionalDeps, InferSchemaInput<TSchema>>,\n  \"outputSchema\"\n> & {\n  outputSchema: TSchema;\n};\n\ntype RemoteStepDefinitionBase<\n  TParentOptions extends object,\n  TDeps extends readonly AnyStep<TParentOptions>[],\n  TOptionalDeps extends readonly AnyStep<TParentOptions>[],\n  TPayload,\n  TSchema extends StandardSchemaV1,\n> = {\n  adapter: RemoteStepAdapter<TParentOptions, TPayload, InferSchemaInput<TSchema>>;\n  mapInput(\n    inputs: RequiredInputs<TDeps> & OptionalInputs<TOptionalDeps>,\n    context: PipelineStepContext<TParentOptions>\n  ): TPayload;\n  outputSchema: TSchema;\n  dependsOn?: TDeps;\n  optionalDependsOn?: TOptionalDeps;\n  skipAfterFailureOf?: readonly AnyStep<TParentOptions>[];\n  name?: string;\n  description?: string;\n  dryRun?: StepDryRunPolicy<TParentOptions, TDeps, TOptionalDeps, InferSchemaInput<TSchema>>;\n};\n\n/** Step constructors scoped to one pipeline's domain option types. */\ntype StepFactory<\n  TOptions extends object,\n  TInputOptions extends object = TOptions,\n  TOptionsSchema extends StandardSchemaV1 | undefined = undefined,\n> = ReturnType<typeof createStepFactory<TOptions, TInputOptions, TOptionsSchema>>;\n\n/**\n * Create typed step constructors for one pipeline definition.\n * Returns a step factory scoped to one pipeline's domain options. Pass built-in\n * run controls as the second argument to `run` / `runOrThrow`, or through a\n * child step's separate `controls` field.\n */\nexport function createSteps<TOptions extends object = {}>(): StepFactory<TOptions>;\nexport function createSteps<const TSchema extends StandardSchemaV1<object, object> | undefined>(\n  optionsSchema: TSchema\n): StepFactory<\n  TSchema extends StandardSchemaV1 ? InferSchemaOutput<TSchema> : object,\n  TSchema extends StandardSchemaV1 ? InferSchemaInput<TSchema> : object,\n  TSchema\n>;\nexport function createSteps(\n  optionsSchema?: StandardSchemaV1<object, object>\n): StepFactory<object, object, StandardSchemaV1 | undefined> {\n  return createStepFactory<object, object, StandardSchemaV1 | undefined>(optionsSchema);\n}\n\nfunction createStepFactory<\n  TOptions extends object,\n  TInputOptions extends object = TOptions,\n  TOptionsSchema extends StandardSchemaV1 | undefined = undefined,\n>(optionsSchema?: TOptionsSchema) {\n  // Preserve the runtime schema in the step type so adapters cannot infer flags\n  // from erased TypeScript-only options.\n  type BuiltStep<\n    TId extends string,\n    TOut,\n    TStepOptions extends object,\n    TInput extends object,\n    TRunOut = TOut,\n  > = TOptionsSchema extends StandardSchemaV1\n    ? Step<TId, TOut, TStepOptions, TInput, TRunOut, TOptionsSchema>\n    : Step<TId, TOut, TStepOptions, TInput, TRunOut>;\n  const buildStep = (id: string, definition: StepDefinitionBody<TOptions>): AnyStep<TOptions> => {\n    const built: AnyStep<TOptions> = { id, ...definition };\n    if (optionsSchema) {\n      Object.defineProperty(built, STEP_OPTIONS_SCHEMA, { value: optionsSchema });\n    }\n    return built;\n  };\n\n  function step<\n    TId extends string,\n    TSchema extends StandardSchemaV1,\n    const TDeps extends readonly AnyStep<TOptions>[] = [],\n    const TOptionalDeps extends readonly AnyStep<TOptions>[] = [],\n    TDecision extends StepSkipDecision<InferSchemaInput<TSchema>> = StepSkipDecision<\n      InferSchemaInput<TSchema>\n    >,\n  >(\n    id: TId,\n    definition: SchemaStepFields<TOptions, TDeps, TOptionalDeps, TSchema> & {\n      skip:\n        | StepSkipPredicate<TOptions, TDeps, TOptionalDeps, InferSchemaInput<TSchema>, TDecision>\n        | undefined;\n    }\n  ): BuiltStep<\n    TId,\n    PolicySkippedOutput<InferSchemaOutput<TSchema>, TDecision>,\n    TOptions,\n    TInputOptions,\n    InferSchemaInput<TSchema>\n  >;\n  function step<\n    TId extends string,\n    const TDeps extends readonly AnyStep<TOptions>[] = [],\n    const TOptionalDeps extends readonly AnyStep<TOptions>[] = [],\n    TOut = unknown,\n    TDecision extends StepSkipDecision<NoInfer<TOut>> = StepSkipDecision<NoInfer<TOut>>,\n  >(\n    id: TId,\n    definition: PlainStepFields<TOptions, TDeps, TOptionalDeps, TOut> & {\n      skip: StepSkipPredicate<TOptions, TDeps, TOptionalDeps, NoInfer<TOut>, TDecision> | undefined;\n    }\n  ): BuiltStep<TId, PolicySkippedOutput<TOut, TDecision>, TOptions, TInputOptions>;\n  function step<\n    TId extends string,\n    TSchema extends StandardSchemaV1,\n    const TDeps extends readonly AnyStep<TOptions>[] = [],\n    const TOptionalDeps extends readonly AnyStep<TOptions>[] = [],\n  >(\n    id: TId,\n    definition: SchemaStepFields<TOptions, TDeps, TOptionalDeps, TSchema> & { skip?: never }\n  ): BuiltStep<TId, InferSchemaOutput<TSchema>, TOptions, TInputOptions, InferSchemaInput<TSchema>>;\n  function step<\n    TId extends string,\n    const TDeps extends readonly AnyStep<TOptions>[] = [],\n    const TOptionalDeps extends readonly AnyStep<TOptions>[] = [],\n    TOut = unknown,\n  >(\n    id: TId,\n    definition: PlainStepFields<TOptions, TDeps, TOptionalDeps, TOut> & { skip?: never }\n  ): BuiltStep<TId, TOut, TOptions, TInputOptions>;\n  function step(id: string, definition: StepDefinitionBody<TOptions>): AnyStep<TOptions> {\n    return buildStep(id, definition);\n  }\n\n  /** Read an artifact as an ordinary step, publishing only its typed value. */\n  function loadArtifact<\n    TId extends string,\n    const TDeps extends readonly AnyStep<TOptions>[] = [],\n    const TOptionalDeps extends readonly AnyStep<TOptions>[] = [],\n    TValue = unknown,\n  >(\n    id: TId,\n    definition: Omit<\n      PlainStepFields<TOptions, TDeps, TOptionalDeps, ArtifactResult<TValue>>,\n      \"run\"\n    > & {\n      load: ArtifactLoader<RequiredInputs<TDeps> & OptionalInputs<TOptionalDeps>, TValue, TOptions>;\n    }\n  ): BuiltStep<TId, TValue, TOptions, TInputOptions> {\n    const { load, dryRun, ...fields } = definition;\n    const wrap =\n      (handler: typeof load) =>\n      async (\n        inputs: RequiredInputs<TDeps> & OptionalInputs<TOptionalDeps>,\n        context: PipelineStepContext<TOptions>\n      ) => {\n        const loaded = await handler(inputs, context);\n        context.recordArtifact({ operation: \"read\", artifact: loaded.artifact });\n        return loaded.value;\n      };\n    return step(id, {\n      ...fields,\n      run: wrap(load),\n      dryRun: typeof dryRun === \"function\" ? wrap(dryRun) : dryRun,\n    });\n  }\n\n  /** Write an artifact as an ordinary step. Dry runs skip unless a preview is supplied. */\n  function saveArtifact<\n    TId extends string,\n    const TDeps extends readonly AnyStep<TOptions>[] = [],\n    const TOptionalDeps extends readonly AnyStep<TOptions>[] = [],\n    TValue = unknown,\n  >(\n    id: TId,\n    definition: Omit<\n      PlainStepFields<TOptions, TDeps, TOptionalDeps, ArtifactResult<TValue>>,\n      \"run\"\n    > & {\n      save: ArtifactSaver<RequiredInputs<TDeps> & OptionalInputs<TOptionalDeps>, TValue, TOptions>;\n    }\n  ): BuiltStep<TId, TValue, TOptions, TInputOptions> {\n    const { save, dryRun, ...fields } = definition;\n    const wrap =\n      (handler: typeof save) =>\n      async (\n        inputs: RequiredInputs<TDeps> & OptionalInputs<TOptionalDeps>,\n        context: PipelineStepContext<TOptions>\n      ) => {\n        const saved = await handler(inputs, context);\n        context.recordArtifact({ operation: \"write\", artifact: saved.artifact });\n        return saved.value;\n      };\n    return step(id, {\n      ...fields,\n      run: wrap(save),\n      dryRun: typeof dryRun === \"function\" ? wrap(dryRun) : \"skip\",\n    });\n  }\n\n  const buildPipelineStep = (\n    id: string,\n    config: ChildPipelineStepDefinitionBase<\n      TOptions,\n      readonly AnyStep<TOptions>[],\n      readonly AnyStep<TOptions>[],\n      Pipeline<object, unknown>\n    > & {\n      skip?: StepSkipPredicate<\n        TOptions,\n        readonly AnyStep<TOptions>[],\n        readonly AnyStep<TOptions>[],\n        unknown\n      >;\n      mapResult?: (\n        value: unknown,\n        result: PipelineRun<unknown>,\n        context: PipelineStepContext<TOptions>\n      ) => unknown;\n    }\n  ) => {\n    const definition: StepDefinitionBody<TOptions> = {\n      [STEP_NESTED_PIPELINE]: {\n        mode: \"single\" as const,\n        pipelineId: config.pipeline.id,\n        identity: config.pipeline.definition?.identity,\n        stepIds: config.pipeline.stepIds,\n      },\n      dependsOn: config.dependsOn,\n      optionalDependsOn: config.optionalDependsOn,\n      skipAfterFailureOf: config.skipAfterFailureOf,\n      name: config.name,\n      description: config.description,\n      dryRun: config.dryRun,\n      run: createSingleChildRunner(config),\n    };\n\n    const skip = config.skip;\n    if (skip !== undefined) {\n      definition.skip = skip;\n    }\n    return buildStep(id, definition);\n  };\n\n  function fromPipeline<\n    TId extends string,\n    TChildPipeline extends Pipeline<object, unknown>,\n    const TDeps extends readonly AnyStep<TOptions>[] = [],\n    const TOptionalDeps extends readonly AnyStep<TOptions>[] = [],\n  >(\n    id: TId,\n    definition: ChildPipelineStepDefinition<TOptions, TDeps, TOptionalDeps, TChildPipeline> & {\n      skip?: never;\n      mapResult?: undefined;\n    }\n  ): BuiltStep<TId, PipelineResultOf<TChildPipeline>, TOptions, TInputOptions>;\n  function fromPipeline<\n    TId extends string,\n    TChildPipeline extends Pipeline<object, unknown>,\n    TOut,\n    const TDeps extends readonly AnyStep<TOptions>[] = [],\n    const TOptionalDeps extends readonly AnyStep<TOptions>[] = [],\n  >(\n    id: TId,\n    definition: ChildPipelineStepDefinitionBase<TOptions, TDeps, TOptionalDeps, TChildPipeline> & {\n      skip?: never;\n      mapResult(\n        value: PipelineResultOf<TChildPipeline>,\n        result: PipelineRun<PipelineResultOf<TChildPipeline>>,\n        context: PipelineStepContext<TOptions>\n      ): TOut;\n    }\n  ): BuiltStep<TId, Awaited<TOut>, TOptions, TInputOptions>;\n  function fromPipeline<\n    TId extends string,\n    TChildPipeline extends Pipeline<object, unknown>,\n    const TDeps extends readonly AnyStep<TOptions>[] = [],\n    const TOptionalDeps extends readonly AnyStep<TOptions>[] = [],\n    TDecision extends StepSkipDecision<PipelineResultOf<TChildPipeline>> = StepSkipDecision<\n      PipelineResultOf<TChildPipeline>\n    >,\n  >(\n    id: TId,\n    definition: ChildPipelineStepDefinitionBase<TOptions, TDeps, TOptionalDeps, TChildPipeline> & {\n      skip:\n        | StepSkipPredicate<\n            TOptions,\n            TDeps,\n            TOptionalDeps,\n            PipelineResultOf<TChildPipeline>,\n            TDecision\n          >\n        | undefined;\n      mapResult?: undefined;\n    }\n  ): BuiltStep<\n    TId,\n    PolicySkippedOutput<PipelineResultOf<TChildPipeline>, TDecision>,\n    TOptions,\n    TInputOptions\n  >;\n  function fromPipeline<\n    TId extends string,\n    TChildPipeline extends Pipeline<object, unknown>,\n    TOut,\n    const TDeps extends readonly AnyStep<TOptions>[] = [],\n    const TOptionalDeps extends readonly AnyStep<TOptions>[] = [],\n    TDecision extends StepSkipDecision<NoInfer<Awaited<TOut>>> = StepSkipDecision<\n      NoInfer<Awaited<TOut>>\n    >,\n  >(\n    id: TId,\n    definition: ChildPipelineStepDefinitionBase<TOptions, TDeps, TOptionalDeps, TChildPipeline> & {\n      skip:\n        | StepSkipPredicate<TOptions, TDeps, TOptionalDeps, NoInfer<Awaited<TOut>>, TDecision>\n        | undefined;\n      mapResult(\n        value: PipelineResultOf<TChildPipeline>,\n        result: PipelineRun<PipelineResultOf<TChildPipeline>>,\n        context: PipelineStepContext<TOptions>\n      ): TOut;\n    }\n  ): BuiltStep<TId, PolicySkippedOutput<Awaited<TOut>, TDecision>, TOptions, TInputOptions>;\n  function fromPipeline(\n    id: string,\n    definition: Parameters<typeof buildPipelineStep>[1]\n  ): AnyStep<TOptions> {\n    return buildPipelineStep(id, definition);\n  }\n\n  const buildRemoteStep = (\n    id: string,\n    config: {\n      adapter: RemoteStepAdapter<object, unknown, unknown>;\n      mapInput(inputs: Record<string, unknown>, context: PipelineStepContext<TOptions>): unknown;\n      outputSchema: StandardSchemaV1;\n      dependsOn?: readonly AnyStep<TOptions>[];\n      optionalDependsOn?: readonly AnyStep<TOptions>[];\n      skipAfterFailureOf?: readonly AnyStep<TOptions>[];\n      name?: string;\n      description?: string;\n      dryRun?: \"skip\" | AnyStepDryRunHandler<TOptions>;\n      skip?: StepSkipPredicate<\n        TOptions,\n        readonly AnyStep<TOptions>[],\n        readonly AnyStep<TOptions>[],\n        unknown\n      >;\n    }\n  ) => {\n    const remote: NonNullable<PipelinePlanStep[\"remote\"]> = { engine: config.adapter.engine };\n    if (config.adapter.target !== undefined) remote.target = config.adapter.target;\n    const definition: StepDefinitionBody<TOptions> = {\n      [STEP_REMOTE]: remote,\n      dependsOn: config.dependsOn,\n      optionalDependsOn: config.optionalDependsOn,\n      skipAfterFailureOf: config.skipAfterFailureOf,\n      name: config.name,\n      description: config.description,\n      dryRun: config.dryRun,\n      outputSchema: config.outputSchema,\n      run: (inputs: Record<string, unknown>, context: PipelineStepContext<TOptions>) =>\n        config.adapter.invoke(config.mapInput(inputs, context), context),\n    };\n    const skip = config.skip;\n    if (skip !== undefined) {\n      definition.skip = skip;\n    }\n    return buildStep(id, definition);\n  };\n\n  function fromRemote<\n    TId extends string,\n    TSchema extends StandardSchemaV1,\n    TPayload,\n    const TDeps extends readonly AnyStep<TOptions>[] = [],\n    const TOptionalDeps extends readonly AnyStep<TOptions>[] = [],\n  >(\n    id: TId,\n    definition: RemoteStepDefinitionBase<TOptions, TDeps, TOptionalDeps, TPayload, TSchema> & {\n      skip?: never;\n    }\n  ): BuiltStep<TId, InferSchemaOutput<TSchema>, TOptions, TInputOptions, InferSchemaInput<TSchema>>;\n  function fromRemote<\n    TId extends string,\n    TSchema extends StandardSchemaV1,\n    TPayload,\n    const TDeps extends readonly AnyStep<TOptions>[] = [],\n    const TOptionalDeps extends readonly AnyStep<TOptions>[] = [],\n    TDecision extends StepSkipDecision<InferSchemaInput<TSchema>> = StepSkipDecision<\n      InferSchemaInput<TSchema>\n    >,\n  >(\n    id: TId,\n    definition: RemoteStepDefinitionBase<TOptions, TDeps, TOptionalDeps, TPayload, TSchema> & {\n      skip:\n        | StepSkipPredicate<TOptions, TDeps, TOptionalDeps, InferSchemaInput<TSchema>, TDecision>\n        | undefined;\n    }\n  ): BuiltStep<\n    TId,\n    PolicySkippedOutput<InferSchemaOutput<TSchema>, TDecision>,\n    TOptions,\n    TInputOptions,\n    InferSchemaInput<TSchema>\n  >;\n  function fromRemote(\n    id: string,\n    definition: Parameters<typeof buildRemoteStep>[1]\n  ): AnyStep<TOptions> {\n    return buildRemoteStep(id, definition);\n  }\n\n  const buildMappedPipelineStep = (\n    id: string,\n    config: MappedChildPipelineStepDefinition<\n      TOptions,\n      readonly AnyStep<TOptions>[],\n      readonly AnyStep<TOptions>[],\n      Pipeline<object, unknown>,\n      unknown\n    > & {\n      mapResult?: (\n        value: unknown,\n        result: PipelineRun<unknown>,\n        item: unknown,\n        index: number,\n        context: PipelineStepContext<TOptions>\n      ) => unknown;\n      skip?: StepSkipPredicate<\n        TOptions,\n        readonly AnyStep<TOptions>[],\n        readonly AnyStep<TOptions>[],\n        unknown\n      >;\n    }\n  ) => {\n    const definition: StepDefinitionBody<TOptions> = {\n      [STEP_NESTED_PIPELINE]: {\n        mode: \"for-each\" as const,\n        concurrency:\n          typeof config.concurrency === \"function\" ? \"dynamic\" : (config.concurrency ?? 1),\n        pipelineId: config.pipeline.id,\n        identity: config.pipeline.definition?.identity,\n        stepIds: config.pipeline.stepIds,\n      },\n      dependsOn: config.dependsOn,\n      optionalDependsOn: config.optionalDependsOn,\n      skipAfterFailureOf: config.skipAfterFailureOf,\n      name: config.name,\n      description: config.description,\n      dryRun: config.dryRun,\n      run: createMappedChildRunner(config),\n    };\n\n    const skip = config.skip;\n    if (skip !== undefined) {\n      definition.skip = skip;\n    }\n    return buildStep(id, definition);\n  };\n\n  function forEachPipeline<\n    TId extends string,\n    TChildPipeline extends Pipeline<object, unknown>,\n    TItem,\n    const TDeps extends readonly AnyStep<TOptions>[] = [],\n    const TOptionalDeps extends readonly AnyStep<TOptions>[] = [],\n  >(\n    id: TId,\n    definition: MappedChildPipelineStepDefinition<\n      TOptions,\n      TDeps,\n      TOptionalDeps,\n      TChildPipeline,\n      TItem\n    > & {\n      skip?: never;\n      mapResult?: undefined;\n    }\n  ): BuiltStep<TId, readonly PipelineResultOf<TChildPipeline>[], TOptions, TInputOptions>;\n  function forEachPipeline<\n    TId extends string,\n    TChildPipeline extends Pipeline<object, unknown>,\n    TItem,\n    TOut,\n    const TDeps extends readonly AnyStep<TOptions>[] = [],\n    const TOptionalDeps extends readonly AnyStep<TOptions>[] = [],\n  >(\n    id: TId,\n    definition: MappedChildPipelineStepDefinition<\n      TOptions,\n      TDeps,\n      TOptionalDeps,\n      TChildPipeline,\n      TItem\n    > & {\n      skip?: never;\n      mapResult(\n        value: PipelineResultOf<TChildPipeline>,\n        result: PipelineRun<PipelineResultOf<TChildPipeline>>,\n        item: TItem,\n        index: number,\n        context: PipelineStepContext<TOptions>\n      ): TOut;\n    }\n  ): BuiltStep<TId, readonly TOut[], TOptions, TInputOptions>;\n  function forEachPipeline<\n    TId extends string,\n    TChildPipeline extends Pipeline<object, unknown>,\n    TItem,\n    const TDeps extends readonly AnyStep<TOptions>[] = [],\n    const TOptionalDeps extends readonly AnyStep<TOptions>[] = [],\n    TDecision extends StepSkipDecision<readonly PipelineResultOf<TChildPipeline>[]> =\n      StepSkipDecision<readonly PipelineResultOf<TChildPipeline>[]>,\n  >(\n    id: TId,\n    definition: MappedChildPipelineStepDefinition<\n      TOptions,\n      TDeps,\n      TOptionalDeps,\n      TChildPipeline,\n      TItem\n    > & {\n      skip:\n        | StepSkipPredicate<\n            TOptions,\n            TDeps,\n            TOptionalDeps,\n            readonly PipelineResultOf<TChildPipeline>[],\n            TDecision\n          >\n        | undefined;\n      mapResult?: undefined;\n    }\n  ): BuiltStep<\n    TId,\n    PolicySkippedOutput<readonly PipelineResultOf<TChildPipeline>[], TDecision>,\n    TOptions,\n    TInputOptions\n  >;\n  function forEachPipeline<\n    TId extends string,\n    TChildPipeline extends Pipeline<object, unknown>,\n    TItem,\n    TOut,\n    const TDeps extends readonly AnyStep<TOptions>[] = [],\n    const TOptionalDeps extends readonly AnyStep<TOptions>[] = [],\n    TDecision extends StepSkipDecision<NoInfer<readonly TOut[]>> = StepSkipDecision<\n      NoInfer<readonly TOut[]>\n    >,\n  >(\n    id: TId,\n    definition: MappedChildPipelineStepDefinition<\n      TOptions,\n      TDeps,\n      TOptionalDeps,\n      TChildPipeline,\n      TItem\n    > & {\n      skip:\n        | StepSkipPredicate<TOptions, TDeps, TOptionalDeps, NoInfer<readonly TOut[]>, TDecision>\n        | undefined;\n      mapResult(\n        value: PipelineResultOf<TChildPipeline>,\n        result: PipelineRun<PipelineResultOf<TChildPipeline>>,\n        item: TItem,\n        index: number,\n        context: PipelineStepContext<TOptions>\n      ): TOut;\n    }\n  ): BuiltStep<TId, PolicySkippedOutput<readonly TOut[], TDecision>, TOptions, TInputOptions>;\n  function forEachPipeline(\n    id: string,\n    definition: Parameters<typeof buildMappedPipelineStep>[1]\n  ): AnyStep<TOptions> {\n    return buildMappedPipelineStep(id, definition);\n  }\n\n  function iteratePipeline<\n    const TId extends string,\n    TChild extends Pipeline<object, unknown>,\n    TState,\n    TResult,\n    const TDeps extends readonly AnyStep<TOptions>[] = [],\n  >(\n    id: TId,\n    definition: {\n      pipeline: TChild;\n      name?: string;\n      description?: string;\n      dependsOn?: TDeps;\n      maxIterations: number;\n      dryRun?: \"skip\";\n      controls?: PipelineRunControlsOf<TChild>;\n      initialState(\n        inputs: RequiredInputs<TDeps>,\n        context: PipelineExecutionContext<TOptions>\n      ): TState;\n      mapOptions(\n        state: IterationState<NoInfer<TState>>,\n        inputs: RequiredInputs<TDeps>,\n        context: PipelineExecutionContext<TOptions>\n      ): PipelineOptionsOf<TChild>;\n      transition(\n        result: PipelineResultOf<TChild>,\n        state: IterationState<NoInfer<TState>>,\n        context: PipelineExecutionContext<TOptions>\n      ):\n        | IterationDecision<NoInfer<TState>, TResult>\n        | Promise<IterationDecision<NoInfer<TState>, TResult>>;\n    }\n  ): BuiltStep<TId, Awaited<TResult>, TOptions, TInputOptions>;\n  function iteratePipeline(\n    id: string,\n    definition: Omit<Parameters<typeof createIterationRunner<TOptions>>[0], \"stepId\"> & {\n      name?: string;\n      description?: string;\n      dependsOn?: readonly AnyStep<TOptions>[];\n      dryRun?: \"skip\";\n    }\n  ): AnyStep<TOptions> {\n    if (!Number.isSafeInteger(definition.maxIterations) || definition.maxIterations < 1) {\n      throw new RangeError(\"iteratePipeline maxIterations must be a positive safe integer\");\n    }\n    const controls = definition.controls ? structuredClone(definition.controls) : undefined;\n    if (controls) {\n      if (controls.targets) Object.freeze(controls.targets);\n      if (controls.stepIds) Object.freeze(controls.stepIds);\n      Object.freeze(controls);\n    }\n    const config = { ...definition, stepId: id, controls };\n    return buildStep(id, {\n      [STEP_NESTED_PIPELINE]: {\n        mode: \"iterate\",\n        maxIterations: config.maxIterations,\n        controls: config.controls,\n        pipelineId: config.pipeline.id,\n        identity: config.pipeline.definition?.identity,\n        stepIds: config.pipeline.stepIds,\n      },\n      name: config.name,\n      description: config.description,\n      dependsOn: config.dependsOn,\n      dryRun: config.dryRun,\n      run: createIterationRunner(config),\n    });\n  }\n\n  const factory = {\n    step,\n    loadArtifact,\n    saveArtifact,\n    fromPipeline,\n    fromRemote,\n    forEachPipeline,\n    iteratePipeline,\n  };\n\n  return factory;\n}\n"]}

package/dist/core/pipeline-types.d.ts

@@ -1,3 +1,4 @@
+import type { ArtifactRecord } from "../tracing/artifact-metadata.js";
 import type { PipelineDefinitionIdentityContract, PipelineDefinitionSnapshotContract } from "../tracing/tracing-schema.js";
 /** Versioned graph identity, separate from the optional handler implementation version. */
 export type PipelineDefinitionIdentity = Readonly<PipelineDefinitionIdentityContract>;
@@ -79,6 +80,8 @@ export interface PipelineExecutionContext<TOptions extends object> extends Pipel
 export type PipelineStepProgressDetailStatus = "cancelled" | "completed" | "failed" | "pending" | "running" | "skipped";
 /** One optional nested row in a step progress snapshot. */
 export interface PipelineStepProgressDetail {
+    /** Provenance of a supplied test output, independent of the row status. */
+    outputSource?: "override";
     /** Stable identity for the row (item key, path, job id, …). */
     id: string;
     /** Optional display name; identity remains `id`. */
@@ -112,6 +115,8 @@ export interface PipelineStepProgress {
 export interface PipelineStepContext<TOptions extends object> extends PipelineExecutionContext<TOptions> {
     /** Stable identity for this execution of the current step. */
     attemptId: string;
+    /** Record completed I/O without changing the step output. Calls after the handler settles are ignored. */
+    recordArtifact(record: ArtifactRecord): void;
     /** Emit a retry/attempt trace event for this step when tracing is enabled. */
     reportAttempt(attempt: number, attributes?: PipelineTraceAttributes): void;
     /** Publish the latest progress snapshot for this step. */
@@ -226,6 +231,8 @@ export interface PipelineErrorCause {
     sourceCode?: string;
 }
 interface PipelineStepReportBase {
+    /** Present once a supplied test output enters validation, including failed/cancelled attempts. */
+    outputSource?: "override";
     /** Present when the step started an execution attempt. */
     attemptId?: string;
     id: string;
@@ -327,6 +334,8 @@ export type PipelineStepStatus = {
 } | {
     attemptId: string;
     pipelineId: string;
+    /** Supplied test output; the normal step handler is not executing. */
+    outputSource?: "override";
     progress?: PipelineStepProgress;
     status: "running";
     step: PipelinePlanStep;
@@ -441,8 +450,12 @@ export interface PipelinePlanStep {
     name?: string;
     /** Static child structure when this opaque step executes another pipeline. */
     nestedPipeline?: {
-        /** One child execution or one child execution per runtime item. */
-        mode: "single" | "for-each";
+        /** One child, runtime fan-out, or bounded sequential iteration. */
+        mode: "single" | "for-each" | "iterate";
+        /** Upper bound for a dynamically repeated child. */
+        maxIterations?: number;
+        /** Static child controls, recorded for iteration identity and inspection. */
+        controls?: PipelineRunControls;
         identity?: PipelineDefinitionIdentity;
         concurrency?: number | "dynamic";
         pipelineId: string;
@@ -483,6 +496,15 @@ export interface PipelineMermaidOptions {
     /** Append each operational description to its node label. Defaults to false. */
     includeDescriptions?: boolean;
 }
+type PipelineRunArguments<TOptions, TStepId extends string, TTargetId extends string> = {} extends TOptions ? [
+    options?: TOptions,
+    controls?: PipelineRunControls<TStepId, TTargetId>,
+    context?: Partial<PipelineContext>
+] : [
+    options: TOptions,
+    controls?: PipelineRunControls<TStepId, TTargetId>,
+    context?: Partial<PipelineContext>
+];
 /** Compiled pipeline that can be planned, executed, and rendered as a graph. */
 export interface Pipeline<TOptions extends object, TResult, TStepId extends string = string, TTargetId extends string = TStepId, TId extends string = string> {
     readonly id: TId;
@@ -499,13 +521,16 @@ export interface Pipeline<TOptions extends object, TResult, TStepId extends stri
     /** Stable declared goal ids that support dependency-aware target execution. */
     readonly targetIds: readonly TTargetId[];
     plan(controls?: PipelineRunControls<TStepId, TTargetId>): PipelinePlan;
+    /** Omitted options default to {} when the input type has no required fields. */
     run(options: TOptions, controls?: PipelineRunControls<TStepId, TTargetId>, context?: Partial<PipelineContext>): Promise<PipelineRun<TResult>>;
+    run(...args: PipelineRunArguments<TOptions, TStepId, TTargetId>): Promise<PipelineRun<TResult>>;
     runOrThrow(options: TOptions, controls?: PipelineRunControls<TStepId, TTargetId>, context?: Partial<PipelineContext>): Promise<TResult>;
+    runOrThrow(...args: PipelineRunArguments<TOptions, TStepId, TTargetId>): Promise<TResult>;
     /** Generate a static Mermaid flowchart without running or planning the pipeline. */
     toMermaid(options?: PipelineMermaidOptions): string;
 }
 /** Input accepted by a pipeline run before any options schema transformation. */
-export type PipelineInput<TPipeline extends Pipeline<object, unknown>> = Parameters<TPipeline["run"]>[0];
+export type PipelineInput<TPipeline extends Pipeline<object, unknown>> = Exclude<Parameters<TPipeline["run"]>[0], undefined>;
 /** Successful result produced by a pipeline run. */
 export type PipelineResult<TPipeline extends Pipeline<object, unknown>> = Awaited<ReturnType<TPipeline["runOrThrow"]>>;
 export {};

package/dist/core/pipeline-types.js.map

@@ -1 +1 @@
-{"version":3,"file":"pipeline-types.js","sourceRoot":"","sources":["../../src/core/pipeline-types.ts"],"names":[],"mappings":"AAeA,OAAO,EAAE,oBAAoB,IAAI,0BAA0B,EAAE,MAAM,8BAA8B,CAAC;AA4JlG,yEAAyE;AACzE,MAAM,CAAC,MAAM,oBAAoB,GAAG,MAAM,CAAC,MAAM,CAAC,0BAA0B,CAAC,CAAC;AAK9E,MAAM,oBAAoB,GAAwB,IAAI,GAAG,CAAC,oBAAoB,CAAC,CAAC;AAEhF,qFAAqF;AACrF,MAAM,UAAU,mBAAmB,CAAC,KAAc;IAChD,OAAO,OAAO,KAAK,KAAK,QAAQ,IAAI,oBAAoB,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC;AACtE,CAAC;AA2UD,0DAA0D;AAC1D,MAAM,CAAC,MAAM,2BAA2B,GAAG,CAAC,IAAI,EAAE,IAAI,EAAE,IAAI,EAAE,IAAI,EAAE,IAAI,CAAU,CAAC","sourcesContent":["import type {\n  PipelineDefinitionIdentityContract,\n  PipelineDefinitionSnapshotContract,\n} from \"../tracing/tracing-schema.js\";\n\n/** Versioned graph identity, separate from the optional handler implementation version. */\nexport type PipelineDefinitionIdentity = Readonly<PipelineDefinitionIdentityContract>;\n/** Serializable compiled semantics; no handlers, inputs, or application imports. */\ntype ReadonlyDefinition<T> = T extends object\n  ? { readonly [K in keyof T]: ReadonlyDefinition<T[K]> }\n  : T;\n/** Immutable snapshot of the compiled pipeline definition recorded for inspection and tracing. */\nexport type PipelineDefinitionSnapshot = ReadonlyDefinition<PipelineDefinitionSnapshotContract>;\n\nimport type { RUN_MODEL_VERSION } from \"./pipeline-ids.js\";\nimport { PIPELINE_ERROR_CODES as PIPELINE_ERROR_CODE_VALUES } from \"../tracing/tracing-schema.js\";\nimport type {\n  PipelineErrorKindContract,\n  PipelineErrorPhaseContract,\n} from \"../tracing/tracing-schema.js\";\nimport type {\n  PipelineTraceAttributes,\n  PipelineTraceContext,\n  PipelineTracingOptions,\n} from \"../tracing/tracing-contracts.js\";\n\n/** Minimal logger used by pipeline execution, reporters, and CLI adapters. */\nexport interface PipelineLogger {\n  error(message?: unknown, ...optionalParams: unknown[]): void;\n  log(message?: unknown, ...optionalParams: unknown[]): void;\n  warn(message?: unknown, ...optionalParams: unknown[]): void;\n}\n\n/** Caller-supplied services and metadata shared by one pipeline execution. */\nexport interface PipelineContext {\n  /** Optional caller-owned identifier used to correlate separate executions. */\n  correlationId?: string;\n  cwd: string;\n  /** Hook sets run in order and failures are isolated per set. */\n  hooks?: PipelineHooks | readonly PipelineHooks[];\n  log: PipelineLogger;\n  /** Timestamp source for persisted run records. Defaults to `Date.now`. */\n  now?: () => number;\n  /** Optional package-generated execution identity of this run's parent. */\n  parentRunId?: string;\n  signal?: AbortSignal;\n  sleep?: (durationMs: number, signal?: AbortSignal) => Promise<void>;\n  /** Optional structured lifecycle tracing configuration for this run. */\n  tracing?: PipelineTracingOptions;\n}\n\n/** Built-in run controls. Choose targets or stepIds, or omit both to run every step. */\nexport type PipelineRunControls<\n  TStepId extends string = string,\n  TTargetId extends string = string,\n> = {\n  /** Maximum simultaneous steps, including skip predicates and output validation. Defaults to 1. */\n  maxConcurrency?: number;\n  /** Continue eligible branches after failure; otherwise stop dispatch and drain active steps. */\n  continueOnError?: boolean;\n  dryRun?: boolean;\n} & (\n  | {\n      /**\n       * Run only these steps, without adding prerequisites. Omit both stepIds and\n       * targets to run every step. An empty array is invalid and fails planning.\n       */\n      stepIds?: readonly TStepId[];\n      targets?: undefined;\n    }\n  | {\n      stepIds?: undefined;\n      /**\n       * Run these declared targets and their required inputs and failure gates,\n       * recursively; optional-only inputs are not included. Omit both targets\n       * and stepIds to run every step; no target is selected automatically.\n       */\n      targets?: readonly TTargetId[];\n    }\n);\n\n/** Resolved caller context. Core fills `now` and `sleep` before execution. */\nexport interface PipelineRuntime extends PipelineContext {\n  now: () => number;\n  sleep: (durationMs: number, signal?: AbortSignal) => Promise<void>;\n}\n\n/** Resolved execution context provided to pipeline handlers. */\nexport interface PipelineExecutionContext<TOptions extends object> extends PipelineRuntime {\n  dryRun: boolean;\n  options: TOptions;\n  /** Stable identity for this execution, whether or not tracing is configured. */\n  runId: string;\n  /** Stable identities for this traced run; absent unless `context.tracing` is configured. */\n  trace?: PipelineTraceContext;\n}\n\n/**\n * Lifecycle status displayed for an optional nested progress row.\n *\n * Detail rows are indented under a parent step's progress.\n * Domain-agnostic: mapped children, nested work units, per-file status, etc.\n */\nexport type PipelineStepProgressDetailStatus =\n  | \"cancelled\"\n  | \"completed\"\n  | \"failed\"\n  | \"pending\"\n  | \"running\"\n  | \"skipped\";\n\n/** One optional nested row in a step progress snapshot. */\nexport interface PipelineStepProgressDetail {\n  /** Stable identity for the row (item key, path, job id, …). */\n  id: string;\n  /** Optional display name; identity remains `id`. */\n  name?: string;\n  /** Indentation relative to direct child rows (0). Rows are in tree preorder. */\n  depth?: number;\n  /** Inner work counts, independent of the parent's lifecycle count. */\n  completed?: number;\n  total?: number;\n  /** Short status text shown after the id. */\n  label?: string;\n  /** Controls the detail row symbol. Defaults to `running`. */\n  status?: PipelineStepProgressDetailStatus;\n}\n\n/** Latest progress snapshot reported by a running step. */\nexport interface PipelineStepProgress {\n  /** Work completed so far. Values outside the reported total are allowed but renderers may clamp them. */\n  completed: number;\n  /** Total work when known. Omit for indeterminate progress. */\n  total?: number;\n  /** Optional short status shown next to the step. Prefer one-line summaries. */\n  message?: string;\n  /**\n   * Optional multi-line detail rows for capable reporters (interactive TTY).\n   * Keep the parent `message` as a summary; put per-item status here so high\n   * concurrency does not collapse onto one truncated line.\n   */\n  details?: readonly PipelineStepProgressDetail[];\n}\n\n/** Step execution context with attempt identity and progress reporting helpers. */\nexport interface PipelineStepContext<\n  TOptions extends object,\n> extends PipelineExecutionContext<TOptions> {\n  /** Stable identity for this execution of the current step. */\n  attemptId: string;\n  /** Emit a retry/attempt trace event for this step when tracing is enabled. */\n  reportAttempt(attempt: number, attributes?: PipelineTraceAttributes): void;\n  /** Publish the latest progress snapshot for this step. */\n  reportProgress(progress: PipelineStepProgress): void;\n}\n\n/** Adapter that invokes one step on an external execution engine. */\nexport interface RemoteStepAdapter<TOptions extends object, TPayload, TResult> {\n  /** Presentation only. The kernel never switches on this. */\n  readonly engine: string;\n  /** Function name, workflow type, URL, queue. Presentation only. */\n  readonly target?: string;\n  invoke(payload: TPayload, context: PipelineStepContext<TOptions>): Promise<TResult>;\n}\n\n/** Pipeline lifecycle phase in which an error occurred. */\nexport type PipelineErrorPhase = PipelineErrorPhaseContract;\n\n/** Broad category of a structured pipeline error. */\nexport type PipelineErrorKind = PipelineErrorKindContract;\n\n/** Ordered catalog of every stable package-owned pipeline error code. */\nexport const PIPELINE_ERROR_CODES = Object.freeze(PIPELINE_ERROR_CODE_VALUES);\n\n/** Stable package-owned code for a pipeline error. */\nexport type PipelineErrorCode = (typeof PIPELINE_ERROR_CODES)[number];\n\nconst pipelineErrorCodeSet: ReadonlySet<string> = new Set(PIPELINE_ERROR_CODES);\n\n/** Return whether an unknown value is a stable package-owned pipeline error code. */\nexport function isPipelineErrorCode(value: unknown): value is PipelineErrorCode {\n  return typeof value === \"string\" && pipelineErrorCodeSet.has(value);\n}\n\n/** One dependency-free Standard Schema issue normalized for reports and traces. */\nexport interface PipelineValidationIssue {\n  message: string;\n  path?: readonly (number | string)[];\n}\n\n/** Bounded diagnostics for a failed or cancelled runtime fan-out. */\nexport interface PipelineFanOutFailure {\n  /** Original input position, including when the key is truncated. */\n  index: number;\n  /** At most 1024 UTF-16 code units; do not rerun by key when keyTruncated is true. */\n  key: string;\n  keyTruncated: boolean;\n  cancelled: boolean;\n  error: PipelineErrorCause;\n}\n\n/** Bounded diagnostics collected from a failed or cancelled fan-out step. */\nexport interface PipelineFanOutDiagnostics {\n  /** Failed started items, in input order; at most 32 entries. */\n  failures: readonly PipelineFanOutFailure[];\n  /** Total failed started items, including omitted diagnostics. */\n  failureCount: number;\n  omittedFailureCount: number;\n  /** Scheduler failure is separate and never assigned an item key. */\n  schedulerError?: PipelineErrorCause;\n}\n\n/** Structured, machine-readable error stored in plans, runs, and traces. */\nexport interface PipelineError {\n  /** Present for aggregated fan-out failures; absent for setup errors. */\n  fanOut?: PipelineFanOutDiagnostics;\n  /** Bounded, JSON-safe snapshot of the thrown error's cause chain. */\n  cause?: PipelineErrorCause;\n  code: PipelineErrorCode;\n  kind: PipelineErrorKind;\n  message: string;\n  phase: PipelineErrorPhase;\n  /** Present when a Standard Schema rejected a boundary value. */\n  issues?: readonly PipelineValidationIssue[];\n  stepId?: string;\n  /** Machine-readable code copied from the original thrown error, when present. */\n  sourceCode?: string;\n  stack?: string;\n}\n\n/** Dependency-free subset of the Standard Schema V1 protocol. */\nexport interface StandardSchemaV1<TInput = unknown, TOutput = TInput> {\n  readonly \"~standard\": StandardSchemaV1Props<TInput, TOutput>;\n}\n\n/** Standard Schema V1 metadata and validation contract consumed by Tubeless. */\ninterface StandardSchemaV1Props<TInput = unknown, TOutput = TInput> {\n  /** Optional Standard JSON Schema input converter, used to infer CLI flags. */\n  readonly jsonSchema?: {\n    readonly input: (options: { readonly target: \"draft-2020-12\" }) => Record<string, unknown>;\n  };\n  readonly types?: { readonly input: TInput; readonly output: TOutput };\n  readonly validate: (\n    value: unknown,\n    options?: { readonly libraryOptions?: Record<string, unknown> }\n  ) => StandardSchemaV1Result<TOutput> | Promise<StandardSchemaV1Result<TOutput>>;\n  readonly vendor: string;\n  readonly version: 1;\n}\n\n/** Successful value or validation issues returned by a Standard Schema V1 validator. */\nexport type StandardSchemaV1Result<TOutput> =\n  | { readonly issues?: undefined; readonly value: TOutput }\n  | { readonly issues: readonly StandardSchemaV1Issue[] };\n\n/** Validation issue shape accepted from a Standard Schema V1 validator. */\nexport interface StandardSchemaV1Issue {\n  readonly message: string;\n  readonly path?: readonly (PropertyKey | { readonly key: PropertyKey })[];\n}\n\n/** Infer the accepted input type from a Standard Schema without importing its package. */\nexport type InferSchemaInput<TSchema extends StandardSchemaV1> = NonNullable<\n  TSchema[\"~standard\"][\"types\"]\n>[\"input\"];\n\n/** Infer the validated output type from a Standard Schema without importing its package. */\nexport type InferSchemaOutput<TSchema extends StandardSchemaV1> = NonNullable<\n  TSchema[\"~standard\"][\"types\"]\n>[\"output\"];\n\n/** Bounded JSON-safe snapshot of a thrown value and its cause chain. */\nexport interface PipelineErrorCause {\n  cause?: PipelineErrorCause;\n  message: string;\n  name?: string;\n  /** Machine-readable code copied from this cause, when present. */\n  sourceCode?: string;\n}\n\ninterface PipelineStepReportBase {\n  /** Present when the step started an execution attempt. */\n  attemptId?: string;\n  id: string;\n  /** Optional human-facing display name. Stable machine identity remains `id`. */\n  name?: string;\n  description?: string;\n  /** Wall-clock time when this terminal report was recorded. */\n  finishedAtMs: number;\n  /** Wall-clock time when execution began; absent when the step never started. */\n  startedAtMs?: number;\n}\n\n/** Terminal report for a successfully completed step. */\nexport interface PipelineStepCompleteReport extends PipelineStepReportBase {\n  attemptId: string;\n  startedAtMs: number;\n  status: \"completed\";\n}\n\n/** Terminal report for a structurally or intentionally skipped step. */\nexport interface PipelineStepSkippedReport extends PipelineStepReportBase {\n  /** Dependency that blocked this step, when applicable. */\n  dependencyId?: string;\n  /** Human-readable skip detail, especially for policy and fail-fast skips. */\n  message?: string;\n  reason: PipelineStepSkipReason;\n  status: \"skipped\";\n}\n\n/** Terminal report for a cancelled step. */\nexport interface PipelineStepCancelledReport extends PipelineStepReportBase {\n  error: PipelineError;\n  status: \"cancelled\";\n}\n\n/** Terminal report for a failed step. */\nexport interface PipelineStepFailedReport extends PipelineStepReportBase {\n  attemptId: string;\n  error: PipelineError;\n  startedAtMs: number;\n  status: \"failed\";\n}\n\n/** Terminal state recorded for one step after a run. */\nexport type PipelineStepReport =\n  | PipelineStepCancelledReport\n  | PipelineStepFailedReport\n  | PipelineStepSkippedReport\n  | PipelineStepCompleteReport;\n\n/** Terminal status recorded in a step report. */\nexport type PipelineStepReportStatus = PipelineStepReport[\"status\"];\n\n/** Terminal disposition of a completed run record. */\nexport type PipelineRunStatus = \"cancelled\" | \"completed\" | \"failed\";\n\ninterface PipelineRunRecord {\n  definitionIdentity?: PipelineDefinitionIdentity;\n  /** Caller-owned identifier shared by related executions, when supplied. */\n  correlationId?: string;\n  pipelineId: string;\n  dryRun: boolean;\n  /** Run-level errors first, step errors in plan order, then finalization errors. */\n  errors: PipelineError[];\n  finishedAtMs: number;\n  parentRunId?: string;\n  runId: string;\n  startedAtMs: number;\n  status: PipelineRunStatus;\n  /** Terminal step reports in stable plan order, independent of completion order. */\n  steps: PipelineStepReport[];\n  version: typeof RUN_MODEL_VERSION;\n}\n\n/** Versioned public record returned for one pipeline execution. */\nexport type PipelineRun<TResult = unknown> =\n  | (PipelineRunRecord & {\n      /** Finalization did not produce a result. Independent of terminal run status. */\n      finalized: false;\n      value?: undefined;\n    })\n  | (PipelineRunRecord & {\n      /** Finalization produced a result. Independent of terminal run status. */\n      finalized: true;\n      value: TResult;\n    });\n\n/**\n * Why a step did not run. Built-in structural reasons keep dependency semantics;\n * `\"policy\"` is an intentional skip from `step.skip()` (still unlocks dependents).\n */\nexport type PipelineStepSkipReason =\n  | \"dry-run\"\n  | \"failed-dependency\"\n  | \"fail-fast\"\n  | \"filtered\"\n  | \"policy\"\n  | \"unmet-dependency\";\n\n/**\n * Decision from an optional `skip` predicate.\n * - falsy / `false` → run the step\n * - non-empty string → skip with that message (`reason: \"policy\"`); the step's\n *   published output is `undefined`\n * - `{ reason, value? }` → skip and optionally publish `value` for dependents\n *   (`value` may be intentionally `undefined` if passed explicitly)\n *\n * Policy skips unlock required dependents. A bare-string skip (or a `{ reason }`\n * without `value`) makes dependents see `TOut | undefined`. When every skip\n * branch returns `{ reason, value }`, the step retains `TOut`; schema-backed\n * values use the schema input type and publish its transformed output type.\n */\nexport type StepSkipDecision<TOut = unknown> =\n  | false\n  | null\n  | undefined\n  | string\n  | { reason: string; value?: TOut };\n\n/** One observable status in a step's planned → running → terminal lifecycle. */\nexport type PipelineStepStatus =\n  | { pipelineId: string; status: \"planned\"; step: PipelinePlanStep }\n  | {\n      attemptId: string;\n      pipelineId: string;\n      progress?: PipelineStepProgress;\n      status: \"running\";\n      step: PipelinePlanStep;\n    }\n  | ({ pipelineId: string; step: PipelinePlanStep } & PipelineStepCancelledReport)\n  | ({ pipelineId: string; step: PipelinePlanStep } & PipelineStepFailedReport)\n  | ({ pipelineId: string; step: PipelinePlanStep } & PipelineStepSkippedReport)\n  | ({ pipelineId: string; step: PipelinePlanStep } & PipelineStepCompleteReport);\n\n/** Any planned, running, or terminal step lifecycle status. */\nexport type PipelineStepLifecycleStatus = PipelineStepStatus[\"status\"];\n\n/** Lifecycle event emitted when a step is planned. */\nexport type PipelineStepPlannedEvent = Extract<PipelineStepStatus, { status: \"planned\" }>;\ntype PipelineStepRunningStatus = Extract<PipelineStepStatus, { status: \"running\" }>;\n/** Lifecycle event emitted when a step begins running. */\nexport type PipelineStepStartEvent = Omit<PipelineStepRunningStatus, \"progress\"> & {\n  progress?: undefined;\n};\n/** Lifecycle event emitted when a running step reports progress. */\nexport type PipelineStepProgressEvent = Omit<PipelineStepRunningStatus, \"progress\"> & {\n  progress: PipelineStepProgress;\n};\n/** Lifecycle event emitted when a step is cancelled. */\nexport type PipelineStepCancelledEvent = Extract<PipelineStepStatus, { status: \"cancelled\" }>;\n/** Lifecycle event emitted when a step fails. */\nexport type PipelineStepFailedEvent = Extract<PipelineStepStatus, { status: \"failed\" }>;\n/** Lifecycle event emitted when a step is skipped. */\nexport type PipelineStepSkippedEvent = Extract<PipelineStepStatus, { status: \"skipped\" }>;\n/** Lifecycle event emitted when a step completes successfully. */\nexport type PipelineStepCompleteEvent = Extract<PipelineStepStatus, { status: \"completed\" }>;\n\n/**\n * Optional lifecycle callbacks, each receiving its own metadata snapshot.\n * Domain result values retain their identity; hooks must treat them as read-only.\n */\nexport interface PipelineHooks<TResult = unknown> {\n  onFinalizeComplete?(event: { durationMs: number; pipelineId: string; value: TResult }): void;\n  onFinalizeError?(event: { durationMs: number; error: PipelineError; pipelineId: string }): void;\n  onFinalizeStart?(event: { pipelineId: string }): void;\n  onPipelineComplete?(event: PipelineRun<TResult>): void;\n  onPipelineStart?(event: PipelinePlan): void;\n  onStepCancel?(event: PipelineStepCancelledEvent): void;\n  onStepFail?(event: PipelineStepFailedEvent): void;\n  onStepPlan?(event: PipelineStepPlannedEvent): void;\n  onStepProgress?(event: PipelineStepProgressEvent): void;\n  onStepSkip?(event: PipelineStepSkippedEvent): void;\n  onStepStart?(event: PipelineStepStartEvent): void;\n  onStepStatus?(event: PipelineStepStatus): void;\n  onStepComplete?(event: PipelineStepCompleteEvent): void;\n}\n\n/** Machine-readable explanation of why a planned step was included or omitted. */\nexport type PipelineStepSelectionReason =\n  | { kind: \"all\" }\n  | { kind: \"exact\" }\n  | { kind: \"target\"; targetId: string }\n  | { dependentId: string; kind: \"required-dependency\"; targetId: string }\n  | { dependentId: string; kind: \"failure-gate\"; targetId: string }\n  | { dependentId: string; kind: \"optional-only\"; targetId: string }\n  | { kind: \"outside-target-closure\" }\n  | { kind: \"not-selected\" };\n\n/** Planned representation of one declared step and its selection state. */\nexport interface PipelinePlanStep {\n  dependencies: string[];\n  description?: string;\n  /** How this step behaves when the pipeline is run with `dryRun: true`. */\n  dryRun: \"custom\" | \"run\" | \"skip\";\n  id: string;\n  /** Optional human-facing display name. Stable machine identity remains `id`. */\n  name?: string;\n  /** Static child structure when this opaque step executes another pipeline. */\n  nestedPipeline?: {\n    /** One child execution or one child execution per runtime item. */\n    mode: \"single\" | \"for-each\";\n    identity?: PipelineDefinitionIdentity;\n    concurrency?: number | \"dynamic\";\n    pipelineId: string;\n    /** All declared child step ids; runtime selection may execute only a subset. */\n    stepIds: readonly string[];\n  };\n  /** Static remote adapter metadata when this opaque step calls an external engine. */\n  remote?: {\n    engine: string;\n    target?: string;\n  };\n  optionalDependencies: string[];\n  /** True when the step's runtime policy may elect not to run it. */\n  runtimeSkipPossible: boolean;\n  selected: boolean;\n  /** Stable reasons for selection or omission; shared prerequisites can have several. */\n  selectionReasons: readonly PipelineStepSelectionReason[];\n  skipAfterFailureOf: string[];\n  skipReason?: PipelineStepSkipReason;\n}\n\n/** Side-effect-free validation and selection result for a pipeline run. */\nexport interface PipelinePlan {\n  definition?: PipelineDefinitionSnapshot;\n  dryRun: boolean;\n  errors: PipelineError[];\n  ok: boolean;\n  pipelineId: string;\n  steps: PipelinePlanStep[];\n}\n\n/** Layout directions for generated Mermaid flowcharts. */\nexport const PIPELINE_MERMAID_DIRECTIONS = [\"BT\", \"LR\", \"RL\", \"TB\", \"TD\"] as const;\n/** Supported Mermaid flowchart direction. */\nexport type PipelineMermaidDirection = (typeof PIPELINE_MERMAID_DIRECTIONS)[number];\n\n/** Rendering options for a pipeline Mermaid flowchart. */\nexport interface PipelineMermaidOptions {\n  /** Mermaid flowchart direction. Defaults to top-down (`TD`). */\n  direction?: PipelineMermaidDirection;\n  /** Append each operational description to its node label. Defaults to false. */\n  includeDescriptions?: boolean;\n}\n\n/** Compiled pipeline that can be planned, executed, and rendered as a graph. */\nexport interface Pipeline<\n  TOptions extends object,\n  TResult,\n  TStepId extends string = string,\n  TTargetId extends string = TStepId,\n  TId extends string = string,\n> {\n  readonly id: TId;\n  /** Optional display name; stable identity remains `id`. */\n  readonly name?: string;\n  /** Human-readable purpose for command and discovery surfaces. */\n  readonly description?: string;\n  /** Compiled definition metadata. Absent only on externally implemented pipelines. */\n  readonly definition?: PipelineDefinitionSnapshot;\n  /** Runtime domain schema supplied to createSteps; CLI adapters can infer its input flags. */\n  readonly optionsSchema?: StandardSchemaV1;\n  /** Stable definition-order step ids for discovery surfaces such as CLI help. */\n  readonly stepIds: readonly TStepId[];\n  /** Stable declared goal ids that support dependency-aware target execution. */\n  readonly targetIds: readonly TTargetId[];\n  plan(controls?: PipelineRunControls<TStepId, TTargetId>): PipelinePlan;\n  run(\n    options: TOptions,\n    controls?: PipelineRunControls<TStepId, TTargetId>,\n    context?: Partial<PipelineContext>\n  ): Promise<PipelineRun<TResult>>;\n  runOrThrow(\n    options: TOptions,\n    controls?: PipelineRunControls<TStepId, TTargetId>,\n    context?: Partial<PipelineContext>\n  ): Promise<TResult>;\n  /** Generate a static Mermaid flowchart without running or planning the pipeline. */\n  toMermaid(options?: PipelineMermaidOptions): string;\n}\n\n/** Input accepted by a pipeline run before any options schema transformation. */\nexport type PipelineInput<TPipeline extends Pipeline<object, unknown>> = Parameters<\n  TPipeline[\"run\"]\n>[0];\n\n/** Successful result produced by a pipeline run. */\nexport type PipelineResult<TPipeline extends Pipeline<object, unknown>> = Awaited<\n  ReturnType<TPipeline[\"runOrThrow\"]>\n>;\n"]}
+{"version":3,"file":"pipeline-types.js","sourceRoot":"","sources":["../../src/core/pipeline-types.ts"],"names":[],"mappings":"AAgBA,OAAO,EAAE,oBAAoB,IAAI,0BAA0B,EAAE,MAAM,8BAA8B,CAAC;AAgKlG,yEAAyE;AACzE,MAAM,CAAC,MAAM,oBAAoB,GAAG,MAAM,CAAC,MAAM,CAAC,0BAA0B,CAAC,CAAC;AAK9E,MAAM,oBAAoB,GAAwB,IAAI,GAAG,CAAC,oBAAoB,CAAC,CAAC;AAEhF,qFAAqF;AACrF,MAAM,UAAU,mBAAmB,CAAC,KAAc;IAChD,OAAO,OAAO,KAAK,KAAK,QAAQ,IAAI,oBAAoB,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC;AACtE,CAAC;AAmVD,0DAA0D;AAC1D,MAAM,CAAC,MAAM,2BAA2B,GAAG,CAAC,IAAI,EAAE,IAAI,EAAE,IAAI,EAAE,IAAI,EAAE,IAAI,CAAU,CAAC","sourcesContent":["import type { ArtifactRecord } from \"../tracing/artifact-metadata.js\";\nimport type {\n  PipelineDefinitionIdentityContract,\n  PipelineDefinitionSnapshotContract,\n} from \"../tracing/tracing-schema.js\";\n\n/** Versioned graph identity, separate from the optional handler implementation version. */\nexport type PipelineDefinitionIdentity = Readonly<PipelineDefinitionIdentityContract>;\n/** Serializable compiled semantics; no handlers, inputs, or application imports. */\ntype ReadonlyDefinition<T> = T extends object\n  ? { readonly [K in keyof T]: ReadonlyDefinition<T[K]> }\n  : T;\n/** Immutable snapshot of the compiled pipeline definition recorded for inspection and tracing. */\nexport type PipelineDefinitionSnapshot = ReadonlyDefinition<PipelineDefinitionSnapshotContract>;\n\nimport type { RUN_MODEL_VERSION } from \"./pipeline-ids.js\";\nimport { PIPELINE_ERROR_CODES as PIPELINE_ERROR_CODE_VALUES } from \"../tracing/tracing-schema.js\";\nimport type {\n  PipelineErrorKindContract,\n  PipelineErrorPhaseContract,\n} from \"../tracing/tracing-schema.js\";\nimport type {\n  PipelineTraceAttributes,\n  PipelineTraceContext,\n  PipelineTracingOptions,\n} from \"../tracing/tracing-contracts.js\";\n\n/** Minimal logger used by pipeline execution, reporters, and CLI adapters. */\nexport interface PipelineLogger {\n  error(message?: unknown, ...optionalParams: unknown[]): void;\n  log(message?: unknown, ...optionalParams: unknown[]): void;\n  warn(message?: unknown, ...optionalParams: unknown[]): void;\n}\n\n/** Caller-supplied services and metadata shared by one pipeline execution. */\nexport interface PipelineContext {\n  /** Optional caller-owned identifier used to correlate separate executions. */\n  correlationId?: string;\n  cwd: string;\n  /** Hook sets run in order and failures are isolated per set. */\n  hooks?: PipelineHooks | readonly PipelineHooks[];\n  log: PipelineLogger;\n  /** Timestamp source for persisted run records. Defaults to `Date.now`. */\n  now?: () => number;\n  /** Optional package-generated execution identity of this run's parent. */\n  parentRunId?: string;\n  signal?: AbortSignal;\n  sleep?: (durationMs: number, signal?: AbortSignal) => Promise<void>;\n  /** Optional structured lifecycle tracing configuration for this run. */\n  tracing?: PipelineTracingOptions;\n}\n\n/** Built-in run controls. Choose targets or stepIds, or omit both to run every step. */\nexport type PipelineRunControls<\n  TStepId extends string = string,\n  TTargetId extends string = string,\n> = {\n  /** Maximum simultaneous steps, including skip predicates and output validation. Defaults to 1. */\n  maxConcurrency?: number;\n  /** Continue eligible branches after failure; otherwise stop dispatch and drain active steps. */\n  continueOnError?: boolean;\n  dryRun?: boolean;\n} & (\n  | {\n      /**\n       * Run only these steps, without adding prerequisites. Omit both stepIds and\n       * targets to run every step. An empty array is invalid and fails planning.\n       */\n      stepIds?: readonly TStepId[];\n      targets?: undefined;\n    }\n  | {\n      stepIds?: undefined;\n      /**\n       * Run these declared targets and their required inputs and failure gates,\n       * recursively; optional-only inputs are not included. Omit both targets\n       * and stepIds to run every step; no target is selected automatically.\n       */\n      targets?: readonly TTargetId[];\n    }\n);\n\n/** Resolved caller context. Core fills `now` and `sleep` before execution. */\nexport interface PipelineRuntime extends PipelineContext {\n  now: () => number;\n  sleep: (durationMs: number, signal?: AbortSignal) => Promise<void>;\n}\n\n/** Resolved execution context provided to pipeline handlers. */\nexport interface PipelineExecutionContext<TOptions extends object> extends PipelineRuntime {\n  dryRun: boolean;\n  options: TOptions;\n  /** Stable identity for this execution, whether or not tracing is configured. */\n  runId: string;\n  /** Stable identities for this traced run; absent unless `context.tracing` is configured. */\n  trace?: PipelineTraceContext;\n}\n\n/**\n * Lifecycle status displayed for an optional nested progress row.\n *\n * Detail rows are indented under a parent step's progress.\n * Domain-agnostic: mapped children, nested work units, per-file status, etc.\n */\nexport type PipelineStepProgressDetailStatus =\n  | \"cancelled\"\n  | \"completed\"\n  | \"failed\"\n  | \"pending\"\n  | \"running\"\n  | \"skipped\";\n\n/** One optional nested row in a step progress snapshot. */\nexport interface PipelineStepProgressDetail {\n  /** Provenance of a supplied test output, independent of the row status. */\n  outputSource?: \"override\";\n  /** Stable identity for the row (item key, path, job id, …). */\n  id: string;\n  /** Optional display name; identity remains `id`. */\n  name?: string;\n  /** Indentation relative to direct child rows (0). Rows are in tree preorder. */\n  depth?: number;\n  /** Inner work counts, independent of the parent's lifecycle count. */\n  completed?: number;\n  total?: number;\n  /** Short status text shown after the id. */\n  label?: string;\n  /** Controls the detail row symbol. Defaults to `running`. */\n  status?: PipelineStepProgressDetailStatus;\n}\n\n/** Latest progress snapshot reported by a running step. */\nexport interface PipelineStepProgress {\n  /** Work completed so far. Values outside the reported total are allowed but renderers may clamp them. */\n  completed: number;\n  /** Total work when known. Omit for indeterminate progress. */\n  total?: number;\n  /** Optional short status shown next to the step. Prefer one-line summaries. */\n  message?: string;\n  /**\n   * Optional multi-line detail rows for capable reporters (interactive TTY).\n   * Keep the parent `message` as a summary; put per-item status here so high\n   * concurrency does not collapse onto one truncated line.\n   */\n  details?: readonly PipelineStepProgressDetail[];\n}\n\n/** Step execution context with attempt identity and progress reporting helpers. */\nexport interface PipelineStepContext<\n  TOptions extends object,\n> extends PipelineExecutionContext<TOptions> {\n  /** Stable identity for this execution of the current step. */\n  attemptId: string;\n  /** Record completed I/O without changing the step output. Calls after the handler settles are ignored. */\n  recordArtifact(record: ArtifactRecord): void;\n  /** Emit a retry/attempt trace event for this step when tracing is enabled. */\n  reportAttempt(attempt: number, attributes?: PipelineTraceAttributes): void;\n  /** Publish the latest progress snapshot for this step. */\n  reportProgress(progress: PipelineStepProgress): void;\n}\n\n/** Adapter that invokes one step on an external execution engine. */\nexport interface RemoteStepAdapter<TOptions extends object, TPayload, TResult> {\n  /** Presentation only. The kernel never switches on this. */\n  readonly engine: string;\n  /** Function name, workflow type, URL, queue. Presentation only. */\n  readonly target?: string;\n  invoke(payload: TPayload, context: PipelineStepContext<TOptions>): Promise<TResult>;\n}\n\n/** Pipeline lifecycle phase in which an error occurred. */\nexport type PipelineErrorPhase = PipelineErrorPhaseContract;\n\n/** Broad category of a structured pipeline error. */\nexport type PipelineErrorKind = PipelineErrorKindContract;\n\n/** Ordered catalog of every stable package-owned pipeline error code. */\nexport const PIPELINE_ERROR_CODES = Object.freeze(PIPELINE_ERROR_CODE_VALUES);\n\n/** Stable package-owned code for a pipeline error. */\nexport type PipelineErrorCode = (typeof PIPELINE_ERROR_CODES)[number];\n\nconst pipelineErrorCodeSet: ReadonlySet<string> = new Set(PIPELINE_ERROR_CODES);\n\n/** Return whether an unknown value is a stable package-owned pipeline error code. */\nexport function isPipelineErrorCode(value: unknown): value is PipelineErrorCode {\n  return typeof value === \"string\" && pipelineErrorCodeSet.has(value);\n}\n\n/** One dependency-free Standard Schema issue normalized for reports and traces. */\nexport interface PipelineValidationIssue {\n  message: string;\n  path?: readonly (number | string)[];\n}\n\n/** Bounded diagnostics for a failed or cancelled runtime fan-out. */\nexport interface PipelineFanOutFailure {\n  /** Original input position, including when the key is truncated. */\n  index: number;\n  /** At most 1024 UTF-16 code units; do not rerun by key when keyTruncated is true. */\n  key: string;\n  keyTruncated: boolean;\n  cancelled: boolean;\n  error: PipelineErrorCause;\n}\n\n/** Bounded diagnostics collected from a failed or cancelled fan-out step. */\nexport interface PipelineFanOutDiagnostics {\n  /** Failed started items, in input order; at most 32 entries. */\n  failures: readonly PipelineFanOutFailure[];\n  /** Total failed started items, including omitted diagnostics. */\n  failureCount: number;\n  omittedFailureCount: number;\n  /** Scheduler failure is separate and never assigned an item key. */\n  schedulerError?: PipelineErrorCause;\n}\n\n/** Structured, machine-readable error stored in plans, runs, and traces. */\nexport interface PipelineError {\n  /** Present for aggregated fan-out failures; absent for setup errors. */\n  fanOut?: PipelineFanOutDiagnostics;\n  /** Bounded, JSON-safe snapshot of the thrown error's cause chain. */\n  cause?: PipelineErrorCause;\n  code: PipelineErrorCode;\n  kind: PipelineErrorKind;\n  message: string;\n  phase: PipelineErrorPhase;\n  /** Present when a Standard Schema rejected a boundary value. */\n  issues?: readonly PipelineValidationIssue[];\n  stepId?: string;\n  /** Machine-readable code copied from the original thrown error, when present. */\n  sourceCode?: string;\n  stack?: string;\n}\n\n/** Dependency-free subset of the Standard Schema V1 protocol. */\nexport interface StandardSchemaV1<TInput = unknown, TOutput = TInput> {\n  readonly \"~standard\": StandardSchemaV1Props<TInput, TOutput>;\n}\n\n/** Standard Schema V1 metadata and validation contract consumed by Tubeless. */\ninterface StandardSchemaV1Props<TInput = unknown, TOutput = TInput> {\n  /** Optional Standard JSON Schema input converter, used to infer CLI flags. */\n  readonly jsonSchema?: {\n    readonly input: (options: { readonly target: \"draft-2020-12\" }) => Record<string, unknown>;\n  };\n  readonly types?: { readonly input: TInput; readonly output: TOutput };\n  readonly validate: (\n    value: unknown,\n    options?: { readonly libraryOptions?: Record<string, unknown> }\n  ) => StandardSchemaV1Result<TOutput> | Promise<StandardSchemaV1Result<TOutput>>;\n  readonly vendor: string;\n  readonly version: 1;\n}\n\n/** Successful value or validation issues returned by a Standard Schema V1 validator. */\nexport type StandardSchemaV1Result<TOutput> =\n  | { readonly issues?: undefined; readonly value: TOutput }\n  | { readonly issues: readonly StandardSchemaV1Issue[] };\n\n/** Validation issue shape accepted from a Standard Schema V1 validator. */\nexport interface StandardSchemaV1Issue {\n  readonly message: string;\n  readonly path?: readonly (PropertyKey | { readonly key: PropertyKey })[];\n}\n\n/** Infer the accepted input type from a Standard Schema without importing its package. */\nexport type InferSchemaInput<TSchema extends StandardSchemaV1> = NonNullable<\n  TSchema[\"~standard\"][\"types\"]\n>[\"input\"];\n\n/** Infer the validated output type from a Standard Schema without importing its package. */\nexport type InferSchemaOutput<TSchema extends StandardSchemaV1> = NonNullable<\n  TSchema[\"~standard\"][\"types\"]\n>[\"output\"];\n\n/** Bounded JSON-safe snapshot of a thrown value and its cause chain. */\nexport interface PipelineErrorCause {\n  cause?: PipelineErrorCause;\n  message: string;\n  name?: string;\n  /** Machine-readable code copied from this cause, when present. */\n  sourceCode?: string;\n}\n\ninterface PipelineStepReportBase {\n  /** Present once a supplied test output enters validation, including failed/cancelled attempts. */\n  outputSource?: \"override\";\n  /** Present when the step started an execution attempt. */\n  attemptId?: string;\n  id: string;\n  /** Optional human-facing display name. Stable machine identity remains `id`. */\n  name?: string;\n  description?: string;\n  /** Wall-clock time when this terminal report was recorded. */\n  finishedAtMs: number;\n  /** Wall-clock time when execution began; absent when the step never started. */\n  startedAtMs?: number;\n}\n\n/** Terminal report for a successfully completed step. */\nexport interface PipelineStepCompleteReport extends PipelineStepReportBase {\n  attemptId: string;\n  startedAtMs: number;\n  status: \"completed\";\n}\n\n/** Terminal report for a structurally or intentionally skipped step. */\nexport interface PipelineStepSkippedReport extends PipelineStepReportBase {\n  /** Dependency that blocked this step, when applicable. */\n  dependencyId?: string;\n  /** Human-readable skip detail, especially for policy and fail-fast skips. */\n  message?: string;\n  reason: PipelineStepSkipReason;\n  status: \"skipped\";\n}\n\n/** Terminal report for a cancelled step. */\nexport interface PipelineStepCancelledReport extends PipelineStepReportBase {\n  error: PipelineError;\n  status: \"cancelled\";\n}\n\n/** Terminal report for a failed step. */\nexport interface PipelineStepFailedReport extends PipelineStepReportBase {\n  attemptId: string;\n  error: PipelineError;\n  startedAtMs: number;\n  status: \"failed\";\n}\n\n/** Terminal state recorded for one step after a run. */\nexport type PipelineStepReport =\n  | PipelineStepCancelledReport\n  | PipelineStepFailedReport\n  | PipelineStepSkippedReport\n  | PipelineStepCompleteReport;\n\n/** Terminal status recorded in a step report. */\nexport type PipelineStepReportStatus = PipelineStepReport[\"status\"];\n\n/** Terminal disposition of a completed run record. */\nexport type PipelineRunStatus = \"cancelled\" | \"completed\" | \"failed\";\n\ninterface PipelineRunRecord {\n  definitionIdentity?: PipelineDefinitionIdentity;\n  /** Caller-owned identifier shared by related executions, when supplied. */\n  correlationId?: string;\n  pipelineId: string;\n  dryRun: boolean;\n  /** Run-level errors first, step errors in plan order, then finalization errors. */\n  errors: PipelineError[];\n  finishedAtMs: number;\n  parentRunId?: string;\n  runId: string;\n  startedAtMs: number;\n  status: PipelineRunStatus;\n  /** Terminal step reports in stable plan order, independent of completion order. */\n  steps: PipelineStepReport[];\n  version: typeof RUN_MODEL_VERSION;\n}\n\n/** Versioned public record returned for one pipeline execution. */\nexport type PipelineRun<TResult = unknown> =\n  | (PipelineRunRecord & {\n      /** Finalization did not produce a result. Independent of terminal run status. */\n      finalized: false;\n      value?: undefined;\n    })\n  | (PipelineRunRecord & {\n      /** Finalization produced a result. Independent of terminal run status. */\n      finalized: true;\n      value: TResult;\n    });\n\n/**\n * Why a step did not run. Built-in structural reasons keep dependency semantics;\n * `\"policy\"` is an intentional skip from `step.skip()` (still unlocks dependents).\n */\nexport type PipelineStepSkipReason =\n  | \"dry-run\"\n  | \"failed-dependency\"\n  | \"fail-fast\"\n  | \"filtered\"\n  | \"policy\"\n  | \"unmet-dependency\";\n\n/**\n * Decision from an optional `skip` predicate.\n * - falsy / `false` → run the step\n * - non-empty string → skip with that message (`reason: \"policy\"`); the step's\n *   published output is `undefined`\n * - `{ reason, value? }` → skip and optionally publish `value` for dependents\n *   (`value` may be intentionally `undefined` if passed explicitly)\n *\n * Policy skips unlock required dependents. A bare-string skip (or a `{ reason }`\n * without `value`) makes dependents see `TOut | undefined`. When every skip\n * branch returns `{ reason, value }`, the step retains `TOut`; schema-backed\n * values use the schema input type and publish its transformed output type.\n */\nexport type StepSkipDecision<TOut = unknown> =\n  | false\n  | null\n  | undefined\n  | string\n  | { reason: string; value?: TOut };\n\n/** One observable status in a step's planned → running → terminal lifecycle. */\nexport type PipelineStepStatus =\n  | { pipelineId: string; status: \"planned\"; step: PipelinePlanStep }\n  | {\n      attemptId: string;\n      pipelineId: string;\n      /** Supplied test output; the normal step handler is not executing. */\n      outputSource?: \"override\";\n      progress?: PipelineStepProgress;\n      status: \"running\";\n      step: PipelinePlanStep;\n    }\n  | ({ pipelineId: string; step: PipelinePlanStep } & PipelineStepCancelledReport)\n  | ({ pipelineId: string; step: PipelinePlanStep } & PipelineStepFailedReport)\n  | ({ pipelineId: string; step: PipelinePlanStep } & PipelineStepSkippedReport)\n  | ({ pipelineId: string; step: PipelinePlanStep } & PipelineStepCompleteReport);\n\n/** Any planned, running, or terminal step lifecycle status. */\nexport type PipelineStepLifecycleStatus = PipelineStepStatus[\"status\"];\n\n/** Lifecycle event emitted when a step is planned. */\nexport type PipelineStepPlannedEvent = Extract<PipelineStepStatus, { status: \"planned\" }>;\ntype PipelineStepRunningStatus = Extract<PipelineStepStatus, { status: \"running\" }>;\n/** Lifecycle event emitted when a step begins running. */\nexport type PipelineStepStartEvent = Omit<PipelineStepRunningStatus, \"progress\"> & {\n  progress?: undefined;\n};\n/** Lifecycle event emitted when a running step reports progress. */\nexport type PipelineStepProgressEvent = Omit<PipelineStepRunningStatus, \"progress\"> & {\n  progress: PipelineStepProgress;\n};\n/** Lifecycle event emitted when a step is cancelled. */\nexport type PipelineStepCancelledEvent = Extract<PipelineStepStatus, { status: \"cancelled\" }>;\n/** Lifecycle event emitted when a step fails. */\nexport type PipelineStepFailedEvent = Extract<PipelineStepStatus, { status: \"failed\" }>;\n/** Lifecycle event emitted when a step is skipped. */\nexport type PipelineStepSkippedEvent = Extract<PipelineStepStatus, { status: \"skipped\" }>;\n/** Lifecycle event emitted when a step completes successfully. */\nexport type PipelineStepCompleteEvent = Extract<PipelineStepStatus, { status: \"completed\" }>;\n\n/**\n * Optional lifecycle callbacks, each receiving its own metadata snapshot.\n * Domain result values retain their identity; hooks must treat them as read-only.\n */\nexport interface PipelineHooks<TResult = unknown> {\n  onFinalizeComplete?(event: { durationMs: number; pipelineId: string; value: TResult }): void;\n  onFinalizeError?(event: { durationMs: number; error: PipelineError; pipelineId: string }): void;\n  onFinalizeStart?(event: { pipelineId: string }): void;\n  onPipelineComplete?(event: PipelineRun<TResult>): void;\n  onPipelineStart?(event: PipelinePlan): void;\n  onStepCancel?(event: PipelineStepCancelledEvent): void;\n  onStepFail?(event: PipelineStepFailedEvent): void;\n  onStepPlan?(event: PipelineStepPlannedEvent): void;\n  onStepProgress?(event: PipelineStepProgressEvent): void;\n  onStepSkip?(event: PipelineStepSkippedEvent): void;\n  onStepStart?(event: PipelineStepStartEvent): void;\n  onStepStatus?(event: PipelineStepStatus): void;\n  onStepComplete?(event: PipelineStepCompleteEvent): void;\n}\n\n/** Machine-readable explanation of why a planned step was included or omitted. */\nexport type PipelineStepSelectionReason =\n  | { kind: \"all\" }\n  | { kind: \"exact\" }\n  | { kind: \"target\"; targetId: string }\n  | { dependentId: string; kind: \"required-dependency\"; targetId: string }\n  | { dependentId: string; kind: \"failure-gate\"; targetId: string }\n  | { dependentId: string; kind: \"optional-only\"; targetId: string }\n  | { kind: \"outside-target-closure\" }\n  | { kind: \"not-selected\" };\n\n/** Planned representation of one declared step and its selection state. */\nexport interface PipelinePlanStep {\n  dependencies: string[];\n  description?: string;\n  /** How this step behaves when the pipeline is run with `dryRun: true`. */\n  dryRun: \"custom\" | \"run\" | \"skip\";\n  id: string;\n  /** Optional human-facing display name. Stable machine identity remains `id`. */\n  name?: string;\n  /** Static child structure when this opaque step executes another pipeline. */\n  nestedPipeline?: {\n    /** One child, runtime fan-out, or bounded sequential iteration. */\n    mode: \"single\" | \"for-each\" | \"iterate\";\n    /** Upper bound for a dynamically repeated child. */\n    maxIterations?: number;\n    /** Static child controls, recorded for iteration identity and inspection. */\n    controls?: PipelineRunControls;\n    identity?: PipelineDefinitionIdentity;\n    concurrency?: number | \"dynamic\";\n    pipelineId: string;\n    /** All declared child step ids; runtime selection may execute only a subset. */\n    stepIds: readonly string[];\n  };\n  /** Static remote adapter metadata when this opaque step calls an external engine. */\n  remote?: {\n    engine: string;\n    target?: string;\n  };\n  optionalDependencies: string[];\n  /** True when the step's runtime policy may elect not to run it. */\n  runtimeSkipPossible: boolean;\n  selected: boolean;\n  /** Stable reasons for selection or omission; shared prerequisites can have several. */\n  selectionReasons: readonly PipelineStepSelectionReason[];\n  skipAfterFailureOf: string[];\n  skipReason?: PipelineStepSkipReason;\n}\n\n/** Side-effect-free validation and selection result for a pipeline run. */\nexport interface PipelinePlan {\n  definition?: PipelineDefinitionSnapshot;\n  dryRun: boolean;\n  errors: PipelineError[];\n  ok: boolean;\n  pipelineId: string;\n  steps: PipelinePlanStep[];\n}\n\n/** Layout directions for generated Mermaid flowcharts. */\nexport const PIPELINE_MERMAID_DIRECTIONS = [\"BT\", \"LR\", \"RL\", \"TB\", \"TD\"] as const;\n/** Supported Mermaid flowchart direction. */\nexport type PipelineMermaidDirection = (typeof PIPELINE_MERMAID_DIRECTIONS)[number];\n\n/** Rendering options for a pipeline Mermaid flowchart. */\nexport interface PipelineMermaidOptions {\n  /** Mermaid flowchart direction. Defaults to top-down (`TD`). */\n  direction?: PipelineMermaidDirection;\n  /** Append each operational description to its node label. Defaults to false. */\n  includeDescriptions?: boolean;\n}\n\ntype PipelineRunArguments<\n  TOptions,\n  TStepId extends string,\n  TTargetId extends string,\n> = {} extends TOptions\n  ? [\n      options?: TOptions,\n      controls?: PipelineRunControls<TStepId, TTargetId>,\n      context?: Partial<PipelineContext>,\n    ]\n  : [\n      options: TOptions,\n      controls?: PipelineRunControls<TStepId, TTargetId>,\n      context?: Partial<PipelineContext>,\n    ];\n\n/** Compiled pipeline that can be planned, executed, and rendered as a graph. */\nexport interface Pipeline<\n  TOptions extends object,\n  TResult,\n  TStepId extends string = string,\n  TTargetId extends string = TStepId,\n  TId extends string = string,\n> {\n  readonly id: TId;\n  /** Optional display name; stable identity remains `id`. */\n  readonly name?: string;\n  /** Human-readable purpose for command and discovery surfaces. */\n  readonly description?: string;\n  /** Compiled definition metadata. Absent only on externally implemented pipelines. */\n  readonly definition?: PipelineDefinitionSnapshot;\n  /** Runtime domain schema supplied to createSteps; CLI adapters can infer its input flags. */\n  readonly optionsSchema?: StandardSchemaV1;\n  /** Stable definition-order step ids for discovery surfaces such as CLI help. */\n  readonly stepIds: readonly TStepId[];\n  /** Stable declared goal ids that support dependency-aware target execution. */\n  readonly targetIds: readonly TTargetId[];\n  plan(controls?: PipelineRunControls<TStepId, TTargetId>): PipelinePlan;\n  /** Omitted options default to {} when the input type has no required fields. */\n  run(\n    options: TOptions,\n    controls?: PipelineRunControls<TStepId, TTargetId>,\n    context?: Partial<PipelineContext>\n  ): Promise<PipelineRun<TResult>>;\n  run(...args: PipelineRunArguments<TOptions, TStepId, TTargetId>): Promise<PipelineRun<TResult>>;\n  runOrThrow(\n    options: TOptions,\n    controls?: PipelineRunControls<TStepId, TTargetId>,\n    context?: Partial<PipelineContext>\n  ): Promise<TResult>;\n  runOrThrow(...args: PipelineRunArguments<TOptions, TStepId, TTargetId>): Promise<TResult>;\n  /** Generate a static Mermaid flowchart without running or planning the pipeline. */\n  toMermaid(options?: PipelineMermaidOptions): string;\n}\n\n/** Input accepted by a pipeline run before any options schema transformation. */\nexport type PipelineInput<TPipeline extends Pipeline<object, unknown>> = Exclude<\n  Parameters<TPipeline[\"run\"]>[0],\n  undefined\n>;\n\n/** Successful result produced by a pipeline run. */\nexport type PipelineResult<TPipeline extends Pipeline<object, unknown>> = Awaited<\n  ReturnType<TPipeline[\"runOrThrow\"]>\n>;\n"]}

package/dist/core/pipeline.d.ts

@@ -1,4 +1,4 @@
-import { PipelineExecutionError } from "./pipeline-execute.js";
+import { PipelineExecutionError } from "./pipeline-execution-error.js";
 import { RUN_MODEL_VERSION } from "./pipeline-ids.js";
 import type { DefaultPipelineResult, DefaultPipelineTargets, PipelineDefinition, StepIds, StepsInputOptions, StepsOptionsSchema, TargetIds } from "./pipeline-definition.js";
 import { PipelineDefinitionError } from "./pipeline-errors.js";
@@ -8,6 +8,7 @@ import type { InferSchemaOutput, Pipeline, PipelineDefinitionSnapshot, StandardS
 export { PipelineExecutionError, RUN_MODEL_VERSION };
 export { isPipelineErrorCode, PIPELINE_ERROR_CODES } from "./pipeline-types.js";
 export { createSteps } from "./pipeline-steps.js";
+export type { IterationDecision, IterationState } from "./iteration.js";
 export { PipelineDefinitionError, requireOutputs };
 export type { PipelineDefinitionIdentity, PipelineDefinitionSnapshot, PipelineLogger, PipelineContext, PipelineRunControls, PipelineExecutionContext, PipelineStepProgressDetailStatus, PipelineStepProgressDetail, PipelineStepProgress, PipelineStepContext, RemoteStepAdapter, PipelineErrorPhase, PipelineErrorKind, PipelineErrorCode, PipelineValidationIssue, PipelineError, PipelineFanOutDiagnostics, PipelineFanOutFailure, StandardSchemaV1, PipelineErrorCause, PipelineStepCompleteReport, PipelineStepSkippedReport, PipelineStepCancelledReport, PipelineStepFailedReport, PipelineStepReport, PipelineStepReportStatus, PipelineRunStatus, PipelineRun, PipelineStepSkipReason, StepSkipDecision, PipelineStepStatus, PipelineStepLifecycleStatus, PipelineStepPlannedEvent, PipelineStepStartEvent, PipelineStepProgressEvent, PipelineStepCancelledEvent, PipelineStepFailedEvent, PipelineStepSkippedEvent, PipelineStepCompleteEvent, PipelineHooks, PipelineStepSelectionReason, PipelinePlanStep, PipelinePlan, PipelineMermaidDirection, PipelineMermaidOptions, Pipeline, PipelineInput, PipelineResult, } from "./pipeline-types.js";
 export type { PipelineDefinition } from "./pipeline-definition.js";
@@ -29,3 +30,5 @@ export declare function definePipeline<const TSteps extends readonly AnyStep[],
     readonly definition: PipelineDefinitionSnapshot;
     readonly optionsSchema: StepsOptionsSchema<TSteps>;
 };
+export type { ArtifactJsonValue, ArtifactMetadata, ArtifactRecord, } from "../tracing/artifact-metadata.js";
+export type { ArtifactLoader, ArtifactSaver, ArtifactResult } from "./pipeline-artifacts.js";

package/dist/core/pipeline.js

@@ -1,9 +1,10 @@
-import { defaultPipelineContext, executePlannedRun, PipelineExecutionError, resolvePipelineRuntime, } from "./pipeline-execute.js";
+import { PipelineExecutionError } from "./pipeline-execution-error.js";
+import { defaultPipelineContext, executePlannedRun, resolvePipelineRuntime, } from "./pipeline-execute.js";
 import { RUN_MODEL_VERSION } from "./pipeline-ids.js";
 import { compilePipeline } from "./pipeline-compiler.js";
 import { PipelineDefinitionError } from "./pipeline-errors.js";
 import { requireOutputs } from "./pipeline-finalizer.js";
-import { brandCompiledPipeline, EXECUTE_COMPILED_RUN } from "./pipeline-identity.js";
+import { brandCompiledPipeline, EXECUTE_COMPILED_RUN, EXECUTE_TEST_RUN, } from "./pipeline-identity.js";
 import { renderPipelineMermaid } from "./pipeline-mermaid.js";
 import { buildPipelinePlan } from "./pipeline-plan.js";
 export { PipelineExecutionError, RUN_MODEL_VERSION };
@@ -50,18 +51,22 @@ export function definePipeline(definition) {
     function toMermaid(options = {}) {
         return renderPipelineMermaid(compiled.orderedSteps, options, compiled.stepGraph);
     }
-    async function executeCompiled(runPlan, options, controls, context = defaultPipelineContext()) {
+    async function executeCompiled(runPlan, options, controls, context = defaultPipelineContext(), overrides) {
         return executePlannedRun({
             compiled,
             controls,
             domainOptions: options,
             plan: runPlan,
             runtime: resolvePipelineRuntime(context),
+            overrides,
         });
     }
     async function run(options, controls = {}, context = defaultPipelineContext()) {
         const prepared = prepareRun(controls);
-        return executeCompiled(prepared.plan, options, prepared.controls, context);
+        // SAFETY: the public signature permits omission only when {} satisfies the
+        // input type. Schemas still validate the default object during execution.
+        const input = options === undefined ? {} : options;
+        return executeCompiled(prepared.plan, input, prepared.controls, context);
     }
     async function runOrThrow(options, controls = {}, context = defaultPipelineContext()) {
         const result = await run(options, controls, context);
@@ -86,6 +91,19 @@ export function definePipeline(definition) {
         toMermaid,
     };
     Object.defineProperty(pipeline, EXECUTE_COMPILED_RUN, { value: executeCompiled });
+    Object.defineProperty(pipeline, EXECUTE_TEST_RUN, {
+        value: (options, controls, context, overrides) => {
+            const resolved = new Map();
+            for (const [step, value] of overrides) {
+                const compiledStep = compiled.compiledByAuthorStep.get(step);
+                if (!compiledStep)
+                    throw new TypeError(`Override step ${step.id} does not belong to pipeline ${compiled.id}`);
+                resolved.set(compiledStep, value);
+            }
+            const prepared = prepareRun(controls);
+            return executeCompiled(prepared.plan, options === undefined ? {} : options, prepared.controls, context, resolved);
+        },
+    });
     brandCompiledPipeline(pipeline);
     return pipeline;
 }