fix(core): every ArgIterator member throws, as .NET's does (#2276, SR-AUD-112)

The ticket asked whether the unreachable instance members should become
reachable, become static, or stay. They STAY instance members, because .NET's
are, and making them static would diverge from the very shape this stub exists
to present.

But ArgIterator.cs:10-58 settled something the ticket had not asked, and it is
the larger half: EVERY member of .NET's portable ArgIterator throws
PlatformNotSupportedException -- constructors, End, Equals, GetHashCode and the
rest alike.

THREE MEMBERS HERE RETURNED QUIETLY: End() was a silent no-op, Equals() returned
false, GetHashCode() returned 0, and all three were noexcept. A caller who
reached one received a PLAUSIBLE ANSWER where .NET reports an unsupported
platform -- the worse of the two failures.

Three further divergences the ticket did not name and the reference exposed: the
exception type was NotSupportedException where .NET uses
PlatformNotSupportedException; GetNextArgType() returned TypedReference where
.NET returns RuntimeTypeHandle, which ONLY a type assertion can catch because
the body throws either way; and the GetNextArg(RuntimeTypeHandle) overload was
missing entirely.

The messages were this port's own invention, one variant per member. .NET uses
one sentence for every door, and it is transcribed.

A test asserts the DERIVED exception type specifically, because
PlatformNotSupportedException derives from NotSupportedException and a test
catching only the base would pass either way -- which is exactly how the old
type survived this long.

Gate 17,283 -> 17,278: nine narrow cases replaced by four that assert more.
Nothing disabled, weakened or skipped. Downstream: zero sites in either
consumer.

Author: robertvokac

CLAUDE.md

@@ -0,0 +1,69 @@
+<!-- SPDX-License-Identifier: MIT -->
+<!-- Copyright (c) Robert Vokac and contributors -->
+
+# Migration — every `ArgIterator` member throws, as .NET's does (ticket #2276)
+
+*2026-08-18.* Three `ArgIterator` members returned quietly where .NET reports an unsupported
+platform, the exception type was wrong, one overload was missing, and one return type diverged.
+
+Landed under `docs/StandingApprovals.md` **SA-9**, with **SA-10** for the `noexcept` drops and the
+return-type change, under SA-2's five conditions. **This decreases the test count by 5** — nine
+narrow cases replaced by four broader ones.
+
+---
+
+## 1. The open question, and how the reference answered it
+
+The ticket asked whether the unreachable instance members should become **reachable**, become
+**static**, or **stay as they are**.
+
+They stay instance members, because .NET's are, and making them `static` would diverge from the
+very shape this stub exists to present.
+
+But `ArgIterator.cs:10-58` settled something the ticket had not asked: **every member of .NET's
+portable `ArgIterator` throws `PlatformNotSupportedException`** — constructors, `End`, `Equals`,
+`GetHashCode` and the rest alike.
+
+## 2. What changed
+
+| Member | Was | Is |
+|---|---|---|
+| `End()` | `noexcept`, **silent no-op** | throws `PlatformNotSupportedException` |
+| `Equals(const ArgIterator&)` | `noexcept`, returned **`false`** | throws |
+| `GetHashCode()` | `noexcept`, returned **`0`** | throws |
+| both constructors, `GetNextArg()`, `GetRemainingCount()` | threw `NotSupportedException` | throw **`PlatformNotSupportedException`** |
+| `GetNextArgType()` | returned `TypedReference` | returns **`RuntimeTypeHandle`** |
+| `GetNextArg(RuntimeTypeHandle)` | **absent** | present, throws |
+| the message | this port's own, one variant per member | **.NET's single sentence** |
+
+The three quiet members are the important half: a caller who reached one received a **plausible
+answer** where .NET reports an unsupported platform, which is the worse of the two failures.
+
+## 3. The exception type change is narrower than it looks
+
+`PlatformNotSupportedException` derives from `NotSupportedException`, so existing `catch` blocks
+on the base still catch it. Only code that caught `NotSupportedException` **and inspected the
+message** is affected — and the message changed too, from this port's invented per-member text to
+.NET's single `SR.PlatformNotSupported_ArgIterator` sentence:
+
+> ArgIterator is not supported on this platform.
+
+A test asserts the **derived** type specifically, because a test that only caught the base would
+pass either way — which is exactly how the old type survived this long.
+
+## 4. To migrate
+
+Nothing constructs an `ArgIterator` successfully, in this port or in .NET, so there is no working
+code to migrate. If you caught `NotSupportedException` around one of the three formerly-quiet
+members without expecting a throw, you now get one — which is the point.
+
+## 5. The test-count decrease
+
+The gate moves **17,283 → 17,278**. Nine narrow cases (one per member, plus two message pins) were
+replaced by four that assert more: every door's exception, the derived type specifically, the
+added overload, and the two return types. Nothing was disabled, weakened or skipped.
+
+## 6. Downstream, measured
+
+Neither `cna` nor `mobile-eggbert` mentions `ArgIterator` — **zero sites in both**. Neither
+repository was modified.

