ingraph-derive 0.1.0

The attribute and derive macros for ingraph: the words a record, node, key, filter and vocabulary declaration is written in.
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
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
1001
1002
1003
1004
1005
1006
1007
1008
1009
1010
1011
1012
1013
1014
1015
1016
1017
1018
1019
1020
1021
1022
1023
1024
1025
1026
1027
1028
1029
1030
1031
1032
1033
1034
1035
1036
1037
1038
1039
1040
1041
1042
1043
1044
1045
1046
1047
1048
1049
1050
1051
1052
1053
1054
1055
1056
1057
1058
1059
1060
1061
1062
1063
1064
1065
1066
1067
1068
1069
1070
1071
1072
1073
1074
1075
1076
1077
1078
1079
1080
1081
1082
1083
1084
1085
1086
1087
1088
1089
1090
1091
1092
1093
1094
1095
1096
1097
1098
1099
1100
1101
1102
1103
1104
1105
1106
1107
1108
1109
1110
1111
1112
1113
1114
1115
1116
1117
1118
1119
1120
1121
1122
1123
1124
1125
1126
1127
1128
1129
1130
1131
1132
1133
1134
1135
1136
1137
1138
1139
1140
1141
1142
1143
1144
1145
1146
1147
1148
1149
1150
1151
1152
1153
1154
1155
1156
1157
1158
1159
1160
1161
1162
1163
1164
1165
1166
1167
1168
1169
1170
1171
1172
1173
1174
1175
1176
1177
1178
1179
1180
1181
1182
1183
1184
1185
1186
1187
1188
1189
1190
1191
1192
1193
1194
1195
1196
1197
1198
1199
1200
1201
1202
1203
1204
1205
1206
1207
1208
1209
1210
1211
1212
1213
1214
1215
1216
1217
1218
//! Validating a TOWER's declaration into the model the emitter consumes.
//!
//! A tower declares its two ENDS and its STEPS, and its steps are its fields:
//!
//! ```ignore
//! #[ingraph::tower(question(type = "String"), answer = "Vec<f32>")]
//! pub struct ClipText {
//!   #[ingraph(answer = "Vec<String>")]     tokenize: Tokenize,
//!   #[ingraph(answer = "Vec<f32>", async)] encode:   ClipTextTower,
//! }
//!
//! #[ingraph::tower]                        // every word omitted: the steps' own canonical lines
//! pub struct Canonical {
//!   tokenize: Tokenize,
//!   #[ingraph(async)] encode: ClipTextTower,
//! }
//! ```
//!
//! # FIELDS ARE STEPS, which is what deleted a naming vocabulary
//!
//! A field's NAME is the step's name and its TYPE is the step's server, so there is nothing here
//! that mints a name and nothing that overrides one. That is the whole reason the inline form's
//! `name =` word and its `stepN` defaults are retired rather than carried: a name an author already
//! wrote cannot disagree with itself, and one name serves the steps struct, the tower's options and
//! the schema row alike.
//!
//! # The words, and what each decides
//!
//! | position | word | omissible | what it decides |
//! |---|---|---|---|
//! | the tower | `question(type = "…")` | yes | what the WHOLE tower is asked — the first step's question |
//! | the tower | `question = "…"` | yes | the same, in the sugar |
//! | the tower | `answer = "…"` | yes | NOTHING — the tower's own end, WRITTEN DOWN and then demanded |
//! | the tower | `answer(type = "…")` | yes | the same, in the full form |
//! | a step | `answer = "…"` | yes | what this step answers — the next step's question |
//! | a step | `async` | — | which FACE this step's hop demands |
//! | a step | `annotate(type = "…")` | yes | ⟂ the stage where the question is ENRICHED IN PLACE, and with what |
//! | a step | `expand(type = "…")` | yes | ② the segment where this question WIDENS, and what widens it |
//! | a step | `route(router = …, slot = "…")` | yes | ④ the segment where it CROSSES into probes, and the wiring |
//!
//! Every question after the first IS the answer before it, so a chain is DERIVED rather than
//! declared: there is no adjacency word, and no pair of words that could disagree about one hop.
//!
//! # THE HEAD'S `answer` IS A DOUBLE ENTRY, and the only word here that decides nothing
//!
//! A tower answers what its LAST STEP answers, and the word at the head cannot change that. What it
//! does is state an INTENT the emission then DEMANDS of the derivation — the source layer's own
//! shape one axis over, where a `mutation` word and a `Mutation` seat are checked against each other
//! at the declaration. So the two spellings at the two positions mean genuinely different things:
//!
//! ```ignore
//! #[ingraph::tower(answer = "Vec<f32>")]        // ← a CLAIM about where the chain arrives
//! pub struct ClipText {
//!   tokenize: Tokenize,
//!   #[ingraph(answer = "Vec<f32>")] encode: Encode,   // ← what this STEP answers, which decides
//! }
//! ```
//!
//! The head word is OPTIONAL and costs an omitting declaration nothing at all — not a bound, not a
//! token. What writing it buys is WHERE a drift is reported: a chain whose last step moved is caught
//! anyway, by whatever bound named the answer it expected, but that refusal lands in the recipe and
//! this one lands at the tower.
//!
//! # THE TWO OVERRIDE WORDS
//!
//! The tower's `question` and a step's `answer` NAME a type where a declaration wants one named, and
//! step aside where the step's own type already says it: a server carrying
//! `impl DefaultServe for Tokenize` has declared, once, what it is canonically asked and what it
//! canonically answers, and an omitted word is that line's projection. So a wholly canonical tower
//! is `#[ingraph::tower]` over a struct of plain fields.
//!
//! Absence is a ROAD and never a gap — but a WRITTEN word still has to point at something. A bare
//! `question`, or one whose block names no `type`, is refused: that is a word that decided nothing,
//! which is a different thing from a word not written.
//!
//! # THE TWO FAN WORDS, and why they are shaped so differently
//!
//! The tower law's amendment is that a tower MAY CONTAIN FANNING SEGMENTS — expansion × lane
//! routing — and that every fan folds before the tower's mouth, leaving the outer contract 1 → 1.
//! A segment is OPENED by a word beside the step it starts at, and closed by the walk: there is no
//! fold word, because where a fan folds is the law's answer rather than an author's.
//!
//! ```ignore
//! #[ingraph::tower(question(type = "String"))]
//! pub struct Road {
//!   #[ingraph(expand = "app::Synonyms")]                          widen:  Widen,
//!   #[ingraph(route(router = script_weighted_fan, slot = "app::BodySlot"))] fan: Fan,
//! }
//! ```
//!
//! **② `expand` NAMES ONE TYPE, so it keeps the two spellings the end words keep.** An expander is
//! a HOOK — a policy a deployment picks at launch and holds erased — so what a declaration writes
//! is the DEFAULT, the deployment overrides it, and the word has exactly one property to carry.
//! `expand = "…"` therefore omits nothing and is legal, and `expand(type = "…")` is the form the
//! vocabulary would grow in. There is NO bare word at this position and there is nothing to add
//! one for: this framework ships no expander, so a synonym table, a spelling fixer and a translator
//! are all the declaring crate's and all arrive quoted.
//!
//! **④ `route` NAMES TWO, so its GROUP FORM IS THE CITIZEN.** A router is a CAPABILITY rather than
//! a policy: what makes a mis-wiring `E0271` at the seat instead of a conversion in the middle is
//! an EQUALITY between what the router answers and what the slot's lanes are asked with, and a
//! grammar holding one half of an equality holds none of it. So the entry names the ROUTER and the
//! SLOT, both by name, and `route = <router>` is refused pointing at the full form rather than
//! accepted with the wiring guessed — the measure entry's own tooth, one grammar over. The router
//! half is MINT BARE, REFER QUOTED: three shipped routers have bare words, and every other router
//! there is arrives as a path.
//!
//! # ⟂ THE THIRD WORD, and the one whose ENDS ARE THE SAME TYPE
//!
//! ```ignore
//! #[ingraph::tower(question(type = "app::Ask"))]
//! pub struct Road {
//!   #[ingraph(annotate = "app::LanguageTag", async)] detect: Door<app::Ask, app::Ask>,
//!   #[ingraph(expand = "app::Synonyms")]             widen:  Expansion<app::Ask>,
//! }
//! ```
//!
//! **`annotate` NAMES ONE TYPE, so it keeps the two spellings the end words keep** — and what it
//! names is the ANNOTATION rather than the operator, which is the whole difference from ②. An
//! expander is a hook a deployment mounts, so `expand` writes down a default; an annotation stage's
//! operator is an ordinary SERVER and the field's own type is already its name. What no type can say
//! is WHICH annotation this stage fills, and that is what the word carries.
//!
//! The stage ANNOTATES rather than transforms: it is handed the question and hands back the same
//! question, one fact richer. So there is no `answer` word here — both ends are the type the chain
//! already arrived at — and one written is refused BY NAME rather than read as a second spelling of
//! the line above it. There IS an `async` word, and it means exactly what it means everywhere else:
//! the step holds a server, and a server behind a transient edge wears the awaited face.
//!
//! # THE STAGE ORDER IS THE FRAMEWORK'S OPINION, and out of order is refused BY NAME
//!
//! ⟂ runs before ②, and ② before ④, always. A widening is an endomorphism over QUESTIONS and a
//! routing crosses a question into PROBES, so an expansion after a routing would have to widen a
//! probe — a different type, in a currency whichever store holds that lane chose. And an annotation
//! runs before both because both READ it: a widening's targets and a crossing's lanes come off what
//! the annotation wrote, and a step's answer travels downstream only — a stage that filled the seat
//! after them would fill it for nobody.
//!
//! The tower grammar had no ordering machinery to express this with (steps are fields, and adjacency
//! is derived rather than declared), so the order is stated in the model as `Stage`'s own [`Ord`]
//! and checked here. A declaration that writes them the other way round is REFUSED naming both
//! steps, and never silently reordered: the fields are the walk, and a pass that moved one would be
//! rewriting the chain its author wrote.
//!
//! ONE SEGMENT OF EACH KIND, and each kind has its own reason. The fold's arithmetic is defined
//! over one expansion family and one lane fan — the family dedup takes *original + widenings* as
//! one witness, and the weights compose one lane emphasis with one arm weight — so a second segment
//! of either kind is refused by name rather than accepted into a fold with no law for it. A second
//! ANNOTATION stage is refused for a sharper reason: fill-if-absent means it would run exactly
//! where the first one did not fill the seat, which is nowhere. **A tower wanting two DIFFERENT
//! annotations is a door**, recorded rather than opened: the seat's parameter already admits it and
//! what a second word would need is a rule this pass cannot keep, two type strings being two
//! spellings a token pass cannot compare.
//!
//! # What this pass can see, and what it cannot
//!
//! It sees TOKENS. So it enforces the SHAPE — a named-field struct with at least one field, no
//! generic parameter, and a value under every word that takes one — and nothing about whether the
//! types it was handed serve anything, or declare a canonical line. That half is the EMISSION's,
//! where the compiler can see it: the chain is stated as one `where` predicate per step, so a hop
//! that does not meet is `E0277` with the caret on the step's own field, and a step whose type has
//! no `DefaultServe` to read an omitted word off is the same `E0277` at the same place. The head
//! pin is the same division once more: this pass reads a TYPE out of a string, and whether the chain
//! arrives at it is `E0271` where the compiler resolves both.
//!
//! **THE FAN'S OWN HALF OF THAT DIVISION, censused rather than guessed.** What is REAL at parse is
//! everything positional: which steps carry which word, that each kind is written once, that ② comes
//! before ④, that one step opens one fan, and that both halves of the wiring are named. What is NOT
//! real at parse is every claim about SHAPE — whether a router's `Routed` meets the slot's
//! `LanedStore::Probe`, whether an expander widens the type the chain arrived at, and whether what
//! the fanned arms come back with can HOST a fold at all. Those are type facts about types this
//! pass reads out of strings, so none of them is checkable here and none is checked here: they are
//! the emission's `E0271` and `E0277`, at the step's own field, exactly where a broken hop already
//! lands. A refusal invented here for one of them would be a rule this pass cannot keep.

