tubeless 0.2.2 → 0.2.4

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

@@ -0,0 +1,17 @@
+import type { PipelineDefinition, StepsOptions } from "./pipeline-definition.js";
+import { type CompiledStepGraph } from "./pipeline-graph.js";
+import type { AnyStep } from "./pipeline-steps.js";
+import type { StandardSchemaV1 } from "./pipeline-types.js";
+export interface CompiledPipeline<TSteps extends readonly AnyStep[] = readonly AnyStep[], TResult = unknown, TTargets extends readonly TSteps[number][] = readonly [], TResultSchema extends StandardSchemaV1 | undefined = undefined> {
+    readonly declaredTargets: readonly AnyStep<StepsOptions<TSteps>>[];
+    readonly finalize: PipelineDefinition<TSteps, TResult, TTargets, TResultSchema>["finalize"];
+    readonly id: string;
+    readonly optionsSchema: StandardSchemaV1 | undefined;
+    readonly orderedSteps: readonly AnyStep<StepsOptions<TSteps>>[];
+    readonly requiredFinalizerSteps: readonly AnyStep<StepsOptions<TSteps>>[] | undefined;
+    readonly stepGraph: ReadonlyMap<AnyStep, CompiledStepGraph>;
+    readonly resultSchema: TResultSchema | undefined;
+    readonly stepIds: readonly string[];
+    readonly targetIds: readonly string[];
+}
+export declare function compilePipeline<TSteps extends readonly AnyStep[], TResult, TTargets extends readonly TSteps[number][], TResultSchema extends StandardSchemaV1 | undefined>(definition: PipelineDefinition<TSteps, TResult, TTargets, TResultSchema>): CompiledPipeline<TSteps, TResult, TTargets, TResultSchema>;

package/dist/core/pipeline-compiler.js

@@ -0,0 +1,44 @@
+import { validatePipelineDefinition } from "./pipeline-definition-validation.js";
+import { PipelineDefinitionError } from "./pipeline-errors.js";
+import { requiredFinalizerMetadata } from "./pipeline-finalizer.js";
+import { compilePipelineGraph } from "./pipeline-graph.js";
+import { STEP_OPTIONS_SCHEMA } from "./pipeline-step-metadata.js";
+export function compilePipeline(definition) {
+    const errors = validatePipelineDefinition(definition);
+    if (errors.length > 0) {
+        throw new PipelineDefinitionError(definition.id, errors);
+    }
+    // SAFETY: `steps` is `TSteps extends readonly AnyStep[]`; the cast restores
+    // the `TOptions` generic that the tuple erased, without changing the values.
+    const { compiledByAuthorStep, orderedSteps, stepGraph } = compilePipelineGraph(definition.steps);
+    const finalizerMetadata = requiredFinalizerMetadata(definition.finalize);
+    const requiredFinalizerSteps = finalizerMetadata?.steps;
+    // SAFETY: targets are a subset of `TSteps[number]`, each an `AnyStep<TOptions>`.
+    const declaredTargets = (definition.targets ?? []);
+    const compiledTargets = declaredTargets.map((target) => compiledByAuthorStep.get(target));
+    const compiledRequiredFinalizerSteps = requiredFinalizerSteps?.map((step) => compiledByAuthorStep.get(step));
+    const compiledFinalize = finalizerMetadata
+        ? finalizerMetadata.compile(compiledRequiredFinalizerSteps.map((step) => step.id))
+        : (outputs, context) => definition.finalize(outputs, context);
+    return Object.freeze({
+        declaredTargets: Object.freeze(compiledTargets),
+        // Invoke ordinary finalizers on the author's definition so method-style
+        // implementations keep `this`. Required finalizers compile the same input
+        // and context contract with stable required ids.
+        // SAFETY: both branches preserve `definition.finalize`'s call signature.
+        finalize: compiledFinalize,
+        id: definition.id,
+        optionsSchema: definition.steps.length === 0
+            ? undefined
+            : compiledByAuthorStep.get(definition.steps[0])?.[STEP_OPTIONS_SCHEMA],
+        orderedSteps: Object.freeze([...orderedSteps]),
+        stepGraph,
+        requiredFinalizerSteps: compiledRequiredFinalizerSteps
+            ? Object.freeze(compiledRequiredFinalizerSteps)
+            : undefined,
+        resultSchema: definition.resultSchema,
+        stepIds: Object.freeze(definition.steps.map((step) => compiledByAuthorStep.get(step).id)),
+        targetIds: Object.freeze(compiledTargets.map((step) => step.id)),
+    });
+}
+//# sourceMappingURL=pipeline-compiler.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"pipeline-compiler.js","sourceRoot":"","sources":["../../src/core/pipeline-compiler.ts"],"names":[],"mappings":"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","sourcesContent":["import type { PipelineDefinition, StepsOptions } from \"./pipeline-definition.js\";\nimport { validatePipelineDefinition } from \"./pipeline-definition-validation.js\";\nimport { PipelineDefinitionError } from \"./pipeline-errors.js\";\nimport { requiredFinalizerMetadata } from \"./pipeline-finalizer.js\";\nimport { compilePipelineGraph, type CompiledStepGraph } from \"./pipeline-graph.js\";\nimport type { AnyStep } from \"./pipeline-steps.js\";\nimport { STEP_OPTIONS_SCHEMA } from \"./pipeline-step-metadata.js\";\nimport type { StandardSchemaV1 } from \"./pipeline-types.js\";\n\nexport interface CompiledPipeline<\n  TSteps extends readonly AnyStep[] = readonly AnyStep[],\n  TResult = unknown,\n  TTargets extends readonly TSteps[number][] = readonly [],\n  TResultSchema extends StandardSchemaV1 | undefined = undefined,\n> {\n  readonly declaredTargets: readonly AnyStep<StepsOptions<TSteps>>[];\n  readonly finalize: PipelineDefinition<TSteps, TResult, TTargets, TResultSchema>[\"finalize\"];\n  readonly id: string;\n  readonly optionsSchema: StandardSchemaV1 | undefined;\n  readonly orderedSteps: readonly AnyStep<StepsOptions<TSteps>>[];\n  readonly requiredFinalizerSteps: readonly AnyStep<StepsOptions<TSteps>>[] | undefined;\n  readonly stepGraph: ReadonlyMap<AnyStep, CompiledStepGraph>;\n  readonly resultSchema: TResultSchema | undefined;\n  readonly stepIds: readonly string[];\n  readonly targetIds: readonly string[];\n}\n\nexport function compilePipeline<\n  TSteps extends readonly AnyStep[],\n  TResult,\n  TTargets extends readonly TSteps[number][],\n  TResultSchema extends StandardSchemaV1 | undefined,\n>(\n  definition: PipelineDefinition<TSteps, TResult, TTargets, TResultSchema>\n): CompiledPipeline<TSteps, TResult, TTargets, TResultSchema> {\n  const errors = validatePipelineDefinition(definition);\n  if (errors.length > 0) {\n    throw new PipelineDefinitionError(definition.id, errors);\n  }\n  type TOptions = StepsOptions<TSteps>;\n  // SAFETY: `steps` is `TSteps extends readonly AnyStep[]`; the cast restores\n  // the `TOptions` generic that the tuple erased, without changing the values.\n  const { compiledByAuthorStep, orderedSteps, stepGraph } = compilePipelineGraph(\n    definition.steps as readonly AnyStep<TOptions>[]\n  );\n  const finalizerMetadata = requiredFinalizerMetadata<TOptions>(definition.finalize);\n  const requiredFinalizerSteps = finalizerMetadata?.steps;\n  // SAFETY: targets are a subset of `TSteps[number]`, each an `AnyStep<TOptions>`.\n  const declaredTargets = (definition.targets ?? []) as readonly AnyStep<TOptions>[];\n  const compiledTargets = declaredTargets.map((target) => compiledByAuthorStep.get(target)!);\n  const compiledRequiredFinalizerSteps = requiredFinalizerSteps?.map((step) =>\n    compiledByAuthorStep.get(step)!\n  );\n  const compiledFinalize = finalizerMetadata\n    ? finalizerMetadata.compile(compiledRequiredFinalizerSteps!.map((step) => step.id))\n    : (\n        outputs: Parameters<typeof definition.finalize>[0],\n        context: Parameters<typeof definition.finalize>[1]\n      ) => definition.finalize(outputs, context);\n  return Object.freeze({\n    declaredTargets: Object.freeze(compiledTargets),\n    // Invoke ordinary finalizers on the author's definition so method-style\n    // implementations keep `this`. Required finalizers compile the same input\n    // and context contract with stable required ids.\n    // SAFETY: both branches preserve `definition.finalize`'s call signature.\n    finalize: compiledFinalize as typeof definition.finalize,\n    id: definition.id,\n    optionsSchema:\n      definition.steps.length === 0\n        ? undefined\n        : compiledByAuthorStep.get(definition.steps[0]!)?.[STEP_OPTIONS_SCHEMA],\n    orderedSteps: Object.freeze([...orderedSteps]),\n    stepGraph,\n    requiredFinalizerSteps: compiledRequiredFinalizerSteps\n      ? Object.freeze(compiledRequiredFinalizerSteps)\n      : undefined,\n    resultSchema: definition.resultSchema,\n    stepIds: Object.freeze(definition.steps.map((step) => compiledByAuthorStep.get(step)!.id)),\n    targetIds: Object.freeze(compiledTargets.map((step) => step.id)),\n  });\n}\n"]}

