fix: consult segment cache before registering reads

[gatesn]

Constructing a segment request currently registers the underlying read before checking the cache. When neighboring cached requests have not yet been consumed, Vortex can coalesce them into a physical read and fetch bytes already cached.

Resolve the cache lookup before registering a source read. Eagerly poll one request future so ready cold misses retain registration and read coalescing. Suspend after registration until the caller demands the read, and retain pending cache lookups without restarting them. This avoids a separate owned-lookup future allocation. Cache errors still fall through to the source. No new public APIs or cross-open coordination.

Release benchmark with the real Vortex file coalescer, 16 adjacent 4 KiB segments, and the previous adapter compiled into the same binary as the control:

Case	Before	After
Cold, concurrent or ordered demand	1 read / 64 KiB	1 read / 64 KiB
Half cached, ordered demand	1 read / 64 KiB	1 read / 32 KiB
Half cached, concurrent demand	1 read / 32 KiB	1 read / 32 KiB
Fully cached	0 reads	0 reads

Physical counts and bytes held across 101 zero-latency repetitions and 9 repetitions with simulated 2 ms storage latency per case. Cold medians with simulated latency were approximately 3.44–3.45 ms before and after. Zero-latency cold medians were 22.8 → 21.1 µs for concurrent demand and 21.5 → 21.5 µs for ordered demand. These are local coalescing measurements, not remote storage or end-to-end scan performance claims. Ready lookups were measured with the built-in cache; a pending custom cache lookup must resolve before its read can be registered.

Regressions cover ready cache hits, eager miss registration without demanding I/O, pending hits/misses without restarting lookups, cold coalescing with concurrent and ordered demand, and cached bytes excluded from ordered coalesced reads. The release benchmark is an explicitly ignored test in vortex-file/tests/segment_cache_coalescing.rs.

Validation: 7 release cache unit cases and 3 release integration/benchmark cases passed. Reproduce with:

cargo test --release -p vortex-layout segments::cache::tests -- --nocapture
cargo test --release -p vortex-file --test segment_cache_coalescing -- --include-ignored --nocapture

[codspeed]

Merging this PR will improve performance by 24.86%

⚠️ Unknown Walltime execution environment detected

Using the Walltime instrument on standard Hosted Runners will lead to inconsistent data.

For the most accurate results, we recommend using CodSpeed Macro Runners: bare-metal machines fine-tuned for performance measurement consistency.

⚠️ 19 benchmarks spent significant time in system calls

System calls cannot be consistently instrumented, so they are not included in the measure, which understates the real cost. Please switch to the Walltime instrument to accurately measure system calls.

Measurement and system calls

• test_repeated_scan_scalar_at[int]
• chunked_dict_primitive_into_canonical[f64, (1000, 1000, 10)]
• test_scan_filter[int_str]
• test_scan_filter[int_float]
• take_varbin
• test_scan[int_str]
• test_scan_filter[int_str_float]
• random_i128[0.01]
• multipolygon_mixed_validity
• ilike_contains
• …and 9 more

ℹ️ 40 benchmarks have no flame graph

The flamegraph could not be generated because we failed to resolve the symbols in the profiling trace. This happens when we fail to harvest information about language frames.

• test_repeated_scan_scalar_at[int_float]
• test_repeated_scan_scalar_at[int]
• test_repeated_scan_scalar_at[int_str_float]
• test_repeated_scan_scalar_at[int_str]
• test_scan_scalar_at[int_str]
• test_scan_scalar_at[int]
• test_scan_scalar_at[int_str_float]
• test_scan_scalar_at[int_float]
• test_repeated_scan_to_arrow_array[int]
• test_scan_filter_to_arrow_array[int]
• …and 30 more

⚠️ Different runtime environments detected

Some benchmarks with significant performance changes were compared across different runtime environments,
which may affect the accuracy of the results.

Open the report in CodSpeed to investigate

⚡ 2 improved benchmarks
✅ 2257 untouched benchmarks

Performance Changes

	Mode	Benchmark	BASE	HEAD	Efficiency
⚡ ℹ️	Simulation	test_repeated_scan_scalar_at[int_float]	486.7 µs	368.2 µs	+32.21%
⚡	WallTime	filter_neon[80]	2.9 µs	2.5 µs	+17.91%

Tip

Curious why performance improved? Comment @codspeedbot explain why performance improved on this PR, or directly use the CodSpeed MCP with your agent.

---

_{Comparing ngates/segment-cache-loads (3e13bab) with develop (18aebea)}

[joseph-isaacs]

We don't benchmark this anywhere do we?

[robert3005]

Do you have a benchmark?