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
//! What a TOWER is: the question pipeline that turns what a person asked into what an index can be
//! asked with.
//!
//! A tower is layer ⑤ — `Question → step → step → … → Answer` — and its whole content is a chain of
//! [`Serves`](crate::Serves) / [`AsyncServes`](crate::AsyncServes) hops whose ends meet. The
//! declaration is the struct that HOLDS them:
//!
//! ```ignore
//! #[ingraph::tower(question(type = "String"))]
//! pub struct ClipText {
//!   #[ingraph(answer = "Vec<String>")]  tokenize: Tokenize,
//!   #[ingraph(answer = "Vec<f32>", async)] encode: ClipTextTower,
//! }
//! ```
//!
//! # THE CHAIN IS NOT STATED HERE, and it could not be
//!
//! This trait carries the tower's two ENDS and where its steps live, and says nothing about the
//! hops between them. That is not an omission: a trait's shape is fixed and a tower's arity is
//! not, so the per-hop demand — *this step answers the question the step before it asked* — has no
//! seat here to sit in. It is stated instead on the emitted `impl`'s own `where` clause, one
//! predicate per adjacency, each spanned at the step field it is about. A tower whose chain does
//! not meet is `E0277` at the impl with the caret on the step that broke it, and this trait is what
//! that impl is FOR.
//!
//! # The WALK is an inherent fn, for the same reason
//!
//! A three-step tower's walk takes three step borrows and a five-step tower's takes five, so the
//! walk cannot be a method here either. The emission mints it on the declaration itself —
//! `ClipText::walk(question, &mut tokenize, &mut encode, options)` — which is the mutation node's
//! assembled face one layer over, and its FACE follows the same OR law: one awaited step makes the
//! whole walk awaited.
//!
//! # It is an OPEN seam
//!
//! Nothing here is the macro's to own. A hand-written tower writes these three lines and its own
//! walk, and every consumer that binds `SearchTower` takes it — the framework-open discipline the
//! resource axis and the origin layer already state one layer down.
//!
//! # THE RECORD is what crosses the wall
//!
//! [`SearchTower`] is what a tower IS; [`DeclaredTower`] is what one DECLARED. The split is the
//! same one [`DeclaredMutation`](crate::DeclaredMutation) and [`DeclaredOrigin`](crate::DeclaredOrigin)
//! already make one layer down, and it exists for the same wall: a search recipe naming
//! `tower(text(type = "crate::ClipText"))` expands in a pass that has never seen `ClipText`'s
//! fields, so what crosses is a trait impl and a projection off it rather than a guess at a name.

/// **WHAT A TOWER IS ASKED, WHAT IT ANSWERS, AND WHERE ITS STEPS LIVE.**
///
/// Emitted by `#[ingraph::tower]` off the declaration's own words, and hand-writable by anybody —
/// see the module note for why the chain between the two ends is not here.
///
/// # The two ends are TYPES rather than a kind
///
/// A tower is KIND-AGNOSTIC: a `String → String` rewrite tower serves a full-text binding and a
/// `String → Vec<f32>` one serves a vector binding, and nothing here distinguishes them. What a
/// binding checks is the [`Answer`](Self::Answer) TYPE against what the member it binds is
/// addressed by, so the contract is the type and never a word.
#[diagnostic::on_unimplemented(
  message = "`{Self}` is not a search tower",
  label = "no tower declaration",
  note = "`#[ingraph::tower(question(type = \"…\"))]` emits this row off the declaration's own \
          words; a hand-written tower writes `impl SearchTower for {Self}` with its two ends and \
          its steps"
)]
pub trait SearchTower {
  /// What the WHOLE tower is asked — the first step's question, and the only one a caller names.
  ///
  /// Every question after it is the answer of the step before, so a tower takes exactly one type
  /// however many hops it has.
  type Question;

  /// What the whole tower ANSWERS — the last step's answer.
  ///
  /// This is the seat a binding is checked against: a member addressed by one coordinate type and
  /// a tower answering another do not meet, and the refusal names both.
  ///
  /// It is also what a declaration's own `answer = "…"` head word is checked against, and the same
  /// seat serves both on purpose: a tower's stated intent and a consumer's demand are the same
  /// question asked at two distances, so a chain whose end moves is answered identically at each.
  type Answer;

