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
//! [`RoutedProbe`] — one dispatch: which lane, and what to ask it.

use crate::LaneIdent;

#[cfg(test)]
mod tests;

/// **ONE DISPATCH** — a lane, and the probe to ask it with.
///
/// # A NAMED CARRIER rather than a tuple
///
/// `(LaneIdent, R)` would say the same thing and say it worse: which half is which is positional,
/// two of them cannot be told apart in a signature, and neither half can grow a name. This is the
/// same construction [`Ranked`](crate::Ranked) and [`Rooted`](crate::Rooted) already make one layer
/// over, and it is a SISTER of the expand step's own carrier — same law, different road, and neither
/// names the other.
///
/// # THE CONSUMPTION CONTRACT
///
/// A router answers a `Vec` of these, and every element of it is **one independent dispatch and one
/// ranked stream**. Three things follow, and all three are the ruling's own:
///
/// - **Several probes may name ONE lane.** The mechanism allows it — a router that wants a lane
///   asked twice with two probes gets two streams and the fold counts both. Whether that is wise is
///   the router's own discipline, and the shipped [`ScriptRouter`](super::ScriptRouter) exercises it
///   by MERGING the runs that land in one lane rather than emitting them separately.
/// - **The order does not enter the score.** Reciprocal rank fusion reads each stream's own
///   ordinals, so where a probe sat in the `Vec` is worth nothing — what it is worth is the STABLE
///   TIE ORDER, because the fold's sort is stable and equal scores come back in first-sighting
///   order.
/// - **Empty is the empty set.** No probes means no streams means an empty answer, which is a
///   result rather than a refusal.
///
/// # The four-piece vocabulary, in full
///
/// Both seats carry the consuming [`with_`](Self::with_lane) and the in-place [`set_`](Self::set_lane)
/// forms beside the accessors, because both are genuinely narrowable: a middleware wrapping a router
/// re-points a probe at another lane, and one rewriting the probe's text leaves the lane alone. That
/// is the difference from [`ScriptRun`](crate::ScriptRun), whose three seats are one fact and carry
/// no setters at all.
/// # NO [`Eq`] AND NO [`Hash`], and the weight is why
///
/// A `f64` has neither, and this row carries one. That is the same trade
/// [`Member`](crate::Member) and [`Route`](crate::Route) already take one layer over — the two other
/// weight-carrying rows in this crate — and it costs nothing a dispatch plan does: a plan is walked
/// in order, never keyed on.
#[derive(Debug, Clone, Copy, PartialEq)]
pub struct RoutedProbe<R> {
  /// The lane this dispatch is for.
  lane: &'static LaneIdent,
  /// What to ask it with.
  probe: R,
  /// How much this stream's opinion counts in the fold.
  weight: f64,
}

impl<R> RoutedProbe<R> {
  /// **THE UNWEIGHTED WEIGHT** — the multiplicative identity, and what a dispatch carries unless a
  /// router says otherwise.
  ///
  /// [`Route::DEFAULT_WEIGHT`](crate::Route::DEFAULT_WEIGHT)'s own value and its own reason: a plan
  /// where nobody weighted anything runs the unweighted fold exactly.
  pub const UNWEIGHTED: f64 = 1.0;

  /// Ask `lane` with `probe`.
  #[inline]
  #[must_use]
  pub const fn new(lane: &'static LaneIdent, probe: R) -> Self {
    Self {
      lane,
      probe,
      weight: Self::UNWEIGHTED,
    }
  }

  /// The lane this dispatch is for.
  #[inline]
  #[must_use]
  pub const fn lane(&self) -> &'static LaneIdent {
    self.lane
  }

  /// What it asks with.
  #[inline]
  #[must_use]
  pub const fn probe(&self) -> &R {
    &self.probe
  }

  /// **HOW MUCH THIS STREAM'S OPINION COUNTS** in the fold — the multiplicative identity unless a
  /// router said otherwise.
  ///
  /// It is the coefficient [`fuse_weighted`](crate::fuse_weighted) multiplies this lane's every RRF
  /// term by, so a plan whose weights are all [`UNWEIGHTED`](Self::UNWEIGHTED) fuses exactly as the
  /// unweighted fold does — which is what makes the seat free for every router that has no opinion.
  ///
  /// # It is a WEIGHT and never a score
  ///
  /// [`Route::weight`](crate::Route::weight)'s own law, one road over: a weight is what a caller
  /// believes about a STREAM, and it multiplies every term that stream contributes. It never meets a
  /// score and never touches an ordinal.
  #[inline]
  #[must_use]
  pub const fn weight(&self) -> f64 {
    self.weight
  }

  /// The same dispatch, counting `weight` in the fold.
  #[inline]
  #[must_use]
  pub fn with_weight(mut self, weight: f64) -> Self {
    self.set_weight(weight);
    self
  }

  /// [`with_weight`](Self::with_weight), in place.
  #[inline]
  pub const fn set_weight(&mut self, weight: f64) -> &mut Self {
    self.weight = weight;
    self
  }

  /// The same probe, pointed at `lane` instead.
  #[inline]
  #[must_use]
  pub fn with_lane(mut self, lane: &'static LaneIdent) -> Self {
    self.set_lane(lane);
    self
  }

  /// [`with_lane`](Self::with_lane), in place.
  #[inline]
  pub const fn set_lane(&mut self, lane: &'static LaneIdent) -> &mut Self {
    self.lane = lane;
    self
  }

  /// The same lane, asked with `probe` instead.
  #[inline]
  #[must_use]
  pub fn with_probe(mut self, probe: R) -> Self {
    self.set_probe(probe);
    self
  }

  /// [`with_probe`](Self::with_probe), in place.
  #[inline]
  pub fn set_probe(&mut self, probe: R) -> &mut Self {
    self.probe = probe;
    self
  }

  /// The probe alone, for a caller that already knows which lane it is walking.
  #[inline]
  #[must_use]
  pub fn into_probe(self) -> R {
    self.probe
  }

  /// ALL THREE SEATS, owned — what a fan spends when it reads one lane, keeps the key to attribute
  /// the stream with, and hands the weight to the fold.
  ///
  /// WIDENED rather than joined by a second door when the weight arrived: `into_components` is *every
  /// seat this row has*, which is what [`Rooted`](crate::Rooted) and [`ScriptRun`](crate::ScriptRun)
  /// already mean by the name. Two doors onto one fact is the shape this crate refuses everywhere,
  /// so the tuple grew and the seats stayed in declaration order.
  #[inline]
  #[must_use]
  pub fn into_components(self) -> (&'static LaneIdent, R, f64) {
    (self.lane, self.probe, self.weight)
  }

  /// The same dispatch, carrying a probe of another type.
  ///
  /// THE LANE AND THE WEIGHT SURVIVE IT — only the probe crosses. A router that produces text and a
  /// store that
  /// is asked in its own probe type meet somewhere, and the lane must survive that crossing
  /// untouched. Written once rather than at each such meeting, which is
  /// [`Fused::map_root`](crate::Fused::map_root)'s own reason one layer over.
  #[inline]
  #[must_use]
  pub fn map_probe<T>(self, into: impl FnOnce(R) -> T) -> RoutedProbe<T> {
    RoutedProbe {
      lane: self.lane,
      probe: into(self.probe),
      weight: self.weight,
    }
  }
}