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 ruling's five clauses for a detection: the carrier, top-k, the filter's shape, the columns,
//! and the interop that is deliberately not here.

use crate::{
  ColumnKind, ColumnShape, ConfidenceFilter, ConfidenceOperand, ScalarFilter, Score, width,
};

use super::{DetectedLanguage, DetectedLanguageFilter};
use crate::primitives::lang::{Language, LanguageId, LanguageIdFilter, ScriptSubtag};

/// One tag the door must take, unwrapped.
fn tag(sent: &str) -> LanguageId {
  LanguageId::new(sent).unwrap_or_else(|refused| panic!("`{sent}` is a language tag: {refused}"))
}

/// One confidence, unwrapped.
fn sure(value: f32) -> Score {
  Score::new(value).expect("a confidence in the unit interval")
}

/// A filter's THRESHOLD — widthless, and read at the column's own carrier by the crossing.
fn threshold(value: f64) -> ConfidenceOperand {
  ConfidenceOperand::number(value).expect("a threshold in [0, 1]")
}

/// One detection.
fn detected(sent: &str, confidence: f32) -> DetectedLanguage {
  DetectedLanguage::new(tag(sent), sure(confidence))
}

/// **THE CARRIER IS A WHOLE IDENTITY** — the ruling's first clause, and the one that decides how
/// long this type lasts.
///
/// A detector that emits a bare two-letter code lands a `LanguageId` with three empty seats. One
/// that names a script lands the same type with one more seat filled, and nothing about the value,
/// the columns or the wire changes shape between the two.
#[test]
fn a_bare_code_and_a_scripted_one_are_the_same_carrier() {
  let whisper = detected("zh", 0.94);
  assert_eq!(whisper.language().language().as_str(), "zh");
  assert_eq!(whisper.language().script(), None);

  let finer = detected("zh-Hans", 0.94);
  assert_eq!(
    finer.language().script().map(ScriptSubtag::as_str),
    Some("Hans")
  );

  // Two identities and therefore two detections — which is the losslessness the carrier buys: a
  // bare `zh` is not a `zh-Hans` with a note attached.
  assert_ne!(whisper, finer);
  assert_eq!(whisper.confidence(), finer.confidence());
}

/// **EQUALITY IS THE PAIR**, so the same language at two confidences is two detections.
#[test]
fn the_confidence_is_part_of_the_identity() {
  assert_ne!(detected("de", 0.9), detected("de", 0.2));
  assert_eq!(detected("de", 0.9), detected("de", 0.9));

  // …and the fold reaches the language half, so an mkv's spelling and an mp4's are one detection.
  assert_eq!(detected("ger", 0.9), detected("deu", 0.9));

  let mut distinct = std::collections::HashSet::new();
  distinct.insert(detected("ger", 0.9));
  distinct.insert(detected("deu", 0.9));
  distinct.insert(detected("de", 0.2));
  assert_eq!(distinct.len(), 2);
}

/// **FIVE COLUMNS: the identity's four FLATTENED, then the confidence.**
///
/// Flattened rather than nested, which is one path segment per column: a detection at `detected`
/// reaches `detected_language` and not `detected_language_language`.
#[test]
fn a_detection_spans_the_identitys_four_columns_and_one_more() {
  let segments = <DetectedLanguage as ColumnKind>::SEGMENTS;

  assert_eq!(segments.len(), 2, "one composite and one plain");
  assert_eq!(width(segments), 5, "and five columns between them");

  let ColumnShape::Composite {
    field,
    segments: inner,
  } = segments[0]
  else {
    panic!("the identity is a composite");
  };
  assert_eq!(field, None, "FLATTENED — it lends no segment of its own");
  assert_eq!(inner, <LanguageId as ColumnKind>::SEGMENTS);

  let ColumnShape::Plain(confidence) = segments[1] else {
    panic!("the confidence is one plain column");
  };
  assert_eq!(confidence.stored().as_str(), "confidence");
}