  /// WHERE THE STEPS LIVE — the struct whose fields are the servers a walk borrows.
  ///
  /// The declaration is its own steps struct today (`type Steps = Self`), which is what
  /// fields-are-steps means: the field that holds a step, the walk parameter that borrows it and
  /// the row that will configure it are one name in three places. The seat is a TYPE rather than
  /// `Self` so that a deployment holding its steps somewhere else — assembled by a builder, owned
  /// by a registry — has somewhere to say so without the tower's two ends moving.
  type Steps;
}

/// **WHAT ONE TOWER DECLARED** — the facts its own expansion states, for the readers that cannot see
/// its tokens.
///
/// [`DeclaredMutation`](crate::DeclaredMutation)'s shape one layer over, and for the same wall: two
/// macro expansions cannot read each other, so a tower STATES its facts as a trait impl and whoever
/// needs them NAMES them through a projection.
///
/// ```ignore
/// impl DeclaredTower for ClipText {
///   type StepOptions = ClipTextStepOptions;
///   type SearchOptions = ClipTextSearchOptions;
///   const ALL_SYNC: bool = false;
///   const STEPS: &'static [Step] = &[Step::of("tokenize"), Step::of("encode").awaited()];
/// }
/// ```
///
/// # What each seat is FOR
///
/// A search recipe binding a tower has four questions its own tokens cannot answer, and this row
/// answers all four: whether to `.await` the walk it emits ([`ALL_SYNC`](Self::ALL_SYNC), the OR law
/// read the other way round), what the DEPLOYMENT named at install
/// ([`StepOptions`](Self::StepOptions)), what a REQUEST may name per question
/// ([`SearchOptions`](Self::SearchOptions)), and which steps the step-keyed object has rows for
/// ([`STEPS`](Self::STEPS), in declaration order — the same order the walk takes its borrows in).
///
/// # THE TWO OPTIONS SEATS ARE TWO CLOCKS, and the names say which
///
/// [`StepOptions`](Self::StepOptions) is keyed by STEP and named once, at INSTALL: it is the
/// deployment's clock, and its rows are the application's own `Serve::Options` types.
/// [`SearchOptions`](Self::SearchOptions) is keyed by the declaration's own WORDS and named per
/// REQUEST: it is the requester's clock, and its rows are the FRAMEWORK's knobs — the only ones an
/// emitter can key a field on and the only ones that mean the same thing for every tower.
///
/// The two ENDS are not restated here, and that is the one-landing law rather than an omission: the
/// supertrait already carries [`Question`](SearchTower::Question) and
/// [`Answer`](SearchTower::Answer), so a reader that holds this row holds them too and no two seats
/// can disagree about one fact.
///
/// # It is a PUBLIC seam, exactly as [`SearchTower`] is
///
/// Both constants are defaulted, so a hand-written tower joins with two type lines and nothing else.
/// A tower is not obliged to be generated to be bound.
#[diagnostic::on_unimplemented(
  message = "`{Self}` states no tower declaration",
  label = "no declared tower",
  note = "`#[ingraph::tower]` emits this row off the declaration's own fields; a hand-written tower \
          writes `impl DeclaredTower for {Self} {{ type StepOptions = (); type SearchOptions = \
          ::ingraph::SearchBudget; }}` — the honest nothing at install, and the framework's \
          budget-only citizen per request"
)]
pub trait DeclaredTower: SearchTower {
  /// **THE KNOBS A DEPLOYMENT NAMES FOR THE WHOLE TOWER** — the emitted `<Tower>StepOptions`, whose
  /// fields are its steps.
  ///
  /// This is the tower's own object and never a step's seat: a step's knobs are declared once on the
  /// SERVER, at [`Serve::Options`](crate::Serve::Options), and what this type does is hold one
  /// [`Option`] of each so that a caller names some, all or none of them in one value.
  ///
  /// `()` for a hand-written tower that takes none, on [`Serve::Options`](crate::Serve::Options)'s
  /// own road — an ANSWER rather than a placeholder.
  ///
  /// It has NO DEFAULT, and that is the language rather than a choice: associated-type defaults are
  /// not stable, so a hand-written tower states `type StepOptions = ();` in as many words.
  type StepOptions;

