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 road: [`FoldedQuery`] — what a set-similarity retrieve is asked with — and the
//! two framework functions both physical forms of a stored embedding SET share, [`owner_best`] and
//! [`set_scored`].
//!
//! # WHERE `set` LIVES AND WHERE `Folded` DOES, ruled 2026-08-19
//!
//! Two words on one road, split by GRAIN rather than by taste.
//!
//! **`set` is the DECLARATION's word.** `list(embedding)` elects a set, `streams = N` guards how
//! many query vectors one request may ask a `_with` road with, and what an author reads off either
//! is *this column holds a SET of coordinates*. Nothing there has been folded yet.
//!
//! **`Folded` is the ANSWER's word.** A fold is what turns `m` unordered streams into one order, so
//! every type a client reads is named after the operation that authored it: [`Folded`], the wire
//! `FoldedMatch` it crosses into, and the [`FoldSemantics`](super::FoldSemantics) that decided the
//! number.
//!
//! [`FoldedQuery`] sits on the ANSWER's side, because a query is named for the answer it asks for:
//! two callers holding `m` vectors are told apart by whether a fold runs, and by nothing else. What
//! stays `set` in THIS module is the SHARED CORE both physical forms of a stored set spend —
//! [`set_scored`] walks a stored set, and no fold has happened when it does.

use core::{cmp::Ordering, num::NonZeroUsize};

use super::{Bests, Deferred, FoldSemantics, Folded, Ranked, Seen, StreamBest, ranked_keys};
use crate::{Anon, Embedding, Hits};

/// A SET-SIMILARITY retrieve: the `m` query embeddings, and the minimum score a neighbour must
/// reach.
///
/// [`VectorQuery`](super::VectorQuery)'s multi-vector twin, and every clause of that type holds here
/// unchanged: the width and the space are checked where an [`Embedding`] is BUILT, the floor is
/// MANDATORY and rides the constructor's positional parameter, and the score's currency is the
/// ENGINE's rather than the framework's.
///
/// # The floor is in the ELEMENT's currency, and it cuts before the fold
///
/// It is the same number [`VectorQuery`](super::VectorQuery) carries — the engine's own score for
/// one query vector against one stored vector — and it is spent at the same stage, terminating each
/// per-query walk. It is NOT a floor on the folded set score, which would be a number in a third
/// currency (a [`Sum`](super::Sum) of `m` cosines is not a cosine) that no engine reports and no
/// author could calibrate. So *what counts as a match* stays a fact about one pair of vectors, which
/// is the only grain at which a person has ever seen a score.
///
/// # The EMPTY query set is refused, and the refusal is the constructor
///
/// A set query with no query vectors asks nothing: there is no `bⱼ` to fold, so every fold is an
/// empty product and every entity ties. [`new`](Self::new) hands back [`None`] for it — the same
/// shape [`Embedding::new`] uses for a slice that is not this type's width, and for the same reason:
/// an empty list is not a value of this type. The dividend is one parameter further on:
/// [`asked`](Self::asked) is a [`NonZeroUsize`], so the `m ≥ 1` a
/// [`FoldSemantics`](super::FoldSemantics) is promised is a fact of this type rather than a comment
/// on it.
///
/// # The FLOORLESS form is the same type at a different floor TYPE
///
/// [`of`](Self::of) defers the number and answers `FoldedQuery<E, Deferred, N, Space>`, which no
/// engine-facing door takes — see [`Deferred`](super::Deferred) for why the deferral is structural
/// rather than an `Option` inside the query.
///
/// # `m = 1` is the DEGENERATE form and not a different one
///
/// [`single`](Self::single) builds it and cannot fail. Every fold agrees on a single slot — there is
/// one number and it is the answer — so an `ask` chain that produced one embedding reaches this road
/// unchanged and a caller holding one vector never learns the knob exists.
pub struct FoldedQuery<E, S, const N: usize, Space = Anon> {
  inputs: Vec<Embedding<E, N, Space>>,
  floor: S,
}

impl<E, const N: usize, Space> FoldedQuery<E, Deferred, N, Space> {
  /// Ask for the neighbours of every embedding in `inputs`, DEFERRING the floor — or [`None`] where
  /// `inputs` is empty.
  ///
  /// [`new`](Self::new)'s floorless twin, and [`VectorQuery::of`](super::VectorQuery::of)'s: the
  /// ruled chain is *查询层传入 > attr 默认*, and this is how a caller declines the first step. The
  /// EMPTY refusal is unchanged, being a fact about the question rather than about the floor.
  #[inline]
  #[must_use]
  pub fn of(inputs: Vec<Embedding<E, N, Space>>) -> Option<Self> {
    Self::new(inputs, Deferred::new())
  }