use ingraph_codegen::tower::{Fan, Router, Stage, StepModel, TowerModel};

use crate::{attribute, errors::Errors, value};

#[cfg(test)]
mod tests;

/// Validate a decorated declaration into the model the emitter consumes.
///
/// # Errors
/// A [`syn::Error`] carrying EVERY rule the pass could still see violated, each spanned at the token
/// that violated it, so one compile reports the whole declaration's problems.
pub(crate) fn parse(
  input: &syn::DeriveInput,
  arguments: &[syn::Attribute],
) -> syn::Result<TowerModel> {
  let mut errors = Errors::default();
  crate::host::refuse_a_moved_option_block(&input.attrs, &mut errors);
  let (krate, question, answer) = options(arguments, &mut errors);
  concrete(&input.generics, &mut errors);

  let fields = match named_fields(input) {
    Ok(fields) => fields,
    Err(terminal) => return Err(errors.seal(terminal)),
  };

  let steps: Vec<StepModel> = fields
    .named
    .iter()
    .filter_map(|field| {
      let name = field.ident.clone()?;
      Some(step(field, name, &mut errors))
    })
    .collect();
  segments(&steps, &mut errors);

  errors.into_result(TowerModel {
    krate: krate.unwrap_or_else(|| syn::parse_quote!(::ingraph)),
    name: input.ident.clone(),
    vis: input.vis.clone(),
    // ABSENCE IS A ROAD, not a gap: an unwritten question is the first step's canonical one, which
    // the emission spells as a projection off that step's own type.
    question,
    // ABSENCE IS THE WHOLE ROAD here: an unwritten head answer is not a projection standing in for a
    // word, it is a declaration that stated no intent — so nothing is emitted and nothing is checked.
    answer,
    steps,
  })
}

