test: phase 3 -- property-based, determinism, adversarial tests + concurrency docs

[stffns]

Summary

Phase 3 (first slice): trust and correctness. Adds 29 tests across
three new files and documents the concurrency contract. Fixes one
real bug caught while writing adversarial tests.

Commits

1. `fix: raise ValueError when SnapIndex.search is called with k < 1`
   -- `SnapIndex.search(k=0)` was silently returning all results
   because slicing with a non-positive k no-ops. PQSnapIndex,
   ResidualSnapIndex, and IVFPQSnapIndex already validated k>=1; this
   aligns SnapIndex with the rest of the public API. Caught by the
   new adversarial suite.
2. `test: add property-based, determinism, and adversarial tests`
   -- 29 new tests, suite goes from 151 to 180. Pulls
   `hypothesis>=6.100` into dev deps.
3. `docs: document the single-writer / multi-reader contract`
   -- new `docs/user-guide/concurrency.md` page, linked from nav.

What each suite covers

test_properties.py (8 hypothesis-driven tests)

• `len(idx)` equals the number of ids added.
• `search(q, k)` returns at most k hits, sorted by descending score.
• `delete(id)` reduces len by exactly 1 (and returns False for unknown id).
• `save()` then `load()` preserves `search()` output bit-for-bit.
• With `filter_ids=S`, every returned hit is in S.
• PQSnapIndex `fit` + `add_batch` reports correct `len`.
• IVFPQSnapIndex search respects k and score ordering across nprobe.
• IVFPQSnapIndex with only unknown filter ids returns `[]`.

`max_examples=25` per test, full file runs in <1s.

test_determinism.py (7 tests)

• `SnapIndex` / `PQSnapIndex` / `ResidualSnapIndex` / `IVFPQSnapIndex`:
  same seed + same inputs produce byte-identical index files
  (`sha256` comparison).
• Search results are identical across two freshly-built indices for
  each class that doesn't require coarse training.

test_adversarial.py (14 tests)

Empty index; n=1; k > n; zero-norm query; all-same-vector corpus;
unknown / empty filter set; delete-all; bits=2 behaviour;
`nprobe=nlist` and `nprobe` out-of-range on IVF-PQ;
`ResidualSnapIndex` rerank saturation.

Test plan

• `ruff check snapvec/ tests/` passes
• `pytest -q` passes locally (180 tests)
• `mkdocs build --strict` passes
• CI runs green on this PR (tests + lint + docs build)

Out of scope

• File format v2 / per-block checksums
• BEIR-SciFact integration test in CI
• Reproducible `bench/` suite separated from `experiments/`

Those move to phase 3b in a follow-up PR.

[gemini-code-assist]

Code Review

This pull request introduces a new concurrency guide to the documentation, adds input validation to the search method, and significantly expands the test suite with adversarial, determinism, and property-based tests using Hypothesis. The review feedback highlights an inconsistency in the thread-safety documentation example where the search method should be protected by a lock to prevent data races during mutations. Additionally, there are suggestions to expand the coverage of determinism and property-based tests to include all index types, specifically IVFPQSnapIndex and PQSnapIndex.

[gemini-code-assist]

The SafeIndex example is currently unsafe for concurrent use when mutations are active. While the documentation states that search() only touches shared state, it also explicitly mentions in lines 21-23 that one thread mutating while another searches is not safe because internal arrays are resized. In the provided SafeIndex implementation, search() does not acquire the lock, meaning it can run concurrently with add_batch() or delete(), leading to potential crashes or undefined behavior. To be truly safe, search() should also be protected by the lock, or the documentation should clarify that this pattern only protects writers from each other and requires external coordination with readers.

Suggested change

	def search(self, query, k=10, **kwargs):
	return self._idx.search(query, k=k, **kwargs) # no lock
	def search(self, query, k=10, **kwargs):
	with self._lock:
	return self._idx.search(query, k=k, **kwargs)

[gemini-code-assist]

IVFPQSnapIndex is missing from the test_search_results_are_deterministic parametrization. Since it is included in the bitwise determinism tests (line 79), it should also be verified here to ensure that its search results are consistent across different builds with the same seed.

@pytest.mark.parametrize(
    ("index_cls", "ext", "build_kwargs"),
    [
        (SnapIndex, ".snpv", {"bits": 4}),
        (PQSnapIndex, ".snpq", {"M": 8, "K": 16}),
        (ResidualSnapIndex, ".snpr", {"b1": 3, "b2": 3}),
        (IVFPQSnapIndex, ".snpi", {"nlist": 8, "M": 8, "K": 16}),
    ],
)

[gemini-code-assist]

The property-based tests for delete, save/load, and filter_ids are currently only implemented for SnapIndex. To ensure consistent behavior and catch regressions across all index types, these tests should be generalized or parametrized to include PQSnapIndex, IVFPQSnapIndex, and ResidualSnapIndex where applicable.

[Copilot]

Pull request overview

Adds phase-3 test coverage focused on invariants, determinism, and adversarial edge-cases; documents the library’s concurrency model; and aligns SnapIndex.search() with other index types by validating k >= 1.

Changes:

• Add 3 new test suites: property-based (Hypothesis), determinism (bitwise save), and adversarial edge cases.
• Fix SnapIndex.search() to raise ValueError when called with k < 1.
• Document the concurrency contract and link it into the MkDocs nav; add hypothesis to dev dependencies.

Reviewed changes

Copilot reviewed 7 out of 7 changed files in this pull request and generated 2 comments.

Show a summary per file

File	Description
tests/test_properties.py	New Hypothesis-driven invariant tests across SnapIndex, PQSnapIndex, and IVFPQSnapIndex.
tests/test_determinism.py	New tests asserting bitwise-deterministic index files and deterministic search results.
tests/test_adversarial.py	New edge-case regression tests (empty index, k edge cases, filters, degenerate vectors, IVF-PQ nprobe bounds).
snapvec/_index.py	Enforce k >= 1 in SnapIndex.search() (matches other index classes’ validation).
pyproject.toml	Add hypothesis>=6.100 to dev dependencies.
mkdocs.yml	Add Concurrency page to documentation navigation.
docs/user-guide/concurrency.md	New concurrency contract documentation + usage guidance.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

The SafeIndex example only locks add_batch/delete, but leaves search() unlocked. That does not prevent reader/writer overlap on the same instance, which the page says is unsafe. Either (a) take the same lock in search() as well, (b) demonstrate a reader/writer lock, or (c) recommend a copy-on-write pattern (build a new index, then atomically swap the reference) so searches never overlap with mutations.

[Copilot]

The doc claims concurrent search() calls are safe because search only reads shared state, but SnapIndex.search() can still mutate internal state (e.g., lazily materializing _cache on first query) unless the index is freeze()d / pre-warmed. This makes the “no external lock required” statement inaccurate for first-query concurrency. Consider updating the contract to explicitly require idx.freeze() (or an explicit warm-up query) before multi-threaded search, aligning with snapvec/_freezable.py and SnapIndex.freeze()’s cache pre-warm behavior.