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

package/dist/cli.cjs

@@ -1292,13 +1292,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);
     }
   }
@@ -1308,9 +1314,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);
     }
   }
@@ -1320,7 +1326,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;
@@ -1555,7 +1564,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];
@@ -1578,8 +1587,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;
 }
@@ -1630,11 +1639,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);
       }
     }
@@ -1907,6 +1916,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;
@@ -1920,6 +1930,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;
@@ -2203,22 +2214,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 };
   }
-  return route !== void 0 ? { node, route } : { node };
+  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((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;
@@ -2264,28 +2297,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);
@@ -2349,6 +2382,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}.`;
   }
@@ -7026,6 +7062,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)];
@@ -7134,6 +7196,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);
       }
@@ -23706,6 +23769,38 @@ async function buildApi(opts) {
 
 // src/watch.ts
 init_auth();
+
+// src/hang-sensor.ts
+init_cjs_shims();
+var import_types102 = 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_types102.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/watch.ts
 init_otel();
 
 // src/connectors/kubernetes/index.ts
@@ -24057,7 +24152,7 @@ function mapWorkloadsToSignals(deployments, pods, config) {
 
 // src/connectors/kubernetes/resolve.ts
 init_cjs_shims();
-var import_types103 = require("@neat.is/types");
+var import_types104 = require("@neat.is/types");
 var NO_ENV3 = "unknown";
 function createK8sResolveTarget(graph) {
   return (signal) => {
@@ -24068,7 +24163,7 @@ function createK8sResolveTarget(graph) {
     return {
       targetNodeId: resolveFusedServiceId(graph, serviceName, NO_ENV3),
       serviceName,
-      edgeType: import_types103.EdgeType.CALLS
+      edgeType: import_types104.EdgeType.CALLS
     };
   };
 }
@@ -24192,7 +24287,7 @@ var import_node_fs42 = require("fs");
 var import_node_path78 = __toESM(require("path"), 1);
 
 // src/daemon.ts
-var import_types106 = require("@neat.is/types");
+var import_types107 = require("@neat.is/types");
 function daemonJsonPath(scanPath) {
   return import_node_path79.default.join(scanPath, "neat-out", "daemon.json");
 }
@@ -24844,7 +24939,10 @@ async function startWatch(graph, opts) {
   const stopStaleness = startStalenessLoop(graph, {
     staleEventsPath: opts.staleEventsPath,
     project: projectName,
-    onPolicyTrigger
+    onPolicyTrigger,
+    // Graduate FRONTIER surfaces whose twin arrived + stage surfaces for current
+    // hangs (ADR-226), each post-ingest tick.
+    onReconcile: (g) => reconcileFrontierSurfaces(g, opts.errorsPath)
   });
   const stopConnectors = await startConnectorPolling({
     project: projectName,
@@ -29218,7 +29316,7 @@ var import_node_path89 = __toESM(require("path"), 1);
 
 // src/cli-client.ts
 init_cjs_shims();
-var import_types107 = require("@neat.is/types");
+var import_types108 = require("@neat.is/types");
 var HttpError = class extends Error {
   constructor(status2, message, responseBody = "") {
     super(message);
@@ -29360,7 +29458,7 @@ async function runBlastRadius(client, input) {
   }
 }
 function formatBlastEntry(n) {
-  const tag = n.edgeProvenance === import_types107.Provenance.STALE ? " [STALE \u2014 last seen too long ago]" : "";
+  const tag = n.edgeProvenance === import_types108.Provenance.STALE ? " [STALE \u2014 last seen too long ago]" : "";
   return `  \u2022 ${n.nodeId} (distance ${n.distance}, ${n.edgeProvenance})${tag}`;
 }
 async function runDependencies(client, input) {
@@ -29417,7 +29515,7 @@ async function runObservedDependencies(client, input) {
       if (result.observed) {
         return {
           summary: `${input.nodeId} makes no outbound runtime calls, but OTel has observed it receiving traffic on ${result.inboundObservedCount} inbound call path${result.inboundObservedCount === 1 ? "" : "s"} \u2014 it's a pure receiver.`,
-          provenance: import_types107.Provenance.OBSERVED
+          provenance: import_types108.Provenance.OBSERVED
         };
       }
       const note = result.hasExtractedOutbound ? " Static (EXTRACTED) dependencies exist but no runtime traffic has been seen \u2014 is OTel running?" : "";
