Skip to main content

Module wire

Module wire 

Source
Expand description

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)

VariantWire JSON
Nullnull
Booltrue / false
IntJSON integer
FloatJSON number (non-finite NaN/±Inf → "NaN"/"Inf"/"-Inf", see below)
StrJSON string
ListJSON array (elements recursively encoded)
MapJSON object (values recursively encoded)
Node{"kind":"node","id","labels","properties"}
Relationship{"kind":"relationship","id","type","start_node","end_node","properties"}
PathJSON array alternating [node, rel, node, rel, …, node] (no tag of its own; elements carry their kind, ADR-0223)
DateISO-8601 date string YYYY-MM-DD
TimeISO-8601 time string HH:MM[:SS[.fff]][±HH:MM[:SS] or Z]
DateTimeISO-8601 YYYY-MM-DDTHH:MM:SS[.fff]±HH:MM[[Zone/Id]]
LocalDateTimeISO-8601 YYYY-MM-DDTHH:MM:SS[.fff]
DurationISO-8601 duration PnYnMnDTnHnMnS
Pointcoordinate-key object + srid/crs marker (below)
GeometryGeoJSON-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)

{ "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).

Modules§

golden
Shared golden fixtures: the cross-surface anti-drift substrate.
notification_keys
The engine-native notification keys (ADR-0363 decision 9) — the vocabulary notification_to_wire_json emits and every consumer reads, single-sourced like super::plan_keys.
plan_keys
The plan wire form’s key vocabulary (ADR-0344/0345): the names PlanNode::to_value produces and every consumer reads, single-sourced so drift between producer and consumer is a compile error, not a silent mismatch. Its own module (the plan-node types and decoder stay in plan_wire); the public path is wire::plan_keys.

Structs§

Notification
One query notification (ADR-0363 decision 1): the record { kind, description, remedy, operator_id }.
PlanMetricsWire
The PROFILE metric set (ADR-0344 phase 2 + metric fields) as named fields: which number is rows, nanoseconds, store accesses, or row-materialization bytes is stated by the names, not by a position convention.
PlanNodeWire
The typed view of one structured-plan wire node (ADR-0344/0345): the producer (relate’s PlanNode::to_value) emits exactly this shape, so this accessor states the invariants instead of tolerating misses — a malformed plan fails loudly rather than silently dropping a row or shifting cells into the wrong column.
PlanPhasesWire
The phase times a PROFILE node reports (LABS-448): the elapsed time the read kinds’ store work spent — the seek (candidate resolution and admission, the Nodes kind’s work) and the walk (relationship traversal, the Rels/Degree kinds’ work), inclusive of a multi-element pattern’s nested phases.
PlanProfiledFacts
A metrics-carrying node’s presentation bundle (cumulative vs self): the PROFILE metric set and its subtree total — the derived total travels with the metrics it sums, present together or not at all, so no presentation can render a total beside unavailable metrics or a metric set without one.
PlanReadsWire
The store-read mix a PROFILE node reports (LABS-369): the kinds the one Db Hits total blends — relationship hops, neighbor walks, and node-store reads.
StatCounter
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.
TimingStampMs
The statement’s timing block as one wire value — the wire-side spelling of the engine’s result-header timing stamp: the ADR-0221 wall-clock total (elapsed_ms) together with its always-on PARSE / PLAN / EXECUTE split (ADR-0491) and the fine sub-split plus the plan-cache outcome (LABS-1120), flattened to the envelope keys’ own milliseconds. Bundled like the engine bundles its stamp, so an envelope construction site cannot carry the total without its split — and the canonical builder stays under clippy::too_many_arguments.
WireStatsSnapshot
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).

Enums§

ColumnTypeKind
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.
KernelRungWire
The traversal rung a PROFILE node reports (LABS-1117), typed from the wire vocabulary: the chain carries its hop count, so a chain without one — the half-state the parser rejects — is unrepresentable. Self::as_str is the vocabulary’s one spelling; plan_keys::KERNEL_RUNGS is derived from it.
NotificationCategory
The category spellings (ADR-0363 decision 1): the categories in scope.
NotificationKind
The notification kinds (ADR-0363 decision 1) — the row identities of the one vocabulary below, generated from its single table.
NotificationSeverity
The severity spellings (ADR-0363 decision 1): Neo4j’s two severities.
PlanWarning
One typed warning a plan node carries (ADR-0344, typed node warnings): the vocabulary’s one definition — the wire name it serializes by, the message text that renders beside the affected operator and in the warnings footer, the payload variant that names the property index, and the notification kind it projects to (ADR-0363 decision 1) — each owned here once, beside the notification vocabulary it projects into, so the engine’s detection, the wire parse, and every surface’s rendering cannot drift (LABS-461: one warning type, not three coordinated layers).

Constants§