package/dist/core/pipeline-definition-validation.d.ts

@@ -0,0 +1,4 @@
+import type { PipelineDefinition } from "./pipeline-definition.js";
+import type { AnyStep } from "./pipeline-steps.js";
+import type { PipelineError, StandardSchemaV1 } from "./pipeline-types.js";
+export declare function validatePipelineDefinition<TSteps extends readonly AnyStep[], TResult, TTargets extends readonly TSteps[number][], TResultSchema extends StandardSchemaV1 | undefined>(definition: PipelineDefinition<TSteps, TResult, TTargets, TResultSchema>): PipelineError[];

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

@@ -0,0 +1,101 @@
+import { duplicateValues } from "../utilities/collections.js";
+import { requiredFinalizerMetadata } from "./pipeline-finalizer.js";
+import { stepEdges, targetClosure, topologicalSort } from "./pipeline-graph.js";
+import { pipelineDiagnostic } from "./pipeline-errors.js";
+import { PIPELINE_FINALIZE_STEP_ID, STEP_OPTIONS_SCHEMA } from "./pipeline-step-metadata.js";
+export function validatePipelineDefinition(definition) {
+    const steps = definition.steps;
+    const errors = [];
+    if (definition.id.trim().length === 0) {
+        errors.push(pipelineDiagnostic("TUBELESS_DEFINITION_PIPELINE_ID_BLANK", "definition", "definition", "Pipeline id must not be blank"));
+    }
+    const stepIds = steps.map((step) => step.id);
+    const duplicateStepIds = duplicateValues(stepIds);
+    if (duplicateStepIds.length > 0) {
+        errors.push(pipelineDiagnostic("TUBELESS_DEFINITION_STEP_IDS_DUPLICATE", "definition", "definition", `Pipeline ${definition.id} has duplicate step ids: ${duplicateStepIds.join(", ")}`));
+    }
+    const optionsSchemas = new Set(steps.map((step) => step[STEP_OPTIONS_SCHEMA]));
+    if (optionsSchemas.size > 1 && [...optionsSchemas].some(Boolean)) {
+        errors.push(pipelineDiagnostic("TUBELESS_DEFINITION_OPTIONS_SCHEMA_CONFLICT", "definition", "definition", `Pipeline ${definition.id} mixes steps from different options-schema scopes`));
+    }
+    for (const step of steps) {
+        if (step.id.trim().length === 0) {
+            errors.push(pipelineDiagnostic("TUBELESS_DEFINITION_STEP_ID_BLANK", "definition", "definition", `Pipeline ${definition.id} has a step with a blank id`, { stepId: step.id }));
+        }
+        if (step.id === PIPELINE_FINALIZE_STEP_ID) {
+            errors.push(pipelineDiagnostic("TUBELESS_DEFINITION_STEP_ID_RESERVED", "definition", "definition", `Pipeline ${definition.id} uses reserved step id ${PIPELINE_FINALIZE_STEP_ID}`, { stepId: step.id }));
+        }
+        if (step.name !== undefined && step.name.trim().length === 0) {
+            errors.push(pipelineDiagnostic("TUBELESS_DEFINITION_STEP_NAME_BLANK", "definition", "definition", `Pipeline ${definition.id} step ${step.id} has a blank display name`, { stepId: step.id }));
+        }
+        const dependencyGroups = [
+            ["dependsOn", step.dependsOn ?? []],
+            ["optionalDependsOn", step.optionalDependsOn ?? []],
+            ["skipAfterFailureOf", step.skipAfterFailureOf ?? []],
+        ];
+        for (const [field, dependencies] of dependencyGroups) {
+            const duplicates = duplicateValues(dependencies.map((dependency) => dependency.id));
+            if (duplicates.length > 0) {
+                errors.push(pipelineDiagnostic("TUBELESS_DEFINITION_DEPENDENCY_DUPLICATE", "definition", "definition", `Pipeline ${definition.id} step ${step.id} repeats ${field}: ${duplicates.join(", ")}`, { stepId: step.id }));
+            }
+            if (dependencies.includes(step)) {
+                errors.push(pipelineDiagnostic("TUBELESS_DEFINITION_DEPENDENCY_SELF_REFERENCE", "definition", "definition", `Pipeline ${definition.id} step ${step.id} cannot reference itself in ${field}`, { stepId: step.id }));
+            }
+        }
+        const required = new Set(step.dependsOn ?? []);
+        const contradictory = (step.optionalDependsOn ?? []).filter((dependency) => required.has(dependency));
+        if (contradictory.length > 0) {
+            errors.push(pipelineDiagnostic("TUBELESS_DEFINITION_DEPENDENCY_CONTRADICTORY", "definition", "definition", `Pipeline ${definition.id} step ${step.id} declares dependencies as both required and optional: ${contradictory.map(({ id }) => id).join(", ")}`, { stepId: step.id }));
+        }
+    }
+    // SAFETY: `steps` is `TSteps extends readonly AnyStep[]`; the cast restores
+    // the `TOptions` generic that the tuple erased, without changing the values.
+    const knownSteps = new Set(steps);
+    // SAFETY: targets are a subset of `TSteps[number]`, each an `AnyStep<TOptions>`.
+    const declaredTargets = (definition.targets ?? []);
+    const duplicateTargetIds = duplicateValues(declaredTargets.map((target) => target.id));
+    if (duplicateTargetIds.length > 0) {
+        errors.push(pipelineDiagnostic("TUBELESS_DEFINITION_TARGETS_DUPLICATE", "definition", "definition", `Pipeline ${definition.id} declares duplicate targets: ${duplicateTargetIds.join(", ")}`));
+    }
+    const missingTargets = declaredTargets.filter((target) => !knownSteps.has(target));
+    if (missingTargets.length > 0) {
+        errors.push(pipelineDiagnostic("TUBELESS_DEFINITION_TARGET_NOT_IN_STEPS", "definition", "definition", `Pipeline ${definition.id} declares target step(s) not included in its steps list: ${missingTargets.map(({ id }) => id).join(", ")}`));
+    }
+    const missingReferences = [];
+    // SAFETY: `steps` is `TSteps extends readonly AnyStep[]`; the cast restores the
+    // `TOptions` generic that the tuple erased, without changing the values.
+    for (const step of steps) {
+        for (const dependency of stepEdges(step)) {
+            if (!knownSteps.has(dependency)) {
+                missingReferences.push(`${step.id} -> ${dependency.id}`);
+            }
+        }
+    }
+    if (missingReferences.length > 0) {
+        errors.push(pipelineDiagnostic("TUBELESS_DEFINITION_DEPENDENCY_NOT_IN_STEPS", "definition", "definition", `Pipeline ${definition.id} references step(s) not included in its steps list: ${missingReferences.join(", ")}`));
+    }
+    const requiredFinalizerSteps = requiredFinalizerMetadata(definition.finalize)?.steps;
+    const missingFinalizerSteps = (requiredFinalizerSteps ?? []).filter((step) => !knownSteps.has(step));
+    if (missingFinalizerSteps.length > 0) {
+        errors.push(pipelineDiagnostic("TUBELESS_DEFINITION_FINALIZER_STEP_NOT_IN_STEPS", "definition", "definition", `Pipeline ${definition.id} requires finalizer output from step(s) not included in its steps list: ${missingFinalizerSteps.map(({ id }) => id).join(", ")}`));
+    }
+    if (requiredFinalizerSteps &&
+        missingTargets.length === 0 &&
+        missingReferences.length === 0 &&
+        missingFinalizerSteps.length === 0) {
+        for (const target of declaredTargets) {
+            const selected = targetClosure([target]);
+            const missingRequiredSteps = requiredFinalizerSteps.filter((step) => !selected.has(step));
+            if (missingRequiredSteps.length > 0) {
+                errors.push(pipelineDiagnostic("TUBELESS_DEFINITION_TARGET_FINALIZER_MISMATCH", "definition", "definition", `Pipeline ${definition.id} target ${target.id} cannot satisfy required finalizer output(s): ${missingRequiredSteps.map(({ id }) => id).join(", ")}`, { stepId: target.id }));
+            }
+        }
+    }
+    // SAFETY: `steps` is `TSteps extends readonly AnyStep[]`; the cast restores the
+    // `TOptions` generic that the tuple erased, without changing the values.
+    if (errors.length === 0 && !topologicalSort(steps)) {
+        errors.push(pipelineDiagnostic("TUBELESS_DEFINITION_DEPENDENCY_CYCLE", "definition", "definition", `Pipeline ${definition.id} has a dependency cycle`));
+    }
+    return errors;
+}
+//# sourceMappingURL=pipeline-definition-validation.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"pipeline-definition-validation.js","sourceRoot":"","sources":["../../src/core/pipeline-definition-validation.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,eAAe,EAAE,MAAM,6BAA6B,CAAC;AAE9D,OAAO,EAAE,yBAAyB,EAAE,MAAM,yBAAyB,CAAC;AACpE,OAAO,EAAE,SAAS,EAAE,aAAa,EAAE,eAAe,EAAE,MAAM,qBAAqB,CAAC;AAChF,OAAO,EAAE,kBAAkB,EAAE,MAAM,sBAAsB,CAAC;AAE1D,OAAO,EAAE,yBAAyB,EAAE,mBAAmB,EAAE,MAAM,6BAA6B,CAAC;AAG7F,MAAM,UAAU,0BAA0B,CAKxC,UAAwE;IAExE,MAAM,KAAK,GAAG,UAAU,CAAC,KAAK,CAAC;IAC/B,MAAM,MAAM,GAAoB,EAAE,CAAC;IACnC,IAAI,UAAU,CAAC,EAAE,CAAC,IAAI,EAAE,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QACtC,MAAM,CAAC,IAAI,CACT,kBAAkB,CAChB,uCAAuC,EACvC,YAAY,EACZ,YAAY,EACZ,+BAA+B,CAChC,CACF,CAAC;IACJ,CAAC;IAED,MAAM,OAAO,GAAG,KAAK,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;IAC7C,MAAM,gBAAgB,GAAG,eAAe,CAAC,OAAO,CAAC,CAAC;IAClD,IAAI,gBAAgB,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QAChC,MAAM,CAAC,IAAI,CACT,kBAAkB,CAChB,wCAAwC,EACxC,YAAY,EACZ,YAAY,EACZ,YAAY,UAAU,CAAC,EAAE,4BAA4B,gBAAgB,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CACnF,CACF,CAAC;IACJ,CAAC;IACD,MAAM,cAAc,GAAG,IAAI,GAAG,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,CAAC,mBAAmB,CAAC,CAAC,CAAC,CAAC;IAC/E,IAAI,cAAc,CAAC,IAAI,GAAG,CAAC,IAAI,CAAC,GAAG,cAAc,CAAC,CAAC,IAAI,CAAC,OAAO,CAAC,EAAE,CAAC;QACjE,MAAM,CAAC,IAAI,CACT,kBAAkB,CAChB,6CAA6C,EAC7C,YAAY,EACZ,YAAY,EACZ,YAAY,UAAU,CAAC,EAAE,mDAAmD,CAC7E,CACF,CAAC;IACJ,CAAC;IACD,KAAK,MAAM,IAAI,IAAI,KAAK,EAAE,CAAC;QACzB,IAAI,IAAI,CAAC,EAAE,CAAC,IAAI,EAAE,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;YAChC,MAAM,CAAC,IAAI,CACT,kBAAkB,CAChB,mCAAmC,EACnC,YAAY,EACZ,YAAY,EACZ,YAAY,UAAU,CAAC,EAAE,6BAA6B,EACtD,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,EAAE,CACpB,CACF,CAAC;QACJ,CAAC;QACD,IAAI,IAAI,CAAC,EAAE,KAAK,yBAAyB,EAAE,CAAC;YAC1C,MAAM,CAAC,IAAI,CACT,kBAAkB,CAChB,sCAAsC,EACtC,YAAY,EACZ,YAAY,EACZ,YAAY,UAAU,CAAC,EAAE,0BAA0B,yBAAyB,EAAE,EAC9E,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,EAAE,CACpB,CACF,CAAC;QACJ,CAAC;QACD,IAAI,IAAI,CAAC,IAAI,KAAK,SAAS,IAAI,IAAI,CAAC,IAAI,CAAC,IAAI,EAAE,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;YAC7D,MAAM,CAAC,IAAI,CACT,kBAAkB,CAChB,qCAAqC,EACrC,YAAY,EACZ,YAAY,EACZ,YAAY,UAAU,CAAC,EAAE,SAAS,IAAI,CAAC,EAAE,2BAA2B,EACpE,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,EAAE,CACpB,CACF,CAAC;QACJ,CAAC;QACD,MAAM,gBAAgB,GAAG;YACvB,CAAC,WAAW,EAAE,IAAI,CAAC,SAAS,IAAI,EAAE,CAAC;YACnC,CAAC,mBAAmB,EAAE,IAAI,CAAC,iBAAiB,IAAI,EAAE,CAAC;YACnD,CAAC,oBAAoB,EAAE,IAAI,CAAC,kBAAkB,IAAI,EAAE,CAAC;SAC7C,CAAC;QACX,KAAK,MAAM,CAAC,KAAK,EAAE,YAAY,CAAC,IAAI,gBAAgB,EAAE,CAAC;YACrD,MAAM,UAAU,GAAG,eAAe,CAAC,YAAY,CAAC,GAAG,CAAC,CAAC,UAAU,EAAE,EAAE,CAAC,UAAU,CAAC,EAAE,CAAC,CAAC,CAAC;YACpF,IAAI,UAAU,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;gBAC1B,MAAM,CAAC,IAAI,CACT,kBAAkB,CAChB,0CAA0C,EAC1C,YAAY,EACZ,YAAY,EACZ,YAAY,UAAU,CAAC,EAAE,SAAS,IAAI,CAAC,EAAE,YAAY,KAAK,KAAK,UAAU,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,EACtF,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,EAAE,CACpB,CACF,CAAC;YACJ,CAAC;YACD,IAAI,YAAY,CAAC,QAAQ,CAAC,IAAI,CAAC,EAAE,CAAC;gBAChC,MAAM,CAAC,IAAI,CACT,kBAAkB,CAChB,+CAA+C,EAC/C,YAAY,EACZ,YAAY,EACZ,YAAY,UAAU,CAAC,EAAE,SAAS,IAAI,CAAC,EAAE,+BAA+B,KAAK,EAAE,EAC/E,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,EAAE,CACpB,CACF,CAAC;YACJ,CAAC;QACH,CAAC;QAED,MAAM,QAAQ,GAAG,IAAI,GAAG,CAAC,IAAI,CAAC,SAAS,IAAI,EAAE,CAAC,CAAC;QAC/C,MAAM,aAAa,GAAG,CAAC,IAAI,CAAC,iBAAiB,IAAI,EAAE,CAAC,CAAC,MAAM,CAAC,CAAC,UAAU,EAAE,EAAE,CACzE,QAAQ,CAAC,GAAG,CAAC,UAAU,CAAC,CACzB,CAAC;QACF,IAAI,aAAa,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;YAC7B,MAAM,CAAC,IAAI,CACT,kBAAkB,CAChB,8CAA8C,EAC9C,YAAY,EACZ,YAAY,EACZ,YAAY,UAAU,CAAC,EAAE,SAAS,IAAI,CAAC,EAAE,yDAAyD,aAAa,CAAC,GAAG,CAAC,CAAC,EAAE,EAAE,EAAE,EAAE,EAAE,CAAC,EAAE,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,EAChJ,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,EAAE,CACpB,CACF,CAAC;QACJ,CAAC;IACH,CAAC;IAED,4EAA4E;IAC5E,6EAA6E;IAC7E,MAAM,UAAU,GAAG,IAAI,GAAG,CAAoB,KAAqC,CAAC,CAAC;IACrF,iFAAiF;IACjF,MAAM,eAAe,GAAG,CAAC,UAAU,CAAC,OAAO,IAAI,EAAE,CAAiC,CAAC;IACnF,MAAM,kBAAkB,GAAG,eAAe,CAAC,eAAe,CAAC,GAAG,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC,MAAM,CAAC,EAAE,CAAC,CAAC,CAAC;IACvF,IAAI,kBAAkB,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QAClC,MAAM,CAAC,IAAI,CACT,kBAAkB,CAChB,uCAAuC,EACvC,YAAY,EACZ,YAAY,EACZ,YAAY,UAAU,CAAC,EAAE,gCAAgC,kBAAkB,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CACzF,CACF,CAAC;IACJ,CAAC;IACD,MAAM,cAAc,GAAG,eAAe,CAAC,MAAM,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC,UAAU,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC,CAAC;IACnF,IAAI,cAAc,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QAC9B,MAAM,CAAC,IAAI,CACT,kBAAkB,CAChB,yCAAyC,EACzC,YAAY,EACZ,YAAY,EACZ,YAAY,UAAU,CAAC,EAAE,4DAA4D,cAAc,CAAC,GAAG,CAAC,CAAC,EAAE,EAAE,EAAE,EAAE,EAAE,CAAC,EAAE,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CACrI,CACF,CAAC;IACJ,CAAC;IACD,MAAM,iBAAiB,GAAa,EAAE,CAAC;IACvC,gFAAgF;IAChF,yEAAyE;IACzE,KAAK,MAAM,IAAI,IAAI,KAAqC,EAAE,CAAC;QACzD,KAAK,MAAM,UAAU,IAAI,SAAS,CAAC,IAAI,CAAC,EAAE,CAAC;YACzC,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC,UAAU,CAAC,EAAE,CAAC;gBAChC,iBAAiB,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC,EAAE,OAAO,UAAU,CAAC,EAAE,EAAE,CAAC,CAAC;YAC3D,CAAC;QACH,CAAC;IACH,CAAC;IACD,IAAI,iBAAiB,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QACjC,MAAM,CAAC,IAAI,CACT,kBAAkB,CAChB,6CAA6C,EAC7C,YAAY,EACZ,YAAY,EACZ,YAAY,UAAU,CAAC,EAAE,uDAAuD,iBAAiB,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAC/G,CACF,CAAC;IACJ,CAAC;IAED,MAAM,sBAAsB,GAAG,yBAAyB,CAAW,UAAU,CAAC,QAAQ,CAAC,EAAE,KAAK,CAAC;IAC/F,MAAM,qBAAqB,GAAG,CAAC,sBAAsB,IAAI,EAAE,CAAC,CAAC,MAAM,CACjE,CAAC,IAAI,EAAE,EAAE,CAAC,CAAC,UAAU,CAAC,GAAG,CAAC,IAAI,CAAC,CAChC,CAAC;IACF,IAAI,qBAAqB,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QACrC,MAAM,CAAC,IAAI,CACT,kBAAkB,CAChB,iDAAiD,EACjD,YAAY,EACZ,YAAY,EACZ,YAAY,UAAU,CAAC,EAAE,2EAA2E,qBAAqB,CAAC,GAAG,CAAC,CAAC,EAAE,EAAE,EAAE,EAAE,EAAE,CAAC,EAAE,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAC3J,CACF,CAAC;IACJ,CAAC;IAED,IACE,sBAAsB;QACtB,cAAc,CAAC,MAAM,KAAK,CAAC;QAC3B,iBAAiB,CAAC,MAAM,KAAK,CAAC;QAC9B,qBAAqB,CAAC,MAAM,KAAK,CAAC,EAClC,CAAC;QACD,KAAK,MAAM,MAAM,IAAI,eAAe,EAAE,CAAC;YACrC,MAAM,QAAQ,GAAG,aAAa,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC;YACzC,MAAM,oBAAoB,GAAG,sBAAsB,CAAC,MAAM,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,CAAC,QAAQ,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC,CAAC;YAC1F,IAAI,oBAAoB,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;gBACpC,MAAM,CAAC,IAAI,CACT,kBAAkB,CAChB,+CAA+C,EAC/C,YAAY,EACZ,YAAY,EACZ,YAAY,UAAU,CAAC,EAAE,WAAW,MAAM,CAAC,EAAE,iDAAiD,oBAAoB,CAAC,GAAG,CAAC,CAAC,EAAE,EAAE,EAAE,EAAE,EAAE,CAAC,EAAE,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,EACnJ,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,EAAE,CACtB,CACF,CAAC;YACJ,CAAC;QACH,CAAC;IACH,CAAC;IAED,gFAAgF;IAChF,yEAAyE;IACzE,IAAI,MAAM,CAAC,MAAM,KAAK,CAAC,IAAI,CAAC,eAAe,CAAC,KAAqC,CAAC,EAAE,CAAC;QACnF,MAAM,CAAC,IAAI,CACT,kBAAkB,CAChB,sCAAsC,EACtC,YAAY,EACZ,YAAY,EACZ,YAAY,UAAU,CAAC,EAAE,yBAAyB,CACnD,CACF,CAAC;IACJ,CAAC;IACD,OAAO,MAAM,CAAC;AAChB,CAAC","sourcesContent":["import { duplicateValues } from \"../utilities/collections.js\";\nimport type { PipelineDefinition, StepsOptions } from \"./pipeline-definition.js\";\nimport { requiredFinalizerMetadata } from \"./pipeline-finalizer.js\";\nimport { stepEdges, targetClosure, topologicalSort } from \"./pipeline-graph.js\";\nimport { pipelineDiagnostic } from \"./pipeline-errors.js\";\nimport type { AnyStep } from \"./pipeline-steps.js\";\nimport { PIPELINE_FINALIZE_STEP_ID, STEP_OPTIONS_SCHEMA } from \"./pipeline-step-metadata.js\";\nimport type { PipelineError, StandardSchemaV1 } from \"./pipeline-types.js\";\n\nexport function validatePipelineDefinition<\n  TSteps extends readonly AnyStep[],\n  TResult,\n  TTargets extends readonly TSteps[number][],\n  TResultSchema extends StandardSchemaV1 | undefined,\n>(definition: PipelineDefinition<TSteps, TResult, TTargets, TResultSchema>): PipelineError[] {\n  type TOptions = StepsOptions<TSteps>;\n  const steps = definition.steps;\n  const errors: PipelineError[] = [];\n  if (definition.id.trim().length === 0) {\n    errors.push(\n      pipelineDiagnostic(\n        \"TUBELESS_DEFINITION_PIPELINE_ID_BLANK\",\n        \"definition\",\n        \"definition\",\n        \"Pipeline id must not be blank\"\n      )\n    );\n  }\n\n  const stepIds = steps.map((step) => step.id);\n  const duplicateStepIds = duplicateValues(stepIds);\n  if (duplicateStepIds.length > 0) {\n    errors.push(\n      pipelineDiagnostic(\n        \"TUBELESS_DEFINITION_STEP_IDS_DUPLICATE\",\n        \"definition\",\n        \"definition\",\n        `Pipeline ${definition.id} has duplicate step ids: ${duplicateStepIds.join(\", \")}`\n      )\n    );\n  }\n  const optionsSchemas = new Set(steps.map((step) => step[STEP_OPTIONS_SCHEMA]));\n  if (optionsSchemas.size > 1 && [...optionsSchemas].some(Boolean)) {\n    errors.push(\n      pipelineDiagnostic(\n        \"TUBELESS_DEFINITION_OPTIONS_SCHEMA_CONFLICT\",\n        \"definition\",\n        \"definition\",\n        `Pipeline ${definition.id} mixes steps from different options-schema scopes`\n      )\n    );\n  }\n  for (const step of steps) {\n    if (step.id.trim().length === 0) {\n      errors.push(\n        pipelineDiagnostic(\n          \"TUBELESS_DEFINITION_STEP_ID_BLANK\",\n          \"definition\",\n          \"definition\",\n          `Pipeline ${definition.id} has a step with a blank id`,\n          { stepId: step.id }\n        )\n      );\n    }\n    if (step.id === PIPELINE_FINALIZE_STEP_ID) {\n      errors.push(\n        pipelineDiagnostic(\n          \"TUBELESS_DEFINITION_STEP_ID_RESERVED\",\n          \"definition\",\n          \"definition\",\n          `Pipeline ${definition.id} uses reserved step id ${PIPELINE_FINALIZE_STEP_ID}`,\n          { stepId: step.id }\n        )\n      );\n    }\n    if (step.name !== undefined && step.name.trim().length === 0) {\n      errors.push(\n        pipelineDiagnostic(\n          \"TUBELESS_DEFINITION_STEP_NAME_BLANK\",\n          \"definition\",\n          \"definition\",\n          `Pipeline ${definition.id} step ${step.id} has a blank display name`,\n          { stepId: step.id }\n        )\n      );\n    }\n    const dependencyGroups = [\n      [\"dependsOn\", step.dependsOn ?? []],\n      [\"optionalDependsOn\", step.optionalDependsOn ?? []],\n      [\"skipAfterFailureOf\", step.skipAfterFailureOf ?? []],\n    ] as const;\n    for (const [field, dependencies] of dependencyGroups) {\n      const duplicates = duplicateValues(dependencies.map((dependency) => dependency.id));\n      if (duplicates.length > 0) {\n        errors.push(\n          pipelineDiagnostic(\n            \"TUBELESS_DEFINITION_DEPENDENCY_DUPLICATE\",\n            \"definition\",\n            \"definition\",\n            `Pipeline ${definition.id} step ${step.id} repeats ${field}: ${duplicates.join(\", \")}`,\n            { stepId: step.id }\n          )\n        );\n      }\n      if (dependencies.includes(step)) {\n        errors.push(\n          pipelineDiagnostic(\n            \"TUBELESS_DEFINITION_DEPENDENCY_SELF_REFERENCE\",\n            \"definition\",\n            \"definition\",\n            `Pipeline ${definition.id} step ${step.id} cannot reference itself in ${field}`,\n            { stepId: step.id }\n          )\n        );\n      }\n    }\n\n    const required = new Set(step.dependsOn ?? []);\n    const contradictory = (step.optionalDependsOn ?? []).filter((dependency) =>\n      required.has(dependency)\n    );\n    if (contradictory.length > 0) {\n      errors.push(\n        pipelineDiagnostic(\n          \"TUBELESS_DEFINITION_DEPENDENCY_CONTRADICTORY\",\n          \"definition\",\n          \"definition\",\n          `Pipeline ${definition.id} step ${step.id} declares dependencies as both required and optional: ${contradictory.map(({ id }) => id).join(\", \")}`,\n          { stepId: step.id }\n        )\n      );\n    }\n  }\n\n  // SAFETY: `steps` is `TSteps extends readonly AnyStep[]`; the cast restores\n  // the `TOptions` generic that the tuple erased, without changing the values.\n  const knownSteps = new Set<AnyStep<TOptions>>(steps as readonly AnyStep<TOptions>[]);\n  // SAFETY: targets are a subset of `TSteps[number]`, each an `AnyStep<TOptions>`.\n  const declaredTargets = (definition.targets ?? []) as readonly AnyStep<TOptions>[];\n  const duplicateTargetIds = duplicateValues(declaredTargets.map((target) => target.id));\n  if (duplicateTargetIds.length > 0) {\n    errors.push(\n      pipelineDiagnostic(\n        \"TUBELESS_DEFINITION_TARGETS_DUPLICATE\",\n        \"definition\",\n        \"definition\",\n        `Pipeline ${definition.id} declares duplicate targets: ${duplicateTargetIds.join(\", \")}`\n      )\n    );\n  }\n  const missingTargets = declaredTargets.filter((target) => !knownSteps.has(target));\n  if (missingTargets.length > 0) {\n    errors.push(\n      pipelineDiagnostic(\n        \"TUBELESS_DEFINITION_TARGET_NOT_IN_STEPS\",\n        \"definition\",\n        \"definition\",\n        `Pipeline ${definition.id} declares target step(s) not included in its steps list: ${missingTargets.map(({ id }) => id).join(\", \")}`\n      )\n    );\n  }\n  const missingReferences: string[] = [];\n  // SAFETY: `steps` is `TSteps extends readonly AnyStep[]`; the cast restores the\n  // `TOptions` generic that the tuple erased, without changing the values.\n  for (const step of steps as readonly AnyStep<TOptions>[]) {\n    for (const dependency of stepEdges(step)) {\n      if (!knownSteps.has(dependency)) {\n        missingReferences.push(`${step.id} -> ${dependency.id}`);\n      }\n    }\n  }\n  if (missingReferences.length > 0) {\n    errors.push(\n      pipelineDiagnostic(\n        \"TUBELESS_DEFINITION_DEPENDENCY_NOT_IN_STEPS\",\n        \"definition\",\n        \"definition\",\n        `Pipeline ${definition.id} references step(s) not included in its steps list: ${missingReferences.join(\", \")}`\n      )\n    );\n  }\n\n  const requiredFinalizerSteps = requiredFinalizerMetadata<TOptions>(definition.finalize)?.steps;\n  const missingFinalizerSteps = (requiredFinalizerSteps ?? []).filter(\n    (step) => !knownSteps.has(step)\n  );\n  if (missingFinalizerSteps.length > 0) {\n    errors.push(\n      pipelineDiagnostic(\n        \"TUBELESS_DEFINITION_FINALIZER_STEP_NOT_IN_STEPS\",\n        \"definition\",\n        \"definition\",\n        `Pipeline ${definition.id} requires finalizer output from step(s) not included in its steps list: ${missingFinalizerSteps.map(({ id }) => id).join(\", \")}`\n      )\n    );\n  }\n\n  if (\n    requiredFinalizerSteps &&\n    missingTargets.length === 0 &&\n    missingReferences.length === 0 &&\n    missingFinalizerSteps.length === 0\n  ) {\n    for (const target of declaredTargets) {\n      const selected = targetClosure([target]);\n      const missingRequiredSteps = requiredFinalizerSteps.filter((step) => !selected.has(step));\n      if (missingRequiredSteps.length > 0) {\n        errors.push(\n          pipelineDiagnostic(\n            \"TUBELESS_DEFINITION_TARGET_FINALIZER_MISMATCH\",\n            \"definition\",\n            \"definition\",\n            `Pipeline ${definition.id} target ${target.id} cannot satisfy required finalizer output(s): ${missingRequiredSteps.map(({ id }) => id).join(\", \")}`,\n            { stepId: target.id }\n          )\n        );\n      }\n    }\n  }\n\n  // SAFETY: `steps` is `TSteps extends readonly AnyStep[]`; the cast restores the\n  // `TOptions` generic that the tuple erased, without changing the values.\n  if (errors.length === 0 && !topologicalSort(steps as readonly AnyStep<TOptions>[])) {\n    errors.push(\n      pipelineDiagnostic(\n        \"TUBELESS_DEFINITION_DEPENDENCY_CYCLE\",\n        \"definition\",\n        \"definition\",\n        `Pipeline ${definition.id} has a dependency cycle`\n      )\n    );\n  }\n  return errors;\n}\n"]}

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

