fix(routing): deliver scheduled notifications in order so Navigate returns its view model (#4484)

## Summary

**Awaiting `RoutingState.Navigate.Execute` returns the navigated view
model on any main-thread scheduler.**

- **Scheduled notifications arrive in order.** The internal observer
that delivers results on a scheduler queues `OnNext`, `OnError` and
`OnCompleted` and delivers them from a single scheduled drain, so a
concurrent scheduler cannot run completion before the value.
- **The same ordering applies to `ReactiveProperty` and
`ScheduledSubject`,** which use the same observer.

## Why

**With a concurrent main-thread scheduler, an awaited navigation could
fail after it had succeeded.**

- When no platform is registered, `RxSchedulers.MainThreadScheduler` is
the task pool. Each notification was scheduled as its own work item, so
`OnCompleted` could run first and the awaiter threw "The source
completed without producing a value", although the view model was
already on the navigation stack.

Closes #4480

## Breaking changes

**None.**

- `Sequencer.Immediate` still delivers inline. Other schedulers deliver
a burst of notifications from one scheduled work item instead of one
work item each.

## How this was verified

**A test uses a scheduler that runs queued work newest first and checks
that `Navigate` delivers the view model before it completes; a console
app that awaits `Navigate.Execute` 1000 times on the task-pool scheduler
no longer fails.**

## Notes for the reviewer

**The fix is `SchedulingObserver`; the test is in
`RoutingStateTests`.**

- The queue is guarded by a lock, and a flag makes sure only one drain
is scheduled at a time; the drain clears the flag when the queue is
empty.
- `ReactiveCommand` was not affected: `Execute()` hands its result to
the caller on the execution thread.

## Checklist
- [x] I have read the [Contribute
guide](https://www.reactiveui.net/contribute/index.html)
- [x] The PR title follows [Conventional
Commits](https://www.conventionalcommits.org/)
- [x] Tests cover this change, or the summary says why they do not
- [x] New or changed public API has XML documentation

Author: glennawatson

src/ReactiveUI.Shared/Internal/Subjects/SchedulingObserver.cs

@@ -11,42 +11,133 @@ namespace ReactiveUI.Reactive.Internal;
 #else
 namespace ReactiveUI.Internal;
 #endif
-/// Forwards each notification to a downstream observer on a scheduler, replacing a per-observer ObserveOn.
+/// 
+/// Forwards each notification to a downstream observer on a scheduler, replacing a per-observer ObserveOn.
+/// Notifications are queued and delivered in arrival order by a single scheduled drain, so a concurrent scheduler
+/// (such as the task pool) cannot run a later notification (for example OnCompleted) before an earlier one.
+/// 
 /// The element type.
 /// The observer that receives the scheduled notifications.
 /// The scheduler each notification is delivered on.
 internal sealed class SchedulingObserver<T>(IObserver<T> downstream, ISequencer scheduler) : IObserver<T>
 {
+    /// Guards  and .
+#if NET9_0_OR_GREATER
+    private readonly Lock _gate = new();
+#else
+    private readonly object _gate = new();
+#endif
+
+    /// Notifications waiting for the drain, in arrival order.
+    private readonly Queue<Notification> _queue = new();
+
+    /// Whether a drain is scheduled or running.
+    private bool _draining;
+
+    /// The kind of a queued notification.
+    private enum NotificationKind
+    {
+        /// An OnNext value.
+        Next = 0,
+
+        /// An OnError failure.
+        Error = 1,
+
+        /// An OnCompleted signal.
+        Completed = 2,
+    }
+
     /// 
     [MethodImpl(MethodImplOptions.AggressiveInlining)]
-    public void OnNext(T value) =>
-        scheduler.ScheduleOrInline(
-            (Observer: downstream, Value: value),
-            static (_, state) =>
-            {
-                state.Observer.OnNext(state.Value);
-                return EmptyDisposable.Instance;
-            });
+    public void OnNext(T value) => Enqueue(new(NotificationKind.Next, value, null));
 
     /// 
     [MethodImpl(MethodImplOptions.AggressiveInlining)]
-    public void OnError(Exception error) =>
-        scheduler.ScheduleOrInline(
-            (Observer: downstream, Error: error),
-            static (_, state) =>
-            {
-                state.Observer.OnError(state.Error);
-                return EmptyDisposable.Instance;
-            });
+    public void OnError(Exception error) => Enqueue(new(NotificationKind.Error, default!, error));
 
     /// 
     [MethodImpl(MethodImplOptions.AggressiveInlining)]
-    public void OnCompleted() =>
-        scheduler.ScheduleOrInline(
-            downstream,
-            static (_, observer) =>
+    public void OnCompleted() => Enqueue(new(NotificationKind.Completed, default!, null));
+
+    /// Queues a notification and schedules a drain when none is pending.
+    /// The notification to deliver.
+    private void Enqueue(in Notification notification)
+    {
+        // The immediate scheduler runs work inline on the calling thread, so arrival order is already kept.
+        if (ReferenceEquals(scheduler, Sequencer.Immediate))
+        {
+            Deliver(notification);
+            return;
+        }
+
+        lock (_gate)
+        {
+            _queue.Enqueue(notification);
+            if (_draining)
+            {
+                return;
+            }
+
+            _draining = true;
+        }
+
+        _ = scheduler.Schedule(this, static (_, self) =>
+        {
+            self.Drain();
+            return EmptyDisposable.Instance;
+        });
+    }
+
+    /// Delivers queued notifications in order until the queue is empty.
+    private void Drain()
+    {
+        while (true)
+        {
+            Notification notification;
+            lock (_gate)
             {
-                observer.OnCompleted();
-                return EmptyDisposable.Instance;
-            });
+                if (_queue.Count == 0)
+                {
+                    _draining = false;
+                    return;
+                }
+
+                notification = _queue.Dequeue();
+            }
+
+            Deliver(notification);
+        }
+    }
+
+    /// Forwards one notification to the downstream observer.
+    /// The notification to forward.
+    private void Deliver(in Notification notification)
+    {
+        switch (notification.Kind)
+        {
+            case NotificationKind.Next:
+                {
+                    downstream.OnNext(notification.Value);
+                    break;
+                }
+
+            case NotificationKind.Error:
+                {
+                    downstream.OnError(notification.Error!);
+                    break;
+                }
+
+            default:
+                {
+                    downstream.OnCompleted();
+                    break;
+                }
+        }
+    }
+
+    /// A queued notification.
+    /// The notification kind.
+    /// The value, for .
+    /// The failure, for .
+    private readonly record struct Notification(NotificationKind Kind, T Value, Exception? Error);
 }

src/tests/ReactiveUI.Tests/Routing/RoutingStateTests.cs

@@ -0,0 +1,121 @@
+// Copyright (c) 2009-2026 .NET Foundation and Contributors. All rights reserved.
+// Licensed to the .NET Foundation under one or more agreements.
+// The .NET Foundation licenses this file to you under the MIT license.
+// See the LICENSE file in the project root for full license information.
+
+#if REACTIVE_SHIM
+using System.Reactive.Concurrency;
+#else
+using ReactiveUI.Primitives.Concurrency;
+#endif
+
+namespace ReactiveUI.Tests.Routing;
+
+/// Tests for .
+public class RoutingStateTests
+{
+    /// 
+    /// Navigate delivers the navigated view model before it completes, even when the navigation scheduler runs
+    /// queued work out of order (as a concurrent scheduler such as the task pool can).
+    /// 
+    /// A  representing the asynchronous operation.
+    [Test]
+    public async Task NavigateDeliversViewModelBeforeCompletionOnReorderingScheduler()
+    {
+        var scheduler = new ReorderingScheduler();
+        var router = new RoutingState(scheduler);
+        var viewModel = new TestViewModel();
+        var notifications = new List<string>();
+
+        using var subscription = router.Navigate.Execute(viewModel).Subscribe(
+            vm => notifications.Add(ReferenceEquals(vm, viewModel) ? "next" : "next-other"),
+            () => notifications.Add("completed"));
+        scheduler.RunNewestFirst();
+
+        await Assert.That(notifications).IsEquivalentTo(["next", "completed"], TUnit.Assertions.Enums.CollectionOrdering.Matching);
+    }
+
+    /// A routable view model used as the navigation target.
+    private sealed class TestViewModel : ReactiveObject, IRoutableViewModel
+    {
+        /// 
+        public string? UrlPathSegment => "test";
+
+        /// 
+        public IScreen HostScreen => null!;
+    }
+
+#if REACTIVE_SHIM
+    /// 
+    /// A scheduler that holds work until , then runs it newest first. It stands in for a
+    /// concurrent scheduler, which gives no ordering guarantee between separately scheduled work items.
+    /// 
+    private sealed class ReorderingScheduler : IScheduler
+    {
+        /// The pending work, newest last.
+        private readonly List<Action> _pending = [];
+
+        /// 
+        public DateTimeOffset Now => default;
+
+        /// 
+        public IDisposable Schedule<TState>(TState state, Func<IScheduler, TState, IDisposable> action)
+        {
+            _pending.Add(() => action(this, state));
+            return EmptyDisposable.Instance;
+        }
+
+        /// 
+        public IDisposable Schedule<TState>(TState state, TimeSpan dueTime, Func<IScheduler, TState, IDisposable> action) =>
+            Schedule(state, action);
+
+        /// 
+        public IDisposable Schedule<TState>(TState state, DateTimeOffset dueTime, Func<IScheduler, TState, IDisposable> action) =>
+            Schedule(state, action);
+
+        /// Runs pending work, newest first, until none remains.
+        public void RunNewestFirst()
+        {
+            while (_pending.Count > 0)
+            {
+                var work = _pending[^1];
+                _pending.RemoveAt(_pending.Count - 1);
+                work();
+            }
+        }
+    }
+#else
+    /// 
+    /// A scheduler that holds work until , then runs it newest first. It stands in for a
+    /// concurrent scheduler, which gives no ordering guarantee between separately scheduled work items.
+    /// 
+    private sealed class ReorderingScheduler : ISequencer
+    {
+        /// The pending work, newest last.
+        private readonly List<IWorkItem> _pending = [];
+
+        /// 
+        public DateTimeOffset Now => default;
+
+        /// 
+        public long Timestamp => 0;
+
+        /// 
+        public void Schedule(IWorkItem item) => _pending.Add(item);
+
+        /// 
+        public void Schedule(IWorkItem item, long dueTimestamp) => _pending.Add(item);
+
+        /// Runs pending work, newest first, until none remains.
+        public void RunNewestFirst()
+        {
+            while (_pending.Count > 0)
+            {
+                var work = _pending[^1];
+                _pending.RemoveAt(_pending.Count - 1);
+                work.Execute();
+            }
+        }
+    }
+#endif
+}