@neat.is/core 0.7.10 → 0.8.0

package/dist/neatd.js

@@ -2,11 +2,11 @@
 import {
   reconcileDaemonRecordSync,
   startDaemon
-} from "./chunk-D4OX6MUX.js";
+} from "./chunk-OJ6BW63H.js";
 import {
   listProjects,
   registryPath
-} from "./chunk-6T7ZHODF.js";
+} from "./chunk-3PXRQH53.js";
 import {
   BindAuthorityError,
   __require

package/dist/server.cjs

@@ -4323,6 +4323,63 @@ async function addRoutes(graph, services) {
   return { nodesAdded, edgesAdded };
 }
 
+// src/latency-digest.ts
+init_cjs_shims();
+var SUB = 16;
+var MIN_EXP = -10;
+var MAX_EXP = 22;
+var OCTAVES = MAX_EXP - MIN_EXP + 1;
+var OVERFLOW_INDEX = OCTAVES * SUB + 1;
+function latencyBucketIndex(ms) {
+  if (!Number.isFinite(ms) || ms <= 0) return 0;
+  const e = Math.floor(Math.log2(ms));
+  if (e < MIN_EXP) return 0;
+  if (e > MAX_EXP) return OVERFLOW_INDEX;
+  const base = 2 ** e;
+  const raw = Math.floor((ms / base - 1) * SUB);
+  const s = raw < 0 ? 0 : raw >= SUB ? SUB - 1 : raw;
+  return (e - MIN_EXP) * SUB + s + 1;
+}
+function bucketRepresentativeMs(index) {
+  if (index <= 0) return 0;
+  if (index >= OVERFLOW_INDEX) return 2 ** (MAX_EXP + 1);
+  const zeroBased = index - 1;
+  const e = MIN_EXP + Math.floor(zeroBased / SUB);
+  const s = zeroBased % SUB;
+  const base = 2 ** e;
+  const lower = base * (1 + s / SUB);
+  const upper = base * (1 + (s + 1) / SUB);
+  return (lower + upper) / 2;
+}
+function recordLatency(hist, ms) {
+  const key = String(latencyBucketIndex(ms));
+  hist[key] = (hist[key] ?? 0) + 1;
+  return hist;
+}
+function quantile(hist, q) {
+  const entries = Object.entries(hist).map(([k, c]) => [Number(k), c]).filter(([idx, c]) => Number.isFinite(idx) && c > 0).sort((a, b) => a[0] - b[0]);
+  let total = 0;
+  for (const [, c] of entries) total += c;
+  if (total === 0) return 0;
+  const rank = Math.max(1, Math.ceil(q * total));
+  let cumulative = 0;
+  for (const [idx, c] of entries) {
+    cumulative += c;
+    if (cumulative >= rank) return bucketRepresentativeMs(idx);
+  }
+  return bucketRepresentativeMs(entries[entries.length - 1][0]);
+}
+function round(ms) {
+  return Math.round(ms * 100) / 100;
+}
+function latencyPercentiles(hist) {
+  if (!hist) return void 0;
+  let total = 0;
+  for (const c of Object.values(hist)) total += c;
+  if (total === 0) return void 0;
+  return { p50: round(quantile(hist, 0.5)), p95: round(quantile(hist, 0.95)) };
+}
+
 // src/ingest.ts
 var HOUR_MS = 60 * 60 * 1e3;
 var DAY_MS = 24 * HOUR_MS;
@@ -5018,7 +5075,7 @@ function ensureFrontierNode(graph, host, ts) {
   graph.addNode(id, node);
   return id;
 }
-function upsertObservedEdge(graph, type, source, target, ts, isError = false, evidence) {
+function upsertObservedEdge(graph, type, source, target, ts, isError = false, evidence, durationMs) {
   if (!graph.hasNode(source) || !graph.hasNode(target)) return null;
   const grain = source.startsWith("file:") || source.startsWith("symbol:") ? "file" : "service";
   const id = makeObservedEdgeId(type, source, target);
@@ -5026,10 +5083,15 @@ function upsertObservedEdge(graph, type, source, target, ts, isError = false, ev
     const existing = graph.getEdgeAttributes(id);
     const newSpanCount = (existing.signal?.spanCount ?? existing.callCount ?? 0) + 1;
     const newErrorCount = (existing.signal?.errorCount ?? 0) + (isError ? 1 : 0);
+    const latencyHist2 = durationMs !== void 0 ? recordLatency({ ...existing.signal?.latencyHist ?? {} }, durationMs) : existing.signal?.latencyHist;
+    const latencyMs2 = latencyPercentiles(latencyHist2) ?? existing.signal?.latencyMs;
     const newSignal = {
       spanCount: newSpanCount,
       errorCount: newErrorCount,
-      lastObservedAgeMs: 0
+      lastObservedAgeMs: 0,
+      ...latencyHist2 ? { latencyHist: latencyHist2 } : {},
+      ...latencyMs2 ? { latencyMs: latencyMs2 } : {},
+      ...existing.signal?.anomalous !== void 0 ? { anomalous: existing.signal.anomalous } : {}
     };
     const updated = {
       ...existing,
@@ -5044,10 +5106,14 @@ function upsertObservedEdge(graph, type, source, target, ts, isError = false, ev
     graph.replaceEdgeAttributes(id, updated);
     return { edge: updated, created: false };
   }
+  const latencyHist = durationMs !== void 0 ? recordLatency({}, durationMs) : void 0;
+  const latencyMs = latencyHist ? latencyPercentiles(latencyHist) : void 0;
   const signal = {
     spanCount: 1,
     errorCount: isError ? 1 : 0,
-    lastObservedAgeMs: 0
+    lastObservedAgeMs: 0,
+    ...latencyHist ? { latencyHist } : {},
+    ...latencyMs ? { latencyMs } : {}
   };
   const edge = {
     id,
@@ -5247,6 +5313,7 @@ async function handleSpan(ctx, span) {
   }
   const sourceId = ensureServiceNode(ctx.graph, span.service, env);
   const isError = span.statusCode === 2;
+  const durationMs = span.durationNanos > 0n ? Number(span.durationNanos) / 1e6 : void 0;
   const sourceServiceNode = ctx.graph.getNodeAttributes(sourceId);
   const callSite = callSiteFromSpan(span, sourceServiceNode, ctx.scanPath);
   cacheSpanService(span, nowMs, callSite);
@@ -5285,7 +5352,8 @@ async function handleSpan(ctx, span) {
         targetId,
         ts,
         isError,
-        callSiteEvidence
+        callSiteEvidence,
+        durationMs
       );
       if (result) affectedNode = targetId;
       if (span.dbSystem === "mongodb" && span.dbCollection) {
@@ -5297,7 +5365,8 @@ async function handleSpan(ctx, span) {
           collectionId,
           ts,
           isError,
-          callSiteEvidence
+          callSiteEvidence,
+          durationMs
         );
       }
       if (span.dbTable) {
@@ -5309,7 +5378,8 @@ async function handleSpan(ctx, span) {
           tableId,
           ts,
           isError,
-          callSiteEvidence
+          callSiteEvidence,
+          durationMs
         );
         mergeObservedColumns(ctx.graph, tableId, span.dbColumns);
       }
@@ -5328,7 +5398,8 @@ async function handleSpan(ctx, span) {
       targetId,
       ts,
       isError,
-      callSiteEvidence
+      callSiteEvidence,
+      durationMs
     );
     if (result) affectedNode = targetId;
   } else if (span.graphqlOperationName && span.graphqlOperationType && spanServesGraphqlOperation(span.kind)) {
@@ -5345,7 +5416,8 @@ async function handleSpan(ctx, span) {
       targetId,
       ts,
       isError,
-      callSiteEvidence
+      callSiteEvidence,
+      durationMs
     );
     if (result) affectedNode = targetId;
   } else if (span.rpcSystem === "grpc" && span.rpcService && span.rpcMethod && spanServesGrpcMethod(span.kind)) {
@@ -5357,7 +5429,8 @@ async function handleSpan(ctx, span) {
       targetId,
       ts,
       isError,
-      callSiteEvidence
+      callSiteEvidence,
+      durationMs
     );
     if (result) affectedNode = targetId;
   } else if (span.websocketChannel && spanServesWebsocketChannel(span.kind)) {
@@ -5373,7 +5446,8 @@ async function handleSpan(ctx, span) {
       targetId,
       ts,
       isError,
-      callSiteEvidence
+      callSiteEvidence,
+      durationMs
     );
     if (result) affectedNode = targetId;
   } else {
@@ -5389,7 +5463,8 @@ async function handleSpan(ctx, span) {
           targetId,
           ts,
           isError,
-          callSiteEvidence
+          callSiteEvidence,
+          durationMs
         );
         affectedNode = targetId;
         resolvedViaAddress = true;
@@ -5402,7 +5477,8 @@ async function handleSpan(ctx, span) {
           frontierNodeId,
           ts,
           isError,
-          callSiteEvidence
+          callSiteEvidence,
+          durationMs
         );
         affectedNode = frontierNodeId;
         resolvedViaAddress = true;
@@ -5428,7 +5504,8 @@ async function handleSpan(ctx, span) {
           sourceId,
           ts,
           isError,
-          fallbackEvidence
+          fallbackEvidence,
+          durationMs
         );
       }
     }
@@ -5442,7 +5519,7 @@ async function handleSpan(ctx, span) {
     );
     if (routeNodeId) {
       const routeSvc = ctx.graph.getNodeAttributes(routeNodeId).service;
-      upsertObservedEdge(ctx.graph, import_types7.EdgeType.CONTAINS, (0, import_types7.serviceId)(routeSvc), routeNodeId, ts, isError);
+      upsertObservedEdge(ctx.graph, import_types7.EdgeType.CONTAINS, (0, import_types7.serviceId)(routeSvc), routeNodeId, ts, isError, void 0, durationMs);
     }
   }
   if (span.statusCode === 2) {
@@ -5942,7 +6019,7 @@ var rootCauseShapes = {
   [import_types8.NodeType.FileNode]: fileRootCauseShape,
   [import_types8.NodeType.SymbolNode]: symbolRootCauseShape
 };
-function getRootCause(graph, errorNodeId, errorEvent, incidents) {
+function legacyRootCause(graph, errorNodeId, errorEvent, incidents) {
   if (!graph.hasNode(errorNodeId)) return null;
   const origin = graph.getNodeAttributes(errorNodeId);
   const shape = rootCauseShapes[origin.type];
@@ -6199,7 +6276,9 @@ function getObservedDependencies(graph, nodeId) {
       dependencies: [],
       observed: false,
       inboundObservedCount: 0,
-      hasExtractedOutbound: false
+      hasExtractedOutbound: false,
+      inboundVolume: 0,
+      window: "lifetime"
     });
   }
   const attrs = graph.getNodeAttributes(nodeId);
@@ -6230,11 +6309,19 @@ function getObservedDependencies(graph, nodeId) {
     }
   }
   let inboundObservedCount = 0;
+  let inboundVolume = 0;
+  let inboundLastObserved;
   for (const tgt of scope) {
     for (const edgeId of graph.inboundEdges(tgt)) {
       const e = graph.getEdgeAttributes(edgeId);
       if (e.type === import_types8.EdgeType.CONTAINS) continue;
-      if (e.provenance === import_types8.Provenance.OBSERVED) inboundObservedCount += 1;
+      if (e.provenance === import_types8.Provenance.OBSERVED) {
+        inboundObservedCount += 1;
+        inboundVolume += e.callCount ?? e.signal?.spanCount ?? 1;
+        if (e.lastObserved && (!inboundLastObserved || e.lastObserved > inboundLastObserved)) {
+          inboundLastObserved = e.lastObserved;
+        }
+      }
     }
   }
   dependencies.sort(
@@ -6245,7 +6332,291 @@ function getObservedDependencies(graph, nodeId) {
     dependencies,
     observed: dependencies.length > 0 || inboundObservedCount > 0,
     inboundObservedCount,
-    hasExtractedOutbound
+    hasExtractedOutbound,
+    // The signal is cumulative, so the honest window label is "lifetime" (ADR-190).
+    inboundVolume,
+    window: "lifetime",
+    ...inboundLastObserved ? { inboundLastObserved } : {}
+  });
+}
+var SATURATION_P95_MS = 1e3;
+function nodeScope(graph, nodeId) {
+  const scope = [nodeId];
+  if (!graph.hasNode(nodeId)) return scope;
+  const attrs = graph.getNodeAttributes(nodeId);
+  if (attrs.type === import_types8.NodeType.ServiceNode) {
+    for (const edgeId of graph.outboundEdges(nodeId)) {
+      const e = graph.getEdgeAttributes(edgeId);
+      if (e.type !== import_types8.EdgeType.CONTAINS) continue;
+      const owned = graph.getNodeAttributes(e.target);
+      if (owned.type === import_types8.NodeType.FileNode) scope.push(e.target);
+    }
+  }
+  return scope;
+}
+function incidentCountForNode(nodeId, incidents) {
+  if (!incidents || incidents.length === 0) return 0;
+  return incidents.filter((ev) => incidentMatchesNode(ev, nodeId)).length;
+}
+function nodeContext(graph, nodeId, incidents, now = Date.now()) {
+  const scope = nodeScope(graph, nodeId);
+  let errorsFromCallers = 0;
+  let inboundVolume = 0;
+  let outboundVolume = 0;
+  let outboundErrors = 0;
+  let latestInboundMs;
+  let latencyP95Ms;
+  let stale = false;
+  for (const n of scope) {
+    if (!graph.hasNode(n)) continue;
+    for (const edgeId of graph.inboundEdges(n)) {
+      const e = graph.getEdgeAttributes(edgeId);
+      if (e.type === import_types8.EdgeType.CONTAINS) continue;
+      errorsFromCallers += e.signal?.errorCount ?? 0;
+      inboundVolume += e.callCount ?? e.signal?.spanCount ?? 0;
+      if (e.provenance === import_types8.Provenance.STALE) stale = true;
+      const p95 = e.signal?.latencyMs?.p95;
+      if (p95 !== void 0) latencyP95Ms = Math.max(latencyP95Ms ?? 0, p95);
+      if (e.lastObserved) {
+        const t = Date.parse(e.lastObserved);
+        if (Number.isFinite(t)) latestInboundMs = Math.max(latestInboundMs ?? 0, t);
+      }
+    }
+    for (const edgeId of graph.outboundEdges(n)) {
+      const e = graph.getEdgeAttributes(edgeId);
+      if (e.type === import_types8.EdgeType.CONTAINS) continue;
+      outboundVolume += e.callCount ?? e.signal?.spanCount ?? 0;
+      if (e.type === import_types8.EdgeType.CALLS) outboundErrors += e.signal?.errorCount ?? 0;
+      if (e.provenance === import_types8.Provenance.STALE) stale = true;
+    }
+  }
+  const errorsEmittedHere = incidentCountForNode(nodeId, incidents) + outboundErrors;
+  const lastObservedAgeMs = latestInboundMs !== void 0 ? Math.max(0, now - latestInboundMs) : void 0;
+  return {
+    errorsEmittedHere,
+    errorsFromCallers,
+    callCount: inboundVolume,
+    outboundVolume,
+    ...lastObservedAgeMs !== void 0 ? { lastObservedAgeMs } : {},
+    ...latencyP95Ms !== void 0 ? { latencyP95Ms } : {},
+    stale
+  };
+}
+function isSaturated(ctx) {
+  return ctx.latencyP95Ms !== void 0 && ctx.latencyP95Ms >= SATURATION_P95_MS;
+}
+function classifyNode(ctx) {
+  if (ctx.errorsEmittedHere > 0) {
+    if ((ctx.stale || isSaturated(ctx)) && ctx.errorsFromCallers >= ctx.errorsEmittedHere) {
+      return "symptom-only";
+    }
+    return "primary-failure";
+  }
+  if (ctx.errorsFromCallers > 0) return "symptom-only";
+  return "unrelated";
+}
+function isVictimSeed(ctx) {
+  return ctx.errorsFromCallers > 0 && (ctx.stale || isSaturated(ctx)) && ctx.errorsEmittedHere <= ctx.errorsFromCallers;
+}
+function grainOf(graph, nodeId) {
+  if (!graph.hasNode(nodeId)) return "unknown";
+  const t = graph.getNodeAttributes(nodeId).type;
+  if (t === import_types8.NodeType.ServiceNode) return "service";
+  if (t === import_types8.NodeType.FileNode) return "file";
+  if (t === import_types8.NodeType.SymbolNode) return "symbol";
+  return t;
+}
+function findPath(graph, from, to, direction, maxDepth) {
+  if (!graph.hasNode(from) || !graph.hasNode(to)) return null;
+  if (from === to) return { nodes: [from], edges: [] };
+  const queue = [{ nodeId: from, depth: 0, nodes: [from], edges: [] }];
+  const enqueued = /* @__PURE__ */ new Set([from]);
+  while (queue.length > 0) {
+    const frame = queue.shift();
+    if (frame.depth >= maxDepth) continue;
+    const best = direction === "up" ? bestEdgeBySource(graph, graph.inboundEdges(frame.nodeId)) : bestEdgeByTarget(graph, graph.outboundEdges(frame.nodeId));
+    const neighbours = [...best.entries()].sort((a, b) => a[0].localeCompare(b[0]));
+    for (const [nid, edge] of neighbours) {
+      if (nid === to) return { nodes: [...frame.nodes, nid], edges: [...frame.edges, edge] };
+      if (enqueued.has(nid)) continue;
+      enqueued.add(nid);
+      queue.push({
+        nodeId: nid,
+        depth: frame.depth + 1,
+        nodes: [...frame.nodes, nid],
+        edges: [...frame.edges, edge]
+      });
+    }
+  }
+  return null;
+}
+var EMPTY_CONTEXT = {
+  errorsEmittedHere: 0,
+  errorsFromCallers: 0,
+  callCount: 0,
+  outboundVolume: 0,
+  stale: false
+};
+function expandNode(graph, nodeId, direction, incidents, now = Date.now()) {
+  if (!graph.hasNode(nodeId)) {
+    return import_types8.ExpandResultSchema.parse({
+      origin: nodeId,
+      direction,
+      node: { id: nodeId, classification: "unrelated", context: EMPTY_CONTEXT },
+      neighbours: []
+    });
+  }
+  const ctx = nodeContext(graph, nodeId, incidents, now);
+  const best = direction === "up" ? bestEdgeBySource(graph, graph.inboundEdges(nodeId)) : bestEdgeByTarget(graph, graph.outboundEdges(nodeId));
+  const neighbours = [];
+  for (const [nid, edge] of best) {
+    if (edge.type === import_types8.EdgeType.CONTAINS) continue;
+    const nctx = nodeContext(graph, nid, incidents, now);
+    neighbours.push({
+      node: nid,
+      edgeType: edge.type,
+      provenance: edge.provenance,
+      classification: classifyNode(nctx),
+      context: nctx
+    });
+  }
+  neighbours.sort((a, b) => a.node.localeCompare(b.node));
+  return import_types8.ExpandResultSchema.parse({
+    origin: nodeId,
+    direction,
+    node: { id: nodeId, classification: classifyNode(ctx), context: ctx },
+    neighbours
+  });
+}
+function relate(graph, a, b, maxDepth = ROOT_CAUSE_MAX_DEPTH) {
+  const buildPath = (fp) => ({
+    nodes: fp.nodes,
+    edgeTypes: fp.edges.map((e) => e.type),
+    provenance: fp.edges.map((e) => e.provenance),
+    grain: fp.nodes.map((n) => grainOf(graph, n)),
+    // The failure runs end to end when every hop carries error / latency / alert
+    // signal — that is what turns reachability into cause-confirmation.
+    carriesSignal: fp.edges.length > 0 && fp.edges.every(
+      (e) => (e.signal?.errorCount ?? 0) > 0 || e.signal?.latencyMs !== void 0 || e.signal?.anomalous !== void 0
+    )
+  });
+  if (!graph.hasNode(a) || !graph.hasNode(b)) {
+    return import_types8.RelateResultSchema.parse({
+      a,
+      b,
+      related: false,
+      direction: null,
+      paths: [],
+      note: !graph.hasNode(a) ? `node not found: ${a}` : `node not found: ${b}`
+    });
+  }
+  const down = findPath(graph, a, b, "down", maxDepth);
+  const up = findPath(graph, a, b, "up", maxDepth);
+  if (!down && !up) {
+    return import_types8.RelateResultSchema.parse({
+      a,
+      b,
+      related: false,
+      direction: null,
+      paths: [],
+      note: `no path within ${maxDepth} hops`
+    });
+  }
+  const paths = [];
+  const direction = down ? "a->b" : "b->a";
+  if (down) paths.push(buildPath(down));
+  if (up) paths.push(buildPath(up));
+  const endpointsFine = grainOf(graph, a) !== "service" && grainOf(graph, b) !== "service";
+  const grainGap = endpointsFine && paths[0].grain.some((g) => g === "service");
+  return import_types8.RelateResultSchema.parse({
+    a,
+    b,
+    related: true,
+    direction,
+    paths,
+    ...grainGap ? { grainGap: true } : {}
+  });
+}
+function findLoadOrigin(graph, alertNodeId, incidents, now) {
+  const upstream = getBlastRadius(graph, alertNodeId).affectedNodes.map((n) => n.nodeId);
+  let best = null;
+  for (const nid of upstream) {
+    if (nid === alertNodeId) continue;
+    const ctx = nodeContext(graph, nid, incidents, now);
+    if (ctx.outboundVolume === 0) continue;
+    const isSource = ctx.callCount === 0;
+    const better = !best || (isSource !== best.isSource ? isSource : ctx.outboundVolume !== best.ctx.outboundVolume ? ctx.outboundVolume > best.ctx.outboundVolume : nid < best.node);
+    if (better) best = { node: nid, ctx, isSource };
+  }
+  return best ? { node: best.node, ctx: best.ctx } : null;
+}
+function getRootCause(graph, errorNodeId, errorEvent, incidents, opts) {
+  const legacy = legacyRootCause(graph, errorNodeId, errorEvent, incidents);
+  if (!legacy) return null;
+  const navigation = opts?.navigation ?? process.env.NEAT_RCA_NAVIGATION !== "0";
+  if (!navigation) return legacy;
+  return enrichWithNavigation(graph, errorNodeId, legacy, incidents, opts?.now ?? Date.now());
+}
+function enrichWithNavigation(graph, errorNodeId, legacy, incidents, now) {
+  const seedNode = legacy.rootCauseNode;
+  const seedCtx = graph.hasNode(seedNode) ? nodeContext(graph, seedNode, incidents, now) : null;
+  const lastProv = legacy.edgeProvenances[legacy.edgeProvenances.length - 1];
+  const candidates = [];
+  if (seedCtx && isVictimSeed(seedCtx)) {
+    const origin = findLoadOrigin(graph, errorNodeId, incidents, now);
+    if (origin) {
+      const path68 = findPath(graph, errorNodeId, origin.node, "up", ROOT_CAUSE_MAX_DEPTH);
+      const originConfidence = confidenceFromMix(path68?.edges ?? [], now);
+      candidates.push({
+        node: origin.node,
+        classification: "primary-failure",
+        reason: `Highest-volume upstream source (${origin.ctx.outboundVolume} observed outbound calls) driving a saturated/stale subgraph; the alerting path decays downstream into a starved victim rather than a fault at the callee.`,
+        context: origin.ctx,
+        confidence: Math.max(0.3, Math.min(0.8, originConfidence || 0.5)),
+        provenance: import_types8.Provenance.OBSERVED
+      });
+    }
+    const staleNote = seedCtx.stale ? "; the node has gone STALE" : "";
+    const satNote = isSaturated(seedCtx) ? `; inbound p95 ${Math.round(seedCtx.latencyP95Ms)}ms is saturated` : "";
+    candidates.push({
+      node: seedNode,
+      classification: "symptom-only",
+      reason: `Errors arrive from callers (${seedCtx.errorsFromCallers}) but none originate here${staleNote}${satNote} \u2014 a downstream victim of load, not the fault.`,
+      context: seedCtx,
+      confidence: Math.min(legacy.confidence, 0.4),
+      ...lastProv ? { provenance: lastProv } : {}
+    });
+  } else {
+    candidates.push({
+      node: seedNode,
+      classification: "primary-failure",
+      reason: legacy.rootCauseReason,
+      context: seedCtx ?? EMPTY_CONTEXT,
+      confidence: legacy.confidence,
+      ...lastProv ? { provenance: lastProv } : {}
+    });
+  }
+  const top = candidates[0];
+  let traversalPath = legacy.traversalPath;
+  let edgeProvenances = legacy.edgeProvenances;
+  if (top.node !== seedNode) {
+    const path68 = findPath(graph, errorNodeId, top.node, "up", ROOT_CAUSE_MAX_DEPTH);
+    if (path68) {
+      traversalPath = path68.nodes;
+      edgeProvenances = path68.edges.map((e) => e.provenance);
+    } else {
+      traversalPath = [errorNodeId, top.node];
+      edgeProvenances = [top.provenance ?? import_types8.Provenance.OBSERVED];
+    }
+  }
+  return import_types8.RootCauseResultSchema.parse({
+    rootCauseNode: top.node,
+    rootCauseReason: top.reason,
+    traversalPath,
+    edgeProvenances,
+    confidence: top.confidence,
+    ...legacy.fixRecommendation ? { fixRecommendation: legacy.fixRecommendation } : {},
+    candidates
   });
 }
 
@@ -18039,6 +18410,34 @@ function registerRoutes(scope, ctx) {
     }
     return getBlastRadius(proj.graph, nodeId, depth);
   });
