feat(minor): Enable cross-module specialisation of iterators + add Histogram.add(_:) merge API

[hassila]

Summary

• Part 1 — @inlinable iterator hot paths. Enable cross-module generic specialisation for iterator next() and all supporting helpers so downstream consumers compiling against Histogram<Count> from another SwiftPM target can specialise on the concrete Count. Fixes the _swift_getGenericMetadata / MetadataCacheKey::operator== hot path that showed up in a profiled consumer.
• Part 2 — new Histogram.add(_ other:) merge API. Direct element-wise bucket sum; the operation the motivating consumer was previously reaching for by iterating recordedValues() and calling record(_:count:) into the target.

Both changes are additive and ABI-compatible (no public type/method signature changed or removed).

Context

Profiling a downstream consumer on a 3.4 GB workload showed _swift_getGenericMetadata / swift::MetadataCacheKey::operator== dominating Histogram<UInt64>.RecordedValues.next() — roughly 6% of main-thread wall time. Annotating the caller with @_assemblyVision in release build produced:

Unable to specialize generic function "Histogram.Histogram.recordedValues()" since definition is not visible
Unable to specialize generic function "Histogram.Histogram.RecordedValues.next()" since definition is not visible

Root cause: Histogram<Count> is generic, but the iterator bodies are not @inlinable, so cross-module callers can't see through them and every iteration step falls back to runtime generic dispatch with metadata-cache lookups.

Changes in Sources/Histogram/Histogram.swift

Part 1 — @inlinable / @usableFromInline

• IteratorImpl becomes @usableFromInline; every stored property and every method (init, hasNext, moveNext, makeIterationValueAndUpdatePrev, exhaustedSubBuckets, valueIteratedTo, incrementSubBucket) annotated accordingly.
• Every iterator family — Percentiles, LinearBucketValues, LogarithmicBucketValues, RecordedValues, AllValues — has its stored properties marked @usableFromInline and its init / next() / private helpers marked @inlinable (with their private removed where needed so the inliner can see them).
• Public accessors recordedValues(), allValues(), percentiles(_:), linearBucketValues(_:), logarithmicBucketValues(_:_:) marked @inlinable.
• Transitive helpers reached from the iterator hot paths marked @inlinable (with @usableFromInline where previously internal, and private removed where present): highestEquivalentForValue, lowestEquivalentForValue, nextNonEquivalentForValue, sizeOfEquivalentRangeForValue, sizeOfEquivalentRangeFor, valueFromIndex, valueFrom, subBucketIndexForValue, bucketIndexForValue, countsIndexForValue, countsIndexFor.
• Stored fields on Histogram that the above reach — bucketCount, subBucketMask, subBucketHalfCountMagnitude, leadingZeroCountBase, unitMagnitude — marked @usableFromInline.
• Computed subBucketCount / subBucketHalfCount marked @usableFromInline with @inlinable get.
• IterationValue gets an explicit @usableFromInline memberwise initializer (the synthesised one was internal), so makeIterationValueAndUpdatePrev can construct it from an @inlinable context.

Part 2 — add(_:)

New @inlinable public mutating func add(_ other: Histogram) that traps on shape mismatch (counts.count, numberOfSignificantValueDigits, lowestDiscernibleValue) and otherwise sums the count arrays element-wise (&+=) via withUnsafeMutableBufferPointer / withUnsafeBufferPointer. _totalCount is summed; maxValue and minNonZeroValue take the correct max/min.

Tests

New Tests/HistogramTests/HistogramMergeTests.swift:

• testMergeRoundTrip — splits a mixed-value batch across two histograms, merges, and verifies totalCount, maxRecorded, minNonZero, valueAtPercentile at 0 / 25 / 50 / 75 / 90 / 99 / 99.9 / 100, and bucket-by-bucket equality, all against a reference histogram that recorded the same batch directly.
• testAddEmptyOtherLeavesSelfUnchanged — merging an empty histogram leaves self equal to its pre-merge snapshot.
• testAddSelfDoublesCounts — a.add(a) doubles every bucket count (and totalCount), leaves max / min unchanged.
• testShapeMismatchesAreObservable — documents and verifies each shape-mismatch input class (differing highestTrackableValue, numberOfSignificantValueDigits, lowestDiscernibleValue). A note explains that catching the precondition trap itself requires signal-handling test infra (CwlPreconditionTesting or similar) that the package doesn't currently depend on, so the test asserts that the guarded conditions really are differing shapes.

