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
use std::{cell::Cell, rc::Rc};

use super::ranked_keys;
use crate::{
  Scored,
  retrieve::{EqSeen, HashSeen, Ranked},
};

/// A key with a lineage step beside its id, which is the shape every emitted key has — so a
/// duplicate here is two hits at ONE address rather than two ids that happen to collide.
#[derive(Debug, Clone, PartialEq, Eq, Hash)]
struct SegmentKey {
  media: &'static str,
  segment: i64,
}

const fn key(media: &'static str, segment: i64) -> SegmentKey {
  SegmentKey { media, segment }
}

/// One raw hit, spelled as the engine hands it over.
fn hit(media: &'static str, segment: i64, score: f32) -> Scored<SegmentKey, f32> {
  Scored::new(key(media, segment), score)
}

/// The engine's stream, WITH a counter on it — the instrument the early-termination pin reads.
///
/// It counts what the framework PULLED, which is the only observable that separates a floor applied
/// at the walk from a floor applied after it: the two agree about the result on a descending stream
/// and disagree about how much of the tail was touched.
struct Counted<I> {
  inner: I,
  pulled: Rc<Cell<usize>>,
}

impl<I: Iterator> Iterator for Counted<I> {
  type Item = I::Item;

  fn next(&mut self) -> Option<I::Item> {
    let next = self.inner.next();
    if next.is_some() {
      self.pulled.set(self.pulled.get() + 1);
    }
    next
  }
}

fn counted<I: IntoIterator>(hits: I) -> (Counted<I::IntoIter>, Rc<Cell<usize>>) {
  let pulled = Rc::new(Cell::new(0));
  (
    Counted {
      inner: hits.into_iter(),
      pulled: Rc::clone(&pulled),
    },
    pulled,
  )
}

/// What each survivor came back as: `(media, segment, score, rank)`, which is the whole of what an
/// assertion about this stage has to say.
fn shape(ranked: &[Ranked<SegmentKey, f32>]) -> Vec<(&'static str, i64, f32, u64)> {
  ranked
    .iter()
    .map(|hit| {
      (
        hit.node_ref().media,
        hit.node_ref().segment,
        hit.score(),
        hit.rank(),
      )
    })
    .collect()
}

/// The whole pipeline in one walk: the floor cuts the tail, the duplicate is dropped, and the ranks
/// that survive are the RAW stream's own — with a hole where the duplicate stood.
#[test]
fn the_pipeline_runs_floor_then_dedup_then_rank() {
  let hits = vec![
    hit("m1", 1, 0.90),
    hit("m2", 7, 0.80),
    hit("m1", 1, 0.70), // the duplicate — rank 3 is consumed and no survivor wears it
    hit("m3", 2, 0.60),
    hit("m4", 9, 0.20), // below the floor — the walk ends here
    hit("m5", 4, 0.10),
  ];

  let ranked = ranked_keys::<_, _, HashSeen<_>>(hits, &0.5, usize::MAX);

  assert_eq!(
    shape(&ranked),
    vec![("m1", 1, 0.90, 1), ("m2", 7, 0.80, 2), ("m3", 2, 0.60, 4)]
  );
}

/// **MUTATION PIN — dedup must keep the FIRST sighting, which on a descending stream is the BEST
/// score.**
///
/// Keeping the later one instead (a `HashMap` insert that overwrites, a `retain` that walks from
/// the end) still returns one entry per key and still returns the right COUNT, so nothing about the
/// shape of the answer says it happened. What changes is the score and the rank on the survivor,
/// which is exactly what this asserts: `0.90` at rank 1, never `0.30` at rank 4.
#[test]
fn dedup_keeps_the_first_sighting_and_therefore_the_best_score() {
  let hits = vec![
    hit("m1", 1, 0.90),
    hit("m2", 7, 0.80),
    hit("m1", 1, 0.50),
    hit("m1", 1, 0.30),
  ];

  let ranked = ranked_keys::<_, _, HashSeen<_>>(hits, &0.1, usize::MAX);

  assert_eq!(shape(&ranked), vec![("m1", 1, 0.90, 1), ("m2", 7, 0.80, 2)]);
}

/// **MUTATION PIN — rank is the RAW stream's ordinal and is never re-densified.**
///
/// Minting rank as *the count of emitted results + 1* — the dense emission ordinal, which reads as
/// the tidier answer — returns the same keys with the same scores and renumbers them `1, 2, 3`. The
/// holes are the deliverable: they are what lets a caller re-ask with a wider budget and drop
/// everything at or below the last rank seen, which is v1's whole substitute for a cursor.
#[test]
fn rank_is_the_raw_ordinal_with_the_holes_left_in() {
  let hits = vec![
    hit("m1", 1, 0.90),
    hit("m1", 1, 0.85), // duplicate — consumes rank 2
    hit("m1", 1, 0.84), // duplicate — consumes rank 3
    hit("m2", 7, 0.80), // rank 4, NOT 2
    hit("m2", 7, 0.75), // duplicate — consumes rank 5
    hit("m3", 2, 0.60), // rank 6, NOT 3
  ];

  let ranked = ranked_keys::<_, _, HashSeen<_>>(hits, &0.1, usize::MAX);

  assert_eq!(
    ranked.iter().map(Ranked::rank).collect::<Vec<_>>(),
    vec![1, 4, 6]
  );
}

