relate-model 1.1.0

Data model types (CypherValue) for the Relate graph database
Documentation
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
//! Canonical JSON **wire** encoding shared by every Relate surface.
//!
//! This module is the single source of truth for how a [`CypherValue`], a set
//! of mutation counters, and a query response are rendered as JSON on the wire
//! (the C FFI, the CLI, and the shapes the language bindings derive from
//! those). Every surface is expected to route its serialization
//! through here so that a drift in one surface becomes a failing golden test
//! (see the [`golden`] submodule).
//!
//! It is deliberately distinct from the persistence encoding in
//! [`crate::serde_value`] (the `__type`-tagged format used for on-disk
//! round-tripping and for `CypherValue`'s `serde::Serialize` impl). The wire
//! encoding is **self-describing and stable**: it never falls through to a
//! `Display` string for a structured value, and is documented field-by-field
//! below. Entity values (nodes and relationships) carry an explicit
//! `"kind"` discriminator so clients dispatch on a
//! documented field instead of sniffing key sets (ADR-0223, a breaking wire
//! change recorded in the CHANGELOG); the `__type`-tagged persistence
//! format remains a separate encoding.
//!
//! # Value encoding ([`value_to_wire_json`])
//!
//! | Variant | Wire JSON |
//! |---|---|
//! | `Null` | `null` |
//! | `Bool` | `true` / `false` |
//! | `Int` | JSON integer |
//! | `Float` | JSON number (non-finite `NaN`/`±Inf` → `"NaN"`/`"Inf"`/`"-Inf"`, see below) |
//! | `Str` | JSON string |
//! | `List` | JSON array (elements recursively encoded) |
//! | `Map` | JSON object (values recursively encoded) |
//! | `Node` | `{"kind":"node","id","labels","properties"}` |
//! | `Relationship` | `{"kind":"relationship","id","type","start_node","end_node","properties"}` |
//! | `Path` | JSON array alternating `[node, rel, node, rel, …, node]` (no tag of its own; elements carry their `kind`, ADR-0223) |
//! | `Date` | ISO-8601 date string `YYYY-MM-DD` |
//! | `Time` | ISO-8601 time string `HH:MM[:SS[.fff]][±HH:MM[:SS] or Z]` |
//! | `DateTime` | ISO-8601 `YYYY-MM-DDTHH:MM:SS[.fff]±HH:MM[[Zone/Id]]` |
//! | `LocalDateTime` | ISO-8601 `YYYY-MM-DDTHH:MM:SS[.fff]` |
//! | `Duration` | ISO-8601 duration `PnYnMnDTnHnMnS` |
//! | `Point` | coordinate-key object + `srid`/`crs` marker (below) |
//! | `Geometry` | GeoJSON-style `{"type", "coordinates" or "geometries"}` |
//! | `Vector` | `{"type","dim","values"}` (structured, **not** a string) |
//!
//! The five temporal renderings are exactly the canonical ISO-8601 `Display`
//! forms of the corresponding `CypherValue` (trailing-zero-trimmed fractional
//! seconds, compact offsets, `Z` for UTC, `[IANA/Zone]` suffix on a zoned
//! `DateTime`). They are unambiguous and parseable, and — unlike the
//! persistence format — carry no type tag.
//!
//! ## Point (`Point`)
//!
//! A coordinate-key object carrying an explicit CRS marker so the reader never
//! has to guess the coordinate space:
//! - geographic (`srid` 4326 / 4979): `{"srid","crs","longitude","latitude"[,"height"]}`
//! - cartesian (all other srids): `{"srid","crs","x","y"[,"z"]}`
//!
//! `crs` is the Neo4j CRS name (`wgs-84`, `wgs-84-3d`, `cartesian`,
//! `cartesian-3d`; unknown srids fall back to `cartesian` keys/name). The
//! `srid`/`crs` marker is new relative to the historical CLI/WASM point output,
//! which emitted the coordinate keys alone.
//!
//! ## Vector (`Vector`)
//!
//! `{"type": <coordinate-type name>, "dim": <usize>, "values": [<number>, …]}`.
//! `type` is the canonical coordinate-type name (`INTEGER8`, `INTEGER16`,
//! `INTEGER32`, `INTEGER`, `FLOAT32`, `FLOAT`); integer-kind vectors carry JSON
//! integers, float-kind vectors carry JSON numbers. This replaces the previous
//! bug where every surface stringified a vector via `Display`
//! (`vector([…], 3, FLOAT32 NOT NULL)`).
//!
//! ## Non-finite floats
//!
//! `NaN`, `+Inf`, and `-Inf` are not representable as standard JSON numbers
//! and are encoded as the JSON strings `"NaN"`, `"Inf"`, and `"-Inf"` —
//! exactly the `CypherValue` `Display` spellings, so the JSON surfaces agree
//! with the table/CSV modes and a non-finite float is never
//! indistinguishable from a genuine `null` (ADR-0280; a breaking wire
//! change from the previous `null` encoding, acceptable pre-1.0/alpha per
//! the precedent below, recorded in the CHANGELOG).
//!
//! # Stats encoding ([`stats_to_wire_json`])
//!
//! All **11** mutation counters, **snake_case**, **zeros included**:
//!
//! `nodes_created`, `nodes_deleted`, `relationships_created`,
//! `relationships_deleted`, `properties_set`, `labels_added`, `labels_removed`,
//! `indexes_added`, `indexes_removed`, `constraints_added`,
//! `constraints_removed`.
//!
//! [`stats_from_wire_json`] is the inverse: it decodes that object back into
//! a [`WireStatsSnapshot`], naming the first canonical counter that is
//! missing or not an unsigned integer.
//!
//! These are the canonical names (they match the engine's `Stats` field names
//! and Neo4j's `Added`/`Removed` semantics). The historical JSONL server
//! renamed four of them (`indexes_added`→`indexes_created`,
//! `indexes_removed`→`indexes_dropped`, and the two `constraints_*`
//! equivalents); the WASM surface used camelCase and omitted zeros; the FFI
//! surface emitted only six. Unifying on this set is a breaking wire change
//! (documented in the CHANGELOG; acceptable pre-1.0/alpha).
//!
//! # Response envelope ([`response_envelope`] / [`error_envelope`])
//!
//! ```json
//! { "columns": [ … ], "columnTypes": [ … ], "rows": [ { … }, … ], "stats": { … }, "notifications": [ … ], "elapsed_ms": 1.25, "parse_ms": 0.4, "plan_ms": 1.1, "execute_ms": 10.8, "plan": { … } | null, "error": null }
//! ```
//!
//! `notifications` is always present and empty on a plain run (ADR-0363
//! decision 9); its entries are the engine-native notification objects
//! ([`notification_to_wire_json`]). `plan` is always present too — the
//! `relate.plan/v1` document (LABS-418, ADR-0381), `null` on a plain
//! run.
//!
//! The row container key is **`rows`**. The historical JSONL server and FFI
//! used `data`; migrating them to `rows` is part of the same unification.
//! `elapsed_ms` is the engine-reported statement elapsed in wall-clock
//! milliseconds (ADR-0221). `parse_ms`/`plan_ms`/`execute_ms` are that
//! window's PARSE / PLAN / EXECUTE split (ADR-0491): always-on, disjoint
//! sub-windows whose sum never exceeds `elapsed_ms` (the inter-stage gaps
//! stay in the total alone). The total and its split ride the builder
//! together as one [`TimingStampMs`] — an envelope construction site
//! cannot carry the total without its split.
//! `columnTypes` carries the engine-stamped
//! per-column type names of ADR-0224 (one of the 18 canonical names, beside
//! `columns`, same length and order; a column whose first-row value is
//! `Null`, or a result with no rows, stamps `ANY`, so a write-only envelope
//! carries `"columnTypes": []`). On error: `columns: []`, `rows: []`,
//! `stats: {}`, `error: <message string>` (no `elapsed_ms`: no statement
//! ran).

