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 FOLD AT THE MOUTH** — where a tower's fan closes, and where its two laws are structural.
//!
//! ```text
//! arm₀ (the original)  ×  lane_en  ─▶ tail ─▶ ranked stream ─┐
//! arm₀                 ×  lane_ja  ─▶ tail ─▶ ranked stream ─┤
//! arm₁ (a paraphrase)  ×  lane_en  ─▶ tail ─▶ ranked stream ─┼─ (F) dedup ─▶ (D) weights ─▶ fuse
//! arm₁                 ×  lane_ja  ─▶ tail ─▶ ranked stream ─┘
//! ```
//!
//! A [`tower`](crate::retrieve::tower) may contain FANNING SEGMENTS — a widening at ②, a crossing at
//! ④ — and the tower law's amendment is that every fan folds before the tower's mouth, so the outer
//! contract stays 1 → 1. This module is the fold that closes them, and the two rulings that shaped
//! it live in the two places nothing can route around:
//!
//! - **(D) MULTIPLY IS LAW.** A cell's coefficient is `arm × lane`, and the only door into a cell is
//!   [`FanStream::new`], which takes the two numbers and multiplies them. There is no seat holding a
//!   pre-composed weight, so there is no way to hand the fold a product it did not compute.
//! - **(F) ONE QUESTION'S FAMILY IS ONE WITNESS.** [`fuse_fanned`] deduplicates on FULL EVIDENCE
//!   IDENTITY `(root, evidence)` across the ARMS of one lane before a single term is computed, so
//!   two paraphrases of one question that found the same thing count once.
//!
//! # WHY THE DEDUP IS ACROSS ARMS AND NOT ACROSS LANES
//!
//! Reciprocal rank fusion measures AGREEMENT BETWEEN SOURCES, and the two axes of this grid are not
//! the same kind of thing. Two LANES are two indexes: a root that both the English and the Japanese
//! lane ranked was found twice, by two readers, and that is the agreement the fold exists to reward.
//! Two ARMS are one question said twice — the caller's own words and an expander's paraphrase of
//! them — so a root both arms found was found ONCE, by one reader, and counting it twice would be
//! measuring how many synonyms an expander happens to know.
//!
//! # AND WHY THE IDENTITY IS `(R, V)` RATHER THAN `R`
//!
//! Because the framework does not know what a root's evidence means, and must not guess. A product
//! whose evidence carries a time locus has two entries under one root that are genuinely two
//! findings — the same video at two different moments — and one that carries nothing has two entries
//! under one root that are genuinely one. Keying on the full pair lets each product's own `V: Eq`
//! settle it, which is the layering theorem rather than a framework policy: **no domain vocabulary
//! enters here, and the equality spent is the product's own.**

use crate::LaneIdent;

use super::{Fused, Fusion, Join, Rooted, fuse_weighted};

#[cfg(test)]
mod tests;

/// **WHAT A FANNED TOWER'S TAIL ANSWERS**, and the seat the mouth reads its two parameters off.
///
/// A fanned tower's outer answer is `Vec<Fused<R, V>>` — one value, the amendment's 1 → 1 contract
/// kept — and the emission has to name `R` and `V` to say so. It cannot take them apart from the
/// type its author WROTE: a tail answering `MyStream` or a type alias is a token sequence, and a
/// macro that pattern-matched on the spelling would be reading a name instead of a type. So the two
/// are PROJECTED through this seam, and what a declaration writes at its last step decides them.
///
/// # It is OPEN, and the blanket is the shipped case rather than the only one
///
/// `Vec<Rooted<R, V>>` — what every read walk in this crate already answers in — wears it through
/// the blanket below and costs a declaration nothing. A tail that answers in its own carrier
/// implements this by hand and joins, which is the framework-open discipline the whole retrieve tier
/// keeps: the fold names no product type, and a product names no fold.
#[diagnostic::on_unimplemented(
  message = "`{Self}` is not a ranked stream, so a fanned tower cannot fold it",
  label = "no ranked stream",
  note = "the LAST step of a fanned tower answers what its lanes found — `Vec<Rooted<Root, \
          Evidence>>` wears this row already; a tail answering its own carrier writes `impl \
          RankedStream for {Self}` and states the two types it folds at"
)]
pub trait RankedStream {
  /// What the fold JOINS at — a hit's root, in whatever currency the tail reports one.
  type Root;

