1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
//! What a TOWER is: the question pipeline that turns what a person asked into what an index can be
//! asked with.
//!
//! A tower is layer ⑤ — `Question → step → step → … → Answer` — and its whole content is a chain of
//! [`Serves`](crate::Serves) / [`AsyncServes`](crate::AsyncServes) hops whose ends meet. The
//! declaration is the struct that HOLDS them:
//!
//! ```ignore
//! #[ingraph::tower(question(type = "String"))]
//! pub struct ClipText {
//! #[ingraph(answer = "Vec<String>")] tokenize: Tokenize,
//! #[ingraph(answer = "Vec<f32>", async)] encode: ClipTextTower,
//! }
//! ```
//!
//! # THE CHAIN IS NOT STATED HERE, and it could not be
//!
//! This trait carries the tower's two ENDS and where its steps live, and says nothing about the
//! hops between them. That is not an omission: a trait's shape is fixed and a tower's arity is
//! not, so the per-hop demand — *this step answers the question the step before it asked* — has no
//! seat here to sit in. It is stated instead on the emitted `impl`'s own `where` clause, one
//! predicate per adjacency, each spanned at the step field it is about. A tower whose chain does
//! not meet is `E0277` at the impl with the caret on the step that broke it, and this trait is what
//! that impl is FOR.
//!
//! # The WALK is an inherent fn, for the same reason
//!
//! A three-step tower's walk takes three step borrows and a five-step tower's takes five, so the
//! walk cannot be a method here either. The emission mints it on the declaration itself —
//! `ClipText::walk(question, &mut tokenize, &mut encode, options)` — which is the mutation node's
//! assembled face one layer over, and its FACE follows the same OR law: one awaited step makes the
//! whole walk awaited.
//!
//! # It is an OPEN seam
//!
//! Nothing here is the macro's to own. A hand-written tower writes these three lines and its own
//! walk, and every consumer that binds `SearchTower` takes it — the framework-open discipline the
//! resource axis and the origin layer already state one layer down.
//!
//! # THE RECORD is what crosses the wall
//!
//! [`SearchTower`] is what a tower IS; [`DeclaredTower`] is what one DECLARED. The split is the
//! same one [`DeclaredMutation`](crate::DeclaredMutation) and [`DeclaredOrigin`](crate::DeclaredOrigin)
//! already make one layer down, and it exists for the same wall: a search recipe naming
//! `tower(text(type = "crate::ClipText"))` expands in a pass that has never seen `ClipText`'s
//! fields, so what crosses is a trait impl and a projection off it rather than a guess at a name.
/// **WHAT A TOWER IS ASKED, WHAT IT ANSWERS, AND WHERE ITS STEPS LIVE.**
///
/// Emitted by `#[ingraph::tower]` off the declaration's own words, and hand-writable by anybody —
/// see the module note for why the chain between the two ends is not here.
///
/// # The two ends are TYPES rather than a kind
///
/// A tower is KIND-AGNOSTIC: a `String → String` rewrite tower serves a full-text binding and a
/// `String → Vec<f32>` one serves a vector binding, and nothing here distinguishes them. What a
/// binding checks is the [`Answer`](Self::Answer) TYPE against what the member it binds is
/// addressed by, so the contract is the type and never a word.
/// **WHAT ONE TOWER DECLARED** — the facts its own expansion states, for the readers that cannot see
/// its tokens.
///
/// [`DeclaredMutation`](crate::DeclaredMutation)'s shape one layer over, and for the same wall: two
/// macro expansions cannot read each other, so a tower STATES its facts as a trait impl and whoever
/// needs them NAMES them through a projection.
///
/// ```ignore
/// impl DeclaredTower for ClipText {
/// type StepOptions = ClipTextStepOptions;
/// type SearchOptions = ClipTextSearchOptions;
/// const ALL_SYNC: bool = false;
/// const STEPS: &'static [Step] = &[Step::of("tokenize"), Step::of("encode").awaited()];
/// }
/// ```
///
/// # What each seat is FOR
///
/// A search recipe binding a tower has four questions its own tokens cannot answer, and this row
/// answers all four: whether to `.await` the walk it emits ([`ALL_SYNC`](Self::ALL_SYNC), the OR law
/// read the other way round), what the DEPLOYMENT named at install
/// ([`StepOptions`](Self::StepOptions)), what a REQUEST may name per question
/// ([`SearchOptions`](Self::SearchOptions)), and which steps the step-keyed object has rows for
/// ([`STEPS`](Self::STEPS), in declaration order — the same order the walk takes its borrows in).
///
/// # THE TWO OPTIONS SEATS ARE TWO CLOCKS, and the names say which
///
/// [`StepOptions`](Self::StepOptions) is keyed by STEP and named once, at INSTALL: it is the
/// deployment's clock, and its rows are the application's own `Serve::Options` types.
/// [`SearchOptions`](Self::SearchOptions) is keyed by the declaration's own WORDS and named per
/// REQUEST: it is the requester's clock, and its rows are the FRAMEWORK's knobs — the only ones an
/// emitter can key a field on and the only ones that mean the same thing for every tower.
///
/// The two ENDS are not restated here, and that is the one-landing law rather than an omission: the
/// supertrait already carries [`Question`](SearchTower::Question) and
/// [`Answer`](SearchTower::Answer), so a reader that holds this row holds them too and no two seats
/// can disagree about one fact.
///
/// # It is a PUBLIC seam, exactly as [`SearchTower`] is
///
/// Both constants are defaulted, so a hand-written tower joins with two type lines and nothing else.
/// A tower is not obliged to be generated to be bound.
/// ONE DECLARED STEP, as the declaration wrote it.
///
/// The per-field facts of the tower grammar, in the shape a reader spends them: which field, and
/// which face the word beside it chose. Both are `const`-constructible, because the whole roster is
/// an associated constant — [`Exchange`](crate::Exchange)'s own reason one layer down: a tower's
/// steps are a fact about its declaration and not a value anybody computes.
///
/// # It carries the NAME and never the type
///
/// A step's server is a TYPE, and a type is what the emitted chain's own `where` predicate names —
/// where the compiler can check it. What a reader of this record does with a step is name its ROW:
/// the walk parameter it fills, the options field it configures, the schema row it publishes. So
/// what is carried is the one name those three homes share.