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 core::{
  pin::pin,
  task::{Context, Poll, Waker},
};

use super::{AsyncGather, RetrieveError, filled};
use crate::retrieve::Ranked;

/// Drive a future to its value without a runtime — every future in this module is already-ready,
/// for `store::vector`'s reason one layer over.
fn block_on<F: Future>(future: F) -> F::Output {
  let mut future = pin!(future);
  let mut cx = Context::from_waker(Waker::noop());
  loop {
    if let Poll::Ready(value) = future.as_mut().poll(&mut cx) {
      return value;
    }
  }
}

/// The whole domain entity a tier-B retrieve answers with — not a key, not a row.
#[derive(Debug, Clone, PartialEq)]
struct Segment {
  key: i64,
  title: String,
}

/// A store standing in for the system of record: it holds entities by key, refuses the ones a
/// filter names, and RECORDS every batch it was asked for — which is what the fill loop's own
/// assertions read.
struct Corpus {
  held: Vec<Segment>,
  batches: Vec<Vec<i64>>,
}

impl Corpus {
  fn new(held: impl IntoIterator<Item = (i64, &'static str)>) -> Self {
    Self {
      held: held
        .into_iter()
        .map(|(key, title)| Segment {
          key,
          title: title.to_owned(),
        })
        .collect(),
      batches: Vec::new(),
    }
  }
}

impl AsyncGather<i64, Segment> for Corpus {
  /// The pruned keys, which stands in for a lowered comparison: what the seam cares about is that
  /// ONE call carries both the keys and the predicate.
  type Filter = [i64];
  type Error = &'static str;

  fn gather(
    &mut self,
    keys: &[i64],
    filter: Option<&[i64]>,
  ) -> impl Future<Output = Result<Vec<Option<Segment>>, &'static str>> {
    self.batches.push(keys.to_vec());
    let found = keys
      .iter()
      .map(|key| {
        if filter.is_some_and(|pruned| pruned.contains(key)) {
          return None;
        }
        self.held.iter().find(|held| held.key == *key).cloned()
      })
      .collect();
    core::future::ready(Ok(found))
  }
}

/// A store that refuses, for the error half.
struct Refusing;

impl AsyncGather<i64, Segment> for Refusing {
  type Filter = ();
  type Error = &'static str;

  fn gather(
    &mut self,
    _keys: &[i64],
    _filter: Option<&()>,
  ) -> impl Future<Output = Result<Vec<Option<Segment>>, &'static str>> {
    core::future::ready(Err("the store refused"))
  }
}

/// Ranked keys as tier A hands them over: the ranks are the RAW stream's, holes included, because
/// tier B's job is to carry them through untouched.
fn ranked(hits: impl IntoIterator<Item = (i64, f32, u64)>) -> Vec<Ranked<i64, f32>> {
  hits
    .into_iter()
    .map(|(key, score, rank)| Ranked::new(score, rank, key))
    .collect()
}

fn shape(filled: &[Ranked<Segment, f32>]) -> Vec<(&str, f32, u64)> {
  filled
    .iter()
    .map(|hit| (hit.node_ref().title.as_str(), hit.score(), hit.rank()))
    .collect()
}

/// The unfiltered case: ONE batch, ONE call, the page full, and every entity wearing the score and
/// rank its key carried.
#[test]
fn a_full_page_costs_one_composed_query() {
  let mut store = Corpus::new([(1, "alpha"), (2, "beta"), (3, "gamma")]);

  let page = block_on(filled(
    ranked([(1, 0.9, 1), (2, 0.8, 4), (3, 0.7, 9)]),
    &mut store,
    None,
    3,
  ))
  .expect("the corpus answers");

  assert_eq!(
    shape(&page),
    vec![("alpha", 0.9, 1), ("beta", 0.8, 4), ("gamma", 0.7, 9)]
  );
  assert_eq!(store.batches, vec![vec![1, 2, 3]]);
}

/// The order is the ENGINE's — the key list's own — and never the store's. The corpus is seeded in
/// the reverse of the ranking, so a page that came back in storage order would be visible here.
#[test]
fn the_page_is_in_engine_order_and_not_the_stores() {
  let mut store = Corpus::new([(3, "gamma"), (2, "beta"), (1, "alpha")]);

  let page = block_on(filled(
    ranked([(2, 0.9, 1), (1, 0.8, 2), (3, 0.7, 3)]),
    &mut store,
    None,
    3,
  ))
  .expect("the corpus answers");

  assert_eq!(
    page
      .iter()
      .map(|hit| hit.node_ref().key)
      .collect::<Vec<_>>(),
    vec![2, 1, 3]
  );
}

