relate_model/agent_plan.rs
1//! The agent-native plan projection (`relate.plan/v1`, LABS-370): the
2//! engine's plan wire form projected onto the stable, snake_case schema
3//! our own bindings hand out — real numbers, no `args` nesting, warnings
4//! carrying the engine's remedy-bearing notifications.
5//!
6//! This is *our* API dialect, deliberately distinct from the Neo4j-facing
7//! projection the Bolt and HTTP surfaces emit (ADR-0357, ADR-0365), which
8//! mirrors Neo4j's own node shape for its tooling. Both read the same
9//! engine wire form through the one typed accessor
10//! ([`plan_node_wire`](crate::wire::plan_node_wire)); neither re-matches
11//! the raw map.
12//!
13//! Schema stability: the document carries its `schema` identifier
14//! (`relate.plan/v1`); a breaking shape change bumps the version and
15//! ships its own ADR. Fields are added, never renamed in place.
16
17use serde_json::{json, Map, Value};
18
19use super::notification_wire::notification_fields;
20use crate::wire::Notification;
21use crate::wire::{plan_node_wire, PlanMetricsWire, PlanNodeWire};
22use crate::CypherValue;
23
24/// The schema identifier every projected document carries.
25pub const SCHEMA: &str = "relate.plan/v1";
26
27/// Project a plan wire tree (the engine's `PlanNode::to_value()` form)
28/// into the agent-native document, as a `serde_json::Value` — the surface
29/// serializes it, exactly as it does the sibling wire documents
30/// (`stats_to_wire_json`, `notifications_to_wire_json`).
31///
32/// `statement` is the planned statement as echoed (`None` for a
33/// hand-built tree); `notifications` is the result's remedy-bearing
34/// notification list (ADR-0363), joined into each node's `warnings` by the
35/// operator id the engine stamps — so an agent reads the diagnosis and the
36/// action beside it. `profiled` is derived from the walked tree itself —
37/// any node carrying runtime metrics makes it a `PROFILE` tree — so the
38/// top-level flag can never contradict the per-node `actual` objects.
39///
40/// # Panics
41///
42/// Panics when the value is not a plan wire tree — the same contract
43/// [`plan_node_wire`] enforces (a wire break is an engine bug, never
44/// silently dropped) — and when an operator-scoped notification stamps an
45/// id no walked node carries, so a warning can never vanish from the
46/// document.
47pub fn plan_document(
48 tree: &CypherValue,
49 statement: Option<&str>,
50 notifications: &[Notification],
51) -> Value {
52 // The subtree totals, one pass over the tree (the one map every
53 // node's `total_time_ms` reads — the same spelling the table's walk
54 // uses, never a second fold).
55 let totals = crate::wire::plan_subtree_totals(tree);
56 // The flat notification list, indexed by operator id in one pass: each
57 // node's `warnings` is then a lookup, never a re-scan of the whole list
58 // per node.
59 let warnings_by_operator = operator_warnings(notifications);
60 let operator_scoped = warnings_by_operator.values().map(Vec::len).sum::<usize>();
61 // The one walk: `node_json` validates each node once (through the
62 // typed accessor) and reports whether its subtree carries runtime
63 // metrics, which is exactly `profiled` — never a second pass and never
64 // a caller-supplied flag that could disagree with the `actual` objects.
65 // It also counts the notifications that joined a node.
66 let mut joined = 0;
67 let (root, profiled) = node_json(
68 &plan_node_wire(tree),
69 &totals,
70 &warnings_by_operator,
71 &mut joined,
72 );
73 // Every operator-scoped notification belongs to a node of the walked
74 // tree; a stamp that matches no node (or matches two) is a
75 // wire-contract break that fails loudly, never a warning silently
76 // dropped from the document.
77 assert_eq!(
78 joined, operator_scoped,
79 "every operator-scoped notification joins exactly one plan node (ADR-0363, ADR-0381): \
80 {operator_scoped} stamped, {joined} joined"
81 );
82 json!({
83 "schema": SCHEMA,
84 "profiled": profiled,
85 "statement": statement,
86 "root": root,
87 })
88}
89
90/// The flat notification list grouped by the operator id each entry
91/// stamps — built in one pass, the index every node's `warnings` lookup
92/// reads. Statement-scoped entries (no operator id) have no node to join.
93fn operator_warnings(notifications: &[Notification]) -> crate::IndexMap<usize, Vec<&Notification>> {
94 let mut by_operator: crate::IndexMap<usize, Vec<&Notification>> = crate::IndexMap::new();
95 for notification in notifications {
96 if let Some(operator_id) = notification.operator_id() {
97 by_operator
98 .entry(operator_id)
99 .or_default()
100 .push(notification);
101 }
102 }
103 by_operator
104}
105
106/// One operator node's document: the display facts, the estimate, the
107/// runtime metrics when the tree is profiled, the typed warnings, and the
108/// children — each read from the validated typed view, never a raw match.
109/// One node's document plus whether its subtree carries runtime metrics
110/// (the fact `profiled` is derived from, reported by the same walk).
111fn node_json(
112 node: &PlanNodeWire<'_>,
113 totals: &crate::IndexMap<i64, i64>,
114 warnings_by_operator: &crate::IndexMap<usize, Vec<&Notification>>,
115 joined: &mut usize,
116) -> (Value, bool) {
117 // The children walk first: each child reports whether its subtree
118 // carries runtime metrics (the fact `profiled` derives from), by the
119 // same single walk.
120 let mut profiled = node.metrics.is_some();
121 let children: Vec<Value> = node
122 .children
123 .iter()
124 .map(|child| {
125 let (child_json, child_profiled) =
126 node_json(&plan_node_wire(child), totals, warnings_by_operator, joined);
127 profiled |= child_profiled;
128 child_json
129 })
130 .collect();
131 // LABS-448: the arm's iteration count — the input clause's rows (the
132 // child operator's `Rows`, the number the table shows one cell up),
133 // named here for consumers that do not walk children. `None` when the
134 // node has no input child (the statement's seed row).
135 let loops = node.children.first().and_then(|first| {
136 plan_node_wire(first)
137 .metrics
138 .map(|m| crate::wire::metric_u64(m.rows))
139 });
140 let mut out = Map::new();
141 out.insert("operator".to_string(), json!(node.operator_type));
142 out.insert("details".to_string(), json!(node.details));
143 out.insert(
144 "identifiers".to_string(),
145 Value::Array(node.identifiers.iter().map(|name| json!(name)).collect()),
146 );
147 out.insert("estimated_rows".to_string(), json!(node.estimated_rows));
148 out.insert(
149 "actual".to_string(),
150 match &node.metrics {
151 Some(metrics) => {
152 // The bundle — the one pairing helper in wire, the same
153 // spelling the table's walk reads, never a second fold or
154 // a re-stated contract here.
155 let facts = crate::wire::profiled_facts(*metrics, totals, node.id);
156 actual_json(&facts.metrics, facts.total_time_ns, loops)
157 }
158 None => Value::Null,
159 },
160 );
161 out.insert("children".to_string(), Value::Array(children));
162 // The operator's warnings: the remedy-bearing notifications raised for
163 // it (ADR-0363), looked up by the operator id the engine stamps — the
164 // diagnosis and the actionable remedy beside it, which is what makes
165 // the document agent-actionable. Each warning is the canonical
166 // notification projection minus the join key the node already scopes,
167 // so the two spellings cannot drift. Always present, `[]` when none:
168 // one absence spelling in the document.
169 //
170 // The id is widened once, through the typed accessor: a malformed id
171 // fails there even when the result carries no notification to join.
172 let operator_id = node.operator_id();
173 let warnings = warnings_by_operator
174 .get(&operator_id)
175 .map(Vec::as_slice)
176 .unwrap_or_default();
177 *joined += warnings.len();
178 out.insert(
179 "warnings".to_string(),
180 Value::Array(
181 warnings
182 .iter()
183 .map(|notification| Value::Object(notification_fields(notification)))
184 .collect(),
185 ),
186 );
187 (Value::Object(out), profiled)
188}
189
190/// The runtime metrics of a profiled node: rows, the operator's own time
191/// in milliseconds (through the wire's one conversion), the subtree total
192/// of that time (cumulative vs self — the node plus every descendant, the
193/// cost of the sub-pipeline it heads), store accesses, the read-kind mix,
194/// and the walk's chosen start when the operator walked one.
195fn actual_json(metrics: &PlanMetricsWire, subtree_ns: i64, loops: Option<u64>) -> Value {
196 let mut out = Map::new();
197 out.insert("rows".to_string(), json!(metrics.rows));
198 out.insert(
199 "time_ms".to_string(),
200 json!(crate::wire::time_ns_ms(metrics.time_ns)),
201 );
202 out.insert(
203 "total_time_ms".to_string(),
204 json!(crate::wire::time_ns_ms(subtree_ns)),
205 );
206 out.insert("db_hits".to_string(), json!(metrics.db_hits));
207 // LABS-448: the phase times behind the read kinds — the seek (the
208 // candidate resolution and admission `node_reads` counts) and the walk
209 // (the relationship traversal `hops`/`neighbor_walks` count),
210 // inclusive of a multi-element pattern's nested phases. The kinds
211 // themselves stay where they are; the phases add only the time
212 // attribution, never a second spelling of a count.
213 out.insert(
214 "seek_ms".to_string(),
215 json!(crate::wire::time_ns_ms(metrics.phases.seek_ns)),
216 );
217 out.insert(
218 "walk_ms".to_string(),
219 json!(crate::wire::time_ns_ms(metrics.phases.walk_ns)),
220 );
221 // LABS-448: the arm's iteration count — always present, `null` when
222 // the node has no input child (the seed row), the one absence
223 // spelling the document uses.
224 out.insert("loops".to_string(), json!(loops));
225 out.insert("memory_bytes".to_string(), json!(metrics.memory_bytes));
226 // ADR-0463: expression allocation bytes, beside the row-materialization
227 // bytes — the two allocation facts PROFILE reports separately.
228 out.insert(
229 "expression_built_bytes".to_string(),
230 json!(metrics.expression_built_bytes),
231 );
232 out.insert("hops".to_string(), json!(metrics.reads.hops));
233 out.insert(
234 "neighbor_walks".to_string(),
235 json!(metrics.reads.neighbor_walks),
236 );
237 out.insert("node_reads".to_string(), json!(metrics.reads.node_reads));
238 // ADR-0468 (LABS-359): whether the operator ran the batch
239 // scan/filter/project chain over `Chunk` — always present, `false`
240 // on every operator the chain declined, so a consumer never faces a
241 // missing-key rule.
242 out.insert("batched".to_string(), json!(metrics.batched));
243 // LABS-645: the batch filter's zone skips — always present, `0` on
244 // every operator that skipped nothing, the same never-missing-key
245 // rule.
246 out.insert("zone_skips".to_string(), json!(metrics.zone_skips));
247 // ADR-0478: the frontier family's run counters — always present as
248 // the nested set, all zeros on every operator the family declined,
249 // the same never-missing-key rule. The NFA rung's own facts ride
250 // the same object (ADR-0516): the cells, the rule memo's hits and
251 // misses, the admission asks by verdict, and the budget fraction
252 // the rule's work spent.
253 out.insert(
254 "frontier".to_string(),
255 json!({
256 "edge_visits": metrics.frontier.edge_visits,
257 "levels": metrics.frontier.levels,
258 "endpoints": metrics.frontier.endpoints,
259 "cells": metrics.frontier.cells,
260 "memo_hits": metrics.frontier.memo_hits,
261 "memo_misses": metrics.frontier.memo_misses,
262 "representative_proofs": metrics.frontier.representative_proofs,
263 "search_proven": metrics.frontier.search_proven,
264 "search_disproven": metrics.frontier.search_disproven,
265 "declined_exhausted": metrics.frontier.declined_exhausted,
266 "budget_fraction": metrics.frontier.budget_fraction,
267 }),
268 );
269 // ADR-0516: the frontier rung's run-time decline — always present,
270 // `null` when the rung never declined, the one absence spelling the
271 // document uses (a consumer never faces a missing-key rule).
272 out.insert(
273 "frontier_decline".to_string(),
274 json!(metrics.frontier_decline),
275 );
276 // Always present, `null` when the operator walked no pattern: the one
277 // absence spelling the document uses (a consumer never faces a
278 // missing-key rule).
279 out.insert(
280 "start".to_string(),
281 match &metrics.start {
282 Some(start) => json!({
283 "element": start.element,
284 "backward": start.backward,
285 "reason": start.reason,
286 }),
287 None => Value::Null,
288 },
289 );
290 // LABS-1117: which rung served the clause's MATCH walk — always
291 // present, `null` when no rung served it (the one absence spelling).
292 out.insert(
293 "kernel".to_string(),
294 match metrics.kernel {
295 Some(rung) => json!({"rung": rung.as_str(), "hops": rung.hops()}),
296 None => Value::Null,
297 },
298 );
299 Value::Object(out)
300}
301
302#[cfg(test)]
303mod tests {
304 use super::*;
305 use crate::wire::plan_test_fixtures::{plan_seek_wire_node, plan_wire_node};
306
307 #[test]
308 fn actual_carries_the_subtree_total() {
309 let scan = plan_wire_node("NodeByLabelScan", 1, Some(3_000_000), vec![]);
310 let root = plan_wire_node("ProduceResults", 0, Some(10_000_000), vec![scan]);
311 let doc = plan_document(&root, Some("MATCH (n) RETURN n"), &[]);
312 assert_eq!(doc["profiled"], true);
313 assert_eq!(
314 doc["root"]["actual"]["time_ms"], 10.0,
315 "the root's own time renders in milliseconds"
316 );
317 assert_eq!(
318 doc["root"]["actual"]["total_time_ms"], 13.0,
319 "the root's total covers itself plus the scan: 10 + 3 = 13 ms"
320 );
321 let child = &doc["root"]["children"][0];
322 assert_eq!(
323 child["actual"]["total_time_ms"], 3.0,
324 "a leaf's total equals its own time"
325 );
326 // An unprofiled tree: no actual, no fabricated total.
327 let explain = plan_document(
328 &plan_wire_node("ProduceResults", 0, None, vec![]),
329 Some("RETURN 1"),
330 &[],
331 );
332 assert!(explain["root"]["actual"].is_null());
333 }
334
335 /// The phases and loops (LABS-448): `seek_ms`/`walk_ms` render the
336 /// phase times beside the kinds they attribute (the kinds stay where
337 /// they are — the phases add only the time, never a second count),
338 /// and `loops` names the input clause's rows for consumers that do
339 /// not walk children (`null` at the root, the seed row).
340 #[test]
341 fn actual_carries_the_phase_times_and_loops() {
342 let scan = plan_wire_node("NodeByLabelScan", 1, Some(3_000_000), vec![]);
343 let root = plan_wire_node("ProduceResults", 0, Some(10_000_000), vec![scan]);
344 let doc = plan_document(&root, Some("MATCH (n) RETURN n"), &[]);
345 // The fixture emits zero phases: the fields render, always
346 // present, zeros rather than absences.
347 assert_eq!(doc["root"]["actual"]["seek_ms"], 0.0);
348 assert_eq!(doc["root"]["actual"]["walk_ms"], 0.0);
349 // The root's loops is its input child's rows (the scan produced
350 // one); the scan itself has no input child (the seed row), so its
351 // loops is null — the one absence spelling.
352 assert_eq!(doc["root"]["actual"]["loops"], 1, "the scan's rows");
353 let child = &doc["root"]["children"][0];
354 assert!(child["actual"]["loops"].is_null());
355 }
356
357 #[test]
358 fn projects_the_document_shape() {
359 let doc = plan_document(
360 &plan_wire_node("ProduceResults", 0, None, vec![]),
361 Some("RETURN 1"),
362 &[],
363 );
364 assert_eq!(doc["schema"], SCHEMA);
365 assert_eq!(doc["profiled"], false);
366 assert_eq!(doc["root"]["operator"], "ProduceResults");
367 assert_eq!(doc["root"]["identifiers"][0], "name");
368 assert!(
369 doc["root"]["warnings"].is_array(),
370 "warnings always present"
371 );
372 assert!(doc["root"]["actual"].is_null());
373 }
374
375 /// ADR-0486: the index-seek operators project into the agent document
376 /// like every other operator — the name, the seek-line details and the
377 /// seek's own count riding `estimated_rows`, no operator-specific
378 /// projection anywhere in the document.
379 #[test]
380 fn the_seek_operators_project_into_the_document() {
381 let seek = plan_seek_wire_node(
382 "NodeIndexSeekByRange",
383 "RANGE INDEX n:User(age) WHERE age > 5, WHERE filter",
384 5,
385 1,
386 );
387 let root = plan_wire_node("ProduceResults", 0, None, vec![seek]);
388 let doc = plan_document(&root, Some("MATCH (n:User) WHERE n.age > 5 RETURN n"), &[]);
389 let node = &doc["root"]["children"][0];
390 assert_eq!(node["operator"], "NodeIndexSeekByRange");
391 assert_eq!(
392 node["details"],
393 "RANGE INDEX n:User(age) WHERE age > 5, WHERE filter"
394 );
395 assert_eq!(node["estimated_rows"], 5);
396 assert!(
397 node["actual"].is_null(),
398 "an EXPLAIN-shaped seek node carries no metrics"
399 );
400 }
401
402 #[test]
403 fn node_warnings_are_the_canonical_notification_projection() {
404 use crate::wire::{notification_keys, notification_to_wire_json, NotificationKind};
405
406 let notification =
407 Notification::new(NotificationKind::CartesianProduct, "no join predicate")
408 .with_operator_id(1);
409 let tree = plan_wire_node(
410 "ProduceResults",
411 0,
412 None,
413 vec![plan_wire_node("CartesianProduct", 1, None, vec![])],
414 );
415 let doc = plan_document(
416 &tree,
417 Some("MATCH (a), (b) RETURN a, b"),
418 std::slice::from_ref(¬ification),
419 );
420
421 let warning = &doc["root"]["children"][0]["warnings"][0];
422 let mut canonical = notification_to_wire_json(¬ification);
423 canonical
424 .as_object_mut()
425 .expect("the canonical notification is an object")
426 .remove(notification_keys::OPERATOR_ID);
427 assert_eq!(
428 *warning, canonical,
429 "the node warning is the canonical notification object minus the join key"
430 );
431 assert!(
432 warning.get(notification_keys::OPERATOR_ID).is_none(),
433 "the node scopes the operator, so the join key is not repeated"
434 );
435 assert_eq!(doc["root"]["warnings"], json!([]));
436 }
437
438 #[test]
439 #[should_panic(expected = "plan wire Id is non-negative")]
440 fn negative_operator_id_is_a_loud_wire_break() {
441 let tree = plan_wire_node("ProduceResults", -1, None, vec![]);
442 let _ = plan_document(&tree, Some("RETURN 1"), &[]);
443 }
444
445 #[test]
446 #[should_panic(expected = "every operator-scoped notification joins exactly one plan node")]
447 fn an_unjoined_operator_notification_is_a_loud_wire_break() {
448 use crate::wire::NotificationKind;
449
450 let notification =
451 Notification::new(NotificationKind::CartesianProduct, "no join predicate")
452 .with_operator_id(7);
453 let tree = plan_wire_node("ProduceResults", 0, None, vec![]);
454 let _ = plan_document(&tree, Some("RETURN 1"), &[notification]);
455 }
456}