ruvector 0.1.0__tar.gz → 0.1.2__tar.gz

{ruvector-0.1.0 → ruvector-0.1.2}/Cargo.lock

@@ -10759,7 +10759,7 @@ dependencies = [
 
 [[package]]
 name = "ruvector-py"
-version = "0.1.0"
+version = "0.1.2"
 dependencies = [
  "numpy",
  "pyo3",

{ruvector-0.1.0 → ruvector-0.1.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ruvector
-Version: 0.1.0
+Version: 0.1.2
 Classifier: Development Status :: 3 - Alpha
 Classifier: Programming Language :: Rust
 Classifier: Programming Language :: Python :: 3
@@ -9,6 +9,7 @@ Classifier: Programming Language :: Python :: 3.10
 Classifier: Programming Language :: Python :: 3.11
 Classifier: Programming Language :: Python :: 3.12
 Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
 Classifier: Programming Language :: Python :: Implementation :: CPython
 Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
 Classifier: Topic :: Database :: Database Engines/Servers
@@ -136,6 +137,7 @@ ruvector benchmark -n 100000 --dim 128     # in-process latency/QPS, no external
 ruvector serve                             # MCP server over stdio
 ruvector serve --http --port 8420          # MCP server over streamable-HTTP (loopback)
 ruvector serve --read-only                 # no create/insert/delete tools
+ruvector serve --max-vectors 50000         # cap vectors per collection (default 1,000,000)
 ```
 
 `serve --http` on a non-loopback `--host` refuses to start unless
@@ -161,6 +163,16 @@ directory-traversal surface regardless of what a remote MCP client sends.
 See `ruvector/mcp_server.py`'s module docstring for the full security
 model.
 
+Write size is capped. Per call: 10,000 rows, 2,000,000 floats in total, and
+64 KiB of serialized metadata per row. Per collection: 1,000,000 vectors by
+default, counting deleted-but-not-vacuumed rows; `vector_insert` and
+`vector_insert_batch` fail with a `ToolError` that names the limit once it
+would be exceeded. Change it with `ruvector serve --max-vectors N` or
+`RUVECTOR_MCP_MAX_VECTORS=N` (the option wins; a non-positive or non-integer
+value stops the server at startup). The server re-saves the whole collection
+on every write, so keep this cap well below what your disk and latency budget
+can take.
+
 ```sh
 # point an MCP client at: ruvector serve   (stdio)
 # or:                      ruvector serve --http --port 8420

{ruvector-0.1.0 → ruvector-0.1.2}/README.md

@@ -88,6 +88,7 @@ ruvector benchmark -n 100000 --dim 128     # in-process latency/QPS, no external
 ruvector serve                             # MCP server over stdio
 ruvector serve --http --port 8420          # MCP server over streamable-HTTP (loopback)
 ruvector serve --read-only                 # no create/insert/delete tools
+ruvector serve --max-vectors 50000         # cap vectors per collection (default 1,000,000)
 ```
 
 `serve --http` on a non-loopback `--host` refuses to start unless
@@ -113,6 +114,16 @@ directory-traversal surface regardless of what a remote MCP client sends.
 See `ruvector/mcp_server.py`'s module docstring for the full security
 model.
 
+Write size is capped. Per call: 10,000 rows, 2,000,000 floats in total, and
+64 KiB of serialized metadata per row. Per collection: 1,000,000 vectors by
+default, counting deleted-but-not-vacuumed rows; `vector_insert` and
+`vector_insert_batch` fail with a `ToolError` that names the limit once it
+would be exceeded. Change it with `ruvector serve --max-vectors N` or
+`RUVECTOR_MCP_MAX_VECTORS=N` (the option wins; a non-positive or non-integer
+value stops the server at startup). The server re-saves the whole collection
+on every write, so keep this cap well below what your disk and latency budget
+can take.
+
 ```sh
 # point an MCP client at: ruvector serve   (stdio)
 # or:                      ruvector serve --http --port 8420

{ruvector-0.1.0 → ruvector-0.1.2}/crates/ruvector-py/Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "ruvector-py"
-version = "0.1.0"
+version = "0.1.2"
 edition = "2021"
 rust-version.workspace = true
 license = "MIT"

{ruvector-0.1.0 → ruvector-0.1.2}/crates/ruvector-py/README.md

@@ -88,6 +88,7 @@ ruvector benchmark -n 100000 --dim 128     # in-process latency/QPS, no external
 ruvector serve                             # MCP server over stdio
 ruvector serve --http --port 8420          # MCP server over streamable-HTTP (loopback)
 ruvector serve --read-only                 # no create/insert/delete tools
+ruvector serve --max-vectors 50000         # cap vectors per collection (default 1,000,000)
 ```
 
 `serve --http` on a non-loopback `--host` refuses to start unless
@@ -113,6 +114,16 @@ directory-traversal surface regardless of what a remote MCP client sends.
 See `ruvector/mcp_server.py`'s module docstring for the full security
 model.
 
+Write size is capped. Per call: 10,000 rows, 2,000,000 floats in total, and
+64 KiB of serialized metadata per row. Per collection: 1,000,000 vectors by
+default, counting deleted-but-not-vacuumed rows; `vector_insert` and
+`vector_insert_batch` fail with a `ToolError` that names the limit once it
+would be exceeded. Change it with `ruvector serve --max-vectors N` or
+`RUVECTOR_MCP_MAX_VECTORS=N` (the option wins; a non-positive or non-integer
+value stops the server at startup). The server re-saves the whole collection
+on every write, so keep this cap well below what your disk and latency budget
+can take.
+
 ```sh
 # point an MCP client at: ruvector serve   (stdio)
 # or:                      ruvector serve --http --port 8420

{ruvector-0.1.0 → ruvector-0.1.2}/crates/ruvector-py/src/rabitq.rs

@@ -12,6 +12,7 @@
 //! and `RabitqAsymIndex` as separate Python classes per the surface sketch in
 //! `docs/sdk/03-api-surface.md`. M1 ships exactly one class.
 
+use std::collections::HashSet;
 use std::fs::File;
 use std::io::{BufReader, BufWriter};
 
@@ -50,6 +51,53 @@ pub struct RabitqIndex {
     // to keep a redundant copy here. The seed lives separately because
     // `RabitqPlusIndex` doesn't expose its own seed field.
     seed: u64,
+    // Ids currently in the index, so `add`/`add_batch` can reject a duplicate in O(1).
+    ids: HashSet<u32>,
+}
+
+/// Describe a Python object for an error message (dtype and ndim when it is an array).
+fn describe(obj: &Bound<'_, PyAny>) -> String {
+    match (obj.getattr("dtype"), obj.getattr("ndim")) {
+        (Ok(d), Ok(n)) => format!("dtype={d}, ndim={n}"),
+        _ => obj
+            .get_type()
+            .name()
+            .map(|n| n.to_string())
+            .unwrap_or_else(|_| "an unknown object".into()),
+    }
+}
+
+fn arr1<'py>(obj: &Bound<'py, PyAny>, name: &str) -> PyResult<PyReadonlyArray1<'py, f32>> {
+    obj.extract().map_err(|_| {
+        PyTypeError::new_err(format!(
+            "{name} must be a 1D float32 NumPy array, got {}; convert with np.ascontiguousarray(x, dtype=np.float32)",
+            describe(obj)
+        ))
+    })
+}
+
+fn arr2<'py>(obj: &Bound<'py, PyAny>, name: &str) -> PyResult<PyReadonlyArray2<'py, f32>> {
+    obj.extract().map_err(|_| {
+        PyTypeError::new_err(format!(
+            "{name} must be a 2D float32 NumPy array, got {}; convert with np.ascontiguousarray(x, dtype=np.float32)",
+            describe(obj)
+        ))
+    })
+}
+
+/// Reject NaN and infinity, which would otherwise be indexed or searched and yield NaN scores.
+fn check_finite(data: &[f32], dim: usize, name: &str) -> PyResult<()> {
+    match data.iter().position(|x| !x.is_finite()) {
+        None => Ok(()),
+        Some(i) if dim > 0 && data.len() > dim => Err(PyValueError::new_err(format!(
+            "{name} contains a non-finite value (NaN or inf) at row {}, column {}",
+            i / dim,
+            i % dim
+        ))),
+        Some(i) => Err(PyValueError::new_err(format!(
+            "{name} contains a non-finite value (NaN or inf) at position {i}"
+        ))),
+    }
 }
 
 #[pymethods]
