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
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
//! WHAT AN ELECTED FIELD HOLDS — the type-level family an `embedding(<field>)` election projects
//! every fact through, so that no macro ever reads a type by its spelling.
//!
//! ```text
//! Embedding<f32, 768, Clip> → Item = Embedding<f32, 768, Clip> Multiplicity = One
//! Vec<Embedding<f32, 768, Clip>> → Item = Embedding<f32, 768, Clip> Multiplicity = Set
//! type ClipFrames = Vec<…> → the SAME two answers, the alias being transparent to a bound
//! ```
//!
//! # The law this layer exists to keep
//!
//! A derive holds TOKENS. It cannot know what `ClipFrames` denotes, and a front end that reached
//! into the tokens to find out — peeling a `Vec<…>`, then reading `E`, `N` and `S` off what was
//! inside — is guessing at a meaning only rustc has. The guess is wrong for every alias, for every
//! re-export renamed on the way in, and for every carrier that is not literally spelled `Vec`.
//!
//! So the front end reads NOTHING off an elected field's type. It carries the type as an opaque
//! token and the emission projects, and this is the family the projections go through:
//!
//! | the fact | where it comes from |
//! |---|---|
//! | one embedding or a set of them | [`EmbeddingMarker::Multiplicity`] |
//! | the carried embedding | [`EmbeddingMarker::Item`] |
//! | `E`, `N`, `S` | [`EmbeddingShape`] on that item, and NOWHERE else |
//! | the values | [`EmbeddingMarker::members`] |
//!
//! [`Item`](EmbeddingMarker::Item) is the SINGLE AUTHORITY: every fact about the coordinates is read
//! off it, so a carrier states its item and cannot go on to state a width that disagrees with the
//! item's own. Two homes for one fact are two answers that may drift; this family has one.
//!
//! # The LABEL is the other reader, and these traits are what settle the two
//!
//! A declaration also writes a label — `embedding` or `list(embedding)` — and the label is what the
//! EXPANSION reads, because an expansion cannot resolve a type. So one fact has two readers, which
//! is the shape that drifts. [`ElectsOne`] and [`ElectsSet`] are how it is settled: the emission
//! states the label's claim as a bound and rustc decides it, at the span of the election word its
//! author wrote.
//!
//! # OPEN, because a carrier is not the framework's to enumerate
//!
//! [`EmbeddingMarker`] is not sealed. A downstream holding its embeddings in something other than a
//! [`Vec`] — a `SmallVec`, an arena slice, a newtype that owns an invariant about its members —
//! writes one impl and its elections work exactly as the framework's own do. That is the same
//! openness [`State`](crate::State) has one layer over, and for the same reason: what a container IS
//! is the container's to say.
//!
//! What is CLOSED is the [`Multiplicity`] vocabulary, and only that. [`One`] and [`Set`] are the two
//! structural axes an emission knows how to emit faces for, so a third would be a face nobody wrote
//! rather than a carrier nobody had thought of — the crate's standing split between a
//! framework-owned vocabulary and the open surface underneath it.
//!
//! # The fixed-size seat is RESERVED, and the orphan rule holds it for free
//!
//! `[Embedding<E, N, S>; K]` has no impl here. It therefore elects nothing today, and the refusal an
//! author meets is [`EmbeddingMarker`]'s own `on_unimplemented` note. Nobody downstream can take the
//! seat either — a foreign trait on a foreign type is `E0117` — so the day this framework decides
//! what a constant length MEANS to a slot, the impl it writes is the first one and breaks nothing.
use crateEmbedding;
/// A field an `embedding(<field>)` election may name — ONE embedding, or a carrier holding a SET of
/// them.
///
/// # What implementing it costs
///
/// Three lines, and the third is the only one with a body:
///
/// ```
/// use ingraph::{Embedding, EmbeddingMarker, Set};
///
/// /// A downstream carrier: keyframe embeddings that arrive already in frame order.
/// pub struct Frames(Vec<Embedding<f32, 768>>);
///
/// impl EmbeddingMarker for Frames {
/// type Item = Embedding<f32, 768>;
/// type Multiplicity = Set;
///
/// fn members(&self) -> impl Iterator<Item = &Self::Item> {
/// self.0.iter()
/// }
/// }
/// ```
///
/// Nothing registers the carrier and nothing here has to learn about it. A `vector` declaration may
/// then elect a `Frames` field, and every fact the emission needs — the element, the width, the
/// space, the members and their order — comes back through this impl.
///
/// # The ORDER `members` yields IS the ordinal order
///
/// A set election's members are stored under `(owner, ordinal)`, and the ordinals are minted by
/// walking this iterator. So the contract is that the walk is the entity's own order and is the SAME
/// order twice: a set of keyframe embeddings comes back in keyframe order because the carrier yields
/// them in it, and a carrier whose iteration order is not stable has not implemented this trait.
///
/// It is a contract rather than a bound because no bound expresses it — [`Iterator`] promises an
/// order and promises nothing about which. What the framework can do is state it here and pin it on
/// its own rows, which
/// [`the_order_members_yields_is_the_ordinal_order`](self::tests::the_order_members_yields_is_the_ordinal_order)
/// does.
///
/// # A single election is a set of one, mechanically
///
/// [`One`]'s row yields exactly one member. So the emission has ONE way to read values — walk the
/// members — and the multiplicity decides only which FACE they are reported on and whether an
/// ordinal rides beside them. There is no unwrap anywhere on that path and no partial function to
/// get wrong.
/// ONE embedding's own facts — the element type, the width and the space — as a projection rather
/// than as a spelling.
///
/// Separate from [`EmbeddingMarker`] because the two answer about different things: a marker answers
/// about the FIELD, and this answers about what the field carries. Welding them would give a carrier
/// its own `Element` and `WIDTH` beside the item's, which is the disagreement
/// [`Item`](EmbeddingMarker::Item) exists to make unspellable.
///
/// OPEN for [`EmbeddingMarker`]'s reason, one grain down: a downstream whose embeddings are its own
/// type — a quantized vector, a borrowed view over a decoder's buffer — implements this and joins
/// without the framework knowing it exists.
/// HOW MANY embeddings one election names — a CLOSED type-level vocabulary of two.
///
/// Closed because it is the FRAMEWORK's: each word names a set of faces the emission knows how to
/// write, so a third would be a shape nobody had emitted anything for rather than a carrier nobody
/// had thought of. That is this crate's standing split — a framework-owned vocabulary is closed, and
/// the open surface is one level down, where [`EmbeddingMarker`] takes any carrier at all.
///
/// Sealed rather than merely documented, so the closure is a compile error rather than a request.
/// ONE embedding — the shape every election written before the set arrived has, and the one this
/// family leaves entirely alone.
///
/// Its field is reported on [`VectorRecord::vectors`](crate::VectorRecord::vectors) exactly as it
/// always was, carries no ordinal, and grows no set door.
);
/// A per-entity SET of embeddings — variable in length, EMPTY being legal.
///
/// Its field is reported on [`VectorRecord::vector_sets`](crate::VectorRecord::vector_sets) under
/// ordinals running `0..n` in [`members`](EmbeddingMarker::members) order, and its election grows the
/// set-similarity door.
);
/// The `embedding` LABEL's claim, held over the MULTIPLICITY a field's marker answers with.
///
/// # Why the label is audited at all
///
/// The label is what the EXPANSION reads — it decides which faces and which doors are written, and a
/// macro cannot resolve a type to find out. The marker is what RUSTC reads. Two readers of one fact
/// is exactly the shape that drifts, so the emission states the label's claim as a bound and lets
/// the compiler settle it: a field labelled `embedding` whose type carries a set is refused HERE, at
/// the span of the election word its author wrote.
///
/// # The claim is held over the MULTIPLICITY, and that is what makes the sentence reachable
///
/// Two shapes say the same thing and only one of them can teach. `where F: EmbeddingMarker<
/// Multiplicity = One>` — and equally a blanket `impl<F> ElectsOne for F where F:
/// EmbeddingMarker<Multiplicity = One>` — decides applicability by an ASSOCIATED-TYPE EQUALITY, so a
/// mismatch is `E0271`, *type mismatch resolving …*, and
/// [`on_unimplemented`](diagnostic::on_unimplemented) rides unsatisfied TRAIT bounds only: the note
/// never renders. Measured on stable, twice, then written this way — the obligation is
/// `<F as EmbeddingMarker>::Multiplicity: ElectsOne<F>`, which a set-carrying field fails by having
/// NO IMPL, which is `E0277`, which carries the sentence.
///
/// The field rides as the parameter so the message can name it: `{Field}` is what the author wrote,
/// and `{Self}` is the multiplicity their type actually answered with.
/// [`One`] satisfies the claim for EVERY field — which is the whole of what the claim says: this
/// field's multiplicity is that one.
/// The `list(embedding)` LABEL's claim — [`ElectsOne`]'s twin, whose note states the whole of what
/// this trait is for.
/// [`Set`]'s row — [`ElectsOne`]'s, one multiplicity over.
/// The `embedding` label's audit, as a function an expansion takes the address of.
///
/// `const _: fn() = elects_one::<TheField>;` beside the election, which is the shape every audit in
/// this crate takes — see [`stores_rows`](crate::stores_rows), where the idiom is written down.
/// The `list(embedding)` label's audit — [`elects_one`]'s twin.
/// The FRAMEWORK's single-embedding row: a field spelled `Embedding<E, N[, S]>` is one embedding,
/// and is its own item.
/// The FRAMEWORK's set row, and the only carrier it ships.
///
/// `Vec<Embedding<…>>` rather than a blanket over every [`IntoIterator`], because a blanket would
/// collide with the single row above the moment a downstream embedding type wanted to iterate as
/// itself — and because a carrier's ORDER is the contract here, which a blanket cannot state on
/// somebody else's behalf.
/// The element, the width and the space, off the type that states all three.