[gouyt13]

Summary

• Part of Index file format v2 with a written specification #212 (with 64-bit IDs, with -1 for missing results #211)

This PR adds index file format 2 and moves all three indexes onto it: IVF-RaBitQ, HNSW-RaBitQ and SymphonyQG. Each index also records its construction seed, so Python keeps seed after load. It also adds the cosine metric, rabitqlib.FormatError for rejected files, and Python point IDs as int64 with -1 for missing results (#211).

Merge plan: this PR targets dev/0.9, the branch that collects the breaking changes of the 0.9 release, and is merged there now. main deploys its docs on every push and must stay releasable for 0.8.x, so this work reaches main only when dev/0.9 is merged right before the version bump. Format 2 can still change until then.

Commits

1. docs(formats): the specification. It is in docs/formats.md, next to the rabitqlib.quant byte formats. It covers:
   • a 128-byte header and a section table, with 64-byte-aligned sections;
   • ext4-style incompat / ro_compat / compat feature masks and required/optional sections;
   • the section kinds and record layouts, including the HNSW routing graph field by field;
   • each index's reader rules;
   • companion files for RaBitQ-SSD;
   • the reading order and the compatibility rules.
2. feat(index): the container layer (src/index/format2.*, not installed). It writes files front to back without seeking. The reader validates the expected index kind before any section, and reads through the stream buffer.
3. feat(ivf): IVF-RaBitQ saves and loads format 2.
   • One file. HNSW centroid routing is section 260, so save writes no <file>.hnsw sidecar.
   • Earlier files still load, including their sidecars.
   • New frozen fixtures, tests/fixtures/persistence/v0.8.3/. They were generated from an isolated v0.8.3 checkout and cover the RABQIDX1 v2 layout, which had no frozen fixture before.
   • Rotator blob in C++. The codec and a zlib-compatible CRC-32 move to private core sources. rabitqlib.quant is unchanged; the C++ codec reads and rewrites its golden files byte for byte.
4. fix(ivf): two misses that CI found.
   • The HNSW load benchmark still called the removed Initializer::save/load.
   • A Windows test path was written as a narrow string literal; it is now a UTF-8 literal.
5. test(ivf): reproducible HNSW routing in a byte comparison. A test trained its routing graph with several threads, whose insertion order is nondeterministic. It now trains with one thread, and the docs say the graph is reproducible only when built with one thread.
6. test(persistence): frozen v0.8.3 HNSW-RaBitQ and SymphonyQG fixtures.
   • HNSW at 1, 5 and 9 bits, with removals and upper layers.
   • SymphonyQG raw, 4- and 8-bit, with FHT/Kac and matrix rotation.
   • A separate generator writes them, so the committed IVF fixtures keep their bytes. The current readers loaded them before the writers changed.
7. feat(index): HNSW-RaBitQ and SymphonyQG save and load format 2.
   • Sections: HNSW uses 512–516; SymphonyQG uses 768–770, and the raw mode stores no centroid.
   • Shared graph checks: HNSW's earlier-layout reader keeps all of its checks, and the format-2 reader uses the same validate_graph.
   • Seed and settings: every index records its seed. SymphonyQG also records ef_construction and init, which QGBuilder records on the graph.
   • Read-only loading works for all three indexes:
     • IVF-RaBitQ: refuses add, reserve, remove and save.
     • HNSW-RaBitQ: refuses add, resize, remove and save.
     • SymphonyQG: refuses save until a builder rebuilds it.
8. feat(index): rabitqlib.FormatError.
   • C++ loads throw rabitqlib::FormatError (new public header rabitqlib/index/format_error.hpp, a std::runtime_error) for a truncated, corrupt, mismatched or unsupported file, in format 2 and every earlier layout. A file that cannot be opened stays a plain std::runtime_error.
   • Python raises rabitqlib.FormatError, a subclass of both ValueError and RuntimeError, so except RuntimeError keeps working. rabitqlib.quant.FormatError is the same class.
   • This resolves the spec's open question on the Python error type.
9. feat(python): int64 point IDs (64-bit IDs, with -1 for missing results #211).
   • search returns int64 IDs with -1 for a missing result, instead of 2**32 - 1; distances stay inf. add returns int64; remove already took any integer IDs and rejects -1.
   • C++ point IDs stay 32-bit PID values with kPidMax. The bindings widen each search batch once, mapping kPidMax to -1.
10. fix(index): the remaining rejected headers. A fourth independent review found loads that escaped the FormatError contract:
    • SymphonyQG records too large for size_t threw std::length_error, in format 2 and the earlier layouts.
    • Earlier IVF-RaBitQ and SymphonyQG layouts with dimensions the FHT/Kac rotation does not support threw std::invalid_argument.
    • The earlier IVF-RaBitQ reader caught std::ios_base::failure, which libstdc++ before GCC 13 throws with an ABI the catch does not match. It now checks each group of reads.
11. Merge of main after 0.8.4. It brings perf(utils): check coordinates in a single pass #223 and test: run the Python quick start in CI #224 and has no conflicts.
12. feat(index): the cosine metric (Index file format v2 with a written specification #212).
    • All three indexes accept METRIC_COSINE (Python metric="cosine").
    • An index stores METRIC_IP internally and normalizes vectors where they enter: train, construction, add, search and the SymphonyQG builder. The helpers are in src/index/cosine.hpp.
    • The inner-product distance 1 - dot of unit vectors is 1 - cos. A cosine file therefore equals the inner-product file of the normalized vectors, apart from the header's metric field, which readers now accept.
    • The normalization is specified bit for bit in the spec: squares summed in double, one rounding per coordinate. A zero vector stays zero.
    • Coordinates are checked before normalizing. Centroids given to set_centroids or construct are used as given.
13. Merge of dev/0.9 (8894723). dev/0.9 is main at ecc594c, which brings test(python): migrate index count tests to the 0.8 API #226, test(python): migrate ten test files off the 0.7 call forms #227, test: make graph tests independent of graph connectivity #228, test(python): migrate the last seven test files off the 0.7 call forms #230 and feat(python): let IvfIndex.set_centroids take num_threads #231, plus the workflow change that runs the Python checks for pull requests into it. Two conflicts: usage.md, where both sides reworded the note on nondeterministic HNSW builds (the wording of main is kept), and tests/python/test_ivf.py, where this branch's save-failure and embedded-routing tests now build their indexes with the _built helper from main instead of the 0.7 constructor and build.

Breaking changes (0.9, release-noted in docs/docs/releases/unreleased.md)

• File format: releases up to 0.8 cannot read files saved by this branch. IVF-RaBitQ files are rejected as Invalid IVF index metadata rather than misread; this was inferred from the v0.8.3 reader, not run.
• ivf::Initializer (installed header): save(std::ofstream&, const char*) and load(std::ifstream&, const char*) become write(std::ostream&) and read(std::istream&, uint64_t).
• New accessors (additive):
  • IVF::seed();
  • HierarchicalNSW::seed();
  • QuantizedGraph<float>::seed(), ef_construction() and initialization().
• symqg::QGInitialization moves from qg_builder.hpp to qg.hpp, which qg_builder.hpp includes.
• Vendored hnswlib: a patch, marked // RaBitQ:, adds saveIndex(std::ostream&) and loadIndex(std::istream&, size_t, ...). The path overloads delegate to them.
• Cosine metric (additive):
  • MetricType gains METRIC_COSINE.
  • The stable core API v1 rejects it like any other invalid metric, and so do factor computation, the query classes, FastScan, clustering and the IVF initializers. v1 therefore stays 1.0; core_api.md and development.md record this.
  • A switch over MetricType without a default may warn about the new value. zvec has no such switch.
  • rabitqlib.quant still rejects "cosine".
  • An invalid index metric now raises metric must be 'l2', 'ip' or 'cosine'.
• Error type: rejected files raise rabitqlib.FormatError (C++ rabitqlib::FormatError) instead of RuntimeError/std::runtime_error, which still catch it. Earlier-layout files that threw std::invalid_argument or std::length_error for invalid contents also throw it. quant.FormatError was a ValueError only.
• Python IDs (64-bit IDs, with -1 for missing results #211): search and add return int64; a missing result is -1, not 2**32 - 1. np.isfinite(distances) works before and after. txtai 9.14.0 and earlier filter with uid != 0xFFFFFFFF, so 0.9 waits for a compatible txtai release (Remove the deprecated 0.7 Python call forms #213).
• Python:
  • After load, seed and SymphonyQG's ef_construction and init are kept. They are None only for files from releases up to 0.8.
  • cp.seed follows a recorded seed: the seed itself for IVF-RaBitQ, its low 32 bits for HNSW-RaBitQ.
• Reproducible files: saved files include the IVF HNSW routing graph, which is reproducible only when built with num_threads=1.
• Error messages:
  • Damaged format-2 files get container messages.
  • HNSW routing-graph errors say graph instead of sidecar.
  • A failed HNSW-RaBitQ write raises HNSW index file cannot be written.
  • A leftover .hnsw beside a resaved IVF file is not removed.

Review questions

• RaBitQ-SSD:
  • The companion-file design: a 4 KiB header page, then pages from offset 4,096.
  • The FNV-1a fingerprint over the rotated centroids.
  • The coarse quantizer recording the base fingerprint instead of being a companion.
• Section 260: whether it should keep hnswlib's native layout. It is now specified field by field, as 64-bit little-endian.

Known limitations

• Version stamp. Files from this branch record writer version 0.8.4 until the 0.9.0 bump. main cannot carry a development version, because automatic releases accept only X.Y.Z.
• Cosine memory. Cosine train, add and construction normalize a copy of their whole input, so they briefly need memory for one more float32 copy of it. IVF train normalizes every row, although k-means samples at most 256 per centroid. The usage docs suggest training on a sample and adding in several calls. Blockwise normalization is left for later; it is unmeasured.
• HNSW-RaBitQ level generator. It is not reseeded on load (unchanged from before), so points added after a reload do not follow the recorded seed. HNSW-RaBitQ also cannot be rebuilt in place, so a read-only HNSW index stays read-only.
• hnswlib loadIndex integrity loop. It calls tellg() twice per centroid, as upstream does; this also applies to legacy sidecars.
• Allocation before the graph check. IVF's HNSW routing storage is allocated before its graph is validated; the parameter sections are checksummed.
• Rotator copies. Rotator sections are copied whole before decoding. A SymphonyQG load with a matrix rotator briefly holds about three copies of it.
• Dimension limit. IVF-RaBitQ save rejects more than 65,536 dimensions, the rotator blob's limit.

Testing

All runs: Linux x86-64, GCC 14.3, Release, RABITQ_ENABLE_NATIVE_OPTIMIZATION=OFF.

• C++ suite: 555/555 pass on 61550c2.
• Core-only build: index, FastScan and OpenMP all off; 155/155 pass on the cosine change, which touches core/metric.hpp.
• Benchmark targets (-DRABITQ_BUILD_BENCHMARKS=ON): they build, and their 15 smoke tests pass (run on d2b25a1; later commits do not touch benchmark code).
• Python: the package was reinstalled from 61550c2. The suite, plus tests/test_mypy.py and tests/test_pyright.py: 1186 passed, 2 skipped.
• Static checks: check-format.sh, check-python.sh and check-isa-symbols.sh pass. The full check-tidy.sh with the CI configuration reports no findings; .clang-tidy exempts METRIC_COSINE like its siblings METRIC_L2 and METRIC_IP. mkdocs build --strict passes.
• After the merge of main (75c81d4): C++ 546 passed and 1 skipped, Python 1170 passed, including test: run the Python quick start in CI #224's quick start test.
• After the merge of dev/0.9 (8894723): against a wheel built from the merged tree, the Python suite has 1169 passed and 18 skipped (the C++ example targets were not built), and tests/test_mypy.py and tests/test_pyright.py pass; check-python.sh and the strict docs build pass. The C++ suites ran in CI on this commit, where every check passes.
• Coverage:
  • Frozen fixtures. The v0.5.2 and v0.8.3 fixtures of all three indexes load and match their reference results. Migrated files are format 2, keep an unknown seed (and, for SymphonyQG, unknown settings), and saving them again reproduces them byte for byte.
  • Earlier layouts. Their checks run on copies of the v0.8.3 fixtures. A test-only converter that reproduces the v0.8.3 IVF fixtures byte for byte builds the layouts no fixture covers.
  • Rejections. Every container rule and every per-index reader rule has a rejection test with its exact message.
  • Other cases: read-only loading for each index, unknown optional sections, write failures, and the seed and settings round trips.
  • FormatError: truncated and damaged headers of every earlier layout and format 2 raise it in C++ and Python, with exact messages; a missing file does not. The tests of the last commit fail without it.
  • IDs: int64 dtypes, -1 padding for every index, and search output passed back to remove.
  • Cosine:
    • Each index is compared with an inner-product index of the normalized vectors at several bit widths and initializers: section bytes, IDs and distances, before and after reload. The Python test reproduces the normalization in NumPy.
    • Also covered: zero vectors (exact distance 1 in raw modes), failed and replacing loads, training errors, train/set_centroids paths, earlier layouts rejecting metric byte 2, and v1 rejecting the new value.
    • Removing HNSW's swap(cosine_) makes a test fail.
• Load time (smoke test, not deployment performance):
  • Setup: an IVF index of 1M × 64 vectors in 100k clusters, 4 bits, a 126 MB file. Xeon Gold 6418H, warm page cache, an unisolated host.
  • Result: format 2 takes 138.2 ms median and the 0.8 layout 136.6 ms, with about the same read and lseek counts.
• Review: five independent reviews, of the container, the IVF changes, the HNSW-RaBitQ/SymphonyQG changes, FormatError with the int64 IDs, and the cosine metric. Their findings are addressed, including:
  • a 2.5× IVF load regression;
  • HNSW-RaBitQ and SymphonyQG ignoring unknown read-only features;
  • several tests that patched new files at old offsets and passed without exercising their check;
  • for cosine, docs that still said there was none, a zero-vector claim that holds exactly only for raw vectors, and missing load-state and HNSW zero-vector tests.
• CI: all checks passed on d2b25a1. This push re-runs them on 61550c2.