fix(core): AggregateException composes its message unconditionally (#2309)

SR-AUD-098 clauses C2/C3/C4. AggregateException("outer", {a, b}) reported "outer"
and DISCARDED the contained diagnostics; .NET composes unconditionally whenever
there are inner exceptions.

THE TICKET'S TWO BLOCKING GROUNDS ANSWER EACH OTHER.

Ground 1 was representation: composition (C2) and preservation (C3/C4) cannot both
hold under ONE stored string. The ticket measured all five candidate models --
closing C2 alone works, closing C3/C4 alone works, and closing BOTH yields
"custom outer (a) (b) (a) (b)" and GROWS WITHOUT BOUND under repeated Flatten().
The only escape is a second std::string, which is exactly SA-3's case: a private
data member on a public type with no vtable, mangled-symbol, signature or noexcept
change. Taken. sizeof(AggregateException) 192 -> 224 and
sizeof(UnobservedTaskExceptionEventArgs) -- a public header holding one by value --
208 -> 240, both pinned by a layout test. Consumers must rebuild; no source change.

Ground 2 was the reference text, and /rv settles it:

    if (_innerExceptions.Length == 0) return base.Message;
    sb.Append(base.Message); sb.Append(' ');
    for (...) { sb.Append('('); sb.Append(_innerExceptions[i].Message); sb.Append(") "); }
    sb.Length--;                                    -- AggregateException.cs:339-360

Two details are transcribed rather than reconstructed. The composition is
UNCONDITIONAL when there are leaves -- this port composed only for the DEFAULT
message, which is the C2 defect and an inconsistency with itself. And the trailing
`sb.Length--` means the string ends at ")" with no trailing space; that is
reproduced by appending ") " and dropping the last character rather than by
special-casing the final element, so the two spellings cannot drift apart.

FLATTEN AND HANDLE DIFFER, AND THAT IS .NET'S DOING.

    Flatten: new AggregateException(GetType() == typeof(AggregateException)
                                        ? base.Message : Message, ...)          :335
    Handle:  throw new AggregateException(Message, unhandled.ToArray(), ...)     :281

Flatten passes the RAW message for a plain AggregateException and the COMPOSED one
for a derived type -- and that discrimination is precisely what stops repeated
flattening from accreting leaf text, which is the pathology the ticket measured.
Handle passes the COMPOSED one, so a rethrown aggregate legitimately lists its
leaves twice. The two are transcribed separately rather than sharing a helper that
would hide the difference. typeid is the C++ counterpart of GetType(), and this
class is polymorphic, so it reads the dynamic type as .NET's does.

The composition runs in the CONSTRUCTOR rather than the getter. That is
observationally identical rather than a shortcut: innerExceptions_ is fixed at
construction and never mutated, here and in .NET, where _innerExceptions is a
ReadOnlyCollection assigned once. Composing on access would additionally force
getMessageProperty() to stop returning const std::string&, which is a public
signature change this needs no part of.

Three pins inverted, four cases added. Five mutations, all caught.

ALSO REPAIRED: a pre-existing flake this ticket's gate run caught.
StopwatchDefinedArithmeticTests.Fix2326_TheResolutionThatWasLost took 200 pairs of
back-to-back timestamps and required the smallest positive delta to be under 100
units -- which measures the MACHINE, not the code. It passed eight times out of
eight in isolation and failed once inside a full gate, where any of the 200 pairs
can be preempted. The property is a UNIT, so it is now asserted against a unit:
GetTimestamp() samples steady_clock's own epoch, so a division by 100 would put its
value two orders of magnitude below the same clock read directly. A comparison of
values, immune to scheduling -- and it still catches the mutation that restores the
division. A test that is intermittently green is not evidence (#2352).

Downstream: neither cna nor mobile-eggbert references AggregateException -- zero
sites in both. The rebuild requirement is recorded for any future consumer.

Gate: 17,333 run, 17,333 passed, 0 failed, 0 skipped across 38 executables, GREEN,
confirmed by two consecutive full runs.

docs/Migration-AggregateExceptionRawMessage.md

Author: robertvokac

CLAUDE.md

@@ -0,0 +1,114 @@
+<!-- SPDX-License-Identifier: MIT -->
+<!-- Copyright (c) Robert Vokac and contributors -->
+
+# Migration — `AggregateException` composes its message unconditionally (ticket #2309)
+
+*2026-08-18.* `AggregateException("outer", {a, b}).what()` is now `"outer (a) (b)"`. It used to be
+`"outer"` — the contained diagnostics were **discarded** whenever the caller supplied a message.
+
+`sizeof(AggregateException)` grows **192 → 224** and `sizeof(UnobservedTaskExceptionEventArgs)`
+**208 → 240**. **Downstream consumers must be recompiled**; no source change is needed.
+
+Landed under `docs/StandingApprovals.md` **SA-3** (a private data member on a public type, with no
+vtable, mangled-symbol, signature or `noexcept` change, the before/after `sizeof` pinned by a
+layout test, and the full gate).
+
+---
+
+## 1. What changed
+
+| Expression | Was | Is |
+|---|---|---|
+| `AggregateException("outer", {a, b})` | `"outer"` | `"outer (a) (b)"` |
+| `AggregateException("outer", a)` | `"outer"` | `"outer (a)"` |
+| `AggregateException({a, b})` | `"One or more errors occurred. (a) (b)"` | **unchanged** |
+| `AggregateException("bare")` | `"bare"` | **unchanged** — no leaves, no composition |
+| `outer.Flatten()` | `"One or more errors occurred. (a) (b)"` | `"outer (a) (b)"` — the caller's message survives |
+| `outer.Flatten().Flatten()` | — | `"outer (a) (b)"` — **does not accrete** |
+| `Handle` rethrow | — | composed twice, deliberately — §4 |
+
+## 2. Why the ticket was blocked, and what unblocked it
+
+#2309 was blocked on two independent grounds.
+
+**Ground 1 — representation.** Composition (C2) and preservation (C3/C4) cannot both hold under
+one stored string. The ticket measured all five candidate models: closing C2 alone works, closing
+C3/C4 alone works, and closing **both** yields `"custom outer (a) (b) (a) (b)"` and **grows
+without bound under repeated `Flatten()`**. The only escape is a second `std::string`.
+
+That is exactly SA-3's case, so the field is taken.
+
+**Ground 2 — reference text.** The composed grammar, and whether `Flatten`/`Handle` pass the raw
+or the composed message, were unverifiable. `/rv` settles both, and the answer is what makes the
+second field work.
+
+## 3. The grammar
+
+```csharp
+if (_innerExceptions.Length == 0) return base.Message;
+sb.Append(base.Message); sb.Append(' ');
+for (…) { sb.Append('('); sb.Append(_innerExceptions[i].Message); sb.Append(") "); }
+sb.Length--;                                          // AggregateException.cs:339-360
+```
+
+Two details are transcribed rather than reconstructed. The composition is **unconditional** when
+there are leaves — this port composed only for the *default* message, which is the C2 defect. And
+the trailing `sb.Length--` means the string ends at `")"` with **no** trailing space; that is
+reproduced by appending `") "` and dropping the last character, rather than by special-casing the
+final element, so the two spellings cannot drift apart.
+
+The composition happens in the constructor rather than in the getter, and that is observationally
+identical rather than a shortcut: `innerExceptions_` is fixed at construction and never mutated,
+here and in .NET, where `_innerExceptions` is a `ReadOnlyCollection` assigned once. Composing on
+access would additionally force `getMessageProperty()` to stop returning `const std::string&` —
+a public signature change this needs no part of.
+
+## 4. `Flatten` and `Handle` differ, and that is .NET's doing
+
+```csharp
+// Flatten
+new AggregateException(GetType() == typeof(AggregateException) ? base.Message : Message, …)   // :335
+// Handle
+throw new AggregateException(Message, unhandledExceptions.ToArray(), …)                       // :281
+```
+
+`Flatten` passes the **raw** message for a plain `AggregateException` and the **composed** one for
+a derived type. That discrimination is precisely what stops repeated flattening from accreting
+leaf text — the pathology the ticket measured. `typeid` is the C++ counterpart of `GetType()`, and
+this class is polymorphic, so it reads the *dynamic* type as .NET's does.
+
+`Handle` passes the **composed** message. So a rethrown aggregate's message contains the leaves
+twice: `"custom outer (a) (b) (a) (b)"`. That is .NET's behaviour, not an accident here, and the
+two are transcribed separately rather than sharing a helper that would hide the difference.
+
+## 5. To migrate
+
+Rebuild. If you assert on an `AggregateException`'s message and supplied your own, expect the
+leaves to follow it.
+
+## 6. Evidence
+
+| Mutation | Caught |
+|---|---|
+| `Flatten` passes the composed message (the unbounded-growth pathology) | ✅ (2 tests) |
+| `Handle` passes the raw message (Flatten's rule, not its own) | ✅ |
+| Compose only for the default message (the pre-#2309 C2 behaviour) | ✅ (4 tests) |
+| Keep the trailing space (drop the `pop_back`) | ✅ (4 tests) |
+| The separator loses its space | ✅ (4 tests) |
+
+## 7. A pre-existing flake this ticket's gate run caught
+
+`StopwatchDefinedArithmeticTests.Fix2326_TheResolutionThatWasLost` took 200 pairs of back-to-back
+timestamps and required the smallest positive delta to be under 100 units. **That measures the
+machine, not the code**: it passed eight times out of eight in isolation and failed once inside a
+full gate, where any of the 200 pairs can be preempted.
+
+The property is a **unit**, so it is now asserted against a unit: `GetTimestamp()` samples
+`steady_clock`'s own epoch, so a division by 100 would put its value two orders of magnitude below
+the same clock read directly. That is a comparison of values, immune to scheduling — and it still
+catches the mutation that restores the division.
+
+## 8. Downstream
+
+Neither `cna` nor `mobile-eggbert` references `AggregateException` — zero sites in both. The
+rebuild requirement is recorded here for any future consumer.

docs/Migration-AggregateExceptionRawMessage.md

@@ -3,6 +3,7 @@
 // Portions based on .NET runtime API (MIT License, Copyright .NET Foundation and Contributors)
 #pragma once
 #include <functional>
+#include <typeinfo>
 #include <initializer_list>
 #include <memory>
 #include <stdexcept>
@@ -23,6 +24,31 @@ namespace System {
 class AggregateException : public Exception {
     std::vector<std::exception_ptr> innerExceptions_;
 
+    /**
+     * @brief The message the CALLER supplied, before composition.
+     *
+     * Ticket #2309 (SR-AUD-098 clauses C2/C3/C4), landed under `docs/StandingApprovals.md` SA-3.
+     *
+     * .NET stores the raw message and composes `Message` on every access
+     * (`AggregateException.cs:339-360`); this port stored only the composed result. The ticket
+     * measured why one string cannot serve both: closing C2 alone works, closing C3/C4 alone
+     * works, and closing BOTH under one stored string yields
+     * `"custom outer (a) (b) (a) (b)"` and **grows without bound under repeated `Flatten()`**.
+     * A second field is the only escape, and it is exactly SA-3's case.
+     *
+     * The composition happens in the constructor rather than in the getter, and that is
+     * observationally identical rather than a shortcut: `innerExceptions_` is fixed at
+     * construction and never mutated, in this port and in .NET (`_innerExceptions` is a
+     * `ReadOnlyCollection` assigned once). Composing on access would additionally require
+     * `getMessageProperty()` to stop returning `const std::string&`, which is a public signature
+     * change this needs no part of.
+     *
+     * `sizeof(AggregateException)` grows **192 → 224** and
+     * `sizeof(UnobservedTaskExceptionEventArgs)` — a public header holding one by value —
+     * **208 → 240**. Both are pinned by a layout test; consumers must rebuild.
+     */
+    std::string rawMessage_;
+
     /**
      * @brief Rejects a null entry in a collection of inner exceptions.
      *
@@ -98,40 +124,66 @@ class AggregateException : public Exception {
         // initializer is sequenced before every member initializer, so validating here
         // also protects innerExceptions_ in the constructors that build their message
         // from the same vector.
+        return composeMessage("One or more errors occurred.", exs);
+    }
+
+    /**
+     * @brief .NET's `Message` composition, transcribed.
+     *
+     * @code
+     * if (_innerExceptions.Length == 0) return base.Message;
+     * sb.Append(base.Message); sb.Append(' ');
+     * for (…) { sb.Append('('); sb.Append(_innerExceptions[i].Message); sb.Append(") "); }
+     * sb.Length--;                                   // AggregateException.cs:339-360
+     * @endcode
+     *
+     * Ticket #2309 corrected two things here. First, the composition is **unconditional** when
+     * there are inner exceptions: this port composed only when the message was the default one,
+     * so `AggregateException("custom outer", {a, b})` reported `"custom outer"` and **discarded
+     * the leaves**, which is C2. Second, the separator is `") ("` in both, but the trailing
+     * `sb.Length--` means .NET ends at `")"` with **no** trailing space — reproduced by
+     * appending `") "` and dropping the last character, rather than by special-casing the last
+     * element, so the two spellings cannot drift.
+     */
+    static std::string composeMessage(const std::string& raw,
+                                      const std::vector<std::exception_ptr>& exs) {
+        // Ahead of the loop below, because that loop is the first of the three
+        // std::rethrow_exception call sites a null entry would reach. A base-class
+        // initializer is sequenced before every member initializer, so validating here
+        // also protects innerExceptions_ in the constructors that build their message
+        // from the same vector.
         requireNoNullElements(exs);
-        if (exs.empty()) return "One or more errors occurred.";
-        std::string m = "One or more errors occurred. (";
-        bool first = true;
+        if (exs.empty()) return raw;
+        std::string m = raw;
+        m += ' ';
         for (auto& ep : exs) {
+            m += '(';
             try { std::rethrow_exception(ep); }
-            catch (const std::exception& e) {
-                if (!first) m += ") (";
-                m += e.what();
-                first = false;
-            } catch (...) {
-                if (!first) m += ") (";
-                m += "unknown error";
-                first = false;
-            }
+            catch (const std::exception& e) { m += e.what(); }
+            catch (...) { m += "unknown error"; }
+            m += ") ";
         }
-        m += ")";
+        m.pop_back();
         return m;
     }
 
 public:
     /** @brief Initializes a new instance with the default aggregate error message. */
-    AggregateException() : Exception("One or more errors occurred.") {}
+    AggregateException() : Exception("One or more errors occurred."),
+                           rawMessage_("One or more errors occurred.") {}
 
     /** @brief Initializes a new instance with the specified error message. */
-    explicit AggregateException(const std::string& message) : Exception(message) {}
+    explicit AggregateException(const std::string& message)
+        : Exception(message), rawMessage_(message) {}
 
     /**
      * @brief Initializes a new instance with a collection of inner exceptions.
      * @throws System::ArgumentException if any entry is a null `std::exception_ptr`.
      */
     explicit AggregateException(std::vector<std::exception_ptr> innerExceptions)
         : Exception(buildMessage(innerExceptions), firstValidatedInnerOf(innerExceptions)),
-          innerExceptions_(std::move(innerExceptions)) {}
+          innerExceptions_(std::move(innerExceptions)),
+          rawMessage_("One or more errors occurred.") {}
 
     /**
      * @brief Initializes a new instance with an initializer list of inner exceptions.
@@ -145,8 +197,10 @@ class AggregateException : public Exception {
      * @throws System::ArgumentException if any entry is a null `std::exception_ptr`.
      */
     AggregateException(const std::string& message, std::vector<std::exception_ptr> innerExceptions)
-        : Exception(message, firstValidatedInnerOf(innerExceptions)),
-          innerExceptions_(std::move(innerExceptions)) {}
+        : Exception(composeMessage(message, innerExceptions),
+                    firstValidatedInnerOf(innerExceptions)),
+          innerExceptions_(std::move(innerExceptions)),
+          rawMessage_(message) {}
 
     /**
      * @brief Initializes a new instance with a message and a single inner exception.
@@ -159,8 +213,9 @@ class AggregateException : public Exception {
      * @throws System::ArgumentNullException if @p innerException is null.
      */
     AggregateException(const std::string& message, std::exception_ptr innerException)
-        : Exception(message, requireNonNullInner(innerException)),
-          innerExceptions_({innerException}) {}
+        : Exception(composeMessage(message, {innerException}), requireNonNullInner(innerException)),
+          innerExceptions_({innerException}),
+          rawMessage_(message) {}
 
     /**
      * @brief Gets the read-only collection of inner exceptions that caused this aggregate exception.
@@ -263,7 +318,20 @@ class AggregateException : public Exception {
                 }
             }
         }
-        return AggregateException(std::move(flat));
+        // #2309. .NET is
+        //     new AggregateException(GetType() == typeof(AggregateException) ? base.Message
+        //                                                                    : Message, ...)
+        //                                                    -- AggregateException.cs:335
+        // The RAW message for a plain AggregateException, the COMPOSED one for a derived type.
+        // That discrimination is what stops repeated Flatten() from accreting leaf text: passing
+        // the composed message here yields "custom outer (a) (b) (a) (b)" and grows without
+        // bound, which is exactly the pathology this ticket measured before the raw field existed.
+        //
+        // typeid is the C++ counterpart of GetType(), and this class is polymorphic, so it reads
+        // the DYNAMIC type -- a derived aggregate takes the other arm, as .NET's does.
+        return AggregateException(
+            typeid(*this) == typeid(AggregateException) ? rawMessage_ : getMessageProperty(),
+            std::move(flat));
     }
 
     /**
@@ -289,7 +357,12 @@ class AggregateException : public Exception {
         for (auto& ep : innerExceptions_) {
             if (!predicate(ep)) unhandled.push_back(ep);
         }
-        if (!unhandled.empty()) throw AggregateException(std::move(unhandled));
+        // #2309. Handle passes the COMPOSED message, not the raw one --
+        // `throw new AggregateException(Message, unhandledExceptions.ToArray(), ...)`
+        // (AggregateException.cs:281). It differs from Flatten deliberately and the two are
+        // transcribed separately rather than being given one shared helper that would hide it.
+        if (!unhandled.empty())
+            throw AggregateException(getMessageProperty(), std::move(unhandled));
     }
 };
 

modules/core/include/System/AggregateException.hpp

@@ -241,15 +241,29 @@ TEST(StopwatchDefinedArithmeticTests, Fix2326_FrequencyIsTheClocksOwnNotTheTimeS
 TEST(StopwatchDefinedArithmeticTests, Fix2326_TheResolutionThatWasLost) {
     // WHY THE OLD VALUE WAS A DEFECT AND NOT MERELY A DIFFERENT CHOICE. GetTimestamp() used to
     // divide the clock's nanosecond count by 100, so anything finer than 100 ns was truncated
-    // away. Two timestamps taken back to back must now be able to differ by less than 100 units.
-    long long minimumDelta = kLongMax;
-    for (int i = 0; i < 200; ++i) {
-        const long long a = Stopwatch::GetTimestamp();
-        const long long b = Stopwatch::GetTimestamp();
-        if (b > a) minimumDelta = std::min(minimumDelta, b - a);
-    }
-    EXPECT_LT(minimumDelta, 100LL)
+    // away.
+    //
+    // REWRITTEN BY #2309's GATE RUN (2026-08-18). The first version took 200 pairs of back-to-back
+    // timestamps and required the smallest positive delta to be under 100 units. That measures the
+    // MACHINE, not the code: it passed eight times out of eight in isolation and failed once
+    // inside a full gate, where every one of the 200 pairs can be preempted. A test that is
+    // intermittently green is not evidence (#2352).
+    //
+    // The property is a UNIT, so it is asserted against a unit. GetTimestamp() samples
+    // steady_clock's own epoch, so a division by 100 would put its value two orders of magnitude
+    // below the same clock read directly -- a comparison of VALUES, immune to scheduling.
+    const auto chronoNanoseconds = std::chrono::duration_cast<std::chrono::nanoseconds>(
+                                       std::chrono::steady_clock::now().time_since_epoch())
+                                       .count();
+    const long long timestamp = Stopwatch::GetTimestamp();
+    ASSERT_GT(chronoNanoseconds, 0LL) << "the clock's epoch is too close to now to discriminate";
+    EXPECT_GT(timestamp, chronoNanoseconds / 2)
         << "GetTimestamp() is still quantised to 100 ns -- the #2326 division is back";
+    EXPECT_LT(timestamp / 2, chronoNanoseconds);
+
+    // The same statement from the other side: the declared frequency IS the clock's own, so one
+    // unit is one nanosecond rather than one hundred.
+    EXPECT_EQ(Stopwatch::Frequency, 1000000000LL);
 }
 
 TEST(StopwatchDefinedArithmeticTests, GetElapsedTime_MinToMax_WrapsToMinusOne) {