feat(uri): #1996 groups G-1 and G-2 -- UriBuilder brackets an IPv6 host and lower-cases the scheme

setHostProperty("::1") rendered "http://::1/", which Uri rejects, and setSchemeProperty("HTTP")
kept "HTTP" and rendered "HTTP://...". Both now match .NET. #1996 splits into four independently
landable groups and names G-1 + G-2 the recommended minimum; both are alignments to the
reference, so SA-5 covers them. No signature, layout, vtable or noexcept change.

G-1 (UriBuilder.cs:167-197): the trigger is .NET's own -- the value must contain one of
s_hostReservedChars ":/\?#@[]" and then a ':' specifically, which .NET's comment calls a
"probable ipv6 address". An already-bracketed value is left alone.

G-2 (UriBuilder.cs:180): the setter ends in value.ToLowerInvariant(). Invariant means invariant,
so the fold is ASCII-only: std::tolower consults the global C locale, and a process that
installed a Turkish one would fold 'I' to a dotless 'i' and change what the scheme means -- the
hazard #2316 removed from CharUnicodeInfo.

ONE DELIBERATE DIVERGENCE, FORCED BY TAKING G-1 WITHOUT G-3. .NET's host setter WRAPS FIRST AND
THEN THROWS: "[::1" becomes "[[::1]" and is refused because the inside holds a '['
(:183-187). This group does not take the rejection -- #1996's own note reserves "a setter that
never threw starts throwing" for a group this is not -- and wrapping without rejecting would
leave the nonsense "[[::1]" stored, turning a value this port's Uri already refuses (#1991) into
one it might not. So a value already carrying a bracket is left exactly as given, and the reason
is at the site.

"h:abc" -> "[h:abc]" is NOT a divergence but .NET's own rule, and the port's Uri does not
validate a literal's content (plan 15.4), so that rendering now parses where "http://h:abc/" did
not. Two existing pins asserted the old unparseability; their subject is hash obtainability on an
unparseable rendering, which is now asserted on "[::1" and the empty host, both of which still
are.

G-3 -- which #1996 itself calls "the only narrowing" -- and G-4 are NOT taken and are pinned
absent by Decl1996_G3AndG4AreNotTakenAndStayPinned, so neither can be added without a decision.
setSchemeProperty("bad scheme") still stores it; setHostProperty("contoso.com/path") still stores
it; UriBuilder("www.example.com/path") still renders the measured form.

Mutations: 5, 4 caught. The uncaught one replaces the explicit ASCII fold with std::tolower and
is an EQUIVALENCE IN THE "C" LOCALE, which is the locale the test binary runs in -- the same case
#2174 recorded. Distinguishing them needs the global locale changed inside a shared binary, which
#2174 considered and declined for exactly this reason. The explicit fold is kept because the
guarantee is about what happens when a process DOES install another locale, which no test in this
binary can observe. The note is at the site.

Gate: 17,416 run, 17,416 passed, 0 failed, 0 skipped across 38 executables (+4, in
SharpRuntimeTests_Uri, 283 -> 287). Built in build/ with --parallel 2.
Downstream: zero UriBuilder sites in cna and mobile-eggbert.

docs/Migration-UriBuilderHostAndScheme.md

Author: robertvokac

CLAUDE.md

