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
//! [`Ranked`] — what a retrieve hands back: the score the engine gave it, where in the engine's raw
//! stream it stood, and the thing itself.

/// One retrieved result: its score, its rank, and what was retrieved.
///
/// # The three fields, and why the order is the one it is
///
/// `score` is written first because it is the more important of the two numbers. It is the
/// instrument the caller calibrates the MANDATORY floor with — a query cannot be asked without one,
/// and a floor is a number in the engine's own currency, so a caller that cannot see the scores it
/// got back has no way to learn which floor its corpus wants. Field order changes nothing a compiler
/// checks; it records the priority where a reader meets it.
///
/// `rank` is the hit's **1-based position in the engine's RAW hit stream**, and it is NOT the
/// position of this item in the returned list. The two disagree wherever the pipeline dropped a hit
/// — a duplicate key, a row the filter pruned, a row the store no longer has — and the holes are
/// left exactly where they fell. Re-densifying them would throw away the one number a caller can
/// continue from: re-issue the same query with a wider budget, drop everything at or below the last
/// rank seen, and the tail is the continuation. That is what v1 offers instead of a cursor, and it
/// works only while the number means *where the engine put it*.
///
/// `node` is the thing: the KEY at tier A, and the WHOLE upstream domain entity at tier B.
///
/// # `S` is the engine's own currency, and nothing here defaults it
///
/// The score arrives at the type the store face declared — BM25's `f32`, a cosine face's distance,
/// a fused shape — untranslated. [`Scored`](crate::Scored) states the whole argument for the
/// parameter one layer down, and this type is the same fact carried up: two ranked lists at
/// different `S` do not merge, and making them merge is a conversion somebody writes.
///
/// # The accessors are [`Scored`](crate::Scored)'s, plus the number
///
/// The borrow always, the copy in addition behind a `Copy` gate written on the METHOD rather than
/// on the parameter — so a `String` key or a composite fused score is stored, borrowed and
/// decomposed exactly as an `f32` is, and the only thing it declines is being handed back by value
/// for free. [`rank`](Self::rank) takes no gate at all, being a `u64`.
#[derive(Debug, Clone, PartialEq)]
pub struct Ranked<T, S> {
  score: S,
  rank: u64,
  node: T,
}

impl<T, S> Ranked<T, S> {
  /// Pair what was retrieved with the score it matched at and the position the engine gave it.
  ///
  /// Arguments in field order, so a call site reads as the record does.
  #[inline]
  pub const fn new(score: S, rank: u64, node: T) -> Self {
    Self { score, rank, node }
  }

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

  /// The score, BY VALUE, where it is `Copy` — a BM25 `f32`, a [`Score`](crate::Score).
  #[inline(always)]
  pub const fn score(&self) -> S
  where
    S: Copy,
  {
    *self.score_ref()
  }

  /// The hit's 1-based position in the ENGINE's raw stream — with the holes the pipeline left in
  /// it.
  #[inline(always)]
  pub const fn rank(&self) -> u64 {
    self.rank
  }

  /// What was retrieved, BORROWED.
  #[inline(always)]
  pub const fn node_ref(&self) -> &T {
    &self.node
  }

  /// What was retrieved, BY VALUE, where it is `Copy`.
  #[inline(always)]
  pub const fn node(&self) -> T
  where
    T: Copy,
  {
    *self.node_ref()
  }

  /// Take what was retrieved, dropping both numbers — for a caller that has finished with the
  /// ranking.
  #[inline]
  pub fn into_node(self) -> T {
    self.node
  }

  /// Take all three, none cloned — for the caller that keeps the numbers: a wire mapping rendering
  /// the triple, a fill loop carrying score and rank across a hydration.
  ///
  /// In FIELD order, which is also the order [`new`](Self::new) takes them back in.
  #[inline]
  pub fn into_components(self) -> (S, u64, T) {
    (self.score, self.rank, self.node)
  }

  /// The same triple with a DIFFERENT node, the two numbers carried across.
  ///
  /// The tier-B fill loop's one move: a ranked KEY becomes a ranked ENTITY, and the score and the
  /// rank are the engine's answer about that key rather than about the row the store found under
  /// it. Written here rather than at the loop so the carry cannot pick up a number from somewhere
  /// else.
  #[inline]
  pub fn map_node<U>(self, node: U) -> Ranked<U, S> {
    Ranked {
      score: self.score,
      rank: self.rank,
      node,
    }
  }
}

#[cfg(test)]
mod tests;