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
//! The MIRROR MODE: what `#[ingraph::flags(u32, remote = "…")]` adds to a flags declaration.
//!
//! A mirror is a flags set somebody ELSE declared, RESTATED here so this framework has a local type
//! to write impls on. The declaration writes the bits out — names AND numbers, both — and this
//! module writes the crossing between the two types and the pin that keeps the restatement honest.
//!
//! ```ignore
//! // `upstream::Disposition` is the `bitflags!` set another crate declares.
//! // `ingraph-derive/tests/flags_remote.rs` declares one and COMPILES this example, which is what
//! // makes it an example rather than a sketch.
//! #[ingraph::flags(u32, remote = "upstream::Disposition")]
//! #[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
//! pub enum Disposition {
//! Default = 0x1,
//! Forced = 0x2,
//! #[ingraph(rename = "HEARING_IMPAIRED")]
//! Hi = 0x4,
//! }
//! ```
//!
//! # The RESTATEMENT is names AND numbers, where a vocabulary's mirror restates names alone
//!
//! [`enumeration::remote`](crate::enumeration::remote) restates IDENTIFIERS and delegates every
//! word to the upstream's own `Display` and `FromStr`, because a vocabulary's stored form IS a word
//! and two tables over one grammar are two things that can come to disagree. A flags set stores a
//! BIT PATTERN, so the number is the thing that crosses and the word never leaves this crate: the
//! text form is read off THIS declaration's bit table, the wire fields are this declaration's, and
//! the upstream's spelling of a bit is its own business.
//!
//! That inverts what a restatement can get wrong, and the enforcement follows it:
//!
//! | mode | restates | what a mistake IS | who catches it |
//! |---|---|---|---|
//! | `derive(Enum)` mirror | identifiers | a name the upstream has not got | `E0599` at the arm |
//! | `flags` mirror | names and NUMBERS | a number the upstream does not hold | the DRIFT PIN, at compile time |
//!
//! `#[ingraph(rename = "…")]` therefore names the upstream `const` — the same reading the vocabulary
//! mirror's `rename` takes — rather than moving a word, and a mirror's own words stay its own.
//!
//! # The DRIFT PIN is the whole point, and it is a `const`
//!
//! ```ignore
//! const _: () = assert!(Disposition::DEFAULT.bits() as u128 == upstream::Disposition::DEFAULT.bits() as u128);
//! ```
//!
//! One per restated bit. An upstream release that RENUMBERS a bit is a compile error here, in the
//! declaring crate, at the bit that drifted — where without it a mirror would keep crossing values
//! and quietly mean something else, since both sides are just integers and nothing about the
//! crossing could notice.
//!
//! The two sides are cast to [`u128`](core::primitive::u128) rather than compared at their own
//! types, and that is a diagnostic decision rather than arithmetic: an upstream of a DIFFERENT width
//! would otherwise make every pin an `E0308` beside the one named refusal the width law already
//! produces, and a reader would be told the same thing once per bit. Cast, the pin is
//! width-agnostic — so a width fault earns exactly the width sentence and a drift fault earns
//! exactly the drift one.
//!
//! # ABSORPTION: a bit this mirror does not restate is KEPT
//!
//! Both legs of the crossing are `from_bits_retain`, so an upstream value carrying a bit this
//! declaration never named crosses in, survives, and crosses back out as the same number. That is
//! the same posture the vocabulary mirror's escape variant takes and it exists for the same reason:
//! an upstream release that GROWS a bit must not break a build.
//!
//! What names the absence is a TEST-time pin, and this kind gets one for free where the vocabulary
//! kind had to wait for a roster: `<Remote as bitflags::Flags>::FLAGS` is the upstream's own bit
//! table, published by `bitflags!` itself, so a mirror's completeness is walkable without the
//! upstream declaring anything for us. `ingraph-derive/tests/flags_remote.rs` carries that pin,
//! written generically so a mirror arriving in a later commit takes it by naming its own types.
//!
//! **The strict doors are unmoved by any of it**, and the line is *which door*: absorption is what
//! the CROSSING does, and a value reaching this framework from OUTSIDE — an operand a client wrote,
//! a number a row holds, a cursor a process handed back — is still refused when it carries a bit
//! this declaration never named. A mirror is therefore lossless across the crossing and loud at
//! every entrance, which is the posture that keeps an upstream's new bit a thing somebody fixes
//! rather than a thing that decodes into a value this vocabulary cannot spell.
//!
//! The strict TEXT form is the one place an absorbed bit is visible, and `bitflags`' own renderer
//! is what makes it so: a bit with no name renders as a trailing `0x…` token, which the operand
//! grammar already reads back.
//!
//! # What it emits
//!
//! | item | condition |
//! |---|---|
//! | `From<Remote>` and `From<Self> for Remote`, both `from_bits_retain` | always |
//! | one drift pin per restated bit | per bit |
//! | the width obligation below | always |
//!
//! and NOTHING ELSE — no materialization gate, no reference family, no second wire face. The
//! vocabulary mirror emits a `remote()` because its escape holds a WORD and turning one back into an
//! upstream value is real work; here the crossing is a number, `From` is total in both directions,
//! and a gate beside it would be a second name for one conversion.
//!
//! # FOUR things a declaration can get wrong, and whose words say so
//!
//! None of them is checkable at the door — a proc macro cannot see the upstream's declaration — so
//! each is a claim spent against the upstream where the compiler settles it.
//!
//! | the mistake | the refusal | whose words |
//! |---|---|---|
//! | the upstream is not a `bitflags!` set | `E0277` on `bitflags::Flags`, at the `remote = "…"` token | `bitflags`' |
//! | it is one, at another WIDTH | `E0277` on `__IngraphMirrorWidth`, at the same token | this framework's |
//! | a bit's number has DRIFTED | `E0080` at the pin, spanned at the bit | this framework's |
//! | a `rename` names no upstream `const` | `E0599`, spanned at the `rename` literal | rustc's |
//!
//! **The first row was measured rather than settled for.** A marker wrapping the `Flags` bound — a
//! trait carrying `#[diagnostic::on_unimplemented]`, blanket-implemented over it — was written,
//! compiled and thrown away: rustc reports the LEAF obligation, so the headline stayed the foreign
//! trait's and the marker's own sentence never rendered, in either arrangement of
//! `#[diagnostic::do_not_recommend]`. What rustc prints instead names precisely the thing to fix,
//! and `bitflags::Flags` is the honest word for it — the trait `bitflags!` writes, and the one this
//! crate reads every bit table through.
//!
//! The WIDTH row is this framework's because its leaf IS: `__IngraphMirrorWidth` is implemented for
//! exactly one primitive, the declared width, so a differently-carried upstream is an unsatisfied
//! bound on a trait this expansion owns. It is local to the anonymous `const`, so nothing here
//! reaches the framework's shelf for a trait whose whole life is one declaration's expansion.
use ;
use Spanned as _;
use ;
/// A path as a declaration WROTE it, for the sentences that quote one back.