ingraph-codegen 0.1.0

The emission engine behind ingraph-derive: a plain declaration model in, the ingraph framework faces out.
Documentation
//! WHAT THE SIMILAR-BY-EXAMPLE DOOR EMITS — one per election, its shape, and the kinds of
//! declaration that get none.
//!
//! Beside [`engines`](super::engines) and [`elections`](super::elections) rather than inside
//! [`tests`](super::tests), on those files' own precedent: one file per thing being proved.
//! [`by_key`](super::by_key) is the sibling this file now leans on — the read the door is written
//! in terms of, and the single authority for what a stored vector has to be.
//!
//! # Every assertion is written as an EXCLUSION too
//!
//! The door is *sugar over the pair*, and the way sugar goes wrong is by quietly becoming a second
//! query path. So the assertions are as much about what the body does NOT contain — the plain
//! `ranked_keys`, a `AsyncGather`, a store parameter, a `Semantics`, and now any judgment of its own —
//! as about what it does. An emission that walked its own pipeline would pass an inclusion-only
//! suite while answering ranks the engine never gave.
//!
//! # The readings moved from the EMISSION to the DOOR, and that is the delegation's own cost
//!
//! Several assertions here used to search the whole emission for a word. That was sound while the
//! door was the only thing in the expansion that could contain one; it stopped being sound the day
//! the get door was emitted beside it, because the words are all in THAT body now. Each such
//! reading is therefore cut to this door's own tokens, and the ones that were only ever about the
//! read are gone from this file rather than left to pass for the wrong reason.

use super::{
  IndexModel,
  tests::{document, embedding_index, two_elections},
};
use crate::{model::NodeKind, prefix::EmissionPrefix};

/// The emission's tokens as text — the gate-blind reading, because the doors live inside the
/// observation gate pair and the subject here is the door rather than the gate.
fn emitted(model: &IndexModel) -> String {
  model.emit().to_string()
}

/// **ONE DOOR PER ELECTION, named after the field its `knn` marker elected** — the pair's own naming
/// law, spent on the third door.
///
/// Counted at TWO per name because the retrieve face is written once per half of the observation
/// gate, which is the shape every door here already has.
#[test]
fn every_election_gets_its_own_similar_door() {
  let emission = emitted(&two_elections());
  for field in ["caption_embedding", "image_embedding"] {
    assert_eq!(
      emission
        .matches(&format!("async fn retrieve_similar_by_{field} <"))
        .count(),
      2,
      "`retrieve_similar_by_{field}` is not written once per gate half: {emission}"
    );
  }
}

/// **A DECLARATION THAT ELECTS NOTHING GETS NO DOOR**, and the two kinds that elect nothing get it
/// for two different reasons.
///
/// A full-text index elects fields with `searchable` and its engine now takes a column subset, so
/// it HAS the per-field search doors — what it has no grammar for is the by-key READ those two doors
/// are built on: `FulltextEngine` answers hits and nothing hands a stored document back. A `blob` is
/// addressed rather than ranked and answers no retrieve at all. Neither is a gap waiting to be
/// filled by this round.
#[test]
fn a_kind_with_no_election_gets_no_similar_door() {
  for model in [
    document(),
    IndexModel {
      prefix: EmissionPrefix::default(),
      kind: NodeKind::Blob,
      ..document()
    },
  ] {
    let emission = emitted(&model);
    assert!(
      !emission.contains("retrieve_similar"),
      "{:?} carries a door it cannot answer: {emission}",
      model.kind
    );
  }
}

/// **THE BODY IS THE RULED RECIPE AND NOTHING ELSE** — *fetch own set → query with it → exclude
/// self*, each step a call to something that already existed.
///
/// Read on the DOOR's own body rather than on the whole emission, which is what the first step
/// becoming a door of its own cost this assertion: *fetch own set* used to be two framework calls
/// written here and is now one call to `get_<field>`, so an emission-wide reading would go on
/// finding `vector_addressed` in the door next to this one and report a recipe this body no longer
/// contains. What that door does with those two calls is [`super::by_key`]'s subject.
#[test]
fn the_body_is_the_ruled_recipe() {
  let emission = emitted(&embedding_index());
  let door = emission
    .split("async fn retrieve_similar_by_image_embedding <")
    .nth(1)
    .expect("the door is emitted");
  let body = door.split("async fn").next().expect("the door has a body");
  for call in [
    // fetch own set, through the by-key door that judges what came back
    "get_image_embedding",
    // query with it, through the SAME knn the raw pair calls
    "knn",
    // the same address read the raw pair performs
    "vector_keyed",
    // exclude self — the walk with the example already seen
    "ranked_keys_excluding",
  ] {
    assert!(
      body.contains(call),
      "the recipe is missing `{call}`: {body}"
    );
  }
}

