stageflow 0.9.0 → 0.12.0

package/dist/config/pipelineNeeds.d.ts

@@ -0,0 +1,19 @@
+import type { NeedTerminalState, PipelineNeedEdge, PipelineNeeds, PipelineStageRef, 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): {
+    ok: true;
+    value: PipelineNeeds;
+} | {
+    ok: false;
+    message: string;
+};
+export declare function toNeedEdges(needs: PipelineStageRef["needs"]): PipelineNeedEdge[];
+export declare function predecessorEdges(node: Pick<ResolvedPipelineStageNode, "needs" | "needsEdges">): PipelineNeedEdge[];
+export declare function hydrateResolvedNeeds(node: {
+    needs?: unknown;
+    needsEdges?: unknown;
+}): {
+    needs: string | null;
+    needsEdges: PipelineNeedEdge[];
+};

package/dist/config/pipelineNeeds.js

@@ -0,0 +1,151 @@
+export const NEED_TERMINAL_STATES = [
+    "succeeded",
+    "failed",
+    "skipped",
+];
+const NEED_TERMINAL_STATE_SET = new Set(NEED_TERMINAL_STATES);
+export function isNeedTerminalState(value) {
+    return typeof value === "string" && NEED_TERMINAL_STATE_SET.has(value);
+}
+function isPlainObject(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function parseNeedOn(raw, stageId, parentId) {
+    if (!Array.isArray(raw) || raw.length === 0) {
+        return {
+            ok: false,
+            message: `stage "${stageId}": needs "${parentId}": on must be a non-empty unique subset of succeeded, failed, skipped`,
+        };
+    }
+    const seen = new Set();
+    const on = [];
+    for (const item of raw) {
+        if (typeof item !== "string" || !NEED_TERMINAL_STATE_SET.has(item) || seen.has(item)) {
+            return {
+                ok: false,
+                message: `stage "${stageId}": needs "${parentId}": 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 parsePipelineNeeds(raw, stageId) {
+    if (typeof raw === "string") {
+        if (!raw) {
+            return { ok: false, message: `stage "${stageId}": needs must be a non-empty string` };
+        }
+        return { ok: true, value: raw };
+    }
+    if (!Array.isArray(raw)) {
+        return {
+            ok: false,
+            message: `stage "${stageId}": needs must be a non-empty string or an array of at least two items`,
+        };
+    }
+    if (raw.length < 2) {
+        return {
+            ok: false,
+            message: `stage "${stageId}": needs array must contain at least two items`,
+        };
+    }
+    const edges = [];
+    const seen = new Set();
+    for (const item of raw) {
+        if (typeof item === "string") {
+            if (!item) {
+                return {
+                    ok: false,
+                    message: `stage "${stageId}": needs item must be a stage id or { id, on }`,
+                };
+            }
+            if (seen.has(item)) {
+                return {
+                    ok: false,
+                    message: `stage "${stageId}": needs contains duplicate id "${item}"`,
+                };
+            }
+            seen.add(item);
+            edges.push({ id: item, on: ["succeeded"] });
+            continue;
+        }
+        if (!isPlainObject(item)) {
+            return {
+                ok: false,
+                message: `stage "${stageId}": needs item must be a stage id or { id, on }`,
+            };
+        }
+        for (const key of Object.keys(item)) {
+            if (key !== "id" && key !== "on") {
+                return {
+                    ok: false,
+                    message: `stage "${stageId}": needs item: unknown key "${key}"`,
+                };
+            }
+        }
+        if (typeof item.id !== "string" || !item.id) {
+            return {
+                ok: false,
+                message: `stage "${stageId}": needs item must be a stage id or { id, on }`,
+            };
+        }
+        if (seen.has(item.id)) {
+            return {
+                ok: false,
+                message: `stage "${stageId}": needs contains duplicate id "${item.id}"`,
+            };
+        }
+        const onResult = parseNeedOn(item.on, stageId, item.id);
+        if (!onResult.ok)
+            return onResult;
+        seen.add(item.id);
+        edges.push({ id: item.id, on: onResult.value });
+    }
+    return { ok: true, value: edges };
+}
+export function toNeedEdges(needs) {
+    if (needs === undefined)
+        return [];
+    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"] });
+}
+export function predecessorEdges(node) {
+    if (node.needsEdges !== undefined)
+        return node.needsEdges;
+    if (typeof node.needs === "string" && node.needs) {
+        return [{ id: node.needs, on: ["succeeded"] }];
+    }
+    return [];
+}
+export function hydrateResolvedNeeds(node) {
+    if (Array.isArray(node.needsEdges)) {
+        const edges = [];
+        for (const item of node.needsEdges) {
+            if (!isPlainObject(item) || typeof item.id !== "string" || !item.id)
+                continue;
+            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"] });
+        }
+        if (typeof node.needs === "string") {
+            return { needs: node.needs, needsEdges: edges };
+        }
+        if (node.needs === null) {
+            return { needs: null, needsEdges: edges };
+        }
+        return {
+            needs: edges.length === 1 ? edges[0].id : null,
+            needsEdges: edges,
+        };
+    }
+    if (typeof node.needs === "string" && node.needs) {
+        return { needs: node.needs, needsEdges: toNeedEdges(node.needs) };
+    }
+    return { needs: null, needsEdges: [] };
+}

package/dist/config/pipelineStageKeys.js

@@ -1,9 +1,24 @@
-export const WIRING_KEYS = new Set(["id", "needs", "fork", "uses", "clonable", "clone_cap"]);
+export const WIRING_KEYS = new Set([
+    "id",
+    "needs",
+    "fork",
+    "uses",
+    "clonable",
+    "clone_cap",
+    "completion",
+    "recovery",
+    "feedback_loop",
+    "replay_safe",
+]);
 export const BODY_KEYS = new Set([
     "system_prompt",
     "model",
     "payload_schema",
     "gate_kinds",
+    "pre_emit_checks",
+    "clone_input_schema",
+    "clone_actions",
+    "timeout_ms",
     "skill",
 ]);
 export function isPipelineStageBodyKey(key) {

package/dist/config/resolveForkEmitContext.d.ts

@@ -1,4 +1,8 @@
-import type { CloneEmitContext, ForkEmitContext } from "../types/forkChoice.js";
+import type { CloneAction, CloneEmitContext, ForkEmitContext } from "../types/forkChoice.js";
 import type { ResolvedPipelineDag } from "../types/pipeline.js";
-export declare function resolveCloneEmitContext(dag: ResolvedPipelineDag, stageId: string): CloneEmitContext | undefined;
+export type ResolveCloneEmitOptions = {
+    allowedActions?: CloneAction[];
+    successorCloneInputSchemas?: Record<string, unknown>;
+};
+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,18 +1,25 @@
-export function resolveCloneEmitContext(dag, stageId) {
+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 };
+    return {
+        clonableSuccessors,
+        ...(options?.allowedActions !== undefined
+            ? { allowedActions: options.allowedActions }
+            : {}),
+    };
 }
 export function resolveForkEmitContext(dag, stageId) {
     const dagNode = dag.nodes.find((n) => n.id === stageId);

package/dist/config/resolvePipelineDag.d.ts

@@ -1,8 +1,9 @@
-import type { PipelineStageRef, PipelineStageYamlEntry, ResolvedPipelineDag } from "../types/pipeline.js";
+import type { PipelineStageRef, PipelineStageYamlEntry, ResolvedPipelineDag, FeedbackLoopConfig } 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[];

package/dist/config/resolvePipelineDag.js

@@ -1,4 +1,6 @@
 import { isAllowedPipelineStageEntryKey } from "./pipelineStageKeys.js";
+import { parseExecutionPolicy } from "./parseCompletionContract.js";
+import { parsePipelineNeeds, predecessorEdges, toNeedEdges } from "./pipelineNeeds.js";
 const ALLOWED_FORK_KEYS = new Set(["select", "allow_none"]);
 function pipelineLabel(ctx) {
     return `Pipeline ${ctx.pipelineId} (${ctx.path})`;
@@ -9,6 +11,44 @@ function formatError(ctx, message) {
 function isPlainObject(value) {
     return typeof value === "object" && value !== null && !Array.isArray(value);
 }
+const ALLOWED_FEEDBACK_LOOP_KEYS = new Set([
+    "target",
+    "max_replays",
+    "on_max_replays",
+    "replay_session",
+]);
+export function parseFeedbackLoopConfig(value, stageId, ctx) {
+    if (!isPlainObject(value)) {
+        throw new Error(formatError(ctx, `stage "${stageId}": feedback_loop must be an object`));
+    }
+    for (const key of Object.keys(value)) {
+        if (!ALLOWED_FEEDBACK_LOOP_KEYS.has(key)) {
+            throw new Error(formatError(ctx, `stage "${stageId}": feedback_loop: unknown key "${key}"`));
+        }
+    }
+    if (Array.isArray(value.target)) {
+        throw new Error(formatError(ctx, `stage "${stageId}": feedback_loop.target must be a single stage id string, not an array`));
+    }
+    if (typeof value.target !== "string" || value.target.trim() === "") {
+        throw new Error(formatError(ctx, `stage "${stageId}": feedback_loop.target must be a non-empty stage id`));
+    }
+    if (!Number.isInteger(value.max_replays) || value.max_replays < 1) {
+        throw new Error(formatError(ctx, `stage "${stageId}": feedback_loop.max_replays must be a positive integer`));
+    }
+    if (value.on_max_replays !== "require_continue" &&
+        value.on_max_replays !== "wait_for_human") {
+        throw new Error(formatError(ctx, `stage "${stageId}": feedback_loop.on_max_replays must be "require_continue" or "wait_for_human"`));
+    }
+    if (value.replay_session !== "resume" && value.replay_session !== "new_session") {
+        throw new Error(formatError(ctx, `stage "${stageId}": feedback_loop.replay_session must be "resume" or "new_session"`));
+    }
+    return {
+        target: value.target,
+        max_replays: value.max_replays,
+        on_max_replays: value.on_max_replays,
+        replay_session: value.replay_session,
+    };
+}
 export function parsePipelineStageEntries(raw, ctx) {
     if (!Array.isArray(raw)) {
         throw new Error(formatError(ctx, "stages[] is required"));
@@ -53,41 +93,69 @@ export function parsePipelineStageEntries(raw, ctx) {
             ...(entry.clonable !== undefined ? { clonable: entry.clonable } : {}),
             ...(entry.clone_cap !== undefined ? { clone_cap: entry.clone_cap } : {}),
         };
+        const policyOutcome = parseExecutionPolicy(entry, entry.id);
+        if (!policyOutcome.ok) {
+            throw new Error(formatError(ctx, policyOutcome.issues[0]?.message ?? "invalid execution policy"));
+        }
+        const policyFields = {
+            ...(policyOutcome.value.completion !== undefined
+                ? { completion: policyOutcome.value.completion }
+                : {}),
+            ...(policyOutcome.value.recovery !== undefined
+                ? { recovery: policyOutcome.value.recovery }
+                : {}),
+        };
+        const feedbackLoopFields = entry.feedback_loop !== undefined
+            ? { feedback_loop: parseFeedbackLoopConfig(entry.feedback_loop, entry.id, ctx) }
+            : {};
+        if (entry.replay_safe !== undefined && typeof entry.replay_safe !== "boolean") {
+            throw new Error(formatError(ctx, `stage "${entry.id}": replay_safe must be a boolean`));
+        }
+        const replaySafetyFields = entry.replay_safe !== undefined ? { replay_safe: entry.replay_safe } : {};
         if (entry.needs === undefined) {
             entries.push({
                 id: entry.id,
                 ...(forkValue !== undefined ? { fork: forkValue } : {}),
                 ...clonableFields,
+                ...policyFields,
+                ...feedbackLoopFields,
+                ...replaySafetyFields,
             });
             continue;
         }
-        if (Array.isArray(entry.needs)) {
-            if (entry.needs.length > 1) {
-                throw new Error(formatError(ctx, `stage "${entry.id}": fan-in not supported; needs must be a single stage id`));
-            }
-            throw new Error(formatError(ctx, `stage "${entry.id}": needs must be a string, not an array`));
-        }
-        if (typeof entry.needs !== "string" || !entry.needs) {
-            throw new Error(formatError(ctx, `stage "${entry.id}": needs must be a non-empty string`));
+        const parsedNeeds = parsePipelineNeeds(entry.needs, entry.id);
+        if (!parsedNeeds.ok) {
+            throw new Error(formatError(ctx, parsedNeeds.message));
         }
         entries.push({
             id: entry.id,
-            needs: entry.needs,
+            needs: parsedNeeds.value,
             ...(forkValue !== undefined ? { fork: forkValue } : {}),
             ...clonableFields,
+            ...policyFields,
+            ...feedbackLoopFields,
+            ...replaySafetyFields,
         });
     }
     return entries;
 }
 function normalizeToEdges(entries) {
-    return entries.map((entry, index) => ({
-        id: entry.id,
-        needs: entry.needs ?? null,
-        stageIndex: index,
-        ...(entry.fork !== undefined ? { fork: entry.fork } : {}),
-        ...(entry.clonable !== undefined ? { clonable: entry.clonable } : {}),
-        ...(entry.clone_cap !== undefined ? { clone_cap: entry.clone_cap } : {}),
-    }));
+    return entries.map((entry, index) => {
+        const needsEdges = toNeedEdges(entry.needs);
+        return {
+            id: entry.id,
+            needs: needsEdges.length === 1 ? needsEdges[0].id : null,
+            needsEdges,
+            stageIndex: index,
+            ...(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 } : {}),
+        };
+    });
 }
 function detectDuplicateIds(edges, ctx) {
     const seen = new Set();
@@ -101,8 +169,10 @@ function detectDuplicateIds(edges, ctx) {
 function validateNeedsTargets(edges, ctx) {
     const declared = new Set(edges.map((edge) => edge.id));
     for (const edge of edges) {
-        if (edge.needs !== null && !declared.has(edge.needs)) {
-            throw new Error(formatError(ctx, `stage "${edge.id}" has unknown needs "${edge.needs}"`));
+        for (const parent of edge.needsEdges) {
+            if (!declared.has(parent.id)) {
+                throw new Error(formatError(ctx, `stage "${edge.id}" has unknown needs "${parent.id}"`));
+            }
         }
     }
 }
@@ -114,10 +184,10 @@ function detectCycle(edges, ctx) {
         children.set(edge.id, []);
     }
     for (const edge of edges) {
-        if (edge.needs === null)
-            continue;
-        indegree.set(edge.id, (indegree.get(edge.id) ?? 0) + 1);
-        children.get(edge.needs)?.push(edge.id);
+        for (const parent of edge.needsEdges) {
+            indegree.set(edge.id, (indegree.get(edge.id) ?? 0) + 1);
+            children.get(parent.id)?.push(edge.id);
+        }
     }
     const queue = [];
     for (const [id, degree] of indegree) {
@@ -140,19 +210,31 @@ function detectCycle(edges, ctx) {
     }
 }
 function computeAncestors(edges) {
-    const needsById = new Map(edges.map((edge) => [edge.id, edge.needs]));
+    const parentsById = new Map(edges.map((edge) => [edge.id, edge.needsEdges]));
     const ancestorsById = new Map();
     function ancestorsFor(id) {
         const cached = ancestorsById.get(id);
         if (cached)
             return cached;
-        const needs = needsById.get(id) ?? null;
-        if (needs === null) {
+        const parents = parentsById.get(id) ?? [];
+        if (parents.length === 0) {
             ancestorsById.set(id, []);
             return [];
         }
-        const parentAncestors = ancestorsFor(needs);
-        const ancestors = [...parentAncestors, needs];
+        const seen = new Set();
+        const ancestors = [];
+        for (const parent of parents) {
+            for (const ancestor of ancestorsFor(parent.id)) {
+                if (seen.has(ancestor))
+                    continue;
+                seen.add(ancestor);
+                ancestors.push(ancestor);
+            }
+            if (!seen.has(parent.id)) {
+                seen.add(parent.id);
+                ancestors.push(parent.id);
+            }
+        }
         ancestorsById.set(id, ancestors);
         return ancestors;
     }
@@ -170,16 +252,16 @@ function topologicalSort(edges) {
         children.set(edge.id, []);
     }
     for (const edge of edges) {
-        if (edge.needs === null)
-            continue;
-        indegree.set(edge.id, (indegree.get(edge.id) ?? 0) + 1);
-        children.get(edge.needs)?.push(edge.id);
+        for (const parent of edge.needsEdges) {
+            indegree.set(edge.id, (indegree.get(edge.id) ?? 0) + 1);
+            children.get(parent.id)?.push(edge.id);
+        }
     }
     for (const [, childIds] of children) {
         childIds.sort((a, b) => (byId.get(a)?.stageIndex ?? 0) - (byId.get(b)?.stageIndex ?? 0));
     }
     const roots = edges
-        .filter((edge) => edge.needs === null)
+        .filter((edge) => edge.needsEdges.length === 0)
         .sort((a, b) => a.stageIndex - b.stageIndex)
         .map((edge) => edge.id);
     const sorted = [];
@@ -206,8 +288,8 @@ function buildResolvedPipelineDag(edges) {
         childrenOf[edge.id] = [];
     }
     for (const edge of edges) {
-        if (edge.needs !== null) {
-            childrenOf[edge.needs].push(edge.id);
+        for (const parent of edge.needsEdges) {
+            childrenOf[parent.id].push(edge.id);
         }
     }
     for (const id of Object.keys(childrenOf)) {
@@ -215,12 +297,13 @@ function buildResolvedPipelineDag(edges) {
             (edges.find((edge) => edge.id === b)?.stageIndex ?? 0));
     }
     const roots = edges
-        .filter((edge) => edge.needs === null)
+        .filter((edge) => edge.needsEdges.length === 0)
         .sort((a, b) => a.stageIndex - b.stageIndex)
         .map((edge) => edge.id);
     const nodes = sortedEdges.map((edge) => ({
         id: edge.id,
         needs: edge.needs,
+        needsEdges: edge.needsEdges,
         ancestors: ancestorsById.get(edge.id) ?? [],
         stageIndex: edge.stageIndex,
         ...(edge.fork !== undefined
@@ -229,6 +312,10 @@ function buildResolvedPipelineDag(edges) {
         ...(edge.clonable === true
             ? { clonable: true, clone_cap: edge.clone_cap ?? 5 }
             : {}),
+        ...(edge.completion !== undefined ? { completion: edge.completion } : {}),
+        ...(edge.recovery !== undefined ? { recovery: edge.recovery } : {}),
+        ...(edge.feedback_loop !== undefined ? { feedback_loop: edge.feedback_loop } : {}),
+        ...(edge.replay_safe !== undefined ? { replay_safe: edge.replay_safe } : {}),
     }));
     return { nodes, roots, childrenOf };
 }
@@ -259,6 +346,34 @@ function validateClonableFields(edges, dag, ctx) {
         }
     }
 }
+function validateFeedbackLoopFields(dag, ctx) {
+    const byId = new Map(dag.nodes.map((node) => [node.id, node]));
+    for (const source of dag.nodes) {
+        const policy = source.feedback_loop;
+        if (!policy)
+            continue;
+        if (source.clonable === true) {
+            throw new Error(formatError(ctx, `stage "${source.id}": feedback_loop source cannot be clonable`));
+        }
+        const targetId = policy.target;
+        const target = byId.get(targetId);
+        if (!target) {
+            throw new Error(formatError(ctx, `stage "${source.id}": feedback_loop target "${targetId}" is not declared`));
+        }
+        if (!source.ancestors.includes(targetId)) {
+            throw new Error(formatError(ctx, `stage "${source.id}": feedback_loop target "${targetId}" must be an earlier ancestor`));
+        }
+        if (target.clonable === true) {
+            throw new Error(formatError(ctx, `stage "${source.id}": feedback_loop target "${targetId}" cannot be clonable`));
+        }
+        const targetIndex = source.ancestors.indexOf(targetId);
+        const route = [...source.ancestors.slice(targetIndex), source.id];
+        const unsafeStage = route.find((stageId) => byId.get(stageId)?.replay_safe === false);
+        if (unsafeStage !== undefined) {
+            throw new Error(formatError(ctx, `stage "${source.id}": feedback_loop target "${targetId}" replays replay_safe: false stage "${unsafeStage}"`));
+        }
+    }
+}
 export function resolvePipelineDagFromRefs(refs, ctx) {
     const edges = normalizeToEdges(refs);
     detectDuplicateIds(edges, ctx);
@@ -271,6 +386,7 @@ export function resolvePipelineDagFromRefs(refs, ctx) {
     const dag = buildResolvedPipelineDag(edges);
     validateForkFields(edges, dag, ctx);
     validateClonableFields(edges, dag, ctx);
+    validateFeedbackLoopFields(dag, ctx);
     return { stages, dag };
 }
 export function resolvePipelineDag(rawStages, ctx) {
@@ -293,12 +409,40 @@ export function areResolvedDagsEquivalent(a, b) {
         const nodeB = byIdB.get(id);
         if (nodeA.needs !== nodeB.needs)
             return false;
+        const edgesA = predecessorEdges(nodeA);
+        const edgesB = predecessorEdges(nodeB);
+        if (edgesA.length !== edgesB.length)
+            return false;
+        for (let i = 0; i < edgesA.length; i++) {
+            if (edgesA[i].id !== edgesB[i].id)
+                return false;
+            if (edgesA[i].on.length !== edgesB[i].on.length)
+                return false;
+            for (let j = 0; j < edgesA[i].on.length; j++) {
+                if (edgesA[i].on[j] !== edgesB[i].on[j])
+                    return false;
+            }
+        }
         if (nodeA.ancestors.length !== nodeB.ancestors.length)
             return false;
         for (let i = 0; i < nodeA.ancestors.length; i++) {
             if (nodeA.ancestors[i] !== nodeB.ancestors[i])
                 return false;
         }
+        if ((nodeA.replay_safe ?? true) !== (nodeB.replay_safe ?? true))
+            return false;
+        if (nodeA.feedback_loop?.max_replays !== nodeB.feedback_loop?.max_replays) {
+            return false;
+        }
+        if (nodeA.feedback_loop?.on_max_replays !==
+            nodeB.feedback_loop?.on_max_replays) {
+            return false;
+        }
+        if (nodeA.feedback_loop?.replay_session !== nodeB.feedback_loop?.replay_session) {
+            return false;
+        }
+        if (nodeA.feedback_loop?.target !== nodeB.feedback_loop?.target)
+            return false;
     }
     return true;
 }
@@ -321,9 +465,8 @@ export function extractPipelineStageIds(rawStages) {
         if (typeof entry.id !== "string" || !entry.id)
             return null;
         if (entry.needs !== undefined) {
-            if (Array.isArray(entry.needs))
-                return null;
-            if (typeof entry.needs !== "string" || !entry.needs)
+            const parsedNeeds = parsePipelineNeeds(entry.needs, entry.id);
+            if (!parsedNeeds.ok)
                 return null;
         }
         stageIds.push(entry.id);

package/dist/config/validateCatalog.d.ts

@@ -2,7 +2,7 @@ import type { LoadedPipeline } from "../types/pipeline.js";
 import type { LoadIssue } from "./loadOutcome.js";
 export type ValidationSeverity = "error" | "warning";
 export type ValidationCategory = "pipeline" | "stage" | "catalog" | "task";
-export type ValidationFindingCode = "pipeline.invalid_shape" | "pipeline.dag_error" | "pipeline.missing_stage" | "pipeline.load_error" | "pipeline.string_stage_ref" | "pipeline.stage_uses_inline_conflict" | "pipeline.stage_missing_body" | "pipeline.stage_id_mismatch" | "pipeline.include_cycle" | "pipeline.include_invalid" | "pipeline.include_duplicate_stage" | "stage.invalid_shape" | "stage.invalid_payload_schema" | "stage.invalid_gate_kinds" | "stage.invalid_skill" | "stage.load_error" | "stage.id_filename_mismatch" | "task.invalid_shape" | "task.load_error" | "catalog.duplicate_pipeline_id" | "catalog.manifest_missing" | "catalog.manifest_invalid" | "catalog.empty_catalog" | "catalog.manifest_load_error";
+export type ValidationFindingCode = "pipeline.invalid_shape" | "pipeline.dag_error" | "pipeline.missing_stage" | "pipeline.load_error" | "pipeline.string_stage_ref" | "pipeline.stage_uses_inline_conflict" | "pipeline.stage_missing_body" | "pipeline.stage_id_mismatch" | "pipeline.invalid_completion" | "pipeline.invalid_recovery" | "pipeline.include_cycle" | "pipeline.include_invalid" | "pipeline.include_duplicate_stage" | "pipeline.invalid_agent" | "stage.invalid_shape" | "stage.invalid_payload_schema" | "stage.invalid_clone_input_schema" | "stage.invalid_clone_actions" | "stage.invalid_gate_kinds" | "stage.invalid_pre_emit_checks" | "stage.invalid_timeout_ms" | "stage.invalid_skill" | "stage.invalid_agent" | "stage.load_error" | "stage.id_filename_mismatch" | "task.invalid_shape" | "task.load_error" | "catalog.duplicate_pipeline_id" | "catalog.manifest_missing" | "catalog.manifest_invalid" | "catalog.empty_catalog" | "catalog.manifest_load_error";
 export type ValidationFinding = {
     severity: ValidationSeverity;
     code: ValidationFindingCode | string;

package/dist/config/validateCompletionContract.d.ts

@@ -0,0 +1,4 @@
+import type { CompletionContract } from "../types/completion.js";
+import type { StageConfig } from "../types/stage.js";
+import { type LoadOutcome } from "./loadOutcome.js";
+export declare function validateCompletionContractForStage(stage: StageConfig, completion: CompletionContract | undefined): LoadOutcome<void>;