ingraph 0.1.0

A declaration-driven indexing framework: records and nodes are written as Rust types, and the storage rows, the dataflow between them and the GraphQL query surface are emitted from the declaration.
Documentation
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
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
//! THE HABITAT: what one storage target's HOME for a declared type looks like — [`Habitat`], the
//! kind-level vocabulary, and the three minimal blueprints the engine kinds describe themselves in.
//!
//! ```text
//! target                     Habitat::Blueprint         what it describes
//! ─────────────────────────────────────────────────────────────────────────────────────
//! sqlx::Sqlite / …           Table                      one node's table, its columns, its edges
//! a full-text resource       &'static [SlotSchema]      the corpora that declaration owns there
//! a vector resource          &'static [SlotSpec]        the same, with the width a coordinate has
//! a blob resource            &'static [Layout]          the buckets a family's artifacts go in
//! ```
//!
//! # Why the blueprint is an ASSOCIATED TYPE and not one struct with four arms
//!
//! A record's home is a TABLE and a full-text election's home is a CORPUS, and the two share no
//! member: a table has a primary key and no tokenizer, a corpus has a text posture and no columns to
//! order by. An enum over the four would make every visitor match on three arms it cannot serve, and
//! would put a fifth kind's arrival in this file rather than in the module that owns that kind's
//! face. So the vocabulary is the TARGET's own answer, and the walk that hands it over names
//! [`Describe`](crate::Describe) alone.
//!
//! # The blueprints are the DERIVATION HALF, and nothing here is an author's knob
//!
//! Everything in this module is `const`-constructible and derived from a DECLARATION: a corpus's
//! durable name, the columns an election put in it, the posture its `stored` word chose. What a
//! deployment TUNES — a tokenizer, an HNSW's `ef`, a bucket's storage class — is not here and
//! deliberately: those are per-slot VALUES, they arrive at boot rather than at compile time, and a
//! `const` is exactly the wrong place for a value a document decides. They live on the VISITOR, in
//! its own per-slot table, whose value type is the projection of the engine's
//! [`Options`](crate::FulltextEngine::Options) seat — see
//! [`TantivySlotMaker`](crate::TantivySlotMaker), which is the first one built.
//!
//! That split is what keeps a blueprint an ITEM: a descriptor built per boot is a schema that could
//! differ between two of them, which is [`Table`](crate::Table)'s own argument one module over.
//!
//! # Per TARGET, and NEVER a blanket
//!
//! Every impl of [`Habitat`] names one concrete target. There is no blanket over a kind trait, and
//! the reason is measured rather than stylistic: one connection-manager may answer two seams — a
//! store with both a full-text and a vector extension is one type wearing two mount faces — so a
//! blanket per kind would give that type two `Habitat` impls and `E0119`. A target states its
//! blueprint once, in the module that knows it.

use crate::{ColumnDoor, slot::SlotName};

/// A storage TARGET's kind-level vocabulary: what a declared type's home in it looks like.
///
/// # Who implements it
///
/// The framework, for the SQL dialects it ships a schema lane for; `#[ingraph::resource(<word>)]`,
/// for the builtin engines whose kind the word carries; and a FOREIGN resource's author, in one
/// line, which is the open seam's usual price.
///
/// # The parameter position it takes
///
/// [`Describe<T>`](crate::Describe) names it, so `T` is what a node's self-description is stated
/// AGAINST and [`Blueprint`](Self::Blueprint) is what that description IS. A visitor's
/// [`Db`](crate::TypeVisitor::Db) is bound by it for the same reason: a walk hands a visitor one
/// blueprint per node, and a target that has not said what a blueprint is has nothing to hand.
///
/// # Examples
///
/// A hand-written target whose homes are corpora:
///
/// ```
/// use ingraph::{Describe, Habitat, SlotColumn, SlotSchema, SlotName};
///
/// struct Corpora;
///
/// impl Habitat for Corpora {
///   type Blueprint = &'static [SlotSchema];
/// }
///
/// struct Media;
///
/// impl Describe<Corpora> for Media {
///   const BLUEPRINT: &'static [SlotSchema] = &[SlotSchema::new(
///     SlotName::new("media__title__lexical"),
///     &[SlotColumn::text("title")],
///   )];
/// }
///
/// assert_eq!(<Media as Describe<Corpora>>::BLUEPRINT.len(), 1);
/// ```
pub trait Habitat {
  /// What ONE declared type's home in this target looks like.
  ///
  /// Unbounded, for the reason [`TypeVisitor::Db`](crate::TypeVisitor::Db) used to be: what a
  /// blueprint must BE is the KIND's question and the kinds disagree, so it is asked where the
  /// target is written rather than on the vocabulary every target answers.
  type Blueprint;
}

