[MarkWolters]

Summary

Adds a generic Index API and HnswIndexBuilder, a fluent builder that makes building, compressing, persisting and searching a graph index a line or two each, instead of hand-assembling GraphIndexBuilder constructors, PQ training, writers and score providers. The builder wraps the existing GraphIndexBuilder code, so performance and recall are unchanged; GraphIndexBuilder remains fully supported.

Changes

• Indexes.hnswBuilder(...): type-first entry point with defaults for every setting; buildAndPopulate() builds a complete graph in one call.
• Compression as a setting: withCompressionType(PQ | BQ) trains and encodes inside the builder, with PQ defaults matching Cassandra's and overridable (withPqSubspaces, withPqGlobalCentering, withPqAnisotropicThreshold); getCompressedVectors() returns the codes for search or fused-PQ writing.
• Incremental construction on the same builder (addGraphNode, markNodeDeleted, cleanup, rescore, withExistingGraph), with early rejection of invalid or mixed-scoring configurations.
• Generic handles: api.Index / api.IndexSearcher; ImmutableGraphIndex is renamed GraphIndex and implements Index.
• Simpler persistence and search: PersistableGraphIndex writer accessors return each writer's own builder, writeTo(path, vectors) writes a basic on-disk index, and GraphSearcher.search(query, topK, rerankK, vsf, filter) searches with the graph's stored vectors.
• Fixes: inserting after cleanup(), rescore dropping pending deletes, and writer builders leaking a file handle when not built.
• Experimental placeholders: recipes (HnswRecipe.DEFAULT only) and IVF types.

Breaking changes

ImmutableGraphIndex is renamed GraphIndex (no alias), and GraphIndexBuilder.build(ravv) / getGraph() now return PersistableGraphIndex. Callers must recompile; see UPGRADING.md.

Testing

• New and updated unit tests for the builder, PQ options, writer accessors, stored-vector search and concurrency; the full suite passes.
• Measured against main (100k × 128-dim): build time, search latency and recall (exact, inline, fused PQ) are the same within noise.
• IndexApiExample exercises every pattern end to end: mvn compile exec:exec@index-api-example.

Docs

UPGRADING.md (migration guide) and release notes (docs/release notes/4.0.2/728.enhancement.md).

pr728.tar.gz