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
//! ANNOTATION — the stage BEFORE the widening, and the one seat a question opens to it.
//!
//! ```text
//! question ──▶ ⟂ annotate ──▶ the SAME question, enriched ──▶ ② expand ──▶ ④ route ──▶ the tail
//!                  │                                              │            │
//!                  └── writes the annotation ─────────────────────┴── read here ┘
//! ```
//!
//! [`expand`](super::expand) widens a question into several and [`LaneFan`](crate::LaneFan) crosses
//! one into probes. This module is what happens BEFORE either: a question may be ANNOTATED — asked at a
//! detector, a classifier or a resident holding a model, and handed back **as itself**, carrying one
//! more fact than it arrived with.
//!
//! # THE STAGE ANNOTATES; IT DOES NOT TRANSFORM
//!
//! Every other step of a tower turns one type into the next, and the chain is what those hops
//! derive. An annotation stage's ends are THE SAME TYPE, and that is not a special case of the chain
//! — it is the whole reason the stage exists. The stages after it READ what it wrote: a widening
//! picks the targets to widen INTO, a crossing picks the lanes to ask, and neither can read a datum
//! that arrives as its own step's ANSWER, because a step's answer goes downstream and never up. A
//! stage that annotates in place is the one shape that reaches both.
//!
//! # FILL-IF-ABSENT, and the operator is NOT CONSULTED for a value the caller supplied
//!
//! A question may arrive with the annotation already aboard — a client that knows its own language
//! says so, and a request is supreme over anything a deployment would have detected. So the walk
//! ASKS THE QUESTION FIRST, through [`AnnotatedQuestion::carried`], and calls the stage's operator
//! only where the answer is [`None`].
//!
//! **Not consulted, rather than consulted and discarded.** The two readings differ by exactly one
//! thing and it is the expensive one: what a resident-mounted stage holds is
//! *query-time compute over an exclusive model* — a detector, a tokenizer, a device context — and
//! spending a forward pass on a value that will be thrown away is a cost the framework would be
//! choosing on an application's behalf. The cheaper reading is also the honest one: *fill if absent*
//! says the stage fills a gap, and there is no gap.
//!
//! # THE ANNOTATION'S TYPE IS THE DECLARATION'S, and this module names none
//!
//! [`AnnotatedQuestion`] is generic over what is carried, so a language tag, a detected script, a
//! classified intent and a tenant identifier are one mechanism. **No language vocabulary enters
//! here**: what a lane is keyed on is [`LanguageTag`](crate::LanguageTag)'s and
//! [`lane_for`](crate::lane_for)'s business one module over, and what a QUESTION carries is the
//! declaring crate's own type — a tower's question is the application's, which is the ruling this
//! framework has kept at every position where a question's shape came up.

/// **A QUESTION THAT CARRIES AN ANNOTATION** — the ⟂ stage's one seat, written at the stage and
/// READ everywhere after it.
///
/// ```
/// use ingraph::AnnotatedQuestion;
///
/// pub struct Ask {
///   text: String,
///   lang: Option<String>,
/// }
///
/// impl AnnotatedQuestion<String> for Ask {
///   fn carried(&self) -> Option<&String> {
///     self.lang.as_ref()
///   }
/// }
///
/// let told = Ask { text: "sunset".to_owned(), lang: Some("ja".to_owned()) };
/// let silent = Ask { text: "sunset".to_owned(), lang: None };
///
/// // What the walk asks before it spends the stage's operator.
/// assert!(told.carried().is_some());
/// assert!(silent.carried().is_none());
/// ```
///
/// # ONE METHOD, because the framework only ever READS
///
/// What WRITES the annotation is the stage's own operator — a [`Serves`](crate::Serves) or
/// [`AsyncServes`](crate::AsyncServes) whose question and answer are both this type — so there is no
/// setter here and there is nothing for one to be. That division is what keeps *perfect adaptation
/// belongs to the arm author* true at this position too: how a question folds a detected tag into
/// itself, which of several seats it fills, and what it recomputes when it does are the question
/// author's, and a framework setter would be the framework guessing all three.
///
/// # A QUESTION MAY CARRY SEVERAL, and that is why the parameter is on the TRAIT
///
/// `impl AnnotatedQuestion<LanguageTag> for Ask` and `impl AnnotatedQuestion<Intent> for Ask` stand
/// side by side, each read by the stage that names its type. An associated type would have closed
/// that to one annotation per question and closed it in the direction this framework never closes:
/// what a product enriches a question with is the product's, and a seat with room for one is a
/// vocabulary with room for whatever the framework happened to imagine.
///
/// # It asks NOTHING of the annotation
///
/// No [`Eq`], no [`Clone`], no [`Debug`]. The framework's whole spend is *is it there* — the
/// borrowed value is for the stages downstream, and what THEY need of it is theirs to demand.
#[diagnostic::on_unimplemented(
  message = "`{Self}` carries no `{A}` for an annotation stage to fill",
  label = "no `AnnotatedQuestion<{A}>`",
  note = "A ⟂ step annotates the question IN PLACE, so the type it is asked has to have a seat for \
          what the stage writes and a way to say whether the caller already filled it. Write \
          `impl AnnotatedQuestion<{A}> for {Self} {{ fn carried(&self) -> Option<&{A}> {{ … }} }}` \
          — or take the `annotate` word off the step, which makes it the ordinary hop its ends \
          already describe."
)]
pub trait AnnotatedQuestion<A> {
  /// What this question ALREADY carries — [`None`] where the caller supplied nothing.
  ///
  /// The whole of FILL-IF-ABSENT is this answer: [`Some`] and the stage's operator is not called at
  /// all, [`None`] and it is. It is also the READ every stage after ⟂ makes — a router choosing
  /// lanes and an expander choosing targets both reach the annotation here, and neither has to know
  /// which step wrote it.
  fn carried(&self) -> Option<&A>;
}

#[cfg(test)]
mod tests;