fix(uri): Uri equality and hashing are canonical (#1995, SR-AUD-142)

Rule-14 sweep. operator== compared the raw input string and GetHashCode
hashed it, so HTTP://EXAMPLE.COM:80/Path and http://example.com/Path were
unequal with different hashes. Both members now feed from one canonical key,
which is how .NET keeps them consistent -- it renders both from
UriComponents.HttpRequestUrl = Scheme | Host | Port | Path | Query.

The design record missed the most surprising half. Section 14.1 proposes only
folding and the default port; the reference ALSO excludes the fragment and
the user-info, in a comment of its own -- "Fragment AND UserInfo (for
non-mailto URIs) are ignored" (Uri.cs:1833).

A trap measurement found, not the record: defaultPortForScheme matches
lower-case names only, so this port parses HTTP://example.com/ with port -1
and the lower-case form with 80. Comparing stored numbers would have left
them unequal even after folding the scheme, defeating the repair on its own
motivating input. The key resolves the default from the folded scheme, for
comparison only; the parse is untouched.

Not reproduced and stated: .NET compares UNC/DOS paths case-insensitively and
hashes file: URIs likewise. This port models neither, so equality is narrower
than .NET's -- never equal where .NET is unequal, the safe direction.

UriBuilder is deliberately NOT delegated, though section 14.1 and .NET both
say it should be: delegating reintroduces the throw #2004 measured and
removed, so the two landed decisions conflict and the reference cannot settle
it for this port. Filed as #2391.

Six mutations, all caught. M2/M3/M6 were invalid as first written -- their
anchors spelled \x01 as an escape rather than the literal text -- and were
re-run rather than counted.

Three pre-existing pins handled: two inverted (both existed to make this
change visible) and one rewritten, with the obsolete name removed rather than
left as a disabled stub.

Downstream measured: 0 sites in both -- the single grep hit is a comment
saying cna deliberately avoids System::Uri.

Gate: 17,528 run, 17,528 passed, 0 failed, 0 skipped across 38 executables
(+6 on 17,522; SharpRuntimeTests_Uri 294 -> 300). Module graph 41/93.

Author: robertvokac

CLAUDE.md

