Skip to main content

ingraph_codegen/search/
fuse.rs

1//! RECIPE FUSION — the packages a search recipe mints over the members it LISTS, the evidence its
2//! door answers with, and the door itself.
3//!
4//! ```ignore
5//! #[ingraph::search(shared(text(type = "String")), dedup(hash), limit = 20)]
6//! pub struct TravelSearch {
7//!   #[ingraph(weight = 1.0, depth = 50, tower(zh(type = "crate::ZhQuery", shared)))]
8//!   subs: Subs,
9//!   #[ingraph(weight = 2.0, depth = 100,
10//!     tower(text(type = "crate::ClipText", shared)),
11//!     tower(image(type = "crate::ClipImage", shared)))]
12//!   shots: Shots,
13//! }
14//! ```
15//!
16//! mints, at module scope:
17//!
18//! ```text
19//! TravelSearchSubsTowerOptions   { zh }                          one member's bound towers
20//! TravelSearchShotsTowerOptions  { text, image }
21//! TravelSearchFuseOptions        { fusion, subs: Route<…>, shots: Route<…>, subs_towers, shots_towers }
22//! TravelSearchFuseQuestion       { question, subs: …, shots: … }
23//! TravelSearchFusedEvidence<V₁,…>  one variant per member, holding THAT MEMBER's own evidence
24//! TravelSearchFusedError<E₁,…>     one variant per member, holding THAT MEMBER's own refusal
25//! TravelSearch::fuse(…)            the door
26//! ```
27//!
28//! # THIS IS #290's MACHINERY, MOVED — the ONE HOME migration, and nothing else
29//!
30//! Every type above was minted by a GRAPH ROOT until this round, off the root's `fuse(…)` word, from
31//! `crate::graph::fuse`. What moved is the HOME and the SOURCE: the same [`Packages`] emitter, the
32//! same [`Route`]/[`Fusable`]/`AsyncFusedRead` road, the same reciprocal-rank fold, the same
33//! nested-evidence enums — now minted off a [`SearchModel`] rather than off a `GraphModel`.
34//!
35//! Three things did NOT come with it, each because the migration took away its reason to exist:
36//!
37//! 1. **The WORD-COUNT DOOR LAW.** A root counted how many members wore which word to decide how
38//!    many doors to emit; a recipe LISTS its members, so there is exactly one door and its arity is
39//!    the declaration's own field list. Nothing here counts.
40//! 2. **The TRIMS** — `fuse(vector)` / `fuse(fulltext)` — and with them the typed doors and the
41//!    `VectorFusable`/`FulltextFusable` demands those doors carried. A recipe that wants two
42//!    members fused writes two members; a recipe that wants a different set writes a second recipe,
43//!    which is the *several recipes over one set of members* the grammar already admits. There was
44//!    nothing left for a modality claim to trim, and on 2026-08-19 the two markers themselves were
45//!    struck from `ingraph` — so the demand this list records as unwritten is now unwritable.
46//! 3. **The ROOT's own `fuse` EMISSION.** The graph root keeps the word as a TIER word — it is what
47//!    puts a retrieving declaration on the slot-bearing list the launch builds and the type walk
48//!    visits — and emits no door, no package and no evidence enum. See [`crate::graph`].
49//!
50//! What did NOT change is the MEMBER's side: a member is asked through `AsyncFusedRead::keys` with
51//! its own package and its own question, both reached by projection, and its `fused_keys` stays what
52//! its own declaration minted. The question layer is the grain above this one and owes the member
53//! nothing.
54//!
55//! # THE ROOT the members are joined at is a PARAMETER
56//!
57//! A recipe answers in a key it never names: every member's `AsyncFusedRead::Root` is bound to one
58//! parameter, so two members answering two key types is `E0271` at the caller's own call rather than
59//! a runtime mismatch.
60//!
61//! What the recipe DOES say about that parameter is how the fold tells two of them apart — the
62//! `dedup(hash)` / `dedup(eq)` word, which picks the framework join (`HashJoin` / `EqJoin`) and the
63//! `where` row stated about the root parameter (`Hash + Eq` / `PartialEq`, `Clone` on both).
64//!
65//! [`Route`]: https://docs.rs/ingraph
66//! [`Fusable`]: https://docs.rs/ingraph
67
68use heck::ToUpperCamelCase as _;
69use quote::{format_ident, quote};
70
71use super::{MemberModel, SearchModel};
72use crate::{
73  emit::{framework, leading},
74  fuse::{Packages, Row},
75};
76
77#[cfg(test)]
78mod dedup_tests;
79#[cfg(test)]
80mod tests;
81
82impl SearchModel {
83  /// The RECIPE FUSION emission, whole: the tower packages, the two request packages, the evidence
84  /// and refusal enums, and the door.
85  ///
86  /// UNCONDITIONAL, which is the word-count law's absence stated as code: a recipe with one member
87  /// is a recipe that fuses one ranking, and a one-term fold is the fold. What made the root's
88  /// emission conditional was that a root's members arrived by a word rather than by a list, so
89  /// *fewer than two* was a state it could be in; a recipe with no member is refused at the front
90  /// end.
91  #[must_use]
92  pub fn fuse(&self) -> proc_macro2::TokenStream {
93    let towers = self.tower_packages();
94    let packages = self.packages_emission();
95    let evidence = self.evidence();
96    let door = self.door();
97    quote! {
98      #towers
99      #packages
100      #evidence
101      #door
102    }
103  }
104
105  /// The PACKAGE EMITTER this recipe mints through — the same one an index tier and a graph root
106  /// use, which is what makes this a migration rather than a second implementation.
107  fn packages(&self) -> Packages<'_> {
108    Packages {
109      krate: &self.krate,
110      vis: &self.vis,
111      owner: &self.name,
112      // UNDRESSED BY CHOICE, and the choice is a reserved seam rather than a structural block. A
113      // recipe DOES name a backend (`SearchModel::graphql`) and `IndexGraphql::of` builds the block
114      // this seat wants out of one word, so dressing the tree is a line here rather than a road.
115      // What holds it back is what a dressed tree would then be obliged to publish, which the
116      // 2026-08-27 census read off the rows:
117      //
118      // * the `<member>_towers` rows hold `<Tower as DeclaredTower>::StepOptions`, whose own rows are
119      //   `<Step as Serve>::Options` — so a dressed tree walks straight into the `()` seat: a step
120      //   configured with nothing has no wire face, and this pass cannot know which steps those are;
121      // * the per-member rows hold `Route<<M as Fusable>::Options>`, and `Route`'s own input face
122      //   demands the member's package cross — which is a third party's declaration to keep.
123      //
124      // Both land as `E0277` at the RECIPE's declaration, about types it never wrote. So the packages
125      // stay Rust-only until a round rules WHICH rows a request may name.
126      graphql: None,
127      base: &self.name,
128      // No block is no override: every minted name reaches a schema as its Rust name.
129      members: Vec::new(),
130    }
131  }
132
133  /// ONE PACKAGE PER MEMBER THAT BINDS A TOWER — the knobs a caller names for the towers this
134  /// recipe bound to that member.
135  ///
136  /// # THE TOWER LIVES AT THE SEARCH GRAIN, and this is where that is spelled
137  ///
138  /// A binding used to be written inside the member's own declaration (`arm(…)` / `chain(…)`), and
139  /// that form is retired: a tower turns a QUESTION into what a member can be asked with, and which
140  /// question a deployment asks is the recipe's business rather than the index's. So the tower's
141  /// seat is here, on the recipe's own options tree, beside the [`Route`] rows for the same members.
142  ///
143  /// The type is `<Tower as DeclaredTower>::StepOptions` — a PROJECTION and never a name mangled out
144  /// of the path's last segment. The recipe's expansion has never seen the tower's fields, and this
145  /// is the seam that fact is crossed by: a hand-written tower stating `type StepOptions = ();` seats
146  /// here exactly as a generated one does.
147  ///
148  /// It is the DEPLOYMENT's clock and not the request's, which is why the rename matters at this
149  /// seat: `<Tower>SearchOptions` — the word-keyed package a REQUEST names — is published as the
150  /// recipe's own `options` ARGUMENT and never as a row of this tree.
151  ///
152  /// A member that binds no tower mints nothing, which is the presence law every other package
153  /// emitter here already keeps.
154  ///
155  /// [`Route`]: https://docs.rs/ingraph
156  fn tower_packages(&self) -> proc_macro2::TokenStream {
157    let bound = self.members.iter().filter(|member| !member.arms.is_empty());
158    let minted = bound.map(|member| self.tower_package(member));
159    quote!(#(#minted)*)
160  }
161
162  /// ONE member's tower package — the rows its arms declared, each spelled as the projection.
163  fn tower_package(&self, member: &MemberModel) -> proc_macro2::TokenStream {
164    let declared = framework(&self.krate, &["retrieve"], "DeclaredTower");
165    let rows: Vec<Row> = member
166      .arms
167      .iter()
168      .map(|arm| {
169        let tower = &arm.tower;
170        Row::new(
171          &arm.name,
172          quote!(<#tower as #declared>::StepOptions),
173          &format!("`{}` tower", arm.name),
174        )
175      })
176      .collect();
177    self.packages().package(
178      &tower_options_name(&self.name, &member.field),
179      &format!(
180        "The knobs the towers bound to [`{recipe}`]'s `{member}` member run under — one row per \
181         arm, each holding that TOWER's own options object by projection.",
182        recipe = self.name,
183        member = member.field,
184      ),
185      &rows,
186    )
187  }
188
189  /// The two PACKAGES the door is configured and asked with — one `Route` seat per member, one
190  /// tower seat per member that binds one, and one question seat per member, all reached BY
191  /// PROJECTION off `Fusable`.
192  ///
193  /// A recipe names no member's package type. `<M as Fusable>::Options` is what the seat holds, so a
194  /// third-party member joins with no edit here.
195  fn packages_emission(&self) -> proc_macro2::TokenStream {
196    let krate = &self.krate;
197    let route = framework(krate, &["retrieve"], "Route");
198    let flavour = framework(krate, &["retrieve"], "FusionOptions");
199    let fusable = framework(krate, &["retrieve"], "Fusable");
200    let packages = self.packages();
201    let mut rows = vec![Row::new(
202      &format_ident!("fusion"),
203      quote!(#flavour),
204      "fusion flavour",
205    )];
206    rows.extend(self.members.iter().map(|member| {
207      let ty = &member.ty;
208      Row::new(
209        &member.field,
210        quote!(#route<<#ty as #fusable>::Options>),
211        &format!("`{}` member", member.field),
212      )
213    }));
214    rows.extend(
215      self
216        .members
217        .iter()
218        .filter(|member| !member.arms.is_empty())
219        .map(|member| {
220          let package = tower_options_name(&self.name, &member.field);
221          Row::new(
222            &tower_row(&member.field),
223            quote!(#package),
224            &format!("towers bound to `{}`", member.field),
225          )
226        }),
227    );
228    let options = packages.package(
229      &self.options_name(),
230      &format!(
231        "The knobs a FUSED retrieve under [`{recipe}`] runs under — one route per member, each \
232         wearing the edge facts a request states about it (its weight in the fold, whether it is \
233         walked, and HOW DEEP to ask it) and holding that member's OWN package by projection, plus \
234         one seat per member for the towers this recipe bound to it.",
235        recipe = self.name,
236      ),
237      &rows,
238    );
239    let mut asked = vec![Row::new(
240      &format_ident!("question"),
241      quote!(::std::string::String),
242      "question",
243    )];
244    asked.extend(self.members.iter().map(|member| {
245      let ty = &member.ty;
246      Row::new(
247        &member.field,
248        quote!(<#ty as #fusable>::Question),
249        &format!("`{}` member", member.field),
250      )
251    }));
252    let question = packages.question(
253      &self.question_name(),
254      &format!(
255        "The question a FUSED retrieve under [`{recipe}`] is asked with — the recipe's own, and one \
256         package per member for the members that ask something else. A member whose seat is EMPTY \
257         is not walked, which is the participation rule at recipe grain.",
258        recipe = self.name,
259      ),
260      &asked,
261    );
262    quote! {
263      #options
264      #question
265    }
266  }
267
268  /// The EVIDENCE and REFUSAL enums the door answers with — one variant per member, each holding
269  /// that member's OWN type as a parameter.
270  ///
271  /// # NESTED provenance, and the recipe opens none of it
272  ///
273  /// A member's evidence is whatever its own grain minted. The recipe wraps it in a variant naming
274  /// the MEMBER and asks nothing of the type, which is what *aggregating by projection* means: the
275  /// client reads *which members agreed, and what each of them saw*, all the way down.
276  fn evidence(&self) -> proc_macro2::TokenStream {
277    let vis = &self.vis;
278    let evidence = self.evidence_name();
279    let refusal = self.refusal_name();
280    let seen: Vec<syn::Ident> = self
281      .members
282      .iter()
283      .map(|member| evidence_param(&member.field))
284      .collect();
285    let errors: Vec<syn::Ident> = self
286      .members
287      .iter()
288      .map(|member| error_param(&member.field))
289      .collect();
290    let variants = self.members.iter().zip(&seen).map(|(member, param)| {
291      let variant = variant(&member.field);
292      let doc = leading(&format!(
293        "`{member}` ranked this root, and what `{member}` itself saw — that member's own \
294         provenance, whole.",
295        member = member.field,
296      ));
297      quote! {
298        #[doc = #doc]
299        #variant(#param)
300      }
301    });
302    let refusals = self.members.iter().zip(&errors).map(|(member, param)| {
303      let variant = variant(&member.field);
304      let doc = leading(&format!(
305        "`{member}` refused, in that member's own vocabulary.",
306        member = member.field,
307      ));
308      quote! {
309        #[doc = #doc]
310        #variant(#param)
311      }
312    });
313    let arms = self.members.iter().map(|member| {
314      let variant = variant(&member.field);
315      let field = member.field.to_string();
316      quote! {
317        Self::#variant(__ingraph_refusal) => {
318          ::core::write!(__ingraph_formatter, "{}: {__ingraph_refusal}", #field)
319        }
320      }
321    });
322    let sources = self.members.iter().map(|member| {
323      let variant = variant(&member.field);
324      quote!(Self::#variant(__ingraph_refusal) => ::core::option::Option::Some(__ingraph_refusal))
325    });
326    let displays = errors
327      .iter()
328      .map(|param| quote!(#param: ::core::fmt::Display));
329    let bounds = errors
330      .iter()
331      .map(|param| quote!(#param: ::core::error::Error + 'static));
332    let doc = leading(&format!(
333      "WHICH of [`{recipe}`]'s members agreed about a fused root, and what each of them saw — one \
334       variant per member, each carrying that member's OWN evidence untouched.",
335      recipe = self.name,
336    ));
337    let refusal_doc = leading(&format!(
338      "WHICH of [`{recipe}`]'s members refused, in that member's own vocabulary.",
339      recipe = self.name,
340    ));
341    quote! {
342      #[doc = #doc]
343      #[derive(::core::fmt::Debug, ::core::clone::Clone, ::core::cmp::PartialEq)]
344      #vis enum #evidence<#(#seen,)*> {
345        #(#variants,)*
346      }
347
348      #[doc = #refusal_doc]
349      #[derive(::core::fmt::Debug, ::core::clone::Clone, ::core::cmp::PartialEq)]
350      #vis enum #refusal<#(#errors,)*> {
351        #(#refusals,)*
352      }
353
354      #[automatically_derived]
355      impl<#(#displays,)*> ::core::fmt::Display for #refusal<#(#errors,)*> {
356        fn fmt(
357          &self,
358          __ingraph_formatter: &mut ::core::fmt::Formatter<'_>,
359        ) -> ::core::fmt::Result {
360          match self {
361            #(#arms,)*
362          }
363        }
364      }
365
366      #[automatically_derived]
367      impl<#(#bounds,)*> ::core::error::Error for #refusal<#(#errors,)*> {
368        fn source(&self) -> ::core::option::Option<&(dyn ::core::error::Error + 'static)> {
369          match self {
370            #(#sources,)*
371          }
372        }
373      }
374    }
375  }
376
377  /// THE DOOR — every member asked through the one road, their ordinals folded, and the answer in a
378  /// key this recipe never names.
379  ///
380  /// # The four facts a fold needs, and the recipe answers three of them by DECLARATION
381  ///
382  /// WHICH members to ask (a member whose question seat is empty is structurally absent, and one the
383  /// caller disabled is not walked), how much each one's opinion counts, HOW DEEP to ask each of
384  /// them, and what arithmetic joins them.
385  ///
386  /// The root read the middle two off the REQUEST alone and fell back to the framework's own
387  /// numbers. A recipe declared them, so the fallbacks are the DECLARATION's: a member the request
388  /// did not configure takes the `weight` the recipe wrote for it, and a member the request did not
389  /// ask a depth of is capped at the `depth` the recipe wrote. A recipe that wrote neither is the
390  /// root's own behaviour exactly — `Route::DEFAULT_WEIGHT` and the caller's whole budget — which is
391  /// what makes the migration behaviour-preserving where nothing new was written.
392  ///
393  /// # `limit` STAYS REQUIRED, and the recipe's own `limit` is not what answers it
394  ///
395  /// The declared `limit` rides [`DeclaredSearch::LIMIT`] instead, for the ruling's own reason: the
396  /// framework's answer to *how many* is a CODEGEN constant that becomes an SDL literal, and *no
397  /// door, seam or fold ever reads it*. A door taking an optional budget would need a runtime
398  /// framework default to terminate its chain, which is exactly what that ruling refuses to mint. So
399  /// the caller of the Rust door states its budget, and the declared number is the WIRE's default —
400  /// the tier it was ruled to be in.
401  ///
402  /// # It narrows a member's intake through the EDGE, which is the only place a request may
403  ///
404  /// A recipe holds a member's package by PROJECTION and cannot read a row out of it. What it DOES
405  /// hold about a member is the edge, and `Route::depth` is the fact on it — resolved by
406  /// `route_depth` against the recipe's own declared depth and handed down as that member's own
407  /// `limit`. What happens to the number below is the member's business, which is the FRACTAL.
408  ///
409  /// # The JOIN is the RECIPE's word
410  ///
411  /// The framework join the fold runs and the `where` row the door states about its root parameter
412  /// are both read off `dedup` — `HashJoin` with `Hash + Eq` or `EqJoin` with `PartialEq`.
413  ///
414  /// [`DeclaredSearch::LIMIT`]: https://docs.rs/ingraph
415  fn door(&self) -> proc_macro2::TokenStream {
416    let SearchModel {
417      krate, vis, dedup, ..
418    } = self;
419    let read = framework(krate, &["retrieve"], "AsyncFusedRead");
420    let route = framework(krate, &["retrieve"], "Route");
421    let flavour = framework(krate, &["retrieve"], "FusionOptions");
422    let fusion = framework(krate, &["retrieve"], "Fusion");
423    let fused = framework(krate, &["retrieve"], "Fused");
424    let rooted = framework(krate, &["retrieve"], "Rooted");
425    let weighted = framework(krate, &["retrieve"], "fuse_weighted");
426    let join = framework(krate, &["retrieve"], dedup.join());
427    let admits = dedup.admits();
428    let recipe = &self.name;
429    let key = format_ident!("__INGRAPH_ROOT__");
430    let options = self.options_name();
431    let question = self.question_name();
432    let evidence = self.evidence_name();
433    let refusal = self.refusal_name();
434
435    let engines: Vec<syn::Ident> = self
436      .members
437      .iter()
438      .map(|member| engine_param(&member.field))
439      .collect();
440    let seen: Vec<proc_macro2::TokenStream> = self
441      .members
442      .iter()
443      .zip(&engines)
444      .map(|(member, engine)| {
445        let ty = &member.ty;
446        quote!(<#ty as #read<#engine>>::Evidence)
447      })
448      .collect();
449    let errors: Vec<proc_macro2::TokenStream> = self
450      .members
451      .iter()
452      .zip(&engines)
453      .map(|(member, engine)| {
454        let ty = &member.ty;
455        quote!(<#ty as #read<#engine>>::Error)
456      })
457      .collect();
458    let params = self.members.iter().zip(&engines).map(|(member, engine)| {
459      let field = &member.field;
460      let ty = &member.ty;
461      quote!(#field: <#ty as #read<#engine>>::Ctx<'__ingraph_ctx>,)
462    });
463    let obligations = self.members.iter().zip(&engines).map(|(member, engine)| {
464      let ty = &member.ty;
465      quote! {
466        #engine: '__ingraph_ctx,
467        #ty: #read<#engine, Root = #key>,
468      }
469    });
470    let asks = self.members.iter().zip(&engines).map(|(member, engine)| {
471      let field = &member.field;
472      let ty = &member.ty;
473      let variant = variant(field);
474      let edge = self.member_edge(member);
475      quote! {
476        {
477          #edge
478          // A MEMBER WITH NO QUESTION IS STRUCTURALLY ABSENT, which is `participates`' law at recipe
479          // grain: a request that asked two of three members does not silently ask the third.
480          if let (true, ::core::option::Option::Some(__ingraph_asked)) =
481            (__ingraph_enabled, #question::#field(question))
482          {
483            let __ingraph_ranked = <#ty as #read<#engine>>::keys(
484              #field,
485              ::core::option::Option::and_then(__ingraph_route, #route::options),
486              __ingraph_asked,
487              __ingraph_depth,
488            )
489            .await
490            .map_err(#refusal::#variant)?;
491            __ingraph_members.push((
492              __ingraph_weight,
493              ::core::iter::Iterator::collect::<::std::vec::Vec<_>>(
494                ::core::iter::Iterator::map(
495                  ::std::vec::Vec::into_iter(__ingraph_ranked),
496                  |__ingraph_hit| {
497                    let (__ingraph_root, __ingraph_rank, __ingraph_seen) =
498                      __ingraph_hit.into_components();
499                    #rooted::new(
500                      __ingraph_root,
501                      __ingraph_rank,
502                      #evidence::#variant(__ingraph_seen),
503                    )
504                  },
505                ),
506              ),
507            ));
508          }
509        }
510      }
511    });
512    let doc = leading(&format!(
513      "FUSED — every member [`{recipe}`] lists asked at once, their rankings joined by reciprocal \
514       rank fusion. Answers in the key every one of them agrees about.",
515    ));
516    let projection = leading(
517      "This recipe names NOTHING of a member's: the context, the package, the question, the \
518       evidence and the refusal are all projections, so a third-party member joins by implementing \
519       `AsyncFusedRead` and this door absorbs it with no edit here.",
520    );
521    let currency = leading(
522      "No score of any member enters the fusion — only the ORDINAL each of them gave the hit — which \
523       is what lets members whose currencies were never compared be fused at all. Each member's own \
524       evidence rides out NESTED instead, whole and unopened.",
525    );
526    let key_note = leading(
527      "The ROOT is a parameter and never a type this emission names: every member's own key is \
528       bound to it, so two members answering two key types have no root to be fused at and say so \
529       as `E0271` at this call.",
530    );
531    let mechanism = leading(&format!(
532      "Roots are placed through `{join}`, which is what this recipe's `dedup({word})` chose — the \
533       `where` row below is that mechanism's price. The law it answers is that a key that cannot \
534       hash is retrievable, so a member that reached for `dedup(eq)` for that reason must not \
535       become unfusable in a recipe that lists it.",
536      join = dedup.join(),
537      word = dedup.as_str(),
538    ));
539    quote! {
540      #[automatically_derived]
541      impl #recipe {
542        #[doc = #doc]
543        #[doc = ""]
544        #[doc = #projection]
545        #[doc = ""]
546        #[doc = #key_note]
547        #[doc = ""]
548        #[doc = #currency]
549        #[doc = ""]
550        #[doc = #mechanism]
551        #[allow(clippy::too_many_arguments)]
552        #vis async fn fuse<'__ingraph_ctx, #key, #(#engines),*>(
553          #(#params)*
554          options: ::core::option::Option<&#options>,
555          question: &#question,
556          limit: ::core::num::NonZeroUsize,
557        ) -> ::core::result::Result<
558          ::std::vec::Vec<#fused<#key, #evidence<#(#seen,)*>>>,
559          #refusal<#(#errors,)*>,
560        >
561        where
562          #key: #admits,
563          #(#obligations)*
564        {
565          let __ingraph_fusion = ::core::option::Option::map_or(
566            ::core::option::Option::and_then(options, #options::fusion),
567            <#fusion as ::core::default::Default>::default(),
568            #flavour::fusion,
569          );
570          let mut __ingraph_members = ::std::vec::Vec::new();
571          #(#asks)*
572          ::core::result::Result::Ok(
573            #weighted::<_, _, #join<#key>>(__ingraph_members, __ingraph_fusion)
574          )
575        }
576      }
577    }
578  }
579
580  /// **ONE MEMBER'S EDGE, RESOLVED** — the four numbers a fold needs about a member, in the tier
581  /// order the spec locks, as the statements that bind them.
582  ///
583  /// Binds `__ingraph_route`, `__ingraph_enabled`, `__ingraph_weight` and `__ingraph_depth`, and
584  /// reads `options` and `limit` from the scope it is spliced into.
585  ///
586  /// # It is a HELPER because there are two callers and ONE law
587  ///
588  /// The Rust door asks each member through its own `Ctx`; the WIRE road asks it through the citizen
589  /// seam, out of the schema's own data. What each of them ASKS differs; what the recipe DECLARED
590  /// about the edge does not — the weight, the depth chain and the participation rule are the same
591  /// four lines whoever spends them. Written twice they could come to disagree, and the thing that
592  /// would disagree is the number a client sees.
593  pub(super) fn member_edge(&self, member: &MemberModel) -> proc_macro2::TokenStream {
594    let krate = &self.krate;
595    let route = framework(krate, &["retrieve"], "Route");
596    let depth = framework(krate, &["retrieve"], "route_depth");
597    let fusable = framework(krate, &["retrieve"], "Fusable");
598    let options = self.options_name();
599    let field = &member.field;
600    let ty = &member.ty;
601    // THE DECLARED COEFFICIENT — the recipe's own `weight`, or the request layer's multiplicative
602    // identity where the recipe wrote none. `Route::weight` is not an `Option`, so a route the
603    // request supplied answers whole and a member with no route falls to the declaration.
604    let declared_weight = member.weight.map_or_else(
605      || quote!(#route::<<#ty as #fusable>::Options>::DEFAULT_WEIGHT),
606      |weight| quote!(#weight),
607    );
608    let declared_depth = member.depth.map_or_else(
609      || quote!(::core::option::Option::None),
610      |depth| {
611        let depth = depth.get();
612        quote!(::core::num::NonZeroU32::new(#depth))
613      },
614    );
615    quote! {
616      let __ingraph_route = ::core::option::Option::and_then(options, #options::#field);
617      let __ingraph_enabled = ::core::option::Option::map_or(
618        __ingraph_route,
619        #route::<<#ty as #fusable>::Options>::DEFAULT_ENABLED,
620        #route::enabled,
621      );
622      let __ingraph_weight = ::core::option::Option::map_or(
623        __ingraph_route,
624        #declared_weight,
625        #route::weight,
626      );
627      // THE DEPTH THIS RECIPE ASKS THIS MEMBER AT — the request's own ask, capped by the depth the
628      // DECLARATION wrote, cut at the caller's budget. The middle tier is what a graph root
629      // structurally could not fill: a root held no per-member number, and a recipe does.
630      let __ingraph_declared: ::core::option::Option<::core::num::NonZeroU32> = #declared_depth;
631      let __ingraph_depth = #depth(
632        ::core::option::Option::and_then(__ingraph_route, #route::depth),
633        ::core::option::Option::as_ref(&__ingraph_declared),
634        limit,
635      );
636    }
637  }
638
639  /// The name of the package the door is configured with.
640  pub(super) fn options_name(&self) -> syn::Ident {
641    format_ident!("{}FuseOptions", self.name)
642  }
643
644  /// The name of the package the door is asked with.
645  pub(super) fn question_name(&self) -> syn::Ident {
646    format_ident!("{}FuseQuestion", self.name)
647  }
648
649  /// The name of the enum the door's answers carry their provenance in.
650  pub(super) fn evidence_name(&self) -> syn::Ident {
651    format_ident!("{}FusedEvidence", self.name)
652  }
653
654  /// The name of the enum the door refuses with.
655  pub(super) fn refusal_name(&self) -> syn::Ident {
656    format_ident!("{}FusedError", self.name)
657  }
658}
659
660/// The name of ONE MEMBER's tower package.
661fn tower_options_name(recipe: &syn::Ident, member: &syn::Ident) -> syn::Ident {
662  format_ident!(
663    "{recipe}{}TowerOptions",
664    member.to_string().to_upper_camel_case()
665  )
666}
667
668/// The row ONE MEMBER's tower package takes in the recipe's own options package.
669///
670/// A COMPOUND name, and the one this emission mints: a member already owns the row holding its
671/// `Route`, and its towers are a second fact about the same member. Two rows under one name is
672/// refused where every package is built, so a member whose neighbour is literally called
673/// `<member>_towers` is told so rather than silently merged.
674fn tower_row(member: &syn::Ident) -> syn::Ident {
675  format_ident!("{member}_towers")
676}
677
678/// ONE member's variant name in a recipe's evidence and refusal enums.
679fn variant(field: &syn::Ident) -> syn::Ident {
680  format_ident!("{}", field.to_string().to_upper_camel_case())
681}
682
683/// The ENGINE parameter one member is asked through — the standing emitted-ident law at recipe
684/// grain.
685fn engine_param(field: &syn::Ident) -> syn::Ident {
686  crate::fuse::engine_param(field)
687}
688
689/// The EVIDENCE parameter one member's own provenance rides.
690fn evidence_param(field: &syn::Ident) -> syn::Ident {
691  use heck::ToShoutySnakeCase as _;
692
693  format_ident!(
694    "__INGRAPH_EVIDENCE_{}__",
695    field.to_string().to_shouty_snake_case()
696  )
697}
698
699/// The ERROR parameter one member's own refusal rides.
700fn error_param(field: &syn::Ident) -> syn::Ident {
701  crate::fuse::error_param(field)
702}