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
//! Typed AST → [`ParseTree`] reverse walk (`DslDump`).
//!
//! [`DslBuild`](crate::DslBuild) turns a validated [`ParseTree`] into a
//! typed AST value; this module is its inverse. A type deriving
//! `#[derive(DslDump)]` (in `dsl-kit-macros`) re-emits the tree shape
//! its own `DslBuild` derive accepts, so the two derives stay a
//! round-trip pair by construction:
//!
//! ```text
//! from_parse_tree(&ast.to_parse_tree()?, &ids) ≙ ast (modulo NodeId)
//! ```
//!
//! Chaining the emitted tree through
//! [`to_canonical_json`](crate::serde_bridge::to_canonical_json) yields
//! the serde-bridge JSON serializer downstream consumers want — see
//! [`dump_canonical_json`]. Because `to_canonical_json` runs
//! [`check_conformance`](crate::check_conformance) on the way down, a
//! derive bug that emitted a non-conforming shape surfaces as loud
//! diagnostics rather than silently wrong JSON.
//!
//! ## Emission rules (the duals of the build defaults)
//!
//! - `id: NodeId` is **not** serialized — re-parsing mints fresh ids,
//! which is the same contract every front-end already has. The id is
//! only used to look up the node's `$allow` annotation in the
//! caller-supplied [`AllowTable`].
//! - An absent `Option<T>` payload / child omits its key entirely
//! (never `null`), matching the canonical-JSON spelling and
//! [`build_field_optional`](crate::build_field_optional)'s absent →
//! `None` rule.
//! - `Vec<T>` payloads always emit, including as `[]` when empty —
//! one unambiguous spelling. ([`build_field_vec`](crate::build_field_vec)
//! accepts the omitted spelling too, so both round-trip; the emit
//! side just never produces it.)
//! - `Vec<Self>` child slots always emit the slot, including empty.
//! A slot declared `non_empty` fails conformance downstream in that
//! case, which is the declared-constraint violation surfacing — not
//! something to paper over here.
//! - Keyed slots (`BTreeMap`) emit in map iteration order, which is
//! already ascending by key — the sortedness
//! [`check_conformance`](crate::check_conformance) demands. Empty
//! maps omit the slot (the PEG front-end's "nothing to record"
//! spelling; both spellings are accepted everywhere it matters).
//! - Spans are `None`: a synthesized tree has no source text.
//!
//! One known asymmetry, inherited rather than introduced: nested
//! `Option<Option<T>>` payloads cannot distinguish `Some(None)` from
//! `None` in JSON (both spell as an absent key / `null`), exactly as on
//! the build side.
use BTreeMap;
use AllowTable;
use Value;
use crate;
use crate::;
// ---------------------------------------------------------------------------
// DslDump
// ---------------------------------------------------------------------------
/// Contract for re-emitting a typed AST value as the [`ParseTree`] its
/// [`DslBuild`](crate::DslBuild) impl accepts.
///
/// Implemented via `#[derive(DslDump)]` in `dsl-kit-macros`;
/// hand-written impls are fine for shapes the derive cannot express,
/// as long as they uphold the round-trip contract in the module docs.
// ---------------------------------------------------------------------------
// Canonical-JSON convenience
// ---------------------------------------------------------------------------
/// Serializes a typed AST straight to canonical serde-bridge JSON:
/// [`DslDump::to_parse_tree`] chained through
/// [`to_canonical_json`](crate::serde_bridge::to_canonical_json)
/// against the type's own derived schema.
///
/// The output is what the JSON front-end
/// ([`from_json_value`](crate::serde_bridge::from_json_value)) parses
/// back into an equivalent AST — the wire form for caching, transport,
/// and content hashing of an AST a program built or transformed in
/// memory.
/// [`dump_canonical_json`] with an [`AllowTable`] so `$allow`
/// annotations survive into the JSON (and therefore into content
/// hashes computed over it).
// ---------------------------------------------------------------------------
// Field helpers (payload side)
// ---------------------------------------------------------------------------
/// Serializes one payload field into the tree as
/// [`RawValue::Json`].
///
/// Dual of [`build_field`](crate::build_field): the emitted value is
/// what `serde_json::from_value` on the build side deserializes back.
/// Serialization failure (a map with non-string keys, a non-finite
/// float, a failing custom `Serialize`) reports
/// [`serde_codes::DUMP_FIELD`].
/// Serializes an optional payload field, omitting the key when `None`.
///
/// Dual of [`build_field_optional`](crate::build_field_optional): the
/// absent key is the canonical spelling of `None`, so `Some(x)` emits
/// `x`'s value (never a JSON `null`).
// ---------------------------------------------------------------------------
// Child helpers (recursive side)
// ---------------------------------------------------------------------------
/// Emits a [`Multiplicity::One`](dsl_kit_schema::Multiplicity::One)
/// child slot. Dual of [`build_child_one`](crate::build_child_one).
/// Emits a
/// [`Multiplicity::Optional`](dsl_kit_schema::Multiplicity::Optional)
/// child slot, omitting the slot entirely when `None`. Dual of
/// [`build_child_optional`](crate::build_child_optional).
///
/// Takes `Option<&T>` rather than `&Option<T>` so `Option<Box<T>>`
/// fields flatten in via `as_deref()`.
/// Emits a [`Multiplicity::Many`](dsl_kit_schema::Multiplicity::Many)
/// child slot — always, including as an empty slot, so the emitted
/// spelling is unambiguous. Dual of
/// [`build_child_many`](crate::build_child_many).
///
/// Takes an iterator of `&T` so `Vec<T>` and `Vec<Box<T>>` fields both
/// feed in without an intermediate collect.
/// Emits a [`Multiplicity::Map`](dsl_kit_schema::Multiplicity::Map)
/// child slot from `(key, node)` entries, omitting the slot when
/// empty. Dual of [`build_child_map`](crate::build_child_map).
///
/// The entries must arrive in ascending key order —
/// [`BTreeMap::iter`] order, which is where the derive reads them
/// from — so the emitted tree passes the
/// [`KEYED_SLOT_UNSORTED`](crate::codes::KEYED_SLOT_UNSORTED)
/// conformance gate.
/// Emits a scalar-valued keyed slot (`BTreeMap<String, V>` where `V`
/// is a payload type) as keyed entries each carrying a single `value`
/// field — the exact shape the JSON front-end builds on ingest and
/// [`build_scalar_map`](crate::build_scalar_map) reads back. Omits the
/// slot when the map is empty.