@genfeedai/workflow-engine 0.2.0

package/README.md

@@ -0,0 +1,5 @@
+# Workflow Engine
+
+Core workflow execution engine for Genfeed.
+
+This package owns execution/runtime logic, workflow contracts, templates, and supporting types for workflow processing.

package/dist/execution/engine.d.ts

@@ -0,0 +1,52 @@
+import type {
+  CreditCostConfig,
+  ExecutableNode,
+  ExecutableWorkflow,
+  ExecutionOptions,
+  ExecutionRunResult,
+  RetryConfig,
+} from '@workflow-engine/types';
+export type NodeExecutor = (
+  node: ExecutableNode,
+  inputs: Map<string, unknown>,
+  context: ExecutionContext,
+) => Promise<unknown>;
+export interface ExecutionContext {
+  workflowId: string;
+  runId: string;
+  organizationId: string;
+  userId: string;
+  abortSignal?: AbortSignal;
+}
+export interface EngineConfig {
+  maxConcurrency: number;
+  retryConfig: RetryConfig;
+  creditCosts: CreditCostConfig;
+  defaultExecutor?: NodeExecutor;
+}
+export declare class WorkflowEngine {
+  private executors;
+  private config;
+  constructor(config?: Partial<EngineConfig>);
+  registerExecutor(nodeType: string, executor: NodeExecutor): void;
+  getExecutor(nodeType: string): NodeExecutor | undefined;
+  execute(
+    workflow: ExecutableWorkflow,
+    options?: ExecutionOptions,
+  ): Promise<ExecutionRunResult>;
+  resume(
+    workflow: ExecutableWorkflow,
+    previousRunResult: ExecutionRunResult,
+    options?: ExecutionOptions,
+  ): Promise<ExecutionRunResult>;
+  private executeNode;
+  private gatherInputs;
+  private topologicalSort;
+  estimateCredits(nodes: ExecutableNode[]): number;
+  private emitProgress;
+  private emitNodeStatusChange;
+}
+export declare function createWorkflowEngine(
+  config?: Partial<EngineConfig>,
+): WorkflowEngine;
+//# sourceMappingURL=engine.d.ts.map

package/dist/execution/engine.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"engine.d.ts","sourceRoot":"","sources":["../../src/execution/engine.ts"],"names":[],"mappings":"AASA,OAAO,KAAK,EACV,gBAAgB,EAChB,cAAc,EACd,kBAAkB,EAClB,gBAAgB,EAEhB,kBAAkB,EAIlB,WAAW,EACZ,MAAM,wBAAwB,CAAC;AAIhC,MAAM,MAAM,YAAY,GAAG,CACzB,IAAI,EAAE,cAAc,EACpB,MAAM,EAAE,GAAG,CAAC,MAAM,EAAE,OAAO,CAAC,EAC5B,OAAO,EAAE,gBAAgB,KACtB,OAAO,CAAC,OAAO,CAAC,CAAC;AAEtB,MAAM,WAAW,gBAAgB;IAC/B,UAAU,EAAE,MAAM,CAAC;IACnB,KAAK,EAAE,MAAM,CAAC;IACd,cAAc,EAAE,MAAM,CAAC;IACvB,MAAM,EAAE,MAAM,CAAC;IACf,WAAW,CAAC,EAAE,WAAW,CAAC;CAC3B;AAED,MAAM,WAAW,YAAY;IAC3B,cAAc,EAAE,MAAM,CAAC;IACvB,WAAW,EAAE,WAAW,CAAC;IACzB,WAAW,EAAE,gBAAgB,CAAC;IAC9B,eAAe,CAAC,EAAE,YAAY,CAAC;CAChC;AAQD,qBAAa,cAAc;IACzB,OAAO,CAAC,SAAS,CAAmC;IACpD,OAAO,CAAC,MAAM,CAAe;gBAEjB,MAAM,GAAE,OAAO,CAAC,YAAY,CAAM;IAI9C,gBAAgB,CAAC,QAAQ,EAAE,MAAM,EAAE,QAAQ,EAAE,YAAY,GAAG,IAAI;IAIhE,WAAW,CAAC,QAAQ,EAAE,MAAM,GAAG,YAAY,GAAG,SAAS;IAIjD,OAAO,CACX,QAAQ,EAAE,kBAAkB,EAC5B,OAAO,GAAE,gBAAqB,GAC7B,OAAO,CAAC,kBAAkB,CAAC;IAkP9B,MAAM,CACJ,QAAQ,EAAE,kBAAkB,EAC5B,iBAAiB,EAAE,kBAAkB,EACrC,OAAO,GAAE,gBAAqB,GAC7B,OAAO,CAAC,kBAAkB,CAAC;YAiDhB,WAAW;IAwDzB,OAAO,CAAC,YAAY;IAgCpB,OAAO,CAAC,eAAe;IA2CvB,eAAe,CAAC,KAAK,EAAE,cAAc,EAAE,GAAG,MAAM;IAMhD,OAAO,CAAC,YAAY;IAapB,OAAO,CAAC,oBAAoB;CAY7B;AAED,wBAAgB,oBAAoB,CAClC,MAAM,CAAC,EAAE,OAAO,CAAC,YAAY,CAAC,GAC7B,cAAc,CAEhB"}

