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 per-member score floors a fused query carries: [`FloorSpec`] and the precedence it resolves
//! by.
//!
//! # The CEILING half of this module is GONE, and the wall law is why
//!
//! `CeilingSpec` stood beside [`FloorSpec`] — per-flavour intake defaults, per-member overrides, and
//! a shipped `CEILING` constant the chain terminated in. Both are deleted, condemned twice over by
//! the protection law: a query-carried ceiling vocabulary is a PROTECTIVE number crossing the wire,
//! which that law outlaws by name, and a framework-chosen fallback bound contradicts *no declared
//! ceiling = the author's informed openness*. Neither was ever referenced outside this file — a
//! published law no door ran.
//!
//! Ceiling has ONE home now: the declaration, capping through
//! [`route_depth`](super::route_depth)'s `min`. A floor is a different family and keeps everything
//! it had — it is a PREFERENCE, it crosses the wire, and a declaration must state one.
//!
//! # The ARM CLASS arrived with the fan, and it is the second axis this module carries
//!
//! A widened question is asked in several arms and an arm a translator minted scores elsewhere than
//! the caller's own words do, so one number cannot floor both. The answer is an OFFSET rather than a
//! second precedence chain: whichever tier won the base, a minted arm runs at `base + offset`. See
//! [`FloorSpec`]'s own note for why the class is binary and why the offset composes with the tiers
//! instead of competing with them.