  /// RESOLVE the deferred floor — [`VectorQuery::floored`](super::VectorQuery::floored)'s twin, and
  /// the same seam.
  #[inline]
  #[must_use]
  pub fn floored<S>(self, floor: S) -> FoldedQuery<E, S, N, Space> {
    FoldedQuery {
      inputs: self.inputs,
      floor,
    }
  }
}

impl<E, S, const N: usize, Space> FoldedQuery<E, S, N, Space> {
  /// Ask for the neighbours of every embedding in `inputs`, returning nothing that scores below
  /// `floor` — or [`None`] where `inputs` is empty.
  #[inline]
  #[must_use]
  pub fn new(inputs: Vec<Embedding<E, N, Space>>, floor: S) -> Option<Self> {
    (!inputs.is_empty()).then_some(Self { inputs, floor })
  }

  /// The DEGENERATE form: one query vector, which no refusal can be about.
  ///
  /// What an `ask` chain's single answer becomes, and what makes the `m = 1` coincidence reachable
  /// without a caller unwrapping an [`Option`] it can prove is `Some`.
  #[inline]
  #[must_use]
  pub fn single(input: Embedding<E, N, Space>, floor: S) -> Self {
    Self {
      inputs: vec![input],
      floor,
    }
  }

  /// The query embeddings, in the order the caller wrote them.
  #[inline]
  #[must_use]
  pub fn inputs(&self) -> &[Embedding<E, N, Space>] {
    &self.inputs
  }

  /// Each query vector's coordinates, as [`VectorRead::knn`](crate::VectorRead::knn) takes them
  /// — [`VectorQuery::coordinates`](super::VectorQuery::coordinates) once per member.
  ///
  /// What the emitted set door walks: one engine call per item, in this order, so the `bⱼ` the fold
  /// receives are in the order the caller asked their questions.
  #[inline]
  pub fn coordinates(&self) -> impl Iterator<Item = &[E]> {
    self.inputs.iter().map(Embedding::coordinates)
  }

  /// `m` — how many query vectors were ASKED, which is how many slots a fold is handed.
  ///
  /// Non-zero because the constructor refused the empty set.
  #[inline]
  #[must_use]
  pub fn asked(&self) -> NonZeroUsize {
    NonZeroUsize::new(self.inputs.len()).expect("a set query holds at least one embedding")
  }

  /// The minimum score one query vector's neighbour must reach, in the engine's own currency and
  /// direction.
  #[inline]
  pub const fn floor(&self) -> &S {
    &self.floor
  }
}

/// The three are written rather than derived, for [`VectorQuery`](super::VectorQuery)'s own reason:
/// a derive bounds every parameter it sees, and `Space` is a marker holding nothing that a sealed
/// `pub struct Clip(());` derives nothing for.
impl<E: core::fmt::Debug, S: core::fmt::Debug, const N: usize, Space> core::fmt::Debug
  for FoldedQuery<E, S, N, Space>
{
  fn fmt(&self, f: &mut core::fmt::Formatter<'_>) -> core::fmt::Result {
    f.debug_struct("FoldedQuery")
      .field("inputs", &self.inputs)
      .field("floor", &self.floor)
      .finish()
  }
}

impl<E, S: Clone, const N: usize, Space> Clone for FoldedQuery<E, S, N, Space> {
  #[inline]
  fn clone(&self) -> Self {
    Self {
      // Each embedding's own `Clone` is a refcount bump and carries no `E: Clone`, so this one does
      // not either — the derived body would have demanded it of both.
      inputs: self.inputs.clone(),
      floor: self.floor.clone(),
    }
  }
}

impl<E: PartialEq, S: PartialEq, const N: usize, Space> PartialEq for FoldedQuery<E, S, N, Space> {
  #[inline]
  fn eq(&self, other: &Self) -> bool {
    self.inputs == other.inputs && self.floor == other.floor
  }
}

