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
use async_graphql::OutputType as _;

use super::{OutputCrossing, ToGraphqlOutput};
use crate::{
  BytesMarker, DefaultVecMarker, I64, I128, ListMarker, QuantifiedMarker, U128,
  primitives::{Count, Score, Timestamp},
};

/// The id type a declaration writes where the real one is a UUIDv7 newtype — the alias the corpus
/// itself uses, so what is pinned here is what a declaration writes.
type Uuid7 = u128;

/// **THE ALIAS IS NOT A TYPE.** A projection chosen by matching the written word would hand `Uuid7`
/// straight through; resolved by the compiler it reaches `u128`'s row, and the two spellings name
/// one output form.
///
/// The SIGNATURE below is the type half of the claim — a function handing an alias's projection back
/// as the type's is well formed only while the two are one type — and the values are the value half.
#[expect(
  dead_code,
  reason = "the signature is the assertion — rustc checks it without a caller"
)]
fn one_form_under_two_spellings(
  projected: <Uuid7 as ToGraphqlOutput>::Output<'_>,
) -> <u128 as ToGraphqlOutput>::Output<'_> {
  projected
}

#[test]
fn an_alias_projects_exactly_as_the_type_it_names() {
  let through_alias: <Uuid7 as ToGraphqlOutput>::Output<'_> =
    <Uuid7 as ToGraphqlOutput>::to_graphql_output(&7_u128);
  let through_type: <u128 as ToGraphqlOutput>::Output<'_> =
    <u128 as ToGraphqlOutput>::to_graphql_output(&7_u128);

  assert_eq!(through_alias, through_type);
  assert_eq!(through_alias, U128::from(7_u128));
}

