ingraph-codegen 0.1.0

The emission engine behind ingraph-derive: a plain declaration model in, the ingraph framework faces out.
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
//! The OPTIONS SPINE: what a graph root's own name becomes when a deployment configures it.
//!
//! ```ignore
//! #[ingraph::graph]
//! pub struct Media {
//!   videos: Video,
//!   scenes: Scene,
//! }
//! ```
//!
//! emits, beside the walk, a typed `MediaOptions` — one field per DECLARED node, named by the mount
//! the declaration wrote, holding that node's own [`AsyncConstructor::Options`] under a section:
//!
//! ```ignore
//! pub struct MediaOptions {
//!   pub(crate) videos: Option<NodeSection<<Video as AsyncConstructor>::Options>>,
//!   pub(crate) scenes: Option<NodeSection<<Scene as AsyncConstructor>::Options>>,
//! }
//! ```
//!
//! # PRESENCE IS ENABLEMENT, and that is what the `Option` is
//!
//! An application DECLARES a catalog and a deployment LAUNCHES a subset, so a node with no section
//! is a node that does not start. The sleeping catalog costs no boilerplate and a node added in code
//! runs nowhere until somebody names it — which is the design rather than a hazard. Every field is
//! `serde(default)`, so a document naming three of thirty nodes parses and the other twenty-seven
//! are absent rather than malformed.
//!
//! It is the ONLY enablement axis. A section carries no switch to hold a written node back, because
//! a configuration file is an immutable artifact: a deployment that wants a node off points at a
//! different file rather than toggling this one.
//!
//! # The RESOURCES ride under ONE key
//!
//! A root's `#[ingraph(resource)]` fields are on the same list as its nodes, and the document groups
//! them: the spine grows one `resources` field holding a `<Root>Resources` block, so a deployment
//! writes `[resources.egemma]` rather than a section at the top level. That is what makes
//! `resources` a reserved mount — a node named `resources` would be a second meaning for the same
//! key, and the derive refuses one. [`crate::catalog`] emits the block; this emits the field that
//! holds it, and only where the root declares a resource that has a section at all.
//!
//! # The REGISTRY seat is the SECOND reserved key, and it is on EVERY root
//!
//! Beside `resources` the spine grows one `registry` field, holding [`RegistryOptions`] — the
//! deployment-wide timing the root-key registry runs under: `[registry]`'s own defaults, and
//! whatever families it named their own words for under `[registry.<family>]`. Unlike `resources`
//! it is on every root whether or not one is declared for, because there is no per-root marker that
//! would make it conditional — every graph gets the registry's defaults, whether or not anything
//! reads them yet. `registry` is therefore RESERVED the same way `resources` is: a member mounted
//! there would be a second meaning for the key, and the derive refuses one by name.
//!
//! # The RETIRED seat is the THIRD reserved key, and it is CONDITIONAL
//!
//! A root that wrote `retired(<engine>)` grows one `retired` field, holding [`RetiredOptions`] — the
//! connection its retirement ledger is opened on. Unlike `registry` it is conditional, and the
//! difference is what a ledger IS: the registry runs on every root whether or not a document tunes
//! it, while a root that declared no ledger has no engine, no connection and no table, so a
//! `[retired]` section on it would be a document key naming nothing. The NAME is reserved
//! unconditionally all the same, on `resources`' own posture — a member called `retired` would have
//! to be renamed the day its root declares a ledger.
//!
//! Beside the field the spine grows one associated `const`, `RETIRED_ENGINE`, which is the word's
//! own answer carried across to whatever builds the store. It is a `const` rather than a field
//! because an engine is not a thing a document may say: it decides what the program COMPILES, and a
//! document is read after the program is built.
//!
//! # The GENERATIONS seat is the FOURTH, on exactly that shape
//!
//! A root that wrote `generations(<engine>)` grows one `generations` field holding
//! [`GenerationsOptions`] — the connection its current pointers are opened on, and how many
//! generations a closure keeps — plus one `GENERATIONS_ENGINE` const beside it. Everything the
//! `retired` seat's two paragraphs argue holds here word for word: conditional FIELD, unconditional
//! NAME, and the engine as a `const` because a document is read after the program is built.
//!
//! [`GenerationsOptions`]: ../../ingraph/struct.GenerationsOptions.html
//!
//! # The BRIDGE to the launch floor
//!
//! Beside the accessors, the spine emits one `enablement()` — the deployment's sections read into
//! the launch layer's own `Enablement`, one call per DECLARED mount. That is the whole of how a
//! document reaches the validate walk: the walk asks about node NAMES, the spine's fields ARE those
//! names, and a field left `None` is the node this deployment does not launch.
//!
//! # ONE schema, and no second document to keep in step
//!
//! The field NAMES are the mount names, so a section's key is the same word the declaration wrote —
//! there is no map from string to node to maintain, and a rename moves both ends at once.
//! `deny_unknown_fields` is what turns a typo into a refusal naming the field, at deserialization,
//! where the reader is looking at the file. What a section CONTAINS is the node author's own options
//! type reached through the trait, so the deployment's schema is the sum of the authors' schemas and
//! this emitter invents no part of it.
//!
//! # The framework does NO file I/O
//!
//! What is emitted is a plain `serde::Deserialize` type. Which format a deployment writes, how many
//! layers it merges, where the file lives and what an environment variable overrides are all the
//! APPLICATION's business — this crate hands it a type and reads nothing.
//!
//! # Two lanes, because a derive is an attribute
//!
//! The spine exists in every build: a hand-built options value is how a programmatic deployment
//! states what it runs, and the launch entry's signature names the type whatever a build compiled.
//! Only the DERIVE is conditional — an attribute cannot be added by a macro that expands to nothing
//! — so the declaration is written twice, once inside each half of the `serde` gate, and the gate
//! slurps tokens rather than parsing them, exactly as the four backend gates do.

