stageflow 0.8.0 → 0.12.0

package/dist/runstore/sqlite/schema.d.ts

@@ -1 +1 @@
-export declare const SCHEMA_SQL = "\nCREATE TABLE IF NOT EXISTS runs (\n  run_id TEXT PRIMARY KEY,\n  pipeline_id TEXT NOT NULL,\n  task_id TEXT,\n  task_yaml TEXT NOT NULL,\n  status TEXT NOT NULL,\n  created_at TEXT NOT NULL,\n  updated_at TEXT NOT NULL,\n  checkout_root TEXT,\n  pipeline_dag_json TEXT,\n  git_sha TEXT,\n  ci_pr_url TEXT,\n  ci_job_url TEXT,\n  pipeline_path TEXT,\n  task_path TEXT,\n  project_root TEXT\n);\n\nCREATE TABLE IF NOT EXISTS stages (\n  run_id TEXT NOT NULL,\n  stage_id TEXT NOT NULL,\n  status TEXT,\n  summary TEXT,\n  envelope_json TEXT,\n  started_at TEXT,\n  finished_at TEXT,\n  PRIMARY KEY (run_id, stage_id),\n  FOREIGN KEY (run_id) REFERENCES runs(run_id)\n);\n\nCREATE TABLE IF NOT EXISTS stage_events (\n  id INTEGER PRIMARY KEY AUTOINCREMENT,\n  run_id TEXT NOT NULL,\n  stage_id TEXT NOT NULL,\n  at TEXT NOT NULL,\n  event TEXT NOT NULL,\n  payload_json TEXT,\n  FOREIGN KEY (run_id) REFERENCES runs(run_id)\n);\n\nCREATE INDEX IF NOT EXISTS idx_runs_status_created\n  ON runs (status, created_at DESC);\n\nCREATE INDEX IF NOT EXISTS idx_runs_pipeline_created\n  ON runs (pipeline_id, created_at DESC);\n\nCREATE INDEX IF NOT EXISTS idx_stage_events_run_stage_at\n  ON stage_events (run_id, stage_id, at);\n\nCREATE TABLE IF NOT EXISTS stage_executions (\n  run_id TEXT NOT NULL,\n  stage_id TEXT NOT NULL,\n  attempt INTEGER NOT NULL,\n  status TEXT NOT NULL,\n  started_at TEXT,\n  finished_at TEXT,\n  envelope_json TEXT,\n  PRIMARY KEY (run_id, stage_id, attempt),\n  FOREIGN KEY (run_id) REFERENCES runs(run_id)\n);\n\nCREATE INDEX IF NOT EXISTS idx_stage_executions_run_stage\n  ON stage_executions (run_id, stage_id, attempt);\n";
+export declare const SCHEMA_SQL = "\nCREATE TABLE IF NOT EXISTS runs (\n  run_id TEXT PRIMARY KEY,\n  pipeline_id TEXT NOT NULL,\n  task_id TEXT,\n  task_yaml TEXT NOT NULL,\n  status TEXT NOT NULL,\n  created_at TEXT NOT NULL,\n  updated_at TEXT NOT NULL,\n  checkout_root TEXT,\n  pipeline_dag_json TEXT,\n  git_sha TEXT,\n  ci_pr_url TEXT,\n  ci_job_url TEXT,\n  pipeline_path TEXT,\n  task_path TEXT,\n  project_root TEXT\n);\n\nCREATE TABLE IF NOT EXISTS stages (\n  run_id TEXT NOT NULL,\n  stage_id TEXT NOT NULL,\n  status TEXT,\n  summary TEXT,\n  envelope_json TEXT,\n  started_at TEXT,\n  finished_at TEXT,\n  PRIMARY KEY (run_id, stage_id),\n  FOREIGN KEY (run_id) REFERENCES runs(run_id)\n);\n\nCREATE TABLE IF NOT EXISTS stage_events (\n  id INTEGER PRIMARY KEY AUTOINCREMENT,\n  run_id TEXT NOT NULL,\n  stage_id TEXT NOT NULL,\n  at TEXT NOT NULL,\n  event TEXT NOT NULL,\n  payload_json TEXT,\n  FOREIGN KEY (run_id) REFERENCES runs(run_id)\n);\n\nCREATE INDEX IF NOT EXISTS idx_runs_status_created\n  ON runs (status, created_at DESC);\n\nCREATE INDEX IF NOT EXISTS idx_runs_pipeline_created\n  ON runs (pipeline_id, created_at DESC);\n\nCREATE INDEX IF NOT EXISTS idx_stage_events_run_stage_at\n  ON stage_events (run_id, stage_id, at);\n\nCREATE TABLE IF NOT EXISTS stage_executions (\n  run_id TEXT NOT NULL,\n  stage_id TEXT NOT NULL,\n  attempt INTEGER NOT NULL,\n  status TEXT NOT NULL,\n  verification_outcome TEXT NOT NULL DEFAULT 'not_run',\n  started_at TEXT,\n  finished_at TEXT,\n  envelope_json TEXT,\n  PRIMARY KEY (run_id, stage_id, attempt),\n  FOREIGN KEY (run_id) REFERENCES runs(run_id)\n);\n\nCREATE INDEX IF NOT EXISTS idx_stage_executions_run_stage\n  ON stage_executions (run_id, stage_id, attempt);\n\nCREATE TABLE IF NOT EXISTS verification_check_results (\n  run_id TEXT NOT NULL,\n  stage_id TEXT NOT NULL,\n  attempt INTEGER NOT NULL,\n  check_id TEXT NOT NULL,\n  check_type TEXT NOT NULL,\n  status TEXT NOT NULL,\n  started_at TEXT,\n  finished_at TEXT,\n  evidence_json TEXT,\n  PRIMARY KEY (run_id, stage_id, attempt, check_id),\n  FOREIGN KEY (run_id, stage_id, attempt)\n    REFERENCES stage_executions(run_id, stage_id, attempt)\n);\n\nCREATE INDEX IF NOT EXISTS idx_verification_check_results_execution\n  ON verification_check_results (run_id, stage_id, attempt, check_id);\n\nCREATE TABLE IF NOT EXISTS feedback_loops (\n  run_id TEXT NOT NULL,\n  loop_id TEXT NOT NULL,\n  source_stage_id TEXT NOT NULL,\n  source_attempt INTEGER NOT NULL,\n  policy_json TEXT NOT NULL,\n  state TEXT NOT NULL,\n  current_replay_id TEXT,\n  current_replay_number INTEGER,\n  deferred_send_back_json TEXT,\n  created_at TEXT NOT NULL,\n  updated_at TEXT NOT NULL,\n  PRIMARY KEY (run_id, loop_id),\n  FOREIGN KEY (run_id) REFERENCES runs(run_id)\n);\n\nCREATE INDEX IF NOT EXISTS idx_feedback_loops_run_state\n  ON feedback_loops (run_id, state, created_at);\n\nCREATE TABLE IF NOT EXISTS feedback_replays (\n  run_id TEXT NOT NULL,\n  replay_id TEXT NOT NULL,\n  loop_id TEXT NOT NULL,\n  source_stage_id TEXT NOT NULL,\n  source_attempt INTEGER NOT NULL,\n  target_stage_id TEXT NOT NULL,\n  replay_number INTEGER NOT NULL,\n  max_replays INTEGER NOT NULL,\n  replay_session TEXT NOT NULL,\n  route_stage_ids_json TEXT NOT NULL,\n  feedback_envelope_json TEXT NOT NULL,\n  status TEXT NOT NULL,\n  created_at TEXT NOT NULL,\n  updated_at TEXT NOT NULL,\n  PRIMARY KEY (run_id, replay_id),\n  FOREIGN KEY (run_id, loop_id) REFERENCES feedback_loops(run_id, loop_id)\n);\n\nCREATE UNIQUE INDEX IF NOT EXISTS idx_feedback_replays_loop_number\n  ON feedback_replays (run_id, loop_id, replay_number);\nCREATE INDEX IF NOT EXISTS idx_feedback_replays_run_loop\n  ON feedback_replays (run_id, loop_id, created_at);\n\nCREATE TABLE IF NOT EXISTS feedback_replay_stage_passes (\n  run_id TEXT NOT NULL,\n  replay_id TEXT NOT NULL,\n  stage_id TEXT NOT NULL,\n  stage_attempt INTEGER NOT NULL,\n  session_origin_attempt INTEGER,\n  session_mode TEXT NOT NULL,\n  status TEXT NOT NULL,\n  started_at TEXT,\n  finished_at TEXT,\n  emitted_envelope_json TEXT,\n  PRIMARY KEY (run_id, replay_id, stage_id),\n  FOREIGN KEY (run_id, replay_id) REFERENCES feedback_replays(run_id, replay_id)\n);\n\nCREATE INDEX IF NOT EXISTS idx_feedback_replay_stage_passes_replay\n  ON feedback_replay_stage_passes (run_id, replay_id, stage_id);\n\nCREATE TABLE IF NOT EXISTS fork_generations (\n  run_id TEXT NOT NULL,\n  generation_id TEXT NOT NULL,\n  replay_id TEXT,\n  fork_parent_stage_id TEXT NOT NULL,\n  generation_number INTEGER NOT NULL,\n  clone_stage_ids_json TEXT NOT NULL,\n  status TEXT NOT NULL,\n  created_at TEXT NOT NULL,\n  updated_at TEXT NOT NULL,\n  PRIMARY KEY (run_id, generation_id),\n  FOREIGN KEY (run_id, replay_id) REFERENCES feedback_replays(run_id, replay_id)\n);\n\nCREATE UNIQUE INDEX IF NOT EXISTS idx_fork_generations_parent_number\n  ON fork_generations (run_id, fork_parent_stage_id, generation_number);\nCREATE INDEX IF NOT EXISTS idx_fork_generations_run_replay\n  ON fork_generations (run_id, replay_id, created_at);\n";

