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
//! [`Folded`] — what a SET retrieve hands back: the folded score, what each query vector's own
//! stream said about the entity, and the thing itself — and [`StreamBest`], one of those slots.

/// ONE QUERY VECTOR'S SIGHTING of an entity: the best score that vector found in the entity's set,
/// and where that vector's own stream put it.
///
/// # It exists because the fold stopped stripping what it computes
///
/// [`set_scored`](super::set_scored) accumulates a score AND an ordinal per query vector, hands the
/// scores to a [`FoldSemantics`](super::FoldSemantics), and used to keep only the ordinals: the
/// answer carried `ranks[j]` and the number the fold actually read — `bests[j]` — was dropped at the
/// push site. That is the same loss [`Sighting`](super::Sighting) was minted to end one family over,
/// and the argument transfers without change: a client reading a set answer has no engine, no floor
/// and no second query to recompute `bⱼ` from, and the ordering alone cannot say whether a stream
/// led by a nose or by a mile.
///
/// The recomputation road is worse here than it was there. A caller CAN re-ask query vector `j` and
/// read the score back, but that is a second engine call against a corpus that may have moved, so
/// the number it returns is a number that can disagree with the one the fold used. What is carried
/// from the fold cannot disagree with the fold, because it IS the fold's.
///
/// # The ordinal is `ordinal` and not `rank`, and the word is the SET family's
///
/// [`Ranked::rank`](super::Ranked::rank) is *where the engine put it* on a road that has ONE stream,
/// so the bare word is unambiguous there. A set retrieve has `m` of them, and a bare `rank` on this
/// slot would read as a position in the answer — which is the one number this whole family refuses
/// to mint, the fold authoring the answer's order. [`Sighting::ordinal`](super::Sighting::ordinal)
/// already spells it this way for the same reason, so the two provenance slots of the two folds say
/// the same word.
///
/// # `Copy` follows `S`, and the accessors are [`Folded`]'s own pair
///
/// The borrow always, the copy behind a `Copy` gate on the METHOD rather than on the parameter — so
/// a composite score is stored, borrowed and decomposed exactly as an `f32` is.
#[derive(Debug, Clone, Copy, PartialEq)]
pub struct StreamBest<S> {
  score: S,
  ordinal: u64,
}

impl<S> StreamBest<S> {
  /// One stream's sighting: the best score it found, and its ordinal in that stream.
  ///
  /// `const`, and taken as it stands — [`Sighting::new`](super::Sighting::new)'s reason: the walk is
  /// what produced both numbers, and a constructor that re-derived either would be a second opinion
  /// about a value with one source.
  #[inline]
  pub const fn new(score: S, ordinal: u64) -> Self {
    Self { score, ordinal }
  }

  /// THE BEST SCORE this query vector found in the entity's set, BORROWED — `bⱼ`, in the engine's
  /// own currency, before any fold touched it.
  ///
  /// It is a PRE-FOLD number, which is what makes it comparable to the floor the query carried:
  /// the floor cuts at the element grain and this is that grain's own answer. The folded score
  /// beside it is in a third currency and no floor is stated in it.
  #[inline(always)]
  pub const fn score_ref(&self) -> &S {
    &self.score
  }

  /// The same score, BY VALUE, where it is `Copy`.
  #[inline(always)]
  pub const fn score(&self) -> S
  where
    S: Copy,
  {
    self.score
  }

  /// This entity's 1-based position in THIS query vector's own raw stream, holes left in.
  ///
  /// The number [`Ranked::rank`](super::Ranked::rank) carries, unchanged and unre-densified — see
  /// [`Folded`]'s note on why nothing anywhere mints one across the streams, and on how a caller
  /// continues from `m` of these.
  #[inline(always)]
  pub const fn ordinal(&self) -> u64 {
    self.ordinal
  }

  /// Both, taken — in field order, for a wire mapping or a hydration carrying the slot across.
  #[inline]
  pub fn into_components(self) -> (S, u64) {
    (self.score, self.ordinal)
  }
}

