Skip to main content

ingraph_codegen/
graph.rs

1//! The GRAPH ROOT: what a struct whose fields are an application's nodes expands into.
2//!
3//! ```ignore
4//! #[ingraph::graph]
5//! pub struct Media {
6//!   videos: Video,
7//!   scenes: Scene,
8//! }
9//! ```
10//!
11//! # The root IS the registry, and that is the whole of the inversion
12//!
13//! The reference implementation pairs its walk with a per-entity back-pointer: an entity names the
14//! graph it belongs to, and a visitor written for one graph cannot be handed another's entity. That
15//! wall is bought with a bounded slot on every entity's binding, and it is what a REGISTRY needs — a
16//! type has to say which list it is on.
17//!
18//! Here the list is written once, by hand, in the field order somebody chose. No node registers
19//! itself anywhere, nothing on the entity binding points back, and there is no second list a type
20//! could be borrowed from. What this half emits is that list, turned into a walk.
21//!
22//! # Three items, and each is INHERENT
23//!
24//! `type_iter` cannot be a trait method, and the reason is the mechanism the walk's own bound rests
25//! on: an impl may not ADD a where clause to a trait method (`E0276`), and this walk's body has one
26//! predicate per field to discharge. So the emission is an inherent impl, which is also what the
27//! ruling asks for — `Media::init(db)`, on the root, with the handle as a parameter.
28//!
29//! `init` and `validate` ride the SQL family's gate. Their signatures name the schema lane's own
30//! types and `sqlx`'s, so they exist per family rather than per declaration; `type_iter` names
31//! neither and is emitted unconditionally, which is what keeps the walk the single authority whether
32//! or not a build carries a database.
33//!
34//! # The RESOURCES are on the same list, and that is one namespace
35//!
36//! A field marked `#[ingraph(resource)]` is not a node: it is a shared citizen the launch builds
37//! once and hands to whoever demanded it. It rides the SAME field list because the root is the
38//! deployment's whole catalog — so the two kinds are told apart by the attribute and never by a
39//! second declaration. What that buys is Rust's own refusal for a collision between them, and one
40//! place to read a deployment's members off. [`crate::catalog`] holds their half: the document block
41//! they are grouped under, and the walk that declares them.
42//!
43//! # And the INTERFACES, which are the THIRD tier of that one list
44//!
45//! A field marked `#[ingraph(interface)]` names an interface — a contract over members rather than a
46//! member. It is not a node and it is not a resource: it owns no table for the storage walk to
47//! describe, nothing for the create pass to build, and no options section for a document to fill. So
48//! it is a list of its own ([`InterfaceMount`]), read off the same fields, and the three walks a node
49//! joins never see it.
50//!
51//! What it DOES join is the root query, under the same `#[ingraph(query)]` word a node's membership
52//! is written with — see [`query`](self::query) for the projection, which is one hop shorter than a
53//! node's because an interface implements no `Transformer`.
54//!
55//! # And the ORIGINS, which are the FIFTH tier and the only one that is a HEAD
56//!
57//! A field marked `#[ingraph(origin)]` names an `#[ingraph::source]` declaration — a body that is
58//! STARTED ONCE and runs until it is spent, told to stop or dead, rather than one called per item.
59//! It is not a node: it declares no upstream, owns no table, mints no id and answers no query, so it
60//! joins neither the storage walk nor the root query nor the create pass's own predicate set.
61//!
62//! What it DOES have is one out-edge, and that edge IS its feed — the consumer names the origin by
63//! type in its own `subscribe(…)`, the join finds it among these very fields, and the launch hands
64//! the origin the consumer's inbox rather than pumping items into it. So the tier's whole emission
65//! is the options section (presence is enablement, as everywhere) and five lines of the launch. See
66//! [`OriginMount`] and [`crate::launch`].
67//!
68//! # The OPTIONS SPINE rides along, and it is not an entry
69//!
70//! Beside those three the root gets `<Root>Options` — one section per declared node and one
71//! `resources` block beside them, which is how a deployment says which of the catalog it launches
72//! and what it builds its shared citizens with. It is a TYPE rather than an entry and it is
73//! written in [`crate::options`], where its own note carries the whole of why: presence is
74//! enablement, the mount name is the document's key, and the framework reads no file.
75//!
76//! # And the TWO WORDS that put a DURABLE thing on the root
77//!
78//! `retired(<engine>)` names where this deployment's retirees are written down — see
79//! [`RetiredLedger`]. It is on the root rather than on a member because a retirement is a fact about
80//! a ROOT KEY: no member's declaration could carry it, and the ledger is one per deployment. What it
81//! grows is a `[retired]` section and a `RETIRED_ENGINE` const on the spine, both in
82//! [`crate::options`].
83//!
84//! `generations(<engine>)` is its sibling and names where this deployment's current pointers are
85//! written down — see [`GenerationsSeat`]. It is on the root for the same reason and a second one: a
86//! run closes over a ROOT KEY, and the pointer table is one per deployment. What it grows is a
87//! `[generations]` section and a `GENERATIONS_ENGINE` const, in the same place.
88//!
89//! They are the only two entries on a root that name a store, and they are two entries rather than
90//! one because a deployment may write either without the other: retirement is a fact about which
91//! keys are OUT, and a generation is a fact about which run a key's closure is READ at.
92//!
93//! # And the ENTRY that spends it
94//!
95//! `<Root>::launch` is the fourth item, written in [`crate::launch`]: the ruled start-up sequence
96//! walked once — validate, create, wire, ignite — with the node pass emitted in full and the steps
97//! that name types this derive cannot see arriving as parameters. `<Root>Nodes` rides with it, the
98//! create walk's product read off the same list of mounts.
99//!
100//! # Handles are PARAMETERS
101//!
102//! The root owns no context. `init` and `validate` take the connection they run on, so a graph is
103//! a description of what exists and never a holder of what it is stored in — the injection seam, and
104//! the reason neither emitted entry has a receiver.
105//!
106//! # The ROOT QUERY, folded from the members that have one
107//!
108//! `<Root>Query` is the fifth item, written in [`query`](self::query): a `MergedObject` over the
109//! query UNIT each marked member emits, reached by projection rather than by name. It is the one
110//! emitted item here that is CONDITIONAL on a word — see that module for why membership is read off
111//! this declaration and nowhere else.
112//!
113//! # What it does NOT emit, and what that is not a gap
114//!
115//! No subscribe audit: what a member subscribes to is written in the member's own declaration, which
116//! this derive cannot see — the three-author wall — so subscribe-completeness is an assembly check
117//! and is named as one rather than half-attempted here.
118
119use quote::quote;
120
121use crate::{catalog::ResourceField, engine::EngineBinding};
122
123mod query;
124
125#[cfg(test)]
126mod tests;
127
128/// A validated ingraph root, ready to emit.
129///
130/// Plain public fields, for the reason every model in this crate has them: the front ends that build
131/// one — the derive today, a compiler from a manifest later — reach the same emitter without either
132/// of them being this crate's concern.
133#[derive(Debug, Clone)]
134pub struct GraphModel {
135  /// Where `ingraph` lives, as the declaration named it or `::ingraph` by default.
136  pub krate: syn::Path,
137  /// The root's own visibility — what the emitted entries take, so a private ingraph's walk stays
138  /// private rather than leaking into its crate's public API.
139  pub vis: syn::Visibility,
140  /// The root type.
141  pub name: syn::Ident,
142  /// The NODES, in the order the declaration's fields were written.
143  pub nodes: Vec<syn::Type>,
144  /// The field NAMES, in that same order.
145  ///
146  /// The query surface's mount names, and the wire round is what will spend them as that. What
147  /// spends them TODAY is [`mounts`](Self::mounts): the walk reads a field's TYPE and never its
148  /// value, so without one read somewhere every graph root would carry a `dead_code` warning per
149  /// node — a lint about a member the framework declared and has not paid for yet.
150  pub mounts: Vec<syn::Ident>,
151  /// The nodes whose ROOT FIELDS join the graph's query, in the order the declaration wrote them —
152  /// a SUBSET of [`nodes`](Self::nodes), read off the `#[ingraph(query)]` word.
153  ///
154  /// A second list rather than a flag beside each node, because the two are spent by two emissions:
155  /// the walk visits every node and the fold projects only these. Empty is the ordinary state of a
156  /// graph that serves no schema, and it is what makes the whole query emission conditional —
157  /// see [`query`](Self::query).
158  pub queried: Vec<syn::Type>,
159  /// The INTERFACES this root declares, in the order the declaration's fields were written.
160  ///
161  /// A THIRD list beside the nodes and the resources, and the tier word is what puts a field on it.
162  /// An interface owns no table, mints no id and has no options section, so it joins none of the
163  /// three walks a node joins — the storage description, the create pass, the options spine — and a
164  /// list of its own is what states that rather than three exclusions restating it.
165  ///
166  /// Empty is the ordinary state. What reads it is [`mounts`](Self::mounts), for the `dead_code`
167  /// reason every mount is read, and [`query`](Self::query), which projects the ones that wrote the
168  /// mount word.
169  pub interfaces: Vec<InterfaceMount>,
170  /// The RESOURCES, in the order the declaration's fields were written.
171  ///
172  /// A separate list from the nodes because the two are spent differently — a node is built from
173  /// its own section and wired, a resource is built once and handed out — and one namespace because
174  /// they are one struct's fields. See [`crate::catalog`].
175  pub resources: Vec<ResourceField>,
176  /// The RETRIEVING members this root mounts, in the order the declaration wrote them — read off
177  /// the `fuse` word.
178  ///
179  /// # A FOURTH TIER, and that is forced rather than chosen
180  ///
181  /// A fused member is a RETRIEVING DECLARATION — a `#[ingraph::vector(…)]` or
182  /// `#[ingraph::fulltext(…)]` one — and those are not launchable nodes: they implement neither
183  /// `Declared` nor `AsyncConstructor`, so a field naming one on the NODE tier is `E0277` at the root
184  /// before anything about fusion is reached. An index owns no `Creation::node`, has no options
185  /// section, and nothing about it is the storage-description walk's.
186  ///
187  /// So `fuse` is a TIER WORD, exactly as `interface` and `resource` are, and it is what keeps a
188  /// retrieving member off the three walks a node joins. That is now the WHOLE of what it says: the
189  /// modality trims it used to carry retired with the doors they trimmed.
190  ///
191  /// What the list is SPENT on is the slot walk and the launch — the two places a retrieving member
192  /// differs from a node — and the destructuring that reads every mount. The FUSED DOORS it used to
193  /// mint are `#[ingraph::search]`'s now, one recipe at a time: see `crate::search::fuse`, which
194  /// carries the migration note. Empty is the ordinary state of a root that mounts no index.
195  ///
196  /// # THE WORD IS A BARE LAYER NOW, AND IT IS RECORDED RATHER THAN SWEPT
197  ///
198  /// Everything `fuse` decided has left it: the trims, the typed doors, the packages, the evidence
199  /// enums and — on 2026-08-19 — the two modality markers the trims used to demand. What is left is
200  /// *this field is on the retrieving tier*, which is a fact the INDEX LAYER already knows about
201  /// itself: a `#[ingraph::vector(…)]` declaration implements neither `Declared` nor
202  /// `AsyncConstructor`, so the tier is derivable from the type rather than declared beside it.
203  ///
204  /// The word is NOT retired in this round, and the reason is that the successor is not built.
205  /// Deriving the tier means the root reading a trait bound off each member's type, which is the
206  /// index-layer re-expression `crate::search` is heading toward; retiring the word before that
207  /// exists would take a working declaration away and give nothing back. So it stays, carrying one
208  /// bit, and the DEBT is written here rather than left as a shape a reader has to notice:
209  ///
210  /// **when the index layer can state its own tier, `fuse` goes whole — the word, this list, the
211  /// `FusedMember` type and the reader in `ingraph_derive::graph::resource`.** Not narrowed, not
212  /// defaulted: a word that carries one derivable bit is a word with nothing left to say.
213  pub fused: Vec<FusedMember>,
214  /// The ORIGINS this root mounts, in the order the declaration wrote them — read off the `origin`
215  /// word.
216  ///
217  /// # A FIFTH TIER, and it is forced by the same wall the fourth was
218  ///
219  /// An origin is an `#[ingraph::source]` declaration, and those are not launchable NODES: they
220  /// implement [`DeclaredOrigin`] rather than `Declared`, so a field naming one on the node tier is
221  /// `E0277` at the root before anything about a feed is reached. An origin owns no table for the
222  /// storage walk to describe, mints no id, answers no query and declares no upstream — what it has
223  /// instead is ONE OUT-EDGE, and that edge IS its feed.
224  ///
225  /// So the two walks it joins are the two a node's own membership is spent on and no others: the
226  /// OPTIONS SPINE (presence is enablement, exactly as a node's section is) and the LAUNCH, which
227  /// declares it as a head, builds it from its section, opens its one edge and puts it on an engine.
228  /// The storage walk, the slot walk, the resource catalog and the root query each skip it by
229  /// construction rather than by exclusion — there is nothing about an origin for any of them to
230  /// read.
231  ///
232  /// Empty is the ordinary state of a root that mounts no origin, and it is what makes every one of
233  /// this tier's emissions disappear rather than loop over no members.
234  ///
235  /// [`DeclaredOrigin`]: ../../ingraph/trait.DeclaredOrigin.html
236  pub origins: Vec<OriginMount>,
237  /// The ENGINE WORDS this root binds, in the order they were written — `engines(hnsw =
238  /// "app::hnsw::Hnsw")`.
239  ///
240  /// EMPTY is the ordinary state, and it does not mean *no engines*: a deployment whose declarations
241  /// name only SHIPPED words binds nothing here, a shipped word self-binding under its own feature.
242  /// What this list holds is the third-party half — the open vocabulary's other end.
243  ///
244  /// It is on the ROOT rather than on a declaration for [`EngineBinding`]'s reason: a word on a field
245  /// is a NAME, and a name is bound where the program is assembled.
246  pub engines: Vec<EngineBinding>,
247  /// The RETIRED LEDGER this root declares, or [`None`] where it declared none.
248  ///
249  /// One per root and never a list: a deployment's retirees live in ONE place, the ledger being the
250  /// truth about which root keys are out rather than a per-family choice. What varies per family is
251  /// the TABLE — `__ig_retired_<family>` — and that is minted at run time off the family's own
252  /// name, families being opened rather than declared.
253  ///
254  /// `None` is the ordinary state, and it is a graph with no durable retirement at all: the registry
255  /// still runs, a retirement still moves a key's state, and nothing is written down. See
256  /// [`crate::options`] for the section this grows, and `ingraph::drive::retired` for what it means
257  /// at run time.
258  pub retired: Option<RetiredLedger>,
259  /// The GENERATIONS SEAT this root declares, or [`None`] where it declared none.
260  ///
261  /// [`retired`](Self::retired)'s sibling one field over, and one per root for its reason: a
262  /// deployment's current pointers live in ONE place, the pointer table being the truth about which
263  /// generation each closure is reading rather than a per-family choice. What varies per family is
264  /// the TABLE — `__ig_current_<family>` — and that is minted at run time off the family's own name,
265  /// families being opened rather than declared.
266  ///
267  /// `None` is the ordinary state, and it is a graph with no generational discipline at all: the
268  /// registry still closes runs, a run still earns a flip, and nothing is written down. See
269  /// [`crate::options`] for the section this grows, and `ingraph::drive::generations` for what it
270  /// means at run time.
271  pub generations: Option<GenerationsSeat>,
272}
273
274/// The `retired(<engine>)` word a root wrote — which engine its retirement rows live on.
275///
276/// The ENGINE and nothing else: where on that engine is a deployment's `[retired]` section, and the
277/// table's name is the family's. See `ingraph::drive::RetiredOptions`, where the division is argued.
278#[derive(Debug, Clone)]
279pub struct RetiredLedger {
280  /// The engine the word named — one of the four the framework builds unaided.
281  pub engine: crate::model::DatabaseKind,
282}
283
284/// The `generations(<engine>)` word a root wrote — which engine its current pointers live on.
285///
286/// The ENGINE and nothing else: where on that engine, and how deep the history goes, are a
287/// deployment's `[generations]` section. See `ingraph::GenerationsOptions`, where the division is
288/// argued.
289#[derive(Debug, Clone)]
290pub struct GenerationsSeat {
291  /// The engine the word named — one of the three the framework builds unaided.
292  pub engine: crate::model::DatabaseKind,
293}
294
295/// ONE RETRIEVING MEMBER of a graph root: the field that names it, and its type.
296///
297/// # The MODALITY seat is retired, and so is everything the word used to decide
298///
299/// The `fuse` word carried a modality — bare, `fuse(vector)`, `fuse(fulltext)` — because a root
300/// MINTED its own fused doors and the trims chose which of them a member joined. Those doors moved
301/// to `#[ingraph::search]`, where a recipe LISTS its members, so there is no door for a trim to
302/// select and no count for a law to read. What is left is the TIER: the word says this member is a
303/// retrieving declaration rather than a launchable node, which is what keeps it off the storage
304/// walk, off the create pass and off the options spine, and on the slot walk and the launch.
305#[derive(Debug, Clone)]
306pub struct FusedMember {
307  /// The field's name — the seat this member takes in the root's own destructuring.
308  pub mount: syn::Ident,
309  /// The member's type, as the field spelled it.
310  pub ty: syn::Type,
311  /// Whether the field wrote `#[ingraph(query)]` — the ROOT QUERY-SURFACE gap this seat closes.
312  ///
313  /// A retrieving declaration MINTS a query unit (`<Decl>Queries`) and binds it at
314  /// [`Graphql::Query`](crate::model::…), exactly as an interface does — and until this seat existed
315  /// nothing folded it: the root's `MergedObject` projected nodes and interfaces, and a member on
316  /// the index tier wrote the mount word to no effect. So a declaration could publish a whole
317  /// answer family that no emitted schema could reach.
318  ///
319  /// One `bool` beside the type rather than a fourth list, on [`InterfaceMount::queried`]'s own
320  /// reason: a retrieving member joins exactly ONE walk here, so the fact and the field it is about
321  /// are one value.
322  pub queried: bool,
323}
324
325/// ONE ORIGIN on a graph root: the field that names it, and its type.
326///
327/// TWO fields where the other two tier structs carry three, and the missing one is the `query` word:
328/// an origin publishes no root field and there is no fold for it to join, so the word is refused on
329/// this tier rather than carried and ignored. What an origin's membership is spent on is the options
330/// spine and the launch, and both read the pair below.
331#[derive(Debug, Clone)]
332pub struct OriginMount {
333  /// The field's name — the mount this origin is declared, sectioned and reported under.
334  pub mount: syn::Ident,
335  /// The origin's type, as the field spelled it.
336  pub ty: syn::Type,
337}
338
339/// ONE interface on a graph root: the field that names it, and whether this deployment publishes its
340/// root fields.
341///
342/// A struct rather than the two parallel lists a node's mount and membership are kept in, and the
343/// reason is that the node pair is spent by two DIFFERENT walks — every node is walked, only the
344/// marked ones are folded — where an interface joins exactly one. So the fact and the field it is
345/// about are one value.
346#[derive(Debug, Clone)]
347pub struct InterfaceMount {
348  /// The field's name — read once so a declaration carries no `dead_code` warning for it.
349  pub mount: syn::Ident,
350  /// The interface's type, as the field spelled it.
351  pub ty: syn::Type,
352  /// Whether the field wrote `#[ingraph(query)]` — presence is the enablement, so an interface that
353  /// did not write it publishes no root field.
354  pub queried: bool,
355}
356
357impl GraphModel {
358  /// The walk, the two entries that drive it, the one line that reads the fields, the resource
359  /// catalog, and the options spine a deployment configures the root through.
360  #[must_use]
361  pub fn emit(&self) -> proc_macro2::TokenStream {
362    let walk = self.walk();
363    let slot_walk = self.slot_walk();
364    let entries = self.entries();
365    let mounts = self.mounts();
366    let catalog = self.catalog().emit();
367    let options = self.options().emit();
368    let launch = self.launch().emit();
369    let query = self.query();
370    let bindings = self.bindings();
371    quote! {
372      #walk
373      #slot_walk
374      #entries
375      #mounts
376      #catalog
377      #options
378      #launch
379      #query
380      #bindings
381    }
382  }
383
384  /// The ENGINE MEMBER TABLE: one marker type per bound word, carrying the concrete engine.
385  ///
386  /// # It is a TYPE-LEVEL table, and that is the whole choice
387  ///
388  /// A field names its engines by WORD and this is where a word becomes a TYPE. A runtime map from
389  /// string to engine would have been simpler and is the thing being refused: a member resolved by
390  /// name at run time is a member no signature can be written against, and what the fused face needs
391  /// is exactly a signature — *which engines does this query fan across* is a question about types.
392  ///
393  /// # At MODULE SCOPE, and public to the root's own visibility
394  ///
395  /// A binding is NAMED by whoever reads the table, so it goes where the root's other emitted items
396  /// go and carries the root's visibility. A private root's bindings stay private, for the reason
397  /// every emitted item mirrors its declaration's visibility: no one can widen a type they did not
398  /// declare.
399  ///
400  /// # Nothing here is GATED
401  ///
402  /// A bound word names a type the DECLARING crate wrote, so no feature of the framework's decides
403  /// whether it exists. The gate is the shipped half's — a word `ingraph` itself ships is bound by
404  /// `ingraph`, under its own feature, and never appears in this table at all.
405  fn bindings(&self) -> proc_macro2::TokenStream {
406    let GraphModel {
407      krate, vis, name, ..
408    } = self;
409    let bound = crate::emit::framework(krate, &["store"], "Bound");
410    let rows = self.engines.iter().map(|binding| {
411      let marker = binding.marker(name);
412      let engine = &binding.engine;
413      let word = binding.word.to_string();
414      let doc = crate::emit::leading(&format!(
415        "The engine word `{word}`, as [`{name}`] bound it — one row of this root's compile-time \
416         engine table. A field that names `{word}` is written to this type.",
417      ));
418      quote! {
419        #[doc = #doc]
420        #[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
421        #vis struct #marker;
422
423        #[automatically_derived]
424        impl #bound for #marker {
425          type Engine = #engine;
426
427          const WORD: &'static ::core::primitive::str = #word;
428        }
429      }
430    });
431    quote!(#(#rows)*)
432  }
433
434  /// This root's RESOURCE CATALOG — see [`crate::catalog`] for the block it emits and the walk it
435  /// declares them through.
436  ///
437  /// A borrow of the same list the other two borrow, for the same reason.
438  #[must_use]
439  pub fn catalog(&self) -> crate::catalog::Catalog<'_> {
440    crate::catalog::Catalog {
441      krate: &self.krate,
442      vis: &self.vis,
443      root: &self.name,
444      resources: &self.resources,
445    }
446  }
447
448  /// This root's LAUNCH ENTRY — see [`crate::launch`] for the sequence it walks and the three
449  /// things it has to be handed.
450  ///
451  /// A borrow of the same list [`options`](Self::options) borrows, for the same reason.
452  #[must_use]
453  pub fn launch(&self) -> crate::launch::LaunchEntry<'_> {
454    crate::launch::LaunchEntry {
455      krate: &self.krate,
456      vis: &self.vis,
457      root: &self.name,
458      nodes: &self.nodes,
459      mounts: &self.mounts,
460      resources: &self.resources,
461      fused: &self.fused,
462      origins: &self.origins,
463    }
464  }
465
466  /// This root's OPTIONS SPINE — see [`crate::options`] for the whole of what it emits and why.
467  ///
468  /// A borrow of the list this model already holds, rather than a second copy of it.
469  #[must_use]
470  pub fn options(&self) -> crate::options::OptionsSpine<'_> {
471    crate::options::OptionsSpine {
472      krate: &self.krate,
473      vis: &self.vis,
474      root: &self.name,
475      nodes: &self.nodes,
476      mounts: &self.mounts,
477      resources: &self.resources,
478      origins: &self.origins,
479      retired: self.retired.as_ref(),
480      generations: self.generations.as_ref(),
481    }
482  }
483
484  /// The FIELDS, read once, so a declaration carries no `dead_code` warning for them.
485  ///
486  /// A graph root's fields are its list and its mount names. The walk spends their TYPES and the
487  /// wire round will spend their NAMES; neither reads a VALUE, so rustc reports every field of every
488  /// ingraph as never read — a lint a declaration would have to silence for a member the framework
489  /// asked it to write. Resources are read here too, and for the same reason: a resource field is
490  /// never read either, its value living in the launch's context rather than in the root.
491  ///
492  /// A DESTRUCTURING and not a field access, because that is what counts as a read whatever else the
493  /// pattern's own function is: the binding is the use. It sits inside an anonymous `const`, where it
494  /// collides with nothing anybody wrote, and it is `#[allow(dead_code)]` so the reader is not
495  /// replaced by a warning about itself.
496  fn mounts(&self) -> proc_macro2::TokenStream {
497    let name = &self.name;
498    // EVERY field, all five tiers: the destructuring is a pattern, so a member left out of it is
499    // not a reader that skipped one but a pattern that does not match the struct.
500    let mounts: Vec<&syn::Ident> = self
501      .mounts
502      .iter()
503      .chain(self.interfaces.iter().map(|interface| &interface.mount))
504      .chain(self.fused.iter().map(|member| &member.mount))
505      .chain(self.origins.iter().map(|origin| &origin.mount))
506      .chain(self.resources.iter().map(|resource| &resource.mount))
507      .collect();
508    quote! {
509      const _: () = {
510        #[allow(dead_code)]
511        fn __ig_mounts(root: &#name) {
512          let #name { #(#mounts,)* } = root;
513          #(let _ = #mounts;)*
514        }
515      };
516    }
517  }
518
519  /// `Media::type_iter` — one `next_type` per field, with one predicate per field for the caller to
520  /// discharge.
521  ///
522  /// The predicates are what make the walk's bound mean something at the ROOT: a field whose type
523  /// describes no storage in the visitor's database is `E0277` here, naming the field's type and the
524  /// database, rather than inside whichever visitor reached it first.
525  fn walk(&self) -> proc_macro2::TokenStream {
526    let krate = &self.krate;
527    let vis = &self.vis;
528    let name = &self.name;
529    let nodes = &self.nodes;
530    quote! {
531      impl #name {
532        /// Apply `visitor` to every node this graph declares, in the order its fields are
533        /// written.
534        ///
535        /// # Errors
536        ///
537        /// The first node the visitor refuses, with the nodes after it left unvisited.
538        #vis fn type_iter<__IgVisitor>(
539          visitor: &mut __IgVisitor,
540        ) -> ::core::result::Result<(), <__IgVisitor as #krate::__private::transform::TypeVisitor>::Error>
541        where
542          __IgVisitor: #krate::__private::transform::TypeVisitor,
543          #(
544            #nodes: #krate::__private::schema::Describe<
545              <__IgVisitor as #krate::__private::transform::TypeVisitor>::Db,
546            >,
547          )*
548        {
549          #(
550            #krate::__private::transform::TypeVisitor::next_type::<#nodes>(visitor)?;
551          )*
552          ::core::result::Result::Ok(())
553        }
554      }
555    }
556  }
557
558  /// `Media::type_iter_for` and `Media::type_iter_for_async` — the walk over the SLOT-BEARING tier,
559  /// once per FACE.
560  ///
561  /// # A SECOND list, because it is a second question
562  ///
563  /// [`walk`](Self::walk) lists the NODES, and a node's home is a table: what drives it is a DDL
564  /// visitor over a SQL dialect. This lists the FUSED members — the `#[ingraph::vector(…)]` and
565  /// `#[ingraph::fulltext(…)]` declarations whose elections own corpora — and what drives it is a
566  /// SLOT MAKER over a resource. Two tiers, two habitats, two walks; folding them would make every
567  /// visitor prove a `Describe` for members its target has no home for.
568  ///
569  /// # `_for`, because the TARGET is what it is FOR
570  ///
571  /// The visitor names its own [`Db`], so a call says which target this walk is being made for
572  /// without a second parameter — and the predicates say the rest: a member with no home in that
573  /// target is `E0277` HERE, at the root's own field list, which is where it can be fixed.
574  ///
575  /// # BOTH FACES are emitted, always
576  ///
577  /// The completeness law's own precondition: a deployment may mount a blocking target and an
578  /// awaited one at once, so the root has to be walkable by either kind of visitor and the pair is
579  /// emitted whether or not this build mounts both. Neither is conditional on a word.
580  ///
581  /// # What the LAUNCH drives, and why it is not this
582  ///
583  /// An emitted launch drives layer two per DECLARATION (`Habitats::make`), because which targets a
584  /// declaration's legs point at is written in the declaration and not in this list — see
585  /// `ingraph`'s `drive::habitats`, where the measurement is. These two are the HAND door: the walk
586  /// a deployment drives itself when it holds one target every member lives in, and the shape a
587  /// third-party initializer is written against.
588  ///
589  /// [`Db`]: ../../ingraph/trait.TypeVisitor.html#associatedtype.Db
590  fn slot_walk(&self) -> proc_macro2::TokenStream {
591    let krate = &self.krate;
592    let vis = &self.vis;
593    let name = &self.name;
594    let members: Vec<&syn::Type> = self.fused.iter().map(|member| &member.ty).collect();
595    quote! {
596      impl #name {
597        /// Apply `visitor` to every SLOT-BEARING member this graph declares, in the order its
598        /// fields are written — the BLOCKING face.
599        ///
600        /// # Errors
601        ///
602        /// The first member the visitor refused, with the members after it left unvisited.
603        #vis fn type_iter_for<__IgVisitor>(
604          visitor: &mut __IgVisitor,
605        ) -> ::core::result::Result<(), <__IgVisitor as #krate::__private::transform::TypeVisitor>::Error>
606        where
607          __IgVisitor: #krate::__private::transform::TypeVisitor,
608          #(
609            #members: #krate::__private::schema::Describe<
610              <__IgVisitor as #krate::__private::transform::TypeVisitor>::Db,
611            >,
612          )*
613        {
614          #(
615            #krate::__private::transform::TypeVisitor::next_type::<#members>(visitor)?;
616          )*
617          ::core::result::Result::Ok(())
618        }
619
620        /// [`type_iter_for`](Self::type_iter_for) on the AWAITED face — the walk a target whose
621        /// creates answer with a future is made by.
622        ///
623        /// # Errors
624        ///
625        /// The first member the visitor refused, with the members after it left unvisited.
626        #vis async fn type_iter_for_async<__IgVisitor>(
627          visitor: &mut __IgVisitor,
628        ) -> ::core::result::Result<(), <__IgVisitor as #krate::__private::transform::AsyncTypeVisitor>::Error>
629        where
630          __IgVisitor: #krate::__private::transform::AsyncTypeVisitor,
631          #(
632            #members: #krate::__private::schema::Describe<
633              <__IgVisitor as #krate::__private::transform::AsyncTypeVisitor>::Db,
634            >,
635          )*
636        {
637          #(
638            #krate::__private::transform::AsyncTypeVisitor::next_type::<#members>(visitor).await?;
639          )*
640          ::core::result::Result::Ok(())
641        }
642      }
643    }
644  }
645
646  /// `Media::init` and `Media::validate`, inside the SQL family's gate.
647  ///
648  /// Both are the same three lines — build the visitor, drive the walk, spend what it collected —
649  /// and both carry the same where clause: the dialect, and one storage description per field. The
650  /// driver predicates a statement and a decode need are NOT here, because
651  /// [`AsyncSchemaDialect`](../../ingraph/query/sql/trait.AsyncSchemaDialect.html) carries its own I/O, which
652  /// is what keeps this emission from restating four bounds it does not spend.
653  fn entries(&self) -> proc_macro2::TokenStream {
654    let krate = &self.krate;
655    let vis = &self.vis;
656    let name = &self.name;
657    let nodes = &self.nodes;
658    quote! {
659      #krate::__private::gate::if_sqlx! {
660        impl #name {
661          /// Create every table, index and edge table this graph declares, on `conn`.
662          ///
663          /// The whole schema RENDERS before any of it executes, so a graph with one node this
664          /// dialect cannot describe creates nothing rather than half of itself. It is safe to
665          /// re-run: every statement carries `IF NOT EXISTS`.
666          ///
667          /// # Errors
668          ///
669          /// A descriptor this dialect will not render, or the driver's own refusal.
670          #vis async fn init<__IgDb>(
671            conn: &mut <__IgDb as #krate::__private::sqlx::Database>::Connection,
672          ) -> ::core::result::Result<(), #krate::__private::query::sql::SqlSchemaError>
673          where
674            __IgDb: #krate::__private::query::sql::AsyncSchemaDialect,
675            #(#nodes: #krate::__private::schema::Describe<__IgDb>,)*
676          {
677            let mut visitor = #krate::__private::query::sql::Create::<__IgDb>::new();
678            Self::type_iter(&mut visitor)?;
679            visitor.run(conn).await
680          }
681
682          /// Audit what `conn` actually stores against what this graph declares.
683          ///
684          /// # Errors
685          ///
686          /// The first drift — a table this database does not have, a declared column it does not
687          /// carry, or a column stored at a type the declaration does not name — and the driver's
688          /// own refusal for a probe that would not run.
689          #vis async fn validate<__IgDb>(
690            conn: &mut <__IgDb as #krate::__private::sqlx::Database>::Connection,
691          ) -> ::core::result::Result<(), #krate::__private::query::sql::SqlSchemaError>
692          where
693            __IgDb: #krate::__private::query::sql::AsyncSchemaDialect,
694            #(#nodes: #krate::__private::schema::Describe<__IgDb>,)*
695          {
696            let mut visitor = #krate::__private::query::sql::Validate::<__IgDb>::new();
697            Self::type_iter(&mut visitor)?;
698            visitor.audit(conn).await
699          }
700        }
701      }
702    }
703  }
704}