use proc_macro2::TokenStream;
use quote::{format_ident, quote};

use crate::{
  catalog::{Catalog, ResourceField, default_resources_name},
  emit::{framework, leading, vendored},
  graph::{GenerationsSeat, OriginMount, RetiredLedger},
};

#[cfg(test)]
mod origin_tests;
#[cfg(test)]
mod tests;

/// The mount name the registry seat is emitted under, which no member may take.
///
/// [`crate::catalog::RESERVED_MOUNT`]'s sibling and reserved for the same reason one level up: the
/// spine's `registry` field is graph-level rather than grouped under any node's own section, so a
/// member of that name would be a second meaning for the key the seat already owns.
pub const RESERVED_REGISTRY_MOUNT: &str = "registry";

/// The mount name the RETIRED LEDGER's section is emitted under, which no member may take.
///
/// [`RESERVED_REGISTRY_MOUNT`]'s sibling, one seat over. Unlike that one the FIELD is conditional —
/// only a root that wrote `retired(<engine>)` grows it — and the RESERVATION is not: a member named
/// `retired` on a root that has no ledger today would have to be renamed the day it declares one, so
/// the word is held for the seat whether or not the seat is occupied. That is the same posture
/// `resources` takes, whose field is conditional on a root declaring one and whose name is refused
/// unconditionally.
pub const RESERVED_RETIRED_MOUNT: &str = "retired";

/// The mount name the GENERATIONS SEAT's section is emitted under, which no member may take.
///
/// [`RESERVED_RETIRED_MOUNT`]'s sibling, and held on exactly its terms: the FIELD is conditional on
/// a root writing `generations(<engine>)` and the RESERVATION is not, because a member named
/// `generations` on a root that has no seat today would have to be renamed the day it declares one.
pub const RESERVED_GENERATIONS_MOUNT: &str = "generations";

/// `<Root>Options` — the name a root's own spine takes.
///
/// Derived from the USER's root type, so a deployment writes `MediaOptions` for a `Media`: the
/// framework's own vocabulary moved off `universe`, and the emitted global still reads off whatever
/// the declaration called itself.
#[must_use]
pub fn default_options_name(root: &syn::Ident) -> syn::Ident {
  format_ident!("{root}Options")
}

