feat: Deterministic Proof Bridge — per-record BLAKE3 Merkle proofs

- Fix f32→Q16.16 conversion discrepancy (from_f32 now uses round+clamp)
- Single source of truth: kernel's from_f32() used by FFI, never inlined
- Add bridge functions: ingest_embedding, generate_proof, verify_embedding
- Add insert_with_proof() — atomic insert with proof as Record.metadata
- Proofs are event-sourced, snapshot-persisted, included in state hash
- Add ValoriAdapter — drop-in wrapper for external vector DBs
- 47 Python tests + 11 Rust tests, all passing

Files changed:
  src/fxp/ops.rs          — from_f32() aligned to use .round().clamp()
  ffi/Cargo.toml          — enable std feature, add blake3 dep
  ffi/src/lib.rs          — bridge functions + insert_with_proof
  python/valori/adapter.py — kernel-backed proof adapter
  python/valori/__init__.py — export bridge functions
  README.md               — document Proof Bridge

Author: varshith-Git

Cargo.lock

@@ -191,6 +191,86 @@ Valori uses **Q16.16 Fixed-Point Arithmetic** instead of standard `f32` floats.
 - **Bare Metal:** `no_std` compatible for ARM Cortex-M embedded systems
 - **Replication:** Leader-follower for read scaling
 
+### 7. Deterministic Proof Bridge
+- **Per-record proofs** — BLAKE3 Merkle tree over Q16.16 integers
+- **Atomic insertion** — proof baked into `Record.metadata` at birth
+- **Event-sourced** — proofs go through `KernelEvent`, survive restarts
+- **Drop-in adapter** — wrap any existing vector DB (Pinecone, Qdrant, etc.)
+- **Hardware-independent** — same embedding → same proof on any machine
+
+---
+
+## 🔐 Deterministic Proof Bridge
+
+Valori can generate per-record cryptographic proofs over AI embeddings. Proofs are deterministic — identical on any hardware — and stored inside the kernel's event-sourced state.
+
+### Direct Usage (Rust FFI)
+
+```python
+from valori import ingest_embedding, generate_proof, verify_embedding
+
+# Any AI model → float embedding
+embedding = model.encode("patient diagnosis report")
+
+# Convert to Q16.16 integers (deterministic, hardware-independent)
+fixed = ingest_embedding(embedding.tolist())
+
+# Generate BLAKE3 Merkle proof
+proof_hash = generate_proof(fixed)
+
+# Verify on any machine, any time — no server needed
+assert verify_embedding(embedding.tolist(), proof_hash)  # True
+```
+
+### Atomic Insert with Proof (Kernel-Backed)
+
+```python
+from valori import Valori
+
+client = Valori()
+
+# Single FFI call — proof is baked into Record.metadata
+record_id, proof_hash = client.kernel.insert_with_proof(
+    embedding.tolist(), tag=0
+)
+
+# Proof is now:
+# ✅ Stored as Record.metadata
+# ✅ Event-sourced (in the event log)
+# ✅ Included in kernel_state_hash()
+# ✅ Persisted in snapshots
+# ✅ Survives crashes and restarts
+```
+
+### Drop-in Adapter for Existing Systems
+
+```python
+from valori import ValoriAdapter
+
+# Wrap your existing vector DB — zero changes to existing code
+db = ValoriAdapter(your_pinecone_client)
+
+# Insert goes to both: external DB + Valori kernel (for proofs)
+proof = db.insert("doc_001", embedding)
+
+# Verify anytime
+db.verify("doc_001", embedding)  # True — proof from kernel metadata
+
+# Search results include verification status
+results = db.search(query_embedding, k=10)
+# Each result has: {"id": ..., "verified": True, "proof_hash": "abc..."}
+```
+
+### What Makes This Different
+
+| Feature | Other VectorDBs | Valori |
+|---------|----------------|--------|
+| **Per-record proof** | ❌ Not possible | ✅ BLAKE3 Merkle root per embedding |
+| **Offline verification** | ❌ Need running server | ✅ `verify_embedding()` runs anywhere |
+| **Tamper detection** | ❌ Only global checksums | ✅ Detects exactly which record changed |
+| **Hardware-independent** | ❌ Float rounding varies | ✅ Q16.16 integers — bit-identical everywhere |
+| **Zero trust** | ❌ Must trust vendor | ✅ Proof is math, not policy |
+
 ---
 
 ## 📚 Documentation

README.md

@@ -8,8 +8,9 @@ name = "valori_ffi"
 crate-type = ["cdylib"]
 
 [dependencies]
-valori-kernel = { path = ".." }
+valori-kernel = { path = "..", features = ["std"] }
 valori-node = { path = "../node" }
 pyo3 = { version = "0.23", features = ["extension-module", "abi3-py39"] }
 serde_json = "1.0"
 hex = "0.4"
