tubeless 0.1.0

package/dist/pipeline.js

@@ -0,0 +1,1444 @@
+import { abortableSleep, isAbortError, throwIfAborted as throwIfSignalAborted } from "./abort.js";
+import { createPipelineLifecycleObserver } from "./lifecycle.js";
+import { createMappedChildRunner, createSingleChildRunner, PipelineChildError, } from "./child-execution.js";
+import { formatPipelineError } from "./pipeline-diagnostics.js";
+import { createPipelineTraceEmitter } from "./tracing-internal.js";
+/** Current persisted run-record schema version. */
+export const RUN_MODEL_VERSION = 1;
+export const PIPELINE_FINALIZE_STEP_ID = "__finalize__";
+const fallbackNow = () => Date.now();
+let nextRunSequence = 0;
+/** Create a dependency-free opaque ID suitable for a pipeline run record. */
+export function createRunId(pipelineId) {
+    nextRunSequence += 1;
+    const random = globalThis.crypto?.randomUUID?.();
+    return random
+        ? `${pipelineId}:${random}`
+        : `${pipelineId}:${Date.now().toString(36)}:${nextRunSequence.toString(36)}`;
+}
+function terminalRunStatus(errors) {
+    if (errors.length === 0)
+        return "completed";
+    return errors.length > 0 && errors.every(({ kind }) => kind === "cancellation")
+        ? "cancelled"
+        : "failed";
+}
+const fallbackSleep = (durationMs, signal) => abortableSleep(durationMs, signal, "Pipeline sleep");
+const PIPELINE_LOGGER_BASE = Symbol("pipelineLoggerBase");
+function basePipelineLogger(log) {
+    // SAFETY: `TracedPipelineLogger` only adds the optional symbol-keyed base
+    // property; reading it off any `PipelineLogger` is safe because the property
+    // is absent unless a tracing wrapper installed it.
+    return log[PIPELINE_LOGGER_BASE] ?? log;
+}
+export function defaultPipelineContext() {
+    return { cwd: process.cwd(), log: console, now: fallbackNow, sleep: fallbackSleep };
+}
+const originalPipelineErrors = new WeakMap();
+function defaultExecutionErrorMessage(result) {
+    const firstError = result.errors[0];
+    const disposition = result.errors.length > 0 && result.errors.every(({ kind }) => kind === "cancellation")
+        ? "cancelled"
+        : "failed";
+    return firstError
+        ? `Pipeline ${result.pipelineId} ${disposition}: ${formatPipelineError(firstError)}`
+        : `Pipeline ${result.pipelineId} ${disposition}`;
+}
+function firstOriginalPipelineError(errors) {
+    for (const error of errors) {
+        if (originalPipelineErrors.has(error))
+            return originalPipelineErrors.get(error);
+    }
+    return undefined;
+}
+export class PipelineExecutionError extends Error {
+    result;
+    constructor(result, message = defaultExecutionErrorMessage(result)) {
+        const cause = firstOriginalPipelineError(result.errors);
+        super(message, cause === undefined ? undefined : { cause });
+        this.result = result;
+        this.name = "PipelineExecutionError";
+    }
+}
+/** 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";
+    }
+}
+class PipelineBoundaryValidationError extends Error {
+    issues;
+    constructor(message, issues, cause) {
+        super(message, cause === undefined ? undefined : { cause });
+        this.issues = issues;
+        this.name = "PipelineBoundaryValidationError";
+    }
+}
+function normalizeValidationPath(path) {
+    if (!path || path.length === 0)
+        return undefined;
+    return path.map((segment) => {
+        const key = typeof segment === "object" && segment !== null ? segment.key : segment;
+        return typeof key === "number" || typeof key === "string" ? key : String(key);
+    });
+}
+function renderValidationIssue(issue) {
+    const location = issue.path?.map(String).join(".");
+    return location ? `${location}: ${issue.message}` : issue.message;
+}
+async function validateStandardSchema(schema, value, boundary) {
+    let result;
+    try {
+        result = await schema["~standard"].validate(value);
+    }
+    catch (error) {
+        throw new PipelineBoundaryValidationError(`${boundary} schema (${schema["~standard"].vendor}) threw while validating`, [], error);
+    }
+    if (result.issues) {
+        const issues = result.issues.map((issue) => {
+            const path = normalizeValidationPath(issue.path);
+            const normalized = { message: issue.message };
+            if (path)
+                normalized.path = path;
+            return normalized;
+        });
+        throw new PipelineBoundaryValidationError(`${boundary} validation failed: ${issues.map(renderValidationIssue).join("; ")}`, issues);
+    }
+    return result.value;
+}
+const PIPELINE_RUN_CONTROL_KEYS = ["continueOnError", "dryRun", "stepIds", "targets"];
+function isPipelineRunControlKey(property) {
+    return (typeof property === "string" &&
+        // SAFETY: `includes` membership over the literal tuple guarantees the cast
+        // target is exactly one of the declared run-control keys.
+        PIPELINE_RUN_CONTROL_KEYS.includes(property));
+}
+function createDomainOptionsTarget(options) {
+    const descriptors = Object.fromEntries(Reflect.ownKeys(options)
+        .filter((property) => !isPipelineRunControlKey(property))
+        .map((property) => {
+        const descriptor = Reflect.getOwnPropertyDescriptor(options, property);
+        return [property, { ...descriptor, configurable: true }];
+    }));
+    // SAFETY: `Object.create` returns the same prototype shape as `options` with
+    // only its own enumerable descriptors re-applied, so it remains assignable
+    // to the caller's `object` contract.
+    return Object.create(Object.getPrototypeOf(options), descriptors);
+}
+function createDomainOptionsView(options) {
+    const target = createDomainOptionsTarget(options);
+    const boundMethods = new WeakMap();
+    // SAFETY: the Proxy wraps the domain-options target and forwards to the
+    // original options, so its surface is assignable to `TOptions`.
+    return new Proxy(target, {
+        get(_target, property) {
+            if (isPipelineRunControlKey(property))
+                return undefined;
+            // SAFETY: `property` is a non-control key, so indexing the options object
+            // with it reads a genuine domain property; the cast is the only way to
+            // express dynamic-key access on a generic options type.
+            const value = options[property];
+            if (typeof value !== "function")
+                return value;
+            const cached = boundMethods.get(value);
+            if (cached)
+                return cached;
+            const bound = value.bind(options);
+            boundMethods.set(value, bound);
+            return bound;
+        },
+        has(_target, property) {
+            return isPipelineRunControlKey(property) ? false : Reflect.has(options, property);
+        },
+        set(_target, property, value) {
+            if (isPipelineRunControlKey(property))
+                return true;
+            return Reflect.set(options, property, value, options);
+        },
+        // SAFETY: the Proxy target is the domain-options object, so it is
+        // assignable to the caller's `TOptions` contract.
+    });
+}
+function splitPipelineRunOptions(options) {
+    const controls = {};
+    let hasControls = false;
+    for (const key of PIPELINE_RUN_CONTROL_KEYS) {
+        if (!Object.prototype.hasOwnProperty.call(options, key))
+            continue;
+        hasControls = true;
+        Object.assign(controls, { [key]: options[key] });
+    }
+    return {
+        controls,
+        domainOptions: hasControls ? createDomainOptionsView(options) : options,
+    };
+}
+const STEP_OPTIONS_SCHEMA = Symbol("tubeless.stepOptionsSchema");
+const STEP_NESTED_PIPELINE = Symbol("tubeless.stepNestedPipeline");
+export function createSteps(optionsSchema) {
+    return createStepFactory(optionsSchema);
+}
+function createStepFactory(optionsSchema) {
+    // Runtime construction is deliberately simple; the public factory owns the
+    // distinction between ordinary and explicitly skippable constructors.
+    const buildStep = (id, definition) => {
+        // SAFETY: `definition` carries the step's own fields; spreading it onto the
+        // id-bearing shell yields a value whose shape matches `AnyStep<TOptions>`.
+        const built = { id, ...definition };
+        if (optionsSchema) {
+            Object.defineProperty(built, STEP_OPTIONS_SCHEMA, { value: optionsSchema });
+        }
+        return built;
+    };
+    // SAFETY: the closure's parameter and return shapes match the
+    // `fromPipeline` constructor signature it is assigned to.
+    const fromPipeline = ((id, config) => {
+        const definition = {
+            [STEP_NESTED_PIPELINE]: {
+                mode: "single",
+                pipelineId: config.pipeline.id,
+                stepIds: config.pipeline.stepIds,
+            },
+            dependsOn: config.dependsOn,
+            optionalDependsOn: config.optionalDependsOn,
+            skipAfterFailureOf: config.skipAfterFailureOf,
+            name: config.name,
+            description: config.description,
+            dryRun: config.dryRun,
+            // SAFETY: the config carries `pipeline` and `mapResult`; the runner
+            // derives `mapOptions` from the same fields, so the config is a valid
+            // single-child execution config at runtime.
+            run: createSingleChildRunner(config, {
+                createExecutionError: (result, message) => new PipelineExecutionError(result, message),
+                isCancellation: (error, childContext) => isPipelineCancellation(error, childContext),
+            }),
+        };
+        if ("skip" in config && config.skip !== undefined) {
+            const skip = config.skip;
+            // SAFETY: the skip predicate is invoked with the step's own inputs and
+            // returns a step-skip decision; the casts only align the generic
+            // predicate signature with the concrete step context.
+            return buildStep(id, {
+                ...definition,
+                skip: (inputs, context) => skip(inputs, context),
+            });
+        }
+        return buildStep(id, definition);
+    });
+    // SAFETY: the closure's parameter and return shapes match the
+    // `forEachPipeline` constructor signature it is assigned to.
+    const forEachPipeline = ((id, config) => buildStep(id, {
+        [STEP_NESTED_PIPELINE]: {
+            mode: "for-each",
+            pipelineId: config.pipeline.id,
+            stepIds: config.pipeline.stepIds,
+        },
+        dependsOn: config.dependsOn,
+        optionalDependsOn: config.optionalDependsOn,
+        skipAfterFailureOf: config.skipAfterFailureOf,
+        name: config.name,
+        description: config.description,
+        dryRun: config.dryRun,
+        // SAFETY: the config carries `pipeline`, `items`, `key`, and `mapResult`;
+        // the runner derives the rest from those fields, so the config is a valid
+        // mapped-child execution config at runtime.
+        run: createMappedChildRunner(config, {
+            createExecutionError: (result, message) => new PipelineExecutionError(result, message),
+            isCancellation: (error, childContext) => isPipelineCancellation(error, childContext),
+        }),
+    }));
+    // SAFETY: `buildStep` is a callable; attaching the constructor properties
+    // yields exactly the `StepFactory` surface (call + skippable + fromPipeline +
+    // forEachPipeline), so the single assertion is sound.
+    // SAFETY: `buildStep` is a callable; attaching the constructor properties
+    // yields exactly the `StepFactory` surface (call + skippable + fromPipeline +
+    // forEachPipeline), so the single assertion is sound.
+    const factory = Object.assign(buildStep, {
+        skippable: buildStep,
+        fromPipeline,
+        forEachPipeline,
+    });
+    // SAFETY: `fromPipeline` is the same callable as `factory.fromPipeline`; it
+    // carries the skippable variant, so the assignment is sound.
+    factory.fromPipeline.skippable = fromPipeline;
+    return factory;
+}
+const REQUIRED_FINALIZER_OUTPUTS = Symbol("tubeless.requiredFinalizerOutputs");
+/**
+ * Build a finalizer that only runs when every listed step published an output.
+ * Presence is checked by output slot, so a successfully published `undefined`
+ * remains distinct from a structural skip or failure.
+ */
+export function requireOutputs(requiredSteps, finalize) {
+    const uniqueRequiredSteps = [...new Set(requiredSteps)];
+    const requiredFinalizer = (outputs, context) => {
+        const missingStepIds = uniqueRequiredSteps
+            .filter((step) => !Object.prototype.hasOwnProperty.call(outputs, step.id))
+            .map((step) => step.id);
+        if (missingStepIds.length > 0) {
+            throw new Error(`Required pipeline outputs missing: ${missingStepIds.join(", ")}`);
+        }
+        // SAFETY: every required step id was verified present above, so the partial
+        // outputs contain all required keys and are a complete required-outputs map.
+        return finalize(outputs, context);
+    };
+    Object.defineProperty(requiredFinalizer, REQUIRED_FINALIZER_OUTPUTS, {
+        value: uniqueRequiredSteps,
+    });
+    return requiredFinalizer;
+}
+function duplicateValues(values) {
+    const seen = new Set();
+    const duplicates = new Set();
+    for (const value of values) {
+        if (seen.has(value)) {
+            duplicates.add(value);
+        }
+        seen.add(value);
+    }
+    return [...duplicates].sort((left, right) => left.localeCompare(right));
+}
+function pipelineDiagnostic(code, phase, kind, message, fields = {}) {
+    return { code, kind, message, phase, ...fields };
+}
+const MAX_PIPELINE_CAUSE_DEPTH = 8;
+function readErrorField(value, field) {
+    try {
+        // SAFETY: any object may be probed for an optional string-keyed field; a
+        // getter that throws is caught below, so the cast only enables the lookup.
+        return value[field];
+    }
+    catch {
+        return undefined;
+    }
+}
+function safeErrorMessage(value) {
+    try {
+        return String(value);
+    }
+    catch {
+        return "Unknown thrown value";
+    }
+}
+function normalizePipelineCause(value, seen, depth = 0) {
+    if (depth >= MAX_PIPELINE_CAUSE_DEPTH) {
+        return { message: "Cause chain truncated" };
+    }
+    if (typeof value !== "object" || value === null) {
+        return { message: safeErrorMessage(value) };
+    }
+    if (seen.has(value)) {
+        return { message: "Circular cause" };
+    }
+    seen.add(value);
+    const message = readErrorField(value, "message");
+    const name = readErrorField(value, "name");
+    const sourceCode = readErrorField(value, "code");
+    const nested = readErrorField(value, "cause");
+    const cause = {
+        message: typeof message === "string" ? message : safeErrorMessage(value),
+    };
+    if (typeof name === "string")
+        cause.name = name;
+    if (typeof sourceCode === "string")
+        cause.sourceCode = sourceCode;
+    if (nested !== undefined)
+        cause.cause = normalizePipelineCause(nested, seen, depth + 1);
+    return cause;
+}
+function normalizedNestedCause(error) {
+    if (typeof error !== "object" || error === null)
+        return undefined;
+    const cause = readErrorField(error, "cause");
+    if (cause === undefined)
+        return undefined;
+    const seen = new WeakSet();
+    seen.add(error);
+    return normalizePipelineCause(cause, seen);
+}
+function toPipelineError(error, classification) {
+    const sourceCode = typeof error === "object" && error !== null ? readErrorField(error, "code") : undefined;
+    const cause = normalizedNestedCause(error);
+    const pipelineError = {
+        ...classification,
+        message: error instanceof Error ? error.message : safeErrorMessage(error),
+    };
+    if (error instanceof Error && error.stack)
+        pipelineError.stack = error.stack;
+    if (typeof sourceCode === "string")
+        pipelineError.sourceCode = sourceCode;
+    if (cause)
+        pipelineError.cause = cause;
+    if (error instanceof PipelineBoundaryValidationError)
+        pipelineError.issues = error.issues;
+    originalPipelineErrors.set(pipelineError, error);
+    return pipelineError;
+}
+function isPipelineCancellation(error, runtime) {
+    if (isAbortError(error))
+        return true;
+    if (runtime.signal?.aborted === true && error === runtime.signal.reason)
+        return true;
+    if (error instanceof PipelineChildError)
+        return error.cancelled;
+    return error instanceof PipelineExecutionError && isCancelledResult(error.result);
+}
+function isCancelledResult(result) {
+    return result.status === "cancelled";
+}
+function errorRunResult(runtime, pipelineId, dryRun, startedAt, errors, identity) {
+    const finishedAtMs = runtime.now();
+    const result = {
+        pipelineId,
+        dryRun,
+        errors,
+        finalized: false,
+        finishedAtMs,
+        runId: identity.runId,
+        startedAtMs: startedAt,
+        status: terminalRunStatus(errors),
+        steps: [],
+        version: RUN_MODEL_VERSION,
+    };
+    if (identity.parentRunId)
+        result.parentRunId = identity.parentRunId;
+    return result;
+}
+function resolvePipelineRuntime(context = {}) {
+    const defaults = defaultPipelineContext();
+    return {
+        ...defaults,
+        ...context,
+        cwd: context.cwd ?? defaults.cwd,
+        log: context.log ?? defaults.log,
+        now: context.now ?? defaults.now ?? fallbackNow,
+        sleep: context.sleep ?? defaults.sleep ?? fallbackSleep,
+    };
+}
+function throwIfAborted(runtime) {
+    throwIfSignalAborted(runtime.signal, "Pipeline run");
+}
+function recordSkip(step, stepId, reports, reportsByStepId, reason, message, dependencyId, attemptId, startedAtMs, finishedAtMs) {
+    const report = {
+        id: stepId,
+        name: step.name,
+        description: step.description,
+        finishedAtMs,
+        reason,
+        status: "skipped",
+    };
+    if (attemptId)
+        report.attemptId = attemptId;
+    if (startedAtMs !== undefined)
+        report.startedAtMs = startedAtMs;
+    if (dependencyId)
+        report.dependencyId = dependencyId;
+    if (message)
+        report.message = message;
+    reports.push(report);
+    reportsByStepId.set(stepId, report);
+    return report;
+}
+function normalizeStepSkipDecision(decision) {
+    if (decision == null || decision === false)
+        return null;
+    if (typeof decision === "string") {
+        const reason = decision.trim();
+        return reason.length > 0 ? { reason } : null;
+    }
+    if (typeof decision === "object" && typeof decision.reason === "string") {
+        const reason = decision.reason.trim();
+        if (reason.length === 0)
+            return null;
+        return { reason, value: decision.value };
+    }
+    return null;
+}
+/** Required dependencies are met when completed, or intentionally policy-skipped. */
+function isRequiredDependencyMet(report) {
+    if (!report)
+        return false;
+    if (report.status === "complete")
+        return true;
+    return report.status === "skipped" && report.reason === "policy";
+}
+/**
+ * Single skip ladder for plan, live execution, and fail-fast/cancel remainder.
+ * Policy skips stay outside: they run only after a step is scheduled.
+ *
+ * When `stoppedAfter` is set, live failed/cancelled deps and fail-fast remainder
+ * skips do not reclassify the step as unmet-dependency — those become fail-fast
+ * or cancelled so the whole remainder keeps today's abort attribution. Structural
+ * skip reports (filtered / unmet-dependency / dry-run / failed-dependency) still
+ * win so plan-time chains survive remainder recording.
+ */
+function decideStepDisposition(input) {
+    const { dryRun, planned, reportsByStepId, step, stoppedAfter } = input;
+    if (!planned.selected) {
+        return { kind: "skip", reason: "filtered" };
+    }
+    if (!stoppedAfter) {
+        const unsuccessfulAncestor = (step.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 = (step.dependsOn ?? []).find((dep) => {
+        const report = reportsByStepId.get(dep.id);
+        if (stoppedAfter) {
+            // Only structural skips propagate under abort remainder. Failed/cancelled
+            // deps and fail-fast skips fall through so the step is fail-fast/cancelled.
+            return (report?.status === "skipped" && report.reason !== "policy" && report.reason !== "fail-fast");
+        }
+        return !isRequiredDependencyMet(report);
+    });
+    if (unmetDependency) {
+        return {
+            kind: "skip",
+            reason: "unmet-dependency",
+            dependencyId: unmetDependency.id,
+        };
+    }
+    if (dryRun && skipsInDryRun(step)) {
+        return { kind: "skip", reason: "dry-run" };
+    }
+    if (stoppedAfter) {
+        if (stoppedAfter.cancelled) {
+            return { kind: "cancelled" };
+        }
+        const failedStepId = stoppedAfter.stepId;
+        const disposition = {
+            kind: "skip",
+            reason: "fail-fast",
+            message: failedStepId
+                ? `Not run because fail-fast stopped after ${failedStepId} failed.`
+                : "Not run because the pipeline was aborted before this step started.",
+        };
+        if (failedStepId)
+            disposition.dependencyId = failedStepId;
+        return disposition;
+    }
+    return { kind: "run" };
+}
+/**
+ * Deduplicated by object identity: the same dependency commonly appears in more than one
+ * of these arrays (e.g. a step that's both `optionalDependsOn` and `skipAfterFailureOf` the
+ * same upstream step). Without dedup, `topologicalSort`'s in-degree count would no longer
+ * equal the number of distinct prerequisites — harmless there since the inflated count and
+ * the duplicated `dependentsOf` entries cancel out, but confusing to read and a latent trap
+ * for future callers of this helper that assume it returns distinct edges.
+ */
+function stepEdges(step) {
+    return [
+        ...new Set([
+            ...(step.dependsOn ?? []),
+            ...(step.optionalDependsOn ?? []),
+            ...(step.skipAfterFailureOf ?? []),
+        ]),
+    ];
+}
+/** Required data and failure-gate closure for dependency-aware targets. */
+function targetClosure(targets) {
+    const selected = new Set();
+    const include = (step) => {
+        if (selected.has(step))
+            return;
+        selected.add(step);
+        for (const prerequisite of [...(step.dependsOn ?? []), ...(step.skipAfterFailureOf ?? [])]) {
+            include(prerequisite);
+        }
+    };
+    for (const target of targets)
+        include(target);
+    return selected;
+}
+/**
+ * Orders `steps` so every dependency runs before its dependents, using each step's
+ * original array position to break ties. For an array that's already in valid dependency
+ * order (true of every hand-ordered pipeline today) this provably reproduces that same
+ * order — each step becomes eligible (in-degree 0) at the same point it would've been
+ * reached by a plain declaration-order walk. What it adds is tolerance for a `steps` array
+ * that ISN'T already ordered, and a real error instead of silent misbehavior on a cycle.
+ * Returns null if the graph has a cycle (shouldn't happen given `const`-reference
+ * construction, but the executor should never spin or drop steps if it somehow does).
+ */
+function topologicalSort(steps) {
+    const indexById = new Map(steps.map((step, index) => [step.id, index]));
+    const remainingInDegree = new Map(steps.map((step) => [step.id, stepEdges(step).length]));
+    const dependentsOf = new Map();
+    for (const step of steps) {
+        for (const dep of stepEdges(step)) {
+            const dependents = dependentsOf.get(dep.id) ?? [];
+            dependents.push(step.id);
+            dependentsOf.set(dep.id, dependents);
+        }
+    }
+    const ready = steps.filter((step) => remainingInDegree.get(step.id) === 0).map((step) => step.id);
+    const orderedIds = [];
+    while (ready.length > 0) {
+        ready.sort((left, right) => (indexById.get(left) ?? 0) - (indexById.get(right) ?? 0));
+        const nextId = ready.shift();
+        if (nextId === undefined) {
+            break;
+        }
+        orderedIds.push(nextId);
+        for (const dependentId of dependentsOf.get(nextId) ?? []) {
+            const remaining = (remainingInDegree.get(dependentId) ?? 0) - 1;
+            remainingInDegree.set(dependentId, remaining);
+            if (remaining === 0) {
+                ready.push(dependentId);
+            }
+        }
+    }
+    if (orderedIds.length !== steps.length) {
+        return null;
+    }
+    const stepsById = new Map(steps.map((step) => [step.id, step]));
+    // SAFETY: every id in `orderedIds` was produced by walking the same `steps`
+    // array, so the map lookup always finds the matching `AnyStep<TOptions>`.
+    return orderedIds.map((id) => stepsById.get(id));
+}
+function escapeMermaidLabel(value) {
+    return value
+        .replace(/\r\n?|\n/g, " ")
+        .replace(/[\u0000-\u001f\u007f-\u009f]/g, " ")
+        .replace(/#/g, "#35;")
+        .replace(/&/g, "#38;")
+        .replace(/"/g, "#quot;")
+        .replace(/</g, "#60;")
+        .replace(/>/g, "#62;");
+}
+function renderPipelineMermaid(steps, options) {
+    const direction = options.direction ?? "TD";
+    if (!["BT", "LR", "RL", "TB", "TD"].includes(direction)) {
+        throw new Error(`Invalid Mermaid flowchart direction: ${direction}`);
+    }
+    const nodeIdByStep = new Map(steps.map((step, index) => [step, `step${index}`]));
+    const lines = [`flowchart ${direction}`];
+    for (const step of steps) {
+        const nodeId = nodeIdByStep.get(step);
+        const displayName = step.name ?? step.id;
+        const label = options.includeDescriptions && step.description
+            ? `${displayName} — ${step.description}`
+            : displayName;
+        lines.push(`  ${nodeId}["${escapeMermaidLabel(label)}"]`);
+    }
+    const edgeLines = [];
+    for (const step of steps) {
+        const targetId = nodeIdByStep.get(step);
+        const required = new Set(step.dependsOn ?? []);
+        const optional = new Set(step.optionalDependsOn ?? []);
+        const failureGates = new Set(step.skipAfterFailureOf ?? []);
+        for (const dependency of stepEdges(step)) {
+            const sourceId = nodeIdByStep.get(dependency);
+            if (required.has(dependency)) {
+                edgeLines.push(`  ${sourceId} --> ${targetId}`);
+                continue;
+            }
+            if (optional.has(dependency) && failureGates.has(dependency)) {
+                edgeLines.push(`  ${sourceId} -. optional input + failure gate .-> ${targetId}`);
+                continue;
+            }
+            if (optional.has(dependency)) {
+                edgeLines.push(`  ${sourceId} -. optional input .-> ${targetId}`);
+                continue;
+            }
+            edgeLines.push(`  ${sourceId} -. failure gate .-> ${targetId}`);
+        }
+    }
+    if (edgeLines.length > 0) {
+        lines.push("", ...edgeLines);
+    }
+    return `${lines.join("\n")}\n`;
+}
+function stepToPlanStep(step, selected, skipReason, selectionReasons = [{ kind: "all" }]) {
+    const planStep = {
+        dependencies: (step.dependsOn ?? []).map((dep) => dep.id),
+        description: step.description,
+        dryRun: step.dryRun === "skip" ? "skip" : step.dryRun !== undefined ? "custom" : "run",
+        id: step.id,
+        name: step.name,
+        optionalDependencies: (step.optionalDependsOn ?? []).map((dep) => dep.id),
+        runtimeSkipPossible: step.skip !== undefined,
+        selected,
+        selectionReasons,
+        skipAfterFailureOf: (step.skipAfterFailureOf ?? []).map((dep) => dep.id),
+        skipReason,
+    };
+    if (step[STEP_NESTED_PIPELINE]) {
+        planStep.nestedPipeline = {
+            ...step[STEP_NESTED_PIPELINE],
+            stepIds: [...step[STEP_NESTED_PIPELINE].stepIds],
+        };
+    }
+    return planStep;
+}
+function addSelectionReason(reasonsByStepId, stepId, reason) {
+    const reasons = reasonsByStepId.get(stepId) ?? [];
+    const reasonKey = JSON.stringify(reason);
+    if (!reasons.some((candidate) => JSON.stringify(candidate) === reasonKey)) {
+        reasons.push(reason);
+        reasonsByStepId.set(stepId, reasons);
+    }
+}
+function targetSelectionReasons(targets) {
+    const reasonsByStepId = new Map();
+    for (const target of targets) {
+        addSelectionReason(reasonsByStepId, target.id, { kind: "target", targetId: target.id });
+        const expanded = new Set();
+        const includePrerequisites = (step) => {
+            if (expanded.has(step))
+                return;
+            expanded.add(step);
+            for (const dependency of step.dependsOn ?? []) {
+                addSelectionReason(reasonsByStepId, dependency.id, {
+                    dependentId: step.id,
+                    kind: "required-dependency",
+                    targetId: target.id,
+                });
+                includePrerequisites(dependency);
+            }
+            for (const dependency of step.skipAfterFailureOf ?? []) {
+                addSelectionReason(reasonsByStepId, dependency.id, {
+                    dependentId: step.id,
+                    kind: "failure-gate",
+                    targetId: target.id,
+                });
+                includePrerequisites(dependency);
+            }
+            for (const dependency of step.optionalDependsOn ?? []) {
+                addSelectionReason(reasonsByStepId, dependency.id, {
+                    dependentId: step.id,
+                    kind: "optional-only",
+                    targetId: target.id,
+                });
+            }
+        };
+        includePrerequisites(target);
+    }
+    return reasonsByStepId;
+}
+function selectsStep(reason) {
+    return !["not-selected", "optional-only", "outside-target-closure"].includes(reason.kind);
+}
+function skipsInDryRun(step) {
+    return step.dryRun === "skip";
+}
+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(", ")}`));
+    }
+    // SAFETY: `requireOutputs` stamps the required step ids onto the finalizer
+    // function under `REQUIRED_FINALIZER_OUTPUTS`; the intersection only widens
+    // the function type to expose that optional property.
+    const requiredFinalizerSteps = definition.finalize[REQUIRED_FINALIZER_OUTPUTS];
+    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;
+}
+function buildPipelinePlan(definition, controls) {
+    const dryRun = controls.dryRun === true;
+    const steps = definition.steps;
+    const stepIds = steps.map((step) => step.id);
+    const errors = validatePipelineDefinition(definition);
+    const knownStepIds = new Set(stepIds);
+    const declaredTargetIds = new Set((definition.targets ?? []).map((target) => target.id));
+    const requestedStepIds = controls.stepIds ?? [];
+    const requestedTargets = controls.targets ?? [];
+    if (controls.stepIds !== undefined && controls.targets !== undefined) {
+        errors.push(pipelineDiagnostic("TUBELESS_PLANNING_SELECTION_CONFLICT", "planning", "selection", `Pipeline ${definition.id} cannot combine exact stepIds filtering with dependency-aware targets`));
+    }
+    if (controls.stepIds !== undefined && controls.stepIds.length === 0) {
+        errors.push(pipelineDiagnostic("TUBELESS_PLANNING_STEP_SELECTION_EMPTY", "planning", "selection", `Pipeline ${definition.id} received an empty stepIds array; omit stepIds to run every step, or pass at least one step id`));
+    }
+    if (controls.targets !== undefined && controls.targets.length === 0) {
+        errors.push(pipelineDiagnostic("TUBELESS_PLANNING_TARGET_SELECTION_EMPTY", "planning", "selection", `Pipeline ${definition.id} received an empty targets array; omit targets to run every step, or pass at least one target step id`));
+    }
+    const duplicateRequestedStepIds = duplicateValues(requestedStepIds);
+    if (duplicateRequestedStepIds.length > 0) {
+        errors.push(pipelineDiagnostic("TUBELESS_PLANNING_STEP_SELECTION_DUPLICATE", "planning", "selection", `Pipeline ${definition.id} requested duplicate step ids: ${duplicateRequestedStepIds.join(", ")}`));
+    }
+    const unknownRequestedStepIds = requestedStepIds.filter((stepId) => !knownStepIds.has(stepId));
+    if (unknownRequestedStepIds.length > 0) {
+        errors.push(pipelineDiagnostic("TUBELESS_PLANNING_STEP_UNKNOWN", "planning", "selection", `Pipeline ${definition.id} requested unknown step ids: ${unknownRequestedStepIds.join(", ")}`));
+    }
+    const duplicateTargets = duplicateValues(requestedTargets);
+    if (duplicateTargets.length > 0) {
+        errors.push(pipelineDiagnostic("TUBELESS_PLANNING_TARGET_SELECTION_DUPLICATE", "planning", "selection", `Pipeline ${definition.id} requested duplicate targets: ${duplicateTargets.join(", ")}`));
+    }
+    const unknownTargets = requestedTargets.filter((stepId) => !knownStepIds.has(stepId));
+    if (unknownTargets.length > 0) {
+        errors.push(pipelineDiagnostic("TUBELESS_PLANNING_TARGET_UNKNOWN", "planning", "selection", `Pipeline ${definition.id} requested unknown targets: ${unknownTargets.join(", ")}`));
+    }
+    const undeclaredTargets = requestedTargets.filter((stepId) => knownStepIds.has(stepId) && !declaredTargetIds.has(stepId));
+    if (undeclaredTargets.length > 0) {
+        errors.push(pipelineDiagnostic("TUBELESS_PLANNING_TARGET_UNDECLARED", "planning", "selection", `Pipeline ${definition.id} requested undeclared targets: ${undeclaredTargets.join(", ")}`));
+    }
+    const orderedSteps = errors.length === 0 ? topologicalSort(steps) : null;
+    if (errors.length > 0) {
+        return {
+            dryRun,
+            errors,
+            ok: false,
+            pipelineId: definition.id,
+            steps: [],
+        };
+    }
+    let selectionReasonsByStepId;
+    if (controls.stepIds !== undefined) {
+        const selectedIds = new Set(controls.stepIds);
+        selectionReasonsByStepId = new Map(steps.map((step) => [
+            step.id,
+            selectedIds.has(step.id)
+                ? [{ kind: "exact" }]
+                : [{ kind: "not-selected" }],
+        ]));
+    }
+    else if (controls.targets !== undefined) {
+        const stepsById = new Map(steps.map((step) => [step.id, step]));
+        const selectedTargets = controls.targets.map((target) => stepsById.get(target));
+        selectionReasonsByStepId = targetSelectionReasons(selectedTargets);
+        for (const step of steps) {
+            const reasons = selectionReasonsByStepId.get(step.id) ?? [];
+            const selected = reasons.some(selectsStep);
+            selectionReasonsByStepId.set(step.id, selected
+                ? reasons.filter(selectsStep)
+                : reasons.length > 0
+                    ? reasons
+                    : [{ kind: "outside-target-closure" }]);
+        }
+    }
+    else {
+        selectionReasonsByStepId = new Map(steps.map((step) => [step.id, [{ kind: "all" }]]));
+    }
+    const planSteps = [];
+    // Accumulated planned skip/complete reports so later steps see the same
+    // unmet-dependency chain as today's skipReason walk (not one empty map).
+    const plannedReportsByStepId = new Map();
+    for (const step of orderedSteps ?? steps) {
+        const selectionReasons = selectionReasonsByStepId.get(step.id);
+        const selected = selectionReasons.some(selectsStep);
+        const planned = stepToPlanStep(step, selected, undefined, selectionReasons);
+        const disposition = decideStepDisposition({
+            dryRun,
+            planned,
+            reportsByStepId: plannedReportsByStepId,
+            step,
+        });
+        const skipReason = disposition.kind === "skip" ? disposition.reason : undefined;
+        const planStep = stepToPlanStep(step, selected, skipReason, selectionReasons);
+        planSteps.push(planStep);
+        if (disposition.kind === "skip") {
+            const report = {
+                id: step.id,
+                name: step.name,
+                description: step.description,
+                finishedAtMs: 0,
+                reason: disposition.reason,
+                status: "skipped",
+            };
+            if (disposition.dependencyId)
+                report.dependencyId = disposition.dependencyId;
+            if (disposition.message)
+                report.message = disposition.message;
+            plannedReportsByStepId.set(step.id, report);
+        }
+        else {
+            // Synthetic complete so isRequiredDependencyMet treats will-run deps as met.
+            plannedReportsByStepId.set(step.id, {
+                attemptId: "",
+                id: step.id,
+                name: step.name,
+                description: step.description,
+                finishedAtMs: 0,
+                startedAtMs: 0,
+                status: "complete",
+            });
+        }
+    }
+    return {
+        dryRun,
+        errors,
+        ok: errors.length === 0,
+        pipelineId: definition.id,
+        steps: planSteps,
+    };
+}
+function planStepById(plan) {
+    return new Map(plan.steps.map((step) => [step.id, step]));
+}
+export function definePipeline(definition) {
+    const definitionErrors = validatePipelineDefinition(definition);
+    if (definitionErrors.length > 0) {
+        throw new PipelineDefinitionError(definition.id, definitionErrors);
+    }
+    // SAFETY: each step id is a string key of `TSteps`, so the frozen id list is
+    // exactly the declared `TStepId` union.
+    const stepIds = Object.freeze(definition.steps.map((step) => step.id));
+    // SAFETY: each target id is a string key of `TTargets`, so the frozen list is
+    // exactly the declared `TTargetId` union.
+    const targetIds = Object.freeze((definition.targets ?? []).map((step) => step.id));
+    const optionsSchema = definition.steps[0]?.[STEP_OPTIONS_SCHEMA];
+    // SAFETY: every step in `definition.steps` is an `AnyStep<TOptions>`; the
+    // cast only restores the generic type parameter that the tuple lost.
+    const orderedDefinitionSteps = topologicalSort(definition.steps);
+    function plan(controls = {}) {
+        return buildPipelinePlan(definition, controls);
+    }
+    function toMermaid(options = {}) {
+        return renderPipelineMermaid(orderedDefinitionSteps, options);
+    }
+    async function run(options, context = defaultPipelineContext()) {
+        const { controls, domainOptions } = splitPipelineRunOptions(options);
+        // SAFETY: `domainOptions` is the user-supplied options object; if a schema
+        // is present it is re-validated below before assignment to `pipelineOptions`.
+        let pipelineOptions = domainOptions;
+        const runtime = resolvePipelineRuntime(context);
+        const startedAt = runtime.now();
+        const runId = runtime.runId ?? createRunId(definition.id);
+        const parentRunId = runtime.parentRunId;
+        const identity = { runId };
+        if (parentRunId)
+            identity.parentRunId = parentRunId;
+        const dryRun = controls.dryRun === true;
+        const trace = createPipelineTraceEmitter(definition.id, runtime.tracing, basePipelineLogger(runtime.log), {
+            ...identity,
+            itemKey: runtime.tracing?.itemKey,
+        }, runtime.now);
+        const lifecycle = createPipelineLifecycleObserver(definition.id, runtime, trace);
+        const tracedLogger = (stepId, attemptId) => {
+            if (!trace)
+                return runtime.log;
+            const base = basePipelineLogger(runtime.log);
+            const log = {
+                error: (message, ...params) => {
+                    lifecycle.log("error", message, params, stepId, attemptId);
+                    base.error(message, ...params);
+                },
+                log: (message, ...params) => {
+                    lifecycle.log("log", message, params, stepId, attemptId);
+                    base.log(message, ...params);
+                },
+                warn: (message, ...params) => {
+                    lifecycle.log("warn", message, params, stepId, attemptId);
+                    base.warn(message, ...params);
+                },
+            };
+            log[PIPELINE_LOGGER_BASE] = base;
+            return log;
+        };
+        let nextAttemptSequence = 0;
+        const beginAttempt = (stepId, startedAtMs = runtime.now()) => ({
+            attemptId: `${runId}:attempt:${(nextAttemptSequence += 1).toString(36)}`,
+            startedAtMs,
+            stepId,
+        });
+        const currentStepStatuses = new Map();
+        const publishStepStatus = (event, traceStatus = true) => {
+            const previous = currentStepStatuses.get(event.step.id);
+            const valid = (previous === undefined && event.status === "planned") ||
+                (previous === "planned" &&
+                    (event.status === "running" ||
+                        event.status === "skipped" ||
+                        event.status === "cancelled")) ||
+                (previous === "running" &&
+                    (event.status === "running" ||
+                        event.status === "complete" ||
+                        event.status === "skipped" ||
+                        event.status === "cancelled" ||
+                        event.status === "failed"));
+            if (!valid) {
+                throw new Error(`Invalid step status transition for ${event.step.id}: ${previous ?? "unobserved"} -> ${event.status}`);
+            }
+            currentStepStatuses.set(event.step.id, event.status);
+            lifecycle.stepStatus(event, traceStatus);
+        };
+        const publishStepReport = (step, report) => {
+            switch (report.status) {
+                case "cancelled":
+                case "failed":
+                case "skipped":
+                case "complete":
+                    publishStepStatus({ ...report, pipelineId: definition.id, step });
+            }
+        };
+        const runPlan = plan(controls);
+        const plannedSteps = planStepById(runPlan);
+        lifecycle.pipelineStart(runPlan, targetIds);
+        if (!runPlan.ok) {
+            const result = errorRunResult(runtime, definition.id, dryRun, startedAt, runPlan.errors, identity);
+            lifecycle.pipelineComplete(result);
+            await lifecycle.flush();
+            return result;
+        }
+        if (optionsSchema) {
+            try {
+                const validated = await validateStandardSchema(optionsSchema, domainOptions, `Pipeline ${definition.id} options`);
+                if (typeof validated !== "object" || validated === null || Array.isArray(validated)) {
+                    throw new PipelineBoundaryValidationError(`Pipeline ${definition.id} options schema returned a non-object value`, [{ message: "Expected the validated options value to be an object" }]);
+                }
+                // SAFETY: the schema validated the value against `TOptions` and the
+                // object-shape check above passed, so the value is a `TOptions`.
+                pipelineOptions = validated;
+            }
+            catch (error) {
+                const pipelineError = toPipelineError(error, {
+                    code: "TUBELESS_OPTIONS_VALIDATION_FAILED",
+                    kind: "validation",
+                    phase: "execution",
+                });
+                const result = errorRunResult(runtime, definition.id, dryRun, startedAt, [pipelineError], identity);
+                lifecycle.pipelineComplete(result);
+                await lifecycle.flush();
+                return result;
+            }
+        }
+        for (const step of runPlan.steps) {
+            publishStepStatus({ pipelineId: definition.id, status: "planned", step });
+        }
+        const outputs = new Map();
+        const reports = [];
+        const errors = [];
+        const reportsByStepId = new Map();
+        let completed = true;
+        const executionContext = {
+            ...runtime,
+            dryRun,
+            log: tracedLogger(),
+            options: pipelineOptions,
+            runId,
+            trace: trace?.context,
+        };
+        if (parentRunId)
+            executionContext.parentRunId = parentRunId;
+        const stepsById = new Map(definition.steps.map((step) => [step.id, step]));
+        // `runPlan.steps` is already topologically ordered. Rehydrate from the original step
+        // objects so callers still get the typed `run` functions rather than plan metadata.
+        // SAFETY: every planned step id originates from `definition.steps`, so the
+        // map lookup always finds the matching `AnyStep<TOptions>`.
+        const orderedSteps = runPlan.steps.map((step) => stepsById.get(step.id));
+        const recordRemainingStates = (fromIndex, failedStepId, cancellationError) => {
+            const stoppedAfter = {
+                stepId: failedStepId ?? "",
+                cancelled: cancellationError !== undefined,
+            };
+            for (let index = fromIndex; index < orderedSteps.length; index++) {
+                const step = orderedSteps[index];
+                const plannedStep = plannedSteps.get(step.id) ?? stepToPlanStep(step, true);
+                const disposition = decideStepDisposition({
+                    dryRun,
+                    planned: plannedStep,
+                    reportsByStepId,
+                    step,
+                    stoppedAfter,
+                });
+                if (disposition.kind === "cancelled" && cancellationError) {
+                    const report = {
+                        id: step.id,
+                        name: step.name,
+                        description: step.description,
+                        error: { ...cancellationError, stepId: step.id },
+                        finishedAtMs: runtime.now(),
+                        status: "cancelled",
+                    };
+                    reports.push(report);
+                    reportsByStepId.set(step.id, report);
+                    publishStepReport(plannedStep, report);
+                    continue;
+                }
+                const skip = disposition.kind === "skip"
+                    ? disposition
+                    : {
+                        reason: "fail-fast",
+                        dependencyId: failedStepId,
+                        message: failedStepId
+                            ? `Not run because fail-fast stopped after ${failedStepId} failed.`
+                            : "Not run because the pipeline was aborted before this step started.",
+                    };
+                const report = recordSkip(step, step.id, reports, reportsByStepId, skip.reason, skip.message, skip.dependencyId, undefined, undefined, runtime.now());
+                publishStepReport(plannedStep, report);
+            }
+        };
+        for (const [stepIndex, step] of orderedSteps.entries()) {
+            const stepId = step.id;
+            const plannedStep = plannedSteps.get(stepId) ?? stepToPlanStep(step, true);
+            try {
+                throwIfAborted(runtime);
+            }
+            catch (error) {
+                const pipelineError = toPipelineError(error, {
+                    code: "TUBELESS_RUN_CANCELLED",
+                    kind: "cancellation",
+                    phase: "execution",
+                    stepId,
+                });
+                errors.push(pipelineError);
+                completed = false;
+                recordRemainingStates(stepIndex, undefined, pipelineError);
+                break;
+            }
+            const disposition = decideStepDisposition({
+                dryRun,
+                planned: plannedStep,
+                reportsByStepId,
+                step,
+            });
+            if (disposition.kind === "skip") {
+                const report = recordSkip(step, stepId, reports, reportsByStepId, disposition.reason, disposition.message, disposition.dependencyId, undefined, undefined, runtime.now());
+                publishStepReport(plannedStep, report);
+                continue;
+            }
+            const inputs = {};
+            for (const dep of step.dependsOn ?? []) {
+                inputs[dep.id] = outputs.get(dep.id);
+            }
+            for (const dep of step.optionalDependsOn ?? []) {
+                if (outputs.has(dep.id)) {
+                    inputs[dep.id] = outputs.get(dep.id);
+                }
+            }
+            if (typeof step.skip === "function") {
+                const skipDecision = normalizeStepSkipDecision(await step.skip(inputs, { ...executionContext, log: tracedLogger(stepId) }));
+                if (skipDecision) {
+                    let skippedOutput = skipDecision.value;
+                    let policyAttemptId;
+                    let policyStartedAtMs;
+                    let policyFinishedAtMs;
+                    if (step.outputSchema) {
+                        const validationStartedAt = runtime.now();
+                        const attempt = beginAttempt(stepId, validationStartedAt);
+                        policyAttemptId = attempt.attemptId;
+                        policyStartedAtMs = attempt.startedAtMs;
+                        publishStepStatus({
+                            attemptId: attempt.attemptId,
+                            pipelineId: definition.id,
+                            status: "running",
+                            step: plannedStep,
+                        });
+                        try {
+                            skippedOutput = await validateStandardSchema(step.outputSchema, skippedOutput, `Pipeline ${definition.id} step ${stepId} output`);
+                        }
+                        catch (error) {
+                            const pipelineError = toPipelineError(error, {
+                                code: "TUBELESS_STEP_OUTPUT_VALIDATION_FAILED",
+                                kind: "validation",
+                                phase: "execution",
+                                stepId,
+                            });
+                            errors.push(pipelineError);
+                            const finishedAtMs = runtime.now();
+                            const report = {
+                                attemptId: attempt.attemptId,
+                                id: stepId,
+                                name: step.name,
+                                description: step.description,
+                                error: pipelineError,
+                                finishedAtMs,
+                                startedAtMs: attempt.startedAtMs,
+                                status: "failed",
+                            };
+                            reports.push(report);
+                            reportsByStepId.set(stepId, report);
+                            publishStepReport(plannedStep, report);
+                            completed = false;
+                            if (!controls.continueOnError) {
+                                recordRemainingStates(stepIndex + 1, stepId);
+                                break;
+                            }
+                            continue;
+                        }
+                        policyFinishedAtMs = runtime.now();
+                    }
+                    // Always publish an output slot so optionalDependsOn can observe the skip.
+                    outputs.set(stepId, skippedOutput);
+                    const report = recordSkip(step, stepId, reports, reportsByStepId, "policy", skipDecision.reason, undefined, policyAttemptId, policyStartedAtMs, policyFinishedAtMs ?? runtime.now());
+                    publishStepReport(plannedStep, report);
+                    continue;
+                }
+            }
+            const stepStartedAt = runtime.now();
+            const attempt = beginAttempt(stepId, stepStartedAt);
+            publishStepStatus({
+                attemptId: attempt.attemptId,
+                pipelineId: definition.id,
+                status: "running",
+                step: plannedStep,
+            });
+            try {
+                let acceptsProgress = true;
+                const publishProgress = (progress) => {
+                    if (!acceptsProgress)
+                        return;
+                    publishStepStatus({
+                        attemptId: attempt.attemptId,
+                        pipelineId: definition.id,
+                        progress,
+                        status: "running",
+                        step: plannedStep,
+                    });
+                };
+                const stepContext = {
+                    ...executionContext,
+                    attemptId: attempt.attemptId,
+                    log: tracedLogger(stepId, attempt.attemptId),
+                    reportAttempt: (attempt, attributes) => {
+                        lifecycle.reportAttempt(stepId, attempt, attributes, stepContext.attemptId);
+                    },
+                    reportProgress: (progress) => {
+                        publishProgress(progress);
+                    },
+                };
+                let output;
+                try {
+                    const runStep = dryRun && typeof step.dryRun === "function" ? step.dryRun : step.run;
+                    output = await runStep(inputs, stepContext);
+                    if (step.outputSchema) {
+                        output = await validateStandardSchema(step.outputSchema, output, `Pipeline ${definition.id} step ${stepId} output`);
+                    }
+                }
+                finally {
+                    acceptsProgress = false;
+                }
+                outputs.set(stepId, output);
+                const finishedAtMs = runtime.now();
+                const report = {
+                    attemptId: attempt.attemptId,
+                    id: stepId,
+                    name: step.name,
+                    description: step.description,
+                    finishedAtMs,
+                    startedAtMs: attempt.startedAtMs,
+                    status: "complete",
+                };
+                reports.push(report);
+                reportsByStepId.set(stepId, report);
+                publishStepReport(plannedStep, report);
+            }
+            catch (error) {
+                const cancelled = isPipelineCancellation(error, runtime);
+                const childFailure = error instanceof PipelineExecutionError || error instanceof PipelineChildError;
+                const validationFailure = error instanceof PipelineBoundaryValidationError;
+                const pipelineError = toPipelineError(error, {
+                    code: cancelled
+                        ? "TUBELESS_RUN_CANCELLED"
+                        : validationFailure
+                            ? "TUBELESS_STEP_OUTPUT_VALIDATION_FAILED"
+                            : childFailure
+                                ? "TUBELESS_CHILD_FAILED"
+                                : "TUBELESS_STEP_FAILED",
+                    kind: cancelled
+                        ? "cancellation"
+                        : validationFailure
+                            ? "validation"
+                            : childFailure
+                                ? "child"
+                                : "step",
+                    phase: "execution",
+                    stepId,
+                });
+                errors.push(pipelineError);
+                const finishedAtMs = runtime.now();
+                const report = cancelled
+                    ? {
+                        attemptId: attempt.attemptId,
+                        id: stepId,
+                        name: step.name,
+                        description: step.description,
+                        error: pipelineError,
+                        finishedAtMs,
+                        startedAtMs: attempt.startedAtMs,
+                        status: "cancelled",
+                    }
+                    : {
+                        attemptId: attempt.attemptId,
+                        id: stepId,
+                        name: step.name,
+                        description: step.description,
+                        error: pipelineError,
+                        finishedAtMs,
+                        startedAtMs: attempt.startedAtMs,
+                        status: "failed",
+                    };
+                reports.push(report);
+                reportsByStepId.set(stepId, report);
+                publishStepReport(plannedStep, report);
+                completed = false;
+                if (!controls.continueOnError) {
+                    recordRemainingStates(stepIndex + 1, stepId, report.status === "cancelled" ? pipelineError : undefined);
+                    break;
+                }
+            }
+        }
+        let value;
+        let finalized = false;
+        if (completed || controls.continueOnError) {
+            const finalizeStartedAt = runtime.now();
+            lifecycle.finalizeStart();
+            try {
+                throwIfAborted(runtime);
+                // SAFETY: `outputs` maps step ids to their produced values, which is
+                // exactly the shape `Partial<PipelineOutputs<TSteps>>` describes.
+                const finalOutputs = Object.fromEntries(outputs);
+                const finalizedValue = await definition.finalize(finalOutputs, {
+                    ...executionContext,
+                    log: tracedLogger(PIPELINE_FINALIZE_STEP_ID),
+                });
+                // SAFETY: with a result schema the value is validated against
+                // `TPipelineResult`; without one the finalizer's declared return type
+                // is `TPipelineResult`, so the cast only restores that type.
+                value = definition.resultSchema
+                    ? (await validateStandardSchema(definition.resultSchema, finalizedValue, `Pipeline ${definition.id} final result`))
+                    : finalizedValue;
+                finalized = true;
+                lifecycle.finalizeComplete(runtime.now() - finalizeStartedAt, value);
+            }
+            catch (error) {
+                const cancelled = isPipelineCancellation(error, runtime);
+                const validationFailure = error instanceof PipelineBoundaryValidationError;
+                const pipelineError = toPipelineError(error, {
+                    code: cancelled
+                        ? "TUBELESS_FINALIZATION_CANCELLED"
+                        : validationFailure
+                            ? "TUBELESS_FINAL_RESULT_VALIDATION_FAILED"
+                            : "TUBELESS_FINALIZATION_FAILED",
+                    kind: cancelled ? "cancellation" : validationFailure ? "validation" : "finalization",
+                    phase: "finalization",
+                    stepId: PIPELINE_FINALIZE_STEP_ID,
+                });
+                errors.push(pipelineError);
+                lifecycle.finalizeError(pipelineError, runtime.now() - finalizeStartedAt);
+                completed = false;
+            }
+        }
+        const finishedAtMs = runtime.now();
+        const result = {
+            pipelineId: definition.id,
+            dryRun,
+            errors,
+            finalized,
+            finishedAtMs,
+            runId,
+            startedAtMs: startedAt,
+            status: terminalRunStatus(errors),
+            steps: reports,
+            value,
+            version: RUN_MODEL_VERSION,
+        };
+        if (parentRunId)
+            result.parentRunId = parentRunId;
+        lifecycle.pipelineComplete(result);
+        await lifecycle.flush();
+        return result;
+    }
+    async function runOrThrow(options, context = defaultPipelineContext()) {
+        const result = await run(options, context);
+        if (result.status !== "completed") {
+            throw new PipelineExecutionError(result);
+        }
+        // SAFETY: a completed run always carries its `TPipelineResult` value.
+        return result.value;
+    }
+    return { id: definition.id, stepIds, targetIds, plan, run, runOrThrow, toMermaid };
+}
+export { formatMappedChildProgressMessage, mappedChildProgressDetails, mappedChildProgressUnits, toMappedChildStepProgress, } from "./mapped-child-progress.js";
+//# sourceMappingURL=pipeline.js.map