stageflow 0.16.0 → 0.18.0

package/dist/config/routeIf.js

@@ -0,0 +1,247 @@
+import { resolvePayloadSchemaFieldPath } from "../envelope/payloadSchema.js";
+const ALLOWED_LEAF_KEYS = new Set(["field", "op", "value"]);
+const ALLOWED_ALL_KEYS = new Set(["all"]);
+const ALLOWED_ANY_KEYS = new Set(["any"]);
+const ALLOWED_NOT_KEYS = new Set(["not"]);
+const ROUTE_IF_OPS = new Set([
+    "eq",
+    "ne",
+    "gt",
+    "gte",
+    "lt",
+    "lte",
+    "in",
+    "not_in",
+]);
+const EQ_NE_TYPES = new Set(["string", "number", "integer", "boolean"]);
+const NUMERIC_TYPES = new Set(["number", "integer"]);
+const NUMERIC_OPS = new Set(["gt", "gte", "lt", "lte"]);
+const MEMBERSHIP_OPS = new Set(["in", "not_in"]);
+function isPlainObject(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function hasOwn(object, key) {
+    return Object.prototype.hasOwnProperty.call(object, key);
+}
+function isRouteIfOp(value) {
+    return typeof value === "string" && ROUTE_IF_OPS.has(value);
+}
+function failParse(prefix, message) {
+    return {
+        ok: false,
+        message: `${prefix}${message}`,
+        code: "pipeline.route_if_invalid",
+    };
+}
+function unknownKeyIssue(raw, allowed, prefix) {
+    for (const key of Object.keys(raw)) {
+        if (!allowed.has(key)) {
+            return failParse(prefix, `: unknown key "${key}"`);
+        }
+    }
+    return undefined;
+}
+function parseRouteIfLeaf(raw, prefix) {
+    const extra = unknownKeyIssue(raw, ALLOWED_LEAF_KEYS, prefix);
+    if (extra)
+        return extra;
+    if (typeof raw.field !== "string" || !raw.field) {
+        return failParse(prefix, ": field must be a non-empty string");
+    }
+    if (!isRouteIfOp(raw.op)) {
+        return failParse(prefix, `: unknown op "${String(raw.op)}"`);
+    }
+    if (!hasOwn(raw, "value")) {
+        return failParse(prefix, ": value is required");
+    }
+    if (MEMBERSHIP_OPS.has(raw.op)) {
+        if (!Array.isArray(raw.value) || raw.value.length === 0) {
+            return failParse(prefix, `: ${raw.op} value must be a non-empty list`);
+        }
+    }
+    return {
+        ok: true,
+        value: {
+            field: raw.field,
+            op: raw.op,
+            value: raw.value,
+        },
+    };
+}
+function parseRouteIfNode(raw, prefix) {
+    if (!isPlainObject(raw)) {
+        return failParse(prefix, " must be a predicate object");
+    }
+    const hasAll = hasOwn(raw, "all");
+    const hasAny = hasOwn(raw, "any");
+    const hasNot = hasOwn(raw, "not");
+    const hasField = hasOwn(raw, "field");
+    const hasOp = hasOwn(raw, "op");
+    const hasValue = hasOwn(raw, "value");
+    const compositionCount = Number(hasAll) + Number(hasAny) + Number(hasNot);
+    const hasLeafKeys = hasField || hasOp || hasValue;
+    if (compositionCount > 1 || (compositionCount === 1 && hasLeafKeys)) {
+        return failParse(prefix, " must be exactly one of { field, op, value }, { all }, { any }, or { not }");
+    }
+    if (hasAll) {
+        const extra = unknownKeyIssue(raw, ALLOWED_ALL_KEYS, prefix);
+        if (extra)
+            return extra;
+        return parseRouteIfList(raw.all, prefix, "all");
+    }
+    if (hasAny) {
+        const extra = unknownKeyIssue(raw, ALLOWED_ANY_KEYS, prefix);
+        if (extra)
+            return extra;
+        return parseRouteIfList(raw.any, prefix, "any");
+    }
+    if (hasNot) {
+        const extra = unknownKeyIssue(raw, ALLOWED_NOT_KEYS, prefix);
+        if (extra)
+            return extra;
+        if (!isPlainObject(raw.not)) {
+            return failParse(prefix, ": not must be a predicate object");
+        }
+        const inner = parseRouteIfNode(raw.not, prefix);
+        if (!inner.ok)
+            return inner;
+        return { ok: true, value: { not: inner.value } };
+    }
+    return parseRouteIfLeaf(raw, prefix);
+}
+function parseRouteIfList(raw, prefix, kind) {
+    if (!Array.isArray(raw) || raw.length === 0) {
+        return failParse(prefix, `: ${kind} must be a non-empty list`);
+    }
+    const children = [];
+    for (const item of raw) {
+        const parsed = parseRouteIfNode(item, prefix);
+        if (!parsed.ok)
+            return parsed;
+        children.push(parsed.value);
+    }
+    return { ok: true, value: kind === "all" ? { all: children } : { any: children } };
+}
+export function parseRouteIf(raw, stageId, targetId) {
+    return parseRouteIfNode(raw, `stage "${stageId}": route "${targetId}" if`);
+}
+function valueMatchesScalarType(value, typeName) {
+    if (typeName === "string")
+        return typeof value === "string";
+    if (typeName === "boolean")
+        return typeof value === "boolean";
+    if (typeName === "number")
+        return typeof value === "number" && Number.isFinite(value);
+    if (typeName === "integer")
+        return typeof value === "number" && Number.isInteger(value);
+    return false;
+}
+function isRouteIfLeaf(predicate) {
+    return "op" in predicate && predicate.op !== undefined && typeof predicate.field === "string";
+}
+function routeIfLeafSchemaIssue(predicate, payloadSchema, prefix) {
+    const path = resolvePayloadSchemaFieldPath(payloadSchema, predicate.field);
+    if (!path.ok) {
+        if (path.issue === "array_index") {
+            return `${prefix}: field "${predicate.field}" array index paths are not allowed`;
+        }
+        if (path.issue === "optional") {
+            return `${prefix}: field "${predicate.field}" must be required on io.output.schema`;
+        }
+        return `${prefix}: field "${predicate.field}" is not a property of io.output.schema`;
+    }
+    const fieldType = path.type;
+    if (NUMERIC_OPS.has(predicate.op)) {
+        if (!NUMERIC_TYPES.has(fieldType)) {
+            return `${prefix}: op ${predicate.op} is only valid for number or integer fields`;
+        }
+        return undefined;
+    }
+    if (!EQ_NE_TYPES.has(fieldType)) {
+        return `${prefix}: op ${predicate.op} is only valid for string, number, integer, or boolean fields`;
+    }
+    if (MEMBERSHIP_OPS.has(predicate.op)) {
+        if (!Array.isArray(predicate.value) || predicate.value.length === 0) {
+            return `${prefix}: ${predicate.op} value must be a non-empty list`;
+        }
+        if (!predicate.value.every((item) => valueMatchesScalarType(item, fieldType))) {
+            return `${prefix}: ${predicate.op} list items must be the same scalar type as field "${predicate.field}"`;
+        }
+    }
+    return undefined;
+}
+function routeIfFieldSchemaIssue(predicate, payloadSchema, stageId, targetId, pipelineId) {
+    const prefix = `Pipeline ${pipelineId}: stage "${stageId}": route "${targetId}" if`;
+    if ("all" in predicate && predicate.all !== undefined) {
+        for (const child of predicate.all) {
+            const issue = routeIfFieldSchemaIssue(child, payloadSchema, stageId, targetId, pipelineId);
+            if (issue !== undefined)
+                return issue;
+        }
+        return undefined;
+    }
+    if ("any" in predicate && predicate.any !== undefined) {
+        for (const child of predicate.any) {
+            const issue = routeIfFieldSchemaIssue(child, payloadSchema, stageId, targetId, pipelineId);
+            if (issue !== undefined)
+                return issue;
+        }
+        return undefined;
+    }
+    if ("not" in predicate && predicate.not !== undefined) {
+        return routeIfFieldSchemaIssue(predicate.not, payloadSchema, stageId, targetId, pipelineId);
+    }
+    if (!isRouteIfLeaf(predicate))
+        return `${prefix}: invalid predicate`;
+    return routeIfLeafSchemaIssue(predicate, payloadSchema, prefix);
+}
+function isForwardRouteEntry(entry) {
+    return !("type" in entry) || entry.type === undefined;
+}
+export function collectRouteIfIllegalCombos(_refs, _pipelineId) {
+    return [];
+}
+export function collectRouteIfSchemaIssues(stages, refs, pipelineId) {
+    const stageById = new Map(stages.map((stage) => [stage.id, stage]));
+    const issues = [];
+    for (const ref of refs) {
+        if (ref.route === undefined)
+            continue;
+        const source = stageById.get(ref.id);
+        for (const entry of ref.route) {
+            if (!("if" in entry) || entry.if === undefined)
+                continue;
+            const message = routeIfFieldSchemaIssue(entry.if, source?.payload_schema, ref.id, entry.to, pipelineId);
+            if (message === undefined)
+                continue;
+            issues.push({
+                code: "pipeline.route_if_invalid",
+                message,
+                category: "pipeline",
+                pipelineId,
+                stageId: ref.id,
+            });
+        }
+    }
+    return issues;
+}
+export function collectRouteAllGatedWarnings(refs, pipelineId) {
+    const issues = [];
+    for (const ref of refs) {
+        if (ref.route === undefined)
+            continue;
+        const forward = ref.route.filter((entry) => !("type" in entry) || entry.type === undefined);
+        if (forward.length === 0)
+            continue;
+        if (!forward.every((entry) => entry.if !== undefined))
+            continue;
+        issues.push({
+            code: "pipeline.route_all_gated",
+            message: `Pipeline ${pipelineId}: stage "${ref.id}": every forward route entry has if`,
+            category: "pipeline",
+            pipelineId,
+            stageId: ref.id,
+        });
+    }
+    return issues;
+}

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" | "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 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" | "pipeline.route_if_invalid" | "pipeline.route_all_gated" | "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;

package/dist/config/validateCatalog.js

@@ -69,7 +69,7 @@ function baseFinding(fields, severity) {
         ...(fields.stageId !== undefined ? { stageId: fields.stageId } : {}),
     };
 }