package/dist/execution/engine.js

@@ -0,0 +1,419 @@
+import {
+  canExecuteNode,
+  planPartialExecution,
+} from '@workflow-engine/execution/partial-execution';
+import {
+  analyzeForResume,
+  createCacheFromRun,
+} from '@workflow-engine/execution/resume-handler';
+import { withRetry } from '@workflow-engine/execution/retry-handler';
+import { DEFAULT_RETRY_CONFIG } from '@workflow-engine/types';
+import { v4 as uuidv4 } from 'uuid';
+
+const DEFAULT_ENGINE_CONFIG = {
+  creditCosts: {},
+  maxConcurrency: 3,
+  retryConfig: DEFAULT_RETRY_CONFIG,
+};
+export class WorkflowEngine {
+  executors = new Map();
+  config;
+  constructor(config = {}) {
+    this.config = { ...DEFAULT_ENGINE_CONFIG, ...config };
+  }
+  registerExecutor(nodeType, executor) {
+    this.executors.set(nodeType, executor);
+  }
+  getExecutor(nodeType) {
+    return this.executors.get(nodeType) ?? this.config.defaultExecutor;
+  }
+  async execute(workflow, options = {}) {
+    const runId = uuidv4();
+    const startedAt = new Date();
+    const nodeResults = new Map();
+    const nodeCache = new Map();
+    let totalCreditsUsed = 0;
+    // Pre-populate cache from nodes with cachedOutput (e.g. from resume)
+    for (const node of workflow.nodes) {
+      if (node.cachedOutput !== undefined) {
+        nodeCache.set(node.id, node.cachedOutput);
+      }
+    }
+    const context = {
+      organizationId: workflow.organizationId,
+      runId,
+      userId: workflow.userId,
+      workflowId: workflow.id,
+    };
+    let nodesToExecute;
+    let executionOrder;
+    if (options.nodeIds && options.nodeIds.length > 0) {
+      const plan = planPartialExecution(
+        options.nodeIds,
+        workflow.nodes,
+        workflow.edges,
+        nodeCache,
+      );
+      if (!plan.isValid) {
+        return {
+          completedAt: new Date(),
+          error: plan.errors.join('; '),
+          nodeResults,
+          runId,
+          startedAt,
+          status: 'failed',
+          totalCreditsUsed: 0,
+          workflowId: workflow.id,
+        };
+      }
+      nodesToExecute = plan.nodesToExecute;
+      executionOrder = plan.executionOrder;
+      for (const node of workflow.nodes) {
+        if (node.isLocked && node.cachedOutput !== undefined) {
+          nodeCache.set(node.id, node.cachedOutput);
+        }
+      }
+    } else {
+      nodesToExecute = workflow.nodes.map((n) => n.id);
+      executionOrder = this.topologicalSort(workflow);
+      if (options.respectLocks !== false) {
+        for (const nodeId of workflow.lockedNodeIds) {
+          const node = workflow.nodes.find((n) => n.id === nodeId);
+          if (node?.cachedOutput !== undefined) {
+            nodeCache.set(nodeId, node.cachedOutput);
+            nodeResults.set(nodeId, {
+              completedAt: new Date(),
+              creditsUsed: 0,
+              nodeId,
+              output: node.cachedOutput,
+              retryCount: 0,
+              startedAt,
+              status: 'skipped',
+            });
+          }
+        }
+      }
+    }
+    if (options.respectLocks !== false) {
+      nodesToExecute = nodesToExecute.filter(
+        (id) => !workflow.lockedNodeIds.includes(id) || !nodeCache.has(id),
+      );
+      executionOrder = executionOrder.filter(
+        (id) => !workflow.lockedNodeIds.includes(id) || !nodeCache.has(id),
+      );
+    }
+    if (options.availableCredits !== undefined) {
+      const estimatedCredits = this.estimateCredits(
+        nodesToExecute
+          .map((id) => workflow.nodes.find((n) => n.id === id))
+          .filter((n) => n !== undefined),
+      );
+      if (estimatedCredits > options.availableCredits) {
+        return {
+          completedAt: new Date(),
+          error: `Insufficient credits: need ${estimatedCredits}, have ${options.availableCredits}`,
+          nodeResults,
+          runId,
+          startedAt,
+          status: 'failed',
+          totalCreditsUsed: 0,
+          workflowId: workflow.id,
+        };
+      }
+    }
+    if (options.dryRun) {
+      return {
+        completedAt: new Date(),
+        nodeResults,
+        runId,
+        startedAt,
+        status: 'completed',
+        totalCreditsUsed: 0,
+        workflowId: workflow.id,
+      };
+    }
+    const completedNodes = new Set(
+      Array.from(nodeResults.entries())
+        .filter(([_, r]) => r.status === 'completed' || r.status === 'skipped')
+        .map(([id]) => id),
+    );
+    const failedNodes = new Set();
+    let currentStatus = 'running';
+    let lastError;
+    for (const nodeId of executionOrder) {
+      if (!nodesToExecute.includes(nodeId)) {
+        continue;
+      }
+      if (completedNodes.has(nodeId)) {
+        continue;
+      }
+      const node = workflow.nodes.find((n) => n.id === nodeId);
+      if (!node) {
+        lastError = `Node ${nodeId} not found`;
+        currentStatus = 'failed';
+        break;
+      }
+      if (
+        !canExecuteNode(
+          nodeId,
+          workflow.nodes,
+          workflow.edges,
+          completedNodes,
+          nodeCache,
+        )
+      ) {
+        lastError = `Dependencies not satisfied for node ${nodeId}`;
+        failedNodes.add(nodeId);
+        currentStatus = 'failed';
+        break;
+      }
+      const inputs = this.gatherInputs(node, workflow.edges, nodeCache);
+      this.emitNodeStatusChange(options, {
+        newStatus: 'running',
+        nodeId,
+        previousStatus: 'pending',
+        runId,
+        timestamp: new Date(),
+        workflowId: workflow.id,
+      });
+      const result = await this.executeNode(node, inputs, context, options);
+      nodeResults.set(nodeId, result);
+      totalCreditsUsed += result.creditsUsed;
+      if (result.status === 'completed') {
+        completedNodes.add(nodeId);
+        if (result.output !== undefined) {
+          nodeCache.set(nodeId, result.output);
+        }
+      } else if (result.status === 'failed') {
+        failedNodes.add(nodeId);
+        lastError = result.error;
+        currentStatus = 'failed';
+        this.emitNodeStatusChange(options, {
+          error: result.error,
+          newStatus: 'failed',
+          nodeId,
+          previousStatus: 'running',
+          runId,
+          timestamp: new Date(),
+          workflowId: workflow.id,
+        });
+        break;
+      }
+      const totalNodes = nodesToExecute.length || 1;
+      // Only count completed nodes that are in the execution list for progress
+      const executedCount = nodesToExecute.filter((id) =>
+        completedNodes.has(id),
+      ).length;
+      const progress = Math.round((executedCount / totalNodes) * 100);
+      this.emitProgress(options, {
+        completedNodes: Array.from(completedNodes),
+        currentNodeId: nodeId,
+        currentNodeLabel: node.label,
+        failedNodes: Array.from(failedNodes),
+        progress,
+        runId,
+        timestamp: new Date(),
+        workflowId: workflow.id,
+      });
+      this.emitNodeStatusChange(options, {
+        newStatus: result.status,
+        nodeId,
+        output: result.output,
+        previousStatus: 'running',
+        runId,
+        timestamp: new Date(),
+        workflowId: workflow.id,
+      });
+    }
+    if (currentStatus !== 'failed') {
+      // Count only nodes that were in the execution list (not pre-skipped locked nodes)
+      const executedOrSkipped = nodesToExecute.every((id) =>
+        completedNodes.has(id),
+      );
+      currentStatus = executedOrSkipped ? 'completed' : 'failed';
+    }
+    return {
+      completedAt: new Date(),
+      error: lastError,
+      nodeResults,
+      runId,
+      startedAt,
+      status: currentStatus,
+      totalCreditsUsed,
+      workflowId: workflow.id,
+    };
+  }
+  resume(workflow, previousRunResult, options = {}) {
+    const previousRun = {
+      completedAt: previousRunResult.completedAt,
+      creditsUsed: previousRunResult.totalCreditsUsed,
+      error: previousRunResult.error,
+      executedNodeIds: Array.from(previousRunResult.nodeResults.keys()),
+      failedNodeId: Array.from(previousRunResult.nodeResults.entries()).find(
+        ([_, r]) => r.status === 'failed',
+      )?.[0],
+      nodeResults: Array.from(previousRunResult.nodeResults.values()),
+      runId: previousRunResult.runId,
+      startedAt: previousRunResult.startedAt,
+      status: previousRunResult.status,
+    };
+    const analysis = analyzeForResume(
+      previousRun,
+      workflow.nodes,
+      workflow.edges,
+    );
+    if (!analysis.canResume) {
+      return Promise.resolve({
+        completedAt: new Date(),
+        error: analysis.reason ?? 'Cannot resume execution',
+        nodeResults: new Map(),
+        runId: uuidv4(),
+        startedAt: new Date(),
+        status: 'failed',
+        totalCreditsUsed: 0,
+        workflowId: workflow.id,
+      });
+    }
+    const cache = createCacheFromRun(previousRun);
+    for (const node of workflow.nodes) {
+      if (cache.has(node.id)) {
+        node.cachedOutput = cache.get(node.id);
+      }
+    }
+    return this.execute(workflow, {
+      ...options,
+      nodeIds: analysis.nodesToReExecute,
+      resumeFromNodeId: analysis.resumeFromNodeId ?? undefined,
+    });
+  }
+  async executeNode(node, inputs, context, options) {
+    const startedAt = new Date();
+    let retryCount = 0;
+    const maxRetries = options.maxRetries ?? this.config.retryConfig.maxRetries;
+    const executor = this.getExecutor(node.type);
+    if (!executor) {
+      return {
+        completedAt: new Date(),
+        creditsUsed: 0,
+        error: `No executor registered for node type: ${node.type}`,
+        nodeId: node.id,
+        retryCount: 0,
+        startedAt,
+        status: 'failed',
+      };
+    }
+    try {
+      const output = await withRetry(
+        () => executor(node, inputs, context),
+        { ...this.config.retryConfig, maxRetries },
+        (attempt) => {
+          retryCount = attempt;
+        },
+      );
+      const creditsUsed = this.config.creditCosts[node.type] ?? 0;
+      return {
+        completedAt: new Date(),
+        creditsUsed,
+        nodeId: node.id,
+        output,
+        retryCount,
+        startedAt,
+        status: 'completed',
+      };
+    } catch (error) {
+      return {
+        completedAt: new Date(),
+        creditsUsed: 0,
+        error: error instanceof Error ? error.message : String(error),
+        nodeId: node.id,
+        retryCount,
+        startedAt,
+        status: 'failed',
+      };
+    }
+  }
+  gatherInputs(node, edges, cache) {
+    const inputs = new Map();
+    for (const edge of edges) {
+      if (edge.target === node.id) {
+        const sourceOutput = cache.get(edge.source);
+        if (sourceOutput !== undefined) {
+          const handleKey = edge.targetHandle ?? edge.source;
+          if (
+            edge.targetHandle &&
+            sourceOutput &&
+            typeof sourceOutput === 'object' &&
+            edge.targetHandle in sourceOutput
+          ) {
+            inputs.set(handleKey, sourceOutput[edge.targetHandle]);
+          } else {
+            inputs.set(handleKey, sourceOutput);
+          }
+        }
+      }
+    }
+    return inputs;
+  }
+  topologicalSort(workflow) {
+    const inDegree = new Map();
+    const adjList = new Map();
+    for (const node of workflow.nodes) {
+      inDegree.set(node.id, 0);
+      adjList.set(node.id, []);
+    }
+    for (const edge of workflow.edges) {
+      inDegree.set(edge.target, (inDegree.get(edge.target) ?? 0) + 1);
+      const adj = adjList.get(edge.source) ?? [];
+      adj.push(edge.target);
+      adjList.set(edge.source, adj);
+    }
+    const queue = [];
+    for (const [nodeId, degree] of inDegree) {
+      if (degree === 0) {
+        queue.push(nodeId);
+      }
+    }
+    const result = [];
+    while (queue.length > 0) {
+      const current = queue.shift();
+      if (!current) {
+        continue;
+      }
+      result.push(current);
+      for (const neighbor of adjList.get(current) ?? []) {
+        const newDegree = (inDegree.get(neighbor) ?? 0) - 1;
+        inDegree.set(neighbor, newDegree);
+        if (newDegree === 0) {
+          queue.push(neighbor);
+        }
+      }
+    }
+    return result;
+  }
+  estimateCredits(nodes) {
+    return nodes.reduce((total, node) => {
+      return total + (this.config.creditCosts[node.type] ?? 0);
+    }, 0);
+  }
+  emitProgress(options, event) {
+    if (options.onProgress) {
+      try {
+        options.onProgress(event);
+      } catch {
+        /* Ignore callback errors */
+      }
+    }
+  }
+  emitNodeStatusChange(options, event) {
+    if (options.onNodeStatusChange) {
+      try {
+        options.onNodeStatusChange(event);
+      } catch {
+        /* Ignore callback errors */
+      }
+    }
+  }
+}
+export function createWorkflowEngine(config) {
+  return new WorkflowEngine(config);
+}

