perf(align): reuse cluster_seeds' window-bin map across reads (-7% median, output-neutral)

[BenjaminDEMAILLE]

Stacked on #184 → #182 → #179 → #178 → #176 → #175 → #174 → #173. Merge in that order. It touches only src/align/stitch.rs and rebases off the solo stack cleanly if you would rather take it alone.

First item of roadmap P3, and not the item P3 led with — see the profile below for why.

The defects

Two, both per-read allocations in cluster_seeds.

1. A rehashing map

cluster_seeds built a fresh FxHashMap per read, pre-sized to anchor_indices.len() * 2. That pre-sizing is only a floor. When two windows merge, the code re-keys every bin in the merged span:

for bin in left_window.bin_start..=left_window.bin_end {
    win_bin.insert((strand, bin), left_idx);
}

so a read with wide windows inserts far more entries than it has anchors, and the map rehashes — inside the function the code itself labels "the #1 align hotspot".

2. A clone thrown away one statement later

clusters.push(SeedCluster {
    alignments: window.alignments.clone(),   // full Vec<WindowAlignment> copy
    ...
});

windows is dropped at the end of the function. The copy existed only to be discarded.

Profile first, since P3 assumed otherwise

Sampled a real human run: 10x pbmc_1k_v3, 20 M read pairs, GRCh38, 14 threads.

	self time
cluster_seeds + its hashbrown::reserve_rehash	19.2%, of which 2.1% is the rehash alone
seed search (compare_seq_to_genome, search_direction_sparse, PackedArray::read)	16.4%
stitch DP (extend_alignment, stitch_recurse, finalize_transcript)	21%
allocator (mimalloc + RawVec::finish_grow)	11.2%
idle / synchronisation	12.5%
inflate (gzip input)	0.5%

P3 led with the batched prefetching seed search, on the strength of a 2.09× the donor measured for that engine. At 16.4% of on-CPU time here, 2.09× on that engine is worth about 8% of wall clock — real, but it is 500 lines of state machine, and find_mult_range probes in ways the donor's batch does not cover. These changes are ten lines against a bigger share.

(That 0.5% for inflate is also a second, independent confirmation of the measurement that closed #183.)

What it does

The map is kept per thread and cleared per read, so its capacity settles at what the workload needs and growth is paid once per thread rather than once per read.

It is taken out of the thread-local with mem::take and handed back at both exit points, rather than borrowed across the body. There is no nested call today; if one appeared it would get a fresh map instead of panicking on an already-active RefCell borrow.

Output-neutral, checked

On the same 20 M read pairs, old binary against new:

matrix.mtx.gz     identical
barcodes.tsv.gz   identical
features.tsv.gz   identical
SJ.out.tab        identical

Compared decompressed, so a change in gzip framing could not be mistaken for a change in output.

Timing, and what I got wrong measuring it

Two changes, both in cluster_seeds: the map reuse above, and moving each window's Vec<WindowAlignment> into its cluster instead of cloning it (windows is dropped one statement later, so every read paid a full copy per window to discard the original).

The honest answer is "a few percent, direction confirmed, magnitude not pinned down." Getting there took two attempts and the first one was biased.

My first harness ran ABAB — old, new, old, new. Under that, new won 8 of 8 pairs, median −7.0%. Then a second run of the same shape had new losing 2 of 3, and the reason was visible in the raw times: the same binary on the same input went 97.5 s → 111.7 s → 122.2 s. The machine was drifting about 20% while I measured a 5% effect, and ABAB is biased under monotonic drift, because within each pair the second binary always runs on the hotter machine. That penalises "new" systematically.

So I rewrote it as ABBA — old, new, new, old — which cancels a linear drift because each binary gets one early and one late slot per block, let the machine cool, and re-ran:

block	old (drift-cancelled mean)	new
1	104.2 s	104.3 s	+0.1%
2	109.3 s	99.0 s	−9.4%
3	103.8 s	97.2 s	−6.3%
4	107.2 s	102.2 s	−4.7%

New faster in 3 of 4 blocks, median −5.5%. Drift across the run, measuring the old binary alone, was still 96.9 s to 116.9 s — a 21% spread against a 5% effect.

Taking both runs together, new is ahead in 11 of 12 comparisons, and the ABAB 8-of-8 counts for more than I first thought since the bias ran against it. What I will not claim is a specific figure: on a machine with a 21% spread, "−5.5%" is a direction with an order of magnitude, not a measurement.

This is exactly what #171 exists to prevent. That PR's harness samples CPU idle before and after every run and drops the rounds it could not measure honestly. It has been open since 29 July. I got caught by precisely the failure mode it was written for, which is the best argument for it I can offer.

What is not in this PR

The rest of P3 — SmallVec in the stitch recursion, Arc<[u8]> for Transcript::read_seq, and the batched seed search — is separate work. The profile above says the allocator is worth 11.2% and the seed search 16.4%, so both are worth doing; neither belongs in a four-line PR.

Gate: 577 lib + 27 integration tests, cargo clippy --all-targets -- -D warnings, cargo fmt --check, all green.