use std::borrow::Cow;

use indexmap::IndexMap;
use serde_json::{Map, Value};

use crate::point::{is_geographic, point_axis_keys};
use crate::value::{CypherValue, GeometryValue, PointValue};

/// The `kind` discriminator of a wire node object (ADR-0223). Decoder sides
/// match on these constants instead of re-typing the literals.
pub const WIRE_KIND_NODE: &str = "node";

/// The `kind` discriminator of a wire relationship object (ADR-0223).
pub const WIRE_KIND_RELATIONSHIP: &str = "relationship";

/// Encode a [`CypherValue`] as its canonical wire JSON.
///
/// Covers all 18 variants with structured, self-describing encodings; no
/// variant falls through to a `Display` string except the five temporal
/// variants, whose ISO-8601 string *is* the canonical encoding. See the module
/// docs for the full table.
pub fn value_to_wire_json(val: &CypherValue) -> Value {
    match val {
        CypherValue::Null => Value::Null,
        CypherValue::Bool(b) => Value::Bool(*b),
        CypherValue::Int(i) => Value::Number((*i).into()),
        CypherValue::Float(f) => json_f64(*f),
        CypherValue::Str(s) => Value::String(s.clone()),
        CypherValue::List(items) => Value::Array(items.iter().map(value_to_wire_json).collect()),
        CypherValue::Map(map) => Value::Object(map_to_wire_json(map)),
        CypherValue::Node {
            id,
            labels,
            properties,
        } => {
            let mut obj = Map::new();
            // ADR-0223: the `kind` discriminator lets clients dispatch on a
            // documented field instead of shape-sniffing.
            obj.insert("kind".into(), Value::String(WIRE_KIND_NODE.into()));
            obj.insert("id".into(), Value::Number((*id).into()));
            obj.insert(
                "labels".into(),
                Value::Array(labels.iter().map(|l| Value::String(l.clone())).collect()),
            );
            obj.insert(
                "properties".into(),
                Value::Object(map_to_wire_json(properties)),
            );
            Value::Object(obj)
        }
        CypherValue::Relationship {
            id,
            start_id,
            end_id,
            rel_type,
            properties,
        } => {
            let mut obj = Map::new();
            // ADR-0223: see the `Node` arm.
            obj.insert("kind".into(), Value::String(WIRE_KIND_RELATIONSHIP.into()));
            obj.insert("id".into(), Value::Number((*id).into()));
            obj.insert("type".into(), Value::String(rel_type.clone()));
            obj.insert("start_node".into(), Value::Number((*start_id).into()));
            obj.insert("end_node".into(), Value::Number((*end_id).into()));
            obj.insert(
                "properties".into(),
                Value::Object(map_to_wire_json(properties)),
            );
            Value::Object(obj)
        }
        CypherValue::Path {
            nodes,
            relationships,
        } => {
            // Alternating [node, rel, node, rel, …, node]. A well-formed path
            // has `nodes.len() == relationships.len() + 1`, so the trailing
            // node emits no following relationship.
            let mut items = Vec::with_capacity(nodes.len() + relationships.len());
            for (i, n) in nodes.iter().enumerate() {
                items.push(value_to_wire_json(n));
                if let Some(r) = relationships.get(i) {
                    items.push(value_to_wire_json(r));
                }
            }
            Value::Array(items)
        }
        // Temporal values: canonical ISO-8601 Display strings (documented,
        // stable, and tag-free). This is the one intentional "Display" arm.
        CypherValue::Date(_)
        | CypherValue::Time(_, _)
        | CypherValue::DateTime(_, _)
        | CypherValue::LocalDateTime(_)
        | CypherValue::Duration(_) => Value::String(val.to_string()),
        CypherValue::Point(p) => point_to_wire_json(p),
        CypherValue::Geometry(g) => geometry_to_wire_json(g),
        CypherValue::Vector { coord, dim, values } => {
            let mut obj = Map::new();
            obj.insert(
                "type".into(),
                Value::String(coord.canonical_name().to_string()),
            );
            obj.insert("dim".into(), Value::Number((*dim as u64).into()));
            obj.insert(
                "values".into(),
                Value::Array(values.iter().map(value_to_wire_json).collect()),
            );
            Value::Object(obj)
        }
    }
}

