tubeless 0.3.2 → 0.3.3

package/dist/core/pipeline-finalizer.js

@@ -1,3 +1,4 @@
+import { REQUIRED_OUTPUTS_MISSING_CODE } from "./pipeline-diagnostics.js";
 const REQUIRED_FINALIZER_OUTPUTS = Symbol("tubeless.requiredFinalizerOutputs");
 export function requiredFinalizerMetadata(finalize) {
     if (finalize && typeof finalize !== "function") {
@@ -18,7 +19,7 @@ export function requireOutputs(requiredSteps, finalize) {
     const invoke = (requiredStepIds, outputs, context) => {
         const missingStepIds = requiredStepIds.filter((stepId) => !Object.prototype.hasOwnProperty.call(outputs, stepId));
         if (missingStepIds.length > 0) {
-            throw new Error(`Required pipeline outputs missing: ${missingStepIds.join(", ")}`);
+            throw Object.assign(new Error(`Required pipeline outputs missing: ${missingStepIds.join(", ")}`), { code: REQUIRED_OUTPUTS_MISSING_CODE });
         }
         // SAFETY: every required step id was verified present above, so the partial
         // outputs contain all required keys and are a complete required-outputs map.

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

@@ -1 +1 @@
-{"version":3,"file":"pipeline-finalizer.js","sourceRoot":"","sources":["../../src/core/pipeline-finalizer.ts"],"names":[],"mappings":"AAIA,MAAM,0BAA0B,GAAkB,MAAM,CAAC,mCAAmC,CAAC,CAAC;AAW9F,MAAM,UAAU,yBAAyB,CACvC,QAAyE;IAEzE,IAAI,QAAQ,IAAI,OAAO,QAAQ,KAAK,UAAU,EAAE,CAAC;QAC/C,MAAM,EAAE,GAAG,QAAQ,CAAC,EAAE,CAAC;QACvB,OAAO,yBAAyB,CAC9B,cAAc,CAAC,CAAC,QAAQ,CAAC,EAAE,CAAC,OAAO,EAAE,EAAE,CAAC,OAAO,CAAC,EAAE,CAAC,CAAC,CACrD,CAAC;IACJ,CAAC;IACD,yEAAyE;IACzE,mEAAmE;IACnE,OACE,QACD,EAAE,CAAC,0BAA0B,CAAC,CAAC;AAClC,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,cAAc,CAC5B,aAA6B,EAC7B,QAG+B;IAK/B,MAAM,mBAAmB,GAAG,CAAC,GAAG,IAAI,GAAG,CAAC,aAAa,CAAC,CAAC,CAAC;IACxD,MAAM,MAAM,GAAG,CACb,eAAkC,EAClC,OAAyD,EACzD,OAA+D,EAC/D,EAAE;QACF,MAAM,cAAc,GAAG,eAAe,CAAC,MAAM,CAC3C,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC,MAAM,CAAC,SAAS,CAAC,cAAc,CAAC,IAAI,CAAC,OAAO,EAAE,MAAM,CAAC,CACnE,CAAC;QACF,IAAI,cAAc,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;YAC9B,MAAM,IAAI,KAAK,CAAC,sCAAsC,cAAc,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;QACrF,CAAC;QACD,4EAA4E;QAC5E,6EAA6E;QAC7E,OAAO,QAAQ,CAAC,OAA6D,EAAE,OAAO,CAAC,CAAC;IAC1F,CAAC,CAAC;IACF,MAAM,iBAAiB,GAAG,CACxB,OAAyD,EACzD,OAA+D,EAC/D,EAAE,CACF,MAAM,CACJ,mBAAmB,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,CAAC,EAAE,CAAC,EAC1C,OAAO,EACP,OAAO,CACR,CAAC;IACJ,MAAM,QAAQ,GAA4D,MAAM,CAAC,MAAM,CAAC;QACtF,OAAO,EAAE,CAAC,eAAkC,EAAE,EAAE;YAC9C,MAAM,QAAQ,GAAG,MAAM,CAAC,MAAM,CAAC,CAAC,GAAG,eAAe,CAAC,CAAC,CAAC;YACrD,OAAO,CACL,OAAyD,EACzD,OAA+D,EAC/D,EAAE,CAAC,MAAM,CAAC,QAAQ,EAAE,OAAO,EAAE,OAAO,CAAC,CAAC;QAC1C,CAAC;QACD,KAAK,EAAE,MAAM,CAAC,MAAM,CAAC,CAAC,GAAG,mBAAmB,CAAC,CAAC;KAC/C,CAAC,CAAC;IACH,MAAM,CAAC,cAAc,CAAC,iBAAiB,EAAE,0BAA0B,EAAE;QACnE,KAAK,EAAE,QAAQ;KAChB,CAAC,CAAC;IACH,OAAO,iBAAiB,CAAC;AAC3B,CAAC","sourcesContent":["import type { AnyStep, StepOutput } from \"./pipeline-steps.js\";\nimport type { StepsOptions } from \"./pipeline-definition.js\";\nimport type { PipelineExecutionContext } from \"./pipeline-types.js\";\n\nconst REQUIRED_FINALIZER_OUTPUTS: unique symbol = Symbol(\"tubeless.requiredFinalizerOutputs\");\n\nexport interface RequiredFinalizerMetadata<TOptions extends object> {\n  readonly steps: readonly AnyStep<TOptions>[];\n  compile(requiredStepIds: readonly string[]): (...args: never[]) => unknown;\n}\n\ntype RequiredPipelineOutputs<TSteps extends readonly AnyStep[]> = {\n  [S in TSteps[number] as S[\"id\"]]-?: StepOutput<S>;\n};\n\nexport function requiredFinalizerMetadata<TOptions extends object>(\n  finalize: AnyStep<TOptions> | ((...args: never[]) => unknown) | undefined\n): RequiredFinalizerMetadata<TOptions> | undefined {\n  if (finalize && typeof finalize !== \"function\") {\n    const id = finalize.id;\n    return requiredFinalizerMetadata<TOptions>(\n      requireOutputs([finalize], (outputs) => outputs[id])\n    );\n  }\n  // SAFETY: `requireOutputs` stamps internal compilation metadata onto the\n  // finalizer; the intersection only exposes that optional property.\n  return (\n    finalize as { [REQUIRED_FINALIZER_OUTPUTS]?: RequiredFinalizerMetadata<TOptions> } | undefined\n  )?.[REQUIRED_FINALIZER_OUTPUTS];\n}\n\n/**\n * Build a finalizer that only runs when every listed step published an output.\n * Presence is checked by output slot, so a successfully published `undefined`\n * remains distinct from a structural skip or failure.\n */\nexport function requireOutputs<const TRequiredSteps extends readonly AnyStep[], TResult>(\n  requiredSteps: TRequiredSteps,\n  finalize: (\n    outputs: RequiredPipelineOutputs<TRequiredSteps>,\n    context: PipelineExecutionContext<StepsOptions<TRequiredSteps>>\n  ) => TResult | Promise<TResult>\n): (\n  outputs: Partial<RequiredPipelineOutputs<TRequiredSteps>>,\n  context: PipelineExecutionContext<StepsOptions<TRequiredSteps>>\n) => TResult | Promise<TResult> {\n  const uniqueRequiredSteps = [...new Set(requiredSteps)];\n  const invoke = (\n    requiredStepIds: readonly string[],\n    outputs: Partial<RequiredPipelineOutputs<TRequiredSteps>>,\n    context: PipelineExecutionContext<StepsOptions<TRequiredSteps>>\n  ) => {\n    const missingStepIds = requiredStepIds.filter(\n      (stepId) => !Object.prototype.hasOwnProperty.call(outputs, stepId)\n    );\n    if (missingStepIds.length > 0) {\n      throw new Error(`Required pipeline outputs missing: ${missingStepIds.join(\", \")}`);\n    }\n    // SAFETY: every required step id was verified present above, so the partial\n    // outputs contain all required keys and are a complete required-outputs map.\n    return finalize(outputs as unknown as RequiredPipelineOutputs<TRequiredSteps>, context);\n  };\n  const requiredFinalizer = (\n    outputs: Partial<RequiredPipelineOutputs<TRequiredSteps>>,\n    context: PipelineExecutionContext<StepsOptions<TRequiredSteps>>\n  ) =>\n    invoke(\n      uniqueRequiredSteps.map((step) => step.id),\n      outputs,\n      context\n    );\n  const metadata: RequiredFinalizerMetadata<StepsOptions<TRequiredSteps>> = Object.freeze({\n    compile: (requiredStepIds: readonly string[]) => {\n      const snapshot = Object.freeze([...requiredStepIds]);\n      return (\n        outputs: Partial<RequiredPipelineOutputs<TRequiredSteps>>,\n        context: PipelineExecutionContext<StepsOptions<TRequiredSteps>>\n      ) => invoke(snapshot, outputs, context);\n    },\n    steps: Object.freeze([...uniqueRequiredSteps]),\n  });\n  Object.defineProperty(requiredFinalizer, REQUIRED_FINALIZER_OUTPUTS, {\n    value: metadata,\n  });\n  return requiredFinalizer;\n}\n"]}
+{"version":3,"file":"pipeline-finalizer.js","sourceRoot":"","sources":["../../src/core/pipeline-finalizer.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,6BAA6B,EAAE,MAAM,2BAA2B,CAAC;AAE1E,MAAM,0BAA0B,GAAkB,MAAM,CAAC,mCAAmC,CAAC,CAAC;AAW9F,MAAM,UAAU,yBAAyB,CACvC,QAAyE;IAEzE,IAAI,QAAQ,IAAI,OAAO,QAAQ,KAAK,UAAU,EAAE,CAAC;QAC/C,MAAM,EAAE,GAAG,QAAQ,CAAC,EAAE,CAAC;QACvB,OAAO,yBAAyB,CAC9B,cAAc,CAAC,CAAC,QAAQ,CAAC,EAAE,CAAC,OAAO,EAAE,EAAE,CAAC,OAAO,CAAC,EAAE,CAAC,CAAC,CACrD,CAAC;IACJ,CAAC;IACD,yEAAyE;IACzE,mEAAmE;IACnE,OACE,QACD,EAAE,CAAC,0BAA0B,CAAC,CAAC;AAClC,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,cAAc,CAC5B,aAA6B,EAC7B,QAG+B;IAK/B,MAAM,mBAAmB,GAAG,CAAC,GAAG,IAAI,GAAG,CAAC,aAAa,CAAC,CAAC,CAAC;IACxD,MAAM,MAAM,GAAG,CACb,eAAkC,EAClC,OAAyD,EACzD,OAA+D,EAC/D,EAAE;QACF,MAAM,cAAc,GAAG,eAAe,CAAC,MAAM,CAC3C,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC,MAAM,CAAC,SAAS,CAAC,cAAc,CAAC,IAAI,CAAC,OAAO,EAAE,MAAM,CAAC,CACnE,CAAC;QACF,IAAI,cAAc,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;YAC9B,MAAM,MAAM,CAAC,MAAM,CACjB,IAAI,KAAK,CAAC,sCAAsC,cAAc,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC,EAC5E,EAAE,IAAI,EAAE,6BAA6B,EAAE,CACxC,CAAC;QACJ,CAAC;QACD,4EAA4E;QAC5E,6EAA6E;QAC7E,OAAO,QAAQ,CAAC,OAA6D,EAAE,OAAO,CAAC,CAAC;IAC1F,CAAC,CAAC;IACF,MAAM,iBAAiB,GAAG,CACxB,OAAyD,EACzD,OAA+D,EAC/D,EAAE,CACF,MAAM,CACJ,mBAAmB,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,CAAC,EAAE,CAAC,EAC1C,OAAO,EACP,OAAO,CACR,CAAC;IACJ,MAAM,QAAQ,GAA4D,MAAM,CAAC,MAAM,CAAC;QACtF,OAAO,EAAE,CAAC,eAAkC,EAAE,EAAE;YAC9C,MAAM,QAAQ,GAAG,MAAM,CAAC,MAAM,CAAC,CAAC,GAAG,eAAe,CAAC,CAAC,CAAC;YACrD,OAAO,CACL,OAAyD,EACzD,OAA+D,EAC/D,EAAE,CAAC,MAAM,CAAC,QAAQ,EAAE,OAAO,EAAE,OAAO,CAAC,CAAC;QAC1C,CAAC;QACD,KAAK,EAAE,MAAM,CAAC,MAAM,CAAC,CAAC,GAAG,mBAAmB,CAAC,CAAC;KAC/C,CAAC,CAAC;IACH,MAAM,CAAC,cAAc,CAAC,iBAAiB,EAAE,0BAA0B,EAAE;QACnE,KAAK,EAAE,QAAQ;KAChB,CAAC,CAAC;IACH,OAAO,iBAAiB,CAAC;AAC3B,CAAC","sourcesContent":["import type { AnyStep, StepOutput } from \"./pipeline-steps.js\";\nimport type { StepsOptions } from \"./pipeline-definition.js\";\nimport type { PipelineExecutionContext } from \"./pipeline-types.js\";\nimport { REQUIRED_OUTPUTS_MISSING_CODE } from \"./pipeline-diagnostics.js\";\n\nconst REQUIRED_FINALIZER_OUTPUTS: unique symbol = Symbol(\"tubeless.requiredFinalizerOutputs\");\n\nexport interface RequiredFinalizerMetadata<TOptions extends object> {\n  readonly steps: readonly AnyStep<TOptions>[];\n  compile(requiredStepIds: readonly string[]): (...args: never[]) => unknown;\n}\n\ntype RequiredPipelineOutputs<TSteps extends readonly AnyStep[]> = {\n  [S in TSteps[number] as S[\"id\"]]-?: StepOutput<S>;\n};\n\nexport function requiredFinalizerMetadata<TOptions extends object>(\n  finalize: AnyStep<TOptions> | ((...args: never[]) => unknown) | undefined\n): RequiredFinalizerMetadata<TOptions> | undefined {\n  if (finalize && typeof finalize !== \"function\") {\n    const id = finalize.id;\n    return requiredFinalizerMetadata<TOptions>(\n      requireOutputs([finalize], (outputs) => outputs[id])\n    );\n  }\n  // SAFETY: `requireOutputs` stamps internal compilation metadata onto the\n  // finalizer; the intersection only exposes that optional property.\n  return (\n    finalize as { [REQUIRED_FINALIZER_OUTPUTS]?: RequiredFinalizerMetadata<TOptions> } | undefined\n  )?.[REQUIRED_FINALIZER_OUTPUTS];\n}\n\n/**\n * Build a finalizer that only runs when every listed step published an output.\n * Presence is checked by output slot, so a successfully published `undefined`\n * remains distinct from a structural skip or failure.\n */\nexport function requireOutputs<const TRequiredSteps extends readonly AnyStep[], TResult>(\n  requiredSteps: TRequiredSteps,\n  finalize: (\n    outputs: RequiredPipelineOutputs<TRequiredSteps>,\n    context: PipelineExecutionContext<StepsOptions<TRequiredSteps>>\n  ) => TResult | Promise<TResult>\n): (\n  outputs: Partial<RequiredPipelineOutputs<TRequiredSteps>>,\n  context: PipelineExecutionContext<StepsOptions<TRequiredSteps>>\n) => TResult | Promise<TResult> {\n  const uniqueRequiredSteps = [...new Set(requiredSteps)];\n  const invoke = (\n    requiredStepIds: readonly string[],\n    outputs: Partial<RequiredPipelineOutputs<TRequiredSteps>>,\n    context: PipelineExecutionContext<StepsOptions<TRequiredSteps>>\n  ) => {\n    const missingStepIds = requiredStepIds.filter(\n      (stepId) => !Object.prototype.hasOwnProperty.call(outputs, stepId)\n    );\n    if (missingStepIds.length > 0) {\n      throw Object.assign(\n        new Error(`Required pipeline outputs missing: ${missingStepIds.join(\", \")}`),\n        { code: REQUIRED_OUTPUTS_MISSING_CODE }\n      );\n    }\n    // SAFETY: every required step id was verified present above, so the partial\n    // outputs contain all required keys and are a complete required-outputs map.\n    return finalize(outputs as unknown as RequiredPipelineOutputs<TRequiredSteps>, context);\n  };\n  const requiredFinalizer = (\n    outputs: Partial<RequiredPipelineOutputs<TRequiredSteps>>,\n    context: PipelineExecutionContext<StepsOptions<TRequiredSteps>>\n  ) =>\n    invoke(\n      uniqueRequiredSteps.map((step) => step.id),\n      outputs,\n      context\n    );\n  const metadata: RequiredFinalizerMetadata<StepsOptions<TRequiredSteps>> = Object.freeze({\n    compile: (requiredStepIds: readonly string[]) => {\n      const snapshot = Object.freeze([...requiredStepIds]);\n      return (\n        outputs: Partial<RequiredPipelineOutputs<TRequiredSteps>>,\n        context: PipelineExecutionContext<StepsOptions<TRequiredSteps>>\n      ) => invoke(snapshot, outputs, context);\n    },\n    steps: Object.freeze([...uniqueRequiredSteps]),\n  });\n  Object.defineProperty(requiredFinalizer, REQUIRED_FINALIZER_OUTPUTS, {\n    value: metadata,\n  });\n  return requiredFinalizer;\n}\n"]}

package/dist/core/pipeline-step-builders.d.ts

@@ -0,0 +1,63 @@
+import type { PipelineMetadata } from "../tracing/graph-metadata.js";
+import type { ArtifactLoader, ArtifactSaver } from "./pipeline-artifacts.js";
+import { createIterationRunner } from "./iteration.js";
+import type { AnyStep, AnyStepDryRunHandler, ChildPipelineStepDefinitionBase, MappedChildPipelineStepDefinition, StepDefinitionBody, StepSkipPredicate } from "./pipeline-step-types.js";
+import type { Pipeline, PipelineRun, PipelineStepContext, RemoteStepAdapter, StandardSchemaV1 } from "./pipeline-types.js";
+/**
+ * Runtime construction for each step kind. `createSteps` owns the typed overloads;
+ * these builders receive the erased definitions and the factory's `buildStep`.
+ */
+export type BuildStep<TOptions extends object> = (id: string, definition: StepDefinitionBody<TOptions>) => AnyStep<TOptions>;
+type AnyDeps<TOptions extends object> = readonly AnyStep<TOptions>[];
+type AnySkip<TOptions extends object> = StepSkipPredicate<TOptions, AnyDeps<TOptions>, AnyDeps<TOptions>, unknown>;
+type ArtifactStepFields<TOptions extends object> = Omit<StepDefinitionBody<TOptions>, "run" | "dryRun" | "cache" | "outputSchema" | "skip"> & {
+    cache?: unknown;
+    skip?: AnySkip<TOptions>;
+};
+/** Read an artifact as an ordinary step, publishing only its typed value. */
+export declare function buildLoadArtifactStep<TOptions extends object>(buildStep: BuildStep<TOptions>, id: string, definition: ArtifactStepFields<TOptions> & {
+    dryRun?: "skip" | ArtifactLoader<Record<string, unknown>, unknown, TOptions>;
+    load: ArtifactLoader<Record<string, unknown>, unknown, TOptions>;
+}): AnyStep<TOptions>;
+/** Write an artifact as an ordinary step. Dry runs skip unless a preview is supplied. */
+export declare function buildSaveArtifactStep<TOptions extends object>(buildStep: BuildStep<TOptions>, id: string, definition: ArtifactStepFields<TOptions> & {
+    dryRun?: "skip" | ArtifactSaver<Record<string, unknown>, unknown, TOptions>;
+    save: ArtifactSaver<Record<string, unknown>, unknown, TOptions>;
+}): AnyStep<TOptions>;
+/** Erased `fromPipeline` definition. */
+export type SingleChildStepConfig<TOptions extends object> = ChildPipelineStepDefinitionBase<TOptions, AnyDeps<TOptions>, AnyDeps<TOptions>, Pipeline<object, unknown>> & {
+    skip?: AnySkip<TOptions>;
+    mapResult?: (value: unknown, result: PipelineRun<unknown>, context: PipelineStepContext<TOptions>) => unknown;
+};
+export declare function buildPipelineStep<TOptions extends object>(buildStep: BuildStep<TOptions>, id: string, config: SingleChildStepConfig<TOptions>): AnyStep<TOptions>;
+/** Erased `fromRemote` definition. */
+export interface RemoteStepConfig<TOptions extends object> {
+    adapter: RemoteStepAdapter<object, unknown, unknown>;
+    mapInput(inputs: Record<string, unknown>, context: PipelineStepContext<TOptions>): unknown;
+    outputSchema: StandardSchemaV1;
+    dependsOn?: AnyDeps<TOptions>;
+    optionalDependsOn?: AnyDeps<TOptions>;
+    skipAfterFailureOf?: AnyDeps<TOptions>;
+    name?: string;
+    description?: string;
+    metadata?: PipelineMetadata;
+    dryRun?: "skip" | AnyStepDryRunHandler<TOptions>;
+    skip?: AnySkip<TOptions>;
+}
+export declare function buildRemoteStep<TOptions extends object>(buildStep: BuildStep<TOptions>, id: string, config: RemoteStepConfig<TOptions>): AnyStep<TOptions>;
+/** Erased `forEachPipeline` definition. */
+export type MappedChildStepConfig<TOptions extends object> = MappedChildPipelineStepDefinition<TOptions, AnyDeps<TOptions>, AnyDeps<TOptions>, Pipeline<object, unknown>, unknown> & {
+    mapResult?: (value: unknown, result: PipelineRun<unknown>, item: unknown, index: number, context: PipelineStepContext<TOptions>) => unknown;
+    skip?: AnySkip<TOptions>;
+};
+export declare function buildMappedPipelineStep<TOptions extends object>(buildStep: BuildStep<TOptions>, id: string, config: MappedChildStepConfig<TOptions>): AnyStep<TOptions>;
+/** Erased `iteratePipeline` definition. */
+export type IterationStepConfig<TOptions extends object> = Omit<Parameters<typeof createIterationRunner<TOptions>>[0], "stepId"> & {
+    name?: string;
+    description?: string;
+    metadata?: PipelineMetadata;
+    dependsOn?: AnyDeps<TOptions>;
+    dryRun?: "skip";
+};
+export declare function buildIterationStep<TOptions extends object>(buildStep: BuildStep<TOptions>, id: string, definition: IterationStepConfig<TOptions>): AnyStep<TOptions>;
+export {};

package/dist/core/pipeline-step-builders.js

@@ -0,0 +1,140 @@
+import { createMappedChildRunner, createSingleChildRunner } from "./child-execution.js";
+import { createIterationRunner } from "./iteration.js";
+import { STEP_NESTED_PIPELINE, STEP_REMOTE } from "./pipeline-step-metadata.js";
+/** Read an artifact as an ordinary step, publishing only its typed value. */
+export function buildLoadArtifactStep(buildStep, id, definition) {
+    const { cache, load, dryRun, ...fields } = definition;
+    if (cache !== undefined)
+        throw new Error("Artifact helpers cannot configure caching");
+    const wrap = (handler) => async (inputs, context) => {
+        const loaded = await handler(inputs, context);
+        context.recordArtifact({ operation: "read", artifact: loaded.artifact });
+        return loaded.value;
+    };
+    return buildStep(id, {
+        ...fields,
+        run: wrap(load),
+        dryRun: typeof dryRun === "function" ? wrap(dryRun) : dryRun,
+    });
+}
+/** Write an artifact as an ordinary step. Dry runs skip unless a preview is supplied. */
+export function buildSaveArtifactStep(buildStep, id, definition) {
+    const { cache, save, dryRun, ...fields } = definition;
+    if (cache !== undefined)
+        throw new Error("Artifact helpers cannot configure caching");
+    const wrap = (handler) => async (inputs, context) => {
+        const saved = await handler(inputs, context);
+        context.recordArtifact({ operation: "write", artifact: saved.artifact });
+        return saved.value;
+    };
+    return buildStep(id, {
+        ...fields,
+        run: wrap(save),
+        dryRun: typeof dryRun === "function" ? wrap(dryRun) : "skip",
+    });
+}
+export function buildPipelineStep(buildStep, id, config) {
+    const definition = {
+        [STEP_NESTED_PIPELINE]: {
+            mode: "single",
+            pipelineId: config.pipeline.id,
+            identity: config.pipeline.definition?.identity,
+            stepIds: config.pipeline.stepIds,
+        },
+        dependsOn: config.dependsOn,
+        optionalDependsOn: config.optionalDependsOn,
+        skipAfterFailureOf: config.skipAfterFailureOf,
+        name: config.name,
+        description: config.description,
+        metadata: config.metadata,
+        dryRun: config.dryRun,
+        run: createSingleChildRunner({ ...config, stepId: id }),
+    };
+    const skip = config.skip;
+    if (skip !== undefined) {
+        definition.skip = skip;
+    }
+    return buildStep(id, definition);
+}
+export function buildRemoteStep(buildStep, id, config) {
+    const remote = { engine: config.adapter.engine };
+    if (config.adapter.target !== undefined)
+        remote.target = config.adapter.target;
+    const definition = {
+        [STEP_REMOTE]: remote,
+        dependsOn: config.dependsOn,
+        optionalDependsOn: config.optionalDependsOn,
+        skipAfterFailureOf: config.skipAfterFailureOf,
+        name: config.name,
+        description: config.description,
+        metadata: config.metadata,
+        dryRun: config.dryRun,
+        outputSchema: config.outputSchema,
+        run: (inputs, context) => config.adapter.invoke(config.mapInput(inputs, context), context),
+    };
+    const skip = config.skip;
+    if (skip !== undefined) {
+        definition.skip = skip;
+    }
+    return buildStep(id, definition);
+}
+export function buildMappedPipelineStep(buildStep, id, config) {
+    const configuredConcurrency = config.concurrency;
+    if (typeof configuredConcurrency === "number" &&
+        (!Number.isInteger(configuredConcurrency) || configuredConcurrency < 1)) {
+        throw new RangeError(`forEachPipeline concurrency must be a positive finite integer, got ${configuredConcurrency}`);
+    }
+    const definition = {
+        [STEP_NESTED_PIPELINE]: {
+            mode: "for-each",
+            concurrency: typeof configuredConcurrency === "function" ? "dynamic" : (configuredConcurrency ?? 1),
+            pipelineId: config.pipeline.id,
+            identity: config.pipeline.definition?.identity,
+            stepIds: config.pipeline.stepIds,
+        },
+        dependsOn: config.dependsOn,
+        optionalDependsOn: config.optionalDependsOn,
+        skipAfterFailureOf: config.skipAfterFailureOf,
+        name: config.name,
+        description: config.description,
+        metadata: config.metadata,
+        dryRun: config.dryRun,
+        run: createMappedChildRunner({ ...config, stepId: id }),
+    };
+    const skip = config.skip;
+    if (skip !== undefined) {
+        definition.skip = skip;
+    }
+    return buildStep(id, definition);
+}
+export function buildIterationStep(buildStep, id, definition) {
+    if (!Number.isSafeInteger(definition.maxIterations) || definition.maxIterations < 1) {
+        throw new RangeError("iteratePipeline maxIterations must be a positive safe integer");
+    }
+    const controls = definition.controls ? structuredClone(definition.controls) : undefined;
+    if (controls) {
+        if (controls.targets)
+            Object.freeze(controls.targets);
+        if (controls.stepIds)
+            Object.freeze(controls.stepIds);
+        Object.freeze(controls);
+    }
+    const config = { ...definition, stepId: id, controls };
+    return buildStep(id, {
+        [STEP_NESTED_PIPELINE]: {
+            mode: "iterate",
+            maxIterations: config.maxIterations,
+            controls: config.controls,
+            pipelineId: config.pipeline.id,
+            identity: config.pipeline.definition?.identity,
+            stepIds: config.pipeline.stepIds,
+        },
+        name: config.name,
+        description: config.description,
+        metadata: config.metadata,
+        dependsOn: config.dependsOn,
+        dryRun: config.dryRun,
+        run: createIterationRunner(config),
+    });
+}
+//# sourceMappingURL=pipeline-step-builders.js.map

package/dist/core/pipeline-step-builders.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"pipeline-step-builders.js","sourceRoot":"","sources":["../../src/core/pipeline-step-builders.ts"],"names":[],"mappings":"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","sourcesContent":["import type { PipelineMetadata } from \"../tracing/graph-metadata.js\";\nimport type { ArtifactLoader, ArtifactSaver } from \"./pipeline-artifacts.js\";\nimport { createMappedChildRunner, createSingleChildRunner } from \"./child-execution.js\";\nimport { createIterationRunner } from \"./iteration.js\";\nimport { STEP_NESTED_PIPELINE, STEP_REMOTE } from \"./pipeline-step-metadata.js\";\nimport type {\n  AnyStep,\n  AnyStepDryRunHandler,\n  ChildPipelineStepDefinitionBase,\n  MappedChildPipelineStepDefinition,\n  StepDefinitionBody,\n  StepSkipPredicate,\n} from \"./pipeline-step-types.js\";\nimport type {\n  Pipeline,\n  PipelinePlanStep,\n  PipelineRun,\n  PipelineStepContext,\n  RemoteStepAdapter,\n  StandardSchemaV1,\n} from \"./pipeline-types.js\";\n\n/**\n * Runtime construction for each step kind. `createSteps` owns the typed overloads;\n * these builders receive the erased definitions and the factory's `buildStep`.\n */\nexport type BuildStep<TOptions extends object> = (\n  id: string,\n  definition: StepDefinitionBody<TOptions>\n) => AnyStep<TOptions>;\n\ntype AnyDeps<TOptions extends object> = readonly AnyStep<TOptions>[];\ntype AnySkip<TOptions extends object> = StepSkipPredicate<\n  TOptions,\n  AnyDeps<TOptions>,\n  AnyDeps<TOptions>,\n  unknown\n>;\n\ntype ArtifactStepFields<TOptions extends object> = Omit<\n  StepDefinitionBody<TOptions>,\n  \"run\" | \"dryRun\" | \"cache\" | \"outputSchema\" | \"skip\"\n> & {\n  cache?: unknown;\n  skip?: AnySkip<TOptions>;\n};\n\n/** Read an artifact as an ordinary step, publishing only its typed value. */\nexport function buildLoadArtifactStep<TOptions extends object>(\n  buildStep: BuildStep<TOptions>,\n  id: string,\n  definition: ArtifactStepFields<TOptions> & {\n    dryRun?: \"skip\" | ArtifactLoader<Record<string, unknown>, unknown, TOptions>;\n    load: ArtifactLoader<Record<string, unknown>, unknown, TOptions>;\n  }\n): AnyStep<TOptions> {\n  const { cache, load, dryRun, ...fields } = definition;\n  if (cache !== undefined) throw new Error(\"Artifact helpers cannot configure caching\");\n  const wrap =\n    (handler: typeof load) =>\n    async (inputs: Record<string, unknown>, context: PipelineStepContext<TOptions>) => {\n      const loaded = await handler(inputs, context);\n      context.recordArtifact({ operation: \"read\", artifact: loaded.artifact });\n      return loaded.value;\n    };\n  return buildStep(id, {\n    ...fields,\n    run: wrap(load),\n    dryRun: typeof dryRun === \"function\" ? wrap(dryRun) : dryRun,\n  });\n}\n\n/** Write an artifact as an ordinary step. Dry runs skip unless a preview is supplied. */\nexport function buildSaveArtifactStep<TOptions extends object>(\n  buildStep: BuildStep<TOptions>,\n  id: string,\n  definition: ArtifactStepFields<TOptions> & {\n    dryRun?: \"skip\" | ArtifactSaver<Record<string, unknown>, unknown, TOptions>;\n    save: ArtifactSaver<Record<string, unknown>, unknown, TOptions>;\n  }\n): AnyStep<TOptions> {\n  const { cache, save, dryRun, ...fields } = definition;\n  if (cache !== undefined) throw new Error(\"Artifact helpers cannot configure caching\");\n  const wrap =\n    (handler: typeof save) =>\n    async (inputs: Record<string, unknown>, context: PipelineStepContext<TOptions>) => {\n      const saved = await handler(inputs, context);\n      context.recordArtifact({ operation: \"write\", artifact: saved.artifact });\n      return saved.value;\n    };\n  return buildStep(id, {\n    ...fields,\n    run: wrap(save),\n    dryRun: typeof dryRun === \"function\" ? wrap(dryRun) : \"skip\",\n  });\n}\n\n/** Erased `fromPipeline` definition. */\nexport type SingleChildStepConfig<TOptions extends object> = ChildPipelineStepDefinitionBase<\n  TOptions,\n  AnyDeps<TOptions>,\n  AnyDeps<TOptions>,\n  Pipeline<object, unknown>\n> & {\n  skip?: AnySkip<TOptions>;\n  mapResult?: (\n    value: unknown,\n    result: PipelineRun<unknown>,\n    context: PipelineStepContext<TOptions>\n  ) => unknown;\n};\n\nexport function buildPipelineStep<TOptions extends object>(\n  buildStep: BuildStep<TOptions>,\n  id: string,\n  config: SingleChildStepConfig<TOptions>\n): AnyStep<TOptions> {\n  const definition: StepDefinitionBody<TOptions> = {\n    [STEP_NESTED_PIPELINE]: {\n      mode: \"single\" as const,\n      pipelineId: config.pipeline.id,\n      identity: config.pipeline.definition?.identity,\n      stepIds: config.pipeline.stepIds,\n    },\n    dependsOn: config.dependsOn,\n    optionalDependsOn: config.optionalDependsOn,\n    skipAfterFailureOf: config.skipAfterFailureOf,\n    name: config.name,\n    description: config.description,\n    metadata: config.metadata,\n    dryRun: config.dryRun,\n    run: createSingleChildRunner({ ...config, stepId: id }),\n  };\n\n  const skip = config.skip;\n  if (skip !== undefined) {\n    definition.skip = skip;\n  }\n  return buildStep(id, definition);\n}\n\n/** Erased `fromRemote` definition. */\nexport interface RemoteStepConfig<TOptions extends object> {\n  adapter: RemoteStepAdapter<object, unknown, unknown>;\n  mapInput(inputs: Record<string, unknown>, context: PipelineStepContext<TOptions>): unknown;\n  outputSchema: StandardSchemaV1;\n  dependsOn?: AnyDeps<TOptions>;\n  optionalDependsOn?: AnyDeps<TOptions>;\n  skipAfterFailureOf?: AnyDeps<TOptions>;\n  name?: string;\n  description?: string;\n  metadata?: PipelineMetadata;\n  dryRun?: \"skip\" | AnyStepDryRunHandler<TOptions>;\n  skip?: AnySkip<TOptions>;\n}\n\nexport function buildRemoteStep<TOptions extends object>(\n  buildStep: BuildStep<TOptions>,\n  id: string,\n  config: RemoteStepConfig<TOptions>\n): AnyStep<TOptions> {\n  const remote: NonNullable<PipelinePlanStep[\"remote\"]> = { engine: config.adapter.engine };\n  if (config.adapter.target !== undefined) remote.target = config.adapter.target;\n  const definition: StepDefinitionBody<TOptions> = {\n    [STEP_REMOTE]: remote,\n    dependsOn: config.dependsOn,\n    optionalDependsOn: config.optionalDependsOn,\n    skipAfterFailureOf: config.skipAfterFailureOf,\n    name: config.name,\n    description: config.description,\n    metadata: config.metadata,\n    dryRun: config.dryRun,\n    outputSchema: config.outputSchema,\n    run: (inputs: Record<string, unknown>, context: PipelineStepContext<TOptions>) =>\n      config.adapter.invoke(config.mapInput(inputs, context), context),\n  };\n  const skip = config.skip;\n  if (skip !== undefined) {\n    definition.skip = skip;\n  }\n  return buildStep(id, definition);\n}\n\n/** Erased `forEachPipeline` definition. */\nexport type MappedChildStepConfig<TOptions extends object> = MappedChildPipelineStepDefinition<\n  TOptions,\n  AnyDeps<TOptions>,\n  AnyDeps<TOptions>,\n  Pipeline<object, unknown>,\n  unknown\n> & {\n  mapResult?: (\n    value: unknown,\n    result: PipelineRun<unknown>,\n    item: unknown,\n    index: number,\n    context: PipelineStepContext<TOptions>\n  ) => unknown;\n  skip?: AnySkip<TOptions>;\n};\n\nexport function buildMappedPipelineStep<TOptions extends object>(\n  buildStep: BuildStep<TOptions>,\n  id: string,\n  config: MappedChildStepConfig<TOptions>\n): AnyStep<TOptions> {\n  const configuredConcurrency = config.concurrency;\n  if (\n    typeof configuredConcurrency === \"number\" &&\n    (!Number.isInteger(configuredConcurrency) || configuredConcurrency < 1)\n  ) {\n    throw new RangeError(\n      `forEachPipeline concurrency must be a positive finite integer, got ${configuredConcurrency}`\n    );\n  }\n  const definition: StepDefinitionBody<TOptions> = {\n    [STEP_NESTED_PIPELINE]: {\n      mode: \"for-each\" as const,\n      concurrency:\n        typeof configuredConcurrency === \"function\" ? \"dynamic\" : (configuredConcurrency ?? 1),\n      pipelineId: config.pipeline.id,\n      identity: config.pipeline.definition?.identity,\n      stepIds: config.pipeline.stepIds,\n    },\n    dependsOn: config.dependsOn,\n    optionalDependsOn: config.optionalDependsOn,\n    skipAfterFailureOf: config.skipAfterFailureOf,\n    name: config.name,\n    description: config.description,\n    metadata: config.metadata,\n    dryRun: config.dryRun,\n    run: createMappedChildRunner({ ...config, stepId: id }),\n  };\n\n  const skip = config.skip;\n  if (skip !== undefined) {\n    definition.skip = skip;\n  }\n  return buildStep(id, definition);\n}\n\n/** Erased `iteratePipeline` definition. */\nexport type IterationStepConfig<TOptions extends object> = Omit<\n  Parameters<typeof createIterationRunner<TOptions>>[0],\n  \"stepId\"\n> & {\n  name?: string;\n  description?: string;\n  metadata?: PipelineMetadata;\n  dependsOn?: AnyDeps<TOptions>;\n  dryRun?: \"skip\";\n};\n\nexport function buildIterationStep<TOptions extends object>(\n  buildStep: BuildStep<TOptions>,\n  id: string,\n  definition: IterationStepConfig<TOptions>\n): AnyStep<TOptions> {\n  if (!Number.isSafeInteger(definition.maxIterations) || definition.maxIterations < 1) {\n    throw new RangeError(\"iteratePipeline maxIterations must be a positive safe integer\");\n  }\n  const controls = definition.controls ? structuredClone(definition.controls) : undefined;\n  if (controls) {\n    if (controls.targets) Object.freeze(controls.targets);\n    if (controls.stepIds) Object.freeze(controls.stepIds);\n    Object.freeze(controls);\n  }\n  const config = { ...definition, stepId: id, controls };\n  return buildStep(id, {\n    [STEP_NESTED_PIPELINE]: {\n      mode: \"iterate\",\n      maxIterations: config.maxIterations,\n      controls: config.controls,\n      pipelineId: config.pipeline.id,\n      identity: config.pipeline.definition?.identity,\n      stepIds: config.pipeline.stepIds,\n    },\n    name: config.name,\n    description: config.description,\n    metadata: config.metadata,\n    dependsOn: config.dependsOn,\n    dryRun: config.dryRun,\n    run: createIterationRunner(config),\n  });\n}\n"]}

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

@@ -0,0 +1,160 @@
+import type { PipelineMetadata } from "../tracing/graph-metadata.js";
+import type { CompiledStepCache, StepCache } from "./pipeline-cache.js";
+import type { ToMappedChildStepProgressOptions } from "./mapped-child-progress.js";
+import type { STEP_AGENT, STEP_CACHE, STEP_NESTED_PIPELINE, STEP_OPTIONS_SCHEMA, STEP_ORCHESTRATION, STEP_REMOTE } from "./pipeline-step-metadata.js";
+import type { InferSchemaInput, Pipeline, PipelineExecutionContext, PipelinePlanStep, PipelineRunControls, PipelineStepContext, RemoteStepAdapter, StandardSchemaV1, StepSkipDecision } from "./pipeline-types.js";
+/**
+ * A step's dependencies are references to the dependency's own step object, not string ids
+ * into a hand-maintained output-type map. This buys two things no amount of extra generics
+ * on a string-keyed design could:
+ *  - a step used before its dependency exists is a compile error (JS temporal dead zone on
+ *    `const`), so out-of-order and self/cyclic dependencies are caught by the language, not
+ *    a bespoke runtime check
+ *  - each step only ever states its own id/deps; the output-type map is derived, never
+ *    restated, and callers of `definePipeline`/`createSteps` never write out its generics
+ */
+export type AnyStepDryRunHandler<TOptions extends object> = {
+    bivarianceHack(inputs: Record<string, unknown>, context: PipelineStepContext<TOptions>): unknown | Promise<unknown>;
+}["bivarianceHack"];
+/** Runtime shape shared by every declared pipeline step. */
+export interface AnyStep<TOptions extends object = object> {
+    readonly [STEP_ORCHESTRATION]?: true;
+    readonly [STEP_AGENT]?: NonNullable<PipelinePlanStep["agent"]>;
+    readonly [STEP_NESTED_PIPELINE]?: NonNullable<PipelinePlanStep["nestedPipeline"]>;
+    readonly [STEP_REMOTE]?: NonNullable<PipelinePlanStep["remote"]>;
+    readonly [STEP_OPTIONS_SCHEMA]?: StandardSchemaV1;
+    readonly id: string;
+    readonly dependsOn?: readonly AnyStep<TOptions>[];
+    readonly optionalDependsOn?: readonly AnyStep<TOptions>[];
+    readonly skipAfterFailureOf?: readonly AnyStep<TOptions>[];
+    /** Optional human-facing display name. Stable machine identity remains `id`. */
+    readonly name?: string;
+    readonly description?: string;
+    readonly metadata?: PipelineMetadata;
+    /**
+     * Dry-run policy. Omitted runs the normal handler, `"skip"` structurally
+     * skips it, and a handler substitutes for `run` while preserving its output.
+     */
+    readonly dryRun?: "skip" | AnyStepDryRunHandler<TOptions>;
+    /** Optional Standard Schema for values published by this step. */
+    readonly outputSchema?: StandardSchemaV1;
+    /** Explicit output caching for ordinary deterministic steps only. */
+    readonly cache?: boolean | StepCache<Record<string, unknown>, TOptions>;
+    readonly [STEP_CACHE]?: CompiledStepCache<TOptions>;
+    /**
+     * Optional runtime skip. Return a non-empty reason (or `{ reason, value }`) to
+     * skip without calling `run`. Policy skips unlock dependents; structural skips
+     * (dry-run, filtered, …) do not use this hook.
+     */
+    skip?(inputs: Record<string, unknown>, context: PipelineExecutionContext<TOptions>): StepSkipDecision | Promise<StepSkipDecision>;
+    run(inputs: Record<string, unknown>, context: PipelineStepContext<TOptions>): unknown;
+}
+/** The step fields that `buildStep` merges onto the id-bearing shell. */
+export type StepDefinitionBody<TOptions extends object> = Omit<AnyStep<TOptions>, "id">;
+/** Typed pipeline step carrying its stable ID, output, and option types. */
+export interface Step<TId extends string, TOut, TOptions extends object, TInputOptions extends object = TOptions, TRunOut = TOut, TOptionsSchema extends StandardSchemaV1 | undefined = StandardSchemaV1 | undefined> extends AnyStep<TOptions> {
+    readonly [STEP_OPTIONS_SCHEMA]?: TOptionsSchema;
+    readonly id: TId;
+    run(inputs: Record<string, unknown>, context: PipelineStepContext<TOptions>): TRunOut | Promise<TRunOut>;
+    /** Type-only: carries this step's output type for sibling inference. Never set at runtime. */
+    readonly __outputType?: TOut;
+    /** Type-only: carries pre-validation run options for pipeline call-site inference. */
+    readonly __inputOptionsType?: TInputOptions;
+}
+/**
+ * Extract a step's output type for dependency typing.
+ * Prefer matching `Step<…, TOut, …>` over `{ __outputType?: infer T }`: optional-property
+ * inference collapses `TOut | undefined` to `TOut`, which hides policy-skip widening.
+ */
+export type StepOutput<S> = S extends Step<string, infer TOut, infer _TOptions, infer _TInputOptions, infer _TRunOut> ? TOut : never;
+export interface StepToken {
+    readonly id: string;
+    readonly __outputType?: unknown;
+}
+export type RequiredInputs<TDeps extends readonly StepToken[]> = {
+    [S in TDeps[number] as S["id"]]: StepOutput<S>;
+};
+export type OptionalInputs<TDeps extends readonly StepToken[]> = {
+    [S in TDeps[number] as S["id"]]?: StepOutput<S>;
+};
+export type PipelineResultOf<TPipeline> = TPipeline extends Pipeline<object, infer TResult, infer _TStepId, infer _TTargetId> ? TResult : never;
+export type PipelineOptionsOf<TPipeline> = TPipeline extends Pipeline<infer TOptions, unknown, infer _TStepId, infer _TTargetId> ? TOptions : never;
+export type PipelineRunControlsOf<TPipeline> = TPipeline extends Pipeline<infer _TOptions, unknown, infer TStepId, infer TTargetId> ? PipelineRunControls<TStepId, TTargetId> : never;
+export type ChildPipelineStepDefinitionBase<TParentOptions extends object, TDeps extends readonly AnyStep<TParentOptions>[], TOptionalDeps extends readonly AnyStep<TParentOptions>[], TChildPipeline extends Pipeline<object, unknown>> = {
+    pipeline: TChildPipeline;
+    dependsOn?: TDeps;
+    optionalDependsOn?: TOptionalDeps;
+    skipAfterFailureOf?: readonly AnyStep<TParentOptions>[];
+    name?: string;
+    description?: string;
+    metadata?: PipelineMetadata;
+    dryRun?: "skip";
+    controls?: PipelineRunControlsOf<TChildPipeline> | ((inputs: RequiredInputs<TDeps> & OptionalInputs<TOptionalDeps>, context: PipelineExecutionContext<TParentOptions>) => PipelineRunControlsOf<TChildPipeline>);
+} & ([TParentOptions] extends [PipelineOptionsOf<NoInfer<TChildPipeline>>] ? {
+    mapOptions?(inputs: RequiredInputs<TDeps> & OptionalInputs<TOptionalDeps>, context: PipelineExecutionContext<TParentOptions>): PipelineOptionsOf<TChildPipeline>;
+} : {
+    mapOptions(inputs: RequiredInputs<TDeps> & OptionalInputs<TOptionalDeps>, context: PipelineExecutionContext<TParentOptions>): PipelineOptionsOf<TChildPipeline>;
+});
+/** Child step without policy skip (dependents see the full child result type). */
+export type ChildPipelineStepDefinition<TParentOptions extends object, TDeps extends readonly AnyStep<TParentOptions>[], TOptionalDeps extends readonly AnyStep<TParentOptions>[], TChildPipeline extends Pipeline<object, unknown>> = ChildPipelineStepDefinitionBase<TParentOptions, TDeps, TOptionalDeps, TChildPipeline>;
+/**
+ * Presentation options for opaque `forEachPipeline` progress.
+ * Defaults are domain-neutral (`N/M items · K running · key/step`).
+ * Override `formatMessage` when a domain wants its own noun (images, shards, …).
+ */
+export type MappedChildProgressOptions = ToMappedChildStepProgressOptions;
+export type MappedChildPipelineStepDefinition<TParentOptions extends object, TDeps extends readonly AnyStep<TParentOptions>[], TOptionalDeps extends readonly AnyStep<TParentOptions>[], TChildPipeline extends Pipeline<object, unknown>, TItem> = {
+    pipeline: TChildPipeline;
+    dependsOn?: TDeps;
+    optionalDependsOn?: TOptionalDeps;
+    skipAfterFailureOf?: readonly AnyStep<TParentOptions>[];
+    name?: string;
+    description?: string;
+    metadata?: PipelineMetadata;
+    dryRun?: "skip";
+    items(inputs: RequiredInputs<TDeps> & OptionalInputs<TOptionalDeps>, context: PipelineExecutionContext<TParentOptions>): readonly TItem[] | Promise<readonly TItem[]>;
+    key(item: TItem, index: number): string;
+    concurrency?: number | ((inputs: RequiredInputs<TDeps> & OptionalInputs<TOptionalDeps>, context: PipelineExecutionContext<TParentOptions>) => number);
+    /**
+     * How the opaque parent step reports live fan-out progress.
+     * Purely presentational — does not change scheduling or results.
+     */
+    progress?: MappedChildProgressOptions;
+    controls?: PipelineRunControlsOf<TChildPipeline> | ((item: TItem, index: number, inputs: RequiredInputs<TDeps> & OptionalInputs<TOptionalDeps>, context: PipelineExecutionContext<TParentOptions>) => PipelineRunControlsOf<TChildPipeline>);
+    mapOptions(item: TItem, index: number, inputs: RequiredInputs<TDeps> & OptionalInputs<TOptionalDeps>, context: PipelineExecutionContext<TParentOptions>): PipelineOptionsOf<TChildPipeline>;
+};
+export type StepSkipPredicate<TOptions extends object, TDeps extends readonly AnyStep<TOptions>[], TOptionalDeps extends readonly AnyStep<TOptions>[], TOut, TDecision extends StepSkipDecision<TOut> = StepSkipDecision<TOut>> = (inputs: RequiredInputs<TDeps> & OptionalInputs<TOptionalDeps>, context: PipelineExecutionContext<TOptions>) => TDecision | Promise<TDecision>;
+export type PolicySkippedOutput<TOut, TDecision> = [
+    Exclude<Awaited<TDecision>, false | null | undefined>
+] extends [{
+    reason: string;
+    value: unknown;
+}] ? TOut : TOut | undefined;
+export type StepDryRunPolicy<TOptions extends object, TDeps extends readonly AnyStep<TOptions>[], TOptionalDeps extends readonly AnyStep<TOptions>[], TOut> = "skip" | ((inputs: RequiredInputs<TDeps> & OptionalInputs<TOptionalDeps>, context: PipelineStepContext<TOptions>) => TOut | Promise<TOut>);
+export type PlainStepFields<TOptions extends object, TDeps extends readonly AnyStep<TOptions>[], TOptionalDeps extends readonly AnyStep<TOptions>[], TOut> = {
+    dependsOn?: TDeps;
+    optionalDependsOn?: TOptionalDeps;
+    skipAfterFailureOf?: readonly AnyStep<TOptions>[];
+    name?: string;
+    description?: string;
+    metadata?: PipelineMetadata;
+    dryRun?: StepDryRunPolicy<TOptions, TDeps, TOptionalDeps, TOut>;
+    outputSchema?: never;
+    cache?: boolean | StepCache<RequiredInputs<TDeps> & OptionalInputs<TOptionalDeps>, TOptions>;
+    run(inputs: RequiredInputs<TDeps> & OptionalInputs<TOptionalDeps>, context: PipelineStepContext<TOptions>): TOut | Promise<TOut>;
+};
+export type SchemaStepFields<TOptions extends object, TDeps extends readonly AnyStep<TOptions>[], TOptionalDeps extends readonly AnyStep<TOptions>[], TSchema extends StandardSchemaV1> = Omit<PlainStepFields<TOptions, TDeps, TOptionalDeps, InferSchemaInput<TSchema>>, "outputSchema"> & {
+    outputSchema: TSchema;
+};
+export type RemoteStepDefinitionBase<TParentOptions extends object, TDeps extends readonly AnyStep<TParentOptions>[], TOptionalDeps extends readonly AnyStep<TParentOptions>[], TPayload, TSchema extends StandardSchemaV1> = {
+    adapter: RemoteStepAdapter<TParentOptions, TPayload, InferSchemaInput<TSchema>>;
+    mapInput(inputs: RequiredInputs<TDeps> & OptionalInputs<TOptionalDeps>, context: PipelineStepContext<TParentOptions>): TPayload;
+    outputSchema: TSchema;
+    dependsOn?: TDeps;
+    optionalDependsOn?: TOptionalDeps;
+    skipAfterFailureOf?: readonly AnyStep<TParentOptions>[];
+    name?: string;
+    description?: string;
+    metadata?: PipelineMetadata;
+    dryRun?: StepDryRunPolicy<TParentOptions, TDeps, TOptionalDeps, InferSchemaInput<TSchema>>;
+};

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

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=pipeline-step-types.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"pipeline-step-types.js","sourceRoot":"","sources":["../../src/core/pipeline-step-types.ts"],"names":[],"mappings":"","sourcesContent":["import type { PipelineMetadata } from \"../tracing/graph-metadata.js\";\nimport type { CompiledStepCache, StepCache } from \"./pipeline-cache.js\";\nimport type { ToMappedChildStepProgressOptions } from \"./mapped-child-progress.js\";\nimport type {\n  STEP_AGENT,\n  STEP_CACHE,\n  STEP_NESTED_PIPELINE,\n  STEP_OPTIONS_SCHEMA,\n  STEP_ORCHESTRATION,\n  STEP_REMOTE,\n} from \"./pipeline-step-metadata.js\";\nimport type {\n  InferSchemaInput,\n  Pipeline,\n  PipelineExecutionContext,\n  PipelinePlanStep,\n  PipelineRunControls,\n  PipelineStepContext,\n  RemoteStepAdapter,\n  StandardSchemaV1,\n  StepSkipDecision,\n} from \"./pipeline-types.js\";\n\n/**\n * A step's dependencies are references to the dependency's own step object, not string ids\n * into a hand-maintained output-type map. This buys two things no amount of extra generics\n * on a string-keyed design could:\n *  - a step used before its dependency exists is a compile error (JS temporal dead zone on\n *    `const`), so out-of-order and self/cyclic dependencies are caught by the language, not\n *    a bespoke runtime check\n *  - each step only ever states its own id/deps; the output-type map is derived, never\n *    restated, and callers of `definePipeline`/`createSteps` never write out its generics\n */\nexport type AnyStepDryRunHandler<TOptions extends object> = {\n  bivarianceHack(\n    inputs: Record<string, unknown>,\n    context: PipelineStepContext<TOptions>\n  ): unknown | Promise<unknown>;\n}[\"bivarianceHack\"];\n\n/** Runtime shape shared by every declared pipeline step. */\nexport interface AnyStep<TOptions extends object = object> {\n  readonly [STEP_ORCHESTRATION]?: true;\n  readonly [STEP_AGENT]?: NonNullable<PipelinePlanStep[\"agent\"]>;\n  readonly [STEP_NESTED_PIPELINE]?: NonNullable<PipelinePlanStep[\"nestedPipeline\"]>;\n  readonly [STEP_REMOTE]?: NonNullable<PipelinePlanStep[\"remote\"]>;\n  readonly [STEP_OPTIONS_SCHEMA]?: StandardSchemaV1;\n  readonly id: string;\n  readonly dependsOn?: readonly AnyStep<TOptions>[];\n  readonly optionalDependsOn?: readonly AnyStep<TOptions>[];\n  readonly skipAfterFailureOf?: readonly AnyStep<TOptions>[];\n  /** Optional human-facing display name. Stable machine identity remains `id`. */\n  readonly name?: string;\n  readonly description?: string;\n  readonly metadata?: PipelineMetadata;\n  /**\n   * Dry-run policy. Omitted runs the normal handler, `\"skip\"` structurally\n   * skips it, and a handler substitutes for `run` while preserving its output.\n   */\n  readonly dryRun?: \"skip\" | AnyStepDryRunHandler<TOptions>;\n  /** Optional Standard Schema for values published by this step. */\n  readonly outputSchema?: StandardSchemaV1;\n  /** Explicit output caching for ordinary deterministic steps only. */\n  readonly cache?: boolean | StepCache<Record<string, unknown>, TOptions>;\n  readonly [STEP_CACHE]?: CompiledStepCache<TOptions>;\n  /**\n   * Optional runtime skip. Return a non-empty reason (or `{ reason, value }`) to\n   * skip without calling `run`. Policy skips unlock dependents; structural skips\n   * (dry-run, filtered, …) do not use this hook.\n   */\n  skip?(\n    inputs: Record<string, unknown>,\n    context: PipelineExecutionContext<TOptions>\n  ): StepSkipDecision | Promise<StepSkipDecision>;\n  run(inputs: Record<string, unknown>, context: PipelineStepContext<TOptions>): unknown;\n}\n\n/** The step fields that `buildStep` merges onto the id-bearing shell. */\nexport type StepDefinitionBody<TOptions extends object> = Omit<AnyStep<TOptions>, \"id\">;\n\n/** Typed pipeline step carrying its stable ID, output, and option types. */\nexport interface Step<\n  TId extends string,\n  TOut,\n  TOptions extends object,\n  TInputOptions extends object = TOptions,\n  TRunOut = TOut,\n  TOptionsSchema extends StandardSchemaV1 | undefined = StandardSchemaV1 | undefined,\n> extends AnyStep<TOptions> {\n  readonly [STEP_OPTIONS_SCHEMA]?: TOptionsSchema;\n  readonly id: TId;\n  run(\n    inputs: Record<string, unknown>,\n    context: PipelineStepContext<TOptions>\n  ): TRunOut | Promise<TRunOut>;\n  /** Type-only: carries this step's output type for sibling inference. Never set at runtime. */\n  readonly __outputType?: TOut;\n  /** Type-only: carries pre-validation run options for pipeline call-site inference. */\n  readonly __inputOptionsType?: TInputOptions;\n}\n\n/**\n * Extract a step's output type for dependency typing.\n * Prefer matching `Step<…, TOut, …>` over `{ __outputType?: infer T }`: optional-property\n * inference collapses `TOut | undefined` to `TOut`, which hides policy-skip widening.\n */\nexport type StepOutput<S> =\n  S extends Step<string, infer TOut, infer _TOptions, infer _TInputOptions, infer _TRunOut>\n    ? TOut\n    : never;\n\nexport interface StepToken {\n  readonly id: string;\n  readonly __outputType?: unknown;\n}\n\nexport type RequiredInputs<TDeps extends readonly StepToken[]> = {\n  [S in TDeps[number] as S[\"id\"]]: StepOutput<S>;\n};\n\nexport type OptionalInputs<TDeps extends readonly StepToken[]> = {\n  [S in TDeps[number] as S[\"id\"]]?: StepOutput<S>;\n};\n\nexport type PipelineResultOf<TPipeline> =\n  TPipeline extends Pipeline<object, infer TResult, infer _TStepId, infer _TTargetId>\n    ? TResult\n    : never;\n\nexport type PipelineOptionsOf<TPipeline> =\n  TPipeline extends Pipeline<infer TOptions, unknown, infer _TStepId, infer _TTargetId>\n    ? TOptions\n    : never;\n\nexport type PipelineRunControlsOf<TPipeline> =\n  TPipeline extends Pipeline<infer _TOptions, unknown, infer TStepId, infer TTargetId>\n    ? PipelineRunControls<TStepId, TTargetId>\n    : never;\n\nexport type ChildPipelineStepDefinitionBase<\n  TParentOptions extends object,\n  TDeps extends readonly AnyStep<TParentOptions>[],\n  TOptionalDeps extends readonly AnyStep<TParentOptions>[],\n  TChildPipeline extends Pipeline<object, unknown>,\n> = {\n  pipeline: TChildPipeline;\n  dependsOn?: TDeps;\n  optionalDependsOn?: TOptionalDeps;\n  skipAfterFailureOf?: readonly AnyStep<TParentOptions>[];\n  name?: string;\n  description?: string;\n  metadata?: PipelineMetadata;\n  dryRun?: \"skip\";\n  controls?:\n    | PipelineRunControlsOf<TChildPipeline>\n    | ((\n        inputs: RequiredInputs<TDeps> & OptionalInputs<TOptionalDeps>,\n        context: PipelineExecutionContext<TParentOptions>\n      ) => PipelineRunControlsOf<TChildPipeline>);\n} & ([TParentOptions] extends [PipelineOptionsOf<NoInfer<TChildPipeline>>]\n  ? {\n      mapOptions?(\n        inputs: RequiredInputs<TDeps> & OptionalInputs<TOptionalDeps>,\n        context: PipelineExecutionContext<TParentOptions>\n      ): PipelineOptionsOf<TChildPipeline>;\n    }\n  : {\n      mapOptions(\n        inputs: RequiredInputs<TDeps> & OptionalInputs<TOptionalDeps>,\n        context: PipelineExecutionContext<TParentOptions>\n      ): PipelineOptionsOf<TChildPipeline>;\n    });\n\n/** Child step without policy skip (dependents see the full child result type). */\nexport type ChildPipelineStepDefinition<\n  TParentOptions extends object,\n  TDeps extends readonly AnyStep<TParentOptions>[],\n  TOptionalDeps extends readonly AnyStep<TParentOptions>[],\n  TChildPipeline extends Pipeline<object, unknown>,\n> = ChildPipelineStepDefinitionBase<TParentOptions, TDeps, TOptionalDeps, TChildPipeline>;\n\n/**\n * Presentation options for opaque `forEachPipeline` progress.\n * Defaults are domain-neutral (`N/M items · K running · key/step`).\n * Override `formatMessage` when a domain wants its own noun (images, shards, …).\n */\nexport type MappedChildProgressOptions = ToMappedChildStepProgressOptions;\n\nexport type MappedChildPipelineStepDefinition<\n  TParentOptions extends object,\n  TDeps extends readonly AnyStep<TParentOptions>[],\n  TOptionalDeps extends readonly AnyStep<TParentOptions>[],\n  TChildPipeline extends Pipeline<object, unknown>,\n  TItem,\n> = {\n  pipeline: TChildPipeline;\n  dependsOn?: TDeps;\n  optionalDependsOn?: TOptionalDeps;\n  skipAfterFailureOf?: readonly AnyStep<TParentOptions>[];\n  name?: string;\n  description?: string;\n  metadata?: PipelineMetadata;\n  dryRun?: \"skip\";\n  items(\n    inputs: RequiredInputs<TDeps> & OptionalInputs<TOptionalDeps>,\n    context: PipelineExecutionContext<TParentOptions>\n  ): readonly TItem[] | Promise<readonly TItem[]>;\n  key(item: TItem, index: number): string;\n  concurrency?:\n    | number\n    | ((\n        inputs: RequiredInputs<TDeps> & OptionalInputs<TOptionalDeps>,\n        context: PipelineExecutionContext<TParentOptions>\n      ) => number);\n  /**\n   * How the opaque parent step reports live fan-out progress.\n   * Purely presentational — does not change scheduling or results.\n   */\n  progress?: MappedChildProgressOptions;\n  controls?:\n    | PipelineRunControlsOf<TChildPipeline>\n    | ((\n        item: TItem,\n        index: number,\n        inputs: RequiredInputs<TDeps> & OptionalInputs<TOptionalDeps>,\n        context: PipelineExecutionContext<TParentOptions>\n      ) => PipelineRunControlsOf<TChildPipeline>);\n  mapOptions(\n    item: TItem,\n    index: number,\n    inputs: RequiredInputs<TDeps> & OptionalInputs<TOptionalDeps>,\n    context: PipelineExecutionContext<TParentOptions>\n  ): PipelineOptionsOf<TChildPipeline>;\n};\n\nexport type StepSkipPredicate<\n  TOptions extends object,\n  TDeps extends readonly AnyStep<TOptions>[],\n  TOptionalDeps extends readonly AnyStep<TOptions>[],\n  TOut,\n  TDecision extends StepSkipDecision<TOut> = StepSkipDecision<TOut>,\n> = (\n  inputs: RequiredInputs<TDeps> & OptionalInputs<TOptionalDeps>,\n  context: PipelineExecutionContext<TOptions>\n) => TDecision | Promise<TDecision>;\n\nexport type PolicySkippedOutput<TOut, TDecision> = [\n  Exclude<Awaited<TDecision>, false | null | undefined>,\n] extends [{ reason: string; value: unknown }]\n  ? TOut\n  : TOut | undefined;\n\nexport type StepDryRunPolicy<\n  TOptions extends object,\n  TDeps extends readonly AnyStep<TOptions>[],\n  TOptionalDeps extends readonly AnyStep<TOptions>[],\n  TOut,\n> =\n  | \"skip\"\n  | ((\n      inputs: RequiredInputs<TDeps> & OptionalInputs<TOptionalDeps>,\n      context: PipelineStepContext<TOptions>\n    ) => TOut | Promise<TOut>);\n\nexport type PlainStepFields<\n  TOptions extends object,\n  TDeps extends readonly AnyStep<TOptions>[],\n  TOptionalDeps extends readonly AnyStep<TOptions>[],\n  TOut,\n> = {\n  dependsOn?: TDeps;\n  optionalDependsOn?: TOptionalDeps;\n  skipAfterFailureOf?: readonly AnyStep<TOptions>[];\n  name?: string;\n  description?: string;\n  metadata?: PipelineMetadata;\n  dryRun?: StepDryRunPolicy<TOptions, TDeps, TOptionalDeps, TOut>;\n  outputSchema?: never;\n  cache?: boolean | StepCache<RequiredInputs<TDeps> & OptionalInputs<TOptionalDeps>, TOptions>;\n  run(\n    inputs: RequiredInputs<TDeps> & OptionalInputs<TOptionalDeps>,\n    context: PipelineStepContext<TOptions>\n  ): TOut | Promise<TOut>;\n};\n\nexport type SchemaStepFields<\n  TOptions extends object,\n  TDeps extends readonly AnyStep<TOptions>[],\n  TOptionalDeps extends readonly AnyStep<TOptions>[],\n  TSchema extends StandardSchemaV1,\n> = Omit<\n  PlainStepFields<TOptions, TDeps, TOptionalDeps, InferSchemaInput<TSchema>>,\n  \"outputSchema\"\n> & {\n  outputSchema: TSchema;\n};\n\nexport type RemoteStepDefinitionBase<\n  TParentOptions extends object,\n  TDeps extends readonly AnyStep<TParentOptions>[],\n  TOptionalDeps extends readonly AnyStep<TParentOptions>[],\n  TPayload,\n  TSchema extends StandardSchemaV1,\n> = {\n  adapter: RemoteStepAdapter<TParentOptions, TPayload, InferSchemaInput<TSchema>>;\n  mapInput(\n    inputs: RequiredInputs<TDeps> & OptionalInputs<TOptionalDeps>,\n    context: PipelineStepContext<TParentOptions>\n  ): TPayload;\n  outputSchema: TSchema;\n  dependsOn?: TDeps;\n  optionalDependsOn?: TOptionalDeps;\n  skipAfterFailureOf?: readonly AnyStep<TParentOptions>[];\n  name?: string;\n  description?: string;\n  metadata?: PipelineMetadata;\n  dryRun?: StepDryRunPolicy<TParentOptions, TDeps, TOptionalDeps, InferSchemaInput<TSchema>>;\n};\n"]}