ingraph-codegen 0.1.0

The emission engine behind ingraph-derive: a plain declaration model in, the ingraph framework faces out.
Documentation
//! THE FANNED READ SEMANTICS — `rrf`, the presence rules it decides, and the selector seat that is
//! orthogonal to it.
//!
//! Beside [`doors`](super::doors) rather than inside it, on that file's own precedent: one file per
//! thing being proved. `doors` holds the law at the TIER's grain, where a route is a field; this
//! holds it at the SLOT's, where a route is a store.
//!
//! # Both words are read on both lists, every time
//!
//! `rrf` decides the leaderboard and `type =` decides addressability, and the orthogonality law says
//! all four combinations mean something. A test that read only one of the two lists would pass for
//! an emission that had collapsed them, so every accepting test below says what the ROUTE SEATS took
//! AND what the SELECTOR took.

use crate::{
  engine::{Engine, FieldEngines},
  index::{Dedup, Elected, ElectionLabel, IndexModel, Upstream},
  model::NodeKind,
  prefix::EmissionPrefix,
};

fn ident(name: &str) -> syn::Ident {
  syn::Ident::new(name, proc_macro2::Span::call_site())
}

/// One engine block, with `rrf` and `type =` written as the row under test says.
fn leg(word: &str, rrf: bool, typed: bool) -> Engine {
  Engine {
    rrf,
    resource: typed.then(|| syn::parse_quote!(crate::Store)),
    ..Engine::bare(ident(word))
  }
}

/// A vector declaration whose ONE election is FANNED across `legs`.
fn fanned(legs: Vec<Engine>) -> IndexModel {
  IndexModel {
    prefix: EmissionPrefix::default(),
    numbers: crate::index::Numbers::default(),
    field_numbers: Vec::new(),
    index: ident("Shots"),
    kind: NodeKind::Vector,
    vis: syn::parse_quote!(pub),
    krate: syn::parse_quote!(::ingraph),
    source: Upstream {
      node: syn::parse_quote!(Keyframe),
      projections: Vec::new(),
    },
    dedup: Dedup::Hash,
    embeddings: vec![Elected::new(
      ident("clip"),
      ElectionLabel::Embedding,
      syn::parse_quote!(::ingraph::Embedding<f32, 4, Clip>),
      None,
    )],
    labelled: Vec::new(),
    searchable: Vec::new(),
    engines: vec![FieldEngines {
      field: ident("clip"),
      engines: legs,
      fanout: true,
    }],
    stores: Vec::new(),
    data: false,
    keys: false,
    subscribe: false,
    extension: None,
    graphql: None,
    rename: None,
    slot: None,
    fields: Vec::new(),
  }
}

/// The whole expansion with the spaces taken out — what a claim about a type or a row is read off.
fn tight(model: &IndexModel) -> String {
  model.emit().to_string().split_whitespace().collect()
}

/// The tier's own packages, likewise.
fn packages(model: &IndexModel) -> String {
  model.tier().emit().to_string().split_whitespace().collect()
}

/// **THE PRESENCE MATRIX, OVER THE NUMBER OF PARTICIPANTS.** Read as a table because the rule is
/// small and total, and because the two degenerate cases are the ones a reader will come looking
/// for.
///
/// | participants | the slot's package | the mini door |
/// |---|---|---|
/// | 0 — every leg `rrf = false` | the FLAT leaf | absent |
/// | 1 | the FLAT leaf | absent |
/// | ≥ 2 | the mini TIER | present |
#[test]
fn the_fused_face_is_present_exactly_where_two_legs_participate() {
  for (participants, tiered) in [(0_usize, false), (1, false), (2, true), (3, true)] {
    let legs = (0..3)
      .map(|at| leg(["lance", "hnsw", "faiss"][at], at < participants, false))
      .collect();
    let model = fanned(legs);
    let emitted = tight(&model);
    assert_eq!(
      emitted.contains("structShotsClipFuseOptions"),
      tiered,
      "{participants} participants minted the wrong slot package: {emitted}",
    );
    assert_eq!(
      emitted.contains("structShotsClipVectorOptions"),
      !tiered,
      "{participants} participants minted the wrong slot package: {emitted}",
    );
    assert_eq!(
      emitted.contains("enumShotsClipFusedEvidence"),
      tiered,
      "{participants} participants minted the wrong evidence face: {emitted}",
    );
    assert_eq!(
      emitted.contains("fnvector_fuse_by_clip"),
      tiered,
      "{participants} participants minted the wrong door: {emitted}",
    );
  }
}

/// **ALL-FALSE IS A PURE MULTI-WRITE**, and the fused face is absent ENTIRELY — not an empty
/// package, not a door behind a bound nobody satisfies. A fan for REDUNDANCY is a legal declaration
/// and this is what it looks like.
///
/// The WRITE half is untouched, which is the other side of the claim: the slots are still two.
#[test]
fn a_fan_for_redundancy_keeps_its_slots_and_loses_its_leaderboard() {
  let model = fanned(vec![leg("lance", false, false), leg("hnsw", false, false)]);
  let emitted = tight(&model);
  for absent in [
    "ShotsClipFuseOptions",
    "ShotsClipFusedEvidence",
    "ShotsClipFusedError",
    "ShotsClipLanceLegOptions",
    "vector_fuse_by_clip",
  ] {
    assert!(
      !emitted.contains(absent),
      "a fan nobody put in the leaderboard minted `{absent}`: {emitted}",
    );
  }
  assert_eq!(
    model.engines[0].slots().len(),
    2,
    "the write fan lost a slot to a READ word",
  );
}

