fix(core): Stopwatch::Frequency is the clock's own (#2326, SR-AUD-130)

Frequency was 10,000,000 and GetTimestamp() divided the clock's nanosecond count
by 100. .NET reports the platform's frequency -- 1,000,000,000 on Unix. Landed
under SA-8, option A of the review's two.

THE OLD PAIR WAS SELF-CONSISTENT AND STILL A DEFECT, and that distinction is the
ticket. Every elapsed time it computed was correct; what it could not do was
RESOLVE anything finer than 100 ns, because GetTimestamp() threw the low two
digits away -- two events 30 ns apart got the same timestamp here and different
ones in .NET. A test asserts the resolution directly rather than the constant.

THE VALUE IS DERIVED FROM Clock::period, NOT TRANSCRIBED. .NET's Windows build
returns QueryPerformanceFrequency, but this port samples std::chrono::
steady_clock, so reporting QPC's frequency would be a lie about a different
timer. It also stays constexpr where .NET's is a runtime static readonly, which
is a stronger guarantee, not a weaker one.

THE REVIEW'S WARNING WAS CORRECT AND WAS ACTED ON. Twelve tests across two
suites had to be rescaled, and none was a regression: they are CCF-004's
evidence that the subtraction is DEFINED, which is untouched -- the delta still
wraps to exactly the two's-complement value. What moved is the reported tick
count, and every new expectation is .NET's own (long)((end - start) * 0.01),
hand-computed rather than taken from the implementation, because a test that
mirrors its own formula proves nothing.

Two needed more than a number: SignedSweepAtUnitFrequency and
PrecisionAbovePow2_53IsAPreExistingProperty are about double rounding at unit
scale, and the system provider only HAPPENED to have unit frequency. They now
construct a FixedFrequencyProvider(TicksPerSecond), which is what their names
always claimed.

Instance measurement is completely unaffected -- it never went through
Frequency. Gate 17,306 run, 0 failed. Downstream: zero sites in either consumer.

Author: robertvokac

CLAUDE.md

