stageflow 0.16.0 → 0.18.0

package/dist/config/normalizePipelineStageEntry.js

@@ -1,17 +1,17 @@
 /**
  * Normalize a pipeline `stages:` entry. Target YAML (`io` / `verify` /
- * `on_verify_fail`) compiles onto IR `completion` / `recovery` / body
- * `payload_schema`. Legacy YAML keys are dual-read via legacyYaml.ts.
+ * `on_verify_fail`) compiles onto IR `completion` / `recovery`. Emit/schema
+ * fields stay on the YAML-shaped inline body until `parseStageFields`.
+ * Legacy YAML keys are dual-read via legacyYaml.ts.
  */
 import path from "node:path";
 import { loadFailure, loadSuccess } from "./loadOutcome.js";
 import { parseStageMcp } from "./loadStage.js";
 import { legacyAuthoringRejected, presentLegacyKeys } from "./legacyYaml.js";
-import { applyCompiledBody, compileTargetContract, dialectFromKeys, mixedDialectIssue, } from "./yamlDialect.js";
+import { compileTargetContract, dialectFromKeys, mixedDialectIssue, } from "./yamlDialect.js";
 import { BODY_KEYS, isAllowedPipelineStageEntryKey, } from "./pipelineStageKeys.js";
 import { parseExecutionPolicy } from "./parseCompletionContract.js";
-import { parsePipelineNeeds } from "./pipelineNeeds.js";
-import { parseFeedbackLoopConfig } from "./resolvePipelineDag.js";
+import { parsePipelineRoute } from "./pipelineRoute.js";
 function isPlainObject(value) {
     return typeof value === "object" && value !== null && !Array.isArray(value);
 }
@@ -149,7 +149,106 @@ export function normalizePipelineStageEntries(rawEntries, ctx) {
                 },
             ]);
         }
-        let compiledBody;
+        if (raw.needs !== undefined) {
+            return loadFailure([
+                {
+                    code: "pipeline.dag_error",
+                    message: `Pipeline ${ctx.pipelineId} (${ctx.path}): stage "${id}": "needs" is no longer supported — declare the wiring on the source stage's "route" instead`,
+                    category: "pipeline",
+                    pipelineId: ctx.pipelineId,
+                },
+            ]);
+        }
+        if (raw.fork !== undefined) {
+            return loadFailure([
+                {
+                    code: "pipeline.dag_error",
+                    message: `Pipeline ${ctx.pipelineId} (${ctx.path}): stage "${id}": "fork" is no longer supported — use "route" instead; listed route targets always run`,
+                    category: "pipeline",
+                    pipelineId: ctx.pipelineId,
+                },
+            ]);
+        }
+        if (raw.feedback_loop !== undefined) {
+            return loadFailure([
+                {
+                    code: "pipeline.dag_error",
+                    message: `Pipeline ${ctx.pipelineId} (${ctx.path}): stage "${id}": "feedback_loop" is no longer supported — use a "type: loop" entry inside "route" instead`,
+                    category: "pipeline",
+                    pipelineId: ctx.pipelineId,
+                },
+            ]);
+        }
+        if (raw.route_select !== undefined) {
+            return loadFailure([
+                {
+                    code: "pipeline.dag_error",
+                    message: `Pipeline ${ctx.pipelineId} (${ctx.path}): stage "${id}": "route_select" is no longer supported — listed route targets always run`,
+                    category: "pipeline",
+                    pipelineId: ctx.pipelineId,
+                },
+            ]);
+        }
+        if (raw.allow_none !== undefined) {
+            return loadFailure([
+                {
+                    code: "pipeline.dag_error",
+                    message: `Pipeline ${ctx.pipelineId} (${ctx.path}): stage "${id}": "allow_none" is no longer supported — listed route targets always run`,
+                    category: "pipeline",
+                    pipelineId: ctx.pipelineId,
+                },
+            ]);
+        }
+        if (raw.clonable !== undefined) {
+            return loadFailure([
+                {
+                    code: "pipeline.dag_error",
+                    message: `Pipeline ${ctx.pipelineId} (${ctx.path}): stage "${id}": "clonable" is no longer supported — use a Clone Chain instead`,
+                    category: "pipeline",
+                    pipelineId: ctx.pipelineId,
+                },
+            ]);
+        }
+        let cloneCap;
+        if (raw.clone_cap !== undefined) {
+            if (typeof raw.clone_cap !== "number" ||
+                !Number.isInteger(raw.clone_cap) ||
+                raw.clone_cap < 1) {
+                return loadFailure([
+                    {
+                        code: "pipeline.dag_error",
+                        message: `Pipeline ${ctx.pipelineId} (${ctx.path}): stage "${id}": clone_cap must be an integer >= 1`,
+                        category: "pipeline",
+                        pipelineId: ctx.pipelineId,
+                    },
+                ]);
+            }
+            cloneCap = raw.clone_cap;
+        }
+        let cloneMode;
+        if (raw.clone_mode !== undefined) {
+            if (raw.clone_mode !== "parallel" && raw.clone_mode !== "sequential") {
+                return loadFailure([
+                    {
+                        code: "pipeline.dag_error",
+                        message: `Pipeline ${ctx.pipelineId} (${ctx.path}): stage "${id}": clone_mode must be "parallel" or "sequential"`,
+                        category: "pipeline",
+                        pipelineId: ctx.pipelineId,
+                    },
+                ]);
+            }
+            cloneMode = raw.clone_mode;
+        }
+        if (raw.clone_actions !== undefined) {
+            return loadFailure([
+                {
+                    code: "pipeline.dag_error",
+                    message: `Pipeline ${ctx.pipelineId} (${ctx.path}): stage "${id}": "clone_actions" is no longer supported — use a Clone Chain instead`,
+                    category: "pipeline",
+                    pipelineId: ctx.pipelineId,
+                },
+            ]);
+        }
         let policyOutcome;
         if (dialect === "target") {
             const compiled = compileTargetContract(raw, {
@@ -157,6 +256,7 @@ export function normalizePipelineStageEntries(rawEntries, ctx) {
                 label: `entry at index ${index} in ${declaringPath}`,
                 category: "pipeline",
                 deferSchemaRefs: true,
+                requireIo: !uses,
             });
             if (!compiled.ok)
                 return compiled;
@@ -168,9 +268,6 @@ export function normalizePipelineStageEntries(rawEntries, ctx) {
                     ? { recovery: compiled.value.recovery }
                     : {}),
             });
