@ema.co/mcp-toolkit 2026.1.27 → 2026.1.28-2

package/dist/sdk/structural-rules.js

@@ -129,6 +129,38 @@ export const STRUCTURAL_INVARIANTS = [
         fix: "Use entity_extraction to extract email_address, then connect to to_email",
         severity: "critical",
     },
+    {
+        id: "no_redundant_classifiers",
+        name: "No Redundant Classifiers",
+        rule: "Multiple categorizers analyzing the same input source cause overlapping/conflicting routing decisions.",
+        violation: "Two chat_categorizer nodes both receive trigger.chat_conversation",
+        fix: "Consolidate into single classifier, or chain sequentially with clear precedence (first categorizer → second categorizer)",
+        severity: "warning",
+    },
+    {
+        id: "all_inputs_exist",
+        name: "All Input Sources Must Exist",
+        rule: "When a node expects input from another node, that source node must exist in the workflow.",
+        violation: "Node 'respond' expects data from 'search_old' but that node doesn't exist",
+        fix: "Add the missing source node or update the input binding to reference an existing node",
+        severity: "critical",
+    },
+    {
+        id: "gated_dependencies_match",
+        name: "Gated Dependencies Need Matching Gates",
+        rule: "If a node depends on a gated source (has runIf), the dependent node should also be gated with a matching condition, or the dependency may not provide data.",
+        violation: "Node 'respond' depends on gated 'search_billing' (only runs when category='billing') but has no gate itself",
+        fix: "Add matching runIf condition to the dependent node, or restructure so dependency is always available",
+        severity: "warning",
+    },
+    {
+        id: "no_orphaned_outputs",
+        name: "No Orphaned Outputs",
+        rule: "Node outputs that aren't consumed by any downstream node or mapped to WORKFLOW_OUTPUT are wasted computation.",
+        violation: "Node 'search_backup' output is never used",
+        fix: "Connect the output to a downstream node, map to WORKFLOW_OUTPUT, or remove the node if unused",
+        severity: "warning",
+    },
 ];
 export const EXECUTION_RULES = [
     {
@@ -199,6 +231,24 @@ export const COMMON_STRUCTURAL_MISTAKES = [
         cause: "Nodes created but never connected, or connections removed without removing node",
         fix: "Either connect the node or remove it. Use analyzeWorkflow to detect orphans.",
     },
+    {
+        id: "redundant_classifiers",
+        symptom: "Workflow has multiple categorizers that analyze the same input",
+        cause: "Two or more chat_categorizer nodes both receive the same conversation input",
+        fix: "Consolidate into single classifier, or chain sequentially (first categorizer → second categorizer with different categories)",
+    },
+    {
+        id: "missing_input_source",
+        symptom: "Node fails with 'missing input' error",
+        cause: "Input binding references a node that doesn't exist in the workflow",
+        fix: "Add the missing source node or update the input binding to reference an existing node",
+    },
+    {
+        id: "gated_dependency_mismatch",
+        symptom: "Node doesn't receive expected data even when source node exists",
+        cause: "Source node is gated (has runIf) but dependent node has no matching gate",
+        fix: "Add matching runIf condition to dependent node, or restructure so dependency is always available",
+    },
     {
         id: "search_no_results",
         symptom: "Response says 'I don't have information' even when KB has data",
@@ -276,6 +326,448 @@ After generating/modifying a workflow, verify:
 - [ ] Email recipients come from entity_extraction
 - [ ] No circular dependencies
 `;
+export const GRAPH_ANALYSIS_RULES = [
+    // ═══════════════════════════════════════════════════════════════════════════
+    // Loop Detection
+    // ═══════════════════════════════════════════════════════════════════════════
+    {
+        id: "circular_loop",
+        name: "Circular Loop Detection",
+        definition: "A cycle in the directed graph of nodes (A → B → ... → A). Circular loops cause infinite execution.",
+        symptoms: [
+            "Presence of directed cycles in node connections",
+            "Edges that lead back to nodes earlier in the path without a runIf/condition or state-change guard",
+            "A path that repeatedly produces the same trigger event",
+        ],
+        examplePattern: "adjacency: trigger → A, A → B, B → A (cycle). Or node A has an output that is connected to trigger.user_query or trigger.chat_conversation without a gating condition.",
+        concreteExample: {
+            snippet: `{
+  "trigger": { "action_name": "chat_trigger", "incoming_edges": [] },
+  "A": {
+    "action_name": "action_A",
+    "incoming_edges": [
+      { "source_node_id": "trigger", "source_output": "user_query", "target_input": "query" },
+      { "source_node_id": "B", "source_output": "feedback", "target_input": "query" }
+    ]
+  },
+  "B": {
+    "action_name": "action_B",
+    "incoming_edges": [
+      { "source_node_id": "A", "source_output": "result", "target_input": "input" }
+    ]
+  }
+}`,
+            whyThisMatches: "A → B → A forms a directed cycle. Also re-entry if A/B feed fields that the trigger listens to (e.g., sending to trigger.user_query) — flag as high risk when no runIf/state-change guard.",
+            quickRemediation: "Break the cycle with a runIf guard, state transition, or remove re-entry edge.",
+        },
+        detectionAlgorithm: "Build adjacency list from incoming_edges: for each edge (source_node_id → target_node_id). Run depth-first search (DFS) or Tarjan's SCC to find cycles. If any SCC has size > 1 or a self-loop, report a cycle.",
+        detectionSteps: [
+            "Create directed graph G from node connections",
+            "Run cycle detection (DFS or Tarjan's SCC algorithm)",
+            "List cycles with node sequences",
+            "For each cycle, look for nodes in the cycle with gating conditions (runIf, trigger_when)",
+            "If cycle has no gating conditions, mark as 'potential infinite loop' (high risk)",
+        ],
+        remediation: "Add explicit runIf/trigger_when conditions, counters, or idempotency checks. Break the cycle by adding a terminal node or require user confirmation before re-trigger.",
+        severity: "critical",
+        thresholds: [
+            {
+                description: "Cycle severity",
+                value: "Cycles with no gating → high; cycles with explicit counters or state updates → medium/low",
+            },
+        ],
+    },
+    // ═══════════════════════════════════════════════════════════════════════════
+    // Multiple Responder Detection
+    // ═══════════════════════════════════════════════════════════════════════════
+    {
+        id: "multiple_responders",
+        name: "Multiple Responder Detection",
+        definition: "Two or more responder nodes (call_llm, external_action_caller, response sinks) can be activated for the same incoming trigger, producing duplicated user-visible outputs.",
+        symptoms: [
+            "Multiple nodes with the same trigger_when category or overlapping conditions",
+            "Multiple call_llm or external_action_caller nodes subscribing to the same category or to an ungated default",
+            "Same node type present in parallel paths that both end up connected to the Workflow Output sink",
+        ],
+        examplePattern: "chat_categorizer → category::Cancel Booking → external_action_caller A; chat_categorizer → category::Cancel Booking → external_action_caller B; Both A and B outputs connect to WORKFLOW_OUTPUT.",
+        concreteExample: {
+            snippet: `{
+  "trigger": { "action_name": "chat_trigger", "incoming_edges": [] },
+  "categorizer": {
+    "action_name": "chat_categorizer",
+    "incoming_edges": [
+      { "source_node_id": "trigger", "source_output": "chat_conversation", "target_input": "conversation" }
+    ]
+  },
+  "responder_1": {
+    "action_name": "call_llm",
+    "incoming_edges": [
+      { "source_node_id": "trigger", "source_output": "user_query", "target_input": "query" },
+      { "source_node_id": "categorizer", "source_output": "category::Billing", "target_input": "trigger_when" }
+    ]
+  },
+  "responder_2": {
+    "action_name": "call_llm",
+    "incoming_edges": [
+      { "source_node_id": "trigger", "source_output": "user_query", "target_input": "query" },
+      { "source_node_id": "categorizer", "source_output": "category::Billing", "target_input": "trigger_when" }
+    ]
+  }
+}`,
+            whyThisMatches: "Two responders subscribe to the same category::Billing → both can fire.",
+            quickRemediation: "Consolidate responders or add mutually exclusive runIf conditions or priorities.",
+        },
+        detectionAlgorithm: "Group responder nodes (call_llm, external_action_caller, any node that produces final responses). For each responder, extract its trigger_when or runIf conditions; compute condition overlap: exact-match overlap (identical categories/conditions) or semantic overlap (overlapping category sets or both are ungated). If two responders have overlapping triggers and both feed the final sink (or both send to users), flag as multiple responders.",
+        detectionSteps: [
+            "Find all nodes with action_name in {call_llm, external_action_caller, respond_with_sources}",
+            "For each responder, extract trigger_when or runIf conditions",
+            "For each pair of responders, compute condition overlap",
+            "Check if both responders feed WORKFLOW_OUTPUT or response sink",
+            "If overlap AND both feed response sink, report as duplicate responders",
+        ],
+        remediation: "Consolidate responders behind a single handler, add disambiguating conditions, or add a categorizer route that ensures only one responder is triggered.",
+        severity: "critical",
+        thresholds: [
+            {
+                description: "Condition overlap",
+                value: "Exact matches → high risk; semantic overlap (subset patterns) → medium risk",
+            },
+        ],
+    },
+    // ═══════════════════════════════════════════════════════════════════════════
+    // Ungated Catch-All Detection
+    // ═══════════════════════════════════════════════════════════════════════════
+    {
+        id: "ungated_catch_all",
+        name: "Ungated Catch-All Detection",
+        definition: "A node that accepts the main trigger input (user_query or conversation) without a gating condition (no trigger_when, runIf or categorizer constraint), effectively acting as a default/catch-all that runs for all inputs.",
+        symptoms: [
+            "Nodes that have inputs from trigger.user_query or trigger.chat_conversation but do not have any trigger_when/runIf or category gating edges",
+            "A categorizer that has a 'default' category wired to a node that is intended to be fallback but has no specificity, causing it to capture everything",
+        ],
+        examplePattern: "call_llm node: incoming edge from trigger.user_query and no trigger_when edge from categorizer → acts as catch-all.",
+        concreteExample: {
+            snippet: `{
+  "trigger": { "action_name": "chat_trigger", "incoming_edges": [] },
+  "cat": {
+    "action_name": "chat_categorizer",
+    "incoming_edges": [
+      { "source_node_id": "trigger", "source_output": "chat_conversation", "target_input": "conversation" }
+    ]
+  },
+  "catch_responder": {
+    "action_name": "call_llm",
+    "incoming_edges": [
+      { "source_node_id": "trigger", "source_output": "user_query", "target_input": "query" },
+      { "source_node_id": "cat", "source_output": "category::CatchAll", "target_input": "trigger_when" }
+    ]
+  }
+}`,
+            whyThisMatches: "CatchAll connected directly to responder; if no other handlers have priority, every message may be consumed here.",
+            quickRemediation: "Add explicit priorities, runIf conditions, or refine categorizer so specific categories are routed first.",
+        },
+        detectionAlgorithm: "For each node that consumes trigger.* inputs directly, check presence of a trigger_when or runIf incoming edge from a categorizer or another gating node. If absent, flag as ungated catch-all. Also detect categorizer categories labeled 'default' or 'catch-all' that are broad (e.g., no examples or a category with pattern '*').",
+        detectionSteps: [
+            "For each node that consumes trigger.user_query or trigger.chat_conversation",
+            "Check if node has trigger_when or runIf incoming edge from categorizer",
+            "If absent, flag as ungated catch-all",
+            "Check categorizer categories for 'default' or 'catch-all' with broad patterns",
+        ],
+        remediation: "Add explicit gating conditions or make it an explicit fallback with lower priority and documentation; use categorizer default only if intended and ensure it's mutually exclusive with other handlers.",
+        severity: "warning",
+    },
+    // ═══════════════════════════════════════════════════════════════════════════
+    // Redundant Classifier Detection
+    // ═══════════════════════════════════════════════════════════════════════════
+    {
+        id: "redundant_classifier",
+        name: "Redundant Classifier Detection",
+        definition: "Multiple categorizer/classifier components that overlap heavily in categories or are functionally duplicated, producing extra routing complexity and possible inconsistencies.",
+        symptoms: [
+            "Multiple chat_categorizer nodes with same or overlapping category names",
+            "Categories with identical examples/descriptions or categories that are strict subsets of others and are both used for routing",
+            "Multiple categorizer outputs wired to the same downstream nodes causing duplicate triggers",
+        ],
+        examplePattern: "chat_categorizer A categories: {Cancel Booking, Flight Status}; chat_categorizer B categories: {Cancel Booking, Change Booking}; Both wired to the same downstream nodes for Cancel Booking (duplicate classification).",
+        concreteExample: {
+            snippet: `{
+  "trigger": { "action_name": "chat_trigger", "incoming_edges": [] },
+  "classifier_1": {
+    "action_name": "chat_categorizer",
+    "incoming_edges": [
+      { "source_node_id": "trigger", "source_output": "chat_conversation", "target_input": "conversation" }
+    ]
+  },
+  "classifier_2": {
+    "action_name": "chat_categorizer",
+    "incoming_edges": [
+      { "source_node_id": "classifier_1", "source_output": "conversation", "target_input": "conversation" }
+    ]
+  },
+  "responder": {
+    "action_name": "call_llm",
+    "incoming_edges": [
+      { "source_node_id": "trigger", "source_output": "user_query", "target_input": "query" },
+      { "source_node_id": "classifier_2", "source_output": "category::Support", "target_input": "trigger_when" }
+    ]
+  }
+}`,
+            whyThisMatches: "Two classifiers in series often replicate work or re-label identically.",
+            quickRemediation: "Merge classifiers, or ensure each has distinct responsibility (coarse vs. fine classification) with documented downstream expectations.",
+        },
+        detectionAlgorithm: "List all categorizer nodes and their categories (name, examples). Compute string similarity and example overlap between categories across categorizers. Find categories that share > X% of example texts or identical names — flag as potential redundancy. Detect multiple categorizer outputs feeding the same node for the same category.",
+        detectionSteps: [
+            "List all categorizer nodes and their categories (name, examples)",
+            "Compute string similarity and example overlap between categories across categorizers",
+            "Find categories that share > 60-70% of example texts or identical names",
+            "Detect multiple categorizer outputs feeding the same node for the same category",
+            "Flag as potential redundancy",
+        ],
+        remediation: "Merge classifiers or consolidate category definitions. Make classifier responsibilities orthogonal (e.g., one for intents, one for sentiment).",
+        severity: "warning",
+        thresholds: [
+            {
+                description: "Category similarity",
+                value: "Flag if > 60-70% example overlap or identical names",
+            },
+        ],
+    },
+    // ═══════════════════════════════════════════════════════════════════════════
+    // Data Flow Analysis
+    // ═══════════════════════════════════════════════════════════════════════════
+    {
+        id: "data_flow_analysis",
+        name: "Data Flow Analysis",
+        definition: "Ensuring required inputs are provided to nodes, outputs are consumed, no type mismatches, and the overall flow is consistent.",
+        symptoms: [
+            "Node inputs that have no incoming_edges (missing required data)",
+            "Edges that reference non-existent source outputs or target inputs (typos)",
+            "Outputs that are never consumed (dead outputs) or consumed by nodes that don't exist",
+            "Type/semantic mismatches (e.g., passing a structured tool_execution_result into an LLM prompt expecting plain text)",
+        ],
+        examplePattern: "Edge references source_output that does not exist in source node outputs → report. Node input field has no incoming edge → report missing input.",
+        concreteExample: {
+            snippet: `{
+  "trigger": { "action_name": "chat_trigger", "incoming_edges": [] },
+  "finder": {
+    "action_name": "find_booking",
+    "incoming_edges": [
+      { "source_node_id": "trigger", "source_output": "user_query", "target_input": "query" }
+    ],
+    "outputs": ["booking_id"]
+  },
+  "responder": {
+    "action_name": "call_llm",
+    "incoming_edges": [
+      { "source_node_id": "finder", "source_output": "booking_id", "target_input": "booking_ref" }
+    ]
+  }
+}`,
+            whyThisMatches: "responder expects booking_ref but finder outputs booking_id — mismatch leads to empty data at runtime.",
+            quickRemediation: "Align field names or add a transformer node to map booking_id -> booking_ref. Report outputs that are never consumed or inputs that have no upstream provider.",
+        },
+        detectionAlgorithm: "For each node, verify all required input fields are satisfied by incoming_edges. Validate source_output names exist on the source node (check the node spec for outputs). Check that at least one sink consumes the node's significant outputs; if none, mark as unused output. Identify type mismatches by checking node input/output semantic names (e.g., tool_execution_result vs. response_with_sources). Trace data lineage: for each final output (WorkflowOutput sink), walk backwards to see which nodes contributed which fields.",
+        detectionSteps: [
+            "For node N: for input field f in N.required_inputs: if no incoming edge maps to f, report missing input",
+            "For edge e: ensure source_node has output named source_output; ensure target_node has input named target_input",
+            "Check that node outputs are consumed by at least one downstream node or WORKFLOW_OUTPUT",
+            "Validate type compatibility: check semantic names match expected types",
+            "Trace data lineage from WORKFLOW_OUTPUT backwards to verify all paths are valid",
+        ],
+        remediation: "Add missing edges, correct typos, or refactor node interfaces. Introduce intermediate transformation nodes where necessary.",
+        severity: "critical",
+    },
+    // ═══════════════════════════════════════════════════════════════════════════
+    // RunIf Condition Validation
+    // ═══════════════════════════════════════════════════════════════════════════
+    {
+        id: "runif_validation",
+        name: "RunIf Condition Validation",
+        definition: "Ensuring runIf/trigger_when conditions are syntactically valid, reference existing inputs/fields, and are logically satisfiable.",
+        symptoms: [
+            "Conditions referencing non-existent variables (typos), impossible conditions (x > 5 and x < 3), or always-true/always-false conditions",
+            "Use of unsupported operators or invalid value types",
+            "Logical contradictions between conditions on parallel nodes that make some nodes unreachable",
+        ],
+        examplePattern: "Node has runIf: 'user.locale == \"en-US\" && user.locale == \"fr-FR\"' → unreachable. Node runIf references 'trigger.user_input_text' but upstream node outputs 'user_query' instead → invalid reference.",
+        concreteExample: {
+            snippet: `{
+  "trigger": { "action_name": "chat_trigger", "incoming_edges": [] },
+  "proc": {
+    "action_name": "process_booking",
+    "incoming_edges": [
+      { "source_node_id": "trigger", "source_output": "user_query", "target_input": "query" }
+    ],
+    "runIf": "booking.status == 'confirmed' && user.is_admin"
+  }
+}`,
+            whyThisMatches: "if upstream nodes never produce booking or user objects, the expression references undefined variables — should be validated.",
+            quickRemediation: "Validate runIf identifiers against upstream outputs; add safe existence checks or use documented expression language. Flag conditions referencing unknown fields as errors.",
+        },
+        detectionAlgorithm: "Parse each runIf/trigger_when expression. Validate identifiers exist in the upstream data model (available outputs). Evaluate static satisfiability where possible: check for contradictions (e.g., x == 'A' and x == 'B'). Check boolean expression correctness (operators, parentheses). Flag conditions that are always true or always false given constant inputs.",
+        detectionSteps: [
+            "Parse each runIf/trigger_when expression",
+            "Validate identifiers exist in the upstream data model (available outputs)",
+            "Evaluate static satisfiability: check for contradictions (e.g., x == 'A' and x == 'B')",
+            "Check boolean expression correctness (operators, parentheses)",
+            "Flag conditions that are always true or always false given constant inputs",
+        ],
+        remediation: "Fix typos, ensure conditions reference correct fields, simplify conditions, or add descriptive comments/examples.",
+        severity: "critical",
+    },
+    // ═══════════════════════════════════════════════════════════════════════════
+    // Parallel Execution Opportunities
+    // ═══════════════════════════════════════════════════════════════════════════
+    {
+        id: "parallel_execution_opportunities",
+        name: "Parallel Execution Opportunities",
+        definition: "Independent nodes or subgraphs that can be executed concurrently (no data dependencies between them).",
+        symptoms: [
+            "Multiple responder or action nodes consuming only trigger data and not depending on each other's outputs",
+            "Subgraphs that start from the trigger and end in independent sinks with no cross edges",
+        ],
+        examplePattern: "Nodes reachable from trigger that have no inter-node edges → mark as parallelizable.",
+        concreteExample: {
+            snippet: `{
+  "trigger": { "action_name": "chat_trigger", "incoming_edges": [] },
+  "A": {
+    "action_name": "enrich_profile",
+    "incoming_edges": [
+      { "source_node_id": "trigger", "source_output": "user_query", "target_input": "query" }
+    ]
+  },
+  "B": {
+    "action_name": "fetch_metrics",
+    "incoming_edges": [
+      { "source_node_id": "trigger", "source_output": "user_query", "target_input": "query" }
+    ]
+  },
+  "merge": {
+    "action_name": "aggregate_results",
+    "incoming_edges": [
+      { "source_node_id": "A", "source_output": "profile", "target_input": "profile" },
+      { "source_node_id": "B", "source_output": "metrics", "target_input": "metrics" }
+    ]
+  }
+}`,
+            whyThisMatches: "A and B do not depend on each other and can be scheduled in parallel; only merge needs both results.",
+            quickRemediation: "Mark independent branches as parallelizable or set executor to run independent nodes concurrently.",
+        },
+        detectionAlgorithm: "Build dependency DAG (edges represent data dependency). Identify nodes or groups with no interconnections (no path between them); these are candidates for parallel execution. Use topological sort to find levels of nodes that can be run concurrently; nodes at same level with no edges between them are parallelizable.",
+        detectionSteps: [
+            "Build dependency DAG (edges represent data dependency)",
+            "Topologically sort graph",
+            "For each layer (nodes with same distance from sources), mark nodes that don't share dependencies as parallel",
+            "Identify nodes or groups with no interconnections (no path between them)",
+        ],
+        remediation: "Recommend executing parallelizable actions concurrently to reduce latency. Ensure side-effects on shared resources are synchronized.",
+        severity: "info",
+    },
+    // ═══════════════════════════════════════════════════════════════════════════
+    // Dead Code Path Detection
+    // ═══════════════════════════════════════════════════════════════════════════
+    {
+        id: "dead_code_path",
+        name: "Dead Code Path Detection",
+        definition: "Nodes or edges that can never be reached/run during any valid execution (unreachable) or nodes whose outputs are never used.",
+        symptoms: [
+            "Nodes with no incoming edges from the trigger (except trigger node itself)",
+            "Nodes whose runIf/trigger_when are contradictory or shadowed by higher-priority rules",
+            "Outputs that are never connected to a sink",
+        ],
+        examplePattern: "Node X exists, but no incoming edges. Or Node Y has a runIf that is false for all upstream values.",
+        concreteExample: {
+            snippet: `{
+  "trigger": { "action_name": "chat_trigger", "incoming_edges": [] },
+  "classifier": {
+    "action_name": "chat_categorizer",
+    "incoming_edges": [
+      { "source_node_id": "trigger", "source_output": "chat_conversation", "target_input": "conversation" }
+    ],
+    "outputs": ["category::A", "category::B", "category::Unused"]
+  },
+  "responder_A": {
+    "action_name": "call_llm",
+    "incoming_edges": [
+      { "source_node_id": "classifier", "source_output": "category::A", "target_input": "trigger_when" }
+    ]
+  },
+  "orphan": {
+    "action_name": "orphan_action",
+    "incoming_edges": [
+      { "source_node_id": "nonexistent", "source_output": "x", "target_input": "input" }
+    ]
+  }
+}`,
+            whyThisMatches: "category::Unused is never wired to any node; orphan_action has no valid upstream → unreachable. Also check for runIf conditions that are constant-false.",
+            quickRemediation: "Remove or rewire unused categories/nodes; fix upstream wiring; simplify or document intentional dead paths.",
+        },
+        detectionAlgorithm: "Reachability analysis: starting from the trigger node(s), do BFS/DFS and mark visited nodes. Any node not visited = unreachable. For conditional nodes, conservatively evaluate whether their condition can be true given upstream outputs; if impossible, mark unreachable. For outputs, check whether there exists a path from node output to the WorkflowOutput sink; if none, mark as unused.",
+        detectionSteps: [
+            "Starting from trigger node(s), do BFS/DFS and mark visited nodes",
+            "Any node not visited = unreachable",
+            "For conditional nodes, evaluate whether their condition can be true given upstream outputs",
+            "If condition is impossible, mark as unreachable",
+            "For outputs, check if path exists from node output to WORKFLOW_OUTPUT sink",
+            "If no path, mark as unused output",
+        ],
+        remediation: "Remove or repurpose unreachable nodes. Fix conditions or routing so intended logic is reachable.",
+        severity: "warning",
+    },
+];
+/**
+ * Generic LLM instruction for applying all graph analysis rules.
+ * Use this as a prompt template for LLM-based workflow validation.
+ */
+export const GRAPH_ANALYSIS_LLM_INSTRUCTION = `
+Parse the workflow graph JSON. Build adjacency lists and node metadata (action_name, inputs, outputs, trigger_when/runIf/conditions). Run:
+
+1. **Cycle detection** (Tarjan/DFS) - Find circular dependencies
+2. **Responder-grouping and overlap detection** - Find duplicate responses
+3. **Ungated-node scan** - Nodes directly consuming trigger.* with no trigger_when/runIf
+4. **Classifier similarity comparison** - Redundant categorizers
+5. **Dataflow validation** - Missing inputs, invalid edge references, type mismatches
+6. **runIf parsing and satisfiability checks** - Invalid conditions
+7. **Dependency DAG/topological sort for parallelism** - Optimization opportunities
+8. **Reachability analysis** - Find dead code paths
+
+For each finding produce:
+- **type**: (Loop / Multiple responders / Ungated catch-all / Redundant classifier / Data flow / RunIf validation / Parallel opportunity / Dead code)
+- **nodes_involved**: [node ids]
+- **evidence**: short quote of graph edges/conditions
+- **severity**: high/medium/low
+- **suggested_fix**: one-sentence remediation
+
+Optionally include a small graph snippet showing the offending edges.
+`;
+/**
+ * Concrete JSON-matching patterns for quick detection.
+ * These are patterns an LLM can look for in workflow JSON structures.
+ */
+export const GRAPH_ANALYSIS_PATTERNS = {
+    loop: "Find path sequence ['nodeA', 'nodeB', 'nodeA']",
+    multiple_responders: "List nodes where action_name in {call_llm, external_action_caller} and trigger_when == same_category → report duplicates",
+    ungated_catch_all: "Node has incoming from trigger.user_query AND no incoming trigger_when/runIf → report",
+    redundant_classifier: "Two chat_categorizer nodes with category names intersecting or identical examples → report",
+    data_flow: "Edge references source_output that does not exist in source node outputs → report",
+    runif: "Condition contains identifier not present in any upstream outputs → report",
+    parallelism: "Nodes reachable from trigger that have no inter-node edges → mark as parallelizable",
+    dead_code: "Node.id not in traversal from trigger → unreachable",
+};
+/**
+ * Concise algorithmic checks summary for LLM validation.
+ * These are short, actionable checks an LLM can run on workflow graphs.
+ */
+export const GRAPH_ANALYSIS_ALGORITHMIC_CHECKS = {
+    loop_detection: "Build adjacency graph from incoming_edges; run DFS/Tarjan to detect cycles (loop detection).",
+    multiple_responder_detection: "For each responder-type node, collect its trigger_when / category inputs and flag if multiple responders share the same condition (multiple responder detection).",
+    ungated_catch_all_detection: "Detect any 'catch-all' category outputs (names like CatchAll, Other, default, '*') wired without exclusive guards.",
+    redundant_classifier_detection: "Find classifier nodes in series or classifiers whose outputs are re-classified by another classifier without transformation (redundant classifier).",
+    data_flow_analysis: "Compare source_output names vs expected target_input names; list outputs with zero consumers and inputs with zero providers (data flow issues).",
+    runif_validation: "Parse runIf expressions: check referenced identifiers against upstream outputs; flag missing identifiers or unsupported syntax (runIf validation).",
+    parallel_execution_opportunities: "Identify independent subgraphs (no shared upstream dependencies) and suggest parallel execution points (parallel opportunities).",
+    dead_code_path_detection: "Find nodes with no path from trigger or nodes that never reach WORKFLOW_OUTPUT or whose runIf is constant false (dead code paths).",
+};
 // ─────────────────────────────────────────────────────────────────────────────
 // Exports
 // ─────────────────────────────────────────────────────────────────────────────
@@ -288,3 +780,9 @@ export function getInvariantById(id) {
 export function getCriticalInvariants() {
     return STRUCTURAL_INVARIANTS.filter(i => i.severity === "critical");
 }
+export function getGraphAnalysisRuleById(id) {
+    return GRAPH_ANALYSIS_RULES.find(r => r.id === id);
+}
+export function getAllGraphAnalysisRules() {
+    return GRAPH_ANALYSIS_RULES;
+}

package/dist/sdk/workflow-generator.js

@@ -9,6 +9,7 @@
  * 2. Construct nodes based on user requirements
  * 3. Pass to compileWorkflow() to generate deployment-ready JSON
  */
+import { PROJECT_TYPES } from "./knowledge.js";
 /**
  * FALLBACK VALUES - Used only when ActionRegistry is not available.
  * These are based on API data as of 2026-01-16.
@@ -329,7 +330,7 @@ function buildInputBinding(binding) {
     }
 }
 function buildProtoConfig(spec) {
-    const projectType = spec.personaType === "voice" ? 5 : spec.personaType === "chat" ? 4 : 2;
+    const projectType = PROJECT_TYPES[spec.personaType] ?? PROJECT_TYPES.dashboard;
     // Widget format expected by Ema API:
     // { name: "widgetName", type: <type_id>, widgetName: { ...config... } }
     // The config is stored under a key matching the widget's name