[gouyt13]

Resolves the remaining decided items from the audit (#195–#197).

fix(hnsw): clamp ef to the stored point count and validate cluster lookups

• HierarchicalNSW::search_knn_sorted_with allocated a candidate pool of max(ef, k) entries, so HnswIndex.search(ef=2**40) failed with MemoryError rather than being handled; a pool can never hold more distinct points than are stored, so ef is now clamped to num_stored_points(). Results are unchanged (the C++ test compares a 2**40 window with an exhaustive one; the Python test likewise). Documented in the C++ header, the ef docstring (.pyi kept in sync) and hnsw.md.
• cluster_id_of(PID) is public API but read the record array without checks. It now throws std::logic_error on an unbuilt index and std::invalid_argument for an internal ID >= num_stored_points(); the comment states that internal IDs coincide with labels only for points added in order. The search estimators and construction keep a private unchecked stored_cluster_id, so the hot path is unchanged: single-thread SIFT1M search on the saved benchmark index, interleaved with the merged main binary, 2 passes × 2 rounds: ef=128 5575/5479 · 5850/5789 (main) vs 5771/5373 · 5433/5724 (this PR); ef=256 3413/3414 · 3492/3507 vs 3469/3432 · 3476/3507; recall@10 identical. (Absolute numbers are lower than in fix: validate advanced encoder preconditions and bound HNSW prefetch look-ahead #197 because sanitizer and Python suites were running concurrently.)

docs: index files are trusted input

Records the maintainer decision from the audit in usage.md and the "Change persistence" recipe: loaders validate structure so corrupt or mismatched files are reported, but a crafted file is not a supported input (it can make load allocate its stored capacity, or violate invariants that later add/remove rely on).

Verification

• check-format.sh, ruff on the Python test and stub, git diff --check, mkdocs build --strict.
• GCC 14 portable build: ctest --no-tests=error 441/441; Clang 23 ASan/UBSan: 441/441, no diagnostics.
• Installed-consumer build and tests against a fresh install prefix; focused clang-tidy on the HNSW TUs, ivf*.cpp and hnsw_bindings.cpp.
• Reinstalled package: pytest tests/python tests/test_mypy.py tests/test_pyright.py 841 passed, 2 skipped (includes the stub/runtime docstring comparison).