@synergenius/flow-weaver 0.33.1 → 0.44.0

package/dist/chunks/chunk-ZMGN6F3S.js

@@ -0,0 +1,4256 @@
+import {
+  COERCE_TYPE_MAP,
+  COERCION_NODE_TYPES,
+  collectModuleBindings,
+  expandExpressionReferences
+} from "./chunk-4KDUEOFD.js";
+import {
+  getErrorMessage
+} from "./chunk-DUO6H5PR.js";
+import {
+  assignImplicitPortOrders,
+  generateJSDocPortTag,
+  impliedPathDataEdgesInto,
+  tagHandlerRegistry
+} from "./chunk-VP2P3BPA.js";
+import {
+  extractFunctionLikes,
+  getPackageExports,
+  getSharedProject,
+  nestedAnnotationWarnings,
+  resolvePackageTypesPath
+} from "./chunk-B6HQ6YS5.js";
+import {
+  inferDataTypeFromTS,
+  isValidPortType,
+  stripOptionalUndefined
+} from "./chunk-E5WN7IGO.js";
+import {
+  parseCancelOnLine,
+  parseCoerceLine,
+  parseConnectLine,
+  parseFanInLine,
+  parseFanOutLine,
+  parseMapLine,
+  parseNodeLine,
+  parsePathLine,
+  parseRetriesLine,
+  parseScopeLine,
+  parseThrottleLine,
+  parseTimeoutLine,
+  parseTriggerLine
+} from "./chunk-KMWCCOUJ.js";
+import {
+  parsePortLine
+} from "./chunk-QYPORSLO.js";
+import {
+  EXECUTION_STRATEGIES,
+  KNOWN_NODETYPE_TAGS,
+  RESERVED_PORT_NAMES,
+  STANDARD_JSDOC_TAGS,
+  getKnownWorkflowTags,
+  isControlFlowPort,
+  isExecutePort,
+  isFailurePort,
+  isScopedMandatoryPort,
+  isSuccessPort
+} from "./chunk-R4QGNK34.js";
+
+// src/parser/generated-sections.ts
+var MARKERS = {
+  RUNTIME_START: "// @flow-weaver-runtime-start",
+  RUNTIME_END: "// @flow-weaver-runtime-end",
+  BODY_START: "// @flow-weaver-body-start",
+  BODY_END: "// @flow-weaver-body-end",
+  IMPORTS_START: "// @flow-weaver-imports-start",
+  IMPORTS_END: "// @flow-weaver-imports-end"
+};
+function hasInPlaceMarkers(source) {
+  return source.includes(MARKERS.RUNTIME_START) && source.includes(MARKERS.RUNTIME_END) && source.includes(MARKERS.BODY_START) && source.includes(MARKERS.BODY_END);
+}
+function stripGeneratedSections(source) {
+  let result = source;
+  const runtimeStartIdx = result.indexOf(MARKERS.RUNTIME_START);
+  const runtimeEndIdx = result.indexOf(MARKERS.RUNTIME_END);
+  if (runtimeStartIdx !== -1 && runtimeEndIdx !== -1) {
+    const lineStart = result.lastIndexOf("\n", runtimeStartIdx);
+    const lineEnd = result.indexOf("\n", runtimeEndIdx + MARKERS.RUNTIME_END.length);
+    result = result.slice(0, lineStart === -1 ? 0 : lineStart) + result.slice(lineEnd === -1 ? result.length : lineEnd);
+  }
+  while (true) {
+    const bodyStartIdx = result.indexOf(MARKERS.BODY_START);
+    const bodyEndIdx = result.indexOf(MARKERS.BODY_END);
+    if (bodyStartIdx === -1 || bodyEndIdx === -1 || bodyEndIdx < bodyStartIdx) break;
+    const before = result.slice(0, bodyStartIdx);
+    const after = result.slice(bodyEndIdx + MARKERS.BODY_END.length);
+    result = before + `throw new Error('Not implemented');` + after;
+  }
+  return result;
+}
+
+// src/parser/npm-node-types.ts
+function resolveNpmNodeTypes(ast, workdir) {
+  if (!ast.nodeTypes || ast.nodeTypes.length === 0) {
+    return ast;
+  }
+  const resolvedNodeTypes = ast.nodeTypes.map((nodeType) => {
+    if (!nodeType.importSource) {
+      return nodeType;
+    }
+    const packageExports = getPackageExports(nodeType.importSource, workdir);
+    const matchingExport = packageExports.find(
+      (exp) => exp.name === nodeType.name || exp.function === nodeType.functionName
+    );
+    if (!matchingExport) {
+      return nodeType;
+    }
+    const inputs = {};
+    const outputs = {};
+    for (const port of matchingExport.ports) {
+      if (port.direction === "INPUT") {
+        inputs[port.name] = {
+          dataType: port.type,
+          label: port.defaultLabel
+        };
+      } else if (port.direction === "OUTPUT") {
+        outputs[port.name] = {
+          dataType: port.type,
+          label: port.defaultLabel
+        };
+      }
+    }
+    return {
+      ...nodeType,
+      inputs,
+      outputs,
+      isAsync: matchingExport.synchronicity === "ASYNC"
+    };
+  });
+  return {
+    ...ast,
+    nodeTypes: resolvedNodeTypes
+  };
+}
+
+// src/parser/annotation-parser.ts
+import { createHash } from "node:crypto";
+import * as fs3 from "node:fs";
+
+// src/utils/lru-cache.ts
+var LRUCache = class {
+  map = /* @__PURE__ */ new Map();
+  maxSize;
+  constructor(maxSize) {
+    this.maxSize = maxSize;
+  }
+  get(key) {
+    const value = this.map.get(key);
+    if (value !== void 0) {
+      this.map.delete(key);
+      this.map.set(key, value);
+    }
+    return value;
+  }
+  has(key) {
+    return this.map.has(key);
+  }
+  set(key, value) {
+    if (this.map.has(key)) {
+      this.map.delete(key);
+    }
+    this.map.set(key, value);
+    while (this.map.size > this.maxSize) {
+      const firstKey = this.map.keys().next().value;
+      this.map.delete(firstKey);
+    }
+  }
+  clear() {
+    this.map.clear();
+  }
+  get size() {
+    return this.map.size;
+  }
+};
+
+// src/utils/string-distance.ts
+function levenshteinDistance(a, b) {
+  const la = a.length;
+  const lb = b.length;
+  if (la === 0) return lb;
+  if (lb === 0) return la;
+  let prev = Array.from({ length: lb + 1 }, (_, i) => i);
+  let curr = new Array(lb + 1);
+  for (let i = 1; i <= la; i++) {
+    curr[0] = i;
+    for (let j = 1; j <= lb; j++) {
+      const cost = a[i - 1] === b[j - 1] ? 0 : 1;
+      curr[j] = Math.min(
+        curr[j - 1] + 1,
+        // insertion
+        prev[j] + 1,
+        // deletion
+        prev[j - 1] + cost
+        // substitution
+      );
+    }
+    [prev, curr] = [curr, prev];
+  }
+  return prev[lb];
+}
+function adaptiveMaxDistance(target) {
+  const len = target.length;
+  if (len <= 3) return 1;
+  if (len <= 6) return 2;
+  return 3;
+}
+function findClosestMatches(target, candidates, maxDistance) {
+  const effectiveMax = maxDistance ?? adaptiveMaxDistance(target);
+  const scored = candidates.filter((c) => c !== target).map((c) => ({ name: c, distance: levenshteinDistance(target, c) })).filter((s) => s.distance <= effectiveMax).sort((a, b) => a.distance - b.distance);
+  return scored.map((s) => s.name);
+}
+
+// src/parser/jsdoc/signature-types.ts
+function unwrapPromise(type) {
+  if (type.getText().startsWith("Promise<")) {
+    const typeArgs = type.getTypeArguments();
+    if (typeArgs.length > 0) {
+      return typeArgs[0];
+    }
+  }
+  return type;
+}
+function resolveCallSignatures(callbackType) {
+  let sigs = callbackType.getCallSignatures();
+  if (sigs.length > 0) return sigs;
+  try {
+    sigs = callbackType.getApparentType().getCallSignatures();
+    if (sigs.length > 0) return sigs;
+  } catch {
+  }
+  try {
+    const symbol = callbackType.getSymbol() ?? callbackType.getAliasSymbol();
+    const decl = symbol?.getDeclarations()?.[0];
+    if (decl) {
+      sigs = decl.getType().getCallSignatures();
+      if (sigs.length > 0) return sigs;
+    }
+  } catch {
+  }
+  return sigs;
+}
+function extractCallbackReturnFieldType(callbackType, fieldName) {
+  const callSignatures = resolveCallSignatures(callbackType);
+  if (callSignatures.length === 0) {
+    return void 0;
+  }
+  const returnType = unwrapPromise(callSignatures[0].getReturnType());
+  const property = returnType.getProperty(fieldName);
+  if (!property) {
+    return void 0;
+  }
+  const propertyType = getPropertyType(property, returnType);
+  if (!propertyType) {
+    return void 0;
+  }
+  return propertyType.getText(void 0, 0);
+}
+function getPropertyType(property, containerType) {
+  const valueDecl = property.getValueDeclaration();
+  if (valueDecl) {
+    return valueDecl.getType();
+  }
+  const declaredType = containerType.getPropertyOrThrow(property.getName());
+  if (declaredType) {
+    const decls = declaredType.getDeclarations();
+    if (decls.length > 0) {
+      return decls[0].getType();
+    }
+  }
+  return void 0;
+}
+function extractCallbackParamType(callbackType, paramName) {
+  const callSignatures = resolveCallSignatures(callbackType);
+  if (callSignatures.length === 0) {
+    return void 0;
+  }
+  const parameters = callSignatures[0].getParameters();
+  for (const param of parameters) {
+    if (param.getName() === paramName) {
+      const valueDecl = param.getValueDeclaration();
+      if (valueDecl) {
+        const paramType = valueDecl.getType();
+        return paramType.getText(void 0, 0);
+      }
+    }
+  }
+  return void 0;
+}
+function typeScopedPort(direction, name, scope, func, warnings) {
+  const nodeTypeName = func.getName() || "unknown";
+  const scopeParam = func.getParameters().find((p) => p.getName() === scope);
+  if (!scopeParam) {
+    const callbackShape = direction === "INPUT" ? `(...) => { ${name}: YourType }` : `(${name}: YourType, ...) => { ... }`;
+    warnings.push(
+      `Scoped ${direction} port '${name}' references scope '${scope}', but no callback parameter named '${scope}' was found in node type '${nodeTypeName}'. Add a callback parameter: ${scope}: ${callbackShape}`
+    );
+    return { type: "ANY" };
+  }
+  const extract = direction === "INPUT" ? extractCallbackReturnFieldType : extractCallbackParamType;
+  const tsType = extract(scopeParam.getType(), name);
+  if (tsType) return { type: inferDataTypeFromTS(tsType), tsType };
+  const expectation = direction === "INPUT" ? `should have a return type that includes '${name}'` : `should have a parameter named '${name}'`;
+  warnings.push(
+    `Cannot infer type for scoped ${direction} port '${name}' in scope '${scope}' of node type '${nodeTypeName}'. The callback parameter '${scope}' ${expectation}. Consider adding an explicit type annotation to the callback signature.`
+  );
+  return { type: "ANY" };
+}
+function applyDeclaredType(direction, name, declared, inferred, tsType, func, warnings) {
+  if (!declared) return inferred;
+  const nodeTypeName = func.getName() || "unknown";
+  if (!isValidPortType(declared)) {
+    warnings.push(
+      `@${direction} ${name} in node type '${nodeTypeName}' declares [type:${declared}], which is not a port type. Use one of STRING, NUMBER, BOOLEAN, ARRAY, OBJECT, FUNCTION, ANY or STEP.`
+    );
+    return inferred;
+  }
+  if (inferred === "ANY") return declared;
+  if (declared !== inferred && declared !== "ANY") {
+    warnings.push(
+      `@${direction} ${name} in node type '${nodeTypeName}' declares [type:${declared}] but the signature gives ${inferred}${tsType ? ` (${tsType})` : ""}. The signature type is used; change one to match.`
+    );
+  }
+  return inferred;
+}
+function objectFieldPattern(name) {
+  const escaped = name.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+  return new RegExp(`(?:^|[{;,\\s])${escaped}\\??\\s*:\\s*([^;},]+)`);
+}
+
+// src/parser/jsdoc/port-tags.ts
+function workflowParameterDefault(tagText, name) {
+  const escaped = name.replace(/[.*+?^${}()|[\]\\]/gu, "\\$&");
+  const match = tagText.match(new RegExp(`\\[\\s*${escaped}\\s*=\\s*([^\\]\\r\\n]*)\\]`, "u"));
+  return match?.[1]?.trim();
+}
+function parseDefaultValue(value) {
+  try {
+    return JSON.parse(value);
+  } catch {
+    return value;
+  }
+}
+function parseInputTag(tag, config, func, warnings) {
+  const comment = tag.getCommentText() || "";
+  const result = parsePortLine(`@input ${comment}`, warnings);
+  if (!result) {
+    return;
+  }
+  const { name, defaultValue, isOptional, scope, order, mergeStrategy, hidden, description, customMetadata } = result;
+  let type;
+  let tsType;
+  const isScopedStepInput = scope && isScopedMandatoryPort(name);
+  if (isExecutePort(name) || isScopedStepInput) {
+    if (result.dataType && result.dataType !== "STEP") {
+      warnings.push(`Port "${name}" is a reserved control port. Its type will always be STEP.`);
+    }
+    type = "STEP";
+  } else if (scope) {
+    ({ type, tsType } = typeScopedPort("INPUT", name, scope, func, warnings));
+  } else {
+    const param = func.getParameters().find((p) => {
+      const pName = p.getName();
+      return pName === name || pName === `_${name}`;
+    });
+    if (param) {
+      const rawTsType = param.getType().getText(param);
+      tsType = param.isOptional() || param.hasInitializer() ? stripOptionalUndefined(rawTsType) : rawTsType;
+      type = inferDataTypeFromTS(tsType);
+    } else {
+      type = "ANY";
+    }
+    type = applyDeclaredType("input", name, result.dataType, type, tsType, func, warnings);
+  }
+  let label = description?.trim();
+  let expression = void 0;
+  if (label && label.startsWith("Expression:")) {
+    expression = label.substring("Expression:".length).trim();
+    label = void 0;
+  }
+  if (Object.prototype.hasOwnProperty.call(config.inputs, name)) {
+    warnings.push(`Duplicate @input "${name}". The second declaration will overwrite the first.`);
+  }
+  config.inputs[name] = {
+    type,
+    defaultValue: defaultValue === void 0 ? void 0 : parseDefaultValue(defaultValue),
+    ...isOptional && { optional: true },
+    label,
+    ...expression && { expression },
+    ...scope && { scope },
+    ...mergeStrategy && { mergeStrategy },
+    ...hidden && { hidden },
+    ...(order !== void 0 || customMetadata) && {
+      metadata: { ...order !== void 0 && { order }, ...customMetadata }
+    },
+    ...tsType && { tsType }
+  };
+}
+function parseOutputTag(tag, config, func, warnings) {
+  const comment = tag.getCommentText() || "";
+  const result = parsePortLine(`@output ${comment}`, warnings);
+  if (!result) {
+    return;
+  }
+  const { name, scope, order, hidden, description, customMetadata } = result;
+  let type;
+  let tsType;
+  const isScopedStepOutput = scope && isScopedMandatoryPort(name);
+  if (isSuccessPort(name) || isFailurePort(name) || isScopedStepOutput) {
+    if (result.dataType && result.dataType !== "STEP") {
+      warnings.push(`Port "${name}" is a reserved control port. Its type will always be STEP.`);
+    }
+    type = "STEP";
+  } else if (scope) {
+    ({ type, tsType } = typeScopedPort("OUTPUT", name, scope, func, warnings));
+  } else {
+    const returnType = unwrapPromise(func.getReturnType());
+    const property = returnType.getProperty(name);
+    if (property) {
+      const propertyType = getPropertyType(property, returnType);
+      if (propertyType) {
+        tsType = propertyType.getText(void 0, 0);
+        type = inferDataTypeFromTS(tsType);
+      } else {
+        type = "ANY";
+      }
+    } else {
+      type = "ANY";
+    }
+    type = applyDeclaredType("output", name, result.dataType, type, tsType, func, warnings);
+  }
+  if (Object.prototype.hasOwnProperty.call(config.outputs, name)) {
+    warnings.push(`Duplicate @output "${name}". The second declaration will overwrite the first.`);
+  }
+  config.outputs[name] = {
+    type,
+    label: description?.trim(),
+    ...scope && { scope },
+    ...hidden && { hidden },
+    ...(order !== void 0 || customMetadata) && {
+      metadata: { ...order !== void 0 && { order }, ...customMetadata }
+    },
+    ...tsType && { tsType }
+  };
+}
+function parseStepTag(tag, config, func, warnings) {
+  const comment = tag.getCommentText() || "";
+  const result = parsePortLine(`@step ${comment}`, warnings);
+  if (!result) {
+    return;
+  }
+  const { name, description } = result;
+  const param = func.getParameters().find((p) => p.getName() === name);
+  if (param) {
+    config.inputs[name] = {
+      type: "STEP",
+      label: description?.trim()
+    };
+  } else {
+    config.outputs[name] = {
+      type: "STEP",
+      label: description?.trim()
+    };
+  }
+}
+function parseReturnTag(tag, config, func, warnings) {
+  const comment = tag.getCommentText() || "";
+  const result = parsePortLine(`@output ${comment}`, warnings);
+  if (!result) {
+    return;
+  }
+  const { name, order, description, customMetadata } = result;
+  let type = "ANY";
+  if (isSuccessPort(name) || isFailurePort(name)) {
+    type = "STEP";
+  } else if (func) {
+    const returnType = func.getReturnType();
+    const returnTypeText = returnType.getText();
+    const fieldMatch = returnTypeText.match(objectFieldPattern(name));
+    if (fieldMatch) {
+      type = inferDataTypeFromTS(fieldMatch[1].trim());
+    } else {
+      warnings.push(`Could not infer type for @returns "${name}", defaulting to ANY.`);
+    }
+  }
+  config.returnPorts = config.returnPorts || {};
+  if (Object.prototype.hasOwnProperty.call(config.returnPorts, name)) {
+    warnings.push(`Duplicate @returns "${name}". The second declaration will overwrite the first.`);
+  }
+  config.returnPorts[name] = {
+    dataType: type,
+    label: description?.trim(),
+    ...(order !== void 0 || customMetadata) && {
+      metadata: { ...order !== void 0 && { order }, ...customMetadata }
+    }
+  };
+}
+function parseParamTag(tag, config, func, warnings) {
+  const compilerNode = tag.compilerNode;
+  const tagWithGetName = tag;
+  const name = compilerNode.name?.getText?.() || tagWithGetName.getName && tagWithGetName.getName();
+  if (!name) {
+    return;
+  }
+  const comment = tag.getCommentText() || "";
+  const result = parsePortLine(`@input ${name} ${comment}`, warnings);
+  const order = result?.order;
+  const description = result?.description;
+  const optional = compilerNode.isBracketed === true;
+  const defaultSource = workflowParameterDefault(tag.getText(), name);
+  let type = "ANY";
+  if (isExecutePort(name)) {
+    type = "STEP";
+  } else if (func) {
+    const params = func.getParameters();
+    const paramsParam = params.find((p) => p.getName() === "params");
+    if (paramsParam) {
+      const paramType = paramsParam.getType();
+      const paramTypeText = paramType.getText();
+      const isCatchAllRecord = /^Record<string,\s*(never|any|unknown)>$/.test(paramTypeText) || paramTypeText === "{}" || /^\{\s*\[[\w]+:\s*string\]:\s*(never|any|unknown);\s*\}$/.test(paramTypeText);
+      if (!isCatchAllRecord) {
+        const fieldMatch = paramTypeText.match(objectFieldPattern(name));
+        if (fieldMatch) {
+          type = inferDataTypeFromTS(fieldMatch[1].trim());
+        } else {
+          warnings.push(`@param "${name}" does not match any field in the params object. Type defaults to ANY.`);
+        }
+      }
+    }
+  }
+  config.startPorts = config.startPorts || {};
+  if (Object.prototype.hasOwnProperty.call(config.startPorts, name)) {
+    warnings.push(`Duplicate @param "${name}". The second declaration will overwrite the first.`);
+  }
+  config.startPorts[name] = {
+    dataType: type,
+    label: description?.trim(),
+    ...optional && { optional: true },
+    ...defaultSource === void 0 ? {} : { default: parseDefaultValue(defaultSource) },
+    ...order !== void 0 && { metadata: { order } }
+  };
+}
+
+// src/parser/jsdoc/parse-line-once.ts
+function parseLineOnce(parse, line, warnings, fallback) {
+  const before = warnings.length;
+  const result = parse(line, warnings);
+  if (result === null && warnings.length === before) warnings.push(fallback);
+  return result;
+}
+
+// src/parser/jsdoc/runtime-tags.ts
+var HTTP_METHODS = /* @__PURE__ */ new Set(["GET", "POST", "PUT", "PATCH", "DELETE"]);
+function parseTriggerTag(tag, config, warnings, tagRegistry) {
+  const comment = (tag.getCommentText() || "").trim();
+  const result = parseTriggerLine(`@trigger ${comment}`, warnings);
+  if (result) {
+    config.trigger = config.trigger || {};
+    if (result.event) config.trigger.event = result.event;
+    if (result.cron) config.trigger.cron = result.cron;
+    return;
+  }
+  if (tagRegistry && tagRegistry.has("_trigger")) {
+    if (!config.deploy) config.deploy = {};
+    tagRegistry.handle("_trigger", comment, "workflow", config.deploy, warnings);
+    return;
+  }
+  warnings.push(`Invalid @trigger format: @trigger ${comment}`);
+}
+function parseCancelOnTag(tag, config, warnings) {
+  const comment = tag.getCommentText() || "";
+  const result = parseLineOnce(parseCancelOnLine, `@cancelOn ${comment}`, warnings, `Invalid @cancelOn format: @cancelOn ${comment}`);
+  if (!result) {
+    return;
+  }
+  config.cancelOn = result;
+}
+function parseThrottleTag(tag, config, warnings) {
+  const comment = tag.getCommentText() || "";
+  const result = parseLineOnce(parseThrottleLine, `@throttle ${comment}`, warnings, `Invalid @throttle format: @throttle ${comment}`);
+  if (!result) {
+    return;
+  }
+  config.throttle = result;
+}
+function parseRetriesTag(tag, config, warnings) {
+  const comment = tag.getCommentText() || "";
+  const result = parseRetriesLine(`@retries ${comment.trim()}`, warnings);
+  if (result && result.retries >= 0) config.retries = result.retries;
+}
+function parseTimeoutTag(tag, config, warnings) {
+  const comment = tag.getCommentText() || "";
+  const raw = comment.trim();
+  const quoted = /^"(?:[^"\\]|\\.)*"$/.test(raw) ? raw : `"${raw.replace(/^['"]|['"]$/g, "")}"`;
+  const result = parseTimeoutLine(`@timeout ${quoted}`, warnings);
+  if (result && result.timeout) config.timeout = result.timeout;
+}
+function parseHttpTag(tag, config, warnings) {
+  const text = (tag.getCommentText() || "").trim();
+  const parts = text.split(/\s+/).filter(Boolean);
+  const fail = (why) => {
+    warnings.push(`Invalid @http: "${text}". ${why} Format: @http METHOD /path [mode=sync|async] [auth=bearer|none] [callback]`);
+  };
+  if (parts.length < 2) return fail("Give a method and a path.");
+  const method = parts[0].toUpperCase();
+  if (!HTTP_METHODS.has(method)) return fail(`"${parts[0]}" is not one of GET, POST, PUT, PATCH, DELETE.`);
+  const routePath = parts[1];
+  if (!/^\/(?:[A-Za-z0-9_\-.~%]+|:[A-Za-z_][A-Za-z0-9_]*)(?:\/(?:[A-Za-z0-9_\-.~%]+|:[A-Za-z_][A-Za-z0-9_]*))*\/?$|^\/$/.test(routePath)) {
+    return fail(`"${routePath}" is not a path: it starts with / and its segments are words or :params.`);
+  }
+  const route = { method, path: routePath.length > 1 ? routePath.replace(/\/$/, "") : routePath };
+  for (const opt of parts.slice(2)) {
+    const [key, raw] = opt.includes("=") ? opt.split("=", 2) : [opt, void 0];
+    const value = raw?.replace(/^["']|["']$/g, "");
+    if (key === "mode" && (value === "sync" || value === "async")) {
+      if (value === "async") route.mode = "async";
+    } else if (key === "auth" && (value === "bearer" || value === "none")) {
+      if (value === "none") route.auth = "none";
+    } else if (key === "callback" && (value === void 0 || value === "true" || value === "false")) {
+      if (value !== "false") route.callback = true;
+    } else return fail(`"${opt}" is not an option.`);
+  }
+  config.http = config.http || [];
+  if (config.http.some((r) => r.method === route.method && r.path === route.path)) {
+    warnings.push(`Duplicate @http route ${route.method} ${route.path}. The first one stands.`);
+    return;
+  }
+  config.http.push(route);
+}
+function parseDeployTag(tag, deployMap) {
+  const text = (tag.getCommentText() || "").trim();
+  if (!text) return;
+  const spaceIdx = text.indexOf(" ");
+  const targetName = spaceIdx === -1 ? text : text.substring(0, spaceIdx);
+  const rest = spaceIdx === -1 ? "" : text.substring(spaceIdx + 1);
+  if (!targetName) return;
+  if (!deployMap[targetName]) deployMap[targetName] = {};
+  if (!rest) return;
+  const kvRegex = /(\w[\w-]*)\s*=\s*(?:"((?:[^"\\]|\\.)*)"|([\S]+))/g;
+  let match;
+  while ((match = kvRegex.exec(rest)) !== null) {
+    const key = match[1];
+    const quotedVal = match[2];
+    const bareVal = match[3];
+    if (quotedVal !== void 0) {
+      if (quotedVal.includes(",")) {
+        deployMap[targetName][key] = quotedVal.split(",").map((v) => v.trim());
+      } else {
+        deployMap[targetName][key] = quotedVal;
+      }
+    } else if (bareVal !== void 0) {
+      if (bareVal === "true") {
+        deployMap[targetName][key] = true;
+      } else if (bareVal === "false") {
+        deployMap[targetName][key] = false;
+      } else {
+        const num = Number(bareVal);
+        deployMap[targetName][key] = isNaN(num) ? bareVal : num;
+      }
+    }
+  }
+}
+
+// src/parser/jsdoc/node-type-block.ts
+function parseResilience(comment, config, warnings) {
+  const resilience = {};
+  const attributes = comment.matchAll(/(\w+)=(?:"([^"]*)"|'([^']*)'|(\S+))/g);
+  for (const match of attributes) {
+    const key = match[1];
+    const value = match[2] ?? match[3] ?? match[4];
+    if (key === "retries") {
+      const retries = Number(value);
+      if (Number.isInteger(retries) && retries > 0) {
+        resilience.retries = retries;
+      } else {
+        warnings.push("@resilience retries must be a positive integer.");
+      }
+    } else if (key === "fallback") {
+      if (value.trim()) resilience.fallback = value.trim();
+    } else {
+      warnings.push(`Unknown @resilience option "${key}". Supported options: retries, fallback.`);
+    }
+  }
+  if (resilience.retries !== void 0 || resilience.fallback !== void 0) {
+    config.resilience = resilience;
+  } else {
+    warnings.push('@resilience requires retries=N and/or fallback="provider".');
+  }
+}
+function parseNodeType(func, warnings, tagRegistry) {
+  const jsdocs = func.getJsDocs();
+  if (jsdocs.length === 0) return null;
+  let jsdoc = null;
+  let flowWeaverTag = null;
+  let isNodeShorthand = false;
+  for (const doc of jsdocs) {
+    const tags2 = doc.getTags();
+    const tag = tags2.find(
+      (t) => {
+        if (t.getTagName() !== "flowWeaver") return false;
+        const comment = t.getCommentText()?.trim();
+        return comment === "nodeType" || comment === "node";
+      }
+    );
+    if (tag) {
+      jsdoc = doc;
+      flowWeaverTag = tag;
+      isNodeShorthand = flowWeaverTag.getCommentText()?.trim() === "node";
+      break;
+    }
+  }
+  if (!jsdoc || !flowWeaverTag) return null;
+  const tags = jsdoc.getTags();
+  const config = {
+    inputs: {},
+    outputs: {}
+  };
+  if (isNodeShorthand) {
+    config.expression = true;
+  }
+  const descriptionText = jsdoc.getDescription();
+  if (descriptionText && descriptionText.trim()) {
+    config.description = descriptionText.trim();
+  }
+  tags.forEach((tag) => {
+    const tagName = tag.getTagName();
+    const comment = tag.getCommentText() || "";
+    switch (tagName) {
+      case "name":
+        config.name = comment.trim();
+        break;
+      case "label":
+        config.label = comment.trim();
+        break;
+      case "description":
+        config.description = comment.trim();
+        break;
+      case "color":
+        config.color = comment.trim().replace(/^["']|["']$/g, "");
+        break;
+      case "icon":
+        config.icon = comment.trim().replace(/^["']|["']$/g, "");
+        break;
+      case "tag": {
+        config.tags = config.tags || [];
+        const tagMatch = comment.match(/^(\S+)(?:\s+"([^"]+)")?$/);
+        if (tagMatch) {
+          config.tags.push({
+            label: tagMatch[1],
+            ...tagMatch[2] && { tooltip: tagMatch[2] }
+          });
+        }
+        break;
+      }
+      case "executeWhen":
+        config.executeWhen = comment.trim();
+        break;
+      case "scope":
+        config.scope = comment.trim();
+        break;
+      case "expression":
+        config.expression = true;
+        break;
+      case "pullExecution": {
+        const pullValue = comment.trim();
+        if (pullValue) {
+          config.defaultConfig = config.defaultConfig || {};
+          config.defaultConfig.pullExecution = { triggerPort: pullValue };
+        }
+        break;
+      }
+      case "resilience":
+        parseResilience(comment, config, warnings);
+        break;
+      case "input":
+        parseInputTag(tag, config, func, warnings);
+        break;
+      case "output":
+        parseOutputTag(tag, config, func, warnings);
+        break;
+      case "step":
+        parseStepTag(tag, config, func, warnings);
+        break;
+      case "deploy":
+        config.deploy = config.deploy || {};
+        parseDeployTag(tag, config.deploy);
+        break;
+      default: {
+        if (tagName === "param" || tagName === "returns" || tagName === "return") {
+          warnings.push(`@${tagName} is for workflows, not node types. Use @input/@output instead.`);
+        } else if (tagRegistry && tagRegistry.has(tagName)) {
+          if (!config.deploy) config.deploy = {};
+          tagRegistry.handle(tagName, comment, "nodeType", config.deploy, warnings);
+        } else if (!KNOWN_NODETYPE_TAGS.has(tagName) && !STANDARD_JSDOC_TAGS.has(tagName)) {
+          const suggestions = findClosestMatches(tagName, [...KNOWN_NODETYPE_TAGS]);
+          const hint = suggestions.length > 0 ? ` Did you mean @${suggestions[0]}?` : "";
+          warnings.push(`Unknown annotation @${tagName} in nodeType block.${hint}`);
+        }
+        break;
+      }
+    }
+  });
+  return config;
+}
+
+// src/parser/jsdoc/graph-tags.ts
+var POSITION_ATTR = /\s*\[position:\s*-?\d+\s+-?\d+\]|,\s*position:\s*-?\d+\s+-?\d+(?=\s*[,\]])|(?<=\[)\s*position:\s*-?\d+\s+-?\d+\s*,\s*/g;
+var positionGone = (where) => `${where}: node positions are no longer part of the grammar and this was ignored. Remove it, or run \`fw compile\` / \`fw migrate\` to rewrite the block without it.`;
+function parseImportTag(tag, config, warnings) {
+  const comment = tag.getCommentText()?.trim() || "";
+  const match = comment.match(/^(\S+)\s+(\S+)\s+from\s+["']([^"']+)["']$/);
+  if (match) {
+    const [, name, functionName, importSource] = match;
+    config.imports.push({ name, functionName, importSource });
+  } else {
+    warnings.push(
+      `Invalid @fwImport tag format: "${comment}". Expected: @fwImport nodeName functionName from "packageName"`
+    );
+  }
+}
+function parseNodeTag(tag, config, warnings) {
+  let comment = tag.getCommentText() || "";
+  if (POSITION_ATTR.test(comment)) {
+    POSITION_ATTR.lastIndex = 0;
+    comment = comment.replace(POSITION_ATTR, "");
+    warnings.push(positionGone(`@node ${comment.trim().split(/\s+/)[0]} [position:]`));
+  }
+  POSITION_ATTR.lastIndex = 0;
+  const result = parseNodeLine(`@node ${comment}`, warnings);
+  if (!result) {
+    return;
+  }
+  const {
+    instanceId,
+    nodeType,
+    parentScope,
+    label,
+    expressions,
+    portOrder,
+    portLabel,
+    minimized,
+    pullExecution,
+    size,
+    color,
+    icon,
+    tags,
+    attributes,
+    suppress
+  } = result;
+  const line = tag.getStartLineNumber();
+  let portConfigs;
+  if (portOrder) {
+    portConfigs = Object.entries(portOrder).map(([portName, order]) => ({
+      portName,
+      order
+    }));
+  }
+  if (portLabel) {
+    portConfigs = portConfigs || [];
+    for (const [portName, labelVal] of Object.entries(portLabel)) {
+      const existingIndex = portConfigs.findIndex((pc) => pc.portName === portName);
+      if (existingIndex >= 0) {
+        portConfigs[existingIndex] = { ...portConfigs[existingIndex], label: labelVal };
+      } else {
+        portConfigs.push({ portName, label: labelVal });
+      }
+    }
+  }
+  if (expressions) {
+    portConfigs = portConfigs || [];
+    for (const [portName, expression] of Object.entries(expressions)) {
+      const existingIndex = portConfigs.findIndex((pc) => pc.portName === portName);
+      if (existingIndex >= 0) {
+        portConfigs[existingIndex] = { ...portConfigs[existingIndex], expression };
+      } else {
+        portConfigs.push({ portName, expression });
+      }
+    }
+  }
+  config.instances.push({
+    id: instanceId,
+    type: nodeType,
+    ...parentScope && { parentScope },
+    ...label && { label },
+    ...portConfigs && portConfigs.length > 0 && { portConfigs },
+    ...pullExecution && { pullExecution: { triggerPort: pullExecution } },
+    ...minimized && { minimized },
+    ...color && { color },
+    ...icon && { icon },
+    ...tags && tags.length > 0 && { tags },
+    ...size && { width: size.width, height: size.height },
+    ...attributes && Object.keys(attributes).length > 0 && { attributes },
+    ...suppress && suppress.length > 0 && { suppressWarnings: suppress },
+    sourceLocation: { line, column: 0 }
+  });
+}
+function parseConnectTag(tag, config, warnings) {
+  const comment = tag.getCommentText() || "";
+  const result = parseLineOnce(parseConnectLine, `@connect ${comment}`, warnings, `Invalid @connect tag format: @connect ${comment}`);
+  if (!result) {
+    return;
+  }
+  const { source, target, coerce } = result;
+  const line = tag.getStartLineNumber();
+  config.connections.push({
+    from: {
+      node: source.nodeId,
+      port: source.portName,
+      ...source.scope && { scope: source.scope }
+    },
+    to: {
+      node: target.nodeId,
+      port: target.portName,
+      ...target.scope && { scope: target.scope }
+    },
+    sourceLocation: { line, column: 0 },
+    ...coerce && { coerce }
+  });
+}
+function parseScopeTag(tag, config, warnings) {
+  const comment = tag.getCommentText() || "";
+  const result = parseLineOnce(parseScopeLine, `@scope ${comment}`, warnings, `Invalid @scope tag format: ${comment}`);
+  if (!result) {
+    return;
+  }
+  config.scopes[result.scopeName] = result.children;
+}
+function parseMapTag(tag, config, warnings) {
+  const comment = tag.getCommentText() || "";
+  const result = parseLineOnce(parseMapLine, `@map ${comment}`, warnings, `Invalid @map tag format: ${comment}`);
+  if (!result) {
+    return;
+  }
+  config.maps = config.maps || [];
+  config.maps.push({
+    instanceId: result.instanceId,
+    childId: result.childId,
+    sourceNode: result.sourceNode,
+    sourcePort: result.sourcePort,
+    ...result.inputPort && { inputPort: result.inputPort },
+    ...result.outputPort && { outputPort: result.outputPort }
+  });
+}
+function parsePathTag(tag, config, warnings) {
+  const comment = tag.getCommentText() || "";
+  const results = parseLineOnce(parsePathLine, `@path ${comment}`, warnings, `Invalid @path tag format: ${comment}`);
+  if (!results) {
+    return;
+  }
+  config.paths = config.paths || [];
+  for (const result of results) {
+    config.paths.push({
+      steps: result.steps
+    });
+  }
+}
+function parseFanOutTag(tag, config, warnings) {
+  const comment = tag.getCommentText() || "";
+  const result = parseLineOnce(parseFanOutLine, `@fanOut ${comment}`, warnings, `Invalid @fanOut tag format: ${comment}`);
+  if (!result) {
+    return;
+  }
+  if (!result.source.port) {
+    warnings.push(`@fanOut source must specify a port: ${comment}`);
+    return;
+  }
+  config.fanOuts = config.fanOuts || [];
+  config.fanOuts.push({
+    source: { node: result.source.node, port: result.source.port },
+    targets: result.targets
+  });
+}
+function parseFanInTag(tag, config, warnings) {
+  const comment = tag.getCommentText() || "";
+  const result = parseLineOnce(parseFanInLine, `@fanIn ${comment}`, warnings, `Invalid @fanIn tag format: ${comment}`);
+  if (!result) {
+    return;
+  }
+  if (!result.target.port) {
+    warnings.push(`@fanIn target must specify a port: ${comment}`);
+    return;
+  }
+  config.fanIns = config.fanIns || [];
+  config.fanIns.push({
+    sources: result.sources,
+    target: { node: result.target.node, port: result.target.port }
+  });
+}
+function parseCoerceTag(tag, config, warnings) {
+  const comment = tag.getCommentText() || "";
+  const result = parseLineOnce(parseCoerceLine, `@coerce ${comment}`, warnings, `Invalid @coerce tag format: ${comment}`);
+  if (!result) {
+    return;
+  }
+  config.coercions = config.coercions || [];
+  config.coercions.push({
+    instanceId: result.instanceId,
+    source: result.source,
+    target: result.target,
+    targetType: result.targetType
+  });
+}
+
+// src/parser/jsdoc/workflow-block.ts
+function parseWorkflow(func, warnings, tagRegistry) {
+  const jsdocs = func.getJsDocs();
+  if (jsdocs.length === 0) return null;
+  let jsdoc = null;
+  let flowWeaverTag = null;
+  for (const doc of jsdocs) {
+    const tags2 = doc.getTags();
+    const tag = tags2.find(
+      (t) => t.getTagName() === "flowWeaver" && t.getCommentText()?.trim() === "workflow"
+    );
+    if (tag) {
+      jsdoc = doc;
+      flowWeaverTag = tag;
+      break;
+    }
+  }
+  if (!jsdoc || !flowWeaverTag) return null;
+  const tags = jsdoc.getTags();
+  const config = {
+    imports: [],
+    instances: [],
+    connections: [],
+    scopes: {}
+  };
+  const descriptionText = jsdoc.getDescription();
+  if (descriptionText && descriptionText.trim()) {
+    config.description = descriptionText.trim();
+  }
+  tags.forEach((tag) => {
+    const tagName = tag.getTagName();
+    const comment = tag.getCommentText() || "";
+    switch (tagName) {
+      case "name":
+        config.name = comment.trim();
+        break;
+      case "fwImport":
+        parseImportTag(tag, config, warnings);
+        break;
+      case "description":
+        config.description = comment.trim();
+        break;
+      case "strictTypes":
+        config.strictTypes = comment.trim().toLowerCase() !== "false";
+        break;
+      case "autoConnect":
+        config.autoConnect = true;
+        break;
+      case "node":
+        parseNodeTag(tag, config, warnings);
+        break;
+      case "position":
+        warnings.push(positionGone(`@position ${comment.trim()}`));
+        break;
+      case "connect":
+        parseConnectTag(tag, config, warnings);
+        break;
+      case "scope":
+        parseScopeTag(tag, config, warnings);
+        break;
+      case "map":
+        parseMapTag(tag, config, warnings);
+        break;
+      case "path":
+        parsePathTag(tag, config, warnings);
+        break;
+      case "fanOut":
+        parseFanOutTag(tag, config, warnings);
+        break;
+      case "fanIn":
+        parseFanInTag(tag, config, warnings);
+        break;
+      case "coerce":
+        parseCoerceTag(tag, config, warnings);
+        break;
+      case "trigger":
+        parseTriggerTag(tag, config, warnings, tagRegistry);
+        break;
+      case "http":
+        parseHttpTag(tag, config, warnings);
+        break;
+      case "cancelOn":
+        parseCancelOnTag(tag, config, warnings);
+        break;
+      case "retries":
+        parseRetriesTag(tag, config, warnings);
+        break;
+      case "timeout":
+        parseTimeoutTag(tag, config, warnings);
+        break;
+      case "throttle":
+        parseThrottleTag(tag, config, warnings);
+        break;
+      case "deploy":
+        config.deploy = config.deploy || {};
+        parseDeployTag(tag, config.deploy);
+        break;
+      case "param":
+        parseParamTag(tag, config, func, warnings);
+        break;
+      case "return":
+      case "returns":
+        parseReturnTag(tag, config, func, warnings);
+        break;
+      default: {
+        if (tagName === "color" || tagName === "icon" || tagName === "tag") {
+          warnings.push(`@${tagName} is for node types, not workflows. Use it on @flowWeaver nodeType instead.`);
+        } else if (tagName === "input" || tagName === "output" || tagName === "step") {
+          warnings.push(`@${tagName} is for node types, not workflows. Use @param/@returns for workflows.`);
+        } else if (tagRegistry && tagRegistry.has(tagName)) {
+          if (!config.deploy) config.deploy = {};
+          tagRegistry.handle(tagName, comment, "workflow", config.deploy, warnings);
+        } else {
+          const knownTags = getKnownWorkflowTags(tagRegistry?.getRegisteredTags());
+          if (!knownTags.has(tagName) && !STANDARD_JSDOC_TAGS.has(tagName)) {
+            const suggestions = findClosestMatches(tagName, [...knownTags]);
+            const hint = suggestions.length > 0 ? ` Did you mean @${suggestions[0]}?` : "";
+            warnings.push(`Unknown annotation @${tagName} in workflow block.${hint}`);
+          }
+        }
+        break;
+      }
+    }
+  });
+  return config;
+}
+
+// src/parser/jsdoc-parser.ts
+var jsdocParser = {
+  parseNodeType,
+  parseWorkflow
+};
+
+// src/built-in-nodes/generated-registry.ts
+var BUILT_IN_NODE_TYPES = [
+  {
+    type: "NodeType",
+    name: "delay",
+    functionName: "delay",
+    isAsync: true,
+    receivesAbortSignal: true,
+    receivesRuntime: true,
+    durablePure: true,
+    hasSuccessPort: true,
+    hasFailurePort: true,
+    executeWhen: "CONJUNCTION",
+    variant: "FUNCTION",
+    inputs: {
+      execute: { dataType: "STEP", label: "Execute" },
+      duration: { dataType: "STRING", label: 'Duration to sleep (e.g. "30s", "5m", "1h", "2d")', tsType: "string" }
+    },
+    outputs: {
+      elapsed: { dataType: "BOOLEAN", label: "Always true after sleep completes", tsType: "boolean" },
+      onSuccess: { dataType: "STEP", label: "On Success", isControlFlow: true },
+      onFailure: { dataType: "STEP", label: "On Failure", isControlFlow: true, failure: true }
+    },
+    helperText: `
+function __fw_getMockConfig(runtime?: NodeExecutionRuntime): FwMockConfig | undefined {
+  return runtime?.runtime.services.mocks;
+}
+
+function __fw_lookupMock<T>(
+  section: Record<string, T> | undefined,
+  key: string,
+  runtime?: NodeExecutionRuntime,
+): T | undefined {
+  if (!section) return undefined;
+
+  const nodeId = runtime?.nodeId;
+  if (nodeId) {
+    const qualified = section[\`\${nodeId}:\${key}\`];
+    if (qualified !== undefined) return qualified;
+    const any = section[\`\${nodeId}:*\`];
+    if (any !== undefined) return any;
+  }
+
+  return section[key];
+}
+`.trim(),
+    helperTextProduction: void 0,
+    functionText: `
+async function delay(
+  execute: boolean,
+  duration: string,
+  abortSignal?: AbortSignal,
+  runtime?: NodeExecutionRuntime,
+): Promise<{ onSuccess: boolean; onFailure: boolean; elapsed: boolean }> {
+  if (!execute) return { onSuccess: false, onFailure: false, elapsed: false };
+
+  const mocks = __fw_getMockConfig(runtime);
+  if (mocks?.fast) {
+    // Fast mode: skip real sleep, keep async behavior with 1ms
+    await __fw_waitForDuration(1, abortSignal);
+  } else {
+    const ms = __fw_parseDuration(duration) ?? 0;
+    // setTimeout holds a signed 32-bit delay. Past 2^31-1 ms (24.8 days) it
+    // fires at once with a warning instead of waiting, so a longer duration
+    // is refused rather than silently cut short. A run that waits that long
+    // wants \`sleep\`, which holds no process.
+    if (ms > 2147483647) {
+      throw new Error(
+        'delay: "' + duration + '" is longer than setTimeout can wait (24.8 days); use sleep for a wait this long',
+      );
+    }
+    await __fw_waitForDuration(ms, abortSignal);
+  }
+
+  return { onSuccess: true, onFailure: false, elapsed: true };
+}
+
+function __fw_waitForDuration(ms: number, abortSignal?: AbortSignal): Promise<void> {
+  if (abortSignal?.aborted) return Promise.reject(new CancellationError());
+
+  return new Promise((resolve, reject) => {
+    let settled = false;
+    const onAbort = () => {
+      if (settled) return;
+      settled = true;
+      clearTimeout(timer);
+      abortSignal?.removeEventListener('abort', onAbort);
+      reject(new CancellationError());
+    };
+    const timer = setTimeout(() => {
+      if (settled) return;
+      settled = true;
+      abortSignal?.removeEventListener('abort', onAbort);
+      resolve();
+    }, ms);
+
+    abortSignal?.addEventListener('abort', onAbort, { once: true });
+    if (abortSignal?.aborted) onAbort();
+  });
+}
+
+// \`<number><unit>\` with unit \`ms\`, \`s\`, \`m\`, \`h\` or \`d\`, whitespace around
+// either allowed; \`undefined\` for anything else, including an empty string.
+// This is the one reading of a duration string in the package: the
+// coordinator's clock (\`src/coordinator/time.ts\`) re-exports it for a
+// \`sleep\` duration and a gate \`timeout\`, and this file's body is inlined into
+// compiled workflows, which is why the function lives here and not there.
+function __fw_parseDuration(text: unknown): number | undefined {
+  if (typeof text !== 'string') return undefined;
+  const match = /^\\s*(\\d+)\\s*(ms|s|m|h|d)\\s*$/.exec(text);
+  if (!match) return undefined;
+  const units: Record<string, number> = { ms: 1, s: 1000, m: 60000, h: 3600000, d: 86400000 };
+  return Number(match[1]) * units[match[2]];
+}
+`.trim(),
+    functionTextProduction: `
+async function delay(
+  execute: boolean,
+  duration: string,
+  abortSignal?: AbortSignal,
+  runtime?: NodeExecutionRuntime,
+): Promise<{ onSuccess: boolean; onFailure: boolean; elapsed: boolean }> {
+  if (!execute) return { onSuccess: false, onFailure: false, elapsed: false };
+
+const ms = __fw_parseDuration(duration) ?? 0;
+  // setTimeout holds a signed 32-bit delay. Past 2^31-1 ms (24.8 days) it
+  // fires at once with a warning instead of waiting, so a longer duration
+  // is refused rather than silently cut short. A run that waits that long
+  // wants \`sleep\`, which holds no process.
+  if (ms > 2147483647) {
+    throw new Error(
+      'delay: "' + duration + '" is longer than setTimeout can wait (24.8 days); use sleep for a wait this long',
+    );
+  }
+  await __fw_waitForDuration(ms, abortSignal);
+
+  return { onSuccess: true, onFailure: false, elapsed: true };
+}
+
+function __fw_waitForDuration(ms: number, abortSignal?: AbortSignal): Promise<void> {
+  if (abortSignal?.aborted) return Promise.reject(new CancellationError());
+
+  return new Promise((resolve, reject) => {
+    let settled = false;
+    const onAbort = () => {
+      if (settled) return;
+      settled = true;
+      clearTimeout(timer);
+      abortSignal?.removeEventListener('abort', onAbort);
+      reject(new CancellationError());
+    };
+    const timer = setTimeout(() => {
+      if (settled) return;
+      settled = true;
+      abortSignal?.removeEventListener('abort', onAbort);
+      resolve();
+    }, ms);
+
+    abortSignal?.addEventListener('abort', onAbort, { once: true });
+    if (abortSignal?.aborted) onAbort();
+  });
+}
+
+// \`<number><unit>\` with unit \`ms\`, \`s\`, \`m\`, \`h\` or \`d\`, whitespace around
+// either allowed; \`undefined\` for anything else, including an empty string.
+// This is the one reading of a duration string in the package: the
+// coordinator's clock (\`src/coordinator/time.ts\`) re-exports it for a
+// \`sleep\` duration and a gate \`timeout\`, and this file's body is inlined into
+// compiled workflows, which is why the function lives here and not there.
+function __fw_parseDuration(text: unknown): number | undefined {
+  if (typeof text !== 'string') return undefined;
+  const match = /^\\s*(\\d+)\\s*(ms|s|m|h|d)\\s*$/.exec(text);
+  if (!match) return undefined;
+  const units: Record<string, number> = { ms: 1, s: 1000, m: 60000, h: 3600000, d: 86400000 };
+  return Number(match[1]) * units[match[2]];
+}
+`.trim()
+  },
+  {
+    type: "NodeType",
+    name: "sleep",
+    functionName: "sleep",
+    isAsync: true,
+    receivesAbortSignal: false,
+    receivesRuntime: true,
+    durableGate: "timer",
+    hasSuccessPort: true,
+    hasFailurePort: true,
+    executeWhen: "CONJUNCTION",
+    variant: "FUNCTION",
+    inputs: {
+      execute: { dataType: "STEP", label: "Execute" },
+      duration: { dataType: "STRING", label: 'How long the run sleeps before it goes on (e.g. "30s", "2h", "3d")', tsType: "string" }
+    },
+    outputs: {
+      wokeAt: { dataType: "STRING", label: "When the run went on, as an ISO 8601 time", tsType: "string" },
+      onSuccess: { dataType: "STEP", label: "On Success", isControlFlow: true },
+      onFailure: { dataType: "STEP", label: "On Failure", isControlFlow: true, failure: true }
+    },
+    helperText: `
+function __fw_getMockConfig(runtime?: NodeExecutionRuntime): FwMockConfig | undefined {
+  return runtime?.runtime.services.mocks;
+}
+
+function __fw_lookupMock<T>(
+  section: Record<string, T> | undefined,
+  key: string,
+  runtime?: NodeExecutionRuntime,
+): T | undefined {
+  if (!section) return undefined;
+
+  const nodeId = runtime?.nodeId;
+  if (nodeId) {
+    const qualified = section[\`\${nodeId}:\${key}\`];
+    if (qualified !== undefined) return qualified;
+    const any = section[\`\${nodeId}:*\`];
+    if (any !== undefined) return any;
+  }
+
+  return section[key];
+}
+`.trim(),
+    helperTextProduction: void 0,
+    functionText: `
+async function sleep(
+  execute: boolean,
+  duration: string,
+  runtime?: NodeExecutionRuntime,
+): Promise<{ onSuccess: boolean; onFailure: boolean; wokeAt: string }> {
+  if (!execute) return { onSuccess: false, onFailure: false, wokeAt: '' };
+
+  // A timer gate. The compiler replaces this call with a durable yield, and
+  // whoever keeps the run (the coordinator's clock, or a host of its own)
+  // resumes it once \`duration\` has passed; under test \`fast\` wakes it at
+  // once (see \`FwMockConfig\` in \`src/built-in-nodes/mock-types.ts\`).
+  // Reaching this body means the generated program did not apply the gate
+  // boundary, so it fails closed. A wait that holds the process is what
+  // \`delay\` is for.
+  void duration;
+  void runtime;
+  throw new Error('sleep requires a generated durable timer gate');
+}
+`.trim(),
+    functionTextProduction: `
+async function sleep(
+  execute: boolean,
+  duration: string,
+  runtime?: NodeExecutionRuntime,
+): Promise<{ onSuccess: boolean; onFailure: boolean; wokeAt: string }> {
+  if (!execute) return { onSuccess: false, onFailure: false, wokeAt: '' };
+
+  // A timer gate. The compiler replaces this call with a durable yield, and
+  // whoever keeps the run (the coordinator's clock, or a host of its own)
+  // resumes it once \`duration\` has passed; under test \`fast\` wakes it at
+  // Reaching this body means the generated program did not apply the gate
+  // boundary, so it fails closed. A wait that holds the process is what
+  // \`delay\` is for.
+  void duration;
+  void runtime;
+  throw new Error('sleep requires a generated durable timer gate');
+}
+`.trim()
+  },
+  {
+    type: "NodeType",
+    name: "waitForEvent",
+    functionName: "waitForEvent",
+    isAsync: true,
+    receivesAbortSignal: false,
+    receivesRuntime: true,
+    durableGate: "input",
+    hasSuccessPort: true,
+    hasFailurePort: true,
+    executeWhen: "CONJUNCTION",
+    variant: "FUNCTION",
+    inputs: {
+      execute: { dataType: "STEP", label: "Execute" },
+      eventName: { dataType: "STRING", label: 'Event name to wait for (e.g. "app/approval.received")', tsType: "string" },
+      match: { dataType: "STRING", label: 'Field to match between trigger and waited event (e.g. "data.requestId")', tsType: "string", optional: true },
+      timeout: { dataType: "STRING", label: 'Max wait time (e.g. "24h", "7d"). Empty = no timeout', tsType: "string", optional: true }
+    },
+    outputs: {
+      eventData: { dataType: "OBJECT", label: "The received event's data payload", tsType: "object" },
+      onSuccess: { dataType: "STEP", label: "On Success", isControlFlow: true },
+      onFailure: { dataType: "STEP", label: "On Failure", isControlFlow: true, failure: true }
+    },
+    helperText: `
+function __fw_getMockConfig(runtime?: NodeExecutionRuntime): FwMockConfig | undefined {
+  return runtime?.runtime.services.mocks;
+}
+
+function __fw_lookupMock<T>(
+  section: Record<string, T> | undefined,
+  key: string,
+  runtime?: NodeExecutionRuntime,
+): T | undefined {
+  if (!section) return undefined;
+
+  const nodeId = runtime?.nodeId;
+  if (nodeId) {
+    const qualified = section[\`\${nodeId}:\${key}\`];
+    if (qualified !== undefined) return qualified;
+    const any = section[\`\${nodeId}:*\`];
+    if (any !== undefined) return any;
+  }
+
+  return section[key];
+}
+`.trim(),
+    helperTextProduction: void 0,
+    functionText: `
+async function waitForEvent(
+  execute: boolean,
+  eventName: string,
+  match?: string,
+  timeout?: string,
+  runtime?: NodeExecutionRuntime,
+): Promise<{ onSuccess: boolean; onFailure: boolean; eventData: object }> {
+  if (!execute) return { onSuccess: false, onFailure: false, eventData: {} };
+
+  // An input gate. The compiler replaces this call with a durable yield, and
+  // the engine answers the gate: from a person, or under test from the run's
+  // canned answers (see \`FwMockConfig\` in \`src/built-in-nodes/mock-types.ts\`
+  // for how those are read). Reaching this body means the generated program
+  // did not apply the gate boundary, so it fails closed.
+  void eventName;
+  void match;
+  void timeout;
+  void runtime;
+  throw new Error('waitForEvent requires a generated durable input gate');
+}
+`.trim(),
+    functionTextProduction: `
+async function waitForEvent(
+  execute: boolean,
+  eventName: string,
+  match?: string,
+  timeout?: string,
+  runtime?: NodeExecutionRuntime,
+): Promise<{ onSuccess: boolean; onFailure: boolean; eventData: object }> {
+  if (!execute) return { onSuccess: false, onFailure: false, eventData: {} };
+
+  // An input gate. The compiler replaces this call with a durable yield, and
+  // the engine answers the gate: from a person, or under test from the run's
+  // for how those are read). Reaching this body means the generated program
+  // did not apply the gate boundary, so it fails closed.
+  void eventName;
+  void match;
+  void timeout;
+  void runtime;
+  throw new Error('waitForEvent requires a generated durable input gate');
+}
+`.trim()
+  },
+  {
+    type: "NodeType",
+    name: "invokeWorkflow",
+    functionName: "invokeWorkflow",
+    isAsync: true,
+    receivesAbortSignal: true,
+    receivesRuntime: true,
+    durablePure: true,
+    hasSuccessPort: true,
+    hasFailurePort: true,
+    executeWhen: "CONJUNCTION",
+    variant: "FUNCTION",
+    inputs: {
+      execute: { dataType: "STEP", label: "Execute" },
+      functionId: { dataType: "STRING", label: 'Function ID of the workflow to invoke (e.g. "my-service/sub-workflow")', tsType: "string" },
+      payload: { dataType: "OBJECT", label: "Data to pass as event.data to the invoked function", tsType: "object" },
+      timeout: { dataType: "STRING", label: 'Max wait time (e.g. "1h")', tsType: "string", optional: true }
+    },
+    outputs: {
+      result: { dataType: "OBJECT", label: "Return value from the invoked function", tsType: "object" },
+      onSuccess: { dataType: "STEP", label: "On Success", isControlFlow: true },
+      onFailure: { dataType: "STEP", label: "On Failure", isControlFlow: true, failure: true }
+    },
+    helperText: `
+function __fw_getMockConfig(runtime?: NodeExecutionRuntime): FwMockConfig | undefined {
+  return runtime?.runtime.services.mocks;
+}
+
+function __fw_lookupMock<T>(
+  section: Record<string, T> | undefined,
+  key: string,
+  runtime?: NodeExecutionRuntime,
+): T | undefined {
+  if (!section) return undefined;
+
+  const nodeId = runtime?.nodeId;
+  if (nodeId) {
+    const qualified = section[\`\${nodeId}:\${key}\`];
+    if (qualified !== undefined) return qualified;
+    const any = section[\`\${nodeId}:*\`];
+    if (any !== undefined) return any;
+  }
+
+  return section[key];
+}
+`.trim(),
+    helperTextProduction: void 0,
+    functionText: `
+async function invokeWorkflow(
+  execute: boolean,
+  functionId: string,
+  payload: object,
+  timeout?: string,
+  abortSignal?: AbortSignal,
+  runtime?: NodeExecutionRuntime,
+): Promise<{ onSuccess: boolean; onFailure: boolean; result: object }> {
+  if (!execute) return { onSuccess: false, onFailure: false, result: {} };
+
+  const mocks = __fw_getMockConfig(runtime);
+  if (mocks) {
+    // Mock mode: look up result by functionId (supports instance-qualified keys)
+    const mockResult = __fw_lookupMock(mocks.invocations, functionId, runtime);
+    if (mockResult !== undefined) {
+      return { onSuccess: true, onFailure: false, result: mockResult };
+    }
+    // No mock data for this functionId, so simulate failure
+    return { onSuccess: false, onFailure: true, result: {} };
+  }
+
+  // Check local workflow registry (populated by executeWorkflow)
+  const registry = runtime?.runtime.services.workflowRegistry;
+  if (registry?.[functionId]) {
+    const nodeRuntime = runtime!;
+    if (
+      !Number.isSafeInteger(nodeRuntime.recursionDepth) ||
+      nodeRuntime.recursionDepth < 0 ||
+      nodeRuntime.recursionDepth >= 999
+    ) {
+      throw new Error('Max recursion depth exceeded (1000) in dynamic workflow invocation');
+    }
+    try {
+      const result = await registry[functionId](
+        true,
+        { ...payload, __rd__: nodeRuntime.recursionDepth + 1 },
+        nodeRuntime.createNestedRuntime(functionId),
+      );
+      return { onSuccess: true, onFailure: false, result: (result as object) ?? {} };
+    } catch (error) {
+      const controlFlowCode =
+        typeof error === 'object' && error !== null
+          ? (error as { code?: unknown }).code
+          : undefined;
+      if (
+        CancellationError.isCancellationError(error) ||
+        controlFlowCode === 'FLOW_WEAVER_DURABLE_GATE_YIELD' ||
+        controlFlowCode === 'FLOW_WEAVER_AMBIGUOUS_EFFECT'
+      ) {
+        throw error;
+      }
+      return { onSuccess: false, onFailure: true, result: {} };
+    }
+  }
+
+  // No mocks, no registry match: original no-op behavior (always succeeds)
+  return { onSuccess: true, onFailure: false, result: {} };
+}
+`.trim(),
+    functionTextProduction: `
+async function invokeWorkflow(
+  execute: boolean,
+  functionId: string,
+  payload: object,
+  timeout?: string,
+  abortSignal?: AbortSignal,
+  runtime?: NodeExecutionRuntime,
+): Promise<{ onSuccess: boolean; onFailure: boolean; result: object }> {
+  if (!execute) return { onSuccess: false, onFailure: false, result: {} };
+
+
+  // Check local workflow registry (populated by executeWorkflow)
+  const registry = runtime?.runtime.services.workflowRegistry;
+  if (registry?.[functionId]) {
+    const nodeRuntime = runtime!;
+    if (
+      !Number.isSafeInteger(nodeRuntime.recursionDepth) ||
+      nodeRuntime.recursionDepth < 0 ||
+      nodeRuntime.recursionDepth >= 999
+    ) {
+      throw new Error('Max recursion depth exceeded (1000) in dynamic workflow invocation');
+    }
+    try {
+      const result = await registry[functionId](
+        true,
+        { ...payload, __rd__: nodeRuntime.recursionDepth + 1 },
+        nodeRuntime.createNestedRuntime(functionId),
+      );
+      return { onSuccess: true, onFailure: false, result: (result as object) ?? {} };
+    } catch (error) {
+      const controlFlowCode =
+        typeof error === 'object' && error !== null
+          ? (error as { code?: unknown }).code
+          : undefined;
+      if (
+        CancellationError.isCancellationError(error) ||
+        controlFlowCode === 'FLOW_WEAVER_DURABLE_GATE_YIELD' ||
+        controlFlowCode === 'FLOW_WEAVER_AMBIGUOUS_EFFECT'
+      ) {
+        throw error;
+      }
+      return { onSuccess: false, onFailure: true, result: {} };
+    }
+  }
+
+  return { onSuccess: true, onFailure: false, result: {} };
+}
+`.trim()
+  },
+  {
+    type: "NodeType",
+    name: "waitForAgent",
+    functionName: "waitForAgent",
+    isAsync: true,
+    receivesAbortSignal: true,
+    receivesRuntime: true,
+    durableGate: "agent",
+    hasSuccessPort: true,
+    hasFailurePort: true,
+    executeWhen: "CONJUNCTION",
+    variant: "FUNCTION",
+    inputs: {
+      execute: { dataType: "STEP", label: "Execute" },
+      agentId: { dataType: "STRING", label: "Agent/task identifier", tsType: "string" },
+      context: { dataType: "OBJECT", label: "Context data to send to the agent", tsType: "object" },
+      prompt: { dataType: "STRING", label: "Message to display when requesting input", tsType: "string", optional: true }
+    },
+    outputs: {
+      agentResult: { dataType: "OBJECT", label: "Result returned by the agent", tsType: "object" },
+      onSuccess: { dataType: "STEP", label: "On Success", isControlFlow: true },
+      onFailure: { dataType: "STEP", label: "On Failure", isControlFlow: true, failure: true }
+    },
+    helperText: `
+function __fw_getMockConfig(runtime?: NodeExecutionRuntime): FwMockConfig | undefined {
+  return runtime?.runtime.services.mocks;
+}
+
+function __fw_lookupMock<T>(
+  section: Record<string, T> | undefined,
+  key: string,
+  runtime?: NodeExecutionRuntime,
+): T | undefined {
+  if (!section) return undefined;
+
+  const nodeId = runtime?.nodeId;
+  if (nodeId) {
+    const qualified = section[\`\${nodeId}:\${key}\`];
+    if (qualified !== undefined) return qualified;
+    const any = section[\`\${nodeId}:*\`];
+    if (any !== undefined) return any;
+  }
+
+  return section[key];
+}
+`.trim(),
+    helperTextProduction: void 0,
+    functionText: `
+async function waitForAgent(
+  execute: boolean,
+  agentId: string,
+  context: object,
+  prompt?: string,
+  _abortSignal?: AbortSignal,
+  runtime?: NodeExecutionRuntime,
+): Promise<{ onSuccess: boolean; onFailure: boolean; agentResult: object }> {
+  if (!execute) return { onSuccess: false, onFailure: false, agentResult: {} };
+
+  // An agent gate. The compiler replaces this call with a durable yield, and
+  // the engine answers the gate: from a person, or under test from the run's
+  // canned answers (see \`FwMockConfig\` in \`src/built-in-nodes/mock-types.ts\`
+  // for how those are read). Reaching this body means the generated program
+  // did not apply the gate boundary, so it fails closed.
+  void agentId;
+  void context;
+  void prompt;
+  void runtime;
+  throw new Error('waitForAgent requires a generated durable agent gate');
+}
+`.trim(),
+    functionTextProduction: `
+async function waitForAgent(
+  execute: boolean,
+  agentId: string,
+  context: object,
+  prompt?: string,
+  _abortSignal?: AbortSignal,
+  runtime?: NodeExecutionRuntime,
+): Promise<{ onSuccess: boolean; onFailure: boolean; agentResult: object }> {
+  if (!execute) return { onSuccess: false, onFailure: false, agentResult: {} };
+
+  // An agent gate. The compiler replaces this call with a durable yield, and
+  // the engine answers the gate: from a person, or under test from the run's
+  // for how those are read). Reaching this body means the generated program
+  // did not apply the gate boundary, so it fails closed.
+  void agentId;
+  void context;
+  void prompt;
+  void runtime;
+  throw new Error('waitForAgent requires a generated durable agent gate');
+}
+`.trim()
+  }
+];
+
+// src/parser/port-inference.ts
+import * as path from "node:path";
+function parseStartPorts(fn, config) {
+  const ports = {};
+  const params = fn.getParameters();
+  if (params.length === 0) {
+    ports.execute = { dataType: "STEP", label: "Execute" };
+    return ports;
+  }
+  const firstParam = params[0];
+  const firstParamName = firstParam.getName();
+  const firstParamType = firstParam.getType();
+  const firstParamTypeText = firstParamType.getText();
+  const isExecutePort2 = firstParamName === "execute" && (firstParamTypeText === "boolean" || firstParamTypeText === "any" && config?.startPorts?.["execute"]);
+  if (isExecutePort2) {
+    if (config?.startPorts && config.startPorts["execute"]) {
+      ports.execute = {
+        dataType: "STEP",
+        tsType: "boolean",
+        ...config.startPorts["execute"]
+      };
+    } else {
+      ports.execute = { dataType: "STEP", tsType: "boolean", label: "Execute" };
+    }
+    if (params.length > 1) {
+      const dataParams = params.slice(1).filter(
+        (p) => p.getName() !== "__runtime__" && !["AbortSignal", "TDebugger"].includes(p.getType().getText(p))
+      );
+      const shouldExpandProperties = dataParams.length === 1 && isExpandableObjectType(dataParams[0].getType());
+      const declaresNoPorts = dataParams.length === 1 && isPropertylessObjectType(dataParams[0].getType());
+      if (declaresNoPorts) {
+      } else if (shouldExpandProperties) {
+        const dataParam = dataParams[0];
+        const dataParamType = dataParam.getType();
+        const properties = dataParamType.getProperties();
+        properties.forEach((prop) => {
+          const propName = prop.getName();
+          const propType = prop.getTypeAtLocation(dataParam);
+          const portType = inferPortType(propType);
+          const propTypeText = propType.getText();
+          const tsSchema = portType === "OBJECT" ? extractTypeSchema(propType) : void 0;
+          const startPortConfig = config?.startPorts?.[propName];
+          ports[propName] = {
+            dataType: portType,
+            label: startPortConfig?.label || capitalize(propName),
+            ...startPortConfig?.optional === true && { optional: true },
+            ...startPortConfig !== void 0 && Object.hasOwn(startPortConfig, "default") ? { default: startPortConfig.default } : {},
+            ...startPortConfig?.metadata && { metadata: startPortConfig.metadata },
+            ...propTypeText && { tsType: propTypeText },
+            ...tsSchema && Object.keys(tsSchema).length > 0 && { tsSchema }
+          };
+        });
+      } else {
+        for (const param of dataParams) {
+          const paramName = param.getName();
+          const paramType = param.getType();
+          const portType = inferPortType(paramType);
+          const rawParamTypeText = paramType.getText(param);
+          const paramTypeText = param.isOptional() || param.hasInitializer() ? stripOptionalUndefined(rawParamTypeText) : rawParamTypeText;
+          const tsSchema = portType === "OBJECT" ? extractTypeSchema(paramType) : void 0;
+          const startPortConfig = config?.startPorts?.[paramName];
+          ports[paramName] = {
+            dataType: portType,
+            label: startPortConfig?.label || capitalize(paramName),
+            ...startPortConfig?.optional === true && { optional: true },
+            ...startPortConfig !== void 0 && Object.hasOwn(startPortConfig, "default") ? { default: startPortConfig.default } : {},
+            ...startPortConfig?.metadata && { metadata: startPortConfig.metadata },
+            ...paramTypeText && { tsType: paramTypeText },
+            ...tsSchema && Object.keys(tsSchema).length > 0 && { tsSchema }
+          };
+        }
+      }
+    }
+  } else {
+    throw new Error(
+      `Invalid workflow function signature for "${fn.getName()}". Expected first parameter to be "execute: boolean", but got "${firstParamName}: ${firstParamTypeText}". Correct format: export function ${fn.getName()}(execute: boolean, params: {...}): { onSuccess: boolean; onFailure: boolean; ... }`
+    );
+  }
+  assignImplicitPortOrders(ports);
+  return ports;
+}
+function parseExitPorts(fn, config, warnings) {
+  const ports = {};
+  let returnType = fn.getReturnType();
+  const typeText = returnType?.getText();
+  const sourceFile = fn.getSourceFile();
+  const filePath = sourceFile?.getFilePath() || "unknown file";
+  const fileName = path.basename(filePath);
+  if (!typeText || typeText === "void") {
+    warnings?.push(
+      `Could not determine the return type of workflow "${fn.getName()}" in ${fileName}, so it has no Exit ports. Add an explicit return type like: Promise<{ onSuccess: boolean; onFailure: boolean }>`
+    );
+    return ports;
+  }
+  if (typeText.startsWith("Promise<")) {
+    const typeArgs = returnType.getTypeArguments();
+    if (typeArgs && typeArgs.length > 0) {
+      returnType = typeArgs[0];
+    }
+  }
+  const properties = returnType.getProperties();
+  properties.forEach((prop) => {
+    const propName = prop.getName();
+    if (propName === "onSuccess" || propName === "onFailure") {
+      const returnPortConfig = config?.returnPorts?.[propName];
+      ports[propName] = {
+        dataType: "STEP",
+        label: returnPortConfig?.label || (propName === "onSuccess" ? "On Success" : "On Failure"),
+        isControlFlow: true,
+        ...propName === "onFailure" && { failure: true },
+        ...returnPortConfig?.metadata && { metadata: returnPortConfig.metadata }
+      };
+    } else {
+      const propType = prop.getTypeAtLocation(fn.getTypeResolutionNode());
+      const portType = inferPortType(propType);
+      const propTypeText = propType.getText();
+      const tsSchema = portType === "OBJECT" ? extractTypeSchema(propType) : void 0;
+      const returnPortConfig = config?.returnPorts?.[propName];
+      ports[propName] = {
+        dataType: portType,
+        label: returnPortConfig?.label || capitalize(propName),
+        ...returnPortConfig?.metadata && { metadata: returnPortConfig.metadata },
+        // Include original TS type for rich type display (e.g., "ResearchReport" instead of "object")
+        ...propTypeText && propTypeText !== portType.toLowerCase() && { tsType: propTypeText },
+        // Include schema breakdown for complex types
+        ...tsSchema && Object.keys(tsSchema).length > 0 && { tsSchema }
+      };
+    }
+  });
+  assignImplicitPortOrders(ports);
+  return ports;
+}
+function extractTypeSchema(tsType) {
+  const schema = {};
+  const properties = tsType.getProperties();
+  if (!properties || properties.length === 0) {
+    return void 0;
+  }
+  for (const prop of properties) {
+    const propName = prop.getName();
+    if (propName.startsWith("_")) continue;
+    const propType = prop.getValueDeclaration()?.getType();
+    if (propType) {
+      schema[propName] = propType.getText();
+    } else {
+      const declarations = prop.getDeclarations();
+      if (declarations && declarations.length > 0) {
+        const decl = declarations[0];
+        schema[propName] = decl.getType().getText();
+      }
+    }
+  }
+  return Object.keys(schema).length > 0 ? schema : void 0;
+}
+function isPropertylessObjectType(tsType) {
+  return tsType.isObject() && !tsType.isArray() && tsType.getCallSignatures().length === 0 && tsType.getProperties().length === 0;
+}
+function isExpandableObjectType(tsType) {
+  const typeText = tsType.getText();
+  const primitiveTypes = /* @__PURE__ */ new Set(["string", "number", "boolean", "any", "unknown", "never", "object", "Object"]);
+  if (primitiveTypes.has(typeText)) return false;
+  if (typeText.endsWith("[]") || typeText.startsWith("Array<")) return false;
+  return tsType.isObject() && tsType.getProperties().length > 0;
+}
+function inferPortType(tsType) {
+  const typeText = tsType.getText();
+  return inferDataTypeFromTS(typeText);
+}
+function capitalize(str) {
+  return str.charAt(0).toUpperCase() + str.slice(1);
+}
+
+// src/parser/durable-effect-contract.ts
+function jsDocTagComment(fn, tagName) {
+  for (const doc of fn.getJsDocs()) {
+    for (const tag of doc.getTags()) {
+      if (tag.getTagName() === tagName) {
+        return tag.getCommentText?.()?.trim() ?? "";
+      }
+    }
+  }
+  return void 0;
+}
+function hasJsDocTag(fn, tagName) {
+  return jsDocTagComment(fn, tagName) !== void 0;
+}
+function durableGateKind(fn) {
+  const kind = jsDocTagComment(fn, "durableGate")?.split(/\s+/)[0];
+  return kind === "approval" || kind === "input" || kind === "agent" || kind === "timer" ? kind : void 0;
+}
+function describeType(type, fn) {
+  return type.getText(fn.getTypeResolutionNode());
+}
+function nonUndefinedUnionMembers(type) {
+  const members = type.isUnion() ? type.getUnionTypes() : [type];
+  return members.filter((member) => !member.isUndefined());
+}
+function wireTypeFailure(type, path4 = "$", seen = /* @__PURE__ */ new Set()) {
+  const identity = type.compilerType;
+  if (seen.has(identity)) return void 0;
+  seen.add(identity);
+  const members = nonUndefinedUnionMembers(type);
+  if (members.length === 0) return `${path4} has no defined member`;
+  if (members.length > 1 || type.isUnion()) {
+    for (const member of members) {
+      const failure = wireTypeFailure(member, path4, new Set(seen));
+      if (failure !== void 0) return failure;
+    }
+    return void 0;
+  }
+  const candidate = members[0];
+  if (candidate.isAny() || candidate.isUnknown() || candidate.isNever() || candidate.isVoid() || candidate.isBigInt() || candidate.isBigIntLiteral()) {
+    return `${path4} is ${candidate.getText()}`;
+  }
+  if (candidate.isNull() || candidate.isString() || candidate.isStringLiteral() || candidate.isNumber() || candidate.isNumberLiteral() || candidate.isBoolean() || candidate.isBooleanLiteral() || candidate.isTemplateLiteral()) {
+    return void 0;
+  }
+  if (candidate.isTuple()) {
+    for (const [index, element] of candidate.getTupleElements().entries()) {
+      const failure = wireTypeFailure(element, `${path4}[${index}]`, new Set(seen));
+      if (failure !== void 0) return failure;
+    }
+    return void 0;
+  }
+  if (candidate.isArray() || candidate.isReadonlyArray()) {
+    const element = candidate.getArrayElementType();
+    return element === void 0 ? `${path4} has no array element type` : wireTypeFailure(element, `${path4}[]`, new Set(seen));
+  }
+  if (!candidate.isObject() || candidate.isClass()) return `${path4} is not a plain object`;
+  if (candidate.getCallSignatures().length > 0 || candidate.getConstructSignatures().length > 0) {
+    return `${path4} is callable or constructable`;
+  }
+  const indexTypes = [
+    candidate.getStringIndexType(),
+    candidate.getNumberIndexType()
+  ].filter((indexType) => indexType !== void 0);
+  for (const indexType of indexTypes) {
+    const failure = wireTypeFailure(indexType, `${path4}[key]`, new Set(seen));
+    if (failure !== void 0) return failure;
+  }
+  for (const property of candidate.getProperties()) {
+    const location = property.getValueDeclaration() ?? property.getDeclarations()[0];
+    if (location === void 0) return `${path4}.${property.getName()} has no declaration`;
+    const failure = wireTypeFailure(
+      property.getTypeAtLocation(location),
+      `${path4}.${property.getName()}`,
+      new Set(seen)
+    );
+    if (failure !== void 0) return failure;
+  }
+  return void 0;
+}
+function matchesPortType(type, dataType) {
+  const members = nonUndefinedUnionMembers(type);
+  if (members.length === 0) return false;
+  return members.every((member) => {
+    switch (dataType) {
+      case "STRING":
+        return member.isString() || member.isStringLiteral() || member.isTemplateLiteral();
+      case "NUMBER":
+        return member.isNumber() || member.isNumberLiteral();
+      case "BOOLEAN":
+      case "STEP":
+        return member.isBoolean() || member.isBooleanLiteral();
+      case "ARRAY":
+        return member.isArray() || member.isReadonlyArray() || member.isTuple();
+      case "OBJECT":
+        return member.isObject() && !member.isArray() && !member.isReadonlyArray();
+      case "FUNCTION":
+        return member.getCallSignatures().length > 0;
+      case "ANY":
+        return true;
+    }
+  });
+}
+function validateEnvelopeMember(envelope, outputs, fn) {
+  const diagnostics = [];
+  if (!envelope.isObject() || envelope.isArray() || envelope.isReadonlyArray()) {
+    return [
+      `return type must be exactly { receipt, result }, got ${describeType(envelope, fn)}`
+    ];
+  }
+  if (envelope.getStringIndexType() || envelope.getNumberIndexType()) {
+    diagnostics.push("return envelope must not declare an index signature");
+  }
+  const envelopeProperties = envelope.getProperties();
+  const envelopeNames = envelopeProperties.map((property) => property.getName()).sort();
+  if (envelopeNames.join(",") !== "receipt,result") {
+    diagnostics.push(
+      `return envelope must have exactly the required receipt and result fields. Found ${envelopeNames.join(", ") || "none"}`
+    );
+  }
+  const receiptProperty = envelope.getProperty("receipt");
+  const resultProperty = envelope.getProperty("result");
+  if (receiptProperty?.isOptional()) diagnostics.push("receipt must be required");
+  if (resultProperty?.isOptional()) diagnostics.push("result must be required");
+  const location = fn.getTypeResolutionNode();
+  if (receiptProperty) {
+    const receiptType = receiptProperty.getTypeAtLocation(location);
+    const failure = wireTypeFailure(receiptType);
+    if (failure !== void 0) {
+      diagnostics.push(
+        `receipt must be a durable wire value, got ${describeType(receiptType, fn)} (${failure})`
+      );
+    }
+  }
+  if (!resultProperty) {
+    const expectedNames2 = Object.entries(outputs).filter(([, output]) => output.scope === void 0).map(([name]) => name).sort();
+    const plainResultNames = envelopeProperties.map((property) => property.getName()).sort();
+    const missing = expectedNames2.filter((name) => !plainResultNames.includes(name));
+    const extra = plainResultNames.filter((name) => !expectedNames2.includes(name));
+    diagnostics.push(
+      [
+        "result fields must exactly match the node outputs",
+        missing.length > 0 ? `missing ${missing.join(", ")}` : void 0,
+        extra.length > 0 ? `unexpected ${extra.join(", ")}` : void 0
+      ].filter(Boolean).join("; ")
+    );
+    return diagnostics;
+  }
+  const resultType = resultProperty.getTypeAtLocation(location);
+  if (!resultType.isObject() || resultType.isArray() || resultType.isReadonlyArray()) {
+    diagnostics.push(
+      `result must be an object matching the node outputs, got ${describeType(resultType, fn)}`
+    );
+    return diagnostics;
+  }
+  const resultFailure = wireTypeFailure(resultType);
+  if (resultFailure !== void 0) {
+    diagnostics.push(
+      `result must be a durable wire value, got ${describeType(resultType, fn)} (${resultFailure})`
+    );
+  }
+  const expectedNames = Object.entries(outputs).filter(([, output]) => output.scope === void 0).map(([name]) => name).sort();
+  const actualNames = resultType.getProperties().map((property) => property.getName()).sort();
+  if (actualNames.join(",") !== expectedNames.join(",")) {
+    const missing = expectedNames.filter((name) => !actualNames.includes(name));
+    const extra = actualNames.filter((name) => !expectedNames.includes(name));
+    diagnostics.push(
+      [
+        "result fields must exactly match the node outputs",
+        missing.length > 0 ? `missing ${missing.join(", ")}` : void 0,
+        extra.length > 0 ? `unexpected ${extra.join(", ")}` : void 0
+      ].filter(Boolean).join("; ")
+    );
+  }
+  for (const [name, output] of Object.entries(outputs)) {
+    if (output.scope !== void 0) continue;
+    const property = resultType.getProperty(name);
+    if (!property) continue;
+    if (property.isOptional()) {
+      diagnostics.push(`result.${name} must be required`);
+      continue;
+    }
+    const propertyType = property.getTypeAtLocation(location);
+    if (!matchesPortType(propertyType, output.dataType)) {
+      diagnostics.push(
+        `result.${name} is ${describeType(propertyType, fn)}, incompatible with ${output.dataType}`
+      );
+    }
+  }
+  return diagnostics;
+}
+function analyzeDurableEffectContract(fn, inputs, outputs) {
+  const diagnostics = [];
+  const parameters = fn.getParameters();
+  const operationKey = parameters.at(-1);
+  if (!operationKey) {
+    diagnostics.push("callable must accept a required final operationKey: string parameter");
+  } else {
+    if (operationKey.isOptional() || operationKey.hasInitializer() || operationKey.isRestParameter()) {
+      diagnostics.push("final operationKey parameter must be required and non-rest");
+    }
+    const operationKeyType = operationKey.getType();
+    if (!operationKeyType.isString() || operationKeyType.isStringLiteral()) {
+      diagnostics.push(
+        `final operationKey parameter must be string, got ${describeType(operationKeyType, fn)}`
+      );
+    }
+    if (Object.hasOwn(inputs, operationKey.getName())) {
+      diagnostics.push(
+        "callable must accept an injected final operationKey: string after every declared node input"
+      );
+    }
+  }
+  const declaredReturn = fn.getReturnType();
+  const resolvedReturn = declaredReturn.getAwaitedType() ?? declaredReturn;
+  const returnMembers = resolvedReturn.isUnion() ? resolvedReturn.getUnionTypes() : [resolvedReturn];
+  for (const returnMember of returnMembers) {
+    diagnostics.push(...validateEnvelopeMember(returnMember, outputs, fn));
+  }
+  return { valid: diagnostics.length === 0, diagnostics };
+}
+
+// src/parser/node-inference.ts
+function returnsPromise(fn) {
+  return fn.isAsync() || fn.getReturnType().getText().startsWith("Promise<");
+}
+function extractNodeTypes(sourceFile, warnings, tagRegistry) {
+  const nodeTypes = [];
+  warnings.push(...nestedAnnotationWarnings(sourceFile));
+  extractFunctionLikes(sourceFile).forEach((fn) => {
+    const config = jsdocParser.parseNodeType(fn, warnings, tagRegistry);
+    if (!config) {
+      const jsdocText = fn.getJsDocs().map((d) => d.getFullText()).join("");
+      if (jsdocText.includes("@flowWeaver nodeType")) {
+        warnings.push(
+          `Function "${fn.getName() || "anonymous"}" has @flowWeaver annotation but could not be parsed. Check for special characters (---) or malformed JSDoc syntax.`
+        );
+      }
+      return;
+    }
+    const functionName = fn.getName() || "anonymous";
+    const nodeTypeName = config.name || functionName;
+    const durableGate = durableGateKind(fn);
+    const durableEffect = hasJsDocTag(fn, "durableEffect");
+    const durablePure = hasJsDocTag(fn, "durablePure");
+    const builtIn = BUILT_IN_NODE_TYPES.find((nt) => nt.functionName === functionName);
+    const paramTypes = builtIn ? fn.getParameters().map((p) => p.getTypeNode()?.getText()) : [];
+    const receivesAbortSignal = builtIn?.receivesAbortSignal === true && paramTypes.includes("AbortSignal");
+    const receivesRuntime = builtIn?.receivesRuntime === true && paramTypes.includes("NodeExecutionRuntime");
+    const inputs = {};
+    if (config.inputs) {
+      for (const [portName, portDef] of Object.entries(config.inputs)) {
+        inputs[portName] = {
+          dataType: portDef.type,
+          default: portDef.defaultValue,
+          optional: portDef.optional,
+          label: portDef.label,
+          expression: portDef.expression,
+          ...portDef.scope && { scope: portDef.scope },
+          ...portDef.hidden && { hidden: portDef.hidden },
+          ...portDef.metadata && { metadata: portDef.metadata },
+          ...portDef.tsType && { tsType: portDef.tsType },
+          // The fan-in strategy is what lets the validator accept several
+          // connections into this port and tells the generator how to combine
+          // them. Dropping it here silently turned every strategy into FIRST.
+          ...portDef.mergeStrategy && { mergeStrategy: portDef.mergeStrategy }
+        };
+      }
+    }
+    const outputs = {};
+    if (config.outputs) {
+      for (const [portName, portDef] of Object.entries(config.outputs)) {
+        outputs[portName] = {
+          dataType: portDef.type,
+          label: portDef.label,
+          ...portDef.scope && { scope: portDef.scope },
+          ...portDef.hidden && { hidden: portDef.hidden },
+          ...portDef.metadata && { metadata: portDef.metadata },
+          ...portDef.tsType && { tsType: portDef.tsType }
+        };
+      }
+    }
+    const isStub = fn.isAmbient?.() ?? false;
+    if (isStub) {
+      config.expression = true;
+    }
+    if (config.expression) {
+      const inferred = inferNodeTypeFromFunction(
+        fn,
+        nodeTypeName,
+        fn.getSourceFile().getFilePath()
+      );
+      const reconcile = (explicit, inferredPorts, isControl) => {
+        const explicitData = Object.entries(explicit).filter(([name]) => !isControl(name));
+        const inferredData = Object.entries(inferredPorts).filter(([name]) => !isControl(name));
+        if (explicitData.length === 0) return Object.fromEntries(inferredData);
+        const inferredNames = new Set(inferredData.map(([name]) => name));
+        const isPartial = explicitData.length < inferredData.length && explicitData.every(([name]) => inferredNames.has(name));
+        if (!isPartial) return Object.fromEntries(explicitData);
+        const explicitByName = new Map(explicitData);
+        return Object.fromEntries(
+          inferredData.map(([name, port]) => {
+            const override = explicitByName.get(name);
+            if (!override) return [name, port];
+            const refined = { ...port };
+            for (const [key, value] of Object.entries(override)) {
+              if (value === void 0) continue;
+              if (key === "dataType" && value === "ANY") continue;
+              if (key === "label" && typeof value === "string" && value.length === 0) continue;
+              refined[key] = value;
+            }
+            return [name, refined];
+          })
+        );
+      };
+      const reconciledInputs = reconcile(inputs, inferred.inputs, (n) => n === "execute");
+      const reconciledOutputs = reconcile(outputs, inferred.outputs, (n) => n === "onSuccess" || n === "onFailure");
+      for (const key of Object.keys(inputs)) if (key !== "execute") delete inputs[key];
+      for (const key of Object.keys(outputs)) if (key !== "onSuccess" && key !== "onFailure") delete outputs[key];
+      Object.assign(inputs, reconciledInputs);
+      Object.assign(outputs, reconciledOutputs);
+    }
+    inputs.execute = {
+      label: "Execute",
+      // Default label
+      ...inputs.execute,
+      // User can override label
+      dataType: "STEP"
+      // But dataType is mandatory
+    };
+    outputs.onSuccess = {
+      label: "On Success",
+      // Default label
+      ...outputs.onSuccess,
+      // User can override label
+      dataType: "STEP",
+      // But dataType is mandatory
+      isControlFlow: true
+      // Always a control flow port
+    };
+    outputs.onFailure = {
+      label: "On Failure",
+      // Default label
+      ...outputs.onFailure,
+      // User can override label
+      dataType: "STEP",
+      // But dataType is mandatory
+      failure: true,
+      // Always a failure port
+      isControlFlow: true
+      // Always a control flow port
+    };
+    assignImplicitPortOrders(inputs);
+    assignImplicitPortOrders(outputs);
+    const jsDocs = fn.getJsDocs();
+    const jsDocText = jsDocs.map((doc) => doc.getText()).join("\n");
+    const functionText = isStub ? void 0 : jsDocText ? `${jsDocText}
+${fn.getText()}` : fn.getText();
+    const durableEffectContract = durableEffect ? analyzeDurableEffectContract(fn, inputs, outputs) : void 0;
+    const isAsync = returnsPromise(fn);
+    let defaultConfig = void 0;
+    if (config.defaultConfig) {
+      defaultConfig = {
+        label: config.defaultConfig.label,
+        description: config.defaultConfig.description,
+        pullExecution: config.defaultConfig.pullExecution
+      };
+    }
+    const portScopes = /* @__PURE__ */ new Set();
+    Object.values(inputs).forEach((port) => {
+      if (port.scope) portScopes.add(port.scope);
+    });
+    Object.values(outputs).forEach((port) => {
+      if (port.scope) portScopes.add(port.scope);
+    });
+    let scopes;
+    if (config.scope) {
+      scopes = [config.scope];
+    } else if (portScopes.size > 0) {
+      const orderedScopes = [];
+      try {
+        const params = fn.getParameters();
+        for (const param of params) {
+          const paramName = param.getName();
+          if (portScopes.has(paramName)) {
+            orderedScopes.push(paramName);
+          }
+        }
+      } catch {
+      }
+      for (const scope of portScopes) {
+        if (!orderedScopes.includes(scope)) {
+          orderedScopes.push(scope);
+        }
+      }
+      scopes = orderedScopes;
+    }
+    nodeTypes.push({
+      type: "NodeType",
+      name: nodeTypeName,
+      functionName,
+      variant: isStub ? "STUB" : "FUNCTION",
+      inputs,
+      outputs,
+      hasSuccessPort: RESERVED_PORT_NAMES.ON_SUCCESS in outputs,
+      hasFailurePort: RESERVED_PORT_NAMES.ON_FAILURE in outputs,
+      isAsync,
+      functionText,
+      ...durableGate && { durableGate },
+      ...durableEffect && { durableEffect: true },
+      ...durableEffectContract && { durableEffectContract },
+      ...durablePure && { durablePure: true },
+      ...receivesAbortSignal && { receivesAbortSignal: true },
+      ...receivesRuntime && { receivesRuntime: true },
+      ...config.resilience && { resilience: config.resilience },
+      executeWhen: config.executeWhen || EXECUTION_STRATEGIES.CONJUNCTION,
+      defaultConfig,
+      scope: config.scope,
+      scopes,
+      ...config.expression && { expression: true },
+      ...fn.getDeclarationKind?.() && { declarationKind: fn.getDeclarationKind() },
+      label: config.label,
+      description: config.description,
+      visuals: config.color || config.icon || config.tags ? {
+        color: config.color,
+        icon: config.icon,
+        tags: config.tags
+      } : void 0,
+      ...config.deploy && { deploy: config.deploy },
+      sourceLocation: {
+        file: sourceFile.getFilePath(),
+        line: fn.getStartLineNumber(false),
+        column: 0
+      }
+    });
+  });
+  return nodeTypes;
+}
+function inferNodeTypeFromFunction(fn, name, filePath) {
+  const durableGate = durableGateKind(fn);
+  const durableEffect = hasJsDocTag(fn, "durableEffect");
+  const durablePure = hasJsDocTag(fn, "durablePure");
+  const inputs = {};
+  const params = fn.getParameters();
+  const firstParamIsExecute = params.length > 0 && params[0].getName() === "execute";
+  const authoredInputParams = durableEffect ? params.slice(0, -1) : params;
+  for (const param of authoredInputParams) {
+    const paramName = param.getName();
+    const optional = param.isOptional() || param.hasInitializer();
+    const rawTsType = param.getType().getText(param);
+    const tsType = optional ? stripOptionalUndefined(rawTsType) : rawTsType;
+    const dataType = inferDataTypeFromTS(tsType);
+    inputs[paramName] = {
+      dataType,
+      optional: optional || void 0,
+      label: capitalize(paramName),
+      tsType
+    };
+  }
+  const outputs = {};
+  let returnType = fn.getReturnType();
+  const returnTypeText = returnType.getText();
+  if (returnTypeText.startsWith("Promise<")) {
+    const typeArgs = returnType.getTypeArguments();
+    if (typeArgs && typeArgs.length > 0) {
+      returnType = typeArgs[0];
+    }
+  }
+  if (durableEffect) {
+    const effectResult = returnType.getProperty("result");
+    if (effectResult) {
+      returnType = effectResult.getTypeAtLocation(fn.getTypeResolutionNode());
+    }
+  }
+  const unwrappedText = returnType.getText();
+  if (unwrappedText !== "void" && unwrappedText !== "undefined") {
+    const primitiveTypes = /* @__PURE__ */ new Set(["string", "number", "boolean", "any", "unknown", "never"]);
+    const isPrimitive = primitiveTypes.has(unwrappedText);
+    const isArray = unwrappedText.endsWith("[]") || unwrappedText.startsWith("Array<");
+    const properties = returnType.getProperties();
+    const isObjectLike = !isPrimitive && !isArray && returnType.isObject() && properties.length > 0;
+    if (isObjectLike) {
+      for (const prop of properties) {
+        const propName = prop.getName();
+        if (propName === "onSuccess" || propName === "onFailure") continue;
+        const propType = prop.getTypeAtLocation(fn.getTypeResolutionNode());
+        const propTypeText = propType.getText();
+        const dataType = inferDataTypeFromTS(propTypeText);
+        outputs[propName] = {
+          dataType,
+          label: capitalize(propName),
+          tsType: propTypeText
+        };
+      }
+    } else {
+      const dataType = inferDataTypeFromTS(unwrappedText);
+      outputs.result = {
+        dataType,
+        label: "Result",
+        tsType: unwrappedText
+      };
+    }
+  }
+  inputs.execute = { dataType: "STEP", label: "Execute" };
+  outputs.onSuccess = { dataType: "STEP", label: "On Success", isControlFlow: true };
+  outputs.onFailure = {
+    dataType: "STEP",
+    label: "On Failure",
+    failure: true,
+    isControlFlow: true
+  };
+  assignImplicitPortOrders(inputs);
+  assignImplicitPortOrders(outputs);
+  const jsDocs = fn.getJsDocs();
+  const jsDocText = jsDocs.map((doc) => doc.getText()).join("\n");
+  const functionText = jsDocText ? `${jsDocText}
+${fn.getText()}` : fn.getText();
+  const durableEffectContract = durableEffect ? analyzeDurableEffectContract(fn, inputs, outputs) : void 0;
+  return {
+    type: "NodeType",
+    name,
+    functionName: name,
+    variant: "FUNCTION",
+    inputs,
+    outputs,
+    hasSuccessPort: true,
+    hasFailurePort: true,
+    isAsync: returnsPromise(fn),
+    executeWhen: EXECUTION_STRATEGIES.CONJUNCTION,
+    expression: !firstParamIsExecute,
+    // Expression only if original function lacks execute as first param
+    inferred: true,
+    functionText,
+    ...durableGate && { durableGate },
+    ...durableEffect && { durableEffect: true },
+    ...durableEffectContract && { durableEffectContract },
+    ...durablePure && { durablePure: true },
+    ...fn.getDeclarationKind?.() && {
+      declarationKind: fn.getDeclarationKind()
+    },
+    sourceLocation: {
+      file: filePath,
+      line: fn.getStartLineNumber(false),
+      column: 0
+    }
+  };
+}
+function inferAllUnannotatedFunctions(sourceFile, existingNodeTypes) {
+  const allFunctions = extractFunctionLikes(sourceFile);
+  const existingNames = /* @__PURE__ */ new Set();
+  for (const nt of existingNodeTypes) {
+    existingNames.add(nt.name);
+    existingNames.add(nt.functionName);
+  }
+  const inferred = [];
+  for (const fn of allFunctions) {
+    const fnName = fn.getName();
+    if (!fnName) continue;
+    if (existingNames.has(fnName)) continue;
+    if (hasFlowWeaverAnnotation(fn)) continue;
+    inferred.push(inferNodeTypeFromFunction(fn, fnName, sourceFile.getFilePath()));
+    existingNames.add(fnName);
+  }
+  return inferred;
+}
+function inferNodeTypesFromUnannotated(sourceFile, existingNodeTypes, localNodeTypes, warnings) {
+  const allFunctions = extractFunctionLikes(sourceFile);
+  const referencedTypes = /* @__PURE__ */ new Set();
+  for (const fn of allFunctions) {
+    const config = jsdocParser.parseWorkflow(fn, []);
+    if (!config) continue;
+    for (const inst of config.instances || []) {
+      referencedTypes.add(inst.type);
+    }
+  }
+  const existingNames = /* @__PURE__ */ new Set();
+  for (const nt of existingNodeTypes) {
+    existingNames.add(nt.name);
+    existingNames.add(nt.functionName);
+  }
+  const unresolvedTypes = /* @__PURE__ */ new Set();
+  for (const typeName of referencedTypes) {
+    if (!existingNames.has(typeName)) {
+      unresolvedTypes.add(typeName);
+    }
+  }
+  if (unresolvedTypes.size === 0) return [];
+  const inferredNodeTypes = [];
+  const alreadyInferred = /* @__PURE__ */ new Set();
+  const builtInByName = new Map(BUILT_IN_NODE_TYPES.map((nt) => [nt.name, nt]));
+  const annotatedNames = new Set(localNodeTypes.map((nt) => nt.functionName));
+  for (const unresolvedType of unresolvedTypes) {
+    if (alreadyInferred.has(unresolvedType)) continue;
+    const builtIn = builtInByName.get(unresolvedType);
+    if (builtIn) {
+      inferredNodeTypes.push(builtIn);
+      alreadyInferred.add(unresolvedType);
+      if (!annotatedNames.has(unresolvedType)) {
+        const shadowFn = allFunctions.find((fn) => fn.getName() === unresolvedType && !hasFlowWeaverAnnotation(fn));
+        if (shadowFn) {
+          warnings.push(
+            `Function '${unresolvedType}' exists in this file but is not annotated with @flowWeaver nodeType. The built-in '${unresolvedType}' will be used instead. Add @flowWeaver nodeType to use your version.`
+          );
+        }
+      }
+      continue;
+    }
+    const matchedFn = allFunctions.find((fn) => {
+      if (fn.getName() !== unresolvedType) return false;
+      return !hasFlowWeaverAnnotation(fn);
+    });
+    if (!matchedFn) continue;
+    inferredNodeTypes.push(
+      inferNodeTypeFromFunction(matchedFn, unresolvedType, sourceFile.getFilePath())
+    );
+    alreadyInferred.add(unresolvedType);
+  }
+  return inferredNodeTypes;
+}
+function hasFlowWeaverAnnotation(fn) {
+  const validTypes = /* @__PURE__ */ new Set(["nodeType", "node", "workflow"]);
+  return fn.getJsDocs().some(
+    (doc) => doc.getTags().some((t) => {
+      if (t.getTagName() !== "flowWeaver") return false;
+      const comment = t.getCommentText?.()?.trim() || "";
+      return validTypes.has(comment.split(/\s/)[0]);
+    })
+  );
+}
+
+// src/parser/module-resolution.ts
+import * as ts from "typescript";
+import * as path2 from "node:path";
+import * as fs from "node:fs";
+var SOURCE_EXTENSIONS = /* @__PURE__ */ new Set([".ts", ".tsx", ".js", ".jsx", ".mts", ".cts", ".mjs", ".cjs"]);
+function resolveModulePath(moduleSpecifier, currentDir, warnings) {
+  const extensions = [".ts", ".tsx", ".js", ".jsx"];
+  const hasExtension = extensions.some((ext) => moduleSpecifier.endsWith(ext));
+  if (hasExtension) {
+    const fullPath = path2.resolve(currentDir, moduleSpecifier);
+    if (fs.existsSync(fullPath)) return fullPath;
+    if (moduleSpecifier.endsWith(".js")) {
+      const tsPath = fullPath.replace(/\.js$/, ".ts");
+      if (fs.existsSync(tsPath)) return tsPath;
+      const tsxPath = fullPath.replace(/\.js$/, ".tsx");
+      if (fs.existsSync(tsxPath)) return tsxPath;
+    } else if (moduleSpecifier.endsWith(".jsx")) {
+      const tsxPath = fullPath.replace(/\.jsx$/, ".tsx");
+      if (fs.existsSync(tsxPath)) return tsxPath;
+    }
+    return null;
+  }
+  for (const ext of extensions) {
+    const fullPath = path2.resolve(currentDir, moduleSpecifier + ext);
+    if (fs.existsSync(fullPath)) {
+      return fullPath;
+    }
+  }
+  const dirPath = path2.resolve(currentDir, moduleSpecifier);
+  if (fs.existsSync(dirPath) && fs.statSync(dirPath).isDirectory()) {
+    const pkgPath = path2.join(dirPath, "package.json");
+    if (fs.existsSync(pkgPath)) {
+      try {
+        const pkg = JSON.parse(fs.readFileSync(pkgPath, "utf-8"));
+        if (pkg.main) {
+          const mainPath = path2.resolve(dirPath, pkg.main);
+          if (fs.existsSync(mainPath)) {
+            return mainPath;
+          }
+        }
+      } catch (e) {
+        warnings?.push(`Could not read ${pkgPath} while resolving "${moduleSpecifier}": ${getErrorMessage(e)}`);
+      }
+    }
+    for (const ext of extensions) {
+      const indexPath = path2.join(dirPath, `index${ext}`);
+      if (fs.existsSync(indexPath)) {
+        return indexPath;
+      }
+    }
+  }
+  return null;
+}
+function resolveReExportedDts(baseDir, spec) {
+  const noExt = spec.replace(/\.(js|mjs|cjs|jsx|ts|tsx)$/, "");
+  const candidates = [
+    path2.resolve(baseDir, `${noExt}.d.ts`),
+    path2.resolve(baseDir, noExt, "index.d.ts"),
+    path2.resolve(baseDir, spec)
+    // already a .d.ts path
+  ];
+  for (const c of candidates) {
+    if (c.endsWith(".d.ts") && fs.existsSync(c)) return c;
+  }
+  return null;
+}
+function preloadSourceOverrides(project, importer, source, importResolver, sourceLoader, seen) {
+  const parsed = ts.createSourceFile(importer, source, ts.ScriptTarget.Latest, true);
+  for (const statement of parsed.statements) {
+    if (!ts.isImportDeclaration(statement) || !ts.isStringLiteral(statement.moduleSpecifier)) {
+      continue;
+    }
+    const specifier = statement.moduleSpecifier.text;
+    if (!specifier.startsWith(".")) continue;
+    const resolved = importResolver?.(specifier, importer) ?? resolveModulePath(specifier, path2.dirname(importer));
+    if (resolved === void 0 || resolved === null || seen.has(resolved)) continue;
+    const override = sourceLoader(resolved);
+    if (override === void 0) continue;
+    seen.add(resolved);
+    preloadSourceOverrides(project, resolved, override, importResolver, sourceLoader, seen);
+    project.createSourceFile(resolved, override, { overwrite: true });
+  }
+}
+
+// src/parser/import-resolution.ts
+import * as path3 from "node:path";
+import * as fs2 from "node:fs";
+
+// src/parser/macro-expansion.ts
+function expandMapMacro(mapConfig, instances, connections, scopes, availableNodeTypes, macros, errors, _warnings) {
+  const { instanceId, childId, sourceNode, sourcePort } = mapConfig;
+  const scopeName = "iterate";
+  const childInstance = instances.find((inst) => inst.id === childId);
+  if (!childInstance) {
+    errors.push(
+      `@map "${instanceId}": child node "${childId}" not found. Declare it with @node before using @map.`
+    );
+    return;
+  }
+  const childNodeType = availableNodeTypes.find(
+    (nt) => nt.name === childInstance.nodeType || nt.functionName === childInstance.nodeType
+  );
+  if (!childNodeType) {
+    errors.push(
+      `@map "${instanceId}": node type "${childInstance.nodeType}" for child "${childId}" not found.`
+    );
+    return;
+  }
+  let inputPort = mapConfig.inputPort;
+  let outputPort = mapConfig.outputPort;
+  if (!inputPort) {
+    const dataInputs = Object.entries(childNodeType.inputs).filter(
+      ([name, def]) => name !== "execute" && def.dataType !== "STEP"
+    );
+    if (dataInputs.length === 0) {
+      errors.push(
+        `@map "${instanceId}": child node "${childId}" has no data input ports to receive items.`
+      );
+      return;
+    }
+    inputPort = dataInputs[0][0];
+  }
+  if (!outputPort) {
+    const dataOutputs = Object.entries(childNodeType.outputs).filter(
+      ([name, def]) => name !== "onSuccess" && name !== "onFailure" && def.dataType !== "STEP" && !def.isControlFlow && !def.failure
+    );
+    if (dataOutputs.length === 0) {
+      errors.push(
+        `@map "${instanceId}": child node "${childId}" has no data output ports for results.`
+      );
+      return;
+    }
+    outputPort = dataOutputs[0][0];
+  }
+  const childInputDef = childNodeType.inputs[inputPort];
+  const childOutputDef = childNodeType.outputs[outputPort];
+  const syntheticTypeName = `__map_${instanceId}__`;
+  const syntheticNodeType = {
+    type: "NodeType",
+    name: syntheticTypeName,
+    functionName: syntheticTypeName,
+    variant: "MAP_ITERATOR",
+    isAsync: true,
+    executeWhen: "CONJUNCTION",
+    hasSuccessPort: true,
+    hasFailurePort: true,
+    scope: scopeName,
+    scopes: [scopeName],
+    inputs: {
+      execute: { dataType: "STEP", label: "Execute" },
+      items: {
+        dataType: "ARRAY",
+        label: "Items",
+        tsType: childInputDef?.tsType ? `(${childInputDef.tsType})[]` : "unknown[]"
+      },
+      // Scoped INPUT ports (receive from children)
+      success: { dataType: "STEP", scope: scopeName },
+      failure: { dataType: "STEP", scope: scopeName },
+      processed: {
+        dataType: childOutputDef?.dataType || "ANY",
+        scope: scopeName,
+        ...childOutputDef?.tsType && { tsType: childOutputDef.tsType }
+      }
+    },
+    outputs: {
+      onSuccess: { dataType: "STEP", label: "On Success", isControlFlow: true },
+      onFailure: { dataType: "STEP", label: "On Failure", isControlFlow: true, failure: true },
+      results: {
+        dataType: "ARRAY",
+        label: "Results",
+        tsType: childOutputDef?.tsType ? `(${childOutputDef.tsType})[]` : "unknown[]"
+      },
+      // Scoped OUTPUT ports (send to children)
+      start: { dataType: "STEP", scope: scopeName },
+      item: {
+        dataType: childInputDef?.dataType || "ANY",
+        scope: scopeName,
+        ...childInputDef?.tsType && { tsType: childInputDef.tsType }
+      }
+    }
+  };
+  availableNodeTypes.push(syntheticNodeType);
+  const mapInstance = {
+    type: "NodeInstance",
+    id: instanceId,
+    nodeType: syntheticTypeName
+  };
+  instances.push(mapInstance);
+  childInstance.parent = { id: instanceId, scope: scopeName };
+  connections.push({
+    type: "Connection",
+    from: { node: instanceId, port: "start", scope: scopeName },
+    to: { node: childId, port: "execute", scope: scopeName }
+  });
+  connections.push({
+    type: "Connection",
+    from: { node: instanceId, port: "item", scope: scopeName },
+    to: { node: childId, port: inputPort, scope: scopeName }
+  });
+  connections.push({
+    type: "Connection",
+    from: { node: childId, port: outputPort, scope: scopeName },
+    to: { node: instanceId, port: "processed", scope: scopeName }
+  });
+  connections.push({
+    type: "Connection",
+    from: { node: childId, port: "onSuccess", scope: scopeName },
+    to: { node: instanceId, port: "success", scope: scopeName }
+  });
+  connections.push({
+    type: "Connection",
+    from: { node: childId, port: "onFailure", scope: scopeName },
+    to: { node: instanceId, port: "failure", scope: scopeName }
+  });
+  connections.push({
+    type: "Connection",
+    from: { node: sourceNode, port: sourcePort },
+    to: { node: instanceId, port: "items" }
+  });
+  scopes[`${instanceId}.${scopeName}`] = [childId];
+  macros.push({
+    type: "map",
+    instanceId,
+    childId,
+    sourcePort: `${sourceNode}.${sourcePort}`,
+    ...mapConfig.inputPort && { inputPort: mapConfig.inputPort },
+    ...mapConfig.outputPort && { outputPort: mapConfig.outputPort }
+  });
+}
+function expandPathMacros(pathConfigs, instances, connections, availableNodeTypes, startPorts, exitPorts, macros, errors, _warnings) {
+  const findNodeType = (nodeTypeName) => availableNodeTypes.find(
+    (nt) => nt.name === nodeTypeName || nt.functionName === nodeTypeName
+  );
+  const getNodeType = (nodeId) => {
+    const instance = instances.find((inst) => inst.id === nodeId);
+    if (!instance) return void 0;
+    return findNodeType(instance.nodeType);
+  };
+  const getOutputPorts = (nodeId) => {
+    if (nodeId === "Start") return startPorts;
+    if (nodeId === "Exit") return exitPorts;
+    const nodeType = getNodeType(nodeId);
+    return nodeType?.outputs || {};
+  };
+  const getInputPorts = (nodeId) => {
+    if (nodeId === "Exit") return exitPorts;
+    if (nodeId === "Start") return startPorts;
+    const nodeType = getNodeType(nodeId);
+    return nodeType?.inputs || {};
+  };
+  const existingKeys = /* @__PURE__ */ new Set();
+  for (const conn of connections) {
+    existingKeys.add(`${conn.from.node}.${conn.from.port}->${conn.to.node}.${conn.to.port}`);
+  }
+  const addConnection = (fromNode, fromPort, toNode, toPort) => {
+    const key = `${fromNode}.${fromPort}->${toNode}.${toPort}`;
+    if (existingKeys.has(key)) return;
+    existingKeys.add(key);
+    connections.push({
+      type: "Connection",
+      from: { node: fromNode, port: fromPort },
+      to: { node: toNode, port: toPort }
+    });
+  };
+  for (const pathConfig of pathConfigs) {
+    const { steps } = pathConfig;
+    if (steps.length < 2) {
+      errors.push(`@path requires at least 2 steps, got ${steps.length}.`);
+      continue;
+    }
+    let valid = true;
+    for (const step of steps) {
+      if (step.node === "Start" || step.node === "Exit") continue;
+      const instance = instances.find((inst) => inst.id === step.node);
+      if (!instance) {
+        errors.push(
+          `@path: node "${step.node}" not found. Declare it with @node before using @path.`
+        );
+        valid = false;
+      }
+    }
+    if (!valid) continue;
+    for (let i = 0; i < steps.length - 1; i++) {
+      const current = steps[i];
+      const next = steps[i + 1];
+      const currentId = current.node;
+      const nextId = next.node;
+      const route = current.route || "ok";
+      if (currentId === "Start") {
+        addConnection("Start", "execute", nextId, nextId === "Exit" ? "onSuccess" : "execute");
+      } else if (nextId === "Exit") {
+        if (route === "fail") {
+          addConnection(currentId, "onFailure", "Exit", "onFailure");
+        } else {
+          addConnection(currentId, "onSuccess", "Exit", "onSuccess");
+        }
+      } else {
+        if (route === "fail") {
+          addConnection(currentId, "onFailure", nextId, "execute");
+        } else {
+          addConnection(currentId, "onSuccess", nextId, "execute");
+        }
+      }
+      for (const edge of impliedPathDataEdgesInto(steps, i + 1, { inputs: getInputPorts, outputs: getOutputPorts })) {
+        const alreadyConnected = connections.some(
+          (c) => c.to.node === edge.to.node && c.to.port === edge.to.port
+        );
+        if (alreadyConnected) continue;
+        addConnection(edge.from.node, edge.from.port, edge.to.node, edge.to.port);
+      }
+    }
+    macros.push({
+      type: "path",
+      steps: steps.map((s) => s.route ? { node: s.node, route: s.route } : { node: s.node })
+    });
+  }
+}
+function expandFanOutMacros(fanOutConfigs, instances, connections, startPorts, exitPorts, macros, errors) {
+  const instanceIds = new Set(instances.map((i) => i.id));
+  instanceIds.add("Start");
+  instanceIds.add("Exit");
+  for (const config of fanOutConfigs) {
+    const { source, targets } = config;
+    if (!instanceIds.has(source.node)) {
+      errors.push(`@fanOut: source node "${source.node}" does not exist`);
+      continue;
+    }
+    let valid = true;
+    for (const target of targets) {
+      if (!instanceIds.has(target.node)) {
+        errors.push(`@fanOut: target node "${target.node}" does not exist`);
+        valid = false;
+      }
+    }
+    if (!valid) continue;
+    for (const target of targets) {
+      const targetPort = target.port ?? source.port;
+      const conn = {
+        type: "Connection",
+        from: { node: source.node, port: source.port },
+        to: { node: target.node, port: targetPort }
+      };
+      const exists = connections.some(
+        (c) => c.from.node === conn.from.node && c.from.port === conn.from.port && c.to.node === conn.to.node && c.to.port === conn.to.port
+      );
+      if (!exists) {
+        connections.push(conn);
+      }
+    }
+    macros.push({
+      type: "fanOut",
+      source: { node: source.node, port: source.port },
+      targets: targets.map((t) => t.port ? { node: t.node, port: t.port } : { node: t.node })
+    });
+  }
+}
+function expandFanInMacros(fanInConfigs, instances, connections, startPorts, exitPorts, macros, errors) {
+  const instanceIds = new Set(instances.map((i) => i.id));
+  instanceIds.add("Start");
+  instanceIds.add("Exit");
+  for (const config of fanInConfigs) {
+    const { sources, target } = config;
+    if (!instanceIds.has(target.node)) {
+      errors.push(`@fanIn: target node "${target.node}" does not exist`);
+      continue;
+    }
+    let valid = true;
+    for (const source of sources) {
+      if (!instanceIds.has(source.node)) {
+        errors.push(`@fanIn: source node "${source.node}" does not exist`);
+        valid = false;
+      }
+    }
+    if (!valid) continue;
+    for (const source of sources) {
+      const sourcePort = source.port ?? target.port;
+      const conn = {
+        type: "Connection",
+        from: { node: source.node, port: sourcePort },
+        to: { node: target.node, port: target.port }
+      };
+      const exists = connections.some(
+        (c) => c.from.node === conn.from.node && c.from.port === conn.from.port && c.to.node === conn.to.node && c.to.port === conn.to.port
+      );
+      if (!exists) {
+        connections.push(conn);
+      }
+    }
+    macros.push({
+      type: "fanIn",
+      sources: sources.map((s) => s.port ? { node: s.node, port: s.port } : { node: s.node }),
+      target: { node: target.node, port: target.port }
+    });
+  }
+}
+function expandCoerceMacros(coerceConfigs, instances, connections, startPorts, exitPorts, macros, errors) {
+  const instanceIds = new Set(instances.map((i) => i.id));
+  instanceIds.add("Start");
+  instanceIds.add("Exit");
+  for (const config of coerceConfigs) {
+    const { instanceId, source, target, targetType } = config;
+    if (!instanceIds.has(source.node)) {
+      errors.push(`@coerce: source node "${source.node}" does not exist`);
+      continue;
+    }
+    if (!instanceIds.has(target.node)) {
+      errors.push(`@coerce: target node "${target.node}" does not exist`);
+      continue;
+    }
+    if (instanceIds.has(instanceId)) {
+      errors.push(`@coerce: instance ID "${instanceId}" already exists`);
+      continue;
+    }
+    const nodeTypeName = COERCE_TYPE_MAP[targetType];
+    if (!nodeTypeName) {
+      errors.push(`@coerce: unknown target type "${targetType}"`);
+      continue;
+    }
+    instances.push({
+      type: "NodeInstance",
+      id: instanceId,
+      nodeType: nodeTypeName
+    });
+    instanceIds.add(instanceId);
+    connections.push({
+      type: "Connection",
+      from: { node: source.node, port: source.port },
+      to: { node: instanceId, port: "value" }
+    });
+    connections.push({
+      type: "Connection",
+      from: { node: instanceId, port: "result" },
+      to: { node: target.node, port: target.port }
+    });
+    macros.push({
+      type: "coerce",
+      instanceId,
+      source: { node: source.node, port: source.port },
+      target: { node: target.node, port: target.port },
+      targetType
+    });
+  }
+}
+function generateAutoConnections(instances, availableNodeTypes, startPorts, exitPorts) {
+  const connections = [];
+  const findNodeType = (nodeTypeName) => availableNodeTypes.find(
+    (nt) => nt.name === nodeTypeName || nt.functionName === nodeTypeName
+  );
+  if (instances.length > 0) {
+    const firstInstance = instances[0];
+    const firstNodeType = findNodeType(firstInstance.nodeType);
+    connections.push({
+      type: "Connection",
+      from: { node: "Start", port: "execute" },
+      to: { node: firstInstance.id, port: "execute" }
+    });
+    if (firstNodeType) {
+      for (const [portName, portDef] of Object.entries(startPorts)) {
+        if (portDef.dataType === "STEP") continue;
+        if (portName in firstNodeType.inputs && !isControlFlowPort(portName)) {
+          connections.push({
+            type: "Connection",
+            from: { node: "Start", port: portName },
+            to: { node: firstInstance.id, port: portName }
+          });
+        }
+      }
+    }
+  }
+  for (let i = 0; i < instances.length - 1; i++) {
+    const current = instances[i];
+    const next = instances[i + 1];
+    const currentNodeType = findNodeType(current.nodeType);
+    const nextNodeType = findNodeType(next.nodeType);
+    connections.push({
+      type: "Connection",
+      from: { node: current.id, port: "onSuccess" },
+      to: { node: next.id, port: "execute" }
+    });
+    if (currentNodeType && nextNodeType) {
+      for (const [outputName, outputDef] of Object.entries(currentNodeType.outputs)) {
+        if (outputDef.dataType === "STEP" || isControlFlowPort(outputName)) continue;
+        if (outputName in nextNodeType.inputs && !isControlFlowPort(outputName)) {
+          connections.push({
+            type: "Connection",
+            from: { node: current.id, port: outputName },
+            to: { node: next.id, port: outputName }
+          });
+        }
+      }
+    }
+  }
+  if (instances.length > 0) {
+    const lastInstance = instances[instances.length - 1];
+    const lastNodeType = findNodeType(lastInstance.nodeType);
+    connections.push({
+      type: "Connection",
+      from: { node: lastInstance.id, port: "onSuccess" },
+      to: { node: "Exit", port: "onSuccess" }
+    });
+    if (lastNodeType) {
+      for (const [portName, portDef] of Object.entries(exitPorts)) {
+        if (portDef.dataType === "STEP" || portDef.isControlFlow) continue;
+        if (lastNodeType.outputs[portName] && !isControlFlowPort(portName)) {
+          connections.push({
+            type: "Connection",
+            from: { node: lastInstance.id, port: portName },
+            to: { node: "Exit", port: portName }
+          });
+        }
+      }
+    }
+  }
+  return connections;
+}
+
+// src/parser/import-stub.ts
+function createImportStub(imp) {
+  return {
+    type: "NodeType",
+    name: imp.name,
+    functionName: imp.functionName,
+    importSource: imp.importSource,
+    variant: "FUNCTION",
+    inputs: {},
+    outputs: { result: { dataType: "ANY" } },
+    hasSuccessPort: true,
+    hasFailurePort: true,
+    executeWhen: "CONJUNCTION",
+    isAsync: false,
+    // Mark as expression since most npm functions are pure
+    // This is a reasonable default for stubs
+    expression: true
+  };
+}
+function isImportStub(nt) {
+  if (!nt.importSource) return false;
+  const inputKeys = Object.keys(nt.inputs ?? {});
+  const outputKeys = Object.keys(nt.outputs ?? {});
+  return inputKeys.length === 0 && outputKeys.length === 1 && outputKeys[0] === "result";
+}
+
+// src/parser/workflow-extraction.ts
+var RESERVED_OPTION_KEYS = /* @__PURE__ */ new Set([
+  "strictTypes",
+  "autoConnect",
+  "trigger",
+  "http",
+  "cancelOn",
+  "retries",
+  "timeout",
+  "throttle",
+  "deploy"
+]);
+function promoteDeployNamespaces(deploy) {
+  if (!deploy) return {};
+  const promoted = {};
+  for (const [namespace, data] of Object.entries(deploy)) {
+    if (RESERVED_OPTION_KEYS.has(namespace)) continue;
+    if (data && typeof data === "object") promoted[namespace] = data;
+  }
+  return promoted;
+}
+function extractWorkflowSignatures(sourceFile, filePath, warnings, tagRegistry) {
+  const workflows = [];
+  extractFunctionLikes(sourceFile).forEach((fn) => {
+    const config = jsdocParser.parseWorkflow(fn, warnings, tagRegistry);
+    if (!config) return;
+    const functionName = fn.getName() || "anonymous";
+    const startPorts = parseStartPorts(fn, config);
+    const exitPorts = parseExitPorts(fn, config, warnings);
+    const userSpecifiedAsync = fn.isAsync();
+    workflows.push({
+      type: "Workflow",
+      sourceFile: filePath,
+      name: config.name || functionName,
+      functionName,
+      nodeTypes: [],
+      instances: [],
+      connections: [],
+      startPorts,
+      exitPorts,
+      imports: [],
+      description: config.description,
+      userSpecifiedAsync
+    });
+  });
+  return workflows;
+}
+function workflowToNodeType(workflow) {
+  return {
+    type: "NodeType",
+    name: workflow.name,
+    functionName: workflow.functionName,
+    variant: "IMPORTED_WORKFLOW",
+    path: workflow.sourceFile,
+    inputs: { ...workflow.startPorts },
+    outputs: { ...workflow.exitPorts },
+    hasSuccessPort: "onSuccess" in workflow.exitPorts,
+    hasFailurePort: "onFailure" in workflow.exitPorts,
+    isAsync: workflow.userSpecifiedAsync || false,
+    executeWhen: EXECUTION_STRATEGIES.CONJUNCTION,
+    description: workflow.description,
+    sourceLocation: {
+      file: workflow.sourceFile,
+      line: 0,
+      column: 0
+    }
+  };
+}
+function extractWorkflows(sourceFile, availableNodeTypes, filePath, errors, warnings, tagRegistry, resolveImport) {
+  const workflows = [];
+  const allFunctions = extractFunctionLikes(sourceFile);
+  const allFunctionNames = allFunctions.map((fn) => fn.getName()).filter((name) => !!name);
+  allFunctions.forEach((fn) => {
+    const config = jsdocParser.parseWorkflow(fn, warnings, tagRegistry);
+    if (!config) {
+      const jsdocText = fn.getJsDocs().map((d) => d.getFullText()).join("");
+      if (jsdocText.includes("@flowWeaver workflow")) {
+        warnings.push(
+          `Function "${fn.getName() || "anonymous"}" has @flowWeaver annotation but could not be parsed. Check for special characters (---) or malformed JSDoc syntax.`
+        );
+      }
+      return;
+    }
+    const functionName = fn.getName() || "anonymous";
+    if (config.connections) {
+      for (const conn of config.connections) {
+        if (conn.from.node === "IN" || conn.from.node === "OUT") {
+          errors.push(
+            `Workflow "${functionName}" uses "${conn.from.node}", which is not a node. Use "Start" or "Exit" instead.`
+          );
+        }
+        if (conn.to.node === "IN" || conn.to.node === "OUT") {
+          errors.push(
+            `Workflow "${functionName}" uses "${conn.to.node}", which is not a node. Use "Start" or "Exit" instead.`
+          );
+        }
+      }
+    }
+    const userSpecifiedAsync = fn.isAsync();
+    const startPorts = parseStartPorts(fn, config);
+    const exitPorts = parseExitPorts(fn, config, warnings);
+    const importedNpmNodeTypes = (config.imports || []).map(
+      (imp) => resolveImport(imp, filePath, warnings)
+    );
+    for (const nt of importedNpmNodeTypes) {
+      const dataInputs = Object.keys(nt.inputs).filter((p) => p !== "execute");
+      const nonControlOutputs = Object.keys(nt.outputs).filter(
+        (p) => p !== "onSuccess" && p !== "onFailure"
+      );
+      const isStubOnly = nonControlOutputs.length === 1 && nonControlOutputs[0] === "result" && nt.outputs.result?.dataType === "ANY";
+      if (dataInputs.length === 0 && isStubOnly) {
+        warnings.push(
+          `Could not infer ports for "${nt.functionName}" from "${nt.importSource}". Wrap it in a local function with @flowWeaver nodeType annotations instead.`
+        );
+      }
+    }
+    const allAvailableNodeTypes = [...availableNodeTypes, ...importedNpmNodeTypes];
+    const instances = (config.instances || []).map((inst) => {
+      let parent;
+      if (inst.parentScope) {
+        const dotIndex = inst.parentScope.indexOf(".");
+        if (dotIndex > 0) {
+          parent = {
+            id: inst.parentScope.substring(0, dotIndex),
+            scope: inst.parentScope.substring(dotIndex + 1)
+          };
+        }
+      }
+      const portConfigs = inst.portConfigs;
+      return {
+        type: "NodeInstance",
+        id: inst.id,
+        nodeType: inst.type,
+        ...parent && { parent },
+        config: {
+          ...inst.label && { label: inst.label },
+          ...portConfigs && portConfigs.length > 0 && { portConfigs },
+          ...inst.pullExecution && { pullExecution: inst.pullExecution },
+          ...inst.minimized && { minimized: inst.minimized },
+          ...inst.color && { color: inst.color },
+          ...inst.icon && { icon: inst.icon },
+          ...inst.tags && inst.tags.length > 0 && { tags: inst.tags },
+          ...inst.width && { width: inst.width },
+          ...inst.height && { height: inst.height },
+          ...inst.suppressWarnings?.length && { suppressWarnings: inst.suppressWarnings }
+        },
+        ...inst.sourceLocation && {
+          sourceLocation: { file: filePath, ...inst.sourceLocation }
+        },
+        ...inst.attributes && { attributes: inst.attributes }
+      };
+    });
+    const connections = (config.connections || []).map((conn) => ({
+      type: "Connection",
+      from: conn.from,
+      to: conn.to,
+      ...conn.sourceLocation && { sourceLocation: { file: filePath, ...conn.sourceLocation } },
+      ...conn.coerce && { coerce: conn.coerce }
+    }));
+    if (config.autoConnect && connections.length === 0 && instances.length > 0) {
+      const autoConnections = generateAutoConnections(
+        instances,
+        allAvailableNodeTypes,
+        startPorts,
+        exitPorts
+      );
+      connections.push(...autoConnections);
+    }
+    const scopes = config.scopes || {};
+    const macros = [];
+    if (config.maps && config.maps.length > 0) {
+      for (const mapConfig of config.maps) {
+        expandMapMacro(
+          mapConfig,
+          instances,
+          connections,
+          scopes,
+          allAvailableNodeTypes,
+          macros,
+          errors,
+          warnings
+        );
+      }
+    }
+    if (config.paths && config.paths.length > 0) {
+      expandPathMacros(
+        config.paths,
+        instances,
+        connections,
+        allAvailableNodeTypes,
+        startPorts,
+        exitPorts,
+        macros,
+        errors,
+        warnings
+      );
+    }
+    if (config.fanOuts && config.fanOuts.length > 0) {
+      expandFanOutMacros(config.fanOuts, instances, connections, startPorts, exitPorts, macros, errors);
+    }
+    if (config.fanIns && config.fanIns.length > 0) {
+      expandFanInMacros(config.fanIns, instances, connections, startPorts, exitPorts, macros, errors);
+    }
+    if (config.coercions && config.coercions.length > 0) {
+      expandCoerceMacros(config.coercions, instances, connections, startPorts, exitPorts, macros, errors);
+    }
+    if (instances.some((inst) => inst.config?.portConfigs?.some((pc) => pc.expression !== void 0))) {
+      expandExpressionReferences({
+        instances,
+        connections,
+        findNodeType: (name) => allAvailableNodeTypes.find((nt) => nt.name === name || nt.functionName === name),
+        startPorts,
+        moduleBindings: collectModuleBindings(
+          sourceFile,
+          new Set(allAvailableNodeTypes.map((nt) => nt.functionName))
+        ),
+        errors
+      });
+    }
+    const realNameToType = /* @__PURE__ */ new Map();
+    for (const nt of allAvailableNodeTypes) {
+      if (!isImportStub(nt) && !importedNpmNodeTypes.includes(nt)) {
+        realNameToType.set(nt.name, nt);
+      }
+    }
+    const resolvedImportedTypes = importedNpmNodeTypes.map((imp) => {
+      if (isImportStub(imp)) {
+        const real = realNameToType.get(imp.name);
+        if (real) {
+          const merged = { ...real };
+          const impSource = imp.importSource;
+          if (impSource) merged.importSource = impSource;
+          return merged;
+        }
+      }
+      return imp;
+    });
+    const importedNames = new Set(resolvedImportedTypes.map((nt) => nt.name));
+    const dedupedAvailableTypes = allAvailableNodeTypes.filter((nt) => !importedNames.has(nt.name));
+    const workflowNodeTypes = [...dedupedAvailableTypes, ...resolvedImportedTypes];
+    for (const inst of instances) {
+      if (inst.nodeType.startsWith("__fw_") && COERCION_NODE_TYPES[inst.nodeType]) {
+        if (!workflowNodeTypes.some((nt) => nt.functionName === inst.nodeType)) {
+          workflowNodeTypes.push(COERCION_NODE_TYPES[inst.nodeType]);
+        }
+      }
+    }
+    workflows.push({
+      type: "Workflow",
+      sourceFile: filePath,
+      name: config.name || functionName,
+      functionName,
+      nodeTypes: workflowNodeTypes,
+      instances,
+      connections,
+      scopes,
+      startPorts,
+      exitPorts,
+      imports: [],
+      description: config.description,
+      userSpecifiedAsync,
+      availableFunctionNames: allFunctionNames,
+      ...macros.length > 0 && { macros },
+      ...(config.strictTypes !== void 0 || config.autoConnect || config.trigger || config.http || config.cancelOn || config.retries !== void 0 || config.timeout || config.throttle || config.deploy) && {
+        options: {
+          ...config.strictTypes !== void 0 && { strictTypes: config.strictTypes },
+          ...config.autoConnect && { autoConnect: true },
+          ...config.trigger && { trigger: config.trigger },
+          ...config.http && config.http.length > 0 && { http: config.http },
+          ...config.cancelOn && { cancelOn: config.cancelOn },
+          ...config.retries !== void 0 && { retries: config.retries },
+          ...config.timeout && { timeout: config.timeout },
+          ...config.throttle && { throttle: config.throttle },
+          // Surface each pack deploy namespace as a top-level options.<namespace>
+          // convenience mirror (e.g. options.<pack> from deploy['<pack>']). Packs
+          // type these fields via module augmentation of TWorkflowOptions; core
+          // stays namespace-agnostic and keeps no vendor vocabulary.
+          ...promoteDeployNamespaces(config.deploy),
+          // Per-target deployment config
+          ...config.deploy && { deploy: config.deploy }
+        }
+      }
+    });
+  });
+  return workflows;
+}
+
+// src/parser/import-resolution.ts
+function dependenciesUnchanged(deps) {
+  for (const dep of deps) {
+    try {
+      if (fs2.statSync(dep.path).mtimeMs !== dep.mtime) return false;
+    } catch {
+      return false;
+    }
+  }
+  return true;
+}
+function recordDependency(ctx, filePath, mtime) {
+  for (const recorder of ctx.dependencyRecorders) {
+    recorder.set(filePath, mtime);
+  }
+}
+function extractImportedNodeTypes(ctx, sourceFile, currentFilePath, importResolver, sourceLoader, warnings) {
+  const importedNodeTypes = [];
+  const imports = sourceFile.getImportDeclarations();
+  for (const importDecl of imports) {
+    const moduleSpecifier = importDecl.getModuleSpecifierValue();
+    if (!moduleSpecifier) {
+      continue;
+    }
+    if (!moduleSpecifier.startsWith(".")) {
+      const packageNodeTypes = resolveNpmPackageTypes(
+        ctx,
+        importDecl,
+        moduleSpecifier,
+        currentFilePath
+      );
+      importedNodeTypes.push(...packageNodeTypes);
+      continue;
+    }
+    const currentDir = path3.dirname(currentFilePath);
+    const importedFilePath = importResolver?.(moduleSpecifier, currentFilePath) ?? resolveModulePath(moduleSpecifier, currentDir, warnings);
+    if (!importedFilePath) {
+      const ext = path3.extname(moduleSpecifier);
+      if (ext && !SOURCE_EXTENSIONS.has(ext)) {
+        continue;
+      }
+      throw new Error(
+        `Import error: File not found for "${moduleSpecifier}"
+  Imported from: ${currentFilePath}
+  Searched extensions: .ts, .tsx, .js, .jsx`
+      );
+    }
+    if (ctx.importStack.has(importedFilePath)) {
+      const cycle = Array.from(ctx.importStack).concat(importedFilePath);
+      throw new Error(`Circular dependency detected:
+  ${cycle.join("\n  -> ")}`);
+    }
+    try {
+      let nodeTypes;
+      const overriddenSource = sourceLoader?.(importedFilePath);
+      const importStats = overriddenSource === void 0 ? fs2.statSync(importedFilePath) : { mtimeMs: 0 };
+      if (overriddenSource === void 0) {
+        recordDependency(ctx, importedFilePath, importStats.mtimeMs);
+      }
+      const cached = overriddenSource === void 0 ? ctx.importCache.get(importedFilePath) : void 0;
+      if (cached && cached.mtime === importStats.mtimeMs && dependenciesUnchanged(cached.deps)) {
+        nodeTypes = cached.nodeTypes;
+        for (const dep of cached.deps) recordDependency(ctx, dep.path, dep.mtime);
+      } else {
+        ctx.importStack.add(importedFilePath);
+        const importDeps = /* @__PURE__ */ new Map();
+        ctx.dependencyRecorders.push(importDeps);
+        try {
+          const importedRaw = overriddenSource ?? fs2.readFileSync(importedFilePath, "utf-8");
+          const importedContent = hasInPlaceMarkers(importedRaw) ? stripGeneratedSections(importedRaw) : importedRaw;
+          const importedFile = ctx.project.createSourceFile(importedFilePath, importedContent, {
+            overwrite: true
+          });
+          const importWarnings = [];
+          const localNodeTypes = extractNodeTypes(importedFile, importWarnings, ctx.tagRegistry);
+          const importedFromFile = extractImportedNodeTypes(
+            ctx,
+            importedFile,
+            importedFilePath,
+            importResolver,
+            sourceLoader,
+            warnings
+          );
+          const workflows = extractWorkflows(
+            importedFile,
+            [...localNodeTypes, ...importedFromFile],
+            importedFilePath,
+            [],
+            importWarnings,
+            ctx.tagRegistry,
+            (imp, filePath, importAnnotationWarnings) => resolveImportAnnotation(ctx, imp, filePath, importAnnotationWarnings)
+          );
+          const workflowAsNodeTypes = workflows.map((wf) => workflowToNodeType(wf));
+          nodeTypes = [...localNodeTypes, ...importedFromFile, ...workflowAsNodeTypes];
+          const inferredFromImport = inferAllUnannotatedFunctions(importedFile, nodeTypes);
+          nodeTypes.push(...inferredFromImport);
+          if (overriddenSource === void 0) {
+            ctx.project.removeSourceFile(importedFile);
+          }
+          ctx.importCache.set(importedFilePath, {
+            mtime: importStats.mtimeMs,
+            nodeTypes,
+            deps: [...importDeps].map(([path4, mtime]) => ({ path: path4, mtime }))
+          });
+        } finally {
+          ctx.importStack.delete(importedFilePath);
+          ctx.dependencyRecorders.pop();
+        }
+      }
+      const importedNames = /* @__PURE__ */ new Set();
+      importDecl.getNamedImports().forEach((namedImport) => {
+        importedNames.add(namedImport.getName());
+      });
+      nodeTypes.forEach((nodeType) => {
+        if (importedNames.has(nodeType.functionName)) {
+          importedNodeTypes.push({
+            ...nodeType,
+            sourceLocation: {
+              file: importedFilePath,
+              line: nodeType.sourceLocation?.line || 0,
+              column: nodeType.sourceLocation?.column || 0
+            }
+          });
+        }
+      });
+    } catch (error) {
+      if (error instanceof Error) {
+        throw new Error(`Failed to process import from ${importedFilePath}:
+  ${error.message}`, { cause: error });
+      }
+      throw error;
+    }
+  }
+  return importedNodeTypes;
+}
+function resolveNpmPackageTypes(ctx, importDecl, moduleSpecifier, currentFilePath) {
+  const namedImports = importDecl.getNamedImports();
+  if (namedImports.length === 0) return [];
+  const importedNames = /* @__PURE__ */ new Set();
+  namedImports.forEach((ni) => importedNames.add(ni.getName()));
+  const cacheKey = `npm:${moduleSpecifier}`;
+  const npmCached = ctx.importCache.get(cacheKey);
+  if (npmCached) {
+    const currentDir2 = path3.dirname(currentFilePath);
+    const resolvedDts = resolvePackageTypesPath(moduleSpecifier, currentDir2);
+    if (resolvedDts) {
+      try {
+        const dtsStats = fs2.statSync(resolvedDts);
+        if (npmCached.mtime === dtsStats.mtimeMs) {
+          recordDependency(ctx, resolvedDts, dtsStats.mtimeMs);
+          return npmCached.nodeTypes.filter((nt) => importedNames.has(nt.functionName));
+        }
+      } catch {
+      }
+    } else {
+      return npmCached.nodeTypes.filter((nt) => importedNames.has(nt.functionName));
+    }
+  }
+  const currentDir = path3.dirname(currentFilePath);
+  const dtsPath = resolvePackageTypesPath(moduleSpecifier, currentDir);
+  if (!dtsPath) return [];
+  try {
+    const dtsContent = fs2.readFileSync(dtsPath, "utf-8");
+    recordDependency(ctx, dtsPath, fs2.statSync(dtsPath).mtimeMs);
+    const dtsFile = ctx.project.createSourceFile(
+      `__npm_dts__/${moduleSpecifier}.d.ts`,
+      dtsContent,
+      { overwrite: true }
+    );
+    const fns = extractFunctionLikes(dtsFile);
+    const allNodeTypes = [];
+    const seenNames = /* @__PURE__ */ new Set();
+    for (const fn of fns) {
+      const fnName = fn.getName();
+      if (!fnName) continue;
+      if (seenNames.has(fnName)) continue;
+      seenNames.add(fnName);
+      const nodeType = inferNodeTypeFromFunction(fn, fnName, dtsPath);
+      nodeType.importSource = moduleSpecifier;
+      nodeType.functionText = void 0;
+      allNodeTypes.push(nodeType);
+    }
+    ctx.project.removeSourceFile(dtsFile);
+    const dtsMtime = fs2.statSync(dtsPath).mtimeMs;
+    ctx.importCache.set(cacheKey, { mtime: dtsMtime, nodeTypes: allNodeTypes, deps: [] });
+    return allNodeTypes.filter((nt) => importedNames.has(nt.functionName));
+  } catch {
+    return [];
+  }
+}
+function resolveImportAnnotation(ctx, imp, currentFilePath, warnings) {
+  const currentDir = path3.dirname(currentFilePath);
+  if (imp.importSource.startsWith(".")) {
+    return resolveLocalImportAnnotation(ctx, imp, currentDir, warnings);
+  } else {
+    return resolveNpmImportAnnotation(ctx, imp, currentDir, warnings);
+  }
+}
+function resolveLocalImportAnnotation(ctx, imp, currentDir, warnings) {
+  const importedFilePath = resolveModulePath(imp.importSource, currentDir, warnings);
+  if (!importedFilePath) {
+    warnings.push(`@fwImport: Could not resolve "${imp.importSource}" from ${currentDir}`);
+    return createImportStub(imp);
+  }
+  if (ctx.importStack.has(importedFilePath)) {
+    const cycle = Array.from(ctx.importStack).concat(importedFilePath);
+    warnings.push(`@fwImport: Circular dependency detected:
+  ${cycle.join("\n  -> ")}`);
+    return createImportStub(imp);
+  }
+  ctx.importStack.add(importedFilePath);
+  try {
+    const importedContent = fs2.readFileSync(importedFilePath, "utf-8");
+    recordDependency(ctx, importedFilePath, fs2.statSync(importedFilePath).mtimeMs);
+    const importedFile = ctx.project.createSourceFile(importedFilePath, importedContent, {
+      overwrite: true
+    });
+    const fns = extractFunctionLikes(importedFile);
+    const fn = fns.find((f) => f.getName() === imp.functionName);
+    if (!fn) {
+      ctx.project.removeSourceFile(importedFile);
+      return createImportStub(imp);
+    }
+    const nodeType = inferNodeTypeFromFunction(fn, imp.name, importedFilePath);
+    nodeType.importSource = imp.importSource;
+    nodeType.functionText = void 0;
+    ctx.project.removeSourceFile(importedFile);
+    return nodeType;
+  } catch {
+    return createImportStub(imp);
+  } finally {
+    ctx.importStack.delete(importedFilePath);
+  }
+}
+function resolveNpmImportAnnotation(ctx, imp, currentDir, warnings) {
+  const cacheKey = `npm:${imp.importSource}`;
+  if (ctx.importCache.has(cacheKey)) {
+    const cached = ctx.importCache.get(cacheKey);
+    const resolvedDts = resolvePackageTypesPath(imp.importSource, currentDir);
+    let cacheValid = false;
+    if (resolvedDts) {
+      try {
+        const dtsStats = fs2.statSync(resolvedDts);
+        cacheValid = cached.mtime === dtsStats.mtimeMs;
+      } catch {
+      }
+    } else {
+      cacheValid = true;
+    }
+    if (cacheValid) {
+      const found = cached.nodeTypes.find((nt) => nt.functionName === imp.functionName);
+      if (found) {
+        return { ...found, name: imp.name, importSource: imp.importSource };
+      }
+    }
+  }
+  const dtsPath = resolvePackageTypesPath(imp.importSource, currentDir);
+  if (!dtsPath) {
+    warnings.push(
+      `@fwImport: Package "${imp.importSource}" has no type declarations (.d.ts). Install @types/${imp.importSource} or add a local wrapper with @flowWeaver nodeType annotations.`
+    );
+    return createImportStub(imp);
+  }
+  try {
+    const allNodeTypes = inferNodeTypesDeep(
+      ctx.project,
+      dtsPath,
+      imp.importSource,
+      /* @__PURE__ */ new Set(),
+      /* @__PURE__ */ new Set(),
+      0
+    );
+    const dtsMtime2 = fs2.statSync(dtsPath).mtimeMs;
+    recordDependency(ctx, dtsPath, dtsMtime2);
+    ctx.importCache.set(cacheKey, { mtime: dtsMtime2, nodeTypes: allNodeTypes, deps: [] });
+    const found = allNodeTypes.find((nt) => nt.functionName === imp.functionName);
+    if (found) {
+      return { ...found, name: imp.name, importSource: imp.importSource };
+    }
+    warnings.push(
+      `@fwImport: Function "${imp.functionName}" not found in type declarations for "${imp.importSource}". Available exports: ${allNodeTypes.map((nt) => nt.functionName).join(", ") || "(none)"}.`
+    );
+  } catch (err) {
+    warnings.push(
+      `@fwImport: Failed to parse type declarations for "${imp.importSource}": ${err.message}. Node "${imp.name}" will use a generic stub.`
+    );
+  }
+  return createImportStub(imp);
+}
+function inferNodeTypesDeep(project, dtsPath, importSource, visitedFiles, seenNames, depth) {
+  const MAX_DEPTH = 8;
+  const resolved = path3.resolve(dtsPath);
+  if (visitedFiles.has(resolved) || depth > MAX_DEPTH) return [];
+  visitedFiles.add(resolved);
+  let dtsContent;
+  try {
+    dtsContent = fs2.readFileSync(resolved, "utf-8");
+  } catch (err) {
+    if (depth === 0) throw err;
+    return [];
+  }
+  const sf = project.createSourceFile(
+    `__npm_dts__/${resolved.replace(/[^A-Za-z0-9._-]/g, "_")}.d.ts`,
+    dtsContent,
+    { overwrite: true }
+  );
+  const out = [];
+  try {
+    for (const fn of extractFunctionLikes(sf)) {
+      const fnName = fn.getName();
+      if (!fnName) continue;
+      if (seenNames.has(fnName)) continue;
+      seenNames.add(fnName);
+      const nodeType = inferNodeTypeFromFunction(fn, fnName, resolved);
+      nodeType.importSource = importSource;
+      nodeType.functionText = void 0;
+      out.push(nodeType);
+    }
+    const baseDir = path3.dirname(resolved);
+    for (const exp of sf.getExportDeclarations()) {
+      const spec = exp.getModuleSpecifierValue();
+      if (!spec || !spec.startsWith(".")) continue;
+      const target = resolveReExportedDts(baseDir, spec);
+      if (!target) continue;
+      out.push(
+        ...inferNodeTypesDeep(project, target, importSource, visitedFiles, seenNames, depth + 1)
+      );
+    }
+  } finally {
+    project.removeSourceFile(sf);
+  }
+  return out;
+}
+
+// src/parser/external-node-types.ts
+function externalToAST(ext) {
+  const inputs = {};
+  const outputs = {};
+  const isExpression = ext.expression === true;
+  if (ext.ports) {
+    for (const port of ext.ports) {
+      const def = {
+        dataType: port.type || "ANY",
+        ...port.defaultLabel && { label: port.defaultLabel }
+      };
+      if (port.direction === "OUTPUT") {
+        outputs[port.name] = def;
+      } else {
+        inputs[port.name] = def;
+      }
+    }
+  }
+  if (!inputs.execute) {
+    inputs.execute = { dataType: "STEP", label: "Execute" };
+  }
+  if (!outputs.onSuccess) {
+    outputs.onSuccess = { dataType: "STEP", label: "On Success", isControlFlow: true };
+  }
+  if (!outputs.onFailure) {
+    outputs.onFailure = {
+      dataType: "STEP",
+      label: "On Failure",
+      isControlFlow: true,
+      failure: true
+    };
+  }
+  return {
+    type: "NodeType",
+    name: ext.name,
+    functionName: ext.functionName || ext.name,
+    inputs,
+    outputs,
+    hasSuccessPort: "onSuccess" in outputs,
+    hasFailurePort: "onFailure" in outputs,
+    // Honor the supplied async flag so codegen emits `await` for an async
+    // foreign node (e.g. pack-core `waitForApproval`). Defaults to sync
+    // when the caller doesn't say, preserving prior behavior.
+    isAsync: ext.isAsync === true || ext.durableEffect === true,
+    executeWhen: EXECUTION_STRATEGIES.CONJUNCTION,
+    variant: "FUNCTION",
+    // Honor the expression flag so codegen calls the node WITHOUT the
+    // leading `execute` arg (e.g. pack-core `resolveMonth(spec)`).
+    ...isExpression && { expression: true },
+    ...ext.durableGate && { durableGate: ext.durableGate },
+    ...ext.durableEffect === true && { durableEffect: true },
+    ...ext.durablePure === true && { durablePure: true },
+    ...ext.resilience && { resilience: ext.resilience }
+  };
+}
+function mergeExternalNodeTypes(nodeTypes, externalNodeTypes) {
+  for (const ext of externalNodeTypes) {
+    const existingIdx = nodeTypes.findIndex(
+      (nt) => nt.name === ext.name || nt.functionName === ext.name
+    );
+    if (existingIdx === -1) {
+      nodeTypes.push(externalToAST(ext));
+      continue;
+    }
+    if (isImportStub(nodeTypes[existingIdx])) {
+      const replacement = externalToAST(ext);
+      const stubImportSource = nodeTypes[existingIdx].importSource;
+      if (stubImportSource) {
+        replacement.importSource = stubImportSource;
+      }
+      nodeTypes[existingIdx] = replacement;
+    }
+  }
+}
+
+// src/parser/annotation-suggestion.ts
+function generateAnnotationSuggestion(project, content, cursorLine, virtualPath = "virtual.ts") {
+  const existingFile = project.getSourceFile(virtualPath);
+  if (existingFile) {
+    project.removeSourceFile(existingFile);
+  }
+  const contentLines = content.split(/\r?\n/);
+  let typedJsDocStart = /^\s*\/\*\*\s*$/.test(contentLines[cursorLine] ?? "");
+  for (let i = cursorLine + 1; typedJsDocStart && i < contentLines.length; i++) {
+    const line = contentLines[i].trim();
+    if (!line.startsWith("*")) break;
+    if (line.includes("*/")) typedJsDocStart = false;
+  }
+  const parseContent = typedJsDocStart ? contentLines.map((line, i) => i === cursorLine ? "" : line).join("\n") : content;
+  const sourceFile = project.createSourceFile(virtualPath, parseContent, { overwrite: true });
+  try {
+    const allFunctions = extractFunctionLikes(sourceFile);
+    if (allFunctions.length === 0) return null;
+    let targetFn = null;
+    let bestDistance = Infinity;
+    for (const fn of allFunctions) {
+      const fnLine = fn.getStartLineNumber(false) - 1;
+      const distance = fnLine >= cursorLine ? fnLine - cursorLine : cursorLine - fnLine + 1e3;
+      if (distance < bestDistance) {
+        bestDistance = distance;
+        targetFn = fn;
+      }
+    }
+    if (!targetFn) return null;
+    const fnName = targetFn.getName() || "anonymous";
+    const fnStartLine = targetFn.getStartLineNumber(false) - 1;
+    if (cursorLine < fnStartLine - 30) return null;
+    const hasAnnotation = hasFlowWeaverAnnotation(targetFn);
+    const hasAnyJsDoc = targetFn.getJsDocs().length > 0;
+    if (hasAnyJsDoc && !hasAnnotation) return null;
+    const inferred = inferNodeTypeFromFunction(targetFn, fnName, virtualPath);
+    const paramDescriptions = /* @__PURE__ */ new Map();
+    for (const doc of targetFn.getJsDocs()) {
+      for (const tag of doc.getTags()) {
+        if (tag.getTagName() === "param") {
+          const comment = tag.getCommentText?.()?.trim() || "";
+          const paramMatch = comment.match(/^(?:\{[^}]*\}\s+)?(\w+)(?:\s*-\s*|\s+)(.+)/);
+          if (paramMatch) {
+            paramDescriptions.set(paramMatch[1], paramMatch[2]);
+          }
+        }
+      }
+    }
+    for (const [portName, portDef] of Object.entries(inferred.inputs)) {
+      const desc = paramDescriptions.get(portName);
+      if (desc) {
+        portDef.label = desc;
+      }
+    }
+    const existingPorts = extractExistingAnnotatedPorts(targetFn);
+    const missingLines = [];
+    for (const [portName, portDef] of Object.entries(inferred.inputs)) {
+      if (isControlFlowPort(portName)) continue;
+      if (existingPorts.inputs.has(portName)) continue;
+      missingLines.push(` * ${generateJSDocPortTag(portName, portDef, "input")}`);
+    }
+    for (const [portName, portDef] of Object.entries(inferred.outputs)) {
+      if (isControlFlowPort(portName)) continue;
+      if (existingPorts.outputs.has(portName)) continue;
+      missingLines.push(` * ${generateJSDocPortTag(portName, portDef, "output")}`);
+    }
+    if (hasAnnotation) {
+      const isWorkflow = isWorkflowBlock(targetFn);
+      if (isWorkflow) {
+        const connectionLines = generateWorkflowStructureSuggestion(targetFn, sourceFile);
+        missingLines.push(...connectionLines);
+      }
+      if (missingLines.length === 0) return null;
+      const lines2 = content.split(/\r?\n/);
+      let jsDocEndLine = -1;
+      for (let i = fnStartLine - 1; i >= 0; i--) {
+        if (lines2[i].includes("*/")) {
+          jsDocEndLine = i;
+          break;
+        }
+      }
+      if (jsDocEndLine < 0) return null;
+      const text2 = missingLines.join("\n") + "\n";
+      return {
+        text: text2,
+        insertLine: jsDocEndLine,
+        replaceLinesCount: 0
+      };
+    }
+    const lines = content.split(/\r?\n/);
+    const cursorLineText = lines[cursorLine] || "";
+    if (/^\s*\/\*\*\s*$/.test(cursorLineText)) {
+      const continuationLines = [
+        ` * @flowWeaver nodeType ${fnName}`,
+        ...inferred.expression ? [" * @expression"] : [],
+        ...missingLines,
+        " */"
+      ];
+      const text2 = continuationLines.join("\n") + "\n";
+      return {
+        text: text2,
+        insertLine: cursorLine + 1,
+        replaceLinesCount: 0
+      };
+    }
+    const allLines = [
+      "/**",
+      ` * @flowWeaver nodeType ${fnName}`,
+      ...inferred.expression ? [" * @expression"] : [],
+      ...missingLines,
+      " */"
+    ];
+    const text = allLines.join("\n") + "\n";
+    return {
+      text,
+      insertLine: fnStartLine,
+      replaceLinesCount: 0
+    };
+  } finally {
+    const sf = project.getSourceFile(virtualPath);
+    if (sf) project.removeSourceFile(sf);
+  }
+}
+function isWorkflowBlock(fn) {
+  for (const doc of fn.getJsDocs()) {
+    for (const tag of doc.getTags()) {
+      if (tag.getTagName() !== "flowWeaver") continue;
+      const comment = tag.getCommentText?.()?.trim() || "";
+      const firstWord = comment.split(/\s/)[0];
+      if (firstWord !== "nodeType") {
+        return true;
+      }
+    }
+  }
+  return false;
+}
+function generateWorkflowStructureSuggestion(fn, sourceFile) {
+  const nodeDecls = /* @__PURE__ */ new Map();
+  const existingConnections = /* @__PURE__ */ new Set();
+  for (const doc of fn.getJsDocs()) {
+    for (const tag of doc.getTags()) {
+      const tagName = tag.getTagName();
+      const comment = tag.getCommentText?.()?.trim() || "";
+      if (tagName === "node") {
+        const nodeMatch = comment.match(/^(\w+)\s+(\w+)/);
+        if (nodeMatch) {
+          nodeDecls.set(nodeMatch[1], nodeMatch[2]);
+        }
+      } else if (tagName === "connect") {
+        const connMatch = comment.match(/^(\w+)\.(\w+)\s*->\s*(\w+)\.(\w+)/);
+        if (connMatch) {
+          existingConnections.add(`${connMatch[1]}.${connMatch[2]}->${connMatch[3]}.${connMatch[4]}`);
+        }
+      }
+    }
+  }
+  if (nodeDecls.size < 2) return [];
+  const allFunctions = extractFunctionLikes(sourceFile);
+  const resolvedTypes = /* @__PURE__ */ new Map();
+  for (const [nodeId, typeName] of nodeDecls) {
+    const matchedFn = allFunctions.find((f) => f.getName() === typeName);
+    if (matchedFn) {
+      resolvedTypes.set(nodeId, inferNodeTypeFromFunction(matchedFn, typeName, sourceFile.getFilePath()));
+    }
+  }
+  const suggestions = [];
+  const nodeIds = [...nodeDecls.keys()];
+  for (let i = 0; i < nodeIds.length; i++) {
+    for (let j = 0; j < nodeIds.length; j++) {
+      if (i === j) continue;
+      const srcId = nodeIds[i];
+      const tgtId = nodeIds[j];
+      const srcType = resolvedTypes.get(srcId);
+      const tgtType = resolvedTypes.get(tgtId);
+      if (!srcType || !tgtType) continue;
+      for (const [outputName, outputDef] of Object.entries(srcType.outputs)) {
+        if (isControlFlowPort(outputName)) continue;
+        if (outputDef.dataType === "STEP") continue;
+        if (outputName in tgtType.inputs && !isControlFlowPort(outputName)) {
+          const connKey = `${srcId}.${outputName}->${tgtId}.${outputName}`;
+          if (!existingConnections.has(connKey)) {
+            suggestions.push(` * @connect ${srcId}.${outputName} -> ${tgtId}.${outputName}`);
+            existingConnections.add(connKey);
+          }
+        }
+      }
+    }
+  }
+  return suggestions;
+}
+function extractExistingAnnotatedPorts(fn) {
+  const inputs = /* @__PURE__ */ new Set();
+  const outputs = /* @__PURE__ */ new Set();
+  for (const doc of fn.getJsDocs()) {
+    for (const tag of doc.getTags()) {
+      const tagName = tag.getTagName();
+      const comment = tag.getCommentText?.()?.trim() || "";
+      const nameMatch = comment.match(/^\[?(\w+)/);
+      if (!nameMatch) continue;
+      const portName = nameMatch[1];
+      if (tagName === "input" || tagName === "step") {
+        inputs.add(portName);
+      } else if (tagName === "output") {
+        outputs.add(portName);
+      }
+    }
+  }
+  return { inputs, outputs };
+}
+
+// src/parser/pack-handlers.ts
+async function registerPackHandlers(tagRegistry, projectDir) {
+  const { discoverTagHandlers, discoverValidationRuleSets } = await import("./registry-K2U5KUTY.js");
+  const { pathToFileURL } = await import("node:url");
+  const handlers = await discoverTagHandlers(projectDir);
+  for (const discovered of handlers) {
+    const handlerAlreadyRegistered = discovered.tags.every((t) => tagRegistry.has(t));
+    try {
+      const mod = await import(pathToFileURL(discovered.absoluteFile).href);
+      if (!handlerAlreadyRegistered) {
+        const handlerFn = discovered.exportName ? mod[discovered.exportName] : mod.default;
+        if (typeof handlerFn === "function") {
+          tagRegistry.register(
+            discovered.tags,
+            discovered.namespace,
+            discovered.scope,
+            handlerFn
+          );
+        }
+      }
+      if (discovered.serializerExport) {
+        const serializerFn = mod[discovered.serializerExport];
+        if (typeof serializerFn === "function") {
+          tagRegistry.registerSerializer(discovered.namespace, serializerFn);
+        }
+      }
+    } catch {
+    }
+  }
+  const { validationRuleRegistry } = await import("./validation-registry-IQZX3UE3.js");
+  const ruleSets = await discoverValidationRuleSets(projectDir);
+  for (const ruleSet of ruleSets) {
+    try {
+      const mod = await import(pathToFileURL(ruleSet.absoluteFile).href);
+      const detectFn = mod[ruleSet.detectExport ?? "detect"];
+      const getRulesFn = mod[ruleSet.rulesExport ?? "getRules"];
+      if (typeof detectFn === "function" && typeof getRulesFn === "function") {
+        validationRuleRegistry.register({
+          name: ruleSet.name,
+          namespace: ruleSet.namespace,
+          detect: detectFn,
+          getRules: getRulesFn
+        });
+      }
+    } catch {
+    }
+  }
+}
+
+// src/parser/annotation-parser.ts
+var AnnotationParser = class {
+  project;
+  importCache = new LRUCache(200);
+  importStack = /* @__PURE__ */ new Set();
+  parseCache = new LRUCache(100);
+  /**
+   * Dependency recorders for the parses in progress: the outer entry belongs to
+   * the workflow file, and each imported file being processed pushes its own so
+   * its importCache entry can list what it read. A file read while any recorder
+   * is active is added to all of them.
+   */
+  dependencyRecorders = [];
+  /** Tag handler registry. Defaults to the global singleton (pre-populated by extensions). */
+  tagRegistry = tagHandlerRegistry;
+  /** Tracks which projectDirs have already had their pack handlers loaded. */
+  loadedPackDirs = /* @__PURE__ */ new Set();
+  constructor(project = getSharedProject()) {
+    this.project = project;
+  }
+  /**
+   * Discover and register tag handlers from installed marketplace packs.
+   * Results are cached per projectDir so repeated parse calls skip the scan.
+   */
+  async loadPackHandlers(projectDir) {
+    if (this.loadedPackDirs.has(projectDir)) return;
+    this.loadedPackDirs.add(projectDir);
+    await registerPackHandlers(this.tagRegistry, projectDir);
+  }
+  computeHash(content) {
+    return createHash("sha256").update(content).digest("hex").slice(0, 16);
+  }
+  /** The import state this parser shares with the import resolution functions. */
+  importContext() {
+    return {
+      project: this.project,
+      tagRegistry: this.tagRegistry,
+      importCache: this.importCache,
+      importStack: this.importStack,
+      dependencyRecorders: this.dependencyRecorders
+    };
+  }
+  parse(filePath, externalNodeTypes) {
+    const stats = fs3.statSync(filePath);
+    const hasExternalTypes = externalNodeTypes && externalNodeTypes.length > 0;
+    if (!hasExternalTypes) {
+      const cached = this.parseCache.get(filePath);
+      const reusable = cached !== void 0 && dependenciesUnchanged(cached.deps);
+      if (cached && reusable && cached.mtime === stats.mtimeMs) {
+        return cached.result;
+      }
+      const rawContent2 = fs3.readFileSync(filePath, "utf-8");
+      const content2 = hasInPlaceMarkers(rawContent2) ? stripGeneratedSections(rawContent2) : rawContent2;
+      const hash2 = this.computeHash(content2);
+      if (cached && reusable && cached.contentHash === hash2) {
+        cached.mtime = stats.mtimeMs;
+        return cached.result;
+      }
+      return this.fullParse(filePath, content2, hash2, stats.mtimeMs);
+    }
+    const rawContent = fs3.readFileSync(filePath, "utf-8");
+    const content = hasInPlaceMarkers(rawContent) ? stripGeneratedSections(rawContent) : rawContent;
+    const hash = this.computeHash(content);
+    return this.fullParse(filePath, content, hash, stats.mtimeMs, externalNodeTypes);
+  }
+  /**
+   * Parse an in-memory source override at its real filesystem path. Relative
+   * imports resolve exactly as they do for parse(), but the override is never
+   * written to disk or stored in the parse cache.
+   */
+  parseSourceAtPath(filePath, content, externalNodeTypes, importResolver, sourceLoader) {
+    return this.fullParse(
+      filePath,
+      content,
+      this.computeHash(content),
+      0,
+      externalNodeTypes,
+      false,
+      importResolver,
+      sourceLoader
+    );
+  }
+  fullParse(filePath, content, hash, mtimeMs, externalNodeTypes, cacheResult = true, importResolver, sourceLoader) {
+    this.importStack.clear();
+    const deps = /* @__PURE__ */ new Map();
+    this.dependencyRecorders = [deps];
+    const ctx = this.importContext();
+    const errors = [];
+    const warnings = [];
+    if (sourceLoader !== void 0) {
+      preloadSourceOverrides(
+        this.project,
+        filePath,
+        content,
+        importResolver,
+        sourceLoader,
+        /* @__PURE__ */ new Set([filePath])
+      );
+    }
+    const sourceFile = this.project.createSourceFile(filePath, content, { overwrite: true });
+    this.importStack.add(filePath);
+    const importedNodeTypes = sourceLoader === void 0 ? [] : extractImportedNodeTypes(ctx, sourceFile, filePath, importResolver, sourceLoader, warnings);
+    const localNodeTypes = extractNodeTypes(sourceFile, warnings, this.tagRegistry);
+    if (sourceLoader === void 0) {
+      importedNodeTypes.push(...extractImportedNodeTypes(
+        ctx,
+        sourceFile,
+        filePath,
+        importResolver,
+        sourceLoader,
+        warnings
+      ));
+    }
+    const workflowSignatures = extractWorkflowSignatures(sourceFile, filePath, warnings, this.tagRegistry);
+    const sameFileWorkflowNodeTypes = workflowSignatures.map((wf) => workflowToNodeType(wf));
+    const nodeTypes = [...localNodeTypes, ...importedNodeTypes, ...sameFileWorkflowNodeTypes];
+    if (externalNodeTypes?.length) {
+      mergeExternalNodeTypes(nodeTypes, externalNodeTypes);
+    }
+    const inferredNodeTypes = inferNodeTypesFromUnannotated(sourceFile, nodeTypes, localNodeTypes, warnings);
+    nodeTypes.push(...inferredNodeTypes);
+    const workflows = extractWorkflows(
+      sourceFile,
+      nodeTypes,
+      filePath,
+      errors,
+      warnings,
+      this.tagRegistry,
+      (imp, currentFilePath, importWarnings) => resolveImportAnnotation(ctx, imp, currentFilePath, importWarnings)
+    );
+    const dedupedWarnings = [...new Set(warnings)];
+    const result = { workflows, nodeTypes, errors, warnings: dedupedWarnings };
+    this.project.removeSourceFile(sourceFile);
+    this.dependencyRecorders = [];
+    if (cacheResult && !externalNodeTypes?.length) {
+      this.parseCache.set(filePath, {
+        mtime: mtimeMs,
+        contentHash: hash,
+        result,
+        deps: [...deps].map(([path4, mtime]) => ({ path: path4, mtime }))
+      });
+    }
+    return result;
+  }
+  /**
+   * Parse workflow from a string instead of a file path.
+   * Useful for testing and in-memory operations.
+   *
+   * Note: Imports from other workflow files are NOT supported in this mode
+   * since there's no filesystem context. Use parse() for files with imports.
+   *
+   * @param code - TypeScript source code containing workflow definitions
+   * @param virtualPath - Virtual file path for error messages (default: 'virtual.ts')
+   * @returns ParseResult with workflows and nodeTypes
+   */
+  parseFromString(code, virtualPath = "virtual.ts") {
+    this.importStack.clear();
+    const existingFile = this.project.getSourceFile(virtualPath);
+    if (existingFile) {
+      this.project.removeSourceFile(existingFile);
+    }
+    const sourceFile = this.project.createSourceFile(virtualPath, code, { overwrite: true });
+    const errors = [];
+    const warnings = [];
+    const localNodeTypes = extractNodeTypes(sourceFile, warnings, this.tagRegistry);
+    const workflowSignatures = extractWorkflowSignatures(sourceFile, virtualPath, warnings, this.tagRegistry);
+    const sameFileWorkflowNodeTypes = workflowSignatures.map((wf) => workflowToNodeType(wf));
+    const nodeTypes = [...localNodeTypes, ...sameFileWorkflowNodeTypes];
+    const inferredNodeTypes = inferNodeTypesFromUnannotated(sourceFile, nodeTypes, localNodeTypes, warnings);
+    nodeTypes.push(...inferredNodeTypes);
+    const ctx = this.importContext();
+    const workflows = extractWorkflows(
+      sourceFile,
+      nodeTypes,
+      virtualPath,
+      errors,
+      warnings,
+      this.tagRegistry,
+      (imp, currentFilePath, importWarnings) => resolveImportAnnotation(ctx, imp, currentFilePath, importWarnings)
+    );
+    this.project.removeSourceFile(sourceFile);
+    const dedupedWarnings = [...new Set(warnings)];
+    return {
+      workflows,
+      nodeTypes,
+      errors,
+      warnings: dedupedWarnings
+    };
+  }
+  clearCache() {
+    this.importCache.clear();
+    this.parseCache.clear();
+  }
+  /** Clear only the parse result cache, keeping the import/node-type cache intact. */
+  clearParseCache() {
+    this.parseCache.clear();
+  }
+  /**
+   * Suggest the `@flowWeaver` JSDoc for the function at or below `cursorLine`
+   * (0-based) in `content`. Returns the text to insert and where, or null when
+   * there is nothing to suggest.
+   */
+  generateAnnotationSuggestion(content, cursorLine, virtualPath = "virtual.ts") {
+    return generateAnnotationSuggestion(this.project, content, cursorLine, virtualPath);
+  }
+};
+var parser = new AnnotationParser();
+
+export {
+  MARKERS,
+  hasInPlaceMarkers,
+  stripGeneratedSections,
+  findClosestMatches,
+  resolveNpmNodeTypes,
+  AnnotationParser,
+  parser
+};