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 BY-KEY VOCABULARY — what the emitted `get_<field>` and `retrieve_similar_by_<field>` doors
//! report when the KEY's own stored vector is the problem.
//!
//! `get_<field>` reads that vector back through [`VectorRead::get`](crate::VectorRead::get) and
//! checks it against what the declaration says it is. `retrieve_similar_by_<field>` is sugar over
//! the raw pair and adds no query machine: it takes its example FROM that door, hands it to the
//! same `knn` the raw door calls, and excludes the example from the answer.
//!
//! What both can say that the raw pair cannot is that the key's own vector was unusable — and those
//! refusals are here, because none of them is an engine failure and answering an empty page for any
//! of them would be indistinguishable from *nothing was near enough*.
//!
//! # ONE type for TWO doors, and that is the delegation's own requirement
//!
//! The three judgments are made in `get_<field>` and reported by both doors. A second vocabulary
//! for the second door would mean translating one into the other at the delegation — and a
//! re-worded refusal is a refusal a caller cannot match against the original, which is the whole
//! failure a shared type removes.
//!
//! # The file is still called `similar`, and the type is not
//!
//! What else lives here is [`tests`] — half of which is about `ranked_keys_excluding`, the
//! EXCLUSION, which belongs to the similar door and to nothing else. The type moved to a name that
//! covers both doors; the module kept the name that covers what it holds.

use core::fmt;

/// What an OWN READ reports: the engine refused, or the entity's own stored vector did.
///
/// The *own read* is the act both by-key doors begin with — `get_<field>` IS it, and
/// `retrieve_similar_by_<field>` reaches its example through that door — so the name is the act
/// rather than either caller. The shape is the family's: one type for the whole call, arms for the
/// things that are not the engine's fault, and the engine's own error carried whole rather than
/// translated.
///
/// # The three non-engine arms are all *the stored vector is not what the declaration says it is*
///
/// An own read has an input the caller never supplies: the vector the engine holds for that key.
/// Every arm below is a way that vector failed to be one, and each is NAMED rather than answered
/// with an empty page — because an empty page already means *nothing cleared the floor*, and a door
/// with two silent meanings for one answer is a door whose caller cannot debug it.
///
/// # ONE type for TWO doors, and the delegation is why
///
/// `get_<field>` makes all three findings; `retrieve_similar_by_<field>` reports them without
/// touching them. A second vocabulary for the second door would mean translating one into the other
/// at the delegation, and a re-worded refusal is one a caller cannot match against the original.
/// Every sentence below is therefore written about what was FOUND rather than about what the caller
/// wanted it for.
#[derive(Debug)]
pub enum OwnReadError<E> {
  /// The engine refused — the by-key read, the `knn` a similar retrieve runs after it, or the
  /// address read between them.
  ///
  /// Carried whole and untranslated, for [`RetrieveError`](super::RetrieveError)'s reason: the
  /// backend's own vocabulary is the only one that can say what actually went wrong, and a
  /// framework re-wording would lose it.
  Engine(E),
  /// The key holds NOTHING in this column.
  ///
  /// The entity was never indexed here, its entry has gone, or the key is not this index's at all.
  /// [`VectorRead::get`](crate::VectorRead::get) treats an empty answer as legal (an engine
  /// owes no opinion about a key it does not hold); the DOOR is where it becomes a refusal, because
  /// here it is a fact about the caller's own argument.
  Unindexed,
  /// The key holds SEVERAL vectors where this election declared ONE.
  ///
  /// A drift between what the engine stored and what the declaration says, and the same restraint
  /// [`ColumnReader::finish`](crate::ColumnReader::finish) — the seat the retired `exhausted` verb
  /// held — takes about an address holding more columns than the key reads: the surplus is named
  /// rather than silently half-used. Taking the
  /// first would be answering from one of several vectors nobody chose between — the same
  /// winner-picking a fanned read is forbidden for, one grain down.
  Several {
    /// How many the column answered with.
    held: usize,
  },
  /// The stored vector is not the WIDTH this election declared.
  ///
  /// The declared width is the field's own `Embedding<_, N>`, checked here for the same reason it is
  /// checked at every other crossing: a value of that type has `N` coordinates or was never built,
  /// and a vector arriving from a backend has been through neither the constructor nor the type.
  Width {
    /// The width the elected field's type states.
    declared: usize,
    /// The width the engine answered with.
    stored: usize,
  },
}

impl<E: fmt::Display> fmt::Display for OwnReadError<E> {
  fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
    match self {
      Self::Engine(error) => write!(f, "{error}"),
      Self::Unindexed => f.write_str("the key holds no vector in this column"),
      Self::Several { held } => write!(
        f,
        "the key holds {held} vectors in this column where the election declared one"
      ),
      Self::Width { declared, stored } => write!(
        f,
        "the stored vector has {stored} coordinates where the election declared {declared}"
      ),
    }
  }
}

impl<E> core::error::Error for OwnReadError<E>
where
  E: core::error::Error + 'static,
{
  fn source(&self) -> Option<&(dyn core::error::Error + 'static)> {
    match self {
      Self::Engine(error) => Some(error),
      Self::Unindexed | Self::Several { .. } | Self::Width { .. } => None,
    }
  }
}

#[cfg(test)]
mod tests;