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 set road's own arithmetic: what the fold does with `m` lists, what the collapse beneath it
//! does with one element stream, and the refusal that keeps the empty query set out of both.

use std::sync::Arc;

use super::{Deferred, FoldedQuery, owner_best, set_scored};
use crate::{Embedding, FoldSemantics, Folded, HashBests, HashSeen, Max, Ranked, Scored, Sum};

const DIM: usize = 4;

fn embedding(coordinates: [f32; DIM]) -> Embedding<f32, DIM> {
  Embedding::new(Arc::from(coordinates.to_vec())).expect("the fixture declares DIM")
}

/// One ENGINE hit, as a stream hands it over — no rank yet, the walk being what mints one.
fn hit(key: &str, score: f32) -> Scored<&str, f32> {
  Scored::new(key, score)
}

/// One entity's best for one query vector, as the collapse hands it to the fold — with the ordinal
/// that query's own stream gave it.
fn best(key: &str, score: f32, rank: u64) -> Ranked<&str, f32> {
  Ranked::new(score, rank, key)
}

fn scored(page: Vec<Folded<&str, f32>>) -> Vec<(&str, f32)> {
  page
    .into_iter()
    .map(|folded| {
      let (score, _streams, node) = folded.into_components();
      (node, score)
    })
    .collect()
}

/// One answer's per-stream ORDINALS, holes and all — the half of a slot an attribution claim is
/// about, read off the slot rather than off a second list.
fn ordinals(folded: &Folded<&str, f32>) -> Vec<Option<u64>> {
  folded
    .streams()
    .iter()
    .map(|slot| slot.map(|best| best.ordinal()))
    .collect()
}

fn collapsed(page: Vec<Ranked<&str, f32>>) -> Vec<(&str, f32, u64)> {
  page
    .into_iter()
    .map(|ranked| {
      let (score, rank, node) = ranked.into_components();
      (node, score, rank)
    })
    .collect()
}

/// **The empty query set is not a value of this type** — the ruled refusal, at the constructor that
/// is the only way in.
#[test]
fn an_empty_query_set_is_not_a_set_query() {
  assert!(FoldedQuery::<f32, f32, DIM>::new(Vec::new(), 0.0).is_none());
}

/// And a non-empty one is, with `m` readable off it — which is what makes the `m ≥ 1` a fold is
/// promised a fact of the type rather than a comment on it.
#[test]
fn a_set_query_reports_how_many_vectors_were_asked() {
  let query = FoldedQuery::new(
    vec![
      embedding([1.0, 0.0, 0.0, 0.0]),
      embedding([0.0, 1.0, 0.0, 0.0]),
    ],
    0.25_f32,
  )
  .expect("two embeddings are a set query");

  assert_eq!(query.asked().get(), 2);
  assert_eq!(query.inputs().len(), 2);
  assert!((*query.floor() - 0.25).abs() < f32::EPSILON);
}

/// The DEGENERATE form cannot fail, which is what lets an `ask` chain's single answer reach this
/// road without unwrapping an [`Option`] it could prove was `Some`.
#[test]
fn the_single_form_is_a_set_query_of_one() {
  let query = FoldedQuery::single(embedding([1.0, 0.0, 0.0, 0.0]), 0.0);

  assert_eq!(query.asked().get(), 1);
}

/// **The collapse is the dedup stage one grain up**: an element stream naming one owner twice
/// collapses to that owner's BEST, and the floor terminates the walk rather than filtering it.
///
/// The RANK comes through it — 1-based over the engine's raw stream, holes where the collapse
/// dropped a repeat sighting — because the set answer attributes each number to the stream that
/// produced it.
#[test]
fn owner_best_keeps_the_best_sighting_per_owner_and_its_ordinal() {
  let stream = vec![
    hit("m1", 0.95),
    hit("m2", 0.90),
    hit("m1", 0.80),
    hit("m3", 0.10),
    hit("m2", 0.05),
  ];

  let bests = owner_best::<_, _, HashSeen<_>>(stream, &0.5);

  assert_eq!(collapsed(bests), vec![("m1", 0.95, 1), ("m2", 0.90, 2)]);
}

/// **`Sum` is late interaction**: an entity answering two query vectors decently outranks one
/// answering a single vector perfectly.
#[test]
fn sum_prefers_the_entity_that_answered_more_of_the_question() {
  let page = set_scored::<_, _, HashBests<_, _>, _>(
    [
      vec![best("broad", 0.6, 2), best("narrow", 0.99, 1)],
      vec![best("broad", 0.6, 1)],
    ],
    &Sum::new(),
    10,
  );

  assert_eq!(scored(page), vec![("broad", 1.2), ("narrow", 0.99)]);
}