@@ -0,0 +1,28 @@
+import type { AnyStep, Step, StepOutput } from "./pipeline-steps.js";
+import type { InferSchemaInput, PipelineExecutionContext, StandardSchemaV1 } from "./pipeline-types.js";
+/**
+ * Recovers the options type from the steps themselves rather than taking it as its own
+ * generic parameter. A `TOptions` parameter constrained by `TSteps extends
+ * readonly AnyStep<TOptions>[]` is self-referential — TypeScript can't solve that at a
+ * `definePipeline(...)` call site and silently widens `TOptions` to its bare
+ * `object` constraint (context.options would lose every pipeline-specific
+ * field). Structuring it as "derive TOptions from TSteps" instead of "constrain TSteps by
+ * TOptions" avoids the cycle, so callers never write out any of these type parameters.
+ */
+export type StepsOptions<TSteps extends readonly AnyStep[]> = TSteps[number] extends AnyStep<infer TOptions> ? TOptions : object;
+export type StepsInputOptions<TSteps extends readonly AnyStep[]> = TSteps[number] extends Step<string, unknown, object, infer TInputOptions, infer _TRunOut> ? TInputOptions : StepsOptions<TSteps>;
+export type StepIds<TSteps extends readonly AnyStep[]> = TSteps[number]["id"];
+export type TargetIds<TTargets extends readonly AnyStep[]> = TTargets[number]["id"];
+type PipelineOutputs<TSteps extends readonly AnyStep[]> = {
+    [S in TSteps[number] as S["id"]]: StepOutput<S>;
+};
+export interface PipelineDefinition<TSteps extends readonly AnyStep[], TResult, TTargets extends readonly TSteps[number][] = readonly [], TResultSchema extends StandardSchemaV1 | undefined = undefined> {
+    id: string;
+    steps: TSteps;
+    /** Public downstream goals that callers may select with `targets`. */
+    targets?: TTargets;
+    /** Optional Standard Schema for the finalized result. */
+    resultSchema?: TResultSchema;
+    finalize(outputs: Partial<PipelineOutputs<TSteps>>, context: PipelineExecutionContext<StepsOptions<TSteps>>): (TResultSchema extends StandardSchemaV1 ? InferSchemaInput<TResultSchema> : TResult) | Promise<TResultSchema extends StandardSchemaV1 ? InferSchemaInput<TResultSchema> : TResult>;
+}
+export {};