/// One set-similarity result: the score a [`FoldSemantics`](super::FoldSemantics) produced, what
/// each query vector's own stream said about the entity, and the key.
///
/// # It is [`Ranked`](super::Ranked)'s twin, and the plural is the whole difference
///
/// A single-vector retrieve has ONE engine stream, so one score and one rank. A set retrieve runs
/// the engine once per query vector, so it has `m` of each and no order between them — which is why
/// the ruled shape for this answer was a plain score with no number at all, and why this type amends
/// that: the numbers exist, one pair per stream, and they are only unspellable if you insist on ONE.
///
/// # ATTRIBUTION is what makes the numbers lawful
///
/// `streams[j]` is what query vector `j`'s own engine stream said about this entity — see
/// [`StreamBest`] for the pair. The ordinal is **1-based over that stream's raw hits**, the same
/// number [`Ranked::rank`](super::Ranked::rank) carries. Nothing here mints a global ordinal over
/// the `m` streams, because there is nothing to mint one from: the fold authors the answer's ORDER,
/// and an ordinal invented over that order would be a number no engine could be continued from.
/// Every number in this list is one stream's own truth, and it is attributed to the stream that
/// produced it.
///
/// That keeps the rank law intact rather than bending it. What a caller gets is `m` per-stream
/// resume tokens instead of one: re-ask query vector `j` with a wider budget and drop everything at
/// or below `streams[j]`'s ordinal, exactly as the single-vector road's continuation works. The
/// ruled resumption story is therefore reachable from here without a cursor slot and without a
/// second meaning for the word *rank*.
///
/// # `None` is *below that stream's floor*
///
/// `streams[j]` is [`None`] exactly where query vector `j` matched nothing of this entity's — the
/// same slot that is [`None`] in the row a fold receives. The correspondence used to be an invariant
/// between two parallel lists and is now a fact of ONE: the accumulator holds the score and the
/// ordinal in the same slot, and there is no longer a second list for it to disagree with.
///
/// # The SCORES the fold read are HERE, and that is what changed
///
/// A [`FoldSemantics`](super::FoldSemantics) implementor is handed exactly `bests[j]`, and this type
/// used to drop them on the way out. Carrying them was recorded as a widening rather than built,
/// on the argument that nothing asked for the pre-fold numbers; the WIRE asked. A client reading a
/// set answer has neither the engine nor the floor to recompute one from, so the number is carried
/// out of the fold instead of being computable in principle. It costs nothing to carry: the score is
/// MOVED out of the slot the fold borrowed, after the fold has read it.
///
/// # `S` is the engine's own currency, folded
///
/// The score here has been through a fold, so it is in the currency's own units and not necessarily
/// in the range one pair of vectors reports: a sum of `m` cosines is not a cosine. That is the
/// reason the FLOOR is spent one stage earlier, at the element grain, where a person has actually
/// seen a number — and the reason [`StreamBest::score_ref`] is the number that compares against it.
///
/// # The accessors are [`Ranked`](super::Ranked)'s, plus the list
///
/// The borrow always, the copy behind a `Copy` gate on the METHOD rather than on the parameter — so
/// a `String` key or a composite score is stored, borrowed and decomposed exactly as an `f32` is.
#[derive(Debug, Clone, PartialEq)]
pub struct Folded<K, S> {
  score: S,
  streams: Box<[Option<StreamBest<S>>]>,
  node: K,
}

impl<K, S> Folded<K, S> {
  /// Pair a key with its folded score and what each query vector's own stream said about it.
  ///
  /// Arguments in field order, so a call site reads as the record does.
  #[inline]
  pub const fn new(score: S, streams: Box<[Option<StreamBest<S>>]>, node: K) -> Self {
    Self {
      score,
      streams,
      node,
    }
  }

  /// The folded score, BORROWED, in the engine's own currency.
  #[inline(always)]
  pub const fn score_ref(&self) -> &S {
    &self.score
  }

  /// The folded score, BY VALUE, where it is `Copy`.
  #[inline(always)]
  pub const fn score(&self) -> S
  where
    S: Copy,
  {
    self.score
  }

  /// What each query vector's own stream said about this entity, in the order the vectors were
  /// asked.
  ///
  /// `m` long, [`None`] where that vector matched nothing of this entity's above its floor.
  #[inline(always)]
  pub fn streams(&self) -> &[Option<StreamBest<S>>] {
    &self.streams
  }

  /// ONE query vector's sighting, by its ordinal — or [`None`] where that vector saw nothing, and
  /// also where there was no such vector.
  ///
  /// The two absences are one answer on purpose: `j` is a position in a set the CALLER asked with,
  /// so a `j` past the end is the caller's own arithmetic rather than a fact about the entity, and a
  /// second shape for it would be a `Result` nobody could act on differently.
  #[inline]
  pub fn stream(&self, ordinal: usize) -> Option<&StreamBest<S>> {
    self.streams.get(ordinal).and_then(Option::as_ref)
  }

  /// The key, BORROWED.
  #[inline(always)]
  pub const fn node_ref(&self) -> &K {
    &self.node
  }

  /// The key, BY VALUE, where it is `Copy`.
  #[inline(always)]
  pub const fn node(&self) -> K
  where
    K: Copy,
  {
    self.node
  }

  /// The key, taken — for the common case of a caller that wants the keys and has read the numbers.
  #[inline]
  pub fn into_node(self) -> K {
    self.node
  }

  /// All three, taken — in field order.
  #[inline]
  pub fn into_components(self) -> (S, Box<[Option<StreamBest<S>>]>, K) {
    (self.score, self.streams, self.node)
  }

  /// The same answer with a DIFFERENT node, the score and every slot carried across.
  ///
  /// [`Ranked::map_node`](super::Ranked::map_node)'s twin, and the same one move: a folded KEY
  /// becomes a folded ENTITY or a folded wire address, and every number on it is the fold's answer
  /// about that key rather than about the row or the object found under it. Written here rather than
  /// at each loop so the carry cannot pick a number up from somewhere else.
  #[inline]
  pub fn map_node<U>(self, node: U) -> Folded<U, S> {
    Folded {
      score: self.score,
      streams: self.streams,
      node,
    }
  }
}

#[cfg(test)]
mod tests;