stageflow 0.13.0 → 0.15.0

package/dist/config/legacyYaml.js

@@ -0,0 +1,98 @@
+/**
+ * Dual-read adapter: accept old YAML authoring keys and warn (`catalog.legacy_yaml`).
+ *
+ * This is not the runtime IR. Stage workers, snapshots, emit, and VSE already
+ * use those same strings as TypeScript fields (`StageConfig.payload_schema`,
+ * DAG `completion` / `recovery`). Target YAML compiles onto that IR in
+ * `yamlDialect.ts`. New catalog fields go on `io` / `verify` / `on_verify_fail`,
+ * not here.
+ *
+ * Off: STAGEFLOW_LEGACY_YAML=0. migrate-yaml still reads legacy via
+ * withLegacyYamlAllowedAsync.
+ *
+ * Delete this file plus migrateYaml.ts, printTargetYaml.ts,
+ * migrateYamlCommand.ts, and tests/fixtures/dual-read to stop accepting
+ * payload_schema / pre_emit_checks / completion / recovery as authoring keys.
+ */
+import { AsyncLocalStorage } from "node:async_hooks";
+export const LEGACY_CONTRACT_KEYS = new Set([
+    "payload_schema",
+    "clone_input_schema",
+    "pre_emit_checks",
+    "completion",
+    "recovery",
+]);
+export const LEGACY_KEY_REPLACEMENTS = {
+    payload_schema: "io.output.schema",
+    clone_input_schema: "io.input.schema",
+    pre_emit_checks: "verify items with when including emit",
+    completion: "verify items with when including after",
+    recovery: "on_verify_fail",
+};
+const TARGET_AUTHORING_KEYS = new Set(["io", "verify", "on_verify_fail"]);
+const legacyYamlOverride = new AsyncLocalStorage();
+function collectDocumentKeys(raw) {
+    const keys = new Set(Object.keys(raw));
+    if (Array.isArray(raw.stages)) {
+        for (const entry of raw.stages) {
+            if (typeof entry === "object" && entry !== null && !Array.isArray(entry)) {
+                for (const key of Object.keys(entry))
+                    keys.add(key);
+            }
+        }
+    }
+    return keys;
+}
+export function formatLegacyReplacements(keys) {
+    return keys
+        .map((key) => {
+        const replacement = LEGACY_KEY_REPLACEMENTS[key];
+        return replacement ? `${key} → ${replacement}` : key;
+    })
+        .join(", ");
+}
+export function presentLegacyKeys(keys) {
+    const set = keys instanceof Set ? keys : new Set(keys);
+    return [...LEGACY_CONTRACT_KEYS].filter((key) => set.has(key));
+}
+export function legacyYamlIssue(fileLabel, keys) {
+    return {
+        code: "catalog.legacy_yaml",
+        message: `${fileLabel} uses legacy YAML keys (${formatLegacyReplacements(keys)})`,
+        category: "catalog",
+    };
+}
+export function dialectWarningForDocument(raw, fileLabel) {
+    const keys = collectDocumentKeys(raw);
+    const legacyKeys = presentLegacyKeys(keys);
+    if (legacyKeys.length === 0)
+        return undefined;
+    for (const key of keys) {
+        if (TARGET_AUTHORING_KEYS.has(key))
+            return undefined;
+    }
+    return legacyYamlIssue(fileLabel, legacyKeys);
+}
+export function allowLegacyYamlAuthoring() {
+    if (legacyYamlOverride.getStore() === true)
+        return true;
+    const raw = process.env.STAGEFLOW_LEGACY_YAML;
+    if (raw === "0" || raw === "false")
+        return false;
+    return true;
+}
+export function withLegacyYamlAllowed(fn) {
+    return legacyYamlOverride.run(true, fn);
+}
+export function withLegacyYamlAllowedAsync(fn) {
+    return legacyYamlOverride.run(true, fn);
+}
+export function legacyAuthoringRejected(dialect, fileLabel, keys) {
+    if (dialect !== "legacy" || allowLegacyYamlAuthoring())
+        return undefined;
+    return {
+        code: "catalog.legacy_yaml",
+        message: `${fileLabel}: dual-read is disabled (STAGEFLOW_LEGACY_YAML=0). Run sf migrate-yaml or author io / verify / on_verify_fail (${formatLegacyReplacements(keys)}).`,
+        category: "catalog",
+    };
+}

