ingraph-codegen 0.1.0

The emission engine behind ingraph-derive: a plain declaration model in, the ingraph framework faces out.
Documentation
//! THE ADDITIVE DOOR LAW — which of the three fused doors a tier emits, over every modality shape
//! there is, and the evidence enum that rides them.
//!
//! Beside [`engines`](super::engines) rather than inside [`tests`](super::tests), on that file's own
//! precedent: one file per thing being proved.
//!
//! # The law is asserted over the NUMBERS and over the TIERS, and both halves are needed
//!
//! [`Doors::of`] is the rule and it is total over two counts, so it can be read exhaustively —
//! which is what the shape table below does. What a TIER's counts actually are is the second half
//! and the one a rule cannot check itself: a full-text declaration is one route however many fields
//! it elects, and a set election is no route at all, and neither fact is visible from a number.

use super::{
  Doors,
  tests::{blob, fanned, fulltext, one_slot, two_slots},
};
use crate::{
  index::{Elected, ElectionLabel},
  model::NodeKind,
};

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

/// A single-vector election, the only shape that enters a fused door.
fn single(field: &str) -> Elected {
  Elected::new(
    ident(field),
    ElectionLabel::Embedding,
    syn::parse_quote!(::ingraph::Embedding<f32, 4, Clip>),
    None,
  )
}

/// A VECTOR declaration electing TWO SINGLE fields — the one index shape the law gives a door to.
fn two_singles() -> crate::index::IndexModel {
  let mut model = one_slot();
  model.embeddings = vec![single("clip"), single("poster")];
  model
}

/// **THE LAW, OVER EVERY SHAPE ITS TWO COUNTS CAN TAKE.** Read as a table because the rule is total
/// and small: a reader checking whether a shape is handled should be able to find the row.
#[test]
fn the_law_is_a_table_over_two_counts() {
  // (full-text routes, vector routes) => (fulltext_fuse, vector_fuse, fuse)
  for (fulltext, vector, expected) in [
    (0, 0, (false, false, false)),
    (1, 0, (false, false, false)),
    (2, 0, (true, false, false)),
    (0, 1, (false, false, false)),
    (0, 2, (false, true, false)),
    (1, 1, (false, false, true)),
    (2, 1, (true, false, true)),
    (1, 2, (false, true, true)),
    (2, 2, (true, true, true)),
  ] {
    let doors = Doors::of(fulltext, vector);
    assert_eq!(
      (doors.fulltext, doors.vector, doors.mixed),
      expected,
      "({fulltext}, {vector})",
    );
  }
}

/// **A SINGLE-MODALITY TIER NEVER GETS THE MIXED DOOR**, however many routes it has — two doors
/// over one route set would be two spellings of one behaviour.
#[test]
fn the_mixed_door_needs_both_modalities() {
  for routes in 2..6 {
    assert!(!Doors::of(routes, 0).mixed, "{routes} full-text routes");
    assert!(!Doors::of(0, routes).mixed, "{routes} vector routes");
  }
}

/// **A SINGLE-ROUTE TIER GETS NO FUSED DOOR AT ALL** — and keeps every per-kind door it had, which
/// is the additive half of the law and is asserted on the emission rather than on the numbers.
#[test]
fn a_single_route_tier_fuses_nothing_and_loses_nothing() {
  let tier = one_slot();
  assert!(!tier.tier().doors().any());
  let emitted = tier.emit().to_string();
  assert!(
    emitted.contains("retrieve_keys_by_image_embedding"),
    "the plain door stopped emitting: {emitted}",
  );
  assert!(
    !emitted.contains("vector_fuse"),
    "a one-route tier grew a fused door: {emitted}",
  );
}

/// **A FULL-TEXT TIER IS ONE ROUTE HOWEVER MANY FIELDS IT ELECTS**, so `fulltext_fuse` has no home
/// at the index grain — its home is the ROOT, where two full-text MEMBERS can meet.
///
/// `FulltextRead::search` takes no column selector at the route grain: an elected field is a
/// COLUMN of one subject, which is what the package's `columns` row says.
#[test]
fn a_fulltext_declaration_is_one_route() {
  let tier = fulltext();
  assert_eq!(tier.searchable.len(), 2, "the fixture elects two fields");
  assert!(
    !tier.tier().doors().any(),
    "two elected COLUMNS were read as two routes",
  );
}

/// **A SET ELECTION IS NOT A ROUTE**, and the absence is at EMISSION rather than at run time.
///
/// RRF reads the ENGINE's raw ordinal. A `list(embedding)` election answers in `Folded`, whose
/// order the FOLD authored and across whose `m` streams no ordinal is minted — so there is no
/// number to hand the fold that means what it reads, and passing the folded answer's POSITION would
/// produce a perfectly ordered result on every fixture whose floor let everything through.
#[test]
fn a_set_election_does_not_enter_a_fused_door() {
  // `two_slots` is one SET election beside one single, so it has two elections and ONE route.
  let tier = two_slots();
  assert_eq!(tier.embeddings.len(), 2, "the fixture elects two fields");
  assert_eq!(tier.tier().fused_routes().count(), 1);
  assert!(
    !tier.tier().doors().any(),
    "a set election was counted as a route",
  );

  // Two SINGLE elections is the shape that does get the door.
  assert!(two_singles().tier().doors().vector);
}