/// The row the whole map was minted for: a 128-bit integer leaves as its carrier, and the carrier's
/// wire form is TEXT.
#[test]
fn the_wide_integers_cross_through_their_carriers() {
  assert_eq!(
    <u128 as ToGraphqlOutput>::to_graphql_output(&u128::MAX),
    U128::from(u128::MAX)
  );
  assert_eq!(
    <i128 as ToGraphqlOutput>::to_graphql_output(&i128::MIN),
    I128::from(i128::MIN)
  );

  assert_eq!(<u128 as ToGraphqlOutput>::Output::<'_>::type_name(), "u128");
  assert_eq!(<i128 as ToGraphqlOutput>::Output::<'_>::type_name(), "i128");
}

/// A type async-graphql already faces is returned BY REFERENCE, which is what keeps the common case
/// free of a clone per field per row.
#[test]
fn a_facing_type_crosses_as_itself() {
  let title = String::from("the take");
  let projected: &String = <String as ToGraphqlOutput>::to_graphql_output(&title);

  assert!(core::ptr::eq(projected, &title));
  assert_eq!(
    <String as ToGraphqlOutput>::Output::<'_>::type_name(),
    "String"
  );
}

/// The framework's own three primitives are rows here, so a record exposing a confidence, an instant
/// or a cardinality needs nothing of its own — and they do not all take the same arm, which is the
/// 2026-08-21 ruling and the 2026-08-27 one read together.
///
/// An instant faces itself under a scalar this crate mints. A confidence crosses through its WIDTH's
/// own roster carrier — `f32` here — because the four `Score*` scalars are retired: what they added
/// over the roster row was the interval, which is a constructor's promise rather than a grammar, so
/// the name bought a client nothing it could act on and cost it a second word for one wire form.
///
/// **A CARDINALITY takes the confidence's arm and not the instant's**, and the reason is the same
/// sentence one type over: what `Count` adds to a `u64` is a PROVENANCE — *this magnitude counted
/// rows that exist* — which buys a client nothing to act on and buys the STORAGE side a narrowing.
/// So it returns `u64`'s own roster carrier and the SDL says `u64`.
#[test]
fn the_frameworks_own_primitives_are_rows() {
  let score = Score::new(0.5).expect("half is inside the unit interval");
  let projected = <Score as ToGraphqlOutput>::to_graphql_output(&score);
  assert_eq!(f32::from(projected), 0.5);

  assert_eq!(<Score as ToGraphqlOutput>::Output::<'_>::type_name(), "f32");
  assert_eq!(
    <Timestamp as ToGraphqlOutput>::Output::<'_>::type_name(),
    "Timestamp"
  );

  let tracks = Count::new(9);
  assert_eq!(
    u64::from(<Count as ToGraphqlOutput>::to_graphql_output(&tracks)),
    9
  );
  assert_eq!(<Count as ToGraphqlOutput>::Output::<'_>::type_name(), "u64");
}

/// **The one element whose `Vec` is not a list.** A blob leaves as hex; a list of the same element
/// type would have left as `[Int!]`, which is the face this map exists to keep out of a schema.
#[test]
fn a_byte_vector_crosses_as_hex_and_a_list_does_not() {
  let cover = vec![0x89_u8, 0x50, 0x4e, 0x47];
  let projected: crate::U8Vector = <Vec<u8> as ToGraphqlOutput>::to_graphql_output(&cover);

  assert_eq!(projected.to_string(), "89504e47");
  assert_eq!(
    <Vec<u8> as ToGraphqlOutput>::Output::<'_>::type_name(),
    "U8Vector"
  );

  // Every other element keeps the LIST, and a numeric element crosses into its own width's wrapper
  // element by element — where it used to be handed back as `[Int!]`, a list of *some integer*.
  let counts = vec![1_i64, 2, 3];
  let listed: Vec<I64> = <Vec<i64> as ToGraphqlOutput>::to_graphql_output(&counts);
  assert_eq!(listed, vec![I64::from(1), I64::from(2), I64::from(3)]);
  assert_eq!(
    <Vec<i64> as ToGraphqlOutput>::Output::<'_>::type_name(),
    "[i64!]"
  );

  // An IDENTITY element still borrows the row's own storage, which is the half the suite did not
  // take: `String` faces itself, so its list is a list of references and nothing is copied.
  let titles = vec![String::from("the take")];
  let borrowed: Vec<&String> = <Vec<String> as ToGraphqlOutput>::to_graphql_output(&titles);
  assert!(core::ptr::eq(borrowed[0], &titles[0]));
}

/// A `Vec` of a CARRIER element is a list of carriers — the projection reaching inside the
/// collection, which is what a `&[u128]` could never be.
#[test]
fn a_vector_of_wide_integers_crosses_element_by_element() {
  let ids = vec![1_u128, u128::MAX];
  let projected: Vec<U128> = <Vec<u128> as ToGraphqlOutput>::to_graphql_output(&ids);

  assert_eq!(projected, vec![U128::from(1_u128), U128::from(u128::MAX)]);
  assert_eq!(
    <Vec<u128> as ToGraphqlOutput>::Output::<'_>::type_name(),
    "[u128!]"
  );
}

/// A COLLECTION of blobs — the element's own row reaching inside a list, and the nested shape a
/// backend actually stores.
#[test]
fn a_vector_of_blobs_is_a_list_of_hex() {
  let covers = vec![vec![0xff_u8, 0xd8], Vec::new()];
  let projected: Vec<crate::U8Vector> =
    <Vec<Vec<u8>> as ToGraphqlOutput>::to_graphql_output(&covers);

  assert_eq!(
    projected
      .iter()
      .map(ToString::to_string)
      .collect::<Vec<_>>(),
    vec![String::from("ffd8"), String::new()]
  );
  assert_eq!(
    <Vec<Vec<u8>> as ToGraphqlOutput>::Output::<'_>::type_name(),
    "[U8Vector!]"
  );
}

/// **THE NARROW COLLECTION RETURNS ITS MEMBERS**, exactly as the two wide readings do.
///
/// [`QuantifiedMarker`] is a fact about the FILTER: an element with no honest literal makes seven of
/// a sequence's nine operators unanswerable, so that reading publishes `any` and `count` alone. A
/// RETURN is not a reading — what a client receives is the members — so the form is the list every
/// collection reading gives, and the assertion is that the markers agree rather than merely both
/// existing.
///
/// The row was ABSENT while no element in this crate defaulted to the narrow marker, and the absence
/// was invisible for a reason worth keeping: a declaration's `quantified` word moves the FILTER and
/// never reaches this map, so a `Vec<u64>` declared narrow still projected through `u64`'s own
/// [`ListMarker`] default. `primitives::lang`'s `DetectedLanguage` is the first element whose
/// [`DefaultVecMarker`] IS the narrow one — a `Vec` of it being the top-k shape that family's ruling
/// names — so the hole surfaced as `E0277` at the emitted face of a column meant to be held.
#[test]
fn the_narrow_collection_reading_returns_the_list_the_wide_ones_do() {
  let titles = vec![String::from("a red car"), String::from("a blue one")];

  let narrow: Vec<&String> =
    <QuantifiedMarker<Vec<String>> as ToGraphqlOutput<Vec<String>>>::to_graphql_output(&titles);
  let wide: Vec<&String> =
    <ListMarker<Vec<String>> as ToGraphqlOutput<Vec<String>>>::to_graphql_output(&titles);

  assert!(
    core::ptr::eq(narrow[0], &titles[0]),
    "the members, borrowed rather than cloned"
  );
  assert_eq!(
    narrow, wide,
    "and the same members the wide reading returns"
  );
  assert_eq!(
    <QuantifiedMarker<Vec<String>> as ToGraphqlOutput<Vec<String>>>::Output::<'_>::type_name(),
    "[String!]",
    "one SDL form for all three readings",
  );
}

/// The nullable leg projects what is UNDER the option, so a nullable wide column reaches the same
/// carrier the `NOT NULL` one does.
#[test]
fn a_nullable_column_projects_its_inner_half() {
  let held: Option<u128> = Some(9);
  let empty: Option<u128> = None;

  assert_eq!(
    <Option<u128> as ToGraphqlOutput>::to_graphql_output(&held),
    Some(U128::from(9_u128))
  );
  assert_eq!(
    <Option<u128> as ToGraphqlOutput>::to_graphql_output(&empty),
    None
  );
  assert_eq!(
    <Option<u128> as ToGraphqlOutput>::Output::<'_>::type_name(),
    "u128"
  );
}

/// **THE `Vec` FORK IS THE INPUT SIDE'S OWN ROW** — the mechanism the second output trait was
/// retired for.
///
/// The signature is the whole assertion, and it is written twice over one fact: `u8`'s
/// [`DefaultVecMarker`] row names [`BytesMarker`] and every other element's names [`ListMarker`], so
/// a `Vec<u8>`'s output form is the BLOB marker's and a `Vec<i64>`'s is the collection marker's.
/// Nothing on the output side decides it, and nothing on the output side could disagree with the
/// filter about it.
#[expect(
  dead_code,
  reason = "the signature is the assertion — rustc checks it without a caller"
)]
fn the_vec_fork_is_read_off_the_elements_marker<'a>(
  blob: <BytesMarker<Vec<u8>> as ToGraphqlOutput<Vec<u8>>>::Output<'a>,
  list: <ListMarker<Vec<i64>, crate::ScalarMarker<i64>> as ToGraphqlOutput<Vec<i64>>>::Output<'a>,
) -> (
  <Vec<u8> as ToGraphqlOutput>::Output<'a>,
  <Vec<i64> as ToGraphqlOutput>::Output<'a>,
) {
  (blob, list)
}

/// The same fact from the other end: the element's declared marker IS what the delegation names.
#[expect(
  dead_code,
  reason = "the signature is the assertion — rustc checks it without a caller"
)]
fn the_elements_marker_is_the_one_the_input_side_registered(
  marker: <u8 as DefaultVecMarker>::Marker,
) -> BytesMarker<Vec<u8>> {
  marker
}

/// The witness demands the row and nothing else — one line per class of the wire table.
///
/// A signature rather than a call, because what is asserted is that each of these types HAS a row;
/// rustc checks that without anything running.
#[expect(
  dead_code,
  reason = "the signature is the assertion — rustc checks it without a caller"
)]
fn every_class_of_the_wire_table_has_a_row() -> [(); 10] {
  const _: OutputCrossing<i64> = OutputCrossing::WITNESS;
  const _: OutputCrossing<String> = OutputCrossing::WITNESS;
  const _: OutputCrossing<Uuid7> = OutputCrossing::WITNESS;
  const _: OutputCrossing<i128> = OutputCrossing::WITNESS;
  const _: OutputCrossing<Vec<u8>> = OutputCrossing::WITNESS;
  const _: OutputCrossing<Vec<i64>> = OutputCrossing::WITNESS;
  const _: OutputCrossing<Vec<Vec<u8>>> = OutputCrossing::WITNESS;
  const _: OutputCrossing<Option<u128>> = OutputCrossing::WITNESS;
  const _: OutputCrossing<Score> = OutputCrossing::WITNESS;
  const _: OutputCrossing<Count> = OutputCrossing::WITNESS;

  [(); 10]
}