stageflow 0.16.0 → 0.18.0

package/dist/config/loadPipeline.d.ts

@@ -6,8 +6,10 @@ export declare function resolvePipelinePath(pipelinePath: string, cwd: string):
 export declare function loadPipelineOutcome(nameOrPath: string, options?: {
     cwd?: string;
     projectRoot?: string;
+    requireIo?: boolean;
 }): Promise<LoadOutcome<LoadedPipeline>>;
 export declare function loadPipeline(nameOrPath: string, options?: {
     cwd?: string;
     projectRoot?: string;
+    requireIo?: boolean;
 }): Promise<LoadedPipeline>;

package/dist/config/loadPipeline.js

@@ -10,6 +10,8 @@ import { predecessorEdges } from "./pipelineNeeds.js";
 import { resolvePipelineDagFromRefs } from "./resolvePipelineDag.js";
 import { recoveryRequiresCompletionIssue } from "./parseCompletionContract.js";
 import { validateCompletionContractForStage } from "./validateCompletionContract.js";
+import { applyCloneChains } from "./cloneChain.js";
+import { collectRouteIfSchemaIssues, collectRouteIfIllegalCombos, collectRouteAllGatedWarnings, } from "./routeIf.js";
 function schemaCompileIssue(stageId, field, err, pipelineId) {
     const message = err instanceof Error ? err.message : String(err);
     if (err instanceof UnresolvedSchemaRefError) {
@@ -59,26 +61,23 @@ function checkSequentialIoCompatibility(stages, dag, pipelineId, schemas) {
         const node = nodeById.get(child.id);
         if (!node)
             continue;
-        const parents = predecessorEdges(node);
-        if (parents.length !== 1)
-            continue;
-        if (node.clonable)
-            continue;
-        const parentNode = nodeById.get(parents[0].id);
-        if (parentNode?.clonable)
-            continue;
-        const parent = stageById.get(parents[0].id);
-        if (!parent?.payload_schema || child.clone_input_schema === undefined)
-            continue;
-        if (!isPayloadSchemaSubset(child.clone_input_schema, parent.payload_schema, options)) {
-            return loadFailure([
-                {
-                    code: "pipeline.io_incompatible",
-                    message: `Pipeline ${pipelineId}: stage "${child.id}" io.input is not a structural subset of "${parent.id}" io.output`,
-                    category: "pipeline",
-                    pipelineId,
-                },
-            ]);
+        for (const parentEdge of predecessorEdges(node)) {
+            const parentNode = nodeById.get(parentEdge.id);
+            if (parentNode?.clone_array_field !== undefined)
+                continue;
+            const parent = stageById.get(parentEdge.id);
+            if (!parent?.payload_schema || child.clone_input_schema === undefined)
+                continue;
+            if (!isPayloadSchemaSubset(child.clone_input_schema, parent.payload_schema, options)) {
+                return loadFailure([
+                    {
+                        code: "pipeline.io_incompatible",
+                        message: `Pipeline ${pipelineId}: stage "${child.id}" io.input is not a structural subset of "${parent.id}" io.output`,
+                        category: "pipeline",
+                        pipelineId,
+                    },
+                ]);
+            }
         }
     }
     return loadSuccess(undefined);
@@ -93,7 +92,7 @@ export async function resolvePipelinePath(pipelinePath, cwd) {
         throw new Error(`Pipeline file not found: ${resolved}. Pass a filesystem path to --pipeline (e.g. pipelines/hello.pipeline.yaml), not a bare pipeline id.`);
     }
 }
-async function loadPipelineFromPath(pipelinePath, cwd, projectRoot = cwd) {
+async function loadPipelineFromPath(pipelinePath, cwd, projectRoot = cwd, requireIo = true) {
     const normalizedPipelinePath = path.normalize(path.resolve(pipelinePath));
     const mergeOutcome = await mergePipelineStages(normalizedPipelinePath);
     if (!mergeOutcome.ok) {
@@ -147,6 +146,7 @@ async function loadPipelineFromPath(pipelinePath, cwd, projectRoot = cwd) {
                 entryId: entry.id,
                 declaringPath: entry.declaringPath,
                 deferSchemaRefs: true,
+                requireIo,
             });
             if (!inlineOutcome.ok) {
                 return loadFailure(inlineOutcome.issues);
@@ -157,6 +157,7 @@ async function loadPipelineFromPath(pipelinePath, cwd, projectRoot = cwd) {
         }
         const stageOutcome = await loadStageOutcome(entry.body.absolutePath, {
             deferSchemaRefs: true,
+            requireIo,
         });
         if (!stageOutcome.ok) {
             if (stageOutcome.issues.some((issue) => issue.code === "catalog.mixed_yaml_dialect")) {
@@ -206,9 +207,20 @@ async function loadPipelineFromPath(pipelinePath, cwd, projectRoot = cwd) {
         stages.push(stage);
         stageSources[stageId] = { kind: "file", path: entry.body.absolutePath };
     }
+    const cloneChainOutcome = applyCloneChains(stages, wiringRefs, dag, pipelineId);
+    if (!cloneChainOutcome.ok)
+        return cloneChainOutcome;
     const schemaOutcome = attachPipelineSchemas(stages, pipelineSchemas, pipelineId);
     if (!schemaOutcome.ok)
         return schemaOutcome;
+    const routeIfIssues = [
+        ...collectRouteIfSchemaIssues(stages, wiringRefs, pipelineId),
+        ...collectRouteIfIllegalCombos(wiringRefs, pipelineId),
+    ];
+    if (routeIfIssues.length > 0) {
+        return loadFailure(routeIfIssues);
+    }
+    warnings.push(...collectRouteAllGatedWarnings(wiringRefs, pipelineId));
     const ioOutcome = checkSequentialIoCompatibility(stages, dag, pipelineId, pipelineSchemas);
     if (!ioOutcome.ok)
         return ioOutcome;
@@ -283,7 +295,7 @@ export async function loadPipelineOutcome(nameOrPath, options = {}) {
             },
         ]);
     }
-    return loadPipelineFromPath(pipelinePath, cwd, projectRoot);
+    return loadPipelineFromPath(pipelinePath, cwd, projectRoot, options.requireIo !== false);
 }
 export async function loadPipeline(nameOrPath, options = {}) {
     const outcome = await loadPipelineOutcome(nameOrPath, options);

package/dist/config/loadStage.d.ts

@@ -6,11 +6,13 @@ export declare function afterCompletionForStage(stage: StageConfig): CompletionC
 export declare function parseStageMcp(raw: unknown, label: string, stageId?: string): LoadOutcome<string[] | undefined>;
 export type LoadStageOptions = {
     deferSchemaRefs?: boolean;
+    requireIo?: boolean;
 };
 export declare function loadStageFromObjectOutcome(raw: Record<string, unknown>, ctx: {
     entryId: string;
     declaringPath: string;
     deferSchemaRefs?: boolean;
+    requireIo?: boolean;
 }): LoadOutcome<StageConfig>;
 export declare function loadStageOutcome(filePath: string, options?: LoadStageOptions): Promise<LoadOutcome<StageConfig>>;
 export declare function loadStage(filePath: string): Promise<StageConfig>;

package/dist/config/loadStage.js

@@ -1,6 +1,5 @@
 import { parseAgentField } from "../agent/agentBackend.js";
 import { STAGEFLOW_MCP_SERVER_NAME } from "../agent/claudeTools.js";
-import { CLONE_ACTIONS } from "../types/forkChoice.js";
 import { STAGE_GATE_KINDS, } from "../types/stage.js";
 import { compilePayloadSchema, UnresolvedSchemaRefError } from "../envelope/payloadSchema.js";
 import { loadFailure, loadSuccess } from "./loadOutcome.js";
@@ -8,7 +7,7 @@ import { parseModelField } from "./modelField.js";
 import { allowLegacyYamlAuthoring, dialectWarningForDocument, legacyAuthoringRejected, presentLegacyKeys, } from "./legacyYaml.js";
 import { parsePreEmitChecks } from "./parsePreEmitChecks.js";
 import { readYamlObject } from "./readYamlObject.js";
-import { applyCompiledBody, classifyYamlDocument, compileTargetContract, dialectFromKeys, mixedDialectIssue, STAGE_FILE_WIRING_KEYS, } from "./yamlDialect.js";
+import { classifyYamlDocument, compileTargetContract, dialectFromKeys, mixedDialectIssue, STAGE_FILE_WIRING_KEYS, } from "./yamlDialect.js";
 const afterCompletionByStage = new WeakMap();
 /** After-phase IR from target `verify` (`when` includes after). Stamped onto DAG `completion`. */
 export function afterCompletionForStage(stage) {
@@ -17,45 +16,6 @@ export function afterCompletionForStage(stage) {
 function isGateKind(value) {
     return STAGE_GATE_KINDS.includes(value);
 }
-function isCloneAction(value) {
-    return CLONE_ACTIONS.includes(value);
-}
-function parseCloneActions(raw, label) {
-    if (raw === undefined)
-        return loadSuccess(undefined);
-    if (!Array.isArray(raw) || !raw.every((item) => typeof item === "string")) {
-        return loadFailure([
-            {
-                code: "stage.invalid_clone_actions",
-                message: `Invalid stage ${label}: clone_actions must be a non-empty array of strings`,
-                category: "stage",
-            },
-        ]);
-    }
-    if (raw.length === 0) {
-        return loadFailure([
-            {
-                code: "stage.invalid_clone_actions",
-                message: `Invalid stage ${label}: clone_actions must not be empty`,
-                category: "stage",
-            },
-        ]);
-    }
-    const actions = [];
-    for (const item of raw) {
-        if (!isCloneAction(item)) {
-            return loadFailure([
-                {
-                    code: "stage.invalid_clone_actions",
-                    message: `Invalid stage ${label}: unsupported clone_actions value "${item}" (allowed: ${CLONE_ACTIONS.join(", ")})`,
-                    category: "stage",
-                },
-            ]);
-        }
-        actions.push(item);
-    }
-    return loadSuccess(actions);
-}
 function parseTimeoutMs(raw, label) {
     if (raw === undefined)
         return loadSuccess(undefined);
@@ -162,9 +122,7 @@ export function parseStageMcp(raw, label, stageId) {
     }
     return loadSuccess(names);
 }
-function parseStageFields(raw, label, entryId, deferSchemaRefs) {
-    // Reads IR field names. Target YAML must already be compiled via
-    // applyCompiledBody; legacy YAML uses these keys as authoring.
+function parseStageFields(raw, label, entryId, deferSchemaRefs, requireIo, compiled) {
     if (typeof raw.system_prompt !== "string") {
         return loadFailure([
             {
@@ -179,6 +137,16 @@ function parseStageFields(raw, label, entryId, deferSchemaRefs) {
         id: entryId,
         system_prompt: raw.system_prompt,
     };
+    if (raw.clone_actions !== undefined) {
+        return loadFailure([
+            {
+                code: "stage.invalid_clone_actions",
+                message: `Invalid stage ${label}: "clone_actions" is no longer supported — use a Clone Chain instead`,
+                category: "stage",
+                stageId: entryId,
+            },
+        ]);
+    }
     const modelField = parseModelField(raw.model);
     if (!modelField.ok) {
         return loadFailure([
@@ -193,102 +161,133 @@ function parseStageFields(raw, label, entryId, deferSchemaRefs) {
     if (modelField.value !== undefined) {
         stage.model = modelField.value;
     }
-    if (raw.payload_schema !== undefined) {
-        if (raw.payload_schema === null ||
-            typeof raw.payload_schema !== "object" ||
-            Array.isArray(raw.payload_schema)) {
-            return loadFailure([
-                {
-                    code: "stage.invalid_payload_schema",
-                    message: `Invalid stage ${label}: payload_schema must be an object`,
-                    category: "stage",
-                    stageId: entryId,
-                },
-            ]);
+    if (compiled) {
+        if (compiled.payload_schema !== undefined) {
+            stage.payload_schema = compiled.payload_schema;
         }
-        try {
-            compilePayloadSchema(raw.payload_schema);
+        if (compiled.clone_input_schema !== undefined) {
+            stage.clone_input_schema = compiled.clone_input_schema;
         }
-        catch (err) {
-            if (err instanceof UnresolvedSchemaRefError) {
-                if (!deferSchemaRefs) {
+    }
+    else {
+        if (raw.payload_schema !== undefined) {
+            if (raw.payload_schema === null ||
+                typeof raw.payload_schema !== "object" ||
+                Array.isArray(raw.payload_schema)) {
+                return loadFailure([
+                    {
+                        code: "stage.invalid_payload_schema",
+                        message: `Invalid stage ${label}: io.output.schema must be an object`,
+                        category: "stage",
+                        stageId: entryId,
+                    },
+                ]);
+            }
+            try {
+                compilePayloadSchema(raw.payload_schema);
+            }
+            catch (err) {
+                if (err instanceof UnresolvedSchemaRefError) {
+                    if (!deferSchemaRefs) {
+                        return loadFailure([
+                            {
+                                code: "stage.unresolved_schema_ref",
+                                message: `Invalid stage ${label}: ${err.message}`,
+                                category: "stage",
+                                stageId: entryId,
+                            },
+                        ]);
+                    }
+                }
+                else {
+                    const message = err instanceof Error ? err.message : String(err);
                     return loadFailure([
                         {
-                            code: "stage.unresolved_schema_ref",
-                            message: `Invalid stage ${label}: ${err.message}`,
+                            code: "stage.invalid_payload_schema",
+                            message: `Invalid stage ${label}: invalid io.output.schema: ${message}`,
                             category: "stage",
                             stageId: entryId,
                         },
                     ]);
                 }
             }
-            else {
-                const message = err instanceof Error ? err.message : String(err);
+            stage.payload_schema = raw.payload_schema;
+        }
+        if (raw.clone_input_schema !== undefined) {
+            if (raw.clone_input_schema === null ||
+                typeof raw.clone_input_schema !== "object" ||
+                Array.isArray(raw.clone_input_schema)) {
                 return loadFailure([
                     {
-                        code: "stage.invalid_payload_schema",
-                        message: `Invalid stage ${label}: invalid payload_schema: ${message}`,
+                        code: "stage.invalid_clone_input_schema",
+                        message: `Invalid stage ${label}: io.input.schema must be an object`,
                         category: "stage",
                         stageId: entryId,
                     },
                 ]);
             }
-        }
-        stage.payload_schema = raw.payload_schema;
-    }
-    if (raw.clone_input_schema !== undefined) {
-        if (raw.clone_input_schema === null ||
-            typeof raw.clone_input_schema !== "object" ||
-            Array.isArray(raw.clone_input_schema)) {
-            return loadFailure([
-                {
-                    code: "stage.invalid_clone_input_schema",
-                    message: `Invalid stage ${label}: clone_input_schema must be an object`,
-                    category: "stage",
-                    stageId: entryId,
-                },
-            ]);
-        }
-        try {
-            compilePayloadSchema(raw.clone_input_schema);
-        }
-        catch (err) {
-            if (err instanceof UnresolvedSchemaRefError) {
-                if (!deferSchemaRefs) {
+            try {
+                compilePayloadSchema(raw.clone_input_schema);
+            }
+            catch (err) {
+                if (err instanceof UnresolvedSchemaRefError) {
+                    if (!deferSchemaRefs) {
+                        return loadFailure([
+                            {
+                                code: "stage.unresolved_schema_ref",
+                                message: `Invalid stage ${label}: ${err.message}`,
+                                category: "stage",
+                                stageId: entryId,
+                            },
+                        ]);
+                    }
+                }
+                else {
+                    const message = err instanceof Error ? err.message : String(err);
                     return loadFailure([
                         {
-                            code: "stage.unresolved_schema_ref",
-                            message: `Invalid stage ${label}: ${err.message}`,
+                            code: "stage.invalid_clone_input_schema",
+                            message: `Invalid stage ${label}: invalid io.input.schema: ${message}`,
                             category: "stage",
                             stageId: entryId,
                         },
                     ]);
                 }
             }
-            else {
-                const message = err instanceof Error ? err.message : String(err);
+            stage.clone_input_schema = raw.clone_input_schema;
+        }
+        if (requireIo) {
+            if (raw.payload_schema === undefined && raw.clone_input_schema === undefined) {
                 return loadFailure([
                     {
-                        code: "stage.invalid_clone_input_schema",
-                        message: `Invalid stage ${label}: invalid clone_input_schema: ${message}`,
+                        code: "stage.invalid_io",
+                        message: `Invalid stage ${label}: io is required`,
+                        category: "stage",
+                        stageId: entryId,
+                    },
+                ]);
+            }
+            if (raw.payload_schema === undefined) {
+                return loadFailure([
+                    {
+                        code: "stage.invalid_io",
+                        message: `Invalid stage ${label}: io.output.schema is required`,
+                        category: "stage",
+                        stageId: entryId,
+                    },
+                ]);
+            }
+            if (raw.clone_input_schema === undefined) {
+                return loadFailure([
+                    {
+                        code: "stage.invalid_io",
+                        message: `Invalid stage ${label}: io.input.schema is required`,
                         category: "stage",
                         stageId: entryId,
                     },
                 ]);
             }
         }
-        stage.clone_input_schema = raw.clone_input_schema;
-    }
-    const cloneActionsOutcome = parseCloneActions(raw.clone_actions, label);
-    if (!cloneActionsOutcome.ok) {
-        const issues = cloneActionsOutcome.issues.map((issue) => ({
-            ...issue,
-            stageId: entryId,
-        }));
-        return loadFailure(issues);
-    }
-    if (cloneActionsOutcome.value !== undefined) {
-        stage.clone_actions = cloneActionsOutcome.value;
     }
     const gateKindsOutcome = parseGateKinds(raw.gate_kinds, label);
     if (!gateKindsOutcome.ok) {
@@ -312,16 +311,23 @@ function parseStageFields(raw, label, entryId, deferSchemaRefs) {
     if (timeoutMsOutcome.value !== undefined) {
         stage.timeout_ms = timeoutMsOutcome.value;
     }
-    const preEmitChecksOutcome = parsePreEmitChecks(raw.pre_emit_checks, label);
-    if (!preEmitChecksOutcome.ok) {
-        const issues = preEmitChecksOutcome.issues.map((issue) => ({
-            ...issue,
-            stageId: entryId,
-        }));
-        return loadFailure(issues);
+    if (compiled) {
+        if (compiled.pre_emit_checks !== undefined) {
+            stage.pre_emit_checks = compiled.pre_emit_checks;
+        }
     }
-    if (preEmitChecksOutcome.value !== undefined) {
-        stage.pre_emit_checks = preEmitChecksOutcome.value;
+    else {
+        const preEmitChecksOutcome = parsePreEmitChecks(raw.pre_emit_checks, label);
+        if (!preEmitChecksOutcome.ok) {
+            const issues = preEmitChecksOutcome.issues.map((issue) => ({
+                ...issue,
+                stageId: entryId,
+            }));
+            return loadFailure(issues);
+        }
+        if (preEmitChecksOutcome.value !== undefined) {
+            stage.pre_emit_checks = preEmitChecksOutcome.value;
+        }
     }
     if (raw.skill !== undefined) {
         if (typeof raw.skill !== "string" || raw.skill.trim() === "") {
@@ -361,6 +367,7 @@ function parseStageFields(raw, label, entryId, deferSchemaRefs) {
 export function loadStageFromObjectOutcome(raw, ctx) {
     const label = `${ctx.entryId} (${ctx.declaringPath})`;
     const deferSchemaRefs = ctx.deferSchemaRefs === true;
+    const requireIo = ctx.requireIo !== false;
     const dialect = dialectFromKeys(Object.keys(raw));
     if (dialect === "invalid") {
         return loadFailure([mixedDialectIssue()]);
@@ -374,12 +381,13 @@ export function loadStageFromObjectOutcome(raw, ctx) {
             label,
             category: "stage",
             deferSchemaRefs,
+            requireIo,
         });
         if (!compiled.ok)
             return compiled;
-        return parseStageFields(applyCompiledBody(raw, compiled.value), label, ctx.entryId, deferSchemaRefs);
+        return parseStageFields(raw, label, ctx.entryId, deferSchemaRefs, requireIo, compiled.value);
     }
-    return parseStageFields(raw, label, ctx.entryId, deferSchemaRefs);
+    return parseStageFields(raw, label, ctx.entryId, deferSchemaRefs, requireIo);
 }
 export async function loadStageOutcome(filePath, options = {}) {
     let raw;
@@ -425,22 +433,24 @@ export async function loadStageOutcome(filePath, options = {}) {
             ]);
         }
     }
-    let parseRaw = raw;
+    let compiled;
     let afterCompletion;
     const deferSchemaRefs = options.deferSchemaRefs === true;
+    const requireIo = options.requireIo !== false;
     if (dialect === "target") {
-        const compiled = compileTargetContract(raw, {
+        const compiledOutcome = compileTargetContract(raw, {
             stageId: raw.id,
             label: `file ${filePath}`,
             category: "stage",
             deferSchemaRefs,
+            requireIo,
         });
-        if (!compiled.ok)
-            return compiled;
-        parseRaw = applyCompiledBody(raw, compiled.value);
-        afterCompletion = compiled.value.completion;
+        if (!compiledOutcome.ok)
+            return compiledOutcome;
+        compiled = compiledOutcome.value;
+        afterCompletion = compiled.completion;
     }
-    const outcome = parseStageFields(parseRaw, `file ${filePath}`, raw.id, deferSchemaRefs);
+    const outcome = parseStageFields(raw, `file ${filePath}`, raw.id, deferSchemaRefs, requireIo, compiled);
     if (!outcome.ok)
         return outcome;
     if (outcome.value.id !== raw.id) {

package/dist/config/migrateYaml.js

@@ -333,7 +333,11 @@ async function refuseOutOfScopeUsesFolds(usesCompile, scopePipelines, catalogRoo
             catch {
                 outsideId = undefined;
             }
-            const outcome = await loadPipelineOutcome(pipelinePath, { cwd, projectRoot });
+            const outcome = await loadPipelineOutcome(pipelinePath, {
+                cwd,
+                projectRoot,
+                requireIo: false,
+            });
             if (outcome.ok) {
                 const other = new Map();
                 const otherErrors = [];
@@ -415,7 +419,11 @@ async function planMigrateYamlInner(targetPath, options) {
             skipped.add(relPath(cwd, pipelinePath));
             continue;
         }
-        const outcome = await loadPipelineOutcome(pipelinePath, { cwd, projectRoot });
+        const outcome = await loadPipelineOutcome(pipelinePath, {
+            cwd,
+            projectRoot,
+            requireIo: false,
+        });
         if (!outcome.ok) {
             if (outcome.issues.some((issue) => issue.code === "catalog.mixed_yaml_dialect")) {
                 skipped.add(relPath(cwd, pipelinePath));
@@ -518,7 +526,10 @@ async function planMigrateYamlInner(targetPath, options) {
             skipped.add(relPath(cwd, stagePath));
             continue;
         }
-        const outcome = await loadStageOutcome(stagePath, { deferSchemaRefs: true });
+        const outcome = await loadStageOutcome(stagePath, {
+            deferSchemaRefs: true,
+            requireIo: false,
+        });
         if (!outcome.ok) {
             if (outcome.issues.some((issue) => issue.code === "catalog.mixed_yaml_dialect")) {
                 skipped.add(relPath(cwd, stagePath));

package/dist/config/normalizePipelineStageEntry.d.ts

@@ -1,5 +1,5 @@
 import type { CompletionContract, RecoveryPolicy } from "../types/completion.js";
-import type { NormalizedPipelineStageEntry, PipelineNeeds } from "../types/pipeline.js";
+import type { CloneMode, NormalizedPipelineStageEntry, PipelineRouteEntry } from "../types/pipeline.js";
 import { type LoadOutcome } from "./loadOutcome.js";
 import type { RawMergedEntry } from "./mergePipelineIncludes.js";
 export declare function inferIdFromUsesPath(usesPath: string): string | null;
@@ -9,15 +9,11 @@ export declare function normalizePipelineStageEntries(rawEntries: RawMergedEntry
 }): LoadOutcome<NormalizedPipelineStageEntry[]>;
 export declare function toWiringRefs(entries: NormalizedPipelineStageEntry[]): Array<{
     id: string;
-    needs?: PipelineNeeds;
-    fork?: {
-        select: "one" | "subset";
-        allow_none?: boolean;
-    };
-    clonable?: boolean;
-    clone_cap?: number;
     completion?: CompletionContract;
     recovery?: RecoveryPolicy;
-    feedback_loop?: NormalizedPipelineStageEntry["feedback_loop"];
     replay_safe?: boolean;
+    route?: PipelineRouteEntry[];
+    entry?: boolean;
+    clone_cap?: number;
+    clone_mode?: CloneMode;
 }>;