ingraph-codegen 0.1.0

The emission engine behind ingraph-derive: a plain declaration model in, the ingraph framework faces out.
Documentation
//! WHAT THE DOORS EMIT AROUND `k` — the ONE currency they now carry, the fork that is GONE, and the
//! two boundaries where a non-zero number is spent back into a plain `usize`.
//!
//! Beside [`by_key`](super::by_key) and [`similar_set`](super::similar_set) on this directory's own
//! precedent: one file per thing being proved. What only a token reading can prove is a TYPE and an
//! ABSENCE — the framework suite runs the doors and can see what they answer, but *no conversion is
//! written anywhere in this emission* is a fact about the emitted text.
//!
//! # The claim this file used to make, and the one it makes now
//!
//! It used to assert an ORDER: the doors kept `limit : usize`, each body forked a zero into an early
//! empty answer, and where that fork sat relative to a door's own by-key read was the difference
//! between a named refusal and a silent empty page. Every one of those assertions was about a branch.
//!
//! The currency is `NonZeroUsize` now, door-family-wide, so *ask for nothing* is not a request a
//! caller can compose and the branch has nothing left to decide. What is asserted here instead is the
//! SIGNATURE — because a type is what replaced the branch — and the ABSENCE of the conversion, which
//! is what says the fork was deleted rather than relocated.
//!
//! # The two `usize` boundaries are asserted TOO, and they are not a leak
//!
//! `ranked_keys` / `ranked_keys_excluding` / `set_scored` / `filled` count SURVIVORS, and a walk asked
//! for nothing is a legal call with an empty answer where an ENGINE asked for nothing is not a
//! question at all. So the runtime walks keep a plain `usize` and the doors spend `NonZeroUsize::get`
//! at the crossing. Asserting the spelling is what keeps the two currencies from being confused back
//! into one.

use super::{
  ElectionLabel, IndexModel,
  tests::{document, embedding_index},
};

/// The DOOR CURRENCY, spelled as the emitted tokens spell it.
const CURRENCY: &str = "limit : :: core :: num :: NonZeroUsize";

/// The conversion the retype DELETED — the zero fork, in the only spelling any door ever wrote it in.
const FORK: &str = "NonZeroUsize :: new (limit)";

/// The emission's tokens as text — the gate-blind reading, the doors living inside the observation
/// gate pair.
fn emitted(model: &IndexModel) -> String {
  model.emit().to_string()
}

/// The same model with its election relabelled a SET, which is what the two `_with` doors hang off.
fn as_set(mut model: IndexModel) -> IndexModel {
  for elected in &mut model.embeddings {
    elected.label = ElectionLabel::List;
    elected.ty = syn::parse_quote!(::std::vec::Vec<::ingraph::Embedding<f32, 4, Clip>>);
  }
  model
}

/// One door's own tokens, cut at the next item — signature, `where` clause and body, and none of the
/// neighbour's docs.
///
/// The cut matters here for the reason it matters in [`by_key`](super::by_key): an assertion about a
/// door's own text that ran into the next door's prose would answer about a sentence rather than
/// about a statement.
fn door<'a>(emission: &'a str, name: &str) -> &'a str {
  let at = emission
    .split(&format!("async fn {name} <"))
    .nth(1)
    .unwrap_or_else(|| panic!("`{name}` is emitted: {emission}"));
  let end = [at.find("# [doc"), at.find("async fn")]
    .into_iter()
    .flatten()
    .min()
    .unwrap_or(at.len());
  &at[..end]
}