package/dist/core/pipeline-definition.js

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

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

@@ -0,0 +1 @@
+{"version":3,"file":"pipeline-definition.js","sourceRoot":"","sources":["../../src/core/pipeline-definition.ts"],"names":[],"mappings":"","sourcesContent":["import type { AnyStep, Step, StepOutput } from \"./pipeline-steps.js\";\nimport type {\n  InferSchemaInput,\n  PipelineExecutionContext,\n  StandardSchemaV1,\n} from \"./pipeline-types.js\";\n\n/**\n * Recovers the options type from the steps themselves rather than taking it as its own\n * generic parameter. A `TOptions` parameter constrained by `TSteps extends\n * readonly AnyStep<TOptions>[]` is self-referential — TypeScript can't solve that at a\n * `definePipeline(...)` call site and silently widens `TOptions` to its bare\n * `object` constraint (context.options would lose every pipeline-specific\n * field). Structuring it as \"derive TOptions from TSteps\" instead of \"constrain TSteps by\n * TOptions\" avoids the cycle, so callers never write out any of these type parameters.\n */\nexport type StepsOptions<TSteps extends readonly AnyStep[]> =\n  TSteps[number] extends AnyStep<infer TOptions> ? TOptions : object;\n\nexport type StepsInputOptions<TSteps extends readonly AnyStep[]> =\n  TSteps[number] extends Step<string, unknown, object, infer TInputOptions, infer _TRunOut>\n    ? TInputOptions\n    : StepsOptions<TSteps>;\n\nexport type StepIds<TSteps extends readonly AnyStep[]> = TSteps[number][\"id\"];\n\nexport type TargetIds<TTargets extends readonly AnyStep[]> = TTargets[number][\"id\"];\n\ntype PipelineOutputs<TSteps extends readonly AnyStep[]> = {\n  [S in TSteps[number] as S[\"id\"]]: StepOutput<S>;\n};\n\nexport interface PipelineDefinition<\n  TSteps extends readonly AnyStep[],\n  TResult,\n  TTargets extends readonly TSteps[number][] = readonly [],\n  TResultSchema extends StandardSchemaV1 | undefined = undefined,\n> {\n  id: string;\n  steps: TSteps;\n  /** Public downstream goals that callers may select with `targets`. */\n  targets?: TTargets;\n  /** Optional Standard Schema for the finalized result. */\n  resultSchema?: TResultSchema;\n  finalize(\n    outputs: Partial<PipelineOutputs<TSteps>>,\n    context: PipelineExecutionContext<StepsOptions<TSteps>>\n  ):\n    | (TResultSchema extends StandardSchemaV1 ? InferSchemaInput<TResultSchema> : TResult)\n    | Promise<TResultSchema extends StandardSchemaV1 ? InferSchemaInput<TResultSchema> : TResult>;\n}\n"]}

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