Full test run: 54 tests passed, 0 failures.

Verifying specialisation — @_assemblyVision before / after

Minimal downstream package depending on this one via local path, with:

import Histogram

@_assemblyVision
public func consume(_ h: Histogram<UInt64>) -> UInt64 {
    var total: UInt64 = 0
    for v in h.recordedValues() { total &+= UInt64(v.count) }
    return total
}

Built with swift build -c release 2>&1 | tee /tmp/av.txt, then grep "Unable to specialize" /tmp/av.txt:

Before

$ grep -c "Unable to specialize" /tmp/av-before.txt
80

$ grep "Unable to specialize" /tmp/av-before.txt | grep -oE '"[^"]+"' | sort -u
"Histogram.Histogram.AllValues.next()"
"Histogram.Histogram.LinearBucketValues.next()"
"Histogram.Histogram.LogarithmicBucketValues.next()"
"Histogram.Histogram.Percentiles.next()"
"Histogram.Histogram.RecordedValues.next()"
"Histogram.Histogram.allValues()"
"Histogram.Histogram.linearBucketValues(valueUnitsPerBucket:)"
"Histogram.Histogram.logarithmicBucketValues(valueUnitsInFirstBucket:logBase:)"
"Histogram.Histogram.percentiles(ticksPerHalfDistance:)"
"Histogram.Histogram.recordedValues()"

(All ten of the iterator accessors and their next() methods miss specialisation. 80 total emission points across the consumer's five @_assemblyVision functions.)

After

$ grep -c "Unable to specialize" /tmp/av-after.txt
0

$ grep "Specialized function" /tmp/av-after.txt | grep -oE '"[^"]+"' | sort -u
"Histogram.Histogram.AllValues.next()"
"Histogram.Histogram.LinearBucketValues.next()"
"Histogram.Histogram.LogarithmicBucketValues.next()"
"Histogram.Histogram.Percentiles.next()"
"Histogram.Histogram.RecordedValues.next()"
"Histogram.Histogram.add(_:)"
"Histogram.Histogram.allValues()"
"Histogram.Histogram.linearBucketValues(valueUnitsPerBucket:)"
"Histogram.Histogram.logarithmicBucketValues(valueUnitsInFirstBucket:logBase:)"
"Histogram.Histogram.percentiles(ticksPerHalfDistance:)"
"Histogram.Histogram.recordedValues()"
"Swift.Sequence<>.makeIterator()"

The previously-unspecialisable functions are now concretely specialised for Histogram<UInt64>. For example:

Specialized function "Histogram.Histogram.RecordedValues.next()" with type
  (@inout Histogram<UInt64>.RecordedValues) -> @out Optional<Histogram<UInt64>.IterationValue>
Specialized function "Histogram.Histogram.recordedValues()" with type
  (@guaranteed Histogram<UInt64>) -> @out Histogram<UInt64>.RecordedValues
Specialized function "Histogram.Histogram.add(_:)" with type
  (@in_guaranteed Histogram<UInt64>, @inout Histogram<UInt64>) -> ()

Scope notes

• No public API type or signature changed. add(_:) is additive.
• Storage layout of Histogram and IteratorImpl is unchanged — only attributes added.
• @inlinable locks the implementation into the ABI surface; for these paths the algorithm is determined by the HDR histogram layout itself so that tradeoff seems fine.

Test plan

• swift build clean
• swift test — 54/54 pass
• @_assemblyVision smoke: 80 → 0 "Unable to specialize" remarks; iterator next() specialisations now visible
• Project CI (runs on PR open)