feat(mask): add range-aware Runs variant + insert_run / iter_runs APIs

[westonpace]

Summary

• Adds a third RowAddrSelection variant, Runs(Vec<RangeInclusive<u32>>),
  for storing range-shaped per-fragment selections without inflating to a
  per-row roaring bitmap.
• Adds two new methods on RowAddrTreeMap: insert_run(fragment_id, run)
  for range-shaped producers and iter_runs() for range-shaped consumers.
• Adds a criterion bench suite (row_addr_mask) that pins the row-
  cardinality scaling weakness of the existing API and the cost saved by
  the new one.

This is an additive, backwards-compatible change — existing code paths
keep working unchanged, the on-disk format does not move, and all 97
pre-existing utils::mask tests pass alongside 11 new ones.

Motivation

Producers like lance-index's search_zones and consumers like
mask_to_offset_ranges operate naturally on row-address ranges, but
the only public RowAddrSelection representations today are Full and
Partial(RoaringBitmap). Every range-shaped result therefore round-trips
through a per-row bitmap, so the cost of using a RowAddrMask is set by
the row cardinality of the result, not the number of distinct ranges.

The baseline benchmark suite (row_addr_mask) introduced in the first
commit of this PR makes this concrete:

Op (10M-row contiguous selection)	Existing	Achievable
Producer (insert_range)	6.5 µs	—
Consumer (into_addr_iter)	19.9 ms	1.7 µs
End-to-end (mask_to_offset_ranges_inner_loop)	19.3 ms	—

The consumer-side gap (≈11,000×) is the largest, and matches what we
observed in production: a chrome trace of IS NULL against a zonemap-
indexed 10M-row dataset spent ≈495 ms of 889 ms inside
mask_to_offset_ranges, all of it converting between the per-row mask
and a Vec<Range<u64>>.

What this PR does not do

It does not migrate any callers to the new APIs, and does not change
on-disk semantics. The point of this PR is to land the data structure +
API surface + benchmarks so follow-up PRs can cut over search_zones,
mask_to_offset_ranges, and friends one at a time with a measurable
delta each.

API surface

// New variant on the existing enum.
pub enum RowAddrSelection {
    Full,
    Partial(RoaringBitmap),
    /// A sorted, non-overlapping, non-adjacent list of inclusive ranges.
    Runs(Vec<RangeInclusive<u32>>),
}

impl RowAddrTreeMap {
    /// Range-shaped producer. O(1) amortized when runs arrive in order
    /// (the common pattern for scalar-index zone walks).
    pub fn insert_run(&mut self, fragment_id: u32, run: RangeInclusive<u32>);

    /// Range-shaped consumer. Yields `(fragment_id, RangeInclusive<u32>)`,
    /// one item per run regardless of how many rows the run covers.
    pub unsafe fn iter_runs(&self) -> impl Iterator<Item = (u32, RangeInclusive<u32>)> + '_;

    /// Force a Runs entry into its equivalent Partial form. Useful for
    /// callers that need direct bitmap access via `get_fragment_bitmap`.
    pub fn canonicalize_to_partial(&mut self, fragment_id: u32);
}

Both insert_run and iter_runs are full citizens of the mask
machinery:

• insert_run preserves the sorted / non-overlapping / non-adjacent
  invariants even on unsorted input. Merging is O(num_runs) in the
  pathological case, O(1) amortized in the common in-order case.
• iter_runs works on all three variants: yields stored ranges
  for Runs, surfaces roaring's container run-encoding for Partial
  via Iter::next_range, and panics on Full (matching the existing
  into_addr_iter contract — same unsafe justification).

Backwards compatibility

Concern	Status
Existing utils::mask tests	97/97 pass unchanged
On-disk wire format	Unchanged — serialize_into inflates Runs to its equivalent bitmap before writing; old readers continue to load. deserialize_from always returns Partial.
into_addr_iter cost	Unchanged: 19.4 ms before, 19.9 ms after (within noise). The trick is itertools::Either rather than Box<dyn Iterator> so the new arm adds no dynamic dispatch to the existing path.
Existing set operations (&, |, -, Extend)	Updated to accept Runs inputs by transparently inflating to Partial before applying the existing roaring-bitmap logic — semantics-preserving fallback. Native run-shaped set ops are deferred to a follow-up since intersect_two_runs at 10M rows is already 12 µs (not a bottleneck).
Existing RowAddrSelection consumers outside mask.rs	One match site in filtered_read.rs (in FilteredReadExec::with_plan) grew a Runs arm that emits the stored runs as Range<u64> directly. Compilation guarantees no other consumer was missed.

Benchmark results

Run with cargo bench -p lance-core --bench row_addr_mask.

Producer: insert one run covering N rows

N	insert_range (existing)	insert_run (new)	speedup
10K	54 ns	31 ns	1.8×
100K	67 ns	31 ns	2.2×
1M	543 ns	31 ns	17.7×
10M	6.5 µs	31 ns	210×

Consumer: iterate selection of N rows

N	into_addr_iter (existing)	iter_runs (new)	speedup
10K	19.4 µs	6.3 ns	3,078×
100K	193 µs	6.4 ns	30,209×
1M	1.94 ms	6.3 ns	306,879×
10M	19.9 ms	6.3 ns	3,154,000×

Producer: K runs summing to 1M rows

K	insert_range (existing)	insert_run (new)	speedup
1	608 ns	32 ns	19.2×
10	827 ns	199 ns	4.2×
100	3.1 µs	769 ns	4.1×
1,000	28.4 µs	5.7 µs	5.0×
10,000	273 µs	49 µs	5.6×

Test plan

• All 97 pre-existing utils::mask tests still pass.
• 11 new unit tests cover:
  • insert_run invariant preservation on in-order, out-of-order, and
    overlapping inputs.
  • insert_run degradation rules: Full → no-op, Partial → stays
    Partial, empty/Runs → stays Runs.
  • iter_runs against pure-Runs, pure-Partial, and mixed-variant maps.
  • canonicalize_to_partial converts Runs to Partial in place.
  • Serialization round-trip: a Runs-built map and the equivalent
    Partial-built map produce byte-identical on-disk output.
  • Set operations (&, |, -) yield identical cardinalities for
    Runs-built and Partial-built equivalent inputs.
• cargo build --workspace --tests clean.
• cargo bench -p lance-core --bench row_addr_mask runs end-to-end
  and the criterion change: output confirms into_addr_iter was not
  regressed by the new variant.

Follow-ups (not in this PR)

1. Migrate lance_index::scalar::zoned::search_zones from
   RowAddrTreeMap::insert_range to insert_run. This is the producer
   half of the zonemap IS NULL hot path.
2. Migrate lance_table::rowids::RowIdSequence::mask_to_offset_ranges's
   U64Segment::Range arm to consume iter_runs instead of
   materializing the source range and intersecting. Closes the consumer
   half.
3. Add native run-shaped intersection (Runs ∩ Runs → Runs) once a
   call site materializes that they want the result-side representation
   preserved.
4. Optional: a serialization-format minor-version bump so Runs can be
   written on the wire too, avoiding the inflate-on-write step. Not
   needed for any of (1)–(3) since current call sites build masks
   in-memory per query.

🤖 Generated with Claude Code

[codecov]

Codecov Report

❌ Patch coverage is 79.15567% with 79 lines in your changes missing coverage. Please review.

Files with missing lines	Patch %	Lines
rust/lance-core/src/utils/mask.rs	80.00%	67 Missing and 8 partials ⚠️
rust/lance/src/io/exec/filtered_read.rs	0.00%	4 Missing ⚠️

📢 Thoughts on this report? Let us know!