Skip to main content

Crate ruvector_retrieval_receipt

Crate ruvector_retrieval_receipt 

Source
Expand description

Witness-chained provenance receipts for ANN retrieval results.

ruvector-proof-gate answers “what was written, and can I prove it hasn’t been tampered with?” for the write path. This crate addresses the read path: it commits a query’s result set to a receipt so that a receipt/result pair, once issued, cannot be silently mutated in transit or in storage without verification failing.

§Threat model — read this before relying on the receipts

Receipts are unsigned commitments produced by the query engine itself. What they do and do not guarantee:

  • They detect post-issuance mutation of a receipt/result pair. That is the guarantee: an auditor holding the receipt can tell whether the result set they were handed is the one the engine committed to.
  • They do not protect against a dishonest query engine. Leaves are engine-chosen; nothing binds a leaf’s score to an actual cosine computation, or the committed k-set to the true top-k.
  • They do not prove write-chain membership. Each leaf commits to copies of the WriteReceipt’s fields; verification never consults the write gate, so mutating the ingestion history after a receipt is issued leaves that receipt verifying. Binding each result to an offline membership proof via ruvector_proof_gate::MerkleGate’s MMR is the named future-work item that would make the write→read link real.

§Variants

VariantPer-query build costEvidence to verify 1 of k resultsGuarantee
NoReceipt0none (unverifiable)none
PerResultReceiptO(k) hashesO(idx) bytes, O(idx) worksequential tamper-evidence
MerkleReceiptO(k) hashesO(log k) bytes, O(log k) workmembership-proof tamper-evidence

§Signed anchoring (origin authentication)

The variants above are all unsigned: they detect tamper but do not authenticate an issuing key. signing adds typed, scoped Ed25519 anchoring on top of PerResultReceipt/MerkleReceipt roots, either per query (signing::Issuer::sign_root) or amortized across a batch of queries under one signature (signing::BatchAnchor). Binding a key to an organization remains the responsibility of an external key registry and revocation policy. See RetrievalReceipt::root and the signing module docs.

§Independent state-root anchoring

Signed receipt roots (above) authenticate what a specific query returned. state_anchor answers a decoupled question: has index_state_root itself ever been attested, independent of any query or receipt? See the module docs for the periodic-anchoring tradeoff this makes measurable.

Re-exports§

pub use batch_fill::BatchFillPolicy;
pub use batch_fill::BatchScheduler;
pub use batch_fill::PendingMember;
pub use signing::verify_root;
pub use signing::AnchorContext;
pub use signing::AnchorError;
pub use signing::AnchorPurpose;
pub use signing::BatchAnchor;
pub use signing::Issuer;
pub use signing::RootStatement;
pub use signing::SignedRoot;
pub use signing::VerifiedRoot;
pub use signing::SIGNED_ROOT_VERSION;
pub use state_anchor::verify_state_anchor;
pub use state_anchor::StateAnchor;
pub use state_anchor::StateAnchorLog;
pub use state_anchor::StateAnchorPolicy;

Modules§

batch_fill
Batch-fill scheduling for signed retrieval-receipt batches.
signing
Ed25519 authentication for retrieval receipt roots.
state_anchor
Independent, periodic signing of index_state_root, decoupled from any specific query or receipt.

Structs§

MerkleReceipt
Binary Merkle tree over a single query’s result set.
PerResultReceipt
Sequential SHA-256 chain over a single query’s result set. Verifying result i in isolation (without trusting a locally-held gate instance) requires replaying the chain from the genesis using leaves[0..=i]: O(i) work and O(i) bytes of evidence.
ResultItem
A single write-provenance-bound retrieval result.
RetrievalIndex
A brute-force, exact cosine-similarity retrieval index whose ingestion path is wrapped by a ruvector_proof_gate::HashChainGate. Every stored vector therefore carries a tamper-evident WriteReceipt from the moment it is admitted, and search returns those receipts alongside each result so a retrieval receipt can commit to them.

Enums§

ReceiptVariant
Which receipt strategy produced a given RetrievalReceipt.
RetrievalReceipt
A built receipt for one query’s result set, in whichever variant was requested. Carries enough state to answer proof_bytes_for / verify_item / verify_full uniformly across variants for benchmarking.

Functions§

query_hash
SHA-256 of the query vector’s raw bytes. Bound into every leaf so a receipt attests to which query produced the result set, not just the result set in isolation (prevents a receipt from being replayed against a different query).
synthetic_queries
Deterministic query generator: derives query vectors from the same xorshift stream family as RetrievalIndex::ingest, seeded independently so queries are reproducible but not identical to any stored vector.