research(nightly): CoDEQ streaming quantizer — kd-tree median-split with O(1) updates (ADR-193)

Cargo.toml

@@ -18,6 +18,8 @@ exclude = ["crates/micro-hnsw-wasm", "crates/ruvector-hyperbolic-hnsw", "crates/
     # land in iters 92-97.
     "crates/ruos-thermal"]
 members = [
+    "crates/ruvector-codeq",
+    "crates/ruvector-streaming-hnsw",
     "crates/ruvector-acorn",
     "crates/ruvector-acorn-wasm",
     "crates/ruvector-rabitq",

crates/ruvector-codeq/Cargo.toml

@@ -0,0 +1,25 @@
+[package]
+name = "ruvector-codeq"
+version.workspace = true
+edition.workspace = true
+rust-version.workspace = true
+license.workspace = true
+authors.workspace = true
+repository.workspace = true
+description = "CoDEQ: Consistent Dynamic Efficient Quantizer — kd-tree median-split quantization with O(1)-bounded streaming inserts/deletes for ruvector (arXiv:2512.18335)"
+
+[[bin]]
+name = "codeq-demo"
+path = "src/main.rs"
+
+[[bench]]
+name = "codeq_bench"
+harness = false
+
+[dependencies]
+rand = { workspace = true }
+rand_distr = { workspace = true }
+thiserror = { workspace = true }
+
+[dev-dependencies]
+criterion = { workspace = true }

crates/ruvector-codeq/benches/codeq_bench.rs

@@ -0,0 +1,53 @@
+use criterion::{criterion_group, criterion_main, BenchmarkId, Criterion};
+use rand::SeedableRng;
+use rand_distr::{Distribution, Normal};
+use ruvector_codeq::{CoDEQIndex, recall_at_k};
+use ruvector_codeq::pq_baseline::{FlatL2IndexCoDEQ, StaticPqIndex};
+
+fn make_vecs(n: usize, dim: usize, seed: u64) -> Vec<(u64, Vec<f32>)> {
+    let mut rng = rand::rngs::StdRng::seed_from_u64(seed);
+    let dist = Normal::new(0.0_f32, 1.0).unwrap();
+    (0..n as u64)
+        .map(|id| (id, (0..dim).map(|_| dist.sample(&mut rng)).collect()))
+        .collect()
+}
+
+fn bench_search(c: &mut Criterion) {
+    let dim = 128;
+    let n = 2_000;
+    let k = 10;
+    let data = make_vecs(n, dim, 42);
+    let queries = make_vecs(20, dim, 99);
+
+    let flat = FlatL2IndexCoDEQ::from_vecs(data.clone()).unwrap();
+    let pq   = StaticPqIndex::build(&data, 8, 64, 10).unwrap();
+    let codeq = CoDEQIndex::from_vecs(&data, 8, 42).unwrap();
+
+    let mut g = c.benchmark_group("codeq_search");
+    g.bench_function("FlatL2", |b| b.iter(|| {
+        for (_qid, qv) in &queries { let _ = flat.search(qv, k); }
+    }));
+    g.bench_function("StaticPQ", |b| b.iter(|| {
+        for (_qid, qv) in &queries { let _ = pq.search_adc(qv, k); }
+    }));
+    g.bench_function("CoDEQ", |b| b.iter(|| {
+        for (_qid, qv) in &queries { let _ = codeq.search_adc(qv, k); }
+    }));
+    g.finish();
+}
+
+fn bench_insert(c: &mut Criterion) {
+    let dim = 128;
+    let data = make_vecs(1_000, dim, 1);
+    let new_vec = make_vecs(1, dim, 2)[0].1.clone();
+
+    c.bench_function("CoDEQ_streaming_insert", |b| {
+        b.iter(|| {
+            let mut idx = CoDEQIndex::from_vecs(&data, 8, 42).unwrap();
+            idx.insert(99999, new_vec.clone()).unwrap();
+        });
+    });
+}
+
+criterion_group!(benches, bench_search, bench_insert);
+criterion_main!(benches);

crates/ruvector-codeq/src/dist.rs

@@ -0,0 +1,26 @@
+/// Squared Euclidean distance — the inner loop of every ANN search.
+#[inline]
+pub fn l2_sq(a: &[f32], b: &[f32]) -> f32 {
+    a.iter().zip(b).map(|(x, y)| (x - y) * (x - y)).sum()
+}
+
+/// Dot product (used in ADC asymmetric distance estimation).
+#[inline]
+pub fn dot(a: &[f32], b: &[f32]) -> f32 {
+    a.iter().zip(b).map(|(x, y)| x * y).sum()
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn l2_sq_known() {
+        assert!((l2_sq(&[0.0, 0.0], &[3.0, 4.0]) - 25.0).abs() < 1e-5);
+    }
+
+    #[test]
+    fn dot_orthogonal() {
+        assert!(dot(&[1.0, 0.0], &[0.0, 1.0]).abs() < 1e-6);
+    }
+}

crates/ruvector-codeq/src/error.rs

@@ -0,0 +1,15 @@
+use thiserror::Error;
+
+#[derive(Debug, Error)]
+pub enum CoDEQError {
+    #[error("empty dataset")]
+    EmptyDataset,
+    #[error("dimension mismatch: expected {expected}, got {actual}")]
+    DimMismatch { expected: usize, actual: usize },
+    #[error("k ({k}) exceeds collection size ({n})")]
+    KTooLarge { k: usize, n: usize },
+    #[error("id {0} not found")]
+    IdNotFound(u64),
+    #[error("bits must be 1–8, got {0}")]
+    InvalidBits(u8),
+}