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
//! The seam's two roads, spent — and the words they declare, which is the whole of what the switch
//! changed.
//!
//! The COMPLETENESS half of this module needs no test: it is the audit at the bottom of the parent
//! file, checked by the compiler over the same member list `store::fs` and `store::field` audit. So
//! what is left here is what a compiling row says nothing about — that the round trip actually
//! recovers the value, that a refusal is a refusal, and that the two roads land in DIFFERENT columns.

use super::IdColumn;

/// The dialect a road is read at when the question is not about a dialect. `()` is no database, and
/// every row but `u64`'s resolves for it — see `stores_dialect_blind`, where that is the audit's own
/// instrument, and `stores_dialect` beside it, which is `u64`'s: it took the per-`Db` seat on the
/// 2026-08-30 MySQL ruling, so its own round trip is asked per CONCRETE dialect below rather than
/// through this one.
type Blind = ();

/// One value, through the column and back.
fn round_trip<T: IdColumn<Blind>>(value: T) -> Result<T, T::Refusal> {
  T::from_stored(value.to_stored())
}

/// **THE TEXT ROAD RECOVERS THE VALUE**, which is the one obligation the trait states — a lossy
/// crossing at an ADDRESS is two keys resolving one row.
///
/// `i128`/`u64`/`u128` are NOT here — the 2026-08-30 ruling moved them to the big-endian blob road,
/// and [`the_big_endian_blob_road_round_trips_the_wide_integers`] is their round trip now.
#[test]
fn the_text_road_round_trips_every_shape_it_carries() {
  assert_eq!(round_trip(-42_i64), Ok(-42));
  assert_eq!(
    round_trip(core::num::NonZeroU32::new(7).expect("seven is not zero")),
    Ok(core::num::NonZeroU32::new(7).expect("seven is not zero")),
  );
  assert_eq!(
    round_trip("2001:db8::1".parse::<core::net::Ipv6Addr>().expect("a v6")),
    Ok("2001:db8::1".parse().expect("a v6")),
  );
  assert_eq!(
    round_trip(
      "[2001:db8::1]:443"
        .parse::<core::net::SocketAddrV6>()
        .expect("a v6 socket"),
    ),
    Ok("[2001:db8::1]:443".parse().expect("a v6 socket")),
  );
}

/// The rendering IS the type's own, and nothing here invents a grammar: what a column holds is what
/// `Display` writes.
#[test]
fn the_stored_text_is_the_types_own_rendering() {
  assert_eq!(<i64 as IdColumn<Blind>>::to_stored(&-42), "-42");
  assert_eq!(
    <core::net::Ipv4Addr as IdColumn<Blind>>::to_stored(&core::net::Ipv4Addr::new(10, 0, 0, 1)),
    "10.0.0.1",
  );
}

/// A stored form the type does not admit is REFUSED rather than read around — the failure a
/// hand-edited row reaches, carried as the type's own parse error.
#[test]
fn the_text_road_refuses_a_spelling_the_type_does_not_admit() {
  assert!(<i64 as IdColumn<Blind>>::from_stored("not a number".to_owned()).is_err());
  assert!(
    <core::num::NonZeroU32 as IdColumn<Blind>>::from_stored("0".to_owned()).is_err(),
    "the invariant is re-established coming back, by the type's own door",
  );
  assert!(<core::net::IpAddr as IdColumn<Blind>>::from_stored(String::new()).is_err());
}

/// **THE ONE MEMBER THAT MOVED** — a uuid is stored as itself, sixteen bytes, with no rendering
/// between the value and the column.
#[test]
fn the_uuid_road_is_the_value_itself() {
  let raw = uuid::Uuid::from_u128(0x0192_38ab_cdef_0123_4567_89ab_cdef_0123);
  let stored: uuid::Uuid = <uuid::Uuid as IdColumn<Blind>>::to_stored(&raw);
  assert_eq!(stored, raw);
  assert_eq!(round_trip(raw), Ok(raw));
  assert_eq!(
    stored.as_bytes().len(),
    16,
    "the stored form is the bytes and not the 36-character text",
  );
}

