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
//! [`FusedScore`] — the framework's OWN currency, and the only score in the system nobody's engine
//! minted.

/// What a fused retrieve ranks by: the sum of its members' reciprocal-rank contributions.
///
/// # It compares WITHIN ONE RESULT and nowhere else
///
/// The number is a function of how many members ranked this root and how highly, so it is
/// meaningful against the other roots of the SAME answer and against nothing else. Two things it is
/// specifically not:
///
/// - **Not comparable across queries.** A query that three members answered produces larger numbers
///   than one that two answered, with no statement about relevance in the difference.
/// - **Not a confidence.** It has no interpretation as a probability or a similarity, and it is
///   deliberately NOT a [`Score`](crate::Score): that type IS the closed unit interval, and writing
///   it here would be a claim that something normalised this value, which nothing did.
///
/// A client sorting by it, thresholding it against a constant, or storing it to compare with
/// tomorrow's is doing three things, and only the first is defined.
///
/// # `f64`, and the framework's rather than the engines'
///
/// The members' own currencies never enter — an engine's [`Score`](crate::FulltextEngine::Score) is
/// untranslated all the way to the evidence, and the fold reads its ORDINAL instead. So the width
/// here is chosen for the arithmetic and not to match anybody: a sum of up to N terms each in
/// `(0, 1]`, where the terms differ by factors of thousands once a member's ordinals run deep, and
/// `f32` loses the small ones under the large ones exactly where the fold is deciding a close call.
///
/// # The total order, and the one value the constructor refuses
///
/// `NaN` is the only `f64` for which `partial_cmp` answers `None`, and refusing it at construction
/// is what makes [`Ord`] a fact about this type rather than a convention its users keep. That is
/// [`Score`](crate::Score)'s own move, made here for the same reason and at a different range: this
/// type has NO range to check, an unbounded sum being what it is, so the refusal is `NaN` alone.
///
/// The infinities are ADMITTED, which is the honest reading rather than an oversight: they order
/// totally against everything else, and refusing them would put a fallible constructor in the
/// middle of a fold whose inputs cannot produce one anyway — `1 / (k + rank)` with a rank of at
/// least one is finite by construction.
#[derive(Debug, Clone, Copy, PartialEq)]
pub struct FusedScore(f64);

impl FusedScore {
  /// A root no member ranked — the additive identity, and what an accumulator starts at.
  pub const ZERO: Self = Self(0.0);

  /// Build a fused score, or refuse a `NaN`.
  ///
  /// `-0.0` is accepted and normalised to `+0.0`: it passes the check, compares equal to `+0.0` and
  /// carries different bits, so admitting it unchanged would make two equal values disagree the
  /// moment anything hashes one.
  #[inline]
  #[must_use]
  pub fn new(value: f64) -> Option<Self> {
    if value.is_nan() {
      return None;
    }
    // `+ 0.0` maps -0.0 to +0.0 and is the identity on every other value, the infinities included.
    Some(Self(value + 0.0))
  }

  /// The wrapped value, never `NaN`.
  #[inline]
  #[must_use]
  pub const fn get(&self) -> f64 {
    self.0
  }
}

// `PartialEq` is derived and `Eq` is not, because only one of the two is a statement about `f64`:
// its equality is already the right one here, and its REFLEXIVITY is a property of THIS type — `x ==
// x` fails for `NaN` alone, and a fused score is never one.
impl Eq for FusedScore {}

impl Ord for FusedScore {
  /// Total because [`FusedScore::new`] refuses `NaN`.
  #[inline]
  fn cmp(&self, other: &Self) -> core::cmp::Ordering {
    self
      .0
      .partial_cmp(&other.0)
      .expect("a fused score is never NaN")
  }
}

impl PartialOrd for FusedScore {
  #[inline]
  fn partial_cmp(&self, other: &Self) -> Option<core::cmp::Ordering> {
    Some(self.cmp(other))
  }
}

#[cfg(test)]
mod tests;