@synergenius/flow-weaver 0.10.2 → 0.10.3

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"]
@@ -28164,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)) {
@@ -28293,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) => {
@@ -28309,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);
@@ -43545,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", () => {
@@ -43573,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;
@@ -43607,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();
@@ -45307,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: {
@@ -45320,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 }
     });
   }
   /**
@@ -54285,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";
@@ -96730,7 +96900,7 @@ function displayInstalledPackage(pkg) {
 }
 
 // src/cli/index.ts
-var version2 = true ? "0.10.2" : "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/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.2",
+  "version": "0.10.3",
   "description": "Deterministic workflow compiler for AI agents. Compiles to standalone TypeScript, no runtime dependencies.",
   "private": false,
   "type": "module",