/// Encode a property/value map (used for node & relationship `properties` and
/// for `CypherValue::Map`).
fn map_to_wire_json(map: &IndexMap<String, CypherValue>) -> Map<String, Value> {
    map.iter()
        .map(|(k, v)| (k.clone(), value_to_wire_json(v)))
        .collect()
}

/// Encode an `f64` as wire JSON: a JSON number when finite, otherwise the
/// JSON string of its `CypherValue` `Display` spelling (`"NaN"`/`"Inf"`/
/// `"-Inf"`, ADR-0280).
pub fn json_f64(f: f64) -> Value {
    serde_json::Number::from_f64(f)
        .map(Value::Number)
        .unwrap_or_else(|| Value::String(CypherValue::Float(f).to_string()))
}

/// The Neo4j CRS name for an SRID (used as the `crs` point marker) — the
/// canonical mapping every surface shares (ADR-0280 wire shape).
pub fn crs_name(srid: i32) -> &'static str {
    match srid {
        4326 => "wgs-84",
        4979 => "wgs-84-3d",
        7203 => "cartesian",
        9157 => "cartesian-3d",
        _ => "cartesian",
    }
}

fn point_to_wire_json(p: &PointValue) -> Value {
    let mut obj = Map::new();
    obj.insert("srid".into(), Value::Number(p.srid.into()));
    obj.insert("crs".into(), Value::String(crs_name(p.srid).to_string()));
    // Geographic and cartesian differ only in the coordinate key names,
    // which are the shared axis vocabulary's two spellings.
    let [x_key, y_key, z_key] = point_axis_keys(is_geographic(p.srid));
    obj.insert(x_key.into(), json_f64(p.x));
    obj.insert(y_key.into(), json_f64(p.y));
    if let Some(z) = p.z {
        obj.insert(z_key.into(), json_f64(z));
    }
    Value::Object(obj)
}

