ingraph_codegen/engine.rs
1//! WHERE an elected field is written: the engine blocks a declaration wears, and the SLOT each one
2//! names.
3//!
4//! ```text
5//! #[ingraph(knn, lance, hnsw(ef = 200), fanout)]
6//! pub image: Embedding<f32, 768>,
7//! ```
8//!
9//! One field, one election, and beside it the engines that hold it. The words are BARE and they
10//! carry their own options, because on an index field the ENGINE IS THE STORE — there is no second
11//! axis for a `persist(…)` wrapper to namespace against, which is the whole of why the record's
12//! shape is not repeated here.
13//!
14//! # The semantics are the RECORD's, measured and mirrored rather than reinvented
15//!
16//! Several blocks are declared PORTABILITY, and the default is SINGLE-WRITE. That is not a new rule:
17//! it is what `persist(sqlite, postgres)` already means, and the record side answers *which one is
18//! live* in two layers that this module mirrors exactly —
19//!
20//! | layer | the record side | here |
21//! |---|---|---|
22//! | COMPILE — declared ∩ compiled-in | `__private::gate::if_<db>!` around every impl naming a concrete backend | [`EngineKind::gate`], around every impl naming a concrete engine |
23//! | CALL — which store this call writes | the METHOD NAME (`insert_postgres`), the driver staying a type parameter | the SLOT (`field × engine`), the engine staying a type parameter |
24//!
25//! The record side's own words for the second layer: *an expansion may not spell `sqlx::Sqlite`, so
26//! the method NAME is where the database is chosen and the type parameter is where the driver is.*
27//! Read back here, the SLOT is where the engine is chosen and the type parameter is where the engine
28//! handle is — which is the shape a derived index's emitted retrieve already had before this round,
29//! carrying `__INGRAPH_ENGINE__` as a method parameter.
30//!
31//! So *declare many, build one, and write through whichever door the deployment opened* is
32//! inherited whole. [`fanout`](FieldEngines::fanout) is the ONE departure, and it is a marker
33//! precisely because it departs.
34//!
35//! # The vocabulary is OPEN, and [`EngineKind`] is not the vocabulary
36//!
37//! [`DatabaseKind`](crate::model::DatabaseKind) is CLOSED — *a database the framework does not ship
38//! an emitter for has nothing to be opened* — and the engine axis is the opposite case, which is why
39//! the two tables look alike and mean different things. A database needs an emitter here; an engine
40//! needs only an implementation of a trait `ingraph` already publishes, and third parties are
41//! expected to bring them. [`EngineKind`] is therefore the SHIPPED table — the words that self-bind
42//! under their own feature — and a word outside it is an ordinary declared word whose binding is the
43//! graph root's `engines(…)`.
44
45use quote::format_ident;
46
47use crate::model::NodeKind;
48
49/// An engine `ingraph` itself ships — the words that SELF-BIND under a feature of the framework's
50/// own.
51///
52/// # Why a table at all, when the vocabulary is open
53///
54/// Three facts are true of a shipped word and of no other, and each of them is a refusal or an
55/// emission that has to know:
56///
57/// 1. it names a CONCRETE type this crate can spell, so the impls naming one ride
58/// [`gate`](Self::gate) — the record side's law, applied to the engine axis;
59/// 2. it is a KIND, and kind is said ONCE — at the resource. So the word at an ELECTION is a named
60/// refusal whichever kind it serves, and [`serves`](Self::serves) is what lets that sentence say
61/// what the word actually holds. (It was a kind-GUARDED refusal while the word self-bound at the
62/// election; the resource axis dropped the guard and kept the reading.)
63/// 3. it is ALREADY BOUND, so `engines(tantivy = "…")` at a graph root is a refusal — rebinding a
64/// shipped word would give one word two meanings in one program.
65///
66/// A word outside this table is none of those things and is refused for none of them.
67///
68/// # It has TWO members, and that is a measurement rather than a stub
69///
70/// `ingraph` ships exactly two engine implementations: `TantivyFulltext` under `feature = "tantivy"`,
71/// and the local-filesystem blob store under NO feature at all. There is no `VectorEngine`
72/// implementation in this workspace — *lance* appears in this repository only in prose and in the
73/// unbuilt `legacy/` reference — so the vector side of the grammar is served entirely by the open
74/// half, which is the strongest argument the open half has.
75#[derive(Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord, Hash)]
76pub enum EngineKind {
77 /// Tantivy, the shipped FULL-TEXT engine.
78 Tantivy,
79 /// The local filesystem, the shipped ARTIFACT store.
80 Fs,
81}
82
83impl EngineKind {
84 /// Every shipped engine, in the order a refusal lists them.
85 pub const ALL: [Self; 2] = [Self::Tantivy, Self::Fs];
86
87 /// The word a declaration writes.
88 #[must_use]
89 pub const fn as_str(self) -> &'static str {
90 match self {
91 Self::Tantivy => "tantivy",
92 Self::Fs => "fs",
93 }
94 }
95
96 /// WHICH KIND of declaration this engine serves.
97 ///
98 /// A full-text engine holds documents and a vector engine holds coordinates, and the two seams are
99 /// different traits. It is read in two places and means the same thing in both: the BLOB walk
100 /// refuses a word of another family outright, and the ELECTION's retirement sentence — which
101 /// refuses every shipped word, its own kind included — spends it to say what the word holds and
102 /// therefore which `#[ingraph::resource(…)]` declaration to write instead.
103 #[must_use]
104 pub const fn serves(self) -> NodeKind {
105 match self {
106 Self::Tantivy => NodeKind::Fulltext,
107 Self::Fs => NodeKind::Blob,
108 }
109 }
110
111 /// The CONDITIONAL-EXPANSION gate this engine's concrete impls ride — `if_tantivy`, reached on
112 /// `ingraph`'s `__private::gate` shelf.
113 ///
114 /// Mechanical from [`as_str`](Self::as_str), exactly as
115 /// [`DatabaseKind::gate`](crate::method) is: the word the declaration writes, the word the
116 /// framework's feature carries and the word the gate is named after are ONE word, so the three
117 /// cannot drift into naming different engines.
118 ///
119 /// This is the MEASURED mechanism of ruling 2, mirrored rather than reinvented. What it buys is
120 /// what it buys on the record side: a declaration naming two engines in a build carrying one is
121 /// bound to the one, and the other has no impl at all — `E0277` for a party that asks and silence
122 /// for one that does not.
123 ///
124 /// # [`None`] for an engine under no feature
125 ///
126 /// `fs` is at the root under nothing — *a backend that needs no feature having no gate to carry*,
127 /// which is `ingraph`'s own sentence about it — so there is no `if_fs` and a caller that wrapped
128 /// its impls in one would name a macro that does not exist. An engine with no feature is always
129 /// compiled in, which is the same answer the gate would have given, reached without inventing one.
130 #[must_use]
131 pub fn gate(self) -> Option<syn::Ident> {
132 match self {
133 Self::Tantivy => Some(format_ident!("if_{}", self.as_str())),
134 Self::Fs => None,
135 }
136 }
137
138 /// The word, if it is a shipped one.
139 #[must_use]
140 pub fn of(word: &syn::Ident) -> Option<Self> {
141 Self::ALL.into_iter().find(|kind| word == kind.as_str())
142 }
143}
144
145/// THE FROM-ROAD one engine block declares: how the elected field's value becomes THIS engine's
146/// document text.
147///
148/// # `from` and no `into`, and the direction law is why
149///
150/// *`from` BUILDS the projection a block is about* — here, the document. There is no `into` leg and
151/// there is not going to be one: a document is written and searched, never hydrated back into the
152/// domain. What a hit hands back is an ADDRESS, and that pair does round-trip, which is the axis
153/// this one deliberately lacks.
154///
155/// # The shorthands are a SEAM, not a closed pair
156///
157/// `join` and `multi` are the two the framework ships because they are the two loops a converter is
158/// otherwise written out as, and they differ in the one thing the declaration is about: whether a
159/// phrase may match ACROSS two values. A third builtin arrives as a variant here and an arm in the
160/// walk — no grammar change, because the position it is written in already exists.
161///
162/// # Per ENGINE BLOCK, and it could not be per field
163///
164/// The segmentation means different things to different engines: a positional one puts a gap
165/// between segments, and a single-text-column face has to flatten them — so one converter indexes
166/// correctly in the first and subtly wrongly in the second, both "working" and only the results
167/// differing. A field-level, engine-agnostic road is therefore not expressible, which is what puts
168/// this member on the block rather than beside the election.
169#[derive(Debug, Clone, Default, PartialEq, Eq)]
170pub enum Road {
171 /// NOTHING was declared — the IDENTITY road, the field's value being the document text as it
172 /// stands.
173 ///
174 /// The default, and the one that can REFUSE: whether a value is text at all is not a question a
175 /// front end can answer, so it is asked as a BOUND at the expansion and the refusal lands on the
176 /// field's own type token. See `ingraph`'s `Searchable`.
177 #[default]
178 Identity,
179 /// `join = "<sep>"` — ONE segment, the values written into it with the separator between them. A
180 /// phrase CAN match across two values.
181 Join(syn::LitStr),
182 /// `multi` — ONE SEGMENT PER VALUE. A phrase CANNOT match across two of them.
183 Multi,
184 /// `from = "…"` / `try_from = "…"` — the conversion the declaration NAMED, in the SHIPPED family
185 /// every other crossing in this grammar is written in.
186 ///
187 /// [`Conversion::Default`](crate::model::Conversion::Default) never reaches here: a block that
188 /// named no function took [`Identity`](Self::Identity), which is a different road rather than a
189 /// missing one.
190 Declared(crate::model::Conversion),
191}
192
193impl Road {
194 /// Whether the block wrote a road at all, or took the identity one by saying nothing.
195 #[must_use]
196 pub const fn declared(&self) -> bool {
197 !matches!(self, Self::Identity)
198 }
199
200 /// Whether this road can FAIL — the one bit that decides the emitted slot's error type.
201 ///
202 /// Only a declared `try_from` can: the identity road pushes what it was handed, and both
203 /// shorthands are loops over that.
204 #[must_use]
205 pub const fn fallible(&self) -> bool {
206 match self {
207 Self::Declared(conversion) => conversion.fallible(),
208 Self::Identity | Self::Join(_) | Self::Multi => false,
209 }
210 }
211
212 /// The WORD a refusal names this road by.
213 #[must_use]
214 pub const fn word(&self) -> &'static str {
215 match self {
216 Self::Identity => "identity",
217 Self::Join(_) => "join",
218 Self::Multi => "multi",
219 Self::Declared(_) => "from",
220 }
221 }
222}
223
224/// ONE engine block as a field declared it — the word, and whatever it carried.
225#[derive(Debug, Clone)]
226pub struct Engine {
227 /// The word, carrying its own span — where every refusal about this block lands.
228 pub word: syn::Ident,
229 /// The FROM-ROAD this block declares — [`Road::Identity`] where it declared none.
230 pub road: Road,
231 /// `stored` — this engine KEEPS the original value, retrievable.
232 ///
233 /// `false` unless the word was written, and the cheap default is the ruled one: only the computed
234 /// result is guaranteed SEARCHABLE, and retrieval is opt-in. What it reaches in the shipped engine
235 /// is tantivy's `STORED` flag on the body field.
236 pub stored: bool,
237 /// `resource = "path::To::Resource"` — the RESOURCE this leg is written to, as the declaration
238 /// POINTED at it.
239 ///
240 /// # It POINTS; it does not TYPE. `type =` retired to get here
241 ///
242 /// The word this replaces named an ENGINE directly, which put the kind of a store in two places:
243 /// on the declaration that wrote the type, and on whatever the deployment actually opened. **Kind
244 /// is said once, at the resource** — `#[ingraph::resource(tantivy)] pub struct Ft;` — and every
245 /// other position POINTS at that declaration. So what a leg holds is the path of a resource, and
246 /// the engine underneath it is the resource's own business.
247 ///
248 /// # What POINTING buys that TYPING did not
249 ///
250 /// A slot's package still publishes knobs in the store's own currencies — a floor is a
251 /// `<Ft as FulltextEngine>::Score` and a search input is that store's own — and the projection is
252 /// unchanged in shape: it simply runs off the RESOURCE type rather than off an engine type.
253 /// Two facts come free with the move:
254 ///
255 /// - the KIND CHECK is the projection itself. `<Ft as FulltextEngine>::Score` is `E0277` at the
256 /// path the author wrote when `Ft` is a vector resource, so *named → kind-verified* needs no
257 /// marker trait and no check anyone can forget to run;
258 /// - two resources of ONE KIND are two TYPES and therefore two `TypeId`s, which is what lets a
259 /// deployment run two stores of the same engine and keeps a door citizen's `Shared<R>` lookup
260 /// unambiguous. A word bound to a type could not say that.
261 ///
262 /// # [`None`] is the ordinary state, and it is the SOLE-DEFAULT's condition
263 ///
264 /// An unpointed leg contributes no variant and a slot whose legs are all unpointed grows no
265 /// `engine` seat at all — the presence law, unchanged. What is new is that saying nothing is no
266 /// longer only a fallback: a deployment declaring exactly ONE resource of this leg's kind binds
267 /// it by that fact alone, and zero or several is a START-UP refusal listing the candidates. See
268 /// the binding laws on [`FieldEngines`].
269 ///
270 /// REFER-QUOTED, so the path resolves at the span its author wrote and a path naming nothing is
271 /// `E0412` there rather than inside an expansion.
272 pub resource: Option<syn::Path>,
273 /// The block's contents, UNINTERPRETED, and empty where the word was written bare.
274 ///
275 /// # Verbatim, and it could not be otherwise
276 ///
277 /// `hnsw(ef = 200)` names a knob of an engine this crate has never heard of. Reading it would mean
278 /// carrying every engine's option set here — the maintenance an open vocabulary exists to avoid —
279 /// and refusing what it could not read would close the vocabulary through the back door. So the
280 /// tokens are carried to the binding and interpreted by whoever owns the engine, which is the same
281 /// division the framework already draws around a backend's own words.
282 ///
283 /// A [`proc_macro2::TokenStream`] rather than parsed pairs, therefore, and the spans inside it are
284 /// the author's own — so an engine that refuses one of its knobs refuses it where it was written.
285 ///
286 /// # It is the block MINUS the framework's own words, and that is not a hole in the argument
287 ///
288 /// [`road`](Self::road) and [`stored`](Self::stored) are written inside these parentheses and are
289 /// taken out of what is carried. The division is the same one the outer walk already draws: a
290 /// FRAMEWORK word has one meaning wherever it appears, and an engine's knob has whatever meaning
291 /// its engine gives it. Reading `ef = 200` would mean carrying every engine's option set here;
292 /// reading `stored` means carrying one word whose meaning the framework defines, and whose whole
293 /// point is that it means the same thing to every engine that has a doc store.
294 ///
295 /// The price is stated rather than hidden: an engine with a knob of its own called `stored`,
296 /// `join`, `multi`, `from`, `try_from`, `resource` or `lanes` cannot spell it here, because the
297 /// framework claimed the spelling first. That is the ordinary cost of a shared namespace, and it
298 /// is bounded by seven words.
299 pub options: proc_macro2::TokenStream,
300 /// `rrf = <bool>` — whether this leg enters the FUSED ROAD of the slot it holds.
301 ///
302 /// # It is LEADERBOARD MEMBERSHIP and nothing else
303 ///
304 /// A fanned slot writes every declared engine at once. What that fan is FOR is two different
305 /// things and the declaration could not say which: a leaderboard, where each engine's ranking is
306 /// separate evidence and the fold joins them; or REDUNDANCY, where the same content lives in
307 /// several stores and a read comes from one of them. `rrf = false` is the second — the leg is
308 /// written and is not a route.
309 ///
310 /// # TRUE by absence, per the de-Option law
311 ///
312 /// A `bool` rather than an `Option<bool>`: there is no third state. The default is the shape a
313 /// fan already had before the word existed, so a declaration that says nothing keeps exactly the
314 /// slot it had — which is what makes the word purely additive.
315 ///
316 /// # ORTHOGONAL to [`resource`](Self::resource), and all four quadrants mean something
317 ///
318 /// `resource =` is ADDRESSABILITY (and the `Score` projection a package publishes floors in);
319 /// `rrf =` is leaderboard membership. A pointed leg outside the leaderboard is directly readable
320 /// and does not rank; an unpointed leg inside it ranks and cannot be named by a request; a leg
321 /// that is neither is written for redundancy alone.
322 pub rrf: bool,
323 /// `lanes(zh(accepts(cmn)), en, rest(catch_all))` — the PARTITIONS this leg's corpus is cut into,
324 /// in declaration order, and EMPTY where the word was not written.
325 ///
326 /// # Presence is the whole state, and absence is the corpus that always was
327 ///
328 /// An empty list is a declaration that said nothing about lanes, and what it mints is nothing: the
329 /// slot takes [`Lanes`](../../ingraph/trait.Lanes.html)' own default, which is ONE lane keyed
330 /// `und`. So the word is purely additive — a leg that never wrote it emits, indexes and answers
331 /// exactly as it did before the word existed.
332 ///
333 /// # The KEY and the ALIASES are read; the ANALYZER is not here
334 ///
335 /// A lane's EXISTENCE shapes the slot, so it is a compile-time fact and this grammar reads it. Its
336 /// INSTANCE is a value a deployment builds at boot, so a `tokenizer = "…"` written inside a lane
337 /// is the ENGINE's knob and rides [`options`](Self::options) with every other one — the same
338 /// partition the block around it already draws, one grain down. That division is the ruling's own:
339 /// *a lane's existence is a declaration fact, its instance an assembly one.*
340 pub lanes: Vec<DeclaredLane>,
341}
342
343/// ONE LANE, as a `lanes(…)` block wrote it — the framework's half of one entry.
344///
345/// The engine's half of the same entry is NOT here: it is carried verbatim into
346/// [`Engine::options`], because a lane's analyzer is a word only the backend reads.
347#[derive(Debug, Clone, PartialEq, Eq)]
348pub struct DeclaredLane {
349 /// The lane's KEY, carrying its own span — where a refusal about this lane lands, and the one word
350 /// the gate ever hands back.
351 pub key: syn::Ident,
352 /// `accepts(…)` — the tags this lane answers beside its own key, in the order they were written.
353 pub accepts: Vec<syn::Ident>,
354 /// `catch_all` — the WORD itself where it was written, so a refusal about a SECOND catch-all lands
355 /// on the second one rather than on the roster.
356 pub catch_all: Option<syn::Ident>,
357}
358
359impl DeclaredLane {
360 /// A lane keyed `key`, accepting nothing and catching nothing — the bare `zh` entry.
361 #[must_use]
362 pub fn of(key: syn::Ident) -> Self {
363 Self {
364 key,
365 accepts: Vec::new(),
366 catch_all: None,
367 }
368 }
369
370 /// Every WORD this lane claims — its key first, then its aliases.
371 ///
372 /// That order is not a preference: it is the order
373 /// [`lane_claim`](../../ingraph/fn.lane_claim.html) addresses a roster's flat claim positions in,
374 /// and the emitted per-word assertions are counted out against those positions. Two orders would
375 /// put a refusal's sentence on the wrong word.
376 pub fn claims(&self) -> impl Iterator<Item = &syn::Ident> {
377 core::iter::once(&self.key).chain(self.accepts.iter())
378 }
379}
380
381impl Engine {
382 /// A block written BARE — `tantivy` with no parentheses at all.
383 ///
384 /// The most common shape by far, and the one every default is defined against: the identity road,
385 /// nothing kept, NOTHING POINTED AT, no knobs carried, no lanes cut, and IN the fused road. A named
386 /// constructor rather than a [`Default`], because the WORD is not defaultable and a partial default
387 /// would be the thing that quietly disagrees with the grammar when an eighth framework word
388 /// arrives.
389 #[must_use]
390 pub fn bare(word: syn::Ident) -> Self {
391 Self {
392 word,
393 road: Road::Identity,
394 stored: false,
395 resource: None,
396 options: proc_macro2::TokenStream::new(),
397 rrf: true,
398 lanes: Vec::new(),
399 }
400 }
401
402 /// The shipped engine this word names, or [`None`] for a word bound at the graph root.
403 #[must_use]
404 pub fn shipped(&self) -> Option<EngineKind> {
405 EngineKind::of(&self.word)
406 }
407}
408
409/// ONE `engines(<word> = "path::To::Engine")` entry on a graph root — a WORD bound to a CONCRETE
410/// TYPE.
411///
412/// # Why the binding is at the ROOT and not on the declaration
413///
414/// A word on a field is a NAME, and a name is bound where the program is assembled. Writing the path
415/// on the declaration would bind it there — in a library crate that cannot know which engine the
416/// application compiled, and cannot be re-pointed without editing the declaration. The root is the
417/// one place that knows: it is the deployment's whole catalog already, and the same list the
418/// resources are read off.
419///
420/// It is REFER-QUOTED for this grammar's standing reason: a word that points at something written
421/// elsewhere is written in a string literal, so the path resolves at the span its author wrote.
422///
423/// # What it emits: the compile-time MEMBER TABLE
424///
425/// One marker type per bound word, carrying the concrete engine as an associated type. That table is
426/// what a fused face reads to know which engines a query fans across, and it is a TYPE-level table
427/// rather than a runtime map for the reason every other binding here is: a member resolved by name
428/// at run time is a member no signature can be written against.
429#[derive(Debug, Clone)]
430pub struct EngineBinding {
431 /// The WORD, exactly as a field would spell it.
432 pub word: syn::Ident,
433 /// The CONCRETE engine type, carried VERBATIM and resolved nowhere in this crate.
434 ///
435 /// The tokens are the author's own — respanned onto the string literal that named them — so a path
436 /// naming nothing is `E0412` where it was written, which is the division every referring word in
437 /// this grammar is under.
438 pub engine: syn::Path,
439}
440
441impl EngineBinding {
442 /// The ZERO-SIZED TYPE this binding is carried as — `<Root>Engine<Word>`.
443 #[must_use]
444 pub fn marker(&self, root: &syn::Ident) -> syn::Ident {
445 use heck::ToUpperCamelCase as _;
446
447 format_ident!(
448 "{root}Engine{}",
449 self.word.to_string().to_upper_camel_case()
450 )
451 }
452}
453
454/// ONE elected field's engines, and whether all of them are live at once.
455#[derive(Debug, Clone)]
456pub struct FieldEngines {
457 /// The field these engines hold — one of the declaration's own elections.
458 pub field: syn::Ident,
459 /// The engines, in the order they were WRITTEN.
460 ///
461 /// Order is kept for [`Persist::backends`](crate::model::Persist)' reason: the slots emit in the
462 /// order the author wrote them, so an expansion is stable and diffable. It may be EMPTY — an
463 /// election that named no engine is a declaration that has not said where its index lives, which
464 /// is legal and means the deployment says instead.
465 pub engines: Vec<Engine>,
466 /// `fanout` — ALL declared engines simultaneously live.
467 ///
468 /// # What the marker changes, and what it deliberately does not
469 ///
470 /// Without it the blocks are PORTABILITY: the deployment opens one slot and writes through it,
471 /// which is the record side's *declare many, build one* inherited whole. With it every declared
472 /// engine's slot is live at once — the write lane fans to all of them, and the per-engine rankings
473 /// enter FUSION as separate evidence on the way back.
474 ///
475 /// R2 builds the WRITE half and RECORDS the read half. The read side's fan-and-fuse is the face
476 /// round's to consume, and it is recorded rather than sketched for the reason this crate refuses
477 /// every other promise: a word parsed into a model nothing spends is a promise rather than a rule.
478 /// What is spent today is the write, and it is spent completely.
479 ///
480 /// On a field with FEWER THAN TWO engines the marker is a named refusal — there is nothing to fan.
481 pub fanout: bool,
482}
483
484impl FieldEngines {
485 /// The legs that ENTER this field's fused road — the `rrf` half of a fanned slot's declaration.
486 ///
487 /// Read wherever a fanned slot's mini tier is shaped: the `Route` seats it carries, the evidence
488 /// variants a fold can produce, and whether the mini fuse door emits at all. Every leg still
489 /// WRITES — that half is [`fanout`](Self::fanout)'s and this word does not touch it.
490 pub fn participants(&self) -> impl Iterator<Item = &Engine> {
491 self.engines.iter().filter(|engine| engine.rrf)
492 }
493
494 /// The SLOTS this field declares — one per engine.
495 #[must_use]
496 pub fn slots(&self) -> Vec<Slot> {
497 self
498 .engines
499 .iter()
500 .map(|engine| Slot {
501 field: self.field.clone(),
502 engine: engine.word.clone(),
503 })
504 .collect()
505 }
506}
507
508/// ONE SLOT: a field and the engine that holds it.
509///
510/// # Slot identity moved, and this type is the move
511///
512/// It used to be the DECLARATION — one `FulltextTable::SLOT` per index, and *one declaration, one
513/// slot* was the keystone the brand rested on. Under the engine grammar it is `(field × engine)`,
514/// and the per-slot laws follow it there: ONE Tantivy index per slot, because BM25's corpus
515/// statistics are index-wide, is now one index per `(field, engine)` — which is what makes two
516/// fields of one declaration searchable independently without their scores moving under each other.
517///
518/// The COLUMN axis is unchanged and is one grain finer: a vector slot may still hold several
519/// columns, and `VectorColumn` still says which one a knn runs over. What this type adds is the axis
520/// above it, not a replacement for the one below.
521#[derive(Debug, Clone, PartialEq, Eq)]
522pub struct Slot {
523 /// The elected field.
524 pub field: syn::Ident,
525 /// The engine word — as WRITTEN, since a free word has no other spelling.
526 pub engine: syn::Ident,
527}
528
529impl Slot {
530 /// This slot's durable NAME, as the emission mints it: `<index>__<field>__<engine>`.
531 ///
532 /// # Why all three parts, and why the double underscore
533 ///
534 /// A slot name reaches a directory, a table or a virtual table, so two slots sharing one is two
535 /// declarations sharing a corpus — the exact class the brand exists to keep out. All three parts
536 /// are therefore in the name: two indexes may declare a field of the same name, and one field may
537 /// name several engines.
538 ///
539 /// The separator is `__` because a single one is legal INSIDE each part — `image_embedding` is a field
540 /// name — so a single-underscore join would let `a_b` × `c` and `a` × `b_c` mint one name. It is
541 /// not the framework's `__…__` fence: that reservation is *both ends*, and this name has neither.
542 ///
543 /// SNAKE CASE from the index's own name, which is the convention
544 /// [`RecordModel::table_name`](crate::model::RecordModel::table_name) already defaults a table to
545 /// — one convention for every durable name a declaration mints.
546 #[must_use]
547 pub fn name(&self, index: &syn::Ident) -> String {
548 use heck::ToSnakeCase as _;
549
550 format!(
551 "{}__{}__{}",
552 index.to_string().to_snake_case(),
553 self.field,
554 self.engine,
555 )
556 }
557
558 /// The ZERO-SIZED TYPE this slot is carried as — `<Index><Field><Engine>`.
559 ///
560 /// A TYPE and not a name, for the reason the election markers are types: a handle branded with a
561 /// slot cannot be handed to another slot's door, and a brand is a fact carried through the types.
562 /// A `SlotName` alone would put the pairing back in a value, where a swap is a runtime mistake
563 /// nobody sees.
564 #[must_use]
565 pub fn marker(&self, index: &syn::Ident) -> syn::Ident {
566 use heck::ToUpperCamelCase as _;
567
568 format_ident!(
569 "{index}{}{}",
570 self.field.to_string().to_upper_camel_case(),
571 self.engine.to_string().to_upper_camel_case(),
572 )
573 }
574}
575
576#[cfg(test)]
577mod tests;