fix: int64 overflow in linear/log iterator reporting level (near INT64_MAX)

[filipecosta90]

Stacked on #148 (the iterators call move_next, whose value-range overflow #148 fixes). Base this PR on #148; retarget to main once #148 merges.

Bug (found by adversarial review during the ClusterFuzzLite effort)

For a histogram with highest_trackable_value near INT64_MAX, the linear and log iterators overflow int64 when advancing the reporting level:

• iter_linear_next (:1162): next_value_reporting_level += value_units_per_bucket
• log_iter_next (:1219): next_value_reporting_level *= (int64_t) log_base

Both are in-contract (public iterators) and reachable via any full linear/log iteration of such a histogram; the wrapped negative level then triggers a negative left-shift in lowest_equivalent_value.

Fix

Saturate the reporting level at INT64_MAX when the next step would overflow. Termination: naive saturation would re-report the top level forever (the emit branch doesn't advance counts_index). Since no bucket value ever equals INT64_MAX, pinning next_value_reporting_level_lowest_equivalent to INT64_MAX as well makes the iter->value >= level test stop firing, so the iterator drains remaining buckets and terminates.

Verification (ASan+UBSan)

• Linear (units=2^62) and log (base 2) over an INT64_MAX histogram: no trap, terminate (2 and 64 steps). Normal-range iteration unchanged. Regression test added; full suite green.

🤖 Generated with Claude Code

[github-actions]

🤖 Automated first-pass review — a human maintainer's review is still required before merge.

The core overflow fix reads correctly to me, and the diff stays on the safe side of the ABI line: no change to struct hdr_histogram, struct hdr_iter, or any public signature, so there's no HDR_SOVERSION_* question here. Three things worth a look:

1. The degenerate-parameter handling is a new, undocumented public-API contract. hdr_iter_linear_init with value_units_per_bucket <= 0, and hdr_iter_log_init with log_base <= 1 or a non-positive first bucket, now quietly produce a draining iteration instead of hanging. Better than an infinite loop, certainly — but my recollection is that Java's LinearIterator/LogarithmicIterator reject those arguments up front rather than degrading, and I haven't actually checked that against the current upstream source, so I'd want that confirmed before settling on saturation as the C semantics. Either way, include/hdr/hdr_histogram.h currently says nothing about the valid range for these parameters and this PR doesn't add it; both init functions return void, so the doc comment is the only place that contract can live.

2. peek_next_value_from_index duplicates hdr_value_at_index's decomposition. The index→(bucket_index, sub_bucket_index) math now exists in two places and will drift. Saturating inside value_from_index, or adding a saturating variant next to it, keeps it in one place.

3. The second commit's message says the peek "reads one past counts[]." It doesn't — hdr_value_at_index is pure arithmetic and never touches the array. The signed-shift UB is real; the out-of-bounds-read framing isn't, and that's the text that ends up in git log for a fix people will go read later.

On coverage: the per-PR ClusterFuzzLite job runs ASan only — UBSan is weekly-batch only — so this whole class of signed-overflow/shift UB isn't caught by the per-PR gate. The added unit test is the real regression gate here, and the 1023-step tail assertion is a good thing to have after the peek-guard revision, given that revision was itself fixing an over-eager guard.

Finally, the description still says to base this on #148 and retarget to main once that merges — worth confirming that's actually done. The last three commits also have empty bodies, unlike the first two, which are unusually good.

[paulorsousa]

Looks like iter.value_iterated_to remains at the previous reporting level after saturation (instead of being updated to INT64_MAX)
Should this test also assert that the final reported value is INT64_MAX?

If so, it should also apply for the log iterator test too