refactor: isolate scheduler state and condense code comments (#211)

* chore: Update benchmarks and fix tests

* refactor(tests): drive scheduling tests from state, not the clock

- Replace delays, polling and thread rendezvous with awaited completion
  sources, virtual clocks and ordered calls into internal seams.
- Add seams for stepwise dispatch: WasmScheduler.QueueReady and
  RunReadyBatch, so enqueue, dispose and drain are explicit steps.
- Assert per-item dispatch counts where a total was checked before.
- Trim documentation to the contract: concise summaries, inline notes at
  the confusing line, and remarks only for non-obvious behaviour.
- Correct exception docs to the type thrown rather than the guard helper.

* chore: more churn

* further work

* docs: state what non-public members do, not why

- Reduce internal operator and helper summaries to a single line of behaviour.
- Drop allocation and deadlock rationale from field and method summaries.
- Keep remarks for public contracts a caller cannot infer from the signature.

* Further

* further

* fix(concurrency): convert durations and timestamps with integer math

- Scale between ticks and monotonic timestamps without a double round trip, so
  a duration representable on both grids survives unchanged.
- A 50-tick delay converted at a 10 MHz timestamp frequency no longer lands a
  tick late, which left scheduled work undue at its own due time.

* docs(extensions): name what each parameter carries

- Replace placeholder parameter text with the role the argument plays.
- Say which window a sequencer times, and which side an observer receives.

* Add further tests

* Fix build issue

Author: glennawatson

CLAUDE.md

@@ -134,12 +134,11 @@ dotnet test "tests/ReactiveUI.Primitives.Async.Tests/ReactiveUI.Primitives.Async
   --treenode-filter "/*/*/*/Async"
 ```
 
-### API Approval Notes
+### Public API Checks
 
-- API approval baselines live under `src/tests/**/ApiApprovalTests.*.verified.txt`
-- New TFMs usually require corresponding new `DotNet11_0.verified.txt` files
-- If approval tests fail with `.received.txt` output, inspect the generated snapshot and promote it intentionally if the
-  API change is expected
+- `PublicApiSharp.Analyzers` checks each package's `src//PublicAPI//PublicAPI.txt` baseline.
+- New target frameworks require a corresponding baseline directory.
+- For an intentional API change, review the affected signatures and update the corresponding framework baselines.
 
 ---
 

src/Directory.Packages.props

@@ -33,7 +33,6 @@
   ItemGroup>
   <ItemGroup>
     <PackageVersion Include="Avalonia" Version="$(AvaloniaVersion)"/>
-    <PackageVersion Include="Avalonia.Headless" Version="$(AvaloniaVersion)"/>
     <PackageVersion Include="Microsoft.AspNetCore.Components" Version="8.0.31" Condition="$([MSBuild]::IsTargetFrameworkCompatible('$(TargetFramework)', 'net8.0')) AND !$([MSBuild]::IsTargetFrameworkCompatible('$(TargetFramework)', 'net9.0'))"/>
     <PackageVersion Include="Microsoft.AspNetCore.Components" Version="9.0.20" Condition="$([MSBuild]::IsTargetFrameworkCompatible('$(TargetFramework)', 'net9.0')) AND !$([MSBuild]::IsTargetFrameworkCompatible('$(TargetFramework)', 'net10.0'))"/>
     <PackageVersion Include="Microsoft.AspNetCore.Components" Version="10.0.12" Condition="$([MSBuild]::IsTargetFrameworkCompatible('$(TargetFramework)', 'net10.0')) AND !$([MSBuild]::IsTargetFrameworkCompatible('$(TargetFramework)', 'net11.0'))"/>

src/Polyfills/ArgumentExceptionHelper.cs

@@ -7,11 +7,7 @@
 
 namespace ReactiveUI.Primitives.Internal;
 
-/// 
-/// Polyfill for ArgumentNullException.ThrowIfNull on target frameworks (net462-net481) that predate it.
-/// On net8.0 and later this type is not compiled; consuming projects alias the ArgumentExceptionHelper
-/// identifier directly to  so the call sites bind to the BCL method.
-/// 
+/// Polyfill for ArgumentNullException.ThrowIfNull on target frameworks that predate it.
 [ExcludeFromCodeCoverage]
 internal static class ArgumentExceptionHelper
 {

src/Polyfills/ArgumentOutOfRangeExceptionHelper.cs

@@ -70,9 +70,7 @@ internal static void ThrowIfLessThan(
         "Design",
         "SST2318:Members should not have identical bodies",
         Justification =
-            "A type-specialized polyfill overload. The bounds-check body is identical to the int overload only "
-            + "because the guard shape is the same; the two operate on different value types (int vs TimeSpan) and "
-            + "cannot forward to one another. This mirrors the BCL's per-type ThrowIfLessThan overloads.")]
+            "The int and TimeSpan overloads guard different value types and cannot forward to one another.")]
     internal static void ThrowIfLessThan(
         TimeSpan value,
         TimeSpan other,

src/Polyfills/ObjectDisposedExceptionHelper.cs

@@ -6,11 +6,7 @@
 
 namespace ReactiveUI.Primitives.Internal;
 
-/// 
-/// Polyfill for ObjectDisposedException.ThrowIf on target frameworks (net462-net481) that predate it.
-/// On net8.0 and later this type is not compiled; consuming projects alias the ObjectDisposedExceptionHelper
-/// identifier directly to  so the call sites bind to the BCL method.
-/// 
+/// Polyfill for ObjectDisposedException.ThrowIf on target frameworks that predate it.
 [ExcludeFromCodeCoverage]
 internal static class ObjectDisposedExceptionHelper
 {

src/Polyfills/TaskCompletionSource.cs

@@ -19,7 +19,7 @@ internal sealed class TaskCompletionSource
 
     /// Initializes a new instance of the  class.
     [SuppressMessage("Concurrency", "PSH1302", Justification =
-        "BCL-parity polyfill; must match the framework ctor's TaskCreationOptions.None default, not force async continuations.")]
+        "Matches the framework constructor's TaskCreationOptions.None default.")]
     public TaskCompletionSource() => _inner = new();
 
     /// Transitions the underlying task to the  state.