/// **THE WIDE INTEGERS THAT MOVED, DIALECT-BLIND** — the 2026-08-30 ruling: `i128` and `u128` are
/// stored through their existing big-endian blob carriers, exactly as
/// [`the_uuid_road_is_the_value_itself`] pins for the first member that moved — no rendering between
/// the value and the column. `u64`'s own round trip is
/// [`the_big_endian_blob_road_round_trips_u64_on_sqlite`] and
/// [`the_big_endian_blob_road_round_trips_u64_on_postgres`] below, and not here, for `Blind`'s own
/// reason: the same ruling's MySQL fast-follow took `u64` off the blind road, so `Db = ()` no longer
/// resolves for it.
#[test]
fn the_big_endian_blob_road_round_trips_the_wide_integers() {
  assert_eq!(round_trip(i128::MIN), Ok(i128::MIN));
  assert_eq!(round_trip(u128::MAX), Ok(u128::MAX));

  assert_eq!(<i128 as IdColumn<Blind>>::to_stored(&-1), crate::BeI128(-1),);
  assert_eq!(<u128 as IdColumn<Blind>>::to_stored(&1), crate::BeU128(1));
}

/// **`u64`'s OWN ROUND TRIP ON SQLITE** — the big-endian blob, at the CONCRETE dialect it now
/// resolves at instead of at `Blind`. PostgreSQL is
/// [`the_big_endian_blob_road_round_trips_u64_on_postgres`] beside this one, and MySQL is
/// [`u64_stores_natively_on_mysql`] below, on the native road rather than this one.
#[cfg(feature = "sqlite")]
#[test]
fn the_big_endian_blob_road_round_trips_u64_on_sqlite() {
  assert_eq!(
    <u64 as IdColumn<sqlx::Sqlite>>::from_stored(<u64 as IdColumn<sqlx::Sqlite>>::to_stored(&9)),
    Ok(9),
  );
  assert_eq!(
    <u64 as IdColumn<sqlx::Sqlite>>::from_stored(<u64 as IdColumn<sqlx::Sqlite>>::to_stored(
      &u64::MAX
    )),
    Ok(u64::MAX),
  );

  let stored: crate::BeU64 = <u64 as IdColumn<sqlx::Sqlite>>::to_stored(&9);
  assert_eq!(stored, crate::BeU64(9));
  assert_eq!(
    stored.to_blob().len(),
    8,
    "the stored form is eight bytes and not a decimal rendering",
  );
}

/// The same round trip, on PostgreSQL's `BYTEA` — [`the_big_endian_blob_road_round_trips_u64_on_sqlite`]'s
/// own reason, one dialect over.
#[cfg(feature = "postgres")]
#[test]
fn the_big_endian_blob_road_round_trips_u64_on_postgres() {
  assert_eq!(
    <u64 as IdColumn<sqlx::Postgres>>::from_stored(<u64 as IdColumn<sqlx::Postgres>>::to_stored(
      &9
    )),
    Ok(9),
  );
  assert_eq!(
    <u64 as IdColumn<sqlx::Postgres>>::from_stored(<u64 as IdColumn<sqlx::Postgres>>::to_stored(
      &u64::MAX
    )),
    Ok(u64::MAX),
  );
}

/// **`u64` STORES NATIVELY ON MYSQL** — `type Stored = Self`, so the round trip is the identity and
/// the assertion is that no encoding step was inserted where none belongs: [`own_column!`]'s own
/// shape, taken by name rather than by the macro since the impl is for `sqlx::MySql` alone.
#[cfg(feature = "mysql")]
#[test]
fn u64_stores_natively_on_mysql() {
  let stored: u64 = <u64 as IdColumn<sqlx::MySql>>::to_stored(&9);
  assert_eq!(
    stored, 9,
    "the stored form IS the value — no blob, no rendering"
  );
  assert_eq!(<u64 as IdColumn<sqlx::MySql>>::from_stored(stored), Ok(9));
}

/// **THE ORDER THE MOVE RESTORES** — stored bytes now agree with the integer's own `Ord`, where the
/// abandoned text road's decimal rendering did not: `"10"` precedes `"9"` lexicographically, and
/// `10 > 9` numerically. SQLite's blob road, read at the CONCRETE dialect `u64`'s own row now needs.
#[cfg(feature = "sqlite")]
#[test]
fn the_stored_bytes_now_agree_with_the_integers_own_ord() {
  // `9 < 10` is the premise the assertion below is drawn against, and it is ARITHMETIC rather than a
  // claim about this crate — asserted, it was a constant the compiler folds and clippy removes. It
  // is stated here because the test's whole subject is which of the two orders the bytes take.
  let (nine, ten): (crate::BeU64, crate::BeU64) = (
    <u64 as IdColumn<sqlx::Sqlite>>::to_stored(&9),
    <u64 as IdColumn<sqlx::Sqlite>>::to_stored(&10),
  );
  assert!(
    nine.to_blob() < ten.to_blob(),
    "the stored bytes compare the same way the values do",
  );
  // The OTHER order, said at `str` — borrowed rather than owned, which is the same comparison
  // without the two allocations clippy names.
  assert!(
    "9" > "10",
    "which the abandoned text road would have gotten backwards",
  );
}

