relate_model/plan_keys.rs
1//! The plan wire form's key vocabulary (ADR-0344/0345): the names
2//! `PlanNode::to_value` produces and every consumer reads, single-sourced
3//! so drift between producer and consumer is a compile error, not a silent
4//! mismatch. Its own module (the plan-node types and decoder stay in
5//! `plan_wire`); the public path is `wire::plan_keys`.
6
7use crate::wire::KernelRungWire;
8
9pub const OPERATOR_TYPE: &str = "operatorType";
10pub const ARGS: &str = "args";
11pub const IDENTIFIERS: &str = "identifiers";
12pub const CHILDREN: &str = "children";
13pub const ID: &str = "Id";
14pub const DETAILS: &str = "Details";
15pub const ESTIMATED_ROWS: &str = "EstimatedRows";
16/// PROFILE metrics (ADR-0344 phase 2).
17pub const ROWS: &str = "Rows";
18pub const TIME_NS: &str = "TimeNs";
19/// PROFILE metric fields (ADR-0344 metric fields).
20pub const DB_HITS: &str = "DbHits";
21pub const MEMORY_BYTES: &str = "MemoryBytes";
22/// The expression allocation bytes a profiled clause charged against the
23/// ADR-0463 statement budget, emitted with the metric block.
24pub const EXPRESSION_BUILT_BYTES: &str = "ExpressionBuiltBytes";
25/// The store-read mix behind `DbHits` (LABS-369): the kinds the one
26/// total blends — relationship hops, neighbor walks, node-store reads.
27pub const HOPS: &str = "Hops";
28pub const NEIGHBOR_WALKS: &str = "NeighborWalks";
29pub const NODE_READS: &str = "NodeReads";
30/// The phase times the read kinds' store work spent (LABS-448): the
31/// seek (candidate resolution and admission — the `Nodes` kind's
32/// work) and the walk (relationship traversal — the `Rels`/`Degree`
33/// kinds' work), inclusive of a multi-element pattern's nested
34/// phases. Emitted together with the metric block and the kinds.
35pub const SEEK_TIME_NS: &str = "SeekTimeNs";
36/// See [`SEEK_TIME_NS`].
37pub const WALK_TIME_NS: &str = "WalkTimeNs";
38/// The walk's chosen start (LABS-369): the pattern element index, its
39/// direction, and the reason class (`bound-pivot`, `cheapest`,
40/// `seek-anchored`, `index-0`) — the fact an opaque `Expand` hid.
41pub const START_ELEMENT: &str = "StartElement";
42pub const START_BACKWARD: &str = "StartBackward";
43pub const START_REASON: &str = "StartReason";
44/// Which rung served the clause's `MATCH` walk (LABS-1117), one of the
45/// `KERNEL_RUNGS` vocabulary — emitted only when a rung served the
46/// clause, with the metric set (a non-`MATCH` clause and a batch-chain
47/// `MATCH` emit no key).
48pub const KERNEL_RUNG: &str = "KernelRung";
49/// The chain rung's hop count (LABS-1117) — emitted with `KernelRung`
50/// when the rung is the chain, never for another rung.
51pub const KERNEL_HOPS: &str = "KernelHops";
52/// The store's active pattern-engine rung (LABS-1117): `auto`, `nfa`,
53/// or `walk`, emitted on every `MATCH` operator of an EXPLAIN and
54/// PROFILE tree — the one static rung fact the plan can state.
55pub const PATTERN_ENGINE: &str = "PatternEngine";
56/// The kernel-rung vocabulary (LABS-1117), the typed [`KernelRungWire`]'s
57/// name list — one spelling, never a second list and never a fabricated
58/// variant value. The executor's `KernelRung::as_str` reads the same name
59/// constants, and the mapping is pinned by `relate`'s
60/// `decline_and_start_reason_names_match_the_wire_tables`, like the start
61/// reasons and the run-time declines.
62pub const KERNEL_RUNGS: [&str; 4] = KernelRungWire::NAMES;
63/// Whether the clause ran ADR-0468's batch scan/filter/project chain
64/// over `Chunk` (LABS-359) — emitted only when true (like the start
65/// trio's presence-only-when-walked), with the metric set.
66pub const BATCHED: &str = "Batched";
67/// The batch filter's zone skips (LABS-645): conjunct-batch
68/// evaluations the chunk's derived min/max zone metadata provably
69/// replaced with the correct empty survivor set — emitted only when
70/// nonzero (a count's presence-only shape), with the metric set.
71pub const ZONE_SKIPS: &str = "ZoneSkips";
72/// The frontier family's run counters (ADR-0478): the BFS's edge
73/// visits, completed levels, and accepted endpoints — emitted only
74/// when the family ran the clause (`levels > 0`), the three together
75/// (a half-present trio is a wire-contract break), with the metric
76/// set.
77pub const FRONTIER_EDGES: &str = "FrontierEdges";
78pub const FRONTIER_LEVELS: &str = "FrontierLevels";
79pub const FRONTIER_ENDPOINTS: &str = "FrontierEndpoints";
80/// The frontier-NFA rung's own PROFILE facts (ADR-0478 §3, ADR-0516),
81/// riding the frontier trio's presence-only-when-engaged group: the
82/// (node, state) cells the runs created, the re-arrival rule memo's
83/// hits and misses, the admission asks by verdict
84/// (representative-proof / search-proven / search-disproven /
85/// declined-exhausted), and the budget fraction the rule's work
86/// spent — the seven integers and the one float emitted together
87/// with the trio, a half-present set a wire-contract break.
88pub const FRONTIER_CELLS: &str = "FrontierCells";
89pub const FRONTIER_MEMO_HITS: &str = "FrontierMemoHits";
90pub const FRONTIER_MEMO_MISSES: &str = "FrontierMemoMisses";
91pub const FRONTIER_REPRESENTATIVE_PROOFS: &str = "FrontierRepresentativeProofs";
92pub const FRONTIER_SEARCH_PROVEN: &str = "FrontierSearchProven";
93pub const FRONTIER_SEARCH_DISPROVEN: &str = "FrontierSearchDisproven";
94pub const FRONTIER_DECLINED_EXHAUSTED: &str = "FrontierDeclinedExhausted";
95pub const FRONTIER_BUDGET_FRACTION: &str = "FrontierBudgetFraction";
96/// Why the frontier rung did not serve the clause, one of the
97/// `DECLINE_REASONS` vocabulary — emitted with the metric set when the
98/// rung declined at plan time (counters absent: it never ran) or engaged,
99/// ran, and fell through (ADR-0516, counters beside it).
100pub const FRONTIER_DECLINE_REASON: &str = "FrontierDeclineReason";
101/// The decline vocabulary: first the run-time declines (ADR-0516), the
102/// executor's `FrontierRunDecline::as_str` names, then the plan-time
103/// gates' (ADR-0478), `FrontierDecline::as_str` — single-sourced here so
104/// a renamed decline fails loudly at the wire boundary, like the start
105/// reasons.
106pub const DECLINE_REASONS: [&str; 16] = [
107 "rearrival-budget",
108 "table-budget",
109 "multiple-patterns",
110 "carrying-row",
111 "mode",
112 "nested-spine",
113 "all-reduce-group",
114 "pinned-binding",
115 "conjunct",
116 "nfa-shape",
117 "guarded-group",
118 "full-enumeration",
119 "ordered-cap",
120 "path-count",
121 "path-consumer",
122 "cost",
123];
124/// The start-reason vocabulary (LABS-369), the executor's
125/// `StartReason::as_str` names — single-sourced here so a renamed
126/// reason fails loudly at the wire boundary, like the warning names.
127pub const REASONS: [&str; 4] = ["bound-pivot", "cheapest", "seek-anchored", "index-0"];
128/// The typed warnings the node carries (typed node warnings): a list
129/// of warning maps from the [`PlanWarning`](crate::wire::PlanWarning)
130/// vocabulary, present only when the node carries one. Each map
131/// carries the warning's name and, when the warning has a payload
132/// (the `AllNodesScan` warning's suggested index), that payload —
133/// one spelling for the producer and every consumer.
134pub const WARNINGS: &str = "warnings";
135/// The warning map's name field (typed node warnings).
136pub const WARNING_NAME: &str = "name";
137/// The warning map's payload field (typed node warnings): the
138/// `AllNodesScan` warning's suggested property index text.
139pub const WARNING_INDEX: &str = "index";
140/// The Neo4j-facing root args (ADR-0357): the plan's rendered text —
141/// Neo4j's plan root carries it and tooling (Browser's Code tab,
142/// strict clients) renders from it. The engine's own args stay as
143/// they are; the one decoration lives on `PlanNode` (the
144/// `relate` crate's `to_neo4j_value`, this vocabulary's only
145/// writer) and each surface calls it at its boundary.
146pub const STRING_REPRESENTATION: &str = "string-representation";
147/// The planner and runtime identity args (ADR-0357): `planner` names
148/// the planner, `planner-impl`/`planner-version` its implementation
149/// and version; `runtime`/`runtime-impl`/`runtime-version` the same
150/// for the runtime; `version` is the Cypher language version — Neo4j's
151/// plan root carries all of them and tooling (cypher-shell's summary
152/// block, Browser's footer) reads them.
153pub const PLANNER_IMPL: &str = "planner-impl";
154/// See [`PLANNER_IMPL`].
155pub const PLANNER: &str = "planner";
156/// See [`PLANNER_IMPL`].
157pub const PLANNER_VERSION: &str = "planner-version";
158/// See [`PLANNER_IMPL`].
159pub const RUNTIME: &str = "runtime";
160/// See [`PLANNER_IMPL`].
161pub const RUNTIME_IMPL: &str = "runtime-impl";
162/// See [`PLANNER_IMPL`].
163pub const RUNTIME_VERSION: &str = "runtime-version";
164/// See [`PLANNER_IMPL`]: the Cypher language version the plan ran
165/// under.
166pub const VERSION: &str = "version";
167/// See [`PLANNER_IMPL`]: Neo4j's `Memory` arg — the root mirrors this
168/// engine's row-materialization bytes under it (ADR-0357).
169pub const MEMORY: &str = "Memory";