lodedb 1.2.0__tar.gz → 1.3.0__tar.gz

{lodedb-1.2.0 → lodedb-1.3.0}/Cargo.toml

@@ -7,7 +7,7 @@ members = [
 resolver = "2"
 
 [workspace.package]
-version = "1.2.0"
+version = "1.3.0"
 edition = "2021"
 rust-version = "1.70"
 license = "Apache-2.0"

{lodedb-1.2.0 → lodedb-1.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: lodedb
-Version: 1.2.0
+Version: 1.3.0
 Classifier: Development Status :: 4 - Beta
 Classifier: Intended Audience :: Developers
 Classifier: Programming Language :: Python :: 3 :: Only
@@ -89,12 +89,12 @@ All numbers are reported as the mean of 3 independent runs on a L40S server. [Fu
 > and it will migrate your existing store onto the LodeDB backend.
 
 Most embedded vector databases stop at the CPU. LodeDB runs the same on-disk index **on the
-GPU** when you have one: batched search hits *24k queries/sec on an A10 and 50k qps on an L40S*,
-2.8× to 4.8× the all-CPU ceiling, with recall unchanged. It also persists changed rows
-incrementally, so a commit stays **sub-millisecond even at 1M vectors**.
+GPU** when you have one: batched search hits *24k queries/sec on an A10 and 53k qps on an L40S*,
+with recall matching the CPU scan. It also persists changed rows incrementally, so a commit
+stays **sub-millisecond even at 1M vectors**.
 
-- **GPU-resident batch search**: an fp16 copy of the index lives on the GPU, scored with a
-  tiled GEMM plus a streaming top-k (`[gpu]`, Linux/CUDA). [How it works](#gpu-resident-index).
+- **GPU-resident batch search**: a float32 copy of the index lives on the GPU, scored with a
+  cuBLAS GEMM plus an on-device top-k (`[gpu]`, Linux/CUDA). [How it works](#gpu-resident-index).
 - **O(changed) persistence**: commits only the rows that changed, 173× to 1,308× faster
   than a full rewrite. [How it works](#delta-persistence).
 - **Compact storage**: the MIT [TurboVec](#turbovec) core packs vectors into 2/4-bit codes
@@ -289,37 +289,42 @@ operational gotchas live in [Deployment and performance](docs/deployment-and-per
 
 ## Hybrid search
 
-Vector search alone misses exact tokens the embedding does not capture: error codes
-(`E1234`), serial numbers (`ABC-123`), dates (`2024-01-15`). Pass `mode="hybrid"` to run a
-lexical BM25 ranker alongside the vector scan and fuse the two ranked lists with Reciprocal
-Rank Fusion. The lexical ranker matches those tokens exactly, so a document whose body carries
-the code is recovered even when the embedding ranks it nowhere near the top.
+Hybrid retrieval is the default. Vector search alone misses exact tokens the embedding does not
+capture: error codes (`E1234`), serial numbers (`ABC-123`), dates (`2024-01-15`). By default
+LodeDB runs a lexical BM25 ranker alongside the vector scan and fuses the two ranked lists with
+Reciprocal Rank Fusion, so a document whose body carries the code is recovered even when the
+embedding ranks it nowhere near the top. The default resolves to hybrid whenever a text source is
+available (the out-of-the-box configuration) and falls back to a plain vector scan otherwise, so
+it never raises on a vector-only store.
 
 ```python
 db.add("the turbine tripped and reported fault code E1234 overnight", metadata={"unit": "t3"})
 
-db.search("E1234", k=5)                 # mode="vector" (default): may miss the exact code
-db.search("E1234", k=5, mode="hybrid")  # BM25 + RRF: surfaces it in the top-k
-db.search("E1234", k=5, mode="lexical") # BM25 ranking alone, no vector scan
+db.search("E1234", k=5)                  # default: hybrid (BM25 + RRF) when text is retained
+db.search("E1234", k=5, mode="vector")   # vector scan alone: may miss the exact code
+db.search("E1234", k=5, mode="lexical")  # BM25 ranking alone, no vector scan
 ```
 
 <details>
 <summary><b>Prerequisites</b></summary>
 
 `mode="hybrid"` and `mode="lexical"` build a BM25 index over your text, so they need a text
-source enabled when you open the database. `mode="vector"` (the default) needs nothing.
+source enabled when you open the database. Both text sources are on by default, so the hybrid
+default works out of the box; `mode="vector"` needs nothing and is the automatic fallback when no
+text source is present.
 
 | Mode | Enable | Source of the BM25 index |
 | --- | --- | --- |
-| `"vector"` (default) | nothing | not used |
-| `"hybrid"`, `"lexical"` | `store_text=True` (on by default) | rebuilt in memory from the retained raw text |
-| `"hybrid"`, `"lexical"` | `index_text=True` (on by default, follows `store_text`) | a durable on-disk postings store, no raw text required |
+| `"hybrid"` (default), `"lexical"` | `store_text=True` (on by default) | rebuilt in memory from the retained raw text |
+| `"hybrid"` (default), `"lexical"` | `index_text=True` (on by default, follows `store_text`) | a durable on-disk postings store, no raw text required |
+| `"vector"` (fallback) | nothing | not used |
 
 Both sources are on by default, so hybrid and lexical work out of the box: `store_text=True`
 retains the raw text and `index_text` defaults to match it, persisting the lexical postings.
 Either source alone is enough, and `index_text` decouples from `store_text` when set explicitly.
-With neither source enabled (`store_text=False, index_text=False`), a hybrid or lexical query
-raises a clear, actionable error rather than silently degrading.
+With neither source enabled (`store_text=False, index_text=False`), the default resolves to a
+plain vector scan; an *explicit* `mode="hybrid"`/`"lexical"` then raises a clear, actionable
+error rather than silently degrading.
 </details>
 
 <details>
@@ -440,37 +445,43 @@ persists with the index. See [`docs/late-interaction.md`](docs/late-interaction.
 
 ## GPU-resident index
 
-With the `[gpu]` extra on a CUDA host, LodeDB reconstructs the compact index into an fp16
-matrix resident on the GPU and scores batched `search_many` with a tiled GEMM plus a
-streaming top-k. It is opt-in and lazy: single queries, non-CUDA hosts, and GPU-memory
+With the `[gpu]` extra on a CUDA host, LodeDB keeps a reconstructed float32 copy of the
+compact index resident on the GPU and scores a batched `search_many` with a cuBLAS GEMM plus
+an on-device top-k. It is opt-in and lazy: single queries, non-CUDA hosts, and GPU-memory
 rejection fall back to the CPU scan, which stays the source of truth.
 
-GPU throughput climbs with batch size while the CPU scan is flat. Same 4-bit index
-(d=1536, 100K), same host, only the scoring step differs. Crossover is around batch 50:
+Both scans stream the corpus once per batch and amortize that read across the queries, so
+per-query throughput climbs with batch size; the GPU pulls away as the batch grows and its
+parallelism dominates. End-to-end through the public arrays API
+(`search_many_by_vector_arrays`, scores and ids) on a 4-bit index (d=1536, 100K):
 
 | query batch | A10 GPU | L40S GPU |
 |---:|---:|---:|
-| 1 | 261 q/s | 432 q/s |
-| 16 | 3,531 | 5,562 |
-| 64 | 11,463 | 18,175 |
-| 256 | 19,998 | 39,449 |
-| 1024 | **24,037** | **50,326** |
+| 16 | 8,413 | 12,469 |
+| 64 | 19,030 | 33,040 |
+| 256 | 23,669 | 49,927 |
+| 1024 | **24,359** | **52,940** |
 
-Vanilla TurboVec CPU (all threads) on the same boxes: 8,497 q/s (A10 host), 10,420 q/s
-(L40S host). At batch 1024 the GPU is 2.8× / 4.8× that, and it scales with GPU class.
+These are the arrays fast path; the default hits API (per-hit result objects) runs somewhat
+lower, about 18.4k / 35.6k q/s at batch 1024. A single query stays on the CPU (the GPU batch
+path engages at batch >= 4) and is one exact scan over the whole corpus, so its cost is bound
+by memory bandwidth rather than the API; batching amortizes that corpus read, which is what
+the throughput above exploits.
 
-![GPU throughput vs batch size: A10 and L40S vs the vanilla CPU scan](benchmarks/gpu_vanilla_vs_augmented/docs/speed_batch.png)
+The curves below are the GPU and CPU scans through that same default hits API, so the gap is
+like-for-like:
 
-Recall is unchanged: the GPU scores the exact 4-bit reconstruction, so R@1 tracks the CPU
-scan across datasets and bit-widths, and edges ahead on GloVe-200 where quantization error
-is largest.
+![Native vector-search throughput: GPU vs CPU on the default hits API](benchmarks/vector_search_native/docs/throughput_batch.png)
 
-![Recall: vanilla CPU scan vs GPU fp16 reconstruction](benchmarks/gpu_vanilla_vs_augmented/docs/recall.png)
+A one-line reproduction is in [benchmarks/vector_search_native](benchmarks/vector_search_native/).
+
+Recall matches the CPU scan: the GPU scores the same 4-bit reconstruction, and LodeDB's
+parity tests hold its document recall within 0.002 of the CPU scan across batch sizes, so
+moving a query to the GPU changes its latency, not its results.
 
 Other in-process vector databases stay CPU-bound. Alibaba's
 [zvec](https://github.com/alibaba/zvec) reports about 8.4k q/s (VectorDBBench, 16-vCPU CPU,
-Cohere 768-dim): the same class as the TurboVec CPU scan, and a different regime from ours,
-so read it as the CPU-class baseline. The GPU-resident path is what clears it.
+Cohere 768-dim); read it as the CPU-class baseline that the GPU-resident path clears.
 
 **Scope.** GPU search is Linux/CUDA-only and opt-in (`[gpu]`). macOS scans on the CPU by
 default; a first-class opt-in MPS exact scan exists (`LODEDB_MPS_DIRECT_TURBOVEC`) but NEON
@@ -489,8 +500,6 @@ rows that changed (O(changed)), so a 1,000-row commit stays sub-millisecond at a
 | 500K | 190.4 ms | 0.24 ms | 782× |
 | 1M | 404.9 ms | 0.31 ms | **1,308×** |
 
-![Persist time: full rewrite vs delta export](benchmarks/gpu_vanilla_vs_augmented/docs/update.png)
-
 The GPU path makes reads fast; the delta makes writes cheap. The on-disk format stays a
 plain snapshot that replays on reopen.
 
@@ -513,8 +522,6 @@ and the complete figure set are in [docs/benchmarks.md](docs/benchmarks.md); eac
 Local is the common case. On an Apple M1 (MiniLM, 20K docs) the CPU scan is ~0.25 ms p50,
 and end-to-end single-query latency is 5.7 ms p50.
 
-![Single-query latency on a laptop](benchmarks/laptop/docs/query_latency.png)
-
 ## CLI
 
 ```bash

{lodedb-1.2.0 → lodedb-1.3.0}/README.md

@@ -40,12 +40,12 @@ All numbers are reported as the mean of 3 independent runs on a L40S server. [Fu
 > and it will migrate your existing store onto the LodeDB backend.
 
 Most embedded vector databases stop at the CPU. LodeDB runs the same on-disk index **on the
-GPU** when you have one: batched search hits *24k queries/sec on an A10 and 50k qps on an L40S*,
-2.8× to 4.8× the all-CPU ceiling, with recall unchanged. It also persists changed rows
-incrementally, so a commit stays **sub-millisecond even at 1M vectors**.
+GPU** when you have one: batched search hits *24k queries/sec on an A10 and 53k qps on an L40S*,
+with recall matching the CPU scan. It also persists changed rows incrementally, so a commit
+stays **sub-millisecond even at 1M vectors**.
 
-- **GPU-resident batch search**: an fp16 copy of the index lives on the GPU, scored with a
-  tiled GEMM plus a streaming top-k (`[gpu]`, Linux/CUDA). [How it works](#gpu-resident-index).
+- **GPU-resident batch search**: a float32 copy of the index lives on the GPU, scored with a
+  cuBLAS GEMM plus an on-device top-k (`[gpu]`, Linux/CUDA). [How it works](#gpu-resident-index).
 - **O(changed) persistence**: commits only the rows that changed, 173× to 1,308× faster
   than a full rewrite. [How it works](#delta-persistence).
 - **Compact storage**: the MIT [TurboVec](#turbovec) core packs vectors into 2/4-bit codes
@@ -240,37 +240,42 @@ operational gotchas live in [Deployment and performance](docs/deployment-and-per
 
 ## Hybrid search
 
-Vector search alone misses exact tokens the embedding does not capture: error codes
-(`E1234`), serial numbers (`ABC-123`), dates (`2024-01-15`). Pass `mode="hybrid"` to run a
-lexical BM25 ranker alongside the vector scan and fuse the two ranked lists with Reciprocal
-Rank Fusion. The lexical ranker matches those tokens exactly, so a document whose body carries
-the code is recovered even when the embedding ranks it nowhere near the top.
+Hybrid retrieval is the default. Vector search alone misses exact tokens the embedding does not
+capture: error codes (`E1234`), serial numbers (`ABC-123`), dates (`2024-01-15`). By default
+LodeDB runs a lexical BM25 ranker alongside the vector scan and fuses the two ranked lists with
+Reciprocal Rank Fusion, so a document whose body carries the code is recovered even when the
+embedding ranks it nowhere near the top. The default resolves to hybrid whenever a text source is
+available (the out-of-the-box configuration) and falls back to a plain vector scan otherwise, so
+it never raises on a vector-only store.
 
 ```python
 db.add("the turbine tripped and reported fault code E1234 overnight", metadata={"unit": "t3"})
 
-db.search("E1234", k=5)                 # mode="vector" (default): may miss the exact code
-db.search("E1234", k=5, mode="hybrid")  # BM25 + RRF: surfaces it in the top-k
-db.search("E1234", k=5, mode="lexical") # BM25 ranking alone, no vector scan
+db.search("E1234", k=5)                  # default: hybrid (BM25 + RRF) when text is retained
+db.search("E1234", k=5, mode="vector")   # vector scan alone: may miss the exact code
+db.search("E1234", k=5, mode="lexical")  # BM25 ranking alone, no vector scan
 ```
 
 <details>
 <summary><b>Prerequisites</b></summary>
 
 `mode="hybrid"` and `mode="lexical"` build a BM25 index over your text, so they need a text
-source enabled when you open the database. `mode="vector"` (the default) needs nothing.
+source enabled when you open the database. Both text sources are on by default, so the hybrid
+default works out of the box; `mode="vector"` needs nothing and is the automatic fallback when no
+text source is present.
 
 | Mode | Enable | Source of the BM25 index |
 | --- | --- | --- |
-| `"vector"` (default) | nothing | not used |
-| `"hybrid"`, `"lexical"` | `store_text=True` (on by default) | rebuilt in memory from the retained raw text |
-| `"hybrid"`, `"lexical"` | `index_text=True` (on by default, follows `store_text`) | a durable on-disk postings store, no raw text required |
+| `"hybrid"` (default), `"lexical"` | `store_text=True` (on by default) | rebuilt in memory from the retained raw text |
+| `"hybrid"` (default), `"lexical"` | `index_text=True` (on by default, follows `store_text`) | a durable on-disk postings store, no raw text required |
+| `"vector"` (fallback) | nothing | not used |
 
 Both sources are on by default, so hybrid and lexical work out of the box: `store_text=True`
 retains the raw text and `index_text` defaults to match it, persisting the lexical postings.
 Either source alone is enough, and `index_text` decouples from `store_text` when set explicitly.
-With neither source enabled (`store_text=False, index_text=False`), a hybrid or lexical query
-raises a clear, actionable error rather than silently degrading.
+With neither source enabled (`store_text=False, index_text=False`), the default resolves to a
+plain vector scan; an *explicit* `mode="hybrid"`/`"lexical"` then raises a clear, actionable
+error rather than silently degrading.
 </details>
 
 <details>
@@ -391,37 +396,43 @@ persists with the index. See [`docs/late-interaction.md`](docs/late-interaction.
 
 ## GPU-resident index
 
-With the `[gpu]` extra on a CUDA host, LodeDB reconstructs the compact index into an fp16
-matrix resident on the GPU and scores batched `search_many` with a tiled GEMM plus a
-streaming top-k. It is opt-in and lazy: single queries, non-CUDA hosts, and GPU-memory
+With the `[gpu]` extra on a CUDA host, LodeDB keeps a reconstructed float32 copy of the
+compact index resident on the GPU and scores a batched `search_many` with a cuBLAS GEMM plus
+an on-device top-k. It is opt-in and lazy: single queries, non-CUDA hosts, and GPU-memory
 rejection fall back to the CPU scan, which stays the source of truth.
 
-GPU throughput climbs with batch size while the CPU scan is flat. Same 4-bit index
-(d=1536, 100K), same host, only the scoring step differs. Crossover is around batch 50:
+Both scans stream the corpus once per batch and amortize that read across the queries, so
+per-query throughput climbs with batch size; the GPU pulls away as the batch grows and its
+parallelism dominates. End-to-end through the public arrays API
+(`search_many_by_vector_arrays`, scores and ids) on a 4-bit index (d=1536, 100K):
 
 | query batch | A10 GPU | L40S GPU |
 |---:|---:|---:|
-| 1 | 261 q/s | 432 q/s |
-| 16 | 3,531 | 5,562 |
-| 64 | 11,463 | 18,175 |
-| 256 | 19,998 | 39,449 |
-| 1024 | **24,037** | **50,326** |
+| 16 | 8,413 | 12,469 |
+| 64 | 19,030 | 33,040 |
+| 256 | 23,669 | 49,927 |
+| 1024 | **24,359** | **52,940** |
 
-Vanilla TurboVec CPU (all threads) on the same boxes: 8,497 q/s (A10 host), 10,420 q/s
-(L40S host). At batch 1024 the GPU is 2.8× / 4.8× that, and it scales with GPU class.
+These are the arrays fast path; the default hits API (per-hit result objects) runs somewhat
+lower, about 18.4k / 35.6k q/s at batch 1024. A single query stays on the CPU (the GPU batch
+path engages at batch >= 4) and is one exact scan over the whole corpus, so its cost is bound
+by memory bandwidth rather than the API; batching amortizes that corpus read, which is what
+the throughput above exploits.
 
-![GPU throughput vs batch size: A10 and L40S vs the vanilla CPU scan](benchmarks/gpu_vanilla_vs_augmented/docs/speed_batch.png)
+The curves below are the GPU and CPU scans through that same default hits API, so the gap is
+like-for-like:
 
-Recall is unchanged: the GPU scores the exact 4-bit reconstruction, so R@1 tracks the CPU
-scan across datasets and bit-widths, and edges ahead on GloVe-200 where quantization error
-is largest.
+![Native vector-search throughput: GPU vs CPU on the default hits API](benchmarks/vector_search_native/docs/throughput_batch.png)
 
-![Recall: vanilla CPU scan vs GPU fp16 reconstruction](benchmarks/gpu_vanilla_vs_augmented/docs/recall.png)
+A one-line reproduction is in [benchmarks/vector_search_native](benchmarks/vector_search_native/).
+
+Recall matches the CPU scan: the GPU scores the same 4-bit reconstruction, and LodeDB's
+parity tests hold its document recall within 0.002 of the CPU scan across batch sizes, so
+moving a query to the GPU changes its latency, not its results.
 
 Other in-process vector databases stay CPU-bound. Alibaba's
 [zvec](https://github.com/alibaba/zvec) reports about 8.4k q/s (VectorDBBench, 16-vCPU CPU,
-Cohere 768-dim): the same class as the TurboVec CPU scan, and a different regime from ours,
-so read it as the CPU-class baseline. The GPU-resident path is what clears it.
+Cohere 768-dim); read it as the CPU-class baseline that the GPU-resident path clears.
 
 **Scope.** GPU search is Linux/CUDA-only and opt-in (`[gpu]`). macOS scans on the CPU by
 default; a first-class opt-in MPS exact scan exists (`LODEDB_MPS_DIRECT_TURBOVEC`) but NEON
@@ -440,8 +451,6 @@ rows that changed (O(changed)), so a 1,000-row commit stays sub-millisecond at a
 | 500K | 190.4 ms | 0.24 ms | 782× |
 | 1M | 404.9 ms | 0.31 ms | **1,308×** |
 
-![Persist time: full rewrite vs delta export](benchmarks/gpu_vanilla_vs_augmented/docs/update.png)
-
 The GPU path makes reads fast; the delta makes writes cheap. The on-disk format stays a
 plain snapshot that replays on reopen.
 
@@ -464,8 +473,6 @@ and the complete figure set are in [docs/benchmarks.md](docs/benchmarks.md); eac
 Local is the common case. On an Apple M1 (MiniLM, 20K docs) the CPU scan is ~0.25 ms p50,
 and end-to-end single-query latency is 5.7 ms p50.
 
-![Single-query latency on a laptop](benchmarks/laptop/docs/query_latency.png)
-
 ## CLI
 
 ```bash

{lodedb-1.2.0 → lodedb-1.3.0}/crates/lodedb-core/Cargo.toml

@@ -12,6 +12,10 @@ name = "lodedb_core"
 
 [dependencies]
 lodedb-gpu = { path = "../lodedb-gpu" }
+# Parallelizes the ANN cluster-index build (k-means seeding + assignment) across
+# cores. Same version TurboVec already pins, and rayon's public API is safe, so
+# lodedb-core keeps unsafe_code = forbid.
+rayon = "1.10"
 serde = { version = "1.0", features = ["derive"] }
 serde_json = "1.0"
 sha2 = "0.10"

{lodedb-1.2.0 → lodedb-1.3.0}/crates/lodedb-core/src/vector/ann.rs

@@ -14,13 +14,18 @@
 //! Everything here is deterministic: no clocks, no RNG (`unsafe_code = forbid`
 //! and no `rand` dependency), fixed iteration counts, and stable-order tie
 //! breaks. The same corpus always yields the same clustering and the same
-//! candidates. Vectors are the TurboVec-reconstructed rows (rotated space), and
-//! the index stores the matching rotation so it can rotate a raw query into that
-//! space itself before scoring centroids. The metric is dot product to match the
-//! exact scan.
+//! candidates. The seeding and assignment passes run under rayon, but each is
+//! order-preserving (indexed collects) or per-element independent (an in-place
+//! max), so the clustering never depends on thread count or scheduling and is
+//! byte-identical to a serial build. Vectors are the TurboVec-reconstructed rows
+//! (rotated space), and the index stores the matching rotation so it can rotate a
+//! raw query into that space itself before scoring centroids. The metric is dot
+//! product to match the exact scan.
 
 use std::cmp::Ordering;
 
+use rayon::prelude::*;
+
 use crate::vector::math::{dot, rotate};
 
 /// Lloyd iterations for the cluster build. Candidate generation needs a decent
@@ -65,12 +70,13 @@ impl ClusterIndex {
         let n = entries.len();
         let k = requested_k.clamp(1, n.max(1));
 
-        // Deterministic farthest-first seeding: start from the first (lowest
-        // chunk id) row, then repeatedly take the unseeded row least similar to
-        // every seed chosen so far. No RNG. Only unseeded rows are considered, so
-        // a zero- or low-norm first row (whose dot with everything is near zero)
-        // cannot make the search re-pick an already-seeded index and collapse the
-        // corpus to a single cluster.
+        // Deterministic farthest-first seeding: start from the first (lowest chunk
+        // id) row, then repeatedly take the unseeded row least similar to every seed
+        // chosen so far. No RNG. Only unseeded rows are considered, so a zero- or
+        // low-norm first row (whose dot with everything is near zero) cannot make the
+        // search re-pick an already-seeded index and collapse the corpus to a single
+        // cluster. Each seed's similarity fold over the corpus is parallel; the
+        // argmin pick is a cheap serial scan with a lowest-index tie-break.
         let mut seeds: Vec<usize> = Vec::with_capacity(k);
         let mut seeded = vec![false; n];
         seeds.push(0);
@@ -104,24 +110,13 @@ impl ClusterIndex {
             centroids[cluster * dim..(cluster + 1) * dim].copy_from_slice(entries[row].2);
         }
 
-        // Lloyd iterations: assign by max dot product, update centroids to the
-        // mean of their members. Means accumulate in f64 in a fixed order so the
-        // build is bit-reproducible for the same entries.
-        let mut assignment = vec![usize::MAX; n];
-        for _ in 0..MAX_ITERS {
-            let mut changed = false;
-            for (i, entry) in entries.iter().enumerate() {
-                let cluster = nearest_centroid(entry.2, &centroids, cluster_count, dim);
-                if cluster != assignment[i] {
-                    assignment[i] = cluster;
-                    changed = true;
-                }
-            }
-            if !changed {
-                break;
-            }
-            recompute_centroids(&mut centroids, entries, &assignment, cluster_count, dim);
-        }
+        // Lloyd iterations: assign every row to its nearest centroid (parallel) and
+        // update centroids to the f64 mean of their members (serial, fixed order so
+        // the means are bit-reproducible). Both parallel passes are order-preserving
+        // or per-row independent, so the clustering is byte-identical regardless of
+        // thread count, and the final centroids are the means of the returned
+        // assignment (so a persisted reload via `from_assignment` reproduces them).
+        let assignment = lloyd(&mut centroids, entries, cluster_count, dim);
 
         // Materialize postings and drop empty clusters. An empty cluster owns no
         // chunks, so probing it can only waste a probe slot; dropping it keeps
@@ -352,6 +347,48 @@ fn write_cluster_mean(centroid: &mut [f32], sum: &[f64], count: usize) {
     }
 }
 
+/// Runs Lloyd's algorithm in place over `entries`: assign every entry to its
+/// nearest centroid (parallel), update each centroid to the f64 mean of its
+/// members (sequential, fixed order for bit-reproducibility), repeat up to
+/// [`MAX_ITERS`] with an unchanged-assignment early exit. Returns the final
+/// assignment. On an early exit the centroids are the means of that assignment
+/// *and* every entry's nearest centroid is its assigned cluster; at the iteration
+/// cap only the former holds. Empty clusters keep their prior centroid and are
+/// dropped later by the caller.
+fn lloyd(
+    centroids: &mut [f32],
+    entries: &[ClusterEntry<'_>],
+    cluster_count: usize,
+    dim: usize,
+) -> Vec<usize> {
+    let mut assignment = vec![usize::MAX; entries.len()];
+    for _ in 0..MAX_ITERS {
+        let next = assign_all(entries, centroids, cluster_count, dim);
+        if next == assignment {
+            break;
+        }
+        assignment = next;
+        recompute_centroids(centroids, entries, &assignment, cluster_count, dim);
+    }
+    assignment
+}
+
+/// Assigns every entry to its nearest centroid, in parallel. The per-row result
+/// depends only on that row and the (shared, read-only) centroids, and the
+/// indexed collect preserves order, so the assignment is byte-identical to a
+/// sequential pass regardless of thread count.
+fn assign_all(
+    entries: &[ClusterEntry<'_>],
+    centroids: &[f32],
+    cluster_count: usize,
+    dim: usize,
+) -> Vec<usize> {
+    entries
+        .par_iter()
+        .map(|entry| nearest_centroid(entry.2, centroids, cluster_count, dim))
+        .collect()
+}
+
 fn nearest_centroid(vector: &[f32], centroids: &[f32], cluster_count: usize, dim: usize) -> usize {
     let mut best = 0usize;
     let mut best_dot = f32::NEG_INFINITY;
@@ -368,13 +405,19 @@ fn nearest_centroid(vector: &[f32], centroids: &[f32], cluster_count: usize, dim
     best
 }
 
+/// Folds a newly chosen seed's similarities into the running per-row nearest-seed
+/// maxima, in parallel. Each slot is updated from its own row only (an in-place
+/// max), so the result is independent of thread count.
 fn update_nearest(nearest: &mut [f32], entries: &[ClusterEntry<'_>], centroid: &[f32]) {
-    for (slot, entry) in nearest.iter_mut().zip(entries) {
-        let similarity = dot(entry.2, centroid);
-        if similarity > *slot {
-            *slot = similarity;
-        }
-    }
+    nearest
+        .par_iter_mut()
+        .zip(entries.par_iter())
+        .for_each(|(slot, entry)| {
+            let similarity = dot(entry.2, centroid);
+            if similarity > *slot {
+                *slot = similarity;
+            }
+        });
 }
 
 #[cfg(test)]
@@ -554,6 +597,34 @@ mod tests {
         );
     }
 
+    #[test]
+    fn parallel_build_recovers_each_row_with_a_single_probe() {
+        // Posting/centroid consistency on a larger, converging corpus: after the
+        // parallel Lloyd, each row's own cluster is the one a self-query scores
+        // highest, so probing just the single nearest cluster recovers the row. This
+        // guards against the centroids drifting out of sync with the postings they
+        // were grouped from (which would drop true neighbors from the probed set).
+        let mut rows = Vec::new();
+        for blob in 0..8 {
+            for i in 0..40 {
+                let mut vector = vec![0.0f32; 8];
+                vector[blob] = 1.0;
+                vector[(blob + 1) % 8] = 0.001 * (i as f32 + 1.0);
+                rows.push((format!("b{blob}c{i:02}"), vector));
+            }
+        }
+        let (owned, reverse) = entries(&rows);
+        let index = ClusterIndex::build(&refs(&owned), 8, 16, None);
+        assert_eq!(index.num_vectors(), owned.len());
+        for (id, _, vector) in &owned {
+            let hits = chunk_ids(&index.candidate_stable_ids(vector, 1, 1), &reverse);
+            assert!(
+                hits.contains(id),
+                "self-query for {id} must probe the cluster that owns it"
+            );
+        }
+    }
+
     #[test]
     fn handles_k_larger_than_corpus_and_identical_vectors() {
         let rows: Vec<(String, Vec<f32>)> = (0..3)