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
//! Walking `#[ingraph(…)]`, whatever a derive keeps inside it.
//!
//! The grammar this layer knows is structural, not semantic: an attribute holds ENTRIES, an entry
//! may be a flag, a `= value`, or a named BLOCK holding entries of its own, and anything declared
//! twice or not recognised at all is refused rather than ignored. What those entries MEAN is the
//! consuming derive's business.
//!
//! Three collapses are worth knowing about, because they were separate ideas before this layer
//! existed:
//!
//! - A block's "declared twice" check is [`set_once`] on the block's own presence. It was a
//! `bool` and a bespoke message; a block is just an option whose value is the fact it was
//! written.
//! - The root of an attribute is a block too — the record's `#[ingraph(…)]` and a field's are the
//! same shape as `key(…)` inside them, differing only in what they accept. So [`unknown`] serves
//! every level, and the caller supplies the sentence naming what that level takes.
//! - "Declared" has three spellings — `sqlite`, `sqlite()`, `sqlite(…)` — and [`options`] is the one
//! place that decides between them. It was the same six-line guard around NINE walkers, and the
//! store families brought six more.
//!
//! Part of the layer every `ingraph` derive parses on; `Record` is its first consumer.
use ToTokens as _;
use crate::;
/// The attribute every `ingraph` derive reads.
const ATTRIBUTE: &str = "ingraph";
/// `#[cfg(…)]` — the one non-`ingraph` field attribute this grammar READS rather than forwards.
const CONDITION: &str = "cfg";
/// `#[cfg_attr(…)]` — conditional decoration, which removes nothing and therefore gates nothing.
const DECORATION: &str = "cfg_attr";
/// A field's CONDITION — its `#[cfg]`s for the family, its `#[cfg_attr]`s for the stand-in.
///
/// The one place a non-`ingraph` field attribute is interpreted, and it interprets exactly two.
/// `rewrite` decides whether the decorations are KEPT: an ordinary declaration's echoed field
/// carries them already — the host forwards every attribute it does not own — so gathering them
/// there would be a second copy of tokens the program already has. A rewrite deletes the field, so
/// its decorations have to be carried or dropped, and they ride the reader beside the doc comments.
///
/// # `#[cfg_attr(pred, ingraph(…))]` is REFUSED, in both modes
///
/// A proc macro cannot evaluate `pred`, so a declaration writing this is asking the macro whether
/// its own word applies — a question it has no way to answer. Today it is not even silent-and-wrong:
/// the walk above filters on `path().is_ident("ingraph")`, and a word wrapped in `cfg_attr` fails
/// that test whichever way the predicate goes, so the word is SILENTLY DROPPED. An attribute nobody
/// reads is a rule its author believes they declared, which is the standing reason this grammar
/// refuses rather than ignores.
pub
/// **IDENTITY IS NOT CONDITIONAL** — a `#[cfg]` on the id or on a lineage step is refused by name.
///
/// Every other field of a declaration is a column the family can lose: the reader goes, the column
/// goes, the seat goes, and what is left is a smaller record. An identity-bearing field is not one
/// of those. It names the ROW — the `*Key` is built from it, `Identifiable` binds its type, `get`
/// addresses by it, a blob's directory path nests under it, and a relation at another declaration
/// resolves through it — so a build that removes one does not make a smaller record, it makes a
/// record with no address, and there is no shape for that.
///
/// The answer is one grain out and the sentence says so: put the `#[cfg]` on the DECLARATION, where
/// two configurations are two records and each has an address of its own.
pub
/// **A REFERENCE IS NOT CONDITIONAL** — `#[cfg]` beside `ref = "…"` on one field is refused by name.
///
/// A `ref` is the one field word that is a fact TWO declarations share, and only one of them can see
/// the condition. What the other side reads is `Related::COLUMNS`, and it reads it POSITIONALLY: the
/// one-reference shorthand resolves `COLUMNS[0]`, so a list that contracted under a predicate would
/// silently hand a reverse position a DIFFERENT column rather than fail. The artifact tuple beside
/// it — `type Fields = (…,)` — cannot contract at all, tuple TYPE elements admitting no attribute,
/// and its arity is what `OneReference` counts.
///
/// So the whole relation family stays unconditional and the refusal says where the condition may go:
/// on a field that refers to nothing, or on the declaration.
pub
/// **A PAGING POSITION IS NOT CONDITIONAL** — a `#[cfg]` on a field of a `cursor` fragment is
/// refused by name.
///
/// It is [`refuse_a_conditional_identity`]'s rule at the tier that bears no identity, and the reason
/// is the same shape: a cursor's key is the fragment's WHOLE declared order — the front end refuses a
/// pin that names a different one or a shorter one — so a build that removes a field does not make a
/// smaller key, it makes a DIFFERENT one. The bytes a cursor carries are the members in that order,
/// and two builds of one program would then write and read frames neither could tell from a forged
/// one; the SQL keyset compares the same columns and would resume a page at a boundary the statement
/// never compared.
///
/// The answer is one grain out, exactly as identity's is: put the `#[cfg]` on the DECLARATION, where
/// two configurations are two fragments and each asserts an order of its own.
pub
/// Refuse a `#[cfg_attr(pred, ingraph(…))]` by name — see [`condition`] for why it cannot be served.
///
/// The entries after the predicate are the ATTRIBUTES the word applies, so the check reads them and
/// nothing else: `#[cfg_attr(unix, serde(skip))]` is another crate's business and passes through.
/// A `cfg_attr` this parse cannot make sense of at all is left alone — rustc refuses a malformed one
/// with its own sentence, and a second refusal over the same tokens says less than that one does.
/// Walk the entries of every `#[ingraph(…)]` attribute in a list, collecting rather than stopping.
///
/// `entry` is called once per entry, and is handed the accumulator so a refusal it records does
/// not end the walk. A parse failure the walk itself hits is recorded too, so a malformed
/// attribute costs one error rather than silence.
///
/// # It answers WHETHER IT READ TO THE END, and an ABSENCE CHECK is what spends the answer
///
/// A parse failure ends the walk at the token that broke it, and every word after that token is
/// UNREAD. So a caller that refuses a declaration for NOT NAMING something — a mandatory clock, a
/// block with no entries, a marked field the head forgot — cannot make that claim over a walk that
/// returned `false`: the word may be written three tokens past where the reader stopped, and
/// telling its author they omitted it is one mistake reported as two, the second one false.
///
/// A plain [`bool`] rather than a `#[must_use]` one, because most callers have no absence check to
/// suppress and ignoring the answer is the right thing for them to do.
pub
/// Enter a named block, recording that it was written and refusing a second one.
///
/// `repeated` is the message for that refusal — the block's meaning is the caller's, so the
/// sentence is too. `entry` is handed the accumulator for the same reason [`walk`] is: a refusal
/// it records must not end the block.
pub
/// Fill an option exactly once. A second value is the refusal, spanned AT the repeat, and the
/// FIRST one is kept so the rest of the pass reads a settled declaration.
pub
/// Refuse an entry this derive does not understand — never accept-and-ignore, because an entry
/// nobody reads is a rule its author believes they declared.
///
/// Swallows whatever the entry carried, so one unrecognised name costs one error rather than one
/// plus a parse failure at the token after it.
///
/// # `vocabulary` is THIS position's words, and it is not optional
///
/// The near-miss round put it in the signature rather than beside it, so that no position can be
/// added without deciding what a typo of its words looks like. `&[]` is the honest answer wherever
/// the refusal is about the entry's SHAPE rather than its spelling — a path where a word belongs, a
/// block that needs the one option it exists for, a word this grammar recognises and refuses for a
/// reason — and it says so at the call rather than by omission.
///
/// The list is what the MESSAGE names. A word the sentence refuses by name is not in it, and
/// neither is a word from a neighbouring scope: see [`crate::suggest`].
pub
/// Refuse an entry this derive DOES understand — [`unknown`]'s shape with the caller's own sentence.
///
/// The refusals that name a rule: a block belonging to another declaration, a word whose round has
/// not arrived. It swallows the entry for the same reason [`unknown`] does — one rule broken should
/// cost one error rather than one plus a parse failure at the token after it — and it is here rather
/// than in either grammar because forgetting that step is the mistake a second copy makes.
pub
/// Whether the entry is followed by a `(…)` block AT ALL.
///
/// The question a marker that may also be a block has to ask: `meta` says "persist this field" and
/// `meta(…)` says the same plus how. Calling `parse_nested_meta` on the first would refuse it
/// ("expected parentheses") for writing the shorter of two legal forms.
pub
/// Whether the entry is followed by a `= value` AT ALL.
///
/// [`has_block`]'s question for the other shape an entry may take. A label word is written bare —
/// `list(string)` — and `list = "…"` is a shape the grammar refuses, so the reader has to SEE the
/// value to say so. Reading it unconditionally would refuse the bare word ("expected `=`") for
/// writing the form the grammar actually takes.
pub
/// The raw tokens inside an entry's `(…)`, uninterpreted.
///
/// For a PASSTHROUGH — an entry whose contents belong to something other than this grammar, and
/// which this grammar must therefore not read. Interpreting them would mean tracking a backend's
/// whole option set here, which is the maintenance the passthrough exists to avoid.
///
/// # Errors
/// A [`syn::Error`] when the entry is not followed by a parenthesized group.
pub
/// Walk an entry's OPTIONS, when a declaration wrote any.
///
/// The three legal spellings of "declared" collapse here: `sqlite`, `sqlite()` and `sqlite(…)` all
/// mean the block was written, and only the third has entries to walk. Asking
/// [`parse_nested_meta`](syn::meta::ParseNestedMeta::parse_nested_meta) directly would refuse the
/// first ("expected parentheses") and the second ("unexpected end of input") — one refusal apiece for
/// writing the shorter of three legal forms — so every block that takes optional options used to
/// carry the same [`has_block`]-and-not-[`empty_group`] guard around its walker. That guard was the
/// shape repeated most in the grammar; it is one decision, and this is where it is made.
///
/// The two guards that stayed are not this shape: `lineage(fields())` REFUSES an empty group rather
/// than reading it as a default, and a [`rename_block`] requires the option that is the only thing
/// it is for.
///
/// # Errors
/// Whatever the walk hit, exactly as `parse_nested_meta` reports it.
pub
/// Whether the entry is followed by an EMPTY `()`.
///
/// Looked at through a fork, so the real stream is untouched for whoever parses it next. Worth
/// asking before walking a list: syn refuses an empty group on its own terms ("unexpected end of
/// input"), which would cost one mistake a second, worse-worded error.
pub
/// Take ONE entry a walk did not claim — its path and whatever followed it — into `carried`,
/// verbatim.
///
/// [`verbatim`]'s twin for a PARTITIONING walk: where `verbatim` carries a whole block because none
/// of it is this grammar's, this carries one entry at a time because SOME of the block is. An
/// engine block is the case that needs it — `tantivy(stored, ef = 200)` holds a framework word and
/// an engine's knob in one pair of parentheses, and the framework's half has to be read while the
/// engine's half stays untouched, spans included.
///
/// The comma between carried entries is re-inserted here, so the result parses as a block's contents
/// again rather than as a run of pasted tokens.
pub
/// Consume whatever an entry carried, up to the comma that ends it.
pub
/// A block whose only job is to name the ONE thing it is about, whatever KIND of name that is.
///
/// The block grammar is one thing and the word's KIND is another, and this is the split: every
/// sentence a declaration can earn from such a block — the bare or empty block, the repeat, the
/// unknown entry — is written HERE, once, and the caller passes only the reader that decides what a
/// legal word looks like. [`rename_block`] and [`sdl_name_block`] are two of the kinds and the
/// index grammar's road blocks are the third; a declaration cannot tell them apart except by which
/// words each accepts.
///
/// `noun` is what the block's contents NAME — a type at every caller in this file, a query FIELD at
/// the index grammar's roads. It is a parameter rather than the fixed word it used to be because
/// the 2026-08-16 rename ruling put field seats and type seats under one grammar: telling a road's
/// author that the block is *for naming the type* would be one sentence describing the wrong axis.
///
/// `pub(crate)` since that ruling, so a grammar whose reader needs facts this layer has no name for
/// — which election, which road — can pass its own closure rather than inventing a second block.
pub
/// A block whose only job is to name the ONE emitted RUST TYPE it is about — IDENT-kind.
///
/// Eight of these across the four derives — the record's `row`, `comparison`, `output`, `key`,
/// `filter` and `order_by`, the vocabulary's `error`, and the `unwrap_error` both member sets take
/// through the seam that emits their refusal — because `rename` names the thing its block is about
/// and a bare one beside them could not say which, which is exactly why the flat spellings are
/// refused.
///
/// It sits in this shared layer rather than in any one grammar because they all spell an
/// emitted-type rename with the SAME words: one reader is what keeps a later derive from inventing
/// its own wording for a rule the first one already has.
pub
/// What the two blocks in this file name — the word their shared sentences read *naming the … is
/// the only thing it is for* with.
///
/// A const rather than the literal at both calls, so the third kind (the index grammar's roads,
/// which name a FIELD) reads as a deliberate difference rather than as a typo of this one.
pub const TYPE: &str = "type";
/// A block whose only job is to name the ONE SCHEMA entity it is about — STRING-kind.
///
/// The same block, the same sentences, one different fence. The user's ruling of 2026-08-13:
/// *graphql 和 db 那边 type 和其他的 rust 关键词都不是问题, 所以我们应该想办法支持* — a word that
/// names a type in GraphQL's own namespace has no Rust identifier behind it, so a Rust KEYWORD is
/// an ordinary word here and `connection(rename = "type")` must be writable.
///
/// So the literal is carried AS a literal and never parsed as a `syn::Ident`, which is the only
/// thing that was refusing it. The fence is [`crate::wire::refuse_invalid_name`]'s GraphQL Name
/// grammar, applied where the word settles — and it is the ONLY fence, which is what makes the
/// classification exception-free: a `rename` that names a Rust type is ident-kind, a word that names
/// a schema entity is string-kind, and the plural was string-kind before either of these was.
pub
/// The refusal when an emitted type's name is not one.
///
/// An IDENTIFIER, unlike a column's `rename`: a column name reaches SQL, where `type` is ordinary
/// and the field carrying it is mangled. A type name reaches only Rust, and mangling it
/// through [`RustSafeName`](ingraph_codegen::name::RustSafeName) would snake_case it — `"S"` would
/// emit a type called `s` — so the literal is parsed as the identifier it has to be, and anything
/// else is refused here. An empty string is the same refusal for the same reason: `""` is not one.
pub const TYPE_NAME: &str =
"a type's `rename` must be a valid identifier, in a string literal";
/// The refusal when a SCHEMA name is not written as a string at all.
///
/// This is the shape refusal only — a missing value, or one that is not a string literal. WHICH
/// strings are legal is GraphQL's Name grammar, refused at the word's own span once it settles, and
/// that check is deliberately not repeated in this sentence: a reader told *a valid identifier* here
/// would conclude a Rust keyword is illegal, which is exactly the belief the 2026-08-13 ruling
/// corrected.
pub const SDL_NAME: &str =
"a schema type's `rename` must be a word in a string literal, as GraphQL spells names";