@@ -0,0 +1,116 @@
+<!-- SPDX-License-Identifier: MIT -->
+<!-- Copyright (c) Robert Vokac and contributors -->
+
+# Migration — `Uri` equality and hashing are canonical (ticket #1995, SR-AUD-142)
+
+*2026-08-19.* `System::Uri::operator==` and `GetHashCode` compare and hash a **canonical
+identity** instead of the raw input string.
+
+**Equality semantics change**, so the behaviour of any container keyed by `Uri` changes. Nothing
+that was equal becomes unequal — the change is a widening. Landed under **SA-5**; no signature,
+layout, vtable, mangled-symbol or `noexcept` change, and **no rendered string moves**.
+
+---
+
+## 1. What was wrong
+
+`operator==` compared `absoluteUri_` verbatim and `GetHashCode` hashed it. Measured:
+`HTTP://EXAMPLE.COM:80/Path` and `http://example.com/Path` were **unequal, with different
+hashes**, although they name the same resource.
+
+## 2. What .NET compares — and the half the design record missed
+
+Both members feed from the **same** component set, which is why they cannot disagree:
+
+```csharp
+UriComponents components = UriComponents.HttpRequestUrl;                  // Uri.cs:1835, 1539
+if (_syntax.InFact(UriSyntaxFlags.MailToLikeUri)) components |= UriComponents.UserInfo;
+string selfUrl = ... GetParts(components, UriFormat.SafeUnescaped);
+```
+
+and `HttpRequestUrl = Scheme | Host | Port | Path | Query` (`UriEnumTypes.cs:43`).
+
+**The design record proposed only "case-fold scheme and host, treat an explicit default port as
+absent".** The reference *also* excludes the **fragment** and the **user-info**, and says so in a
+comment of its own — *"Fragment AND UserInfo (for non-mailto URIs) are ignored"* (`Uri.cs:1833`).
+So:
+
+```cpp
+Uri("http://example.com/p#one") == Uri("http://example.com/p#two")   // true
+Uri("http://user@example.com/p") == Uri("http://example.com/p")      // true
+```
+
+Neither follows from §14.1's wording. Both are now asserted.
+
+## 3. A trap measurement found, not the record
+
+`defaultPortForScheme` matches **lower-case** scheme names only, so this port parses
+`HTTP://example.com/` with port **−1** and `http://example.com/` with port **80**. Comparing the
+*stored* numbers would therefore have left those two **unequal even after folding the scheme** —
+defeating the repair on exactly the input it exists for.
+
+The identity key resolves the default from the **folded** scheme. The parse itself is untouched:
+`getPortProperty()` still returns −1 there, and the pre-existing pin asserting that still passes.
+
+.NET has no such trap because it lower-cases the scheme *while parsing* and then resolves the
+default, so its `Port != other.Port` (`Uri.cs:1822`) already compares resolved numbers.
+
+## 4. Why fold at comparison rather than at parse
+
+This port deliberately performs **no parse-time canonicalisation** — an explicit exclusion of the
+review plan (§15). Folding at comparison reaches .NET's answer without touching `AbsoluteUri`,
+`OriginalString`, `getSchemeProperty()` or `getHostProperty()`, all of which still return the raw
+input. A test asserts that.
+
+## 5. What is *not* reproduced, stated rather than discovered later
+
+.NET compares the **path** case-insensitively for UNC and DOS paths
+(`IsUncOrDosPath ? OrdinalIgnoreCase : Ordinal`, `Uri.cs:1849`) and hashes a `file:` URI
+case-insensitively (`Uri.cs:1548-1551`). This port models **neither** `IsUncOrDosPath` nor
+`IsFile`, so the path is always compared case-sensitively.
+
+That is a **narrower** equality than .NET's — it never calls equal two URIs .NET would call
+unequal — which is the safe direction. A test pins it.
+
+## 6. `UriBuilder` is deliberately not changed, and that is a conflict, not an omission
+
+§14.1 also says *"`UriBuilder` delegates to `Uri`"*, and .NET does exactly that
+(`GetHashCode() => Uri.GetHashCode()`, `UriBuilder.cs:279`). **Delegating would reintroduce a
+defect this repository already measured and removed.** .NET's `Uri` property builds the Uri and
+can **throw**; ticket #2004 moved `UriBuilder::GetHashCode` off that route precisely because of
+it, listing four routes through *ordinary setters* where it throws.
+
+So the two landed decisions conflict, and the reference does not settle it *for this port*: .NET
+is consistent because **both** its members go through `Uri` and throw together; this port is
+consistent because **neither** does. Delegating one alone restores the inconsistency #2004
+removed.
+
+That is **ticket #2391**, not something to resolve silently here. The gap #1995 widens — a builder
+identity that is raw text while `Uri`'s is canonical — is pinned by
+`Decl1995_BuilderHashNoLongerMatchesTheBuiltUrisHash`.
+
+## 7. Evidence
+
+Six mutations, **all caught**: no case folding; the fragment included; the user-info included;
+the default port not resolved; the hash reverting to `absoluteUri_`; the query dropped.
+
+M2, M3 and M6 were **invalid as first written** — their anchors spelled `\x01` as an escape
+rather than as the literal backslash text in the source — and were re-run rather than counted.
+
+Two pre-existing pins were **inverted rather than deleted**, because both existed to make this
+change visible: `DocumentedContract_CaseDifferingUrisAreNotEqualYet` said *"this test must be
+updated when identity changes"*, and `UriIdentityItselfIsUnchangedByThisTicket` was written by
+#2004 so a reader would not mistake **that** ticket for an identity change. A third,
+`HashIsValueIdenticalWhereTheOldRouteSucceeded`, asserted a #2004 compatibility claim this ticket
+invalidates, and was rewritten to assert the new relationship and name #2391.
+
+Gate: **17,528 run, 17,528 passed, 0 failed, 0 skipped** across 38 executables — `+6` on 17,522
+(`SharpRuntimeTests_Uri` 294 → 300: seven cases added, two pins inverted in place, and one
+obsolete pin removed rather than left disabled). No other executable moved. Module graph unchanged
+at 41/93.
+
+## 8. Downstream, measured
+
+`System::Uri` appears in **zero** places in `cna` and **zero** in `mobile-eggbert`. The one grep
+hit is a **comment** in `cna/modules/media/src/Xna/Song.cpp` explaining that it deliberately does
+*not* use `System::Uri`. Neither repository was modified.