  /// **THE KNOBS A REQUEST NAMES FOR ONE QUESTION** — the emitted `<Tower>SearchOptions`, whose
  /// fields are the declaration's own WORDS.
  ///
  /// Tier three's carriage, and the seat that made [`ArmWeights::over`](crate::ArmWeights::over) and
  /// [`tightened_budget`](crate::tightened_budget) reachable from a wire at all. It is keyed by the
  /// TOWER GRAMMAR — `expand` mints an arm-weight row, a shipped weighted crossing mints a lane
  /// emphasis — because that grammar is where the words are; a recipe binding a tower holds a type
  /// path and can key nothing.
  ///
  /// # THE BUDGET ROW IS ALWAYS THERE, and a wordless tower still has a face
  ///
  /// [`SearchBudget`](crate::SearchBudget) is the framework's budget-only citizen and it means the
  /// same thing for every tower ever declared, so the minted object carries it whatever words the
  /// declaration wrote. That is also what keeps the face SPELLABLE: a GraphQL input object may not
  /// define zero fields, so a tower whose grammar wrote nothing would otherwise have no face to
  /// publish.
  ///
  /// # `()` is sayable and it is a ROAD rather than a gap
  ///
  /// A hand-written tower that is walked from Rust alone writes `type SearchOptions = ();` and pays
  /// nothing. The demand for a WIRE face lands only where a DRESSED recipe publishes the argument —
  /// see [`SearchOptionsFace`](crate::SearchOptionsFace), whose refusal names the one line to write.
  ///
  /// It has NO DEFAULT, for [`StepOptions`](Self::StepOptions)'s reason: associated-type defaults
  /// are not stable, so a hand-written tower states its answer in as many words.
  type SearchOptions;

  /// Whether EVERY step here is served by a BLOCKING face.
  ///
  /// The OR law read the other way round, and the same seat
  /// [`DeclaredMutation::ALL_SYNC`](crate::DeclaredMutation::ALL_SYNC) holds one layer down: one
  /// awaited step makes the whole walk awaited, so this is `true` only where the tower is blocking
  /// end to end. A recipe emitting a call to a tower's `walk` reads it to know whether the call it
  /// writes is awaited — which is a fact about tokens it cannot see, and the reason this row exists.
  ///
  /// Defaulted to the blocking answer, which is what a declaration with no `async` step states.
  const ALL_SYNC: bool = true;

  /// Every step this tower declared, in declaration order — EMPTY for a hand-written tower that
  /// states nothing about its steps.
  ///
  /// Declaration order is the contract, exactly as it is for
  /// [`DeclaredMutation::EXCHANGES`](crate::DeclaredMutation::EXCHANGES): the walk takes its step
  /// borrows in this order and the options object carries its rows in it, so an entry's PLACE here
  /// is the position it occupies in both.
  const STEPS: &'static [Step] = &[];
}

/// ONE DECLARED STEP, as the declaration wrote it.
///
/// The per-field facts of the tower grammar, in the shape a reader spends them: which field, and
/// which face the word beside it chose. Both are `const`-constructible, because the whole roster is
/// an associated constant — [`Exchange`](crate::Exchange)'s own reason one layer down: a tower's
/// steps are a fact about its declaration and not a value anybody computes.
///
/// # It carries the NAME and never the type
///
/// A step's server is a TYPE, and a type is what the emitted chain's own `where` predicate names —
/// where the compiler can check it. What a reader of this record does with a step is name its ROW:
/// the walk parameter it fills, the options field it configures, the schema row it publishes. So
/// what is carried is the one name those three homes share.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
pub struct Step {
  /// The RUST field this step was declared as.
  field: &'static str,
  /// Whether it wore the `async` word.
  awaited: bool,
}

impl Step {
  /// The step `field` declares, on the BLOCKING face — the one word no step can omit.
  ///
  /// The face is the word a step MAY write, so it arrives through the builder below and the absence
  /// of a call IS the absence of the word.
  #[inline]
  #[must_use]
  pub const fn of(field: &'static str) -> Self {
    Self {
      field,
      awaited: false,
    }
  }

  /// The same step, whose hop wears the `async` word.
  #[inline]
  #[must_use]
  pub const fn awaited(mut self) -> Self {
    self.awaited = true;
    self
  }

  /// The Rust field this step was declared as — its ONE name, in all three of its homes.
  #[inline]
  #[must_use]
  pub const fn field(&self) -> &'static str {
    self.field
  }

  /// Whether this step's hop is awaited.
  #[inline]
  #[must_use]
  pub const fn is_awaited(&self) -> bool {
    self.awaited
  }
}

#[cfg(test)]
mod tests;