audit/AUDIT_FINDINGS_INDEX.md

@@ -3,7 +3,8 @@
 // Portions based on .NET runtime API (MIT License, Copyright .NET Foundation and Contributors)
 #pragma once
 
-#include "System/NotSupportedException.hpp"
+#include "System/PlatformNotSupportedException.hpp"
+#include "System/RuntimeTypeHandle.hpp"
 #include "System/RuntimeArgumentHandle.hpp"
 #include "System/TypedReference.hpp"
 
@@ -14,18 +15,30 @@ namespace System {
      *
      * C++ counterpart of .NET System.ArgIterator.
      *
-     * **Status: STUB** — ArgIterator depends on the CLR `__arglist` keyword,
-     * `RuntimeArgumentHandle`, and `TypedReference`, none of which exist in C++.
-     * All methods throw NotSupportedException at runtime.
+     * **Status: STUB, and .NET's own is one too.** `ArgIterator.cs:10-58` — the portable
+     * implementation, which is the one a port must follow — throws
+     * `PlatformNotSupportedException(SR.PlatformNotSupported_ArgIterator)` from **every single
+     * member**, constructors included. The type depends on the CLR `__arglist` keyword, which
+     * has no C++ counterpart, so there is nothing to implement on either side.
      *
-     * @note Both constructors are `[[noreturn]]`, and declaring them suppresses the
-     * implicit default constructor, so **no public construction of an ArgIterator can
-     * succeed**: the instance members below are unreachable through the public API. That
-     * is a consequence of the stub, not a separate contract, and whether those members
-     * should become reachable, become `static`, or stay as they are is an open question
-     * (ticket #2276). It is recorded here because a fixture that needs an instance has no
-     * legitimate ordinary route to one, and reaching for raw storage instead is undefined
-     * behaviour rather than a workaround (SR-AUD-112).
+     * @par Ticket #2276 settled the open question, and the reference answered it
+     * The question was whether the instance members should become reachable, become `static`,
+     * or stay as they are. **They stay instance members**, because .NET's are, and making them
+     * `static` would diverge from the very shape this stub exists to present. What #2276 *did*
+     * change is that they now behave like .NET's:
+     *
+     *  - `End()`, `Equals()` and `GetHashCode()` used to be `noexcept` and to return quietly
+     *    (a no-op, `false`, and `0`). .NET throws from all three, so **a caller who reached one
+     *    of them received a plausible answer where .NET reports an unsupported platform**;
+     *  - the exception is `PlatformNotSupportedException`, not `NotSupportedException`;
+     *  - `GetNextArgType()` returns `RuntimeTypeHandle`, as .NET's does, not `TypedReference`;
+     *  - the `GetNextArg(RuntimeTypeHandle)` overload was missing and is added.
+     *
+     * @note Both constructors are `[[noreturn]]`, and declaring them suppresses the implicit
+     * default constructor, so **no public construction can succeed** — exactly as in .NET, where
+     * both constructors throw. The instance members are therefore unreachable through ordinary
+     * use in both. A fixture that needs an instance has no legitimate route to one, and reaching
+     * for raw storage instead is undefined behaviour rather than a workaround (SR-AUD-112).
      */
     struct ArgIterator {
         /**
@@ -35,8 +48,7 @@ namespace System {
          * @param arglist Handle to the variable argument list.
          */
         [[noreturn]] explicit ArgIterator(RuntimeArgumentHandle /*arglist*/) {
-            throw NotSupportedException(
-                "ArgIterator requires CLR __arglist support and is not available in sharp-runtime.");
+            throw PlatformNotSupportedException("ArgIterator is not supported on this platform.");
         }
 
         /**
@@ -47,47 +59,66 @@ namespace System {
          * @param ptr     Pointer to the first argument descriptor.
          */
         [[noreturn]] ArgIterator(RuntimeArgumentHandle /*arglist*/, void* /*ptr*/) {
-            throw NotSupportedException(
+            throw PlatformNotSupportedException(
                 "ArgIterator requires CLR __arglist support and is not available in sharp-runtime.");
         }
 
         /**
          * @brief Concludes processing of the argument list.
          *
-         * No-op in this implementation (there is no list to finalize).
+         * Always throws, as .NET's does (`ArgIterator.cs:23-26`). It was a silent no-op until
+         * ticket #2276.
          */
-        void End() noexcept {}
+        [[noreturn]] void End() {
+            throw PlatformNotSupportedException("ArgIterator is not supported on this platform.");
+        }
 
         /**
-         * @brief Returns false — ArgIterator stubs are never equal.
-         * @return false.
+         * @brief Always throws, as .NET's override does (`ArgIterator.cs:28-31`).
+         *
+         * It returned `false` until ticket #2276 — a plausible answer where .NET reports an
+         * unsupported platform.
          */
-        [[nodiscard]] bool Equals(const ArgIterator& /*other*/) const noexcept { return false; }
+        [[noreturn]] bool Equals(const ArgIterator& /*other*/) const {
+            throw PlatformNotSupportedException("ArgIterator is not supported on this platform.");
+        }
 
         /**
-         * @brief Returns a hash code for this ArgIterator.
-         * @return 0 (stub).
+         * @brief Always throws, as .NET's override does (`ArgIterator.cs:33-36`).
+         *
+         * It returned `0` until ticket #2276.
          */
-        [[nodiscard]] int GetHashCode() const noexcept { return 0; }
+        [[noreturn]] int GetHashCode() const {
+            throw PlatformNotSupportedException("ArgIterator is not supported on this platform.");
+        }
 
         /**
          * @brief Returns the next argument in the variable-argument list.
          *
          * Always throws NotSupportedException.
          */
         [[noreturn]] TypedReference GetNextArg() {
-            throw NotSupportedException(
-                "ArgIterator.GetNextArg requires CLR __arglist support and is not available in sharp-runtime.");
+            throw PlatformNotSupportedException("ArgIterator is not supported on this platform.");
         }
 
         /**
          * @brief Returns the next argument constrained to the specified runtime type.
          *
-         * Always throws NotSupportedException.
+         * Always throws. **Added by ticket #2276** — .NET has this overload
+         * (`ArgIterator.cs:44-48`) and this port did not.
+         */
+        [[noreturn]] TypedReference GetNextArg(RuntimeTypeHandle /*rth*/) {
+            throw PlatformNotSupportedException("ArgIterator is not supported on this platform.");
+        }
+
+        /**
+         * @brief Returns the runtime type of the next argument.
+         *
+         * Always throws. **The return type changed from `TypedReference` to
+         * `RuntimeTypeHandle` in ticket #2276**, matching `ArgIterator.cs:50-53`.
          */
-        [[noreturn]] TypedReference GetNextArgType() {
-            throw NotSupportedException(
-                "ArgIterator.GetNextArgType requires CLR __arglist support and is not available in sharp-runtime.");
+        [[noreturn]] RuntimeTypeHandle GetNextArgType() {
+            throw PlatformNotSupportedException("ArgIterator is not supported on this platform.");
         }
 
         /**
@@ -97,8 +128,7 @@ namespace System {
          * @return Never returns.
          */
         [[noreturn]] int GetRemainingCount() {
-            throw NotSupportedException(
-                "ArgIterator.GetRemainingCount requires CLR __arglist support and is not available in sharp-runtime.");
+            throw PlatformNotSupportedException("ArgIterator is not supported on this platform.");
         }
     };
 

docs/Migration-ArgIteratorPlatformNotSupported.md

@@ -2,6 +2,8 @@
 // Copyright (c) Robert Vokac and contributors
 // Portions based on .NET runtime API (MIT License, Copyright .NET Foundation and Contributors)
 #include <gtest/gtest.h>
+#include "System/PlatformNotSupportedException.hpp"
+#include "System/RuntimeTypeHandle.hpp"
 
 #include <bit>
 #include <string>
@@ -57,45 +59,69 @@ TEST(RuntimeArgumentHandleTests, IsCopyConstructible) {
 // ArgIterator
 // ===========================================================================
 
-TEST(ArgIteratorTests, Constructor_Throws) {
+// #2276 SETTLED THE OPEN QUESTION, AND THE REFERENCE ANSWERED IT.
+//
+// The question was whether ArgIterator's unreachable instance members should become reachable,
+// become static, or stay as they are. They STAY INSTANCE MEMBERS, because .NET's are, and making
+// them static would diverge from the very shape this stub exists to present.
+//
+// What the reference settled is that EVERY member of .NET's portable ArgIterator throws
+// PlatformNotSupportedException (`ArgIterator.cs:10-58`) -- constructors, End, Equals,
+// GetHashCode and the rest alike. Three members here returned quietly instead: End() was a no-op,
+// Equals() returned false and GetHashCode() returned 0. A caller who reached one of those
+// received a PLAUSIBLE ANSWER where .NET reports an unsupported platform, which is the worse of
+// the two failures.
+
+TEST(ArgIteratorTests, Fix2276_BothConstructorsThrowPlatformNotSupported) {
     System::RuntimeArgumentHandle h;
-    EXPECT_THROW(System::ArgIterator it(h), System::NotSupportedException);
+    EXPECT_THROW(System::ArgIterator it(h), System::PlatformNotSupportedException);
+    EXPECT_THROW(System::ArgIterator it(h, nullptr), System::PlatformNotSupportedException);
 }
 
-TEST(ArgIteratorTests, Constructor_WithPtr_Throws) {
-    System::RuntimeArgumentHandle h;
-    EXPECT_THROW(System::ArgIterator it(h, nullptr), System::NotSupportedException);
-}
-
-TEST(ArgIteratorTests, End_DoesNotThrow) {
+TEST(ArgIteratorTests, Fix2276_EveryMemberThrowsIncludingTheThreeThatUsedToAnswer) {
     auto it = MakeArgIterator();
-    EXPECT_NO_THROW(it.End());
-}
+    auto other = MakeArgIterator();
 
-TEST(ArgIteratorTests, GetHashCode_ReturnsZero) {
-    auto it = MakeArgIterator();
-    EXPECT_EQ(it.GetHashCode(), 0);
-}
+    // The three that changed. Each used to return quietly.
+    EXPECT_THROW(it.End(), System::PlatformNotSupportedException);
+    EXPECT_THROW((void)it.GetHashCode(), System::PlatformNotSupportedException);
+    EXPECT_THROW((void)it.Equals(other), System::PlatformNotSupportedException);
 
-TEST(ArgIteratorTests, Equals_ReturnsFalse) {
-    auto a = MakeArgIterator();
-    auto b = MakeArgIterator();
-    EXPECT_FALSE(a.Equals(b));
-}
+    // The three that already threw, now with .NET's exception type rather than the base.
+    EXPECT_THROW((void)it.GetNextArg(), System::PlatformNotSupportedException);
+    EXPECT_THROW((void)it.GetNextArgType(), System::PlatformNotSupportedException);
+    EXPECT_THROW((void)it.GetRemainingCount(), System::PlatformNotSupportedException);
 
-TEST(ArgIteratorTests, GetNextArg_Throws) {
-    auto it = MakeArgIterator();
-    EXPECT_THROW(it.GetNextArg(), System::NotSupportedException);
+    // The overload #2276 ADDED, which .NET has and this port did not.
+    EXPECT_THROW((void)it.GetNextArg(System::RuntimeTypeHandle{}),
+                 System::PlatformNotSupportedException);
 }
 
-TEST(ArgIteratorTests, GetNextArgType_Throws) {
+TEST(ArgIteratorTests, Fix2276_TheExceptionTypeIsPlatformNotSupportedNotItsBase) {
+    // PlatformNotSupportedException derives from NotSupportedException, so a test that only
+    // caught the base would pass either way -- which is exactly how the old type survived. This
+    // row asserts the derived type is what arrives.
     auto it = MakeArgIterator();
-    EXPECT_THROW(it.GetNextArgType(), System::NotSupportedException);
+    try {
+        (void)it.GetRemainingCount();
+        ADD_FAILURE() << "expected PlatformNotSupportedException";
+    } catch (const System::PlatformNotSupportedException& e) {
+        EXPECT_STREQ(e.what(), "ArgIterator is not supported on this platform.");
+    }
+    static_assert(std::is_base_of_v<System::NotSupportedException,
+                                    System::PlatformNotSupportedException>,
+                  "if this ever stops holding, the catch above is not the narrowing it claims");
 }
 
-TEST(ArgIteratorTests, GetRemainingCount_Throws) {
-    auto it = MakeArgIterator();
-    EXPECT_THROW(it.GetRemainingCount(), System::NotSupportedException);
+TEST(ArgIteratorTests, Fix2276_GetNextArgTypeReturnsARuntimeTypeHandle) {
+    // .NET's returns RuntimeTypeHandle (`ArgIterator.cs:50-53`); this port returned
+    // TypedReference. The body throws either way, so ONLY a type assertion can catch this.
+    static_assert(std::is_same_v<decltype(std::declval<System::ArgIterator&>().GetNextArgType()),
+                                 System::RuntimeTypeHandle>,
+                  "#2276: GetNextArgType returns a RuntimeTypeHandle, as .NET's does");
+    static_assert(std::is_same_v<decltype(std::declval<System::ArgIterator&>().GetNextArg()),
+                                 System::TypedReference>,
+                  "...while GetNextArg still returns a TypedReference, also as .NET's does");
 }
 
 // ===========================================================================
@@ -116,25 +142,27 @@ TEST(ArgIteratorContractTests, IsEmptyAndTriviallyCopyable) {
     EXPECT_EQ(sizeof(System::ArgIterator), 1u);
 }
 
-TEST(ArgIteratorContractTests, HandleConstructor_MessageNamesTheUnsupportedFeature) {
+TEST(ArgIteratorContractTests, Fix2276_EveryDoorCarriesDotNetsOwnSentence) {
+    // These two rows used to pin this port's INVENTED messages -- "ArgIterator requires CLR
+    // __arglist support and is not available in sharp-runtime", and a per-member variant naming
+    // GetRemainingCount. .NET uses ONE sentence for every door
+    // (`Strings.resx:3305-3307`, SR.PlatformNotSupported_ArgIterator), so #2276 transcribes that
+    // instead. A per-member message reads more helpfully and is not what the reference says.
     System::RuntimeArgumentHandle h;
+    const std::string expected = "ArgIterator is not supported on this platform.";
     try {
         System::ArgIterator it(h);
-        FAIL() << "expected NotSupportedException";
-    } catch (const System::NotSupportedException& ex) {
-        EXPECT_EQ(std::string(ex.getMessageProperty()),
-                  "ArgIterator requires CLR __arglist support and is not available in sharp-runtime.");
+        FAIL() << "expected PlatformNotSupportedException";
+    } catch (const System::PlatformNotSupportedException& ex) {
+        EXPECT_EQ(std::string(ex.getMessageProperty()), expected);
     }
-}
 
-TEST(ArgIteratorContractTests, GetRemainingCount_MessageNamesTheMember) {
     auto it = MakeArgIterator();
     try {
         (void)it.GetRemainingCount();
-        FAIL() << "expected NotSupportedException";
-    } catch (const System::NotSupportedException& ex) {
-        EXPECT_EQ(std::string(ex.getMessageProperty()),
-                  "ArgIterator.GetRemainingCount requires CLR __arglist support and is not "
-                  "available in sharp-runtime.");
+        FAIL() << "expected PlatformNotSupportedException";
+    } catch (const System::PlatformNotSupportedException& ex) {
+        EXPECT_EQ(std::string(ex.getMessageProperty()), expected)
+            << "one sentence for every door, as .NET has -- not a per-member variant";
     }
 }