  /// What the tail SAW, carried whole to the fused row and opened by nobody here.
  type Evidence;

  /// The stream, as the fold reads one: hits wearing their ENGINE ordinals.
  fn into_ranked(self) -> Vec<Rooted<Self::Root, Self::Evidence>>;
}

/// The shipped tail: a ranked stream IS a list of rooted hits, and the conversion is identity.
impl<R, V> RankedStream for Vec<Rooted<R, V>> {
  type Root = R;
  type Evidence = V;

  #[inline]
  fn into_ranked(self) -> Self {
    self
  }
}

/// **ONE CELL OF A FAN'S GRID** — which lane, which arm, what the cell is worth, and what it found.
///
/// ```
/// use ingraph::{ArmWeights, FanStream, LaneIdent, Rooted, RoutedProbe};
///
/// // (D) MULTIPLY IS LAW: the paraphrase arm's 0.5 meets the emphasised lane's 2.0.
/// let cell = FanStream::new(
///   LaneIdent::new("ja"),
///   1,
///   ArmWeights::DEFAULT_ARM_WEIGHT,
///   2.0,
///   vec![Rooted::new(7_u32, 1, ())],
/// );
///
/// assert_eq!(cell.weight(), 1.0);
/// assert_eq!(cell.arm(), 1);
///
/// // The axis a tower did not open is the identity on that side, and it is spelled rather than
/// // guessed.
/// let uncut = FanStream::uncut(0, ArmWeights::ORIGINAL, vec![Rooted::new(7_u32, 1, ())]);
/// assert_eq!(uncut.lane(), LaneIdent::UND);
/// assert_eq!(uncut.weight(), RoutedProbe::<()>::UNWEIGHTED);
/// ```
///
/// # THE WEIGHT CANNOT BE HANDED IN, and that is (D) as a shape
///
/// The ruling is *multiply is law, and it is not configurable*. A seat taking a composed coefficient
/// would make the law a convention every caller re-keeps, so there is no such seat: the constructor
/// takes the ARM's number and the LANE's number and the product is the only thing stored. What a
/// deployment tunes is the two inputs, at the two places that own them —
/// [`ArmWeights`](crate::ArmWeights) at the widening step, and the router's own emphasis at the
/// crossing.
///
/// # The ARM is a POSITION and not a name
///
/// [`arm`](Self::arm) is the entry's place in the expansion family, and `0` is the original —
/// [`Expansion::expand`](crate::Expansion::expand)'s own law, which pins the caller's question at
/// the head of the road. The dedup needs to tell *the same lane, a different arm* from *the same
/// lane, the same arm asked twice*, and a position is the one fact that distinguishes them; the arm's
/// LABEL is [`ExpandOrigin`](crate::ExpandOrigin)'s and it has already been spent, on the weight.
#[derive(Debug, Clone, PartialEq)]
pub struct FanStream<R, V> {
  /// The lane this cell was read from.
  lane: &'static LaneIdent,
  /// Which arm of the expansion family asked — `0` being the original.
  arm: usize,
  /// The COMPOSED coefficient: arm × lane, multiplied at construction and never handed in.
  weight: f64,
  /// What the cell found, wearing the engine's own ordinals.
  ranked: Vec<Rooted<R, V>>,
}

