fix(core): an all-zero magnitude never overflows, at any exponent (#2356)

Int32::Parse("0E30") threw OverflowException. .NET returns 0.

THE RECORDED ANSWER WAS WRONG, AND SO WAS THE FIRST CORRECTION. Both are
documented rather than quietly replaced.

The ticket asked whether an all-zero magnitude with a non-positive scale
overflows 'as .NET's source says it does'. It never overflows, at any scale.
The decisive line is Number.Parsing.Common.cs:259-268, which runs after the
trailing-token loop and, when StateNonZero was never set, forces Scale = 0 and
clears IsNegative for an integer buffer with no decimal separator. The scale an
all-zero magnitude would have overflowed on is discarded before the fold ever
sees it.

A middle answer was derived and is also wrong, and is recorded as a trap for the
next reader: because line 103 makes a leading zero skip that same block, it does
not advance the scale either, so the count of zeros cannot matter -- '0E-2' and
'00E-2' must agree.

The old gated pin asserted the opposite for the positive case and is replaced,
not extended. Its own comment named why it was unreliable: 'the reading is an
unexecutable source trace'.

Four mutations, two caught, two reported honestly. M2 (dropping the !sawDecimal
guard) is not observable in this port, because the unsigned path rejects '-' in
the grammar -- filed as #2362, and the test now says so instead of implying a
defence it cannot provide. M4 is semantically identical after normalisation.

A pure widening: nothing that parsed before stops parsing. Gate 17,271 run, 0
failed, 38 executables. Record: docs/Migration-IntegerAllZeroMagnitude.md.

Author: robertvokac

docs/Migration-IntegerAllZeroMagnitude.md

@@ -0,0 +1,71 @@
+<!-- SPDX-License-Identifier: MIT -->
+<!-- Copyright (c) Robert Vokac and contributors -->
+
+# Migration — an all-zero magnitude never overflows (ticket #2356)
+
+*2026-08-18.* `Int32::Parse("0E30", NumberStyles::Any)` threw `OverflowException`. .NET returns
+`0`. So does this port now.
+
+Landed under `docs/StandingApprovals.md` SA-5 (derivation from the reference). A **widening**: no
+input that parsed before stops parsing. No signature, layout, vtable or `noexcept` change.
+
+---
+
+## 1. What changed
+
+| Call | Was | Is |
+|---|---|---|
+| `Parse("0E30")` | `OverflowException` | `0` |
+| `Parse("0E100000000")` | `OverflowException` | `0` |
+| `Parse("0E-1")`, `"0E-2"`, `"00E-2"`, `"0.0"` | `0` | `0` — unchanged |
+| `Parse("65E-1")`, `"1E100000000"` | `OverflowException` | unchanged |
+| every input with a nonzero digit | — | **unchanged** |
+
+## 2. Why — and why the recorded answer was wrong twice
+
+The deferred ticket asked whether an all-zero magnitude with a **non-positive scale** overflows
+*"as .NET's source says it does"*. It does not, at any scale, and the pin that guarded the
+question asserted the opposite for the positive case.
+
+The pin's own comment named the reason it was unreliable — *"the reading is an unexecutable source
+trace"* — and the line the trace had missed is `Number.Parsing.Common.cs:259-268`, which runs
+after the trailing-token loop:
+
+```csharp
+if ((state & StateNonZero) == 0)
+{
+    if (number.Kind != NumberBufferKind.Decimal)                  number.Scale = 0;
+    if (number.Kind == NumberBufferKind.Integer && !StateDecimal) number.IsNegative = false;
+}
+```
+
+`StateNonZero` is set only inside `if (ch != '0' || (state & StateNonZero) != 0)`
+(`Number.Parsing.Common.cs:103`), so an all-zero magnitude never sets it — and **the scale it
+would have overflowed on is discarded before `TryNumberBufferToBinaryInteger` ever sees it.**
+
+**A middle answer was reached and is also wrong**, so it is recorded here rather than left as a
+trap for the next reader. Because line 103 makes a *leading* zero skip the whole block, that zero
+does not advance the scale either. So the count of zeros written cannot matter: `"0E-2"` and
+`"00E-2"` must agree, and they do. An implementation that distinguishes them is wrong in one
+direction or the other.
+
+## 3. The second half of the same normalisation
+
+.NET also drops the **sign** — but only for an integer buffer that saw no decimal separator. So
+`UInt32.Parse("-0")` is `0` in .NET while `UInt32.Parse("-0.0")` overflows.
+
+This port does not reproduce that, and the reason is a pre-existing, deliberate deviation rather
+than an oversight: the unsigned grammar rejects `-` outright, so `UInt32::Parse("-0")` and
+`UInt32::Parse("-1")` are both `FormatException` where .NET answers `0` and `OverflowException`.
+Repairing the `"-0"` row alone would align one spelling and leave the other diverging, which is
+worse than the present consistent rule. **Ticket #2362** holds the family.
+
+One honest consequence, measured: the `!sawDecimal` guard in the signed core is therefore
+**unobservable today** — a mutation that drops it is not caught by any test, and was measured not
+to be. It is kept as a faithful transcription that becomes live when #2362 lands, and the test
+says so rather than implying a defence it cannot provide.
+
+## 4. To migrate
+
+Nothing to do. Code that caught `OverflowException` around a zero-valued literal with a large
+exponent will simply stop seeing it.

modules/core/include/System/detail/IntegerNumberStylesParser.hpp

@@ -155,6 +155,7 @@ struct IntegerNumberStylesParser {
         int       digitsCount = 0;      ///< .NET's `number.DigitsCount`.
         long long scale       = 0;      ///< .NET's `number.Scale`.
         bool      any         = false;  ///< .NET's `StateDigits` — at least one digit was seen.
+        bool      sawDecimal  = false;  ///< .NET's `StateDecimal` — a decimal separator was consumed.
         bool      overflowed  = false;  ///< The significant digits do not fit in 64 bits.
     };
 
@@ -203,7 +204,7 @@ struct IntegerNumberStylesParser {
                 }
                 ++i;
             } else if (allowDecimalPoint && !sawDecimal && s[i] == kDecimalSeparator) {
-                sawDecimal = true; ++i;
+                sawDecimal = true; scan.sawDecimal = true; ++i;
             } else if (allowThousands && scan.any && !sawDecimal && s[i] == kGroupSeparator) {
                 ++i;
             } else break;
