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

package/dist/index.d.cts

@@ -440,6 +440,7 @@ interface StalenessLoopOptions {
     staleEventsPath?: string;
     project?: string;
     onPolicyTrigger?: (graph: NeatGraph) => Promise<void> | void;
+    onReconcile?: (graph: NeatGraph) => Promise<void> | void;
 }
 declare function startStalenessLoop(graph: NeatGraph, options?: StalenessLoopOptions): () => void;
 declare function readErrorEvents(errorsPath: string, opts?: {

package/dist/index.d.ts

@@ -440,6 +440,7 @@ interface StalenessLoopOptions {
     staleEventsPath?: string;
     project?: string;
     onPolicyTrigger?: (graph: NeatGraph) => Promise<void> | void;
+    onReconcile?: (graph: NeatGraph) => Promise<void> | void;
 }
 declare function startStalenessLoop(graph: NeatGraph, options?: StalenessLoopOptions): () => void;
 declare function readErrorEvents(errorsPath: string, opts?: {

package/dist/index.js

@@ -1,7 +1,7 @@
 import {
   routeSpanToProject,
   startDaemon
-} from "./chunk-BKSM2YLV.js";
+} from "./chunk-NV4WWJSU.js";
 import {
   ProjectNameCollisionError,
   addProject,
@@ -37,7 +37,7 @@ import {
   thresholdForEdgeType,
   touchLastSeen,
   writeAtomically
-} from "./chunk-RL6H3VVD.js";
+} from "./chunk-SSLPBQWY.js";
 import {
   startOtelGrpcReceiver
 } from "./chunk-ERE47MCR.js";

package/dist/neatd.cjs

@@ -1247,13 +1247,19 @@ function resolveOwningService(graph, nodeId) {
   }
   return null;
 }
+function isFrontierEdge(e) {
+  return e.provenance === import_types.Provenance.FRONTIER;
+}
+function rankOf(p) {
+  return p === import_types.Provenance.FRONTIER ? -1 : import_types.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 || import_types.PROV_RANK[e.provenance] > import_types.PROV_RANK[cur.provenance]) {
+    if (!cur || rankOf(e.provenance) > rankOf(cur.provenance)) {
       best.set(e.source, e);
     }
   }
@@ -1263,9 +1269,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 || import_types.PROV_RANK[e.provenance] > import_types.PROV_RANK[cur.provenance]) {
+    if (!cur || rankOf(e.provenance) > rankOf(cur.provenance)) {
       best.set(e.target, e);
     }
   }
@@ -1275,7 +1281,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;
@@ -1510,7 +1519,7 @@ function rootCauseFromIncidents(nodeId, incidents, errorEvent) {
   });
 }
 function isFailingCallEdge(e) {
-  return e.type === import_types.EdgeType.CALLS && (e.signal?.errorCount ?? 0) > 0;
+  return e.type === import_types.EdgeType.CALLS && !isFrontierEdge(e) && (e.signal?.errorCount ?? 0) > 0;
 }
 function callSourcesForService(graph, serviceId17) {
   const ids = [serviceId17];
@@ -1533,8 +1542,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 (import_types.PROV_RANK[e.provenance] !== import_types.PROV_RANK[curEdge.provenance]) {
-    return import_types.PROV_RANK[e.provenance] > import_types.PROV_RANK[curEdge.provenance];
+  if (rankOf(e.provenance) !== rankOf(curEdge.provenance)) {
+    return rankOf(e.provenance) > rankOf(curEdge.provenance);
   }
   return id < curId;
 }
@@ -1585,11 +1594,11 @@ function dominantStaleCall(graph, serviceId17, visited) {
     for (const edgeId of graph.outboundEdges(src)) {
       const e = graph.getEdgeAttributes(edgeId);
       if (e.type !== import_types.EdgeType.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 || import_types.PROV_RANK[e.provenance] > import_types.PROV_RANK[cur.provenance]) {
+      if (!cur || rankOf(e.provenance) > rankOf(cur.provenance)) {
         bestByCallee.set(owner.id, e);
       }
     }
@@ -1862,6 +1871,7 @@ function nodeContext(graph, nodeId, incidents, now = Date.now()) {
     for (const edgeId of graph.inboundEdges(n)) {
       const e = graph.getEdgeAttributes(edgeId);
       if (e.type === import_types.EdgeType.CONTAINS) continue;
+      if (isFrontierEdge(e)) continue;
       errorsFromCallers += e.signal?.errorCount ?? 0;
       inboundVolume += e.callCount ?? e.signal?.spanCount ?? 0;
       if (e.provenance === import_types.Provenance.STALE) stale = true;
@@ -1875,6 +1885,7 @@ function nodeContext(graph, nodeId, incidents, now = Date.now()) {
     for (const edgeId of graph.outboundEdges(n)) {
       const e = graph.getEdgeAttributes(edgeId);
       if (e.type === import_types.EdgeType.CONTAINS) continue;
+      if (isFrontierEdge(e)) continue;
       outboundVolume += e.callCount ?? e.signal?.spanCount ?? 0;
       if (e.type === import_types.EdgeType.CALLS) outboundErrors += e.signal?.errorCount ?? 0;
       if (e.provenance === import_types.Provenance.STALE) stale = true;
@@ -2158,22 +2169,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 !== import_types.Provenance.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((0, import_types.frontierEdgeId)(hop.source, hop.target, import_types.EdgeType.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;
@@ -2219,28 +2252,28 @@ function enrichWithNavigation(graph, errorNodeId, tagged, incidents, now) {
       provenance: import_types.Provenance.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: import_types.Provenance.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: import_types.Provenance.FRONTIER
+      });
+    }
   } else if (staleChain) {
     const culprit = staleChain.culprit;
     const culpritName = displayNameOf(culprit);
@@ -2304,6 +2337,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 === import_types.Provenance.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}.`;
   }
@@ -6969,6 +7005,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((0, import_types8.observedEdgeId)(source, target, type))) return false;
+  const key = (0, import_types8.frontierEdgeId)(source, target, type);
+  if (graph.hasEdge(key)) return false;
+  graph.addEdgeWithKey(key, source, target, {
+    id: key,
+    source,
+    target,
+    type,
+    provenance: import_types8.Provenance.FRONTIER
+  });
+  return true;
+}
+function promoteFrontierEdges(graph) {
+  const graduated = [];
+  graph.forEachEdge((edgeId, attrs) => {
+    const e = attrs;
+    if (e.provenance !== import_types8.Provenance.FRONTIER) return;
+    if (graph.hasEdge((0, import_types8.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)];
@@ -7074,6 +7136,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);
       }
@@ -23203,6 +23266,36 @@ async function buildApi(opts) {
 // src/daemon.ts
 init_otel();
 
+// src/hang-sensor.ts
+init_cjs_shims();
+var import_types101 = require("@neat.is/types");
+var RECONCILE_INCIDENT_LIMIT = 500;
+function stageHangSurfaces(graph, incidents) {
+  const boundaries = /* @__PURE__ */ new Set();
+  for (const ev of incidents) {
+    if (ev.affectedNode && graph.hasNode(ev.affectedNode)) boundaries.add(ev.affectedNode);
+  }
+  let staged = 0;
+  for (const boundary of boundaries) {
+    const ctx = nodeContext(graph, boundary, incidents);
+    if (!isBoundaryTimeoutSymptom(ctx)) continue;
+    const hop = resolveHangHop(graph, boundary, incidents);
+    if (!hop) continue;
+    if (stageFrontierEdge(graph, hop.source, hop.target, import_types101.EdgeType.CALLS)) staged++;
+  }
+  return staged;
+}
+async function reconcileFrontierSurfaces(graph, errorsPath) {
+  promoteFrontierEdges(graph);
+  let incidents = [];
+  try {
+    incidents = await readErrorEvents(errorsPath, { limit: RECONCILE_INCIDENT_LIMIT });
+  } catch {
+    incidents = [];
+  }
+  stageHangSurfaces(graph, incidents);
+}
+
 // src/connectors/kubernetes/index.ts
 init_cjs_shims();
 
@@ -23552,7 +23645,7 @@ function mapWorkloadsToSignals(deployments, pods, config) {
 
 // src/connectors/kubernetes/resolve.ts
 init_cjs_shims();
-var import_types102 = require("@neat.is/types");
+var import_types103 = require("@neat.is/types");
 var NO_ENV3 = "unknown";
 function createK8sResolveTarget(graph) {
   return (signal) => {
@@ -23563,7 +23656,7 @@ function createK8sResolveTarget(graph) {
     return {
       targetNodeId: resolveFusedServiceId(graph, serviceName, NO_ENV3),
       serviceName,
-      edgeType: import_types102.EdgeType.CALLS
+      edgeType: import_types103.EdgeType.CALLS
     };
   };
 }
@@ -23698,7 +23791,7 @@ function unroutedErrorsPath(neatHome4) {
 }
 
 // src/daemon.ts
-var import_types105 = require("@neat.is/types");
+var import_types106 = require("@neat.is/types");
 function daemonJsonPath(scanPath) {
   return import_node_path77.default.join(scanPath, "neat-out", "daemon.json");
 }
@@ -23841,7 +23934,7 @@ function spanBelongsToSingleProject(graph, project, serviceName) {
   if (!serviceName) return true;
   if (serviceNameMatchesProject(serviceName, project)) return true;
   return graph.someNode(
-    (_id, attrs) => attrs.type === import_types105.NodeType.ServiceNode && attrs.name === serviceName
+    (_id, attrs) => attrs.type === import_types106.NodeType.ServiceNode && attrs.name === serviceName
   );
 }
 async function bootstrapProject(entry2, connectors = [], neatHome4) {
@@ -23885,7 +23978,11 @@ async function bootstrapProject(entry2, connectors = [], neatHome4) {
     const stopPersist = startPersistLoop(graph, outPath, { exitOnSignal: false });
     const stopStaleness = startStalenessLoop(graph, {
       staleEventsPath: paths.staleEventsPath,
-      project: entry2.name
+      project: entry2.name,
+      // Graduate FRONTIER surfaces whose OBSERVED twin has arrived + stage surfaces
+      // for current hangs (ADR-226), each post-ingest tick — the periodic point
+      // where OBSERVED state has settled and the errors ledger is current.
+      onReconcile: (g) => reconcileFrontierSurfaces(g, paths.errorsPath)
     });
     const stopConnectors = await startConnectorPolling({
       project: entry2.name,