/// **THE MYSQL-LANE NUMERIC-ORDER PROOF** — `id_column_coverage`'s own SQLite proof
/// (`a_u64_inner_id_orders_numerically_not_lexicographically`), one dialect over. This crate
/// provisions no MySQL server for any suite to connect to — `ddl::index_tests`'s own posture, ridden
/// by every MySQL fixture here — so what is measured is what is actually true of the RENDERED form
/// rather than a connection: the stored form for a `u64`-inner id on MySQL is `u64` ITSELF, so its
/// order is `u64::Ord` with no encoding step of its own to disagree with it, unlike the blob road's
/// bytes, which [`the_stored_bytes_now_agree_with_the_integers_own_ord`] exists to prove agree.
#[cfg(feature = "mysql")]
#[test]
fn a_u64_inner_id_on_mysql_orders_numerically_not_lexicographically() {
  // SCRAMBLED, the SAME values and the SAME reason `id_column_coverage`'s SQLite proof states: "10"
  // and "100" both precede "9" lexicographically, where 9 < 10 < 100 numerically.
  let scrambled = [10u64, 100, 2, 9, 1];

  let mut stored: Vec<u64> = scrambled
    .iter()
    .map(<u64 as IdColumn<sqlx::MySql>>::to_stored)
    .collect();
  stored.sort_unstable();
  assert_eq!(
    stored,
    [1, 2, 9, 10, 100],
    "BIGINT UNSIGNED sorts numerically because the stored form IS the value — nothing here \
     re-encodes it, so there is no byte order to disagree with `u64::Ord`",
  );

  let mut decimal: Vec<String> = scrambled.iter().map(ToString::to_string).collect();
  decimal.sort_unstable();
  assert_ne!(
    decimal,
    ["1", "2", "9", "10", "100"],
    "the abandoned text road would have sorted these lexicographically instead",
  );
}

/// The two text members that ARE a column keep their own type across the crossing, which is what
/// lets `Utf8Bytes` — which has no `FromStr` at all — have a road.
#[test]
fn the_text_members_that_are_columns_are_stored_as_themselves() {
  assert_eq!(round_trip("abc".to_owned()), Ok("abc".to_owned()));
  let carried = smol_bytes::Utf8Bytes::from("abc");
  assert_eq!(round_trip(carried.clone()), Ok(carried));
}

/// **THE SWITCH, READ AT THE COLUMN** — the two roads declare different things, and the uuid's is the
/// native one. This is the assertion that reports it the day either road moves.
#[cfg(feature = "sqlite")]
#[test]
fn the_two_roads_declare_different_columns() {
  use crate::StoredAs;

  assert_eq!(
    <<uuid::Uuid as IdColumn<sqlx::Sqlite>>::Stored as StoredAs<sqlx::Sqlite>>::WORDS,
    ["BLOB"],
    "a uuid-inner id is declared at the native sixteen bytes",
  );
  assert_eq!(
    <<i64 as IdColumn<sqlx::Sqlite>>::Stored as StoredAs<sqlx::Sqlite>>::WORDS,
    ["TEXT"],
    "and every text-road member at the column its rendering goes into",
  );
  assert_eq!(
    <<String as IdColumn<sqlx::Sqlite>>::Stored as StoredAs<sqlx::Sqlite>>::WORDS,
    ["TEXT"],
  );
  // The 2026-08-30 ruling's own three: the wide integers now declare the same word the uuid does —
  // a THIRD road exists, and it is not a fourth one, because it is uuid's own carrier reused.
  assert_eq!(
    <<u64 as IdColumn<sqlx::Sqlite>>::Stored as StoredAs<sqlx::Sqlite>>::WORDS,
    ["BLOB"],
    "a u64-inner id is declared at its eight big-endian bytes",
  );
  assert_eq!(
    <<i128 as IdColumn<sqlx::Sqlite>>::Stored as StoredAs<sqlx::Sqlite>>::WORDS,
    ["BLOB"],
  );
  assert_eq!(
    <<u128 as IdColumn<sqlx::Sqlite>>::Stored as StoredAs<sqlx::Sqlite>>::WORDS,
    ["BLOB"],
  );
}