+  scope.get("/graph/expand/:nodeId", async (req, reply) => {
+    const proj = resolveProject(registry, req, reply, ctx.bootstrap, ctx.singleProject);
+    if (!proj) return;
+    const { nodeId } = req.params;
+    if (!proj.graph.hasNode(nodeId)) {
+      return reply.code(404).send({ error: "node not found", id: nodeId });
+    }
+    const direction = req.query.direction;
+    if (direction !== "up" && direction !== "down") {
+      return reply.code(400).send({ error: 'direction must be "up" or "down"' });
+    }
+    const epath = errorsPathFor(proj);
+    const incidents = epath ? await readErrorEvents(epath) : [];
+    return expandNode(proj.graph, nodeId, direction, incidents);
+  });
+  scope.get("/graph/relate", async (req, reply) => {
+    const proj = resolveProject(registry, req, reply, ctx.bootstrap, ctx.singleProject);
+    if (!proj) return;
+    const { a, b } = req.query;
+    if (!a || !b) {
+      return reply.code(400).send({ error: "both a and b query params are required" });
+    }
+    const maxDepth = req.query.maxDepth ? Number(req.query.maxDepth) : void 0;
+    if (maxDepth !== void 0 && (!Number.isFinite(maxDepth) || maxDepth < 1)) {
+      return reply.code(400).send({ error: "maxDepth must be a positive integer" });
+    }
+    return relate(proj.graph, a, b, maxDepth);
+  });
   scope.get("/search", async (req, reply) => {
     const proj = resolveProject(registry, req, reply, ctx.bootstrap, ctx.singleProject);
     if (!proj) return;