stageflow 0.9.0 → 0.13.0

package/dist/config/parseCompletionContract.js

@@ -0,0 +1,218 @@
+import path from "node:path";
+import { STAGE_GATE_KINDS } from "../types/stage.js";
+import { loadFailure, loadSuccess } from "./loadOutcome.js";
+function isPlainObject(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function failure(stageId, field, message) {
+    return loadFailure([
+        {
+            code: field === "completion"
+                ? "pipeline.invalid_completion"
+                : "pipeline.invalid_recovery",
+            message: `Stage "${stageId}" ${field}: ${message}`,
+            category: "pipeline",
+        },
+    ]);
+}
+function hasOnlyKeys(value, allowed) {
+    return Object.keys(value).find((key) => !allowed.includes(key));
+}
+function isPositiveInteger(value) {
+    return typeof value === "number" && Number.isSafeInteger(value) && value > 0;
+}
+function isGateKind(value) {
+    return typeof value === "string" && STAGE_GATE_KINDS.includes(value);
+}
+function parsePathFields(value) {
+    if (value === undefined)
+        return undefined;
+    if (!Array.isArray(value) ||
+        value.length === 0 ||
+        !value.every((item) => typeof item === "string" && item.trim() !== "")) {
+        return undefined;
+    }
+    const fields = value.map((item) => item.trim());
+    return new Set(fields).size === fields.length ? fields : undefined;
+}
+function parseCheck(raw, stageId, index) {
+    if (!isPlainObject(raw)) {
+        return failure(stageId, "completion", `checks[${index}] must be an object`);
+    }
+    if (typeof raw.id !== "string" || raw.id.trim() === "") {
+        return failure(stageId, "completion", `checks[${index}].id must be a non-empty string`);
+    }
+    if (typeof raw.type !== "string") {
+        return failure(stageId, "completion", `checks[${index}].type must be a string`);
+    }
+    const id = raw.id.trim();
+    if (raw.type === "command") {
+        const unknown = hasOnlyKeys(raw, ["id", "type", "run", "cwd", "timeout_ms"]);
+        if (unknown)
+            return failure(stageId, "completion", `checks[${index}]: unknown key "${unknown}"`);
+        if (typeof raw.run !== "string" || raw.run.trim() === "") {
+            return failure(stageId, "completion", `checks[${index}] command check requires a non-empty run`);
+        }
+        if (raw.cwd !== undefined && (typeof raw.cwd !== "string" || raw.cwd.trim() === "")) {
+            return failure(stageId, "completion", `checks[${index}].cwd must be a non-empty string`);
+        }
+        if (raw.timeout_ms !== undefined && !isPositiveInteger(raw.timeout_ms)) {
+            return failure(stageId, "completion", `checks[${index}].timeout_ms must be a positive integer`);
+        }
+        return loadSuccess({
+            id,
+            type: "command",
+            run: raw.run.trim(),
+            ...(typeof raw.cwd === "string" ? { cwd: raw.cwd.trim() } : {}),
+            ...(typeof raw.timeout_ms === "number" ? { timeout_ms: raw.timeout_ms } : {}),
+        });
+    }
+    if (raw.type === "artifact") {
+        const unknown = hasOnlyKeys(raw, ["id", "type", "path", "nonempty"]);
+        if (unknown)
+            return failure(stageId, "completion", `checks[${index}]: unknown key "${unknown}"`);
+        if (typeof raw.path !== "string" || raw.path.trim() === "") {
+            return failure(stageId, "completion", `checks[${index}] artifact check requires a non-empty path`);
+        }
+        const artifactPath = raw.path.trim();
+        const normalizedPath = path.normalize(artifactPath);
+        if (path.isAbsolute(artifactPath) ||
+            normalizedPath === ".." ||
+            normalizedPath.startsWith(`..${path.sep}`)) {
+            return failure(stageId, "completion", `checks[${index}] artifact path must stay inside the attempt artifact directory`);
+        }
+        if (raw.nonempty !== undefined && typeof raw.nonempty !== "boolean") {
+            return failure(stageId, "completion", `checks[${index}].nonempty must be a boolean`);
+        }
+        return loadSuccess({
+            id,
+            type: "artifact",
+            path: artifactPath,
+            ...(typeof raw.nonempty === "boolean" ? { nonempty: raw.nonempty } : {}),
+        });
+    }
+    if (raw.type === "checklist") {
+        const unknown = hasOnlyKeys(raw, ["id", "type", "items"]);
+        if (unknown)
+            return failure(stageId, "completion", `checks[${index}]: unknown key "${unknown}"`);
+        if (!Array.isArray(raw.items) ||
+            raw.items.length === 0 ||
+            !raw.items.every((item) => typeof item === "string" && item.trim() !== "")) {
+            return failure(stageId, "completion", `checks[${index}] checklist requires a non-empty items array of strings`);
+        }
+        const items = raw.items.map((item) => item.trim());
+        if (new Set(items).size !== items.length) {
+            return failure(stageId, "completion", `checks[${index}] checklist items must be unique`);
+        }
+        return loadSuccess({ id, type: "checklist", items });
+    }
+    if (raw.type === "payload_schema") {
+        const unknown = hasOnlyKeys(raw, ["id", "type"]);
+        if (unknown)
+            return failure(stageId, "completion", `checks[${index}]: unknown key "${unknown}"`);
+        return loadSuccess({ id, type: "payload_schema" });
+    }
+    if (raw.type === "gate") {
+        const unknown = hasOnlyKeys(raw, ["id", "type", "kind"]);
+        if (unknown)
+            return failure(stageId, "completion", `checks[${index}]: unknown key "${unknown}"`);
+        if (!isGateKind(raw.kind)) {
+            return failure(stageId, "completion", `checks[${index}].kind must be one of ${STAGE_GATE_KINDS.join(", ")}`);
+        }
+        return loadSuccess({ id, type: "gate", kind: raw.kind });
+    }
+    if (raw.type === "checkout_changes") {
+        const unknown = hasOnlyKeys(raw, ["id", "type", "path_fields"]);
+        if (unknown)
+            return failure(stageId, "completion", `checks[${index}]: unknown key "${unknown}"`);
+        const pathFields = parsePathFields(raw.path_fields);
+        if (raw.path_fields !== undefined && pathFields === undefined) {
+            return failure(stageId, "completion", `checks[${index}].path_fields must be a unique, non-empty array of strings`);
+        }
+        return loadSuccess({
+            id,
+            type: "checkout_changes",
+            ...(pathFields !== undefined ? { path_fields: pathFields } : {}),
+        });
+    }
+    return failure(stageId, "completion", `checks[${index}].type "${raw.type}" is unsupported`);
+}
+function parseCompletion(raw, stageId) {
+    if (raw === undefined)
+        return loadSuccess(undefined);
+    if (!isPlainObject(raw))
+        return failure(stageId, "completion", "must be an object");
+    const unknown = hasOnlyKeys(raw, ["mode", "checks"]);
+    if (unknown)
+        return failure(stageId, "completion", `unknown key "${unknown}"`);
+    if (raw.mode !== undefined && raw.mode !== "all") {
+        return failure(stageId, "completion", 'mode must be "all"');
+    }
+    if (!Array.isArray(raw.checks) || raw.checks.length === 0) {
+        return failure(stageId, "completion", "checks must be a non-empty array");
+    }
+    const checks = [];
+    for (let index = 0; index < raw.checks.length; index++) {
+        const outcome = parseCheck(raw.checks[index], stageId, index);
+        if (!outcome.ok)
+            return outcome;
+        checks.push(outcome.value);
+    }
+    const duplicates = checks.find((check, index) => checks.findIndex((item) => item.id === check.id) !== index);
+    if (duplicates)
+        return failure(stageId, "completion", `check id "${duplicates.id}" is duplicated`);
+    return loadSuccess({ mode: "all", checks });
+}
+function parseRecovery(raw, stageId, hasCompletion) {
+    if (raw === undefined)
+        return loadSuccess(undefined);
+    if (!hasCompletion)
+        return failure(stageId, "recovery", "requires a completion contract");
+    if (!isPlainObject(raw))
+        return failure(stageId, "recovery", "must be an object");
+    const unknown = hasOnlyKeys(raw, ["mode", "max_attempts", "retry_safety", "include_failed_checks"]);
+    if (unknown)
+        return failure(stageId, "recovery", `unknown key "${unknown}"`);
+    if (raw.mode !== "repair" && raw.mode !== "manual") {
+        return failure(stageId, "recovery", 'mode must be "repair" or "manual"');
+    }
+    if (raw.retry_safety !== "idempotent" && raw.retry_safety !== "side_effecting") {
+        return failure(stageId, "recovery", 'retry_safety must be "idempotent" or "side_effecting"');
+    }
+    if (raw.include_failed_checks !== undefined && typeof raw.include_failed_checks !== "boolean") {
+        return failure(stageId, "recovery", "include_failed_checks must be a boolean");
+    }
+    if (raw.mode === "repair") {
+        if (!isPositiveInteger(raw.max_attempts)) {
+            return failure(stageId, "recovery", "repair requires max_attempts to be a positive integer");
+        }
+        if (raw.retry_safety !== "idempotent") {
+            return failure(stageId, "recovery", "automatic repair requires retry_safety: idempotent");
+        }
+        return loadSuccess({
+            mode: "repair",
+            max_attempts: raw.max_attempts,
+            retry_safety: "idempotent",
+            include_failed_checks: raw.include_failed_checks ?? true,
+        });
+    }
+    return loadSuccess({
+        mode: "manual",
+        retry_safety: raw.retry_safety,
+        ...(typeof raw.include_failed_checks === "boolean"
+            ? { include_failed_checks: raw.include_failed_checks }
+            : {}),
+    });
+}
+export function parseExecutionPolicy(raw, stageId) {
+    const completion = parseCompletion(raw.completion, stageId);
+    if (!completion.ok)
+        return completion;
+    const recovery = parseRecovery(raw.recovery, stageId, completion.value !== undefined);
+    if (!recovery.ok)
+        return recovery;
+    return loadSuccess({
+        ...(completion.value !== undefined ? { completion: completion.value } : {}),
+        ...(recovery.value !== undefined ? { recovery: recovery.value } : {}),
+    });
+}

package/dist/config/parsePreEmitChecks.d.ts

@@ -0,0 +1,3 @@
+import type { PreEmitCheck } from "../types/preEmitCheck.js";
+import { type LoadOutcome } from "./loadOutcome.js";
+export declare function parsePreEmitChecks(raw: unknown, label: string): LoadOutcome<PreEmitCheck[] | undefined>;

package/dist/config/parsePreEmitChecks.js

@@ -0,0 +1,65 @@
+import { STAGE_GATE_KINDS } from "../types/stage.js";
+import { loadFailure, loadSuccess } from "./loadOutcome.js";
+function isPlainObject(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function isGateKind(value) {
+    return typeof value === "string" && STAGE_GATE_KINDS.includes(value);
+}
+function failure(label, message) {
+    return loadFailure([
+        {
+            code: "stage.invalid_pre_emit_checks",
+            message: `Invalid stage ${label}: pre_emit_checks ${message}`,
+            category: "stage",
+        },
+    ]);
+}
+function parsePreEmitCheck(raw, label, index) {
+    if (!isPlainObject(raw)) {
+        return failure(label, `[${index}] must be an object`);
+    }
+    if (typeof raw.id !== "string" || raw.id.trim() === "") {
+        return failure(label, `[${index}].id must be a non-empty string`);
+    }
+    if (typeof raw.type !== "string") {
+        return failure(label, `[${index}].type must be a string`);
+    }
+    const id = raw.id.trim();
+    if (raw.type === "gate") {
+        if (!isGateKind(raw.kind)) {
+            return failure(label, `[${index}].kind must be one of ${STAGE_GATE_KINDS.join(", ")}`);
+        }
+        return loadSuccess({ id, type: "gate", kind: raw.kind });
+    }
+    if (raw.type === "artifact_declared") {
+        if (typeof raw.basename !== "string" || raw.basename.trim() === "") {
+            return failure(label, `[${index}].basename must be a non-empty string`);
+        }
+        return loadSuccess({
+            id,
+            type: "artifact_declared",
+            basename: raw.basename.trim(),
+        });
+    }
+    return failure(label, `[${index}].type "${raw.type}" is unsupported`);
+}
+export function parsePreEmitChecks(raw, label) {
+    if (raw === undefined)
+        return loadSuccess(undefined);
+    if (!Array.isArray(raw) || raw.length === 0) {
+        return failure(label, "must be a non-empty array");
+    }
+    const checks = [];
+    for (let index = 0; index < raw.length; index++) {
+        const outcome = parsePreEmitCheck(raw[index], label, index);
+        if (!outcome.ok)
+            return outcome;
+        checks.push(outcome.value);
+    }
+    const duplicate = checks.find((check, index) => checks.findIndex((item) => item.id === check.id) !== index);
+    if (duplicate) {
+        return failure(label, `id "${duplicate.id}" is duplicated`);
+    }
+    return loadSuccess(checks);
+}

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,10 +1,26 @@
-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",
+    "mcp",
 ]);
 export function isPipelineStageBodyKey(key) {
     return BODY_KEYS.has(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[];