package/dist/execution/index.d.ts

@@ -0,0 +1,5 @@
+export * from '@workflow-engine/execution/engine';
+export * from '@workflow-engine/execution/partial-execution';
+export * from '@workflow-engine/execution/resume-handler';
+export * from '@workflow-engine/execution/retry-handler';
+//# sourceMappingURL=index.d.ts.map

package/dist/execution/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/execution/index.ts"],"names":[],"mappings":"AAAA,cAAc,mCAAmC,CAAC;AAClD,cAAc,8CAA8C,CAAC;AAC7D,cAAc,2CAA2C,CAAC;AAC1D,cAAc,0CAA0C,CAAC"}

package/dist/execution/index.js

@@ -0,0 +1,4 @@
+export * from '@workflow-engine/execution/engine';
+export * from '@workflow-engine/execution/partial-execution';
+export * from '@workflow-engine/execution/resume-handler';
+export * from '@workflow-engine/execution/retry-handler';

package/dist/execution/partial-execution.d.ts

@@ -0,0 +1,26 @@
+import type { ExecutableEdge, ExecutableNode } from '@workflow-engine/types';
+export interface PartialExecutionPlan {
+  nodesToExecute: string[];
+  nodesRequiringCache: string[];
+  missingDependencies: Array<{
+    nodeId: string;
+    missingInputs: string[];
+  }>;
+  executionOrder: string[];
+  isValid: boolean;
+  errors: string[];
+}
+export declare function planPartialExecution(
+  selectedNodeIds: string[],
+  nodes: ExecutableNode[],
+  edges: ExecutableEdge[],
+  nodeCache: Map<string, unknown>,
+): PartialExecutionPlan;
+export declare function canExecuteNode(
+  nodeId: string,
+  nodes: ExecutableNode[],
+  edges: ExecutableEdge[],
+  completedNodes: Set<string>,
+  nodeCache: Map<string, unknown>,
+): boolean;
+//# sourceMappingURL=partial-execution.d.ts.map

