tubeless 0.2.13 → 0.2.15

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 {\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"]}
+{"version":3,"file":"pipeline-steps.js","sourceRoot":"","sources":["../../src/core/pipeline-steps.ts"],"names":[],"mappings":"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","sourcesContent":["import type { PipelineMetadata } from \"../tracing/graph-metadata.js\";\nimport type { CompiledStepCache, StepCache } from \"./pipeline-cache.js\";\nimport {\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_CACHE,\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  readonly metadata?: PipelineMetadata;\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  /** Explicit output caching for ordinary deterministic steps only. */\n  readonly cache?: boolean | StepCache<Record<string, unknown>, TOptions>;\n  readonly [STEP_CACHE]?: CompiledStepCache<TOptions>;\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  metadata?: PipelineMetadata;\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  metadata?: PipelineMetadata;\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  metadata?: PipelineMetadata;\n  dryRun?: StepDryRunPolicy<TOptions, TDeps, TOptionalDeps, TOut>;\n  outputSchema?: never;\n  cache?: boolean | StepCache<RequiredInputs<TDeps> & OptionalInputs<TOptionalDeps>, TOptions>;\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  metadata?: PipelineMetadata;\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\" | \"cache\"\n    > & {\n      cache?: never;\n      load: ArtifactLoader<RequiredInputs<TDeps> & OptionalInputs<TOptionalDeps>, TValue, TOptions>;\n    }\n  ): BuiltStep<TId, TValue, TOptions, TInputOptions> {\n    const { cache, load, dryRun, ...fields } = definition;\n    if (cache !== undefined) throw new Error(\"Artifact helpers cannot configure caching\");\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\" | \"cache\"\n    > & {\n      cache?: never;\n      save: ArtifactSaver<RequiredInputs<TDeps> & OptionalInputs<TOptionalDeps>, TValue, TOptions>;\n    }\n  ): BuiltStep<TId, TValue, TOptions, TInputOptions> {\n    const { cache, save, dryRun, ...fields } = definition;\n    if (cache !== undefined) throw new Error(\"Artifact helpers cannot configure caching\");\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      metadata: config.metadata,\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      metadata?: PipelineMetadata;\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      metadata: config.metadata,\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      metadata: config.metadata,\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      metadata?: PipelineMetadata;\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      metadata?: PipelineMetadata;\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      metadata: config.metadata,\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,10 +1,13 @@
+import type { PipelineMetadata } from "../tracing/graph-metadata.js";
+import type { PipelineStepQuery } from "./pipeline-query.js";
+import type { StepCachePolicy } from "./pipeline-cache.js";
 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>;
 /** Serializable compiled semantics; no handlers, inputs, or application imports. */
 type ReadonlyDefinition<T> = T extends object ? {
-    readonly [K in keyof T]: ReadonlyDefinition<T[K]>;
+    readonly [K in keyof T]: K extends "metadata" ? T[K] : ReadonlyDefinition<T[K]>;
 } : T;
 /** Immutable snapshot of the compiled pipeline definition recorded for inspection and tracing. */
 export type PipelineDefinitionSnapshot = ReadonlyDefinition<PipelineDefinitionSnapshotContract>;
@@ -38,6 +41,8 @@ export interface PipelineContext {
 export type PipelineRunControls<TStepId extends string = string, TTargetId extends string = string> = {
     /** Maximum simultaneous steps, including skip predicates and output validation. Defaults to 1. */
     maxConcurrency?: number;
+    /** Run-wide cache policy for opted-in steps, including children. */
+    cache?: StepCachePolicy;
     /** Continue eligible branches after failure; otherwise stop dispatch and drain active steps. */
     continueOnError?: boolean;
     dryRun?: boolean;
@@ -66,6 +71,8 @@ export interface PipelineRuntime extends PipelineContext {
 export interface PipelineExecutionContext<TOptions extends object> extends PipelineRuntime {
     dryRun: boolean;
     options: TOptions;
+    /** Explicit run-wide cache policy; absent uses each step's policy. */
+    cachePolicy?: StepCachePolicy;
     /** Stable identity for this execution, whether or not tracing is configured. */
     runId: string;
     /** Stable identities for this traced run; absent unless `context.tracing` is configured. */
@@ -80,8 +87,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";
+    /** Provenance of a supplied test or cached output, independent of the row status. */
+    outputSource?: "override" | "cache";
     /** Stable identity for the row (item key, path, job id, …). */
     id: string;
     /** Optional display name; identity remains `id`. */
@@ -135,7 +142,7 @@ export type PipelineErrorPhase = PipelineErrorPhaseContract;
 /** Broad category of a structured pipeline error. */
 export type PipelineErrorKind = PipelineErrorKindContract;
 /** Ordered catalog of every stable package-owned pipeline error code. */
-export declare const PIPELINE_ERROR_CODES: readonly ["TUBELESS_CHILD_FAILED", "TUBELESS_DEFINITION_DEPENDENCY_CONTRADICTORY", "TUBELESS_DEFINITION_DEPENDENCY_CYCLE", "TUBELESS_DEFINITION_DEPENDENCY_DUPLICATE", "TUBELESS_DEFINITION_DEPENDENCY_NOT_IN_STEPS", "TUBELESS_DEFINITION_DEPENDENCY_SELF_REFERENCE", "TUBELESS_DEFINITION_FINALIZER_STEP_NOT_IN_STEPS", "TUBELESS_DEFINITION_IMPLEMENTATION_VERSION_INVALID", "TUBELESS_DEFINITION_OPTIONS_SCHEMA_CONFLICT", "TUBELESS_DEFINITION_PIPELINE_DESCRIPTION_BLANK", "TUBELESS_DEFINITION_PIPELINE_ID_BLANK", "TUBELESS_DEFINITION_PIPELINE_NAME_BLANK", "TUBELESS_DEFINITION_STEP_ID_BLANK", "TUBELESS_DEFINITION_STEP_ID_RESERVED", "TUBELESS_DEFINITION_STEP_IDS_DUPLICATE", "TUBELESS_DEFINITION_STEP_NAME_BLANK", "TUBELESS_DEFINITION_TARGET_FINALIZER_MISMATCH", "TUBELESS_DEFINITION_TARGET_NOT_IN_STEPS", "TUBELESS_DEFINITION_TARGETS_DUPLICATE", "TUBELESS_FINALIZATION_CANCELLED", "TUBELESS_FINALIZATION_FAILED", "TUBELESS_FINAL_RESULT_VALIDATION_FAILED", "TUBELESS_OPTIONS_VALIDATION_FAILED", "TUBELESS_PLANNING_SELECTION_CONFLICT", "TUBELESS_PLANNING_STEP_SELECTION_DUPLICATE", "TUBELESS_PLANNING_STEP_SELECTION_EMPTY", "TUBELESS_PLANNING_STEP_UNKNOWN", "TUBELESS_PLANNING_TARGET_SELECTION_DUPLICATE", "TUBELESS_PLANNING_TARGET_SELECTION_EMPTY", "TUBELESS_PLANNING_TARGET_UNDECLARED", "TUBELESS_PLANNING_TARGET_UNKNOWN", "TUBELESS_RUN_CANCELLED", "TUBELESS_RUN_CONCURRENCY_INVALID", "TUBELESS_STEP_OUTPUT_VALIDATION_FAILED", "TUBELESS_STEP_FAILED"];
+export declare const PIPELINE_ERROR_CODES: readonly ["TUBELESS_CHILD_FAILED", "TUBELESS_DEFINITION_CACHE_INVALID", "TUBELESS_DEFINITION_DEPENDENCY_CONTRADICTORY", "TUBELESS_DEFINITION_DEPENDENCY_CYCLE", "TUBELESS_DEFINITION_DEPENDENCY_DUPLICATE", "TUBELESS_DEFINITION_DEPENDENCY_NOT_IN_STEPS", "TUBELESS_DEFINITION_DEPENDENCY_SELF_REFERENCE", "TUBELESS_DEFINITION_FINALIZER_STEP_NOT_IN_STEPS", "TUBELESS_DEFINITION_IMPLEMENTATION_VERSION_INVALID", "TUBELESS_DEFINITION_OPTIONS_SCHEMA_CONFLICT", "TUBELESS_DEFINITION_PIPELINE_DESCRIPTION_BLANK", "TUBELESS_DEFINITION_PIPELINE_ID_BLANK", "TUBELESS_DEFINITION_PIPELINE_NAME_BLANK", "TUBELESS_DEFINITION_STEP_CACHE_INVALID", "TUBELESS_DEFINITION_STEP_ID_BLANK", "TUBELESS_DEFINITION_STEP_ID_RESERVED", "TUBELESS_DEFINITION_STEP_IDS_DUPLICATE", "TUBELESS_DEFINITION_STEP_NAME_BLANK", "TUBELESS_DEFINITION_TARGET_FINALIZER_MISMATCH", "TUBELESS_DEFINITION_TARGET_NOT_IN_STEPS", "TUBELESS_DEFINITION_TARGETS_DUPLICATE", "TUBELESS_FINALIZATION_CANCELLED", "TUBELESS_FINALIZATION_FAILED", "TUBELESS_FINAL_RESULT_VALIDATION_FAILED", "TUBELESS_OPTIONS_VALIDATION_FAILED", "TUBELESS_PLANNING_SELECTION_CONFLICT", "TUBELESS_PLANNING_STEP_SELECTION_DUPLICATE", "TUBELESS_PLANNING_STEP_SELECTION_EMPTY", "TUBELESS_PLANNING_STEP_UNKNOWN", "TUBELESS_PLANNING_TARGET_SELECTION_DUPLICATE", "TUBELESS_PLANNING_TARGET_SELECTION_EMPTY", "TUBELESS_PLANNING_TARGET_UNDECLARED", "TUBELESS_PLANNING_TARGET_UNKNOWN", "TUBELESS_RUN_CANCELLED", "TUBELESS_RUN_CONCURRENCY_INVALID", "TUBELESS_RUN_CACHE_INVALID", "TUBELESS_STEP_OUTPUT_VALIDATION_FAILED", "TUBELESS_STEP_FAILED"];
 /** Stable package-owned code for a pipeline error. */
 export type PipelineErrorCode = (typeof PIPELINE_ERROR_CODES)[number];
 /** Return whether an unknown value is a stable package-owned pipeline error code. */
@@ -231,8 +238,8 @@ export interface PipelineErrorCause {
     sourceCode?: string;
 }
 interface PipelineStepReportBase {
-    /** Present once a supplied test output enters validation, including failed/cancelled attempts. */
-    outputSource?: "override";
+    /** Present once a test or cached output is selected, including failed/cancelled validation. */
+    outputSource?: "override" | "cache";
     /** Present when the step started an execution attempt. */
     attemptId?: string;
     id: string;
@@ -335,7 +342,7 @@ export type PipelineStepStatus = {
     attemptId: string;
     pipelineId: string;
     /** Supplied test output; the normal step handler is not executing. */
-    outputSource?: "override";
+    outputSource?: "override" | "cache";
     progress?: PipelineStepProgress;
     status: "running";
     step: PipelinePlanStep;
@@ -441,6 +448,7 @@ export type PipelineStepSelectionReason = {
 };
 /** Planned representation of one declared step and its selection state. */
 export interface PipelinePlanStep {
+    metadata?: PipelineMetadata;
     dependencies: string[];
     description?: string;
     /** How this step behaves when the pipeline is run with `dryRun: true`. */
@@ -491,6 +499,10 @@ export declare const PIPELINE_MERMAID_DIRECTIONS: readonly ["BT", "LR", "RL", "T
 export type PipelineMermaidDirection = (typeof PIPELINE_MERMAID_DIRECTIONS)[number];
 /** Rendering options for a pipeline Mermaid flowchart. */
 export interface PipelineMermaidOptions {
+    /** Filter displayed steps only; edges to omitted steps are omitted. */
+    query?: PipelineStepQuery;
+    /** Include structured metadata in node labels. */
+    includeMetadata?: boolean;
     /** Mermaid flowchart direction. Defaults to top-down (`TD`). */
     direction?: PipelineMermaidDirection;
     /** Append each operational description to its node label. Defaults to false. */
@@ -512,6 +524,7 @@ export interface Pipeline<TOptions extends object, TResult, TStepId extends stri
     readonly name?: string;
     /** Human-readable purpose for command and discovery surfaces. */
     readonly description?: string;
+    readonly metadata?: PipelineMetadata;
     /** Compiled definition metadata. Absent only on externally implemented pipelines. */
     readonly definition?: PipelineDefinitionSnapshot;
     /** Runtime domain schema supplied to createSteps; CLI adapters can infer its input flags. */

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

@@ -1 +1 @@
-{"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"]}
+{"version":3,"file":"pipeline-types.js","sourceRoot":"","sources":["../../src/core/pipeline-types.ts"],"names":[],"mappings":"AAmBA,OAAO,EAAE,oBAAoB,IAAI,0BAA0B,EAAE,MAAM,8BAA8B,CAAC;AAoKlG,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;AAoVD,0DAA0D;AAC1D,MAAM,CAAC,MAAM,2BAA2B,GAAG,CAAC,IAAI,EAAE,IAAI,EAAE,IAAI,EAAE,IAAI,EAAE,IAAI,CAAU,CAAC","sourcesContent":["import type { PipelineMetadata } from \"../tracing/graph-metadata.js\";\nimport type { PipelineStepQuery } from \"./pipeline-query.js\";\nimport type { StepCachePolicy } from \"./pipeline-cache.js\";\nimport 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]: K extends \"metadata\" ? T[K] : 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  /** Run-wide cache policy for opted-in steps, including children. */\n  cache?: StepCachePolicy;\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  /** Explicit run-wide cache policy; absent uses each step's policy. */\n  cachePolicy?: StepCachePolicy;\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 or cached output, independent of the row status. */\n  outputSource?: \"override\" | \"cache\";\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 test or cached output is selected, including failed/cancelled validation. */\n  outputSource?: \"override\" | \"cache\";\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\" | \"cache\";\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  metadata?: PipelineMetadata;\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  /** Filter displayed steps only; edges to omitted steps are omitted. */\n  query?: PipelineStepQuery;\n  /** Include structured metadata in node labels. */\n  includeMetadata?: boolean;\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  readonly metadata?: PipelineMetadata;\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-validation.js

@@ -7,7 +7,7 @@ export class PipelineBoundaryValidationError extends Error {
     }
 }
 function normalizeValidationPath(path) {
-    if (!path || path.length === 0)
+    if (!path)
         return undefined;
     return path.map((segment) => {
         const key = typeof segment === "object" && segment !== null ? segment.key : segment;

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

@@ -1 +1 @@
-{"version":3,"file":"pipeline-validation.js","sourceRoot":"","sources":["../../src/core/pipeline-validation.ts"],"names":[],"mappings":"AAQA,MAAM,OAAO,+BAAgC,SAAQ,KAAK;IAG7C,MAAM;IAFjB,YACE,OAAe,EACN,MAA0C,EACnD,KAAe;QAEf,KAAK,CAAC,OAAO,EAAE,KAAK,KAAK,SAAS,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,EAAE,KAAK,EAAE,CAAC,CAAC;sBAHnD,MAAM;QAIf,IAAI,CAAC,IAAI,GAAG,iCAAiC,CAAC;IAChD,CAAC;CACF;AAED,SAAS,uBAAuB,CAC9B,IAAmC;IAEnC,IAAI,CAAC,IAAI,IAAI,IAAI,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,SAAS,CAAC;IACjD,OAAO,IAAI,CAAC,GAAG,CAAC,CAAC,OAAO,EAAE,EAAE;QAC1B,MAAM,GAAG,GAAG,OAAO,OAAO,KAAK,QAAQ,IAAI,OAAO,KAAK,IAAI,CAAC,CAAC,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC,OAAO,CAAC;QACpF,OAAO,OAAO,GAAG,KAAK,QAAQ,IAAI,OAAO,GAAG,KAAK,QAAQ,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;IAChF,CAAC,CAAC,CAAC;AACL,CAAC;AAED,SAAS,qBAAqB,CAAC,KAA8B;IAC3D,MAAM,QAAQ,GAAG,KAAK,CAAC,IAAI,EAAE,GAAG,CAAC,MAAM,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;IACnD,OAAO,QAAQ,CAAC,CAAC,CAAC,GAAG,QAAQ,KAAK,KAAK,CAAC,OAAO,EAAE,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC;AACpE,CAAC;AAED,MAAM,CAAC,KAAK,UAAU,sBAAsB,CAC1C,MAAe,EACf,KAAc,EACd,QAAgB;IAEhB,IAAI,MAA0D,CAAC;IAC/D,IAAI,CAAC;QACH,MAAM,GAAG,MAAM,MAAM,CAAC,WAAW,CAAC,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAC;IACrD,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,MAAM,IAAI,+BAA+B,CACvC,GAAG,QAAQ,YAAY,MAAM,CAAC,WAAW,CAAC,CAAC,MAAM,0BAA0B,EAC3E,EAAE,EACF,KAAK,CACN,CAAC;IACJ,CAAC;IACD,IAAI,MAAM,CAAC,MAAM,EAAE,CAAC;QAClB,MAAM,MAAM,GAAG,MAAM,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,KAAK,EAAE,EAAE;YACzC,MAAM,IAAI,GAAG,uBAAuB,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;YACjD,MAAM,UAAU,GAA4B,EAAE,OAAO,EAAE,KAAK,CAAC,OAAO,EAAE,CAAC;YACvE,IAAI,IAAI;gBAAE,UAAU,CAAC,IAAI,GAAG,IAAI,CAAC;YACjC,OAAO,UAAU,CAAC;QACpB,CAAC,CAAC,CAAC;QACH,MAAM,IAAI,+BAA+B,CACvC,GAAG,QAAQ,uBAAuB,MAAM,CAAC,GAAG,CAAC,qBAAqB,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,EAChF,MAAM,CACP,CAAC;IACJ,CAAC;IACD,OAAO,MAAM,CAAC,KAAK,CAAC;AACtB,CAAC","sourcesContent":["import type {\n  InferSchemaOutput,\n  PipelineValidationIssue,\n  StandardSchemaV1,\n  StandardSchemaV1Issue,\n  StandardSchemaV1Result,\n} from \"./pipeline-types.js\";\n\nexport class PipelineBoundaryValidationError extends Error {\n  constructor(\n    message: string,\n    readonly issues: readonly PipelineValidationIssue[],\n    cause?: unknown\n  ) {\n    super(message, cause === undefined ? undefined : { cause });\n    this.name = \"PipelineBoundaryValidationError\";\n  }\n}\n\nfunction normalizeValidationPath(\n  path: StandardSchemaV1Issue[\"path\"]\n): readonly (number | string)[] | undefined {\n  if (!path || path.length === 0) return undefined;\n  return path.map((segment) => {\n    const key = typeof segment === \"object\" && segment !== null ? segment.key : segment;\n    return typeof key === \"number\" || typeof key === \"string\" ? key : String(key);\n  });\n}\n\nfunction renderValidationIssue(issue: PipelineValidationIssue): string {\n  const location = issue.path?.map(String).join(\".\");\n  return location ? `${location}: ${issue.message}` : issue.message;\n}\n\nexport async function validateStandardSchema<TSchema extends StandardSchemaV1>(\n  schema: TSchema,\n  value: unknown,\n  boundary: string\n): Promise<InferSchemaOutput<TSchema>> {\n  let result: StandardSchemaV1Result<InferSchemaOutput<TSchema>>;\n  try {\n    result = await schema[\"~standard\"].validate(value);\n  } catch (error) {\n    throw new PipelineBoundaryValidationError(\n      `${boundary} schema (${schema[\"~standard\"].vendor}) threw while validating`,\n      [],\n      error\n    );\n  }\n  if (result.issues) {\n    const issues = result.issues.map((issue) => {\n      const path = normalizeValidationPath(issue.path);\n      const normalized: PipelineValidationIssue = { message: issue.message };\n      if (path) normalized.path = path;\n      return normalized;\n    });\n    throw new PipelineBoundaryValidationError(\n      `${boundary} validation failed: ${issues.map(renderValidationIssue).join(\"; \")}`,\n      issues\n    );\n  }\n  return result.value;\n}\n"]}
+{"version":3,"file":"pipeline-validation.js","sourceRoot":"","sources":["../../src/core/pipeline-validation.ts"],"names":[],"mappings":"AAQA,MAAM,OAAO,+BAAgC,SAAQ,KAAK;IAG7C,MAAM;IAFjB,YACE,OAAe,EACN,MAA0C,EACnD,KAAe;QAEf,KAAK,CAAC,OAAO,EAAE,KAAK,KAAK,SAAS,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,EAAE,KAAK,EAAE,CAAC,CAAC;sBAHnD,MAAM;QAIf,IAAI,CAAC,IAAI,GAAG,iCAAiC,CAAC;IAChD,CAAC;CACF;AAED,SAAS,uBAAuB,CAC9B,IAAmC;IAEnC,IAAI,CAAC,IAAI;QAAE,OAAO,SAAS,CAAC;IAC5B,OAAO,IAAI,CAAC,GAAG,CAAC,CAAC,OAAO,EAAE,EAAE;QAC1B,MAAM,GAAG,GAAG,OAAO,OAAO,KAAK,QAAQ,IAAI,OAAO,KAAK,IAAI,CAAC,CAAC,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC,OAAO,CAAC;QACpF,OAAO,OAAO,GAAG,KAAK,QAAQ,IAAI,OAAO,GAAG,KAAK,QAAQ,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;IAChF,CAAC,CAAC,CAAC;AACL,CAAC;AAED,SAAS,qBAAqB,CAAC,KAA8B;IAC3D,MAAM,QAAQ,GAAG,KAAK,CAAC,IAAI,EAAE,GAAG,CAAC,MAAM,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;IACnD,OAAO,QAAQ,CAAC,CAAC,CAAC,GAAG,QAAQ,KAAK,KAAK,CAAC,OAAO,EAAE,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC;AACpE,CAAC;AAED,MAAM,CAAC,KAAK,UAAU,sBAAsB,CAC1C,MAAe,EACf,KAAc,EACd,QAAgB;IAEhB,IAAI,MAA0D,CAAC;IAC/D,IAAI,CAAC;QACH,MAAM,GAAG,MAAM,MAAM,CAAC,WAAW,CAAC,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAC;IACrD,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,MAAM,IAAI,+BAA+B,CACvC,GAAG,QAAQ,YAAY,MAAM,CAAC,WAAW,CAAC,CAAC,MAAM,0BAA0B,EAC3E,EAAE,EACF,KAAK,CACN,CAAC;IACJ,CAAC;IACD,IAAI,MAAM,CAAC,MAAM,EAAE,CAAC;QAClB,MAAM,MAAM,GAAG,MAAM,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,KAAK,EAAE,EAAE;YACzC,MAAM,IAAI,GAAG,uBAAuB,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;YACjD,MAAM,UAAU,GAA4B,EAAE,OAAO,EAAE,KAAK,CAAC,OAAO,EAAE,CAAC;YACvE,IAAI,IAAI;gBAAE,UAAU,CAAC,IAAI,GAAG,IAAI,CAAC;YACjC,OAAO,UAAU,CAAC;QACpB,CAAC,CAAC,CAAC;QACH,MAAM,IAAI,+BAA+B,CACvC,GAAG,QAAQ,uBAAuB,MAAM,CAAC,GAAG,CAAC,qBAAqB,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,EAChF,MAAM,CACP,CAAC;IACJ,CAAC;IACD,OAAO,MAAM,CAAC,KAAK,CAAC;AACtB,CAAC","sourcesContent":["import type {\n  InferSchemaOutput,\n  PipelineValidationIssue,\n  StandardSchemaV1,\n  StandardSchemaV1Issue,\n  StandardSchemaV1Result,\n} from \"./pipeline-types.js\";\n\nexport class PipelineBoundaryValidationError extends Error {\n  constructor(\n    message: string,\n    readonly issues: readonly PipelineValidationIssue[],\n    cause?: unknown\n  ) {\n    super(message, cause === undefined ? undefined : { cause });\n    this.name = \"PipelineBoundaryValidationError\";\n  }\n}\n\nfunction normalizeValidationPath(\n  path: StandardSchemaV1Issue[\"path\"]\n): readonly (number | string)[] | undefined {\n  if (!path) return undefined;\n  return path.map((segment) => {\n    const key = typeof segment === \"object\" && segment !== null ? segment.key : segment;\n    return typeof key === \"number\" || typeof key === \"string\" ? key : String(key);\n  });\n}\n\nfunction renderValidationIssue(issue: PipelineValidationIssue): string {\n  const location = issue.path?.map(String).join(\".\");\n  return location ? `${location}: ${issue.message}` : issue.message;\n}\n\nexport async function validateStandardSchema<TSchema extends StandardSchemaV1>(\n  schema: TSchema,\n  value: unknown,\n  boundary: string\n): Promise<InferSchemaOutput<TSchema>> {\n  let result: StandardSchemaV1Result<InferSchemaOutput<TSchema>>;\n  try {\n    result = await schema[\"~standard\"].validate(value);\n  } catch (error) {\n    throw new PipelineBoundaryValidationError(\n      `${boundary} schema (${schema[\"~standard\"].vendor}) threw while validating`,\n      [],\n      error\n    );\n  }\n  if (result.issues) {\n    const issues = result.issues.map((issue) => {\n      const path = normalizeValidationPath(issue.path);\n      const normalized: PipelineValidationIssue = { message: issue.message };\n      if (path) normalized.path = path;\n      return normalized;\n    });\n    throw new PipelineBoundaryValidationError(\n      `${boundary} validation failed: ${issues.map(renderValidationIssue).join(\"; \")}`,\n      issues\n    );\n  }\n  return result.value;\n}\n"]}

package/dist/core/pipeline.d.ts

@@ -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 { PipelineCacheOptions, StepCacheEntry, StepCache, StepCacheCodec, StepCacheContext, StepCachePolicy, StepCacheStore, } from "./pipeline-cache.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";
@@ -32,3 +33,6 @@ export declare function definePipeline<const TSteps extends readonly AnyStep[],
 };
 export type { ArtifactJsonValue, ArtifactMetadata, ArtifactRecord, } from "../tracing/artifact-metadata.js";
 export type { ArtifactLoader, ArtifactSaver, ArtifactResult } from "./pipeline-artifacts.js";
+export { querySteps } from "./pipeline-query.js";
+export type { PipelineStepQuery } from "./pipeline-query.js";
+export type { PipelineMetadata, PipelineMetadataValue } from "../tracing/graph-metadata.js";

package/dist/core/pipeline.js

@@ -12,8 +12,10 @@ export { isPipelineErrorCode, PIPELINE_ERROR_CODES } from "./pipeline-types.js";
 export { createSteps } from "./pipeline-steps.js";
 export { PipelineDefinitionError, requireOutputs };
 function normalizeRunControls(controls) {
-    const { continueOnError, dryRun, maxConcurrency, stepIds, targets } = controls;
+    const { cache, continueOnError, dryRun, maxConcurrency, stepIds, targets } = controls;
     const snapshot = {};
+    if (cache !== undefined)
+        snapshot.cache = cache;
     if (continueOnError !== undefined)
         snapshot.continueOnError = continueOnError;
     if (dryRun !== undefined)
@@ -80,6 +82,9 @@ export function definePipeline(definition) {
         id: definition.id,
         ...(definition.name === undefined ? {} : { name: definition.name }),
         ...(definition.description === undefined ? {} : { description: definition.description }),
+        ...(compiled.definition.metadata === undefined
+            ? {}
+            : { metadata: compiled.definition.metadata }),
         definition: compiled.definition,
         // SAFETY: compilation verifies that every step belongs to the same options schema.
         optionsSchema: compiled.optionsSchema,
@@ -107,4 +112,5 @@ export function definePipeline(definition) {
     brandCompiledPipeline(pipeline);
     return pipeline;
 }
+export { querySteps } from "./pipeline-query.js";
 //# sourceMappingURL=pipeline.js.map

package/dist/core/pipeline.js.map

@@ -1 +1 @@
-{"version":3,"file":"pipeline.js","sourceRoot":"","sources":["../../src/core/pipeline.ts"],"names":[],"mappings":"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","sourcesContent":["import { PipelineExecutionError } from \"./pipeline-execution-error.js\";\nimport {\n  defaultPipelineContext,\n  executePlannedRun,\n  resolvePipelineRuntime,\n} from \"./pipeline-execute.js\";\nimport { RUN_MODEL_VERSION } from \"./pipeline-ids.js\";\nimport { compilePipeline } from \"./pipeline-compiler.js\";\nimport type {\n  DefaultPipelineResult,\n  DefaultPipelineTargets,\n  PipelineDefinition,\n  StepIds,\n  StepsInputOptions,\n  StepsOptionsSchema,\n  TargetIds,\n} from \"./pipeline-definition.js\";\nimport { PipelineDefinitionError } from \"./pipeline-errors.js\";\nimport { requireOutputs } from \"./pipeline-finalizer.js\";\nimport {\n  brandCompiledPipeline,\n  EXECUTE_COMPILED_RUN,\n  EXECUTE_TEST_RUN,\n} from \"./pipeline-identity.js\";\nimport { renderPipelineMermaid } from \"./pipeline-mermaid.js\";\nimport { buildPipelinePlan } from \"./pipeline-plan.js\";\nimport type { AnyStep } from \"./pipeline-steps.js\";\nimport type {\n  InferSchemaOutput,\n  Pipeline,\n  PipelineContext,\n  PipelineDefinitionSnapshot,\n  PipelineMermaidOptions,\n  PipelinePlan,\n  PipelineRun,\n  PipelineRunControls,\n  StandardSchemaV1,\n} from \"./pipeline-types.js\";\n\nexport { PipelineExecutionError, RUN_MODEL_VERSION };\nexport { isPipelineErrorCode, PIPELINE_ERROR_CODES } from \"./pipeline-types.js\";\nexport { createSteps } from \"./pipeline-steps.js\";\nexport type { IterationDecision, IterationState } from \"./iteration.js\";\nexport { PipelineDefinitionError, requireOutputs };\nexport type {\n  PipelineDefinitionIdentity,\n  PipelineDefinitionSnapshot,\n  PipelineLogger,\n  PipelineContext,\n  PipelineRunControls,\n  PipelineExecutionContext,\n  PipelineStepProgressDetailStatus,\n  PipelineStepProgressDetail,\n  PipelineStepProgress,\n  PipelineStepContext,\n  RemoteStepAdapter,\n  PipelineErrorPhase,\n  PipelineErrorKind,\n  PipelineErrorCode,\n  PipelineValidationIssue,\n  PipelineError,\n  PipelineFanOutDiagnostics,\n  PipelineFanOutFailure,\n  StandardSchemaV1,\n  PipelineErrorCause,\n  PipelineStepCompleteReport,\n  PipelineStepSkippedReport,\n  PipelineStepCancelledReport,\n  PipelineStepFailedReport,\n  PipelineStepReport,\n  PipelineStepReportStatus,\n  PipelineRunStatus,\n  PipelineRun,\n  PipelineStepSkipReason,\n  StepSkipDecision,\n  PipelineStepStatus,\n  PipelineStepLifecycleStatus,\n  PipelineStepPlannedEvent,\n  PipelineStepStartEvent,\n  PipelineStepProgressEvent,\n  PipelineStepCancelledEvent,\n  PipelineStepFailedEvent,\n  PipelineStepSkippedEvent,\n  PipelineStepCompleteEvent,\n  PipelineHooks,\n  PipelineStepSelectionReason,\n  PipelinePlanStep,\n  PipelinePlan,\n  PipelineMermaidDirection,\n  PipelineMermaidOptions,\n  Pipeline,\n  PipelineInput,\n  PipelineResult,\n} from \"./pipeline-types.js\";\n\nexport type { PipelineDefinition } from \"./pipeline-definition.js\";\n\nexport type { Step, MappedChildProgressOptions } from \"./pipeline-steps.js\";\n\ntype DuplicateStepIds<\n  TSteps extends readonly AnyStep[],\n  TSeen extends string = never,\n> = TSteps extends readonly [infer THead, ...infer TTail]\n  ? THead extends AnyStep\n    ? TTail extends readonly AnyStep[]\n      ? THead[\"id\"] extends TSeen\n        ? THead[\"id\"] | DuplicateStepIds<TTail, TSeen>\n        : DuplicateStepIds<TTail, TSeen | THead[\"id\"]>\n      : never\n    : never\n  : never;\n\ntype CheckedStepTuple<TSteps extends readonly AnyStep[]> =\n  string extends StepIds<TSteps>\n    ? unknown\n    : DuplicateStepIds<TSteps> extends never\n      ? unknown\n      : {\n          /** Compile-time diagnostic: every literal step ID in a definition must be unique. */\n          readonly __duplicateStepIds: DuplicateStepIds<TSteps>;\n        };\n\nfunction normalizeRunControls<TStepId extends string, TTargetId extends string>(\n  controls: PipelineRunControls<TStepId, TTargetId>\n): PipelineRunControls<TStepId, TTargetId> {\n  const { continueOnError, dryRun, maxConcurrency, stepIds, targets } = controls;\n  const snapshot: PipelineRunControls<TStepId, TTargetId> = {};\n  if (continueOnError !== undefined) snapshot.continueOnError = continueOnError;\n  if (dryRun !== undefined) snapshot.dryRun = dryRun;\n  if (maxConcurrency !== undefined) snapshot.maxConcurrency = maxConcurrency;\n  if (stepIds !== undefined) snapshot.stepIds = [...stepIds];\n  if (targets !== undefined) snapshot.targets = [...targets];\n  return snapshot;\n}\n\n/**\n * Compile a typed step graph into a validated, executable pipeline.\n * Prefer inferred type arguments to preserve the literal id. For an explicit\n * result contract, annotate the finalizer's return type; partially supplied type\n * arguments use defaults for remaining parameters, including the id's string type.\n */\nexport function definePipeline<\n  const TSteps extends readonly AnyStep[],\n  TResult = DefaultPipelineResult<TSteps>,\n  const TTargets extends readonly TSteps[number][] = DefaultPipelineTargets<TSteps>,\n  const TResultSchema extends StandardSchemaV1 | undefined = undefined,\n  const TId extends string = string,\n>(\n  definition: PipelineDefinition<TSteps, TResult, TTargets, TResultSchema> &\n    CheckedStepTuple<TSteps> & { readonly id: TId }\n): Pipeline<\n  StepsInputOptions<TSteps>,\n  TResultSchema extends StandardSchemaV1 ? InferSchemaOutput<TResultSchema> : TResult,\n  StepIds<TSteps>,\n  TargetIds<TTargets>,\n  TId\n> & {\n  readonly definition: PipelineDefinitionSnapshot;\n  readonly optionsSchema: StepsOptionsSchema<TSteps>;\n} {\n  const compiled = compilePipeline<TSteps, TResult, TTargets, TResultSchema>(definition);\n  type TInputOptions = StepsInputOptions<TSteps>;\n  type TPipelineResult = TResultSchema extends StandardSchemaV1\n    ? InferSchemaOutput<TResultSchema>\n    : TResult;\n  type TStepId = StepIds<TSteps>;\n  type TTargetId = TargetIds<TTargets>;\n  // SAFETY: each compiled step id is a string key of `TSteps`.\n  const stepIds = compiled.stepIds as readonly TStepId[];\n  // SAFETY: each compiled target id is a string key of `TTargets`.\n  const targetIds = compiled.targetIds as readonly TTargetId[];\n\n  function prepareRun(controls: PipelineRunControls<TStepId, TTargetId>): {\n    controls: PipelineRunControls<TStepId, TTargetId>;\n    plan: PipelinePlan;\n  } {\n    const normalizedControls = normalizeRunControls(controls);\n    return {\n      controls: normalizedControls,\n      plan: buildPipelinePlan(compiled, normalizedControls),\n    };\n  }\n\n  function plan(controls: PipelineRunControls<TStepId, TTargetId> = {}): PipelinePlan {\n    return prepareRun(controls).plan;\n  }\n\n  function toMermaid(options: PipelineMermaidOptions = {}): string {\n    return renderPipelineMermaid(compiled.orderedSteps, options, compiled.stepGraph);\n  }\n\n  async function executeCompiled(\n    runPlan: PipelinePlan,\n    options: TInputOptions,\n    controls: PipelineRunControls<TStepId, TTargetId>,\n    context: Partial<PipelineContext> = defaultPipelineContext(),\n    overrides?: ReadonlyMap<AnyStep, unknown>\n  ): Promise<PipelineRun<TPipelineResult>> {\n    return executePlannedRun({\n      compiled,\n      controls,\n      domainOptions: options,\n      plan: runPlan,\n      runtime: resolvePipelineRuntime(context),\n      overrides,\n    });\n  }\n\n  async function run(\n    options?: TInputOptions,\n    controls: PipelineRunControls<TStepId, TTargetId> = {},\n    context: Partial<PipelineContext> = defaultPipelineContext()\n  ): Promise<PipelineRun<TPipelineResult>> {\n    const prepared = prepareRun(controls);\n    // SAFETY: the public signature permits omission only when {} satisfies the\n    // input type. Schemas still validate the default object during execution.\n    const input = options === undefined ? ({} as TInputOptions) : options;\n    return executeCompiled(prepared.plan, input, prepared.controls, context);\n  }\n\n  async function runOrThrow(\n    options?: TInputOptions,\n    controls: PipelineRunControls<TStepId, TTargetId> = {},\n    context: Partial<PipelineContext> = defaultPipelineContext()\n  ): Promise<TPipelineResult> {\n    const result = await run(options, controls, context);\n    if (result.status !== \"completed\") {\n      throw new PipelineExecutionError(result);\n    }\n    // SAFETY: a completed run always carries its `TPipelineResult` value.\n    return result.value as TPipelineResult;\n  }\n\n  const pipeline = {\n    id: definition.id,\n    ...(definition.name === undefined ? {} : { name: definition.name }),\n    ...(definition.description === undefined ? {} : { description: definition.description }),\n    definition: compiled.definition,\n    // SAFETY: compilation verifies that every step belongs to the same options schema.\n    optionsSchema: compiled.optionsSchema as StepsOptionsSchema<TSteps> &\n      (StandardSchemaV1 | undefined),\n    stepIds,\n    targetIds,\n    plan,\n    run,\n    runOrThrow,\n    toMermaid,\n  };\n  Object.defineProperty(pipeline, EXECUTE_COMPILED_RUN, { value: executeCompiled });\n  Object.defineProperty(pipeline, EXECUTE_TEST_RUN, {\n    value: (\n      options: TInputOptions,\n      controls: PipelineRunControls<TStepId, TTargetId>,\n      context: Partial<PipelineContext>,\n      overrides: ReadonlyMap<AnyStep, unknown>\n    ) => {\n      const resolved = new Map<AnyStep, unknown>();\n      for (const [step, value] of overrides) {\n        const compiledStep = compiled.compiledByAuthorStep.get(step);\n        if (!compiledStep)\n          throw new TypeError(\n            `Override step ${step.id} does not belong to pipeline ${compiled.id}`\n          );\n        resolved.set(compiledStep, value);\n      }\n      const prepared = prepareRun(controls);\n      return executeCompiled(\n        prepared.plan,\n        options === undefined ? ({} as TInputOptions) : options,\n        prepared.controls,\n        context,\n        resolved\n      );\n    },\n  });\n  brandCompiledPipeline(pipeline);\n  return pipeline;\n}\n\nexport type {\n  ArtifactJsonValue,\n  ArtifactMetadata,\n  ArtifactRecord,\n} from \"../tracing/artifact-metadata.js\";\nexport type { ArtifactLoader, ArtifactSaver, ArtifactResult } from \"./pipeline-artifacts.js\";\n"]}
+{"version":3,"file":"pipeline.js","sourceRoot":"","sources":["../../src/core/pipeline.ts"],"names":[],"mappings":"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","sourcesContent":["import { PipelineExecutionError } from \"./pipeline-execution-error.js\";\nimport {\n  defaultPipelineContext,\n  executePlannedRun,\n  resolvePipelineRuntime,\n} from \"./pipeline-execute.js\";\nimport { RUN_MODEL_VERSION } from \"./pipeline-ids.js\";\nimport { compilePipeline } from \"./pipeline-compiler.js\";\nimport type {\n  DefaultPipelineResult,\n  DefaultPipelineTargets,\n  PipelineDefinition,\n  StepIds,\n  StepsInputOptions,\n  StepsOptionsSchema,\n  TargetIds,\n} from \"./pipeline-definition.js\";\nimport { PipelineDefinitionError } from \"./pipeline-errors.js\";\nimport { requireOutputs } from \"./pipeline-finalizer.js\";\nimport {\n  brandCompiledPipeline,\n  EXECUTE_COMPILED_RUN,\n  EXECUTE_TEST_RUN,\n} from \"./pipeline-identity.js\";\nimport { renderPipelineMermaid } from \"./pipeline-mermaid.js\";\nimport { buildPipelinePlan } from \"./pipeline-plan.js\";\nimport type { AnyStep } from \"./pipeline-steps.js\";\nimport type {\n  InferSchemaOutput,\n  Pipeline,\n  PipelineContext,\n  PipelineDefinitionSnapshot,\n  PipelineMermaidOptions,\n  PipelinePlan,\n  PipelineRun,\n  PipelineRunControls,\n  StandardSchemaV1,\n} from \"./pipeline-types.js\";\n\nexport { PipelineExecutionError, RUN_MODEL_VERSION };\nexport { isPipelineErrorCode, PIPELINE_ERROR_CODES } from \"./pipeline-types.js\";\nexport { createSteps } from \"./pipeline-steps.js\";\nexport type {\n  PipelineCacheOptions,\n  StepCacheEntry,\n  StepCache,\n  StepCacheCodec,\n  StepCacheContext,\n  StepCachePolicy,\n  StepCacheStore,\n} from \"./pipeline-cache.js\";\nexport type { IterationDecision, IterationState } from \"./iteration.js\";\nexport { PipelineDefinitionError, requireOutputs };\nexport type {\n  PipelineDefinitionIdentity,\n  PipelineDefinitionSnapshot,\n  PipelineLogger,\n  PipelineContext,\n  PipelineRunControls,\n  PipelineExecutionContext,\n  PipelineStepProgressDetailStatus,\n  PipelineStepProgressDetail,\n  PipelineStepProgress,\n  PipelineStepContext,\n  RemoteStepAdapter,\n  PipelineErrorPhase,\n  PipelineErrorKind,\n  PipelineErrorCode,\n  PipelineValidationIssue,\n  PipelineError,\n  PipelineFanOutDiagnostics,\n  PipelineFanOutFailure,\n  StandardSchemaV1,\n  PipelineErrorCause,\n  PipelineStepCompleteReport,\n  PipelineStepSkippedReport,\n  PipelineStepCancelledReport,\n  PipelineStepFailedReport,\n  PipelineStepReport,\n  PipelineStepReportStatus,\n  PipelineRunStatus,\n  PipelineRun,\n  PipelineStepSkipReason,\n  StepSkipDecision,\n  PipelineStepStatus,\n  PipelineStepLifecycleStatus,\n  PipelineStepPlannedEvent,\n  PipelineStepStartEvent,\n  PipelineStepProgressEvent,\n  PipelineStepCancelledEvent,\n  PipelineStepFailedEvent,\n  PipelineStepSkippedEvent,\n  PipelineStepCompleteEvent,\n  PipelineHooks,\n  PipelineStepSelectionReason,\n  PipelinePlanStep,\n  PipelinePlan,\n  PipelineMermaidDirection,\n  PipelineMermaidOptions,\n  Pipeline,\n  PipelineInput,\n  PipelineResult,\n} from \"./pipeline-types.js\";\n\nexport type { PipelineDefinition } from \"./pipeline-definition.js\";\n\nexport type { Step, MappedChildProgressOptions } from \"./pipeline-steps.js\";\n\ntype DuplicateStepIds<\n  TSteps extends readonly AnyStep[],\n  TSeen extends string = never,\n> = TSteps extends readonly [infer THead, ...infer TTail]\n  ? THead extends AnyStep\n    ? TTail extends readonly AnyStep[]\n      ? THead[\"id\"] extends TSeen\n        ? THead[\"id\"] | DuplicateStepIds<TTail, TSeen>\n        : DuplicateStepIds<TTail, TSeen | THead[\"id\"]>\n      : never\n    : never\n  : never;\n\ntype CheckedStepTuple<TSteps extends readonly AnyStep[]> =\n  string extends StepIds<TSteps>\n    ? unknown\n    : DuplicateStepIds<TSteps> extends never\n      ? unknown\n      : {\n          /** Compile-time diagnostic: every literal step ID in a definition must be unique. */\n          readonly __duplicateStepIds: DuplicateStepIds<TSteps>;\n        };\n\nfunction normalizeRunControls<TStepId extends string, TTargetId extends string>(\n  controls: PipelineRunControls<TStepId, TTargetId>\n): PipelineRunControls<TStepId, TTargetId> {\n  const { cache, continueOnError, dryRun, maxConcurrency, stepIds, targets } = controls;\n  const snapshot: PipelineRunControls<TStepId, TTargetId> = {};\n  if (cache !== undefined) snapshot.cache = cache;\n  if (continueOnError !== undefined) snapshot.continueOnError = continueOnError;\n  if (dryRun !== undefined) snapshot.dryRun = dryRun;\n  if (maxConcurrency !== undefined) snapshot.maxConcurrency = maxConcurrency;\n  if (stepIds !== undefined) snapshot.stepIds = [...stepIds];\n  if (targets !== undefined) snapshot.targets = [...targets];\n  return snapshot;\n}\n\n/**\n * Compile a typed step graph into a validated, executable pipeline.\n * Prefer inferred type arguments to preserve the literal id. For an explicit\n * result contract, annotate the finalizer's return type; partially supplied type\n * arguments use defaults for remaining parameters, including the id's string type.\n */\nexport function definePipeline<\n  const TSteps extends readonly AnyStep[],\n  TResult = DefaultPipelineResult<TSteps>,\n  const TTargets extends readonly TSteps[number][] = DefaultPipelineTargets<TSteps>,\n  const TResultSchema extends StandardSchemaV1 | undefined = undefined,\n  const TId extends string = string,\n>(\n  definition: PipelineDefinition<TSteps, TResult, TTargets, TResultSchema> &\n    CheckedStepTuple<TSteps> & { readonly id: TId }\n): Pipeline<\n  StepsInputOptions<TSteps>,\n  TResultSchema extends StandardSchemaV1 ? InferSchemaOutput<TResultSchema> : TResult,\n  StepIds<TSteps>,\n  TargetIds<TTargets>,\n  TId\n> & {\n  readonly definition: PipelineDefinitionSnapshot;\n  readonly optionsSchema: StepsOptionsSchema<TSteps>;\n} {\n  const compiled = compilePipeline<TSteps, TResult, TTargets, TResultSchema>(definition);\n  type TInputOptions = StepsInputOptions<TSteps>;\n  type TPipelineResult = TResultSchema extends StandardSchemaV1\n    ? InferSchemaOutput<TResultSchema>\n    : TResult;\n  type TStepId = StepIds<TSteps>;\n  type TTargetId = TargetIds<TTargets>;\n  // SAFETY: each compiled step id is a string key of `TSteps`.\n  const stepIds = compiled.stepIds as readonly TStepId[];\n  // SAFETY: each compiled target id is a string key of `TTargets`.\n  const targetIds = compiled.targetIds as readonly TTargetId[];\n\n  function prepareRun(controls: PipelineRunControls<TStepId, TTargetId>): {\n    controls: PipelineRunControls<TStepId, TTargetId>;\n    plan: PipelinePlan;\n  } {\n    const normalizedControls = normalizeRunControls(controls);\n    return {\n      controls: normalizedControls,\n      plan: buildPipelinePlan(compiled, normalizedControls),\n    };\n  }\n\n  function plan(controls: PipelineRunControls<TStepId, TTargetId> = {}): PipelinePlan {\n    return prepareRun(controls).plan;\n  }\n\n  function toMermaid(options: PipelineMermaidOptions = {}): string {\n    return renderPipelineMermaid(compiled.orderedSteps, options, compiled.stepGraph);\n  }\n\n  async function executeCompiled(\n    runPlan: PipelinePlan,\n    options: TInputOptions,\n    controls: PipelineRunControls<TStepId, TTargetId>,\n    context: Partial<PipelineContext> = defaultPipelineContext(),\n    overrides?: ReadonlyMap<AnyStep, unknown>\n  ): Promise<PipelineRun<TPipelineResult>> {\n    return executePlannedRun({\n      compiled,\n      controls,\n      domainOptions: options,\n      plan: runPlan,\n      runtime: resolvePipelineRuntime(context),\n      overrides,\n    });\n  }\n\n  async function run(\n    options?: TInputOptions,\n    controls: PipelineRunControls<TStepId, TTargetId> = {},\n    context: Partial<PipelineContext> = defaultPipelineContext()\n  ): Promise<PipelineRun<TPipelineResult>> {\n    const prepared = prepareRun(controls);\n    // SAFETY: the public signature permits omission only when {} satisfies the\n    // input type. Schemas still validate the default object during execution.\n    const input = options === undefined ? ({} as TInputOptions) : options;\n    return executeCompiled(prepared.plan, input, prepared.controls, context);\n  }\n\n  async function runOrThrow(\n    options?: TInputOptions,\n    controls: PipelineRunControls<TStepId, TTargetId> = {},\n    context: Partial<PipelineContext> = defaultPipelineContext()\n  ): Promise<TPipelineResult> {\n    const result = await run(options, controls, context);\n    if (result.status !== \"completed\") {\n      throw new PipelineExecutionError(result);\n    }\n    // SAFETY: a completed run always carries its `TPipelineResult` value.\n    return result.value as TPipelineResult;\n  }\n\n  const pipeline = {\n    id: definition.id,\n    ...(definition.name === undefined ? {} : { name: definition.name }),\n    ...(definition.description === undefined ? {} : { description: definition.description }),\n    ...(compiled.definition.metadata === undefined\n      ? {}\n      : { metadata: compiled.definition.metadata }),\n    definition: compiled.definition,\n    // SAFETY: compilation verifies that every step belongs to the same options schema.\n    optionsSchema: compiled.optionsSchema as StepsOptionsSchema<TSteps> &\n      (StandardSchemaV1 | undefined),\n    stepIds,\n    targetIds,\n    plan,\n    run,\n    runOrThrow,\n    toMermaid,\n  };\n  Object.defineProperty(pipeline, EXECUTE_COMPILED_RUN, { value: executeCompiled });\n  Object.defineProperty(pipeline, EXECUTE_TEST_RUN, {\n    value: (\n      options: TInputOptions,\n      controls: PipelineRunControls<TStepId, TTargetId>,\n      context: Partial<PipelineContext>,\n      overrides: ReadonlyMap<AnyStep, unknown>\n    ) => {\n      const resolved = new Map<AnyStep, unknown>();\n      for (const [step, value] of overrides) {\n        const compiledStep = compiled.compiledByAuthorStep.get(step);\n        if (!compiledStep)\n          throw new TypeError(\n            `Override step ${step.id} does not belong to pipeline ${compiled.id}`\n          );\n        resolved.set(compiledStep, value);\n      }\n      const prepared = prepareRun(controls);\n      return executeCompiled(\n        prepared.plan,\n        options === undefined ? ({} as TInputOptions) : options,\n        prepared.controls,\n        context,\n        resolved\n      );\n    },\n  });\n  brandCompiledPipeline(pipeline);\n  return pipeline;\n}\n\nexport type {\n  ArtifactJsonValue,\n  ArtifactMetadata,\n  ArtifactRecord,\n} from \"../tracing/artifact-metadata.js\";\nexport type { ArtifactLoader, ArtifactSaver, ArtifactResult } from \"./pipeline-artifacts.js\";\n\nexport { querySteps } from \"./pipeline-query.js\";\nexport type { PipelineStepQuery } from \"./pipeline-query.js\";\nexport type { PipelineMetadata, PipelineMetadataValue } from \"../tracing/graph-metadata.js\";\n"]}

package/dist/node/node.d.ts

@@ -4,3 +4,4 @@ export { readJson, resetDir, writeJson } from "./file-utils.js";
 export { definePaths } from "./paths.js";
 export { createWorkerThreadAdapter, type WorkerThreadAdapter, type WorkerThreadAdapterOptions, } from "./worker-thread-adapter.js";
 export type { WorkerThreadContext } from "./worker-thread-protocol.js";
+export { createFileStepCache, v8StepCacheCodec } from "../utilities/cache-storage.js";