package/dist/config/loadOutcome.d.ts

@@ -23,9 +23,10 @@ export type LoadIssue = {
 export type LoadOutcome<T> = {
     ok: true;
     value: T;
+    issues?: LoadIssue[];
 } | {
     ok: false;
     issues: LoadIssue[];
 };
 export declare function loadFailure<T>(issues: LoadIssue[]): LoadOutcome<T>;
-export declare function loadSuccess<T>(value: T): LoadOutcome<T>;
+export declare function loadSuccess<T>(value: T, issues?: LoadIssue[]): LoadOutcome<T>;

package/dist/config/loadOutcome.js

@@ -1,6 +1,9 @@
 export function loadFailure(issues) {
     return { ok: false, issues };
 }
-export function loadSuccess(value) {
+export function loadSuccess(value, issues) {
+    if (issues && issues.length > 0) {
+        return { ok: true, value, issues };
+    }
     return { ok: true, value };
 }

package/dist/config/loadPipeline.d.ts

@@ -5,7 +5,9 @@ export type { LoadIssue, LoadOutcome } from "./loadOutcome.js";
 export declare function resolvePipelinePath(pipelinePath: string, cwd: string): Promise<string>;
 export declare function loadPipelineOutcome(nameOrPath: string, options?: {
     cwd?: string;
+    projectRoot?: string;
 }): Promise<LoadOutcome<LoadedPipeline>>;
 export declare function loadPipeline(nameOrPath: string, options?: {
     cwd?: string;
+    projectRoot?: string;
 }): Promise<LoadedPipeline>;

package/dist/config/loadPipeline.js

@@ -1,11 +1,88 @@
 import { access } from "node:fs/promises";
 import path from "node:path";
+import { compilePayloadSchema, expandPayloadSchemaRefs, isPayloadSchemaSubset, UnresolvedSchemaRefError, } from "../envelope/payloadSchema.js";
 import { loadFailure, loadSuccess } from "./loadOutcome.js";
 import { mergePipelineStages } from "./mergePipelineIncludes.js";
 import { normalizePipelineStageEntries, toWiringRefs, } from "./normalizePipelineStageEntry.js";
-import { loadStageFromObjectOutcome, loadStageOutcome } from "./loadStage.js";
+import { loadStageFromObjectOutcome, loadStageOutcome, afterCompletionForStage } from "./loadStage.js";
+import { materializeStageModels } from "./materializeStageModels.js";
+import { predecessorEdges } from "./pipelineNeeds.js";
 import { resolvePipelineDagFromRefs } from "./resolvePipelineDag.js";
+import { recoveryRequiresCompletionIssue } from "./parseCompletionContract.js";
 import { validateCompletionContractForStage } from "./validateCompletionContract.js";
+function schemaCompileIssue(stageId, field, err, pipelineId) {
+    const message = err instanceof Error ? err.message : String(err);
+    if (err instanceof UnresolvedSchemaRefError) {
+        return {
+            code: "stage.unresolved_schema_ref",
+            message: `Pipeline ${pipelineId}: stage "${stageId}" ${field}: ${message}`,
+            category: "stage",
+            stageId,
+        };
+    }
+    return {
+        code: field === "payload_schema" ? "stage.invalid_payload_schema" : "stage.invalid_clone_input_schema",
+        message: `Pipeline ${pipelineId}: stage "${stageId}" ${field}: ${message}`,
+        category: "stage",
+        stageId,
+    };
+}
+function attachPipelineSchemas(stages, schemas, pipelineId) {
+    const options = schemas !== undefined ? { schemas } : undefined;
+    for (const stage of stages) {
+        if (stage.payload_schema !== undefined) {
+            try {
+                compilePayloadSchema(stage.payload_schema, options);
+                stage.payload_schema = expandPayloadSchemaRefs(stage.payload_schema, options);
+            }
+            catch (err) {
+                return loadFailure([schemaCompileIssue(stage.id, "payload_schema", err, pipelineId)]);
+            }
+        }
+        if (stage.clone_input_schema !== undefined) {
+            try {
+                compilePayloadSchema(stage.clone_input_schema, options);
+                stage.clone_input_schema = expandPayloadSchemaRefs(stage.clone_input_schema, options);
+            }
+            catch (err) {
+                return loadFailure([schemaCompileIssue(stage.id, "clone_input_schema", err, pipelineId)]);
+            }
+        }
+    }
+    return loadSuccess(undefined);
+}
+function checkSequentialIoCompatibility(stages, dag, pipelineId, schemas) {
+    const stageById = new Map(stages.map((stage) => [stage.id, stage]));
+    const nodeById = new Map(dag.nodes.map((node) => [node.id, node]));
+    const options = schemas !== undefined ? { schemas } : undefined;
+    for (const child of stages) {
+        const node = nodeById.get(child.id);
+        if (!node)
+            continue;
+        const parents = predecessorEdges(node);
+        if (parents.length !== 1)
+            continue;
+        if (node.clonable)
+            continue;
+        const parentNode = nodeById.get(parents[0].id);
+        if (parentNode?.clonable)
+            continue;
+        const parent = stageById.get(parents[0].id);
+        if (!parent?.payload_schema || child.clone_input_schema === undefined)
+            continue;
+        if (!isPayloadSchemaSubset(child.clone_input_schema, parent.payload_schema, options)) {
+            return loadFailure([
+                {
+                    code: "pipeline.io_incompatible",
+                    message: `Pipeline ${pipelineId}: stage "${child.id}" io.input is not a structural subset of "${parent.id}" io.output`,
+                    category: "pipeline",
+                    pipelineId,
+                },
+            ]);
+        }
+    }
+    return loadSuccess(undefined);
+}
 export async function resolvePipelinePath(pipelinePath, cwd) {
     const resolved = path.normalize(path.resolve(cwd, pipelinePath));
     try {
@@ -16,14 +93,15 @@ export async function resolvePipelinePath(pipelinePath, cwd) {
         throw new Error(`Pipeline file not found: ${resolved}. Pass a filesystem path to --pipeline (e.g. pipelines/hello.pipeline.yaml), not a bare pipeline id.`);
     }
 }
-async function loadPipelineFromPath(pipelinePath) {
+async function loadPipelineFromPath(pipelinePath, cwd, projectRoot = cwd) {
     const normalizedPipelinePath = path.normalize(path.resolve(pipelinePath));
     const mergeOutcome = await mergePipelineStages(normalizedPipelinePath);
     if (!mergeOutcome.ok) {
         return loadFailure(mergeOutcome.issues);
     }
-    const { entries: rawEntries, pipelineId, agent: pipelineAgent } = mergeOutcome.value;
+    const { entries: rawEntries, pipelineId, agent: pipelineAgent, model: pipelineModel, schemas: pipelineSchemas, warnings: mergeWarnings, } = mergeOutcome.value;
     const ctx = { pipelineId, path: normalizedPipelinePath };
+    const warnings = [...mergeWarnings];
     const normalizeOutcome = normalizePipelineStageEntries(rawEntries, ctx);
     if (!normalizeOutcome.ok) {
         return loadFailure(normalizeOutcome.issues);
@@ -51,6 +129,7 @@ async function loadPipelineFromPath(pipelinePath) {
     const entryById = new Map(normalizedEntries.map((entry) => [entry.id, entry]));
     const stageSources = {};
     const stages = [];
+    const fileAfterById = new Map();
     for (const stageId of stageIds) {
         const entry = entryById.get(stageId);
         if (!entry) {
@@ -67,6 +146,7 @@ async function loadPipelineFromPath(pipelinePath) {
             const inlineOutcome = loadStageFromObjectOutcome(entry.body.raw, {
                 entryId: entry.id,
                 declaringPath: entry.declaringPath,
+                deferSchemaRefs: true,
             });
             if (!inlineOutcome.ok) {
                 return loadFailure(inlineOutcome.issues);
@@ -75,8 +155,13 @@ async function loadPipelineFromPath(pipelinePath) {
             stageSources[stageId] = { kind: "inline" };
             continue;
         }
-        const stageOutcome = await loadStageOutcome(entry.body.absolutePath);
+        const stageOutcome = await loadStageOutcome(entry.body.absolutePath, {
+            deferSchemaRefs: true,
+        });
         if (!stageOutcome.ok) {
+            if (stageOutcome.issues.some((issue) => issue.code === "catalog.mixed_yaml_dialect")) {
+                return loadFailure(stageOutcome.issues);
+            }
             return loadFailure([
                 {
                     code: "pipeline.missing_stage",
@@ -87,6 +172,22 @@ async function loadPipelineFromPath(pipelinePath) {
                 ...stageOutcome.issues,
             ]);
         }
+        if (stageOutcome.issues)
+            warnings.push(...stageOutcome.issues);
+        const fileAfter = afterCompletionForStage(stageOutcome.value);
+        if (fileAfter && entry.completion) {
+            return loadFailure([
+                {
+                    code: "pipeline.invalid_completion",
+                    message: `Pipeline ${pipelineId}: stage "${stageId}" after-checks come from both body verify and wrapper completion`,
+                    category: "pipeline",
+                    pipelineId,
+                },
+            ]);
+        }
+        if (fileAfter && !entry.completion) {
+            fileAfterById.set(stageId, fileAfter);
+        }
         if (stageOutcome.value.id !== entry.id) {
             return loadFailure([
                 {
@@ -105,13 +206,53 @@ async function loadPipelineFromPath(pipelinePath) {
         stages.push(stage);
         stageSources[stageId] = { kind: "file", path: entry.body.absolutePath };
     }
+    const schemaOutcome = attachPipelineSchemas(stages, pipelineSchemas, pipelineId);
+    if (!schemaOutcome.ok)
+        return schemaOutcome;
+    const ioOutcome = checkSequentialIoCompatibility(stages, dag, pipelineId, pipelineSchemas);
+    if (!ioOutcome.ok)
+        return ioOutcome;
+    if (pipelineModel !== undefined) {
+        const inheritingIds = stages
+            .filter((stage) => stage.model === undefined)
+            .map((stage) => stage.id);
+        if (inheritingIds.length > 0) {
+            warnings.push({
+                code: "pipeline.model_applies",
+                message: `Pipeline ${pipelineId}: pipeline-root model now applies to stages that omit model (${inheritingIds.join(", ")})`,
+                category: "pipeline",
+                pipelineId,
+            });
+        }
+    }
+    const materializeOutcome = await materializeStageModels(stages, {
+        pipelineModel,
+        pipelineId,
+        projectRoot,
+    });
+    if (!materializeOutcome.ok) {
+        return loadFailure(materializeOutcome.issues);
+    }
+    const loadedStages = materializeOutcome.value;
     const pipeline = {
         id: pipelineId,
         stages: stageIds,
         ...(pipelineAgent !== undefined ? { agent: pipelineAgent } : {}),
+        ...(pipelineModel !== undefined ? { model: pipelineModel } : {}),
+        ...(pipelineSchemas !== undefined ? { schemas: pipelineSchemas } : {}),
     };
     const nodeById = new Map(dag.nodes.map((node) => [node.id, node]));
-    for (const stage of stages) {
+    for (const [stageId, after] of fileAfterById) {
+        const node = nodeById.get(stageId);
+        if (node)
+            node.completion = after;
+    }
+    for (const node of dag.nodes) {
+        if (node.recovery !== undefined && node.completion === undefined) {
+            return loadFailure([recoveryRequiresCompletionIssue(node.id)]);
+        }
+    }
+    for (const stage of loadedStages) {
         const completion = nodeById.get(stage.id)?.completion;
         const completionOutcome = validateCompletionContractForStage(stage, completion);
         if (!completionOutcome.ok)
@@ -119,14 +260,15 @@ async function loadPipelineFromPath(pipelinePath) {
     }
     return loadSuccess({
         pipeline,
-        stages,
+        stages: loadedStages,
         dag,
         pipelinePath: normalizedPipelinePath,
         stageSources,
-    });
+    }, warnings);
 }
 export async function loadPipelineOutcome(nameOrPath, options = {}) {
     const cwd = options.cwd ?? process.cwd();
+    const projectRoot = options.projectRoot ?? cwd;
     let pipelinePath;
     try {
         pipelinePath = await resolvePipelinePath(nameOrPath, cwd);
@@ -141,7 +283,7 @@ export async function loadPipelineOutcome(nameOrPath, options = {}) {
             },
         ]);
     }
-    return loadPipelineFromPath(pipelinePath);
+    return loadPipelineFromPath(pipelinePath, cwd, projectRoot);
 }
 export async function loadPipeline(nameOrPath, options = {}) {
     const outcome = await loadPipelineOutcome(nameOrPath, options);

package/dist/config/loadStage.d.ts

@@ -1,9 +1,16 @@
+import type { CompletionContract } from "../types/completion.js";
 import { type StageConfig } from "../types/stage.js";
 import { type LoadOutcome } from "./loadOutcome.js";
+/** After-phase IR from target `verify` (`when` includes after). Stamped onto DAG `completion`. */
+export declare function afterCompletionForStage(stage: StageConfig): CompletionContract | undefined;
 export declare function parseStageMcp(raw: unknown, label: string, stageId?: string): LoadOutcome<string[] | undefined>;
+export type LoadStageOptions = {
+    deferSchemaRefs?: boolean;
+};
 export declare function loadStageFromObjectOutcome(raw: Record<string, unknown>, ctx: {
     entryId: string;
     declaringPath: string;
+    deferSchemaRefs?: boolean;
 }): LoadOutcome<StageConfig>;
-export declare function loadStageOutcome(filePath: string): Promise<LoadOutcome<StageConfig>>;
+export declare function loadStageOutcome(filePath: string, options?: LoadStageOptions): Promise<LoadOutcome<StageConfig>>;
 export declare function loadStage(filePath: string): Promise<StageConfig>;

package/dist/config/loadStage.js

@@ -2,10 +2,18 @@ import { parseAgentField } from "../agent/agentBackend.js";
 import { STAGEFLOW_MCP_SERVER_NAME } from "../agent/claudeTools.js";
 import { CLONE_ACTIONS } from "../types/forkChoice.js";
 import { STAGE_GATE_KINDS, } from "../types/stage.js";
-import { compilePayloadSchema } from "../envelope/payloadSchema.js";
+import { compilePayloadSchema, UnresolvedSchemaRefError } from "../envelope/payloadSchema.js";
 import { loadFailure, loadSuccess } from "./loadOutcome.js";
+import { parseModelField } from "./modelField.js";
+import { allowLegacyYamlAuthoring, dialectWarningForDocument, legacyAuthoringRejected, presentLegacyKeys, } from "./legacyYaml.js";
 import { parsePreEmitChecks } from "./parsePreEmitChecks.js";
 import { readYamlObject } from "./readYamlObject.js";
+import { applyCompiledBody, classifyYamlDocument, compileTargetContract, dialectFromKeys, mixedDialectIssue, STAGE_FILE_WIRING_KEYS, } from "./yamlDialect.js";
+const afterCompletionByStage = new WeakMap();
+/** After-phase IR from target `verify` (`when` includes after). Stamped onto DAG `completion`. */
+export function afterCompletionForStage(stage) {
+    return afterCompletionByStage.get(stage);
+}
 function isGateKind(value) {
     return STAGE_GATE_KINDS.includes(value);
 }
@@ -154,13 +162,14 @@ export function parseStageMcp(raw, label, stageId) {
     }
     return loadSuccess(names);
 }
-function parseStageFields(raw, label, entryId) {
-    if (typeof raw.system_prompt !== "string" ||
-        typeof raw.model !== "string") {
+function parseStageFields(raw, label, entryId, deferSchemaRefs) {
+    // Reads IR field names. Target YAML must already be compiled via
+    // applyCompiledBody; legacy YAML uses these keys as authoring.
+    if (typeof raw.system_prompt !== "string") {
         return loadFailure([
             {
                 code: "stage.invalid_shape",
-                message: `Invalid stage ${label}: system_prompt and model are required strings`,
+                message: `Invalid stage ${label}: system_prompt is a required string`,
                 category: "stage",
                 stageId: entryId,
             },
@@ -169,8 +178,21 @@ function parseStageFields(raw, label, entryId) {
     const stage = {
         id: entryId,
         system_prompt: raw.system_prompt,
-        model: raw.model,
     };
+    const modelField = parseModelField(raw.model);
+    if (!modelField.ok) {
+        return loadFailure([
+            {
+                code: "stage.invalid_model",
+                message: `Invalid stage ${label}: ${modelField.message}`,
+                category: "stage",
+                stageId: entryId,
+            },
+        ]);
+    }
+    if (modelField.value !== undefined) {
+        stage.model = modelField.value;
+    }
     if (raw.payload_schema !== undefined) {
         if (raw.payload_schema === null ||
             typeof raw.payload_schema !== "object" ||
@@ -188,15 +210,29 @@ function parseStageFields(raw, label, entryId) {
             compilePayloadSchema(raw.payload_schema);
         }
         catch (err) {
-            const message = err instanceof Error ? err.message : String(err);
-            return loadFailure([
-                {
-                    code: "stage.invalid_payload_schema",
-                    message: `Invalid stage ${label}: invalid payload_schema: ${message}`,
-                    category: "stage",
-                    stageId: entryId,
-                },
-            ]);
+            if (err instanceof UnresolvedSchemaRefError) {
+                if (!deferSchemaRefs) {
+                    return loadFailure([
+                        {
+                            code: "stage.unresolved_schema_ref",
+                            message: `Invalid stage ${label}: ${err.message}`,
+                            category: "stage",
+                            stageId: entryId,
+                        },
+                    ]);
+                }
+            }
+            else {
+                const message = err instanceof Error ? err.message : String(err);
+                return loadFailure([
+                    {
+                        code: "stage.invalid_payload_schema",
+                        message: `Invalid stage ${label}: invalid payload_schema: ${message}`,
+                        category: "stage",
+                        stageId: entryId,
+                    },
+                ]);
+            }
         }
         stage.payload_schema = raw.payload_schema;
     }
@@ -217,15 +253,29 @@ function parseStageFields(raw, label, entryId) {
             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,
-                },
-            ]);
+            if (err instanceof UnresolvedSchemaRefError) {
+                if (!deferSchemaRefs) {
+                    return loadFailure([
+                        {
+                            code: "stage.unresolved_schema_ref",
+                            message: `Invalid stage ${label}: ${err.message}`,
+                            category: "stage",
+                            stageId: entryId,
+                        },
+                    ]);
+                }
+            }
+            else {
+                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;
     }
@@ -310,9 +360,28 @@ function parseStageFields(raw, label, entryId) {
 }
 export function loadStageFromObjectOutcome(raw, ctx) {
     const label = `${ctx.entryId} (${ctx.declaringPath})`;
-    return parseStageFields(raw, label, ctx.entryId);
+    const deferSchemaRefs = ctx.deferSchemaRefs === true;
+    const dialect = dialectFromKeys(Object.keys(raw));
+    if (dialect === "invalid") {
+        return loadFailure([mixedDialectIssue()]);
+    }
+    const rejected = legacyAuthoringRejected(dialect, label, presentLegacyKeys(Object.keys(raw)));
+    if (rejected)
+        return loadFailure([rejected]);
+    if (dialect === "target") {
+        const compiled = compileTargetContract(raw, {
+            stageId: ctx.entryId,
+            label,
+            category: "stage",
+            deferSchemaRefs,
+        });
+        if (!compiled.ok)
+            return compiled;
+        return parseStageFields(applyCompiledBody(raw, compiled.value), label, ctx.entryId, deferSchemaRefs);
+    }
+    return parseStageFields(raw, label, ctx.entryId, deferSchemaRefs);
 }
-export async function loadStageOutcome(filePath) {
+export async function loadStageOutcome(filePath, options = {}) {
     let raw;
     try {
         raw = await readYamlObject(filePath);
@@ -331,12 +400,47 @@ export async function loadStageOutcome(filePath) {
         return loadFailure([
             {
                 code: "stage.invalid_shape",
-                message: `Invalid stage file ${filePath}: id, system_prompt, and model are required strings`,
+                message: `Invalid stage file ${filePath}: id and system_prompt are required strings`,
                 category: "stage",
             },
         ]);
     }
-    const outcome = parseStageFields(raw, `file ${filePath}`, raw.id);
+    const dialect = classifyYamlDocument(raw);
+    if (dialect === "invalid") {
+        return loadFailure([mixedDialectIssue()]);
+    }
+    const rejected = legacyAuthoringRejected(dialect, filePath, presentLegacyKeys(Object.keys(raw)));
+    if (rejected)
+        return loadFailure([rejected]);
+    if (dialect === "target") {
+        const wiring = STAGE_FILE_WIRING_KEYS.find((key) => raw[key] !== undefined);
+        if (wiring) {
+            return loadFailure([
+                {
+                    code: "stage.invalid_shape",
+                    message: `Invalid stage file ${filePath}: new-dialect stage files must not declare wiring key "${wiring}"`,
+                    category: "stage",
+                    stageId: raw.id,
+                },
+            ]);
+        }
+    }
+    let parseRaw = raw;
+    let afterCompletion;
+    const deferSchemaRefs = options.deferSchemaRefs === true;
+    if (dialect === "target") {
+        const compiled = compileTargetContract(raw, {
+            stageId: raw.id,
+            label: `file ${filePath}`,
+            category: "stage",
+            deferSchemaRefs,
+        });
+        if (!compiled.ok)
+            return compiled;
+        parseRaw = applyCompiledBody(raw, compiled.value);
+        afterCompletion = compiled.value.completion;
+    }
+    const outcome = parseStageFields(parseRaw, `file ${filePath}`, raw.id, deferSchemaRefs);
     if (!outcome.ok)
         return outcome;
     if (outcome.value.id !== raw.id) {
@@ -349,7 +453,12 @@ export async function loadStageOutcome(filePath) {
             },
         ]);
     }
-    return outcome;
+    if (afterCompletion)
+        afterCompletionByStage.set(outcome.value, afterCompletion);
+    const warning = allowLegacyYamlAuthoring()
+        ? dialectWarningForDocument(raw, filePath)
+        : undefined;
+    return loadSuccess(outcome.value, warning ? [warning] : undefined);
 }
 export async function loadStage(filePath) {
     const outcome = await loadStageOutcome(filePath);

package/dist/config/loadStageflowManifest.js

@@ -3,6 +3,7 @@ import path from "node:path";
 import { parse as parseYaml } from "yaml";
 import { parseAgentField } from "../agent/agentBackend.js";
 import { loadFailure, loadSuccess } from "./loadOutcome.js";
+import { parseModelField } from "./modelField.js";
 const DEFAULT_PIPELINE_PATTERN = "*.pipeline.yaml";
 const DEFAULT_TASK_PATTERN = "*.task.yaml";
 export function manifestPathForProject(projectRoot) {
@@ -117,6 +118,14 @@ export function parseStageflowManifestOutcome(yamlText, manifestPath, projectRoo
     else {
         agent = agentField.value;
     }
+    let model;
+    const modelField = parseModelField(record.model);
+    if (!modelField.ok) {
+        issues.push(catalogIssue("catalog.manifest_invalid", modelField.message));
+    }
+    else {
+        model = modelField.value;
+    }
     if (issues.length > 0) {
         return loadFailure(issues);
     }
@@ -140,6 +149,7 @@ export function parseStageflowManifestOutcome(yamlText, manifestPath, projectRoo
         version: 1,
         catalog,
         ...(agent !== undefined ? { agent } : {}),
+        ...(model !== undefined ? { model } : {}),
     };
     return loadSuccess({
         path: manifestPath,