feat(uri): UriCreationOptions reaches a Uri operation (#1997, group A-3)

Rule-14 sweep. UriCreationOptions existed but no Uri operation accepted it,
so a value could be constructed and read and then had nowhere to go --
SR-AUD-149's consumer half. Uri gains the constructor and TryCreate overloads
that take it. Purely additive, under SA-5; nothing needed migrating.

Premise correction found by the compiler: the plan's wording implied the
option type had to be written too, and it already existed -- a first cut
declaring it alongside the overloads failed with "redefinition of class
System::UriCreationOptions". Only the overloads were missing. The existing
type is left untouched, including its public data member, because .NET's is
an unvalidated settable auto-property that a public field is observationally
identical to (#1969's reasoning for ChannelOptions).

Both overloads resolve against Absolute, and that is the reference's choice
(Uri.cs:476-480, UriExt.cs:236-240), so a relative string throws through the
constructor and fails through TryCreate even though the sibling one-argument
constructor accepts one. All three are asserted together so the asymmetry is
observable rather than theoretical.

The option itself stays inert and that is disclosed rather than implied:
.NET's flag disables path/query canonicalisation and this port performs none,
so a Uri built with it set and one built with it clear are byte-for-byte
identical -- asserted across three inputs chosen for dot segments, percent
sequences and a default port. If that test ever fails, the port has grown
canonicalisation and the disclosure must be revisited. The header's obsolete
warning is replaced accordingly; leaving it would be the SR-AUD-168 defect.

Three mutations, all caught, two run once per overload because they are
independent bodies. Downstream measured: 0 sites in both.

#1997 stays open for A-2 (a measured module-boundary cost) and A-4 (a vtable
and access-level change).

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

Author: robertvokac

CLAUDE.md

@@ -0,0 +1,93 @@
+<!-- SPDX-License-Identifier: MIT -->
+<!-- Copyright (c) Robert Vokac and contributors -->
+
+# Migration — `UriCreationOptions` reaches a Uri operation (ticket #1997, group A-3)
+
+*2026-08-19.* `System::Uri` gains `Uri(string, const UriCreationOptions&)` and
+`Uri::TryCreate(string, const UriCreationOptions&, shared_ptr<Uri>&)`.
+
+**Purely additive** — no existing declaration, layout, vtable or mangled symbol changes. Landed
+under **SA-5**. Nothing needs migrating.
+
+---
+
+## 1. What was wrong
+
+`UriCreationOptions` existed, but **no `Uri` operation accepted it**. A value could be constructed
+and read and then had nowhere to go. The type's own header said so, and named this group as the
+fix — SR-AUD-149's consumer half.
+
+## 2. A premise correction found by the compiler
+
+The plan describes A-3 as adding *"`Uri(string, UriCreationOptions)` + `TryCreate` overload"*,
+which reads as though the option type had to be written too. **It already existed**, as
+`modules/uri/include/System/UriCreationOptions.hpp`, and a first cut that declared it alongside
+the overloads failed with *"redefinition of class System::UriCreationOptions"*. Only the two
+overloads were missing.
+
+The existing type is left exactly as it was, including its **public data member**: .NET's
+`DangerousDisablePathAndQueryCanonicalization` is a settable auto-property with no validation,
+which a public field is observationally identical to. SA-8 reaches a representation .NET keeps
+private, readonly or absent — the same reasoning #1969 recorded for `ChannelOptions`' three base
+flags.
+
+## 3. Both overloads resolve against `Absolute`, and that is the reference's choice
+
+```csharp
+public Uri(string uriString, in UriCreationOptions creationOptions)
+    => CreateThis(uriString, false, UriKind.Absolute, in creationOptions);      // Uri.cs:476-480
+
+public static bool TryCreate(string? uriString, in UriCreationOptions creationOptions, out Uri? result)
+    => (result = CreateHelper(uriString, false, UriKind.Absolute, in creationOptions)) is not null;
+                                                                                // UriExt.cs:236-240
+```
+
+So a **relative** string throws through the constructor and fails through `TryCreate`, even
+though the sibling one-argument `Uri(string)` accepts one. That asymmetry is easy to get wrong in
+either direction, and a test asserts all three behaviours together so the distinction is
+observable rather than theoretical.
+
+## 4. The option is inert here, and that is disclosed rather than implied
+
+.NET's flag disables validation and normalisation of the path and query. **This port performs
+none** — no path or query canonicalisation and no percent-encoding or decoding at all, a declared
+limitation of `Uri` and an explicit exclusion in the review plan (§15).
+
+Turning off something that never happens changes nothing. A `Uri` built with the flag set and one
+built with it clear are byte-for-byte identical, and a test asserts that across three inputs
+chosen to exercise dot segments, percent sequences and a default port — the cases where
+canonicalisation would show if it existed. **If that test ever fails, the port has grown
+canonicalisation and the disclosure must be revisited.**
+
+So this group closes SR-AUD-149's **consumer** half and explicitly does not close the behavioural
+half. The header now says exactly that, replacing the obsolete half of its old warning. Saying it
+is not optional: a header describing an effect it cannot produce, without disclosing it, is the
+defect SR-AUD-168 recorded one module over.
+
+## 5. Evidence
+
+Three mutations, **all caught**:
+
+| Mutation | Caught by |
+|---|---|
+| M1 — the constructor's kind becomes `RelativeOrAbsolute` | `Decl1997A3_BothOverloadsResolveAgainstAbsoluteNotRelativeOrAbsolute` |
+| M2 — `TryCreate`'s kind becomes `RelativeOrAbsolute` | the same case |
+| M3 — `TryCreate` always fails | `Fix1997A3_TheTryCreateOverloadExists` |
+
+M1 and M2 are run once per overload because they are **two independent bodies** — fixing one and
+leaving the other is the easy half-repair.
+
+Gate: **17,522 run, 17,522 passed, 0 failed, 0 skipped** across 38 executables — `+5` on 17,517
+(`SharpRuntimeTests_Uri` 289 → 294). No other executable moved. Module graph unchanged at 41/93.
+
+## 6. Downstream, measured
+
+`UriCreationOptions` appears in **zero** places in `cna` and **zero** in `mobile-eggbert`, and
+nothing existing changed in any case. Neither repository was modified.
+
+## 7. Scope
+
+This closes **A-3** of #1997. A-1 landed earlier the same day. **A-2** (`Uri::CheckHostName`)
+remains blocked on a measured module-boundary cost — it classifies through
+`IPv6AddressHelper`/`IPv4AddressHelper`, which `modules/uri` does not have and cannot reach
+without a new public edge — and **A-4** changes `UriParser`'s vtable and access levels.

docs/Migration-UriCreationOptionsOverloads.md

@@ -8,9 +8,11 @@
 #include "SharpRuntime/SharpRuntimeHelper.hpp"
 #include "System/UriHostNameType.hpp"
 #include "System/UriPartial.hpp"
+#include "System/UriCreationOptions.hpp"
 
 namespace System {
 
+
     using SharpRuntime::intcs;
 
     /**
@@ -89,6 +91,25 @@ namespace System {
          */
         Uri(const std::string& uriString, UriKind uriKind);
 
+        /**
+         * @brief Constructs a Uri from a string with the given creation options.
+         *
+         * C++ counterpart of .NET's `Uri(string uriString, in UriCreationOptions creationOptions)`
+         * (`Uri.cs:476-480`). Ticket #1997 group A-3 / SR-AUD-149.
+         *
+         * @param uriString      The URI string.
+         * @param creationOptions Options controlling creation. **Inert in this port** — see
+         *                        `UriCreationOptions`.
+         * @throws System::UriFormatException if @p uriString is not a valid **absolute** URI.
+         *
+         * @note **The kind is `Absolute`, not `RelativeOrAbsolute`**, and that is the reference's
+         * choice rather than this port's: .NET's body is
+         * `CreateThis(uriString, false, UriKind.Absolute, in creationOptions)`. A relative string
+         * therefore throws here, exactly as it does through .NET's overload — which is easy to
+         * get wrong, because the sibling one-argument constructor accepts one.
+         */
+        Uri(const std::string& uriString, const UriCreationOptions& creationOptions);
+
         /**
          * @brief Constructs an absolute URI by combining a base URI with a relative reference.
          *
@@ -193,6 +214,26 @@ namespace System {
         static bool TryCreate(const std::string& uriString, UriKind uriKind,
                                std::shared_ptr<Uri>& result);
 
+        /**
+         * @brief Tries to construct a Uri from a string with the given creation options.
+         *
+         * C++ counterpart of .NET's
+         * `TryCreate(string?, in UriCreationOptions, out Uri?)` (`UriExt.cs:236-240`). Ticket
+         * #1997 group A-3 / SR-AUD-149.
+         *
+         * @param uriString      The URI string.
+         * @param creationOptions Options controlling creation. **Inert in this port** — see
+         *                        `UriCreationOptions`.
+         * @param result         Receives the constructed Uri on success, or null on failure.
+         * @return @c true on success.
+         *
+         * @note Like the constructor, this resolves against `UriKind::Absolute` --
+         * .NET's body is `CreateHelper(uriString, false, UriKind.Absolute, in creationOptions)`.
+         */
+        static bool TryCreate(const std::string& uriString,
+                               const UriCreationOptions& creationOptions,
+                               std::shared_ptr<Uri>& result);
+
         /**
          * @brief Determines whether @p schemeName is a syntactically valid URI scheme.
          *

modules/uri/include/System/Uri.hpp

@@ -10,13 +10,30 @@ namespace System {
      *
      * C++ counterpart of .NET System.UriCreationOptions (introduced in .NET 6).
      *
-     * @warning **No System::Uri operation accepts this type.** The .NET original is
-     *   consumed by `Uri(string, UriCreationOptions)` and by an options-bearing
-     *   `Uri.TryCreate`; this port has neither overload, so a value of this type can be
-     *   constructed and read but can never reach a URI operation at all. That is
-     *   SR-AUD-149, and adding the consumer overloads is public API addition, gated as
-     *   ticket #1997 group A-3. Ticket #1994 added this disclosure only — the type's
-     *   behaviour is unchanged.
+     * @note **Both consumer overloads now exist** — `Uri(string, const UriCreationOptions&)`
+     *   and `Uri::TryCreate(string, const UriCreationOptions&, shared_ptr<Uri>&)` — added by
+     *   ticket #1997 group A-3, which closed SR-AUD-149's consumer half. Ticket #1994 had
+     *   previously added the disclosure that neither existed; that half of the warning is now
+     *   obsolete and is replaced by this note.
+     *
+     * @warning **The option itself remains INERT, and that is the half SR-AUD-149 does not
+     *   close.** .NET's flag disables validation and normalisation of the path and query, but
+     *   this port's `Uri` performs **no path or query canonicalisation and no
+     *   percent-encoding/decoding at all** — a declared limitation of that class
+     *   (`docs/SystemUriNamespaceReviewPlan.md` §15). Turning off something that never happens
+     *   changes nothing: a `Uri` built with the flag set and one built with it clear are
+     *   byte-for-byte identical, and `UriCreationOptionsTest` asserts exactly that.
+     *
+     *   The overloads exist so ported C# declarations compile and so the caller's expressed
+     *   intent is preserved and readable — not because the flag has an effect. Saying so is not
+     *   optional: a header that describes an effect it cannot produce, without disclosing it, is
+     *   the defect SR-AUD-168 recorded one module over.
+     *
+     * @note The flag is a **public data member** rather than a rule-5 accessor pair, and that is
+     *   deliberate: .NET's is a settable auto-property with no validation, which a public field
+     *   is observationally identical to. SA-8 reaches a representation .NET keeps private,
+     *   readonly or absent — the same reasoning #1969 recorded for `ChannelOptions`' three base
+     *   flags.
      */
     struct UriCreationOptions {
         /**

modules/uri/include/System/UriCreationOptions.hpp

@@ -431,6 +431,16 @@ Uri::Uri(const std::string& uriString, UriKind uriKind) {
         throw System::UriFormatException("URI must be relative");
 }
 
+// Ticket #1997 group A-3 / SR-AUD-149. Delegates to the UriKind overload with Absolute, which is
+// what .NET's body does: CreateThis(uriString, false, UriKind.Absolute, in creationOptions)
+// (Uri.cs:476-480). The options are accepted and preserved by the caller's own object; they carry
+// no effect here because this Uri performs no path/query canonicalisation to disable -- disclosed
+// on UriCreationOptions itself.
+Uri::Uri(const std::string& uriString, const UriCreationOptions& creationOptions)
+    : Uri(uriString, UriKind::Absolute) {
+    (void)creationOptions;
+}
+
 Uri::Uri(const Uri& baseUri, const std::string& relativeUri) {
     if (!baseUri.isAbsoluteUri_)
         throw System::ArgumentOutOfRangeException("baseUri");
@@ -658,4 +668,14 @@ bool Uri::TryCreate(const std::string& uriString, UriKind uriKind,
     }
 }
 
+// Ticket #1997 group A-3 / SR-AUD-149. .NET's body is
+// CreateHelper(uriString, false, UriKind.Absolute, in creationOptions) (UriExt.cs:236-240), so
+// this resolves against Absolute like the constructor -- NOT RelativeOrAbsolute, which is the
+// easy mistake because the sibling one-argument constructor accepts a relative string.
+bool Uri::TryCreate(const std::string& uriString, const UriCreationOptions& creationOptions,
+                    std::shared_ptr<Uri>& result) {
+    (void)creationOptions;
+    return TryCreate(uriString, UriKind::Absolute, result);
+}
+
 } // namespace System

modules/uri/src/System/Uri.cpp

@@ -24,3 +24,85 @@ TEST(UriCreationOptionsTest, TwoInstancesIndependent) {
     EXPECT_FALSE(a.DangerousDisablePathAndQueryCanonicalization);
     EXPECT_TRUE(b.DangerousDisablePathAndQueryCanonicalization);
 }
+
+// =============================================================================================
+// Ticket #1997 group A-3 (SR-AUD-149) — the two consumer overloads.
+//
+// Before this group, a UriCreationOptions could be constructed and read but could NEVER REACH A
+// URI OPERATION: neither Uri(string, UriCreationOptions) nor an options-bearing TryCreate
+// existed. That was the finding, and the type's own header said so.
+//
+// The overloads are transcribed from the reference, INCLUDING their kind:
+//   Uri(string, in UriCreationOptions)  -> CreateThis(uriString, false, UriKind.Absolute, ...)
+//                                                                          (Uri.cs:476-480)
+//   TryCreate(string, in UriCreationOptions, out Uri?)
+//                                       -> CreateHelper(uriString, false, UriKind.Absolute, ...)
+//                                                                          (UriExt.cs:236-240)
+// =============================================================================================
+#include <memory>
+#include "System/Uri.hpp"
+#include "System/UriFormatException.hpp"
+
+TEST(UriCreationOptionsTest, Fix1997A3_TheConstructorOverloadExistsAndParses) {
+    UriCreationOptions opts;
+    System::Uri uri("http://example.com/path", opts);
+    EXPECT_EQ(uri.getHostProperty(), "example.com");
+    EXPECT_TRUE(uri.getIsAbsoluteUriProperty());
+}
+
+TEST(UriCreationOptionsTest, Fix1997A3_TheTryCreateOverloadExists) {
+    UriCreationOptions opts;
+    std::shared_ptr<System::Uri> result;
+    EXPECT_TRUE(System::Uri::TryCreate("http://example.com/path", opts, result));
+    ASSERT_NE(result, nullptr);
+    EXPECT_EQ(result->getHostProperty(), "example.com");
+}
+
+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.
+    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"));
+}
+
+TEST(UriCreationOptionsTest, Decl1997A3_TheFlagIsInertAndTheResultIsIdentical) {
+    // THE HALF SR-AUD-149 DOES NOT CLOSE, asserted rather than merely documented. .NET's flag
+    // disables path/query canonicalisation; this port performs none, so setting it changes
+    // nothing. If this ever starts failing, the port has grown canonicalisation and the header's
+    // disclosure must be revisited.
+    UriCreationOptions off;
+    UriCreationOptions on;
+    on.DangerousDisablePathAndQueryCanonicalization = true;
+
+    for (const char* text : {"http://example.com/a/./b/../c?q=1&r=%2F",
+                             "http://example.com/%zz/trailing%",
+                             "https://example.com:443/path#frag"}) {
+        System::Uri a(text, off);
+        System::Uri b(text, on);
+        EXPECT_EQ(a.getOriginalStringProperty(), b.getOriginalStringProperty()) << text;
+        EXPECT_EQ(a.getAbsolutePathProperty(),   b.getAbsolutePathProperty())   << text;
+        EXPECT_EQ(a.getQueryProperty(),          b.getQueryProperty())          << text;
+        EXPECT_EQ(a.getHostProperty(),           b.getHostProperty())           << text;
+    }
+}
+
+TEST(UriCreationOptionsTest, Decl1997A3_TheOptionsAreNotMutatedByEitherOverload) {
+    // The caller's object is theirs; neither overload may write through it.
+    UriCreationOptions opts;
+    opts.DangerousDisablePathAndQueryCanonicalization = true;
+    System::Uri uri("http://example.com/", opts);
+    EXPECT_TRUE(opts.DangerousDisablePathAndQueryCanonicalization);
+
+    std::shared_ptr<System::Uri> result;
+    (void)System::Uri::TryCreate("http://example.com/", opts, result);
+    EXPECT_TRUE(opts.DangerousDisablePathAndQueryCanonicalization);
+}