/// The per-member score floors a fused query carries, above what each declaration already states.
///
/// # Why there is no blanket field
///
/// A floor is a number in ONE ENGINE'S OWN CURRENCY. A BM25 relevance is corpus-relative and
/// unbounded above where a cosine similarity is absolute in `[-1, 1]`, so a single number applied
/// across both flavours means two unrelated things and is a strictly incoherent knob — it is refused
/// by construction rather than documented against. The FLAVOUR is the coarsest layer over which one
/// number is still coherent, which is why the defaults here are per-flavour and stop there.
///
/// The two parameters are what that coherence looks like in Rust: `F` is the full-text members'
/// score currency and `V` is the vector members' — the same axis the wire spells as two `Float`
/// fields, typed. A catalog whose two full-text members score in different types has no full-text
/// flavour default available to it, and the emitted builder is where that is a compile-time fact.
///
/// # The named per-member OVERRIDES are not here, and the reason is the member table
///
/// The ruled shape is `{ fulltext?, vector?, overrides }`, and the override list is keyed by the
/// COMPILE-TIME MEMBER TABLE — *typos don't compile*. That table is minted per graph root by the
/// emission, so a framework type cannot hold a map keyed by it. What lives here is therefore the
/// flavour layer, and the override is an ARGUMENT to the resolvers below, supplied by the emitted
/// builder that does know the members' names. The precedence is unchanged by the split; only who
/// holds which tier is.
///
/// # ⟨WATCH⟩ THE EMITTED BUILDER ABOVE DOES NOT EXIST YET, and the 2026-08-27 census says why
///
/// This type is constructed nowhere outside its own tests, and the round that went looking for the
/// seam to construct it at found none. Three findings, each of which would have to fall before the
/// `over:` argument has a supplier:
///
/// 1. **The recipe grain records a floor as a FACT and not as a value.** `floor = "…"` is parsed off
///    a member and off an arm, and what crosses the expansion wall is
///    [`Member::is_floored`](crate::Member::is_floored) — *a floor const was named*. The PATH is
///    dropped, so there is no tier-one number for a chain to terminate in.
/// 2. **A fanned tower's tail has no floor seam.** The tail answers a
///    [`RankedStream`](super::RankedStream), which is a stream somebody has already floored, dedup'd
///    and ranked; the shipped serving lane one layer below answers raw `Hits`, and neither the
///    full-text ask nor the vector ask it is asked with carries a floor. The number is spent inside a
///    step whose own `Serve::Options` the framework cannot read.
/// 3. **The CURRENCY is not projectable where the wire face is minted.** `F` and `V` are somebody's
///    score types, and the seams a recipe reaches a member through publish no score:
///    [`Fusable`](super::Fusable) carries `Options` and `Question`,
///    [`AsyncFusedRead`](super::AsyncFusedRead) carries `Root`, `Evidence`, `Error` and `Ctx`. A
///    member's score currency lives inside the package the recipe holds BY PROJECTION and cannot read
///    a row out of — which is the same wall the per-member override list is on the far side of.
///
/// The offset axis below inherits all three: it is a number in the same currency, spent at the same
/// absent seam. Nothing here is deferred by taste, and nothing here forecloses the door.
///
/// # The precedence, and the tier that cannot be missing
///
/// **override > flavour default > the declaration's own.** The declaration's is not an [`Option`]
/// because an index without a declared floor cannot join a graph-root face at all — the
/// mandatory-floor law continued into the fused world — so the chain always terminates.
///
/// # THE ARM CLASS IS A SECOND AXIS, and it is an OFFSET rather than a fourth tier
///
/// A widened question is asked in several arms, and an arm a translator minted does not score where
/// the caller's own words do: the same corpus answers a rendering of the question at a systematically
/// different place in the engine's currency. A floor calibrated on what was actually asked therefore
/// mis-cuts every other arm, in a direction that depends on the arm and not on the member.
///
/// So the arm class does not JOIN the precedence chain — it moves the number the chain arrived at, by
/// [`translated_fulltext_offset`](Self::translated_fulltext_offset) and its vector twin. That is
/// what makes it composable with all three tiers rather than a competitor to them: whichever tier won
/// the base, a minted arm runs at `base + offset` and the caller's own arm runs at `base`. The
/// resolvers that spend it are [`resolve_fulltext_at`](Self::resolve_fulltext_at) and
/// [`resolve_vector_at`](Self::resolve_vector_at); the two older resolvers are the same functions at
/// the original arm and are unchanged.
///
/// **The class is BINARY, and that is [`ArmWeights`](crate::ArmWeights)' own answer rather than a
/// simplification.** The framework knows *the caller asked this* and *something minted this*, which is
/// all [`ExpandOrigin`](crate::ExpandOrigin) distinguishes. A per-LABEL table — *this translator's
/// arms floor higher than that synonym table's* — would be a policy in the framework about expanders
/// the framework has never seen, refused here for the reason it is refused at the weight.
///
/// # THE CLASSIFICATION: every number on this type is a PREFERENCE
///
/// A floor is named in the one-sentence law at [`route_depth`](super::route_depth) as a preference —
/// *a requester's own statement about the answer it wants* — so it rides all three tiers and the
/// outermost one wins outright. [`over`](Self::over) is that composition. The offset is a preference
/// for the same reason and by the same reading: it moves where an answer is cut, and cutting more or
/// less of one's own answer costs the deployment nothing.
///
/// # THERE IS NO `DEFAULT_*` CONSTANT HERE, and the absence is the open currency
///
/// The three-tier law's first tier is a shipped constant, and this type cannot hold one: `F` and `V`
/// are somebody else's score currencies, and a framework constant in a type it has never seen is
/// unwritable. Tier one is therefore the DECLARATION's own const — `floor = "crate::floors::SEM"`,
/// the path the recipe grammar takes — which is exactly the `declared` argument the resolvers
/// terminate in. The offset's tier one is *no offset*: absence, and not a zero, because the additive
/// identity of an open currency is as unwritable as its floor.
///
/// The derive list is [`FulltextQuery`](crate::FulltextQuery)'s, for its reason: a floor's currency
/// is an engine's own type, `f32` is the one every shipped engine uses, and `Eq` and `Hash` are
/// exactly the two an `f32` cannot supply — so deriving them would add impls no real instantiation
/// can reach.
#[derive(Debug, Clone, PartialEq)]
pub struct FloorSpec<F, V> {
  fulltext: Option<F>,
  vector: Option<V>,
  translated_fulltext: Option<F>,
  translated_vector: Option<V>,
}