/// **`Max` is the best single pair**, which reverses that same stream: one perfect match wins.
#[test]
fn max_prefers_the_single_best_pair() {
  let page = set_scored::<_, _, HashBests<_, _>, _>(
    [
      vec![best("broad", 0.6, 2), best("narrow", 0.99, 1)],
      vec![best("broad", 0.6, 1)],
    ],
    &Max::new(),
    10,
  );

  assert_eq!(scored(page), vec![("narrow", 0.99), ("broad", 0.6)]);
}

/// **THE ATTRIBUTION PIN.** Each ordinal is the RAW position of the stream that produced it, sitting
/// in that stream's own slot beside the score that stream measured — never renumbered, and never
/// invented for a stream that did not answer.
#[test]
fn every_ordinal_is_its_own_streams_and_an_unanswered_stream_leaves_a_hole() {
  let page = set_scored::<_, _, HashBests<_, _>, _>(
    [
      vec![best("clip", 0.5, 1)],
      vec![best("other", 0.9, 1)],
      vec![best("other", 0.8, 1), best("clip", 0.4, 7)],
    ],
    &Sum::new(),
    10,
  );

  let clip = page
    .iter()
    .find(|folded| folded.node() == "clip")
    .expect("the entity two of the three vectors matched");

  assert_eq!(ordinals(clip), vec![Some(1), None, Some(7)]);
  assert_eq!(
    clip.streams().len(),
    3,
    "one slot per query vector asked, answered or not"
  );
  // **THE SCORES ARRIVE WITH THEIR ORDINALS**, which is what makes the folded number explicable from
  // the answer alone: an assertion about the ordinals by themselves would pass for a walk that read
  // every score and then dropped it.
  assert_eq!(
    clip
      .streams()
      .iter()
      .flatten()
      .map(|best| best.score())
      .collect::<Vec<_>>(),
    vec![0.5, 0.4],
  );
  assert!((clip.score() - 0.9).abs() < f32::EPSILON, "0.5 + 0.4");
}

/// **THE SLOT CORRESPONDENCE.** `streams[j].is_some()` is `bests[j].is_some()`, for every `j` — the
/// two are filled from one sighting, so a fold that reads its `None`s is reading the same absence
/// the answer reports.
#[test]
fn the_slots_a_fold_sees_correspond_to_the_sightings_the_answer_carries() {
  /// A fold that RECORDS the shape of what it was handed, so the invariant can be compared against
  /// the answer rather than assumed of it.
  struct Witness(std::sync::Mutex<Vec<Vec<bool>>>);

  impl FoldSemantics<f32> for Witness {
    fn score(&self, bests: &[Option<f32>]) -> f32 {
      self
        .0
        .lock()
        .expect("the fixture holds the lock alone")
        .push(bests.iter().map(Option::is_some).collect());
      bests.iter().flatten().copied().fold(0.0, f32::max)
    }

    fn name(&self) -> &str {
      "witness"
    }
  }

  let witness = Witness(std::sync::Mutex::new(Vec::new()));
  let page = set_scored::<_, _, HashBests<_, _>, _>(
    [
      vec![best("clip", 0.5, 1)],
      vec![],
      vec![best("clip", 0.4, 3)],
    ],
    &witness,
    10,
  );

  let seen = witness.0.into_inner().expect("the fixture is done with it");
  assert_eq!(seen, vec![vec![true, false, true]]);
  assert_eq!(
    page[0]
      .streams()
      .iter()
      .map(Option::is_some)
      .collect::<Vec<_>>(),
    seen[0]
  );
}

/// **A USER-AUTHORED MEAN.** The withdrawn word's dignified home: a fold that sees its `None`s owns
/// the division, and the two readings that split `Mean` in half are both one impl away.
#[test]
fn a_custom_fold_divides_by_whichever_count_its_author_means() {
  /// `Σ bⱼ / m` — over every vector ASKED, which is the reading the withdrawn word had.
  struct OverAsked;
  /// `Σ bⱼ / |answered|` — over the ones this entity answered, which is the reading it did not.
  struct OverAnswered;

  impl FoldSemantics<f32> for OverAsked {
    fn score(&self, bests: &[Option<f32>]) -> f32 {
      bests.iter().flatten().sum::<f32>() / bests.len() as f32
    }

    fn name(&self) -> &str {
      "over-asked"
    }
  }

  impl FoldSemantics<f32> for OverAnswered {
    fn score(&self, bests: &[Option<f32>]) -> f32 {
      let answered = bests.iter().flatten().count();
      bests.iter().flatten().sum::<f32>() / answered as f32
    }

    fn name(&self) -> &str {
      "over-answered"
    }
  }

  let lists = || {
    [
      vec![best("half", 0.8, 1), best("whole", 0.4, 2)],
      vec![best("whole", 0.4, 1)],
    ]
  };

  let asked = scored(set_scored::<_, _, HashBests<_, _>, _>(
    lists(),
    &OverAsked,
    10,
  ));
  let answered = scored(set_scored::<_, _, HashBests<_, _>, _>(
    lists(),
    &OverAnswered,
    10,
  ));

  // Over `m`, the two tie: answering half the question well is worth answering all of it adequately.
  assert!(
    asked
      .iter()
      .all(|(_, score)| (score - 0.4).abs() < f32::EPSILON),
    "{asked:?}"
  );
  // Over its own hits, the one-of-two match wins outright — which is exactly the semantics no
  // framework word should have picked on an author's behalf.
  assert_eq!(answered, vec![("half", 0.8), ("whole", 0.4)]);
}