/// **The under-filled page pulls the next key batch.** The filter prunes two of the first three, so
/// the loop asks again — for exactly the shortfall — and keeps asking until the page is full.
#[test]
fn a_filter_that_prunes_mid_page_pulls_another_batch() {
  let mut store = Corpus::new((1..=9).map(|key| (key, "held")));
  let pruned = [2_i64, 3, 5, 6, 8];

  let page = block_on(filled(
    ranked((1..=9).map(|key| (key, 1.0, key as u64))),
    &mut store,
    Some(&pruned[..]),
    3,
  ))
  .expect("the corpus answers");

  assert_eq!(
    page
      .iter()
      .map(|hit| (hit.node_ref().key, hit.rank()))
      .collect::<Vec<_>>(),
    vec![(1, 1), (4, 4), (7, 7)]
  );
  // Each round asks for exactly the shortfall: three, one survived; two, one survived; one, pruned;
  // one, survived. Four round trips for a page of three, which is what a filter this aggressive
  // costs and what a fixed batch size would have guessed at.
  assert_eq!(
    store.batches,
    vec![vec![1, 2, 3], vec![4, 5], vec![6], vec![7]]
  );
}

/// A key the ENGINE knows and the STORE has lost is treated exactly as a filter prune: skipped, and
/// the page keeps filling. There is no error and no hole in the returned list.
#[test]
fn a_store_missing_row_is_skipped_like_a_prune() {
  let mut store = Corpus::new([(1, "alpha"), (3, "gamma")]);

  let page = block_on(filled(
    ranked([(1, 0.9, 1), (2, 0.8, 2), (3, 0.7, 3)]),
    &mut store,
    None,
    3,
  ))
  .expect("the corpus answers");

  assert_eq!(shape(&page), vec![("alpha", 0.9, 1), ("gamma", 0.7, 3)]);
}

/// The keys running out ends the loop with a SHORT page — the honest answer when the engine ran dry
/// or the floor cut its tail. 宁短不凑.
#[test]
fn the_page_comes_back_short_when_the_keys_run_out() {
  let mut store = Corpus::new([(1, "alpha"), (2, "beta")]);

  let page = block_on(filled(
    ranked([(1, 0.9, 1), (2, 0.8, 2)]),
    &mut store,
    None,
    10,
  ))
  .expect("the corpus answers");

  assert_eq!(page.len(), 2);
  assert_eq!(store.batches, vec![vec![1, 2]]);
}

/// The budget is a ceiling on RESULTS: a batch that over-delivers is cut at the limit, and the keys
/// past it are never asked for.
#[test]
fn the_budget_stops_the_loop_mid_batch() {
  let mut store = Corpus::new((1..=9).map(|key| (key, "held")));

  let page = block_on(filled(
    ranked((1..=9).map(|key| (key, 1.0, key as u64))),
    &mut store,
    None,
    2,
  ))
  .expect("the corpus answers");

  assert_eq!(page.len(), 2);
  assert_eq!(store.batches, vec![vec![1, 2]]);
}

/// No keys is no round trip at all — a retrieve whose engine matched nothing must not touch the
/// system of record.
#[test]
fn an_empty_key_list_asks_the_store_nothing() {
  let mut store = Corpus::new([(1, "alpha")]);

  let page = block_on(filled(Vec::<Ranked<i64, f32>>::new(), &mut store, None, 10))
    .expect("the corpus answers");

  assert!(page.is_empty());
  assert!(store.batches.is_empty());
}

/// The store's refusal is carried, and the retrieve error keeps the two backends apart: a caller
/// matching on this can tell a malformed query from a bind ceiling.
#[test]
fn the_stores_refusal_is_carried() {
  let mut store = Refusing;

  let refused = block_on(filled(ranked([(1, 0.9, 1)]), &mut store, None, 3));

  assert_eq!(refused, Err("the store refused"));
  let error: RetrieveError<&str, &str> = RetrieveError::Gather("the store refused");
  assert_eq!(
    error.to_string(),
    "the store refused the gather: the store refused"
  );
  assert_eq!(
    RetrieveError::<&str, &str>::Engine("bad syntax").to_string(),
    "the index refused the query: bad syntax"
  );
}