adding clamp logic

Author: trvon

include/sqlite-vec-cpp/index/hnsw.hpp

@@ -56,6 +56,7 @@ template <concepts::VectorElement StorageT, typename MetricT> class HNSWIndex {
         size_t ef_construction = 200; ///< Exploration factor during construction (100-500)
         float ml_factor = 1.0f / std::log(2.0f); ///< Layer selection multiplier (1/ln(2))
         MetricT metric{};                        ///< Distance metric (operates on float spans)
+        bool clamp_negative_distances = true; ///< Clamp negative distances to 0 (safe for L2/cosine)
 
         /// Create config optimized for high recall on large corpora
         /// @param corpus_size Expected number of vectors
@@ -812,7 +813,8 @@ template <concepts::VectorElement StorageT, typename MetricT> class HNSWIndex {
     size_t greedy_search_layer_locked(std::span<const float> query, size_t entry_point,
                                       size_t layer, const FilterFn* filter) const {
         // Small negative threshold to handle floating-point error in distance calculation
-        constexpr float kDistanceEpsilon = -1e-5f;
+        const float kDistanceEpsilon =
+            config_.clamp_negative_distances ? -1e-5f : std::numeric_limits<float>::lowest();
 
         size_t current = entry_point;
         float current_dist = distance(query, current);
@@ -903,9 +905,12 @@ template <concepts::VectorElement StorageT, typename MetricT> class HNSWIndex {
         // Note: entry_dist can be slightly negative due to floating-point error
         // (e.g., cosine distance of identical vectors = 1 - 1.0000001 = -1e-7)
         // We allow small negative values to avoid missing exact matches.
-        constexpr float kDistanceEpsilon = -1e-5f;
+        const float kDistanceEpsilon =
+            config_.clamp_negative_distances ? -1e-5f : std::numeric_limits<float>::lowest();
         if (passes_filter(entry_point) && entry_dist >= kDistanceEpsilon) {
-            top_candidates.emplace(std::max(0.0f, entry_dist), entry_point);
+            float entry_score =
+                config_.clamp_negative_distances ? std::max(0.0f, entry_dist) : entry_dist;
+            top_candidates.emplace(entry_score, entry_point);
         }
 
         while (!candidates.empty()) {
@@ -958,12 +963,18 @@ template <concepts::VectorElement StorageT, typename MetricT> class HNSWIndex {
                                       neighbor_dist < top_candidates.top().first;
 
                 if (should_explore) {
-                    candidates.emplace(std::max(0.0f, neighbor_dist), neighbor);
+                    float candidate_score = config_.clamp_negative_distances
+                                                ? std::max(0.0f, neighbor_dist)
+                                                : neighbor_dist;
+                    candidates.emplace(candidate_score, neighbor);
                 }
 
                 if (passes_filter(neighbor)) {
                     if (top_candidates.size() < ef || neighbor_dist < top_candidates.top().first) {
-                        top_candidates.emplace(std::max(0.0f, neighbor_dist), neighbor);
+                        float top_score = config_.clamp_negative_distances
+                                              ? std::max(0.0f, neighbor_dist)
+                                              : neighbor_dist;
+                        top_candidates.emplace(top_score, neighbor);
                         if (top_candidates.size() > ef) {
                             top_candidates.pop();
                         }

include/sqlite-vec-cpp/index/hnsw_persistence.hpp

@@ -24,7 +24,7 @@ std::vector<uint8_t> serialize_hnsw_config(const typename HNSWIndex<T, Metric>::
     blob.reserve(64);
 
     // Version marker (for future compatibility)
-    constexpr uint32_t version = 1;
+    constexpr uint32_t version = 2;
     auto write_u32 = [&](uint32_t val) {
         for (int i = 0; i < 4; ++i) {
             blob.push_back((val >> (i * 8)) & 0xFF);
@@ -47,15 +47,17 @@ std::vector<uint8_t> serialize_hnsw_config(const typename HNSWIndex<T, Metric>::
     write_u64(config.M_max_0);
     write_u64(config.ef_construction);
     write_f32(config.ml_factor);
+    write_u32(config.clamp_negative_distances ? 1U : 0U);
 
     return blob;
 }
 
 /// Deserialize HNSW index configuration from blob
 template <typename T, typename Metric>
 typename HNSWIndex<T, Metric>::Config deserialize_hnsw_config(const void* blob, size_t size) {
-    // Config blob: version(4) + M(8) + M_max(8) + M_max_0(8) + ef_construction(8) + ml_factor(4) =
-    // 40 bytes
+    // Config blob v1: version(4) + M(8) + M_max(8) + M_max_0(8) + ef_construction(8) + ml_factor(4)
+    // = 40 bytes
+    // Config blob v2: v1 + clamp_negative_distances(4) = 44 bytes
     if (size < 40) {
         throw std::runtime_error("Invalid HNSW config blob: too small");
     }
@@ -85,7 +87,7 @@ typename HNSWIndex<T, Metric>::Config deserialize_hnsw_config(const void* blob,
     };
 
     uint32_t version = read_u32();
-    if (version != 1) {
+    if (version != 1 && version != 2) {
         throw std::runtime_error("Unsupported HNSW config version");
     }
 
@@ -95,6 +97,14 @@ typename HNSWIndex<T, Metric>::Config deserialize_hnsw_config(const void* blob,
     config.M_max_0 = read_u64();
     config.ef_construction = read_u64();
     config.ml_factor = read_f32();
+    if (version >= 2) {
+        if (size < 44) {
+            throw std::runtime_error("Invalid HNSW config blob: missing clamp flag");
+        }
+        config.clamp_negative_distances = (read_u32() != 0);
+    } else {
+        config.clamp_negative_distances = true;
+    }
 
     return config;
 }