stageflow 0.2.0 → 0.8.0

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

@@ -1,6 +1,6 @@
 import type { StageEnvelope } from "../../types/envelope.js";
 import type { StageLogLine } from "../../agent/activity.js";
-import { type CreateRunInput, type CreatedRun, type RunDetail, type RunMeta, type RunStatus, type RunStore, type RunSummary, type StageExecution, type StageExecutionPatch, type StageLogEvent } from "../port.js";
+import { type CreateRunInput, type CreatedRun, type ListRunsFilter, type RunDetail, type RunMeta, type RunPipelineDagSnapshot, type RunStatus, type RunStore, type RunSummary, type StageExecution, type StageExecutionPatch, type StageLogEvent } from "../port.js";
 export declare class SqliteRunStore implements RunStore {
     private readonly storeRoot;
     private readonly db;
@@ -11,6 +11,7 @@ export declare class SqliteRunStore implements RunStore {
     getWorkspaceDir(runId: string): string;
     createRun(input: CreateRunInput): Promise<CreatedRun>;
     updateRunStatus(runId: string, status: RunStatus): Promise<void>;
+    updatePipelineDag(runId: string, dag: RunPipelineDagSnapshot): Promise<void>;
     readRunMeta(runId: string): Promise<RunMeta>;
     readTaskYaml(runId: string): Promise<string>;
     ensureStageWorkspace(runId: string, stageId: string): Promise<void>;
@@ -37,7 +38,7 @@ export declare class SqliteRunStore implements RunStore {
      */
     private updateStageStatusDenorm;
     listStageEvents(runId: string, stageId: string, attempt?: number): Promise<StageLogEvent[]>;
-    listRuns(): Promise<RunSummary[]>;
+    listRuns(filter?: ListRunsFilter): Promise<RunSummary[]>;
     readRun(runId: string): Promise<RunDetail>;
     private readPipelineDagSnapshotFromRow;
     private runMetaFromRow;

package/dist/runstore/sqlite/SqliteRunStore.js

@@ -2,6 +2,7 @@ import Database from "better-sqlite3";
 import { mkdir } from "node:fs/promises";
 import path from "node:path";
 import { projectRunDetail, projectRunSummary, orderStageSnapshots } from "../runProjection.js";
+import { normalizeCatalogPath } from "../normalizeCatalogPath.js";
 import { buildStageSnapshotFromStore } from "../stageSnapshot.js";
 import { parsePipelineDagSnapshot } from "../pipelineDagSnapshot.js";
 import { newRunId, runWorkspaceDir } from "../paths.js";
@@ -42,6 +43,15 @@ function ensurePipelineDagColumn(db) {
         db.exec(`ALTER TABLE runs ADD COLUMN pipeline_dag_json TEXT`);
     }
 }
+function ensureRunLocatorColumns(db) {
+    const cols = db.prepare(`PRAGMA table_info(runs)`).all();
+    const names = new Set(cols.map((c) => c.name));
+    for (const name of ["pipeline_path", "task_path", "project_root"]) {
+        if (!names.has(name)) {
+            db.exec(`ALTER TABLE runs ADD COLUMN ${name} TEXT`);
+        }
+    }
+}
 function ensureStageExecutionsTable(db) {
     db.exec(`
 CREATE TABLE IF NOT EXISTS stage_executions (
@@ -98,6 +108,7 @@ export class SqliteRunStore {
         ensureCheckoutRootColumn(this.db);
         ensureCiIdentityColumns(this.db);
         ensurePipelineDagColumn(this.db);
+        ensureRunLocatorColumns(this.db);
         ensureStageExecutionsTable(this.db);
         ensureStageEventsAttemptColumn(this.db);
         this.migratePromise = importDiskRunsIfEmpty(this.db, storeRoot).then(() => undefined);
@@ -115,11 +126,20 @@ export class SqliteRunStore {
         const workspaceDir = this.getWorkspaceDir(runId);
         await mkdir(path.join(workspaceDir, "stages"), { recursive: true });
         const now = new Date().toISOString();
+        const pipelinePath = input.pipelinePath
+            ? normalizeCatalogPath(input.pipelinePath)
+            : null;
+        const taskPath = input.taskPath
+            ? normalizeCatalogPath(input.taskPath)
+            : null;
+        const projectRoot = input.projectRoot
+            ? normalizeCatalogPath(input.projectRoot)
+            : null;
         this.db
             .prepare(`INSERT INTO runs
-          (run_id, pipeline_id, task_id, task_yaml, status, created_at, updated_at, checkout_root, pipeline_dag_json, git_sha, ci_pr_url, ci_job_url)
+          (run_id, pipeline_id, task_id, task_yaml, status, created_at, updated_at, checkout_root, pipeline_dag_json, git_sha, ci_pr_url, ci_job_url, pipeline_path, task_path, project_root)
          VALUES
-          (@run_id, @pipeline_id, @task_id, @task_yaml, @status, @created_at, @updated_at, @checkout_root, @pipeline_dag_json, @git_sha, @ci_pr_url, @ci_job_url)`)
+          (@run_id, @pipeline_id, @task_id, @task_yaml, @status, @created_at, @updated_at, @checkout_root, @pipeline_dag_json, @git_sha, @ci_pr_url, @ci_job_url, @pipeline_path, @task_path, @project_root)`)
             .run({
             run_id: runId,
             pipeline_id: input.pipelineId,
@@ -135,6 +155,9 @@ export class SqliteRunStore {
             git_sha: input.gitSha ?? null,
             ci_pr_url: input.ciPrUrl ?? null,
             ci_job_url: input.ciJobUrl ?? null,
+            pipeline_path: pipelinePath,
+            task_path: taskPath,
+            project_root: projectRoot,
         });
         return { runId, workspaceDir };
     }
@@ -151,6 +174,19 @@ export class SqliteRunStore {
             throw new Error(`Run not found: ${runId}`);
         }
     }
+    async updatePipelineDag(runId, dag) {
+        await this.ready();
+        const result = this.db
+            .prepare(`UPDATE runs SET pipeline_dag_json = @pipeline_dag_json, updated_at = @updated_at WHERE run_id = @run_id`)
+            .run({
+            run_id: runId,
+            pipeline_dag_json: JSON.stringify(dag),
+            updated_at: new Date().toISOString(),
+        });
+        if (result.changes === 0) {
+            throw new Error(`Run not found: ${runId}`);
+        }
+    }
     async readRunMeta(runId) {
         await this.ready();
         return this.runMetaFromRow(this.getRunRow(runId));
@@ -388,12 +424,29 @@ export class SqliteRunStore {
         await this.ready();
         return this.loadEvents(runId, stageId, attempt);
     }
-    async listRuns() {
+    async listRuns(filter) {
         await this.ready();
+        const clauses = [];
+        const params = [];
+        if (filter?.status !== undefined) {
+            clauses.push("status = ?");
+            params.push(filter.status);
+        }
+        if (filter?.since !== undefined) {
+            clauses.push("created_at >= ?");
+            params.push(filter.since);
+        }
+        if (filter?.pipeline !== undefined && filter.pipeline.trim().length > 0) {
+            const pipeline = filter.pipeline.trim();
+            const normalized = normalizeCatalogPath(pipeline);
+            clauses.push("(pipeline_id = ? OR pipeline_path = ? OR pipeline_path = ?)");
+            params.push(pipeline, pipeline, normalized);
+        }
+        const where = clauses.length > 0 ? `WHERE ${clauses.join(" AND ")}` : "";
         const rows = this.db
-            .prepare(`SELECT run_id, pipeline_id, task_id, task_yaml, status, created_at, updated_at, checkout_root, pipeline_dag_json, git_sha, ci_pr_url, ci_job_url
-         FROM runs ORDER BY created_at DESC`)
-            .all();
+            .prepare(`SELECT run_id, pipeline_id, task_id, task_yaml, status, created_at, updated_at, checkout_root, pipeline_dag_json, git_sha, ci_pr_url, ci_job_url, pipeline_path, task_path, project_root
+         FROM runs ${where} ORDER BY created_at DESC`)
+            .all(...params);
         const summaries = [];
         for (const row of rows) {
             const dagSnapshot = this.readPipelineDagSnapshotFromRow(row);
@@ -415,6 +468,7 @@ export class SqliteRunStore {
         return parsePipelineDagSnapshot(JSON.parse(row.pipeline_dag_json));
     }
     runMetaFromRow(row) {
+        const pipeline_dag = this.readPipelineDagSnapshotFromRow(row);
         return {
             run_id: row.run_id,
             pipeline_id: row.pipeline_id,
@@ -426,11 +480,15 @@ export class SqliteRunStore {
             ...(row.git_sha != null ? { git_sha: row.git_sha } : {}),
             ...(row.ci_pr_url != null ? { ci_pr_url: row.ci_pr_url } : {}),
             ...(row.ci_job_url != null ? { ci_job_url: row.ci_job_url } : {}),
+            ...(row.pipeline_path != null ? { pipeline_path: row.pipeline_path } : {}),
+            ...(row.task_path != null ? { task_path: row.task_path } : {}),
+            ...(row.project_root != null ? { project_root: row.project_root } : {}),
+            ...(pipeline_dag ? { pipeline_dag } : {}),
         };
     }
     getRunRow(runId) {
         const row = this.db
-            .prepare(`SELECT run_id, pipeline_id, task_id, task_yaml, status, created_at, updated_at, checkout_root, pipeline_dag_json, git_sha, ci_pr_url, ci_job_url
+            .prepare(`SELECT run_id, pipeline_id, task_id, task_yaml, status, created_at, updated_at, checkout_root, pipeline_dag_json, git_sha, ci_pr_url, ci_job_url, pipeline_path, task_path, project_root
          FROM runs WHERE run_id = ?`)
             .get(runId);
         if (!row)

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);\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  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";

package/dist/runstore/sqlite/schema.js

@@ -11,7 +11,10 @@ CREATE TABLE IF NOT EXISTS runs (
   pipeline_dag_json TEXT,
   git_sha TEXT,
   ci_pr_url TEXT,
-  ci_job_url TEXT
+  ci_job_url TEXT,
+  pipeline_path TEXT,
+  task_path TEXT,
+  project_root TEXT
 );
 
 CREATE TABLE IF NOT EXISTS stages (

package/dist/runstore/stageInstanceId.d.ts

@@ -0,0 +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 definitionIdForInstance(snapshot: RunPipelineDagSnapshot | null | undefined, instanceId: string): string;

package/dist/runstore/stageInstanceId.js

@@ -0,0 +1,23 @@
+import { guardStageId } from "./workspaceLayout.js";
+function guardPositiveInteger(n, label) {
+    if (!Number.isInteger(n) || n < 1) {
+        throw new Error(`${label} must be a positive integer`);
+    }
+}
+export function mintCloneInstanceId(catalogId, n) {
+    guardPositiveInteger(n, "n");
+    guardStageId(catalogId);
+    const instanceId = `${catalogId}~${n}`;
+    guardStageId(instanceId);
+    return instanceId;
+}
+export function mintCloneInstanceIds(catalogId, count) {
+    guardPositiveInteger(count, "count");
+    return Array.from({ length: count }, (_, i) => mintCloneInstanceId(catalogId, i + 1));
+}
+export function definitionIdForInstance(snapshot, instanceId) {
+    const node = snapshot?.nodes.find((n) => n.id === instanceId);
+    if (!node)
+        return instanceId;
+    return node.definition_id ?? node.id;
+}

package/dist/runstore/syntheticStageSnapshot.d.ts

@@ -1,2 +1,2 @@
 import type { StageSnapshot } from "./port.js";
-export declare function syntheticPendingSnapshot(stageId: string): StageSnapshot;
+export declare function syntheticPendingSnapshot(stageId: string, definitionId?: string): StageSnapshot;

package/dist/runstore/syntheticStageSnapshot.js

@@ -1,4 +1,4 @@
-export function syntheticPendingSnapshot(stageId) {
+export function syntheticPendingSnapshot(stageId, definitionId) {
     return {
         stage_id: stageId,
         status: "pending",
@@ -6,5 +6,6 @@ export function syntheticPendingSnapshot(stageId) {
         envelope: null,
         artifacts: [],
         attempt_count: 1,
+        ...(definitionId !== undefined ? { definition_id: definitionId } : {}),
     };
 }

package/dist/runstore/trackProjection.js

@@ -1,10 +1,14 @@
-import { linearCompatDagSnapshot } from "./pipelineDagSnapshot.js";
+import { instancesOfDefinition, linearCompatDagSnapshot, } from "./pipelineDagSnapshot.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 computeLayers(dag) {
     const layers = new Map();
     const nodeById = new Map(dag.nodes.map((n) => [n.id, n]));
@@ -17,7 +21,8 @@ function computeLayers(dag) {
             layers.set(id, 0);
             return 0;
         }
-        const l = layerFor(node.needs) + 1;
+        const fromIds = predecessorIds(dag, node.needs);
+        const l = Math.max(...fromIds.map(layerFor)) + 1;
         layers.set(id, l);
         return l;
     }
@@ -32,6 +37,8 @@ function deriveReadiness(stage, dag, snapshotsById, halted) {
         return { readiness: "succeeded" };
     if (status === "failed")
         return { readiness: "failed" };
+    if (status === "skipped")
+        return { readiness: "skipped" };
     if (status === "running")
         return { readiness: "running" };
     if (status === "waiting_for_input")
@@ -42,9 +49,13 @@ function deriveReadiness(stage, dag, snapshotsById, halted) {
     const node = dag.nodes.find((n) => n.id === stage.stage_id);
     const need = node?.needs;
     if (need) {
-        const predecessor = snapshotsById.get(need);
-        if (!predecessor || predecessor.status !== "succeeded") {
-            return { readiness: "blocked", blocked_by: [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 };
         }
     }
     return { readiness: "ready" };
@@ -63,6 +74,7 @@ export function buildPipelineTrack(input) {
         }
         const node = dag.nodes.find((n) => n.id === stageId);
         const { readiness, blocked_by } = deriveReadiness(stage, dag, snapshotsById, halted);
+        const definitionId = node?.definition_id ?? stage.definition_id ?? stageId;
         const trackNode = {
             stage_id: stageId,
             status: stage.status,
@@ -70,10 +82,11 @@ export function buildPipelineTrack(input) {
             layer: layers.get(stageId) ?? 0,
             layer_order: node?.stageIndex ?? dag.stage_ids.indexOf(stageId),
             attempt_count: stage.attempt_count,
+            definition_id: definitionId,
         };
         if (blocked_by?.length)
             trackNode.blocked_by = blocked_by;
-        const gateKinds = dag.gate_kinds?.[stageId];
+        const gateKinds = dag.gate_kinds?.[definitionId] ?? dag.gate_kinds?.[stageId];
         if (gateKinds?.length)
             trackNode.gate_kinds = gateKinds;
         return trackNode;
@@ -82,13 +95,16 @@ export function buildPipelineTrack(input) {
     for (const node of dag.nodes) {
         if (!node.needs)
             continue;
-        const fromStage = snapshotsById.get(node.needs);
-        const edge = { from: node.needs, to: node.id };
-        if (fromStage?.status === "succeeded" &&
-            fromStage.envelope?.summary) {
-            edge.envelope_summary = fromStage.envelope.summary;
+        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;
+            }
+            edges.push(edge);
         }
-        edges.push(edge);
     }
     return { nodes, edges };
 }

package/dist/runstore/workspaceLayout.d.ts

@@ -1,4 +1,5 @@
 export { stageDir } from "./paths.js";
+export declare function guardStageId(stageId: string): void;
 export declare function attemptWorkspaceDir(workspaceDir: string, stageId: string, attempt: number): string;
 export declare function attemptLogPath(workspaceDir: string, stageId: string, attempt: number): string;
 export declare function attemptEnvelopePath(workspaceDir: string, stageId: string, attempt: number): string;

package/dist/runstore/workspaceLayout.js

@@ -1,7 +1,7 @@
 import { access, lstat, mkdir, readdir, realpath } from "node:fs/promises";
 import path from "node:path";
 export { stageDir } from "./paths.js";
-function guardStageId(stageId) {
+export function guardStageId(stageId) {
     if (stageId.includes("..") ||
         stageId.includes("/") ||
         stageId.includes("\\")) {

package/dist/runtime/cloneSchedule.d.ts

@@ -0,0 +1,18 @@
+import type { RunPipelineDagSnapshot } from "../runstore/port.js";
+import type { StageEnvelope } from "../types/envelope.js";
+import type { ResolvedPipelineDag } from "../types/pipeline.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 protectedClonableChildIds(dag: ResolvedPipelineDag, predecessorId: string, envelope: StageEnvelope): Set<string>;
+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 type ApplyCloneForksResult = {
+    dag: RunPipelineDagSnapshot;
+    skippedIds: string[];
+};
+export declare function applyCloneForksToSchedule(dag: ResolvedPipelineDag, predecessorId: string, envelope: StageEnvelope, states: Map<string, StageScheduleState>): ApplyCloneForksResult;
+export declare function applyCloneForksFromEnvelopes(dag: ResolvedPipelineDag, states: Map<string, StageScheduleState>, completedEnvelopes: Map<string, StageEnvelope>): ApplyCloneForksResult;

package/dist/runtime/cloneSchedule.js

@@ -0,0 +1,233 @@
+import { appendCloneInstances, instancesOfDefinition, } from "../runstore/pipelineDagSnapshot.js";
+import { definitionIdForInstance } from "../runstore/stageInstanceId.js";
+import { collectDownstreamClosure, collectDownstreamStageIds } from "./dagTraversal.js";
+function asDagSnapshot(dag) {
+    const snapshot = dag;
+    if (Array.isArray(snapshot.stage_ids))
+        return snapshot;
+    return {
+        ...dag,
+        stage_ids: dag.nodes.map((n) => n.id),
+    };
+}
+function definitionInstances(dag, catalogId) {
+    const snapshot = dag;
+    if (Array.isArray(snapshot.stage_ids)) {
+        return instancesOfDefinition(snapshot, catalogId);
+    }
+    return dag.nodes.some((n) => n.id === catalogId) ? [catalogId] : [];
+}
+export function isCloneInstance(dag, stageId) {
+    return definitionIdForInstance(asDagSnapshot(dag), stageId) !== stageId;
+}
+function isParallelCloneInstance(dag, stageId, completedEnvelopes) {
+    if (!isCloneInstance(dag, stageId))
+        return false;
+    const defId = definitionIdForInstance(asDagSnapshot(dag), stageId);
+    for (const envelope of completedEnvelopes.values()) {
+        for (const item of envelope.clone_forks ?? []) {
+            if (item.action === "fanout" &&
+                item.mode === "parallel" &&
+                item.successor_id === defId &&
+                definitionInstances(dag, defId).includes(stageId)) {
+                return true;
+            }
+        }
+    }
+    return false;
+}
+function isSequentialFanoutSuccessor(completedEnvelopes, successorId) {
+    for (const envelope of completedEnvelopes.values()) {
+        for (const item of envelope.clone_forks ?? []) {
+            if (item.action === "fanout" &&
+                item.mode === "sequential" &&
+                item.successor_id === successorId) {
+                return true;
+            }
+        }
+    }
+    return false;
+}
+function isSequentialCloneInstance(dag, stageId, completedEnvelopes) {
+    if (!isCloneInstance(dag, stageId))
+        return false;
+    const defId = definitionIdForInstance(asDagSnapshot(dag), stageId);
+    if (!isSequentialFanoutSuccessor(completedEnvelopes, defId))
+        return false;
+    return definitionInstances(dag, defId).includes(stageId);
+}
+function sequentialInstanceList(dag, stageId, completedEnvelopes) {
+    for (const envelope of completedEnvelopes.values()) {
+        for (const item of envelope.clone_forks ?? []) {
+            if (item.action !== "fanout" || item.mode !== "sequential")
+                continue;
+            const instances = definitionInstances(dag, item.successor_id);
+            if (instances.includes(stageId))
+                return instances;
+        }
+    }
+    return undefined;
+}
+function sequentialPreviousUnsatisfied(dag, stageId, states, completedEnvelopes) {
+    const instances = sequentialInstanceList(dag, stageId, completedEnvelopes);
+    if (instances === undefined)
+        return false;
+    const i = instances.indexOf(stageId);
+    if (i <= 0)
+        return false;
+    return states.get(instances[i - 1]) !== "succeeded";
+}
+export function sequentialLaterCloneIds(dag, stageId, completedEnvelopes) {
+    const instances = sequentialInstanceList(dag, stageId, completedEnvelopes);
+    if (instances === undefined)
+        return [];
+    const i = instances.indexOf(stageId);
+    if (i === -1)
+        return [];
+    return instances.slice(i + 1);
+}
+function joinSuccessorIds(dag, successorId) {
+    return dag.nodes.filter((n) => n.needs === successorId).map((n) => n.id);
+}
+function joinAndDownstreamIds(dag, cloneStageId) {
+    const defId = definitionIdForInstance(asDagSnapshot(dag), cloneStageId);
+    const ids = [];
+    for (const joinId of joinSuccessorIds(dag, defId)) {
+        ids.push(joinId);
+        for (const desc of collectDownstreamStageIds(dag, joinId)) {
+            ids.push(desc);
+        }
+    }
+    return ids;
+}
+export function cloneFanoutConflict(dag, envelope) {
+    const snapshot = asDagSnapshot(dag);
+    for (const item of envelope.clone_forks ?? []) {
+        if (item.action !== "fanout")
+            continue;
+        if (definitionInstances(dag, item.successor_id).some((id) => id !== item.successor_id)) {
+            return `clone fan-out for "${item.successor_id}" is already instanced`;
+        }
+        if (!snapshot.stage_ids.includes(item.successor_id)) {
+            return `clone fan-out for "${item.successor_id}" is already instanced`;
+        }
+    }
+    return undefined;
+}
+export function protectedClonableChildIds(dag, predecessorId, envelope) {
+    const ids = new Set();
+    for (const childId of dag.childrenOf[predecessorId] ?? []) {
+        const child = dag.nodes.find((n) => n.id === childId);
+        if (child?.clonable === true)
+            ids.add(childId);
+    }
+    for (const item of envelope.clone_forks ?? []) {
+        ids.add(item.successor_id);
+    }
+    return ids;
+}
+export function cloneRetryDownstream(dag, stageIds) {
+    const downstream = collectDownstreamClosure(dag, stageIds);
+    for (const id of stageIds) {
+        const defId = definitionIdForInstance(asDagSnapshot(dag), id);
+        for (const child of dag.childrenOf[defId] ?? []) {
+            downstream.add(child);
+            for (const desc of collectDownstreamStageIds(dag, child)) {
+                downstream.add(desc);
+            }
+        }
+    }
+    return downstream;
+}
+export function cloneFailureContinuesSchedule(dag, stageId, completedEnvelopes) {
+    return (isParallelCloneInstance(dag, stageId, completedEnvelopes) ||
+        isSequentialCloneInstance(dag, stageId, completedEnvelopes));
+}
+export function cloneFailFastSkipIds(dag, stageId, completedEnvelopes) {
+    if (isParallelCloneInstance(dag, stageId, completedEnvelopes)) {
+        return joinAndDownstreamIds(dag, stageId);
+    }
+    if (!isSequentialCloneInstance(dag, stageId, completedEnvelopes))
+        return [];
+    const instances = sequentialInstanceList(dag, stageId, completedEnvelopes);
+    if (instances === undefined)
+        return [];
+    const idx = instances.indexOf(stageId);
+    const ids = [];
+    for (const id of instances.slice(idx + 1)) {
+        ids.push(id);
+    }
+    ids.push(...joinAndDownstreamIds(dag, stageId));
+    return ids;
+}
+export function cloneScheduleAllowsRun(dag, stageId, states, completedEnvelopes) {
+    const node = dag.nodes.find((n) => n.id === stageId);
+    if (!node)
+        return false;
+    if (definitionInstances(dag, stageId).some((id) => id !== stageId)) {
+        return false;
+    }
+    if (node.needs === null) {
+        return !sequentialPreviousUnsatisfied(dag, stageId, states, completedEnvelopes);
+    }
+    const instances = definitionInstances(dag, node.needs);
+    if (instances.length <= 1) {
+        const parentId = instances[0] ?? node.needs;
+        if (states.get(parentId) !== "succeeded")
+            return false;
+    }
+    else if (!instances.every((id) => states.get(id) === "succeeded")) {
+        return false;
+    }
+    return !sequentialPreviousUnsatisfied(dag, stageId, states, completedEnvelopes);
+}
+export function applyCloneForksToSchedule(dag, predecessorId, envelope, states) {
+    let current = asDagSnapshot(dag);
+    const skippedIds = [];
+    const skipPending = (stageId) => {
+        if (states.get(stageId) === "pending") {
+            states.set(stageId, "skipped");
+            skippedIds.push(stageId);
+        }
+    };
+    for (const item of envelope.clone_forks ?? []) {
+        if (item.action === "skip") {
+            skipPending(item.successor_id);
+            for (const desc of collectDownstreamStageIds(current, item.successor_id)) {
+                skipPending(desc);
+            }
+            continue;
+        }
+        if (item.action !== "fanout")
+            continue;
+        const existing = definitionInstances(current, item.successor_id);
+        if (existing.some((id) => id !== item.successor_id)) {
+            continue;
+        }
+        const { snapshot, instanceIds } = appendCloneInstances(current, {
+            catalogId: item.successor_id,
+            predecessorId,
+            count: item.clones.length,
+        });
+        current = snapshot;
+        states.delete(item.successor_id);
+        for (const id of instanceIds) {
+            states.set(id, "pending");
+        }
+    }
+    return { dag: current, skippedIds };
+}
+export function applyCloneForksFromEnvelopes(dag, states, completedEnvelopes) {
+    let current = asDagSnapshot(dag);
+    const skippedIds = [];
+    const predecessors = [...current.nodes];
+    for (const node of predecessors) {
+        const envelope = completedEnvelopes.get(node.id);
+        if (!envelope?.clone_forks?.length)
+            continue;
+        const applied = applyCloneForksToSchedule(current, node.id, envelope, states);
+        current = applied.dag;
+        skippedIds.push(...applied.skippedIds);
+    }
+    return { dag: current, skippedIds };
+}

package/dist/runtime/credentialBinding.d.ts

@@ -1,5 +1,6 @@
-import { parseCredentialSource, readCredentialSourceFromFile, writeCredentialSourceToFile, type CredentialSource } from "./settingsFile.js";
-export { parseCredentialSource, readCredentialSourceFromFile, writeCredentialSourceToFile, };
+import { type ProjectContext } from "../project/resolveProjectContext.js";
+import { parseCredentialSource, readCredentialSourceFromContext, writeCredentialSourceToContext, type CredentialSource } from "./settingsFile.js";
+export { parseCredentialSource, readCredentialSourceFromContext, writeCredentialSourceToContext, };
 export type CredentialBinding = {
     source: CredentialSource;
     authPath: string;
@@ -8,9 +9,10 @@ export type CredentialBinding = {
 export type ResolveCredentialBindingOptions = {
     piHomeAuthPath?: string;
 };
-export declare function sfOwnedAgentDir(cwd: string): string;
-export declare function sfOwnedAuthPath(cwd: string): string;
+export declare function sfOwnedAgentDir(): string;
+export declare function sfOwnedAuthPath(): string;
 export declare function piHomeAuthPath(override?: string): string;
 export declare function isUsableAuthFile(authPath: string): boolean;
-export declare function ensureSfOwnedAuthStore(cwd: string): string;
-export declare function resolveCredentialBinding(cwd: string, options?: ResolveCredentialBindingOptions): CredentialBinding;
+export declare function ensureSfOwnedAuthStore(): string;
+export declare function resolveCredentialBinding(ctx: ProjectContext | string, options?: ResolveCredentialBindingOptions): CredentialBinding;
+export { readCredentialSourceFromFile, writeCredentialSourceToFile, } from "./settingsFile.js";