@@ -0,0 +1,26 @@
+import type { CompiledStepGraph } from "./pipeline-graph.js";
+import type { AnyStep } from "./pipeline-steps.js";
+import type { PipelinePlanStep, PipelineStepReport, PipelineStepSkipReason } from "./pipeline-types.js";
+type StepDispositionInput<TOptions extends object> = {
+    dryRun: boolean;
+    graph: CompiledStepGraph<TOptions>;
+    planned: PipelinePlanStep;
+    reportsByStepId: ReadonlyMap<string, PipelineStepReport>;
+    step: AnyStep<TOptions>;
+};
+type StepDisposition = {
+    kind: "run";
+} | {
+    kind: "skip";
+    reason: PipelineStepSkipReason;
+    dependencyId?: string;
+    message?: string;
+};
+/**
+ * Single skip ladder for plan and live execution.
+ * Policy skips stay outside: they run only after a step is scheduled.
+ * Remainder copies plan `skipReason` for structural skips and marks planned-run
+ * steps fail-fast or cancelled, so this ladder has no abort/fail-fast mode.
+ */
+export declare function decideStepDisposition<TOptions extends object>(input: StepDispositionInput<TOptions>): StepDisposition;
+export {};

package/dist/core/pipeline-disposition.js

@@ -0,0 +1,44 @@
+/** Required dependencies are met when completed, or intentionally policy-skipped. */
+function isRequiredDependencyMet(report) {
+    if (!report)
+        return false;
+    if (report.status === "completed")
+        return true;
+    return report.status === "skipped" && report.reason === "policy";
+}
+/**
+ * Single skip ladder for plan and live execution.
+ * Policy skips stay outside: they run only after a step is scheduled.
+ * Remainder copies plan `skipReason` for structural skips and marks planned-run
+ * steps fail-fast or cancelled, so this ladder has no abort/fail-fast mode.
+ */
+export function decideStepDisposition(input) {
+    const { dryRun, graph, planned, reportsByStepId, step } = input;
+    if (!planned.selected) {
+        return { kind: "skip", reason: "filtered" };
+    }
+    const unsuccessfulAncestor = graph.skipAfterFailureOf.find((dep) => {
+        const status = reportsByStepId.get(dep.id)?.status;
+        return status === "failed" || status === "cancelled";
+    });
+    if (unsuccessfulAncestor) {
+        return {
+            kind: "skip",
+            reason: "failed-dependency",
+            dependencyId: unsuccessfulAncestor.id,
+        };
+    }
+    const unmetDependency = graph.dependsOn.find((dep) => !isRequiredDependencyMet(reportsByStepId.get(dep.id)));
+    if (unmetDependency) {
+        return {
+            kind: "skip",
+            reason: "unmet-dependency",
+            dependencyId: unmetDependency.id,
+        };
+    }
+    if (dryRun && step.dryRun === "skip") {
+        return { kind: "skip", reason: "dry-run" };
+    }
+    return { kind: "run" };
+}
+//# sourceMappingURL=pipeline-disposition.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"pipeline-disposition.js","sourceRoot":"","sources":["../../src/core/pipeline-disposition.ts"],"names":[],"mappings":"AAQA,qFAAqF;AACrF,SAAS,uBAAuB,CAAC,MAAsC;IACrE,IAAI,CAAC,MAAM;QAAE,OAAO,KAAK,CAAC;IAC1B,IAAI,MAAM,CAAC,MAAM,KAAK,WAAW;QAAE,OAAO,IAAI,CAAC;IAC/C,OAAO,MAAM,CAAC,MAAM,KAAK,SAAS,IAAI,MAAM,CAAC,MAAM,KAAK,QAAQ,CAAC;AACnE,CAAC;AAmBD;;;;;GAKG;AACH,MAAM,UAAU,qBAAqB,CACnC,KAAqC;IAErC,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,EAAE,eAAe,EAAE,IAAI,EAAE,GAAG,KAAK,CAAC;IAEhE,IAAI,CAAC,OAAO,CAAC,QAAQ,EAAE,CAAC;QACtB,OAAO,EAAE,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,UAAU,EAAE,CAAC;IAC9C,CAAC;IAED,MAAM,oBAAoB,GAAG,KAAK,CAAC,kBAAkB,CAAC,IAAI,CAAC,CAAC,GAAG,EAAE,EAAE;QACjE,MAAM,MAAM,GAAG,eAAe,CAAC,GAAG,CAAC,GAAG,CAAC,EAAE,CAAC,EAAE,MAAM,CAAC;QACnD,OAAO,MAAM,KAAK,QAAQ,IAAI,MAAM,KAAK,WAAW,CAAC;IACvD,CAAC,CAAC,CAAC;IACH,IAAI,oBAAoB,EAAE,CAAC;QACzB,OAAO;YACL,IAAI,EAAE,MAAM;YACZ,MAAM,EAAE,mBAAmB;YAC3B,YAAY,EAAE,oBAAoB,CAAC,EAAE;SACtC,CAAC;IACJ,CAAC;IAED,MAAM,eAAe,GAAG,KAAK,CAAC,SAAS,CAAC,IAAI,CAC1C,CAAC,GAAG,EAAE,EAAE,CAAC,CAAC,uBAAuB,CAAC,eAAe,CAAC,GAAG,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC,CAC/D,CAAC;IACF,IAAI,eAAe,EAAE,CAAC;QACpB,OAAO;YACL,IAAI,EAAE,MAAM;YACZ,MAAM,EAAE,kBAAkB;YAC1B,YAAY,EAAE,eAAe,CAAC,EAAE;SACjC,CAAC;IACJ,CAAC;IAED,IAAI,MAAM,IAAI,IAAI,CAAC,MAAM,KAAK,MAAM,EAAE,CAAC;QACrC,OAAO,EAAE,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,SAAS,EAAE,CAAC;IAC7C,CAAC;IAED,OAAO,EAAE,IAAI,EAAE,KAAK,EAAE,CAAC;AACzB,CAAC","sourcesContent":["import type { CompiledStepGraph } from \"./pipeline-graph.js\";\nimport type { AnyStep } from \"./pipeline-steps.js\";\nimport type {\n  PipelinePlanStep,\n  PipelineStepReport,\n  PipelineStepSkipReason,\n} from \"./pipeline-types.js\";\n\n/** Required dependencies are met when completed, or intentionally policy-skipped. */\nfunction isRequiredDependencyMet(report: PipelineStepReport | undefined): boolean {\n  if (!report) return false;\n  if (report.status === \"completed\") return true;\n  return report.status === \"skipped\" && report.reason === \"policy\";\n}\n\ntype StepDispositionInput<TOptions extends object> = {\n  dryRun: boolean;\n  graph: CompiledStepGraph<TOptions>;\n  planned: PipelinePlanStep;\n  reportsByStepId: ReadonlyMap<string, PipelineStepReport>;\n  step: AnyStep<TOptions>;\n};\n\ntype StepDisposition =\n  | { kind: \"run\" }\n  | {\n      kind: \"skip\";\n      reason: PipelineStepSkipReason;\n      dependencyId?: string;\n      message?: string;\n    };\n\n/**\n * Single skip ladder for plan and live execution.\n * Policy skips stay outside: they run only after a step is scheduled.\n * Remainder copies plan `skipReason` for structural skips and marks planned-run\n * steps fail-fast or cancelled, so this ladder has no abort/fail-fast mode.\n */\nexport function decideStepDisposition<TOptions extends object>(\n  input: StepDispositionInput<TOptions>\n): StepDisposition {\n  const { dryRun, graph, planned, reportsByStepId, step } = input;\n\n  if (!planned.selected) {\n    return { kind: \"skip\", reason: \"filtered\" };\n  }\n\n  const unsuccessfulAncestor = graph.skipAfterFailureOf.find((dep) => {\n    const status = reportsByStepId.get(dep.id)?.status;\n    return status === \"failed\" || status === \"cancelled\";\n  });\n  if (unsuccessfulAncestor) {\n    return {\n      kind: \"skip\",\n      reason: \"failed-dependency\",\n      dependencyId: unsuccessfulAncestor.id,\n    };\n  }\n\n  const unmetDependency = graph.dependsOn.find(\n    (dep) => !isRequiredDependencyMet(reportsByStepId.get(dep.id))\n  );\n  if (unmetDependency) {\n    return {\n      kind: \"skip\",\n      reason: \"unmet-dependency\",\n      dependencyId: unmetDependency.id,\n    };\n  }\n\n  if (dryRun && step.dryRun === \"skip\") {\n    return { kind: \"skip\", reason: \"dry-run\" };\n  }\n\n  return { kind: \"run\" };\n}\n"]}

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