CYPHER_VERSION
The Cypher language version the plan’s version arg reports (ADR-0357): this engine’s front-end is openCypher 5-compatible (ADR-0046), so the Neo4j-shaped version arg says 5 — the language version, not a product version.
NEO4J_PLANNER_IMPL
The planner-impl value every surface sends (ADR-0357): this engine’s own planner, named honestly — never Neo4j’s IDP/COST, which would claim a planner this engine does not run.
PLAN_SCHEMA
The schema identifier every projected document carries.
PLAN_UNAVAILABLE
The one spelling of a plan column’s unavailable value, shared by every presentation of the plan table (the engine renderer and the surfaces’ table layout) so “column not produced” renders identically everywhere.
STAT_COUNTERS
The mutation counters of an envelope’s stats object, in canonical order.
WIRE_KIND_NODE
The kind discriminator of a wire node object (ADR-0223). Decoder sides match on these constants instead of re-typing the literals.
WIRE_KIND_RELATIONSHIP
The kind discriminator of a wire relationship object (ADR-0223).

Traits§

WireStats
The 11 canonical mutation counters, read as u64.

Functions§

column_type_kind
Classify a first-row value into its canonical ADR-0224 kind.
column_type_name
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.
crs_name
The Neo4j CRS name for an SRID (used as the crs point marker) — the canonical mapping every surface shares (ADR-0280 wire shape).
error_envelope
Build the canonical error response envelope: empty columns/rows, empty stats, and the error message string under error.
estimation_miss
The one estimated-vs-actual overshoot policy (ADR-0344 metric fields + typed node warnings): the estimate misses when it overshoots the actual rows by 10x or more and the operator produced rows (an estimate over zero actual rows has no ratio). Both the ratio cell’s warning marker and the EstimationMiss warning derive from this one policy, never a second computation.
json_f64
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).
metric_i64
The wire form’s one width policy for metric integers: saturate at i64::MAX — one policy for every metric field (rows and time alike), never an unchecked cast on one and a clamp on the other.
metric_u64
The consumer side of the metric width policy: a wire metric is non-negative when present (the producer saturates), so the one conversion every metric cell reads goes through here — never a bare as cast at a call site.
notification_to_neo4j_entries
One notification’s Neo4j-shaped entries (ADR-0363 decisions 11/12), in Bolt’s entry order: code, title, description, severity, category. The effective remedy is folded into description as (remedy: <remedy>); no remedy and no position entry is ever emitted. This is the ordered form Bolt packs directly, without building or re-reading a JSON object; notification_to_neo4j_json is the JSON projection of the same entries.
notification_to_neo4j_json
One notification’s Neo4j-shaped wire object (ADR-0363 decisions 11/12): exactly code, title, description, severity, category, with the remedy folded into description as (remedy: <remedy>) and no remedy or position key. Built from notification_to_neo4j_entries.
notification_to_wire_json
One notification’s engine-native wire object (ADR-0363 decision 9): code, gql_status, severity, category, title, description, remedy and — on operator-scoped kinds — operator_id.
notifications_to_wire_json
A notification list in the engine-native form — the array the shared success envelope always carries (empty on a plain run).
plan_document
Project a plan wire tree (the engine’s PlanNode::to_value() form) into the agent-native document, as a serde_json::Value — the surface serializes it, exactly as it does the sibling wire documents (stats_to_wire_json, notifications_to_wire_json).
plan_node_wire
Read one plan wire node (ADR-0344/0345). Panics on a malformed node — the wire form is engine-produced and invariant-bound, so a deviation is an engine contract break, kept loud like every other boundary here.
plan_subtree_totals
The one subtree-total pass (cumulative vs self): every node’s own elapsed time plus every descendant’s, saturated through the metric width policy — ONE walk over the tree, keyed by the node’s pre-order id, so the table’s walk and the agent document’s walk read the same map instead of each re-folding its subtree (one policy, one spelling). Reads the typed accessor (the same validation every other consumer takes), so a malformed tree fails loudly here rather than silently summing partial subtrees.
profiled_facts
A metrics-carrying node’s presentation bundle, read from the totals map — the ONE spelling of the pairing’s contract (“the map covers every walked node”), so the table’s walk and the agent document’s walk cannot each re-state the lookup, and a third consumer inherits it instead of cloning the panic.
ratio_defined
Whether the estimated-vs-actual ratio is defined (ADR-0344 metric fields): the operator produced rows. The one predicate both the ratio cell and the overshoot policy read — never a second actual > 0 spelling at either site.
response_envelope
Build the canonical success response envelope (ADR-0491): the one construction every JSON surface renders — the pre-0491 envelope plus the statement’s per-phase timing split beside elapsed_ms.
row_to_wire_json
Encode one result row (an ordered column→value map) as a JSON object.
rows_for_result
Build the canonical wire rows array for a query result.
stats_from_wire_json
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.
stats_to_wire_json
Encode the 11 canonical mutation counters as a JSON object: snake_case keys, zeros included. See the module docs for the canonical name set.
time_ns_ms
The one nanoseconds-to-milliseconds conversion, as a float: every millisecond presentation reads it — the table cell’s {:.3} render, the HTTP v2 node’s time field, the agent document’s time_ms and total_time_ms — so the spellings cannot drift (and none truncates a sub-millisecond operator to 0).
value_to_wire_json
Encode a CypherValue as its canonical wire JSON.
warning_wire_json
The wire shape of one typed warning: {name, index?}, built from the one PlanWarning vocabulary — the spelling the plan-wire warning projections read (the HTTP v2 plan), never a re-assembled {name, index} at each site. The agent-native document does not read it: per ADR-0381 its node warnings derive from the result’s remedy-bearing notifications.