/// **THE DOCUMENT IS FIVE KEYS AT ONE LEVEL** — the identity's four, then the confidence, which is
/// the SEGMENTS above read in the other family's spelling.
///
/// The claim that would be silent if it broke is the NESTING. `LanguageId`'s own row writes a
/// sub-document, so a detection that nested its identity would carry
/// `{language: {language: "zh", …}, confidence: …}` — well-formed BSON, addressed as
/// `heard.language.language`, and a doubled word nothing in the SQL family has. What decides against
/// it is the identity's entry lending NO NAME: there is no key to nest under, so its four join this
/// document's own.
#[cfg(feature = "mongo")]
#[test]
fn a_detection_carries_as_the_identitys_keys_and_one_more() {
  use crate::MongoCarrier;
  use bson::Bson;

  let Bson::Document(carried) = detected("zh-Hans", 0.94).to_bson() else {
    panic!("a detection carries as a document");
  };

  let keys: Vec<&str> = carried.keys().map(String::as_str).collect();
  assert_eq!(
    keys,
    ["language", "script", "region", "rest", "confidence"],
    "the identity's four keys at THIS level, then the confidence",
  );
  assert_eq!(carried.get("language"), Some(&Bson::from("zh")));
  assert_eq!(carried.get("script"), Some(&Bson::from("Hans")));
  assert_eq!(
    carried.get("confidence"),
    Some(&Bson::Double(f64::from(0.94_f32))),
    "the width's own row — BSON's only binary float, which an `f32` widens into exactly",
  );

  // The identity's OWN document is the first four keys and nothing else — one shape, written by one
  // row, whether it is a field of its own or a detection's half.
  let Bson::Document(alone) = tag("zh-Hans").to_bson() else {
    panic!("an identity carries as a sub-document");
  };
  for seat in alone.keys() {
    assert_eq!(
      carried.get(seat),
      alone.get(seat),
      "`{seat}` says the same thing in both",
    );
  }
  assert_eq!(
    carried.len(),
    alone.len() + 1,
    "and the detection adds exactly one key to it",
  );
}

/// **THE READ IS THE WRITE'S MIRROR** — a detection written as five keys at one level reads back as
/// the pair that wrote it: the identity's four through [`LanguageId`]'s own door, then the
/// confidence through [`Score`]'s.
#[cfg(feature = "mongo")]
#[test]
fn a_detection_reads_back_the_document_it_carried_as() {
  use crate::{MongoCarrier, query::mongo::MongoExtract};

  for (sent, confidence) in [
    ("zh", 0.94),
    ("zh-Hans", 0.94),
    ("de-DE", 0.5),
    ("und", 0.0),
  ] {
    let value = detected(sent, confidence);
    let written = value.to_bson();
    assert_eq!(
      DetectedLanguage::extract(Some(&written)),
      Ok(value),
      "`{sent}`"
    );
  }
}

/// **THE WHOLE FIELD'S ABSENCE AND WRONG TYPE ARE REFUSED BY NAME**, exactly as a bare `LanguageId`
/// field's are — the outer check is not this composite's own invention, it is
/// `document_seats`'s caller doing what every other row in this vocabulary does first.
#[cfg(feature = "mongo")]
#[test]
fn a_detection_read_refuses_absence_and_the_wrong_type() {
  use crate::query::mongo::{MongoExtract, MongoTypeError};
  use bson::Bson;

  assert_eq!(DetectedLanguage::extract(None), Err(MongoTypeError::Absent));
  assert_eq!(
    DetectedLanguage::extract(Some(&Bson::Int32(1))),
    Err(MongoTypeError::wrong_type("object", "int"))
  );
}

/// **THE CONFIDENCE KEY READS THROUGH [`Score`]'S OWN ROW, UNCHANGED** — an out-of-domain double at
/// the `confidence` key is refused the way any bare `Score` column's is, nothing about the
/// refusal being reinvented for this composite.
#[cfg(feature = "mongo")]
#[test]
fn an_out_of_domain_confidence_is_refused_by_scores_own_rule() {
  use crate::query::mongo::{MongoExtract, MongoTypeError};
  use bson::doc;

  let document = doc! {
    "language": "zh", "script": bson::Bson::Null, "region": bson::Bson::Null,
    "rest": bson::Bson::Null, "confidence": 2.0
  };

  assert!(matches!(
    DetectedLanguage::extract(Some(&document.into())),
    Err(MongoTypeError::Range(_))
  ));
}