@@ -29427,7 +29525,7 @@ async function runObservedDependencies(client, input) {
     return {
       summary: `${input.nodeId} has ${result.dependencies.length} runtime dependenc${result.dependencies.length === 1 ? "y" : "ies"} confirmed by OTel.`,
       block: blockLines.join("\n"),
-      provenance: import_types107.Provenance.OBSERVED
+      provenance: import_types108.Provenance.OBSERVED
     };
   } catch (err) {
     if (err instanceof HttpError && err.status === 404) {
@@ -29481,7 +29579,7 @@ async function runIncidents(client, input) {
     return {
       summary: `${target} has ${body.total} recorded incident${body.total === 1 ? "" : "s"}; showing the ${ordered.length} most recent.`,
       block: blockLines.join("\n"),
-      provenance: import_types107.Provenance.OBSERVED
+      provenance: import_types108.Provenance.OBSERVED
     };
   } catch (err) {
     if (err instanceof HttpError && err.status === 404) {
@@ -29590,7 +29688,7 @@ async function runStaleEdges(client, input) {
   return {
     summary: `${events.length} stale-edge transition${events.length === 1 ? "" : "s"} recorded${input.edgeType ? ` for ${input.edgeType}` : ""}.`,
     block: blockLines.join("\n"),
-    provenance: import_types107.Provenance.STALE
+    provenance: import_types108.Provenance.STALE
   };
 }
 async function runPolicies(client, input) {
@@ -30887,12 +30985,12 @@ async function runEditorCommand(clientId, args, projectDir = process.cwd()) {
 
 // src/monitor.ts
 init_cjs_shims();
-var import_types108 = require("@neat.is/types");
+var import_types109 = require("@neat.is/types");
 var OBSERVED_DEP_EDGE_TYPES = /* @__PURE__ */ new Set([
-  import_types108.EdgeType.CALLS,
-  import_types108.EdgeType.CONNECTS_TO,
-  import_types108.EdgeType.PUBLISHES_TO,
-  import_types108.EdgeType.CONSUMES_FROM
+  import_types109.EdgeType.CALLS,
+  import_types109.EdgeType.CONNECTS_TO,
+  import_types109.EdgeType.PUBLISHES_TO,
+  import_types109.EdgeType.CONSUMES_FROM
 ]);
 function divergenceKey(d) {
   const column = "column" in d && d.column ? d.column : "";
@@ -30953,7 +31051,7 @@ function formatDivergenceLine2(d) {
   }
 }
 function formatStaleLine(edgeId) {
-  const parsed = (0, import_types108.parseEdgeId)(edgeId);
+  const parsed = (0, import_types109.parseEdgeId)(edgeId);
   if (parsed) {
     return `\u22EF stale  ${parsed.source} \u2192 ${parsed.target}  (observed edge went quiet)`;
   }
@@ -30966,7 +31064,7 @@ function divergenceJson(d) {
   return JSON.stringify({ kind: "divergence", ...d });
 }
 function staleJson(edgeId) {
-  const parsed = (0, import_types108.parseEdgeId)(edgeId);
+  const parsed = (0, import_types109.parseEdgeId)(edgeId);
   return JSON.stringify({
     kind: "stale",
     edgeId,
@@ -31049,7 +31147,7 @@ var MonitorEmitter = class {
   // ignores non-OBSERVED edges and non-dependency edge types (structural
   // ownership), so only real runtime dependencies reach stdout.
   emitObservedEdge(edge) {
-    if (edge.provenance !== import_types108.Provenance.OBSERVED) return false;
+    if (edge.provenance !== import_types109.Provenance.OBSERVED) return false;
     if (!OBSERVED_DEP_EDGE_TYPES.has(edge.type)) return false;
     const key = `edge|${edge.id}`;
     if (this.seen.has(key)) return false;
@@ -31230,7 +31328,7 @@ async function runMonitor(opts) {
       case "edge-added": {
         const payload = safeParse(frame.data);
         const edge = payload?.edge;
-        if (edge && edge.provenance === import_types108.Provenance.OBSERVED) {
+        if (edge && edge.provenance === import_types109.Provenance.OBSERVED) {
           emitter.emitObservedEdge(edge);
           divergences.schedule();
         }
@@ -31480,7 +31578,7 @@ async function runSync(opts) {
 }
 
 // src/cli.ts
-var import_types109 = require("@neat.is/types");
+var import_types110 = require("@neat.is/types");
 function isNpxInvocation() {
   if (process.env.npm_command === "exec") return true;
   const execpath = process.env.npm_execpath ?? "";
@@ -32564,10 +32662,10 @@ async function runQueryVerb(cmd, parsed) {
         const parts = parsed.type.split(",").map((s) => s.trim()).filter((s) => s.length > 0);
         const out = [];
         for (const p of parts) {
-          const r = import_types109.DivergenceTypeSchema.safeParse(p);
+          const r = import_types110.DivergenceTypeSchema.safeParse(p);
           if (!r.success) {
             console.error(
-              `neat divergences: unknown --type "${p}". allowed: ${import_types109.DivergenceTypeSchema.options.join(", ")}`
+              `neat divergences: unknown --type "${p}". allowed: ${import_types110.DivergenceTypeSchema.options.join(", ")}`
             );
             return 2;
           }