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
//! ONE ENTRY OF A FUSED ANSWER'S PROVENANCE — [`Sighting`], what a member said about a root and how
//! much that saying moved it.
//!
//! ```text
//! Fused { score, root, evidence: [ Sighting { contribution, ordinal, seen }, … ] }
//!                                         │          │        └── the member's own evidence
//!                                         │          └── the RANK that term was computed from
//!                                         └── the WEIGHTED term it added to `score`
//! ```
//!
//! # It exists because the fold stopped stripping what it computes
//!
//! `fuse_weighted` multiplies a member's reciprocal-rank term by that member's weight, adds the
//! product into the root's score, and ORDERS the evidence by it. Until this type the product was
//! then dropped, and the evidence list was a bare `Vec<V>` whose order was the only trace left of a
//! number the fold had held in a local.
//!
//! That was defensible while the answer was Rust-only: a caller with the member's own `Ranked` could
//! recompute `1 / (k + rank)`, and a stored copy is a number that can disagree with the one the fold
//! used. The wire road ends it. A client reading a union variant has no `k`, no weight and no local
//! to recompute from, and the ordering alone cannot say whether the first entry led by a nose or by
//! a mile — so the number the fold already has is carried instead of computed twice.
//!
//! The recomputation argument does not survive the carry either, which is the part worth stating: a
//! number carried FROM the fold cannot disagree with the fold, because it IS the fold's. What could
//! disagree was the recomputation.
//!
//! # `Sighting` and [`Sightings`](crate::Sightings) are different things
//!
//! The plural one is the SET door's — how many of an entity's own vectors a stream ranked, and where
//! — and it belongs to the fold that accumulates across `m` query vectors. This one is a FUSED
//! answer's, one entry per member that ranked a root. Neighbouring words for neighbouring ideas, and
//! neither is the other's shorthand.

/// ONE MEMBER'S SIGHTING of a fused root — its own evidence, and the weighted term it contributed.
///
/// # The contribution is `f64` at every grain, and that is the framework's arithmetic rather than an
/// engine's
///
/// A member's own SCORE is that member's engine's currency and crosses as itself; the CONTRIBUTION
/// is what the fold made of that member's RANK, in the fold's own arithmetic — `weight × 1/(k+rank)`
/// — so it is one type however many currencies met. The same split [`FusedScore`](super::FusedScore)
/// already states one level up: what fuses is ordinals, and the numbers fusion produces are the
/// framework's.
///
/// # `Copy` where the evidence is, and `PartialEq` unconditionally on the pair
///
/// The derives follow `V`, so a sighting over an emitted evidence enum has exactly the faces that
/// enum has. Nothing here demands more of `V` than the answer it sits inside already does.
#[derive(Debug, Clone, Copy, PartialEq)]
pub struct Sighting<V> {
  contribution: f64,
  ordinal: u64,
  seen: V,
}

impl<V> Sighting<V> {
  /// Assemble one entry.
  ///
  /// `const`, and taken as it stands: the fold is what computes the contribution, and a constructor
  /// that recomputed or validated it would be a second opinion about a number that has one source.
  #[inline]
  pub const fn new(contribution: f64, ordinal: u64, seen: V) -> Self {
    Self {
      contribution,
      ordinal,
      seen,
    }
  }

  /// THE WEIGHTED TERM this sighting added to the root's fused score.
  ///
  /// Finite and positive by construction — the fold's own denominator floor is what makes it so —
  /// and it is the key the evidence list is ordered by, descending.
  #[inline(always)]
  pub const fn contribution(&self) -> f64 {
    self.contribution
  }

  /// THE RANK this member gave the root — the 1-based ordinal in that member's own stream, and the
  /// number the contribution above was computed FROM.
  ///
  /// # It is carried rather than inferred, and #296-L3 is the measurement that settled it
  ///
  /// The alternative was to publish nothing and let a reader recover it. Three roads were measured
  /// and all three are closed:
  ///
  /// - the evidence ARRAY's order is the cross-route contribution order of ONE hit's sightings —
  ///   a different axis entirely from any route's in-stream position;
  /// - `contribution = weight / (k + rank)` is two unknowns in one equation, and the weight is a
  ///   parent's belief that never crosses the wire;
  /// - the scores are per-route currencies, so they do not compare across variants at all.
  ///
  /// RRF's INPUT is the rank. Provenance without it tells the story minus its middle term.
  #[inline(always)]
  pub const fn ordinal(&self) -> u64 {
    self.ordinal
  }

  /// What the member itself said — its own evidence, in its own currency.
  #[inline(always)]
  pub const fn seen(&self) -> &V {
    &self.seen
  }

  /// All three, none cloned — for a wire mapping, or a hydration carrying the provenance across.
  #[inline]
  pub fn into_components(self) -> (f64, u64, V) {
    (self.contribution, self.ordinal, self.seen)
  }

  /// The same sighting over a DIFFERENT evidence, the contribution carried across.
  ///
  /// [`Fused::map_root`](super::Fused::map_root)'s reason one grain down: an emitted face maps a
  /// member's evidence into its wire shape, and the contribution and the ordinal are the FOLD's
  /// answers about that sighting rather than anything the mapping produced.
  #[inline]
  pub fn map_seen<U, F>(self, f: F) -> Sighting<U>
  where
    F: FnOnce(V) -> U,
  {
    Sighting {
      contribution: self.contribution,
      ordinal: self.ordinal,
      seen: f(self.seen),
    }
  }
}

#[cfg(test)]
mod tests;