@synergenius/flow-weaver 0.33.1 → 0.44.0

package/dist/index.js

@@ -1,92 +1,1322 @@
-/**
- * @packageDocumentation
- *
- * # Flow Weaver Library
- *
- * A visual dataflow programming system for TypeScript. Workflows are defined via
- * JSDoc annotations in standard TypeScript files and can be parsed, validated,
- * and compiled to executable code.
- *
- * ## Core Concepts
- *
- * - **Workflow** (`TWorkflowAST`) - A graph of connected nodes with start/exit ports
- * - **NodeType** (`TNodeTypeAST`) - Template defining inputs, outputs, and behavior
- * - **NodeInstance** (`TNodeInstanceAST`) - A usage of a node type in a workflow
- * - **Port** (`TPortDefinition`) - Entry/exit point on a node (data or control flow)
- * - **Connection** (`TConnectionAST`) - Links ports between nodes
- *
- * ## File Format
- *
- * Any `.ts`, `.tsx`, `.js`, or `.jsx` file can contain workflows.
- *
- * ```typescript
- * // Define a node type
- * /**
- *  * @flowWeaver nodeType
- *  * @input a - First number
- *  * @input b - Second number
- *  * @output result - Sum
- *  *\/
- * function add(execute: boolean, a: number, b: number): { onSuccess: boolean; result: number } { ... }
- *
- * // Define a workflow
- * /**
- *  * @flowWeaver workflow
- *  * @node adder1 add
- *  * @connect Start.execute -> adder1.execute
- *  * @connect adder1.onSuccess -> Exit.onSuccess
- *  *\/
- * export function myWorkflow(execute: boolean, params: {...}): {...} { ... }
- * ```
- *
- * ## Main APIs
- *
- * - {@link parseWorkflow} - Parse a file to AST
- * - {@link validateWorkflow} - Validate workflow structure
- * - {@link generateCode} - Generate executable code from AST
- * - {@link compileWorkflow} - Parse + validate + generate in one step
- *
- * ## JSDoc Port Sync (Browser-compatible)
- *
- * For IDE integration, use the browser-compatible sync functions:
- * - {@link parsePortsFromFunctionText} - Extract ports from JSDoc
- * - {@link updatePortsInFunctionText} - Update ports in function text
- * - {@link formatPortsInFunctionText} - Format ports consistently
- *
- * @module @synergenius/flow-weaver
- */
-// Public API
-export * from './api/index.js';
-// Parser (for advanced use - clearing import cache)
-export { parser, resolveNpmNodeTypes } from './parser.js';
-// Extension registries
-export { TagHandlerRegistry } from './parser/tag-registry.js';
-export { ValidationRuleRegistry } from './validation/rule-registry.js';
-// AST Builders (for programmatic AST construction)
-export { WorkflowBuilder, NodeTypeBuilder, NodeInstanceBuilder, ConnectionBuilder, } from './ast/builder.js';
-export { portRef, port, workflow, nodeType, nodeInstance } from './ast/builder.js';
-// Runtime
-export { GeneratedExecutionContext } from './runtime/ExecutionContext.js';
-// Generated Branding (configurable output branding)
-export { configureGeneratedBranding, getGeneratedBranding } from './generated-branding.js';
-// Type Mappings & Constants
-export * from './type-mappings.js';
-export * from './constants.js';
-// Validation
-export { validator, WorkflowValidator } from './validator.js';
-// Friendly Errors (beginner-friendly validation messages)
-export { getFriendlyError, formatFriendlyDiagnostics } from './friendly-errors.js';
-// Code Generation
-export { generator, WorkflowGenerator } from './generator.js';
-export { AnnotationGenerator } from './annotation-generator.js';
-// Generator Utilities (for advanced use)
-export * as GeneratorUtils from './generator.js';
-// JSDoc Port Sync (browser-compatible parsing/updating)
-export { parsePortsFromFunctionText, updatePortsInFunctionText, formatPortsInFunctionText, syncCodeRenames, renamePortInCode, parseReturnTypeFields, parseFunctionSignature, parseReturnFields, } from './jsdoc-port-sync/index.js';
-// Templates (for workflow/node creation)
-export { workflowTemplates, nodeTemplates, getWorkflowTemplate, getNodeTemplate, toCamelCase, toPascalCase, } from './cli/templates/index.js';
-// Diff (semantic comparison)
-export { WorkflowDiffer } from './diff/WorkflowDiffer.js';
-export { formatDiff } from './diff/formatDiff.js';
-export { IMPACT_DESCRIPTIONS, IMPACT_COLORS, getImpactReasons, hasBreakingChanges, getNodeTypeChanges, getCriticalConnections, } from './diff/impact.js';
-//# sourceMappingURL=index.js.map
+import {
+  ConnectionBuilder,
+  NodeInstanceBuilder,
+  NodeTypeBuilder,
+  WorkflowBuilder,
+  nodeInstance,
+  nodeType,
+  port,
+  portRef,
+  workflow
+} from "./chunks/chunk-CY3RNVML.js";
+import {
+  addConnection,
+  addConnections,
+  addNode,
+  addNodeType,
+  addNodes,
+  addToScope,
+  applyModifyOperation,
+  assertNodeExists,
+  assertNodeNotExists,
+  assertNodeTypeExists,
+  cloneWorkflow,
+  createScope,
+  createWorkflow,
+  fromAST,
+  generateNodeFromTemplate,
+  generateUniqueNodeId,
+  generateWorkflowFromTemplate,
+  getAvailableCommands,
+  getNodeType,
+  hasNodeType,
+  listNodeTemplates,
+  listNodeTypes,
+  listWorkflowTemplates,
+  moveToScope,
+  reconnect,
+  removeAllConnections,
+  removeConnection,
+  removeFromScope,
+  removeNode,
+  removeNodeType,
+  removeNodes,
+  removeScope,
+  renameNode,
+  renameNodeType,
+  renameWorkflow,
+  replaceConnections,
+  replaceNodeTypes,
+  runCommand,
+  setInstancePortConfigs,
+  setNodeConfig,
+  setNodeLabel,
+  setNodeMinimized,
+  setNodeSize,
+  setOutputFileType,
+  setStartExitPorts,
+  setWorkflowDescription,
+  setWorkflowMetadata,
+  setWorkflowPorts,
+  swapNodeInstancePortOrder,
+  swapPortOrder,
+  transformWorkflow,
+  updateNode,
+  updateNodeType,
+  validateModifyParams,
+  withMinimalValidation,
+  withValidation,
+  withoutValidation
+} from "./chunks/chunk-7YYKTPJ5.js";
+import {
+  validateWorkflow
+} from "./chunks/chunk-P44RIZ7C.js";
+import "./chunks/chunk-ZKEGXO73.js";
+import {
+  ValidationRuleRegistry,
+  validationRuleRegistry
+} from "./chunks/chunk-A5MBOFVY.js";
+import {
+  IMPACT_COLORS,
+  IMPACT_DESCRIPTIONS,
+  WorkflowDiffer,
+  formatDiff,
+  getCriticalConnections,
+  getImpactReasons,
+  getNodeTypeChanges,
+  hasBreakingChanges
+} from "./chunks/chunk-CYHYDLV4.js";
+import {
+  formatPortsInFunctionText,
+  parsePortsFromFunctionText,
+  renamePortInCode,
+  syncCodeRenames,
+  updatePortsInFunctionText
+} from "./chunks/chunk-FMTLP5ZX.js";
+import {
+  GeneratedExecutionContext
+} from "./chunks/chunk-KMCAYNUM.js";
+import {
+  AmbiguousEffectError,
+  DurableExecution,
+  DurableGateYield,
+  createWorkflowRuntime,
+  isAmbiguousEffectError,
+  isDurableGateYield
+} from "./chunks/chunk-OOQG7UPP.js";
+import {
+  compileWorkflow,
+  generateCode
+} from "./chunks/chunk-F3RTZV2A.js";
+import {
+  addWorkflowToSource,
+  getAvailableWorkflows,
+  removeWorkflowFromSource,
+  toggleWorkflowExport
+} from "./chunks/chunk-YSPBPZDV.js";
+import {
+  decodeContinuation
+} from "./chunks/chunk-DCMGQP5V.js";
+import "./chunks/chunk-6KMVP6AU.js";
+import {
+  COERCE_TYPE_FOR_DATA_TYPE,
+  WorkflowValidator,
+  validator
+} from "./chunks/chunk-VQ7H33J4.js";
+import "./chunks/chunk-HKZLQJDV.js";
+import {
+  parseFunctionSignature,
+  parseReturnFields,
+  parseReturnTypeFields
+} from "./chunks/chunk-NQNLUAPO.js";
+import {
+  generateInPlace
+} from "./chunks/chunk-TAIUWKZB.js";
+import {
+  parseWorkflow,
+  parseWorkflowSourceAtPath
+} from "./chunks/chunk-INDEVYEC.js";
+import "./chunks/chunk-KU3CLJI2.js";
+import "./chunks/chunk-5Y3AIUWY.js";
+import "./chunks/chunk-CZBCCK4Y.js";
+import {
+  configureGeneratedBranding,
+  getGeneratedBranding
+} from "./chunks/chunk-AXNQRVJB.js";
+import {
+  CONTINUATION_FORMAT_VERSION,
+  ENGINE_VERSION,
+  ENVELOPE_KEYS,
+  GENERATOR_ABI,
+  MAX_CONTINUATION_BYTES,
+  MAX_CONTINUATION_DEPTH,
+  MAX_CONTINUATION_ENTRIES,
+  MAX_CONTINUATION_STRING_BYTES,
+  WireValidationError,
+  acceptContinuation,
+  assertAcceptedContinuation,
+  canonicalWireValue,
+  cloneAndFreezeWireValue,
+  continuationChecksum,
+  createContinuationEnvelope,
+  durableGateId,
+  executionAddressKey,
+  hasExactlyTheKeys,
+  isExecutionAddress,
+  isPlainObjectRecord,
+  operationKey,
+  sha256Hex,
+  structurallyValidEnvelope,
+  utf8ByteLength,
+  validateWireValue
+} from "./chunks/chunk-O2U2LO57.js";
+import "./chunks/chunk-QDE4Z7KW.js";
+import "./chunks/chunk-XAV22WD7.js";
+import {
+  countConnections,
+  countNodeTypes,
+  countNodes,
+  findDeadEndDetails,
+  findDeadEnds,
+  findDisconnectedOutputPorts,
+  findIsolatedNodes,
+  findNodesByName,
+  findPath,
+  findUnusedNodeTypes,
+  findWorkflows,
+  formatPortReference,
+  getConnectedPorts,
+  getConnections,
+  getDataDependencies,
+  getDependencies,
+  getDependents,
+  getExecutionGroups,
+  getIncomingConnections,
+  getNode,
+  getNodes,
+  getNodesByType,
+  getNodesInScope,
+  getOutgoingConnections,
+  getTopologicalOrder,
+  getTransitiveDependencies,
+  getUnconnectedPorts,
+  hasNode,
+  isConnected,
+  portReferencesEqual,
+  validatePortReference
+} from "./chunks/chunk-P2CVDGHR.js";
+import {
+  AnnotationParser,
+  MARKERS,
+  hasInPlaceMarkers,
+  parser,
+  resolveNpmNodeTypes,
+  stripGeneratedSections
+} from "./chunks/chunk-ZMGN6F3S.js";
+import "./chunks/chunk-REEYC73I.js";
+import "./chunks/chunk-4EUSHAY6.js";
+import "./chunks/chunk-4KDUEOFD.js";
+import "./chunks/chunk-DUO6H5PR.js";
+import {
+  AnnotationGenerator,
+  TagHandlerRegistry,
+  tagHandlerRegistry
+} from "./chunks/chunk-VP2P3BPA.js";
+import "./chunks/chunk-B6HQ6YS5.js";
+import {
+  PORT_TYPE_MAPPINGS,
+  getAllPortTypes,
+  getPortTypeDescription,
+  inferDataTypeFromTS,
+  isValidPortType,
+  mapToTypeScript,
+  stripOptionalUndefined
+} from "./chunks/chunk-E5WN7IGO.js";
+import {
+  getNodeTemplate,
+  getWorkflowTemplate,
+  nodeTemplates,
+  toCamelCase,
+  toPascalCase,
+  workflowTemplates
+} from "./chunks/chunk-NDSTGMKR.js";
+import "./chunks/chunk-KMWCCOUJ.js";
+import "./chunks/chunk-QYPORSLO.js";
+import {
+  BRANCHING_STRATEGIES,
+  EXECUTION_STRATEGIES,
+  KNOWN_NODETYPE_TAGS,
+  KNOWN_WORKFLOW_TAGS,
+  MIN_NODE_MAJOR,
+  RESERVED_NODE_NAMES,
+  RESERVED_PORT_NAMES,
+  SCOPED_PORT_NAMES,
+  STANDARD_JSDOC_TAGS,
+  VALID_NODE_COLORS,
+  getKnownWorkflowTags,
+  isControlFlowPort,
+  isExecutePort,
+  isExitNode,
+  isFailurePort,
+  isPseudoNode,
+  isReservedNodeName,
+  isReservedPortName,
+  isScopedFailurePort,
+  isScopedMandatoryPort,
+  isScopedPort,
+  isScopedStartPort,
+  isScopedSuccessPort,
+  isSpecialNode,
+  isStartNode,
+  isSuccessPort
+} from "./chunks/chunk-R4QGNK34.js";
+import "./chunks/chunk-SEWDMQ6Q.js";
+
+// src/validation/friendly-errors.ts
+function extractQuoted(message) {
+  const matches = message.match(/"([^"]+)"/g);
+  return matches ? matches.map((m) => m.replace(/"/g, "")) : [];
+}
+function extractTypes(message) {
+  const structuralMatch = message.match(/from (.+?) \(\w+\) to (.+?) \(\w+\)/);
+  if (structuralMatch) return { source: structuralMatch[1], target: structuralMatch[2] };
+  const fromToMatch = message.match(/from (\w+) to (\w+)/i);
+  if (fromToMatch) return { source: fromToMatch[1], target: fromToMatch[2] };
+  const structuralParenMatch = message.match(/\((.+?) \(\w+\)\) .* \((.+?) \(\w+\)\)/);
+  if (structuralParenMatch) return { source: structuralParenMatch[1], target: structuralParenMatch[2] };
+  const parenMatch = message.match(/\((\w+)\) .* \((\w+)\)/);
+  if (parenMatch) return { source: parenMatch[1], target: parenMatch[2] };
+  return null;
+}
+function buildCoerceSuggestion(message, targetType) {
+  const coerceType = COERCE_TYPE_FOR_DATA_TYPE[targetType.toUpperCase()] || targetType.toLowerCase();
+  if (!["string", "number", "boolean", "json", "object"].includes(coerceType)) return null;
+  const route = message.match(CONNECTION_ROUTE);
+  const portRefs = route ? [route[1], route[2]] : extractQuoted(message).filter((q) => PORT_REF.test(q));
+  if (portRefs.length < 2) return null;
+  return `@connect ${portRefs[0]} -> ${portRefs[1]} as ${coerceType}`;
+}
+var PORT_REF = /^[\w]+\.[\w]+$/;
+var CONNECTION_ROUTE = /([\w$]+\.[\w$]+)(?: \((?:[^()]|\([^()]*\))*\))? → ([\w$]+\.[\w$]+)/;
+function extractCyclePath(message) {
+  const match = message.match(/:\s*(.+ -> .+)/);
+  return match ? match[1] : null;
+}
+var errorMappers = {
+  MISSING_WORKFLOW_NAME(error) {
+    return {
+      title: "Missing Workflow Name",
+      explanation: "The workflow annotation is missing or has no name. Every workflow needs a name in the @flowWeaver workflow block.",
+      fix: "Add @flowWeaver workflow to the JSDoc block above your exported workflow function.",
+      code: error.code
+    };
+  },
+  MISSING_FUNCTION_NAME(error) {
+    return {
+      title: "Missing Function Name",
+      explanation: "The compiler found a @flowWeaver workflow annotation but the function is anonymous or not exported.",
+      fix: "Make sure your workflow is declared as `export function myWorkflowName(...)`, not anonymous or unexported.",
+      code: error.code
+    };
+  },
+  MISSING_REQUIRED_INPUT(error) {
+    const quoted = extractQuoted(error.message);
+    const nodeName = quoted[0] || error.node || "unknown";
+    const portName = quoted[1] || "unknown";
+    return {
+      title: "Missing Required Input",
+      explanation: `Node '${nodeName}' needs a value for '${portName}' but nothing is connected to it.`,
+      fix: `Connect an output port from another node to '${portName}' on '${nodeName}', or mark the port as optional with @input [${portName}].`,
+      code: error.code
+    };
+  },
+  STEP_PORT_TYPE_MISMATCH(error) {
+    const stepToData = error.message.match(
+      /^STEP port "([^"]+)" on node "([^"]+)" cannot connect to non-STEP port "([^"]+)"(?: \([^)]*\))? on node "([^"]+)"/
+    );
+    const dataToStep = error.message.match(
+      /^Non-STEP port "([^"]+)"(?: \([^)]*\))? on node "([^"]+)" cannot connect to STEP port "([^"]+)" on node "([^"]+)"/
+    );
+    const fix = 'STEP ports carry control flow signals (like "go next"), not data. Connect data ports to data ports and STEP ports to STEP ports.';
+    if (stepToData) {
+      const [, fromPort, fromNode, toPort, toNode] = stepToData;
+      return {
+        title: "Wrong Port Type",
+        explanation: `'${fromNode}.${fromPort}' is a STEP port: it carries a control signal, but '${toNode}.${toPort}' is a data port. Connect '${fromNode}.${fromPort}' to a STEP input such as '${toNode}.execute'.`,
+        fix,
+        code: error.code
+      };
+    }
+    if (dataToStep) {
+      const [, fromPort, fromNode, toPort, toNode] = dataToStep;
+      return {
+        title: "Wrong Port Type",
+        explanation: `'${toNode}.${toPort}' is a STEP port: it expects a control signal, but '${fromNode}.${fromPort}' carries data. Connect '${toNode}.${toPort}' to a STEP output such as '${fromNode}.onSuccess'.`,
+        fix,
+        code: error.code
+      };
+    }
+    const quoted = extractQuoted(error.message);
+    const portName = quoted[0] || "unknown";
+    return {
+      title: "Wrong Port Type",
+      explanation: `Port '${portName}' mixes a STEP (control flow) port with a data port.`,
+      fix,
+      code: error.code
+    };
+  },
+  UNKNOWN_NODE_TYPE(error) {
+    const quoted = extractQuoted(error.message);
+    const nodeTypeName = quoted[1] || quoted[0] || "unknown";
+    return {
+      title: "Unknown Node Type",
+      explanation: `Node type '${nodeTypeName}' doesn't exist. Did you forget to add @flowWeaver nodeType above the function?`,
+      fix: `Add /** @flowWeaver nodeType */ as a JSDoc comment above the function '${nodeTypeName}', or check that the function name is spelled correctly.`,
+      code: error.code
+    };
+  },
+  UNKNOWN_SOURCE_NODE(error) {
+    const quoted = extractQuoted(error.message);
+    const nodeName = quoted[0] || error.node || "unknown";
+    return {
+      title: "Missing Source Node",
+      explanation: `Connection references node '${nodeName}' which doesn't exist in this workflow.`,
+      fix: `Add a @node annotation for '${nodeName}' in the workflow JSDoc, or fix the spelling in the @connect annotation.`,
+      code: error.code
+    };
+  },
+  UNKNOWN_TARGET_NODE(error) {
+    const quoted = extractQuoted(error.message);
+    const nodeName = quoted[0] || error.node || "unknown";
+    return {
+      title: "Missing Target Node",
+      explanation: `Connection references node '${nodeName}' which doesn't exist in this workflow.`,
+      fix: `Add a @node annotation for '${nodeName}' in the workflow JSDoc, or fix the spelling in the @connect annotation.`,
+      code: error.code
+    };
+  },
+  UNKNOWN_SOURCE_PORT(error) {
+    const known = error.message.match(/^(?:Node "([^"]+)"|(Start) node) does not have output port "([^"]+)"/);
+    const quoted = extractQuoted(error.message);
+    const displayNode = known ? known[1] ?? known[2] : error.node || quoted[0] || "unknown";
+    const displayPort = known ? known[3] : quoted[1] || quoted[0] || "unknown";
+    const didYouMean = error.message.match(/Did you mean "([^"]+)"/)?.[1];
+    const hint = didYouMean ? ` Did you mean '${didYouMean}'?` : "";
+    const fix = displayNode === "Start" ? `Add '@param ${displayPort}' to the workflow JSDoc and to its params object, or fix the port name in the @connect annotation.` : `Add @output ${displayPort} to the node type's JSDoc, or check the port name in the @connect annotation.`;
+    return {
+      title: "Unknown Output Port",
+      explanation: `Port '${displayPort}' doesn't exist on node '${displayNode}'.${hint} Check the spelling or add the port to the node type.`,
+      fix,
+      code: error.code
+    };
+  },
+  UNKNOWN_TARGET_PORT(error) {
+    const known = error.message.match(/^(?:Node "([^"]+)"|(Exit) node) does not have input port "([^"]+)"/);
+    const quoted = extractQuoted(error.message);
+    const displayNode = known ? known[1] ?? known[2] : error.node || "unknown";
+    const displayPort = known ? known[3] : quoted[0] || "unknown";
+    const didYouMean = error.message.match(/Did you mean "([^"]+)"/)?.[1];
+    const hint = didYouMean ? ` Did you mean '${didYouMean}'?` : "";
+    const fix = displayNode === "Exit" ? `Add '@returns ${displayPort}' to the workflow JSDoc and to its return type, or fix the port name in the @connect annotation.` : `Add @input ${displayPort} to the node type's JSDoc, or check the port name in the @connect annotation.`;
+    return {
+      title: "Unknown Input Port",
+      explanation: `Port '${displayPort}' doesn't exist on node '${displayNode}'.${hint} Check the spelling or add the port to the node type.`,
+      fix,
+      code: error.code
+    };
+  },
+  TYPE_MISMATCH(error) {
+    const types = extractTypes(error.message);
+    const source = types?.source || "unknown";
+    const target = types?.target || "unknown";
+    const coerceSuggestion = buildCoerceSuggestion(error.message, target);
+    return {
+      title: "Type Mismatch",
+      explanation: `Type mismatch: you're connecting a ${source} to a ${target}. The value will be automatically converted, but this might cause unexpected behavior.`,
+      fix: coerceSuggestion ? `Use \`${coerceSuggestion}\` for explicit coercion, change one of the port types, or use @strictTypes to turn this into an error.` : `Add \`as <type>\` to the @connect annotation (e.g. \`as string\`), change one of the port types, or use @strictTypes to turn this into an error.`,
+      code: error.code
+    };
+  },
+  CYCLE_DETECTED(error) {
+    const cyclePath = extractCyclePath(error.message);
+    const nodeName = error.node || "unknown";
+    return {
+      title: "Circular Dependency Found",
+      explanation: `Circular dependency found. Node '${nodeName}' eventually connects back to itself, creating an infinite loop.${cyclePath ? ` Path: ${cyclePath}` : ""}`,
+      // A durable-gate workflow may contain a scoped loop, but only a bounded
+      // one; point at the scope node and its limit rather than banning it.
+      fix: "Break the cycle by removing one of the connections in the loop, or use a scoped node (like forEach) for intentional iteration. Inside a workflow that pauses at a durable gate, that scope must be bounded: give it a max/limit/attempts/iterations input.",
+      code: error.code
+    };
+  },
+  UNUSED_NODE(error) {
+    const quoted = extractQuoted(error.message);
+    const nodeName = quoted[0] || error.node || "unknown";
+    return {
+      title: "Unused Node",
+      explanation: `Node '${nodeName}' is defined but never used in the workflow. Consider removing it or connecting it.`,
+      fix: `Connect '${nodeName}' to other nodes with @connect, or remove the @node annotation if it's no longer needed.`,
+      code: error.code
+    };
+  },
+  NO_START_CONNECTIONS(error) {
+    return {
+      title: "No Start Connections",
+      explanation: "Your workflow has no connections from the Start node. Nothing will execute.",
+      fix: "Add a @connect Start.execute -> yourNode.execute annotation to kick off the workflow.",
+      code: error.code
+    };
+  },
+  NO_EXIT_CONNECTIONS(error) {
+    return {
+      title: "No Exit Connections",
+      explanation: "Your workflow has no connections to the Exit node. The workflow won't return any results.",
+      fix: "Add a @connect yourNode.onSuccess -> Exit.onSuccess annotation so the workflow produces output.",
+      code: error.code
+    };
+  },
+  DUPLICATE_NODE_NAME(error) {
+    const quoted = extractQuoted(error.message);
+    const nodeName = quoted[0] || error.node || "unknown";
+    return {
+      title: "Duplicate Node Name",
+      explanation: `Two node types have the same name '${nodeName}'. Each node type needs a unique function name.`,
+      fix: `Rename one of the '${nodeName}' functions to give it a unique name.`,
+      code: error.code
+    };
+  },
+  RESERVED_NODE_NAME(error) {
+    const quoted = extractQuoted(error.message);
+    const nodeName = quoted[0] || error.node || "unknown";
+    return {
+      title: "Reserved Name Used",
+      explanation: `'Start' and 'Exit' are reserved names. Choose a different name for your node type.`,
+      fix: `Rename '${nodeName}' to something other than 'Start' or 'Exit'. These names are used internally by the workflow engine.`,
+      code: error.code
+    };
+  },
+  RESERVED_INSTANCE_ID(error) {
+    const quoted = extractQuoted(error.message);
+    const instanceId = quoted[0] || error.node || "unknown";
+    return {
+      title: "Reserved Instance ID",
+      explanation: `Instance ID '${instanceId}' is reserved. 'Start' and 'Exit' are built-in nodes in every workflow.`,
+      fix: `Choose a different instance ID, like 'startHandler' or 'exitProcessor'.`,
+      code: error.code
+    };
+  },
+  INFERRED_NODE_TYPE(error) {
+    const quoted = extractQuoted(error.message);
+    const nodeTypeName = quoted[0] || error.node || "unknown";
+    return {
+      title: "Inferred Node Type",
+      explanation: `Node type '${nodeTypeName}' was auto-inferred from the function signature. It works, but you lose explicit control over port names, types, and ordering.`,
+      fix: `Add /** @flowWeaver nodeType @expression */ above the function for explicit port control.`,
+      code: error.code
+    };
+  },
+  INVALID_SCOPE_NAME(error) {
+    const quoted = extractQuoted(error.message);
+    const portName = quoted[0] || "unknown";
+    const nodeName = quoted[1] || error.node || "unknown";
+    const scopeName = quoted[2] || "unknown";
+    return {
+      title: "Invalid Scope Name",
+      explanation: `Port '${portName}' on node type '${nodeName}' uses scope '${scopeName}', which is not a JavaScript identifier. Scope names become identifiers in the generated code.`,
+      fix: `Rename the scope in every 'scope:${scopeName}' modifier and in the matching callback parameter to letters, digits, '_' or '$', not starting with a digit.`,
+      code: error.code
+    };
+  },
+  EXPRESSION_SYNTAX(error) {
+    const quoted = extractQuoted(error.message);
+    const portName = quoted[0] || "unknown";
+    const where = quoted[1] || error.node || "unknown";
+    return {
+      title: "Expression Is Not JavaScript",
+      explanation: `The expression for '${portName}' on '${where}' does not parse as JavaScript. ${error.message.replace(/^.*?is not a JavaScript expression: /, "")}`,
+      fix: `An [expr:] value is JavaScript. Text needs quotes inside the attribute (timeout="'24h'"). An upstream port is read as node.port (agentId="prep.agentId"). See advanced-annotations.`,
+      code: error.code
+    };
+  },
+  TYPE_INCOMPATIBLE(error) {
+    const types = extractTypes(error.message);
+    const source = types?.source || "unknown";
+    const target = types?.target || "unknown";
+    const coerceSuggestion = buildCoerceSuggestion(error.message, target);
+    return {
+      title: "Type Incompatible",
+      explanation: `Type mismatch: ${source} to ${target}. With @strictTypes enabled, this is an error instead of a warning.`,
+      fix: coerceSuggestion ? `Use \`${coerceSuggestion}\` for explicit coercion, change one of the port types, or remove @strictTypes to allow implicit coercions.` : `Add \`as <type>\` to the @connect annotation (e.g. \`as number\`), change one of the port types, or remove @strictTypes to allow implicit coercions.`,
+      code: error.code
+    };
+  },
+  UNUSUAL_TYPE_COERCION(error) {
+    const types = extractTypes(error.message);
+    const source = types?.source || "unknown";
+    const target = types?.target || "unknown";
+    const coerceSuggestion = buildCoerceSuggestion(error.message, target);
+    return {
+      title: "Unusual Type Coercion",
+      explanation: `Converting ${source} to ${target} is technically valid but semantically unusual and may produce unexpected behavior.`,
+      fix: coerceSuggestion ? `If intentional, use \`${coerceSuggestion}\` for explicit coercion, or use @strictTypes to enforce type safety.` : `If intentional, add \`as <type>\` to the @connect annotation, or use @strictTypes to enforce type safety.`,
+      code: error.code
+    };
+  },
+  MULTIPLE_CONNECTIONS_TO_INPUT(error) {
+    const quoted = extractQuoted(error.message);
+    const portName = quoted[0] || "unknown";
+    const nodeName = quoted[1] || error.node || "unknown";
+    return {
+      title: "Multiple Input Connections",
+      explanation: `Input port '${portName}' on node '${nodeName}' has multiple connections. A data input takes one connection unless the port declares how to combine several.`,
+      fix: `Remove extra connections to '${nodeName}.${portName}', declare a merge strategy on the port with '@input ${portName} [mergeStrategy:FIRST|LAST|COLLECT|MERGE|CONCAT]' on the node type, or add a merge node before it.`,
+      code: error.code
+    };
+  },
+  SCOPE_MISSING_REQUIRED_INPUT(error) {
+    const quoted = extractQuoted(error.message);
+    const childId = quoted[0] || error.node || "unknown";
+    const portName = quoted[1] || "unknown";
+    const scopeName = quoted[2] || "unknown";
+    const parentId = quoted[3] || "unknown";
+    return {
+      title: "Scope Child Missing Input",
+      explanation: `Child node '${childId}' inside scope '${scopeName}' of '${parentId}' has a required input '${portName}' with no connection.`,
+      fix: `Connect the parent's scoped output to '${childId}.${portName}' within the scope, or mark the port as optional.`,
+      code: error.code
+    };
+  },
+  SCOPE_UNUSED_INPUT(error) {
+    const quoted = extractQuoted(error.message);
+    const portName = quoted[0] || "unknown";
+    const parentId = quoted[1] || error.node || "unknown";
+    const scopeName = quoted[2] || "unknown";
+    return {
+      title: "Scope Input Unused",
+      explanation: `Scoped input '${portName}' on '${parentId}' expects data back from inner nodes, but nothing connects to it within scope '${scopeName}'.`,
+      fix: `Connect an inner node's output to '${parentId}.${portName}:${scopeName}' to return data from the scope.`,
+      code: error.code
+    };
+  },
+  SCOPE_WRONG_SCOPE_NAME(error) {
+    const quoted = extractQuoted(error.message);
+    const portRef2 = quoted[0] || "unknown";
+    const nodeName = quoted[2] || "unknown";
+    return {
+      title: "Invalid Scope Qualifier",
+      explanation: `A connection at '${portRef2}' uses an invalid scope name. Node '${nodeName}' doesn't define that scope.`,
+      fix: `Check the scope names defined on the node type. Fix the :scopeName qualifier in the @connect annotation to match an existing scope.`,
+      code: error.code
+    };
+  },
+  SCOPE_CONNECTION_OUTSIDE(error) {
+    return {
+      title: "Scope Connection Leak",
+      explanation: `A scoped connection references a node that is outside the scope boundary. Scoped connections must stay within the scope.`,
+      fix: `Move the target node inside the scope (declare it with the scope parent in @node), or remove the scope qualifier from the connection.`,
+      code: error.code
+    };
+  },
+  SCOPE_PORT_TYPE_MISMATCH(error) {
+    const quoted = extractQuoted(error.message);
+    return {
+      title: "Scope Port Type Mismatch",
+      explanation: `Type mismatch within scope '${quoted[0] || "unknown"}'. The parent's scoped port and the child's port have incompatible types.`,
+      fix: `Change one of the port types to match, or add a transformation node inside the scope.`,
+      code: error.code
+    };
+  },
+  SCOPE_UNKNOWN_PORT(error) {
+    const quoted = extractQuoted(error.message);
+    const portName = quoted[0] || "unknown";
+    return {
+      title: "Unknown Scoped Port",
+      explanation: `Port '${portName}' is referenced in a scoped connection but doesn't exist as a scoped port on that node, or belongs to a different scope.`,
+      fix: `Add the port as a scoped port with @output ${portName} scope:scopeName, or fix the port name in the @connect annotation.`,
+      code: error.code
+    };
+  },
+  SCOPE_ORPHANED_CHILD(error) {
+    const quoted = extractQuoted(error.message);
+    const childId = quoted[0] || error.node || "unknown";
+    const scopeName = quoted[1] || "unknown";
+    const parentId = quoted[2] || "unknown";
+    return {
+      title: "Orphaned Scope Child",
+      explanation: `Node '${childId}' is declared inside scope '${scopeName}' of '${parentId}' but has no scoped connections. It won't receive data from or return data to the scope.`,
+      fix: `Connect the parent's scoped output ports to '${childId}' inputs, and connect '${childId}' outputs back to the parent's scoped input ports.`,
+      code: error.code
+    };
+  },
+  OBJECT_TYPE_MISMATCH(error) {
+    const quoted = extractQuoted(error.message);
+    const sourceType = quoted[0] || "unknown";
+    const targetType = quoted[1] || "unknown";
+    return {
+      title: "Object Shape Mismatch",
+      explanation: `The object shapes don't match. The source provides '${sourceType}' but the target expects '${targetType}'.`,
+      fix: "Verify the object structures are compatible. Add a transformation node if you need to reshape the data.",
+      code: error.code
+    };
+  },
+  MUTABLE_NODE_TYPE_BINDING(error) {
+    const quoted = extractQuoted(error.message);
+    const nodeName = quoted[0] || error.node || "unknown";
+    const bindingKind = quoted[1] || "let";
+    return {
+      title: "Mutable Node Binding",
+      explanation: `Node type '${nodeName}' is declared with '${bindingKind}' which allows accidental reassignment at runtime.`,
+      fix: `Use 'function ${nodeName}(...)' or 'const ${nodeName} = ...' instead. Node types must be immutable.`,
+      code: error.code
+    };
+  },
+  UNUSED_OUTPUT_PORT(error) {
+    const quoted = extractQuoted(error.message);
+    const portName = quoted[0] || "unknown";
+    const nodeName = quoted[1] || error.node || "unknown";
+    return {
+      title: "Unused Output Port",
+      explanation: `Output port '${portName}' on node '${nodeName}' is not connected to anything. Its data will be discarded.`,
+      fix: `Connect '${nodeName}.${portName}' to another node's input, or remove the @output annotation if it's not needed.`,
+      code: error.code
+    };
+  },
+  UNREACHABLE_EXIT_PORT(error) {
+    const quoted = extractQuoted(error.message);
+    const portName = quoted[0] || "unknown";
+    return {
+      title: "Unreachable Exit Port",
+      explanation: `Exit port '${portName}' has no incoming data. The workflow will return undefined for this output.`,
+      fix: `Add a @connect annotation to send data to Exit.${portName}, or remove the @returns ${portName} annotation.`,
+      code: error.code
+    };
+  },
+  HTTP_PARAM_UNKNOWN(error) {
+    const quoted = extractQuoted(error.message);
+    const param = (quoted[0] || ":param").replace(/^:/, "");
+    return {
+      title: "Route Parameter Is Not a Workflow Parameter",
+      explanation: `The @http route has a ':${param}' segment, but the workflow has no @param named '${param}', so there is nothing for the path to bind to.`,
+      fix: `Name a segment after one of the workflow's @param entries, or add '@param ${param}' to the workflow and connect it.`,
+      code: error.code
+    };
+  },
+  MULTIPLE_EXIT_CONNECTIONS(error) {
+    const quoted = extractQuoted(error.message);
+    const portName = quoted[0] || "unknown";
+    return {
+      title: "Multiple Exit Connections",
+      explanation: `Exit port '${portName}' receives data from multiple nodes. Only one value will be used, which may lead to unpredictable results.`,
+      fix: `Use separate Exit ports for each source, or add a merge node to combine the values before connecting to Exit.${portName}.`,
+      code: error.code
+    };
+  },
+  ANNOTATION_SIGNATURE_MISMATCH(error) {
+    const quoted = extractQuoted(error.message);
+    const portName = quoted[0] || "unknown";
+    const nodeName = quoted[1] || error.node || "unknown";
+    return {
+      title: "Optional Port Mismatch",
+      explanation: `Port '${portName}' on '${nodeName}' is optional in the TypeScript signature but required in the annotation.`,
+      fix: `Use @input [${portName}] (with brackets) to mark the port as optional in the annotation, matching the TypeScript signature.`,
+      code: error.code
+    };
+  },
+  ANNOTATION_SIGNATURE_TYPE_MISMATCH(error) {
+    const quoted = extractQuoted(error.message);
+    const portName = quoted[0] || "unknown";
+    const nodeName = quoted[1] || error.node || "unknown";
+    const annotationType = quoted[2] || "unknown";
+    const sigType = quoted[3] || "unknown";
+    return {
+      title: "Annotation Type Mismatch",
+      explanation: `Port '${portName}' on '${nodeName}' has type '${annotationType}' in the annotation but '${sigType}' in the TypeScript signature.`,
+      fix: `Update the @input/@output annotation type to match the function signature, or change the signature type. The annotation and TypeScript types should agree.`,
+      code: error.code
+    };
+  },
+  // ── Agent-specific rules ──────────────────────────────────────────────
+  AGENT_LLM_MISSING_ERROR_HANDLER(error) {
+    const nodeName = error.node || "unknown";
+    return {
+      title: "LLM Missing Error Handler",
+      explanation: `LLM node '${nodeName}' has no error handler. LLM calls can fail due to rate limits, timeouts, or model errors, and failures will be silently swallowed.`,
+      fix: `Connect ${nodeName}.onFailure to a retry node, fallback handler, or Exit.onFailure to handle LLM errors gracefully.`,
+      code: error.code
+    };
+  },
+  AGENT_UNGUARDED_TOOL_EXECUTOR(error) {
+    const nodeName = error.node || "unknown";
+    return {
+      title: "Unguarded Tool Executor",
+      explanation: `Tool executor '${nodeName}' has no human approval gate upstream. If it performs destructive actions (writes, deletes, sends), this could be unsafe.`,
+      fix: `Add a human-approval node before '${nodeName}' to gate destructive tool calls. If this tool is read-only, you can safely ignore this warning.`,
+      code: error.code
+    };
+  },
+  AGENT_MISSING_MEMORY_IN_LOOP(error) {
+    const quoted = extractQuoted(error.message);
+    const scopeName = quoted[0] || "the loop";
+    return {
+      title: "No Memory in Agent Loop",
+      explanation: `Loop scope '${scopeName}' contains an LLM node but no conversation memory. The LLM will lose context between loop iterations.`,
+      fix: `Add a conversation-memory node inside the loop to persist messages between iterations, so the LLM retains context across loop cycles.`,
+      code: error.code
+    };
+  },
+  AGENT_LLM_NO_FALLBACK(error) {
+    const nodeName = error.node || "unknown";
+    return {
+      title: "LLM Failure Goes to Exit",
+      explanation: `LLM node '${nodeName}' routes failures directly to Exit, meaning any LLM error immediately aborts the entire workflow.`,
+      fix: `Add a retry node or fallback LLM provider between ${nodeName}.onFailure and Exit to improve resilience against transient LLM failures.`,
+      code: error.code
+    };
+  },
+  AGENT_TOOL_NO_OUTPUT_HANDLING(error) {
+    const nodeName = error.node || "unknown";
+    return {
+      title: "Tool Results Discarded",
+      explanation: `Tool executor '${nodeName}' computes results but none of its data output ports are connected. Tool results are being thrown away.`,
+      fix: `Connect the data output ports of '${nodeName}' (e.g., result, resultMessage) to downstream nodes, or remove this tool executor if its results aren't needed.`,
+      code: error.code
+    };
+  },
+  // ── Design quality rules ─────────────────────────────────────────────
+  DESIGN_ASYNC_NO_ERROR_PATH(error) {
+    const nodeName = error.node || "unknown";
+    return {
+      title: "Async Node Missing Error Path",
+      explanation: `Async node '${nodeName}' has no failure handling. Async operations (network calls, file I/O, AI calls) can fail. A normal-mode node's onFailure is silently lost. An @expression node's throw aborts the run with the error.`,
+      fix: `For a normal-mode node, connect ${nodeName}.onFailure to an error handler, retry node, or Exit.onFailure. For an @expression node, wiring onFailure does nothing about a throw: to route the failure, write the node in normal mode and return onFailure, or suppress this warning if aborting is intended.`,
+      code: error.code
+    };
+  },
+  DESIGN_SCOPE_NO_FAILURE_EXIT(error) {
+    const nodeName = error.node || "unknown";
+    return {
+      title: "Scope Missing Failure Exit",
+      explanation: `Scope node '${nodeName}' has no failure path out. If all iterations fail, execution stalls with no error surfaced upstream.`,
+      fix: `Connect ${nodeName}.onFailure to an error handler or Exit.onFailure so scope failures propagate.`,
+      code: error.code
+    };
+  },
+  DESIGN_UNBOUNDED_RETRY(error) {
+    const nodeName = error.node || "unknown";
+    return {
+      title: "Unbounded Retry Loop",
+      explanation: `Scope node '${nodeName}' looks like a retry loop but has no visible attempt limit input. This could loop indefinitely on persistent failures.`,
+      fix: `Add a maxAttempts or retries input port to the node type, or use a counter to break out of the loop after N attempts.`,
+      code: error.code
+    };
+  },
+  DESIGN_FANOUT_NO_FANIN(error) {
+    const nodeName = error.node || "unknown";
+    return {
+      title: "Fan-Out Without Fan-In",
+      explanation: `Node '${nodeName}' fans out to multiple step targets, but those paths never merge back to a shared downstream node. Data from parallel branches may be lost.`,
+      fix: `Add a merge node downstream where the parallel branches converge, or wire them to a shared node before Exit.`,
+      code: error.code
+    };
+  },
+  DESIGN_EXIT_DATA_UNREACHABLE(error) {
+    const quoted = extractQuoted(error.message);
+    const portName = quoted[0] || "unknown";
+    return {
+      title: "Exit Data Unreachable",
+      explanation: `Exit port '${portName}' has no incoming data connection and no pull-execution node provides it. The workflow will return undefined for this output.`,
+      fix: `Connect a node's data output to Exit.${portName}, or add a pull-execution node that computes this value on demand.`,
+      code: error.code
+    };
+  },
+  DESIGN_PULL_CANDIDATE(error) {
+    const nodeName = error.node || "unknown";
+    return {
+      title: "Pull Execution Candidate",
+      explanation: `Node '${nodeName}' has no incoming step connection but its data outputs are consumed downstream. Without a step trigger or pullExecution, this node may never execute.`,
+      fix: `Add [pullExecution: execute] to the @node annotation so the node runs on demand when downstream nodes read its output.`,
+      code: error.code
+    };
+  },
+  DESIGN_PULL_UNUSED(error) {
+    const nodeName = error.node || "unknown";
+    return {
+      title: "Unused Pull Execution",
+      explanation: `Node '${nodeName}' is marked with pullExecution but no downstream node reads its data output. The node will never execute since pull execution requires a consumer.`,
+      fix: `Connect a data output from '${nodeName}' to a downstream node, or remove the pullExecution config if the node isn't needed.`,
+      code: error.code
+    };
+  },
+  DURABLE_CLOSURE_INVALID(error) {
+    const message = error.message;
+    let fix = "Keep each gate/effect in one branch region reading only from its immediate predecessor. Thread shared values through the chain rather than wiring them around a gate. See the durable-gates topic.";
+    if (message.includes("needs a visible attempt limit")) {
+      fix = "A loop inside a durable workflow is allowed once it is bounded: give the scope node a max/limit/attempts/iterations input (like the maxSteps on the ReAct agent) so a resumed run has a finite, inspectable iteration space. The iteration ordinal is reconstructed from committed state on resume, so the bound is all that is missing. See the durable-gates topic.";
+    } else if (message.includes("do not support pull or lazy execution")) {
+      fix = "Remove pullExecution from the named nodes, or give them a step connection so they run in order. A yielded continuation needs every predecessor already compiled into it. See the durable-gates topic.";
+    } else if (message.includes("Durable classification errors")) {
+      fix = "Give every reachable node exactly one of @durablePure, @durableGate or @durableEffect. An @expression node is pure automatically; a normal-mode node that only computes needs @durablePure. See the durable-gates topic.";
+    } else if (message.includes("effect contract")) {
+      fix = "A @durableEffect node takes an operationKey parameter and returns { result, receipt }, so the engine can replay the receipt instead of running it twice. See the durable-gates topic.";
+    }
+    return { title: "Invalid Durable Closure", explanation: message, fix, code: error.code };
+  },
+  STUB_NODE(error) {
+    const nodeName = error.node || "unknown";
+    const typeMatch = error.message.match(/stub type "([^"]+)"/);
+    const typeName = typeMatch?.[1] || "unknown";
+    return {
+      title: "Stub Node",
+      explanation: `Node '${nodeName}' uses node type '${typeName}', which has no implementation yet. The workflow cannot run until it is implemented.`,
+      fix: `Implement '${typeName}' as a @flowWeaver nodeType function, or validate with draft mode (fw_validate draft: true) to check structure while it is still a stub.`,
+      code: error.code
+    };
+  },
+  CROSS_SCOPE_CONNECTION(error) {
+    const ends = error.message.match(/from "([^"]+)" \(in ([^)]+)\) to "([^"]+)" \(in ([^)]+)\)/);
+    const from = ends?.[1] || "unknown";
+    const fromCtx = ends?.[2] || "one scope";
+    const to = ends?.[3] || "unknown";
+    const toCtx = ends?.[4] || "another scope";
+    return {
+      title: "Cross-Scope Connection",
+      explanation: `Connection '${from}' \u2192 '${to}' links a node in ${fromCtx} to a node in ${toCtx}. Nodes in different scopes cannot connect directly. Data crosses a scope boundary only through the scope owner's scoped ports.`,
+      fix: `Route the value through the scope owner: connect '${from}' to one of the owner's scoped output ports, and read it inside the scope from there. Or move both nodes into the same scope.`,
+      code: error.code
+    };
+  },
+  SUPPRESS_UNKNOWN_CODE(error) {
+    const nodeName = error.node || "unknown";
+    const codeMatch = error.message.match(/suppresses '([^']+)'/);
+    const bad = codeMatch?.[1] || "unknown";
+    const corrected = bad.includes(",") ? `[suppress: ${bad.split(",").map((c) => `"${c.trim()}"`).join(", ")}]` : `[suppress: "<CODE>"]`;
+    return {
+      title: "Unknown Suppress Code",
+      explanation: `Node '${nodeName}' lists '${bad}' in [suppress: ...], but that cannot be a validation code, so nothing is suppressed. Codes are separate string literals, not one comma-joined string.`,
+      fix: `Write each code as its own string: ${corrected}.`,
+      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_TYPE_FOR_DATA_TYPE[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";
+    const target = types?.target || "unknown";
+    const coerceSuggestion = buildCoerceSuggestion(error.message, target);
+    return {
+      title: "Lossy Type Conversion",
+      explanation: `Converting ${source} to ${target} may lose data or produce unexpected results (e.g., NaN, truncation).`,
+      fix: coerceSuggestion ? `Use \`${coerceSuggestion}\` for explicit coercion, or use @strictTypes to enforce type safety.` : `Add \`as <type>\` to the @connect annotation for explicit conversion, or use @strictTypes to enforce type safety.`,
+      code: error.code
+    };
+  },
+  INVALID_EXIT_PORT_TYPE(error) {
+    const portName = error.message.match(/Exit port '([^']+)'/)?.[1] || extractQuoted(error.message)[0] || "onSuccess";
+    return {
+      title: "Invalid Exit Port Type",
+      explanation: `Exit port '${portName}' must be STEP type (control flow signal), but a different type was found. onSuccess and onFailure are control flow ports, not data ports.`,
+      fix: `Connect a STEP-type output (like onSuccess or onFailure) to Exit.${portName}. Don't connect data ports to control flow ports.`,
+      code: error.code
+    };
+  },
+  // ── Annotation validation rules ──────────────────────────────────────
+  DUPLICATE_INSTANCE_ID(error) {
+    const quoted = extractQuoted(error.message);
+    const instanceId = quoted[0] || error.node || "unknown";
+    return {
+      title: "Duplicate Instance ID",
+      explanation: `Two @node declarations use the same ID '${instanceId}'. Each node instance needs a unique ID within its workflow.`,
+      fix: `Rename one of the '${instanceId}' instances to give it a unique ID.`,
+      code: error.code
+    };
+  },
+  DUPLICATE_CONNECTION(error) {
+    return {
+      title: "Duplicate Connection",
+      explanation: `The same connection is declared twice. ${error.message}`,
+      fix: `Remove the duplicate @connect annotation.`,
+      code: error.code
+    };
+  },
+  INVALID_COLOR(error) {
+    const quoted = extractQuoted(error.message);
+    const color = quoted[1] || quoted[0] || "unknown";
+    return {
+      title: "Invalid Color",
+      explanation: `Color '${color}' is not a recognized node color. Check the spelling or use a valid color name.`,
+      fix: `Use one of the valid colors: blue, purple, cyan, orange, pink, green, red, yellow, teal.`,
+      code: error.code
+    };
+  },
+  INVALID_ICON(error) {
+    const quoted = extractQuoted(error.message);
+    const icon = quoted[1] || quoted[0] || "unknown";
+    return {
+      title: "Invalid Icon",
+      explanation: `Icon '${icon}' is not a Material Symbols name. Check the spelling.`,
+      fix: `Use a Material Symbols name (fonts.google.com/icons), in snake_case or camelCase: flag, database, swap_horiz, smart_toy.`,
+      code: error.code
+    };
+  },
+  INVALID_PORT_TYPE(error) {
+    const quoted = extractQuoted(error.message);
+    const portName = quoted[0] || "unknown";
+    const typeName = quoted[2] || quoted[1] || "unknown";
+    return {
+      title: "Invalid Port Type",
+      explanation: `Port '${portName}' has an unrecognized type '${typeName}'.`,
+      fix: `Use a valid port type: STRING, NUMBER, BOOLEAN, ARRAY, OBJECT, FUNCTION, ANY, or STEP.`,
+      code: error.code
+    };
+  },
+  INVALID_PORT_CONFIG_REF(error) {
+    const quoted = extractQuoted(error.message);
+    const instanceId = quoted[0] || error.node || "unknown";
+    const portName = quoted[1] || "unknown";
+    return {
+      title: "Invalid Port Config Reference",
+      explanation: `Instance '${instanceId}' references port '${portName}' in a portOrder or portLabel annotation, but this port doesn't exist on the node type.`,
+      fix: `Check the port name spelling, or remove the port configuration if the port was renamed or removed.`,
+      code: error.code
+    };
+  },
+  INVALID_EXECUTE_WHEN(error) {
+    const quoted = extractQuoted(error.message);
+    const value = quoted[1] || quoted[0] || "unknown";
+    return {
+      title: "Invalid Execution Strategy",
+      explanation: `@executeWhen value '${value}' is not recognized.`,
+      fix: `Use one of: CONJUNCTION (all inputs), DISJUNCTION (any input), or CUSTOM (custom logic).`,
+      code: error.code
+    };
+  },
+  SCOPE_EMPTY(error) {
+    const quoted = extractQuoted(error.message);
+    const scopeName = quoted[0] || "unknown";
+    const nodeName = quoted[1] || error.node || "unknown";
+    return {
+      title: "Empty Scope",
+      explanation: `Scope '${scopeName}' on node '${nodeName}' has no child nodes declared inside it. The scope won't iterate over anything.`,
+      fix: `Add child nodes to the scope with @scope ${scopeName} [childId1, childId2], or remove the scope if it's not needed.`,
+      code: error.code
+    };
+  },
+  SCOPE_INCONSISTENT(error) {
+    const quoted = extractQuoted(error.message);
+    const instanceId = quoted[0] || error.node || "unknown";
+    return {
+      title: "Scope Conflict",
+      explanation: `Instance '${instanceId}' is assigned to multiple scopes. A node can only belong to one scope at a time.`,
+      fix: `Remove '${instanceId}' from one of the conflicting @scope declarations.`,
+      code: error.code
+    };
+  }
+};
+function getFriendlyError(error) {
+  const mapper = errorMappers[error.code];
+  if (!mapper) return null;
+  return mapper(error);
+}
+function formatFriendlyDiagnostics(errors) {
+  if (errors.length === 0) return "";
+  const lines = [];
+  for (const error of errors) {
+    const friendly = getFriendlyError(error);
+    const severity = error.type === "error" ? "ERROR" : "WARNING";
+    if (friendly) {
+      lines.push(`[${severity}] ${friendly.title}`);
+      lines.push(`  ${friendly.explanation}`);
+      lines.push(`  How to fix: ${friendly.fix}`);
+      lines.push(`  Code: ${friendly.code}`);
+    } else {
+      lines.push(`[${severity}] ${error.code}`);
+      lines.push(`  ${error.message}`);
+    }
+    lines.push("");
+  }
+  return lines.join("\n");
+}
+
+// src/generator/workflow-generator.ts
+import * as path from "node:path";
+var WorkflowGenerator = class {
+  async generate(filePath, workflowName, options = {}) {
+    const { production = false, sourceMap = false } = options;
+    const parseResult = await this.parse(filePath, workflowName);
+    this.validate(parseResult.ast);
+    if (sourceMap) {
+      return generateCode(parseResult.ast, { production, sourceMap: true, allWorkflows: parseResult.allWorkflows });
+    }
+    return generateCode(parseResult.ast, { production, allWorkflows: parseResult.allWorkflows });
+  }
+  async parse(filePath, workflowName) {
+    const parseResult = await parseWorkflow(filePath, { workflowName, projectDir: path.dirname(filePath) });
+    if (parseResult.errors.length > 0) {
+      throw new Error(
+        `Workflow parsing failed with ${parseResult.errors.length} error(s):
+${parseResult.errors.map((e) => `  - ${e}`).join("\n")}`
+      );
+    }
+    return parseResult;
+  }
+  validate(ast) {
+    const validation = validateWorkflow(ast);
+    if (!validation.valid) {
+      const lines = validation.errors.map((error) => `  - ${error.message}${error.node ? ` (node: ${error.node})` : ""}`);
+      throw new Error(`Workflow validation failed with ${validation.errors.length} error(s):
+${lines.join("\n")}`);
+    }
+    return validation;
+  }
+};
+var generator = new WorkflowGenerator();
+export {
+  AmbiguousEffectError,
+  AnnotationGenerator,
+  AnnotationParser,
+  BRANCHING_STRATEGIES,
+  CONTINUATION_FORMAT_VERSION,
+  ConnectionBuilder,
+  DurableExecution,
+  DurableGateYield,
+  ENGINE_VERSION,
+  ENVELOPE_KEYS,
+  EXECUTION_STRATEGIES,
+  GENERATOR_ABI,
+  GeneratedExecutionContext,
+  IMPACT_COLORS,
+  IMPACT_DESCRIPTIONS,
+  KNOWN_NODETYPE_TAGS,
+  KNOWN_WORKFLOW_TAGS,
+  MARKERS,
+  MAX_CONTINUATION_BYTES,
+  MAX_CONTINUATION_DEPTH,
+  MAX_CONTINUATION_ENTRIES,
+  MAX_CONTINUATION_STRING_BYTES,
+  MIN_NODE_MAJOR,
+  NodeInstanceBuilder,
+  NodeTypeBuilder,
+  PORT_TYPE_MAPPINGS,
+  RESERVED_NODE_NAMES,
+  RESERVED_PORT_NAMES,
+  SCOPED_PORT_NAMES,
+  STANDARD_JSDOC_TAGS,
+  TagHandlerRegistry,
+  VALID_NODE_COLORS,
+  ValidationRuleRegistry,
+  WireValidationError,
+  WorkflowBuilder,
+  WorkflowDiffer,
+  WorkflowGenerator,
+  WorkflowValidator,
+  acceptContinuation,
+  addConnection,
+  addConnections,
+  addNode,
+  addNodeType,
+  addNodes,
+  addToScope,
+  addWorkflowToSource,
+  applyModifyOperation,
+  assertAcceptedContinuation,
+  assertNodeExists,
+  assertNodeNotExists,
+  assertNodeTypeExists,
+  canonicalWireValue,
+  cloneAndFreezeWireValue,
+  cloneWorkflow,
+  compileWorkflow,
+  configureGeneratedBranding,
+  continuationChecksum,
+  countConnections,
+  countNodeTypes,
+  countNodes,
+  createContinuationEnvelope,
+  createScope,
+  createWorkflow,
+  createWorkflowRuntime,
+  decodeContinuation,
+  durableGateId,
+  executionAddressKey,
+  findDeadEndDetails,
+  findDeadEnds,
+  findDisconnectedOutputPorts,
+  findIsolatedNodes,
+  findNodesByName,
+  findPath,
+  findUnusedNodeTypes,
+  findWorkflows,
+  formatDiff,
+  formatFriendlyDiagnostics,
+  formatPortReference,
+  formatPortsInFunctionText,
+  fromAST,
+  generateCode,
+  generateInPlace,
+  generateNodeFromTemplate,
+  generateUniqueNodeId,
+  generateWorkflowFromTemplate,
+  generator,
+  getAllPortTypes,
+  getAvailableCommands,
+  getAvailableWorkflows,
+  getConnectedPorts,
+  getConnections,
+  getCriticalConnections,
+  getDataDependencies,
+  getDependencies,
+  getDependents,
+  getExecutionGroups,
+  getFriendlyError,
+  getGeneratedBranding,
+  getImpactReasons,
+  getIncomingConnections,
+  getKnownWorkflowTags,
+  getNode,
+  getNodeTemplate,
+  getNodeType,
+  getNodeTypeChanges,
+  getNodes,
+  getNodesByType,
+  getNodesInScope,
+  getOutgoingConnections,
+  getPortTypeDescription,
+  getTopologicalOrder,
+  getTransitiveDependencies,
+  getUnconnectedPorts,
+  getWorkflowTemplate,
+  hasBreakingChanges,
+  hasExactlyTheKeys,
+  hasInPlaceMarkers,
+  hasNode,
+  hasNodeType,
+  inferDataTypeFromTS,
+  isAmbiguousEffectError,
+  isConnected,
+  isControlFlowPort,
+  isDurableGateYield,
+  isExecutePort,
+  isExecutionAddress,
+  isExitNode,
+  isFailurePort,
+  isPlainObjectRecord,
+  isPseudoNode,
+  isReservedNodeName,
+  isReservedPortName,
+  isScopedFailurePort,
+  isScopedMandatoryPort,
+  isScopedPort,
+  isScopedStartPort,
+  isScopedSuccessPort,
+  isSpecialNode,
+  isStartNode,
+  isSuccessPort,
+  isValidPortType,
+  listNodeTemplates,
+  listNodeTypes,
+  listWorkflowTemplates,
+  mapToTypeScript,
+  moveToScope,
+  nodeInstance,
+  nodeTemplates,
+  nodeType,
+  operationKey,
+  parseFunctionSignature,
+  parsePortsFromFunctionText,
+  parseReturnFields,
+  parseReturnTypeFields,
+  parseWorkflow,
+  parseWorkflowSourceAtPath,
+  parser,
+  port,
+  portRef,
+  portReferencesEqual,
+  reconnect,
+  removeAllConnections,
+  removeConnection,
+  removeFromScope,
+  removeNode,
+  removeNodeType,
+  removeNodes,
+  removeScope,
+  removeWorkflowFromSource,
+  renameNode,
+  renameNodeType,
+  renamePortInCode,
+  renameWorkflow,
+  replaceConnections,
+  replaceNodeTypes,
+  resolveNpmNodeTypes,
+  runCommand,
+  setInstancePortConfigs,
+  setNodeConfig,
+  setNodeLabel,
+  setNodeMinimized,
+  setNodeSize,
+  setOutputFileType,
+  setStartExitPorts,
+  setWorkflowDescription,
+  setWorkflowMetadata,
+  setWorkflowPorts,
+  sha256Hex,
+  stripGeneratedSections,
+  stripOptionalUndefined,
+  structurallyValidEnvelope,
+  swapNodeInstancePortOrder,
+  swapPortOrder,
+  syncCodeRenames,
+  tagHandlerRegistry,
+  toCamelCase,
+  toPascalCase,
+  toggleWorkflowExport,
+  transformWorkflow,
+  updateNode,
+  updateNodeType,
+  updatePortsInFunctionText,
+  utf8ByteLength,
+  validateModifyParams,
+  validatePortReference,
+  validateWireValue,
+  validateWorkflow,
+  validationRuleRegistry,
+  validator,
+  withMinimalValidation,
+  withValidation,
+  withoutValidation,
+  workflow,
+  workflowTemplates
+};