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
//! **`k` IS A CEILING AND NOT AN ALLOCATION HINT** — the seam's law, observed on the engine that is
//! its reference discipline.
//!
//! The law is stated on both engine verbs' `k` docs, and a sentence on a trait binds nobody by
//! itself. What binds this backend is the clamp in `search_slot`: `min(k, num_docs)`,
//! answer-preserving by construction, because a search cannot return more hits than there are live
//! documents. This file is the clamp's own proof.
//!
//! # The number is not hypothetical
//!
//! `NonZeroUsize::MAX` is what the emitted tier-B door asks its own tier A with, and it means *as
//! many as exist* — the fill loop's filter is what decides how many of them fill a page. So an
//! engine that sized a collector by `k` would abort on an ordinary door call rather than on an
//! exotic one: tantivy's `TopNComputer` allocates `k.max(1) * 2` up front, and that multiply
//! overflows long before it allocates.
//!
//! Sibling to [`tests`](super) rather than inside it, on the one-file-per-thing-proved precedent:
//! what is proved here is a DISCIPLINE, and it is the only thing in this backend's suite that would
//! fail by aborting rather than by answering wrongly.

use super::*;

/// Everything that exists — the honest unbounded ask, in the door family's own currency.
const EVERYTHING: NonZeroUsize = NonZeroUsize::MAX;

/// **AN UNBOUNDED `k` ANSWERS** rather than aborting, and it answers the same hits a small one does.
///
/// Both halves are the claim. Answering at all is the clamp doing its job; answering the SAME thing
/// is what *answer-preserving by construction* means — a ceiling above the corpus removes only
/// capacity that could never have been filled, so the result is the corpus's own and not a truncated
/// view of it.
///
/// MUTATION-CHECKED: hand `TopDocs::with_limit` the raw `k.get()` and this aborts inside tantivy
/// where no caller can catch it — *attempt to multiply with overflow*, at `TopNComputer`'s own
/// `n.max(1) * 2`.
#[test]
fn an_unbounded_k_is_clamped_to_what_the_slot_holds_and_still_answers() {
  let (_dir, store) = open_store();
  let captions = store.fulltext(Caption::SLOT.as_ref());

  commit(
    &store,
    &captions,
    &[
      caption("m1", 1, "the quick brown fox"),
      caption("m2", 2, "a heron over still water"),
    ],
  );

  let unbounded = block_on(captions.search(
    Connected::new(&store, ()),
    FulltextSubset::All,
    "fox",
    EVERYTHING,
    None,
  ))
  .expect("an unbounded ask is an ordinary ask");
  let unbounded = keyed::<TantivyFulltext, CaptionKey>(unbounded).expect("the address reads back");

  assert_eq!(unbounded.len(), 1);
  assert_eq!(unbounded[0].data_ref(), &caption_key("m1", 1));
  assert_eq!(
    unbounded,
    search(&store, &captions, "fox").expect("the bounded search runs"),
    "the ceiling above the corpus changed the answer",
  );
}

/// **AN EMPTY SLOT STILL RUNS THE QUERY** under the same unbounded ask — the clamp's own floor.
///
/// `min(k, num_docs)` is zero on a never-written corpus and `with_limit` asserts on zero, so the
/// clamp carries a `.max(1)`. What it buys is that *no hits* is an ANSWER here rather than a panic,
/// which is the only honest result for a slot nobody has written to yet.
///
/// MUTATION-CHECKED, and it fires on THIS test alone: drop the `.max(1)` and only this one reds —
/// *Limit must be greater than 0*, tantivy's own assertion — while the test above stays green. The
/// two halves of the clamp are therefore two claims, each with its own pin.
#[test]
fn an_empty_slot_answers_nothing_rather_than_aborting() {
  let (_dir, store) = open_store();
  let captions = store.fulltext(Caption::SLOT.as_ref());

  let hits = block_on(captions.search(
    Connected::new(&store, ()),
    FulltextSubset::All,
    "fox",
    EVERYTHING,
    None,
  ))
  .expect("an unwritten slot answers");

  assert!(hits.is_empty(), "{hits:?}");
}