/// ONE query vector's `bⱼ`: the engine's hits for it, collapsed to **the best score per OWNER**.
///
/// # It is the dedup stage, read one grain up
///
/// The multi-row physical form stores an entity's set as one row per member — owner key, ordinal,
/// element vector — so the engine's raw stream is at the ELEMENT grain and several of its hits can
/// name one entity. The primitive the fold needs is that entity's BEST, which is precisely *first
/// occurrence wins on a score-descending stream*: the pipeline's own dedup, asked about an owner
/// instead of about a key that was already one. So this delegates to
/// [`ranked_keys`](super::ranked_keys) rather than reimplementing the walk, and inherits every
/// property stated there — the floor TERMINATES rather than filters, an incomparable score ends the
/// walk, and the mechanism is the declaration's own.
///
/// The `hits` this takes are therefore already read back into the OWNER's key type: the address the
/// engine hands back carries owner and ordinal, and the row family ([`Field`](crate::Field)) is
/// where a key decides that the ordinal is not part of it.
///
/// # The RANK is KEPT here, and ATTRIBUTED where it lands
///
/// [`ranked_keys`] mints an ordinal over the engine's raw stream, and a set query has `m` such
/// streams. The number is this stream's own truth and stays that: it rides through the fold into the
/// slot belonging to the query vector that produced it, which is what
/// [`Folded::streams`](super::Folded::streams) hands back — beside the score it was measured with.
/// Nothing anywhere mints an ordinal ACROSS the streams — the fold authors the answer's order, and a
/// number invented over that order would be one no engine could be continued from.
///
/// # It is UNBOUNDED, and that is the fold's requirement rather than an oversight
///
/// Every above-floor owner is returned. `k` counts ENTITIES and is applied by [`set_scored`] AFTER
/// the fold, because an entity that places 200th for one query vector and first for the other four
/// is exactly the entity a late-interaction score exists to find — truncating per query vector would
/// cut it before its score existed.
pub fn owner_best<K, S, D>(hits: Hits<K, S>, floor: &S) -> Vec<Ranked<K, S>>
where
  S: PartialOrd,
  D: Seen<K>,
{
  ranked_keys::<K, S, D>(hits, floor, usize::MAX)
}

/// [`owner_best`] with ONE OWNER ALREADY SEEN — the collapse a fuse-BY-EXAMPLE runs, where the
/// example must not answer its own question.
///
/// # It is the SET grain's spelling of an exclusion the single-vector doors already had
///
/// [`ranked_keys_excluding`](super::ranked_keys_excluding) is what a
/// `retrieve_similar_by_<field>` walks, and a set-similarity door asks the same question with `m`
/// vectors instead of one — so each of the `m` streams needs the same seed, and the exclusion has
/// to happen HERE rather than after the fold. Filtering the fused answer instead would let the
/// example contribute to its own neighbours' sightings, which is a different ranking wearing the
/// same name.
///
/// UNBOUNDED like the sibling it wraps, and for the same reason: `k` counts entities and is spent
/// by [`set_scored`] after the fold.
pub fn owner_best_excluding<K, S, D>(hits: Hits<K, S>, floor: &S, excluded: &K) -> Vec<Ranked<K, S>>
where
  S: PartialOrd,
  D: Seen<K>,
{
  super::ranked_keys_excluding::<K, S, D>(hits, floor, usize::MAX, excluded)
}

/// ONE ENTITY's per-query sightings, as the fold accumulates them — the accumulator's VALUE, and a
/// type a caller of [`set_scored`] names and never builds.
///
/// # Why the accumulated value is not just the score
///
/// A [`FoldSemantics`](super::FoldSemantics) is handed `m` SLOTS, and the answer carries the same
/// `m` sightings. So what one entity accumulates is a sighting per query vector that saw it — which
/// query, at what score, at what ordinal in that query's own stream — and the row is widened to the
/// two `m`-long lists only at the end, where the number of queries asked is finally known.
///
/// SPARSE, one entry per vector that actually saw the entity: an entity matched by one of fifty
/// query vectors carries one sighting rather than fifty slots, and the widening to `m` happens once.
///
/// # Opaque
///
/// It is public because the accumulator's instantiation names it — `HashBests<Key, Sightings<Score>>`
/// is what an emitted set door writes — and it carries no constructor, because the only party that
/// fills one is the fold below.
#[derive(Debug, Clone, PartialEq)]
pub struct Sightings<S>(Vec<(usize, S, u64)>);

impl<S> Sightings<S> {
  /// One query vector's sighting of one entity: which vector, its best score, its rank in that
  /// vector's own stream.
  fn of(query: usize, score: S, rank: u64) -> Self {
    Self(vec![(query, score, rank)])
  }

  /// Two sightings of one entity, joined — [`Bests::fold`](super::Bests::fold)'s `combine`.
  ///
  /// A CONCATENATION rather than a comparison, and that is the grain difference between this and the
  /// dedup stage: two sightings of one entity come from two different query vectors, so neither
  /// replaces the other and both are the answer.
  fn joined(mut running: Self, incoming: Self) -> Self {
    running.0.extend(incoming.0);
    running
  }