package/dist/runstore/sqlite/schema.js

@@ -53,6 +53,7 @@ CREATE TABLE IF NOT EXISTS stage_executions (
   stage_id TEXT NOT NULL,
   attempt INTEGER NOT NULL,
   status TEXT NOT NULL,
+  verification_outcome TEXT NOT NULL DEFAULT 'not_run',
   started_at TEXT,
   finished_at TEXT,
   envelope_json TEXT,
@@ -62,4 +63,102 @@ CREATE TABLE IF NOT EXISTS stage_executions (
 
 CREATE INDEX IF NOT EXISTS idx_stage_executions_run_stage
   ON stage_executions (run_id, stage_id, attempt);
+
+CREATE TABLE IF NOT EXISTS verification_check_results (
+  run_id TEXT NOT NULL,
+  stage_id TEXT NOT NULL,
+  attempt INTEGER NOT NULL,
+  check_id TEXT NOT NULL,
+  check_type TEXT NOT NULL,
+  status TEXT NOT NULL,
+  started_at TEXT,
+  finished_at TEXT,
+  evidence_json TEXT,
+  PRIMARY KEY (run_id, stage_id, attempt, check_id),
+  FOREIGN KEY (run_id, stage_id, attempt)
+    REFERENCES stage_executions(run_id, stage_id, attempt)
+);
+
+CREATE INDEX IF NOT EXISTS idx_verification_check_results_execution
+  ON verification_check_results (run_id, stage_id, attempt, check_id);
+
+CREATE TABLE IF NOT EXISTS feedback_loops (
+  run_id TEXT NOT NULL,
+  loop_id TEXT NOT NULL,
+  source_stage_id TEXT NOT NULL,
+  source_attempt INTEGER NOT NULL,
+  policy_json TEXT NOT NULL,
+  state TEXT NOT NULL,
+  current_replay_id TEXT,
+  current_replay_number INTEGER,
+  deferred_send_back_json TEXT,
+  created_at TEXT NOT NULL,
+  updated_at TEXT NOT NULL,
+  PRIMARY KEY (run_id, loop_id),
+  FOREIGN KEY (run_id) REFERENCES runs(run_id)
+);
+
+CREATE INDEX IF NOT EXISTS idx_feedback_loops_run_state
+  ON feedback_loops (run_id, state, created_at);
+
+CREATE TABLE IF NOT EXISTS feedback_replays (
+  run_id TEXT NOT NULL,
+  replay_id TEXT NOT NULL,
+  loop_id TEXT NOT NULL,
+  source_stage_id TEXT NOT NULL,
+  source_attempt INTEGER NOT NULL,
+  target_stage_id TEXT NOT NULL,
+  replay_number INTEGER NOT NULL,
+  max_replays INTEGER NOT NULL,
+  replay_session TEXT NOT NULL,
+  route_stage_ids_json TEXT NOT NULL,
+  feedback_envelope_json TEXT NOT NULL,
+  status TEXT NOT NULL,
+  created_at TEXT NOT NULL,
+  updated_at TEXT NOT NULL,
+  PRIMARY KEY (run_id, replay_id),
+  FOREIGN KEY (run_id, loop_id) REFERENCES feedback_loops(run_id, loop_id)
+);
+
+CREATE UNIQUE INDEX IF NOT EXISTS idx_feedback_replays_loop_number
+  ON feedback_replays (run_id, loop_id, replay_number);
+CREATE INDEX IF NOT EXISTS idx_feedback_replays_run_loop
+  ON feedback_replays (run_id, loop_id, created_at);
+
+CREATE TABLE IF NOT EXISTS feedback_replay_stage_passes (
+  run_id TEXT NOT NULL,
+  replay_id TEXT NOT NULL,
+  stage_id TEXT NOT NULL,
+  stage_attempt INTEGER NOT NULL,
+  session_origin_attempt INTEGER,
+  session_mode TEXT NOT NULL,
+  status TEXT NOT NULL,
+  started_at TEXT,
+  finished_at TEXT,
+  emitted_envelope_json TEXT,
+  PRIMARY KEY (run_id, replay_id, stage_id),
+  FOREIGN KEY (run_id, replay_id) REFERENCES feedback_replays(run_id, replay_id)
+);
+
+CREATE INDEX IF NOT EXISTS idx_feedback_replay_stage_passes_replay
+  ON feedback_replay_stage_passes (run_id, replay_id, stage_id);
+
+CREATE TABLE IF NOT EXISTS fork_generations (
+  run_id TEXT NOT NULL,
+  generation_id TEXT NOT NULL,
+  replay_id TEXT,
+  fork_parent_stage_id TEXT NOT NULL,
+  generation_number INTEGER NOT NULL,
+  clone_stage_ids_json TEXT NOT NULL,
+  status TEXT NOT NULL,
+  created_at TEXT NOT NULL,
+  updated_at TEXT NOT NULL,
+  PRIMARY KEY (run_id, generation_id),
+  FOREIGN KEY (run_id, replay_id) REFERENCES feedback_replays(run_id, replay_id)
+);
+
+CREATE UNIQUE INDEX IF NOT EXISTS idx_fork_generations_parent_number
+  ON fork_generations (run_id, fork_parent_stage_id, generation_number);
+CREATE INDEX IF NOT EXISTS idx_fork_generations_run_replay
+  ON fork_generations (run_id, replay_id, created_at);
 `;

package/dist/runstore/stageInstanceId.d.ts

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

package/dist/runstore/stageInstanceId.js

@@ -11,9 +11,10 @@ export function mintCloneInstanceId(catalogId, n) {
     guardStageId(instanceId);
     return instanceId;
 }
-export function mintCloneInstanceIds(catalogId, count) {
+export function mintCloneInstanceIds(catalogId, count, startAt = 1) {
     guardPositiveInteger(count, "count");
-    return Array.from({ length: count }, (_, i) => mintCloneInstanceId(catalogId, i + 1));
+    guardPositiveInteger(startAt, "startAt");
+    return Array.from({ length: count }, (_, i) => mintCloneInstanceId(catalogId, startAt + i));
 }
 export function definitionIdForInstance(snapshot, instanceId) {
     const node = snapshot?.nodes.find((n) => n.id === instanceId);

package/dist/runstore/trackProjection.js

@@ -1,14 +1,38 @@
+import { isNeedTerminalState, predecessorEdges } from "../config/pipelineNeeds.js";
 import { instancesOfDefinition, linearCompatDagSnapshot, } from "./pipelineDagSnapshot.js";
+import { definitionIdForInstance } from "./stageInstanceId.js";
 function stageStarted(stage) {
     return stage.events.some((e) => e.event === "started" || e.event === "resumed");
 }
-function runHalted(stages) {
-    return stages.some((s) => s.status === "failed");
-}
 function predecessorIds(dag, needs) {
     const preds = instancesOfDefinition(dag, needs);
     return preds.length > 0 ? preds : [needs];
 }
+function inboundFromIds(dag, node) {
+    if (!node)
+        return [];
+    const ids = [];
+    for (const edge of predecessorEdges(node)) {
+        ids.push(...predecessorIds(dag, edge.id));
+    }
+    return ids;
+}
+function failureIsAccepted(dag, failedId, snapshotsById) {
+    const defId = definitionIdForInstance(dag, failedId);
+    for (const node of dag.nodes) {
+        const edge = predecessorEdges(node).find((item) => item.id === failedId || item.id === defId);
+        if (!edge?.on.includes("failed"))
+            continue;
+        const join = snapshotsById.get(node.id);
+        if (join && join.status !== "skipped")
+            return true;
+    }
+    return false;
+}
+function runHalted(dag, stages, snapshotsById) {
+    return stages.some((s) => s.status === "failed" &&
+        !failureIsAccepted(dag, s.stage_id, snapshotsById));
+}
 function computeLayers(dag) {
     const layers = new Map();
     const nodeById = new Map(dag.nodes.map((n) => [n.id, n]));
@@ -16,12 +40,11 @@ function computeLayers(dag) {
         const cached = layers.get(id);
         if (cached !== undefined)
             return cached;
-        const node = nodeById.get(id);
-        if (!node?.needs) {
+        const fromIds = inboundFromIds(dag, nodeById.get(id));
+        if (fromIds.length === 0) {
             layers.set(id, 0);
             return 0;
         }
-        const fromIds = predecessorIds(dag, node.needs);
         const l = Math.max(...fromIds.map(layerFor)) + 1;
         layers.set(id, l);
         return l;
@@ -47,17 +70,22 @@ function deriveReadiness(stage, dag, snapshotsById, halted) {
         return { readiness: "skipped" };
     }
     const node = dag.nodes.find((n) => n.id === stage.stage_id);
-    const need = node?.needs;
-    if (need) {
-        const fromIds = predecessorIds(dag, need);
-        const unresolved = fromIds.filter((id) => {
-            const predecessor = snapshotsById.get(id);
-            return !predecessor || predecessor.status !== "succeeded";
-        });
-        if (unresolved.length > 0) {
-            return { readiness: "blocked", blocked_by: unresolved };
+    const unresolved = [];
+    if (node) {
+        for (const edge of predecessorEdges(node)) {
+            for (const fromId of predecessorIds(dag, edge.id)) {
+                const predecessor = snapshotsById.get(fromId);
+                if (!predecessor ||
+                    !isNeedTerminalState(predecessor.status) ||
+                    !edge.on.includes(predecessor.status)) {
+                    unresolved.push(fromId);
+                }
+            }
         }
     }
+    if (unresolved.length > 0) {
+        return { readiness: "blocked", blocked_by: unresolved };
+    }
     return { readiness: "ready" };
 }
 export function buildPipelineTrack(input) {
@@ -66,7 +94,7 @@ export function buildPipelineTrack(input) {
         input.stages.map((s) => s.stage_id);
     const dag = input.dagSnapshot ?? linearCompatDagSnapshot(stageIds);
     const layers = computeLayers(dag);
-    const halted = runHalted(input.stages);
+    const halted = runHalted(dag, input.stages, snapshotsById);
     const nodes = dag.stage_ids.map((stageId) => {
         const stage = snapshotsById.get(stageId);
         if (!stage) {
@@ -87,23 +115,27 @@ export function buildPipelineTrack(input) {
         if (blocked_by?.length)
             trackNode.blocked_by = blocked_by;
         const gateKinds = dag.gate_kinds?.[definitionId] ?? dag.gate_kinds?.[stageId];
-        if (gateKinds?.length)
+        if (gateKinds !== undefined)
             trackNode.gate_kinds = gateKinds;
+        const feedbackTarget = node?.feedback_loop?.target;
+        if (feedbackTarget !== undefined && feedbackTarget.trim() !== "") {
+            trackNode.feedback_loop = { target: feedbackTarget };
+        }
         return trackNode;
     });
     const edges = [];
     for (const node of dag.nodes) {
-        if (!node.needs)
-            continue;
-        const fromIds = predecessorIds(dag, node.needs);
-        for (const fromId of fromIds) {
-            const fromStage = snapshotsById.get(fromId);
-            const edge = { from: fromId, to: node.id };
-            if (fromStage?.status === "succeeded" &&
-                fromStage.envelope?.summary) {
-                edge.envelope_summary = fromStage.envelope.summary;
+        for (const edge of predecessorEdges(node)) {
+            const fromIds = predecessorIds(dag, edge.id);
+            for (const fromId of fromIds) {
+                const fromStage = snapshotsById.get(fromId);
+                const trackEdge = { from: fromId, to: node.id };
+                if (fromStage?.status === "succeeded" &&
+                    fromStage.envelope?.summary) {
+                    trackEdge.envelope_summary = fromStage.envelope.summary;
+                }
+                edges.push(trackEdge);
             }
-            edges.push(edge);
         }
     }
     return { nodes, edges };

package/dist/runstore/verificationHistory.d.ts

@@ -0,0 +1,19 @@
+import type { RunStore, StageExecution, VerificationCheckResult } from "./port.js";
+/**
+ * The audit trail for every execution of one stage. This is deliberately a
+ * stage-scoped read model: command output and other check evidence can be
+ * substantial, so it does not belong in a run listing or summary.
+ */
+export type StageVerificationAttempt = Pick<StageExecution, "attempt" | "status" | "verification_outcome" | "started_at" | "finished_at"> & {
+    checks: VerificationCheckResult[];
+};
+export type StageVerificationHistory = {
+    run_id: string;
+    stage_id: string;
+    attempts: StageVerificationAttempt[];
+    manual_recovery?: {
+        status: "available" | "stopped";
+        failed_attempt: number;
+    };
+};
+export declare function readStageVerificationHistory(store: RunStore, runId: string, stageId: string): Promise<StageVerificationHistory>;

package/dist/runstore/verificationHistory.js

@@ -0,0 +1,30 @@
+import { manualRecoveryHistory, readManualRecoveryState, } from "../runtime/manualRecoveryState.js";
+export async function readStageVerificationHistory(store, runId, stageId) {
+    const run = await store.readRun(runId);
+    if (!run.stages.some((stage) => stage.stage_id === stageId)) {
+        throw new Error(`Stage not found: ${stageId}`);
+    }
+    const executions = await store.listStageExecutions(runId, stageId);
+    const attempts = await Promise.all(executions.map(async (execution) => ({
+        attempt: execution.attempt,
+        status: execution.status,
+        verification_outcome: execution.verification_outcome,
+        ...(execution.started_at !== undefined
+            ? { started_at: execution.started_at }
+            : {}),
+        ...(execution.finished_at !== undefined
+            ? { finished_at: execution.finished_at }
+            : {}),
+        checks: await store.listVerificationCheckResults(runId, stageId, execution.attempt),
+    })));
+    const recovery = manualRecoveryHistory(await readManualRecoveryState(store, runId, stageId));
+    if (recovery === undefined) {
+        return { run_id: runId, stage_id: stageId, attempts };
+    }
+    return {
+        run_id: runId,
+        stage_id: stageId,
+        attempts,
+        manual_recovery: recovery,
+    };
+}

package/dist/runtime/cloneSchedule.d.ts

@@ -1,18 +1,54 @@
 import type { RunPipelineDagSnapshot } from "../runstore/port.js";
 import type { StageEnvelope } from "../types/envelope.js";
-import type { ResolvedPipelineDag } from "../types/pipeline.js";
+import type { NeedTerminalState, ResolvedPipelineDag } from "../types/pipeline.js";
+import { type ActiveCohort } from "./forkGeneration.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 cloneFanoutConflict(dag: ResolvedPipelineDag, envelope: StageEnvelope): string | undefined;
+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>;
+/**
+ * Downstream closure for a retry, resolved through clone-instance ids and
+ * static multi-parent edges. Catalog-level children (e.g. a join stage) are
+ * registered in `childrenOf` under the *definition* id, not per clone
+ * instance, so a plain childrenOf walk starting above a fanout dead-ends at
+ * the instance ids it discovers transitively. Resolving definition-id
+ * children and `predecessorEdges` join successors at every step means
+ * retrying an ancestor or a single clone instance still reaches the join
+ * and everything after it, without pulling in sibling terminals.
+ */
 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>): boolean;
+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>): ApplyCloneForksResult;
+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;