/// EVERY DOOR OF THE FAMILY that takes a budget, counted rather than sampled — the vector side's five
/// under a SET election, and the full-text side's four.
fn family() -> [(String, Vec<&'static str>); 2] {
  [
    (
      emitted(&as_set(embedding_index())),
      vec![
        "retrieve_keys_by_image_embedding",
        "retrieve_by_image_embedding",
        "retrieve_similar_by_image_embedding",
        "retrieve_keys_by_image_embedding_with",
        "retrieve_similar_by_image_embedding_with",
      ],
    ),
    (
      emitted(&document()),
      vec![
        "retrieve_keys",
        "retrieve",
        "retrieve_keys_by_title",
        "retrieve_by_title",
      ],
    ),
  ]
}

/// **THE DOOR FAMILY CARRIES ONE CURRENCY, AND IT IS THE SEAM'S** — asserted over the whole roster
/// rather than over a door somebody remembered.
///
/// The negative half is what makes it a claim: a `limit : usize` anywhere in the family is a door
/// that still admits a number the engine below it cannot be handed, which is the two-seat disease the
/// k-seat round cured from the other side.
#[test]
fn every_door_of_the_family_takes_a_non_zero_budget() {
  for (emission, doors) in family() {
    for name in doors {
      let body = door(&emission, name);
      assert!(
        body.contains(CURRENCY),
        "`{name}` does not take the family's currency: {body}",
      );
      assert!(
        !body.contains("limit : usize"),
        "`{name}` still admits a zero: {body}",
      );
    }
  }
}

/// **THE ZERO FORK IS GONE FROM THE WHOLE EMISSION**, which is the difference between deleting a
/// branch and moving one.
///
/// The subject is the EMISSION and not a door, deliberately: a fork that survived anywhere — pushed
/// into a helper, hidden in one arm of a fanned leg — would satisfy a per-door assertion and would
/// still mean the type had not been trusted. There is exactly one spelling any door ever wrote this
/// in, and this says the emission contains none of it.
///
/// MUTATION-CHECKED: put back the `match NonZeroUsize::new(limit)` any one door used to open with,
/// and this reds while every behavioural test stays green — which is the whole of what an absence
/// needs a token reading for.
#[test]
fn no_door_body_converts_a_budget_because_none_arrives_convertible() {
  for (emission, _) in family() {
    assert!(
      !emission.contains(FORK),
      "a zero fork survived the retype: {emission}",
    );
  }
}

/// **THE UNBOUNDED ASK IS SPELLED IN THE FAMILY'S OWN CURRENCY.**
///
/// Tier B asks tier A for every above-floor key, because its own fill loop's filter is what decides
/// how many of them fill a page. That ask used to be `usize::MAX`; it is `NonZeroUsize::MAX` now, and
/// the SEMANTICS are unchanged — a huge `k` means *as many as exist*, and what it costs is the
/// engine's business in its own storage.
#[test]
fn tier_b_asks_tier_a_for_the_widest_number_the_currency_has() {
  let emission = emitted(&embedding_index());
  let body = door(&emission, "retrieve_by_image_embedding");

  assert!(
    body.contains(":: core :: num :: NonZeroUsize :: MAX"),
    "{body}",
  );
  assert!(
    !body.contains("usize :: MAX ,"),
    "the bare `usize::MAX` is a number this door can no longer hand its own tier A: {body}",
  );
}

/// **THE WALKS KEEP `usize`, AND THE DOORS SPEND THE NON-ZERO NUMBER AT THE CROSSING.**
///
/// A walk counts SURVIVORS — a walk asked for nothing is a legal call with an empty answer — so the
/// runtime helpers were not retyped, and the boundary is written out at each door that reaches one.
/// The assertion is the spelling, because the alternative that compiles is a door that quietly
/// retyped a walk and made *nothing survived* unrepresentable too.
#[test]
fn the_runtime_walks_are_handed_a_plain_count() {
  let emission = emitted(&as_set(embedding_index()));

  for (name, walk) in [
    ("retrieve_keys_by_image_embedding", "ranked_keys"),
    (
      "retrieve_similar_by_image_embedding",
      "ranked_keys_excluding",
    ),
    ("retrieve_keys_by_image_embedding_with", "set_scored"),
    ("retrieve_similar_by_image_embedding_with", "set_scored"),
    ("retrieve_by_image_embedding", "filled"),
  ] {
    let body = door(&emission, name);
    assert!(
      body.contains(walk),
      "`{name}` no longer reaches `{walk}`: {body}",
    );
    assert!(
      body.contains(":: core :: num :: NonZeroUsize :: get (limit)"),
      "`{name}` hands `{walk}` something other than the spent budget: {body}",
    );
  }
}

/// **THE FULL-TEXT DOOR TAKES THE SAME SEAT**, at both grains its subject comes in.
///
/// The whole-subject door and a per-column one are two subjects and one law, so the `k` they hand
/// `search` sits between the query text and the knobs in both — which is the parameter law read off
/// the emission rather than off the trait. It is the door's own `limit` that arrives there now, with
/// nothing in between, and the knobs beside it are the door's own `options` rather than the fixed
/// `None` that stood in the seat while it was unwired.
#[test]
fn the_fulltext_door_hands_its_k_between_the_query_and_the_knobs() {
  let body = {
    let emission = emitted(&document());
    door(&emission, "retrieve_keys").to_owned()
  };

  assert!(body.contains("query . text () , limit , options"), "{body}");
}