Skip to main content

relate_model/
notification_wire.rs

1//! The query-notification vocabulary and its two wire forms (ADR-0363):
2//! one table of kinds (code, GQLSTATUS, severity, category, title and
3//! canonical remedy), the notification record every surface projects from,
4//! and the native and Neo4j-shaped serializers.
5//!
6//! Lives beside the plan vocabulary in `plan_wire` — whose presentation
7//! model lives with its one consumer in the formatter (ADR-0400) — and is
8//! re-exported through [`super`] so `wire::Notification` is the one public
9//! path, matching that layout.
10//!
11//! Two shapes exist by design (ADR-0363 decisions 9/11/12):
12//!
13//! - the **native** form carries `code`, `gql_status`, `severity`,
14//!   `category`, `title`, `description`, `remedy` and — on operator-scoped
15//!   kinds — `operator_id`, with the diagnosis and the action as separate
16//!   fields;
17//! - the **Neo4j-shaped** form (Bolt and the HTTP Query API v2) carries
18//!   exactly `code`, `title`, `description`, `severity`, `category`; the
19//!   remedy folds into `description` as ` (remedy: <remedy>)` and no
20//!   `remedy` or `position` key ever appears.
21
22use serde_json::{Map, Value};
23
24/// The severity spellings (ADR-0363 decision 1): Neo4j's two severities.
25#[derive(Clone, Copy, Debug, PartialEq, Eq)]
26pub enum NotificationSeverity {
27    /// An informational hint (`INFORMATION`).
28    Information,
29    /// A warning (`WARNING`).
30    Warning,
31}
32
33impl NotificationSeverity {
34    /// The wire spelling — the one severity vocabulary.
35    pub fn as_str(self) -> &'static str {
36        match self {
37            NotificationSeverity::Information => "INFORMATION",
38            NotificationSeverity::Warning => "WARNING",
39        }
40    }
41}
42
43impl std::fmt::Display for NotificationSeverity {
44    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
45        f.write_str(self.as_str())
46    }
47}
48
49/// The category spellings (ADR-0363 decision 1): the categories in scope.
50#[derive(Clone, Copy, Debug, PartialEq, Eq)]
51pub enum NotificationCategory {
52    /// A performance hint (`PERFORMANCE`).
53    Performance,
54    /// A name the catalog does not know (`UNRECOGNIZED`).
55    Unrecognized,
56    /// A deprecated feature (`DEPRECATION`).
57    Deprecation,
58    /// A schema DDL note (`SCHEMA`): the informational 00NA0-00NA2 family.
59    Schema,
60    /// An unfulfilled planner hint (`HINT`): the 01N31/01N30 family.
61    Hint,
62}
63
64impl NotificationCategory {
65    /// The wire spelling — the one category vocabulary.
66    pub fn as_str(self) -> &'static str {
67        match self {
68            NotificationCategory::Performance => "PERFORMANCE",
69            NotificationCategory::Unrecognized => "UNRECOGNIZED",
70            NotificationCategory::Deprecation => "DEPRECATION",
71            NotificationCategory::Schema => "SCHEMA",
72            NotificationCategory::Hint => "HINT",
73        }
74    }
75}
76
77impl std::fmt::Display for NotificationCategory {
78    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
79        f.write_str(self.as_str())
80    }
81}
82
83/// One row of the notification vocabulary (ADR-0363 decision 1). The
84/// trigger column of the ADR's table is documentation for the detector
85/// nodes; the runtime needs the metadata below.
86struct NotificationRow {
87    code: &'static str,
88    gql_status: &'static str,
89    severity: NotificationSeverity,
90    category: NotificationCategory,
91    title: &'static str,
92    remedy: &'static str,
93    /// Whether the plan table renders this kind in its `Warnings` column
94    /// (ADR-0363 decision 8) — the one membership fact `is_plan_warning`
95    /// reads.
96    plan_warning: bool,
97    /// Whether two notifications of this kind with the same description
98    /// are two occurrences that must both be reported (ADR-0363
99    /// decision 6) — the one membership fact `dedups_identical` reads.
100    /// Neo4j reports one notification per occurrence (a deprecated call,
101    /// a clause-shaped deprecation, a per-hint diagnostic), so those kinds
102    /// set it; a name-based diagnostic collapses and does not.
103    occurrence_scoped: bool,
104}
105
106// The one notification vocabulary (ADR-0363 decision 1): every kind's code,
107// GQLSTATUS, severity, category, title and canonical remedy, one entry per
108// kind. Engine-own kinds use the `Relate.Notification.*` namespace and a `C`
109// in GQLSTATUS position 3; a kind whose diagnostic matches Neo4j's keeps
110// Neo4j's code and status.
111//
112// The one macro generates the `NotificationKind` enum, its `ALL` listing and
113// the exhaustive variant-to-row binding from this single table, so a new
114// kind is one entry and cannot be omitted from any of the three.
115macro_rules! notification_vocabulary {
116    ($(
117        $(#[$doc:meta])*
118        $kind:ident {
119            code: $code:expr,
120            gql_status: $gql_status:expr,
121            severity: $severity:expr,
122            category: $category:expr,
123            title: $title:expr,
124            remedy: $remedy:expr,
125            plan_warning: $plan_warning:expr,
126            occurrence_scoped: $occurrence_scoped:expr $(,)?
127        }
128    )*) => {
129        /// The notification kinds (ADR-0363 decision 1) — the row identities
130        /// of the one vocabulary below, generated from its single table.
131        #[derive(Clone, Copy, Debug, PartialEq, Eq, Hash)]
132        pub enum NotificationKind {
133            $($(#[$doc])* $kind,)*
134        }
135
136        impl NotificationKind {
137            /// Every kind, in vocabulary order.
138            #[cfg(test)]
139            pub(crate) const ALL: &'static [NotificationKind] =
140                &[$(NotificationKind::$kind),*];
141
142            /// The vocabulary row for this kind — the one lookup every
143            /// metadata accessor reads, so no accessor re-spells a code or
144            /// status.
145            fn row(self) -> &'static NotificationRow {
146                match self {
147                    $(NotificationKind::$kind => &NotificationRow {
148                        code: $code,
149                        gql_status: $gql_status,
150                        severity: $severity,
151                        category: $category,
152                        title: $title,
153                        remedy: $remedy,
154                        plan_warning: $plan_warning,
155                        occurrence_scoped: $occurrence_scoped,
156                    },)*
157                }
158            }
159        }
160    };
161}
162
163notification_vocabulary! {
164    /// A multi-pattern `MATCH` whose patterns share no join anchor.
165    CartesianProduct {
166        code: "Neo.ClientNotification.Statement.CartesianProduct",
167        gql_status: "03N90",
168        severity: NotificationSeverity::Information,
169        category: NotificationCategory::Performance,
170        title: "Cartesian product",
171        remedy: "Give the patterns a join anchor: reuse a node variable across them, or add a \
172                 pattern that relates their endpoints; otherwise run them as separate queries.",
173        plan_warning: true,
174        occurrence_scoped: true,
175    }
176    /// A variable-length relationship pattern with no upper bound.
177    UnboundedVariableLengthPattern {
178        code: "Neo.ClientNotification.Statement.UnboundedVariableLengthPattern",
179        gql_status: "03N91",
180        severity: NotificationSeverity::Information,
181        category: NotificationCategory::Performance,
182        title: "Unbounded variable-length pattern",
183        remedy: "Bound the expansion (`[:R*1..5]`) where arbitrary length is not required, or add \
184                 a selective endpoint/label predicate and a `LIMIT`.",
185        plan_warning: false,
186        occurrence_scoped: true,
187    }
188    /// A label-less node scan while a property index exists.
189    AllNodesScan {
190        code: "Relate.Notification.Statement.AllNodesScan",
191        gql_status: "03C90",
192        severity: NotificationSeverity::Information,
193        category: NotificationCategory::Performance,
194        title: "All nodes scan",
195        remedy: "Name the label the scan intends (`MATCH (n:<Label>)`); on the index's label the \
196                 scan becomes an index-backed lookup.",
197        plan_warning: true,
198        occurrence_scoped: false,
199    }
200    /// A static label disjunction no seek serves: the scan answers per
201    /// disjunct label (LABS-1083).
202    LabelDisjunctionScan {
203        code: "Relate.Notification.Statement.LabelDisjunctionScan",
204        gql_status: "03C94",
205        severity: NotificationSeverity::Information,
206        category: NotificationCategory::Performance,
207        title: "Label disjunction scan",
208        remedy: "Create a range index on each disjunct label's filtered property: the disjunction \
209                 then serves as per-label keyed lookups instead of per-label scans.",
210        plan_warning: true,
211        occurrence_scoped: false,
212    }
213    /// A label/property equality with no range index on the pair.
214    MissingIndex {
215        code: "Relate.Notification.Statement.MissingIndex",
216        gql_status: "03C91",
217        severity: NotificationSeverity::Information,
218        category: NotificationCategory::Performance,
219        title: "Missing index",
220        remedy: "`CREATE INDEX relate_Person__email FOR (n:Person) ON (n.email)` — the exact \
221                 runnable statement, with the name derived deterministically from label and \
222                 property.",
223        plan_warning: false,
224        occurrence_scoped: false,
225    }
226    /// An aggregation whose input estimate reaches the eager threshold.
227    EagerAggregation {
228        code: "Relate.Notification.Statement.EagerAggregation",
229        gql_status: "03C92",
230        severity: NotificationSeverity::Information,
231        category: NotificationCategory::Performance,
232        title: "Eager aggregation",
233        remedy: "Reduce the rows reaching the aggregation with a selective label/property \
234                 predicate or a `LIMIT` before it; profile again to confirm the buffered input \
235                 shrank.",
236        plan_warning: false,
237        occurrence_scoped: false,
238    }
239    /// `PROFILE` only: an estimate at least 10x the actual rows.
240    EstimationMiss {
241        code: "Relate.Notification.Statement.EstimationMiss",
242        gql_status: "03C93",
243        severity: NotificationSeverity::Information,
244        category: NotificationCategory::Performance,
245        title: "Estimation miss",
246        remedy: "Rework the operator's input so the estimate can see the filter (add the \
247                 selective predicate at the scan, or reorder the join); the estimate is a planner \
248                 assumption, not a runtime fact.",
249        plan_warning: true,
250        occurrence_scoped: false,
251    }
252    /// A node pattern naming a label absent from the catalog.
253    UnknownLabelWarning {
254        code: "Neo.ClientNotification.Statement.UnknownLabelWarning",
255        gql_status: "01N50",
256        severity: NotificationSeverity::Warning,
257        category: NotificationCategory::Unrecognized,
258        title: "Unknown label",
259        remedy: "Check the spelling; the label exists after the first write that creates it, and \
260                 no index or constraint uses the unknown name.",
261        plan_warning: false,
262        occurrence_scoped: false,
263    }
264    /// A relationship pattern naming a type absent from the catalog.
265    UnknownRelationshipTypeWarning {
266        code: "Neo.ClientNotification.Statement.UnknownRelationshipTypeWarning",
267        gql_status: "01N51",
268        severity: NotificationSeverity::Warning,
269        category: NotificationCategory::Unrecognized,
270        title: "Unknown relationship type",
271        remedy: "Check the spelling; the type exists after the first write that creates it.",
272        plan_warning: false,
273        occurrence_scoped: false,
274    }
275    /// A predicate or property access naming an absent property key.
276    UnknownPropertyKeyWarning {
277        code: "Neo.ClientNotification.Statement.UnknownPropertyKeyWarning",
278        gql_status: "01N52",
279        severity: NotificationSeverity::Warning,
280        category: NotificationCategory::Unrecognized,
281        title: "Unknown property key",
282        remedy: "Check the spelling; the key exists after the first write that sets it.",
283        plan_warning: false,
284        occurrence_scoped: false,
285    }
286    /// A function call resolving to a deprecated catalog entry.
287    DeprecatedFunction {
288        code: "Neo.ClientNotification.Statement.FeatureDeprecationWarning",
289        gql_status: "01N01",
290        severity: NotificationSeverity::Warning,
291        category: NotificationCategory::Deprecation,
292        title: "Deprecated function",
293        remedy: "Replace the call with the catalog's `deprecated_by` (`id(n)` → `elementId(n)`).",
294        plan_warning: false,
295        occurrence_scoped: true,
296    }
297    /// A `CALL` resolving to a deprecated procedure.
298    DeprecatedProcedure {
299        code: "Neo.ClientNotification.Statement.FeatureDeprecationWarning",
300        gql_status: "01N01",
301        severity: NotificationSeverity::Warning,
302        category: NotificationCategory::Deprecation,
303        title: "Deprecated procedure",
304        remedy: "Use the registry's `deprecated_by` replacement instead; the replacement is the \
305                 remedy.",
306        plan_warning: false,
307        occurrence_scoped: true,
308    }
309    /// A `CALL { … }` subquery with no variable scope clause.
310    CallSubqueryWithoutScope {
311        code: "Neo.ClientNotification.Statement.FeatureDeprecationWarning",
312        gql_status: "01N00",
313        severity: NotificationSeverity::Warning,
314        category: NotificationCategory::Deprecation,
315        title: "CALL subquery without scope",
316        remedy: "Add the scope clause the body imports: `CALL (n) { … }`, or `CALL () { … }` when \
317                 it imports nothing.",
318        plan_warning: false,
319        occurrence_scoped: true,
320    }
321    /// A `MERGE` whose property map references the entity it merges.
322    MergeSelfReference {
323        code: "Neo.ClientNotification.Statement.FeatureDeprecationWarning",
324        gql_status: "01N00",
325        severity: NotificationSeverity::Warning,
326        category: NotificationCategory::Deprecation,
327        title: "Merge self-reference",
328        remedy: "Compute the property into a separate variable before the MERGE, or set it \
329                 with ON CREATE SET after the merge.",
330        plan_warning: false,
331        occurrence_scoped: true,
332    }
333    /// A projection subclause expression (`ORDER BY`/`WHERE`) referencing a
334    /// variable that the projection's own alias re-binds.
335    AmbiguousSubclauseReference {
336        code: "Neo.ClientNotification.Statement.FeatureDeprecationWarning",
337        gql_status: "01N01",
338        severity: NotificationSeverity::Warning,
339        category: NotificationCategory::Deprecation,
340        title: "Deprecated ambiguous subclause reference",
341        remedy: "Reference the projection item by an alias, or use the `GROUP BY` clause.",
342        plan_warning: false,
343        occurrence_scoped: true,
344    }
345    /// A projection subclause expression containing a complex projection
346    /// item expression as a proper sub-expression.
347    ComplexSubclauseReference {
348        code: "Neo.ClientNotification.Statement.FeatureDeprecationWarning",
349        gql_status: "01N01",
350        severity: NotificationSeverity::Warning,
351        category: NotificationCategory::Deprecation,
352        title: "Deprecated complex subclause reference",
353        remedy: "Reference the projection item expression by an alias.",
354        plan_warning: false,
355        occurrence_scoped: true,
356    }
357    /// A `CREATE` whose property definition references an entity created in
358    /// the same clause.
359    CreateSelfReference {
360        code: "Neo.ClientNotification.Statement.FeatureDeprecationWarning",
361        gql_status: "01N00",
362        severity: NotificationSeverity::Warning,
363        category: NotificationCategory::Deprecation,
364        title: "Create self-reference",
365        remedy: "Create the entity in a separate `CREATE` clause before referencing it, or set \
366                 the property afterwards.",
367        plan_warning: false,
368        occurrence_scoped: true,
369    }
370    /// A variable declared in a subquery that shadows an outer variable.
371    SubqueryVariableShadowing {
372        code: "Neo.ClientNotification.Statement.SubqueryVariableShadowing",
373        gql_status: "03N60",
374        severity: NotificationSeverity::Information,
375        category: NotificationCategory::Unrecognized,
376        title: "Subquery variable shadowing",
377        remedy: "Import the outer variable with `CALL (name) { … }`, or rename the inner one.",
378        plan_warning: false,
379        occurrence_scoped: true,
380    }
381    /// A dynamic property-key predicate on a variable whose label (or
382    /// relationship type) carries an index no static predicate can serve.
383    DynamicProperty {
384        code: "Neo.ClientNotification.Statement.DynamicProperty",
385        gql_status: "03N95",
386        severity: NotificationSeverity::Information,
387        category: NotificationCategory::Performance,
388        title: "Queries using dynamic properties will use neither index seeks nor \
389                index scans for those properties",
390        remedy: "Use a static property so index lookups stay possible.",
391        plan_warning: false,
392        occurrence_scoped: false,
393    }
394    /// A relationship type expression no single type can satisfy.
395    UnsatisfiableRelationshipTypeExpression {
396        code: "Neo.ClientNotification.Statement.UnsatisfiableRelationshipTypeExpression",
397        gql_status: "01N61",
398        severity: NotificationSeverity::Warning,
399        category: NotificationCategory::Unrecognized,
400        title: "Unsatisfiable relationship type expression",
401        remedy: "Request one type or a disjunction of types; a relationship has exactly one type.",
402        plan_warning: false,
403        occurrence_scoped: true,
404    }
405    /// A relationship variable repeated across pattern elements.
406    RepeatedRelationshipVariable {
407        code: "Neo.ClientNotification.Statement.RepeatedRelationshipVariable",
408        gql_status: "01N63",
409        severity: NotificationSeverity::Warning,
410        category: NotificationCategory::Unrecognized,
411        title: "Repeated relationship pattern variable",
412        remedy: "Use a distinct variable per relationship position; a relationship cannot be \
413                 traversed twice in one pattern.",
414        plan_warning: false,
415        occurrence_scoped: true,
416    }
417    /// A `SEARCH` index identifier sharing a name with a variable in scope.
418    SearchIdentifierShadowingVariable {
419        code: "Neo.ClientNotification.Statement.IdentifierShadowingVariable",
420        gql_status: "03N63",
421        severity: NotificationSeverity::Information,
422        category: NotificationCategory::Unrecognized,
423        title: "Identifier shadowing variable",
424        remedy: "Rename the index or the variable; the index name is taken literally.",
425        plan_warning: false,
426        occurrence_scoped: true,
427    }
428    /// A `shortestPath` whose predicates force exhaustive evaluation.
429    ExhaustiveShortestPath {
430        code: "Neo.ClientNotification.Statement.ExhaustiveShortestPath",
431        gql_status: "03N92",
432        severity: NotificationSeverity::Information,
433        category: NotificationCategory::Performance,
434        title: "Exhaustive shortest path",
435        remedy: "Separate the existential predicate from the `MATCH` with `WITH` where possible.",
436        plan_warning: false,
437        occurrence_scoped: true,
438    }
439    /// A schema DDL command that had no effect because an identical or
440    /// schema-equivalent index/constraint already exists (`00NA0`).
441    SchemaIndexOrConstraintAlreadyExists {
442        code: "Neo.ClientNotification.Schema.IndexOrConstraintAlreadyExists",
443        gql_status: "00NA0",
444        severity: NotificationSeverity::Information,
445        category: NotificationCategory::Schema,
446        title: "Index or constraint already exists",
447        remedy: "Drop the existing index or constraint first, or use a different name or schema.",
448        plan_warning: false,
449        occurrence_scoped: false,
450    }
451    /// A `DROP INDEX/CONSTRAINT … IF EXISTS` that had no effect because no
452    /// such index/constraint exists (`00NA1`).
453    SchemaIndexOrConstraintDoesNotExist {
454        code: "Neo.ClientNotification.Schema.IndexOrConstraintDoesNotExist",
455        gql_status: "00NA1",
456        severity: NotificationSeverity::Information,
457        category: NotificationCategory::Schema,
458        title: "Index or constraint does not exist",
459        remedy: "Check the name; `IF EXISTS` makes a missing index or constraint a no-op.",
460        plan_warning: false,
461        occurrence_scoped: false,
462    }
463    /// A `CREATE VECTOR INDEX` that omitted `vector.dimensions` (`00NA2`).
464    SchemaVectorIndexDimensionsNotSpecified {
465        code: "Neo.ClientNotification.Schema.VectorIndexDimensionsNotSpecified",
466        gql_status: "00NA2",
467        severity: NotificationSeverity::Information,
468        category: NotificationCategory::Schema,
469        title: "Vector index dimensions not specified",
470        remedy: "Set `vector.dimensions` in `OPTIONS { indexConfig: { … } }` when creating the index.",
471        plan_warning: false,
472        occurrence_scoped: false,
473    }
474    /// A `USING INDEX` hint no catalog index can serve (`01N31`).
475    HintedIndexNotFound {
476        code: "Neo.ClientNotification.Schema.HintedIndexNotFound",
477        gql_status: "01N31",
478        severity: NotificationSeverity::Warning,
479        category: NotificationCategory::Hint,
480        title: "The request (directly or indirectly) referred to an index that \
481                does not exist.",
482        remedy: "Create the index, or drop the hint.",
483        plan_warning: false,
484        occurrence_scoped: true,
485    }
486    /// A `USING JOIN ON` hint the planner could not fulfil (`01N30`).
487    JoinHintUnfulfillable {
488        code: "Neo.ClientNotification.Statement.JoinHintUnfulfillableWarning",
489        gql_status: "01N30",
490        severity: NotificationSeverity::Warning,
491        category: NotificationCategory::Hint,
492        title: "The database was unable to plan a hinted join.",
493        remedy: "Try a different join key or restructure the query.",
494        plan_warning: false,
495        occurrence_scoped: true,
496    }
497    /// An `OPTIONAL CALL` over a procedure that produces no rows (`03N61`).
498    RedundantOptionalProcedure {
499        code: "Neo.ClientNotification.Statement.RedundantOptionalProcedure",
500        gql_status: "03N61",
501        severity: NotificationSeverity::Information,
502        category: NotificationCategory::Performance,
503        title: "Redundant optional procedure",
504        remedy: "Drop `OPTIONAL`: the procedure declares no return columns, so the call yields \
505                 the same single row either way.",
506        plan_warning: false,
507        occurrence_scoped: true,
508    }
509    /// An `OPTIONAL CALL { … }` whose body projects no columns (`03N62`).
510    RedundantOptionalSubquery {
511        code: "Neo.ClientNotification.Statement.RedundantOptionalSubquery",
512        gql_status: "03N62",
513        severity: NotificationSeverity::Information,
514        category: NotificationCategory::Performance,
515        title: "Redundant optional subquery",
516        remedy: "Drop `OPTIONAL`: the subquery projects no columns, so the call yields the same \
517                 single row either way.",
518        plan_warning: false,
519        occurrence_scoped: true,
520    }
521}
522
523impl NotificationKind {
524    /// Whether two notifications of this kind with the same description are
525    /// the same finding (`true`) or two occurrences that must both be
526    /// reported (`false`). Name-based diagnostics collapse; every
527    /// occurrence-scoped kind — a deprecated call, a clause-shaped
528    /// deprecation, a per-pattern performance hint — keeps its duplicates,
529    /// because Neo4j reports one notification per occurrence.
530    pub fn dedups_identical(self) -> bool {
531        !self.row().occurrence_scoped
532    }
533
534    /// Whether the plan table already renders this kind (ADR-0363
535    /// decision 8): the kinds that project to a `PlanWarning` variant, whose
536    /// one text rendering is the plan table's `Warnings` column plus footer
537    /// (ADR-0344/0345). The other operator-scoped kinds (`UnboundedVariableLengthPattern`,
538    /// `MissingIndex`, `EagerAggregation`) do not join that column, so a
539    /// text block carries them. The membership is the row's `plan_warning`
540    /// column, so a new kind states its side where it names its metadata.
541    pub fn is_plan_warning(self) -> bool {
542        self.row().plan_warning
543    }
544
545    /// The diagnostic code (`Neo.ClientNotification.*` for a Neo4j analog,
546    /// `Relate.Notification.*` for an engine-own kind).
547    pub fn code(self) -> &'static str {
548        self.row().code
549    }
550
551    /// The GQLSTATUS value (`03N90`, `03C90`, `01N50`, …).
552    pub fn gql_status(self) -> &'static str {
553        self.row().gql_status
554    }
555
556    /// The severity (INFORMATION or WARNING).
557    pub fn severity(self) -> NotificationSeverity {
558        self.row().severity
559    }
560
561    /// The category (PERFORMANCE, UNRECOGNIZED or DEPRECATION).
562    pub fn category(self) -> NotificationCategory {
563        self.row().category
564    }
565
566    /// The one canonical human title for this kind — defined here, never
567    /// invented by a caller.
568    pub fn title(self) -> &'static str {
569        self.row().title
570    }
571
572    /// The kind's canonical remedy, used when a notification carries no
573    /// instance-specific one.
574    pub fn remedy(self) -> &'static str {
575        self.row().remedy
576    }
577}
578
579/// One query notification (ADR-0363 decision 1): the record
580/// `{ kind, description, remedy, operator_id }`.
581///
582/// The kind supplies the metadata — code, GQLSTATUS, severity, category,
583/// title and the canonical remedy — so the record stores no copy of it and
584/// the two cannot drift. `description` carries the instance detail (the
585/// unknown name, the index text, the procedure name); an instance-specific
586/// `remedy` overrides the kind's canonical text where the detector can name
587/// the precise action (the exact `CREATE INDEX`, the `deprecated_by`
588/// replacement). `operator_id` is the raising operator's `PlanNode.id`,
589/// present only on operator-scoped kinds.
590#[derive(Clone, Debug, PartialEq, Eq)]
591pub struct Notification {
592    kind: NotificationKind,
593    description: String,
594    remedy: Option<String>,
595    operator_id: Option<usize>,
596}
597
598impl Notification {
599    /// One notification of `kind` with its instance `description`; no
600    /// instance remedy (the kind's canonical remedy applies) and no
601    /// operator association (statement-scoped until [`Self::with_operator_id`]).
602    pub fn new(kind: NotificationKind, description: impl Into<String>) -> Self {
603        Notification {
604            kind,
605            description: description.into(),
606            remedy: None,
607            operator_id: None,
608        }
609    }
610
611    /// Attach an operator association — the raising `PlanNode.id` — the one
612    /// way an operator-scoped notification gains `operator_id`.
613    pub fn with_operator_id(mut self, operator_id: usize) -> Self {
614        self.operator_id = Some(operator_id);
615        self
616    }
617
618    /// Override the kind's canonical remedy with the instance-specific
619    /// action (the exact runnable statement, the replacement name).
620    pub fn with_remedy(mut self, remedy: impl Into<String>) -> Self {
621        self.remedy = Some(remedy.into());
622        self
623    }
624
625    /// The notification's kind — the vocabulary row identity.
626    pub fn kind(&self) -> NotificationKind {
627        self.kind
628    }
629
630    /// The instance detail — the unknown name, index text, procedure name
631    /// or warning message.
632    pub fn description(&self) -> &str {
633        &self.description
634    }
635
636    /// The kind's diagnostic code.
637    pub fn code(&self) -> &'static str {
638        self.kind.code()
639    }
640
641    /// The kind's GQLSTATUS value.
642    pub fn gql_status(&self) -> &'static str {
643        self.kind.gql_status()
644    }
645
646    /// The kind's canonical title.
647    pub fn title(&self) -> &'static str {
648        self.kind.title()
649    }
650
651    /// The kind's severity.
652    pub fn severity(&self) -> NotificationSeverity {
653        self.kind.severity()
654    }
655
656    /// The kind's category.
657    pub fn category(&self) -> NotificationCategory {
658        self.kind.category()
659    }
660
661    /// The effective remedy: the instance-specific one when the detector
662    /// supplied it, else the kind's canonical remedy. Every vocabulary kind
663    /// carries a remedy, so this is never absent.
664    pub fn remedy(&self) -> &str {
665        self.remedy.as_deref().unwrap_or_else(|| self.kind.remedy())
666    }
667
668    /// The raising operator's `PlanNode.id`, on operator-scoped kinds only.
669    pub fn operator_id(&self) -> Option<usize> {
670        self.operator_id
671    }
672}
673
674/// The engine-native notification keys (ADR-0363 decision 9) — the
675/// vocabulary [`notification_to_wire_json`] emits and every consumer
676/// reads, single-sourced like [`super::plan_keys`].
677pub mod notification_keys {
678    /// The diagnostic code.
679    pub const CODE: &str = "code";
680    /// The GQLSTATUS value.
681    pub const GQL_STATUS: &str = "gql_status";
682    /// The severity spelling.
683    pub const SEVERITY: &str = "severity";
684    /// The category spelling.
685    pub const CATEGORY: &str = "category";
686    /// The canonical title.
687    pub const TITLE: &str = "title";
688    /// The instance diagnosis.
689    pub const DESCRIPTION: &str = "description";
690    /// The effective remedy (always present on the native form).
691    pub const REMEDY: &str = "remedy";
692    /// The raising operator's id (operator-scoped kinds only).
693    pub const OPERATOR_ID: &str = "operator_id";
694    /// The response envelope's always-present notification list.
695    pub const NOTIFICATIONS: &str = "notifications";
696}
697
698/// The seven diagnostic fields of one notification's engine-native wire
699/// object, keyed by the [`notification_keys`] vocabulary — the core
700/// [`notification_to_wire_json`] layers the operator id onto, and the exact
701/// object the agent-native plan document projects for a node's `warnings`
702/// (the node already scopes the operator, so the join key is not repeated
703/// there). One spelling of the field set, so a field added to the canonical
704/// notification reaches every projection instead of drifting in a second
705/// hand-rolled one.
706pub(crate) fn notification_fields(notification: &Notification) -> Map<String, Value> {
707    let mut obj = Map::new();
708    obj.insert(
709        notification_keys::CODE.into(),
710        Value::String(notification.code().into()),
711    );
712    obj.insert(
713        notification_keys::GQL_STATUS.into(),
714        Value::String(notification.gql_status().into()),
715    );
716    obj.insert(
717        notification_keys::SEVERITY.into(),
718        Value::String(notification.severity().as_str().into()),
719    );
720    obj.insert(
721        notification_keys::CATEGORY.into(),
722        Value::String(notification.category().as_str().into()),
723    );
724    obj.insert(
725        notification_keys::TITLE.into(),
726        Value::String(notification.title().into()),
727    );
728    obj.insert(
729        notification_keys::DESCRIPTION.into(),
730        Value::String(notification.description().into()),
731    );
732    obj.insert(
733        notification_keys::REMEDY.into(),
734        Value::String(notification.remedy().into()),
735    );
736    obj
737}
738
739/// One notification's engine-native wire object (ADR-0363 decision 9):
740/// `code`, `gql_status`, `severity`, `category`, `title`, `description`,
741/// `remedy` and — on operator-scoped kinds — `operator_id`.
742pub fn notification_to_wire_json(notification: &Notification) -> Value {
743    let mut obj = notification_fields(notification);
744    if let Some(operator_id) = notification.operator_id() {
745        obj.insert(
746            notification_keys::OPERATOR_ID.into(),
747            Value::from(operator_id),
748        );
749    }
750    Value::Object(obj)
751}
752
753/// A notification list in the engine-native form — the array the shared
754/// success envelope always carries (empty on a plain run).
755pub fn notifications_to_wire_json(notifications: &[Notification]) -> Value {
756    Value::Array(
757        notifications
758            .iter()
759            .map(notification_to_wire_json)
760            .collect(),
761    )
762}
763
764/// One notification's Neo4j-shaped entries (ADR-0363 decisions 11/12), in
765/// Bolt's entry order: `code`, `title`, `description`, `severity`,
766/// `category`. The effective remedy is folded into `description` as
767/// ` (remedy: <remedy>)`; no `remedy` and no `position` entry is ever
768/// emitted. This is the ordered form Bolt packs directly, without building
769/// or re-reading a JSON object; [`notification_to_neo4j_json`] is the JSON
770/// projection of the same entries.
771pub fn notification_to_neo4j_entries(notification: &Notification) -> Vec<(&'static str, String)> {
772    vec![
773        (notification_keys::CODE, notification.code().to_string()),
774        (notification_keys::TITLE, notification.title().to_string()),
775        (
776            notification_keys::DESCRIPTION,
777            format!(
778                "{} (remedy: {})",
779                notification.description(),
780                notification.remedy()
781            ),
782        ),
783        (
784            notification_keys::SEVERITY,
785            notification.severity().as_str().to_string(),
786        ),
787        (
788            notification_keys::CATEGORY,
789            notification.category().as_str().to_string(),
790        ),
791    ]
792}
793
794/// One notification's Neo4j-shaped wire object (ADR-0363 decisions 11/12):
795/// exactly `code`, `title`, `description`, `severity`, `category`, with the
796/// remedy folded into `description` as ` (remedy: <remedy>)` and no `remedy`
797/// or `position` key. Built from [`notification_to_neo4j_entries`].
798///
799/// `serde_json::Map` is a sorted map in this workspace (it does not enable
800/// `preserve_order`), so the object's key order is sorted, not Bolt's.
801/// Callers that emit ordered entries — Bolt — read
802/// [`notification_to_neo4j_entries`] instead.
803pub fn notification_to_neo4j_json(notification: &Notification) -> Value {
804    let obj: Map<String, Value> = notification_to_neo4j_entries(notification)
805        .into_iter()
806        .map(|(key, value)| (key.to_owned(), Value::String(value)))
807        .collect();
808    Value::Object(obj)
809}
810
811#[cfg(test)]
812#[path = "notification_wire/tests.rs"]
813mod tests;