@neat.is/core 0.9.2-dev.20260821 → 0.9.2

package/dist/{chunk-RQQUI3NQ.js → chunk-HD5X5TWY.js}

@@ -3096,11 +3096,11 @@ function actixAttributeRoute(attrItem, out) {
   if (!nameNode) return;
   const macro = nameNode.type === "identifier" ? nameNode.text : nameNode.type === "scoped_identifier" ? nameNode.childForFieldName("name")?.text ?? null : null;
   if (!macro) return;
-  const tokens = attr.childForFieldName("arguments");
-  if (!tokens || tokens.type !== "token_tree") return;
+  const tokens2 = attr.childForFieldName("arguments");
+  if (!tokens2 || tokens2.type !== "token_tree") return;
   const strings = [];
-  for (let i = 0; i < tokens.namedChildCount; i++) {
-    const s = rustStringContent(tokens.namedChild(i));
+  for (let i = 0; i < tokens2.namedChildCount; i++) {
+    const s = rustStringContent(tokens2.namedChild(i));
     if (s !== null) strings.push(s);
   }
   const pathStr = strings[0];
@@ -4992,29 +4992,29 @@ function promoteFrontierNodes(graph, opts = {}) {
     toPromote.push({ frontierId: id, serviceId: target });
   });
   let promoted = 0;
-  for (const { frontierId: frontierId2, serviceId: serviceId15 } of toPromote) {
+  for (const { frontierId: frontierId2, serviceId: serviceId16 } of toPromote) {
     if (opts.policies && opts.policies.length > 0 && opts.policyCtx) {
       const gate = canPromoteFrontier(graph, frontierId2, opts.policies, opts.policyCtx);
       if (!gate.allowed) {
         continue;
       }
     }
-    rewireFrontierEdges(graph, frontierId2, serviceId15);
+    rewireFrontierEdges(graph, frontierId2, serviceId16);
     graph.dropNode(frontierId2);
     promoted++;
   }
   return promoted;
 }
-function rewireFrontierEdges(graph, frontierId2, serviceId15) {
+function rewireFrontierEdges(graph, frontierId2, serviceId16) {
   const inbound = [...graph.inboundEdges(frontierId2)];
   const outbound = [...graph.outboundEdges(frontierId2)];
   for (const edgeId of inbound) {
     const edge = graph.getEdgeAttributes(edgeId);
-    rebuildEdge(graph, edge, edge.source, serviceId15, edgeId);
+    rebuildEdge(graph, edge, edge.source, serviceId16, edgeId);
   }
   for (const edgeId of outbound) {
     const edge = graph.getEdgeAttributes(edgeId);
-    rebuildEdge(graph, edge, serviceId15, edge.target, edgeId);
+    rebuildEdge(graph, edge, serviceId16, edge.target, edgeId);
   }
 }
 function rebuildEdge(graph, edge, newSource, newTarget, oldEdgeId) {
@@ -5373,7 +5373,7 @@ function databaseRootCauseShape(graph, origin, walk10) {
   for (const id of walk10.path) {
     const owner = resolveOwningService(graph, id);
     if (!owner) continue;
-    const { id: serviceId15, svc } = owner;
+    const { id: serviceId16, svc } = owner;
     const deps = svc.dependencies ?? {};
     for (const pair of candidatePairs) {
       const declared = deps[pair.driver];
@@ -5386,7 +5386,7 @@ function databaseRootCauseShape(graph, origin, walk10) {
       );
       if (!result.compatible) {
         return {
-          rootCauseNode: serviceId15,
+          rootCauseNode: serviceId16,
           rootCauseReason: result.reason ?? "incompatible driver",
           ...result.minDriverVersion ? {
             fixRecommendation: `Upgrade ${svc.name} ${pair.driver} driver to >= ${result.minDriverVersion}`
@@ -5401,7 +5401,7 @@ function serviceRootCauseShape(graph, _origin, walk10) {
   for (const id of walk10.path) {
     const owner = resolveOwningService(graph, id);
     if (!owner) continue;
-    const { id: serviceId15, svc } = owner;
+    const { id: serviceId16, svc } = owner;
     const deps = svc.dependencies ?? {};
     const serviceNodeEngine = svc.nodeEngine;
     for (const constraint of nodeEngineConstraints()) {
@@ -5410,7 +5410,7 @@ function serviceRootCauseShape(graph, _origin, walk10) {
       const result = checkNodeEngineConstraint(constraint, declared, serviceNodeEngine);
       if (!result.compatible && result.reason) {
         return {
-          rootCauseNode: serviceId15,
+          rootCauseNode: serviceId16,
           rootCauseReason: result.reason,
           ...result.requiredNodeVersion ? {
             fixRecommendation: `Bump ${svc.name}'s engines.node to >= ${result.requiredNodeVersion}`
@@ -5425,7 +5425,7 @@ function serviceRootCauseShape(graph, _origin, walk10) {
       const result = checkPackageConflict(conflict, declared, requiredDeclared);
       if (!result.compatible && result.reason) {
         return {
-          rootCauseNode: serviceId15,
+          rootCauseNode: serviceId16,
           rootCauseReason: result.reason,
           fixRecommendation: `Upgrade ${svc.name}'s ${conflict.requires.name} to >= ${conflict.requires.minVersion}`
         };
@@ -5530,9 +5530,9 @@ function rootCauseFromIncidents(nodeId, incidents, errorEvent) {
 function isFailingCallEdge(e) {
   return e.type === EdgeType6.CALLS && (e.signal?.errorCount ?? 0) > 0;
 }
-function callSourcesForService(graph, serviceId15) {
-  const ids = [serviceId15];
-  for (const edgeId of graph.outboundEdges(serviceId15)) {
+function callSourcesForService(graph, serviceId16) {
+  const ids = [serviceId16];
+  for (const edgeId of graph.outboundEdges(serviceId16)) {
     const e = graph.getEdgeAttributes(edgeId);
     if (e.type !== EdgeType6.CONTAINS) continue;
     const tgt = graph.getNodeAttributes(e.target);
@@ -5556,9 +5556,9 @@ function failingCallDominates(e, id, curEdge, curId) {
   }
   return id < curId;
 }
-function dominantFailingCall(graph, serviceId15, visited) {
+function dominantFailingCall(graph, serviceId16, visited) {
   let best = null;
-  for (const src of callSourcesForService(graph, serviceId15)) {
+  for (const src of callSourcesForService(graph, serviceId16)) {
     for (const edgeId of graph.outboundEdges(src)) {
       const e = graph.getEdgeAttributes(edgeId);
       if (!isFailingCallEdge(e)) continue;
@@ -5597,9 +5597,9 @@ function staleCallDominates(e, id, curEdge, curId) {
   if (ev !== cv) return ev > cv;
   return id < curId;
 }
-function dominantStaleCall(graph, serviceId15, visited) {
+function dominantStaleCall(graph, serviceId16, visited) {
   const bestByCallee = /* @__PURE__ */ new Map();
-  for (const src of callSourcesForService(graph, serviceId15)) {
+  for (const src of callSourcesForService(graph, serviceId16)) {
     for (const edgeId of graph.outboundEdges(src)) {
       const e = graph.getEdgeAttributes(edgeId);
       if (e.type !== EdgeType6.CALLS) continue;
@@ -7059,9 +7059,9 @@ var K8S_KINDS_WITH_HOSTNAMES = /* @__PURE__ */ new Set([
   "StatefulSet",
   "DaemonSet"
 ]);
-function addAliases(graph, serviceId15, candidates) {
-  if (!graph.hasNode(serviceId15)) return;
-  const node = graph.getNodeAttributes(serviceId15);
+function addAliases(graph, serviceId16, candidates) {
+  if (!graph.hasNode(serviceId16)) return;
+  const node = graph.getNodeAttributes(serviceId16);
   if (node.type !== NodeType16.ServiceNode) return;
   const set = new Set(node.aliases ?? []);
   for (const c of candidates) {
@@ -7071,7 +7071,7 @@ function addAliases(graph, serviceId15, candidates) {
   }
   if (set.size === 0) return;
   const updated = { ...node, aliases: [...set].sort() };
-  graph.replaceNodeAttributes(serviceId15, updated);
+  graph.replaceNodeAttributes(serviceId16, updated);
 }
 function indexServicesByName(services) {
   const map = /* @__PURE__ */ new Map();
@@ -7104,12 +7104,12 @@ async function collectComposeAliases(graph, scanPath, serviceIndex) {
   }
   if (!compose?.services) return;
   for (const [composeName, svc] of Object.entries(compose.services)) {
-    const serviceId15 = serviceIndex.get(composeName);
-    if (!serviceId15) continue;
+    const serviceId16 = serviceIndex.get(composeName);
+    if (!serviceId16) continue;
     const aliases = /* @__PURE__ */ new Set([composeName]);
     if (svc.container_name) aliases.add(svc.container_name);
     if (svc.hostname) aliases.add(svc.hostname);
-    addAliases(graph, serviceId15, aliases);
+    addAliases(graph, serviceId16, aliases);
   }
 }
 var LABEL_KEYS = /* @__PURE__ */ new Set([
@@ -16331,6 +16331,638 @@ function queryLogEntries(opts) {
   return merged;
 }
 
+// src/ask.ts
+import { AskResultSchema, NodeType as NodeType32, Provenance as Provenance26, serviceId as serviceId14 } from "@neat.is/types";
+var DEFAULT_MAX_NODES = 3;
+var MAX_FACTS_PER_SECTION = 6;
+var INTENT_RULES = [
+  {
+    intent: "root-cause",
+    test: /\b(why|root[\s-]?cause|failing|fail(?:s|ed)?|breaking|broke(?:n)?|crash(?:ing|ed)?|throw(?:ing|s)?|culprit|5\d\d)\b/
+  },
+  {
+    intent: "blast-radius",
+    test: /\b(blast|break[\s-]?if|breaks[\s-]?if|impact|downstream|dependents?|redeploy|who\s+(?:uses|calls|depends)|what\s+depends\s+on|affect(?:s|ed)?)\b/
+  },
+  {
+    intent: "divergence",
+    test: /\b(diverg\w*|weird|mismatch|drift|out\s+of\s+sync|inconsistent|disagree\w*|declared\s+vs|anything\s+wrong)\b/
+  },
+  {
+    intent: "incidents",
+    test: /\b(incidents?|recent\s+(?:errors?|failures?)|error\s+history|failure\s+history)\b/
+  },
+  {
+    intent: "observed",
+    test: /\b(at\s+runtime|in\s+prod(?:uction)?|actually\s+call\w*|really\s+call\w*|observed|runtime\s+traffic)\b/
+  },
+  {
+    intent: "dependencies",
+    test: /\b(depend\w*|calls?|uses?|imports?|relies\s+on|needs?)\b/
+  }
+];
+function classifyIntent(question) {
+  const q = question.toLowerCase();
+  for (const rule of INTENT_RULES) {
+    if (rule.test.test(q)) return rule.intent;
+  }
+  return "overview";
+}
+var STOPWORDS = /* @__PURE__ */ new Set([
+  "the",
+  "a",
+  "an",
+  "is",
+  "are",
+  "was",
+  "were",
+  "be",
+  "been",
+  "being",
+  "of",
+  "to",
+  "in",
+  "on",
+  "at",
+  "by",
+  "for",
+  "with",
+  "and",
+  "or",
+  "but",
+  "if",
+  "as",
+  "this",
+  "that",
+  "these",
+  "those",
+  "it",
+  "its",
+  "do",
+  "does",
+  "did",
+  "has",
+  "have",
+  "had",
+  "what",
+  "which",
+  "who",
+  "whom",
+  "how",
+  "when",
+  "where",
+  "my",
+  "me",
+  "i",
+  "we",
+  "you",
+  "they",
+  "them",
+  "from",
+  "into",
+  "about",
+  "would",
+  "will",
+  "can",
+  "could",
+  "should",
+  "anything",
+  "everything",
+  "something",
+  "all",
+  "any",
+  "some",
+  "no",
+  "not",
+  "so",
+  "up",
+  "out",
+  "over",
+  "get",
+  "got",
+  "show",
+  "tell",
+  "explain",
+  "find",
+  "give",
+  "happen",
+  "happens",
+  "happening",
+  "here",
+  "there",
+  "system",
+  "code",
+  "service",
+  "node",
+  "graph"
+]);
+var INTENT_WORDS = /* @__PURE__ */ new Set([
+  "why",
+  "root",
+  "cause",
+  "failing",
+  "fail",
+  "fails",
+  "failed",
+  "breaking",
+  "broke",
+  "broken",
+  "crash",
+  "crashing",
+  "crashed",
+  "throw",
+  "throwing",
+  "throws",
+  "culprit",
+  "blast",
+  "radius",
+  "break",
+  "breaks",
+  "impact",
+  "downstream",
+  "dependent",
+  "dependents",
+  "redeploy",
+  "affect",
+  "affects",
+  "affected",
+  "diverge",
+  "divergence",
+  "divergences",
+  "weird",
+  "mismatch",
+  "drift",
+  "inconsistent",
+  "disagree",
+  "declared",
+  "observed",
+  "incident",
+  "incidents",
+  "recent",
+  "errors",
+  "error",
+  "failures",
+  "failure",
+  "history",
+  "runtime",
+  "production",
+  "prod",
+  "traffic",
+  "actually",
+  "really",
+  "depend",
+  "depends",
+  "dependency",
+  "dependencies",
+  "call",
+  "calls",
+  "use",
+  "uses",
+  "using",
+  "import",
+  "imports",
+  "relies",
+  "rely",
+  "needs",
+  "need",
+  "sync"
+]);
+function tokens(input) {
+  const spaced = input.replace(/([a-z0-9])([A-Z])/g, "$1 $2");
+  return (spaced.toLowerCase().match(/[a-z0-9]+/g) ?? []).filter((t) => t.length >= 2);
+}
+function queryTokens(question) {
+  const seen = /* @__PURE__ */ new Set();
+  const out = [];
+  for (const t of tokens(question)) {
+    if (STOPWORDS.has(t) || INTENT_WORDS.has(t)) continue;
+    if (seen.has(t)) continue;
+    seen.add(t);
+    out.push(t);
+  }
+  return out;
+}
+function nodeName(node) {
+  return node.name ?? node.id;
+}
+function idBody(id) {
+  const colon = id.indexOf(":");
+  return colon >= 0 ? id.slice(colon + 1) : id;
+}
+var EMBED_MIN_SCORE = 0.35;
+async function resolveEntities(graph, question, searchIndex, maxNodes) {
+  const qTokens = queryTokens(question);
+  const normalized = question.toLowerCase();
+  const best = /* @__PURE__ */ new Map();
+  const consider = (cand) => {
+    const cur = best.get(cand.nodeId);
+    if (!cur || cand.score > cur.score) best.set(cand.nodeId, cand);
+  };
+  graph.forEachNode((id, attrs) => {
+    const node = attrs;
+    if (node.type === NodeType32.FrontierNode) return;
+    const name = nodeName(node);
+    const body = idBody(id);
+    const labelTokens = /* @__PURE__ */ new Set([...tokens(body), ...tokens(name)]);
+    if (labelTokens.size === 0) return;
+    let matched = 0;
+    for (const t of qTokens) if (labelTokens.has(t)) matched += 1;
+    const named = body.length >= 2 && normalized.includes(body.toLowerCase()) || name.length >= 2 && normalized.includes(name.toLowerCase());
+    if (matched === 0 && !named) return;
+    const coverage = qTokens.length > 0 ? matched / qTokens.length : 0;
+    const via = named ? "id" : matched > 0 && tokens(name).some((t) => qTokens.includes(t)) ? "label" : "token";
+    const score = named ? Math.max(0.9, coverage) : Math.min(0.85, 0.3 + 0.7 * coverage);
+    consider({ nodeId: id, label: name, via, score: Math.min(1, score) });
+  });
+  if (searchIndex) {
+    try {
+      const res = await searchIndex.search(question, 10);
+      if (res.provider !== "substring") {
+        for (const m of res.matches) {
+          if (m.node.type === NodeType32.FrontierNode) continue;
+          const already = best.get(m.node.id);
+          if (!already && m.score < EMBED_MIN_SCORE) continue;
+          consider({
+            nodeId: m.node.id,
+            label: nodeName(m.node),
+            via: "embedding",
+            score: Math.max(0, Math.min(1, m.score))
+          });
+        }
+      }
+    } catch {
+    }
+  }
+  const viaRank = { id: 3, label: 2, token: 1, embedding: 0 };
+  return [...best.values()].sort(
+    (a, b) => b.score - a.score || viaRank[b.via] - viaRank[a.via] || a.nodeId.localeCompare(b.nodeId)
+  ).slice(0, maxNodes).map((s) => ({ nodeId: s.nodeId, label: s.label, via: s.via, score: Number(s.score.toFixed(3)) }));
+}
+function incidentsForNode(nodeId, incidents) {
+  if (!incidents || incidents.length === 0) return [];
+  const svc = nodeId.replace(/^service:/, "");
+  return incidents.filter((e) => e.affectedNode === nodeId || e.service === svc);
+}
+function edgeSignalNote(e) {
+  const bits = [];
+  if (e.signal) {
+    bits.push(`${e.signal.spanCount} spans`);
+    if (e.signal.errorCount > 0) bits.push(`${e.signal.errorCount} errors`);
+    if (e.signal.latencyMs?.p95 !== void 0) bits.push(`p95 ${Math.round(e.signal.latencyMs.p95)}ms`);
+  } else if (e.callCount !== void 0) {
+    bits.push(`${e.callCount} calls`);
+  }
+  return bits.length ? ` (${bits.join(", ")})` : "";
+}
+function buildRootCauseSection(graph, node, incidents, now) {
+  const result = getRootCause(graph, node, void 0, incidents, { now });
+  if (!result) return null;
+  const lastProv = result.edgeProvenances[result.edgeProvenances.length - 1] ?? Provenance26.OBSERVED;
+  const facts = [
+    {
+      text: `Root cause: ${result.rootCauseNode} \u2014 ${result.rootCauseReason}`,
+      provenance: lastProv,
+      confidence: result.confidence
+    }
+  ];
+  const candidates = result.candidates ?? [];
+  for (const c of candidates.slice(0, 3)) {
+    facts.push({
+      text: `Candidate ${c.node} \u2014 ${c.classification}: ${c.reason}`,
+      ...c.provenance ? { provenance: c.provenance } : {},
+      confidence: c.confidence
+    });
+  }
+  if (result.traversalPath.length > 1) {
+    facts.push({ text: `Traversal: ${result.traversalPath.join(" \u2190 ")}` });
+  }
+  if (result.fixRecommendation) {
+    facts.push({ text: `Recommended fix: ${result.fixRecommendation}` });
+  }
+  return { heading: "Root cause (navigation)", facts: facts.slice(0, MAX_FACTS_PER_SECTION) };
+}
+function buildDependenciesSection(graph, node) {
+  const result = getTransitiveDependencies(graph, node, 2);
+  if (result.total === 0) return null;
+  const facts = result.dependencies.slice(0, MAX_FACTS_PER_SECTION).map((d) => ({
+    text: `${d.nodeId} \u2014 ${d.edgeType} (distance ${d.distance})`,
+    // Per-fact provenance: the transitive walk mixes EXTRACTED and OBSERVED
+    // edges, so the tag is on the fact, not asserted for the whole section.
+    provenance: d.provenance
+  }));
+  return { heading: "Dependencies", facts };
+}
+function buildObservedSection(graph, node) {
+  const result = getObservedDependencies(graph, node);
+  const facts = [];
+  for (const e of result.dependencies.slice(0, MAX_FACTS_PER_SECTION)) {
+    const via = e.source !== node ? ` via ${e.source}` : "";
+    facts.push({
+      text: `calls ${e.target}${via}${edgeSignalNote(e)}`,
+      provenance: e.provenance,
+      confidence: confidenceForEdge(e)
+    });
+  }
+  if (facts.length === 0) {
+    if (result.observed && result.inboundObservedCount > 0) {
+      facts.push({
+        text: `no outbound runtime calls, but OTel observed ${result.inboundObservedCount} inbound call path${result.inboundObservedCount === 1 ? "" : "s"} \u2014 a pure receiver`,
+        provenance: Provenance26.OBSERVED
+      });
+    } else {
+      return null;
+    }
+  }
+  return { heading: "Runtime dependencies (OBSERVED)", facts };
+}
+function buildBlastSection(graph, node) {
+  const result = getBlastRadius(graph, node);
+  if (result.totalAffected === 0) return null;
+  const facts = result.affectedNodes.slice(0, MAX_FACTS_PER_SECTION).map((n) => ({
+    text: `${n.nodeId} (distance ${n.distance})`,
+    provenance: n.edgeProvenance,
+    confidence: n.confidence
+  }));
+  return {
+    heading: `Blast radius \u2014 ${result.totalAffected} dependent${result.totalAffected === 1 ? "" : "s"}`,
+    facts
+  };
+}
+function buildIncidentsSection(node, incidents) {
+  const relevant = incidentsForNode(node, incidents);
+  if (relevant.length === 0) return null;
+  const ordered = [...relevant].sort((a, b) => b.timestamp.localeCompare(a.timestamp)).slice(0, 4);
+  const facts = ordered.map((ev) => ({
+    text: `${ev.timestamp} \u2014 ${ev.service}: ${ev.errorMessage}`,
+    // ErrorEvents are observation records — OBSERVED by definition.
+    provenance: Provenance26.OBSERVED
+  }));
+  return { heading: `Recent incidents (OBSERVED) \u2014 ${relevant.length} recorded`, facts };
+}
+function divergenceLine(d) {
+  if ((d.type === "missing-observed" || d.type === "missing-extracted") && d.column) {
+    return `[${d.type}] ${d.table ?? d.source} column ${d.column} \u2014 ${d.reason}`;
+  }
+  return `[${d.type}] ${d.source} \u2192 ${d.target} \u2014 ${d.reason}`;
+}
+function buildDivergenceSection(graph, node) {
+  const result = computeDivergences(graph, { node });
+  if (result.totalAffected === 0) return null;
+  const facts = result.divergences.slice(0, MAX_FACTS_PER_SECTION).map((d) => ({
+    text: divergenceLine(d),
+    confidence: d.confidence
+    // A divergence is composite by construction (EXTRACTED vs OBSERVED), so it
+    // carries no single provenance — the fact leaves it unset.
+  }));
+  return {
+    heading: `Divergences (EXTRACTED vs OBSERVED) \u2014 ${result.totalAffected}`,
+    facts
+  };
+}
+function buildGlobalDivergenceSection(graph) {
+  const result = computeDivergences(graph);
+  if (result.totalAffected === 0) {
+    return {
+      heading: "Divergences (EXTRACTED vs OBSERVED)",
+      facts: [{ text: "None \u2014 declared code and observed runtime agree across the graph." }]
+    };
+  }
+  const facts = result.divergences.slice(0, MAX_FACTS_PER_SECTION).map((d) => ({
+    text: divergenceLine(d),
+    confidence: d.confidence
+    // Composite by construction (EXTRACTED vs OBSERVED), so no single provenance.
+  }));
+  return {
+    heading: `Divergences (EXTRACTED vs OBSERVED) \u2014 ${result.totalAffected}`,
+    facts
+  };
+}
+function buildGlobalIncidentsSection(incidents) {
+  if (!incidents || incidents.length === 0) {
+    return {
+      heading: "Incidents across the system",
+      facts: [{ text: "None recorded \u2014 the OBSERVED incident store is empty." }]
+    };
+  }
+  const byKey = /* @__PURE__ */ new Map();
+  for (const ev of incidents) {
+    const key = ev.affectedNode || serviceId14(ev.service);
+    const cur = byKey.get(key);
+    if (!cur) {
+      byKey.set(key, { key, count: 1, latest: ev.timestamp, sampleMsg: ev.errorMessage });
+    } else {
+      cur.count += 1;
+      if (ev.timestamp > cur.latest) {
+        cur.latest = ev.timestamp;
+        cur.sampleMsg = ev.errorMessage;
+      }
+    }
+  }
+  const rows = [...byKey.values()].sort((a, b) => b.count - a.count || b.latest.localeCompare(a.latest) || a.key.localeCompare(b.key)).slice(0, MAX_FACTS_PER_SECTION);
+  const facts = rows.map((r) => ({
+    text: `${r.key} \u2014 ${r.count} incident${r.count === 1 ? "" : "s"}, latest ${r.latest}: ${r.sampleMsg}`,
+    provenance: Provenance26.OBSERVED
+  }));
+  return {
+    heading: `Incidents across the system \u2014 ${incidents.length} recorded`,
+    facts
+  };
+}
+function buildOverviewSections(graph, incidents) {
+  const nodeByType = /* @__PURE__ */ new Map();
+  const services = [];
+  graph.forEachNode((_id, attrs) => {
+    const node = attrs;
+    nodeByType.set(node.type, (nodeByType.get(node.type) ?? 0) + 1);
+    if (node.type === NodeType32.ServiceNode) services.push(node.id);
+  });
+  const edgeByProv = /* @__PURE__ */ new Map();
+  graph.forEachEdge((_id, attrs) => {
+    const p = attrs.provenance;
+    edgeByProv.set(p, (edgeByProv.get(p) ?? 0) + 1);
+  });
+  const sections = [];
+  const count = (t) => nodeByType.get(t) ?? 0;
+  const shapeFacts = [
+    { text: `${graph.order} nodes, ${graph.size} edges` },
+    {
+      text: `${count(NodeType32.ServiceNode)} services, ${count(NodeType32.FileNode)} files, ${count(NodeType32.SymbolNode)} symbols, ${count(NodeType32.DatabaseNode)} databases`
+    }
+  ];
+  for (const p of [Provenance26.EXTRACTED, Provenance26.OBSERVED, Provenance26.INFERRED, Provenance26.STALE]) {
+    const n = edgeByProv.get(p) ?? 0;
+    if (n > 0) shapeFacts.push({ text: `${n} ${p} edge${n === 1 ? "" : "s"}`, provenance: p });
+  }
+  sections.push({ heading: "System shape", facts: shapeFacts });
+  const depCounts = services.map((s) => ({ s, n: getTransitiveDependencies(graph, s, 1).total })).filter((r) => r.n > 0).sort((a, b) => b.n - a.n || a.s.localeCompare(b.s)).slice(0, MAX_FACTS_PER_SECTION);
+  if (depCounts.length > 0) {
+    sections.push({
+      heading: "Busiest services (by direct dependencies)",
+      facts: depCounts.map((r) => ({
+        text: `${r.s} \u2014 ${r.n} direct dependenc${r.n === 1 ? "y" : "ies"}`
+      }))
+    });
+  }
+  if (incidents && incidents.length > 0) {
+    const incCount = /* @__PURE__ */ new Map();
+    for (const ev of incidents) {
+      const key = ev.affectedNode || serviceId14(ev.service);
+      incCount.set(key, (incCount.get(key) ?? 0) + 1);
+    }
+    const top = [...incCount.entries()].sort((a, b) => b[1] - a[1] || a[0].localeCompare(b[0])).slice(0, MAX_FACTS_PER_SECTION);
+    sections.push({
+      heading: `Nodes with incidents \u2014 ${incidents.length} recorded`,
+      facts: top.map(([k, n]) => ({
+        text: `${k} \u2014 ${n} incident${n === 1 ? "" : "s"}`,
+        provenance: Provenance26.OBSERVED
+      }))
+    });
+  }
+  const div = computeDivergences(graph);
+  sections.push({
+    heading: "Divergences",
+    facts: [
+      {
+        text: div.totalAffected === 0 ? "None \u2014 declared code and observed runtime agree across the graph." : `${div.totalAffected} divergence${div.totalAffected === 1 ? "" : "s"} between declared code and observed runtime \u2014 ask "are there any divergences?" for the list.`
+      }
+    ]
+  });
+  return sections;
+}
+function buildGlobalSections(intent, graph, incidents) {
+  switch (intent) {
+    case "divergence":
+      return [buildGlobalDivergenceSection(graph)];
+    case "incidents":
+      return [buildGlobalIncidentsSection(incidents)];
+    case "overview":
+      return buildOverviewSections(graph, incidents);
+    default:
+      return null;
+  }
+}
+var SECTION_ORDER = {
+  "root-cause": ["root-cause", "incidents", "blast", "observed", "divergence"],
+  "blast-radius": ["blast", "dependencies", "observed", "incidents"],
+  dependencies: ["dependencies", "observed", "blast"],
+  observed: ["observed", "dependencies", "incidents"],
+  incidents: ["incidents", "root-cause", "observed"],
+  divergence: ["divergence", "observed", "dependencies", "incidents"],
+  overview: ["dependencies", "observed", "blast", "incidents", "divergence"]
+};
+function buildSection(kind, graph, node, incidents, now) {
+  switch (kind) {
+    case "root-cause":
+      return buildRootCauseSection(graph, node, incidents, now);
+    case "dependencies":
+      return buildDependenciesSection(graph, node);
+    case "observed":
+      return buildObservedSection(graph, node);
+    case "blast":
+      return buildBlastSection(graph, node);
+    case "incidents":
+      return buildIncidentsSection(node, incidents);
+    case "divergence":
+      return buildDivergenceSection(graph, node);
+  }
+}
+function summarizeGlobal(intent, sections) {
+  const lead = sections[0];
+  switch (intent) {
+    case "divergence": {
+      const none = lead?.facts[0]?.text.startsWith("None") ?? true;
+      return none ? "No divergences across the graph \u2014 declared code and observed runtime agree." : `${lead.heading} across the graph, highest-confidence first below.`;
+    }
+    case "incidents": {
+      const none = lead?.facts[0]?.text.startsWith("None") ?? true;
+      return none ? "No incidents recorded across the system \u2014 the OBSERVED incident store is empty." : `${lead.heading}, aggregated by node below.`;
+    }
+    case "overview":
+    default:
+      return `System overview across the whole graph: ${sections.length} view${sections.length === 1 ? "" : "s"} below \u2014 shape (nodes/edges by provenance), busiest services, incidents, and divergences.`;
+  }
+}
+function summarize(question, intent, matched, primary, sections, scope) {
+  if (scope === "global") {
+    return summarizeGlobal(intent, sections);
+  }
+  if (!primary) {
+    return `Nothing in "${question}" resolved to a node in the graph. Name a service, file, route, or table \u2014 e.g. \`ask "what does <service> depend on?"\`. For a graph-wide look, ask for an overview, divergences, or incidents.`;
+  }
+  const lead = sections[0];
+  const others = matched.slice(1);
+  const alsoNote = others.length ? ` Also matched: ${others.map((m) => m.nodeId).join(", ")}.` : "";
+  let core;
+  switch (intent) {
+    case "root-cause": {
+      const rc = sections.find((s) => s.heading === "Root cause (navigation)");
+      if (rc) {
+        core = rc.facts[0]?.text ?? "";
+      } else if (lead) {
+        core = `No root cause surfaced for ${primary} \u2014 it may be healthy, or the failure isn't recorded. Nearest context: ${lead.heading.toLowerCase()}.`;
+      } else {
+        core = `No root cause surfaced for ${primary} \u2014 it may be healthy.`;
+      }
+      break;
+    }
+    case "blast-radius":
+      core = lead ? `${lead.heading} of ${primary}.` : `${primary} has no dependents \u2014 nothing else would break if it failed.`;
+      break;
+    case "dependencies":
+      core = lead ? `${primary}: ${lead.heading.toLowerCase()} listed below.` : `${primary} has no declared dependencies in the graph.`;
+      break;
+    case "observed":
+      core = lead ? `${primary} at runtime: ${lead.facts.length} OBSERVED fact${lead.facts.length === 1 ? "" : "s"}.` : `No runtime traffic OBSERVED for ${primary}.`;
+      break;
+    case "incidents":
+      core = lead ? `${primary}: ${lead.heading.toLowerCase()}.` : `No incidents recorded against ${primary}.`;
+      break;
+    case "divergence":
+      core = lead ? `${lead.heading} involving ${primary}.` : `No divergences involve ${primary} \u2014 declared and observed agree here.`;
+      break;
+    default:
+      core = `${primary}: ${sections.length} view${sections.length === 1 ? "" : "s"} of its fused local context below.`;
+  }
+  return `${core}${alsoNote}`;
+}
+async function askGraph(graph, question, opts = {}) {
+  const now = opts.now ?? Date.now();
+  const maxNodes = opts.maxNodes ?? DEFAULT_MAX_NODES;
+  const intent = classifyIntent(question);
+  const matched = await resolveEntities(graph, question, opts.searchIndex, maxNodes);
+  const primary = matched[0]?.nodeId;
+  const sections = [];
+  let scope;
+  if (primary) {
+    scope = "node";
+    for (const kind of SECTION_ORDER[intent]) {
+      const s = buildSection(kind, graph, primary, opts.incidents, now);
+      if (s && s.facts.length > 0) sections.push(s);
+    }
+  } else {
+    const global = buildGlobalSections(intent, graph, opts.incidents);
+    if (global) {
+      scope = "global";
+      for (const s of global) if (s.facts.length > 0) sections.push(s);
+    }
+  }
+  const answer = summarize(question, intent, matched, primary, sections, scope);
+  const provSet = /* @__PURE__ */ new Set();
+  for (const s of sections) for (const f of s.facts) if (f.provenance) provSet.add(f.provenance);
+  const confidence = sections[0]?.facts[0]?.confidence;
+  return AskResultSchema.parse({
+    question,
+    intent,
+    matched,
+    ...primary ? { primaryNode: primary } : {},
+    ...scope ? { scope } : {},
+    sections,
+    answer,
+    ...confidence !== void 0 ? { confidence } : {},
+    provenance: [...provSet]
+  });
+}
+
 // src/streaming.ts
 var SSE_HEARTBEAT_MS = 3e4;
 var SSE_BACKPRESSURE_CAP = 1e3;
@@ -16713,14 +17345,14 @@ function getConnectorStatus(id, now = Date.now(), thresholdMs = CONNECTOR_STALE_
 }
 
 // src/connectors/index.ts
-import { NodeType as NodeType32, parseFileId as parseFileId2, Provenance as Provenance26 } from "@neat.is/types";
+import { NodeType as NodeType33, parseFileId as parseFileId2, Provenance as Provenance27 } from "@neat.is/types";
 var NO_ENV = "unknown";
 function staticCallSiteFor(graph, serviceName, targetNodeId) {
   if (!graph.hasNode(targetNodeId)) return void 0;
   const sites = [];
   for (const edgeId of graph.inboundEdges(targetNodeId)) {
     const edge = graph.getEdgeAttributes(edgeId);
-    if (edge.provenance !== Provenance26.EXTRACTED) continue;
+    if (edge.provenance !== Provenance27.EXTRACTED) continue;
     const parsed = parseFileId2(edge.source);
     if (!parsed || parsed.service !== serviceName || !edge.evidence) continue;
     const site = { relPath: edge.evidence.file };
@@ -16732,7 +17364,7 @@ function staticCallSiteFor(graph, serviceName, targetNodeId) {
 function routeCallSiteFor(graph, targetNodeId) {
   if (!graph.hasNode(targetNodeId)) return void 0;
   const attrs = graph.getNodeAttributes(targetNodeId);
-  if (attrs.type !== NodeType32.RouteNode || !attrs.path) return void 0;
+  if (attrs.type !== NodeType33.RouteNode || !attrs.path) return void 0;
   const site = { relPath: attrs.path };
   if (attrs.line !== void 0) site.line = attrs.line;
   return site;
@@ -17437,7 +18069,7 @@ function createSupabaseConnector(graph, config, deps = {}) {
 }
 
 // src/connectors/railway/index.ts
-import { EdgeType as EdgeType27, NodeType as NodeType33, serviceId as serviceId14 } from "@neat.is/types";
+import { EdgeType as EdgeType27, NodeType as NodeType34, serviceId as serviceId15 } from "@neat.is/types";
 
 // src/connectors/railway/client.ts
 var DEFAULT_RAILWAY_API_URL = "https://backboard.railway.com/graphql/v2";
@@ -17587,7 +18219,7 @@ function buildRailwayRouteIndex(graph, serviceName) {
   const out = [];
   graph.forEachNode((_id, attrs) => {
     const node = attrs;
-    if (node.type !== NodeType33.RouteNode) return;
+    if (node.type !== NodeType34.RouteNode) return;
     const route = attrs;
     if (route.service !== serviceName) return;
     out.push({
@@ -17696,7 +18328,7 @@ function createRailwayResolveTarget(config) {
     if (signal.targetKind === PEER_SERVICE_TARGET_KIND) {
       const peerName = config.serviceNameById[signal.targetName];
       if (!peerName) return null;
-      return { targetNodeId: serviceId14(peerName), serviceName, edgeType: EdgeType27.CONNECTS_TO };
+      return { targetNodeId: serviceId15(peerName), serviceName, edgeType: EdgeType27.CONNECTS_TO };
     }
     return null;
   };
@@ -17878,7 +18510,7 @@ function mapLogEntriesToSignals(entries) {
 }
 
 // src/connectors/firebase/resolve.ts
-import { NodeType as NodeType34, EdgeType as EdgeType28 } from "@neat.is/types";
+import { NodeType as NodeType35, EdgeType as EdgeType28 } from "@neat.is/types";
 function neatServiceNameFor(resourceType, resourceName, serviceMap) {
   switch (resourceType) {
     case "cloud_function":
@@ -17893,7 +18525,7 @@ function routeEntriesFor(graph, serviceName) {
   const entries = [];
   graph.forEachNode((_id, attrs) => {
     const node = attrs;
-    if (node.type !== NodeType34.RouteNode) return;
+    if (node.type !== NodeType35.RouteNode) return;
     const route = attrs;
     if (route.service !== serviceName) return;
     entries.push({
@@ -17948,7 +18580,7 @@ function createFirebaseConnector(graph, serviceMap) {
 }
 
 // src/connectors/cloudflare/connector.ts
-import { EdgeType as EdgeType29, NodeType as NodeType35, fileId as fileId5, infraId as infraId22 } from "@neat.is/types";
+import { EdgeType as EdgeType29, NodeType as NodeType36, fileId as fileId5, infraId as infraId22 } from "@neat.is/types";
 
 // src/connectors/cloudflare/client.ts
 import { randomUUID } from "crypto";
@@ -18107,7 +18739,7 @@ function findTaggedWorkerFileNode(graph, workerName) {
   graph.forEachNode((id, attrs) => {
     if (found) return;
     const a = attrs;
-    if (a.type === NodeType35.FileNode && a.platform === "cloudflare" && a.platformName === workerName) {
+    if (a.type === NodeType36.FileNode && a.platform === "cloudflare" && a.platformName === workerName) {
       found = id;
     }
   });
@@ -18119,7 +18751,7 @@ function findMatchingRouteNode(graph, serviceName, method, path72) {
   graph.forEachNode((id, attrs) => {
     if (found) return;
     const a = attrs;
-    if (a.type !== NodeType35.RouteNode || a.service !== serviceName) return;
+    if (a.type !== NodeType36.RouteNode || a.service !== serviceName) return;
     if (!a.pathTemplate || normalizePathTemplate(a.pathTemplate) !== normalizedPath) return;
     const routeMethod = (a.method ?? "").toUpperCase();
     if (routeMethod !== "ALL" && routeMethod !== method) return;
@@ -18518,14 +19150,14 @@ function mapLogEntriesToSignals2(entries) {
 }
 
 // src/connectors/cloud-run/resolve.ts
-import { EdgeType as EdgeType31, NodeType as NodeType36, infraId as infraId24 } from "@neat.is/types";
+import { EdgeType as EdgeType31, NodeType as NodeType37, infraId as infraId24 } from "@neat.is/types";
 var CLOUD_RUN_SERVICE_INFRA_KIND = "cloud-run-service";
 function findMatchingRouteNode2(graph, serviceName, method, normalizedPath) {
   let found = null;
   graph.forEachNode((_id, attrs) => {
     if (found) return;
     const node = attrs;
-    if (node.type !== NodeType36.RouteNode) return;
+    if (node.type !== NodeType37.RouteNode) return;
     const route = attrs;
     if (route.service !== serviceName || !route.pathTemplate) return;
     if (normalizePathTemplate(route.pathTemplate) !== normalizedPath) return;
@@ -18596,7 +19228,7 @@ function createCloudRunConnector(graph, config = {}) {
 }
 
 // src/connectors/render/index.ts
-import { EdgeType as EdgeType32, NodeType as NodeType37 } from "@neat.is/types";
+import { EdgeType as EdgeType32, NodeType as NodeType38 } from "@neat.is/types";
 
 // src/connectors/render/types.ts
 function readRenderToken(credentials) {
@@ -18672,7 +19304,7 @@ function buildRenderRouteIndex(graph, serviceName) {
   const out = [];
   graph.forEachNode((_id, attrs) => {
     const node = attrs;
-    if (node.type !== NodeType37.RouteNode) return;
+    if (node.type !== NodeType38.RouteNode) return;
     const route = attrs;
     if (route.service !== serviceName) return;
     out.push({
@@ -19156,7 +19788,7 @@ function mapBuildsToSignals(builds, serviceName) {
 }
 
 // src/connectors/eas/resolve.ts
-import { EdgeType as EdgeType34, NodeType as NodeType38, parseFileId as parseFileId3 } from "@neat.is/types";
+import { EdgeType as EdgeType34, NodeType as NodeType39, parseFileId as parseFileId3 } from "@neat.is/types";
 var NO_ENV2 = "unknown";
 var EAS_JSON_PHASES = /* @__PURE__ */ new Set(["READ_EAS_JSON"]);
 var APP_CONFIG_PHASES = /* @__PURE__ */ new Set([
@@ -19184,7 +19816,7 @@ function findConfigNode(graph, basenames, serviceName) {
   graph.forEachNode((id, attrs) => {
     if (scoped) return;
     const node = attrs;
-    if (node.type !== NodeType38.ConfigNode) return;
+    if (node.type !== NodeType39.ConfigNode) return;
     if (typeof node.name !== "string" || !basenames.includes(node.name)) return;
     if (anyMatch === null) anyMatch = id;
     if (configNodeService(graph, id) === serviceName) scoped = id;
@@ -20257,6 +20889,18 @@ function registerRoutes(scope, ctx) {
       matches: matches.slice(0, safeLimit)
     };
   });
+  scope.get("/graph/ask", async (req, reply) => {
+    const proj = resolveProject(registry, req, reply, ctx.bootstrap, ctx.singleProject);
+    if (!proj) return;
+    const question = (req.query.q ?? "").trim();
+    if (!question) return reply.code(400).send({ error: "query parameter `q` is required" });
+    const epath = errorsPathFor(proj);
+    const incidents = epath ? await readErrorEvents(epath) : [];
+    return askGraph(proj.graph, question, {
+      ...proj.searchIndex ? { searchIndex: proj.searchIndex } : {},
+      incidents
+    });
+  });
   scope.get(
     "/graph/diff",
     async (req, reply) => {
@@ -20796,4 +21440,4 @@ export {
   deprovisionConnector,
   buildApi
 };
-//# sourceMappingURL=chunk-RQQUI3NQ.js.map
+//# sourceMappingURL=chunk-HD5X5TWY.js.map