/// Walk the declaration-level attribute: the tower's two END WORDS, and where `ingraph` lives.
fn options(
  attrs: &[syn::Attribute],
  errors: &mut Errors,
) -> (Option<syn::Path>, Option<syn::Type>, Option<syn::Type>) {
  let mut krate: Option<syn::Path> = None;
  let mut question: Option<syn::Type> = None;
  let mut answer: Option<syn::Type> = None;

  attribute::walk(attrs, errors, |meta, errors| {
    // `crate` is a keyword; syn's nested-meta path parser takes it with `Ident::parse_any`, so it
    // arrives here as an ordinary one-segment path.
    if meta.path.is_ident("crate") {
      match value::parse_literal::<syn::Path>(
        &meta,
        "`#[ingraph(crate = \"…\")]` must be a path to the `ingraph` crate, in a string literal",
      ) {
        Ok(path) => attribute::set_once(
          &mut krate,
          path,
          &meta.path,
          "`crate` is declared more than once — one declaration names one crate",
          errors,
        ),
        Err(e) => refuse_value(&meta, e, errors),
      }
      return Ok(());
    }

    if meta.path.is_ident("question") {
      return one_type(&meta, &mut question, &QUESTION, errors);
    }

    if meta.path.is_ident("answer") {
      return one_type(&meta, &mut answer, &ANSWER, errors);
    }

    // THE RETIRED INLINE FORM. `tower(arm(chain(…)))` was written on an ELECTION, and both of its
    // inner words are refused BY NAME rather than as unknowns: an author moving a declaration
    // across needs to be told where the form went, and a near-miss list would only suggest a word
    // that is not the answer.
    if let Some(word) = RETIRED_INLINE.iter().find(|word| meta.path.is_ident(*word)) {
      errors.push(attribute::named(&meta, retired_inline(word)));
      return Ok(());
    }

    errors.push(attribute::unknown(
      &meta,
      "unknown entry in `#[ingraph::tower(…)]` — it takes `question(type = \"…\")` (what the whole \
       tower is asked), `answer(type = \"…\")` (what its chain must ARRIVE at, checked against the \
       last step's own answer), each also spellable as `… = \"…\"`, and `crate = \"…\"`. WHAT the \
       steps are is the declaration's own fields, and what each answers is the word beside it",
      &["question", "answer", "crate"],
    ));
    Ok(())
  });

  (krate, question, answer)
}

/// A WORD THAT NAMES ONE TYPE, in either of its two spellings.
///
/// The FULL FORM is the one the vocabulary grows in — a later word about the same subject has a
/// block to live in — and the sugar is the shape a declaration that has nothing else to say writes.
/// Both fill one seat, so writing both is the ordinary second-declaration refusal.
///
/// ONE READER for all three positions, and the SENTENCES travel beside the seat: the tower's two
/// ends and a step's `expand` are written identically and differ only in what they mean, so a second
/// copy of this walk would be a place for three spellings to drift apart. What each says is
/// [`OneType`]'s.
///
/// It is generic over WHAT KIND OF TYPE the seat holds, which is the one axis the three positions do
/// differ on: an END names a data type and may be `Vec<f32>`, and a MOUNT names an implementation
/// this expansion will write a binding through, which is a path. The parse is the fence either way,
/// so the sentence a wrong value earns is still the position's own.
fn one_type<T: syn::parse::Parse>(
  meta: &syn::meta::ParseNestedMeta<'_>,
  seat: &mut Option<T>,
  words: &OneType,
  errors: &mut Errors,
) -> syn::Result<()> {
  if attribute::has_value(meta) {
    match value::parse_literal::<T>(meta, words.ty) {
      Ok(named) => attribute::set_once(seat, named, &meta.path, words.twice, errors),
      Err(e) => refuse_value(meta, e, errors),
    }
    return Ok(());
  }

  if !attribute::has_block(meta) || attribute::empty_group(meta) {
    errors.push(attribute::unknown(meta, words.empty, &[]));
    return Ok(());
  }

  let mut typed_at: Option<syn::Path> = None;
  // AN ENTRY THIS BLOCK COULD NOT PLACE, and the reason the absence check below is conditional on
  // it: a word whose MEANING is unknown is a word that may have been the one thing the block wanted,
  // so `question(kind = "String")` is ONE mistake and telling its author they also named no type
  // would be the second half of their typo reported as a rule they broke. The measure entry's
  // `refused` flag, at the one reader all three of this grammar's type words share.
  let mut refused = false;
  let walked = meta.parse_nested_meta(|inner| {
    // `type` is a keyword, and arrives as a one-segment path for `crate`'s reason above.
    if inner.path.is_ident("type") {
      typed_at = Some(inner.path.clone());
      match value::parse_literal::<T>(&inner, words.ty) {
        Ok(named) => attribute::set_once(seat, named, &inner.path, words.twice, errors),
        Err(e) => refuse_value(&inner, e, errors),
      }
      return Ok(());
    }

    refused = true;
    errors.push(attribute::unknown(&inner, words.inner, &["type"]));
    Ok(())
  });
  if let Err(e) = walked {
    refused = true;
    errors.push(e);
  }

  if seat.is_none() && typed_at.is_none() && !refused {
    errors.push(syn::Error::new_spanned(&meta.path, words.empty));
  }
  Ok(())
}

