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
//! 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 crate::Embedding;

#[cfg(test)]
mod tests;

/// 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.
#[rustfmt::skip]
#[diagnostic::on_unimplemented(
  message = "`{Self}` is not a field a knn can run over",
  label = "not an embedding field",
  note = "an elected field holds coordinates: `Embedding<E, N>`, or `Embedding<E, N, S>` where it names the SPACE its coordinates live in. A field holding a SET of them is a carrier over that type — `Vec<Embedding<E, N>>` is the one this framework ships — and its label is `list(embedding)`",
  note = "the FIXED-SIZE form `[Embedding<E, N>; K]` has its seat RESERVED and no implementation: nothing here reads a constant length yet, and accepting it now would make a promise about a constant nobody has asked to be kept. Write the variable form, whose length is a fact about each entity",
  note = "a carrier this framework does not ship joins by implementing `EmbeddingMarker` for itself — the trait is open, and one impl is the whole of it"
)]
pub trait EmbeddingMarker {
  /// The EMBEDDING this field carries — one authority for every fact about the coordinates.
  ///
  /// `Embedding<E, N, S>` for both of the framework's own rows, [`Self`] being that type in the
  /// [`One`] case. A carrier names the type it holds and states nothing else about it: the element,
  /// the width and the space are read off this through [`EmbeddingShape`], so a carrier has no
  /// second place to restate one of them and no way to restate it differently.
  type Item: EmbeddingShape;

  /// ONE embedding or a SET of them — see [`Multiplicity`], whose vocabulary is closed to those two.
  ///
  /// It is what an emission spends: a [`Set`] field is reported under an ordinal and grows the
  /// set-similarity door, a [`One`] field is reported as it always was and does not.
  type Multiplicity: Multiplicity;

  /// This field's embeddings, in ORDINAL ORDER — exactly one for a [`One`] carrier, and the whole
  /// set, possibly empty, for a [`Set`] one.
  ///
  /// An EMPTY set is a legal value rather than a missing one: a collection has no null state, so
  /// *no members* is what a record with nothing to index says, and a knn over its column simply does
  /// not reach it.
  fn members(&self) -> impl Iterator<Item = &Self::Item>;
}

/// 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.
#[rustfmt::skip]
#[diagnostic::on_unimplemented(
  message = "`{Self}` is not an embedding",
  label = "no element, width or space to read",
  note = "an `EmbeddingMarker`'s `Item` is what a knn's coordinates come out of, so it states its element type, its width and its space through `EmbeddingShape`; `Embedding<E, N, S>` is the framework's own row"
)]
pub trait EmbeddingShape {
  /// `E` — the coordinate type, which becomes the emitted
  /// [`VectorRecord::Element`](crate::VectorRecord::Element).
  ///
  /// One slot is opened at one element, so N elections of one declaration are N columns of one
  /// element — and rustc is what says so: the emission takes the FIRST election's and every other
  /// election's projection has to unify with it, at the span of the election that disagrees.
  type Element;

  /// `S` — the SPACE these coordinates live in, [`Anon`](crate::Anon) where the type named none.
  ///
  /// There is no *absent* state to carry: the parameter defaults, so a field spelled
  /// `Embedding<f32, 768>` answers [`Anon`](crate::Anon) here and a query built in another space is
  /// `E0308` against it. What used to be an emitter's choice — spell the third argument or leave it
  /// off — is a projection that is simply always right.
  type Space;

  /// `N` — how many coordinates one value holds.
  ///
  /// Spent in CONST-GENERIC position by the emitted query types, which is what makes asking a
  /// 768-wide column with a 384-wide query `E0308` at the call.
  const WIDTH: usize;

  /// The coordinates — exactly [`WIDTH`](Self::WIDTH) of them.
  ///
  /// The write face reads values through here and never through an inherent method it found by
  /// name: a declaration that aliased `Embedding` to a type of its own is answered by THAT type's
  /// impl, which is the whole point of routing a fact through a trait.
  fn coordinates(&self) -> &[Self::Element];
}

/// 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.
pub trait Multiplicity: sealed::Sealed {}

