stageflow 0.15.0 → 0.18.0

package/dist/config/pipelineRoute.js

@@ -0,0 +1,215 @@
+import { isNeedTerminalState } from "./pipelineNeeds.js";
+import { parseRouteIf } from "./routeIf.js";
+function isPlainObject(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function isForwardRouteEntry(entry) {
+    return !("type" in entry) || entry.type === undefined;
+}
+export function isLoopRouteEntry(entry) {
+    return "type" in entry && entry.type === "loop";
+}
+const ALLOWED_LOOP_ITEM_KEYS = new Set([
+    "type",
+    "to",
+    "max_replays",
+    "on_max_replays",
+    "replay_session",
+]);
+function parseRouteLoopEntry(item, stageId) {
+    if ("if" in item) {
+        return {
+            ok: false,
+            message: `stage "${stageId}": if is not allowed on a loop route entry`,
+            code: "pipeline.route_if_invalid",
+        };
+    }
+    for (const key of Object.keys(item)) {
+        if (!ALLOWED_LOOP_ITEM_KEYS.has(key)) {
+            return {
+                ok: false,
+                message: `stage "${stageId}": route item: unknown key "${key}"`,
+            };
+        }
+    }
+    if (typeof item.to !== "string" || !item.to) {
+        return {
+            ok: false,
+            message: `stage "${stageId}": route item must have a non-empty "to" stage id`,
+        };
+    }
+    if (!Number.isInteger(item.max_replays) || item.max_replays < 1) {
+        return {
+            ok: false,
+            message: `stage "${stageId}": route "${item.to}": max_replays must be a positive integer`,
+        };
+    }
+    if (item.on_max_replays !== "require_continue" && item.on_max_replays !== "wait_for_human") {
+        return {
+            ok: false,
+            message: `stage "${stageId}": route "${item.to}": on_max_replays must be "require_continue" or "wait_for_human"`,
+        };
+    }
+    if (item.replay_session !== "resume" && item.replay_session !== "new_session") {
+        return {
+            ok: false,
+            message: `stage "${stageId}": route "${item.to}": replay_session must be "resume" or "new_session"`,
+        };
+    }
+    return {
+        ok: true,
+        value: {
+            type: "loop",
+            to: item.to,
+            max_replays: item.max_replays,
+            on_max_replays: item.on_max_replays,
+            replay_session: item.replay_session,
+        },
+    };
+}
+function parseRouteOn(raw, stageId, targetId) {
+    if (raw === undefined) {
+        return { ok: true, value: ["succeeded"] };
+    }
+    const items = Array.isArray(raw) ? raw : [raw];
+    if (items.length === 0) {
+        return {
+            ok: false,
+            message: `stage "${stageId}": route "${targetId}": on must be a non-empty unique subset of succeeded, failed, skipped`,
+        };
+    }
+    const seen = new Set();
+    const on = [];
+    for (const item of items) {
+        if (typeof item !== "string" || !isNeedTerminalState(item) || seen.has(item)) {
+            return {
+                ok: false,
+                message: `stage "${stageId}": route "${targetId}": on must be a non-empty unique subset of succeeded, failed, skipped`,
+            };
+        }
+        seen.add(item);
+        on.push(item);
+    }
+    return { ok: true, value: on };
+}
+export function parsePipelineRoute(raw, stageId) {
+    if (!Array.isArray(raw)) {
+        return {
+            ok: false,
+            message: `stage "${stageId}": route must be a non-empty array`,
+        };
+    }
+    if (raw.length < 1) {
+        return {
+            ok: false,
+            message: `stage "${stageId}": route array must contain at least one item`,
+        };
+    }
+    const entries = [];
+    const seenTargets = new Set();
+    for (const item of raw) {
+        if (!isPlainObject(item)) {
+            return {
+                ok: false,
+                message: `stage "${stageId}": route item must be an object { to, on? }`,
+            };
+        }
+        if (item.type !== undefined && item.type !== "loop") {
+            return {
+                ok: false,
+                message: `stage "${stageId}": route item: type must be "loop" if present, got "${String(item.type)}"`,
+            };
+        }
+        if (item.type === "loop") {
+            const loopResult = parseRouteLoopEntry(item, stageId);
+            if (!loopResult.ok)
+                return loopResult;
+            if (seenTargets.has(loopResult.value.to)) {
+                return {
+                    ok: false,
+                    message: `stage "${stageId}": route contains duplicate target "${loopResult.value.to}"`,
+                };
+            }
+            seenTargets.add(loopResult.value.to);
+            entries.push(loopResult.value);
+            continue;
+        }
+        for (const key of Object.keys(item)) {
+            if (key !== "to" && key !== "on" && key !== "if") {
+                return {
+                    ok: false,
+                    message: `stage "${stageId}": route item: unknown key "${key}"`,
+                };
+            }
+        }
+        if (typeof item.to !== "string" || !item.to) {
+            return {
+                ok: false,
+                message: `stage "${stageId}": route item must have a non-empty "to" stage id`,
+            };
+        }
+        if (seenTargets.has(item.to)) {
+            return {
+                ok: false,
+                message: `stage "${stageId}": route contains duplicate target "${item.to}"`,
+            };
+        }
+        const onResult = parseRouteOn(item.on, stageId, item.to);
+        if (!onResult.ok)
+            return onResult;
+        let routeIf;
+        if (item.if !== undefined) {
+            const ifResult = parseRouteIf(item.if, stageId, item.to);
+            if (!ifResult.ok)
+                return ifResult;
+            if (onResult.value.length !== 1 || onResult.value[0] !== "succeeded") {
+                return {
+                    ok: false,
+                    message: `stage "${stageId}": route "${item.to}": if is only allowed with on succeeded`,
+                    code: "pipeline.route_if_invalid",
+                };
+            }
+            routeIf = ifResult.value;
+        }
+        seenTargets.add(item.to);
+        entries.push({
+            to: item.to,
+            on: onResult.value,
+            ...(routeIf !== undefined ? { if: routeIf } : {}),
+        });
+    }
+    return { ok: true, value: entries };
+}
+/**
+ * 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 function toRouteEdges(route) {
+    if (route === undefined)
+        return [];
+    const edges = [];
+    for (const item of route) {
+        if (!isForwardRouteEntry(item))
+            continue;
+        const on = item.on === undefined ? ["succeeded"] : Array.isArray(item.on) ? item.on : [item.on];
+        edges.push({
+            to: item.to,
+            on: on,
+            ...(item.if !== undefined ? { if: item.if } : {}),
+        });
+    }
+    return edges;
+}
+/**
+ * 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 function toRouteLoopEntries(route) {
+    if (route === undefined)
+        return [];
+    return route.filter(isLoopRouteEntry);
+}

package/dist/config/pipelineStageKeys.d.ts

@@ -11,5 +11,7 @@
 export declare const WIRING_KEYS: Set<string>;
 /** Stage body keys. Target: `io` / `verify`. IR/legacy: `payload_schema`, `pre_emit_checks`, `clone_input_schema`. */
 export declare const BODY_KEYS: Set<string>;
+/** Recognized only so catalog load can name the field and point at Clone Chain. */
+export declare const REJECTED_CLONE_PRODUCT_KEYS: Set<string>;
 export declare function isPipelineStageBodyKey(key: string): boolean;
 export declare function isAllowedPipelineStageEntryKey(key: string): boolean;

package/dist/config/pipelineStageKeys.js

@@ -13,13 +13,18 @@ export const WIRING_KEYS = new Set([
     "needs",
     "fork",
     "uses",
-    "clonable",
-    "clone_cap",
     "completion",
     "recovery",
     "on_verify_fail",
     "feedback_loop",
     "replay_safe",
+    /** Additive, alongside `needs`/`fork`/`feedback_loop` (see docs/yaml-catalog.md). */
+    "route",
+    "entry",
+    "route_select",
+    "allow_none",
+    "clone_cap",
+    "clone_mode",
 ]);
 /** Stage body keys. Target: `io` / `verify`. IR/legacy: `payload_schema`, `pre_emit_checks`, `clone_input_schema`. */
 export const BODY_KEYS = new Set([
@@ -29,16 +34,22 @@ export const BODY_KEYS = new Set([
     "gate_kinds",
     "pre_emit_checks",
     "clone_input_schema",
-    "clone_actions",
     "timeout_ms",
     "skill",
     "mcp",
     "io",
     "verify",
 ]);
+/** Recognized only so catalog load can name the field and point at Clone Chain. */
+export const REJECTED_CLONE_PRODUCT_KEYS = new Set([
+    "clonable",
+    "clone_actions",
+]);
 export function isPipelineStageBodyKey(key) {
     return BODY_KEYS.has(key);
 }
 export function isAllowedPipelineStageEntryKey(key) {
-    return WIRING_KEYS.has(key) || BODY_KEYS.has(key);
+    return (WIRING_KEYS.has(key) ||
+        BODY_KEYS.has(key) ||
+        REJECTED_CLONE_PRODUCT_KEYS.has(key));
 }

package/dist/config/printTargetYaml.js

@@ -112,19 +112,28 @@ export function buildVerifyItems(preEmit, afterChecks) {
     }
     return { ok: true, items: order.map((id) => byId.get(id)) };
 }
+const OBJECT_SCHEMA = { type: "object" };
 export function ioFromSchemas(stage) {
-    const io = {};
-    if (stage.clone_input_schema !== undefined) {
-        io.input = { schema: stage.clone_input_schema };
-    }
-    if (stage.payload_schema !== undefined) {
-        io.output = { schema: stage.payload_schema };
+    if (stage.clone_input_schema === undefined && stage.payload_schema === undefined) {
+        return undefined;
     }
-    return io.input !== undefined || io.output !== undefined ? io : undefined;
+    return {
+        input: { schema: stage.clone_input_schema ?? OBJECT_SCHEMA },
+        output: { schema: stage.payload_schema ?? OBJECT_SCHEMA },
+    };
 }
 export function ioFromRawDocument(raw) {
-    if (isPlainObject(raw.io))
-        return raw.io;
+    if (isPlainObject(raw.io)) {
+        const io = raw.io;
+        const input = isPlainObject(io.input) ? io.input : undefined;
+        const output = isPlainObject(io.output) ? io.output : undefined;
+        if (input?.schema === undefined && output?.schema === undefined)
+            return undefined;
+        return {
+            input: { schema: input?.schema ?? OBJECT_SCHEMA },
+            output: { schema: output?.schema ?? OBJECT_SCHEMA },
+        };
+    }
     return ioFromSchemas({
         payload_schema: raw.payload_schema,
         clone_input_schema: raw.clone_input_schema,
@@ -148,7 +157,6 @@ const STAGE_BODY_ORDER = [
     "io",
     "verify",
     "gate_kinds",
-    "clone_actions",
     "skill",
     "mcp",
 ];
@@ -159,8 +167,6 @@ const PIPELINE_WIRING_ORDER = [
     "mcp",
     "needs",
     "fork",
-    "clonable",
-    "clone_cap",
     "on_verify_fail",
     "feedback_loop",
     "replay_safe",

package/dist/config/resolveForkEmitContext.d.ts

@@ -4,5 +4,5 @@ export type ResolveCloneEmitOptions = {
     allowedActions?: CloneAction[];
     successorCloneInputSchemas?: Record<string, unknown>;
 };
-export declare function resolveCloneEmitContext(dag: ResolvedPipelineDag, stageId: string, options?: ResolveCloneEmitOptions): CloneEmitContext | undefined;
+export declare function resolveCloneEmitContext(_dag: ResolvedPipelineDag, _stageId: string, _options?: ResolveCloneEmitOptions): CloneEmitContext | undefined;
 export declare function resolveForkEmitContext(dag: ResolvedPipelineDag, stageId: string): ForkEmitContext | undefined;

package/dist/config/resolveForkEmitContext.js

@@ -1,34 +1,11 @@
-export function resolveCloneEmitContext(dag, stageId, options) {
-    const childIds = dag.childrenOf[stageId] ?? [];
-    const clonableSuccessors = [];
-    for (const childId of childIds) {
-        const node = dag.nodes.find((n) => n.id === childId);
-        if (node?.clonable === true) {
-            const cloneInputSchema = options?.successorCloneInputSchemas?.[childId];
-            clonableSuccessors.push({
-                successorId: childId,
-                cloneCap: node.clone_cap,
-                ...(cloneInputSchema !== undefined ? { cloneInputSchema } : {}),
-            });
-        }
-    }
-    if (clonableSuccessors.length === 0)
-        return undefined;
-    return {
-        clonableSuccessors,
-        ...(options?.allowedActions !== undefined
-            ? { allowedActions: options.allowedActions }
-            : {}),
-    };
+export function resolveCloneEmitContext(_dag, _stageId, _options) {
+    return undefined;
 }
 export function resolveForkEmitContext(dag, stageId) {
     const dagNode = dag.nodes.find((n) => n.id === stageId);
     if (!dagNode?.fork)
         return undefined;
-    const immediateSuccessorIds = (dag.childrenOf[stageId] ?? []).filter((childId) => {
-        const child = dag.nodes.find((n) => n.id === childId);
-        return child?.clonable !== true;
-    });
+    const immediateSuccessorIds = dag.childrenOf[stageId] ?? [];
     if (immediateSuccessorIds.length === 0)
         return undefined;
     return {

package/dist/config/resolvePipelineDag.d.ts

@@ -1,10 +1,8 @@
-import type { PipelineStageRef, PipelineStageYamlEntry, ResolvedPipelineDag, FeedbackLoopConfig } from "../types/pipeline.js";
+import type { PipelineStageRef, ResolvedPipelineDag } from "../types/pipeline.js";
 export type ResolvePipelineDagContext = {
     pipelineId: string;
     path: string;
 };
-export declare function parseFeedbackLoopConfig(value: unknown, stageId: string, ctx: ResolvePipelineDagContext): FeedbackLoopConfig;
-export declare function parsePipelineStageEntries(raw: unknown, ctx: ResolvePipelineDagContext): PipelineStageYamlEntry[];
 export declare function resolvePipelineDagFromRefs(refs: PipelineStageRef[], ctx: ResolvePipelineDagContext): {
     stages: string[];
     dag: ResolvedPipelineDag;