impl<F, V> FloorSpec<F, V> {
  /// Name no flavour default — every member takes its own declared floor unless it is overridden.
  #[inline]
  #[must_use]
  pub const fn new() -> Self {
    Self {
      fulltext: None,
      vector: None,
      translated_fulltext: None,
      translated_vector: None,
    }
  }

  /// Set the default floor for every FULL-TEXT member, in the full-text flavour's currency.
  #[inline]
  #[must_use]
  pub fn with_fulltext(mut self, floor: F) -> Self {
    self.fulltext = Some(floor);
    self
  }

  /// Set the default floor for every VECTOR member, in the vector flavour's currency.
  #[inline]
  #[must_use]
  pub fn with_vector(mut self, floor: V) -> Self {
    self.vector = Some(floor);
    self
  }

  /// The full-text flavour default, if the query named one.
  #[inline]
  pub const fn fulltext(&self) -> Option<&F> {
    self.fulltext.as_ref()
  }

  /// The vector flavour default, if the query named one.
  #[inline]
  pub const fn vector(&self) -> Option<&V> {
    self.vector.as_ref()
  }

  /// **THE TRANSLATED-ARM OFFSET** for FULL-TEXT members — what a minted arm's floor sits above the
  /// caller's own, in the full-text flavour's currency.
  ///
  /// A positive offset floors a minted arm HIGHER, which is what a deployment that trusts its
  /// paraphrases less says; the currency is signed or not as the currency itself is, and the
  /// framework reads nothing into the sign.
  #[inline]
  #[must_use]
  pub fn with_translated_fulltext_offset(mut self, offset: F) -> Self {
    self.translated_fulltext = Some(offset);
    self
  }

  /// [`with_translated_fulltext_offset`](Self::with_translated_fulltext_offset)'s vector twin.
  #[inline]
  #[must_use]
  pub fn with_translated_vector_offset(mut self, offset: V) -> Self {
    self.translated_vector = Some(offset);
    self
  }

  /// The full-text offset a minted arm is floored above the original by, if this call named one.
  #[inline]
  pub const fn translated_fulltext_offset(&self) -> Option<&F> {
    self.translated_fulltext.as_ref()
  }

  /// The vector offset a minted arm is floored above the original by, if this call named one.
  #[inline]
  pub const fn translated_vector_offset(&self) -> Option<&V> {
    self.translated_vector.as_ref()
  }