@@ -47,9 +47,7 @@ internal sealed class TaskCompletionSource
         "Design",
         "SST2318:Members should not have identical bodies",
         Justification =
-            "Distinct BCL-parity surface members with different contracts and return types: SetCanceled is void and "
-            + "TrySetCanceled returns bool. They share the same backing call here but must track the framework surface "
-            + "independently, so they are deliberately kept as separate members rather than one forwarding to the other.")]
+            "SetCanceled returns void and TrySetCanceled returns bool; each tracks its own framework contract.")]
     internal bool TrySetCanceled() => _inner.TrySetCanceled();
 
     /// Attempts to transition the underlying task to the  state for the specified token.

src/Polyfills/TaskPolyfillExtensions.cs

@@ -58,7 +58,7 @@ private static async Task WaitForCompletionAsync(Task task, TimeSpan timeout, Ca
         using var linked = CancellationTokenSource.CreateLinkedTokenSource(cancellationToken);
         if (timeout != Timeout.InfiniteTimeSpan)
         {
-            linked.CancelAfter(timeout);
+            ScheduleTimeout(linked, timeout);
         }
 
         using (linked.Token.Register(static state => ((TaskCompletionSource<bool>)state).TrySetResult(true), signal))
@@ -71,5 +71,12 @@ private static async Task WaitForCompletionAsync(Task task, TimeSpan timeout, Ca
             }
         }
     }
+
+    /// Schedules cancellation when the timeout elapses.
+    /// The cancellation source.
+    /// The timeout duration.
+    [System.Diagnostics.CodeAnalysis.ExcludeFromCodeCoverage]
+    [System.Runtime.CompilerServices.MethodImpl(System.Runtime.CompilerServices.MethodImplOptions.AggressiveInlining)]
+    private static void ScheduleTimeout(CancellationTokenSource source, TimeSpan timeout) => source.CancelAfter(timeout);
 }
 #endif

src/Primitives.Async.Shared/Advanced/StartSubscription.cs

@@ -46,7 +46,21 @@ protected override async ValueTask ExecuteAsyncCore(
             return;
         }
 
-        await Task.Factory.StartNew(
+        await ExecuteOnSchedulerAsync(observer, taskScheduler, cancellationToken).ConfigureAwait(false);
+    }
+
+    /// Starts the action through the supplied scheduler.
+    /// The observer receiving the signal notification.
+    /// The scheduler that starts the action.
+    /// Cancellation for the scheduled task and notifications.
+    /// The scheduled action and notification operation.
+    [System.Diagnostics.CodeAnalysis.ExcludeFromCodeCoverage]
+    [System.Runtime.CompilerServices.MethodImpl(System.Runtime.CompilerServices.MethodImplOptions.AggressiveInlining)]
+    private Task ExecuteOnSchedulerAsync(
+        IObserverAsync<RxVoid> observer,
+        TaskScheduler taskScheduler,
+        CancellationToken cancellationToken) =>
+        Task.Factory.StartNew(
                 static s =>
                 {
                     var (self, observer, cancellationToken) =
@@ -57,9 +71,7 @@ await Task.Factory.StartNew(
                 cancellationToken,
                 TaskCreationOptions.DenyChildAttach,
                 taskScheduler)
-            .Unwrap()
-            .ConfigureAwait(false);
-    }
+            .Unwrap();
 
     /// Runs the action and forwards the completion signal.
     /// The observer receiving the signal notification.