1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
//! **WHERE A SCHEMA-ASKED RECIPE FINDS ITS MEMBERS** — the two seams a recipe's emitted resolver
//! reaches one member through, and the one it hydrates an address through.
//!
//! ```text
//! travelSearch(text: "harbour at dusk", first: 10)
//! │
//! ├─ <Subs as FusedEngine>::Engine WHICH engine a schema asks this member through
//! ├─ <Subs as FusedCitizen<_>>::ranked(ctx, …) that member's ranked keys, citizens and all
//! ├─ <Shots as FusedCitizen<_>>::ranked(ctx, …)
//! │
//! ├─ fuse_weighted(…) the framework's own fold, over the same edges
//! │
//! ├─ <Root as WireRoot>::address(root) the KEYS half of the answer pair
//! └─ <Root as WireRoot>::hydrate(ctx, keys) the HYDRATED half of it
//! ```
//!
//! # THE WALL THESE THREE EXIST FOR
//!
//! A recipe holds a member's type PATH. What a member is asked THROUGH — a slot handle branded for
//! that declaration, a read scope opened on that mount's manager, the engine's own floor and its own
//! knobs — is written in the MEMBER's declaration, and
//! [`AsyncFusedRead::Ctx`](crate::AsyncFusedRead::Ctx) is the seat that carries it across without a
//! parent ever naming a part of it. That works for a RUST caller, who holds the handles already.
//!
//! A RESOLVER holds none: it has an [`async_graphql::Context`] and a schema somebody handed a
//! [`Shared<R>`](crate::Shared) to, and it cannot be generic — a resolver is a concrete `async fn`
//! on a unit type, and the corpus lookup is a `TypeId` on a concrete pairing. So the engine has to
//! be a type the RECIPE's expansion can spell, and the only declaration that knows one is the
//! member's. That is exactly the shape [`Fusable`](crate::Fusable) and
//! [`AsyncFusedRead`](crate::AsyncFusedRead) already answer for the Rust road, and these are their
//! wire twins.
//!
//! # WHY TWO TRAITS AND NOT ONE
//!
//! The obvious single trait carries `type Engine` beside a verb whose signature mentions
//! `<Self as AsyncFusedRead<Self::Engine>>::…`. It is a supertrait cycle through an associated type,
//! and the road around it needs a higher-ranked associated-type equality over a lifetime, which is
//! not spellable on stable. So the engine is named by one trait and the read parameterised on it,
//! and the recipe writes `<M as FusedCitizen<<M as FusedEngine>::Engine>>::ranked(ctx, …)`.
//!
//! # THEY ARE OPEN, and that is the whole reason they are traits
//!
//! Nothing here is the macro's to own. A third-party member joins a recipe's WIRE road exactly as it
//! joins its Rust one — by writing these impls — and the recipe absorbs it by projection with no
//! edit. The same discipline [`Fusable`](crate::Fusable)'s own note states one layer down.
use ;
/// **WHICH ENGINE A SCHEMA ASKS THIS MEMBER THROUGH.**
///
/// A member's Rust doors are generic over their engine — that is the heterogeneity the fusion tree
/// is built on — and a RESOLVER cannot be. So a member that publishes a wire road names the one
/// engine a schema asks it through, and the recipe's expansion reads it as a projection.
///
/// # It is the member's answer and not the recipe's
///
/// A recipe lists members; which store each of them is written to is that member's declaration's
/// business, and a recipe that named one would be reaching inside a declaration it cannot see. The
/// same two-clock wall the per-leg floor already sits behind.
/// **HOW A SCHEMA ASKS ONE MEMBER FOR ITS RANKED KEYS** — the wire twin of
/// [`AsyncFusedRead::keys`](crate::AsyncFusedRead::keys), with the citizen lookup inside it.
///
/// The read seam takes the asking position as a parameter, because a RUST caller already holds the
/// handles. A resolver holds an [`async_graphql::Context`] and nothing else, so this verb mints the
/// position out of the schema's own citizens and spends it in one move — and the recipe's wire face
/// never names a slot, a scope, a floor or a knob of any member's.
///
/// # THE FUTURE IS BOXED, and that is measured rather than a matter of taste
///
/// The obvious signature returns `impl Future<…> + Send + 'a`. It does not survive contact with a
/// resolver: a recipe's members are asked through `Ctx<'a>` GATs carrying `where E: 'a`, and an
/// opaque future over those cannot be produced inside another `async fn` at all —
/// rust-lang/rust#100013, reported as *lifetime bound not satisfied* at the attribute that emitted
/// the caller, with no span a reader could act on and no note naming a type. A `Pin<Box<dyn …>>` is
/// a CONCRETE type with no hidden regions, so the limitation has nothing to bite. The cost is one
/// allocation per member per request, paid where a store round trip is about to be.
///
/// The `Send` is the IMPLEMENTOR's promise rather than the seam's demand on anybody: a member knows
/// its own engine, where [`AsyncFusedRead`](crate::AsyncFusedRead) — which is total over engines it
/// has never seen — deliberately promises nothing. A resolver's future must be `Send`, so this is
/// where that obligation lands and the only place it can.
///
/// # The shipped road for a declared member
///
/// [`vector_slot`](super::vector_slot) / [`search_slot`](super::search_slot) mint the branded handle
/// and the manager it reaches back through, off the [`Shared<R>`](crate::Shared) a launch installed;
/// the body then hands both to this member's own `keys`. A member whose store is held somewhere else
/// mints its position whichever way it likes — the openness the resource axis already put one layer
/// down.
/// **WHAT A RECIPE'S ROOT IS ON THE WIRE** — the address a client reads, and the row that address
/// points at.
///
/// A recipe answers in a ROOT: one key type every member agrees about. The KEYS tier publishes the
/// address and the HYDRATED tier publishes what it points at, and both are facts about the KEY — so
/// they arrive as one capability ON the key rather than as a mechanism this crate picked, and two
/// recipes over one root answer the same way by construction.
///
/// # The ADDRESS is a projection of the key's columns, not the key
///
/// [`GraphqlOutput::Key`](crate::GraphqlOutput::Key)'s own statement one family over: a key holds
/// the declaration's own types and an address holds what a schema can name. An entity that publishes
/// a wire face already mints the projection and the `From` that reaches it, so the shipped impl is
/// one line.
///
/// # HYDRATION IS POSITIONAL, and a hole is an answer
///
/// [`hydrate`](Self::hydrate) answers one entry per key IN THE ORDER THEY WERE ASKED, and [`None`]
/// where the row is gone. That is the emitted hydrated road's own law one grain down: a lost row
/// leaves a hole rather than shifting every row after it, so the two halves of the answer pair can
/// be read side by side.
///
/// # It is a RECIPE's demand and never a member's
///
/// A member's own roads publish their own addresses through their own upstream's face. This is what
/// a RECIPE needs, whose root is a type it never names — every member's
/// [`Root`](crate::AsyncFusedRead::Root) is bound to one parameter — so the capability belongs where
/// the type is.