/// ONE STEP — the field, and the words beside it.
fn step(field: &syn::Field, name: syn::Ident, errors: &mut Errors) -> StepModel {
  let mut answer: Option<syn::Type> = None;
  // WHERE `answer` WAS WRITTEN, kept for the ⟂ refusal alone: a word that decides nothing at this
  // position has to be refused AT ITSELF, and the attribute walk has moved on by the time the
  // annotation seat is known to be filled.
  let mut answered_at: Option<syn::Path> = None;
  let mut awaited: Option<syn::Path> = None;
  // THE THREE SEGMENT WORDS ARE READ INTO SEPARATE SEATS and joined afterwards, which is what lets
  // each keep its own second-declaration sentence: a step that wrote `expand` twice is told about
  // `expand`, and a step that wrote one of each is told the law that refuses the pair.
  let mut annotation: Option<syn::Type> = None;
  let mut expander: Option<syn::Path> = None;
  let mut routed: Option<Fan> = None;

  attribute::walk(&field.attrs, errors, |meta, errors| {
    if meta.path.is_ident("answer") {
      answered_at.get_or_insert_with(|| meta.path.clone());
      match value::parse_literal::<syn::Type>(&meta, STEP_ANSWER_TYPE) {
        Ok(answered) => attribute::set_once(
          &mut answer,
          answered,
          &meta.path,
          "`answer` is declared more than once on this step — one step answers one type, and the \
           next step's question is it",
          errors,
        ),
        Err(e) => refuse_value(&meta, e, errors),
      }
      return Ok(());
    }

    // THE FACE WORD, and the fifth position in this framework where a word chooses one —
    // `source(async)`, `handler(async)`, `operator(async)` and `resource(async)` are the other
    // four, and this is the first that is per FIELD. It carries nothing: what the faces DO is the
    // step author's own impl, and the whole content of the word is which of the two the emitted
    // chain demands.
    if meta.path.is_ident("async") {
      if attribute::has_value(&meta) || attribute::has_block(&meta) {
        errors.push(attribute::named(&meta, ASYNC_BARE.to_owned()));
        return Ok(());
      }
      attribute::set_once(
        &mut awaited,
        meta.path.clone(),
        &meta.path,
        "`async` is declared more than once on this step — one step wears one face",
        errors,
      );
      return Ok(());
    }

    // ⟂ THE ANNOTATION. One property, so both spellings are legal and neither omits anything.
    if meta.path.is_ident(ANNOTATE) {
      return one_type(&meta, &mut annotation, &ANNOTATION, errors);
    }

    // ② THE WIDENING. One property, so both spellings are legal and neither omits anything.
    if meta.path.is_ident(EXPAND) {
      return one_type(&meta, &mut expander, &EXPANDER, errors);
    }

    // ④ THE CROSSING. Two properties, so the group form is the citizen and the sugar is refused.
    if meta.path.is_ident(ROUTE) {
      return route(&meta, &mut routed, &name, errors);
    }

    // RESERVED, and refused with the law rather than as an unknown: the seat this word will reach
    // is the SERVER's, and a step whose server seats `()` has no row for one to fill.
    if meta.path.is_ident("options") {
      errors.push(attribute::named(&meta, options_reserved(&name)));
      return Ok(());
    }

    // THE RETIRED INLINE FORM's naming word, refused by name for the reason its outer words are.
    if meta.path.is_ident("name") {
      errors.push(attribute::named(&meta, retired_name(&name)));
      return Ok(());
    }

    errors.push(attribute::unknown(
      &meta,
      "unknown entry in `#[ingraph(…)]` on a step — a step takes `answer = \"…\"` (what it \
       answers, which is the next step's question), `async` (which face its hop demands), and the \
       three words that open a PIPELINE STAGE: `annotate(type = \"…\")`, where the question is \
       enriched in place, `expand(type = \"…\")`, where it widens, and `route(router = …, slot = \
       \"…\")`, where it crosses into one probe per lane. Its NAME is the field's own and its \
       SERVER is the field's type, so neither has a word",
      &["answer", "async", ANNOTATE, EXPAND, ROUTE],
    ));
    Ok(())
  });

  let (annotation, fan) = segment(annotation, expander, routed, &name, errors);
  // **A FAN STEP HAS NO SERVER FOR A FACE TO BE ABOUT**, which is what the walk found when it came
  // to spend one. A segment's field holds the SEGMENT'S SEAT — the value a deployment assembles an
  // expander or a router into — and a seat answers no `serve` call, so `async` here would be a word
  // choosing between two faces neither of which is asked for. It is refused rather than ignored, on
  // the house law that every word either acts or refuses loudly.
  //
  // ⟂ IS NOT IN THIS RULE AND THAT IS THE STAGE'S OWN SHAPE: an annotation step holds a SERVER —
  // the operator that detects, classifies or looks up — so `async` there names exactly what it names
  // everywhere else, and an LID behind a `Door` onto a graph resident is precisely the step that
  // wears it.
  if let (Some(fan), Some(at)) = (&fan, &awaited) {
    errors.push(syn::Error::new_spanned(at, fan_wears_no_face(&name, fan)));
  }
  // ⟂ **THE ANSWER WORD DECIDES NOTHING HERE**, so it is refused BY NAME rather than read as a
  // second spelling of the question one line above.
  if let (Some(_), Some(at)) = (&annotation, &answered_at) {
    errors.push(syn::Error::new_spanned(
      at,
      annotation_answers_itself(&name),
    ));
  }

  StepModel {
    field: name.clone(),
    ty: field.ty.clone(),
    answer,
    awaited: awaited.is_some(),
    fan,
    annotation,
  }
}

/// The refusal `async` beside a fan word earns.
fn fan_wears_no_face(field: &syn::Ident, fan: &Fan) -> String {
  let (segment, face) = match fan {
    Fan::Expand { .. } => (
      "the WIDENING",
      "an expansion awaits through the expand seam's own call face, and a blocking expander reaches \
       it through the lift bridge",
    ),
    Fan::Route { .. } => (
      "the CROSSING",
      "routing is pure computation over a question and a roster, so a router has one face and it is \
       the blocking one",
    ),
  };
  format!(
    "`async` names the face a step's SERVER wears, and `{field}` opens {segment} rather than \
     holding a server — `{word}` puts the segment's own SEAT in this field, and a seat answers no \
     `serve` call for a face to be about. What face the SEGMENT wears is not an author's to choose: \
     {face}. Take the word off",
    word = fan.word(),
  )
}

/// THE STEP'S ONE SEGMENT SEAT, out of the three words that could have filled it.
///
/// A step opens ONE stage. `annotate` says *the question is enriched here*, `expand` says *it widens
/// here* and `route` says *it crosses into probes here*, and those are three stages of the pipeline
/// rather than three facts about one hop — the stage ORDER is the whole of what a separate-step
/// spelling states, and a step wearing two would state it about itself. NEITHER of a written pair is
/// kept, which is [`attribute::set_once`]'s law reaching its limit: with two words equally written
/// there is no FIRST one to settle on, and the declaration is refused anyway, so nothing downstream
/// reads the seat.
///
/// The pair is reported ONCE however many words a step wrote, which is the near-miss discipline at
/// the grain of a law: three words on one field is one mistake, and naming the three pairs it makes
/// would be that mistake reported three times.
///
/// Spanned at the FIELD, which is the step's own span and the one token every such word is beside.
fn segment(
  annotation: Option<syn::Type>,
  expander: Option<syn::Path>,
  routed: Option<Fan>,
  field: &syn::Ident,
  errors: &mut Errors,
) -> (Option<syn::Type>, Option<Fan>) {
  let written: Vec<&'static str> = [
    annotation.is_some().then_some(ANNOTATE),
    expander.is_some().then_some(EXPAND),
    routed.is_some().then_some(ROUTE),
  ]
  .into_iter()
  .flatten()
  .collect();
  if written.len() > 1 {
    errors.push(syn::Error::new_spanned(
      field,
      one_segment_per_step(field, &written),
    ));
    return (None, None);
  }
  let fan = match (expander, routed) {
    (Some(expander), _) => Some(Fan::Expand { expander }),
    (None, routed) => routed,
  };
  (annotation, fan)
}

/// Record a refusal about an entry's VALUE, and swallow the entry it was written in.
///
/// [`attribute::unknown`]'s law applied to the other half of a grammar: a value reader leaves the
/// token it could not read where it found it, so a walk that resumed there would earn syn's own
/// `expected ,` at the same column.
fn refuse_value(meta: &syn::meta::ParseNestedMeta<'_>, error: syn::Error, errors: &mut Errors) {
  errors.push(error);
  attribute::skip_entry(meta);
}

