fix(uri): UriTypeConverter::ConvertFrom returns std::optional<Uri> (#1999)

Rule-14 sweep. The by-value Uri return type cannot express .NET's null, so
ConvertFrom("") forwarded the empty string straight to the Uri constructor
and threw where .NET returns null (UriTypeConverter.cs:40-51).

The recorded gate and the recorded cost are both corrected. Section 14.5
wrote an approval sentence because this is "a vtable-slot signature change";
SA-10, granted after that record, names RETURN TYPE explicitly and routes it
through SA-2's five conditions -- SA-3's exclusion is a change to the vtable's
SHAPE, not a signature within an existing slot. And the record's "mandatory
migration for every override" is measurably zero: there are no overrides and
no derivations anywhere, in-tree or downstream, so the migration was four
test call sites.

The widening is exactly one input wide, and that is .NET's own boundary --
its comment says the malformed case is left to the constructor. A separate
pin asserts it, because "return the empty state on any failure" is the
plausible over-correction.

The kind is now spelled RelativeOrAbsolute, matching the reference. It is
behaviourally identical to the one-argument Uri(text) this used to call, so
the change is documentation rather than behaviour, and the note says so.

Four mutations, all caught. M4 only after a case was added: every test
converted an absolute URI, so requiring UriKind::Absolute never failed -- a
relative input is the only one the kind discriminates, which is exactly why
.NET passes RelativeOrAbsolute. M2 was invalid as first written
(-Werror=unused-parameter) and was reformulated rather than counted.

Fixture set 43/223 -> 44/226. Site 3's diagnostic is "invalid covariant
return type" rather than the "does not override" predicted, and it is the
more precise of the two.

Downstream measured: 0 sites in cna, 0 in mobile-eggbert.

Gate: 17,517 run, 17,517 passed, 0 failed, 0 skipped across 38 executables
(+2 on 17,515; SharpRuntimeTests_Uri 287 -> 289; no other executable moved).
Module graph unchanged at 41/93.

Author: robertvokac

CLAUDE.md

@@ -0,0 +1,111 @@
+<!-- SPDX-License-Identifier: MIT -->
+<!-- Copyright (c) Robert Vokac and contributors -->
+
+# Migration — `UriTypeConverter::ConvertFrom` returns `std::optional<Uri>` (ticket #1999)
+
+*2026-08-19.* `System::UriTypeConverter::ConvertFrom` returns `std::optional<Uri>` instead of
+`Uri`, so an **empty** input returns the empty state rather than throwing.
+
+**This is a public virtual signature change**, landed under **SA-10** with SA-2's five conditions
+discharged.
+
+---
+
+## 1. What was wrong
+
+The return type was a by-value `Uri`, which **cannot express .NET's `null`**. So an empty string
+was forwarded straight to the `Uri` constructor and threw `UriFormatException`. .NET
+short-circuits it:
+
+```csharp
+if (value is string uriString)
+{
+    if (string.IsNullOrEmpty(uriString))
+    {
+        return null;
+    }
+
+    // Let the Uri constructor throw any informative exceptions
+    return new Uri(uriString, UriKind.RelativeOrAbsolute);
+}                                                     // UriTypeConverter.cs:40-51
+```
+
+## 2. The widening is exactly one input wide
+
+.NET's own comment — *"Let the Uri constructor throw any informative exceptions"* — says the empty
+case is the **only** one it short-circuits. A malformed string still throws.
+
+That boundary is pinned by its own test, because "return the empty state on any failure" is the
+plausible over-correction, and it is mutation M3.
+
+## 3. Why SA-10 and not an approval
+
+The design record (`docs/SystemUriNamespaceReviewPlan.md` §14.5) called this *"a vtable-slot
+signature change, plus mandatory migration for every override"* and wrote an approval sentence.
+Two things have changed since:
+
+* **SA-10 was granted afterwards**, and its list names **"return type"** explicitly, routing such
+  a change through SA-2's five conditions rather than a fresh ask. SA-3's exclusion is a change to
+  the vtable's **shape** — adding or removing a virtual, or changing the base class — not a
+  signature within an existing slot.
+* **The migration cost is measurably zero.** There are **no overrides and no derivations** of
+  `UriTypeConverter` anywhere: not in `modules/`, not in `test/` or `tests/`, and not in either
+  downstream consumer. The only call sites were four in this repository's own tests.
+
+What a *future* override would lose is pinned as site 3 of the negative fixture.
+
+## 4. To migrate
+
+```cpp
+Uri uri = converter.ConvertFrom(text);              // was
+auto uri = converter.ConvertFrom(text);             // now
+if (uri) { /* … uri->getHostProperty() … */ }
+```
+
+An empty `text` no longer throws — it yields an empty optional.
+
+## 5. One detail made explicit rather than changed
+
+The kind is now spelled `UriKind::RelativeOrAbsolute`, matching the reference. It is
+**behaviourally identical** to the one-argument `Uri(text)` this used to call: with that kind, both
+guards in `Uri(string, UriKind)` are inert and it simply parses. The change is documentation, not
+behaviour — stated so a reader does not look for an effect that is not there.
+
+## 6. Evidence
+
+Four mutations, **all caught**:
+
+| Mutation | Caught by |
+|---|---|
+| M1 — the empty input is no longer short-circuited | `Fix1999_ConvertFromEmptyReturnsTheEmptyStateInsteadOfThrowing` |
+| M2 — every input returns the empty state | four cases |
+| M3 — a *malformed* input is short-circuited too | `Decl1999_OnlyTheEmptyInputIsShortCircuited` |
+| M4 — the kind becomes `Absolute` | `Fix1999_ARelativeUriIsAccepted` — **only after that case was added** |
+
+**M3** is the plausible over-correction — "return the empty state on any failure" — and the reason
+§2's boundary has a test of its own.
+
+**M4 is the one worth recording.** It went **uncaught** at first: every case converted an
+*absolute* URI, so requiring `UriKind::Absolute` never failed. A relative input is the only one
+the kind discriminates, which is precisely why .NET passes `RelativeOrAbsolute` — and the new case
+also shows the relative URI round-trips, which is why `ConvertTo` uses `OriginalString`.
+
+M2 was invalid as first written — it left `text` unused and `-Werror=unused-parameter` rejected it
+— and was reformulated rather than counted.
+
+Negative consumer fixture: `test/consumer/uri_typeconverter_optional_negative.cpp`, three sites,
+all rejected. Fixture set grows to **44 fixtures / 226 sites**. Site 2 is the spelling most likely
+to survive a careless migration — calling straight through the result, which used to be a `Uri`.
+
+Site 3's diagnostic is **"invalid covariant return type"** rather than the "does not override" I
+predicted, and it is the more precise of the two: gcc reads the old signature as an *attempted
+covariant override* of the new one and rejects it on the spot, naming the reason.
+
+Gate: **17,517 run, 17,517 passed, 0 failed, 0 skipped** across 38 executables — `+2` on 17,515
+(`SharpRuntimeTests_Uri` 287 → 289; one pin inverted in place, two cases added). No other
+executable moved. Module graph unchanged at 41/93.
+
+## 7. Downstream, measured
+
+`UriTypeConverter` appears in **zero** places in `cna` and **zero** in `mobile-eggbert`. Neither
+repository was modified, and no downstream ticket is needed.

docs/Migration-UriTypeConverterOptional.md

@@ -2,6 +2,7 @@
 // Copyright (c) Robert Vokac and contributors
 // Portions based on .NET runtime API (MIT License, Copyright .NET Foundation and Contributors)
 #pragma once
+#include <optional>
 #include <string>
 #include "System/Uri.hpp"
 
@@ -42,13 +43,39 @@ namespace System {
         /**
          * @brief Converts a string to a Uri.
          *
-         * C++ counterpart of .NET UriTypeConverter.ConvertFrom(ITypeDescriptorContext, CultureInfo, object).
+         * C++ counterpart of .NET UriTypeConverter.ConvertFrom(ITypeDescriptorContext,
+         * CultureInfo, object).
+         *
          * @param text The string representation of a URI.
-         * @return A Uri constructed from @p text.
-         * @throws System::UriFormatException if @p text is empty or malformed.
+         * @return A Uri constructed from @p text, or **`std::nullopt` when @p text is empty**.
+         * @throws System::UriFormatException if @p text is malformed.
+         *
+         * Ticket #1999 / SR-AUD-148 (U-I). The return type was a by-value `Uri`, which **cannot
+         * express .NET's `null`**, so an empty string was forwarded straight to the `Uri`
+         * constructor and threw `UriFormatException`. .NET returns null:
+         * @code
+         * if (value is string uriString)
+         * {
+         *     if (string.IsNullOrEmpty(uriString))
+         *     {
+         *         return null;
+         *     }
+         *     // Let the Uri constructor throw any informative exceptions
+         *     return new Uri(uriString, UriKind.RelativeOrAbsolute);
+         * }                                       // UriTypeConverter.cs:40-51
+         * @endcode
+         * The empty case is the ONLY one .NET short-circuits -- its comment says outright that a
+         * malformed string is left to the constructor -- so `std::optional` widens exactly one
+         * input and nothing else.
+         *
+         * @note The kind is spelled **explicitly** as `RelativeOrAbsolute`, matching the
+         * reference. It is behaviourally identical to the one-argument `Uri(text)` this used to
+         * call -- with that kind the two guards in `Uri(string, UriKind)` are both inert -- so
+         * the change is documentation rather than behaviour.
          */
-        [[nodiscard]] virtual Uri ConvertFrom(const std::string& text) const {
-            return Uri(text);
+        [[nodiscard]] virtual std::optional<Uri> ConvertFrom(const std::string& text) const {
+            if (text.empty()) return std::nullopt;
+            return Uri(text, UriKind::RelativeOrAbsolute);
         }
 
         /**

modules/uri/include/System/UriTypeConverter.hpp

@@ -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 <optional>
 #include "System/UriFormatException.hpp"
 #include "System/UriTypeConverter.hpp"
 
@@ -19,14 +20,44 @@ TEST(UriTypeConverterTest, CanConvertTo) {
 }
 
 TEST(UriTypeConverterTest, ConvertFromString) {
+    // MIGRATED by #1999: ConvertFrom returns std::optional<Uri>, because a by-value Uri cannot
+    // express .NET's null.
     UriTypeConverter c;
-    Uri uri = c.ConvertFrom("http://example.com");
-    EXPECT_EQ(uri.getHostProperty(), "example.com");
+    auto uri = c.ConvertFrom("http://example.com");
+    ASSERT_TRUE(uri.has_value());
+    EXPECT_EQ(uri->getHostProperty(), "example.com");
 }
 
-TEST(UriTypeConverterTest, ConvertFromEmptyThrows) {
+TEST(UriTypeConverterTest, Fix1999_ConvertFromEmptyReturnsTheEmptyStateInsteadOfThrowing) {
+    // INVERTED by #1999 / SR-AUD-148. This asserted the divergence: an empty string was forwarded
+    // straight to the Uri constructor and threw. .NET short-circuits it and returns null --
+    // "if (string.IsNullOrEmpty(uriString)) { return null; }" (UriTypeConverter.cs:44-47).
     UriTypeConverter c;
-    EXPECT_THROW(c.ConvertFrom(""), System::UriFormatException);
+    std::optional<Uri> result;
+    EXPECT_NO_THROW(result = c.ConvertFrom(""));
+    EXPECT_FALSE(result.has_value());
+}
+
+TEST(UriTypeConverterTest, Fix1999_ARelativeUriIsAccepted) {
+    // Added after mutation M4 -- "use UriKind::Absolute" -- went UNCAUGHT: every other case
+    // converts an ABSOLUTE URI, so requiring Absolute never failed. A relative input is the only
+    // one the kind discriminates, and .NET passes UriKind.RelativeOrAbsolute precisely so this
+    // works (UriTypeConverter.cs:50).
+    UriTypeConverter c;
+    std::optional<Uri> relative;
+    EXPECT_NO_THROW(relative = c.ConvertFrom("/path/to/resource"));
+    ASSERT_TRUE(relative.has_value());
+    EXPECT_FALSE(relative->getIsAbsoluteUriProperty());
+    EXPECT_EQ(c.ConvertTo(*relative), "/path/to/resource")
+        << "and it round-trips, which is why ConvertTo uses OriginalString";
+}
+
+TEST(UriTypeConverterTest, Decl1999_OnlyTheEmptyInputIsShortCircuited) {
+    // The widening is exactly one input wide, and that is .NET's own boundary: its comment says
+    // "Let the Uri constructor throw any informative exceptions", so a MALFORMED string must
+    // still throw rather than return the empty state.
+    UriTypeConverter c;
+    EXPECT_THROW((void)c.ConvertFrom("http://exa mple.com/"), System::UriFormatException);
 }
 
 TEST(UriTypeConverterTest, ConvertToString) {
@@ -40,8 +71,9 @@ TEST(UriTypeConverterTest, RoundTrip) {
     UriTypeConverter c;
     Uri original("https://test.org/api");
     std::string s = c.ConvertTo(original);
-    Uri restored = c.ConvertFrom(s);
-    EXPECT_EQ(restored.getHostProperty(), "test.org");
+    auto restored = c.ConvertFrom(s);
+    ASSERT_TRUE(restored.has_value());
+    EXPECT_EQ(restored->getHostProperty(), "test.org");
 }
 
 // ---------------------------------------------------------------------------

modules/uri/tests/System/UriTypeConverterTests.cpp

@@ -0,0 +1,102 @@
+// SPDX-License-Identifier: MIT
+// Copyright (c) Robert Vokac and contributors
+//
+// Negative compile fixture for ticket #1999 (SR-AUD-148, cause U-I).
+//
+// #1999 changed System::UriTypeConverter::ConvertFrom's return type from `Uri` to
+// `std::optional<Uri>`. The by-value Uri CANNOT EXPRESS .NET's null, so an empty string was
+// forwarded straight to the Uri constructor and threw UriFormatException. .NET returns null:
+//
+//     if (value is string uriString)
+//     {
+//         if (string.IsNullOrEmpty(uriString)) { return null; }
+//         // Let the Uri constructor throw any informative exceptions
+//         return new Uri(uriString, UriKind.RelativeOrAbsolute);
+//     }                                                    // UriTypeConverter.cs:40-51
+//
+// The empty case is the ONLY one .NET short-circuits, so the widening is exactly one input wide.
+//
+// This is a public VIRTUAL signature change, which is why it lands under SA-10 (whose list names
+// "return type" explicitly) with SA-2's five conditions, rather than under SA-3 -- SA-3's
+// exclusion is a change to the vtable's SHAPE (adding or removing a virtual, or changing the
+// base), not a signature within an existing slot. Measured, there are ZERO overrides and ZERO
+// derivations anywhere, so the design record's "mandatory migration for every override" cost is
+// zero; what a future override would lose is site 3 below.
+//
+// Migration: bind the result to `auto` (or `std::optional<Uri>`) and test `has_value()`.
+//
+// Records: docs/Migration-UriTypeConverterOptional.md,
+// docs/NegativeConsumerFixtureValidation.md.
+//
+// NEGATIVE-FIXTURE: component=Uri
+#include <optional>
+#include <string>
+#include <type_traits>
+
+#include "System/UriTypeConverter.hpp"
+
+#ifndef SHARP_RUNTIME_NEGATIVE_SITE
+#define SHARP_RUNTIME_NEGATIVE_SITE 0
+#endif
+
+using System::Uri;
+using System::UriTypeConverter;
+
+int main() {
+    const UriTypeConverter converter;
+
+#if SHARP_RUNTIME_NEGATIVE_SITE == 1
+    // NEGATIVE(uritypeconverter-by-value-result): conversion from
+    //     | cannot convert
+    //     | no viable conversion
+    Uri byValue = converter.ConvertFrom("http://example.com");
+    (void)byValue;
+#else
+    auto byValue = converter.ConvertFrom("http://example.com");
+    (void)byValue;
+#endif
+
+#if SHARP_RUNTIME_NEGATIVE_SITE == 2
+    // NEGATIVE(uritypeconverter-direct-member-access): base operand of '->' has non-pointer type
+    //     | no member named
+    //     | base operand of
+    // THE SPELLING MOST LIKELY TO SURVIVE A CARELESS MIGRATION: calling straight through the
+    // result, which used to be a Uri and is now an optional.
+    const std::string host = converter.ConvertFrom("http://example.com").getHostProperty();
+    (void)host;
+#else
+    const std::string host = converter.ConvertFrom("http://example.com")->getHostProperty();
+    (void)host;
+#endif
+
+#if SHARP_RUNTIME_NEGATIVE_SITE == 3
+    // NEGATIVE(uritypeconverter-override-old-signature): invalid covariant return type
+    //     | does not override
+    //     | marked 'override', but does not override
+    // What a FUTURE override loses. Measured, there are none today -- in this repository or in
+    // either downstream consumer -- which is why the recorded migration cost was zero.
+    //
+    // The diagnostic is "invalid covariant return type" rather than "does not override", and that
+    // is more precise than expected: gcc reads the old signature as an ATTEMPTED covariant
+    // override of the new one and rejects it on the spot, naming the reason.
+    struct MyConverter final : UriTypeConverter {
+        Uri ConvertFrom(const std::string& text) const override { return Uri(text); }
+    };
+    (void)sizeof(MyConverter);
+#else
+    struct MyConverter final : UriTypeConverter {
+        std::optional<Uri> ConvertFrom(const std::string& text) const override {
+            return text.empty() ? std::optional<Uri>{} : std::optional<Uri>{Uri(text)};
+        }
+    };
+    (void)sizeof(MyConverter);
+#endif
+
+    // UNCHANGED, and asserted so the fixture proves what did NOT break: ConvertTo still returns a
+    // string by value, the type is still polymorphic, and the empty input no longer throws.
+    static_assert(std::is_same_v<decltype(converter.ConvertTo(std::declval<const Uri&>())),
+                                  std::string>,
+                  "#1999 must not have touched ConvertTo");
+    static_assert(std::is_polymorphic_v<UriTypeConverter>, "still polymorphic");
+    return converter.ConvertFrom("").has_value() ? 1 : 0;
+}