  /// The floor ONE full-text member runs at: `over` if it was named for that member, else the
  /// flavour default, else `declared`.
  ///
  /// Borrowed through rather than cloned, so a floor whose currency is an expensive shape costs the
  /// resolution nothing.
  #[inline]
  pub fn resolve_fulltext<'a>(&'a self, over: Option<&'a F>, declared: &'a F) -> &'a F {
    over.or(self.fulltext()).unwrap_or(declared)
  }

  /// The floor ONE vector member runs at, by the same precedence.
  #[inline]
  pub fn resolve_vector<'a>(&'a self, over: Option<&'a V>, declared: &'a V) -> &'a V {
    over.or(self.vector()).unwrap_or(declared)
  }

  /// **THE FLOOR ONE FULL-TEXT MEMBER RUNS AT IN ONE ARM** —
  /// [`resolve_fulltext`](Self::resolve_fulltext)'s number, plus the offset where `origin` is an arm
  /// something minted.
  ///
  /// ```
  /// use ingraph::{ExpandOrigin, FloorSpec};
  ///
  /// let spec = FloorSpec::<f32, f32>::new()
  ///   .with_fulltext(0.4)
  ///   .with_translated_fulltext_offset(0.1);
  ///
  /// // What the caller asked runs at the base the precedence chain arrived at.
  /// assert_eq!(spec.resolve_fulltext_at(&ExpandOrigin::Original, None, &0.2), 0.4);
  ///
  /// // An arm an expander minted runs one offset above it — the SAME base, moved.
  /// assert_eq!(
  ///   spec.resolve_fulltext_at(&ExpandOrigin::expander("translate"), None, &0.2),
  ///   0.5,
  /// );
  ///
  /// // And the offset moves whichever tier won: a named override is a base like any other.
  /// assert_eq!(
  ///   spec.resolve_fulltext_at(&ExpandOrigin::expander("translate"), Some(&0.9), &0.2),
  ///   1.0,
  /// );
  /// ```
  ///
  /// # It answers BY VALUE where its base answers by borrow, and addition is why
  ///
  /// [`resolve_fulltext`](Self::resolve_fulltext) borrows through so an expensive currency costs the
  /// resolution nothing. A sum is a new value and there is nothing to borrow it from, so this one
  /// owns its answer — and the two bounds are on the METHOD rather than on the type, which is the
  /// posture [`Ranked::score`](crate::Ranked::score) already takes: a currency that cannot be added
  /// still gets a `FloorSpec`, and declines only this one call.
  #[inline]
  #[must_use]
  pub fn resolve_fulltext_at(
    &self,
    origin: &crate::ExpandOrigin,
    over: Option<&F>,
    declared: &F,
  ) -> F
  where
    F: Clone + core::ops::Add<Output = F>,
  {
    let base = self.resolve_fulltext(over, declared).clone();
    match self.translated_fulltext_offset() {
      Some(offset) if !origin.is_original() => base + offset.clone(),
      _ => base,
    }
  }

  /// [`resolve_fulltext_at`](Self::resolve_fulltext_at)'s vector twin, by the same precedence and the
  /// same offset law.
  #[inline]
  #[must_use]
  pub fn resolve_vector_at(&self, origin: &crate::ExpandOrigin, over: Option<&V>, declared: &V) -> V
  where
    V: Clone + core::ops::Add<Output = V>,
  {
    let base = self.resolve_vector(over, declared).clone();
    match self.translated_vector_offset() {
      Some(offset) if !origin.is_original() => base + offset.clone(),
      _ => base,
    }
  }

  /// **TIER 3 OVER TIER 2** — this request's floors laid over `deployment`'s, one field at a time.
  ///
  /// ```
  /// use ingraph::FloorSpec;
  ///
  /// let deployment = FloorSpec::<f32, f32>::new().with_fulltext(0.4).with_vector(0.7);
  /// let request = FloorSpec::<f32, f32>::new().with_vector(0.9);
  ///
  /// // The request names the vector floor and wins it; the full-text floor it said nothing about
  /// // is still the deployment's.
  /// let effective = request.over(deployment);
  /// assert_eq!(effective.vector(), Some(&0.9));
  /// assert_eq!(effective.fulltext(), Some(&0.4));
  /// ```
  ///
  /// # It is FIELD BY FIELD and never whole-value, and the difference is what a client wrote
  ///
  /// A request naming one flavour's floor has said nothing about the other, and replacing the whole
  /// value would read that silence as *take the shipped default* — turning a one-field request into
  /// a two-field one behind the client's back. The four fields resolve independently for the same
  /// reason [`ArmWeights::over`](crate::ArmWeights::over)'s one does.
  ///
  /// # CONSUMING, where the arm weight's is by reference
  ///
  /// A floor's currency is an open type and this crate will not demand `Clone` of it to compose two
  /// specs. Taking both sides by value moves each named number into the answer and costs nothing,
  /// which is the same trade every `with_…` on this type already makes.
  #[inline]
  #[must_use]
  pub fn over(self, deployment: Self) -> Self {
    Self {
      fulltext: self.fulltext.or(deployment.fulltext),
      vector: self.vector.or(deployment.vector),
      translated_fulltext: self.translated_fulltext.or(deployment.translated_fulltext),
      translated_vector: self.translated_vector.or(deployment.translated_vector),
    }
  }
}

/// No flavour default named.
///
/// Written rather than derived, because the derived body would have demanded `F: Default` and
/// `V: Default` — of two types whose only job is to be somebody else's score currency.
impl<F, V> Default for FloorSpec<F, V> {
  #[inline]
  fn default() -> Self {
    Self::new()
  }
}

#[cfg(test)]
mod tests;