stageflow 0.9.0 → 0.12.0

package/dist/config/loadStage.js

@@ -1,10 +1,69 @@
+import { parseAgentField } from "../agent/agentBackend.js";
+import { CLONE_ACTIONS } from "../types/forkChoice.js";
 import { STAGE_GATE_KINDS, } from "../types/stage.js";
 import { compilePayloadSchema } from "../envelope/payloadSchema.js";
 import { loadFailure, loadSuccess } from "./loadOutcome.js";
+import { parsePreEmitChecks } from "./parsePreEmitChecks.js";
 import { readYamlObject } from "./readYamlObject.js";
 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);
+    if (typeof raw !== "number" ||
+        !Number.isFinite(raw) ||
+        !Number.isInteger(raw) ||
+        raw <= 0) {
+        return loadFailure([
+            {
+                code: "stage.invalid_timeout_ms",
+                message: `Invalid stage ${label}: timeout_ms must be a positive integer (milliseconds)`,
+                category: "stage",
+            },
+        ]);
+    }
+    return loadSuccess(raw);
+}
 function parseGateKinds(raw, label) {
     if (raw === undefined)
         return loadSuccess(undefined);
@@ -30,7 +89,7 @@ function parseGateKinds(raw, label) {
         }
         kinds.push(item);
     }
-    return loadSuccess(kinds.length > 0 ? kinds : undefined);
+    return loadSuccess(kinds);
 }
 function parseStageFields(raw, label, entryId) {
     if (typeof raw.system_prompt !== "string" ||
@@ -78,6 +137,46 @@ function parseStageFields(raw, label, 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) {
+            const message = err instanceof Error ? err.message : String(err);
+            return loadFailure([
+                {
+                    code: "stage.invalid_clone_input_schema",
+                    message: `Invalid stage ${label}: invalid clone_input_schema: ${message}`,
+                    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) {
         const issues = gateKindsOutcome.issues.map((issue) => ({
@@ -86,8 +185,31 @@ function parseStageFields(raw, label, entryId) {
         }));
         return loadFailure(issues);
     }
-    if (gateKindsOutcome.value)
+    if (gateKindsOutcome.value !== undefined) {
         stage.gate_kinds = gateKindsOutcome.value;
+    }
+    const timeoutMsOutcome = parseTimeoutMs(raw.timeout_ms, label);
+    if (!timeoutMsOutcome.ok) {
+        const issues = timeoutMsOutcome.issues.map((issue) => ({
+            ...issue,
+            stageId: entryId,
+        }));
+        return loadFailure(issues);
+    }
+    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 (preEmitChecksOutcome.value !== undefined) {
+        stage.pre_emit_checks = preEmitChecksOutcome.value;
+    }
     if (raw.skill !== undefined) {
         if (typeof raw.skill !== "string" || raw.skill.trim() === "") {
             return loadFailure([
@@ -101,6 +223,20 @@ function parseStageFields(raw, label, entryId) {
         }
         stage.skill = raw.skill.trim();
     }
+    const agentField = parseAgentField(raw.agent);
+    if (!agentField.ok) {
+        return loadFailure([
+            {
+                code: "stage.invalid_agent",
+                message: `Invalid stage ${label}: ${agentField.message}`,
+                category: "stage",
+                stageId: entryId,
+            },
+        ]);
+    }
+    if (agentField.value !== undefined) {
+        stage.agent = agentField.value;
+    }
     return loadSuccess(stage);
 }
 export function loadStageFromObjectOutcome(raw, ctx) {

package/dist/config/loadStageflowManifest.js

@@ -1,6 +1,7 @@
 import { access, readFile } from "node:fs/promises";
 import path from "node:path";
 import { parse as parseYaml } from "yaml";
+import { parseAgentField } from "../agent/agentBackend.js";
 import { loadFailure, loadSuccess } from "./loadOutcome.js";
 const DEFAULT_PIPELINE_PATTERN = "*.pipeline.yaml";
 const DEFAULT_TASK_PATTERN = "*.task.yaml";
@@ -108,6 +109,14 @@ export function parseStageflowManifestOutcome(yamlText, manifestPath, projectRoo
         }
     }
     const patterns = parsePatterns(catalogRecord.patterns, issues);
+    let agent;
+    const agentField = parseAgentField(record.agent);
+    if (!agentField.ok) {
+        issues.push(catalogIssue("catalog.manifest_invalid", agentField.message));
+    }
+    else {
+        agent = agentField.value;
+    }
     if (issues.length > 0) {
         return loadFailure(issues);
     }
@@ -127,7 +136,11 @@ export function parseStageflowManifestOutcome(yamlText, manifestPath, projectRoo
             catalog.patterns.task = patterns.task;
         }
     }
-    const manifest = { version: 1, catalog };
+    const manifest = {
+        version: 1,
+        catalog,
+        ...(agent !== undefined ? { agent } : {}),
+    };
     return loadSuccess({
         path: manifestPath,
         projectRoot,

package/dist/config/mergePipelineIncludes.d.ts

@@ -6,4 +6,5 @@ export type RawMergedEntry = {
 export declare function mergePipelineStages(rootPath: string): Promise<LoadOutcome<{
     entries: RawMergedEntry[];
     pipelineId: string;
+    agent?: string;
 }>>;

package/dist/config/mergePipelineIncludes.js

@@ -1,4 +1,5 @@
 import path from "node:path";
+import { parseAgentField } from "../agent/agentBackend.js";
 import { loadFailure, loadSuccess } from "./loadOutcome.js";
 import { readYamlObject } from "./readYamlObject.js";
 function isPlainObject(value) {
@@ -123,6 +124,18 @@ export async function mergePipelineStages(rootPath) {
         ]);
     }
     const pipelineId = raw.id;
+    const agentField = parseAgentField(raw.agent);
+    if (!agentField.ok) {
+        return loadFailure([
+            {
+                code: "pipeline.invalid_agent",
+                message: `Invalid pipeline ${absRoot}: ${agentField.message}`,
+                category: "pipeline",
+                pipelineId,
+            },
+        ]);
+    }
+    const agent = agentField.value;
     const idLocations = new Map();
     const entries = [];
     const mergeResult = await visitPipelineFile(absRoot, [], idLocations, entries);
@@ -137,5 +150,5 @@ export async function mergePipelineStages(rootPath) {
             },
         ]);
     }
-    return loadSuccess({ entries, pipelineId });
+    return loadSuccess({ entries, pipelineId, ...(agent !== undefined ? { agent } : {}) });
 }

package/dist/config/normalizePipelineStageEntry.d.ts

@@ -1,4 +1,5 @@
-import type { NormalizedPipelineStageEntry } from "../types/pipeline.js";
+import type { CompletionContract, RecoveryPolicy } from "../types/completion.js";
+import type { NormalizedPipelineStageEntry, PipelineNeeds } from "../types/pipeline.js";
 import { type LoadOutcome } from "./loadOutcome.js";
 import type { RawMergedEntry } from "./mergePipelineIncludes.js";
 export declare function inferIdFromUsesPath(usesPath: string): string | null;
@@ -8,11 +9,15 @@ export declare function normalizePipelineStageEntries(rawEntries: RawMergedEntry
 }): LoadOutcome<NormalizedPipelineStageEntry[]>;
 export declare function toWiringRefs(entries: NormalizedPipelineStageEntry[]): Array<{
     id: string;
-    needs?: 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;
 }>;

package/dist/config/normalizePipelineStageEntry.js

@@ -1,6 +1,9 @@
 import path from "node:path";
 import { loadFailure, loadSuccess } from "./loadOutcome.js";
 import { BODY_KEYS, isAllowedPipelineStageEntryKey, } from "./pipelineStageKeys.js";
+import { parseExecutionPolicy } from "./parseCompletionContract.js";
+import { parsePipelineNeeds } from "./pipelineNeeds.js";
+import { parseFeedbackLoopConfig } from "./resolvePipelineDag.js";
 function isPlainObject(value) {
     return typeof value === "object" && value !== null && !Array.isArray(value);
 }
@@ -130,27 +133,49 @@ export function normalizePipelineStageEntries(rawEntries, ctx) {
                 },
             ]);
         }
-        if (raw.needs !== undefined) {
-            if (Array.isArray(raw.needs)) {
+        const policyOutcome = parseExecutionPolicy(raw, id);
+        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: `Pipeline ${ctx.pipelineId} (${ctx.path}): stage "${id}": needs must be a string, not an array`,
+                        message: err instanceof Error ? err.message : String(err),
                         category: "pipeline",
                         pipelineId: ctx.pipelineId,
                     },
                 ]);
             }