/// ONE COLUMN of an engine-backed slot: the name a declaration elected, and the DOOR of the column
/// language its values cross by.
///
/// # Why the door and not a stored TYPE
///
/// A [`Column`](crate::Column) carries the word THIS DATABASE stores it at — `INTEGER`, `int8`,
/// `BIGINT` — because a SQL dialect's storage classes are the dialect's own and a `CREATE TABLE`
/// writes one of them verbatim. An engine has no such text: what crosses a full-text or a vector
/// seam is TYPED COLUMNS, through [`ColumnWriter`](crate::ColumnWriter) and
/// [`ColumnReader`](crate::ColumnReader), and [`ColumnDoor`] is that language's own closed
/// vocabulary — one variant per method. So the two families state the same fact in the two
/// vocabularies their backends actually read.
///
/// It is also the vocabulary the CONFORMANCE walk already reports splits in, which is what makes a
/// blueprint's column and a round trip's diagnosis nameable in one word.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
pub struct SlotColumn {
  name: &'static str,
  door: ColumnDoor,
}

impl SlotColumn {
  /// The column `name`, whose values cross by `door`.
  #[inline]
  #[must_use]
  pub const fn new(name: &'static str, door: ColumnDoor) -> Self {
    Self { name, door }
  }

  /// A TEXT column — what every `searchable` election mints, this family's values being text by the
  /// road that built them.
  #[inline]
  #[must_use]
  pub const fn text(name: &'static str) -> Self {
    Self::new(name, ColumnDoor::Text)
  }

  /// The column's name, as the declaration spelled the field.
  #[inline]
  #[must_use]
  pub const fn name(&self) -> &'static str {
    self.name
  }

  /// Which door of the column language its values cross by.
  #[inline]
  #[must_use]
  pub const fn door(&self) -> ColumnDoor {
    self.door
  }
}

/// ONE FULL-TEXT CORPUS, as a declaration describes it: its durable name, the columns it holds, and
/// whether the engine KEEPS what it indexed.
///
/// # It carries the NAME, exactly as [`Table`](crate::Table) does
///
/// A table's descriptor leads with its [`address`](crate::Table::address) because a `CREATE TABLE`
/// has to name something, and a slot maker is in the same position: a corpus is a directory, a
/// virtual table or an index, and creating one is creating it UNDER A NAME. The name is the
/// declaration's own — `<index>__<field>__<label>`, or whatever a `slot = "…"` wrote instead — so
/// the corpus a walk creates and the corpus a read opens have ONE home.
///
/// # The `stored` posture is the TEXT SEAT, and it is the only knob-shaped thing here
///
/// It is not a knob: it is a fact the DECLARATION states with the `stored` word, which means the
/// same thing to every engine that has a doc store — the text is retrievable beside what was
/// indexed. What a backend does with it is the backend's ([`FulltextRoad::STORED`] is where the word
/// is read), and what varies per DEPLOYMENT — the analyzer, the tokenizer — is not here at all. See
/// the module note for where that half lives.
///
/// [`FulltextRoad::STORED`]: crate::FulltextRoad::STORED
///
/// # Examples
///
/// ```
/// use ingraph::{SlotColumn, SlotName, SlotSchema};
///
/// const TITLE: SlotSchema = SlotSchema::new(
///   SlotName::new("media__title__lexical"),
///   &[SlotColumn::text("title")],
/// );
///
/// assert_eq!(TITLE.slot().as_ref(), "media__title__lexical");
/// assert!(!TITLE.is_stored());
/// assert!(TITLE.keeping().is_stored());
/// ```
#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
pub struct SlotSchema {
  slot: &'static SlotName,
  columns: &'static [SlotColumn],
  stored: bool,
  lanes: &'static [crate::Lane],
}