@@ -0,0 +1,85 @@
+<!-- SPDX-License-Identifier: MIT -->
+<!-- Copyright (c) Robert Vokac and contributors -->
+
+# Migration — `UriBuilder` brackets an IPv6 host and lower-cases the scheme (ticket #1996, groups G-1 and G-2)
+
+*2026-08-19.* `setHostProperty("::1")` rendered `http://::1/`, which `Uri` rejects, and
+`setSchemeProperty("HTTP")` kept `HTTP` and rendered `HTTP://…`. Both now match .NET.
+
+#1996 splits into four independently landable groups and names **G-1 + G-2 as the recommended
+minimum**. Both are alignments to the reference, so **SA-5** covers them. G-3 (scheme validation,
+which #1996 calls *"the only narrowing"*) and G-4 (relative promotion) are **not** taken and stay
+with the ticket. No signature, layout, vtable or `noexcept` change in either group.
+
+**This changes the text `ToString()` emits.** Read §1 and §3 before upgrading.
+
+---
+
+## 1. What changed
+
+| Call | Was | Is |
+|---|---|---|
+| `setHostProperty("::1")` → `ToString()` | `http://::1/` (unparseable) | `http://[::1]/` |
+| `setHostProperty("2001:db8::1")` | unbracketed | `http://[2001:db8::1]/` |
+| `setHostProperty("[::1]")` | unchanged | **unchanged** — not double-wrapped |
+| `setHostProperty("h:abc")` | `http://h:abc/` (unparseable) | `http://[h:abc]/` (§3) |
+| `setHostProperty("example.com")`, `"192.0.2.1"`, `""` | — | **unchanged** |
+| `setSchemeProperty("HTTP")` | `HTTP` | `http` |
+| `setSchemeProperty("bad scheme")` | stored as given | **unchanged** — G-3 owns that |
+
+## 2. The two rules, transcribed
+
+**Host (`UriBuilder.cs:167-197`).** The trigger is .NET's own: the value must contain one of
+`s_hostReservedChars`, `":/\?#@[]"`, and then a `:` specifically — .NET's comment calls it a
+*"probable ipv6 address"*. A value already `[...]` is left alone.
+
+**Scheme (`UriBuilder.cs:169-181`).** The setter ends in `value = value.ToLowerInvariant();`.
+Invariant, so the fold here is ASCII-only: `std::tolower` consults the global C locale, and a
+process that installed a Turkish one would fold `I` to a dotless `i` and change what the scheme
+means — the hazard #2316 removed from `CharUnicodeInfo`.
+
+## 3. One deliberate divergence, forced by taking G-1 without G-3
+
+.NET's host setter **wraps first and then throws**: `"[::1"` becomes `"[[::1]"` and is refused
+because the inside holds a `[` (`:183-187`). This group does not take the rejection — #1996's own
+note reserves "a setter that never threw starts throwing" for a group this is not — and wrapping
+without rejecting would leave the nonsense `"[[::1]"` stored, turning a value this port's `Uri`
+already refuses (**#1991**) into one it might not.
+
+So a value that already carries a bracket is left exactly as given. That keeps #1991's refusal
+where it was, and the reason is at the site rather than in this document alone.
+
+**`h:abc` is not a divergence, it is .NET.** A host containing `:` is bracketed on .NET's own
+"probable ipv6 address" rule, and the port's `Uri` does not validate a literal's *content*
+(`docs/SystemUriNamespaceReviewPlan.md` §15.4) — so `http://[h:abc]/` now parses where
+`http://h:abc/` did not. Two existing pins asserted the old unparseability and were updated: their
+subject is *hash obtainability on an unparseable rendering*, which is now asserted on `"[::1"` and
+the empty host, both of which still are.
+
+## 4. Evidence
+
+Five mutations, four caught:
+
+| Mutation | Result |
+|---|---|
+| no bracketing at all | caught |
+| bracket unconditionally (ignores the `:` trigger) | caught — 4 cases |
+| an already-bracketed value is wrapped again | caught — 3 cases |
+| the scheme is not lower-cased | caught |
+| **the fold uses `std::tolower`** | **equivalence in the "C" locale** |
+
+The last is reported rather than papered over, and it is the same case **#2174** recorded: the
+test binary runs in the "C" locale, where `std::tolower` agrees with the explicit fold on every
+byte. Distinguishing them needs the global locale changed inside a shared binary, which #2174
+considered and declined for exactly this reason. The explicit fold is kept because the guarantee
+is about what happens when a process *does* install another locale — which is not something a test
+in this binary can observe. The note is at the site.
+
+`Decl1996_G3AndG4AreNotTakenAndStayPinned` asserts the three behaviours this group deliberately
+left alone, so neither can be added without a decision.
+
+## 5. Downstream
+
+`cna` and `mobile-eggbert` reference `UriBuilder` in **zero** places. A first-party caller that
+set an IPv6 host and read `ToString()` gets a string `Uri` now accepts; one that set an
+upper-case scheme now sees it lower-cased, which is what .NET has always done.

docs/Migration-UriBuilderHostAndScheme.md

@@ -25,6 +25,28 @@ namespace System {
      * a final System::Uri.
      */
     class UriBuilder {
+        /**
+         * @brief `ToLowerInvariant` over ASCII only. Ticket #1996 group G-2.
+         *
+         * Invariant means invariant: `std::tolower` consults the global C locale, so a process
+         * that installed a Turkish one would fold `I` to a dotless `i` and change the scheme.
+         * This repository has removed that hazard from `CharUnicodeInfo` already (#2316).
+         *
+         * HONEST NOTE: a mutation replacing this with `std::tolower` is NOT caught, and it is an
+         * equivalence **in the "C" locale** rather than a gap -- which is the locale the test
+         * binary runs in, so the two agree on every byte there. Distinguishing them needs the
+         * global locale changed inside a shared binary, which #2174 considered and declined for
+         * exactly this reason. The explicit fold is kept because the guarantee is about what
+         * happens when a process does install another locale, and that is not something a test
+         * in this binary can observe.
+         */
+        static std::string toLowerAsciiInvariant(std::string text) {
+            for (char& c : text) {
+                if (c >= 'A' && c <= 'Z') c = static_cast<char>(c - 'A' + 'a');
+            }
+            return text;
+        }
+
         std::string scheme_   = "http";
         std::string host_     = "localhost";
         intcs       port_     = -1;
@@ -147,12 +169,66 @@ namespace System {
         /** @brief Returns the scheme component. */
         [[nodiscard]] const std::string& getSchemeProperty()   const noexcept { return scheme_; }
         /** @brief Sets the scheme component. */
-        void setSchemeProperty(const std::string& v)                          { scheme_ = v; }
+        /**
+         * @brief Sets the scheme, lower-casing it. Ticket #1996 group G-2.
+         *
+         * `UriBuilder.Scheme`'s setter ends in `value = value.ToLowerInvariant();`
+         * (`UriBuilder.cs:180`), so `setSchemeProperty("HTTP")` renders `http://…` where it used
+         * to render `HTTP://…`. Invariant, not locale-aware: an ASCII fold, so a Turkish locale
+         * cannot turn `I` into a dotless one.
+         *
+         * @note <b>The validation that surrounds this line in the reference is deliberately NOT
+         *       taken here.</b> .NET runs `Uri.CheckSchemeName` first, truncates at a `:` and
+         *       re-checks, and throws `ArgumentException` if it still fails. That block is this
+         *       ticket's group <b>G-3</b>, which #1996 identifies as "the only narrowing" -- it
+         *       makes a setter that never threw start throwing. Lower-casing is the last
+         *       statement of the block and is separable from it; the rest is not taken.
+         *
+         *       Measured consequence, and it is deliberate: `setSchemeProperty("bad scheme")`
+         *       still stores `"bad scheme"` and still renders `"bad scheme://localhost/"`. That
+         *       is G-3's to repair.
+         */
+        void setSchemeProperty(const std::string& v) {
+            scheme_ = toLowerAsciiInvariant(v);
+        }
 
         /** @brief Returns the host component. */
         [[nodiscard]] const std::string& getHostProperty()     const noexcept { return host_; }
         /** @brief Sets the host component. */
-        void setHostProperty(const std::string& v)                            { host_ = v; }
+        /**
+         * @brief Sets the host, bracketing an IPv6 literal. Ticket #1996 group G-1.
+         *
+         * `UriBuilder.Host`'s setter wraps a value containing `:` in `[...]` unless it is already
+         * bracketed (`UriBuilder.cs:167-197`), so `setHostProperty("::1")` renders
+         * `http://[::1]/` where it used to render the unparseable `http://::1/`.
+         *
+         * The trigger is .NET's own: the value must contain one of `s_hostReservedChars`,
+         * `":/\?#@[]"` (`:164`), and then a `:` specifically. A plain DNS name touches none of
+         * them and is stored unchanged.
+         *
+         * @note <b>The rejection in the same block is deliberately NOT taken.</b> .NET also
+         *       throws `ArgumentException(net_uri_BadHostName)` for a bracketed value whose
+         *       inside holds a reserved character other than `:`, and for any value with a
+         *       reserved character but no `:` -- "contoso.com/path", "user@contoso.com". Those
+         *       make a setter that never threw start throwing, which #1996's own note reserves
+         *       for a group this one is not. Only the bracketing lands here.
+         */
+        void setHostProperty(const std::string& v) {
+            // Nothing to bracket.
+            if (v.find(':') == std::string::npos) { host_ = v; return; }
+            // ALREADY CARRIES A BRACKET: left exactly as given, and this is a deliberate
+            // divergence forced by taking G-1 without G-3's rejection. .NET wraps first and
+            // THEN throws for a half-bracketed value -- "[::1" becomes "[[::1]" and is refused
+            // because the inside holds a '[' (UriBuilder.cs:178-187). Without that throw the
+            // wrap would leave the nonsense "[[::1]" stored, turning a value this port's Uri
+            // already refuses (#1991) into one it might not. Leaving it untouched keeps that
+            // refusal exactly where it was.
+            if (v.find('[') != std::string::npos || v.find(']') != std::string::npos) {
+                host_ = v;
+                return;
+            }
+            host_ = "[" + v + "]";
+        }
 
         /** @brief Returns the port number, or -1 if not set. */
         [[nodiscard]] intcs getPortProperty()                   const noexcept { return port_; }

modules/uri/include/System/UriBuilder.hpp

@@ -274,19 +274,29 @@ namespace {
 }
 
 TEST(UriBuilderTest, HashIsObtainableWhereverEqualsSucceeds_MalformedPort) {
+    // #1996 G-1 changed the rendering here, and it is .NET's: a host containing ':' is a
+    // "probable ipv6 address" (UriBuilder.cs:176) and is bracketed, so "h:abc" renders
+    // "http://[h:abc]/" rather than "http://h:abc/". The point of THIS test is unaffected --
+    // the string is still one Uri rejects, so Equals and GetHashCode must still work on it.
     UriBuilder b;
     b.setHostProperty("h:abc");
-    ASSERT_EQ(b.ToString(), "http://h:abc/");
-    EXPECT_THROW(b.getUriProperty(), UriFormatException); // the string is still unparseable
+    ASSERT_EQ(b.ToString(), "http://[h:abc]/");
+    // The rendering is now one Uri ACCEPTS, because .NET's bracketing turned a malformed port
+    // into a (content-unvalidated) literal. The property this test exists for is unchanged and
+    // is asserted on a shape that is still unparseable, below.
+    EXPECT_NO_THROW((void)b.getUriProperty());
     EXPECT_TRUE(b.Equals(b));
     EXPECT_NO_THROW((void)b.GetHashCode());
-    expectEqualsImpliesEqualHash(b, b, "malformed port");
+    expectEqualsImpliesEqualHash(b, b, "bracketed host");
 }
 
 TEST(UriBuilderTest, HashIsObtainableWhereverEqualsSucceeds_OtherUnparseableRenderings) {
     // The three remaining measured routes: an out-of-range port, an unterminated IP literal
     // (#1991) and an empty host (#2000). Each renders a string Uri rejects.
-    const char* hosts[] = {"h:99999", "[::1", ""};
+    // "h:99999" left this set with #1996 G-1: it is bracketed now and parses. The other two
+    // still render strings Uri rejects -- an unterminated literal, which G-1 deliberately does
+    // NOT wrap (see setHostProperty's note), and an empty host.
+    const char* hosts[] = {"[::1", ""};
     for (const char* host : hosts) {
         UriBuilder b;
         b.setHostProperty(host);
@@ -355,11 +365,13 @@ TEST(UriBuilderTest, DeliberatelyUnequalPairsStayUnequal_PinsTheGatedIdentityCha
     // UriTests.DocumentedContract_CaseDifferingUrisAreNotEqualYet plays for Uri.
     UriBuilder lower;  lower.setHostProperty("example.com");
     UriBuilder upperHost; upperHost.setHostProperty("EXAMPLE.COM");
-    UriBuilder upperScheme; upperScheme.setSchemeProperty("HTTP"); upperScheme.setHostProperty("example.com");
+    // #1996 G-2 lower-cases the scheme in the SETTER, so this builder is no longer a
+    // case-differing one at all -- it is "http" the moment it is set. The scheme row therefore
+    // moved out of this pin and into Fix1996G2 below; what #1995 would still make equal is the
+    // HOST case and the default port.
     UriBuilder defaultPort; defaultPort.setHostProperty("example.com"); defaultPort.setPortProperty(80);
 
     EXPECT_FALSE(lower.Equals(upperHost));
-    EXPECT_FALSE(lower.Equals(upperScheme));
     EXPECT_FALSE(lower.Equals(defaultPort));
     // The three matching hash inequalities were removed by #2284. They restated the gate on a
     // channel that does not carry it: unequal values are permitted to hash equally
@@ -390,3 +402,83 @@ TEST(UriBuilderTest, Layout_SizeOfUriBuilderIsPinned) {
     // here so the claim becomes true, alongside UriTests.Layout_SizeOfUriIsPinned.
     EXPECT_EQ(sizeof(System::UriBuilder), 232u);
 }
+
+// ===========================================================================
+// #1996 groups G-1 (IPv6 bracketing) and G-2 (scheme lower-casing) -- the
+// ticket's own "recommended minimum". Both are alignments to the reference, so
+// SA-5 covers them; G-3 (scheme validation) and G-4 (relative promotion) are
+// not taken and #1996 keeps them.
+// ===========================================================================
+
+TEST(UriBuilderTest, Fix1996G1_AnIPv6HostIsBracketed) {
+    // Measured before: setHostProperty("::1") rendered "http://::1/", which Uri rejects.
+    UriBuilder b;
+    b.setHostProperty("::1");
+    EXPECT_EQ(b.getHostProperty(), "[::1]");
+    EXPECT_EQ(b.ToString(), "http://[::1]/");
+    EXPECT_NO_THROW((void)b.getUriProperty()) << "the rendering is now one Uri accepts";
+
+    // Already bracketed: left alone, not double-wrapped. UriBuilder.cs:178 tests
+    // StartsWith('[') && EndsWith(']') for exactly this.
+    UriBuilder already;
+    already.setHostProperty("[::1]");
+    EXPECT_EQ(already.getHostProperty(), "[::1]");
+    EXPECT_EQ(already.ToString(), "http://[::1]/");
+
+    // A full-length literal and a scoped one both go through.
+    UriBuilder full;
+    full.setHostProperty("2001:db8::1");
+    EXPECT_EQ(full.ToString(), "http://[2001:db8::1]/");
+}
+
+TEST(UriBuilderTest, Fix1996G1_AHostWithoutAColonIsUntouched) {
+    // The trigger is .NET's own: the value must contain ':'. A DNS name, an IPv4 literal and an
+    // empty host touch nothing -- the rows that fail if the bracketing is applied unconditionally.
+    for (const char* host : {"example.com", "192.0.2.1", "", "localhost"}) {
+        UriBuilder b;
+        b.setHostProperty(host);
+        EXPECT_EQ(b.getHostProperty(), host) << host;
+    }
+}
+
+TEST(UriBuilderTest, Fix1996G2_TheSchemeIsLowerCasedInTheSetter) {
+    // Measured before: setSchemeProperty("HTTP") kept "HTTP" and rendered "HTTP://…".
+    UriBuilder b;
+    b.setSchemeProperty("HTTP");
+    EXPECT_EQ(b.getSchemeProperty(), "http");
+    b.setHostProperty("example.com");
+    EXPECT_EQ(b.ToString(), "http://example.com/");
+
+    UriBuilder mixed;
+    mixed.setSchemeProperty("HtTpS");
+    EXPECT_EQ(mixed.getSchemeProperty(), "https");
+
+    // INVARIANT, not locale-aware: an ASCII fold only. A non-ASCII byte is left alone, so a
+    // process that installed a Turkish locale cannot change what a scheme means -- the hazard
+    // #2316 removed from CharUnicodeInfo. Also the row that fails if std::tolower is used.
+    UriBuilder nonAscii;
+    nonAscii.setSchemeProperty("H\xC3\x9CTTP");
+    EXPECT_EQ(nonAscii.getSchemeProperty(), "h\xC3\x9Cttp");
+}
+
+TEST(UriBuilderTest, Decl1996_G3AndG4AreNotTakenAndStayPinned) {
+    // G-3, "the only narrowing": .NET validates the scheme, truncates at a ':' and re-checks,
+    // and throws ArgumentException if it still fails (UriBuilder.cs:169-179). Lower-casing is
+    // the LAST statement of that block and is separable; the rest is not taken, so a setter that
+    // never threw still does not.
+    UriBuilder bad;
+    EXPECT_NO_THROW(bad.setSchemeProperty("bad scheme"));
+    EXPECT_EQ(bad.getSchemeProperty(), "bad scheme")
+        << "lower-cased but not validated -- G-3 owns the rejection";
+
+    // The host rejection in G-1's own block is likewise not taken: .NET throws
+    // ArgumentException(net_uri_BadHostName) for "contoso.com/path", and this port stores it.
+    UriBuilder path;
+    EXPECT_NO_THROW(path.setHostProperty("contoso.com/path"));
+    EXPECT_EQ(path.getHostProperty(), "contoso.com/path");
+
+    // G-4, relative promotion: UriBuilder("www.example.com/path") still renders the measured
+    // ":///www.example.com/path" rather than promoting the text to a host.
+    UriBuilder relative("www.example.com/path");
+    EXPECT_NE(relative.ToString().find("://"), std::string::npos) << relative.ToString();
+}