fix(time-zone): conversions clamp, adjustment rules validate (#2186)

#2186 asked five System::TimeZone parity questions, each "requiring the .NET
reference or a managed runtime that this container does not have". /rv answers all
five: three repairs, two already correct.

(1) THE CONVERSIONS CLAMP. .NET builds its result through

    private static DateTime SafeCreateDateTimeFromTicks(long ticks, DateTimeKind kind = ...)
        => (ulong)ticks <= DateTime.MaxTicks ? new DateTime(ticks, kind)
                                             : (ticks < 0 ? DateTime.MinValue : DateTime.MaxValue);
                                                     -- TimeZoneInfo.Cache.cs:340-342

so ConvertTimeFromUtc(DateTime::MaxValue, +14) is MaxValue, not an exception. The
cast to ulong is the whole trick and is reproduced: a negative tick count wraps to
something enormous, so one unsigned comparison rejects both ends at once.

ConvertTime clamps ONCE, at the end. .NET computes the result "from raw ticks to
avoid precision loss from double-clamping" (TimeZoneInfo.cs:683-685), so an
intermediate UTC value that leaves the range must not drag a representable final
answer to a bound. A mutation that clamps twice is caught.

.NET does NOT clamp everywhere, and that is recorded rather than smoothed over: its
invalid-time compatibility path builds a raw `new DateTime(...)` and lets it throw,
with a comment saying so (:661-667). That path needs TimeZoneInfoOptions and
adjustment rules this port's TimeZoneInfo does not model.

(2)+(3) THE THREE VALIDATIONS, AND THE REFERENCE CORRECTS THE TICKET ON TWO OF THEM.
#2179 measured all three as accepted and declined to repair them because "inventing
three more rejections on a recollection of the .NET source is exactly what this
review declines to do". That was right:

  * the daylightDelta range is NOT +/-14 hours. It is -23.0 .. 14.0, and .NET
    explains why in a comment of its own -- Samoa moved across the International
    Date Line, so describing its delta needs -23. THE MESSAGE STILL SAYS "plus or
    minus 14.0 hours", because it is shared with UtcOffsetOutOfRange. That
    inconsistency is .NET's and is transcribed rather than tidied;
  * the seconds check is not "sub-minute". It is "not a whole number of minutes",
    so 1h30m30s fails as surely as 30s does;
  * the time-of-day check EXEMPTS MinValue for dateStart and MaxValue for dateEnd.

One conjunct of .NET's time-of-day check is `Kind == Unspecified`. This port has no
DateTimeKind (a permanent deviation), so it is absent -- which makes this port
stricter for a UTC-kinded argument and identical for every argument it can express.

(4) TWO QUESTIONS, TWO DIFFERENT ANSWERS. TryFindSystemTimeZoneById returns false
for every failure and already matched: .NET's discards the exception outright
(TimeZoneInfo.cs:526-527). The throwing form was the divergence -- #2183 folded
three failures into one boolean and kept TimeZoneNotFoundException "rather than
guessing InvalidTimeZoneException". .NET raises InvalidTimeZoneException when the
file EXISTS but is not zone data (TimeZoneInfo.Unix.cs:697) and reserves
TimeZoneNotFoundException for an id that names nothing. Those are different answers
to different questions, and a caller catching only the first used to swallow the
second.

(5) ALREADY CORRECT, AND THE REFERENCE CONTAINS A TRAP. TimeZone.CalculateUtcOffset
first decides isDst from the DST window, which puts an ambiguous 01:30 INSIDE
daylight -- and the next line overrides it:

    if (isDst && time >= ambiguousStart && time < ambiguousEnd)
        isDst = time.IsAmbiguousDaylightSavingTime();      -- TimeZone.cs:237-240

That flag is set only by a prior UTC-to-local conversion, so a DateTime built from
its fields carries false and the answer is the STANDARD offset. Reading only the
window test gives the opposite answer. #2182 chose standard and chose right; the
pin's parenthetical is now a measurement rather than a recollection.

Two gated pins inverted, three cases replacing two. Five mutations, all caught.

Downstream: neither cna nor mobile-eggbert references TimeZoneInfo or TimeZone --
zero sites in both.

Gate: 17,329 run, 17,329 passed, 0 failed, 0 skipped across 38 executables, GREEN.

docs/Migration-TimeZoneClampAndValidation.md

Author: robertvokac

CLAUDE.md

@@ -0,0 +1,115 @@
+<!-- SPDX-License-Identifier: MIT -->
+<!-- Copyright (c) Robert Vokac and contributors -->
+
+# Migration — time-zone conversions clamp, and adjustment rules validate (ticket #2186)
+
+*2026-08-18.* #2186 asked five `System::TimeZone` parity questions, each *"requiring the .NET
+reference or a managed runtime that this container does not have"*. `/rv` answers all five.
+**Three were repairs, two were already correct — and the reference corrects the ticket's own
+statement of two of the repairs.**
+
+Landed under `docs/StandingApprovals.md` SA-5. No signature, layout or `noexcept` change.
+
+---
+
+## 1. The five answers
+
+| # | Question | .NET | Outcome |
+|---|---|---|---|
+| 1 | Do the conversions clamp at `DateTime::Min/MaxValue`? | **yes** (`TimeZoneInfo.Cache.cs:340-342`) | **repaired** |
+| 2 | Does `CreateAdjustmentRule` reject three further shapes? | **yes** (`AdjustmentRule.cs:206-223`) | **repaired**, with two corrections |
+| 3 | What are the exact resource strings? | four of them | **landed** |
+| 4 | Does `TryFind…` return false for every failure? Which exception for non-zone data? | false always; **`InvalidTimeZoneException`** | half already correct, half **repaired** |
+| 5 | For an ambiguous local time, is the standard reading preferred? | **yes** | **already correct** |
+
+## 2. Question 1 — the conversions clamp
+
+```csharp
+private static DateTime SafeCreateDateTimeFromTicks(long ticks, DateTimeKind kind = …)
+    => (ulong)ticks <= DateTime.MaxTicks ? new DateTime(ticks, kind)
+                                         : (ticks < 0 ? DateTime.MinValue : DateTime.MaxValue);
+```
+
+| Call | Was | Is |
+|---|---|---|
+| `ConvertTimeFromUtc(DateTime::MaxValue, +14)` | `ArgumentOutOfRangeException` | `DateTime::MaxValue` |
+| `ConvertTimeToUtc(DateTime::MinValue, +14)` | `ArgumentOutOfRangeException` | `DateTime::MinValue` |
+| any in-range conversion | — | **unchanged** |
+
+The cast to `ulong` is the whole trick and is reproduced deliberately: a negative tick count wraps
+to something enormous, so **one** unsigned comparison rejects both ends at once.
+
+`ConvertTime(dt, source, destination)` clamps **once, at the end**. .NET computes the result *"from
+raw ticks to avoid precision loss from double-clamping"* (`TimeZoneInfo.cs:683-685`), so an
+intermediate UTC value that leaves the range must not drag a representable final answer to a bound.
+A test pins that, and a mutation that clamps twice is caught.
+
+**.NET does not clamp everywhere**, and the exception is documented rather than smoothed over: its
+invalid-time compatibility path builds a raw `new DateTime(...)` and lets it throw, with a comment
+saying so (`TimeZoneInfo.cs:661-667`). That path needs `TimeZoneInfoOptions` and adjustment rules
+this port's `TimeZoneInfo` does not model, so it is unreachable here.
+
+## 3. Question 2 — and two of the ticket's three statements were wrong
+
+#2179 measured all three as accepted and declined to repair them, because *"inventing three more
+rejections on a recollection of the .NET source is exactly what this review declines to do."* That
+was the right call, and the reference shows why:
+
+* **the `daylightDelta` range is not ±14 hours.** It is `-23.0 .. 14.0`, and .NET explains why in
+  a comment of its own: *Samoa moved across the International Date Line*, so describing its delta
+  needs −23. **The message still says "plus or minus 14.0 hours"**, because it is shared with
+  `UtcOffsetOutOfRange`. That inconsistency is .NET's and is transcribed rather than tidied;
+* **the seconds check is not "sub-minute".** It is *not a whole number of minutes*, so
+  `1h30m30s` fails as surely as `30s` does;
+* the time-of-day check **exempts** `MinValue` for `dateStart` and `MaxValue` for `dateEnd`.
+
+One conjunct of .NET's time-of-day check is `Kind == Unspecified`. This port has no `DateTimeKind`
+(a permanent deviation), so it is absent — which makes this port **stricter** for a UTC-kinded
+argument and identical for every argument this port can express.
+
+## 4. Question 4 — two questions, two different answers
+
+`TryFindSystemTimeZoneById` returns **false for every failure**: .NET's discards the exception
+outright (`TimeZoneInfo.cs:526-527`), and this port's `catch (...)` already did the same.
+
+The throwing form is where the divergence was. #2183 folded three failures into one boolean and
+kept `TimeZoneNotFoundException` for all of them *"rather than guessing InvalidTimeZoneException"*.
+.NET raises `InvalidTimeZoneException` when the file **exists but is not zone data**
+(`TimeZoneInfo.Unix.cs:697`) and reserves `TimeZoneNotFoundException` for an id that names nothing.
+Those are different answers to different questions — *"there is no such zone"* versus *"that is not
+a zone"* — and a caller catching only the first used to swallow the second.
+
+## 5. Question 5 — already correct, and the reference contains a trap
+
+.NET's legacy `TimeZone.CalculateUtcOffset` first decides `isDst` from the DST window, which puts
+an ambiguous 01:30 **inside daylight** — and then overrides it:
+
+```csharp
+if (isDst && time >= ambiguousStart && time < ambiguousEnd)
+    isDst = time.IsAmbiguousDaylightSavingTime();      // TimeZone.cs:237-240
+```
+
+That flag is set only by a prior UTC→local conversion, so a `DateTime` built from its fields
+carries `false` and the answer is the **standard** offset. **Reading only the window test gives the
+opposite answer**, and that is the trap: the override decides it, not the window. #2182 chose
+standard, and it chose right.
+
+## 6. To migrate
+
+Code that caught `ArgumentOutOfRangeException` around a conversion at the extremes will no longer
+see it; the result is clamped instead. Code that builds adjustment rules with a time-of-day, a
+sub-minute delta or a delta beyond `-23..14` hours will now be rejected.
+
+## 7. Evidence
+
+| Mutation | Caught |
+|---|---|
+| Clamp both ends to `MaxValue` (the sign is ignored) | ✅ |
+| `ConvertTime` clamps the intermediate UTC value too | ✅ |
+| The `daylightDelta` range becomes a symmetric ±14 | ✅ |
+| The whole-minutes check becomes a sub-minute check | ✅ |
+| Non-zone-data goes back to `TimeZoneNotFoundException` | ✅ (3 tests) |
+
+## 8. Downstream
+
+Neither `cna` nor `mobile-eggbert` references `TimeZoneInfo` or `TimeZone` — zero sites in both.

docs/Migration-TimeZoneClampAndValidation.md

@@ -293,6 +293,68 @@ namespace System {
                         "dateStart");
             }
 