-            if (!uses) {
-                compiledBody = applyCompiledBody(extractBodyRaw(raw), compiled.value);
-            }
         }
         else {
             const rejected = legacyAuthoringRejected(dialect, `stage "${id}" in ${declaringPath}`, presentLegacyKeys(Object.keys(raw)));
@@ -180,23 +277,6 @@ export function normalizePipelineStageEntries(rawEntries, ctx) {
         }
         if (!policyOutcome.ok)
             return policyOutcome;
-        let needs;
-        let feedbackLoop;
-        if (raw.feedback_loop !== undefined) {
-            try {
-                feedbackLoop = parseFeedbackLoopConfig(raw.feedback_loop, id, ctx);
-            }
-            catch (err) {
-                return loadFailure([
-                    {
-                        code: "pipeline.dag_error",
-                        message: err instanceof Error ? err.message : String(err),
-                        category: "pipeline",
-                        pipelineId: ctx.pipelineId,
-                    },
-                ]);
-            }
-        }
         if (raw.replay_safe !== undefined && typeof raw.replay_safe !== "boolean") {
             return loadFailure([
                 {
@@ -207,64 +287,60 @@ export function normalizePipelineStageEntries(rawEntries, ctx) {
                 },
             ]);
         }
-        if (raw.needs !== undefined) {
-            const parsedNeeds = parsePipelineNeeds(raw.needs, id);
-            if (!parsedNeeds.ok) {
+        let route;
+        if (raw.route !== undefined) {
+            const parsedRoute = parsePipelineRoute(raw.route, id);
+            if (!parsedRoute.ok) {
                 return loadFailure([
                     {
-                        code: "pipeline.dag_error",
-                        message: `Pipeline ${ctx.pipelineId} (${ctx.path}): ${parsedNeeds.message}`,
+                        code: parsedRoute.code ?? "pipeline.dag_error",
+                        message: `Pipeline ${ctx.pipelineId} (${ctx.path}): ${parsedRoute.message}`,
                         category: "pipeline",
                         pipelineId: ctx.pipelineId,
+                        ...(parsedRoute.code === "pipeline.route_if_invalid" ? { stageId: id } : {}),
                     },
                 ]);
             }
-            needs = parsedNeeds.value;
+            route = parsedRoute.value;
         }
-        let forkValue;
-        if (raw.fork !== undefined) {
-            if (!isPlainObject(raw.fork)) {
-                return loadFailure([
-                    {
-                        code: "pipeline.dag_error",
-                        message: `Pipeline ${ctx.pipelineId} (${ctx.path}): stage "${id}": fork must be an object`,
-                        category: "pipeline",
-                        pipelineId: ctx.pipelineId,
-                    },
-                ]);
-            }
-            forkValue = raw.fork;
+        if (raw.entry !== undefined && typeof raw.entry !== "boolean") {
+            return loadFailure([
+                {
+                    code: "pipeline.dag_error",
+                    message: `Pipeline ${ctx.pipelineId} (${ctx.path}): stage "${id}": entry must be a boolean`,
+                    category: "pipeline",
+                    pipelineId: ctx.pipelineId,
+                },
+            ]);
         }
+        const entryFlag = raw.entry;
         let body;
         if (uses) {
             const absolutePath = path.resolve(path.dirname(declaringPath), uses);
             body = { kind: "uses", path: uses, absolutePath };
         }
         else {
-            body = { kind: "inline", raw: compiledBody ?? extractBodyRaw(raw) };
+            body = { kind: "inline", raw: extractBodyRaw(raw) };
         }
         const entry = {
             id,
             declaringPath,
             body,
-            ...(needs !== undefined ? { needs } : {}),
-            ...(forkValue !== undefined ? { fork: forkValue } : {}),
-            ...(raw.clonable !== undefined ? { clonable: raw.clonable } : {}),
-            ...(raw.clone_cap !== undefined ? { clone_cap: raw.clone_cap } : {}),
             ...(policyOutcome.value.completion !== undefined
                 ? { completion: policyOutcome.value.completion }
                 : {}),
             ...(policyOutcome.value.recovery !== undefined
                 ? { recovery: policyOutcome.value.recovery }
                 : {}),
-            ...(feedbackLoop !== undefined
-                ? { feedback_loop: feedbackLoop }
-                : {}),
             ...(raw.replay_safe !== undefined
                 ? { replay_safe: raw.replay_safe }
                 : {}),
+            ...(route !== undefined ? { route } : {}),
+            ...(entryFlag !== undefined ? { entry: entryFlag } : {}),
             ...(skill !== undefined ? { skill } : {}),
             ...(mcp !== undefined ? { mcp } : {}),
+            ...(cloneCap !== undefined ? { clone_cap: cloneCap } : {}),
+            ...(cloneMode !== undefined ? { clone_mode: cloneMode } : {}),
         };
         const priorPath = normalized.find((e) => e.id === id)?.declaringPath;
         if (priorPath) {
@@ -284,15 +360,12 @@ export function normalizePipelineStageEntries(rawEntries, ctx) {
 export function toWiringRefs(entries) {
     return entries.map((entry) => ({
         id: entry.id,
-        ...(entry.needs !== undefined ? { needs: entry.needs } : {}),
-        ...(entry.fork !== undefined ? { fork: entry.fork } : {}),
-        ...(entry.clonable !== undefined ? { clonable: entry.clonable } : {}),
-        ...(entry.clone_cap !== undefined ? { clone_cap: entry.clone_cap } : {}),
         ...(entry.completion !== undefined ? { completion: entry.completion } : {}),
         ...(entry.recovery !== undefined ? { recovery: entry.recovery } : {}),
-        ...(entry.feedback_loop !== undefined
-            ? { feedback_loop: entry.feedback_loop }
-            : {}),
         ...(entry.replay_safe !== undefined ? { replay_safe: entry.replay_safe } : {}),
+        ...(entry.route !== undefined ? { route: entry.route } : {}),
+        ...(entry.entry !== undefined ? { entry: entry.entry } : {}),
+        ...(entry.clone_cap !== undefined ? { clone_cap: entry.clone_cap } : {}),
+        ...(entry.clone_mode !== undefined ? { clone_mode: entry.clone_mode } : {}),
     }));
 }

package/dist/config/parsePreEmitChecks.js

@@ -1,6 +1,6 @@
 /**
- * Parse IR `pre_emit_checks` (emit-phase). YAML `verify` emit items are compiled
- * onto this list in yamlDialect.ts before this parser runs.
+ * Parse IR `pre_emit_checks` (emit-phase). Target `verify` emit items are mapped
+ * in yamlDialect.ts then parsed here. Legacy YAML still authors this key.
  */
 import { STAGE_GATE_KINDS } from "../types/stage.js";
 import { loadFailure, loadSuccess } from "./loadOutcome.js";

package/dist/config/pipelineNeeds.d.ts

@@ -1,4 +1,4 @@
-import type { NeedTerminalState, PipelineNeedEdge, PipelineNeeds, PipelineStageRef, ResolvedPipelineStageNode } from "../types/pipeline.js";
+import type { NeedTerminalState, PipelineNeedEdge, PipelineNeedItem, PipelineNeeds, PipelineRoute, PipelineRouteForwardEntry, ResolvedPipelineStageNode } from "../types/pipeline.js";
 export declare const NEED_TERMINAL_STATES: readonly NeedTerminalState[];
 export declare function isNeedTerminalState(value: unknown): value is NeedTerminalState;
 export declare function parsePipelineNeeds(raw: unknown, stageId: string): {
@@ -8,7 +8,20 @@ export declare function parsePipelineNeeds(raw: unknown, stageId: string): {
     ok: false;
     message: string;
 };
-export declare function toNeedEdges(needs: PipelineStageRef["needs"]): PipelineNeedEdge[];
+export declare function toNeedEdges(needs: PipelineNeeds | PipelineNeedItem[] | undefined): PipelineNeedEdge[];
+export declare function toPipelineNeeds(edges: PipelineNeedEdge[]): PipelineNeeds;
+export declare function invertRouteToPredecessorEdges(sources: ReadonlyArray<{
+    id: string;
+    route?: PipelineRoute;
+}>): Map<string, PipelineNeedEdge[]>;
+export type OutboundRouteInversion = {
+    route?: PipelineRouteForwardEntry[];
+    entry?: boolean;
+};
+export declare function invertPredecessorEdgesToRoute(stages: ReadonlyArray<{
+    id: string;
+    needs?: PipelineNeeds;
+}>): Map<string, OutboundRouteInversion>;
 export declare function predecessorEdges(node: Pick<ResolvedPipelineStageNode, "needs" | "needsEdges">): PipelineNeedEdge[];
 export declare function hydrateResolvedNeeds(node: {
     needs?: unknown;

package/dist/config/pipelineNeeds.js

@@ -1,3 +1,4 @@
+import { parseRouteIf } from "./routeIf.js";
 export const NEED_TERMINAL_STATES = [
     "succeeded",
     "failed",
@@ -110,9 +111,81 @@ export function toNeedEdges(needs) {
     if (typeof needs === "string") {
         return needs ? [{ id: needs, on: ["succeeded"] }] : [];
     }
-    return needs.map((item) => typeof item === "string"
-        ? { id: item, on: ["succeeded"] }
-        : { id: item.id, on: item.on && item.on.length > 0 ? item.on : ["succeeded"] });
+    return needs.map((item) => {
+        if (typeof item === "string") {
+            return { id: item, on: ["succeeded"] };
+        }
+        const edge = {
+            id: item.id,
+            on: item.on && item.on.length > 0 ? item.on : ["succeeded"],
+        };
+        if ("if" in item && item.if !== undefined) {
+            edge.if = item.if;
+        }
+        return edge;
+    });
+}
+export function toPipelineNeeds(edges) {
+    const only = edges[0];
+    if (edges.length === 1 &&
+        only !== undefined &&
+        only.on.length === 1 &&
+        only.on[0] === "succeeded" &&
+        only.if === undefined) {
+        return only.id;
+    }
+    return edges;
+}
+function isForwardRouteEntry(entry) {
+    return !("type" in entry) || entry.type === undefined;
+}
+export function invertRouteToPredecessorEdges(sources) {
+    const inbound = new Map();
+    for (const source of sources) {
+        if (source.route === undefined)
+            continue;
+        for (const item of source.route) {
+            if (!isForwardRouteEntry(item))
+                continue;
+            const on = item.on === undefined
+                ? ["succeeded"]
+                : Array.isArray(item.on)
+                    ? item.on
+                    : [item.on];
+            const list = inbound.get(item.to) ?? [];
+            const edge = { id: source.id, on };
+            if (item.if !== undefined)
+                edge.if = item.if;
+            list.push(edge);
+            inbound.set(item.to, list);
+        }
+    }
+    return inbound;
+}
+export function invertPredecessorEdgesToRoute(stages) {
+    const result = new Map();
+    if (!stages.some((stage) => stage.needs !== undefined)) {
+        return result;
+    }
+    const outbound = new Map();
+    for (const stage of stages) {
+        if (stage.needs === undefined) {
+            result.set(stage.id, { entry: true });
+            continue;
+        }
+        for (const parent of toNeedEdges(stage.needs)) {
+            const list = outbound.get(parent.id) ?? [];
+            const entry = { to: stage.id, on: parent.on };
+            if (parent.if !== undefined)
+                entry.if = parent.if;
+            list.push(entry);
+            outbound.set(parent.id, list);
+        }
+    }
+    for (const [id, route] of outbound) {
+        result.set(id, { ...(result.get(id) ?? {}), route });
+    }
+    return result;
 }
 export function predecessorEdges(node) {
     if (node.needsEdges !== undefined)
@@ -131,7 +204,16 @@ export function hydrateResolvedNeeds(node) {
             const on = Array.isArray(item.on)
                 ? item.on.filter((state) => typeof state === "string" && NEED_TERMINAL_STATE_SET.has(state))
                 : ["succeeded"];
-            edges.push({ id: item.id, on: on.length > 0 ? on : ["succeeded"] });
+            const edge = {
+                id: item.id,
+                on: on.length > 0 ? on : ["succeeded"],
+            };
+            if (item.if !== undefined) {
+                const parsedIf = parseRouteIf(item.if, item.id, item.id);
+                if (parsedIf.ok)
+                    edge.if = parsedIf.value;
+            }
+            edges.push(edge);
         }
         if (typeof node.needs === "string") {
             return { needs: node.needs, needsEdges: edges };

package/dist/config/pipelineRoute.d.ts

@@ -0,0 +1,46 @@
+/**
+ * Parsing/normalization for the additive `route` stage field
+ * (docs/yaml-catalog.md). Mirrors the shape of
+ * pipelineNeeds.ts: `parsePipelineRoute` validates raw YAML/JSON input at
+ * parse time, `toRouteEdges`/`toRouteLoopEntries` normalize an already-typed
+ * `PipelineRoute` (used by the `resolvePipelineDagFromRefs` seam, which may
+ * receive un-validated refs built directly in TypeScript/tests).
+ *
+ * Ticket 01 handled forward entries (`{ to, on? }`) only. Ticket 03 adds the
+ * loop entry shape (`{ type: "loop", to, max_replays, on_max_replays,
+ * replay_session }`) — same replay-policy fields `FeedbackLoopConfig`
+ * carries today, `target` renamed to `to`. Loop entries never produce a
+ * forward edge: `toRouteEdges` skips them, `toRouteLoopEntries` extracts
+ * them for the resolver's replay validation/synthesis.
+ */
+import type { PipelineRoute, PipelineRouteEdge, PipelineRouteEntry, PipelineRouteLoopEntry } from "../types/pipeline.js";
+export declare function isLoopRouteEntry(entry: PipelineRouteEntry): entry is PipelineRouteLoopEntry;
+/**
+ * Parse+validate a raw `route:` field for one stage. Each item is either a
+ * forward entry (`{ to, on? }`) or a loop entry (`{ type: "loop", to,
+ * max_replays, on_max_replays, replay_session }`); entries are never bare
+ * strings (route entries are always structured objects, per the spec).
+ */
+export type ParsePipelineRouteFailure = {
+    ok: false;
+    message: string;
+    code?: "pipeline.route_if_invalid";
+};
+export declare function parsePipelineRoute(raw: unknown, stageId: string): {
+    ok: true;
+    value: PipelineRouteEntry[];
+} | ParsePipelineRouteFailure;
+/**
+ * Normalize an already-typed `route` value (as found on a `PipelineStageRef`,
+ * which may be hand-built in TypeScript and not have gone through
+ * `parsePipelineRoute`) into forward route edges with `on` always populated.
+ * Loop entries are skipped — they contribute no forward edge.
+ */
+export declare function toRouteEdges(route: PipelineRoute | undefined): PipelineRouteEdge[];
+/**
+ * Extract the loop entries from an already-typed `route` value (mirrors
+ * `toRouteEdges`, the forward-entry counterpart). Used by the resolver to
+ * validate replay policy and synthesize the legacy `feedback_loop` shape on
+ * the resolved DAG node.
+ */
+export declare function toRouteLoopEntries(route: PipelineRoute | undefined): PipelineRouteLoopEntry[];