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 EXCLUSION, at the grain the emitted door cannot show — and the own-read vocabulary beside it.
//!
//! What lives here is the mechanism `retrieve_similar_by_<field>` is built out of, asserted where a
//! mutation to it is visible: [`ranked_keys_excluding`] against the plain walk, over the SAME hit
//! stream, so every difference between the two answers is the exclusion's doing and nothing else's.
//!
//! [`OwnReadError`] is beside it rather than in a file of its own for the same reason the type kept
//! this module: the exclusion is the similar door's and the vocabulary is both doors', and one small
//! file holding both is closer to how they are read than two files apiece would be.
//!
//! # Why the pair matters more than either half
//!
//! *The example is missing from the page* is the easy half and it is not the claim. The claim is
//! that the example is missing AND its raw-stream ordinal is still spent — a `retain` before the
//! walk passes the first and fails the second, silently, by renumbering everything behind it. Every
//! assertion below is therefore written against [`ranked_keys`] over the identical input, so the
//! wrong implementation is the one whose two answers agree about the ranks.

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

/// A key with a lineage step beside its id, as every emitted key has — so *the example* is one
/// address rather than one id that another lineage could collide with.
#[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 STREAM a similar-by-example query actually gets: the example FIRST, at the top score, because
/// an entity is its own nearest neighbour under every metric an engine reports.
fn stream() -> Vec<Scored<SegmentKey, f32>> {
  vec![
    hit("m1", 1, 1.00),
    hit("m1", 2, 0.90),
    hit("m2", 3, 0.80),
    hit("m2", 4, 0.70),
  ]
}

/// Each survivor's `(segment, rank)` — the pair every assertion here is really about.
fn placed(ranked: &[Ranked<SegmentKey, f32>]) -> Vec<(i64, u64)> {
  ranked
    .iter()
    .map(|item| (item.node_ref().segment, item.rank()))
    .collect()
}

/// The whole claim in one assertion: the example is gone, everything behind it keeps the ordinal the
/// ENGINE gave it, and the plain walk over the same stream is what says those ordinals were 1..4.
///
/// MUTATION-CHECKED. Filtering the example out of the stream BEFORE the walk answers
/// `[(2, 1), (3, 2), (4, 3)]` here — the same three entities, every rank one too low — and this
/// assertion is the only thing in the crate that separates the two implementations.
#[test]
fn the_example_leaves_its_ordinal_behind() {
  let plain = ranked_keys::<_, _, HashSeen<SegmentKey>>(stream(), &0.0, 10);
  assert_eq!(placed(&plain), vec![(1, 1), (2, 2), (3, 3), (4, 4)]);

  let without =
    ranked_keys_excluding::<_, _, HashSeen<SegmentKey>>(stream(), &0.0, 10, &key("m1", 1));
  assert_eq!(placed(&without), vec![(2, 2), (3, 3), (4, 4)]);
}

/// `limit` counts NEIGHBOURS: a budget of two fills with two other entities, where a filter applied
/// after the walk would have handed back one.
///
/// The plain walk beside it is what makes the number readable — the same budget over the same stream
/// returns the example and one neighbour.
#[test]
fn the_budget_counts_neighbours_rather_than_counting_the_example() {
  let plain = ranked_keys::<_, _, HashSeen<SegmentKey>>(stream(), &0.0, 2);
  assert_eq!(placed(&plain), vec![(1, 1), (2, 2)]);

  let without =
    ranked_keys_excluding::<_, _, HashSeen<SegmentKey>>(stream(), &0.0, 2, &key("m1", 1));
  assert_eq!(placed(&without), vec![(2, 2), (3, 3)]);
}

/// The exclusion is the DEDUP MECHANISM, so the declaration's own `dedup` word carries it — and the
/// `eq` membership, which asks only [`PartialEq`] of the key, excludes exactly what the `hash` one
/// does.
///
/// It matters because the two are different data structures: `eq` walks a list and `hash` probes a
/// table, and a seed that reached only one of them would be a word-dependent door.
#[test]
fn either_dedup_word_carries_the_exclusion() {
  let hashed =
    ranked_keys_excluding::<_, _, HashSeen<SegmentKey>>(stream(), &0.0, 10, &key("m2", 3));
  let compared =
    ranked_keys_excluding::<_, _, EqSeen<SegmentKey>>(stream(), &0.0, 10, &key("m2", 3));
  assert_eq!(placed(&hashed), vec![(1, 1), (2, 2), (4, 4)]);
  assert_eq!(placed(&hashed), placed(&compared));
}