@@ -0,0 +1,93 @@
+<!-- SPDX-License-Identifier: MIT -->
+<!-- Copyright (c) Robert Vokac and contributors -->
+
+# Migration — `Stopwatch::Frequency` is the clock's, not the `TimeSpan` tick rate (ticket #2326)
+
+*2026-08-18.* `Stopwatch::Frequency` was `10'000'000` and `GetTimestamp()` divided the clock's
+nanosecond count by 100. .NET reports the **platform's** frequency — 1,000,000,000 on Unix.
+
+Landed under `docs/StandingApprovals.md` **SA-8**. **Timestamp values change scale by 100×** and
+`GetElapsedTime`'s conversion is no longer the identity. No signature, layout, vtable or
+`noexcept` change, and `Frequency` stays `constexpr`.
+
+---
+
+## 1. What changed
+
+| | Was | Is |
+|---|---|---|
+| `Stopwatch::Frequency` | `10'000'000` | **`1'000'000'000`** |
+| `GetTimestamp()` | nanoseconds **÷ 100** | the clock's raw nanosecond count |
+| `GetElapsedTime(a, b)` scale factor | exactly `1.0` | **`0.01`** — .NET's `s_tickFrequency` |
+| `GetElapsedTime(1000, 3000)` | `2000` ticks | **`20`** ticks (2000 ns *is* 20 ticks) |
+| `TimeProvider::getTimestampFrequencyProperty()` | `10'000'000` | **`1'000'000'000`** (it forwards) |
+| `Elapsed`, `ElapsedMilliseconds`, `ElapsedTicks` on an instance | — | **unchanged** |
+| every measured duration | — | **unchanged, and finer** |
+
+## 2. Why the old value was a defect, not merely a different choice
+
+The old pair was **self-consistent**: `Frequency` was `TimeSpan::TicksPerSecond`, timestamps were
+100-ns ticks, and every elapsed time it computed was correct. What it could not do was **resolve**
+anything finer than 100 ns — `GetTimestamp()` threw the low two digits away, so two events 30 ns
+apart received the *same* timestamp here and different ones in .NET.
+
+A test asserts the resolution directly: two back-to-back `GetTimestamp()` calls must be able to
+differ by less than 100.
+
+## 3. The value is derived, not transcribed
+
+```cpp
+static constexpr longcs Frequency = Clock::period::den / Clock::period::num;
+```
+
+.NET's Windows build returns `QueryPerformanceFrequency`. This port samples
+`std::chrono::steady_clock`, so **reporting QPC's frequency would be a lie about a different
+timer**. Reporting the frequency of the clock actually read is the correct answer, and on both
+libstdc++ and MSVC `steady_clock::period` is `std::nano` — .NET's own Unix answer.
+
+It also stays `constexpr`, where .NET's is a runtime `static readonly`. That is a *stronger*
+guarantee than .NET gives, not a weaker one.
+
+## 4. To migrate
+
+A stored timestamp from a previous build is no longer comparable with a new one — but that was
+never a durable value anyway (`steady_clock`'s epoch is unspecified and process-local).
+
+```cpp
+// converting a timestamp delta to seconds: unchanged, and now more precise
+double seconds = double(t2 - t1) / Stopwatch::Frequency;
+
+// code that assumed timestamps were TimeSpan ticks
+TimeSpan span = TimeSpan::FromTicks(t2 - t1);        // WRONG since #2326
+TimeSpan span = Stopwatch::GetElapsedTime(t1, t2);   // right, and always was
+```
+
+Instance measurement — `Start`/`Stop`/`Elapsed`/`ElapsedTicks` — is **completely unaffected**; it
+never went through `Frequency`.
+
+## 5. What this ticket had to re-measure, and why
+
+The review warned that `TimeProvider::GetElapsedTime`'s scaling factor was *"exactly 1.0 precisely
+because `Frequency == TimeSpan::TicksPerSecond`"*, and that changing `Frequency` re-enables a
+non-unit scale on a path carrying CCF-004 saturation work. That was correct, and twelve tests
+across two suites had to be rescaled.
+
+**None of them was a regression.** They were CCF-004's evidence that the subtraction is *defined*
+rather than undefined, and that claim is untouched — the delta still wraps to exactly the
+two's-complement value. What moved is the reported tick count, because a scale is now applied, and
+every new expectation is **.NET's own**: `(long)((end - start) * 0.01)` with the saturating
+float-to-integer conversion modern .NET adopted.
+
+Two of them needed more than a number. `SignedSweepAtUnitFrequency` and
+`PrecisionAbovePow2_53IsAPreExistingProperty` are about `double` rounding at unit scale, and the
+system provider only *happened* to have unit frequency; they now construct a
+`FixedFrequencyProvider(TicksPerSecond)`, which is what their names always claimed.
+
+Two saturation pins stopped reaching the guard, because `0.01 × INT64_MAX` is comfortably
+representable. The guard is still exercised — by `CustomFrequency_ScalingLeavingRangeSaturates`,
+which supplies its own frequency and is unaffected.
+
+## 6. Downstream, measured
+
+Neither `cna` nor `mobile-eggbert` references `Stopwatch::Frequency`, `Stopwatch::GetTimestamp` or
+`getTimestampFrequencyProperty` — **zero sites in both**. Neither repository was modified.

audit/AUDIT_FINDINGS_INDEX.md

@@ -106,17 +106,44 @@ namespace System::Diagnostics {
 
         /**
          * @brief Gets the frequency of the timer as the number of ticks per second.
-         * Returns 10,000,000 to match the .NET tick resolution (100 ns per tick).
+         *
+         * C++ counterpart of .NET `Stopwatch.Frequency`, which is `public static readonly long`
+         * and **platform-determined**: `Stopwatch.Unix.cs:8-12` returns 1,000,000,000 and the
+         * Windows build returns `QueryPerformanceFrequency`.
+         *
+         * @par This was 10,000,000 until ticket #2326, and the old value cost RESOLUTION
+         * The port reported .NET's `TimeSpan` tick rate rather than its own clock's, and
+         * `GetTimestamp()` divided by 100 to match — so two events 30 ns apart received the
+         * **same** timestamp here and different ones in .NET. The pair was self-consistent, and
+         * every elapsed time it computed was correct; what it could not do was resolve anything
+         * finer than 100 ns.
+         *
+         * The value is derived from `Clock::period`, which is the frequency of the clock this
+         * type actually reads. That is deliberate and is not the same as transcribing .NET's
+         * Windows branch: reporting `QueryPerformanceFrequency` while sampling
+         * `std::chrono::steady_clock` would be a lie about a different timer. On libstdc++ and
+         * MSVC alike `steady_clock::period` is `std::nano`, so this is 1,000,000,000 — .NET's
+         * own Unix answer.
+         *
+         * @note It stays `constexpr`, where .NET's is a runtime `static readonly`, because
+         *       `Clock::period` is a compile-time property. That is a *stronger* guarantee than
+         *       .NET gives, not a weaker one, so no caller can be surprised by it.
          */
-        static constexpr longcs Frequency = 10'000'000LL;
+        static constexpr longcs Frequency =
+            static_cast<longcs>(Clock::period::den) / static_cast<longcs>(Clock::period::num);
 
         /** @brief Indicates whether the Stopwatch timer is based on a high-resolution performance counter. */
         static constexpr bool IsHighResolution = true;
 
-        /** @brief Returns the current high-frequency timestamp in Frequency units (100-ns ticks since epoch). */
+        /**
+         * @brief Returns the current high-frequency timestamp, in `Frequency` units.
+         *
+         * Since ticket #2326 this is the clock's own raw count — nanoseconds on every platform
+         * this port builds for — rather than that count divided by 100. The division was what
+         * cost the resolution described on `Frequency`.
+         */
         [[nodiscard]] static longcs GetTimestamp() {
-            return std::chrono::duration_cast<std::chrono::nanoseconds>(
-                       Clock::now().time_since_epoch()).count() / 100LL;
+            return static_cast<longcs>(Clock::now().time_since_epoch().count());
         }
 
         /**
@@ -129,10 +156,15 @@ namespace System::Diagnostics {
 
         /**
          * @brief Gets the elapsed time between two timestamps previously retrieved via
-         * GetTimestamp(). Both @p startingTimestamp and @p endingTimestamp are already expressed
-         * in Frequency (100-ns tick) units on this port, so no unit conversion is needed --
-         * real .NET's own s_tickFrequency scaling factor reduces to exactly 1.0 here since
-         * Frequency == TimeSpan.TicksPerSecond.
+         * GetTimestamp().
+         *
+         * @par The scaling factor is no longer 1.0 (#2326)
+         * It used to be, because `Frequency` was `TimeSpan::TicksPerSecond` and the timestamps
+         * were already `TimeSpan` ticks. Now `Frequency` is the clock's own — 1,000,000,000 —
+         * so this applies .NET's `s_tickFrequency = TimeSpan.TicksPerSecond / Frequency`
+         * (`Stopwatch.cs:18`) like the reference does. The delta is still computed in the
+         * unsigned domain first, for the CCF-004 reason below, and the scaling saturates rather
+         * than overflowing.
          */
         [[nodiscard]] static System::TimeSpan GetElapsedTime(longcs startingTimestamp, longcs endingTimestamp) {
             // CCF-004 class A -- defined wrap (docs/DefinedArithmeticBoundaryPlan.md section 4.1,
@@ -144,7 +176,22 @@ namespace System::Diagnostics {
             // one-argument door, so the same wrap is produced in the unsigned domain and
             // converted back. Every representable difference is byte-identical to before, and the
             // four wrapping shapes keep the exact values they had (SR-AUD-131, ticket #2218).
-            return System::TimeSpan::FromTicks(subtractTimestamps(endingTimestamp, startingTimestamp));
+            const longcs delta = subtractTimestamps(endingTimestamp, startingTimestamp);
+            if constexpr (Frequency == System::TimeSpan::TicksPerSecond) {
+                return System::TimeSpan::FromTicks(delta);
+            } else {
+                // .NET's own conversion, and it must SATURATE rather than overflow: the domain of
+                // a nanosecond delta is wider than the TimeSpan tick domain by a factor of 100,
+                // so a large-but-representable delta scales past INT64_MAX. The bounds are the
+                // same ones TimeProvider::GetElapsedTime uses, for the same reason.
+                const double scaled = static_cast<double>(delta) *
+                    (static_cast<double>(System::TimeSpan::TicksPerSecond) /
+                     static_cast<double>(Frequency));
+                constexpr double twoPow63 = 9223372036854775808.0;   // 2^63 exactly
+                if (scaled >= twoPow63)  return System::TimeSpan::FromTicks(std::numeric_limits<longcs>::max());
+                if (scaled < -twoPow63)  return System::TimeSpan::FromTicks(std::numeric_limits<longcs>::min());
+                return System::TimeSpan::FromTicks(static_cast<longcs>(scaled));
+            }
         }
 
         /** @brief Returns the elapsed time formatted the same way as Elapsed.ToString(). */