package/dist/execution/partial-execution.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"partial-execution.d.ts","sourceRoot":"","sources":["../../src/execution/partial-execution.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,cAAc,EAAE,MAAM,wBAAwB,CAAC;AAE7E,MAAM,WAAW,oBAAoB;IACnC,cAAc,EAAE,MAAM,EAAE,CAAC;IACzB,mBAAmB,EAAE,MAAM,EAAE,CAAC;IAC9B,mBAAmB,EAAE,KAAK,CAAC;QACzB,MAAM,EAAE,MAAM,CAAC;QACf,aAAa,EAAE,MAAM,EAAE,CAAC;KACzB,CAAC,CAAC;IACH,cAAc,EAAE,MAAM,EAAE,CAAC;IACzB,OAAO,EAAE,OAAO,CAAC;IACjB,MAAM,EAAE,MAAM,EAAE,CAAC;CAClB;AAiGD,wBAAgB,oBAAoB,CAClC,eAAe,EAAE,MAAM,EAAE,EACzB,KAAK,EAAE,cAAc,EAAE,EACvB,KAAK,EAAE,cAAc,EAAE,EACvB,SAAS,EAAE,GAAG,CAAC,MAAM,EAAE,OAAO,CAAC,GAC9B,oBAAoB,CAqFtB;AAED,wBAAgB,cAAc,CAC5B,MAAM,EAAE,MAAM,EACd,KAAK,EAAE,cAAc,EAAE,EACvB,KAAK,EAAE,cAAc,EAAE,EACvB,cAAc,EAAE,GAAG,CAAC,MAAM,CAAC,EAC3B,SAAS,EAAE,GAAG,CAAC,MAAM,EAAE,OAAO,CAAC,GAC9B,OAAO,CA2BT"}

