gqlite 1.5.0 → 1.7.0

data/ext/gqlitedb/src/tests/store/vector_index.rs

@@ -0,0 +1,2313 @@
+#[cfg(feature = "redb")]
+mod redb;
+#[cfg(feature = "sqlite")]
+mod sqlite;
+
+#[cfg(feature = "postgres")]
+mod postgres;
+
+use crate::{
+  graph,
+  prelude::*,
+  store::{self, SelectNodeQuery, Store, TransactionBoxable, VectorIndexSpec, VectorMetric},
+};
+
+pub(crate) fn test_vector_operations<S: Store>(store: S)
+{
+  let spec = store::VectorIndexSpec {
+    name: "embeddings".to_string(),
+    dimension: 3,
+    metric: store::VectorMetric::L2,
+    ..Default::default()
+  };
+
+  let mut tx = store.begin_write().unwrap();
+  store.create_vector_index(&mut tx, "default", spec).unwrap();
+  tx.close().unwrap();
+
+  let node1 = graph::Node::new(
+    Some("default".to_string()),
+    graph::Key::default(),
+    graph::labels!("Item"),
+    value::ValueMap::new(),
+  );
+  let node2 = graph::Node::new(
+    Some("default".to_string()),
+    graph::Key::default(),
+    graph::labels!("Item"),
+    value::ValueMap::new(),
+  );
+  let node3 = graph::Node::new(
+    Some("default".to_string()),
+    graph::Key::default(),
+    graph::labels!("Item"),
+    value::ValueMap::new(),
+  );
+
+  let mut tx = store.begin_write().unwrap();
+  store
+    .create_nodes(
+      &mut tx,
+      "default",
+      [node1.clone(), node2.clone(), node3.clone()].iter(),
+    )
+    .unwrap();
+
+  let vector1 = vec![1.0, 0.0, 0.0];
+  let vector2 = vec![0.9, 0.1, 0.0];
+  let vector3 = vec![0.0, 1.0, 0.0];
+
+  store
+    .upsert_vector(
+      &mut tx,
+      "default",
+      "embeddings",
+      node1.key(),
+      &crate::value::Tensor::from_f32_slice(&vector1),
+    )
+    .unwrap();
+  store
+    .upsert_vector(
+      &mut tx,
+      "default",
+      "embeddings",
+      node2.key(),
+      &crate::value::Tensor::from_f32_slice(&vector2),
+    )
+    .unwrap();
+  store
+    .upsert_vector(
+      &mut tx,
+      "default",
+      "embeddings",
+      node3.key(),
+      &crate::value::Tensor::from_f32_slice(&vector3),
+    )
+    .unwrap();
+
+  tx.close().unwrap();
+
+  let mut tx = store.begin_read().unwrap();
+  let query = vec![1.0, 0.0, 0.0];
+  let results = store
+    .vector_search(
+      &mut tx,
+      "default",
+      "embeddings",
+      &crate::value::Tensor::from_f32_slice(&query),
+      2,
+    )
+    .unwrap();
+  tx.close().unwrap();
+
+  assert_eq!(
+    results.len(),
+    2,
+    "Expected 2 results, got {}",
+    results.len()
+  );
+
+  assert_eq!(results[0].node_id, node1.key());
+  assert_eq!(results[1].node_id, node2.key());
+
+  let mut tx = store.begin_read().unwrap();
+  let query2 = vec![0.0, 1.0, 0.0];
+  let results2 = store
+    .vector_search(
+      &mut tx,
+      "default",
+      "embeddings",
+      &crate::value::Tensor::from_f32_slice(&query2),
+      2,
+    )
+    .unwrap();
+  tx.close().unwrap();
+
+  assert_eq!(results2.len(), 2);
+  assert_eq!(results2[0].node_id, node3.key());
+  assert_eq!(results2[1].node_id, node2.key());
+}
+
+pub(crate) fn test_vector_search_returns_results<S: Store>(store: S)
+{
+  let mut tx = store.begin_write().unwrap();
+  store
+    .create_vector_index(
+      &mut tx,
+      "default",
+      VectorIndexSpec {
+        name: "idx".into(),
+        dimension: 3,
+        metric: VectorMetric::Cosine,
+        ..Default::default()
+      },
+    )
+    .unwrap();
+
+  let node = graph::Node::new(
+    Some("default".into()),
+    graph::Key::default(),
+    graph::labels!("Item"),
+    value::ValueMap::new(),
+  );
+
+  store.create_nodes(&mut tx, "default", [&node]).unwrap();
+
+  store
+    .upsert_vector(
+      &mut tx,
+      "default",
+      "idx",
+      node.key(),
+      &crate::value::Tensor::from_f32_slice(&[1.0, 0.0, 0.0]),
+    )
+    .unwrap();
+
+  tx.close().unwrap();
+
+  let mut tx = store.begin_read().unwrap();
+  let results = store
+    .vector_search(
+      &mut tx,
+      "default",
+      "idx",
+      &crate::value::Tensor::from_f32_slice(&[1.0, 0.0, 0.0]),
+      10,
+    )
+    .unwrap();
+
+  assert!(!results.is_empty(), "Vector search returned no results");
+  tx.close().unwrap();
+}
+
+pub(crate) fn test_vector_search_k_limit<S: Store>(store: S)
+{
+  let mut tx = store.begin_write().unwrap();
+  store
+    .create_vector_index(
+      &mut tx,
+      "default",
+      VectorIndexSpec {
+        name: "idx".into(),
+        dimension: 3,
+        metric: VectorMetric::Cosine,
+        ..Default::default()
+      },
+    )
+    .unwrap();
+
+  for i in 0..5
+  {
+    let node = graph::Node::new(
+      Some("default".into()),
+      graph::Key::new(i as u128),
+      graph::labels!("Item"),
+      value::ValueMap::new(),
+    );
+
+    store.create_nodes(&mut tx, "default", [&node]).unwrap();
+
+    let vector = vec![
+      i as f32 * 0.1,
+      (i as f32 + 1.0) * 0.1,
+      (i as f32 + 2.0) * 0.1,
+    ];
+    store
+      .upsert_vector(
+        &mut tx,
+        "default",
+        "idx",
+        node.key(),
+        &crate::value::Tensor::from_f32_slice(&vector),
+      )
+      .unwrap();
+  }
+
+  tx.close().unwrap();
+
+  let mut tx = store.begin_read().unwrap();
+  let results = store
+    .vector_search(
+      &mut tx,
+      "default",
+      "idx",
+      &crate::value::Tensor::from_f32_slice(&[0.5, 0.6, 0.7]),
+      3,
+    )
+    .unwrap();
+
+  assert_eq!(results.len(), 3, "Should return exactly k=3 results");
+  tx.close().unwrap();
+}
+
+pub(crate) fn test_vector_upsert_does_not_duplicate<S: Store>(store: S)
+{
+  let mut tx = store.begin_write().unwrap();
+
+  store
+    .create_vector_index(
+      &mut tx,
+      "default",
+      VectorIndexSpec {
+        name: "idx".into(),
+        dimension: 3,
+        ..Default::default()
+      },
+    )
+    .unwrap();
+
+  let node = graph::Key::new(42);
+
+  store
+    .upsert_vector(
+      &mut tx,
+      "default",
+      "idx",
+      node,
+      &crate::value::Tensor::from_f32_slice(&[1.0, 0.0, 0.0]),
+    )
+    .unwrap();
+
+  store
+    .upsert_vector(
+      &mut tx,
+      "default",
+      "idx",
+      node,
+      &crate::value::Tensor::from_f32_slice(&[0.0, 1.0, 0.0]),
+    )
+    .unwrap();
+
+  tx.close().unwrap();
+
+  let mut tx = store.begin_read().unwrap();
+  let results = store
+    .vector_search(
+      &mut tx,
+      "default",
+      "idx",
+      &crate::value::Tensor::from_f32_slice(&[0.0, 1.0, 0.0]),
+      10,
+    )
+    .unwrap();
+
+  let matches: Vec<_> = results.into_iter().filter(|r| r.node_id == node).collect();
+
+  assert_eq!(
+    matches.len(),
+    1,
+    "duplicate entries detected (rowid instability)"
+  );
+  tx.close().unwrap();
+}
+
+pub(crate) fn test_multiple_indexes_do_not_conflict<S: Store>(store: S)
+{
+  let mut tx = store.begin_write().unwrap();
+
+  store
+    .create_vector_index(
+      &mut tx,
+      "default",
+      VectorIndexSpec {
+        name: "idx1".into(),
+        dimension: 2,
+        ..Default::default()
+      },
+    )
+    .unwrap();
+
+  store
+    .create_vector_index(
+      &mut tx,
+      "default",
+      VectorIndexSpec {
+        name: "idx2".into(),
+        dimension: 2,
+        ..Default::default()
+      },
+    )
+    .unwrap();
+
+  let node = graph::Key::new(1);
+
+  store
+    .upsert_vector(
+      &mut tx,
+      "default",
+      "idx1",
+      node,
+      &crate::value::Tensor::from_f32_slice(&[1.0, 0.0]),
+    )
+    .unwrap();
+
+  tx.close().unwrap();
+
+  let mut tx = store.begin_read().unwrap();
+  let r1 = store
+    .vector_search(
+      &mut tx,
+      "default",
+      "idx1",
+      &crate::value::Tensor::from_f32_slice(&[1.0, 0.0]),
+      1,
+    )
+    .unwrap();
+  let r2 = store
+    .vector_search(
+      &mut tx,
+      "default",
+      "idx2",
+      &crate::value::Tensor::from_f32_slice(&[1.0, 0.0]),
+      1,
+    )
+    .unwrap();
+
+  assert_eq!(r1.len(), 1);
+  assert_eq!(r2.len(), 0);
+  tx.close().unwrap();
+}
+
+pub(crate) fn test_dimension_mismatch_fails<S: Store>(store: S)
+{
+  let mut tx = store.begin_write().unwrap();
+
+  store
+    .create_vector_index(
+      &mut tx,
+      "default",
+      VectorIndexSpec {
+        name: "idx".into(),
+        dimension: 3,
+        ..Default::default()
+      },
+    )
+    .unwrap();
+
+  let node = graph::Key::new(1);
+
+  let upsert_result = store.upsert_vector(
+    &mut tx,
+    "default",
+    "idx",
+    node,
+    &crate::value::Tensor::from_f32_slice(&[1.0, 2.0]),
+  );
+
+  tx.close().unwrap();
+
+  match upsert_result
+  {
+    Err(_) =>
+    {} // backend validated at upsert time
+    Ok(_) =>
+    {
+      // backend didn't validate; search should catch the mismatch
+      let mut tx = store.begin_read().unwrap();
+      let search_result = store.vector_search(
+        &mut tx,
+        "default",
+        "idx",
+        &crate::value::Tensor::from_f32_slice(&[1.0, 2.0]),
+        1,
+      );
+      assert!(
+        search_result.is_err(),
+        "dimension mismatch should fail at search time"
+      );
+    }
+  }
+}
+
+pub(crate) fn test_upsert_on_missing_index_fails<S: Store>(store: S)
+{
+  let mut tx = store.begin_write().unwrap();
+  store
+    .create_vector_index(
+      &mut tx,
+      "default",
+      VectorIndexSpec {
+        name: "idx".into(),
+        dimension: 3,
+        metric: VectorMetric::Cosine,
+        ..Default::default()
+      },
+    )
+    .unwrap();
+
+  let node = graph::Node::new(
+    Some("default".into()),
+    graph::Key::new(100),
+    graph::labels!("Item"),
+    value::ValueMap::new(),
+  );
+  store.create_nodes(&mut tx, "default", [&node]).unwrap();
+
+  let result = store.upsert_vector(
+    &mut tx,
+    "default",
+    "nonexistent_idx",
+    node.key(),
+    &crate::value::Tensor::from_f32_slice(&[1.0, 0.0, 0.0]),
+  );
+
+  assert!(
+    result.is_err(),
+    "upsert on missing vector index should fail"
+  );
+}
+
+pub(crate) fn test_search_on_missing_index_fails<S: Store>(store: S)
+{
+  let mut tx = store.begin_read().unwrap();
+  let result = store.vector_search(
+    &mut tx,
+    "default",
+    "never_created",
+    &crate::value::Tensor::from_f32_slice(&[1.0, 0.0, 0.0]),
+    5,
+  );
+  tx.close().unwrap();
+  assert!(
+    result.is_err(),
+    "search on a never-created index should fail"
+  );
+}
+
+pub(crate) fn test_drop_graph_cleans_vector_data<S: Store>(store: S)
+{
+  let graph_name = "g";
+  let index_name = "idx";
+  let old_node = graph::Node::new(
+    Some(graph_name.into()),
+    graph::Key::new(6001),
+    graph::labels!("Item"),
+    value::ValueMap::new(),
+  );
+
+  let mut tx = store.begin_write().unwrap();
+  store.create_graph(&mut tx, graph_name, false).unwrap();
+  store
+    .create_vector_index(
+      &mut tx,
+      graph_name,
+      VectorIndexSpec {
+        name: index_name.into(),
+        dimension: 3,
+        metric: VectorMetric::Cosine,
+        ..Default::default()
+      },
+    )
+    .unwrap();
+  store
+    .create_nodes(&mut tx, graph_name, [&old_node])
+    .unwrap();
+  store
+    .upsert_vector(
+      &mut tx,
+      graph_name,
+      index_name,
+      old_node.key(),
+      &crate::value::Tensor::from_f32_slice(&[1.0, 0.0, 0.0]),
+    )
+    .unwrap();
+  tx.close().unwrap();
+
+  let mut tx = store.begin_write().unwrap();
+  store.drop_graph(&mut tx, graph_name, false).unwrap();
+  store.create_graph(&mut tx, graph_name, false).unwrap();
+  tx.close().unwrap();
+
+  let mut tx = store.begin_read().unwrap();
+  let missing_index_result = store.vector_search(
+    &mut tx,
+    graph_name,
+    index_name,
+    &crate::value::Tensor::from_f32_slice(&[1.0, 0.0, 0.0]),
+    10,
+  );
+  tx.close().unwrap();
+  assert!(
+    missing_index_result.is_err(),
+    "search should fail after graph drop/recreate because index no longer exists"
+  );
+
+  let new_node = graph::Node::new(
+    Some(graph_name.into()),
+    graph::Key::new(6002),
+    graph::labels!("Item"),
+    value::ValueMap::new(),
+  );
+  let mut tx = store.begin_write().unwrap();
+  store
+    .create_vector_index(
+      &mut tx,
+      graph_name,
+      VectorIndexSpec {
+        name: index_name.into(),
+        dimension: 3,
+        metric: VectorMetric::Cosine,
+        ..Default::default()
+      },
+    )
+    .unwrap();
+  store
+    .create_nodes(&mut tx, graph_name, [&new_node])
+    .unwrap();
+  store
+    .upsert_vector(
+      &mut tx,
+      graph_name,
+      index_name,
+      new_node.key(),
+      &crate::value::Tensor::from_f32_slice(&[0.0, 1.0, 0.0]),
+    )
+    .unwrap();
+  tx.close().unwrap();
+
+  let mut tx = store.begin_read().unwrap();
+  let results = store
+    .vector_search(
+      &mut tx,
+      graph_name,
+      index_name,
+      &crate::value::Tensor::from_f32_slice(&[0.0, 1.0, 0.0]),
+      10,
+    )
+    .unwrap();
+  tx.close().unwrap();
+
+  assert_eq!(
+    results.len(),
+    1,
+    "recreated index should only contain new node"
+  );
+  assert_eq!(results[0].node_id, new_node.key());
+}
+
+pub(crate) fn test_vector_updated_on_node_property_update<S: Store>(store: S)
+{
+  let node_a = crate::graph::Node::new(
+    Some("default".into()),
+    crate::graph::Key::new(1),
+    crate::graph::labels!("Item"),
+    crate::value::value_map!("embedding" => vec![1.0, 0.0, 0.0]),
+  );
+  let node_b = crate::graph::Node::new(
+    Some("default".into()),
+    crate::graph::Key::new(2),
+    crate::graph::labels!("Item"),
+    crate::value::value_map!("embedding" => vec![0.8, 0.2, 0.0]),
+  );
+
+  let mut tx = store.begin_write().unwrap();
+  store
+    .create_nodes(&mut tx, "default", [&node_a, &node_b])
+    .unwrap();
+  tx.close().unwrap();
+
+  let mut tx = store.begin_write().unwrap();
+  store
+    .create_vector_index(
+      &mut tx,
+      "default",
+      crate::store::VectorIndexSpec {
+        name: "idx".into(),
+        dimension: 3,
+        metric: crate::store::VectorMetric::Cosine,
+        label: Some("Item".into()),
+        property: Some("embedding".into()),
+        ..Default::default()
+      },
+    )
+    .unwrap();
+  tx.close().unwrap();
+
+  let mut tx = store.begin_read().unwrap();
+  let results = store
+    .vector_search(
+      &mut tx,
+      "default",
+      "idx",
+      &crate::value::Tensor::from_f32_slice(&[1.0, 0.0, 0.0]),
+      2,
+    )
+    .unwrap();
+  tx.close().unwrap();
+  assert_eq!(results[0].node_id, node_a.key());
+
+  let updated_node_a = crate::graph::Node::new(
+    Some("default".into()),
+    node_a.key(),
+    crate::graph::labels!("Item"),
+    crate::value::value_map!("embedding" => vec![0.0, 1.0, 0.0]),
+  );
+
+  let mut tx = store.begin_write().unwrap();
+  store
+    .update_node(&mut tx, "default", &updated_node_a)
+    .unwrap();
+  // Explicitly update the vector in the index after updating the node
+  store
+    .upsert_vector(
+      &mut tx,
+      "default",
+      "idx",
+      updated_node_a.key(),
+      &crate::value::Tensor::from_f32_slice(&[0.0, 1.0, 0.0]),
+    )
+    .unwrap();
+  tx.close().unwrap();
+
+  let mut tx = store.begin_read().unwrap();
+  let old_results = store
+    .vector_search(
+      &mut tx,
+      "default",
+      "idx",
+      &crate::value::Tensor::from_f32_slice(&[1.0, 0.0, 0.0]),
+      2,
+    )
+    .unwrap();
+  let new_results = store
+    .vector_search(
+      &mut tx,
+      "default",
+      "idx",
+      &crate::value::Tensor::from_f32_slice(&[0.0, 1.0, 0.0]),
+      2,
+    )
+    .unwrap();
+  tx.close().unwrap();
+
+  assert_ne!(old_results[0].node_id, updated_node_a.key());
+  assert_eq!(new_results[0].node_id, updated_node_a.key());
+}
+
+pub(crate) fn test_vector_search_empty_corpus<S: Store>(store: S)
+{
+  let mut tx = store.begin_write().unwrap();
+  store
+    .create_vector_index(
+      &mut tx,
+      "default",
+      VectorIndexSpec {
+        name: "empty_idx".into(),
+        dimension: 3,
+        metric: VectorMetric::Cosine,
+        ..Default::default()
+      },
+    )
+    .unwrap();
+  tx.close().unwrap();
+
+  let mut tx = store.begin_read().unwrap();
+  let result = store
+    .vector_search(
+      &mut tx,
+      "default",
+      "empty_idx",
+      &crate::value::Tensor::from_f32_slice(&[1.0, 0.0, 0.0]),
+      5,
+    )
+    .unwrap();
+  tx.close().unwrap();
+  assert!(
+    result.is_empty(),
+    "empty corpus search should return no results"
+  );
+}
+
+pub(crate) fn test_vector_search_k_larger_than_corpus<S: Store>(store: S)
+{
+  let mut tx = store.begin_write().unwrap();
+  store
+    .create_vector_index(
+      &mut tx,
+      "default",
+      VectorIndexSpec {
+        name: "idx".into(),
+        dimension: 3,
+        metric: VectorMetric::Cosine,
+        ..Default::default()
+      },
+    )
+    .unwrap();
+
+  for i in 0..3
+  {
+    let node = graph::Node::new(
+      Some("default".into()),
+      graph::Key::new(7000 + i as u128),
+      graph::labels!("Item"),
+      value::ValueMap::new(),
+    );
+    store.create_nodes(&mut tx, "default", [&node]).unwrap();
+    store
+      .upsert_vector(
+        &mut tx,
+        "default",
+        "idx",
+        node.key(),
+        &crate::value::Tensor::from_f32_slice(&[1.0 - i as f32 * 0.1, i as f32 * 0.1, 0.0]),
+      )
+      .unwrap();
+  }
+  tx.close().unwrap();
+
+  let mut tx = store.begin_read().unwrap();
+  let results = store
+    .vector_search(
+      &mut tx,
+      "default",
+      "idx",
+      &crate::value::Tensor::from_f32_slice(&[1.0, 0.0, 0.0]),
+      100,
+    )
+    .unwrap();
+  tx.close().unwrap();
+
+  assert_eq!(
+    results.len(),
+    3,
+    "k larger than corpus should return corpus size"
+  );
+}
+
+pub(crate) fn test_vector_zero_magnitude_handling<S: Store>(store: S)
+{
+  let normal_node = graph::Node::new(
+    Some("default".into()),
+    graph::Key::new(8001),
+    graph::labels!("Item"),
+    value::ValueMap::new(),
+  );
+  let zero_node = graph::Node::new(
+    Some("default".into()),
+    graph::Key::new(8002),
+    graph::labels!("Item"),
+    value::ValueMap::new(),
+  );
+
+  let mut tx = store.begin_write().unwrap();
+  store
+    .create_vector_index(
+      &mut tx,
+      "default",
+      VectorIndexSpec {
+        name: "zero_idx".into(),
+        dimension: 3,
+        metric: VectorMetric::Cosine,
+        ..Default::default()
+      },
+    )
+    .unwrap();
+  store
+    .create_nodes(&mut tx, "default", [&normal_node, &zero_node])
+    .unwrap();
+  store
+    .upsert_vector(
+      &mut tx,
+      "default",
+      "zero_idx",
+      normal_node.key(),
+      &crate::value::Tensor::from_f32_slice(&[1.0, 0.0, 0.0]),
+    )
+    .unwrap();
+  store
+    .upsert_vector(
+      &mut tx,
+      "default",
+      "zero_idx",
+      zero_node.key(),
+      &crate::value::Tensor::from_f32_slice(&[0.0, 0.0, 0.0]),
+    )
+    .unwrap();
+  tx.close().unwrap();
+
+  let mut tx = store.begin_read().unwrap();
+  let results = store
+    .vector_search(
+      &mut tx,
+      "default",
+      "zero_idx",
+      &crate::value::Tensor::from_f32_slice(&[1.0, 0.0, 0.0]),
+      2,
+    )
+    .unwrap();
+  tx.close().unwrap();
+
+  assert_eq!(
+    results.len(),
+    2,
+    "zero-magnitude handling should not drop results"
+  );
+  assert_eq!(
+    results[0].node_id,
+    normal_node.key(),
+    "normal vector should rank before zero vector"
+  );
+  assert_eq!(results[1].node_id, zero_node.key());
+}
+
+pub(crate) fn test_vector_search_k_zero<S: Store>(store: S)
+{
+  let mut tx = store.begin_write().unwrap();
+  store
+    .create_vector_index(
+      &mut tx,
+      "default",
+      VectorIndexSpec {
+        name: "k0_idx".into(),
+        dimension: 3,
+        metric: VectorMetric::Cosine,
+        ..Default::default()
+      },
+    )
+    .unwrap();
+  for i in 0..3
+  {
+    let node = graph::Node::new(
+      Some("default".into()),
+      graph::Key::new(9000 + i as u128),
+      graph::labels!("Item"),
+      value::ValueMap::new(),
+    );
+    store.create_nodes(&mut tx, "default", [&node]).unwrap();
+    store
+      .upsert_vector(
+        &mut tx,
+        "default",
+        "k0_idx",
+        node.key(),
+        &crate::value::Tensor::from_f32_slice(&[1.0, i as f32 * 0.1, 0.0]),
+      )
+      .unwrap();
+  }
+  tx.close().unwrap();
+
+  let mut tx = store.begin_read().unwrap();
+  let results = store
+    .vector_search(
+      &mut tx,
+      "default",
+      "k0_idx",
+      &crate::value::Tensor::from_f32_slice(&[1.0, 0.0, 0.0]),
+      0,
+    )
+    .unwrap();
+  tx.close().unwrap();
+  assert!(results.is_empty(), "k=0 should return empty results");
+}
+
+pub(crate) fn test_drop_vector_index_missing_fails<S: Store>(store: S)
+{
+  let mut tx = store.begin_write().unwrap();
+  let result = store.drop_vector_index(&mut tx, "default", "missing_idx");
+  tx.close().unwrap();
+
+  assert!(result.is_err(), "dropping a missing index should fail");
+  assert!(
+    result.unwrap_err().to_string().contains("missing_idx"),
+    "error should mention missing index name"
+  );
+}
+
+pub(crate) fn test_drop_vector_index_removes_index_state<S: Store>(store: S)
+{
+  let node = graph::Node::new(
+    Some("default".into()),
+    graph::Key::new(501),
+    graph::labels!("Item"),
+    value::ValueMap::new(),
+  );
+
+  let mut tx = store.begin_write().unwrap();
+  store
+    .create_vector_index(
+      &mut tx,
+      "default",
+      VectorIndexSpec {
+        name: "idx".into(),
+        dimension: 3,
+        metric: VectorMetric::Cosine,
+        ..Default::default()
+      },
+    )
+    .unwrap();
+  store.create_nodes(&mut tx, "default", [&node]).unwrap();
+  store
+    .upsert_vector(
+      &mut tx,
+      "default",
+      "idx",
+      node.key(),
+      &crate::value::Tensor::from_f32_slice(&[1.0, 0.0, 0.0]),
+    )
+    .unwrap();
+  store.drop_vector_index(&mut tx, "default", "idx").unwrap();
+
+  let search_result = store.vector_search(
+    &mut tx,
+    "default",
+    "idx",
+    &crate::value::Tensor::from_f32_slice(&[1.0, 0.0, 0.0]),
+    1,
+  );
+  assert!(
+    search_result.is_err(),
+    "search on dropped index should return an error"
+  );
+
+  let upsert_result = store.upsert_vector(
+    &mut tx,
+    "default",
+    "idx",
+    node.key(),
+    &crate::value::Tensor::from_f32_slice(&[1.0, 0.0, 0.0]),
+  );
+  assert!(
+    upsert_result.is_err(),
+    "upsert on dropped index should return an error"
+  );
+  tx.close().unwrap();
+}
+
+pub(crate) fn test_drop_graph_recreate_index_is_clean<S: Store>(store: S)
+{
+  let graph_name = "drop_graph_recreate";
+  let index_name = "idx";
+  let node = graph::Node::new(
+    Some(graph_name.into()),
+    graph::Key::new(9001),
+    graph::labels!("Item"),
+    value::ValueMap::new(),
+  );
+
+  let mut tx = store.begin_write().unwrap();
+  store.create_graph(&mut tx, graph_name, false).unwrap();
+  store
+    .create_vector_index(
+      &mut tx,
+      graph_name,
+      VectorIndexSpec {
+        name: index_name.into(),
+        dimension: 3,
+        metric: VectorMetric::Cosine,
+        ..Default::default()
+      },
+    )
+    .unwrap();
+  store.create_nodes(&mut tx, graph_name, [&node]).unwrap();
+  store
+    .upsert_vector(
+      &mut tx,
+      graph_name,
+      index_name,
+      node.key(),
+      &crate::value::Tensor::from_f32_slice(&[1.0, 0.0, 0.0]),
+    )
+    .unwrap();
+  tx.close().unwrap();
+
+  let mut tx = store.begin_read().unwrap();
+  let before = store
+    .vector_search(
+      &mut tx,
+      graph_name,
+      index_name,
+      &crate::value::Tensor::from_f32_slice(&[1.0, 0.0, 0.0]),
+      5,
+    )
+    .unwrap();
+  tx.close().unwrap();
+  assert!(
+    !before.is_empty(),
+    "precondition: index should contain data"
+  );
+
+  let mut tx = store.begin_write().unwrap();
+  store.drop_graph(&mut tx, graph_name, false).unwrap();
+  store.create_graph(&mut tx, graph_name, false).unwrap();
+  store
+    .create_vector_index(
+      &mut tx,
+      graph_name,
+      VectorIndexSpec {
+        name: index_name.into(),
+        dimension: 3,
+        metric: VectorMetric::Cosine,
+        ..Default::default()
+      },
+    )
+    .unwrap();
+  tx.close().unwrap();
+
+  let mut tx = store.begin_read().unwrap();
+  let after = store
+    .vector_search(
+      &mut tx,
+      graph_name,
+      index_name,
+      &crate::value::Tensor::from_f32_slice(&[1.0, 0.0, 0.0]),
+      5,
+    )
+    .unwrap();
+  tx.close().unwrap();
+  assert!(
+    after.is_empty(),
+    "recreated graph/index should not contain stale vectors"
+  );
+}
+
+pub(crate) fn test_vector_search_ordering<S: Store>(store: S)
+{
+  let mut tx = store.begin_write().unwrap();
+
+  store
+    .create_vector_index(
+      &mut tx,
+      "default",
+      VectorIndexSpec {
+        name: "idx".into(),
+        dimension: 2,
+        ..Default::default()
+      },
+    )
+    .unwrap();
+
+  let n1 = graph::Key::new(1);
+  let n2 = graph::Key::new(2);
+
+  store
+    .upsert_vector(
+      &mut tx,
+      "default",
+      "idx",
+      n1,
+      &crate::value::Tensor::from_f32_slice(&[1.0, 0.0]),
+    )
+    .unwrap();
+  store
+    .upsert_vector(
+      &mut tx,
+      "default",
+      "idx",
+      n2,
+      &crate::value::Tensor::from_f32_slice(&[0.0, 1.0]),
+    )
+    .unwrap();
+
+  tx.close().unwrap();
+
+  let mut tx = store.begin_read().unwrap();
+  let results = store
+    .vector_search(
+      &mut tx,
+      "default",
+      "idx",
+      &crate::value::Tensor::from_f32_slice(&[1.0, 0.0]),
+      2,
+    )
+    .unwrap();
+
+  assert_eq!(results[0].node_id, n1);
+  tx.close().unwrap();
+}
+
+pub(crate) fn test_vector_metrics<S: Store>(store: S)
+{
+  for (metric_name, metric) in [
+    ("cosine", VectorMetric::Cosine),
+    ("l2", VectorMetric::L2),
+    ("dotproduct", VectorMetric::DotProduct),
+  ]
+  {
+    let mut tx = store.begin_write().unwrap();
+    store
+      .create_vector_index(
+        &mut tx,
+        "default",
+        VectorIndexSpec {
+          name: format!("idx_{}", metric_name),
+          dimension: 3,
+          metric,
+          ..Default::default()
+        },
+      )
+      .unwrap();
+
+    let node_a = graph::Node::new(
+      Some("default".into()),
+      graph::Key::new(1),
+      graph::labels!("Item"),
+      value::value_map!("embedding" => vec![1.0, 0.0, 0.0]),
+    );
+    let node_b = graph::Node::new(
+      Some("default".into()),
+      graph::Key::new(2),
+      graph::labels!("Item"),
+      value::value_map!("embedding" => vec![0.0, 1.0, 0.0]),
+    );
+
+    store
+      .create_nodes(&mut tx, "default", [&node_a, &node_b])
+      .unwrap();
+    store
+      .upsert_vector(
+        &mut tx,
+        "default",
+        format!("idx_{}", metric_name),
+        node_a.key(),
+        &crate::value::Tensor::from_f32_slice(&[1.0, 0.0, 0.0]),
+      )
+      .unwrap();
+    store
+      .upsert_vector(
+        &mut tx,
+        "default",
+        format!("idx_{}", metric_name),
+        node_b.key(),
+        &crate::value::Tensor::from_f32_slice(&[0.0, 1.0, 0.0]),
+      )
+      .unwrap();
+
+    tx.close().unwrap();
+
+    let mut tx = store.begin_read().unwrap();
+    let result = store.vector_search(
+      &mut tx,
+      "default",
+      format!("idx_{}", metric_name),
+      &crate::value::Tensor::from_f32_slice(&[1.0, 0.0, 0.0]),
+      2,
+    );
+
+    let results = result.unwrap();
+    assert_eq!(results.len(), 2, "Vector search should return both vectors");
+    assert_eq!(results[0].node_id, node_a.key());
+
+    match metric
+    {
+      VectorMetric::Cosine | VectorMetric::L2 =>
+      {
+        assert!(
+          (results[0].score - 0.0).abs() < 1e-4,
+          "{} score should be near zero for an exact match",
+          metric_name
+        );
+      }
+      VectorMetric::DotProduct =>
+      {
+        assert!(
+          results[0].score <= results[1].score,
+          "dot-product results should be ordered by the smallest score"
+        );
+      }
+    }
+
+    tx.close().unwrap();
+  }
+}
+
+pub(crate) fn test_multiple_vector_indexes_isolation<S: Store>(store: S)
+{
+  let mut tx = store.begin_write().unwrap();
+
+  for name in ["idx1", "idx2"]
+  {
+    store
+      .create_vector_index(
+        &mut tx,
+        "default",
+        VectorIndexSpec {
+          name: name.into(),
+          dimension: 3,
+          metric: VectorMetric::Cosine,
+          ..Default::default()
+        },
+      )
+      .unwrap();
+  }
+
+  tx.close().unwrap();
+}
+
+pub(crate) fn test_list_vector_indexes<S: Store>(store: S)
+{
+  let mut tx = store.begin_write().unwrap();
+  store.create_graph(&mut tx, "no_indices", false).unwrap();
+
+  store
+    .create_vector_index(
+      &mut tx,
+      "default",
+      VectorIndexSpec {
+        name: "idx_a".to_string(),
+        dimension: 3,
+        metric: VectorMetric::Cosine,
+        ..Default::default()
+      },
+    )
+    .unwrap();
+  store
+    .create_vector_index(
+      &mut tx,
+      "default",
+      VectorIndexSpec {
+        name: "idx_b".to_string(),
+        dimension: 4,
+        metric: VectorMetric::L2,
+        ..Default::default()
+      },
+    )
+    .unwrap();
+  tx.close().unwrap();
+
+  let mut tx = store.begin_read().unwrap();
+  let listed = store.list_vector_indexes(&mut tx, "default").unwrap();
+  let empty = store.list_vector_indexes(&mut tx, "no_indices").unwrap();
+  tx.close().unwrap();
+
+  assert_eq!(listed.len(), 2, "expected exactly two vector indexes");
+  assert!(empty.is_empty(), "graph with no indices should list empty");
+
+  let idx_a = listed.iter().find(|spec| spec.name == "idx_a").unwrap();
+  assert_eq!(idx_a.metric, VectorMetric::Cosine);
+  assert_eq!(idx_a.dimension, 3);
+
+  let idx_b = listed.iter().find(|spec| spec.name == "idx_b").unwrap();
+  assert_eq!(idx_b.metric, VectorMetric::L2);
+  assert_eq!(idx_b.dimension, 4);
+}
+pub(crate) fn test_vector_rollback<S: Store>(store: S)
+{
+  let graph = "default";
+  let index = "idx";
+
+  {
+    let mut tx = store.begin_write().unwrap();
+    store
+      .create_vector_index(
+        &mut tx,
+        graph,
+        VectorIndexSpec {
+          name: index.into(),
+          dimension: 2,
+          ..Default::default()
+        },
+      )
+      .unwrap();
+
+    store
+      .upsert_vector(
+        &mut tx,
+        graph,
+        index,
+        graph::Key::new(7),
+        &crate::value::Tensor::from_f32_slice(&[1.0, 0.0]),
+      )
+      .unwrap();
+  }
+
+  let mut tx = store.begin_write().unwrap();
+
+  match store.vector_search(
+    &mut tx,
+    graph,
+    index,
+    &crate::value::Tensor::from_f32_slice(&[1.0, 0.0]),
+    1,
+  )
+  {
+    Ok(results) =>
+    {
+      // Index was persisted (in-memory backend) but vector was rolled back
+      assert!(results.is_empty(), "rollback should leave no vectors");
+    }
+    Err(_) =>
+    {
+      // Index was fully rolled back (transactional backend) or reads are forbidden
+    }
+  }
+}
+
+pub(crate) fn test_vector_cleanup_after_node_deletion<S: Store>(store: S)
+{
+  // Use explicit upsert_vector so the test works for all backends regardless of
+  // whether they support retroactive population or apply_vector_indices_for_node.
+  let node = graph::Node::new(
+    Some("default".to_string()),
+    graph::Key::default(),
+    graph::labels!("Article"),
+    value::ValueMap::new(),
+  );
+
+  let mut tx = store.begin_write().unwrap();
+  store
+    .create_vector_index(
+      &mut tx,
+      "default",
+      VectorIndexSpec {
+        name: "cleanup_idx".to_string(),
+        dimension: 3,
+        metric: VectorMetric::Cosine,
+        ..Default::default()
+      },
+    )
+    .unwrap();
+  store
+    .create_nodes(&mut tx, "default", [node.clone()].iter())
+    .unwrap();
+  store
+    .upsert_vector(
+      &mut tx,
+      "default",
+      "cleanup_idx",
+      node.key(),
+      &crate::value::Tensor::from_f32_slice(&[1.0, 0.0, 0.0]),
+    )
+    .unwrap();
+  tx.close().unwrap();
+
+  // Verify the node is found before deletion
+  let mut tx = store.begin_read().unwrap();
+  let results_before = store
+    .vector_search(
+      &mut tx,
+      "default",
+      "cleanup_idx",
+      &crate::value::Tensor::from_f32_slice(&[1.0, 0.0, 0.0]),
+      1,
+    )
+    .unwrap();
+  tx.close().unwrap();
+  assert_eq!(results_before.len(), 1, "Expected 1 result before deletion");
+  assert_eq!(results_before[0].node_id, node.key());
+
+  // Delete the node
+  let mut tx = store.begin_write().unwrap();
+  store
+    .delete_nodes(
+      &mut tx,
+      "default",
+      store::SelectNodeQuery::select_keys(vec![node.key()]),
+      false,
+    )
+    .unwrap();
+  tx.close().unwrap();
+
+  // After deletion, vector search must return no results (no stale entries)
+  let mut tx = store.begin_read().unwrap();
+  let results_after = store
+    .vector_search(
+      &mut tx,
+      "default",
+      "cleanup_idx",
+      &crate::value::Tensor::from_f32_slice(&[1.0, 0.0, 0.0]),
+      1,
+    )
+    .unwrap();
+  tx.close().unwrap();
+  assert_eq!(
+    results_after.len(),
+    0,
+    "Expected 0 results after deletion — stale vector entry was not cleaned up"
+  );
+}
+
+pub(crate) fn test_vector_search_returns_correct_node<S: Store>(store: S)
+{
+  let n1 = graph::Node::new(
+    Some("default".to_string()),
+    graph::Key::default(),
+    graph::labels!("Article"),
+    value::value_map!("embedding" => vec![1.0, 0.0, 0.0], "id" => 1),
+  );
+
+  let n2 = graph::Node::new(
+    Some("default".to_string()),
+    graph::Key::default(),
+    graph::labels!("Article"),
+    value::value_map!("embedding" => vec![0.0, 1.0, 0.0], "id" => 2),
+  );
+
+  let n3 = graph::Node::new(
+    Some("default".to_string()),
+    graph::Key::default(),
+    graph::labels!("Article"),
+    value::value_map!("embedding" => vec![1.0, 0.2, 0.0], "id" => 3),
+  );
+
+  let mut tx = store.begin_write().unwrap();
+  store
+    .create_nodes(
+      &mut tx,
+      "default",
+      [n1.clone(), n2.clone(), n3.clone()].iter(),
+    )
+    .unwrap();
+
+  store
+    .create_vector_index(
+      &mut tx,
+      "default",
+      VectorIndexSpec {
+        name: "article_idx".to_string(),
+        dimension: 3,
+        metric: VectorMetric::Cosine,
+        label: Some("Article".to_string()),
+        property: Some("embedding".to_string()),
+        ..Default::default()
+      },
+    )
+    .unwrap();
+  tx.close().unwrap();
+
+  let mut tx = store.begin_read().unwrap();
+  let results = store
+    .vector_search(
+      &mut tx,
+      "default",
+      "article_idx",
+      &crate::value::Tensor::from_f32_slice(&[1.0, 0.0, 0.0]),
+      2,
+    )
+    .unwrap();
+  tx.close().unwrap();
+
+  assert_eq!(
+    results.len(),
+    2,
+    "Expected 2 results, got {}",
+    results.len()
+  );
+
+  assert_eq!(
+    results[0].node_id,
+    n1.key(),
+    "First result should be n1 (closest to query vector)"
+  );
+  assert_eq!(
+    results[1].node_id,
+    n3.key(),
+    "Second result should be n3 (next closest)"
+  );
+
+  use std::borrow::BorrowMut;
+  let mut tx = store.begin_read().unwrap();
+  let selected_nodes = store
+    .select_nodes(
+      tx.borrow_mut(),
+      "default",
+      store::SelectNodeQuery::select_keys(vec![results[0].node_id, results[1].node_id]),
+    )
+    .unwrap();
+  tx.close().unwrap();
+
+  let mut n1_found = false;
+  let mut n3_found = false;
+  for node in selected_nodes
+  {
+    let id_val = node.properties().get("id").cloned();
+    if let Some(id) = id_val
+    {
+      if id == value::Value::from(1)
+      {
+        assert_eq!(
+          node.key(),
+          n1.key(),
+          "Node with id=1 should have key matching n1"
+        );
+        n1_found = true;
+      }
+      else if id == value::Value::from(3)
+      {
+        assert_eq!(
+          node.key(),
+          n3.key(),
+          "Node with id=3 should have key matching n3"
+        );
+        n3_found = true;
+      }
+    }
+  }
+  assert!(n1_found, "Node with id=1 should be in selected nodes");
+  assert!(n3_found, "Node with id=3 should be in selected nodes");
+}
+
+pub(crate) fn test_vector_index_on_non_default_graph<S: Store>(store: S)
+{
+  let graph_name = "docs_graph";
+  let index_name = "idx";
+
+  let mut tx = store.begin_write().unwrap();
+  store.create_graph(&mut tx, graph_name, false).unwrap();
+  store
+    .create_vector_index(
+      &mut tx,
+      graph_name,
+      VectorIndexSpec {
+        name: index_name.into(),
+        dimension: 3,
+        metric: VectorMetric::Cosine,
+        ..Default::default()
+      },
+    )
+    .unwrap();
+  let node = graph::Node::new(
+    Some(graph_name.into()),
+    graph::Key::new(1),
+    graph::labels!("Doc"),
+    value::ValueMap::new(),
+  );
+  store.create_nodes(&mut tx, graph_name, [&node]).unwrap();
+  store
+    .upsert_vector(
+      &mut tx,
+      graph_name,
+      index_name,
+      node.key(),
+      &crate::value::Tensor::from_f32_slice(&[1.0, 0.0, 0.0]),
+    )
+    .unwrap();
+  tx.close().unwrap();
+
+  // Positive case: search on the graph the index actually belongs to.
+  let mut tx = store.begin_read().unwrap();
+  let hits = store
+    .vector_search(
+      &mut tx,
+      graph_name,
+      index_name,
+      &crate::value::Tensor::from_f32_slice(&[1.0, 0.0, 0.0]),
+      5,
+    )
+    .unwrap();
+  tx.close().unwrap();
+  assert_eq!(
+    hits.len(),
+    1,
+    "index must be usable on the graph it was created on"
+  );
+  assert_eq!(hits[0].node_id, node.key());
+}
+
+pub(crate) fn test_vector_index_not_visible_from_a_different_graph<S: Store>(store: S)
+{
+  let graph_name = "docs_graph";
+  let other_graph = "other_graph";
+  let index_name = "idx";
+
+  let mut tx = store.begin_write().unwrap();
+  store.create_graph(&mut tx, graph_name, false).unwrap();
+  store.create_graph(&mut tx, other_graph, false).unwrap();
+  store
+    .create_vector_index(
+      &mut tx,
+      graph_name,
+      VectorIndexSpec {
+        name: index_name.into(),
+        dimension: 3,
+        metric: VectorMetric::Cosine,
+        ..Default::default()
+      },
+    )
+    .unwrap();
+  tx.close().unwrap();
+
+  // Negative case: the SAME index name, looked up against a DIFFERENT
+  // graph than the one it was created on, must fail -- not silently
+  // resolve to the graph it actually lives on, and not silently succeed
+  // against an empty/default fallback.
+  let mut tx = store.begin_read().unwrap();
+  let result = store.vector_search(
+    &mut tx,
+    other_graph,
+    index_name,
+    &crate::value::Tensor::from_f32_slice(&[1.0, 0.0, 0.0]),
+    5,
+  );
+  tx.close().unwrap();
+  assert!(
+    result.is_err(),
+    "an index created on '{}' must not be reachable from '{}'",
+    graph_name,
+    other_graph
+  );
+}
+
+pub(crate) fn test_same_index_name_on_different_graphs_does_not_conflict<S: Store>(store: S)
+{
+  let graph_a = "graph_a";
+  let graph_b = "graph_b";
+  let index_name = "idx"; // deliberately identical on both graphs
+
+  let mut tx = store.begin_write().unwrap();
+  store.create_graph(&mut tx, graph_a, false).unwrap();
+  store.create_graph(&mut tx, graph_b, false).unwrap();
+
+  store
+    .create_vector_index(
+      &mut tx,
+      graph_a,
+      VectorIndexSpec {
+        name: index_name.into(),
+        dimension: 3,
+        metric: VectorMetric::Cosine,
+        ..Default::default()
+      },
+    )
+    .unwrap();
+  // Must not error just because an index of the same name already exists
+  // on a DIFFERENT graph -- index identity is (graph, name), not name alone.
+  store
+    .create_vector_index(
+      &mut tx,
+      graph_b,
+      VectorIndexSpec {
+        name: index_name.into(),
+        dimension: 3,
+        metric: VectorMetric::Cosine,
+        ..Default::default()
+      },
+    )
+    .unwrap();
+
+  let node_a = graph::Node::new(
+    Some(graph_a.into()),
+    graph::Key::new(1),
+    graph::labels!("Doc"),
+    value::ValueMap::new(),
+  );
+  let node_b = graph::Node::new(
+    Some(graph_b.into()),
+    graph::Key::new(2),
+    graph::labels!("Doc"),
+    value::ValueMap::new(),
+  );
+  store.create_nodes(&mut tx, graph_a, [&node_a]).unwrap();
+  store.create_nodes(&mut tx, graph_b, [&node_b]).unwrap();
+  store
+    .upsert_vector(
+      &mut tx,
+      graph_a,
+      index_name,
+      node_a.key(),
+      &crate::value::Tensor::from_f32_slice(&[1.0, 0.0, 0.0]),
+    )
+    .unwrap();
+  store
+    .upsert_vector(
+      &mut tx,
+      graph_b,
+      index_name,
+      node_b.key(),
+      &crate::value::Tensor::from_f32_slice(&[0.0, 1.0, 0.0]),
+    )
+    .unwrap();
+  tx.close().unwrap();
+
+  let mut tx = store.begin_read().unwrap();
+  let hits_a = store
+    .vector_search(
+      &mut tx,
+      graph_a,
+      index_name,
+      &crate::value::Tensor::from_f32_slice(&[1.0, 0.0, 0.0]),
+      5,
+    )
+    .unwrap();
+  let hits_b = store
+    .vector_search(
+      &mut tx,
+      graph_b,
+      index_name,
+      &crate::value::Tensor::from_f32_slice(&[0.0, 1.0, 0.0]),
+      5,
+    )
+    .unwrap();
+  tx.close().unwrap();
+
+  assert_eq!(hits_a.len(), 1);
+  assert_eq!(hits_a[0].node_id, node_a.key());
+  assert_eq!(hits_b.len(), 1);
+  assert_eq!(hits_b[0].node_id, node_b.key());
+  assert_ne!(
+    hits_a[0].node_id, hits_b[0].node_id,
+    "same-named indexes on different graphs must never cross-contaminate results"
+  );
+}
+
+/// The headline roundtrip: populate, close, reopen, search.
+pub(crate) fn test_vector_index_survives_reopen<S: Store>(factory: &dyn Fn() -> S)
+{
+  let graph_name = "reopen_rt";
+  let index_name = "idx";
+
+  {
+    let store = factory();
+    let mut tx = store.begin_write().unwrap();
+    store.create_graph(&mut tx, graph_name, false).unwrap();
+    store
+      .create_vector_index(
+        &mut tx,
+        graph_name,
+        VectorIndexSpec {
+          name: index_name.into(),
+          dimension: 3,
+          metric: VectorMetric::Cosine,
+          ..Default::default()
+        },
+      )
+      .unwrap();
+    for (id, v) in [
+      (1u64, [1.0f32, 0.0, 0.0]),
+      (2, [0.0, 1.0, 0.0]),
+      (3, [0.0, 0.0, 1.0]),
+    ]
+    {
+      let node = graph::Node::new(
+        Some(graph_name.into()),
+        graph::Key::new(id as u128),
+        graph::labels!("Item"),
+        value::ValueMap::new(),
+      );
+      store.create_nodes(&mut tx, graph_name, [&node]).unwrap();
+      store
+        .upsert_vector(
+          &mut tx,
+          graph_name,
+          index_name,
+          node.key(),
+          &crate::value::Tensor::from_f32_slice(&v),
+        )
+        .unwrap();
+    }
+    tx.close().unwrap();
+  } // store dropped: all in-memory state gone
+
+  let store = factory(); // reopen from the same backing storage
+  let mut tx = store.begin_read().unwrap();
+  let results = store
+    .vector_search(
+      &mut tx,
+      graph_name,
+      index_name,
+      &crate::value::Tensor::from_f32_slice(&[1.0, 0.0, 0.0]),
+      1,
+    )
+    .unwrap();
+  tx.close().unwrap();
+
+  assert_eq!(results.len(), 1, "reopened index must serve searches");
+  assert_eq!(
+    results[0].node_id,
+    graph::Key::new(1),
+    "reopened index must return the correct nearest neighbour, not merely any result"
+  );
+}
+
+/// Reopen must also restore write capability: inserting more vectors into a
+/// reopened index must work, and search must find both old and new vectors.
+/// Catches the capacity-not-restored class of bug (a reloaded index whose
+/// internal limits were sized to the persisted count instead of the original
+/// configuration) and any install-ordering issue that leaves the reloaded
+/// index read-only.
+pub(crate) fn test_insert_after_reopen<S: Store>(factory: &dyn Fn() -> S)
+{
+  let graph_name = "reopen_insert";
+  let index_name = "idx";
+
+  {
+    let store = factory();
+    let mut tx = store.begin_write().unwrap();
+    store.create_graph(&mut tx, graph_name, false).unwrap();
+    store
+      .create_vector_index(
+        &mut tx,
+        graph_name,
+        VectorIndexSpec {
+          name: index_name.into(),
+          dimension: 3,
+          metric: VectorMetric::Cosine,
+          ..Default::default()
+        },
+      )
+      .unwrap();
+    let node = graph::Node::new(
+      Some(graph_name.into()),
+      graph::Key::new(1u128),
+      graph::labels!("Item"),
+      value::ValueMap::new(),
+    );
+    store.create_nodes(&mut tx, graph_name, [&node]).unwrap();
+    store
+      .upsert_vector(
+        &mut tx,
+        graph_name,
+        index_name,
+        node.key(),
+        &crate::value::Tensor::from_f32_slice(&[1.0, 0.0, 0.0]),
+      )
+      .unwrap();
+    tx.close().unwrap();
+  }
+
+  let store = factory();
+  let mut tx = store.begin_write().unwrap();
+  let node = graph::Node::new(
+    Some(graph_name.into()),
+    graph::Key::new(2u128),
+    graph::labels!("Item"),
+    value::ValueMap::new(),
+  );
+  store.create_nodes(&mut tx, graph_name, [&node]).unwrap();
+  store
+    .upsert_vector(
+      &mut tx,
+      graph_name,
+      index_name,
+      node.key(),
+      &crate::value::Tensor::from_f32_slice(&[0.0, 1.0, 0.0]),
+    )
+    .unwrap();
+  tx.close().unwrap();
+
+  let mut tx = store.begin_read().unwrap();
+  let old_hit = store
+    .vector_search(
+      &mut tx,
+      graph_name,
+      index_name,
+      &crate::value::Tensor::from_f32_slice(&[1.0, 0.0, 0.0]),
+      1,
+    )
+    .unwrap();
+  let new_hit = store
+    .vector_search(
+      &mut tx,
+      graph_name,
+      index_name,
+      &crate::value::Tensor::from_f32_slice(&[0.0, 1.0, 0.0]),
+      1,
+    )
+    .unwrap();
+  tx.close().unwrap();
+
+  assert_eq!(
+    old_hit[0].node_id,
+    graph::Key::new(1),
+    "pre-reopen vector must remain searchable"
+  );
+  assert_eq!(
+    new_hit[0].node_id,
+    graph::Key::new(2),
+    "post-reopen insert must be searchable"
+  );
+}
+
+/// A vector deleted (via node deletion) before close must stay gone after
+/// reopen; surviving vectors must remain searchable. Catches resurrection
+/// through stale persisted records.
+pub(crate) fn test_deleted_vector_stays_deleted_after_reopen<S: Store>(factory: &dyn Fn() -> S)
+{
+  let graph_name = "reopen_deleted";
+  let index_name = "idx";
+
+  {
+    let store = factory();
+    let mut tx = store.begin_write().unwrap();
+    store.create_graph(&mut tx, graph_name, false).unwrap();
+    store
+      .create_vector_index(
+        &mut tx,
+        graph_name,
+        VectorIndexSpec {
+          name: index_name.into(),
+          dimension: 3,
+          metric: VectorMetric::Cosine,
+          ..Default::default()
+        },
+      )
+      .unwrap();
+    for (id, v) in [
+      (1u64, [1.0f32, 0.0, 0.0]),
+      (2, [0.0, 1.0, 0.0]),
+      (3, [0.0, 0.0, 1.0]),
+    ]
+    {
+      let node = graph::Node::new(
+        Some(graph_name.into()),
+        graph::Key::new(id as u128),
+        graph::labels!("Item"),
+        value::ValueMap::new(),
+      );
+      store.create_nodes(&mut tx, graph_name, [&node]).unwrap();
+      store
+        .upsert_vector(
+          &mut tx,
+          graph_name,
+          index_name,
+          node.key(),
+          &crate::value::Tensor::from_f32_slice(&v),
+        )
+        .unwrap();
+    }
+    tx.close().unwrap();
+
+    let mut tx = store.begin_write().unwrap();
+    store
+      .delete_nodes(
+        &mut tx,
+        graph_name,
+        SelectNodeQuery::select_keys(vec![graph::Key::new(2)]),
+        false,
+      )
+      .unwrap();
+    tx.close().unwrap();
+  }
+
+  let store = factory();
+  let mut tx = store.begin_read().unwrap();
+  let results = store
+    .vector_search(
+      &mut tx,
+      graph_name,
+      index_name,
+      &crate::value::Tensor::from_f32_slice(&[0.0, 1.0, 0.0]),
+      3,
+    )
+    .unwrap();
+  tx.close().unwrap();
+
+  assert_eq!(
+    results.len(),
+    2,
+    "search should return 2 results (nodes 1 and 3), not 3"
+  );
+  let found_uuids: Vec<_> = results.iter().map(|r| r.node_id.uuid()).collect();
+  assert!(
+    found_uuids.contains(&1),
+    "reopened index must still have node 1"
+  );
+  assert!(
+    found_uuids.contains(&3),
+    "reopened index must still have node 3"
+  );
+  assert!(
+    !found_uuids.contains(&2),
+    "deleted node 2 must not resurface after reopen"
+  );
+}
+
+/// An index created but never populated must reopen as an empty, functional
+/// index — search returns Ok(empty), not an error and not a missing-index error.
+pub(crate) fn test_empty_index_survives_reopen<S: Store>(factory: &dyn Fn() -> S)
+{
+  let graph_name = "reopen_empty";
+  let index_name = "idx";
+
+  {
+    let store = factory();
+    let mut tx = store.begin_write().unwrap();
+    store.create_graph(&mut tx, graph_name, false).unwrap();
+    store
+      .create_vector_index(
+        &mut tx,
+        graph_name,
+        VectorIndexSpec {
+          name: index_name.into(),
+          dimension: 3,
+          metric: VectorMetric::Cosine,
+          ..Default::default()
+        },
+      )
+      .unwrap();
+    tx.close().unwrap();
+  }
+
+  let store = factory();
+  let mut tx = store.begin_read().unwrap();
+  let results = store
+    .vector_search(
+      &mut tx,
+      graph_name,
+      index_name,
+      &crate::value::Tensor::from_f32_slice(&[1.0, 0.0, 0.0]),
+      5,
+    )
+    .unwrap();
+  tx.close().unwrap();
+
+  assert!(
+    results.is_empty(),
+    "empty index search should return empty results, not an error"
+  );
+}
+
+/// Generates one #[test] per generic single-open test. `$setup` must
+/// evaluate to `(guard, store)`; the guard keeps backing resources (tmp
+/// file, tmp database) alive for the test's duration. `$setup` is re-evaluated
+/// inside every generated test, so each test gets a fresh store.
+/// Extra attributes (e.g. #[serial]) are applied to every generated test.
+#[macro_export]
+macro_rules! vector_index_test_suite {
+  ($(#[$attr:meta])* setup = $setup:expr) => {
+    $(#[$attr])*
+    #[test]
+    fn test_vector_operations()
+    {
+      let (_guard, store) = ($setup)(0);
+      super::super::test_vector_operations(store);
+    }
+
+    $(#[$attr])*
+    #[test]
+    fn test_vector_search_returns_results()
+    {
+      let (_guard, store) = ($setup)(1);
+      super::super::test_vector_search_returns_results(store);
+    }
+
+    $(#[$attr])*
+    #[test]
+    fn test_vector_search_k_limit()
+    {
+      let (_guard, store) = ($setup)(2);
+      super::super::test_vector_search_k_limit(store);
+    }
+
+    $(#[$attr])*
+    #[test]
+    fn test_vector_upsert_does_not_duplicate()
+    {
+      let (_guard, store) = ($setup)(3);
+      super::super::test_vector_upsert_does_not_duplicate(store);
+    }
+
+    $(#[$attr])*
+    #[test]
+    fn test_multiple_indexes_do_not_conflict()
+    {
+      let (_guard, store) = ($setup)(4);
+      super::super::test_multiple_indexes_do_not_conflict(store);
+    }
+
+    $(#[$attr])*
+    #[test]
+    fn test_dimension_mismatch_fails()
+    {
+      let (_guard, store) = ($setup)(5);
+      super::super::test_dimension_mismatch_fails(store);
+    }
+
+    $(#[$attr])*
+    #[test]
+    fn test_upsert_on_missing_index_fails()
+    {
+      let (_guard, store) = ($setup)(6);
+      super::super::test_upsert_on_missing_index_fails(store);
+    }
+
+    $(#[$attr])*
+    #[test]
+    fn test_search_on_missing_index_fails()
+    {
+      let (_guard, store) = ($setup)(7);
+      super::super::test_search_on_missing_index_fails(store);
+    }
+
+    $(#[$attr])*
+    #[test]
+    fn test_drop_graph_cleans_vector_data()
+    {
+      let (_guard, store) = ($setup)(8);
+      super::super::test_drop_graph_cleans_vector_data(store);
+    }
+
+    $(#[$attr])*
+    #[test]
+    fn test_vector_updated_on_node_property_update()
+    {
+      let (_guard, store) = ($setup)(9);
+      super::super::test_vector_updated_on_node_property_update(store);
+    }
+
+    $(#[$attr])*
+    #[test]
+    fn test_vector_search_empty_corpus()
+    {
+      let (_guard, store) = ($setup)(10);
+      super::super::test_vector_search_empty_corpus(store);
+    }
+
+    $(#[$attr])*
+    #[test]
+    fn test_vector_search_k_larger_than_corpus()
+    {
+      let (_guard, store) = ($setup)(11);
+      super::super::test_vector_search_k_larger_than_corpus(store);
+    }
+
+    $(#[$attr])*
+    #[test]
+    fn test_vector_zero_magnitude_handling()
+    {
+      let (_guard, store) = ($setup)(12);
+      super::super::test_vector_zero_magnitude_handling(store);
+    }
+
+    $(#[$attr])*
+    #[test]
+    fn test_vector_search_k_zero()
+    {
+      let (_guard, store) = ($setup)(13);
+      super::super::test_vector_search_k_zero(store);
+    }
+
+    $(#[$attr])*
+    #[test]
+    fn test_drop_vector_index_missing_fails()
+    {
+      let (_guard, store) = ($setup)(14);
+      super::super::test_drop_vector_index_missing_fails(store);
+    }
+
+    $(#[$attr])*
+    #[test]
+    fn test_drop_vector_index_removes_index_state()
+    {
+      let (_guard, store) = ($setup)(15);
+      super::super::test_drop_vector_index_removes_index_state(store);
+    }
+
+    $(#[$attr])*
+    #[test]
+    fn test_drop_graph_recreate_index_is_clean()
+    {
+      let (_guard, store) = ($setup)(16);
+      super::super::test_drop_graph_recreate_index_is_clean(store);
+    }
+
+    $(#[$attr])*
+    #[test]
+    fn test_vector_search_ordering()
+    {
+      let (_guard, store) = ($setup)(17);
+      super::super::test_vector_search_ordering(store);
+    }
+
+    $(#[$attr])*
+    #[test]
+    fn test_vector_metrics()
+    {
+      let (_guard, store) = ($setup)(18);
+      super::super::test_vector_metrics(store);
+    }
+
+    $(#[$attr])*
+    #[test]
+    fn test_multiple_vector_indexes_isolation()
+    {
+      let (_guard, store) = ($setup)(19);
+      super::super::test_multiple_vector_indexes_isolation(store);
+    }
+
+    $(#[$attr])*
+    #[test]
+    fn test_list_vector_indexes()
+    {
+      let (_guard, store) = ($setup)(20);
+      super::super::test_list_vector_indexes(store);
+    }
+
+    $(#[$attr])*
+    #[test]
+    fn test_vector_rollback()
+    {
+      let (_guard, store) = ($setup)(21);
+      super::super::test_vector_rollback(store);
+    }
+
+    $(#[$attr])*
+    #[test]
+    fn test_vector_search_returns_correct_node()
+    {
+      let (_guard, store) = ($setup)(22);
+      super::super::test_vector_search_returns_correct_node(store);
+    }
+
+    $(#[$attr])*
+    #[test]
+    fn test_vector_cleanup_after_node_deletion()
+    {
+      let (_guard, store) = ($setup)(23);
+      super::super::test_vector_cleanup_after_node_deletion(store);
+    }
+
+    $(#[$attr])*
+    #[test]
+    fn test_vector_index_on_non_default_graph()
+    {
+      let (_guard, store) = ($setup)(24);
+      super::super::test_vector_index_on_non_default_graph(store);
+    }
+
+    $(#[$attr])*
+    #[test]
+    fn test_vector_index_not_visible_from_a_different_graph()
+    {
+      let (_guard, store) = ($setup)(25);
+      super::super::test_vector_index_not_visible_from_a_different_graph(store);
+    }
+
+    $(#[$attr])*
+    #[test]
+    fn test_same_index_name_on_different_graphs_does_not_conflict()
+    {
+      let (_guard, store) = ($setup)(26);
+      super::super::test_same_index_name_on_different_graphs_does_not_conflict(store);
+    }
+  };
+}
+
+/// Reopen suite: `$setup` evaluates to `(guard, factory)` where the factory
+/// constructs a store against the same backing storage on every call.
+/// Extra attributes (e.g. #[serial]) are applied to every generated test.
+#[macro_export]
+macro_rules! vector_index_reopen_suite {
+  ($(#[$attr:meta])* setup = $setup:expr) => {
+    $(#[$attr])*
+    #[test]
+    fn test_vector_index_survives_reopen()
+    {
+      let (_guard, factory) = ($setup)(0);
+      super::super::test_vector_index_survives_reopen(&factory);
+    }
+
+    $(#[$attr])*
+    #[test]
+    fn test_insert_after_reopen()
+    {
+      let (_guard, factory) = ($setup)(1);
+      super::super::test_insert_after_reopen(&factory);
+    }
+
+    $(#[$attr])*
+    #[test]
+    fn test_deleted_vector_stays_deleted_after_reopen()
+    {
+      let (_guard, factory) = ($setup)(2);
+      super::super::test_deleted_vector_stays_deleted_after_reopen(&factory);
+    }
+
+    $(#[$attr])*
+    #[test]
+    fn test_empty_index_survives_reopen()
+    {
+      let (_guard, factory) = ($setup)(3);
+      super::super::test_empty_index_survives_reopen(&factory);
+    }
+  };
+}