@synergenius/flow-weaver 0.20.5 → 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.5";
+    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};`
         );
@@ -39987,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, {
@@ -39996,6 +40267,7 @@ function validateWorkflow(ast, options) {
   const result = validator.validate(ast, { mode: options?.mode });
   const allRules = [
     ...getAgentValidationRules(),
+    ...getDesignValidationRules(),
     ...validationRuleRegistry.getApplicableRules(ast),
     ...options?.customRules || []
   ];
@@ -40030,6 +40302,7 @@ var init_validate = __esm({
     "use strict";
     init_validator();
     init_agent_rules();
+    init_design_rules();
     init_validation_registry();
   }
 });
@@ -46512,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
@@ -47149,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
@@ -47163,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;
@@ -47181,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++;
@@ -47319,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
@@ -47448,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
@@ -47463,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;
@@ -47478,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) {
@@ -47791,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
@@ -78203,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";
@@ -100073,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) => {
@@ -106731,7 +107083,7 @@ function displayInstalledPackage(pkg) {
 // src/cli/index.ts
 init_logger();
 init_error_utils();
-var version2 = true ? "0.20.5" : "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

package/dist/doc-metadata/extractors/error-codes.js

@@ -318,5 +318,55 @@ export const VALIDATION_CODES = [
         description: 'Tool executor data outputs all unconnected',
         category: 'agent',
     },
+    // ── Design ──────────────────────────────────────────────────────────
+    {
+        code: 'DESIGN_ASYNC_NO_ERROR_PATH',
+        severity: 'warning',
+        title: 'Async Node Missing Error Path',
+        description: 'Async node has no onFailure connection',
+        category: 'design',
+    },
+    {
+        code: 'DESIGN_SCOPE_NO_FAILURE_EXIT',
+        severity: 'warning',
+        title: 'Scope Missing Failure Exit',
+        description: 'Scope node has no failure path out',
+        category: 'design',
+    },
+    {
+        code: 'DESIGN_UNBOUNDED_RETRY',
+        severity: 'warning',
+        title: 'Unbounded Retry Loop',
+        description: 'Retry scope has no visible attempt limit',
+        category: 'design',
+    },
+    {
+        code: 'DESIGN_FANOUT_NO_FANIN',
+        severity: 'warning',
+        title: 'Fan-Out Without Fan-In',
+        description: 'Fan-out to multiple step targets with no merge back',
+        category: 'design',
+    },
+    {
+        code: 'DESIGN_EXIT_DATA_UNREACHABLE',
+        severity: 'warning',
+        title: 'Exit Data Unreachable',
+        description: 'Exit data port has no connection and no pull-execution provider',
+        category: 'design',
+    },
+    {
+        code: 'DESIGN_PULL_CANDIDATE',
+        severity: 'warning',
+        title: 'Pull Execution Candidate',
+        description: 'Node has no step trigger but its outputs are consumed downstream',
+        category: 'design',
+    },
+    {
+        code: 'DESIGN_PULL_UNUSED',
+        severity: 'warning',
+        title: 'Unused Pull Execution',
+        description: 'Pull-execution node has no downstream consumers',
+        category: 'design',
+    },
 ];
 //# sourceMappingURL=error-codes.js.map

package/dist/friendly-errors.js

@@ -505,6 +505,71 @@ const errorMappers = {
             code: error.code,
         };
     },
+    // ── Design quality rules ─────────────────────────────────────────────
+    DESIGN_ASYNC_NO_ERROR_PATH(error) {
+        const nodeName = error.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: error.code,
+        };
+    },
+    DESIGN_SCOPE_NO_FAILURE_EXIT(error) {
+        const nodeName = error.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: error.code,
+        };
+    },
+    DESIGN_UNBOUNDED_RETRY(error) {
+        const nodeName = error.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: error.code,
+        };
+    },
+    DESIGN_FANOUT_NO_FANIN(error) {
+        const nodeName = error.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: error.code,
+        };
+    },
+    DESIGN_EXIT_DATA_UNREACHABLE(error) {
+        const quoted = extractQuoted(error.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: error.code,
+        };
+    },
+    DESIGN_PULL_CANDIDATE(error) {
+        const nodeName = error.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: error.code,
+        };
+    },
+    DESIGN_PULL_UNUSED(error) {
+        const nodeName = error.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: error.code,
+        };
+    },
     COERCE_TYPE_MISMATCH(error) {
         const coerceMatch = error.message.match(/`as (\w+)`/);
         const coerceType = coerceMatch?.[1] || 'unknown';

package/dist/generated-version.d.ts

@@ -1,2 +1,2 @@
-export declare const VERSION = "0.20.5";
+export declare const VERSION = "0.20.6";
 //# sourceMappingURL=generated-version.d.ts.map

package/dist/generated-version.js

@@ -1,3 +1,3 @@
 // Auto-generated by scripts/generate-version.ts — do not edit manually
-export const VERSION = '0.20.5';
+export const VERSION = '0.20.6';
 //# sourceMappingURL=generated-version.js.map

package/dist/mcp/response-utils.js

@@ -55,6 +55,14 @@ export const ERROR_HINTS = {
     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',
+    // 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',
 };
 /**
  * Enriches validation items with actionable hints from {@link ERROR_HINTS} and optional

package/dist/validation/design-rules.d.ts

@@ -0,0 +1,61 @@
+/**
+ * Design Quality Validation Rules
+ *
+ * Deterministic, AST-inspectable rules that catch common workflow design problems.
+ * A workflow can compile fine and still be poorly designed: missing error paths,
+ * unbounded retries, fan-out without fan-in, dead-end branches.
+ *
+ * All rules are warnings or info. None block compilation.
+ * Users can suppress any with @suppress.
+ *
+ * Rules:
+ * 1. DESIGN_ASYNC_NO_ERROR_PATH - Async node has no onFailure connection
+ * 2. DESIGN_SCOPE_NO_FAILURE_EXIT - Scope has no failure path out
+ * 3. DESIGN_UNBOUNDED_RETRY - Retry scope has no visible attempt limit
+ * 4. DESIGN_FANOUT_NO_FANIN - Fan-out to step targets with no merge back
+ * 5. DESIGN_EXIT_DATA_UNREACHABLE - Exit data port has no connection and no pull-execution provider
+ * 6. DESIGN_PULL_CANDIDATE - Node with no incoming step but consumed data outputs
+ * 7. DESIGN_PULL_UNUSED - Node marked pullExecution but no downstream reads its output
+ */
+import type { TValidationRule } from '../ast/types.js';
+/**
+ * Async nodes (network, disk, AI) can fail. If onFailure is unconnected,
+ * failures may be silently swallowed or crash the workflow.
+ */
+export declare const asyncNoErrorPathRule: TValidationRule;
+/**
+ * A scope (retry/forEach) with no failure path out means if every iteration
+ * fails, execution stalls with no way to surface the error.
+ */
+export declare const scopeNoFailureExitRule: TValidationRule;
+/**
+ * A scope used as a retry loop without a visible attempt limit could loop
+ * indefinitely. Check if the parent node type name/function suggests retry
+ * semantics but lacks a maxAttempts-like input or config.
+ */
+export declare const unboundedRetryRule: TValidationRule;
+/**
+ * A node that fans out via step connections to multiple targets, but none of
+ * those paths merge back to a shared downstream node. Data from parallel
+ * branches may be lost.
+ */
+export declare const fanoutNoFaninRule: TValidationRule;
+/**
+ * Extends UNREACHABLE_EXIT_PORT to consider pull execution. An exit data port
+ * is fine if a pull-executed node is wired to provide it, even without a
+ * step path.
+ */
+export declare const exitDataUnreachableRule: TValidationRule;
+/**
+ * A node with no incoming step connections but data outputs consumed downstream
+ * is a candidate for pullExecution. Without it, the node may never execute.
+ */
+export declare const pullCandidateRule: TValidationRule;
+/**
+ * A node marked with pullExecution but no downstream node reads its data output.
+ * The node will never execute since pull execution requires a consumer.
+ */
+export declare const pullUnusedRule: TValidationRule;
+export declare const designValidationRules: TValidationRule[];
+export declare function getDesignValidationRules(): TValidationRule[];
+//# sourceMappingURL=design-rules.d.ts.map

package/dist/validation/design-rules.js

@@ -0,0 +1,377 @@
+/**
+ * Design Quality Validation Rules
+ *
+ * Deterministic, AST-inspectable rules that catch common workflow design problems.
+ * A workflow can compile fine and still be poorly designed: missing error paths,
+ * unbounded retries, fan-out without fan-in, dead-end branches.
+ *
+ * All rules are warnings or info. None block compilation.
+ * Users can suppress any with @suppress.
+ *
+ * Rules:
+ * 1. DESIGN_ASYNC_NO_ERROR_PATH - Async node has no onFailure connection
+ * 2. DESIGN_SCOPE_NO_FAILURE_EXIT - Scope has no failure path out
+ * 3. DESIGN_UNBOUNDED_RETRY - Retry scope has no visible attempt limit
+ * 4. DESIGN_FANOUT_NO_FANIN - Fan-out to step targets with no merge back
+ * 5. DESIGN_EXIT_DATA_UNREACHABLE - Exit data port has no connection and no pull-execution provider
+ * 6. DESIGN_PULL_CANDIDATE - Node with no incoming step but consumed data outputs
+ * 7. DESIGN_PULL_UNUSED - Node marked pullExecution but no downstream reads its output
+ */
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+function resolveNodeType(ast, instance) {
+    return ast.nodeTypes.find((nt) => nt.name === instance.nodeType || nt.functionName === instance.nodeType);
+}
+function getOutgoing(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;
+    });
+}
+const STEP_PORTS = new Set(['execute', 'onSuccess', 'onFailure', 'start', 'success', 'failure']);
+function isStepPort(portName, portDef) {
+    if (portDef?.dataType === 'STEP')
+        return true;
+    return STEP_PORTS.has(portName);
+}
+// ---------------------------------------------------------------------------
+// Rule 1: Async Node Missing Error Path
+// ---------------------------------------------------------------------------
+/**
+ * Async nodes (network, disk, AI) can fail. If onFailure is unconnected,
+ * failures may be silently swallowed or crash the workflow.
+ */
+export const asyncNoErrorPathRule = {
+    name: 'DESIGN_ASYNC_NO_ERROR_PATH',
+    validate(ast) {
+        const errors = [];
+        for (const instance of ast.instances) {
+            const nt = resolveNodeType(ast, instance);
+            if (!nt)
+                continue;
+            if (!nt.isAsync)
+                continue;
+            if (!nt.hasFailurePort)
+                continue;
+            const failureConns = getOutgoing(ast, instance.id, 'onFailure');
+            if (failureConns.length === 0) {
+                errors.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 errors;
+    },
+};
+// ---------------------------------------------------------------------------
+// Rule 2: Scope With No Failure Exit
+// ---------------------------------------------------------------------------
+/**
+ * A scope (retry/forEach) with no failure path out means if every iteration
+ * fails, execution stalls with no way to surface the error.
+ */
+export const scopeNoFailureExitRule = {
+    name: 'DESIGN_SCOPE_NO_FAILURE_EXIT',
+    validate(ast) {
+        const errors = [];
+        for (const instance of ast.instances) {
+            const nt = resolveNodeType(ast, instance);
+            if (!nt)
+                continue;
+            // Only check nodes that define scopes
+            const scopeNames = nt.scopes ?? (nt.scope ? [nt.scope] : []);
+            if (scopeNames.length === 0)
+                continue;
+            // A scope parent needs an onFailure or failure port connected
+            if (!nt.hasFailurePort)
+                continue;
+            const failureConns = getOutgoing(ast, instance.id, 'onFailure');
+            // Also check 'failure' port used in some scope patterns
+            const failureConns2 = getOutgoing(ast, instance.id, 'failure');
+            if (failureConns.length === 0 && failureConns2.length === 0) {
+                errors.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 errors;
+    },
+};
+// ---------------------------------------------------------------------------
+// Rule 3: Unbounded Retry
+// ---------------------------------------------------------------------------
+/**
+ * A scope used as a retry loop without a visible attempt limit could loop
+ * indefinitely. Check if the parent node type name/function suggests retry
+ * semantics but lacks a maxAttempts-like input or config.
+ */
+export const unboundedRetryRule = {
+    name: 'DESIGN_UNBOUNDED_RETRY',
+    validate(ast) {
+        const errors = [];
+        const retryPatterns = /retry|repeat|loop|poll|backoff/i;
+        for (const instance of ast.instances) {
+            const nt = resolveNodeType(ast, instance);
+            if (!nt)
+                continue;
+            const scopeNames = nt.scopes ?? (nt.scope ? [nt.scope] : []);
+            if (scopeNames.length === 0)
+                continue;
+            // Only flag nodes that look like retry patterns
+            const nameHint = `${nt.name} ${nt.functionName} ${nt.label ?? ''}`;
+            if (!retryPatterns.test(nameHint))
+                continue;
+            // Check for a maxAttempts/retries/limit input port
+            const limitInputs = Object.keys(nt.inputs).filter((p) => /max|limit|attempts|retries|count/i.test(p));
+            if (limitInputs.length === 0) {
+                errors.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 errors;
+    },
+};
+// ---------------------------------------------------------------------------
+// Rule 4: Fan-Out Without Fan-In
+// ---------------------------------------------------------------------------
+/**
+ * A node that fans out via step connections to multiple targets, but none of
+ * those paths merge back to a shared downstream node. Data from parallel
+ * branches may be lost.
+ */
+export const fanoutNoFaninRule = {
+    name: 'DESIGN_FANOUT_NO_FANIN',
+    validate(ast) {
+        const errors = [];
+        for (const instance of ast.instances) {
+            const nt = resolveNodeType(ast, instance);
+            // Find step output connections (excluding data ports)
+            const stepOutConns = getOutgoing(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);
+            });
+            // Get unique step targets (excluding Exit, which is a natural terminus)
+            const stepTargets = [...new Set(stepOutConns.map((c) => c.to.node))].filter((n) => n !== 'Exit');
+            // Need at least 3 targets to be a meaningful fan-out (2 is just success/failure branching)
+            if (stepTargets.length < 3)
+                continue;
+            // For each target, walk forward to find all reachable nodes
+            const reachableSets = stepTargets.map((target) => getReachableNodes(ast, target));
+            // Check if any node appears in multiple reachable sets (fan-in point)
+            const allNodes = 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);
+                }
+            }
+            // Also check if any target has a merge strategy on its input ports
+            if (!hasMerge) {
+                for (const target of stepTargets) {
+                    const targetInst = ast.instances.find((i) => i.id === target);
+                    if (!targetInst)
+                        continue;
+                    const targetNt = resolveNodeType(ast, targetInst);
+                    if (!targetNt)
+                        continue;
+                    const hasMergePort = Object.values(targetNt.inputs).some((p) => p.mergeStrategy);
+                    if (hasMergePort) {
+                        hasMerge = true;
+                        break;
+                    }
+                }
+            }
+            if (!hasMerge) {
+                errors.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 errors;
+    },
+};
+/** Walk forward from a node to find all reachable nodes (BFS via step connections). */
+function getReachableNodes(ast, startNode) {
+    const visited = new Set();
+    const queue = [startNode];
+    while (queue.length > 0) {
+        const current = queue.shift();
+        if (visited.has(current))
+            continue;
+        visited.add(current);
+        for (const conn of ast.connections) {
+            if (conn.from.node === current && !visited.has(conn.to.node)) {
+                queue.push(conn.to.node);
+            }
+        }
+    }
+    return visited;
+}
+// ---------------------------------------------------------------------------
+// Rule 5: Exit Data Port Unreachable (Pull-Execution Aware)
+// ---------------------------------------------------------------------------
+/**
+ * Extends UNREACHABLE_EXIT_PORT to consider pull execution. An exit data port
+ * is fine if a pull-executed node is wired to provide it, even without a
+ * step path.
+ */
+export const exitDataUnreachableRule = {
+    name: 'DESIGN_EXIT_DATA_UNREACHABLE',
+    validate(ast) {
+        const errors = [];
+        const stepPorts = new Set(['onSuccess', 'onFailure']);
+        for (const [portName, portDef] of Object.entries(ast.exitPorts)) {
+            if (portDef.dataType === 'STEP')
+                continue; // Step ports handled by core validator
+            const incoming = getIncoming(ast, 'Exit', portName);
+            if (incoming.length > 0)
+                continue; // Has a direct connection, fine
+            // Check if a pull-executed node provides this port
+            const hasPullProvider = ast.instances.some((inst) => {
+                const isPull = inst.config?.pullExecution ||
+                    resolveNodeType(ast, inst)?.defaultConfig?.pullExecution;
+                if (!isPull)
+                    return false;
+                // Check if this pull node has a data output connected to Exit.<portName>
+                return getOutgoing(ast, inst.id).some((c) => c.to.node === 'Exit' && c.to.port === portName);
+            });
+            if (!hasPullProvider) {
+                errors.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 errors;
+    },
+};
+// ---------------------------------------------------------------------------
+// Rule 6: Pull Execution Candidate
+// ---------------------------------------------------------------------------
+/**
+ * A node with no incoming step connections but data outputs consumed downstream
+ * is a candidate for pullExecution. Without it, the node may never execute.
+ */
+export const pullCandidateRule = {
+    name: 'DESIGN_PULL_CANDIDATE',
+    validate(ast) {
+        const errors = [];
+        for (const instance of ast.instances) {
+            const nt = resolveNodeType(ast, instance);
+            if (!nt)
+                continue;
+            // Skip if already has pullExecution configured
+            if (instance.config?.pullExecution || nt.defaultConfig?.pullExecution)
+                continue;
+            // Skip expression nodes (they are already pull-executed by nature)
+            if (nt.expression)
+                continue;
+            // Check for incoming step connections
+            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; // Has step trigger, not a candidate
+            // Check if any data outputs are consumed downstream
+            const dataOutputs = Object.keys(nt.outputs).filter((p) => !STEP_PORTS.has(p));
+            const hasConsumedOutput = dataOutputs.some((port) => getOutgoing(ast, instance.id, port).length > 0);
+            if (hasConsumedOutput) {
+                errors.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 errors;
+    },
+};
+// ---------------------------------------------------------------------------
+// Rule 7: Unused Pull Execution
+// ---------------------------------------------------------------------------
+/**
+ * A node marked with pullExecution but no downstream node reads its data output.
+ * The node will never execute since pull execution requires a consumer.
+ */
+export const pullUnusedRule = {
+    name: 'DESIGN_PULL_UNUSED',
+    validate(ast) {
+        const errors = [];
+        for (const instance of ast.instances) {
+            const nt = resolveNodeType(ast, instance);
+            if (!nt)
+                continue;
+            const isPull = instance.config?.pullExecution || nt.defaultConfig?.pullExecution;
+            if (!isPull)
+                continue;
+            // Check if any data output ports are connected
+            const dataOutputs = Object.keys(nt.outputs).filter((p) => !STEP_PORTS.has(p));
+            const hasConnectedOutput = dataOutputs.some((port) => getOutgoing(ast, instance.id, port).length > 0);
+            if (!hasConnectedOutput) {
+                errors.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 errors;
+    },
+};
+// ---------------------------------------------------------------------------
+// Public API
+// ---------------------------------------------------------------------------
+export const designValidationRules = [
+    asyncNoErrorPathRule,
+    scopeNoFailureExitRule,
+    unboundedRetryRule,
+    fanoutNoFaninRule,
+    exitDataUnreachableRule,
+    pullCandidateRule,
+    pullUnusedRule,
+];
+export function getDesignValidationRules() {
+    return designValidationRules;
+}
+//# sourceMappingURL=design-rules.js.map

package/docs/reference/error-codes.md

@@ -631,6 +631,73 @@ These codes apply to AI agent workflows that use LLM, tool-executor, and memory
 >
 > **What to do:** Connect the tool executor's data output ports (e.g., `result`) to downstream nodes that consume the data.
 
+### Design Quality Rules
+
+These rules detect common workflow design problems that compile fine but indicate poor structure. All are warnings or info-level, suppressible with `@suppress`.
+
+#### DESIGN_ASYNC_NO_ERROR_PATH (warning)
+
+| Field         | Value                                                                                                                                                         |
+| ------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Severity      | Warning                                                                                                                                                       |
+| Meaning       | An async node has no onFailure connection. Async operations (network calls, file I/O, AI calls) can fail, and errors will be silently lost.                  |
+| Common Causes | Adding an async node and connecting onSuccess but forgetting to wire onFailure.                                                                              |
+| Fix           | Connect the node's `onFailure` port to an error handler, retry node, or `Exit.onFailure`.                                                                   |
+
+#### DESIGN_SCOPE_NO_FAILURE_EXIT (warning)
+
+| Field         | Value                                                                                                                                                         |
+| ------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Severity      | Warning                                                                                                                                                       |
+| Meaning       | A scope node (retry/forEach) has no failure path out. If all iterations fail, execution stalls with no error surfaced upstream.                               |
+| Common Causes | Creating a forEach or retry scope and only wiring the success path.                                                                                          |
+| Fix           | Connect the scope node's `onFailure` port to propagate errors.                                                                                               |
+
+#### DESIGN_UNBOUNDED_RETRY (warning)
+
+| Field         | Value                                                                                                                                                         |
+| ------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Severity      | Warning                                                                                                                                                       |
+| Meaning       | A scope node with retry/loop semantics (detected by name) has no visible attempt limit input. This could loop indefinitely on persistent failures.            |
+| Common Causes | Creating a custom retry loop without a maxAttempts or retries parameter.                                                                                     |
+| Fix           | Add a `maxAttempts` or `retries` input port to the node type, or use a counter to break out.                                                                 |
+
+#### DESIGN_FANOUT_NO_FANIN (warning)
+
+| Field         | Value                                                                                                                                                         |
+| ------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Severity      | Warning                                                                                                                                                       |
+| Meaning       | A node fans out to 3+ step targets, but those paths never converge to a shared downstream node. Data from parallel branches may be lost.                     |
+| Common Causes | Dispatching work to multiple parallel branches without a merge point before Exit.                                                                             |
+| Fix           | Add a merge node downstream where parallel branches converge, or use a merge strategy on the target port.                                                    |
+
+#### DESIGN_EXIT_DATA_UNREACHABLE (warning)
+
+| Field         | Value                                                                                                                                                         |
+| ------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Severity      | Warning                                                                                                                                                       |
+| Meaning       | An Exit data port has no incoming connection and no pull-execution node provides it. Extends UNREACHABLE_EXIT_PORT with pull-execution awareness.             |
+| Common Causes | Declaring an exit port but never connecting any node output to it, and no pull-execution node wires to it.                                                   |
+| Fix           | Connect a node's data output to the Exit port, or add a pull-execution node that computes the value on demand.                                               |
+
+#### DESIGN_PULL_CANDIDATE (warning)
+
+| Field         | Value                                                                                                                                                         |
+| ------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Severity      | Warning                                                                                                                                                       |
+| Meaning       | A node has no incoming step connection but its data outputs are consumed downstream. Without pullExecution, the node may never execute.                       |
+| Common Causes | Adding a node and connecting its data outputs to downstream nodes but forgetting a step trigger or pullExecution config.                                      |
+| Fix           | Add `[pullExecution: execute]` to the `@node` annotation so the node runs on demand.                                                                        |
+
+#### DESIGN_PULL_UNUSED (warning)
+
+| Field         | Value                                                                                                                                                         |
+| ------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Severity      | Warning                                                                                                                                                       |
+| Meaning       | A node is marked with pullExecution but no downstream node reads its data output. Pull execution requires a consumer to trigger.                              |
+| Common Causes | Setting pullExecution on a node but then not connecting any of its data outputs.                                                                              |
+| Fix           | Connect a data output to a downstream node, or remove the pullExecution config if the node isn't needed.                                                     |
+
 ---
 
 ## Quick Reference: Error Severity Summary
@@ -690,4 +757,11 @@ These codes apply to AI agent workflows that use LLM, tool-executor, and memory
 | AGENT_MISSING_MEMORY_IN_LOOP | Loop has LLM but no conversation memory node |
 | AGENT_LLM_NO_FALLBACK | LLM onFailure routes directly to Exit |
 | AGENT_TOOL_NO_OUTPUT_HANDLING | Tool executor data outputs all unconnected |
+| DESIGN_ASYNC_NO_ERROR_PATH | Async node has no onFailure connection |
+| DESIGN_SCOPE_NO_FAILURE_EXIT | Scope node has no failure path out |
+| DESIGN_UNBOUNDED_RETRY | Retry scope has no visible attempt limit |
+| DESIGN_FANOUT_NO_FANIN | Fan-out to multiple step targets with no merge back |
+| DESIGN_EXIT_DATA_UNREACHABLE | Exit data port has no connection and no pull-execution provider |
+| DESIGN_PULL_CANDIDATE | Node has no step trigger but its outputs are consumed downstream |
+| DESIGN_PULL_UNUSED | Pull-execution node has no downstream consumers |
 <!-- AUTO:END warning_summary_table -->

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@synergenius/flow-weaver",
-  "version": "0.20.5",
+  "version": "0.20.6",
   "description": "Deterministic workflow compiler for AI agents. Compiles to standalone TypeScript, no runtime dependencies.",
   "private": false,
   "type": "module",