package/dist/execution/partial-execution.js

@@ -0,0 +1,174 @@
+function buildDependencyGraph(nodes, edges) {
+  const dependencies = new Map();
+  for (const node of nodes) {
+    dependencies.set(node.id, []);
+  }
+  for (const edge of edges) {
+    const deps = dependencies.get(edge.target) ?? [];
+    deps.push(edge.source);
+    dependencies.set(edge.target, deps);
+  }
+  return dependencies;
+}
+function topologicalSort(nodeIds, dependencies) {
+  const inDegree = new Map();
+  const adjList = new Map();
+  for (const nodeId of nodeIds) {
+    inDegree.set(nodeId, 0);
+    adjList.set(nodeId, []);
+  }
+  for (const nodeId of nodeIds) {
+    const deps = dependencies.get(nodeId) ?? [];
+    for (const dep of deps) {
+      if (nodeIds.includes(dep)) {
+        inDegree.set(nodeId, (inDegree.get(nodeId) ?? 0) + 1);
+        const adj = adjList.get(dep) ?? [];
+        adj.push(nodeId);
+        adjList.set(dep, adj);
+      }
+    }
+  }
+  const queue = [];
+  for (const [nodeId, degree] of inDegree) {
+    if (degree === 0) {
+      queue.push(nodeId);
+    }
+  }
+  const result = [];
+  while (queue.length > 0) {
+    const current = queue.shift();
+    if (!current) {
+      continue;
+    }
+    result.push(current);
+    for (const neighbor of adjList.get(current) ?? []) {
+      const newDegree = (inDegree.get(neighbor) ?? 0) - 1;
+      inDegree.set(neighbor, newDegree);
+      if (newDegree === 0) {
+        queue.push(neighbor);
+      }
+    }
+  }
+  return result;
+}
+function findAllDependencies(nodeIds, dependencies) {
+  const visited = new Set();
+  const queue = [...nodeIds];
+  while (queue.length > 0) {
+    const current = queue.shift();
+    if (!current || visited.has(current)) {
+      continue;
+    }
+    visited.add(current);
+    const deps = dependencies.get(current) ?? [];
+    for (const dep of deps) {
+      if (!visited.has(dep)) {
+        queue.push(dep);
+      }
+    }
+  }
+  return visited;
+}
+export function planPartialExecution(selectedNodeIds, nodes, edges, nodeCache) {
+  const errors = [];
+  const nodeMap = new Map(nodes.map((n) => [n.id, n]));
+  // Validate selected nodes exist
+  for (const nodeId of selectedNodeIds) {
+    if (!nodeMap.has(nodeId)) {
+      errors.push(`Node ${nodeId} not found in workflow`);
+    }
+  }
+  if (errors.length > 0) {
+    return {
+      errors,
+      executionOrder: [],
+      isValid: false,
+      missingDependencies: [],
+      nodesRequiringCache: [],
+      nodesToExecute: [],
+    };
+  }
+  const dependencies = buildDependencyGraph(nodes, edges);
+  const allNeededNodes = findAllDependencies(selectedNodeIds, dependencies);
+  const nodesToExecute = new Set(selectedNodeIds);
+  const nodesRequiringCache = [];
+  const missingDependencies = [];
+  for (const nodeId of allNeededNodes) {
+    if (!nodesToExecute.has(nodeId)) {
+      const node = nodeMap.get(nodeId);
+      if (!node) {
+        continue;
+      }
+      if (node.isLocked && node.cachedOutput !== undefined) {
+        nodesRequiringCache.push(nodeId);
+      } else if (nodeCache.has(nodeId)) {
+        nodesRequiringCache.push(nodeId);
+      } else {
+        for (const selectedNodeId of selectedNodeIds) {
+          const selectedDeps = dependencies.get(selectedNodeId) ?? [];
+          if (
+            selectedDeps.includes(nodeId) ||
+            findAllDependencies([selectedNodeId], dependencies).has(nodeId)
+          ) {
+            const existing = missingDependencies.find(
+              (m) => m.nodeId === selectedNodeId,
+            );
+            if (existing) {
+              existing.missingInputs.push(nodeId);
+            } else {
+              missingDependencies.push({
+                missingInputs: [nodeId],
+                nodeId: selectedNodeId,
+              });
+            }
+          }
+        }
+      }
+    }
+  }
+  if (missingDependencies.length > 0) {
+    for (const missing of missingDependencies) {
+      errors.push(
+        `Node ${missing.nodeId} requires output from ${missing.missingInputs.join(', ')} which is not available in cache`,
+      );
+    }
+  }
+  const executionOrder = topologicalSort(selectedNodeIds, dependencies);
+  return {
+    errors,
+    executionOrder,
+    isValid: errors.length === 0,
+    missingDependencies,
+    nodesRequiringCache,
+    nodesToExecute: selectedNodeIds,
+  };
+}
+export function canExecuteNode(
+  nodeId,
+  nodes,
+  edges,
+  completedNodes,
+  nodeCache,
+) {
+  const node = nodes.find((n) => n.id === nodeId);
+  if (!node) {
+    return false;
+  }
+  const nodeDependencies = edges
+    .filter((e) => e.target === nodeId)
+    .map((e) => e.source);
+  for (const dep of nodeDependencies) {
+    const depNode = nodes.find((n) => n.id === dep);
+    if (!depNode) {
+      return false;
+    }
+    const isCompleted = completedNodes.has(dep);
+    const isCached = nodeCache.has(dep);
+    const isLockedWithOutput =
+      depNode.isLocked && depNode.cachedOutput !== undefined;
+    if (!isCompleted && !isCached && !isLockedWithOutput) {
+      return false;
+    }
+  }
+  return true;
+}