/// The roster a corpus that declared no fan holds — [`Lanes::LANES`](crate::Lanes::LANES)'s own
/// default, at the one other place the same fact is read.
///
/// It is not a SECOND home for a roster. A declaration that DID cut its corpus writes a `Lanes` impl
/// and the emission carries THAT impl's const into the row through [`fanned`](SlotSchema::fanned),
/// so the two cannot come to disagree; what this constant answers is the corpus that said nothing,
/// where both sides are the unfanned one by construction.
const UNFANNED: &[crate::Lane] = &[crate::Lane::of(crate::LaneIdent::UND)];

impl SlotSchema {
  /// The corpus `slot` names, holding `columns`, indexed and NOT kept.
  ///
  /// The cheap posture is the default for [`FulltextRoad::STORED`](crate::FulltextRoad::STORED)'s
  /// reason: what a full-text index promises is that the text is FINDABLE, and handing it back is a
  /// second promise paid for in bytes on every entry.
  ///
  /// UNFANNED, which is the zero-configuration corpus: one lane, keyed
  /// [`und`](crate::LaneIdent::UND). [`fanned`](Self::fanned) is what a declaration that cut its
  /// corpus into several writes instead.
  #[inline]
  #[must_use]
  pub const fn new(slot: &'static SlotName, columns: &'static [SlotColumn]) -> Self {
    Self {
      slot,
      columns,
      stored: false,
      lanes: UNFANNED,
    }
  }

  /// The same corpus with the indexed text KEPT — what a declaration's `stored` word asks for.
  #[inline]
  #[must_use]
  pub const fn keeping(mut self) -> Self {
    self.stored = true;
    self
  }

  /// **THE SAME CORPUS, CUT INTO `lanes`** — what a declaration's `lanes(…)` word asks for.
  ///
  /// # The roster is on the BLUEPRINT because the SLOT MAKER is what needs it
  ///
  /// A lane's EXISTENCE shapes the home: a fanned corpus is several analyzers, so the maker that
  /// creates it has to know how many partitions to shape it for. The maker is handed one of these
  /// rows and nothing else — it has no slot TYPE to project a [`Lanes`](crate::Lanes) impl off —
  /// so the roster travels here. That is the same fact and not a second one: the emission writes
  /// `.fanned(<Slot as Lanes>::LANES)`, so the row and the seam are one const read twice.
  ///
  /// What is still NOT here is the ANALYZER. A lane's tokenizer is a value a DEPLOYMENT decides at
  /// boot, so it arrives through [`Options`](crate::FulltextEngine::Options) on the visitor's own
  /// table — the split the module note draws, unchanged by this word.
  #[inline]
  #[must_use]
  pub const fn fanned(mut self, lanes: &'static [crate::Lane]) -> Self {
    self.lanes = lanes;
    self
  }

  /// The same corpus at the posture `stored` states — the shape an emission writes, which reads the
  /// declaration's word rather than choosing between two constructors.
  #[inline]
  #[must_use]
  pub const fn of(slot: &'static SlotName, columns: &'static [SlotColumn], stored: bool) -> Self {
    Self {
      slot,
      columns,
      stored,
      lanes: UNFANNED,
    }
  }

  /// The corpus's durable name — what the engine makes a directory, a table or an index out of.
  #[inline]
  #[must_use]
  pub const fn slot(&self) -> &'static SlotName {
    self.slot
  }

  /// The columns this corpus holds, in the order the declaration elected them.
  #[inline]
  #[must_use]
  pub const fn columns(&self) -> &'static [SlotColumn] {
    self.columns
  }

  /// Whether the engine keeps the indexed text, retrievable.
  #[inline]
  #[must_use]
  pub const fn is_stored(&self) -> bool {
    self.stored
  }

  /// The partitions this corpus is cut into — ONE unfanned lane where the declaration named none.
  #[inline]
  #[must_use]
  pub const fn lanes(&self) -> &'static [crate::Lane] {
    self.lanes
  }
}