fn coords_to_wire_json(coords: &[[f64; 2]]) -> Value {
    Value::Array(
        coords
            .iter()
            .map(|c| Value::Array(vec![json_f64(c[0]), json_f64(c[1])]))
            .collect(),
    )
}

fn geometry_to_wire_json(g: &GeometryValue) -> Value {
    let mut obj = Map::new();
    obj.insert("type".into(), Value::String(g.type_name().to_string()));
    match g {
        GeometryValue::LineString { coordinates, .. } => {
            obj.insert("coordinates".into(), coords_to_wire_json(coordinates));
        }
        GeometryValue::Polygon { rings, .. } => {
            obj.insert(
                "coordinates".into(),
                Value::Array(rings.iter().map(|r| coords_to_wire_json(r)).collect()),
            );
        }
        GeometryValue::MultiPoint { points, .. } => {
            obj.insert("coordinates".into(), coords_to_wire_json(points));
        }
        GeometryValue::MultiLineString { lines, .. } => {
            obj.insert(
                "coordinates".into(),
                Value::Array(lines.iter().map(|l| coords_to_wire_json(l)).collect()),
            );
        }
        GeometryValue::MultiPolygon { polygons, .. } => {
            obj.insert(
                "coordinates".into(),
                Value::Array(
                    polygons
                        .iter()
                        .map(|poly| {
                            Value::Array(poly.iter().map(|r| coords_to_wire_json(r)).collect())
                        })
                        .collect(),
                ),
            );
        }
        GeometryValue::GeometryCollection { geometries, .. } => {
            obj.insert(
                "geometries".into(),
                Value::Array(geometries.iter().map(geometry_to_wire_json).collect()),
            );
        }
    }
    Value::Object(obj)
}

