feat(runtime): #1980 group G-1 -- OSPlatform default, RuntimeIdentifier, ExternalException ErrorCode

#1980's own acceptance criterion calls G-1 "purely ADDITIVE, closes three medium findings and
CANNOT BREAK A CONSUMER -- it is the recommended minimum", which makes it ordinary SA-5 work
rather than an approval. G-2..G-5 are untouched and #1980 stays blocked for them.

SR-AUD-152 -- OSPlatform has a reachable default. .NET's is a readonly struct, so
default(OSPlatform) has always been reachable and its Name is null; this port's only constructor
was PRIVATE, so the value had no spelling at all. The asymmetry with Create(""), which still
throws, is .NET's: the factory validates its argument, the default is the absence of one.

SR-AUD-153 -- the header's note was right about ONE of its two members.
  * FrameworkDescription: the note holds. It is GENERATED AT BUILD TIME as ".NET {version}"
    (ProductVersionInfoGenerator.cs:55) -- the .NET PRODUCT version. There is none here, so any
    string this port produced would be an invention. It stays absent, now with the citation.
  * RuntimeIdentifier: the note does not hold. It is not derived from the platform at all:
    RuntimeInformation.cs:20-21 is AppContext.GetData("RUNTIME_IDENTIFIER") as string ??
    "unknown" -- a lookup in a store this port has, with a literal fallback. Reproduced exactly.
    The `as string` is a TYPE TEST, not a coercion, the same rule AppContext's own
    APP_CONTEXT_BASE_DIRECTORY lookup follows (#2255); a blind cast is caught.

SR-AUD-159 -- ExternalException gains (message, errorCode) and ErrorCode. ERRORCODE NEEDS NO DATA
MEMBER, which corrects the finding's implication that it is separate state: .NET's is
`public virtual int ErrorCode => HResult;`, an ALIAS for the HResult this type already sets. So
sizeof is unchanged and no consumer rebuilds. It is non-virtual here because a virtual would add
a vtable slot, which SA-3 excludes. The new constructor sets HResult = errorCode rather than
E_FAIL, which is the whole point of the overload.

ToString() WAS IMPLEMENTED AND THEN REMOVED, ON THE DOWNSTREAM MEASUREMENT SA-2 CONDITION 5
REQUIRES. .NET's is "{GetType()} (0x{HResult:X8})" and GetType() is the MOST DERIVED type. It was
written with the name resolved statically at the site, exactly as #2323 did for Exception's
fallback message -- and cna derives from ExternalException in THREE types
(NoAudioHardwareException, InstancePlayLimitException, StorageDeviceNotConnectedException), every
one of which that name would have misnamed. #2323's own rule applies in its own words: a message
naming the wrong type is a lie, where an empty one is merely an absence. Both remaining routes
cost more than this ticket may spend -- a virtual is a vtable change (SA-3 excludes) and a stored
name is a data member on a class three downstream types derive from -- so it is #2387
(needs_user), and the absence is pinned by a static_assert naming it. The pin's `requires` takes
a DEPENDENT parameter, the #2299 gcc trap.

Mutations: 5, all caught. Two were invalid as first written and reformulated rather than counted:
removing the (message,errorCode) body leaves the parameter unused and -Werror rejects it, and the
OSPlatform mutation is caught BY COMPILATION -- the only way C++ reports a missing constructor.
ToString's own two mutations were caught before it was withdrawn (X8 padding, and appending an
empty message -- the latter only after a row was added, because every other case had a message);
that work is recorded in the note because #2387 starts from it.

Gate: 17,408 run, 17,408 passed, 0 failed, 0 skipped across 38 executables (+4, in
SharpRuntimeTests_Runtime, 170 -> 174). Module graph unchanged at 41/93; no sizeof, vtable or
signature change. Built in build/ with --parallel 2.
Downstream: cna uses ExternalException's EXISTING (message) and (message, inner) constructors at
its three derived types; both untouched, so nothing needs migrating. OSPlatform and
RuntimeInformation have zero consumer sites. Neither repository was modified.