impl<R, V> FanStream<R, V> {
  /// One cell: `arm` asked `lane`, at `arm_weight` × `lane_weight`, and found `ranked`.
  ///
  /// **THE MULTIPLICATION HAPPENS HERE AND NOWHERE ELSE** — see the type note.
  #[inline]
  #[must_use]
  pub fn new(
    lane: &'static LaneIdent,
    arm: usize,
    arm_weight: f64,
    lane_weight: f64,
    ranked: Vec<Rooted<R, V>>,
  ) -> Self {
    Self {
      lane,
      arm,
      weight: arm_weight * lane_weight,
      ranked,
    }
  }

  /// The cell of a fan that WIDENS BUT DOES NOT CROSS — one lane, and it is the roster's default.
  ///
  /// [`LaneIdent::UND`] is what a slot that declared no lanes holds, so a tower that opened no
  /// crossing is not a special case here: it is a corpus of one lane, read once, at the unweighted
  /// coefficient every dispatch carries unless a router says otherwise.
  #[inline]
  #[must_use]
  pub fn uncut(arm: usize, arm_weight: f64, ranked: Vec<Rooted<R, V>>) -> Self {
    Self::new(
      LaneIdent::UND,
      arm,
      arm_weight,
      crate::RoutedProbe::<()>::UNWEIGHTED,
      ranked,
    )
  }

  /// The cell of a fan that CROSSES BUT DOES NOT WIDEN — the sole arm, at the original's weight.
  #[inline]
  #[must_use]
  pub fn unwidened(lane: &'static LaneIdent, lane_weight: f64, ranked: Vec<Rooted<R, V>>) -> Self {
    Self::new(lane, 0, crate::ArmWeights::ORIGINAL, lane_weight, ranked)
  }

  /// The lane this cell was read from.
  #[inline]
  #[must_use]
  pub const fn lane(&self) -> &'static LaneIdent {
    self.lane
  }

  /// Which arm of the family asked — `0` being the caller's own question.
  #[inline]
  #[must_use]
  pub const fn arm(&self) -> usize {
    self.arm
  }

  /// **THE COMPOSED COEFFICIENT** — arm × lane, as [`new`](Self::new) multiplied it.
  #[inline]
  #[must_use]
  pub const fn weight(&self) -> f64 {
    self.weight
  }

  /// What the cell found, BORROWED.
  #[inline]
  #[must_use]
  pub fn ranked(&self) -> &[Rooted<R, V>] {
    &self.ranked
  }

  /// All four seats, owned — what the fold spends.
  #[inline]
  #[must_use]
  pub fn into_components(self) -> (&'static LaneIdent, usize, f64, Vec<Rooted<R, V>>) {
    (self.lane, self.arm, self.weight, self.ranked)
  }
}

/// **THE FOLD AT THE MOUTH** — a fan's whole grid in, one ranked answer out.
///
/// ```text
/// grid ─▶ (F) one family, one witness ─▶ (D) each cell at arm × lane ─▶ fuse_weighted ─▶ answer
/// ```
///
/// # It is [`fuse_weighted`] with ONE STAGE IN FRONT OF IT, and not a second fold
///
/// Every sentence of the fold's own note holds here verbatim: no member's score enters, the ordinal
/// is the engine's raw one, a member is counted once per root, the sort is stable and equal scores
/// come back in first-sighting order. What this adds is the family dedup — the one thing the fan
/// road knows that the fold cannot: which cells were the SAME QUESTION asked in different words.
///
/// # THE SURVIVOR IS THE BEST RANK, and the tie goes to the earlier arm
///
/// Where two arms of one lane found the same `(root, evidence)`, the entry at the LOWER engine
/// ordinal survives and the other is dropped whole. A tie keeps the entry already held, and since
/// the grid arrives in arm order and the original is arm `0`, a tie keeps the caller's own question's
/// finding.
///
/// **The consequence is worth stating**: the survivor carries ITS OWN cell's coefficient, so a
/// paraphrase that ranked something higher than the original did contributes at the paraphrase's
/// weight. That is the ruling read literally — *best rank surviving* — rather than a rank moved onto
/// another arm's entry, which would be this layer inventing an ordinal no engine reported.
///
/// # The bounds, and where each is spent
///
/// `J` is the join's mechanism, last, for [`fuse`](super::fuse)'s own reason. `V: Eq` is the FAMILY
/// dedup's and lands HERE rather than on [`fuse_weighted`], which asks nothing of `V` and must go on
/// asking nothing: a fold that demanded equality of an evidence type would tax every unfanned member
/// in the tree for a law only a fan has.
pub fn fuse_fanned<R, V, J>(grid: Vec<FanStream<R, V>>, fusion: Fusion) -> Vec<Fused<R, V>>
where
  J: Join<R>,
  V: Eq,
{
  let survivors = survivors::<R, V, J>(&grid);
  let members = grid
    .into_iter()
    .zip(survivors)
    .map(|(cell, kept)| {
      let (_, _, weight, ranked) = cell.into_components();
      let ranked = ranked
        .into_iter()
        .zip(kept)
        .filter_map(|(hit, keep)| keep.then_some(hit))
        .collect();
      (weight, ranked)
    })
    .collect();
  fuse_weighted::<R, V, J>(members, fusion)
}

