@neat.is/core 0.9.13-dev.20260901 → 0.9.14

package/dist/{chunk-RBZNXA5L.js → chunk-SSLPBQWY.js}

@@ -935,6 +935,7 @@ import {
   inferredEdgeId,
   infraId,
   observedEdgeId,
+  frontierEdgeId,
   serviceId,
   symbolId,
   websocketChannelId
@@ -4413,6 +4414,14 @@ function mergeColumnsAt(graph, tableNodeId, columns, provenance, confidence) {
 function mergeObservedColumns(graph, tableNodeId, columns) {
   mergeColumnsAt(graph, tableNodeId, columns, Provenance5.OBSERVED, OBSERVED_COLUMN_CONFIDENCE);
 }
+function mergeObservedDeployState(graph, serviceNodeId, state) {
+  if (!graph.hasNode(serviceNodeId)) return;
+  const attrs = {};
+  if (typeof state.image === "string" && state.image.length > 0) attrs["observedImage"] = state.image;
+  if (typeof state.readyReplicas === "number") attrs["observedReadyReplicas"] = state.readyReplicas;
+  if (Object.keys(attrs).length === 0) return;
+  graph.mergeNodeAttributes(serviceNodeId, attrs);
+}
 function ensureDatabaseNode(graph, host, engine) {
   const id = databaseId(host);
   if (graph.hasNode(id)) return id;
@@ -5109,6 +5118,32 @@ function promoteFrontierNodes(graph, opts = {}) {
   }
   return promoted;
 }
+function stageFrontierEdge(graph, source, target, type) {
+  if (!graph.hasNode(source) || !graph.hasNode(target)) return false;
+  if (graph.hasEdge(observedEdgeId(source, target, type))) return false;
+  const key = frontierEdgeId(source, target, type);
+  if (graph.hasEdge(key)) return false;
+  graph.addEdgeWithKey(key, source, target, {
+    id: key,
+    source,
+    target,
+    type,
+    provenance: Provenance5.FRONTIER
+  });
+  return true;
+}
+function promoteFrontierEdges(graph) {
+  const graduated = [];
+  graph.forEachEdge((edgeId, attrs) => {
+    const e = attrs;
+    if (e.provenance !== Provenance5.FRONTIER) return;
+    if (graph.hasEdge(observedEdgeId(e.source, e.target, e.type))) {
+      graduated.push(edgeId);
+    }
+  });
+  for (const edgeId of graduated) graph.dropEdge(edgeId);
+  return graduated.length;
+}
 function rewireFrontierEdges(graph, frontierId2, serviceId17) {
   const inbound = [...graph.inboundEdges(frontierId2)];
   const outbound = [...graph.outboundEdges(frontierId2)];
@@ -5217,6 +5252,7 @@ function startStalenessLoop(graph, options = {}) {
           project: options.project
         });
         if (options.onPolicyTrigger) await options.onPolicyTrigger(graph);
+        if (options.onReconcile) await options.onReconcile(graph);
       } catch (err) {
         console.error("staleness tick failed", err);
       }
@@ -5360,6 +5396,7 @@ import {
   RootCauseResultSchema,
   TransitiveDependenciesResultSchema,
   fileId as fileId4,
+  frontierEdgeId as frontierEdgeId2,
   parseSymbolId
 } from "@neat.is/types";
 var ROOT_CAUSE_MAX_DEPTH = 5;
@@ -5390,13 +5427,19 @@ function resolveOwningService(graph, nodeId) {
   }
   return null;
 }
