stageflow 0.13.0 → 0.16.0

package/dist/config/normalizePipelineStageEntry.js

@@ -1,6 +1,13 @@
+/**
+ * Normalize a pipeline `stages:` entry. Target YAML (`io` / `verify` /
+ * `on_verify_fail`) compiles onto IR `completion` / `recovery` / body
+ * `payload_schema`. Legacy YAML keys are dual-read via legacyYaml.ts.
+ */
 import path from "node:path";
 import { loadFailure, loadSuccess } from "./loadOutcome.js";
 import { parseStageMcp } from "./loadStage.js";
+import { legacyAuthoringRejected, presentLegacyKeys } from "./legacyYaml.js";
+import { applyCompiledBody, compileTargetContract, dialectFromKeys, mixedDialectIssue, } from "./yamlDialect.js";
 import { BODY_KEYS, isAllowedPipelineStageEntryKey, } from "./pipelineStageKeys.js";
 import { parseExecutionPolicy } from "./parseCompletionContract.js";
 import { parsePipelineNeeds } from "./pipelineNeeds.js";
@@ -90,6 +97,10 @@ export function normalizePipelineStageEntries(rawEntries, ctx) {
                 ]);
             }
         }
+        const dialect = dialectFromKeys(Object.keys(raw));
+        if (dialect === "invalid") {
+            return loadFailure([mixedDialectIssue()]);
+        }
         const uses = typeof raw.uses === "string" ? raw.uses : undefined;
         const hasBody = hasBodyKey(raw);
         const skillOutcome = readSkill(raw);
@@ -138,7 +149,35 @@ export function normalizePipelineStageEntries(rawEntries, ctx) {
                 },
             ]);
         }
-        const policyOutcome = parseExecutionPolicy(raw, id);
+        let compiledBody;
+        let policyOutcome;
+        if (dialect === "target") {
+            const compiled = compileTargetContract(raw, {
+                stageId: id,
+                label: `entry at index ${index} in ${declaringPath}`,
+                category: "pipeline",
+                deferSchemaRefs: true,
+            });
+            if (!compiled.ok)
+                return compiled;
+            policyOutcome = loadSuccess({
+                ...(compiled.value.completion !== undefined
+                    ? { completion: compiled.value.completion }
+                    : {}),
+                ...(compiled.value.recovery !== undefined
+                    ? { recovery: compiled.value.recovery }
+                    : {}),
+            });
+            if (!uses) {
+                compiledBody = applyCompiledBody(extractBodyRaw(raw), compiled.value);
+            }
+        }
+        else {
+            const rejected = legacyAuthoringRejected(dialect, `stage "${id}" in ${declaringPath}`, presentLegacyKeys(Object.keys(raw)));
+            if (rejected)
+                return loadFailure([rejected]);
+            policyOutcome = parseExecutionPolicy(raw, id);
+        }
         if (!policyOutcome.ok)
             return policyOutcome;
         let needs;
