stageflow 0.16.0 → 0.19.0

package/dist/envelope/payloadSchema.js

@@ -179,10 +179,21 @@ function compileNode(node, path, ctx) {
                     schema.minItems < 0)) {
                 throw new Error(`${path}: minItems must be a non-negative integer when present`);
             }
+            if (schema.maxItems !== undefined &&
+                (typeof schema.maxItems !== "number" ||
+                    !Number.isInteger(schema.maxItems) ||
+                    schema.maxItems < 0)) {
+                throw new Error(`${path}: maxItems must be a non-negative integer when present`);
+            }
             const items = compileNode(schema.items, `${path}.items`, childCtx);
+            const arrayOpts = {};
+            if (schema.minItems !== undefined)
+                arrayOpts.minItems = schema.minItems;
+            if (schema.maxItems !== undefined)
+                arrayOpts.maxItems = schema.maxItems;
             base =
-                schema.minItems !== undefined
-                    ? Type.Array(items, { minItems: schema.minItems })
+                Object.keys(arrayOpts).length > 0
+                    ? Type.Array(items, arrayOpts)
                     : Type.Array(items);
             break;
         }
@@ -420,6 +431,61 @@ export function expandPayloadSchemaRefs(raw, options) {
         stack: [],
     });
 }
+const INDEX_SEGMENT = /^\d+$/;
+function schemaNodeType(schema) {
+    return typeof schema?.type === "string" ? schema.type : undefined;
+}
+function tryExpandSchema(node, options) {
+    try {
+        return expandPayloadSchemaRefs(node, options);
+    }
+    catch {
+        return node;
+    }
+}
+export function resolvePayloadSchemaFieldPath(schema, field, options) {
+    const segments = field.split(".");
+    if (segments.length === 0 || segments.some((segment) => segment === "")) {
+        return { ok: false, issue: "empty_segment" };
+    }
+    if (segments.some((segment) => INDEX_SEGMENT.test(segment))) {
+        return { ok: false, issue: "array_index" };
+    }
+    let current = tryExpandSchema(schema, options);
+    for (const segment of segments) {
+        if (!isPlainSchemaObject(current)) {
+            return { ok: false, issue: "missing" };
+        }
+        const node = current;
+        if (node.$ref !== undefined && node.properties === undefined) {
+            return { ok: false, issue: "missing" };
+        }
+        const typeName = schemaNodeType(node);
+        if (typeName === "array" ||
+            (node.items !== undefined && typeName !== "object")) {
+            return { ok: false, issue: "array_index" };
+        }
+        const properties = readProperties(node);
+        if (!Object.prototype.hasOwnProperty.call(properties, segment)) {
+            return { ok: false, issue: "missing" };
+        }
+        if (!readRequiredKeys(node).includes(segment)) {
+            return { ok: false, issue: "optional" };
+        }
+        current = properties[segment];
+    }
+    const leaf = isPlainSchemaObject(current)
+        ? tryExpandSchema(current, options)
+        : undefined;
+    if (leaf?.$ref !== undefined && leaf.properties === undefined) {
+        return { ok: false, issue: "untyped" };
+    }
+    const fieldType = schemaNodeType(leaf);
+    if (fieldType === undefined) {
+        return { ok: false, issue: "untyped" };
+    }
+    return { ok: true, type: fieldType };
+}
 function expandSchemaNode(node, path, ctx) {
     const { schema, stack } = derefSchemaNode(node, path, ctx);
     const childCtx = { schemas: ctx.schemas, stack };
@@ -496,3 +562,22 @@ export function assertCloneAssignmentPayload(envelope, cloneInputSchema, success
             : `${pathLead}clone assignment payload does not match io.input.schema for ${successorId}`);
     }
 }