@@ -247,13 +248,13 @@ struct IntegerNumberStylesParser {
      * however small the number looks. `"65E-1"` is 6.5 and fails here, which is exactly what
      * .NET's own `Int32Tests.cs:548` pins.
      *
-     * @note An all-zero magnitude with a non-positive scale is the one case this port does not
-     *       follow; see the class doc-comment's deviation note and ticket #2356.
+     * @note An all-zero magnitude needs no special case here: the caller has already applied
+     *       .NET's normalisation, which leaves it at scale 0 with no digits, so the general path
+     *       below accepts it and yields 0. Ticket #2356.
      */
     static bool TryFoldScale(DigitScan& scan) {
         if (scan.overflowed) return false;
         if (scan.scale > kMaxSignificantScale) return false;
-        if (scan.digitsCount == 0) { scan.magnitude = 0; return true; }
         if (scan.scale < scan.digitsCount) return false;
         for (long long k = scan.scale - scan.digitsCount; k > 0; --k) {
             if (scan.magnitude > UINT64_MAX / 10) return false;
@@ -335,6 +336,32 @@ struct IntegerNumberStylesParser {
 
         if (haveParen) return false;   // '(' opened but never closed
         if (i != n) return false;
+
+        // .NET's all-zero normalisation (`Number.Parsing.Common.cs:259-268`), transcribed at its
+        // own position -- AFTER the trailing-token loop, which is what makes it reach a TRAILING
+        // sign as well as a leading one.
+        //
+        //     if ((state & StateNonZero) == 0) {
+        //         if (number.Kind != NumberBufferKind.Decimal)                  number.Scale = 0;
+        //         if (number.Kind == NumberBufferKind.Integer && !StateDecimal) number.IsNegative = false;
+        //     }
+        //
+        // `StateNonZero` is set only inside .NET's `if (ch != '0' || StateNonZero)` block, so it
+        // means "a nonzero digit was seen" -- exactly this scan's `digitsCount != 0`, since a
+        // zero enters the buffer only once a nonzero digit has. TWO CONSEQUENCES, and both are
+        // easy to get wrong in opposite directions:
+        //
+        //   * an all-zero magnitude NEVER overflows, at ANY exponent, because the scale it would
+        //     have overflowed on is discarded first -- "0E30" and "0E100000000" are 0, not
+        //     OverflowException (ticket #2356, where the recorded premise was the reverse);
+        //   * the sign is dropped too, so `UInt32::Parse("-0")` is 0 -- but ONLY when no decimal
+        //     separator was seen, which is why `UInt32::Parse("-0.0")` still fails. That
+        //     asymmetry is .NET's, not this port's convenience.
+        if (scan.digitsCount == 0) {
+            scan.scale = 0;
+            if (!scan.sawDecimal) negative = false;
+        }
+
         // Format-grammar validity takes precedence over the scale overflow, matching real .NET's
         // own documented precedence rule -- checked only after the two lines above.
         if (!TryFoldScale(scan)) { overflowed = true; return true; }
@@ -431,6 +458,13 @@ struct IntegerNumberStylesParser {
         if (i < n && s[i] == '-') return false; // trailing minus: same rejection as leading
 
         if (i != n) return false;
+
+        // .NET's all-zero normalisation, the same transcription as the signed core above
+        // (`Number.Parsing.Common.cs:259-268`). Only the scale half applies here: a '-' never
+        // reaches this point on the unsigned path, which is this parser's own long-standing
+        // deviation and is documented on TryParseUnsignedCore.
+        if (scan.digitsCount == 0) scan.scale = 0;
+
         if (!TryFoldScale(scan)) { overflowed = true; return true; }
 
         result = static_cast<SharpRuntime::ulongcs>(scan.magnitude);

modules/core/tests/System/NumberStylesExtendedTests.cpp

@@ -424,23 +424,79 @@ TEST(IntegerAllowExponentTests, Fix2268_EveryIntegerWrapperGotTheFlagNotJustInt3
     EXPECT_EQ(10000000000000000000ull, UInt64::Parse("1E19", E, nullptr));
 }
 
-TEST(IntegerAllowExponentTests, Fix2268_TheAllZeroMagnitudeIsTheOneDeliberateDeviation) {
-    // Read literally, `Scale < DigitsCount` makes "0.0" an OverflowException in .NET: the
-    // fractional zero takes the `Scale--` branch and leaves scale -1 against a digits count of
-    // 0. This port keeps returning 0, because .NET's own suite pins no such row, the reading is
-    // an unexecutable source trace, and it is a narrowing SR-AUD-177 never asked for. Ticket
-    // #2356 holds the question; this test is what stops the answer changing by accident.
+TEST(IntegerAllowExponentTests, Fix2356_AnAllZeroMagnitudeNeverOverflowsAtAnyExponent) {
+    // #2356 RESOLVED, AND IT REVERSED THE RECORDED ANSWER TWICE.
+    //
+    // The deferred pin this replaces asserted that an all-zero magnitude with an absurd POSITIVE
+    // exponent overflows "exactly as .NET does". It does not. The pin's own comment named the
+    // reason it was wrong -- "the reading is an unexecutable source trace" -- and the missing
+    // line is `Number.Parsing.Common.cs:259-268`, which runs after the trailing-token loop:
+    //
+    //     if ((state & StateNonZero) == 0) {
+    //         if (number.Kind != NumberBufferKind.Decimal)                  number.Scale = 0;
+    //         if (number.Kind == NumberBufferKind.Integer && !StateDecimal) number.IsNegative = false;
+    //     }
+    //
+    // `StateNonZero` is set only inside `if (ch != '0' || StateNonZero)`, so an all-zero magnitude
+    // never sets it, and the scale it would have overflowed on IS DISCARDED BEFORE THE CHECK.
+    //
+    // A middle answer was considered and is also wrong: because a LEADING zero skips that same
+    // block, it does not advance the scale either, so the count of zeros written cannot matter.
+    // "0E-2" and "00E-2" must agree, and this test pins that they do.
+    for (const char* zero : {"0", "00", "000"}) {
+        SCOPED_TRACE(zero);
+        EXPECT_EQ(0, Int32::Parse(zero, NumberStyles::Any, nullptr));
+    }
+    for (const char* text : {"0E-1", "0E-2", "00E-2", "000E-9", "0E1", "0E30", "0E100000000",
+                             "0E-100000000", "0.0E-5"}) {
+        SCOPED_TRACE(text);
+        EXPECT_EQ(0, Int32::Parse(text, NumberStyles::Any, nullptr));
+        EXPECT_EQ(0u, UInt32::Parse(text, NumberStyles::Any, nullptr));
+    }
+
+    // The decimal-point rows the old pin defended are unchanged, and now for the RIGHT reason:
+    // not "this port declines a narrowing", but "this is what .NET computes".
     EXPECT_EQ(0, Int32::Parse("0.0", NumberStyles::Number, nullptr));
     EXPECT_EQ(0, Int32::Parse("000.000", NumberStyles::Number, nullptr));
-    EXPECT_EQ(0, Int32::Parse("0E-2", NumberStyles::AllowExponent, nullptr));
-    EXPECT_EQ(0, Int32::Parse("0E2", NumberStyles::AllowExponent, nullptr));
 
-    // The deviation is confined to a NON-POSITIVE scale. An all-zero magnitude with an absurd
-    // positive exponent still overflows, exactly as .NET does.
-    EXPECT_THROW((void)Int32::Parse("0E100000000", NumberStyles::AllowExponent, nullptr),
+    // The normalisation is confined to an ALL-ZERO magnitude. One nonzero digit anywhere and the
+    // ordinary scale rules apply again -- 6.5 is not an integer, and .NET's own Int32Tests.cs:548
+    // pins that as an OverflowException.
+    EXPECT_THROW((void)Int32::Parse("65E-1", NumberStyles::Any, nullptr), System::OverflowException);
+    EXPECT_THROW((void)Int32::Parse("1E100000000", NumberStyles::Any, nullptr),
                  System::OverflowException);
 }
 
+TEST(IntegerAllowExponentTests, Fix2356_TheSignIsDroppedToo_ButOnlyWithoutADecimalSeparator) {
+    // The normalisation's second half, which is easy to miss because it is guarded differently
+    // from the first: .NET clears IsNegative only for an Integer-kind buffer that saw NO decimal
+    // separator. So "-0" loses its sign and "-0.0" keeps it.
+    //
+    // HONEST LIMIT OF THESE ROWS. On the signed path both spellings are 0 either way, and on the
+    // unsigned path a '-' never gets this far, so THE `!sawDecimal` GUARD IS CURRENTLY
+    // UNOBSERVABLE: a mutation that drops it is not caught, by this suite or any other, and was
+    // measured not to be (#2356 mutation M2). It is kept because it is a faithful transcription
+    // of the reference line and becomes live the moment #2362 lets a '-' reach the unsigned
+    // buffer -- not because a test defends it. The rows below still pin the values themselves.
+    EXPECT_EQ(0, Int32::Parse("-0", NumberStyles::Any, nullptr));
+    EXPECT_EQ(0, Int32::Parse("-0.0", NumberStyles::Number, nullptr));
+    EXPECT_EQ(0, Int32::Parse("-0E-1", NumberStyles::Any, nullptr));
+
+    // .NET applies the normalisation AFTER its trailing-token loop, which is what makes it reach
+    // a TRAILING sign as well as a leading one. This port transcribes that position.
+    EXPECT_EQ(0, Int32::Parse("0-", NumberStyles::Any, nullptr));
+
+    // WHERE THIS PORT STILL DIVERGES, PINNED RATHER THAN QUIETLY FIXED. On the UNSIGNED path a
+    // '-' is rejected by the grammar before any of this runs, so UInt32::Parse("-0") is a
+    // FormatException where .NET returns 0. That is not a #2356 defect: it is the long-standing,
+    // deliberate deviation documented on TryParseUnsignedCore, which declines to reproduce
+    // .NET's negative-unsigned-throws-OverflowException quirk. Repairing the "-0" row alone
+    // would align one spelling and leave "-1" diverging, which is worse than a consistent rule.
+    // Ticket #2362 holds it.
+    EXPECT_THROW((void)UInt32::Parse("-0", NumberStyles::Any, nullptr), System::FormatException);
+    EXPECT_THROW((void)UInt32::Parse("-1", NumberStyles::Any, nullptr), System::FormatException);
+}
+
 TEST(IntegerAllowExponentTests, Fix2268_TheDecimalPointRowsAreUntouched) {
     // The scale model replaced a `fracNonZero` flag, so every pre-existing decimal-point answer
     // has to be reproduced by the new code rather than merely left alone.