@pikku/core 0.11.2 → 0.12.1

package/src/wirings/workflow/graph/graph-runner.ts

@@ -1,75 +1,89 @@
 import type { PikkuWorkflowService } from '../pikku-workflow-service.js'
-import type {
-  GraphNodeConfig,
-  RefValue,
-  RefFn,
-  NextConfig,
-  GraphWireState,
-  PikkuGraphWire,
-  WorkflowGraphDefinition,
-} from './workflow-graph.types.js'
-import { createRef, isRef } from './workflow-graph.types.js'
+import type { GraphWireState, PikkuGraphWire } from './workflow-graph.types.js'
 import { pikkuState } from '../../../pikku-state.js'
+import type { WorkflowRuntimeMeta, WorkflowRunWire } from '../workflow.types.js'
+import { RPCNotFoundError } from '../../rpc/rpc-runner.js'
+
+function buildTemplateRegex(nodeId: string): RegExp | null {
+  if (!nodeId.includes('${')) return null
+  const escaped = nodeId
+    .split(/\$\{[^}]+\}/)
+    .map((part) => part.replace(/[.*+?^${}()|[\]\\]/g, '\\$&'))
+    .join('.+')
+  return new RegExp(`^${escaped}$`)
+}
 
-/**
- * Add a workflow graph to the system
- * This is called by the generated workflow wirings
- */
-export const addWorkflowGraph = (
-  workflowName: string,
-  graphResult: { graph: Record<string, GraphNodeConfig<string>>; wires?: any }
-) => {
-  // Get workflow metadata from inspector
-  const meta = pikkuState(null, 'workflows', 'meta')
-  const workflowMeta = meta[workflowName]
-  if (!workflowMeta) {
-    throw new Error(
-      `Workflow metadata not found for '${workflowName}'. Make sure to run the CLI to generate metadata.`
-    )
+function remapStepNamesToNodeIds(
+  stepNames: string[],
+  nodes: Record<string, any>,
+  graphName: string
+): string[] {
+  const templatePatterns = new Map<string, RegExp>()
+  for (const nodeId of Object.keys(nodes)) {
+    const regex = buildTemplateRegex(nodeId)
+    if (regex) templatePatterns.set(nodeId, regex)
   }
-
-  // Store workflow graph definition in state
-  const registrations = pikkuState(null, 'workflows', 'graphRegistrations')
-  registrations.set(workflowName, {
-    name: workflowName,
-    wires: graphResult.wires || {},
-    graph: graphResult.graph,
+  if (templatePatterns.size === 0) return stepNames
+  return stepNames.map((name) => {
+    if (nodes[name]) return name
+    const matches: string[] = []
+    for (const [nodeId, regex] of templatePatterns) {
+      if (regex.test(name)) matches.push(nodeId)
+    }
+    if (matches.length > 1) {
+      throw new Error(
+        `Workflow graph '${graphName}': ambiguous template node match for '${name}' (${matches.join(', ')})`
+      )
+    }
+    if (matches.length === 1) {
+      return matches[0]!
+    }
+    return name
   })
 }
 
-/**
- * Get a registered workflow graph by name
- */
-export function getWorkflowGraph(
-  name: string
-): WorkflowGraphDefinition<any> | undefined {
-  const registrations = pikkuState(null, 'workflows', 'graphRegistrations')
-  return registrations.get(name)
+function remapBranchKeys(
+  branchKeys: Record<string, string>,
+  nodes: Record<string, any>,
+  graphName: string
+): Record<string, string> {
+  const templatePatterns = new Map<string, RegExp>()
+  for (const nodeId of Object.keys(nodes)) {
+    const regex = buildTemplateRegex(nodeId)
+    if (regex) templatePatterns.set(nodeId, regex)
+  }
+  if (templatePatterns.size === 0) return branchKeys
+  const remapped: Record<string, string> = {}
+  for (const [key, value] of Object.entries(branchKeys)) {
+    let mappedKey = key
+    if (!nodes[key]) {
+      const matches: string[] = []
+      for (const [nodeId, regex] of templatePatterns) {
+        if (regex.test(key)) matches.push(nodeId)
+      }
+      if (matches.length > 1) {
+        throw new Error(
+          `Workflow graph '${graphName}': ambiguous template branch key match for '${key}' (${matches.join(', ')})`
+        )
+      }
+      if (matches.length === 1) {
+        mappedKey = matches[0]!
+      }
+    }
+    remapped[mappedKey] = value
+  }
+  return remapped
 }
 
-/**
- * Resolve next config to array of node IDs
- * For branching (Record), uses the branch key from step
- */
-function resolveNextFromConfig(
-  next: NextConfig<string> | undefined,
-  branchKey?: string
-): string[] {
-  if (!next) return []
-
-  if (typeof next === 'string') return [next]
-  if (Array.isArray(next)) return next
-
-  // Record (branching) - use branch key set by graph.branch()
-  if (!branchKey || !(branchKey in next)) return []
-
-  const branchNext = next[branchKey]
-  return Array.isArray(branchNext) ? branchNext : [branchNext]
+function isDataRef(value: unknown): value is { $ref: string; path?: string } {
+  return (
+    typeof value === 'object' &&
+    value !== null &&
+    '$ref' in value &&
+    typeof (value as any).$ref === 'string'
+  )
 }
 
-/**
- * Template value - represents a string template with variable interpolation
- */
 interface TemplateValue {
   $template: {
     parts: string[]
@@ -77,9 +91,6 @@ interface TemplateValue {
   }
 }
 
-/**
- * Check if a value is a template
- */
 function isTemplate(value: unknown): value is TemplateValue {
   return (
     typeof value === 'object' &&
@@ -89,73 +100,37 @@ function isTemplate(value: unknown): value is TemplateValue {
   )
 }
 
-/**
- * Create a template function for use in input callbacks
- */
-function createTemplate(templateStr: string, refs: RefValue[]): TemplateValue {
-  const parts: string[] = []
-  const expressions: Array<{ $ref: string; path?: string }> = []
-
-  const regex = /\$(\d+)/g
-  let lastIndex = 0
-  let match
-
-  while ((match = regex.exec(templateStr)) !== null) {
-    parts.push(templateStr.slice(lastIndex, match.index))
-    const refIndex = parseInt(match[1]!, 10)
-    const refValue = refs[refIndex]
-    if (refValue) {
-      expressions.push({ $ref: refValue.nodeId, path: refValue.path })
-    } else {
-      expressions.push({ $ref: 'unknown' })
-    }
-    lastIndex = regex.lastIndex
-  }
-  parts.push(templateStr.slice(lastIndex))
-
-  return { $template: { parts, expressions } }
+function getWorkflowMeta(name: string): WorkflowRuntimeMeta | undefined {
+  const meta = pikkuState(null, 'workflows', 'meta')
+  return meta[name]
 }
 
-/**
- * Evaluate a node's input callback to get the input mapping
- */
-function evaluateInputCallback(
-  node: GraphNodeConfig
-): Record<string, unknown | RefValue | TemplateValue> {
-  if (!node.input) return {}
+function resolveNextFromConfig(next: unknown, branchKey?: string): string[] {
+  if (!next) return []
 
-  const ref: RefFn<string> = (targetNodeId: string, path?: string) =>
-    createRef(targetNodeId, path)
+  if (typeof next === 'string') return [next]
+  if (Array.isArray(next)) return next
 
-  const template = (templateStr: string, refs: RefValue[]) =>
-    createTemplate(templateStr, refs)
+  if (typeof next === 'object' && next !== null) {
+    if (!branchKey || !(branchKey in next)) return []
+    const branchNext = (next as Record<string, string | string[]>)[branchKey]!
+    return Array.isArray(branchNext) ? branchNext : [branchNext]
+  }
 
-  // Call with both ref and template - input callback may accept 1 or 2 params
-  return (node.input as any)(ref, template)
+  return []
 }
 
-/**
- * Extract node IDs referenced in an input mapping (including from templates)
- */
-function extractReferencedNodeIds(
-  inputMapping: Record<string, unknown | RefValue | TemplateValue>
-): string[] {
-  const nodeIds: string[] = []
-  for (const value of Object.values(inputMapping)) {
-    if (isRef(value)) {
-      nodeIds.push(value.nodeId)
-    } else if (isTemplate(value)) {
-      for (const expr of value.$template.expressions) {
-        nodeIds.push(expr.$ref)
-      }
-    }
+function getValueAtPath(obj: any, path: string): any {
+  if (!path) return obj
+  const parts = path.split('.')
+  let current = obj
+  for (const part of parts) {
+    if (current == null) return undefined
+    current = current[part]
   }
-  return [...new Set(nodeIds)]
+  return current
 }
 
-/**
- * Resolve a template value using node results
- */
 function resolveTemplate(
   template: TemplateValue,
   nodeResults: Record<string, any>
@@ -165,7 +140,7 @@ function resolveTemplate(
   for (let i = 0; i < parts.length; i++) {
     result += parts[i]
     if (i < expressions.length) {
-      const expr = expressions[i]
+      const expr = expressions[i]!
       const nodeResult = nodeResults[expr.$ref]
       const value = expr.path
         ? getValueAtPath(nodeResult, expr.path)
@@ -176,62 +151,144 @@ function resolveTemplate(
   return result
 }
 
-/**
- * Resolve input mapping using node results
- */
-function resolveInputMapping(
-  inputMapping: Record<string, unknown | RefValue | TemplateValue>,
+function resolveValue(value: unknown, nodeResults: Record<string, any>): any {
+  if (isDataRef(value)) {
+    const source = nodeResults[value.$ref]
+    return value.path ? getValueAtPath(source, value.path) : source
+  }
+  if (isTemplate(value)) {
+    return resolveTemplate(value, nodeResults)
+  }
+  if (Array.isArray(value)) {
+    return value.map((item) => resolveValue(item, nodeResults))
+  }
+  if (typeof value === 'object' && value !== null) {
+    const resolved: Record<string, any> = {}
+    for (const [k, v] of Object.entries(value)) {
+      resolved[k] = resolveValue(v, nodeResults)
+    }
+    return resolved
+  }
+  return value
+}
+
+function resolveSerializedInput(
+  input: Record<string, unknown> | undefined,
   nodeResults: Record<string, any>
 ): Record<string, any> {
+  if (!input || Object.keys(input).length === 0) return {}
+
   const resolved: Record<string, any> = {}
+  for (const [key, value] of Object.entries(input)) {
+    resolved[key] = resolveValue(value, nodeResults)
+  }
+  return resolved
+}
 
-  for (const [key, value] of Object.entries(inputMapping)) {
-    if (isRef(value)) {
-      const nodeResult = nodeResults[value.nodeId]
-      resolved[key] = value.path
-        ? getValueAtPath(nodeResult, value.path)
-        : nodeResult
-    } else if (isTemplate(value)) {
-      resolved[key] = resolveTemplate(value, nodeResults)
-    } else {
-      resolved[key] = value
+function collectReferencedNodeIds(value: unknown, nodeIds: string[]): void {
+  if (isDataRef(value)) {
+    nodeIds.push(value.$ref)
+  } else if (isTemplate(value)) {
+    for (const expr of value.$template.expressions) {
+      nodeIds.push(expr.$ref)
+    }
+  } else if (Array.isArray(value)) {
+    for (const item of value) {
+      collectReferencedNodeIds(item, nodeIds)
+    }
+  } else if (typeof value === 'object' && value !== null) {
+    for (const v of Object.values(value)) {
+      collectReferencedNodeIds(v, nodeIds)
     }
   }
+}
 
-  return resolved
+function extractReferencedNodeIds(
+  input: Record<string, unknown> | undefined
+): string[] {
+  if (!input) return []
+  const nodeIds: string[] = []
+  for (const value of Object.values(input)) {
+    collectReferencedNodeIds(value, nodeIds)
+  }
+  return [...new Set(nodeIds)]
 }
 
-/**
- * Get value at a dot-notation path from an object
- */
-function getValueAtPath(obj: any, path: string): any {
-  if (!path) return obj
-  const parts = path.split('.')
-  let current = obj
-  for (const part of parts) {
-    if (current == null) return undefined
-    current = current[part]
+const IGNORED_REFS = new Set(['trigger', '$item', 'unknown'])
+
+function normalizeNodeTargets(value: unknown): string[] {
+  if (!value) return []
+  if (typeof value === 'string') return [value]
+  if (Array.isArray(value)) return value.filter((v) => typeof v === 'string')
+  if (typeof value === 'object') {
+    const targets: string[] = []
+    for (const branchTarget of Object.values(
+      value as Record<string, unknown>
+    )) {
+      targets.push(...normalizeNodeTargets(branchTarget))
+    }
+    return targets
   }
-  return current
+  return []
 }
 
-/**
- * Get the RPC name from a graph node's func
- * Supports both function references (func.name) and string RPC names
- */
-function getRpcName(node: GraphNodeConfig): string {
-  const func = node.func as any
-  // If func is a string, use it directly as the RPC name
-  if (typeof func === 'string') {
-    return func
-  }
-  // Otherwise, it's a function reference - use its name
-  return func?.name || 'unknown'
+function validateGraphReferences(
+  graphName: string,
+  nodes: Record<string, any>,
+  entryNodes: string[]
+): void {
+  const nodeIds = new Set(Object.keys(nodes))
+
+  for (const entryId of entryNodes) {
+    if (!nodeIds.has(entryId)) {
+      throw new Error(
+        `Workflow graph '${graphName}': entry node '${entryId}' is not defined`
+      )
+    }
+  }
+
+  for (const [nodeId, node] of Object.entries(nodes)) {
+    const inputRefs = extractReferencedNodeIds(node.input).filter(
+      (id) => !IGNORED_REFS.has(id)
+    )
+    for (const refId of inputRefs) {
+      if (!nodeIds.has(refId)) {
+        throw new Error(
+          `Workflow graph '${graphName}': node '${nodeId}' references unknown node '${refId}' in input`
+        )
+      }
+    }
+
+    const nextTargets = normalizeNodeTargets(node.next)
+    for (const nextId of nextTargets) {
+      if (!nodeIds.has(nextId)) {
+        throw new Error(
+          `Workflow graph '${graphName}': node '${nodeId}' routes to unknown node '${nextId}'`
+        )
+      }
+    }
+
+    const errorTargets = normalizeNodeTargets(node.onError)
+    for (const errorId of errorTargets) {
+      if (!nodeIds.has(errorId)) {
+        throw new Error(
+          `Workflow graph '${graphName}': node '${nodeId}' onError targets unknown node '${errorId}'`
+        )
+      }
+    }
+  }
+}
+
+function areDependenciesSatisfied(
+  node: { input?: Record<string, unknown> },
+  completedNodeIds: Set<string>
+): boolean {
+  const deps = extractReferencedNodeIds(node.input).filter(
+    (id) => !IGNORED_REFS.has(id)
+  )
+  return deps.every((dep) => completedNodeIds.has(dep))
 }
 
-/**
- * Queue a graph node for execution
- */
 async function queueGraphNode(
   workflowService: PikkuWorkflowService,
   runId: string,
@@ -240,105 +297,137 @@ async function queueGraphNode(
   rpcName: string,
   input: any
 ): Promise<void> {
-  // Step name convention: node:<nodeId>
-  // Graph name is stored as the workflow name on the run
-  await workflowService.insertStepState(
-    runId,
-    `node:${nodeId}`,
-    rpcName,
-    input,
-    { retries: 3 }
-  )
-  await workflowService.resumeWorkflow(runId)
+  await workflowService.insertStepState(runId, nodeId, rpcName, input, {
+    retries: 0,
+  })
+  await workflowService.queueStepWorker(runId, nodeId, rpcName, input)
 }
 
-/**
- * Continue graph execution
- * Non-blocking - finds pending nodes, resolves inputs, queues them for execution
- */
 export async function continueGraph(
   workflowService: PikkuWorkflowService,
   runId: string,
-  graphName: string
+  graphName: string,
+  overrideMeta?: WorkflowRuntimeMeta
 ): Promise<void> {
-  const definition = getWorkflowGraph(graphName)
-  if (!definition) {
-    throw new Error(`Workflow graph '${graphName}' not found`)
+  const meta = overrideMeta ?? getWorkflowMeta(graphName)
+  if (!meta?.nodes) {
+    throw new Error(`Workflow graph meta '${graphName}' not found`)
   }
 
-  const graph = definition.graph
+  const nodes = meta.nodes
+  validateGraphReferences(graphName, nodes, meta.entryNodeIds ?? [])
+
+  const {
+    completedNodeIds: rawCompleted,
+    failedNodeIds: rawFailed,
+    branchKeys: rawBranch,
+  } = await workflowService.getCompletedGraphState(runId)
+  const completedNodeIds = remapStepNamesToNodeIds(
+    rawCompleted,
+    nodes,
+    graphName
+  )
+  const completedNodeIdSet = new Set(completedNodeIds)
+  const failedNodeIds = remapStepNamesToNodeIds(rawFailed, nodes, graphName)
+  const branchKeys = remapBranchKeys(rawBranch, nodes, graphName)
+
+  if (failedNodeIds.length > 0) {
+    const failedNode = failedNodeIds[0]!
+    await workflowService.updateRunStatus(runId, 'failed', undefined, {
+      message: `Graph node '${failedNode}' failed after exhausting retries`,
+      stack: '',
+      code: 'GRAPH_NODE_FAILED',
+    })
+    return
+  }
 
-  // Get completed node IDs + branch keys (lightweight, no results)
-  const { completedNodeIds, branchKeys } =
-    await workflowService.getCompletedGraphState(runId)
+  const currentRun = await workflowService.getRun(runId)
+  if (currentRun?.status === 'suspended') {
+    return
+  }
 
-  // Find candidate next nodes from completed nodes
-  const candidateNodes: string[] = []
+  const candidateNodes = new Set<string>()
 
   for (const nodeId of completedNodeIds) {
-    const node = graph[nodeId]
+    const node = nodes[nodeId]
     if (!node?.next) continue
 
     const nextNodes = resolveNextFromConfig(node.next, branchKeys[nodeId])
-    candidateNodes.push(...nextNodes)
+    for (const nextNode of nextNodes) {
+      candidateNodes.add(nextNode)
+    }
+  }
+
+  for (const entryId of meta.entryNodeIds ?? []) {
+    candidateNodes.add(entryId)
   }
 
-  if (candidateNodes.length === 0 && completedNodeIds.length > 0) {
-    // No more nodes to run - graph complete
+  if (candidateNodes.size === 0 && completedNodeIds.length > 0) {
     await workflowService.updateRunStatus(runId, 'completed')
     return
   }
 
-  // Filter to only nodes that don't have a step yet
-  const nodesToQueue = await workflowService.getNodesWithoutSteps(
-    runId,
-    candidateNodes
-  )
+  const unstartedNodes = await workflowService.getNodesWithoutSteps(runId, [
+    ...candidateNodes,
+  ])
 
-  // Queue each node for execution
-  for (const nodeId of nodesToQueue) {
-    const node = graph[nodeId]
-    if (!node) continue
+  const nodesToQueue = unstartedNodes.filter((nodeId) => {
+    const node = nodes[nodeId]
+    return node && areDependenciesSatisfied(node, completedNodeIdSet)
+  })
 
-    // Evaluate input callback to get the mapping
-    const inputMapping = evaluateInputCallback(node)
+  if (nodesToQueue.length === 0) {
+    const allRpcNodes = Object.entries(nodes)
+      .filter(([_, n]) => n.rpcName)
+      .map(([id]) => id)
+    const allRpcCompleted = allRpcNodes.every((id) =>
+      completedNodeIdSet.has(id)
+    )
+    if (allRpcCompleted) {
+      await workflowService.updateRunStatus(runId, 'completed')
+    }
+    return
+  }
+
+  const run = await workflowService.getRun(runId)
+  const triggerInput = run?.input
+
+  for (const nodeId of nodesToQueue) {
+    const node = nodes[nodeId]
+    if (!node?.rpcName) continue
 
-    // Only fetch results for nodes referenced in this node's input
-    const referencedNodeIds = extractReferencedNodeIds(inputMapping)
-    const nodeResults = await workflowService.getNodeResults(
+    const referencedNodeIds = extractReferencedNodeIds(node.input).filter(
+      (id) => !IGNORED_REFS.has(id)
+    )
+    const fetchedResults = await workflowService.getNodeResults(
       runId,
       referencedNodeIds
     )
 
-    const resolvedInput = resolveInputMapping(inputMapping, nodeResults)
-    const rpcName = getRpcName(node)
+    const nodeResults = { trigger: triggerInput, ...fetchedResults }
+    const resolvedInput = resolveSerializedInput(node.input, nodeResults)
 
     await queueGraphNode(
       workflowService,
       runId,
       graphName,
       nodeId,
-      rpcName,
+      node.rpcName,
       resolvedInput
     )
   }
 }
 
-/**
- * Execute a graph step with wire context.
- * Called by the step worker when executing graph nodes.
- */
 export async function executeGraphStep(
   workflowService: PikkuWorkflowService,
   rpcService: any,
   runId: string,
   stepId: string,
-  stepName: string,
+  nodeId: string,
   rpcName: string,
   data: any,
   graphName: string
 ): Promise<any> {
-  const nodeId = stepName.replace(/^node:/, '')
   const wireState: GraphWireState = {}
   const graphWire: PikkuGraphWire = {
     runId,
@@ -353,54 +442,50 @@ export async function executeGraphStep(
   }
 
   try {
-    // Execute the RPC with graph wire context
     const result = await rpcService.rpcWithWire(rpcName, data, {
       graph: graphWire,
     })
 
-    // If branch was called, store the branch key
     if (wireState.branchKey) {
       await workflowService.setBranchTaken(stepId, wireState.branchKey)
     }
 
     return result
   } catch (error) {
-    // Check if this node has an onError handler
-    const definition = getWorkflowGraph(graphName)
-    if (definition) {
-      const node = definition.graph[nodeId]
+    if (error instanceof RPCNotFoundError) {
+      await workflowService.updateRunStatus(runId, 'suspended', undefined, {
+        message: `RPC '${rpcName}' not found. Deploy the missing function and resume.`,
+        code: 'RPC_NOT_FOUND',
+      })
+      throw error
+    }
+    const meta = getWorkflowMeta(graphName)
+    if (meta?.nodes) {
+      const node = meta.nodes[nodeId]
       if (node?.onError) {
-        // Route to error handler nodes
         const errorNodes = Array.isArray(node.onError)
           ? node.onError
           : [node.onError]
         for (const errorNodeId of errorNodes) {
-          const errorNode = definition.graph[errorNodeId]
+          const errorNode = meta.nodes[errorNodeId]
           if (errorNode) {
-            const errorRpcName = getRpcName(errorNode)
-            // Queue error node with the error as input
             await queueGraphNode(
               workflowService,
               runId,
               graphName,
               errorNodeId,
-              errorRpcName,
+              errorNode.rpcName,
               { error: { message: (error as Error).message } }
             )
           }
         }
-        // Don't rethrow - error was handled by routing to error nodes
-        return
+        throw error
       }
     }
-    // No error handler - rethrow
     throw error
   }
 }
 
-/**
- * Handle node completion - re-triggers graph continuation
- */
 export async function onGraphNodeComplete(
   workflowService: PikkuWorkflowService,
   runId: string,
@@ -409,9 +494,15 @@ export async function onGraphNodeComplete(
   await continueGraph(workflowService, runId, graphName)
 }
 
-/**
- * Execute a graph node inline (without queue)
- */
+export async function runFromMeta(
+  workflowService: PikkuWorkflowService,
+  runId: string,
+  meta: WorkflowRuntimeMeta,
+  _rpcService: any
+): Promise<void> {
+  await continueGraph(workflowService, runId, meta.name, meta)
+}
+
 async function executeGraphNodeInline(
   workflowService: PikkuWorkflowService,
   rpcService: any,
@@ -419,18 +510,16 @@ async function executeGraphNodeInline(
   graphName: string,
   nodeId: string,
   input: any,
-  graph: Record<string, GraphNodeConfig>
+  nodes: Record<string, any>
 ): Promise<void> {
-  const node = graph[nodeId]
+  const node = nodes[nodeId]
   if (!node) return
 
-  const rpcName = getRpcName(node)
-  const stepName = `node:${nodeId}`
+  const rpcName = node.rpcName
 
-  // Insert step state
   const stepState = await workflowService.insertStepState(
     runId,
-    stepName,
+    nodeId,
     rpcName,
     input,
     { retries: 3 }
@@ -438,7 +527,6 @@ async function executeGraphNodeInline(
 
   await workflowService.setStepRunning(stepState.stepId)
 
-  // Execute with graph wire context
   const wireState: GraphWireState = {}
   const graphWire: PikkuGraphWire = {
     runId,
@@ -457,7 +545,6 @@ async function executeGraphNodeInline(
       graph: graphWire,
     })
 
-    // If branch was called, store the branch key
     if (wireState.branchKey) {
       await workflowService.setBranchTaken(
         stepState.stepId,
@@ -467,109 +554,125 @@ async function executeGraphNodeInline(
 
     await workflowService.setStepResult(stepState.stepId, result)
   } catch (error) {
+    if (error instanceof RPCNotFoundError) {
+      await workflowService.setStepError(stepState.stepId, error as Error)
+      await workflowService.updateRunStatus(runId, 'suspended', undefined, {
+        message: `RPC '${rpcName}' not found. Deploy the missing function and resume.`,
+        code: 'RPC_NOT_FOUND',
+      })
+      return
+    }
     await workflowService.setStepError(stepState.stepId, error as Error)
 
-    // Check if this node has an onError handler
-    const definition = getWorkflowGraph(graphName)
-    if (definition) {
-      const node = definition.graph[nodeId]
-      if (node?.onError) {
-        // Route to error handler nodes (inline)
-        const errorNodes = Array.isArray(node.onError)
-          ? node.onError
-          : [node.onError]
-        await Promise.all(
-          errorNodes.map((errorNodeId) =>
-            executeGraphNodeInline(
-              workflowService,
-              rpcService,
-              runId,
-              graphName,
-              errorNodeId,
-              { error: { message: (error as Error).message } },
-              graph
-            )
+    if (node?.onError) {
+      const errorNodes = Array.isArray(node.onError)
+        ? node.onError
+        : [node.onError]
+      await Promise.all(
+        errorNodes.map((errorNodeId: string) =>
+          executeGraphNodeInline(
+            workflowService,
+            rpcService,
+            runId,
+            graphName,
+            errorNodeId,
+            { error: { message: (error as Error).message } },
+            nodes
           )
         )
-        return
-      }
+      )
+      return
     }
-    // No error handler - rethrow
     throw error
   }
 }
 
-/**
- * Continue graph execution inline (without queue)
- * Executes nodes in parallel where possible using Promise.all
- */
 async function continueGraphInline(
   workflowService: PikkuWorkflowService,
   rpcService: any,
   runId: string,
   graphName: string,
-  graph: Record<string, GraphNodeConfig>,
-  triggerInput: any
+  nodes: Record<string, any>,
+  triggerInput: any,
+  entryNodeIds: string[]
 ): Promise<void> {
   while (true) {
-    // Get completed node IDs + branch keys (lightweight, no results)
-    const { completedNodeIds, branchKeys } =
-      await workflowService.getCompletedGraphState(runId)
+    const {
+      completedNodeIds: rawCompleted,
+      failedNodeIds: rawFailed,
+      branchKeys: rawBranch,
+    } = await workflowService.getCompletedGraphState(runId)
+    const completedNodeIds = remapStepNamesToNodeIds(
+      rawCompleted,
+      nodes,
+      graphName
+    )
+    const completedNodeIdSet = new Set(completedNodeIds)
+    const failedNodeIds = remapStepNamesToNodeIds(rawFailed, nodes, graphName)
+    const branchKeys = remapBranchKeys(rawBranch, nodes, graphName)
+
+    if (failedNodeIds.length > 0) {
+      const failedNode = failedNodeIds[0]!
+      await workflowService.updateRunStatus(runId, 'failed', undefined, {
+        message: `Graph node '${failedNode}' failed after exhausting retries`,
+        stack: '',
+        code: 'GRAPH_NODE_FAILED',
+      })
+      return
+    }
 
-    // Find candidate next nodes from completed nodes
-    const candidateNodes: string[] = []
+    const candidateNodes = new Set<string>()
 
     for (const nodeId of completedNodeIds) {
-      const node = graph[nodeId]
+      const node = nodes[nodeId]
       if (!node?.next) continue
 
       const nextNodes = resolveNextFromConfig(node.next, branchKeys[nodeId])
-      candidateNodes.push(...nextNodes)
+      for (const nextNode of nextNodes) {
+        candidateNodes.add(nextNode)
+      }
+    }
+
+    for (const entryId of entryNodeIds) {
+      candidateNodes.add(entryId)
     }
 
-    if (candidateNodes.length === 0 && completedNodeIds.length > 0) {
-      // No more nodes to run - graph complete
+    if (candidateNodes.size === 0 && completedNodeIds.length > 0) {
       await workflowService.updateRunStatus(runId, 'completed')
       return
     }
 
-    // Filter to only nodes that don't have a step yet
-    const nodesToExecute = await workflowService.getNodesWithoutSteps(
-      runId,
-      candidateNodes
-    )
+    const unstartedNodes = await workflowService.getNodesWithoutSteps(runId, [
+      ...candidateNodes,
+    ])
+
+    const nodesToExecute = unstartedNodes.filter((nodeId) => {
+      const node = nodes[nodeId]
+      return node && areDependenciesSatisfied(node, completedNodeIdSet)
+    })
 
     if (nodesToExecute.length === 0) {
-      // No more nodes to execute - if we've completed at least one node, we're done
-      // This handles branching where only some paths are taken
-      if (completedNodeIds.length > 0) {
+      if (completedNodeIds.length > 0 && unstartedNodes.length === 0) {
         await workflowService.updateRunStatus(runId, 'completed')
       }
       return
     }
 
-    // Execute all nodes in parallel
     await Promise.all(
       nodesToExecute.map(async (nodeId) => {
-        const node = graph[nodeId]
-        if (!node) return
+        const node = nodes[nodeId]
+        if (!node?.rpcName) return
 
-        // Evaluate input callback to get the mapping
-        const inputMapping = evaluateInputCallback(node)
-
-        // Only fetch results for nodes referenced in this node's input (excluding trigger)
-        const referencedNodeIds = extractReferencedNodeIds(inputMapping).filter(
-          (id) => id !== 'trigger'
+        const referencedNodeIds = extractReferencedNodeIds(node.input).filter(
+          (id) => !IGNORED_REFS.has(id)
         )
         const fetchedResults = await workflowService.getNodeResults(
           runId,
           referencedNodeIds
         )
 
-        // Merge fetched results with trigger input
         const nodeResults = { trigger: triggerInput, ...fetchedResults }
-
-        const resolvedInput = resolveInputMapping(inputMapping, nodeResults)
+        const resolvedInput = resolveSerializedInput(node.input, nodeResults)
 
         await executeGraphNodeInline(
           workflowService,
@@ -578,117 +681,136 @@ async function continueGraphInline(
           graphName,
           nodeId,
           resolvedInput,
-          graph
+          nodes
         )
       })
     )
   }
 }
 
-/**
- * Start a workflow graph execution
- * @param startNode - Optional starting node ID (from wire config). If not provided, uses wires.api from graph definition.
- */
 export async function runWorkflowGraph(
   workflowService: PikkuWorkflowService,
   graphName: string,
   triggerInput: any,
   rpcService?: any,
   inline?: boolean,
-  startNode?: string
+  startNode?: string,
+  wire?: WorkflowRunWire
 ): Promise<{ runId: string }> {
-  const definition = getWorkflowGraph(graphName)
-  if (!definition) {
+  const meta = getWorkflowMeta(graphName)
+  if (!meta?.nodes) {
     throw new Error(`Workflow graph '${graphName}' not found`)
   }
 
-  // Use startNode from caller if provided, otherwise use wires.api from graph definition
-  const apiStartNode = startNode ?? definition.wires?.api
-  const entryNodes: string[] = apiStartNode ? [apiStartNode] : []
+  const nodes = meta.nodes
+  const entryNodes: string[] = startNode
+    ? [startNode]
+    : (meta.entryNodeIds ?? [])
+  validateGraphReferences(graphName, nodes, entryNodes)
 
   if (entryNodes.length === 0) {
     throw new Error(
-      `Workflow graph '${graphName}' has no wires.api defined and no startNode was provided`
+      `Workflow graph '${graphName}': no entry nodes found in meta or startNode`
+    )
+  }
+
+  const readyEntryNodes = entryNodes.filter((nodeId) => {
+    const node = nodes[nodeId]
+    return node && areDependenciesSatisfied(node, new Set())
+  })
+
+  if (readyEntryNodes.length === 0) {
+    throw new Error(
+      `Workflow graph '${graphName}': no entry nodes have satisfied dependencies`
     )
   }
 
-  const graph = definition.graph
-  const runId = await workflowService.createRun(graphName, triggerInput, inline)
+  if (!meta.graphHash) {
+    throw new Error(`Workflow graph '${graphName}': missing graphHash in meta`)
+  }
+
+  const runId = await workflowService.createRun(
+    graphName,
+    triggerInput,
+    inline ?? false,
+    meta.graphHash,
+    wire ?? { type: 'unknown' }
+  )
 
-  // Register as inline for fast lookup
   if (inline) {
     workflowService.registerInlineRun(runId)
   }
 
-  // Create nodeResults with trigger for resolving entry node inputs
   const triggerNodeResults = { trigger: triggerInput }
 
-  try {
-    if (inline && rpcService) {
-      // Inline mode - execute entry nodes in parallel
-      await Promise.all(
-        entryNodes.map(async (nodeId) => {
-          const node = graph[nodeId]
-          if (!node) return
-
-          // Evaluate and resolve entry node input
-          const inputMapping = evaluateInputCallback(node)
-          const resolvedInput =
-            Object.keys(inputMapping).length > 0
-              ? resolveInputMapping(inputMapping, triggerNodeResults)
-              : triggerInput
-
-          await executeGraphNodeInline(
-            workflowService,
-            rpcService,
-            runId,
-            graphName,
-            nodeId,
-            resolvedInput,
-            graph
-          )
-        })
-      )
+  if (inline && rpcService) {
+    const executeInline = async () => {
+      try {
+        await Promise.all(
+          readyEntryNodes.map(async (nodeId) => {
+            const node = nodes[nodeId]
+            if (!node?.rpcName) return
 
-      // Continue executing remaining nodes inline
-      await continueGraphInline(
-        workflowService,
-        rpcService,
-        runId,
-        graphName,
-        graph,
-        triggerInput
-      )
-    } else {
-      // Queue-based mode
-      for (const nodeId of entryNodes) {
-        const node = graph[nodeId]
-        if (!node) continue
-
-        // Evaluate and resolve entry node input
-        const inputMapping = evaluateInputCallback(node)
-        const resolvedInput =
-          Object.keys(inputMapping).length > 0
-            ? resolveInputMapping(inputMapping, triggerNodeResults)
-            : triggerInput
-
-        const rpcName = getRpcName(node)
-        await queueGraphNode(
+            const resolvedInput =
+              node.input && Object.keys(node.input).length > 0
+                ? resolveSerializedInput(node.input, triggerNodeResults)
+                : triggerInput
+
+            await executeGraphNodeInline(
+              workflowService,
+              rpcService,
+              runId,
+              graphName,
+              nodeId,
+              resolvedInput,
+              nodes
+            )
+          })
+        )
+
+        await continueGraphInline(
           workflowService,
+          rpcService,
           runId,
           graphName,
-          nodeId,
-          rpcName,
-          resolvedInput
+          nodes,
+          triggerInput,
+          entryNodes
         )
+      } catch (error) {
+        await workflowService.updateRunStatus(runId, 'failed', undefined, {
+          message: (error as Error).message,
+          stack: (error as Error).stack || '',
+          code: 'GRAPH_NODE_FAILED',
+        })
+      } finally {
+        workflowService.unregisterInlineRun(runId)
       }
     }
-
-    return { runId }
-  } finally {
-    // Clean up inline tracking
+    await executeInline()
+  } else {
+    for (const nodeId of readyEntryNodes) {
+      const node = nodes[nodeId]
+      if (!node?.rpcName) continue
+
+      const resolvedInput =
+        node.input && Object.keys(node.input).length > 0
+          ? resolveSerializedInput(node.input, triggerNodeResults)
+          : triggerInput
+
+      await queueGraphNode(
+        workflowService,
+        runId,
+        graphName,
+        nodeId,
+        node.rpcName,
+        resolvedInput
+      )
+    }
     if (inline) {
       workflowService.unregisterInlineRun(runId)
     }
   }
+
+  return { runId }
 }