@@ -0,0 +1,8 @@
+import type { PipelineError, PipelineErrorCode, PipelineErrorKind, PipelineErrorPhase } from "./pipeline-types.js";
+export declare function pipelineDiagnostic(code: PipelineErrorCode, phase: PipelineErrorPhase, kind: PipelineErrorKind, message: string, fields?: Pick<PipelineError, "stepId">): PipelineError;
+/** Programmer error raised immediately when a pipeline graph is invalid. */
+export declare class PipelineDefinitionError extends Error {
+    readonly pipelineId: string;
+    readonly errors: readonly PipelineError[];
+    constructor(pipelineId: string, errors: readonly PipelineError[]);
+}

package/dist/core/pipeline-errors.js

@@ -0,0 +1,20 @@
+import { brandTubelessError } from "../utilities/tubeless-error.js";
+import { formatPipelineError } from "./pipeline-diagnostics.js";
+export function pipelineDiagnostic(code, phase, kind, message, fields = {}) {
+    return { code, kind, message, phase, ...fields };
+}
+/** Programmer error raised immediately when a pipeline graph is invalid. */
+export class PipelineDefinitionError extends Error {
+    pipelineId;
+    errors;
+    constructor(pipelineId, errors) {
+        super(errors.length > 0
+            ? `Invalid pipeline ${pipelineId}: ${errors.map((error) => formatPipelineError(error)).join("; ")}`
+            : `Invalid pipeline ${pipelineId}`);
+        this.pipelineId = pipelineId;
+        this.errors = errors;
+        this.name = "PipelineDefinitionError";
+        brandTubelessError(this, "pipeline-definition");
+    }
+}
+//# sourceMappingURL=pipeline-errors.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"pipeline-errors.js","sourceRoot":"","sources":["../../src/core/pipeline-errors.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,kBAAkB,EAAE,MAAM,gCAAgC,CAAC;AACpE,OAAO,EAAE,mBAAmB,EAAE,MAAM,2BAA2B,CAAC;AAQhE,MAAM,UAAU,kBAAkB,CAChC,IAAuB,EACvB,KAAyB,EACzB,IAAuB,EACvB,OAAe,EACf,MAAM,GAAkC,EAAE;IAE1C,OAAO,EAAE,IAAI,EAAE,IAAI,EAAE,OAAO,EAAE,KAAK,EAAE,GAAG,MAAM,EAAE,CAAC;AACnD,CAAC;AAED,4EAA4E;AAC5E,MAAM,OAAO,uBAAwB,SAAQ,KAAK;IAErC,UAAU;IACV,MAAM;IAFjB,YACW,UAAkB,EAClB,MAAgC;QAEzC,KAAK,CACH,MAAM,CAAC,MAAM,GAAG,CAAC;YACf,CAAC,CAAC,oBAAoB,UAAU,KAAK,MAAM,CAAC,GAAG,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,mBAAmB,CAAC,KAAK,CAAC,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE;YACnG,CAAC,CAAC,oBAAoB,UAAU,EAAE,CACrC,CAAC;0BAPO,UAAU;sBACV,MAAM;QAOf,IAAI,CAAC,IAAI,GAAG,yBAAyB,CAAC;QACtC,kBAAkB,CAAC,IAAI,EAAE,qBAAqB,CAAC,CAAC;IAClD,CAAC;CACF","sourcesContent":["import { brandTubelessError } from \"../utilities/tubeless-error.js\";\nimport { formatPipelineError } from \"./pipeline-diagnostics.js\";\nimport type {\n  PipelineError,\n  PipelineErrorCode,\n  PipelineErrorKind,\n  PipelineErrorPhase,\n} from \"./pipeline-types.js\";\n\nexport function pipelineDiagnostic(\n  code: PipelineErrorCode,\n  phase: PipelineErrorPhase,\n  kind: PipelineErrorKind,\n  message: string,\n  fields: Pick<PipelineError, \"stepId\"> = {}\n): PipelineError {\n  return { code, kind, message, phase, ...fields };\n}\n\n/** Programmer error raised immediately when a pipeline graph is invalid. */\nexport class PipelineDefinitionError extends Error {\n  constructor(\n    readonly pipelineId: string,\n    readonly errors: readonly PipelineError[]\n  ) {\n    super(\n      errors.length > 0\n        ? `Invalid pipeline ${pipelineId}: ${errors.map((error) => formatPipelineError(error)).join(\"; \")}`\n        : `Invalid pipeline ${pipelineId}`\n    );\n    this.name = \"PipelineDefinitionError\";\n    brandTubelessError(this, \"pipeline-definition\");\n  }\n}\n"]}

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

@@ -1,6 +1,8 @@
-import { type CompiledPipeline } from "./pipeline-plan.js";
+import type { CompiledPipeline } from "./pipeline-compiler.js";
 import type { AnyStep } from "./pipeline-steps.js";
 import type { InferSchemaOutput, PipelineContext, PipelinePlan, PipelineRun, PipelineRunControls, PipelineRuntime, StandardSchemaV1 } from "./pipeline-types.js";
+/** Observe an execution ID from an internal host without allowing it to be overridden. */
+export declare function observePipelineRunId<TContext extends object>(context: TContext, observer: (runId: string) => void): TContext;
 export declare class PipelineExecutionError extends Error {
     readonly result: PipelineRun<unknown>;
     constructor(result: PipelineRun<unknown>, message?: string);