stageflow 0.8.0 → 0.12.0

package/dist/config/resolvePipelineDag.js

@@ -1,4 +1,6 @@
 import { isAllowedPipelineStageEntryKey } from "./pipelineStageKeys.js";
+import { parseExecutionPolicy } from "./parseCompletionContract.js";
+import { parsePipelineNeeds, predecessorEdges, toNeedEdges } from "./pipelineNeeds.js";
 const ALLOWED_FORK_KEYS = new Set(["select", "allow_none"]);
 function pipelineLabel(ctx) {
     return `Pipeline ${ctx.pipelineId} (${ctx.path})`;
@@ -9,6 +11,44 @@ function formatError(ctx, message) {
 function isPlainObject(value) {
     return typeof value === "object" && value !== null && !Array.isArray(value);
 }
+const ALLOWED_FEEDBACK_LOOP_KEYS = new Set([
+    "target",
+    "max_replays",
+    "on_max_replays",
+    "replay_session",
+]);
+export function parseFeedbackLoopConfig(value, stageId, ctx) {
+    if (!isPlainObject(value)) {
+        throw new Error(formatError(ctx, `stage "${stageId}": feedback_loop must be an object`));
+    }
+    for (const key of Object.keys(value)) {
+        if (!ALLOWED_FEEDBACK_LOOP_KEYS.has(key)) {
+            throw new Error(formatError(ctx, `stage "${stageId}": feedback_loop: unknown key "${key}"`));
+        }
+    }
+    if (Array.isArray(value.target)) {
+        throw new Error(formatError(ctx, `stage "${stageId}": feedback_loop.target must be a single stage id string, not an array`));
+    }
+    if (typeof value.target !== "string" || value.target.trim() === "") {
+        throw new Error(formatError(ctx, `stage "${stageId}": feedback_loop.target must be a non-empty stage id`));
+    }
+    if (!Number.isInteger(value.max_replays) || value.max_replays < 1) {
+        throw new Error(formatError(ctx, `stage "${stageId}": feedback_loop.max_replays must be a positive integer`));
+    }
+    if (value.on_max_replays !== "require_continue" &&
+        value.on_max_replays !== "wait_for_human") {
+        throw new Error(formatError(ctx, `stage "${stageId}": feedback_loop.on_max_replays must be "require_continue" or "wait_for_human"`));
+    }
+    if (value.replay_session !== "resume" && value.replay_session !== "new_session") {
+        throw new Error(formatError(ctx, `stage "${stageId}": feedback_loop.replay_session must be "resume" or "new_session"`));
+    }
+    return {
+        target: value.target,
+        max_replays: value.max_replays,
+        on_max_replays: value.on_max_replays,
+        replay_session: value.replay_session,
+    };
+}
 export function parsePipelineStageEntries(raw, ctx) {
     if (!Array.isArray(raw)) {
         throw new Error(formatError(ctx, "stages[] is required"));
@@ -53,41 +93,69 @@ export function parsePipelineStageEntries(raw, ctx) {
             ...(entry.clonable !== undefined ? { clonable: entry.clonable } : {}),
             ...(entry.clone_cap !== undefined ? { clone_cap: entry.clone_cap } : {}),
         };
+        const policyOutcome = parseExecutionPolicy(entry, entry.id);
+        if (!policyOutcome.ok) {
+            throw new Error(formatError(ctx, policyOutcome.issues[0]?.message ?? "invalid execution policy"));
+        }
+        const policyFields = {
+            ...(policyOutcome.value.completion !== undefined
+                ? { completion: policyOutcome.value.completion }
+                : {}),
+            ...(policyOutcome.value.recovery !== undefined
+                ? { recovery: policyOutcome.value.recovery }
+                : {}),
+        };
+        const feedbackLoopFields = entry.feedback_loop !== undefined
+            ? { feedback_loop: parseFeedbackLoopConfig(entry.feedback_loop, entry.id, ctx) }
+            : {};
+        if (entry.replay_safe !== undefined && typeof entry.replay_safe !== "boolean") {
+            throw new Error(formatError(ctx, `stage "${entry.id}": replay_safe must be a boolean`));
+        }
+        const replaySafetyFields = entry.replay_safe !== undefined ? { replay_safe: entry.replay_safe } : {};
         if (entry.needs === undefined) {
             entries.push({
                 id: entry.id,
                 ...(forkValue !== undefined ? { fork: forkValue } : {}),
                 ...clonableFields,
+                ...policyFields,
+                ...feedbackLoopFields,
+                ...replaySafetyFields,
             });
             continue;
         }
-        if (Array.isArray(entry.needs)) {
-            if (entry.needs.length > 1) {
-                throw new Error(formatError(ctx, `stage "${entry.id}": fan-in not supported; needs must be a single stage id`));
-            }
-            throw new Error(formatError(ctx, `stage "${entry.id}": needs must be a string, not an array`));
-        }
-        if (typeof entry.needs !== "string" || !entry.needs) {
-            throw new Error(formatError(ctx, `stage "${entry.id}": needs must be a non-empty string`));
+        const parsedNeeds = parsePipelineNeeds(entry.needs, entry.id);
+        if (!parsedNeeds.ok) {
+            throw new Error(formatError(ctx, parsedNeeds.message));
         }
         entries.push({
             id: entry.id,
-            needs: entry.needs,
+            needs: parsedNeeds.value,
             ...(forkValue !== undefined ? { fork: forkValue } : {}),
             ...clonableFields,
+            ...policyFields,
+            ...feedbackLoopFields,
+            ...replaySafetyFields,
         });
     }
     return entries;
 }
 function normalizeToEdges(entries) {
-    return entries.map((entry, index) => ({
-        id: entry.id,
-        needs: entry.needs ?? null,
-        stageIndex: index,
-        ...(entry.fork !== undefined ? { fork: entry.fork } : {}),
-        ...(entry.clonable !== undefined ? { clonable: entry.clonable } : {}),
-        ...(entry.clone_cap !== undefined ? { clone_cap: entry.clone_cap } : {}),
-    }));
+    return entries.map((entry, index) => {
+        const needsEdges = toNeedEdges(entry.needs);
+        return {
+            id: entry.id,
+            needs: needsEdges.length === 1 ? needsEdges[0].id : null,
+            needsEdges,
+            stageIndex: index,
+            ...(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 } : {}),
+        };
+    });
 }
 function detectDuplicateIds(edges, ctx) {
     const seen = new Set();
@@ -101,8 +169,10 @@ function detectDuplicateIds(edges, ctx) {
 function validateNeedsTargets(edges, ctx) {
     const declared = new Set(edges.map((edge) => edge.id));
     for (const edge of edges) {
-        if (edge.needs !== null && !declared.has(edge.needs)) {
-            throw new Error(formatError(ctx, `stage "${edge.id}" has unknown needs "${edge.needs}"`));
+        for (const parent of edge.needsEdges) {
+            if (!declared.has(parent.id)) {
+                throw new Error(formatError(ctx, `stage "${edge.id}" has unknown needs "${parent.id}"`));
+            }
         }
     }
 }
@@ -114,10 +184,10 @@ function detectCycle(edges, ctx) {
         children.set(edge.id, []);
     }
     for (const edge of edges) {
-        if (edge.needs === null)
-            continue;
-        indegree.set(edge.id, (indegree.get(edge.id) ?? 0) + 1);
-        children.get(edge.needs)?.push(edge.id);
+        for (const parent of edge.needsEdges) {
+            indegree.set(edge.id, (indegree.get(edge.id) ?? 0) + 1);
+            children.get(parent.id)?.push(edge.id);
+        }
     }
     const queue = [];
     for (const [id, degree] of indegree) {
@@ -140,19 +210,31 @@ function detectCycle(edges, ctx) {
     }
 }
 function computeAncestors(edges) {
-    const needsById = new Map(edges.map((edge) => [edge.id, edge.needs]));
+    const parentsById = new Map(edges.map((edge) => [edge.id, edge.needsEdges]));
     const ancestorsById = new Map();
     function ancestorsFor(id) {
         const cached = ancestorsById.get(id);
         if (cached)
             return cached;
-        const needs = needsById.get(id) ?? null;
-        if (needs === null) {
+        const parents = parentsById.get(id) ?? [];
+        if (parents.length === 0) {
             ancestorsById.set(id, []);
             return [];
         }
-        const parentAncestors = ancestorsFor(needs);
-        const ancestors = [...parentAncestors, needs];
+        const seen = new Set();
+        const ancestors = [];
+        for (const parent of parents) {
+            for (const ancestor of ancestorsFor(parent.id)) {
+                if (seen.has(ancestor))
+                    continue;
+                seen.add(ancestor);
+                ancestors.push(ancestor);
+            }
+            if (!seen.has(parent.id)) {
+                seen.add(parent.id);
+                ancestors.push(parent.id);
+            }
+        }
         ancestorsById.set(id, ancestors);
         return ancestors;
     }
@@ -170,16 +252,16 @@ function topologicalSort(edges) {
         children.set(edge.id, []);
     }
     for (const edge of edges) {
-        if (edge.needs === null)
-            continue;
-        indegree.set(edge.id, (indegree.get(edge.id) ?? 0) + 1);
-        children.get(edge.needs)?.push(edge.id);
+        for (const parent of edge.needsEdges) {
+            indegree.set(edge.id, (indegree.get(edge.id) ?? 0) + 1);
+            children.get(parent.id)?.push(edge.id);
+        }
     }
     for (const [, childIds] of children) {
         childIds.sort((a, b) => (byId.get(a)?.stageIndex ?? 0) - (byId.get(b)?.stageIndex ?? 0));
     }
     const roots = edges
-        .filter((edge) => edge.needs === null)
+        .filter((edge) => edge.needsEdges.length === 0)
         .sort((a, b) => a.stageIndex - b.stageIndex)
         .map((edge) => edge.id);
     const sorted = [];
@@ -206,8 +288,8 @@ function buildResolvedPipelineDag(edges) {
         childrenOf[edge.id] = [];
     }
     for (const edge of edges) {
-        if (edge.needs !== null) {
-            childrenOf[edge.needs].push(edge.id);
+        for (const parent of edge.needsEdges) {
+            childrenOf[parent.id].push(edge.id);
         }
     }
     for (const id of Object.keys(childrenOf)) {
@@ -215,12 +297,13 @@ function buildResolvedPipelineDag(edges) {
             (edges.find((edge) => edge.id === b)?.stageIndex ?? 0));
     }
     const roots = edges
-        .filter((edge) => edge.needs === null)
+        .filter((edge) => edge.needsEdges.length === 0)
         .sort((a, b) => a.stageIndex - b.stageIndex)
         .map((edge) => edge.id);
     const nodes = sortedEdges.map((edge) => ({
         id: edge.id,
         needs: edge.needs,
+        needsEdges: edge.needsEdges,
         ancestors: ancestorsById.get(edge.id) ?? [],
         stageIndex: edge.stageIndex,
         ...(edge.fork !== undefined
@@ -229,6 +312,10 @@ function buildResolvedPipelineDag(edges) {
         ...(edge.clonable === true
             ? { clonable: true, clone_cap: edge.clone_cap ?? 5 }
             : {}),
+        ...(edge.completion !== undefined ? { completion: edge.completion } : {}),
+        ...(edge.recovery !== undefined ? { recovery: edge.recovery } : {}),
+        ...(edge.feedback_loop !== undefined ? { feedback_loop: edge.feedback_loop } : {}),
+        ...(edge.replay_safe !== undefined ? { replay_safe: edge.replay_safe } : {}),
     }));
     return { nodes, roots, childrenOf };
 }
@@ -259,6 +346,34 @@ function validateClonableFields(edges, dag, ctx) {
         }
     }
 }
+function validateFeedbackLoopFields(dag, ctx) {
+    const byId = new Map(dag.nodes.map((node) => [node.id, node]));
+    for (const source of dag.nodes) {
+        const policy = source.feedback_loop;
+        if (!policy)
+            continue;
+        if (source.clonable === true) {
+            throw new Error(formatError(ctx, `stage "${source.id}": feedback_loop source cannot be clonable`));
+        }
+        const targetId = policy.target;
+        const target = byId.get(targetId);
+        if (!target) {
+            throw new Error(formatError(ctx, `stage "${source.id}": feedback_loop target "${targetId}" is not declared`));
+        }
+        if (!source.ancestors.includes(targetId)) {
+            throw new Error(formatError(ctx, `stage "${source.id}": feedback_loop target "${targetId}" must be an earlier ancestor`));
+        }
+        if (target.clonable === true) {
+            throw new Error(formatError(ctx, `stage "${source.id}": feedback_loop target "${targetId}" cannot be clonable`));
+        }
+        const targetIndex = source.ancestors.indexOf(targetId);
+        const route = [...source.ancestors.slice(targetIndex), source.id];
+        const unsafeStage = route.find((stageId) => byId.get(stageId)?.replay_safe === false);
+        if (unsafeStage !== undefined) {
+            throw new Error(formatError(ctx, `stage "${source.id}": feedback_loop target "${targetId}" replays replay_safe: false stage "${unsafeStage}"`));
+        }
+    }
+}
 export function resolvePipelineDagFromRefs(refs, ctx) {
     const edges = normalizeToEdges(refs);
     detectDuplicateIds(edges, ctx);
@@ -271,6 +386,7 @@ export function resolvePipelineDagFromRefs(refs, ctx) {
     const dag = buildResolvedPipelineDag(edges);
     validateForkFields(edges, dag, ctx);
     validateClonableFields(edges, dag, ctx);
+    validateFeedbackLoopFields(dag, ctx);
     return { stages, dag };
 }
 export function resolvePipelineDag(rawStages, ctx) {
@@ -293,12 +409,40 @@ export function areResolvedDagsEquivalent(a, b) {
         const nodeB = byIdB.get(id);
         if (nodeA.needs !== nodeB.needs)
             return false;
+        const edgesA = predecessorEdges(nodeA);
+        const edgesB = predecessorEdges(nodeB);
+        if (edgesA.length !== edgesB.length)
+            return false;
+        for (let i = 0; i < edgesA.length; i++) {
+            if (edgesA[i].id !== edgesB[i].id)
+                return false;
+            if (edgesA[i].on.length !== edgesB[i].on.length)
+                return false;
+            for (let j = 0; j < edgesA[i].on.length; j++) {
+                if (edgesA[i].on[j] !== edgesB[i].on[j])
+                    return false;
+            }
+        }
         if (nodeA.ancestors.length !== nodeB.ancestors.length)
             return false;
         for (let i = 0; i < nodeA.ancestors.length; i++) {
             if (nodeA.ancestors[i] !== nodeB.ancestors[i])
                 return false;
         }
+        if ((nodeA.replay_safe ?? true) !== (nodeB.replay_safe ?? true))
+            return false;
+        if (nodeA.feedback_loop?.max_replays !== nodeB.feedback_loop?.max_replays) {
+            return false;
+        }
+        if (nodeA.feedback_loop?.on_max_replays !==
+            nodeB.feedback_loop?.on_max_replays) {
+            return false;
+        }
+        if (nodeA.feedback_loop?.replay_session !== nodeB.feedback_loop?.replay_session) {
+            return false;
+        }
+        if (nodeA.feedback_loop?.target !== nodeB.feedback_loop?.target)
+            return false;
     }
     return true;
 }
@@ -321,9 +465,8 @@ export function extractPipelineStageIds(rawStages) {
         if (typeof entry.id !== "string" || !entry.id)
             return null;
         if (entry.needs !== undefined) {
-            if (Array.isArray(entry.needs))
-                return null;
-            if (typeof entry.needs !== "string" || !entry.needs)
+            const parsedNeeds = parsePipelineNeeds(entry.needs, entry.id);
+            if (!parsedNeeds.ok)
                 return null;
         }
         stageIds.push(entry.id);

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.include_cycle" | "pipeline.include_invalid" | "pipeline.include_duplicate_stage" | "stage.invalid_shape" | "stage.invalid_payload_schema" | "stage.invalid_gate_kinds" | "stage.invalid_skill" | "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";
+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_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";
 export type ValidationFinding = {
     severity: ValidationSeverity;
     code: ValidationFindingCode | string;

package/dist/config/validateCompletionContract.d.ts

@@ -0,0 +1,4 @@
+import type { CompletionContract } from "../types/completion.js";
+import type { StageConfig } from "../types/stage.js";
+import { type LoadOutcome } from "./loadOutcome.js";
+export declare function validateCompletionContractForStage(stage: StageConfig, completion: CompletionContract | undefined): LoadOutcome<void>;

package/dist/config/validateCompletionContract.js

@@ -0,0 +1,52 @@
+import { loadFailure, loadSuccess } from "./loadOutcome.js";
+function failure(stageId, message) {
+    return loadFailure([
+        {
+            code: "pipeline.invalid_completion",
+            message: `Stage "${stageId}" completion: ${message}`,
+            category: "pipeline",
+        },
+    ]);
+}
+function isRequiredStringArrayField(schema, field) {
+    if (!schema || typeof schema !== "object" || Array.isArray(schema))
+        return false;
+    const root = schema;
+    if (!Array.isArray(root.required) || !root.required.includes(field))
+        return false;
+    if (!root.properties || typeof root.properties !== "object" || Array.isArray(root.properties)) {
+        return false;
+    }
+    const property = root.properties[field];
+    if (!property || typeof property !== "object" || Array.isArray(property))
+        return false;
+    const arraySchema = property;
+    if (arraySchema.type !== "array")
+        return false;
+    const items = arraySchema.items;
+    return Boolean(items &&
+        typeof items === "object" &&
+        !Array.isArray(items) &&
+        items.type === "string");
+}
+export function validateCompletionContractForStage(stage, completion) {
+    if (!completion)
+        return loadSuccess(undefined);
+    for (const check of completion.checks) {
+        if (check.type === "payload_schema" && stage.payload_schema === undefined) {
+            return failure(stage.id, `check "${check.id}" requires the stage to declare payload_schema`);
+        }
+        if (check.type === "gate" &&
+            !stage.gate_kinds?.includes(check.kind)) {
+            return failure(stage.id, `gate check "${check.id}" requires gate_kinds to include "${check.kind}"`);
+        }
+        if (check.type === "checkout_changes") {
+            for (const field of check.path_fields ?? []) {
+                if (!isRequiredStringArrayField(stage.payload_schema, field)) {
+                    return failure(stage.id, `checkout check "${check.id}" path field "${field}" must be a required array of strings in payload_schema`);
+                }
+            }
+        }
+    }
+    return loadSuccess(undefined);
+}

package/dist/envelope/check.d.ts

@@ -1,5 +1,5 @@
 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): StageEnvelope;
+export declare function assertRequiredEnvelope(value: unknown, pathPrefix?: string): StageEnvelope;
 export declare function isAdvancingEnvelope(envelope: StageEnvelope): boolean;

package/dist/envelope/check.js

@@ -1,4 +1,13 @@
 import { EnvelopeError, } from "../types/envelope.js";
+function qualifyEnvelopeMessage(pathPrefix, message) {
+    if (!pathPrefix) {
+        return message;
+    }
+    if (message === "envelope must be an object") {
+        return `${pathPrefix} must be an object`;
+    }
+    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`);
@@ -16,7 +25,11 @@ function parseCloneForkItem(raw, index) {
         action,
     };
     if (record.envelope !== undefined) {
-        item.envelope = assertRequiredEnvelope(record.envelope);
+        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") {
@@ -36,7 +49,11 @@ function parseCloneForkItem(raw, index) {
             if (cloneRecord.envelope === undefined) {
                 throw new EnvelopeError(`clone_forks[${index}].clones[${cloneIndex}].envelope is required`);
             }
-            return { envelope: assertRequiredEnvelope(cloneRecord.envelope) };
+            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;
@@ -47,26 +64,26 @@ export function parseCloneForks(raw) {
     }
     return raw.map((item, index) => parseCloneForkItem(item, index));
 }
-export function assertRequiredEnvelope(value) {
+export function assertRequiredEnvelope(value, pathPrefix = "") {
     if (value === null || typeof value !== "object" || Array.isArray(value)) {
-        throw new EnvelopeError("envelope must be an object");
+        throw new EnvelopeError(qualifyEnvelopeMessage(pathPrefix, "envelope must be an object"));
     }
     const record = value;
     const status = record.status;
     if (status !== "success" && status !== "failure") {
-        throw new EnvelopeError('status must be "success" or "failure"');
+        throw new EnvelopeError(qualifyEnvelopeMessage(pathPrefix, 'status must be "success" or "failure"'));
     }
     if (typeof record.summary !== "string" || record.summary.trim() === "") {
-        throw new EnvelopeError("summary must be a non-empty string");
+        throw new EnvelopeError(qualifyEnvelopeMessage(pathPrefix, "summary must be a non-empty string"));
     }
     if (!("artifacts" in record)) {
-        throw new EnvelopeError("artifacts field is required");
+        throw new EnvelopeError(qualifyEnvelopeMessage(pathPrefix, "artifacts field is required"));
     }
     if (!Array.isArray(record.artifacts)) {
-        throw new EnvelopeError("artifacts must be an array");
+        throw new EnvelopeError(qualifyEnvelopeMessage(pathPrefix, "artifacts must be an array"));
     }
     if (!record.artifacts.every((item) => typeof item === "string")) {
-        throw new EnvelopeError("artifacts must be an array of strings");
+        throw new EnvelopeError(qualifyEnvelopeMessage(pathPrefix, "artifacts must be an array of strings"));
     }
     const envelope = {
         status,
@@ -76,30 +93,86 @@ export function assertRequiredEnvelope(value) {
     if (record.fork_choice !== undefined) {
         if (!Array.isArray(record.fork_choice) ||
             !record.fork_choice.every((item) => typeof item === "string")) {
-            throw new EnvelopeError("fork_choice must be an array of strings");
+            throw new EnvelopeError(qualifyEnvelopeMessage(pathPrefix, "fork_choice must be an array of strings"));
         }
         envelope.fork_choice = record.fork_choice;
     }
     if (record.clone_forks !== undefined) {
         envelope.clone_forks = parseCloneForks(record.clone_forks);
     }
+    if (record.feedback_loop !== undefined) {
+        if (record.feedback_loop === null ||
+            typeof record.feedback_loop !== "object" ||
+            Array.isArray(record.feedback_loop)) {
+            throw new EnvelopeError(qualifyEnvelopeMessage(pathPrefix, "feedback_loop must be an object"));
+        }
+        const feedbackLoop = record.feedback_loop;
+        if (feedbackLoop.action === "continue") {
+            for (const key of Object.keys(feedbackLoop)) {
+                if (key !== "action" && key !== "target") {
+                    throw new EnvelopeError(qualifyEnvelopeMessage(pathPrefix, `feedback_loop: unknown key "${key}"`));
+                }
+            }
+            if (feedbackLoop.target !== undefined) {
+                throw new EnvelopeError(qualifyEnvelopeMessage(pathPrefix, "feedback_loop.target is not allowed for action continue"));
+            }
+            envelope.feedback_loop = { action: "continue" };
+        }
+        else if (feedbackLoop.action === "send_back") {
+            for (const key of Object.keys(feedbackLoop)) {
+                if (key !== "action" && key !== "target") {
+                    throw new EnvelopeError(qualifyEnvelopeMessage(pathPrefix, `feedback_loop: unknown key "${key}"`));
+                }
+            }
+            if (typeof feedbackLoop.target !== "string" || feedbackLoop.target.trim() === "") {
+                throw new EnvelopeError(qualifyEnvelopeMessage(pathPrefix, "feedback_loop.target must be a non-empty string for action send_back"));
+            }
+            envelope.feedback_loop = { action: "send_back", target: feedbackLoop.target };
+        }
+        else {
+            throw new EnvelopeError(qualifyEnvelopeMessage(pathPrefix, 'feedback_loop.action must be "continue" or "send_back"'));
+        }
+    }
+    if (record.checklist_attestations !== undefined) {
+        if (!Array.isArray(record.checklist_attestations)) {
+            throw new EnvelopeError("checklist_attestations must be an array");
+        }
+        const ids = new Set();
+        envelope.checklist_attestations = record.checklist_attestations.map((value, index) => {
+            if (value === null || typeof value !== "object" || Array.isArray(value)) {
+                throw new EnvelopeError(`checklist_attestations[${index}] must be an object`);
+            }
+            const attestation = value;
+            if (typeof attestation.check_id !== "string" || attestation.check_id.trim() === "") {
+                throw new EnvelopeError(`checklist_attestations[${index}].check_id must be a non-empty string`);
+            }
+            if (ids.has(attestation.check_id)) {
+                throw new EnvelopeError(`checklist_attestations contains duplicate check_id "${attestation.check_id}"`);
+            }
+            ids.add(attestation.check_id);
+            if (!Array.isArray(attestation.items) || !attestation.items.every((item) => typeof item === "string")) {
+                throw new EnvelopeError(`checklist_attestations[${index}].items must be an array of strings`);
+            }
+            return { check_id: attestation.check_id, items: attestation.items };
+        });
+    }
     if (record.payload !== undefined) {
         if (record.payload === null ||
             typeof record.payload !== "object" ||
             Array.isArray(record.payload)) {
-            throw new EnvelopeError("payload must be an object when present");
+            throw new EnvelopeError(qualifyEnvelopeMessage(pathPrefix, "payload must be an object when present"));
         }
         envelope.payload = record.payload;
     }
     if (record.stage_id !== undefined) {
         if (typeof record.stage_id !== "string") {
-            throw new EnvelopeError("stage_id must be a string when present");
+            throw new EnvelopeError(qualifyEnvelopeMessage(pathPrefix, "stage_id must be a string when present"));
         }
         envelope.stage_id = record.stage_id;
     }
     if (record.notes !== undefined) {
         if (typeof record.notes !== "string") {
-            throw new EnvelopeError("notes must be a string when present");
+            throw new EnvelopeError(qualifyEnvelopeMessage(pathPrefix, "notes must be a string when present"));
         }
         envelope.notes = record.notes;
     }

package/dist/envelope/cloneForks.d.ts

@@ -1,2 +1,2 @@
-import type { CloneEmitContext } from "../types/forkChoice.js";
+import { type CloneEmitContext } from "../types/forkChoice.js";
 export declare function assertCloneForks(params: unknown, cloneEmitContext: CloneEmitContext): void;