@synergenius/flow-weaver 0.10.1 → 0.10.3

package/README.md

@@ -1,8 +1,12 @@
 # @synergenius/flow-weaver
 
-[![npm version](https://img.shields.io/npm/v/@synergenius/flow-weaver.svg)](https://www.npmjs.com/package/@synergenius/flow-weaver)
-[![License: Flow Weaver Library License](https://img.shields.io/badge/License-Flow%20Weaver%20Library-blue.svg)](./LICENSE)
-[![Node.js](https://img.shields.io/badge/Node.js-%3E%3D18-green.svg)](https://nodejs.org)
+[![npm version](https://img.shields.io/npm/v/@synergenius/flow-weaver?style=flat)](https://www.npmjs.com/package/@synergenius/flow-weaver)
+[![npm downloads](https://img.shields.io/npm/dw/@synergenius/flow-weaver?style=flat)](https://www.npmjs.com/package/@synergenius/flow-weaver)
+[![CI](https://img.shields.io/github/actions/workflow/status/synergenius-fw/flow-weaver/ci.yml?branch=main&style=flat)](https://github.com/synergenius-fw/flow-weaver/actions/workflows/ci.yml)
+[![Tests](https://img.shields.io/endpoint?url=https://gist.githubusercontent.com/moraispgsi/305430ef59a51d0a58eb61fefdfbe634/raw/flow-weaver-test-count.json&style=flat)](https://github.com/synergenius-fw/flow-weaver/actions/workflows/ci.yml)
+[![Coverage](https://img.shields.io/codecov/c/github/synergenius-fw/flow-weaver?style=flat)](https://codecov.io/gh/synergenius-fw/flow-weaver)
+[![License: Flow Weaver Library License](https://img.shields.io/badge/License-Flow%20Weaver%20Library-blue?style=flat)](./LICENSE)
+[![Node.js](https://img.shields.io/badge/Node.js-%3E%3D18-green?style=flat)](https://nodejs.org)
 
 **Build AI agent workflows visually. Ship them as your own code.**
 

package/dist/ast/types.d.ts

@@ -459,6 +459,8 @@ export type TConnectionAST = {
     metadata?: TConnectionMetadata;
     /** Pre-computed type compatibility (set during parsing when ts-morph Types are available) */
     typeCompatibility?: TTypeCompatibility;
+    /** Explicit type coercion for this connection (e.g., 'number' wraps value with Number()) */
+    coerce?: TCoerceTargetType;
 };
 /**
  * Port Reference - Identifies a specific port on a node.

package/dist/chevrotain-parser/connect-parser.d.ts

@@ -3,6 +3,7 @@
  *
  * Parser for @connect declarations using Chevrotain.
  */
+import type { TCoerceTargetType } from '../ast/types.js';
 export interface PortReference {
     nodeId: string;
     portName: string;
@@ -11,6 +12,10 @@ export interface PortReference {
 export interface ConnectParseResult {
     source: PortReference;
     target: PortReference;
+    /** Explicit type coercion (from `as <type>` suffix) */
+    coerce?: TCoerceTargetType;
+    /** Set when `as <type>` uses an unrecognized type (cleared after warning is emitted) */
+    invalidCoerceType?: string;
 }
 /**
  * Parse a @connect line and return structured result.

package/dist/chevrotain-parser/connect-parser.js

@@ -4,7 +4,7 @@
  * Parser for @connect declarations using Chevrotain.
  */
 import { CstParser } from 'chevrotain';
-import { JSDocLexer, ConnectTag, Identifier, Arrow, Dot, Colon, allTokens } from './tokens.js';
+import { JSDocLexer, ConnectTag, Identifier, Arrow, Dot, Colon, AsKeyword, allTokens } from './tokens.js';
 // =============================================================================
 // Parser Definition
 // =============================================================================
@@ -13,12 +13,16 @@ class ConnectParser extends CstParser {
         super(allTokens);
         this.performSelfAnalysis();
     }
-    // Entry rule for connect line
+    // Entry rule for connect line: @connect A.port -> B.port [as type]
     connectLine = this.RULE('connectLine', () => {
         this.CONSUME(ConnectTag);
         this.SUBRULE(this.portRef, { LABEL: 'sourceRef' });
         this.CONSUME(Arrow);
         this.SUBRULE2(this.portRef, { LABEL: 'targetRef' });
+        this.OPTION(() => {
+            this.CONSUME(AsKeyword);
+            this.CONSUME(Identifier, { LABEL: 'coerceType' });
+        });
     });
     // node.port or node.port:scope
     portRef = this.RULE('portRef', () => {
@@ -47,7 +51,18 @@ class ConnectVisitor extends BaseVisitor {
     connectLine(ctx) {
         const source = this.visit(ctx.sourceRef);
         const target = this.visit(ctx.targetRef);
-        return { source, target };
+        const result = { source, target };
+        if (ctx.coerceType?.[0]) {
+            const validTypes = new Set(['string', 'number', 'boolean', 'json', 'object']);
+            const raw = ctx.coerceType[0].image;
+            if (validTypes.has(raw)) {
+                result.coerce = raw;
+            }
+            else {
+                result.invalidCoerceType = raw;
+            }
+        }
+        return result;
     }
     portRef(ctx) {
         const nodeId = ctx.nodeId[0].image;
@@ -87,7 +102,12 @@ export function parseConnectLine(input, warnings) {
             `  Expected format: @connect sourceNode.port -> targetNode.port`);
         return null;
     }
-    return visitorInstance.visit(cst);
+    const result = visitorInstance.visit(cst);
+    if (result.invalidCoerceType) {
+        warnings.push(`Invalid coerce type "${result.invalidCoerceType}" in @connect. Valid types: string, number, boolean, json, object`);
+        delete result.invalidCoerceType;
+    }
+    return result;
 }
 /**
  * Get serialized grammar for documentation/diagram generation.

package/dist/cli/flow-weaver.mjs

@@ -12263,7 +12263,21 @@ var init_theme = __esm({
 });
 
 // src/validator.ts
-var DOCS_BASE, ERROR_DOC_URLS, WorkflowValidator, validator;
+function suggestCoerceType(targetType) {
+  switch (targetType) {
+    case "STRING":
+      return "string";
+    case "NUMBER":
+      return "number";
+    case "BOOLEAN":
+      return "boolean";
+    case "OBJECT":
+      return "object";
+    default:
+      return "<type>";
+  }
+}
+var DOCS_BASE, ERROR_DOC_URLS, COERCE_OUTPUT_TYPE, WorkflowValidator, validator;
 var init_validator = __esm({
   "src/validator.ts"() {
     "use strict";
@@ -12284,7 +12298,17 @@ var init_validator = __esm({
       MISSING_EXIT_CONNECTION: `${DOCS_BASE}/concepts#start-and-exit`,
       INFERRED_NODE_TYPE: `${DOCS_BASE}/node-conversion`,
       DUPLICATE_CONNECTION: `${DOCS_BASE}/concepts#connections`,
-      STUB_NODE: `${DOCS_BASE}/model-driven#stub-nodes`
+      STUB_NODE: `${DOCS_BASE}/model-driven#stub-nodes`,
+      COERCE_TYPE_MISMATCH: `${DOCS_BASE}/compilation#type-coercion`,
+      REDUNDANT_COERCE: `${DOCS_BASE}/compilation#type-coercion`,
+      COERCE_ON_FUNCTION_PORT: `${DOCS_BASE}/compilation#type-coercion`
+    };
+    COERCE_OUTPUT_TYPE = {
+      string: "STRING",
+      number: "NUMBER",
+      boolean: "BOOLEAN",
+      json: "STRING",
+      object: "OBJECT"
     };
     WorkflowValidator = class {
       errors = [];
@@ -12710,7 +12734,27 @@ Add '@param ${fromPort}' to the workflow JSDoc and include it in the params obje
           if (sourceType === "STEP" && targetType === "STEP") {
             return;
           }
+          if (conn.coerce && (sourceType === "FUNCTION" || targetType === "FUNCTION")) {
+            this.errors.push({
+              type: "error",
+              code: "COERCE_ON_FUNCTION_PORT",
+              message: `Coercion \`as ${conn.coerce}\` cannot be used on FUNCTION ports in connection "${fromNode}.${fromPort}" \u2192 "${toNode}.${toPort}". FUNCTION values cannot be meaningfully coerced.`,
+              connection: conn,
+              location: connLocation
+            });
+            return;
+          }
           if (sourceType === targetType) {
+            if (conn.coerce) {
+              this.warnings.push({
+                type: "warning",
+                code: "REDUNDANT_COERCE",
+                message: `Coercion \`as ${conn.coerce}\` on connection "${fromNode}.${fromPort}" \u2192 "${toNode}.${toPort}" is redundant \u2014 source and target are both ${sourceType}.`,
+                connection: conn,
+                location: connLocation
+              });
+              return;
+            }
             if (sourceType === "OBJECT" && sourcePortDef.tsType && targetPortDef.tsType) {
               const normalizedSource = this.normalizeTypeString(sourcePortDef.tsType);
               const normalizedTarget = this.normalizeTypeString(targetPortDef.tsType);
@@ -12732,6 +12776,23 @@ Add '@param ${fromPort}' to the workflow JSDoc and include it in the params obje
           if (sourceType === "ANY" || targetType === "ANY") {
             return;
           }
+          if (conn.coerce) {
+            const producedType = COERCE_OUTPUT_TYPE[conn.coerce];
+            if (producedType === targetType) {
+              return;
+            }
+            pushTypeIssue(
+              {
+                type: "warning",
+                code: "COERCE_TYPE_MISMATCH",
+                message: `Coercion \`as ${conn.coerce}\` produces ${producedType} but target port "${toPort}" on "${toNode}" expects ${targetType}. Use \`as ${suggestCoerceType(targetType)}\` instead.`,
+                connection: conn,
+                location: connLocation
+              },
+              true
+            );
+            return;
+          }
           const safeCoercions = [
             ["NUMBER", "STRING"],
             ["BOOLEAN", "STRING"]
@@ -16881,6 +16942,121 @@ var require_browser = __commonJS({
   }
 });
 
+// node_modules/has-flag/index.js
+var require_has_flag = __commonJS({
+  "node_modules/has-flag/index.js"(exports2, module2) {
+    "use strict";
+    module2.exports = (flag, argv = process.argv) => {
+      const prefix = flag.startsWith("-") ? "" : flag.length === 1 ? "-" : "--";
+      const position = argv.indexOf(prefix + flag);
+      const terminatorPosition = argv.indexOf("--");
+      return position !== -1 && (terminatorPosition === -1 || position < terminatorPosition);
+    };
+  }
+});
+
+// node_modules/supports-color/index.js
+var require_supports_color = __commonJS({
+  "node_modules/supports-color/index.js"(exports2, module2) {
+    "use strict";
+    var os3 = __require("os");
+    var tty = __require("tty");
+    var hasFlag = require_has_flag();
+    var { env } = process;
+    var forceColor;
+    if (hasFlag("no-color") || hasFlag("no-colors") || hasFlag("color=false") || hasFlag("color=never")) {
+      forceColor = 0;
+    } else if (hasFlag("color") || hasFlag("colors") || hasFlag("color=true") || hasFlag("color=always")) {
+      forceColor = 1;
+    }
+    if ("FORCE_COLOR" in env) {
+      if (env.FORCE_COLOR === "true") {
+        forceColor = 1;
+      } else if (env.FORCE_COLOR === "false") {
+        forceColor = 0;
+      } else {
+        forceColor = env.FORCE_COLOR.length === 0 ? 1 : Math.min(parseInt(env.FORCE_COLOR, 10), 3);
+      }
+    }
+    function translateLevel(level) {
+      if (level === 0) {
+        return false;
+      }
+      return {
+        level,
+        hasBasic: true,
+        has256: level >= 2,
+        has16m: level >= 3
+      };
+    }
+    function supportsColor(haveStream, streamIsTTY) {
+      if (forceColor === 0) {
+        return 0;
+      }
+      if (hasFlag("color=16m") || hasFlag("color=full") || hasFlag("color=truecolor")) {
+        return 3;
+      }
+      if (hasFlag("color=256")) {
+        return 2;
+      }
+      if (haveStream && !streamIsTTY && forceColor === void 0) {
+        return 0;
+      }
+      const min = forceColor || 0;
+      if (env.TERM === "dumb") {
+        return min;
+      }
+      if (process.platform === "win32") {
+        const osRelease = os3.release().split(".");
+        if (Number(osRelease[0]) >= 10 && Number(osRelease[2]) >= 10586) {
+          return Number(osRelease[2]) >= 14931 ? 3 : 2;
+        }
+        return 1;
+      }
+      if ("CI" in env) {
+        if (["TRAVIS", "CIRCLECI", "APPVEYOR", "GITLAB_CI", "GITHUB_ACTIONS", "BUILDKITE"].some((sign) => sign in env) || env.CI_NAME === "codeship") {
+          return 1;
+        }
+        return min;
+      }
+      if ("TEAMCITY_VERSION" in env) {
+        return /^(9\.(0*[1-9]\d*)\.|\d{2,}\.)/.test(env.TEAMCITY_VERSION) ? 1 : 0;
+      }
+      if (env.COLORTERM === "truecolor") {
+        return 3;
+      }
+      if ("TERM_PROGRAM" in env) {
+        const version3 = parseInt((env.TERM_PROGRAM_VERSION || "").split(".")[0], 10);
+        switch (env.TERM_PROGRAM) {
+          case "iTerm.app":
+            return version3 >= 3 ? 3 : 2;
+          case "Apple_Terminal":
+            return 2;
+        }
+      }
+      if (/-256(color)?$/i.test(env.TERM)) {
+        return 2;
+      }
+      if (/^screen|^xterm|^vt100|^vt220|^rxvt|color|ansi|cygwin|linux/i.test(env.TERM)) {
+        return 1;
+      }
+      if ("COLORTERM" in env) {
+        return 1;
+      }
+      return min;
+    }
+    function getSupportLevel(stream2) {
+      const level = supportsColor(stream2, stream2 && stream2.isTTY);
+      return translateLevel(level);
+    }
+    module2.exports = {
+      supportsColor: getSupportLevel,
+      stdout: translateLevel(supportsColor(true, tty.isatty(1))),
+      stderr: translateLevel(supportsColor(true, tty.isatty(2)))
+    };
+  }
+});
+
 // node_modules/debug/src/node.js
 var require_node = __commonJS({
   "node_modules/debug/src/node.js"(exports2, module2) {
@@ -16899,7 +17075,7 @@ var require_node = __commonJS({
     );
     exports2.colors = [6, 2, 3, 4, 5, 1];
     try {
-      const supportsColor = __require("supports-color");
+      const supportsColor = require_supports_color();
       if (supportsColor && (supportsColor.stderr || supportsColor).level >= 2) {
         exports2.colors = [
           20,
@@ -28049,6 +28225,43 @@ function generateScopeFunctionClosure(scopeName, parentNodeId, parentNodeType, w
 
 // src/generator/code-utils.ts
 init_type_mappings();
+var COERCION_EXPRESSIONS = {
+  string: "String",
+  number: "Number",
+  boolean: "Boolean",
+  json: "JSON.stringify",
+  object: "JSON.parse"
+};
+function resolveSourcePortDataType(workflow, sourceNodeId, sourcePort) {
+  if (isStartNode(sourceNodeId)) {
+    return workflow.startPorts?.[sourcePort]?.dataType;
+  }
+  if (isExitNode(sourceNodeId)) {
+    return workflow.exitPorts?.[sourcePort]?.dataType;
+  }
+  const instance = workflow.instances.find((i) => i.id === sourceNodeId);
+  if (!instance) return void 0;
+  const nodeType = workflow.nodeTypes.find(
+    (nt) => nt.name === instance.nodeType || nt.functionName === instance.nodeType
+  );
+  if (!nodeType) return void 0;
+  return nodeType.outputs?.[sourcePort]?.dataType;
+}
+function getCoercionWrapper(connection, sourceDataType, targetDataType) {
+  if (connection.coerce) {
+    return COERCION_EXPRESSIONS[connection.coerce];
+  }
+  if (!sourceDataType || !targetDataType || sourceDataType === targetDataType) return null;
+  if (sourceDataType === "STEP" || targetDataType === "STEP") return null;
+  if (sourceDataType === "ANY" || targetDataType === "ANY") return null;
+  if (targetDataType === "STRING" && sourceDataType !== "STRING") {
+    return "String";
+  }
+  if (sourceDataType === "BOOLEAN" && targetDataType === "NUMBER") {
+    return "Number";
+  }
+  return null;
+}
 function toValidIdentifier(nodeId) {
   let sanitized = nodeId.replace(/[^a-zA-Z0-9_$]/g, "_");
   if (/^[0-9]/.test(sanitized)) {
@@ -28178,9 +28391,18 @@ function buildNodeArgumentsWithContext(opts) {
             `${indent}const ${varName} = ${varName}_resolved.fn as ${portType};`
           );
         } else {
-          lines.push(
-            `${indent}const ${varName} = ${getCall}({ id: '${sourceNode}', portName: '${sourcePort}', executionIndex: ${sourceIdx}${nonNullAssert} }) as ${portType};`
-          );
+          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) {
+            lines.push(
+              `${indent}const ${varName} = ${coerceExpr}(${getExpr}) as ${portType};`
+            );
+          } else {
+            lines.push(
+              `${indent}const ${varName} = ${getExpr} as ${portType};`
+            );
+          }
         }
       } else {
         const validConnections = connections.filter((conn) => {
@@ -28194,13 +28416,19 @@ function buildNodeArgumentsWithContext(opts) {
           return;
         }
         const attempts = [];
-        validConnections.forEach((conn, _idx) => {
+        validConnections.forEach((conn) => {
           const sourceNode = conn.from.node;
           const sourcePort = conn.from.port;
           const sourceIdx = isStartNode(sourceNode) ? "startIdx" : `${toValidIdentifier(sourceNode)}Idx`;
-          attempts.push(
-            `(${sourceIdx} !== undefined ? ${getCall}({ id: '${sourceNode}', portName: '${sourcePort}', executionIndex: ${sourceIdx} }) : undefined)`
-          );
+          const getExpr = `${getCall}({ id: '${sourceNode}', portName: '${sourcePort}', executionIndex: ${sourceIdx} })`;
+          if (portConfig.dataType !== "FUNCTION") {
+            const sourceDataType = resolveSourcePortDataType(workflow, sourceNode, sourcePort);
+            const coerceExpr = getCoercionWrapper(conn, sourceDataType, portConfig.dataType);
+            const wrapped = coerceExpr ? `${coerceExpr}(${getExpr})` : getExpr;
+            attempts.push(`(${sourceIdx} !== undefined ? ${wrapped} : undefined)`);
+          } else {
+            attempts.push(`(${sourceIdx} !== undefined ? ${getExpr} : undefined)`);
+          }
         });
         const ternary = attempts.join(" ?? ");
         const portType = mapToTypeScript(portConfig.dataType, portConfig.tsType);
@@ -43430,12 +43658,16 @@ var ConnectParser = class extends CstParser {
     super(allTokens);
     this.performSelfAnalysis();
   }
-  // Entry rule for connect line
+  // Entry rule for connect line: @connect A.port -> B.port [as type]
   connectLine = this.RULE("connectLine", () => {
     this.CONSUME(ConnectTag);
     this.SUBRULE(this.portRef, { LABEL: "sourceRef" });
     this.CONSUME(Arrow);
     this.SUBRULE2(this.portRef, { LABEL: "targetRef" });
+    this.OPTION(() => {
+      this.CONSUME(AsKeyword);
+      this.CONSUME(Identifier, { LABEL: "coerceType" });
+    });
   });
   // node.port or node.port:scope
   portRef = this.RULE("portRef", () => {
@@ -43458,7 +43690,17 @@ var ConnectVisitor = class extends BaseVisitor3 {
   connectLine(ctx) {
     const source = this.visit(ctx.sourceRef);
     const target = this.visit(ctx.targetRef);
-    return { source, target };
+    const result = { source, target };
+    if (ctx.coerceType?.[0]) {
+      const validTypes = /* @__PURE__ */ new Set(["string", "number", "boolean", "json", "object"]);
+      const raw = ctx.coerceType[0].image;
+      if (validTypes.has(raw)) {
+        result.coerce = raw;
+      } else {
+        result.invalidCoerceType = raw;
+      }
+    }
+    return result;
   }
   portRef(ctx) {
     const nodeId = ctx.nodeId[0].image;
@@ -43492,7 +43734,14 @@ function parseConnectLine(input, warnings) {
     );
     return null;
   }
-  return visitorInstance3.visit(cst);
+  const result = visitorInstance3.visit(cst);
+  if (result.invalidCoerceType) {
+    warnings.push(
+      `Invalid coerce type "${result.invalidCoerceType}" in @connect. Valid types: string, number, boolean, json, object`
+    );
+    delete result.invalidCoerceType;
+  }
+  return result;
 }
 function getConnectGrammar() {
   return parserInstance3.getSerializedGastProductions();
@@ -45192,7 +45441,7 @@ var JSDocParser = class {
       warnings.push(`Invalid @connect tag format: @connect ${comment}`);
       return;
     }
-    const { source, target } = result;
+    const { source, target, coerce: coerce2 } = result;
     const line = tag.getStartLineNumber();
     config2.connections.push({
       from: {
@@ -45205,7 +45454,8 @@ var JSDocParser = class {
         port: target.portName,
         ...target.scope && { scope: target.scope }
       },
-      sourceLocation: { line, column: 0 }
+      sourceLocation: { line, column: 0 },
+      ...coerce2 && { coerce: coerce2 }
     });
   }
   /**
@@ -54170,6 +54420,41 @@ var errorMappers = {
       code: error2.code
     };
   },
+  COERCE_TYPE_MISMATCH(error2) {
+    const coerceMatch = error2.message.match(/`as (\w+)`/);
+    const coerceType = coerceMatch?.[1] || "unknown";
+    const expectsMatch = error2.message.match(/expects (\w+)/);
+    const expectedType = expectsMatch?.[1] || "unknown";
+    const suggestedType = COERCE_TARGET_TYPES[expectedType.toUpperCase()] || expectedType.toLowerCase();
+    return {
+      title: "Wrong Coercion Type",
+      explanation: `The \`as ${coerceType}\` coercion produces the wrong type for the target port. The target expects ${expectedType}.`,
+      fix: `Change \`as ${coerceType}\` to \`as ${suggestedType}\` in the @connect annotation.`,
+      code: error2.code
+    };
+  },
+  REDUNDANT_COERCE(error2) {
+    const coerceMatch = error2.message.match(/`as (\w+)`/);
+    const coerceType = coerceMatch?.[1] || "unknown";
+    const bothMatch = error2.message.match(/both (\w+)/);
+    const dataType = bothMatch?.[1] || "the same type";
+    return {
+      title: "Redundant Coercion",
+      explanation: `The \`as ${coerceType}\` coercion is unnecessary because both the source and target ports are already ${dataType}.`,
+      fix: `Remove \`as ${coerceType}\` from the @connect annotation \u2014 no coercion is needed.`,
+      code: error2.code
+    };
+  },
+  COERCE_ON_FUNCTION_PORT(error2) {
+    const coerceMatch = error2.message.match(/`as (\w+)`/);
+    const coerceType = coerceMatch?.[1] || "unknown";
+    return {
+      title: "Coercion on Function Port",
+      explanation: `The \`as ${coerceType}\` coercion cannot be applied to FUNCTION ports. Function values are callable references and cannot be meaningfully converted to other types.`,
+      fix: `Remove \`as ${coerceType}\` from the @connect annotation. If you need to convert the function's return value, add a transformation node.`,
+      code: error2.code
+    };
+  },
   LOSSY_TYPE_COERCION(error2) {
     const types2 = extractTypes(error2.message);
     const source = types2?.source || "unknown";
@@ -61065,12 +61350,12 @@ function renderConnection(parts2, conn, gradIndex) {
     `  <path d="${conn.path}" fill="none" stroke="url(#conn-grad-${gradIndex})" stroke-width="3"${dashAttr} stroke-linecap="round" data-source="${escapeXml(conn.fromNode)}.${escapeXml(conn.fromPort)}:output" data-target="${escapeXml(conn.toNode)}.${escapeXml(conn.toPort)}:input"/>`
   );
 }
-function renderScopeConnection(parts2, conn, allConnections) {
+function renderScopeConnection(parts2, conn, allConnections, parentNodeId) {
   const gradIndex = allConnections.indexOf(conn);
   if (gradIndex < 0) return;
   const dashAttr = conn.isStepConnection ? "" : ' stroke-dasharray="8 4"';
   parts2.push(
-    `    <path d="${conn.path}" fill="none" stroke="url(#conn-grad-${gradIndex})" stroke-width="2.5"${dashAttr} stroke-linecap="round" data-source="${escapeXml(conn.fromNode)}.${escapeXml(conn.fromPort)}:output" data-target="${escapeXml(conn.toNode)}.${escapeXml(conn.toPort)}:input"/>`
+    `    <path d="${conn.path}" fill="none" stroke="url(#conn-grad-${gradIndex})" stroke-width="2.5"${dashAttr} stroke-linecap="round" data-source="${escapeXml(conn.fromNode)}.${escapeXml(conn.fromPort)}:output" data-target="${escapeXml(conn.toNode)}.${escapeXml(conn.toPort)}:input" data-scope="${escapeXml(parentNodeId)}"/>`
   );
 }
 function renderNodeBody(parts2, node, theme, indent) {
@@ -61114,7 +61399,7 @@ function renderScopedContent(parts2, node, theme, themeName, allConnections) {
     `    <rect x="${scopeX}" y="${scopeY}" width="${scopeW}" height="${scopeH}" rx="4" fill="none" stroke="${theme.scopeAreaStroke}" stroke-width="1" stroke-dasharray="4 2" opacity="0.5"/>`
   );
   for (const conn of node.scopeConnections ?? []) {
-    renderScopeConnection(parts2, conn, allConnections);
+    renderScopeConnection(parts2, conn, allConnections, node.id);
   }
   if (scopePorts) {
     renderPortDots(parts2, node.id, scopePorts.inputs, scopePorts.outputs, themeName);
@@ -61662,7 +61947,7 @@ path[data-source].port-hover { opacity: 1; }
   var connIndex = [];
   content.querySelectorAll('path[data-source]').forEach(function(p) {
     var src = p.getAttribute('data-source'), tgt = p.getAttribute('data-target');
-    connIndex.push({ el: p, src: src, tgt: tgt, srcNode: src.split('.')[0], tgtNode: tgt.split('.')[0] });
+    connIndex.push({ el: p, src: src, tgt: tgt, srcNode: src.split('.')[0], tgtNode: tgt.split('.')[0], scopeOf: p.getAttribute('data-scope') || null });
   });
 
   // Snapshot of original port positions for reset
@@ -61704,9 +61989,18 @@ path[data-source].port-hover { opacity: 1; }
     off.dx += dx; off.dy += dy;
     var tr = 'translate(' + off.dx + ',' + off.dy + ')';
 
-    // Move node group
+    // Move node group (if nested inside a scoped parent, subtract parent offset)
     var nodeG = content.querySelector('.nodes [data-node-id="' + CSS.escape(nodeId) + '"]');
-    if (nodeG) nodeG.setAttribute('transform', tr);
+    if (nodeG) {
+      var parentNodeG = nodeG.parentElement ? nodeG.parentElement.closest('[data-node-id]') : null;
+      if (parentNodeG) {
+        var parentId = parentNodeG.getAttribute('data-node-id');
+        var parentOff = nodeOffsets[parentId] || { dx: 0, dy: 0 };
+        nodeG.setAttribute('transform', 'translate(' + (off.dx - parentOff.dx) + ',' + (off.dy - parentOff.dy) + ')');
+      } else {
+        nodeG.setAttribute('transform', tr);
+      }
+    }
 
     // Move label
     var labelG = content.querySelector('[data-label-for="' + CSS.escape(nodeId) + '"]');
@@ -61753,11 +62047,20 @@ path[data-source].port-hover { opacity: 1; }
       });
     }
 
-    // Recalculate affected connection paths
+    // Recalculate affected connection paths (skip scope connections when parent is dragged \u2014 they move with the group transform)
     connIndex.forEach(function(c) {
+      if (c.scopeOf === nodeId) return;
       if (c.srcNode === nodeId || c.tgtNode === nodeId) {
         var sp = portPositions[c.src], tp = portPositions[c.tgt];
-        if (sp && tp) c.el.setAttribute('d', computeConnectionPath(sp.cx, sp.cy, tp.cx, tp.cy));
+        if (sp && tp) {
+          if (c.scopeOf) {
+            // Scope connection paths live inside the parent group; use parent-local coords
+            var pOff = nodeOffsets[c.scopeOf] || { dx: 0, dy: 0 };
+            c.el.setAttribute('d', computeConnectionPath(sp.cx - pOff.dx, sp.cy - pOff.dy, tp.cx - pOff.dx, tp.cy - pOff.dy));
+          } else {
+            c.el.setAttribute('d', computeConnectionPath(sp.cx, sp.cy, tp.cx, tp.cy));
+          }
+        }
       }
       if (nodeG) {
         var children = nodeG.querySelectorAll(':scope > g[data-node-id]');
@@ -61765,7 +62068,14 @@ path[data-source].port-hover { opacity: 1; }
           var childId = childG.getAttribute('data-node-id');
           if (c.srcNode === childId || c.tgtNode === childId) {
             var sp = portPositions[c.src], tp = portPositions[c.tgt];
-            if (sp && tp) c.el.setAttribute('d', computeConnectionPath(sp.cx, sp.cy, tp.cx, tp.cy));
+            if (sp && tp) {
+              if (c.scopeOf) {
+                var pOff = nodeOffsets[c.scopeOf] || { dx: 0, dy: 0 };
+                c.el.setAttribute('d', computeConnectionPath(sp.cx - pOff.dx, sp.cy - pOff.dy, tp.cx - pOff.dx, tp.cy - pOff.dy));
+              } else {
+                c.el.setAttribute('d', computeConnectionPath(sp.cx, sp.cy, tp.cx, tp.cy));
+              }
+            }
           }
         });
       }
@@ -96590,7 +96900,7 @@ function displayInstalledPackage(pkg) {
 }
 
 // src/cli/index.ts
-var version2 = true ? "0.10.1" : "0.0.0-dev";
+var version2 = true ? "0.10.3" : "0.0.0-dev";
 var program2 = new Command();
 program2.name("flow-weaver").description("Flow Weaver Annotations - Compile and validate workflow files").version(version2, "-v, --version", "Output the current version");
 program2.configureOutput({

package/dist/diagram/html-viewer.js

@@ -481,7 +481,7 @@ path[data-source].port-hover { opacity: 1; }
   var connIndex = [];
   content.querySelectorAll('path[data-source]').forEach(function(p) {
     var src = p.getAttribute('data-source'), tgt = p.getAttribute('data-target');
-    connIndex.push({ el: p, src: src, tgt: tgt, srcNode: src.split('.')[0], tgtNode: tgt.split('.')[0] });
+    connIndex.push({ el: p, src: src, tgt: tgt, srcNode: src.split('.')[0], tgtNode: tgt.split('.')[0], scopeOf: p.getAttribute('data-scope') || null });
   });
 
   // Snapshot of original port positions for reset
@@ -523,9 +523,18 @@ path[data-source].port-hover { opacity: 1; }
     off.dx += dx; off.dy += dy;
     var tr = 'translate(' + off.dx + ',' + off.dy + ')';
 
-    // Move node group
+    // Move node group (if nested inside a scoped parent, subtract parent offset)
     var nodeG = content.querySelector('.nodes [data-node-id="' + CSS.escape(nodeId) + '"]');
-    if (nodeG) nodeG.setAttribute('transform', tr);
+    if (nodeG) {
+      var parentNodeG = nodeG.parentElement ? nodeG.parentElement.closest('[data-node-id]') : null;
+      if (parentNodeG) {
+        var parentId = parentNodeG.getAttribute('data-node-id');
+        var parentOff = nodeOffsets[parentId] || { dx: 0, dy: 0 };
+        nodeG.setAttribute('transform', 'translate(' + (off.dx - parentOff.dx) + ',' + (off.dy - parentOff.dy) + ')');
+      } else {
+        nodeG.setAttribute('transform', tr);
+      }
+    }
 
     // Move label
     var labelG = content.querySelector('[data-label-for="' + CSS.escape(nodeId) + '"]');
@@ -572,11 +581,20 @@ path[data-source].port-hover { opacity: 1; }
       });
     }
 
-    // Recalculate affected connection paths
+    // Recalculate affected connection paths (skip scope connections when parent is dragged — they move with the group transform)
     connIndex.forEach(function(c) {
+      if (c.scopeOf === nodeId) return;
       if (c.srcNode === nodeId || c.tgtNode === nodeId) {
         var sp = portPositions[c.src], tp = portPositions[c.tgt];
-        if (sp && tp) c.el.setAttribute('d', computeConnectionPath(sp.cx, sp.cy, tp.cx, tp.cy));
+        if (sp && tp) {
+          if (c.scopeOf) {
+            // Scope connection paths live inside the parent group; use parent-local coords
+            var pOff = nodeOffsets[c.scopeOf] || { dx: 0, dy: 0 };
+            c.el.setAttribute('d', computeConnectionPath(sp.cx - pOff.dx, sp.cy - pOff.dy, tp.cx - pOff.dx, tp.cy - pOff.dy));
+          } else {
+            c.el.setAttribute('d', computeConnectionPath(sp.cx, sp.cy, tp.cx, tp.cy));
+          }
+        }
       }
       if (nodeG) {
         var children = nodeG.querySelectorAll(':scope > g[data-node-id]');
@@ -584,7 +602,14 @@ path[data-source].port-hover { opacity: 1; }
           var childId = childG.getAttribute('data-node-id');
           if (c.srcNode === childId || c.tgtNode === childId) {
             var sp = portPositions[c.src], tp = portPositions[c.tgt];
-            if (sp && tp) c.el.setAttribute('d', computeConnectionPath(sp.cx, sp.cy, tp.cx, tp.cy));
+            if (sp && tp) {
+              if (c.scopeOf) {
+                var pOff = nodeOffsets[c.scopeOf] || { dx: 0, dy: 0 };
+                c.el.setAttribute('d', computeConnectionPath(sp.cx - pOff.dx, sp.cy - pOff.dy, tp.cx - pOff.dx, tp.cy - pOff.dy));
+              } else {
+                c.el.setAttribute('d', computeConnectionPath(sp.cx, sp.cy, tp.cx, tp.cy));
+              }
+            }
           }
         });
       }

package/dist/diagram/renderer.js

@@ -100,12 +100,12 @@ function renderConnection(parts, conn, gradIndex) {
     const dashAttr = conn.isStepConnection ? '' : ' stroke-dasharray="8 4"';
     parts.push(`  <path d="${conn.path}" fill="none" stroke="url(#conn-grad-${gradIndex})" stroke-width="3"${dashAttr} stroke-linecap="round" data-source="${escapeXml(conn.fromNode)}.${escapeXml(conn.fromPort)}:output" data-target="${escapeXml(conn.toNode)}.${escapeXml(conn.toPort)}:input"/>`);
 }
-function renderScopeConnection(parts, conn, allConnections) {
+function renderScopeConnection(parts, conn, allConnections, parentNodeId) {
     const gradIndex = allConnections.indexOf(conn);
     if (gradIndex < 0)
         return;
     const dashAttr = conn.isStepConnection ? '' : ' stroke-dasharray="8 4"';
-    parts.push(`    <path d="${conn.path}" fill="none" stroke="url(#conn-grad-${gradIndex})" stroke-width="2.5"${dashAttr} stroke-linecap="round" data-source="${escapeXml(conn.fromNode)}.${escapeXml(conn.fromPort)}:output" data-target="${escapeXml(conn.toNode)}.${escapeXml(conn.toPort)}:input"/>`);
+    parts.push(`    <path d="${conn.path}" fill="none" stroke="url(#conn-grad-${gradIndex})" stroke-width="2.5"${dashAttr} stroke-linecap="round" data-source="${escapeXml(conn.fromNode)}.${escapeXml(conn.fromPort)}:output" data-target="${escapeXml(conn.toNode)}.${escapeXml(conn.toPort)}:input" data-scope="${escapeXml(parentNodeId)}"/>`);
 }
 // ---- Node rendering ----
 /** Render node body rect + icon */
@@ -147,7 +147,7 @@ function renderScopedContent(parts, node, theme, themeName, allConnections) {
     parts.push(`    <rect x="${scopeX}" y="${scopeY}" width="${scopeW}" height="${scopeH}" rx="4" fill="none" stroke="${theme.scopeAreaStroke}" stroke-width="1" stroke-dasharray="4 2" opacity="0.5"/>`);
     // Scope connections (before ports so ports appear on top)
     for (const conn of node.scopeConnections ?? []) {
-        renderScopeConnection(parts, conn, allConnections);
+        renderScopeConnection(parts, conn, allConnections, node.id);
     }
     // Scope port dots (before children so dots sit on top of connections)
     if (scopePorts) {

package/dist/friendly-errors.js

@@ -505,6 +505,41 @@ const errorMappers = {
             code: error.code,
         };
     },
+    COERCE_TYPE_MISMATCH(error) {
+        const coerceMatch = error.message.match(/`as (\w+)`/);
+        const coerceType = coerceMatch?.[1] || 'unknown';
+        const expectsMatch = error.message.match(/expects (\w+)/);
+        const expectedType = expectsMatch?.[1] || 'unknown';
+        const suggestedType = COERCE_TARGET_TYPES[expectedType.toUpperCase()] || expectedType.toLowerCase();
+        return {
+            title: 'Wrong Coercion Type',
+            explanation: `The \`as ${coerceType}\` coercion produces the wrong type for the target port. The target expects ${expectedType}.`,
+            fix: `Change \`as ${coerceType}\` to \`as ${suggestedType}\` in the @connect annotation.`,
+            code: error.code,
+        };
+    },
+    REDUNDANT_COERCE(error) {
+        const coerceMatch = error.message.match(/`as (\w+)`/);
+        const coerceType = coerceMatch?.[1] || 'unknown';
+        const bothMatch = error.message.match(/both (\w+)/);
+        const dataType = bothMatch?.[1] || 'the same type';
+        return {
+            title: 'Redundant Coercion',
+            explanation: `The \`as ${coerceType}\` coercion is unnecessary because both the source and target ports are already ${dataType}.`,
+            fix: `Remove \`as ${coerceType}\` from the @connect annotation — no coercion is needed.`,
+            code: error.code,
+        };
+    },
+    COERCE_ON_FUNCTION_PORT(error) {
+        const coerceMatch = error.message.match(/`as (\w+)`/);
+        const coerceType = coerceMatch?.[1] || 'unknown';
+        return {
+            title: 'Coercion on Function Port',
+            explanation: `The \`as ${coerceType}\` coercion cannot be applied to FUNCTION ports. Function values are callable references and cannot be meaningfully converted to other types.`,
+            fix: `Remove \`as ${coerceType}\` from the @connect annotation. If you need to convert the function's return value, add a transformation node.`,
+            code: error.code,
+        };
+    },
     LOSSY_TYPE_COERCION(error) {
         const types = extractTypes(error.message);
         const source = types?.source || 'unknown';

package/dist/generator/code-utils.d.ts

@@ -1,4 +1,15 @@
-import type { TNodeTypeAST, TWorkflowAST, TMergeStrategy } from '../ast/index.js';
+import type { TNodeTypeAST, TWorkflowAST, TMergeStrategy, TConnectionAST, TDataType } from '../ast/index.js';
+/**
+ * Get the coercion expression to wrap a value, if coercion is needed.
+ * Returns null if no coercion needed.
+ *
+ * Priority:
+ * 1. Explicit coerce on the connection (from `as <type>` annotation)
+ * 2. Auto-coercion for safe pairs:
+ *    - anything -> STRING (String() never fails)
+ *    - BOOLEAN -> NUMBER (well-defined: false->0, true->1)
+ */
+export declare function getCoercionWrapper(connection: TConnectionAST, sourceDataType: TDataType | undefined, targetDataType: TDataType | undefined): string | null;
 /**
  * Sanitize a node ID to be a valid JavaScript identifier.
  * Replaces non-alphanumeric characters (except _ and $) with underscores.

package/dist/generator/code-utils.js

@@ -1,6 +1,72 @@
 import { RESERVED_PORT_NAMES, isStartNode, isExitNode, isExecutePort, isSuccessPort, isFailurePort, } from '../constants.js';
 import { generateScopeFunctionClosure } from './scope-function-generator.js';
 import { mapToTypeScript } from '../type-mappings.js';
+/** Map coercion target type to inline JS expression */
+const COERCION_EXPRESSIONS = {
+    string: 'String',
+    number: 'Number',
+    boolean: 'Boolean',
+    json: 'JSON.stringify',
+    object: 'JSON.parse',
+};
+/** Map TDataType to TCoerceTargetType for auto-coercion */
+const DATATYPE_TO_COERCE = {
+    STRING: 'string',
+    NUMBER: 'number',
+    BOOLEAN: 'boolean',
+    OBJECT: 'object',
+};
+/**
+ * Resolve the dataType of a source port by looking up the node instance -> node type -> outputs.
+ */
+function resolveSourcePortDataType(workflow, sourceNodeId, sourcePort) {
+    if (isStartNode(sourceNodeId)) {
+        return workflow.startPorts?.[sourcePort]?.dataType;
+    }
+    if (isExitNode(sourceNodeId)) {
+        return workflow.exitPorts?.[sourcePort]?.dataType;
+    }
+    const instance = workflow.instances.find((i) => i.id === sourceNodeId);
+    if (!instance)
+        return undefined;
+    const nodeType = workflow.nodeTypes.find((nt) => nt.name === instance.nodeType || nt.functionName === instance.nodeType);
+    if (!nodeType)
+        return undefined;
+    return nodeType.outputs?.[sourcePort]?.dataType;
+}
+/**
+ * Get the coercion expression to wrap a value, if coercion is needed.
+ * Returns null if no coercion needed.
+ *
+ * Priority:
+ * 1. Explicit coerce on the connection (from `as <type>` annotation)
+ * 2. Auto-coercion for safe pairs:
+ *    - anything -> STRING (String() never fails)
+ *    - BOOLEAN -> NUMBER (well-defined: false->0, true->1)
+ */
+export function getCoercionWrapper(connection, sourceDataType, targetDataType) {
+    // Explicit coerce on connection
+    if (connection.coerce) {
+        return COERCION_EXPRESSIONS[connection.coerce];
+    }
+    // No auto-coercion if types are unknown or same
+    if (!sourceDataType || !targetDataType || sourceDataType === targetDataType)
+        return null;
+    // Skip STEP and ANY ports — no coercion needed
+    if (sourceDataType === 'STEP' || targetDataType === 'STEP')
+        return null;
+    if (sourceDataType === 'ANY' || targetDataType === 'ANY')
+        return null;
+    // Auto-coerce: anything -> STRING
+    if (targetDataType === 'STRING' && sourceDataType !== 'STRING') {
+        return 'String';
+    }
+    // Auto-coerce: BOOLEAN -> NUMBER
+    if (sourceDataType === 'BOOLEAN' && targetDataType === 'NUMBER') {
+        return 'Number';
+    }
+    return null;
+}
 /**
  * Sanitize a node ID to be a valid JavaScript identifier.
  * Replaces non-alphanumeric characters (except _ and $) with underscores.
@@ -197,7 +263,16 @@ export function buildNodeArgumentsWithContext(opts) {
                     lines.push(`${indent}const ${varName} = ${varName}_resolved.fn as ${portType};`);
                 }
                 else {
-                    lines.push(`${indent}const ${varName} = ${getCall}({ id: '${sourceNode}', portName: '${sourcePort}', executionIndex: ${sourceIdx}${nonNullAssert} }) as ${portType};`);
+                    // Check for coercion (explicit or auto)
+                    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) {
+                        lines.push(`${indent}const ${varName} = ${coerceExpr}(${getExpr}) as ${portType};`);
+                    }
+                    else {
+                        lines.push(`${indent}const ${varName} = ${getExpr} as ${portType};`);
+                    }
                 }
             }
             else {
@@ -214,11 +289,21 @@ export function buildNodeArgumentsWithContext(opts) {
                     return;
                 }
                 const attempts = [];
-                validConnections.forEach((conn, _idx) => {
+                validConnections.forEach((conn) => {
                     const sourceNode = conn.from.node;
                     const sourcePort = conn.from.port;
                     const sourceIdx = isStartNode(sourceNode) ? 'startIdx' : `${toValidIdentifier(sourceNode)}Idx`;
-                    attempts.push(`(${sourceIdx} !== undefined ? ${getCall}({ id: '${sourceNode}', portName: '${sourcePort}', executionIndex: ${sourceIdx} }) : undefined)`);
+                    const getExpr = `${getCall}({ id: '${sourceNode}', portName: '${sourcePort}', executionIndex: ${sourceIdx} })`;
+                    // Per-connection coercion: each source gets its own coercion wrapper
+                    if (portConfig.dataType !== 'FUNCTION') {
+                        const sourceDataType = resolveSourcePortDataType(workflow, sourceNode, sourcePort);
+                        const coerceExpr = getCoercionWrapper(conn, sourceDataType, portConfig.dataType);
+                        const wrapped = coerceExpr ? `${coerceExpr}(${getExpr})` : getExpr;
+                        attempts.push(`(${sourceIdx} !== undefined ? ${wrapped} : undefined)`);
+                    }
+                    else {
+                        attempts.push(`(${sourceIdx} !== undefined ? ${getExpr} : undefined)`);
+                    }
                 });
                 const ternary = attempts.join(' ?? ');
                 const portType = mapToTypeScript(portConfig.dataType, portConfig.tsType);

package/dist/jsdoc-parser.js

@@ -889,7 +889,7 @@ export class JSDocParser {
             warnings.push(`Invalid @connect tag format: @connect ${comment}`);
             return;
         }
-        const { source, target } = result;
+        const { source, target, coerce } = result;
         // Capture source location from tag
         const line = tag.getStartLineNumber();
         config.connections.push({
@@ -904,6 +904,7 @@ export class JSDocParser {
                 ...(target.scope && { scope: target.scope }),
             },
             sourceLocation: { line, column: 0 },
+            ...(coerce && { coerce }),
         });
     }
     /**

package/dist/validator.js

@@ -17,7 +17,25 @@ const ERROR_DOC_URLS = {
     INFERRED_NODE_TYPE: `${DOCS_BASE}/node-conversion`,
     DUPLICATE_CONNECTION: `${DOCS_BASE}/concepts#connections`,
     STUB_NODE: `${DOCS_BASE}/model-driven#stub-nodes`,
+    COERCE_TYPE_MISMATCH: `${DOCS_BASE}/compilation#type-coercion`,
+    REDUNDANT_COERCE: `${DOCS_BASE}/compilation#type-coercion`,
+    COERCE_ON_FUNCTION_PORT: `${DOCS_BASE}/compilation#type-coercion`,
 };
+/** Map coerce type to the dataType it produces */
+const COERCE_OUTPUT_TYPE = {
+    string: 'STRING', number: 'NUMBER', boolean: 'BOOLEAN',
+    json: 'STRING', object: 'OBJECT',
+};
+/** Suggest the correct `as <type>` for a given target dataType */
+function suggestCoerceType(targetType) {
+    switch (targetType) {
+        case 'STRING': return 'string';
+        case 'NUMBER': return 'number';
+        case 'BOOLEAN': return 'boolean';
+        case 'OBJECT': return 'object';
+        default: return '<type>';
+    }
+}
 export class WorkflowValidator {
     errors = [];
     warnings = [];
@@ -478,8 +496,30 @@ export class WorkflowValidator {
             if (sourceType === 'STEP' && targetType === 'STEP') {
                 return;
             }
+            // Block coercion on FUNCTION ports — coercing a function value is nonsensical
+            if (conn.coerce && (sourceType === 'FUNCTION' || targetType === 'FUNCTION')) {
+                this.errors.push({
+                    type: 'error',
+                    code: 'COERCE_ON_FUNCTION_PORT',
+                    message: `Coercion \`as ${conn.coerce}\` cannot be used on FUNCTION ports in connection "${fromNode}.${fromPort}" → "${toNode}.${toPort}". FUNCTION values cannot be meaningfully coerced.`,
+                    connection: conn,
+                    location: connLocation,
+                });
+                return;
+            }
             // Same type - check for structural compatibility if both are OBJECT
             if (sourceType === targetType) {
+                // Redundant coerce: same types don't need coercion
+                if (conn.coerce) {
+                    this.warnings.push({
+                        type: 'warning',
+                        code: 'REDUNDANT_COERCE',
+                        message: `Coercion \`as ${conn.coerce}\` on connection "${fromNode}.${fromPort}" → "${toNode}.${toPort}" is redundant — source and target are both ${sourceType}.`,
+                        connection: conn,
+                        location: connLocation,
+                    });
+                    return;
+                }
                 // For OBJECT types, check if tsType differs (structural mismatch)
                 if (sourceType === 'OBJECT' && sourcePortDef.tsType && targetPortDef.tsType) {
                     const normalizedSource = this.normalizeTypeString(sourcePortDef.tsType);
@@ -504,6 +544,22 @@ export class WorkflowValidator {
             if (sourceType === 'ANY' || targetType === 'ANY') {
                 return;
             }
+            // Validate explicit coerce: check that produced type matches target
+            if (conn.coerce) {
+                const producedType = COERCE_OUTPUT_TYPE[conn.coerce];
+                if (producedType === targetType) {
+                    return; // Coerce correctly resolves the mismatch
+                }
+                // Wrong coerce type — produced type doesn't match target
+                pushTypeIssue({
+                    type: 'warning',
+                    code: 'COERCE_TYPE_MISMATCH',
+                    message: `Coercion \`as ${conn.coerce}\` produces ${producedType} but target port "${toPort}" on "${toNode}" expects ${targetType}. Use \`as ${suggestCoerceType(targetType)}\` instead.`,
+                    connection: conn,
+                    location: connLocation,
+                }, true);
+                return;
+            }
             // Safe coercions (no warning)
             const safeCoercions = [
                 ['NUMBER', 'STRING'],

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@synergenius/flow-weaver",
-  "version": "0.10.1",
+  "version": "0.10.3",
   "description": "Deterministic workflow compiler for AI agents. Compiles to standalone TypeScript, no runtime dependencies.",
   "private": false,
   "type": "module",
@@ -145,6 +145,7 @@
     "@types/js-yaml": "^4.0.9",
     "@types/node": "^20.11.0",
     "@types/react": "^19.0.0",
+    "@vitest/coverage-v8": "^4.0.18",
     "esbuild": "^0.27.2",
     "prettier": "^3.1.1",
     "rimraf": "6.1.2",