LLLV — Index Pack & Evidence (lllv-index)

lllv-index constrói um Index Pack com Merkle root e responde consultas com Top-K + Evidence verificável (provas de inclusão). É o núcleo de busca com prova do Retrieval Atom (Paper III).

• Pack: TOC por blocos (params, vetores, doc_table, merkle) + Merkle root
• Evidence: ids, scores e Merkle paths; verificação offline
• Manifesto (opcional): JSON✯Atomic assinado (Paper II)

Instalação

[dependencies]
lllv-index = "0.1.0"
lllv-core  = "0.1.0"
serde = { version = "1.0", features = ["derive"] }

Quickstart — build, query, verify

use lllv_index::{IndexPackBuilder, QueryRequest};
use lllv_core::{Capsule, CapsuleFlags};
use ed25519_dalek::SigningKey;

fn main() {
    // 1) montar cápsulas (exemplo simples, vetores em f32 -> bytes)
    let sk = SigningKey::from_bytes(&[1u8; 32]);
    let v1 = vec![1.0f32, 0.0, 0.0];
    let v2 = vec![0.0f32, 1.0, 0.0];
    let v3 = vec![0.0f32, 0.0, 1.0];
    
    fn to_bytes(v: &[f32]) -> Vec<u8> {
        v.iter().flat_map(|x| x.to_le_bytes()).collect()
    }
    
    let mut b = IndexPackBuilder::new(3);
    b.add_capsule("a".into(), Capsule::create(3, &to_bytes(&v1), CapsuleFlags::NONE, &sk).unwrap()).unwrap();
    b.add_capsule("b".into(), Capsule::create(3, &to_bytes(&v2), CapsuleFlags::NONE, &sk).unwrap()).unwrap();
    b.add_capsule("c".into(), Capsule::create(3, &to_bytes(&v3), CapsuleFlags::NONE, &sk).unwrap()).unwrap();

    // 2) build do pack
    let pack = b.build(None).unwrap(); // None = sem manifesto assinado

    // 3) query
    let q = vec![1.0f32, 0.0, 0.0]; // perto de "a"
    let ev = pack.query(&QueryRequest::from_vec(&q), 2).unwrap();

    // 4) verify
    pack.verify(&ev).unwrap();
    assert_eq!(ev.results[0].id, "a");
    println!("Top1 = {}, score={:.3}", ev.results[0].id, ev.results[0].score);
}

Nota: para manifesto/evidence assinados (JSON✯Atomic), ative a feature manifest e forneça uma SigningKey no build().

API (essencial)

pub struct IndexPack { /* dim, ids, vetores, merkle_root, ... */ }
pub struct IndexPackBuilder::new(dim: u16);
impl IndexPackBuilder {
  pub fn add_capsule(&mut self, id: String, cap: lllv_core::Capsule) -> Result<(), Error>;
  pub fn build(&self, sk: Option<&ed25519_dalek::SigningKey>) -> Result<IndexPack, Error>;
}
pub struct QueryRequest { pub vec: Vec<f32> }
pub struct QueryEvidence { pub index_pack_cid: String, pub results: Vec<QueryResult>, /* proofs… */ }
impl IndexPack {
  pub fn query(&self, req: &QueryRequest, topk: usize) -> Result<QueryEvidence, Error>;
  pub fn verify(&self, ev: &QueryEvidence) -> Result<(), Error>;
}

Segurança

• Cada documento vira folha Merkle: H( "DOC" || id || H(payload) )
• Merkle root cobre toda a doc_table
• Evidence inclui Merkle path por resultado → verificação offline
• Opcional: manifesto do Pack e evidence selados (JSON✯Atomic + Ed25519)

MIT • MSRV 1.75+ • pronto para evoluir p/ alloc/no_std no v0.1.1.