-function findingPipelineError(cwd, absPath, message, code, pipelineId) {
+function findingPipelineError(cwd, absPath, message, code, pipelineId, stageId) {
     return baseFinding({
         cwd,
         absPath,
@@ -77,6 +77,7 @@ function findingPipelineError(cwd, absPath, message, code, pipelineId) {
         code,
         category: "pipeline",
         pipelineId,
+        stageId,
     }, "error");
 }
 function findingStageError(cwd, absPath, message, code, stageId) {
@@ -110,7 +111,7 @@ function findingCatalog(cwd, absPath, message, code, severity) {
 export function findingsFromLoadIssues(cwd, absPath, issues) {
     return issues.flatMap((issue) => {
         if (issue.category === "pipeline") {
-            if (issue.code === "pipeline.model_applies") {
+            if (issue.code === "pipeline.model_applies" || issue.code === "pipeline.route_all_gated") {
                 return [
                     baseFinding({
                         cwd,
@@ -119,11 +120,12 @@ export function findingsFromLoadIssues(cwd, absPath, issues) {
                         code: issue.code,
                         category: "pipeline",
                         pipelineId: issue.pipelineId,
+                        stageId: issue.stageId,
                     }, "warning"),
                 ];
             }
             return [
-                findingPipelineError(cwd, absPath, issue.message, issue.code, issue.pipelineId),
+                findingPipelineError(cwd, absPath, issue.message, issue.code, issue.pipelineId, issue.stageId),
             ];
         }
         if (issue.category === "stage") {

package/dist/config/yamlDialect.d.ts

@@ -1,16 +1,14 @@
 import type { CompletionContract, RecoveryPolicy } from "../types/completion.js";
+import type { CompiledStageEmitBody } from "../types/stage.js";
 import { type LoadIssue, type LoadOutcome } from "./loadOutcome.js";
 export { LEGACY_CONTRACT_KEYS, LEGACY_KEY_REPLACEMENTS, dialectWarningForDocument, formatLegacyReplacements, legacyYamlIssue, presentLegacyKeys, } from "./legacyYaml.js";
 /** Target authoring keys. New catalog contracts belong here, not on the IR field names. */
 export declare const TARGET_CONTRACT_KEYS: Set<string>;
 /** Target wiring on a stage *file* is forbidden (`on_verify_fail`). `completion`/`recovery` are IR/legacy keys. */
-export declare const STAGE_FILE_WIRING_KEYS: readonly ["needs", "on_verify_fail", "completion", "recovery", "fork", "clonable"];
+export declare const STAGE_FILE_WIRING_KEYS: readonly ["needs", "on_verify_fail", "completion", "recovery", "fork", "route", "entry", "route_select", "allow_none", "clone_cap", "clone_mode"];
 export type YamlDialect = "legacy" | "target" | "invalid" | "neutral";
-/** Target YAML compiled onto IR field names (see file comment). */
-export type CompiledTargetContract = {
-    payload_schema?: unknown;
-    clone_input_schema?: unknown;
-    pre_emit_raw?: unknown[];
+/** Target YAML compiled onto typed emit/after/recovery IR fields (see file comment). */
+export type CompiledTargetContract = CompiledStageEmitBody & {
     completion?: CompletionContract;
     recovery?: RecoveryPolicy;
 };
@@ -24,6 +22,5 @@ export declare function compileTargetContract(raw: Record<string, unknown>, ctx:
     label: string;
     category: "pipeline" | "stage";
     deferSchemaRefs?: boolean;
+    requireIo?: boolean;
 }): LoadOutcome<CompiledTargetContract>;
-/** Strip target YAML keys and stamp IR `payload_schema` / `clone_input_schema` / `pre_emit_checks`. */
-export declare function applyCompiledBody(raw: Record<string, unknown>, compiled: CompiledTargetContract): Record<string, unknown>;

package/dist/config/yamlDialect.js

@@ -22,6 +22,7 @@ import path from "node:path";
 import { compilePayloadSchema, UnresolvedSchemaRefError, } from "../envelope/payloadSchema.js";
 import { loadFailure, loadSuccess } from "./loadOutcome.js";
 import { parseExecutionPolicy } from "./parseCompletionContract.js";
+import { parsePreEmitChecks } from "./parsePreEmitChecks.js";
 import { LEGACY_CONTRACT_KEYS } from "./legacyYaml.js";
 export { LEGACY_CONTRACT_KEYS, LEGACY_KEY_REPLACEMENTS, dialectWarningForDocument, formatLegacyReplacements, legacyYamlIssue, presentLegacyKeys, } from "./legacyYaml.js";
 /** Target authoring keys. New catalog contracts belong here, not on the IR field names. */
@@ -33,7 +34,12 @@ export const STAGE_FILE_WIRING_KEYS = [
     "completion",
     "recovery",
     "fork",
-    "clonable",
+    "route",
+    "entry",
+    "route_select",
+    "allow_none",
+    "clone_cap",
+    "clone_mode",
 ];
 function isPlainObject(value) {
     return typeof value === "object" && value !== null && !Array.isArray(value);
@@ -97,9 +103,12 @@ function invalidVerify(stageId, message, category) {
         },
     ]);
 }
-function parseIo(raw, label, stageId, deferSchemaRefs) {
-    if (raw === undefined)
-        return loadSuccess({});
+function parseIo(raw, label, stageId, deferSchemaRefs, requireIo) {
+    if (raw === undefined) {
+        if (!requireIo)
+            return loadSuccess({});
+        return invalidIo(label, "io is required", stageId);
+    }
     if (!isPlainObject(raw)) {
         return invalidIo(label, "io must be an object", stageId);
     }
@@ -108,14 +117,18 @@ function parseIo(raw, label, stageId, deferSchemaRefs) {
             return invalidIo(label, `io: unknown key "${key}"`, stageId);
         }
     }
+    if (raw.input === undefined) {
+        return invalidIo(label, "io.input.schema is required", stageId);
+    }
+    if (raw.output === undefined) {
+        return invalidIo(label, "io.output.schema is required", stageId);
+    }
     const result = {};
     for (const [field, target] of [
         ["output", "payload_schema"],
         ["input", "clone_input_schema"],
     ]) {
         const side = raw[field];
-        if (side === undefined)
-            continue;
         if (!isPlainObject(side)) {
             return invalidIo(label, `io.${field} must be an object`, stageId);
         }
@@ -124,8 +137,9 @@ function parseIo(raw, label, stageId, deferSchemaRefs) {
                 return invalidIo(label, `io.${field}: unknown key "${key}"`, stageId);
             }
         }
-        if (side.schema === undefined)
-            continue;
+        if (side.schema === undefined) {
+            return invalidIo(label, `io.${field}.schema is required`, stageId);
+        }
         if (side.schema === null || typeof side.schema !== "object" || Array.isArray(side.schema)) {
             return invalidIo(label, `io.${field}.schema must be an object`, stageId);
         }
@@ -158,6 +172,12 @@ function parseIo(raw, label, stageId, deferSchemaRefs) {
         else
             result.clone_input_schema = side.schema;
     }
+    if (result.payload_schema === undefined) {
+        return invalidIo(label, "io.output.schema is required", stageId);
+    }
+    if (result.clone_input_schema === undefined) {
+        return invalidIo(label, "io.input.schema is required", stageId);
+    }
     return loadSuccess(result);
 }
 const EMIT_LEGAL_TYPES = new Set(["gate", "artifact"]);
@@ -283,7 +303,7 @@ function parseVerifyList(raw, stageId, category) {
 }
 /** Compile target YAML (`io` / `verify` / `on_verify_fail`) onto IR fields. */
 export function compileTargetContract(raw, ctx) {
-    const ioOutcome = parseIo(raw.io, ctx.label, ctx.stageId, ctx.deferSchemaRefs === true);
+    const ioOutcome = parseIo(raw.io, ctx.label, ctx.stageId, ctx.deferSchemaRefs === true, ctx.requireIo !== false);
     if (!ioOutcome.ok)
         return ioOutcome;
     const verifyOutcome = parseVerifyList(raw.verify, ctx.stageId, ctx.category);
@@ -295,11 +315,16 @@ export function compileTargetContract(raw, ctx) {
     }, ctx.stageId, { requireCompletionForRecovery: false });
     if (!policyOutcome.ok)
         return policyOutcome;
+    let pre_emit_checks;
+    if (verifyOutcome.value.pre_emit_raw !== undefined) {
+        const preEmitOutcome = parsePreEmitChecks(verifyOutcome.value.pre_emit_raw, ctx.label);
+        if (!preEmitOutcome.ok)
+            return preEmitOutcome;
+        pre_emit_checks = preEmitOutcome.value;
+    }
     return loadSuccess({
         ...ioOutcome.value,
-        ...(verifyOutcome.value.pre_emit_raw !== undefined
-            ? { pre_emit_raw: verifyOutcome.value.pre_emit_raw }
-            : {}),
+        ...(pre_emit_checks !== undefined ? { pre_emit_checks } : {}),
         ...(policyOutcome.value.completion !== undefined
             ? { completion: policyOutcome.value.completion }
             : {}),
@@ -308,20 +333,3 @@ export function compileTargetContract(raw, ctx) {
             : {}),
     });
 }
-/** Strip target YAML keys and stamp IR `payload_schema` / `clone_input_schema` / `pre_emit_checks`. */
-export function applyCompiledBody(raw, compiled) {
-    const next = {};
-    for (const [key, value] of Object.entries(raw)) {
-        if (key === "io" || key === "verify" || key === "on_verify_fail")
-            continue;
-        next[key] = value;
-    }
-    if (compiled.payload_schema !== undefined)
-        next.payload_schema = compiled.payload_schema;
-    if (compiled.clone_input_schema !== undefined) {
-        next.clone_input_schema = compiled.clone_input_schema;
-    }
-    if (compiled.pre_emit_raw !== undefined)
-        next.pre_emit_checks = compiled.pre_emit_raw;
-    return next;
-}

package/dist/envelope/check.d.ts

@@ -1,5 +1,3 @@
 import { type StageEnvelope } from "../types/envelope.js";
-import type { CloneForkItem } from "../types/forkChoice.js";
-export declare function parseCloneForks(raw: unknown): CloneForkItem[];
 export declare function assertRequiredEnvelope(value: unknown, pathPrefix?: string): StageEnvelope;
 export declare function isAdvancingEnvelope(envelope: StageEnvelope): boolean;

package/dist/envelope/check.js

@@ -8,62 +8,6 @@ function qualifyEnvelopeMessage(pathPrefix, message) {
     }
     return `${pathPrefix}.${message}`;
 }
-function parseCloneForkItem(raw, index) {
-    if (raw === null || typeof raw !== "object" || Array.isArray(raw)) {
-        throw new EnvelopeError(`clone_forks[${index}] must be an object`);
-    }
-    const record = raw;
-    if (typeof record.successor_id !== "string") {
-        throw new EnvelopeError(`clone_forks[${index}].successor_id must be a string`);
-    }
-    const action = record.action;
-    if (action !== "skip" && action !== "once" && action !== "fanout") {
-        throw new EnvelopeError(`clone_forks[${index}].action must be "skip", "once", or "fanout"`);
-    }
-    const item = {
-        successor_id: record.successor_id,
-        action,
-    };
-    if (record.envelope !== undefined) {
-        const envelope = assertRequiredEnvelope(record.envelope, `clone_forks[${index}].envelope`);
-        if (envelope.feedback_loop !== undefined) {
-            throw new EnvelopeError(`clone_forks[${index}].envelope.feedback_loop is not allowed in clone assignment envelopes`);
-        }
-        item.envelope = envelope;
-    }
-    if (record.mode !== undefined) {
-        if (record.mode !== "parallel" && record.mode !== "sequential") {
-            throw new EnvelopeError(`clone_forks[${index}].mode must be "parallel" or "sequential"`);
-        }
-        item.mode = record.mode;
-    }
-    if (record.clones !== undefined) {
-        if (!Array.isArray(record.clones)) {
-            throw new EnvelopeError(`clone_forks[${index}].clones must be an array`);
-        }
-        item.clones = record.clones.map((clone, cloneIndex) => {
-            if (clone === null || typeof clone !== "object" || Array.isArray(clone)) {
-                throw new EnvelopeError(`clone_forks[${index}].clones[${cloneIndex}] must be an object`);
-            }
-            const cloneRecord = clone;
-            if (cloneRecord.envelope === undefined) {
-                throw new EnvelopeError(`clone_forks[${index}].clones[${cloneIndex}].envelope is required`);
-            }
-            const envelope = assertRequiredEnvelope(cloneRecord.envelope, `clone_forks[${index}].clones[${cloneIndex}].envelope`);
-            if (envelope.feedback_loop !== undefined) {
-                throw new EnvelopeError(`clone_forks[${index}].clones[${cloneIndex}].envelope.feedback_loop is not allowed in clone assignment envelopes`);
-            }
-            return { envelope };
-        });
-    }
-    return item;
-}
-export function parseCloneForks(raw) {
-    if (!Array.isArray(raw)) {
-        throw new EnvelopeError("clone_forks must be an array");
-    }
-    return raw.map((item, index) => parseCloneForkItem(item, index));
-}
 export function assertRequiredEnvelope(value, pathPrefix = "") {
     if (value === null || typeof value !== "object" || Array.isArray(value)) {
         throw new EnvelopeError(qualifyEnvelopeMessage(pathPrefix, "envelope must be an object"));
@@ -98,7 +42,7 @@ export function assertRequiredEnvelope(value, pathPrefix = "") {
         envelope.fork_choice = record.fork_choice;
     }
     if (record.clone_forks !== undefined) {
-        envelope.clone_forks = parseCloneForks(record.clone_forks);
+        throw new EnvelopeError(qualifyEnvelopeMessage(pathPrefix, '"clone_forks" is no longer supported — use a Clone Chain instead'));
     }
     if (record.feedback_loop !== undefined) {
         if (record.feedback_loop === null ||

package/dist/envelope/feedbackLoop.js

@@ -22,9 +22,6 @@ export function assertFeedbackLoopAction(envelope, context) {
     if (envelope.fork_choice !== undefined) {
         throw new EnvelopeError("feedback_loop send_back cannot be combined with fork_choice");
     }
-    if (envelope.clone_forks !== undefined) {
-        throw new EnvelopeError("feedback_loop send_back cannot be combined with clone_forks");
-    }
     if (action.target !== context.target) {
         throw new EnvelopeError(`feedback_loop.target "${action.target}" is not an allowed feedback-loop target`);
     }

package/dist/envelope/forkChoice.js

@@ -7,7 +7,7 @@ function assertForkChoiceLegality(choices, forkEmitContext) {
     const { immediateSuccessorIds, forkShape } = forkEmitContext;
     for (const id of choices) {
         if (!immediateSuccessorIds.includes(id)) {
-            throw new EnvelopeError(`fork_choice contains non-immediate successor: ${id}; clonable successors belong in clone_forks`);
+            throw new EnvelopeError(`fork_choice contains non-immediate successor: ${id}`);
         }
     }
     if (choices.length === 0) {

package/dist/envelope/payloadSchema.d.ts

@@ -39,6 +39,15 @@ export declare function compilePayloadSchema(raw: unknown, options?: CompilePayl
  */
 export declare function isPayloadSchemaSubset(consumer: unknown, producer: unknown, options?: CompilePayloadSchemaOptions): boolean;
 export declare function expandPayloadSchemaRefs(raw: unknown, options?: CompilePayloadSchemaOptions): unknown;
+export type PayloadSchemaFieldPathIssue = "empty_segment" | "array_index" | "missing" | "optional" | "untyped";
+export type PayloadSchemaFieldPathResult = {
+    ok: true;
+    type: string;
+} | {
+    ok: false;
+    issue: PayloadSchemaFieldPathIssue;
+};
+export declare function resolvePayloadSchemaFieldPath(schema: unknown, field: string, options?: CompilePayloadSchemaOptions): PayloadSchemaFieldPathResult;
 export declare function payloadInstanceMismatch(instance: unknown, payloadSchema: unknown, options?: CompilePayloadSchemaOptions): string | undefined;
 export declare function assertEnvelopePayload(envelope: StageEnvelope, payloadSchema: unknown | undefined, options?: CompilePayloadSchemaOptions): void;
 /**
@@ -46,3 +55,8 @@ export declare function assertEnvelopePayload(envelope: StageEnvelope, payloadSc
  * `clone_input_schema` (YAML: `io.input.schema`).
  */
 export declare function assertCloneAssignmentPayload(envelope: StageEnvelope, cloneInputSchema: unknown, successorId: string, itemPath?: string, options?: CompilePayloadSchemaOptions): void;
+/**
+ * Validate a predecessor success payload against the child's IR
+ * `clone_input_schema` (YAML: `io.input.schema`) on a normal pipeline edge.
+ */
+export declare function assertPriorInputPayload(envelope: StageEnvelope, cloneInputSchema: unknown, childId: string, options?: CompilePayloadSchemaOptions): void;