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 two shapes the fold moves between: [`Rooted`] going in, [`Fused`] coming out.

use super::{FusedScore, Sighting};

/// ONE member's answer about ONE root: where that member put it, and what that member saw.
///
/// This is what a member's ranked list becomes on the way into [`fuse`](super::fuse), and the
/// projection is the EMISSION's act rather than this type's — a key's root is its own root-first
/// prefix, and only the code that can see the key's shape can take it.
///
/// # Three members, and the fold reads two of them
///
/// `root` is what the join happens at. `rank` is the ENGINE ordinal the member's survivor wore, and
/// it is the whole of the fold's arithmetic. `evidence` the fold never opens: it carries it to the
/// [`Fused`] that comes out, ordered by how much it contributed, and asks NOTHING of the type.
///
/// # Why `evidence` is a parameter and not a read through a trait
///
/// The alternative was a trait the emitted evidence enum implements, so the fold could read the rank
/// back out of it. It buys one fewer field and costs every emitted enum an impl — and the rank it
/// would read is a number the caller is holding anyway at the moment it builds this. A bound that
/// recovers what the call site already has is a bound with nothing behind it.
///
/// # The rank is the RAW ordinal, and passing the list position instead is a silent defect
///
/// [`Ranked::rank`](crate::Ranked::rank) is the number, not `position()` in the survivor list. The
/// two agree exactly when nothing was dropped, so a call site that passes the wrong one produces a
/// perfectly ordered answer on every fixture whose floor let everything through — which is why the
/// distinction is written here, where the number is taken.
#[derive(Debug, Clone, PartialEq)]
pub struct Rooted<R, V> {
  root: R,
  rank: u64,
  evidence: V,
}

impl<R, V> Rooted<R, V> {
  /// State that a member ranked `root` at `rank`, and what it saw there.
  ///
  /// Arguments in field order, so a call site reads as the record does.
  #[inline]
  pub const fn new(root: R, rank: u64, evidence: V) -> Self {
    Self {
      root,
      rank,
      evidence,
    }
  }

  /// The root this member's hit projects to, BORROWED.
  #[inline(always)]
  pub const fn root_ref(&self) -> &R {
    &self.root
  }

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

  /// What the member saw, BORROWED.
  #[inline(always)]
  pub const fn evidence_ref(&self) -> &V {
    &self.evidence
  }

  /// Take all three, none cloned.
  ///
  /// In FIELD order, which is also the order [`new`](Self::new) takes them back in.
  #[inline]
  pub fn into_components(self) -> (R, u64, V) {
    (self.root, self.rank, self.evidence)
  }
}

/// One row of a fused answer: the framework's score, the root it is about, and every member's
/// evidence for it.
///
/// # `R` is the root at two tiers, exactly as [`Ranked`](crate::Ranked)'s node is
///
/// The root KEY where the caller asked for keys, and the whole hydrated root ENTITY where it asked
/// for entities — the second reached through the same address lanes tier B already walks. One
/// parameter covers both because the fold never looks at it beyond joining on it.
///
/// # `V` is the EMITTED evidence, and it is a parameter because it has to be
///
/// The ruling spells this type `Fused<R>` and, in the same clause, names the evidence as *the
/// EMITTED per-root evidence enum (variant per member, carrying that member's `Ranked<Key, Score>`)*
/// — a type minted per graph root, since its variants ARE that root's member table. A framework
/// struct cannot hold a type the emission mints, so the two halves of that clause are simultaneously
/// satisfiable only with the evidence as a second parameter. The emission instantiates
/// `Fused<MediaKey, MediaEvidence>` and the ruled shape is what a reader of the emitted signature
/// sees.
///
/// # `evidence` is a LIST, and its order is the ruling's
///
/// One entry per member that ranked this root — never per member in the catalog, since a member that
/// did not rank it has nothing to say — ordered by CONTRIBUTION DESCENDING. That is the UI's primary
/// jump point first: the entry at index 0 is the member whose ranking moved this root the most, and
/// it is the one to open when a user clicks the result.
///
/// # THE CONTRIBUTION IS CARRIED, and carrying it is merely not stripping it
///
/// The entry is a [`Sighting`] — the member's own evidence beside the WEIGHTED term it added to the
/// score above. Until the #296-L2 ruling the list was a bare `Vec<V>` and this note argued the other
/// way: the number was `1 / (k + rank)`, the rank rode inside the member's own `Ranked`, so a client
/// computed it and a stored copy was a second version that could disagree.
///
/// The wire road ended that argument. A client reading a union variant has no `k`, no weight and no
/// local to recompute from, and the order alone cannot say whether the leading entry led by a nose
/// or by a mile. And the disagreement clause does not survive the carry: a number taken FROM the
/// fold cannot disagree with the fold, because it IS the fold's — what could disagree was the
/// recomputation.
#[derive(Debug, Clone, PartialEq)]
pub struct Fused<R, V> {
  score: FusedScore,
  root: R,
  evidence: Vec<Sighting<V>>,
}

impl<R, V> Fused<R, V> {
  /// Assemble a fused row.
  ///
  /// `evidence` is taken as it stands, in contribution order — [`fuse`](super::fuse) is what puts it
  /// in that order, and this constructor does not re-sort what it is handed. Written so an emitted
  /// face mapping the root across a hydration can rebuild the row without the fold running twice.
  #[inline]
  pub const fn new(score: FusedScore, root: R, evidence: Vec<Sighting<V>>) -> Self {
    Self {
      score,
      root,
      evidence,
    }
  }

  /// The fused score — comparable against the other rows of THIS answer, and nothing else.
  #[inline(always)]
  pub const fn score(&self) -> FusedScore {
    self.score
  }

  /// The root, BORROWED.
  #[inline(always)]
  pub const fn root_ref(&self) -> &R {
    &self.root
  }

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

  /// Every member's evidence for this root, CONTRIBUTION-ORDERED — the biggest mover first.
  #[inline(always)]
  pub fn evidence(&self) -> &[Sighting<V>] {
    &self.evidence
  }

  /// Take all three, none cloned — for a wire mapping, or for a hydration carrying the score and
  /// the evidence across.
  #[inline]
  pub fn into_components(self) -> (FusedScore, R, Vec<Sighting<V>>) {
    (self.score, self.root, self.evidence)
  }

  /// The same row with a DIFFERENT root, the score and the evidence carried across.
  ///
  /// The tier-B move, and [`Ranked::map_node`](crate::Ranked::map_node)'s own reason for existing:
  /// a fused KEY becomes a fused ENTITY, and the score and the evidence are the fold's answer about
  /// THAT root rather than about the row the store found under it. Written here so the carry cannot
  /// pick either up from somewhere else.
  #[inline]
  pub fn map_root<U>(self, root: U) -> Fused<U, V> {
    Fused {
      score: self.score,
      root,
      evidence: self.evidence,
    }
  }
}

#[cfg(test)]
mod tests;