/// **The `m = 1` coincidence**: with one query vector every fold agrees, which is what makes the
/// everyday single-vector search knob-free — and what makes naming a non-default fold there legal
/// rather than refused.
#[test]
fn one_query_vector_makes_every_fold_agree() {
  let one = || vec![vec![best("a", 0.75, 1), best("b", 0.5, 2)]];

  let sum = scored(set_scored::<_, _, HashBests<_, _>, _>(
    one(),
    &Sum::new(),
    10,
  ));
  let max = scored(set_scored::<_, _, HashBests<_, _>, _>(
    one(),
    &Max::new(),
    10,
  ));

  assert_eq!(sum, vec![("a", 0.75), ("b", 0.5)]);
  assert_eq!(sum, max);
}

/// **`limit` counts ENTITIES and is spent LAST** — after the fold, so an entity that places poorly
/// for every single query vector and well across all of them is still in the page.
#[test]
fn the_limit_counts_entities_and_is_spent_after_the_fold() {
  let page = set_scored::<_, _, HashBests<_, _>, _>(
    [
      vec![best("spike", 0.9, 1), best("steady", 0.5, 2)],
      vec![best("steady", 0.5, 1)],
      vec![best("steady", 0.5, 1)],
    ],
    &Sum::new(),
    1,
  );

  assert_eq!(scored(page), vec![("steady", 1.5)]);
}

/// A budget of zero answers nothing, which is the same reading the single-vector walk takes.
#[test]
fn a_zero_budget_answers_nothing() {
  let page = set_scored::<_, _, HashBests<_, _>, _>([vec![best("a", 0.75, 1)]], &Sum::new(), 0);

  assert!(page.is_empty());
}

/// Zero LISTS is not reachable through [`FoldedQuery`], and a direct caller of the fold gets the honest
/// shape rather than a fold over nothing: nothing was asked, so nothing scored.
#[test]
fn a_fold_over_no_query_vectors_answers_nothing() {
  let page = set_scored::<&str, f32, HashBests<_, _>, _>(
    Vec::<Vec<Ranked<&str, f32>>>::new(),
    &Sum::new(),
    10,
  );

  assert!(page.is_empty());
}

/// A query vector that matched NOTHING still holds its slot — an empty list is a question that was
/// asked and went unanswered, not a question that was not asked.
#[test]
fn an_unanswered_query_vector_still_holds_its_slot() {
  let page =
    set_scored::<_, _, HashBests<_, _>, _>([vec![best("a", 0.9, 1)], Vec::new()], &Sum::new(), 10);

  assert_eq!(scored(page.clone()), vec![("a", 0.9)]);
  assert_eq!(ordinals(&page[0]), vec![Some(1), None]);
}

/// **THE FLOORLESS SET FORM**, and the refusal it does NOT lose: the empty set is a fact about the
/// question, so deferring the floor changes nothing about it.
#[test]
fn a_floorless_set_query_defers_the_number_and_keeps_the_empty_refusal() {
  let deferred: FoldedQuery<f32, Deferred, DIM> =
    FoldedQuery::of(vec![embedding([1.0, 0.0, 0.0, 0.0])]).expect("one vector is not none");

  assert_eq!(deferred.asked().get(), 1);
  assert_eq!(deferred.floor(), &Deferred::new());
  assert!(FoldedQuery::<f32, Deferred, DIM>::of(Vec::new()).is_none());
}

/// Resolving is the chain's second step and answers the query the explicit form builds — which is
/// what makes *查询层传入 > attr 默认* one road rather than two.
#[test]
fn a_resolved_set_query_is_the_explicit_one() {
  let vectors = vec![
    embedding([1.0, 0.0, 0.0, 0.0]),
    embedding([0.0, 1.0, 0.0, 0.0]),
  ];

  let resolved = FoldedQuery::of(vectors.clone())
    .expect("two vectors are not none")
    .floored(0.3_f32);

  assert_eq!(
    resolved,
    FoldedQuery::new(vectors, 0.3).expect("two vectors are not none")
  );
}