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
//! The MULTI-VECTOR fold: [`FoldSemantics`], the contract a set query is asked under, and the three
//! citizens this framework ships as implementations of it.
//!
//! # THE SEMANTIC-KIND NAMING LAW
//!
//! A *semantics* is not one thing. It is a KIND of decision a query makes, and this module holds the
//! first of them — the FOLD, which is how `m` per-query numbers become one. The kind's word
//! conjugates the whole way down, and that is a law rather than a coincidence of this round:
//!
//! ```text
//! semantics(fold = "app::MyFold")     the declaration's word    — the KEY is the kind
//!            FoldSemantics<S>         the contract
//!            …_with(…, fold: F)       the parameter
//!            Folded<K, S>             the result
//! ```
//!
//! So a second kind arrives spelled the same way and collides with nothing: `semantics(xyz = "…")`
//! reaches `XyzSemantics`, rides as `xyz: F`, and answers in `Xyzed`. The kind is the key of a
//! framework-closed vocabulary and the implementation behind it is open, which is the crossing this
//! whole family is built on.
//!
//! # The vocabulary IS the trait, and the shipped members are CITIZENS
//!
//! There is no `enum Semantics`. The fold a query is asked under is a TYPE implementing
//! [`FoldSemantics`], and [`Sum`], [`Max`] and [`Weighted`] are three of them that happen to ship
//! here. A fourth — framework or downstream — is one ZST and one impl, purely additive: no match
//! site widens, no enum gains an arm, and nothing that compiled before stops compiling. What a
//! closed vocabulary would have bought is a wire enum, and that is emitted PER ELECTION at the face
//! that needs it rather than fixed here.
//!
//! # Every empty type here is SEALED, and that is this crate's law for one
//!
//! `pub struct Sum(());` rather than `pub struct Sum;`. A bare unit struct is constructible by
//! anybody who can name it, so the day a citizen grows a field is the day every downstream literal
//! stops compiling. The private `()` funnels construction through [`Sum::new`] from the first
//! version, and the type can grow without breaking a caller.

use core::{
  cmp::Ordering,
  ops::{Add, Mul},
};

use super::FoldedQuery;

/// HOW the per-query bests fold into one set score — the query-time contract of the multi-vector
/// round.
///
/// # The primitive it folds over
///
/// A set query is `m` query vectors against an entity holding `n` of its own. The primitive both
/// physical forms produce is the same list of `m` numbers: **per query vector, its best match in the
/// entity's set** — `bⱼ = maxᵢ sim(qⱼ, vᵢ)`. An engine with native multi-vector scoring produces it
/// as a singleton MaxSim; every other engine produces it as an element knn followed by an owner-max,
/// which is the framework's own [`Seen`](super::Seen) stage read one grain up. This trait is what
/// turns those `m` numbers into ONE.
///
/// # THE DELEGATION LAW IS INHERITED BY CONSTRUCTION
///
/// The input is that primitive and nothing else. There is no `m·n` matrix in this signature, and
/// there cannot be one: a native set-scoring engine answers with the per-query best and never
/// exposes the pairs behind it. So all-pairs averaging — `ΣᵢΣⱼ sim(qⱼ, vᵢ) / (m·n)` — is not
/// refused here by a sentence; it is UNREPRESENTABLE, because the numbers it needs are not in the
/// argument. Every implementation anybody writes is therefore realizable on both delegation paths,
/// including the ones this framework has never seen.
///
/// # The SLOTS carry absence, and that is the whole of what a fold has to decide
///
/// `bests[j]` is query vector `j`'s own best, and [`None`] means that vector matched nothing of
/// this entity's ABOVE ITS FLOOR. The slot is there either way, so a fold that wants to know which
/// question went unanswered can see it, and a fold that does not can ignore it — the two readings
/// that split `Mean` in half are both writable, by the party that knows which one it means.
///
/// The slice is `m` long, `m ≥ 1`. Both facts are guaranteed upstream: a
/// [`FoldedQuery`](super::FoldedQuery) refuses the empty set at its constructor, and the walk that fills
/// these slots visits every query vector. They are stated here rather than re-checked, which is what
/// makes a refusal that was paid for once worth having.
///
/// # `Send + Sync`
///
/// The emitted door is `async` and holds the fold across the engine calls, so a fold that could not
/// cross a task boundary would make that future `!Send` and be unusable from every runtime that
/// spawns. It costs the ZST citizens nothing and costs a stateful one exactly what it would have
/// cost at the call site.
pub trait FoldSemantics<S>: Send + Sync {
  /// Fold one entity's per-query bests into its set score.
  ///
  /// # Panics
  ///
  /// A shipped citizen with nothing to start from panics rather than inventing a value — see
  /// [`Sum`], where the absence of an identity element is argued. An entity reaches this call
  /// because at least one query vector matched it, so a slice of all-[`None`] is unreachable
  /// through this crate's own road.
  fn score(&self, bests: &[Option<S>]) -> S;