+            /**
+             * @brief The three further validations .NET's ValidateAdjustmentRule performs.
+             *
+             * Ticket #2186 (2026-08-18). #2179 measured all three as accepted here and
+             * deliberately did not repair them, because "the audit's managed probe covers only
+             * the reversed date range, and inventing three more rejections on a recollection of
+             * the .NET source is exactly what this review declines to do". The reference is
+             * available now (`TimeZoneInfo.AdjustmentRule.cs:174-223`), and it **corrects the
+             * ticket's own statement of two of the three**:
+             *
+             *   - the `daylightDelta` range is NOT +/-14 hours. It is `-23.0 .. 14.0`, and .NET
+             *     explains why in a comment of its own: Samoa moved across the International Date
+             *     Line, so describing its daylight delta needs -23. The MESSAGE still says "plus
+             *     or minus 14.0 hours", because it is shared with `UtcOffsetOutOfRange`. That
+             *     inconsistency is .NET's and is transcribed rather than tidied;
+             *   - the seconds check is not "sub-minute". It is "not a whole number of minutes",
+             *     so 1h30m30s fails as surely as 30s does;
+             *   - the time-of-day check EXEMPTS `DateTime::MinValue` for `dateStart` and
+             *     `MaxValue` for `dateEnd`, which is how a rule that spans all time is spelled.
+             */
+            static void validateAdjustmentRule(const DateTime& dateStart, const DateTime& dateEnd,
+                                               const TimeSpan& daylightDelta) {
+                validateDateRange(dateStart, dateEnd);
+
+                // TimeZoneInfo.AdjustmentRule.cs:206-209.
+                constexpr double kMinDaylightDeltaHours = -23.0;
+                constexpr double kMaxDaylightDeltaHours = 14.0;
+                if (daylightDelta.getTotalHoursProperty() < kMinDaylightDeltaHours ||
+                    daylightDelta.getTotalHoursProperty() > kMaxDaylightDeltaHours) {
+                    throw System::ArgumentOutOfRangeException(
+                        "daylightDelta", daylightDelta.ToString(),
+                        "The TimeSpan parameter must be within plus or minus 14.0 hours.");
+                }
+
+                // :211-214.
+                if (daylightDelta.getTicksProperty() % TimeSpan::TicksPerMinute != 0) {
+                    throw System::ArgumentException(
+                        "The TimeSpan parameter cannot be specified more precisely than whole "
+                        "minutes.",
+                        "daylightDelta");
+                }
+
+                // :216-223. This port has no DateTimeKind (a permanent deviation), so the
+                // `Kind == Unspecified` conjunct is not reproducible and is simply absent -- which
+                // makes this port's check STRICTER than .NET's for a UTC-kinded argument, and
+                // identical for every argument this port can express.
+                if (dateStart != DateTime::MinValue &&
+                    dateStart.getTimeOfDayProperty() != TimeSpan::Zero) {
+                    throw System::ArgumentException(
+                        "The supplied DateTime includes a TimeOfDay setting.   This is not "
+                        "supported.",
+                        "dateStart");
+                }
+                if (dateEnd != DateTime::MaxValue &&
+                    dateEnd.getTimeOfDayProperty() != TimeSpan::Zero) {
+                    throw System::ArgumentException(
+                        "The supplied DateTime includes a TimeOfDay setting.   This is not "
+                        "supported.",
+                        "dateEnd");
+                }
+            }
+
             /**
              * @brief Creates an adjustment rule with zero BaseUtcOffsetDelta.
              *
@@ -304,7 +366,7 @@ namespace System {
                 DateTime dateStart, DateTime dateEnd, TimeSpan daylightDelta,
                 TransitionTime daylightTransitionStart, TransitionTime daylightTransitionEnd)
             {
-                validateDateRange(dateStart, dateEnd);
+                validateAdjustmentRule(dateStart, dateEnd, daylightDelta);
                 auto r = std::shared_ptr<AdjustmentRule>(new AdjustmentRule());
                 r->dateStart_               = dateStart;
                 r->dateEnd_                 = dateEnd;
@@ -330,7 +392,7 @@ namespace System {
                 TransitionTime daylightTransitionStart, TransitionTime daylightTransitionEnd,
                 TimeSpan baseUtcOffsetDelta)
             {
-                validateDateRange(dateStart, dateEnd);
+                validateAdjustmentRule(dateStart, dateEnd, daylightDelta);
                 auto r = std::shared_ptr<AdjustmentRule>(new AdjustmentRule());
                 r->dateStart_               = dateStart;
                 r->dateEnd_                 = dateEnd;
@@ -782,11 +844,47 @@ namespace System {
          *
          * C++ counterpart of .NET TimeZoneInfo.ConvertTime(DateTime, TimeZoneInfo, TimeZoneInfo).
          */
