@neat.is/types 0.7.10 → 0.8.0

package/dist/index.js

@@ -170,10 +170,30 @@ var EdgeEvidenceSchema = z2.object({
   method: z2.string().optional(),
   pathTemplate: z2.string().optional()
 });
+var LatencyMsSchema = z2.object({
+  p50: z2.number().nonnegative(),
+  p95: z2.number().nonnegative()
+});
+var EdgeAnomalySchema = z2.union([
+  z2.object({ source: z2.string(), rule: z2.string() }),
+  z2.boolean()
+]);
 var EdgeSignalSchema = z2.object({
   spanCount: z2.number().int().nonnegative(),
   errorCount: z2.number().int().nonnegative(),
-  lastObservedAgeMs: z2.number().nonnegative().optional()
+  lastObservedAgeMs: z2.number().nonnegative().optional(),
+  // Per-edge latency (ADR-190). `latencyMs` is derived at each observation from
+  // `latencyHist`, a bounded log-linear (HDR-style) histogram — a sparse
+  // bucket→count map, never raw durations — maintained by upsertObservedEdge via
+  // latency-digest.ts. Both are `.optional()` growth (ADR-031): a legacy edge and
+  // a connector edge without a provider latency carry neither and read honestly
+  // absent. `latencyHist` is the ingest accumulator `latencyMs` is read from;
+  // consumers read `latencyMs`.
+  latencyMs: LatencyMsSchema.optional(),
+  latencyHist: z2.record(z2.string(), z2.number().int().nonnegative()).optional(),
+  // A pre-thresholded external alert riding on the edge (ADR-190). Optional and
+  // empty until an alert source is wired.
+  anomalous: EdgeAnomalySchema.optional()
 });
 var GraphEdgeSchema = z2.object({
   id: z2.string(),
@@ -526,13 +546,98 @@ var LogEntrySchema = z4.object({
 
 // src/results.ts
 import { z as z5 } from "zod";
+var NodeContextSchema = z5.object({
+  // Errors originating at this node: incidents localized here plus its own
+  // outbound CALLS that fail. A node that emits errors is a candidate cause.
+  errorsEmittedHere: z5.number().int().nonnegative(),
+  // Errors arriving from callers: the inbound edges' errorCount. Errors arriving
+  // with none emitted here is the victim signature.
+  errorsFromCallers: z5.number().int().nonnegative(),
+  // Inbound call volume through the node — how hard production hits it.
+  callCount: z5.number().int().nonnegative(),
+  // Outbound call volume — how hard this node drives its own dependencies. A
+  // pure driver of load (high out, no in) is where an overload originates.
+  outboundVolume: z5.number().int().nonnegative(),
+  // Staleness: ms since the node was last observed. A stale node under inbound
+  // load is a starved victim, not a cause.
+  lastObservedAgeMs: z5.number().nonnegative().optional(),
+  // Saturation: the worst inbound p95 latency (ms), from ADR-190. High absolute
+  // latency with low error emission reads as saturated.
+  latencyP95Ms: z5.number().nonnegative().optional(),
+  // Is the node fed by STALE edges — did it stop responding?
+  stale: z5.boolean()
+});
+var NodeClassificationSchema = z5.enum([
+  "primary-failure",
+  "symptom-only",
+  "unrelated"
+]);
+var RootCauseCandidateSchema = z5.object({
+  node: z5.string(),
+  classification: NodeClassificationSchema,
+  reason: z5.string(),
+  context: NodeContextSchema,
+  confidence: z5.number().min(0).max(1),
+  provenance: ProvenanceSchema.optional()
+});
 var RootCauseResultSchema = z5.object({
   rootCauseNode: z5.string(),
   rootCauseReason: z5.string(),
   traversalPath: z5.array(z5.string()),
   edgeProvenances: z5.array(ProvenanceSchema),
   confidence: z5.number().min(0).max(1),
-  fixRecommendation: z5.string().optional()
+  fixRecommendation: z5.string().optional(),
+  // Agent-driven navigation (ADR-189): the ranked candidate set with per-node
+  // classification + evidence. `candidates[0]` is the top-ranked cause and the
+  // legacy `rootCauseNode` above tracks it. Optional growth (ADR-031); present
+  // by default, the legacy verdict fields stay populated for one deprecation
+  // cycle. A saturated downstream victim classifies `symptom-only` here and the
+  // ranking walks up to the load origin instead of naming the victim.
+  candidates: z5.array(RootCauseCandidateSchema).optional()
+});
+var RelatePathSchema = z5.object({
+  // origin → ... → target, the node ids along the path.
+  nodes: z5.array(z5.string()).min(2),
+  // The edge type of each hop (length = nodes.length - 1).
+  edgeTypes: z5.array(EdgeTypeSchema),
+  // The provenance of each hop.
+  provenance: z5.array(ProvenanceSchema),
+  // The grain of each node on the path ('service' | 'file' | 'symbol' | other
+  // node type), so a cross-grain descent is legible.
+  grain: z5.array(z5.string()),
+  // Does the failure run end to end — errorCount / latency / anomalous on every
+  // hop? A signal-carrying path turns reachability into cause-confirmation.
+  carriesSignal: z5.boolean()
+});
+var RelateResultSchema = z5.object({
+  a: z5.string(),
+  b: z5.string(),
+  related: z5.boolean(),
+  direction: z5.enum(["a->b", "b->a"]).nullable(),
+  paths: z5.array(RelatePathSchema),
+  // True when only a coarser-grain link is in evidence than a and b's own grain
+  // — the fine link was never observed, so the coarser one is returned and the
+  // gap flagged rather than a finer link synthesized (file-awareness.md §6).
+  grainGap: z5.boolean().optional(),
+  // The terminal-honesty label when related is false.
+  note: z5.string().optional()
+});
+var ExpandNeighbourSchema = z5.object({
+  node: z5.string(),
+  edgeType: EdgeTypeSchema,
+  provenance: ProvenanceSchema,
+  classification: NodeClassificationSchema,
+  context: NodeContextSchema
+});
+var ExpandResultSchema = z5.object({
+  origin: z5.string(),
+  direction: z5.enum(["up", "down"]),
+  node: z5.object({
+    id: z5.string(),
+    classification: NodeClassificationSchema,
+    context: NodeContextSchema
+  }),
+  neighbours: z5.array(ExpandNeighbourSchema)
 });
 var BlastRadiusAffectedNodeSchema = z5.object({
   nodeId: z5.string(),
@@ -585,7 +690,21 @@ var ObservedDependenciesResultSchema = z5.object({
   inboundObservedCount: z5.number().int().nonnegative(),
   // Are there EXTRACTED outbound edges but no OBSERVED ones? Only then is
   // "static deps exist but no runtime traffic — is OTel running?" the honest note.
-  hasExtractedOutbound: z5.boolean()
+  hasExtractedOutbound: z5.boolean(),
+  // Node-level *inbound* traffic block (ADR-190): how hard and how recently
+  // production hits THIS node, sourced from its inbound OBSERVED edges — the
+  // "served N× in {window}, last seen {age}" story the navigation reads and
+  // neat-action renders. `inboundVolume` is the summed inbound-edge count
+  // (distinct from `inboundObservedCount`, the number of inbound edges).
+  // `window` labels the count ("7d" | "lifetime") so a consumer never renders a
+  // window the data doesn't have; the cumulative signal is "lifetime" today.
+  // `inboundLastObserved` is when production last called this node, raw ISO8601
+  // and never pre-formatted — absent when there is no inbound observation.
+  // All three are optional growth (ADR-031); the producer emits `inboundVolume`
+  // and `window` together, `inboundLastObserved` when there is inbound traffic.
+  inboundVolume: z5.number().int().nonnegative().optional(),
+  window: z5.enum(["7d", "lifetime"]).optional(),
+  inboundLastObserved: z5.string().datetime().optional()
 });
 
 // src/identity.ts
@@ -1080,6 +1199,9 @@ var MCP_TOOL_NAMES = [
   "get_recent_stale_edges",
   "check_policies",
   "get_divergences",
+  // Two-way RCA navigation (ADR-189): step the graph and confirm a link.
+  "expand",
+  "relate",
   // Six /neat extend tools (ADR-081, ADR-086, #387).
   "neat_list_uninstrumented",
   "neat_lookup_instrumentation",
@@ -1293,11 +1415,14 @@ export {
   DivergenceTypeSchema,
   EMPTY_REGISTRY,
   EXTRACTED_CONFIDENCE,
+  EdgeAnomalySchema,
   EdgeEvidenceSchema,
   EdgeSignalSchema,
   EdgeType,
   EdgeTypeSchema,
   ErrorEventSchema,
+  ExpandNeighbourSchema,
+  ExpandResultSchema,
   ExtractionCoverageSchema,
   FieldGuardRuleSchema,
   FileNodeSchema,
@@ -1314,12 +1439,15 @@ export {
   HypotheticalActionSchema,
   IncidentsResponseSchema,
   InfraNodeSchema,
+  LatencyMsSchema,
   LogEntrySchema,
   LogSourceSchema,
   LogsResponseSchema,
   MCP_TOOL_NAMES,
   MissingExtractedDivergenceSchema,
   MissingObservedDivergenceSchema,
+  NodeClassificationSchema,
+  NodeContextSchema,
   NodeType,
   NodeTypeSchema,
   ObservedDependenciesResultSchema,
@@ -1341,6 +1469,9 @@ export {
   RegistryEntrySchema,
   RegistryFileSchema,
   RegistryStatusSchema,
+  RelatePathSchema,
+  RelateResultSchema,
+  RootCauseCandidateSchema,
   RootCauseResultSchema,
   RouteNodeSchema,
   SearchMatchSchema,