  /// A stable name for a tap, a refusal and a doc — `"sum"`, `"max"`, `"weighted"`.
  ///
  /// # It is a ROW rather than a default, because a fold with no name is a fold nobody can report
  ///
  /// There is no default body, and that is the choice worth stating: the emitted set door opens its
  /// span with `fold = <name>` and its refusals name the fold that authored the order they came
  /// back in, so a citizen that inherited `"unnamed"` would silently make every trace of a
  /// deployment running it useless. One line per implementation buys the whole reporting surface,
  /// which is the same trade [`Concern::as_str`](crate::Concern::as_str) and the fate vocabulary
  /// already make one layer up.
  ///
  /// # It is NOT the wire's self-description
  ///
  /// SDL descriptions are built at compile time and the installed fold is a launch-time fact, so
  /// nothing here reaches a schema. What this name reaches is the three places a runtime value can
  /// be read: a span field, a refusal's text, and a log line. A dynamic wire row for it needs an
  /// introspection home that does not exist yet.
  ///
  /// `&str` rather than `&'static str`, so a fold assembled at launch — a weighting read from
  /// configuration, a tenant's own — can name itself from a `String` it holds.
  fn name(&self) -> &str;
}

/// A BORROWED fold folds — what lets a door taking its fold BY VALUE be handed one that lives
/// somewhere else.
///
/// The emitted set-similarity resolver is the caller this exists for: the fold it runs under is
/// either the one a deployment installed (behind an `Arc` inside a
/// [`FoldDoor`](crate::FoldDoor), so borrowed) or the one the declaration elected (a local, so
/// borrowable), and the door's parameter is `F: FoldSemantics<S>` taken by value. Without this impl
/// the resolver would have to monomorphize the whole door call once per arm of that choice, which
/// is the same body written twice for a decision made once per request.
///
/// `?Sized` so `&dyn FoldSemantics<S>` is one of them: the installed fold is erased, the elected one
/// is not, and both reach the door through this one line. Nothing is added to the fold — `score`
/// and `name` forward, and a borrow cannot disagree with what it borrows.
impl<S, F> FoldSemantics<S> for &F
where
  F: FoldSemantics<S> + ?Sized,
{
  #[inline]
  fn score(&self, bests: &[Option<S>]) -> S {
    F::score(self, bests)
  }

  #[inline]
  fn name(&self) -> &str {
    F::name(self)
  }
}

/// `Σⱼ bⱼ` — standard MaxSim / late-interaction, and the citizen a door falls back to.
///
/// The default because it is what the late-interaction family means by a set score: every query
/// vector contributes its own best, so an entity matching many of them outranks one matching a
/// single vector perfectly.
///
/// # NO ZERO, and no identity anywhere
///
/// The fold starts from the FIRST PRESENT element and adds the rest pairwise. It does not start
/// from a zero, because a currency's zero is a value only that currency can name — a distance-shaped
/// score (lower is closer) has no honest one, and a similarity in `[0, 1]` has one that means
/// *matched nothing*, which is the opposite of an identity.
///
/// [`iter::Sum`](core::iter::Sum) was measured and rejected for exactly this: its empty case
/// MANUFACTURES a value, so a bug that emptied the slots would answer with a zero-scored entity
/// instead of failing. What this does instead is start from a real number, which is available
/// because an entity that matched nothing never entered the accumulator at all.
#[derive(Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord, Hash, Default)]
pub struct Sum(());

impl Sum {
  /// The citizen's stable name — ONE spelling, read by the trait row and by the panic beside it.
  ///
  /// A const rather than a literal at each site, and the reason is a MEASUREMENT rather than tidiness:
  /// `self.name()` inside a `FoldSemantics<S>` body is `E0284`, the citizen implementing the trait at
  /// every `S` it can be added at, so the method call would have to be turbofished with a type the
  /// body has no other use for. A const on the citizen is the same fact reached without naming `S`
  /// at all.
  const NAME: &'static str = "sum";