+/**
+ * Validate a predecessor success payload against the child's IR
+ * `clone_input_schema` (YAML: `io.input.schema`) on a normal pipeline edge.
+ */
+export function assertPriorInputPayload(envelope, cloneInputSchema, childId, options) {
+    if (envelope.status !== "success") {
+        return;
+    }
+    const schema = compilePayloadSchema(cloneInputSchema, options);
+    if (envelope.payload === undefined) {
+        throw new EnvelopeError(`prior payload is required by io.input.schema for ${childId}`);
+    }
+    if (!Value.Check(schema, envelope.payload)) {
+        const details = payloadSchemaMismatchDetails(schema, envelope.payload);
+        throw new EnvelopeError(details
+            ? `prior payload does not match io.input.schema for ${childId}: ${details}`
+            : `prior payload does not match io.input.schema for ${childId}`);
+    }
+}

package/dist/mcp/catalogTools.js

@@ -153,7 +153,7 @@ export function registerCatalogTools(server, deps) {
         }
     });
     server.registerTool("describe_pipeline", {
-        description: "Describe a pipeline DAG: stages with needs, fork, clonable, clone_cap, and gate_kinds. Input is a filesystem pipeline path (same as start_run).",
+        description: "Describe a pipeline DAG: stages with needs, fork, and gate_kinds. Input is a filesystem pipeline path (same as start_run).",
         inputSchema: z.object({
             pipeline: z.string(),
         }),
@@ -170,7 +170,6 @@ export function registerCatalogTools(server, deps) {
                     ? node.needsEdges.map((edge) => ({ id: edge.id, on: [...edge.on] }))
                     : node.needs,
                 ...(node.fork !== undefined ? { fork: node.fork } : {}),
-                ...(node.clonable !== undefined ? { clonable: node.clonable } : {}),
                 ...(node.clone_cap !== undefined ? { clone_cap: node.clone_cap } : {}),
                 ...(gateById.get(node.id) !== undefined
                     ? { gate_kinds: gateById.get(node.id) }

package/dist/mcp/controlTools.js

@@ -183,6 +183,23 @@ export function registerControlTools(server, deps) {
             attemptIndex: result.attemptIndex,
         });
     });
+    server.registerTool("resume_stage", {
+        description: "Resume a stage that failed because it timed out, continuing the same attempt/session (same as POST .../resume). Does not start a new attempt — use retry_stage to start over.",
+        inputSchema: z.object({
+            runId: z.string(),
+            stageId: z.string(),
+        }),
+    }, async ({ runId, stageId }) => {
+        const result = await manager.resumeTimedOutStage(runId, stageId);
+        if (!result.ok) {
+            return textResult({ ...mapRetryStageFailure(result), status: result.status }, true);
+        }
+        return textResult({
+            runId: result.runId,
+            stageId: result.stageId,
+            attemptIndex: result.attemptIndex,
+        });
+    });
     server.registerTool("abandon_stage", {
         description: "Abandon a running stage (marks it failed/interrupted). Does not dismiss HITL — waiting stages return 409; answer them with answer_gate. There is no run-level cancel tool.",
         inputSchema: z.object({

package/dist/package-meta.d.ts

@@ -1,2 +1,2 @@
 export declare const PACKAGE_NAME = "stageflow";
-export declare const PACKAGE_VERSION = "0.16.0";
+export declare const PACKAGE_VERSION = "0.19.0";

package/dist/package-meta.js

@@ -1,2 +1,2 @@
 export const PACKAGE_NAME = "stageflow";
-export const PACKAGE_VERSION = "0.16.0";
+export const PACKAGE_VERSION = "0.19.0";

package/dist/projection/projectRun.d.ts

@@ -2,7 +2,6 @@ import type { FeedbackLoopHistory, FeedbackLoopRecord, RunDetail, StageSnapshot
 import type { PipelineTrackProjection, RunSummary } from "../runstore/port.js";
 import type { AskOperatorPrompt } from "../tools/askOperator.js";
 import type { StageEnvelope } from "../types/envelope.js";
-import type { CloneForkItem } from "../types/forkChoice.js";
 export type StageProjection = {
     stage_id: string;
     status: StageSnapshot["status"];
@@ -12,7 +11,6 @@ export type StageProjection = {
         artifacts: string[];
         payload?: Record<string, unknown>;
         fork_choice?: string[];
-        clone_forks?: CloneForkItem[];
         feedback_loop?: StageEnvelope["feedback_loop"];
     } | null;
     artifacts: string[];

package/dist/projection/projectRun.js

@@ -59,9 +59,6 @@ export function projectRun(detail) {
                     ...(stage.envelope.fork_choice !== undefined
                         ? { fork_choice: stage.envelope.fork_choice }
                         : {}),
-                    ...(stage.envelope.clone_forks !== undefined
-                        ? { clone_forks: stage.envelope.clone_forks }
-                        : {}),
                     ...(stage.envelope.feedback_loop !== undefined
                         ? { feedback_loop: stage.envelope.feedback_loop }
                         : {}),

package/dist/prompt/priorEnvelope.js

@@ -3,7 +3,7 @@ export function formatPriorEnvelope(priorEnvelope, priorEnvelopes, priorEnvelope
         return `Prior envelopes by stage (declaration order):\n${JSON.stringify(priorEnvelopesByStage, null, 2)}`;
     }
     if (priorEnvelopes !== undefined && priorEnvelopes.length > 0) {
-        return `Prior envelopes (${priorEnvelopes.length} clones, clone-list order):\n${JSON.stringify(priorEnvelopes, null, 2)}`;
+        return `Prior envelopes (${priorEnvelopes.length}):\n${JSON.stringify(priorEnvelopes, null, 2)}`;
     }
     return priorEnvelope === null
         ? "No prior envelope (first stage)."

package/dist/runstore/port.js

@@ -12,6 +12,8 @@ export function stageStatusFromEvents(events) {
             status = "failed";
         if (ev.event === "skipped")
             status = "skipped";
+        if (ev.event === "reopened")
+            status = "pending";
     }
     return status;
 }

package/dist/runstore/stageInstanceId.d.ts

@@ -1,4 +1,5 @@
 import type { RunPipelineDagSnapshot } from "./port.js";
 export declare function mintCloneInstanceId(catalogId: string, n: number): string;
 export declare function mintCloneInstanceIds(catalogId: string, count: number, startAt?: number): string[];
+export declare function cloneInstanceOrdinal(instanceId: string, catalogId: string): number | undefined;
 export declare function definitionIdForInstance(snapshot: RunPipelineDagSnapshot | null | undefined, instanceId: string): string;

package/dist/runstore/stageInstanceId.js

@@ -16,6 +16,15 @@ export function mintCloneInstanceIds(catalogId, count, startAt = 1) {
     guardPositiveInteger(startAt, "startAt");
     return Array.from({ length: count }, (_, i) => mintCloneInstanceId(catalogId, startAt + i));
 }
+export function cloneInstanceOrdinal(instanceId, catalogId) {
+    const prefix = `${catalogId}~`;
+    if (!instanceId.startsWith(prefix))
+        return undefined;
+    const n = Number(instanceId.slice(prefix.length));
+    if (!Number.isInteger(n) || n < 1)
+        return undefined;
+    return n;
+}
 export function definitionIdForInstance(snapshot, instanceId) {
     const node = snapshot?.nodes.find((n) => n.id === instanceId);
     if (!node)

package/dist/runtime/cloneSchedule.d.ts

@@ -1,30 +1,26 @@
 import type { RunPipelineDagSnapshot } from "../runstore/port.js";
 import type { StageEnvelope } from "../types/envelope.js";
 import type { NeedTerminalState, ResolvedPipelineDag } from "../types/pipeline.js";
-import { type ActiveCohort } from "./forkGeneration.js";
+import type { ResolvePriorEnvelopeResult } from "./envelopeRouting.js";
 import type { StageScheduleState } from "./pipelineScheduler.js";
 export declare function isCloneInstance(dag: ResolvedPipelineDag, stageId: string): boolean;
 export declare function sequentialLaterCloneIds(dag: ResolvedPipelineDag, stageId: string, completedEnvelopes: Map<string, StageEnvelope>): string[];
 export declare function skipRejectedNeedDependents(dag: ResolvedPipelineDag, parentId: string, states: Map<string, StageScheduleState>, observed: NeedTerminalState, onSkip: (stageId: string) => void): void;
 export declare function failureIsAccepted(dag: ResolvedPipelineDag, failedId: string, states: Map<string, StageScheduleState>): boolean;
-/**
- * A fresh clone_forks fanout targeting a catalog id that already has
- * instances is only safe when every existing instance was put back to
- * `pending` by the current retry cascade (`retryDownstreamIds`) — that means
- * an ancestor was legitimately retried and this parent re-emitted the same
- * fanout for reactivation. Instances that are still active/terminal, or
- * merely `pending` without having gone through a retry reset (e.g. an
- * envelope processed twice in one live run), are rejected as before.
- *
- * Feedback-loop replay is different: the prior cohort was superseded
- * (`skipped`) and a new generation must mint fresh `~N` ids, so
- * `forceFreshCloneIds` bypasses the conflict.
- */
-export declare function cloneFanoutConflict(dag: ResolvedPipelineDag, envelope: StageEnvelope, states: Map<string, StageScheduleState>, retryDownstreamIds: ReadonlySet<string>, options?: {
-    forceFreshCloneIds?: boolean;
-}): string | undefined;
-export declare function nextFreeCloneSuffix(snapshot: RunPipelineDagSnapshot, catalogId: string): number;
-export declare function protectedClonableChildIds(dag: ResolvedPipelineDag, predecessorId: string, envelope: StageEnvelope): Set<string>;
+export type MintResult = {
+    kind: "none";
+} | {
+    kind: "error";
+    reason: string;
+} | {
+    kind: "minted";
+    dag: RunPipelineDagSnapshot;
+    catalogChildId: string;
+    instanceIds: string[];
+};
+export declare function mint(dag: ResolvedPipelineDag, emitterId: string, envelope: StageEnvelope): MintResult;
+export declare function assignment(dag: ResolvedPipelineDag, stageId: string, definitionId: string, completedEnvelopes: Map<string, StageEnvelope>): ResolvePriorEnvelopeResult | undefined;
+export declare function protectedClonableChildIds(dag: ResolvedPipelineDag, predecessorId: string, _envelope: StageEnvelope): Set<string>;
 /**
  * Downstream closure for a retry, resolved through clone-instance ids and
  * static multi-parent edges. Catalog-level children (e.g. a join stage) are
@@ -38,17 +34,4 @@ export declare function protectedClonableChildIds(dag: ResolvedPipelineDag, pred
 export declare function cloneRetryDownstream(dag: ResolvedPipelineDag, stageIds: string[]): Set<string>;
 export declare function cloneFailureContinuesSchedule(dag: ResolvedPipelineDag, stageId: string, completedEnvelopes: Map<string, StageEnvelope>): boolean;
 export declare function cloneFailFastSkipIds(dag: ResolvedPipelineDag, stageId: string, completedEnvelopes: Map<string, StageEnvelope>): string[];
-export declare function cloneScheduleAllowsRun(dag: ResolvedPipelineDag, stageId: string, states: Map<string, StageScheduleState>, completedEnvelopes: Map<string, StageEnvelope>, options?: {
-    activeCohortForNeeds?: (needsId: string) => ActiveCohort;
-    activeCloneIdsForNeeds?: (needsId: string) => Set<string> | null;
-}): boolean;
-export type ApplyCloneForksResult = {
-    dag: RunPipelineDagSnapshot;
-    skippedIds: string[];
-    /** Freshly minted instance ids keyed by clonable catalog successor id. */
-    mintedBySuccessor?: Map<string, string[]>;
-};
-export declare function applyCloneForksToSchedule(dag: ResolvedPipelineDag, predecessorId: string, envelope: StageEnvelope, states: Map<string, StageScheduleState>, options?: {
-    forceFreshCloneIds?: boolean;
-}): ApplyCloneForksResult;
-export declare function applyCloneForksFromEnvelopes(dag: ResolvedPipelineDag, states: Map<string, StageScheduleState>, completedEnvelopes: Map<string, StageEnvelope>): ApplyCloneForksResult;
+export declare function cloneScheduleAllowsRun(dag: ResolvedPipelineDag, stageId: string, states: Map<string, StageScheduleState>, completedEnvelopes: Map<string, StageEnvelope>): boolean;