/// **THE EXCLUSION IS THE WALK'S OWN, and the plain walk is what the door must NOT reach.**
///
/// The mutation this exists for is the tempting one: call `ranked_keys` and `retain` the example out
/// afterwards. That answers the same entities and the wrong ranks, and no other assertion in this
/// crate would notice.
#[test]
fn the_similar_door_never_reaches_the_plain_walk() {
  let emission = emitted(&embedding_index());
  let door = emission
    .split("async fn retrieve_similar_by_image_embedding")
    .nth(1)
    .expect("the door is emitted");
  let body = door.split("async fn").next().expect("the door has a body");
  assert!(
    body.contains("ranked_keys_excluding"),
    "the door does not exclude: {body}"
  );
  assert!(
    !body.contains("retain"),
    "the door filters instead of seeding the membership: {body}"
  );
}

/// **IT IS TIER A AND ONLY TIER A** — the ruling names two doors and both are `retrieve_keys_*`, so
/// there is no store parameter, no filter and no gather anywhere in this one.
#[test]
fn the_similar_door_takes_no_store() {
  let emission = emitted(&embedding_index());
  let door = emission
    .split("async fn retrieve_similar_by_image_embedding")
    .nth(1)
    .expect("the door is emitted");
  let signature = door.split('{').next().expect("the door has a signature");
  assert!(
    !signature.contains("AsyncGather"),
    "a tier-A door gathers: {signature}"
  );
  assert!(
    !signature.contains("filter"),
    "a tier-A door filters: {signature}"
  );
}

/// **TWO READ SCOPES**, because the door makes two engine calls and a `Connected` is not `Clone`.
///
/// Asserted on the signature rather than on a count of the type, since both scopes project the same
/// `ReadContext` — what says there are two is the two parameter NAMES.
#[test]
fn the_similar_door_takes_a_scope_per_crossing() {
  let emission = emitted(&embedding_index());
  let door = emission
    .split("async fn retrieve_similar_by_image_embedding")
    .nth(1)
    .expect("the door is emitted");
  let signature = door.split('{').next().expect("the door has a signature");
  assert!(
    signature.contains("own :"),
    "no own-read scope: {signature}"
  );
  assert!(signature.contains("scope :"), "no knn scope: {signature}");
  // The example is a BORROW: the caller keeps its key, and the walk's membership takes whatever copy
  // it needs on its own terms.
  assert!(signature.contains("key : &"), "{signature}");
}

/// **IT RESTATES NO JUDGMENT AND NARROWS NO REFUSAL** — everything the by-key door can say about the
/// example reaches this door's caller unchanged.
///
/// The two claims are one design: the arity and the width are decided in `get_<field>`, so this
/// body has nothing to decide, and the error it declares has to be the SAME four-arm type or the
/// delegation would need a translation — which is the one thing a sugar door must not add, because
/// a re-worded refusal is a refusal a caller cannot match the original against.
///
/// This replaced two whole-emission readings that asserted `Embedding`, `DIM`, `Width`, `Unindexed`
/// and `Several` appeared SOMEWHERE. They did, and they still do — in the door next to this one — so
/// as claims about the similar door they had already stopped being true. What proves them now is
/// [`super::by_key`], which counts rather than sights.
#[test]
fn the_door_restates_no_judgment_and_narrows_no_refusal() {
  let emission = emitted(&embedding_index());
  let door = emission
    .split("async fn retrieve_similar_by_image_embedding <")
    .nth(1)
    .expect("the door is emitted");
  let signature = door.split('{').next().expect("the door has a signature");
  assert!(
    signature.contains("OwnReadError"),
    "the door hands back some other vocabulary: {signature}"
  );
  // Cut at the next item's first DOC as well as at its `async fn`, because what follows this door
  // is a neighbour's prose and a negative assertion that read it would be answering about words in
  // a doc comment.
  let end = [door.find("# [doc"), door.find("async fn")]
    .into_iter()
    .flatten()
    .min()
    .unwrap_or(door.len());
  let body = &door[..end];
  for judgment in ["Unindexed", "Several", "Width", "DIM"] {
    assert!(
      !body.contains(judgment),
      "the door decides `{judgment}` for itself, so two doors can drift about it: {body}"
    );
  }
}

/// **NO `Semantics`** — the fold vocabulary belongs to the multi-vector round, which has not landed
/// on this line, and a door minting the word here would be inventing it.
#[test]
fn the_similar_door_mints_no_fold_vocabulary() {
  let emission = emitted(&two_elections());
  assert!(!emission.contains("Semantics"), "{emission}");
  assert!(!emission.contains("FoldedQuery"), "{emission}");
}

/// **IT WEARS ITS OWN SPAN**, named by its own `entry` — the fifth door of the instrumented half.
#[test]
fn the_similar_door_names_itself_in_its_span() {
  let emission = emitted(&embedding_index());
  assert!(
    emission.contains("entry = \"retrieve_similar_by_image_embedding\""),
    "the door opens no span of its own: {emission}"
  );
}