@neat.is/core 0.9.13 → 0.9.15-dev.20260902

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

@@ -935,6 +935,7 @@ import {
   inferredEdgeId,
   infraId,
   observedEdgeId,
+  frontierEdgeId,
   serviceId,
   symbolId,
   websocketChannelId
@@ -5117,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)];
@@ -5225,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);
       }
@@ -5368,6 +5396,7 @@ import {
   RootCauseResultSchema,
   TransitiveDependenciesResultSchema,
   fileId as fileId4,
+  frontierEdgeId as frontierEdgeId2,
   parseSymbolId
 } from "@neat.is/types";
 var ROOT_CAUSE_MAX_DEPTH = 5;
@@ -5398,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);
     }
   }
@@ -5414,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);
     }
   }
@@ -5426,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;
@@ -5661,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];
@@ -5684,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;
 }
@@ -5736,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);
       }
     }
@@ -6013,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;
@@ -6026,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;
@@ -6309,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 route !== void 0 ? { node, route } : { node };
+  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 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;
@@ -6370,28 +6432,28 @@ function enrichWithNavigation(graph, errorNodeId, tagged, incidents, now) {
       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);
@@ -6455,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}.`;
   }
@@ -22708,7 +22773,10 @@ export {
   attachGraphToEventBus,
   confidenceForEdge,
   getBlastRadius,
+  nodeContext,
+  isBoundaryTimeoutSymptom,
   getRootCause,
+  resolveHangHop,
   evaluateAllPolicies,
   loadPolicyFile,
   PolicyViolationsLog,
@@ -22723,6 +22791,8 @@ export {
   makeErrorSpanWriter,
   handleSpan,
   promoteFrontierNodes,
+  stageFrontierEdge,
+  promoteFrontierEdges,
   makeSpanHandler,
   markStaleEdges,
   readStaleEvents,
@@ -22787,4 +22857,4 @@ export {
   deprovisionConnector,
   buildApi
 };
-//# sourceMappingURL=chunk-RL6H3VVD.js.map
+//# sourceMappingURL=chunk-SSLPBQWY.js.map