/// An example the stream never yields changes NOTHING — the seed is a membership entry, not a
/// promise that something will be dropped.
///
/// This is the *key from another lineage* case, and it is also what says the exclusion is keyed on
/// the whole key rather than on the id: `("m2", 1)` shares an id with the first hit and is not it.
#[test]
fn an_example_outside_the_stream_drops_nothing() {
  let without =
    ranked_keys_excluding::<_, _, HashSeen<SegmentKey>>(stream(), &0.0, 10, &key("m2", 1));
  assert_eq!(placed(&without), vec![(1, 1), (2, 2), (3, 3), (4, 4)]);
}

/// The floor still TERMINATES under an exclusion, and the example's ordinal is spent before the cut
/// rather than instead of it — the stages compose in the ruled order, exclusion being one of them.
#[test]
fn the_floor_still_terminates_and_the_hole_survives_it() {
  let without =
    ranked_keys_excluding::<_, _, HashSeen<SegmentKey>>(stream(), &0.75, 10, &key("m1", 1));
  assert_eq!(placed(&without), vec![(2, 2), (3, 3)]);
}

/// A zero budget answers nothing, exclusion or no exclusion — the seed is spent before the walk and
/// the walk's own early return is unmoved by it.
#[test]
fn a_zero_budget_answers_nothing() {
  let without =
    ranked_keys_excluding::<_, _, HashSeen<SegmentKey>>(stream(), &0.0, 0, &key("m1", 1));
  assert!(without.is_empty());
}

/// The three non-engine arms each say a DIFFERENT thing, and none of them says *nothing was near
/// enough* — which is the whole reason they are refusals rather than an empty page.
///
/// Each sentence names what the READ FOUND and not what the caller wanted it for, which is what
/// lets one vocabulary serve a search and a plain get: `get_<field>` refusing with *no vector in
/// this column to be similar to* would be telling its caller about a search nobody ran.
#[test]
fn every_refusal_names_what_the_read_found() {
  let unindexed = OwnReadError::<core::convert::Infallible>::Unindexed.to_string();
  let several = OwnReadError::<core::convert::Infallible>::Several { held: 3 }.to_string();
  let width = OwnReadError::<core::convert::Infallible>::Width {
    declared: 768,
    stored: 384,
  }
  .to_string();

  assert_eq!(unindexed, "the key holds no vector in this column");
  assert_eq!(
    several,
    "the key holds 3 vectors in this column where the election declared one"
  );
  assert_eq!(
    width,
    "the stored vector has 384 coordinates where the election declared 768"
  );

  // THREE SENTENCES, THREE MEANINGS — deduped rather than counted, so an edit that made two arms
  // read alike fails here instead of passing a suite that only checked each one against itself.
  let mut distinct = vec![unindexed, several, width];
  distinct.sort();
  distinct.dedup();
  assert_eq!(
    distinct.len(),
    3,
    "two arms say the same thing: {distinct:?}"
  );
}

/// The ENGINE arm carries the backend's own error whole, and it is the ONLY arm with a `source`.
///
/// The others are the framework's own findings about the example, so a caller walking the chain
/// reaches a backend error exactly when there was one.
#[test]
fn only_the_engine_arm_has_a_source() {
  #[derive(Debug)]
  struct Refusal;

  impl core::fmt::Display for Refusal {
    fn fmt(&self, f: &mut core::fmt::Formatter<'_>) -> core::fmt::Result {
      f.write_str("the toy engine refused")
    }
  }

  impl core::error::Error for Refusal {}

  let engine = OwnReadError::Engine(Refusal);
  assert_eq!(engine.to_string(), "the toy engine refused");
  assert!(core::error::Error::source(&engine).is_some());

  let unindexed = OwnReadError::<Refusal>::Unindexed;
  assert!(core::error::Error::source(&unindexed).is_none());
  assert!(core::error::Error::source(&OwnReadError::<Refusal>::Several { held: 2 }).is_none());
  assert!(
    core::error::Error::source(&OwnReadError::<Refusal>::Width {
      declared: 4,
      stored: 5
    })
    .is_none()
  );
}