docs/Migration-RuntimeG1AdditiveSurface.md

Author: robertvokac

CLAUDE.md

@@ -0,0 +1,98 @@
+<!-- SPDX-License-Identifier: MIT -->
+<!-- Copyright (c) Robert Vokac and contributors -->
+
+# Migration — `System::Runtime` group G-1: three additive members (ticket #1980)
+
+*2026-08-19.* #1980's own acceptance criterion calls G-1 *"purely **ADDITIVE**, closes three
+medium findings and **cannot break a consumer** — it is the recommended minimum"*, which makes it
+ordinary **SA-5** work rather than an approval. G-2 to G-5 are untouched and stay blocked.
+
+Nothing was removed, no signature changed, no `sizeof` moved, no vtable moved.
+
+---
+
+## 1. SR-AUD-152 — `OSPlatform` has a reachable default
+
+.NET's `OSPlatform` is a `readonly struct`, so `default(OSPlatform)` has always been reachable and
+its `Name` is null. This port's only constructor was **private**, so the value had no spelling at
+all. `OSPlatform() = default;` is now public.
+
+The asymmetry with `Create("")`, which still throws `ArgumentException`, is .NET's: the factory
+validates its argument, the default is the absence of one. Both are pinned so neither is tidied
+into the other.
+
+## 2. SR-AUD-153 — the note was right about one member and wrong about the other
+
+The header said `RuntimeIdentifier` and `FrameworkDescription` *"are not reproduced — there is no
+.NET runtime/assembly identity in a native C++ build for these to describe"*. Measured:
+
+* **`FrameworkDescription` — the note holds.** It is *generated at build time* as the literal
+  `".NET {version}"` (`ProductVersionInfoGenerator.cs:55`) — the .NET **product** version. There
+  is no such product here, so any string this port produced would be an invention. It stays
+  absent, and the note now says why with the citation.
+* **`RuntimeIdentifier` — the note does not hold.** It is not derived from the platform at all:
+  `RuntimeInformation.cs:20-21` is
+  `AppContext.GetData("RUNTIME_IDENTIFIER") as string ?? "unknown"` — a lookup in a store this
+  port has, with a literal fallback. It is reproduced exactly.
+
+The `as string` is a **type test, not a coercion**: an entry of another type falls through to
+`"unknown"` rather than being rendered, which is the same rule `AppContext`'s own
+`APP_CONTEXT_BASE_DIRECTORY` lookup follows (#2255). A mutation that casts blindly is caught.
+
+## 3. SR-AUD-159 — `ExternalException`, and one member deliberately not landed
+
+`ExternalException(message, errorCode)` and `getErrorCodeProperty()` landed.
+
+**`ErrorCode` needed no data member**, which corrects the finding's implication that it is separate
+state: .NET's is `public virtual int ErrorCode => HResult;` — an **alias** for the HResult this
+type already sets. So `sizeof` is unchanged and no consumer rebuilds. It is non-virtual here
+because a virtual would add a vtable slot, which SA-3 excludes.
+
+The new constructor sets `HResult = errorCode` rather than `E_FAIL`, which is the whole point of
+the overload existing; the other three keep `E_FAIL`.
+
+### `ToString()` was implemented and then removed, on the downstream measurement
+
+.NET's is `$"{GetType()} (0x{HResult:X8})"` plus the message and any inner exception, and
+`GetType()` is the **most derived** type — reflection this port permanently lacks. It was
+implemented with the name resolved statically at the site, exactly as **#2323** did for
+`Exception`'s fallback message, and then removed when SA-2's condition 5 was discharged:
+
+> **`cna` derives from `ExternalException` in three types** — `NoAudioHardwareException`,
+> `InstancePlayLimitException` and `StorageDeviceNotConnectedException` — every one of which a
+> static name would have misnamed.
+
+That is #2323's own rule in its own words: *a message naming the wrong type is a lie, where an
+empty one is merely an absence.* The two remaining routes both cost more than this ticket may
+spend — a virtual `ToString()` is a vtable change (SA-3 excludes), and a stored type name is a
+data member on a class three downstream types derive from. It is ticket **#2387**, and the absence
+is pinned by a `static_assert` naming it.
+
+The pin's `requires` takes a **dependent** parameter, because gcc evaluates a non-dependent one
+eagerly and hard-errors instead of yielding false (#2299).
+
+## 4. Evidence
+
+Five mutations, **all caught**:
+
+| Mutation | Caught by |
+|---|---|
+| the `(message, errorCode)` constructor ignores its argument | 2 cases |
+| `ToString`'s `X8` padding dropped | — *(removed with `ToString`)* |
+| `RuntimeIdentifier` casts blindly instead of type-testing | its own case |
+| the `OSPlatform` default constructor removed | **compilation** — the only way C++ reports a missing constructor |
+
+Two were invalid as first written and reformulated rather than counted: removing the
+`(message, errorCode)` body leaves the parameter unused and `-Werror` rejects it, and the
+`OSPlatform` mutation is caught as a build failure by construction.
+
+Before `ToString()` was withdrawn its two mutations were caught (the `%x`-instead-of-`%08X`
+padding, and appending an empty message) — and the empty-message one needed a row added, because
+every other case had a message. That work is recorded here because it is what #2387 will start
+from.
+
+## 5. Downstream, measured
+
+`cna` uses `ExternalException`'s **existing** `(message)` and `(message, inner)` constructors at
+its three derived types; both are untouched, so nothing needs migrating. `OSPlatform` and
+`RuntimeInformation` have zero consumer sites. Neither repository was modified.

docs/Migration-RuntimeG1AdditiveSurface.md

@@ -4,11 +4,21 @@
 #pragma once
 
 #include "System/SystemException.hpp"
+#include <cstdio>
 #include <string>
 
 namespace System::Runtime::InteropServices
 {
-    /** Base class for exceptions thrown by, or related to, external (unmanaged) code. */
+    /**
+     * @brief Base class for exceptions thrown by, or related to, external (unmanaged) code.
+     *
+     * @note <b>#1980 group G-1 (SR-AUD-159).</b> The `(message, errorCode)` constructor,
+     * `getErrorCodeProperty()` and `ToString()` were absent. `ErrorCode` needed <b>no data
+     * member</b>: .NET's is `public virtual int ErrorCode => HResult;` (`ExternalException.cs`),
+     * an alias for the HResult this type already sets, so `sizeof` is unchanged and no consumer
+     * rebuilds. The finding's implication that it is separate state does not survive the
+     * reference.
+     */
     class ExternalException : public System::SystemException
     {
     public:
@@ -27,6 +37,49 @@ namespace System::Runtime::InteropServices
             setHResultProperty(static_cast<SharpRuntime::intcs>(0x80004005u)); // E_FAIL
         }
 
+        /**
+         * @brief Creates an exception carrying a specific HRESULT.
+         *
+         * `ExternalException.cs`: `public ExternalException(string? message, int errorCode)`
+         * sets `HResult = errorCode` -- it does NOT default to E_FAIL, which is the whole point
+         * of the overload.
+         */
+        ExternalException(const std::string& message, SharpRuntime::intcs errorCode)
+            : System::SystemException(message) {
+            setHResultProperty(errorCode);
+        }
+
+        /**
+         * @brief The HRESULT of the error.
+         *
+         * .NET's is `public virtual int ErrorCode => HResult;` -- an alias, not a second field.
+         * It is non-virtual here because making it virtual would add a slot to this class's
+         * vtable, which `docs/StandingApprovals.md` SA-3 excludes; nothing in this repository
+         * derives from `ExternalException` (measured -- `Win32Exception` derives from
+         * `System::Exception` directly and says so at its own site), so no override is lost.
+         */
+        [[nodiscard]] SharpRuntime::intcs getErrorCodeProperty() const {
+            return getHResultProperty();
+        }
+
+        /**
+         * @note <b>`ToString()` is deliberately ABSENT, and #1980 measured why rather than
+         * assuming it.</b> .NET's is `$"{GetType()} (0x{HResult:X8})"` plus the message and any
+         * inner exception -- and `GetType()` is the MOST DERIVED type, which is reflection this
+         * port permanently lacks.
+         *
+         * It was implemented, with the type name resolved statically at this site as #2323 did
+         * for `Exception`'s fallback message, and then <b>removed on the downstream
+         * measurement</b> SA-2 condition 5 requires: `cna` derives from this class in
+         * <b>three</b> types -- `NoAudioHardwareException`, `InstancePlayLimitException` and
+         * `StorageDeviceNotConnectedException` -- every one of which the static name would have
+         * misnamed. That is exactly #2323's own rule, in its own words: <i>a message naming the
+         * wrong type is a lie, where an empty one is merely an absence.</i>
+         *
+         * The remaining routes both cost more than this ticket may spend: a virtual `ToString()`
+         * adds a slot to this class's vtable, which SA-3 excludes, and a stored type name is a
+         * data member on a class three downstream types derive from. Ticket <b>#2387</b>.
+         */
         ~ExternalException() override = default;
     };
 

modules/runtime/include/System/Runtime/InteropServices/ExternalException.hpp

@@ -27,6 +27,19 @@ namespace System::Runtime::InteropServices {
         }
 
     public:
+        /**
+         * @brief Creates the default OSPlatform, whose name is empty.
+         *
+         * #1980 group G-1 (SR-AUD-152). .NET's `OSPlatform` is a `readonly struct`, so
+         * `default(OSPlatform)` has always been reachable and its `Name` is null; this port's
+         * only constructor was private, so the value had no spelling at all.
+         *
+         * @note The asymmetry with `Create("")` is .NET's, not an oversight here: `Create` rejects
+         * an empty name with `ArgumentException` while the default value carries one. `Create` is
+         * a factory that validates its argument; the default is the absence of an argument.
+         */
+        OSPlatform() = default;
+
         /** @brief Creates a new OSPlatform instance. Consider caching the result if called frequently. */
         [[nodiscard]] static OSPlatform Create(const std::string& osPlatform) {
             if (osPlatform.empty()) {

modules/runtime/include/System/Runtime/InteropServices/OSPlatform.hpp

@@ -13,8 +13,19 @@ namespace System::Runtime::InteropServices {
      *
      * C++ counterpart of .NET System.Runtime.InteropServices.RuntimeInformation.
      *
-     * @note `RuntimeIdentifier`/`FrameworkDescription` are not reproduced — there is no .NET
-     * runtime/assembly identity in a native C++ build for these to describe.
+     * @note <b>#1980 group G-1 (SR-AUD-153) corrected this note, which was right about one of
+     * the two members and wrong about the other.</b> It said both "are not reproduced — there is
+     * no .NET runtime/assembly identity in a native C++ build for these to describe".
+     *
+     * That holds for <b>`FrameworkDescription`</b>, and the reference shows why: it is
+     * <i>generated at build time</i> as the literal `".NET {version}"`
+     * (`ProductVersionInfoGenerator.cs:55`), i.e. the .NET <i>product</i> version. There is no
+     * such product here, so any string this port produced would be an invention.
+     *
+     * It does <b>not</b> hold for `RuntimeIdentifier`, which is not derived from the platform at
+     * all: `RuntimeInformation.cs:20-21` is
+     * `AppContext.GetData("RUNTIME_IDENTIFIER") as string ?? "unknown"` — a lookup in a store
+     * this port has, with a literal fallback. It is reproduced exactly.
      */
     class RuntimeInformation {
     public:
@@ -23,6 +34,18 @@ namespace System::Runtime::InteropServices {
         /** @return A human-readable description of the operating system. */
         [[nodiscard]] static std::string getOSDescriptionProperty();
 
+        /**
+         * @return The platform on which the application is running, or `"unknown"`.
+         *
+         * `RuntimeInformation.cs:20-21`, transcribed:
+         * `AppContext.GetData("RUNTIME_IDENTIFIER") as string ?? "unknown"`.
+         *
+         * @note The `as string` matters and is reproduced: an entry of some other type falls
+         * through to `"unknown"` rather than being coerced, which is the same rule
+         * `AppContext`'s own `APP_CONTEXT_BASE_DIRECTORY` lookup follows (#2255).
+         */
+        [[nodiscard]] static std::string getRuntimeIdentifierProperty();
+
         /** @return true if the current platform matches @p osPlatform. */
         [[nodiscard]] static bool IsOSPlatform(const OSPlatform& osPlatform);
 

modules/runtime/include/System/Runtime/InteropServices/RuntimeInformation.hpp

@@ -2,6 +2,9 @@
 // Copyright (c) Robert Vokac and contributors
 // Portions based on .NET runtime API (MIT License, Copyright .NET Foundation and Contributors)
 #include "System/Runtime/InteropServices/RuntimeInformation.hpp"
+#include "System/AppContext.hpp"
+#include <any>
+#include <string>
 
 #if defined(_WIN32)
 #include <windows.h>
@@ -13,6 +16,16 @@
 
 namespace System::Runtime::InteropServices {
 
+std::string RuntimeInformation::getRuntimeIdentifierProperty() {
+    // RuntimeInformation.cs:20-21 -- AppContext.GetData("RUNTIME_IDENTIFIER") as string ?? "unknown".
+    // The `as string` is a TYPE TEST, not a coercion: an entry of another type falls through to
+    // the literal rather than being rendered, exactly as AppContext's own base-directory lookup
+    // does (#2255).
+    const std::any data = System::AppContext::GetData("RUNTIME_IDENTIFIER");
+    if (const auto* text = std::any_cast<std::string>(&data)) return *text;
+    return "unknown";
+}
+
 Architecture RuntimeInformation::getProcessArchitectureProperty() {
 #if defined(__x86_64__) || defined(_M_X64)
     return Architecture::X64;

modules/runtime/src/System/Runtime/InteropServices/RuntimeInformation.cpp

@@ -2,6 +2,7 @@
 // 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/AppContext.hpp"
 #include <vector>
 #include <algorithm>
 #include "System/ArgumentException.hpp"
@@ -119,3 +120,43 @@ TEST(RuntimeInformationTests, Fix1983_TheProcessArchitectureIsTheCompilationTarg
     SUCCEED() << "no assertion for this target; the #error guarantees the list covers it";
 #endif
 }
+
+// ===========================================================================
+// #1980 group G-1 -- SR-AUD-152 (OSPlatform default) and SR-AUD-153
+// (RuntimeIdentifier). The ticket calls G-1 "purely ADDITIVE ... cannot break a
+// consumer", which is what makes it ordinary SA-5 work rather than an approval.
+// ===========================================================================
+
+TEST(RuntimeInformationTests, Fix1980G1_OSPlatformHasAReachableDefault) {
+    // .NET's OSPlatform is a readonly struct, so default(OSPlatform) has always been reachable
+    // and its Name is null. This port's only constructor was private, so the value had no
+    // spelling at all.
+    OSPlatform def;
+    EXPECT_TRUE(def.ToString().empty());
+    EXPECT_TRUE(def == OSPlatform());
+
+    // The asymmetry with Create("") is .NET's: the factory validates its argument, the default
+    // is the absence of one. Both rows are asserted so neither can be "tidied" into the other.
+    EXPECT_THROW((void)OSPlatform::Create(""), System::ArgumentException);
+    EXPECT_FALSE(def == OSPlatform::Create("LINUX"));
+}
+
+TEST(RuntimeInformationTests, Fix1980G1_RuntimeIdentifierIsAnAppContextLookupWithALiteralFallback) {
+    // RuntimeInformation.cs:20-21 -- AppContext.GetData("RUNTIME_IDENTIFIER") as string ??
+    // "unknown". Nothing is derived from the platform, which is why this is reproducible at all.
+    EXPECT_EQ(RuntimeInformation::getRuntimeIdentifierProperty(), "unknown");
+
+    System::AppContext::SetData("RUNTIME_IDENTIFIER", std::string("linux-x64"));
+    EXPECT_EQ(RuntimeInformation::getRuntimeIdentifierProperty(), "linux-x64");
+
+    // `as string` is a TYPE TEST, not a coercion: a non-string entry falls through to the
+    // literal rather than being rendered. The row that fails if the lookup casts blindly.
+    System::AppContext::SetData("RUNTIME_IDENTIFIER", 42);
+    EXPECT_EQ(RuntimeInformation::getRuntimeIdentifierProperty(), "unknown");
+
+    System::AppContext::SetData("RUNTIME_IDENTIFIER", std::string());
+    EXPECT_EQ(RuntimeInformation::getRuntimeIdentifierProperty(), "")
+        << "an entry that IS a string is returned even when empty -- `as string` succeeds";
+
+    System::AppContext::SetData("RUNTIME_IDENTIFIER", std::string("unknown"));
+}

modules/runtime/tests/System/Runtime/InteropServices/RuntimeInformationTests.cpp

@@ -830,3 +830,43 @@ TEST(ConditionalWeakTableTests, ScalarKeys_StillExpireWhenTheLastOwnerDrops) {
     while (e->MoveNext()) ++enumerated;
     EXPECT_EQ(enumerated, 0) << "an expired scalar key was still enumerated";
 }
+
+// ===========================================================================
+// #1980 group G-1 -- SR-AUD-159. ExternalException's (message, errorCode)
+// constructor, ErrorCode and ToString.
+// ===========================================================================
+
+TEST(ExternalExceptionTests, Fix1980G1_ErrorCodeIsTheHResultAndNeedsNoField) {
+    // .NET's is `public virtual int ErrorCode => HResult;` -- an ALIAS, not separate state. The
+    // finding's implication that it is a second field does not survive the reference, and this
+    // row is what says so: setting one moves the other.
+    ExternalException withCode("boom", static_cast<SharpRuntime::intcs>(0x80070005));
+    EXPECT_EQ(withCode.getErrorCodeProperty(), static_cast<SharpRuntime::intcs>(0x80070005));
+    EXPECT_EQ(withCode.getHResultProperty(), withCode.getErrorCodeProperty());
+
+    // The other constructors keep E_FAIL, which is the whole point of the new overload existing.
+    EXPECT_EQ(ExternalException().getErrorCodeProperty(),
+              static_cast<SharpRuntime::intcs>(0x80004005));
+    EXPECT_EQ(ExternalException("m").getErrorCodeProperty(),
+              static_cast<SharpRuntime::intcs>(0x80004005));
+}
+
+// #1980 G-1 deliberately did NOT land ToString(), and this pins the absence so it cannot be
+// added without the decision. It was implemented and then removed on the downstream measurement:
+// cna derives from ExternalException in THREE types, and a statically resolved type name would
+// have misnamed every one -- #2323's own rule, that a message naming the wrong type is a lie
+// where an empty one is merely an absence. Ticket #2387.
+//
+// The parameter is DEPENDENT because gcc evaluates a non-dependent `requires` eagerly and
+// hard-errors instead of yielding false (#2299, recorded in CLAUDE.md).
+template <typename T> concept HasToString = requires(const T& e) { e.ToString(); };
+
+TEST(ExternalExceptionTests, Decl1980G1_ToStringIsAbsentUntilItsTypeNameQuestionIsAnswered) {
+    static_assert(!HasToString<ExternalException>,
+                  "#2387: ToString() landed without resolving the derived-type name -- three cna "
+                  "types derive from this class and a static name misnames all of them.");
+    // The two members that DID land are unaffected and stay reachable.
+    ExternalException ex("boom", static_cast<SharpRuntime::intcs>(0x80070005));
+    EXPECT_EQ(ex.getErrorCodeProperty(), static_cast<SharpRuntime::intcs>(0x80070005));
+    SUCCEED();
+}