gqlite 1.5.0 → 1.7.0

data/ext/db-index/src/hnsw/implementation.rs

@@ -0,0 +1,1517 @@
+use super::error::Error;
+use super::error::Result;
+use super::graph_store::GraphStoreRead;
+use super::graph_store::GraphStoreWrite;
+use super::id::NodeId;
+use super::vector::VectorFamily;
+use super::vector::VectorRef;
+use super::vector::VectorView;
+use crate::hnsw::metric::Metric;
+use crate::hnsw::vectors::VectorStore;
+use crate::hnsw::vectors::VectorStoreMut;
+use ahash::HashSetExt;
+use ordered_float::OrderedFloat;
+use std::collections::BinaryHeap;
+use tracing::warn;
+
+fn splitmix64(mut x: u64) -> u64
+{
+  x = x.wrapping_add(0x9E3779B97F4A7C15);
+  x = (x ^ (x >> 30)).wrapping_mul(0xBF58476D1CE4E5B9);
+  x = (x ^ (x >> 27)).wrapping_mul(0x94D049BB133111EB);
+  x ^ (x >> 31)
+}
+
+pub(crate) fn hash_level(seed: u64, node_id: u32, mult: f64) -> i32
+{
+  let h = splitmix64(seed ^ ((node_id as u64) << 1 | 1));
+  let u = ((h >> 11) + 1) as f64 / (1u64 << 53) as f64;
+  (-u.ln() * mult) as i32
+}
+
+#[derive(Debug, Clone, PartialEq, serde::Serialize, serde::Deserialize)]
+pub struct HnswConfig
+{
+  pub dim: usize,
+  pub max_nodes: usize,
+  pub m: usize,
+  pub ef_construction: usize,
+  pub ef_search: usize,
+  pub seed: u64,
+}
+
+impl HnswConfig
+{
+  pub fn new(dim: usize, max_nodes: usize) -> Self
+  {
+    Self {
+      dim,
+      max_nodes,
+      m: 16,
+      ef_construction: 200,
+      ef_search: 50,
+      seed: 100,
+    }
+  }
+
+  pub fn m(mut self, m: usize) -> Self
+  {
+    self.m = m;
+    self
+  }
+
+  pub fn ef_construction(mut self, ef: usize) -> Self
+  {
+    self.ef_construction = ef;
+    self
+  }
+
+  pub fn ef_search(mut self, ef: usize) -> Self
+  {
+    self.ef_search = ef;
+    self
+  }
+
+  pub fn seed(mut self, seed: u64) -> Self
+  {
+    self.seed = seed;
+    self
+  }
+}
+
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub enum SetOutcome
+{
+  Inserted,
+  Updated,
+  Resurrected,
+}
+
+#[derive(Debug, Clone, PartialEq)]
+pub struct SearchHit<K>
+{
+  pub key: K,
+  pub distance: f32,
+}
+
+pub struct HnswIndex<M>
+where
+  M: Metric,
+{
+  metric: M,
+  cfg: HnswConfig,
+  max_m: usize,
+  max_m0: usize,
+  mult: f64,
+  ef_construction: usize,
+}
+
+impl<M> HnswIndex<M>
+where
+  M: Metric,
+{
+  pub fn new(metric: M, mut cfg: HnswConfig) -> Self
+  {
+    assert!(cfg.max_nodes <= u32::MAX as usize);
+    assert!(cfg.dim > 0, "dim must be > 0");
+    assert!(cfg.m >= 2, "m must be >= 2");
+
+    let m = if cfg.m <= 10_000
+    {
+      cfg.m
+    }
+    else
+    {
+      warn!("m={} exceeds 10000; capping to 10000", cfg.m);
+      10_000
+    };
+    cfg.m = m;
+
+    let max_m = m;
+    let max_m0 = m * 2;
+    let ef_construction = cfg.ef_construction.max(m);
+    cfg.ef_construction = ef_construction;
+
+    let mult = 1.0 / (m as f64).ln();
+
+    Self {
+      metric,
+      cfg,
+      max_m,
+      max_m0,
+      mult,
+      ef_construction,
+    }
+  }
+
+  pub fn dim(&self) -> usize
+  {
+    self.cfg.dim
+  }
+
+  pub fn m(&self) -> usize
+  {
+    self.cfg.m
+  }
+
+  pub fn ef_construction(&self) -> usize
+  {
+    self.ef_construction
+  }
+
+  pub fn max_nodes(&self) -> usize
+  {
+    self.cfg.max_nodes
+  }
+
+  pub fn metric(&self) -> &M
+  {
+    &self.metric
+  }
+
+  pub fn config(&self) -> &HnswConfig
+  {
+    &self.cfg
+  }
+
+  fn level_for_key<K: std::hash::Hash>(&self, key: &K) -> i32
+  {
+    // Derive level from key hash, not node id, so the level is determined before
+    // allocation. Each node gets its own level assignment based on its key's hash.
+    let key_hash = ahash::RandomState::with_seeds(self.cfg.seed, 0, 0, 0).hash_one(key);
+    hash_level(self.cfg.seed, key_hash as u32, self.mult)
+  }
+
+  pub fn insert<K, G, V>(
+    &self,
+    graph: &mut G,
+    vectors: &mut V,
+    key: K,
+    vector: <M::Family as VectorFamily>::Ref<'_>,
+  ) -> Result<()>
+  where
+    K: Eq + std::hash::Hash + Clone + Send + Sync + 'static,
+    G: GraphStoreWrite<K>,
+    V: VectorStoreMut<Family = M::Family>,
+    G::Error: Into<Error>,
+  {
+    if vector.len() != self.cfg.dim
+    {
+      return Err(Error::DimensionMismatch {
+        expected: self.cfg.dim,
+        actual: vector.len(),
+      });
+    }
+
+    if graph.node_of(&key).map_err(|e| e.into())?.is_some()
+    {
+      return Err(Error::KeyAlreadyExists);
+    }
+
+    let level = self.level_for_key(&key);
+    let node = graph.insert_node(key, level).map_err(|e| e.into())?;
+
+    // Rollback if vector write fails
+    if let Err(e) = vectors.set(node, vector)
+    {
+      let _ = graph.remove_node(node).map_err(|e2| e2.into());
+      return Err(e);
+    }
+
+    // Rollback if graph linking fails
+    if let Err(e) = self.add_point_at_level(graph, vectors, node, level)
+    {
+      let _ = graph.remove_node(node).map_err(|e2| e2.into());
+      return Err(e);
+    }
+
+    Ok(())
+  }
+
+  pub fn set<K, G, V>(
+    &self,
+    graph: &mut G,
+    vectors: &mut V,
+    key: K,
+    vector: <M::Family as VectorFamily>::Ref<'_>,
+  ) -> Result<SetOutcome>
+  where
+    K: Eq + std::hash::Hash + Clone + Send + Sync + 'static,
+    G: GraphStoreWrite<K>,
+    V: VectorStoreMut<Family = M::Family>,
+    G::Error: Into<Error>,
+  {
+    if vector.len() != self.cfg.dim
+    {
+      return Err(Error::DimensionMismatch {
+        expected: self.cfg.dim,
+        actual: vector.len(),
+      });
+    }
+
+    if let Some(node) = graph.node_of(&key).map_err(|e| e.into())?
+    {
+      vectors.set(node, vector)?;
+      self.update_point(graph, vectors, node)?;
+      return Ok(SetOutcome::Updated);
+    }
+
+    let level = self.level_for_key(&key);
+    let node = graph.insert_node(key, level).map_err(|e| e.into())?;
+
+    // Rollback if vector write fails
+    if let Err(e) = vectors.set(node, vector)
+    {
+      let _ = graph.remove_node(node).map_err(|e2| e2.into());
+      return Err(e);
+    }
+
+    // Rollback if graph linking fails
+    if let Err(e) = self.add_point_at_level(graph, vectors, node, level)
+    {
+      let _ = graph.remove_node(node).map_err(|e2| e2.into());
+      return Err(e);
+    }
+
+    Ok(SetOutcome::Inserted)
+  }
+
+  pub fn delete<K, G>(&self, graph: &mut G, key: &K) -> Result<bool>
+  where
+    K: Eq + std::hash::Hash + Clone + Send + Sync + 'static,
+    G: GraphStoreWrite<K>,
+    G::Error: Into<Error>,
+  {
+    let Some(node) = graph.node_of(key).map_err(|e| e.into())?
+    else
+    {
+      return Ok(false);
+    };
+
+    let entry_point_data = graph.entry_point().map_err(|e| e.into())?;
+
+    graph.remove_node(node).map_err(|e| e.into())?;
+
+    // If we deleted the entry point, find a new one
+    if let Some((ep, _)) = entry_point_data
+    {
+      if ep == node
+      {
+        let node_count = graph.node_count().map_err(|e| e.into())?;
+        let mut best_level = -1i32;
+        let mut best_node = None;
+
+        // Scan all nodes to find the highest-level survivor
+        for i in 0..node_count
+        {
+          let test_node = NodeId::new(i as u32);
+          if graph.contains(test_node).map_err(|e| e.into())?
+          {
+            let level = graph.level(test_node).map_err(|e| e.into())?;
+            if level > best_level
+            {
+              best_level = level;
+              best_node = Some(test_node);
+            }
+          }
+        }
+
+        let new_ep = best_node.map(|n| (n, best_level));
+        graph.set_entry_point(new_ep).map_err(|e| e.into())?;
+      }
+    }
+
+    Ok(true)
+  }
+
+  pub fn search<K, G, V>(
+    &self,
+    graph: &G,
+    vectors: &V,
+    query: <M::Family as VectorFamily>::Ref<'_>,
+    k: usize,
+    ef_search: Option<usize>,
+    filter: Option<&dyn Fn(&K) -> bool>,
+  ) -> Result<Vec<SearchHit<K>>>
+  where
+    K: Eq + std::hash::Hash + Clone + Send + Sync + 'static,
+    G: GraphStoreRead<K>,
+    V: VectorStore<Family = M::Family>,
+    G::Error: Into<Error>,
+  {
+    if query.len() != self.cfg.dim
+    {
+      return Err(Error::DimensionMismatch {
+        expected: self.cfg.dim,
+        actual: query.len(),
+      });
+    }
+
+    let ef = std::cmp::max(k + 1, ef_search.unwrap_or(self.cfg.ef_search));
+
+    let (entry, max_level) = graph
+      .entry_point()
+      .map_err(|e| e.into())?
+      .ok_or(Error::EmptyIndex)?;
+    let node_count = graph.node_count().map_err(|e| e.into())?;
+    // TODO: visited pool / epoch tags — currently `node_count` is total ever inserted and never shrinks
+    let mut visited = vec![false; node_count];
+
+    let mut curr = entry;
+    let mut curdist = self.distance_query_to_node(graph, vectors, query, curr)?;
+
+    // Traverse upper layers to find better starting point
+    for level in (1..=max_level.max(0) as usize).rev()
+    {
+      let mut changed = true;
+      while changed
+      {
+        changed = false;
+        let mut neighbors = Vec::new();
+        graph
+          .neighbors(curr, level, &mut neighbors)
+          .map_err(|e| e.into())?;
+        for cand in neighbors
+        {
+          if !graph.contains(cand).map_err(|e| e.into())?
+          {
+            continue;
+          }
+          let d = self.distance_query_to_node(graph, vectors, query, cand)?;
+          if d < curdist
+          {
+            curdist = d;
+            curr = cand;
+            changed = true;
+          }
+        }
+      }
+    }
+
+    // Search base layer
+    let top_candidates =
+      self.search_base_layer(graph, vectors, curr, query, 0, ef, &mut visited, filter)?;
+
+    let mut result: Vec<(OrderedFloat<f32>, K)> = Vec::new();
+    for (dist, node) in top_candidates.into_sorted_vec()
+    {
+      if result.len() >= k
+      {
+        break;
+      }
+      if !graph.contains(node).map_err(|e| e.into())?
+      {
+        continue;
+      }
+      if let Some(key) = graph.key_of(node).map_err(|e| e.into())?
+      {
+        let allowed = filter.map(|f| f(&key)).unwrap_or(true);
+        if allowed
+        {
+          result.push((dist, key));
+        }
+      }
+    }
+
+    let mut hits = Vec::new();
+    for (dist, key) in result
+    {
+      hits.push(SearchHit {
+        key,
+        distance: dist.0,
+      });
+    }
+    Ok(hits)
+  }
+
+  #[allow(clippy::too_many_arguments)]
+  fn search_base_layer<K, G, V>(
+    &self,
+    graph: &G,
+    vectors: &V,
+    ep: NodeId,
+    query: <M::Family as VectorFamily>::Ref<'_>,
+    layer: usize,
+    ef: usize,
+    visited: &mut [bool],
+    filter: Option<&dyn Fn(&K) -> bool>,
+  ) -> Result<BinaryHeap<(OrderedFloat<f32>, NodeId)>>
+  where
+    K: Eq + std::hash::Hash + Clone + Send + Sync + 'static,
+    G: GraphStoreRead<K>,
+    V: VectorStore<Family = M::Family>,
+    G::Error: Into<Error>,
+  {
+    let mut top_candidates: BinaryHeap<(OrderedFloat<f32>, NodeId)> = BinaryHeap::new();
+    let mut candidate_set: BinaryHeap<(OrderedFloat<f32>, NodeId)> = BinaryHeap::new();
+
+    let mut lower_bound;
+    let ep_key = graph.key_of(ep).map_err(|e| e.into())?;
+    let ep_allowed = if let Some(key) = ep_key
+    {
+      filter.map(|f| f(&key)).unwrap_or(true)
+    }
+    else
+    {
+      false
+    };
+
+    if graph.contains(ep).map_err(|e| e.into())? && ep_allowed
+    {
+      let dist = self.distance_query_to_node(graph, vectors, query, ep)?;
+      lower_bound = dist;
+      top_candidates.push((OrderedFloat(dist), ep));
+      candidate_set.push((OrderedFloat(-dist), ep));
+    }
+    else
+    {
+      lower_bound = f32::INFINITY;
+      candidate_set.push((OrderedFloat(-lower_bound), ep));
+    }
+
+    visited[ep.as_usize()] = true;
+
+    while let Some((neg_dist, cur)) = candidate_set.pop()
+    {
+      let cur_dist = -neg_dist.0;
+      if cur_dist > lower_bound && top_candidates.len() == ef
+      {
+        break;
+      }
+
+      let mut neighbors = Vec::new();
+      graph
+        .neighbors(cur, layer, &mut neighbors)
+        .map_err(|e| e.into())?;
+
+      for cand in neighbors
+      {
+        if visited[cand.as_usize()]
+        {
+          continue;
+        }
+        visited[cand.as_usize()] = true;
+
+        if !graph.contains(cand).map_err(|e| e.into())?
+        {
+          continue;
+        }
+
+        let dist = self.distance_query_to_node(graph, vectors, query, cand)?;
+        let should_consider = top_candidates.len() < ef || lower_bound > dist;
+        if !should_consider
+        {
+          continue;
+        }
+
+        candidate_set.push((OrderedFloat(-dist), cand));
+
+        let cand_key = graph.key_of(cand).map_err(|e| e.into())?;
+        let cand_allowed = if let Some(key) = cand_key
+        {
+          filter.map(|f| f(&key)).unwrap_or(true)
+        }
+        else
+        {
+          false
+        };
+
+        if cand_allowed
+        {
+          top_candidates.push((OrderedFloat(dist), cand));
+        }
+
+        while top_candidates.len() > ef
+        {
+          top_candidates.pop();
+        }
+        if let Some((worst, _)) = top_candidates.peek()
+        {
+          lower_bound = worst.0;
+        }
+      }
+    }
+
+    Ok(top_candidates)
+  }
+
+  fn distance_query_to_node<K, G, V>(
+    &self,
+    _graph: &G,
+    vectors: &V,
+    query: <M::Family as VectorFamily>::Ref<'_>,
+    node: NodeId,
+  ) -> Result<f32>
+  where
+    K: Eq + std::hash::Hash + Clone + Send + Sync + 'static,
+    G: GraphStoreRead<K>,
+    V: VectorStore<Family = M::Family>,
+    G::Error: Into<Error>,
+  {
+    let node_vec = vectors
+      .vector(node)
+      .ok_or_else(|| Error::InvalidIndexFormat("vector not found".to_string()))?;
+    Ok(self.metric.distance(query, node_vec.view()))
+  }
+
+  fn distance_between_nodes<K, G, V>(
+    &self,
+    _graph: &G,
+    vectors: &V,
+    a: NodeId,
+    b: NodeId,
+  ) -> Result<f32>
+  where
+    K: Eq + std::hash::Hash + Clone + Send + Sync + 'static,
+    G: GraphStoreRead<K>,
+    V: VectorStore<Family = M::Family>,
+    G::Error: Into<Error>,
+  {
+    let a_vec = vectors
+      .vector(a)
+      .ok_or_else(|| Error::InvalidIndexFormat("vector a not found".to_string()))?;
+    let b_vec = vectors
+      .vector(b)
+      .ok_or_else(|| Error::InvalidIndexFormat("vector b not found".to_string()))?;
+    Ok(self.metric.distance(a_vec.view(), b_vec.view()))
+  }
+
+  fn get_neighbors_by_heuristic2<K, G, V>(
+    &self,
+    graph: &G,
+    vectors: &V,
+    top_candidates: &mut BinaryHeap<(OrderedFloat<f32>, NodeId)>,
+    m: usize,
+  ) -> Result<()>
+  where
+    K: Eq + std::hash::Hash + Clone + Send + Sync + 'static,
+    G: GraphStoreRead<K>,
+    V: VectorStore<Family = M::Family>,
+    G::Error: Into<Error>,
+  {
+    if top_candidates.len() < m
+    {
+      return Ok(());
+    }
+
+    let mut queue_closest: BinaryHeap<(OrderedFloat<f32>, NodeId)> = BinaryHeap::new();
+    while let Some((dist, id)) = top_candidates.pop()
+    {
+      queue_closest.push((OrderedFloat(-dist.0), id));
+    }
+
+    let mut return_list: Vec<(OrderedFloat<f32>, NodeId)> = Vec::with_capacity(m);
+    while let Some((neg_dist_to_query, cur_id)) = queue_closest.pop()
+    {
+      if return_list.len() >= m
+      {
+        break;
+      }
+      let dist_to_query = -neg_dist_to_query.0;
+
+      let mut good = true;
+      for &(_, selected_id) in &return_list
+      {
+        let cur_dist = self.distance_between_nodes(graph, vectors, selected_id, cur_id)?;
+        if cur_dist < dist_to_query
+        {
+          good = false;
+          break;
+        }
+      }
+
+      if good
+      {
+        return_list.push((neg_dist_to_query, cur_id));
+      }
+    }
+
+    for (neg_dist, id) in return_list
+    {
+      top_candidates.push((OrderedFloat(-neg_dist.0), id));
+    }
+    Ok(())
+  }
+
+  fn mutually_connect_new_element<K, G, V>(
+    &self,
+    graph: &mut G,
+    vectors: &V,
+    node: NodeId,
+    mut top_candidates: BinaryHeap<(OrderedFloat<f32>, NodeId)>,
+    level: usize,
+    _is_update: bool,
+  ) -> Result<NodeId>
+  where
+    K: Eq + std::hash::Hash + Clone + Send + Sync + 'static,
+    G: GraphStoreWrite<K>,
+    V: VectorStore<Family = M::Family>,
+    G::Error: Into<Error>,
+  {
+    let cap = if level == 0 { self.max_m0 } else { self.max_m };
+    self.get_neighbors_by_heuristic2(graph, vectors, &mut top_candidates, self.cfg.m)?;
+    if top_candidates.len() > self.cfg.m
+    {
+      return Err(Error::InvalidIndexFormat(
+        "heuristic returned more than m candidates".to_string(),
+      ));
+    }
+
+    let mut selected: Vec<NodeId> = Vec::with_capacity(self.cfg.m);
+    while let Some((_dist, id)) = top_candidates.pop()
+    {
+      selected.push(id);
+    }
+
+    let next_entry = *selected
+      .last()
+      .ok_or_else(|| Error::InvalidIndexFormat("empty selected neighbor list".to_string()))?;
+
+    for &neighbor in &selected
+    {
+      let neighbor_level = graph.level(neighbor).map_err(|e| e.into())?;
+      if level > neighbor_level.max(0) as usize
+      {
+        return Err(Error::InvalidIndexFormat(
+          "trying to link on a non-existent level".to_string(),
+        ));
+      }
+    }
+
+    graph
+      .set_neighbors(node, level, &selected)
+      .map_err(|e| e.into())?;
+    self.connect_backlinks(graph, vectors, node, &selected, level)?;
+
+    if selected.len() > cap
+    {
+      return Err(Error::InvalidIndexFormat(
+        "too many selected neighbors".to_string(),
+      ));
+    }
+
+    Ok(next_entry)
+  }
+
+  fn connect_backlinks<K, G, V>(
+    &self,
+    graph: &mut G,
+    vectors: &V,
+    node: NodeId,
+    selected: &[NodeId],
+    level: usize,
+  ) -> Result<()>
+  where
+    K: Eq + std::hash::Hash + Clone + Send + Sync + 'static,
+    G: GraphStoreWrite<K>,
+    V: VectorStore<Family = M::Family>,
+    G::Error: Into<Error>,
+  {
+    let mcurmax = if level > 0 { self.max_m } else { self.max_m0 };
+
+    for &neighbor in selected
+    {
+      if neighbor == node
+      {
+        return Err(Error::InvalidIndexFormat(
+          "trying to connect a node to itself".to_string(),
+        ));
+      }
+      let neighbor_level = graph.level(neighbor).map_err(|e| e.into())?;
+      if level > neighbor_level.max(0) as usize
+      {
+        return Err(Error::InvalidIndexFormat(
+          "trying to link on a non-existent level".to_string(),
+        ));
+      }
+
+      let mut existing = Vec::new();
+      graph
+        .neighbors(neighbor, level, &mut existing)
+        .map_err(|e| e.into())?;
+      let sz_other = existing.len();
+      let is_present = existing.contains(&node);
+
+      if sz_other > mcurmax
+      {
+        return Err(Error::InvalidIndexFormat(
+          "bad neighbor list size".to_string(),
+        ));
+      }
+      if is_present
+      {
+        continue;
+      }
+
+      if sz_other < mcurmax
+      {
+        existing.push(node);
+        graph
+          .set_neighbors(neighbor, level, &existing)
+          .map_err(|e| e.into())?;
+        continue;
+      }
+
+      let mut candidates: BinaryHeap<(OrderedFloat<f32>, NodeId)> = BinaryHeap::new();
+      let d_max = self.distance_between_nodes(graph, vectors, node, neighbor)?;
+      candidates.push((OrderedFloat(d_max), node));
+
+      for &existing_neighbor in &existing
+      {
+        let dist = self.distance_between_nodes(graph, vectors, existing_neighbor, neighbor)?;
+        candidates.push((OrderedFloat(dist), existing_neighbor));
+      }
+
+      self.get_neighbors_by_heuristic2(graph, vectors, &mut candidates, mcurmax)?;
+
+      let mut new_neighbors: Vec<NodeId> = Vec::with_capacity(candidates.len());
+      while let Some((_dist, id)) = candidates.pop()
+      {
+        new_neighbors.push(id);
+      }
+
+      graph
+        .set_neighbors(neighbor, level, &new_neighbors)
+        .map_err(|e| e.into())?;
+    }
+
+    Ok(())
+  }
+
+  fn update_point<K, G, V>(&self, graph: &mut G, vectors: &V, node: NodeId) -> Result<()>
+  where
+    K: Eq + std::hash::Hash + Clone + Send + Sync + 'static,
+    G: GraphStoreWrite<K>,
+    V: VectorStore<Family = M::Family>,
+    G::Error: Into<Error>,
+  {
+    let entry_point_data = graph
+      .entry_point()
+      .map_err(|e| e.into())?
+      .ok_or(Error::EmptyIndex)?;
+    let (entry, max_level_copy) = entry_point_data;
+
+    let node_count = graph.node_count().map_err(|e| e.into())?;
+    if entry == node && node_count == 1
+    {
+      return Ok(());
+    }
+
+    let elem_level = graph.level(node).map_err(|e| e.into())?;
+    if elem_level < 0
+    {
+      return Err(Error::InvalidIndexFormat("node level < 0".to_string()));
+    }
+
+    // Use deterministic pseudo-random based on node id and config seed
+    let mut next_random_seed = self.cfg.seed ^ (node.as_u32() as u64);
+    let update_neighbor_probability = 1.0 / (self.cfg.m as f32);
+
+    for layer in 0..=elem_level as usize
+    {
+      let mut s_cand = ahash::HashSet::<NodeId>::new();
+      let mut s_neigh = ahash::HashSet::<NodeId>::new();
+
+      let mut list_one_hop = Vec::new();
+      graph
+        .neighbors(node, layer, &mut list_one_hop)
+        .map_err(|e| e.into())?;
+
+      if list_one_hop.is_empty()
+      {
+        continue;
+      }
+
+      s_cand.insert(node);
+
+      for el_one_hop in list_one_hop
+      {
+        s_cand.insert(el_one_hop);
+
+        // Deterministic random using splitmix64
+        next_random_seed = splitmix64(next_random_seed);
+        let random_val = ((next_random_seed >> 11) as f64 + 1.0) / (1u64 << 53) as f64;
+        if random_val as f32 > update_neighbor_probability
+        {
+          continue;
+        }
+
+        s_neigh.insert(el_one_hop);
+        let mut list_two_hop = Vec::new();
+        graph
+          .neighbors(el_one_hop, layer, &mut list_two_hop)
+          .map_err(|e| e.into())?;
+        for el_two_hop in list_two_hop
+        {
+          s_cand.insert(el_two_hop);
+        }
+      }
+
+      for neigh in s_neigh
+      {
+        let size = if s_cand.contains(&neigh)
+        {
+          s_cand.len().saturating_sub(1)
+        }
+        else
+        {
+          s_cand.len()
+        };
+        if size == 0
+        {
+          continue;
+        }
+
+        let elements_to_keep = self.ef_construction.min(size);
+        let mut candidates: BinaryHeap<(OrderedFloat<f32>, NodeId)> = BinaryHeap::new();
+
+        for cand in s_cand.iter().copied()
+        {
+          if cand == neigh
+          {
+            continue;
+          }
+          let dist = self.distance_between_nodes(graph, vectors, neigh, cand)?;
+          if candidates.len() < elements_to_keep
+          {
+            candidates.push((OrderedFloat(dist), cand));
+          }
+          else if let Some((worst, _)) = candidates.peek()
+          {
+            if dist < worst.0
+            {
+              candidates.pop();
+              candidates.push((OrderedFloat(dist), cand));
+            }
+          }
+        }
+
+        let cap = if layer == 0 { self.max_m0 } else { self.max_m };
+        self.get_neighbors_by_heuristic2(graph, vectors, &mut candidates, cap)?;
+
+        let mut new_neighbors: Vec<NodeId> = Vec::with_capacity(candidates.len());
+        while let Some((_dist, id)) = candidates.pop()
+        {
+          new_neighbors.push(id);
+        }
+        graph
+          .set_neighbors(neigh, layer, &new_neighbors)
+          .map_err(|e| e.into())?;
+      }
+    }
+
+    self.repair_connections_for_update(
+      graph,
+      vectors,
+      entry,
+      node,
+      elem_level as usize,
+      max_level_copy.max(0) as usize,
+    )?;
+
+    Ok(())
+  }
+
+  fn repair_connections_for_update<K, G, V>(
+    &self,
+    graph: &mut G,
+    vectors: &V,
+    entry: NodeId,
+    node: NodeId,
+    node_level: usize,
+    max_level: usize,
+  ) -> Result<()>
+  where
+    K: Eq + std::hash::Hash + Clone + Send + Sync + 'static,
+    G: GraphStoreWrite<K>,
+    V: VectorStore<Family = M::Family>,
+    G::Error: Into<Error>,
+  {
+    let mut curr = entry;
+
+    // Descend to node level if it's below max level
+    if node_level < max_level
+    {
+      let node_vec = vectors.vector(node).ok_or(Error::MissingVector)?;
+      let node_vec = node_vec.view();
+      let mut curdist = self.distance_query_to_node(graph, vectors, node_vec, curr)?;
+      for level in (node_level + 1..=max_level).rev()
+      {
+        let mut changed = true;
+        while changed
+        {
+          changed = false;
+          let mut neighbors = Vec::new();
+          graph
+            .neighbors(curr, level, &mut neighbors)
+            .map_err(|e| e.into())?;
+          for cand in neighbors
+          {
+            let d = self.distance_between_nodes(graph, vectors, node, cand)?;
+            if d < curdist
+            {
+              curdist = d;
+              curr = cand;
+              changed = true;
+            }
+          }
+        }
+      }
+    }
+
+    if node_level > max_level
+    {
+      return Err(Error::InvalidIndexFormat(
+        "node level cannot exceed max level".to_string(),
+      ));
+    }
+
+    let node_vec = vectors.vector(node).ok_or(Error::MissingVector)?;
+    let node_vec = node_vec.view();
+    let node_count = graph.node_count().map_err(|e| e.into())?;
+    let mut visited = vec![false; node_count];
+
+    for level in (0..=node_level).rev()
+    {
+      visited.fill(false);
+      let mut top_candidates = self.search_base_layer(
+        graph,
+        vectors,
+        curr,
+        node_vec,
+        level,
+        self.ef_construction,
+        &mut visited,
+        None,
+      )?;
+
+      let mut filtered: BinaryHeap<(OrderedFloat<f32>, NodeId)> = BinaryHeap::new();
+      while let Some(cand) = top_candidates.pop()
+      {
+        if cand.1 != node
+        {
+          filtered.push(cand);
+        }
+      }
+
+      if !filtered.is_empty()
+      {
+        curr = self.mutually_connect_new_element(graph, vectors, node, filtered, level, true)?;
+      }
+    }
+
+    Ok(())
+  }
+
+  fn add_point_at_level<K, G, V>(
+    &self,
+    graph: &mut G,
+    vectors: &V,
+    node: NodeId,
+    cur_level: i32,
+  ) -> Result<()>
+  where
+    K: Eq + std::hash::Hash + Clone + Send + Sync + 'static,
+    G: GraphStoreWrite<K>,
+    V: VectorStore<Family = M::Family>,
+    G::Error: Into<Error>,
+  {
+    if cur_level < 0
+    {
+      return Err(Error::InvalidIndexFormat("level must be >= 0".to_string()));
+    }
+
+    let entry_point_data = graph.entry_point().map_err(|e| e.into())?;
+
+    let (mut curr_obj, max_level_copy) = match entry_point_data
+    {
+      Some((entry, max_level)) => (Some(entry), max_level),
+      None =>
+      {
+        graph
+          .set_entry_point(Some((node, cur_level)))
+          .map_err(|e| e.into())?;
+        return Ok(());
+      }
+    };
+
+    let node_vec = vectors.vector(node).ok_or(Error::MissingVector)?;
+    let node_vec = node_vec.view();
+
+    if max_level_copy >= 0 && cur_level < max_level_copy
+    {
+      let entry = curr_obj.unwrap();
+      let mut curdist = self.distance_query_to_node(graph, vectors, node_vec, entry)?;
+      let mut curr = entry;
+      for level in ((cur_level + 1) as usize..=max_level_copy as usize).rev()
+      {
+        let mut changed = true;
+        while changed
+        {
+          changed = false;
+          let mut neighbors = Vec::new();
+          graph
+            .neighbors(curr, level, &mut neighbors)
+            .map_err(|e| e.into())?;
+          for cand in neighbors
+          {
+            let d = self.distance_query_to_node(graph, vectors, node_vec, cand)?;
+            if d < curdist
+            {
+              curdist = d;
+              curr = cand;
+              changed = true;
+            }
+          }
+        }
+      }
+      curr_obj = Some(curr);
+    }
+
+    let mut curr_obj = curr_obj.expect("entry checked above");
+    let max_conn_level = usize::min(cur_level.max(0) as usize, max_level_copy.max(0) as usize);
+    let node_count = graph.node_count().map_err(|e| e.into())?;
+
+    let mut selected_per_level: Vec<Vec<NodeId>> = vec![Vec::new(); max_conn_level + 1];
+    let mut visited = vec![false; node_count];
+
+    for level in (0..=max_conn_level).rev()
+    {
+      visited.fill(false);
+      let mut top_candidates = self.search_base_layer(
+        graph,
+        vectors,
+        curr_obj,
+        node_vec,
+        level,
+        self.ef_construction,
+        &mut visited,
+        None,
+      )?;
+
+      // After bug fix for entry point reassignment (Bug 2), this should never
+      // occur: the entry point is always a level-maximal survivor, and
+      // search_base_layer searches from it. Empty candidates would indicate
+      // an invariant violation.
+      if top_candidates.is_empty()
+      {
+        return Err(Error::InvalidIndexFormat(
+          "add_point_at_level: no candidates found at level (entry point invariant violated)"
+            .to_string(),
+        ));
+      }
+
+      self.get_neighbors_by_heuristic2(graph, vectors, &mut top_candidates, self.cfg.m)?;
+      if top_candidates.len() > self.cfg.m
+      {
+        return Err(Error::InvalidIndexFormat(
+          "heuristic returned more than m candidates".to_string(),
+        ));
+      }
+
+      let mut selected: Vec<NodeId> = Vec::with_capacity(self.cfg.m);
+      while let Some((_dist, id)) = top_candidates.pop()
+      {
+        selected.push(id);
+      }
+
+      let next_entry = *selected
+        .last()
+        .ok_or_else(|| Error::InvalidIndexFormat("empty selected neighbor list".to_string()))?;
+
+      for &neighbor in &selected
+      {
+        let neighbor_level = graph.level(neighbor).map_err(|e| e.into())?;
+        if level > neighbor_level.max(0) as usize
+        {
+          return Err(Error::InvalidIndexFormat(
+            "trying to link on a non-existent level".to_string(),
+          ));
+        }
+      }
+
+      graph
+        .set_neighbors(node, level, &selected)
+        .map_err(|e| e.into())?;
+      selected_per_level[level] = selected;
+      curr_obj = next_entry;
+    }
+
+    for level in (0..=max_conn_level).rev()
+    {
+      self.connect_backlinks(graph, vectors, node, &selected_per_level[level], level)?;
+    }
+
+    if cur_level > max_level_copy
+    {
+      graph
+        .set_entry_point(Some((node, cur_level)))
+        .map_err(|e| e.into())?;
+    }
+
+    Ok(())
+  }
+}
+
+// HnswIndex holds only config; all mutable state lives in the graph/vector stores.
+// This function is never called, but will fail to compile if HnswIndex is not Sync.
+#[allow(dead_code)]
+fn assert_hnsw_index_is_sync()
+{
+  fn is_sync<T: Sync>() {}
+  is_sync::<HnswIndex<super::metric::L2>>();
+}
+
+#[cfg(test)]
+mod tests
+{
+  use super::*;
+  use crate::hnsw::metric::L2;
+  use crate::hnsw::simple_store::SimpleGraphStore;
+  use crate::hnsw::vectors::InMemoryVectorStore;
+
+  #[test]
+  fn simple_store_passes_conformance()
+  {
+    crate::hnsw::graph_store::conformance_all::<u128, _>(SimpleGraphStore::<u128>::new);
+  }
+
+  #[test]
+  fn hash_level_is_deterministic_and_seed_sensitive()
+  {
+    let mult = 1.0 / (16f64).ln();
+    assert_eq!(hash_level(100, 7, mult), hash_level(100, 7, mult));
+    let differs = (0..64u32).any(|id| hash_level(100, id, mult) != hash_level(101, id, mult));
+    assert!(
+      differs,
+      "different seeds must produce different level sequences"
+    );
+  }
+
+  #[test]
+  fn hash_level_distribution_matches_exponential()
+  {
+    // P(level >= 1) = 1/m. At n=20_000, m=16: expected 1250, sd ~34.
+    let mult = 1.0 / (16f64).ln();
+    let above = (0..20_000u32)
+      .filter(|&id| hash_level(100, id, mult) >= 1)
+      .count();
+    assert!(
+      (1050..1450).contains(&above),
+      "P(level>=1) should be ~1/16 of 20k, got {above}"
+    );
+  }
+
+  #[test]
+  fn set_and_search_roundtrip_exact_nearest()
+  {
+    let cfg = HnswConfig::new(4, 0);
+    let idx = HnswIndex::new(L2::<f32>::new(), cfg);
+    let mut g = SimpleGraphStore::<u128>::new();
+    let mut vectors = InMemoryVectorStore::<f32>::new(4, 64);
+
+    for (key, v) in [
+      (1u128, [10.0f32, 0.0, 0.0, 0.0]),
+      (2, [0.0, 10.0, 0.0, 0.0]),
+      (3, [0.0, 0.0, 10.0, 0.0]),
+      (5, [0.1, 0.0, 0.0, 0.0]),
+    ]
+    {
+      let _ = idx.set(&mut g, &mut vectors, key, &v).unwrap();
+    }
+
+    let hits = idx
+      .search(&g, &vectors, &[0.05, 0.0, 0.0, 0.0], 2, None, None)
+      .unwrap();
+    assert_eq!(hits[0].key, 5);
+    assert_eq!(hits[1].key, 1);
+  }
+
+  #[test]
+  fn delete_removes_immediately_and_search_excludes()
+  {
+    let cfg = HnswConfig::new(4, 0);
+    let idx = HnswIndex::new(L2::<f32>::new(), cfg);
+    let mut g = SimpleGraphStore::<u128>::new();
+    let mut vectors = InMemoryVectorStore::<f32>::new(4, 64);
+
+    for (key, v) in [
+      (1u128, [1.0f32, 0., 0., 0.]),
+      (2, [2.0, 0., 0., 0.]),
+      (3, [3.0, 0., 0., 0.]),
+    ]
+    {
+      idx.set(&mut g, &mut vectors, key, &v).unwrap();
+    }
+
+    assert!(idx.delete(&mut g, &2u128).unwrap());
+    assert!(
+      !idx.delete(&mut g, &2u128).unwrap(),
+      "second delete returns false"
+    );
+    assert_eq!(g.node_of(&2u128).unwrap(), None);
+
+    let hits = idx
+      .search(&g, &vectors, &[2.0, 0., 0., 0.], 3, None, None)
+      .unwrap();
+    assert_eq!(hits.len(), 2);
+    assert!(!hits.iter().any(|h| h.key == 2));
+  }
+
+  #[test]
+  fn deleting_entry_point_reassigns_and_search_survives()
+  {
+    let cfg = HnswConfig::new(4, 0);
+    let idx = HnswIndex::new(L2::<f32>::new(), cfg);
+    let mut g = SimpleGraphStore::<u128>::new();
+    let mut vectors = InMemoryVectorStore::<f32>::new(4, 64);
+
+    for i in 0..5u128
+    {
+      idx
+        .set(&mut g, &mut vectors, i, &[i as f32, 0., 0., 0.])
+        .unwrap();
+    }
+
+    let (ep, _) = g.entry_point().unwrap().unwrap();
+    let ep_key = g.key_of(ep).unwrap().unwrap();
+    assert!(idx.delete(&mut g, &ep_key).unwrap());
+
+    let (new_ep, _) = g
+      .entry_point()
+      .unwrap()
+      .expect("entry point reassigned, not dangling");
+    assert_ne!(new_ep, ep);
+    assert!(g.contains(new_ep).unwrap());
+
+    let hits = idx
+      .search(&g, &vectors, &[0.0, 0., 0., 0.], 4, None, None)
+      .unwrap();
+    assert_eq!(hits.len(), 4);
+  }
+
+  #[test]
+  fn traversal_through_a_stale_link_is_safe()
+  {
+    let cfg = HnswConfig::new(4, 0);
+    let idx = HnswIndex::new(L2::<f32>::new(), cfg);
+    let mut g = SimpleGraphStore::<u128>::new();
+    let mut vectors = InMemoryVectorStore::<f32>::new(4, 64);
+
+    for i in 0..4u128
+    {
+      idx
+        .set(&mut g, &mut vectors, i, &[i as f32, 0., 0., 0.])
+        .unwrap();
+    }
+
+    let victim = g.node_of(&1u128).unwrap().unwrap();
+    idx.delete(&mut g, &1u128).unwrap();
+
+    // Force a stale link (delete leaves inbound links; make one explicit so
+    // the test doesn't depend on graph shape):
+    let holder = g.node_of(&0u128).unwrap().unwrap();
+    let mut nbrs = Vec::new();
+    g.neighbors(holder, 0, &mut nbrs).unwrap();
+    nbrs.push(victim);
+    g.set_neighbors(holder, 0, &nbrs).unwrap();
+
+    let hits = idx
+      .search(&g, &vectors, &[1.0, 0., 0., 0.], 3, None, None)
+      .unwrap();
+    assert!(
+      !hits.iter().any(|h| h.key == 1),
+      "removed node never surfaces"
+    );
+    assert_eq!(hits.len(), 3);
+  }
+
+  #[test]
+  fn test_config()
+  {
+    let cfg = HnswConfig::new(10, 1000);
+    assert_eq!(cfg.dim, 10);
+    assert_eq!(cfg.max_nodes, 1000);
+  }
+
+  #[test]
+  fn test_hnsw_index_creation()
+  {
+    let index = HnswIndex::new(L2::<f32>::new(), HnswConfig::new(4, 100));
+    assert_eq!(index.dim(), 4);
+    assert_eq!(index.m(), 16);
+    assert_eq!(index.max_nodes(), 100);
+  }
+
+  /// Invariant: levels are derived per-key, so a large insert batch must
+  /// produce a multi-level graph (P(level>=1) = 1/m per node; at n=1000, m=16,
+  /// expected ~60 nodes above level 0, far beyond noise).
+  #[test]
+  fn insert_produces_varying_levels_across_many_nodes()
+  {
+    let cfg = HnswConfig::new(4, 0).m(16).seed(100);
+    let idx = HnswIndex::new(L2::<f32>::new(), cfg);
+    let mut g = SimpleGraphStore::<u128>::new();
+    let mut vectors = InMemoryVectorStore::<f32>::new(4, 2048);
+
+    const N: usize = 1000;
+    for i in 0..N as u128
+    {
+      let v = [i as f32, (i * 7) as f32, (i * 13) as f32, (i * 19) as f32];
+      idx.insert(&mut g, &mut vectors, i, &v).unwrap();
+    }
+
+    let levels: std::collections::HashSet<i32> = (0..N as u32)
+      .map(|raw| g.level(NodeId::from_u32(raw)).unwrap())
+      .collect();
+
+    assert!(
+      levels.len() > 1,
+      "expected multiple distinct levels across {N} real inserts, got only {levels:?} -- \
+       every node received the identical level, meaning hash_level was called with the \
+       same (seed, node_id) pair every time instead of each node's own id"
+    );
+
+    let above_level_0 = (0..N as u32)
+      .filter(|&raw| g.level(NodeId::from_u32(raw)).unwrap() > 0)
+      .count();
+    assert!(
+      above_level_0 > 40,
+      "expected roughly N/m = {} nodes above level 0 at m=16, n={N}, got {above_level_0} -- \
+       far too few for a correctly seeded per-node level assignment",
+      N / 16
+    );
+  }
+
+  /// Invariant: when any node is inserted, if it reaches a level higher than
+  /// the current entry point, the entry point and max_level are updated.
+  /// This ensures max_level advances monotonically as the graph grows.
+  #[test]
+  fn max_level_advances_as_more_nodes_are_inserted()
+  {
+    let cfg = HnswConfig::new(4, 0).m(16).seed(100);
+    let idx = HnswIndex::new(L2::<f32>::new(), cfg);
+    let mut g = SimpleGraphStore::<u128>::new();
+    let mut vectors = InMemoryVectorStore::<f32>::new(4, 1024);
+
+    idx
+      .insert(&mut g, &mut vectors, 0u128, &[0.0, 0.0, 0.0, 0.0])
+      .unwrap();
+    let (_, initial_max_level) = g.entry_point().unwrap().unwrap();
+
+    for i in 1..500u128
+    {
+      let v = [i as f32, (i * 3) as f32, (i * 5) as f32, (i * 11) as f32];
+      idx.insert(&mut g, &mut vectors, i, &v).unwrap();
+    }
+
+    let (_, final_max_level) = g.entry_point().unwrap().unwrap();
+    assert!(
+      final_max_level > initial_max_level,
+      "max_level never advanced past the first-inserted node's own level ({initial_max_level}) \
+       across 499 further inserts -- consistent with every node receiving that same level"
+    );
+  }
+
+  /// Invariant: when the entry point is deleted, the replacement must be a
+  /// level-maximal survivor, so max_level never regresses below the true max.
+  #[test]
+  fn deleting_entry_point_reassigns_to_the_highest_level_survivor()
+  {
+    let cfg = HnswConfig::new(4, 0).m(16).seed(100);
+    let idx = HnswIndex::new(L2::<f32>::new(), cfg);
+    let mut g = SimpleGraphStore::<u128>::new();
+    let mut vectors = InMemoryVectorStore::<f32>::new(4, 1024);
+
+    // Enough nodes to guarantee at least one non-entry-point node reaches
+    // a level >= 1, so "highest surviving level" is a real, checkable claim
+    // rather than everything being tied at level 0.
+    const N: usize = 500;
+    for i in 0..N as u128
+    {
+      let v = [i as f32, (i * 3) as f32, (i * 5) as f32, (i * 11) as f32];
+      idx.insert(&mut g, &mut vectors, i, &v).unwrap();
+    }
+
+    let (entry_before, max_level_before) = g.entry_point().unwrap().unwrap();
+    let entry_key = g.key_of(entry_before).unwrap().unwrap();
+    assert!(
+      max_level_before > 0,
+      "test precondition: need a real multi-level graph to distinguish \
+       'highest survivor' from 'any survivor' -- if this fails, bug 1 is \
+       still present and this test can't isolate bug 2"
+    );
+
+    // Independently compute the true highest-level node among everyone
+    // EXCEPT the entry point, by direct inspection -- this is the ground
+    // truth the delete path's reassignment must match.
+    let mut expected_level = -1i32;
+    let mut expected_node = None;
+    for raw in 0..N as u32
+    {
+      let n = NodeId::from_u32(raw);
+      if n == entry_before || !g.contains(n).unwrap()
+      {
+        continue;
+      }
+      let lvl = g.level(n).unwrap();
+      if lvl > expected_level
+      {
+        expected_level = lvl;
+        expected_node = Some(n);
+      }
+    }
+    let _expected_node = expected_node.expect("graph has more than one node");
+
+    assert!(idx.delete(&mut g, &entry_key).unwrap());
+
+    let (new_entry, new_max_level) = g
+      .entry_point()
+      .unwrap()
+      .expect("entry point must be reassigned, not left empty, when survivors exist");
+
+    // The new entry point must have the maximum level among survivors.
+    assert_eq!(
+      new_max_level, expected_level,
+      "reassigned entry point's level ({new_max_level}) does not match the true \
+       highest level among survivors ({expected_level})"
+    );
+    // Any node at the maximum level is valid, so just verify it exists and has the right level.
+    assert!(g.contains(new_entry).unwrap());
+    assert_eq!(g.level(new_entry).unwrap(), expected_level);
+  }
+
+  /// Adversarial variant: construct a deterministic graph where the
+  /// lowest-numbered surviving node has a LOWER level than a higher-numbered
+  /// survivor. This tests that reassignment picks by level, not by node id.
+  #[test]
+  fn entry_point_reassignment_does_not_prefer_low_node_ids_over_high_levels()
+  {
+    let cfg = HnswConfig::new(4, 0).m(16).seed(100);
+    let idx = HnswIndex::new(L2::<f32>::new(), cfg);
+    let mut g = SimpleGraphStore::<u128>::new();
+
+    // Build a deterministic graph: node 0 (level 0), node 1 (level 2), entry (level 3).
+    let n0 = g.insert_node(0u128, 0).unwrap();
+    let n1 = g.insert_node(1u128, 2).unwrap();
+    let ep = g.insert_node(2u128, 3).unwrap();
+    g.set_entry_point(Some((ep, 3))).unwrap();
+
+    // Delete the entry point.
+    assert!(idx.delete(&mut g, &2u128).unwrap());
+
+    // The new entry point must be node 1 (level 2), not node 0 (level 0).
+    let (new_ep, new_level) = g
+      .entry_point()
+      .unwrap()
+      .expect("entry point must be reassigned when survivors exist");
+
+    assert_eq!(new_level, 2, "entry point should have level 2");
+    assert_eq!(
+      new_ep, n1,
+      "entry point should be the level-2 node, not the level-0 node"
+    );
+
+    let _ = n0; // unused but intentional
+  }
+}