stageflow 0.9.0 → 0.12.0

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;

package/dist/envelope/cloneForks.js

@@ -1,5 +1,7 @@
 import { parseCloneForks } from "./check.js";
+import { assertCloneAssignmentPayload } from "./payloadSchema.js";
 import { EnvelopeError } from "../types/envelope.js";
+import { CLONE_ACTIONS } from "../types/forkChoice.js";
 function fieldPresent(item, key) {
     return item[key] !== undefined;
 }
@@ -17,40 +19,53 @@ export function assertCloneForks(params, cloneEmitContext) {
     const expectedIds = cloneEmitContext.clonableSuccessors.map((s) => s.successorId);
     const expectedSet = new Set(expectedIds);
     const seen = new Set();
-    for (const item of items) {
+    for (const [i, item] of items.entries()) {
+        const itemPath = `clone_forks[${i}]`;
         if (seen.has(item.successor_id)) {
-            throw new EnvelopeError(`clone_forks contains duplicate successor_id: ${item.successor_id}`);
+            throw new EnvelopeError(`${itemPath} contains duplicate successor_id: ${item.successor_id}`);
         }
         if (!expectedSet.has(item.successor_id)) {
-            throw new EnvelopeError(`clone_forks contains extra successor_id: ${item.successor_id}`);
+            throw new EnvelopeError(`${itemPath} contains extra successor_id: ${item.successor_id}`);
         }
         seen.add(item.successor_id);
         const capEntry = cloneEmitContext.clonableSuccessors.find((s) => s.successorId === item.successor_id);
         const cloneCap = capEntry?.cloneCap;
+        const allowedActions = cloneEmitContext.allowedActions ?? [...CLONE_ACTIONS];
+        if (!allowedActions.includes(item.action)) {
+            throw new EnvelopeError(`${itemPath} action "${item.action}" is not allowed for ${item.successor_id} (allowed: ${allowedActions.join(", ")})`);
+        }
         if (item.action === "skip") {
             if (fieldPresent(item, "envelope") ||
                 fieldPresent(item, "mode") ||
                 fieldPresent(item, "clones")) {
-                throw new EnvelopeError(`clone_forks skip for ${item.successor_id} must not include envelope, mode, or clones`);
+                throw new EnvelopeError(`${itemPath} skip for ${item.successor_id} must not include envelope, mode, or clones`);
             }
         }
         else if (item.action === "once") {
             if (!fieldPresent(item, "envelope")) {
-                throw new EnvelopeError(`clone_forks once for ${item.successor_id} requires envelope`);
+                throw new EnvelopeError(`${itemPath} once for ${item.successor_id} requires envelope`);
             }
             if (fieldPresent(item, "mode") || fieldPresent(item, "clones")) {
-                throw new EnvelopeError(`clone_forks once for ${item.successor_id} must not include mode or clones`);
+                throw new EnvelopeError(`${itemPath} once for ${item.successor_id} must not include mode or clones`);
+            }
+            if (capEntry?.cloneInputSchema !== undefined) {
+                assertCloneAssignmentPayload(item.envelope, capEntry.cloneInputSchema, item.successor_id, `${itemPath}.envelope`);
             }
         }
         else if (item.action === "fanout") {
             if (fieldPresent(item, "envelope")) {
-                throw new EnvelopeError(`clone_forks fanout for ${item.successor_id} must not include a top-level envelope`);
+                throw new EnvelopeError(`${itemPath} fanout for ${item.successor_id} must not include a top-level envelope`);
             }
             if (!fieldPresent(item, "mode") || !fieldPresent(item, "clones") || item.clones === undefined) {
-                throw new EnvelopeError(`clone_forks fanout for ${item.successor_id} requires mode and clones`);
+                throw new EnvelopeError(`${itemPath} fanout for ${item.successor_id} requires mode and clones`);
             }
             if (cloneCap === undefined || item.clones.length < 2 || item.clones.length > cloneCap) {
-                throw new EnvelopeError(`clone_forks fanout for ${item.successor_id} must have between 2 and ${cloneCap} clones`);
+                throw new EnvelopeError(`${itemPath} fanout for ${item.successor_id} must have between 2 and ${cloneCap} clones`);
+            }
+            if (capEntry?.cloneInputSchema !== undefined) {
+                for (const [j, clone] of item.clones.entries()) {
+                    assertCloneAssignmentPayload(clone.envelope, capEntry.cloneInputSchema, item.successor_id, `${itemPath}.clones[${j}].envelope`);
+                }
             }
         }
     }

package/dist/envelope/feedbackLoop.d.ts

@@ -0,0 +1,4 @@
+import { type StageEnvelope } from "../types/envelope.js";
+import type { FeedbackLoopConfig } from "../types/pipeline.js";
+/** Validates an action against the source stage's declared feedback-loop policy. */
+export declare function assertFeedbackLoopAction(envelope: StageEnvelope, context: FeedbackLoopConfig | undefined): void;

package/dist/envelope/feedbackLoop.js

@@ -0,0 +1,31 @@
+import { EnvelopeError } from "../types/envelope.js";
+/** Validates an action against the source stage's declared feedback-loop policy. */
+export function assertFeedbackLoopAction(envelope, context) {
+    if (context === undefined) {
+        if (envelope.feedback_loop !== undefined) {
+            throw new EnvelopeError("feedback_loop is only allowed for a configured feedback-loop stage");
+        }
+        return;
+    }
+    if (envelope.status === "failure") {
+        if (envelope.feedback_loop !== undefined) {
+            throw new EnvelopeError("feedback_loop action is not allowed when status is failure");
+        }
+        return;
+    }
+    const action = envelope.feedback_loop;
+    if (action === undefined) {
+        throw new EnvelopeError("feedback_loop action is required for a successful feedback-loop stage");
+    }
+    if (action.action === "continue")
+        return;
+    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/payloadSchema.d.ts

@@ -4,7 +4,13 @@ export type CompiledPayloadSchema = TSchema;
 /**
  * Compile a JSON Schema subset used for stage payload_schema.
  * Supported: type object/string/number/integer/boolean/array,
- * properties, required, items, additionalProperties (boolean).
+ * properties, required, items, additionalProperties (boolean),
+ * minItems, enum, minimum, maximum. String nodes also accept
+ * pattern (a JS RegExp validated with the unicode flag), minLength,
+ * and maxLength (non-negative integers). Nested nodes accept
+ * nullable (boolean), compiling to a union of that type with null;
+ * the root object cannot be nullable. Unknown keywords are ignored.
  */
 export declare function compilePayloadSchema(raw: unknown): CompiledPayloadSchema;
 export declare function assertEnvelopePayload(envelope: StageEnvelope, payloadSchema: unknown | undefined): void;
+export declare function assertCloneAssignmentPayload(envelope: StageEnvelope, cloneInputSchema: unknown, successorId: string, itemPath?: string): void;

package/dist/envelope/payloadSchema.js

@@ -1,6 +1,89 @@
 import { Type } from "typebox";
 import { Value } from "typebox/value";
 import { EnvelopeError } from "../types/envelope.js";
+function readEnum(schema, path, valueType) {
+    if (schema.enum === undefined) {
+        return undefined;
+    }
+    if (!Array.isArray(schema.enum) || schema.enum.length === 0) {
+        throw new Error(`${path}: enum must be a non-empty array when present`);
+    }
+    if (valueType === "string") {
+        if (!schema.enum.every((value) => typeof value === "string")) {
+            throw new Error(`${path}: enum values must be strings`);
+        }
+        return schema.enum;
+    }
+    if (!schema.enum.every((value) => typeof value === "number" && Number.isInteger(value))) {
+        throw new Error(`${path}: enum values must be integers`);
+    }
+    return schema.enum;
+}
+function readBound(value, path, keyword) {
+    if (value === undefined) {
+        return undefined;
+    }
+    if (typeof value !== "number" || !Number.isFinite(value)) {
+        throw new Error(`${path}: ${keyword} must be a number when present`);
+    }
+    return value;
+}
+function numericOptions(schema, path) {
+    const minimum = readBound(schema.minimum, path, "minimum");
+    const maximum = readBound(schema.maximum, path, "maximum");
+    if (minimum === undefined && maximum === undefined) {
+        return undefined;
+    }
+    return {
+        ...(minimum !== undefined ? { minimum } : {}),
+        ...(maximum !== undefined ? { maximum } : {}),
+    };
+}
+function readPattern(value, path) {
+    if (value === undefined) {
+        return undefined;
+    }
+    if (typeof value !== "string") {
+        throw new Error(`${path}: pattern must be a string when present`);
+    }
+    try {
+        // eslint-disable-next-line no-new
+        new RegExp(value, "u");
+    }
+    catch {
+        throw new Error(`${path}: pattern must be a valid regular expression`);
+    }
+    return value;
+}
+function readNonNegativeInt(value, path, keyword) {
+    if (value === undefined) {
+        return undefined;
+    }
+    if (typeof value !== "number" ||
+        !Number.isInteger(value) ||
+        value < 0) {
+        throw new Error(`${path}: ${keyword} must be a non-negative integer when present`);
+    }
+    return value;
+}
+function stringOptions(schema, path) {
+    const pattern = readPattern(schema.pattern, path);
+    const minLength = readNonNegativeInt(schema.minLength, path, "minLength");
+    const maxLength = readNonNegativeInt(schema.maxLength, path, "maxLength");
+    if (minLength !== undefined &&
+        maxLength !== undefined &&
+        minLength > maxLength) {
+        throw new Error(`${path}: minLength must be <= maxLength`);
+    }
+    if (pattern === undefined && minLength === undefined && maxLength === undefined) {
+        return undefined;
+    }
+    return {
+        ...(pattern !== undefined ? { pattern } : {}),
+        ...(minLength !== undefined ? { minLength } : {}),
+        ...(maxLength !== undefined ? { maxLength } : {}),
+    };
+}
 function compileNode(node, path) {
     if (node === null || typeof node !== "object" || Array.isArray(node)) {
         throw new Error(`${path}: schema must be an object`);
@@ -9,20 +92,58 @@ function compileNode(node, path) {
     if (typeof schema.type !== "string") {
         throw new Error(`${path}: type is required`);
     }
+    if (schema.nullable !== undefined && typeof schema.nullable !== "boolean") {
+        throw new Error(`${path}: nullable must be a boolean when present`);
+    }
+    const nullable = schema.nullable === true;
+    let base;
     switch (schema.type) {
-        case "string":
-            return Type.String();
-        case "number":
-            return Type.Number();
-        case "integer":
-            return Type.Integer();
+        case "string": {
+            const enumerated = readEnum(schema, path, "string");
+            const opts = stringOptions(schema, path);
+            base =
+                enumerated !== undefined
+                    ? Type.Enum(enumerated, opts)
+                    : opts !== undefined
+                        ? Type.String(opts)
+                        : Type.String();
+            break;
+        }
+        case "number": {
+            const options = numericOptions(schema, path);
+            base = options !== undefined ? Type.Number(options) : Type.Number();
+            break;
+        }
+        case "integer": {
+            const enumerated = readEnum(schema, path, "integer");
+            const options = numericOptions(schema, path);
+            if (enumerated !== undefined) {
+                base = Type.Enum(enumerated, options);
+            }
+            else {
+                base = options !== undefined ? Type.Integer(options) : Type.Integer();
+            }
+            break;
+        }
         case "boolean":
-            return Type.Boolean();
+            base = Type.Boolean();
+            break;
         case "array": {
             if (schema.items === undefined) {
                 throw new Error(`${path}: array requires items`);
             }
-            return Type.Array(compileNode(schema.items, `${path}.items`));
+            if (schema.minItems !== undefined &&
+                (typeof schema.minItems !== "number" ||
+                    !Number.isInteger(schema.minItems) ||
+                    schema.minItems < 0)) {
+                throw new Error(`${path}: minItems must be a non-negative integer when present`);
+            }
+            const items = compileNode(schema.items, `${path}.items`);
+            base =
+                schema.minItems !== undefined
+                    ? Type.Array(items, { minItems: schema.minItems })
+                    : Type.Array(items);
+            break;
         }
         case "object": {
             const properties = schema.properties ?? {};
@@ -51,24 +172,46 @@ function compileNode(node, path) {
             const options = schema.additionalProperties === false
                 ? { additionalProperties: false }
                 : undefined;
-            return Type.Object(compiledProps, options);
+            base = Type.Object(compiledProps, options);
+            break;
         }
         default:
             throw new Error(`${path}: unsupported type "${schema.type}" (supported: object, string, number, integer, boolean, array)`);
     }
+    return nullable ? Type.Union([base, Type.Null()]) : base;
 }
 /**
  * Compile a JSON Schema subset used for stage payload_schema.
  * Supported: type object/string/number/integer/boolean/array,
- * properties, required, items, additionalProperties (boolean).
+ * properties, required, items, additionalProperties (boolean),
+ * minItems, enum, minimum, maximum. String nodes also accept
+ * pattern (a JS RegExp validated with the unicode flag), minLength,
+ * and maxLength (non-negative integers). Nested nodes accept
+ * nullable (boolean), compiling to a union of that type with null;
+ * the root object cannot be nullable. Unknown keywords are ignored.
  */
 export function compilePayloadSchema(raw) {
+    if (raw !== null &&
+        typeof raw === "object" &&
+        !Array.isArray(raw) &&
+        raw.nullable === true) {
+        throw new Error("payload_schema: root cannot be nullable");
+    }
     const compiled = compileNode(raw, "payload_schema");
     if (!Type.IsObject(compiled)) {
         throw new Error("payload_schema: root type must be object");
     }
     return compiled;
 }
+function formatPayloadInstancePath(instancePath) {
+    const translated = instancePath.replace(/\//g, ".").replace(/^\./, "");
+    return translated ? `payload.${translated}` : "payload";
+}
+function payloadSchemaMismatchDetails(schema, payload) {
+    return [...Value.Errors(schema, payload)]
+        .map((err) => `${formatPayloadInstancePath(err.instancePath)} ${err.message}`)
+        .join("; ");
+}
 export function assertEnvelopePayload(envelope, payloadSchema) {
     if (payloadSchema === undefined) {
         return;
@@ -81,11 +224,25 @@ export function assertEnvelopePayload(envelope, payloadSchema) {
         throw new EnvelopeError("payload is required by stage payload_schema");
     }
     if (!Value.Check(schema, envelope.payload)) {
-        const details = [...Value.Errors(schema, envelope.payload)]
-            .map((err) => `${err.instancePath || "/"} ${err.message}`)
-            .join("; ");
+        const details = payloadSchemaMismatchDetails(schema, envelope.payload);
         throw new EnvelopeError(details
             ? `payload does not match payload_schema: ${details}`
             : "payload does not match payload_schema");
     }
 }
+export function assertCloneAssignmentPayload(envelope, cloneInputSchema, successorId, itemPath = "") {
+    if (envelope.status !== "success") {
+        return;
+    }
+    const schema = compilePayloadSchema(cloneInputSchema);
+    const pathLead = itemPath ? `${itemPath}: ` : "";
+    if (envelope.payload === undefined) {
+        throw new EnvelopeError(`${pathLead}clone assignment payload is required by clone_input_schema for ${successorId}`);
+    }
+    if (!Value.Check(schema, envelope.payload)) {
+        const details = payloadSchemaMismatchDetails(schema, envelope.payload);
+        throw new EnvelopeError(details
+            ? `${pathLead}clone assignment payload does not match clone_input_schema for ${successorId}: ${details}`
+            : `${pathLead}clone assignment payload does not match clone_input_schema for ${successorId}`);
+    }
+}

package/dist/envelope/preEmitChecks.d.ts

@@ -0,0 +1,29 @@
+/**
+ * In-session runner for `pre_emit_checks` (`src/types/preEmitCheck.ts`).
+ *
+ * Distinct from `completionCheckRunner.ts`'s post-hoc `CompletionCheck`
+ * runner: this runs synchronously inside `emit_stage_envelope`'s own tool
+ * call, before a candidate envelope is even captured, and never touches
+ * disk — `artifact_declared` only checks whether a basename is *listed* in
+ * `envelope.artifacts`, and `gate` only reads the live, attempt-scoped QA
+ * trail via a caller-supplied `readQaTrail`. See the design doc's Q1/Q3 for
+ * why this stays separate from `CompletionCheck`'s `artifact`/`gate` runners.
+ */
+import { type QaExchange } from "../hitl/qaTrail.js";
+import { type StageEnvelope } from "../types/envelope.js";
+import type { PreEmitCheck } from "../types/preEmitCheck.js";
+export type PreEmitCheckOptions = {
+    checks?: PreEmitCheck[];
+    readQaTrail?: () => QaExchange[] | Promise<QaExchange[]>;
+};
+export declare function declaredArtifactIssue(artifacts: readonly string[], check: Extract<PreEmitCheck, {
+    type: "artifact_declared";
+}>): string | undefined;
+/**
+ * Runs `options.checks` in declaration order and throws `EnvelopeError` on
+ * the first failing check, matching the single-message-per-rejected-emit
+ * contract the rest of `emitStageEnvelope.ts`'s `assert*` helpers use. A
+ * `gate` check with no `readQaTrail` fails closed (cannot be verified). No
+ * `checks` (or an empty list) is a no-op.
+ */
+export declare function assertPreEmitChecks(envelope: Pick<StageEnvelope, "artifacts">, options: PreEmitCheckOptions | undefined): Promise<void>;