+function isFrontierEdge(e) {
+  return e.provenance === Provenance6.FRONTIER;
+}
+function rankOf(p) {
+  return p === Provenance6.FRONTIER ? -1 : PROV_RANK[p];
+}
 function bestEdgeBySource(graph, edgeIds) {
   const best = /* @__PURE__ */ new Map();
   for (const id of edgeIds) {
     const e = graph.getEdgeAttributes(id);
-    if (isFrontierNode(graph, e.source)) continue;
+    if (isFrontierNode(graph, e.source) || isFrontierEdge(e)) continue;
     const cur = best.get(e.source);
-    if (!cur || PROV_RANK[e.provenance] > PROV_RANK[cur.provenance]) {
+    if (!cur || rankOf(e.provenance) > rankOf(cur.provenance)) {
       best.set(e.source, e);
     }
   }
@@ -5406,9 +5449,9 @@ function bestEdgeByTarget(graph, edgeIds) {
   const best = /* @__PURE__ */ new Map();
   for (const id of edgeIds) {
     const e = graph.getEdgeAttributes(id);
-    if (isFrontierNode(graph, e.target)) continue;
+    if (isFrontierNode(graph, e.target) || isFrontierEdge(e)) continue;
     const cur = best.get(e.target);
-    if (!cur || PROV_RANK[e.provenance] > PROV_RANK[cur.provenance]) {
+    if (!cur || rankOf(e.provenance) > rankOf(cur.provenance)) {
       best.set(e.target, e);
     }
   }
@@ -5418,7 +5461,10 @@ var PROVENANCE_CEILING = {
   OBSERVED: 1,
   INFERRED: 0.7,
   EXTRACTED: 0.5,
-  STALE: 0.3
+  STALE: 0.3,
+  // A FRONTIER surface (ADR-226) is a proposal about a cause NEAT could not observe
+  // — the least-trusted claim it makes, below STALE (which was at least once seen).
+  FRONTIER: 0.2
 };
 function volumeWeight(spanCount) {
   if (!spanCount || spanCount <= 0) return 0.5;
@@ -5653,7 +5699,7 @@ function rootCauseFromIncidents(nodeId, incidents, errorEvent) {
   });
 }
 function isFailingCallEdge(e) {
-  return e.type === EdgeType6.CALLS && (e.signal?.errorCount ?? 0) > 0;
+  return e.type === EdgeType6.CALLS && !isFrontierEdge(e) && (e.signal?.errorCount ?? 0) > 0;
 }
 function callSourcesForService(graph, serviceId17) {
   const ids = [serviceId17];
@@ -5676,8 +5722,8 @@ function failingCallDominates(e, id, curEdge, curId) {
   const ec = e.signal?.errorCount ?? 0;
   const cc = curEdge.signal?.errorCount ?? 0;
   if (ec !== cc) return ec > cc;
-  if (PROV_RANK[e.provenance] !== PROV_RANK[curEdge.provenance]) {
-    return PROV_RANK[e.provenance] > PROV_RANK[curEdge.provenance];
+  if (rankOf(e.provenance) !== rankOf(curEdge.provenance)) {
+    return rankOf(e.provenance) > rankOf(curEdge.provenance);
   }
   return id < curId;
 }
@@ -5728,11 +5774,11 @@ function dominantStaleCall(graph, serviceId17, visited) {
     for (const edgeId of graph.outboundEdges(src)) {
       const e = graph.getEdgeAttributes(edgeId);
       if (e.type !== EdgeType6.CALLS) continue;
-      if (isFrontierNode(graph, e.target)) continue;
+      if (isFrontierNode(graph, e.target) || isFrontierEdge(e)) continue;
       const owner = resolveOwningService(graph, e.target);
       if (!owner || visited.has(owner.id)) continue;
       const cur = bestByCallee.get(owner.id);
-      if (!cur || PROV_RANK[e.provenance] > PROV_RANK[cur.provenance]) {
+      if (!cur || rankOf(e.provenance) > rankOf(cur.provenance)) {
         bestByCallee.set(owner.id, e);
       }
     }
@@ -6005,6 +6051,7 @@ function nodeContext(graph, nodeId, incidents, now = Date.now()) {
     for (const edgeId of graph.inboundEdges(n)) {
       const e = graph.getEdgeAttributes(edgeId);
       if (e.type === EdgeType6.CONTAINS) continue;
+      if (isFrontierEdge(e)) continue;
       errorsFromCallers += e.signal?.errorCount ?? 0;
       inboundVolume += e.callCount ?? e.signal?.spanCount ?? 0;
       if (e.provenance === Provenance6.STALE) stale = true;
@@ -6018,6 +6065,7 @@ function nodeContext(graph, nodeId, incidents, now = Date.now()) {
     for (const edgeId of graph.outboundEdges(n)) {
       const e = graph.getEdgeAttributes(edgeId);
       if (e.type === EdgeType6.CONTAINS) continue;
+      if (isFrontierEdge(e)) continue;
       outboundVolume += e.callCount ?? e.signal?.spanCount ?? 0;
       if (e.type === EdgeType6.CALLS) outboundErrors += e.signal?.errorCount ?? 0;
       if (e.provenance === Provenance6.STALE) stale = true;
@@ -6051,6 +6099,11 @@ function isSaturated(ctx) {
 function isBoundaryTimeoutSymptom(ctx) {
   return ctx.errorsEmittedHere > 0 && ctx.boundaryTimeout === true && ctx.errorsFromCallers === 0 && ctx.hasOutboundDeps === true && ctx.observedErroringDownstream !== true;
 }
+var UNREACHABLE_INBOUND_ERROR_RATE = 0.5;
+var UNREACHABLE_MIN_INBOUND = 3;
+function isUnreachableSeed(ctx) {
+  return ctx.callCount >= UNREACHABLE_MIN_INBOUND && ctx.errorsFromCallers > 0 && ctx.errorsFromCallers >= UNREACHABLE_INBOUND_ERROR_RATE * ctx.callCount && ctx.errorsEmittedHere === 0 && ctx.outboundVolume === 0;
+}
 function classifyNode(ctx) {
   if (ctx.errorsEmittedHere > 0) {
     if ((ctx.stale || isSaturated(ctx)) && ctx.errorsFromCallers >= ctx.errorsEmittedHere) {
@@ -6059,6 +6112,7 @@ function classifyNode(ctx) {
     if (isBoundaryTimeoutSymptom(ctx)) return "symptom-only";
     return "primary-failure";
   }
+  if (isUnreachableSeed(ctx)) return "unreachable";
   if (ctx.errorsFromCallers > 0) return "symptom-only";
   return "unrelated";
 }
@@ -6295,22 +6349,44 @@ function routeMatches(declared, incident) {
   const b = normalizeRoute(incident);
   return a === b || a.startsWith(b) || b.startsWith(a);
 }
-function structuralUpstreamPointer(graph, boundaryNode, incidents) {
-  const route = boundaryIncidentRoute(boundaryNode, incidents);
-  const callees = declaredOutboundCallees(graph, boundaryNode);
+function firstDeclaredCallee(graph, node, route) {
+  const callees = declaredOutboundCallees(graph, node);
   if (callees.length === 0) return null;
   const narrowed = route !== void 0 ? callees.filter((c) => c.route !== void 0 && routeMatches(c.route, route)) : callees;
   const chosen = narrowed.length === 1 ? narrowed[0] : callees.length === 1 ? callees[0] : null;
-  if (!chosen) return null;
-  let node = chosen.target;
-  const seen = /* @__PURE__ */ new Set([boundaryNode, node]);
-  for (let depth = 0; depth < ROOT_CAUSE_MAX_DEPTH; depth++) {
-    const next = declaredOutboundCallees(graph, node);
-    if (next.length !== 1 || seen.has(next[0].target)) break;
-    node = next[0].target;
-    seen.add(node);
+  return chosen ? chosen.target : null;
+}
+function observedOutboundNextServices(graph, nodeId) {
+  const targets = /* @__PURE__ */ new Set();
+  for (const n of nodeScope(graph, nodeId)) {
+    if (!graph.hasNode(n)) continue;
+    for (const edgeId of graph.outboundEdges(n)) {
+      const e = graph.getEdgeAttributes(edgeId);
+      if (!DEP_EDGE_TYPES.has(e.type)) continue;
+      if (e.provenance !== Provenance6.OBSERVED) continue;
+      if (e.target !== nodeId) targets.add(e.target);
+    }
+  }
+  return [...targets];
+}
+function resolveHangHop(graph, boundaryNode, incidents) {
+  const route = boundaryIncidentRoute(boundaryNode, incidents);
+  const own = firstDeclaredCallee(graph, boundaryNode, route);
+  if (own) {
+    return route !== void 0 ? { source: boundaryNode, target: own, route } : { source: boundaryNode, target: own };
+  }
+  const resolved = observedOutboundNextServices(graph, boundaryNode).map((n) => ({ source: n, target: firstDeclaredCallee(graph, n, route) })).filter((r) => r.target !== null);
+  if (resolved.length === 1) {
+    const hop = resolved[0];
+    return route !== void 0 ? { ...hop, route } : hop;
   }
-  return route !== void 0 ? { node, route } : { node };
+  return null;
+}
+function stagedHangProposal(graph, boundaryNode, incidents) {
+  const hop = resolveHangHop(graph, boundaryNode, incidents);
+  if (!hop) return null;
+  if (!graph.hasEdge(frontierEdgeId2(hop.source, hop.target, EdgeType6.CALLS))) return null;
+  return hop.route !== void 0 ? { node: hop.target, route: hop.route } : { node: hop.target };
 }
 function enrichWithNavigation(graph, errorNodeId, tagged, incidents, now) {
   const legacy = tagged.result;
@@ -6345,29 +6421,39 @@ function enrichWithNavigation(graph, errorNodeId, tagged, incidents, now) {
       confidence: Math.min(legacy.confidence, 0.4),
       ...lastProv ? { provenance: lastProv } : {}
     });
+  } else if (seedCtx && isUnreachableSeed(seedCtx)) {
+    const name = displayNameOf(seedNode);
+    candidates.push({
+      node: seedNode,
+      classification: "unreachable",
+      reason: `${name} is unreachable: its callers' requests fail (${seedCtx.errorsFromCallers} erroring inbound calls) and it produced no telemetry of its own \u2014 no server spans, no outbound calls \u2014 so it never served. The failure is observed, but its cause is not in the trace: a startup failure, a crash before the first span, or an unschedulable / unhealthy pod. Inspect ${name}'s deploy state and logs \u2014 there is no code fault to find in the graph here.`,
+      context: seedCtx,
+      confidence: legacy.confidence,
+      provenance: Provenance6.OBSERVED
+    });
   } else if (seedCtx && isBoundaryTimeoutSymptom(seedCtx)) {
-    const pointer = structuralUpstreamPointer(graph, seedNode, incidents);
     const seedName = displayNameOf(seedNode);
-    const routeNote = pointer?.route ? ` serving ${pointer.route}` : "";
-    if (pointer) {
-      const causeName = displayNameOf(pointer.node);
-      candidates.push({
-        node: pointer.node,
-        classification: "primary-failure",
-        reason: `${causeName} is the likely root cause (structural, INFERRED \u2014 not observed): the boundary ${seedName} only timed out waiting, and the actual culprit hung without exporting a span, so this is walked from the declared call graph${routeNote}, not from runtime signal. Restore instrumentation / inspect ${causeName} to confirm.`,
-        context: nodeContext(graph, pointer.node, incidents, now),
-        confidence: Math.min(legacy.confidence, PROVENANCE_CEILING.EXTRACTED),
-        provenance: Provenance6.INFERRED
-      });
-    }
+    const proposal = stagedHangProposal(graph, seedNode, incidents);
+    const routeNote = proposal?.route ? ` serving ${proposal.route}` : "";
     candidates.push({
       node: seedNode,
       classification: "symptom-only",
-      reason: pointer ? `${seedName} timed out waiting on a downstream that hung and exported nothing \u2014 a boundary reporting an upstream fault, not the fault itself.` : `${seedName} timed out but nothing it can see downstream is erroring \u2014 the cause is downstream and unobserved (the culprit hung and exported no span). No single declared callee${routeNote} resolves, so no confident cause is named; inspect ${seedName}'s declared downstream.`,
+      reason: proposal ? `${seedName} timed out waiting on a downstream that hung and exported no span \u2014 a boundary reporting an upstream fault, not the fault itself. The cause is unobservable; NEAT proposes the staged FRONTIER surface below, a hypothesis to confirm, not an observed cause.` : `${seedName} timed out but nothing it can see downstream is erroring \u2014 the cause is downstream and unobserved (the culprit hung and exported no span). No FRONTIER surface${routeNote} is staged, so no cause is proposed; inspect ${seedName}'s declared downstream and restore instrumentation.`,
       context: seedCtx,
       confidence: Math.min(legacy.confidence, 0.3),
       ...lastProv ? { provenance: lastProv } : {}
     });
+    if (proposal) {
+      const causeName = displayNameOf(proposal.node);
+      candidates.push({
+        node: proposal.node,
+        classification: "primary-failure",
+        reason: `${causeName} is the proposed hang cause (FRONTIER \u2014 a hypothesis, not observed): the boundary ${seedName} only timed out waiting and the culprit hung without exporting a span, so NEAT staged a FRONTIER surface on the unobservable hop${routeNote}. It graduates to OBSERVED when ${causeName} comes back; until then, inspect it / restore instrumentation to confirm, or it is culled.`,
+        context: nodeContext(graph, proposal.node, incidents, now),
+        confidence: Math.min(legacy.confidence, PROVENANCE_CEILING.FRONTIER),
+        provenance: Provenance6.FRONTIER
+      });
+    }
   } else if (staleChain) {
     const culprit = staleChain.culprit;
     const culpritName = displayNameOf(culprit);
@@ -6431,6 +6517,9 @@ function fixRecommendationForTop(top, seedNode, legacy) {
     return legacy.fixRecommendation;
   }
   const name = top.node.replace(/^service:/, "");
+  if (top.classification === "symptom-only" && top.context.boundaryTimeout === true) {
+    return `${name} timed out waiting on a downstream that hung and exported no span \u2014 the cause is unobservable from traces. Inspect the FRONTIER surface NEAT staged on the unobservable hop (see candidates); it graduates to OBSERVED when that service recovers. Restore instrumentation on that path to confirm, rather than treating ${name} as the fault.`;
+  }
   if (top.provenance === Provenance6.STALE) {
     return `Live telemetry for this path has gone quiet; the last-observed topology traces the failure downstream to ${name}. Restore instrumentation (or re-run with live traces) to confirm, then inspect ${name}.`;
   }
@@ -15708,6 +15797,25 @@ function detectColumnDrift(node) {
   }
   return out;
 }
+var RECOMMENDATION_DEPLOY_IMAGE_MISMATCH = "The running image differs from the manifest-declared image \u2014 the rollout has not taken (the old ReplicaSet is still serving). Re-apply the deployment or investigate why the new image failed to roll out.";
+var DEPLOY_DIVERGENCE_CONFIDENCE = 0.9;
+function detectDeployDivergence(svc) {
+  const out = [];
+  if (typeof svc.declaredImage === "string" && typeof svc.observedImage === "string" && svc.declaredImage !== svc.observedImage) {
+    out.push({
+      type: "deploy-mismatch",
+      kind: "image",
+      source: svc.id,
+      target: svc.id,
+      declaredImage: svc.declaredImage,
+      observedImage: svc.observedImage,
+      confidence: DEPLOY_DIVERGENCE_CONFIDENCE,
+      reason: `Service ${svc.name} declares image ${svc.declaredImage} but its running pods report ${svc.observedImage} \u2014 the deploy has not taken (the old version is still serving), so no incident fires.`,
+      recommendation: RECOMMENDATION_DEPLOY_IMAGE_MISMATCH
+    });
+  }
+  return out;
+}
 var SYMBOL_MISMATCH_PATTERNS = [
   {
     // "'ListProductsResponse' object has no attribute 'products_list'" and kin.
@@ -16035,6 +16143,7 @@ function computeDivergences(graph, opts = {}) {
       const svc = n;
       for (const d of detectHostMismatch(graph, nodeId, svc)) all.push(d);
       for (const d of detectCompatDivergences(graph, nodeId, svc)) all.push(d);
+      for (const d of detectDeployDivergence(svc)) all.push(d);
       return;
     }
     if (n.type === NodeType30.InfraNode && n.kind === "sql-table") {
@@ -16075,7 +16184,12 @@ function computeDivergences(graph, opts = {}) {
     // orders last so at equal confidence the structural and symbol divergences
     // lead, per the contract ("rank below the definitive structural and symbol
     // divergences").
-    "observed-failing": 6
+    "observed-failing": 6,
+    // Deploy mismatch (ADR-225) is a definitive structural declared-vs-observed
+    // divergence carrying high confidence (0.9), so the confidence sort already
+    // places it among the structural leaders; this slot only breaks an exact
+    // confidence tie and sits last as a stable tiebreaker.
+    "deploy-mismatch": 7
   };
   filtered.sort((a, b) => {
     if (b.confidence !== a.confidence) return b.confidence - a.confidence;
@@ -18378,6 +18492,11 @@ async function runConnectorPoll(connector, ctx, graph, resolveTarget) {
       unresolved++;
       continue;
     }
+    if (signal.deployState) {
+      ensureServiceNode(graph, resolved.serviceName, NO_ENV);
+      mergeObservedDeployState(graph, resolved.targetNodeId, signal.deployState);
+      continue;
+    }
     if (signal.incident) {
       ensureServiceNode(graph, resolved.serviceName, NO_ENV);
       if (!ctx.errorsPath || !graph.hasNode(resolved.targetNodeId)) {
@@ -22654,7 +22773,10 @@ export {
   attachGraphToEventBus,
   confidenceForEdge,
   getBlastRadius,
+  nodeContext,
+  isBoundaryTimeoutSymptom,
   getRootCause,
+  resolveHangHop,
   evaluateAllPolicies,
   loadPolicyFile,
   PolicyViolationsLog,
@@ -22669,6 +22791,8 @@ export {
   makeErrorSpanWriter,
   handleSpan,
   promoteFrontierNodes,
+  stageFrontierEdge,
+  promoteFrontierEdges,
   makeSpanHandler,
   markStaleEdges,
   readStaleEvents,
@@ -22733,4 +22857,4 @@ export {
   deprovisionConnector,
   buildApi
 };
-//# sourceMappingURL=chunk-RBZNXA5L.js.map
+//# sourceMappingURL=chunk-SSLPBQWY.js.map