docs/Migration-UriCanonicalIdentity.md

@@ -59,6 +59,16 @@ namespace System {
         /** Parses @p uriString into component fields. Called by all constructors. */
         void parse(const std::string& uriString);
 
+        /**
+         * @brief Builds the canonical string that `operator==` compares and `GetHashCode` hashes.
+         *
+         * Ticket #1995 / SR-AUD-142. Both identity members feed from this one function, so they
+         * cannot disagree -- the same guarantee .NET gets by feeding both from
+         * `GetParts(UriComponents.HttpRequestUrl, ...)`. See the definition in `Uri.cpp` for what
+         * is included, what is deliberately excluded, and what is not reproduced.
+         */
+        [[nodiscard]] std::string identityKey() const;
+
     public:
         /**
          * @brief Constructs a Uri from an absolute or relative URI string.

modules/uri/include/System/Uri.hpp

@@ -642,15 +642,83 @@ bool Uri::getIsLoopbackProperty() const {
 
 std::string Uri::ToString() const { return absoluteUri_; }
 
+// ---------------------------------------------------------------------------
+// Ticket #1995 / SR-AUD-142 — URI identity.
+//
+// operator== compared absoluteUri_ verbatim and GetHashCode hashed it, so
+// "HTTP://EXAMPLE.COM:80/Path" and "http://example.com/Path" were UNEQUAL with different hashes,
+// although they name the same resource.
+//
+// .NET compares and hashes the SAME component set, which is why the two agree by construction:
+//
+//     UriComponents components = UriComponents.HttpRequestUrl;          // Uri.cs:1835, 1539
+//     if (_syntax.InFact(UriSyntaxFlags.MailToLikeUri)) components |= UriComponents.UserInfo;
+//     string selfUrl = ... GetParts(components, UriFormat.SafeUnescaped);
+//
+// and HttpRequestUrl is `Scheme | Host | Port | Path | Query` (UriEnumTypes.cs:43).
+//
+// THE DESIGN RECORD MISSED THE MOST SURPRISING HALF OF THAT. Section 14.1 proposes only
+// "case-fold scheme and host, treat an explicit default port as absent"; the reference ALSO
+// EXCLUDES THE FRAGMENT AND THE USER-INFO, and says so in a comment of its own -- "Fragment AND
+// UserInfo (for non-mailto URIs) are ignored" (Uri.cs:1833). So `http://a/b#x == http://a/b#y`
+// and `http://u@a/b == http://a/b`, which no reading of the record would have predicted.
+//
+// Scheme and host are folded HERE rather than at parse time because this port deliberately does
+// no parse-time canonicalisation (review plan section 15); .NET lower-cases them while parsing,
+// so by the time its equality runs they are already canonical. Folding at comparison reaches the
+// same answer without touching AbsoluteUri or OriginalString -- no rendered string moves.
+//
+// NOT REPRODUCED, and measured rather than assumed: .NET compares the PATH case-insensitively for
+// UNC and DOS paths (`IsUncOrDosPath ? OrdinalIgnoreCase : Ordinal`, Uri.cs:1849) and hashes a
+// file: URI case-insensitively (Uri.cs:1548-1551). This port models neither IsUncOrDosPath nor
+// IsFile, so the path is always compared case-sensitively. That is a narrower equality than
+// .NET's -- it never calls equal two URIs .NET would call unequal -- and a test pins it.
+std::string Uri::identityKey() const {
+    // A relative reference has no components to canonicalise: .NET compares OriginalString
+    // (Uri.cs:1752-1753).
+    if (!isAbsoluteUri_) return "\x01relative\x01" + absoluteUri_;
+
+    const auto fold = [](std::string v) {
+        for (char& c : v)
+            if (c >= 'A' && c <= 'Z') c = static_cast<char>(c - 'A' + 'a');
+        return v;
+    };
+
+    const std::string foldedScheme = fold(scheme_);
+
+    // THE DEFAULT PORT MUST BE RESOLVED FROM THE FOLDED SCHEME, and that is a trap measurement
+    // found rather than the design record: defaultPortForScheme matches lower-case names only, so
+    // this port parses "HTTP://example.com/" with port -1 and "http://example.com/" with port 80.
+    // Comparing the stored numbers would therefore have left those two UNEQUAL even after
+    // case-folding the scheme -- defeating the repair on exactly the input it exists for.
+    // (`UriTests.DocumentedContract_MixedCaseSchemeHasNoDefaultPort` pins that parse behaviour,
+    // which is unchanged: this resolves for COMPARISON only.)
+    //
+    // .NET has no such trap because it lower-cases the scheme while parsing and then resolves the
+    // default, so its `Port != other.Port` (Uri.cs:1822) is already comparing resolved numbers.
+    const intcs resolvedPort = (port_ == -1) ? defaultPortForScheme(foldedScheme) : port_;
+
+    return foldedScheme + "\x01" + fold(host_) + "\x01" + std::to_string(resolvedPort) + "\x01"
+         + path_ + "\x01" + query_;
+}
+
 intcs Uri::GetHashCode() const {
-    return static_cast<intcs>(std::hash<std::string>{}(absoluteUri_));
+    // Hashes exactly what operator== compares, so the two cannot disagree -- which is the same
+    // guarantee .NET gets by feeding both from GetParts(HttpRequestUrl, ...).
+    return static_cast<intcs>(std::hash<std::string>{}(identityKey()));
 }
 
 // ---------------------------------------------------------------------------
 // Operators
 // ---------------------------------------------------------------------------
 
-bool Uri::operator==(const Uri& other) const { return absoluteUri_ == other.absoluteUri_; }
+bool Uri::operator==(const Uri& other) const {
+    // An absolute and a relative reference are never equal: .NET returns false as soon as
+    // IsAbsoluteUri differs (Uri.cs:1749-1750). The key encodes that, but stating it here keeps
+    // the intent visible.
+    if (isAbsoluteUri_ != other.isAbsoluteUri_) return false;
+    return identityKey() == other.identityKey();
+}
 bool Uri::operator!=(const Uri& other) const { return !(*this == other); }
 
 // ---------------------------------------------------------------------------

modules/uri/src/System/Uri.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 <functional>
 #include "System/UriBuilder.hpp"
 #include "System/ArgumentException.hpp"
 #include "System/ArgumentOutOfRangeException.hpp"
@@ -310,19 +311,26 @@ TEST(UriBuilderTest, HashIsObtainableWhereverEqualsSucceeds_OtherUnparseableRend
     }
 }
 
-TEST(UriBuilderTest, HashIsValueIdenticalWhereTheOldRouteSucceeded) {
-    // The compatibility claim, asserted rather than argued: for every builder whose
-    // rendering parses, hashing the string and hashing the built Uri give the same number.
-    UriBuilder shapes[6];
-    shapes[0].setHostProperty("example.com");
-    shapes[1].setHostProperty("example.com"); shapes[1].setPortProperty(8080);
-    shapes[2].setHostProperty("example.com"); shapes[2].setUserNameProperty("u");
-                                              shapes[2].setPasswordProperty("p");
-    shapes[3].setHostProperty("example.com"); shapes[3].setQueryProperty("a=1");
-    shapes[4].setHostProperty("example.com"); shapes[4].setFragmentProperty("f");
-    shapes[5].setHostProperty("[::1]");       shapes[5].setPortProperty(443);
-    for (const UriBuilder& b : shapes)
-        EXPECT_EQ(b.GetHashCode(), b.getUriProperty().GetHashCode()) << b.ToString();
+TEST(UriBuilderTest, Decl1995_BuilderHashNoLongerMatchesTheBuiltUrisHash) {
+    // REWRITTEN by #1995. This asserted #2004's compatibility claim -- that for every builder
+    // whose rendering parses, hashing the string and hashing the built Uri give the same number.
+    // That claim rested on Uri::GetHashCode hashing absoluteUri_ verbatim, which #1995 changed:
+    // Uri now hashes a canonical identity key (folded scheme and host, resolved port, no fragment
+    // or user-info), so the two numbers legitimately differ.
+    //
+    // The builder's own hash is UNCHANGED and still hashes the rendered string, because #2004
+    // measured four ordinary setter routes where building a Uri THROWS -- see this file's
+    // GetHashCode doc-comment. Making the builder delegate to Uri, which is what .NET does
+    // (`GetHashCode() => Uri.GetHashCode()`, UriBuilder.cs:279), would reintroduce that throw.
+    // That conflict is ticket #2391, not something to resolve silently here.
+    UriBuilder b;
+    b.setHostProperty("EXAMPLE.COM");
+    b.setPortProperty(80);
+    EXPECT_EQ(b.GetHashCode(), static_cast<SharpRuntime::intcs>(
+                                    std::hash<std::string>{}(b.ToString())))
+        << "the builder still hashes its rendered string";
+    EXPECT_NE(b.GetHashCode(), b.getUriProperty().GetHashCode())
+        << "and the built Uri now hashes its canonical identity instead";
 }
 
 TEST(UriBuilderTest, EqualsAndGetHashCodeAreTotalOnTheSameSet) {
@@ -379,21 +387,20 @@ TEST(UriBuilderTest, DeliberatelyUnequalPairsStayUnequal_PinsTheGatedIdentityCha
     // and only they have to be updated when #1995 lands.
 }
 
-TEST(UriBuilderTest, UriIdentityItselfIsUnchangedByThisTicket) {
-    // Uri's own operator== and GetHashCode were already paired (both read absoluteUri_) and
-    // this ticket does not touch them. Pinned so a later reader does not mistake #2004 for
-    // an identity change.
+TEST(UriBuilderTest, Fix1995_UriIdentityIsNowCanonical) {
+    // INVERTED by #1995. This was written by #2004 to say "this ticket does not change Uri
+    // identity", so a later reader would not mistake #2004 for an identity change. #1995 IS that
+    // change, so the pin's subject moves rather than the pin being deleted.
     System::Uri a("http://example.com/p");
     System::Uri b("http://example.com/p");
     System::Uri caseDiff("HTTP://EXAMPLE.COM/p");
     System::Uri explicitDefaultPort("http://example.com:80/p");
-    // Equal Uris hash equally -- the contract direction, kept. The two matching inequalities for
-    // the unequal pairs were removed by #2284: a collision between unequal values is legal
-    // (docs/HashAssertionContractRule.md R2), so the operator== assertions carry the pin.
     EXPECT_TRUE(a == b);
     EXPECT_EQ(a.GetHashCode(), b.GetHashCode());
-    EXPECT_FALSE(a == caseDiff);
-    EXPECT_FALSE(a == explicitDefaultPort);
+    EXPECT_TRUE(a == caseDiff)            << "#1995: scheme and host are folded for comparison";
+    EXPECT_TRUE(a == explicitDefaultPort) << "#1995: an explicit default port is the default";
+    EXPECT_EQ(a.GetHashCode(), caseDiff.GetHashCode());
+    EXPECT_EQ(a.GetHashCode(), explicitDefaultPort.GetHashCode());
 }
 
 TEST(UriBuilderTest, Layout_SizeOfUriBuilderIsPinned) {