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}