perf: eliminate ref-fetch parallel overhead + fuse variant-window fetches (#221)

[d-laub]

Summary

Eliminates two sources of overhead in the variant-windows reference read path so Reference.fetch scales with bytes copied instead of dominating the decode (issue #221):

• Numba thread cap — numba.get_num_threads() reports host logical CPUs, not the cgroup allocation (e.g. 208 reported vs. 52 allocated), so parallel=True regions paid a flat ~37 ms fork-join for trivial work. New _threads.py caps the worker count to the cgroup-aware core count once at import (overridable via GVL_NUM_THREADS).
• Serial/parallel kernel dispatch — the two reference-copy kernels (_fetch_impl in Reference.fetch, and get_reference) now route to a serial njit below a per-thread byte threshold and a parallel njit above it, via should_parallelize(total_bytes). Both kernels share an inline="always" row body, so serial and parallel are byte-identical by construction.
• Fetch fusion (3 → 1) — the variant-windows flank builders in _flat_flanks.py now do a single [start−L, end+L) read and slice f5/f3 internally. The both-window decode is routed through the fused compute_windows (1 fetch instead of 2). Public signatures are unchanged, so the existing oracle tests act as byte-identity guards.

Test Plan

• pixi run -e dev pytest tests/dataset/ tests/unit/dataset/ tests/unit/test_threads.py → 294 passed, 4 skipped, 2 xfailed
• Kernel-agreement tests (_fetch_impl_ser/_par, _get_reference_ser/_par) confirm serial ≡ parallel, incl. OOB-left/right regions
• Existing _oracle_* / split-equivalence tests confirm the fused fetch is byte-identical to the old separate-fetch path
• New test_variant_windows_single_fetch_per_decode pins the both-window decode to exactly 1 Reference.fetch call (down from 3)
• ruff check python/ clean; pyrefly 0 errors
• Production confirmation against gvf-germ-som per Perf: Reference.fetch dominated by numba parallel=True fork-join overhead in variant-windows path (~37ms/call for tiny windows); also 3 redundant fetches/decode #221 acceptance criteria

Closes #221.

🤖 Generated with Claude Code