@@ -202,7 +241,7 @@ export function normalizePipelineStageEntries(rawEntries, ctx) {
             body = { kind: "uses", path: uses, absolutePath };
         }
         else {
-            body = { kind: "inline", raw: extractBodyRaw(raw) };
+            body = { kind: "inline", raw: compiledBody ?? extractBodyRaw(raw) };
         }
         const entry = {
             id,

package/dist/config/parseCompletionContract.d.ts

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

package/dist/config/parseCompletionContract.js

@@ -1,3 +1,8 @@
+/**
+ * Parse IR `completion` / `recovery` objects (DAG wiring after compile, or
+ * legacy YAML keys). Target YAML `on_verify_fail` / after-phase `verify` are
+ * compiled onto these shapes in yamlDialect.ts before this parser runs.
+ */
 import path from "node:path";
 import { STAGE_GATE_KINDS } from "../types/stage.js";
 import { loadFailure, loadSuccess } from "./loadOutcome.js";
@@ -21,6 +26,13 @@ function hasOnlyKeys(value, allowed) {
 function isPositiveInteger(value) {
     return typeof value === "number" && Number.isSafeInteger(value) && value > 0;
 }
+export function recoveryRequiresCompletionIssue(stageId) {
+    return {
+        code: "pipeline.invalid_recovery",
+        message: `Stage "${stageId}" recovery: requires a completion contract`,
+        category: "pipeline",
+    };
+}
 function isGateKind(value) {
     return typeof value === "string" && STAGE_GATE_KINDS.includes(value);
 }
@@ -167,7 +179,7 @@ function parseRecovery(raw, stageId, hasCompletion) {
     if (raw === undefined)
         return loadSuccess(undefined);
     if (!hasCompletion)
-        return failure(stageId, "recovery", "requires a completion contract");
+        return loadFailure([recoveryRequiresCompletionIssue(stageId)]);
     if (!isPlainObject(raw))
         return failure(stageId, "recovery", "must be an object");
     const unknown = hasOnlyKeys(raw, ["mode", "max_attempts", "retry_safety", "include_failed_checks"]);
@@ -204,11 +216,12 @@ function parseRecovery(raw, stageId, hasCompletion) {
             : {}),
     });
 }
