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, at unit grain: the weight product, the family dedup, and the two
//! degenerate axes.

use crate::{ArmWeights, ExpandOrigin, HashJoin, LaneIdent, RoutedProbe};

use super::{FanStream, Fusion, RankedStream, Rooted, fuse_fanned};

/// The two lanes every grid below is cut into.
static EN: &LaneIdent = LaneIdent::new("en");
static JA: &LaneIdent = LaneIdent::new("ja");

/// A cell, spelled the way the walk spells one.
fn cell(
  lane: &'static LaneIdent,
  arm: usize,
  arm_weight: f64,
  lane_weight: f64,
  ranked: &[(u32, u64, u8)],
) -> FanStream<u32, u8> {
  FanStream::new(
    lane,
    arm,
    arm_weight,
    lane_weight,
    ranked
      .iter()
      .map(|&(root, rank, seen)| Rooted::new(root, rank, seen))
      .collect(),
  )
}

/// The fused answer's roots, in order.
fn roots(grid: Vec<FanStream<u32, u8>>) -> Vec<u32> {
  fuse_fanned::<u32, u8, HashJoin<u32>>(grid, Fusion::rrf())
    .into_iter()
    .map(|row| row.into_components().1)
    .collect()
}

/// **(D) MULTIPLY IS LAW**, and the product is the only thing the cell stores.
#[test]
fn a_cells_coefficient_is_the_two_numbers_multiplied() {
  let composed = cell(JA, 1, ArmWeights::DEFAULT_ARM_WEIGHT, 2.0, &[(7, 1, 0)]);
  assert!((composed.weight() - 1.0).abs() < 1e-12);
  assert_eq!(composed.arm(), 1);
  assert_eq!(composed.lane(), JA);

  // The identity on either side leaves the other number standing.
  assert!(
    (cell(EN, 0, ArmWeights::ORIGINAL, 2.0, &[]).weight() - 2.0).abs() < 1e-12,
    "the original arm carries the lane's emphasis whole",
  );
  assert!(
    (cell(EN, 2, 0.25, RoutedProbe::<()>::UNWEIGHTED, &[]).weight() - 0.25).abs() < 1e-12,
    "an unweighted lane carries the arm's own number whole",
  );
}

/// **THE TWO DEGENERATE AXES ARE SPELLED**, so a tower that opened one segment is not a special case.
#[test]
fn the_axis_a_tower_did_not_open_is_the_identity_on_that_side() {
  let uncut = FanStream::uncut(
    1,
    ArmWeights::DEFAULT_ARM_WEIGHT,
    vec![Rooted::new(1_u32, 1, 0_u8)],
  );
  assert_eq!(uncut.lane(), LaneIdent::UND);
  assert!((uncut.weight() - ArmWeights::DEFAULT_ARM_WEIGHT).abs() < 1e-12);

  let unwidened = FanStream::unwidened(JA, 2.0, vec![Rooted::new(1_u32, 1, 0_u8)]);
  assert_eq!(unwidened.arm(), 0);
  assert!((unwidened.weight() - 2.0).abs() < 1e-12);
}

/// **THE ARM WEIGHT READS THE ORIGIN AND NOTHING ELSE.**
#[test]
fn an_arms_weight_is_read_off_its_origin() {
  let shipped = ArmWeights::new();
  assert!((shipped.weight(&ExpandOrigin::Original) - ArmWeights::ORIGINAL).abs() < 1e-12);
  assert!(
    (shipped.weight(&ExpandOrigin::expander("synonyms")) - ArmWeights::DEFAULT_ARM_WEIGHT).abs()
      < 1e-12
  );

  let named = ArmWeights::new().with_paraphrase(0.9);
  assert_eq!(named.paraphrase(), Some(0.9));
  assert!((named.weight(&ExpandOrigin::expander("translate")) - 0.9).abs() < 1e-12);
  // The original is not a knob, so naming the paraphrase leaves it exactly where it was.
  assert!((named.weight(&ExpandOrigin::Original) - ArmWeights::ORIGINAL).abs() < 1e-12);

  // And a call that names nothing is the shipped pair.
  let mut narrowed = named;
  narrowed.set_paraphrase(None);
  assert_eq!(narrowed, ArmWeights::DEFAULT);
}

