@ema.co/mcp-toolkit 2026.2.5 → 2026.2.13

package/dist/mcp/domain/workflow-graph-transforms.js

@@ -0,0 +1,808 @@
+/**
+ * Workflow Graph Transforms
+ *
+ * Registry of pure transform functions that operate on workflow_def JSON.
+ * Each transform: (workflowDef, graph) -> TransformResult | null
+ *
+ * - Auto-fix transforms modify the workflow to fix issues
+ * - Advisory transforms report issues without fixing
+ * - NEVER mutates the input workflowDef
+ * - Returns null when not applicable
+ */
+import { getReachableNodes, getNodesByType, getOutputConsumers, } from "./workflow-graph.js";
+// ─────────────────────────────────────────────────────────────────────────────
+// Helpers
+// ─────────────────────────────────────────────────────────────────────────────
+function deepClone(obj) {
+    return JSON.parse(JSON.stringify(obj));
+}
+function emptyResult(workflowDef) {
+    return {
+        applied: true,
+        workflowDef,
+        description: "",
+        nodesRemoved: [],
+        nodesAdded: [],
+        nodesModified: [],
+        edgesRewired: [],
+    };
+}
+/** Extract the action type name from a raw action object. */
+function extractActionType(action) {
+    const actionDef = action.action;
+    const actionName = actionDef?.name;
+    if (typeof actionName === "string")
+        return actionName;
+    if (actionName && typeof actionName === "object") {
+        return actionName.name ?? "unknown";
+    }
+    return "unknown";
+}
+/** Build a signature for a node to detect identical nodes. */
+function nodeSignature(action) {
+    const actionType = extractActionType(action);
+    const actionDef = action.action;
+    const version = actionDef?.version ?? "";
+    const inputs = action.inputs;
+    // Serialize input wiring deterministically (sorted keys, only actionOutput refs)
+    const inputWiring = {};
+    if (inputs) {
+        const sortedKeys = Object.keys(inputs).sort();
+        for (const key of sortedKeys) {
+            const val = inputs[key];
+            if (val?.actionOutput) {
+                inputWiring[key] = val.actionOutput;
+            }
+            else if (val?.widgetConfig) {
+                inputWiring[key] = { widget: val.widgetConfig };
+            }
+            else if (val?.inline) {
+                inputWiring[key] = { inline: val.inline };
+            }
+            else if (val?.multiBinding) {
+                inputWiring[key] = { multi: val.multiBinding };
+            }
+        }
+    }
+    return JSON.stringify({ actionType, version, inputWiring });
+}
+/** Check if an action has side effects based on its type. */
+function hasSideEffects(action) {
+    const actionType = extractActionType(action);
+    const SIDE_EFFECT_FREE = new Set([
+        "search", "call_llm", "entity_extraction", "respond_with_sources",
+        "respond_for_external_actions", "conversation_to_search_query",
+        "combine_search_results", "text_categorizer", "chat_categorizer",
+        "response_validator", "fixed_response", "live_web_search",
+        "ai_web_search", "json_mapper", "custom_agent",
+    ]);
+    const TRIGGER_TYPES = new Set(["chat_trigger", "voice_trigger", "document_trigger"]);
+    if (TRIGGER_TYPES.has(actionType))
+        return false;
+    if (SIDE_EFFECT_FREE.has(actionType))
+        return false;
+    return true;
+}
+/** Check if an action is a trigger node. */
+function isTriggerAction(action) {
+    const actionType = extractActionType(action);
+    return actionType === "chat_trigger" || actionType === "voice_trigger" || actionType === "document_trigger";
+}
+/** Get all node names from actions array. */
+function getActionNames(actions) {
+    return new Set(actions.map((a) => a.name).filter(Boolean));
+}
+/**
+ * Rewire all references from oldName to newName in the actions array.
+ * This updates actionOutput bindings, multiBinding refs, and runIf refs.
+ */
+function rewireReferences(actions, oldName, newName) {
+    for (const action of actions) {
+        const inputs = action.inputs;
+        if (inputs) {
+            for (const val of Object.values(inputs)) {
+                const binding = val;
+                if (binding?.actionOutput) {
+                    const ao = binding.actionOutput;
+                    if (ao.actionName === oldName) {
+                        ao.actionName = newName;
+                    }
+                }
+                if (binding?.multiBinding) {
+                    const mb = binding.multiBinding;
+                    const elements = mb.elements ?? [];
+                    for (const elem of elements) {
+                        if (elem.namedBinding) {
+                            const nb = elem.namedBinding;
+                            const value = nb.value;
+                            if (value?.actionOutput) {
+                                const ao = value.actionOutput;
+                                if (ao.actionName === oldName) {
+                                    ao.actionName = newName;
+                                }
+                            }
+                        }
+                        else if (elem.actionOutput) {
+                            const ao = elem.actionOutput;
+                            if (ao.actionName === oldName) {
+                                ao.actionName = newName;
+                            }
+                        }
+                    }
+                }
+            }
+        }
+        // Rewire runIf
+        const runIf = action.runIf;
+        if (runIf) {
+            const lhs = runIf.lhs;
+            if (lhs?.actionOutput) {
+                const ao = lhs.actionOutput;
+                if (ao.actionName === oldName) {
+                    ao.actionName = newName;
+                }
+            }
+        }
+    }
+}
+/**
+ * Rewire result mappings from oldName to newName.
+ */
+function rewireResults(results, oldName, newName) {
+    for (const resultDef of Object.values(results)) {
+        if (resultDef && resultDef.actionName === oldName) {
+            resultDef.actionName = newName;
+        }
+    }
+}
+// ─────────────────────────────────────────────────────────────────────────────
+// Auto-fix Transforms
+// ─────────────────────────────────────────────────────────────────────────────
+/**
+ * 1. Remove dead nodes unreachable from trigger.
+ */
+const removeDeadNodes = {
+    id: "remove-dead-nodes",
+    name: "Remove Dead Nodes",
+    description: "Remove nodes unreachable from the trigger via BFS",
+    apply(workflowDef, graph) {
+        try {
+            if (!graph.trigger || graph.nodes.size === 0)
+                return null;
+            const reachable = getReachableNodes(graph);
+            const unreachable = [];
+            for (const nodeId of graph.nodes.keys()) {
+                if (!reachable.has(nodeId)) {
+                    unreachable.push(nodeId);
+                }
+            }
+            if (unreachable.length === 0)
+                return null;
+            const cloned = deepClone(workflowDef);
+            const actions = cloned.actions;
+            const results = (cloned.results ?? {});
+            const removedNodes = [];
+            // Attempt to wire intentional nodes, remove truly orphaned ones
+            for (const nodeId of unreachable) {
+                const node = graph.nodes.get(nodeId);
+                const hasDisplayName = node.displayName && node.displayName !== nodeId;
+                const isReferencedInResults = Object.values(results).some((r) => r.actionName === nodeId);
+                const hasActionOutputInputs = [...node.inputs.values()].some((ref) => ref.type === "action_output");
+                if (hasDisplayName || isReferencedInResults || hasActionOutputInputs) {
+                    // Intentional node: skip removal (could attempt wiring, but
+                    // wiring heuristics are risky so we just keep it)
+                    continue;
+                }
+                // Truly orphaned: remove
+                const idx = actions.findIndex((a) => a.name === nodeId);
+                if (idx !== -1) {
+                    actions.splice(idx, 1);
+                    removedNodes.push(nodeId);
+                }
+                // Remove associated result mappings
+                for (const [key, resultDef] of Object.entries(results)) {
+                    if (resultDef.actionName === nodeId) {
+                        delete results[key];
+                    }
+                }
+            }
+            if (removedNodes.length === 0)
+                return null;
+            const result = emptyResult(cloned);
+            result.nodesRemoved = removedNodes;
+            result.description = `Removed ${removedNodes.length} unreachable node(s): ${removedNodes.join(", ")}`;
+            return result;
+        }
+        catch {
+            return null;
+        }
+    },
+};
+/**
+ * 2. Break cycles by removing back-edges.
+ */
+const breakCycles = {
+    id: "break-cycles",
+    name: "Break Cycles",
+    description: "Remove back-edges that create cycles in the workflow graph",
+    apply(workflowDef, graph) {
+        try {
+            if (!graph.trigger || graph.nodes.size === 0)
+                return null;
+            // DFS to find back-edges
+            const visited = new Set();
+            const inStack = new Set();
+            const backEdges = [];
+            function dfs(nodeId) {
+                visited.add(nodeId);
+                inStack.add(nodeId);
+                for (const child of graph.forward.get(nodeId) ?? []) {
+                    if (inStack.has(child)) {
+                        // Back-edge: nodeId -> child where child is ancestor in DFS stack.
+                        // forward.get(nodeId) has nodes consuming nodeId's output, so child
+                        // has an input binding referencing nodeId. Remove it to break cycle.
+                        backEdges.push({ from: nodeId, to: child, inputName: "" });
+                    }
+                    else if (!visited.has(child)) {
+                        dfs(child);
+                    }
+                }
+                inStack.delete(nodeId);
+            }
+            dfs(graph.trigger);
+            if (backEdges.length === 0)
+                return null;
+            const cloned = deepClone(workflowDef);
+            const actions = cloned.actions;
+            const edgesRewired = [];
+            const nodesModified = [];
+            for (const backEdge of backEdges) {
+                // Find the target node (child) and remove inputs referencing backEdge.from
+                const targetAction = actions.find((a) => a.name === backEdge.to);
+                if (!targetAction)
+                    continue;
+                const inputs = targetAction.inputs;
+                if (!inputs)
+                    continue;
+                for (const [inputName, inputVal] of Object.entries(inputs)) {
+                    const binding = inputVal;
+                    if (binding?.actionOutput) {
+                        const ao = binding.actionOutput;
+                        if (ao.actionName === backEdge.from) {
+                            delete inputs[inputName];
+                            edgesRewired.push({
+                                from: backEdge.from,
+                                to: backEdge.to,
+                                reason: `Removed back-edge input "${inputName}" to break cycle`,
+                            });
+                            if (!nodesModified.includes(backEdge.to)) {
+                                nodesModified.push(backEdge.to);
+                            }
+                        }
+                    }
+                }
+            }
+            if (edgesRewired.length === 0)
+                return null;
+            const result = emptyResult(cloned);
+            result.nodesModified = nodesModified;
+            result.edgesRewired = edgesRewired;
+            result.description = `Broke ${edgesRewired.length} cycle(s) by removing back-edge input bindings`;
+            return result;
+        }
+        catch {
+            return null;
+        }
+    },
+};
+/**
+ * 3. Merge identical nodes (same action type, version, and input wiring).
+ */
+const mergeIdenticalNodes = {
+    id: "merge-identical-nodes",
+    name: "Merge Identical Nodes",
+    description: "Merge nodes with identical action type, version, and input wiring",
+    apply(workflowDef, graph) {
+        try {
+            if (graph.nodes.size === 0)
+                return null;
+            const actions = workflowDef.actions ?? [];
+            // Group by signature, skipping triggers and side-effect nodes
+            const groups = new Map();
+            for (const action of actions) {
+                if (isTriggerAction(action))
+                    continue;
+                if (hasSideEffects(action))
+                    continue;
+                const sig = nodeSignature(action);
+                if (!groups.has(sig))
+                    groups.set(sig, []);
+                groups.get(sig).push(action);
+            }
+            // Find groups with duplicates
+            const mergeGroups = [...groups.values()].filter((g) => g.length >= 2);
+            if (mergeGroups.length === 0)
+                return null;
+            const cloned = deepClone(workflowDef);
+            const clonedActions = cloned.actions;
+            const clonedResults = (cloned.results ?? {});
+            const removedNodes = [];
+            const edgesRewired = [];
+            for (const group of mergeGroups) {
+                const survivorName = group[0].name;
+                for (let i = 1; i < group.length; i++) {
+                    const duplicateName = group[i].name;
+                    // Rewire all references from duplicate to survivor
+                    rewireReferences(clonedActions, duplicateName, survivorName);
+                    rewireResults(clonedResults, duplicateName, survivorName);
+                    // Remove the duplicate
+                    const idx = clonedActions.findIndex((a) => a.name === duplicateName);
+                    if (idx !== -1) {
+                        clonedActions.splice(idx, 1);
+                        removedNodes.push(duplicateName);
+                        edgesRewired.push({
+                            from: duplicateName,
+                            to: survivorName,
+                            reason: `Merged identical node "${duplicateName}" into "${survivorName}"`,
+                        });
+                    }
+                }
+            }
+            if (removedNodes.length === 0)
+                return null;
+            const result = emptyResult(cloned);
+            result.nodesRemoved = removedNodes;
+            result.edgesRewired = edgesRewired;
+            result.description = `Merged ${removedNodes.length} duplicate node(s)`;
+            return result;
+        }
+        catch {
+            return null;
+        }
+    },
+};
+/**
+ * 4. Remove unnecessary categorizers where all handlers are identical.
+ */
+const removeUnnecessaryCategorizers = {
+    id: "remove-unnecessary-categorizers",
+    name: "Remove Unnecessary Categorizers",
+    description: "Remove categorizers where all handler branches do the same thing",
+    apply(workflowDef, graph) {
+        try {
+            if (graph.nodes.size === 0)
+                return null;
+            const categorizerNodes = getNodesByType(graph, "chat_categorizer", "text_categorizer");
+            if (categorizerNodes.length === 0)
+                return null;
+            const cloned = deepClone(workflowDef);
+            const actions = cloned.actions;
+            const removedNodes = [];
+            const nodesModified = [];
+            for (const catNode of categorizerNodes) {
+                // Find all handler nodes (nodes with runIf referencing this categorizer)
+                const handlerNodes = [];
+                for (const node of graph.nodes.values()) {
+                    if (node.runIf?.sourceNode === catNode.id) {
+                        handlerNodes.push(node);
+                    }
+                }
+                if (handlerNodes.length < 2)
+                    continue;
+                // Check if all handlers have identical action type + input wiring (ignoring runIf)
+                const originalActions = workflowDef.actions ?? [];
+                const handlerSignatures = handlerNodes.map((h) => {
+                    const rawAction = originalActions.find((a) => a.name === h.id);
+                    if (!rawAction)
+                        return "";
+                    // Build signature without runIf
+                    const withoutRunIf = { ...rawAction };
+                    delete withoutRunIf.runIf;
+                    return nodeSignature(withoutRunIf);
+                });
+                const allSame = handlerSignatures.every((s) => s === handlerSignatures[0]);
+                if (!allSame)
+                    continue;
+                // Remove the categorizer
+                const catIdx = actions.findIndex((a) => a.name === catNode.id);
+                if (catIdx !== -1) {
+                    actions.splice(catIdx, 1);
+                    removedNodes.push(catNode.id);
+                }
+                // Keep only the first handler, remove runIf from it, remove others
+                const keepHandler = handlerNodes[0].id;
+                for (const handler of handlerNodes) {
+                    const handlerAction = actions.find((a) => a.name === handler.id);
+                    if (!handlerAction)
+                        continue;
+                    if (handler.id === keepHandler) {
+                        // Remove runIf from kept handler
+                        delete handlerAction.runIf;
+                        nodesModified.push(handler.id);
+                    }
+                    else {
+                        // Remove duplicate handlers
+                        const idx = actions.findIndex((a) => a.name === handler.id);
+                        if (idx !== -1) {
+                            // Rewire references from this handler to the kept handler
+                            rewireReferences(actions, handler.id, keepHandler);
+                            const results = (cloned.results ?? {});
+                            rewireResults(results, handler.id, keepHandler);
+                            actions.splice(idx, 1);
+                            removedNodes.push(handler.id);
+                        }
+                    }
+                }
+            }
+            if (removedNodes.length === 0)
+                return null;
+            const result = emptyResult(cloned);
+            result.nodesRemoved = removedNodes;
+            result.nodesModified = nodesModified;
+            result.description = `Removed ${removedNodes.filter((n) => categorizerNodes.some((c) => c.id === n)).length} unnecessary categorizer(s) with identical handlers`;
+            return result;
+        }
+        catch {
+            return null;
+        }
+    },
+};
+/**
+ * 5. Prune dead branches (categories with no handlers).
+ */
+const pruneDeadBranches = {
+    id: "prune-dead-branches",
+    name: "Prune Dead Branches",
+    description: "Remove categorizer categories that have no handler nodes",
+    apply(workflowDef, graph) {
+        try {
+            if (graph.nodes.size === 0)
+                return null;
+            const categorizerNodes = getNodesByType(graph, "chat_categorizer", "text_categorizer");
+            if (categorizerNodes.length === 0)
+                return null;
+            const cloned = deepClone(workflowDef);
+            const actions = cloned.actions;
+            const enumTypes = (cloned.enumTypes ?? []);
+            const deadCategories = [];
+            for (const catNode of categorizerNodes) {
+                const categories = catNode.categories ?? [];
+                if (categories.length === 0)
+                    continue;
+                // Find which categories have handlers
+                const handledCategories = new Set();
+                for (const node of graph.nodes.values()) {
+                    if (node.runIf?.sourceNode === catNode.id && node.runIf?.value) {
+                        handledCategories.add(node.runIf.value);
+                    }
+                }
+                const unhandled = categories.filter((c) => !handledCategories.has(c));
+                if (unhandled.length === 0)
+                    continue;
+                deadCategories.push(...unhandled);
+                // Remove unhandled categories from the categorizer action
+                const catAction = actions.find((a) => a.name === catNode.id);
+                if (catAction) {
+                    const cats = catAction.categories;
+                    if (Array.isArray(cats)) {
+                        catAction.categories = cats.filter((c) => !unhandled.includes(c));
+                    }
+                }
+                // Remove from enumTypes
+                for (const et of enumTypes) {
+                    const options = et.options;
+                    if (Array.isArray(options)) {
+                        et.options = options.filter((o) => !unhandled.includes(o.name));
+                    }
+                }
+            }
+            if (deadCategories.length === 0)
+                return null;
+            const result = emptyResult(cloned);
+            result.nodesModified = categorizerNodes
+                .filter((c) => (c.categories ?? []).some((cat) => deadCategories.includes(cat)))
+                .map((c) => c.id);
+            result.description = `Pruned ${deadCategories.length} dead branch(es): ${deadCategories.join(", ")}`;
+            return result;
+        }
+        catch {
+            return null;
+        }
+    },
+};
+/**
+ * 6. Remove trailing nodes downstream of result mappings that don't contribute to outputs.
+ */
+const removeTrailingNodes = {
+    id: "remove-trailing-nodes",
+    name: "Remove Trailing Nodes",
+    description: "Remove side-effect-free nodes downstream of result mappings that don't contribute to any output",
+    apply(workflowDef, graph) {
+        try {
+            if (graph.nodes.size === 0)
+                return null;
+            // Build set of nodes that contribute to output mappings
+            const resultNodes = new Set(graph.outputMappings.map((m) => m.nodeId));
+            // Find nodes that are downstream of result nodes but don't contribute to results
+            // and are side-effect-free
+            const trailingNodes = [];
+            for (const [nodeId, node] of graph.nodes) {
+                if (node.isTrigger)
+                    continue;
+                if (resultNodes.has(nodeId))
+                    continue;
+                if (node.hasSideEffects)
+                    continue;
+                // Check if this node has no downstream consumers, or none of its
+                // downstream path reaches a result node
+                const consumers = getOutputConsumers(graph, nodeId);
+                // If no one consumes this node's output and it's not a result node, it's trailing
+                // Also check: is this node only reachable through result nodes?
+                // More precisely: a node is trailing if it doesn't contribute to any result mapping
+                const contributesToResult = doesContributeToResult(nodeId, graph, resultNodes);
+                if (!contributesToResult) {
+                    trailingNodes.push(nodeId);
+                }
+            }
+            if (trailingNodes.length === 0)
+                return null;
+            const cloned = deepClone(workflowDef);
+            const actions = cloned.actions;
+            for (const nodeId of trailingNodes) {
+                const idx = actions.findIndex((a) => a.name === nodeId);
+                if (idx !== -1) {
+                    actions.splice(idx, 1);
+                }
+            }
+            const result = emptyResult(cloned);
+            result.nodesRemoved = trailingNodes;
+            result.description = `Removed ${trailingNodes.length} trailing node(s): ${trailingNodes.join(", ")}`;
+            return result;
+        }
+        catch {
+            return null;
+        }
+    },
+};
+/**
+ * Check if a node contributes to any result mapping via forward traversal.
+ */
+function doesContributeToResult(nodeId, graph, resultNodes) {
+    if (resultNodes.has(nodeId))
+        return true;
+    // BFS forward from this node to see if any path leads to a result node
+    const visited = new Set();
+    const queue = [nodeId];
+    while (queue.length > 0) {
+        const current = queue.shift();
+        if (visited.has(current))
+            continue;
+        visited.add(current);
+        const consumers = graph.forward.get(current);
+        if (!consumers)
+            continue;
+        for (const consumer of consumers) {
+            if (resultNodes.has(consumer))
+                return true;
+            if (!visited.has(consumer)) {
+                queue.push(consumer);
+            }
+        }
+    }
+    return false;
+}
+/**
+ * 7. Prune stale result mappings referencing non-existent nodes.
+ */
+const pruneStaleResultMappings = {
+    id: "prune-stale-results",
+    name: "Prune Stale Result Mappings",
+    description: "Remove result entries that reference non-existent action nodes",
+    apply(workflowDef, graph) {
+        try {
+            const results = workflowDef.results;
+            if (!results || Object.keys(results).length === 0)
+                return null;
+            const actions = workflowDef.actions ?? [];
+            const actionNames = getActionNames(actions);
+            const staleKeys = [];
+            for (const [key, resultDef] of Object.entries(results)) {
+                if (!resultDef || !resultDef.actionName)
+                    continue;
+                if (!actionNames.has(resultDef.actionName)) {
+                    staleKeys.push(key);
+                }
+            }
+            if (staleKeys.length === 0)
+                return null;
+            const cloned = deepClone(workflowDef);
+            const clonedResults = cloned.results;
+            for (const key of staleKeys) {
+                delete clonedResults[key];
+            }
+            const result = emptyResult(cloned);
+            result.description = `Removed ${staleKeys.length} stale result mapping(s): ${staleKeys.join(", ")}`;
+            return result;
+        }
+        catch {
+            return null;
+        }
+    },
+};
+/**
+ * 8. Deduplicate enumTypes by name.
+ */
+const deduplicateEnumTypes = {
+    id: "deduplicate-enums",
+    name: "Deduplicate Enum Types",
+    description: "Remove duplicate enumType entries with the same name",
+    apply(workflowDef, graph) {
+        try {
+            const enumTypes = workflowDef.enumTypes;
+            if (!enumTypes || !Array.isArray(enumTypes) || enumTypes.length === 0)
+                return null;
+            const seen = new Set();
+            const duplicateIndices = [];
+            for (let i = 0; i < enumTypes.length; i++) {
+                const name = extractEnumName(enumTypes[i]);
+                if (!name)
+                    continue;
+                if (seen.has(name)) {
+                    duplicateIndices.push(i);
+                }
+                else {
+                    seen.add(name);
+                }
+            }
+            if (duplicateIndices.length === 0)
+                return null;
+            const cloned = deepClone(workflowDef);
+            const clonedEnums = cloned.enumTypes;
+            // Remove in reverse order to preserve indices
+            for (let i = duplicateIndices.length - 1; i >= 0; i--) {
+                clonedEnums.splice(duplicateIndices[i], 1);
+            }
+            const result = emptyResult(cloned);
+            result.description = `Removed ${duplicateIndices.length} duplicate enumType(s)`;
+            return result;
+        }
+        catch {
+            return null;
+        }
+    },
+};
+/** Extract enum type name, handling nested name objects. */
+function extractEnumName(et) {
+    const rawName = et.name;
+    if (typeof rawName === "string")
+        return rawName;
+    if (rawName && typeof rawName === "object") {
+        const nameObj = rawName;
+        if (typeof nameObj.name === "string")
+            return nameObj.name;
+        if (nameObj.name && typeof nameObj.name === "object") {
+            const nested = nameObj.name;
+            if (typeof nested.name === "string")
+                return nested.name;
+        }
+    }
+    return undefined;
+}
+// ─────────────────────────────────────────────────────────────────────────────
+// Advisory Transforms
+// ─────────────────────────────────────────────────────────────────────────────
+/**
+ * 9. Detect similar nodes (same action type, different inputs).
+ */
+const detectSimilarNodes = {
+    id: "similar-nodes",
+    name: "Detect Similar Nodes",
+    description: "Find nodes with the same action type but different inputs",
+    apply(workflowDef, graph) {
+        try {
+            if (graph.nodes.size === 0)
+                return null;
+            // Group non-trigger nodes by action type
+            const byType = new Map();
+            for (const node of graph.nodes.values()) {
+                if (node.isTrigger)
+                    continue;
+                if (!byType.has(node.actionType))
+                    byType.set(node.actionType, []);
+                byType.get(node.actionType).push(node);
+            }
+            const actions = workflowDef.actions ?? [];
+            const similarPairs = [];
+            for (const [actionType, nodes] of byType) {
+                if (nodes.length < 2)
+                    continue;
+                // Check if any pair has different signatures (similar but not identical)
+                for (let i = 0; i < nodes.length; i++) {
+                    for (let j = i + 1; j < nodes.length; j++) {
+                        const rawA = actions.find((a) => a.name === nodes[i].id);
+                        const rawB = actions.find((a) => a.name === nodes[j].id);
+                        if (!rawA || !rawB)
+                            continue;
+                        const sigA = nodeSignature(rawA);
+                        const sigB = nodeSignature(rawB);
+                        if (sigA !== sigB) {
+                            similarPairs.push({ a: nodes[i].id, b: nodes[j].id, actionType });
+                        }
+                    }
+                }
+            }
+            if (similarPairs.length === 0)
+                return null;
+            const result = emptyResult(workflowDef);
+            result.applied = false;
+            result.description = `Found ${similarPairs.length} pair(s) of similar nodes: ${similarPairs.map((p) => `${p.a} <-> ${p.b} (${p.actionType})`).join("; ")}`;
+            return result;
+        }
+        catch {
+            return null;
+        }
+    },
+};
+/**
+ * 10. Detect suboptimal branching patterns.
+ */
+const detectSuboptimalBranching = {
+    id: "suboptimal-branching",
+    name: "Detect Suboptimal Branching",
+    description: "Detect single-category categorizers and deeply nested categorizer chains",
+    apply(workflowDef, graph) {
+        try {
+            if (graph.nodes.size === 0)
+                return null;
+            const categorizerNodes = getNodesByType(graph, "chat_categorizer", "text_categorizer");
+            if (categorizerNodes.length === 0)
+                return null;
+            const issues = [];
+            for (const catNode of categorizerNodes) {
+                const categories = catNode.categories ?? [];
+                // Single-category (plus Fallback) detection
+                const nonFallback = categories.filter((c) => c !== "Fallback");
+                if (nonFallback.length <= 1) {
+                    issues.push(`Categorizer "${catNode.id}" has only ${nonFallback.length} non-Fallback category (${nonFallback.join(", ") || "none"}) - branching adds no value`);
+                }
+            }
+            // Detect deeply nested categorizer chains (categorizer -> handler with runIf -> another categorizer)
+            for (const catNode of categorizerNodes) {
+                // Check if any downstream node is also a categorizer
+                const consumers = getOutputConsumers(graph, catNode.id);
+                for (const consumerId of consumers) {
+                    const consumer = graph.nodes.get(consumerId);
+                    if (consumer && (consumer.actionType === "chat_categorizer" || consumer.actionType === "text_categorizer")) {
+                        issues.push(`Nested categorizer chain: "${catNode.id}" -> "${consumerId}" - consider flattening`);
+                    }
+                }
+            }
+            if (issues.length === 0)
+                return null;
+            const result = emptyResult(workflowDef);
+            result.applied = false;
+            result.description = issues.join("; ");
+            return result;
+        }
+        catch {
+            return null;
+        }
+    },
+};
+// ─────────────────────────────────────────────────────────────────────────────
+// Exports
+// ─────────────────────────────────────────────────────────────────────────────
+export const AUTO_TRANSFORMS = [
+    removeDeadNodes,
+    breakCycles,
+    mergeIdenticalNodes,
+    removeUnnecessaryCategorizers,
+    pruneDeadBranches,
+    removeTrailingNodes,
+    pruneStaleResultMappings,
+    deduplicateEnumTypes,
+];
+export const ADVISORY_TRANSFORMS = [
+    detectSimilarNodes,
+    detectSuboptimalBranching,
+];