fix(uri): the constructor and TryCreate share one absolute-URI grammar (#2393)

This port had TWO absolute-URI grammars in one type. Uri::Uri(const
std::string&) called parse() and NEVER checked isAbsoluteUri_, while the
(string, UriKind) overload did -- and TryCreate goes through that overload. So
Uri("://example.com/") SUCCEEDED while
TryCreate("://example.com/", UriKind::Absolute, u) returned FALSE: a caller
could construct a Uri this port's own TryCreate says is not an absolute URI.
Reachable from ordinary code, because a UriBuilder with an empty scheme renders
exactly that string and getUriProperty() is Uri(ToString()).

THE DIRECTION WAS DERIVED, NOT CHOSEN. .NET has one grammar by construction:
new Uri(s) is CreateThis(s, false, UriKind.Absolute) (Uri.cs:424-429),
TryCreate(s, Absolute, out u) is CreateHelper(s, false, UriKind.Absolute)
(UriExt.cs:223-227), and CreateThis throws exactly what CreateHelper returns
null for. The repair is one line.

THE NARROWING IS WIDER THAN THE TICKET DESCRIBED, and is stated plainly rather
than left to be discovered: the constructor no longer accepts ANY relative
reference. Relative-URI support itself is untouched -- only the default kind
moved, onto .NET's, and the migration is to name it. Measured: zero real
consumer sites (cna's single System::Uri match is inside a comment), zero in
mobile-eggbert, and 51 first-party constructions across 24 tests, each keeping
its coverage through the two-argument constructor. Two shipped assertions were
inverted because they asserted the defect.

One consequence moved three times in a day and is recorded: #2391's mutation M1
was an equivalence, then measured wrong BECAUSE OF THIS DEFECT, and is an
equivalence again now that the second grammar is gone. The original reasoning
was right and was defeated only by a bug one layer down.

Four mutations, all caught. The pin asserts the equivalence over an 11-row
corpus rather than the one reported string.

Gate: 17,559 run, 17,559 passed, 0 failed, 0 skipped across 38 executables (+1).
Build directory: build/ only, --parallel 2 throughout.

Author: robertvokac

CLAUDE.md

@@ -0,0 +1,101 @@
+<!-- SPDX-License-Identifier: MIT -->
+# Migration — `Uri(std::string)` requires an absolute URI (#2393)
+
+Ticket **#2393**, landed 2026-08-19 under SA-5 (*"aligning to the reference is ordinary work …
+including where a call that succeeds today starts throwing"*).
+
+## The defect
+
+This port had **two absolute-URI grammars in one type**:
+
+```cpp
+Uri("://example.com/")                                    // SUCCEEDED
+Uri::TryCreate("://example.com/", UriKind::Absolute, u)   // returned FALSE
+```
+
+`Uri::Uri(const std::string&)` called `parse()` and **never checked `isAbsoluteUri_`**, while the
+`(string, UriKind)` overload did — and `TryCreate` goes through that overload. So a caller could
+construct a `Uri` that this port's own `TryCreate` says is not an absolute URI.
+
+**Reachable from ordinary code**: a `UriBuilder` with an empty scheme (accepted since #1996 G-3)
+renders `"://example.com/"`, and `UriBuilder::getUriProperty()` is `Uri(ToString())`.
+
+## The direction was derived, not chosen
+
+.NET has **one** grammar, by construction:
+
+* `new Uri(s)` is `CreateThis(s, false, UriKind.Absolute)` (`Uri.cs:424-429`);
+* `TryCreate(s, UriKind.Absolute, out u)` is `CreateHelper(s, false, UriKind.Absolute)`
+  (`UriExt.cs:223-227`);
+* `CreateThis` throws exactly what `CreateHelper` returns `null` for (`UriExt.cs:18-26`).
+
+So the constructor was wrong and `TryCreate` was right. The repair is one line: delegate.
+
+## The narrowing is wider than the ticket described — say so plainly
+
+The reported symptom was one odd string. The actual change is that **the one-argument constructor no
+longer accepts *any* relative reference**:
+
+```cpp
+Uri u("/relative/path");    // used to construct silently; now throws UriFormatException
+Uri u("a?b");               // likewise
+Uri u("#fragment");         // likewise
+```
+
+**Migration**: name the kind.
+
+```cpp
+Uri u("/relative/path", UriKind::RelativeOrAbsolute);
+```
+
+Relative-URI support is **not** removed — every component accessor, the query/fragment split, and
+resolution against a base all behave exactly as before. Only the *default kind* of the
+one-argument constructor moved, and it moved onto .NET's.
+
+**Measured impact**: **zero** real sites in `cna` (its single `System::Uri` match is inside a
+comment) and **zero** in `mobile-eggbert`. First-party, **51 constructions across 24 tests** needed
+the kind spelled out; every one of those tests keeps its coverage through the two-argument
+constructor, because they were testing *relative-URI behaviour*, not the constructor's default.
+
+Two shipped assertions were **inverted** rather than adapted, because they asserted the defect:
+
+* `Decl1997A3_BothOverloadsResolveAgainstAbsoluteNotRelativeOrAbsolute` ended with
+  `EXPECT_NO_THROW(Uri("/relative/path"))` and called that *"what makes the distinction observable
+  rather than theoretical"*. It was observable, and it was the defect. The case now asserts the
+  throw, and keeps its real subject by contrasting against `UriKind::RelativeOrAbsolute`.
+* `Fix2391_TheComparandKindIsRelativeOrAbsoluteAndItIsLoadBearing` — see below.
+
+## A consequence worth following, because it moved twice in one day
+
+#2391 mutation **M1** (the comparand kind `Absolute` instead of `RelativeOrAbsolute`) has now
+changed status **three times**, and the sequence is the point:
+
+1. First recorded as an **unobservable equivalence**, reasoning that `getUriProperty()` is always
+   absolute, so a relative comparand can never compare equal and both spellings return `false`.
+2. Then measured **wrong**, because of *this* defect: the constructor accepted `"://example.com/"`
+   while `TryCreate(Absolute)` refused it, so `self` could be a `Uri` the strict comparand parse
+   would reject, and the two spellings disagreed. The case was rewritten to pin that.
+3. Now an **equivalence again** — #2393 removed the second grammar, so `self` can no longer be such
+   a `Uri`; the builder throws before any comparand is parsed.
+
+The original reasoning was right; it was defeated only by a bug one layer down. The case is
+renamed `Decl2391_TheComparandKindIsRelativeOrAbsoluteAndIsNowAnEquivalence` and records all three
+steps, so the line is kept because .NET writes it, not because it is load-bearing.
+
+## Tests
+
+`Fix2393_TheConstructorAndTryCreateShareOneGrammar` asserts the **equivalence over an 11-row
+corpus** — empty scheme, absolute-path, relative-path and network-path references, query-only,
+fragment-only, `":"`, `""`, and three genuinely absolute URIs — rather than on the one reported
+string, because a repair that fixed only the reported example would pass a single-row test.
+
+## Mutation testing
+
+Four mutations, all caught:
+
+| # | Mutation | Caught by |
+|---|---|---|
+| M1 | revert to the two grammars | the equivalence pin + `Decl1997A3` + `Decl2391` |
+| M2 | delegate to `RelativeOrAbsolute` | the same |
+| M3 | delegate to `Relative` | broadly, including `UriBuilderTest.ToUri` |
+| M4 | the kind overload stops enforcing `Absolute` | the same set |

docs/Migration-UriConstructorRequiresAnAbsoluteUri.md

@@ -87,6 +87,20 @@ namespace System {
          *         would report the scheme's default port for a host that does not exist,
          *         while `"file:///path"` (RFC 8089) and every hierarchical scheme with no
          *         default-port entry keep an empty host with `Port == -1` and are accepted.
+         *
+         * @note **This constructor requires an ABSOLUTE URI** and throws `UriFormatException` for
+         * a relative reference — ticket **#2393**, 2026-08-19. It is
+         * `CreateThis(uriString, false, UriKind.Absolute)` in .NET (`Uri.cs:424-429`), the same
+         * grammar `TryCreate(s, UriKind::Absolute, u)` uses, so the two accept exactly the same
+         * strings and the constructor throws precisely where `TryCreate` returns `false`.
+         *
+         * **This is a narrowing.** It used to call `parse()` and never check, so it silently
+         * accepted every relative reference — and, because the sibling overload *did* check, this
+         * port carried **two absolute-URI grammars**: `Uri("://example.com/")` succeeded while
+         * `TryCreate("://example.com/", UriKind::Absolute, u)` returned `false`. To construct a
+         * relative reference, name the kind:
+         * `Uri("/relative/path", UriKind::RelativeOrAbsolute)`. Relative-URI support itself is
+         * unchanged. See `docs/Migration-UriConstructorRequiresAnAbsoluteUri.md`.
          */
         explicit Uri(const std::string& uriString);
 

modules/uri/include/System/Uri.hpp

@@ -405,9 +405,21 @@ void Uri::parse(const std::string& rawUriString) {
 // Constructors
 // ---------------------------------------------------------------------------
 
-Uri::Uri(const std::string& uriString) {
-    parse(uriString);
-}
+// Ticket #2393. .NET's one-argument constructor is `CreateThis(uriString, false,
+// UriKind.Absolute)` (Uri.cs:424-429) and TryCreate(s, UriKind.Absolute, out u) is
+// `CreateHelper(uriString, false, UriKind.Absolute)` (UriExt.cs:223-227) -- the SAME grammar, so
+// in .NET the constructor throws exactly where TryCreate returns false.
+//
+// This port had TWO grammars: the body below called parse() and never checked isAbsoluteUri_,
+// while the (string, UriKind) overload did. So `Uri("://example.com/")` SUCCEEDED while
+// `Uri::TryCreate("://example.com/", UriKind::Absolute, u)` returned FALSE -- a caller could
+// construct a Uri this port's own TryCreate says is not an absolute URI. Reachable from ordinary
+// code: a UriBuilder with an empty scheme (accepted since #1996 G-3) renders "://example.com/",
+// and UriBuilder::getUriProperty() is Uri(ToString()).
+//
+// Delegating is the whole repair, and it is a NARROWING: a relative string that used to construct
+// silently now throws UriFormatException, which is what .NET does.
+Uri::Uri(const std::string& uriString) : Uri(uriString, UriKind::Absolute) {}
 
 Uri::Uri(const std::string& uriString, UriKind uriKind) {
     // Ticket #1992 (SR-AUD-145b): reject a value outside the enum's declared domain BEFORE

modules/uri/src/System/Uri.cpp

@@ -404,38 +404,49 @@ TEST(UriBuilderTest, Fix2391_TheComparandIsAStringSoAnUnparseableOTHERIsMerelyUn
         << "an unparseable SELF throws, because the Uri property does";
 }
 
-TEST(UriBuilderTest, Fix2391_TheComparandKindIsRelativeOrAbsoluteAndItIsLoadBearing) {
-    // .NET's comparand branch uses UriKind.RelativeOrAbsolute, NOT Absolute
-    // (Uri.cs, the `comparand is string` branch). Absolute is the plausible wrong choice -- it is
-    // what #1997 A-3 picked for the CREATION overloads, and the two questions have different
-    // answers.
+TEST(UriBuilderTest, Decl2391_TheComparandKindIsRelativeOrAbsoluteAndIsNowAnEquivalence) {
+    // .NET's comparand branch uses UriKind.RelativeOrAbsolute, NOT Absolute (Uri.cs, the
+    // `comparand is string` branch), and this port transcribes that. HONEST RECORD, and it has
+    // moved twice in one day:
     //
-    // A first cut of this test recorded the kind as an unobservable equivalence, reasoning that
-    // `getUriProperty()` is always absolute so a relative comparand can never be equal. MEASURED,
-    // that reasoning is wrong at its premise: this port's `Uri(std::string)` constructor ACCEPTS
-    // "://example.com/" while `TryCreate(s, UriKind::Absolute)` REJECTS it, so `self` can be a
-    // Uri the strict comparand parse would refuse -- and then the two spellings disagree.
+    //   * The first cut of this case recorded the kind as an unobservable EQUIVALENCE, reasoning
+    //     that getUriProperty() is always ABSOLUTE, so a relative comparand can never compare
+    //     equal and both spellings return false.
+    //   * That reasoning was then measured WRONG, because this port's Uri(std::string)
+    //     constructor ACCEPTED "://example.com/" while its own TryCreate(s, Absolute) REJECTED
+    //     it -- two grammars in one type. `self` could therefore be a Uri the strict comparand
+    //     parse would refuse, and the spellings disagreed. The case was rewritten to pin that.
+    //   * #2393 REMOVED THE SECOND GRAMMAR. Uri(std::string) now delegates to
+    //     Uri(s, UriKind::Absolute), which is what .NET's does (Uri.cs:424-429), so the
+    //     constructor and TryCreate accept exactly the same strings -- and the original
+    //     reasoning becomes true. The kind is an equivalence again, this time for a reason that
+    //     holds by construction rather than by luck.
+    //
+    // So: mutating RelativeOrAbsolute to Absolute is a mutation NO TEST CAN CATCH, and the line
+    // is kept as RelativeOrAbsolute because that is what .NET writes, not because it is
+    // load-bearing. Simplifying it would be simplifying the reference rather than porting it.
     UriBuilder emptyScheme;
     emptyScheme.setSchemeProperty("");   // accepted since #1996 G-3
     emptyScheme.setHostProperty("example.com");
     ASSERT_EQ(emptyScheme.ToString(), "://example.com/");
 
-    // Reachability, measured: the two kinds really do disagree on a string a builder can render.
+    // The premise, measured: the two kinds still disagree on this string, so the branch is
+    // reachable and the equivalence is not vacuous.
     std::shared_ptr<System::Uri> parsed;
     EXPECT_TRUE(System::Uri::TryCreate(emptyScheme.ToString(),
                                        System::UriKind::RelativeOrAbsolute, parsed));
     EXPECT_FALSE(System::Uri::TryCreate(emptyScheme.ToString(),
                                         System::UriKind::Absolute, parsed));
 
-    // THIS is the assertion that discriminates. With RelativeOrAbsolute the comparand parses and
-    // the builder is equal to itself; with Absolute the parse fails and Equals returns false,
-    // making a builder unequal to ITSELF.
-    EXPECT_TRUE(emptyScheme.Equals(emptyScheme))
-        << "a builder must be equal to itself wherever its own Uri is obtainable";
-
-    // Still unequal to a different builder, so the case above is not passing for a trivial reason.
+    // And here is why it no longer discriminates: `self` can no longer BE such a Uri. The builder
+    // throws before any comparand is parsed, so neither spelling is ever reached.
     UriBuilder good; good.setHostProperty("example.com");
-    EXPECT_FALSE(emptyScheme.Equals(good));
+    EXPECT_THROW((void)emptyScheme.getUriProperty(), UriFormatException);
+    EXPECT_THROW((void)emptyScheme.Equals(emptyScheme), UriFormatException);
+    EXPECT_THROW((void)emptyScheme.Equals(good), UriFormatException);
+
+    // An unparseable OTHER is still merely unequal, which is the asymmetry #2391 landed and
+    // #2393 does not touch.
     EXPECT_FALSE(good.Equals(emptyScheme));
 }
 

modules/uri/tests/System/UriBuilderTests.cpp

@@ -59,19 +59,28 @@ TEST(UriCreationOptionsTest, Fix1997A3_TheTryCreateOverloadExists) {
 }
 
 TEST(UriCreationOptionsTest, Decl1997A3_BothOverloadsResolveAgainstAbsoluteNotRelativeOrAbsolute) {
-    // THE DETAIL THAT IS EASY TO GET WRONG, because the sibling one-argument Uri constructor
-    // accepts a relative string. .NET passes UriKind.Absolute in BOTH bodies, so a relative
-    // string throws through the constructor and fails through TryCreate.
+    // .NET passes UriKind.Absolute in BOTH bodies, so a relative string throws through the
+    // constructor and fails through TryCreate.
     UriCreationOptions opts;
     EXPECT_THROW(System::Uri("/relative/path", opts), System::UriFormatException);
 
     std::shared_ptr<System::Uri> result;
     EXPECT_FALSE(System::Uri::TryCreate("/relative/path", opts, result));
     EXPECT_EQ(result, nullptr);
 
-    // ...while the one-argument constructor still accepts it, which is what makes the
-    // distinction observable rather than theoretical.
-    EXPECT_NO_THROW(System::Uri("/relative/path"));
+    // UPDATED BY #2393. This case used to end by asserting that the ONE-ARGUMENT constructor
+    // still ACCEPTS "/relative/path", and called that "what makes the distinction observable
+    // rather than theoretical". It was observable, and it was a DEFECT rather than a
+    // distinction: .NET's one-argument constructor is CreateThis(uriString, false,
+    // UriKind.Absolute) (Uri.cs:424-429), the same grammar TryCreate uses, so it rejects a
+    // relative string too. #2393 made the two agree, and the assertion is inverted.
+    EXPECT_THROW((void)System::Uri("/relative/path"), System::UriFormatException)
+        << "#2393: the one-argument constructor is UriKind::Absolute, as .NET's is";
+
+    // What genuinely IS a distinction, and what this case is really for: the options overloads
+    // resolve against Absolute rather than RelativeOrAbsolute. Asserted against the kind that
+    // WOULD have accepted it, so the case still discriminates now that the sibling agrees.
+    EXPECT_NO_THROW((void)System::Uri("/relative/path", System::UriKind::RelativeOrAbsolute));
 }
 
 TEST(UriCreationOptionsTest, Decl1997A3_TheFlagIsInertAndTheResultIsIdentical) {