/// The fields a tower's steps are read off.
///
/// # Errors
/// A [`syn::Error`] where the declaration is not a struct with at least one named field — the one
/// refusal that is TERMINAL here, there being no steps to check the rest of the rules against.
fn named_fields(input: &syn::DeriveInput) -> syn::Result<&syn::FieldsNamed> {
  match &input.data {
    syn::Data::Struct(data) => match &data.fields {
      syn::Fields::Named(named) if !named.named.is_empty() => Ok(named),
      syn::Fields::Named(named) => Err(syn::Error::new_spanned(named, EMPTY_TOWER)),
      syn::Fields::Unit => Err(syn::Error::new_spanned(&input.ident, EMPTY_TOWER)),
      syn::Fields::Unnamed(unnamed) => Err(syn::Error::new_spanned(unnamed, POSITIONAL_STEPS)),
    },
    syn::Data::Enum(_) | syn::Data::Union(_) => Err(syn::Error::new_spanned(
      &input.ident,
      "`#[ingraph::tower]` supports structs only — a tower's FIELDS are its steps, in the order \
       they are walked, and variants are a choice between things rather than a chain of them",
    )),
  }
}

/// A tower declaration takes no generic parameter.
///
/// The emission states ONE chain over ONE type, and a parameter is not a type until it is
/// substituted — so a generic tower would state the connectivity for nobody, and the theorem the
/// chain exists to prove would be proved about no program.
fn concrete(generics: &syn::Generics, errors: &mut Errors) {
  const WHY: &str = "a tower takes no generic parameter — the emission states ONE chain over ONE \
                     declaration, and a parameter is not a type until it is substituted, so a \
                     generic tower would prove its connectivity for nobody";
  if !generics.params.is_empty() {
    errors.push(syn::Error::new_spanned(generics, WHY));
  } else if let Some(clause) = &generics.where_clause {
    errors.push(syn::Error::new_spanned(clause, WHY));
  }
}

/// The words the RETIRED inline form wrote at the tower position.
const RETIRED_INLINE: &[&str] = &["arm", "chain"];

/// The refusal a retired inline-form word earns, naming where the form went.
fn retired_inline(word: &str) -> String {
  format!(
    "`{word}` is the RETIRED inline tower form — `tower(arm(chain(…)))`, written on an election. A \
     tower is its OWN declaration now and its fields are its steps; what binds one to an index is \
     the search recipe's own `tower(…)` word, so an election carries no tower vocabulary at all"
  )
}

/// The refusal the inline form's naming word earns on a step.
fn retired_name(field: &syn::Ident) -> String {
  format!(
    "`name` is the retired inline form's word — `{field}` already IS this step's name. Fields are \
     steps, so one name serves the steps struct, the tower's options and the schema row, and there \
     is no default for an override word to correct"
  )
}

/// The refusal the reserved `options` word earns, naming the seat it would reach.
///
/// The `()`-SEAT LAW is the sentence's second half and the reason the word is refused BY NAME
/// rather than as an unknown: a step's knobs are declared once, on the SERVER, and the emitted
/// `<Tower>StepOptions` already carries one row per step — so an options word here is a second spelling
/// of a seat that exists, and for a `()`-seated step it is a name for knobs nothing reads. Neither
/// is something a near-miss list can point at.
fn options_reserved(field: &syn::Ident) -> String {
  format!(
    "`options` is not a step's word. A step's knobs are its SERVER's own `Serve::Options` seat — \
     `{field}`'s type declares it, not this declaration — and what a caller names reaches that seat \
     through the emitted `<Tower>StepOptions`, which carries one row per step already. A step whose \
     server seats `()` takes no knobs at all, so an options word written for one would be naming \
     knobs nothing reads"
  )
}

/// ⟂ — the word that opens an ANNOTATION.
const ANNOTATE: &str = "annotate";

/// ② — the word that opens a WIDENING.
const EXPAND: &str = "expand";

/// ④ — the word that opens a CROSSING.
const ROUTE: &str = "route";

/// `route(…)`'s first property: WHO cuts a question into lanes.
const ROUTER: &str = "router";

/// `route(…)`'s second property: WHOSE lanes, and the currency they are asked in.
const SLOT: &str = "slot";

/// **⟂ THE ANNOTATION** — one property, so both spellings are legal and neither omits anything.
///
/// The word names WHAT THE STAGE WRITES rather than who writes it, and that is the whole difference
/// between this position and ②'s. An expander is a HOOK, so `expand` names the type a deployment
/// gets by default; an annotation stage's operator is an ordinary SERVER and the field's own type
/// already names it — a `Door` onto a graph resident, an in-process detector, a lookup. What the
/// declaration still has to say is the thing no type can say for it: which ANNOTATION this stage
/// fills, because that is what *fill if absent* is a test about and what the stages downstream read.
const ANNOTATION: OneType = OneType {
  empty: "`annotate` names no type — write `annotate = \"path::to::Annotation\"`, or \
          `annotate(type = \"path::to::Annotation\")` for the full form. There is no bare word to \
          write instead: what a question is enriched WITH is the declaring crate's own type, and a \
          language tag, a detected script and a classified intent are all one mechanism here",
  ty: "`annotate` names the TYPE this stage writes into the question — quoted, because the word \
       names a type this declaration did not mint and the compiler resolves where the expansion \
       lands. It is what the walk asks the question about before it spends the step's operator: a \
       question already carrying one is handed on untouched",
  twice: "`annotate` is declared more than once on this step — one step fills one annotation, and \
          the full form and the sugar fill the same seat",
  inner: "unknown entry in `annotate(…)` — it names the TYPE this stage writes into the question \
          and nothing else. WHO writes it is the field's own type, and whether a caller already \
          supplied one is the question's own answer rather than a word",
};

/// **② THE WIDENING** — one property, so both spellings are legal and neither omits anything.
///
/// An expander is a HOOK: a deployment picks one at launch and holds it erased, so what this word
/// writes down is the declaration's DEFAULT rather than the instance. That is the same three-party
/// governance the fold door already keeps — a request never chooses an implementation, a declaration
/// defaults one, a deployment overrides at launch — and it is why the word names a TYPE rather than
/// a value.
const EXPANDER: OneType = OneType {
  empty: "`expand` names no type — write `expand = \"path::to::Expander\"`, or `expand(type = \
          \"path::to::Expander\")` for the full form. There is no bare word to write instead: this \
          framework ships no expander, so a synonym table, a spelling fixer and a translator are \
          all the declaring crate's",
  ty: "`expand` names the TYPE that widens this question — quoted, because the word names a type \
       this declaration did not mint and the compiler resolves where the expansion lands. What it \
       writes down is this declaration's DEFAULT; a deployment installs its own at launch",
  twice: "`expand` is declared more than once on this step — one step opens one widening, and the \
          full form and the sugar fill the same seat",
  inner: "unknown entry in `expand(…)` — it names the TYPE that widens this question and nothing \
          else. How wide a widening goes is the expander's own knobs, and what an arm is weighted \
          by is the tower's own options",
};

