@neat.is/types 0.7.9 → 0.8.0-rc.1

package/dist/index.cjs

@@ -49,11 +49,14 @@ __export(index_exports, {
   DivergenceTypeSchema: () => DivergenceTypeSchema,
   EMPTY_REGISTRY: () => EMPTY_REGISTRY,
   EXTRACTED_CONFIDENCE: () => EXTRACTED_CONFIDENCE,
+  EdgeAnomalySchema: () => EdgeAnomalySchema,
   EdgeEvidenceSchema: () => EdgeEvidenceSchema,
   EdgeSignalSchema: () => EdgeSignalSchema,
   EdgeType: () => EdgeType,
   EdgeTypeSchema: () => EdgeTypeSchema,
   ErrorEventSchema: () => ErrorEventSchema,
+  ExpandNeighbourSchema: () => ExpandNeighbourSchema,
+  ExpandResultSchema: () => ExpandResultSchema,
   ExtractionCoverageSchema: () => ExtractionCoverageSchema,
   FieldGuardRuleSchema: () => FieldGuardRuleSchema,
   FileNodeSchema: () => FileNodeSchema,
@@ -70,12 +73,15 @@ __export(index_exports, {
   HypotheticalActionSchema: () => HypotheticalActionSchema,
   IncidentsResponseSchema: () => IncidentsResponseSchema,
   InfraNodeSchema: () => InfraNodeSchema,
+  LatencyMsSchema: () => LatencyMsSchema,
   LogEntrySchema: () => LogEntrySchema,
   LogSourceSchema: () => LogSourceSchema,
   LogsResponseSchema: () => LogsResponseSchema,
   MCP_TOOL_NAMES: () => MCP_TOOL_NAMES,
   MissingExtractedDivergenceSchema: () => MissingExtractedDivergenceSchema,
   MissingObservedDivergenceSchema: () => MissingObservedDivergenceSchema,
+  NodeClassificationSchema: () => NodeClassificationSchema,
+  NodeContextSchema: () => NodeContextSchema,
   NodeType: () => NodeType,
   NodeTypeSchema: () => NodeTypeSchema,
   ObservedDependenciesResultSchema: () => ObservedDependenciesResultSchema,
@@ -97,6 +103,9 @@ __export(index_exports, {
   RegistryEntrySchema: () => RegistryEntrySchema,
   RegistryFileSchema: () => RegistryFileSchema,
   RegistryStatusSchema: () => RegistryStatusSchema,
+  RelatePathSchema: () => RelatePathSchema,
+  RelateResultSchema: () => RelateResultSchema,
+  RootCauseCandidateSchema: () => RootCauseCandidateSchema,
   RootCauseResultSchema: () => RootCauseResultSchema,
   RouteNodeSchema: () => RouteNodeSchema,
   SearchMatchSchema: () => SearchMatchSchema,
@@ -324,10 +333,30 @@ var EdgeEvidenceSchema = import_zod2.z.object({
   method: import_zod2.z.string().optional(),
   pathTemplate: import_zod2.z.string().optional()
 });
+var LatencyMsSchema = import_zod2.z.object({
+  p50: import_zod2.z.number().nonnegative(),
+  p95: import_zod2.z.number().nonnegative()
+});
+var EdgeAnomalySchema = import_zod2.z.union([
+  import_zod2.z.object({ source: import_zod2.z.string(), rule: import_zod2.z.string() }),
+  import_zod2.z.boolean()
+]);
 var EdgeSignalSchema = import_zod2.z.object({
   spanCount: import_zod2.z.number().int().nonnegative(),
   errorCount: import_zod2.z.number().int().nonnegative(),
-  lastObservedAgeMs: import_zod2.z.number().nonnegative().optional()
+  lastObservedAgeMs: import_zod2.z.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: import_zod2.z.record(import_zod2.z.string(), import_zod2.z.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 = import_zod2.z.object({
   id: import_zod2.z.string(),
@@ -680,13 +709,98 @@ var LogEntrySchema = import_zod4.z.object({
 
 // src/results.ts
 var import_zod5 = require("zod");
+var NodeContextSchema = import_zod5.z.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: import_zod5.z.number().int().nonnegative(),
+  // Errors arriving from callers: the inbound edges' errorCount. Errors arriving
+  // with none emitted here is the victim signature.
+  errorsFromCallers: import_zod5.z.number().int().nonnegative(),
+  // Inbound call volume through the node — how hard production hits it.
+  callCount: import_zod5.z.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: import_zod5.z.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: import_zod5.z.number().nonnegative().optional(),
+  // Saturation: the worst inbound p95 latency (ms), from ADR-190. High absolute
+  // latency with low error emission reads as saturated.
+  latencyP95Ms: import_zod5.z.number().nonnegative().optional(),
+  // Is the node fed by STALE edges — did it stop responding?
+  stale: import_zod5.z.boolean()
+});
+var NodeClassificationSchema = import_zod5.z.enum([
+  "primary-failure",
+  "symptom-only",
+  "unrelated"
+]);
+var RootCauseCandidateSchema = import_zod5.z.object({
+  node: import_zod5.z.string(),
+  classification: NodeClassificationSchema,
+  reason: import_zod5.z.string(),
+  context: NodeContextSchema,
+  confidence: import_zod5.z.number().min(0).max(1),
+  provenance: ProvenanceSchema.optional()
+});
 var RootCauseResultSchema = import_zod5.z.object({
   rootCauseNode: import_zod5.z.string(),
   rootCauseReason: import_zod5.z.string(),
   traversalPath: import_zod5.z.array(import_zod5.z.string()),
   edgeProvenances: import_zod5.z.array(ProvenanceSchema),
   confidence: import_zod5.z.number().min(0).max(1),
-  fixRecommendation: import_zod5.z.string().optional()
+  fixRecommendation: import_zod5.z.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: import_zod5.z.array(RootCauseCandidateSchema).optional()
+});
+var RelatePathSchema = import_zod5.z.object({
+  // origin → ... → target, the node ids along the path.
+  nodes: import_zod5.z.array(import_zod5.z.string()).min(2),
+  // The edge type of each hop (length = nodes.length - 1).
+  edgeTypes: import_zod5.z.array(EdgeTypeSchema),
+  // The provenance of each hop.
+  provenance: import_zod5.z.array(ProvenanceSchema),
+  // The grain of each node on the path ('service' | 'file' | 'symbol' | other
+  // node type), so a cross-grain descent is legible.
+  grain: import_zod5.z.array(import_zod5.z.string()),
+  // Does the failure run end to end — errorCount / latency / anomalous on every
+  // hop? A signal-carrying path turns reachability into cause-confirmation.
+  carriesSignal: import_zod5.z.boolean()
+});
+var RelateResultSchema = import_zod5.z.object({
+  a: import_zod5.z.string(),
+  b: import_zod5.z.string(),
+  related: import_zod5.z.boolean(),
+  direction: import_zod5.z.enum(["a->b", "b->a"]).nullable(),
+  paths: import_zod5.z.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: import_zod5.z.boolean().optional(),
+  // The terminal-honesty label when related is false.
+  note: import_zod5.z.string().optional()
+});
+var ExpandNeighbourSchema = import_zod5.z.object({
+  node: import_zod5.z.string(),
+  edgeType: EdgeTypeSchema,
+  provenance: ProvenanceSchema,
+  classification: NodeClassificationSchema,
+  context: NodeContextSchema
+});
+var ExpandResultSchema = import_zod5.z.object({
+  origin: import_zod5.z.string(),
+  direction: import_zod5.z.enum(["up", "down"]),
+  node: import_zod5.z.object({
+    id: import_zod5.z.string(),
+    classification: NodeClassificationSchema,
+    context: NodeContextSchema
+  }),
+  neighbours: import_zod5.z.array(ExpandNeighbourSchema)
 });
 var BlastRadiusAffectedNodeSchema = import_zod5.z.object({
   nodeId: import_zod5.z.string(),
@@ -739,7 +853,21 @@ var ObservedDependenciesResultSchema = import_zod5.z.object({
   inboundObservedCount: import_zod5.z.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: import_zod5.z.boolean()
+  hasExtractedOutbound: import_zod5.z.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: import_zod5.z.number().int().nonnegative().optional(),
+  window: import_zod5.z.enum(["7d", "lifetime"]).optional(),
+  inboundLastObserved: import_zod5.z.string().datetime().optional()
 });
 
 // src/identity.ts
@@ -1234,6 +1362,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",
@@ -1448,11 +1579,14 @@ function passesExtractedFloor(confidence) {
   DivergenceTypeSchema,
   EMPTY_REGISTRY,
   EXTRACTED_CONFIDENCE,
+  EdgeAnomalySchema,
   EdgeEvidenceSchema,
   EdgeSignalSchema,
   EdgeType,
   EdgeTypeSchema,
   ErrorEventSchema,
+  ExpandNeighbourSchema,
+  ExpandResultSchema,
   ExtractionCoverageSchema,
   FieldGuardRuleSchema,
   FileNodeSchema,
@@ -1469,12 +1603,15 @@ function passesExtractedFloor(confidence) {
   HypotheticalActionSchema,
   IncidentsResponseSchema,
   InfraNodeSchema,
+  LatencyMsSchema,
   LogEntrySchema,
   LogSourceSchema,
   LogsResponseSchema,
   MCP_TOOL_NAMES,
   MissingExtractedDivergenceSchema,
   MissingObservedDivergenceSchema,
+  NodeClassificationSchema,
+  NodeContextSchema,
   NodeType,
   NodeTypeSchema,
   ObservedDependenciesResultSchema,
@@ -1496,6 +1633,9 @@ function passesExtractedFloor(confidence) {
   RegistryEntrySchema,
   RegistryFileSchema,
   RegistryStatusSchema,
+  RelatePathSchema,
+  RelateResultSchema,
+  RootCauseCandidateSchema,
   RootCauseResultSchema,
   RouteNodeSchema,
   SearchMatchSchema,