/// Encode one result row (an ordered column→value map) as a JSON object.
///
/// Columns are taken from `columns` (preserving the query's column order in the
/// underlying ordered map); a column absent from `row` encodes as `null`.
pub fn row_to_wire_json(columns: &[String], row: &IndexMap<String, CypherValue>) -> Value {
    let mut obj = Map::new();
    for col in columns {
        let v = row.get(col).map(value_to_wire_json).unwrap_or(Value::Null);
        obj.insert(col.clone(), v);
    }
    Value::Object(obj)
}

/// Build the canonical wire `rows` array for a query result.
///
/// This is the single, shared assembly point for the row container so the
/// JSON surfaces (C FFI, CLI) cannot diverge on it. It applies
/// the **write-only rule**: a statement that produces no result columns (a
/// `CREATE`/`MERGE`/`SET`/… without `RETURN`) yields an empty `rows` array — not
/// a `[{}]` array of empty objects — even though the engine emits one driving
/// row per input row (seeded with a single empty row for a top-level write).
/// When there are columns, each row is encoded via [`row_to_wire_json`].
///
/// Historically only the JSONL server guarded the empty-columns case; the FFI
/// and WASM surfaces mapped every driving row unconditionally and so emitted
/// `[{}]` for a write-only statement. Routing all three through this helper
/// makes that drift structurally impossible (pinned by
/// [`golden::envelope_write_only`]).
pub fn rows_for_result(columns: &[String], rows: &[IndexMap<String, CypherValue>]) -> Vec<Value> {
    if columns.is_empty() {
        Vec::new()
    } else {
        rows.iter()
            .map(|row| row_to_wire_json(columns, row))
            .collect()
    }
}

/// The 11 canonical mutation counters, read as `u64`.
///
/// Implemented by [`WireStatsSnapshot`] here (built from the executor's
/// `QueryStats` via `relate::query_stats_to_wire`), so
/// `stats_to_wire_json` can serialize either without `relate-model`
/// depending on the executor.
pub trait WireStats {
    fn nodes_created(&self) -> u64;
    fn nodes_deleted(&self) -> u64;
    fn relationships_created(&self) -> u64;
    fn relationships_deleted(&self) -> u64;
    fn properties_set(&self) -> u64;
    fn labels_added(&self) -> u64;
    fn labels_removed(&self) -> u64;
    fn indexes_added(&self) -> u64;
    fn indexes_removed(&self) -> u64;
    fn constraints_added(&self) -> u64;
    fn constraints_removed(&self) -> u64;
}

/// A plain, model-owned carrier of the 11 counters — a [`WireStats`] value that
/// does not require the engine crate (used by the golden fixtures and by any
/// surface that already has counts in hand).
#[derive(Debug, Clone, Default, PartialEq, Eq)]
pub struct WireStatsSnapshot {
    pub nodes_created: u64,
    pub nodes_deleted: u64,
    pub relationships_created: u64,
    pub relationships_deleted: u64,
    pub properties_set: u64,
    pub labels_added: u64,
    pub labels_removed: u64,
    pub indexes_added: u64,
    pub indexes_removed: u64,
    pub constraints_added: u64,
    pub constraints_removed: u64,
}

impl WireStats for WireStatsSnapshot {
    fn nodes_created(&self) -> u64 {
        self.nodes_created
    }
    fn nodes_deleted(&self) -> u64 {
        self.nodes_deleted
    }
    fn relationships_created(&self) -> u64 {
        self.relationships_created
    }
    fn relationships_deleted(&self) -> u64 {
        self.relationships_deleted
    }
    fn properties_set(&self) -> u64 {
        self.properties_set
    }
    fn labels_added(&self) -> u64 {
        self.labels_added
    }
    fn labels_removed(&self) -> u64 {
        self.labels_removed
    }
    fn indexes_added(&self) -> u64 {
        self.indexes_added
    }
    fn indexes_removed(&self) -> u64 {
        self.indexes_removed
    }
    fn constraints_added(&self) -> u64 {
        self.constraints_added
    }
    fn constraints_removed(&self) -> u64 {
        self.constraints_removed
    }
}