/// **④ THE CROSSING** — the fan word that ties a router to the lanes machinery.
///
/// # THE GROUP FORM IS THE CITIZEN, and there is no sugar at all
///
/// The entry names TWO things, so the full-form law binds without a case to argue: a wiring is an
/// EQUALITY between what a router answers and what one lane of a slot is asked with, and a grammar
/// holding one half of an equality holds none of it. `route = <router>` is therefore refused
/// pointing at the full form rather than accepted with the slot guessed — the measure entry's own
/// tooth one grammar over, where a fold that reads a column has no seat in the short spelling and
/// earns the long one by name.
///
/// # A TABLE, because this entry IS the seat's growth point
///
/// The properties are DATA, which is the measure entry's shape and the `cursor(…)` block's before
/// it: a new property is one row here and one pair of fields on [`RouteForm`], and the near-miss
/// vocabulary, the printed roster and the sentence an unknown word earns all derive from this array
/// and are restated nowhere.
///
/// # Errors
/// Whatever the property walk hit, which is the one thing this reader cannot step over.
fn route(
  meta: &syn::meta::ParseNestedMeta<'_>,
  seat: &mut Option<Fan>,
  field: &syn::Ident,
  errors: &mut Errors,
) -> syn::Result<()> {
  if attribute::has_value(meta) {
    errors.push(attribute::named(meta, route_has_no_sugar(field)));
    return Ok(());
  }
  if !attribute::has_block(meta) || attribute::empty_group(meta) {
    errors.push(attribute::named(meta, route_names_its_properties(field)));
    return Ok(());
  }

  let mut written = RouteForm::default();
  meta.parse_nested_meta(|property| {
    match ROUTE_PROPERTIES
      .iter()
      .find(|known| property.path.is_ident(known.word))
    {
      Some(known) => (known.read)(&property, &mut written, field, errors),
      None => {
        written.refused = true;
        errors.push(attribute::unknown(
          &property,
          &unknown_route_property(field),
          &property_words(),
        ));
      }
    }
    Ok(())
  })?;

  if let Some(fan) = settled(written, &meta.path, field, errors) {
    attribute::set_once(seat, fan, &meta.path, &route_twice(field), errors);
  }
  Ok(())
}

/// ONE property a `route(…)` entry takes — the word an author writes, and the reader that takes it.
struct RouteProperty {
  /// The word, as it is written.
  word: &'static str,
  /// What it fills in — and what it refuses with, which is the property's own business.
  read: fn(&syn::meta::ParseNestedMeta<'_>, &mut RouteForm, &syn::Ident, &mut Errors),
}

/// Everything a `route(…)` entry takes today.
const ROUTE_PROPERTIES: &[RouteProperty] = &[
  RouteProperty {
    word: ROUTER,
    read: read_router,
  },
  RouteProperty {
    word: SLOT,
    read: read_slot,
  },
];

/// What one `route(…)` entry was read into.
#[derive(Default)]
struct RouteForm {
  /// `router = …`, where it was read.
  router: Option<Router>,
  /// Whether `router` was written AT ALL, however badly.
  ///
  /// The `role_spoken` device at the property grain: an entry whose router was refused BY NAME must
  /// not also earn the names-no-router sentence, which would tell an author who did name one that
  /// they did not.
  router_spoken: bool,
  /// `slot = "…"`, where it was read.
  slot: Option<syn::Path>,
  /// Whether `slot` was written at all, for [`router_spoken`](Self::router_spoken)'s reason.
  slot_spoken: bool,
  /// Whether a property this entry does not know was written in it.
  ///
  /// The same device at the grain of the whole entry, and the same law the aggregate head's own
  /// `whole` flag states: a word the reader could not place is a word whose MEANING is unknown, so
  /// an absence check that would have read it cannot be run. `route(router = fan_all, slt = "S")`
  /// is one mistake, and telling its author their entry also names no slot would be the second half
  /// of their typo reported as a rule they broke.
  refused: bool,
}

/// The ROUTER property's reader.
fn read_router(
  property: &syn::meta::ParseNestedMeta<'_>,
  written: &mut RouteForm,
  field: &syn::Ident,
  errors: &mut Errors,
) {
  if written.router_spoken {
    errors.push(attribute::named(property, property_once(ROUTER, field)));
    return;
  }
  written.router_spoken = true;
  written.router = router_value(property, field, errors);
}

/// The SLOT property's reader.
fn read_slot(
  property: &syn::meta::ParseNestedMeta<'_>,
  written: &mut RouteForm,
  field: &syn::Ident,
  errors: &mut Errors,
) {
  if written.slot_spoken {
    errors.push(attribute::named(property, property_once(SLOT, field)));
    return;
  }
  written.slot_spoken = true;
  match value::parse_literal::<syn::Path>(property, SLOT_IS_A_QUOTED_PATH) {
    Ok(slot) => written.slot = Some(slot),
    Err(e) => refuse_value(property, e, errors),
  }
}

/// **MINT BARE, REFER QUOTED** at the position that names who cuts a question into lanes.
///
/// A BARE word is one of the routers this framework ships; a QUOTED path is a router the declaring
/// crate wrote. The two are told apart by LOOKING AT THE VALUE rather than by asking an author to
/// spell the distinction twice — choosing between a shipped router and one's own is choosing a
/// value, not writing a different property.
fn router_value(
  property: &syn::meta::ParseNestedMeta<'_>,
  field: &syn::Ident,
  errors: &mut Errors,
) -> Option<Router> {
  let Ok(stream) = property.value() else {
    errors.push(attribute::named(property, router_shape(field)));
    return None;
  };
  if stream.peek(syn::LitStr) {
    // The QUOTED half. Nothing here resolves the path — the emission writes it, and a path naming
    // nothing is rustc's own refusal at the string the author wrote.
    return match stream
      .parse::<syn::LitStr>()
      .and_then(|spelled| spelled.parse::<syn::Path>())
    {
      Ok(path) => Some(Router::Declared(path)),
      Err(e) => {
        errors.push(syn::Error::new(e.span(), ROUTER_IS_A_PATH));
        attribute::skip_entry(property);
        None
      }
    };
  }
  if stream.peek(syn::Ident) {
    let Ok(word) = stream.parse::<syn::Ident>() else {
      errors.push(attribute::named(property, router_shape(field)));
      return None;
    };
    let Some(shipped) = Router::shipped(&word.to_string()) else {
      errors.push(syn::Error::new_spanned(
        &word,
        format!(
          "{unknown}{suggestion}",
          unknown = unshipped_router(&word),
          suggestion = crate::suggest::did_you_mean(&word.to_string(), Router::SHIPPED),
        ),
      ));
      attribute::skip_entry(property);
      return None;
    };
    // A TAIL after the word — `router = fan_all(…)` reads as the word with a group behind it, and a
    // reader that stopped at the word would leave the leftover to syn, whose sentence names the
    // punctuation rather than the rule. The measure entry's own measured lesson.
    if !property.input.is_empty() && !property.input.peek(syn::Token![,]) {
      errors.push(syn::Error::new_spanned(&word, router_shape(field)));
      attribute::skip_entry(property);
      return None;
    }
    return Some(shipped);
  }
  errors.push(attribute::named(property, router_shape(field)));
  None
}

/// WHAT A WALKED `route(…)` ENTRY SETTLED TO, and the two absences that are checked only where they
/// could honestly be claimed.
///
/// The absences are spanned at the WORD rather than at the field, on the measure entry's own
/// reasoning: what is missing is missing from this block, so the caret belongs on the block's own
/// name. The refusals that are about a STEP — two words on one field, a second segment, an order —
/// are spanned at the field, because their fix is to move or delete a step rather than to fill a
/// block in.
fn settled(
  written: RouteForm,
  at: &syn::Path,
  field: &syn::Ident,
  errors: &mut Errors,
) -> Option<Fan> {
  if written.refused {
    return None;
  }
  if !written.router_spoken {
    errors.push(syn::Error::new_spanned(at, route_names_no_router(field)));
  }
  if !written.slot_spoken {
    errors.push(syn::Error::new_spanned(at, route_names_no_slot(field)));
  }
  Some(Fan::Route {
    router: written.router?,
    slot: written.slot?,
  })
}

/// The words a `route(…)` entry takes, for a near-miss list — read off the table and nowhere else.
fn property_words() -> Vec<&'static str> {
  ROUTE_PROPERTIES.iter().map(|known| known.word).collect()
}