/// One ingraph root's options spine, ready to emit.
///
/// It borrows rather than owning, because what it needs is what the root model already holds — the
/// list and the mount names, in one order — and a second copy of that list is a second thing to keep
/// in step.
#[derive(Debug, Clone, Copy)]
pub struct OptionsSpine<'a> {
  /// Where `ingraph` lives, as the declaration named it.
  pub krate: &'a syn::Path,
  /// The root's own visibility — what the spine and its accessors take.
  pub vis: &'a syn::Visibility,
  /// The root type, whose name the spine derives its own from.
  pub root: &'a syn::Ident,
  /// The NODES, in declaration order.
  pub nodes: &'a [syn::Type],
  /// The mount NAMES beside them, in that same order — the spine's fields, and a document's keys.
  pub mounts: &'a [syn::Ident],
  /// The RESOURCES, in declaration order — what the spine's one `resources` field groups.
  pub resources: &'a [ResourceField],
  /// The ORIGINS, in declaration order — one section apiece, beside the nodes and under no block.
  ///
  /// AT THE TOP LEVEL rather than grouped, which is the difference between this tier and the
  /// resources: a resource is DEMAND-SCANNED (nothing is enabled by naming one), and an origin is
  /// ENABLED BY PRESENCE exactly as a node is. So an origin's section says the same thing a node's
  /// says in the same place, and a document writes `[watch]` beside `[discover]` rather than
  /// `[origins.watch]` — the reader is told which members run by one flat list.
  pub origins: &'a [OriginMount],
  /// The RETIRED LEDGER this root declared, or [`None`] where it declared none — what makes the
  /// `retired` field and its accessors conditional.
  pub retired: Option<&'a RetiredLedger>,
  /// The GENERATIONS SEAT this root declared, or [`None`] where it declared none — what makes the
  /// `generations` field and its accessors conditional, on [`retired`](Self::retired)'s own terms.
  pub generations: Option<&'a GenerationsSeat>,
}

