fix(threading): AutoResetEvent and ManualResetEvent are WaitHandles (#1958, SR-AUD-209)

This closes #1958, the last of its eight members.

Both types had no base class and no vtable, each carrying its own mutex,
condition variable and signalled flag -- a third and fourth copy of logic
EventWaitHandle already had. They are now what .NET declares: sealed classes
deriving from EventWaitHandle whose ENTIRE BODY is one constructor
(AutoResetEvent.cs:6-9, ManualResetEvent.cs:6-9). Neither declares a member of
its own, so this deletes the duplicated bodies rather than adding a base to
them.

WHY IT MATTERED: because they were not WaitHandles, WaitHandle::WaitAll and
WaitAny -- repaired by #1952 and documented ever since -- could not accept them
at all. Not a wrong answer: the code did not compile.

TWO THINGS THE FINDING DID NOT NAME, both required:

 1. EventWaitHandle had no closed state. #1956 gave Mutex, AutoResetEvent and
    ManualResetEvent a closed_ flag; EventWaitHandle was its fourth case and
    was missed, so Close() reached WaitHandle's EMPTY Dispose() and did
    nothing. Deriving without fixing that would have silently reverted #1956
    for both events.

 2. EventWaitHandle::Set() lost wakeups -- it stored and notified without
    holding mtx_, so a waiter that had evaluated the predicate as false but
    not yet slept missed the notification. AutoResetEvent::Set() took the
    lock, so deriving would have INTRODUCED the race into a type that did not
    have it. Probed over 900 single-waiter rounds: EventWaitHandle lost 2,
    AutoResetEvent lost 0. cna holds this type by value in six places, all for
    async completion.

Layout: both events 96 -> 112, EventWaitHandle 104 -> 112; consumers rebuild.
112 was measured after 104 was asserted and the build rejected it. The pin
asserts the relationship -- both events must be exactly sizeof(EventWaitHandle)
-- as well as the figures.

WaitOne() returns bool rather than void, a widening at every call site. The
initialState parameter loses its default, as .NET has none and it had zero
call sites.

Seven mutations, six caught. M6 (revert Set() to the unlocked form) is NOT
caught and cannot be caught deterministically: ~0.2% per round means a bounded
test would catch it about a third of the time. A first cut carried exactly such
a 200-round case and it was REMOVED rather than kept, on the reasoning
#1957/SR-AUD-201 and #2031 recorded. A multi-waiter amplification was tried and
is invalid -- it reports 100% "loss" for the locked form too, because repeated
Set() calls on an AutoReset event coalesce into one signal.

Downstream: zero AutoResetEvent/ManualResetEvent sites in both consumers; all
14 hits are EventWaitHandle and need a rebuild, not an edit. cna builds against
the sibling checkout on develop, so both repairs reach it at the merge.

Gate: 17,594 run / 17,594 passed / 0 failed / 0 skipped across 38 executables,
recounted from the per-executable logs (+4, Threading 523 -> 527).
Build: build/ only, --parallel 2 throughout.

Author: robertvokac

CLAUDE.md

@@ -0,0 +1,101 @@
+<!-- SPDX-License-Identifier: MIT -->
+<!-- Copyright (c) Robert Vokac and contributors -->
+
+# Migration: `AutoResetEvent` and `ManualResetEvent` are `WaitHandle`s (#1958 / SR-AUD-209)
+
+**Landed:** 2026-08-19, branch `next`. **Ticket:** #1958, finding SR-AUD-209. **This closes #1958.**
+
+## What changed
+
+Both types had **no base class and no vtable**, and each carried its own mutex, condition
+variable and signalled flag — a third and fourth copy of logic `EventWaitHandle` already had.
+They are now what .NET declares:
+
+```cpp
+class AutoResetEvent   final : public EventWaitHandle { explicit AutoResetEvent(bool); };
+class ManualResetEvent final : public EventWaitHandle { explicit ManualResetEvent(bool); };
+```
+
+That is not a paraphrase of the reference — it *is* the reference. .NET's
+`AutoResetEvent.cs` and `ManualResetEvent.cs` are nine lines each, and their entire bodies are
+
+```csharp
+public sealed class AutoResetEvent : EventWaitHandle
+{
+    public AutoResetEvent(bool initialState) : base(initialState, EventResetMode.AutoReset) { }
+}
+```
+
+Neither declares a member of its own. `Set`, `Reset`, `WaitOne`, `Close` and `Dispose` are all
+inherited.
+
+## Why it mattered
+
+Because they were not `WaitHandle`s, `WaitHandle::WaitAll` and `WaitHandle::WaitAny` **could not
+accept them at all** — not "returned the wrong answer", the code did not compile. Those entry
+points were repaired by #1952 and documented ever since. SR-AUD-209 was the one divergence in
+`System::Threading` that left a documented API unusable.
+
+## Two things the finding did not name, both required
+
+**1. `EventWaitHandle` had no closed state.** #1956 gave `Mutex`, `AutoResetEvent` and
+`ManualResetEvent` a `closed_` flag so that `Close()` really closes; `EventWaitHandle` was its
+fourth case and was missed, so `Close()` there reached `WaitHandle`'s **empty** `Dispose()` and did
+nothing. Deriving the two events without fixing that would have **silently reverted #1956 for both
+of them**. The guard now lives in `EventWaitHandle` and the derived types inherit it, which is
+where .NET puts it too (`WaitHandle.cs:87-98,118`).
+
+**2. `EventWaitHandle::Set()` lost wakeups.** It stored and notified **without holding `mtx_`**,
+so a waiter that had evaluated the predicate as false but had not yet atomically released the lock
+and slept missed the notification and blocked until some later `Set()`. `AutoResetEvent::Set()`
+took the lock, so deriving it would have **introduced** the race into a type that did not have it.
+
+Measured with `build-probe/2209_probe1_lost_wakeup.cpp` over 900 single-waiter rounds:
+`EventWaitHandle` lost **2**, `AutoResetEvent` lost **0**. This is the type six `cna` data members
+hold **by value**, all of them for async completion — precisely the shape a lost wakeup hangs.
+
+## Layout — consumers must rebuild
+
+| type | before | after |
+|---|---|---|
+| `AutoResetEvent` | 96 | **112** |
+| `ManualResetEvent` | 96 | **112** |
+| `EventWaitHandle` | 104 | **112** |
+
+`EventWaitHandle`'s growth was **asserted at 104 first and the build rejected it**: #1956's flags
+fitted into existing padding on three other types and that expectation was carried over rather
+than measured. It does not fit here.
+
+This is a vtable and base-class change (SA-3 excludes it; the user approved it directly on
+2026-08-19) plus an ABI change on a type `cna` holds by value in six places, so **every consumer
+must rebuild**. The layout pin asserts the *relationship* — both events must be exactly
+`sizeof(EventWaitHandle)` — as well as the absolute figures, so it says "these declare no members
+of their own" rather than merely "these are 112 bytes today".
+
+## Source changes
+
+- **`WaitOne()` returns `bool`**, not `void`. Nothing that compiled stops compiling — ignoring a
+  returned value is legal — so this is a widening at every call site.
+- **The `initialState` parameter has no default.** .NET's has none; the default this port
+  published had **zero** call sites across `modules/`, `test/` and both downstream consumers.
+- Both classes are `final`, matching `sealed`.
+
+## Downstream
+
+Measured 2026-08-19: **zero** `AutoResetEvent` and **zero** `ManualResetEvent` sites in `cna` and
+`mobile-eggbert`. All 14 downstream hits are `EventWaitHandle`, six of them data members by value
+(`StorageDevice.cpp`, `NetworkSession.hpp`, `Gamer.hpp`, `Guide.cpp`, `AvatarDescription.cpp`,
+`LeaderboardReader.cpp`). Those need a **rebuild**, not an edit — and they gain both repairs
+above, which is the substantive downstream effect of this ticket.
+
+## Evidence, including what is not testable
+
+Seven mutations. Six caught; **M6 — reverting `Set()` to store without the lock — is not caught,
+and cannot be caught deterministically.** At roughly 0.2% loss per round, a bounded test would
+detect it about a third of the time, and a test that is intermittently green is not evidence
+(#2352). A first cut of the suite carried such a case at 200 rounds and it was **removed rather
+than kept**, on the reasoning #1957/SR-AUD-201 and #2031 recorded for their own window-closing
+mutations. A multi-waiter amplification was tried and is invalid: repeated `Set()` calls on an
+AutoReset event coalesce into one signal, so the harness reported 100% "loss" for the **locked**
+form too — it measures AutoReset semantics, not the race. The reasoning sits in the test file
+where the case would have been.

docs/Migration-ResetEventsDeriveFromWaitHandle.md

@@ -2,107 +2,43 @@
 // Copyright (c) Robert Vokac and contributors
 // Portions based on .NET runtime API (MIT License, Copyright .NET Foundation and Contributors)
 #pragma once
-#include <mutex>
-#include <atomic>
-#include <condition_variable>
 
-#include "SharpRuntime/SharpRuntimeHelper.hpp"
-#include "System/ObjectDisposedException.hpp"
-#include "System/Threading/WaitHandle.hpp"
+#include "System/Threading/EventResetMode.hpp"
+#include "System/Threading/EventWaitHandle.hpp"
 
 namespace System::Threading {
 
-    using SharpRuntime::intcs;
-
     /**
-     * Represents a thread synchronization event that resets automatically after releasing a single waiting thread.
-     * 
-     * Wraps std::condition_variable. Partial C++ counterpart of .NET System.Threading.AutoResetEvent.
-     * 
-     * @note Status: Implemented
+     * @brief Represents a thread synchronization event that resets automatically after
+     *        releasing a single waiting thread.
+     *
+     * C++ counterpart of .NET `System.Threading.AutoResetEvent`, which is
+     * `public sealed class AutoResetEvent : EventWaitHandle` whose entire body is
+     * `public AutoResetEvent(bool initialState) : base(initialState, EventResetMode.AutoReset)`
+     * (`AutoResetEvent.cs:6-9`). It declares **no members of its own**; `Set`, `Reset`,
+     * `WaitOne`, `Close` and `Dispose` are all inherited.
+     *
+     * @note **Derived since ticket #1958 / SR-AUD-209 (2026-08-19).** This class used to have
+     * no base and no vtable, holding its own mutex, condition variable and signalled flag --
+     * a third copy of logic `EventWaitHandle` already had. Because it was not a `WaitHandle`,
+     * `WaitHandle::WaitAll`/`WaitAny` **could not accept it at all**, which is what made
+     * SR-AUD-209 the one finding in the namespace that left a documented API unusable.
+     *
+     * `WaitOne()` consequently returns `bool` rather than `void`. Nothing that compiled stops
+     * compiling -- ignoring a returned value is legal -- so the change is a widening at every
+     * call site, but `sizeof` grows and a vtable appears, so consumers must rebuild.
      */
-    class AutoResetEvent {
-        std::mutex              mutex_;
-        std::condition_variable cv_;
-        bool                    signaled_;
-        // Ticket #1956 / cause T-G (SR-AUD-208). Close() was an EMPTY BODY, so a closed handle
-        // stayed fully usable: measured, Close() followed by WaitOne(0) returned success. .NET's
-        // WaitHandle.Close() is `=> Dispose()`, Dispose(bool) is `_waitHandle?.Close()`, and every
-        // wait path then opens with `ObjectDisposedException.ThrowIf(waitHandle is null, this)`
-        // (WaitHandle.cs:87-98, 118). The header here already CLAIMED Close "closes the handle",
-        // so the documentation and the behaviour disagreed.
-        //
-        // std::atomic<bool> is 1 byte and 1-byte aligned, and it lands in padding these types
-        // already had -- the sizes are unchanged, pinned by a layout test. Landed under SA-5 (a
-        // call that succeeds today starts throwing) with SA-3's layout condition discharged.
-        std::atomic<bool> closed_{false};
-
-        void ThrowIfClosed() const {
-            if (closed_.load(std::memory_order_acquire))
-                throw System::ObjectDisposedException("The handle has been closed.");
-        }
+    class AutoResetEvent final : public EventWaitHandle {
     public:
-        /** @param initialState If true, the event starts in the signaled state. */
-        explicit AutoResetEvent(bool initialState = false) : signaled_(initialState) {}
-
-        /** Sets the event to signaled, releasing one waiting thread; the event then resets automatically. */
-        void Set() {
-            ThrowIfClosed();
-            { std::lock_guard<std::mutex> lk(mutex_); signaled_ = true; }
-            cv_.notify_one();
-        }
-
-        /** Resets the event to non-signaled. */
-        void Reset() {
-            ThrowIfClosed();
-            std::lock_guard<std::mutex> lk(mutex_);
-            signaled_ = false;
-        }
-
-        /** Blocks until the event is signaled (then auto-resets). */
-        void WaitOne() {
-            ThrowIfClosed();
-            std::unique_lock<std::mutex> lk(mutex_);
-            cv_.wait(lk, [this]{ return signaled_; });
-            signaled_ = false;
-        }
-
-        /**
-         * Blocks until signaled or timeout elapses.
-         * @param milliseconds Maximum time to wait.
-         * @return True if the event was signaled (then auto-resets); false on timeout.
-         * @throws System::ArgumentOutOfRangeException if @p milliseconds is less than -1.
-         * @note Verified against every sibling wait-handle type in this codebase
-         * (ManualResetEvent, EventWaitHandle, Mutex, Semaphore, SemaphoreSlim, CountdownEvent,
-         * ManualResetEventSlim), all of which call WaitHandle::ValidateTimeout(...) here. This
-         * was previously the one call site missing it: a timeout below -1 (e.g. -2) silently
-         * reached cv_.wait_for(..., milliseconds(-2), ...), which per C++'s negative-duration
-         * semantics returns almost immediately instead of throwing.
-         */
-        bool WaitOne(intcs milliseconds) {
-            ThrowIfClosed();
-            WaitHandle::ValidateTimeout(milliseconds);
-            std::unique_lock<std::mutex> lk(mutex_);
-            // -1 (Timeout.Infinite) waits indefinitely; std::chrono's wait_for treats a
-            // negative duration as already-expired, so it must be special-cased.
-            bool ok;
-            if (milliseconds == -1) {
-                cv_.wait(lk, [this]{ return signaled_; });
-                ok = true;
-            } else {
-                ok = cv_.wait_for(lk, std::chrono::milliseconds(milliseconds), [this]{ return signaled_; });
-            }
-            if (ok) signaled_ = false;
-            return ok;
-        }
-
         /**
-         * @brief Closes the handle. Every later Set, Reset or WaitOne throws
-         *        System::ObjectDisposedException.
+         * @param initialState If true, the event starts in the signaled state.
          *
-         * Idempotent, as .NET's is: Close() is `=> Dispose()` and disposing twice is defined.
+         * The parameter has no default, as .NET's has none. The default this port used to
+         * publish had **zero** call sites, measured across `modules/`, `test/` and both
+         * downstream consumers, so removing it migrates nothing.
          */
-        void Close() { closed_.store(true, std::memory_order_release); }
+        explicit AutoResetEvent(bool initialState)
+            : EventWaitHandle(initialState, EventResetMode::AutoReset) {}
     };
 
 } // namespace System::Threading

modules/threading/include/System/Threading/AutoResetEvent.hpp

@@ -7,6 +7,7 @@
 #include <mutex>
 #include "SharpRuntime/SharpRuntimeHelper.hpp"
 #include "System/Threading/WaitHandle.hpp"
+#include "System/ObjectDisposedException.hpp"
 #include "System/Threading/EventResetMode.hpp"
 
 namespace System::Threading {
@@ -20,6 +21,18 @@ namespace System::Threading {
         std::mutex mtx_;
         std::condition_variable cv_;
 
+        // Ticket #1958 / SR-AUD-209. #1956 gave AutoResetEvent, ManualResetEvent and Mutex a
+        // closed state; EventWaitHandle was its fourth case and was missed, so Close() here
+        // reached WaitHandle's EMPTY Dispose() and a closed handle stayed fully usable. That gap
+        // had to be closed before AutoResetEvent and ManualResetEvent could derive from this
+        // class, or deriving would have silently reverted #1956 for both of them.
+        std::atomic<bool> closed_{false};
+
+        void ThrowIfClosed() const {
+            if (closed_.load(std::memory_order_acquire))
+                throw System::ObjectDisposedException("The handle has been closed.");
+        }
+
     public:
         /**
          * @brief Constructs an EventWaitHandle with the specified initial state and reset mode.
@@ -56,20 +69,50 @@ namespace System::Threading {
                 throw System::ArgumentException("Value of flags is invalid.", "mode");
         }
 
-        /** Sets the event to the signalled state. */
+        /**
+         * @brief Sets the event to the signalled state.
+         * @throws System::ObjectDisposedException if the handle has been closed.
+         *
+         * The store and the notification happen under `mtx_`. Ticket #1958 / SR-AUD-209
+         * measured that doing them WITHOUT the lock loses wakeups: a waiter that has evaluated
+         * the predicate as false but has not yet atomically released the lock and slept misses
+         * the notification entirely and blocks until some later Set(). Probed over 900 rounds,
+         * the unlocked form lost 2 and the locked form lost 0 -- and this is the type six `cna`
+         * data members hold by value, all of them for async completion, which is exactly the
+         * shape a lost wakeup hangs.
+         */
         void Set() {
-            set_.store(true, std::memory_order_release);
+            ThrowIfClosed();
+            { std::lock_guard<std::mutex> lk(mtx_); set_.store(true, std::memory_order_release); }
             if (mode_ == EventResetMode::ManualReset)
                 cv_.notify_all();
             else
                 cv_.notify_one();
         }
 
-        /** Sets the event to the non-signalled state. */
-        void Reset() { set_.store(false, std::memory_order_release); }
+        /**
+         * @brief Sets the event to the non-signalled state.
+         * @throws System::ObjectDisposedException if the handle has been closed.
+         */
+        void Reset() {
+            ThrowIfClosed();
+            std::lock_guard<std::mutex> lk(mtx_);
+            set_.store(false, std::memory_order_release);
+        }
+
+        /**
+         * @brief Closes the handle; every later Set, Reset or WaitOne throws
+         *        System::ObjectDisposedException.
+         *
+         * .NET's `WaitHandle.Close()` is `=> Dispose()` and this port's base spells it the same
+         * way, so overriding Dispose() is what makes Close() effective here. Idempotent, as
+         * .NET's is.
+         */
+        void Dispose() override { closed_.store(true, std::memory_order_release); }
 
         /** Blocks until the event is signalled; auto-resets if the mode is AutoReset. */
         bool WaitOne() override {
+            ThrowIfClosed();
             std::unique_lock<std::mutex> lock(mtx_);
             cv_.wait(lock, [this]{ return set_.load(std::memory_order_acquire); });
             if (mode_ == EventResetMode::AutoReset)
@@ -82,6 +125,7 @@ namespace System::Threading {
          * @throws System::ArgumentOutOfRangeException if @p milliseconds is less than -1.
          */
         bool WaitOne(intcs milliseconds) override {
+            ThrowIfClosed();
             ValidateTimeout(milliseconds);
             std::unique_lock<std::mutex> lock(mtx_);
             // -1 (Timeout.Infinite) waits indefinitely; std::chrono's wait_for treats a