/// **THE ROUTE SEATS ARE THE PARTICIPANTS**, and a leg outside the leaderboard has neither a seat
/// nor a leg package — there is no edge for a parent to weight and no ceiling for a fold to narrow.
#[test]
fn a_leg_outside_the_leaderboard_has_no_route_seat() {
  let model = fanned(vec![
    leg("lance", true, false),
    leg("hnsw", true, false),
    leg("faiss", false, false),
  ]);
  let emitted = packages(&model);
  assert!(emitted.contains("ShotsClipLanceLegOptions"), "{emitted}");
  assert!(emitted.contains("ShotsClipHnswLegOptions"), "{emitted}");
  assert!(
    !emitted.contains("ShotsClipFaissLegOptions"),
    "a leg outside the leaderboard grew a route package: {emitted}",
  );
  assert!(
    emitted.contains("fnwith_lance") && emitted.contains("fnwith_hnsw"),
    "{emitted}",
  );
  assert!(
    !emitted.contains("fnwith_faiss"),
    "a leg outside the leaderboard grew a route seat: {emitted}",
  );
}

/// **THE SELECTOR IS THE TYPED LEGS, REGARDLESS OF `rrf`** — `type =` IS the author's
/// leg-addressability opt-in, and the two words are orthogonal.
///
/// The fixture is the third quadrant: a leg the declaration typed and took OUT of the leaderboard.
/// It has no route seat, it is not folded, and a request can still name it.
#[test]
fn the_selector_names_every_typed_leg_and_the_leaderboard_does_not() {
  let model = fanned(vec![
    leg("lance", true, true),
    leg("hnsw", true, false),
    leg("faiss", false, true),
  ]);
  let emitted = packages(&model);
  assert!(emitted.contains("enumShotsClipEngineInput"), "{emitted}");
  assert!(
    emitted.contains("Lance(ShotsClipLanceEngineInput)"),
    "{emitted}",
  );
  assert!(
    emitted.contains("Faiss(ShotsClipFaissEngineInput)"),
    "a typed leg outside the leaderboard is unnameable: {emitted}",
  );
  assert!(
    !emitted.contains("Hnsw(ShotsClipHnswEngineInput)"),
    "an untyped leg became addressable: {emitted}",
  );
  assert!(
    emitted.contains("fnwith_engine"),
    "the mini tier grew no selector seat: {emitted}",
  );
}

/// **THE EVIDENCE ENUM IS THE UNION**, and the third quadrant is why: a typed leg outside the
/// leaderboard is reachable by the selector, and a request that names it is answered in the SAME
/// shape — so the enum needs a variant for it or the direct read has nothing to report through.
#[test]
fn the_evidence_enum_holds_every_leg_an_answer_can_name() {
  let model = fanned(vec![
    leg("lance", true, true),
    leg("hnsw", true, false),
    leg("faiss", false, true),
    leg("scann", false, false),
  ]);
  let emitted = packages(&model);
  assert!(
    emitted.contains(
      "enumShotsClipFusedEvidence<__INGRAPH_SCORE_LANCE__,__INGRAPH_SCORE_HNSW__,\
       __INGRAPH_SCORE_FAISS__,>"
    ),
    "{emitted}",
  );
  assert!(
    emitted.contains(
      "enumShotsClipFusedError<__INGRAPH_ERROR_LANCE__,__INGRAPH_ERROR_HNSW__,\
       __INGRAPH_ERROR_FAISS__,>"
    ),
    "{emitted}",
  );
  assert!(
    !emitted.contains("Scann("),
    "a leg that is neither folded nor nameable got a variant: {emitted}",
  );
}

/// **THE MINI DOORS ARE ON THE ROSTER**, so a declaration whose field collides with one earns a
/// named refusal rather than `E0592` at the attribute.
#[test]
fn the_mini_doors_are_rostered() {
  let model = fanned(vec![leg("lance", true, false), leg("hnsw", true, false)]);
  let names: Vec<String> = model
    .emitted_methods()
    .into_iter()
    .map(|emitted| emitted.name.to_string())
    .collect();
  for owed in ["vector_fuse_by_clip", "vector_fuse_similar_by_clip"] {
    assert!(names.contains(&owed.to_owned()), "{names:?}");
  }
  let types: Vec<String> = model
    .tier()
    .emitted_types()
    .into_iter()
    .map(|name| name.to_string())
    .collect();
  for owed in ["ShotsClipFusedEvidence", "ShotsClipFusedError"] {
    assert!(types.contains(&owed.to_owned()), "{types:?}");
  }
}

/// **A SET ELECTION GETS NO MINI DOOR**, for the reason a set election is no route of its tier: RRF
/// reads an ordinal and there is none across the `m` streams a fold authored.
///
/// The PACKAGES survive — they describe the write fan and cross the wire — so the absence is the
/// door's alone, which is what makes this a measurement rather than a blanket exclusion.
#[test]
fn a_fanned_set_election_fans_and_does_not_fuse() {
  let mut model = fanned(vec![leg("lance", true, false), leg("hnsw", true, false)]);
  model.embeddings = vec![Elected::new(
    ident("clip"),
    ElectionLabel::List,
    syn::parse_quote!(::std::vec::Vec<::ingraph::Embedding<f32, 4, Clip>>),
    None,
  )];
  let emitted = tight(&model);
  assert!(
    emitted.contains("structShotsClipFuseOptions"),
    "the write fan lost its package: {emitted}",
  );
  assert!(
    !emitted.contains("fnvector_fuse_by_clip"),
    "a set election grew a door whose ordinal does not exist: {emitted}",
  );
}