@graphrefly/graphrefly 0.45.0 → 0.46.0

package/dist/utils/graphspec/index.cjs

@@ -0,0 +1,1174 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/utils/graphspec/index.ts
+var graphspec_exports = {};
+__export(graphspec_exports, {
+  compileSpec: () => compileSpec,
+  decompileSpec: () => decompileSpec,
+  extractFnFactory: () => extractFnFactory,
+  extractSourceFactory: () => extractSourceFactory,
+  generateCatalogPrompt: () => generateCatalogPrompt,
+  isRichFnEntry: () => isRichFnEntry,
+  isRichSourceEntry: () => isRichSourceEntry,
+  llmCompose: () => llmCompose,
+  llmRefine: () => llmRefine,
+  specDiff: () => specDiff,
+  validateOwnership: () => validateOwnership,
+  validateSpec: () => validateSpec,
+  validateSpecAgainstCatalog: () => validateSpecAgainstCatalog
+});
+module.exports = __toCommonJS(graphspec_exports);
+var import_core3 = require("@graphrefly/pure-ts/core");
+var import_graph3 = require("@graphrefly/pure-ts/graph");
+
+// src/utils/reduction/index.ts
+var import_core2 = require("@graphrefly/pure-ts/core");
+var import_extra2 = require("@graphrefly/pure-ts/extra");
+var import_graph2 = require("@graphrefly/pure-ts/graph");
+var import_extra3 = require("@graphrefly/pure-ts/extra");
+
+// src/base/meta/domain-meta.ts
+function domainMeta(domain, kind, extra) {
+  return {
+    [domain]: true,
+    [`${domain}_type`]: kind,
+    ...extra ?? {}
+  };
+}
+
+// src/base/mutation/index.ts
+var import_core = require("@graphrefly/pure-ts/core");
+var import_extra = require("@graphrefly/pure-ts/extra");
+var import_graph = require("@graphrefly/pure-ts/graph");
+function tryIncrementBounded(counter, cap, by = 1) {
+  const cur = counter.cache ?? 0;
+  if (by > cap - cur) return false;
+  counter.down([[import_core.DIRTY], [import_core.DATA, cur + by]]);
+  return true;
+}
+var DEFAULT_AUDIT_GUARD = (0, import_core.policy)((allow, deny) => {
+  allow("observe");
+  allow("signal");
+  deny("write");
+});
+
+// src/utils/reduction/index.ts
+function baseMeta(kind, meta) {
+  return domainMeta("reduction", kind, meta);
+}
+function feedback(graph, condition, reentry, opts) {
+  const maxIter = opts?.maxIterations ?? 10;
+  const counterName = `__feedback_${condition}`;
+  const counter = (0, import_core2.node)([], {
+    ...{
+      meta: baseMeta("feedback_counter", {
+        maxIterations: maxIter,
+        feedbackFrom: condition,
+        feedbackTo: reentry
+      })
+    },
+    initial: 0
+  });
+  graph.add(counter, { name: counterName });
+  const condNode = graph.resolve(condition);
+  const reentryNode = graph.resolve(reentry);
+  const feedbackEffectName = `__feedback_effect_${condition}`;
+  const feedbackEffect = (0, import_core2.node)(
+    [],
+    (_data, _feedbackActions) => {
+      const unsub = condNode.subscribe((msgs) => {
+        for (const msg of msgs) {
+          const t = msg[0];
+          if (t === import_core2.DATA) {
+            const condValue = msg[1];
+            if (condValue == null) return;
+            (0, import_core2.batch)(() => {
+              if (tryIncrementBounded(counter, maxIter)) {
+                reentryNode.emit(condValue);
+              }
+            });
+          } else if (t === import_core2.COMPLETE || t === import_core2.ERROR) {
+            const terminal = t === import_core2.ERROR && msg.length > 1 ? [import_core2.ERROR, msg[1]] : [t];
+            counter.down([terminal]);
+          }
+        }
+      });
+      return () => unsub();
+    },
+    {
+      name: feedbackEffectName,
+      describeKind: "effect",
+      meta: {
+        ...baseMeta("feedback_effect", {
+          feedbackFrom: condition,
+          feedbackTo: reentry
+        }),
+        _internal: true
+      }
+    }
+  );
+  graph.add(feedbackEffect, { name: feedbackEffectName });
+  graph.addDisposer((0, import_extra3.keepalive)(feedbackEffect));
+  return graph;
+}
+
+// src/utils/graphspec/index.ts
+function readFactory(node4) {
+  const f = node4.meta?.factory;
+  return typeof f === "string" ? f : void 0;
+}
+function readFactoryArgs(node4) {
+  const a = node4.meta?.factoryArgs;
+  return a != null && typeof a === "object" ? a : {};
+}
+function readStateInitial(node4) {
+  const args = readFactoryArgs(node4);
+  if ("initial" in args) return args.initial;
+  return node4.value;
+}
+function isRichFnEntry(entry) {
+  return typeof entry === "object" && entry !== null && "factory" in entry;
+}
+function isRichSourceEntry(entry) {
+  return typeof entry === "object" && entry !== null && "factory" in entry;
+}
+function extractFnFactory(entry) {
+  return isRichFnEntry(entry) ? entry.factory : entry;
+}
+function extractSourceFactory(entry) {
+  return isRichSourceEntry(entry) ? entry.factory : entry;
+}
+function generateCatalogPrompt(catalog) {
+  const sections = [];
+  if (catalog.fns) {
+    const groups = /* @__PURE__ */ new Map();
+    for (const [name, entry] of Object.entries(catalog.fns)) {
+      const tag = isRichFnEntry(entry) ? entry.tags?.[0] ?? "Other" : "Other";
+      if (!groups.has(tag)) groups.set(tag, []);
+      groups.get(tag).push(formatFnEntry(name, entry));
+    }
+    for (const [tag, lines] of groups) {
+      sections.push(`${tag}:
+${lines.join("\n")}`);
+    }
+  }
+  if (catalog.sources) {
+    const lines = [];
+    for (const [name, entry] of Object.entries(catalog.sources)) {
+      lines.push(formatSourceEntry(name, entry));
+    }
+    if (lines.length > 0) {
+      sections.push(`Sources:
+${lines.join("\n")}`);
+    }
+  }
+  return sections.join("\n\n");
+}
+function formatFnEntry(name, entry) {
+  if (!isRichFnEntry(entry)) return `- ${name}`;
+  let line = `- ${name}: ${entry.description}`;
+  if (entry.configSchema) {
+    const fields = Object.entries(entry.configSchema).map(([k, v]) => {
+      let desc = `${k}: ${v.type}`;
+      if (v.enum) desc += ` (${v.enum.join("|")})`;
+      if (v.required === false) desc += "?";
+      return desc;
+    });
+    line += `. Config: { ${fields.join(", ")} }`;
+  }
+  return line;
+}
+function formatSourceEntry(name, entry) {
+  if (!isRichSourceEntry(entry)) return `- ${name}`;
+  let line = `- ${name}: ${entry.description}`;
+  if (entry.configSchema) {
+    const fields = Object.entries(entry.configSchema).map(([k, v]) => {
+      let desc = `${k}: ${v.type}`;
+      if (v.required === false) desc += "?";
+      return desc;
+    });
+    line += `. Config: { ${fields.join(", ")} }`;
+  }
+  return line;
+}
+function validateSpecAgainstCatalog(spec, catalog) {
+  const errors = [];
+  const fnNames = new Set(Object.keys(catalog.fns ?? {}));
+  const sourceNames = new Set(Object.keys(catalog.sources ?? {}));
+  for (const [nodeName, nodeRaw] of Object.entries(spec.nodes)) {
+    if (nodeRaw.type === "template") continue;
+    const node4 = nodeRaw;
+    const factoryName = readFactory(node4);
+    if (factoryName == null) continue;
+    const isProducer = node4.type === "producer";
+    if (node4.type === "state" && factoryName === "state") continue;
+    if (isProducer) {
+      const inSources = sourceNames.has(factoryName);
+      const inFns = fnNames.has(factoryName);
+      if (!inSources && !inFns && (sourceNames.size > 0 || fnNames.size > 0)) {
+        const suggestion = findClosest(factoryName, sourceNames) ?? findClosest(factoryName, fnNames);
+        errors.push(
+          `Node "${nodeName}": source "${factoryName}" not found in catalog` + (suggestion ? `. Did you mean "${suggestion}"?` : "")
+        );
+      }
+    } else {
+      if (fnNames.size > 0 && !fnNames.has(factoryName)) {
+        if (sourceNames.has(factoryName)) {
+          errors.push(
+            `Node "${nodeName}": fn "${factoryName}" is a source, not a function. Use it as a producer source instead, or use a function from: ${[...fnNames].join(", ")}`
+          );
+        } else {
+          const suggestion = findClosest(factoryName, fnNames);
+          errors.push(
+            `Node "${nodeName}": fn "${factoryName}" not found in catalog` + (suggestion ? `. Did you mean "${suggestion}"?` : "")
+          );
+        }
+      }
+    }
+    const factoryArgs = readFactoryArgs(node4);
+    if (!isProducer && catalog.fns?.[factoryName]) {
+      const entry = catalog.fns[factoryName];
+      if (isRichFnEntry(entry) && entry.configSchema) {
+        for (const [field, schema] of Object.entries(entry.configSchema)) {
+          if (schema.required !== false && !(field in factoryArgs)) {
+            errors.push(`Node "${nodeName}": config missing required field "${field}"`);
+          }
+          if (field in factoryArgs && schema.enum) {
+            const val = factoryArgs[field];
+            if (!schema.enum.includes(val)) {
+              errors.push(
+                `Node "${nodeName}": config.${field} = ${JSON.stringify(val)}, expected one of: ${schema.enum.join(", ")}`
+              );
+            }
+          }
+        }
+      }
+    }
+    if (isProducer && catalog.sources?.[factoryName]) {
+      const entry = catalog.sources[factoryName];
+      if (isRichSourceEntry(entry) && entry.configSchema) {
+        for (const [field, schema] of Object.entries(entry.configSchema)) {
+          if (schema.required !== false && !(field in factoryArgs)) {
+            errors.push(`Node "${nodeName}": config missing required field "${field}"`);
+          }
+          if (field in factoryArgs && schema.enum) {
+            const val = factoryArgs[field];
+            if (!schema.enum.includes(val)) {
+              errors.push(
+                `Node "${nodeName}": config.${field} = ${JSON.stringify(val)}, expected one of: ${schema.enum.join(", ")}`
+              );
+            }
+          }
+        }
+      }
+    }
+  }
+  if (spec.templates) {
+    for (const [tName, template] of Object.entries(spec.templates)) {
+      for (const [nodeName, node4] of Object.entries(template.nodes)) {
+        const factoryName = readFactory(node4);
+        if (factoryName == null) continue;
+        if (node4.type === "state" && factoryName === "state") continue;
+        if (node4.type === "producer") continue;
+        if (fnNames.size > 0 && !fnNames.has(factoryName)) {
+          const suggestion = findClosest(factoryName, fnNames);
+          errors.push(
+            `Template "${tName}" node "${nodeName}": fn "${factoryName}" not found in catalog` + (suggestion ? `. Did you mean "${suggestion}"?` : "")
+          );
+        }
+      }
+    }
+  }
+  return { valid: errors.length === 0, errors, warnings: [] };
+}
+function findClosest(input, candidates) {
+  let best = null;
+  let bestDist = Infinity;
+  const lower = input.toLowerCase();
+  for (const c of candidates) {
+    const dist = levenshtein(lower, c.toLowerCase());
+    if (dist < bestDist && dist <= Math.max(3, Math.floor(input.length / 2))) {
+      bestDist = dist;
+      best = c;
+    }
+  }
+  return best;
+}
+function levenshtein(a, b) {
+  const m = a.length;
+  const n = b.length;
+  const dp = Array.from(
+    { length: m + 1 },
+    (_, i) => Array.from({ length: n + 1 }, (_2, j) => i === 0 ? j : j === 0 ? i : 0)
+  );
+  for (let i = 1; i <= m; i++) {
+    for (let j = 1; j <= n; j++) {
+      dp[i][j] = a[i - 1] === b[j - 1] ? dp[i - 1][j - 1] : 1 + Math.min(dp[i - 1][j], dp[i][j - 1], dp[i - 1][j - 1]);
+    }
+  }
+  return dp[m][n];
+}
+var VALID_NODE_TYPES = /* @__PURE__ */ new Set([
+  "state",
+  "producer",
+  "derived",
+  "effect",
+  "operator",
+  "template"
+]);
+var INNER_NODE_TYPES = /* @__PURE__ */ new Set(["state", "producer", "derived", "effect", "operator"]);
+function validateSpec(spec) {
+  const errors = [];
+  const warnings = [];
+  if (spec == null || typeof spec !== "object") {
+    return { valid: false, errors: ["GraphSpec must be a non-null object"], warnings };
+  }
+  const s = spec;
+  if (typeof s.name !== "string" || s.name.length === 0) {
+    errors.push("Missing or empty 'name' field");
+  }
+  if (s.nodes == null || typeof s.nodes !== "object" || Array.isArray(s.nodes)) {
+    errors.push("Missing or invalid 'nodes' field (must be an object)");
+    return { valid: false, errors, warnings };
+  }
+  const nodeNames = new Set(Object.keys(s.nodes));
+  const nodeTypes = /* @__PURE__ */ new Map();
+  const templateDefs = /* @__PURE__ */ new Map();
+  if (s.templates != null && typeof s.templates === "object" && !Array.isArray(s.templates)) {
+    for (const [tName, tRaw] of Object.entries(s.templates)) {
+      if (tRaw != null && typeof tRaw === "object") {
+        const t = tRaw;
+        templateDefs.set(tName, {
+          params: Array.isArray(t.params) ? t.params : []
+        });
+      }
+    }
+  }
+  if (s.templates != null) {
+    if (typeof s.templates !== "object" || Array.isArray(s.templates)) {
+      errors.push("'templates' must be an object");
+    } else {
+      for (const [tName, tRaw] of Object.entries(s.templates)) {
+        if (tRaw == null || typeof tRaw !== "object") {
+          errors.push(`Template "${tName}": must be an object`);
+          continue;
+        }
+        const t = tRaw;
+        if (!Array.isArray(t.params)) {
+          errors.push(`Template "${tName}": missing 'params' array`);
+        }
+        if (t.nodes == null || typeof t.nodes !== "object" || Array.isArray(t.nodes)) {
+          errors.push(`Template "${tName}": missing or invalid 'nodes' object`);
+        } else {
+          const paramSet = new Set(Array.isArray(t.params) ? t.params : []);
+          const innerNames = new Set(Object.keys(t.nodes));
+          for (const [nName, nRaw] of Object.entries(t.nodes)) {
+            if (nRaw == null || typeof nRaw !== "object") {
+              errors.push(`Template "${tName}" node "${nName}": must be an object`);
+              continue;
+            }
+            const n = nRaw;
+            if (typeof n.type !== "string" || !INNER_NODE_TYPES.has(n.type)) {
+              errors.push(`Template "${tName}" node "${nName}": invalid type`);
+            }
+            if (Array.isArray(n.deps)) {
+              for (const dep of n.deps) {
+                if (!innerNames.has(dep) && !paramSet.has(dep)) {
+                  errors.push(
+                    `Template "${tName}" node "${nName}": dep "${dep}" is not an inner node or param`
+                  );
+                }
+              }
+            }
+          }
+          if (typeof t.output !== "string") {
+            errors.push(`Template "${tName}": missing 'output' string`);
+          } else if (!t.nodes[t.output]) {
+            errors.push(`Template "${tName}": output "${t.output}" is not a declared node`);
+          }
+        }
+      }
+    }
+  }
+  for (const [name, raw] of Object.entries(s.nodes)) {
+    if (raw == null || typeof raw !== "object") {
+      errors.push(`Node "${name}": must be an object`);
+      continue;
+    }
+    const n = raw;
+    if (typeof n.type !== "string" || !VALID_NODE_TYPES.has(n.type)) {
+      errors.push(
+        `Node "${name}": invalid type "${String(n.type)}" (expected: ${[...VALID_NODE_TYPES].join(", ")})`
+      );
+      continue;
+    }
+    nodeTypes.set(name, n.type);
+    if (n.type === "template") {
+      if (typeof n.template !== "string" || !templateDefs.has(n.template)) {
+        errors.push(`Node "${name}": template "${String(n.template)}" not found in templates`);
+      } else {
+        if (n.bind == null || typeof n.bind !== "object" || Array.isArray(n.bind)) {
+          errors.push(`Node "${name}": template ref requires 'bind' object`);
+        } else {
+          const tmpl = templateDefs.get(n.template);
+          const bind = n.bind;
+          for (const param of tmpl.params) {
+            if (!(param in bind)) {
+              errors.push(
+                `Node "${name}": template param "${param}" is not bound (template "${n.template}")`
+              );
+            }
+          }
+          for (const [, target] of Object.entries(bind)) {
+            if (typeof target === "string" && !nodeNames.has(target)) {
+              errors.push(
+                `Node "${name}": bind target "${target}" does not reference an existing node`
+              );
+            }
+          }
+        }
+      }
+    } else {
+      if (Array.isArray(n.deps)) {
+        for (const dep of n.deps) {
+          if (dep === name) {
+            errors.push(`Node "${name}": self-referencing dep`);
+          } else if (!nodeNames.has(dep)) {
+            errors.push(`Node "${name}": dep "${dep}" does not reference an existing node`);
+          }
+        }
+      }
+      if ((n.type === "derived" || n.type === "effect" || n.type === "operator") && !Array.isArray(n.deps)) {
+        errors.push(`Node "${name}": ${n.type} node should have a 'deps' array`);
+      }
+    }
+  }
+  if (s.feedback != null) {
+    if (!Array.isArray(s.feedback)) {
+      errors.push("'feedback' must be an array");
+    } else {
+      for (let i = 0; i < s.feedback.length; i++) {
+        const edge = s.feedback[i];
+        if (edge == null || typeof edge !== "object") {
+          errors.push(`Feedback [${i}]: must be an object`);
+          continue;
+        }
+        const e = edge;
+        if (typeof e.from !== "string" || !nodeNames.has(e.from)) {
+          errors.push(
+            `Feedback [${i}]: 'from' "${String(e.from)}" does not reference an existing node`
+          );
+        } else if (nodeTypes.get(e.from) === "effect") {
+          warnings.push(
+            `Feedback [${i}]: 'from' "${e.from}" is an effect node \u2014 effects emit no DATA, so the feedback edge will never fire. Did you mean a derived/state node upstream?`
+          );
+        }
+        if (typeof e.from === "string" && e.from === e.to) {
+          errors.push(`Feedback [${i}]: 'from' and 'to' must be different nodes`);
+        }
+        if (typeof e.to !== "string" || !nodeNames.has(e.to)) {
+          errors.push(
+            `Feedback [${i}]: 'to' "${String(e.to)}" does not reference an existing node`
+          );
+        } else if (typeof e.to === "string" && nodeTypes.get(e.to) !== "state") {
+          errors.push(
+            `Feedback [${i}]: 'to' node "${e.to}" must be a state node (got "${nodeTypes.get(e.to) ?? "unknown"}")`
+          );
+        }
+      }
+    }
+  }
+  return {
+    valid: errors.length === 0,
+    errors,
+    warnings
+  };
+}
+function readOwner(node4) {
+  const o = node4.meta?.owner;
+  return typeof o === "string" && o.length > 0 ? o : void 0;
+}
+var OVERRIDE_OWNER_TRAILER = /^\s*override-owner\s*:\s*(.+?)\s*$/im;
+function parseOverrideOwner(commitMessage) {
+  if (commitMessage == null) return void 0;
+  const m = OVERRIDE_OWNER_TRAILER.exec(commitMessage);
+  const reason = m?.[1]?.trim();
+  return reason != null && reason.length > 0 ? reason : void 0;
+}
+function validateOwnership(spec, prDiff) {
+  const violations = [];
+  const overridden = [];
+  if (spec == null || typeof spec !== "object") {
+    return { ok: true, violations, overridden };
+  }
+  const s = spec;
+  const nodes = s.nodes;
+  if (nodes == null || typeof nodes !== "object" || Array.isArray(nodes)) {
+    return { ok: true, violations, overridden };
+  }
+  const edited = new Set(prDiff.editedFactories);
+  if (edited.size > 0) {
+    for (const [path, nRaw] of Object.entries(nodes)) {
+      if (nRaw == null || typeof nRaw !== "object") continue;
+      const n = nRaw;
+      const factory = readFactory(n);
+      if (factory == null || !edited.has(factory)) continue;
+      const owner = readOwner(n);
+      if (owner == null) continue;
+      if (owner === prDiff.author) continue;
+      violations.push({ node: path, owner, author: prDiff.author, factory });
+    }
+  }
+  const overrideReason = parseOverrideOwner(prDiff.commitMessage);
+  if (violations.length > 0 && overrideReason != null) {
+    overridden.push(...violations);
+    return { ok: true, violations: [], overridden, overrideReason };
+  }
+  return {
+    ok: violations.length === 0,
+    violations,
+    overridden,
+    ...overrideReason != null ? { overrideReason } : {}
+  };
+}
+function compileSpec(spec, opts) {
+  const validation = validateSpec(spec);
+  if (!validation.valid) {
+    throw new Error(`compileSpec: invalid GraphSpec:
+${validation.errors.join("\n")}`);
+  }
+  const specFactory = spec.factory;
+  const specFactoryArgs = spec.factoryArgs;
+  if (typeof specFactory === "string") {
+    const graphFactory = opts?.catalog?.graphFactories?.[specFactory];
+    if (graphFactory) return graphFactory(specFactoryArgs);
+  }
+  const catalog = opts?.catalog ?? {};
+  const onMissing = opts?.onMissing ?? "placeholder";
+  const g = new import_graph3.Graph(spec.name);
+  const templates = spec.templates ?? {};
+  const catalogValidation = validateSpecAgainstCatalog(spec, catalog);
+  if (!catalogValidation.valid) {
+    throw new Error(
+      `compileSpec: catalog validation errors:
+${catalogValidation.errors.join("\n")}`
+    );
+  }
+  const missingEntries = [];
+  const recordMissing = (nodePath, kind, name) => {
+    missingEntries.push({ path: nodePath, kind, name });
+  };
+  const resolveFn = (fnName) => {
+    const entry = catalog.fns?.[fnName];
+    return entry ? extractFnFactory(entry) : void 0;
+  };
+  const resolveSource = (sourceName) => {
+    const entry = catalog.sources?.[sourceName];
+    return entry ? extractSourceFactory(entry) : void 0;
+  };
+  const stripFactoryMeta = (meta) => {
+    if (!meta) return void 0;
+    const out = {};
+    for (const [k, v] of Object.entries(meta)) {
+      if (k === "factory" || k === "factoryArgs") continue;
+      out[k] = v;
+    }
+    return Object.keys(out).length > 0 ? out : void 0;
+  };
+  const created = /* @__PURE__ */ new Map();
+  const deferred = [];
+  for (const [name, raw] of Object.entries(spec.nodes)) {
+    if (raw.type === "template") continue;
+    const n = raw;
+    const factoryName = readFactory(n);
+    const factoryArgs = readFactoryArgs(n);
+    if (n.type === "state") {
+      const initial = readStateInitial(n);
+      const nd = (0, import_core3.node)([], {
+        name,
+        initial,
+        meta: stripFactoryMeta(n.meta)
+      });
+      g.add(nd, { name });
+      created.set(name, nd);
+    } else if (n.type === "producer") {
+      const sourceFactory = factoryName ? resolveSource(factoryName) : void 0;
+      const fnFactory = factoryName ? resolveFn(factoryName) : void 0;
+      if (sourceFactory) {
+        const nd = sourceFactory(factoryArgs);
+        g.add(nd, { name });
+        created.set(name, nd);
+      } else if (fnFactory) {
+        const nd = fnFactory([], factoryArgs);
+        g.add(nd, { name });
+        created.set(name, nd);
+      } else {
+        if (factoryName) recordMissing(name, "source", factoryName);
+        const nd = (0, import_core3.node)([], () => {
+        }, {
+          name,
+          describeKind: "producer",
+          meta: { ...stripFactoryMeta(n.meta), _specSource: factoryName }
+        });
+        g.add(nd, { name });
+        created.set(name, nd);
+      }
+    } else {
+      deferred.push([name, n]);
+    }
+  }
+  let progressed = true;
+  const pending = new Map(deferred);
+  while (pending.size > 0 && progressed) {
+    progressed = false;
+    for (const [name, n] of [...pending.entries()]) {
+      const deps = n.deps ?? [];
+      if (!deps.every((dep) => created.has(dep))) continue;
+      const resolvedDeps = deps.map((dep) => created.get(dep));
+      const factoryName = readFactory(n);
+      const factoryArgs = readFactoryArgs(n);
+      const fnFactory = factoryName ? resolveFn(factoryName) : void 0;
+      let nd;
+      if (fnFactory) {
+        nd = fnFactory(resolvedDeps, factoryArgs);
+      } else if (n.type === "effect") {
+        if (factoryName) recordMissing(name, "fn", factoryName);
+        nd = (0, import_core3.node)(resolvedDeps, () => {
+        }, { describeKind: "effect" });
+      } else {
+        if (factoryName) recordMissing(name, "fn", factoryName);
+        nd = (0, import_core3.node)(
+          resolvedDeps,
+          (batchData, actions, ctx) => {
+            const data = batchData.map(
+              (batch3, i) => batch3 != null && batch3.length > 0 ? batch3.at(-1) : ctx.prevData[i]
+            );
+            actions.emit(data[0]);
+          },
+          { describeKind: "derived" }
+        );
+      }
+      g.add(nd, { name });
+      created.set(name, nd);
+      pending.delete(name);
+      progressed = true;
+    }
+  }
+  if (pending.size > 0) {
+    const unresolved = [...pending.keys()].sort().join(", ");
+    throw new Error(`compileSpec: unresolvable deps for nodes: ${unresolved}`);
+  }
+  for (const [name, raw] of Object.entries(spec.nodes)) {
+    if (raw.type !== "template") continue;
+    const ref = raw;
+    const tmpl = templates[ref.template];
+    const sub = new import_graph3.Graph(name);
+    const subCreated = /* @__PURE__ */ new Map();
+    const subDeferred = [];
+    for (const [nName, nSpec] of Object.entries(tmpl.nodes)) {
+      const resolvedDeps = (nSpec.deps ?? []).map((dep) => {
+        if (dep.startsWith("$") && ref.bind[dep]) {
+          return ref.bind[dep];
+        }
+        return dep;
+      });
+      const specWithResolvedDeps = { ...nSpec, deps: resolvedDeps };
+      const factoryName = readFactory(nSpec);
+      const factoryArgs = readFactoryArgs(nSpec);
+      if (nSpec.type === "state") {
+        const initial = readStateInitial(nSpec);
+        const nd = (0, import_core3.node)([], {
+          name: nName,
+          initial,
+          meta: stripFactoryMeta(nSpec.meta)
+        });
+        sub.add(nd, { name: nName });
+        subCreated.set(nName, nd);
+      } else if (nSpec.type === "producer") {
+        const sourceFactory = factoryName ? resolveSource(factoryName) : void 0;
+        const fnFactory = factoryName ? resolveFn(factoryName) : void 0;
+        if (sourceFactory) {
+          const nd = sourceFactory(factoryArgs);
+          sub.add(nd, { name: nName });
+          subCreated.set(nName, nd);
+        } else if (fnFactory) {
+          const nd = fnFactory([], factoryArgs);
+          sub.add(nd, { name: nName });
+          subCreated.set(nName, nd);
+        } else {
+          if (factoryName) recordMissing(`${name}.${nName}`, "source", factoryName);
+          const nd = (0, import_core3.node)([], () => {
+          }, {
+            name: nName,
+            describeKind: "producer",
+            meta: { ...stripFactoryMeta(nSpec.meta), _specSource: factoryName }
+          });
+          sub.add(nd, { name: nName });
+          subCreated.set(nName, nd);
+        }
+      } else {
+        subDeferred.push([nName, specWithResolvedDeps]);
+      }
+    }
+    let subProgressed = true;
+    const subPending = new Map(subDeferred);
+    while (subPending.size > 0 && subProgressed) {
+      subProgressed = false;
+      for (const [nName, nSpec] of [...subPending.entries()]) {
+        const deps = nSpec.deps ?? [];
+        const allReady = deps.every((dep) => subCreated.has(dep) || created.has(dep));
+        if (!allReady) continue;
+        const resolvedDeps = deps.map((dep) => subCreated.get(dep) ?? created.get(dep));
+        const factoryName = readFactory(nSpec);
+        const factoryArgs = readFactoryArgs(nSpec);
+        const fnFactory = factoryName ? resolveFn(factoryName) : void 0;
+        let nd;
+        if (fnFactory) {
+          nd = fnFactory(resolvedDeps, factoryArgs);
+        } else if (nSpec.type === "effect") {
+          if (factoryName) recordMissing(`${name}.${nName}`, "fn", factoryName);
+          nd = (0, import_core3.node)(resolvedDeps, () => {
+          }, { describeKind: "effect" });
+        } else {
+          if (factoryName) recordMissing(`${name}.${nName}`, "fn", factoryName);
+          nd = (0, import_core3.node)(
+            resolvedDeps,
+            (batchData, actions, ctx) => {
+              const data = batchData.map(
+                (batch3, i) => batch3 != null && batch3.length > 0 ? batch3.at(-1) : ctx.prevData[i]
+              );
+              actions.emit(data[0]);
+            },
+            { describeKind: "derived" }
+          );
+        }
+        sub.add(nd, { name: nName });
+        subCreated.set(nName, nd);
+        subPending.delete(nName);
+        subProgressed = true;
+      }
+    }
+    if (subPending.size > 0) {
+      const unresolved = [...subPending.keys()].sort().join(", ");
+      throw new Error(
+        `compileSpec: template "${ref.template}" has unresolvable deps: ${unresolved}`
+      );
+    }
+    g.mount(name, sub);
+    const outputPath = `${name}::${tmpl.output}`;
+    created.set(name, g.resolve(outputPath));
+    try {
+      const outputNode = g.resolve(outputPath);
+      outputNode.meta._templateName?.emit(ref.template);
+      outputNode.meta._templateBind?.emit(ref.bind);
+    } catch {
+    }
+  }
+  for (const fb of spec.feedback ?? []) {
+    feedback(g, fb.from, fb.to, {
+      maxIterations: fb.maxIterations
+    });
+  }
+  if (missingEntries.length > 0) {
+    if (onMissing === "error") {
+      const lines = missingEntries.map((e) => `  - ${e.path}: missing ${e.kind} "${e.name}"`);
+      throw new Error(
+        `compileSpec: ${missingEntries.length} catalog entr${missingEntries.length === 1 ? "y" : "ies"} missing \u2014 pass them via opts.catalog or set opts.onMissing to "warn"/"placeholder":
+${lines.join("\n")}`
+      );
+    }
+    if (onMissing === "warn") {
+      const warn = opts?.onWarn ?? ((m) => console.warn(m));
+      for (const e of missingEntries) {
+        warn(
+          `compileSpec: ${e.path} references missing ${e.kind} "${e.name}" \u2014 substituted placeholder`
+        );
+      }
+    }
+  }
+  return g;
+}
+var INTERNAL_META_KEYS = /* @__PURE__ */ new Set([
+  "reduction",
+  "reduction_type",
+  "_specFn",
+  "_specSource",
+  "_templateName",
+  "_templateBind",
+  "feedbackFrom",
+  "feedbackTo",
+  "_internal"
+]);
+function decompileSpec(graph) {
+  const desc = graph.describe({ detail: "spec" });
+  const metaSegment = `::${import_graph3.GRAPH_META_SEGMENT}::`;
+  const feedbackCounterPattern = /^__feedback_(?!effect_)(.+)$/;
+  const feedbackEdges = [];
+  const compoundFactoryPrefixes = /* @__PURE__ */ new Set();
+  for (const [path, nodeDesc] of Object.entries(desc.nodes)) {
+    const meta = nodeDesc.meta;
+    if (meta?.factory != null && !path.includes("::")) {
+      if (meta.factory === "proxy") continue;
+      compoundFactoryPrefixes.add(path);
+    }
+  }
+  const allPaths = new Set(Object.keys(desc.nodes));
+  for (const path of allPaths) {
+    const sepIdx = path.indexOf("::");
+    if (sepIdx <= 0) continue;
+    const parent = path.slice(0, sepIdx);
+    if (path.includes(metaSegment)) continue;
+    if (path.startsWith("__feedback_effect_") || path.startsWith("__bridge_")) continue;
+    if (compoundFactoryPrefixes.has(parent)) continue;
+    if (!allPaths.has(parent)) continue;
+    throw new Error(
+      `decompileSpec: untagged compound factory at "${parent}" (child: "${path}"). Compound factories that ship \`parent::child\` topology MUST set \`meta.factory\` on the parent so \`compileSpec\` can reconstruct the internals via the catalog. Either tag the parent (\`{ meta: factoryTag('myFactory', args) }\`) OR rename the child to use \`/\` instead of \`::\` if it's not a compound-factory internal (see COMPOSITION-GUIDE \xA738).`
+    );
+  }
+  const nodes = {};
+  for (const [path, nodeDesc] of Object.entries(desc.nodes)) {
+    if (path.includes(metaSegment)) continue;
+    const sepIdx = path.indexOf("::");
+    if (sepIdx > 0 && compoundFactoryPrefixes.has(path.slice(0, sepIdx))) continue;
+    const match = feedbackCounterPattern.exec(path);
+    if (match) {
+      const meta2 = nodeDesc.meta;
+      if (meta2?.feedbackFrom && meta2?.feedbackTo) {
+        feedbackEdges.push({
+          from: meta2.feedbackFrom,
+          to: meta2.feedbackTo,
+          ...meta2.maxIterations ? { maxIterations: meta2.maxIterations } : {}
+        });
+      }
+      continue;
+    }
+    if (nodeDesc.meta?._internal) continue;
+    if (path.startsWith("__feedback_effect_")) continue;
+    if (path.startsWith("__bridge_")) continue;
+    const meta = nodeDesc.meta;
+    let cleanedMeta = meta;
+    if (meta && Object.keys(meta).length > 0) {
+      const out = {};
+      for (const [k, v] of Object.entries(meta)) {
+        if (INTERNAL_META_KEYS.has(k)) continue;
+        out[k] = v;
+      }
+      if (out.factory === "withStatus") {
+        delete out.status;
+        delete out.error;
+      } else if (out.factory === "withBreaker") {
+        delete out.breakerState;
+      } else if (out.factory === "verifiable") {
+        delete out.sourceVersion;
+      }
+      cleanedMeta = Object.keys(out).length > 0 ? out : void 0;
+    }
+    const cleaned = { ...nodeDesc };
+    if (cleanedMeta === void 0) delete cleaned.meta;
+    else cleaned.meta = cleanedMeta;
+    nodes[path] = cleaned;
+  }
+  const result = { ...desc, nodes };
+  delete result.expand;
+  if (feedbackEdges.length > 0) result.feedback = feedbackEdges;
+  return result;
+}
+function specDiff(specA, specB) {
+  const entries = [];
+  if (specA.name !== specB.name) {
+    entries.push({
+      type: "changed",
+      path: "name",
+      detail: `"${specA.name}" \u2192 "${specB.name}"`
+    });
+  }
+  const nodesA = new Set(Object.keys(specA.nodes));
+  const nodesB = new Set(Object.keys(specB.nodes));
+  for (const name of nodesB) {
+    if (!nodesA.has(name)) {
+      const n = specB.nodes[name];
+      entries.push({
+        type: "added",
+        path: `nodes.${name}`,
+        detail: `type: ${n.type}`
+      });
+    }
+  }
+  for (const name of nodesA) {
+    if (!nodesB.has(name)) {
+      entries.push({ type: "removed", path: `nodes.${name}` });
+    }
+  }
+  for (const name of nodesA) {
+    if (!nodesB.has(name)) continue;
+    const a = specA.nodes[name];
+    const b = specB.nodes[name];
+    if (JSON.stringify(a) !== JSON.stringify(b)) {
+      const details = [];
+      if (a.type !== b.type) details.push(`type: ${a.type} \u2192 ${b.type}`);
+      if (JSON.stringify(a.deps) !== JSON.stringify(b.deps)) {
+        details.push("deps changed");
+      }
+      const aFactory = a.type === "template" ? void 0 : readFactory(a);
+      const bFactory = b.type === "template" ? void 0 : readFactory(b);
+      if (aFactory !== bFactory) {
+        details.push(`fn: ${aFactory} \u2192 ${bFactory}`);
+      }
+      const aArgs = a.type === "template" ? void 0 : readFactoryArgs(a);
+      const bArgs = b.type === "template" ? void 0 : readFactoryArgs(b);
+      if (JSON.stringify(aArgs) !== JSON.stringify(bArgs)) {
+        details.push("config changed");
+      }
+      entries.push({
+        type: "changed",
+        path: `nodes.${name}`,
+        detail: details.join("; ") || "modified"
+      });
+    }
+  }
+  const tmplA = specA.templates ?? {};
+  const tmplB = specB.templates ?? {};
+  const tmplNamesA = new Set(Object.keys(tmplA));
+  const tmplNamesB = new Set(Object.keys(tmplB));
+  for (const name of tmplNamesB) {
+    if (!tmplNamesA.has(name)) {
+      entries.push({ type: "added", path: `templates.${name}` });
+    }
+  }
+  for (const name of tmplNamesA) {
+    if (!tmplNamesB.has(name)) {
+      entries.push({ type: "removed", path: `templates.${name}` });
+    }
+  }
+  for (const name of tmplNamesA) {
+    if (!tmplNamesB.has(name)) continue;
+    if (JSON.stringify(tmplA[name]) !== JSON.stringify(tmplB[name])) {
+      entries.push({
+        type: "changed",
+        path: `templates.${name}`,
+        detail: "template definition changed"
+      });
+    }
+  }
+  const fbA = specA.feedback ?? [];
+  const fbB = specB.feedback ?? [];
+  const fbKeyA = new Set(fbA.map((e) => `${e.from}->${e.to}`));
+  const fbKeyB = new Set(fbB.map((e) => `${e.from}->${e.to}`));
+  for (const fb of fbB) {
+    const key = `${fb.from}->${fb.to}`;
+    if (!fbKeyA.has(key)) {
+      entries.push({
+        type: "added",
+        path: `feedback.${key}`,
+        detail: `maxIterations: ${fb.maxIterations ?? 10}`
+      });
+    }
+  }
+  for (const fb of fbA) {
+    const key = `${fb.from}->${fb.to}`;
+    if (!fbKeyB.has(key)) {
+      entries.push({ type: "removed", path: `feedback.${key}` });
+    }
+  }
+  for (const fb of fbA) {
+    const key = `${fb.from}->${fb.to}`;
+    const counterpart = fbB.find((b) => b.from === fb.from && b.to === fb.to);
+    if (counterpart && JSON.stringify(fb) !== JSON.stringify(counterpart)) {
+      entries.push({
+        type: "changed",
+        path: `feedback.${key}`,
+        detail: `maxIterations: ${fb.maxIterations ?? 10} \u2192 ${counterpart.maxIterations ?? 10}`
+      });
+    }
+  }
+  const added = entries.filter((e) => e.type === "added").length;
+  const removed = entries.filter((e) => e.type === "removed").length;
+  const changed = entries.filter((e) => e.type === "changed").length;
+  const parts = [];
+  if (added) parts.push(`${added} added`);
+  if (removed) parts.push(`${removed} removed`);
+  if (changed) parts.push(`${changed} changed`);
+  const summary = parts.length > 0 ? parts.join(", ") : "no changes";
+  return { entries, summary };
+}
+var LLM_COMPOSE_SYSTEM_PROMPT = `You are a graph architect for GraphReFly, a reactive graph protocol.
+
+Given a natural-language description, produce a JSON GraphSpec with this structure:
+
+{
+  "name": "<graph_name>",
+  "nodes": {
+    "<node_name>": {
+      "type": "state" | "derived" | "producer" | "effect",
+      "deps": ["<dep_node_name>", ...],
+      "value": <initial_value>,
+      "meta": {
+        "factory": "<catalog_factory_name>",
+        "factoryArgs": { ... },
+        "description": "<purpose>"
+      }
+    },
+    "<template_instance>": {
+      "type": "template",
+      "template": "<template_name>",
+      "bind": { "$param": "node_name" }
+    }
+  },
+  "templates": {
+    "<template_name>": {
+      "params": ["$param1", "$param2"],
+      "nodes": { ... },
+      "output": "<output_node>"
+    }
+  },
+  "feedback": [
+    { "from": "<condition_node>", "to": "<state_node>", "maxIterations": 10 }
+  ]
+}
+
+Rules:
+- "state" nodes hold user/LLM-writable values (knobs). Stamp the initial value
+  in "meta.factoryArgs.initial" (or as the top-level "value" field \u2014 both work).
+- "derived" nodes compute from deps using a catalog function named in
+  "meta.factory"; pass any config via "meta.factoryArgs".
+- "effect" nodes produce side effects from deps; same meta.factory shape as derived.
+- "producer" nodes generate values from a catalog source named in "meta.factory";
+  pass any config via "meta.factoryArgs".
+- Use "templates" when the same subgraph pattern repeats (e.g., per-source resilience).
+- Use "feedback" for bounded cycles where a derived value writes back to a state node.
+- meta.description is required for every node.
+- Return ONLY valid JSON, no markdown fences or commentary.`;
+function stripFences(text) {
+  const match = text.match(/^```(?:json)?\s*([\s\S]*?)\s*```[\s\S]*$/);
+  return match ? match[1] : text;
+}
+async function llmCompose(problem, adapter, opts) {
+  let systemPrompt = LLM_COMPOSE_SYSTEM_PROMPT;
+  const catalogPrompt = opts?.catalogDescription ?? (opts?.catalog ? generateCatalogPrompt(opts.catalog) : void 0);
+  if (catalogPrompt) {
+    systemPrompt += `
+
+Available catalog (use ONLY these names):
+${catalogPrompt}`;
+  }
+  if (opts?.systemPromptExtra) {
+    systemPrompt += `
+
+${opts.systemPromptExtra}`;
+  }
+  const messages = [
+    { role: "system", content: systemPrompt },
+    { role: "user", content: problem }
+  ];
+  const rawResult = adapter.invoke(messages, {
+    model: opts?.model,
+    temperature: opts?.temperature ?? 0,
+    maxTokens: opts?.maxTokens
+  });
+  const response = await rawResult;
+  let content = response.content.trim();
+  if (content.startsWith("```")) {
+    content = stripFences(content);
+  }
+  let parsed;
+  try {
+    parsed = JSON.parse(content);
+  } catch {
+    throw new Error(`llmCompose: LLM response is not valid JSON: ${content.slice(0, 200)}`);
+  }
+  const validation = validateSpec(parsed);
+  if (!validation.valid) {
+    throw new Error(`llmCompose: invalid GraphSpec:
+${validation.errors.join("\n")}`);
+  }
+  let spec = parsed;
+  if (opts?.catalog) {
+    const maxRefine = opts.maxAutoRefine ?? 0;
+    for (let attempt = 0; attempt <= maxRefine; attempt++) {
+      const catalogValidation = validateSpecAgainstCatalog(spec, opts.catalog);
+      if (catalogValidation.valid) break;
+      if (attempt === maxRefine) {
+        throw new Error(
+          `llmCompose: catalog validation failed after ${maxRefine} refine attempts:
+${catalogValidation.errors.join("\n")}`
+        );
+      }
+      spec = await llmRefine(
+        spec,
+        `Fix these catalog errors:
+${catalogValidation.errors.join("\n")}
+
+Use ONLY functions and sources from the catalog.`,
+        adapter,
+        { ...opts, catalogDescription: catalogPrompt }
+      );
+    }
+  }
+  return spec;
+}
+async function llmRefine(currentSpec, feedback2, adapter, opts) {
+  let systemPrompt = LLM_COMPOSE_SYSTEM_PROMPT;
+  if (opts?.catalogDescription) {
+    systemPrompt += `
+
+Available catalog:
+${opts.catalogDescription}`;
+  }
+  if (opts?.systemPromptExtra) {
+    systemPrompt += `
+
+${opts.systemPromptExtra}`;
+  }
+  const messages = [
+    { role: "system", content: systemPrompt },
+    {
+      role: "user",
+      content: `Current GraphSpec:
+${JSON.stringify(currentSpec, null, 2)}
+
+Modification request: ${feedback2}
+
+Return the complete modified GraphSpec as JSON.`
+    }
+  ];
+  const rawResult = adapter.invoke(messages, {
+    model: opts?.model,
+    temperature: opts?.temperature ?? 0,
+    maxTokens: opts?.maxTokens
+  });
+  const response = await rawResult;
+  let content = response.content.trim();
+  if (content.startsWith("```")) {
+    content = stripFences(content);
+  }
+  let parsed;
+  try {
+    parsed = JSON.parse(content);
+  } catch {
+    throw new Error(`llmRefine: LLM response is not valid JSON: ${content.slice(0, 200)}`);
+  }
+  const validation = validateSpec(parsed);
+  if (!validation.valid) {
+    throw new Error(`llmRefine: invalid GraphSpec:
+${validation.errors.join("\n")}`);
+  }
+  return parsed;
+}
+//# sourceMappingURL=index.cjs.map