/// **THE FILTER FLATTENS THE IDENTITY AND NESTS THE CONFIDENCE** — the ruling's third clause, read
/// in Rust. The wire half of the same claim is in `tests/detected_language_citizen.rs`.
#[test]
fn the_filter_holds_a_whole_identity_filter_and_a_score_filter() {
  let empty = DetectedLanguageFilter::new();
  assert!(empty.is_empty());
  assert!(empty.language().is_empty());
  assert_eq!(empty.confidence(), None);

  // The identity component is the WHOLE `LanguageIdFilter`, so every slot it has is reachable —
  // nothing is restated here and nothing can drift.
  let chinese = DetectedLanguageFilter::new().with_language(
    LanguageIdFilter::new()
      .with_language(ScalarFilter::new().with_eq(Language::new("zh").expect("a language"))),
  );
  assert!(!chinese.is_empty());
  assert!(!chinese.language().is_empty());

  let confident =
    DetectedLanguageFilter::new().with_confidence(ConfidenceFilter::new().with_gte(threshold(0.8)));
  assert!(!confident.is_empty());
  assert_eq!(
    confident.confidence().and_then(ConfidenceFilter::gte),
    Some(&threshold(0.8))
  );

  // A component filter that is present and EMPTY asks nothing, which is the emptiness law every
  // nested slot answers by.
  let hollow = DetectedLanguageFilter::new()
    .with_language(LanguageIdFilter::new())
    .with_confidence(ConfidenceFilter::new());
  assert!(hollow.is_empty());
}

/// **TOP-K IS THE FIELD'S SHAPE**, which is what the collection marker says and what this type does
/// not.
///
/// Nothing here knows whether a detection is the best candidate, and that is the point: a ranked
/// list is a `Vec` at the declaration, `count` asks how many there were, and `any` asks about each.
#[test]
fn a_detection_knows_nothing_about_its_rank() {
  let candidates = [
    detected("zh", 0.94),
    detected("ja", 0.04),
    detected("ko", 0.02),
  ];

  // The ORDER is the caller's — this type has no rank field and no rank method, so a `Vec` is the
  // only thing that carries one.
  assert_eq!(candidates[0].confidence(), sure(0.94));
  assert!(
    candidates
      .windows(2)
      .all(|pair| pair[0].confidence() >= pair[1].confidence())
  );

  // …and the element's own ordering is the SEATS then the confidence, which is a cursor key rather
  // than a ranking: sorting the candidates by it does not put the best first.
  let mut sorted = candidates.clone();
  sorted.sort();
  assert_eq!(sorted[0].language().language().as_str(), "ja");
}

/// The two renderings, and which of them is an inverse of a parse.
///
/// [`Display`](core::fmt::Display) is a rendering and NOT a round trip — the pair has no spelling
/// any standard defines — where the identity's own `Display` is the inverse of its parse.
#[test]
fn the_rendering_is_a_rendering_and_not_a_round_trip() {
  let detection = detected("zh-Hans", 0.94);

  assert_eq!(detection.to_string(), "zh-Hans (0.94)");
  assert_eq!(detection.language().to_string(), "zh-Hans");
  assert_eq!(
    LanguageId::new(&detection.language().to_string()).expect("canonical"),
    *detection.language()
  );

  assert_eq!(
    format!("{detection:?}"),
    r#"DetectedLanguage { language: "zh-Hans", confidence: 0.94 }"#
  );
}

/// **THE INTEROP IS NOT HERE, and that is the ruling's fifth clause rather than an omission.**
///
/// A conversion from a detector's own result type belongs on the SERVICE side, so the dependency
/// points from the service to the graph and this crate never grows one on a model wrapper. What
/// this type owes that conversion is a total constructor with no hidden invariant, which
/// [`DetectedLanguage::new`] is: both halves are already validated, so there is nothing for a
/// `From` on the other side to fail at.
#[test]
fn the_constructor_is_total_so_an_upstream_conversion_cannot_fail() {
  let language = tag("zh");
  let confidence = sure(0.94);

  let detection = DetectedLanguage::new(language.clone(), confidence);

  assert_eq!(detection.language(), &language);
  assert_eq!(detection.confidence(), confidence);
}