  /// The two `m`-long lists, in query order — the scores a fold reads, and the ordinals that go
  /// back into the answer beside them.
  ///
  /// **The correspondence is minted HERE**, which is why it is an invariant rather than a
  /// convention: one sighting fills one slot of each list, so `ordinals[j].is_some()` and
  /// `bests[j].is_some()` are the same fact written twice. The pair is joined back into ONE list of
  /// [`StreamBest`](super::StreamBest) by [`set_scored`] the moment the fold has read the scores —
  /// which is the earliest a join can happen without cloning a currency, and the last moment the
  /// two can be out of step.
  fn slots(self, asked: usize) -> (Vec<Option<S>>, Box<[Option<u64>]>) {
    let mut bests = Vec::with_capacity(asked);
    bests.resize_with(asked, || None);
    let mut ordinals = vec![None; asked];
    for (query, score, ordinal) in self.0 {
      bests[query] = Some(score);
      ordinals[query] = Some(ordinal);
    }
    (bests, ordinals.into_boxed_slice())
  }
}

/// THE FOLD: `m` lists of per-query bests in, one [`Folded`](super::Folded) per ENTITY out, ranked
/// and cut to `limit`.
///
/// The half of the multi-vector road that is identical over both physical forms. A native
/// multi-vector engine hands its per-query singleton MaxSim straight in; an engine on the universal
/// multi-row form hands in what [`owner_best`] collapsed. Neither is named here, which is the
/// delegation law made mechanical: the framework folds a primitive and never learns which side of
/// the delegation produced it.
///
/// # The SEMANTICS is a type, and the arithmetic is entirely its own
///
/// This function walks, slots and sorts. What the `m` numbers MEAN together is
/// [`FoldSemantics::score`](super::FoldSemantics::score)'s, called once per entity with that
/// entity's slots — so a fold nobody here has heard of is reached by the same walk, and no arm in
/// this body knows which one it called.
///
/// # `limit` counts ENTITIES, and it is spent LAST
///
/// After the fold and after the sort. A set score is not known until every query vector has been
/// walked, so a budget spent earlier would be a budget spent on a number that did not exist yet.
///
/// # The order the answer comes back in
///
/// Set score DESCENDING. Two entities whose scores cannot be compared — which takes a currency that
/// produced a `NaN` in the fold — are left in the accumulator's own order rather than being placed
/// against each other on evidence that does not exist; the sort is stable, so that order is the
/// mechanism's and is at least the same twice.
///
/// # `m` is COUNTED here rather than passed
///
/// The slots are `m` long, and `m` is the number of lists this function walks. Taking it as a
/// parameter would let a caller state a different one, and there is no case where a caller knows
/// better than the walk.
pub fn set_scored<K, S, B, F>(
  bests: impl IntoIterator<Item = Vec<Ranked<K, S>>>,
  fold: &F,
  limit: usize,
) -> Vec<Folded<K, S>>
where
  S: PartialOrd,
  B: Bests<K, Sightings<S>>,
  F: FoldSemantics<S>,
{
  let mut asked = 0usize;
  let mut folding = B::empty();
  for list in bests {
    let at = asked;
    asked += 1;
    for hit in list {
      let (score, rank, key) = Ranked::into_components(hit);
      folding.fold(key, Sightings::of(at, score, rank), Sightings::joined);
    }
  }
  // Zero lists is not reachable through `FoldedQuery`, whose constructor refuses the empty set — this
  // is the shape a direct caller of the fold gets, and it is the honest one: nothing was asked, so
  // nothing scored.
  if asked == 0 {
    return Vec::new();
  }
  let mut scored: Vec<Folded<K, S>> = folding
    .drain()
    .into_iter()
    .map(|entity| {
      let (key, sightings) = entity.into_components();
      let (bests, ordinals) = sightings.slots(asked);
      // THE FOLD READS FIRST, AND THE SCORES ARE MOVED OUT AFTER IT — which is the whole reason the
      // widening costs nothing. A join written before this line would have to hand the fold a
      // borrowed view or a clone per slot, and `S` is bounded by `PartialOrd` here: a `Clone` added
      // to carry a number out would be a bound the walk does not otherwise need.
      let score = fold.score(&bests);
      let streams = bests
        .into_iter()
        .zip(ordinals)
        // A HALF-FILLED PAIR IS UNREACHABLE and is answered rather than asserted: `slots` fills both
        // lists from ONE sighting, so `(Some, None)` cannot be built by this crate's road. Answering
        // `None` for it is the honest reading if a caller ever builds one by hand — *that stream saw
        // nothing* — where a panic would be this walk having an opinion about somebody else's row.
        .map(|slot| match slot {
          (Some(best), Some(ordinal)) => Some(StreamBest::new(best, ordinal)),
          (Some(_) | None, _) => None,
        })
        .collect();
      Folded::new(score, streams, key)
    })
    .collect();
  scored.sort_by(|a, b| {
    b.score_ref()
      .partial_cmp(a.score_ref())
      .unwrap_or(Ordering::Equal)
  });
  scored.truncate(limit);
  scored
}

#[cfg(test)]
mod tests;