[Sequence] Add "terminal" methods: aggregation

[nikophil]

Third of four PRs bringing the terminal vocabulary to Sequence — element access
landed in #29, querying in #31, aggregation here, then forEach/toMap. This adds
fold, reduce/reduceOrNull, sum, avg/avgOrNull, min/max (+ OrNull),
minOf/maxOf (+ OrNull) and joinToString.

The whole batch is shared

#29 settled that a body identical on both sides lives in IterableTerminalsLogic
rather than being copied, and #31 split five methods off that way. This time
nothing splits: 232 lines leave CollectionLogic for the trait and
SequenceLogic gains not a single line — both sides already use the trait, so
the sequence picks these up by declaring them on the interface.

That is not a coincidence. What kept isEmpty, contains and count per side in
#31 was the store: the eager side answers them in O(1) where a sequence has to
pull. An aggregation has no such shortcut — sum, min, avg and friends have to
visit every element whatever they are backed by, so the eager body is the lazy
body. Collection behaviour is unchanged, and its existing suite is what proves
it.

The OrNull variants stop swallowing the caller's exceptions

This is the one behavioural change, and it touches Collection too. The eager
OrNull methods were try-catch wrappers:

public function reduceOrNull(Closure $operation): mixed
{
    try {
        return $this->reduce($operation);
    } catch (UnsupportedOperationException) {
        return null;
    }
}

The catch cannot tell its own empty-subject throw from one raised inside
$operation, which is user code. So reduceOrNull() reported null — "the
subject was empty" — for a subject that was not empty at all, and the same held for
minOrNull/maxOrNull/minOfOrNull/maxOfOrNull against a selector raising
NoSuchElementException. Rare, but it turns a real error into a plausible answer,
which is the failure mode worth spending code on.

Each OrNull now walks on its own and returns null when nothing was found — no
flag needed, the accumulator simply stays null. Two parity tests on the eager
side pin the propagation
(reduceOrNull_propagates_an_UnsupportedOperationException_thrown_by_the_operation,
minOrNull_propagates_a_NoSuchElementException_thrown_by_the_selector), and
the_OrNull_extremes_propagate_a_NoSuchElementException_thrown_by_the_selector
does the same on the lazy side. The duplication that buys is four short loops.

Empty-subject messages

UnsupportedOperationException gets cannotReduceEmptySubject() and
cannotAverageEmptySubject(), joining NoSuchElementException::emptySubject() on
the NamesItsSubject trait — a sequence must not be told a "Collection" is empty.
lcfirst leaves avg()'s eager wording byte-identical; reduce() gains the
message it never carried (it threw a bare UnsupportedOperationException).

Laziness, pinned

Aggregations drain — that is what they are — but the tests say so out loud rather
than leaving it implied: the_other_aggregations_drain_the_source counts what the
source handed out, an_aggregation_consumes_a_pass_of_a_one_shot_source and
aggregation_replays_over_a_replayable_source hold the replayability contract, and
joinToString_stops_pulling_at_the_limit shows the one method here that
short-circuits: past $limit it appends $truncated and stops asking.
aggregation_matches_its_collection_counterpart asserts the eager and lazy answers
are the same values.

Types

tests/Type/Sequence/AggregationTypeTest.php covers what the PHPDoc promises:
fold returns the accumulator type R rather than E, min/max hand back E
(declared : mixed) while minOf/maxOf hand back the selector's R, and sum's
conditional return type narrows to int for a sequence of ints and widens to
float|int as soon as a float appears on either side — including when it appears
through a map() upstream rather than at the source.

#[NoDiscard]

None of these take it — they hand back a scalar or an element rather than a new
container, which is where #29 settled the rule.

Not in this batch

toMap() and forEach() are the fourth PR. findLast/expectLast and
random/randomOrNull are still open questions on #23 rather than omissions.

Related to #23, follows #31.

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.

📢 Thoughts on this report? Let us know!

[delacry]

Hi, sorry for the late response, I was on a vacation, and then I needed another vacation from my vacation 😄 so I'll try to look at it by the end of this week.

[nikophil]

Haha no rush, hope vacation were good

[delacry]

Thanks!