-            if (typeof raw.needs !== "string" || !raw.needs) {
+        }
+        if (raw.replay_safe !== undefined && typeof raw.replay_safe !== "boolean") {
+            return loadFailure([
+                {
+                    code: "pipeline.dag_error",
+                    message: `Pipeline ${ctx.pipelineId} (${ctx.path}): stage "${id}": replay_safe must be a boolean`,
+                    category: "pipeline",
+                    pipelineId: ctx.pipelineId,
+                },
+            ]);
+        }
+        if (raw.needs !== undefined) {
+            const parsedNeeds = parsePipelineNeeds(raw.needs, id);
+            if (!parsedNeeds.ok) {
                 return loadFailure([
                     {
                         code: "pipeline.dag_error",
-                        message: `Pipeline ${ctx.pipelineId} (${ctx.path}): stage "${id}": needs must be a non-empty string`,
+                        message: `Pipeline ${ctx.pipelineId} (${ctx.path}): ${parsedNeeds.message}`,
                         category: "pipeline",
                         pipelineId: ctx.pipelineId,
                     },
                 ]);
             }
+            needs = parsedNeeds.value;
         }
         let forkValue;
         if (raw.fork !== undefined) {
@@ -178,10 +203,22 @@ export function normalizePipelineStageEntries(rawEntries, ctx) {
             id,
             declaringPath,
             body,
-            ...(typeof raw.needs === "string" ? { needs: raw.needs } : {}),
+            ...(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 }
+                : {}),
             ...(skill !== undefined ? { skill } : {}),
         };
         const priorPath = normalized.find((e) => e.id === id)?.declaringPath;
@@ -206,5 +243,11 @@ export function toWiringRefs(entries) {
         ...(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 } : {}),
     }));
 }

package/dist/config/parseCompletionContract.d.ts

@@ -0,0 +1,8 @@
+import type { CompletionContract, RecoveryPolicy } from "../types/completion.js";
+import { type LoadOutcome } from "./loadOutcome.js";
+type ExecutionPolicy = {
+    completion?: CompletionContract;
+    recovery?: RecoveryPolicy;
+};
+export declare function parseExecutionPolicy(raw: Record<string, unknown>, stageId: string): LoadOutcome<ExecutionPolicy>;
+export {};

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);
+}