  /// The citizen.
  ///
  /// A constructor rather than a bare unit struct — see this module's note on the sealed form.
  #[inline]
  #[must_use]
  pub const fn new() -> Self {
    Self(())
  }
}

impl<S> FoldSemantics<S> for Sum
where
  S: Clone + Add<Output = S> + Send + Sync,
{
  /// # Panics
  ///
  /// If every slot is [`None`], which the road above this cannot produce: an entity is in the
  /// accumulator because some query vector's stream held it above the floor.
  #[inline]
  fn score(&self, bests: &[Option<S>]) -> S {
    let mut present = bests.iter().flatten().cloned();
    let first = first_of(&mut present, Self::NAME);
    present.fold(first, |running, next| running + next)
  }

  #[inline]
  fn name(&self) -> &str {
    Self::NAME
  }
}

/// `maxⱼ bⱼ` — the best single (query vector, set member) pair.
///
/// For the question *did ANY of my vectors find this entity convincing*, where the sum's reward for
/// answering many questions adequately is not what the caller means.
///
/// # The comparison is written out, and the posture is the walk's own
///
/// A running maximum over [`PartialOrd`] keeps what it holds unless the newcomer is strictly
/// greater, so a tie and an incomparable pair are treated alike: a value that cannot be SHOWN to
/// beat what is held does not replace it. That is the same reading
/// [`ranked_keys`](super::ranked_keys) takes of a score it cannot place, and it is why this citizen
/// asks for no ordering the currency does not already have — floats are not [`Ord`], and demanding
/// that they were would lock out every score shape this framework exists to carry.
///
/// [`Clone`] is the SIGNATURE's price rather than the comparison's: the slots are borrowed and the
/// answer is owned.
#[derive(Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord, Hash, Default)]
pub struct Max(());

impl Max {
  /// The citizen's stable name — [`Sum`]'s own const, and the same `E0284` measurement.
  const NAME: &'static str = "max";

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

impl<S> FoldSemantics<S> for Max
where
  S: Clone + PartialOrd + Send + Sync,
{
  /// # Panics
  ///
  /// If every slot is [`None`] — see [`Sum`], whose argument is the same.
  #[inline]
  fn score(&self, bests: &[Option<S>]) -> S {
    let mut present = bests.iter().flatten().cloned();
    let first = first_of(&mut present, Self::NAME);
    present.fold(first, |running, next| match next.partial_cmp(&running) {
      Some(Ordering::Greater) => next,
      Some(Ordering::Less | Ordering::Equal) | None => running,
    })
  }

  #[inline]
  fn name(&self) -> &str {
    Self::NAME
  }
}

/// `Σⱼ wⱼ·bⱼ` — the sum with a weight per QUERY VECTOR, for a caller whose questions are not equally
/// important.
///
/// # Why a weight is a FOLD-layer fact
///
/// A non-negative weight does not move a per-query argmax: `w·maxᵢ sim(qⱼ, vᵢ) = maxᵢ w·sim(qⱼ, vᵢ)`.
/// So weighting AFTER the per-query max is the same answer as weighting inside it, which is what
/// makes this citizen correct on both delegation paths — a native set-scoring engine that never
/// exposed its pairs has already produced exactly the numbers this scales.
///
/// Pushing the weights down into an engine that has a native weighted-multi-vector option is an
/// OPTIMIZATION on the same answer, and it belongs to that engine's own options rather than here.
///
/// # The ARITY is checked at CONSTRUCTION, which is the only place it can be
///
/// [`for_query`](Self::for_query) takes the query the weights are for and refuses a list that is not
/// its length. So a mismatched pair is not a value of this type, and [`score`](FoldSemantics::score)
/// has nothing left to re-check — the same shape [`FoldedQuery::new`](super::FoldedQuery::new) uses for
/// the empty question, and for the same reason.
///
/// # An ABSENT answer contributes nothing
///
/// A [`None`] slot adds no term. Not a zero-valued one — that would be a number the currency never
/// produced — and not a shorter question either: the weight for an unanswered vector is simply not
/// spent, so an entity that answered the heavy question wins over one that answered the light one.
#[derive(Debug, Clone, PartialEq, Eq, Hash)]
pub struct Weighted<S>(Box<[S]>);

impl<S> Weighted<S> {
  /// The citizen's stable name — [`Sum`]'s own const, and the same `E0284` measurement.
  const NAME: &'static str = "weighted";