-export function parseExecutionPolicy(raw, stageId) {
+export function parseExecutionPolicy(raw, stageId, options) {
     const completion = parseCompletion(raw.completion, stageId);
     if (!completion.ok)
         return completion;
-    const recovery = parseRecovery(raw.recovery, stageId, completion.value !== undefined);
+    const requireCompletion = options?.requireCompletionForRecovery ?? true;
+    const recovery = parseRecovery(raw.recovery, stageId, requireCompletion ? completion.value !== undefined : true);
     if (!recovery.ok)
         return recovery;
     return loadSuccess({

package/dist/config/parsePreEmitChecks.js

@@ -1,3 +1,7 @@
+/**
+ * Parse IR `pre_emit_checks` (emit-phase). YAML `verify` emit items are compiled
+ * onto this list in yamlDialect.ts before this parser runs.
+ */
 import { STAGE_GATE_KINDS } from "../types/stage.js";
 import { loadFailure, loadSuccess } from "./loadOutcome.js";
 function isPlainObject(value) {

package/dist/config/pipelineNeeds.js

@@ -41,13 +41,13 @@ export function parsePipelineNeeds(raw, stageId) {
     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`,
+            message: `stage "${stageId}": needs must be a non-empty string or a non-empty array`,
         };
     }
-    if (raw.length < 2) {
+    if (raw.length < 1) {
         return {
             ok: false,
-            message: `stage "${stageId}": needs array must contain at least two items`,
+            message: `stage "${stageId}": needs array must contain at least one item`,
         };
     }
     const edges = [];

package/dist/config/pipelineStageKeys.d.ts

@@ -1,4 +1,15 @@
+/**
+ * Allowed keys on a pipeline stage YAML entry.
+ *
+ * Target authoring: `io`, `verify`, `on_verify_fail`.
+ * IR / legacy YAML (same strings): `payload_schema`, `pre_emit_checks`,
+ * `completion`, `recovery`, `clone_input_schema`.
+ *
+ * New catalog fields go on the target keys (and compileTargetContract). Dual-read
+ * still lists the IR names so old files load.
+ */
 export declare const WIRING_KEYS: Set<string>;
+/** Stage body keys. Target: `io` / `verify`. IR/legacy: `payload_schema`, `pre_emit_checks`, `clone_input_schema`. */
 export declare const BODY_KEYS: Set<string>;
 export declare function isPipelineStageBodyKey(key: string): boolean;
 export declare function isAllowedPipelineStageEntryKey(key: string): boolean;

package/dist/config/pipelineStageKeys.js

@@ -1,3 +1,13 @@
+/**
+ * Allowed keys on a pipeline stage YAML entry.
+ *
+ * Target authoring: `io`, `verify`, `on_verify_fail`.
+ * IR / legacy YAML (same strings): `payload_schema`, `pre_emit_checks`,
+ * `completion`, `recovery`, `clone_input_schema`.
+ *
+ * New catalog fields go on the target keys (and compileTargetContract). Dual-read
+ * still lists the IR names so old files load.
+ */
 export const WIRING_KEYS = new Set([
     "id",
     "needs",
@@ -7,9 +17,11 @@ export const WIRING_KEYS = new Set([
     "clone_cap",
     "completion",
     "recovery",
+    "on_verify_fail",
     "feedback_loop",
     "replay_safe",
 ]);
+/** Stage body keys. Target: `io` / `verify`. IR/legacy: `payload_schema`, `pre_emit_checks`, `clone_input_schema`. */
 export const BODY_KEYS = new Set([
     "system_prompt",
     "model",
@@ -21,6 +33,8 @@ export const BODY_KEYS = new Set([
     "timeout_ms",
     "skill",
     "mcp",
+    "io",
+    "verify",
 ]);
 export function isPipelineStageBodyKey(key) {
     return BODY_KEYS.has(key);

package/dist/config/printTargetYaml.d.ts

@@ -0,0 +1,28 @@
+import type { CompletionCheck } from "../types/completion.js";
+import type { PreEmitCheck } from "../types/preEmitCheck.js";
+import type { StageIoYaml } from "../types/stage.js";
+export type VerifyPhase = "emit" | "after";
+export declare function buildVerifyItems(preEmit: PreEmitCheck[] | undefined, afterChecks: CompletionCheck[] | undefined): {
+    ok: true;
+    items: Record<string, unknown>[];
+} | {
+    ok: false;
+    error: string;
+};
+export declare function ioFromSchemas(stage: {
+    payload_schema?: unknown;
+    clone_input_schema?: unknown;
+}): StageIoYaml | undefined;
+export declare function ioFromRawDocument(raw: Record<string, unknown>): StageIoYaml | undefined;
+export declare function rewriteStageDocument(raw: Record<string, unknown>, compiled: {
+    io?: StageIoYaml;
+    verify?: Record<string, unknown>[];
+}): Record<string, unknown>;
+export declare function rewritePipelineStageEntry(raw: Record<string, unknown>, compiled: {
+    uses?: string;
+    io?: StageIoYaml;
+    verify?: Record<string, unknown>[];
+    on_verify_fail?: unknown;
+}): Record<string, unknown>;
+export declare function rewriteCatalogDocument(raw: Record<string, unknown>, rewriteEntry: (entry: Record<string, unknown>, index: number) => Record<string, unknown>): Record<string, unknown>;
+export declare function stringifyTargetYaml(doc: unknown): string;

package/dist/config/printTargetYaml.js

@@ -0,0 +1,243 @@
+/**
+ * Print target YAML (`io` / `verify` / `on_verify_fail`) from compiled IR.
+ * Used by `sf migrate-yaml`. IR field names stay payload_schema / completion.
+ */
+import { stringify as stringifyYaml } from "yaml";
+import { LEGACY_CONTRACT_KEYS } from "./legacyYaml.js";
+import { STAGE_FILE_WIRING_KEYS, TARGET_CONTRACT_KEYS } from "./yamlDialect.js";
+function isPlainObject(value) {
+    return typeof value === "object" && value !== null && Array.isArray(value) === false;
+}
+function uniquePhases(phases) {
+    const seen = new Set();
+    const next = [];
+    for (const phase of phases) {
+        if (seen.has(phase))
+            continue;
+        seen.add(phase);
+        next.push(phase);
+    }
+    return next;
+}
+function artifactTypesCompatible(a, b) {
+    const artifact = a === "artifact" || a === "artifact_declared";
+    const other = b === "artifact" || b === "artifact_declared";
+    return artifact && other;
+}
+function typesCompatible(a, b) {
+    if (a === b)
+        return true;
+    return artifactTypesCompatible(a, b);
+}
+function preEmitToItem(check) {
+    if (check.type === "artifact_declared") {
+        return {
+            id: check.id,
+            type: "artifact",
+            basename: check.basename,
+            when: ["emit"],
+        };
+    }
+    return { ...check, when: ["emit"] };
+}
+function afterCheckToItem(check) {
+    return { ...check, when: ["after"] };
+}
+function mergeVerifyItems(existing, incoming) {
+    const existingType = String(existing.type);
+    const incomingType = String(incoming.type);
+    if (!typesCompatible(existingType, incomingType)) {
+        return {
+            ok: false,
+            error: `verify id "${String(existing.id)}" cannot merge types "${existingType}" and "${incomingType}"`,
+        };
+    }
+    const existingWhen = Array.isArray(existing.when) ? existing.when : [];
+    const incomingWhen = Array.isArray(incoming.when) ? incoming.when : [];
+    const merged = { ...existing };
+    if (artifactTypesCompatible(existingType, incomingType)) {
+        merged.type = "artifact";
+        if (typeof incoming.path === "string")
+            merged.path = incoming.path;
+        if (typeof incoming.basename === "string" && merged.path === undefined) {
+            merged.basename = incoming.basename;
+        }
+        if (typeof incoming.nonempty === "boolean")
+            merged.nonempty = incoming.nonempty;
+        if (typeof existing.basename === "string" && typeof merged.path === "string") {
+            const base = merged.path.split(/[\\/]/).pop();
+            if (base === existing.basename)
+                delete merged.basename;
+        }
+    }
+    else {
+        for (const [key, value] of Object.entries(incoming)) {
+            if (key === "when" || key === "id" || key === "type")
+                continue;
+            if (merged[key] === undefined)
+                merged[key] = value;
+        }
+    }
+    merged.when = uniquePhases([...existingWhen, ...incomingWhen]);
+    return { ok: true, item: merged };
+}
+export function buildVerifyItems(preEmit, afterChecks) {
+    const byId = new Map();
+    const order = [];
+    const add = (item) => {
+        const id = typeof item.id === "string" ? item.id : "";
+        if (!id)
+            return { ok: false, error: "verify item is missing id" };
+        const existing = byId.get(id);
+        if (!existing) {
+            byId.set(id, item);
+            order.push(id);
+            return undefined;
+        }
+        const merged = mergeVerifyItems(existing, item);
+        if (!merged.ok)
+            return { ok: false, error: merged.error };
+        byId.set(id, merged.item);
+        return undefined;
+    };
+    for (const check of preEmit ?? []) {
+        const failed = add(preEmitToItem(check));
+        if (failed)
+            return failed;
+    }
+    for (const check of afterChecks ?? []) {
+        const failed = add(afterCheckToItem(check));
+        if (failed)
+            return failed;
+    }
+    return { ok: true, items: order.map((id) => byId.get(id)) };
+}
+export function ioFromSchemas(stage) {
+    const io = {};
+    if (stage.clone_input_schema !== undefined) {
+        io.input = { schema: stage.clone_input_schema };
+    }
+    if (stage.payload_schema !== undefined) {
+        io.output = { schema: stage.payload_schema };
+    }
+    return io.input !== undefined || io.output !== undefined ? io : undefined;
+}
+export function ioFromRawDocument(raw) {
+    if (isPlainObject(raw.io))
+        return raw.io;
+    return ioFromSchemas({
+        payload_schema: raw.payload_schema,
+        clone_input_schema: raw.clone_input_schema,
+    });
+}
+function dropContractKeys(raw) {
+    const next = {};
+    for (const [key, value] of Object.entries(raw)) {
+        if (LEGACY_CONTRACT_KEYS.has(key) || TARGET_CONTRACT_KEYS.has(key))
+            continue;
+        next[key] = value;
+    }
+    return next;
+}
+const STAGE_BODY_ORDER = [
+    "id",
+    "system_prompt",
+    "model",
+    "agent",
+    "timeout_ms",
+    "io",
+    "verify",
+    "gate_kinds",
+    "clone_actions",
+    "skill",
+    "mcp",
+];
+const PIPELINE_WIRING_ORDER = [
+    "id",
+    "uses",
+    "skill",
+    "mcp",
+    "needs",
+    "fork",
+    "clonable",
+    "clone_cap",
+    "on_verify_fail",
+    "feedback_loop",
+    "replay_safe",
+];
+function orderKeys(raw, preferred) {
+    const next = {};
+    for (const key of preferred) {
+        if (raw[key] !== undefined)
+            next[key] = raw[key];
+    }
+    for (const key of Object.keys(raw)) {
+        if (next[key] !== undefined)
+            continue;
+        next[key] = raw[key];
+    }
+    return next;
+}
+export function rewriteStageDocument(raw, compiled) {
+    const next = dropContractKeys(raw);
+    for (const key of STAGE_FILE_WIRING_KEYS) {
+        delete next[key];
+    }
+    if (compiled.io !== undefined)
+        next.io = compiled.io;
+    if (compiled.verify !== undefined && compiled.verify.length > 0) {
+        next.verify = compiled.verify;
+    }
+    return orderKeys(next, STAGE_BODY_ORDER);
+}
+export function rewritePipelineStageEntry(raw, compiled) {
+    const next = dropContractKeys(raw);
+    if (compiled.uses !== undefined) {
+        next.uses = compiled.uses;
+        delete next.system_prompt;
+        delete next.model;
+        delete next.agent;
+        delete next.timeout_ms;
+        delete next.gate_kinds;
+        delete next.clone_actions;
+        delete next.io;
+        delete next.verify;
+        if (compiled.on_verify_fail !== undefined)
+            next.on_verify_fail = compiled.on_verify_fail;
+        else
+            delete next.on_verify_fail;
+        return orderKeys(next, PIPELINE_WIRING_ORDER);
+    }
+    if (compiled.io !== undefined)
+        next.io = compiled.io;
+    else
+        delete next.io;
+    if (compiled.verify !== undefined && compiled.verify.length > 0)
+        next.verify = compiled.verify;
+    else
+        delete next.verify;
+    if (compiled.on_verify_fail !== undefined)
+        next.on_verify_fail = compiled.on_verify_fail;
+    else
+        delete next.on_verify_fail;
+    return orderKeys(next, [...STAGE_BODY_ORDER, ...PIPELINE_WIRING_ORDER]);
+}
+export function rewriteCatalogDocument(raw, rewriteEntry) {
+    const next = {};
+    for (const [key, value] of Object.entries(raw)) {
+        if (key === "stages" && Array.isArray(value)) {
+            next.stages = value.map((entry, index) => {
+                if (!isPlainObject(entry))
+                    return entry;
+                return rewriteEntry(entry, index);
+            });
+            continue;
+        }
+        next[key] = value;
+    }
+    return next;
+}
+export function stringifyTargetYaml(doc) {
+    const text = stringifyYaml(doc, { indent: 2, lineWidth: 0 });
+    return text.endsWith("\n") ? text : `${text}\n`;
+}

package/dist/config/resolveModel.d.ts

@@ -0,0 +1,20 @@
+import type { LoadedManifest } from "../types/stageflowManifest.js";
+import { type LoadOutcome } from "./loadOutcome.js";
+export type ModelSelection = {
+    /** stageflow.yaml top-level `model`. */
+    global?: string;
+    /** Pipeline yaml top-level `model`; overrides global. */
+    pipeline?: string;
+    /** Stage yaml / inline `model`; overrides pipeline/global. */
+    stage?: string;
+};
+/**
+ * stage > pipeline > global. No silent hardcoded fallback — unset is a load error.
+ * Present-but-empty / whitespace follows parseModelField (load failure, not "").
+ */
+export declare function resolveModelOutcome(selection: ModelSelection, ctx: {
+    stageId: string;
+    pipelineId: string;
+}): LoadOutcome<string>;
+/** The global tier's model id from an already-loaded manifest, or undefined when missing/unset. */
+export declare function globalModelFromManifest(loaded: LoadedManifest | null): string | undefined;

package/dist/config/resolveModel.js

@@ -0,0 +1,35 @@
+import { loadFailure, loadSuccess } from "./loadOutcome.js";
+import { parseModelField } from "./modelField.js";
+/**
+ * stage > pipeline > global. No silent hardcoded fallback — unset is a load error.
+ * Present-but-empty / whitespace follows parseModelField (load failure, not "").
+ */
+export function resolveModelOutcome(selection, ctx) {
+    const effective = selection.stage ?? selection.pipeline ?? selection.global;
+    const parsed = parseModelField(effective);
+    if (!parsed.ok) {
+        return loadFailure([
+            {
+                code: "stage.invalid_model",
+                message: `Stage "${ctx.stageId}" in pipeline "${ctx.pipelineId}": ${parsed.message}`,
+                category: "stage",
+                stageId: ctx.stageId,
+            },
+        ]);
+    }
+    if (parsed.value === undefined) {
+        return loadFailure([
+            {
+                code: "stage.missing_model",
+                message: `Stage "${ctx.stageId}" in pipeline "${ctx.pipelineId}": model is required (set on stage, pipeline, or stageflow.yaml)`,
+                category: "stage",
+                stageId: ctx.stageId,
+            },
+        ]);
+    }
+    return loadSuccess(parsed.value);
+}
+/** The global tier's model id from an already-loaded manifest, or undefined when missing/unset. */
+export function globalModelFromManifest(loaded) {
+    return loaded?.manifest.model;
+}

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.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_mcp" | "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" | "catalog.invalid_mcp";
+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" | "pipeline.invalid_model" | "pipeline.invalid_verify" | "pipeline.io_incompatible" | "pipeline.model_applies" | "stage.invalid_shape" | "stage.invalid_model" | "stage.missing_model" | "stage.invalid_payload_schema" | "stage.invalid_clone_input_schema" | "stage.unresolved_schema_ref" | "stage.invalid_clone_actions" | "stage.invalid_gate_kinds" | "stage.invalid_pre_emit_checks" | "stage.invalid_timeout_ms" | "stage.invalid_skill" | "stage.invalid_mcp" | "stage.invalid_agent" | "stage.invalid_io" | "stage.load_error" | "stage.id_filename_mismatch" | "task.invalid_shape" | "task.load_error" | "task.entry_input_unmet" | "catalog.duplicate_pipeline_id" | "catalog.manifest_missing" | "catalog.manifest_invalid" | "catalog.empty_catalog" | "catalog.manifest_load_error" | "catalog.invalid_mcp" | "catalog.mixed_yaml_dialect" | "catalog.legacy_yaml";
 export type ValidationFinding = {
     severity: ValidationSeverity;
     code: ValidationFindingCode | string;
@@ -15,6 +15,7 @@ export type ValidationFinding = {
 export type ValidationScope = "full" | "pipeline" | "task";
 export type ValidateCatalogOptions = {
     cwd?: string;
+    projectRoot?: string;
     scope: ValidationScope;
     pipeline?: string;
     task?: string;
@@ -36,6 +37,7 @@ export declare function findingsFromLoadIssues(cwd: string, absPath: string, iss
 export declare function findingStageIdFilenameMismatch(cwd: string, absPath: string, fileStem: string, declaredId: string): ValidationFinding;
 export type ValidatePipelineOptions = {
     cwd?: string;
+    projectRoot?: string;
     validateStages?: boolean;
     strict?: boolean;
 };
@@ -43,12 +45,14 @@ export declare function validatePipeline(nameOrPath: string, options?: ValidateP
 export type LoadPipelineValidatedResult = {
     ok: true;
     loaded: LoadedPipeline;
+    findings: ValidationFinding[];
 } | {
     ok: false;
     findings: ValidationFinding[];
 };
 export declare function loadPipelineValidated(nameOrPath: string, options?: {
     cwd?: string;
+    projectRoot?: string;
     validateStages?: boolean;
 }): Promise<LoadPipelineValidatedResult>;
 export declare function validateCatalog(options: ValidateCatalogOptions): Promise<ValidationResult>;