impl OptionsSpine<'_> {
  /// The spine, once inside each half of the `serde` gate — see the module note for why twice.
  #[must_use]
  pub fn emit(&self) -> TokenStream {
    let krate = self.krate;
    let deserialized = self.declaration(true);
    let plain = self.declaration(false);
    let methods = self.methods();
    let debug = self.debug();
    let if_serde = quote!(#krate::__private::gate::if_serde);
    let if_no_serde = quote!(#krate::__private::gate::if_no_serde);
    quote! {
      #if_serde ! { #deserialized }
      #if_no_serde ! { #plain }
      #methods
      #debug
    }
  }

  /// The struct itself, with serde's derive and words where this build has serde.
  fn declaration(&self, deserialized: bool) -> TokenStream {
    let vis = self.vis;
    let root = self.root;
    let name = default_options_name(root);
    let section = framework(self.krate, &["drive"], "NodeSection");
    let constructor = framework(self.krate, &["drive"], "AsyncConstructor");
    let declared = framework(self.krate, &["drive"], "Declared");
    // The ORIGIN tier's projection: an origin's options are its own face's, reached through the mode
    // row. A node's come through `AsyncConstructor`, which is the resident construction door and not
    // an origin's — see `launch::LaunchEntry::origin_predicate` for the round that separated them.
    let tuned = framework(self.krate, &["drive"], "Tuned");

    let fields = self.mounts.iter().zip(self.nodes).map(|(mount, node)| {
      let doc = leading(&format!(
        "What this deployment runs `{mount}` with — `None` being the node it does not \
         start.\n\nThe field NAME is the mount name, so a document's key is the word the \
         declaration wrote."
      ));
      let default = deserialized.then(|| quote!(#[serde(default)]));
      quote! {
        #[doc = #doc]
        #default
        pub(crate) #mount: ::core::option::Option<
          #section<<#node as #constructor>::Options, <#node as #declared>::Channels>
        >,
      }
    });
    let origins = self.origins.iter().map(|origin| {
      let (mount, ty) = (&origin.mount, &origin.ty);
      let doc = leading(&format!(
        "What this deployment runs the ORIGIN `{mount}` with — `None` being the origin it does not \
         start.\n\nA node's section verbatim, one tier over, and there is no `channels` block \
         under it: an origin declares no upstream, so it has no inbound edge for a shelf to tune. \
         Its ONE out-edge is the CONSUMER's, and it is tuned in the consumer's own section."
      ));
      let default = deserialized.then(|| quote!(#[serde(default)]));
      quote! {
        #[doc = #doc]
        #default
        pub(crate) #mount: ::core::option::Option<#section<#tuned<#ty>>>,
      }
    });
    let resources = self.resources_field(deserialized);
    let registry = self.registry_field(deserialized);
    let retired = self.retired_field(deserialized);
    let generations = self.generations_field(deserialized);

    let derives = if deserialized {
      let deserialize = framework(self.krate, &["serde"], "Deserialize");
      let serde = vendored(self.krate, "serde");
      quote! {
        #[derive(::core::default::Default, #deserialize)]
        #[serde(crate = #serde, deny_unknown_fields)]
      }
    } else {
      quote!(#[derive(::core::default::Default)])
    };

    let doc = leading(&format!(
      "What ONE DEPLOYMENT of [`{root}`] runs — one section per declared node, absent for the ones \
       it does not start.\n\nPresence is enablement: a node with no section here is a node that \
       never launches, so an application may declare a catalog and a deployment may take a subset \
       of it without either writing anything about the other, and a section that IS written is a \
       node that runs — presence being the only axis there is.\n\nIt \
       reads no file. Which format states this, how many layers merge into it and where they live \
       are the application's questions; the framework's answer is a type."
    ));
    quote! {
      #[doc = #doc]
      #derives
      #vis struct #name {
        #(#fields)*
        #(#origins)*
        #resources
        #registry
        #retired
        #generations
      }
    }
  }

  /// The `resources` field, where the root declares a document-sourced resource at all.
  ///
  /// It is a BLOCK rather than one field per resource, which is the ruled grouping: struct-flat,
  /// document-nested, so a deployment writes `[resources.egemma]` and every shared citizen's section
  /// is under one roof. That grouping is also what reserves the word — a member mounted at
  /// `resources` would be a second meaning for the key, and the derive refuses one by name.
  ///
  /// Held BY VALUE and not optionally: the block's own fields are what say which resources this
  /// deployment configured, and a document that writes no `resources` at all is every one of them
  /// absent — which is the same statement one nesting level down. Nothing is enabled or disabled by
  /// it, resources being demand-scanned rather than named.
  fn resources_field(&self, deserialized: bool) -> TokenStream {
    if !self.catalog().has_block() {
      return TokenStream::new();
    }
    let block = default_resources_name(self.root);
    let doc = leading(
      "What this deployment builds its shared RESOURCES with — one section per document-sourced \
       resource, under the reserved `resources` key.\n\nEvery section in it is optional and an \
       absent one is that resource at its options' own `Default`, so a deployment that tunes none \
       of them writes no `resources` block at all.",
    );
    let default = deserialized.then(|| quote!(#[serde(default)]));
    quote! {
      #[doc = #doc]
      #default
      pub(crate) resources: #block,
    }
  }

  /// The `registry` field — ON EVERY ROOT, unlike [`resources_field`](Self::resources_field): there
  /// is no per-root marker that would make the seat conditional, so every spine carries the registry's
  /// own defaults whether or not this deployment tunes them.
  fn registry_field(&self, deserialized: bool) -> TokenStream {
    let registry = framework(self.krate, &["drive"], "RegistryOptions");
    let doc = leading(
      "What this deployment tunes the root-key REGISTRY with — `[registry]`'s own defaults, and \
       whatever families it named their own words for under `[registry.<family>]`.\n\nEvery knob \
       has a shipped default, so a document naming none of them still parses.",
    );
    let default = deserialized.then(|| quote!(#[serde(default)]));
    quote! {
      #[doc = #doc]
      #default
      pub(crate) registry: #registry,
    }
  }

  /// The `retired` field — ONLY where the root wrote `retired(<engine>)`, which is the difference
  /// between this seat and [`registry_field`](Self::registry_field).
  ///
  /// The registry runs on every root whether or not a document tunes it, so its options are there to
  /// be defaulted. A LEDGER is not like that: a root that declared none has no engine, no connection
  /// and no table, so a `[retired]` section on it would be a document key naming nothing — which
  /// `deny_unknown_fields` then refuses, telling the reader the truth.
  ///
  /// Held BY VALUE, on [`resources_field`](Self::resources_field)'s own reasoning: an absent
  /// section is every knob at its default, which is the same statement one nesting level down.
  fn retired_field(&self, deserialized: bool) -> TokenStream {
    if self.retired.is_none() {
      return TokenStream::new();
    }
    let options = framework(self.krate, &["drive"], "RetiredOptions");
    let doc = leading(
      "Where this deployment keeps its RETIRED LEDGER — the `[retired]` section.\n\nThe ENGINE is \
       the declaration's (`retired(<engine>)`); this is where on that engine. A document that names \
       no connection is a deployment wiring its own store in code.",
    );
    let default = deserialized.then(|| quote!(#[serde(default)]));
    quote! {
      #[doc = #doc]
      #default
      pub(crate) retired: #options,
    }
  }

  /// The `retired` accessors and the ENGINE the word named, as a `const`.
  ///
  /// The const is what carries the declaration's own decision across to a launch: a deployment
  /// reads `<Root>Options::RETIRED_ENGINE` and builds the store the word asked for. It is an
  /// associated `const` rather than a field because it is not a thing a document may say — an engine
  /// decides what the program COMPILES, and a document is read after the program is built.
  fn retired_methods(&self) -> TokenStream {
    let Some(ledger) = self.retired else {
      return TokenStream::new();
    };
    let vis = self.vis;
    let options = framework(self.krate, &["drive"], "RetiredOptions");
    let engine = self.retired_engine(ledger);
    let engine_doc = leading(
      "WHICH ENGINE this root's retired ledger runs on — the `retired(<engine>)` word, as a \
       value.\n\nA deployment reads it to build the store: the word is the application's decision \
       and `[retired].dsn` is the deployment's.",
    );
    let with_doc = leading(
      "Keep the retired ledger at `retired` — the door a deployment states in code rather than in a \
       document.",
    );
    let borrow_doc = leading("Where this deployment keeps its retired ledger.");
    quote! {
      #[doc = #engine_doc]
      #vis const RETIRED_ENGINE: #engine;

      #[doc = #with_doc]
      #[inline]
      #[must_use]
      #vis fn with_retired(mut self, retired: #options) -> Self {
        self.retired = retired;
        self
      }

      #[doc = #borrow_doc]
      #[inline]
      #[must_use]
      #vis const fn retired(&self) -> &#options {
        &self.retired
      }
    }
  }

  /// The `const`'s TYPE AND ITS VALUE — `RetiredEngine = RetiredEngine::<Arm>`, for the arm
  /// `ledger`'s word named.
  ///
  /// It is the one place the codegen's own database vocabulary crosses into the runtime's engine
  /// word, so the crossing is [`DatabaseKind::retired_arm`](crate::model::DatabaseKind::retired_arm)
  /// and never a spelling written twice.
  ///
  /// The ledger arrives as an ARGUMENT rather than off `self`, so there is no arm to default to
  /// where a root declared none: the one caller has already established that it did.
  fn retired_engine(&self, ledger: &RetiredLedger) -> TokenStream {
    let ty = framework(self.krate, &["drive"], "RetiredEngine");
    let arm = format_ident!("{arm}", arm = ledger.engine.retired_arm());
    quote!(#ty = #ty::#arm)
  }

  /// The `generations` field — ONLY where the root wrote `generations(<engine>)`, on
  /// [`retired_field`](Self::retired_field)'s own terms and for its reason: a root that declared no
  /// seat has no engine, no connection and no pointer table, so a `[generations]` section on it
  /// would be a document key naming nothing, which `deny_unknown_fields` then refuses.
  fn generations_field(&self, deserialized: bool) -> TokenStream {
    if self.generations.is_none() {
      return TokenStream::new();
    }
    let options = framework(self.krate, &["drive"], "GenerationsOptions");
    let doc = leading(
      "Where this deployment keeps its CURRENT POINTERS, and how deep its history goes — the \
       `[generations]` section.\n\nThe ENGINE is the declaration's (`generations(<engine>)`); this \
       is where on that engine, and how many generations a closure keeps (`keep`, one by default).",
    );
    let default = deserialized.then(|| quote!(#[serde(default)]));
    quote! {
      #[doc = #doc]
      #default
      pub(crate) generations: #options,
    }
  }

  /// The `generations` accessors and the ENGINE the word named, as a `const` —
  /// [`retired_methods`](Self::retired_methods)'s shape, one seat over.
  fn generations_methods(&self) -> TokenStream {
    let Some(seat) = self.generations else {
      return TokenStream::new();
    };
    let vis = self.vis;
    let options = framework(self.krate, &["drive"], "GenerationsOptions");
    let engine = self.generations_engine(seat);
    let engine_doc = leading(
      "WHICH ENGINE this root's current pointers run on — the `generations(<engine>)` word, as a \
       value.\n\nA deployment reads it to build the store: the word is the application's decision \
       and `[generations].dsn` is the deployment's.",
    );
    let with_doc = leading(
      "Keep the generations seat at `generations` — the door a deployment states in code rather \
       than in a document.",
    );
    let borrow_doc =
      leading("Where this deployment keeps its current pointers, and how deep its history goes.");
    quote! {
      #[doc = #engine_doc]
      #vis const GENERATIONS_ENGINE: #engine;

      #[doc = #with_doc]
      #[inline]
      #[must_use]
      #vis fn with_generations(mut self, generations: #options) -> Self {
        self.generations = generations;
        self
      }

      #[doc = #borrow_doc]
      #[inline]
      #[must_use]
      #vis const fn generations(&self) -> &#options {
        &self.generations
      }
    }
  }

  /// The `const`'s TYPE AND ITS VALUE — `GenerationsEngine = GenerationsEngine::<Arm>`, for the arm
  /// `seat`'s word named.
  ///
  /// [`retired_engine`](Self::retired_engine)'s twin, crossing through
  /// [`DatabaseKind::generations_arm`](crate::model::DatabaseKind::generations_arm) so the arm is
  /// the runtime enum's own spelling and never one written twice.
  ///
  /// That crossing is PARTIAL where the other is total, and the empty answer is its totality rather
  /// than a case: the derive refuses `generations(mongo)` by name, so a spine is only ever built
  /// over a word the runtime enum has. Spelling the fallback keeps a fourth engine added to one enum
  /// and not the other a MISSING `const` at the declaration rather than a path that does not exist.
  fn generations_engine(&self, seat: &GenerationsSeat) -> TokenStream {
    let ty = framework(self.krate, &["drive"], "GenerationsEngine");
    let Some(arm) = seat.engine.generations_arm() else {
      return TokenStream::new();
    };
    let arm = format_ident!("{arm}");
    quote!(#ty = #ty::#arm)
  }

  /// The catalog half of the same list — see [`crate::catalog`].
  fn catalog(&self) -> Catalog<'_> {
    Catalog {
      krate: self.krate,
      vis: self.vis,
      root: self.root,
      resources: self.resources,
    }
  }

  /// The `resources` accessors, where the block exists.
  ///
  /// A borrow and a builder, exactly as a node's section has: a deployment assembling its options in
  /// code says `with_resources(…)`, and a reader asks the value what it holds.
  fn resource_methods(&self) -> TokenStream {
    if !self.catalog().has_block() {
      return TokenStream::new();
    }
    let vis = self.vis;
    let block = default_resources_name(self.root);
    let with_doc = leading(
      "Build this deployment's shared resources from `resources` — the door a deployment states in \
       code rather than in a document.",
    );
    let borrow_doc = leading("What this deployment builds its shared resources with.");
    quote! {
      #[doc = #with_doc]
      #[inline]
      #[must_use]
      #vis fn with_resources(mut self, resources: #block) -> Self {
        self.resources = resources;
        self
      }

      #[doc = #borrow_doc]
      #[inline]
      #[must_use]
      #vis const fn resources(&self) -> &#block {
        &self.resources
      }
    }
  }

  /// The accessor family: `Default` plus one `with_<mount>` and one borrow per node.
  ///
  /// The shape an emitted arguments type already has one crate over — construction is the default
  /// plus one builder per member — and it is ungated, the two declarations above being the same
  /// struct under two attribute sets.
  fn methods(&self) -> TokenStream {
    let vis = self.vis;
    let name = default_options_name(self.root);
    let section = framework(self.krate, &["drive"], "NodeSection");
    let constructor = framework(self.krate, &["drive"], "AsyncConstructor");
    let declared = framework(self.krate, &["drive"], "Declared");
    let tuned = framework(self.krate, &["drive"], "Tuned");

    let methods = self.mounts.iter().zip(self.nodes).map(|(mount, node)| {
      let with = format_ident!("with_{mount}");
      let held = quote!(#section<<#node as #constructor>::Options, <#node as #declared>::Channels>);
      let with_doc = leading(&format!(
        "Launch `{mount}`, under `section` — the door a deployment states in code rather than in a \
         document."
      ));
      let borrow_doc = leading(&format!(
        "What `{mount}` is to be launched with, or `None` where this deployment does not start it."
      ));
      quote! {
        #[doc = #with_doc]
        #[inline]
        #[must_use]
        #vis fn #with(mut self, section: #held) -> Self {
          self.#mount = ::core::option::Option::Some(section);
          self
        }

        #[doc = #borrow_doc]
        #[inline]
        #[must_use]
        #vis fn #mount(&self) -> ::core::option::Option<&#held> {
          self.#mount.as_ref()
        }
      }
    });

    let origins = self.origins.iter().map(|origin| {
      let (mount, ty) = (&origin.mount, &origin.ty);
      let with = format_ident!("with_{mount}");
      let held = quote!(#section<#tuned<#ty>>);
      let with_doc = leading(&format!(
        "Mount the origin `{mount}`, under `section` — the door a deployment states in code rather \
         than in a document."
      ));
      let borrow_doc = leading(&format!(
        "What the origin `{mount}` is to be mounted with, or `None` where this deployment does not \
         start it."
      ));
      quote! {
        #[doc = #with_doc]
        #[inline]
        #[must_use]
        #vis fn #with(mut self, section: #held) -> Self {
          self.#mount = ::core::option::Option::Some(section);
          self
        }

        #[doc = #borrow_doc]
        #[inline]
        #[must_use]
        #vis fn #mount(&self) -> ::core::option::Option<&#held> {
          self.#mount.as_ref()
        }
      }
    });

    let enablement = self.enablement();
    let resources = self.resource_methods();
    let registry = self.registry_methods();
    let retired = self.retired_methods();
    let generations = self.generations_methods();
    quote! {
      impl #name {
        #(#methods)*

        #(#origins)*

        #resources

        #registry

        #retired

        #generations

        #enablement
      }
    }
  }

  /// The `registry` accessors: a borrow and a builder, exactly as [`resource_methods`](Self::resource_methods)
  /// has — a deployment assembling its options in code says `with_registry(…)`, and a reader asks
  /// the value what it holds.
  fn registry_methods(&self) -> TokenStream {
    let vis = self.vis;
    let registry = framework(self.krate, &["drive"], "RegistryOptions");
    let with_doc = leading(
      "Tune the root-key registry with `registry` — the door a deployment states in code rather \
       than in a document.",
    );
    let borrow_doc = leading("What this deployment tunes the root-key registry with.");
    quote! {
      #[doc = #with_doc]
      #[inline]
      #[must_use]
      #vis fn with_registry(mut self, registry: #registry) -> Self {
        self.registry = registry;
        self
      }

      #[doc = #borrow_doc]
      #[inline]
      #[must_use]
      #vis const fn registry(&self) -> &#registry {
        &self.registry
      }
    }
  }

  /// The BRIDGE: which nodes these options launch, in the launch floor's own word.
  ///
  /// One [`Enablement::mounted`] call per DECLARED mount — not per section the document carried —
  /// so the walk that reads it is told about every node the root declares, including the ones this
  /// deployment said nothing about. That is what makes the absence readable: a mount whose field is
  /// `None` states a node that does not launch, and a mount nobody could name at all does not
  /// exist, the fields being the vocabulary.
  ///
  /// It is a CHAIN and not a fold with an accumulator, which keeps the emitted body free of a
  /// `mut` binding a zero-node root would leave unused.
  fn enablement(&self) -> TokenStream {
    let vis = self.vis;
    let enablement = framework(self.krate, &["drive"], "Enablement");
    let root = self.root;
    // BOTH TIERS, and under one call each: a mount is a mount to the launch floor, which asks about
    // NAMES and never about which door declared one. An origin's absence therefore starves its
    // consumer exactly as an unmounted node's does, and its presence is what makes it a head the
    // validate walk has to check the out-edge of.
    let sections = self
      .mounts
      .iter()
      .chain(self.origins.iter().map(|origin| &origin.mount))
      .map(|mount| {
        let key = mount.to_string();
        quote!(.mounted(#key, ::core::option::Option::as_ref(&self.#mount)))
      });
    let doc = leading(&format!(
      "Which members this deployment of [`{root}`] launches — its nodes and its origins.\n\nPresence \
       is enablement, and it is the only axis: a mount this document named launches, and a mount it \
       did not name is not started at all. This is what the launch walk's checks are asked about — \
       an upstream nothing named starves a channel listener, and the refusal names the section to \
       write."
    ));
    quote! {
      #[doc = #doc]
      #[must_use]
      #vis fn enablement(&self) -> #enablement {
        #enablement::new() #(#sections)*
      }
    }
  }

  /// A `Debug` reporting each node's PRESENCE, and never the options themselves.
  ///
  /// Written rather than derived, and that is the same trade `Shared` and the launch context make:
  /// a node's options are the author's type, and deriving here would put a `Debug` bound on every
  /// one of them for the benefit of this line. What a reader of a start-up log actually wants is
  /// which nodes this deployment launches, which is exactly what the presence of each section says
  /// — `false` for a node nothing named, `true` for one that runs.
  fn debug(&self) -> TokenStream {
    let name = default_options_name(self.root);
    let fields = self
      .mounts
      .iter()
      .chain(self.origins.iter().map(|origin| &origin.mount))
      .map(|mount| {
        let key = mount.to_string();
        quote! {
          .field(#key, &::core::option::Option::is_some(&self.#mount))
        }
      });
    // The block's own `Debug` is the same trade one level down — which resources this deployment
    // wrote a section for, never what is in one.
    let resources = self
      .catalog()
      .has_block()
      .then(|| quote!(.field("resources", &self.resources)));
    // The LEDGER's own `Debug` where there is one, on the registry's reasoning below: it is the
    // framework's type, so printing it whole costs no bound anybody else pays.
    let retired = self
      .retired
      .is_some()
      .then(|| quote!(.field("retired", &self.retired)));
    // The GENERATIONS SEAT's, on the same reasoning and under the same condition.
    let generations = self
      .generations
      .is_some()
      .then(|| quote!(.field("generations", &self.generations)));
    // The registry's OWN `Debug`, and not presence-only: unlike a node's options, which are the
    // author's own type and would bound every one of them for one log line, `RegistryOptions` is the
    // framework's, so printing it whole costs nothing new.
    quote! {
      impl ::core::fmt::Debug for #name {
        fn fmt(&self, f: &mut ::core::fmt::Formatter<'_>) -> ::core::fmt::Result {
          f.debug_struct(::core::stringify!(#name))
            #(#fields)*
            #resources
            .field("registry", &self.registry)
            #retired
            #generations
            .finish()
        }
      }
    }
  }
}