@@ -61,8 +109,15 @@ impl RabitqIndex {
     /// silently copying — silent copies would be an O(n·dim) surprise on a
     /// "fast" build call.
     ///
-    /// `rerank_factor` defaults to 20 per `docs/sdk/03-api-surface.md`'s
-    /// "100% recall@10 at D=128" recommendation citing ADR-154.
+    /// `rerank_factor` defaults to 20. Recall depends on the data: ADR-154
+    /// reports 100% recall@10 at D=128 on clustered, embedding-like data, but
+    /// on isotropic Gaussian vectors (D=128, n=10k) a rerank_factor of 20 gives
+    /// about 0.63 recall@10 and 500 is needed for 1.0. Raise `rerank_factor`
+    /// (here or per `search` call) for hard distributions and measure recall
+    /// against brute force on your own data.
+    ///
+    /// Raises `ValueError` if `vectors` contains NaN or infinity, or if `ids`
+    /// contains a duplicate.
     ///
     /// `seed` defaults to 42 to keep the build deterministic out-of-the-box —
     /// the doc-comment guarantee on `ruvector_rabitq` is that
@@ -81,11 +136,12 @@ impl RabitqIndex {
     #[pyo3(signature = (vectors, *, ids = None, rerank_factor = 20, seed = 42))]
     fn build(
         py: Python<'_>,
-        vectors: PyReadonlyArray2<'_, f32>,
+        vectors: &Bound<'_, PyAny>,
         ids: Option<PyReadonlyArray1<'_, u64>>,
         rerank_factor: u32,
         seed: u64,
     ) -> PyResult<Self> {
+        let vectors = arr2(vectors, "vectors")?;
         // Validate the dtype/contig invariants up front. `PyReadonlyArray2`
         // already guarantees the dtype is f32 (otherwise the conversion at
         // the call site fails with `TypeError`). What it does NOT guarantee
@@ -122,6 +178,7 @@ impl RabitqIndex {
         // across rayon workers. PyO3 cannot give us mutable owned access
         // to NumPy storage without breaking the readonly contract.
         let slice = vectors.as_slice()?; // contiguous view, len = n*dim
+        check_finite(slice, dim, "vectors")?;
         let mut items: Vec<(usize, Vec<f32>)> = Vec::with_capacity(n);
         match ids {
             Some(ids_arr) => {
@@ -145,6 +202,12 @@ impl RabitqIndex {
                         )));
                     }
                 }
+                let mut seen = HashSet::with_capacity(ids_slice.len());
+                for &id in ids_slice {
+                    if !seen.insert(id) {
+                        return Err(PyValueError::new_err(format!("duplicate id {id} in ids")));
+                    }
+                }
                 for (i, &id) in ids_slice.iter().enumerate() {
                     let row = &slice[i * dim..(i + 1) * dim];
                     items.push((id as usize, row.to_vec()));
@@ -168,7 +231,8 @@ impl RabitqIndex {
             })
             .map_err(to_pyerr)?;
 
-        Ok(Self { inner, seed })
+        let ids = inner.ids_u64().into_iter().map(|i| i as u32).collect();
+        Ok(Self { inner, seed, ids })
     }
 
     /// Search for the `k` nearest neighbours of a single `query` vector.
@@ -185,10 +249,11 @@ impl RabitqIndex {
     fn search(
         &self,
         py: Python<'_>,
-        query: PyReadonlyArray1<'_, f32>,
+        query: &Bound<'_, PyAny>,
         k: usize,
         rerank_factor: Option<u32>,
     ) -> PyResult<Vec<(u32, f32)>> {
+        let query = arr1(query, "query")?;
         if !query.is_c_contiguous() {
             return Err(PyTypeError::new_err(
                 "query must be C-contiguous; pass np.ascontiguousarray(...) first",
@@ -198,6 +263,7 @@ impl RabitqIndex {
             return Err(PyValueError::new_err("k must be > 0"));
         }
         let q = query.as_slice()?;
+        check_finite(q, 0, "query")?;
 
         // `search_with_rerank` is the right entry point even when no
         // override is requested, because it is the common path the
@@ -263,7 +329,8 @@ impl RabitqIndex {
         let seed = u64::from_le_bytes(header[16..24].try_into().unwrap());
 
         let inner = persist::load_index(&mut r).map_err(to_pyerr)?;
-        Ok(Self { inner, seed })
+        let ids = inner.ids_u64().into_iter().map(|i| i as u32).collect();
+        Ok(Self { inner, seed, ids })
     }
 
     /// Number of indexed vectors (matches `AnnIndex::len`).
@@ -303,7 +370,8 @@ impl RabitqIndex {
     /// release/reacquire cost itself (same call made for `RabitqPlusIndex.add`
     /// in `docs/sdk/02-strategy.md`'s GIL table). Use `add_batch` for bulk
     /// inserts, which does release the GIL.
-    fn add(&mut self, id: u32, vector: PyReadonlyArray1<'_, f32>) -> PyResult<()> {
+    fn add(&mut self, id: u32, vector: &Bound<'_, PyAny>) -> PyResult<()> {
+        let vector = arr1(vector, "vector")?;
         if !vector.is_c_contiguous() {
             return Err(PyTypeError::new_err(
                 "vector must be C-contiguous; pass np.ascontiguousarray(...) first",
@@ -317,7 +385,14 @@ impl RabitqIndex {
                 v.len()
             )));
         }
+        check_finite(v, 0, "vector")?;
+        if self.ids.contains(&id) {
+            return Err(PyValueError::new_err(format!(
+                "id {id} is already in the index; ids must be unique"
+            )));
+        }
         self.inner.add(id as usize, v.to_vec()).map_err(to_pyerr)?;
+        self.ids.insert(id);
         Ok(())
     }
 
@@ -328,8 +403,9 @@ impl RabitqIndex {
         &mut self,
         py: Python<'_>,
         ids: PyReadonlyArray1<'_, u64>,
-        vectors: PyReadonlyArray2<'_, f32>,
+        vectors: &Bound<'_, PyAny>,
     ) -> PyResult<()> {
+        let vectors = arr2(vectors, "vectors")?;
         if !vectors.is_c_contiguous() {
             return Err(PyTypeError::new_err(
                 "vectors must be C-contiguous; pass np.ascontiguousarray(...) first",
@@ -371,6 +447,15 @@ impl RabitqIndex {
             }
         }
         let vecs_slice = vectors.as_slice()?;
+        check_finite(vecs_slice, dim, "vectors")?;
+        let mut batch_ids = HashSet::with_capacity(ids_slice.len());
+        for &id in &ids_slice {
+            if self.ids.contains(&(id as u32)) || !batch_ids.insert(id) {
+                return Err(PyValueError::new_err(format!(
+                    "id {id} is already in the index or repeated in the batch; ids must be unique"
+                )));
+            }
+        }
         let rows: Vec<(usize, Vec<f32>)> = (0..n)
             .map(|i| {
                 (
@@ -387,6 +472,7 @@ impl RabitqIndex {
             Ok(())
         })
         .map_err(to_pyerr)?;
+        self.ids.extend(batch_ids.into_iter().map(|i| i as u32));
         Ok(())
     }
 

ruvector-0.1.2/crates/ruvector-py/tests/perf/bench_collection.py

@@ -0,0 +1,84 @@
+"""Micro-benchmark for Collection insert / insert_batch / search / save / load.
+
+Not collected by pytest (no ``test_`` prefix). Run on a quiet machine:
+
+    python tests/perf/bench_collection.py --n 50000 --dim 256 --repeat 5
+
+Each figure is the median of ``--repeat`` runs; the spread (min..max) is printed
+beside it. Data is seeded, so runs are comparable across commits on one machine.
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import statistics
+import tempfile
+import time
+from pathlib import Path
+from typing import Callable, Dict, List
+
+import numpy as np
+
+from ruvector.collection import Collection
+
+
+def timed(fn: Callable[[], object]) -> float:
+    t0 = time.perf_counter()
+    fn()
+    return time.perf_counter() - t0
+
+
+def summarize(samples: List[float]) -> str:
+    return f"{statistics.median(samples) * 1000:9.2f} ms  [{min(samples) * 1000:.2f}..{max(samples) * 1000:.2f}]"
+
+
+def bench_backend(backend: str, n: int, dim: int, repeat: int, with_meta: bool) -> Dict[str, List[float]]:
+    rng = np.random.default_rng(0)
+    vecs = rng.standard_normal((n, dim)).astype(np.float32)
+    queries = rng.standard_normal((200, dim)).astype(np.float32)
+    metas = [{"i": i, "tag": f"t{i % 50}", "txt": "x" * 40} for i in range(n)] if with_meta else None
+    n_single = min(2000, n)
+    out: Dict[str, List[float]] = {k: [] for k in ("insert_x2000", "insert_batch", "from_vectors", "search_x200", "save", "load")}
+    for _ in range(repeat):
+        c = Collection.create(dim=dim, backend=backend)
+        if backend == "rabitq":  # first row builds; time the add() path after it
+            c.insert(vecs[0])
+        out["insert_x2000"].append(timed(lambda: [c.insert(vecs[i]) for i in range(1, n_single)]))
+        c = Collection.create(dim=dim, backend=backend)
+        out["insert_batch"].append(timed(lambda: c.insert_batch(vecs, metadatas=metas)))
+        out["from_vectors"].append(timed(lambda: Collection.from_vectors(vecs, backend=backend, metadatas=metas)))
+        if backend == "rabitq":
+            for i in range(0, n, 10):  # 10% tombstones, so search exercises the filter path
+                c.delete(i)
+        out["search_x200"].append(timed(lambda: [c.search(q, 10) for q in queries]))
+        with tempfile.TemporaryDirectory() as d:
+            p = Path(d) / "c.idx"
+            out["save"].append(timed(lambda: c.save(p)))
+            out["load"].append(timed(lambda: Collection.load(p)))
+    return out
+
+
+def main() -> None:
+    ap = argparse.ArgumentParser()
+    ap.add_argument("--n", type=int, default=50_000)
+    ap.add_argument("--dim", type=int, default=256)
+    ap.add_argument("--repeat", type=int, default=5)
+    ap.add_argument("--backends", default="hnsw,rabitq")
+    ap.add_argument("--no-metadata", action="store_true")
+    ap.add_argument("--json", action="store_true")
+    a = ap.parse_args()
+    results = {}
+    for backend in a.backends.split(","):
+        results[backend] = bench_backend(backend, a.n, a.dim, a.repeat, not a.no_metadata)
+    if a.json:
+        print(json.dumps({b: {k: statistics.median(v) for k, v in r.items()} for b, r in results.items()}))
+        return
+    print(f"n={a.n} dim={a.dim} repeat={a.repeat} metadata={'no' if a.no_metadata else 'yes'}")
+    for backend, r in results.items():
+        for name, samples in r.items():
+            print(f"{backend:7s} {name:14s} {summarize(samples)}")
+
+
+if __name__ == "__main__":
+    main()

{ruvector-0.1.0 → ruvector-0.1.2}/crates/ruvector-py/tests/test_cli.py

@@ -6,6 +6,7 @@ from __future__ import annotations
 
 import json
 from pathlib import Path
+from typing import Any, List, Optional
 
 import numpy as np
 import pytest
@@ -165,6 +166,41 @@ def test_benchmark_human_readable_has_data(runner: CliRunner) -> None:
     assert "dim=16" in r.output
 
 
+@pytest.mark.parametrize("backend", ["hnsw", "rabitq"])
+def test_benchmark_reports_recall(runner: CliRunner, backend: str) -> None:
+    r = runner.invoke(
+        main, ["benchmark", "-n", "400", "--dim", "16", "--queries", "15", "--backend", backend, "--json"]
+    )
+    assert r.exit_code == 0, r.output
+    result = json.loads(r.output)
+    assert result["backend"] == backend
+    assert result["recall_k"] == 10
+    assert 0.5 <= result["recall_at_10"] <= 1.0
+    # the existing latency fields are unchanged
+    for key in ("n", "dim", "k", "queries", "build_seconds", "p50_ms", "p99_ms", "qps"):
+        assert key in result
+
+
+def test_benchmark_recall_k_is_configurable_and_in_human_output(runner: CliRunner) -> None:
+    r = runner.invoke(main, ["benchmark", "-n", "300", "--dim", "8", "--queries", "10", "--recall-k", "5"])
+    assert r.exit_code == 0, r.output
+    assert "recall@5=" in r.output
+    j = json.loads(runner.invoke(main, ["benchmark", "-n", "300", "--dim", "8", "--queries", "10", "--recall-k", "5", "--json"]).output)
+    assert "recall_at_5" in j and "recall_at_10" not in j
+
+
+def test_benchmark_recall_is_exact_for_tiny_corpus(runner: CliRunner) -> None:
+    # n <= recall-k: every vector is in the top-k, so recall must be exactly 1.0
+    r = runner.invoke(main, ["benchmark", "-n", "6", "--dim", "8", "--queries", "5", "--recall-k", "10", "--json"])
+    assert r.exit_code == 0, r.output
+    assert json.loads(r.output)["recall_at_10"] == 1.0
+
+
+def test_benchmark_rejects_nonpositive_recall_k(runner: CliRunner) -> None:
+    r = runner.invoke(main, ["benchmark", "-n", "50", "--dim", "8", "--recall-k", "0"])
+    assert r.exit_code != 0
+
+
 def test_search_no_color_flag_forces_plain(runner: CliRunner, tmp_path: Path) -> None:
     """--no-color is a no-op in terms of data under CliRunner (already
     non-TTY => already plain), but exercise the flag itself end to end so
@@ -263,3 +299,39 @@ def test_serve_without_mcp_sdk_gives_install_hint(runner: CliRunner, monkeypatch
     assert result.exit_code != 0
     assert "ruvector[mcp]" in result.output
     assert "Traceback" not in result.output
+
+
+# ── serve --max-vectors ─────────────────────────────────────────────────────
+
+
+def test_serve_max_vectors_option_sets_cap(runner: CliRunner, monkeypatch: pytest.MonkeyPatch) -> None:
+    pytest.importorskip("mcp")
+    import ruvector.mcp_server as m
+
+    monkeypatch.delenv("RUVECTOR_MCP_MAX_VECTORS", raising=False)
+    monkeypatch.setattr(m.server, "run", lambda *a, **kw: None)
+    try:
+        result = runner.invoke(main, ["serve", "--max-vectors", "123"])
+        assert result.exit_code == 0, result.output
+        assert m.max_vectors() == 123
+    finally:
+        m.set_max_vectors(None)
+
+
+@pytest.mark.parametrize("args,env", [(["--max-vectors", "0"], None), ([], "nope")])
+def test_serve_rejects_bad_max_vectors(
+    runner: CliRunner, monkeypatch: pytest.MonkeyPatch, args: List[str], env: Optional[str]
+) -> None:
+    pytest.importorskip("mcp")
+    import ruvector.mcp_server as m
+
+    ran: List[Any] = []
+    monkeypatch.setattr(m.server, "run", lambda *a, **kw: ran.append(1))
+    if env is None:
+        monkeypatch.delenv("RUVECTOR_MCP_MAX_VECTORS", raising=False)
+    else:
+        monkeypatch.setenv("RUVECTOR_MCP_MAX_VECTORS", env)
+    result = runner.invoke(main, ["serve", *args])
+    assert result.exit_code != 0
+    assert "positive integer" in result.output
+    assert not ran

{ruvector-0.1.0 → ruvector-0.1.2}/crates/ruvector-py/tests/test_mcp_server.py

@@ -499,3 +499,107 @@ def test_apply_read_only_removes_mutating_tools(tmp_path: Path, monkeypatch: pyt
                 _call(m, gone, name="x")
     finally:
         importlib.reload(m)
+
+
+def test_validation_errors_reach_the_client():
+    """mcp 2.x masks non-ToolError exceptions; our validation messages must get through (issue #1134)."""
+    import asyncio
+
+    from mcp.server.mcpserver.exceptions import ToolError
+
+    from ruvector import mcp_server as m
+
+    async def call(name, args):
+        return await m.server.call_tool(name, args)
+
+    try:
+        asyncio.run(call("vector_create_collection", {"name": "../escape", "dim": 4}))
+    except ToolError as e:
+        assert "invalid collection name" in str(e)
+    else:
+        raise AssertionError("expected ToolError")
+    try:
+        asyncio.run(call("vector_search", {"name": "no-such-collection", "query": [1.0, 2.0, 3.0, 4.0], "k": 1}))
+    except ToolError as e:
+        assert "no such collection" in str(e)
+    else:
+        raise AssertionError("expected ToolError")
+
+
+# ── per-collection vector cap ────────────────────────────────────────────
+
+
+@pytest.fixture
+def capped(server_module: ModuleType, monkeypatch: pytest.MonkeyPatch) -> ModuleType:
+    monkeypatch.delenv("RUVECTOR_MCP_MAX_VECTORS", raising=False)
+    server_module.set_max_vectors(None)
+    yield server_module
+    server_module.set_max_vectors(None)
+
+
+def test_default_vector_cap_is_one_million(capped: ModuleType) -> None:
+    assert capped.max_vectors() == 1_000_000
+
+
+def test_env_var_sets_vector_cap_and_option_wins(capped: ModuleType, monkeypatch: pytest.MonkeyPatch) -> None:
+    monkeypatch.setenv("RUVECTOR_MCP_MAX_VECTORS", "7")
+    assert capped.max_vectors() == 7
+    capped.set_max_vectors(3)
+    assert capped.max_vectors() == 3
+    capped.set_max_vectors(None)
+    monkeypatch.setenv("RUVECTOR_MCP_MAX_VECTORS", "  ")
+    assert capped.max_vectors() == 1_000_000  # blank counts as unset
+
+
+@pytest.mark.parametrize("bad", ["0", "-5", "abc", "1.5"])
+def test_invalid_vector_cap_is_rejected(capped: ModuleType, monkeypatch: pytest.MonkeyPatch, bad: str) -> None:
+    monkeypatch.setenv("RUVECTOR_MCP_MAX_VECTORS", bad)
+    with pytest.raises(ValueError, match="RUVECTOR_MCP_MAX_VECTORS"):
+        capped.max_vectors()
+    with pytest.raises(ValueError):
+        capped.set_max_vectors(int(bad) if bad.lstrip("-").isdigit() else 0)
+
+
+def test_insert_stops_at_vector_cap(capped: ModuleType) -> None:
+    m = capped
+    m.set_max_vectors(2)
+    _call(m, "vector_create_collection", name="cap1", dim=2)
+    _call(m, "vector_insert", name="cap1", vector=[1.0, 0.0])
+    _call(m, "vector_insert", name="cap1", vector=[0.0, 1.0])
+    with _raises_chain(r"vector limit.*maximum of 2"):
+        _call(m, "vector_insert", name="cap1", vector=[1.0, 1.0])
+    assert _call(m, "vector_stats", name="cap1")["count"] == 2
+
+
+def test_batch_insert_is_all_or_nothing_at_cap(capped: ModuleType) -> None:
+    m = capped
+    m.set_max_vectors(3)
+    _call(m, "vector_create_collection", name="cap2", dim=2)
+    _call(m, "vector_insert_batch", name="cap2", vectors=[[1.0, 0.0], [0.0, 1.0]])
+    with _raises_chain("maximum of 3"):
+        _call(m, "vector_insert_batch", name="cap2", vectors=[[1.0, 1.0], [2.0, 2.0]])
+    assert _call(m, "vector_stats", name="cap2")["count"] == 2  # nothing partially written
+    _call(m, "vector_insert_batch", name="cap2", vectors=[[1.0, 1.0]])  # exactly reaches the cap
+    assert _call(m, "vector_stats", name="cap2")["count"] == 3
+
+
+def test_cap_message_is_a_tool_error(capped: ModuleType) -> None:
+    """mcp 2.x hides non-ToolError messages from the client; the cap text must survive."""
+    from mcp.server.mcpserver.exceptions import ToolError
+
+    m = capped
+    m.set_max_vectors(1)
+    _call(m, "vector_create_collection", name="cap3", dim=2)
+    _call(m, "vector_insert", name="cap3", vector=[1.0, 0.0])
+    with pytest.raises(ToolError, match="vector limit"):
+        asyncio.run(m.server.call_tool("vector_insert", {"name": "cap3", "vector": [0.0, 1.0]}))
+
+
+@pytest.mark.parametrize("backend", ["hnsw", "rabitq"])
+def test_deleted_rows_count_until_vacuumed(capped: ModuleType, backend: str) -> None:
+    m = capped
+    m.set_max_vectors(2)
+    _call(m, "vector_create_collection", name=f"cap4{backend}", dim=2, backend=backend)
+    ids = _call(m, "vector_insert_batch", name=f"cap4{backend}", vectors=[[1.0, 0.0], [0.0, 1.0]])["ids"]
+    _call(m, "vector_delete", name=f"cap4{backend}", id=ids[0], vacuum=True)
+    _call(m, "vector_insert", name=f"cap4{backend}", vector=[1.0, 1.0])  # vacuumed -> room again