/// **MUTATION PIN — the floor terminates the WALK, it does not filter the stream.**
///
/// A floor applied after dedup — `ranked.retain(|hit| hit.score() >= floor)`, or a `filter` in the
/// loop instead of a `break` — produces the IDENTICAL list on a descending stream. Every
/// result-shaped assertion passes under the mutation. What does not pass is the count of hits the
/// framework pulled off the engine's stream: terminating reads four and stops, and filtering reads
/// all twelve.
#[test]
fn the_floor_ends_the_walk_rather_than_filtering_the_tail() {
  let mut hits = vec![
    hit("m1", 1, 0.90),
    hit("m2", 2, 0.80),
    hit("m3", 3, 0.70),
    hit("m4", 4, 0.20), // the first sub-floor hit
  ];
  // The unbounded tail an engine is free to hand over. Nothing here may be touched.
  hits.extend((5..13).map(|n| hit("tail", n, 0.19)));

  let (stream, pulled) = counted(hits);
  let ranked = ranked_keys::<_, _, HashSeen<_>>(stream, &0.5, usize::MAX);

  assert_eq!(ranked.len(), 3);
  assert_eq!(
    pulled.get(),
    4,
    "the walk must stop AT the first sub-floor hit, not filter past it"
  );
}

/// A hit exactly AT the floor is a hit: the test is `>=`, so the floor is the minimum score a
/// result may have rather than a score it must beat.
#[test]
fn the_floor_is_inclusive() {
  let hits = vec![hit("m1", 1, 0.5), hit("m2", 2, 0.5), hit("m3", 3, 0.4)];

  let ranked = ranked_keys::<_, _, HashSeen<_>>(hits, &0.5, usize::MAX);

  assert_eq!(ranked.len(), 2);
}

/// A score that cannot be placed against the floor ends the walk, because `NaN >= floor` is false
/// and the walk's test is that comparison and nothing else.
#[test]
fn an_incomparable_score_ends_the_walk() {
  let hits = vec![hit("m1", 1, 0.9), hit("m2", 2, f32::NAN), hit("m3", 3, 0.8)];

  let (stream, pulled) = counted(hits);
  let ranked = ranked_keys::<_, _, HashSeen<_>>(stream, &0.5, usize::MAX);

  assert_eq!(shape(&ranked), vec![("m1", 1, 0.9, 1)]);
  assert_eq!(pulled.get(), 2);
}

/// The budget stops the walk too, and the engine's tail past it is never pulled — a page's worth of
/// keys costs a page's worth of stream.
#[test]
fn the_budget_stops_the_walk_at_the_survivor_it_fills() {
  let hits: Vec<_> = (1..=20).map(|n| hit("m", n, 0.9)).collect();

  let (stream, pulled) = counted(hits);
  let ranked = ranked_keys::<_, _, HashSeen<_>>(stream, &0.5, 3);

  assert_eq!(ranked.len(), 3);
  assert_eq!(pulled.get(), 3);
}

/// A budget of zero asks for nothing and touches nothing — the degenerate case answered without a
/// branch anybody has to remember.
#[test]
fn a_budget_of_zero_pulls_nothing() {
  let hits: Vec<_> = (1..=5).map(|n| hit("m", n, 0.9)).collect();

  let (stream, pulled) = counted(hits);
  let ranked = ranked_keys::<_, _, HashSeen<_>>(stream, &0.5, 0);

  assert!(ranked.is_empty());
  assert_eq!(pulled.get(), 0);
}

/// The mechanism is a parameter and the pipeline is not: the equality membership walks the same
/// stream to the same answer, which is what makes `dedup(eq)` a bounds choice rather than a second
/// behaviour.
#[test]
fn the_equality_mechanism_walks_the_same_pipeline() {
  let hits = vec![
    hit("m1", 1, 0.90),
    hit("m2", 7, 0.80),
    hit("m1", 1, 0.70),
    hit("m3", 2, 0.60),
    hit("m4", 9, 0.20),
  ];

  let hashed = ranked_keys::<_, _, HashSeen<_>>(hits.clone(), &0.5, usize::MAX);
  let listed = ranked_keys::<_, _, EqSeen<_>>(hits, &0.5, usize::MAX);

  assert_eq!(shape(&hashed), shape(&listed));
}

/// An empty stream is an empty answer and not a refusal — the engine matching nothing is a legal
/// outcome, exactly as it is at the store seam.
#[test]
fn an_empty_stream_is_an_empty_answer() {
  let ranked = ranked_keys::<_, _, HashSeen<SegmentKey>>(Vec::new(), &0.5, usize::MAX);

  assert!(ranked.is_empty());
}