/// ONE VECTOR CORPUS, as a declaration describes it — [`SlotSchema`]'s twin, one family over.
///
/// It differs in exactly the member the two per-slot factories differ in, and for the factories' own
/// reason: a coordinate corpus's WIDTH is a fact its storage cannot be shaped without —
/// [`VectorMount::corpus`](crate::VectorMount::corpus) takes it as a parameter and
/// [`VectorStore::vector`](crate::VectorStore::vector) beside it — where a document corpus has no
/// such number.
///
/// # Examples
///
/// ```
/// use ingraph::{ColumnDoor, SlotColumn, SlotName, SlotSpec};
///
/// const CLIP: SlotSpec = SlotSpec::new(
///   SlotName::new("shots__clip__hnsw"),
///   &[SlotColumn::new("clip", ColumnDoor::Bytes)],
///   768,
/// );
///
/// assert_eq!(CLIP.width(), 768);
/// ```
#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
pub struct SlotSpec {
  slot: &'static SlotName,
  columns: &'static [SlotColumn],
  width: usize,
}

impl SlotSpec {
  /// The corpus `slot` names, holding `columns` of `width`-wide coordinates.
  ///
  /// # A ZERO width is refused here
  ///
  /// A coordinate of no components is a point in no space: every distance over it is zero, so every
  /// query returns everything in insertion order. The refusal lands in a `const`, where the
  /// blueprint is written, which is the position every descriptor in this crate refuses from:
  ///
  /// ```compile_fail,E0080
  /// use ingraph::{SlotName, SlotSpec};
  ///
  /// const CLIP: SlotSpec = SlotSpec::new(SlotName::new("shots__clip__hnsw"), &[], 0);
  /// ```
  ///
  /// Its positive twin, since stable rustdoc runs a `compile_fail` block just far enough to see it
  /// fail and never checks why:
  ///
  /// ```
  /// use ingraph::{SlotName, SlotSpec};
  ///
  /// const CLIP: SlotSpec = SlotSpec::new(SlotName::new("shots__clip__hnsw"), &[], 8);
  /// assert_eq!(CLIP.width(), 8);
  /// ```
  #[must_use]
  pub const fn new(slot: &'static SlotName, columns: &'static [SlotColumn], width: usize) -> Self {
    assert!(
      width != 0,
      "a coordinate corpus is shaped by its width, and a vector of no components is a point in no \
       space"
    );
    Self {
      slot,
      columns,
      width,
    }
  }

  /// The corpus's durable name.
  #[inline]
  #[must_use]
  pub const fn slot(&self) -> &'static SlotName {
    self.slot
  }

  /// The columns this corpus holds.
  #[inline]
  #[must_use]
  pub const fn columns(&self) -> &'static [SlotColumn] {
    self.columns
  }

  /// How wide one coordinate is — the number a vector store's per-slot factory takes.
  #[inline]
  #[must_use]
  pub const fn width(&self) -> usize {
    self.width
  }
}

/// ONE ARTIFACT FAMILY's home — the bucket, directory or key prefix a declaration's blobs go in.
///
/// # It holds a NAME and nothing else, and that is a measurement
///
/// The shipped blob store addresses an artifact by the key's own segments under the slot's directory
/// ([`blob_address`](crate::blob_address)), so everything about WHERE one lands is derived from the
/// key and the slot — there is no column list to declare and no width to state. What a second
/// backend adds (a storage class, a retention, a content type) joins this type when that backend
/// does, which is the same discipline every other descriptor here is under: a member with no reader
/// is a promise rather than a fact.
///
/// # Examples
///
/// ```
/// use ingraph::{Describe, Habitat, Layout, SlotName};
///
/// struct Buckets;
///
/// impl Habitat for Buckets {
///   type Blueprint = &'static [Layout];
/// }
///
/// struct Thumbnails;
///
/// impl Describe<Buckets> for Thumbnails {
///   const BLUEPRINT: &'static [Layout] = &[Layout::new(SlotName::new("thumbnails"))];
/// }
///
/// assert_eq!(
///   <Thumbnails as Describe<Buckets>>::BLUEPRINT[0].slot().as_ref(),
///   "thumbnails"
/// );
/// ```
#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
pub struct Layout {
  slot: &'static SlotName,
}

impl Layout {
  /// The family `slot` names.
  #[inline]
  #[must_use]
  pub const fn new(slot: &'static SlotName) -> Self {
    Self { slot }
  }

  /// The family's durable name — what the store makes a directory or a key prefix out of.
  #[inline]
  #[must_use]
  pub const fn slot(&self) -> &'static SlotName {
    self.slot
  }
}

#[cfg(test)]
mod tests;