+blake3 = "1"

ffi/Cargo.toml

@@ -4,8 +4,8 @@ use std::sync::{Arc, Mutex};
 use valori_node::config::NodeConfig;
 use valori_node::engine::Engine;
 use valori_kernel::types::vector::FxpVector;
-use valori_kernel::types::scalar::FxpScalar;
 use valori_kernel::types::id::RecordId;
+use valori_kernel::fxp::ops::from_f32;
 use valori_kernel::event::KernelEvent;
 use serde_json;  // For metadata serialization
 use hex;  // For hash encoding
@@ -17,7 +17,7 @@ const D: usize = 384;
 const MAX_NODES: usize = 100; 
 const MAX_EDGES: usize = 100;
 
-const SCALE: f32 = 65536.0;
+// f32→Q16.16 conversion is handled by valori_kernel::fxp::ops::from_f32 (single source of truth)
 
 #[pyclass]
 struct ValoriEngine {
@@ -62,8 +62,7 @@ impl ValoriEngine {
         // 1. Convert to Fixed Point
         let mut fxp_vec = FxpVector::<D>::new_zeros();
         for (i, v) in vector.iter().enumerate() {
-            let fixed = (v * SCALE).round().clamp(i32::MIN as f32, i32::MAX as f32) as i32;
-            fxp_vec.data[i] = FxpScalar(fixed);
+            fxp_vec.data[i] = from_f32(*v);
         }
 
         // 2. Determine ID (first free slot) - Must match Kernel's deterministic logic
@@ -112,8 +111,7 @@ impl ValoriEngine {
         // Convert query to FxpVector for kernel search
         let mut fxp_vec = FxpVector::<D>::new_zeros();
         for (i, &v) in vector.iter().enumerate() {
-             let fixed = (v * SCALE).round().clamp(i32::MIN as f32, i32::MAX as f32) as i32;
-             fxp_vec.data[i] = FxpScalar(fixed);
+             fxp_vec.data[i] = from_f32(v);
         }
 
         let mut results = vec![valori_kernel::index::SearchResult::default(); k];
@@ -309,10 +307,175 @@ impl ValoriEngine {
         engine.metadata.set(key, value);
         Ok(())
     }
+
+    /// Atomic insert with proof — single FFI call.
+    ///
+    /// 1. Validates + converts f32 → Q16.16 (from_f32)
+    /// 2. Generates BLAKE3 Merkle proof over Q16.16 integers
+    /// 3. Inserts record with proof hash as Record.metadata
+    /// 4. Returns (record_id, proof_hash_hex)
+    ///
+    /// The proof is event-sourced, snapshot-persisted, and included
+    /// in kernel_state_hash() — it can never be out of sync.
+    #[pyo3(signature = (vector, tag))]
+    fn insert_with_proof(&self, vector: Vec<f32>, tag: u64) -> PyResult<(u32, String)> {
+        if vector.len() != D {
+            return Err(pyo3::exceptions::PyValueError::new_err(format!("Expected {} dims", D)));
+        }
+
+        // 1. Validate range + convert to Q16.16
+        let mut fxp_vec = FxpVector::<D>::new_zeros();
+        let mut fixed_values = Vec::with_capacity(D);
+        for (i, &f) in vector.iter().enumerate() {
+            if f < -32767.0 || f > 32767.0 {
+                return Err(pyo3::exceptions::PyValueError::new_err(format!(
+                    "Float at index {} ({}) outside valid range [-32767.0, 32767.0]", i, f
+                )));
+            }
+            let scalar = from_f32(f);
+            fxp_vec.data[i] = scalar;
+            fixed_values.push(scalar.0);
+        }
+
+        // 2. Generate Merkle proof over Q16.16 integers
+        let proof_bytes = generate_proof_bytes(&fixed_values);
+        let proof_hex = hex::encode(&proof_bytes);
+
+        // 3. Insert with proof as Record.metadata (event-sourced)
+        let mut engine = self.inner.lock().unwrap();
+
+        let mut id_val = None;
+        for i in 0..MAX_RECORDS {
+            let rid = RecordId(i as u32);
+            if engine.state.get_record(rid).is_none() {
+                id_val = Some(rid);
+                break;
+            }
+        }
+
+        let rid = id_val.ok_or_else(|| {
+            pyo3::exceptions::PyRuntimeError::new_err("Capacity Exceeded")
+        })?;
+
+        if let Some(ref mut committer) = engine.event_committer {
+            let event = KernelEvent::InsertRecord {
+                id: rid,
+                vector: fxp_vec,
+                metadata: Some(proof_bytes),  // ← proof baked into record
+                tag,
+            };
+            match committer.commit_event(event.clone()) {
+                Ok(_) => {
+                    engine.apply_committed_event(&event).map_err(|e| {
+                        pyo3::exceptions::PyRuntimeError::new_err(format!("Apply failed: {:?}", e))
+                    })?;
+                    Ok((rid.0, proof_hex))
+                }
+                Err(e) => Err(pyo3::exceptions::PyRuntimeError::new_err(
+                    format!("Commit failed: {:?}", e)
+                )),
+            }
+        } else {
+            Err(pyo3::exceptions::PyRuntimeError::new_err("Event Log not initialized"))
+        }
+    }
+}
+
+// ============================================================================
+// Bridge Functions — Standalone pyfunctions for deterministic proof generation
+// ============================================================================
+
+/// Convert float embeddings to Q16.16 fixed-point integers.
+///
+/// Uses the kernel's from_f32() — single source of truth.
+/// Rejects values outside [-32767.0, 32767.0] (Q16.16 safe range).
+#[pyfunction]
+fn ingest_embedding(floats: Vec<f32>) -> PyResult<Vec<i32>> {
+    for (i, &f) in floats.iter().enumerate() {
+        if f < -32767.0 || f > 32767.0 {
+            return Err(pyo3::exceptions::PyValueError::new_err(format!(
+                "Float at index {} ({}) outside valid range [-32767.0, 32767.0]. \
+                 Normalize before ingestion.",
+                i, f
+            )));
+        }
+    }
+
+    let fixed: Vec<i32> = floats.iter().map(|&f| from_f32(f).0).collect();
+    Ok(fixed)
+}
+
+/// Internal helper — generates Merkle proof as raw bytes.
+/// Single source of truth for Merkle logic.
+/// Used by both generate_proof() (hex output) and insert_with_proof() (Record.metadata).
+fn generate_proof_bytes(fixed_values: &[i32]) -> Vec<u8> {
+    let leaves: Vec<[u8; 32]> = fixed_values
+        .iter()
+        .enumerate()
+        .map(|(pos, &val)| {
+            let mut buf = [0u8; 8];
+            buf[..4].copy_from_slice(&(pos as u32).to_le_bytes());
+            buf[4..].copy_from_slice(&val.to_le_bytes());
+
+            let mut hasher = blake3::Hasher::new();
+            hasher.update(&buf);
+            *hasher.finalize().as_bytes()
+        })
+        .collect();
+
+    merkle_root(&leaves).to_vec()
+}
+
+/// Build a position-aware Merkle tree over Q16.16 integers.
+///
+/// Each leaf = BLAKE3(position_u32_le || value_i32_le).
+/// Returns the root hash as a hex string.
+/// Same BLAKE3 crate the kernel uses — zero divergence possible.
+#[pyfunction]
+fn generate_proof(fixed_values: Vec<i32>) -> PyResult<String> {
+    if fixed_values.is_empty() {
+        return Err(pyo3::exceptions::PyValueError::new_err(
+            "Cannot generate proof for empty vector"
+        ));
+    }
+    Ok(hex::encode(generate_proof_bytes(&fixed_values)))
+}
+
+/// Standard binary Merkle tree. Odd leaf: hashed with itself.
+fn merkle_root(leaves: &[[u8; 32]]) -> [u8; 32] {
+    if leaves.len() == 1 {
+        return leaves[0];
+    }
+
+    let next_level: Vec<[u8; 32]> = leaves
+        .chunks(2)
+        .map(|pair| {
+            let mut hasher = blake3::Hasher::new();
+            hasher.update(&pair[0]);
+            hasher.update(pair.get(1).unwrap_or(&pair[0]));
+            *hasher.finalize().as_bytes()
+        })
+        .collect();
+
+    merkle_root(&next_level)
+}
+
+/// Verify a float embedding against a claimed proof hash.
+///
+/// Full pipeline in Rust: f32 → Q16.16 → Merkle → compare.
+/// No Python math involved.
+#[pyfunction]
+fn verify_embedding(floats: Vec<f32>, claimed_hash: String) -> PyResult<bool> {
+    let fixed = ingest_embedding(floats)?;
+    let computed_hash = generate_proof(fixed)?;
+    Ok(computed_hash == claimed_hash)
 }
 
 #[pymodule]
 fn valori_ffi(_py: Python, m: &Bound<'_, PyModule>) -> PyResult<()> {
     m.add_class::<ValoriEngine>()?;
+    m.add_function(wrap_pyfunction!(ingest_embedding, m)?)?;
+    m.add_function(wrap_pyfunction!(generate_proof, m)?)?;
+    m.add_function(wrap_pyfunction!(verify_embedding, m)?)?;
     Ok(())
 }