Skip to main content

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;