/// The same reading in the two dialects with a WORD of their own for the value, so the native road is
/// pinned as native everywhere rather than on SQLite alone.
#[cfg(feature = "postgres")]
#[test]
fn the_native_road_takes_postgres_own_type() {
  use crate::StoredAs;

  assert_eq!(
    <<uuid::Uuid as IdColumn<sqlx::Postgres>>::Stored as StoredAs<sqlx::Postgres>>::WORDS,
    ["uuid"],
  );
  assert_eq!(
    <<i64 as IdColumn<sqlx::Postgres>>::Stored as StoredAs<sqlx::Postgres>>::WORDS,
    ["text"],
  );
  // Postgres has no unsigned or 128-bit column at all, which is the ORIGINAL reason the blob
  // carriers exist — so all three of the 2026-08-30 ruling's members declare `bytea` here, uniform
  // with SQLite's `BLOB`.
  assert_eq!(
    <<u64 as IdColumn<sqlx::Postgres>>::Stored as StoredAs<sqlx::Postgres>>::WORDS,
    ["bytea"],
  );
  assert_eq!(
    <<i128 as IdColumn<sqlx::Postgres>>::Stored as StoredAs<sqlx::Postgres>>::WORDS,
    ["bytea"],
  );
  assert_eq!(
    <<u128 as IdColumn<sqlx::Postgres>>::Stored as StoredAs<sqlx::Postgres>>::WORDS,
    ["bytea"],
  );
}

#[cfg(feature = "mysql")]
#[test]
fn the_native_road_takes_mysqls_fixed_width_binary() {
  use crate::StoredAs;

  assert_eq!(
    <<uuid::Uuid as IdColumn<sqlx::MySql>>::Stored as StoredAs<sqlx::MySql>>::WORDS,
    ["binary(16)"],
  );
  assert_eq!(
    <<i64 as IdColumn<sqlx::MySql>>::Stored as StoredAs<sqlx::MySql>>::WORDS,
    ["varchar(255)"],
  );
}

/// **THE MEASURED ASYMMETRY THE 2026-08-30 RULING NAMED, AND THE SAME-DAY ROW THAT CLOSES IT**:
/// `i128`/`u128` declare MySQL's `blob`, uniform with the other two dialects — neither has ever had
/// a native MySQL column either. `u64` does NOT join them: it declares `bigint unsigned`, the SAME
/// word `column::stored`'s own MySQL table already gave the bare value-column type, read through the
/// `impl IdColumn<sqlx::MySql> for u64` beside [`be_road!`]'s invocation rather than through
/// [`crate::BeU64`], which still carries no `StoredAs<sqlx::MySql>` row and now never needs one.
#[cfg(feature = "mysql")]
#[test]
fn the_128_bit_movers_declare_mysqls_blob_where_u64_declares_its_own_native_word() {
  use crate::StoredAs;

  assert_eq!(
    <<i128 as IdColumn<sqlx::MySql>>::Stored as StoredAs<sqlx::MySql>>::WORDS,
    ["blob"],
  );
  assert_eq!(
    <<u128 as IdColumn<sqlx::MySql>>::Stored as StoredAs<sqlx::MySql>>::WORDS,
    ["blob"],
  );
  assert_eq!(
    <<u64 as IdColumn<sqlx::MySql>>::Stored as StoredAs<sqlx::MySql>>::WORDS,
    ["bigint unsigned"],
    "a u64-inner id is declared at MySQL's own native column, not a blob",
  );
}

/// The text member under its own feature, whose parse cannot fail — every string is one.
#[cfg(feature = "smol_str")]
#[test]
fn the_compact_text_member_round_trips() {
  let value = smol_str::SmolStr::new("a-b-c");
  assert_eq!(round_trip(value.clone()), Ok(value));
}

/// The BSON pair, on the text road the module note censuses per dialect — the canonical hyphenated
/// uuid and the 24-character lowercase hex of an `ObjectId`.
#[cfg(feature = "mongo")]
#[test]
fn the_bson_pair_round_trips_through_its_canonical_text() {
  let uuid = bson::Uuid::from_bytes([7; 16]);
  assert_eq!(
    <bson::Uuid as IdColumn<Blind>>::to_stored(&uuid),
    uuid.to_string(),
  );
  assert!(round_trip(uuid).is_ok());

  let oid = bson::oid::ObjectId::from_bytes([3; 12]);
  assert_eq!(
    <bson::oid::ObjectId as IdColumn<Blind>>::to_stored(&oid),
    "030303030303030303030303",
  );
  assert!(round_trip(oid).is_ok());
}