/// Encode the 11 canonical mutation counters as a JSON object: snake_case keys,
/// zeros included. See the module docs for the canonical name set.
pub fn stats_to_wire_json(stats: &dyn WireStats) -> Value {
    Value::Object(
        STAT_COUNTERS
            .iter()
            .map(|counter| (counter.key.to_string(), (counter.count)(stats).into()))
            .collect(),
    )
}

/// Decode an envelope's `stats` object into the 11 canonical counters — the
/// inverse of [`stats_to_wire_json`], reading the same [`STAT_COUNTERS`]
/// table the encoder writes.
///
/// Every canonical counter must be present as a JSON unsigned integer; the
/// first one that is missing or of another type is an error naming it.
/// Entries outside the canonical set are ignored — the encoder writes none,
/// and a reader must not fail on a recording that carries one.
pub fn stats_from_wire_json(stats: &Map<String, Value>) -> Result<WireStatsSnapshot, String> {
    let mut snapshot = WireStatsSnapshot::default();
    for counter in &STAT_COUNTERS {
        let count = stats
            .get(counter.key)
            .and_then(Value::as_u64)
            .ok_or_else(|| {
                format!(
                    "stats entry `{}` is missing or not an unsigned integer",
                    counter.key
                )
            })?;
        (counter.set)(&mut snapshot, count);
    }
    Ok(snapshot)
}

/// A mutation counter: its key in an envelope's `stats` object, its key on
/// the Bolt wire (derived by [`StatCounter::bolt_key`]), and the
/// [`WireStats`] accessor it encodes — with that accessor's inverse, so
/// [`stats_to_wire_json`] and [`stats_from_wire_json`] read one table.
#[derive(Debug, Clone, Copy)]
pub struct StatCounter {
    /// The counter's key in the JSON envelope's `stats` object (snake_case,
    /// the canonical envelope vocabulary).
    pub key: &'static str,
    /// The [`WireStats`] accessor this counter encodes.
    pub count: fn(&dyn WireStats) -> u64,
    /// The inverse of `count`: writes this counter's value into a
    /// [`WireStatsSnapshot`], so the decoder assigns the field the encoder
    /// reads.
    pub set: fn(&mut WireStatsSnapshot, u64),
}

impl StatCounter {
    /// The counter's key in Bolt's `stats` map (ADR-0309): Neo4j's
    /// kebab-case wire spelling, derived from the envelope key so no second
    /// stored spelling can drift from it.
    pub fn bolt_key(&self) -> Cow<'static, str> {
        self.key.replace('_', "-").into()
    }
}

/// The mutation counters of an envelope's `stats` object, in canonical order.
pub const STAT_COUNTERS: [StatCounter; 11] = [
    StatCounter {
        key: "nodes_created",
        count: |s| s.nodes_created(),
        set: |s, n| s.nodes_created = n,
    },
    StatCounter {
        key: "nodes_deleted",
        count: |s| s.nodes_deleted(),
        set: |s, n| s.nodes_deleted = n,
    },
    StatCounter {
        key: "relationships_created",
        count: |s| s.relationships_created(),
        set: |s, n| s.relationships_created = n,
    },
    StatCounter {
        key: "relationships_deleted",
        count: |s| s.relationships_deleted(),
        set: |s, n| s.relationships_deleted = n,
    },
    StatCounter {
        key: "properties_set",
        count: |s| s.properties_set(),
        set: |s, n| s.properties_set = n,
    },
    StatCounter {
        key: "labels_added",
        count: |s| s.labels_added(),
        set: |s, n| s.labels_added = n,
    },
    StatCounter {
        key: "labels_removed",
        count: |s| s.labels_removed(),
        set: |s, n| s.labels_removed = n,
    },
    StatCounter {
        key: "indexes_added",
        count: |s| s.indexes_added(),
        set: |s, n| s.indexes_added = n,
    },
    StatCounter {
        key: "indexes_removed",
        count: |s| s.indexes_removed(),
        set: |s, n| s.indexes_removed = n,
    },
    StatCounter {
        key: "constraints_added",
        count: |s| s.constraints_added(),
        set: |s, n| s.constraints_added = n,
    },
    StatCounter {
        key: "constraints_removed",
        count: |s| s.constraints_removed(),
        set: |s, n| s.constraints_removed = n,
    },
];

