feat(vector/search): PQ → SQ → f32 three-stage rerank chain (#650 PR-3)

[mosuka]

Summary

• Final child PR of the perf(vector/search): two-stage rerank exists only for HNSW; pipeline is hard-coded #650 rerank-pipeline campaign (PR-1 refactor(vector/search): RerankStage/RerankPipeline abstraction, port HNSW Stage-2 (#650 PR-1) #931, PR-2 feat(vector/search): Stage-2 rerank for Flat/IVF via the shared pipeline (#650 PR-2) #932). Closes perf(vector/search): PQ rerank pipeline not exposed: PQ → SQ → f32 not possible #673.
• Inserts a cheap int8 (SQ) rerank stage ahead of the exact f32 stage on PQ-quantized HNSW fields, activated only when ef_search exceeds the exact-stage budget (top_k * rerank_factor). Today that surplus — candidates the graph traversal already computed — is simply discarded on the noisier PQ ADC order; the SQ stage re-ranks it on a much better proxy (int8) before the narrow exact-stage budget is carved out.
• Design change from the issue's original framing: the comment that adopted perf(vector/search): PQ rerank pipeline not exposed: PQ → SQ → f32 not possible #673 as PR-3 assumed a new on-disk int8 sidecar was the prerequisite. Investigation found that's unnecessary — every 3-stage chain ends in an exact f32 stage, so the f32 sidecar always exists; the int8 view is derived from it lazily (RerankStoragePool::int8_view, OnceLock-cached) instead of persisted separately. Net effect: no new on-disk format, no new RerankStorageKind variant, no new query parameter, zero ripple into proto/bindings/CLI.

Changes

• ScalarQuantParams::train_from_slices (vector/core/quantization.rs): slice-iterator variant of train; train(&[Vector]) now delegates to it.
• RerankStoragePool::int8_view() (vector/index/rerank_storage.rs): lazily derives a QuantizedVectorPool from the pool's own f32 payload, encoded in the same position order so int8_view.record_at(pos) and f32_slice_at(pos) trivially agree on pos. Degrades to None on an empty pool or training failure.
• SqRerankStage (vector/search/rerank.rs): mirrors F32SidecarStage, rescoring via distance_quantized.
• HnswSearcher::finalize_graph_results: inserts SqRerankStage ahead of F32SidecarStage only when segment=PQ/PQ-FastScan + sidecar loaded + rerank_factor set + effective_ef_search > top_k * rerank_factor. score_basis stamping (bug(vector/search): cross-segment scores are not comparable — out-of-range queries clamp to similarity 1.0 per segment #927) is unchanged — still keyed only on the final (still f32) stage.
• Bench: bench_hnsw_graph_search_pq_rerank_real_data_wide_ef (opt-in SIFT, not run in this session — no local fixture).
• Docs (EN+JA): new "PQ → SQ → f32 three-stage rerank" section in vector_indexing.md; grpc_api.md rerank_factor row updated (also fixes a stale feat(vector/search): Stage-2 rerank for Flat/IVF via the shared pipeline (#650 PR-2) #932-era "Flat/IVF fall back" claim) + new ef_search row.

Tests

• Unit: train_from_slices (2), int8_view (6: position-consistency, quantization-error bound, single-build-cached, degrade-to-None), SqRerankStage (2).
• Integration (vector_pq_three_stage_rerank_test.rs, new): pq_three_stage_rerank_end_to_end — wide-ef_search (SQ active) Recall@10 ≥ narrow/budget-exact ef_search (SQ inactive) Recall@10 (measured 0.66 → 0.98 on a deliberately lossy PQ fixture); score_basis stays "f32-rerank"; narrow-ef_search results are bit-exact reproducible.
• RED proof (reversible edit disabling the SQ-stage insertion): wide-ef_search recall dropped 0.98 → 0.9567, confirming the SQ stage's causal contribution.
• Regression: existing PQ recall gates (hnsw_pq_rerank_recall_at_10_meets_stage3_recall_gate + opt-in SIFT variant) stay green.

Verification

• cargo fmt --check / cargo clippy --all-targets -D warnings: clean on stable, 1.97.0, and --features pq-fastscan.
• cargo test -p laurus --lib: 1270 passed. --tests: 68 binaries, all green.
• cargo check -p laurus-wasm --target wasm32-unknown-unknown: clean.
• cargo doc --no-deps -p laurus: 73 warnings (unchanged baseline).
• markdownlint-cli2 EN+JA: 0 errors. Both mdBooks build.

Test plan

• Unit tests for the new derivation/stage logic
• Integration test covering the 3-stage recall property, score_basis contract, and 2-stage-path determinism
• RED proof isolating the SQ stage's causal effect
• No regression on existing PQ rerank recall gates
• Full verification suite (fmt/clippy ×3 configs/tests/wasm/doc/markdownlint/mdbook)