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
//! [`Slot`] — WHICH CORPUS a declaration's elected field is written to, as a type.

use crate::slot::SlotName;

/// ONE SLOT of a declaration: an elected field, and the engine that holds it.
///
/// A derived index's expansion emits one zero-sized type per `(elected field × declared engine)` and
/// implements this on it. Nothing implements it by hand, and the trait is public because a
/// deployment NAMES one: opening a handle is `SlotHandle<E, ThatSlot>`, so the marker has to be
/// spellable wherever the handle is opened.
///
/// # Why slot identity is the PAIR, and what moved to get here
///
/// It used to be the declaration — one name per index, and *one declaration, one slot* was the law
/// the brand rested on. The engine grammar re-keys it, because a declaration may now name several
/// engines and a deployment may run more than one of them at once. Both halves are load-bearing:
///
/// - the FIELD, because the per-slot laws are per-corpus. ONE Tantivy index per slot is BM25's
///   own arithmetic — `docfreq` over `numdocs`, and the length normalization's average — and those
///   statistics are index-wide, so two fields sharing one index move each other's scores. Splitting
///   by field is what lets a title and a body be searched independently.
/// - the ENGINE, because two engines holding one field are two corpora with nothing in common. A
///   name shared between them would have one engine's write land in the other's store, which is the
///   wrong-write class the brand exists for.
///
/// The COLUMN axis is one grain FINER and is untouched: a vector slot may hold several columns, and
/// [`VectorColumn`](super::VectorColumn) still says which one a knn runs over. This is the axis
/// above it, not a replacement for the one below.
///
/// # It NAMES the pairing; it does not open it
///
/// Every constant here is a fact of the DECLARATION, so they exist in every build — including a
/// build that compiled no engine at all. What such a build does not have is the engine to open the
/// slot ON, which is the seam's own refusal and not this one's.
pub trait Slot {
  /// The DECLARATION this slot belongs to.
  ///
  /// Carried so a door may demand the pairing rather than take it on trust: a signature written
  /// `S: Slot<Of = Self>` admits this declaration's slots and refuses another's by name, which is
  /// the brand's guarantee stated where a caller can read it.
  ///
  /// `?Sized`, because a declaration is only ever NAMED here.
  type Of: ?Sized;

  /// The slot's durable NAME — what the engine makes a directory, a table or an index out of.
  ///
  /// `E0080` at the declaration for a malformed one: see [`SlotName::new`].
  const SLOT: &'static SlotName;

  /// The ELECTED FIELD this slot holds, as the declaration spelled it.
  const FIELD: &'static str;

  /// The ENGINE WORD this slot is written to, as the declaration spelled it.
  ///
  /// The WORD rather than the engine type, and the asymmetry is the grammar's: an engine word is
  /// bound to a concrete type by the deployment — shipped words under their own feature, everyone
  /// else's at the graph root — and a slot is a fact of the declaration, which is written long
  /// before any of that is decided.
  const ENGINE: &'static str;
}

/// ONE ROW OF THE MEMBER TABLE: an engine WORD a graph root bound, and the type it named.
///
/// A root's `engines(hnsw = "app::hnsw::Hnsw")` emits one zero-sized type per entry and implements
/// this on it. Nothing implements it by hand.
///
/// # What the table is FOR
///
/// A field names its engines by WORD, because a declaration is written before any deployment exists
/// and a path written there would bind the engine in a library that cannot know which one an
/// application compiled. The root is where the program is assembled, so the root is where a word
/// becomes a type — and this trait is the join, at COMPILE time rather than through a runtime map,
/// because a member resolved by name at run time is a member no signature can be written against.
///
/// # A SHIPPED word is not bound here
///
/// `tantivy` self-binds under `feature = "tantivy"`, exactly as `postgres` does one family over: the
/// framework knows the type, so the deployment says only whether it compiled it. Binding a shipped
/// word at a root is refused by name — one word with two meanings in one program is the collision
/// this table exists to make impossible.
#[diagnostic::on_unimplemented(
  message = "`{Self}` is not a bound engine word",
  label = "no `engines(…)` entry binds this word",
  note = "an engine a field names by word is bound at the GRAPH ROOT — \
          `#[ingraph::graph(engines(<word> = \"path::To::Engine\"))]` — and a word the framework \
          ships binds itself under its own feature instead"
)]
pub trait Bound {
  /// The CONCRETE engine the word names.
  ///
  /// Unbounded, for the reason every backend-facing associated type in this module is: what an
  /// engine must BE is the seam's question, and the seams are two — a full-text engine and a vector
  /// one — so naming either here would bind the table to one family.
  type Engine;

  /// The WORD, as the root and the fields both spell it.
  ///
  /// Carried so the two halves can be checked against each other rather than trusted: a slot's
  /// [`Slot::ENGINE`] and the table's `WORD` are the same string when the join is right.
  const WORD: &'static str;
}

#[cfg(test)]
mod tests;