tubeless 0.2.12 → 0.2.13

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

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

package/dist/core/pipeline.d.ts

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

package/dist/core/pipeline.js

@@ -1,9 +1,10 @@
-import { defaultPipelineContext, executePlannedRun, PipelineExecutionError, resolvePipelineRuntime, } from "./pipeline-execute.js";
+import { PipelineExecutionError } from "./pipeline-execution-error.js";
+import { defaultPipelineContext, executePlannedRun, resolvePipelineRuntime, } from "./pipeline-execute.js";
 import { RUN_MODEL_VERSION } from "./pipeline-ids.js";
 import { compilePipeline } from "./pipeline-compiler.js";
 import { PipelineDefinitionError } from "./pipeline-errors.js";
 import { requireOutputs } from "./pipeline-finalizer.js";
-import { brandCompiledPipeline, EXECUTE_COMPILED_RUN } from "./pipeline-identity.js";
+import { brandCompiledPipeline, EXECUTE_COMPILED_RUN, EXECUTE_TEST_RUN, } from "./pipeline-identity.js";
 import { renderPipelineMermaid } from "./pipeline-mermaid.js";
 import { buildPipelinePlan } from "./pipeline-plan.js";
 export { PipelineExecutionError, RUN_MODEL_VERSION };
@@ -50,13 +51,14 @@ export function definePipeline(definition) {
     function toMermaid(options = {}) {
         return renderPipelineMermaid(compiled.orderedSteps, options, compiled.stepGraph);
     }
-    async function executeCompiled(runPlan, options, controls, context = defaultPipelineContext()) {
+    async function executeCompiled(runPlan, options, controls, context = defaultPipelineContext(), overrides) {
         return executePlannedRun({
             compiled,
             controls,
             domainOptions: options,
             plan: runPlan,
             runtime: resolvePipelineRuntime(context),
+            overrides,
         });
     }
     async function run(options, controls = {}, context = defaultPipelineContext()) {
@@ -89,6 +91,19 @@ export function definePipeline(definition) {
         toMermaid,
     };
     Object.defineProperty(pipeline, EXECUTE_COMPILED_RUN, { value: executeCompiled });
+    Object.defineProperty(pipeline, EXECUTE_TEST_RUN, {
+        value: (options, controls, context, overrides) => {
+            const resolved = new Map();
+            for (const [step, value] of overrides) {
+                const compiledStep = compiled.compiledByAuthorStep.get(step);
+                if (!compiledStep)
+                    throw new TypeError(`Override step ${step.id} does not belong to pipeline ${compiled.id}`);
+                resolved.set(compiledStep, value);
+            }
+            const prepared = prepareRun(controls);
+            return executeCompiled(prepared.plan, options === undefined ? {} : options, prepared.controls, context, resolved);
+        },
+    });
     brandCompiledPipeline(pipeline);
     return pipeline;
 }

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 {\n  defaultPipelineContext,\n  executePlannedRun,\n  PipelineExecutionError,\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 { brandCompiledPipeline, EXECUTE_COMPILED_RUN } 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 { 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  ): Promise<PipelineRun<TPipelineResult>> {\n    return executePlannedRun({\n      compiled,\n      controls,\n      domainOptions: options,\n      plan: runPlan,\n      runtime: resolvePipelineRuntime(context),\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  brandCompiledPipeline(pipeline);\n  return pipeline;\n}\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 { 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"]}

package/dist/project/project-compiler.d.ts

@@ -1,6 +1,8 @@
-import { type MappedChildProgressOptions, type Pipeline, type PipelineExecutionContext, type PipelineRun, type PipelineRunControls, type PipelineStepContext, type StandardSchemaV1, type StepSkipDecision } from "../core/pipeline.js";
+import { type Pipeline } from "../core/pipeline.js";
+import { type ProjectRegistry } from "./project-registry.js";
 import { PipelineDocumentError, type PipelineDocumentMetadata } from "./project-document.js";
 export { PipelineDocumentError };
+export type { ProjectRegistry } from "./project-registry.js";
 /** Immutable compiled pipelines and descriptive metadata from a parsed document. */
 export interface CompiledPipelineDocument {
     readonly pipelines: readonly Pipeline<object, unknown>[];
@@ -8,36 +10,6 @@ export interface CompiledPipelineDocument {
     /** Return the shared compiled instance, or throw if the document has no such id. */
     get(id: string): Pipeline<object, unknown>;
 }
-/** Dependency values are checked at runtime rather than inferred from a project document. */
-type PipelineDocumentHandler = (inputs: Record<string, unknown>, context: PipelineStepContext<object>) => unknown;
-type PipelineDocumentFinalizer = (outputs: Record<string, unknown>, context: PipelineExecutionContext<object>) => unknown;
-type PipelineDocumentSkipPredicate = (inputs: Record<string, unknown>, context: PipelineExecutionContext<object>) => StepSkipDecision | Promise<StepSkipDecision>;
-/** Application-owned wiring for one declarative `fromPipeline` step. */
-interface PipelineDocumentFromPipelineAdapter {
-    controls?: PipelineRunControls | ((inputs: Record<string, unknown>, context: PipelineExecutionContext<object>) => PipelineRunControls);
-    mapOptions(inputs: Record<string, unknown>, context: PipelineExecutionContext<object>): object;
-    mapResult?(value: unknown, result: PipelineRun<unknown>, context: PipelineStepContext<object>): unknown;
-}
-/** Application-owned wiring for one declarative `forEachPipeline` step. */
-interface PipelineDocumentForEachPipelineAdapter {
-    controls?: PipelineRunControls | ((item: unknown, index: number, inputs: Record<string, unknown>, context: PipelineExecutionContext<object>) => PipelineRunControls);
-    items(inputs: Record<string, unknown>, context: PipelineExecutionContext<object>): readonly unknown[] | Promise<readonly unknown[]>;
-    key(item: unknown, index: number): string;
-    concurrency?: number | ((inputs: Record<string, unknown>, context: PipelineExecutionContext<object>) => number);
-    progress?: MappedChildProgressOptions;
-    mapOptions(item: unknown, index: number, inputs: Record<string, unknown>, context: PipelineExecutionContext<object>): object;
-    mapResult?(value: unknown, result: PipelineRun<unknown>, item: unknown, index: number, context: PipelineStepContext<object>): unknown;
-}
-/** Only explicitly registered functions and schemas can be referenced by a document. */
-export interface ProjectRegistry {
-    steps: Readonly<Record<string, PipelineDocumentHandler>>;
-    finalizers: Readonly<Record<string, PipelineDocumentFinalizer>>;
-    skipPredicates?: Readonly<Record<string, PipelineDocumentSkipPredicate>>;
-    fromPipelineAdapters?: Readonly<Record<string, PipelineDocumentFromPipelineAdapter>>;
-    forEachPipelineAdapters?: Readonly<Record<string, PipelineDocumentForEachPipelineAdapter>>;
-    optionsSchemas?: Readonly<Record<string, StandardSchemaV1<object, object>>>;
-    schemas?: Readonly<Record<string, StandardSchemaV1>>;
-}
 /**
  * Compile parsed YAML or JSON into ordinary pipelines. Does not load modules,
  * invoke handlers or schemas, or perform I/O. Graph validation belongs to core.

package/dist/project/project-compiler.js

@@ -1,91 +1,15 @@
-import { createSteps, definePipeline, requireOutputs, } from "../core/pipeline.js";
+import { definePipeline, requireOutputs } from "../core/pipeline.js";
+import { ProjectRegistryResolver } from "./project-registry.js";
+import { compileDocumentSteps } from "./project-step-graph.js";
 import { validatePipelineDocument, PipelineDocumentError, } from "./project-document.js";
 export { PipelineDocumentError };
-function resolve(registry, name, path) {
-    if (!registry || !Object.hasOwn(registry, name)) {
-        throw new PipelineDocumentError(path, `Unknown registered name ${JSON.stringify(name)}`);
-    }
-    return registry[name];
-}
-function handler(registry, name, path) {
-    const value = resolve(registry, name, path);
-    if (typeof value !== "function")
-        throw new PipelineDocumentError(path, "Expected a registered function");
-    return value;
-}
-function schema(registry, name, path) {
-    if (name === undefined)
-        return undefined;
-    const value = resolve(registry, name, path);
-    if (!value ||
-        value["~standard"]?.version !== 1 ||
-        typeof value["~standard"].validate !== "function") {
-        throw new PipelineDocumentError(path, "Expected a Standard Schema v1 schema");
-    }
-    return value;
-}
-function registeredObject(registry, name, path) {
-    const value = resolve(registry, name, path);
-    if (typeof value !== "object" || value === null || Array.isArray(value)) {
-        throw new PipelineDocumentError(path, "Expected a registered adapter object");
-    }
-    return value;
-}
-function fromPipelineAdapter(registry, name, path) {
-    const adapter = registeredObject(registry, name, path);
-    if (typeof adapter.mapOptions !== "function") {
-        throw new PipelineDocumentError(path, "Expected an adapter with mapOptions");
-    }
-    if (adapter.controls !== undefined &&
-        typeof adapter.controls !== "function" &&
-        (typeof adapter.controls !== "object" || adapter.controls === null)) {
-        throw new PipelineDocumentError(path, "Expected adapter controls to be an object or function");
-    }
-    if (adapter.mapResult !== undefined && typeof adapter.mapResult !== "function") {
-        throw new PipelineDocumentError(path, "Expected adapter mapResult to be a function");
-    }
-    return {
-        controls: adapter.controls,
-        mapOptions: adapter.mapOptions,
-        mapResult: adapter.mapResult,
-    };
-}
-function forEachPipelineAdapter(registry, name, path) {
-    const adapter = registeredObject(registry, name, path);
-    if (typeof adapter.items !== "function" ||
-        typeof adapter.key !== "function" ||
-        typeof adapter.mapOptions !== "function") {
-        throw new PipelineDocumentError(path, "Expected an adapter with items, key, and mapOptions");
-    }
-    if (adapter.concurrency !== undefined &&
-        typeof adapter.concurrency !== "number" &&
-        typeof adapter.concurrency !== "function") {
-        throw new PipelineDocumentError(path, "Expected adapter concurrency to be a number or function");
-    }
-    if (adapter.controls !== undefined &&
-        typeof adapter.controls !== "function" &&
-        (typeof adapter.controls !== "object" || adapter.controls === null)) {
-        throw new PipelineDocumentError(path, "Expected adapter controls to be an object or function");
-    }
-    if (adapter.mapResult !== undefined && typeof adapter.mapResult !== "function") {
-        throw new PipelineDocumentError(path, "Expected adapter mapResult to be a function");
-    }
-    return {
-        items: adapter.items,
-        key: adapter.key,
-        controls: adapter.controls,
-        concurrency: adapter.concurrency,
-        progress: adapter.progress,
-        mapOptions: adapter.mapOptions,
-        mapResult: adapter.mapResult,
-    };
-}
 /**
  * Compile parsed YAML or JSON into ordinary pipelines. Does not load modules,
  * invoke handlers or schemas, or perform I/O. Graph validation belongs to core.
  */
 export function compilePipelineDocument(document, registry) {
     const parsed = validatePipelineDocument(document);
+    const resolvedRegistry = new ProjectRegistryResolver(registry);
     const compiled = new Map();
     const compiling = new Set();
     const resolvePipeline = (id, path) => {
@@ -104,112 +28,19 @@ export function compilePipelineDocument(document, registry) {
         const definition = parsed.pipelines[id];
         const path = `$.pipelines[${JSON.stringify(id)}]`;
         compiling.add(id);
-        const optionsSchema = schema(registry.optionsSchemas, definition.optionsSchema, `${path}.optionsSchema`);
-        const factory = createSteps(optionsSchema);
-        const entries = definition.steps.map((definition, index) => {
-            const stepPath = `${path}.steps[${index}]`;
-            // Populate these arrays after all steps exist, allowing forward references
-            // and leaving cycle detection to the existing definition validator.
-            const dependsOn = [];
-            const optionalDependsOn = [];
-            const skipAfterFailureOf = [];
-            const dryRun = definition.dryRun === undefined || definition.dryRun === "skip"
-                ? definition.dryRun
-                : handler(registry.steps, definition.dryRun.run, `${stepPath}.dryRun.run`);
-            const outputSchema = schema(registry.schemas, definition.outputSchema, `${stepPath}.outputSchema`);
-            const common = {
-                name: definition.name,
-                description: definition.description,
-                dependsOn,
-                optionalDependsOn,
-                skipAfterFailureOf,
-            };
-            const skip = definition.skip === undefined
-                ? undefined
-                : handler(registry.skipPredicates ?? {}, definition.skip, `${stepPath}.skip`);
-            let built;
-            if (definition.run !== undefined) {
-                const config = {
-                    ...common,
-                    dryRun,
-                    run: handler(registry.steps, definition.run, `${stepPath}.run`),
-                    skip,
-                };
-                built = outputSchema
-                    ? factory.step(definition.id, { ...config, outputSchema })
-                    : factory.step(definition.id, config);
-            }
-            else if (definition.fromPipeline !== undefined) {
-                const reference = definition.fromPipeline;
-                const adapter = fromPipelineAdapter(registry.fromPipelineAdapters, reference.adapter, `${stepPath}.fromPipeline.adapter`);
-                const config = {
-                    ...common,
-                    dryRun: definition.dryRun,
-                    pipeline: resolvePipeline(reference.pipeline, `${stepPath}.fromPipeline.pipeline`),
-                    controls: adapter.controls,
-                    mapOptions: adapter.mapOptions,
-                    skip,
-                };
-                built =
-                    adapter.mapResult === undefined
-                        ? factory.fromPipeline(definition.id, config)
-                        : factory.fromPipeline(definition.id, { ...config, mapResult: adapter.mapResult });
-            }
-            else {
-                const reference = definition.forEachPipeline;
-                const adapter = forEachPipelineAdapter(registry.forEachPipelineAdapters, reference.adapter, `${stepPath}.forEachPipeline.adapter`);
-                // SAFETY: document pipelines publish unknown values. The fan-out builder
-                // still represents a valued skip as the complete unknown result array.
-                const fanOutSkip = skip;
-                const config = {
-                    ...common,
-                    dryRun: definition.dryRun,
-                    pipeline: resolvePipeline(reference.pipeline, `${stepPath}.forEachPipeline.pipeline`),
-                    items: adapter.items,
-                    key: adapter.key,
-                    concurrency: adapter.concurrency,
-                    controls: adapter.controls,
-                    progress: adapter.progress,
-                    mapOptions: adapter.mapOptions,
-                    skip: fanOutSkip,
-                };
-                built =
-                    adapter.mapResult === undefined
-                        ? factory.forEachPipeline(definition.id, config)
-                        : factory.forEachPipeline(definition.id, { ...config, mapResult: adapter.mapResult });
-            }
-            return {
-                definition,
-                path: stepPath,
-                dependsOn,
-                optionalDependsOn,
-                skipAfterFailureOf,
-                step: built,
-            };
-        });
-        const byId = new Map(entries.map((entry) => [entry.step.id, entry.step]));
-        const resolveSteps = (ids = [], fieldPath) => ids.map((stepId, index) => {
-            const found = byId.get(stepId);
-            if (!found)
-                throw new PipelineDocumentError(`${fieldPath}[${index}]`, `Unknown step ${JSON.stringify(stepId)}`);
-            return found;
-        });
-        for (const entry of entries) {
-            for (const field of ["dependsOn", "optionalDependsOn", "skipAfterFailureOf"]) {
-                entry[field].push(...resolveSteps(entry.definition[field], `${entry.path}.${field}`));
-            }
-        }
-        const finalize = handler(registry.finalizers, definition.finalize.run, `${path}.finalize.run`);
+        const optionsSchema = resolvedRegistry.optionsSchema(definition.optionsSchema, `${path}.optionsSchema`);
+        const graph = compileDocumentSteps(definition.steps, optionsSchema, resolvedRegistry, resolvePipeline, path);
+        const finalize = resolvedRegistry.finalizer(definition.finalize.run, `${path}.finalize.run`);
         const pipeline = definePipeline({
             id,
             name: definition.name,
             description: definition.description,
-            steps: entries.map((entry) => entry.step),
-            targets: resolveSteps(definition.targets, `${path}.targets`),
-            resultSchema: schema(registry.schemas, definition.resultSchema, `${path}.resultSchema`),
+            steps: graph.steps,
+            targets: graph.resolve(definition.targets, `${path}.targets`),
+            resultSchema: resolvedRegistry.outputSchema(definition.resultSchema, `${path}.resultSchema`),
             finalize: definition.finalize.requireOutputs === undefined
                 ? finalize
-                : requireOutputs(resolveSteps(definition.finalize.requireOutputs, `${path}.finalize.requireOutputs`), finalize),
+                : requireOutputs(graph.resolve(definition.finalize.requireOutputs, `${path}.finalize.requireOutputs`), finalize),
         });
         compiled.set(id, pipeline);
         compiling.delete(id);

package/dist/project/project-compiler.js.map

@@ -1 +1 @@
-{"version":3,"file":"project-compiler.js","sourceRoot":"","sources":["../../src/project/project-compiler.ts"],"names":[],"mappings":"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","sourcesContent":["import {\n  createSteps,\n  definePipeline,\n  requireOutputs,\n  type MappedChildProgressOptions,\n  type Pipeline,\n  type PipelineExecutionContext,\n  type PipelineRun,\n  type PipelineRunControls,\n  type PipelineStepContext,\n  type StandardSchemaV1,\n  type StepSkipDecision,\n} from \"../core/pipeline.js\";\nimport type { AnyStep } from \"../core/pipeline-steps.js\";\nimport {\n  validatePipelineDocument,\n  PipelineDocumentError,\n  type PipelineDocumentMetadata,\n} from \"./project-document.js\";\n\nexport { PipelineDocumentError };\n\n/** Immutable compiled pipelines and descriptive metadata from a parsed document. */\nexport interface CompiledPipelineDocument {\n  readonly pipelines: readonly Pipeline<object, unknown>[];\n  readonly metadata?: PipelineDocumentMetadata;\n  /** Return the shared compiled instance, or throw if the document has no such id. */\n  get(id: string): Pipeline<object, unknown>;\n}\n\n/** Dependency values are checked at runtime rather than inferred from a project document. */\ntype PipelineDocumentHandler = (\n  inputs: Record<string, unknown>,\n  context: PipelineStepContext<object>\n) => unknown;\n\ntype PipelineDocumentFinalizer = (\n  outputs: Record<string, unknown>,\n  context: PipelineExecutionContext<object>\n) => unknown;\n\ntype PipelineDocumentSkipPredicate = (\n  inputs: Record<string, unknown>,\n  context: PipelineExecutionContext<object>\n) => StepSkipDecision | Promise<StepSkipDecision>;\n\n/** Application-owned wiring for one declarative `fromPipeline` step. */\ninterface PipelineDocumentFromPipelineAdapter {\n  controls?:\n    | PipelineRunControls\n    | ((\n        inputs: Record<string, unknown>,\n        context: PipelineExecutionContext<object>\n      ) => PipelineRunControls);\n  mapOptions(inputs: Record<string, unknown>, context: PipelineExecutionContext<object>): object;\n  mapResult?(\n    value: unknown,\n    result: PipelineRun<unknown>,\n    context: PipelineStepContext<object>\n  ): unknown;\n}\n\n/** Application-owned wiring for one declarative `forEachPipeline` step. */\ninterface PipelineDocumentForEachPipelineAdapter {\n  controls?:\n    | PipelineRunControls\n    | ((\n        item: unknown,\n        index: number,\n        inputs: Record<string, unknown>,\n        context: PipelineExecutionContext<object>\n      ) => PipelineRunControls);\n  items(\n    inputs: Record<string, unknown>,\n    context: PipelineExecutionContext<object>\n  ): readonly unknown[] | Promise<readonly unknown[]>;\n  key(item: unknown, index: number): string;\n  concurrency?:\n    | number\n    | ((inputs: Record<string, unknown>, context: PipelineExecutionContext<object>) => number);\n  progress?: MappedChildProgressOptions;\n  mapOptions(\n    item: unknown,\n    index: number,\n    inputs: Record<string, unknown>,\n    context: PipelineExecutionContext<object>\n  ): object;\n  mapResult?(\n    value: unknown,\n    result: PipelineRun<unknown>,\n    item: unknown,\n    index: number,\n    context: PipelineStepContext<object>\n  ): unknown;\n}\n\n/** Only explicitly registered functions and schemas can be referenced by a document. */\nexport interface ProjectRegistry {\n  steps: Readonly<Record<string, PipelineDocumentHandler>>;\n  finalizers: Readonly<Record<string, PipelineDocumentFinalizer>>;\n  skipPredicates?: Readonly<Record<string, PipelineDocumentSkipPredicate>>;\n  fromPipelineAdapters?: Readonly<Record<string, PipelineDocumentFromPipelineAdapter>>;\n  forEachPipelineAdapters?: Readonly<Record<string, PipelineDocumentForEachPipelineAdapter>>;\n  optionsSchemas?: Readonly<Record<string, StandardSchemaV1<object, object>>>;\n  schemas?: Readonly<Record<string, StandardSchemaV1>>;\n}\n\nfunction resolve<T>(\n  registry: Readonly<Record<string, T>> | undefined,\n  name: string,\n  path: string\n): T {\n  if (!registry || !Object.hasOwn(registry, name)) {\n    throw new PipelineDocumentError(path, `Unknown registered name ${JSON.stringify(name)}`);\n  }\n  return registry[name];\n}\n\nfunction handler<T extends PipelineDocumentHandler | PipelineDocumentFinalizer>(\n  registry: Readonly<Record<string, T>>,\n  name: string,\n  path: string\n): T {\n  const value = resolve(registry, name, path);\n  if (typeof value !== \"function\")\n    throw new PipelineDocumentError(path, \"Expected a registered function\");\n  return value;\n}\n\nfunction schema<T extends StandardSchemaV1>(\n  registry: Readonly<Record<string, T>> | undefined,\n  name: string | undefined,\n  path: string\n): T | undefined {\n  if (name === undefined) return undefined;\n  const value = resolve(registry, name, path);\n  if (\n    !value ||\n    value[\"~standard\"]?.version !== 1 ||\n    typeof value[\"~standard\"].validate !== \"function\"\n  ) {\n    throw new PipelineDocumentError(path, \"Expected a Standard Schema v1 schema\");\n  }\n  return value;\n}\n\nfunction registeredObject<T extends object>(\n  registry: Readonly<Record<string, T>> | undefined,\n  name: string,\n  path: string\n): T {\n  const value = resolve(registry, name, path);\n  if (typeof value !== \"object\" || value === null || Array.isArray(value)) {\n    throw new PipelineDocumentError(path, \"Expected a registered adapter object\");\n  }\n  return value;\n}\n\nfunction fromPipelineAdapter(\n  registry: ProjectRegistry[\"fromPipelineAdapters\"],\n  name: string,\n  path: string\n): PipelineDocumentFromPipelineAdapter {\n  const adapter = registeredObject(registry, name, path);\n  if (typeof adapter.mapOptions !== \"function\") {\n    throw new PipelineDocumentError(path, \"Expected an adapter with mapOptions\");\n  }\n  if (\n    adapter.controls !== undefined &&\n    typeof adapter.controls !== \"function\" &&\n    (typeof adapter.controls !== \"object\" || adapter.controls === null)\n  ) {\n    throw new PipelineDocumentError(path, \"Expected adapter controls to be an object or function\");\n  }\n  if (adapter.mapResult !== undefined && typeof adapter.mapResult !== \"function\") {\n    throw new PipelineDocumentError(path, \"Expected adapter mapResult to be a function\");\n  }\n  return {\n    controls: adapter.controls,\n    mapOptions: adapter.mapOptions,\n    mapResult: adapter.mapResult,\n  };\n}\n\nfunction forEachPipelineAdapter(\n  registry: ProjectRegistry[\"forEachPipelineAdapters\"],\n  name: string,\n  path: string\n): PipelineDocumentForEachPipelineAdapter {\n  const adapter = registeredObject(registry, name, path);\n  if (\n    typeof adapter.items !== \"function\" ||\n    typeof adapter.key !== \"function\" ||\n    typeof adapter.mapOptions !== \"function\"\n  ) {\n    throw new PipelineDocumentError(path, \"Expected an adapter with items, key, and mapOptions\");\n  }\n  if (\n    adapter.concurrency !== undefined &&\n    typeof adapter.concurrency !== \"number\" &&\n    typeof adapter.concurrency !== \"function\"\n  ) {\n    throw new PipelineDocumentError(\n      path,\n      \"Expected adapter concurrency to be a number or function\"\n    );\n  }\n  if (\n    adapter.controls !== undefined &&\n    typeof adapter.controls !== \"function\" &&\n    (typeof adapter.controls !== \"object\" || adapter.controls === null)\n  ) {\n    throw new PipelineDocumentError(path, \"Expected adapter controls to be an object or function\");\n  }\n  if (adapter.mapResult !== undefined && typeof adapter.mapResult !== \"function\") {\n    throw new PipelineDocumentError(path, \"Expected adapter mapResult to be a function\");\n  }\n  return {\n    items: adapter.items,\n    key: adapter.key,\n    controls: adapter.controls,\n    concurrency: adapter.concurrency,\n    progress: adapter.progress,\n    mapOptions: adapter.mapOptions,\n    mapResult: adapter.mapResult,\n  };\n}\n\n/**\n * Compile parsed YAML or JSON into ordinary pipelines. Does not load modules,\n * invoke handlers or schemas, or perform I/O. Graph validation belongs to core.\n */\nexport function compilePipelineDocument(\n  document: unknown,\n  registry: ProjectRegistry\n): CompiledPipelineDocument {\n  const parsed = validatePipelineDocument(document);\n  const compiled = new Map<string, Pipeline<object, unknown>>();\n  const compiling = new Set<string>();\n\n  const resolvePipeline = (id: string, path: string): Pipeline<object, unknown> => {\n    if (!Object.hasOwn(parsed.pipelines, id)) {\n      throw new PipelineDocumentError(path, `Unknown pipeline ${JSON.stringify(id)}`);\n    }\n    if (compiling.has(id)) {\n      throw new PipelineDocumentError(\n        path,\n        `Pipeline composition cycle through ${JSON.stringify(id)}`\n      );\n    }\n    return compile(id);\n  };\n\n  const compile = (id: string): Pipeline<object, unknown> => {\n    const existing = compiled.get(id);\n    if (existing) return existing;\n    const definition = parsed.pipelines[id]!;\n    const path = `$.pipelines[${JSON.stringify(id)}]`;\n    compiling.add(id);\n    const optionsSchema = schema(\n      registry.optionsSchemas,\n      definition.optionsSchema,\n      `${path}.optionsSchema`\n    );\n    const factory = createSteps(optionsSchema);\n    const entries = definition.steps.map((definition, index) => {\n      const stepPath = `${path}.steps[${index}]`;\n      // Populate these arrays after all steps exist, allowing forward references\n      // and leaving cycle detection to the existing definition validator.\n      const dependsOn: AnyStep[] = [];\n      const optionalDependsOn: AnyStep[] = [];\n      const skipAfterFailureOf: AnyStep[] = [];\n      const dryRun =\n        definition.dryRun === undefined || definition.dryRun === \"skip\"\n          ? definition.dryRun\n          : handler(registry.steps, definition.dryRun.run, `${stepPath}.dryRun.run`);\n      const outputSchema = schema(\n        registry.schemas,\n        definition.outputSchema,\n        `${stepPath}.outputSchema`\n      );\n      const common = {\n        name: definition.name,\n        description: definition.description,\n        dependsOn,\n        optionalDependsOn,\n        skipAfterFailureOf,\n      };\n      const skip =\n        definition.skip === undefined\n          ? undefined\n          : handler(registry.skipPredicates ?? {}, definition.skip, `${stepPath}.skip`);\n      let built: AnyStep<object>;\n      if (definition.run !== undefined) {\n        const config = {\n          ...common,\n          dryRun,\n          run: handler(registry.steps, definition.run, `${stepPath}.run`),\n          skip,\n        };\n        built = outputSchema\n          ? factory.step(definition.id, { ...config, outputSchema })\n          : factory.step(definition.id, config);\n      } else if (definition.fromPipeline !== undefined) {\n        const reference = definition.fromPipeline;\n        const adapter = fromPipelineAdapter(\n          registry.fromPipelineAdapters,\n          reference.adapter,\n          `${stepPath}.fromPipeline.adapter`\n        );\n        const config = {\n          ...common,\n          dryRun: definition.dryRun,\n          pipeline: resolvePipeline(reference.pipeline, `${stepPath}.fromPipeline.pipeline`),\n          controls: adapter.controls,\n          mapOptions: adapter.mapOptions,\n          skip,\n        };\n        built =\n          adapter.mapResult === undefined\n            ? factory.fromPipeline(definition.id, config)\n            : factory.fromPipeline(definition.id, { ...config, mapResult: adapter.mapResult });\n      } else {\n        const reference = definition.forEachPipeline;\n        const adapter = forEachPipelineAdapter(\n          registry.forEachPipelineAdapters,\n          reference.adapter,\n          `${stepPath}.forEachPipeline.adapter`\n        );\n        // SAFETY: document pipelines publish unknown values. The fan-out builder\n        // still represents a valued skip as the complete unknown result array.\n        const fanOutSkip = skip as\n          | ((\n              inputs: Record<string, unknown>,\n              context: PipelineExecutionContext<object>\n            ) =>\n              | StepSkipDecision<readonly unknown[]>\n              | Promise<StepSkipDecision<readonly unknown[]>>)\n          | undefined;\n        const config = {\n          ...common,\n          dryRun: definition.dryRun,\n          pipeline: resolvePipeline(reference.pipeline, `${stepPath}.forEachPipeline.pipeline`),\n          items: adapter.items,\n          key: adapter.key,\n          concurrency: adapter.concurrency,\n          controls: adapter.controls,\n          progress: adapter.progress,\n          mapOptions: adapter.mapOptions,\n          skip: fanOutSkip,\n        };\n        built =\n          adapter.mapResult === undefined\n            ? factory.forEachPipeline(definition.id, config)\n            : factory.forEachPipeline(definition.id, { ...config, mapResult: adapter.mapResult });\n      }\n      return {\n        definition,\n        path: stepPath,\n        dependsOn,\n        optionalDependsOn,\n        skipAfterFailureOf,\n        step: built,\n      };\n    });\n    const byId = new Map(entries.map((entry) => [entry.step.id, entry.step]));\n    const resolveSteps = (ids: readonly string[] = [], fieldPath: string): AnyStep[] =>\n      ids.map((stepId, index) => {\n        const found = byId.get(stepId);\n        if (!found)\n          throw new PipelineDocumentError(\n            `${fieldPath}[${index}]`,\n            `Unknown step ${JSON.stringify(stepId)}`\n          );\n        return found;\n      });\n    for (const entry of entries) {\n      for (const field of [\"dependsOn\", \"optionalDependsOn\", \"skipAfterFailureOf\"] as const) {\n        entry[field].push(...resolveSteps(entry.definition[field], `${entry.path}.${field}`));\n      }\n    }\n    const finalize = handler(registry.finalizers, definition.finalize.run, `${path}.finalize.run`);\n    const pipeline = definePipeline({\n      id,\n      name: definition.name,\n      description: definition.description,\n      steps: entries.map((entry) => entry.step),\n      targets: resolveSteps(definition.targets, `${path}.targets`),\n      resultSchema: schema(registry.schemas, definition.resultSchema, `${path}.resultSchema`),\n      finalize:\n        definition.finalize.requireOutputs === undefined\n          ? finalize\n          : requireOutputs(\n              resolveSteps(definition.finalize.requireOutputs, `${path}.finalize.requireOutputs`),\n              finalize\n            ),\n    });\n    compiled.set(id, pipeline);\n    compiling.delete(id);\n    return pipeline;\n  };\n\n  const pipelines = Object.freeze(Object.keys(parsed.pipelines).map(compile));\n  const metadata =\n    parsed.metadata === undefined\n      ? undefined\n      : Object.freeze({\n          ...parsed.metadata,\n          authors:\n            parsed.metadata.authors === undefined\n              ? undefined\n              : Object.freeze([...parsed.metadata.authors]),\n        });\n  return Object.freeze({\n    pipelines,\n    ...(metadata === undefined ? {} : { metadata }),\n    get(id: string): Pipeline<object, unknown> {\n      const pipeline = compiled.get(id);\n      if (!pipeline) {\n        throw new Error(`Compiled document does not define pipeline ${JSON.stringify(id)}.`);\n      }\n      return pipeline;\n    },\n  });\n}\n"]}
+{"version":3,"file":"project-compiler.js","sourceRoot":"","sources":["../../src/project/project-compiler.ts"],"names":[],"mappings":"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","sourcesContent":["import { definePipeline, requireOutputs, type Pipeline } from \"../core/pipeline.js\";\nimport { ProjectRegistryResolver, type ProjectRegistry } from \"./project-registry.js\";\nimport { compileDocumentSteps } from \"./project-step-graph.js\";\nimport {\n  validatePipelineDocument,\n  PipelineDocumentError,\n  type PipelineDocumentMetadata,\n} from \"./project-document.js\";\n\nexport { PipelineDocumentError };\nexport type { ProjectRegistry } from \"./project-registry.js\";\n\n/** Immutable compiled pipelines and descriptive metadata from a parsed document. */\nexport interface CompiledPipelineDocument {\n  readonly pipelines: readonly Pipeline<object, unknown>[];\n  readonly metadata?: PipelineDocumentMetadata;\n  /** Return the shared compiled instance, or throw if the document has no such id. */\n  get(id: string): Pipeline<object, unknown>;\n}\n\n/**\n * Compile parsed YAML or JSON into ordinary pipelines. Does not load modules,\n * invoke handlers or schemas, or perform I/O. Graph validation belongs to core.\n */\nexport function compilePipelineDocument(\n  document: unknown,\n  registry: ProjectRegistry\n): CompiledPipelineDocument {\n  const parsed = validatePipelineDocument(document);\n  const resolvedRegistry = new ProjectRegistryResolver(registry);\n  const compiled = new Map<string, Pipeline<object, unknown>>();\n  const compiling = new Set<string>();\n\n  const resolvePipeline = (id: string, path: string): Pipeline<object, unknown> => {\n    if (!Object.hasOwn(parsed.pipelines, id)) {\n      throw new PipelineDocumentError(path, `Unknown pipeline ${JSON.stringify(id)}`);\n    }\n    if (compiling.has(id)) {\n      throw new PipelineDocumentError(\n        path,\n        `Pipeline composition cycle through ${JSON.stringify(id)}`\n      );\n    }\n    return compile(id);\n  };\n\n  const compile = (id: string): Pipeline<object, unknown> => {\n    const existing = compiled.get(id);\n    if (existing) return existing;\n    const definition = parsed.pipelines[id]!;\n    const path = `$.pipelines[${JSON.stringify(id)}]`;\n    compiling.add(id);\n    const optionsSchema = resolvedRegistry.optionsSchema(\n      definition.optionsSchema,\n      `${path}.optionsSchema`\n    );\n    const graph = compileDocumentSteps(\n      definition.steps,\n      optionsSchema,\n      resolvedRegistry,\n      resolvePipeline,\n      path\n    );\n    const finalize = resolvedRegistry.finalizer(definition.finalize.run, `${path}.finalize.run`);\n    const pipeline = definePipeline({\n      id,\n      name: definition.name,\n      description: definition.description,\n      steps: graph.steps,\n      targets: graph.resolve(definition.targets, `${path}.targets`),\n      resultSchema: resolvedRegistry.outputSchema(definition.resultSchema, `${path}.resultSchema`),\n      finalize:\n        definition.finalize.requireOutputs === undefined\n          ? finalize\n          : requireOutputs(\n              graph.resolve(definition.finalize.requireOutputs, `${path}.finalize.requireOutputs`),\n              finalize\n            ),\n    });\n    compiled.set(id, pipeline);\n    compiling.delete(id);\n    return pipeline;\n  };\n\n  const pipelines = Object.freeze(Object.keys(parsed.pipelines).map(compile));\n  const metadata =\n    parsed.metadata === undefined\n      ? undefined\n      : Object.freeze({\n          ...parsed.metadata,\n          authors:\n            parsed.metadata.authors === undefined\n              ? undefined\n              : Object.freeze([...parsed.metadata.authors]),\n        });\n  return Object.freeze({\n    pipelines,\n    ...(metadata === undefined ? {} : { metadata }),\n    get(id: string): Pipeline<object, unknown> {\n      const pipeline = compiled.get(id);\n      if (!pipeline) {\n        throw new Error(`Compiled document does not define pipeline ${JSON.stringify(id)}.`);\n      }\n      return pipeline;\n    },\n  });\n}\n"]}