/// The ADR-0224 per-column type classification: the closed 18-kind set the
/// engine stamps result columns with, one kind per first-row value. This
/// enum is the single source of the canonical name spellings — both value
/// taxonomies (the wire-side [`CypherValue`] here, the engine's core
/// `Value` in `relate-core`'s `convert` module) classify into it, so a
/// renamed or extended kind fails to compile at every mapping site instead
/// of drifting into a second hand-maintained table.
///
/// `Uuid` and `Binary` are reserved kinds: neither value enum has a
/// distinct variant that classifies into them today (UUID values cross as
/// `Str`/`String` and stamp `STRING`), so the names exist only to keep a
/// future distinct value kind from renumbering the set.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum ColumnTypeKind {
    Any,
    String,
    Integer,
    Float,
    Boolean,
    Node,
    Relationship,
    Path,
    List,
    Map,
    Point,
    DateTime,
    Date,
    Time,
    Duration,
    Vector,
    Uuid,
    Binary,
}

impl ColumnTypeKind {
    /// The canonical ADR-0224 type-name spelling of this kind.
    pub fn name(self) -> &'static str {
        match self {
            Self::Any => "ANY",
            Self::String => "STRING",
            Self::Integer => "INTEGER",
            Self::Float => "FLOAT",
            Self::Boolean => "BOOLEAN",
            Self::Node => "NODE",
            Self::Relationship => "RELATIONSHIP",
            Self::Path => "PATH",
            Self::List => "LIST",
            Self::Map => "MAP",
            Self::Point => "POINT",
            Self::DateTime => "DATETIME",
            Self::Date => "DATE",
            Self::Time => "TIME",
            Self::Duration => "DURATION",
            Self::Vector => "VECTOR",
            Self::Uuid => "UUID",
            Self::Binary => "BINARY",
        }
    }
}

/// Classify a first-row value into its canonical ADR-0224 kind.
///
/// `Null` classifies `Any` (the stamping rule's `ANY`). `Geometry` is a
/// distinct `CypherValue` variant but is not in the client-facing set; it
/// reports `Point` (the same coordinate family).
pub fn column_type_kind(value: &CypherValue) -> ColumnTypeKind {
    match value {
        CypherValue::Null => ColumnTypeKind::Any,
        CypherValue::Bool(_) => ColumnTypeKind::Boolean,
        CypherValue::Int(_) => ColumnTypeKind::Integer,
        CypherValue::Float(_) => ColumnTypeKind::Float,
        CypherValue::Str(_) => ColumnTypeKind::String,
        CypherValue::List(_) => ColumnTypeKind::List,
        CypherValue::Map(_) => ColumnTypeKind::Map,
        CypherValue::Node { .. } => ColumnTypeKind::Node,
        CypherValue::Relationship { .. } => ColumnTypeKind::Relationship,
        CypherValue::Path { .. } => ColumnTypeKind::Path,
        CypherValue::Date(_) => ColumnTypeKind::Date,
        CypherValue::Time(_, _) => ColumnTypeKind::Time,
        CypherValue::DateTime(_, _) => ColumnTypeKind::DateTime,
        CypherValue::LocalDateTime(_) => ColumnTypeKind::DateTime,
        CypherValue::Duration(_) => ColumnTypeKind::Duration,
        CypherValue::Point(_) => ColumnTypeKind::Point,
        // Distinct value kind, same coordinate family — see the enum docs.
        CypherValue::Geometry(_) => ColumnTypeKind::Point,
        CypherValue::Vector { .. } => ColumnTypeKind::Vector,
    }
}

