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
scoreto 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 viaruvector_proof_gate::MerkleGate’s MMR is the named future-work item that would make the write→read link real.
§Variants
| Variant | Per-query build cost | Evidence to verify 1 of k results | Guarantee |
|---|---|---|---|
NoReceipt | 0 | none (unverifiable) | none |
PerResultReceipt | O(k) hashes | O(idx) bytes, O(idx) work | sequential tamper-evidence |
MerkleReceipt | O(k) hashes | O(log k) bytes, O(log k) work | membership-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§
- Merkle
Receipt - Binary Merkle tree over a single query’s result set.
- PerResult
Receipt - Sequential SHA-256 chain over a single query’s result set. Verifying
result
iin isolation (without trusting a locally-held gate instance) requires replaying the chain from the genesis usingleaves[0..=i]: O(i) work and O(i) bytes of evidence. - Result
Item - A single write-provenance-bound retrieval result.
- Retrieval
Index - 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-evidentWriteReceiptfrom the moment it is admitted, andsearchreturns those receipts alongside each result so a retrieval receipt can commit to them.
Enums§
- Receipt
Variant - Which receipt strategy produced a given
RetrievalReceipt. - Retrieval
Receipt - 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_fulluniformly 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.