/// **A KIND THAT DOES NOT RETRIEVE FUSES NOTHING** — the presence law, on this axis.
#[test]
fn a_non_retrieving_kind_has_no_doors() {
  assert!(!blob().tier().doors().any());
  assert_eq!(blob().tier().doors(), Doors::of(0, 0));
}

/// **A FANNED SLOT IS STILL ONE ROUTE OF ITS TIER.** The fan descends INSIDE the slot's own package
/// — its legs are that mini tier's routes — and a parent absorbs the whole of it as one, which is
/// the property the fractal was built for.
#[test]
fn a_fanned_slot_is_one_route_of_its_parent() {
  let tier = fanned();
  assert_eq!(tier.tier().fused_routes().count(), 1);
  assert!(!tier.tier().doors().any());
}

/// **THE EVIDENCE ENUM RIDES THE DOORS**, one variant per route that enters one — so a tier that
/// fuses nothing mints no evidence type either.
///
/// And ONE CURRENCY PARAMETER PER ROUTE, which is the heterogeneous widening: two routes written in
/// two stores score in two currencies, and a single `__INGRAPH_SCORE__` was the same-engine special
/// case wearing the general name.
#[test]
fn the_evidence_enum_is_one_variant_per_route() {
  let emitted = two_singles()
    .tier()
    .emit()
    .to_string()
    .split_whitespace()
    .collect::<String>();
  assert!(
    emitted.contains("enumCaptionsFusedEvidence<__INGRAPH_SCORE_CLIP__,__INGRAPH_SCORE_POSTER__,>"),
    "{emitted}",
  );
  assert!(
    emitted.contains("Clip(__INGRAPH_SCORE_CLIP__),"),
    "{emitted}"
  );
  assert!(
    emitted.contains("Poster(__INGRAPH_SCORE_POSTER__),"),
    "{emitted}",
  );

  for silent in [one_slot(), fulltext(), blob()] {
    let kind = silent.kind;
    let emitted = silent.tier().emit().to_string();
    assert!(
      !emitted.contains("FusedEvidence"),
      "{kind:?} mints evidence for a door it does not have: {emitted}",
    );
  }
}

/// **THE REFUSAL ENUM IS THE EVIDENCE ENUM'S TWIN**, one variant AND one error parameter per route
/// — because a door asking two engines has two `Error` types and no blanket one to widen them into.
#[test]
fn the_fused_refusal_names_the_route_that_spoke_it() {
  let emitted = two_singles()
    .tier()
    .emit()
    .to_string()
    .split_whitespace()
    .collect::<String>();
  assert!(
    emitted.contains("enumCaptionsFusedError<__INGRAPH_ERROR_CLIP__,__INGRAPH_ERROR_POSTER__,>"),
    "{emitted}",
  );
  assert!(
    emitted.contains("Clip(__INGRAPH_ERROR_CLIP__),"),
    "{emitted}"
  );
  assert!(
    emitted.contains("Poster(__INGRAPH_ERROR_POSTER__),"),
    "{emitted}",
  );

  for silent in [one_slot(), fulltext(), blob()] {
    let kind = silent.kind;
    let emitted = silent.tier().emit().to_string();
    assert!(
      !emitted.contains("FusedError"),
      "{kind:?} mints a fused refusal for a door it does not have: {emitted}",
    );
  }
}

/// **THE EVIDENCE TYPE IS ON THE ROSTER**, so a declaration whose neighbour already owns that name
/// is refused by name rather than by `E0428` at a span nobody wrote.
#[test]
fn the_evidence_type_is_rostered() {
  let types: Vec<String> = two_singles()
    .tier()
    .emitted_types()
    .into_iter()
    .map(|name| name.to_string())
    .collect();
  assert!(
    types.contains(&"CaptionsFusedEvidence".to_owned()),
    "{types:?}",
  );
  assert!(
    types.contains(&"CaptionsFusedError".to_owned()),
    "{types:?}"
  );
  for absent in ["CaptionsFusedEvidence", "CaptionsFusedError"] {
    assert!(
      !one_slot()
        .tier()
        .emitted_types()
        .iter()
        .any(|name| name == absent),
      "a one-route tier rosters `{absent}`, a type it does not emit",
    );
  }
}

/// **THE DOORS THEMSELVES ARE ON THE INDEX'S ROSTER**, which is what makes a declaration with a
/// field called `vector_fuse` a named refusal rather than `E0592` at the attribute.
#[test]
fn the_fused_doors_are_rostered() {
  let names: Vec<String> = two_singles()
    .emitted_methods()
    .into_iter()
    .map(|emitted| emitted.name.to_string())
    .collect();
  for owed in ["vector_fuse", "vector_fuse_similar"] {
    assert!(names.contains(&owed.to_owned()), "{names:?}");
  }
  assert!(
    !one_slot()
      .emitted_methods()
      .iter()
      .any(|emitted| emitted.name == "vector_fuse"),
    "a one-route tier rosters a door it does not emit",
  );
  assert_eq!(
    NodeKind::Vector,
    two_singles().kind,
    "the fixture is the kind the doors are about",
  );
}