/// One canonical ADR-0224 per-column type name for a first-row value — the
/// name spelling of [`column_type_kind`], for callers that want the string
/// directly. The engine stamps each result column with one of the 18
/// canonical names at result construction, from the first row only —
/// Cypher columns are heterogeneous, and the name makes no claim about
/// later rows. This mapping is the wire-side spelling of the engine's
/// `QueryResult::column_types` stamp.
pub fn column_type_name(value: &CypherValue) -> &'static str {
    column_type_kind(value).name()
}

/// Shared golden fixtures: the cross-surface anti-drift substrate.
///
/// Every Relate surface (C FFI, CLI, and — transitively — the language
/// bindings) is expected to serialize through
/// [`value_to_wire_json`]. These fixtures pin the exact expected JSON for every
/// variant so that any surface diverging from the canonical encoding fails a
/// test. The module is public and always compiled so the CLI, FFI (and
/// any other) test suites can `use relate_model::wire::golden;` and run
/// [`golden::assert_all_match`] against their own serializer.
pub mod golden;

#[cfg(test)]
mod tests;

// The one hand-built plan wire fixture — its own file so the wire
// accessor's and the agent document's test modules share one builder,
// never a second copy of the metric-args block.
#[cfg(test)]
#[path = "plan_test_fixtures.rs"]
pub(crate) mod plan_test_fixtures;

// ---------------------------------------------------------------------------
// Structured query plan wire form (ADR-0344/0345) — the node types and
// decoder live in `plan_wire`, the key vocabulary in its own `plan_keys`
// module; both are re-exported here so the one public path stays under
// `wire`.
// ---------------------------------------------------------------------------

#[path = "plan_wire.rs"]
mod plan_wire;

// The plan wire form's key vocabulary, its own module beside the types and
// decoder it names (`plan_keys.rs`); `wire::plan_keys` stays the one public
// path.
#[path = "plan_keys.rs"]
pub mod plan_keys;

pub use plan_wire::{
    metric_i64, metric_u64, plan_node_wire, plan_subtree_totals, profiled_facts, time_ns_ms,
    KernelRungWire, PlanMetricsWire, PlanNodeWire, PlanPhasesWire, PlanProfiledFacts,
    PlanReadsWire, CYPHER_VERSION, NEO4J_PLANNER_IMPL, PLAN_UNAVAILABLE,
};

// The typed plan-warning vocabulary (LABS-461: one warning type) — its
// own module beside the plan wire form it parses into, mirroring the
// notification vocabulary's placement; re-exported here so
// `wire::PlanWarning` is the one public path.

#[path = "plan_warning.rs"]
mod plan_warning;

pub use plan_warning::{estimation_miss, ratio_defined, warning_wire_json, PlanWarning};

// The agent-native plan projection (`relate.plan/v1`, LABS-370) — our
// own API dialect beside the Neo4j-facing one, reading the same typed view.

#[path = "agent_plan.rs"]
mod agent_plan;

pub use agent_plan::{plan_document, SCHEMA as PLAN_SCHEMA};

// ---------------------------------------------------------------------------
// Query notifications (ADR-0363) — lives in `notification_wire`, re-exported
// here so `wire::Notification` is the one public path (the plan vocabulary's
// layout).
// ---------------------------------------------------------------------------

#[path = "notification_wire.rs"]
mod notification_wire;

pub use notification_wire::{
    notification_keys, notification_to_neo4j_entries, notification_to_neo4j_json,
    notification_to_wire_json, notifications_to_wire_json, Notification, NotificationCategory,
    NotificationKind, NotificationSeverity,
};

// ---------------------------------------------------------------------------
// The response-envelope family (the canonical success envelope with the
// ADR-0491 phase split, the error envelope, the bundled timing stamp) —
// lives in `wire/envelope`, re-exported here so `wire::response_envelope`
// is the one public path.
// ---------------------------------------------------------------------------

mod envelope;

pub use envelope::{error_envelope, response_envelope, TimingStampMs};