/// The words a `route(…)` entry takes, as a sentence prints them.
fn property_roster() -> String {
  ROUTE_PROPERTIES
    .iter()
    .map(|known| format!("`{}`", known.word))
    .collect::<Vec<_>>()
    .join(" and ")
}

/// **THE STAGE ORDER AND THE ONE-PER-KIND LAWS** — the rules no single step can see.
///
/// Both are about the tower rather than about a step, so they are checked where the roster is whole.
/// The order walk reads the FIRST step of each stage only: a kind already refused for being written
/// twice must not also earn an ordering sentence about its second occurrence, which would be one
/// mistake reported as two.
fn segments(steps: &[StepModel], errors: &mut Errors) {
  let mut opened: Vec<(Stage, &syn::Ident)> = Vec::new();
  for step in steps {
    let Some(stage) = step.stage() else {
      continue;
    };
    if let Some((_, first)) = opened.iter().find(|(seen, _)| *seen == stage) {
      errors.push(syn::Error::new_spanned(
        &step.field,
        one_segment_per_kind(stage, first),
      ));
      continue;
    }
    opened.push((stage, &step.field));
  }

  // THE ORDER, as a monotonic walk rather than a pair of arms: `Stage` is `Ord` by the pipeline's
  // own order, so the stage the closed design records before ② arrives as one variant and this
  // check does not move. The pair is in DECLARATION order and the comparison is in STAGE order,
  // which is the whole of what the rule says.
  for pair in opened.windows(2) {
    let [(first, at_first), (second, at_second)] = pair else {
      continue;
    };
    if second < first {
      errors.push(syn::Error::new_spanned(
        at_first,
        out_of_order(*first, at_first, *second, at_second),
      ));
    }
  }
}

/// The refusal `route = <router>` earns — the sugar that has nowhere to put the wiring's other half.
fn route_has_no_sugar(field: &syn::Ident) -> String {
  format!(
    "`{ROUTE}` names TWO things and has no short spelling — write `{ROUTE}({ROUTER} = …, {SLOT} = \
     \"path::to::Slot\")` on `{field}`. What makes a mis-wiring a compile error at the seat rather \
     than a conversion somewhere in the middle is the EQUALITY between what the router answers and \
     what one lane of the slot is asked with, and a form that names the router alone holds one half \
     of it"
  )
}

/// The refusal a bare or empty `route` earns.
fn route_names_its_properties(field: &syn::Ident) -> String {
  format!(
    "`{ROUTE}` names no property — write `{ROUTE}({ROUTER} = …, {SLOT} = \"path::to::Slot\")` on \
     `{field}`. It opens the segment where this question CROSSES into one probe per lane, and both \
     halves of that crossing are named here: WHO chooses the lanes, and WHOSE lanes they are"
  )
}

/// The refusal a second `route` on one step earns.
fn route_twice(field: &syn::Ident) -> String {
  format!(
    "`{ROUTE}` is declared more than once on `{field}` — one step opens one crossing, and a second \
     lane fan is a second step"
  )
}

/// The refusal an entry that named no router earns.
fn route_names_no_router(field: &syn::Ident) -> String {
  format!(
    "`{ROUTE}(…)` on `{field}` names no `{ROUTER}` — write `{ROUTER} = {shipped}` for one this \
     framework ships, or `{ROUTER} = \"path::to::Router\"` for the declaring crate's. The word \
     decides WHO cuts a question into lanes, and a crossing with nothing to make that choice with \
     would have to ask an arbitrary one",
    shipped = Router::SHIPPED[2],
  )
}

/// The refusal an entry that named no slot earns.
fn route_names_no_slot(field: &syn::Ident) -> String {
  format!(
    "`{ROUTE}(…)` on `{field}` names no `{SLOT}` — write `{SLOT} = \"path::to::Slot\"`. A slot is \
     the `(elected field × engine)` pairing a declaration's own expansion minted, and it is what \
     states the currency ONE LANE is asked in: without it the router's answer is checked against \
     nothing"
  )
}

/// The refusal a property written twice inside one `route(…)` earns.
fn property_once(word: &str, field: &syn::Ident) -> String {
  format!(
    "`{word}` is declared more than once in `{ROUTE}(…)` on `{field}` — one crossing has one of \
     each"
  )
}

/// The refusal a property this entry does not know earns.
fn unknown_route_property(field: &syn::Ident) -> String {
  format!(
    "unknown property in `{ROUTE}(…)` on `{field}` — the FULL FORM names the crossing's {roster} \
     and nothing else: `{ROUTE}({ROUTER} = …, {SLOT} = \"path::to::Slot\")`. How DEEP a lane is \
     read and what its score is floored at are the recipe's words, and what a lane is leaned on by \
     is the tower's own options",
    roster = property_roster(),
  )
}

/// The refusal a `router` whose value is neither a bare word nor a quoted path earns.
fn router_shape(field: &syn::Ident) -> String {
  format!(
    "`{ROUTER}` on `{field}` is a shipped router's BARE word or the declaring crate's own QUOTED \
     path — `{ROUTER} = {shipped}`, or `{ROUTER} = \"path::to::Router\"`. It carries nothing else: \
     what a router is built from is the slot's own roster, which the declaration already names",
    shipped = Router::SHIPPED[2],
  )
}

/// The refusal a bare word that is no shipped router earns — MINT BARE, REFER QUOTED.
fn unshipped_router(word: &syn::Ident) -> String {
  format!(
    "`{word}` is not a router this framework ships. The bare words are {roster}; every other router \
     there is arrives QUOTED — `{ROUTER} = \"path::to::Router\"` — because a bare word is a promise \
     this crate can write the whole binding, which it can keep only for a type it ships",
    roster = Router::SHIPPED
      .iter()
      .map(|word| format!("`{word}`"))
      .collect::<Vec<_>>()
      .join(", "),
  )
}

/// The refusal a quoted `router` that is not a path earns.
const ROUTER_IS_A_PATH: &str = "`router = \"path::to::Router\"` names the type that cuts a question into lanes. It is QUOTED \
   because it refers to a type this declaration did not mint, which is the law `expand` and the \
   recipe's own `tower` word are written under; whether that type IS a lane router, and whether \
   what it answers meets the slot's probe currency, are rustc's at the seat the expansion writes";