  /// The weights for `query`, in the order its vectors are asked — or [`None`] where there is not
  /// exactly one weight per vector.
  ///
  /// The query is taken WHOLE rather than as a count, so the arity a caller is being held to is the
  /// one their own question has. Its floor type is free: a
  /// [`Deferred`](super::Deferred)-floored query has the same `m` as a resolved one.
  #[inline]
  #[must_use]
  pub fn for_query<E, F, const N: usize, Space>(
    query: &FoldedQuery<E, F, N, Space>,
    weights: impl Into<Box<[S]>>,
  ) -> Option<Self> {
    let weights = weights.into();
    (weights.len() == query.asked().get()).then_some(Self(weights))
  }

  /// The weights, in the order the query vectors were asked.
  #[inline]
  #[must_use]
  pub fn weights(&self) -> &[S] {
    &self.0
  }
}

impl<S> FoldSemantics<S> for Weighted<S>
where
  S: Clone + Add<Output = S> + Mul<Output = S> + Send + Sync,
{
  /// # Panics
  ///
  /// If every slot is [`None`] — see [`Sum`], whose argument is the same.
  #[inline]
  fn score(&self, bests: &[Option<S>]) -> S {
    let mut terms = bests
      .iter()
      .zip(self.0.iter())
      .filter_map(|(best, weight)| best.as_ref().map(|best| weight.clone() * best.clone()));
    let first = first_of(&mut terms, Self::NAME);
    terms.fold(first, |running, next| running + next)
  }

  #[inline]
  fn name(&self) -> &str {
    Self::NAME
  }
}

/// WHAT AN EMITTED WIRE VOCABULARY HANDS ITS FOLD TO — the crossing from a closed set of words back
/// to the open set of types.
///
/// # The problem it exists for
///
/// The vocabulary above is a TRAIT, so a fold is a TYPE. A wire enum is a closed set of WORDS, and
/// the emission mints one per election — variants for the citizens this crate ships and one more for
/// every fold the declaration named. Crossing back is then a `match` whose arms produce DIFFERENT
/// TYPES, which no function returning one type can do and which no `Box<dyn …>` can do without
/// paying a virtual call per entity for a decision made once per query.
///
/// A continuation answers it exactly. The emitted `with_fold` matches, constructs that arm's fold,
/// and hands it here; [`visit`](Self::visit) is generic over the fold, so every arm monomorphizes
/// into its own body and the door below it is the same statically-dispatched door it would have been
/// if the caller had spelled the type. The word never becomes a value that outlives the match.
///
/// # `S` on the trait and `F` on the method, and that is the whole shape
///
/// The currency is the VISITOR's — a caller writes one of these knowing which engine's scores it
/// will fold — and the fold is the WORD's, which the visitor by construction does not know. So `S`
/// is where the implementor states it and `F` is where the emission supplies it, and a visitor
/// written against a currency works for every election scored in it, including the folds it has
/// never heard of.
pub trait FoldVisitor<S> {
  /// What spending the fold produces.
  type Output;

  /// Spend `fold` — whichever of the election's folds the word named.
  fn visit<F: FoldSemantics<S>>(self, fold: F) -> Self::Output;
}

/// The value a fold STARTS from, or the panic that names WHICH FOLD had nothing to start from and
/// why there was none.
///
/// One sentence for all three citizens, so the invariant is written once and reads the same wherever
/// it fires — and one place to change if a fold that can answer about nothing ever ships.
///
/// The fold's own [`name`](FoldSemantics::name) rides the message, which is the second of the three
/// places that row is spent: a deployment reading this abort in a log knows whether the fold that
/// hit it was the shipped `sum` or the one it installed, and that is exactly the fork it would
/// otherwise have to reproduce to find out. The name is taken as an argument rather than read off a
/// `&dyn` here because the caller is the implementation itself, which knows its own name statically.
///
/// # Panics
///
/// Where the slots hold no answer at all, which this crate's own road cannot produce.
#[inline]
fn first_of<T>(present: &mut impl Iterator<Item = T>, fold: &str) -> T {
  present.next().unwrap_or_else(|| {
    panic!(
      "the `{fold}` fold was handed no answer at all: an entity reaches a fold because at least one \
       query vector matched it above its floor",
    )
  })
}

#[cfg(test)]
mod tests;