@synergenius/flow-weaver 0.21.13 → 0.21.15

package/dist/annotation-generator.js

@@ -225,7 +225,18 @@ export class AnnotationGenerator {
             }
         });
         // Filter stale macros (e.g. paths whose connections were deleted)
-        const existingMacros = filterStaleMacros(workflow.macros || [], workflow.connections, workflow.instances);
+        const existingMacros = filterStaleMacros(workflow.macros || [], workflow.connections, workflow.instances, workflow.nodeTypes, workflow.startPorts, workflow.exitPorts);
+        // Compute dropped coerce instance IDs — their connections must be excluded
+        const survivingCoerceIds = new Set();
+        for (const macro of existingMacros) {
+            if (macro.type === 'coerce')
+                survivingCoerceIds.add(macro.instanceId);
+        }
+        const droppedCoerceIds = new Set();
+        for (const id of coerceInstanceIds) {
+            if (!survivingCoerceIds.has(id))
+                droppedCoerceIds.add(id);
+        }
         // Auto-detect @path sugar patterns from connections
         const detected = detectSugarPatterns(workflow.connections, workflow.instances, existingMacros, workflow.nodeTypes, workflow.startPorts, workflow.exitPorts);
         // Merge detected macros with existing ones
@@ -275,11 +286,13 @@ export class AnnotationGenerator {
         if (workflow.ui?.exitNode?.x !== undefined && workflow.ui?.exitNode?.y !== undefined) {
             lines.push(` * @position Exit ${Math.round(workflow.ui.exitNode.x)} ${Math.round(workflow.ui.exitNode.y)}`);
         }
-        // Add connections — skip connections covered by macros
+        // Add connections — skip connections covered by macros and dropped coerce connections
         if (!workflow.options?.autoConnect) {
             workflow.connections.forEach((conn) => {
                 if (allMacros.length > 0 && isConnectionCoveredByMacroStatic(conn, allMacros))
                     return;
+                if (droppedCoerceIds.has(conn.from.node) || droppedCoerceIds.has(conn.to.node))
+                    return;
                 const fromScope = conn.from.scope ? `:${conn.from.scope}` : '';
                 const toScope = conn.to.scope ? `:${conn.to.scope}` : '';
                 lines.push(` * @connect ${conn.from.node}.${conn.from.port}${fromScope} -> ${conn.to.node}.${conn.to.port}${toScope}`);

package/dist/api/generate-in-place.js

@@ -1035,10 +1035,11 @@ function isConnectionCoveredByMacro(conn, macros) {
  */
 function generateWorkflowJSDoc(ast, options = {}) {
     const lines = [];
-    // Build macro coverage sets for filtering (@map-specific)
+    // Build macro coverage sets for filtering (@map and @coerce)
     const macroInstanceIds = new Set();
     const macroChildIds = new Set();
     const macroScopeNames = new Set();
+    const allCoerceInstanceIds = new Set();
     if (ast.macros && ast.macros.length > 0) {
         for (const macro of ast.macros) {
             if (macro.type === 'map') {
@@ -1046,6 +1047,9 @@ function generateWorkflowJSDoc(ast, options = {}) {
                 macroChildIds.add(macro.childId);
                 macroScopeNames.add(`${macro.instanceId}.iterate`);
             }
+            else if (macro.type === 'coerce') {
+                allCoerceInstanceIds.add(macro.instanceId);
+            }
         }
     }
     lines.push('/**');
@@ -1127,11 +1131,13 @@ function generateWorkflowJSDoc(ast, options = {}) {
     // Auto-position: compute default positions for nodes without explicit positions.
     // Must happen before instance tags are generated so [position:] can be emitted.
     const autoPositions = computeAutoPositions(ast);
-    // Add node instances — skip synthetic MAP_ITERATOR instances, strip parent from macro children.
+    // Add node instances — skip synthetic MAP_ITERATOR/COERCION instances, strip parent from macro children.
     // Merge auto-computed positions into instance config (without mutating the AST).
     for (const instance of ast.instances) {
         if (macroInstanceIds.has(instance.id))
             continue;
+        if (allCoerceInstanceIds.has(instance.id))
+            continue;
         // Merge auto-position into config if not already set
         let inst = instance;
         if (inst.config?.x === undefined || inst.config?.y === undefined) {
@@ -1157,7 +1163,18 @@ function generateWorkflowJSDoc(ast, options = {}) {
         }
     }
     // Filter stale macros (e.g. paths whose connections were deleted)
-    const existingMacros = filterStaleMacros(ast.macros || [], ast.connections, ast.instances);
+    const existingMacros = filterStaleMacros(ast.macros || [], ast.connections, ast.instances, ast.nodeTypes, ast.startPorts, ast.exitPorts);
+    // Compute dropped coerce instance IDs — their synthetic instances and connections must be excluded
+    const survivingCoerceIds = new Set();
+    for (const macro of existingMacros) {
+        if (macro.type === 'coerce')
+            survivingCoerceIds.add(macro.instanceId);
+    }
+    const droppedCoerceIds = new Set();
+    for (const id of allCoerceInstanceIds) {
+        if (!survivingCoerceIds.has(id))
+            droppedCoerceIds.add(id);
+    }
     // Auto-detect @path sugar patterns from connections
     const detected = detectSugarPatterns(ast.connections, ast.instances, existingMacros, ast.nodeTypes, ast.startPorts, ast.exitPorts);
     // Merge detected macros with existing ones
@@ -1205,11 +1222,13 @@ function generateWorkflowJSDoc(ast, options = {}) {
         lines.push(` * @position Exit ${Math.round(exitX)} ${Math.round(exitY)}`);
     }
     // Add connections (with scope suffix when present)
-    // Skip connections covered by @map macros and autoConnect-generated connections
+    // Skip connections covered by macros, autoConnect-generated connections, and dropped coerce connections
     if (!ast.options?.autoConnect) {
         for (const conn of ast.connections) {
             if (allMacros.length > 0 && isConnectionCoveredByMacro(conn, allMacros))
                 continue;
+            if (droppedCoerceIds.has(conn.from.node) || droppedCoerceIds.has(conn.to.node))
+                continue;
             const fromScope = conn.from.scope ? `:${conn.from.scope}` : '';
             const toScope = conn.to.scope ? `:${conn.to.scope}` : '';
             lines.push(` * @connect ${conn.from.node}.${conn.from.port}${fromScope} -> ${conn.to.node}.${conn.to.port}${toScope}`);

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.21.13";
+    VERSION = "0.21.15";
   }
 });
 
@@ -18090,7 +18090,7 @@ var init_port_tag_utils = __esm({
 });
 
 // src/sugar-optimizer.ts
-function validatePathMacro(path50, connections, instances) {
+function validatePathMacro(path50, connections, instances, nodeTypes, startPorts, exitPorts) {
   const instanceIds = new Set(instances.map((inst) => inst.id));
   for (const step of path50.steps) {
     if (step.node === "Start" || step.node === "Exit") continue;
@@ -18126,21 +18126,85 @@ function validatePathMacro(path50, connections, instances) {
       return false;
     }
   }
+  if (nodeTypes && startPorts && exitPorts) {
+    const instanceMap = new Map(instances.map((inst) => [inst.id, inst]));
+    const nodeTypeMap = /* @__PURE__ */ new Map();
+    for (const nt of nodeTypes) {
+      nodeTypeMap.set(nt.name, nt);
+      if (nt.functionName !== nt.name) {
+        nodeTypeMap.set(nt.functionName, nt);
+      }
+    }
+    const getNodeType2 = (nodeId) => {
+      const inst = instanceMap.get(nodeId);
+      if (!inst) return void 0;
+      return nodeTypeMap.get(inst.nodeType);
+    };
+    const getOutputPorts = (nodeId) => {
+      if (nodeId === "Start") return startPorts;
+      const nt = getNodeType2(nodeId);
+      return nt?.outputs || {};
+    };
+    const getInputPorts = (nodeId) => {
+      if (nodeId === "Exit") return exitPorts;
+      const nt = getNodeType2(nodeId);
+      return nt?.inputs || {};
+    };
+    const { steps } = path50;
+    for (let i = 0; i < steps.length - 1; i++) {
+      const nextId = steps[i + 1].node;
+      if (nextId === "Exit") continue;
+      const nextInputs = getInputPorts(nextId);
+      for (const [inputName] of Object.entries(nextInputs)) {
+        if (isControlFlowPort(inputName)) continue;
+        for (let j = i; j >= 0; j--) {
+          const ancestorId = steps[j].node;
+          const ancestorOutputs = getOutputPorts(ancestorId);
+          if (inputName in ancestorOutputs && !isControlFlowPort(inputName)) {
+            const key = `${ancestorId}.${inputName}->${nextId}.${inputName}`;
+            if (!connKeys.has(key)) {
+              return false;
+            }
+            break;
+          }
+        }
+      }
+    }
+  }
   return true;
 }
-function filterStaleMacros(macros, connections, instances) {
+function filterStaleMacros(macros, connections, instances, nodeTypes, startPorts, exitPorts) {
   const instanceIds = new Set(instances.map((i) => i.id));
   instanceIds.add("Start");
   instanceIds.add("Exit");
+  const connKeys = /* @__PURE__ */ new Set();
+  for (const conn of connections) {
+    if (!conn.from.scope && !conn.to.scope) {
+      connKeys.add(`${conn.from.node}.${conn.from.port}->${conn.to.node}.${conn.to.port}`);
+    }
+  }
   return macros.filter((macro) => {
-    if (macro.type === "path") return validatePathMacro(macro, connections, instances);
+    if (macro.type === "path") return validatePathMacro(macro, connections, instances, nodeTypes, startPorts, exitPorts);
     if (macro.type === "fanOut") {
       if (!instanceIds.has(macro.source.node)) return false;
-      return macro.targets.every((t) => instanceIds.has(t.node));
+      return macro.targets.every((t) => {
+        if (!instanceIds.has(t.node)) return false;
+        const targetPort = t.port ?? macro.source.port;
+        return connKeys.has(`${macro.source.node}.${macro.source.port}->${t.node}.${targetPort}`);
+      });
     }
     if (macro.type === "fanIn") {
       if (!instanceIds.has(macro.target.node)) return false;
-      return macro.sources.every((s) => instanceIds.has(s.node));
+      return macro.sources.every((s) => {
+        if (!instanceIds.has(s.node)) return false;
+        const sourcePort = s.port ?? macro.target.port;
+        return connKeys.has(`${s.node}.${sourcePort}->${macro.target.node}.${macro.target.port}`);
+      });
+    }
+    if (macro.type === "coerce") {
+      const toCoerce = `${macro.source.node}.${macro.source.port}->${macro.instanceId}.value`;
+      const fromCoerce = `${macro.instanceId}.result->${macro.target.node}.${macro.target.port}`;
+      return connKeys.has(toCoerce) && connKeys.has(fromCoerce);
     }
     return true;
   });
@@ -18775,8 +18839,19 @@ var init_annotation_generator = __esm({
         const existingMacros = filterStaleMacros(
           workflow.macros || [],
           workflow.connections,
-          workflow.instances
+          workflow.instances,
+          workflow.nodeTypes,
+          workflow.startPorts,
+          workflow.exitPorts
         );
+        const survivingCoerceIds = /* @__PURE__ */ new Set();
+        for (const macro of existingMacros) {
+          if (macro.type === "coerce") survivingCoerceIds.add(macro.instanceId);
+        }
+        const droppedCoerceIds = /* @__PURE__ */ new Set();
+        for (const id of coerceInstanceIds) {
+          if (!survivingCoerceIds.has(id)) droppedCoerceIds.add(id);
+        }
         const detected = detectSugarPatterns(
           workflow.connections,
           workflow.instances,
@@ -18825,6 +18900,7 @@ var init_annotation_generator = __esm({
         if (!workflow.options?.autoConnect) {
           workflow.connections.forEach((conn) => {
             if (allMacros.length > 0 && isConnectionCoveredByMacroStatic(conn, allMacros)) return;
+            if (droppedCoerceIds.has(conn.from.node) || droppedCoerceIds.has(conn.to.node)) return;
             const fromScope = conn.from.scope ? `:${conn.from.scope}` : "";
             const toScope = conn.to.scope ? `:${conn.to.scope}` : "";
             lines.push(` * @connect ${conn.from.node}.${conn.from.port}${fromScope} -> ${conn.to.node}.${conn.to.port}${toScope}`);
@@ -19679,12 +19755,15 @@ function generateWorkflowJSDoc(ast, options = {}) {
   const macroInstanceIds = /* @__PURE__ */ new Set();
   const macroChildIds = /* @__PURE__ */ new Set();
   const macroScopeNames = /* @__PURE__ */ new Set();
+  const allCoerceInstanceIds = /* @__PURE__ */ new Set();
   if (ast.macros && ast.macros.length > 0) {
     for (const macro of ast.macros) {
       if (macro.type === "map") {
         macroInstanceIds.add(macro.instanceId);
         macroChildIds.add(macro.childId);
         macroScopeNames.add(`${macro.instanceId}.iterate`);
+      } else if (macro.type === "coerce") {
+        allCoerceInstanceIds.add(macro.instanceId);
       }
     }
   }
@@ -19744,6 +19823,7 @@ function generateWorkflowJSDoc(ast, options = {}) {
   const autoPositions = computeAutoPositions(ast);
   for (const instance of ast.instances) {
     if (macroInstanceIds.has(instance.id)) continue;
+    if (allCoerceInstanceIds.has(instance.id)) continue;
     let inst = instance;
     if (inst.config?.x === void 0 || inst.config?.y === void 0) {
       const autoPos = autoPositions.get(inst.id);
@@ -19768,8 +19848,19 @@ function generateWorkflowJSDoc(ast, options = {}) {
   const existingMacros = filterStaleMacros(
     ast.macros || [],
     ast.connections,
-    ast.instances
+    ast.instances,
+    ast.nodeTypes,
+    ast.startPorts,
+    ast.exitPorts
   );
+  const survivingCoerceIds = /* @__PURE__ */ new Set();
+  for (const macro of existingMacros) {
+    if (macro.type === "coerce") survivingCoerceIds.add(macro.instanceId);
+  }
+  const droppedCoerceIds = /* @__PURE__ */ new Set();
+  for (const id of allCoerceInstanceIds) {
+    if (!survivingCoerceIds.has(id)) droppedCoerceIds.add(id);
+  }
   const detected = detectSugarPatterns(
     ast.connections,
     ast.instances,
@@ -19818,6 +19909,7 @@ function generateWorkflowJSDoc(ast, options = {}) {
   if (!ast.options?.autoConnect) {
     for (const conn of ast.connections) {
       if (allMacros.length > 0 && isConnectionCoveredByMacro(conn, allMacros)) continue;
+      if (droppedCoerceIds.has(conn.from.node) || droppedCoerceIds.has(conn.to.node)) continue;
       const fromScope = conn.from.scope ? `:${conn.from.scope}` : "";
       const toScope = conn.to.scope ? `:${conn.to.scope}` : "";
       lines.push(
@@ -93117,7 +93209,7 @@ function displayInstalledPackage(pkg) {
 // src/cli/index.ts
 init_logger();
 init_error_utils();
-var version2 = true ? "0.21.13" : "0.0.0-dev";
+var version2 = true ? "0.21.15" : "0.0.0-dev";
 var program2 = new Command();
 program2.name("fw").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/generated-version.d.ts

@@ -1,2 +1,2 @@
-export declare const VERSION = "0.21.13";
+export declare const VERSION = "0.21.15";
 //# 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.21.13';
+export const VERSION = '0.21.15';
 //# sourceMappingURL=generated-version.js.map

package/dist/sugar-optimizer.d.ts

@@ -10,19 +10,24 @@ export interface DetectedSugar {
     paths: TPathMacro[];
 }
 /**
- * Validate that a @path macro's control-flow connections still exist
- * in the actual connection set. Also checks that all step nodes exist
- * as instances (or are Start/Exit).
+ * Validate that a @path macro's connections still exist in the actual
+ * connection set. Checks both control-flow AND data connections (scope
+ * walking). Also checks that all step nodes exist as instances (or are
+ * Start/Exit).
  *
  * Returns true if the path is still valid, false if it should be dropped.
+ *
+ * When nodeTypes/startPorts/exitPorts are provided, data connections are
+ * validated using the same scope-walking algorithm that expandPathMacros
+ * uses. Without them, only control-flow is checked (legacy behavior).
  */
-export declare function validatePathMacro(path: TPathMacro, connections: TConnectionAST[], instances: TNodeInstanceAST[]): boolean;
+export declare function validatePathMacro(path: TPathMacro, connections: TConnectionAST[], instances: TNodeInstanceAST[], nodeTypes?: TNodeTypeAST[], startPorts?: Record<string, TPortDefinition>, exitPorts?: Record<string, TPortDefinition>): boolean;
 /**
- * Filter existing macros, removing any @path macros whose control-flow
- * connections no longer exist in the connection set.
+ * Filter existing macros, removing any @path macros whose connections
+ * (control-flow AND data) no longer exist in the connection set.
  * Non-path macros are passed through unchanged.
  */
-export declare function filterStaleMacros(macros: TWorkflowMacro[], connections: TConnectionAST[], instances: TNodeInstanceAST[]): TWorkflowMacro[];
+export declare function filterStaleMacros(macros: TWorkflowMacro[], connections: TConnectionAST[], instances: TNodeInstanceAST[], nodeTypes?: TNodeTypeAST[], startPorts?: Record<string, TPortDefinition>, exitPorts?: Record<string, TPortDefinition>): TWorkflowMacro[];
 /**
  * Detect @path routes from a set of connections.
  *

package/dist/sugar-optimizer.js

@@ -10,13 +10,18 @@ import { isControlFlowPort } from './constants.js';
 // Path Validation (for stale macro detection during round-trip)
 // =============================================================================
 /**
- * Validate that a @path macro's control-flow connections still exist
- * in the actual connection set. Also checks that all step nodes exist
- * as instances (or are Start/Exit).
+ * Validate that a @path macro's connections still exist in the actual
+ * connection set. Checks both control-flow AND data connections (scope
+ * walking). Also checks that all step nodes exist as instances (or are
+ * Start/Exit).
  *
  * Returns true if the path is still valid, false if it should be dropped.
+ *
+ * When nodeTypes/startPorts/exitPorts are provided, data connections are
+ * validated using the same scope-walking algorithm that expandPathMacros
+ * uses. Without them, only control-flow is checked (legacy behavior).
  */
-export function validatePathMacro(path, connections, instances) {
+export function validatePathMacro(path, connections, instances, nodeTypes, startPorts, exitPorts) {
     const instanceIds = new Set(instances.map(inst => inst.id));
     // Check all step nodes exist as instances (or are Start/Exit)
     for (const step of path.steps) {
@@ -61,29 +66,110 @@ export function validatePathMacro(path, connections, instances) {
             return false;
         }
     }
+    // Validate data connections (scope walking) — same algorithm as
+    // expandPathMacros and detectSugarPatterns Step 3.
+    // If any data connection that the path would auto-generate is missing,
+    // the path is stale (a connection was explicitly removed).
+    if (nodeTypes && startPorts && exitPorts) {
+        const instanceMap = new Map(instances.map(inst => [inst.id, inst]));
+        const nodeTypeMap = new Map();
+        for (const nt of nodeTypes) {
+            nodeTypeMap.set(nt.name, nt);
+            if (nt.functionName !== nt.name) {
+                nodeTypeMap.set(nt.functionName, nt);
+            }
+        }
+        const getNodeType = (nodeId) => {
+            const inst = instanceMap.get(nodeId);
+            if (!inst)
+                return undefined;
+            return nodeTypeMap.get(inst.nodeType);
+        };
+        const getOutputPorts = (nodeId) => {
+            if (nodeId === 'Start')
+                return startPorts;
+            const nt = getNodeType(nodeId);
+            return nt?.outputs || {};
+        };
+        const getInputPorts = (nodeId) => {
+            if (nodeId === 'Exit')
+                return exitPorts;
+            const nt = getNodeType(nodeId);
+            return nt?.inputs || {};
+        };
+        const { steps } = path;
+        for (let i = 0; i < steps.length - 1; i++) {
+            const nextId = steps[i + 1].node;
+            if (nextId === 'Exit')
+                continue;
+            const nextInputs = getInputPorts(nextId);
+            for (const [inputName] of Object.entries(nextInputs)) {
+                if (isControlFlowPort(inputName))
+                    continue;
+                // Walk backward through path steps to find nearest ancestor with same-name output
+                for (let j = i; j >= 0; j--) {
+                    const ancestorId = steps[j].node;
+                    const ancestorOutputs = getOutputPorts(ancestorId);
+                    if (inputName in ancestorOutputs && !isControlFlowPort(inputName)) {
+                        const key = `${ancestorId}.${inputName}->${nextId}.${inputName}`;
+                        if (!connKeys.has(key)) {
+                            return false;
+                        }
+                        break;
+                    }
+                }
+            }
+        }
+    }
     return true;
 }
 /**
- * Filter existing macros, removing any @path macros whose control-flow
- * connections no longer exist in the connection set.
+ * Filter existing macros, removing any @path macros whose connections
+ * (control-flow AND data) no longer exist in the connection set.
  * Non-path macros are passed through unchanged.
  */
-export function filterStaleMacros(macros, connections, instances) {
+export function filterStaleMacros(macros, connections, instances, nodeTypes, startPorts, exitPorts) {
     const instanceIds = new Set(instances.map(i => i.id));
     instanceIds.add('Start');
     instanceIds.add('Exit');
+    // Build connection key set for quick lookup
+    const connKeys = new Set();
+    for (const conn of connections) {
+        if (!conn.from.scope && !conn.to.scope) {
+            connKeys.add(`${conn.from.node}.${conn.from.port}->${conn.to.node}.${conn.to.port}`);
+        }
+    }
     return macros.filter(macro => {
         if (macro.type === 'path')
-            return validatePathMacro(macro, connections, instances);
+            return validatePathMacro(macro, connections, instances, nodeTypes, startPorts, exitPorts);
         if (macro.type === 'fanOut') {
             if (!instanceIds.has(macro.source.node))
                 return false;
-            return macro.targets.every(t => instanceIds.has(t.node));
+            // Validate that all fanOut connections still exist
+            return macro.targets.every(t => {
+                if (!instanceIds.has(t.node))
+                    return false;
+                const targetPort = t.port ?? macro.source.port;
+                return connKeys.has(`${macro.source.node}.${macro.source.port}->${t.node}.${targetPort}`);
+            });
         }
         if (macro.type === 'fanIn') {
             if (!instanceIds.has(macro.target.node))
                 return false;
-            return macro.sources.every(s => instanceIds.has(s.node));
+            // Validate that all fanIn connections still exist
+            return macro.sources.every(s => {
+                if (!instanceIds.has(s.node))
+                    return false;
+                const sourcePort = s.port ?? macro.target.port;
+                return connKeys.has(`${s.node}.${sourcePort}->${macro.target.node}.${macro.target.port}`);
+            });
+        }
+        if (macro.type === 'coerce') {
+            // Validate that both coerce connections still exist:
+            // source -> coerceInstance.value AND coerceInstance.result -> target
+            const toCoerce = `${macro.source.node}.${macro.source.port}->${macro.instanceId}.value`;
+            const fromCoerce = `${macro.instanceId}.result->${macro.target.node}.${macro.target.port}`;
+            return connKeys.has(toCoerce) && connKeys.has(fromCoerce);
         }
         return true;
     });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@synergenius/flow-weaver",
-  "version": "0.21.13",
+  "version": "0.21.15",
   "description": "Deterministic workflow compiler for AI agents. Compiles to standalone TypeScript, no runtime dependencies.",
   "private": false,
   "type": "module",
@@ -31,6 +31,10 @@
       "types": "./dist/doc-metadata/index.d.ts",
       "default": "./dist/doc-metadata/index.js"
     },
+    "./docs": {
+      "types": "./dist/docs/index.d.ts",
+      "default": "./dist/docs/index.js"
+    },
     "./ast": {
       "types": "./dist/ast/index.d.ts",
       "default": "./dist/ast/index.js"