/// 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.
#[derive(Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord, Hash, Default)]
pub struct One(());

impl One {
  /// The marker.
  ///
  /// A constructor rather than a bare unit struct, which is this crate's law for every empty type
  /// it ships: the private `()` funnels construction through here from day one, so a field can be
  /// added later without breaking a downstream that built the value literally.
  #[inline]
  #[must_use]
  pub const fn new() -> Self {
    Self(())
  }
}

/// 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.
#[derive(Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord, Hash, Default)]
pub struct Set(());

impl Set {
  /// The marker — [`One::new`]'s twin, and the same law.
  #[inline]
  #[must_use]
  pub const fn new() -> Self {
    Self(())
  }
}

impl Multiplicity for One {}
impl Multiplicity for Set {}

mod sealed {
  pub trait Sealed {}

  impl Sealed for super::One {}
  impl Sealed for super::Set {}
}

/// 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.
#[rustfmt::skip]
#[diagnostic::on_unimplemented(
  message = "`{Field}` is labelled `embedding` and does not hold ONE embedding",
  label = "the label says one, the type says otherwise",
  note = "`embedding` labels a field holding a single `Embedding<E, N[, S]>`; a field holding a SET of them is labelled `list(embedding)`, and the two labels decide which faces and which doors this declaration emits"
)]
pub trait ElectsOne<Field: ?Sized> {}

/// [`One`] satisfies the claim for EVERY field — which is the whole of what the claim says: this
/// field's multiplicity is that one.
impl<Field: ?Sized> ElectsOne<Field> for One {}

/// The `list(embedding)` LABEL's claim — [`ElectsOne`]'s twin, whose note states the whole of what
/// this trait is for.
#[rustfmt::skip]
#[diagnostic::on_unimplemented(
  message = "`{Field}` is labelled `list(embedding)` and does not hold a SET of embeddings",
  label = "the label says a set, the type says otherwise",
  note = "`list(embedding)` labels a field whose type carries several embeddings — `Vec<Embedding<E, N[, S]>>` is the framework's own carrier, and any type implementing `EmbeddingMarker` with `Multiplicity = Set` is one. A field holding a single embedding is labelled `embedding`"
)]
pub trait ElectsSet<Field: ?Sized> {}

/// [`Set`]'s row — [`ElectsOne`]'s, one multiplicity over.
impl<Field: ?Sized> ElectsSet<Field> for Set {}

/// 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.
pub fn elects_one<Field>()
where
  Field: EmbeddingMarker,
  <Field as EmbeddingMarker>::Multiplicity: ElectsOne<Field>,
{
}

/// The `list(embedding)` label's audit — [`elects_one`]'s twin.
pub fn elects_a_set<Field>()
where
  Field: EmbeddingMarker,
  <Field as EmbeddingMarker>::Multiplicity: ElectsSet<Field>,
{
}

/// The FRAMEWORK's single-embedding row: a field spelled `Embedding<E, N[, S]>` is one embedding,
/// and is its own item.
impl<E, const N: usize, S> EmbeddingMarker for Embedding<E, N, S> {
  type Item = Self;
  type Multiplicity = One;

  #[inline]
  fn members(&self) -> impl Iterator<Item = &Self::Item> {
    core::iter::once(self)
  }
}

/// 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.
impl<E, const N: usize, S> EmbeddingMarker for Vec<Embedding<E, N, S>> {
  type Item = Embedding<E, N, S>;
  type Multiplicity = Set;

  #[inline]
  fn members(&self) -> impl Iterator<Item = &Self::Item> {
    self.iter()
  }
}

/// The element, the width and the space, off the type that states all three.
impl<E, const N: usize, S> EmbeddingShape for Embedding<E, N, S> {
  type Element = E;
  type Space = S;

  /// [`DIM`](Embedding::DIM) rather than `N`, so a zero-width election is `E0080` wherever this
  /// const is reached — the same refusal [`Embedding::new`] is held to, arriving through the
  /// projection instead of past it.
  const WIDTH: usize = Self::DIM;

  #[inline]
  fn coordinates(&self) -> &[Self::Element] {
    Self::coordinates(self)
  }
}