/// **(F) TWO ARMS THAT FOUND ONE `(R, V)` COUNT ONCE**, and the better rank is the one that stands.
#[test]
fn one_familys_two_arms_are_one_witness() {
  // Root 1 found by BOTH arms of the `en` lane with the SAME evidence — one witness — and root 2
  // found only by the paraphrase.
  let grid = vec![
    cell(EN, 0, ArmWeights::ORIGINAL, 1.0, &[(1, 3, 0)]),
    cell(EN, 1, ArmWeights::ORIGINAL, 1.0, &[(1, 1, 0), (2, 2, 0)]),
  ];

  let fused = fuse_fanned::<u32, u8, HashJoin<u32>>(grid, Fusion::rrf());
  let one = fused
    .iter()
    .find(|row| *row.root_ref() == 1)
    .expect("the deduplicated root is still answered");

  // ONE sighting, and it is the better-ranked arm's: `1 / (60 + 1)`, not `1/(60+1) + 1/(60+3)`.
  assert_eq!(one.evidence().len(), 1);
  assert_eq!(one.evidence()[0].ordinal(), 1);
  assert!((one.score().get() - 1.0 / 61.0).abs() < 1e-12);
}

/// **THE SAME ROOT WITH DIFFERENT EVIDENCE IS TWO FINDINGS**, which is the layering theorem.
#[test]
fn one_root_under_two_evidences_survives_twice() {
  let grid = vec![
    cell(EN, 0, ArmWeights::ORIGINAL, 1.0, &[(1, 1, 7)]),
    cell(EN, 1, ArmWeights::ORIGINAL, 1.0, &[(1, 1, 9)]),
  ];

  let fused = fuse_fanned::<u32, u8, HashJoin<u32>>(grid, Fusion::rrf());
  let one = fused
    .iter()
    .find(|row| *row.root_ref() == 1)
    .expect("the root is answered");

  assert_eq!(one.evidence().len(), 2);
  assert!((one.score().get() - 2.0 / 61.0).abs() < 1e-12);
}

/// **CROSS-LANE AGREEMENT IS UNTOUCHED** — two lanes are two readers, and RRF exists to reward that.
#[test]
fn two_lanes_that_found_one_pair_are_two_witnesses() {
  let grid = vec![
    cell(EN, 0, ArmWeights::ORIGINAL, 1.0, &[(1, 1, 0)]),
    cell(JA, 0, ArmWeights::ORIGINAL, 1.0, &[(1, 1, 0)]),
  ];

  let fused = fuse_fanned::<u32, u8, HashJoin<u32>>(grid, Fusion::rrf());
  assert_eq!(fused[0].evidence().len(), 2);
  assert!((fused[0].score().get() - 2.0 / 61.0).abs() < 1e-12);
}

/// **ONE ARM ASKED TWICE IS TWO DISPATCHES**, which the mechanism allows and the dedup leaves alone.
#[test]
fn one_arms_own_repeats_are_not_the_familys_business() {
  let grid = vec![
    cell(EN, 0, ArmWeights::ORIGINAL, 1.0, &[(1, 1, 0)]),
    cell(EN, 0, ArmWeights::ORIGINAL, 1.0, &[(1, 4, 0)]),
  ];

  let fused = fuse_fanned::<u32, u8, HashJoin<u32>>(grid, Fusion::rrf());
  assert_eq!(fused[0].evidence().len(), 2);
  assert!((fused[0].score().get() - (1.0 / 61.0 + 1.0 / 64.0)).abs() < 1e-12);
}

/// **AN EMPTY GRID IS AN EMPTY ANSWER**, and a grid of empty cells is too.
#[test]
fn nothing_found_is_nothing_answered() {
  assert!(roots(Vec::new()).is_empty());
  assert!(roots(vec![cell(EN, 0, 1.0, 1.0, &[])]).is_empty());
}

/// **THE SHIPPED TAIL WEARS THE STREAM SEAM**, and the conversion is identity.
#[test]
fn a_vec_of_rooted_hits_is_a_ranked_stream() {
  let stream: Vec<Rooted<u32, u8>> = vec![Rooted::new(1, 1, 0), Rooted::new(2, 2, 0)];
  let ranked = RankedStream::into_ranked(stream.clone());
  assert_eq!(ranked, stream);
}