@synergenius/flow-weaver 0.20.4 → 0.20.6

package/dist/api/validate.js

@@ -6,6 +6,7 @@
  */
 import { validator } from "../validator.js";
 import { getAgentValidationRules } from "../validation/agent-rules.js";
+import { getDesignValidationRules } from "../validation/design-rules.js";
 import { validationRuleRegistry } from "./validation-registry.js";
 /**
  * Validates a workflow AST
@@ -24,6 +25,7 @@ export function validateWorkflow(ast, options) {
     // including CI/CD when applicable), and custom rules
     const allRules = [
         ...getAgentValidationRules(),
+        ...getDesignValidationRules(),
         ...validationRuleRegistry.getApplicableRules(ast),
         ...(options?.customRules || []),
     ];

package/dist/cli/flow-weaver.mjs

@@ -9671,7 +9671,7 @@ var VERSION;
 var init_generated_version = __esm({
   "src/generated-version.ts"() {
     "use strict";
-    VERSION = "0.20.4";
+    VERSION = "0.20.6";
   }
 });
 
@@ -10456,9 +10456,9 @@ function generateScopeFunctionClosure(scopeName, parentNodeId, parentNodeType, w
       const childInstance = childInstances.find((c) => c.id === sourceNode);
       const sourceNodeTypeName = childInstance?.nodeType ?? "";
       const varAddr = `{ id: '${sourceNode}', portName: '${sourcePort}', executionIndex: ${toValidIdentifier(sourceNode)}Idx, nodeTypeName: '${sourceNodeTypeName}' }`;
-      const isStepPort = portName === "success" || portName === "failure";
+      const isStepPort2 = portName === "success" || portName === "failure";
       const defaultValue = portName === "success" ? "true" : portName === "failure" ? "false" : "undefined";
-      if (isStepPort) {
+      if (isStepPort2) {
         lines.push(
           `    const ${varName} = ctx.hasVariable(${varAddr}) ? ${getCallAfterMerge}(${varAddr}) as ${portType} : ${defaultValue};`
         );
@@ -10646,29 +10646,50 @@ function buildNodeArgumentsWithContext(opts) {
         const isConstSource = isStartNode(sourceNode) || sourceNode === instanceParent;
         const nonNullAssert = isConstSource ? "" : "!";
         const portType = mapToTypeScript(portConfig.dataType, portConfig.tsType);
+        const needsGuard = portConfig.optional && !isConstSource;
         if (portConfig.dataType === "FUNCTION") {
           const rawVarName = `${varName}_raw`;
-          lines.push(
-            `${indent}const ${rawVarName} = ${getCall}({ id: '${sourceNode}', portName: '${sourcePort}', executionIndex: ${sourceIdx}${nonNullAssert} });`
-          );
-          lines.push(
-            `${indent}const ${varName}_resolved = resolveFunction(${rawVarName});`
-          );
-          lines.push(
-            `${indent}const ${varName} = ${varName}_resolved.fn as ${portType};`
-          );
+          if (needsGuard) {
+            lines.push(
+              `${indent}const ${rawVarName} = ${sourceIdx} !== undefined ? ${getCall}({ id: '${sourceNode}', portName: '${sourcePort}', executionIndex: ${sourceIdx} }) : undefined;`
+            );
+            lines.push(
+              `${indent}const ${varName}_resolved = ${rawVarName} !== undefined ? resolveFunction(${rawVarName}) : undefined;`
+            );
+            lines.push(
+              `${indent}const ${varName} = ${varName}_resolved?.fn as ${portType};`
+            );
+          } else {
+            lines.push(
+              `${indent}const ${rawVarName} = ${getCall}({ id: '${sourceNode}', portName: '${sourcePort}', executionIndex: ${sourceIdx}${nonNullAssert} });`
+            );
+            lines.push(
+              `${indent}const ${varName}_resolved = resolveFunction(${rawVarName});`
+            );
+            lines.push(
+              `${indent}const ${varName} = ${varName}_resolved.fn as ${portType};`
+            );
+          }
         } else {
           const sourceDataType = resolveSourcePortDataType(workflow, sourceNode, sourcePort);
           const coerceExpr = getCoercionWrapper(connection, sourceDataType, portConfig.dataType);
-          const getExpr = `${getCall}({ id: '${sourceNode}', portName: '${sourcePort}', executionIndex: ${sourceIdx}${nonNullAssert} })`;
-          if (coerceExpr) {
+          if (needsGuard) {
+            const getExpr = `${getCall}({ id: '${sourceNode}', portName: '${sourcePort}', executionIndex: ${sourceIdx} })`;
+            const wrappedExpr = coerceExpr ? `${coerceExpr}(${getExpr})` : getExpr;
             lines.push(
-              `${indent}const ${varName} = ${coerceExpr}(${getExpr}) as ${portType};`
+              `${indent}const ${varName} = ${sourceIdx} !== undefined ? ${wrappedExpr} as ${portType} : undefined;`
             );
           } else {
-            lines.push(
-              `${indent}const ${varName} = ${getExpr} as ${portType};`
-            );
+            const getExpr = `${getCall}({ id: '${sourceNode}', portName: '${sourcePort}', executionIndex: ${sourceIdx}${nonNullAssert} })`;
+            if (coerceExpr) {
+              lines.push(
+                `${indent}const ${varName} = ${coerceExpr}(${getExpr}) as ${portType};`
+              );
+            } else {
+              lines.push(
+                `${indent}const ${varName} = ${getExpr} as ${portType};`
+              );
+            }
           }
         }
       } else {
@@ -39966,6 +39987,277 @@ var init_agent_rules = __esm({
   }
 });
 
+// src/validation/design-rules.ts
+function resolveNodeType2(ast, instance) {
+  return ast.nodeTypes.find(
+    (nt) => nt.name === instance.nodeType || nt.functionName === instance.nodeType
+  );
+}
+function getOutgoing2(ast, nodeId, portName) {
+  return ast.connections.filter((c) => {
+    if (c.from.node !== nodeId) return false;
+    if (portName && c.from.port !== portName) return false;
+    return true;
+  });
+}
+function getIncoming(ast, nodeId, portName) {
+  return ast.connections.filter((c) => {
+    if (c.to.node !== nodeId) return false;
+    if (portName && c.to.port !== portName) return false;
+    return true;
+  });
+}
+function isStepPort(portName, portDef) {
+  if (portDef?.dataType === "STEP") return true;
+  return STEP_PORTS.has(portName);
+}
+function getReachableNodes(ast, startNode) {
+  const visited = /* @__PURE__ */ new Set();
+  const queue = [startNode];
+  while (queue.length > 0) {
+    const current2 = queue.shift();
+    if (visited.has(current2)) continue;
+    visited.add(current2);
+    for (const conn of ast.connections) {
+      if (conn.from.node === current2 && !visited.has(conn.to.node)) {
+        queue.push(conn.to.node);
+      }
+    }
+  }
+  return visited;
+}
+function getDesignValidationRules() {
+  return designValidationRules;
+}
+var STEP_PORTS, asyncNoErrorPathRule, scopeNoFailureExitRule, unboundedRetryRule, fanoutNoFaninRule, exitDataUnreachableRule, pullCandidateRule, pullUnusedRule, designValidationRules;
+var init_design_rules = __esm({
+  "src/validation/design-rules.ts"() {
+    "use strict";
+    STEP_PORTS = /* @__PURE__ */ new Set(["execute", "onSuccess", "onFailure", "start", "success", "failure"]);
+    asyncNoErrorPathRule = {
+      name: "DESIGN_ASYNC_NO_ERROR_PATH",
+      validate(ast) {
+        const errors2 = [];
+        for (const instance of ast.instances) {
+          const nt = resolveNodeType2(ast, instance);
+          if (!nt) continue;
+          if (!nt.isAsync) continue;
+          if (!nt.hasFailurePort) continue;
+          const failureConns = getOutgoing2(ast, instance.id, "onFailure");
+          if (failureConns.length === 0) {
+            errors2.push({
+              type: "warning",
+              code: "DESIGN_ASYNC_NO_ERROR_PATH",
+              message: `Async node '${instance.id}' has no onFailure connection. Async operations (network, disk, AI) can fail, and errors will be silently lost.`,
+              node: instance.id
+            });
+          }
+        }
+        return errors2;
+      }
+    };
+    scopeNoFailureExitRule = {
+      name: "DESIGN_SCOPE_NO_FAILURE_EXIT",
+      validate(ast) {
+        const errors2 = [];
+        for (const instance of ast.instances) {
+          const nt = resolveNodeType2(ast, instance);
+          if (!nt) continue;
+          const scopeNames = nt.scopes ?? (nt.scope ? [nt.scope] : []);
+          if (scopeNames.length === 0) continue;
+          if (!nt.hasFailurePort) continue;
+          const failureConns = getOutgoing2(ast, instance.id, "onFailure");
+          const failureConns2 = getOutgoing2(ast, instance.id, "failure");
+          if (failureConns.length === 0 && failureConns2.length === 0) {
+            errors2.push({
+              type: "warning",
+              code: "DESIGN_SCOPE_NO_FAILURE_EXIT",
+              message: `Scope node '${instance.id}' has no failure path out. If all iterations fail, execution stalls with no error surfaced.`,
+              node: instance.id
+            });
+          }
+        }
+        return errors2;
+      }
+    };
+    unboundedRetryRule = {
+      name: "DESIGN_UNBOUNDED_RETRY",
+      validate(ast) {
+        const errors2 = [];
+        const retryPatterns = /retry|repeat|loop|poll|backoff/i;
+        for (const instance of ast.instances) {
+          const nt = resolveNodeType2(ast, instance);
+          if (!nt) continue;
+          const scopeNames = nt.scopes ?? (nt.scope ? [nt.scope] : []);
+          if (scopeNames.length === 0) continue;
+          const nameHint = `${nt.name} ${nt.functionName} ${nt.label ?? ""}`;
+          if (!retryPatterns.test(nameHint)) continue;
+          const limitInputs = Object.keys(nt.inputs).filter(
+            (p) => /max|limit|attempts|retries|count/i.test(p)
+          );
+          if (limitInputs.length === 0) {
+            errors2.push({
+              type: "warning",
+              code: "DESIGN_UNBOUNDED_RETRY",
+              message: `Scope node '${instance.id}' appears to be a retry loop but has no visible attempt limit input. This could loop indefinitely.`,
+              node: instance.id
+            });
+          }
+        }
+        return errors2;
+      }
+    };
+    fanoutNoFaninRule = {
+      name: "DESIGN_FANOUT_NO_FANIN",
+      validate(ast) {
+        const errors2 = [];
+        for (const instance of ast.instances) {
+          const nt = resolveNodeType2(ast, instance);
+          const stepOutConns = getOutgoing2(ast, instance.id).filter((c) => {
+            if (nt) {
+              const portDef = nt.outputs[c.from.port];
+              return isStepPort(c.from.port, portDef);
+            }
+            return isStepPort(c.from.port);
+          });
+          const stepTargets = [...new Set(stepOutConns.map((c) => c.to.node))].filter(
+            (n) => n !== "Exit"
+          );
+          if (stepTargets.length < 3) continue;
+          const reachableSets = stepTargets.map((target) => getReachableNodes(ast, target));
+          const allNodes = /* @__PURE__ */ new Set();
+          let hasMerge = false;
+          for (const reachable of reachableSets) {
+            for (const node of reachable) {
+              if (allNodes.has(node)) {
+                hasMerge = true;
+                break;
+              }
+            }
+            if (hasMerge) break;
+            for (const node of reachable) {
+              allNodes.add(node);
+            }
+          }
+          if (!hasMerge) {
+            for (const target of stepTargets) {
+              const targetInst = ast.instances.find((i) => i.id === target);
+              if (!targetInst) continue;
+              const targetNt = resolveNodeType2(ast, targetInst);
+              if (!targetNt) continue;
+              const hasMergePort = Object.values(targetNt.inputs).some((p) => p.mergeStrategy);
+              if (hasMergePort) {
+                hasMerge = true;
+                break;
+              }
+            }
+          }
+          if (!hasMerge) {
+            errors2.push({
+              type: "warning",
+              code: "DESIGN_FANOUT_NO_FANIN",
+              message: `Node '${instance.id}' fans out to ${stepTargets.length} step targets (${stepTargets.join(", ")}) but those paths never merge back. Data from parallel branches may be lost.`,
+              node: instance.id
+            });
+          }
+        }
+        return errors2;
+      }
+    };
+    exitDataUnreachableRule = {
+      name: "DESIGN_EXIT_DATA_UNREACHABLE",
+      validate(ast) {
+        const errors2 = [];
+        const stepPorts = /* @__PURE__ */ new Set(["onSuccess", "onFailure"]);
+        for (const [portName, portDef] of Object.entries(ast.exitPorts)) {
+          if (portDef.dataType === "STEP") continue;
+          const incoming = getIncoming(ast, "Exit", portName);
+          if (incoming.length > 0) continue;
+          const hasPullProvider = ast.instances.some((inst) => {
+            const isPull = inst.config?.pullExecution || resolveNodeType2(ast, inst)?.defaultConfig?.pullExecution;
+            if (!isPull) return false;
+            return getOutgoing2(ast, inst.id).some(
+              (c) => c.to.node === "Exit" && c.to.port === portName
+            );
+          });
+          if (!hasPullProvider) {
+            errors2.push({
+              type: "warning",
+              code: "DESIGN_EXIT_DATA_UNREACHABLE",
+              message: `Exit port '${portName}' has no incoming connection and no pull-execution node provides it. The output will be undefined.`
+            });
+          }
+        }
+        return errors2;
+      }
+    };
+    pullCandidateRule = {
+      name: "DESIGN_PULL_CANDIDATE",
+      validate(ast) {
+        const errors2 = [];
+        for (const instance of ast.instances) {
+          const nt = resolveNodeType2(ast, instance);
+          if (!nt) continue;
+          if (instance.config?.pullExecution || nt.defaultConfig?.pullExecution) continue;
+          if (nt.expression) continue;
+          const incomingStep = getIncoming(ast, instance.id).filter((c) => {
+            const portDef = nt.inputs[c.to.port];
+            return isStepPort(c.to.port, portDef);
+          });
+          if (incomingStep.length > 0) continue;
+          const dataOutputs = Object.keys(nt.outputs).filter((p) => !STEP_PORTS.has(p));
+          const hasConsumedOutput = dataOutputs.some(
+            (port) => getOutgoing2(ast, instance.id, port).length > 0
+          );
+          if (hasConsumedOutput) {
+            errors2.push({
+              type: "warning",
+              code: "DESIGN_PULL_CANDIDATE",
+              message: `Node '${instance.id}' has no incoming step connection but its data outputs are consumed downstream. Consider adding [pullExecution: execute] so it executes on demand.`,
+              node: instance.id
+            });
+          }
+        }
+        return errors2;
+      }
+    };
+    pullUnusedRule = {
+      name: "DESIGN_PULL_UNUSED",
+      validate(ast) {
+        const errors2 = [];
+        for (const instance of ast.instances) {
+          const nt = resolveNodeType2(ast, instance);
+          if (!nt) continue;
+          const isPull = instance.config?.pullExecution || nt.defaultConfig?.pullExecution;
+          if (!isPull) continue;
+          const dataOutputs = Object.keys(nt.outputs).filter((p) => !STEP_PORTS.has(p));
+          const hasConnectedOutput = dataOutputs.some(
+            (port) => getOutgoing2(ast, instance.id, port).length > 0
+          );
+          if (!hasConnectedOutput) {
+            errors2.push({
+              type: "warning",
+              code: "DESIGN_PULL_UNUSED",
+              message: `Node '${instance.id}' is marked with pullExecution but no downstream node reads its data output. It will never execute.`,
+              node: instance.id
+            });
+          }
+        }
+        return errors2;
+      }
+    };
+    designValidationRules = [
+      asyncNoErrorPathRule,
+      scopeNoFailureExitRule,
+      unboundedRetryRule,
+      fanoutNoFaninRule,
+      exitDataUnreachableRule,
+      pullCandidateRule,
+      pullUnusedRule
+    ];
+  }
+});
+
 // src/api/validate.ts
 var validate_exports = {};
 __export(validate_exports, {
@@ -39975,6 +40267,7 @@ function validateWorkflow(ast, options) {
   const result = validator.validate(ast, { mode: options?.mode });
   const allRules = [
     ...getAgentValidationRules(),
+    ...getDesignValidationRules(),
     ...validationRuleRegistry.getApplicableRules(ast),
     ...options?.customRules || []
   ];
@@ -40009,6 +40302,7 @@ var init_validate = __esm({
     "use strict";
     init_validator();
     init_agent_rules();
+    init_design_rules();
     init_validation_registry();
   }
 });
@@ -46491,6 +46785,7 @@ function aggregateResults(
  * @connect iterator.results -> Exit.results
  * @connect iterator.results -> aggregator.results
  * @connect iterator.onSuccess -> aggregator.execute
+ * @connect iterator.onFailure -> aggregator.execute
  * @connect aggregator.successCount -> Exit.successCount
  * @connect aggregator.failedCount -> Exit.failedCount
  * @connect aggregator.onSuccess -> Exit.onSuccess
@@ -47128,6 +47423,7 @@ const TOOL_IMPLEMENTATIONS: Record<string, ToolFn> = {
  * @flowWeaver nodeType
  * @label Agent Loop
  * @input userMessage [order:1] - User's input message
+ * @input [maxIterations] [order:2] - Maximum loop iterations (default: 10)
  * @input success scope:iteration [order:0] - From LLM onSuccess
  * @input failure scope:iteration [order:1] - From LLM onFailure
  * @input llmResponse scope:iteration [order:2] - LLM response
@@ -47142,6 +47438,7 @@ const TOOL_IMPLEMENTATIONS: Record<string, ToolFn> = {
 async function agentLoop(
   execute: boolean,
   userMessage: string,
+  maxIterations: number = MAX_ITERATIONS,
   iteration: (start: boolean, state: AgentState) => Promise<{
     success: boolean;
     failure: boolean;
@@ -47160,7 +47457,7 @@ async function agentLoop(
     terminated: false,
   };
 
-  while (state.iteration < MAX_ITERATIONS) {
+  while (state.iteration < maxIterations) {
     const result = await iteration(true, state);
 
     state.iteration++;
@@ -47298,6 +47595,7 @@ async function executeTools(
  * @connect llm.onSuccess -> loop.success:iteration
  * @connect llm.onFailure -> loop.failure:iteration
  * @connect tools.messages -> loop.toolMessages:iteration
+ * @connect tools.onFailure -> loop.failure:iteration
  * @connect loop.response -> Exit.response
  * @connect loop.onSuccess -> Exit.onSuccess
  * @connect loop.onFailure -> Exit.onFailure
@@ -47427,6 +47725,7 @@ const TOOL_IMPLEMENTATIONS: Record<string, (input: string) => Promise<string>> =
  * @label ReAct Loop
  * @input execute [order:0] - Execute
  * @input task [order:1] - Task for the agent
+ * @input [maxSteps] [order:2] - Maximum reasoning steps (default: 10)
  * @input success scope:step [order:0] - Iteration succeeded
  * @input failure scope:step [order:1] - Iteration failed
  * @input thought scope:step [order:2] - Agent's reasoning
@@ -47442,6 +47741,7 @@ const TOOL_IMPLEMENTATIONS: Record<string, (input: string) => Promise<string>> =
 async function reactLoop(
   execute: boolean,
   task: string,
+  maxSteps: number = MAX_STEPS,
   step: (start: boolean, messages: LLMMessage[]) => Promise<{
     success: boolean;
     failure: boolean;
@@ -47457,7 +47757,7 @@ async function reactLoop(
 
   const messages: LLMMessage[] = [{ role: 'user', content: task }];
 
-  for (let i = 0; i < MAX_STEPS; i++) {
+  for (let i = 0; i < maxSteps; i++) {
     const result = await step(true, messages);
 
     if (result.failure) {
@@ -47770,7 +48070,7 @@ Answer:\`;
  * RAG Pipeline for knowledge-based Q&A
  *
  * @flowWeaver workflow
- * @node retriever retrieve [position: -50 0] [color: "teal"] [icon: "search"] [suppress: "UNUSED_OUTPUT_PORT"]
+ * @node retriever retrieve [position: -50 0] [color: "teal"] [icon: "search"] [suppress: "UNUSED_OUTPUT_PORT", "DESIGN_ASYNC_NO_ERROR_PATH"]
  * @node generator generate [position: 200 0] [color: "purple"] [icon: "autoAwesome"]
  * @position Start -300 0
  * @position Exit 400 0
@@ -78182,6 +78482,71 @@ var errorMappers = {
       code: error2.code
     };
   },
+  // ── Design quality rules ─────────────────────────────────────────────
+  DESIGN_ASYNC_NO_ERROR_PATH(error2) {
+    const nodeName = error2.node || "unknown";
+    return {
+      title: "Async Node Missing Error Path",
+      explanation: `Async node '${nodeName}' has no onFailure connection. Async operations (network calls, file I/O, AI calls) can fail, and errors will be silently lost.`,
+      fix: `Connect ${nodeName}.onFailure to an error handler, retry node, or Exit.onFailure.`,
+      code: error2.code
+    };
+  },
+  DESIGN_SCOPE_NO_FAILURE_EXIT(error2) {
+    const nodeName = error2.node || "unknown";
+    return {
+      title: "Scope Missing Failure Exit",
+      explanation: `Scope node '${nodeName}' has no failure path out. If all iterations fail, execution stalls with no error surfaced upstream.`,
+      fix: `Connect ${nodeName}.onFailure to an error handler or Exit.onFailure so scope failures propagate.`,
+      code: error2.code
+    };
+  },
+  DESIGN_UNBOUNDED_RETRY(error2) {
+    const nodeName = error2.node || "unknown";
+    return {
+      title: "Unbounded Retry Loop",
+      explanation: `Scope node '${nodeName}' looks like a retry loop but has no visible attempt limit input. This could loop indefinitely on persistent failures.`,
+      fix: `Add a maxAttempts or retries input port to the node type, or use a counter to break out of the loop after N attempts.`,
+      code: error2.code
+    };
+  },
+  DESIGN_FANOUT_NO_FANIN(error2) {
+    const nodeName = error2.node || "unknown";
+    return {
+      title: "Fan-Out Without Fan-In",
+      explanation: `Node '${nodeName}' fans out to multiple step targets, but those paths never merge back to a shared downstream node. Data from parallel branches may be lost.`,
+      fix: `Add a merge node downstream where the parallel branches converge, or wire them to a shared node before Exit.`,
+      code: error2.code
+    };
+  },
+  DESIGN_EXIT_DATA_UNREACHABLE(error2) {
+    const quoted = extractQuoted(error2.message);
+    const portName = quoted[0] || "unknown";
+    return {
+      title: "Exit Data Unreachable",
+      explanation: `Exit port '${portName}' has no incoming data connection and no pull-execution node provides it. The workflow will return undefined for this output.`,
+      fix: `Connect a node's data output to Exit.${portName}, or add a pull-execution node that computes this value on demand.`,
+      code: error2.code
+    };
+  },
+  DESIGN_PULL_CANDIDATE(error2) {
+    const nodeName = error2.node || "unknown";
+    return {
+      title: "Pull Execution Candidate",
+      explanation: `Node '${nodeName}' has no incoming step connection but its data outputs are consumed downstream. Without a step trigger or pullExecution, this node may never execute.`,
+      fix: `Add [pullExecution: execute] to the @node annotation so the node runs on demand when downstream nodes read its output.`,
+      code: error2.code
+    };
+  },
+  DESIGN_PULL_UNUSED(error2) {
+    const nodeName = error2.node || "unknown";
+    return {
+      title: "Unused Pull Execution",
+      explanation: `Node '${nodeName}' is marked with pullExecution but no downstream node reads its data output. The node will never execute since pull execution requires a consumer.`,
+      fix: `Connect a data output from '${nodeName}' to a downstream node, or remove the pullExecution config if the node isn't needed.`,
+      code: error2.code
+    };
+  },
   COERCE_TYPE_MISMATCH(error2) {
     const coerceMatch = error2.message.match(/`as (\w+)`/);
     const coerceType = coerceMatch?.[1] || "unknown";
@@ -100052,7 +100417,15 @@ var ERROR_HINTS = {
   AGENT_UNGUARDED_TOOL_EXECUTOR: 'Add a human-approval node before the tool executor. Use fw_scaffold(template="human-approval") to create one',
   AGENT_MISSING_MEMORY_IN_LOOP: 'Add a conversation-memory node inside the loop scope. Use fw_scaffold(template="conversation-memory") to create one',
   AGENT_LLM_NO_FALLBACK: "Add a retry or fallback node between the LLM onFailure and Exit. Consider a second LLM provider as fallback",
-  AGENT_TOOL_NO_OUTPUT_HANDLING: 'Use fw_modify(operation="addConnection") to wire tool output ports to downstream nodes'
+  AGENT_TOOL_NO_OUTPUT_HANDLING: 'Use fw_modify(operation="addConnection") to wire tool output ports to downstream nodes',
+  // Design quality rules
+  DESIGN_ASYNC_NO_ERROR_PATH: 'Use fw_modify(operation="addConnection", params={from:"<nodeId>.onFailure", to:"Exit.onFailure"}) or add a retry/error handler',
+  DESIGN_SCOPE_NO_FAILURE_EXIT: 'Use fw_modify(operation="addConnection", params={from:"<nodeId>.onFailure", to:"Exit.onFailure"}) to surface scope failures',
+  DESIGN_UNBOUNDED_RETRY: "Add a maxAttempts or retries input port to the retry node type to bound the loop",
+  DESIGN_FANOUT_NO_FANIN: "Add a merge node downstream where parallel branches converge before Exit",
+  DESIGN_EXIT_DATA_UNREACHABLE: 'Use fw_modify(operation="addConnection") to connect a node output to this Exit port, or add a pull-execution node',
+  DESIGN_PULL_CANDIDATE: "Add [pullExecution: execute] to the @node annotation so the node runs on demand",
+  DESIGN_PULL_UNUSED: "Connect a data output from this node to a downstream consumer, or remove pullExecution"
 };
 function addHintsToItems(items, friendlyErrorFn) {
   return items.map((item) => {
@@ -106710,7 +107083,7 @@ function displayInstalledPackage(pkg) {
 // src/cli/index.ts
 init_logger();
 init_error_utils();
-var version2 = true ? "0.20.4" : "0.0.0-dev";
+var version2 = true ? "0.20.6" : "0.0.0-dev";
 var program2 = new Command();
 program2.name("flow-weaver").description("Flow Weaver Annotations - Compile and validate workflow files").option("-v, --version", "Output the current version").option("--no-color", "Disable colors").option("--color", "Force colors").on("option:version", () => {
   logger.banner(version2);

package/dist/cli/templates/workflows/ai-agent.js

@@ -128,6 +128,7 @@ const TOOL_IMPLEMENTATIONS: Record<string, ToolFn> = {
  * @flowWeaver nodeType
  * @label Agent Loop
  * @input userMessage [order:1] - User's input message
+ * @input [maxIterations] [order:2] - Maximum loop iterations (default: 10)
  * @input success scope:iteration [order:0] - From LLM onSuccess
  * @input failure scope:iteration [order:1] - From LLM onFailure
  * @input llmResponse scope:iteration [order:2] - LLM response
@@ -142,6 +143,7 @@ const TOOL_IMPLEMENTATIONS: Record<string, ToolFn> = {
 async function agentLoop(
   execute: boolean,
   userMessage: string,
+  maxIterations: number = MAX_ITERATIONS,
   iteration: (start: boolean, state: AgentState) => Promise<{
     success: boolean;
     failure: boolean;
@@ -160,7 +162,7 @@ async function agentLoop(
     terminated: false,
   };
 
-  while (state.iteration < MAX_ITERATIONS) {
+  while (state.iteration < maxIterations) {
     const result = await iteration(true, state);
 
     state.iteration++;
@@ -298,6 +300,7 @@ async function executeTools(
  * @connect llm.onSuccess -> loop.success:iteration
  * @connect llm.onFailure -> loop.failure:iteration
  * @connect tools.messages -> loop.toolMessages:iteration
+ * @connect tools.onFailure -> loop.failure:iteration
  * @connect loop.response -> Exit.response
  * @connect loop.onSuccess -> Exit.onSuccess
  * @connect loop.onFailure -> Exit.onFailure

package/dist/cli/templates/workflows/ai-rag.js

@@ -145,7 +145,7 @@ Answer:\`;
  * RAG Pipeline for knowledge-based Q&A
  *
  * @flowWeaver workflow
- * @node retriever retrieve [position: -50 0] [color: "teal"] [icon: "search"] [suppress: "UNUSED_OUTPUT_PORT"]
+ * @node retriever retrieve [position: -50 0] [color: "teal"] [icon: "search"] [suppress: "UNUSED_OUTPUT_PORT", "DESIGN_ASYNC_NO_ERROR_PATH"]
  * @node generator generate [position: 200 0] [color: "purple"] [icon: "autoAwesome"]
  * @position Start -300 0
  * @position Exit 400 0

package/dist/cli/templates/workflows/ai-react.js

@@ -97,6 +97,7 @@ const TOOL_IMPLEMENTATIONS: Record<string, (input: string) => Promise<string>> =
  * @label ReAct Loop
  * @input execute [order:0] - Execute
  * @input task [order:1] - Task for the agent
+ * @input [maxSteps] [order:2] - Maximum reasoning steps (default: 10)
  * @input success scope:step [order:0] - Iteration succeeded
  * @input failure scope:step [order:1] - Iteration failed
  * @input thought scope:step [order:2] - Agent's reasoning
@@ -112,6 +113,7 @@ const TOOL_IMPLEMENTATIONS: Record<string, (input: string) => Promise<string>> =
 async function reactLoop(
   execute: boolean,
   task: string,
+  maxSteps: number = MAX_STEPS,
   step: (start: boolean, messages: LLMMessage[]) => Promise<{
     success: boolean;
     failure: boolean;
@@ -127,7 +129,7 @@ async function reactLoop(
 
   const messages: LLMMessage[] = [{ role: 'user', content: task }];
 
-  for (let i = 0; i < MAX_STEPS; i++) {
+  for (let i = 0; i < maxSteps; i++) {
     const result = await step(true, messages);
 
     if (result.failure) {

package/dist/cli/templates/workflows/foreach.js

@@ -116,6 +116,7 @@ function aggregateResults(
  * @connect iterator.results -> Exit.results
  * @connect iterator.results -> aggregator.results
  * @connect iterator.onSuccess -> aggregator.execute
+ * @connect iterator.onFailure -> aggregator.execute
  * @connect aggregator.successCount -> Exit.successCount
  * @connect aggregator.failedCount -> Exit.failedCount
  * @connect aggregator.onSuccess -> Exit.onSuccess

package/dist/doc-metadata/extractors/error-codes.d.ts

@@ -12,7 +12,7 @@ export interface TValidationCodeDoc {
     severity: 'error' | 'warning';
     title: string;
     description: string;
-    category: 'structural' | 'naming' | 'connection' | 'type' | 'node-ref' | 'graph' | 'data-flow' | 'agent';
+    category: 'structural' | 'naming' | 'connection' | 'type' | 'node-ref' | 'graph' | 'data-flow' | 'agent' | 'design';
 }
 export declare const VALIDATION_CODES: TValidationCodeDoc[];
 //# sourceMappingURL=error-codes.d.ts.map