[ENH] Add maxscore lazy cursor

[HammadB]

Description of changes

This is PR #3 of the BlockMaxMaxScore series, stacked on hammad/maxscore_writer_reader. It replaces the eager-only cursor with a tri-modal cursor and rewrites the query pipeline to use a 3-batch I/O strategy for reduced latency.

• New functionality
  • Tri-modal PostingCursor (cursor.rs): Replaces the eager-only cursor from PR Test queries in nested parquet coco files #2 with three source modes:
    • Eager — fully deserialized SparsePostingBlocks (unchanged from PR Test queries in nested parquet coco files #2).
    • View — borrows raw &[u8] slices from the Arrow block cache. Offsets are decompressed into a reusable buffer; f16 weights are read directly from raw bytes on the fly (fused reads, no bulk conversion).
    • Lazy — blocks start as None, populated on demand via populate_from_cache / populate_all_from_cache. Same fused f16 read path as View once populated.
  • Blockstore raw access APIs: get_raw_from_cache (synchronous cache-only raw byte lookup), count_blocks_for_prefix, Block::get_raw / Block::get_prefix_raw, and ArrowReadableValue::get_raw_bytes trait method.
  • 3-batch I/O pipeline in query():
    • Batch 1: Load directory blocks for all query dimensions in parallel.
    • Batch 2: Small dimensions (≤2 Arrow blocks) get View cursors; large dimensions get Lazy cursors with essential blocks loaded in bulk.
    • Batch 3: After the threshold stabilizes, load remaining non-essential blocks with pruning — blocks where query_weight × max_weight ≤ threshold are skipped entirely.

Test plan

• ms_12_cursor_view — View cursor vs Eager equivalence: advance, drain_essential, score_candidates, get_value, window_upper_bound, current.
• ms_13_cursor_lazy — Lazy cursor via real blockfile I/O: advance, get_value, drain_essential.
• ms_14_three_batch_pipeline — End-to-end 3-batch query: basic correctness, single dim, k > results, empty query, k=0, missing dim, masks, multi-block per dim.
• ms_15_multi_window — Documents spanning 4096-entry window boundaries: boundary transitions, accumulator reset, many-docs-across-windows recall.
• ms_16_lazy_partial_load — Lazy cursor with partially loaded blocks: advance skips unloaded, drain_essential skips unloaded, score_candidates skips unloaded.
• Tests pass locally with cargo test

Migration plan

No migration needed. This changes the internal query execution strategy but does not alter blockfile formats or segment layouts.

Observability plan

No new instrumentation in this PR. Block-skip counters and batch timing will be added alongside segment integration.

Documentation Changes

No user-facing API changes. Internal design is documented in rust/index/src/sparse/maxscore.md.

[HammadB]

Warning

This pull request is not mergeable via GitHub because a downstack PR is open. Once all requirements are satisfied, merge this PR as a stack on Graphite.
Learn more

• [ENH] Add maxscore index to metadata segment #6880
• [ENH] Add maxscore option in schema #6878
• [ENH] Benchmark maxscore #6866
• [ENH] Add SIMD for maxscore #6865
• [ENH] Add maxscore lazy cursor #6829 👈 (View in Graphite)
• [ENH] Add basic maxscore writer/reader #6825
• [ENH] Add SparsePostingBlock #6823
• main

This stack of pull requests is managed by Graphite. Learn more about stacking.

[github-actions]

Reviewer Checklist

Please leverage this checklist to ensure your code review is thorough before approving

Testing, Bugs, Errors, Logs, Documentation

• Can you think of any use case in which the code does not behave as intended? Have they been tested?
• Can you think of any inputs or external events that could break the code? Is user input validated and safe? Have they been tested?
• If appropriate, are there adequate property based tests?
• If appropriate, are there adequate unit tests?
• Should any logging, debugging, tracing information be added or removed?
• Are error messages user-friendly?
• Have all documentation changes needed been made?
• Have all non-obvious changes been commented?

System Compatibility

• Are there any potential impacts on other parts of the system or backward compatibility?
• Does this change intersect with any items on our roadmap, and if so, is there a plan for fitting them together?

Quality

• Is this code of a unexpectedly high quality (Readability, Modularity, Intuitiveness)

[propel-code-bot]

Changes are promising, but one important unsafe lifetime issue and code duplication should be addressed before merge.

Status: Changes Suggested | Risk: Medium

Issues Identified & Suggestions

• Unsafe lifetime transmute may cause use-after-free; return owned bytes or Arc. rust/blockstore/src/arrow/blockfile.rs
• Duplicate View/Lazy logic; extract shared raw-block helper to reduce drift. rust/index/src/sparse/cursor.rs

Review Details

📁 13 files reviewed | 💬 2 comments

👍 / 👎 individual comments to help improve reviews for you

[propel-code-bot]

[Logic] The transmute here extends the lifetime of a &Block borrowed from inside the RwLockReadGuard to &'me Block, where 'me is the lifetime parameter of the reader. This is unsound: once the read guard drops at the end of this function, the underlying Block could theoretically be deallocated if a write guard is acquired elsewhere (e.g., if blocks were evicted from the cache), while the returned &[u8] still points into its Arrow buffers.

The comment says "Block is never removed from loaded_blocks", and the same invariant is relied upon by get_block's existing transmutes (lines 498, 513). However, this is a behavioral invariant, not a type-system invariant. This PR expands the unsafe surface area by adding a new function that relies on the same unverifiable guarantee. If that invariant ever changes (cache eviction, compaction, etc.), this becomes a use-after-free with no compiler warning.

A safer approach is to either:

1. Return an owned Vec<u8> (a copy of the raw bytes), or
2. Wrap Block in Arc<Block> so the caller can hold a reference-counted handle that prevents deallocation without needing the transmute.

Context for Agents

The `transmute` here extends the lifetime of a `&Block` borrowed from inside the `RwLockReadGuard` to `&'me Block`, where `'me` is the lifetime parameter of the reader. This is unsound: once the read guard drops at the end of this function, the underlying `Block` could theoretically be deallocated if a write guard is acquired elsewhere (e.g., if blocks were evicted from the cache), while the returned `&[u8]` still points into its Arrow buffers.

The comment says "Block is never removed from loaded_blocks", and the same invariant is relied upon by `get_block`'s existing transmutes (lines 498, 513). However, this is a behavioral invariant, not a type-system invariant. This PR expands the unsafe surface area by adding a new function that relies on the same unverifiable guarantee. If that invariant ever changes (cache eviction, compaction, etc.), this becomes a use-after-free with no compiler warning.

A safer approach is to either:
1. Return an owned `Vec<u8>` (a copy of the raw bytes), or
2. Wrap Block in `Arc<Block>` so the caller can hold a reference-counted handle that prevents deallocation without needing the transmute.

File: rust/blockstore/src/arrow/blockfile.rs
Line: 571

[propel-code-bot]

Reviewed 15 files for the maxscore lazy cursor enhancement; no issues were found and changes appear ready to merge.

Status: No Issues Found | Risk: Low

Review Details

📁 15 files reviewed | 💬 0 comments

[propel-code-bot]

Add tri-modal PostingCursor and 3-batch MaxScore query pipeline

This PR introduces a new tri-modal cursor architecture for sparse maxscore search by moving PostingCursor into rust/index/src/sparse/cursor.rs and supporting Eager, View, and Lazy source modes. The new modes enable cache-backed raw-byte traversal, selective block population, and fused f16-to-f32 reads in hot paths (drain_essential and score_candidates) to reduce unnecessary deserialization and conversion work.

It also rewrites MaxScoreReader.query() in rust/index/src/sparse/maxscore.rs to a 3-batch I/O strategy: directory preload, essential-term data load, and threshold/pruning-driven non-essential lazy loads. Supporting raw cache access APIs were added in blockstore (get_raw_from_cache, count_blocks_for_prefix, Block::get_raw, Block::get_prefix_raw, ArrowReadableValue::get_raw_bytes), and a substantial new test suite validates cursor equivalence, lazy/partial-load behavior, window-boundary correctness, and end-to-end pipeline parity with brute-force scoring.

This summary was automatically generated by @propel-code-bot