+        /**
+         * @brief `DateTime` from a tick count, clamped to the representable range.
+         *
+         * Ticket #2186 (2026-08-18) answered question 1. The three conversion doors used
+         * `DateTime::Add`, whose overflow is an `ArgumentOutOfRangeException`; .NET **clamps**:
+         *
+         * @code
+         * private static DateTime SafeCreateDateTimeFromTicks(long ticks, DateTimeKind kind = …)
+         *     => (ulong)ticks <= DateTime.MaxTicks ? new DateTime(ticks, kind)
+         *                                          : (ticks < 0 ? DateTime.MinValue : DateTime.MaxValue);
+         * @endcode
+         * (`TimeZoneInfo.Cache.cs:340-342`), and `ConvertTime` builds its result through it
+         * (`TimeZoneInfo.cs:685`).
+         *
+         * **The cast to `ulong` is the whole trick and is reproduced deliberately**: a negative
+         * tick count wraps to something enormous, so one unsigned comparison rejects both ends of
+         * the range at once. Spelling it as two signed comparisons would be equivalent, and this
+         * spelling is kept because it is the reference's.
+         *
+         * .NET does NOT clamp everywhere. Its invalid-time compatibility path builds a raw
+         * `new DateTime(...)` and lets it throw, with a comment saying so explicitly
+         * (`TimeZoneInfo.cs:661-667`) — that path needs `TimeZoneInfoOptions` and adjustment
+         * rules this port's `TimeZoneInfo` does not model, so it is not reachable here.
+         */
+        [[nodiscard]] static DateTime safeFromTicks(SharpRuntime::longcs ticks) {
+            const auto unsignedTicks = static_cast<unsigned long long>(ticks);
+            if (unsignedTicks <= static_cast<unsigned long long>(DateTime::MaxTicks))
+                return DateTime(ticks);
+            return ticks < 0 ? DateTime::MinValue : DateTime::MaxValue;
+        }
+
         static DateTime ConvertTime(const DateTime& dt,
                                     const TimeZoneInfo& sourceTimeZone,
                                     const TimeZoneInfo& destinationTimeZone) {
-            DateTime utc = dt.Add(-sourceTimeZone.baseUtcOffset_);
-            return utc.Add(destinationTimeZone.baseUtcOffset_);
+            // #2186: the intermediate UTC ticks may leave the range while the final local ticks
+            // land back inside it, which is why .NET computes the result "from raw ticks to avoid
+            // precision loss from double-clamping" (TimeZoneInfo.cs:683-685) and clamps only once,
+            // at the end.
+            const SharpRuntime::longcs utcTicks =
+                dt.getTicksProperty() - sourceTimeZone.baseUtcOffset_.getTicksProperty();
+            return safeFromTicks(utcTicks + destinationTimeZone.baseUtcOffset_.getTicksProperty());
         }
 
         /**
@@ -796,7 +894,8 @@ namespace System {
          */
         static DateTime ConvertTimeFromUtc(const DateTime& dt,
                                            const TimeZoneInfo& destinationTimeZone) {
-            return dt.Add(destinationTimeZone.baseUtcOffset_);
+            return safeFromTicks(dt.getTicksProperty() +
+                                 destinationTimeZone.baseUtcOffset_.getTicksProperty());   // #2186
         }
 
         /**
@@ -805,7 +904,8 @@ namespace System {
          * C++ counterpart of .NET TimeZoneInfo.ConvertTimeToUtc(DateTime, TimeZoneInfo).
          */
         static DateTime ConvertTimeToUtc(const DateTime& dt, const TimeZoneInfo& sourceTimeZone) {
-            return dt.Add(-sourceTimeZone.baseUtcOffset_);
+            return safeFromTicks(dt.getTicksProperty() -
+                                 sourceTimeZone.baseUtcOffset_.getTicksProperty());   // #2186
         }
 
         /**

modules/time-zone/include/System/TimeZoneInfo.hpp

@@ -5,6 +5,7 @@
 #include "System/PlatformNotSupportedException.hpp"
 #include "System/TimeZoneNotFoundException.hpp"
 #include "TimeZonePosixSupport.hpp"
+#include "System/InvalidTimeZoneException.hpp"
 #include <cstdlib>
 #include <ctime>
 
@@ -102,12 +103,28 @@ bool hasTzifMagic(const std::string& path) {
 
 } // namespace
 
+// Ticket #2186, question 4. #2183 folded three distinct failures into one boolean and kept
+// TimeZoneNotFoundException for all of them "rather than guessing InvalidTimeZoneException".
+// The guess is unnecessary now: .NET raises TimeZoneNotFoundException when the id names nothing,
+// and InvalidTimeZoneException when the file EXISTS but is not usable zone data
+// (`TimeZoneInfo.Unix.cs:697`, SR.InvalidTimeZone_NoTTInfoStructures). The two are different
+// answers to different questions -- "there is no such zone" versus "that is not a zone" -- and a
+// caller that catches only the first would previously have swallowed the second.
+//
+// TryFindSystemTimeZoneById is unaffected: .NET's discards the exception entirely
+// (`TimeZoneInfo.cs:526-527`), so it returns false for every failure, and this port's `catch (...)`
+// already did the same.
 static bool zoneFileExists(const std::string& id) {
     if (!isWellFormedZoneId(id)) return false;
     std::string path = "/usr/share/zoneinfo/" + id;
     struct stat st {};
-    if (stat(path.c_str(), &st) != 0 || !S_ISREG(st.st_mode)) return false;
-    return hasTzifMagic(path);
+    return stat(path.c_str(), &st) == 0 && S_ISREG(st.st_mode);
+}
+
+// True when a file that EXISTS does not carry zone data. Separated from zoneFileExists so the
+// caller can tell the two failures apart; see the comment above.
+static bool zoneFileIsNotZoneData(const std::string& id) {
+    return !hasTzifMagic("/usr/share/zoneinfo/" + id);
 }
 #endif
 
@@ -262,6 +279,10 @@ std::shared_ptr<TimeZoneInfo> TimeZoneInfo::FindSystemTimeZoneById(const std::st
     if (!zoneFileExists(id))
         throw System::TimeZoneNotFoundException(
             "The time zone ID '" + id + "' was not found on the local computer.");
+    if (zoneFileIsNotZoneData(id))
+        throw System::InvalidTimeZoneException(
+            "There are no ttinfo structures in the tzfile.  At least one ttinfo structure is "
+            "required in order to construct a TimeZoneInfo object.");
 
     detail::ZoneMetadata meta;
     {