/// **(F), AS A MASK** — which entries of which cells survive the family dedup.
///
/// A mask rather than a rebuilt grid, because the comparison needs every cell's evidence in hand
/// while it decides: a walk that moved entries out as it went would be reading a collection it was
/// also draining. The mask is `Vec<Vec<bool>>` in the grid's own shape, so applying it is a zip.
///
/// The lanes are grouped in FIRST-APPEARANCE order and each group is walked in the grid's own order,
/// which is arm-major — that is what makes *the tie goes to the earlier arm* a property of the walk
/// rather than a comparison written down.
fn survivors<R, V, J>(grid: &[FanStream<R, V>]) -> Vec<Vec<bool>>
where
  J: Join<R>,
  V: Eq,
{
  let mut keep: Vec<Vec<bool>> = grid
    .iter()
    .map(|cell| vec![true; cell.ranked.len()])
    .collect();

  let mut lanes: Vec<(&'static LaneIdent, Vec<usize>)> = Vec::new();
  for (at, cell) in grid.iter().enumerate() {
    match lanes.iter_mut().find(|(lane, _)| **lane == *cell.lane) {
      Some((_, cells)) => cells.push(at),
      None => lanes.push((cell.lane, vec![at])),
    }
  }

  for (_, cells) in lanes {
    let mut join = J::empty();
    // Per root, the entries still standing — `(cell, entry)` rather than a borrow, because the
    // decision below both reads the grid and writes the mask.
    let mut witnessed: Vec<Vec<(usize, usize)>> = Vec::new();

    for cell in cells {
      for (entry, hit) in grid[cell].ranked.iter().enumerate() {
        let at = match join.place(hit.root_ref()) {
          Some(at) => at,
          None => {
            witnessed.push(Vec::new());
            witnessed.len() - 1
          }
        };
        // A witness from ANOTHER ARM with the same evidence is the same finding said twice. One
        // arm's own repeats are left alone: a router may legitimately ask one lane with two probes,
        // and the fold's own once-per-member rule is what answers that.
        let found = witnessed[at].iter().position(|&(held, seen)| {
          grid[held].arm != grid[cell].arm
            && grid[held].ranked[seen].evidence_ref() == hit.evidence_ref()
        });
        match found {
          Some(pos) => {
            let (held, seen) = witnessed[at][pos];
            if hit.rank() < grid[held].ranked[seen].rank() {
              keep[held][seen] = false;
              witnessed[at][pos] = (cell, entry);
            } else {
              keep[cell][entry] = false;
            }
          }
          None => witnessed[at].push((cell, entry)),
        }
      }
    }
  }

  keep
}