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
//! bytes → Key: the engine's own addresses read back into the node's own key type — and, since the
//! by-key read landed, Key → bytes on the way back.
//!
//! ONE READ PER ENGINE FAMILY — [`keyed`] for full-text, [`vector_keyed`] for vector. They are two
//! rather than one because the SEAMS are two: `E::Address` and `E::Error` project through
//! [`FulltextEngine`] in one and [`VectorEngine`] in the other. Collapsing them would take a third
//! trait unifying the two engine faces — a seam invented to save a duplicated `map`, and one every
//! backend would then have to know about.
//!
//! **BOTH now spend the same kind of row, which is the column language landed on both sides.** Each
//! walk asks for [`Field`] — engine-blind, one impl per TYPE — and drives its own engine's
//! `buffer` / `finalize` / `open` phases around it. What is still two is the SEAM each is generic
//! in, and nothing else: the bodies are line-for-line the same walk.
//!
//! [`vector_addressed`] is the WRITE, and there is one rather than two because only one family has
//! a caller: [`VectorRead::get`](crate::VectorRead::get) takes an address a key was written into,
//! and the full-text family's own by-key read has no grammar yet. The only code that builds a
//! full-text address is a backend's own entry builder, which spells the three phases where the
//! engine is concrete.

use crate::{ColumnReader, Field, FulltextEngine, Hits, Scored, VectorEngine};

/// Read every FULL-TEXT hit's ADDRESS back into `K` — the emission's half of the read, written once.
///
/// [`vector_keyed`] is the same walk for the other family; the module note says why they are two.
///
/// # Why it is here and not inside the engine
///
/// [`FulltextEngine`] is R-free: it stores what it is handed and hands it back, and it cannot name a
/// declaration's key type. So the typed half of the read belongs to the code that CAN — the emitted
/// `retrieve_keys`, which knows `K` because it knows its own upstream. This function is that code's
/// one shared line, exactly as [`ranked_keys`](super::ranked_keys) is the pipeline's: the emission
/// names the types and the framework owns the walk.
///
/// Three things happen per hit, in this order and no other:
///
/// 1. [`FulltextEngine::open`] turns the hit's address into a READ PHASE, consuming it;
/// 2. `K` takes its columns off that phase, one [`Field`] row per column, in the order the key's own
///    impl wrote them;
/// 3. [`ColumnReader::finish`] asks whether anything is LEFT — a stored address carrying more
///    columns than the key reads is a drifted column sequence, and it is named rather than silently
///    half-read.
///
/// The key's row names NO ENGINE, which is what the column language bought: one [`Field`] impl per
/// TYPE serves every engine there is, where the retired per-family row had to be written once per
/// (type × engine).
///
/// # It is FAIL-FAST, and that is the conservative reading
///
/// One unreadable address fails the whole answer rather than being dropped from it. A key that will
/// not decode is a corrupt index or a key whose column sequence no longer matches what was indexed
/// — a condition about the INDEX, not about that one hit — so a page silently one shorter would hide
/// exactly the thing worth surfacing.
///
/// # Errors
///
/// The engine's own error, from a column's read or from the completeness check — one type, because
/// [`ReadBuffer`](FulltextEngine::ReadBuffer) is tied to [`Error`](FulltextEngine::Error).
pub fn keyed<E, K>(hits: Hits<E::Address, E::Score>) -> Result<Hits<K, E::Score>, E::Error>
where
  E: FulltextEngine,
  K: Field,
{
  hits
    .into_iter()
    .map(|hit| {
      let (address, score) = hit.into_components();
      let mut phase = E::open(address);
      let key = K::read(&mut phase)?;
      phase.finish()?;
      Ok(Scored::new(key, score))
    })
    .collect()
}

/// Read every VECTOR hit's ADDRESS back into `K` — [`keyed`]'s twin, and the SAME walk one seam
/// over.
///
/// Everything [`keyed`] states holds here unchanged, phase for phase and posture for posture: the
/// same order, the same fail-fast reading, the same engine-blind row, and the same reason the typed
/// half is the emission's rather than the engine's — [`VectorEngine`] is R-free too, so it answers
/// in its own address vocabulary and only the code that knows the upstream knows `K`.
///
/// # Errors
///
/// The engine's own error, from a column's read or from the completeness check — one type, because
/// [`ReadBuffer`](VectorEngine::ReadBuffer) is tied to [`Error`](VectorEngine::Error).
pub fn vector_keyed<E, K>(hits: Hits<E::Address, E::Score>) -> Result<Hits<K, E::Score>, E::Error>
where
  E: VectorEngine,
  K: Field,
{
  hits
    .into_iter()
    .map(|hit| {
      let (address, score) = hit.into_components();
      let mut phase = E::open(address);
      let key = K::read(&mut phase)?;
      phase.finish()?;
      Ok(Scored::new(key, score))
    })
    .collect()
}

/// Report `key` into a FRESH buffer of `E`'s own and seal it — the walk above run BACKWARDS, and the
/// emission's half of the by-key read.
///
/// [`vector_keyed`] turns an address the engine produced into a key; this turns a key the caller
/// holds into the address [`VectorRead::get`](crate::VectorRead::get) takes. The two are one
/// correspondence read in two directions, which is why [`Field`] is one trait with two methods:
/// `write` reports a value's columns in the key's own order and `read` takes them back off in that
/// same order, so an address built here and an address a hit arrives under are THE SAME BYTES for
/// the same key.
///
/// # The buffer is the engine's, and that is the one thing this walk cannot supply itself
///
/// A row REPORTS and does not create: it is handed a [`ColumnWriter`](crate::ColumnWriter) and lands
/// its columns in it. Where that writer comes from is the engine's business — an arrow builder, a
/// term buffer, a bound-parameter list — so [`VectorEngine::buffer`] is what this calls, and its doc
/// says why a `Default` bound was the wrong shape for it.
///
/// # It is INFALLIBLE, and the asymmetry with [`vector_keyed`] is real rather than an oversight
///
/// Writing a key cannot fail: [`ColumnWriter`](crate::ColumnWriter) has no failing method, a value
/// renders its own columns, and the address is whatever they seal to. Reading one can, because the
/// bytes may be a key's from another era. There is no completeness check to run either — that check
/// asks whether a STORED address carried more than the key read, and this address was just built
/// from the key and carries exactly it.
pub fn vector_addressed<E, K>(key: &K) -> E::Address
where
  E: VectorEngine,
  K: Field,
{
  let mut buf = E::buffer();
  key.write(&mut buf);
  E::finalize(buf)
}

#[cfg(test)]
mod tests;