/// The refusal a `slot` that is not a quoted path earns.
const SLOT_IS_A_QUOTED_PATH: &str = "`slot = \"path::to::Slot\"` names the slot whose lanes this crossing asks. It is QUOTED for \
   `router`'s reason — the word names a type this declaration did not mint — and what a router \
   wired to it must answer in is that slot's own `LanedStore::Probe`, checked where the compiler \
   resolves both";

/// The refusal a step wearing MORE THAN ONE segment word earns, naming the ones it wrote.
fn one_segment_per_step(field: &syn::Ident, written: &[&str]) -> String {
  let words = written
    .iter()
    .map(|word| format!("`{word}`"))
    .collect::<Vec<_>>()
    .join(" and ");
  format!(
    "`{field}` writes {words}, and a step opens ONE segment. `{ANNOTATE}` is where a question is \
     ENRICHED in place, `{EXPAND}` is where it WIDENS and `{ROUTE}` is where it CROSSES into probes \
     — stages of one pipeline rather than facts about one hop, and writing them on separate steps \
     is exactly how their order is stated"
  )
}

/// The refusal a SECOND segment of one kind earns, naming the step that already opened it.
fn one_segment_per_kind(stage: Stage, first: &syn::Ident) -> String {
  let why = match stage {
    Stage::Annotate => {
      "a tower annotates ONE question: the stage fills the seat only where the caller left it \
       empty, so a second stage over that seat would run exactly where the first did not — which \
       is nowhere"
    }
    Stage::Expand => {
      "a tower widens ONE question: the fold takes the original and its widenings as one family, \
       and a second widening would be a family the dedup and the arm weights have no law for"
    }
    Stage::Route => {
      "a tower has ONE lane fan: the weights compose one lane emphasis with one arm weight, and a \
       second crossing would be probes in a second currency with no fold defined over them"
    }
  };
  format!(
    "`{word}` is already open at `{first}`, and {why}",
    word = stage.word()
  )
}

/// ⟂ The refusal an `answer` word beside `{ANNOTATE}` earns.
fn annotation_answers_itself(field: &syn::Ident) -> String {
  format!(
    "`answer` decides nothing on `{field}`, which opens the ANNOTATION stage — a step that \
     annotates hands back the question it was given, so both of its ends are the type the chain \
     already arrived at and there is no seat here for a word to fill. Take it off: what `{ANNOTATE}` \
     names is the ANNOTATION's type, which is what the stage writes rather than what the step \
     answers"
  )
}

/// The refusal a LATER stage written before an earlier one earns, naming both steps.
///
/// The two words AND the reason come off [`Stage`] rather than out of this sentence, which is what
/// let the third stage arrive as one variant and not a case here. The reason belongs to the stage
/// that was written LATE — a widening is early because of what a WIDENING is, an annotation is
/// early because of what stages downstream READ — so the table has one row per stage rather than
/// one per pair.
fn out_of_order(
  later: Stage,
  at_later: &syn::Ident,
  earlier: Stage,
  at_earlier: &syn::Ident,
) -> String {
  format!(
    "`{later_word}` on `{at_later}` comes before `{earlier_word}` on `{at_earlier}`, and the \
     pipeline's stages run the other way round: {why}. Move the step; the order is not corrected \
     here, because a tower's fields ARE its walk and a pass that reordered one would be rewriting \
     the chain its author wrote",
    later_word = later.word(),
    earlier_word = earlier.word(),
    why = earlier.why_first(),
  )
}

/// What a WORD THAT NAMES ONE TYPE says when it is written wrongly — the whole of what
/// distinguishes the positions, [`one_type`] being the whole of how they are read.
///
/// Four sentences and no fifth, because there are exactly four ways to get such a word wrong: name
/// no type, name something that is not one, name one twice, or write a word the block does not take.
/// A position that cannot answer all four has not decided what its grammar is.
struct OneType {
  /// The refusal the word written bare, as an empty block, or as a block with no `type` earns.
  empty: &'static str,
  /// The refusal a value that is not a quoted type earns.
  ty: &'static str,
  /// The refusal a SECOND one earns, in either spelling.
  twice: &'static str,
  /// The refusal an unknown entry INSIDE the block earns, naming what the block is for.
  inner: &'static str,
}

/// WHAT THE WHOLE TOWER IS ASKED — omissible, and the first step's canonical question when omitted.
const QUESTION: OneType = OneType {
  empty: "`question` names no type — write `question(type = \"path::to::Question\")`, or `question \
          = \"path::to::Question\"` for the sugar",
  ty: "`question` names the TYPE the whole tower is asked — quoted, because the word names a type \
       this declaration cannot resolve and the compiler resolves where the expansion lands",
  twice: "`question` is declared more than once — one tower is asked one type, and the full form \
          and the sugar fill the same seat",
  inner: "unknown entry in `question(…)` — it names the TYPE the whole tower is asked and nothing \
          else. What each step answers is the word beside that step",
};

/// **THE HEAD PIN** — what the tower's chain must ARRIVE at, and the one word here that decides
/// nothing.
///
/// A tower answers what its LAST STEP answers, so this word cannot make it answer anything: what it
/// writes down is an INTENT, and the expansion demands that the derivation agree with it. Its
/// sentences say so, because a word read as an override would be a word an author expects to WIN —
/// and the whole content of this one is that it does not decide, it CHECKS.
const ANSWER: OneType = OneType {
  empty: "`answer` names no type — write `answer = \"path::to::Answer\"`, or `answer(type = \
          \"path::to::Answer\")` for the full form. OMIT it where the tower's answer is simply \
          whatever its last step arrives at",
  ty: "`answer` names the TYPE the whole tower is pinned to answer — quoted, because the word names \
       a type this declaration cannot resolve and the compiler resolves where the expansion lands",
  twice: "`answer` is declared more than once at the tower — one tower answers one type, and the \
          full form and the sugar fill the same seat",
  inner: "unknown entry in `answer(…)` — it names the TYPE this tower's chain must arrive at and \
          nothing else. The word DECIDES nothing: a tower answers what its last step answers, and \
          this is the intent that derivation is checked against",
};

/// The refusal a STEP's `answer` whose value is not a quoted type earns.
///
/// Named for its position, because the word is spelled the same at the tower — where [`ANSWER`]'s
/// own sentences answer for it — and the two say genuinely different things: this one DECIDES what a
/// step gives back, and the head's only claims what the chain arrives at.
const STEP_ANSWER_TYPE: &str = "`answer` names the TYPE this step answers — quoted, because the word names a type this \
   declaration cannot resolve and the compiler resolves where the expansion lands";

/// The refusal an `async` carrying anything earns.
const ASYNC_BARE: &str = "`async` is a bare word here — it names the FACE this step's hop demands, and the step's body \
   is its own author's, so there is nothing to configure";

/// The refusal a tower with no field earns.
const EMPTY_TOWER: &str = "a tower declares no step — its FIELDS are its steps, so one with none has no chain to state \
   and no answer to name";

/// The refusal a tuple struct earns.
const POSITIONAL_STEPS: &str = "a tower must be a struct with NAMED fields — a field's name is the step's name, which is one \
   name serving the steps struct, the tower's options and the schema row alike, and a positional \
   field has none of them";