docs(worker): record the SemaphoreSlim/STA dispatch invariant + single-waiter contract; harden fake

2026-08-15 17:13:17 -04:00
parent 25cbe5cd3e
commit 896d81e286
4 changed files with 47 additions and 4 deletions
@@ -68,6 +68,11 @@ public interface IWorkerRuntimeSession : IDisposable
    ///     no default interface members, so every implementation supplies it. The wait's outcome is
    ///     not surfaced: the caller re-drains and re-checks <see cref="DrainFault"/> after every
    ///     wait, because the signal is coalesced and the timeout is a ceiling, not a poll period.
+    ///     <para>
+    ///         Precondition: <b>at most one waiter</b>. The implementation's wake signal carries a
+    ///         single permit, which is sufficient only because a session has exactly one event
+    ///         drain loop; a second concurrent waiter would degrade to the fallback timeout.
+    ///     </para>
    /// </remarks>
    /// <param name="timeout">Maximum time to wait before the wait completes unsignalled.</param>
    /// <param name="cancellationToken">Token cancelling the wait.</param>